faberun 0.3.0 → 0.7.0

package/src/cli/manual.mjs

@@ -0,0 +1,341 @@
+/**
+ * Regenerates the derivable parts of docs/COMMANDS.md — verb and operation
+ * headings, synopsis lines and flag-table rows — from the option tables the
+ * CLI itself dispatches on. Every other line (description paragraphs,
+ * 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.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { COMMAND_OPTIONS } from "../cli.mjs";
+import CAMPAIGN_OPERATIONS from "./campaign.mjs";
+import SEAT_OPERATIONS from "./seat.mjs";
+import CONTRACT_OPERATIONS from "./contract.mjs";
+import SKILLS_OPERATIONS from "./skills.mjs";
+
+/** @typedef {{type: "string"|"boolean", multiple?: boolean}} FlagSpec */
+/** @typedef {{flags?: Record<string, FlagSpec>, operations?: Record<string, Record<string, FlagSpec>>}} VerbSurface */
+/** @typedef {{verbs: Record<string, VerbSurface>}} Surface */
+
+const MANUAL_PATH = fileURLToPath(new URL("../../docs/COMMANDS.md", import.meta.url));
+
+/**
+ * `campaign`, `seat`, `contract` and `skills` are dispatched before
+ * `COMMAND_OPTIONS` is ever consulted (`cli.mjs` routes them by `argv[0]`), so
+ * they carry no flags of their own — only the operations their own module
+ * declares. Their top-level `## faberun <verb>` section is therefore never
+ * regenerated; it is hand-authored overview prose, preserved verbatim.
+ *
+ * @type {Record<string, Record<string, Record<string, FlagSpec>>>}
+ */
+const CONTAINER_OPERATIONS = {
+  campaign: CAMPAIGN_OPERATIONS,
+  seat: SEAT_OPERATIONS,
+  contract: CONTRACT_OPERATIONS,
+  skills: SKILLS_OPERATIONS,
+};
+
+/**
+ * The real command surface, read from the same option tables `cli.mjs`
+ * parses argv against. `supervise campaign` is `campaign.mjs`'s `supervise`
+ * operation reached through a second spelling (`cli.mjs` routes
+ * `argv = ["supervise", "campaign", …]` into `campaignCli`), so it shares that
+ * operation's flags rather than declaring its own.
+ *
+ * @returns {Surface}
+ */
+export function collectSurface() {
+  /** @type {Record<string, VerbSurface>} */
+  const verbs = {};
+  for (const [verb, flags] of Object.entries(COMMAND_OPTIONS)) verbs[verb] = { flags };
+  if (verbs.supervise) verbs.supervise.operations = { campaign: CAMPAIGN_OPERATIONS.supervise };
+  for (const [verb, operations] of Object.entries(CONTAINER_OPERATIONS)) verbs[verb] = { operations };
+  return { verbs };
+}
+
+const VERB_HEADING = /^## faberun ([a-z][a-z-]*)$/u;
+const TABLE_HEADER = "| Flag | Value | Effect | Default |";
+const TABLE_SEPARATOR = "| --- | --- | --- | --- |";
+/** The start of a flag token in a synopsis line: `--flag` or `[--flag`. */
+const FLAG_TOKEN = /\[?--/u;
+
+/**
+ * Regenerate the derivable parts of a command manual. A verb absent from
+ * `surface` is dropped; one present in `surface` but absent from `current` is
+ * appended as a skeleton section.
+ *
+ * @param {string} current
+ * @param {Surface} surface
+ * @returns {string}
+ */
+export function renderManual(current, surface) {
+  const lines = current.split("\n");
+  /** @type {string[]} */
+  const output = [];
+  const seenVerbs = new Set();
+  let i = 0;
+  while (i < lines.length) {
+    const match = VERB_HEADING.exec(lines[i]);
+    if (!match) {
+      output.push(lines[i]);
+      i += 1;
+      continue;
+    }
+    const verb = match[1];
+    let end = i + 1;
+    while (end < lines.length && !/^## /u.test(lines[end])) end += 1;
+    const entry = surface.verbs[verb];
+    if (entry) {
+      output.push(...renderVerbBlock(verb, lines.slice(i, end), entry));
+      seenVerbs.add(verb);
+    }
+    i = end;
+  }
+  for (const [verb, entry] of Object.entries(surface.verbs)) {
+    if (!seenVerbs.has(verb)) output.push(...renderVerbBlock(verb, [`## faberun ${verb}`], entry));
+  }
+  return output.join("\n");
+}
+
+/**
+ * @param {string} verb
+ * @param {string[]} block
+ * @param {VerbSurface} entry
+ * @returns {string[]}
+ */
+function renderVerbBlock(verb, block, entry) {
+  const heading = block[0] ?? `## faberun ${verb}`;
+  const { body, operationBlocks } = splitOperations(verb, block.slice(1));
+  const renderedBody = entry.flags
+    ? renderFlaggedBody(`faberun ${verb}`, body, entry.flags)
+    : body.length
+      ? body
+      : renderFlaggedBody(`faberun ${verb}`, [], {});
+  const renderedOperations = renderOperations(verb, operationBlocks, entry.operations ?? {});
+  return [heading, ...renderedBody, ...renderedOperations];
+}
+
+/**
+ * Splits a verb's body into the part before its first `### faberun <verb>
+ * <op>` heading and the operation sub-blocks that follow, each running to the
+ * next `### ` heading.
+ *
+ * @param {string} verb
+ * @param {string[]} lines
+ * @returns {{body: string[], operationBlocks: {op: string, block: string[]}[]}}
+ */
+function splitOperations(verb, lines) {
+  const opHeading = new RegExp(`^### faberun ${verb} ([a-z][a-z-]*)$`, "u");
+  const firstOpIndex = lines.findIndex((line) => opHeading.test(line));
+  if (firstOpIndex === -1) return { body: lines, operationBlocks: [] };
+  const body = lines.slice(0, firstOpIndex);
+  /** @type {{op: string, block: string[]}[]} */
+  const operationBlocks = [];
+  let i = firstOpIndex;
+  while (i < lines.length) {
+    const match = opHeading.exec(lines[i]);
+    if (!match) break;
+    let end = i + 1;
+    while (end < lines.length && !/^###? /u.test(lines[end])) end += 1;
+    operationBlocks.push({ op: match[1], block: lines.slice(i, end) });
+    i = end;
+  }
+  return { body, operationBlocks };
+}
+
+/**
+ * @param {string} verb
+ * @param {{op: string, block: string[]}[]} operationBlocks
+ * @param {Record<string, Record<string, FlagSpec>>} operations
+ * @returns {string[]}
+ */
+function renderOperations(verb, operationBlocks, operations) {
+  const output = [];
+  const seen = new Set();
+  for (const { op, block } of operationBlocks) {
+    if (!Object.hasOwn(operations, op)) continue;
+    output.push(block[0] ?? `### faberun ${verb} ${op}`, ...renderFlaggedBody(`faberun ${verb} ${op}`, block.slice(1), operations[op]));
+    seen.add(op);
+  }
+  for (const [op, flags] of Object.entries(operations)) {
+    if (seen.has(op)) continue;
+    output.push(`### faberun ${verb} ${op}`, ...renderFlaggedBody(`faberun ${verb} ${op}`, [], flags));
+  }
+  return output;
+}
+
+/**
+ * Regenerates a section's synopsis fence and flag table in place; every
+ * other line is untouched.
+ *
+ * @param {string} prefix
+ * @param {string[]} body
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string[]}
+ */
+function renderFlaggedBody(prefix, body, flags) {
+  const positional = extractPositional(prefix, body);
+  const synopsis = renderSynopsis(prefix, positional, flags);
+  const fence = findFence(body, "```text");
+  const withSynopsis = fence
+    ? [...body.slice(0, fence.start), "```text", synopsis, "```", ...body.slice(fence.end + 1)]
+    : ["```text", synopsis, "```", ...body];
+  return replaceFlagTable(withSynopsis, flags);
+}
+
+/**
+ * The positional placeholder a synopsis names, kept verbatim from the
+ * current text (including its own brackets, when optional) — everything
+ * before the first flag token.
+ *
+ * @param {string} prefix
+ * @param {string[]} body
+ * @returns {string}
+ */
+function extractPositional(prefix, body) {
+  const fence = findFence(body, "```text");
+  if (!fence) return "";
+  const inner = body[fence.start + 1] ?? "";
+  if (!inner.startsWith(prefix)) return "";
+  const remainder = inner.slice(prefix.length).trim();
+  const flagToken = FLAG_TOKEN.exec(remainder);
+  return flagToken ? remainder.slice(0, flagToken.index).trim() : remainder;
+}
+
+/**
+ * @param {string} prefix
+ * @param {string} positional
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string}
+ */
+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>]`);
+  }
+  return parts.join(" ");
+}
+
+/**
+ * @param {string[]} lines
+ * @param {string} opener
+ * @returns {{start: number, end: number}|null}
+ */
+function findFence(lines, opener) {
+  const start = lines.indexOf(opener);
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length && lines[end] !== "```") end += 1;
+  return { start, end };
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string[]}
+ */
+function replaceFlagTable(lines, flags) {
+  const headerIndex = lines.indexOf(TABLE_HEADER);
+  const existingRows = headerIndex === -1 ? new Map() : parseRows(lines, headerIndex + 2);
+  const newRows = buildRows(flags, existingRows);
+  if (headerIndex === -1) {
+    const fenceEnd = lines.indexOf("```");
+    const insertAt = fenceEnd === -1 ? lines.length : fenceEnd + 1;
+    return [...lines.slice(0, insertAt), TABLE_HEADER, TABLE_SEPARATOR, ...newRows, ...lines.slice(insertAt)];
+  }
+  let rowsEnd = headerIndex + 2;
+  while (rowsEnd < lines.length && lines[rowsEnd].startsWith("|")) rowsEnd += 1;
+  return [...lines.slice(0, headerIndex), TABLE_HEADER, TABLE_SEPARATOR, ...newRows, ...lines.slice(rowsEnd)];
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} start
+ * @returns {Map<string, {value: string, effect: string, default: string}>}
+ */
+function parseRows(lines, start) {
+  /** @type {Map<string, {value: string, effect: string, default: string}>} */
+  const map = new Map();
+  let i = start;
+  while (i < lines.length && lines[i].startsWith("|")) {
+    const cells = lines[i].trim().replace(/^\|/u, "").replace(/\|$/u, "").split("|").map((cell) => cell.trim());
+    if (cells.length === 4) map.set(flagKeyOf(cells[0]), { value: cells[1], effect: cells[2], default: cells[3] });
+    i += 1;
+  }
+  return map;
+}
+
+/** @param {string} cell @returns {string} */
+function flagKeyOf(cell) {
+  const match = /`--([a-z-]+)`/u.exec(cell);
+  return match ? match[1] : "—";
+}
+
+/**
+ * @param {Record<string, FlagSpec>} flags
+ * @param {Map<string, {value: string, effect: string, default: string}>} existingRows
+ * @returns {string[]}
+ */
+function buildRows(flags, existingRows) {
+  const names = Object.keys(flags);
+  if (names.length === 0) {
+    const existing = existingRows.get("—");
+    return [existing ? `| — | ${existing.value} | ${existing.effect} | ${existing.default} |` : "| — | — | No flags. | — |"];
+  }
+  return names.map((name) => {
+    const existing = existingRows.get(name);
+    const value = existing ? existing.value : "<value>";
+    const effect = existing ? existing.effect : "";
+    const fallback = existing ? existing.default : "—";
+    return `| \`--${name}\` | ${value} | ${effect} | ${fallback} |`;
+  });
+}
+
+/**
+ * A minimal, dependency-free diff summary: every line index where the two
+ * texts disagree, capped so a large rewrite does not flood the console.
+ *
+ * @param {string} current
+ * @param {string} next
+ * @returns {string}
+ */
+function diffSummary(current, next) {
+  const a = current.split("\n");
+  const b = next.split("\n");
+  const max = Math.max(a.length, b.length);
+  /** @type {string[]} */
+  const lines = [];
+  for (let i = 0; i < max && lines.length < 40; i += 1) {
+    if (a[i] !== b[i]) lines.push(`line ${i + 1}:\n- ${a[i] ?? "<eof>"}\n+ ${b[i] ?? "<eof>"}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {void}
+ */
+function main(argv) {
+  const mode = argv[0];
+  if (mode !== "--write" && mode !== "--check") {
+    process.stderr.write("usage: manual.mjs --write|--check\n");
+    process.exitCode = 2;
+    return;
+  }
+  const current = readFileSync(MANUAL_PATH, "utf8");
+  const next = renderManual(current, collectSurface());
+  if (next === current) return;
+  if (mode === "--write") {
+    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;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) main(process.argv.slice(2));

package/src/cli/seat.mjs

@@ -137,3 +137,5 @@ function usage() {
   process.stderr.write("usage: faberun seat <start|attach|status|stop|switch> [<campaign-id>] [--cwd <dir>] ...\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli/setup.mjs

@@ -5,9 +5,14 @@
  * It checks the two host prerequisites, discovers the catalogue runtimes
  * through the same `discoverRuntimes` the engine uses, asks which harnesses to
  * enable and which runtime is the default worker and judge, and writes the user
- * config at `$FABERUN_HOME/config.json`. The judge must resolve to a vendor
- * other than the worker's; the prompt refuses a same-vendor answer once and the
- * command fails on the second.
+ * config at `$FABERUN_HOME/config.json`. When a config already exists, its
+ * recorded harnesses, worker and judge seed the defaults instead of the
+ * fresh-machine ones, narrowed to whatever discovery still reports available;
+ * an explicit `--harnesses`, `--worker` or `--judge` still wins. The judge must
+ * resolve to a vendor other than the worker's; the prompt refuses a same-vendor
+ * answer once and the command fails on the second. Once the config is written it offers to register
+ * the faberun skill into every installed harness's skills directory, reusing
+ * `registerSkills` from `./skills.mjs` so discovery has one home.
  *
  * Discovery and the question function are injected so tests never touch a real
  * binary or a terminal. `--json` never asks: it reports the same facts as one
@@ -25,10 +30,12 @@ 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 { writeUserConfig } from "../host/config.mjs";
+import { readUserConfig, writeUserConfig } from "../host/config.mjs";
+import { discoverSkillTargets, registerSkills } from "./skills.mjs";
 
 /** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
 /** @typedef {import("../host/config.mjs").UserConfig} UserConfig */
+/** @typedef {import("./skills.mjs").SkillRegistration} SkillRegistration */
 /** @typedef {(text: string) => void} Writer */
 /** @typedef {(question: string) => Promise<string>} Asker */
 /** @typedef {{id: string, harness: string, model: string, available: boolean, status: string, missing: string[]}} RuntimeView */
@@ -39,9 +46,11 @@ import { writeUserConfig } from "../host/config.mjs";
  * @property {string} [harnesses]
  * @property {string} [worker]
  * @property {string} [judge]
+ * @property {boolean} [skill] whether to register the faberun skill (default true)
  * @property {boolean} [json]
  * @property {NodeJS.ProcessEnv} [env]
  * @property {() => Promise<Record<string, RuntimeAvailability>>} [discover]
+ * @property {(name: string) => boolean} [isInstalled]
  * @property {Asker} [ask]
  * @property {Writer} [stdout]
  * @property {Writer} [stderr]
@@ -94,7 +103,7 @@ export async function setupCommand(options = {}) {
   }
 
   if (requirements.some((requirement) => !requirement.ok)) {
-    if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+    if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills: [] }, null, 2)}\n`);
     return 1;
   }
 
@@ -107,7 +116,7 @@ export async function setupCommand(options = {}) {
 
   if (availableHarnesses.length === 0) {
     if (json) {
-      stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+      stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills: [] }, null, 2)}\n`);
     } else {
       stdout(`${statusToken("fail", level)} harnesses · none available · install one of: ${INSTALL_HARNESSES.join(", ")}\n`);
     }
@@ -115,7 +124,9 @@ export async function setupCommand(options = {}) {
   }
 
   const candidates = availableCandidates(DISCOVERY_RUNTIME_DEFINITIONS, availability);
-  const defaultWorker = cheapest(candidates)?.id ?? "";
+  const kept = mergeExistingConfig(readUserConfig(env), availability);
+  const defaultHarnesses = kept.harnesses.length > 0 ? kept.harnesses : availableHarnesses;
+  const defaultWorker = kept.worker || (cheapest(candidates)?.id ?? "");
   const interactive = isTTY && !json && !yes
     && options.harnesses === undefined && options.worker === undefined && options.judge === undefined;
 
@@ -124,16 +135,19 @@ export async function setupCommand(options = {}) {
   let selectedWorker;
   let selectedJudge;
   const asker = makeAsker(options.ask);
+  /** @type {SkillRegistration[]} */
+  let skills = [];
   try {
     if (interactive) {
-      const harnessAnswer = (await asker.ask(`Enable which harnesses? [${availableHarnesses.join(", ")}] `)).trim();
-      selectedHarnesses = splitHarnesses(harnessAnswer).length ? splitHarnesses(harnessAnswer) : availableHarnesses;
+      const harnessAnswer = (await asker.ask(`Enable which harnesses? [${defaultHarnesses.join(", ")}] `)).trim();
+      selectedHarnesses = splitHarnesses(harnessAnswer).length ? splitHarnesses(harnessAnswer) : defaultHarnesses;
 
       const workerAnswer = (await asker.ask(`Default worker runtime? [${defaultWorker}] `)).trim();
       selectedWorker = workerAnswer || defaultWorker;
 
-      let judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
-      let judge = judgeAnswer || defaultJudge(selectedWorker, candidates);
+      const judgeDefault = keptJudgeDefault(kept, selectedWorker, candidates);
+      let judgeAnswer = (await asker.ask(`Default judge runtime? [${judgeDefault}] `)).trim();
+      let judge = judgeAnswer || judgeDefault;
       if (!crossVendor(judge, selectedWorker)) {
         stderr("the judge must come from a different vendor than the worker\n");
         judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
@@ -142,35 +156,56 @@ export async function setupCommand(options = {}) {
       }
       selectedJudge = judge;
     } else {
-      selectedHarnesses = splitHarnesses(options.harnesses ?? "").length ? splitHarnesses(options.harnesses ?? "") : availableHarnesses;
+      selectedHarnesses = splitHarnesses(options.harnesses ?? "").length ? splitHarnesses(options.harnesses ?? "") : defaultHarnesses;
       selectedWorker = options.worker ?? defaultWorker;
-      selectedJudge = options.judge ?? defaultJudge(selectedWorker, candidates);
+      selectedJudge = options.judge ?? keptJudgeDefault(kept, selectedWorker, candidates);
       if (!crossVendor(selectedJudge, selectedWorker)) {
-        if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+        if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null, skills }, null, 2)}\n`);
         else stdout(`${statusToken("fail", level)} judge · the judge must come from a different vendor than the worker\n`);
         return 1;
       }
     }
-  } finally {
-    asker.close();
-  }
 
-  const config = {
-    schemaVersion: /** @type {1} */ (1),
-    harnesses: selectedHarnesses,
-    worker: selectedWorker,
-    judge: selectedJudge,
-    updatedAt: new Date().toISOString(),
-  };
-  writeUserConfig(env, config);
+    const config = {
+      schemaVersion: /** @type {1} */ (1),
+      harnesses: selectedHarnesses,
+      worker: selectedWorker,
+      judge: selectedJudge,
+      updatedAt: new Date().toISOString(),
+    };
+    writeUserConfig(env, config);
+    if (!json) stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
 
-  if (json) {
-    stdout(`${JSON.stringify({ requirements, runtimes, config }, null, 2)}\n`);
+    // The offer comes after the config is durable, so a machine that answers
+    // no still has a usable setup. Discovery is `skills.mjs`'s table, reused
+    // rather than re-probed here.
+    const detected = discoverSkillTargets({ env, isInstalled: options.isInstalled })
+      .filter((target) => target.dir !== null && target.dirExists && target.installed && !target.unsupported);
+    if (options.skill !== false && detected.length > 0) {
+      let register = true;
+      if (interactive) {
+        const answer = (await asker.ask(`Register the faberun skill for ${detected.map((target) => target.harness).join(", ")}? [Y/n] `)).trim();
+        register = !answer.toLowerCase().startsWith("n");
+      }
+      if (register) {
+        skills = registerSkills({
+          env,
+          level,
+          isInstalled: options.isInstalled,
+          stdout: json ? () => {} : stdout,
+        });
+      }
+    }
+
+    if (json) {
+      stdout(`${JSON.stringify({ requirements, runtimes, config, skills }, null, 2)}\n`);
+      return 0;
+    }
+    stdout("next · faberun init in a repository · faberun doctor\n");
     return 0;
+  } finally {
+    asker.close();
   }
-  stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
-  stdout("next · faberun init in a repository · faberun doctor\n");
-  return 0;
 }
 
 /**
@@ -225,6 +260,50 @@ function missingEnvKeys(runtime, env) {
   return [...new Set(names)];
 }
 
+/**
+ * The recorded harnesses, worker and judge that discovery still reports
+ * available, so a re-run of setup keeps an operator's earlier choices instead
+ * of resetting them to the fresh-machine defaults. A choice discovery cannot
+ * find is dropped, not kept blindly; the caller fills anything empty with
+ * today's defaults. A null `existing` (no config yet, or a malformed one)
+ * yields nothing kept.
+ *
+ * @param {UserConfig|null} existing
+ * @param {Record<string, RuntimeAvailability>} availability
+ * @returns {{harnesses: string[], worker: string, judge: string}}
+ */
+export function mergeExistingConfig(existing, availability) {
+  if (!existing) return { harnesses: [], worker: "", judge: "" };
+  const availableHarnesses = new Set(
+    Object.entries(DISCOVERY_RUNTIME_DEFINITIONS)
+      .filter(([id]) => availability[id]?.available === true)
+      .map(([, definition]) => definition.harness),
+  );
+  const candidateIds = new Set(
+    availableCandidates(DISCOVERY_RUNTIME_DEFINITIONS, availability).map((candidate) => candidate.id),
+  );
+  return {
+    harnesses: existing.harnesses.filter((harness) => availableHarnesses.has(harness)),
+    worker: existing.worker && candidateIds.has(existing.worker) ? existing.worker : "",
+    judge: existing.judge && candidateIds.has(existing.judge) ? existing.judge : "",
+  };
+}
+
+/**
+ * The judge default for the interactive prompt and `--yes`: the recorded judge
+ * when it is still available and still a different vendor than `workerId`,
+ * otherwise the strongest cross-vendor candidate as today.
+ *
+ * @param {{judge: string}} kept
+ * @param {string} workerId
+ * @param {import("../engine/runtime-discovery.mjs").RuntimeCandidate[]} candidates
+ * @returns {string}
+ */
+function keptJudgeDefault(kept, workerId, candidates) {
+  if (kept.judge && crossVendor(kept.judge, workerId)) return kept.judge;
+  return defaultJudge(workerId, candidates);
+}
+
 /**
  * The strongest available runtime whose vendor differs from the worker's. An
  * empty string means no cross-vendor runtime is available, which the caller