@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/src/lib/validators/verify-runner.js

@@ -13,7 +13,8 @@
  *
  * Pure orchestration — reuses (never reimplements):
  *   - runBuildCheck()  from framework/hooks/shared/build-check.js
- *   - runTestSuite()   from src/lib/tasks/test-runner.js
+ *   - runTestSuite()      from src/lib/tasks/test-runner.js (one node)
+ *   - resolveTestNodes()  from src/lib/tasks/test-nodes.js (the LIST of suites)
  *   - runValidation()  from ./validation-runner.js
  *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
  *   - loadRubric() + aggregateScores() from ./score-aggregator.js
@@ -28,7 +29,16 @@ import { join, resolve } from 'path';
 import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
 import { runE2eCheck } from '../../../framework/hooks/shared/e2e-check.js';
 import { buildComposeEnv } from '../e2e/compose-env.js';
-import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
+import { runTestSuite, parseTestCount, compareTestCount, resolveTestTimeout } from '../tasks/test-runner.js';
+import {
+  resolveTestNodes, parseTestFilter, nodeMatchesFilter, recordTestBaselines, morphConfigPath,
+} from '../tasks/test-nodes.js';
+import { runLinuxSuite, checkLinuxPreconditions } from '../tasks/linux-runner.js';
+import {
+  EVAL_RUNNER, evalPreflight, evalNodeEnv, readEvalSummary, evalScenarioCount,
+  evalFailureLines,
+  evalEmptyRunProblem, evalColdCacheWarning,
+} from '../tasks/eval-node.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
 import { checkOutputsTraceability } from './traceability-check.js';
@@ -40,6 +50,23 @@ const DEFAULT_BUILD_TIMEOUT = 120_000;
 /** Number of trailing output lines kept for feedback/reporting. */
 const OUTPUT_TAIL_LINES = 20;
 
+/**
+ * The caller asked for something impossible — not a red verification, a wrong
+ * invocation. The distinction is the exit code: `verify` answers 1 for "the
+ * code is not ready" and 2 for "this command cannot mean what you typed".
+ *
+ * It exists because `--filter` can select nothing. Running every suite (or,
+ * far worse, none of them) and reporting green would be F30 restated as a
+ * one-word typo — so the runner refuses instead of guessing.
+ */
+export class VerifyUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'VerifyUsageError';
+    this.code = 'verify-usage';
+  }
+}
+
 /**
  * Run the deterministic verify cadence for a feature (or a single task within it).
  *
@@ -54,6 +81,11 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {boolean} [options.skipBuild] - Skip the build node
  * @param {boolean} [options.skipE2e] - Skip the e2e node
  * @param {boolean} [options.freshE2e] - Force a stack rebuild instead of reusing a warm one
+ * @param {boolean} [options.recordBaseline] - Measure and write `expectedCount` back into
+ *   `project.tests[]` — only from a run whose every test node is green (D8)
+ * @param {boolean} [options.linux] - Run the test nodes inside a Linux container, on a COPY
+ *   of the tree (see linux-runner.js for why a bind mount would prove nothing)
+ * @param {string} [options.linuxImage] - Image override for --linux
  * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
@@ -69,6 +101,12 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     skipBuild = false,
     skipE2e = false,
     freshE2e = false,
+    recordBaseline = false,
+    refreshCache = false,
+    linux = false,
+    linuxImage = null,
+    _runLinuxSuite = runLinuxSuite,
+    _exec = undefined,
     _runBuildCheck = runBuildCheck,
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
@@ -79,6 +117,64 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   const stack = readStack(projectPath);
   const paths = readProjectPaths(projectPath);
 
+  // The suites are resolved ONCE, before anything is executed, because
+  // `--filter` has to be judged before the first second of build time is
+  // spent: a filter that matches nothing is a typo, and paying for a build to
+  // discover a typo is the worst of both outcomes.
+  const testPlan = resolveTestNodes(projectPath);
+  const filter = parseTestFilter(options.filter);
+  if (filter && !testPlan.nodes.some((node) => nodeMatchesFilter(node, filter))) {
+    const declared = testPlan.nodes.map((node) => node.id).join(', ') || '(none)';
+    throw new VerifyUsageError(
+      `--filter "${filter.raw}" matched no test node — declared nodes: ${declared}`
+    );
+  }
+
+  // `--record-baseline` is judged in the same breath, and for the same reason:
+  // discovering that there is nowhere to write AFTER running the whole fleet
+  // would charge the user a full suite for a usage error. `config.json` is
+  // never created here — this repository deliberately has none, and inventing
+  // one would break `doctor --full`.
+  if (recordBaseline) {
+    const problem = baselineTargetProblem(projectPath, testPlan, { skipTests });
+    if (problem) throw new VerifyUsageError(problem);
+  }
+
+  // `--refresh-cache` is judged in the same breath as `--filter` and
+  // `--record-baseline`, and for the same reason — but here the stake is higher
+  // than a wasted clock: a refusal AFTER the cache was touched would leave a
+  // half-rewritten tree behind. Same discipline as `finish --merge`, which
+  // validates the root BEFORE archiving.
+  if (refreshCache) {
+    const problem = refreshCacheProblem(projectPath, testPlan, filter, { skipTests });
+    if (problem) throw new VerifyUsageError(problem);
+  }
+
+  // `--linux` fails FAST and LOUD when Docker is missing (exit 2). Never a
+  // skip: "we could not check on Linux" reading as green is F35 itself.
+  if (linux) {
+    const problem = checkLinuxPreconditions({
+      projectPath, skipTests, ...(_exec ? { exec: _exec } : {}),
+    });
+    if (problem) throw new VerifyUsageError(problem);
+
+    // The MORPH_EVAL_* channel carries ABSOLUTE host paths, and the container
+    // runs a COPY of the tree at /work — so those paths do not exist inside it.
+    // Refusing by name is the only honest answer: running the node anyway would
+    // fail with an unrelated message, and skipping it would be the green-over-
+    // nothing shape this feature exists to remove. The escape is named.
+    const evalNode = testPlan.nodes.find(
+      (node) => node.runner === EVAL_RUNNER && nodeMatchesFilter(node, filter)
+    );
+    if (evalNode) {
+      throw new VerifyUsageError(
+        `--linux não executa o nó de eval "${evalNode.id}": o canal MORPH_EVAL_* carrega caminhos absolutos do host, `
+      + 'e o container roda uma CÓPIA da árvore em /work. Rode o eval fora do container, '
+      + `ou exclua-o com --filter (nós declarados: ${testPlan.nodes.map((n) => n.id).join(', ')}).`
+      );
+    }
+  }
+
   const nodes = {};
   const feedback = [];
 
@@ -94,10 +190,18 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   const explicitTimeout = Number.isFinite(options.timeout) ? options.timeout : undefined;
   nodes.tests = await runTestsNode({
     projectPath,
+    testPlan,
+    filter,
     skipTests,
     buildNode: nodes.build,
     timeout: explicitTimeout,
+    taskId,
+    refreshCache,
+    linux,
+    linuxImage,
     _runTestSuite,
+    _runLinuxSuite,
+    _exec,
   });
   appendTestsFeedback(feedback, nodes.tests);
 
@@ -132,6 +236,13 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
 
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
+  // Recording happens LAST and only from what actually ran — the number is a
+  // measurement of this invocation, never a value carried in from anywhere.
+  const baseline = recordBaseline ? recordBaselineFrom(projectPath, nodes.tests) : null;
+  if (baseline && !baseline.recorded) {
+    feedback.push(`[baseline] não gravada: ${baseline.reason}`);
+  }
+
   return {
     version: 1,
     feature: featureName,
@@ -143,6 +254,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     nodes,
     feedback,
     traceability,
+    ...(baseline ? { baseline } : {}),
   };
 }
 
@@ -186,35 +298,276 @@ function appendBuildFeedback(feedback, buildNode) {
 // Tests node
 // ============================================================================
 
-async function runTestsNode({ projectPath, skipTests, buildNode, timeout, _runTestSuite }) {
-  const command = resolveTestCommand(projectPath);
+/**
+ * Run EVERY test suite the project declares, and roll the results up.
+ *
+ * Why a rollup instead of one node: defect F30. The resolver answered
+ * "dotnet test", the 3.082 vitest tests of the same repository never ran, and
+ * the gate reported green — a suite nobody could name is a suite that cannot
+ * fail. `resolveTestNodes()` now returns the LIST, each entry runs with its own
+ * command, cwd and clock, and every one of them appears in `runs[]`.
+ *
+ * `nodes.tests` deliberately stays an OBJECT with `status` (D6): verify.js and
+ * the persisted stamp read `nodes.tests.status`, and turning a verification
+ * defect into a shape defect is not progress. The plural detail lives in
+ * `runs[]` beside it.
+ *
+ * @returns {Object} The rollup: `status`, joined `command`, summed `durationMs`,
+ *   `source`, `environment` (null outside a container) and `runs[]`.
+ */
+async function runTestsNode({
+  projectPath, testPlan, filter, skipTests, buildNode, timeout, taskId, refreshCache = false,
+  linux = false, linuxImage = null, _runTestSuite, _runLinuxSuite = runLinuxSuite, _exec,
+}) {
+  const { nodes, source } = testPlan;
+  // Kept readable for whoever only prints the string — the same join the
+  // fallback scan already used for a chain of test projects.
+  const command = nodes.map((n) => n.command).filter(Boolean).join(' && ') || null;
+  // A fresh `runs: []` per return — two rollups must never alias one array.
+  const nothingRan = (reason) => ({
+    status: 'skip', command, source, environment: null, runs: [], warnings: [],
+    durationMs: 0, reason, output: '',
+  });
+
+  if (skipTests) return nothingRan('requested');
 
-  if (skipTests) {
-    return { status: 'skip', command, durationMs: 0, reason: 'requested', output: '' };
+  if (buildNode.status === 'fail') {
+    return nothingRan('build failed — test run would only add noise');
   }
 
-  if (buildNode.status === 'fail') {
-    return {
-      status: 'skip',
-      command,
-      durationMs: 0,
-      reason: 'build failed — test run would only add noise',
-      output: '',
-    };
+  if (linux) {
+    const { runs, environment } = await runNodesInLinux({
+      projectPath, nodes, filter, taskId, timeout, linuxImage, _runLinuxSuite, _exec,
+    });
+    return rollUpTestRuns(runs, { command, source, environment });
+  }
+
+  const runs = [];
+  for (const node of nodes) {
+    runs.push(await runOneTestNode({
+      projectPath, node, filter, taskId, timeout, refreshCache, _runTestSuite,
+    }));
+  }
+
+  return rollUpTestRuns(runs, { command, source });
+}
+
+/**
+ * Run the executable nodes inside ONE Linux container and judge them with the
+ * SAME rules the local path uses.
+ *
+ * The pre-decisions (invalid config, `--filter`, an e2e node at task scope)
+ * happen HERE, before the container exists: a node that must not run must not
+ * be written into the container script either, or the flag would quietly run
+ * what the user filtered out. What the container returns — an exit code and an
+ * output — is then handed to `judgeRun()`, the same function the host path
+ * calls, so a count drop means a count drop in both environments.
+ *
+ * The tree the container executes is a COPY on its own filesystem, never the
+ * bind mount: see linux-runner.js. That is the whole reason this path exists.
+ */
+async function runNodesInLinux({
+  projectPath, nodes, filter, taskId, timeout, linuxImage, _runLinuxSuite, _exec,
+}) {
+  const decided = new Map();
+  const toRun = [];
+  for (const node of nodes) {
+    const pre = preDecideRun({ node, filter, taskId, projectPath });
+    if (pre) decided.set(node.id, pre);
+    else toRun.push(node);
   }
 
+  // One container, one clock: the ceiling is the sum of what each node would
+  // have been given locally, since they share the run.
+  const containerTimeout = toRun.reduce(
+    (sum, node) => sum + resolveTestTimeout(projectPath, node, timeout), 0
+  ) || undefined;
+
+  const suite = await _runLinuxSuite({
+    projectPath,
+    nodes: toRun,
+    image: linuxImage || undefined,
+    timeout: containerTimeout,
+    ...(_exec ? { exec: _exec } : {}),
+  });
+
+  const byId = new Map((suite.results || []).map((r) => [r.id, r]));
+  const runs = nodes.map((node) => {
+    if (decided.has(node.id)) return decided.get(node.id);
+    const raw = byId.get(node.id);
+    if (!raw) {
+      // The container answered about a fleet that does not include this node.
+      // Silence here would be a suite vanishing from the report.
+      return { ...emptyRunEntry(node), status: 'fail', reason: 'o container não reportou este nó' };
+    }
+    if (raw.skipped) {
+      return { ...emptyRunEntry(node), reason: raw.reason };
+    }
+    const result = raw.exitCode === null
+      // No exit code is NOT a pass: the container died before this node
+      // reported, and a green verdict over an unobserved suite is F30's shape.
+      ? { passed: false, output: raw.output || '', reason: raw.reason, exitCode: null }
+      : { passed: raw.exitCode === 0, output: raw.output || '', exitCode: raw.exitCode };
+    return judgeRun({ node, result, durationMs: raw.durationMs ?? 0 });
+  });
+
+  return { runs, environment: suite.environment };
+}
+
+/**
+ * Execute (or decline to execute) one node, always producing a `runs[]` entry.
+ *
+ * Nothing is ever dropped: a node that must not run says so with a reason, in
+ * the place the reader is already looking. A suite that silently disappears
+ * from the report is the defect this whole feature exists to close.
+ */
+async function runOneTestNode({
+  projectPath, node, filter, taskId, timeout, refreshCache = false, _runTestSuite,
+}) {
+  const decided = preDecideRun({ node, filter, taskId, projectPath, refreshCache });
+  if (decided) return decided;
+
+  // The eval channel: the CLI DICTATES where the cache, the dataset and the
+  // summary live, so the same xunit suite is runnable by `verify` without a
+  // second configuration path. `env` is undefined for every other runner, which
+  // keeps `runTestSuite` on exactly the path it had before.
+  const evalChannel = node.runner === EVAL_RUNNER
+    ? evalNodeEnv(node, projectPath, { refresh: refreshCache })
+    : null;
+
   const start = Date.now();
-  const result = await _runTestSuite(projectPath, { timeout });
-  const durationMs = Date.now() - start;
+  const result = await _runTestSuite(projectPath, {
+    timeout, node, ...(evalChannel ? { env: evalChannel.env } : {}),
+  });
+  const entry = judgeRun({ node, result, durationMs: Date.now() - start });
+
+  return evalChannel ? judgeEvalRun(entry, node, evalChannel.summaryPath) : entry;
+}
+
+/**
+ * Second half of an eval verdict: what the SUMMARY says, on top of what the exit
+ * code said.
+ *
+ * Two things the exit code cannot see:
+ *   - the scenario COUNT, which is what `expectedCount` is compared against.
+ *     The summary wins when readable; otherwise the `dotnet` extractor's number
+ *     stands, because an eval IS `dotnet test`. **null stays UNKNOWN, never 0** —
+ *     an unreadable summary must not manufacture a count drop;
+ *   - a suite that evaluated ZERO scenarios and exited 0. Nothing failed, because
+ *     nothing ran: the guardrail-inert shape this repository has already paid to
+ *     learn to detect.
+ */
+function judgeEvalRun(entry, node, summaryPath) {
+  const summary = readEvalSummary(summaryPath);
+  const warnings = [...(entry.warnings || [])];
+
+  const cold = evalColdCacheWarning(summary);
+  if (cold) warnings.push(cold);
+
+  const fromSummary = evalScenarioCount(summary);
+  const count = fromSummary ?? entry.count;
+  const verdict = compareTestCount(count, node.expectedCount);
+  if (verdict.warning) warnings.push(verdict.warning);
+
+  // As falhas NOMEADAS entram no buffer de saida do no, e entram na FRENTE.
+  // `appendTestsFeedback` prefere `output` a `reason`, entao um nome so no
+  // `reason` nunca chegaria ao `feedback[]`; e a cauda do `dotnet` e ruido
+  // truncado exatamente onde o sumario ja tem a frase certa. Prepend, e nao
+  // substituicao, porque um crash do runner tambem vive nessa cauda.
+  const named = evalFailureLines(summary);
+  const withNames = named.length > 0
+    ? { ...entry, output: [...named, ...(entry.output ? [entry.output] : [])].join('\n') }
+    : entry;
+
+  const empty = evalEmptyRunProblem(summary);
+  if (empty) {
+    return { ...withNames, status: 'fail', count, warnings, reason: empty };
+  }
+
+  if (entry.status === 'pass' && verdict.verdict === 'drop') {
+    return { ...withNames, status: 'fail', count, warnings, reason: verdict.reason };
+  }
+  if (verdict.verdict === 'drop') warnings.push(verdict.reason);
+
+  return { ...withNames, count, warnings };
+}
+
+/** The `runs[]` entry every path starts from — every field present, nothing implied. */
+function emptyRunEntry(node) {
+  return {
+    id: node.id,
+    command: node.command,
+    cwd: node.cwd,
+    runner: node.runner,
+    expectedCount: node.expectedCount,
+    // Always present, so no reader has to tell "absent" from "unknown" by
+    // optional chaining. **null is UNKNOWN, never 0** (D7).
+    count: null,
+    status: 'skip',
+    durationMs: 0,
+    reason: null,
+    warnings: [],
+    output: '',
+  };
+}
+
+/**
+ * The verdicts that exist BEFORE anything is executed, or null when the node
+ * has to run to be judged.
+ *
+ * Shared by the local loop and by `--linux`, so a node that must not run is
+ * refused for the same reason and with the same words in both environments —
+ * two copies of this ordering is how a filtered node ends up invisible in one
+ * of them.
+ */
+function preDecideRun({ node, filter, taskId, projectPath = '.', refreshCache = false }) {
+  const entry = emptyRunEntry(node);
+
+  // The resolver already decided: invalid config (fail-closed, D4) or an
+  // explicit "no suites declared". Executing it would be asking a question that
+  // has been answered — and, for an invalid node, answering it wrongly.
+  if (node.status) {
+    return { ...entry, status: node.status, reason: node.reason };
+  }
+
+  // Deliberately AFTER the pre-decided verdict above: `--filter` says "do not
+  // spend time on this suite", not "do not tell me my config is broken". An
+  // invalid node costs no clock and still reddens the gate (D4).
+  if (!nodeMatchesFilter(node, filter)) {
+    return { ...entry, reason: `filtered out (--filter ${filter.raw})` };
+  }
+
+  if (node.e2e && taskId) {
+    return { ...entry, reason: 'e2e node runs at feature scope only' };
+  }
+
+  // The eval pre-flight lives HERE, beside the other pre-decisions, so the host
+  // loop and the `--linux` path refuse for the same reason with the same words.
+  // Its three cache verdicts are FAILURES, never skips: a skip over an unusable
+  // cache is a green gate above a verification that never happened. The only
+  // skip it produces is scope — an eval suite does not pay for itself inside the
+  // per-task loop, and the result Gate 3 reads is the feature-scoped one.
+  if (node.runner === EVAL_RUNNER) {
+    const pre = evalPreflight(projectPath, node, { taskId, refresh: refreshCache });
+    if (pre.status) return { ...entry, status: pre.status, reason: pre.reason };
+  }
+
+  return null;
+}
+
+/**
+ * Turn ONE executor result into a `runs[]` entry — the count rule included.
+ *
+ * Called by both the local loop and the `--linux` container path on purpose:
+ * a drop, a rise and an unknown count must mean the same thing whether the
+ * suite ran on this host or inside a container. A second copy of this judgement
+ * is how two environments start disagreeing about the same suite.
+ */
+function judgeRun({ node, result, durationMs }) {
+  const entry = emptyRunEntry(node);
 
   if (result.skipped) {
-    return {
-      status: 'skip',
-      command,
-      durationMs,
-      reason: result.reason || 'no test command detected',
-      output: '',
-    };
+    return { ...entry, durationMs, reason: result.reason || 'no test command detected' };
   }
 
   // A timeout has no verdict to report: the tail of a truncated log reads like
@@ -222,8 +575,8 @@ async function runTestsNode({ projectPath, skipTests, buildNode, timeout, _runTe
   if (result.timedOut) {
     const tail = tailLines(result.output, OUTPUT_TAIL_LINES);
     return {
+      ...entry,
       status: 'fail',
-      command,
       durationMs,
       timedOut: true,
       reason: result.message,
@@ -231,22 +584,224 @@ async function runTestsNode({ projectPath, skipTests, buildNode, timeout, _runTe
     };
   }
 
+  // How many tests actually ran, and how that compares to the recorded
+  // baseline. Read from the FULL output, before it is truncated to a tail —
+  // the summary line is the last thing a runner prints, but a red run's tail
+  // is chosen for the failures, not for the summary.
+  const parsed = parseTestCount(result.output, node.runner);
+  const count = parsed ? parsed.total : null;
+  const verdict = compareTestCount(count, node.expectedCount);
+  const warnings = verdict.warning ? [verdict.warning] : [];
+
+  // A drop is the one count verdict that fails a node by itself: tests that
+  // used to run no longer do. A RISE never fails (D7) — the suite grows with
+  // every task, and failing on growth teaches deleting tests.
+  if (verdict.verdict === 'drop' && result.passed) {
+    return { ...entry, status: 'fail', durationMs, count, warnings, reason: verdict.reason, output: '' };
+  }
+  // Already red: the failing test is the better lead, so the drop travels
+  // beside it instead of overwriting the reason.
+  if (verdict.verdict === 'drop') warnings.push(verdict.reason);
+
   return {
+    ...entry,
     status: result.passed ? 'pass' : 'fail',
-    command,
     durationMs,
-    reason: null,
+    count,
+    warnings,
+    // `test-build-failed` / `stale-binary`: the executor refused BEFORE any
+    // test ran, and the reason is the only thing worth reading. Without this
+    // the node would go red with a null reason and the reader would go hunting
+    // through a compiler log for a suite that never started.
+    reason: result.reason ?? null,
     output: result.passed ? '' : tailLines(result.output, OUTPUT_TAIL_LINES),
   };
 }
 
+/**
+ * Aggregate the per-node runs into the single node `verify` publishes.
+ *
+ * The rollup is pessimistic on purpose: ANY red run reddens it. A green
+ * aggregate covering a red suite is F30 restated, so `some(fail)` is checked
+ * before anything else. `skip` only survives when there is nothing else to
+ * report — one green run among skips is a pass.
+ */
+function rollUpTestRuns(runs, { command, source, environment = null }) {
+  const failed = runs.filter((r) => r.status === 'fail');
+  const status = failed.length > 0
+    ? 'fail'
+    : runs.some((r) => r.status === 'pass') ? 'pass' : 'skip';
+
+  const node = {
+    status,
+    command,
+    durationMs: runs.reduce((sum, r) => sum + (r.durationMs || 0), 0),
+    reason: null,
+    output: failed.map((r) => r.output).filter(Boolean).join('\n'),
+    source,
+    // Where these suites ran. `null` is the local host; a container run says so
+    // by name and image, because a green from a container and a green from the
+    // host are otherwise indistinguishable in feature.json — and the next
+    // person would not know what was proven.
+    environment,
+    // Named by suite: a warning that does not say WHICH baseline went stale
+    // sends the reader to read every one of them.
+    warnings: runs.flatMap((r) => (r.warnings || []).map((w) => `${r.id}: ${w}`)),
+    runs,
+  };
+
+  if (status === 'fail') node.reason = failed[0].reason ?? null;
+  else if (status === 'skip') {
+    node.reason = runs.length === 1 ? runs[0].reason : 'every test node was skipped';
+  }
+  if (runs.some((r) => r.timedOut)) node.timedOut = true;
+
+  return node;
+}
+
+/**
+ * One feedback line per RED node, named by node id.
+ *
+ * The `[tests/{id}]` prefix replaces the old bare `[tests]`: with N suites, a
+ * line that does not say which one failed sends the reader to the wrong repo
+ * half.
+ */
 function appendTestsFeedback(feedback, testsNode) {
+  // Warnings are emitted whatever the verdict — a stale baseline lives on a
+  // GREEN node by construction (the count rose), so a warning that only
+  // printed on failure would never print at all.
+  for (const run of testsNode.runs || []) {
+    for (const warning of run.warnings || []) {
+      feedback.push(`[tests/${run.id}] warning: ${warning}`);
+    }
+  }
   if (testsNode.status !== 'fail') return;
-  for (const line of linesOf(testsNode.output)) {
-    feedback.push(`[tests] ${line}`);
+  for (const run of testsNode.runs || []) {
+    if (run.status !== 'fail') continue;
+    for (const line of linesOf(run.output || run.reason || '')) {
+      feedback.push(`[tests/${run.id}] ${line}`);
+    }
   }
 }
 
+/**
+ * Why `--refresh-cache` cannot mean what it says, or null when it can.
+ *
+ * Judged BEFORE the build node, and the ordering is the whole point: a refusal
+ * that arrived after the cache was touched would leave a half-rewritten tree
+ * behind. Same discipline `finish --merge` learned — validate the precondition
+ * before the mutation, never after.
+ *
+ * Three refusals, all usage errors (exit 2), never verdicts:
+ *   - no eval node declared: succeeding silently would teach the user to type a
+ *     flag that does nothing;
+ *   - `--skip-tests`: the two flags cancel each other, and the winner would be
+ *     whichever the code happened to check first;
+ *   - a filter that excludes every eval node: same shape as the first.
+ *
+ * The MISSING CREDENTIAL is deliberately NOT judged here: it is per node (each
+ * declares its own `envFile`), so `evalPreflight` answers it — still before the
+ * command runs, and still without touching the tree.
+ *
+ * @param {string} projectPath
+ * @param {{nodes: Array}} testPlan
+ * @param {{tokens: string[], raw: string}|null} filter
+ * @param {{skipTests: boolean}} opts
+ * @returns {string|null}
+ */
+function refreshCacheProblem(projectPath, testPlan, filter, { skipTests }) {
+  if (skipTests) {
+    return '--refresh-cache com --skip-tests: as duas flags se anulam — a regravação da cache É a suíte de eval';
+  }
+
+  const evalNodes = testPlan.nodes.filter((node) => node.runner === EVAL_RUNNER);
+  if (evalNodes.length === 0) {
+    const declared = testPlan.nodes.map((node) => node.id).join(', ') || '(nenhum)';
+    return `--refresh-cache sem nenhum nó \`runner: "evals"\` declarado em project.tests[] — nós declarados: ${declared}`;
+  }
+
+  if (!evalNodes.some((node) => nodeMatchesFilter(node, filter))) {
+    return `--refresh-cache com --filter "${filter.raw}", que não casa nenhum nó de eval`
+         + ` (nós de eval: ${evalNodes.map((node) => node.id).join(', ')})`;
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Baseline recording (--record-baseline)
+// ============================================================================
+
+/**
+ * Why `--record-baseline` cannot run here, or null when it can.
+ *
+ * Judged BEFORE the build node, beside the `--filter` check, because both are
+ * statements about a command that cannot mean what it says. Paying for a full
+ * suite to be told there was nowhere to write the result is the worst possible
+ * ordering.
+ *
+ * The refusal for a project with no `project.tests[]` is deliberate rather
+ * than helpful: the nodes the fallback synthesizes are not declared anywhere,
+ * so there is no entry to update, and writing one would mean this command
+ * inventing the declaration it came to maintain. `config.json` is likewise
+ * never created — the framework repository has none on purpose (creating it
+ * breaks `doctor --full`), so the honest answer is a named usage error.
+ *
+ * @param {string} projectPath
+ * @param {{ nodes: Array, source: string }} testPlan
+ * @param {{ skipTests: boolean }} opts
+ * @returns {string|null}
+ */
+function baselineTargetProblem(projectPath, testPlan, { skipTests }) {
+  if (skipTests) {
+    return '--record-baseline com --skip-tests não mede nada — uma baseline vem de uma execução, não de uma omissão';
+  }
+  if (!existsSync(morphConfigPath(projectPath))) {
+    return `--record-baseline não tem onde gravar: ${morphConfigPath(projectPath)} não existe `
+      + '(e não será criado — declare project.tests[] antes)';
+  }
+  if (testPlan.source !== 'config-tests') {
+    return '--record-baseline exige project.tests[] declarado em .morph/config/config.json — '
+      + `os nós de "${testPlan.source}" são sintetizados pelo fallback e não têm entrada onde gravar`;
+  }
+  return null;
+}
+
+/**
+ * Turn a finished tests rollup into a baseline write, or into a refusal.
+ *
+ * D8 lives here: the number is only ever what a REAL run measured, and only
+ * when every node of that run is green. A red run records nothing — writing a
+ * lower count over a regression is how the regression becomes the new normal.
+ * A PARTIAL run records nothing either: `--filter` and skips leave nodes
+ * unmeasured, and a baseline covering half the fleet is a claim about the
+ * other half that nobody made.
+ *
+ * @param {string} projectPath
+ * @param {Object} testsNode - The rollup produced by runTestsNode()
+ * @returns {{ recorded: boolean, reason: string|null, updates: Array, path?: string }}
+ */
+function recordBaselineFrom(projectPath, testsNode) {
+  const runs = testsNode.runs || [];
+  const refuse = (reason) => ({ recorded: false, reason, updates: [] });
+
+  if (runs.length === 0) return refuse('nenhum nó de teste executou');
+
+  const notGreen = runs.filter((r) => r.status !== 'pass');
+  if (notGreen.length > 0) {
+    const named = notGreen.map((r) => `${r.id} (${r.status}${r.reason ? `: ${r.reason}` : ''})`).join('; ');
+    return refuse(
+      `execução não está inteiramente verde — ${named}. `
+      + 'Gravar baseline de execução vermelha ou parcial congela a regressão'
+    );
+  }
+
+  return recordTestBaselines(
+    projectPath,
+    runs.map((r) => ({ id: r.id, count: r.count }))
+  );
+}
+
 // ============================================================================
 // Validators node
 // ============================================================================