unitbob 0.4.5 → 0.5.0

package/dist/runner/vitest.js

@@ -1,7 +1,8 @@
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
@@ -28,27 +29,44 @@ const PROJECT_CONFIGS = [
     'vite.config.cjs',
 ];
 // Run the materialised Unitbob guardrail suite with the project's own Vitest
-// (spec 30). Only the guardrail file runs — the path argument filters the run.
+// (spec 30). Only the guardrail files run — the path arguments filter the run.
 //
-// A bare `vitest run <file>` treats the path as a filter that is intersected
+// A bare `vitest run <file>` treats each path as a filter that is intersected
 // with the project's `test.include`, so a project whose include does not cover
-// `.unitbob/` would collect no tests. When the project has its own config we
-// therefore write a tiny config that merges it and adds the guardrail file to
-// `include`; the positional filter still narrows the run to that one file. With
-// no project config, Vitest's default include already covers `.unitbob/`, so
-// the bare command is correct and we write nothing.
+// `.unitbob/` would collect no tests. So the config Unitbob writes names every
+// file of the branch in `include`, and the positional filters keep the run to
+// exactly those files.
+//
+// Named files rather than a directory glob, since spec 42, §6.5 made a branch
+// several files: the artifact already says which files it is, and a glob would
+// have to guess a naming convention nothing enforces. `include` is written even
+// when the project has no config of its own — Vitest's default include only
+// covers `.unitbob/` for a file that happens to be named `*.test.ts`, which is a
+// trap set for whoever names a slice after its capability.
 //
 // The JSON report goes to --outputFile, not stdout, so app logging can never
 // corrupt it. The command is connector-owned: the suite artifact never carries
 // a command string.
-export async function runVitestSuite(projectRoot, suitePath) {
-    const configArgs = writeMergedConfig(projectRoot, suitePath);
-    const command = 'npx';
-    const args = ['vitest', 'run', suitePath, ...configArgs, '--reporter=json', `--outputFile=${VITEST_RESULT_FILE}`];
+export async function runVitestSuite(projectRoot, suitePaths) {
+    const configArgs = writeMergedConfig(projectRoot, suitePaths);
+    // An installed vitest — the sidecar's, else the project's — is spawned by
+    // path. `npx` stays as the last resort it has always been: it is the only
+    // option that can conjure a runner out of nothing, which is right here at the
+    // end and wrong everywhere else (see `locateRunner`, which does not offer it).
+    const located = locateRunner(projectRoot, 'vitest');
+    const command = located?.command ?? 'npx';
+    const args = [
+        ...(located ? located.args : ['vitest']),
+        'run',
+        ...suitePaths,
+        ...configArgs,
+        '--reporter=json',
+        `--outputFile=${VITEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: VITEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -58,31 +76,47 @@ export async function runVitestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
     };
 }
-// Returns the `--config` args to add, writing the merge config first. When the
-// project has no config of its own there is nothing to inherit and nothing to
-// override (defaults already cover .unitbob/), so we return no args.
-function writeMergedConfig(projectRoot, suitePath) {
+// Returns the `--config` args to add, writing the config first. Always written:
+// the branch's files have to be in `include` or nothing is collected, and the
+// names a worker gives its slice are not something to bet a whole run on.
+function writeMergedConfig(projectRoot, suitePaths) {
     const projectConfig = PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
-    if (!projectConfig)
-        return [];
-    writeFileSync(join(projectRoot, VITEST_CONFIG_FILE), mergedConfigSource(projectConfig, suitePath));
+    const path = join(projectRoot, VITEST_CONFIG_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, configSource(projectConfig, suitePaths));
     return ['--config', VITEST_CONFIG_FILE];
 }
 // The .unitbob/ config sits one level below the project root, so the project
-// config is a `../` import. `mergeConfig` concatenates `include`, so the
-// guardrail file joins the project's patterns instead of replacing them; the
-// positional filter then isolates it. A function-form config is resolved first.
-function mergedConfigSource(projectConfig, suitePath) {
-    return `// Written by the unitbob connector before each vitest run — do not edit.
-import { mergeConfig } from 'vitest/config';
+// config is a `../` import. A function-form config is resolved first, and
+// everything the project set — plugins, aliases, setup files, environment — is
+// carried through; only `test.include` is replaced, with exactly this branch's
+// files. Replacing rather than concatenating is the point: the run must be these
+// files and no others, and the positional filters then say the same thing twice.
+//
+// Nothing is imported from `vitest` itself, and that is deliberate. Vite
+// re-imports this generated file from a temporary module beside it, so every
+// bare `import` here resolves by walking up from `.unitbob/` — while a project
+// whose only vitest is the one Unitbob installed keeps it at
+// `.unitbob/runners/node_modules`, which is not on that path. An
+// `import { mergeConfig } from 'vitest/config'` there dies with
+// ERR_MODULE_NOT_FOUND before a single test is collected, on exactly the
+// projects the sidecar exists for. A spread does the same job with no import,
+// and `defineConfig` is a typing helper that buys a generated file nothing.
+function configSource(projectConfig, suitePaths) {
+    const include = `include: ${JSON.stringify(suitePaths)}`;
+    const header = '// Written by the unitbob connector before each vitest run — do not edit.';
+    if (!projectConfig) {
+        return `${header}
+export default { test: { ${include} } };
+`;
+    }
+    return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
 
-export default mergeConfig(base, {
-  test: { include: [${JSON.stringify(suitePath)}] },
-});
+export default { ...base, test: { ...(base.test ?? {}), ${include} } };
 `;
 }

package/dist/surfaces/routeInventory.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { dirname, join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
+import { detectStructuralRunner } from "../runner/precheck.js";
 import { graphPath } from "../files/mapBuild.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
@@ -20,7 +21,7 @@ export function routeInventoryPath(projectRoot) {
 // records why Django, FastAPI and Flask come next and why Express cannot follow
 // at all (its addresses are registered by arbitrary code at run time).
 export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
-    if (!looksLikeRails(projectRoot))
+    if (!canAskTheRouter(projectRoot))
         return silent(projectRoot, 'unsupported_stack');
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
@@ -150,8 +151,19 @@ function becauseOf(result) {
 function plural(count, one, many) {
     return count === 1 ? one : many;
 }
-function looksLikeRails(projectRoot) {
-    return existsSync(join(projectRoot, 'config', 'routes.rb'));
+// Which stack this is, is not this module's question — one answer to it already
+// exists and this file now asks it. `config/routes.rb` stays as a second-level
+// condition inside the Ruby branch, because a Rails application without a route
+// file has no router to ask.
+//
+// It used to be the whole test, which made it a fourth independent way of
+// deciding "is this Rails?" — and one that was wrong at both edges: a Rails app
+// that keeps its routes elsewhere was refused, and any project that happens to
+// carry a `config/routes.rb` was asked to boot Rails. There are still several
+// stack detectors in this package; this removes the one that had a single caller
+// and no excuse.
+function canAskTheRouter(projectRoot) {
+    return (detectStructuralRunner(projectRoot) === 'rspec' && existsSync(join(projectRoot, 'config', 'routes.rb')));
 }
 // The question, asked of the router object rather than of the `rails routes`
 // command line. `--expanded` was the earlier reading, and it cost this project

package/dist/verbs/codexInstall.js

@@ -2,7 +2,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder'];
+const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
 const bundledAgentsDir = fileURLToPath(new URL('../../plugin/codex/agents/', import.meta.url));
 export function installCodexAgents(args, deps = { home: homedir(), stdout: process.stdout }) {
     if (args.length > 0)

package/dist/verbs/putSuiteBuild.js

@@ -1,5 +1,6 @@
-import { readBehavioralReview, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { collectBuildProblems, formatBranchProblems } from "./validateBuild.js";
+import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { collectBuildProblems } from "./validateBuild.js";
+import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.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
@@ -28,7 +29,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
-    const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
     const items = [];
     const blocked = unreadable.map((entry) => ({
         suite_kind: entry.suite_kind,
@@ -39,26 +39,19 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
+    // Since spec 42 that check is exactly one question, and it is about a branch
+    // the answer has *no* entry for: everything else it used to ask is now asked
+    // of the server, by a dry run, before this command runs at all. So its
+    // problems can never land on a branch this loop visits, and they are reported
+    // below rather than inside it.
+    //
     // An earlier draft threw and stopped the command, which quietly undid spec
-    // 32-5 Phase 4: one missing marker in the behavioral answer would have left a
-    // finished structural suite unpublished. Every problem this check raises is
-    // already named against a branch, so it blocks that branch and never the
-    // batch. That also bounds what a false positive in a local check can cost —
-    // one branch, with the peer still going up and the server still the authority.
-    const problemsFor = new Map();
-    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
-        problemsFor.set(problem.branch, [...(problemsFor.get(problem.branch) ?? []), problem.message]);
-    }
+    // 32-5 Phase 4: one behavioral problem would have left a finished structural
+    // suite unpublished. Every problem here is named against a branch, so it
+    // blocks that branch and never the batch.
     for (const output of outputs) {
-        const failed = problemsFor.get(output.suite_kind);
-        problemsFor.delete(output.suite_kind);
-        if (failed) {
-            blocked.push({ suite_kind: output.suite_kind, status: BLOCKED_STATUS, error: formatBranchProblems(failed) });
-            continue;
-        }
-        const sourceDigest = digestFor.get(output.suite_kind) ?? '';
         if (output.build_error) {
-            items.push({ suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error });
+            items.push(uploadItem(request, output, undefined));
             continue;
         }
         let testMetadata = output.test_metadata;
@@ -71,23 +64,14 @@ export async function putSuiteBuild(config, _args = [], deps) {
                 continue;
             }
         }
-        items.push({
-            suite_kind: output.suite_kind,
-            source_digest: sourceDigest,
-            artifacts: {
-                suite_file: output.suite_file,
-                runner_manifest: output.runner_manifest,
-                test_metadata: testMetadata,
-            },
-        });
+        items.push(uploadItem(request, output, testMetadata));
     }
-    // What is left in `problemsFor` belongs to a branch the loop above never
-    // reached, because the answer has no entry for it at all. It has nothing to
-    // upload and nothing to roll back, so it costs its peer nothing — but it is
+    // A branch the request asked for and the answer never mentions. It has nothing
+    // to upload and nothing to roll back, so it costs its peer nothing — but it is
     // exactly the branch that used to leave no trace anywhere, and the one line it
     // prints here is the whole point of noticing it (spec 32-6, a2time 2026-08-04).
-    for (const [suiteKind, messages] of problemsFor) {
-        blocked.push({ suite_kind: suiteKind, status: BLOCKED_STATUS, error: formatBranchProblems(messages) });
+    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
+        blocked.push({ suite_kind: problem.branch, status: BLOCKED_STATUS, error: problem.message });
     }
     // Every branch is blocked, so there is nothing to upload. Asking the server to
     // publish an empty batch would turn a local, already-explained problem into a
@@ -103,46 +87,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
 // malformed. Not a server status — it never reaches the server — but it travels
 // as one so a single rule decides what counts as published (see `PUBLISHED`).
 const BLOCKED_STATUS = 'not_ready';
-// The behavioral branch's uploaded metadata, with the independent review and the
-// connector's own run evidence folded in.
-//
-// Throws for anything that leaves this branch unpublishable — a missing review,
-// one bound to a different candidate, a defect the review called not_supplied.
-// The caller turns that into one unpublished branch rather than a failed
-// command: a blocked review is a fact about the behavioral suite, and the
-// structural peer next to it is finished and correct. Sinking the whole upload
-// with it forced the one workaround this contract exists to prevent — hand-editing
-// the answer down to a single branch, which loses the peer candidate for real.
-function withReview(config, request, output) {
-    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.');
-    }
-    return {
-        ...output.test_metadata,
-        bdd_quality_review: {
-            ...qualityReview,
-            candidate_digest: review.candidate_digest,
-        },
-        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
-        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 } : {}),
-    };
-}
-// 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) {
@@ -176,7 +120,20 @@ function printResult(result) {
             .join(', ')
         : '';
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
-    return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
+    return (`${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.` + printDowngrades(result));
+}
+// Spec 42, §7. A capability every one of whose Scenarios the review objected to
+// is stored `unguarded` by the publish. The run is standing right here when that
+// is decided, so it is told here, in the server's own words — finding it on the
+// map afterwards is how a run finishes believing it published a guarantee it did
+// not.
+function printDowngrades(result) {
+    const downgraded = result.unguarded_by_review ?? [];
+    if (downgraded.length === 0)
+        return '';
+    return (`\n  ${downgraded.length} capability(ies) published unguarded, because the review objected to every ` +
+        'Scenario guarding them:\n' +
+        downgraded.map((entry) => `    - ${entry.capability_id}: ${entry.reason}`).join('\n'));
 }
 // 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

package/dist/verbs/run.js

@@ -27,9 +27,12 @@ function resolve(config, deps) {
     return {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        // The whole envelope, support files and all: a branch is a set of files
+        // since spec 42, §6, and picking `path` and `content` out of it here was
+        // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
-            suite_file: { path: item.suite_file.path, content: item.suite_file.content },
+            suite_file: item.suite_file,
             runner_manifest: item.runner_manifest,
         }),
         materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
@@ -98,7 +101,7 @@ async function buildRunPayload(config, d, item) {
         }
         else {
             d.materializeStructural(config.projectRoot, item);
-            result = await d.runStructural(config.projectRoot, runner, item.suite_file.path);
+            result = await d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
         }
     }
     catch (err) {
@@ -121,18 +124,24 @@ async function buildRunPayload(config, d, item) {
 // Exported for `run-local`, which runs these same strategies against the files
 // the host just wrote rather than against a published suite. One dispatch table,
 // so the command the loop iterates on is the command that runs after publishing.
-export function runStructuralByRunner(projectRoot, runner, suitePath) {
+export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     switch (runner) {
         case 'rspec':
-            return runRspecSuite(projectRoot, suitePath);
+            return runRspecSuite(projectRoot, suitePaths);
         case 'vitest':
-            return runVitestSuite(projectRoot, suitePath);
+            return runVitestSuite(projectRoot, suitePaths);
         case 'pytest':
-            return runPytestSuite(projectRoot, suitePath);
+            return runPytestSuite(projectRoot, suitePaths);
         default:
             return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite.`));
     }
 }
+// Every file of the branch, in the order the envelope carries them. A structural
+// branch is one file per assignment since spec 42, §6, and running only the main
+// one would execute a fraction of what the map says is guarded.
+function artifactPaths(file) {
+    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+}
 function suiteError(suiteDigest, message) {
     return {
         suite_digest: suiteDigest,

package/dist/verbs/runLocal.js

@@ -102,10 +102,10 @@ async function runOneBranch(config, d, suiteKind, output) {
         return null;
     }
     let runner;
-    let suitePath;
+    let suitePaths;
     try {
         runner = branchRunner(output);
-        suitePath = mainPathOf(output);
+        suitePaths = artifactPathsOf(output);
     }
     catch (err) {
         d.stdout.write(`Cannot run this branch: ${err.message}\n`);
@@ -120,8 +120,8 @@ async function runOneBranch(config, d, suiteKind, output) {
     try {
         result =
             suiteKind === 'behavioral'
-                ? await d.runBehavioral(config.projectRoot, runner, suitePath)
-                : await d.runStructural(config.projectRoot, runner, suitePath);
+                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0])
+                : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
         d.stdout.write(`The runner could not start: ${err.message}\n`);
@@ -161,14 +161,26 @@ function outputTail(result) {
     const joined = bits.join('\n');
     return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
 }
-// The suite blob's own project-relative path, exactly as the runners expect it.
-function mainPathOf(output) {
+// The suite blob's own project-relative paths, exactly as the runners expect
+// them: the main file first, then every other file of the branch. The main file
+// stopped being the whole suite in spec 42, §6 — a branch is one file per
+// assignment now — and running it alone would exercise a fraction of what the
+// answer claims to guard.
+//
+// The behavioral runners are given the main `.feature` and find the rest
+// themselves: all three are pointed at the directory (`bdd.ts`), which is why a
+// multi-file behavioral branch already worked before this spec.
+function artifactPathsOf(output) {
     const file = output.suite_file;
     const path = file?.path;
     if (typeof path !== 'string' || !path) {
         throw new Error('this branch names no suite file to run.');
     }
-    return path;
+    const support = Array.isArray(file?.support_files) ? file.support_files : [];
+    const rest = support
+        .map((entry) => entry?.path)
+        .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
+    return [path, ...rest];
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -3,9 +3,9 @@ import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
-import { anyStackPrecheck, detectBddRunner, detectStructuralRunner } from "../runner/precheck.js";
+import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
-import { ensureRunner } from "../runner/provision.js";
+import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -46,7 +46,8 @@ function runnerEnvelopeFor(packet, runner, projectRoot) {
         : envelope;
 }
 // Confirm at least one supported stack is present, materialize the Ruby boot
-// helper a generated RSpec suite would require, then fetch both peer assignments
+// helper an RSpec suite would need — only in a Ruby project — then fetch both
+// peer assignments
 // (spec 32) and each branch's recipe, and write the host's task to
 // `.unitbob/suite-build/request.json`. No model is called and no source is read
 // here — that is the host's job, framed by the two generation recipes. An
@@ -60,8 +61,10 @@ export async function suitePrepare(config, args = [], deps) {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
         bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
         worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
@@ -70,7 +73,36 @@ export async function suitePrepare(config, args = [], deps) {
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
-    materializeHelper(config.projectRoot);
+    // Ruby only. This wrote `unitbob_helper.rb` and `rspec.opts` into every
+    // project it touched, so a Flask app and a NestJS app each came away with a
+    // Ruby file they never asked for and cannot run — the product leaving another
+    // stack's litter in someone's repository.
+    if (detectStructuralRunner(config.projectRoot) === 'rspec')
+        materializeHelper(config.projectRoot);
+    // The stack is known; now make it runnable. A vibecoder who has never
+    // installed a test runner is the ordinary customer, not an edge case, so the
+    // runner (and, where the language allows it, the application's own
+    // dependencies) is installed under `.unitbob/` rather than reported as a
+    // reason they cannot use the product. Nothing in their project is written to.
+    //
+    // A project that already has its runner is left completely alone — see
+    // `ensureStructuralRunner` — so this costs nothing on a set-up machine.
+    const setupNotices = [];
+    if (check.runner) {
+        const provisioned = await actual.ensureStructuralRunner(config.projectRoot, check.runner);
+        if (provisioned.status === 'fixable') {
+            const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
+            throw new Error(`The ${check.runner} runner could not be installed under .unitbob/, and nothing can run without it: ` +
+                `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written and nothing was uploaded.`);
+        }
+        setupNotices.push(...(provisioned.checklist ?? []));
+        // Confirm rather than assume. Provisioning reporting success and the runner
+        // actually being startable are two different facts, and this is the cheap
+        // one to check before a whole generation is built on it.
+        const ready = actual.confirmRunner(config.projectRoot, check.runner);
+        if (!ready.ok)
+            throw new Error(ready.message ?? `The ${check.runner} runner is not available.`);
+    }
     // Spec 32-6. Before anything is fetched or written, find out whether the suite
     // would get off the ground at all. It runs here, after the boot helper exists
     // and before the network, so a project whose suite cannot start costs one
@@ -170,6 +202,9 @@ export async function suitePrepare(config, args = [], deps) {
         `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 (setupNotices.length > 0) {
+        actual.stdout.write('\nOne setup step is worth knowing about before you generate:\n  - ' + setupNotices.join('\n  - ') + '\n');
+    }
     if (fixableNotices.length > 0) {
         actual.stdout.write('\nBehavioral suite skipped this run — its runner or connector-owned World profile is not ready. ' +
             'This is a fixable setup step, not a build failure, and it does not affect the structural suite:\n' +
@@ -224,9 +259,10 @@ function bootFinding(boot, runner) {
     // the one the vibecoder can paste into a search.
     const next = boot.cause === 'defect_in_code'
         ? 'Fix that, then run `unitbob suite-prepare` again.'
-        : "Unitbob does not install your project's own dependencies — that would rewrite your Gemfile.lock " +
-            'or package-lock.json. Run the install your project needs (`bundle install`, `npm install`, ' +
-            '`pip install -r requirements.txt`), then run `unitbob suite-prepare` again.';
+        : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+            'it never writes to your project. Something outside that file is still missing here. Run the ' +
+            'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
+            'then run `unitbob suite-prepare` again.';
     return (`${headline}\n\n` +
         `  ${boot.message}\n\n` +
         `${boot.detail}\n\n` +