unitbob 0.7.4 → 0.7.6

package/dist/cli.js

@@ -57,8 +57,11 @@ Verbs:
                        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),
-                       then run every branch it published and report the server's results.
+  put-suite-build [branch]
+                       Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
+                       then run every branch it published and report the server's results. Name a branch
+                       to publish that one alone, as soon as it is finished; with no argument both are
+                       expected, and one the answer never mentions is reported.
   run-local [branch]   Internal: run the suite you just wrote, before publishing it, with the same runner
                        that will run it afterwards. No argument runs every branch the build asked for.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).

package/dist/files/suiteBuild.js

@@ -284,6 +284,27 @@ export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext
     writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
     return request;
 }
+// Which branches a command was told to work on. No name means all of them — the
+// "one suite, one run" shape both recipes insist on, so the default never teaches
+// the habit the recipes forbid. A name narrows: `run-local` uses it for the
+// repair loop, where re-running the finished peer is pure cost, and
+// `put-suite-build` for publishing a branch the moment it is done (spec 41,
+// criterion 3).
+//
+// One parse and one sentence for both, because it is one rule. They had a copy
+// each and worded the same user error two different ways, which makes a person
+// who has met one of them read the other as a different problem.
+export function namedBranches(request, args) {
+    const all = request.branches.map((branch) => branch.suite_kind);
+    const named = args.filter((arg) => !arg.startsWith('-'));
+    if (named.length === 0)
+        return [];
+    const unknown = named.filter((name) => !all.includes(name));
+    if (unknown.length > 0) {
+        throw new Error(`This suite build has no branch called ${unknown.join(', ')}. It asked for: ${all.join(', ')}.`);
+    }
+    return named;
+}
 export function readSuiteBuildRequest(projectRoot) {
     const path = requestPath(projectRoot);
     if (!existsSync(path)) {

package/dist/files/workerPlan.js

@@ -21,6 +21,48 @@ export function requestDigest(projectRoot) {
 export function workerPlanDigest(projectRoot) {
     return exactFileDigest(workerPlanPath(projectRoot));
 }
+// The addresses the request handed to each capability, indexed by id. The
+// checkpoint gate needs them for one question only: was this address given to
+// this slice at all (spec 41, criterion 1). What a slice *left* is not worked out
+// anywhere in this repo — answering that means reading how much of a capability
+// is guarded, which is Rails' to say and, as the architecture guard notes, not a
+// sentence `src/` is even allowed to write.
+//
+// A capability whose assignment lists no surfaces is absent from the map rather
+// than present with an empty list: "this assignment does not say" and "this
+// capability has no addresses" are different, and only the first must leave
+// membership unchecked.
+export function assignedSurfaces(projectRoot) {
+    const request = readRequest(projectRoot);
+    const byId = new Map();
+    for (const branch of Array.isArray(request.branches) ? request.branches : []) {
+        const assignment = branch.assignment;
+        for (const entry of Array.isArray(assignment?.capabilities) ? assignment.capabilities : []) {
+            const capability = entry;
+            const id = capability?.capability_id;
+            const surfaces = capability?.surfaces;
+            if (!isNonEmptyString(id) || !Array.isArray(surfaces) || surfaces.length === 0)
+                continue;
+            byId.set(id, surfaces.filter(isNonEmptyString));
+        }
+    }
+    return byId;
+}
+// The task, read as loosely typed JSON.
+//
+// `readSuiteBuildRequest` in `suiteBuild.ts` returns the same file typed, and is
+// the obvious thing to call — but that module imports this one, so calling it
+// back would close an import cycle. This is the price, written down so the next
+// reader does not spend the same minutes finding out why.
+function readRequest(projectRoot) {
+    const path = requestPath(projectRoot);
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+}
 export function readWorkerPlan(projectRoot) {
     const path = workerPlanPath(projectRoot);
     if (!existsSync(path))
@@ -97,9 +139,15 @@ function seedFor(item, request_digest, plan_digest) {
         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: [] } : {}),
+        // Behavioral only, and absent rather than empty elsewhere — they are about
+        // addresses, and the structural branch has none.
+        //
+        // `unreachable_surfaces` is seeded empty because empty is the honest common
+        // answer and the gate wants the key present either way. Its peer bucket,
+        // `deferred_surfaces`, is deliberately not here: what a slice did not take is
+        // the remainder of what it did, and it is worked out where the upload is
+        // assembled. Two places to answer one question is how the two drift.
+        ...(item.branch === 'behavioral' ? { surface_coverage: [], unreachable_surfaces: [] } : {}),
         facts: [],
     };
 }
@@ -111,13 +159,7 @@ export function validateWorkerPlanFiles(projectRoot) {
     const errors = [];
     const rubyProject = detectStructuralRunner(projectRoot) === 'rspec';
     const plan = readWorkerPlan(projectRoot);
-    let request;
-    try {
-        request = JSON.parse(readFileSync(requestPath(projectRoot), 'utf8'));
-    }
-    catch (error) {
-        throw new Error(`${requestPath(projectRoot)} is not valid JSON: ${error.message}`);
-    }
+    const request = readRequest(projectRoot);
     if (!plan || typeof plan !== 'object')
         return ['worker plan must be an object'];
     if (plan.request_digest !== requestDigest(projectRoot))

package/dist/runner/provision.js

@@ -523,7 +523,23 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
         // the exact shape of failure 35-1 closes. A project that does carry it keeps
         // its own version, and now actually gets to: see the comment on the helper
         // for what asking twice cost A2.Time.
-        gemLineUnlessTheProjectHasIt('webmock');
+        gemLineUnlessTheProjectHasIt('webmock') +
+        // The connector-owned World does not merely mention rspec — it requires
+        // `rspec/expectations` and `rspec/mocks` at load and runs a full mock
+        // lifecycle per scenario (`src/files/behavioral.ts`). Until spec 40 the
+        // sidecar never asked for either, so a Rails project on minitest got a World
+        // that could not load: noahsat-web died on `cannot load such file --
+        // rspec/expectations` and lost its behavioral branch entirely.
+        //
+        // Unpinned, and that is a safety condition rather than a taste. A project
+        // carrying `rspec-rails` does not declare `rspec-expectations` explicitly —
+        // it arrives transitively — so the guard above does not fire and our line is
+        // added. It resolves without conflict because the sidecar starts from a copy
+        // of the project's own lock (below) and `>= 0` constrains nothing, leaving
+        // the version rspec-rails already chose. A pin that missed that line would be
+        // a `Bundler::VersionConflict` at install instead.
+        gemLineUnlessTheProjectHasIt('rspec-expectations') +
+        gemLineUnlessTheProjectHasIt('rspec-mocks');
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }

package/dist/verbs/putSuiteBuild.js

@@ -1,4 +1,4 @@
-import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { namedBranches, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { placeProblem } from "../runner/place.js";
 import { collectBuildProblems } from "./validateBuild.js";
 import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.js";
@@ -20,17 +20,40 @@ import { Wire } from "../wire.js";
 //
 // Returns the server's per-branch results so the caller can compose the first run
 // on top of them (spec 32-4) without parsing the lines printed here.
-export async function putSuiteBuild(config, _args = [], deps) {
+export async function putSuiteBuild(config, args = [], deps) {
     // Spec 36, criterion 7. Publishing is followed immediately by a first run, so
     // a place that cannot be used is not something to discover after the suite is
     // stored on the server.
     const unusable = placeProblem(config.projectRoot);
     if (unusable)
         throw new Error(`${unusable}\nNothing was uploaded.`);
-    const request = readSuiteBuildRequest(config.projectRoot);
+    // Spec 41, criterion 3. The one thing a caller may say about scope: publish
+    // these branches, and only these.
+    //
+    // a2time, 2026-09-05. A two-hour run was interrupted mid-repair and left
+    // nothing on the server, though a complete answer for both branches had been
+    // sitting on disk since before the first run. Uploading one branch was never
+    // the problem — a missing branch has always been named against itself and never
+    // sunk the batch. What was missing is a way to say the peer's absence is the
+    // plan: `collectBuildProblems` exists to catch a branch abandoned in silence,
+    // and on a branch-at-a-time publish it would cry wolf every run.
+    //
+    // The request is cut down once, here, so every later step answers the same
+    // question about the same list instead of each remembering to skip the peer.
+    const whole = readSuiteBuildRequest(config.projectRoot);
+    const only = namedBranches(whole, args);
+    const request = only.length > 0
+        ? { ...whole, branches: whole.branches.filter((branch) => only.includes(branch.suite_kind)) }
+        : whole;
     // Spec 32-6: read branch by branch, so one unreadable entry neither hides the
     // next branch's problems nor sinks a peer that is finished and correct.
-    const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
+    const answer = readHostSuiteOutputsPerBranch(request.output_path, request);
+    // The answer file is the whole run's, not this call's: when a branch is named,
+    // its peer's entry is somebody else's business — already published by an
+    // earlier call, or still being repaired — and reading it here would report the
+    // peer as unpublishable for the sole reason that this call was not about it.
+    const outputs = answer.outputs.filter((output) => only.length === 0 || only.includes(output.suite_kind));
+    const unreadable = answer.unreadable.filter((entry) => only.length === 0 || only.includes(entry.suite_kind));
     const d = {
         putSuiteBuilds: (items) => new Wire(config).putSuiteBuilds(items),
         stdout: process.stdout,

package/dist/verbs/runLocal.js

@@ -1,4 +1,4 @@
-import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { branchRunner, namedBranches, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { digestOf, failureSet, readRunState, rememberFailures, reportedFailures, } from "../runner/failureDigest.js";
 import { placeProblem } from "../runner/place.js";
 import { placeAdvice } from "../runner/placeAdvice.js";
@@ -82,20 +82,11 @@ function compareFailures(config, d, suiteKind, ran, before) {
         'Running it again unchanged prints this same line.\n');
     return true;
 }
-// Which branches to run. No argument runs every branch the request asked for —
-// the same "one suite, one run" shape both recipes insist on, so the default
-// never teaches the habit the recipes forbid. A named branch is for the repair
-// loop, where re-running the finished peer is pure cost.
+// Which branches to run: the ones named, or every branch the request asked for.
+// The parse and the error live in `namedBranches`, shared with the publish side.
 function selectBranches(request, args) {
-    const all = request.branches.map((branch) => branch.suite_kind);
-    const named = args.filter((arg) => !arg.startsWith('-'));
-    if (named.length === 0)
-        return all;
-    const unknown = named.filter((name) => !all.includes(name));
-    if (unknown.length > 0) {
-        throw new Error(`This suite build has no branch called ${unknown.join(', ')}. It asked for: ${all.join(', ')}.`);
-    }
-    return named;
+    const named = namedBranches(request, args);
+    return named.length > 0 ? named : request.branches.map((branch) => branch.suite_kind);
 }
 // Non-null when the runner actually executed the branch. Everything else — no
 // entry, a declared `build_error`, a stack that cannot run it — is a branch that

package/dist/verbs/validateWorkerCheckpoints.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { checkpointPath, readWorkerPlan, requestDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
+import { assignedSurfaces, checkpointPath, readWorkerPlan, requestDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
 export async function validateWorkerCheckpoints(config, _args = [], deps = { stdout: process.stdout }) {
     const planErrors = validateWorkerPlanFiles(config.projectRoot);
     if (planErrors.length > 0)
@@ -7,6 +7,7 @@ export async function validateWorkerCheckpoints(config, _args = [], deps = { std
     const plan = readWorkerPlan(config.projectRoot);
     const expectedRequestDigest = requestDigest(config.projectRoot);
     const expectedPlanDigest = workerPlanDigest(config.projectRoot);
+    const assigned = assignedSurfaces(config.projectRoot);
     const errors = [];
     for (const item of plan.workers) {
         const label = `${item.branch}:${item.worker_id}`;
@@ -53,6 +54,7 @@ export async function validateWorkerCheckpoints(config, _args = [], deps = { std
         }
         validateCompactFacts(checkpoint.facts, label, errors);
         validateSurfaceCoverage(checkpoint.surface_coverage, item, label, errors);
+        validateUnreachableSurfaces(checkpoint.unreachable_surfaces, item, checkpoint.surface_coverage, assigned, label, errors);
         stringArray(checkpoint.decisions, `${label}: decisions`, errors);
         stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
     }
@@ -139,6 +141,75 @@ function validateSurfaceCoverage(value, item, label, errors) {
         }
     }
 }
+// Spec 41, criterion 1. Every assigned address ends in one of three places:
+// driven by a Scenario, unreachable, or deferred. Only the first two are answers
+// a worker can give — deferred is whatever is left, worked out where the upload
+// is assembled, so a slice never has to enumerate what it did not do.
+//
+// a2time, 2026-09-05. Eight capabilities left 81 addresses in none of the three,
+// and the server refused the publication after two hours. The workers were not
+// careless: `deferred_surfaces` was only legal past the ceiling of twenty, six of
+// those eight never came near it, and silence was the only move left. Widening
+// the deferred bucket gave them a legal answer; computing it gave them a free
+// one. What stays here is the pair the machine cannot work out on its own.
+//
+// Behavioral only, for the same reason as its neighbour: the structural branch
+// has no addresses to account for.
+function validateUnreachableSurfaces(value, item, coverage, assigned, label, errors) {
+    if (value === undefined && item.branch !== 'behavioral')
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`${label}: unreachable_surfaces must be an array of {surface, reason} entries, empty when the slice can drive everything it was given`);
+        return;
+    }
+    const driven = new Set(drivenSurfaces(coverage));
+    // Membership is measured against the addresses this slice's own capabilities
+    // were given, never the whole assignment: a neighbour's address is as foreign
+    // as an invented one.
+    const mine = item.capability_ids.flatMap((id) => assigned.get(id) ?? []);
+    const known = new Set(mine);
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            errors.push(`${label}: unreachable_surfaces[${index}] must be an object with surface and reason; got ${jsonType(entry)}`);
+            continue;
+        }
+        const record = entry;
+        const surface = record.surface;
+        if (typeof surface !== 'string' || !surface.trim()) {
+            errors.push(`${label}: unreachable_surfaces[${index}].surface must name one address`);
+            continue;
+        }
+        // A reason per address, never one reason for a list. A sentence you cannot
+        // write about *this* address is the signal it is not really unreachable —
+        // which is the whole guard, and the reason this bucket stays narrow while
+        // its neighbour widened.
+        if (typeof record.reason !== 'string' || !record.reason.trim()) {
+            errors.push(`${label}: unreachable_surfaces[${index}].reason must say what has to happen elsewhere for ${surface} to be called`);
+        }
+        if (driven.has(surface)) {
+            errors.push(`${label}: ${surface} is driven by a Scenario and declared unreachable — it is one or the other`);
+        }
+        // Only when the assignment actually listed addresses for this capability.
+        // An assignment that says nothing cannot say a surface is foreign, and
+        // refusing there would refuse honest slices over an absence.
+        if (known.size > 0 && !known.has(surface)) {
+            errors.push(`${label}: ${surface} was not assigned to this slice`);
+        }
+        if (seen.has(surface))
+            errors.push(`${label}: unreachable_surfaces names ${surface} more than once`);
+        else
+            seen.add(surface);
+    }
+}
+function drivenSurfaces(coverage) {
+    if (!Array.isArray(coverage))
+        return [];
+    return coverage.flatMap((entry) => {
+        const surfaces = entry?.surfaces;
+        return Array.isArray(surfaces) ? surfaces.filter((surface) => typeof surface === 'string') : [];
+    });
+}
 function jsonType(value) {
     if (value === null)
         return 'null';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "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.4 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.6 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

@@ -46,6 +46,22 @@ said about their work; the independent reviewer read the steps instead, six
 Scenarios claimed addresses their steps never drove, and the server refused the
 publication.
 
+Your checkpoint also carries `unreachable_surfaces`, and it is usually empty. An
+address goes there only when *nothing you can do* makes that request happen — a
+third party's callback, a vendor's webhook, a redirect a real account has to
+send. Each one needs its own sentence saying what has to happen elsewhere:
+```json
+{"surface":"GET /oauth2callback","reason":"The provider sends the user back here after they approve access, and no test can cause that."}
+```
+Hard is not unreachable. Authentication, a fixture that takes work, a background
+job, a paid API with a sandbox — all drivable, so drive them.
+
+You do **not** list the addresses you simply did not take. Whatever you neither
+drove nor declared unreachable is the remainder, and the map shows it beside the
+capability as *not taken this time* — "6 of 21 addresses guarded". So take the
+ones that matter first: money, then authorization, then the addresses the rest of
+the code points at most.
+
 Write first, then find out. Start with the planned cases your seeded facts
 already support and get them onto disk; go reading only for what you still lack
 after that. The opposite order — survey the sources, then write — is what spent