faberun 0.27.0 → 0.29.0

package/src/campaign/metrics.mjs

@@ -54,7 +54,7 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
 /** @typedef {Indicator & {unknownCount: number}} JudgeCostShareIndicator */
 /** @typedef {{value: Record<string, number>|null, direction: Direction, count: number, numerator?: Record<string, number>, denominator?: Record<string, number>, excludedRunIds?: string[], missingSources?: string[]}} GroupedIndicator */
 /** @typedef {{atMs: number, index: number, event: JsonObject}} RunEvent */
-/** @typedef {{runId: string, id: string, status: string, attempt?: number|null, revisions?: number|null, review?: string|null}} RunNode */
+/** @typedef {{runId: string, id: string, status: string, attempt?: number|null, revisions?: number|null, review?: string|null, judgeIndependence?: string|null}} RunNode */
 
 /**
  * @typedef {{
@@ -148,7 +148,34 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
     intentToVerifiedSeconds: northStar,
     humanTouches: touches,
   };
-  return applyMissingSources(metrics, missingSources);
+  const projected = /** @type {CampaignMetrics & {effectiveJudgeIndependence: string|null}} */ (applyMissingSources(metrics, missingSources));
+  // R36: the effective judge-independence mode the launch recorded on the run
+  // snapshots, read back from the reduced node input rather than re-derived
+  // from the contract or the machine config. It is metadata about the sources,
+  // like the run count, not a section-6 indicator: non-enumerable so the
+  // indicator set -- and every renderer that walks it -- is unchanged.
+  Object.defineProperty(projected, "effectiveJudgeIndependence", {
+    value: recordedJudgeIndependenceOf(eligibleNodes),
+    enumerable: false,
+  });
+  return projected;
+}
+
+/**
+ * The effective judge-independence mode the launch recorded on the run
+ * snapshots, reduced to the `judgeIndependence` field of the node input. The
+ * launch composes one mode per contract, so the first node that recorded one
+ * answers for the campaign; a caller that re-derives it from the contract or
+ * the machine config would miss a machine-config opt-in the launch recorded.
+ *
+ * @param {RunNode[]} nodes
+ * @returns {string|null}
+ */
+export function recordedJudgeIndependenceOf(nodes) {
+  for (const node of nodes) {
+    if (typeof node.judgeIndependence === "string" && node.judgeIndependence) return node.judgeIndependence;
+  }
+  return null;
 }
 
 /**

package/src/campaign/record.mjs

@@ -9,6 +9,7 @@
 import { CAMPAIGN_FILE, basenameSafe } from "./layout.mjs";
 import { errorCode } from "../util.mjs";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { assertObject, requireId, requirePacketHash, requireString, requireText, requireTimestamp } from "../contract/assert.mjs";
 
@@ -35,6 +36,11 @@ export function readCampaign(path) {
   record.contracts ??= [];
   record.landBranch ??= `campaign/${String(record.id)}`;
   record.promotions ??= [];
+  // The preservation state of the campaign's ledger. A record written before
+  // the marker existed, or written by a close that kept the ledger only in the
+  // operator home, reads as not preserved: removal refuses on the default
+  // rather than deleting evidence it cannot prove is safe.
+  record.ledgerPreserved ??= false;
   return /** @type {Campaign} */ (campaign);
 }
 /**
@@ -48,6 +54,28 @@ export function campaignIdOf(campaignPath) {
     return basenameSafe(campaignPath);
   }
 }
+/**
+ * A generated identifier for a note that arrives without one: the note text
+ * reduced to a lowercase ASCII slug, plus a short random suffix so two notes
+ * with identical text still get distinct ids. The slug is capped so a long
+ * note cannot produce an unusably long identifier, and an empty slug falls
+ * back to a bare `note-<suffix>`.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function generatedNoteId(text) {
+  const slug = text
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 40)
+    .replace(/-+$/gu, "");
+  const suffix = randomUUID().replace(/-/gu, "").slice(0, 6);
+  return slug ? `${slug}-${suffix}` : `note-${suffix}`;
+}
 /**
  * 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`
@@ -94,6 +122,12 @@ export function validateCampaign(campaign) {
     }
   }
   if (record.landBranch !== undefined) requireText(record.landBranch, "campaign.landBranch");
+  // The ledger preservation marker is optional on read (a record written
+  // before it existed reads as not preserved), but once written it must be a
+  // boolean so removal can rely on the state it carries.
+  if (record.ledgerPreserved !== undefined && typeof record.ledgerPreserved !== "boolean") {
+    throw new TypeError("campaign.ledgerPreserved must be a boolean");
+  }
   // The chain's durable park: the campaign stays active but carries the reason
   // it stopped, naming the contract, the node and the status when they exist.
   if (record.attention !== undefined && record.attention !== null) {

package/src/cli/campaign.mjs

@@ -18,7 +18,7 @@ import { syncAgentSignal } from "../repo/signal.mjs";
 import { acknowledgeJournalEvent, appendJournal, appendSeatAllowanceEvent, readJournal, watchJournal } from "../campaign/journal.mjs";
 import { driveCampaignChain } from "../campaign/chain.mjs";
 import { unparkCampaign } from "../campaign/unpark.mjs";
-import { readCampaign } from "../campaign/record.mjs";
+import { generatedNoteId, readCampaign } from "../campaign/record.mjs";
 import { projectMetrics } from "../campaign/metrics.mjs";
 import { readMetricsSources } from "../campaign/metrics-command.mjs";
 import { DEFAULT_WAKE_POLL_MS, watchCampaignWake } from "../campaign/watch.mjs";
@@ -49,7 +49,8 @@ const NOTE_KIND_FLAGS = {
 };
 
 /** Flags are scoped to the operations that declare them; all other flags are rejected. */
-/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+/** @typedef {{type: "string"|"boolean", multiple?: boolean, required?: boolean}} CampaignOption */
+/** @type {Record<string, Record<string, CampaignOption>>} */
 const OPERATION_OPTIONS = {
   list: { cwd: { type: "string" } },
   init: { cwd: { type: "string" }, goal: { type: "string" }, contract: { type: "string", multiple: true }, "land-branch": { type: "string" } },
@@ -67,8 +68,8 @@ const OPERATION_OPTIONS = {
   note: {
     cwd: { type: "string" },
     "session-id": { type: "string" },
-    kind: { type: "string" },
-    text: { type: "string" },
+    kind: { type: "string", required: true },
+    text: { type: "string", required: true },
     "event-id": { type: "string" },
     "decision-id": { type: "string" },
     supersedes: { type: "string" },
@@ -82,7 +83,7 @@ const OPERATION_OPTIONS = {
     text: { type: "string" },
     "event-id": { type: "string" },
   },
-  close: { cwd: { type: "string" }, "event-id": { type: "string" } },
+  close: { cwd: { type: "string" }, "event-id": { type: "string" }, "ledger-in-repo": { type: "boolean" } },
   reledger: { cwd: { type: "string" } },
   supervise: { cwd: { type: "string" }, "allow-main": { type: "boolean" }, "refresh-controller": { type: "boolean" } },
   unpark: { cwd: { type: "string" }, force: { type: "boolean" }, "event-id": { type: "string" } },
@@ -94,7 +95,7 @@ const OPERATION_OPTIONS = {
   ack: { cwd: { type: "string" }, "session-id": { type: "string" }, "event-id": { type: "string" } },
 };
 
-/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, refreshController?: boolean, force?: boolean, path?: string, replace?: string, phase?: string}} CliValues */
+/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, refreshController?: boolean, force?: boolean, path?: string, replace?: string, phase?: string, ledgerInRepo?: boolean}} CliValues */
 /** @typedef {import("../campaign/index.mjs").Campaign} Campaign */
 
 /**
@@ -273,16 +274,36 @@ function note(campaignId, values) {
     type: kind,
     eventId: values.eventId ?? randomUUID(),
     at: new Date().toISOString(),
-    sessionId: required(values.sessionId, "--session-id"),
+    sessionId: values.sessionId ?? lastAttachedSessionId(path),
     text: textValue(values.text, "--text"),
   };
-  if (kind === "decision") entry.decisionId = required(values.decisionId, "--decision-id");
+  if (kind === "decision") entry.decisionId = values.decisionId ?? generatedNoteId(String(entry.text));
   if (kind === "supersede") entry.supersedes = required(values.supersedes, "--supersedes");
-  if (kind === "open-question") entry.questionId = required(values.questionId, "--question-id");
+  if (kind === "open-question") entry.questionId = values.questionId ?? generatedNoteId(String(entry.text));
   if (kind === "outcome" && values.runId !== undefined) entry.runId = required(values.runId, "--run-id");
   appendJournal(path, entry);
   renderHandoff(path, runsDir);
-  process.stdout.write(`[campaign] ${kind} noted\n`);
+  const generatedId = entry.decisionId ?? entry.questionId;
+  process.stdout.write(`[campaign] ${kind} noted${generatedId ? ` · ${generatedId}` : ""}\n`);
+}
+
+/**
+ * The newest session recorded by a `session.attached` journal entry, used when
+ * a note arrives without `--session-id`. Refuses with the flag it needs when
+ * the campaign has no attached session at all.
+ *
+ * @param {string} campaignPath
+ * @returns {string}
+ */
+function lastAttachedSessionId(campaignPath) {
+  const attaches = readJournal(campaignPath).filter(
+    (entry) => entry.type === "session.attached" && typeof entry.sessionId === "string" && entry.sessionId,
+  );
+  const sessionId = attaches.at(-1)?.sessionId;
+  if (typeof sessionId !== "string" || !sessionId) {
+    throw new TypeError("--session-id requires a value and no session is attached to the campaign");
+  }
+  return sessionId;
 }
 
 /**
@@ -311,10 +332,12 @@ function resolveQuestion(campaignId, values) {
  */
 function close(campaignId, values) {
   const { path, runsDir } = selectCampaign(campaignId, values);
-  const closed = closeCampaign(path, { eventId: values.eventId ?? randomUUID() });
+  const ledgerInRepo = values.ledgerInRepo === true;
+  const closed = closeCampaign(path, { eventId: values.eventId ?? randomUUID(), ledgerInRepo });
   renderHandoff(path, runsDir);
   process.stdout.write(`[campaign] ${closed.campaign.id} closed\n`);
-  process.stdout.write(`[campaign] ledger · docs/campaigns/${closed.campaign.id}/ledger · ${closed.ledgerFiles.length} files\n`);
+  const ledgerLocation = ledgerInRepo ? `docs/campaigns/${closed.campaign.id}/ledger` : join(path, "ledger");
+  process.stdout.write(`[campaign] ledger · ${ledgerLocation} · ${closed.ledgerFiles.length} files\n`);
   reportUnknownCostFraction(path, runsDir);
   for (const skipped of closed.ledgerSkipped) {
     process.stdout.write(`[campaign] ledger skipped · ${skipped.runId}/${skipped.source}\n`);

package/src/cli/contract.mjs

@@ -8,6 +8,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { parseArgs as parseFlags } from "node:util";
 import { loadPersistedContract, validateContract } from "../contract/index.mjs";
+import { assertRuntimeAssignment } from "../engine/assignment.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 
@@ -52,9 +53,18 @@ export function contractCli(args) {
  */
 export function validateContractFile(path, { strictTraceability = false } = {}) {
   const runJsonPath = join(dirname(path), "run.json");
-  const contract = existsSync(runJsonPath)
+  const persisted = existsSync(runJsonPath);
+  const contract = persisted
     ? loadPersistedContract(path, readRunDigest(runJsonPath))
     : validateContract(JSON.parse(readFileSync(path, "utf8")), path);
+  // R35: the launch assigns roles before any node dispatches, so an authored
+  // contract must also survive that assignment. The live launch probes
+  // providers, so this dry run gives every runtime as available and refuses
+  // only what no probe could rescue -- an omitted judge with no cross-vendor
+  // candidate, a same-vendor pair below the admitted tier, an exhausted judge
+  // list. A persisted run's contract is a replay of an assignment already
+  // made, so it is not re-decided here.
+  if (!persisted) assertRuntimeAssignment(contract);
   const count = contract.warnings.length;
   const blockingTraceability = strictTraceability
     ? contract.warnings.filter((warning) => isTraceabilityFinding(warning))

package/src/cli/launch.mjs

@@ -14,9 +14,9 @@
 import { SETTLED } from "../engine/prompts.mjs";
 import { bootstrapAckPath, bootstrapAttemptPath, bootstrapPath, cleanupBootstrapAttempts, readJson, writeJsonAtomic } from "../run/store.mjs";
 import { bootstrapFailureMatchesChild, bootstrapMatchesChild, processStartToken, readLock, sameProcessStartToken, validBootstrapNonce } from "../run/lock.mjs";
-import { cleanupBootstrapNonce } from "../engine/detach.mjs";
+import { cleanupBootstrapNonce, discardNodeLessRunDirectory } from "../engine/detach.mjs";
 import { delay, errorCode } from "../util.mjs";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -112,6 +112,7 @@ export async function waitForBootstrap(runDir, pid, child = null, timeoutMs = bo
         const childIdentity = bootstrapMatchesChild(bootstrap, pid, nonce, expectedProcessStartToken);
         if (bootstrap.status === "failed" && bootstrapFailureMatchesChild(bootstrap, pid, nonce, expectedProcessStartToken)) {
           cleanupBootstrapAttempts(runDir);
+          discardNodeLessRunDirectory(runDir);
           throw new Error(`detached bootstrap failed: ${bootstrap.error}`);
         }
         const lock = readLock(runDir);
@@ -139,6 +140,7 @@ export async function waitForBootstrap(runDir, pid, child = null, timeoutMs = bo
         const failure = /** @type {BootstrapRecord} */ (readJson(bootstrapAttemptPath(runDir, nonce)));
         if (failure.status === "failed" && bootstrapFailureMatchesChild(failure, pid, nonce, expectedProcessStartToken)) {
           cleanupBootstrapAttempts(runDir);
+          discardNodeLessRunDirectory(runDir);
           throw new Error(`detached bootstrap failed: ${failure.error}`);
         }
       } catch (error) {
@@ -150,6 +152,7 @@ export async function waitForBootstrap(runDir, pid, child = null, timeoutMs = bo
       }
       cleanupBootstrapNonce(runDir, nonce);
       cleanupBootstrapAttempts(runDir);
+      discardNodeLessRunDirectory(runDir);
       throw new Error(`detached bootstrap failed before readiness for pid ${pid}`);
     }
     await delay(50);
@@ -229,10 +232,34 @@ export function bootstrapRunDir(command, target) {
  */
 export function writeBootstrapFailure(command, target, error) {
   const runDir = bootstrapRunDir(command, target);
-  if (!runDir || !existsSync(runDir)) return;
+  if (!runDir) return;
   const nonce = validBootstrapNonce(process.env.FABERUN_BOOTSTRAP_NONCE) ? process.env.FABERUN_BOOTSTRAP_NONCE : null;
   const failure = { status: "failed", pid: process.pid, processStartToken: processStartToken(process.pid), runDir, nonce, at: new Date().toISOString(), error: error.message };
-  if (command === "run" && existsSync(join(runDir, "contract.json"))) return;
+  const detachedChild = nonce !== null && !process.argv.includes("--detach");
+  if (!existsSync(runDir)) {
+    // A refusal that happens before the run directory exists — a dirty tree, a
+    // base ref that does not resolve — is the one the launcher cannot
+    // otherwise learn: the child's stdio is discarded, so all it could say was
+    // "failed before readiness for pid N". Measured 2026-09-27 (AP10): a whole
+    // `plan` stage died that way over two uncommitted paths. Only a detached
+    // child creates the directory, and only to carry this record;
+    // `waitForBootstrap` removes a node-less one as it reads it.
+    if (!detachedChild) return;
+    try {
+      mkdirSync(runDir, { recursive: true });
+    } catch {
+      // The refusal being reported matters more than the directory that would
+      // have carried it; without one the launcher falls back to its own message.
+      return;
+    }
+  }
+  // A `run` that names an existing run directory is refused before it writes
+  // anything, and its failure must not be stamped into that run's bootstrap
+  // record. The detached child is the exception: it wrote contract.json and
+  // then died before readiness, and the launcher has no other channel to
+  // learn the controller's error, so it must record that error before it
+  // exits.
+  if (command === "run" && !detachedChild && existsSync(join(runDir, "contract.json"))) return;
   /** @type {BootstrapRecord|null} */
   let current = null;
   try {

package/src/cli/manual.mjs

@@ -5,11 +5,16 @@
  * reads/writes prose, examples, Related lines, and the four fixed sections)
  * is copied through unchanged, so the manual's prose stays hand-authored
  * while its command surface cannot drift from the code silently.
+ *
+ * `--check` is the docs check the repository runs: it verifies COMMANDS.md and
+ * then runs the getting-started walkthrough against a throwaway repository, so
+ * the one document a newcomer follows literally cannot drift either.
  */
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { COMMAND_OPTIONS } from "../cli.mjs";
+import { checkGettingStarted, renderWalkthroughFailure } from "./walkthrough.mjs";
 import { METRICS_MANUAL } from "../campaign/metrics-command.mjs";
 import CAMPAIGN_OPERATIONS from "./campaign.mjs";
 import SEAT_OPERATIONS from "./seat.mjs";
@@ -18,7 +23,7 @@ import SKILLS_OPERATIONS from "./skills.mjs";
 import SPEC_OPERATIONS from "./spec.mjs";
 
 /** @typedef {{value: string, effect: string, default: string}} ManualFlag */
-/** @typedef {{type: "string"|"boolean", multiple?: boolean, manual?: ManualFlag}} FlagSpec */
+/** @typedef {{type: "string"|"boolean", multiple?: boolean, required?: boolean, manual?: ManualFlag}} FlagSpec */
 /** @typedef {{flags?: Record<string, FlagSpec>, operations?: Record<string, Record<string, FlagSpec>>}} VerbSurface */
 /** @typedef {{verbs: Record<string, VerbSurface>}} Surface */
 
@@ -223,9 +228,12 @@ function renderSynopsis(prefix, positional, flags) {
   const parts = [prefix];
   if (positional) parts.push(positional);
   for (const [name, spec] of Object.entries(flags)) {
-    if (spec.type === "boolean") parts.push(`[--${name}]`);
-    else if (spec.multiple) parts.push(`[--${name} <a>...]`);
-    else parts.push(`[--${name} <value>]`);
+    const token = spec.type === "boolean"
+      ? `--${name}`
+      : spec.multiple
+        ? `--${name} <a>...`
+        : `--${name} <value>`;
+    parts.push(spec.required ? token : `[${token}]`);
   }
   return parts.join(" ");
 }
@@ -339,13 +347,21 @@ function main(argv) {
   }
   const current = readFileSync(MANUAL_PATH, "utf8");
   const next = renderManual(current, collectSurface());
-  if (next === current) return;
   if (mode === "--write") {
-    writeFileSync(MANUAL_PATH, next);
+    if (next !== current) writeFileSync(MANUAL_PATH, next);
     return;
   }
-  process.stderr.write(`docs/COMMANDS.md is out of date; run \`npm run docs\`.\n${diffSummary(current, next)}\n`);
-  process.exitCode = 1;
+  let failed = false;
+  if (next !== current) {
+    process.stderr.write(`docs/COMMANDS.md is out of date; run \`npm run docs\`.\n${diffSummary(current, next)}\n`);
+    failed = true;
+  }
+  const walkthrough = checkGettingStarted();
+  if (!walkthrough.ok) {
+    process.stderr.write(renderWalkthroughFailure(walkthrough));
+    failed = true;
+  }
+  if (failed) process.exitCode = 1;
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) main(process.argv.slice(2));

package/src/cli/plan.mjs

@@ -5,8 +5,8 @@
  * sequencing and every decision the pipeline makes.
  */
 import { validateJudgeIndependence } from "../contract/judge-independence.mjs";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
 import { runProgress } from "../engine/supervise.mjs";
@@ -17,6 +17,7 @@ import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
 import { parseAnswerFlags, resolvePlanningPipeline } from "../plan/resolve.mjs";
+import { abandonedPlanProgress } from "../plan/progress.mjs";
 import { resolveReviewerList } from "../plan/reviewer.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
 import { readCampaign } from "../campaign/record.mjs";
@@ -112,6 +113,46 @@ export function loadRuntimesCatalogue(path) {
   return runtimes;
 }
 
+/**
+ * The campaign's own checked-in planning inputs live beside the spec it
+ * already keeps in the repository: `docs/campaigns/<id>/plan-inputs/`. A file
+ * that exists there is used as if it had been passed on the command line,
+ * because that is what it is for; an absent one changes nothing.
+ *
+ * Measured 2026-09-27 (AP19): a campaign carried
+ * `plan-inputs/runtimes.json` with a raised output ceiling, `plan` fell back
+ * to the 8192 default without a word, and the operator found out only after
+ * burning rounds on a truncated draft.
+ *
+ * @param {string} cwd @param {string} campaignId @param {string} file
+ * @returns {string}
+ */
+function campaignInputPath(cwd, campaignId, file) {
+  return join(cwd, "docs", "campaigns", campaignId, "plan-inputs", file);
+}
+
+/**
+ * The catalogue a `plan` reads runtimes from, and the file it came from when
+ * that file is the campaign's own. `--runtimes` wins over the checked-in one:
+ * an operator passing a path is overriding, not asking.
+ *
+ * `source` is returned rather than printed here so a caller decides the
+ * wording; `planCli` says it out loud because silence is the whole defect. The
+ * path is resolved from the launch cwd, never from the plan's own target, so
+ * the same command from a subdirectory reads the same file the campaign does.
+ *
+ * @param {{cwd: string, campaignId: string, runtimes?: unknown}} options
+ * @returns {{runtimes: Record<string, import("../contract/index.mjs").ValidatedRuntime>, source: string|null}}
+ */
+export function resolvePlanRuntimes({ cwd, campaignId, runtimes }) {
+  if (typeof runtimes === "string" && runtimes) return { runtimes: loadRuntimesCatalogue(runtimes), source: null };
+  const campaignRuntimes = campaignInputPath(cwd, campaignId, "runtimes.json");
+  if (!existsSync(campaignRuntimes)) {
+    return { runtimes: /** @type {Record<string, import("../contract/index.mjs").ValidatedRuntime>} */ (DISCOVERY_RUNTIME_DEFINITIONS), source: null };
+  }
+  return { runtimes: loadRuntimesCatalogue(campaignRuntimes), source: campaignRuntimes };
+}
+
 /**
  * A `--verification <path>` catalogue: a JSON object carrying either or both
  * of the contract's own suite keys, `sharedVerification` and
@@ -160,9 +201,10 @@ export async function planCli(target, values) {
   // R19: the planner's own reviewer list, never `runtimeDefaults.judge` --
   // `--reviewers` wins over the machine's own `config.reviewers` default.
   const reviewers = resolveReviewerList({ reviewers: parseReviewerList(values.reviewers) }, readUserConfig(process.env));
-  const runtimes = typeof values.runtimes === "string" && values.runtimes
-    ? loadRuntimesCatalogue(values.runtimes)
-    : DISCOVERY_RUNTIME_DEFINITIONS;
+  const { runtimes, source: runtimesSource } = resolvePlanRuntimes({ cwd: process.cwd(), campaignId, runtimes: values.runtimes });
+  // Said out loud because silence is the whole defect: the default and the
+  // campaign's own catalogue look identical from the outside.
+  if (runtimesSource) process.stdout.write(`[plan] runtimes · ${relative(process.cwd(), runtimesSource)}\n`);
   const verification = typeof values.verification === "string" && values.verification
     ? loadVerificationSuites(values.verification)
     : {};
@@ -171,6 +213,15 @@ export async function planCli(target, values) {
     ? undefined
     : validateJudgeIndependence(values["judge-independence"], "--judge-independence");
 
+  // A record with no live process behind it is the only trace a planning run
+  // that died without a word leaves. Measured 2026-09-26 (AP4): `--detach` pid
+  // 64270 vanished during repo-facts and the phase directory stayed empty, so
+  // the next launch is the one place the operator can still be told.
+  const abandoned = abandonedPlanProgress(process.cwd(), campaignId, phase);
+  if (abandoned) {
+    process.stderr.write(`[plan] a previous planning process (pid ${String(abandoned.pid ?? "?")}) stopped during ${String(abandoned.stage ?? "?")} at ${String(abandoned.at ?? "?")} and never reached the end\n`);
+  }
+
   if (values.detach === true) {
     const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
     if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);

package/src/cli/setup.mjs

@@ -31,6 +31,7 @@ import { boundedGitSync } from "../repo/worktree.mjs";
 import { colorLevel, renderBanner, statusToken } from "./brand.mjs";
 import { packageVersion } from "../host/package.mjs";
 import { configPath, faberunHome } from "../host/home.mjs";
+import { recordConfigInstall } from "../host/install-registry.mjs";
 import { readUserConfig, writeUserConfig } from "../host/config.mjs";
 import { discoverSkillTargets, registerSkills } from "./skills.mjs";
 
@@ -181,6 +182,10 @@ export async function setupCommand(options = {}) {
       updatedAt: new Date().toISOString(),
     };
     writeUserConfig(env, config);
+    // The config lives under FABERUN_HOME, which removal deletes wholesale, but
+    // it is still an out-of-repository write; recording it keeps the ledger a
+    // complete account of what setup left behind.
+    recordConfigInstall(env, configPath(faberunHome(env)));
     if (!json) stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
 
     // The offer comes after the config is durable, so a machine that answers

package/src/cli/skills.mjs

@@ -27,6 +27,7 @@ import { fileURLToPath } from "node:url";
 import { parseArgs as parseFlags } from "node:util";
 
 import { faberunHome, installedVersionDir } from "../host/home.mjs";
+import { recordSkillInstall, skillSiteDir } from "../host/install-registry.mjs";
 import { findExecutable, linkDirectory } from "../host/platform.mjs";
 import { colorLevel, statusToken } from "./brand.mjs";
 
@@ -71,15 +72,19 @@ const OPERATION_OPTIONS = {
  *   so it has no registration target. It is kept in the table to record the
  *   measurement, and reported as `no skill support`.
  *
- * @type {Record<string, {binary: string|null, optional: boolean, dir: ((home: string) => string)|null}>}
+ * The destination paths themselves live in `host/install-registry.mjs`'s
+ * `KNOWN_INSTALL_SITES` and are resolved through `skillSiteDir`, so this table
+ * and the manifest removal scans cannot drift apart.
+ *
+ * @type {Record<string, {binary: string|null, optional: boolean, dir: ((home: string) => string|null)|null}>}
  */
 const HARNESS_SKILL_DIRS = {
-  claude: { binary: "claude", optional: false, dir: (home) => join(home, ".claude", "skills") },
-  codex: { binary: "codex", optional: false, dir: (home) => join(home, ".codex", "skills") },
-  zcode: { binary: "zcode", optional: false, dir: (home) => join(home, ".agents", "skills") },
-  agy: { binary: "agy", optional: false, dir: (home) => join(home, ".gemini", "config", "skills") },
-  dsh: { binary: "dsh", optional: false, dir: null },
-  agents: { binary: null, optional: true, dir: (home) => join(home, ".agents", "skills") },
+  claude: { binary: "claude", optional: false, dir: (home) => skillSiteDir("claude", home) },
+  codex: { binary: "codex", optional: false, dir: (home) => skillSiteDir("codex", home) },
+  zcode: { binary: "zcode", optional: false, dir: (home) => skillSiteDir("zcode", home) },
+  agy: { binary: "agy", optional: false, dir: (home) => skillSiteDir("agy", home) },
+  dsh: { binary: "dsh", optional: false, dir: (home) => skillSiteDir("dsh", home) },
+  agents: { binary: null, optional: true, dir: (home) => skillSiteDir("agents", home) },
 };
 
 /** @typedef {(text: string) => void} Writer */
@@ -266,6 +271,12 @@ export function registerSkills(options = {}) {
     }
     mkdirSync(dir, { recursive: true });
     const action = options.copy === true ? copySkill(source, destination, force) : linkSkill(source, destination, force);
+    // `skipped` is a real directory faberun refused to displace, so it is not
+    // faberun's to remove. Every other action left (or confirmed) a faberun
+    // skill at `destination`, so it is recorded with the directory that owns it.
+    if (action !== "skipped") {
+      recordSkillInstall(env, { path: destination, root: dir, harness: target.harness });
+    }
     results.push({ harness: target.harness, dir: destination, action });
     const path = displayPath(destination, home);
     if (action === "skipped") {