unitbob 0.4.4 → 0.5.0

package/dist/cli.js

@@ -133,8 +133,10 @@ export async function main(argv, deps = { ensureLinked }) {
                 await contractPrompt(await linked(), args);
                 return 0;
             case 'run-local':
-                await runLocal(await linked(), args);
-                return 0;
+                // The one verb whose non-zero exit is not an error: a branch that failed
+                // the same set of cases twice in a row (spec 34-6, criterion 3). Red
+                // tests still exit zero — a live defect is the suite working.
+                return await runLocal(await linked(), args);
             case 'run':
             case 'check':
                 await run(await linked(), args);

package/dist/files/guardrails.js

@@ -62,21 +62,31 @@ else
 end
 abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
 `;
-// Write the suite blob's guardrail file at its own (validated) relative path.
-// The Ruby boot kit is materialized only for the rspec runner — Vitest and
-// pytest runs need no connector-written support files here (the runtime
-// pytest.ini lives outside this directory and is written by the pytest runner).
+// Write every file of the suite blob at its own (validated) relative path. The
+// Ruby boot kit is materialized only for the rspec runner — Vitest and pytest
+// runs need no connector-written support files here (the runtime pytest.ini
+// lives outside this directory and is written by the pytest runner).
+//
+// Every file, not just the main one (spec 42, §6.4). The directory is wiped
+// first and only the main file was written back, so a published suite of four
+// files came back as one and the run that followed it silently protected a
+// quarter of what the map claimed.
 export function materializeGuardrails(projectRoot, suite) {
-    assertGuardrailPath(suite.suite_file.path);
+    const files = [suite.suite_file, ...(suite.suite_file.support_files ?? [])];
+    for (const file of files)
+        assertGuardrailPath(file.path);
     const dir = join(projectRoot, GUARDRAILS_DIR);
     rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir, { recursive: true });
-    const suitePath = join(projectRoot, suite.suite_file.path);
-    mkdirSync(dirname(suitePath), { recursive: true });
-    writeFileSync(suitePath, suite.suite_file.content);
+    const written = files.map((file) => {
+        const path = join(projectRoot, file.path);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, file.content);
+        return path;
+    });
     if (suite.runner_manifest.runner === 'rspec')
         materializeHelper(projectRoot);
-    return { suitePath };
+    return { suitePath: written[0], supportPaths: written.slice(1) };
 }
 // Both Ruby flows boot the same way: the check flow writes the boot kit next to
 // the suite here, the suite-build flow writes it right after the precheck.

package/dist/files/suiteBuild.js

@@ -2,7 +2,6 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { createHash } from 'node:crypto';
 import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
-import { readBudget, RUN_BUDGET } from "./budget.js";
 import { readWorkerPlan, validateWorkerPlanFiles, workerPlanDigest, workerPlanPath } from "./workerPlan.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
@@ -83,12 +82,27 @@ export function branchRunner(output) {
     }
     return runner;
 }
+// What the reviewer actually read: the suite files, and the manifest that runs
+// them. Nothing else (spec 42, §4).
+//
+// `test_metadata` used to be in here, and the server's copy of this formula
+// stripped the review's own keys back out to match — two lists that had to stay
+// identical for ever or every upload would break. The real cost was elsewhere,
+// though: editing metadata declared the review stale. On noahsat-web,
+// 2026-08-12 the reviewer was right that the steps drive only `PATCH`, the fix
+// moved three `PUT` aliases into a deferred list, not one byte of the suite
+// moved — and the run still paid for re-binding the candidate and a second
+// reviewer pass, the most expensive step of the whole recipe, to satisfy the
+// reviewer's own finding.
+//
+// `stableJson` sorts object keys and does nothing else. The server's
+// `canonical_json` does the same, which is the only reason the two sides agree;
+// a normalization added on one side alone would break every upload.
 export function suiteCandidateDigest(output) {
     return createHash('sha256')
         .update(stableJson({
         suite_file: output.suite_file,
         runner_manifest: output.runner_manifest,
-        test_metadata: output.test_metadata,
     }))
         .digest('hex');
 }
@@ -232,7 +246,6 @@ export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext
         output_path: outputPath(projectRoot),
         branches,
         known_defect_context: knownDefectContext,
-        budget: RUN_BUDGET,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -251,10 +264,13 @@ export function readSuiteBuildRequest(projectRoot) {
         !Array.isArray(request.branches)) {
         throw new Error(`${path} is malformed: expected project_root, output_path, and a branches array.`);
     }
+    // Spec 34-6, criterion 2.3. A request written by an older connector still
+    // carries a `budget` block; it is spread through untouched and read by nobody,
+    // which is the whole of the compatibility story — there is no ceiling left for
+    // it to name.
     return {
         ...request,
         known_defect_context: readKnownDefectContext(request.known_defect_context, path),
-        budget: readBudget(request.budget),
     };
 }
 function readKnownDefectContext(value, path) {

package/dist/files/suiteBuildUpload.js

@@ -0,0 +1,71 @@
+import { readBehavioralReview } from "./suiteBuild.js";
+// What travels to the server, and what "published" means when it answers. One
+// module, because two commands ask those questions: `put-suite-build` sends the
+// batch, and `validate-build` sends the same batch as a dry run so the server's
+// verdict is about the exact bytes the publish will carry (spec 42, §3).
+//
+// A second assembly would be a second answer to "what are we uploading", and the
+// dry run would then be checking something the publish does not send — which is
+// worth less than not checking at all, because it reads as a verdict.
+// 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.
+export const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
+// The answer a dry run gives to a branch it would accept. A server that does not
+// know `dry_run` answers one of `PUBLISHED` instead — which means it published —
+// and `validate-build` says so rather than reporting a check that passed.
+export const WOULD_PUBLISH = 'would_publish';
+// One branch, as the upload sends it. `source_digest` comes from the request,
+// never from the host's answer, so the host cannot claim a different map than
+// the branch was given.
+export function uploadItem(request, output, testMetadata) {
+    const sourceDigest = request.branches.find((branch) => branch.suite_kind === output.suite_kind)?.source_digest ?? '';
+    if (output.build_error) {
+        return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+    }
+    return {
+        suite_kind: output.suite_kind,
+        source_digest: sourceDigest,
+        artifacts: {
+            suite_file: output.suite_file,
+            runner_manifest: output.runner_manifest,
+            test_metadata: testMetadata,
+        },
+    };
+}
+// 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.
+export 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 } : {}),
+    };
+}

package/dist/files/workerPlan.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 export function workerPlanPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
@@ -33,8 +34,13 @@ export function readWorkerPlan(projectRoot) {
     }
     return parsed;
 }
+const RUBY_HARNESS = {
+    behavioral: '.unitbob/behavioral/step_definitions/00_unitbob_world.rb',
+    structural: '.unitbob/structural/unitbob_helper.rb',
+};
 export function validateWorkerPlanFiles(projectRoot) {
     const errors = [];
+    const rubyProject = detectStructuralRunner(projectRoot) === 'rspec';
     const plan = readWorkerPlan(projectRoot);
     let request;
     try {
@@ -54,8 +60,6 @@ export function validateWorkerPlanFiles(projectRoot) {
         branch.suite_kind,
         assignmentIds(branch.assignment),
     ]));
-    const budget = request.budget;
-    const workerCeiling = typeof budget?.workers === 'number' ? budget.workers : Number.POSITIVE_INFINITY;
     const seenWorkers = new Set();
     const seenPaths = new Map();
     for (const [index, item] of plan.workers.entries()) {
@@ -88,18 +92,26 @@ export function validateWorkerPlanFiles(projectRoot) {
             errors.push(`${label}: done_when must be non-empty`);
         if (!isNonEmptyString(item?.harness_path))
             errors.push(`${label}: harness_path must be non-empty`);
-        const expectedHarness = item?.branch === 'behavioral'
-            ? '.unitbob/behavioral/step_definitions/00_unitbob_world.rb'
-            : item?.branch === 'structural' ? '.unitbob/structural/unitbob_helper.rb' : null;
+        // Both connector-owned harness files are Ruby, and only a Ruby project has
+        // them: `unitbob_helper.rb` boots Rails for RSpec, and the behavioral World
+        // is materialized for cucumber alone. Demanding them everywhere refused
+        // every Python and JS plan over a file that does not exist and would mean
+        // nothing if it did — the same mistake as the stack gate that reported a
+        // Python project as no stack at all. Found 2026-08-12.
+        //
+        // What is required of the other stacks is what the rule was ever about: the
+        // harness is connector territory, under `.unitbob/`, not a file in the
+        // project.
+        const expectedHarness = rubyProject ? RUBY_HARNESS[item?.branch] ?? null : null;
         if (expectedHarness && item.harness_path !== expectedHarness) {
             errors.push(`${label}: harness_path must name the connector-owned ${expectedHarness}`);
         }
+        if (!expectedHarness && isNonEmptyString(item?.harness_path) && !item.harness_path.startsWith('.unitbob/')) {
+            errors.push(`${label}: harness_path must be a connector-owned path under .unitbob/ (got "${item.harness_path}")`);
+        }
         if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
             errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
         }
-        if (!Number.isInteger(item?.limits?.fact_finder_lookups) || item.limits.fact_finder_lookups < 0 || item.limits.fact_finder_lookups > 8) {
-            errors.push(`${label}: limits.fact_finder_lookups must be an integer from 0 to 8`);
-        }
         for (const ownedPath of Array.isArray(item?.owned_paths) ? item.owned_paths : []) {
             if (!isNonEmptyString(ownedPath)) {
                 errors.push(`${label}: owned path must be a non-empty string`);
@@ -118,27 +130,29 @@ export function validateWorkerPlanFiles(projectRoot) {
                 seenPaths.set(ownedPath, label);
         }
     }
+    // Spec 34-6, criterion 1.6. What is left here catches a corrupted plan, never
+    // a small one. The gate used to also demand that every assigned capability
+    // appear — which made the plan's size a copy of the assignment's size, and the
+    // assignment is the whole product map. That is the load one worker could not
+    // finish on a2time, 2026-08-10. Scope is chosen by the coordinator with the
+    // user (workflow step 3), and the plan is the only record of it, so a plan
+    // that covers part of the assignment is now an ordinary plan.
+    //
+    // The neighbours stay for the opposite reason: naming a capability the request
+    // never assigned, or naming one twice, are ways a plan is wrong rather than
+    // ways it is narrow. So is an empty plan for a branch that was given work.
     for (const [branch, expected] of expectedByBranch) {
         const items = plan.workers.filter((item) => item && typeof item === 'object' && !Array.isArray(item) && item.branch === branch);
         if (expected.length > 0 && items.length === 0)
             errors.push(`${branch}: no worker slice was planned`);
-        if (items.length > Math.min(workerCeiling, expected.length)) {
-            errors.push(`${branch}: worker count ${items.length} exceeds min(budget.workers, capability count)`);
-        }
         const assigned = items.flatMap((item) => Array.isArray(item.capability_ids) ? item.capability_ids : []);
         for (const id of expected) {
-            const count = assigned.filter((candidate) => candidate === id).length;
-            if (count === 0)
-                errors.push(`${branch}: assigned capability ${id} is missing from the plan`);
-            if (count > 1)
+            if (assigned.filter((candidate) => candidate === id).length > 1) {
                 errors.push(`${branch}: assigned capability ${id} appears more than once`);
+            }
         }
         for (const id of assigned.filter((id) => !expected.includes(id)))
             errors.push(`${branch}: capability ${id} was not assigned by the request`);
-        const sizes = items.map((item) => Array.isArray(item.planned_cases) ? item.planned_cases.length : 0).filter((size) => size > 0);
-        if (sizes.length > 1 && Math.max(...sizes) / Math.min(...sizes) > 1.5) {
-            errors.push(`${branch}: planned case slice ratio exceeds 1.5`);
-        }
     }
     return errors;
 }

package/dist/proc.js

@@ -115,6 +115,21 @@ export const GRAPH_NOISE_PATTERNS = [
     // Type declarations — a contract for a compiler, with no runtime behaviour.
     '*.d.ts',
     '*.pyi',
+    // Spec 34-6, criterion 6. Unitbob's own session reports, left in the repo root
+    // by the operator, are read as source: on a2time, 2026-08-10, two of them
+    // contributed 44 and 25 nodes and pushed their community to third-largest in
+    // the whole project. The more often you run unitbob, the dirtier its map gets —
+    // a feedback loop with no floor.
+    '/unitbob*.md',
+    // Test scaffolding and boot wiring. Factories and model specs describe the
+    // fixtures a suite builds, not a business promise a guardrail could protect;
+    // `config/initializers/` and `config/deploy/` run once at boot and at deploy.
+    // The project's own request and feature specs stay — they are evidence of what
+    // the app promises.
+    'spec/factories/',
+    'spec/models/',
+    'config/deploy/',
+    'config/initializers/',
 ];
 export function ensureUnitbobIgnored(projectRoot) {
     // `.graphifyignore` is unitbob's own bookkeeping, like the other two entries —

package/dist/runner/bootcheck.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable, runProcess } from "../proc.js";
+import { locateRunner } from "./toolchain.js";
 import { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
 import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
@@ -86,9 +87,14 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // and the global `bundle` was standing right there the whole time.
     const localBundle = join(projectRoot, 'bin', 'bundle');
     const command = executable(localBundle) ? localBundle : 'bundle';
+    // When Unitbob installed rspec-rails for itself, the gems this helper needs
+    // are resolved by the sidecar Gemfile, not the project's. Asking bundler
+    // without that variable would load a different set of gems than the run does,
+    // which is exactly the way a check ends up predicting the wrong thing.
+    const located = locateRunner(projectRoot, 'rspec');
     return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(helper)}`], {
         cwd: projectRoot,
-        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     }), 
     // A clean load says nothing on stdout and exits 0. Anything else is the
     // suite failing to start.
@@ -110,10 +116,25 @@ async function pytestBootCheck(projectRoot, deps) {
     // first: this check must not fail because a different step was skipped.
     mkdirSync(join(projectRoot, dirname(PYTEST_INI_FILE)), { recursive: true });
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
-    for (const python of ['python3', 'python']) {
-        const result = await attempt(deps, python, ['-m', 'pytest', '-c', PYTEST_INI_FILE, '--collect-only', '-q'], {
-            cwd: projectRoot,
-        });
+    // The same pytest the run will use, resolved once in `locateRunner` — the
+    // sidecar under `.unitbob/` when Unitbob installed one, else the machine's own
+    // interpreter. Asking a different interpreter than the run uses is how a check
+    // ends up answering about something nobody is going to execute.
+    //
+    // When it resolves nothing we still try the two interpreters by name rather
+    // than reporting `no_runner` from a lookup. The lookup is a prediction; the
+    // spawn is the fact, and a check that stops at its own prediction can be
+    // wrong in the one direction that costs the most — refusing a project that
+    // would have answered perfectly well.
+    const located = locateRunner(projectRoot, 'pytest');
+    const candidates = located
+        ? [located]
+        : [
+            { command: 'python3', args: ['-m', 'pytest'], env: undefined },
+            { command: 'python', args: ['-m', 'pytest'], env: undefined },
+        ];
+    for (const candidate of candidates) {
+        const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--collect-only', '-q'], { cwd: projectRoot, env: candidate.env });
         if (result === null)
             continue; // this interpreter is not on the machine
         return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
@@ -148,7 +169,10 @@ function pytestVerdict(code) {
 // turn away the majority. A file that is genuinely unparseable is caught here
 // anyway, since `vitest list` has to parse it.
 async function vitestBootCheck(projectRoot, deps) {
-    const local = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    // A sidecar vitest counts as installed: it is ours, it is on disk, and it is
+    // the one the run will spawn. What stays out is `npx`, for the reason below.
+    const local = locateRunner(projectRoot, 'vitest')?.command
+        ?? join(projectRoot, 'node_modules', '.bin', 'vitest');
     // Only a vitest already installed in the project is used. Reaching for `npx`
     // would install a package to answer a question, and installing into the
     // user's project is not this check's business.
@@ -275,15 +299,17 @@ function hasProjectFrame(output, projectRoot, runner) {
     // asked of that file. Judging the whole output at once let `.venv/lib/...`
     // answer yes on the strength of its `lib/`, which is how a `TypeError` deep
     // inside a dependency came back as a defect in the user's code.
-    const ownDirs = runner === 'vitest' ? ['src'] : ['app', 'lib'];
-    const conventional = new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`);
+    const ownDirs = CONVENTIONAL_SOURCE_DIRS[runner] ?? [];
+    const conventional = ownDirs.length
+        ? new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`)
+        : null;
     for (const line of output.split('\n')) {
         // Wherever a dependency is installed, it is not this project's code — and
         // that has to be decided before anything below gets a chance to say yes.
         if (INSTALLED_DEPENDENCY.test(line))
             continue;
         // The conventional homes of business code, relative or absolute.
-        if (conventional.test(line))
+        if (conventional?.test(line))
             return true;
         if (line.includes(projectRoot))
             return true;
@@ -303,6 +329,18 @@ function hasProjectFrame(output, projectRoot, runner) {
     }
     return false;
 }
+// Where each stack conventionally keeps its business code. Only a stack that
+// really has such a convention gets an entry: `app/` and `lib/` are Rails, and
+// they used to be the fallback for everything that was not vitest, which meant a
+// Python project got Rails's layout applied to its stack traces. Python names no
+// fixed layout at all, so it is deliberately absent — the repository-file test
+// below is the answer there, and it is the more reliable one anyway.
+const CONVENTIONAL_SOURCE_DIRS = {
+    rspec: ['app', 'lib'],
+    cucumber: ['app', 'lib'],
+    vitest: ['src'],
+    'cucumber-js': ['src'],
+};
 // Where a dependency lives once installed — never the project's own code, in
 // any of the three languages. The last two are the languages' own installed
 // libraries: `…/lib/ruby/3.3.0/psych.rb` is a frame the `lib/` rule below would

package/dist/runner/failureDigest.js

@@ -0,0 +1,238 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const RUN_STATE_FILE = 'run-state.json';
+// A marker embedded in a reported test name or Gherkin tag. Same shape the
+// server joins on (`CaseMarker::EMBEDDED`): a full 12-hex marker, never a prefix
+// of a longer hex run. A case with no marker still counts as a failure — it is
+// identified by its file and message alone.
+const MARKER = /ubc_[0-9a-f]{12}(?![0-9a-f])/;
+// The failures a report describes, canonically ordered, or `null` when the
+// report cannot be read as one. `null` is not "green": a runner that died before
+// the first test produces no set at all, and comparing against nothing would
+// stop a branch over a harness problem the loop never even reached.
+export function failureSet(runner, report) {
+    if (!report.trim())
+        return null;
+    const found = extract(runner, report);
+    return found && canonical(found);
+}
+// One hash for one set. Same set, same hash, on any machine and in any order.
+export function digestOf(failures) {
+    return createHash('sha256').update(JSON.stringify(failures)).digest('hex');
+}
+export function runStatePath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', RUN_STATE_FILE);
+}
+// A damaged, hand-edited or absent file reads as "no previous run". Refusing to
+// run over a bookkeeping file would turn the one soft stop in the loop into the
+// hardest thing in it — and this file is written by a process that repair
+// deliberately kills and restarts.
+export function readRunState(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(runStatePath(projectRoot), 'utf8'));
+        const branches = parsed?.branches;
+        if (!branches || typeof branches !== 'object' || Array.isArray(branches))
+            return {};
+        return Object.fromEntries(Object.entries(branches).filter(([, value]) => typeof value === 'string'));
+    }
+    catch {
+        return {};
+    }
+}
+// `undefined` forgets this branch: a run that produced no comparable set leaves
+// the next one to be a first run again.
+export function rememberFailures(projectRoot, branch, digest) {
+    const branches = readRunState(projectRoot);
+    if (digest === undefined)
+        delete branches[branch];
+    else
+        branches[branch] = digest;
+    const path = runStatePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    // Written whole and moved into place. A plain write that is interrupted leaves
+    // truncated JSON, which reads back as "no previous run" — exactly at the
+    // moment a run is being killed and restarted, which is the loop this bounds.
+    const staging = `${path}.tmp`;
+    writeFileSync(staging, `${JSON.stringify({ branches }, null, 2)}\n`);
+    renameSync(staging, path);
+}
+export function clearRunState(projectRoot) {
+    rmSync(runStatePath(projectRoot), { force: true });
+}
+function canonical(failures) {
+    const byKey = new Map(failures.map((failure) => [keyOf(failure), failure]));
+    return [...byKey.keys()].sort().map((key) => byKey.get(key));
+}
+function keyOf(failure) {
+    return `${failure.marker}\u0000${failure.file}\u0000${failure.message}`;
+}
+// The connector interprets a report in exactly one other place — `boundReport`,
+// which bounds it for transport — and this switch deliberately mirrors that
+// one's shape rather than inventing a second dispatch. Neither of them judges a
+// run — the server owns every verdict a report leads to. This one only asks "is
+// this the same wall we hit last time", and its answer reaches nothing but an
+// exit code.
+function extract(runner, report) {
+    switch (runner) {
+        case 'rspec':
+            return fromRspec(report);
+        case 'vitest':
+            return fromVitest(report);
+        case 'pytest':
+            return fromJunitXml(report);
+        case 'cucumber':
+        case 'cucumber-js':
+            return fromCucumberMessages(report);
+        case 'pytest-bdd':
+            return fromPytestBdd(report);
+        default:
+            return null;
+    }
+}
+function fromRspec(report) {
+    const data = parseObject(report);
+    if (!Array.isArray(data?.examples))
+        return null;
+    return rows(data.examples).flatMap((example) => {
+        if (example.status === 'passed')
+            return [];
+        const name = `${text(example.description)} ${text(example.full_description)}`;
+        const exception = example.exception;
+        return [failure(name, text(example.file_path), text(exception?.message))];
+    });
+}
+function fromVitest(report) {
+    const data = parseObject(report);
+    if (!Array.isArray(data?.testResults))
+        return null;
+    return rows(data.testResults).flatMap((file) => {
+        const assertions = Array.isArray(file.assertionResults) ? rows(file.assertionResults) : [];
+        return assertions.flatMap((assertion) => {
+            if (assertion.status === 'passed')
+                return [];
+            const messages = Array.isArray(assertion.failureMessages) ? assertion.failureMessages : [];
+            const name = `${text(assertion.title)} ${text(assertion.fullName)}`;
+            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'))];
+        });
+    });
+}
+// pytest's JUnit XML, read the way `boundReport` already reads it: by pattern,
+// because a whole XML parser to answer one yes/no question is a dependency this
+// package does not need.
+//
+// `failure` and `error`, but not `skipped` — and this is the one place the set
+// deliberately does not match the server's "did not pass". A skip never moves:
+// it reports the same thing on every run forever, so counting it here would stop
+// a branch whose only permanent case is a skip, and it would do it while the
+// repair was still fixing everything else. A skip that should not be there is
+// caught at upload, where it costs a message rather than a branch.
+function fromJunitXml(report) {
+    if (!/<testsuites?\b/.test(report))
+        return null;
+    const cases = report.match(/<testcase\b[^>]*(?:\/>|>[\s\S]*?<\/testcase>)/g) ?? [];
+    return cases.flatMap((testcase) => {
+        const problem = testcase.match(/<(?:failure|error)\b[^>]*(?:\/>|>[\s\S]*?<\/(?:failure|error)>)/);
+        if (!problem)
+            return [];
+        const name = attribute(testcase, 'name');
+        const file = attribute(testcase, 'file') || attribute(testcase, 'classname');
+        return [failure(name, file, attribute(problem[0], 'message'))];
+    });
+}
+// Cucumber Messages (NDJSON), both the Ruby and the JS emitter. One scenario is
+// spread over several envelopes: the pickle holds its name, tags and file, the
+// testCase maps its steps, and testStepFinished carries each step's result.
+function fromCucumberMessages(report) {
+    const envelopes = [];
+    for (const line of report.split('\n')) {
+        if (!line.trim())
+            continue;
+        const parsed = parseObject(line);
+        if (!parsed)
+            return null;
+        envelopes.push(parsed);
+    }
+    if (envelopes.length === 0)
+        return null;
+    const pickles = indexBy(envelopes, 'pickle');
+    const testCases = indexBy(envelopes, 'testCase');
+    const results = new Map();
+    for (const envelope of envelopes) {
+        const finished = envelope.testStepFinished;
+        if (!finished)
+            continue;
+        const startedId = text(finished.testCaseStartedId);
+        const list = results.get(startedId) ?? [];
+        list.push(finished.testStepResult ?? {});
+        results.set(startedId, list);
+    }
+    return envelopes.flatMap((envelope) => {
+        const started = envelope.testCaseStarted;
+        if (!started)
+            return [];
+        const testCase = testCases.get(text(started.testCaseId)) ?? {};
+        const pickle = pickles.get(text(testCase.pickleId)) ?? {};
+        const steps = results.get(text(started.id)) ?? [];
+        const failed = steps.filter((step) => text(step.status) !== 'PASSED' && text(step.status) !== 'SKIPPED');
+        if (failed.length === 0)
+            return [];
+        const tags = Array.isArray(pickle.tags) ? pickle.tags : [];
+        const tagText = rows(tags).map((tag) => text(tag.name)).join(' ');
+        const message = failed.map((step) => text(step.message)).find((line) => line.trim()) ?? '';
+        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message)];
+    });
+}
+// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). It names
+// no file — the whole behavioral bundle is one run — so the scenario's marker
+// and message carry the identity alone.
+function fromPytestBdd(report) {
+    const data = parseObject(report);
+    if (!Array.isArray(data?.scenarios))
+        return null;
+    return rows(data.scenarios).flatMap((scenario) => {
+        if (text(scenario.status) === 'passed')
+            return [];
+        const tags = Array.isArray(scenario.tags) ? scenario.tags.map((tag) => text(tag)).join(' ') : '';
+        return [failure(`${tags} ${text(scenario.name)}`, '', text(scenario.failure))];
+    });
+}
+// Only the first line of a message. Later lines are backtraces and diffs, which
+// carry object ids and absolute paths that differ between two runs of the same
+// unchanged failure — the very drift that would make this comparison useless.
+function failure(name, file, message) {
+    return {
+        marker: name.match(MARKER)?.[0] ?? '',
+        file,
+        message: message.split('\n')[0]?.trim() ?? '',
+    };
+}
+function indexBy(envelopes, key) {
+    const found = new Map();
+    for (const envelope of envelopes) {
+        const item = envelope[key];
+        if (item)
+            found.set(text(item.id), item);
+    }
+    return found;
+}
+function attribute(tag, name) {
+    return tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1] ?? '';
+}
+function rows(values) {
+    return values.filter((value) => value !== null && typeof value === 'object' && !Array.isArray(value));
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function parseObject(source) {
+    try {
+        const parsed = JSON.parse(source);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}