unitbob 0.5.1 → 0.6.1

package/dist/runner/bdd.js

@@ -1,12 +1,23 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
-import { readReport } from "./types.js";
+import { executable } from "../proc.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
+import { commandFileOnHost } from "./toolchain.js";
+import { clearReport, readFreshReport } from "./types.js";
 import { PYTEST_BDD_PLUGIN } from "./pytestBddPlugin.js";
 export const BDD_TIMEOUT_MS = 10 * 60 * 1000;
 // The behavioral suite lives under one root; the report is written inside it so
 // the app under test cannot pollute it and it travels with the suite.
+//
+// Spelled here rather than imported from `files/behavioral.ts`, which spells it
+// too: that module imports this one, and an import back would be a cycle whose
+// only symptom is a use-before-initialization at load time.
 const BEHAVIORAL_ROOT = '.unitbob/behavioral';
+// The sidecar Gemfile bundler is pointed at, in one place — the world probe
+// needs the same value and used to carry its own copy. A plain string rather
+// than `join`: this path is read where the run happens, whose separator is not
+// necessarily this machine's.
+export const BEHAVIORAL_GEMFILE = `${BEHAVIORAL_ROOT}/Gemfile`;
 const CUCUMBER_REPORT_NAME = 'cucumber_messages.ndjson';
 const PYTEST_BDD_REPORT_NAME = 'pytest_bdd_report.json';
 const PYTEST_BDD_PLUGIN_NAME = 'unitbob_pytest_bdd_plugin.py';
@@ -112,24 +123,22 @@ function strategyFor(runner) {
 async function runCucumberRuby(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
-    const sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
+    const sidecarGemfile = join(projectRoot, BEHAVIORAL_GEMFILE);
     if (!existsSync(sidecarGemfile)) {
         throw missingRunner('Cucumber');
     }
     const command = 'bundle';
     const args = ['exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
-    const env = {
-        ...process.env,
-        RAILS_ENV: 'test',
-        UNITBOB_REPO_ROOT: projectRoot,
-    };
-    env.BUNDLE_GEMFILE = join(BEHAVIORAL_ROOT, 'Gemfile');
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
-        env,
+        env: {
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+            BUNDLE_GEMFILE: BEHAVIORAL_GEMFILE,
+        },
     });
-    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+    return finalize(run, projectRoot, CUCUMBER_REPORT, survivor);
 }
 function missingRunner(name) {
     return new Error(`Behavioral runner missing (${name}). Run suite-prepare to provision it under ${BEHAVIORAL_ROOT}/, then run the checks again.`);
@@ -139,11 +148,10 @@ function missingRunner(name) {
 async function runCucumberJs(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
-    const sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
-    if (!executable(sidecarBin)) {
+    const command = `${BEHAVIORAL_ROOT}/node_modules/.bin/cucumber-js`;
+    if (!executable(commandFileOnHost(projectRoot, command))) {
         throw missingRunner('Cucumber JS');
     }
-    const command = sidecarBin;
     const args = [
         features,
         '--require',
@@ -151,12 +159,12 @@ async function runCucumberJs(projectRoot) {
         '--format',
         `message:${CUCUMBER_REPORT}`,
     ];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+    const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
-        env: { ...process.env, NODE_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { NODE_ENV: 'test', UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
-    return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
+    return finalize(run, projectRoot, CUCUMBER_REPORT, survivor);
 }
 // Python: pytest driving pytest-bdd, with the connector's reporter plugin. The
 // plugin writes the JSON report; `-c` isolates the run from the project's own
@@ -168,38 +176,45 @@ async function runPytestBdd(projectRoot, mainPath) {
     const command = await pickPython(projectRoot);
     const stepsDir = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const isVenvPytest = command.endsWith('/pytest');
+    // `--rootdir .`, not the absolute root: the working directory is the project
+    // root in every place, and an absolute host path would name a directory that
+    // does not exist wherever the run actually happens.
     const args = isVenvPytest
-        ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot]
-        : ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot];
-    const result = await runProcess(command, args, {
-        cwd: projectRoot,
+        ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.']
+        : ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.'];
+    const survivor = clearReport(join(projectRoot, PYTEST_BDD_REPORT));
+    const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
         env: {
-            ...process.env,
-            UNITBOB_REPO_ROOT: projectRoot,
-            UNITBOB_PYTEST_BDD_REPORT: join(projectRoot, PYTEST_BDD_REPORT),
-            PYTHONPATH: [join(projectRoot, BEHAVIORAL_ROOT), process.env.PYTHONPATH ?? ''].filter(Boolean).join(':'),
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+            // Relative, and the plugin makes it absolute the moment it is imported —
+            // before any fixture has had a chance to change directory. Sent as a host
+            // path it would name a directory the run cannot see.
+            UNITBOB_PYTEST_BDD_REPORT: PYTEST_BDD_REPORT,
+            // The connector's own plugin directory, and only it. The host's own
+            // PYTHONPATH used to be appended here; it names host directories, which
+            // mean nothing where the run happens, and passing on the connector's
+            // environment is exactly what a place must not do.
+            PYTHONPATH: BEHAVIORAL_ROOT,
         },
     });
-    return finalize(result, command, args, projectRoot, PYTEST_BDD_REPORT);
+    return finalize(run, projectRoot, PYTEST_BDD_REPORT, survivor);
     // mainPath is accepted for symmetry with the structural runners; pytest-bdd
     // discovers scenarios from the step-definition modules, not the .feature path.
 }
 function pluginModule() {
     return 'unitbob_pytest_bdd_plugin';
 }
-function finalize(result, command, args, projectRoot, reportRel) {
+function finalize(run, projectRoot, reportRel, survivor) {
     return {
-        ...result,
-        command,
-        args,
+        ...run,
         resultPath: reportRel,
-        report: readReport(join(projectRoot, reportRel)),
+        report: readFreshReport(join(projectRoot, reportRel), survivor),
     };
 }
 async function pickPython(projectRoot) {
-    const sidecarVenvPytest = join(projectRoot, BEHAVIORAL_ROOT, '.venv', 'bin', 'pytest');
-    if (executable(sidecarVenvPytest)) {
+    const sidecarVenvPytest = `${BEHAVIORAL_ROOT}/.venv/bin/pytest`;
+    if (executable(commandFileOnHost(projectRoot, sidecarVenvPytest))) {
         return sidecarVenvPytest;
     }
     throw missingRunner('pytest-bdd');

package/dist/runner/bootcheck.js

@@ -1,16 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
-import { locateRunner } from "./toolchain.js";
+import { executable } from "../proc.js";
+import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
+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";
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, {
-        cwd: options.cwd,
-        timeoutMs: PROVISION_TIMEOUT_MS,
-        env: { ...process.env, ...options.env },
-    }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: PROVISION_TIMEOUT_MS, env: options.env }),
 };
 // How much of a runner's output rides along in `detail`. Enough to see the
 // stack that mattered, short enough that a stop message stays readable.
@@ -49,8 +46,8 @@ export async function bootCheck(projectRoot, runner, deps = defaultDeps) {
 // `spec/support` and the project's own configuration all come along for free,
 // without this module knowing anything about them.
 async function rubyBootCheck(projectRoot, deps) {
-    const helper = join(projectRoot, GUARDRAILS_DIR, HELPER_FILE);
-    if (!existsSync(helper))
+    const helper = `${GUARDRAILS_DIR}/${HELPER_FILE}`;
+    if (!existsSync(join(projectRoot, helper)))
         return { status: 'not_checked', reason: 'nothing_to_load' };
     const first = await loadRubyHelper(projectRoot, helper, deps);
     if (first.status !== 'broken')
@@ -85,16 +82,25 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // someone whose bundler is installed and working. That is the mistake
     // `runner_too_old` and `runner_could_not_answer` were added to stop making,
     // and the global `bundle` was standing right there the whole time.
-    const localBundle = join(projectRoot, 'bin', 'bundle');
-    const command = executable(localBundle) ? localBundle : 'bundle';
+    const command = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     // When Unitbob installed rspec-rails for itself, the gems this helper needs
     // are resolved by the sidecar Gemfile, not the project's. Asking bundler
     // without that variable would load a different set of gems than the run does,
     // which is exactly the way a check ends up predicting the wrong thing.
     const located = locateRunner(projectRoot, 'rspec');
-    return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(helper)}`], {
+    // `require "./…"`, and the leading dot is not cosmetic: Ruby resolves a
+    // relative require against `$LOAD_PATH`, which does not hold the working
+    // directory, and only a path beginning with `.` is resolved against the
+    // working directory instead. The helper finds its own neighbours through
+    // `__dir__`, which is absolute however the file was reached, so nothing else
+    // about it changes.
+    return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(`./${helper}`)}`], {
         cwd: projectRoot,
-        env: { ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: {
+            ...located?.env,
+            RAILS_ENV: 'test',
+            UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+        },
     }), 
     // A clean load says nothing on stdout and exits 0. Anything else is the
     // suite failing to start.
@@ -171,8 +177,7 @@ function pytestVerdict(code) {
 async function vitestBootCheck(projectRoot, deps) {
     // 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
-        ?? join(projectRoot, 'node_modules', '.bin', 'vitest');
+    const local = locateRunner(projectRoot, 'vitest')?.command ?? 'node_modules/.bin/vitest';
     // Only a vitest already installed in the project is used. Reaching for `npx`
     // would install a package to answer a question, and installing into the
     // user's project is not this check's business.
@@ -182,7 +187,7 @@ async function vitestBootCheck(projectRoot, deps) {
     // "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.
-    if (!executable(local))
+    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
@@ -243,6 +248,14 @@ function classify(projectRoot, runner, result, verdict) {
     // nothing about the code, so it must not read as a defect.
     if (result.code === null)
         return { status: 'not_checked', reason: 'timed_out' };
+    // Before the exit code is read at all, and that order is the whole point. The
+    // codes docker returns for its own failures overlap with real runners' codes,
+    // and one step further down `causeOf` picks a cause by matching the output
+    // against a path pattern — so a container that stopped mid-run could come back
+    // as "found a defect that stops your test suite from starting". An accusation
+    // about somebody's code, for a failure of the daemon.
+    if (result.placeFailure)
+        return { status: 'not_checked', reason: 'place_failed', detail: result.placeFailure };
     const outcome = verdict(result);
     if (outcome === 'ok')
         return { status: 'ok' };
@@ -374,13 +387,12 @@ export function firstErrorLine(output) {
 async function prepareTestDatabase(projectRoot, deps) {
     if (!testDatabaseIsSeparate(projectRoot))
         return false;
-    const rails = join(projectRoot, 'bin', 'rails');
-    const useBinstub = executable(rails);
-    const command = useBinstub ? rails : 'bundle';
+    const useBinstub = executable(join(projectRoot, 'bin', 'rails'));
+    const command = useBinstub ? 'bin/rails' : 'bundle';
     const args = useBinstub ? ['db:test:prepare'] : ['exec', 'rails', 'db:test:prepare'];
     const result = await attempt(deps, command, args, {
         cwd: projectRoot,
-        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot) },
     });
     return result !== null && result.code === 0;
 }

package/dist/runner/docker.js

@@ -0,0 +1,139 @@
+// Everything this connector knows about Docker, in one file (spec 36).
+//
+// It is deliberately not "a command prefix the user configures". A prefix would
+// be three lines and would make every message below impossible: with only a
+// string to run, nothing can say "that container is not running", "the project
+// is not mounted into it", or "here is the container that already has your
+// project". Those sentences are the point of the spec, so the connector knows
+// what a container is.
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { posix, relative, sep } from 'node:path';
+const inspected = new Map();
+// Where this container sees the project root, or why it cannot.
+//
+// The path inside is never configured. It is derived from the container's own
+// mounts: the deepest mount whose source is the start of the path to the project
+// root, with the remainder appended to its destination. Exact equality (`.:/app`)
+// is the common case but not the only one — a monorepo mounts the parent
+// (`..:/workspace`) and the project sits inside it, and demanding equality would
+// report "your code is copied into the image" about a project that is plainly
+// mounted.
+//
+// This doubles as the bind-mount check the whole invariant rests on: no mount
+// covering the root means the code was copied into the image, which means files
+// written here are invisible there and reports written there are invisible here.
+export function containerProjectRoot(container, projectRoot) {
+    const found = inspected.get(container) ?? inspect(container);
+    inspected.set(container, found);
+    if ('failure' in found)
+        return found.failure;
+    if (found.container.State?.Running === false)
+        return { status: 'not_running' };
+    const mounted = mountedRoot(found.container.Mounts ?? [], projectRoot);
+    return mounted === null ? { status: 'not_mounted' } : { status: 'ok', projectRoot: mounted };
+}
+function inspect(container) {
+    const result = spawnSync('docker', ['container', 'inspect', container, '--format', '{{json .}}'], {
+        timeout: 30_000,
+        encoding: 'utf8',
+    });
+    // `docker` is not on this machine at all — a different sentence from any
+    // answer about the container, and the only one whose fix is "install Docker".
+    if (result.error && result.error.code === 'ENOENT')
+        return { failure: { status: 'no_docker' } };
+    if (result.error)
+        return { failure: { status: 'unreadable', detail: result.error.message } };
+    const stderr = (result.stderr ?? '').trim();
+    if (result.status !== 0) {
+        if (/no such (container|object)/i.test(stderr))
+            return { failure: { status: 'no_container' } };
+        if (/cannot connect to the docker daemon/i.test(stderr))
+            return { failure: { status: 'no_docker' } };
+        return { failure: { status: 'unreadable', detail: stderr || `docker inspect exited ${result.status}` } };
+    }
+    try {
+        return { container: JSON.parse(result.stdout) };
+    }
+    catch (err) {
+        return { failure: { status: 'unreadable', detail: `could not read what docker said (${err.message})` } };
+    }
+}
+// The deepest mount that holds this project, translated to the path inside.
+//
+// Both sides are resolved through their symlinks before they are compared. On
+// macOS `/tmp` is a link to `/private/tmp`, so a project checked out under one
+// and mounted as the other is the classic way to be told "there is no mount"
+// where there plainly is one.
+function mountedRoot(mounts, projectRoot) {
+    const root = resolved(projectRoot);
+    let best = null;
+    for (const mount of mounts) {
+        if (!mount.Source || !mount.Destination)
+            continue;
+        const inside = relative(resolved(mount.Source), root);
+        // Outside this mount, or on the far side of a `..`, or an absolute path
+        // (which `relative` returns when the two share no root at all).
+        if (inside.startsWith('..') || inside.startsWith('/'))
+            continue;
+        const depth = resolved(mount.Source).split(sep).length;
+        if (best && best.depth >= depth)
+            continue;
+        // The container's own filesystem, so its own separator: a Windows host
+        // still mounts into a Linux path.
+        best = { depth, path: inside === '' ? mount.Destination : posix.join(mount.Destination, inside.split(sep).join('/')) };
+    }
+    return best?.path ?? null;
+}
+function resolved(path) {
+    try {
+        return existsSync(path) ? realpathSync(path) : path;
+    }
+    catch {
+        return path;
+    }
+}
+// The command as it is actually executed. The wrapper is not hidden from
+// anybody: the "ran:" line a person reads and the command string that travels to
+// the brain on a failure both show this, because a line that quietly drops the
+// wrapper is a line that fails differently when somebody pastes it.
+export function dockerExec(container, workingDirectory, env, command, args) {
+    const variables = Object.entries(env).flatMap(([key, value]) => ['-e', `${key}=${value}`]);
+    return { command: 'docker', args: ['exec', '-w', workingDirectory, ...variables, container, command, ...args] };
+}
+// Docker's own failures, told apart from the project's.
+//
+// `docker exec` returns 125, 126 and 127 for reasons entirely its own — the
+// container stopped between the check and the spawn, the executable is not in
+// the image — and those codes collide with real runners' codes. Left
+// unmarked, a boot check reads the exit code as "broken", picks a cause by
+// matching the output against a path pattern, and can announce that it "found a
+// defect that stops your test suite from starting". That would be an accusation
+// about somebody's code for a failure of the daemon.
+//
+// So the code alone is never enough: the client has to have said something only
+// it says.
+const DOCKER_SPEAKING = /Error response from daemon|is not running|No such container|OCI runtime exec failed|executable file not found/i;
+export function dockerOwnFailure(result) {
+    if (result.code !== 125 && result.code !== 126 && result.code !== 127)
+        return null;
+    return DOCKER_SPEAKING.test(result.stderr) ? result.stderr.trim() : null;
+}
+// Every running container that already holds this project, for the message
+// somebody gets when their toolchain is nowhere to be found on this machine.
+//
+// Only ever called once a command has decided to fail. On the successful path
+// `docker` is not run at all, so a project with no Docker in sight pays nothing
+// and is asked nothing.
+export function containersHolding(projectRoot) {
+    const listed = spawnSync('docker', ['ps', '--format', '{{.Names}}'], { timeout: 30_000, encoding: 'utf8' });
+    if (listed.error || listed.status !== 0)
+        return [];
+    const found = [];
+    for (const name of listed.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
+        const lookup = containerProjectRoot(name, projectRoot);
+        if (lookup.status === 'ok')
+            found.push({ name, projectRoot: lookup.projectRoot });
+    }
+    return found;
+}

package/dist/runner/place.js

@@ -0,0 +1,181 @@
+// Where this project's own processes start (spec 36).
+//
+// A mature team's test environment does not live on the machine the connector
+// was called on: the code is on the host, and the interpreter, the packages and
+// the database are inside a container. So "run it here" stops being a fact and
+// becomes a question, and this module is the one place that answers it.
+//
+// The invariant the whole spec is built on:
+//
+//     Files stay on the host. Processes run where the dependencies live.
+//
+// Everything the connector reads and writes — request packets, suite files, run
+// reports — it reads and writes on the host with ordinary filesystem calls. Only
+// the processes that need the project's own toolchain travel.
+//
+// Which processes those are is not decided here and is deliberately not decided
+// by a mode, a flag, or a global. It is decided at each call site by which
+// function it calls: `runInProject` for a command that needs the project's
+// dependencies, `runProcess` for a tool the connector brought with it (graphify
+// is installed on the vibecoder's machine and is nowhere to be found inside
+// somebody else's image). The rule is visible in the call itself, so the next
+// reader sees the boundary without reading this file.
+//
+// The place itself is a property of the *project*, not of the run: it is written
+// in `.unitbob.json` at the project root. So this module works it out from the
+// project root it is handed, and no caller sets it, passes it, or can forget to.
+import { spawnSync } from 'node:child_process';
+import { readLocalExecContainer } from "../config.js";
+import { runProcess } from "../proc.js";
+import { containerProjectRoot, dockerExec, dockerOwnFailure } from "./docker.js";
+// The place this project's processes run in.
+//
+// Read from the project on every call rather than resolved once into a module
+// variable. A setter would be cheap and would introduce exactly the failure this
+// spec exists to remove: a new verb forgets to call it, the connector quietly
+// runs on the host, and nobody finds out.
+export function placeOf(projectRoot) {
+    const container = readLocalExecContainer(projectRoot);
+    return container ? { kind: 'docker', container } : { kind: 'local' };
+}
+// How this place is written down in `.unitbob/.place`, so a runner environment
+// built by one place is never mistaken for one built by another.
+const DOCKER_MARK = 'docker:';
+export function placeId(place) {
+    return place.kind === 'docker' ? `${DOCKER_MARK}${place.container}` : 'local';
+}
+// The same mark in words, for the one message that has to name both the place an
+// environment was built in and the place this run happens in. It lives beside
+// `placeId` because a format written in one file and taken apart in another is a
+// format that drifts.
+export function describePlaceId(id) {
+    return id.startsWith(DOCKER_MARK) ? `the container \`${id.slice(DOCKER_MARK.length)}\`` : 'this machine';
+}
+// The project root as the place sees it.
+//
+// Exactly one value in the system has to know where the root is —
+// `UNITBOB_REPO_ROOT`, which the generated Ruby joins `config/environment` onto.
+// It is built from the place rather than rewritten from a host path, so on the
+// local place it is byte for byte the path it has always been.
+export function projectRootAsSeenByThePlace(projectRoot) {
+    const place = placeOf(projectRoot);
+    if (place.kind === 'local')
+        return projectRoot;
+    const lookup = containerProjectRoot(place.container, projectRoot);
+    if (lookup.status === 'ok')
+        return lookup.projectRoot;
+    // Every command that must not run blind has been through `placeProblem`
+    // first. The one that has not is `map-prepare`, which asks the router and is
+    // allowed to fail — it degrades to one line and the map is built from source
+    // as it always was. So this returns something rather than throwing out of what
+    // reads like a getter: the command it belongs to is not going to run anyway.
+    return projectRoot;
+}
+// Run one of the project's own commands, in the project's own root.
+//
+// The working directory is always the project root, and that is the discipline
+// that keeps host paths out of commands rather than a rule that rewrites them:
+// with the root as the working directory, every argument a command needs can be
+// relative, and a relative argument means the same thing in every place.
+export async function runInProject(projectRoot, command, args, options = {}) {
+    const place = placeOf(projectRoot);
+    if (place.kind === 'local') {
+        const result = await runProcess(command, args, {
+            cwd: projectRoot,
+            timeoutMs: options.timeoutMs,
+            env: { ...process.env, ...options.env },
+        });
+        return { ...result, command, args };
+    }
+    const shaped = shapeForContainer(place.container, projectRoot, command, args, options.env ?? {});
+    const result = await runProcess(shaped.command, shaped.args, {
+        cwd: projectRoot,
+        timeoutMs: options.timeoutMs,
+        // The environment of the `docker` client, not of the command: everything the
+        // command is meant to see was listed with `-e` above. This machine's own
+        // PATH and HOME never travel — a container has a PATH of its own, and
+        // overwriting it hides the very `bundle` the image was built with.
+        env: process.env,
+    });
+    const failure = dockerOwnFailure(result);
+    return { ...result, ...(failure ? { placeFailure: failure } : {}), command: shaped.command, args: shaped.args };
+}
+function shapeForContainer(container, projectRoot, command, args, env) {
+    const lookup = containerProjectRoot(container, projectRoot);
+    // `/` is not a working directory anything would succeed in, and that is the
+    // point: the lookup has already failed, every caller of consequence has been
+    // through `ensurePlaceIsUsable`, and docker's own refusal is a better answer
+    // than a path this connector made up.
+    const workingDirectory = lookup.status === 'ok' ? lookup.projectRoot : '/';
+    return dockerExec(container, workingDirectory, env, command, args);
+}
+// Can work happen here at all? Asked before anything is written and before
+// anything is uploaded (spec 36, criterion 7), because the alternative is a
+// green run whose evidence disappears with the container.
+//
+// Returns the sentence to stop with, or null when the place is usable. Not a
+// throw: two callers want to stop, one — the map — wants to degrade quietly, and
+// the difference belongs to them.
+export function placeProblem(projectRoot) {
+    const place = placeOf(projectRoot);
+    if (place.kind === 'local')
+        return null;
+    return explain(place.container, containerProjectRoot(place.container, projectRoot));
+}
+function explain(container, lookup) {
+    switch (lookup.status) {
+        case 'ok':
+            return null;
+        case 'no_docker':
+            return (`This project is set to run its tests inside the container \`${container}\`, but \`docker\` is not ` +
+                'available on this machine — either it is not installed or its daemon is not running. Start Docker, ' +
+                `or remove \`"exec"\` from ${CONFIG_HINT} to run everything here instead.`);
+        case 'no_container':
+            return (`This project is set to run its tests inside the container \`${container}\`, and no container of that ` +
+                'name exists here. Check the name with `docker ps --format "{{.Names}}"` and correct it in ' +
+                `${CONFIG_HINT}.`);
+        case 'not_running':
+            return (`The container \`${container}\` exists but is not running, and this project's tests are set to run ` +
+                `inside it. Start it (\`docker start ${container}\`, or \`docker compose up -d\`), then run this again.`);
+        case 'not_mounted':
+            return (`The container \`${container}\` is running, but this project's folder is not mounted into it — the ` +
+                'code inside it was copied in when the image was built. Unitbob cannot work that way: it writes the ' +
+                'suite here and the run has to read it there, and a report written inside a container that is not ' +
+                'sharing this folder disappears with the container. Mount the project into the container (a `volumes:` ' +
+                'entry in your compose file) and run this again. Nothing was written and nothing was uploaded.');
+        case 'unreadable':
+            return (`Could not ask docker about the container \`${container}\`, which is where this project's tests are ` +
+                `set to run: ${lookup.detail}`);
+    }
+}
+const CONFIG_HINT = '`.unitbob.json`';
+// "Can this be started at all?" — asked of the same place that will start it.
+//
+// Kept next to `runInProject` rather than left at its old call site, because a
+// check that asks this machine while the run happens somewhere else is a check
+// that predicts the wrong thing. It is the same reason `runnerAvailable` already
+// asks the same interpreters, in the same order, that the run itself asks.
+// One known limitation, written down rather than hidden: the answer is a
+// boolean, so a container that died between the preflight and this question
+// comes back as "no, that cannot be started" — the same conflation `place_failed`
+// was added to the boot check to stop making. It stays a boolean because every
+// caller of `locateRunner` is synchronous and takes yes or no; what keeps it from
+// being the ordinary case is `placeProblem`, which runs first for every command
+// that would act on the answer.
+export function commandSucceedsInProject(projectRoot, command, args) {
+    const place = placeOf(projectRoot);
+    const shaped = place.kind === 'local'
+        ? { command, args }
+        : shapeForContainer(place.container, projectRoot, command, args, {});
+    const result = spawnSync(shaped.command, shaped.args, {
+        cwd: projectRoot,
+        // A round trip through the docker daemon is not the same wait as starting a
+        // local binary: the client has to reach the daemon, and the daemon has to
+        // start a process in a container that may be busy running the application.
+        // Ten seconds is right for `python3 -m pytest --version` here and is the
+        // kind of budget that turns a slow machine into "no runner available".
+        timeout: place.kind === 'local' ? 10_000 : 60_000,
+        env: { ...process.env },
+    });
+    return result.status === 0;
+}

package/dist/runner/placeAdvice.js

@@ -0,0 +1,52 @@
+// What to say when this project's test toolchain cannot be started (spec 36, §7).
+//
+// Half the value of the whole spec is here rather than in the adapter. A field
+// nobody discovers is a field nobody sets: the vibecoder whose gems live only
+// inside a container reads "Bundler failed to provision rspec-rails under
+// .unitbob/runners." — a sentence about a symptom, which sounds like "your
+// project is broken" and sends them off inventing workarounds.
+//
+// Two situations, one question, so they live in one function: the place is not
+// configured and something on this machine looks like the answer, or the place
+// is configured and the advice above just told somebody to run a command in the
+// wrong place.
+import { containersHolding } from "./docker.js";
+import { placeOf } from "./place.js";
+// The sentence to add to a message that has already decided to stop, or null
+// when there is nothing worth saying.
+//
+// Only ever called on the failure path. On a successful run `docker` is not
+// asked anything, so nobody without Docker pays for this and nobody with Docker
+// waits for it.
+export function placeAdvice(projectRoot) {
+    const place = placeOf(projectRoot);
+    // Already running in a container. Then the problem is not "which place" — it
+    // is that every manual command above (`bundle install`, `npm install --prefix
+    // .unitbob/runners`, `gem install bundler`, "activate your virtualenv") reads
+    // as "do this in your project folder", and doing it here would change nothing.
+    // One sentence covers all of them, and none of them has to be rewritten.
+    if (place.kind === 'docker') {
+        return (`This project's tests run inside the container \`${place.container}\`, so any command suggested above ` +
+            `has to be run in there, not here: \`docker exec -it ${place.container} <command>\`.\n` +
+            // The two edge cases the spec asks to be named rather than solved. Both
+            // look like an ordinary install failure and neither is: nothing in the
+            // output says "the mount is read-only" or "these files belong to someone
+            // else", so the reader is left staring at a permission error with no
+            // reason to suspect the container is why.
+            'If it failed on permissions rather than on a missing package, two things are worth checking: that ' +
+            'the project is not mounted read-only, and — on a Linux host — that the files under `.unitbob/` are ' +
+            'still yours, since a container writing there creates them as `root`.');
+    }
+    const candidates = containersHolding(projectRoot);
+    if (candidates.length === 0)
+        return null;
+    const lines = candidates.map((found) => `  \`${found.name}\` — it sees this project as \`${found.projectRoot}\`\n` +
+        `      "exec": {"docker": {"container": ${JSON.stringify(found.name)}}}`);
+    // Several candidates are listed and none is picked. Guessing between `web` and
+    // `worker` is wrong on the first project that has both, and a wrong guess here
+    // is silent: the suite runs somewhere nobody meant it to.
+    return ("This project's tests do not run on this machine, and they may not be meant to. " +
+        `${candidates.length === 1 ? 'A running container already has this project mounted' : 'These running containers already have this project mounted'}` +
+        `:\n\n${lines.join('\n')}\n\n` +
+        `Add the line under the container you run your tests in to \`.unitbob.json\`, then run this again.`);
+}