faberun 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.21.0",
+  "version": "0.23.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/skills/faberun/references/operations.md

@@ -45,22 +45,22 @@ attempt's sealed sha, the same continuation rule as any other retry.
 One controller drives a run, holding `<run-dir>/controller.lock`: `{pid,
 processStartToken, startedAt, hostname}`. Acquisition is an exclusive create
 with no TTL. A contender treats the lock as stale only once it can prove the
-holder dead — the pid is gone, or its process start token no longer matches
-(pid recycled); anything less is `controller_active` and it exits untouched.
-Takeover renames the lock aside, re-checks the captured record is stale, then
-installs its own; a capture that turns out live is handed back. Worker/judge/
+holder dead — pid gone, or its start token no longer matches (pid recycled);
+otherwise it exits `controller_active`, untouched. Takeover renames the lock
+aside and re-checks it is stale before installing its own. Worker/judge/
 verification children run detached in their own process group, so before
 dispatching new work `resume`'s recovery pass terminates (`SIGTERM` then
 `SIGKILL`, same as `cancel`) every invocation recorded for a `running` node —
 unless it is still inside its deadline, when it is adopted and its result read.
-`cancel <run-dir>` signals a live controller first, so its own takeover never
-waits on an expiry.
+`cancel` signals a live controller first, so its takeover never waits.
 
 `supervise <run-dir> [--detach] [--interval <sec>]` is the watchdog above that.
 It holds no lock and writes no state: every interval (default 30s) it launches
 `resume --detach` when a node is unfinished and no controller is live, exits 0
 once all are terminal, and stops after three failed launches. An empty run
-directory is never resumed — it has not proved it needs to be.
+directory is never resumed. A detached controller outlives its launcher,
+not the session scope (cgroup) holding it: run long work under `tmux`,
+`systemd-run` or the seat.
 
 ## Runtime discovery
 

package/src/campaign/chain.mjs

@@ -42,6 +42,7 @@ import { pidAlive, processStartToken } from "../run/lock.mjs";
 import { delay, errorCode, errorMessage } from "../util.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { runDirectory } from "../run/paths.mjs";
+import { listNodeSnapshots, readNodeSnapshot } from "../run/node-store.mjs";
 import { gitArguments, killTarget } from "../host/platform.mjs";
 
 /** @typedef {import("../contract/index.mjs").ControllerIdentity} ControllerIdentity */
@@ -561,12 +562,14 @@ export async function driveCampaignChain(campaignPath, options = {}) {
       try {
         await launch(entry.path, { baseRef, controllerIdentity, runDir, contract });
       } catch (error) {
+        const stranded = strandedRunNote(runDir);
         return park({
           code: errorCode(error) ?? "launch_failed",
-          message: errorMessage(error),
+          message: stranded ? `${errorMessage(error)}; ${stranded}` : errorMessage(error),
           contractPath: entry.path,
           contractId: id,
           runId: id,
+          ...(stranded ? { resume: `resume ${runDir}` } : {}),
         });
       }
       heartbeat.progress();
@@ -578,3 +581,29 @@ export async function driveCampaignChain(campaignPath, options = {}) {
     if (acquired) releaseCoordinatorLock(campaignPath, acquired.lock);
   }
 }
+
+/**
+ * What a launch that died before readiness left on disk. RM-053, measured on
+ * `rec-audit-remediation`: the controller died with the launcher's cgroup,
+ * the park said only `detached bootstrap did not become ready`, and the run
+ * directory it left, every node pending, finished under a durable `resume`.
+ *
+ * @param {string} runDir
+ * @returns {string|null}
+ */
+function strandedRunNote(runDir) {
+  if (!runDir || !existsSync(runDir)) return null;
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const name of listNodeSnapshots(runDir)) {
+    let status = "unreadable";
+    try {
+      status = String(/** @type {{status?: unknown}} */ (readNodeSnapshot(runDir, name.replace(/\.json$/u, ""))).status ?? "unknown");
+    } catch {
+      // A snapshot caught mid-write is counted as unreadable, not dropped.
+    }
+    counts.set(status, (counts.get(status) ?? 0) + 1);
+  }
+  const nodes = [...counts].sort(([left], [right]) => left.localeCompare(right)).map(([status, count]) => `${count} ${status}`).join(" · ");
+  return `run directory ${runDir} exists (nodes: ${nodes || "none written yet"}); \`faberun resume ${runDir}\` completes it, under tmux, systemd-run or faberun seat so it outlives this shell`;
+}

package/src/campaign/index.mjs

@@ -1,5 +1,4 @@
 import {
-  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -11,11 +10,14 @@ import { writeJsonAtomic } from "../run/store.mjs";
 import { projectIdForRunsDir, repositoryForRunsDir } from "../run/paths.mjs";
 import { requireId, requirePacketHash, requireString, requireTimestamp } from "../contract/assert.mjs";
 import { promoteRun } from "../repo/integrate.mjs";
-import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, JOURNAL_FILE, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
+import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
 import { appendJournal, normalizeText, readJournalForDedupe } from "./journal.mjs";
 import { readProjectionState } from "./projection.mjs";
 import { handoffFromState, materializeHandoff } from "./handoff.mjs";
+import { preserveCampaignLedger, reledgerCampaignLedger } from "./ledger.mjs";
+
+export { preserveCampaignLedger, reledgerCampaignLedger } from "./ledger.mjs";
 
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {{path: string, digest: string}} CampaignContract */
@@ -23,7 +25,8 @@ import { handoffFromState, materializeHandoff } from "./handoff.mjs";
 /** @typedef {{code: string, message: string, at: string, contractPath?: string, contractId?: string, runId?: string, node?: string|null, status?: string|null, resume?: string}} CampaignAttention */
 /** @typedef {{runId: string, node: string, passed: boolean|null, verdict: string|null}} RequirementNodeEvidence */
 /** @typedef {{requirementId: string, status: "covered"|"open", nodes: RequirementNodeEvidence[]}} RequirementClosure */
-/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
+/** @typedef {{oldPath: string, newPath: string, runIds: string[], at: string}} ContractReplacement */
+/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], replacements?: ContractReplacement[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
 /** @typedef {{type: string, eventId: string, at: string, sessionId?: string, text?: string, tool?: string, transcript?: string|null, transcriptUnavailable?: boolean, format?: string|null, cursor?: string|null, decisionId?: string, supersedes?: string, runId?: string, questionId?: string, campaignId?: string, nodeId?: string|null, phase?: string, checkpointsDone?: number, checkpointsTotal?: number, runtime?: string|null, state?: string, lastProgressAt?: string, attention?: string|null}} JournalEntry */
 /** @typedef {{updatedAt: string|null, decisions: Record<string, JournalEntry>, questions: Record<string, JournalEntry>, constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], sessions: JournalEntry[], next: JournalEntry|null, evicted: Record<string, number>}} Projection */
 /** @typedef {{cursor: number, byte: number, size: number, projection: Projection}} ProjectionRecord */
@@ -55,6 +58,7 @@ export function initializeCampaign(runsDir, { campaignId, goal, at = new Date().
     status: "active",
     linkedRunIds: [],
     contracts: validatedContracts,
+    replacements: [],
     landBranch: branch,
     promotions: [],
     createdAt: at,
@@ -126,7 +130,7 @@ export function resolveCampaign(runsDir, campaignId) {
 /**
  * @param {string} campaignPath
  * @param {{at?: string, eventId?: string}} options
- * @returns {{path: string, campaign: Campaign, ledgerFiles: string[]}}
+ * @returns {{path: string, campaign: Campaign, ledgerFiles: string[], ledgerSkipped: {runId: string, source: string}[]}}
  */
 export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID() } = {}) {
   requireTimestamp(at, "at");
@@ -140,8 +144,6 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   if (unacknowledged.length) {
     throw new Error(`campaign ${campaign.id} has judge findings no note has answered: ${unacknowledged.join("; ")}. Read them with \`faberun findings <run-dir>\`, then name the node in a note (\`campaign note ${campaign.id} --kind outcome --run-id <run-id> --text "...<node>..."\`) before close`);
   }
-  const repoRoot = campaignRepoRoot(campaignPath);
-  const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
   // The closure travels on the record itself, computed in one deterministic
   // pass over the linked runs' own files before the close is written.
   const requirements = buildRequirementClosure(campaignPath, campaign);
@@ -149,7 +151,24 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   const closed = { ...campaign, status: "closed", closedAt: at, updatedAt: at, requirements };
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
   appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
-  return { path: campaignPath, campaign: closed, ledgerFiles };
+  // Preserve after the closed record exists: the ledger is the recomputable
+  // closed record, including requirements used by the north-star projector.
+  const ledger = preserveCampaignLedger(campaignPath, campaignRepoRoot(campaignPath));
+  return { path: campaignPath, campaign: closed, ledgerFiles: ledger.written, ledgerSkipped: ledger.skipped };
+}
+
+/**
+ * Complete the versioned evidence ledger of a closed campaign. Unlike close,
+ * this operation never updates the campaign record or journal: it only adds
+ * surviving run sources beneath the repository's ledger directory.
+ *
+ * @param {string} campaignPath
+ * @returns {import("./ledger.mjs").LedgerReledger & {ledgerDir: string}}
+ */
+export function reledgerCampaign(campaignPath) {
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status !== "closed") throw new Error(`campaign is not closed: ${campaign.id}`);
+  return reledgerCampaignLedger(campaignPath, campaignRepoRoot(campaignPath));
 }
 
 /**
@@ -290,46 +309,6 @@ function campaignRepoRoot(campaignPath) {
   return resolve(campaignPath, "..", "..", "..");
 }
 
-/**
- * Copy a campaign's journal, record and each linked run's usage into
- * `<repoRoot>/docs/campaigns/<id>/ledger/` so the comparative arm of the
- * planner has a session-side baseline even after `.runs/` (gitignored) is
- * pruned. Nothing in this tree redacts token counts, costs or operator notes
- * before this point, so the copy is verbatim; the pre-commit secret scan is
- * the guard against anything that should not land in git.
- *
- * Idempotent: re-running it (a second `close` on an already-closed campaign
- * cannot reach this, but a direct call can) overwrites the same destination
- * files rather than duplicating them. A linked run without a `usage.jsonl`
- * (never launched, or pruned) is skipped rather than thrown.
- *
- * @param {string} campaignPath
- * @param {string} repoRoot
- * @returns {string[]}
- */
-export function preserveCampaignLedger(campaignPath, repoRoot) {
-  const campaign = readCampaign(campaignPath);
-  const runsDir = resolve(campaignPath, "..", "..");
-  const ledgerDir = join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
-  mkdirSync(ledgerDir, { recursive: true });
-  const written = [];
-  for (const name of [JOURNAL_FILE, CAMPAIGN_FILE]) {
-    const source = join(campaignPath, name);
-    if (!existsSync(source)) continue;
-    const destination = join(ledgerDir, name);
-    copyFileSync(source, destination);
-    written.push(destination);
-  }
-  for (const runId of campaign.linkedRunIds) {
-    const source = join(runsDir, runId, "usage.jsonl");
-    if (!existsSync(source)) continue;
-    const destination = join(ledgerDir, `${runId}.usage.jsonl`);
-    copyFileSync(source, destination);
-    written.push(destination);
-  }
-  return written;
-}
-
 /**
  * @param {string} campaignPath
  * @param {string} runId
@@ -422,6 +401,7 @@ export function addContractToCampaign(campaignPath, contractPath, { at = new Dat
     : campaign.contracts.map((existing, index) => (index === existingIndex ? entry : existing));
   const updated = /** @type {Campaign} */ ({ ...campaign, contracts, updatedAt: at });
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
+  appendJournal(campaignPath, { type: "operator.command", eventId: randomUUID(), at, command: "campaign add-contract" });
   return { campaign: updated, added: true };
 }
 
@@ -458,13 +438,43 @@ export function replaceContractInCampaign(campaignPath, oldPath, newPath, { at =
   const contracts = campaign.contracts.map((entry, position) => (position === index ? replaced : entry));
   const attention = campaign.attention;
   const clearAttention = attention !== undefined && attention.contractPath === oldPath;
+  const replacementRunIds = replacedRunIds(campaignPath, campaign, oldPath, newPath, attention?.runId);
+  const replacement = { oldPath, newPath, runIds: replacementRunIds, at };
   /** @type {Campaign} */
-  const updated = { ...campaign, contracts, updatedAt: at };
+  const updated = { ...campaign, contracts, replacements: [...(campaign.replacements ?? []), replacement], updatedAt: at };
   if (clearAttention) delete updated.attention;
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
   return { campaign: updated, replaced, clearedAttention: clearAttention ? /** @type {CampaignAttention} */ (attention) : null };
 }
 
+/**
+ * Identify the run whose authored contract is being re-issued. The parked
+ * attention is the authoritative link when present; matching the old
+ * contract id also covers a replacement requested before the run was parked.
+ *
+ * @param {string} campaignPath
+ * @param {Campaign} campaign
+ * @param {string} oldPath
+ * @param {string} newPath
+ * @param {string|undefined} attentionRunId
+ * @returns {string[]}
+ */
+function replacedRunIds(campaignPath, campaign, oldPath, newPath, attentionRunId) {
+  const ids = new Set();
+  if (attentionRunId !== undefined && campaign.linkedRunIds.includes(attentionRunId)) ids.add(attentionRunId);
+  const oldContract = readRunJson(oldPath);
+  const oldId = oldContract !== null && typeof oldContract.id === "string" ? oldContract.id : null;
+  if (oldId !== null && campaign.linkedRunIds.includes(oldId)) ids.add(oldId);
+  const runsDir = resolve(campaignPath, "..", "..");
+  for (const runId of campaign.linkedRunIds) {
+    const runContract = readRunJson(join(runsDir, runId, "contract.json"));
+    if (runContract !== null && oldId !== null && runContract.id === oldId) ids.add(runId);
+  }
+  const replacementContract = readRunJson(newPath);
+  const replacementId = replacementContract !== null && typeof replacementContract.id === "string" ? replacementContract.id : null;
+  return [...ids].filter((runId) => replacementId === null || runId !== replacementId).sort();
+}
+
 /**
  * Persist one promotion in the campaign record. Idempotent by run id and the
  * sha it landed: a re-invocation after a crash between the branch move and
@@ -584,4 +594,3 @@ export function renderRunHandoff(runDir) {
   if (!existsSync(join(path, CAMPAIGN_FILE))) return null;
   return renderHandoff(path, runsDir);
 }
-

package/src/campaign/journal.mjs

@@ -33,6 +33,7 @@ const JOURNAL_TYPES = new Set([
   "next",
   "open-question",
   "question.resolved",
+  "operator.command",
   "retrospective",
   "liveness",
   "seat.allowance",
@@ -63,6 +64,7 @@ const ENTRY_SHAPES = {
   next: ["at", "type", "eventId", "sessionId", "text"],
   "open-question": ["at", "type", "eventId", "sessionId", "questionId", "text"],
   "question.resolved": ["at", "type", "eventId", "sessionId", "questionId", "text"],
+  "operator.command": ["at", "type", "eventId", "command", "sessionId", "runId"],
   retrospective: ["at", "type", "eventId", "sessionId", "text"],
   liveness: ["at", "type", "eventId", "campaignId", "runId", "nodeId", "phase", "checkpointsDone", "checkpointsTotal", "runtime", "state", "lastProgressAt", "attention"],
   "seat.allowance": ["at", "type", "eventId", "sample", "harness", "remaining", "limit", "resetsAt", "delta", "window"],
@@ -276,6 +278,12 @@ export function validateJournalEntry(entry) {
   // rejects an unexpected key; no deeper shape validation is needed for a type
   // nothing produces.
   if (type === "liveness") return;
+  if (type === "operator.command") {
+    requireText(record.command, "entry.command");
+    if (record.sessionId !== undefined) requireText(record.sessionId, "entry.sessionId");
+    if (record.runId !== undefined) requireText(record.runId, "entry.runId");
+    return;
+  }
   if (type === "seat.allowance") return validateSeatAllowanceEntry(record);
   if (type === "session.attached") return validateSessionEntry(record);
   if (type === "run.registered") {

package/src/campaign/layout.mjs

@@ -13,6 +13,7 @@ import { requireId } from "../contract/assert.mjs";
 export const CAMPAIGN_DIR_NAME = "campaigns";
 export const CAMPAIGN_FILE = "campaign.json";
 export const JOURNAL_FILE = "journal.jsonl";
+export const LEDGER_SOURCE_MANIFEST_FILE = "sources.json";
 export const HANDOFF_FILE = "HANDOFF.md";
 export const PROJECTION_FILE = "projection.json";
 export const JOURNAL_WATCH_CURSOR_DIR = "watch-cursors";

package/src/campaign/ledger.mjs

@@ -0,0 +1,270 @@
+/**
+ * The closed campaign evidence copy: only the files consumed by campaign and
+ * eval projectors cross from the operator home into the versioned ledger.
+ */
+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 { CAMPAIGN_FILE, JOURNAL_FILE, LEDGER_SOURCE_MANIFEST_FILE } from "./layout.mjs";
+import { readCampaign } from "./record.mjs";
+
+/** @typedef {{runId: string, source: string}} LedgerSkip */
+/** @typedef {{written: string[], skipped: LedgerSkip[]}} LedgerPreservation */
+/** @typedef {{runId: string, source: string}} LedgerChange */
+/** @typedef {{copied: LedgerChange[], gone: LedgerChange[]}} LedgerReledger */
+
+const RUN_SOURCES = [
+  ["events.jsonl", "events.jsonl"],
+  ["usage.jsonl", "usage.jsonl"],
+  ["notify.jsonl", "notify.jsonl"],
+];
+
+/** Fields consumed by `projectMetrics` and `projectEvalIndicators`; worker prose never crosses the ledger boundary. */
+export const EVENT_PROJECTION_FIELDS = Object.freeze([
+  "at", "node", "to", "phase", "runtime", "verdict", "proofApproved", "passed", "override", "recovery", "error", "revisions",
+]);
+/** Fields consumed by `projectMetrics`; notification messages and transport details never cross the ledger boundary. */
+export const NOTIFY_PROJECTION_FIELDS = Object.freeze(["at", "dedupeKey", "attempt", "status"]);
+
+/**
+ * Copy a campaign's projector sources into its versioned ledger. Missing run
+ * sources are reported so a pruned run cannot make the close fail or look
+ * complete by accident. Repeated calls overwrite the same paths.
+ *
+ * @param {string} campaignPath
+ * @param {string} repoRoot
+ * @returns {LedgerPreservation}
+ */
+export function preserveCampaignLedger(campaignPath, repoRoot) {
+  const campaign = readCampaign(campaignPath);
+  const runsDir = resolve(campaignPath, "..", "..");
+  const ledgerDir = join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
+  mkdirSync(ledgerDir, { recursive: true });
+  /** @type {string[]} */
+  const written = [];
+  /** @type {LedgerSkip[]} */
+  const skipped = [];
+  const priorManifest = readSourceManifest(ledgerDir);
+  const absent = new Set(priorManifest.absent);
+  const preserved = new Set(priorManifest.preserved);
+  for (const name of [JOURNAL_FILE, CAMPAIGN_FILE]) {
+    const source = join(campaignPath, name);
+    if (!existsSync(source)) continue;
+    const destination = join(ledgerDir, name);
+    copyFileSync(source, destination);
+    written.push(destination);
+  }
+  for (const runId of campaign.linkedRunIds) {
+    const runDir = join(runsDir, runId);
+    for (const [sourceName, destinationSuffix] of RUN_SOURCES) {
+      const source = join(runDir, sourceName);
+      const destinationName = `${runId}.${destinationSuffix}`;
+      if (!existsSync(source)) {
+        skipped.push({ runId, source: sourceName });
+        if (!preserved.has(destinationName)) absent.add(destinationName);
+        continue;
+      }
+      absent.delete(destinationName);
+      preserved.add(destinationName);
+      const destination = join(ledgerDir, destinationName);
+      if (sourceName === "events.jsonl" || sourceName === "notify.jsonl") {
+        writeFileSync(destination, projectJsonl(source, sourceName === "events.jsonl" ? EVENT_PROJECTION_FIELDS : NOTIFY_PROJECTION_FIELDS));
+      } else {
+        copyFileSync(source, destination);
+      }
+      written.push(destination);
+    }
+    const nodesSource = join(runDir, "nodes");
+    if (!existsSync(nodesSource)) {
+      skipped.push({ runId, source: "nodes" });
+      if (!preserved.has(`${runId}.nodes.json`)) absent.add(`${runId}.nodes.json`);
+      continue;
+    }
+    absent.delete(`${runId}.nodes.json`);
+    preserved.add(`${runId}.nodes.json`);
+    const nodesDestination = join(ledgerDir, `${runId}.nodes.json`);
+    writeFileSync(nodesDestination, `${JSON.stringify(readMetricNodeSnapshots(runDir))}\n`);
+    written.push(nodesDestination);
+  }
+  const proposalsSource = join(campaignPath, "proposals");
+  if (existsSync(proposalsSource)) {
+    const proposalsDestination = join(ledgerDir, "proposals");
+    cpSync(proposalsSource, proposalsDestination, { recursive: true });
+    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`);
+  written.push(manifest);
+  return { written, skipped };
+}
+
+/**
+ * Complete an already closed ledger from the run files still in the operator
+ * home. A destination is replaced only when the source strictly extends its
+ * bytes; this keeps a ledger's evidence stable when a run was rewritten or
+ * truncated after close. Missing run sources are reported as gone.
+ *
+ * @param {string} campaignPath
+ * @param {string} repoRoot
+ * @returns {LedgerReledger & {ledgerDir: string}}
+ */
+export function reledgerCampaignLedger(campaignPath, repoRoot) {
+  const campaign = readCampaign(campaignPath);
+  const runsDir = resolve(campaignPath, "..", "..");
+  const ledgerDir = join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
+  mkdirSync(ledgerDir, { recursive: true });
+  /** @type {LedgerChange[]} */
+  const copied = [];
+  /** @type {LedgerChange[]} */
+  const gone = [];
+  const sourceManifest = readSourceManifest(ledgerDir);
+  const preserved = new Set(sourceManifest.preserved);
+  const absent = new Set(sourceManifest.absent);
+  for (const runId of campaign.linkedRunIds) {
+    const runDir = join(runsDir, runId);
+    for (const [sourceName, destinationSuffix] of RUN_SOURCES) {
+      const source = join(runDir, sourceName);
+      const change = { runId, source: sourceName };
+      if (!existsSync(source)) {
+        gone.push(change);
+        continue;
+      }
+      const destination = join(ledgerDir, `${runId}.${destinationSuffix}`);
+      const projected = sourceName === "events.jsonl" || sourceName === "notify.jsonl"
+        ? projectJsonl(source, sourceName === "events.jsonl" ? EVENT_PROJECTION_FIELDS : NOTIFY_PROJECTION_FIELDS)
+        : source;
+      if (sourceName === "events.jsonl" || sourceName === "notify.jsonl") {
+        if (writeIfStrictExtension(destination, projected)) copied.push(change);
+      } else if (copyIfStrictExtension(projected, destination)) copied.push(change);
+      if (existsSync(destination)) {
+        preserved.add(`${runId}.${destinationSuffix}`);
+        absent.delete(`${runId}.${destinationSuffix}`);
+      }
+    }
+    const nodesSource = join(runDir, "nodes");
+    const nodesChange = { runId, source: "nodes" };
+    if (!existsSync(nodesSource)) {
+      gone.push(nodesChange);
+      continue;
+    }
+    const nodesDestination = join(ledgerDir, `${runId}.nodes.json`);
+    const projection = `${JSON.stringify(readMetricNodeSnapshots(runDir))}\n`;
+    if (writeIfStrictExtension(nodesDestination, projection)) copied.push(nodesChange);
+    if (existsSync(nodesDestination)) {
+      preserved.add(`${runId}.nodes.json`);
+      absent.delete(`${runId}.nodes.json`);
+    }
+  }
+  const proposalsSource = join(campaignPath, "proposals");
+  if (existsSync(proposalsSource)) {
+    for (const relative of filesUnder(proposalsSource)) {
+      const source = join(proposalsSource, relative);
+      const destination = join(ledgerDir, "proposals", relative);
+      if (copyIfStrictExtension(source, destination)) copied.push({ runId: campaign.id, source: `proposals/${relative}` });
+    }
+  }
+  const ledgerCampaign = join(ledgerDir, CAMPAIGN_FILE);
+  if (existsSync(ledgerCampaign)) {
+    const existing = readJsonObject(ledgerCampaign);
+    if (existing?.id === campaign.id && existing.status !== "closed" && campaign.status === "closed") {
+      writeFileSync(ledgerCampaign, readFileSync(join(campaignPath, CAMPAIGN_FILE)));
+    }
+  } 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`);
+  return { ledgerDir, copied, gone };
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @returns {boolean}
+ */
+function copyIfStrictExtension(source, destination) {
+  const bytes = readFileSync(source);
+  return writeIfStrictExtension(destination, bytes);
+}
+
+/**
+ * @param {string} destination
+ * @param {Buffer|string} source
+ * @returns {boolean}
+ */
+function writeIfStrictExtension(destination, source) {
+  const bytes = Buffer.isBuffer(source) ? source : Buffer.from(source);
+  mkdirSync(dirname(destination), { recursive: true });
+  if (!existsSync(destination)) {
+    writeFileSync(destination, bytes);
+    return true;
+  }
+  const existing = readFileSync(destination);
+  if (bytes.length <= existing.length || !bytes.subarray(0, existing.length).equals(existing)) return false;
+  writeFileSync(destination, bytes);
+  return true;
+}
+
+/** @param {string} path @param {readonly string[]} fields @returns {string} */
+function projectJsonl(path, fields) {
+  const text = readFileSync(path, "utf8");
+  const lines = text.split(/\r?\n/u);
+  const projected = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    if (index === lines.length - 1 && !text.endsWith("\n")) continue;
+    const value = JSON.parse(lines[index]);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+    const source = /** @type {Record<string, unknown>} */ (value);
+    /** @type {Record<string, unknown>} */
+    const record = {};
+    for (const field of fields) if (Object.hasOwn(source, field)) record[field] = projectedField(source[field], field);
+    projected.push(JSON.stringify(record));
+  }
+  return projected.length === 0 ? "" : `${projected.join("\n")}\n`;
+}
+
+/** @param {unknown} value @param {string} field @returns {unknown} */
+function projectedField(value, field) {
+  if (field !== "override" || value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  const object = /** @type {Record<string, unknown>} */ (value);
+  return Object.hasOwn(object, "kind") ? { kind: object.kind } : {};
+}
+
+/** @param {string} root @returns {{absent: string[], preserved: 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") : [],
+    };
+  } catch {
+    // An old ledger has no origin manifest; its files remain subject to the legacy missing-source rules.
+    return { absent: [], preserved: [] };
+  }
+}
+
+/** @param {string} path @returns {Record<string, unknown>|null} */
+function readJsonObject(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+      ? /** @type {Record<string, unknown>} */ (value)
+      : null;
+  } catch {
+    // A malformed old ledger record cannot prove that it is already closed.
+    return null;
+  }
+}
+
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+function filesUnder(root) {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.isDirectory()) return filesUnder(join(root, entry.name)).map((path) => join(entry.name, path));
+    return [entry.name];
+  });
+}