forgedock 1.34.0 → 1.35.0

package/bin/engine-cli.mjs

@@ -214,6 +214,19 @@ export function readBuilderRouting(cwd = process.cwd()) {
   const midModel = /^[A-Za-z0-9._:[\]-]+$/.test(v) ? v : readLeanSetting("builder_mid_model", cwd);
   return mode || midModel ? { ...(mode ? { mode } : {}), ...(midModel ? { midModel } : {}) } : undefined;
 }
+/**
+ * forge.yaml `lean.base_merge_*` (#4588): deterministic base-merge resolution of sibling-lane conflicts. Comma lists of globs
+ * `union_globs` (append-only), `json_globs` (JSON maps, key union), `generated_globs` + `generated_command` (base side taken,
+ * then regenerated) (flat keys only). undefined when nothing is configured.
+ */
+export function readBaseMerge(cwd = process.cwd()) {
+  let l = {};
+  try { l = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.lean ?? {}; } catch { return undefined; }
+  const list = (v) => String(v ?? "").replace(/^\[|\]$/g, "").split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+  const cfg = { unionGlobs: list(l.base_merge_union_globs), jsonGlobs: list(l.base_merge_json_globs), generatedGlobs: list(l.base_merge_generated_globs), generatedCommand: String(l.base_merge_generated_command ?? "").trim() };
+  return cfg.unionGlobs.length || cfg.jsonGlobs.length || cfg.generatedGlobs.length ? cfg : undefined;
+}
+
 /**
  * forge.yaml `lean.sequence.regenerate` (#4386): the command that regenerates a schema-changing migration's snapshot
  * after a deterministic renumber. The one-level parser flattens the nested block to `lean.regenerate`; flat
@@ -323,7 +336,9 @@ export function readMergeWait(cwd = process.cwd()) {
 export function readVerify(cwd = process.cwd()) {
   try {
     const sec = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.verify;
-    return sec && typeof sec === "object" ? parseVerify(sec) : undefined;
+    if (!sec || typeof sec !== "object") return undefined;
+    const invariants = readInvariants(cwd), flaky = readYamlList(cwd, "verify", "flaky");
+    return parseVerify({ ...sec, ...(invariants ? { invariants } : {}), ...(flaky ? { flaky } : {}) });
   } catch { return undefined; }
 }
 /** #4542: forge.yaml `execution.host_capabilities` (+ patterns) for a lane's remote-block mapping; undefined when none are declared. */
@@ -350,20 +365,28 @@ export function readExecution(cwd = process.cwd()) {
  * scalars only. undefined when absent, empty or unreadable.
  */
 export function readPrecheckCommands(cwd = process.cwd()) {
+  return readYamlList(cwd, "learned", "test_commands");
+}
+/** #4585: forge.yaml `verify.invariants`, a block list of repo-wide check commands; undefined when absent or empty. */
+export function readInvariants(cwd = process.cwd()) {
+  return readYamlList(cwd, "verify", "invariants");
+}
+function readYamlList(cwd, section, key) {
   let raw;
   try { raw = readFileSync(join(cwd, "forge.yaml"), "utf8"); } catch { return undefined; }
   const out = [];
-  let inLearned = false, listIndent = null;
+  const head = new RegExp(`^${section}:\\s*(#.*)?$`), keyRe = new RegExp(`^\\s+${key}:\\s*(#.*)?$`);
+  let inSection = false, listIndent = null;
   for (const line of raw.split(/\r?\n/)) {
     if (/^\s*(#.*)?$/.test(line)) continue;
-    if (/^\S/.test(line)) { inLearned = /^learned:\s*(#.*)?$/.test(line); listIndent = null; continue; }
-    if (!inLearned) continue;
+    if (/^\S/.test(line)) { inSection = head.test(line); listIndent = null; continue; }
+    if (!inSection) continue;
     const indent = line.length - line.trimStart().length;
     if (listIndent === null) {
-      if (/^\s+test_commands:\s*(#.*)?$/.test(line)) listIndent = indent;
+      if (keyRe.test(line)) listIndent = indent;
       continue;
     }
-    if (indent <= listIndent) { listIndent = /^\s+test_commands:\s*(#.*)?$/.test(line) ? indent : null; continue; }
+    if (indent <= listIndent) { listIndent = keyRe.test(line) ? indent : null; continue; }
     const m = /^\s+-\s+(.*)$/.exec(line);
     if (!m) continue;
     let v = m[1].trim();
@@ -854,7 +877,7 @@ export async function runFromCli(argv, deps = {}) {
       lres = await runCore({ issue, repo: leanRepo, ...(lane ? { lane } : {}), laneOverride, branches: readBranches(), cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
       onTeardown: (fn) => { teardown = fn; }, ...(env.FORGEDOCK_BATCH_ID ? { batchId: env.FORGEDOCK_BATCH_ID } : {}), ...(placement ? { placement } : {}), ...(recover ? { recover } : {}),
       emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
-      admission: readAdmission(), heavy: readHeavy(), ...readCoreLimits(), ...readEnvConfig(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(readContextPack() ? { contextPack: readContextPack() } : {}), ...(readReviewIncomplete() ? { reviewIncomplete: readReviewIncomplete() } : {}), ...(readLaneInstructions() ? { laneInstructions: readLaneInstructions() } : {}), ...(readReproTest() ? { reproTest: readReproTest() } : {}), ...(readExplore() ? { explore: readExplore() } : {}), light: readLight(), ...(readCloseParent() ? { closeParent: true } : {}), ...(readReviewTrigger() ? { reviewTrigger: readReviewTrigger() } : {}), ...(readVerify() ? { verify: readVerify() } : {}), ...readPrecheckOptions(), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}), ...(readFixModel() ? { fixModel: readFixModel() } : {}), ...(readBuilderRouting() ? { builderRouting: readBuilderRouting() } : {}), ...(readVerifier() ? { verifier: readVerifier() } : {}), ...(readHostCaps() ? { hostCaps: readHostCaps() } : {}) , ...(readSequenceRegenerate() ? { sequenceRegenerate: readSequenceRegenerate() } : {}) });
+      admission: readAdmission(), heavy: readHeavy(), ...readCoreLimits(), ...readEnvConfig(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(readContextPack() ? { contextPack: readContextPack() } : {}), ...(readReviewIncomplete() ? { reviewIncomplete: readReviewIncomplete() } : {}), ...(readLaneInstructions() ? { laneInstructions: readLaneInstructions() } : {}), ...(readReproTest() ? { reproTest: readReproTest() } : {}), ...(readExplore() ? { explore: readExplore() } : {}), light: readLight(), ...(readCloseParent() ? { closeParent: true } : {}), ...(readReviewTrigger() ? { reviewTrigger: readReviewTrigger() } : {}), ...(readVerify() ? { verify: readVerify() } : {}), ...readPrecheckOptions(), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}), ...(readFixModel() ? { fixModel: readFixModel() } : {}), ...(readBuilderRouting() ? { builderRouting: readBuilderRouting() } : {}), ...(readVerifier() ? { verifier: readVerifier() } : {}), ...(readHostCaps() ? { hostCaps: readHostCaps() } : {}) , ...(readSequenceRegenerate() ? { sequenceRegenerate: readSequenceRegenerate() } : {}), ...(readBaseMerge() ? { baseMerge: readBaseMerge() } : {}) });
     } catch (e) { if (!interrupted) report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
     finally { if (!interrupted) for (const [sig, f] of Object.entries(handlers)) off(sig, f); }
     if (interrupted) return lres; // the signal handler reported and exits
@@ -1065,7 +1088,7 @@ export async function orchestrateFromCli(argv, deps = {}) {
 const formatRowLine = (r) => (r.issue == null ? `${r.outcome}: ${r.detail}` : `#${r.issue} → ${r.outcome}${r.detail && r.outcome !== "merged" ? ` (${r.detail})` : ""}`);
 const consoleSink = () => ({ batch: () => {}, row: (r) => console.log(formatRowLine(r)), line: (t) => console.log(t) });
 
-const ORCH_USAGE = "usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--repo owner/repo] | --resume <id> [issue...] | --set-parallel <id> <K> | --add <id> <issue...> | --cancel <id>";
+const ORCH_USAGE = "usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--repo owner/repo] | --resume <id> [issue...] | --set-parallel <id> <K> | --add <id> <issue...> | --cancel <id> | --hold <id> <issue...> | --release <id> <issue...>";
 const ORCH_VALUED = ["--parallel", "--lane", "--repo", "--model", "--prefilter-model"];
 const issuesOf = (argv) => {
   const issues = [];
@@ -1123,6 +1146,29 @@ async function addToBatch({ id, tokens, root, io, viaDaemon = null, print = (l)
   return out;
 }
 
+/** #4592: a resume's release line, only when it freed something. */
+const onlyReleased = (l, out = (t) => console.log(t)) => { if (!l.endsWith("(none)")) out(l); };
+
+/**
+ * `--hold <id> N...` / `--release <id> N...` (#4592): the batch's `hold` file, through the daemon (`viaDaemon(op, issues)`, null
+ * when none runs) or directly. A held issue is not admitted (a running lane is not stopped); `--release` (or a `--resume` that
+ * names it) lets it run again. @returns {{ok, batch, changed:number[]}}
+ */
+async function holdBatch({ op, id, tokens, root, viaDaemon = null, print = (l) => console.log(l) }) {
+  const issues = tokens.filter((t) => /^#?\d+$/.test(String(t))).map((t) => parseInt(String(t).replace("#", ""), 10));
+  if (!id || String(id).startsWith("--") || !issues.length) throw new Error(ORCH_USAGE);
+  let res = viaDaemon ? await viaDaemon(op, issues) : null;
+  if (!res) {
+    const b = (await import("./lean/batch.mjs")).openBatch(root, id);
+    if (!b.exists()) throw new Error(`no batch ${id} in ${root}`);
+    res = { changed: op === "hold" ? b.holdIssues(issues) : b.releaseIssues(issues) };
+  }
+  const list = (res.changed ?? []).map((n) => `#${n}`).join(" ") || "(none)";
+  print(op === "hold" ? `batch ${id}: held ${list}; forgedock orchestrate --release ${id} <issue...> (or --resume ${id} <issue...>) re-admits them`
+    : `batch ${id}: released ${list}`);
+  return { ok: true, batch: id, changed: res.changed ?? [] };
+}
+
 /**
  * `--cancel <id>` (#4376): through the daemon (`viaDaemon`, null when none runs) or the batch's `cancel` file directly.
  * A finished batch (report written) is left alone.
@@ -1172,6 +1218,11 @@ async function orchestrateClient(argv, deps = {}) {
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
     return sock ? schedd.request(sock, { op: "add", id, issues }) : null;
   };
+  const holdVia = (id) => async (op, issues) => {
+    let sock = null;
+    try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { sock = null; }
+    return sock ? schedd.request(sock, { op, id, issues }) : null;
+  };
   const batchRootOf = async () => (await import("./lean/batch.mjs")).batchRoot();
   if (argv.includes("--cancel")) {
     const id = flag(argv, "--cancel");
@@ -1181,6 +1232,10 @@ async function orchestrateClient(argv, deps = {}) {
       return sock ? schedd.request(sock, { op: "cancel", id }) : null;
     } });
   }
+  for (const op of ["hold", "release"]) if (argv.includes(`--${op}`)) {
+    const id = flag(argv, `--${op}`);
+    return holdBatch({ op, id, tokens: operandsOf(argv.slice(argv.indexOf(`--${op}`) + 2)), root: await batchRootOf(), viaDaemon: holdVia(id) });
+  }
   if (argv.includes("--add")) {
     const i = argv.indexOf("--add"), id = argv[i + 1];
     if (!id || i + 2 >= argv.length) throw new Error(ORCH_USAGE);
@@ -1190,9 +1245,10 @@ async function orchestrateClient(argv, deps = {}) {
   const resumeExtra = resumeId ? operandsOf(argv.slice(argv.indexOf("--resume") + 2)) : [];
   if (resumeExtra.length) {
     await addToBatch({ id: resumeId, tokens: resumeExtra, root: await batchRootOf(), io: deps.io ?? makeIo(), viaDaemon: addVia(resumeId) });
+    await holdBatch({ op: "release", id: resumeId, tokens: resumeExtra, root: await batchRootOf(), viaDaemon: holdVia(resumeId), print: (l) => onlyReleased(l) }); // #4592: a named, held issue is re-admitted
   }
   let msg;
-  if (resumeId) msg = { op: "attach", id: resumeId };
+  if (resumeId) msg = { op: "attach", id: resumeId, resume: true };
   else {
     if (!issuesOf(argv).length) throw new Error(ORCH_USAGE);
     parallelOf(argv);
@@ -1255,6 +1311,9 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     return { ok: true, batch: b.id, parallel: k };
   }
   if (argv.includes("--cancel")) return cancelBatch({ id: flag(argv, "--cancel"), root, print: (l) => sink.line(l) });
+  for (const op of ["hold", "release"]) if (argv.includes(`--${op}`)) {
+    return holdBatch({ op, id: flag(argv, `--${op}`), tokens: operandsOf(argv.slice(argv.indexOf(`--${op}`) + 2)), root, print: (l) => sink.line(l) });
+  }
   if (argv.includes("--add")) {
     const i = argv.indexOf("--add");
     if (!argv[i + 1] || i + 2 >= argv.length) throw new Error(ORCH_USAGE);
@@ -1264,6 +1323,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   const resumeExtra = resumeId ? operandsOf(argv.slice(argv.indexOf("--resume") + 2)) : [];
   if (resumeExtra.length) {
     await addToBatch({ id: resumeId, tokens: resumeExtra, root, io: deps.io ?? makeIo(), print: (l) => sink.line(l) });
+    await holdBatch({ op: "release", id: resumeId, tokens: resumeExtra, root, print: (l) => onlyReleased(l, (t) => sink.line(t)) }); // #4592
   }
   let batch, plan = null;
   if (resumeId) {
@@ -1340,7 +1400,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     const { runCore } = deps.leanModule;
     const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
     lanes = { adopt: null, runOne: (n, ln, ctx = {}) => runCore({ issue: n, repo, lane: ln, laneOverride, ...(ctx.placement ? { placement: { ...ctx.placement, mode: execMode() } } : {}), ...(ctx.recover ? { recover: ctx.recover } : {}), branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry, batchId: batch.id,
-      admission: readAdmission(cwd), heavy: readHeavy(cwd), ...readCoreLimits(cwd), ...readEnvConfig(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(readContextPack(cwd) ? { contextPack: readContextPack(cwd) } : {}), ...(readReviewIncomplete(cwd) ? { reviewIncomplete: readReviewIncomplete(cwd) } : {}), ...(readLaneInstructions(cwd) ? { laneInstructions: readLaneInstructions(cwd) } : {}), ...(readReproTest(cwd) ? { reproTest: readReproTest(cwd) } : {}), ...(readExplore(cwd) ? { explore: readExplore(cwd) } : {}), light: readLight(cwd), ...(readCloseParent(cwd) ? { closeParent: true } : {}), ...(readReviewTrigger(cwd) ? { reviewTrigger: readReviewTrigger(cwd) } : {}), ...(readVerify(cwd) ? { verify: readVerify(cwd) } : {}), ...readPrecheckOptions(cwd), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}), ...(readFixModel(cwd) ? { fixModel: readFixModel(cwd) } : {}), ...(readBuilderRouting(cwd) ? { builderRouting: readBuilderRouting(cwd) } : {}), ...(readVerifier(cwd) ? { verifier: readVerifier(cwd) } : {}), ...(readHostCaps(cwd) ? { hostCaps: readHostCaps(cwd) } : {}), ...(readSequenceRegenerate(cwd) ? { sequenceRegenerate: readSequenceRegenerate(cwd) } : {}) }) };
+      admission: readAdmission(cwd), heavy: readHeavy(cwd), ...readCoreLimits(cwd), ...readEnvConfig(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(readContextPack(cwd) ? { contextPack: readContextPack(cwd) } : {}), ...(readReviewIncomplete(cwd) ? { reviewIncomplete: readReviewIncomplete(cwd) } : {}), ...(readLaneInstructions(cwd) ? { laneInstructions: readLaneInstructions(cwd) } : {}), ...(readReproTest(cwd) ? { reproTest: readReproTest(cwd) } : {}), ...(readExplore(cwd) ? { explore: readExplore(cwd) } : {}), light: readLight(cwd), ...(readCloseParent(cwd) ? { closeParent: true } : {}), ...(readReviewTrigger(cwd) ? { reviewTrigger: readReviewTrigger(cwd) } : {}), ...(readVerify(cwd) ? { verify: readVerify(cwd) } : {}), ...readPrecheckOptions(cwd), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}), ...(readFixModel(cwd) ? { fixModel: readFixModel(cwd) } : {}), ...(readBuilderRouting(cwd) ? { builderRouting: readBuilderRouting(cwd) } : {}), ...(readVerifier(cwd) ? { verifier: readVerifier(cwd) } : {}), ...(readHostCaps(cwd) ? { hostCaps: readHostCaps(cwd) } : {}), ...(readSequenceRegenerate(cwd) ? { sequenceRegenerate: readSequenceRegenerate(cwd) } : {}), ...(readBaseMerge(cwd) ? { baseMerge: readBaseMerge(cwd) } : {}) }) };
   } else {
     const laneScript = deps.laneScript ?? fileURLToPath(new URL("./forgedock.mjs", import.meta.url));
     // #4256: the placement orchestrate decided for a lane (ctx.placement) reaches it as --placement/--placement-reason.
@@ -1520,7 +1580,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     rows = await orchestrate({
       ...(estimate ? { estimate } : {}),
       beforeAdmit,
-      issues, parallel, prefilter, resolveLane: laneOf, store: batch.store, getParallel: batch.readParallel, getAdded: batch.readAdded, getCancelled: batch.readCancel, ...lanes,
+      issues, parallel, prefilter, resolveLane: laneOf, store: batch.store, getParallel: batch.readParallel, getAdded: batch.readAdded, getCancelled: batch.readCancel, getHeld: batch.readHeld, ...lanes,
       breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(deps.pollMs ? { pollMs: deps.pollMs } : {}), ...budget, limits, identity, batchId: batch.id, drift,
       ...(registry ? { sched: { registry, batch: batch.id, repo, cap: orch.globalParallel ?? null, exclusive: true }, priorityOf: async (n) => schedMod.priorityFromLabels(await labelNames(n)) } : {}),
       ...(remote ? { remote } : {}),
@@ -1757,7 +1817,7 @@ export async function checkFromCli(argv, deps = {}) {
   const plan = await readJson(pre.CHECK_PLAN_FILE);
   const base = o.base ?? plan?.base;
   if (!base) throw Object.assign(new Error(`check: no check plan from the engine; pass --base REF\n${usage}`), { exitCode: 2 });
-  const verify = plan ? { mode: plan.mode, precheckTotalSeconds: plan.precheckTotalSeconds, precheckTimeoutSeconds: plan.precheckTimeoutSeconds } : { ...parseVerify({}), ...(readVerify(repo) ?? {}) };
+  const verify = plan ? { mode: plan.mode, precheckTotalSeconds: plan.precheckTotalSeconds, precheckTimeoutSeconds: plan.precheckTimeoutSeconds, invariants: Array.isArray(plan.invariants) ? plan.invariants : [] } : { ...parseVerify({}), ...(readVerify(repo) ?? {}) };
   const learned = plan ? plan.learned : readPrecheckCommands(repo) ?? [];
   const maxMinutes = plan ? plan.maxMinutes : readPrecheckBudget(repo);
   // the engine's changed files (lean.mjs changedFiles: base...HEAD still differing from base), plus uncommitted work

package/bin/forgedock.mjs

@@ -13,6 +13,7 @@ import {
   renameSync,
   unlinkSync,
 } from "fs";
+import { gitignoreAdditions } from "./lean/toolstate.mjs";
 import { execSync, execFileSync, spawnSync } from "child_process";
 import { homedir } from "os";
 import https from "https";
@@ -1025,6 +1026,20 @@ async function statusScreen(c) {
  *                            Independent of FORGEDOCK_BACKEND, which controls
  *                            the separate `forgedock run` engine backend.
  */
+/** #4590: append the tool-state deny-list (.forge-lean/, tool caches) to the repo's .gitignore; append-only, idempotent. */
+function ensureToolStateIgnored(c) {
+  try {
+    const file = join(c.cwd, ".gitignore");
+    const text = existsSync(file) ? readFileSync(file, "utf-8") : "";
+    let next = false;
+    try { next = Boolean(JSON.parse(readFileSync(join(c.cwd, "package.json"), "utf-8"))?.dependencies?.next); } catch { /* no package.json */ }
+    const add = gitignoreAdditions(text, { next });
+    if (!add.length) return;
+    writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}# ForgeDock lane scratch and tool caches\n${add.join("\n")}\n`);
+    c.stdout.write(`  .gitignore: added ${add.join(", ")}\n`);
+  } catch { /* .gitignore is best effort */ }
+}
+
 async function initFlow(c) {
   const outputPath = join(c.cwd, "forge.yaml");
   const hasExisting = existsSync(outputPath);
@@ -1078,6 +1093,7 @@ async function initFlow(c) {
       stagingBranch: draft.branches.staging.value,
     });
     atomicWriteFile(outputPath, content);
+    ensureToolStateIgnored(c);
     celebrate(c, { written: true, todoCount: 0, isMinimal: true });
     await maybeOfferDemo(c);
     return 0;
@@ -1107,12 +1123,14 @@ async function initFlow(c) {
     if (backup) c.stdout.write(`  Backed up: forge.yaml → ${backup.backupName}\n`);
     const lowKeys = manualLowConfidenceKeys(draft, description, v);
     const { todoCount } = writeForgeYaml(v, lowKeys, outputPath);
+    ensureToolStateIgnored(c);
     celebrate(c, { written: true, todoCount });
     await maybeOfferDemo(c);
     return 0;
   }
   const { draft, description } = await setupAfterRead(c, await read(c));
   const reviewed = await review(c, draft, description);
+  if (!reviewed.aborted) ensureToolStateIgnored(c);
   celebrate(c, reviewed);
   if (!reviewed.aborted) await maybeOfferDemo(c);
   return reviewed.aborted ? 1 : 0;
@@ -3297,7 +3315,7 @@ function help() {
     ["npx forgedock bootstrap <idea|docs> [--dry-run] [--spike <path>] | --plan <plan.json> [--dry-run]", "Headless /bootstrap: idea to orchestrate-ready backlog (--dry-run previews milestones, titles, DAG and estimated agent cost without GitHub writes); --plan validates and creates (or previews) a plan, and re-running resumes from GitHub"],
     ["npx forgedock run-issue <issue> [--lane <lane>] [--lane-override] [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline; the lane comes from the issue: milestone → milestone/<slug>, else staging; --lane is an assertion, never the default branch) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering; each issue on its own lane, cross-lane dependencies reported"],
-    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --cancel <id>", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), change its concurrency live, add issues to a running (or held) batch under its K and DAG, or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume)"],
+    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --cancel <id> | --hold <id> N... | --release <id> N...", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), change its concurrency live, add issues to a running (or held) batch under its K and DAG, or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume), or hold/release single issues of a batch (a held issue is not admitted until released or named by --resume)"],
     ["npx forgedock triage <issue...> [--lane L] [--dry-run]", "Already-fixed pre-filter: close issues a merged PR or green CI already resolved; print the rest"],
     ["npx forgedock probe [issue...] [--dry-run]", "Run declared acceptance probes for closed issues whose fix is on the default branch; a fail reopens the issue"],
     ["npx forgedock check [--base REF] [--json]", "Run the lane's frozen validate commands and change-scoped pre-PR checks locally in this worktree, as the engine will (no GitHub, no Actions)"],

package/bin/hooks/reread-nudge.mjs

@@ -6,9 +6,12 @@
  * (bin/lean/effects.mjs rereadNudgeFlags). It counts reads per path for one session, using the #4410 telemetry's
  * definition of a read (toolstats readPaths), and on exactly the REREAD_MIN-th read of a path it returns an
  * `additionalContext` system reminder. Advisory only: it always exits 0 and an error produces no output.
- * State: {path: count} in <tmpdir>/forgedock-reread/<session_id>.json (a per-run cache).
+ * #4580: the same script is also a PreToolUse guard on Read: a full-file Read (no offset/limit) of a path already read
+ * REREAD_MIN-1 times whose mtime is unchanged since its last read is denied with a reason that points at notes or a line
+ * range. Ranged reads and Bash never deny, and any error allows. A changed mtime resets the path's count.
+ * State: {path: count} in <tmpdir>/forgedock-reread/<session_id>.json plus {path: mtimeMs} in <session_id>.mtime.json (per-run caches).
  */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -38,18 +41,43 @@ export function nudgeFor(payload, counts = {}) {
 export const stateFile = (sessionId, dir = join(tmpdir(), "forgedock-reread")) =>
   join(dir, `${String(sessionId).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "session"}.json`);
 
+const mtimeOf = (p) => { try { return statSync(p).mtimeMs; } catch { return null; } };
+const loadJson = (file) => { try { const v = JSON.parse(readFileSync(file, "utf8")); return v && typeof v === "object" ? v : {}; } catch { return {}; } };
+
+/** Pure core of the guard: the deny reason for a payload, or null. `mtimeNow(path)` is the file's current mtime. */
+export function guardFor(payload, counts = {}, mtimes = {}, mtimeNow = mtimeOf) {
+  const inp = payload?.tool_input ?? {};
+  if (payload?.tool_name !== "Read" || inp.offset != null || inp.limit != null) return null;
+  for (const p of payloadReads(payload)) {
+    const now = mtimeNow(p);
+    if (now != null && (counts[p] ?? 0) >= REREAD_MIN - 1 && mtimes[p] === now)
+      return `${p} has already been read ${counts[p]} times in this session and has not changed: use your notes or the excerpt already in context; `
+        + "if you need a different part, read only that line range (offset and limit).";
+  }
+  return null;
+}
+
 /** One hook call: stdin JSON in, the hookSpecificOutput line (or nothing) out. Fails open. */
 export function main(input, { dir } = {}) {
   try {
     const payload = JSON.parse(input);
     if (!payload?.session_id) return "";
     if (!payloadReads(payload).length) return "";
-    const file = stateFile(payload.session_id, dir);
-    let counts = {};
-    try { counts = JSON.parse(readFileSync(file, "utf8")) ?? {}; } catch { /* first read of this session */ }
+    const file = stateFile(payload.session_id, dir), mfile = file.replace(/\.json$/, ".mtime.json");
+    const counts = loadJson(file), mtimes = loadJson(mfile);
+    if (payload.hook_event_name === "PreToolUse") {
+      const reason = guardFor(payload, counts, mtimes);
+      return reason ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } })}\n` : "";
+    }
+    for (const p of payloadReads(payload)) {
+      const now = mtimeOf(p);
+      if (now != null && mtimes[p] !== now) delete counts[p]; // the file changed (or is new): earlier reads no longer count
+      if (now != null) mtimes[p] = now;
+    }
     const r = nudgeFor(payload, counts);
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(r.counts));
+    writeFileSync(mfile, JSON.stringify(mtimes));
     return r.message ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: r.message } })}\n` : "";
   } catch {
     return "";

package/bin/lean/batch.mjs

@@ -6,6 +6,7 @@
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
  * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
  * `add` (issues added to the batch by `--add`, #4408: a cumulative JSON set the runner re-reads every pass),
+ * `hold` (issues held by `--hold`, #4592: a cumulative JSON set; the runner admits none of them until `--release` or a `--resume` names them),
  * `cancel` (`{at, reason}` written by `--cancel`, #4376: the runner stops admitting and stops its local lanes; a resume clears it),
  * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
  * when the scheduler loop returns; `forgedock orchestrate --resume` on a finished batch replays it, #4192). Every write is tmp + fsync + rename, and the root must be
@@ -68,6 +69,9 @@ const readAdded = (file) => {
   return Array.isArray(v) ? [...new Set(v.filter((n) => Number.isSafeInteger(n) && n > 0))].sort((a, b) => a - b) : [];
 };
 
+/** The positive integers among `list` (numbers, `7`, `#7`). */
+const ints = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN)).filter((n) => Number.isSafeInteger(n) && n > 0);
+
 export function newBatchId(now = Date.now(), pid = process.pid) {
   return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
 }
@@ -118,6 +122,22 @@ export function openBatch(root, id) {
       if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
       return { added, skipped };
     },
+    /** Issues held by `--hold` (#4592): the `hold` file, sorted unique positive integers; [] when missing or invalid. */
+    readHeld: () => readAdded(f("hold")),
+    /** Merge the positive integers of `list` into the `hold` file. @returns {number[]} the issues newly held */
+    holdIssues: (list) => {
+      const have = new Set(readAdded(f("hold")));
+      const added = [...new Set(ints(list))].filter((n) => !have.has(n)).sort((a, b) => a - b);
+      if (added.length) writeAtomic(f("hold"), JSON.stringify([...have, ...added].sort((a, b) => a - b)) + "\n");
+      return added;
+    },
+    /** Remove `list` from the `hold` file. @returns {number[]} the issues that were held */
+    releaseIssues: (list) => {
+      const have = new Set(readAdded(f("hold")));
+      const freed = [...new Set(ints(list))].filter((n) => have.has(n)).sort((a, b) => a - b);
+      if (freed.length) writeAtomic(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
+      return freed;
+    },
     /** `--cancel` (#4376): `{at, reason}` in the `cancel` file; the runner re-reads it every pass. */
     requestCancel: ({ reason = "operator" } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason) }) + "\n"),
     /** The cancel record, or null when missing or invalid. */
@@ -146,7 +166,10 @@ export function isLaneAlive(pid, marker, { kill = process.kill.bind(process), pr
   if (!existsSync(procDir)) return true;
   let cmd;
   try { cmd = readFileSync(join(procDir, String(pid), "cmdline"), "utf8"); } catch { return false; }
-  return !marker || cmd.split("\0").includes(marker);
+  if (marker && !cmd.split("\0").includes(marker)) return false;
+  // A zombie (exited, not yet reaped: PID 1 may not reap) answers `kill(pid, 0)` but is not running.
+  try { if (/^\d+ \(.*\) Z /s.test(readFileSync(join(procDir, String(pid), "stat"), "utf8"))) return false; } catch { /* no stat: treat as alive */ }
+  return true;
 }
 
 /**

package/bin/lean/batch.test.mjs

@@ -213,6 +213,14 @@ await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--
     assert.doesNotThrow(() => assertDiskPath("/home/u/.forge/batches", mounts));
     assert.equal(isLaneAlive(process.pid, "--definitely-not-in-my-cmdline"), false);
     assert.equal(isLaneAlive(2 ** 22 + 12345, null), false);
+    // #4592: a zombie answers kill(pid, 0) but is not a live lane.
+    const proc = tmpDir("proc-"), pd = join(proc, "42");
+    mkdirSync(pd, { recursive: true });
+    writeFileSync(join(pd, "cmdline"), "node\0lane\0");
+    writeFileSync(join(pd, "stat"), "42 (node) S 1 42 42 0 -1\n");
+    assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), true);
+    writeFileSync(join(pd, "stat"), "42 (no) de) Z 1 42 42 0 -1\n");
+    assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), false);
     assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
     writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n  global_parallel: 4\n");
     assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2, globalParallel: 4, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
@@ -760,3 +768,70 @@ describe("#4547: opt-in local fallback in mode remote when no pool agent is onli
     }
   });
 });
+
+describe("#4592: forgedock orchestrate --hold / --release", () => {
+  it("the hold file: holdIssues / readHeld / releaseIssues merge sorted unique positive integers; invalid content reads as []", () => {
+    const b = openBatch(tmpDir("batch-hold-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    assert.deepEqual(b.readHeld(), []);
+    assert.deepEqual(b.holdIssues([5, "#3", "x", 0, 5, "7"]), [3, 5, 7]);
+    assert.deepEqual(b.holdIssues([3, 9]), [9], "already held is not newly held");
+    assert.deepEqual(b.readHeld(), [3, 5, 7, 9]);
+    assert.deepEqual(b.releaseIssues([5, 4, "#9"]), [5, 9]);
+    assert.deepEqual(b.readHeld(), [3, 7]);
+    writeFileSync(join(b.dir, "hold"), "not json");
+    assert.deepEqual(b.readHeld(), []);
+  });
+
+  it("a held issue is never admitted; the rest run, the batch ends with it held, and a release (resume) runs it", async () => {
+    let saved = null, held = [2];
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [], log = [];
+    const run = (issues) => orchestrate({ issues, parallel: 2, pollMs: 5, readBody: async () => "", store, getHeld: () => held, onUpdate: (r) => log.push(r),
+      runOne: async (n) => { started.push(n); return { terminalReason: "merged" }; } });
+    const rows = await run([1, 2, 3]);
+    assert.deepEqual(started.sort(), [1, 3], "#2 is not admitted");
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "held"], [3, "merged"]]);
+    assert.equal(rows[1].detail, "held by operator");
+    assert.equal(log.filter((r) => r.outcome === "hold").length, 1, "one row when the set changes");
+    held = [];
+    const resumed = await run([]);
+    assert.deepEqual(resumed.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.deepEqual(started.sort(), [1, 2, 3]);
+  });
+
+  it("a release while another lane runs admits the held issue in the same batch", async () => {
+    let saved = null, held = [2], free;
+    const gate = new Promise((r) => { free = r; });
+    const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+    const started = [];
+    const done = orchestrate({ issues: [1, 2], parallel: 2, pollMs: 5, readBody: async () => "", store, getHeld: () => held,
+      runOne: async (n) => { started.push(n); if (n === 1) await gate; return { terminalReason: "merged" }; } });
+    await until(() => started.includes(1));
+    await new Promise((r) => setTimeout(r, 30));
+    assert.deepEqual(started, [1]);
+    held = [];
+    await until(() => started.includes(2));
+    free();
+    assert.deepEqual((await done).map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"]]);
+  });
+
+  it("through the CLI: --hold / --release write the hold file (usage and unknown batch reject); --resume <id> N releases N", async () => {
+    const root = tmpDir("batch-hold-cli-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: [], repo: "o/r" });
+    b.store.save({ order: [1, 2] });
+    const io = { gh: async () => JSON.stringify({ state: "OPEN" }) };
+    let res = await quiet(() => orchestrateFromCli(["--hold", "b1", "1", "2"], { batchRoot: root, io }));
+    assert.deepEqual(res.changed, [1, 2]);
+    res = await quiet(() => orchestrateFromCli(["--release", "b1", "1"], { batchRoot: root, io }));
+    assert.deepEqual(res.changed, [1]);
+    assert.deepEqual(b.readHeld(), [2]);
+    await assert.rejects(orchestrateFromCli(["--hold", "b1"], { batchRoot: root, io }), /usage/);
+    await assert.rejects(orchestrateFromCli(["--hold", "nope", "1"], { batchRoot: root, io }), /no batch nope/);
+    // A resume naming a held issue re-admits it (the plan has no issues, so the resume stops with the usage error after that step).
+    await assert.rejects(quiet(() => orchestrateFromCli(["--resume", "b1", "2"], { batchRoot: root, io })), /usage/);
+    assert.deepEqual(b.readHeld(), []);
+    assert.deepEqual(b.readAdded(), [], "an issue already in the batch is not added again");
+  });
+});

package/bin/lean/budget.mjs

@@ -42,6 +42,17 @@ export const nextSize = (size) => (SIZES.includes(size) ? SIZES[Math.min(SIZES.i
 /** #4505: a `budget.exceeded` recovery lane runs at the next size's budget; any other lane keeps its size. */
 export const recoverySize = (size, recover) => (recover?.code === "budget.exceeded" ? nextSize(size) : size);
 
+/**
+ * Extra implement turns for a big L lane (#4587): +10 per distinct deliverable path above 5, capped at +2x the L base;
+ * a `budget.exceeded` recovery of an L lane adds +ceil(base/2) so it gets more than the pass that failed.
+ * 0 for S/M, an unsized lane or a disabled (0) base.
+ */
+export function scaledExtra({ size, contract = null, recover = null, base = TURN_BUDGET_DEFAULTS.L } = {}) {
+  if (size !== "L" || !(base > 0)) return 0;
+  const paths = Array.isArray(contract?.deliverables) ? new Set(contract.deliverables.map((d) => d?.path).filter((p) => typeof p === "string" && p.trim())).size : 0;
+  return Math.min(10 * Math.max(0, paths - 5), 2 * base) + (recover?.code === "budget.exceeded" ? Math.ceil(base / 2) : 0);
+}
+
 /** Turns the wrap-up call may use after the budget is spent. */
 export const wrapupGrant = (budget) => Math.max(5, Math.ceil(budget / 5));
 
@@ -52,10 +63,10 @@ export const wrapupGrant = (budget) => Math.max(5, Math.ceil(budget / 5));
  */
 export function makeTurnBudget(budgets = TURN_BUDGET_DEFAULTS) {
   const b = { ...TURN_BUDGET_DEFAULTS, ...(budgets ?? {}) };
-  let size = null, build = 0, total = 0, exceeded = false;
-  const budget = () => (size && Number.isFinite(b[size]) && b[size] > 0 ? b[size] : 0);
+  let size = null, extra = 0, build = 0, total = 0, exceeded = false;
+  const budget = () => (size && Number.isFinite(b[size]) && b[size] > 0 ? b[size] + extra : 0);
   return {
-    setSize(s) { if (SIZES.includes(s)) size = s; },
+    setSize(s, add = 0) { if (SIZES.includes(s)) { size = s; extra = Number.isFinite(add) && add > 0 ? Math.floor(add) : 0; } },
     get size() { return size; },
     budget,
     on: () => budget() > 0,

package/bin/lean/budget.test.mjs

@@ -5,7 +5,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { writeFileSync, chmodSync } from "node:fs";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { TURN_BUDGET_DEFAULTS, parseTurnBudgets, laneSize, nextSize, recoverySize, wrapupGrant, makeTurnBudget, budgetDigest, formatTurnSummary } from "./budget.mjs";
+import { TURN_BUDGET_DEFAULTS, parseTurnBudgets, laneSize, nextSize, recoverySize, wrapupGrant, makeTurnBudget, scaledExtra, budgetDigest, formatTurnSummary } from "./budget.mjs";
 import { orchestrate } from "./orchestrate.mjs";
 import { OUTCOME_CODES, RECOVERABLE_CODES } from "../engine/outcome-codes.mjs";
 import { RECOVER_HOW } from "./lean.mjs";
@@ -54,6 +54,16 @@ describe("#4392 turn budget", () => {
     assert.equal(wrapupGrant(25), 5); assert.equal(wrapupGrant(100), 20); assert.equal(wrapupGrant(3), 5);
   });
 
+  it("#4587 L budgets scale with the contract (+10/path over 5, cap +2x) and an L recovery gets more; S/M and off unchanged", () => {
+    const b = (n, size = "L", recover = null) => { const tb = makeTurnBudget(); tb.setSize(size, scaledExtra({ size, contract: contract(n), recover })); return tb.budget(); };
+    assert.equal(b(6), 110); assert.equal(b(15), 200); assert.equal(b(40), 300);
+    assert.equal(b(5, "L"), 100);
+    assert.equal(b(15, "L", { code: "budget.exceeded" }), 250); assert.ok(b(6, "L", { code: "budget.exceeded" }) > b(6));
+    assert.equal(b(15, "M"), 60); assert.equal(b(1, "S"), 25);
+    assert.equal(scaledExtra({ size: "L", contract: contract(15), base: 0 }), 0);
+    const off = makeTurnBudget({ L: 0 }); off.setSize("L", 50); assert.equal(off.on(), false);
+  });
+
   it("the digest is the builder's (capped), else the diff stat and the last self-check", () => {
     const d = budgetDigest({ size: "M", budget: 60, used: 66, digest: "x".repeat(5000) });
     assert.match(d, /size M, 60 turns; 66 used/); assert.ok(d.length < 1800);

package/bin/lean/conflictres.mjs

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Deterministic base-merge conflict resolution for sibling lanes (#4588). Sibling lanes of one milestone always collide
+ * on the same kinds of file once one lands; `resolveBaseConflicts` settles them while a base merge is in progress (ours =
+ * the lane, theirs = the base), with no builder session:
+ *   - `unionGlobs`: append-only lists; hunks where both sides purely added lines keep both (basesync.mjs `unionResolve`).
+ *   - `jsonGlobs`: JSON maps (status files); a 3-way key union. A key both sides changed differently, or a non-object
+ *     document, is refused.
+ *   - `generatedGlobs`: the base side is taken, then `generatedCommand` runs once and the files are re-added.
+ * Sequence/migration files are never touched here (sequence.mjs). A file that cannot be fully resolved stays conflicted
+ * and is returned in `remaining`. Resolved files are `git add`ed; the caller commits. Never throws.
+ */
+import { execFile } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { isSequenceFile, matchesGlobs, unionResolve } from "./basesync.mjs";
+
+const pexec = promisify(execFile);
+const defaultRun = (cmd, { cwd }) => pexec("sh", ["-c", cmd], { cwd, timeout: 600000, maxBuffer: 50 * 1024 * 1024 });
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const NONE = Symbol("absent");
+
+/** 3-way merge of parsed JSON (NONE = absent): one-sided changes win, objects merge per key, anything else throws. */
+export function jsonMerge(base, ours, theirs) {
+  if (same(ours, theirs) || same(theirs, base)) return ours;
+  if (same(ours, base)) return theirs;
+  if (!isObj(ours) || !isObj(theirs) || !(isObj(base) || base === NONE)) throw new Error("both sides changed the same value");
+  const b = isObj(base) ? base : {}, out = {};
+  for (const k of [...Object.keys(ours), ...Object.keys(theirs)]) {
+    if (k in out) continue;
+    const v = jsonMerge(k in b ? b[k] : NONE, k in ours ? ours[k] : NONE, k in theirs ? theirs[k] : NONE);
+    if (v !== NONE) out[k] = v;
+  }
+  return out;
+}
+
+/** The merged text of a JSON map file from index stages 1-3, written with the lane's indent; throws when it cannot merge. */
+export function jsonUnionText(baseTxt, oursTxt, theirsTxt) {
+  const base = baseTxt === null ? NONE : JSON.parse(baseTxt), ours = JSON.parse(oursTxt), theirs = JSON.parse(theirsTxt);
+  if (!isObj(ours) || !isObj(theirs)) throw new Error("not a JSON object");
+  const indent = /^([ \t]+)"/m.exec(oursTxt)?.[1] ?? 2;
+  return `${JSON.stringify(jsonMerge(base, ours, theirs), null, indent)}\n`;
+}
+
+/**
+ * @param {{git:(args:string[])=>Promise<string>, cwd:string, files:string[], cfg?:{unionGlobs?:string[],jsonGlobs?:string[],generatedGlobs?:string[],generatedCommand?:string}, run?:Function}} p
+ *   `git` runs in the worktree with the merge in progress and throws on failure.
+ * @returns {Promise<{resolved:string[], remaining:string[], note?:string}>}
+ */
+export async function resolveBaseConflicts({ git, cwd, files = [], cfg = {}, run = defaultRun }) {
+  const resolved = [], remaining = [];
+  try {
+    const stages = new Map();
+    for (const l of lines(await git(["-c", "core.quotepath=off", "ls-files", "-u"]).catch(() => ""))) {
+      const m = /^\d+ \S+ (\d)\t(.+)$/.exec(l); if (m) stages.set(m[2], (stages.get(m[2]) ?? 0) + (1 << Number(m[1])));
+    }
+    const generated = [];
+    for (const f of files) {
+      let ok = false;
+      try {
+        const st = stages.get(f);
+        if (isSequenceFile(f)) ok = false;
+        else if (matchesGlobs(f, cfg.generatedGlobs) && cfg.generatedCommand && (st & 8)) { await git(["checkout", "--theirs", "--", f]); generated.push(f); ok = true; }
+        else if (st === 14 && matchesGlobs(f, cfg.jsonGlobs)) {
+          const show = (n) => git(["show", `:${n}:${f}`]);
+          writeFileSync(join(cwd, f), jsonUnionText(await show(1), await show(2), await show(3))); ok = true;
+        } else if (st === 14 && matchesGlobs(f, cfg.unionGlobs)) {
+          await git(["checkout", "--conflict=diff3", "--", f]);
+          const text = unionResolve(readFileSync(join(cwd, f), "utf8"));
+          if (text !== null) { writeFileSync(join(cwd, f), text); ok = true; }
+        }
+      } catch { ok = false; }
+      if (ok) resolved.push(f); else remaining.push(f);
+    }
+    let note;
+    if (generated.length) {
+      try { await run(cfg.generatedCommand, { cwd }); } catch (e) {
+        note = `generated command failed: ${String(e?.stderr || e?.message || e).trim().split("\n")[0].slice(0, 160)}`;
+        for (const f of generated) { await git(["checkout", "-m", "--", f]).catch(() => {}); resolved.splice(resolved.indexOf(f), 1); remaining.push(f); }
+        generated.length = 0;
+      }
+    }
+    for (const f of resolved) await git(["add", "--", f]);
+    for (const f of generated) await git(["add", "-A", "--", f]);
+    return { resolved, remaining: files.filter((f) => remaining.includes(f)), ...(note ? { note } : {}) };
+  } catch (e) {
+    return { resolved: [], remaining: [...files], note: String(e?.message ?? e).split("\n")[0].slice(0, 160) };
+  }
+}