unitbob 0.7.0 → 0.7.1

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

@@ -84,6 +84,11 @@ export function writeSuitePackets(projectRoot, request) {
         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;
         }
@@ -292,6 +297,7 @@ function copyPacket(projectRoot, sourceFile) {
             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.

package/dist/files/workerPlan.js

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

package/dist/verbs/suitePrepare.js

@@ -1,6 +1,7 @@
 import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
+import { branchWorkloads, workloadLine } from "../files/fanOut.js";
 import { PACKETS_DIR, writeSuitePackets } from "../files/packets.js";
 import { movePreviousRunAside, recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bddStepLoading } from "../runner/bdd.js";
@@ -279,6 +280,7 @@ export async function suitePrepare(config, args = [], deps) {
             'the request that was just replaced.\n');
     }
     actual.stdout.write(packetNotice(request.project_root, sourcePackets));
+    actual.stdout.write(workloadNotice(request.project_root));
     actual.stdout.write(`Next: build ${branches.length === 1 ? 'the' : 'both'} peer ${branches.length === 1 ? 'suite' : 'suites'} (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
         `write your answer to ${request.output_path} as a branches array — one entry per branch named above, and a branch you cannot ` +
         `finish says so in its own entry rather than being left out of the array. Run each locally with \`unitbob run-local\` (the same ` +
@@ -364,6 +366,22 @@ function packetNotice(projectRoot, packets) {
         ` (${packets.notes.join('; ')}). ` +
         `Each says why in ${where}/index.json.\n`);
 }
+// Spec 37-3, criterion 1. The size of the work, printed before the plan exists,
+// because that is the only moment it can decide anything: the packets are built
+// from the request's entrypoints, and the entrypoints are known before the
+// workers are. A number that arrives after the plan is a number the plan was
+// not made from.
+function workloadNotice(projectRoot) {
+    const loads = branchWorkloads(projectRoot);
+    if (loads.length === 0)
+        return '';
+    return ('\nHow much each branch has to read, over the whole assignment and before you narrow it:\n' +
+        loads.map(workloadLine).join('') +
+        'This does not set how many workers a branch gets, and that is worth knowing before you plan: ' +
+        'on the bench of 2026-08-24 the branch with three times the source spent half the turns. What ' +
+        'sets the width is how many cases you intend to write, so it is decided by the plan and ' +
+        'checked by `accept-worker-plan`, which prints the band it accepted.\n');
+}
 // The runner's own rule for which step files it will load, in the words of the
 // side that loads them (spec ask-before-you-spend, §3.2). The same object is in `request.json`, on
 // the behavioral branch; this is the copy the coordinator sees without opening a

package/package.json

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

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

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.7.0 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.1 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