unitbob 0.7.2 → 0.7.4

package/dist/files/packets.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { graphNodes, methodNameOf } from "../surfaces/graph.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 import { surfacesPath } from "./mapBuild.js";
@@ -52,8 +52,7 @@ export function readPacketIndex(projectRoot) {
 // request, the workers are not, so a packet belongs to an entrypoint and two
 // entrypoints in one file share one packet.
 export function writeSuitePackets(projectRoot, request) {
-    const targets = targetsOf(request);
-    const lookup = buildLookup(projectRoot);
+    const targets = resolveTargets(projectRoot, request);
     const notes = new Map();
     // Regenerated whole, every run. A packet left over from a previous assignment
     // sits under an authoritative name with nothing on it saying how old it is.
@@ -63,15 +62,11 @@ export function writeSuitePackets(projectRoot, request) {
     const written = new Map();
     const refused = new Map();
     for (const target of targets) {
-        const sourceFile = lookup(target.entrypoint);
+        const sourceFile = target.source_file;
         if (!sourceFile) {
-            target.note = 'no single file in graph.json or surfaces.json answers to this name — find it yourself';
             count(notes, 'did not resolve to one file');
             continue;
         }
-        // The path travels even when the contents do not: a worker told which file
-        // to open has still been saved the search.
-        target.source_file = sourceFile;
         // Two entrypoints in one file get one packet, written once, referenced twice.
         if (!written.has(sourceFile) && !refused.has(sourceFile)) {
             const copied = copyPacket(projectRoot, sourceFile);
@@ -105,6 +100,63 @@ export function writeSuitePackets(projectRoot, request) {
         notes: [...notes].map(([note, count]) => `${count} × ${note}`),
     };
 }
+// Every entrypoint the request names, each with the file behind it when one file
+// answers. The one place a name is turned into a path: `writeSuitePackets` copies
+// what comes out of here, and `structuralSourceFiles` only reads it. Two
+// resolvers would be two chances to disagree about which file serves a name, and
+// the boot check and the packets have to be talking about the same files.
+//
+// The words for a name nothing answered to are set here rather than by the
+// caller, because they are part of the answer.
+function resolveTargets(projectRoot, request) {
+    const targets = targetsOf(request);
+    const lookup = buildLookup(projectRoot);
+    for (const target of targets) {
+        const sourceFile = lookup(target.entrypoint);
+        // The path travels even when the contents do not: a worker told which file
+        // to open has still been saved the search.
+        if (sourceFile)
+            target.source_file = sourceFile;
+        else
+            target.note = 'no single file in graph.json or surfaces.json answers to this name — find it yourself';
+    }
+    return targets;
+}
+// Spec 38, criterion 2. The source files the structural guardrails of this
+// request will import — the list the boot check loads instead of the project's
+// own tests. Computed from two artifacts already on this machine, so it costs no
+// token and no network call.
+//
+// A name nothing answered to is simply absent. That gap is already a visible
+// number — "the source behind N of M entrypoints" — and turning it into a
+// refusal would stop a run over a hole in the graph (see В3 of the requirements).
+export function structuralSourceFiles(projectRoot, request) {
+    const files = [];
+    for (const target of resolveTargets(projectRoot, request)) {
+        if (target.branch !== 'structural' || !target.source_file)
+            continue;
+        // Only a path that is plainly inside this checkout, and only a file that is
+        // really there. graph.json is written by a tool, not by us, and what comes
+        // out of here becomes an `import` statement — so an absolute path or a `..`
+        // would load something this project does not contain, and a name the graph
+        // kept after the file moved would fail to resolve.
+        //
+        // That last one is the whole reason this check exists. A stale graph entry
+        // reaches the runner as "Failed to resolve import" or "FileNotFoundError",
+        // which reads as a dependency that is not installed or a module that will
+        // not load — and the vibecoder would be sent to repair their code over a
+        // hole in *our* map. `writeSuitePackets` already refuses all three, in
+        // words, one file further down; here silence is right, because nothing reads
+        // this list but the probe.
+        if (isAbsolute(target.source_file) || target.source_file.split('/').includes('..'))
+            continue;
+        if (!existsSync(join(projectRoot, target.source_file)))
+            continue;
+        if (!files.includes(target.source_file))
+            files.push(target.source_file);
+    }
+    return files;
+}
 // The two names a request carries. Structural interfaces name methods
 // (`User#get_token`); behavioral capabilities name addresses (`POST /api/tokens`).
 // Both are entrypoints, both resolve to a file, and both produce the same kind

package/dist/runner/bootcheck.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable } from "../proc.js";
 import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
@@ -6,6 +6,7 @@ import { commandFileOnHost, locateRunner } from "./toolchain.js";
 import { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
 import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
+import { VITEST_BOOT_CONFIG_FILE, vitestBootConfigSource } from "./vitest.js";
 const defaultDeps = {
     runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: PROVISION_TIMEOUT_MS, env: options.env }),
 };
@@ -18,23 +19,29 @@ const DETAIL_LIMIT = 4_000;
 export const SIGNAL_STRENGTH = {
     rspec: 'Full signal on this stack: the check loads the very file the suite starts from, ' +
         'so whatever stops one stops the other.',
-    pytest: 'Partial signal on this stack: collection only imports what the tests import, so code no ' +
-        'test reaches was not checked — and it imports the whole test tree, so a failure may belong ' +
-        "to one of the project's own tests rather than to the suite that was about to be written.",
-    vitest: 'Weak signal on this stack: only test files are parsed and imported, and all of them — so a ' +
-        "failure may belong to one of the project's own tests. Type errors are not checked at all " +
-        '(vite and esbuild strip types without checking them), and a project with no tests yields ' +
-        'no signal.',
+    pytest: 'Full signal on the files it names: the check imports the very modules the guardrails of this ' +
+        "branch will import, and nothing else — none of this project's own tests are opened. Code that " +
+        'no guardrail imports was not looked at.',
+    vitest: 'Full signal on the files it names: the check imports the very modules the guardrails of this ' +
+        "branch will import, through this project's own vite configuration, and nothing else — none of " +
+        "the project's own tests are opened. Types are not checked (vite strips them without checking " +
+        'them), and code no guardrail imports was not looked at.',
 };
 // Does the suite for this stack get off the ground? One attempt, one answer.
-export async function bootCheck(projectRoot, runner, deps = defaultDeps) {
+//
+// `sourceFiles` are the project's own source files this branch's guardrails will
+// import, resolved from the map (spec 38). They are what gets loaded on the two
+// stacks that have no boot file of their own — never the project's test tree.
+// Ruby ignores the list: its helper is the suite's real first line and already
+// pulls the application up behind it.
+export async function bootCheck(projectRoot, runner, sourceFiles, deps = defaultDeps) {
     switch (runner) {
         case 'rspec':
             return rubyBootCheck(projectRoot, deps);
         case 'pytest':
-            return pytestBootCheck(projectRoot, deps);
+            return pytestBootCheck(projectRoot, sourceFiles, deps);
         case 'vitest':
-            return vitestBootCheck(projectRoot, deps);
+            return vitestBootCheck(projectRoot, sourceFiles, deps);
         default:
             return { status: 'not_checked', reason: 'no_runner' };
     }
@@ -80,7 +87,7 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // executable makes `spawn` throw, `attempt` return null, and the answer come
     // back `no_runner`: "no runner available to load your suite with", said to
     // someone whose bundler is installed and working. That is the mistake
-    // `runner_too_old` and `runner_could_not_answer` were added to stop making,
+    // `runner_could_not_answer` was added to stop making,
     // and the global `bundle` was standing right there the whole time.
     const command = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     // When Unitbob installed rspec-rails for itself, the gems this helper needs
@@ -106,9 +113,11 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // suite failing to start.
     (result) => (result.code === 0 ? 'ok' : 'broken'));
 }
-// Python: `pytest --collect-only` imports every test module, which is what the
-// run would do first. It sees import errors in code the tests reach, and only
-// there — recorded as a limitation rather than dressed up as completeness.
+// Python: run one test file of our own, which imports the modules the
+// guardrails will import. Not `--collect-only`, and not the project's test tree:
+// what the run would do first is import *our* suite's targets, and asking pytest
+// to collect everything it can find asks about files this product never touches
+// (spec 38, criterion 1).
 //
 // `-c` with an empty-addopts config, exactly as `runPytestSuite` does and for
 // exactly its reason: the project's own `addopts` (`--cov`, `-n auto`) must not
@@ -117,7 +126,9 @@ async function loadRubyHelper(projectRoot, helper, deps) {
 // a `--cov` flag. The run path had already solved this; the check had not
 // inherited the solution, which also made it *stricter* than the thing it
 // predicts, the one rule this whole check is built on.
-async function pytestBootCheck(projectRoot, deps) {
+async function pytestBootCheck(projectRoot, sourceFiles, deps) {
+    if (sourceFiles.length === 0)
+        return { status: 'not_checked', reason: 'nothing_to_load' };
     // Its own directory, rather than relying on `materializeHelper` having run
     // first: this check must not fail because a different step was skipped.
     mkdirSync(join(projectRoot, dirname(PYTEST_INI_FILE)), { recursive: true });
@@ -139,13 +150,19 @@ async function pytestBootCheck(projectRoot, deps) {
             { command: 'python3', args: ['-m', 'pytest'], env: undefined },
             { command: 'python', args: ['-m', 'pytest'], env: undefined },
         ];
-    for (const candidate of candidates) {
-        const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--collect-only', '-q'], { cwd: projectRoot, env: candidate.env });
-        if (result === null)
-            continue; // this interpreter is not on the machine
-        return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
-    }
-    return { status: 'not_checked', reason: 'no_runner' };
+    return withProbe(projectRoot, { [PYTEST_PROBE_FILE]: pytestProbeSource(sourceFiles) }, async () => {
+        for (const candidate of candidates) {
+            // The probe's path is passed explicitly, and it has to be: `.unitbob` is a
+            // hidden directory, which pytest's default `norecursedirs` skips. Without
+            // the path it would collect the project's tests and not ours — the exact
+            // mistake this spec removes.
+            const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--rootdir', '.', PYTEST_PROBE_FILE, '-q'], { cwd: projectRoot, env: candidate.env });
+            if (result === null)
+                continue; // this interpreter is not on the machine
+            return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
+        }
+        return { status: 'not_checked', reason: 'no_runner' };
+    });
 }
 // pytest's own exit vocabulary, used rather than "zero or not". The distinction
 // that matters is between "your code did not load" and "pytest itself could not
@@ -155,8 +172,9 @@ function pytestVerdict(code) {
     // unreachable — but "no exit code" can only ever mean "we learned nothing".
     if (code === null)
         return 'runner_could_not_answer';
-    // 5 — collected nothing. A project that came to Unitbob *for* tests is the
-    // typical customer, not a defect.
+    // 5 — collected nothing. Since spec 38 the only file offered for collection is
+    // our own probe, so this now means "our probe was not collected", not "this
+    // project has no tests". Still not a verdict on the code either way.
     if (code === 5)
         return 'nothing_to_load';
     // 3 — internal error, 4 — bad usage. Both are about the invocation, not the
@@ -165,16 +183,34 @@ function pytestVerdict(code) {
         return 'runner_could_not_answer';
     return code === 0 ? 'ok' : 'broken';
 }
-// JS/TS: `vitest list` parses and imports the test files, which is the closest
-// thing this stack has to a boot.
+// JS/TS: run one test file of our own, which imports the source files the
+// guardrails will import.
+//
+// It used to be `vitest list`, which parses and imports *every* test file the
+// project has. That answered about somebody else's tests: a jest project came
+// back "found a defect that stops your test suite from starting" because its own
+// suites, green under jest, do not define `describe` under vitest. We do not
+// need the project's tests — we write our own — so we stopped opening them
+// (spec 38, criterion 1).
+//
+// Why a test file rather than a plain import: a test runner has no "load this
+// module and tell me if it exploded" command, and a bare `node` cannot stand in,
+// because TypeScript, JSX, path aliases and bundler plugins are exactly what
+// vite resolves from the project's own config. So the probe is a legal vitest
+// test that asserts nothing and imports everything named. Ruby has done the same
+// since spec 29, through `unitbob_helper.rb`.
 //
 // `tsc --noEmit` is deliberately not used. It answers a different question —
 // are the types sound — and a project with a hundred type errors runs perfectly
 // well, because vite, esbuild and tsx strip types without checking them. Type
 // errors accumulate for years in healthy codebases; calling that "broken" would
 // turn away the majority. A file that is genuinely unparseable is caught here
-// anyway, since `vitest list` has to parse it.
-async function vitestBootCheck(projectRoot, deps) {
+// anyway, since the probe's import has to parse it.
+async function vitestBootCheck(projectRoot, sourceFiles, deps) {
+    // Nothing the map resolved to a file, so there is nothing to import. That is a
+    // hole in the graph, not a broken application, and the run carries on.
+    if (sourceFiles.length === 0)
+        return { status: 'not_checked', reason: 'nothing_to_load' };
     // A sidecar vitest counts as installed: it is ours, it is on disk, and it is
     // the one the run will spawn. What stays out is `npx`, for the reason below.
     const local = locateRunner(projectRoot, 'vitest')?.command ?? 'node_modules/.bin/vitest';
@@ -183,52 +219,107 @@ async function vitestBootCheck(projectRoot, deps) {
     // user's project is not this check's business.
     //
     // `executable`, not `existsSync`, and there is no fallback to go to: an
-    // unrunnable binary sends `spawn` into EACCES, `supportsList` reads that as
-    // "cannot be asked", and the answer came back `runner_too_old` — a positive
-    // falsehood about a version nobody looked at. `no_runner` is the honest one
-    // here: there is no vitest this check can invoke.
+    // unrunnable binary sends `spawn` into EACCES and there is nothing left to
+    // ask. `no_runner` is the honest answer: there is no vitest this check can
+    // invoke.
     if (!executable(commandFileOnHost(projectRoot, local)))
         return { status: 'not_checked', reason: 'no_runner' };
-    // `list` is a subcommand only from Vitest 2.1. Older versions read it as a
-    // *filename filter* and go on to run whatever it matches, which was measured
-    // doing two unhelpful things: reporting "No test files found" on a project
-    // that plainly has tests, and — when a file happened to match — starting watch
-    // mode and hanging until the timeout killed it, two minutes for nothing.
-    //
-    // Neither is `broken`, so no healthy project was ever refused. But a check
-    // that quietly answers about the wrong thing is worse than one that says it
-    // did not run, so ask the version first and decline outright when the
-    // subcommand does not exist.
-    // Not `no_runner`: vitest is installed and works, it simply cannot be asked
-    // this question. Telling someone "no runner available" while it sits in their
-    // node_modules sends them to fix the wrong thing.
-    if (!(await supportsList(projectRoot, local, deps))) {
-        return { status: 'not_checked', reason: 'runner_too_old' };
-    }
-    const result = await attempt(deps, local, ['list'], { cwd: projectRoot });
-    return classify(projectRoot, 'vitest', result, (proc) => {
-        if (proc.code === 0)
-            return 'ok';
-        if (/no test files found/i.test(`${proc.stdout}\n${proc.stderr}`))
-            return 'nothing_to_load';
-        return 'broken';
+    return withProbe(projectRoot, {
+        [VITEST_PROBE_FILE]: vitestProbeSource(sourceFiles),
+        [VITEST_BOOT_CONFIG_FILE]: vitestBootConfigSource(projectRoot, VITEST_PROBE_FILE),
+    }, async () => {
+        // `run`, which every version of vitest has. The version probe that used to
+        // stand here existed only for the `list` subcommand, which arrived in 2.1 —
+        // with it goes the `runner_too_old` answer, and with that the case where a
+        // perfectly good runner was declined for its age.
+        const result = await attempt(deps, local, ['run', '--config', VITEST_BOOT_CONFIG_FILE], { cwd: projectRoot });
+        return classify(projectRoot, 'vitest', result, (proc) => {
+            if (proc.code === 0)
+                return 'ok';
+            // Our own probe was not collected. It says nothing about the project's
+            // code, so it must not read as a verdict on it.
+            if (/no test files found/i.test(`${proc.stdout}\n${proc.stderr}`))
+                return 'nothing_to_load';
+            return 'broken';
+        });
     });
 }
-// The first Vitest that has a `list` subcommand. Below this it is a filter.
-const VITEST_LIST_FROM = { major: 2, minor: 1 };
-// `vitest --version` prints e.g. `vitest/1.6.0 darwin-arm64 node-v25.2.1`. A
-// version we cannot read is treated as unsupported: guessing wrong here costs
-// either a silent non-answer or a two-minute hang, and both are worse than
-// saying plainly that the check did not run.
-async function supportsList(projectRoot, binary, deps) {
-    const result = await attempt(deps, binary, ['--version'], { cwd: projectRoot });
-    if (!result || result.code !== 0)
-        return false;
-    const found = /vitest\/(\d+)\.(\d+)/i.exec(`${result.stdout}\n${result.stderr}`);
-    if (!found)
-        return false;
-    const [major, minor] = [Number(found[1]), Number(found[2])];
-    return major > VITEST_LIST_FROM.major || (major === VITEST_LIST_FROM.major && minor >= VITEST_LIST_FROM.minor);
+// The probe: one test that asserts nothing and imports everything the map named.
+//
+// The vitest probe lives beside the generated suite because that is where the
+// suite's own imports will resolve from; `materializeGuardrails` wipes that
+// directory before writing a suite, and by then the probe is long gone.
+const VITEST_PROBE_FILE = `${GUARDRAILS_DIR}/__unitbob_boot.test.mjs`;
+// `test_` first, on purpose: pytest collects a file by that prefix whatever the
+// project's own `python_files` setting says.
+const PYTEST_PROBE_FILE = `${GUARDRAILS_DIR}/test_unitbob_boot.py`;
+// Every file this check puts in somebody's project, written together and removed
+// together whatever happens — the way `worldProbe` treats its own. One of them
+// left behind would be collected by the project's next test run, and changing
+// what that run does is not ours to do.
+//
+// Both stacks go through here, so the write and the removal cannot drift apart
+// on one of them.
+async function withProbe(projectRoot, files, ask) {
+    for (const [relativePath, source] of Object.entries(files)) {
+        const path = join(projectRoot, relativePath);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, source);
+    }
+    try {
+        return await ask();
+    }
+    finally {
+        for (const relativePath of Object.keys(files))
+            rmSync(join(projectRoot, relativePath), { force: true });
+    }
+}
+// Relative from the probe, which sits two levels down (`.unitbob/structural/`).
+// The empty test is not decoration: vitest fails a file that declares none, and
+// `globals: true` in the config we write is what lets it be named without an
+// import (see `writeVitestBootConfig`).
+function vitestProbeSource(sourceFiles) {
+    const imports = sourceFiles.map((file) => `import ${JSON.stringify(`../../${file}`)};`).join('\n');
+    return `// Written by the unitbob connector before the boot check — do not edit.
+${imports}
+
+test('the modules our guardrails import all load', () => {});
+`;
+}
+// Python imports modules, not files, so the probe does the translation itself.
+// The module is registered in `sys.modules` before it is executed, because a
+// module that is not there yet cannot be the target of its own relative
+// imports.
+//
+// This is the one part of spec 38 that no live project has exercised: there was
+// no Python project on the bench. Worth watching on the first Python run.
+function pytestProbeSource(sourceFiles) {
+    return `# Written by the unitbob connector before the boot check — do not edit.
+import importlib.util
+import pathlib
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+TARGETS = ${JSON.stringify(sourceFiles)}
+
+
+def test_the_modules_our_guardrails_import_all_load():
+    for rel in TARGETS:
+        # A path we cannot build a module out of is our resolution falling
+        # short, never this project's code, so it is passed over in silence.
+        # Blaming somebody's application for a name our own map handed us is
+        # the whole mistake this check was rewritten to stop making.
+        if not rel.endswith(".py"):
+            continue
+        name = rel[:-3].replace("/", ".")
+        spec = importlib.util.spec_from_file_location(name, ROOT / rel)
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        spec.loader.exec_module(module)
+`;
 }
 // Runs one command, turning "this binary is not on the machine" into null (the
 // caller decides whether that means `no_runner` or "try the next interpreter")

package/dist/runner/precheck.js

@@ -262,12 +262,19 @@ function vitestPrecheck(projectRoot, deps) {
     const hasVitest = sidecarProvides(projectRoot, 'vitest', deps) ||
         /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
         existsSync(join(projectRoot, 'node_modules', '.bin', 'vitest'));
+    // What the project runs its own tests with is not asked here and is not a
+    // reason to stop (spec 38): we never open those tests, so jest, mocha or
+    // nothing at all is none of our business. The only question is whether there
+    // is a vitest to run *our* guardrails with — and suite-prepare installs one
+    // under `.unitbob/` when there is not, which is why this sentence is not
+    // reached on the build path at all. It stands for `run` and `run-local`,
+    // where nothing has been provisioned yet.
     if (!hasVitest) {
         return {
             ok: false,
-            message: 'JS/TS guardrails require Vitest (Jest is not supported in MVP v2), and vitest was not ' +
-                "found in this project's package.json or node_modules. Offer the user to add it " +
-                '(`npm i -D vitest`); change dependencies only with their consent, then retry.',
+            message: 'Unitbob runs its own guardrails with Vitest, and no vitest was found in this project\'s ' +
+                'package.json or node_modules — nor one installed by Unitbob under `.unitbob/`. Offer the ' +
+                'user to add it (`npm i -D vitest`); change dependencies only with their consent, then retry.',
         };
     }
     return { ok: true };

package/dist/runner/vitest.js

@@ -10,6 +10,62 @@ export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
 // the project has its own config. Connector-owned: never stored in Rails, never
 // part of the suite digest.
 export const VITEST_CONFIG_FILE = join('.unitbob', 'vitest.config.mjs');
+// The boot check's own config (spec 38), kept in a separate file from the one
+// above rather than shared with it. The two answer different questions and are
+// alive at different moments — the run's config names the branch's suite files
+// and is rewritten immediately before every run, so a boot check that reused it
+// would either be overwritten or leave the run pointing at a probe.
+export const VITEST_BOOT_CONFIG_FILE = join('.unitbob', 'vitest.boot.config.mjs');
+// The structural branch's one shared setup file (spec 39). The coordinator
+// writes it before fan-out and owns it afterwards: it holds whatever has to
+// happen before the first import of any file of the branch — environment
+// variables, a TypeScript loader registration, at the very last resort an entry
+// through the project's root module.
+//
+// A fixed name rather than a new protocol field, because the file has to survive
+// the round trip: `materializeGuardrails` wipes this directory and lays the
+// artifact out again, so the file must travel as an ordinary `support_files`
+// entry — and every such entry is otherwise handed to the runner as a test path.
+// One constant here, read by the config builder, by both collectors of test
+// paths, and by `suite-prepare`, is the whole of the agreement. A field would
+// have had to be agreed with the server and both of its version models.
+//
+// One name, one extension. A second one buys nothing: vitest puts every setup
+// file through vite, so `require` is undefined in a `.js` setup file just as it
+// is in a `.ts` one.
+export const STRUCTURAL_SETUP_FILE = '.unitbob/structural/_setup.ts';
+// The project-relative path of that file, or `undefined` when it has not been
+// written yet. Two callers, one question: the config builder asks it to decide
+// whether to name the file in `setupFiles`, and `suite-prepare` asks it to
+// decide whether the boot probe is a scout or a sentry (spec 39, criterion 4).
+// Deliberately the same observable fact for both, rather than a flag — 32-6
+// forbids a mode, and a mode would let the two sides disagree about which run
+// they are in.
+export function setupFileOf(projectRoot) {
+    return existsSync(join(projectRoot, STRUCTURAL_SETUP_FILE)) ? STRUCTURAL_SETUP_FILE : undefined;
+}
+// Whether anything of ours can run before this stack's branch imports its first
+// module. Only vitest, because `setupFiles` is a vitest notion and the builder
+// below is the single place that inserts our file. Kept here, beside the
+// insertion it describes, rather than in the verb that asks: the verb would be
+// stating a fact about a module it does not own, and the two could then drift.
+export function canPrepareBeforeImports(runner) {
+    return runner === 'vitest';
+}
+// The files of an artifact that a runner may be pointed at, which is all of them
+// except the shared setup file. It travels as an ordinary `support_files` entry
+// so that materialization writes it back rather than wiping it, and it holds no
+// cases at all: a runner given it as a test path opens it, finds nothing, and
+// reports that nothing as a suite.
+//
+// One filter for both collectors — the check flow's and run-local's — because
+// the two must never disagree about which file this is. A leading `./` is
+// tolerated: the answer that names the file is hand-written, and two characters
+// must not be what decides whether the branch's preparation is executed or
+// collected.
+export function testPathsOf(paths) {
+    return paths.filter((path) => path.replace(/^\.\//, '') !== STRUCTURAL_SETUP_FILE);
+}
 // The project configs we inherit from, most specific first. Vitest reads a
 // project's own config even when we pass `--config`, so we must merge ours with
 // it rather than replace it (plugins, path aliases and resolve settings the
@@ -79,12 +135,26 @@ export async function runVitestSuite(projectRoot, suitePaths) {
 // 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)));
     const path = join(projectRoot, VITEST_CONFIG_FILE);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, configSource(projectConfig, suitePaths));
+    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run', setupFileOf(projectRoot)));
     return ['--config', VITEST_CONFIG_FILE];
 }
+// The same config, shaped for the boot check's probe (spec 38). Returned as text
+// rather than written, because the boot check owns the lifetime of every file it
+// puts in the project: it writes them together and removes them together, and a
+// writer here would take half of that away from the one place that can see it.
+export function vitestBootConfigSource(projectRoot, probePath) {
+    // The same preparation the run will get, which is the point of asking twice
+    // (spec 39, criterion 4). On the first `suite-prepare` there is no setup file
+    // and the probe answers "these files do not load on their own"; on the second,
+    // after the coordinator wrote one, it answers the question the run will
+    // actually put — and only then is a red answer worth a branch.
+    return configSource(projectConfigOf(projectRoot), [probePath], 'boot', setupFileOf(projectRoot));
+}
+function projectConfigOf(projectRoot) {
+    return PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
+}
 // The .unitbob/ config sits one level below the project root, so the project
 // config is a `../` import. A function-form config is resolved first, and
 // everything the project set — plugins, aliases, setup files, environment — is
@@ -101,21 +171,60 @@ function writeMergedConfig(projectRoot, suitePaths) {
 // 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)}`;
+// `mode` is the boot check's two differences from the run, and they go together:
+// globals on, and a workspace refused. See `vitestBootConfigSource`.
+//
+// `setupFiles` is the one field that is added to rather than replaced (spec 39,
+// criterion 2). The project's own entry is what raises its test database and
+// reads its environment — epic-stack's `tests/setup/setup-test-env.ts` is why
+// its 50 structural checks have a database to read — and replacing it would
+// take that away from the only structural suite on the bench that works. Ours
+// goes first: it exists to set things up before the first import of anything,
+// and the project's own setup file opens with imports of the application.
+function configSource(projectConfig, suitePaths, mode, setupFile) {
+    // After the project's own `test`, never before it: ours has to win.
+    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}${setupFile ? 'setupFiles, ' : ''}include: ${JSON.stringify(suitePaths)}`;
     const header = '// Written by the unitbob connector before each vitest run — do not edit.';
     if (!projectConfig) {
+        // Nothing to inherit, so nothing to concatenate — but the shared file is
+        // still the branch's, and a project with no config of its own is exactly
+        // the kind that needs it.
+        const alone = setupFile ? `const setupFiles = ${JSON.stringify([setupFile])};\n` : '';
         return `${header}
-export default { test: { ${include} } };
+${alone}export default { test: { ${settings} } };
 `;
     }
+    // Globals, because the probe lives in `.unitbob/structural/`: an
+    // `import { test } from 'vitest'` there resolves by walking up from that
+    // directory, which never reaches `.unitbob/runners/node_modules` — where the
+    // vitest we installed for a project that had none is kept. We write this file,
+    // so we turn the globals on and the probe needs no import at all.
+    //
+    // A workspace is dropped for a harder reason. With `test.projects` (or the
+    // older `test.workspace`) set, the root `include` stops deciding anything and
+    // vitest runs each sub-project's own test files — which would open the
+    // project's tests again through the back door, the one thing spec 38 removes.
+    const narrow = mode === 'boot'
+        ? `
+const { projects, workspace, ...test } = base.test ?? {};
+`
+        : `
+const test = base.test ?? {};
+`;
+    // `[].concat(x)` on purpose: vitest accepts `setupFiles` as an array or as a
+    // bare string, and most projects set neither. All three forms arrive here and
+    // all three have to come out an array, because a config that throws while it
+    // is being read takes the whole run with it.
+    const merge = setupFile
+        ? `const setupFiles = ${JSON.stringify([setupFile])}.concat(test.setupFiles ?? []);\n`
+        : '';
     return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
-
-export default { ...base, test: { ...(base.test ?? {}), ${include} } };
+${narrow}${merge}
+export default { ...base, test: { ...test, ${settings} } };
 `;
 }

package/dist/verbs/run.js

@@ -4,7 +4,7 @@ import { placeProblem } from "../runner/place.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
-import { runVitestSuite } from "../runner/vitest.js";
+import { runVitestSuite, testPathsOf } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { enterUrl } from "../links.js";
@@ -147,8 +147,11 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
 // Every file of the branch, in the order the envelope carries them. A structural
 // branch is one file per assignment since spec one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
+//
+// Every file except the branch's shared setup file, which `testPathsOf` drops
+// (spec 39): it is named in `setupFiles` instead of being collected from.
 function artifactPaths(file) {
-    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+    return testPathsOf([file.path, ...(file.support_files ?? []).map((entry) => entry.path)]);
 }
 function suiteError(suiteDigest, message) {
     return {

package/dist/verbs/runLocal.js

@@ -5,6 +5,7 @@ import { placeAdvice } from "../runner/placeAdvice.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { testPathsOf } from "../runner/vitest.js";
 import { runStructuralByRunner } from "./run.js";
 const OUTPUT_TAIL_CHARS = 4000;
 export async function runLocal(config, args = [], deps) {
@@ -259,7 +260,11 @@ function artifactPathsOf(output) {
     const rest = support
         .map((entry) => entry?.path)
         .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
-    return [path, ...rest];
+    // Everything but the branch's shared setup file (spec 39): it is a support
+    // file so that it survives materialization, and it is named in `setupFiles`
+    // rather than handed over as a path to collect tests from. Literally the same
+    // filter the check flow uses, because both sides have to mean the one file.
+    return testPathsOf([path, ...rest]);
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -1,7 +1,7 @@
 import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
-import { PACKETS_DIR, writeSuitePackets } from "../files/packets.js";
+import { PACKETS_DIR, structuralSourceFiles, writeSuitePackets, } from "../files/packets.js";
 import { movePreviousRunAside, recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bddStepLoading } from "../runner/bdd.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
@@ -11,6 +11,7 @@ import { placeProblem } from "../runner/place.js";
 import { alignRunnerEnvironmentWithPlace } from "../runner/placeEnvironment.js";
 import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { canPrepareBeforeImports, setupFileOf, STRUCTURAL_SETUP_FILE } from "../runner/vitest.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -67,7 +68,7 @@ export async function suitePrepare(config, args = [], deps) {
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
         confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
-        bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
+        bootCheck: (projectRoot, runner, sourceFiles) => bootCheck(projectRoot, runner, sourceFiles),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
         ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
         worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
@@ -130,30 +131,10 @@ export async function suitePrepare(config, args = [], deps) {
             throw new ToolchainUnavailableError(ready.message ?? `The ${check.runner} runner is not available.`, config.projectRoot);
         }
     }
-    // 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
-    // command instead of a full generation.
-    //
-    // There is no `--on-broken-boot` flag and no mode. The decision is not a
-    // policy we could reasonably let a user set — it follows from the fact: we
-    // tried to load the thing the suite starts with, it did not load, therefore
-    // not one test would reach its first assertion. Debugging generation against a
-    // knowingly dead project is our problem, not the vibecoder's.
     // The stack the precheck just identified, rather than a second detection of
     // the same thing: on Python that would shell out to pytest all over again.
+    // Used further down, where the boot check now runs.
     const structuralRunner = check.runner ?? null;
-    const boot = await actual.bootCheck(config.projectRoot, structuralRunner);
-    if (boot.status === 'broken') {
-        // "Your environment is not ready" is the one of the two that a container can
-        // answer — the toolchain is missing here and may be sitting in one. A defect
-        // found in the code is a defect wherever it runs, and offering a container
-        // for it would be the noise this spec is trying to remove.
-        throw boot.cause === 'environment_not_ready'
-            ? new ToolchainUnavailableError(bootFinding(boot, structuralRunner), config.projectRoot)
-            : new Error(bootFinding(boot, structuralRunner));
-    }
-    actual.stdout.write(bootFinding(boot, structuralRunner));
     const packets = await actual.getSuitePacketsBatch();
     // Spec 32-1: Zero-touch sidecar provision for behavioral BDD runners during build preflight.
     // A `fixable` outcome (no package manager available to install the runner) is an infrastructure
@@ -227,8 +208,82 @@ export async function suitePrepare(config, args = [], deps) {
         else
             blockedNotices.push(`  ${packet.suite_kind}: ${envelopeBlockedReason(packet, runner)}`);
     }
+    // Spec 32-6, moved down by spec 38. Before anything is written and before a
+    // single token is spent, find out whether the code this branch's guardrails
+    // will import actually loads.
+    //
+    // Here rather than at the top of the verb, because here the list of those
+    // files exists: it is resolved from the branches that were just assembled,
+    // out of this machine's own graph and route inventory. Nothing is lost by
+    // waiting — `getSuitePacketsBatch` is a GET that writes nothing and costs
+    // nothing, and the generator, which is where the money starts, does not run
+    // until `request.json` is written below.
+    //
+    // What is gained is that a failure here takes one branch and not the run. The
+    // behavioral peer has a runner of its own, touches none of these files, and
+    // used to die of a verdict that was never about it.
+    // Only when there is a branch to check. Ruby's helper ignores the file list
+    // and boots the application for itself, so asking with no structural branch in
+    // the run would start Rails to answer a question nobody put — and a `broken`
+    // answer would then report a branch this build never had.
+    //
+    // Spec 39 kept the sentry and moved the sentence. The probe asks its question
+    // twice: once before anything has been prepared for these files, and once
+    // after the coordinator has written the branch's shared setup file. Only the
+    // second answer costs a branch, because only the second one asks what the run
+    // will ask. Before the setup file exists the probe's question — "do these
+    // files load with nothing in front of them" — is stricter than the condition
+    // it stands in for, and `docs/adr/0001` forbids exactly that: the condition
+    // tested must equal the condition that makes a run impossible, never exceed
+    // it. Two bench projects were refused on that excess while their behavioral
+    // peers built and stayed green.
+    //
+    // The switch is the file on disk and nothing else. No flag and no mode: 32-6
+    // forbade them, and the connector has to ask this same question anyway to
+    // decide whether to name the file in `setupFiles`, so a second signal could
+    // only ever disagree with the first.
+    //
+    // And only on the stack where a preparation can actually be put in front of
+    // the imports — `canPrepareBeforeImports`, which is vitest and only vitest. On
+    // rspec and pytest nothing of ours runs before the branch's imports, so there
+    // the probe's question already *is* the run's question: no excess to correct,
+    // and a red answer costs the branch on the first run exactly as it has since
+    // 32-6. Waiting for a file those stacks will never have would have quietly
+    // reopened the funnel that spec closed.
+    //
+    // One thing this sign cannot see: a setup file left over from an earlier
+    // build. It comes back with the artifact and is materialized like any other
+    // file of the branch, so on a re-generation the probe sentences on its first
+    // ask instead of scouting. That is the honest reading — a preparation does
+    // exist and the probe went through it — and the way out is the same one the
+    // verdict already names: fix that file, run `suite-prepare` again. Telling the
+    // two apart would need a memory of which build wrote it, which is a mode by
+    // another name, and 32-6 forbade those.
+    const bootNotices = [];
+    const bootAdvisories = [];
+    const structuralIndex = branches.findIndex((branch) => branch.suite_kind === 'structural');
+    if (structuralIndex !== -1) {
+        const boot = await actual.bootCheck(config.projectRoot, structuralRunner, structuralSourceFiles(config.projectRoot, { branches }));
+        if (boot.status === 'broken') {
+            if (!canPrepareBeforeImports(structuralRunner) || setupFileOf(config.projectRoot)) {
+                branches.splice(structuralIndex, 1);
+                bootNotices.push(bootStop(boot, structuralRunner));
+            }
+            else {
+                bootAdvisories.push(bootAdvisory(boot, structuralRunner));
+            }
+        }
+        else {
+            actual.stdout.write(bootFinding(boot, structuralRunner));
+        }
+    }
+    // Every reason a branch is not here, in one place. A run can lose its last
+    // branch to any of the three and the reader needs the one that applies to
+    // them — printing only the envelope reasons left a jest project reading an
+    // empty list under "no suite branch can be built".
     if (branches.length === 0) {
-        throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\nNothing was written and nothing was uploaded.`);
+        const why = [...bootNotices, ...blockedNotices, ...fixableNotices].join('\n');
+        throw new Error(`No suite branch can be built this run:\n${why}\nNothing was written and nothing was uploaded.`);
     }
     const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
     // Spec 37-1. The assignment names entrypoints; the packets are the files
@@ -306,6 +361,27 @@ export async function suitePrepare(config, args = [], deps) {
                 'finds its step files — it has no strategy of that name. Nothing here tells you what to call ' +
                 'them, and this connector will not be able to run the branch either.\n');
     }
+    // Same shape as the two notices below it, and the same rule: the branch that
+    // could not be prepared drops out, its peer is untouched, and the reason is
+    // printed rather than swallowed.
+    if (bootNotices.length > 0) {
+        actual.stdout.write('\nThe code-structure suite was left out of this run — the source files its guardrails would ' +
+            'import did not load. None of your own tests were opened; only the files the map named:\n' +
+            bootNotices.join('\n') +
+            '\n');
+    }
+    // The other half of the probe's answer (spec 39), and it needs a heading of
+    // its own: "was left out of this run" is true only of the verdict, and this
+    // branch was not left out of anything. It is being built, and what follows is
+    // the opening fact for whoever writes its preparation.
+    if (bootAdvisories.length > 0) {
+        actual.stdout.write('\nThe code-structure suite is still being built, and here is what its source files did on their own: ' +
+            `they did not load. Nothing has been put in front of them yet — that is what ${STRUCTURAL_SETUP_FILE} ` +
+            'is for, and writing it comes before the fan-out. None of your own tests were opened; only the files ' +
+            'the map named:\n' +
+            bootAdvisories.join('\n') +
+            '\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) {
@@ -382,62 +458,88 @@ function stepLoadingNotice(runner, loading) {
         loading.requirements.join('\n  - ') +
         '\nThis is also in `request.json`, on the behavioral branch, as `step_loading`.\n');
 }
-// What the boot check found, in the vibecoder's terms. Printed on every run,
-// including the quiet ones: "we looked and it starts" and "we could not look"
-// are both worth a line, and a check nobody hears about is a check nobody
-// trusts.
+// What the boot check found when it found nothing wrong, in the vibecoder's
+// terms. Printed on every such run, including the quiet ones: "we looked and it
+// starts" and "we could not look" are both worth a line, and a check nobody
+// hears about is a check nobody trusts.
 //
-// A stop here is a finding, not a refusal, and the wording has to carry that.
-// "We found the defect that stops your suite from starting" and "we could not
-// build your suite" describe the same event and leave the reader in completely
-// different places.
+// The third answer, `broken`, is the only one that changes what gets built, so
+// it goes to `bootStop` and is printed where every other missing branch is
+// explained.
 function bootFinding(boot, runner) {
-    // Both halves of "what this answer is worth" travel together, on every
-    // outcome. Splitting them is how the stack caveat came to be missing from
-    // `broken`, and pinning `STRUCTURAL_ONLY` to `ok` alone would have repeated
-    // that in the same breath as the fix: on Rails the stack caveat reads
-    // "whatever stops one stops the other", which is an unscoped claim about a
-    // branch nobody asked — loudest exactly where the run stops for both.
-    // Empties are dropped rather than joined blindly, so a runner with no caveat
-    // of its own does not leave a blank line behind.
-    const caveat = [runner ? SIGNAL_STRENGTH[runner] : '', runner ? STRUCTURAL_ONLY : '']
-        .filter(Boolean)
-        .map((line) => `\n${line}`)
-        .join('');
+    const caveat = caveatFor(runner);
     if (boot.status === 'ok') {
         return `Checked that the suite can start: it does.${caveat}\n`;
     }
-    if (boot.status === 'not_checked') {
-        // Not checked is not broken, and nothing downstream may treat it as such.
-        // Conflating the two would block honest projects — the whole reason this
-        // state is named for what happened rather than for what we know.
-        const said = boot.detail ? `\n\n  ${boot.detail}\n` : '';
-        return `${NOT_CHECKED_REASON[boot.reason]}${said} Generation continues.${caveat}\n`;
-    }
-    const headline = boot.cause === 'defect_in_code'
-        ? 'Found a defect that stops your test suite from starting.'
-        : 'Your test suite cannot start yet — its environment is not ready.';
-    // The runner's own words. Everything else on screen is ours; this line is
-    // 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 installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+    // Not checked is not broken, and nothing downstream may treat it as such.
+    // Conflating the two would block honest projects — the whole reason this
+    // state is named for what happened rather than for what we know.
+    //
+    // `broken` cannot arrive here: it is the one answer that changes what gets
+    // built, so it goes to `bootStop` and is printed as the reason a branch is
+    // missing.
+    const said = boot.detail ? `\n\n  ${boot.detail}\n` : '';
+    return `${NOT_CHECKED_REASON[boot.reason]}${said} Generation continues.${caveat}\n`;
+}
+// Why the code-structure branch is not in this run. One indented block, the same
+// shape as every other missing-branch reason, because that is now what this is:
+// its peer carries on, `request.json` is written, and the vibecoder comes away
+// with the guardrails that branch can still give rather than with nothing.
+//
+// Reached only once the branch's shared setup file exists (spec 39). By then the
+// probe has been asked through that preparation, so a red answer is the run's
+// own answer and taking the branch is honest.
+function bootStop(boot, runner) {
+    return bootReport(boot, runner, true);
+}
+// The same red answer, read before anything was prepared for these files (spec
+// 39). Same facts, same words from the runner, same caveat — what differs is
+// the step that follows, and that is the whole difference between a scout and a
+// sentry. Nothing here is worded as a verdict on somebody's code, because on
+// this run it is not one: the files were asked to load with nothing in front of
+// them, and putting something in front of them is Unitbob's own work.
+function bootAdvisory(boot, runner) {
+    return bootReport(boot, runner, false);
+}
+// The two causes keep their separate next steps. An un-run `pip install` is not
+// somebody's bug and must not be worded as one; a module of theirs that raises
+// on import, asked with the preparation already in place, is theirs to fix and
+// pointing at an install would waste their time.
+//
+// The environment cause keeps the same next step in both reports: a missing gem
+// is not something a setup file can prepare its way around, and sending someone
+// to write one would waste the round it costs.
+function bootReport(boot, runner, prepared) {
+    const next = boot.cause !== 'defect_in_code'
+        ? '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` +
-        'No suite was written and nothing was uploaded — every test would have died on that line ' +
-        // The caveat belongs here most of all, and this was the one branch it did
-        // not reach — found on the fifth implementation review, 2026-08-03. On
-        // pytest and vitest the check collects the project's whole test tree, so
-        // the line above may come from a test of the project's own that the Unitbob
-        // suite would never have imported. Printing "found a defect" and keeping
-        // that back sends someone to fix a file this product was never going to
-        // touch, which is the same over-claim the spec accepted the wide check only
-        // on condition of disclosing.
-        `before reaching its first assertion. ${next}${caveat}\n`);
+            'then run `unitbob suite-prepare` again.'
+        : prepared
+            ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
+            : `This is what these files do with nothing in front of them, and the run will have ` +
+                `${STRUCTURAL_SETUP_FILE} in front of them. Put into that file whatever has to happen before the ` +
+                'first import — the environment variables the modules read, a loader registration, and only as a ' +
+                'last resort an entry through the project\'s root module — then run `unitbob suite-prepare` again ' +
+                'and this same question will be asked through it.';
+    // `boot.message` is the runner's own words, indented but never paraphrased:
+    // this is the line the vibecoder can paste into a search.
+    return `  ${boot.message}\n\n${boot.detail}\n\n  ${next}${caveatFor(runner, '  ')}\n`;
+}
+// What this answer is worth, in two halves that always travel together: how much
+// this stack's check can see, and the fact that it speaks for one branch only.
+// Splitting them is how the stack caveat came to be missing from the outcome
+// that costs a branch — found on the fifth implementation review, 2026-08-03 —
+// so there is one builder and every caller goes through it. `indent` sets how
+// the lines sit, and is the only thing a caller may vary.
+//
+// Empties are dropped rather than joined blindly, so a runner with no caveat of
+// its own does not leave a blank line behind.
+function caveatFor(runner, indent = '') {
+    return [runner ? SIGNAL_STRENGTH[runner] : '', runner ? STRUCTURAL_ONLY : '']
+        .filter(Boolean)
+        .map((line) => `\n${indent}${line}`)
+        .join('');
 }
 // Spec 32-6 says the boot rule is one rule for both branches; this check asks
 // one of them. It is made against the *structural* runner, which is what
@@ -456,12 +558,7 @@ const STRUCTURAL_ONLY = 'This says nothing about the product-behaviour branch: i
     'which has nothing of ours to load until its suite exists, so it was not asked.';
 const NOT_CHECKED_REASON = {
     no_runner: 'Did not check whether the suite can start: no runner available to load it with.',
-    // Distinct from `no_runner` on purpose. The runner is installed and working;
-    // it is only too old to be asked this particular question, and "no runner
-    // available" would send someone to fix a thing that is not broken.
-    runner_too_old: 'Did not check whether the suite can start: the installed runner is too old to be asked. ' +
-        'Nothing is wrong with it — this check simply has no way to pose the question to that version.',
-    // Distinct for the same reason, one step further along: the runner is there
+    // Distinct from `no_runner` on purpose: the runner is there
     // and current, it was reached, and it declined to answer — pytest exiting on
     // a usage or internal error of its own. That says nothing about the project,
     // and "no runner available" would again send someone after the wrong thing.

package/package.json

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

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.7.2 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.4 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded