unitbob 0.7.7 → 0.7.12

package/dist/runner/failureDigest.js

@@ -24,6 +24,65 @@ export function reportedFailures(runner, report) {
         return null;
     return extract(runner, report);
 }
+// Spec 52-4, AC 1.10. The same parse, read for a third question: how many of
+// a feature's scenarios passed and how many did not. `put-tests` decides from
+// it which proof to attach — all red is the red run, all green with a review
+// is the review, anything else is no proof — and whether a review may be sent
+// at all. The number reaches a sentence on this machine and the choice of a
+// field; the server checks whatever proof it is sent against the report
+// itself. Only the two behavioral shapes have scenarios to count; a report
+// that cannot be read is no tally, never a green one.
+export function scenarioTally(runner, report) {
+    if (!report.trim())
+        return null;
+    const outcomes = scenarioOutcomes(runner, report);
+    if (outcomes === null)
+        return null;
+    const failed = outcomes.filter((passed) => !passed).length;
+    return { passed: outcomes.length - failed, failed };
+}
+// One entry per scenario, true when it passed. Cucumber emits one
+// `testCaseStarted` per attempt when a scenario is retried, so the rows are
+// keyed by the test case and the last attempt is the one that counts — the
+// one the run ended on.
+function scenarioOutcomes(runner, report) {
+    switch (runner) {
+        case 'cucumber':
+        case 'cucumber-js': {
+            const envelopes = [];
+            for (const line of report.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const parsed = parseObject(line);
+                if (!parsed)
+                    return null;
+                envelopes.push(parsed);
+            }
+            const failedRuns = new Set();
+            for (const envelope of envelopes) {
+                const finished = envelope.testStepFinished;
+                const status = text(finished?.testStepResult?.status);
+                if (finished && status !== 'PASSED' && status !== 'SKIPPED')
+                    failedRuns.add(text(finished.testCaseStartedId));
+            }
+            const lastAttempt = new Map();
+            for (const envelope of envelopes) {
+                const started = envelope.testCaseStarted;
+                if (started)
+                    lastAttempt.set(text(started.testCaseId), text(started.id));
+            }
+            return [...lastAttempt.values()].map((startedId) => !failedRuns.has(startedId));
+        }
+        case 'pytest-bdd': {
+            const data = parseObject(report);
+            if (!Array.isArray(data?.scenarios))
+                return null;
+            return rows(data.scenarios).map((scenario) => text(scenario.status) === 'passed');
+        }
+        default:
+            return null;
+    }
+}
 // 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');

package/dist/runner/gitRevision.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+// The revision a connector-made run was taken at, for the server's record:
+// `git rev-parse HEAD`, with `-dirty` when the tree has changes, or a word
+// when there is no git to ask. Read by the known-defect probe (the review)
+// and by the proof of red of a feature's checks (spec 52-3), from one place.
+export function gitRevision(projectRoot) {
+    try {
+        const options = {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        const head = execFileSync('git', ['rev-parse', 'HEAD'], options).trim();
+        const dirty = execFileSync('git', ['status', '--porcelain'], options).trim();
+        return dirty ? `${head}-dirty` : head;
+    }
+    catch {
+        return 'working-tree';
+    }
+}

package/dist/runner/manifest.js

@@ -24,7 +24,9 @@ export function withInstalledRunnerVersion(envelope, runner, projectRoot) {
 const BEHAVIORAL_DIR = '.unitbob/behavioral';
 // Matches the server's own PINNED_VERSION: a digit, then version characters.
 const PINNED_VERSION = /^[0-9][0-9A-Za-z.\-+]*$/;
-function installedRunnerVersion(runner, projectRoot) {
+// Exported for a feature's checks (spec 52-3), which take the runner from the
+// main suite rather than from a selection and still owe the server its version.
+export function installedRunnerVersion(runner, projectRoot) {
     const root = join(projectRoot, BEHAVIORAL_DIR);
     const found = readInstalledVersion(runner, root);
     return found && PINNED_VERSION.test(found) ? found : null;

package/dist/runner/outputTail.js

@@ -0,0 +1,13 @@
+// The end of what a run printed, stderr first: enough to see why a runner
+// died, not the whole log. One place for the three verbs that print it
+// (`check`, `run-local`, `put-tests`); `run-local` asks for more because the
+// person is reading it in a loop, `check` files it into a suite error.
+export function outputTail(result, limit) {
+    const bits = [];
+    if (result.stderr.trim())
+        bits.push(result.stderr.trim());
+    if (result.stdout.trim())
+        bits.push(result.stdout.trim());
+    const joined = bits.join('\n');
+    return joined.length > limit ? joined.slice(-limit) : joined;
+}

package/dist/runner/pytestBddPlugin.js

@@ -7,6 +7,13 @@
 //
 // It only records — it never reconciles markers or aggregates capabilities. It
 // is connector-owned and never part of the LLM-generated step definitions.
+//
+// A step with no definition is recorded too (spec 52-3, AC 3.7): pytest-bdd
+// calls `pytest_bdd_step_func_lookup_error` for it and never `after_step`, so
+// without this hook the scenario went into the report as `passed` with no
+// steps — and a feature's checks, which have to prove they are red, could
+// have passed that proof on wiring nobody wrote. The server's parser refuses
+// an `undefined` step as a broken suite, which is the honest answer.
 export const PYTEST_BDD_PLUGIN = `# Written by the unitbob connector — do not edit.
 import json
 import os
@@ -62,6 +69,14 @@ def pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func
     _record_step(scenario, step, "failed")
 
 
+def pytest_bdd_step_func_lookup_error(request, feature, scenario, step, exception):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is not None:
+        entry["status"] = "failed"
+        entry["failure"] = "{}: {}".format(type(exception).__name__, exception)
+    _record_step(scenario, step, "undefined")
+
+
 def pytest_bdd_after_scenario(request, feature, scenario):
     entry = _UNITBOB_CURRENT.pop(id(scenario), None)
     if entry is not None:

package/dist/verbs/contractPrompt.js

@@ -5,21 +5,40 @@ import { Wire } from "../wire.js";
 // The server composes the whole prompt; the connector prints its plain-language
 // `message` and the copy-ready `prompt`. A 422 (not current / not failing /
 // unknown intent) surfaces via WireError; nothing is fabricated.
+//
+// `feature:<id>` stands in for the digest (spec 52-4, AC 1.3): a feature's
+// checks are not on the map to copy one from, so the id is resolved to
+// the digest of the feature's current checks through the same index `check`
+// runs from. The server words the brief itself, and answers 422 to `accept` —
+// a feature's scenarios change through the talk, not through an accept.
 export async function contractPrompt(config, args = [], deps) {
-    const suiteDigest = (args[0] ?? '').trim();
+    const selector = (args[0] ?? '').trim();
     const testId = (args[1] ?? '').trim();
     const intent = (args[2] ?? 'fix').trim();
-    if (!suiteDigest || !testId) {
-        throw new Error('Usage: unitbob contract-prompt <suite_digest> <test_id> [fix|accept]');
+    if (!selector || !testId) {
+        throw new Error('Usage: unitbob contract-prompt <suite_digest>|feature:<id> <test_id> [fix|accept]');
     }
     if (intent !== 'fix' && intent !== 'accept') {
         throw new Error(`intent must be "fix" or "accept" (got "${intent}").`);
     }
+    const wire = new Wire(config);
     const d = {
-        getContractPrompt: (digest, id, action) => new Wire(config).getContractPrompt(digest, id, action),
+        getContractPrompt: (digest, id, action) => wire.getContractPrompt(digest, id, action),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         stdout: process.stdout,
         ...deps,
     };
+    const suiteDigest = selector.startsWith(FEATURE_SELECTOR) ? await featureDigest(d, selector.slice(FEATURE_SELECTOR.length)) : selector;
     const packet = await d.getContractPrompt(suiteDigest, testId, intent);
     d.stdout.write(`${packet.message}\n\n${packet.prompt}\n`);
 }
+const FEATURE_SELECTOR = 'feature:';
+// The digest of the feature's current checks. Only a feature being built has
+// them in the index: before the checks are written there is nothing to act on,
+// and after Finish they are part of the main suite, on the map like the rest.
+async function featureDigest(d, id) {
+    const item = (await d.getSuiteIndex()).feature_suites.find((entry) => String(entry.feature_id) === id);
+    if (!item)
+        throw new Error(`No feature ${id} has checks to act on — it is not being built, or it is finished.`);
+    return item.suite_digest;
+}

package/dist/verbs/featurePrepare.js

@@ -0,0 +1,49 @@
+import { requestPath, writeFeatureStartRequest } from "../files/featureStart.js";
+import { Wire } from "../wire.js";
+// Fetch the recipe and the behavioral assignment — the product capabilities of
+// the current map, with what each promises and where in the checkout it lives —
+// and write the host's task to `.unitbob/feature-start/request.json` (spec
+// 52-1). One request for the list, the same one `suite-prepare` makes; today's
+// check statuses are not asked for, because they belong on the feature's page
+// and not in the judgement of what the work may touch. No model is called,
+// no source is read, nothing is uploaded. A 409 (no current map) surfaces as a
+// WireError with the server's guidance and nothing is written.
+export async function featurePrepare(config, _args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const [recipe, packets] = await Promise.all([d.getRecipe('feature_intent'), d.getSuitePacketsBatch()]);
+    const behavioral = packets.find((packet) => packet.suite_kind === 'behavioral');
+    if (!behavioral) {
+        throw new Error('The Unitbob server sent no behavioral assignment with the suite packets — it is older than this connector. ' +
+            'Update the server (or the connector) so the two agree, then retry.');
+    }
+    writeFeatureStartRequest(config.projectRoot, recipe, capabilitiesOf(behavioral));
+    d.stdout.write(`Feature request written to ${requestPath(config.projectRoot)}\n`);
+}
+// The six fields the recipe names, in the shape it names them. The contract
+// identity (`contract_key`, `case_marker`) rides in the assignment for the
+// suite recipe and is not copied: the host is naming what may be touched, not
+// writing tests.
+function capabilitiesOf(packet) {
+    const assignment = (packet.assignment ?? {});
+    const list = Array.isArray(assignment.capabilities) ? assignment.capabilities : [];
+    return list.map((entry) => {
+        const item = (typeof entry === 'object' && entry !== null ? entry : {});
+        return {
+            capability_id: String(item.capability_id ?? ''),
+            title: String(item.title ?? ''),
+            description: String(item.description ?? ''),
+            surfaces: strings(item.surfaces),
+            tables: strings(item.tables),
+            externals: strings(item.externals),
+        };
+    });
+}
+function strings(value) {
+    return Array.isArray(value) ? value.map((one) => String(one)) : [];
+}

package/dist/verbs/knowledgePrepare.js

@@ -0,0 +1,39 @@
+import { knowledgeRequestPath, parseFeatureId, writeKnowledgeRequest } from "../files/features.js";
+import { Wire } from "../wire.js";
+// The statuses a feature can be talked through in: not yet talked through,
+// talked through and open to a second talk (spec 52-2, AC 2.1), or its checks
+// written — a talk then withdraws them, out loud (spec 52-3, AC 2.9).
+const TALKABLE = new Set(['intent', 'knowledge', 'red']);
+// Two forms (spec 52-2, AC 2.1). Without an id, the list: one line per feature
+// the talk can start on, so the host finds the one the person means by its
+// words — and the server's own sentence when there is none; the connector
+// words no state of its own. With an id, the host's task: the recipe and the
+// packet the server built, written to `.unitbob/features/<id>/request.json`
+// next to where `knowledge.md` will go. No model is called, nothing is
+// uploaded.
+export async function knowledgePrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        listFeatures: () => wire.listFeatures(),
+        getRecipe: (name) => wire.getRecipe(name),
+        getKnowledgePacket: (id) => wire.getKnowledgePacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    if (args.length === 0) {
+        const list = await d.listFeatures();
+        const talkable = list.features.filter((feature) => TALKABLE.has(feature.status));
+        if (talkable.length === 0) {
+            d.stdout.write(`${list.empty_text}\n`);
+            return;
+        }
+        for (const feature of talkable) {
+            d.stdout.write(`${feature.feature_id}  ${feature.title} (${feature.status})\n`);
+        }
+        return;
+    }
+    const featureId = parseFeatureId(args[0], 'knowledge-prepare');
+    const [recipe, packet] = await Promise.all([d.getRecipe('feature_grill'), d.getKnowledgePacket(featureId)]);
+    writeKnowledgeRequest(config.projectRoot, featureId, recipe, packet);
+    d.stdout.write(`Knowledge request written to ${knowledgeRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/mapPrepare.js

@@ -1,7 +1,7 @@
 import { ensureUnitbobIgnored, ignoreExclusions, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
 import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
-import { Wire } from "../wire.js";
+import { Wire, WireError } from "../wire.js";
 export async function mapPrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
@@ -10,7 +10,9 @@ export async function mapPrepare(config, _args = [], deps) {
         runGraphifyExtractKeyless,
         extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
+        listFeatures: () => wire.listFeatures(),
         stdout: process.stdout,
+        stderr: process.stderr,
         ...deps,
     };
     actual.ensureUnitbobIgnored(config.projectRoot);
@@ -44,18 +46,19 @@ export async function mapPrepare(config, _args = [], deps) {
     // us there reads as a hang.
     actual.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
     const inventory = await actual.extractRouteInventory(config.projectRoot);
-    const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
+    const [decompose, relate, extractSurfaces, decomposeSurfaces, existing] = await Promise.all([
         actual.getRecipe('decompose'),
         actual.getRecipe('relate'),
         actual.getRecipe('extract_surfaces'),
         actual.getRecipe('decompose_surfaces'),
+        existingCapabilities(actual),
     ]);
     const packet = writeMapBuildRequest(config.projectRoot, {
         decompose,
         relate,
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
-    }, inventory.status === 'written' ? inventory.path : undefined);
+    }, inventory.status === 'written' ? inventory.path : undefined, existing);
     actual.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
     actual.stdout.write(`${describeRouteInventory(inventory)}\n`);
     actual.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
@@ -63,3 +66,26 @@ export async function mapPrepare(config, _args = [], deps) {
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
         'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');
 }
+// The capabilities finished features added to the map (spec 52-4, AC 5.1):
+// by id, title and the intent as said — no addresses, the recipe matches by
+// meaning. Only finished features: an open one is not on the map yet. A
+// server older than the fields sends rows without a capability id, and one
+// older than the route answers 404; both read as none, quietly, and the
+// recipe skips its paragraph (AC 7.3). Any other failure of the list is not
+// a reason to stop a map build either — but it is said, on stderr, because a
+// map built without the finished features' ids is one that may redraw them.
+async function existingCapabilities(d) {
+    let features;
+    try {
+        features = (await d.listFeatures()).features;
+    }
+    catch (err) {
+        if (!(err instanceof WireError && err.status === 404)) {
+            d.stderr.write(`Could not list finished features — the map is built without them: ${err.message}\n`);
+        }
+        return [];
+    }
+    return features
+        .filter((feature) => feature.status === 'done' && typeof feature.capability_id === 'string')
+        .map((feature) => ({ id: feature.capability_id, title: feature.title, description: feature.intent ?? '' }));
+}

package/dist/verbs/putFeature.js

@@ -0,0 +1,21 @@
+import { readFeatureAnswer } from "../files/featureStart.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Read the host's answer and record the feature (spec 52-1). The server checks
+// every id against the current map and words the sentence; this prints it and
+// the link to the feature's page through the exchanger, like every link a
+// person gets from the terminal (spec 33). A 422 — an id not on the map — is
+// let through as a WireError with both id lists in its text, so the host
+// corrects its file and runs this again. Nothing is created locally: the
+// feature's folder, its knowledge file and its tests belong to later specs.
+export async function putFeature(config, _args = [], deps) {
+    const d = {
+        postFeature: (payload) => new Wire(config).postFeature(payload),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const answer = readFeatureAnswer(config.projectRoot);
+    const recorded = await d.postFeature(answer);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}

package/dist/verbs/putKnowledge.js

@@ -0,0 +1,21 @@
+import { parseFeatureId, readKnowledge } from "../files/features.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Send `knowledge.md` as text (spec 52-2, AC 2.2) and print the server's
+// sentence and the link to the feature's page through the exchanger, like
+// every link a person gets from the terminal (spec 33). The shape is checked
+// on the server only (Non-Goals); a 422 comes back through the wire as a
+// WireError whose text already holds one line per problem, both sides, and
+// this lets it through so the host fixes the file and runs this again.
+export async function putKnowledge(config, args = [], deps) {
+    const d = {
+        putKnowledge: (id, knowledge) => new Wire(config).putKnowledge(id, knowledge),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'put-knowledge');
+    const text = readKnowledge(config.projectRoot, featureId);
+    const recorded = await d.putKnowledge(featureId, text);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}

package/dist/verbs/putTests.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { knowledgePath, parseFeatureId, readKnowledge, readTestsOutput, readTestsRequest, readTestsReviewOutput, testsReviewOutputPath, } from "../files/features.js";
+import { suiteCandidateDigest } from "../files/suiteBuild.js";
+import { enterUrl } from "../links.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
+import { scenarioTally } from "../runner/failureDigest.js";
+import { gitRevision } from "../runner/gitRevision.js";
+import { placeAdvice } from "../runner/placeAdvice.js";
+import { placeProblem } from "../runner/place.js";
+import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
+import { outputTail } from "../runner/outputTail.js";
+import { Wire } from "../wire.js";
+const OUTPUT_TAIL_CHARS = 2000;
+// The digest of `knowledge.md` on disk against the one the request was written
+// from — both named when they differ, so the reader sees which side moved.
+export function assertKnowledgeUnchanged(projectRoot, featureId, expected) {
+    const got = createHash('sha256').update(readKnowledge(projectRoot, featureId)).digest('hex');
+    if (got === expected)
+        return;
+    throw new Error(`${knowledgePath(projectRoot, featureId)}: knowledge.md on disk differs from what the server has — ` +
+        `run put-knowledge first, or restore the file, then run this again.\nexpected: ${expected}\n     got: ${got}`);
+}
+// `put-tests <feature_id>` (spec 52-3, AC 3.5). The answer is read with its
+// files from disk; the candidate digest is the one the review uses; then the
+// connector runs the feature's tag itself — a report the host already has may
+// be from earlier and over other files, and the proof has to be over these
+// bytes. A runner that could not start or produced no report sends nothing:
+// what it said is printed, and the exit code is non-zero. A 409 or 422 comes
+// back as a WireError already worded by the server, one line per side, and is
+// let through as it is.
+//
+// What the run proves decides what travels with it (spec 52-4, AC 1.10). All
+// red: the run itself as `red_run`, revision and all, the way the known-defect
+// probe sends its own. All green with the reviewer's file beside the answer:
+// that file as `bdd_quality_review`, bound to this candidate. Anything else:
+// no proof — the harness was saved mid-build. A review over a run that is not
+// all green is not sent at all; a review of an older candidate is ignored out
+// loud. And once the server has taken the version, the same run is filed
+// under its digest, so the feature's page shows "N of M checks pass" on it at
+// once rather than on the version before.
+export async function putTests(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        runBehavioral: runBddSuite,
+        gitRevision,
+        putFeatureSuite: (id, upload) => wire.putFeatureSuite(id, upload),
+        postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'put-tests');
+    const request = readTestsRequest(config.projectRoot, featureId);
+    const output = readTestsOutput(config.projectRoot, featureId);
+    // The same check `tests-prepare` made, made again here: the file may have
+    // been edited in between, and the checks are sealed to the text the server
+    // has, not to the text on disk (spec 52-3, edge cases).
+    assertKnowledgeUnchanged(config.projectRoot, featureId, request.knowledge_digest);
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
+    // The review file, before the run: one the connector cannot read is a
+    // stop, said in one line, and a run before it would be a run for nothing.
+    const candidateDigest = suiteCandidateDigest({
+        suite_kind: 'behavioral', suite_file: output.suite_file, runner_manifest: output.runner_manifest,
+    });
+    let review;
+    try {
+        review = readTestsReviewOutput(config.projectRoot, featureId);
+    }
+    catch (err) {
+        d.stdout.write(`${err.message}\n`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    if (review && review.candidate_digest !== candidateDigest) {
+        d.stdout.write(`${testsReviewOutputPath(config.projectRoot, featureId)} is for an older candidate — ignored.\n`);
+        review = null;
+    }
+    let result;
+    try {
+        result = await d.runBehavioral(config.projectRoot, request.runner, request.feature_path, { only: request.feature_tag });
+    }
+    catch (err) {
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    const report = boundReport(request.runner, result);
+    if (report === null) {
+        d.stdout.write(`The run produced no machine-readable report at ${result.resultPath} (exit code ${result.code}) — ` +
+            'it died before the first scenario rather than failing them.\n');
+        const tail = outputTail(result, OUTPUT_TAIL_CHARS);
+        if (tail)
+            d.stdout.write(`${tail}\n`);
+        d.stdout.write('Nothing was sent.\n');
+        return 1;
+    }
+    const tally = scenarioTally(request.runner, result.report);
+    const allRed = tally !== null && tally.passed === 0 && tally.failed > 0;
+    const allGreen = tally !== null && tally.failed === 0 && tally.passed > 0;
+    if (review && !allGreen) {
+        d.stdout.write(`Review the checks when they all pass — ${stillFailing(tally)}.\n`);
+        return 1;
+    }
+    const proof = review
+        ? { bdd_quality_review: { ...review.bdd_quality_review, candidate_digest: candidateDigest } }
+        : allRed
+            ? { red_run: { candidate_digest: candidateDigest, revision: d.gitRevision(config.projectRoot), run_result: report } }
+            : {};
+    const recorded = await d.putFeatureSuite(featureId, {
+        suite_file: output.suite_file,
+        runner_manifest: output.runner_manifest,
+        test_metadata: { ...output.test_metadata, ...proof },
+        knowledge_digest: request.knowledge_digest,
+    });
+    // Said before the run is filed: the upload is done whatever happens next,
+    // and a filing that fails leaves the run to the next `check`.
+    d.stdout.write(`${recorded.message}\n`);
+    const { results } = await d.postRunsBatch([{ suite_digest: recorded.suite_digest, run_result: report }]);
+    for (const item of results)
+        d.stdout.write(`${item.summary}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+    return 0;
+}
+// "2 of 5 still fail" — or, for a report the connector could not count, only
+// that it could not.
+function stillFailing(tally) {
+    if (tally === null)
+        return 'the run’s report could not be read scenario by scenario';
+    return `${tally.failed} of ${tally.passed + tally.failed} still fail`;
+}