unitbob 0.5.1 → 0.6.0

package/dist/runner/vitest.js

@@ -1,9 +1,9 @@
 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 { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { locateRunner } from "./toolchain.js";
-import { readReport } from "./types.js";
+import { clearReport, readFreshReport } from "./types.js";
 export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
 // A connector-owned Vitest config, written next to .unitbob/ before a run when
@@ -37,7 +37,7 @@ const PROJECT_CONFIGS = [
 // 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
+// Named files rather than a directory glob, since spec 43, §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
@@ -63,17 +63,16 @@ export async function runVitestSuite(projectRoot, suitePaths) {
         '--reporter=json',
         `--outputFile=${VITEST_RESULT_FILE}`,
     ];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const reportPath = join(projectRoot, VITEST_RESULT_FILE);
+    const survivor = clearReport(reportPath);
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: VITEST_TIMEOUT_MS,
-        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...located?.env, UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: VITEST_RESULT_FILE,
-        report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
+        report: readFreshReport(reportPath, survivor),
     };
 }
 // Returns the `--config` args to add, writing the config first. Always written:

package/dist/runner/worldProbe.js

@@ -1,36 +1,35 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
 import { BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
+import { BEHAVIORAL_GEMFILE } from "./bdd.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
 const PROBE_ROOT = '.unitbob/suite-build/world-probe';
 export async function probeBehavioralWorld(projectRoot, deps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        env: options.env,
-        timeoutMs: PROVISION_TIMEOUT_MS,
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: PROVISION_TIMEOUT_MS }),
 }) {
+    // Written on the host, named to the run relative to the project root — the
+    // same shape `bdd.ts` has always had, and the reason nothing here needs a path
+    // rewritten when the run happens somewhere else (spec 36, §4.2).
+    const feature = `${PROBE_ROOT}/world.feature`;
+    const steps = `${PROBE_ROOT}/world_steps.rb`;
     const probeRoot = join(projectRoot, PROBE_ROOT);
-    const feature = join(probeRoot, 'world.feature');
-    const steps = join(probeRoot, 'world_steps.rb');
     mkdirSync(probeRoot, { recursive: true });
-    writeFileSync(feature, PROBE_FEATURE);
-    writeFileSync(steps, PROBE_STEPS);
+    writeFileSync(join(projectRoot, feature), PROBE_FEATURE);
+    writeFileSync(join(projectRoot, steps), PROBE_STEPS);
     try {
         const result = await deps.runCmd('bundle', [
             'exec', 'cucumber', feature,
-            '--require', join(projectRoot, BEHAVIORAL_WORLD_PATH),
+            '--require', BEHAVIORAL_WORLD_PATH,
             '--require', steps,
             '--format', 'progress',
         ], {
             cwd: projectRoot,
             env: {
-                ...process.env,
                 RAILS_ENV: 'test',
                 CUCUMBER_PUBLISH_QUIET: 'true',
-                UNITBOB_REPO_ROOT: projectRoot,
-                BUNDLE_GEMFILE: join(projectRoot, '.unitbob', 'behavioral', 'Gemfile'),
+                UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+                BUNDLE_GEMFILE: BEHAVIORAL_GEMFILE,
             },
         });
         if (result.code === 0)
@@ -52,6 +51,9 @@ const PROBE_FEATURE = `Feature: Unitbob World profile
 
   Scenario: supported state is clean at the next scenario boundary
     Then the second World probe scenario sees clean state and fresh mocks
+
+  Scenario: outgoing HTTP does not leave the machine
+    Then the World probe cannot reach the network
 `;
 const PROBE_STEPS = `PROBE_VERSION = "unitbob-world-probe-#{Process.pid}"
 PROBE_TIME_ZONE = Time.zone
@@ -84,6 +86,16 @@ Then('its integration assertion counter advances') do
   expect(unitbob_session.assertions).to be > 0
 end
 
+# Spec 35-1, criterion 2. Checked here rather than trusted, because the failure
+# it guards against is invisible from inside: a suite whose WebMock never came on
+# passes exactly the same way, and only the other end of the wire ever finds out.
+Then('the World probe cannot reach the network') do
+  require 'net/http'
+  expect {
+    Net::HTTP.get(URI('http://unitbob-world-probe.invalid/'))
+  }.to raise_error(WebMock::NetConnectNotAllowedError)
+end
+
 Then('the second World probe scenario sees clean state and fresh mocks') do
   quoted = @unitbob_connection.quote(PROBE_VERSION)
   count = @unitbob_connection.select_value("SELECT COUNT(*) FROM schema_migrations WHERE version = #{quoted}").to_i

package/dist/surfaces/routeInventory.js

@@ -1,18 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { runProcess } from "../proc.js";
+import { executable } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
+import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.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.
 const ROUTES_TIMEOUT_MS = 120_000;
+// The router is the application's own, so asking it is a project command and
+// goes where the project's dependencies live (spec 36, §5). Unlike every other
+// caller this one is allowed to fail: silence is already a normal answer here,
+// so a project whose container is misconfigured loses its route inventory and
+// nothing else.
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        timeoutMs: ROUTES_TIMEOUT_MS,
-        env: { ...process.env, ...options.env },
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: ROUTES_TIMEOUT_MS, env: options.env }),
 };
 export function routeInventoryPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'map-build', 'route_inventory.json');
@@ -202,16 +204,16 @@ end`;
 // `default` means we leave RAILS_ENV alone and take whatever the project's own
 // setup chooses.
 async function askRouterOnce(projectRoot, deps, environment) {
-    const local = join(projectRoot, 'bin', 'rails');
-    const [command, args] = existsSync(local)
-        ? [local, ['runner', ROUTES_SCRIPT]]
+    const [command, args] = executable(join(projectRoot, 'bin', 'rails'))
+        ? ['bin/rails', ['runner', ROUTES_SCRIPT]]
         : ['bundle', ['exec', 'rails', 'runner', ROUTES_SCRIPT]];
+    const repoRoot = projectRootAsSeenByThePlace(projectRoot);
     try {
         return await deps.runCmd(command, args, {
             cwd: projectRoot,
             env: environment === 'test'
-                ? { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot }
-                : { UNITBOB_REPO_ROOT: projectRoot },
+                ? { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: repoRoot }
+                : { UNITBOB_REPO_ROOT: repoRoot },
         });
     }
     catch {
@@ -415,7 +417,7 @@ export function inventoryProblems(inventory, surfaces) {
 // either printed by the router or copied out of the graph. A blank is not a gap
 // to be helpfully filled — an invented `source_file` is the same failure as an
 // invented address, one field over, and a `handler_symbol` swapped for another
-// node that happens to exist passes the host's check while sending spec 36's
+// node that happens to exist passes the host's check while sending spec 38's
 // trace into the wrong code.
 const LINK_FIELDS = ['source_file', 'handler_symbol'];
 // Not a link and nothing downstream reads it — but spec 32-7 took the authoring

package/dist/verbs/codexInstall.js

@@ -18,7 +18,7 @@ const LABEL = {
 // This used to refuse when an installed file differed from the bundled one, to
 // protect a definition the user had edited by hand. The case it actually met was
 // the ordinary one: an upgrade from an older release, where every file differs
-// and every install therefore failed. Spec 43, §1.6.
+// and every install therefore failed. Spec 44, §1.6.
 //
 // The refusal became actively harmful once the workflows started asking a role
 // whether this session can see it. A stale role answers that question exactly

package/dist/verbs/mapPrepare.js

@@ -1,4 +1,4 @@
-import { ensureUnitbobIgnored, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
+import { ensureUnitbobIgnored, ignoreExclusions, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
 import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
 import { Wire } from "../wire.js";
@@ -10,9 +10,20 @@ export async function mapPrepare(config, _args = [], deps) {
         runGraphifyExtractKeyless,
         extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
+        stdout: process.stdout,
         ...deps,
     };
     actual.ensureUnitbobIgnored(config.projectRoot);
+    // Said before the graph is built, because after it there is nothing left to
+    // see: whatever these patterns matched never becomes a node, and a subsystem
+    // that is missing from the map looks exactly like a subsystem that was never
+    // written. One line per pattern that actually took something; a pattern that
+    // matched nothing is not news (spec 35-1, criterion 1).
+    const exclusions = ignoreExclusions(config.projectRoot);
+    if (exclusions.length > 0) {
+        actual.stdout.write('Kept out of the graph by .graphifyignore — nothing below can appear on the map:\n' +
+            exclusions.map((entry) => `  ${entry.pattern} — ${entry.files} file${entry.files === 1 ? '' : 's'}\n`).join(''));
+    }
     await actual.requireGraphify();
     // Keyless: refresh the one canonical graph in place. No inference secret and no
     // graph flags — semantic enrichment is host-LLM work, not a keyed LLM here.
@@ -31,7 +42,7 @@ export async function mapPrepare(config, _args = [], deps) {
     // Said out loud first, because asking a router means booting the application
     // and that can take a minute or two with nothing on the screen. Silence from
     // us there reads as a hang.
-    process.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
+    actual.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
     const inventory = await actual.extractRouteInventory(config.projectRoot);
     const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
         actual.getRecipe('decompose'),
@@ -45,9 +56,9 @@ export async function mapPrepare(config, _args = [], deps) {
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
     }, inventory.status === 'written' ? inventory.path : undefined);
-    process.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
-    process.stdout.write(`${describeRouteInventory(inventory)}\n`);
-    process.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
+    actual.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
+    actual.stdout.write(`${describeRouteInventory(inventory)}\n`);
+    actual.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
         `${packet.output_path} (recipes.decompose, recipes.relate), and the surface map at ` +
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
         'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');

package/dist/verbs/putSuiteBuild.js

@@ -1,4 +1,5 @@
 import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { placeProblem } from "../runner/place.js";
 import { collectBuildProblems } from "./validateBuild.js";
 import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.js";
 import { Wire } from "../wire.js";
@@ -20,6 +21,12 @@ import { Wire } from "../wire.js";
 // 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) {
+    // Spec 36, criterion 7. Publishing is followed immediately by a first run, so
+    // a place that cannot be used is not something to discover after the suite is
+    // stored on the server.
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was uploaded.`);
     const request = readSuiteBuildRequest(config.projectRoot);
     // Spec 32-6: read branch by branch, so one unreadable entry neither hides the
     // next branch's problems nor sinks a peer that is finished and correct.
@@ -39,7 +46,7 @@ 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
+    // Since spec 43 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
@@ -122,7 +129,7 @@ function printResult(result) {
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
     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
+// Spec 43, §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

package/dist/verbs/run.js

@@ -1,5 +1,7 @@
 import { materializeGuardrails } from "../files/guardrails.js";
 import { materializeBehavioral } from "../files/behavioral.js";
+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";
@@ -28,7 +30,7 @@ function resolve(config, deps) {
         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
+        // since spec 43, §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,
@@ -44,6 +46,12 @@ function resolve(config, deps) {
     };
 }
 async function execute(config, d, only) {
+    // Spec 36, criterion 7. Before the first suite is fetched: a run that cannot
+    // happen where this project's dependencies live has nothing honest to file,
+    // and the whole batch would go up as suite errors describing the wrong thing.
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was run and no results were filed.`);
     const suites = await d.getSuites();
     const ready = suites.filter((item) => item.status === 'ready');
     const selected = only === null ? ready : select(ready, only);
@@ -137,7 +145,7 @@ 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 42, §6, and running only the main
+// branch is one file per assignment since spec 43, §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)];

package/dist/verbs/runLocal.js

@@ -1,5 +1,8 @@
 import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { digestOf, failureSet, readRunState, rememberFailures } from "../runner/failureDigest.js";
+import { placeProblem } from "../runner/place.js";
+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 { runStructuralByRunner } from "./run.js";
@@ -12,6 +15,13 @@ export async function runLocal(config, args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
+    // Spec 36, criteria 7 and 6. A run that cannot reach the place its
+    // dependencies live in has nothing to report but noise — and neither has one
+    // whose runner was installed somewhere else, which looks ready because
+    // readiness here is a file existing.
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
     const request = readSuiteBuildRequest(config.projectRoot);
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const wanted = selectBranches(request, args);
@@ -124,7 +134,12 @@ async function runOneBranch(config, d, suiteKind, output) {
                 : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
-        d.stdout.write(`The runner could not start: ${err.message}\n`);
+        // The second and last dead end (spec 36, §7.1). This one does not throw —
+        // it prints and returns zero, so it never reaches the one `catch` that adds
+        // this advice everywhere else. And it is the case that matters most: the
+        // suite exists by now, and the person is trying to run it.
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
         return null;
     }
     d.stdout.write(report(result));
@@ -163,7 +178,7 @@ function outputTail(result) {
 }
 // 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
+// stopped being the whole suite in spec 43, §6 — a branch is one file per
 // assignment now — and running it alone would exercise a fraction of what the
 // answer claims to guard.
 //

package/dist/verbs/suitePrepare.js

@@ -4,9 +4,12 @@ import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bddStepLoading } from "../runner/bdd.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
-import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
+import { anyStackPrecheck, behavioralHarnessNotice, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck, } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
+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 { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -71,9 +74,30 @@ export async function suitePrepare(config, args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
+    // Spec 36, criterion 7. Before the first byte is written and long before the
+    // first call to the server: a place that cannot be used is a fact we can learn
+    // now, and learning it after a suite has been generated and run means the
+    // evidence disappeared with the container.
+    //
+    // Not a `ToolchainUnavailableError`: the place is named in the config and the
+    // message below already says what to do about it. Suggesting a container to
+    // somebody whose container is the problem is noise.
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was written and nothing was uploaded.`);
     const check = actual.precheck(config.projectRoot);
+    // Deliberately a plain stop. This one says "none of the three stacks is here",
+    // which is read off files — a Gemfile, a package.json, a requirements.txt —
+    // and those are on this machine whatever place the run happens in. A container
+    // is never the answer to it.
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
+    // An environment installed somewhere else is not an environment (spec 36, §6).
+    // Here, where it can be built again, and before anything asks whether a runner
+    // is ready.
+    const replaced = alignRunnerEnvironmentWithPlace(config.projectRoot);
+    if (replaced)
+        actual.stdout.write(`${replaced}\n`);
     // 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
@@ -93,16 +117,17 @@ export async function suitePrepare(config, args = [], deps) {
         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.`);
+            throw new ToolchainUnavailableError(`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.`, config.projectRoot);
         }
         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.`);
+        if (!ready.ok) {
+            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
@@ -118,8 +143,15 @@ export async function suitePrepare(config, args = [], deps) {
     // the same thing: on Python that would shell out to pytest all over again.
     const structuralRunner = check.runner ?? null;
     const boot = await actual.bootCheck(config.projectRoot, structuralRunner);
-    if (boot.status === 'broken')
-        throw new Error(bootFinding(boot, 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.
@@ -140,8 +172,14 @@ export async function suitePrepare(config, args = [], deps) {
                 fixableNotices.push(`  Behavioral runner "${runner}" not installed: ${prov.message ?? ''}${steps}`);
                 continue;
             }
+            // Every BDD runner with a connector-owned harness gets it here, before its
+            // branch is offered to the host (spec 35-1). Only Ruby is probed by
+            // running it: the Ruby World integrates deeply with Rails, and the probe
+            // needs an application to integrate with. The JS and Python harnesses do
+            // one thing — refuse connections that leave the machine — and their
+            // guards are executed for real in the connector's own suite.
+            materializeBehavioralWorld(config.projectRoot, runner);
             if (runner === 'cucumber') {
-                materializeBehavioralWorld(config.projectRoot);
                 const probe = await actual.worldProbe(config.projectRoot);
                 if (probe.status === 'fixable') {
                     fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
@@ -157,7 +195,7 @@ export async function suitePrepare(config, args = [], deps) {
         const manifest = actual.runnerEnvelope(packet, runner, config.projectRoot);
         if (!manifest)
             return { packet, runner, branch: null };
-        // Spec 43, §3.2. The rule for which step files this runner loads travels
+        // Spec 44, §3.2. The rule for which step files this runner loads travels
         // with the branch that will be written against it, so nobody has to read
         // the connector's own source to find it out — which is exactly what two
         // coordinators did.
@@ -213,6 +251,12 @@ export async function suitePrepare(config, args = [], deps) {
     for (const { packet, runner, branch } of prepared) {
         if (!branch || packet.suite_kind !== 'behavioral' || !runner)
             continue;
+        // Before the steps are written, not after they misbehave: what this runner
+        // does and does not load is the fact a worker needs while deciding what a
+        // step may assume (spec 35-1, criterion 2).
+        const harness = behavioralHarnessNotice(runner);
+        if (harness)
+            actual.stdout.write(harness);
         actual.stdout.write(branch.step_loading
             ? stepLoadingNotice(runner, branch.step_loading)
             // Said rather than left blank. This connector has no strategy for that
@@ -245,7 +289,7 @@ export async function suitePrepare(config, args = [], deps) {
     }
 }
 // The runner's own rule for which step files it will load, in the words of the
-// side that loads them (spec 43, §3.2). The same object is in `request.json`, on
+// side that loads them (spec 44, §3.2). The same object is in `request.json`, on
 // the behavioral branch; this is the copy the coordinator sees without opening a
 // file.
 //
@@ -291,7 +335,8 @@ function bootFinding(boot, runner) {
         // 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.
-        return `${NOT_CHECKED_REASON[boot.reason]} Generation continues.${caveat}\n`;
+        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.'
@@ -348,6 +393,12 @@ const NOT_CHECKED_REASON = {
         'stopped on an error of its own before loading anything. Nothing was learned about your code either way.',
     timed_out: 'Did not check whether the suite can start: loading it took too long and was stopped.',
     nothing_to_load: 'Did not check whether the suite can start: there was nothing to load yet.',
+    // Spec 36, criterion 8. Docker refused, or the container went away between the
+    // check and the spawn. Nothing here says anything about the project, and the
+    // one thing this must never turn into is "we found a defect in your code".
+    place_failed: 'Did not check whether the suite can start: the place this project runs in did not carry the command ' +
+        'out. That is a fault of the container or the docker daemon, not of your code, and nothing was learned ' +
+        'about your code either way.',
 };
 function knownDefectContext(args) {
     const defect = option(args, '--known-defect=');

package/dist/verbs/suiteReviewPrepare.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBehavioral, } from "../files/behavioral.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
+import { placeOf } from "../runner/place.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
@@ -54,6 +55,19 @@ async function runCandidateInProject(projectRoot, output, revision) {
     return { revision, run_result: report };
 }
 async function runCandidateAtRevision(projectRoot, output, revision) {
+    // Spec 36, Non-Goals. The worktree below is created under the system's
+    // temporary directory — outside anything a container has mounted, so in there
+    // it does not exist at all. Said plainly rather than run into. The obvious
+    // repair, moving the worktree under `.unitbob/`, puts a whole second copy of
+    // the application inside the tree graphify scans, and a copy left behind by a
+    // failure builds the next map out of two applications.
+    const place = placeOf(projectRoot);
+    if (place.kind === 'docker') {
+        throw new Error("Reviewing at a fixed revision is not supported while this project's tests run inside a container " +
+            `(\`${place.container}\`): the review needs a git worktree outside the project, which the container ` +
+            'cannot see. Review against the working tree instead (drop the fixed revision), or run this project ' +
+            'on this machine.');
+    }
     const resolved = execFileSync('git', ['rev-parse', '--verify', revision], {
         cwd: projectRoot,
         encoding: 'utf8',

package/dist/wire.js

@@ -86,7 +86,7 @@ export class Wire {
     // carries one result per suite_kind.
     //
     // `dryRun` is the same route, the same body and the same server-side
-    // validation, stopped before the first write (spec 42, §1). It answers
+    // validation, stopped before the first write (spec 43, §1). It answers
     // `would_publish` instead of `created`, and it is deliberately not a route of
     // its own: a second route would grow a second implementation, which is the
     // defect this whole spec removes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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.5.1 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.6.0 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