forgedock 1.32.0 → 1.33.0

package/bin/engine/outcome-codes.mjs

@@ -46,10 +46,12 @@ export const OUTCOME_CODES = Object.freeze({
   INFRA_DISK_QUOTA: "infra.disk_quota",
   INFRA_CLI_SPAWN_TRANSIENT: "infra.cli_spawn_transient",
   CLI_TIMEOUT: "cli.timeout",
+  CLI_HOST_KILLED: "cli.host_killed", // forge#4518: the builder CLI was SIGTERM/SIGKILLed from outside (host, OOM guard, operator); deferred, never counted by the breaker
   CLI_SPAWN_FAILED: "cli.spawn_failed", // forge#4129: deterministic spawn failure (E2BIG, ENOENT, EACCES, ...)
   ENV_SETUP_FAILED: "env.setup_failed", // forge#4163: forge.yaml env.setup failed before the builder; an environment error, not a build failure
   ENV_TOOL_MISSING: "env.tool_missing", // forge#4323: a validate command could not run because a host tool or module is missing; an environment error, not a conformance failure
   ENV_REPRO_UNRUNNABLE: "env.repro_unrunnable", // forge#4334: the repro harness could not run the repro test on head; an environment error, not a conformance failure
+  ENV_CAPABILITY_REMOTE: "env.capability_remote", // forge#4542: a remote sandbox lane blocked only on a host-only capability (SOPS key, ops credentials, prod monitor SSH) the dispatching host has; recovered locally
   SANDBOX_START_FAILED: "sandbox.start_failed", // forge#4254: a lane sandbox could not start; needs-human, not relaunched
   SANDBOX_CAPACITY: "sandbox.capacity", // forge#4254: the sandbox provider had no capacity; deferred with backoff
   LEASE_HELD: "lease.held",
@@ -175,6 +177,7 @@ export function codeForTerminalReason(reason) {
     case "dependency-open": return OUTCOME_CODES.DEPENDENCY_OPEN;
     case "dependency-unreadable": return OUTCOME_CODES.DEPENDENCY_UNREADABLE;
     case "dependency-blocked": return OUTCOME_CODES.DEPENDENCY_BLOCKED;
+    case "budget-exceeded": return OUTCOME_CODES.BUDGET_EXCEEDED; // forge#4505: the non-human turn-overrun end
     default: return UNCLASSIFIED;
   }
 }
@@ -183,20 +186,21 @@ export function codeForTerminalReason(reason) {
  * Batch recovery classes of a lane result (forge#4267). The batch runner recovers `recoverable` rows once
  * (`orchestration.recovery.max_attempts`) and re-queues them; only `human` rows are escalations.
  */
-export const RECOVERABLE_CODES = Object.freeze([OUTCOME_CODES.CI_RED, OUTCOME_CODES.BASE_CONFLICT, OUTCOME_CODES.BUILDER_BLOCK_UNTYPED, OUTCOME_CODES.CONTRACT_INVALID, OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.BUDGET_EXCEEDED]);
+export const RECOVERABLE_CODES = Object.freeze([OUTCOME_CODES.CI_RED, OUTCOME_CODES.BASE_CONFLICT, OUTCOME_CODES.BUILDER_BLOCK_UNTYPED, OUTCOME_CODES.CONTRACT_INVALID, OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.ENV_CAPABILITY_REMOTE, OUTCOME_CODES.BUDGET_EXCEEDED]);
 /** `builder.blocked` is only reached by a typed human block: credentials, spend, promotion, customer, product-decision. */
 export const HUMAN_CODES = Object.freeze([OUTCOME_CODES.BUILDER_BLOCKED]);
 
 /**
  * `recoverable` | `human` | `terminal` for a lane result row ({outcome|terminalReason, code, issueEdited?, conflicting?}).
- * Recoverable: needs-human `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing`, `env.repro_unrunnable`, `budget.exceeded`, `contract.invalid` after a mid-run issue
- * edit (`issueEdited`), and `ci-pending` on a conflicting PR (`conflicting`). Human: `builder.blocked`. Anything else
+ * Recoverable: needs-human `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing`, `env.repro_unrunnable`, `env.capability_remote`, `budget.exceeded`, `contract.invalid` after a mid-run issue
+ * edit (`issueEdited`), `ci-pending` on a conflicting PR (`conflicting`), and the non-human `budget-exceeded` turn-overrun end (forge#4505). Human: `builder.blocked`. Anything else
  * (another code, or not a needs-human/ci-pending row) is terminal. Pure, never throws.
  */
 export function classifyNeedsHuman(row) {
   if (!row || typeof row !== "object") return "terminal";
   const outcome = row.outcome ?? row.terminalReason;
   if (outcome === "ci-pending") return row.conflicting === true ? "recoverable" : "terminal";
+  if (outcome === "budget-exceeded") return "recoverable";
   if (outcome !== "needs-human") return "terminal";
   if (HUMAN_CODES.includes(row.code)) return "human";
   if (row.code === OUTCOME_CODES.CONTRACT_INVALID) return row.issueEdited === true ? "recoverable" : "terminal";

package/bin/engine/phases.mjs

@@ -308,20 +308,41 @@ async function readIssueRecord(n, io) {
   } catch { return null; }
 }
 
-// A declaration line: optional list marker, optional bold, "Depends on" or "Blocked by" (any case), optional colon
-// inside or after the bold, then one or more `#N` separated by commas, "and", "&" or spaces (#4121).
-const DEPENDS_ON_RE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*|__)?(?:depends on|blocked by)[ \t]*:?(?:\*\*|__)?[ \t]*:?[ \t]*(#\d+\b(?:[ \t]*(?:,|&|\band\b)?[ \t]*#\d+\b)*)/gim;
+// A declaration line: optional list marker, optional bold, "Depends on" or "Blocked by" (any case), then one linear run of blanks, colons
+// and bold markers (no chained quantifiers: #4517), then a list of `#N` (#4121, #4506). The list is `#N` items joined by `,` `&` `and` `or`
+// (each item may carry a parenthetical note, whose own `#N` are prose); any other text ends it, so a trailing
+// "see #99", "Fixes #12", a code span or a sentence never adds an edge (release review #4515).
+const DEPENDS_ON_RE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*|__)?(?:depends on|blocked by)[ \t:*_]*(#\d+\b[^\n]*)/gim;
+const DEP_ITEM_RE = /^(?<![\w/])#(\d+)\b(?:[ \t]*\([^()\n]*\))?/;
+const DEP_JOIN_RE = /^[ \t]*(?:,[ \t]*(?:(?:and|or)\b[ \t]*)?|&[ \t]*|(?:and|or)\b[ \t]*)/i;
+
+/** The `#N` list at the start of a declaration's tail: items and joiners only, stopping at the first other text. */
+function dependsOnList(tail) {
+  const out = [];
+  let rest = tail;
+  for (;;) {
+    const item = DEP_ITEM_RE.exec(rest);
+    if (!item) break;
+    out.push(Number(item[1]));
+    rest = rest.slice(item[0].length);
+    const join = DEP_JOIN_RE.exec(rest);
+    if (!join || !/^#\d/.test(rest.slice(join[0].length))) break;
+    rest = rest.slice(join[0].length);
+  }
+  return out;
+}
 
 /**
  * Issue numbers an issue body declares it waits on: `**Depends on**: #X`, `**Depends on** #X, #Y`, `Depends on #X`,
- * `- Depends on: #X and #Y`, `Blocked by #X`. Only declaration lines count; a mid-line mention is prose. Shared by the
- * engine's admission (`openDependency`) and `forgedock orchestrate` so both agree on what blocks what.
+ * `- Depends on: #X and #Y`, `Depends on #X (why) and #Y (why)`, `Blocked by #X`. Only declaration lines count, and on
+ * them only the leading `#N` list; a mid-line or trailing mention is prose. Shared by the engine's admission
+ * (`openDependency`) and `forgedock orchestrate` so both agree on what blocks what.
  * @returns {number[]} unique, positive, never `issue` itself
  */
 export function parseDependsOn(body, issue = null) {
   const out = new Set();
   for (const m of String(body ?? "").replace(/\r\n/g, "\n").matchAll(DEPENDS_ON_RE)) {
-    for (const r of m[1].matchAll(/#(\d+)/g)) out.add(Number(r[1]));
+    for (const n of dependsOnList(m[1])) out.add(n);
   }
   return [...out].filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue));
 }
@@ -329,8 +350,8 @@ export function parseDependsOn(body, issue = null) {
 /**
  * forge#3932: does the issue declare a `Depends on` / `Blocked by` dependency that is still OPEN?
  * Honoured only when the issue BODY's author is trusted (`isTrustedComment`: OWNER/MEMBER/COLLABORATOR,
- * Bot, or FORGE_TRAIL_TRUSTED_LOGINS) and only for a declaration line `parseDependsOn` accepts (mid-line
- * prose is ignored). A self-reference is ignored. Returns `null` (nothing blocking), `{ open: [N, ...] }`, or `{ unreadable: true, detail }`
+ * Bot, or FORGE_TRAIL_TRUSTED_LOGINS) and only for a declaration line's leading `#N` list as `parseDependsOn` reads it (mid-line
+ * and trailing prose is ignored). A self-reference is ignored. Returns `null` (nothing blocking), `{ open: [N, ...] }`, or `{ unreadable: true, detail }`
  * when the issue or a declared dependency cannot be read (fail closed: the caller refuses the run).
  * An empty read of the issue itself means "no body to trust" and yields `null`.
  */

package/bin/engine-cli.mjs

@@ -18,7 +18,7 @@ import { parseForgeYaml } from "./forge-utils.mjs";
 import { makeEmitTelemetry } from "./engine/telemetry-seam.mjs";
 import { readBranches, resolveLane, isDefaultLane } from "./lean/lane.mjs";
 import { parseVerify } from "./lean/verify.mjs";
-import { parseExecution } from "./lean/execution.mjs";
+import { parseExecution, detectNeeds } from "./lean/execution.mjs";
 import { parseTurnBudgets, formatTurnSummary, TURN_BUDGET_DEFAULTS } from "./lean/budget.mjs";
 import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
 import { parseLightConfig, LIGHT_DEFAULTS } from "./lean/light.mjs";
@@ -326,6 +326,11 @@ export function readVerify(cwd = process.cwd()) {
     return sec && typeof sec === "object" ? parseVerify(sec) : undefined;
   } catch { return undefined; }
 }
+/** #4542: forge.yaml `execution.host_capabilities` (+ patterns) for a lane's remote-block mapping; undefined when none are declared. */
+export function readHostCaps(cwd = process.cwd()) {
+  const e = readExecution(cwd);
+  return e?.hostCapabilities?.length ? { hostCapabilities: e.hostCapabilities, ...(e.hostCapabilityPatterns ? { hostCapabilityPatterns: e.hostCapabilityPatterns } : {}) } : undefined;
+}
 /**
  * forge.yaml `execution:` section (#4253, block style: `execution:` then `  mode: remote`, `  max_remote: 4`,
  * `  provider: container`, `  image`, `  secrets` comma-separated env names; remote provider #4254: `  endpoint`,
@@ -849,7 +854,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() } : {}), ...(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() } : {}) });
     } 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
@@ -1199,19 +1204,34 @@ async function orchestrateClient(argv, deps = {}) {
     }
     msg = { op: "submit", argv: sub, cwd: process.cwd(), env: schedd.batchEnv(process.env) };
   }
-  const sock = await connect();
+  let sock = await connect(), req = msg, reattached = false, losses = 0;
   let id = resumeId;
-  try {
-    const done = await schedd.request(sock, msg, (m) => {
-      if (m.type === "batch") id = m.id;
-      else if (m.type === "row") console.log(formatRowLine(m.row));
-      else if (m.type === "line") console.log(m.text);
-      else if (m.type === "done" && m.replay && m.report) console.log(m.report);
-    });
-    return done.result;
-  } catch (e) {
-    if (id && /closed the connection/.test(e?.message ?? "")) throw new Error(`${e.message}; the batch keeps its state: forgedock orchestrate --resume ${id}`);
-    throw e;
+  const onMsg = (m) => {
+    if (m.type === "batch") id = m.id;
+    else if (m.type === "row") { if (!(reattached && m.replay)) console.log(formatRowLine(m.row)); }
+    else if (m.type === "line") console.log(m.text);
+    else if (m.type === "done" && m.replay && m.report) console.log(m.report);
+  };
+  // #4503: when the daemon dies mid-batch, reconnect (spawning one unless `spawnDaemon: null`) and re-attach, within `reconnectMs`.
+  const reconnectMs = deps.reconnectMs ?? 60_000, sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  for (;;) {
+    try {
+      return (await schedd.request(sock, req, onMsg)).result;
+    } catch (e) {
+      if (!id || !(/closed the connection/.test(e?.message ?? "") || ["ECONNRESET", "EPIPE"].includes(e?.code))) throw e;
+      const giveUp = () => new Error(`${e.message}; the batch keeps its state: forgedock orchestrate --resume ${id}`);
+      if (++losses > 10) throw giveUp();
+      console.log(`schedd connection lost; reconnecting to batch ${id}`);
+      const end = Date.now() + reconnectMs;
+      for (sock = null; !sock;) {
+        try { sock = await connect(); } catch {
+          if (Date.now() >= end) throw giveUp();
+          await sleep(250);
+        }
+      }
+      req = { op: "attach", id };
+      reattached = true;
+    }
   }
 }
 
@@ -1312,13 +1332,15 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   // Lanes: in-process `runCore` when a lean module is injected (tests), otherwise detached `run-issue` processes, or
   // sandboxes when forge.yaml `execution` places them remote (#4253).
   const labelsOf = new Map(); // issue -> label names, filled by readBody (one gh call per issue)
+  const needsOf = new Map(); // issue -> host-only capabilities its body names (#4542), filled by readBody
+  let execForNeeds = null;
   let lanes, remote = null, execBudget = null, execConf = null, hybrid = false;
   const execMode = () => (deps.execution !== undefined ? deps.execution : readExecution(cwd))?.mode ?? "local";
   if (deps.leanModule) {
     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) } : {}), ...(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) } : {}) }) };
   } 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.
@@ -1333,6 +1355,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     }, adopt: l.adopt });
     const execMod = await import("./lean/execution.mjs");
     const exec = deps.execution !== undefined ? deps.execution : readExecution(cwd);
+    execForNeeds = exec ?? null;
     hybrid = exec?.mode === "hybrid" && Number.isInteger(exec.maxRemote) && exec.maxRemote >= 1;
     if (exec && (execMod.placement(exec) === "remote" || hybrid)) {
       // #4253: lanes run in sandboxes, ledger-tracked per lane, admitted against max_remote instead of the host cap.
@@ -1345,12 +1368,12 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       const remoteLanes = execMod.providerLanes({ provider, laneArgs, ledgerFor, env, secrets: exec.secrets, costPerMinute: bud.costPerMinute ?? 0,
         ...(deps.now ? { now: deps.now } : {}), ...(deps.pollMs ? { pollMs: deps.pollMs } : {}) });
       lanes = withPlacement(remoteLanes);
-      if (bud.onBudget === "local" || hybrid) {
+      {
         // #4255: once the budget refuses a remote lane, the rest run as detached host lanes. #4256: hybrid mixes both.
         const local = batchMod.detachedLanes({ batch, cwd, env, script: laneScript, bin: deps.laneBin, pollMs: deps.pollMs, laneArgs });
         lanes = withPlacement({
           runOne: (n, ln, ctx = {}) => (ctx.remote ? remoteLanes : local).runOne(n, ln, ctx),
-          adopt: (n, rec) => (rec?.remote || rec?.handle ? remoteLanes : local).adopt(n, rec),
+          adopt: (n, rec, ctx) => (rec?.remote || rec?.handle ? remoteLanes : local).adopt(n, rec, ctx),
         });
       }
       // #4255: hard execution budget per batch and per host UTC day; every settled sandbox is recorded and reported.
@@ -1358,15 +1381,26 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       execBudget = deps.executionBudget ?? execMod.openExecutionBudget({ budget: bud, file: execMod.executionBudgetFile(env), ...(deps.now ? { now: deps.now } : {}) });
       const emitSbx = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
       // #4256: hybrid places each lane from facts (pure placeLane); validation weight is a repo fact, read once per batch.
-      const place = hybrid ? await (async () => {
+      const relays = Array.isArray(provider.relays) ? provider.relays : [];
+      const place = !hybrid ? (n) => execMod.placeLane({ exec, needs: needsOf.get(n) ?? [], relays }) : await (async () => {
         const verifyMode = (deps.verify !== undefined ? deps.verify : readVerify(cwd))?.mode ?? "local";
         let weight = deps.validationWeight ?? null;
         if (!weight) { try { weight = await execMod.validationWeight({ cwd, precheckCommands: readPrecheckCommands(cwd) ?? [] }); } catch { weight = { heavy: false, signals: [] }; } }
         const headroom = deps.hostHeadroom ?? (() => execMod.hostHeadroom({ cfg: readAdmission(cwd), heavyCfg: readHeavy(cwd) }));
-        return (n) => execMod.placeLane({ exec, verifyMode, labels: labelsOf.get(n) ?? [], weight, headroom: headroom() });
-      })() : null;
+        return (n) => execMod.placeLane({ exec, verifyMode, labels: labelsOf.get(n) ?? [], weight, headroom: headroom(), needs: needsOf.get(n) ?? [], relays });
+      })();
+      // #4540: provider free slots, refreshed in the background (admission is sync); unknown (null) never blocks.
+      let capSample = null, onlineSample = null, capAt = 0, capLast = -Infinity; // #4547: online = agents alive, null unknown
+      const capacity = () => {
+        const t = deps.now ? deps.now() : Date.now();
+        if (typeof provider.capacity === "function" && t - capLast >= (deps.pollMs ?? 5000)) {
+          capLast = t;
+          Promise.resolve().then(() => provider.capacity()).then((c) => { capSample = c && Number.isInteger(c.free) ? c.free : null; onlineSample = c && Number.isInteger(c.online) ? c.online : null; capAt++; }, () => { capSample = null; onlineSample = null; capAt++; });
+        }
+        return capSample === null && onlineSample === null ? null : { free: capSample, online: onlineSample, at: capAt };
+      };
       remote = {
-        max: exec.maxRemote, isRemote: () => true, ...(place ? { place, fallbackLocal: true } : {}), onBudget: bud.onBudget ?? "stop", costPerMinute: bud.costPerMinute ?? 0,
+        capacity, max: exec.maxRemote, isRemote: () => true, place, ...(hybrid ? { fallbackLocal: true } : {}), ...(exec.fallbackLocal ? { offlineFallback: true } : {}), onBudget: bud.onBudget ?? "stop", costPerMinute: bud.costPerMinute ?? 0,
         admit: (u) => execBudget.admit(u),
         onUsage: (n, sb, rec) => {
           const startedAt = rec?.handle?.startedAt ?? rec?.startedAt ?? "?";
@@ -1507,6 +1541,17 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       ...(daemon ? {} : { onExit: (fn) => { exitRelabel = fn; } }),
       // #4454: the daemon's shutdown stop; orchestrate throws batch.stopped, so no report is written and a resume adopts the lanes
       ...(signal ? { signal } : {}),
+      // #4525: a parked needs-human PR is merged with its moved base: clean or union-resolved merges are pushed, other conflicts reported
+      ...(deps.syncParked !== undefined ? (deps.syncParked ? { syncParked: deps.syncParked } : {}) : orch.baseSync?.enabled !== true ? {} : { syncParked: async ({ pr, last }) => {
+        try {
+          const v = JSON.parse(await leanIo.gh(["pr", "view", String(pr), "-R", repo, "--json", "state,headRefName,baseRefName,isCrossRepository"]));
+          if (v.state !== "OPEN" || v.isCrossRepository) return { status: "unchanged" };
+          const { execFile } = await import("node:child_process"), { promisify } = await import("node:util");
+          const run = promisify(execFile);
+          return await (await import("./lean/basesync.mjs")).syncParked({ git: async (a, o = {}) => String((await run("git", a, { cwd: o.cwd ?? cwd, maxBuffer: 1 << 24 })).stdout), base: v.baseRefName, branch: v.headRefName,
+            unionGlobs: orch.baseSync?.unionGlobs ?? [], last });
+        } catch (e) { return { status: "error", detail: String(e?.message ?? e).slice(0, 160) }; }
+      } }),
       conflicting: deps.conflicting ?? (async (_n, pr) => {
         try { return JSON.parse(await leanIo.gh(["pr", "view", String(pr), "-R", repo, "--json", "mergeable"]))?.mergeable === "CONFLICTING"; } catch { return false; }
       }),
@@ -1515,8 +1560,8 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
         sink.line(`cross-lane: #${e.issue} (${e.lane}) depends on #${e.dependency} (${e.dependencyLane}); its fix will not be on ${e.lane}: re-milestone #${e.dependency} or wait for a milestone sync`);
       },
       readBody: maint || registry || hybrid
-        ? async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body,labels"])); labelsOf.set(n, (v.labels ?? []).map((x) => x.name)); return v.body; }
-        : async (n) => JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body"])).body,
+        ? async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body,labels"])); labelsOf.set(n, (v.labels ?? []).map((x) => x.name)); needsOf.set(n, detectNeeds(v.body, execForNeeds)); return v.body; }
+        : async (n) => { const b = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body"])).body; needsOf.set(n, detectNeeds(b, execForNeeds)); return b; },
       onUpdate: (r) => sink.row(r),
     });
   } finally { for (const [sig, f] of Object.entries(handlers)) off(sig, f); }
@@ -1645,6 +1690,16 @@ export async function scheddFromCli(argv, deps = {}) {
   return { running: false };
 }
 
+/**
+ * `forgedock pool router [install] | enroll [--cpus N --mem GB] | status | upgrade [agent] | remove <agent>` (#4544)
+ * The built-in remote compute pool (`bin/pool/`). `pool router` runs in the foreground (for a systemd-user unit:
+ * `ExecStart=forgedock pool router`); `router install` installs that unit. `enroll` prints the one-time install command.
+ */
+export async function poolFromCli(argv, deps = {}) {
+  const { runPoolCli } = await import("./pool/cli.mjs");
+  return (deps.runPoolCli ?? runPoolCli)(argv, deps.poolDeps ?? {});
+}
+
 /**
  * `forgedock limits show` · `forgedock limits clear <id>|--all` (#4190)
  * Usage-limit holds are kept per account (backend identity) in `~/.forge/limits.json` (or `FORGEDOCK_LIMITS_FILE`) and
@@ -1787,6 +1842,8 @@ export async function schedFromCli(argv, deps = {}) {
  * `orchestration.errors|window_min` (or flat `breaker_errors|breaker_window_min`).
  * `orchestration.recovery.max_attempts` (#4267; arrives as `max_attempts`, or flat `recovery_max_attempts`): recovery lanes per
  * issue for a mechanical needs-human, default 1, 0 turns recovery off.
+ * `orchestration.base_sync.enabled` (#4525; default true, false opts out) and `base_sync.union_globs` (comma list of globs of
+ * append-only files whose two-sided line additions a parked PR's base sync keeps both of).
  */
 export function readOrchestration(cwd = process.cwd()) {
   let o = {};
@@ -1796,7 +1853,10 @@ export function readOrchestration(cwd = process.cwd()) {
   const gp = int(o.global_parallel, null);
   const recoveryMax = int(o.recovery_max_attempts ?? o.max_attempts, 1);
   return { breaker: errors > 0 && windowMin > 0 ? { errors, window_min: windowMin } : null, maxDeferrals: int(o.max_deferrals, 3), globalParallel: gp >= 1 ? gp : null,
-    recovery: { maxAttempts: recoveryMax } };
+    recovery: { maxAttempts: recoveryMax },
+    // #4525: parked-PR base sync. The parser flattens one level, so `base_sync.enabled|union_globs` arrive as `enabled|union_globs` (or flat `base_sync_*`).
+    baseSync: { enabled: String(o.base_sync_enabled ?? o.enabled ?? "true").trim().toLowerCase() !== "false",
+      unionGlobs: String(o.base_sync_union_globs ?? o.union_globs ?? "").replace(/^\[|\]$/g, "").split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean) } };
 }
 
 /**

package/bin/forgedock.mjs

@@ -1878,6 +1878,12 @@ function selfUpdateGlobalInstall(version) {
   }
 }
 
+/** #4545: after an update, push the new code + lane image to pool agents (no-op without a pool router config). */
+async function upgradePoolAgents() {
+  const { upgradeAgentsAfterUpdate } = await import("./pool/version.mjs");
+  await upgradeAgentsAfterUpdate({ warn: (m) => console.log(`  ${YELLOW}${m}${RESET}`) });
+}
+
 async function update() {
   console.log("");
   console.log(`${BOLD}ForgeDock${RESET} — Checking for updates`);
@@ -1994,6 +2000,7 @@ async function update() {
         printGitCloneChangelogSummary(before, after);
       }
       await relinkAndHint();
+      await upgradePoolAgents();
     } catch (err) {
       console.log(
         `  ${YELLOW}Cannot fast-forward — local changes exist. Skipping.${RESET}`,
@@ -2081,6 +2088,7 @@ async function update() {
     }
 
     await relinkAndHint();
+    await upgradePoolAgents();
   }
   console.log("");
 }
@@ -3296,6 +3304,7 @@ function help() {
     ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
     ["npx forgedock sched show | cap <N>|--clear | weight <owner/repo> <N>|--clear", "Show the host lane registry, set the host-wide lane cap shared by orchestrate batches, or set a repo's share of slots within a priority (default equal)"],
     ["npx forgedock schedd [status]", "Host scheduler daemon hosting every orchestrate batch (auto-spawned by orchestrate; run in the foreground for a systemd-user unit); status shows its pid and batches"],
+    ["npx forgedock pool router [install] | enroll [--cpus N --mem GB] | status | upgrade [agent] | remove <agent>", "Built-in remote compute pool: run the router (foreground, or install it as a user service), print the one-time install command for a host, list agents, upgrade or remove them"],
     ["npx forgedock gc [--apply] [--older-than 6h] [--docker] [--worktrees] [--branches] [--tmp] [--processes] [--sandboxes]", "Report (dry-run default) and reclaim ForgeDock-owned leftovers: stale lane ledgers, forgedock-labelled containers/volumes, lean-*/agent-* worktrees, abandoned lane branches, ~/.forge/tmp scratch, orphaned lane processes, orphaned lane sandboxes; unowned resources and unpushed work are only reported"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
@@ -3876,7 +3885,7 @@ async function watch() {
 const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "probe", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "check", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "pool", "check", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4141,6 +4150,17 @@ switch (command) {
     }
     break;
   }
+  case "pool": {
+    // #4544: the built-in remote compute pool (router, enrollment, status, upgrade, remove)
+    const { poolFromCli } = await import("./engine-cli.mjs");
+    try {
+      await poolFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = String(err.message).startsWith("usage:") ? 2 : 1;
+    }
+    break;
+  }
   case "sched": {
     const { schedFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/lean/basesync.mjs

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Base sync of a parked PR (#4525): a lane that ended needs-human leaves its PR open and nothing owns the branch, so it
+ * rots as the base moves. `syncParked` merges the base into the PR branch in a throwaway worktree. A clean merge, or one
+ * whose only conflicts are hunks where both sides purely added lines in a file matching `base_sync.union_globs`
+ * (`unionResolve`: keep both), is pushed as a plain merge commit (never forced). Any other conflict is aborted and its
+ * paths returned, the branch untouched. Deterministic (git only, no LLM); sequence/journal files are never resolved here
+ * (they belong to sequence.mjs). Never throws.
+ */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { seqNumber } from "./sequence.mjs";
+
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+
+/** Glob (`*` within a segment, `**` across, `?`) to a RegExp; a pattern with no `/` matches the file name anywhere. */
+const globRe = (g) => {
+  const body = String(g).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\u0000").replace(/\*\*/g, "\u0001").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, "(?:.*/)?").replace(/\u0001/g, ".*");
+  return new RegExp(`^${String(g).includes("/") ? "" : "(?:.*/)?"}${body}$`);
+};
+export const matchesGlobs = (path, globs = []) => globs.some((g) => String(g).trim() && globRe(String(g).trim()).test(String(path)));
+
+/** Never resolved here: a migration journal and numbered sequence files are sequence.mjs's. */
+export const isSequenceFile = (path) => basename(String(path)) === "_journal.json" || seqNumber(path) !== null;
+
+/**
+ * Resolve a diff3-style conflicted text (`<<<<<<<` ours, `|||||||` base, `=======` theirs, `>>>>>>>`): a hunk resolves
+ * only when its base section is empty (both sides only added lines), keeping ours then theirs. Returns the resolved
+ * text, or null when the text has no conflict, no base section, or a hunk where either side changed or removed base lines.
+ */
+export function unionResolve(text) {
+  const src = String(text ?? "").split("\n");
+  const out = [];
+  let i = 0, hunks = 0;
+  while (i < src.length) {
+    if (!src[i].startsWith("<<<<<<<")) { out.push(src[i++]); continue; }
+    const ours = [], base = [], theirs = [];
+    let part = ours, hasBase = false, closed = false;
+    for (i++; i < src.length; i++) {
+      const l = src[i];
+      if (l.startsWith("|||||||")) { part = base; hasBase = true; } else if (l.startsWith("=======") && part !== theirs) part = theirs;
+      else if (l.startsWith(">>>>>>>") && part === theirs) { closed = true; i++; break; } else part.push(l);
+    }
+    if (!closed || !hasBase || base.length) return null;
+    out.push(...ours, ...theirs); hunks++;
+  }
+  return hunks ? out.join("\n") : null;
+}
+
+/**
+ * @param {{git:(args:string[], o?:{cwd?:string})=>Promise<string>, base:string, branch:string, unionGlobs?:string[], last?:?string, tmp?:string}} p
+ *   `git` runs in the repo checkout and throws on failure; `last` is the base sha already handled for this PR.
+ * @returns {Promise<{status:"unchanged"|"up-to-date"|"merged"|"conflict"|"error", base?:string, paths?:string[], detail?:string}>}
+ */
+export async function syncParked({ git, base, branch, unionGlobs = [], last = null, tmp = tmpdir() }) {
+  let wt = null, baseSha;
+  try {
+    await git(["fetch", "origin", base, branch]);
+    baseSha = String(await git(["rev-parse", `origin/${base}`])).trim();
+    if (last && last === baseSha) return { status: "unchanged", base: baseSha };
+    try { await git(["merge-base", "--is-ancestor", `origin/${base}`, `origin/${branch}`]); return { status: "up-to-date", base: baseSha }; } catch { /* behind */ }
+    wt = mkdtempSync(join(tmp, "basesync-"));
+    await git(["worktree", "add", "--detach", wt, `origin/${branch}`]);
+    const g = (a) => git(a, { cwd: wt });
+    const ident = String(await g(["config", "user.email"]).catch(() => "")).trim() ? [] : ["-c", "user.name=ForgeDock", "-c", "user.email=forgedock@users.noreply.github.com"];
+    let clean = true;
+    try { await g([...ident, "merge", "--no-edit", `origin/${base}`]); } catch { clean = false; }
+    if (!clean) {
+      const conflicted = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=U"]).catch(() => ""));
+      const stages = new Map();
+      for (const l of lines(await g(["-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 fixes = [], refused = [];
+      for (const f of conflicted) {
+        let resolved = null;
+        if (stages.get(f) === 14 && !isSequenceFile(f) && matchesGlobs(f, unionGlobs)) { // stages 1,2,3 present: both sides edited an existing file
+          try { await g(["checkout", "--conflict=diff3", "--", f]); resolved = unionResolve(readFileSync(join(wt, f), "utf8")); } catch { resolved = null; }
+        }
+        if (resolved === null) refused.push(f); else fixes.push([f, resolved]);
+      }
+      if (!conflicted.length || refused.length) {
+        await g(["merge", "--abort"]).catch(() => {});
+        return { status: "conflict", base: baseSha, paths: refused.length ? refused : ["(unknown files)"] };
+      }
+      for (const [f, text] of fixes) { writeFileSync(join(wt, f), text); await g(["add", "--", f]); }
+      await g([...ident, "commit", "--no-edit"]);
+    }
+    await git(["push", "origin", `${(await g(["rev-parse", "HEAD"])).trim()}:refs/heads/${branch}`]); // plain push: a rejected race is an error, never forced
+    return { status: "merged", base: baseSha };
+  } catch (e) {
+    return { status: "error", ...(baseSha ? { base: baseSha } : {}), detail: String(e?.message ?? e).split("\n")[0].slice(0, 200) };
+  } finally {
+    if (wt) { await git(["worktree", "remove", "--force", wt]).catch(() => {}); try { rmSync(wt, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+}