faberun 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "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/record.mjs

@@ -49,9 +49,14 @@ export function campaignIdOf(campaignPath) {
   }
 }
 /**
+ * The campaign record's schema, in one home. Exported so the repair verb in
+ * `run/migrate.mjs` can prove a record's only defect is the absent `status`
+ * field by validating the record with that default applied, instead of the
+ * schema being restated beside the repair.
+ *
  * @param {unknown} campaign
  */
-function validateCampaign(campaign) {
+export function validateCampaign(campaign) {
   if (!campaign || typeof campaign !== "object" || Array.isArray(campaign)) {
     throw new TypeError("campaign.json must be an object");
   }

package/src/run/migrate.mjs

@@ -24,6 +24,16 @@
  * redone, by the next run: it verifies the published copy still holds every
  * byte the original holds and removes the original.
  *
+ * A published copy that predates a path the original later gained can never
+ * pass that verification, and the branch that sees one runs no copy for the
+ * path to reach: measured 2026-09-21, `.runs/control/second-opinions` was
+ * written into this repository's original tree after the home side had
+ * become authoritative, and every migrate run refused on it identically.
+ * Repairing the copy in place would publish state nobody verified, so the
+ * refusal is made to carry the resolution instead — it names what to carry
+ * into the published copy by hand, and the run after that action completes
+ * the move.
+ *
  * Idempotent by the same shape. A second run after a completed migration
  * finds no legacy root and reports nothing to move — the normal case for an
  * operator rerunning the command to be sure. A re-run after an interrupted
@@ -34,10 +44,18 @@
  * composed here from `projectsDir` plus names `run/paths.mjs` keeps private;
  * widening that module's surface for one caller is worse than spelling the
  * two literals here, next to this comment.
+ *
+ * `repairCampaignRecords` belongs here for the same reason the move does:
+ * both bring state an older faberun wrote to the shape the current code
+ * reads. Read keeps refusing a record it cannot trust, so the repair is a
+ * verb rather than a silent default on read, and it names every record it
+ * repairs and the field it filled — a repair that happens unreported is
+ * corruption by another name.
  */
-import { cpSync, existsSync, lstatSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { campaignsDir } from "../campaign/layout.mjs";
+import { CAMPAIGN_FILE, campaignsDir } from "../campaign/layout.mjs";
+import { validateCampaign } from "../campaign/record.mjs";
 import { readRemotes } from "../cli/project.mjs";
 import { faberunHome } from "../host/home.mjs";
 import { projectsDir, registerProject } from "../host/projects.mjs";
@@ -101,7 +119,7 @@ export function migrateRunState(cwd, options = {}) {
   // became authoritative; this branch never writes to the copy, so nothing
   // of theirs is at risk.
   if (existsSync(target)) {
-    verifyCopy(legacy, target);
+    verifyCopy(legacy, target, "published");
     const runs = countRunDirs(legacy);
     const campaigns = countCampaigns(legacy);
     refuseLiveLeases(leasesOf(legacy));
@@ -117,7 +135,7 @@ export function migrateRunState(cwd, options = {}) {
   // moment the removal ran; verbatim keeps the literal target, so relative
   // links (the worktrees' dependency symlinks) survive the move.
   cpSync(legacy, staging, { recursive: true, verbatimSymlinks: true });
-  verifyCopy(legacy, staging);
+  verifyCopy(legacy, staging, "staging");
   verifyNothingExtra(legacy, staging);
   const runs = countRunDirs(legacy);
   const campaigns = countCampaigns(legacy);
@@ -136,6 +154,65 @@ export function migrateRunState(cwd, options = {}) {
   return { moved: true, legacy, target, runs, campaigns };
 }
 
+/**
+ * Repair every campaign record under `runsDir` whose only defect is the
+ * absent `status` field: a record written before the field existed carries
+ * id, goal and linkedRunIds but no status, and discovery would report it
+ * corrupt forever. The repair fills the default current writes apply, writes
+ * the record back, and names every record it repaired and the field it
+ * filled in the returned list.
+ *
+ * The default is `closed` because an active campaign is one the product is
+ * currently driving, and a record written before the field existed has not
+ * been driven since.
+ *
+ * The predicate is the validator itself, run on the record with the default
+ * applied, so the repair cannot widen: a record that still fails validation
+ * with a valid status — malformed JSON, a missing id, a goal that is not
+ * text, a linkedRunIds that is not an array, a status present but wrong — is
+ * left exactly as discovery reports it. A record already carrying status is
+ * never rewritten, so a second run repairs nothing and writes nothing.
+ *
+ * @param {string} runsDir
+ * @returns {{id: string, field: string}[]} one entry per repaired record
+ */
+export function repairCampaignRecords(runsDir) {
+  const campaigns = campaignsDir(runsDir);
+  if (!existsSync(campaigns)) return [];
+  /** @type {{id: string, field: string}[]} */
+  const repaired = [];
+  for (const entry of readdirSync(campaigns, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = join(campaigns, entry.name, CAMPAIGN_FILE);
+    if (!existsSync(file)) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      // Unreadable or unparseable: there is no absent field to fill, and
+      // discovery keeps reporting the record corrupt.
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    const record = /** @type {Record<string, unknown>} */ (parsed);
+    // A status present but wrong is corruption, not age: only the absent
+    // field is repairable.
+    if (record.status !== undefined) continue;
+    record.status = "closed";
+    try {
+      validateCampaign(record);
+    } catch {
+      // The record fails the schema for a reason other than the absent
+      // status; the fill above dies with this in-memory object and the file
+      // is never written, so discovery's corrupt report stays true.
+      continue;
+    }
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+    repaired.push({ id: String(record.id), field: "status" });
+  }
+  return repaired;
+}
+
 /**
  * Every controller lock under `tree` whose holder is still alive. The lock
  * file's name is spelled here because `run/lock.mjs` keeps the constant
@@ -184,22 +261,28 @@ function refuseLiveLeases(leases) {
  * of what must be true, and byte-for-byte equality is the strongest check
  * that proves it without trusting the copy step's own bookkeeping.
  *
+ * `role` is which copy this is, and it only chooses what a refusal tells the
+ * operator to do about it: a staging copy is discarded and recopied by the
+ * next run, while a published copy is the one every reader answers while
+ * both trees exist, so only the operator can carry the difference into it.
+ *
  * @param {string} source
  * @param {string} copy
+ * @param {"staging"|"published"} role
  * @returns {void}
  */
-function verifyCopy(source, copy) {
+function verifyCopy(source, copy, role) {
   for (const entry of readdirSync(source, { withFileTypes: true })) {
     const from = join(source, entry.name);
     const to = join(copy, entry.name);
     if (entry.isDirectory()) {
       // lstat, not stat: a copied symlink to a directory must not pass as
       // the directory it points at.
-      if (!lstatSync(to, { throwIfNoEntry: false })?.isDirectory()) throw verifyFailure(from, to);
-      verifyCopy(from, to);
+      if (!lstatSync(to, { throwIfNoEntry: false })?.isDirectory()) throw verifyFailure(from, to, role);
+      verifyCopy(from, to, role);
     } else if (entry.isSymbolicLink()) {
-      if (readLinkOrUndefined(to) !== readlinkSync(from)) throw verifyFailure(from, to);
-    } else if (readOrUndefined(to)?.equals(readFileSync(from)) !== true) throw verifyFailure(from, to);
+      if (readLinkOrUndefined(to) !== readlinkSync(from)) throw verifyFailure(from, to, role);
+    } else if (readOrUndefined(to)?.equals(readFileSync(from)) !== true) throw verifyFailure(from, to, role);
   }
 }
 
@@ -233,9 +316,23 @@ function verifyNothingExtra(source, copy) {
   }
 }
 
-/** @param {string} from @param {string} to @returns {Error} */
-function verifyFailure(from, to) {
-  return new Error(`migration copy does not verify: ${from} is missing or different at ${to}; nothing was published or removed`);
+/**
+ * The refusal is the only way out of a copy that does not verify, so it
+ * names the action that lets a later run finish, not just the mismatch. For
+ * a staging copy that action is nothing: the next run discards the staging
+ * and copies anew. For a published copy there is no next-run help — the
+ * branch runs no copy, and migrating must not repair a copy behind the
+ * operator's back — so the refusal carries the whole resolution: what to
+ * carry into the published copy, by hand, and that the run after that
+ * completes the move.
+ *
+ * @param {string} from @param {string} to @param {"staging"|"published"} role @returns {Error}
+ */
+function verifyFailure(from, to, role) {
+  const action = role === "published"
+    ? `${to} is the copy every reader answers while both trees exist: move what ${from} holds that it lacks into it and settle any differing bytes by hand, then run migrate again`
+    : "the staging copy is discarded and recopied by the next run, so run migrate again";
+  return new Error(`migration copy does not verify: ${from} is missing or different at ${to}; nothing was published or removed — ${action}`);
 }
 
 /** @param {string} path @returns {Error} */