unitbob 0.4.5 → 0.5.0

package/dist/files/guardrails.js

@@ -62,21 +62,31 @@ else
 end
 abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
 `;
-// Write the suite blob's guardrail file at its own (validated) relative path.
-// The Ruby boot kit is materialized only for the rspec runner — Vitest and
-// pytest runs need no connector-written support files here (the runtime
-// pytest.ini lives outside this directory and is written by the pytest runner).
+// Write every file of the suite blob at its own (validated) relative path. The
+// Ruby boot kit is materialized only for the rspec runner — Vitest and pytest
+// runs need no connector-written support files here (the runtime pytest.ini
+// lives outside this directory and is written by the pytest runner).
+//
+// Every file, not just the main one (spec 42, §6.4). The directory is wiped
+// first and only the main file was written back, so a published suite of four
+// files came back as one and the run that followed it silently protected a
+// quarter of what the map claimed.
 export function materializeGuardrails(projectRoot, suite) {
-    assertGuardrailPath(suite.suite_file.path);
+    const files = [suite.suite_file, ...(suite.suite_file.support_files ?? [])];
+    for (const file of files)
+        assertGuardrailPath(file.path);
     const dir = join(projectRoot, GUARDRAILS_DIR);
     rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir, { recursive: true });
-    const suitePath = join(projectRoot, suite.suite_file.path);
-    mkdirSync(dirname(suitePath), { recursive: true });
-    writeFileSync(suitePath, suite.suite_file.content);
+    const written = files.map((file) => {
+        const path = join(projectRoot, file.path);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, file.content);
+        return path;
+    });
     if (suite.runner_manifest.runner === 'rspec')
         materializeHelper(projectRoot);
-    return { suitePath };
+    return { suitePath: written[0], supportPaths: written.slice(1) };
 }
 // Both Ruby flows boot the same way: the check flow writes the boot kit next to
 // the suite here, the suite-build flow writes it right after the precheck.

package/dist/files/suiteBuild.js

@@ -82,12 +82,27 @@ export function branchRunner(output) {
     }
     return runner;
 }
+// What the reviewer actually read: the suite files, and the manifest that runs
+// them. Nothing else (spec 42, §4).
+//
+// `test_metadata` used to be in here, and the server's copy of this formula
+// stripped the review's own keys back out to match — two lists that had to stay
+// identical for ever or every upload would break. The real cost was elsewhere,
+// though: editing metadata declared the review stale. On noahsat-web,
+// 2026-08-12 the reviewer was right that the steps drive only `PATCH`, the fix
+// moved three `PUT` aliases into a deferred list, not one byte of the suite
+// moved — and the run still paid for re-binding the candidate and a second
+// reviewer pass, the most expensive step of the whole recipe, to satisfy the
+// reviewer's own finding.
+//
+// `stableJson` sorts object keys and does nothing else. The server's
+// `canonical_json` does the same, which is the only reason the two sides agree;
+// a normalization added on one side alone would break every upload.
 export function suiteCandidateDigest(output) {
     return createHash('sha256')
         .update(stableJson({
         suite_file: output.suite_file,
         runner_manifest: output.runner_manifest,
-        test_metadata: output.test_metadata,
     }))
         .digest('hex');
 }

package/dist/files/suiteBuildUpload.js

@@ -0,0 +1,71 @@
+import { readBehavioralReview } from "./suiteBuild.js";
+// What travels to the server, and what "published" means when it answers. One
+// module, because two commands ask those questions: `put-suite-build` sends the
+// batch, and `validate-build` sends the same batch as a dry run so the server's
+// verdict is about the exact bytes the publish will carry (spec 42, §3).
+//
+// A second assembly would be a second answer to "what are we uploading", and the
+// dry run would then be checking something the publish does not send — which is
+// worth less than not checking at all, because it reads as a verdict.
+// The three outcomes that leave a branch published and current: a new version, an
+// identical version already stored, or a reactivated one. Each returns the
+// identity to run. Everything else — a rejected branch, a branch the host could
+// not build, or a status this connector has never seen — fails closed and is
+// never run, so a newer server can never trick an older connector into running
+// something it does not understand.
+export const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
+// The answer a dry run gives to a branch it would accept. A server that does not
+// know `dry_run` answers one of `PUBLISHED` instead — which means it published —
+// and `validate-build` says so rather than reporting a check that passed.
+export const WOULD_PUBLISH = 'would_publish';
+// One branch, as the upload sends it. `source_digest` comes from the request,
+// never from the host's answer, so the host cannot claim a different map than
+// the branch was given.
+export function uploadItem(request, output, testMetadata) {
+    const sourceDigest = request.branches.find((branch) => branch.suite_kind === output.suite_kind)?.source_digest ?? '';
+    if (output.build_error) {
+        return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+    }
+    return {
+        suite_kind: output.suite_kind,
+        source_digest: sourceDigest,
+        artifacts: {
+            suite_file: output.suite_file,
+            runner_manifest: output.runner_manifest,
+            test_metadata: testMetadata,
+        },
+    };
+}
+// The behavioral branch's uploaded metadata, with the independent review and the
+// connector's own run evidence folded in.
+//
+// Throws for anything that leaves this branch unpublishable — a missing review,
+// one bound to a different candidate, a defect the review called not_supplied.
+// The caller turns that into one unpublished branch rather than a failed
+// command: a blocked review is a fact about the behavioral suite, and the
+// structural peer next to it is finished and correct. Sinking the whole upload
+// with it forced the one workaround this contract exists to prevent — hand-editing
+// the answer down to a single branch, which loses the peer candidate for real.
+export function withReview(config, request, output) {
+    const review = readBehavioralReview(config.projectRoot, output);
+    const probe = review.known_defect_probe;
+    const qualityReview = review.bdd_quality_review;
+    if (!qualityReview || typeof qualityReview !== 'object') {
+        throw new Error('The separate behavioral review must contain a bdd_quality_review object.');
+    }
+    if (request.known_defect_context.status === 'supplied' && probe?.status === 'not_supplied') {
+        throw new Error('A known defect was supplied to suite-prepare, but the behavioral review marked it not_supplied.');
+    }
+    return {
+        ...output.test_metadata,
+        bdd_quality_review: {
+            ...qualityReview,
+            candidate_digest: review.candidate_digest,
+        },
+        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
+        known_defect_probe: review.known_defect_probe,
+        known_defect_context: request.known_defect_context,
+        candidate_run: review.candidate_run,
+        ...(review.fixed_candidate_run ? { fixed_candidate_run: review.fixed_candidate_run } : {}),
+    };
+}

package/dist/files/workerPlan.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 export function workerPlanPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
@@ -33,8 +34,13 @@ export function readWorkerPlan(projectRoot) {
     }
     return parsed;
 }
+const RUBY_HARNESS = {
+    behavioral: '.unitbob/behavioral/step_definitions/00_unitbob_world.rb',
+    structural: '.unitbob/structural/unitbob_helper.rb',
+};
 export function validateWorkerPlanFiles(projectRoot) {
     const errors = [];
+    const rubyProject = detectStructuralRunner(projectRoot) === 'rspec';
     const plan = readWorkerPlan(projectRoot);
     let request;
     try {
@@ -86,12 +92,23 @@ export function validateWorkerPlanFiles(projectRoot) {
             errors.push(`${label}: done_when must be non-empty`);
         if (!isNonEmptyString(item?.harness_path))
             errors.push(`${label}: harness_path must be non-empty`);
-        const expectedHarness = item?.branch === 'behavioral'
-            ? '.unitbob/behavioral/step_definitions/00_unitbob_world.rb'
-            : item?.branch === 'structural' ? '.unitbob/structural/unitbob_helper.rb' : null;
+        // Both connector-owned harness files are Ruby, and only a Ruby project has
+        // them: `unitbob_helper.rb` boots Rails for RSpec, and the behavioral World
+        // is materialized for cucumber alone. Demanding them everywhere refused
+        // every Python and JS plan over a file that does not exist and would mean
+        // nothing if it did — the same mistake as the stack gate that reported a
+        // Python project as no stack at all. Found 2026-08-12.
+        //
+        // What is required of the other stacks is what the rule was ever about: the
+        // harness is connector territory, under `.unitbob/`, not a file in the
+        // project.
+        const expectedHarness = rubyProject ? RUBY_HARNESS[item?.branch] ?? null : null;
         if (expectedHarness && item.harness_path !== expectedHarness) {
             errors.push(`${label}: harness_path must name the connector-owned ${expectedHarness}`);
         }
+        if (!expectedHarness && isNonEmptyString(item?.harness_path) && !item.harness_path.startsWith('.unitbob/')) {
+            errors.push(`${label}: harness_path must be a connector-owned path under .unitbob/ (got "${item.harness_path}")`);
+        }
         if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
             errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
         }

package/dist/runner/bootcheck.js

@@ -1,6 +1,7 @@
 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 { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
 import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
@@ -86,9 +87,14 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // and the global `bundle` was standing right there the whole time.
     const localBundle = join(projectRoot, 'bin', 'bundle');
     const command = executable(localBundle) ? localBundle : '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)}`], {
         cwd: projectRoot,
-        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     }), 
     // A clean load says nothing on stdout and exits 0. Anything else is the
     // suite failing to start.
@@ -110,10 +116,25 @@ async function pytestBootCheck(projectRoot, deps) {
     // first: this check must not fail because a different step was skipped.
     mkdirSync(join(projectRoot, dirname(PYTEST_INI_FILE)), { recursive: true });
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
-    for (const python of ['python3', 'python']) {
-        const result = await attempt(deps, python, ['-m', 'pytest', '-c', PYTEST_INI_FILE, '--collect-only', '-q'], {
-            cwd: projectRoot,
-        });
+    // The same pytest the run will use, resolved once in `locateRunner` — the
+    // sidecar under `.unitbob/` when Unitbob installed one, else the machine's own
+    // interpreter. Asking a different interpreter than the run uses is how a check
+    // ends up answering about something nobody is going to execute.
+    //
+    // When it resolves nothing we still try the two interpreters by name rather
+    // than reporting `no_runner` from a lookup. The lookup is a prediction; the
+    // spawn is the fact, and a check that stops at its own prediction can be
+    // wrong in the one direction that costs the most — refusing a project that
+    // would have answered perfectly well.
+    const located = locateRunner(projectRoot, 'pytest');
+    const candidates = located
+        ? [located]
+        : [
+            { command: 'python3', args: ['-m', 'pytest'], env: undefined },
+            { command: 'python', args: ['-m', 'pytest'], env: undefined },
+        ];
+    for (const candidate of candidates) {
+        const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--collect-only', '-q'], { cwd: projectRoot, env: candidate.env });
         if (result === null)
             continue; // this interpreter is not on the machine
         return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
@@ -148,7 +169,10 @@ function pytestVerdict(code) {
 // turn away the majority. A file that is genuinely unparseable is caught here
 // anyway, since `vitest list` has to parse it.
 async function vitestBootCheck(projectRoot, deps) {
-    const local = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    // 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');
     // 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.
@@ -275,15 +299,17 @@ function hasProjectFrame(output, projectRoot, runner) {
     // asked of that file. Judging the whole output at once let `.venv/lib/...`
     // answer yes on the strength of its `lib/`, which is how a `TypeError` deep
     // inside a dependency came back as a defect in the user's code.
-    const ownDirs = runner === 'vitest' ? ['src'] : ['app', 'lib'];
-    const conventional = new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`);
+    const ownDirs = CONVENTIONAL_SOURCE_DIRS[runner] ?? [];
+    const conventional = ownDirs.length
+        ? new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`)
+        : null;
     for (const line of output.split('\n')) {
         // Wherever a dependency is installed, it is not this project's code — and
         // that has to be decided before anything below gets a chance to say yes.
         if (INSTALLED_DEPENDENCY.test(line))
             continue;
         // The conventional homes of business code, relative or absolute.
-        if (conventional.test(line))
+        if (conventional?.test(line))
             return true;
         if (line.includes(projectRoot))
             return true;
@@ -303,6 +329,18 @@ function hasProjectFrame(output, projectRoot, runner) {
     }
     return false;
 }
+// Where each stack conventionally keeps its business code. Only a stack that
+// really has such a convention gets an entry: `app/` and `lib/` are Rails, and
+// they used to be the fallback for everything that was not vitest, which meant a
+// Python project got Rails's layout applied to its stack traces. Python names no
+// fixed layout at all, so it is deliberately absent — the repository-file test
+// below is the answer there, and it is the more reliable one anyway.
+const CONVENTIONAL_SOURCE_DIRS = {
+    rspec: ['app', 'lib'],
+    cucumber: ['app', 'lib'],
+    vitest: ['src'],
+    'cucumber-js': ['src'],
+};
 // Where a dependency lives once installed — never the project's own code, in
 // any of the three languages. The last two are the languages' own installed
 // libraries: `…/lib/ruby/3.3.0/psych.rb` is a frame the `lib/` rule below would

package/dist/runner/precheck.js

@@ -1,18 +1,36 @@
-import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-const defaultDeps = {
-    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
-};
+import { defaultToolDeps, hasGemfileWith, locateRunner, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, } from "./toolchain.js";
+const defaultDeps = defaultToolDeps;
 const STACKS = 'Ruby on Rails + RSpec, JavaScript/TypeScript + Vitest, or Python + pytest';
 // Tried in this order, so a project carrying markers for more than one stack
 // resolves to the same runner on every run.
 const STRUCTURAL_RUNNERS = ['rspec', 'vitest', 'pytest'];
+// The file that says "this project is written in this language". Nothing here
+// asks whether the runner is installed — that is a separate question with a
+// separate answer, and merging the two is what made this gate lie.
+//
+// A project whose language is obvious but whose runner is missing used to fail
+// detection, and the caller then reported the only thing it had left: "this
+// project matches none of those stacks". That sentence was false — the project
+// was Python, it simply had no pytest — and it sent people to look for a problem
+// with their project instead of at the one command that fixes it. The runner is
+// now provisioned under `.unitbob/` (see `ensureStructuralRunner`), so the
+// question this gate answers is the one it can answer honestly: which language.
+const PYTHON_MARKERS = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
+function looksLikePython(projectRoot) {
+    return PYTHON_MARKERS.some((name) => existsSync(join(projectRoot, name)));
+}
+const STACK_MARKERS = {
+    rspec: (projectRoot) => hasGemfileWith(projectRoot, /\brails\b/),
+    vitest: (projectRoot) => existsSync(join(projectRoot, 'package.json')),
+    pytest: looksLikePython,
+};
 // Which structural runner this project's markers select, or null when none do.
 // The gate below walks the same list: "is any stack present" and "which one is
 // it" must never be able to disagree.
-export function detectStructuralRunner(projectRoot, deps = defaultDeps) {
-    return STRUCTURAL_RUNNERS.find((runner) => validateStack(projectRoot, runner, deps).ok) ?? null;
+export function detectStructuralRunner(projectRoot, _deps = defaultDeps) {
+    return STRUCTURAL_RUNNERS.find((runner) => STACK_MARKERS[runner]?.(projectRoot)) ?? null;
 }
 // The BDD runner for a structural stack. One project, one language: the
 // behavioral peer follows the stack already detected instead of probing the
@@ -33,7 +51,10 @@ export function detectBddRunner(projectRoot, deps = defaultDeps) {
     const structural = detectStructuralRunner(projectRoot, deps);
     return structural ? BDD_RUNNER_FOR_STACK[structural] ?? null : null;
 }
-// The generation-time gate: at least one supported stack must be present.
+// The generation-time gate: at least one supported stack must be present. It
+// says nothing about whether the runner is installed, because by the time that
+// matters the runner has been provisioned; `runnerReadyPrecheck` is the check
+// for that, and it runs straight after provisioning.
 export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
     const runner = detectStructuralRunner(projectRoot, deps);
     if (runner !== null)
@@ -43,6 +64,54 @@ export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
         message: `Unitbob guardrails support ${STACKS} only. This project matches none of those stacks.`,
     };
 }
+// Is the runner startable now, after provisioning has had its turn?
+//
+// Not the same question as `validateStack`, and the difference is the sidecar.
+// `validateStack` asks whether the *project* is set up for a stack — the right
+// question when a host has chosen one and nothing has been installed yet. This
+// asks whether anything on this machine can start the runner, which includes
+// the environment Unitbob just built under `.unitbob/`.
+//
+// Asking the first question in the second's place refuses a project we have
+// only just finished preparing: a JS project with no vitest of its own was
+// told to `npm i -D vitest` seconds after a working vitest was installed for
+// it. Found on the connector's own repository, 2026-08-12.
+export function runnerReadyPrecheck(projectRoot, runner, deps = defaultDeps) {
+    // Ruby is the one stack whose lookup can never come back empty — `bundle exec
+    // rspec` is always a command one could type — so readiness is the gem being
+    // resolvable, from the sidecar Gemfile or from the project's own.
+    const ready = runner === 'rspec'
+        ? locateRunner(projectRoot, 'rspec')?.source === 'sidecar' || projectProvidesRunner(projectRoot, 'rspec', deps)
+        : runnerAvailable(projectRoot, runner, deps);
+    if (ready)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `The ${runner} runner is not available: it is not installed in this project, and Unitbob could ` +
+            `not install one for itself under ${SIDECAR_DIR}/. Nothing was written and nothing was uploaded.`,
+    };
+}
+// Has Unitbob built this runner for this project already? One question, asked
+// the same way by every precheck that would otherwise advise the user to install
+// something they now have.
+//
+// Ruby needs the second half. Its sidecar is a Gemfile, and `provisionRspec`
+// writes that file *before* it runs bundler and leaves it in place when bundler
+// fails — so its mere existence says "we tried", not "it is there", and taking
+// it as proof would silence the rspec-rails advice exactly when the install
+// failed and the advice is what the user needs. Bundler rewrites the sidecar
+// lock on success, and the project's own lock cannot name a gem its Gemfile
+// lacks, so the gem appearing there is the first artefact that means it
+// resolves. The vitest side needs nothing extra: `locateVitest` tests the actual
+// `.bin/vitest` executable.
+function sidecarProvides(projectRoot, runner, deps = defaultDeps) {
+    if (locateRunner(projectRoot, runner, deps)?.source !== 'sidecar')
+        return false;
+    if (runner !== 'rspec')
+        return true;
+    const lock = join(projectRoot, SIDECAR_DIR, 'Gemfile.lock');
+    return existsSync(lock) && /\brspec-rails\s+\(/.test(readFileSync(lock, 'utf8'));
+}
 // Confirm the host-selected runner against local markers. A mismatch fails
 // closed: the caller writes no files and uploads nothing.
 //
@@ -56,9 +125,9 @@ export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
 export function validateStack(projectRoot, runner, deps = defaultDeps) {
     switch (runner) {
         case 'rspec':
-            return rubyPrecheck(projectRoot);
+            return rubyPrecheck(projectRoot, deps);
         case 'vitest':
-            return vitestPrecheck(projectRoot);
+            return vitestPrecheck(projectRoot, deps);
         case 'pytest':
             return pytestPrecheck(projectRoot, deps);
         case 'cucumber':
@@ -100,16 +169,14 @@ function jsBehavioralPrecheck(projectRoot) {
 // and message shape as the structural pytest precheck; pytest-bdd itself, if
 // missing, surfaces as a suite error from the run.
 function pythonBehavioralPrecheck(projectRoot, deps) {
-    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
-    if (!markers.some((name) => existsSync(join(projectRoot, name)))) {
+    if (!looksLikePython(projectRoot)) {
         return {
             ok: false,
             message: 'The behavioral (Gherkin) suite selected the Python stack, but this project has none of ' +
-                `${markers.join(', ')} — it does not look like a Python project.`,
+                `${PYTHON_MARKERS.join(', ')} — it does not look like a Python project.`,
         };
     }
-    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
-    if (!available) {
+    if (!runnerAvailable(projectRoot, 'pytest', deps)) {
         return {
             ok: false,
             message: 'The behavioral (Gherkin) suite selected the Python stack, but pytest is not importable in ' +
@@ -119,7 +186,7 @@ function pythonBehavioralPrecheck(projectRoot, deps) {
     }
     return { ok: true };
 }
-function rubyPrecheck(projectRoot) {
+function rubyPrecheck(projectRoot, deps) {
     if (!hasGemfileWith(projectRoot, /\brails\b/)) {
         return {
             ok: false,
@@ -129,7 +196,13 @@ function rubyPrecheck(projectRoot) {
     }
     // Specifically rspec-rails: the boot helper requires `rspec/rails`, so a
     // bare `rspec` gem passes nothing downstream — stop with the honest offer.
-    if (!hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
+    //
+    // Unless Unitbob already installed one for itself. The advice below asks the
+    // user to change their Gemfile, and that is the wrong sentence seconds after a
+    // working runner was provisioned under `.unitbob/`. `runnerReadyPrecheck`
+    // already knows this; this function used to send the reader back to the old
+    // answer regardless.
+    if (!sidecarProvides(projectRoot, 'rspec', deps) && !hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
         return {
             ok: false,
             message: "Unitbob guardrails need the rspec-rails gem, which is not in this project's " +
@@ -139,7 +212,7 @@ function rubyPrecheck(projectRoot) {
     }
     return { ok: true };
 }
-function vitestPrecheck(projectRoot) {
+function vitestPrecheck(projectRoot, deps) {
     const packageJson = join(projectRoot, 'package.json');
     if (!existsSync(packageJson)) {
         return {
@@ -147,7 +220,12 @@ function vitestPrecheck(projectRoot) {
             message: 'The JavaScript/TypeScript stack was selected, but this project has no package.json.',
         };
     }
-    const hasVitest = /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
+    // Same rule as the Ruby precheck above: a runner Unitbob installed for this
+    // project is a runner this project has. Without this the connector's own
+    // repository was told to `npm i -D vitest` seconds after a working vitest had
+    // been put under `.unitbob/` for it.
+    const hasVitest = sidecarProvides(projectRoot, 'vitest', deps) ||
+        /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
         existsSync(join(projectRoot, 'node_modules', '.bin', 'vitest'));
     if (!hasVitest) {
         return {
@@ -160,22 +238,20 @@ function vitestPrecheck(projectRoot) {
     return { ok: true };
 }
 function pytestPrecheck(projectRoot, deps) {
-    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
-    const found = markers.some((name) => existsSync(join(projectRoot, name)));
-    if (!found) {
+    if (!looksLikePython(projectRoot)) {
         return {
             ok: false,
             message: 'The Python stack was selected, but this project has none of ' +
-                `${markers.join(', ')} — it does not look like a Python project.`,
+                `${PYTHON_MARKERS.join(', ')} — it does not look like a Python project.`,
         };
     }
     // Spec 30 fails closed on runner availability: unlike marker files, pytest
-    // must actually be importable in the current interpreter, or every run would
-    // end as a "No module named pytest" suite error after files were written. We
-    // probe the same interpreters the pytest runner tries, in the same order, so
-    // the precheck and the run agree on whether pytest is runnable.
-    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
-    if (!available) {
+    // must actually be importable, or every run would end as a "No module named
+    // pytest" suite error after files were written. `runnerAvailable` asks the
+    // same question the run asks, of the same environments in the same order —
+    // the sidecar under `.unitbob/` first, then the machine's own interpreters —
+    // so the check and the run can never disagree about what is runnable.
+    if (!runnerAvailable(projectRoot, 'pytest', deps)) {
         return {
             ok: false,
             message: 'The Python stack was selected, but pytest is not importable in the current Python ' +
@@ -186,11 +262,3 @@ function pytestPrecheck(projectRoot, deps) {
     }
     return { ok: true };
 }
-function hasGemfileWith(projectRoot, pattern) {
-    for (const name of ['Gemfile', 'gems.rb']) {
-        const path = join(projectRoot, name);
-        if (existsSync(path) && pattern.test(readFileSync(path, 'utf8')))
-            return true;
-    }
-    return false;
-}