unitbob 0.7.1 → 0.7.3

package/dist/files/packets.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { graphNodes, methodNameOf } from "../surfaces/graph.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 import { surfacesPath } from "./mapBuild.js";
@@ -52,8 +52,7 @@ export function readPacketIndex(projectRoot) {
 // request, the workers are not, so a packet belongs to an entrypoint and two
 // entrypoints in one file share one packet.
 export function writeSuitePackets(projectRoot, request) {
-    const targets = targetsOf(request);
-    const lookup = buildLookup(projectRoot);
+    const targets = resolveTargets(projectRoot, request);
     const notes = new Map();
     // Regenerated whole, every run. A packet left over from a previous assignment
     // sits under an authoritative name with nothing on it saying how old it is.
@@ -63,15 +62,11 @@ export function writeSuitePackets(projectRoot, request) {
     const written = new Map();
     const refused = new Map();
     for (const target of targets) {
-        const sourceFile = lookup(target.entrypoint);
+        const sourceFile = target.source_file;
         if (!sourceFile) {
-            target.note = 'no single file in graph.json or surfaces.json answers to this name — find it yourself';
             count(notes, 'did not resolve to one file');
             continue;
         }
-        // The path travels even when the contents do not: a worker told which file
-        // to open has still been saved the search.
-        target.source_file = sourceFile;
         // Two entrypoints in one file get one packet, written once, referenced twice.
         if (!written.has(sourceFile) && !refused.has(sourceFile)) {
             const copied = copyPacket(projectRoot, sourceFile);
@@ -105,6 +100,63 @@ export function writeSuitePackets(projectRoot, request) {
         notes: [...notes].map(([note, count]) => `${count} × ${note}`),
     };
 }
+// Every entrypoint the request names, each with the file behind it when one file
+// answers. The one place a name is turned into a path: `writeSuitePackets` copies
+// what comes out of here, and `structuralSourceFiles` only reads it. Two
+// resolvers would be two chances to disagree about which file serves a name, and
+// the boot check and the packets have to be talking about the same files.
+//
+// The words for a name nothing answered to are set here rather than by the
+// caller, because they are part of the answer.
+function resolveTargets(projectRoot, request) {
+    const targets = targetsOf(request);
+    const lookup = buildLookup(projectRoot);
+    for (const target of targets) {
+        const sourceFile = lookup(target.entrypoint);
+        // The path travels even when the contents do not: a worker told which file
+        // to open has still been saved the search.
+        if (sourceFile)
+            target.source_file = sourceFile;
+        else
+            target.note = 'no single file in graph.json or surfaces.json answers to this name — find it yourself';
+    }
+    return targets;
+}
+// Spec 38, criterion 2. The source files the structural guardrails of this
+// request will import — the list the boot check loads instead of the project's
+// own tests. Computed from two artifacts already on this machine, so it costs no
+// token and no network call.
+//
+// A name nothing answered to is simply absent. That gap is already a visible
+// number — "the source behind N of M entrypoints" — and turning it into a
+// refusal would stop a run over a hole in the graph (see В3 of the requirements).
+export function structuralSourceFiles(projectRoot, request) {
+    const files = [];
+    for (const target of resolveTargets(projectRoot, request)) {
+        if (target.branch !== 'structural' || !target.source_file)
+            continue;
+        // Only a path that is plainly inside this checkout, and only a file that is
+        // really there. graph.json is written by a tool, not by us, and what comes
+        // out of here becomes an `import` statement — so an absolute path or a `..`
+        // would load something this project does not contain, and a name the graph
+        // kept after the file moved would fail to resolve.
+        //
+        // That last one is the whole reason this check exists. A stale graph entry
+        // reaches the runner as "Failed to resolve import" or "FileNotFoundError",
+        // which reads as a dependency that is not installed or a module that will
+        // not load — and the vibecoder would be sent to repair their code over a
+        // hole in *our* map. `writeSuitePackets` already refuses all three, in
+        // words, one file further down; here silence is right, because nothing reads
+        // this list but the probe.
+        if (isAbsolute(target.source_file) || target.source_file.split('/').includes('..'))
+            continue;
+        if (!existsSync(join(projectRoot, target.source_file)))
+            continue;
+        if (!files.includes(target.source_file))
+            files.push(target.source_file);
+    }
+    return files;
+}
 // The two names a request carries. Structural interfaces name methods
 // (`User#get_token`); behavioral capabilities name addresses (`POST /api/tokens`).
 // Both are entrypoints, both resolve to a file, and both produce the same kind

package/dist/files/workerPlan.js

@@ -3,7 +3,6 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { dirname, join } from 'node:path';
 import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
-import { branchWidth } from "./fanOut.js";
 export function workerPlanPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
 }
@@ -233,62 +232,9 @@ export function validateWorkerPlanFiles(projectRoot) {
         }
         for (const id of assigned.filter((id) => !expected.includes(id)))
             errors.push(`${branch}: capability ${id} was not assigned by the request`);
-        const cases = items.reduce((sum, item) => sum + (Array.isArray(item.planned_cases) ? item.planned_cases.length : 0), 0);
-        errors.push(...fanOutErrors(branch, items.length, cases));
     }
     return errors;
 }
-// Which assigned ids each branch of a plan actually took. Spec 37-3 weighs a
-// plan against the work it took on, never against the whole assignment: the
-// packets are built before anybody chooses a scope, and since criterion 2 both
-// branches may be narrowed, so the two are different jobs.
-export function takenIds(plan) {
-    const taken = new Map();
-    for (const item of Array.isArray(plan?.workers) ? plan.workers : []) {
-        if (!item || typeof item !== 'object' || Array.isArray(item) || !isNonEmptyString(item.branch))
-            continue;
-        const ids = taken.get(item.branch) ?? new Set();
-        for (const id of Array.isArray(item.capability_ids) ? item.capability_ids : []) {
-            if (isNonEmptyString(id))
-                ids.add(id);
-        }
-        taken.set(item.branch, ids);
-    }
-    return taken;
-}
-// Spec 37-3, criterion 1. Two things are checked, and only when the packets
-// exist to measure against: that the plan says what it divided, and that it did
-// not divide work that already fits in one worker.
-//
-// A run without packets has no measured work, and a rule with no measurement
-// behind it refuses nobody — the same policy the packets themselves follow.
-function fanOutErrors(branch, planned, cases) {
-    const width = branchWidth(branch, cases);
-    if (!width || planned === 0)
-        return [];
-    // A band, not a ceiling. Both ends are expensive and neither is safe: on the
-    // 2026-08-24 bench fifteen workers cost 28% more than the cheapest width, and
-    // one worker cost 85% more — and a single worker on the behavioral branch
-    // would have run 216 turns into a 150-turn fuse. Anywhere inside the band is
-    // within about a tenth of the cheapest, so this refuses only what costs.
-    //
-    // Nothing is restated in the plan to prove the coordinator did this division.
-    // Both halves are already in the file — the cases in `planned_cases`, the
-    // width as the length of the branch's slice list — so a `fan_out` record would
-    // be the same two numbers copied by hand, which is what spec 37-1 refused for
-    // `packet_paths`. The gate is the guarantee; `accept-worker-plan` prints the
-    // derivation next to it.
-    if (planned >= width.fewest && planned <= width.most)
-        return [];
-    const way = planned > width.most ? 'wide' : 'narrow';
-    return [
-        `${branch}: ${planned} slices for ${cases} planned cases is too ${way} — ` +
-            `${width.fewest}-${width.most} is the band, ${width.workers} the cheapest. ` +
-            `Each slice costs a whole opening context (26,065 tokens on that bench, re-read every turn), ` +
-            `and each slice fewer makes one conversation longer, which costs with the square of its ` +
-            `length. At ${width.workers} a worker of this branch runs about ${width.turns_each} turns.`,
-    ];
-}
 function assignmentIds(value) {
     const assignment = value;
     if (Array.isArray(assignment?.capabilities)) {

package/dist/runner/bootcheck.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable } from "../proc.js";
 import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
@@ -6,6 +6,7 @@ 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";
+import { VITEST_BOOT_CONFIG_FILE, vitestBootConfigSource } from "./vitest.js";
 const defaultDeps = {
     runCmd: (command, args, options) => runInProject(options.cwd, command, args, { timeoutMs: PROVISION_TIMEOUT_MS, env: options.env }),
 };
@@ -18,23 +19,29 @@ const DETAIL_LIMIT = 4_000;
 export const SIGNAL_STRENGTH = {
     rspec: 'Full signal on this stack: the check loads the very file the suite starts from, ' +
         'so whatever stops one stops the other.',
-    pytest: 'Partial signal on this stack: collection only imports what the tests import, so code no ' +
-        'test reaches was not checked — and it imports the whole test tree, so a failure may belong ' +
-        "to one of the project's own tests rather than to the suite that was about to be written.",
-    vitest: 'Weak signal on this stack: only test files are parsed and imported, and all of them — so a ' +
-        "failure may belong to one of the project's own tests. Type errors are not checked at all " +
-        '(vite and esbuild strip types without checking them), and a project with no tests yields ' +
-        'no signal.',
+    pytest: 'Full signal on the files it names: the check imports the very modules the guardrails of this ' +
+        "branch will import, and nothing else — none of this project's own tests are opened. Code that " +
+        'no guardrail imports was not looked at.',
+    vitest: 'Full signal on the files it names: the check imports the very modules the guardrails of this ' +
+        "branch will import, through this project's own vite configuration, and nothing else — none of " +
+        "the project's own tests are opened. Types are not checked (vite strips them without checking " +
+        'them), and code no guardrail imports was not looked at.',
 };
 // Does the suite for this stack get off the ground? One attempt, one answer.
-export async function bootCheck(projectRoot, runner, deps = defaultDeps) {
+//
+// `sourceFiles` are the project's own source files this branch's guardrails will
+// import, resolved from the map (spec 38). They are what gets loaded on the two
+// stacks that have no boot file of their own — never the project's test tree.
+// Ruby ignores the list: its helper is the suite's real first line and already
+// pulls the application up behind it.
+export async function bootCheck(projectRoot, runner, sourceFiles, deps = defaultDeps) {
     switch (runner) {
         case 'rspec':
             return rubyBootCheck(projectRoot, deps);
         case 'pytest':
-            return pytestBootCheck(projectRoot, deps);
+            return pytestBootCheck(projectRoot, sourceFiles, deps);
         case 'vitest':
-            return vitestBootCheck(projectRoot, deps);
+            return vitestBootCheck(projectRoot, sourceFiles, deps);
         default:
             return { status: 'not_checked', reason: 'no_runner' };
     }
@@ -80,7 +87,7 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // executable makes `spawn` throw, `attempt` return null, and the answer come
     // back `no_runner`: "no runner available to load your suite with", said to
     // someone whose bundler is installed and working. That is the mistake
-    // `runner_too_old` and `runner_could_not_answer` were added to stop making,
+    // `runner_could_not_answer` was added to stop making,
     // and the global `bundle` was standing right there the whole time.
     const command = executable(join(projectRoot, 'bin', 'bundle')) ? 'bin/bundle' : 'bundle';
     // When Unitbob installed rspec-rails for itself, the gems this helper needs
@@ -106,9 +113,11 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // suite failing to start.
     (result) => (result.code === 0 ? 'ok' : 'broken'));
 }
-// Python: `pytest --collect-only` imports every test module, which is what the
-// run would do first. It sees import errors in code the tests reach, and only
-// there — recorded as a limitation rather than dressed up as completeness.
+// Python: run one test file of our own, which imports the modules the
+// guardrails will import. Not `--collect-only`, and not the project's test tree:
+// what the run would do first is import *our* suite's targets, and asking pytest
+// to collect everything it can find asks about files this product never touches
+// (spec 38, criterion 1).
 //
 // `-c` with an empty-addopts config, exactly as `runPytestSuite` does and for
 // exactly its reason: the project's own `addopts` (`--cov`, `-n auto`) must not
@@ -117,7 +126,9 @@ async function loadRubyHelper(projectRoot, helper, deps) {
 // a `--cov` flag. The run path had already solved this; the check had not
 // inherited the solution, which also made it *stricter* than the thing it
 // predicts, the one rule this whole check is built on.
-async function pytestBootCheck(projectRoot, deps) {
+async function pytestBootCheck(projectRoot, sourceFiles, deps) {
+    if (sourceFiles.length === 0)
+        return { status: 'not_checked', reason: 'nothing_to_load' };
     // Its own directory, rather than relying on `materializeHelper` having run
     // first: this check must not fail because a different step was skipped.
     mkdirSync(join(projectRoot, dirname(PYTEST_INI_FILE)), { recursive: true });
@@ -139,13 +150,19 @@ async function pytestBootCheck(projectRoot, deps) {
             { 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));
-    }
-    return { status: 'not_checked', reason: 'no_runner' };
+    return withProbe(projectRoot, { [PYTEST_PROBE_FILE]: pytestProbeSource(sourceFiles) }, async () => {
+        for (const candidate of candidates) {
+            // The probe's path is passed explicitly, and it has to be: `.unitbob` is a
+            // hidden directory, which pytest's default `norecursedirs` skips. Without
+            // the path it would collect the project's tests and not ours — the exact
+            // mistake this spec removes.
+            const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--rootdir', '.', PYTEST_PROBE_FILE, '-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));
+        }
+        return { status: 'not_checked', reason: 'no_runner' };
+    });
 }
 // pytest's own exit vocabulary, used rather than "zero or not". The distinction
 // that matters is between "your code did not load" and "pytest itself could not
@@ -155,8 +172,9 @@ function pytestVerdict(code) {
     // unreachable — but "no exit code" can only ever mean "we learned nothing".
     if (code === null)
         return 'runner_could_not_answer';
-    // 5 — collected nothing. A project that came to Unitbob *for* tests is the
-    // typical customer, not a defect.
+    // 5 — collected nothing. Since spec 38 the only file offered for collection is
+    // our own probe, so this now means "our probe was not collected", not "this
+    // project has no tests". Still not a verdict on the code either way.
     if (code === 5)
         return 'nothing_to_load';
     // 3 — internal error, 4 — bad usage. Both are about the invocation, not the
@@ -165,16 +183,34 @@ function pytestVerdict(code) {
         return 'runner_could_not_answer';
     return code === 0 ? 'ok' : 'broken';
 }
-// JS/TS: `vitest list` parses and imports the test files, which is the closest
-// thing this stack has to a boot.
+// JS/TS: run one test file of our own, which imports the source files the
+// guardrails will import.
+//
+// It used to be `vitest list`, which parses and imports *every* test file the
+// project has. That answered about somebody else's tests: a jest project came
+// back "found a defect that stops your test suite from starting" because its own
+// suites, green under jest, do not define `describe` under vitest. We do not
+// need the project's tests — we write our own — so we stopped opening them
+// (spec 38, criterion 1).
+//
+// Why a test file rather than a plain import: a test runner has no "load this
+// module and tell me if it exploded" command, and a bare `node` cannot stand in,
+// because TypeScript, JSX, path aliases and bundler plugins are exactly what
+// vite resolves from the project's own config. So the probe is a legal vitest
+// test that asserts nothing and imports everything named. Ruby has done the same
+// since spec 29, through `unitbob_helper.rb`.
 //
 // `tsc --noEmit` is deliberately not used. It answers a different question —
 // are the types sound — and a project with a hundred type errors runs perfectly
 // well, because vite, esbuild and tsx strip types without checking them. Type
 // errors accumulate for years in healthy codebases; calling that "broken" would
 // 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) {
+// anyway, since the probe's import has to parse it.
+async function vitestBootCheck(projectRoot, sourceFiles, deps) {
+    // Nothing the map resolved to a file, so there is nothing to import. That is a
+    // hole in the graph, not a broken application, and the run carries on.
+    if (sourceFiles.length === 0)
+        return { status: 'not_checked', reason: 'nothing_to_load' };
     // 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 ?? 'node_modules/.bin/vitest';
@@ -183,52 +219,107 @@ async function vitestBootCheck(projectRoot, deps) {
     // user's project is not this check's business.
     //
     // `executable`, not `existsSync`, and there is no fallback to go to: an
-    // unrunnable binary sends `spawn` into EACCES, `supportsList` reads that as
-    // "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.
+    // unrunnable binary sends `spawn` into EACCES and there is nothing left to
+    // ask. `no_runner` is the honest answer: there is no vitest this check can
+    // invoke.
     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
-    // doing two unhelpful things: reporting "No test files found" on a project
-    // that plainly has tests, and — when a file happened to match — starting watch
-    // mode and hanging until the timeout killed it, two minutes for nothing.
-    //
-    // Neither is `broken`, so no healthy project was ever refused. But a check
-    // that quietly answers about the wrong thing is worse than one that says it
-    // did not run, so ask the version first and decline outright when the
-    // subcommand does not exist.
-    // Not `no_runner`: vitest is installed and works, it simply cannot be asked
-    // this question. Telling someone "no runner available" while it sits in their
-    // node_modules sends them to fix the wrong thing.
-    if (!(await supportsList(projectRoot, local, deps))) {
-        return { status: 'not_checked', reason: 'runner_too_old' };
-    }
-    const result = await attempt(deps, local, ['list'], { cwd: projectRoot });
-    return classify(projectRoot, 'vitest', result, (proc) => {
-        if (proc.code === 0)
-            return 'ok';
-        if (/no test files found/i.test(`${proc.stdout}\n${proc.stderr}`))
-            return 'nothing_to_load';
-        return 'broken';
+    return withProbe(projectRoot, {
+        [VITEST_PROBE_FILE]: vitestProbeSource(sourceFiles),
+        [VITEST_BOOT_CONFIG_FILE]: vitestBootConfigSource(projectRoot, VITEST_PROBE_FILE),
+    }, async () => {
+        // `run`, which every version of vitest has. The version probe that used to
+        // stand here existed only for the `list` subcommand, which arrived in 2.1 —
+        // with it goes the `runner_too_old` answer, and with that the case where a
+        // perfectly good runner was declined for its age.
+        const result = await attempt(deps, local, ['run', '--config', VITEST_BOOT_CONFIG_FILE], { cwd: projectRoot });
+        return classify(projectRoot, 'vitest', result, (proc) => {
+            if (proc.code === 0)
+                return 'ok';
+            // Our own probe was not collected. It says nothing about the project's
+            // code, so it must not read as a verdict on it.
+            if (/no test files found/i.test(`${proc.stdout}\n${proc.stderr}`))
+                return 'nothing_to_load';
+            return 'broken';
+        });
     });
 }
-// The first Vitest that has a `list` subcommand. Below this it is a filter.
-const VITEST_LIST_FROM = { major: 2, minor: 1 };
-// `vitest --version` prints e.g. `vitest/1.6.0 darwin-arm64 node-v25.2.1`. A
-// version we cannot read is treated as unsupported: guessing wrong here costs
-// either a silent non-answer or a two-minute hang, and both are worse than
-// saying plainly that the check did not run.
-async function supportsList(projectRoot, binary, deps) {
-    const result = await attempt(deps, binary, ['--version'], { cwd: projectRoot });
-    if (!result || result.code !== 0)
-        return false;
-    const found = /vitest\/(\d+)\.(\d+)/i.exec(`${result.stdout}\n${result.stderr}`);
-    if (!found)
-        return false;
-    const [major, minor] = [Number(found[1]), Number(found[2])];
-    return major > VITEST_LIST_FROM.major || (major === VITEST_LIST_FROM.major && minor >= VITEST_LIST_FROM.minor);
+// The probe: one test that asserts nothing and imports everything the map named.
+//
+// The vitest probe lives beside the generated suite because that is where the
+// suite's own imports will resolve from; `materializeGuardrails` wipes that
+// directory before writing a suite, and by then the probe is long gone.
+const VITEST_PROBE_FILE = `${GUARDRAILS_DIR}/__unitbob_boot.test.mjs`;
+// `test_` first, on purpose: pytest collects a file by that prefix whatever the
+// project's own `python_files` setting says.
+const PYTEST_PROBE_FILE = `${GUARDRAILS_DIR}/test_unitbob_boot.py`;
+// Every file this check puts in somebody's project, written together and removed
+// together whatever happens — the way `worldProbe` treats its own. One of them
+// left behind would be collected by the project's next test run, and changing
+// what that run does is not ours to do.
+//
+// Both stacks go through here, so the write and the removal cannot drift apart
+// on one of them.
+async function withProbe(projectRoot, files, ask) {
+    for (const [relativePath, source] of Object.entries(files)) {
+        const path = join(projectRoot, relativePath);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, source);
+    }
+    try {
+        return await ask();
+    }
+    finally {
+        for (const relativePath of Object.keys(files))
+            rmSync(join(projectRoot, relativePath), { force: true });
+    }
+}
+// Relative from the probe, which sits two levels down (`.unitbob/structural/`).
+// The empty test is not decoration: vitest fails a file that declares none, and
+// `globals: true` in the config we write is what lets it be named without an
+// import (see `writeVitestBootConfig`).
+function vitestProbeSource(sourceFiles) {
+    const imports = sourceFiles.map((file) => `import ${JSON.stringify(`../../${file}`)};`).join('\n');
+    return `// Written by the unitbob connector before the boot check — do not edit.
+${imports}
+
+test('the modules our guardrails import all load', () => {});
+`;
+}
+// Python imports modules, not files, so the probe does the translation itself.
+// The module is registered in `sys.modules` before it is executed, because a
+// module that is not there yet cannot be the target of its own relative
+// imports.
+//
+// This is the one part of spec 38 that no live project has exercised: there was
+// no Python project on the bench. Worth watching on the first Python run.
+function pytestProbeSource(sourceFiles) {
+    return `# Written by the unitbob connector before the boot check — do not edit.
+import importlib.util
+import pathlib
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+TARGETS = ${JSON.stringify(sourceFiles)}
+
+
+def test_the_modules_our_guardrails_import_all_load():
+    for rel in TARGETS:
+        # A path we cannot build a module out of is our resolution falling
+        # short, never this project's code, so it is passed over in silence.
+        # Blaming somebody's application for a name our own map handed us is
+        # the whole mistake this check was rewritten to stop making.
+        if not rel.endswith(".py"):
+            continue
+        name = rel[:-3].replace("/", ".")
+        spec = importlib.util.spec_from_file_location(name, ROOT / rel)
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        spec.loader.exec_module(module)
+`;
 }
 // Runs one command, turning "this binary is not on the machine" into null (the
 // caller decides whether that means `no_runner` or "try the next interpreter")

package/dist/runner/precheck.js

@@ -262,12 +262,19 @@ function vitestPrecheck(projectRoot, deps) {
     const hasVitest = sidecarProvides(projectRoot, 'vitest', deps) ||
         /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
         existsSync(join(projectRoot, 'node_modules', '.bin', 'vitest'));
+    // What the project runs its own tests with is not asked here and is not a
+    // reason to stop (spec 38): we never open those tests, so jest, mocha or
+    // nothing at all is none of our business. The only question is whether there
+    // is a vitest to run *our* guardrails with — and suite-prepare installs one
+    // under `.unitbob/` when there is not, which is why this sentence is not
+    // reached on the build path at all. It stands for `run` and `run-local`,
+    // where nothing has been provisioned yet.
     if (!hasVitest) {
         return {
             ok: false,
-            message: 'JS/TS guardrails require Vitest (Jest is not supported in MVP v2), and vitest was not ' +
-                "found in this project's package.json or node_modules. Offer the user to add it " +
-                '(`npm i -D vitest`); change dependencies only with their consent, then retry.',
+            message: 'Unitbob runs its own guardrails with Vitest, and no vitest was found in this project\'s ' +
+                'package.json or node_modules — nor one installed by Unitbob under `.unitbob/`. Offer the ' +
+                'user to add it (`npm i -D vitest`); change dependencies only with their consent, then retry.',
         };
     }
     return { ok: true };

package/dist/runner/vitest.js

@@ -10,6 +10,12 @@ export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
 // the project has its own config. Connector-owned: never stored in Rails, never
 // part of the suite digest.
 export const VITEST_CONFIG_FILE = join('.unitbob', 'vitest.config.mjs');
+// The boot check's own config (spec 38), kept in a separate file from the one
+// above rather than shared with it. The two answer different questions and are
+// alive at different moments — the run's config names the branch's suite files
+// and is rewritten immediately before every run, so a boot check that reused it
+// would either be overwritten or leave the run pointing at a probe.
+export const VITEST_BOOT_CONFIG_FILE = join('.unitbob', 'vitest.boot.config.mjs');
 // The project configs we inherit from, most specific first. Vitest reads a
 // project's own config even when we pass `--config`, so we must merge ours with
 // it rather than replace it (plugins, path aliases and resolve settings the
@@ -79,12 +85,21 @@ export async function runVitestSuite(projectRoot, suitePaths) {
 // the branch's files have to be in `include` or nothing is collected, and the
 // names a worker gives its slice are not something to bet a whole run on.
 function writeMergedConfig(projectRoot, suitePaths) {
-    const projectConfig = PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
     const path = join(projectRoot, VITEST_CONFIG_FILE);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, configSource(projectConfig, suitePaths));
+    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run'));
     return ['--config', VITEST_CONFIG_FILE];
 }
+// The same config, shaped for the boot check's probe (spec 38). Returned as text
+// rather than written, because the boot check owns the lifetime of every file it
+// puts in the project: it writes them together and removes them together, and a
+// writer here would take half of that away from the one place that can see it.
+export function vitestBootConfigSource(projectRoot, probePath) {
+    return configSource(projectConfigOf(projectRoot), [probePath], 'boot');
+}
+function projectConfigOf(projectRoot) {
+    return PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
+}
 // The .unitbob/ config sits one level below the project root, so the project
 // config is a `../` import. A function-form config is resolved first, and
 // everything the project set — plugins, aliases, setup files, environment — is
@@ -101,21 +116,41 @@ function writeMergedConfig(projectRoot, suitePaths) {
 // ERR_MODULE_NOT_FOUND before a single test is collected, on exactly the
 // projects the sidecar exists for. A spread does the same job with no import,
 // and `defineConfig` is a typing helper that buys a generated file nothing.
-function configSource(projectConfig, suitePaths) {
-    const include = `include: ${JSON.stringify(suitePaths)}`;
+// `mode` is the boot check's two differences from the run, and they go together:
+// globals on, and a workspace refused. See `vitestBootConfigSource`.
+function configSource(projectConfig, suitePaths, mode) {
+    // After the project's own `test`, never before it: ours has to win.
+    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}include: ${JSON.stringify(suitePaths)}`;
     const header = '// Written by the unitbob connector before each vitest run — do not edit.';
     if (!projectConfig) {
         return `${header}
-export default { test: { ${include} } };
+export default { test: { ${settings} } };
 `;
     }
+    // Globals, because the probe lives in `.unitbob/structural/`: an
+    // `import { test } from 'vitest'` there resolves by walking up from that
+    // directory, which never reaches `.unitbob/runners/node_modules` — where the
+    // vitest we installed for a project that had none is kept. We write this file,
+    // so we turn the globals on and the probe needs no import at all.
+    //
+    // A workspace is dropped for a harder reason. With `test.projects` (or the
+    // older `test.workspace`) set, the root `include` stops deciding anything and
+    // vitest runs each sub-project's own test files — which would open the
+    // project's tests again through the back door, the one thing spec 38 removes.
+    const narrow = mode === 'boot'
+        ? `
+const { projects, workspace, ...test } = base.test ?? {};
+`
+        : `
+const test = base.test ?? {};
+`;
     return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
-
-export default { ...base, test: { ...(base.test ?? {}), ${include} } };
+${narrow}
+export default { ...base, test: { ...test, ${settings} } };
 `;
 }

package/dist/verbs/suitePrepare.js

@@ -1,8 +1,7 @@
 import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
-import { branchWorkloads, workloadLine } from "../files/fanOut.js";
-import { PACKETS_DIR, writeSuitePackets } from "../files/packets.js";
+import { PACKETS_DIR, structuralSourceFiles, writeSuitePackets, } from "../files/packets.js";
 import { movePreviousRunAside, recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bddStepLoading } from "../runner/bdd.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
@@ -68,7 +67,7 @@ export async function suitePrepare(config, args = [], deps) {
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
         confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
-        bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
+        bootCheck: (projectRoot, runner, sourceFiles) => bootCheck(projectRoot, runner, sourceFiles),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
         ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
         worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
@@ -131,30 +130,10 @@ export async function suitePrepare(config, args = [], deps) {
             throw new ToolchainUnavailableError(ready.message ?? `The ${check.runner} runner is not available.`, config.projectRoot);
         }
     }
-    // Spec 32-6. Before anything is fetched or written, find out whether the suite
-    // would get off the ground at all. It runs here, after the boot helper exists
-    // and before the network, so a project whose suite cannot start costs one
-    // command instead of a full generation.
-    //
-    // There is no `--on-broken-boot` flag and no mode. The decision is not a
-    // policy we could reasonably let a user set — it follows from the fact: we
-    // tried to load the thing the suite starts with, it did not load, therefore
-    // not one test would reach its first assertion. Debugging generation against a
-    // knowingly dead project is our problem, not the vibecoder's.
     // The stack the precheck just identified, rather than a second detection of
     // the same thing: on Python that would shell out to pytest all over again.
+    // Used further down, where the boot check now runs.
     const structuralRunner = check.runner ?? null;
-    const boot = await actual.bootCheck(config.projectRoot, structuralRunner);
-    if (boot.status === 'broken') {
-        // "Your environment is not ready" is the one of the two that a container can
-        // answer — the toolchain is missing here and may be sitting in one. A defect
-        // found in the code is a defect wherever it runs, and offering a container
-        // for it would be the noise this spec is trying to remove.
-        throw boot.cause === 'environment_not_ready'
-            ? new ToolchainUnavailableError(bootFinding(boot, structuralRunner), config.projectRoot)
-            : new Error(bootFinding(boot, structuralRunner));
-    }
-    actual.stdout.write(bootFinding(boot, structuralRunner));
     const packets = await actual.getSuitePacketsBatch();
     // Spec 32-1: Zero-touch sidecar provision for behavioral BDD runners during build preflight.
     // A `fixable` outcome (no package manager available to install the runner) is an infrastructure
@@ -228,8 +207,43 @@ export async function suitePrepare(config, args = [], deps) {
         else
             blockedNotices.push(`  ${packet.suite_kind}: ${envelopeBlockedReason(packet, runner)}`);
     }
+    // Spec 32-6, moved down by spec 38. Before anything is written and before a
+    // single token is spent, find out whether the code this branch's guardrails
+    // will import actually loads.
+    //
+    // Here rather than at the top of the verb, because here the list of those
+    // files exists: it is resolved from the branches that were just assembled,
+    // out of this machine's own graph and route inventory. Nothing is lost by
+    // waiting — `getSuitePacketsBatch` is a GET that writes nothing and costs
+    // nothing, and the generator, which is where the money starts, does not run
+    // until `request.json` is written below.
+    //
+    // What is gained is that a failure here takes one branch and not the run. The
+    // behavioral peer has a runner of its own, touches none of these files, and
+    // used to die of a verdict that was never about it.
+    // Only when there is a branch to check. Ruby's helper ignores the file list
+    // and boots the application for itself, so asking with no structural branch in
+    // the run would start Rails to answer a question nobody put — and a `broken`
+    // answer would then report a branch this build never had.
+    const bootNotices = [];
+    const structuralIndex = branches.findIndex((branch) => branch.suite_kind === 'structural');
+    if (structuralIndex !== -1) {
+        const boot = await actual.bootCheck(config.projectRoot, structuralRunner, structuralSourceFiles(config.projectRoot, { branches }));
+        if (boot.status === 'broken') {
+            branches.splice(structuralIndex, 1);
+            bootNotices.push(bootStop(boot, structuralRunner));
+        }
+        else {
+            actual.stdout.write(bootFinding(boot, structuralRunner));
+        }
+    }
+    // Every reason a branch is not here, in one place. A run can lose its last
+    // branch to any of the three and the reader needs the one that applies to
+    // them — printing only the envelope reasons left a jest project reading an
+    // empty list under "no suite branch can be built".
     if (branches.length === 0) {
-        throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\nNothing was written and nothing was uploaded.`);
+        const why = [...bootNotices, ...blockedNotices, ...fixableNotices].join('\n');
+        throw new Error(`No suite branch can be built this run:\n${why}\nNothing was written and nothing was uploaded.`);
     }
     const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
     // Spec 37-1. The assignment names entrypoints; the packets are the files
@@ -280,7 +294,6 @@ export async function suitePrepare(config, args = [], deps) {
             'the request that was just replaced.\n');
     }
     actual.stdout.write(packetNotice(request.project_root, sourcePackets));
-    actual.stdout.write(workloadNotice(request.project_root));
     actual.stdout.write(`Next: build ${branches.length === 1 ? 'the' : 'both'} peer ${branches.length === 1 ? 'suite' : 'suites'} (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
         `write your answer to ${request.output_path} as a branches array — one entry per branch named above, and a branch you cannot ` +
         `finish says so in its own entry rather than being left out of the array. Run each locally with \`unitbob run-local\` (the same ` +
@@ -308,6 +321,15 @@ export async function suitePrepare(config, args = [], deps) {
                 'finds its step files — it has no strategy of that name. Nothing here tells you what to call ' +
                 'them, and this connector will not be able to run the branch either.\n');
     }
+    // Same shape as the two notices below it, and the same rule: the branch that
+    // could not be prepared drops out, its peer is untouched, and the reason is
+    // printed rather than swallowed.
+    if (bootNotices.length > 0) {
+        actual.stdout.write('\nThe code-structure suite was left out of this run — the source files its guardrails would ' +
+            'import did not load. None of your own tests were opened; only the files the map named:\n' +
+            bootNotices.join('\n') +
+            '\n');
+    }
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.
     if (setupNotices.length > 0) {
@@ -366,22 +388,6 @@ function packetNotice(projectRoot, packets) {
         ` (${packets.notes.join('; ')}). ` +
         `Each says why in ${where}/index.json.\n`);
 }
-// Spec 37-3, criterion 1. The size of the work, printed before the plan exists,
-// because that is the only moment it can decide anything: the packets are built
-// from the request's entrypoints, and the entrypoints are known before the
-// workers are. A number that arrives after the plan is a number the plan was
-// not made from.
-function workloadNotice(projectRoot) {
-    const loads = branchWorkloads(projectRoot);
-    if (loads.length === 0)
-        return '';
-    return ('\nHow much each branch has to read, over the whole assignment and before you narrow it:\n' +
-        loads.map(workloadLine).join('') +
-        'This does not set how many workers a branch gets, and that is worth knowing before you plan: ' +
-        'on the bench of 2026-08-24 the branch with three times the source spent half the turns. What ' +
-        'sets the width is how many cases you intend to write, so it is decided by the plan and ' +
-        'checked by `accept-worker-plan`, which prints the band it accepted.\n');
-}
 // The runner's own rule for which step files it will load, in the words of the
 // side that loads them (spec ask-before-you-spend, §3.2). The same object is in `request.json`, on
 // the behavioral branch; this is the copy the coordinator sees without opening a
@@ -400,62 +406,62 @@ function stepLoadingNotice(runner, loading) {
         loading.requirements.join('\n  - ') +
         '\nThis is also in `request.json`, on the behavioral branch, as `step_loading`.\n');
 }
-// What the boot check found, in the vibecoder's terms. Printed on every run,
-// including the quiet ones: "we looked and it starts" and "we could not look"
-// are both worth a line, and a check nobody hears about is a check nobody
-// trusts.
+// What the boot check found when it found nothing wrong, in the vibecoder's
+// terms. Printed on every such run, including the quiet ones: "we looked and it
+// starts" and "we could not look" are both worth a line, and a check nobody
+// hears about is a check nobody trusts.
 //
-// A stop here is a finding, not a refusal, and the wording has to carry that.
-// "We found the defect that stops your suite from starting" and "we could not
-// build your suite" describe the same event and leave the reader in completely
-// different places.
+// The third answer, `broken`, is the only one that changes what gets built, so
+// it goes to `bootStop` and is printed where every other missing branch is
+// explained.
 function bootFinding(boot, runner) {
-    // Both halves of "what this answer is worth" travel together, on every
-    // outcome. Splitting them is how the stack caveat came to be missing from
-    // `broken`, and pinning `STRUCTURAL_ONLY` to `ok` alone would have repeated
-    // that in the same breath as the fix: on Rails the stack caveat reads
-    // "whatever stops one stops the other", which is an unscoped claim about a
-    // branch nobody asked — loudest exactly where the run stops for both.
-    // Empties are dropped rather than joined blindly, so a runner with no caveat
-    // of its own does not leave a blank line behind.
-    const caveat = [runner ? SIGNAL_STRENGTH[runner] : '', runner ? STRUCTURAL_ONLY : '']
-        .filter(Boolean)
-        .map((line) => `\n${line}`)
-        .join('');
+    const caveat = caveatFor(runner);
     if (boot.status === 'ok') {
         return `Checked that the suite can start: it does.${caveat}\n`;
     }
-    if (boot.status === 'not_checked') {
-        // Not checked is not broken, and nothing downstream may treat it as such.
-        // Conflating the two would block honest projects — the whole reason this
-        // state is named for what happened rather than for what we know.
-        const said = boot.detail ? `\n\n  ${boot.detail}\n` : '';
-        return `${NOT_CHECKED_REASON[boot.reason]}${said} Generation continues.${caveat}\n`;
-    }
-    const headline = boot.cause === 'defect_in_code'
-        ? 'Found a defect that stops your test suite from starting.'
-        : 'Your test suite cannot start yet — its environment is not ready.';
-    // The runner's own words. Everything else on screen is ours; this line is
-    // the one the vibecoder can paste into a search.
+    // Not checked is not broken, and nothing downstream may treat it as such.
+    // Conflating the two would block honest projects — the whole reason this
+    // state is named for what happened rather than for what we know.
+    //
+    // `broken` cannot arrive here: it is the one answer that changes what gets
+    // built, so it goes to `bootStop` and is printed as the reason a branch is
+    // missing.
+    const said = boot.detail ? `\n\n  ${boot.detail}\n` : '';
+    return `${NOT_CHECKED_REASON[boot.reason]}${said} Generation continues.${caveat}\n`;
+}
+// Why the code-structure branch is not in this run. One indented block, the same
+// shape as every other missing-branch reason, because that is now what this is:
+// its peer carries on, `request.json` is written, and the vibecoder comes away
+// with the guardrails that branch can still give rather than with nothing.
+//
+// The two causes keep their separate next steps. An un-run `pip install` is not
+// somebody's bug and must not be worded as one; a module of theirs that raises
+// on import is theirs to fix and pointing at an install would waste their time.
+function bootStop(boot, runner) {
     const next = boot.cause === 'defect_in_code'
-        ? 'Fix that, then run `unitbob suite-prepare` again.'
+        ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
         : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
             'it never writes to your project. Something outside that file is still missing here. Run the ' +
             'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
             'then run `unitbob suite-prepare` again.';
-    return (`${headline}\n\n` +
-        `  ${boot.message}\n\n` +
-        `${boot.detail}\n\n` +
-        'No suite was written and nothing was uploaded — every test would have died on that line ' +
-        // The caveat belongs here most of all, and this was the one branch it did
-        // not reach — found on the fifth implementation review, 2026-08-03. On
-        // pytest and vitest the check collects the project's whole test tree, so
-        // the line above may come from a test of the project's own that the Unitbob
-        // suite would never have imported. Printing "found a defect" and keeping
-        // that back sends someone to fix a file this product was never going to
-        // touch, which is the same over-claim the spec accepted the wide check only
-        // on condition of disclosing.
-        `before reaching its first assertion. ${next}${caveat}\n`);
+    // `boot.message` is the runner's own words, indented but never paraphrased:
+    // this is the line the vibecoder can paste into a search.
+    return `  ${boot.message}\n\n${boot.detail}\n\n  ${next}${caveatFor(runner, '  ')}\n`;
+}
+// What this answer is worth, in two halves that always travel together: how much
+// this stack's check can see, and the fact that it speaks for one branch only.
+// Splitting them is how the stack caveat came to be missing from the outcome
+// that costs a branch — found on the fifth implementation review, 2026-08-03 —
+// so there is one builder and every caller goes through it. `indent` sets how
+// the lines sit, and is the only thing a caller may vary.
+//
+// Empties are dropped rather than joined blindly, so a runner with no caveat of
+// its own does not leave a blank line behind.
+function caveatFor(runner, indent = '') {
+    return [runner ? SIGNAL_STRENGTH[runner] : '', runner ? STRUCTURAL_ONLY : '']
+        .filter(Boolean)
+        .map((line) => `\n${indent}${line}`)
+        .join('');
 }
 // Spec 32-6 says the boot rule is one rule for both branches; this check asks
 // one of them. It is made against the *structural* runner, which is what
@@ -474,12 +480,7 @@ const STRUCTURAL_ONLY = 'This says nothing about the product-behaviour branch: i
     'which has nothing of ours to load until its suite exists, so it was not asked.';
 const NOT_CHECKED_REASON = {
     no_runner: 'Did not check whether the suite can start: no runner available to load it with.',
-    // Distinct from `no_runner` on purpose. The runner is installed and working;
-    // it is only too old to be asked this particular question, and "no runner
-    // available" would send someone to fix a thing that is not broken.
-    runner_too_old: 'Did not check whether the suite can start: the installed runner is too old to be asked. ' +
-        'Nothing is wrong with it — this check simply has no way to pose the question to that version.',
-    // Distinct for the same reason, one step further along: the runner is there
+    // Distinct from `no_runner` on purpose: the runner is there
     // and current, it was reached, and it declined to answer — pytest exiting on
     // a usage or internal error of its own. That says nothing about the project,
     // and "no runner available" would again send someone after the wrong thing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.7.1 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.3 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded

package/dist/files/fanOut.js

@@ -1,148 +0,0 @@
-import { readPacketIndex } from "./packets.js";
-// Spec 37-3, criterion 1. How wide a branch's fan-out should be.
-//
-// The rule this replaces said there was no ceiling at all: "an agent re-reads
-// its context every turn, so splitting the work never costs more than keeping it
-// together." Half right, and the wrong half was load-bearing. An agent's cost is
-// the sum of its context over its turns, so splitting pulls in two directions:
-//
-//   - the opening context is bought once per worker and re-read every turn, so
-//     it multiplies with the width. 26,065 tokens on the bench of 2026-08-24,
-//     the same to within ±370 across fifteen workers.
-//   - each worker's conversation is shorter, and a conversation's cost grows
-//     with the square of its length, so this falls with the width.
-//
-// There is therefore a minimum, and it is neither end. Measured on that bench,
-// against what the fifteen workers actually cost:
-//
-//   workers     1      2      3      5      8     15     20
-//   input   51.2M  34.6M  29.9M  27.7M  28.8M  35.6M  41.3M
-//
-// Fifteen was 28% over the cheapest width. One worker — which is what "the work
-// fits in one context" would have said, and what the first draft of this rule
-// enforced — is 85% over it, and would have run a 216-turn worker into a
-// 150-turn fuse. The floor is as expensive a mistake as the ceiling.
-//
-// See ai/specs/37-3-fan-out-by-workload/after-2026-08-24.md in the brain repo.
-// What the optimum is not a function of. Productive turns per 1,000 tokens of
-// source were 7.8 on the behavioral branch and 1.4 on the structural one of the
-// same run — 5.6× apart — and per assigned id, 8× apart. Bytes measure how much
-// there is to read, which turns out not to be what a worker spends its turns on.
-// They stay here for the printout and for the record in `fan_out`; they do not
-// set the width.
-const BYTES_PER_TOKEN = 4;
-const WRITTEN_PER_READ = 3;
-// What it is a function of. A planned case is one intent the worker has to turn
-// into a written example or Scenario, and its cost in turns is a property of the
-// branch, not of the project: a Gherkin Scenario needs the World, a session, a
-// fixture and an assertion; a structural example calls a method.
-//
-// Measured 2026-08-24: 35 behavioral cases over 126 productive turns, 91
-// structural cases over 65.
-const TURNS_PER_CASE = { behavioral: 3.6, structural: 0.7 };
-// The optimum width is the branch's productive turns over this. It comes out of
-// setting the derivative of the cost above to zero, which gives
-// `sqrt(2·warmup·preamble/added + warmup²)` — 31.3 on the behavioral branch of
-// that run and 41.7 on the structural one, near enough to each other that one
-// number carries both and the flat bottom of the curve absorbs the difference.
-const TURNS_PER_WORKER = 36;
-// What a worker spends before it writes anything — reading its packets, its plan
-// item and its seeded facts. Measured 2026-08-24: 176 warm-up turns over eight
-// behavioral workers, 202 over seven structural ones. It is per worker and does
-// not divide, which is half of why width costs; it is added back here so that
-// the turns this prints are the whole conversation, the thing that meets the
-// 150-turn fuse.
-const WARMUP_TURNS = { behavioral: 22, structural: 28 };
-// Every case ends up at the same handful of widths, so the rule has to be a band
-// rather than a number: anywhere from three to eight workers cost within 10% of
-// the cheapest on the measured run. What the band excludes is what actually
-// costs — fifteen at one end, one at the other.
-const NARROWEST = 0.5;
-const WIDEST = 1.5;
-// How wide a branch should be, from the cases its plan intends to write.
-// Returns nothing for a branch this connector has no measured cost for: a rule
-// with no measurement behind it must not refuse anybody's plan.
-export function branchWidth(branch, plannedCases) {
-    const perCase = TURNS_PER_CASE[branch];
-    if (perCase === undefined || plannedCases <= 0)
-        return undefined;
-    const turns = plannedCases * perCase;
-    const workers = Math.max(1, Math.round(turns / TURNS_PER_WORKER));
-    return {
-        branch,
-        planned_cases: plannedCases,
-        turns_each: Math.round(turns / workers) + (WARMUP_TURNS[branch] ?? 0),
-        workers,
-        fewest: Math.max(1, Math.round(workers * NARROWEST)),
-        most: Math.max(1, Math.ceil(workers * WIDEST)),
-    };
-}
-// What each branch's source weighs. Kept because it is the honest answer to "how
-// much is there", printed before the plan exists and recorded in `fan_out` — but
-// it is not what decides the width. See TURNS_PER_CASE above.
-//
-// `taken` narrows the count to the ids a plan actually took, which matters since
-// criterion 2 let the structural branch be narrowed too: the packets are built
-// from the whole assignment, before anybody chose a scope.
-export function branchWorkloads(projectRoot, taken) {
-    const index = readPacketIndex(projectRoot);
-    if (!index || index.targets.length === 0)
-        return [];
-    const measured = new Map();
-    const unmeasured = new Map();
-    for (const target of index.targets) {
-        const ids = taken?.get(target.branch);
-        if (taken && !ids?.has(target.id))
-            continue;
-        const size = sizeOf(target);
-        // A file too large to copy still has a path and a size, and it is the
-        // heaviest reading on the branch — counting it as nothing would let the
-        // biggest sources look like the smallest.
-        const file = target.packet ?? target.source_file;
-        if (file !== undefined && size !== undefined) {
-            const files = measured.get(target.branch) ?? new Map();
-            files.set(file, size);
-            measured.set(target.branch, files);
-        }
-        else {
-            unmeasured.set(target.branch, (unmeasured.get(target.branch) ?? 0) + 1);
-        }
-    }
-    const branches = new Set([...measured.keys(), ...unmeasured.keys()]);
-    return [...branches].sort().flatMap((branch) => {
-        const files = measured.get(branch);
-        if (!files || files.size === 0)
-            return [];
-        const bytes = [...files.values()].reduce((sum, size) => sum + size, 0);
-        const missing = unmeasured.get(branch) ?? 0;
-        const withMissing = bytes + Math.round((bytes / files.size) * missing);
-        const read_tokens = Math.round(withMissing / BYTES_PER_TOKEN);
-        return [{
-                branch, files: files.size, bytes, unmeasured: missing,
-                read_tokens, work_tokens: read_tokens * (1 + WRITTEN_PER_READ),
-            }];
-    });
-}
-// The index is a file on the vibecoder's disk, so a size that is not a real byte
-// count is treated as a size we do not have rather than as zero. Zero would
-// quietly shrink the branch's average.
-function sizeOf(target) {
-    const { bytes } = target;
-    return typeof bytes === 'number' && Number.isFinite(bytes) && bytes >= 0 ? bytes : undefined;
-}
-export function widthLine(width) {
-    return (`  ${width.branch} — ${width.planned_cases} planned ` +
-        `${width.planned_cases === 1 ? 'case' : 'cases'}: ${width.workers} ` +
-        `${width.workers === 1 ? 'worker' : 'workers'} of about ${width.turns_each} turns each ` +
-        `(${width.fewest}–${width.most} accepted).\n`);
-}
-export function workloadLine(load) {
-    const missing = load.unmeasured === 0
-        ? ''
-        : ` plus ${load.unmeasured} ${load.unmeasured === 1 ? 'entrypoint' : 'entrypoints'} nothing resolved, ` +
-            'priced at what the others average';
-    return (`  ${load.branch} — ${load.files} ${load.files === 1 ? 'file' : 'files'}, ` +
-        `${load.bytes.toLocaleString('en-US')} bytes${missing}: ` +
-        `${load.read_tokens.toLocaleString('en-US')} tokens to read and about ` +
-        `${(load.work_tokens - load.read_tokens).toLocaleString('en-US')} to write.\n`);
-}