forgedock 1.32.0 → 1.33.0

package/bin/lean/depcache.test.mjs

@@ -38,7 +38,7 @@ const FIXTURES = {
 const LOCKFILE = { pnpm: "pnpm-lock.yaml", npm: "package-lock.json", uv: "uv.lock", poetry: "poetry.lock" };
 
 /** Fake package managers: write what a real install leaves behind, including the absolute paths that need rewriting. */
-function fakeExec({ failInstall = false, installDelayMs = 0 } = {}) {
+function fakeExec({ failInstall = false, failRepair = false, installDelayMs = 0 } = {}) {
   const calls = [];
   const venv = (cwd, lock) => {
     const v = join(cwd, ".venv");
@@ -65,6 +65,10 @@ function fakeExec({ failInstall = false, installDelayMs = 0 } = {}) {
     if (full && installDelayMs) await new Promise((r) => setTimeout(r, installDelayMs));
     if (full && failInstall) { put(join(cwd, cmd === "uv" || cmd === "poetry" ? ".venv/partial" : "node_modules/partial"), "x"); throw Object.assign(new Error("install failed"), { stderr: "ERR_PNPM_FROZEN_LOCKFILE" }); }
     if (cmd === "pnpm") {
+      if (args.includes("--offline") && failRepair) {
+        // pnpm prints its errors on stdout; execFile's error then carries an empty stderr (#4522).
+        throw Object.assign(new Error("Command failed: pnpm install --frozen-lockfile --offline"), { stderr: "", stdout: "Lockfile is up to date\n ERR_PNPM_TEST_REPAIR  some cause\n" });
+      }
       if (args.includes("--offline")) return ""; // warm repair pass: nothing to do
       const lock = readFileSync(join(cwd, "pnpm-lock.yaml"), "utf8");
       put(join(cwd, "node_modules/.pnpm/lodash@4/node_modules/lodash/index.js"), `module.exports = ${JSON.stringify(lock)};\n`);
@@ -222,6 +226,43 @@ describe("depcache (#4220): shared dependency installs keyed by lock hash", () =
     assert.equal(r.published, true, "the stale lock was replaced");
   });
 
+  it("#4522 a snapshot whose repair fails falls back to a fresh install outside the lock, keeps the snapshot and records pnpm's stdout error", async () => {
+    const s = setup("pnpm");
+    const [ra] = await s.cache.prepare({ wt: s.lane("a"), repoKey: "r" });
+    assert.equal(ra.status, "miss-installed", ra.reason);
+    const [snap] = snapDirs(s.root, "pnpm");
+    const before = snapshotOf(snap);
+    const broken = makeDepCache({ root: s.root, exec: fakeExec({ failRepair: true }).exec, env: {}, pollMs: 5 });
+    const wt = s.lane("b");
+    const [rb] = await broken.prepare({ wt, repoKey: "r" });
+    assert.equal(rb.status, "materialize-fallback", rb.reason);
+    assert.equal(rb.published, false);
+    assert.match(rb.reason, /^materialize failed: ERR_PNPM_TEST_REPAIR {2}some cause/);
+    assert.ok(existsSync(join(wt, "node_modules/lodash/index.js")), "the lane has node_modules");
+    const after = snapshotOf(snap);
+    delete before["last-used"]; delete after["last-used"];
+    assert.deepEqual(after, before, "the snapshot is untouched");
+    assert.deepEqual(readdirSync(join(s.root, "r")).filter((n) => !/^pnpm-[0-9a-f]{16}$/.test(n)), [], "no lock or tmp left");
+
+    const both = makeDepCache({ root: s.root, exec: fakeExec({ failRepair: true, failInstall: true }).exec, env: {}, pollMs: 5 });
+    const wt2 = s.lane("c");
+    const [rc] = await both.prepare({ wt: wt2, repoKey: "r" });
+    assert.equal(rc.status, "failed");
+    assert.match(rc.reason, /^materialize failed: ERR_PNPM_TEST_REPAIR.*; install failed: ERR_PNPM_FROZEN_LOCKFILE/);
+    assert.ok(!existsSync(join(wt2, "node_modules")), "no partial tree");
+  });
+
+  it("#4522 a failed pnpm install records the ERR_PNPM line it printed on stdout", async () => {
+    const s = setup("pnpm");
+    const exec = async (cmd, args, o) => {
+      if (cmd === "pnpm" && !args.includes("--offline")) throw Object.assign(new Error("Command failed: pnpm install --frozen-lockfile"), { stderr: "", stdout: "Progress: resolved 1\n ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with frozen-lockfile\n\nNote that in CI environments this setting is true by default.\nA\nB\nC\n" });
+      return s.f.exec(cmd, args, o);
+    };
+    const [r] = await makeDepCache({ root: s.root, exec, env: {} }).prepare({ wt: s.lane("x"), repoKey: "r" });
+    assert.equal(r.status, "failed");
+    assert.match(r.reason, /^install failed: ERR_PNPM_OUTDATED_LOCKFILE {2}Cannot install with frozen-lockfile A B C$/);
+  });
+
   it("a failed install, a missing tool or another filesystem leaves no snapshot and no partial tree", async () => {
     const s = setup("pnpm", { failInstall: true });
     const wt = s.lane("x");

package/bin/lean/effects.mjs

@@ -3,7 +3,7 @@
 /** Core work-on: the real effects behind runCore's injected `io`. Argv only, no shell. */
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { readFileSync, appendFileSync, mkdirSync, statSync, existsSync, rmSync, writeFileSync, renameSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { readFileSync, appendFileSync, mkdirSync, mkdtempSync, statSync, existsSync, rmSync, writeFileSync, renameSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, hostname, freemem, loadavg, cpus, tmpdir } from "node:os";
 import { promises as fsp } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
@@ -234,10 +234,36 @@ export function runCheckCommand({ command, cwd, timeoutMs = 300000, env = null }
   });
 }
 
+/**
+ * #4507: a per-run gh HTTP cache (XDG_CACHE_HOME on the gh child only), so concurrent lanes never share a cache entry.
+ * `reset()` drops the current dir (only one this cache created) and switches to a fresh one; with no `root` the dirs
+ * are mkdtemp dirs under `tmp`, removed by `dispose()`.
+ */
+export function makeGhCache({ root = null, tmp = tmpdir() } = {}) {
+  let n = 0, dir = root ? join(root, "gh-cache") : null, disposed = false;
+  const made = new Set();
+  const drop = (d) => { if (d && made.has(d)) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } made.delete(d); } };
+  return {
+    env() {
+      if (!dir || disposed) return undefined; // after dispose (run teardown) gh falls back to its default cache
+      if (!made.has(dir)) { try { mkdirSync(dir, { recursive: true, mode: 0o700 }); made.add(dir); } catch { return undefined; } }
+      return { XDG_CACHE_HOME: dir };
+    },
+    reset() {
+      drop(dir);
+      if (disposed) return;
+      if (root) { dir = join(root, `gh-cache-${++n}`); return; }
+      try { dir = mkdtempSync(join(tmp, "forge-gh-cache-")); made.add(dir); } catch { dir = null; }
+    },
+    dispose() { disposed = true; for (const d of [...made]) drop(d); },
+  };
+}
+
 export function makeLeanIo({ repo }) {
   const base = makeIo();
-  const run = (bin) => async (args, opts = {}) => (await pexec(bin, args, { cwd: opts.cwd, maxBuffer: 100 * 1024 * 1024, timeout: 120000 })).stdout;
+  const run = (bin) => async (args, opts = {}) => (await pexec(bin, args, { cwd: opts.cwd, maxBuffer: 100 * 1024 * 1024, timeout: 120000, ...(opts.env ? { env: { ...process.env, ...opts.env } } : {}) })).stdout;
   return {
+    ghCache: (root) => makeGhCache({ root }),
     gh: run("gh"), git: run("git"), docker: run("docker"), killGroup: async (pid, marker) => killLedgerPid(pid, marker), ledger: (opts) => makeLedger(opts), runTmp: makeRunTmp(), host: makeHostProbe(), heavy: makeHeavyIo({ host: makeHostProbe() }), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
     /** Shared dependency cache (#4220): the repo's own package manager, argv only, bounded by the cache's timeout. */
     deps: makeDepCache({ exec: async (cmd, args, { cwd, env, timeoutMs } = {}) => String((await pexec(cmd, args, { cwd, env: { ...process.env, ...(env ?? {}) }, timeout: timeoutMs ?? 0, maxBuffer: 100 * 1024 * 1024 })).stdout) }),
@@ -344,7 +370,7 @@ export function makeLeanIo({ repo }) {
     sequenceSnapshot: ({ cwd, base }) => snapshotLane({ git: (a) => run("git")(a, { cwd }), base }),
     sequenceVerify: ({ cwd, base, before, moves }) => verifyRenumber({ git: (a) => run("git")(a, { cwd }), base, before, moves }),
     /** #4386: the deterministic renumber, sequence-only base-sync resolution, and the host sequence lease at the merge gate. */
-    sequenceRenumber: ({ cwd, base, laneRef, regenerate }) => renumberLane({ git: (a) => run("git")(a, { cwd }), base, cwd, laneRef, regenerate }),
+    sequenceRenumber: ({ cwd, base, laneRef, regenerate, reserve }) => renumberLane({ git: (a) => run("git")(a, { cwd }), base, cwd, laneRef, regenerate, reserve }),
     sequenceResolve: ({ cwd, files }) => resolveSequenceConflicts({ git: (a) => run("git")(a, { cwd }), files }),
     sequenceLease: makeSequenceLeaseIo(),
     /** #4406: the lane's scoped checks after a base merge (bin/lean/checks.mjs; [] on failure), and same-app duplicate exports (bin/lean/postmerge.mjs). */

package/bin/lean/execution.mjs

@@ -32,10 +32,15 @@
  *
  * Hybrid (#4256): `placeLane` places each lane from facts (lane kind, validation weight, host headroom, verify.mode);
  * orchestrate runs a remote-placed lane locally when `max_remote` or the execution budget is exhausted.
+ *
+ * Host capabilities (#4542): a lane that needs something only the dispatching host has (the SOPS/age key, scoped ops
+ * credentials, read-only prod monitor SSH) is placed local in `remote` and `hybrid` mode, because a sandbox relays none of
+ * them (`detectNeeds`, `placeLane` `needs`). forge.yaml `execution.host_capabilities` declares which the host has; a
+ * remote lane that blocks on one of them ends `env.capability_remote` and is recovered locally (`hostCapabilityBlock`).
  */
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { cpus, homedir, loadavg } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
@@ -50,8 +55,10 @@ import { classifyStep, heavyConfig, memAvailableMb } from "./heavy.mjs";
 import { detectPins } from "./toolchain.mjs";
 
 export const EXECUTION_MODES = Object.freeze(["local", "remote", "hybrid"]);
-export const SANDBOX_PROVIDERS = Object.freeze(["local", "container", "remote"]);
+export const SANDBOX_PROVIDERS = Object.freeze(["local", "container", "remote", "pool"]);
 const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const CAPABILITY_RE = /^[a-z][a-z0-9_-]*$/;
+const safeRegExp = (src) => { try { return new RegExp(src, "i"); } catch { return null; } };
 const ENV_RE = /^[A-Z_][A-Z0-9_]*$/;
 const IMAGE_RE = /^[A-Za-z0-9][A-Za-z0-9._\/:@-]*$/;
 const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
@@ -79,11 +86,19 @@ export function parseExecution(sec = {}) {
   const tokenEnv = ENV_RE.test(str(s.token_env)) ? str(s.token_env) : null;
   const cacheStore = str(s.cache_store) || null;
   const allowActions = str(s.allow_actions).toLowerCase() === "true";
+  const fallbackLocal = str(s.fallback_local).toLowerCase() === "true";
+  const heavyRaw = str(s.heavy).toLowerCase();
+  const heavy = heavyRaw === "true" ? true : heavyRaw === "false" ? false : null;
   const cap = (v) => { const t = str(v), x = Number(t); return t !== "" && Number.isFinite(x) && x >= 0 ? x : null; };
   const cpm = cap(s.cost_per_minute);
   const budget = { batchMinutes: cap(s.budget_minutes), batchUsd: cap(s.budget_usd), dayMinutes: cap(s.day_budget_minutes), dayUsd: cap(s.day_budget_usd),
     onBudget: str(s.on_budget) === "local" ? "local" : "stop", costPerMinute: cpm ?? 0 };
-  return { mode, maxRemote, provider, image, secrets, budget, ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}) };
+  const capList = (v) => (Array.isArray(v) ? v : str(v) ? str(v).split(",") : []).map((x) => str(x).toLowerCase()).filter((x) => CAPABILITY_RE.test(x));
+  const hostCapabilities = [...new Set(capList(s.host_capabilities))];
+  const patRaw = Array.isArray(s.host_capability_patterns) ? s.host_capability_patterns : str(s.host_capability_patterns) ? str(s.host_capability_patterns).split(",") : [];
+  const hostCapabilityPatterns = patRaw.map((x) => { const t = str(x), i = t.indexOf(":"); return { name: t.slice(0, i).trim().toLowerCase(), pattern: t.slice(i + 1).trim() }; })
+    .filter((x) => CAPABILITY_RE.test(x.name) && x.pattern && safeRegExp(x.pattern));
+  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -157,6 +172,33 @@ export function placement(exec) {
   return exec?.mode === "remote" && Number.isInteger(exec.maxRemote) && exec.maxRemote >= 1 ? "remote" : "local";
 }
 
+/** Host-only capabilities and the issue-text signals that mean a lane needs them (#4542). */
+const CAPABILITY_SIGNALS = Object.freeze({
+  sops: /\.secrets\/[^\s`'")]*\.enc\.ya?ml|\bsops\b|\bage key\b|\.age\//i,
+  prod_monitor: /\bssh\s+[\w.-]*-monitor\b|\b(?:ovh|netcup)-monitor\b|\bobs-psql\b|\bprod(?:uction)? monitor/i,
+  ops_credentials: /\bcredentials\.yaml\b|\bops[ _-]credentials\b/i,
+});
+
+/**
+ * Host-only capabilities named by `text` (issue body, contract or a builder summary), zero LLM, sorted by name: the
+ * built-in signals above, a declared name written out (`prod_monitor`, `prod monitor`) and `exec.hostCapabilityPatterns`.
+ */
+export function detectNeeds(text, exec = null) {
+  const t = String(text ?? "");
+  const found = new Set();
+  for (const [name, re] of Object.entries(CAPABILITY_SIGNALS)) if (re.test(t)) found.add(name);
+  for (const name of exec?.hostCapabilities ?? []) if (new RegExp(`\\b${name.replace(/[_-]/g, "[ _-]")}\\b`, "i").test(t)) found.add(name);
+  for (const { name, pattern } of exec?.hostCapabilityPatterns ?? []) { const re = safeRegExp(pattern); if (re?.test(t)) found.add(name); }
+  return [...found].sort();
+}
+
+/** Declared host capabilities a remote lane's block summary names (#4542); empty when it names none the host has. */
+export function hostCapabilityBlock(summary, caps = null) {
+  const have = new Set(caps?.hostCapabilities ?? []);
+  const named = detectNeeds(summary, caps);
+  return named.length && named.every((n) => have.has(n)) ? named : [];
+}
+
 const DOCS_LABELS = new Set(["docs", "documentation", "type:docs"]);
 
 /**
@@ -165,16 +207,22 @@ const DOCS_LABELS = new Set(["docs", "documentation", "type:docs"]);
  * `validationWeight`, `headroom` from `hostHeadroom`. In order: a non-hybrid mode keeps `placement()`; `max_remote` 0 is
  * local; `verify.mode: ci` is local (heavy validation already runs, and is billed, on CI); a docs-only lane is local; a
  * heavy-validation lane is remote; a host without headroom sends the lane remote; anything else stays on the host.
+ * A `needs` entry (host-only capability, #4542) the provider does not `relays` is local first, in `remote` mode too.
  * Capacity (`max_remote` reached, the execution budget) is applied at admission by orchestrate, which falls back to local.
  */
-export function placeLane({ exec = null, verifyMode = "local", labels = [], weight = null, headroom = null } = {}) {
+export function placeLane({ exec = null, verifyMode = "local", labels = [], weight = null, headroom = null, needs = [], relays = [] } = {}) {
   const mode = exec?.mode;
+  if (mode === "remote" || mode === "hybrid") {
+    const missing = (Array.isArray(needs) ? needs : []).map(String).filter((n) => n && !(Array.isArray(relays) ? relays : []).includes(n));
+    if (missing.length) return { where: "local", reason: `host capability: ${missing.join(", ")}` };
+  }
   if (mode !== "hybrid") { const where = placement(exec); return { where, reason: `mode ${EXECUTION_MODES.includes(mode) ? mode : "local"}` }; }
   if (!(Number.isInteger(exec.maxRemote) && exec.maxRemote >= 1)) return { where: "local", reason: "max_remote 0" };
   if (verifyMode === "ci") return { where: "local", reason: "verify.mode ci: validation runs on CI, not billed twice" };
   const names = (Array.isArray(labels) ? labels : []).map((l) => String(l ?? "").trim().toLowerCase());
   if (names.some((l) => DOCS_LABELS.has(l))) return { where: "local", reason: "docs-only lane" };
-  if (weight?.heavy === true) {
+  if (exec.heavy === true) return { where: "remote", reason: "execution.heavy: true" };
+  if (exec.heavy !== false && weight?.heavy === true) {
     const sig = (Array.isArray(weight.signals) ? weight.signals : []).map(String).filter(Boolean);
     return { where: "remote", reason: `heavy validation${sig.length ? `: ${sig.join(", ")}` : ""}` };
   }
@@ -188,6 +236,9 @@ const HEAVY_MARKERS = Object.freeze([
   ["pom.xml", "maven"], ["build.gradle", "gradle"], ["build.gradle.kts", "gradle"],
   ["eslint.config.js", "eslint"], ["eslint.config.mjs", "eslint"], ["eslint.config.cjs", "eslint"], [".eslintrc", "eslint"], [".eslintrc.js", "eslint"], [".eslintrc.cjs", "eslint"], [".eslintrc.json", "eslint"], [".eslintrc.yml", "eslint"],
 ]);
+const SKIP_DIRS = new Set(["node_modules", "vendor", "dist", "build", "target", "venv", "__pycache__"]);
+const MAX_SCAN_DIRS = 200;
+const defaultList = async (d) => (await readdir(d, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
 const HEAVY_SCRIPTS = Object.freeze(["test", "lint", "typecheck", "type-check", "build"]);
 
 /**
@@ -195,7 +246,7 @@ const HEAVY_SCRIPTS = Object.freeze(["test", "lint", "typecheck", "type-check",
  * classifies heavy (heavy.mjs `classifyStep`), or a heavy toolchain marker or package.json test/lint/typecheck/build script
  * exists. The toolchain pin (toolchain.mjs `detectPins`) names the package manager among the signals. Zero LLM.
  */
-export async function validationWeight({ cwd = process.cwd(), precheckCommands = [], read = (p) => readFile(p, "utf8") } = {}) {
+export async function validationWeight({ cwd = process.cwd(), precheckCommands = [], read = (p) => readFile(p, "utf8"), list = defaultList } = {}) {
   const signals = [];
   const add = (s) => { if (!signals.includes(s)) signals.push(s); };
   for (const cmd of Array.isArray(precheckCommands) ? precheckCommands : []) {
@@ -203,11 +254,23 @@ export async function validationWeight({ cwd = process.cwd(), precheckCommands =
     if (name && classifyStep(name, args) === "heavy") add(name.split("/").pop());
   }
   const exists = async (f) => { try { await read(join(cwd, f)); return true; } catch { return false; } };
-  for (const [f, sig] of HEAVY_MARKERS) if (await exists(f)) add(sig);
-  let pkg = null;
-  try { pkg = JSON.parse(String(await read(join(cwd, "package.json")))); } catch { pkg = null; }
-  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
-  for (const k of HEAVY_SCRIPTS) if (typeof scripts[k] === "string" && scripts[k].trim()) add(`${k} script`);
+  const scan = async (dir) => {
+    for (const [f, sig] of HEAVY_MARKERS) if (await exists(join(dir, f))) add(sig);
+    let pkg = null;
+    try { pkg = JSON.parse(String(await read(join(cwd, dir, "package.json")))); } catch { pkg = null; }
+    const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    for (const k of HEAVY_SCRIPTS) if (typeof scripts[k] === "string" && scripts[k].trim()) add(`${k} script`);
+  };
+  await scan("");
+  // Monorepo (#4523): markers one and two levels down (`web/tsconfig.json`, `services/x/pyproject.toml`), bounded.
+  const subdirs = async (dir) => { try { return (await list(join(cwd, dir))).filter((d) => !SKIP_DIRS.has(d) && !d.startsWith(".")).sort(); } catch { return []; } };
+  let scanned = 0;
+  outer: for (const d1 of await subdirs("")) {
+    for (const dir of [d1, ...(await subdirs(d1)).map((d2) => join(d1, d2))]) {
+      if (scanned++ >= MAX_SCAN_DIRS) break outer;
+      await scan(dir);
+    }
+  }
   if (signals.length) {
     let pins = null;
     try { pins = await detectPins(cwd, { read: (p) => read(p) }); } catch { pins = null; }
@@ -335,6 +398,18 @@ export function remoteTransportFor(exec = {}, { transport = null, env = process.
   return httpTransport({ endpoint: exec.endpoint, token: exec.tokenEnv ? credentials(exec.tokenEnv) : null });
 }
 
+/**
+ * The local pool router's endpoint and token (#4546): `COMPUTESHARE_CONFIG` or `~/.config/computeshare/router.json`
+ * (`listen.host`/`listen.port`), token from `forgedock_token_file` or the sibling `forgedock.token`. Null when unreadable.
+ */
+export function poolRouterConfig({ env = process.env, path = env.COMPUTESHARE_CONFIG || join(homedir(), ".config/computeshare/router.json") } = {}) {
+  const c = readJson(path);
+  if (!c?.listen?.host || !c.listen.port) return null;
+  let token = null;
+  try { token = readFileSync(c.forgedock_token_file ?? join(dirname(path), "forgedock.token"), "utf8").trim() || null; } catch { token = null; }
+  return { endpoint: `http://${c.listen.host}:${c.listen.port}`, token };
+}
+
 /** A provider by name; throws a typed error for an unknown one. `remote` reads `opts.exec` (parseExecution output). */
 export function providerByName(name, opts) {
   if (name === "local") return localProvider(opts);
@@ -344,6 +419,20 @@ export function providerByName(name, opts) {
     const env = opts?.env ?? process.env;
     return remoteProvider({ batch: opts.batch, repo: opts.repo, settings: exec, env, transport: remoteTransportFor(exec, { transport: opts?.transport, env }), ...(opts?.now ? { now: opts.now } : {}) });
   }
+  if (name === "pool") {
+    // #4546: `remote` with the endpoint and token defaulted to the local router, and the repo's forge.yaml sent along.
+    const env = opts?.env ?? process.env;
+    const exec = opts?.exec ?? {};
+    const router = opts?.transport || exec.endpoint ? null : poolRouterConfig({ env, ...(opts?.poolConfigPath ? { path: opts.poolConfigPath } : {}) });
+    if (!opts?.transport && !exec.endpoint && !router) throw typedError("execution.provider.misconfigured", "execution.provider pool needs a local router config (forgedock pool router) or execution.endpoint");
+    let forgeYaml = null;
+    try { forgeYaml = opts?.cwd ? readFileSync(join(opts.cwd, "forge.yaml"), "utf8") : null; } catch { forgeYaml = null; }
+    // The router's token is resolved under a fixed name so remoteProvider redacts it like any `token_env` credential.
+    const tokenEnv = exec.tokenEnv ?? (router?.token ? "FORGEDOCK_POOL_TOKEN" : undefined);
+    const credentials = (n) => (n === "FORGEDOCK_POOL_TOKEN" && !exec.tokenEnv ? router?.token ?? null : resolveCredential(n, { env }));
+    const settings = { ...exec, ...(exec.endpoint ? {} : router ? { endpoint: router.endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}) };
+    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings, name: "pool", env, credentials, transport: remoteTransportFor(settings, { transport: opts?.transport, env, credentials }), ...(opts?.now ? { now: opts.now } : {}) });
+  }
   const e = new Error(`unknown execution.provider ${JSON.stringify(name)} (known: ${SANDBOX_PROVIDERS.join(", ")})`);
   e.code = "execution.provider.unknown";
   throw e;
@@ -365,7 +454,8 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     try { u = typeof provider.usage === "function" ? await provider.usage(h, { startedAt, endedAt }) : null; } catch { u = null; }
     const minutes = nonNeg(u?.minutes) ?? nonNeg(h?.minutes) ?? round1(Math.max(0, endedAt - startedAt) / 60000);
     const cost = nonNeg(u?.cost_usd) ?? minutes * cpm;
-    return { ...r, sandbox: { provider: provider.name, id: h.id, minutes: round1(minutes), cost_usd: round6(cost) } };
+    const agent = typeof u?.agent === "string" && u.agent ? u.agent : typeof h?.agent === "string" && h.agent ? h.agent : null; // #4549: the pool agent
+    return { ...r, sandbox: { provider: provider.name, id: h.id, minutes: round1(minutes), cost_usd: round6(cost), ...(agent ? { agent } : {}) } };
   };
   const tear = async (led, h) => {
     let ok = false;
@@ -411,7 +501,7 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
       await tear(led, h); // every path, after the result is in (tear never throws)
       return started ? withUsage(r, h) : r; // a sandbox that never started used nothing
     },
-    adopt: async (n, rec) => {
+    adopt: async (n, rec, ctx = {}) => {
       const saved = rec?.handle;
       if (!saved?.id || saved.provider !== provider.name) return null;
       // Usage runs from the sandbox's real start (persisted on the handle), not from this adopt.
@@ -420,7 +510,9 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
       led?.register("sandbox", h.id, { provider: provider.name, handle: { provider: h.provider, id: h.id, issue: h.issue, ...(Number.isFinite(h.startedAt) ? { startedAt: h.startedAt } : {}) } }); // now owned by this dispatcher
       let r;
       try {
-        r = !(await provider.fetchResult(h)) && (await provider.status(h)) !== "running" ? null : await wait(h); // null: relaunched
+        const ended = await provider.fetchResult(h);
+        if (!ended && (await provider.status(h)) !== "running") r = null; // relaunched
+        else { if (!ended) ctx.onLive?.(); r = await wait(h); } // #4504: a live sandbox is awaited in the background
       } catch (e) {
         r = { terminalReason: "engine-error", detail: `sandbox ${h.id}: ${errText(e)}` };
       }

package/bin/lean/execution.test.mjs

@@ -6,7 +6,7 @@ import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { parseExecution, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -42,6 +42,11 @@ const NO_BUDGET = { batchMinutes: null, batchUsd: null, dayMinutes: null, dayUsd
 const ledgerIn = (root, { pid = process.pid, host = HOST } = {}) => (n) => makeLedger({ root, batch: "bt", lane: `sandbox-${n}`, owner: "orch_test", issue: n, host, pid });
 
 describe("execution config (#4253)", () => {
+  it("pool is a known sandbox provider (#4546)", () => {
+    assert.ok(SANDBOX_PROVIDERS.includes("pool"));
+    assert.equal(parseExecution({ mode: "hybrid", max_remote: "1", provider: "pool" }).provider, "pool");
+  });
+
   it("absent, empty or invalid config is local; max_remote and secrets are validated", () => {
     assert.deepEqual(parseExecution(undefined), { mode: "local", maxRemote: 0, provider: "local", image: null, secrets: [], budget: NO_BUDGET });
     assert.deepEqual(parseExecution({ mode: "cloud", max_remote: "-1" }), { mode: "local", maxRemote: 0, provider: "local", image: null, secrets: [], budget: NO_BUDGET });
@@ -440,6 +445,19 @@ describe("execution budget and sandbox cost (#4255)", () => {
       "sandbox: 1 lane, 12.5 min, $0.25 (token cost $1.50); budget: batch 10 min, day $20; host today 12.5 min, $0.25; cap reached, 1 held");
   });
 
+  it("report: sandbox usage agent becomes per-agent minutes on the row and a by-agent summary suffix (#4549)", async () => {
+    const lines = formatSandboxSummary([
+      { issue: 1, outcome: "merged", cost_usd: 1, sandbox: { minutes: 10, cost_usd: 0, attempts: 1, by_agent: { legion: 10 } } },
+      { issue: 2, outcome: "merged", cost_usd: 1, sandbox: { minutes: 30.5, cost_usd: 0, attempts: 2, by_agent: { legion: 20.5, box2: 10 } } }]);
+    assert.match(lines, /; by agent: legion 30\.5 min, box2 10\.0 min$/);
+    assert.doesNotMatch(formatSandboxSummary([{ issue: 1, outcome: "merged", cost_usd: 1, sandbox: { minutes: 1, cost_usd: 0 } }]), /by agent/);
+    const prov = fakeProvider({ finish: () => ({ terminalReason: "merged", pr: 2 }), usage: async () => ({ minutes: 7, agent: "legion" }) });
+    const lanes = providerLanes({ provider: prov, laneArgs: () => [], ledgerFor: ledgerIn(tmpDir("exec-agent-")), pollMs: 1, now: () => 1000 });
+    const rows = await orchestrate({ issues: [5], parallel: 1, store: null, readBody: async () => "", now: () => 0, remote: { max: 1, isRemote: () => true },
+      runOne: (n, l, ctx) => lanes.runOne(n, l, ctx) });
+    assert.deepEqual(rows[0].sandbox.by_agent, { legion: 7 });
+  });
+
   it("runBatch: rows, report.json and FORGE:TELEMETRY carry each lane's sandbox usage; the host-day store records it", async () => {
     const work = tmpDir("exec-cli-cost-");
     const ledRoot = join(work, "ledger");
@@ -502,6 +520,28 @@ describe("hybrid placement (#4256)", () => {
     assert.deepEqual(await validationWeight({ cwd: repoWith({}), precheckCommands: ["echo ok", "git diff --check"] }), { heavy: false, signals: [] });
   });
 
+  it("validationWeight sees monorepo subdirectory markers (#4523)", async () => {
+    const repo = (files) => { const d = tmpDir("vw-mono-"); for (const [f, t] of Object.entries(files)) { mkdirSync(join(d, f, ".."), { recursive: true }); writeFileSync(join(d, f), t); } return d; };
+    const mono = repo({ "package.json": "{}", "services/x/pyproject.toml": "[project]", "web/tsconfig.json": "{}" });
+    assert.deepEqual(await validationWeight({ cwd: mono }), { heavy: true, signals: ["python", "tsc"] });
+    assert.equal((await validationWeight({ cwd: repo({ "web/package.json": JSON.stringify({ scripts: { lint: "eslint ." } }) }) })).heavy, true);
+    assert.deepEqual(await validationWeight({ cwd: repo({ "node_modules/a/tsconfig.json": "{}", ".git/x/go.mod": "m", "a/b/c/Cargo.toml": "x" }) }), { heavy: false, signals: [] });
+  });
+
+  it("execution.heavy overrides placement only (#4523)", () => {
+    const hy = (heavy) => parseExecution({ mode: "hybrid", max_remote: "2", ...(heavy === undefined ? {} : { heavy }) });
+    assert.equal(hy().heavy, undefined);
+    assert.equal(hy("TRUE").heavy, true);
+    assert.equal(hy("false").heavy, false);
+    assert.equal(hy("maybe").heavy, undefined);
+    const LIGHT = { heavy: false, signals: [] }, HEAVY = { heavy: true, signals: ["tsc"] };
+    assert.deepEqual(placeLane({ exec: hy("true"), weight: LIGHT, headroom: { ok: true } }), { where: "remote", reason: "execution.heavy: true" });
+    assert.deepEqual(placeLane({ exec: hy("false"), weight: HEAVY, headroom: { ok: true } }), { where: "local", reason: "light lane, host has headroom" });
+    assert.equal(placeLane({ exec: hy("false"), weight: HEAVY, headroom: { ok: false, detail: "mem" } }).where, "remote");
+    assert.equal(placeLane({ exec: hy("true"), verifyMode: "ci", weight: LIGHT }).where, "local");
+    assert.equal(placeLane({ exec: parseExecution({ mode: "hybrid", max_remote: "0", heavy: "true" }), weight: LIGHT }).where, "local");
+  });
+
   it("hostHeadroom: memory below the admission floor plus one heavy step, or a configured load ceiling", () => {
     const host = (mem, load = 1, cores = 4) => ({ memAvailableMb: () => mem, loadAvg1: () => load, cores: () => cores });
     assert.deepEqual(hostHeadroom({ host: host(8000) }), { ok: true, detail: "" });
@@ -581,3 +621,63 @@ describe("hybrid placement (#4256)", () => {
     assert.deepEqual(res.rows[0].placement, { where: "remote", reason: "heavy validation: tsc" });
   });
 });
+
+describe("#4547: fallback_local and agent liveness", () => {
+  it("parseExecution: fallback_local is opt-in", () => {
+    assert.equal(parseExecution({ mode: "remote", max_remote: "2" }).fallbackLocal, undefined);
+    assert.equal(parseExecution({ mode: "remote", max_remote: "2", fallback_local: "true" }).fallbackLocal, true);
+    assert.equal(parseExecution({ mode: "remote", fallback_local: "yes" }).fallbackLocal, undefined);
+  });
+  it("transport capacity carries free and liveness; none valid is unknown", async () => {
+    const { httpTransport } = await import("./sandbox-remote.mjs");
+    const cap = async (data, ok = true) => httpTransport({ endpoint: "http://pool.test", token: "t", fetchFn: async () => ({ ok, status: ok ? 200 : 500, headers: new Headers(), text: async () => JSON.stringify(data) }) }).capacity();
+    assert.deepEqual(await cap({ online: 0, total: 2, agents: [] }), { online: 0, total: 2 });
+    assert.deepEqual(await cap({ free: 3 }), { free: 3 });
+    assert.equal(await cap({ online: -1 }), null);
+    assert.equal(await cap({ online: 1 }, false), null);
+  });
+});
+
+describe("host capabilities in placement (#4542)", () => {
+  it("placeLane: a need the provider does not relay is local in remote and hybrid mode, with the reason", () => {
+    assert.deepEqual(placeLane({ exec: { mode: "remote" }, needs: ["sops"] }), { where: "local", reason: "host capability: sops" });
+    assert.deepEqual(placeLane({ exec: { mode: "hybrid", maxRemote: 2, heavy: true }, needs: ["prod_monitor", "sops"] }), { where: "local", reason: "host capability: prod_monitor, sops" });
+    assert.equal(placeLane({ exec: { mode: "remote", maxRemote: 2 }, needs: ["sops"], relays: ["sops"] }).where, "remote");
+  });
+
+  it("no needs: placement is unchanged", () => {
+    assert.deepEqual(placeLane({ exec: { mode: "remote", maxRemote: 2 }, needs: [] }), { where: "remote", reason: "mode remote" });
+    assert.deepEqual(placeLane({ exec: { mode: "remote", maxRemote: 2 } }), { where: "remote", reason: "mode remote" });
+    assert.equal(placeLane({ exec: { mode: "hybrid", maxRemote: 2, heavy: true } }).where, "remote");
+  });
+
+  it("detectNeeds: built-in signals, declared names and declared patterns, zero LLM", () => {
+    assert.deepEqual(detectNeeds("Edit `.secrets/prod.enc.yaml` and run ssh ovh-monitor; see credentials.yaml"), ["ops_credentials", "prod_monitor", "sops"]);
+    assert.deepEqual(detectNeeds("plain change to src/a.js"), []);
+    const exec = parseExecution({ mode: "remote", max_remote: "2", host_capabilities: "vault, Bad Name", host_capability_patterns: "vault:vault\\s+kv, x:(" });
+    assert.deepEqual(exec.hostCapabilities, ["vault"]);
+    assert.deepEqual(exec.hostCapabilityPatterns, [{ name: "vault", pattern: "vault\\s+kv" }]);
+    assert.deepEqual(detectNeeds("run vault kv get", exec), ["vault"]);
+    assert.deepEqual(detectNeeds("needs the Vault", exec), ["vault"]);
+  });
+
+  it("hostCapabilityBlock: only declared capabilities count; a mixed or unknown need stays a human block", () => {
+    const caps = { hostCapabilities: ["sops"] };
+    assert.deepEqual(hostCapabilityBlock("this lane has no sops key", caps), ["sops"]);
+    assert.deepEqual(hostCapabilityBlock("this lane has no sops key", null), []);
+    assert.deepEqual(hostCapabilityBlock("no sops key and no ssh ovh-monitor", caps), []);
+    assert.deepEqual(hostCapabilityBlock("owner must create an account", caps), []);
+  });
+
+  it("orchestrate: a remote lane that ends env.capability_remote is relaunched locally once", async () => {
+    const calls = [];
+    const rows = await orchestrate({ issues: [5], parallel: 2, recovery: { maxAttempts: 1 }, readBody: async () => "",
+      remote: { max: 2, isRemote: () => true, place: () => ({ where: "remote", reason: "mode remote" }), admit: () => ({ ok: true }), onBudget: "stop", costPerMinute: 0 },
+      runOne: async (n, _l, ctx = {}) => {
+        calls.push({ remote: !!ctx.remote, placement: ctx.placement?.where, recover: ctx.recover?.code ?? null });
+        return ctx.recover ? { terminalReason: "merged", pr: 9 } : { terminalReason: "needs-human", code: "env.capability_remote", detail: "no sops" };
+      } });
+    assert.deepEqual(calls, [{ remote: true, placement: "remote", recover: null }, { remote: false, placement: "local", recover: "env.capability_remote" }]);
+    assert.equal(rows.find((r) => r.issue === 5).outcome, "merged");
+  });
+});

package/bin/lean/hostkill.mjs

@@ -0,0 +1,8 @@
+/**
+ * #4518: a builder CLI killed from outside (host or OOM guard, scope stop, operator SIGTERM) exits with SIGTERM/SIGKILL
+ * or status 143/137 and no timer of ours fired (our own kills throw CLI_TIMEOUT / CLI_IDLE / CLI_CONTEXT / CLI_TURNS).
+ */
+export function isExternalKill(e) {
+  if (e?.code !== "CLI_BACKEND_FAILED") return false;
+  return e.signal === "SIGTERM" || e.signal === "SIGKILL" || e.status === 143 || e.status === 137;
+}