unitbob 0.6.3 → 0.7.1

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/fanOut.js

@@ -0,0 +1,148 @@
+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`);
+}

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,325 @@
+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;
+            // The size travels even when the contents do not, so spec 37-3 can weigh
+            // this entrypoint. `packet` stays unset: there is still nothing to open
+            // under the packets folder, and every reader keys off that, not off size.
+            if (refusal.bytes !== undefined)
+                target.bytes = refusal.bytes;
+            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',
+                bytes: stat.size,
+            };
+        }
+        // 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