unitbob 0.4.4 → 0.5.0

package/dist/runner/pytest.js

@@ -2,6 +2,7 @@ import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const PYTEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
@@ -11,19 +12,34 @@ export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
 // never part of the suite digest.
 export const PYTEST_INI_FILE = join('.unitbob', 'pytest.ini');
 export const PYTEST_INI = '[pytest]\naddopts =\n';
-// Run the materialised Unitbob guardrail suite with pytest in the current
-// Python environment (spec 30) — no guessing at Poetry/uv/virtualenv wrappers.
-// Only the guardrail file runs; the JUnit XML report goes to --junit-xml, not
-// stdout. The command is connector-owned: the suite artifact never carries a
-// command string.
-export async function runPytestSuite(projectRoot, suitePath) {
+// Run the materialised Unitbob guardrail suite with pytest (spec 30) — no
+// guessing at Poetry/uv/virtualenv wrappers. Only the guardrail files run; the
+// JUnit XML report goes to --junit-xml, not stdout. The command is
+// connector-owned: the suite artifact never carries a command string.
+//
+// Every file of the branch is named positionally (spec 42, §6.5) — a branch is
+// one file per assignment now, and pytest takes as many paths as it is given.
+//
+// Which pytest is a single question answered in one place (`locateRunner`), so
+// the precheck, the boot check and this run can never end up talking about
+// different interpreters. `python` is the last resort when nothing was found:
+// spawning it produces the honest "No module named pytest" rather than a silent
+// no-op, and the checks upstream have already had their chance to say so first.
+export async function runPytestSuite(projectRoot, suitePaths) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
-    const command = await pickPython(projectRoot);
-    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, suitePath, `--junit-xml=${PYTEST_RESULT_FILE}`];
+    const located = locateRunner(projectRoot, 'pytest');
+    const command = located?.command ?? 'python';
+    const args = [
+        ...(located?.args ?? ['-m', 'pytest']),
+        '-c',
+        PYTEST_INI_FILE,
+        ...suitePaths,
+        `--junit-xml=${PYTEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: PYTEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -33,14 +49,3 @@ export async function runPytestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, PYTEST_RESULT_FILE)),
     };
 }
-// The interpreter that can actually run pytest: `python3` when pytest imports
-// there (macOS/Linux ship no bare `python`), else `python`. Probing `-m pytest`
-// rather than just `--version` keeps this in step with pytestPrecheck, so the
-// run uses the same interpreter the precheck confirmed.
-async function pickPython(projectRoot) {
-    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
-        cwd: projectRoot,
-        timeoutMs: 10_000,
-    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
-    return probe.code === 0 ? 'python3' : 'python';
-}

package/dist/runner/rspec.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
+import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
@@ -8,17 +9,23 @@ export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // the project's random ordering.
 export const RSPEC_SEED = '1';
 export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
-// Run the materialised Unitbob guardrail suite (spec 26). Only this file runs —
+// Run the materialised Unitbob guardrail suite (spec 26). Only these files run —
 // never the project's full suite — under RAILS_ENV=test with a fixed order/seed.
 // --options points at the materialized empty file so the project's own .rspec
 // (a --require of a helper we replaced, an extra stdout formatter) can neither
 // break the boot nor corrupt the JSON output. The JSON report goes to `--out`
 // (a file), not stdout, so the app's own stdout writes during the run can never
-// corrupt it. `suitePath` is the suite blob's own project-relative path.
-export async function runRspecSuite(projectRoot, suitePath) {
+// corrupt it.
+//
+// `suitePaths` is every file of the branch in the suite blob's own
+// project-relative form (spec 42, §6.5). Named one by one rather than as a
+// directory: the artifact already says exactly which files it is, while a
+// directory would also collect whatever else happens to be sitting under the
+// root.
+export async function runRspecSuite(projectRoot, suitePaths) {
     const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
     const { result, command, args } = await invokeRspec(projectRoot, [
-        suitePath,
+        ...suitePaths,
         '--options',
         optionsPath,
         '--order',
@@ -38,18 +45,19 @@ export async function runRspecSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
     };
 }
-// Prefer the project's own `bin/rspec`; fall back to `bundle exec rspec`. Every
+// Which rspec — the sidecar Unitbob installed, the project's own `bin/rspec`
+// binstub, or `bundle exec rspec` — is decided once, in `locateRunner`, so this
+// run and the checks that predicted it always mean the same installation. Every
 // run sets RAILS_ENV=test so guardrails execute against the Rails test
 // environment the project's `rails_helper` configures.
 async function invokeRspec(projectRoot, rspecArgs) {
-    const localRspec = join(projectRoot, 'bin', 'rspec');
-    const hasLocalRspec = executable(localRspec);
-    const command = hasLocalRspec ? localRspec : 'bundle';
-    const args = hasLocalRspec ? rspecArgs : ['exec', 'rspec', ...rspecArgs];
+    const located = locateRunner(projectRoot, 'rspec');
+    const command = located?.command ?? 'bundle';
+    const args = [...(located?.args ?? ['exec', 'rspec']), ...rspecArgs];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: RSPEC_TIMEOUT_MS,
-        env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     });
     return { result, command, args };
 }

package/dist/runner/toolchain.js

@@ -0,0 +1,122 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { executable } from "../proc.js";
+// Where Unitbob keeps a test runner it had to install for itself, together with
+// whatever that runner needs to load the project.
+//
+// Deliberately not `.unitbob/structural/`: `materializeGuardrails` deletes that
+// directory before every suite write, so an environment installed there would be
+// rebuilt on every single run. Deliberately not the project's own dependency
+// files either — the whole point is that a vibecoder's repository looks exactly
+// the same after Unitbob has run as it did before. `.unitbob/` is already in
+// their .gitignore (see `ensureUnitbobIgnored`).
+export const SIDECAR_DIR = '.unitbob/runners';
+export function sidecarPath(projectRoot, ...segments) {
+    return join(projectRoot, SIDECAR_DIR, ...segments);
+}
+export const defaultToolDeps = {
+    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+};
+// How to invoke `runner` in this project, or null when nothing here can.
+//
+// The sidecar wins when it exists, and that order is deliberate. A sidecar is
+// only ever built because the project could not supply the runner itself, so
+// preferring it keeps every later run on the same environment the build was
+// prepared against. The alternative — asking the project first, every time —
+// lets a stray `pip install pytest` between two runs move the suite to a
+// different interpreter without anybody choosing that, and a guardrail suite
+// whose meaning is "green means fine" cannot afford a silent environment flip.
+export function locateRunner(projectRoot, runner, deps = defaultToolDeps) {
+    switch (runner) {
+        case 'pytest':
+            return locatePytest(projectRoot, deps);
+        case 'vitest':
+            return locateVitest(projectRoot);
+        case 'rspec':
+            return locateRspec(projectRoot);
+        default:
+            return null;
+    }
+}
+// Is a runner available at all — from the project or from a sidecar?
+export function runnerAvailable(projectRoot, runner, deps = defaultToolDeps) {
+    return locateRunner(projectRoot, runner, deps) !== null;
+}
+// Does the project supply this runner on its own, with no help from us? This is
+// the question provisioning asks before it builds anything: a project that is
+// already set up is left completely alone.
+//
+// Ruby answers from the Gemfile rather than from `locateRspec`, which always has
+// a `bundle exec rspec` to offer whether or not the gem behind it exists.
+export function projectProvidesRunner(projectRoot, runner, deps = defaultToolDeps) {
+    if (runner === 'rspec') {
+        return hasGemfileWith(projectRoot, /\brails\b/) && hasGemfileWith(projectRoot, /\brspec-rails\b/);
+    }
+    return locateRunner(projectRoot, runner, deps)?.source === 'project';
+}
+// Does one of the project's Gemfiles mention this? Shared by the Ruby precheck
+// and by the question above, so "is this a Rails project" is answered the same
+// way wherever it is asked.
+export function hasGemfileWith(projectRoot, pattern) {
+    for (const name of ['Gemfile', 'gems.rb']) {
+        const path = join(projectRoot, name);
+        if (existsSync(path) && pattern.test(readFileSync(path, 'utf8')))
+            return true;
+    }
+    return false;
+}
+// Python: an interpreter that can actually import pytest. The sidecar venv is
+// checked by file, the project's interpreters by asking them — `python3 -m
+// pytest --version` is the same question the run itself asks, so the two can
+// never disagree about which interpreter is usable.
+function locatePytest(projectRoot, deps) {
+    // The sidecar interpreter is asked the same question as any other, rather
+    // than trusted because the file is there. A virtualenv can exist and still
+    // have no pytest in it — `uv venv` creates one with no pip at all, so an
+    // install into it can fail while leaving a perfectly good `bin/python`
+    // behind. Trusting the file made provisioning report success and the boot
+    // check then say "No module named pytest" about an environment we had just
+    // built. Found on a Flask project, 2026-08-12.
+    const venvPython = sidecarPath(projectRoot, '.venv', 'bin', 'python');
+    if (executable(venvPython) && deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
+        return { command: venvPython, args: ['-m', 'pytest'], source: 'sidecar' };
+    }
+    for (const python of ['python3', 'python']) {
+        if (deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot)) {
+            return { command: python, args: ['-m', 'pytest'], source: 'project' };
+        }
+    }
+    return null;
+}
+// JS/TS: a vitest binary we can spawn. `npx` is not offered here — it would
+// install a package to answer a question, and this function's callers include
+// checks that must not install anything. The vitest runner keeps `npx` as its
+// own last resort, which is the behaviour it has always had.
+function locateVitest(projectRoot) {
+    const sidecar = sidecarPath(projectRoot, 'node_modules', '.bin', 'vitest');
+    if (executable(sidecar))
+        return { command: sidecar, args: [], source: 'sidecar' };
+    const project = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    if (executable(project))
+        return { command: project, args: [], source: 'project' };
+    return null;
+}
+// Ruby: bundler decides what "rspec" means, so the sidecar is selected by
+// pointing BUNDLE_GEMFILE at the sidecar Gemfile rather than by a different
+// binary. The project's own `bin/rspec` binstub is preferred over `bundle exec`
+// when it is there, exactly as the rspec runner has always preferred it.
+function locateRspec(projectRoot) {
+    if (existsSync(sidecarPath(projectRoot, 'Gemfile'))) {
+        return {
+            command: 'bundle',
+            args: ['exec', 'rspec'],
+            env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile` },
+            source: 'sidecar',
+        };
+    }
+    const binstub = join(projectRoot, 'bin', 'rspec');
+    if (executable(binstub))
+        return { command: binstub, args: [], source: 'project' };
+    return { command: 'bundle', args: ['exec', 'rspec'], source: 'project' };
+}

package/dist/runner/vitest.js

@@ -1,7 +1,8 @@
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
@@ -28,27 +29,44 @@ const PROJECT_CONFIGS = [
     'vite.config.cjs',
 ];
 // Run the materialised Unitbob guardrail suite with the project's own Vitest
-// (spec 30). Only the guardrail file runs — the path argument filters the run.
+// (spec 30). Only the guardrail files run — the path arguments filter the run.
 //
-// A bare `vitest run <file>` treats the path as a filter that is intersected
+// A bare `vitest run <file>` treats each path as a filter that is intersected
 // with the project's `test.include`, so a project whose include does not cover
-// `.unitbob/` would collect no tests. When the project has its own config we
-// therefore write a tiny config that merges it and adds the guardrail file to
-// `include`; the positional filter still narrows the run to that one file. With
-// no project config, Vitest's default include already covers `.unitbob/`, so
-// the bare command is correct and we write nothing.
+// `.unitbob/` would collect no tests. So the config Unitbob writes names every
+// file of the branch in `include`, and the positional filters keep the run to
+// exactly those files.
+//
+// Named files rather than a directory glob, since spec 42, §6.5 made a branch
+// several files: the artifact already says which files it is, and a glob would
+// have to guess a naming convention nothing enforces. `include` is written even
+// when the project has no config of its own — Vitest's default include only
+// covers `.unitbob/` for a file that happens to be named `*.test.ts`, which is a
+// trap set for whoever names a slice after its capability.
 //
 // The JSON report goes to --outputFile, not stdout, so app logging can never
 // corrupt it. The command is connector-owned: the suite artifact never carries
 // a command string.
-export async function runVitestSuite(projectRoot, suitePath) {
-    const configArgs = writeMergedConfig(projectRoot, suitePath);
-    const command = 'npx';
-    const args = ['vitest', 'run', suitePath, ...configArgs, '--reporter=json', `--outputFile=${VITEST_RESULT_FILE}`];
+export async function runVitestSuite(projectRoot, suitePaths) {
+    const configArgs = writeMergedConfig(projectRoot, suitePaths);
+    // An installed vitest — the sidecar's, else the project's — is spawned by
+    // path. `npx` stays as the last resort it has always been: it is the only
+    // option that can conjure a runner out of nothing, which is right here at the
+    // end and wrong everywhere else (see `locateRunner`, which does not offer it).
+    const located = locateRunner(projectRoot, 'vitest');
+    const command = located?.command ?? 'npx';
+    const args = [
+        ...(located ? located.args : ['vitest']),
+        'run',
+        ...suitePaths,
+        ...configArgs,
+        '--reporter=json',
+        `--outputFile=${VITEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: VITEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -58,31 +76,47 @@ export async function runVitestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
     };
 }
-// Returns the `--config` args to add, writing the merge config first. When the
-// project has no config of its own there is nothing to inherit and nothing to
-// override (defaults already cover .unitbob/), so we return no args.
-function writeMergedConfig(projectRoot, suitePath) {
+// Returns the `--config` args to add, writing the config first. Always written:
+// the branch's files have to be in `include` or nothing is collected, and the
+// names a worker gives its slice are not something to bet a whole run on.
+function writeMergedConfig(projectRoot, suitePaths) {
     const projectConfig = PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
-    if (!projectConfig)
-        return [];
-    writeFileSync(join(projectRoot, VITEST_CONFIG_FILE), mergedConfigSource(projectConfig, suitePath));
+    const path = join(projectRoot, VITEST_CONFIG_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, configSource(projectConfig, suitePaths));
     return ['--config', VITEST_CONFIG_FILE];
 }
 // The .unitbob/ config sits one level below the project root, so the project
-// config is a `../` import. `mergeConfig` concatenates `include`, so the
-// guardrail file joins the project's patterns instead of replacing them; the
-// positional filter then isolates it. A function-form config is resolved first.
-function mergedConfigSource(projectConfig, suitePath) {
-    return `// Written by the unitbob connector before each vitest run — do not edit.
-import { mergeConfig } from 'vitest/config';
+// config is a `../` import. A function-form config is resolved first, and
+// everything the project set — plugins, aliases, setup files, environment — is
+// carried through; only `test.include` is replaced, with exactly this branch's
+// files. Replacing rather than concatenating is the point: the run must be these
+// files and no others, and the positional filters then say the same thing twice.
+//
+// Nothing is imported from `vitest` itself, and that is deliberate. Vite
+// re-imports this generated file from a temporary module beside it, so every
+// bare `import` here resolves by walking up from `.unitbob/` — while a project
+// whose only vitest is the one Unitbob installed keeps it at
+// `.unitbob/runners/node_modules`, which is not on that path. An
+// `import { mergeConfig } from 'vitest/config'` there dies with
+// ERR_MODULE_NOT_FOUND before a single test is collected, on exactly the
+// projects the sidecar exists for. A spread does the same job with no import,
+// and `defineConfig` is a typing helper that buys a generated file nothing.
+function configSource(projectConfig, suitePaths) {
+    const include = `include: ${JSON.stringify(suitePaths)}`;
+    const header = '// Written by the unitbob connector before each vitest run — do not edit.';
+    if (!projectConfig) {
+        return `${header}
+export default { test: { ${include} } };
+`;
+    }
+    return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
 
-export default mergeConfig(base, {
-  test: { include: [${JSON.stringify(suitePath)}] },
-});
+export default { ...base, test: { ...(base.test ?? {}), ${include} } };
 `;
 }

package/dist/surfaces/routeInventory.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { dirname, join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
+import { detectStructuralRunner } from "../runner/precheck.js";
 import { graphPath } from "../files/mapBuild.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
@@ -20,7 +21,7 @@ export function routeInventoryPath(projectRoot) {
 // records why Django, FastAPI and Flask come next and why Express cannot follow
 // at all (its addresses are registered by arbitrary code at run time).
 export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
-    if (!looksLikeRails(projectRoot))
+    if (!canAskTheRouter(projectRoot))
         return silent(projectRoot, 'unsupported_stack');
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
@@ -150,8 +151,19 @@ function becauseOf(result) {
 function plural(count, one, many) {
     return count === 1 ? one : many;
 }
-function looksLikeRails(projectRoot) {
-    return existsSync(join(projectRoot, 'config', 'routes.rb'));
+// Which stack this is, is not this module's question — one answer to it already
+// exists and this file now asks it. `config/routes.rb` stays as a second-level
+// condition inside the Ruby branch, because a Rails application without a route
+// file has no router to ask.
+//
+// It used to be the whole test, which made it a fourth independent way of
+// deciding "is this Rails?" — and one that was wrong at both edges: a Rails app
+// that keeps its routes elsewhere was refused, and any project that happens to
+// carry a `config/routes.rb` was asked to boot Rails. There are still several
+// stack detectors in this package; this removes the one that had a single caller
+// and no excuse.
+function canAskTheRouter(projectRoot) {
+    return (detectStructuralRunner(projectRoot) === 'rspec' && existsSync(join(projectRoot, 'config', 'routes.rb')));
 }
 // The question, asked of the router object rather than of the `rails routes`
 // command line. `--expanded` was the earlier reading, and it cost this project

package/dist/verbs/codexInstall.js

@@ -2,7 +2,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder'];
+const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
 const bundledAgentsDir = fileURLToPath(new URL('../../plugin/codex/agents/', import.meta.url));
 export function installCodexAgents(args, deps = { home: homedir(), stdout: process.stdout }) {
     if (args.length > 0)

package/dist/verbs/putSuiteBuild.js

@@ -1,5 +1,6 @@
-import { readBehavioralReview, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { collectBuildProblems, formatBranchProblems } from "./validateBuild.js";
+import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { collectBuildProblems } from "./validateBuild.js";
+import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.js";
 import { Wire } from "../wire.js";
 // Read the task and the host's answers, verify each branch parses and carries a
 // safe-path artifact envelope, then upload both peer branches in one batch
@@ -28,7 +29,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
-    const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
     const items = [];
     const blocked = unreadable.map((entry) => ({
         suite_kind: entry.suite_kind,
@@ -39,26 +39,19 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
+    // Since spec 42 that check is exactly one question, and it is about a branch
+    // the answer has *no* entry for: everything else it used to ask is now asked
+    // of the server, by a dry run, before this command runs at all. So its
+    // problems can never land on a branch this loop visits, and they are reported
+    // below rather than inside it.
+    //
     // An earlier draft threw and stopped the command, which quietly undid spec
-    // 32-5 Phase 4: one missing marker in the behavioral answer would have left a
-    // finished structural suite unpublished. Every problem this check raises is
-    // already named against a branch, so it blocks that branch and never the
-    // batch. That also bounds what a false positive in a local check can cost —
-    // one branch, with the peer still going up and the server still the authority.
-    const problemsFor = new Map();
-    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
-        problemsFor.set(problem.branch, [...(problemsFor.get(problem.branch) ?? []), problem.message]);
-    }
+    // 32-5 Phase 4: one behavioral problem would have left a finished structural
+    // suite unpublished. Every problem here is named against a branch, so it
+    // blocks that branch and never the batch.
     for (const output of outputs) {
-        const failed = problemsFor.get(output.suite_kind);
-        problemsFor.delete(output.suite_kind);
-        if (failed) {
-            blocked.push({ suite_kind: output.suite_kind, status: BLOCKED_STATUS, error: formatBranchProblems(failed) });
-            continue;
-        }
-        const sourceDigest = digestFor.get(output.suite_kind) ?? '';
         if (output.build_error) {
-            items.push({ suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error });
+            items.push(uploadItem(request, output, undefined));
             continue;
         }
         let testMetadata = output.test_metadata;
@@ -71,23 +64,14 @@ export async function putSuiteBuild(config, _args = [], deps) {
                 continue;
             }
         }
-        items.push({
-            suite_kind: output.suite_kind,
-            source_digest: sourceDigest,
-            artifacts: {
-                suite_file: output.suite_file,
-                runner_manifest: output.runner_manifest,
-                test_metadata: testMetadata,
-            },
-        });
+        items.push(uploadItem(request, output, testMetadata));
     }
-    // What is left in `problemsFor` belongs to a branch the loop above never
-    // reached, because the answer has no entry for it at all. It has nothing to
-    // upload and nothing to roll back, so it costs its peer nothing — but it is
+    // A branch the request asked for and the answer never mentions. It has nothing
+    // to upload and nothing to roll back, so it costs its peer nothing — but it is
     // exactly the branch that used to leave no trace anywhere, and the one line it
     // prints here is the whole point of noticing it (spec 32-6, a2time 2026-08-04).
-    for (const [suiteKind, messages] of problemsFor) {
-        blocked.push({ suite_kind: suiteKind, status: BLOCKED_STATUS, error: formatBranchProblems(messages) });
+    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
+        blocked.push({ suite_kind: problem.branch, status: BLOCKED_STATUS, error: problem.message });
     }
     // Every branch is blocked, so there is nothing to upload. Asking the server to
     // publish an empty batch would turn a local, already-explained problem into a
@@ -103,46 +87,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
 // malformed. Not a server status — it never reaches the server — but it travels
 // as one so a single rule decides what counts as published (see `PUBLISHED`).
 const BLOCKED_STATUS = 'not_ready';
-// The behavioral branch's uploaded metadata, with the independent review and the
-// connector's own run evidence folded in.
-//
-// Throws for anything that leaves this branch unpublishable — a missing review,
-// one bound to a different candidate, a defect the review called not_supplied.
-// The caller turns that into one unpublished branch rather than a failed
-// command: a blocked review is a fact about the behavioral suite, and the
-// structural peer next to it is finished and correct. Sinking the whole upload
-// with it forced the one workaround this contract exists to prevent — hand-editing
-// the answer down to a single branch, which loses the peer candidate for real.
-function withReview(config, request, output) {
-    const review = readBehavioralReview(config.projectRoot, output);
-    const probe = review.known_defect_probe;
-    const qualityReview = review.bdd_quality_review;
-    if (!qualityReview || typeof qualityReview !== 'object') {
-        throw new Error('The separate behavioral review must contain a bdd_quality_review object.');
-    }
-    if (request.known_defect_context.status === 'supplied' && probe?.status === 'not_supplied') {
-        throw new Error('A known defect was supplied to suite-prepare, but the behavioral review marked it not_supplied.');
-    }
-    return {
-        ...output.test_metadata,
-        bdd_quality_review: {
-            ...qualityReview,
-            candidate_digest: review.candidate_digest,
-        },
-        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
-        known_defect_probe: review.known_defect_probe,
-        known_defect_context: request.known_defect_context,
-        candidate_run: review.candidate_run,
-        ...(review.fixed_candidate_run ? { fixed_candidate_run: review.fixed_candidate_run } : {}),
-    };
-}
-// The three outcomes that leave a branch published and current: a new version, an
-// identical version already stored, or a reactivated one. Each returns the
-// identity to run. Everything else — a rejected branch, a branch the host could
-// not build, or a status this connector has never seen — fails closed and is
-// never run, so a newer server can never trick an older connector into running
-// something it does not understand.
-const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
 export function classifyPublication(results) {
     const split = { digests: [], unpublished: [] };
     for (const result of results) {
@@ -176,7 +120,20 @@ function printResult(result) {
             .join(', ')
         : '';
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
-    return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
+    return (`${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.` + printDowngrades(result));
+}
+// Spec 42, §7. A capability every one of whose Scenarios the review objected to
+// is stored `unguarded` by the publish. The run is standing right here when that
+// is decided, so it is told here, in the server's own words — finding it on the
+// map afterwards is how a run finishes believing it published a guarantee it did
+// not.
+function printDowngrades(result) {
+    const downgraded = result.unguarded_by_review ?? [];
+    if (downgraded.length === 0)
+        return '';
+    return (`\n  ${downgraded.length} capability(ies) published unguarded, because the review objected to every ` +
+        'Scenario guarding them:\n' +
+        downgraded.map((entry) => `    - ${entry.capability_id}: ${entry.reason}`).join('\n'));
 }
 // The server's own words when it sent any; otherwise the best true thing that can
 // be said. A status this connector does not know is quoted rather than guessed

package/dist/verbs/run.js

@@ -27,9 +27,12 @@ function resolve(config, deps) {
     return {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        // The whole envelope, support files and all: a branch is a set of files
+        // since spec 42, §6, and picking `path` and `content` out of it here was
+        // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
-            suite_file: { path: item.suite_file.path, content: item.suite_file.content },
+            suite_file: item.suite_file,
             runner_manifest: item.runner_manifest,
         }),
         materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
@@ -98,7 +101,7 @@ async function buildRunPayload(config, d, item) {
         }
         else {
             d.materializeStructural(config.projectRoot, item);
-            result = await d.runStructural(config.projectRoot, runner, item.suite_file.path);
+            result = await d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
         }
     }
     catch (err) {
@@ -121,18 +124,24 @@ async function buildRunPayload(config, d, item) {
 // Exported for `run-local`, which runs these same strategies against the files
 // the host just wrote rather than against a published suite. One dispatch table,
 // so the command the loop iterates on is the command that runs after publishing.
-export function runStructuralByRunner(projectRoot, runner, suitePath) {
+export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     switch (runner) {
         case 'rspec':
-            return runRspecSuite(projectRoot, suitePath);
+            return runRspecSuite(projectRoot, suitePaths);
         case 'vitest':
-            return runVitestSuite(projectRoot, suitePath);
+            return runVitestSuite(projectRoot, suitePaths);
         case 'pytest':
-            return runPytestSuite(projectRoot, suitePath);
+            return runPytestSuite(projectRoot, suitePaths);
         default:
             return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite.`));
     }
 }
+// Every file of the branch, in the order the envelope carries them. A structural
+// branch is one file per assignment since spec 42, §6, and running only the main
+// one would execute a fraction of what the map says is guarded.
+function artifactPaths(file) {
+    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+}
 function suiteError(suiteDigest, message) {
     return {
         suite_digest: suiteDigest,