unitbob 0.5.1 → 0.6.0

package/dist/runner/placeEnvironment.js

@@ -0,0 +1,111 @@
+// An installed environment belongs to the place that installed it (spec 36, §6).
+//
+// The invariant "files on the host, processes where the dependencies live" is
+// true of text and false of installed packages. `.unitbob/runners/.venv` and
+// `.unitbob/behavioral/node_modules` sit under the project, which is to say
+// inside the mounted folder, which is to say both sides can see them — and they
+// were built for one operating system. A virtualenv built on macOS is not a
+// virtualenv inside a Linux container, however plainly it is there.
+//
+// And the connector cannot tell by looking: readiness is decided by a file being
+// on disk (`provision.ts`, `existsSync(venvPython)`), never by starting it. So
+// the main scenario of this whole spec ends badly without the mark below —
+// somebody hits the wall on this machine (a `.venv` gets created), reads the
+// hint, adds `exec`, runs again, and inside the container the macOS interpreter
+// is taken for a finished environment. What follows is `pip` failing to start,
+// its stderr discarded, and the advice to run a command that cannot run either.
+//
+// The cure is one mark, not a directory scheme per place: cheap to write, and
+// nothing else in the tree has to know about it.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BEHAVIORAL_DIR, RUNNER_ENVIRONMENT_ENTRIES } from "../files/behavioral.js";
+import { describePlaceId, placeId, placeOf } from "./place.js";
+import { SIDECAR_DIR } from "./toolchain.js";
+const PLACE_FILE = '.unitbob/.place';
+// Throw away any runner environment that was built somewhere else, and record
+// where this one is being built. Returns a line worth printing when something
+// was actually removed, and null when nothing was.
+//
+// Called where an environment can be built again — `suite-prepare` — and
+// nowhere else. Clearing it anywhere else would leave a run with no runner and
+// no way to get one.
+export function alignRunnerEnvironmentWithPlace(projectRoot) {
+    const current = placeId(placeOf(projectRoot));
+    const marked = readMark(projectRoot);
+    if (marked === current)
+        return null;
+    // A project that has never been marked was provisioned before this existed,
+    // which means it was provisioned on this machine. Saying so out loud is what
+    // makes "the mark is missing" a fact rather than a mystery.
+    const previous = marked ?? 'local';
+    const removed = previous === current ? [] : removeRunnerEnvironment(projectRoot);
+    writeMark(projectRoot, current);
+    if (removed.length === 0)
+        return null;
+    return (`The test runner installed under \`.unitbob/\` was built for ${describePlaceId(previous)}, and this run ` +
+        `happens in ${describePlaceId(current)}. An installed package is not portable between the two, so it was ` +
+        `removed and will be installed again here (${removed.join(', ')}). Your generated suite was not touched.`);
+}
+// The same question, asked by a command that cannot install anything — `check`
+// and `run-local`. It refuses instead of clearing: throwing the environment away
+// here would leave the run with no runner and no way to get one, which is a
+// worse answer than naming the one command that fixes it.
+//
+// Criterion 6 is about not *accepting* a foreign environment as ready, and this
+// is the half of it that lives outside `suite-prepare`. Without it, adding
+// `exec` to a project whose suite already exists and running `check` starts a
+// macOS interpreter inside a Linux container and reports whatever comes out.
+export function runnerEnvironmentPlaceProblem(projectRoot) {
+    const current = placeId(placeOf(projectRoot));
+    const previous = readMark(projectRoot) ?? 'local';
+    if (previous === current)
+        return null;
+    // Nothing installed, nothing stale. A project whose runner has never been
+    // built has an honest reason to be here — `check` on a fresh checkout — and
+    // the missing runner is reported by the runner, in its own words.
+    const installed = installedRunnerEnvironment(projectRoot);
+    if (installed.length === 0)
+        return null;
+    return (`The test runner installed under \`.unitbob/\` was built for ${describePlaceId(previous)}, and this run ` +
+        `happens in ${describePlaceId(current)} (${installed.join(', ')}). An installed package is not portable ` +
+        'between the two, and this command installs nothing. Run `unitbob suite-prepare` to build the runner ' +
+        'where the run now happens, then try this again.');
+}
+function readMark(projectRoot) {
+    try {
+        const mark = readFileSync(join(projectRoot, PLACE_FILE), 'utf8').trim();
+        return mark.length > 0 ? mark : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMark(projectRoot, id) {
+    mkdirSync(join(projectRoot, '.unitbob'), { recursive: true });
+    writeFileSync(join(projectRoot, PLACE_FILE), `${id}\n`);
+}
+// The structural sidecar whole, and from the behavioral root only the entries
+// that are an installed environment. That list already exists and already means
+// exactly "this was installed, it is not generated text", so the suite the host
+// wrote survives.
+//
+// One list, read by both the command that clears and the command that only
+// complains, so the two can never disagree about what an installed environment
+// is.
+function installedRunnerEnvironment(projectRoot) {
+    const found = [];
+    if (existsSync(join(projectRoot, SIDECAR_DIR)))
+        found.push(`${SIDECAR_DIR}/`);
+    for (const entry of new Set(Object.values(RUNNER_ENVIRONMENT_ENTRIES).flatMap((set) => [...set]))) {
+        if (existsSync(join(projectRoot, BEHAVIORAL_DIR, entry)))
+            found.push(`${BEHAVIORAL_DIR}/${entry}`);
+    }
+    return found.sort();
+}
+function removeRunnerEnvironment(projectRoot) {
+    const installed = installedRunnerEnvironment(projectRoot);
+    for (const entry of installed)
+        rmSync(join(projectRoot, entry), { recursive: true, force: true });
+    return installed;
+}

package/dist/runner/precheck.js

@@ -157,6 +157,41 @@ function rubyBehavioralPrecheck(projectRoot) {
             'like Rails (no `rails` gem found in Gemfile).',
     };
 }
+// What the behavioral branch's environment is, before a single step is written
+// (spec 35-1, criterion 2). None of the three BDD runners reads the project's own
+// test bootstrap, so on every stack nothing a project's test setup switches on is
+// on here — and a worker who assumes otherwise writes a test that quietly goes
+// out to the real network.
+//
+// One sentence per runner, in that runner's own terms and stating only what is
+// true of it. A shared sentence would have to be vague enough to fit all three,
+// and vague is how the fact went unsaid in the first place.
+const BEHAVIORAL_HARNESS_NOTICE = {
+    cucumber: 'Cucumber loads neither `spec/rails_helper.rb` nor `spec/support/**` — whatever your RSpec ' +
+        'setup switches on is off here. The connector-owned World file turns on the part that is the ' +
+        'same in every Rails app: WebMock is on and outgoing HTTP is blocked (localhost still ' +
+        'reachable), Sidekiq is in fake mode, ActiveJob is on the test adapter, and the default URL ' +
+        'host is fixed. Everything that depends on this application — signing in, factories, reading ' +
+        'props, stubbing a provider — is yours to write in shared steps.',
+    'cucumber-js': 'cucumber-js loads none of this project\'s test bootstrap — not your Vitest setup files, and ' +
+        'not `features/support/`, which the connector\'s explicit `--require` switches off. Whatever ' +
+        'your test setup switches on is off here. The connector-owned World file settles the one ' +
+        'thing that is the same in every JavaScript project: a connection that would leave this ' +
+        'machine is refused, localhost included in neither direction — it stays reachable. There is ' +
+        'no project-wide job runner or default host to fix, so nothing else is assumed. Signing in, ' +
+        'fixtures and seeding are yours to write in shared steps.',
+    'pytest-bdd': 'pytest runs here against the connector\'s own config (`-c`), so this project\'s pytest ' +
+        'settings — addopts, markers, plugin configuration — do not apply, and the only conftest.py ' +
+        'files loaded are those from the repository root down to `step_definitions/`: your ' +
+        '`tests/conftest.py` fixtures are not available. The connector-owned `conftest.py` one level ' +
+        'above `step_definitions/` settles the one thing that is the same in every Python project: a ' +
+        'connection that would leave this machine is refused, and localhost stays reachable. Your own ' +
+        '`step_definitions/conftest.py` is untouched and is where your shared fixtures belong.',
+};
+export function behavioralHarnessNotice(runner) {
+    const notice = BEHAVIORAL_HARNESS_NOTICE[runner];
+    return notice ? `\n${notice}\n` : null;
+}
 function jsBehavioralPrecheck(projectRoot) {
     if (existsSync(join(projectRoot, 'package.json')))
         return { ok: true };

package/dist/runner/provision.js

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
-import { defaultToolDeps, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
+import { executable } from "../proc.js";
+import { BEHAVIORAL_DIR } from "../files/behavioral.js";
+import { runInProject } from "./place.js";
+import { commandFileOnHost, defaultToolDeps, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
 // How long a local setup step may take before we stop waiting. Provisioning a
 // runner and loading a cold Rails test environment sit in the same ballpark —
 // tens of seconds on a large app — so `runner/bootcheck.ts` waits on this same
@@ -12,11 +14,14 @@ export const PROVISION_TIMEOUT_MS = 120_000;
 // package index. Two minutes is a normal figure for it, so it gets its own
 // budget instead of borrowing one sized for a single install.
 export const DEPENDENCY_INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
+// `cwd` is the project root at every call site, and that is what decides where
+// the install happens: a sidecar built by this machine is no use inside a
+// container, and one built inside a container is no use here (see
+// `runner/placeEnvironment.ts`).
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, {
         timeoutMs: options.timeoutMs ?? PROVISION_TIMEOUT_MS,
-        env: { ...process.env, ...options.env },
+        env: options.env,
     }),
 };
 export async function ensureRunner(projectRoot, runner, deps = defaultDeps) {
@@ -93,8 +98,8 @@ const VENV_BUILDERS = [
 // the project declares them in a requirements file, the application's own
 // packages — and deliberately nothing else. See `VENV_BUILDERS`.
 async function provisionPytest(projectRoot, deps) {
-    const venvDir = sidecarPath(projectRoot, '.venv');
-    const venvPython = join(venvDir, 'bin', 'python');
+    const venvDir = `${SIDECAR_DIR}/.venv`;
+    const venvPython = `${venvDir}/bin/python`;
     const built = await buildPythonEnvironment(projectRoot, venvDir, deps);
     if (!built.created) {
         return {
@@ -126,14 +131,17 @@ async function provisionPytest(projectRoot, deps) {
 // installs all three from wheels in seconds. So when the requirements will not
 // go in, the environment is rebuilt with the next builder rather than handed
 // over half-empty. Found 2026-08-12.
+// `venvDir` is relative to the project root, like every other path that reaches
+// a command: the interpreter is built and then started by the place, and only
+// the existence checks below are the host's (spec 36, §4.2).
 async function buildPythonEnvironment(projectRoot, venvDir, deps) {
-    const venvPython = join(venvDir, 'bin', 'python');
+    const venvPython = `${venvDir}/bin/python`;
     // The project's own statement of what it needs. It is also the only test of
     // whether an environment is any use: one the application's packages will not
     // install into is the wrong environment, however well it was built.
     const requirements = ['requirements.txt', 'requirements/base.txt', 'requirements-dev.txt']
         .find((name) => existsSync(join(projectRoot, name)));
-    let created = existsSync(venvPython);
+    let created = existsSync(join(projectRoot, venvPython));
     let requirementsOk = requirements === undefined;
     let failure;
     for (const [index, builder] of VENV_BUILDERS.entries()) {
@@ -162,7 +170,7 @@ async function buildPythonEnvironment(projectRoot, venvDir, deps) {
         // application says far more than no suite at all.
         if (index === VENV_BUILDERS.length - 1)
             break;
-        rmSync(venvDir, { recursive: true, force: true });
+        rmSync(join(projectRoot, venvDir), { recursive: true, force: true });
         created = false;
     }
     if (!created)
@@ -178,7 +186,7 @@ async function buildPythonEnvironment(projectRoot, venvDir, deps) {
     // "pg_config not found") that decides what they do next.
     return {
         created,
-        requirementsNote: `installing ${requirements} into ${relativeVenv(projectRoot, venvDir)} did not finish on any Python ` +
+        requirementsNote: `installing ${requirements} into ${venvDir} did not finish on any Python ` +
             `available here — the suite may not be able to import the application.` +
             (failure ? ` The install said: ${failure}` : ''),
     };
@@ -200,7 +208,7 @@ function noDependencySourceNote(projectRoot, venvDir) {
     const where = declared.length
         ? `this project declares its dependencies in ${declared.join(' and ')}, which Unitbob does not install from yet`
         : 'no requirements.txt, pyproject.toml or Pipfile was found';
-    return (`the application's own packages are not installed into ${relativeVenv(projectRoot, venvDir)} — ${where}. ` +
+    return (`the application's own packages are not installed into ${venvDir} — ${where}. ` +
         'The suite can start, but it may not be able to import the application.');
 }
 // Install into the sidecar environment, whichever tool built it.
@@ -270,6 +278,23 @@ async function provisionVitest(projectRoot, deps) {
     }
     return { status: 'provisioned' };
 }
+// Frozen bundler, turned off for our own Gemfile and for nothing else
+// (spec 36, task 2.6).
+//
+// The sidecar Gemfile adds a gem the project's lockfile has never heard of —
+// that is its entire job — and under `frozen` or `deployment` bundler refuses
+// exactly that: "the dependencies in your gemfile changed, but the lockfile
+// can't be updated because frozen mode is set". Nothing installs, and the
+// vibecoder is told to commit a file the connector wrote.
+//
+// Measured, not reasoned about (2026-08-17, `ruby:3.3-slim`). The project's own
+// `.bundle/config` does *not* reach here: bundler reads app config relative to
+// the Gemfile it was given, which is `.unitbob/runners/`. The environment does,
+// and a dev or production image setting `BUNDLE_DEPLOYMENT=1` is ordinary. So
+// the override is scoped to the one install whose Gemfile we wrote; the
+// project's own bundler settings are never touched, and no other bundler
+// invocation carries this.
+const UNFROZEN_SIDECAR = { BUNDLE_FROZEN: 'false', BUNDLE_DEPLOYMENT: 'false' };
 // A sidecar Gemfile that inherits the project's own, plus rspec-rails. Bundler
 // resolves the two together, so the application's gems come with it — the same
 // arrangement the Cucumber sidecar has used since spec 32-1, and the reason the
@@ -283,12 +308,11 @@ async function provisionRspec(projectRoot, deps) {
     // Cucumber sidecar below: without it bundler re-resolves the whole graph and
     // hands the sidecar versions the project does not run.
     copyLockIfPresent(projectRoot, sidecarPath(projectRoot, 'Gemfile.lock'));
-    const localBundle = join(projectRoot, 'bin', 'bundle');
-    const command = existsSync(localBundle) ? localBundle : 'bundle';
+    const command = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     const result = await deps
         .runCmd(command, ['install'], {
         cwd: projectRoot,
-        env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile` },
+        env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile`, ...UNFROZEN_SIDECAR },
         timeoutMs: DEPENDENCY_INSTALL_TIMEOUT_MS,
     })
         .catch((err) => ({ code: 1, stdout: '', stderr: String(err) }));
@@ -328,7 +352,13 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
-        'gem "cucumber", "~> 9.0", require: false\n';
+        'gem "cucumber", "~> 9.0", require: false\n' +
+        // The connector-owned World blocks outgoing HTTP (spec 35-1), and it can only
+        // do that if webmock resolves here. A project that already carries the gem
+        // keeps its own version, because bundler starts from the project's own
+        // resolution. A project that does not would otherwise get a World promising a
+        // block it silently never performs — the exact shape of failure 35-1 closes.
+        'gem "webmock", require: false\n';
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }
@@ -351,11 +381,14 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     if (existsSync(projectLock)) {
         writeFileSync(join(behavioralDir, 'Gemfile.lock'), readFileSync(projectLock, 'utf8'));
     }
-    const gemfileRel = '.unitbob/behavioral/Gemfile';
-    const env = { BUNDLE_GEMFILE: gemfileRel };
-    // Try project local bin/bundle, then bundle
-    const localBundle = join(projectRoot, 'bin', 'bundle');
-    const cmd = existsSync(localBundle) ? localBundle : 'bundle';
+    // The Cucumber sidecar has the same shape and the same problem as the rspec
+    // one: it adds gems the project's lockfile does not carry. See UNFROZEN_SIDECAR.
+    const gemfileRel = `${BEHAVIORAL_DIR}/Gemfile`;
+    const env = { BUNDLE_GEMFILE: gemfileRel, ...UNFROZEN_SIDECAR };
+    // Try project local bin/bundle, then bundle. Relative with a slash: the
+    // working directory is the project root, and a bare name would be looked up on
+    // PATH instead.
+    const cmd = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     const result = await deps.runCmd(cmd, ['install'], { cwd: projectRoot, env }).catch((err) => ({
         code: 1,
         stdout: '',
@@ -371,9 +404,13 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     };
 }
 async function provisionPython(projectRoot, behavioralDir, deps) {
-    const venvDir = join(behavioralDir, '.venv');
-    const venvPython = join(venvDir, 'bin', 'python');
-    const venvPytest = join(venvDir, 'bin', 'pytest');
+    // Two forms of one path, and the split is the rule of spec 36, §4.2: what a
+    // command names is relative, because the command runs where the dependencies
+    // live; what we test for existence is the host's, because that is where the
+    // files are.
+    const venvDir = `${BEHAVIORAL_DIR}/.venv`;
+    const venvPython = `${venvDir}/bin/python`;
+    const venvPytest = commandFileOnHost(projectRoot, `${venvDir}/bin/pytest`);
     // The behavioral suite drives the application, so its environment needs the
     // application in it — the same requirement, and now the same treatment, as the
     // structural peer. It used to be built with `--system-site-packages` and given
@@ -384,7 +421,7 @@ async function provisionPython(projectRoot, behavioralDir, deps) {
     if (!built.created) {
         return {
             status: 'fixable',
-            message: `Failed to create virtual environment under ${relativeVenv(projectRoot, venvDir)}.`,
+            message: `Failed to create virtual environment under ${venvDir}.`,
             checklist: ['Install python3-venv or uv: `python3 -m venv --help` or `pip install uv`.'],
         };
     }
@@ -392,7 +429,7 @@ async function provisionPython(projectRoot, behavioralDir, deps) {
     if (!installed && !existsSync(venvPytest)) {
         return {
             status: 'fixable',
-            message: `Failed to install pytest-bdd into ${relativeVenv(projectRoot, venvDir)}.`,
+            message: `Failed to install pytest-bdd into ${venvDir}.`,
             checklist: [`Run \`${venvPython} -m pip install pytest-bdd\` manually to provision the runner.`],
         };
     }
@@ -400,9 +437,6 @@ async function provisionPython(projectRoot, behavioralDir, deps) {
         ? { status: 'provisioned', checklist: [built.requirementsNote] }
         : { status: 'provisioned' };
 }
-function relativeVenv(projectRoot, venvDir) {
-    return venvDir.startsWith(projectRoot) ? venvDir.slice(projectRoot.length + 1) : venvDir;
-}
 async function provisionJs(projectRoot, behavioralDir, deps) {
     const sidecarPkg = join(behavioralDir, 'package.json');
     const sidecarContent = JSON.stringify({

package/dist/runner/pytest.js

@@ -1,9 +1,9 @@
 import { writeFileSync } from 'node:fs';
 import { 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 PYTEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
 // A minimal runtime config, created or overwritten before each run and passed
@@ -17,7 +17,7 @@ export const PYTEST_INI = '[pytest]\naddopts =\n';
 // JUnit XML report goes to --junit-xml, not stdout. The command is
 // connector-owned: the suite artifact never carries a command string.
 //
-// Every file of the branch is named positionally (spec 42, §6.5) — a branch is
+// Every file of the branch is named positionally (spec 43, §6.5) — a branch is
 // one file per assignment now, and pytest takes as many paths as it is given.
 //
 // Which pytest is a single question answered in one place (`locateRunner`), so
@@ -36,16 +36,15 @@ export async function runPytestSuite(projectRoot, suitePaths) {
         ...suitePaths,
         `--junit-xml=${PYTEST_RESULT_FILE}`,
     ];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const reportPath = join(projectRoot, PYTEST_RESULT_FILE);
+    const survivor = clearReport(reportPath);
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: PYTEST_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: PYTEST_RESULT_FILE,
-        report: readReport(join(projectRoot, PYTEST_RESULT_FILE)),
+        report: readFreshReport(reportPath, survivor),
     };
 }

package/dist/runner/pytestBddPlugin.js

@@ -14,6 +14,15 @@ import os
 _UNITBOB_REPORT = {"version": 1, "scenarios": []}
 _UNITBOB_CURRENT = {}
 
+# Resolved once, at import, and never again. The connector passes this path
+# relative to the project root — a relative path means the same thing whether the
+# run happens on this machine or inside a container, and an absolute host path
+# would name a directory the run cannot see. The working directory is the project
+# root when the plugin loads, so a fixture that changes directory later cannot
+# move the report out from under us.
+_UNITBOB_OUT = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
+_UNITBOB_OUT = os.path.abspath(_UNITBOB_OUT) if _UNITBOB_OUT else None
+
 
 def pytest_bdd_before_scenario(request, feature, scenario):
     _UNITBOB_CURRENT[id(scenario)] = {
@@ -55,8 +64,7 @@ def pytest_bdd_after_scenario(request, feature, scenario):
 
 
 def pytest_sessionfinish(session, exitstatus):
-    out = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
-    if out:
-        with open(out, "w") as handle:
+    if _UNITBOB_OUT:
+        with open(_UNITBOB_OUT, "w") as handle:
             json.dump(_UNITBOB_REPORT, handle)
 `;

package/dist/runner/rspec.js

@@ -1,8 +1,8 @@
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } 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 RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
 // green→red flip can never come from run-order nondeterminism. It does not inherit
@@ -18,13 +18,15 @@ export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // corrupt it.
 //
 // `suitePaths` is every file of the branch in the suite blob's own
-// project-relative form (spec 42, §6.5). Named one by one rather than as a
+// project-relative form (spec 43, §6.5). Named one by one rather than as a
 // directory: the artifact already says exactly which files it is, while a
 // directory would also collect whatever else happens to be sitting under the
 // root.
 export async function runRspecSuite(projectRoot, suitePaths) {
     const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
-    const { result, command, args } = await invokeRspec(projectRoot, [
+    const reportPath = join(projectRoot, RSPEC_RESULT_FILE);
+    const survivor = clearReport(reportPath);
+    const run = await invokeRspec(projectRoot, [
         ...suitePaths,
         '--options',
         optionsPath,
@@ -38,11 +40,9 @@ export async function runRspecSuite(projectRoot, suitePaths) {
         RSPEC_RESULT_FILE,
     ]);
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: RSPEC_RESULT_FILE,
-        report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
+        report: readFreshReport(reportPath, survivor),
     };
 }
 // Which rspec — the sidecar Unitbob installed, the project's own `bin/rspec`
@@ -54,10 +54,12 @@ async function invokeRspec(projectRoot, rspecArgs) {
     const located = locateRunner(projectRoot, 'rspec');
     const command = located?.command ?? 'bundle';
     const args = [...(located?.args ?? ['exec', 'rspec']), ...rspecArgs];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    return runInProject(projectRoot, command, args, {
         timeoutMs: RSPEC_TIMEOUT_MS,
-        env: { ...process.env, ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: {
+            ...located?.env,
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+        },
     });
-    return { result, command, args };
 }

package/dist/runner/toolchain.js

@@ -1,7 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { executable } from "../proc.js";
+import { commandSucceedsInProject } from "./place.js";
 // Where Unitbob keeps a test runner it had to install for itself, together with
 // whatever that runner needs to load the project.
 //
@@ -15,8 +15,42 @@ export const SIDECAR_DIR = '.unitbob/runners';
 export function sidecarPath(projectRoot, ...segments) {
     return join(projectRoot, SIDECAR_DIR, ...segments);
 }
+// The stop that means "nothing here can start this project's test runner"
+// (spec 36, §7.1).
+//
+// It carries no new wording — the four places that throw it say exactly what
+// they said before. All it adds is a name, so that one place at the top can tell
+// this stop apart from "the server did not answer" and "your token was refused",
+// and offer the one piece of advice that only fits this one. Hanging that advice
+// on the individual failure sites instead would have given it to Ruby alone: a
+// pytest project in a container stops somewhere else, with different words, and
+// a vitest one somewhere else again.
+export class ToolchainUnavailableError extends Error {
+    projectRoot;
+    constructor(message, projectRoot) {
+        super(message);
+        this.name = 'ToolchainUnavailableError';
+        this.projectRoot = projectRoot;
+    }
+}
+// The file a command names, on the host's own filesystem.
+//
+// A command that names a file we own is written relative to the project root, so
+// that it means the same thing wherever it is started (spec 36, §4.2). Asking
+// whether that file exists is a different question and is always the host's:
+// under the invariant the connector's files are on the host, and the place sees
+// the very same ones. A command with no path in it — `bundle`, `python3` — is
+// resolved by the place through its own PATH and is returned unchanged.
+export function commandFileOnHost(projectRoot, command) {
+    if (isAbsolute(command) || !command.includes('/'))
+        return command;
+    return join(projectRoot, command);
+}
+// Asked of the place the run will happen in, never of this machine by default
+// (spec 36, §3). `cwd` is the project root at every call site, which is what
+// says which place that is.
 export const defaultToolDeps = {
-    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+    commandSucceeds: (command, args, cwd) => commandSucceedsInProject(cwd, command, args),
 };
 // How to invoke `runner` in this project, or null when nothing here can.
 //
@@ -78,8 +112,9 @@ function locatePytest(projectRoot, deps) {
     // behind. Trusting the file made provisioning report success and the boot
     // check then say "No module named pytest" about an environment we had just
     // built. Found on a Flask project, 2026-08-12.
-    const venvPython = sidecarPath(projectRoot, '.venv', 'bin', 'python');
-    if (executable(venvPython) && deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
+    const venvPython = `${SIDECAR_DIR}/.venv/bin/python`;
+    if (executable(commandFileOnHost(projectRoot, venvPython)) &&
+        deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
         return { command: venvPython, args: ['-m', 'pytest'], source: 'sidecar' };
     }
     for (const python of ['python3', 'python']) {
@@ -94,11 +129,11 @@ function locatePytest(projectRoot, deps) {
 // checks that must not install anything. The vitest runner keeps `npx` as its
 // own last resort, which is the behaviour it has always had.
 function locateVitest(projectRoot) {
-    const sidecar = sidecarPath(projectRoot, 'node_modules', '.bin', 'vitest');
-    if (executable(sidecar))
+    const sidecar = `${SIDECAR_DIR}/node_modules/.bin/vitest`;
+    if (executable(commandFileOnHost(projectRoot, sidecar)))
         return { command: sidecar, args: [], source: 'sidecar' };
-    const project = join(projectRoot, 'node_modules', '.bin', 'vitest');
-    if (executable(project))
+    const project = 'node_modules/.bin/vitest';
+    if (executable(commandFileOnHost(projectRoot, project)))
         return { command: project, args: [], source: 'project' };
     return null;
 }
@@ -115,8 +150,11 @@ function locateRspec(projectRoot) {
             source: 'sidecar',
         };
     }
-    const binstub = join(projectRoot, 'bin', 'rspec');
-    if (executable(binstub))
+    // Relative, and the slash is not decoration: `spawn` resolves a command
+    // against the working directory only when it has one, and a bare `rspec` would
+    // go looking on PATH — a different command altogether.
+    const binstub = 'bin/rspec';
+    if (executable(commandFileOnHost(projectRoot, binstub)))
         return { command: binstub, args: [], source: 'project' };
     return { command: 'bundle', args: ['exec', 'rspec'], source: 'project' };
 }

package/dist/runner/types.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
 // Read a report file back verbatim. A missing or unreadable file is a clean
 // empty string, not a throw: the caller reports a structured suite error.
 export function readReport(path) {
@@ -9,3 +9,47 @@ export function readReport(path) {
         return '';
     }
 }
+// Clear the report before a run, and hand back whatever survived the attempt
+// (spec 36, criterion 9).
+//
+// The report is written to a fixed path with no run marker on it, and — once the
+// run happens in a container — into a folder both sides share. A run we gave up
+// on can leave a process alive inside that container, and that process finishes
+// and writes the report after we stopped waiting. The next run would then read a
+// file belonging to a run nobody watched, and report a green result nobody
+// earned. Having no result at all is the better of the two.
+//
+// What comes back is the modification time of a file that would not delete —
+// a read-only mount, a permission we do not have — so the read below can tell
+// "the same file, still there" from "a new one the run just wrote". Nothing is
+// compared against this machine's clock: both stamps come from whoever wrote the
+// file, so a container whose clock differs from the host's cannot make a good
+// report look stale.
+export function clearReport(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Could not remove it. That is exactly the case the stamp below covers.
+    }
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// The report of *this* run, or nothing. `survivor` is what `clearReport`
+// returned before the run started.
+export function readFreshReport(path, survivor) {
+    if (survivor !== null) {
+        try {
+            if (statSync(path).mtimeMs === survivor)
+                return '';
+        }
+        catch {
+            return '';
+        }
+    }
+    return readReport(path);
+}