unitbob 0.5.0 → 0.6.0

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.`);
+}

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),
     };
 }