faberun 0.12.0 → 0.13.0

package/src/plan/pipeline.mjs

@@ -4,15 +4,16 @@
  * (sizing, routing, freeze), never as one long-lived process. Separate from
  * `template.mjs` (which only builds the one-node contracts) and from
  * `freeze.mjs` (which only turns a plan into a validated contract on disk):
- * this module is the one place that sequences those runs, decides when a
- * plan is contested instead of frozen, and records the operator-approval
- * open-question. `launch` and `wait` are the only two seams that touch a
+ * 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.
  */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { validateContract } from "../contract/index.mjs";
+import { CONTRACT_VERSION, DEFAULT_MAX_TURNS, PROTOCOL_SCHEMA_VERSION, validateContract } from "../contract/index.mjs";
 import { discoveryOutput } from "../contract/worker-result.mjs";
 import { readWorkerResultFile } from "../engine/result-file.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
@@ -24,7 +25,7 @@ import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/a
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
 import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.mjs";
-import { applySizingRules } from "./sizing.mjs";
+import { MIN_WRITE_FILES, applySizingRules } from "./sizing.mjs";
 import { resolveRuntimes } from "./routing.mjs";
 import { freezePlan } from "./freeze.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
@@ -155,90 +156,230 @@ export async function runPlanningPipeline(options) {
     const progress = await wait(runDir);
     const classification = classifyRunProgress(progress);
     if (classification !== "succeeded") {
+      logStage(kind, { runId: validated.id, failed: classification });
       throw new Error(`planning stage ${kind} did not succeed: run ${validated.id} ${classification}`);
     }
     const result = readWorkerResultFile(runDir, kind);
     const output = result ? discoveryOutput(result) : null;
-    if (!output) throw new Error(`planning stage ${kind}: run ${validated.id} recorded no discovery output`);
+    if (!output) {
+      logStage(kind, { runId: validated.id, failed: "no_discovery_output" });
+      throw new Error(`planning stage ${kind}: run ${validated.id} recorded no discovery output`);
+    }
     return { contract: validated, output };
   };
 
   const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath });
-  let plan = validatePlanOutput(draft.output.plan);
-  logStage("draft", { runId: draft.contract.id, nodeCount: plan.nodes.length });
+  /** @type {PlanOutput|null} */
+  let plan = null;
+  /** @type {PlanFindingOutput[]} */
+  let findings = [];
+  try {
+    plan = validatePlanOutput(draft.output.plan);
+  } 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 });
 
   const workingPlanPath = join(scratchDir, "plan.working.json");
-  writeJsonAtomic(workingPlanPath, plan);
   const relativeWorkingPlanPath = relative(cwd, workingPlanPath);
 
-  /** @type {PlanFindingOutput[]} */
-  let findings = [];
-  for (let round = 1; round <= reviewRounds; round += 1) {
-    const review = await runStage("review", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, planPath: relativeWorkingPlanPath });
-    findings = validateFindings(review.output.findings);
+  /**
+   * End the pipeline the way an unresolvable plan already ends: the contested
+   * result, the outstanding findings that forced it, and an open question on
+   * the campaign journal. Every no-valid-plan exit funnels through here.
+   *
+   * @param {number} round
+   * @returns {Promise<ContestedPipelineResult>}
+   */
+  const contest = async (round) => {
     const criticalFindings = findings.filter((finding) => finding.severity === "critical");
-    logStage("review", { round, runId: review.contract.id, findingsCount: findings.length, criticalCount: criticalFindings.length });
-    if (criticalFindings.length === 0) break;
-    if (round === reviewRounds) {
-      const planPath = join(plansDir, "plan.json");
-      writeJsonAtomic(planPath, { formatVersion: 1, status: "contested", rounds: round, findings });
-      logStage("contested", { round, criticalCount: criticalFindings.length });
-      await campaignCli([
-        "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
-        "--kind", "open-question", "--question-id", `plan-${phase}-contested`,
-        "--text", `Plan for phase ${phase} is contested after ${round} review round(s): ${criticalFindings.map((finding) => finding.text).join("; ")}`,
-      ]);
-      return { status: "contested", plansDir, planPath, findings, round };
-    }
-    const findingsPath = join(scratchDir, `findings-round-${round}.json`);
-    writeJsonAtomic(findingsPath, findings);
-    const revise = await runStage("revise", {
-      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),
-    });
-    plan = validatePlanOutput(revise.output.plan);
-    writeJsonAtomic(workingPlanPath, plan);
-    logStage("revise", { round, runId: revise.contract.id });
-  }
+    const planPath = join(plansDir, "plan.json");
+    writeJsonAtomic(planPath, { formatVersion: 1, status: "contested", rounds: round, findings });
+    logStage("contested", { round, criticalCount: criticalFindings.length });
+    await campaignCli([
+      "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
+      "--kind", "open-question", "--question-id", `plan-${phase}-contested`,
+      "--text", `Plan for phase ${phase} is contested after ${round} review round(s): ${criticalFindings.map((finding) => finding.text).join("; ")}`,
+    ]);
+    return { status: "contested", plansDir, planPath, findings, round };
+  };
 
-  const sizing = applySizingRules(
-    { nodes: plan.nodes.map(toSizingNode), justification: plan.justification },
-    { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts },
-  );
-  logStage("sizing", { transformations: sizing.transformations.length, nodeCount: sizing.plan.nodes.length });
-
-  const routingRuntimes = /** @type {Record<string, import("./routing.mjs").RoutingRuntime>} */ (runtimes);
-  const routing = resolveRuntimes(sizing.plan.nodes, {
-    table: [...DEFAULT_ROUTING_TABLE],
-    runtimes: routingRuntimes,
-    availability: availabilityOf(runtimes),
-    runtimeDefaults,
-  });
-  logStage("routing", { assignments: Object.keys(routing.assignments).length });
+  // Which deterministic stage is running, advanced by `assembleFrozenNodes`
+  // so the freeze-wrap catch below names the stage that threw.
+  let stage = "sizing";
+  // The last review round entered, so the freeze-wrap catch contests with
+  // the count of rounds that actually ran.
+  let roundsRun = 0;
+
+  /**
+   * The one assembly a plan freezes through, one home for the expression the
+   * in-round pre-flight and the final freeze must run identically: sizing
+   * reshapes the drafted nodes, routing assigns worker and judge, and
+   * `toContractNode` renders the contract shape. Local and cheap — no I/O,
+   * no model — so running it once per round costs nothing. It advances
+   * `stage` as it goes; see the declaration above.
+   *
+   * @param {PlanOutput} currentPlan
+   * @returns {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}}
+   */
+  const assembleFrozenNodes = (currentPlan) => {
+    stage = "sizing";
+    const sizing = applySizingRules(
+      { nodes: currentPlan.nodes.map(toSizingNode), justification: currentPlan.justification },
+      { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts, minWriteFiles: MIN_WRITE_FILES, turnCeiling: DEFAULT_MAX_TURNS },
+    );
+    stage = "routing";
+    const routing = resolveRuntimes(sizing.plan.nodes, {
+      table: [...DEFAULT_ROUTING_TABLE],
+      runtimes: /** @type {Record<string, import("./routing.mjs").RoutingRuntime>} */ (runtimes),
+      availability: availabilityOf(runtimes),
+      runtimeDefaults,
+    });
+    stage = "freeze";
+    return {
+      sizing,
+      routing,
+      nodes: sizing.plan.nodes.map((node) => toContractNode(/** @type {SizedPlanNode} */ (node), phase, routing.assignments[node.id])),
+    };
+  };
 
-  const highestRiskTier = highestOf(sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
-  const nodes = sizing.plan.nodes.map((node) => toContractNode(/** @type {SizedPlanNode} */ (node), phase, routing.assignments[node.id]));
-  const frozen = freezePlan({
+  /**
+   * The raw contract exactly as `freezePlan` will assemble and validate it,
+   * schemaVersion and contractVersion included. `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
+   * @returns {JsonObject}
+   */
+  const frozenContractRaw = (nodes) => ({
+    schemaVersion: PROTOCOL_SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
     id: `${campaignId}-${phase}`,
     campaignId,
     goal: campaign.goal,
-    // `freezePlan` writes contract.json inside `outDir` (`plansDir`), so `cwd`
-    // has to point back at the repo root from there, exactly like `runStage`
-    // computes it for the nodes it writes under `plansDir/nodes/`.
+    // `freezePlan` writes contract.json inside `outDir` (`plansDir`), so
+    // `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) || ".",
     runtimes,
     runtimeDefaults,
     nodes,
-  }, {
-    outDir: plansDir,
-    provenance: {
-      targetGitHead: repoFacts.gitHead,
-      planner: { runtimeId: runtimeDefaults.worker ?? "", model: modelOf(runtimes, runtimeDefaults.worker) },
-      reviewer: { runtimeId: runtimeDefaults.judge ?? "", model: modelOf(runtimes, runtimeDefaults.judge) },
-      sizing: sizing.transformations,
-      findings,
-    },
   });
-  logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier });
+
+  for (let round = 1; round <= reviewRounds; round += 1) {
+    roundsRun = round;
+    if (plan) {
+      // The reviewer grades a structurally valid plan; an invalid one skips
+      // review and reaches revise through the validator's finding instead.
+      writeJsonAtomic(workingPlanPath, plan);
+      const review = await runStage("review", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, planPath: relativeWorkingPlanPath });
+      /** @type {PlanFindingOutput|null} */
+      let invalidFindings = null;
+      try {
+        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
+        // drives the same revise-or-contest path a real critical finding does,
+        // with the still-outstanding findings riding along.
+        invalidFindings = invalidPlanFinding(`review-r${round}`, error);
+        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,
+      // 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
+      // closure exists to force the per-file decision (declare a write, or
+      // acknowledge a read-only importer), and the revise worker, which can
+      // read the repository, makes it from the validator's own message.
+      /** @type {PlanFindingOutput|null} */
+      let freezeFailure = null;
+      try {
+        validateContract(frozenContractRaw(assembleFrozenNodes(plan).nodes), join(plansDir, "contract.json"));
+      } catch (error) {
+        freezeFailure = invalidPlanFinding(`freeze-r${round}`, error);
+        findings = [...findings, freezeFailure];
+      }
+      logStage("review", {
+        round,
+        runId: review.contract.id,
+        findingsCount: findings.length,
+        criticalCount: findings.filter((finding) => finding.severity === "critical").length,
+        ...(freezeFailure === null ? {} : { freezeFailed: freezeFailure.text }),
+        ...(invalidFindings === null ? {} : { invalid: invalidFindings.text }),
+      });
+    }
+    const criticalFindings = findings.filter((finding) => finding.severity === "critical");
+    if (criticalFindings.length === 0) break;
+    if (round === reviewRounds) return await contest(round);
+    const findingsPath = join(scratchDir, `findings-round-${round}.json`);
+    writeJsonAtomic(findingsPath, findings);
+    const revise = await runStage("revise", {
+      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),
+    });
+    /** @type {PlanFindingOutput|null} */
+    let invalid = null;
+    try {
+      plan = validatePlanOutput(revise.output.plan);
+    } catch (error) {
+      // The revise output was rejected wholesale, so the round's review
+      // findings are still outstanding and ride along to the next round.
+      invalid = invalidPlanFinding(`revise-r${round}`, error);
+      plan = null;
+      findings = [...findings, invalid];
+    }
+    logStage("revise", { round, runId: revise.contract.id, ...(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
+  // end rather than a silent crash at sizing.
+  if (plan === null) return await contest(0);
+
+  // The pre-flight ran this exact assembly through the same validator in the
+  // round that just broke, so a failure here is nearly impossible — but
+  // `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} */
+  let assembled;
+  /** @type {import("./freeze.mjs").FrozenPlan|undefined} */
+  let frozen;
+  /** @type {string|undefined} */
+  let highestRiskTier;
+  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), {
+      outDir: plansDir,
+      provenance: {
+        targetGitHead: repoFacts.gitHead,
+        planner: { runtimeId: runtimeDefaults.worker ?? "", model: modelOf(runtimes, runtimeDefaults.worker) },
+        reviewer: { runtimeId: runtimeDefaults.judge ?? "", model: modelOf(runtimes, runtimeDefaults.judge) },
+        sizing: assembled.sizing.transformations,
+        findings,
+      },
+    });
+    logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier });
+  } 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
+    // contested end every other unresolvable plan takes.
+    logStage(stage, { failed: error instanceof Error ? error.message : String(error) });
+    findings = [...findings, invalidPlanFinding(stage, error)];
+    // freezePlan removes contract.json itself when validation refuses it; a
+    // failure after that write and before its return would otherwise leave a
+    // contract.json no contested result may have.
+    rmSync(join(plansDir, "contract.json"), { force: true });
+    return await contest(roundsRun);
+  }
 
   // A delta only means something between two samples of the same seat: freeze
   // re-samples the exact harness `campaign init` recorded at `sample: "start"`
@@ -294,6 +435,24 @@ function repoRelativePath(cwd, path, label) {
   return relativePath;
 }
 
+/**
+ * A validatePlanOutput, validateFindings or in-round validateContract
+ * rejection, shaped as the finding a review round already carries to revise,
+ * so a structurally invalid plan, a review whose findings are not findings —
+ * 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.
+ *
+ * @param {string} label
+ * @param {unknown} error
+ * @returns {PlanFindingOutput}
+ */
+function invalidPlanFinding(label, error) {
+  const text = error instanceof Error ? error.message : String(error);
+  return { id: `plan-shape-${label}`, severity: "critical", nodeId: "plan", text };
+}
+
 /**
  * Every declared runtime treated as available. Live discovery (probing a
  * harness for real exhaustion) is a separate concern this pipeline does not
@@ -342,10 +501,12 @@ function toSizingNode(node) {
     taskKind: node.taskKind,
     riskTier: node.riskTier,
     objective: node.objective,
+    expectedTurns: node.expectedTurns,
     definitionOfDone: node.definitionOfDone,
     taskPacket: {
       readFiles: node.readFiles,
       writeFiles: node.writeFiles,
+      scopeAcknowledged: node.scopeAcknowledged,
       verification: node.verification,
     },
   });
@@ -383,6 +544,10 @@ function toContractNode(node, phase, assignment) {
       instructions: [node.objective],
       readFiles: node.taskPacket.readFiles ?? [],
       writeFiles: node.taskPacket.writeFiles ?? [],
+      // Carried, never computed here: the drafter decided which importers it
+      // will not change, and scope closure exists to force that decision on a
+      // person rather than answer it for them (src/repo/scope-closure.mjs).
+      scopeAcknowledged: node.taskPacket.scopeAcknowledged ?? [],
       symbols: [],
       decisions: [],
       nonGoals: [],

package/src/plan/template.mjs

@@ -8,8 +8,14 @@
  * accepts, from exactly the inputs each role may see. The reviewer's packet
  * is the enforced case: it carries the spec, the repository facts and the
  * artefact under review, never the author's packet, transcript or summary.
+ *
+ * The plan output validator also owns requirement traceability: a plan
+ * declares, per phase, the requirement ids it satisfies and its one-sentence
+ * deliverable, and a phase associated with no requirement is reported as a
+ * finding — never a silent pass, never a refusal. freeze.mjs imports the same
+ * phase check for the frozen plan record.
  */
-import { assertObject, rejectUnknown, requireId, requireString, requireStringArray } from "../contract/assert.mjs";
+import { assertObject, positiveInteger, rejectUnknown, requireId, requireString, requireStringArray } from "../contract/assert.mjs";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../contract/index.mjs";
 import { validateDefinitionOfDone } from "../contract/definition-of-done.mjs";
 import { validateVerificationCommands } from "../contract/verification.mjs";
@@ -18,8 +24,9 @@ import { validateVerificationCommands } from "../contract/verification.mjs";
 /** @typedef {"draft"|"review"|"revise"|"spec-author"|"spec-review"} PlanningKind */
 /** @typedef {"low"|"standard"|"high"} RiskTier */
 /** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, specPath?: string, repoFactsPath?: string, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
-/** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[]}} PlanOutputNode */
-/** @typedef {{nodes: PlanOutputNode[], justification?: string}} PlanOutput */
+/** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], scopeAcknowledged: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[], expectedTurns?: number}} PlanOutputNode */
+/** @typedef {{nodes: PlanOutputNode[], phases?: PlanPhase[], findings?: PlanFindingOutput[], justification?: string}} PlanOutput */
+/** @typedef {{id: string, requirementIds: string[], deliverable: string}} PlanPhase */
 /** @typedef {{id: string, severity: "critical"|"major"|"minor", nodeId: string, text: string}} PlanFindingOutput */
 
 /**
@@ -62,9 +69,35 @@ const REQUIRED_INPUTS = Object.freeze({
   "spec-review": ["specPath"],
 });
 
-const PLAN_OUTPUT_SHAPE = "{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, definitionOfDone, verification}], justification?}";
+// The nested shapes are spelled from DefinitionOfDoneItem
+// (contract/definition-of-done.mjs) and VerificationCommand
+// (contract/verification.mjs), never from prose: observed 2026-09-20, bare
+// field names made a worker guess — a DoD item with no id, a `command` string
+// where argv belongs — and the guess failed validatePlanOutput only after the
+// run had already succeeded. The id charset is requireId's
+// (contract/assert.mjs) verbatim, because an id that is present but invalid
+// fails that same validator just as late.
+const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds?: [string], deliverable}], justification?}; every id in it (node, phase, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
+/**
+ * The size guidance every draft and revise carries. measured 2026-09-20 over
+ * stored runs: median 49 provider requests per worker turn; cost per turn
+ * nearly independent of the write set; 14.5 minutes of verification, judge
+ * and integration per node outside its worker turn; an attempt is cut at
+ * 150 requests.
+ */
+const SIZING_INSTRUCTION = "Size nodes to 4 to 6 write files where the work allows, and give every node an expectedTurns: the provider requests one worker needs to finish it end to end (measured median 49 for 4 to 6 files). A smaller node pays the same orientation and about 15 minutes of verification, judge and integration for less delivered work; a node you expect past 150 requests must be split, because a run cuts an attempt there.";
 const FINDINGS_SHAPE = "[{id, severity, nodeId, text}]";
 
+// The rule every planned packet is held to at freeze time, worded from
+// AGENTS.md's Faberun protocol and src/repo/scope-closure.mjs ("reading it
+// cannot fix it"): a first draft that ignores it produces a plan that fails
+// the pipeline's in-round contract check a round later than a draft that
+// could have written the write set honestly.
+const SCOPE_CLOSURE_RULE = Object.freeze([
+  "Each node's writeFiles lists what the change forces to change, not only what it intends to: the importers a written module drags along, the schema validator for a field the node adds, the registry that field is recorded in, and any reader the node's own instructions tell the worker to touch.",
+  "Scope closure refuses a task packet whose transitive imports reach an undeclared file, so an importer the change breaks belongs in writeFiles or scopeAcknowledged — readFiles only permits reading, and a broken importer can only be repaired by a write.",
+]);
+
 /** @type {Record<PlanningKind, string>} */
 const OBJECTIVES = Object.freeze({
   draft: "Draft an execution plan for this phase: classify every node's taskKind and riskTier from the spec and the repository facts, and propose the dependency graph.",
@@ -78,14 +111,19 @@ const OBJECTIVES = Object.freeze({
 const INSTRUCTIONS = Object.freeze({
   draft: [
     `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies and the deliverable it produces in one sentence. A phase associated with no requirement is reported as a finding, not refused.",
+    ...SCOPE_CLOSURE_RULE,
     `Return exactly one worker-result JSON object. Put the plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
     "Never name a runtime, harness, model, or vendor anywhere in output.plan. taskKind and riskTier are the only classification a draft makes; a routing table assigns a runtime afterward, from those two fields alone.",
+    SIZING_INSTRUCTION,
   ],
   revise: [
     "Read the findings and resolve every one; do not leave a critical or major finding unaddressed.",
-    `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies and the deliverable it produces in one sentence. A phase associated with no requirement is reported as a finding, not refused.",
+    ...SCOPE_CLOSURE_RULE,
     `Return exactly one worker-result JSON object. Put the revised plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
     "Never name a runtime, harness, model, or vendor anywhere in output.plan.",
+    SIZING_INSTRUCTION,
   ],
   review: [
     "You are given only the spec, the repository facts, and the plan under review; you have not seen how the plan was produced or any reasoning behind it. Review the artefact alone.",
@@ -187,13 +225,15 @@ export function buildPlanningContract(kind, inputs) {
   };
 }
 
-const PLAN_FIELDS = new Set(["nodes", "justification"]);
-const PLAN_NODE_FIELDS = new Set(["id", "objective", "taskKind", "riskTier", "dependsOn", "readFiles", "writeFiles", "definitionOfDone", "verification"]);
+const PLAN_FIELDS = new Set(["nodes", "phases", "justification"]);
+const PLAN_NODE_FIELDS = new Set(["id", "objective", "taskKind", "riskTier", "dependsOn", "readFiles", "writeFiles", "scopeAcknowledged", "definitionOfDone", "verification", "expectedTurns"]);
 
 /**
  * Validate a draft or revise worker's `output.plan`. Rejects a node naming a
  * runtime, harness, model, or vendor (an unknown field, since a plan node's
- * shape never includes one) and a node missing taskKind or riskTier.
+ * shape never includes one) and a node missing taskKind or riskTier. A
+ * declared phase associated with no requirement is reported as a finding on
+ * the result, never a silent pass and never a refusal.
  *
  * @param {unknown} plan
  * @returns {PlanOutput}
@@ -224,8 +264,17 @@ export function validatePlanOutput(plan) {
     requireStringArray(readFiles, `${label}.readFiles`);
     const writeFiles = nodeRecord.writeFiles ?? [];
     requireStringArray(writeFiles, `${label}.writeFiles`);
+    // A node that reaches an importer it must not change says so here. Without
+    // this field the drafter is told (INSTRUCTIONS, draft/revise) to answer a
+    // scope-closure finding with `writeFiles or scopeAcknowledged` and has no
+    // way to say the second, so the only expressible answer is the wrong one:
+    // declaring a read-only importer writable. Measured 2026-09-20 -- a revise
+    // round could not resolve the finding the preflight had just raised.
+    const scopeAcknowledged = nodeRecord.scopeAcknowledged ?? [];
+    requireStringArray(scopeAcknowledged, `${label}.scopeAcknowledged`);
     const definitionOfDone = validateDefinitionOfDone(nodeRecord.definitionOfDone ?? [], `${label}.definitionOfDone`);
     const verification = validateVerificationCommands(nodeRecord.verification ?? [], `${label}.verification`);
+    const expectedTurns = nodeRecord.expectedTurns === undefined ? undefined : positiveInteger(nodeRecord.expectedTurns, `${label}.expectedTurns`);
     return /** @type {PlanOutputNode} */ ({
       id: /** @type {string} */ (nodeRecord.id),
       objective: /** @type {string} */ (nodeRecord.objective),
@@ -234,17 +283,70 @@ export function validatePlanOutput(plan) {
       dependsOn: /** @type {string[]} */ (dependsOn),
       readFiles: /** @type {string[]} */ (readFiles),
       writeFiles: /** @type {string[]} */ (writeFiles),
+      scopeAcknowledged: /** @type {string[]} */ (scopeAcknowledged),
       definitionOfDone,
       verification,
+      ...(expectedTurns === undefined ? {} : { expectedTurns }),
     });
   });
   if (record.justification !== undefined) requireString(record.justification, "plan.justification");
+  const phases = validatePlanPhases(record.phases);
+  const findings = (phases ?? [])
+    .filter((phase) => phase.requirementIds.length === 0)
+    .map((phase) => /** @type {PlanFindingOutput} */ ({
+      id: `no-requirement-${phase.id}`,
+      // minor, not major: a support phase with no direct requirement is a
+      // question for review, not a defect — the finding exists so the gap is
+      // never silent.
+      severity: "minor",
+      nodeId: phase.id,
+      text: `Phase ${phase.id} is associated with no requirement: fill requirementIds with the R<n> ids from the spec that it satisfies, or fold it into a phase that does.`,
+    }));
   return {
     nodes,
+    ...(phases === undefined ? {} : { phases }),
+    ...(findings.length > 0 ? { findings } : {}),
     ...(record.justification === undefined ? {} : { justification: /** @type {string} */ (record.justification) }),
   };
 }
 
+// The fields a phase declaration carries beyond its id: requirementIds|deliverable —
+// which spec requirements the phase satisfies, and the one sentence naming its result.
+const PLAN_PHASE_FIELDS = new Set(["id", "requirementIds", "deliverable"]);
+
+/**
+ * Validate a plan's `phases` — the per-phase requirement declarations: the
+ * requirement ids (R<n> from the spec) each phase satisfies and the
+ * deliverable it produces in one sentence. Absent, empty, and requirement-less
+ * are legal here: a support phase with no requirement is the caller's finding
+ * to report (validatePlanOutput does), so the gap stays visible without a
+ * malformed-but-honest plan being refused. Shared with freeze.mjs, which holds
+ * the same declarations on the frozen plan record.
+ *
+ * @param {unknown} phases
+ * @returns {PlanPhase[]|undefined} the normalized declarations, or undefined when none were given
+ */
+export function validatePlanPhases(phases) {
+  if (phases === undefined) return undefined;
+  if (!Array.isArray(phases)) throw new TypeError("plan.phases must be an array of phase declarations");
+  if (phases.length === 0) return undefined;
+  return phases.map((phase, index) => {
+    const label = `plan.phases[${index}]`;
+    assertObject(phase, label);
+    const record = /** @type {Record<string, unknown>} */ (phase);
+    rejectUnknown(record, PLAN_PHASE_FIELDS, label);
+    requireId(record.id, `${label}.id`);
+    requireString(record.deliverable, `${label}.deliverable`);
+    const requirementIds = record.requirementIds ?? [];
+    requireStringArray(requirementIds, `${label}.requirementIds`);
+    return {
+      id: /** @type {string} */ (record.id),
+      requirementIds: /** @type {string[]} */ (requirementIds),
+      deliverable: /** @type {string} */ (record.deliverable),
+    };
+  });
+}
+
 const FINDING_FIELDS = new Set(["id", "severity", "nodeId", "text"]);
 const FINDING_SEVERITIES = new Set(["critical", "major", "minor"]);
 

package/src/run/operations.mjs

@@ -12,7 +12,7 @@ import { basename, join } from "node:path";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 
-import { readBoundedTail } from "../engine/process.mjs";
+import { readBoundedTail } from "../engine/transcript.mjs";
 import { readJson, writeJsonAtomic } from "./store.mjs";
 import { runtimeSnapshot } from "../engine/failover.mjs";
 import { normalizeProviderResult } from "../harnesses/index.mjs";

package/src/run/usage.mjs

@@ -10,9 +10,10 @@ import { appendJsonl, writeJsonAtomic } from "./store.mjs";
 import { basename, join } from "node:path";
 import { errorMessage, stableJson } from "../util.mjs";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { liveUsage } from "../harnesses/exec-jsonl/index.mjs";
+import { liveUsage } from "../harnesses/session-metrics.mjs";
 
-import { priceUsage, readBoundedTail } from "../engine/process.mjs";
+import { priceUsage } from "../engine/process.mjs";
+import { readBoundedTail, sessionLedger } from "../engine/transcript.mjs";
 import { writeNode } from "../engine/state.mjs";
 import { normalizeProviderResult } from "../harnesses/index.mjs";
 
@@ -80,8 +81,12 @@ export function recordInvocationUsage(job, options = {}) {
   // the single priced object every later copy spreads from.
   const priced = priceUsage(job.runtime, envelope.usage, envelope.costUsd);
   envelope = { ...envelope, costUsd: priced.costUsd, costProvenance: priced.costProvenance };
+  // The per-request ledger is read here, with the usage, for the same reason
+  // the usage is: after this point the transcript may already be capped.
+  const session = sessionLedger(job);
+  job.invocation.session = session;
   state.invocations = (state.invocations ?? []).map((invocation) => invocation.id === job.invocation.id
-    ? { ...invocation, usage: envelope.usage, costUsd: envelope.costUsd, costProvenance: envelope.costProvenance }
+    ? { ...invocation, usage: envelope.usage, costUsd: envelope.costUsd, costProvenance: envelope.costProvenance, session }
     : invocation);
   if (options.accumulate !== false) state.usage = addUsage(state.usage, envelope.usage);
   return envelope;
@@ -158,6 +163,7 @@ export function appendUsageRecord(runDir, invocation) {
     // A persisted `priced` marker wins; otherwise the pre-Phase-4 rule applies
     // unchanged: a reported number is `provider`, absence is `unknown`.
     costProvenance: invocation.costProvenance ?? (typeof invocation.costUsd === "number" ? "provider" : "unknown"),
+    session: invocation.session ?? null,
     startedAt: invocation.startedAt ?? null,
     finishedAt: invocation.closedAt ?? null,
   });