faberun 0.29.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/campaign/campaign-brief.mjs

@@ -45,8 +45,14 @@ import { projectCampaignDecisions } from "./projection.mjs";
 /** @typedef {import("./campaign-brief-graph.mjs").BriefGraph} BriefGraph */
 /** @typedef {{status: "range"|"insufficient data", min: number|null, max: number|null, samples: number|null, reason: string|null, sourceRuns: string[], method: string|null, provenance: string|null}} BriefMeasure */
 /** @typedef {{status?: "range"|"insufficient data", min?: number|null, max?: number|null, samples?: number|null, reason?: string|null, sourceRuns?: string[], method?: string|null, provenance?: string|null}} BriefMeasureInput */
-/** @typedef {{cost?: BriefMeasureInput, duration?: BriefMeasureInput, runtimes?: string[], models?: string[], effectiveConcurrency?: number, nodeCount?: number, workerCount?: number, sampleCutoff?: string|null, method?: string[], assumptions?: string[]}} BriefEstimateInput */
-/** @typedef {{cost: BriefMeasure, duration: BriefMeasure, runtimes: string[], models: string[], effectiveConcurrency: number, nodeCount: number, workerCount: number, sampleCutoff: string|null, method: string[], assumptions: string[], gaps: string[]}} BriefEstimate */
+/** @typedef {{cost?: BriefMeasureInput, costPerAccepted?: BriefMeasureInput, duration?: BriefMeasureInput, runtimes?: string[], models?: string[], effectiveConcurrency?: number, nodeCount?: number, workerCount?: number, sampleCutoff?: string|null, method?: string[], assumptions?: string[]}} BriefEstimateInput */
+/**
+ * `costPerAccepted` is optional because models built before the measure
+ * existed (test fixtures, older snapshots) may omit it: the renderer and the
+ * decision gate treat an absent measure as unrecorded evidence, never as a
+ * crash. `buildEstimate` itself always records it.
+ * @typedef {{cost: BriefMeasure, costPerAccepted?: BriefMeasure, duration: BriefMeasure, runtimes: string[], models: string[], effectiveConcurrency: number, nodeCount: number, workerCount: number, sampleCutoff: string|null, method: string[], assumptions: string[], gaps: string[]}} BriefEstimate
+ */
 /** @typedef {{measure: string, target: string, evidence: string}} BriefSuccessCriterion */
 /** @typedef {{risk: string, impact: string, mitigation: string}} BriefRisk */
 /** @typedef {{intent: string|null, expectedOutcome: string|null, successCriteria: BriefSuccessCriterion[], humanFacts: string[], calculatedFacts: string[], gaps: string[]}} BriefOpening */
@@ -193,9 +199,11 @@ export function buildBriefModel(options) {
 
 /**
  * `gaps to resolve` when the coverage matrix, the work graph or the opening's
- * source facts report a gap, or when either estimate measure lacks its required
+ * source facts report a gap, or when any estimate measure lacks its required
  * evidence; otherwise `ready for human review`. Neither state approves
- * execution.
+ * execution. Cost per accepted result is an estimate measure like cost and
+ * duration: without it the brief cannot support an outcome-vs-price-tag
+ * comparison (phase-4 R5), so it gates readiness the same way.
  *
  * @param {{opening: BriefOpening, coverage: BriefCoverage, graph: BriefGraph, decisions: BriefDecisions, estimate: BriefEstimate}} model
  * @returns {BriefDecisionState}
@@ -205,7 +213,7 @@ export function decideBriefState(model) {
   if (model.graph.gaps.length > 0) return "gaps to resolve";
   if (model.decisions.gaps.length > 0) return "gaps to resolve";
   if (model.opening.gaps.length > 0) return "gaps to resolve";
-  if (model.estimate.cost.status !== "range" || model.estimate.duration.status !== "range") return "gaps to resolve";
+  if (model.estimate.cost.status !== "range" || model.estimate.costPerAccepted?.status !== "range" || model.estimate.duration.status !== "range") return "gaps to resolve";
   return "ready for human review";
 }
 
@@ -492,16 +500,19 @@ function normalizeDecisionText(text) {
  */
 function buildEstimate(input, graph, sampleCutoff) {
   const cost = normalizeMeasure(input?.cost, "cost");
+  const costPerAccepted = normalizeMeasure(input?.costPerAccepted, "cost per accepted result");
   const duration = normalizeMeasure(input?.duration, "duration");
   /** @type {string[]} */
   const gaps = [];
   if (cost.status !== "range") gaps.push(`cost estimate reports insufficient data: ${cost.reason ?? "no reason recorded"}`);
+  if (costPerAccepted.status !== "range") gaps.push(`cost per accepted result estimate reports insufficient data: ${costPerAccepted.reason ?? "no reason recorded"}`);
   if (duration.status !== "range") gaps.push(`duration estimate reports insufficient data: ${duration.reason ?? "no reason recorded"}`);
   if (typeof sampleCutoff !== "string" || !sampleCutoff.trim()) {
     gaps.push("usage sample cutoff is not recorded");
   }
   return {
     cost,
+    costPerAccepted,
     duration,
     runtimes: unique(input?.runtimes ?? graph.nodes.map((node) => node.runtimeId).filter((id) => id !== null).map(String)),
     models: unique(input?.models ?? graph.nodes.map((node) => node.model).filter((model) => model !== null).map(String)),
@@ -584,7 +595,7 @@ function buildOpening(parsedSpec, coverage, graph, estimate, decisions) {
   const calculatedFacts = [
     `Coverage: ${coverage.covered} covered, ${coverage.uncovered} uncovered, ${coverage.outside} outside this plan, ${coverage.traceabilityMissing} traceability missing of ${coverage.total} spec requirements.`,
     `Work graph: ${graph.nodes.length} nodes, ${graph.edges.length} dependency edges, ${graph.independent.length} dependency-independent, effective concurrency ${graph.effectiveConcurrency} under maxParallel ${graph.maxParallel}.`,
-    `Estimate: cost ${estimate.cost.status}, duration ${estimate.duration.status}; sample cutoff ${estimate.sampleCutoff ?? "not recorded"}.`,
+    `Estimate: cost ${estimate.cost.status}, cost per accepted result ${estimate.costPerAccepted?.status ?? "insufficient data"}, duration ${estimate.duration.status}; sample cutoff ${estimate.sampleCutoff ?? "not recorded"}.`,
   ];
   return { intent, expectedOutcome, successCriteria, humanFacts, calculatedFacts, gaps };
 }

package/src/campaign/chain.mjs

@@ -15,7 +15,17 @@
  * Advancement is `runOutcome`, never node counts: `succeeded` advances,
  * `waiting` is a self-resuming tier exhaustion and is neither advanced nor
  * parked, and `parked`/`canceled` park the campaign with attention. An
- * in-flight run (`state: unfinished`/`unknown`) is awaited, not relaunched.
+ * in-flight run (`state: unfinished`/`unknown`) whose controller is alive is
+ * awaited, not relaunched.
+ *
+ * A run whose controller is gone is the other half of that rule, and the reason
+ * R2 exists: the coordinator used to wait on it forever, so a `run` that died
+ * after its bootstrap held the whole campaign. The chain resumes that same run
+ * through the engine's own `resume` -- it does not re-launch, so no node is
+ * dispatched twice -- bounded by `MAX_RUN_RECOVERY_ATTEMPTS` consecutive resumes
+ * without progress, after which the campaign records attention instead of
+ * retrying. A run carrying a requested pause is never resumed: taking the pause
+ * back is the operator's `resume`, not the chain's.
  *
  * Validation of contract N+1 happens here, at launch, against the `landBranch`
  * N's promotion just advanced. Validating the manifest up front would reject
@@ -24,9 +34,11 @@
  * checked first so tampering between authoring and launch is caught before the
  * branch-aware validation runs.
  *
- * The chain takes no run lock and writes no node state. Its own artifacts are
- * `coordinator.lock`, the campaign `heartbeat.json`, and the campaign attention
- * record. Every run lock and node snapshot belongs to a child controller.
+ * The chain writes no node state and no run metadata of its own. Its own
+ * artifacts are `coordinator.lock`, the campaign `heartbeat.json`, and the
+ * campaign attention record. Every run lock belongs to a controller: the
+ * detached child the chain launched, or the controller `resumeRun` becomes
+ * while the chain waits on it. The one writer of a run's nodes stays the engine.
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -37,7 +49,7 @@ import { readCampaign } from "./record.mjs";
 import { validateContract } from "../contract/index.mjs";
 import { defaultControllerIdentity, storedContractDigest, verifyControllerIdentity } from "../engine/run-identity.mjs";
 import { refuseSelfSignal } from "../engine/process-identity.mjs";
-import { HEARTBEAT_INTERVAL_MS, createHeartbeat, groupAlive, heartbeatBreach, readHeartbeat, runProgress, waitForGroupGone } from "../engine/supervise.mjs";
+import { HEARTBEAT_INTERVAL_MS, MAX_CONSECUTIVE_LAUNCH_FAILURES, controllerAlive, createHeartbeat, groupAlive, heartbeatBreach, readHeartbeat, runProgress, waitForGroupGone } from "../engine/supervise.mjs";
 import { pidAlive, processStartToken } from "../run/lock.mjs";
 import { delay, errorCode, errorMessage } from "../util.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
@@ -64,6 +76,21 @@ export const DEFAULT_COORDINATOR_TERMINATE_GRACE_MS = 5_000;
 /** How long the group gets after `SIGKILL` before the takeover stops waiting. */
 export const DEFAULT_COORDINATOR_KILL_GRACE_MS = 5_000;
 
+/**
+ * How many consecutive resumes of one run the chain starts before it records
+ * attention instead of trying again. The number is `supervise.mjs`'s
+ * `MAX_CONSECUTIVE_LAUNCH_FAILURES`, where the reason is recorded: a run that
+ * refuses to resume refuses forever, and a loop that keeps trying hides that
+ * from the operator.
+ *
+ * The budget is the coordinator invocation's own memory, and it resets the
+ * moment the run's own heartbeat shows progress, so a run that dies repeatedly
+ * over hours is still recovered each time. What has to survive a crash is the
+ * attention written when the budget is spent, and the campaign record carries
+ * that: the next invocation reads it and resumes nothing.
+ */
+export const MAX_RUN_RECOVERY_ATTEMPTS = MAX_CONSECUTIVE_LAUNCH_FAILURES;
+
 /**
  * @param {string} campaignPath
  * @returns {string}
@@ -328,6 +355,68 @@ export function classifyRunProgress(progress) {
   return "unfinished";
 }
 
+/**
+ * The chain's own count of how many resumes it has started for one run since
+ * that run last showed progress, and the reason the last one failed.
+ *
+ * @typedef {{attempts: number, progressAt: string|null, reason: string|null}} RecoveryAttempts
+ */
+
+/**
+ * The decision for one in-flight run whose controller is not alive. This is the
+ * one place the chain may cause work on a run it did not launch, and it is
+ * deliberately narrow: a requested pause is never overridden, the resume is the
+ * engine's own (which takes the run lock, so two controllers cannot both run
+ * the run), the run's own progress resets the budget, and a spent budget ends in
+ * attention rather than in a loop that hides a refusal.
+ *
+ * Returns the attention the campaign parks with, or null when the caller should
+ * keep polling.
+ *
+ * @param {{
+ *   runId: string,
+ *   runDir: string,
+ *   contractPath: string,
+ *   progress: RunProgress,
+ *   attempts: Map<string, RecoveryAttempts>,
+ *   resume: (runDir: string, context: {runId: string, attempt: number}) => Promise<void>|void,
+ *   emit: (line: string) => void,
+ * }} context
+ * @returns {Promise<Omit<CampaignAttention, "at">|null>}
+ */
+async function resumeDeadRun(context) {
+  const { runId, runDir, contractPath, progress, attempts, resume, emit } = context;
+  const first = progress.outcomeNodes?.[0];
+  const naming = { contractPath, contractId: runId, runId, node: first?.id ?? null, status: first?.status ?? "unfinished" };
+  if (existsSync(join(runDir, "cancel.request.json"))) {
+    // Re-checked here and not only in the classification above: an operator can
+    // request the pause between those two reads, and a resume consumes a cancel
+    // request as an instruction to continue, which is exactly what must not
+    // happen to a pause the chain decided to honour.
+    return { ...naming, code: "run_canceled", message: `contract ${runId} run carries a requested pause (cancel.request.json) and no controller; \`faberun resume ${runDir}\` continues it when the operator says so`, resume: `resume ${runDir}` };
+  }
+  const progressAt = readHeartbeat(runDir)?.lastProgressAt ?? null;
+  const previous = attempts.get(runId);
+  // Same rule `supervise.mjs`'s `nextRelaunch` applies to the run-level
+  // supervisor: progress since the last resume is the evidence the recovery
+  // worked, so the budget starts again.
+  const spent = previous && previous.progressAt === progressAt ? previous.attempts : 0;
+  if (spent >= MAX_RUN_RECOVERY_ATTEMPTS) {
+    const reason = previous?.reason ? `; last failure: ${previous.reason}` : "";
+    return { ...naming, code: "run_recovery_exhausted", message: `contract ${runId} run is unfinished with no live controller and ${spent} resume attempts made no progress${reason}; \`faberun resume ${runDir}\` retries it from the operator side`, resume: `resume ${runDir}` };
+  }
+  attempts.set(runId, { attempts: spent + 1, progressAt, reason: null });
+  try {
+    await resume(runDir, { runId, attempt: spent + 1 });
+    emit(`[campaign] resumed run ${runId} · attempt ${spent + 1}/${MAX_RUN_RECOVERY_ATTEMPTS} · ${runDir}`);
+  } catch (error) {
+    const reason = errorMessage(error);
+    attempts.set(runId, { attempts: spent + 1, progressAt, reason });
+    emit(`[campaign] run ${runId} resume failed · attempt ${spent + 1}/${MAX_RUN_RECOVERY_ATTEMPTS} · ${reason}`);
+  }
+  return null;
+}
+
 /**
  * @param {string} contractPath
  * @returns {{id: string, cwd: string, runDir: string}}
@@ -388,6 +477,7 @@ function storedContractId(stored) {
  *   controllerIdentity?: ControllerIdentity,
  *   refreshController?: boolean,
  *   launch?: (contractPath: string, context: {baseRef: string|undefined, controllerIdentity: ControllerIdentity, runDir: string, contract: ValidatedContract}) => Promise<void>|void,
+ *   resume?: (runDir: string, context: {runId: string, attempt: number}) => Promise<void>|void,
  *   validate?: (entry: CampaignContract, context: {repo: string|undefined, baseRef: string|undefined, contractPath: string}) => ValidatedContract,
  *   progress?: (runDir: string) => RunProgress,
  *   heartbeat?: {progress: (nodeId?: string, budgetBasis?: number) => void, setActive: (nodes: {nodeId: string, budgetBasis: number}[]) => void, stop: () => void},
@@ -412,6 +502,16 @@ export async function driveCampaignChain(campaignPath, options = {}) {
   const progressOf = options.progress ?? ((runDir) => runProgress(runDir, now()));
   const validate = options.validate ?? ((entry, context) => validateManifestEntryAtLaunch(entry, context));
   const launch = options.launch ?? (() => { throw new Error("driveCampaignChain requires a launch seam"); });
+  // The resume seam is the engine's own resume by default: it takes the run's
+  // controller lock and verifies the run's recorded identity before dispatching
+  // anything, which is what keeps the chain from becoming a second controller.
+  // The engine is reached lazily because `engine/scheduler.mjs` imports this
+  // module's `validateContractForLaunch`: a static edge from here to
+  // `engine/resume.mjs` would close a runtime import cycle through the chain.
+  const resume = options.resume ?? (async (runDir) => {
+    const { resumeRun } = await import("../engine/resume.mjs");
+    await resumeRun(runDir, {});
+  });
 
   /** @type {{role: "observed"|"took-over"|"became", lock: Record<string, unknown>}|null} */
   let acquired = null;
@@ -437,6 +537,8 @@ export async function driveCampaignChain(campaignPath, options = {}) {
     let validatedIndex = -1;
     /** @type {ValidatedContract|null} */
     let validatedContract = null;
+    /** @type {Map<string, RecoveryAttempts>} */
+    const recovery = new Map();
 
     /** @param {Omit<CampaignAttention, "at">} attention */
     const park = (attention) => {
@@ -542,9 +644,23 @@ export async function driveCampaignChain(campaignPath, options = {}) {
             resume: `resume ${runDir}`,
           });
         }
-        // waiting / unfinished / unknown: the run resumes itself, so await it.
-        // `lastProgressAt` is deliberately not refreshed: a wait is not work,
-        // and a self-resuming tier exhaustion must not look like progress.
+        // A `waiting` run resumes itself at the instant its provider recorded:
+        // it needs no controller before then, and `lastProgressAt` is
+        // deliberately not refreshed, because a wait is not work. Anything else
+        // still in flight is either owned by a live controller -- which is
+        // awaited -- or orphaned, which is resumed here, bounded.
+        if (classification !== "waiting" && !controllerAlive(runDir, { now: now(), heartbeatIntervalMs })) {
+          const attention = await resumeDeadRun({
+            runId: id,
+            runDir,
+            contractPath: entry.path,
+            progress,
+            attempts: recovery,
+            resume,
+            emit,
+          });
+          if (attention) return park(attention);
+        }
         await sleep(pollMs);
         continue;
       }

package/src/campaign/ledger.mjs

@@ -5,7 +5,7 @@
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
-import { readMetricNodeSnapshots } from "./metrics-command.mjs";
+import { isPlanningRun, readMetricNodeSnapshots, stringEntriesOf } from "./metrics-command.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { CAMPAIGN_FILE, JOURNAL_FILE, LEDGER_SOURCE_MANIFEST_FILE, campaignsDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
@@ -79,6 +79,13 @@ export function unpreservedLedgerCampaigns(runsDir) {
  * sources are reported so a pruned run cannot make the close fail or look
  * complete by accident. Repeated calls overwrite the same paths.
  *
+ * The manifest also records which linked runs were planning runs (R5): the
+ * ledger preserves no contracts, so a run that was launched to plan has no
+ * other evidence left of what it was, and the projection reads that list back
+ * to separate planning spend from worker and judge spend. A run recorded as
+ * planning stays recorded, because reledgering a pruned run must not silently
+ * reclassify the usage it already preserved.
+ *
  * `ledgerDir` is the exact destination. It defaults to the versioned ledger
  * under `repoRoot/docs/campaigns/<id>/ledger`; `closeCampaign` passes the
  * campaign directory in the operator home instead when `--ledger-in-repo` was
@@ -104,6 +111,7 @@ export function preserveCampaignLedger(campaignPath, repoRoot, ledgerDir = undef
   const priorManifest = readSourceManifest(ledgerDir);
   const absent = new Set(priorManifest.absent);
   const preserved = new Set(priorManifest.preserved);
+  const planning = new Set(priorManifest.planning);
   for (const name of [JOURNAL_FILE, CAMPAIGN_FILE]) {
     const source = join(campaignPath, name);
     if (!existsSync(source)) continue;
@@ -113,6 +121,7 @@ export function preserveCampaignLedger(campaignPath, repoRoot, ledgerDir = undef
   }
   for (const runId of campaign.linkedRunIds) {
     const runDir = join(runsDir, runId);
+    if (isPlanningRun(runDir)) planning.add(runId);
     for (const [sourceName, destinationSuffix] of RUN_SOURCES) {
       const source = join(runDir, sourceName);
       const destinationName = `${runId}.${destinationSuffix}`;
@@ -150,7 +159,7 @@ export function preserveCampaignLedger(campaignPath, repoRoot, ledgerDir = undef
     written.push(...filesUnder(proposalsSource).map((path) => join(proposalsDestination, path)));
   }
   const manifest = join(ledgerDir, LEDGER_SOURCE_MANIFEST_FILE);
-  writeFileSync(manifest, `${JSON.stringify({ schemaVersion: 1, absent: [...absent].sort(), preserved: [...preserved].sort() })}\n`);
+  writeFileSync(manifest, `${JSON.stringify({ schemaVersion: 1, absent: [...absent].sort(), preserved: [...preserved].sort(), planning: [...planning].sort() })}\n`);
   written.push(manifest);
   // The ledger exists, so a versioned preservation now marks the record. The
   // already-copied campaign.json is refreshed afterwards so the durable copy
@@ -186,8 +195,10 @@ export function reledgerCampaignLedger(campaignPath, repoRoot) {
   const sourceManifest = readSourceManifest(ledgerDir);
   const preserved = new Set(sourceManifest.preserved);
   const absent = new Set(sourceManifest.absent);
+  const planning = new Set(sourceManifest.planning);
   for (const runId of campaign.linkedRunIds) {
     const runDir = join(runsDir, runId);
+    if (isPlanningRun(runDir)) planning.add(runId);
     for (const [sourceName, destinationSuffix] of RUN_SOURCES) {
       const source = join(runDir, sourceName);
       const change = { runId, source: sourceName };
@@ -241,7 +252,7 @@ export function reledgerCampaignLedger(campaignPath, repoRoot) {
   } else if (existsSync(join(campaignPath, CAMPAIGN_FILE))) {
     copyFileSync(join(campaignPath, CAMPAIGN_FILE), ledgerCampaign);
   }
-  writeFileSync(join(ledgerDir, LEDGER_SOURCE_MANIFEST_FILE), `${JSON.stringify({ schemaVersion: 1, absent: [...absent].sort(), preserved: [...preserved].sort() })}\n`);
+  writeFileSync(join(ledgerDir, LEDGER_SOURCE_MANIFEST_FILE), `${JSON.stringify({ schemaVersion: 1, absent: [...absent].sort(), preserved: [...preserved].sort(), planning: [...planning].sort() })}\n`);
   return { ledgerDir, copied, gone };
 }
 
@@ -299,17 +310,18 @@ function projectedField(value, field) {
   return Object.hasOwn(object, "kind") ? { kind: object.kind } : {};
 }
 
-/** @param {string} root @returns {{absent: string[], preserved: string[]}} */
+/** @param {string} root @returns {{absent: string[], preserved: string[], planning: string[]}} */
 function readSourceManifest(root) {
   try {
     const value = JSON.parse(readFileSync(join(root, LEDGER_SOURCE_MANIFEST_FILE), "utf8"));
     return {
-      absent: Array.isArray(value?.absent) ? /** @type {unknown[]} */ (value.absent).filter((entry) => typeof entry === "string") : [],
-      preserved: Array.isArray(value?.preserved) ? /** @type {unknown[]} */ (value.preserved).filter((entry) => typeof entry === "string") : [],
+      absent: stringEntriesOf(value?.absent),
+      preserved: stringEntriesOf(value?.preserved),
+      planning: stringEntriesOf(value?.planning),
     };
   } catch {
     // An old ledger has no origin manifest; its files remain subject to the legacy missing-source rules.
-    return { absent: [], preserved: [] };
+    return { absent: [], preserved: [], planning: [] };
   }
 }
 

package/src/campaign/metrics-command.mjs

@@ -2,6 +2,11 @@
  * Filesystem and command layer for `faberun metrics`. This module owns the
  * command's flags and reads the campaign's run or ledger artefacts, while
  * `metrics.mjs` stays a pure function over parsed records.
+ *
+ * It also answers which of those runs were planning runs, because only a
+ * filesystem read can: a run directory still carries the contract that proves
+ * it, and a versioned ledger carries the classification `preserveCampaignLedger`
+ * recorded, since it preserves no contracts.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -50,6 +55,7 @@ const NOTIFY_LOG_FILE = "notify.jsonl";
  *   journal: unknown[],
  *   campaign: JsonObject,
  *   excludedRunIds: string[],
+ *   planningRunIds?: string[],
  *   missingSources: string[],
  * }} MetricsSources
  */
@@ -78,19 +84,25 @@ export function readMetricsSources(campaignPath, { runsDir = join(campaignPath,
   /** @type {unknown[]} */
   const journal = [];
   /** @type {string[]} */
+  const planningRunIds = [];
+  /** @type {string[]} */
   const missingSources = [];
-  const absentAtOrigin = ledgerDir === undefined ? new Set() : readLedgerAbsentSources(ledgerDir);
+  const ledgerManifest = ledgerDir === undefined
+    ? { absent: /** @type {Set<string>} */ (new Set()), planning: /** @type {Set<string>} */ (new Set()) }
+    : readLedgerManifest(ledgerDir);
   const journalPath = join(ledgerDir ?? campaignPath, "journal.jsonl");
   if (existsSync(journalPath)) journal.push(...readJsonlRecords(journalPath));
   else missingSources.push("journal.jsonl");
   for (const runId of campaign.linkedRunIds) {
     if (ledgerDir === undefined) {
+      if (isPlanningRun(join(runsDir, runId))) planningRunIds.push(runId);
       for (const record of readJsonlRecords(join(runsDir, runId, RUN_EVENTS_FILE))) events.push({ ...jsonObjectOf(record), runId });
       for (const record of readJsonlRecords(join(runsDir, runId, USAGE_LOG_FILE))) usageRecords.push({ ...jsonObjectOf(record), runId });
       for (const record of readJsonlRecords(join(runsDir, runId, NOTIFY_LOG_FILE))) notifications.push({ ...jsonObjectOf(record), runId });
       for (const node of readMetricNodeSnapshots(join(runsDir, runId))) nodes.push({ ...node, runId });
       continue;
     }
+    if (ledgerManifest.planning.has(runId)) planningRunIds.push(runId);
     /** @type {[string, unknown[]][]} */
     const sources = [
       [RUN_EVENTS_FILE, events],
@@ -100,14 +112,14 @@ export function readMetricsSources(campaignPath, { runsDir = join(campaignPath,
     for (const [suffix, target] of sources) {
       const path = join(ledgerDir, `${runId}.${suffix}`);
       if (!existsSync(path)) {
-        if (!absentAtOrigin.has(`${runId}.${suffix}`)) missingSources.push(`${runId}.${suffix}`);
+        if (!ledgerManifest.absent.has(`${runId}.${suffix}`)) missingSources.push(`${runId}.${suffix}`);
         continue;
       }
       for (const record of readJsonlRecords(path)) target.push({ ...jsonObjectOf(record), runId });
     }
     const nodesPath = join(ledgerDir, `${runId}.nodes.json`);
     if (!existsSync(nodesPath)) {
-      if (!absentAtOrigin.has(`${runId}.nodes.json`)) missingSources.push(`${runId}.nodes.json`);
+      if (!ledgerManifest.absent.has(`${runId}.nodes.json`)) missingSources.push(`${runId}.nodes.json`);
       continue;
     }
     for (const node of readLedgerNodeSnapshots(nodesPath)) nodes.push({ ...node, runId });
@@ -123,22 +135,69 @@ export function readMetricsSources(campaignPath, { runsDir = join(campaignPath,
     journal,
     campaign: campaignObject,
     excludedRunIds: excludedRunIdsFor(campaignObject, []),
+    planningRunIds,
     missingSources,
   };
 }
 
-/** @param {string} ledgerDir @returns {Set<string>} */
-function readLedgerAbsentSources(ledgerDir) {
+/**
+ * Whether a run is a planning run: every node of its contract is a discovery
+ * packet, the rule the expense pool already uses to keep planning out of an
+ * execution estimate (`collectCompletedExecutionNodes`). A contract that is
+ * gone, torn, or carries no nodes proves nothing about how the run was
+ * launched, so the run is not classified as planning on that evidence alone.
+ *
+ * @param {string} runDir
+ * @returns {boolean}
+ */
+export function isPlanningRun(runDir) {
+  let contract;
+  try {
+    contract = JSON.parse(readFileSync(join(runDir, "contract.json"), "utf8"));
+  } catch {
+    return false;
+  }
+  const contractNodes = /** @type {unknown[]} */ (Array.isArray(contract?.nodes) ? contract.nodes : []);
+  return contractNodes.length > 0 && contractNodes.every((node) => taskPacketModeOf(node) === "discovery");
+}
+
+/** @param {unknown} node @returns {unknown} */
+function taskPacketModeOf(node) {
+  return jsonObjectOf(jsonObjectOf(node)?.taskPacket)?.mode;
+}
+
+/**
+ * @param {string} ledgerDir
+ * @returns {{absent: Set<string>, planning: Set<string>}}
+ */
+function readLedgerManifest(ledgerDir) {
   try {
     const manifest = JSON.parse(readFileSync(join(ledgerDir, LEDGER_SOURCE_MANIFEST_FILE), "utf8"));
-    const preserved = /** @type {Set<string>} */ (new Set(Array.isArray(manifest?.preserved) ? /** @type {unknown[]} */ (manifest.preserved).filter((source) => typeof source === "string") : []));
-    return /** @type {Set<string>} */ (new Set(Array.isArray(manifest?.absent) ? /** @type {unknown[]} */ (manifest.absent).filter((source) => typeof source === "string" && !preserved.has(source)) : []));
+    const preserved = new Set(stringEntriesOf(manifest?.preserved));
+    return {
+      absent: new Set(stringEntriesOf(manifest?.absent).filter((source) => !preserved.has(source))),
+      planning: new Set(stringEntriesOf(manifest?.planning)),
+    };
   } catch {
-    // An old ledger has no origin manifest, so an absent file remains incomplete evidence.
-    return new Set();
+    // An old ledger has no origin manifest, so an absent file remains
+    // incomplete evidence and no run can be proven a planning run.
+    return { absent: new Set(), planning: new Set() };
   }
 }
 
+/**
+ * The string entries of one `sources.json` list field, and an empty list for
+ * anything else. The ledger's writer merges and sorts these lists and the
+ * reader above subtracts preserved names from absent ones, so both need the
+ * same tolerant read of the file's shape; it has one home here.
+ *
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+export function stringEntriesOf(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+
 /** @param {string} path @returns {Omit<RunNode, "runId">[]} */
 function readLedgerNodeSnapshots(path) {
   try {