faberun 0.14.0 → 0.16.0

package/src/plan/pipeline.mjs

@@ -6,10 +6,11 @@
  * `freeze.mjs` (which only turns a plan into a validated contract on disk):
  * this module is the one place that sequences those runs, checks each round's
  * plan against the contract it would freeze into while a revise can still
- * act on the failure, and decides when a plan is contested instead of
- * frozen. `launch` and `wait` are the only two seams that touch a
- * process or the wall clock, so a test drives the whole pipeline through
- * `runContract` in-process, deterministically.
+ * act on the failure, compares a revision's write set against the plan it
+ * revised so scope closure cannot be satisfied by shrinking the work, and
+ * decides when a plan is contested instead of frozen. `launch` and `wait`
+ * are the only two seams that touch a process or the wall clock, so a test
+ * drives the whole pipeline through `runContract` in-process, deterministically.
  */
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
@@ -21,24 +22,28 @@ import { appendSeatAllowanceEvent, readJournal } from "../campaign/journal.mjs";
 import { readCampaign } from "../campaign/record.mjs";
 import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
+import { stableJson } from "../util.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
 import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.mjs";
-import { MIN_WRITE_FILES, applySizingRules } from "./sizing.mjs";
+import { MIN_WRITE_FILES, applySizingRules, provenParallelism } from "./sizing.mjs";
 import { resolveRuntimes } from "./routing.mjs";
 import { freezePlan } from "./freeze.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").VerificationCommand} VerificationCommand */
+/** @typedef {{sharedVerification?: VerificationCommand[], finalVerification?: VerificationCommand[]}} VerificationSuites */
 /** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
 /** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
 /** @typedef {import("./sizing.mjs").PlanNode & {objective: string}} SizedPlanNode */
+/** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}} AssembledPlan */
 /** @typedef {"standard"|"high"|"none"} ApproveBelow */
 /** @typedef {(contractPath: string, contract: ValidatedContract) => Promise<void>|void} LaunchFn */
 /** @typedef {(runDir: string) => Promise<import("../engine/supervise.mjs").RunProgress>|import("../engine/supervise.mjs").RunProgress} WaitFn */
-/** @typedef {{status: "frozen", plansDir: string, planPath: string, contractPath: string, approved: boolean, findings: PlanFindingOutput[]}} FrozenPipelineResult */
+/** @typedef {{status: "frozen", plansDir: string, planPath: string, contractPath: string, approved: boolean, findings: PlanFindingOutput[], warnings: string[]}} FrozenPipelineResult */
 /** @typedef {{status: "contested", plansDir: string, planPath: string, findings: PlanFindingOutput[], round: number}} ContestedPipelineResult */
 
 /**
@@ -75,13 +80,13 @@ export const DEFAULT_NODE_BUDGET_MS = 600_000;
 const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
 
 /**
- * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, launch: LaunchFn, wait: WaitFn}} options
+ * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, launch: LaunchFn, wait: WaitFn}} options
  * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
  */
 export async function runPlanningPipeline(options) {
   const {
     specPath, campaignId, phase, runtimes, launch, wait,
-    reviewRounds = 2, runtimeDefaults = {},
+    reviewRounds = 2, runtimeDefaults = {}, verification = {},
   } = options;
   const approveBelow = /** @type {ApproveBelow} */ (options.approveBelow ?? "standard");
   if (!APPROVE_BELOW_VALUES.has(approveBelow)) throw new TypeError(`approveBelow must be one of ${[...APPROVE_BELOW_VALUES].join(", ")}`);
@@ -171,8 +176,18 @@ export async function runPlanningPipeline(options) {
   const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath });
   /** @type {PlanOutput|null} */
   let plan = null;
+  // Everything still open against the plan in hand, accumulated across rounds
+  // rather than replaced by each one: a reviewer who does not repeat the last
+  // round's objection has not answered it. `unresolvedFindings` is what takes
+  // a finding back out once the plan moved under it.
   /** @type {PlanFindingOutput[]} */
   let findings = [];
+  // The writes the most recent revise dropped, computed where the revise's
+  // output is validated and held for the next round: merged in there, after
+  // the review's own findings, so a drop is never cleaned away by a fresh
+  // review passing over a plan that no longer declares the write.
+  /** @type {PlanFindingOutput[]} */
+  let droppedWrites = [];
   try {
     plan = validatePlanOutput(draft.output.plan);
   } catch (error) {
@@ -222,7 +237,7 @@ export async function runPlanningPipeline(options) {
    * `stage` as it goes; see the declaration above.
    *
    * @param {PlanOutput} currentPlan
-   * @returns {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}}
+   * @returns {AssembledPlan}
    */
   const assembleFrozenNodes = (currentPlan) => {
     stage = "sizing";
@@ -247,16 +262,19 @@ export async function runPlanningPipeline(options) {
 
   /**
    * The raw contract exactly as `freezePlan` will assemble and validate it,
-   * schemaVersion and contractVersion included. `validateContract` never
+   * schemaVersion and contractVersion included. It takes the whole assembly
+   * rather than its nodes because the contract carries a run-level conclusion
+   * of sizing's too (`maxParallel`), and the in-round pre-flight must validate
+   * the same bytes the freeze writes. `validateContract` never
    * reads the path it is given — only `dirname(resolve(contractPath))` to
    * resolve `raw.cwd` — so the pre-flight passes the path the contract will
    * occupy, `contract.json` inside `plansDir`, and validates in memory
    * without writing or deleting anything.
    *
-   * @param {JsonObject[]} nodes
+   * @param {AssembledPlan} assembly
    * @returns {JsonObject}
    */
-  const frozenContractRaw = (nodes) => ({
+  const frozenContractRaw = ({ sizing, nodes }) => ({
     schemaVersion: PROTOCOL_SCHEMA_VERSION,
     contractVersion: CONTRACT_VERSION,
     id: `${campaignId}-${phase}`,
@@ -266,8 +284,20 @@ export async function runPlanningPipeline(options) {
     // `cwd` has to point back at the repo root from there, exactly like
     // `runStage` computes it for the nodes it writes under `plansDir/nodes/`.
     cwd: relative(plansDir, cwd) || ".",
+    // Sizing's `parallelisable` conclusion, which nothing else carries: a
+    // contract node has no `parallel` field, so a plan that says nothing here
+    // freezes at the validator's default of 1 and every independent node it
+    // proved waits for its turn. What the engine does with the number is the
+    // scheduler's business; declaring it is this stage's.
+    maxParallel: provenParallelism(sizing.plan),
     runtimes,
     runtimeDefaults,
+    // 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 } : {}),
     nodes,
   });
 
@@ -281,7 +311,11 @@ export async function runPlanningPipeline(options) {
       /** @type {PlanFindingOutput|null} */
       let invalidFindings = null;
       try {
-        findings = validateFindings(review.output.findings);
+        // Merged over what is still open, never substituted for it: a round's
+        // reviewer grades the plan in front of it and may simply not mention
+        // an objection the last round raised, which a plain assignment here
+        // threw away.
+        findings = mergeFindings(findings, validateFindings(review.output.findings));
       } catch (error) {
         // The review said nothing usable about the plan, so the plan cannot be
         // treated as clean: the malformed-output finding is critical and
@@ -291,7 +325,7 @@ export async function runPlanningPipeline(options) {
         findings = [...findings, invalidFindings];
       }
       // The contract this plan would freeze into is checked here, inside the
-      // round and after the review's findings replaced the previous round's,
+      // round and after the review's findings merged into the open ones,
       // because freeze runs after the last one: caught here, a plan that
       // cannot freeze still has a revise left to fix it. The failure is a
       // critical finding, never an auto-filled acknowledgement — scope
@@ -301,7 +335,7 @@ export async function runPlanningPipeline(options) {
       /** @type {PlanFindingOutput|null} */
       let freezeFailure = null;
       try {
-        validateContract(frozenContractRaw(assembleFrozenNodes(plan).nodes), join(plansDir, "contract.json"));
+        validateContract(frozenContractRaw(assembleFrozenNodes(plan)), join(plansDir, "contract.json"));
       } catch (error) {
         freezeFailure = invalidPlanFinding(`freeze-r${round}`, error);
         findings = [...findings, freezeFailure];
@@ -315,6 +349,12 @@ export async function runPlanningPipeline(options) {
         ...(invalidFindings === null ? {} : { invalid: invalidFindings.text }),
       });
     }
+    // The revise's write-drops land here — after the review above, before the
+    // critical check below — so a drop survives into the same
+    // revise-or-contest decision a review finding reaches. Merged by id: a
+    // drop the last round already carried and this revise made again is one
+    // finding, not two.
+    findings = mergeFindings(findings, droppedWrites);
     const criticalFindings = findings.filter((finding) => finding.severity === "critical");
     if (criticalFindings.length === 0) break;
     if (round === reviewRounds) return await contest(round);
@@ -323,6 +363,9 @@ export async function runPlanningPipeline(options) {
     const revise = await runStage("revise", {
       specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),
     });
+    // Kept for the write-drop comparison: the plan the revise revised, against
+    // the plan it produced.
+    const planBeforeRevise = plan;
     /** @type {PlanFindingOutput|null} */
     let invalid = null;
     try {
@@ -334,7 +377,21 @@ export async function runPlanningPipeline(options) {
       plan = null;
       findings = [...findings, invalid];
     }
-    logStage("revise", { round, runId: revise.contract.id, ...(invalid === null ? {} : { invalid: invalid.text }) });
+    // Null when the revise output was refused: there is no revised write set
+    // to compare, and the refused-output finding already drives the round.
+    droppedWrites = droppedWriteFindings(planBeforeRevise, plan);
+    // What the next round starts from: the findings this revise did not move
+    // the plan under. Everything else — a node it changed, a node it removed,
+    // and the pipeline's own shape findings, which the next round re-derives
+    // — is dropped here rather than carried forever.
+    findings = unresolvedFindings(findings, planBeforeRevise, plan);
+    logStage("revise", {
+      round,
+      runId: revise.contract.id,
+      droppedWrites: droppedWrites.length,
+      carriedFindings: findings.length,
+      ...(invalid === null ? {} : { invalid: invalid.text }),
+    });
   }
   // Reached only when no review round is configured (reviewRounds <= 0) and
   // the draft never validated: no revise exists to reach, so contested is the
@@ -346,18 +403,26 @@ export async function runPlanningPipeline(options) {
   // `nearly` is what this whole phase is about: an unanticipated failure
   // writes its stage line and takes the contested exit instead of leaving
   // pipeline.jsonl stopping between stages.
-  /** @type {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}|undefined} */
+  /** @type {AssembledPlan|undefined} */
   let assembled;
   /** @type {import("./freeze.mjs").FrozenPlan|undefined} */
   let frozen;
   /** @type {string|undefined} */
   let highestRiskTier;
+  // Warned at freeze, never refused: a plan for a repository with no ratchets
+  // 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
+    ? []
+    : ["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 {
     assembled = assembleFrozenNodes(plan);
     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 });
     highestRiskTier = highestOf(assembled.sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
-    frozen = freezePlan(frozenContractRaw(assembled.nodes), {
+    frozen = freezePlan(frozenContractRaw(assembled), {
       outDir: plansDir,
       provenance: {
         targetGitHead: repoFacts.gitHead,
@@ -367,7 +432,7 @@ export async function runPlanningPipeline(options) {
         findings,
       },
     });
-    logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier });
+    logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier, ...(freezeWarnings.length ? { warnings: freezeWarnings } : {}) });
   } catch (error) {
     // The stage line the pipeline would otherwise have stopped short of, the
     // failure carried as the critical finding that names it, and the
@@ -416,7 +481,7 @@ export async function runPlanningPipeline(options) {
   }
   logStage("approval", { approved, approveBelow, highestRiskTier });
 
-  return { status: "frozen", plansDir, planPath, contractPath: join(plansDir, "contract.json"), approved, findings };
+  return { status: "frozen", plansDir, planPath, contractPath: join(plansDir, "contract.json"), approved, findings, warnings: freezeWarnings };
 }
 
 /**
@@ -435,6 +500,25 @@ function repoRelativePath(cwd, path, label) {
   return relativePath;
 }
 
+/**
+ * The prefix `validateContract` throws its scope-closure refusal with
+ * (src/contract/index.mjs owns the wording). Matched here because the only
+ * channel the validator has is its message text, and that text is carried
+ * verbatim — the finding below appends to it, never rewrites it.
+ */
+const SCOPE_CLOSURE_MESSAGE_PREFIX = "task packet scope does not close";
+
+/**
+ * The one sentence about scope closure the validator cannot know: the raw
+ * message reads as "declare or acknowledge", and removing a write clears it
+ * just as well — more cheaply, in fact, since fewer writes drag in fewer
+ * importers and no judgement about which importer breaks. Measured
+ * 2026-09-20 across three plans for one node: a revise took exactly that
+ * cheap move, twice, and two workers then refused their packets with
+ * context_missing for a file the shrink had taken away.
+ */
+const SCOPE_CLOSURE_RESOLUTION = "Resolve it by declaring each named file in writeFiles — or acknowledging it in scopeAcknowledged when the node must not change it — never by dropping a write the node needs: removing a file from writeFiles clears this failure too, and leaves the worker without a file the work requires.";
+
 /**
  * A validatePlanOutput, validateFindings or in-round validateContract
  * rejection, shaped as the finding a review round already carries to revise,
@@ -442,7 +526,9 @@ function repoRelativePath(cwd, path, label) {
  * or a plan that would not survive freeze — reaches the stage that can act on
  * it instead of killing the pipeline between the run finishing and its stage
  * line. `nodeId` is "plan" because the validator's message names a path into
- * the plan, not one of its nodes.
+ * the plan, not one of its nodes. A scope-closure failure carries
+ * `SCOPE_CLOSURE_RESOLUTION` after the validator's verbatim message, which
+ * stays intact because it names the exact paths the reviser must act on.
  *
  * @param {string} label
  * @param {unknown} error
@@ -450,7 +536,114 @@ function repoRelativePath(cwd, path, label) {
  */
 function invalidPlanFinding(label, error) {
   const text = error instanceof Error ? error.message : String(error);
-  return { id: `plan-shape-${label}`, severity: "critical", nodeId: "plan", text };
+  const guided = text.startsWith(SCOPE_CLOSURE_MESSAGE_PREFIX) ? `${text} ${SCOPE_CLOSURE_RESOLUTION}` : text;
+  return { id: `plan-shape-${label}`, severity: "critical", nodeId: "plan", text: guided };
+}
+
+/**
+ * `incoming` merged over `carried`, keyed by finding id. A finding both
+ * rounds raise is the newer reviewer's own re-judgement of the same
+ * objection, severity included, so it replaces the carried copy instead of
+ * duplicating it — this merge never rewrites a severity of its own. Carried
+ * findings keep their order and come first, so the oldest outstanding
+ * objection is at the top of the file the reviser reads.
+ *
+ * @param {PlanFindingOutput[]} carried
+ * @param {PlanFindingOutput[]} incoming
+ * @returns {PlanFindingOutput[]}
+ */
+function mergeFindings(carried, incoming) {
+  const merged = new Map(carried.map((finding) => [finding.id, finding]));
+  for (const finding of incoming) merged.set(finding.id, finding);
+  return [...merged.values()];
+}
+
+/**
+ * The findings still open against the plan a revise produced. A review round
+ * is under no obligation to repeat what the last one found, so replacing the
+ * finding set each round silently drops any objection the new reviewer is
+ * quiet about: a spike run froze a plan carrying a defect round 1 had named
+ * and round 2 did not repeat, and the worker refused the packet with
+ * context_missing.
+ *
+ * What counts as resolved is read off the two plans, never off the reviewer's
+ * silence. A finding whose node the revise removed is moot. A finding whose
+ * node the revise changed at all was acted on — the next review grades the
+ * changed node and can object again in its own words. A finding against a
+ * node the revise left identical was not addressed, and stays open. That rule
+ * is also what keeps a carried finding from making convergence impossible:
+ * every one of them clears the moment the reviser touches the node it names,
+ * so a plan that answers its objections still freezes inside the round
+ * budget, and a plan that does not still ends contested at it. A finding
+ * naming no node of the plan — the pipeline's own `nodeId: "plan"` shape and
+ * freeze failures — is re-derived from scratch by the next round's pre-flight,
+ * so carrying it would double it.
+ *
+ * @param {PlanFindingOutput[]} findings everything open at the end of the round
+ * @param {PlanOutput|null} previousPlan the plan the revise revised
+ * @param {PlanOutput|null} revisedPlan the plan the revise produced, null when its output was refused
+ * @returns {PlanFindingOutput[]}
+ */
+export function unresolvedFindings(findings, previousPlan, revisedPlan) {
+  // No revised plan to measure against: the refused-output finding drives the
+  // next round and everything raised so far is still outstanding.
+  if (!revisedPlan) return findings;
+  const before = new Map((previousPlan?.nodes ?? []).map((node) => [node.id, stableJson(node)]));
+  const after = new Map(revisedPlan.nodes.map((node) => [node.id, stableJson(node)]));
+  return findings.filter((finding) => after.has(finding.nodeId) && before.get(finding.nodeId) === after.get(finding.nodeId));
+}
+
+/**
+ * The write files the plan going into a revise declared that the revised plan
+ * no longer declares, one finding per (node id, path). This is the check the
+ * scope-closure validator cannot make: a shrink satisfies closure without a
+ * judgement about any importer, so the cheap move needs a comparator of its
+ * own. Severity is critical — a drop is not automatically wrong, but it is
+ * always worth a second look, and only a critical finding reaches the round
+ * loop's revise-or-contest decision; major would ride along in the findings
+ * file while the plan froze. Nodes are matched by id alone: a node the
+ * revision renamed or removed entirely is out of scope, because tracking
+ * identity across a rename is a judgement about the graph this check does
+ * not make — a removed node's writes were reviewed as a removal, not as a
+ * silent shrink.
+ *
+ * Membership is judged against the whole revised plan, not against the node
+ * that used to hold the path. A revise that splits one node in two and hands
+ * a file to the new sibling has not dropped that file: it is still declared,
+ * still reviewable, and the graph change is visible in the plan. Measured
+ * 2026-09-21 on durable-state-integrity phase 1, where a per-node test made
+ * exactly that move a critical and contested a sound plan — the draft's only
+ * node wrote src/repo/worktree.mjs and src/engine/cancel.mjs, and the revise
+ * layered them into worktree-preserve-ref-verb and
+ * cancel-preserves-integrated-heads, which is the decomposition this
+ * repository's own layering asks for.
+ *
+ * @param {PlanOutput|null} previousPlan the plan the revise revised, null when the draft never validated
+ * @param {PlanOutput|null} revisedPlan the plan the revise produced, null when its output was refused
+ * @returns {PlanFindingOutput[]}
+ */
+export function droppedWriteFindings(previousPlan, revisedPlan) {
+  if (!previousPlan || !revisedPlan) return [];
+  const before = new Map(previousPlan.nodes.map((node) => [node.id, new Set(node.writeFiles)]));
+  const stillDeclared = new Set(revisedPlan.nodes.flatMap((node) => node.writeFiles));
+  /** @type {PlanFindingOutput[]} */
+  const findings = [];
+  for (const node of revisedPlan.nodes) {
+    const previousWrites = before.get(node.id);
+    if (!previousWrites) continue;
+    let dropped = 0;
+    for (const path of previousWrites) {
+      if (stillDeclared.has(path)) continue;
+      dropped += 1;
+      findings.push({
+        id: `dropped-write-${node.id}-${dropped}`,
+        severity: "critical",
+        nodeId: node.id,
+        text: `Node ${node.id} no longer declares ${path} in writeFiles, which the plan this revise revised did declare, and no other node in the revised plan declares it either. Declare it again on whichever node owns the work: the resolution to a scope-closure finding is to declare or acknowledge the dragged-along file, never to drop a write the node needs — a smaller write set clears the same finding while leaving the worker unable to do the work. Moving the file to another node is a resolution; removing it from the plan is not.`,
+      });
+    }
+  }
+  return findings;
 }
 
 /**

package/src/plan/repo-facts.mjs

@@ -19,6 +19,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { timeVerificationCommands } from "../host/preflight.mjs";
 import { NOTIFY_BIN_ENV } from "../notify/index.mjs";
+import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
 
 /** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
@@ -45,6 +46,7 @@ const MEASURE_OUTPUT_CAP_BYTES = 4096;
  */
 const MEASURE_SIDE_EFFECT_ENV_KEYS = [
   NOTIFY_BIN_ENV,
+  NOTIFY_SESSION_ENV,
   "FABERUN_CODEX_BIN",
   "FABERUN_CLAUDE_BIN",
   "FABERUN_AGY_BIN",