unitbob 0.2.6 → 0.2.8

package/dist/cli.js

@@ -3,15 +3,20 @@
 // 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.
+//
+// One verb is more than a dispatch: `put-suite-build` composes two hands-verbs
+// into a single user operation, so `publishAndRun` at the bottom of this file
+// holds that sequence and the exit code it implies (spec 32-4). Every other verb
+// keeps its whole flow in its own module under `verbs/`.
 import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
-import { run } from "./verbs/run.js";
+import { run, runOnly } from "./verbs/run.js";
 import { init } from "./verbs/init.js";
 import { mapPrepare } from "./verbs/mapPrepare.js";
 import { putMapBuild } from "./verbs/putMapBuild.js";
 import { suitePrepare } from "./verbs/suitePrepare.js";
-import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
+import { classifyPublication, putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
@@ -27,7 +32,8 @@ Verbs:
   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).
+  put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
+                       then run every branch it published and report the server's results.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
   contract-prompt <digest> <test_id> [fix|accept]
                        Internal: fetch the fix/accept brief for one red check on either map.
@@ -37,7 +43,8 @@ Verbs:
 Pipeline: map and suite are built on your machine. \`*-prepare\` writes a request
 packet (with the recipe and paths); you build the artifact at the packet's
 output_path from your local source; \`put-*\` uploads only the structured result.
-\`check\` runs the guardrails locally and reports results to the server.
+\`put-suite-build\` then runs what it published, so a suite never sits with nothing
+to show. \`check\` re-runs the guardrails locally and reports results to the server.
 Graph extraction is keyless: the connector needs no LLM API key. Inference is the
 host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify skill).
 
@@ -73,8 +80,7 @@ export async function main(argv, deps = { ensureLinked }) {
                 await suiteReviewPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-suite-build':
-                await putSuiteBuild(await deps.ensureLinked(), args);
-                return 0;
+                return await publishAndRun(await deps.ensureLinked(), args);
             case 'fix-prepare':
                 await fixPrepare(await deps.ensureLinked(), args);
                 return 0;
@@ -95,3 +101,48 @@ export async function main(argv, deps = { ensureLinked }) {
         return 1;
     }
 }
+// Publishing a suite and running it the first time are one user operation
+// (spec 32-4). They used to be two commands, and the second one was a step the
+// host LLM could simply not take: the suite was stored, nothing had ever run it,
+// and the user was told about results that did not exist. Now the connector owns
+// the sequence, so no instruction-following can drop half of it.
+//
+// This is a composition, not a transaction. The two server requests stay separate:
+// if the run cannot finish, the published suite and any earlier results for the
+// same identity survive untouched, and a standalone `unitbob check` completes the
+// loop. The two outputs also keep separate authorities — which branch published
+// comes from the build response, and what the results are comes only from the
+// server's answer to the run.
+export async function publishAndRun(config, args, deps) {
+    const d = {
+        putSuiteBuild: (cfg, a) => putSuiteBuild(cfg, a),
+        runOnly: (cfg, digests) => runOnly(cfg, digests),
+        stdout: process.stdout,
+        stderr: process.stderr,
+        ...deps,
+    };
+    const { digests, unpublished } = classifyPublication(await d.putSuiteBuild(config, args));
+    // Nothing is current, so there is nothing honest to run. A branch that failed
+    // to publish must never fall back to the suite it was meant to replace.
+    if (digests.length === 0) {
+        d.stderr.write('No suite was published, so nothing was run. Fix the problems reported above and generate the Unitbob guardrails again.\n');
+        return 1;
+    }
+    // Said between the two halves, because it is a fact about publication and the
+    // run summaries have not been printed yet. Reading a peer's results onto a
+    // branch that was never published is the exact mistake this whole spec exists
+    // to stop, so the output names the gap instead of leaving it to be inferred.
+    if (unpublished.length > 0) {
+        d.stdout.write(`Partial success. No run summary below covers: ${unpublished.join(', ')}.\n`);
+    }
+    try {
+        await d.runOnly(config, digests);
+    }
+    catch (err) {
+        // The upload never happened, so no results were stored — partially or
+        // otherwise. Everything published above is still valid and still current.
+        d.stderr.write(`${err.message}\nThe suite is published. Run the Unitbob checks to finish.\n`);
+        return 1;
+    }
+    return 0;
+}

package/dist/files/behavioral.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, 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
@@ -34,6 +34,39 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     }
     return { mainPath };
 }
+// Everything under the behavioral root that the next materialization will
+// delete: it wipes every top-level entry outside the runner environment and
+// writes back only the files the answer listed, so a step file the answer forgot
+// is gone and its steps come back undefined — a harness break reported far from
+// its cause. One file per capability makes forgetting one much easier than a
+// single file for the whole product ever did.
+//
+// The whole root is walked, not just the directories the answer happens to use:
+// the file most likely to be forgotten is the one in a directory the answer
+// never mentions — `features/support/env.rb` is exactly that shape.
+export function filesLostOnMaterialize(projectRoot, artifact, runner) {
+    const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
+    if (!existsSync(behavioralRoot))
+        return [];
+    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    return readdirSync(behavioralRoot)
+        .filter((entry) => !runnerEntries.has(entry))
+        .flatMap((entry) => filesUnder(projectRoot, `${BEHAVIORAL_DIR}/${entry}`))
+        .filter((path) => !listed.has(path))
+        .sort();
+}
+// The real files under `relative`. Symlinks are not followed: materialization
+// removes the link, not what it points at, and naming the target here would read
+// as a warning about a file that was never in danger.
+function filesUnder(projectRoot, relative) {
+    const stats = lstatSync(join(projectRoot, relative));
+    if (stats.isFile())
+        return [relative];
+    if (!stats.isDirectory())
+        return [];
+    return readdirSync(join(projectRoot, relative)).flatMap((entry) => filesUnder(projectRoot, `${relative}/${entry}`));
+}
 export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner) {
     const entries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     for (const entry of entries) {

package/dist/files/suiteBuild.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
@@ -14,25 +14,40 @@ export function reviewOutputPath(projectRoot) {
 export function reviewRequestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'review-request.json');
 }
+export function candidateRunPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'candidate-run.json');
+}
 export function writeBehavioralReviewRequest(projectRoot, output, candidateRun, knownDefectContext = { status: 'not_supplied' }, fixedCandidateRun) {
     const metadata = output.test_metadata;
     const candidateDigest = suiteCandidateDigest(output);
+    const evidence = {
+        candidate_digest: candidateDigest,
+        known_defect_context: knownDefectContext,
+        candidate_run: { candidate_digest: candidateDigest, ...candidateRun },
+        ...(fixedCandidateRun ? {
+            fixed_candidate_run: { candidate_digest: candidateDigest, ...fixedCandidateRun },
+        } : {}),
+    };
+    writeArtifact(candidateRunPath(projectRoot), evidence);
     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 },
+        // Only a supplied defect gives the reviewer something to read a run for.
+        ...(knownDefectContext.status === 'supplied' ? {
+            candidate_run: evidence.candidate_run,
+            ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
         } : {}),
     };
-    const path = reviewRequestPath(projectRoot);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    writeArtifact(reviewRequestPath(projectRoot), request);
     return request;
 }
+function writeArtifact(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
 // 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.
@@ -77,36 +92,79 @@ export function readBehavioralReview(projectRoot, output) {
     }
     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.`);
+        throw new Error(`${path} ${staleReviewReason(projectRoot, review, output)}`);
     }
     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);
+    const evidence = readCandidateRunEvidence(projectRoot, output);
     return {
         ...review,
-        candidate_run: request.candidate_run,
-        ...(request.fixed_candidate_run ? { fixed_candidate_run: request.fixed_candidate_run } : {}),
+        candidate_run: evidence.candidate_run,
+        ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
     };
 }
-function readBehavioralReviewRequest(projectRoot, output) {
-    const path = reviewRequestPath(projectRoot);
-    const request = parseJson(readFileSync(path, 'utf8'), path);
-    const run = request?.candidate_run;
+// Why a review does not bind — two different mistakes with one symptom.
+//
+// The likelier one, now that a branch may answer with a bare `{ path }`: the
+// review was right when it was written, and the candidate changed afterwards.
+// Editing one step file is enough, and nothing in the answer has to change for
+// it — so the digest moves with no visible cause, and "this does not review the
+// current candidate" sends the reader off to audit the reviewer instead of their
+// own last edit.
+//
+// The connector's own evidence file settles which mistake it was: it carries the
+// digest of the candidate that was actually run at review time. Agreeing with
+// the review and disagreeing with what is on disk now means the candidate moved
+// after the review. Otherwise the review really is about a different candidate.
+function staleReviewReason(projectRoot, review, output) {
+    const evidencePath = candidateRunPath(projectRoot);
+    if (review && existsSync(evidencePath)) {
+        const evidence = parseJson(readFileSync(evidencePath, 'utf8'), evidencePath);
+        if (evidence && evidence.candidate_digest === review.candidate_digest) {
+            return 'reviewed this suite as it stood at review time, and it has changed since — re-run ' +
+                '`unitbob suite-review-prepare` and have the reviewer look at the changed suite.';
+        }
+    }
+    return 'does not review the current behavioral suite candidate.';
+}
+// The runs the connector made of this exact candidate, and the defect choice
+// they were made under. One file, read on its own: the evidence the upload
+// carries must not depend on what the reviewer was shown, and reaching back into
+// the reviewer's request for the defect choice would have re-created exactly
+// that dependency.
+function readCandidateRunEvidence(projectRoot, output) {
+    const path = candidateRunPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`unitbob suite-review-prepare\` to record the candidate's run.`);
+    }
+    const file = parseJson(readFileSync(path, 'utf8'), path);
     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) {
+    if (!file || file.candidate_digest !== digest || !isRunEvidence(file.candidate_run, digest)) {
         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) {
+    // Demanded, not defaulted. `readKnownDefectContext` reads a missing field as
+    // `not_supplied`, which is right for a file someone else may have written and
+    // wrong here: the connector writes this one itself, always with the choice it
+    // was given. Missing means the file is damaged, and taking it as "no defect
+    // was supplied" would turn that into a silently skipped fixed-revision check.
+    if (file.known_defect_context === undefined) {
+        throw new Error(`${path} records no known_defect_context — run \`unitbob suite-review-prepare\` again.`);
+    }
+    const context = readKnownDefectContext(file.known_defect_context, path);
+    if (context.status === 'supplied' && context.fixed_revision) {
+        const fixed = file.fixed_candidate_run;
+        if (!isRunEvidence(fixed, digest) || fixed?.revision !== context.fixed_revision) {
             throw new Error(`${path} has no connector runner evidence for fixed revision ${context.fixed_revision}.`);
         }
     }
-    return request;
+    return file;
+}
+function isRunEvidence(value, digest) {
+    const run = value;
+    return Boolean(run && run.candidate_digest === digest &&
+        typeof run.revision === 'string' && run.revision &&
+        typeof run.run_result === 'string' && run.run_result);
 }
 export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
     const request = {
@@ -173,9 +231,9 @@ export function readHostSuiteOutputs(path, request) {
         throw new Error(`${path} is malformed: expected a branches array, one entry per contract system.`);
     }
     const rootFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root]));
-    return branches.map((entry) => readBranch(entry, rootFor, path));
+    return branches.map((entry) => readBranch(entry, rootFor, path, request.project_root));
 }
-function readBranch(entry, rootFor, path) {
+function readBranch(entry, rootFor, path, projectRoot) {
     if (!entry || typeof entry !== 'object') {
         throw new Error(`${path} is malformed: each branch must be an object.`);
     }
@@ -201,32 +259,64 @@ function readBranch(entry, rootFor, path) {
     }
     return {
         suite_kind: suiteKind,
-        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind),
+        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind, projectRoot),
         runner_manifest: manifest,
         test_metadata: branch.test_metadata,
     };
 }
-// The host inlines every file's `content`; each path is checked safe under this
-// branch's root before anything is accepted.
-function resolveSuiteFile(file, root, path, suiteKind) {
+// Each path is checked safe under this branch's root before anything is
+// accepted. `content` may be inlined, but it does not have to be: the host wrote
+// and ran these files on disk before answering, so a bare `{ path }` means "the
+// file already under that path is the answer". Re-serializing a whole suite into
+// this JSON on every rebuild was the single largest cost in the build loop, and
+// the copy was never more trustworthy than the file that was actually executed.
+function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
     if (!file || typeof file !== 'object') {
         throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }
     const envelope = file;
-    const main = readOneFile(envelope, root, path, suiteKind, false);
+    const main = readOneFile(envelope, root, path, suiteKind, false, projectRoot);
     const support = Array.isArray(envelope.support_files)
-        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true))
+        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true, projectRoot))
         : [];
     return support.length > 0 ? { ...main, support_files: support } : main;
 }
-function readOneFile(file, root, path, suiteKind, support) {
+function readOneFile(file, root, path, suiteKind, support, projectRoot) {
     const filePath = typeof file.path === 'string' ? file.path : '';
     assertUnitbobPath(filePath, root);
     if (typeof file.content === 'string' && file.content.trim()) {
         return { path: filePath, content: file.content };
     }
-    const label = support ? 'support file' : 'suite_file';
-    throw new Error(`${path}: the ${suiteKind} ${label} at "${filePath}" has no inline content.`);
+    if (file.content !== undefined) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" has empty content.`);
+    }
+    const onDisk = join(projectRoot, filePath);
+    if (!existsSync(onDisk)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} names "${filePath}", but no such file exists — write it before answering, or inline its content.`);
+    }
+    // `assertUnitbobPath` judges the path text; it cannot see that a safe-looking
+    // name is a link out of the suite root — nor that the directory holding it is.
+    // Inlined content could never reach outside the answer, so reading from disk
+    // is where that check has to be made: these bytes are uploaded.
+    //
+    // Only the project root is resolved, and the suite root is then joined onto it
+    // as text. Resolving the suite root too would let a linked `.unitbob/<kind>/`
+    // vouch for itself — every file under it resolves neatly under the link's own
+    // target. Resolving nothing at all would fail honest projects instead, because
+    // a macOS temp or home path is itself reached through a link.
+    // The wire's `path_root` carries a trailing slash; `join` keeps it.
+    const suiteRoot = join(realpathSync(projectRoot), root).replace(/[\\/]+$/, '');
+    if (!realpathSync(onDisk).startsWith(`${suiteRoot}${sep}`)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" resolves outside the suite root — suite files must be real files under it.`);
+    }
+    const content = readFileSync(onDisk, 'utf8');
+    if (!content.trim()) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" is empty.`);
+    }
+    return { path: filePath, content };
+}
+function fileLabel(support) {
+    return support ? 'support file' : 'suite_file';
 }
 function parseJson(raw, path) {
     try {

package/dist/verbs/putSuiteBuild.js

@@ -6,6 +6,9 @@ import { Wire } from "../wire.js";
 // the host cannot claim a different map than each branch was given. A branch the
 // host could not build is uploaded as a `build_error`, which never rolls back the
 // peer branch. If a branch's answer is unparseable, nothing is uploaded.
+//
+// Returns the server's per-branch results so the caller can compose the first run
+// on top of them (spec 32-4) without parsing the lines printed here.
 export async function putSuiteBuild(config, _args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
     const outputs = readHostSuiteOutputs(request.output_path, request);
@@ -57,10 +60,37 @@ export async function putSuiteBuild(config, _args = [], deps) {
     for (const result of results) {
         d.stdout.write(`${printResult(result)}\n`);
     }
+    return results;
 }
+// The three outcomes that leave a branch published and current: a new version, an
+// identical version already stored, or a reactivated one. Each returns the
+// identity to run. Everything else — a rejected branch, a branch the host could
+// not build, or a status this connector has never seen — fails closed and is
+// never run, so a newer server can never trick an older connector into running
+// something it does not understand.
+const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
+export function classifyPublication(results) {
+    const split = { digests: [], unpublished: [] };
+    for (const result of results) {
+        if (!PUBLISHED.has(result.status)) {
+            split.unpublished.push(result.suite_kind);
+            continue;
+        }
+        if (!result.suite_digest) {
+            throw new Error(`The server accepted the ${result.suite_kind} suite as "${result.status}" but returned no identity ` +
+                'to run it by. The suite is published; run the Unitbob checks to finish.');
+        }
+        split.digests.push(result.suite_digest);
+    }
+    return split;
+}
+// Asks `PUBLISHED` rather than naming the failing statuses again: this line and
+// the run that follows it must agree about what "published" means, or a branch the
+// command skipped gets a line that reads like a success — digest and all — right
+// above "no suite was published".
 function printResult(result) {
-    if (result.status === 'error' || result.status === 'build_error') {
-        return `${result.suite_kind}: not published — ${result.error ?? 'the host could not build this suite'}.`;
+    if (!PUBLISHED.has(result.status)) {
+        return `${result.suite_kind}: not published — ${unpublishedReason(result)}.`;
     }
     const tallies = result.counts
         ? Object.entries(result.counts)
@@ -70,3 +100,13 @@ function printResult(result) {
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
     return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
 }
+// The server's own words when it sent any; otherwise the best true thing that can
+// be said. A status this connector does not know is quoted rather than guessed
+// at — claiming the host could not build it would invent a cause.
+function unpublishedReason(result) {
+    if (result.error)
+        return result.error;
+    if (result.status === 'build_error')
+        return 'the host could not build this suite';
+    return `the server answered "${result.status}"`;
+}

package/dist/verbs/run.js

@@ -8,9 +8,22 @@ import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
 const OUTPUT_TAIL_CHARS = 2000;
+// `check`/`run`: execute every ready peer. This is the standalone flow the user
+// asks for by name, and the recovery path after an interrupted first run.
 export async function run(config, _args, deps) {
+    return execute(config, resolve(config, deps), null);
+}
+// The first run that `put-suite-build` performs itself (spec 32-4): execute
+// exactly the suite identities publication just returned, or none of them. Every
+// requested identity must still be the current one — see `select`. Callers pass a
+// non-empty list; "nothing was published" is decided and reported one level up,
+// where the publication results that explain it are still in hand.
+export async function runOnly(config, digests, deps) {
+    return execute(config, resolve(config, deps), digests);
+}
+function resolve(config, deps) {
     const wire = new Wire(config);
-    const d = {
+    return {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
@@ -25,14 +38,17 @@ export async function run(config, _args, deps) {
         stdout: process.stdout,
         ...deps,
     };
+}
+async function execute(config, d, only) {
     const suites = await d.getSuites();
     const ready = suites.filter((item) => item.status === 'ready');
-    if (ready.length === 0) {
+    const selected = only === null ? ready : select(ready, only);
+    if (selected.length === 0) {
         d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
     const runs = [];
-    for (const item of ready) {
+    for (const item of selected) {
         runs.push(await buildRunPayload(config, d, item));
     }
     const { results, map_url } = await d.postRunsBatch(runs);
@@ -41,6 +57,21 @@ export async function run(config, _args, deps) {
     if (map_url)
         d.stdout.write(`${map_url}\n`);
 }
+// All-or-nothing. Publication and this fetch are two requests, so another client
+// can republish in between. Running whatever is current instead would file honest
+// results against a version the user never asked about, and silently substituting
+// an older suite for a branch that failed to publish would be worse still. So a
+// requested identity that is no longer current stops the whole run.
+function select(ready, wanted) {
+    const byDigest = new Map(ready.map((item) => [item.suite_digest ?? '', item]));
+    const missing = wanted.filter((digest) => !byDigest.has(digest));
+    if (missing.length > 0) {
+        throw new Error(`The suite this project just published (${missing.join(', ')}) is no longer the current one — ` +
+            'something else replaced it while this command was running. Nothing was run, so no results were ' +
+            'filed against the wrong version.');
+    }
+    return wanted.map((digest) => byDigest.get(digest));
+}
 // One branch's run payload. A stack mismatch, a materialize failure, or a runner
 // that produced no report all become this branch's structured suite error — the
 // peer branch is unaffected. This connector never installs anything: a missing

package/dist/verbs/suiteReviewPrepare.js

@@ -2,7 +2,7 @@ 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 { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, 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";
@@ -20,6 +20,13 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     if (behavioral.build_error) {
         throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
     }
+    // Say this before the run, not after: the run materializes the answer, and
+    // that is where a forgotten file turns into undefined steps — by then it is
+    // already gone.
+    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral));
+    if (lost.length > 0) {
+        actual.stdout.write(`Warning: these files sit with the suite but are not in its answer, and running it will delete them: ${lost.join(', ')}.\n`);
+    }
     const candidateRun = await actual.runCandidate(config.projectRoot, behavioral);
     const fixedRevision = buildRequest.known_defect_context.status === 'supplied'
         ? buildRequest.known_defect_context.fixed_revision

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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": {