unitbob 0.7.3 → 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/runner/vitest.js

@@ -16,6 +16,56 @@ export const VITEST_CONFIG_FILE = join('.unitbob', 'vitest.config.mjs');
 // and is rewritten immediately before every run, so a boot check that reused it
 // would either be overwritten or leave the run pointing at a probe.
 export const VITEST_BOOT_CONFIG_FILE = join('.unitbob', 'vitest.boot.config.mjs');
+// The structural branch's one shared setup file (spec 39). The coordinator
+// writes it before fan-out and owns it afterwards: it holds whatever has to
+// happen before the first import of any file of the branch — environment
+// variables, a TypeScript loader registration, at the very last resort an entry
+// through the project's root module.
+//
+// A fixed name rather than a new protocol field, because the file has to survive
+// the round trip: `materializeGuardrails` wipes this directory and lays the
+// artifact out again, so the file must travel as an ordinary `support_files`
+// entry — and every such entry is otherwise handed to the runner as a test path.
+// One constant here, read by the config builder, by both collectors of test
+// paths, and by `suite-prepare`, is the whole of the agreement. A field would
+// have had to be agreed with the server and both of its version models.
+//
+// One name, one extension. A second one buys nothing: vitest puts every setup
+// file through vite, so `require` is undefined in a `.js` setup file just as it
+// is in a `.ts` one.
+export const STRUCTURAL_SETUP_FILE = '.unitbob/structural/_setup.ts';
+// The project-relative path of that file, or `undefined` when it has not been
+// written yet. Two callers, one question: the config builder asks it to decide
+// whether to name the file in `setupFiles`, and `suite-prepare` asks it to
+// decide whether the boot probe is a scout or a sentry (spec 39, criterion 4).
+// Deliberately the same observable fact for both, rather than a flag — 32-6
+// forbids a mode, and a mode would let the two sides disagree about which run
+// they are in.
+export function setupFileOf(projectRoot) {
+    return existsSync(join(projectRoot, STRUCTURAL_SETUP_FILE)) ? STRUCTURAL_SETUP_FILE : undefined;
+}
+// Whether anything of ours can run before this stack's branch imports its first
+// module. Only vitest, because `setupFiles` is a vitest notion and the builder
+// below is the single place that inserts our file. Kept here, beside the
+// insertion it describes, rather than in the verb that asks: the verb would be
+// stating a fact about a module it does not own, and the two could then drift.
+export function canPrepareBeforeImports(runner) {
+    return runner === 'vitest';
+}
+// The files of an artifact that a runner may be pointed at, which is all of them
+// except the shared setup file. It travels as an ordinary `support_files` entry
+// so that materialization writes it back rather than wiping it, and it holds no
+// cases at all: a runner given it as a test path opens it, finds nothing, and
+// reports that nothing as a suite.
+//
+// One filter for both collectors — the check flow's and run-local's — because
+// the two must never disagree about which file this is. A leading `./` is
+// tolerated: the answer that names the file is hand-written, and two characters
+// must not be what decides whether the branch's preparation is executed or
+// collected.
+export function testPathsOf(paths) {
+    return paths.filter((path) => path.replace(/^\.\//, '') !== STRUCTURAL_SETUP_FILE);
+}
 // The project configs we inherit from, most specific first. Vitest reads a
 // project's own config even when we pass `--config`, so we must merge ours with
 // it rather than replace it (plugins, path aliases and resolve settings the
@@ -87,7 +137,7 @@ export async function runVitestSuite(projectRoot, suitePaths) {
 function writeMergedConfig(projectRoot, suitePaths) {
     const path = join(projectRoot, VITEST_CONFIG_FILE);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run'));
+    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run', setupFileOf(projectRoot)));
     return ['--config', VITEST_CONFIG_FILE];
 }
 // The same config, shaped for the boot check's probe (spec 38). Returned as text
@@ -95,7 +145,12 @@ function writeMergedConfig(projectRoot, suitePaths) {
 // puts in the project: it writes them together and removes them together, and a
 // writer here would take half of that away from the one place that can see it.
 export function vitestBootConfigSource(projectRoot, probePath) {
-    return configSource(projectConfigOf(projectRoot), [probePath], 'boot');
+    // The same preparation the run will get, which is the point of asking twice
+    // (spec 39, criterion 4). On the first `suite-prepare` there is no setup file
+    // and the probe answers "these files do not load on their own"; on the second,
+    // after the coordinator wrote one, it answers the question the run will
+    // actually put — and only then is a red answer worth a branch.
+    return configSource(projectConfigOf(projectRoot), [probePath], 'boot', setupFileOf(projectRoot));
 }
 function projectConfigOf(projectRoot) {
     return PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
@@ -118,13 +173,25 @@ function projectConfigOf(projectRoot) {
 // and `defineConfig` is a typing helper that buys a generated file nothing.
 // `mode` is the boot check's two differences from the run, and they go together:
 // globals on, and a workspace refused. See `vitestBootConfigSource`.
-function configSource(projectConfig, suitePaths, mode) {
+//
+// `setupFiles` is the one field that is added to rather than replaced (spec 39,
+// criterion 2). The project's own entry is what raises its test database and
+// reads its environment — epic-stack's `tests/setup/setup-test-env.ts` is why
+// its 50 structural checks have a database to read — and replacing it would
+// take that away from the only structural suite on the bench that works. Ours
+// goes first: it exists to set things up before the first import of anything,
+// and the project's own setup file opens with imports of the application.
+function configSource(projectConfig, suitePaths, mode, setupFile) {
     // After the project's own `test`, never before it: ours has to win.
-    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}include: ${JSON.stringify(suitePaths)}`;
+    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}${setupFile ? 'setupFiles, ' : ''}include: ${JSON.stringify(suitePaths)}`;
     const header = '// Written by the unitbob connector before each vitest run — do not edit.';
     if (!projectConfig) {
+        // Nothing to inherit, so nothing to concatenate — but the shared file is
+        // still the branch's, and a project with no config of its own is exactly
+        // the kind that needs it.
+        const alone = setupFile ? `const setupFiles = ${JSON.stringify([setupFile])};\n` : '';
         return `${header}
-export default { test: { ${settings} } };
+${alone}export default { test: { ${settings} } };
 `;
     }
     // Globals, because the probe lives in `.unitbob/structural/`: an
@@ -144,13 +211,20 @@ const { projects, workspace, ...test } = base.test ?? {};
         : `
 const test = base.test ?? {};
 `;
+    // `[].concat(x)` on purpose: vitest accepts `setupFiles` as an array or as a
+    // bare string, and most projects set neither. All three forms arrive here and
+    // all three have to come out an array, because a config that throws while it
+    // is being read takes the whole run with it.
+    const merge = setupFile
+        ? `const setupFiles = ${JSON.stringify([setupFile])}.concat(test.setupFiles ?? []);\n`
+        : '';
     return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
-${narrow}
+${narrow}${merge}
 export default { ...base, test: { ...test, ${settings} } };
 `;
 }

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

@@ -4,7 +4,7 @@ import { placeProblem } from "../runner/place.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
-import { runVitestSuite } from "../runner/vitest.js";
+import { runVitestSuite, testPathsOf } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { enterUrl } from "../links.js";
@@ -147,8 +147,11 @@ 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 one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
+//
+// Every file except the branch's shared setup file, which `testPathsOf` drops
+// (spec 39): it is named in `setupFiles` instead of being collected from.
 function artifactPaths(file) {
-    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+    return testPathsOf([file.path, ...(file.support_files ?? []).map((entry) => entry.path)]);
 }
 function suiteError(suiteDigest, message) {
     return {

package/dist/verbs/runLocal.js

@@ -1,10 +1,11 @@
-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";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { testPathsOf } from "../runner/vitest.js";
 import { runStructuralByRunner } from "./run.js";
 const OUTPUT_TAIL_CHARS = 4000;
 export async function runLocal(config, args = [], deps) {
@@ -81,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
@@ -259,7 +251,11 @@ function artifactPathsOf(output) {
     const rest = support
         .map((entry) => entry?.path)
         .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
-    return [path, ...rest];
+    // Everything but the branch's shared setup file (spec 39): it is a support
+    // file so that it survives materialization, and it is named in `setupFiles`
+    // rather than handed over as a path to collect tests from. Literally the same
+    // filter the check flow uses, because both sides have to mean the one file.
+    return testPathsOf([path, ...rest]);
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -11,6 +11,7 @@ import { placeProblem } from "../runner/place.js";
 import { alignRunnerEnvironmentWithPlace } from "../runner/placeEnvironment.js";
 import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { canPrepareBeforeImports, setupFileOf, STRUCTURAL_SETUP_FILE } from "../runner/vitest.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -225,13 +226,52 @@ export async function suitePrepare(config, args = [], deps) {
     // and boots the application for itself, so asking with no structural branch in
     // the run would start Rails to answer a question nobody put — and a `broken`
     // answer would then report a branch this build never had.
+    //
+    // Spec 39 kept the sentry and moved the sentence. The probe asks its question
+    // twice: once before anything has been prepared for these files, and once
+    // after the coordinator has written the branch's shared setup file. Only the
+    // second answer costs a branch, because only the second one asks what the run
+    // will ask. Before the setup file exists the probe's question — "do these
+    // files load with nothing in front of them" — is stricter than the condition
+    // it stands in for, and `docs/adr/0001` forbids exactly that: the condition
+    // tested must equal the condition that makes a run impossible, never exceed
+    // it. Two bench projects were refused on that excess while their behavioral
+    // peers built and stayed green.
+    //
+    // The switch is the file on disk and nothing else. No flag and no mode: 32-6
+    // forbade them, and the connector has to ask this same question anyway to
+    // decide whether to name the file in `setupFiles`, so a second signal could
+    // only ever disagree with the first.
+    //
+    // And only on the stack where a preparation can actually be put in front of
+    // the imports — `canPrepareBeforeImports`, which is vitest and only vitest. On
+    // rspec and pytest nothing of ours runs before the branch's imports, so there
+    // the probe's question already *is* the run's question: no excess to correct,
+    // and a red answer costs the branch on the first run exactly as it has since
+    // 32-6. Waiting for a file those stacks will never have would have quietly
+    // reopened the funnel that spec closed.
+    //
+    // One thing this sign cannot see: a setup file left over from an earlier
+    // build. It comes back with the artifact and is materialized like any other
+    // file of the branch, so on a re-generation the probe sentences on its first
+    // ask instead of scouting. That is the honest reading — a preparation does
+    // exist and the probe went through it — and the way out is the same one the
+    // verdict already names: fix that file, run `suite-prepare` again. Telling the
+    // two apart would need a memory of which build wrote it, which is a mode by
+    // another name, and 32-6 forbade those.
     const bootNotices = [];
+    const bootAdvisories = [];
     const structuralIndex = branches.findIndex((branch) => branch.suite_kind === 'structural');
     if (structuralIndex !== -1) {
         const boot = await actual.bootCheck(config.projectRoot, structuralRunner, structuralSourceFiles(config.projectRoot, { branches }));
         if (boot.status === 'broken') {
-            branches.splice(structuralIndex, 1);
-            bootNotices.push(bootStop(boot, structuralRunner));
+            if (!canPrepareBeforeImports(structuralRunner) || setupFileOf(config.projectRoot)) {
+                branches.splice(structuralIndex, 1);
+                bootNotices.push(bootStop(boot, structuralRunner));
+            }
+            else {
+                bootAdvisories.push(bootAdvisory(boot, structuralRunner));
+            }
         }
         else {
             actual.stdout.write(bootFinding(boot, structuralRunner));
@@ -330,6 +370,18 @@ export async function suitePrepare(config, args = [], deps) {
             bootNotices.join('\n') +
             '\n');
     }
+    // The other half of the probe's answer (spec 39), and it needs a heading of
+    // its own: "was left out of this run" is true only of the verdict, and this
+    // branch was not left out of anything. It is being built, and what follows is
+    // the opening fact for whoever writes its preparation.
+    if (bootAdvisories.length > 0) {
+        actual.stdout.write('\nThe code-structure suite is still being built, and here is what its source files did on their own: ' +
+            `they did not load. Nothing has been put in front of them yet — that is what ${STRUCTURAL_SETUP_FILE} ` +
+            'is for, and writing it comes before the fan-out. None of your own tests were opened; only the files ' +
+            'the map named:\n' +
+            bootAdvisories.join('\n') +
+            '\n');
+    }
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.
     if (setupNotices.length > 0) {
@@ -434,16 +486,42 @@ function bootFinding(boot, runner) {
 // its peer carries on, `request.json` is written, and the vibecoder comes away
 // with the guardrails that branch can still give rather than with nothing.
 //
+// Reached only once the branch's shared setup file exists (spec 39). By then the
+// probe has been asked through that preparation, so a red answer is the run's
+// own answer and taking the branch is honest.
+function bootStop(boot, runner) {
+    return bootReport(boot, runner, true);
+}
+// The same red answer, read before anything was prepared for these files (spec
+// 39). Same facts, same words from the runner, same caveat — what differs is
+// the step that follows, and that is the whole difference between a scout and a
+// sentry. Nothing here is worded as a verdict on somebody's code, because on
+// this run it is not one: the files were asked to load with nothing in front of
+// them, and putting something in front of them is Unitbob's own work.
+function bootAdvisory(boot, runner) {
+    return bootReport(boot, runner, false);
+}
 // The two causes keep their separate next steps. An un-run `pip install` is not
 // somebody's bug and must not be worded as one; a module of theirs that raises
-// on import is theirs to fix and pointing at an install would waste their time.
-function bootStop(boot, runner) {
-    const next = boot.cause === 'defect_in_code'
-        ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
-        : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+// on import, asked with the preparation already in place, is theirs to fix and
+// pointing at an install would waste their time.
+//
+// The environment cause keeps the same next step in both reports: a missing gem
+// is not something a setup file can prepare its way around, and sending someone
+// to write one would waste the round it costs.
+function bootReport(boot, runner, prepared) {
+    const next = boot.cause !== 'defect_in_code'
+        ? 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
             'it never writes to your project. Something outside that file is still missing here. Run the ' +
             'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
-            'then run `unitbob suite-prepare` again.';
+            'then run `unitbob suite-prepare` again.'
+        : prepared
+            ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
+            : `This is what these files do with nothing in front of them, and the run will have ` +
+                `${STRUCTURAL_SETUP_FILE} in front of them. Put into that file whatever has to happen before the ` +
+                'first import — the environment variables the modules read, a loader registration, and only as a ' +
+                'last resort an entry through the project\'s root module — then run `unitbob suite-prepare` again ' +
+                'and this same question will be asked through it.';
     // `boot.message` is the runner's own words, indented but never paraphrased:
     // this is the line the vibecoder can paste into a search.
     return `  ${boot.message}\n\n${boot.detail}\n\n  ${next}${caveatFor(runner, '  ')}\n`;

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.3",
+  "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.3 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