faberun 0.28.0 → 0.30.0

package/src/plan/pipeline.mjs

@@ -30,6 +30,7 @@ import { validateJudgeIndependence } from "../contract/judge-independence.mjs";
 import { firstEligibleReviewer, reviewerProvenanceOf } from "./reviewer.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
+import { clearPlanProgress, writePlanProgress } from "./progress.mjs";
 import { checkPlanProofs } from "./proof-check.mjs";
 import { collectHumanSteps } from "./human-step.mjs";
 import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validatePlanOutput } from "./template.mjs";
@@ -38,6 +39,7 @@ import { resolveRuntimes } from "./routing.mjs";
 import { contentDigest, freezePlan, writeFrozenPlanRecord } from "./freeze.mjs";
 import { availabilityOf, fileLineCount, highestOf, modelOf, toContractNode, toSizingNode } from "./pipeline-shape.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
+import { assertLaunchBaseClean } from "../repo/source-identity.mjs";
 import { contestPlan } from "./contest.mjs";
 import { runReviewRounds } from "./rounds.mjs";
 
@@ -55,7 +57,7 @@ export { droppedWriteFindings, unresolvedFindings } from "./rounds.mjs";
 /** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
 /** @typedef {import("./template.mjs").PlanPhase} PlanPhase */
 /** @typedef {import("./sizing.mjs").PlanNode & {objective: string}} SizedPlanNode */
-/** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[], phases?: PlanPhase[]}} AssembledPlan */
+/** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[], phases?: PlanPhase[], suites: VerificationSuites}} AssembledPlan */
 /** @typedef {"standard"|"high"|"none"} ApproveBelow */
 /** @typedef {(contractPath: string, contract: ValidatedContract) => Promise<void>|void} LaunchFn */
 /** @typedef {(runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, cwd: string) => Promise<import("../harnesses/index.mjs").ProbeResult[]>} AskFn */
@@ -105,6 +107,27 @@ const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
  * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
  */
 export async function runPlanningPipeline(options) {
+  try {
+    return await runPlanningStages(options);
+  } finally {
+    // The record of a process that is working must not outlive the work. It is
+    // cleared here, in the one place every return and every throw passes
+    // through, rather than by a caller: `plan` already removed it, but a
+    // caller that forgot left a record that makes the next launch report a
+    // death that never happened, and the record is worth nothing if it can be
+    // wrong in that direction.
+    if (typeof options.campaignId === "string" && typeof options.phase === "string") clearPlanProgress(resolve(options.cwd ?? "."), options.campaignId, options.phase);
+  }
+}
+
+/**
+ * The stages themselves, separate from the exported entry point only so that
+ * the liveness record is removed on every path out of them.
+ *
+ * @param {Parameters<typeof runPlanningPipeline>[0]} options
+ * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
+ */
+async function runPlanningStages(options) {
   const {
     specPath, campaignId, phase, runtimes, launch, wait,
     reviewRounds = 2, runtimeDefaults = {}, reviewers = [], verification = {}, targetedFix = false, judgeIndependence,
@@ -125,6 +148,17 @@ export async function runPlanningPipeline(options) {
   const campaignPath = campaignTree(cwd, campaignId);
   const campaign = readCampaign(campaignPath);
   if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
+  // The run this pipeline launches is the last thing it does, and the run
+  // refuses a tree whose HEAD is dirty. Asking the same question here, before
+  // the first stage, is the difference between a refusal and sixteen minutes
+  // spent on repo facts first. Measured 2026-09-27 (AP10): a `plan` stage that
+  // died exactly that way reported "refusing to launch against HEAD: the
+  // working tree has 2 uncommitted paths" only when the operator re-ran it in
+  // the foreground. Nothing this pipeline writes touches the tree
+  // `dirtyTreePaths` reads: the plan artifacts live under the campaign tree in
+  // the home, and the scratch relay inside the repository is excluded by the
+  // same pathspec the launch uses.
+  assertLaunchBaseClean(cwd, undefined);
   refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode, judgeIndependence);
   refusePlanningSilence(await ask(runtimes, runtimeDefaults, cwd), cwd);
 
@@ -142,10 +176,18 @@ export async function runPlanningPipeline(options) {
   const plansDir = join(campaignTree(cwd, campaignId), "plans", phase);
   mkdirSync(plansDir, { recursive: true });
   const pipelineLog = join(plansDir, "pipeline.jsonl");
+  // Every stage line is also the liveness record: the file is the answer to
+  // "is this plan still working", and a plan that dies mid-stage leaves the
+  // stage it died in as the last thing it ever said. Nothing removes it here;
+  // the caller clears it when the pipeline returns, so a record that survives
+  // a returned pipeline cannot happen and a record that survives anything
+  // else means exactly one thing.
   /** @param {string} stage @param {Record<string, unknown>} [extra] */
-  const logStage = (stage, extra = {}) => appendJsonl(pipelineLog, {
-    type: "plan.stage", at: new Date().toISOString(), campaignId, phase, stage, ...extra,
-  });
+  const logStage = (stage, extra = {}) => {
+    const at = new Date().toISOString();
+    appendJsonl(pipelineLog, { type: "plan.stage", at, campaignId, phase, stage, ...extra });
+    writePlanProgress(cwd, campaignId, phase, { campaignId, phase, at, stage, ...extra });
+  };
 
   // A discovery node's `readFiles` must resolve inside `cwd` (the task packet's
   // own containment rule), but `plansDir` lives under the home since R2 and no
@@ -160,7 +202,17 @@ export async function runPlanningPipeline(options) {
   // the draft stage reads what the planner measured instead of inferring it
   // from the spec's prose.
   const parsedSpec = parseSpec(specText);
-  const repoFacts = collectRepoFacts(cwd, { requirements: parsedSpec.requirements });
+  // This stage holds the terminal for minutes, which is why it says what it is
+  // about to do before it does it and one line per command as each finishes.
+  // Measured 2026-09-25/26 (AP3): five to eight minutes with nothing written
+  // anywhere, on six relaunches.
+  const repoFacts = collectRepoFacts(cwd, {
+    requirements: parsedSpec.requirements,
+    onProgress: (event) => {
+      if (event.kind === "commands") logStage("repo-facts:start", { commands: event.commands.map((argv) => argv.join(" ")) });
+      else logStage("repo-facts:measured", { argv: event.argv, measuredMs: event.measuredMs, index: event.index, total: event.total });
+    },
+  });
   // R16: an operator step a requirement's constraints declare, detected once
   // here so both the freeze below and a caller inspecting the pipeline agree
   // on the same list.
@@ -300,7 +352,7 @@ export async function runPlanningPipeline(options) {
    * @param {PlanOutput} currentPlan
    * @returns {AssembledPlan}
    */
-  const assembleFrozenNodes = (currentPlan) => assembleFrozenPlan(currentPlan, { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence });
+  const assembleFrozenNodes = (currentPlan) => assembleFrozenPlan(currentPlan, { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence, verification });
 
   /**
    * The raw contract exactly as `freezePlan` will assemble and validate it.
@@ -310,7 +362,7 @@ export async function runPlanningPipeline(options) {
    * @param {AssembledPlan} assembly
    * @returns {JsonObject}
    */
-  const frozenContractRaw = (assembly) => frozenContractRawOf(assembly, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, verification, judgeIndependence });
+  const frozenContractRaw = (assembly) => frozenContractRawOf(assembly, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, judgeIndependence });
 
   const roundsResult = await runReviewRounds({
     reviewRounds, plan, rejectedDraft: plan === null ? draft.output.plan : undefined, findings, cwd, plansDir, scratchDir, workingPlanPath, relativeWorkingPlanPath,
@@ -342,8 +394,10 @@ export async function runPlanningPipeline(options) {
   // is legitimate, an unnoticed one is not. Observed 2026-09-20 on the first
   // contract this planner ever froze: it carried neither suite while the same
   // ratchets, on hand-authored contracts, were catching copied helpers
-  // mid-run — and nothing said so.
-  const freezeWarnings = verification.sharedVerification || verification.finalVerification
+  // mid-run — and nothing said so. Read off the effective suites, so a plan
+  // that authored its own ratchets (RM-107) is not warned about a contract
+  // that carries them.
+  const freezeWarnings = carriesSuites(effectiveVerificationSuites(verification, plan))
     ? []
     : ["the frozen contract carries neither sharedVerification nor finalVerification, so no repository ratchet runs on its nodes and no final check closes the phase; pass --verification <file> if the target repository has ratchets every node must run"];
   try {
@@ -552,6 +606,46 @@ function taggedStageError(planStage, error) {
   return Object.assign(wrapped, { planStage });
 }
 
+/**
+ * Which contract-level suites the frozen contract will carry: the operator's
+ * `--verification`, when it was passed, otherwise the plan's own authored
+ * suites (RM-107). The operator wins because the flag is the one place an
+ * operator can still override a plan they did not trust; the plan's suites are
+ * the fallback because a phase whose whole point is a repository-wide ratchet
+ * must not freeze unratcheted just because nobody remembered the flag —
+ * measured 2026-09-27, `safe-to-hand-to-a-friend` phase 1 integrated a red
+ * tree no node had a command to catch.
+ *
+ * An empty array is dropped rather than carried: it runs nothing, and the
+ * contract reads its absence identically. One home, read by `assembleFrozenPlan`
+ * below and by both freeze-warning sites, so the warning cannot disagree with
+ * the contract about whether a ratchet runs.
+ *
+ * @param {VerificationSuites} operator
+ * @param {PlanOutput} plan
+ * @returns {VerificationSuites}
+ */
+export function effectiveVerificationSuites(operator, plan) {
+  const suites = operator.sharedVerification || operator.finalVerification ? operator : plan;
+  return {
+    ...(suites.sharedVerification?.length ? { sharedVerification: suites.sharedVerification } : {}),
+    ...(suites.finalVerification?.length ? { finalVerification: suites.finalVerification } : {}),
+  };
+}
+
+/**
+ * Whether a suite set carries anything at all. Exported beside
+ * `effectiveVerificationSuites` because the freeze warning in two modules asks
+ * this of its result, and a truthiness test written twice is how the warning
+ * and the contract drift apart.
+ *
+ * @param {VerificationSuites} suites
+ * @returns {boolean}
+ */
+export function carriesSuites(suites) {
+  return Boolean(suites.sharedVerification || suites.finalVerification);
+}
+
 /**
  * The one assembly a plan freezes through: sizing reshapes the drafted
  * nodes, routing assigns worker and judge, and `toContractNode` renders the
@@ -561,12 +655,16 @@ function taggedStageError(planStage, error) {
  * plan came from — a fresh draft/revise or one read back off a contested
  * `plan.json`.
  *
+ * `ctx.verification` takes part here, not in `frozenContractRawOf`, because
+ * which suites the contract carries is a decision the assembly makes once for
+ * every caller; the raw contract is then only the assembly rendered.
+ *
  * @param {PlanOutput} currentPlan
- * @param {{repoFacts: import("./repo-facts.mjs").RepoFacts, packageMode: import("./sizing.mjs").PackageMode, targetedFix: boolean, phase: string, cwd: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, judgeIndependence?: "same-vendor"}} ctx
+ * @param {{repoFacts: import("./repo-facts.mjs").RepoFacts, packageMode: import("./sizing.mjs").PackageMode, targetedFix: boolean, phase: string, cwd: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, judgeIndependence?: "same-vendor", verification?: VerificationSuites}} ctx
  * @returns {AssembledPlan}
  */
 export function assembleFrozenPlan(currentPlan, ctx) {
-  const { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence } = ctx;
+  const { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence, verification } = ctx;
   let sizing;
   try {
     sizing = applySizingRules(
@@ -597,6 +695,9 @@ export function assembleFrozenPlan(currentPlan, ctx) {
     // named it must now name the node that absorbed it or freeze would see
     // an unknown assignment.
     phases: carryPhaseDeclarations(currentPlan.phases, sizing.transformations),
+    // The plan's own suites survive sizing untouched: they are contract-level
+    // proof, so no node merge can absorb or invalidate one.
+    suites: effectiveVerificationSuites(verification ?? {}, currentPlan),
   };
 }
 
@@ -609,11 +710,11 @@ export function assembleFrozenPlan(currentPlan, ctx) {
  * for the same reason.
  *
  * @param {AssembledPlan} assembly
- * @param {{campaignId: string, phase: string, campaignGoal: string, cwd: string, plansDir: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, verification: VerificationSuites, judgeIndependence?: "same-vendor"}} ctx
+ * @param {{campaignId: string, phase: string, campaignGoal: string, cwd: string, plansDir: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, judgeIndependence?: "same-vendor"}} ctx
  * @returns {JsonObject}
  */
-export function frozenContractRawOf({ sizing, nodes }, ctx) {
-  const { campaignId, phase, campaignGoal, cwd, plansDir, runtimes, runtimeDefaults, verification, judgeIndependence } = ctx;
+export function frozenContractRawOf({ sizing, nodes, suites }, ctx) {
+  const { campaignId, phase, campaignGoal, cwd, plansDir, runtimes, runtimeDefaults, judgeIndependence } = ctx;
   return {
     schemaVersion: PROTOCOL_SCHEMA_VERSION,
     contractVersion: CONTRACT_VERSION,
@@ -635,12 +736,14 @@ export function frozenContractRawOf({ sizing, nodes }, ctx) {
     // The operator's opt-in, carried verbatim: the frozen contract is
     // validated under the same judge-independence rule its routing used.
     ...(judgeIndependence === undefined ? {} : { judgeIndependence }),
-    // The operator's ratchets, carried verbatim: which suites a repository
-    // runs on every node is the operator's policy, supplied through
-    // `--verification`, never derived from repository facts. Validated at the
-    // flag boundary, so freeze neither re-derives nor edits them.
-    ...(verification.sharedVerification ? { sharedVerification: verification.sharedVerification } : {}),
-    ...(verification.finalVerification ? { finalVerification: verification.finalVerification } : {}),
+    // The ratchets this phase carries, chosen once by the assembly and carried
+    // verbatim here: the operator's `--verification` when it was passed,
+    // otherwise the suites the plan authored from the repository facts
+    // (RM-107). Validated at both boundaries — the flag loader for one, the
+    // plan validator for the other — so freeze neither re-derives nor edits
+    // them.
+    ...(suites?.sharedVerification ? { sharedVerification: suites.sharedVerification } : {}),
+    ...(suites?.finalVerification ? { finalVerification: suites.finalVerification } : {}),
     nodes,
   };
 }

package/src/plan/progress.mjs

@@ -0,0 +1,101 @@
+/**
+ * The liveness record of a planning process: where a `faberun plan` says which
+ * stage it is in, and how a later reader tells a process that is still working
+ * from one that died without a word.
+ *
+ * It is separate from `pipeline.mjs` because two layers need it and neither
+ * owns it: the pipeline writes it as it advances through stages, and
+ * `cli/plan.mjs` reads it before starting and clears it when the pipeline
+ * returns. `cli/plan.mjs` already owns the sibling record for a plan that dies
+ * before the pipeline is reached (`writePlanBootstrapFailure`); this one
+ * covers the death that record cannot, the one that happens minutes later.
+ *
+ * Measured 2026-09-26 (AP4): a detached `plan` (pid 64270) vanished during the
+ * repo-facts stage, leaving `plans/phase-1` empty, with no `pipeline.jsonl` and
+ * no bootstrap failure. `watchPlanBootstrap` covers a five-second window, so a
+ * death after it recorded nothing at all.
+ *
+ * A record exists because a detached process's stdio is discarded, which is
+ * also why `plan --resolve` writes none: it is never detached, so a death
+ * there is visible where it happens and a record would only add a second
+ * account of something the operator already watched.
+ */
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { pidAlive, processStartToken, sameProcessStartToken } from "../run/lock.mjs";
+import { campaignTree } from "../run/paths.mjs";
+import { readJson, writeJsonAtomic } from "../run/store.mjs";
+
+/** @typedef {{pid?: number, processStartToken?: string|null, at?: string, stage?: string, [key: string]: unknown}} PlanProgressRecord */
+
+/**
+ * Beside the phase's durable plan artifacts rather than in the disposable
+ * scratch tree, for the same reason `bootstrap-failure.json` is: a record a
+ * later launch has to find cannot live where the next `plan` may wipe.
+ *
+ * @param {string} cwd @param {string} campaignId @param {string} phase
+ * @returns {string}
+ */
+export function planProgressPath(cwd, campaignId, phase) {
+  return join(campaignTree(cwd, campaignId), "plans", phase, "progress.json");
+}
+
+/**
+ * Write the record of the process that is doing the work right now. It carries
+ * the pid together with the process start token, so a reader an hour later is
+ * not fooled by a pid the operating system handed to somebody else.
+ *
+ * @param {string} cwd @param {string} campaignId @param {string} phase
+ * @param {PlanProgressRecord} record
+ * @returns {void}
+ */
+export function writePlanProgress(cwd, campaignId, phase, record) {
+  writeJsonAtomic(planProgressPath(cwd, campaignId, phase), {
+    pid: process.pid,
+    processStartToken: processStartToken(process.pid),
+    at: new Date().toISOString(),
+    ...record,
+  });
+}
+
+/**
+ * @param {string} cwd @param {string} campaignId @param {string} phase
+ * @returns {PlanProgressRecord|null}
+ */
+export function readPlanProgress(cwd, campaignId, phase) {
+  try {
+    const record = /** @type {PlanProgressRecord} */ (readJson(planProgressPath(cwd, campaignId, phase)));
+    return record && typeof record === "object" && !Array.isArray(record) ? record : null;
+  } catch {
+    // An absent record is the ordinary case: a plan that finished clears it.
+    // A record that will not parse is one a dying process left half-written,
+    // and there is nothing in it a reader could act on either way.
+    return null;
+  }
+}
+
+/**
+ * The record of a process that stopped where it stood, or null when no plan is
+ * running and nothing died. A live pid with the recorded start token is work
+ * in progress, however long it has been in the same stage; anything else means
+ * the pipeline never reached its own end.
+ *
+ * @param {string} cwd @param {string} campaignId @param {string} phase
+ * @returns {PlanProgressRecord|null}
+ */
+export function abandonedPlanProgress(cwd, campaignId, phase) {
+  const record = readPlanProgress(cwd, campaignId, phase);
+  if (!record) return null;
+  const pid = typeof record.pid === "number" ? record.pid : null;
+  const token = typeof record.processStartToken === "string" ? record.processStartToken : null;
+  if (pid !== null && pidAlive(pid) && sameProcessStartToken(processStartToken(pid), token)) return null;
+  return record;
+}
+
+/**
+ * @param {string} cwd @param {string} campaignId @param {string} phase
+ * @returns {void}
+ */
+export function clearPlanProgress(cwd, campaignId, phase) {
+  rmSync(planProgressPath(cwd, campaignId, phase), { force: true });
+}

package/src/plan/proof-check.mjs

@@ -13,7 +13,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { shellWords } from "../util.mjs";
-import { inlineScriptParseError } from "../contract/definition-of-done.mjs";
+import { inlineScriptParseError, unclosedQuote } from "../contract/definition-of-done.mjs";
 import { NAME_PATTERN_FLAG } from "./proof-run.mjs";
 
 /** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
@@ -150,6 +150,18 @@ export function checkPlanProofs(plan, repoFacts, cwd) {
         });
         continue;
       }
+      // AP13: a command the shell cannot parse never runs, so no delivery
+      // makes the item pass; the proof text has to change before the freeze.
+      const openQuote = unclosedQuote(commandText);
+      if (openQuote !== null) {
+        findings.push({
+          id: `proof-unparseable-${node.id}-${item.id}`,
+          severity: "critical",
+          nodeId: node.id,
+          text: `Node ${node.id}'s Definition of Done item "${item.id}" proves itself with a command that leaves a ${openQuote} open ("${commandText}"), which /bin/sh refuses before it runs, so no delivery can make this proof exit 0. Quote the value, as in --test-name-pattern="<title>".`,
+        });
+        continue;
+      }
       const nameFlag = NAME_PATTERN_FLAG.exec(commandText);
       if (nameFlag) {
         const pattern = nameFlag[1] ?? nameFlag[2] ?? nameFlag[3];

package/src/plan/proof-scope.mjs

@@ -30,7 +30,7 @@ const TEST_TITLE = /\b(?:test|it|describe)(?:\.\w+)?\(\s*(["'`])((?:\\.|(?!\1).)
  * @param {string[]} argv
  * @returns {{nameFilters: Array<{flag: string, value: string}>, paths: string[]}|null}
  */
-function nodeTestShape(argv) {
+export function nodeTestShape(argv) {
   if (argv[0] !== "node" || !argv.includes("--test")) return null;
   /** @type {Array<{flag: string, value: string}>} */
   const nameFilters = [];

package/src/plan/repo-facts.mjs

@@ -1,8 +1,9 @@
 /**
  * Repo facts: a deterministic, bounded inventory of the target repository —
  * tracked paths, declared scripts, verification candidates across the Node,
- * Python, Go, Rust, Zig and Makefile ecosystems, and which test file covers
- * which source module — collected without invoking a model. Every candidate
+ * Python, Go, Rust, Zig and Makefile ecosystems, and which source modules each
+ * test file covers, by its name and by what it imports or runs — collected
+ * without invoking a model. Every candidate
  * records the manifest it was read from; only the Node candidates are timed,
  * and no candidate for another ecosystem is ever executed to be found.
  * A planning stage's draft is authored against exactly this JSON instead of
@@ -20,6 +21,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { timeVerificationCommands } from "../host/preflight.mjs";
+import { directReferenceGraph } from "../repo/scope-closure.mjs";
 import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
 import { runShellCapture } from "./proof-run.mjs";
 
@@ -45,7 +47,7 @@ import { runShellCapture } from "./proof-run.mjs";
  *
  * @typedef {{argv: string[], manifest: string, measuredMs: number|null, eligible: boolean}} DetectedVerificationCandidate
  */
-/** @typedef {{path: string, covers: string|null}} TestFileEntry */
+/** @typedef {{path: string, covers: string[]}} TestFileEntry */
 /** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], detectedVerificationCandidates?: DetectedVerificationCandidate[], testFiles: TestFileEntry[], requirementMeasurements: RequirementMeasurement[]}} RepoFacts */
 
 const FORMAT_VERSION = 1;
@@ -95,16 +97,36 @@ function testDirectories(paths) {
 }
 
 /**
+ * What each test file covers: the module it is named after, when that module
+ * exists, plus every tracked module it imports or runs (RM-109). The naming
+ * convention alone was the whole answer, so a test that exercises a module
+ * without being named for it — a cross-module integration test, a test that
+ * spawns the CLI by URL — was invisible to planning. Measured on
+ * `safe-to-hand-to-a-friend`: four failures in 1763 reached the integration
+ * branch while every node had passed its own suite.
+ *
+ * Only tracked paths count, so a stray file in the working tree cannot become
+ * part of a plan's verification, and only `test/**\/*.test.mjs` files are
+ * entries at all: a helper is covered by the tests that import it, never a
+ * verifier itself.
+ *
  * @param {string[]} paths
  * @param {Set<string>} pathSet
+ * @param {Map<string, string[]>} references repo-relative references per file
  * @returns {TestFileEntry[]}
  */
-function testFileEntries(paths, pathSet) {
+function testFileEntries(paths, pathSet, references) {
   return paths
     .filter((path) => path.startsWith("test/") && path.endsWith(".test.mjs"))
     .map((path) => {
-      const modulePath = `src/${path.slice("test/".length, -".test.mjs".length)}.mjs`;
-      return { path, covers: pathSet.has(modulePath) ? modulePath : null };
+      /** @type {Set<string>} */
+      const covers = new Set();
+      const namedAfter = `src/${path.slice("test/".length, -".test.mjs".length)}.mjs`;
+      if (pathSet.has(namedAfter)) covers.add(namedAfter);
+      for (const referenced of references.get(path) ?? []) {
+        if (pathSet.has(referenced)) covers.add(referenced);
+      }
+      return { path, covers: [...covers].sort() };
     });
 }
 
@@ -176,6 +198,19 @@ function manifestCandidateCommands(cwd) {
   return commands;
 }
 
+/**
+ * How a caller watches this stage work. `commands` arrives once, naming every
+ * command about to be timed; `measured` arrives once per command as it
+ * finishes. Neither reaches the returned facts: two calls at the same HEAD
+ * stay byte-identical because no event is written into them.
+ *
+ * Measured 2026-09-25/26 (AP3): this stage took five to eight minutes and said
+ * nothing while it did, so `faberun plan` was indistinguishable from a hang
+ * and the operator checked the process by hand on six relaunches.
+ *
+ * @typedef {(event: {kind: "commands", commands: string[][]} | {kind: "measured", argv: string[], measuredMs: number, index: number, total: number}) => void} RepoFactsProgress
+ */
+
 /**
  * Time every candidate through `timeVerificationCommands`'s own probe —
  * real `spawnSync` and `Date.now` by default, or the caller's fake — instead
@@ -187,9 +222,10 @@ function manifestCandidateCommands(cwd) {
  * @param {string} cwd
  * @param {{argv: string[]}[]} commands
  * @param {MeasureProbes} probes
+ * @param {RepoFactsProgress} [onProgress]
  * @returns {{argv: string[], measuredMs: number, eligible: boolean}[]}
  */
-function measureCandidates(cwd, commands, probes) {
+function measureCandidates(cwd, commands, probes, onProgress) {
   if (commands.length === 0) return [];
   const now = probes.now ?? (() => Date.now());
   /** @type {number[]} */
@@ -201,7 +237,22 @@ function measureCandidates(cwd, commands, probes) {
       taskPacket: { verification: [{ argv: command.argv, timeoutSec: CANDIDATE_TIMEOUT_SEC }] },
     })),
   }));
-  timeVerificationCommands(contract, { ...probes, now: () => { const mark = now(); marks.push(mark); return mark; } });
+  timeVerificationCommands(contract, {
+    ...probes,
+    now: () => {
+      const mark = now();
+      marks.push(mark);
+      // Every command contributes exactly one start mark and one stop mark, in
+      // order, so an even mark count means the command at half that count just
+      // finished. That is the only progress signal this stage has while it
+      // holds the terminal for minutes.
+      const stopped = marks.length;
+      if (stopped % 2 === 0 && onProgress) {
+        onProgress({ kind: "measured", argv: commands[stopped / 2 - 1].argv, measuredMs: mark - marks[stopped - 2], index: stopped / 2, total: commands.length });
+      }
+      return mark;
+    },
+  });
   return commands.map((command, index) => {
     const measuredMs = marks[index * 2 + 1] - marks[index * 2];
     return { argv: command.argv, measuredMs, eligible: measuredMs <= ELIGIBLE_MS_CEILING };
@@ -247,7 +298,7 @@ export function measureRequirements(cwd, requirements, probes = {}) {
 
 /**
  * @param {string} cwd
- * @param {{measure?: MeasureProbes, maxPaths?: number, requirements?: SpecRequirement[]}} [options]
+ * @param {{measure?: MeasureProbes, maxPaths?: number, requirements?: SpecRequirement[], onProgress?: RepoFactsProgress}} [options]
  * @returns {RepoFacts}
  */
 export function collectRepoFacts(cwd, options = {}) {
@@ -255,7 +306,9 @@ export function collectRepoFacts(cwd, options = {}) {
   const allPaths = listTrackedPaths(cwd);
   const pathSet = new Set(allPaths);
   const scripts = readScripts(cwd);
-  const measured = measureCandidates(cwd, nodeCandidateCommands(scripts, allPaths), options.measure ?? {});
+  const candidates = nodeCandidateCommands(scripts, allPaths);
+  options.onProgress?.({ kind: "commands", commands: candidates.map((command) => command.argv) });
+  const measured = measureCandidates(cwd, candidates, options.measure ?? {}, options.onProgress);
   const detected = manifestCandidateCommands(cwd);
   const truncated = allPaths.length > maxPaths;
   return {
@@ -272,7 +325,7 @@ export function collectRepoFacts(cwd, options = {}) {
     // null "no measurement" sentinel freeze.mjs reads and eligibility true.
     verificationCandidates: measured.map((candidate) => ({ ...candidate, manifest: PACKAGE_MANIFEST })),
     detectedVerificationCandidates: detected.map((candidate) => ({ ...candidate, measuredMs: null, eligible: true })),
-    testFiles: testFileEntries(allPaths, pathSet),
+    testFiles: testFileEntries(allPaths, pathSet, directReferenceGraph(cwd)),
     requirementMeasurements: measureRequirements(cwd, options.requirements ?? [], options.measure ?? {}),
   };
 }

package/src/plan/resolve.mjs

@@ -26,7 +26,7 @@ import { freezePlan } from "./freeze.mjs";
 import { collectHumanSteps } from "./human-step.mjs";
 import { highestOf, modelOf } from "./pipeline-shape.mjs";
 import { reviewerProvenanceOf } from "./reviewer.mjs";
-import { PLANNER_SESSION_ID, assembleFrozenPlan, frozenContractRawOf, invalidPlanFinding, writeFrozenPlan } from "./pipeline.mjs";
+import { PLANNER_SESSION_ID, assembleFrozenPlan, carriesSuites, effectiveVerificationSuites, frozenContractRawOf, invalidPlanFinding, writeFrozenPlan } from "./pipeline.mjs";
 import { contestPlan } from "./contest.mjs";
 import { parseSpec } from "./spec.mjs";
 import { RISK_TIERS } from "./template.mjs";
@@ -132,17 +132,19 @@ export async function resolvePlanningPipeline({ plansDir, cwd, answers }) {
   }
   logStage("resolve", { round, answered: criticalFindings.length });
 
-  const freezeWarnings = verification.sharedVerification || verification.finalVerification
+  // The plan resumed here may carry suites of its own (RM-107), so the
+  // warning is read off the same effective set the freeze below will carry.
+  const freezeWarnings = carriesSuites(effectiveVerificationSuites(verification ?? {}, plan))
     ? []
     : ["the frozen contract carries neither sharedVerification nor finalVerification, so no repository ratchet runs on its nodes and no final check closes the phase; pass --verification <file> if the target repository has ratchets every node must run"];
   let stage = "sizing";
   try {
-    const assembled = assembleFrozenPlan(plan, { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence });
+    const assembled = assembleFrozenPlan(plan, { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults, judgeIndependence, verification });
     stage = "freeze";
     logStage("sizing", { transformations: assembled.sizing.transformations.length, nodeCount: assembled.sizing.plan.nodes.length, overheadMinutes: assembled.sizing.estimate.overheadMinutes });
     logStage("routing", { assignments: Object.keys(assembled.routing.assignments).length });
     const highestRiskTier = highestOf(assembled.sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
-    const frozen = freezePlan(frozenContractRawOf(assembled, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, verification, judgeIndependence }), {
+    const frozen = freezePlan(frozenContractRawOf(assembled, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, judgeIndependence }), {
       outDir: plansDir,
       phases: assembled.phases,
       spec: { path: specPath, digest: specDigest },