faberun 0.30.0 → 0.32.0

package/src/plan/human-step.mjs

@@ -5,6 +5,16 @@
  * freeze.mjs can carry it on the frozen plan as an explicit stop, and the
  * Campaign Brief can list it among the human decisions. Pure text matching:
  * no file I/O, no git, no model.
+ *
+ * The same module owns the other thing only an operator can do, because it
+ * is the same boundary at a different source: a packet refusal the failure
+ * classifier named `ambiguous_requirement` (R5, campaign-efficiency phase 4)
+ * is not repairable by widening the packet — the requirement itself can be
+ * read more than one way — so it becomes a durable question
+ * (`durableQuestion`) the run carries until `resume --answer <node>` closes
+ * it, instead of another widening attempt. The source is the run's failure
+ * journal, not the spec's constraints; the discipline is unchanged: pure
+ * record shaping, no file I/O, no git, no model.
  */
 
 /** @typedef {{requirementId: string, step: string, command: string}} HumanStep */
@@ -36,3 +46,29 @@ export function collectHumanSteps(requirements) {
     .map((requirement) => detectHumanStep(requirement))
     .filter((step) => step !== null);
 }
+
+/** @typedef {{node: string, artifactVersion: string, question: string}} DurableQuestion */
+
+/**
+ * The durable question an ambiguous-requirement refusal becomes. Null for
+ * every other cause: a read or write gap is the packet's own defect and a
+ * widening round can repair it, but an ambiguity is a property of the
+ * requirement the packet was written from, and no widening of read or write
+ * scope can answer it — another attempt would re-read the same prose.
+ *
+ * The question names the node and the packet version it refuses so the
+ * operator's answer is bound to the same key the failure journal uses: a
+ * widened packet changes the version, and with it the question.
+ *
+ * @param {{cause: string, node: string, artifactVersion: string}} record a
+ *   failureCause record as the reauthor journal writes it
+ * @returns {DurableQuestion|null}
+ */
+export function durableQuestion(record) {
+  if (record.cause !== "ambiguous_requirement") return null;
+  return {
+    node: record.node,
+    artifactVersion: record.artifactVersion,
+    question: `Node ${record.node} refused its packet at ${record.artifactVersion} with cause ambiguous_requirement: the requirement can be read more than one way, and no widening of the packet can answer it. Decide what the requirement means, then resume with --answer ${record.node}; no reauthor round and no further attempt runs on this packet version until then.`,
+  };
+}

package/src/plan/pipeline.mjs

@@ -25,13 +25,12 @@ import { readCampaign } from "../campaign/record.mjs";
 import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl } from "../run/store.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
-import { askPlanningRuntimes, refusePlanningSilence, refuseUnplannableRuntimes } from "./preflight.mjs";
+import { askPlanningRuntimes, checkPlanBeforeReview, refusePlanningSilence, refuseUnplannableRuntimes } from "./preflight.mjs";
 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 { collectRepoFacts, persistRepoFacts } from "./repo-facts.mjs";
+import { abandonedPlanProgress, clearPlanProgress, startDraftPlan, writePlanDraftRecord, writePlanProgress } from "./progress.mjs";
 import { collectHumanSteps } from "./human-step.mjs";
 import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validatePlanOutput } from "./template.mjs";
 import { MIN_WRITE_FILES, applySizingRules, provenParallelism } from "./sizing.mjs";
@@ -159,6 +158,12 @@ async function runPlanningStages(options) {
   // the home, and the scratch relay inside the repository is excluded by the
   // same pathspec the launch uses.
   assertLaunchBaseClean(cwd, undefined);
+  // The refusal half of the pre-flight, decided from the catalogue and the
+  // machine alone and returned before anything is dispatched, so a runtime
+  // choice no frozen contract could carry costs no model call: it runs before
+  // the liveness ask below because that ask is itself a provider invocation,
+  // and everything a plan can still get wrong is a finding for the repair
+  // loop rather than a refusal.
   refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode, judgeIndependence);
   refusePlanningSilence(await ask(runtimes, runtimeDefaults, cwd), cwd);
 
@@ -202,6 +207,8 @@ async function runPlanningStages(options) {
   // the draft stage reads what the planner measured instead of inferring it
   // from the spec's prose.
   const parsedSpec = parseSpec(specText);
+  // Sampled before this pipeline's own first liveness write (repo facts) overwrites it.
+  const abandoned = abandonedPlanProgress(cwd, campaignId, phase);
   // 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
@@ -217,8 +224,12 @@ async function runPlanningStages(options) {
   // here so both the freeze below and a caller inspecting the pipeline agree
   // on the same list.
   const humanSteps = collectHumanSteps(parsedSpec.requirements);
-  const repoFactsPath = join(scratchDir, "repo-facts.json");
-  writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
+  // The draft and review stages read the cut through `readFiles`, and the
+  // complete path index is staged beside it rather than inside it: the
+  // artefact stays byte-bounded, and a discovery node explicitly authorised to
+  // enumerate the tree is handed `repo-paths.txt` instead of a cut that lies
+  // about what the tree holds (R4).
+  const repoFactsPath = persistRepoFacts(scratchDir, repoFacts, cwd);
   const relativeRepoFactsPath = relative(cwd, repoFactsPath);
   // The taskKind catalogue is staged like every other planning input. It used
   // to be handed over as faberun's own `src/plan/template.mjs`, which resolves
@@ -278,7 +289,13 @@ async function runPlanningStages(options) {
     return { contract: validated, output };
   };
 
-  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode });
+  // R2 resume: the sampled record survives only a process that died, and a
+  // dead attempt that validated its draft left writePlanDraftRecord's file
+  // behind. A finished phase — frozen or contested — has a plan.json, and that drafts fresh.
+  const draft = await startDraftPlan({
+    abandoned, plansDir, specDigest, runStage, logStage,
+    draftStageInput: { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode },
+  });
   /** @type {PlanOutput|null} */
   let plan = null;
   // Everything still open against the plan in hand, accumulated across rounds
@@ -288,23 +305,16 @@ async function runPlanningStages(options) {
   /** @type {PlanFindingOutput[]} */
   let findings = [];
   try {
-    plan = validatePlanOutput(draft.output.plan);
+    plan = validatePlanOutput(draft.planOutput);
   } catch (error) {
     findings = [invalidPlanFinding("draft", error)];
   }
-  logStage("draft", plan === null
-    ? { runId: draft.contract.id, invalid: findings[0].text }
-    : { runId: draft.contract.id, nodeCount: plan.nodes.length });
-
-  // R15: a deterministic check for a DoD proof no node can satisfy, run once
-  // against the drafted plan before the first review round grades it — a
-  // finding this raises is exactly as actionable to a revise as a reviewer's
-  // own, and raising it before review means review never spends a round
-  // re-discovering what a mechanical check already knows for certain.
-  if (plan !== null) {
-    const proofFindings = checkPlanProofs(plan, repoFacts, cwd);
-    if (proofFindings.length > 0) findings = [...findings, ...proofFindings];
-    logStage("proof-check", { findingsCount: proofFindings.length });
+  if (!draft.resumed) {
+    // Durable before its stage line: a death in between leaves an adoptable draft.
+    if (plan !== null) writePlanDraftRecord(plansDir, { runId: draft.runId, at: new Date().toISOString(), specDigest, plan });
+    logStage("draft", plan === null
+      ? { runId: draft.runId, invalid: findings[0].text }
+      : { runId: draft.runId, nodeCount: plan.nodes.length });
   }
 
   const workingPlanPath = join(scratchDir, "plan.working.json");
@@ -364,8 +374,29 @@ async function runPlanningStages(options) {
    */
   const frozenContractRaw = (assembly) => frozenContractRawOf(assembly, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, judgeIndependence });
 
+  // R5: the complete deterministic check set — the freeze rules `freeze.mjs`
+  // and `proof-scope.mjs` apply, plus the plan-wide proof scan (R15) — runs
+  // here, before the first semantic review is dispatched, and its diagnostics
+  // are forwarded into the round loop as findings: a mechanical objection is
+  // then answered by the same revise a reviewer's objection is, inside the
+  // rounds `--review-rounds` already pays for, never by a refusal path of its
+  // own. The plan it hands on is the repaired one, so the artefact the
+  // reviewer reads is the artefact that freezes. A failure the freeze itself
+  // would raise is logged here and raised as a finding by the round loop's own
+  // copy of this check, in the same round and under the round's own id: one
+  // objection, one finding, one repair.
+  if (plan !== null) {
+    const checks = checkPlanBeforeReview(plan, { repoFacts, cwd, plansDir, assembleFrozenNodes, frozenContractRaw });
+    plan = checks.plan;
+    if (checks.raised.length > 0) logStage("timeouts-raised", { raised: checks.raised });
+    if (checks.declared.length > 0) logStage("guards-declared", { declared: checks.declared });
+    findings = [...findings, ...checks.findings];
+    logStage("proof-check", { findingsCount: checks.findings.length });
+    logStage("preflight", { raised: checks.raised.length, declared: checks.declared.length, ...(checks.failure === null ? {} : { failed: checks.failure instanceof Error ? checks.failure.message : String(checks.failure) }) });
+  }
+
   const roundsResult = await runReviewRounds({
-    reviewRounds, plan, rejectedDraft: plan === null ? draft.output.plan : undefined, findings, cwd, plansDir, scratchDir, workingPlanPath, relativeWorkingPlanPath,
+    reviewRounds, plan, rejectedDraft: plan === null ? draft.planOutput : undefined, findings, cwd, plansDir, scratchDir, workingPlanPath, relativeWorkingPlanPath,
     relativeSpecPath, relativeRepoFactsPath, relativeCataloguePath, packageMode, repoFacts,
     runStage, assembleFrozenNodes, frozenContractRaw, contest,
     invalidPlanFinding, logStage,

package/src/plan/preflight.mjs

@@ -1,17 +1,93 @@
 /**
- * The ask `faberun plan` makes before its first stage.
+ * What `faberun plan` decides before it spends anything: the refusals it
+ * returns before the first stage is dispatched -- which runtimes a planning run
+ * will spend, and what counts as one of them not answering -- and the
+ * deterministic checks a plan passes before any semantic review grades it.
  *
- * It lives beside the pipeline rather than inside it because asking is its own
- * concern -- which runtimes a planning run will spend, and what counts as one
- * of them not answering -- and because `pipeline.mjs` sits 45 lines from this
- * tree's 800-line ceiling.
+ * Both halves live beside the pipeline rather than inside it because asking
+ * and checking are their own concerns, and because `pipeline.mjs` sits close
+ * to this tree's 800-line ceiling.
  */
+import { join } from "node:path";
 import { preflightRuntimes } from "../engine/live-preflight.mjs";
 import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { harnessCapabilities } from "../harnesses/index.mjs";
+import { validateContract } from "../contract/index.mjs";
 import { assertRuntimeExecutesCommands, validateRuntime } from "../contract/runtime.mjs";
 import { effectiveProvider } from "../contract/provider.mjs";
 import { SAME_VENDOR_REVIEW_MODE, sameVendorTierRefusal } from "../contract/judge-independence.mjs";
+import { assertTimeoutsCoverMeasured, raiseTimeoutsToMeasured } from "./freeze.mjs";
+import { assertFilteredProofsNameTheirTest, declareDirectoryGuards } from "./proof-scope.mjs";
+import { checkPlanProofs } from "./proof-check.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("./pipeline.mjs").AssembledPlan} AssembledPlan */
+
+/**
+ * What the deterministic checks need: the measured repository facts the freeze
+ * rules read, the cwd and plansDir the contract is assembled against, and the
+ * two closures that render the plan the way `freezePlan` will. They are
+ * supplied rather than imported because they are the pipeline's own assembly
+ * (`pipeline.mjs` imports this module), and taking them as data is what lets
+ * `rounds.mjs` — and a test — run the checks with fakes.
+ *
+ * @typedef {{repoFacts: import("./repo-facts.mjs").RepoFacts, cwd: string, plansDir: string, assembleFrozenNodes: (plan: PlanOutput) => AssembledPlan, frozenContractRaw: (assembly: AssembledPlan) => JsonObject}} PlanCheckContext
+ */
+
+/**
+ * The two mechanically repairable freeze rules, applied, then the freeze
+ * contract itself validated the way `freeze.mjs` and `proof-scope.mjs`
+ * validate it: the rules are imported, never restated, so this cannot drift
+ * from the freeze it stands in front of.
+ *
+ * It does not throw. A plan the checks refuse is a diagnostic for the repair
+ * loop, not a refusal: the refusal is the pre-dispatch half of this module,
+ * and a thrown plan check would spend a round's budget twice — once on the
+ * revise that answers a finding, and once on the error that killed it.
+ *
+ * The failure is returned beside the repaired plan rather than instead of it,
+ * so the caller can hand the plan on to a review (or to the freeze) while
+ * still recording what the freeze would have said.
+ *
+ * @param {PlanOutput} plan
+ * @param {PlanCheckContext} ctx
+ * @returns {{plan: PlanOutput, raised: string[], declared: string[], failure: unknown|null}}
+ */
+export function freezePreflight(plan, ctx) {
+  const timeouts = raiseTimeoutsToMeasured(plan, ctx.repoFacts);
+  const guards = declareDirectoryGuards(timeouts.plan, ctx.repoFacts, ctx.cwd);
+  const candidate = guards.plan;
+  const repaired = { plan: candidate, raised: timeouts.raised, declared: guards.declared };
+  try {
+    const contract = validateContract(ctx.frozenContractRaw(ctx.assembleFrozenNodes(candidate)), join(ctx.plansDir, "contract.json"));
+    assertFilteredProofsNameTheirTest(contract);
+    assertTimeoutsCoverMeasured(contract, ctx.repoFacts);
+    return { ...repaired, failure: null };
+  } catch (error) {
+    return { ...repaired, failure: error };
+  }
+}
+
+/**
+ * The complete deterministic check set a plan passes before any semantic
+ * review begins: `freezePreflight` plus the plan-wide proof scan, whose two
+ * shapes (a name filter that selects no test, a bare grep proving an absence)
+ * no reviewer decides better than a local read. The pipeline runs this once on
+ * the draft and forwards `findings` into the round loop's own repair budget —
+ * the rounds `--review-rounds` already pays for — while the loop runs
+ * `freezePreflight` on every candidate it grades, where the repair it drives
+ * is the answer to whatever the check refused.
+ *
+ * @param {PlanOutput} plan
+ * @param {PlanCheckContext} ctx
+ * @returns {{plan: PlanOutput, raised: string[], declared: string[], findings: PlanFindingOutput[], failure: unknown|null}}
+ */
+export function checkPlanBeforeReview(plan, ctx) {
+  const checks = freezePreflight(plan, ctx);
+  return { ...checks, findings: checkPlanProofs(checks.plan, ctx.repoFacts, ctx.cwd) };
+}
 
 /**
  * The runtimes a planning run will spend, asked once before its first stage.

package/src/plan/progress.mjs

@@ -19,12 +19,24 @@
  * 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.
+ *
+ * The module also holds the record of what a dead attempt finished:
+ * `writePlanDraftRecord` persists the validated draft plan beside the phase's
+ * plan artifacts, and `resumablePlanDraft` reads it back for a resumed
+ * attempt, because the liveness record says that the attempt died but not
+ * what its death had already paid for. `startDraftPlan` decides, for one
+ * attempt, between adopting that draft and dispatching the draft stage —
+ * dispatching stays the pipeline's verb (it is passed in), but whether to
+ * dispatch at all is this module's question. Same boundary, same reader —
+ * all of it answers a later launch's one question, what did the last attempt
+ * leave behind.
  */
-import { rmSync } from "node:fs";
+import { existsSync, 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";
+import { validatePlanOutput } from "./template.mjs";
 
 /** @typedef {{pid?: number, processStartToken?: string|null, at?: string, stage?: string, [key: string]: unknown}} PlanProgressRecord */
 
@@ -99,3 +111,91 @@ export function abandonedPlanProgress(cwd, campaignId, phase) {
 export function clearPlanProgress(cwd, campaignId, phase) {
   rmSync(planProgressPath(cwd, campaignId, phase), { force: true });
 }
+
+/** The file beside a phase's plan artifacts holding the draft a resumed attempt can adopt. */
+const PLAN_DRAFT_FILE = "draft.json";
+
+/**
+ * The validated draft a later attempt can adopt without paying for it again.
+ *
+ * @typedef {{runId: string, at: string, specDigest: string, plan: import("./template.mjs").PlanOutput}} PlanDraftRecord
+ */
+
+/**
+ * Persist the validated draft plan where a later launch of the same phase
+ * finds it: beside the phase's durable plan artifacts, never in the disposable
+ * scratch tree, for the same reason the progress record is there — a record a
+ * later launch has to find cannot live where the next `plan` may wipe. The
+ * record is written once, when the draft validates, and never removed: a
+ * frozen or contested phase writes `plan.json` beside it, and the presence of
+ * that file is what stops a later attempt from adopting anything.
+ *
+ * @param {string} plansDir
+ * @param {PlanDraftRecord} record
+ * @returns {void}
+ */
+export function writePlanDraftRecord(plansDir, record) {
+  writeJsonAtomic(join(plansDir, PLAN_DRAFT_FILE), record);
+}
+
+/**
+ * The dead attempt's draft, when adopting it costs no paid call, or null when
+ * there is nothing to adopt. Two records must agree before anything is
+ * adopted: `abandoned` — the progress record above, sampled by the caller
+ * before its own first liveness write, which would otherwise overwrite the
+ * evidence of the death it is about to resume from — and the draft record
+ * `writePlanDraftRecord` wrote when the dead attempt validated its draft. The
+ * plan in it is exactly the paid work a resumed attempt would otherwise
+ * duplicate. A phase that ever finished, frozen or contested, has a
+ * `plan.json` beside the record: that file, not the record's absence, is
+ * what makes a later deliberate re-plan draft fresh. A record from a
+ * different spec (the operator edited the spec between attempts) or one
+ * whose plan no longer validates is refused the same way.
+ *
+ * @param {{abandoned: PlanProgressRecord|null, plansDir: string, specDigest: string}} options
+ * @returns {{runId: string, plan: import("./template.mjs").PlanOutput}|null}
+ */
+export function resumablePlanDraft({ abandoned, plansDir, specDigest }) {
+  if (abandoned === null) return null;
+  if (existsSync(join(plansDir, "plan.json"))) return null;
+  let record;
+  try {
+    record = /** @type {PlanDraftRecord|unknown} */ (readJson(join(plansDir, PLAN_DRAFT_FILE)));
+  } catch {
+    // An absent record is the ordinary case: a draft still running, or a
+    // death before the draft validated, leaves nothing to adopt.
+    return null;
+  }
+  if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+  const draft = /** @type {PlanDraftRecord} */ (record);
+  if (draft.specDigest !== specDigest || typeof draft.runId !== "string") return null;
+  try {
+    return { runId: draft.runId, plan: validatePlanOutput(draft.plan) };
+  } catch {
+    // The record's plan no longer validates: adopting it would spend the
+    // round budget repairing an unknown shape, so the caller drafts fresh.
+    return null;
+  }
+}
+
+/**
+ * The draft one attempt starts from: the dead attempt's validated plan when
+ * adopting it costs no paid call, or a fresh dispatch of the draft stage.
+ * The adoption is announced as its own stage line — a resumed attempt that
+ * dispatched nothing must still leave the same record a drafting one does.
+ *
+ * @param {{abandoned: PlanProgressRecord|null, plansDir: string, specDigest: string,
+ *   draftStageInput: Record<string, unknown>,
+ *   runStage: (kind: import("./template.mjs").PlanningKind, input: Record<string, unknown>) => Promise<{contract: {id: string}, output: Record<string, unknown>}>,
+ *   logStage: (stage: string, detail: Record<string, unknown>) => void}} options
+ * @returns {Promise<{runId: string, planOutput: unknown, resumed: boolean}>}
+ */
+export async function startDraftPlan({ abandoned, plansDir, specDigest, draftStageInput, runStage, logStage }) {
+  const resumed = resumablePlanDraft({ abandoned, plansDir, specDigest });
+  if (resumed !== null) {
+    logStage("draft-resumed", { runId: resumed.runId, nodeCount: resumed.plan.nodes.length });
+    return { runId: resumed.runId, planOutput: resumed.plan, resumed: true };
+  }
+  const stage = await runStage("draft", draftStageInput);
+  return { runId: stage.contract.id, planOutput: stage.output.plan, resumed: false };
+}