unitbob 0.6.3 → 0.7.0

package/dist/cli.js

@@ -27,7 +27,7 @@ import { validateBuild } from "./verbs/validateBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
-import { validateWorkerPlan } from "./verbs/validateWorkerPlan.js";
+import { acceptWorkerPlan } from "./verbs/acceptWorkerPlan.js";
 import { validateWorkerCheckpoints } from "./verbs/validateWorkerCheckpoints.js";
 import { installCodexAgents } from "./verbs/codexInstall.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
@@ -53,7 +53,8 @@ Verbs:
   suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
   validate-build       Internal: check the host's suite answer against the request, locally, before
                        uploading. Reports every problem at once; put-suite-build runs it too.
-  validate-worker-plan Internal: validate the exact request-bound worker plan before fan-out.
+  accept-worker-plan   Internal: check the exact request-bound worker plan and seed a checkpoint for
+                       every slice it names, before fan-out.
   validate-worker-checkpoints
                        Internal: validate every worker checkpoint before assembly or repair.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
@@ -120,8 +121,8 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'validate-build':
                 await validateBuild(await linked(), args);
                 return 0;
-            case 'validate-worker-plan':
-                await validateWorkerPlan(await linked(), args);
+            case 'accept-worker-plan':
+                await acceptWorkerPlan(await linked(), args);
                 return 0;
             case 'validate-worker-checkpoints':
                 await validateWorkerCheckpoints(await linked(), args);

package/dist/files/guardrails.js

@@ -67,7 +67,7 @@ abort 'unitbob_helper: refusing to run against a non-test environment' unless Ra
 // 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 43, §6.4). The directory is wiped
+// Every file, not just the main one (spec one-place-per-rule, §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.

package/dist/files/packets.js

@@ -0,0 +1,319 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { graphNodes, methodNameOf } from "../surfaces/graph.js";
+import { assertUnitbobPath } from "./artifactPath.js";
+import { surfacesPath } from "./mapBuild.js";
+// Spec 37-1. A worker used to receive names — `User#get_token`, `POST /api/tokens` —
+// and spend its first two thirds finding the code behind them. On microblog,
+// 2026-08-23, that was 474 of 674 worker turns and 63% of their input, once per
+// worker, for an application whose entire source is 92 KB.
+//
+// Resolving a name to a file is a dictionary lookup against two artifacts that
+// are already on this machine, so it costs no tokens and asks no model. What it
+// finds is copied whole: the packet carries exactly what the worker would have
+// opened anyway, which is why it cannot inflate a run.
+//
+// Nothing here goes up the wire. Spec 22 keeps the source on the vibecoder's
+// machine, and a packet is a local file the worker opens by path.
+export const PACKETS_DIR = '.unitbob/suite-build/packets';
+// The fuse, not a setting. It exists for the five-thousand-line controller
+// whose file is not "what a worker would have read anyway" — there the packet
+// carries the path and says so, and the worker opens the part it needs. There
+// is nowhere for this number to live except this source file: the size of a
+// packet is not a fact about the project, it is a fact about what fits.
+export const MAX_PACKET_BYTES = 200_000;
+export function packetsDir(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'packets');
+}
+export function packetIndexPath(projectRoot) {
+    return join(packetsDir(projectRoot), 'index.json');
+}
+export function readPacketIndex(projectRoot) {
+    const path = packetIndexPath(projectRoot);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(parsed?.targets))
+            return null;
+        // Entries, not just the array: a hand-edited index must not throw out of a
+        // verb whose whole policy is that a bad index costs the packets and nothing
+        // else.
+        return { targets: parsed.targets.filter((target) => !!asRecord(target) && asString(target?.id) !== undefined) };
+    }
+    catch {
+        // A packet index we cannot read is the same as none: the worker searches,
+        // as it did before this spec. It is never a reason to fail a build.
+        return null;
+    }
+}
+// Build every packet for this request. Called right after `request.json` is
+// written, and before any plan exists: the entrypoints are known from the
+// 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 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.
+    const dir = packetsDir(projectRoot);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const written = new Map();
+    const refused = new Map();
+    for (const target of targets) {
+        const sourceFile = lookup(target.entrypoint);
+        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);
+            if (typeof copied === 'number')
+                written.set(sourceFile, copied);
+            else
+                refused.set(sourceFile, copied);
+        }
+        const bytes = written.get(sourceFile);
+        if (bytes === undefined) {
+            const refusal = refused.get(sourceFile);
+            target.note = refusal.note;
+            count(notes, refusal.kind);
+            continue;
+        }
+        target.packet = `${PACKETS_DIR}/${sourceFile}`;
+        target.bytes = bytes;
+    }
+    writeFileSync(packetIndexPath(projectRoot), `${JSON.stringify({ targets }, null, 2)}\n`);
+    return {
+        targets: targets.length,
+        located: targets.filter((target) => target.source_file).length,
+        resolved: targets.filter((target) => target.packet).length,
+        files: written.size,
+        bytes: [...written.values()].reduce((sum, bytes) => sum + bytes, 0),
+        notes: [...notes].map(([note, count]) => `${count} × ${note}`),
+    };
+}
+// 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
+// of packet — a worker on either branch opens the same thing the same way.
+function targetsOf(request) {
+    const targets = [];
+    for (const branch of request.branches) {
+        const assignment = branch.assignment;
+        for (const block of asArray(assignment?.blocks)) {
+            for (const iface of asArray(asRecord(block)?.interfaces)) {
+                const record = asRecord(iface);
+                const id = asString(record?.interface_id);
+                if (!id)
+                    continue;
+                for (const entrypoint of asArray(record?.entrypoints)) {
+                    const name = asString(entrypoint);
+                    if (name)
+                        targets.push({ branch: branch.suite_kind, id, entrypoint: name });
+                }
+            }
+        }
+        for (const capability of asArray(assignment?.capabilities)) {
+            const record = asRecord(capability);
+            const id = asString(record?.capability_id);
+            if (!id)
+                continue;
+            for (const surface of asArray(record?.surfaces)) {
+                const name = asString(surface);
+                if (name)
+                    targets.push({ branch: branch.suite_kind, id, entrypoint: name });
+            }
+        }
+    }
+    return targets;
+}
+// One name in, at most one file out. Two local artifacts answer, both of them
+// built from the graph rather than from anybody's spelling rule:
+//
+//   `surfaces.json` — the addresses the router declared, each already carrying
+//   the file that serves it. It answers a behavioral surface (`POST /api/tokens`)
+//   by its id and a structural entrypoint (`MainRoutes.export_posts`) by the
+//   handler label, which is the router's own wording, not a name we built.
+//
+//   `graph.json` — every symbol graphify saw, matched by method name. A name
+//   alone is not enough: `User#get_token` and `ApiTokens.get_token` are two
+//   different entrypoints and graphify saw only one `get_token()`. So the owner
+//   the entrypoint named has to agree with the file before it is believed.
+//
+// Ambiguity ends in silence, never in a first match, and neither does a name
+// that resolves to a file its owner has nothing to do with. A packet holding
+// the wrong file is worse than no packet: the worker reads it, believes it, and
+// writes a test about code that does not serve this entrypoint. On microblog,
+// 2026-08-23, matching on the bare name alone sent both `ApiTokens` entrypoints
+// to `app/models.py`, whose `get_token` belongs to `User`.
+function buildLookup(projectRoot) {
+    const byAddress = new Map();
+    for (const surface of readSurfaces(projectRoot)) {
+        const record = asRecord(surface);
+        const file = normalisePath(asString(record?.source_file));
+        if (!file)
+            continue;
+        for (const key of [asString(record?.id), asString(record?.handler_label)]) {
+            if (key)
+                remember(byAddress, key, file);
+        }
+    }
+    const byMethod = new Map();
+    const byLabel = new Map();
+    for (const node of graphNodes(projectRoot)) {
+        const file = normalisePath(typeof node.source_file === 'string' ? node.source_file : undefined);
+        if (typeof node.label !== 'string' || !file)
+            continue;
+        remember(byMethod, methodNameOf(node.label), file);
+        remember(byLabel, node.label, file);
+    }
+    // The owner and the file agree if graphify put something of the owner's name
+    // in that file, or if the owner is the file — `ApiAuth` and `app/api/auth.py`
+    // are the same thing said twice, once in the map's words and once in the
+    // filesystem's. This confirms a file we already found; it never builds a path
+    // out of a name, which would be us maintaining somebody else's naming rule.
+    const agrees = (owner, file) => byLabel.get(owner)?.has(file) === true ||
+        byMethod.get(owner)?.has(file) === true ||
+        squash(file).includes(squash(owner));
+    return (entrypoint) => {
+        const declared = only(byAddress.get(entrypoint));
+        if (declared)
+            return declared;
+        // An address is the router's word, not a symbol, and must not fall through
+        // to symbol matching: `GET /users` would resolve by the name `users` to
+        // whatever single thing answers to it — a helper, a model, anything.
+        if (/\s/.test(entrypoint))
+            return undefined;
+        const named = byMethod.get(methodNameOf(entrypoint));
+        if (!named)
+            return undefined;
+        const owner = ownerNameOf(entrypoint);
+        if (!owner)
+            return only(named);
+        return only(new Set([...named].filter((file) => agrees(owner, file))));
+    };
+}
+// The name the entrypoint hangs its method on: `User` in `User#get_token`,
+// `Invoice` in `Billing::Invoice#total`. Split exactly as `methodNameOf` splits,
+// so the two never disagree about where a name ends.
+function ownerNameOf(entrypoint) {
+    const parts = entrypoint.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
+    return parts.length > 1 ? parts[parts.length - 2] : undefined;
+}
+function squash(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+// graphify writes a path the way its host does. `app\models.rb` and
+// `./app/models.rb` are the same file as `app/models.rb`, and treating them as
+// three keys makes one file look like three and one method look ambiguous.
+function normalisePath(value) {
+    const normalised = value?.replace(/\\/g, '/').replace(/^\.\//, '');
+    return normalised || undefined;
+}
+function remember(into, key, file) {
+    const seen = into.get(key) ?? new Set();
+    seen.add(file);
+    into.set(key, seen);
+}
+function count(notes, note) {
+    notes.set(note, (notes.get(note) ?? 0) + 1);
+}
+function only(files) {
+    return files && files.size === 1 ? [...files][0] : undefined;
+}
+function readSurfaces(projectRoot) {
+    const path = surfacesPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return asArray(parsed?.surfaces);
+    }
+    catch {
+        return [];
+    }
+}
+// Copy one source file into the packets folder, keeping the path it has in the
+// checkout so the worker recognises it. Returns the byte count, or why there is
+// no copy to make. It never throws: one unreadable file out of a hundred is one
+// worker searching, not a run without packets.
+function copyPacket(projectRoot, sourceFile) {
+    const relative = `${PACKETS_DIR}/${sourceFile}`;
+    try {
+        assertUnitbobPath(relative, PACKETS_DIR);
+    }
+    catch {
+        return {
+            note: `graph.json names a path we will not write (${sourceFile}) — find the file yourself`,
+            kind: 'named a path we will not write',
+        };
+    }
+    try {
+        // The path came from graphify's output, not from us. A symlink or an
+        // absolute path there must not turn "copy a project file" into "copy
+        // anything on this machine", so the file is required to really live inside
+        // the checkout. `realpathSync` resolves every component, so a symlinked
+        // directory in the middle of the path is caught the same way.
+        const root = realpathSync(projectRoot);
+        let onDisk;
+        try {
+            onDisk = realpathSync(resolve(projectRoot, sourceFile));
+        }
+        catch {
+            return {
+                note: `${sourceFile} is named in graph.json but is not on disk — find the file yourself`,
+                kind: 'named a file that is not on disk',
+            };
+        }
+        if (onDisk !== root && !onDisk.startsWith(root + sep)) {
+            return {
+                note: `${sourceFile} resolves outside the project — find the file yourself`,
+                kind: 'resolved outside the project',
+            };
+        }
+        const stat = statSync(onDisk);
+        // A directory passes the size check comfortably and then throws EISDIR on
+        // read. Said here rather than caught below, so the words name the cause.
+        if (!stat.isFile()) {
+            return {
+                note: `${sourceFile} is not a file — find the code yourself`,
+                kind: 'named something that is not a file',
+            };
+        }
+        if (stat.size > MAX_PACKET_BYTES) {
+            return {
+                note: `${sourceFile} is ${stat.size.toLocaleString('en-US')} bytes, over the ${MAX_PACKET_BYTES.toLocaleString('en-US')}-byte packet fuse — open it at that path instead`,
+                kind: 'over the packet fuse — the path travels instead',
+            };
+        }
+        // The bytes we actually wrote, not the size we saw a moment ago.
+        const body = readFileSync(onDisk);
+        const destination = join(projectRoot, relative);
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, body);
+        return body.length;
+    }
+    catch (err) {
+        return {
+            note: `${sourceFile} could not be copied (${err.message}) — find the file yourself`,
+            kind: 'could not be copied',
+        };
+    }
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}

package/dist/files/suiteBuild.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
@@ -18,6 +18,38 @@ export function reviewRequestPath(projectRoot) {
 export function candidateRunPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'candidate-run.json');
 }
+// Spec 37-2, criterion 3. What a new build leaves behind, in the order a reader
+// meets it: the plan, the checkpoints written against that plan, and the answer
+// assembled from them. All three are bound to the `request.json` this run is
+// about to overwrite, so from the next line on they are a previous run's papers
+// wearing this run's filenames — which is exactly the confusion the coordinator
+// used to spend a turn untangling before fan-out.
+const PREVIOUS_RUN_ARTIFACTS = ['worker-plan.json', 'checkpoints', 'suite_output.json'];
+const PREVIOUS_DIR = 'previous';
+// Moved, never removed. A run costs hours and real money, and one interrupt plus
+// one restart must not be able to spend that twice — `previous/` is one line
+// more than `rmSync` and it is the line that makes a restart survivable.
+//
+// Replaced one artifact at a time rather than by clearing `previous/` first. The
+// tidier version — wipe, then move whatever exists — loses a complete previous
+// run to a partial one: a build interrupted between writing the plan and seeding
+// its checkpoints displaces only `worker-plan.json`, and clearing would take the
+// finished checkpoints and answer of the run before it with no way back. A
+// `previous/` holding pieces of two runs is worth strictly more than an empty
+// one, and every piece in it is named by the file it kept.
+export function movePreviousRunAside(projectRoot) {
+    const buildDir = join(projectRoot, '.unitbob', 'suite-build');
+    const found = PREVIOUS_RUN_ARTIFACTS.filter((name) => existsSync(join(buildDir, name)));
+    if (found.length === 0)
+        return [];
+    const previous = join(buildDir, PREVIOUS_DIR);
+    mkdirSync(previous, { recursive: true });
+    for (const name of found) {
+        rmSync(join(previous, name), { recursive: true, force: true });
+        renameSync(join(buildDir, name), join(previous, name));
+    }
+    return found;
+}
 export function writeBehavioralReviewRequest(projectRoot, output, candidateRun, knownDefectContext = { status: 'not_supplied' }, fixedCandidateRun) {
     const metadata = output.test_metadata;
     const candidateDigest = suiteCandidateDigest(output);
@@ -83,7 +115,7 @@ export function branchRunner(output) {
     return runner;
 }
 // What the reviewer actually read: the suite files, and the manifest that runs
-// them. Nothing else (spec 43, §4).
+// them. Nothing else (spec one-place-per-rule, §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

package/dist/files/suiteBuildUpload.js

@@ -2,7 +2,7 @@ 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 43, §3).
+// verdict is about the exact bytes the publish will carry (spec one-place-per-rule, §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

package/dist/files/workerPlan.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 export function workerPlanPath(projectRoot) {
@@ -34,6 +34,75 @@ export function readWorkerPlan(projectRoot) {
     }
     return parsed;
 }
+export const SUPERSEDED_DIR = 'superseded';
+export function seedWorkerCheckpoints(projectRoot) {
+    const plan = readWorkerPlan(projectRoot);
+    const request_digest = requestDigest(projectRoot);
+    const plan_digest = workerPlanDigest(projectRoot);
+    const written = [];
+    const kept = [];
+    const superseded = [];
+    for (const item of plan.workers) {
+        const path = checkpointPath(projectRoot, item);
+        const label = `${item.branch}:${item.worker_id}`;
+        // Left alone when it already belongs to this plan: the coordinator's facts
+        // and a worker's finished slice both live in this file, and a run costs
+        // hours.
+        if (belongsToPlan(path, plan_digest)) {
+            kept.push(label);
+            continue;
+        }
+        // Everything else needs a fresh seed — but the file being replaced is not
+        // necessarily worthless. `plan_digest` is a digest of the whole
+        // `worker-plan.json`, so editing one slice invalidates every checkpoint at
+        // once, including finished ones; and replanning after the first slice comes
+        // back is a documented, ordinary move. Overwriting in place would have made
+        // this verb the one thing in the build that destroys hours of work, on the
+        // most ordinary path there is. Moved for the same reason `suite-prepare`
+        // moves the previous run rather than deleting it.
+        if (existsSync(path)) {
+            const aside = join(dirname(path), SUPERSEDED_DIR, `${item.branch}-${item.worker_id}.json`);
+            mkdirSync(dirname(aside), { recursive: true });
+            rmSync(aside, { force: true });
+            renameSync(path, aside);
+            superseded.push(label);
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(seedFor(item, request_digest, plan_digest), null, 2)}\n`);
+        written.push(label);
+    }
+    return { written, kept, superseded };
+}
+function belongsToPlan(path, planDigest) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed?.plan_digest === planDigest;
+    }
+    catch {
+        return false;
+    }
+}
+function seedFor(item, request_digest, plan_digest) {
+    return {
+        request_digest,
+        plan_digest,
+        branch: item.branch,
+        worker_id: item.worker_id,
+        // Every promise starts unresolved: the slice has not been worked yet, and
+        // the gate wants each one accounted for exactly once.
+        unresolved_promises: [...item.promises],
+        completed_promises: [],
+        written_paths: [],
+        decisions: [],
+        known_problems: [],
+        // Behavioral only, and absent rather than empty elsewhere — it joins Gherkin
+        // Scenarios to addresses, and the structural branch has no Scenarios.
+        ...(item.branch === 'behavioral' ? { surface_coverage: [] } : {}),
+        facts: [],
+    };
+}
 const RUBY_HARNESS = {
     behavioral: '.unitbob/behavioral/step_definitions/00_unitbob_world.rb',
     structural: '.unitbob/structural/unitbob_helper.rb',
@@ -70,6 +139,14 @@ export function validateWorkerPlanFiles(projectRoot) {
         const label = workerLabel(item, index);
         if (!isNonEmptyString(item?.branch) || !expectedByBranch.has(item.branch))
             errors.push(`${label}: branch is not in the request`);
+        // Both halves of the checkpoint filename, held to the same rule. `worker_id`
+        // has always been checked; `branch` never was, because it only ever came
+        // from `request.json` and was only ever read. Since spec 37-2 the pair is
+        // also a path this connector *writes*, and `request.json` is a file on the
+        // vibecoder's disk — so a `suite_kind` of `../../..` would have put a
+        // seeded checkpoint outside the project.
+        else if (!/^[a-zA-Z0-9_-]+$/.test(item.branch))
+            errors.push(`${label}: branch must be a filename-safe name`);
         if (!isNonEmptyString(item?.worker_id) || !/^[a-zA-Z0-9_-]+$/.test(item.worker_id))
             errors.push(`${label}: worker_id must be a stable filename-safe id`);
         else if (seenWorkers.has(item.worker_id))
@@ -109,9 +186,6 @@ export function validateWorkerPlanFiles(projectRoot) {
         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`);
-        }
         for (const ownedPath of Array.isArray(item?.owned_paths) ? item.owned_paths : []) {
             if (!isNonEmptyString(ownedPath)) {
                 errors.push(`${label}: owned path must be a non-empty string`);

package/dist/runner/failureDigest.js

@@ -12,10 +12,17 @@ const MARKER = /ubc_[0-9a-f]{12}(?![0-9a-f])/;
 // the first test produces no set at all, and comparing against nothing would
 // stop a branch over a harness problem the loop never even reached.
 export function failureSet(runner, report) {
+    const found = reportedFailures(runner, report);
+    return found && canonical(found.map(({ marker, file, message }) => ({ marker, file, message })));
+}
+// The same failures, with everything a reader needs and the comparison does not.
+// Reported in the order the runner reported them: this list is read by a person
+// deciding what to repair, and a run's own order is the one that matches the
+// console output next to it.
+export function reportedFailures(runner, report) {
     if (!report.trim())
         return null;
-    const found = extract(runner, report);
-    return found && canonical(found);
+    return extract(runner, report);
 }
 // One hash for one set. Same set, same hash, on any machine and in any order.
 export function digestOf(failures) {
@@ -99,7 +106,9 @@ function fromRspec(report) {
             return [];
         const name = `${text(example.description)} ${text(example.full_description)}`;
         const exception = example.exception;
-        return [failure(name, text(example.file_path), text(exception?.message))];
+        return [failure(name, text(example.file_path), text(exception?.message), {
+                name: text(example.full_description) || text(example.description),
+            })];
     });
 }
 function fromVitest(report) {
@@ -113,7 +122,9 @@ function fromVitest(report) {
                 return [];
             const messages = Array.isArray(assertion.failureMessages) ? assertion.failureMessages : [];
             const name = `${text(assertion.title)} ${text(assertion.fullName)}`;
-            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'))];
+            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'), {
+                    name: text(assertion.fullName) || text(assertion.title),
+                })];
         });
     });
 }
@@ -130,16 +141,55 @@ function fromVitest(report) {
 function fromJunitXml(report) {
     if (!/<testsuites?\b/.test(report))
         return null;
-    const cases = report.match(/<testcase\b[^>]*(?:\/>|>[\s\S]*?<\/testcase>)/g) ?? [];
+    // Self-closing first, and as its own alternative rather than a branch inside
+    // one `[^>]*`. Written the other way the engine backtracks out of `\/>` into
+    // `>[\s\S]*?<\/testcase>` and swallows the next element whole, so a passing
+    // self-closed case immediately before a failing one hands back the passing
+    // one's name and file. Harmless while this was only hashed; wrong the moment
+    // spec 37-2 started printing it to somebody deciding what to repair.
+    const cases = report.match(/<testcase\b[^>]*\/>|<testcase\b[^>]*>[\s\S]*?<\/testcase>/g) ?? [];
     return cases.flatMap((testcase) => {
-        const problem = testcase.match(/<(?:failure|error)\b[^>]*(?:\/>|>[\s\S]*?<\/(?:failure|error)>)/);
+        const problem = testcase.match(/<(failure|error)\b[^>]*\/>|<(failure|error)\b[^>]*>([\s\S]*?)<\/(?:failure|error)>/);
         if (!problem)
             return [];
         const name = attribute(testcase, 'name');
         const file = attribute(testcase, 'file') || attribute(testcase, 'classname');
-        return [failure(name, file, attribute(problem[0], 'message'))];
+        const message = attribute(problem[0], 'message');
+        // pytest puts the one-line summary in `message=` and the assertion with its
+        // traceback in the element's body. The body is what a person needs; the
+        // attribute is what the digest compares, and changing its bytes would make
+        // every branch look like it had moved once.
+        const body = unescapeXml(problem[3] ?? '').trim();
+        return [failure(name, file, message, {
+                name,
+                detail: [unescapeXml(message), body].filter(Boolean).join('\n'),
+            })];
     });
 }
+// The five entities XML defines plus numeric references — pytest escapes its
+// newlines as `&#10;`, and a traceback rendered as one line of `&#10;` is not a
+// traceback. This is pytest's own writer on the other end, not arbitrary markup.
+// `&amp;` last, so `&amp;lt;` comes back as `&lt;` rather than as `<`.
+function unescapeXml(value) {
+    return value
+        .replace(/&#(\d+);/g, (whole, code) => codePoint(Number(code), whole))
+        .replace(/&#x([0-9a-f]+);/gi, (whole, code) => codePoint(parseInt(code, 16), whole))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+// A reference outside Unicode is left as it was written. Nothing here is worth
+// throwing over: this runs while somebody is reading why their suite is red.
+function codePoint(value, whole) {
+    try {
+        return String.fromCodePoint(value);
+    }
+    catch {
+        return whole;
+    }
+}
 // Cucumber Messages (NDJSON), both the Ruby and the JS emitter. One scenario is
 // spread over several envelopes: the pickle holds its name, tags and file, the
 // testCase maps its steps, and testStepFinished carries each step's result.
@@ -164,7 +214,13 @@ function fromCucumberMessages(report) {
             continue;
         const startedId = text(finished.testCaseStartedId);
         const list = results.get(startedId) ?? [];
-        list.push(finished.testStepResult ?? {});
+        list.push({
+            // The step's own id travels with its result, so the text of the step that
+            // failed can be recovered from the pickle it came from (spec 37-2,
+            // criterion 5). Nothing in the digest reads it.
+            testStepId: finished.testStepId,
+            ...(finished.testStepResult ?? {}),
+        });
         results.set(startedId, list);
     }
     return envelopes.flatMap((envelope) => {
@@ -180,12 +236,27 @@ function fromCucumberMessages(report) {
         const tags = Array.isArray(pickle.tags) ? pickle.tags : [];
         const tagText = rows(tags).map((tag) => text(tag.name)).join(' ');
         const message = failed.map((step) => text(step.message)).find((line) => line.trim()) ?? '';
-        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message)];
+        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message, {
+                name: text(pickle.name),
+                step: cucumberStepText(failed[0], testCase, pickle),
+            })];
     });
 }
-// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). It names
-// no file — the whole behavioral bundle is one run — so the scenario's marker
-// and message carry the identity alone.
+// Which step of that Scenario failed, in the words of the feature file. Three
+// hops, because Cucumber Messages keeps the result, the mapping and the text in
+// three different envelopes: result → testStep → pickleStep.
+function cucumberStepText(failed, testCase, pickle) {
+    const testSteps = Array.isArray(testCase.testSteps) ? rows(testCase.testSteps) : [];
+    const testStep = testSteps.find((step) => text(step.id) === text(failed.testStepId));
+    if (!testStep)
+        return '';
+    const pickleSteps = Array.isArray(pickle.steps) ? rows(pickle.steps) : [];
+    return text(pickleSteps.find((step) => text(step.id) === text(testStep.pickleStepId))?.text);
+}
+// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). Its
+// `file` is the `.feature` the Scenario came from, and it is empty on a report
+// written by a connector older than spec 37-2 — which is why it is read
+// defensively rather than assumed.
 function fromPytestBdd(report) {
     const data = parseObject(report);
     if (!Array.isArray(data?.scenarios))
@@ -194,17 +265,28 @@ function fromPytestBdd(report) {
         if (text(scenario.status) === 'passed')
             return [];
         const tags = Array.isArray(scenario.tags) ? scenario.tags.map((tag) => text(tag)).join(' ') : '';
-        return [failure(`${tags} ${text(scenario.name)}`, '', text(scenario.failure))];
+        // Our own plugin records one entry per step with its status, and marks the
+        // one it caught the exception in — so the step is read, never guessed.
+        const steps = Array.isArray(scenario.steps) ? rows(scenario.steps) : [];
+        const broke = steps.find((step) => text(step.status) === 'failed');
+        return [failure(`${tags} ${text(scenario.name)}`, text(scenario.file), text(scenario.failure), {
+                name: text(scenario.name),
+                step: broke ? `${text(broke.keyword)} ${text(broke.text)}`.trim() : '',
+            })];
     });
 }
-// Only the first line of a message. Later lines are backtraces and diffs, which
+// `message` is only the first line. Later lines are backtraces and diffs, which
 // carry object ids and absolute paths that differ between two runs of the same
-// unchanged failure — the very drift that would make this comparison useless.
-function failure(name, file, message) {
+// unchanged failure — the very drift that would make the comparison useless.
+// `detail` keeps all of it: nothing on that field is hashed.
+function failure(name, file, message, extra = {}) {
     return {
         marker: name.match(MARKER)?.[0] ?? '',
         file,
         message: message.split('\n')[0]?.trim() ?? '',
+        name: (extra.name ?? name).trim(),
+        step: extra.step ?? '',
+        detail: (extra.detail ?? message).trim(),
     };
 }
 function indexBy(envelopes, key) {

package/dist/runner/provision.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 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";
+import { commandFileOnHost, defaultToolDeps, hasGemfileWith, 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
@@ -448,11 +448,75 @@ function copyLockIfPresent(projectRoot, destination) {
     if (existsSync(projectLock))
         writeFileSync(destination, readFileSync(projectLock, 'utf8'));
 }
+// The pin the sidecar asks for, and the oldest Ruby that pin will install on.
+// Written next to each other because they are one fact: every cucumber in the
+// 9.x line declares `required_ruby_version >= 2.7` (checked against rubygems for
+// 9.0.0 through 9.2.1, 2026-08-24). Move the pin and this number moves with it.
+const CUCUMBER_PIN = '~> 9.0';
+const CUCUMBER_MIN_RUBY = { major: 2, minor: 7, text: '2.7' };
+// Spec 37-2, criterion 4. One known refusal, made legible — not a parser for
+// other people's error messages.
+//
+// a2time, 2026-08-17: the behavioral branch came back "Bundler failed to
+// provision Cucumber sidecar gem", and the cause was a fact this process could
+// have read in one command — the host's Ruby is 2.6.10, older than the cucumber
+// this connector pins. It cost a round trip through the vibecoder to run
+// `bundle install` by hand and read the same sentence back.
+//
+// Asked before the install rather than after: `bundle install` on a cold
+// application takes minutes, and the answer is the same either way.
+//
+// Only when our pin is the one that applies. A project that declares cucumber
+// itself keeps its own version — `gemLineUnlessTheProjectHasIt` drops our line
+// whole — and refusing that project over a floor it never had to meet would
+// stop a build that works.
+//
+// The Gemfile is read as text, while the line that drops the pin asks bundler's
+// own resolved `dependencies`. The two can disagree, and only one direction of
+// disagreement is expensive: a project whose cucumber arrives through `gemspec`
+// or an `eval_gemfile` would be refused over a floor it never had to meet. So
+// those two words count as "the project may name it", and the check stays quiet
+// — back to bundler's own message, which is where this started and no worse.
+const PROJECT_MAY_NAME_CUCUMBER = /^\s*gem\s+["']cucumber["']|^\s*gemspec\b|^\s*eval_gemfile\b/m;
+async function rubyTooOldForCucumber(projectRoot, deps) {
+    if (hasGemfileWith(projectRoot, PROJECT_MAY_NAME_CUCUMBER))
+        return null;
+    const result = await deps
+        .runCmd('ruby', ['-v'], { cwd: projectRoot })
+        .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+    if (result.code !== 0)
+        return null;
+    // A version we cannot read stops nothing. This check exists to replace one
+    // confusing message with one clear one, and guessing here would replace a
+    // clear failure with a wrong refusal.
+    const found = `${result.stdout}\n${result.stderr}`.match(/\bruby (\d+)\.(\d+)\.(\d+)/i);
+    if (!found)
+        return null;
+    const [, major, minor] = found;
+    const older = Number(major) < CUCUMBER_MIN_RUBY.major
+        || (Number(major) === CUCUMBER_MIN_RUBY.major && Number(minor) < CUCUMBER_MIN_RUBY.minor);
+    return older ? `${major}.${minor}.${found[3]}` : null;
+}
 async function provisionRuby(projectRoot, behavioralDir, deps) {
+    const oldRuby = await rubyTooOldForCucumber(projectRoot, deps);
+    if (oldRuby) {
+        return {
+            status: 'fixable',
+            message: `Cucumber ${CUCUMBER_PIN} needs Ruby ${CUCUMBER_MIN_RUBY.text} or newer, and the Ruby answering here is ` +
+                `${oldRuby}. Bundler was not asked to install it.`,
+            checklist: [
+                `Run Unitbob where the application runs. The Ruby that answered is ${oldRuby}; if the app itself runs ` +
+                    'on a newer one inside a container, name that container under `exec` in `.unitbob.json` and this ' +
+                    'check runs there instead.',
+                `Or declare \`cucumber\` in the project's own Gemfile at a version that supports Ruby ${oldRuby} — ` +
+                    'the sidecar drops its own pin whenever the project names the gem.',
+            ],
+        };
+    }
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
-        gemLineUnlessTheProjectHasIt('cucumber', '~> 9.0') +
+        gemLineUnlessTheProjectHasIt('cucumber', CUCUMBER_PIN) +
         // The connector-owned World blocks outgoing HTTP (spec 35-1), and it can only
         // do that if webmock resolves here. A project that does not carry the gem
         // would otherwise get a World promising a block it silently never performs —

package/dist/runner/pytest.js

@@ -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 43, §6.5) — a branch is
+// Every file of the branch is named positionally (spec one-place-per-rule, §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

package/dist/runner/pytestBddPlugin.js

@@ -27,6 +27,11 @@ _UNITBOB_OUT = os.path.abspath(_UNITBOB_OUT) if _UNITBOB_OUT else None
 def pytest_bdd_before_scenario(request, feature, scenario):
     _UNITBOB_CURRENT[id(scenario)] = {
         "name": scenario.name,
+        # Which .feature file this Scenario came from. Every hook here is handed
+        # the feature and none of them recorded it, so a red run named the
+        # Scenario and left the reader to find the file (spec 37-2, criterion 5).
+        # Project-relative where pytest-bdd offers it.
+        "file": getattr(feature, "rel_filename", None) or getattr(feature, "filename", None) or "",
         "tags": sorted(scenario.tags),
         "status": "passed",
         "failure": "",

package/dist/runner/rspec.js

@@ -18,7 +18,7 @@ export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // corrupt it.
 //
 // `suitePaths` is every file of the branch in the suite blob's own
-// project-relative form (spec 43, §6.5). Named one by one rather than as a
+// project-relative form (spec one-place-per-rule, §6.5). Named one by one rather than as a
 // directory: the artifact already says exactly which files it is, while a
 // directory would also collect whatever else happens to be sitting under the
 // root.

package/dist/runner/vitest.js

@@ -37,7 +37,7 @@ const PROJECT_CONFIGS = [
 // file of the branch in `include`, and the positional filters keep the run to
 // exactly those files.
 //
-// Named files rather than a directory glob, since spec 43, §6.5 made a branch
+// Named files rather than a directory glob, since spec one-place-per-rule, §6.5 made a branch
 // several files: the artifact already says which files it is, and a glob would
 // have to guess a naming convention nothing enforces. `include` is written even
 // when the project has no config of its own — Vitest's default include only

package/dist/surfaces/graph.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { graphPath } from "../files/mapBuild.js";
+export function graphNodes(projectRoot) {
+    const path = graphPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    try {
+        const graph = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(graph.nodes))
+            return [];
+        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
+    }
+    catch {
+        return []; // an unreadable graph costs us the links, not the addresses
+    }
+}
+export function pathsMatch(candidate, file) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    const wanted = file.replace(/\\/g, '/');
+    if (normalised === wanted)
+        return 'exact';
+    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
+}
+// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
+// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
+// them are read the same way — drop the call parentheses, then take the last
+// name — so the match survives the decoration without depending on which form
+// this release of graphify happens to use. The id itself is never rebuilt from
+// any of this; it is copied.
+export function methodNameOf(label) {
+    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
+    return parts[parts.length - 1] ?? '';
+}

package/dist/surfaces/routeInventory.js

@@ -1,10 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.js";
 import { detectStructuralRunner } from "../runner/precheck.js";
-import { graphPath } from "../files/mapBuild.js";
+import { graphNodes, methodNameOf, pathsMatch } from "./graph.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
 const ROUTES_TIMEOUT_MS = 120_000;
@@ -266,20 +266,6 @@ function rowsFrom(record) {
         action,
     }));
 }
-function graphNodes(projectRoot) {
-    const path = graphPath(projectRoot);
-    if (!existsSync(path))
-        return [];
-    try {
-        const graph = JSON.parse(readFileSync(path, 'utf8'));
-        if (!Array.isArray(graph.nodes))
-            return [];
-        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
-    }
-    catch {
-        return []; // an unreadable graph costs us the links, not the addresses
-    }
-}
 function toSurface(projectRoot, row, nodes) {
     const surface = { kind: 'route', id: `${row.verb} ${row.path}` };
     if (!row.controller || !row.action)
@@ -350,23 +336,6 @@ function findNode(nodes, file, action) {
     // still ships, without a link.
     return candidates.length === 1 ? candidates[0] : undefined;
 }
-function pathsMatch(candidate, file) {
-    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
-    const wanted = file.replace(/\\/g, '/');
-    if (normalised === wanted)
-        return 'exact';
-    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
-}
-// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
-// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
-// them are read the same way — drop the call parentheses, then take the last
-// name — so the match survives the decoration without depending on which form
-// this release of graphify happens to use. The id itself is never rebuilt from
-// any of this; it is copied.
-function methodNameOf(label) {
-    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
-    return parts[parts.length - 1] ?? '';
-}
 // What `surfaces.json` must contain for every address the router declared, and
 // what it must not contain on top of them. Used before upload (`put-map-build`):
 // the inventory removed the model's chance to invent an address, and this

package/dist/verbs/putSuiteBuild.js

@@ -46,7 +46,7 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
-    // Since spec 43 that check is exactly one question, and it is about a branch
+    // Since spec one-place-per-rule that check is exactly one question, and it is about a branch
     // the answer has *no* entry for: everything else it used to ask is now asked
     // of the server, by a dry run, before this command runs at all. So its
     // problems can never land on a branch this loop visits, and they are reported

package/dist/verbs/run.js

@@ -30,7 +30,7 @@ function resolve(config, deps) {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
-        // since spec 43, §6, and picking `path` and `content` out of it here was
+        // since spec one-place-per-rule, §6, and picking `path` and `content` out of it here was
         // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
@@ -145,7 +145,7 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     }
 }
 // Every file of the branch, in the order the envelope carries them. A structural
-// branch is one file per assignment since spec 43, §6, and running only the main
+// branch is one file per assignment since spec one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
 function artifactPaths(file) {
     return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];

package/dist/verbs/runLocal.js

@@ -1,5 +1,5 @@
 import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { digestOf, failureSet, readRunState, rememberFailures } from "../runner/failureDigest.js";
+import { digestOf, failureSet, readRunState, rememberFailures, reportedFailures, } from "../runner/failureDigest.js";
 import { placeProblem } from "../runner/place.js";
 import { placeAdvice } from "../runner/placeAdvice.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
@@ -143,8 +143,72 @@ async function runOneBranch(config, d, suiteKind, output) {
         return null;
     }
     d.stdout.write(report(result));
+    d.stdout.write(failureLines(runner, result));
     return { runner, result };
 }
+// How many lines of one failure's message are worth printing here. Enough for an
+// assertion diff and the frame under it; not the whole backtrace, which is in
+// the report file the line above names.
+const DETAIL_LINES = 6;
+const DETAIL_CHARS = 600;
+// Spec 37-2, criterion 5. The report is read by the side that knows its format.
+//
+// Both behavioral report shapes and all three structural ones are already parsed
+// in this connector, for the stall comparison — and the coordinator still opened
+// `pytest_bdd_report.json` with an inline `node -e` and `pytest_result.xml` with
+// an inline `python3`, because nothing printed what it found. That happened on
+// the most expensive turns of the run: the repair stretch of the microblog bench
+// cost 79 coordinator turns and 47% of its input, each turn re-reading a 300,000
+// token conversation.
+//
+// Every failure, up to a budget on the whole block — this list is what the
+// repair packets of step 12 are cut from, so a top-N would send the coordinator
+// back to the file for the rest, which is the cost this removes. But the run
+// this most exists for is the first red one, where the harness is not wired yet
+// and every case fails: unbounded, that is half a megabyte into the very context
+// this spec is trying to make cheaper. What does not fit says so, by count, and
+// the report file is named on the line above.
+const FAILURE_BLOCK_CHARS = 40_000;
+function failureLines(runner, result) {
+    const failures = reportedFailures(runner, result.report);
+    if (!failures || failures.length === 0)
+        return '';
+    const head = `\n${failures.length} ${failures.length === 1 ? 'case' : 'cases'} failed, read out of ` +
+        `${result.resultPath}. Do not open that file to find this again:\n`;
+    const printed = [];
+    let spent = 0;
+    for (const [index, failure] of failures.entries()) {
+        const line = one(failure, index);
+        if (spent + line.length > FAILURE_BLOCK_CHARS && printed.length > 0)
+            break;
+        printed.push(line);
+        spent += line.length;
+    }
+    const left = failures.length - printed.length;
+    const tail = left === 0
+        ? ''
+        : `\n  …and ${left} more failed ${left === 1 ? 'case' : 'cases'}, not printed to keep this readable. ` +
+            `They are in ${result.resultPath}; a branch failing this widely is usually one harness problem, ` +
+            'not that many repairs.\n';
+    return head + printed.join('') + tail;
+}
+function one(failure, index) {
+    const where = failure.file ? ` — ${failure.file}` : '';
+    const lines = [`\n  ${index + 1}. ${failure.name || failure.marker || '(the runner named no case)'}${where}`];
+    if (failure.marker && failure.name.includes(failure.marker) === false)
+        lines.push(`     ${failure.marker}`);
+    if (failure.step)
+        lines.push(`     step: ${failure.step}`);
+    for (const line of trimmed(failure.detail))
+        lines.push(`     ${line}`);
+    return `${lines.join('\n')}\n`;
+}
+function trimmed(detail) {
+    const lines = detail.split('\n').slice(0, DETAIL_LINES);
+    const kept = lines.join('\n').slice(0, DETAIL_CHARS).split('\n');
+    const complete = kept.join('\n') === detail;
+    return complete ? kept : [...kept, '…'];
+}
 // The command first, and always — including on a green run. It is the answer to
 // "how do I run just this one file again", which is the question the whole
 // iteration loop is made of, and printing it only on failure would hide it at
@@ -178,7 +242,7 @@ function outputTail(result) {
 }
 // The suite blob's own project-relative paths, exactly as the runners expect
 // them: the main file first, then every other file of the branch. The main file
-// stopped being the whole suite in spec 43, §6 — a branch is one file per
+// stopped being the whole suite in spec one-place-per-rule, §6 — a branch is one file per
 // assignment now — and running it alone would exercise a fraction of what the
 // answer claims to guard.
 //

package/dist/verbs/suitePrepare.js

@@ -1,7 +1,8 @@
 import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
-import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { PACKETS_DIR, 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";
 import { anyStackPrecheck, behavioralHarnessNotice, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck, } from "../runner/precheck.js";
@@ -230,16 +231,54 @@ export async function suitePrepare(config, args = [], deps) {
         throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\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
+    // behind them, resolved from this machine's own graph and copied where a
+    // worker can open them. Built here because the entrypoints are known from the
+    // request and the workers are not yet — a packet belongs to an entrypoint,
+    // not to whoever ends up guarding it.
+    //
+    // Not written into `request.json`: the coordinator reads that file whole and
+    // pays for it on every turn of the longest-lived context in the run.
+    const sourcePackets = buildPackets(config.projectRoot, request);
     // A new request is a new build, and a new build has no previous run to be
     // stuck against (spec 34-6, criterion 3). Re-running this verb is a documented
     // step of the loop, so a failure set remembered from the build before it would
     // stop a branch that has not run once yet.
     clearRunState(config.projectRoot);
+    // Spec 37-2, criterion 3. Same reasoning, applied to the papers that were left
+    // behind rather than cleared: a plan and its checkpoints outlive the
+    // `request.json` they were digested against, and every one of them is refused
+    // by its own gate from here on. Moved rather than removed — see
+    // `movePreviousRunAside`.
+    //
+    // Wrapped for the same reason `buildPackets` is: by this line the request is
+    // written and the build is real. A read-only checkout or a permission the move
+    // does not have is a note, not a build that dies after its own work landed
+    // and before it could say so.
+    let displaced = [];
+    let displaceProblem = '';
+    try {
+        displaced = movePreviousRunAside(config.projectRoot);
+    }
+    catch (err) {
+        displaceProblem = err.message;
+    }
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
     const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
         ? '`unitbob suite-review-prepare` before upload'
         : '`unitbob put-suite-build`';
     actual.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
+    if (displaced.length > 0) {
+        actual.stdout.write(`The previous run's ${displaced.join(', ')} moved to ` +
+            `${request.project_root}/.unitbob/suite-build/previous/ — none of it is left where this build will ` +
+            'look, and none of it was deleted.\n');
+    }
+    if (displaceProblem) {
+        actual.stdout.write(`\nThe previous run's files could not be moved out of the way (${displaceProblem}). This build is fine, ` +
+            'but a plan or checkpoint left over from it will be refused by its own gate — the digests belong to ' +
+            'the request that was just replaced.\n');
+    }
+    actual.stdout.write(packetNotice(request.project_root, sourcePackets));
     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 ` +
@@ -288,8 +327,45 @@ export async function suitePrepare(config, args = [], deps) {
             '\n');
     }
 }
+// A checkout we cannot write packets into is a run without packets, not a
+// failed build: the workers search the source themselves, exactly as they did
+// before this spec. The same rule the route inventory follows for the same
+// reason — a read-only checkout or a full disk must not take a build down.
+function buildPackets(projectRoot, request) {
+    try {
+        return writeSuitePackets(projectRoot, request);
+    }
+    catch (err) {
+        return err.message;
+    }
+}
+function packetNotice(projectRoot, packets) {
+    if (typeof packets === 'string') {
+        return (`\nNo packets were written this run (${packets}). Workers find their own source, as before.\n`);
+    }
+    if (packets.targets === 0)
+        return '';
+    const where = `${projectRoot}/${PACKETS_DIR}`;
+    const head = packets.files === 0
+        ? `\nNo packet was written this run, so ${where} holds only its index.\n`
+        : `\n${packets.files} ${packets.files === 1 ? 'packet' : 'packets'} (${packets.bytes.toLocaleString('en-US')} bytes) ` +
+            `written to ${where}: the source behind ${packets.resolved} of ${packets.targets} entrypoints, resolved from this ` +
+            `machine's own graph and route inventory without asking a model. Hand each worker the paths of its packets, ` +
+            'never their contents — `unitbob accept-worker-plan` prints them per worker.\n';
+    // Two different outcomes, never merged: a file that was found and not carried
+    // still saves the worker the search, and a name nothing answered to does not.
+    const carried = packets.located - packets.resolved;
+    const unknown = packets.targets - packets.located;
+    if (carried === 0 && unknown === 0)
+        return head;
+    return (head +
+        `${carried + unknown} of ${packets.targets} entrypoints have no packet` +
+        (carried > 0 ? `; ${carried} name a file that was found but not carried` : '') +
+        ` (${packets.notes.join('; ')}). ` +
+        `Each says why in ${where}/index.json.\n`);
+}
 // The runner's own rule for which step files it will load, in the words of the
-// side that loads them (spec 44, §3.2). The same object is in `request.json`, on
+// 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
 // file.
 //

package/dist/wire.js

@@ -87,7 +87,7 @@ export class Wire {
     // carries one result per suite_kind.
     //
     // `dryRun` is the same route, the same body and the same server-side
-    // validation, stopped before the first write (spec 43, §1). It answers
+    // validation, stopped before the first write (spec one-place-per-rule, §1). It answers
     // `would_publish` instead of `created`, and it is deliberately not a route of
     // its own: a second route would grow a second implementation, which is the
     // defect this whole spec removes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "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.6.3 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.0 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/plugin/codex/agents/suite-worker.toml

@@ -7,10 +7,10 @@ You receive exactly one worker-plan item and the request paths it references.
 That item is your complete scope. Do not add capabilities, promises, examples,
 or scenarios after fan-out.
 
-Your checkpoint already exists: the coordinator wrote it before fan-out, at the
-path the workflow prescribes, with the exact request and plan digests, your
-branch and worker id, your promises in `unresolved_promises`, and the facts it
-had already verified. Never initialize it again — not on the first incarnation,
+Your checkpoint already exists: `accept-worker-plan` wrote it before fan-out, at
+the path the workflow prescribes, with the exact request and plan digests, your
+branch and worker id, and your promises in `unresolved_promises`; the
+coordinator added the facts it had already verified. Never initialize it again — not on the first incarnation,
 and not on an explicitly approved fresh incarnation after a native budget stop,
 where you preserve the supplied checkpoint and completed files and continue only
 its `unresolved_promises`. Update it after every completed promise.
@@ -62,7 +62,15 @@ workers got it as verified. One of them looked, disagreed, and kept its scenario
 honest, which is the only reason that access hole came back red instead of green.
 Nothing mechanical enforces any of this; it holds because you keep it.
 
-Read only the `source_paths` and dependencies your finite planned cases need.
+Your source packets are the starting point: do not go looking for what is
+already in one. A source packet is the whole file behind one of your entrypoints,
+found for you and put on disk, so opening it is a read and not a search. Your
+task names the paths — sometimes a path to open in place, when the file was too
+large to carry. If it names none, or the code you need is not in the ones it
+names, then search as you would have anyway.
+
+Read only the source packets, the `source_paths` and the dependencies your
+finite planned cases need.
 Ask closed questions with the files to look in. For a closed missing fact, use
 the named `fact-finder` agent, as often as the work genuinely needs. A lookup
 may confirm implementation facts but may not expand the plan.

package/dist/verbs/validateWorkerPlan.js

@@ -1,9 +0,0 @@
-import { validateWorkerPlanFiles, workerPlanDigest } from "../files/workerPlan.js";
-export async function validateWorkerPlan(config, _args = [], deps = { stdout: process.stdout }) {
-    const errors = validateWorkerPlanFiles(config.projectRoot);
-    if (errors.length > 0)
-        throw new Error(`Worker plan is invalid:\n- ${errors.join('\n- ')}`);
-    const planDigest = workerPlanDigest(config.projectRoot);
-    deps.stdout.write(`Worker plan valid (${planDigest}). Fan-out may start.\n`);
-    return { plan_digest: planDigest };
-}