forgedock 1.32.1 → 1.33.0

package/bin/pool/http.mjs

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { timingSafeEqual } from "node:crypto";
+
+export async function readJson(req, limit = 1 << 20) {
+  const chunks = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > limit) throw Object.assign(new Error("body too large"), { status: 413 });
+    chunks.push(c);
+  }
+  if (!size) return null;
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { throw Object.assign(new Error("invalid json"), { status: 400 }); }
+}
+
+export function send(res, status, data, headers = {}) {
+  const body = data === undefined ? "" : typeof data === "string" ? data : JSON.stringify(data);
+  res.writeHead(status, { "content-type": typeof data === "string" ? "text/plain; charset=utf-8" : "application/json", ...headers });
+  res.end(body);
+}
+
+export function sameSecret(a, b) {
+  const x = Buffer.from(String(a ?? "")), y = Buffer.from(String(b ?? ""));
+  return x.length > 0 && x.length === y.length && timingSafeEqual(x, y);
+}
+
+/** True when the request carries `Authorization: Bearer <token>`. */
+export function bearerOk(req, token) {
+  const m = /^Bearer\s+(\S.*)$/i.exec(req.headers.authorization ?? "");
+  return Boolean(m) && sameSecret(m[1].trim(), token);
+}
+
+/** JSON call to another computeshare process; never throws on HTTP status, only on transport failure. */
+export async function call(base, method, path, { body, token, timeoutMs = 15000, fetchFn = globalThis.fetch } = {}) {
+  const res = await fetchFn(`${String(base).replace(/\/+$/, "")}${path}`, {
+    method,
+    headers: { accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+  return { status: res.status, ok: res.ok, data, retryAfter: res.headers.get("retry-after") };
+}
+
+export function route(method, pattern) {
+  const re = new RegExp(`^${pattern.replace(/:(\w+)/g, "(?<$1>[^/]+)")}$`);
+  return (req, url) => {
+    if (req.method !== method) return null;
+    const m = re.exec(url.pathname);
+    return m ? Object.fromEntries(Object.entries(m.groups ?? {}).map(([k, v]) => [k, decodeURIComponent(v)])) : null;
+  };
+}

package/bin/pool/router.mjs

@@ -0,0 +1,299 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { bearerOk, call, readJson, route, sameSecret, send } from "./http.mjs";
+import { jsonStore } from "./store.mjs";
+import { versionOf } from "./version.mjs";
+
+const run = promisify(execFile);
+
+/**
+ * Router: the endpoint ForgeDock's remote provider talks to (POST /sandboxes, GET /sandboxes/:id[/logs|/result|/usage],
+ * DELETE /sandboxes/:id). It places each sandbox on the enrolled agent with the most free reserved CPU, forwards every
+ * later call to that agent, renews the agent lease while ForgeDock keeps polling, and destroys sandboxes ForgeDock
+ * has abandoned. It also serves the agent installer and enrollment.
+ */
+export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date.now(), log = console } = {}) {
+  const store = jsonStore(join(cfg.state_dir, "router-state.json"), { agents: {}, sandboxes: {} });
+  const agents = () => store.data.agents;
+  const sbx = () => store.data.sandboxes;
+  const lane = { cpus: cfg.lane?.cpus ?? 2, mem_gb: cfg.lane?.mem_gb ?? 3 };
+  const abandonMs = (cfg.abandon_after_s ?? 1800) * 1000;
+  const codes = () => (store.data.codes ??= {});
+  // State maps are keyed by caller input (install codes, agent names, sandbox ids): read own keys only, so a key like
+  // "__proto__" or "constructor" never resolves to an inherited member.
+  const own = (map, key) => (typeof key === "string" && Object.hasOwn(map, key) ? map[key] : undefined);
+  const codeTtlMs = (cfg.code_ttl_s ?? 1800) * 1000;
+  /** The long-lived enroll token, or an unexpired one-time install code (consumed by a successful enrollment). */
+  function enrollOk(token, consume = false) {
+    if (sameSecret(token, cfg.enroll_token)) return true;
+    const c = own(codes(), token);
+    if (!c || c.used || c.expires <= now()) return false;
+    if (consume) { c.used = true; store.save(); }
+    return true;
+  }
+  function issueCode() {
+    const code = randomBytes(9).toString("base64url");
+    codes()[code] = { expires: now() + codeTtlMs, used: false };
+    store.save();
+    return { code, expires_at: new Date(now() + codeTtlMs).toISOString() };
+  }
+  /** The enrolled agent whose token the request carries, or null. */
+  function agentFor(req) {
+    const m = /^Bearer\s+(\S.*)$/i.exec(req.headers.authorization ?? "");
+    if (!m) return null;
+    return Object.entries(agents()).find(([, a]) => sameSecret(m[1].trim(), a.token))?.[0] ?? null;
+  }
+  // Fresh GitHub token for sandboxes, read from this host's gh (kept fresh by its own refresh timer).
+  let gh = { token: null, at: 0 };
+  async function githubToken() {
+    if (!gh.token || now() - gh.at > 60000) {
+      const { stdout } = await run(cfg.gh_bin ?? "gh", ["auth", "token"], { timeout: 20000 });
+      gh = { token: stdout.trim(), at: now() };
+    }
+    return gh.token;
+  }
+  // Claude access token for sandboxes: the logged-in account on this host with the most validity left. Only the
+  // short-lived access token is shared; refresh tokens stay here, so this host keeps refreshing its own sessions.
+  function claudeToken() {
+    const dirs = cfg.claude_config_dirs ?? readdirSync(homedir()).filter((d) => /^\.claude(-\d+)?$/.test(d)).map((d) => join(homedir(), d));
+    let best = null;
+    for (const d of dirs) {
+      try {
+        const o = JSON.parse(readFileSync(join(d, ".credentials.json"), "utf8")).claudeAiOauth;
+        if (o?.accessToken && o.expiresAt > now() + 30 * 60000 && (!best || o.expiresAt > best.expiresAt)) best = o;
+      } catch { /* no login in this dir */ }
+    }
+    if (!best) throw Object.assign(new Error("no Claude login on the router host with 30+ minutes left"), { status: 503 });
+    return { token: best.accessToken, expires_at: new Date(best.expiresAt).toISOString() };
+  }
+  const agentCall = (a, method, path, body, timeoutMs) => call(a.url, method, path, { body, token: a.token, timeoutMs, fetchFn });
+
+  async function capacities() {
+    const out = [];
+    for (const [name, a] of Object.entries(agents())) {
+      try {
+        const r = await agentCall(a, "GET", "/capacity", undefined, 5000);
+        out.push(r.ok ? { name, ok: true, ...r.data } : { name, ok: false, error: `HTTP ${r.status}` });
+      } catch (e) { out.push({ name, ok: false, error: String(e.message ?? e) }); }
+    }
+    return out;
+  }
+
+  /** Agent liveness for the scheduler (#4547): an agent is online when it answers and is not paused. */
+  async function status() {
+    const caps = await capacities();
+    const agentsView = caps.map((c) => ({ name: c.name, ok: c.ok, paused: Boolean(c.paused) }));
+    return { online: agentsView.filter((a) => a.ok && !a.paused).length, total: agentsView.length, agents: agentsView };
+  }
+
+  /** Per-repo extras: the gitignored forge.yaml, and a private Docker daemon (with a bigger reservation) when enabled. */
+  const repoCfg = (spec) => cfg.repos?.[spec?.repo?.slug] ?? {};
+  // Placement counts the (small) reservation; `limit` is each container's hard burst cap (burst model, when configured).
+  const sizeFor = (spec) => {
+    const docker = Boolean(repoCfg(spec).docker), dind = cfg.dind ?? { cpus: 1, mem_gb: 2 };
+    const size = docker ? { cpus: lane.cpus + dind.cpus, mem_gb: lane.mem_gb + dind.mem_gb } : { cpus: lane.cpus, mem_gb: lane.mem_gb };
+    if (cfg.lane?.limit) {
+      size.limit = { lane_cpus: cfg.lane.limit.cpus, lane_mem_gb: cfg.lane.limit.mem_gb, lane_swap_gb: cfg.lane.limit.swap_gb ?? 0,
+        ...(docker ? { dind_cpus: dind.limit?.cpus ?? 2, dind_mem_gb: dind.limit?.mem_gb ?? 3, dind_swap_gb: dind.limit?.swap_gb ?? 0 } : {}) };
+    }
+    return size;
+  };
+  function withForgeYaml(spec0) {
+    const spec = repoCfg(spec0).docker ? { ...spec0, docker: true } : spec0;
+    const path = repoCfg(spec).forge_yaml;
+    if (!path) return spec;
+    try { return { ...spec, env: { ...(spec.env ?? {}), CS_FORGE_YAML_B64: readFileSync(path).toString("base64") } }; }
+    catch (e) { log.warn?.(`forge.yaml for ${spec.repo.slug} unreadable: ${e.message}`); return spec; }
+  }
+
+  async function launch(spec) {
+    if (typeof spec?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(spec.id)) return { status: 400, body: { error: "spec.id required ([A-Za-z0-9._-], max 128)" } };
+    const known = own(sbx(), spec.id);
+    if (known && own(agents(), known.agent)) {
+      known.touched = now(); store.save();
+      const r = await agentCall(own(agents(), known.agent), "POST", "/sandboxes", { spec: withForgeYaml(spec), ...sizeFor(spec) });
+      return { status: r.status, body: r.data, retryAfter: r.retryAfter };
+    }
+    const size = sizeFor(spec);
+    const fits = (await capacities()).filter((c) => c.ok && !c.paused && c.cpus_free >= size.cpus && c.mem_free_gb >= size.mem_gb)
+      .sort((a, b) => b.cpus_free - a.cpus_free || b.mem_free_gb - a.mem_free_gb);
+    for (const c of fits) {
+      const r = await agentCall(own(agents(), c.name), "POST", "/sandboxes", { spec: withForgeYaml(spec), ...size }, 120000);
+      if (r.status === 503) continue; // raced with another launch; try the next host
+      if (r.ok) { sbx()[spec.id] = { agent: c.name, issue: spec.issue ?? null, batch: spec.batch ?? null, createdAt: now(), touched: now() }; store.save(); }
+      return { status: r.status, body: { ...(r.data ?? {}), agent: c.name } };
+    }
+    return { status: 503, body: { error: "no host has a free reservation", lane: size }, retryAfter: cfg.retry_after_s ?? 60 };
+  }
+
+  async function forward(id, method, path) {
+    const s = own(sbx(), id);
+    const a = s && own(agents(), s.agent);
+    if (!a) return { status: 404, body: { state: "gone" } };
+    s.touched = now(); store.save();
+    try {
+      const r = await agentCall(a, method, path);
+      if (method === "DELETE" && (r.ok || r.status === 404)) { delete sbx()[id]; store.save(); }
+      return { status: r.status, body: r.data };
+    } catch (e) { return { status: 502, body: { error: `agent ${s.agent} unreachable: ${e.message}` } }; }
+  }
+
+  /** Renew leases for sandboxes ForgeDock still polls; destroy the ones it abandoned. */
+  async function tick() {
+    for (const [k, c] of Object.entries(codes())) if (c.expires <= now()) delete codes()[k];
+    for (const [id, s] of Object.entries(sbx())) {
+      const a = own(agents(), s.agent);
+      if (!a) { delete sbx()[id]; continue; }
+      try {
+        if (now() - s.touched > abandonMs) {
+          const r = await agentCall(a, "DELETE", `/sandboxes/${encodeURIComponent(id)}`);
+          if (r.ok || r.status === 404) { delete sbx()[id]; log.info?.(`abandoned ${id} destroyed on ${s.agent}`); }
+        } else {
+          const r = await agentCall(a, "POST", `/sandboxes/${encodeURIComponent(id)}/lease`);
+          if (r.status === 404) { delete sbx()[id]; log.info?.(`${id} gone on ${s.agent}`); }
+        }
+      } catch (e) { log.warn?.(`lease ${id} on ${s.agent}: ${e.message}`); }
+    }
+    store.save();
+  }
+
+  function enroll(body) {
+    if (!enrollOk(body?.token)) return { status: 401, body: { error: "bad enrollment token" } };
+    const name = String(body.name ?? "").toLowerCase().replace(/[^a-z0-9-]/g, "");
+    let url;
+    try { url = new URL(String(body.url)); } catch { return { status: 400, body: { error: "url required" } }; }
+    if (!name) return { status: 400, body: { error: "name required" } };
+    enrollOk(body.token, true);
+    const token = randomBytes(32).toString("hex");
+    agents()[name] = { url: url.origin, token, enrolledAt: new Date(now()).toISOString() };
+    store.save();
+    log.info?.(`enrolled agent ${name} at ${url.origin}`);
+    return { status: 200, body: { name, agent_token: token } };
+  }
+
+  function bootstrapScript(token, url) {
+    const q = (s) => `'${String(s).replace(/'/g, "''")}'`;
+    const int = (k) => { const v = Number(url?.searchParams.get(k)); return Number.isInteger(v) && v > 0 ? v : 0; };
+    const sizing = `${int("cpus") ? ` -AllowCpus ${int("cpus")}` : ""}${int("mem") ? ` -AllowMemGb ${int("mem")}` : ""}`;
+    return [
+      "$ErrorActionPreference = 'Stop'",
+      `$RouterUrl = ${q(cfg.public_url)}`,
+      `$EnrollToken = ${q(token)}`,
+      "$tmp = Join-Path $env:TEMP 'computeshare-install'",
+      "Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue",
+      "New-Item -ItemType Directory -Path $tmp | Out-Null",
+      "Invoke-WebRequest -UseBasicParsing \"$RouterUrl/bootstrap/bundle.tar.gz?token=$EnrollToken\" -OutFile (Join-Path $tmp 'bundle.tar.gz')",
+      "tar.exe -xzf (Join-Path $tmp 'bundle.tar.gz') -C $tmp",
+      `& (Join-Path $tmp 'pool\\install\\install-agent.ps1') -RouterUrl $RouterUrl -EnrollToken $EnrollToken -BundlePath (Join-Path $tmp 'bundle.tar.gz')${sizing}`,
+      "",
+    ].join("\r\n");
+  }
+
+  /** Stream an allow-listed image (docker save) to an agent whose daemon cannot reach the registry itself. */
+  async function sendImage(res, ref) {
+    const allowed = cfg.agent_images ?? ["docker:27.5.1-dind"];
+    if (!allowed.includes(ref)) return send(res, 404, { error: "image not offered" });
+    try { await run("docker", ["image", "inspect", ref], { timeout: 20000 }); }
+    catch { await run("docker", ["pull", "-q", ref], { timeout: 30 * 60000 }); }
+    const save = spawn("docker", ["save", ref]);
+    res.writeHead(200, { "content-type": "application/x-tar" });
+    save.stdout.pipe(res);
+    save.on("error", () => res.destroy());
+  }
+
+  function sendBundle(res) {
+    const tar = spawn("tar", ["-czf", "-", "-C", cfg.repo_root, "package.json", "bin/pool", "pool"]);
+    res.writeHead(200, { "content-type": "application/gzip" });
+    tar.stdout.pipe(res);
+    tar.on("error", () => res.destroy());
+  }
+
+  const fd = (fn) => ({ fn, auth: "forgedock" });
+  const routes = [
+    [route("GET", "/health"), { fn: async () => ({ status: 200, body: { ok: true, agents: Object.keys(agents()).length, sandboxes: Object.keys(sbx()).length } }), auth: "none" }],
+    [route("POST", "/sandboxes"), fd(async (_p, body) => launch(body))],
+    [route("GET", "/sandboxes/:id"), fd(async ({ id }) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}`))],
+    [route("GET", "/sandboxes/:id/logs"), fd(async ({ id }, _b, url) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}/logs?cursor=${encodeURIComponent(url.searchParams.get("cursor") ?? "0")}`))],
+    [route("GET", "/sandboxes/:id/result"), fd(async ({ id }) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}/result`))],
+    [route("GET", "/sandboxes/:id/usage"), fd(async ({ id }) => { // #4549: the placing agent rides along for per-agent minutes
+      const agent = own(sbx(), id)?.agent, r = await forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}/usage`);
+      return agent && r.status === 200 && r.body && typeof r.body === "object" ? { ...r, body: { ...r.body, agent } } : r;
+    })],
+    [route("DELETE", "/sandboxes/:id"), fd(async ({ id }) => forward(id, "DELETE", `/sandboxes/${encodeURIComponent(id)}`))],
+    [route("GET", "/status"), fd(async () => ({ status: 200, body: await status() }))],
+    [route("GET", "/agents"), fd(async () => ({ status: 200, body: { agents: await capacities(), sandboxes: sbx() } }))],
+    [route("POST", "/codes"), fd(async () => ({ status: 200, body: issueCode() }))],
+    [route("GET", "/agent/creds/github"), { fn: async () => ({ status: 200, body: { token: await githubToken() } }), auth: "agent" }],
+    [route("GET", "/agent/creds/claude"), { fn: async () => ({ status: 200, body: claudeToken() }), auth: "agent" }],
+    [route("GET", "/agent/bundle"), { fn: async () => ({ bundle: true }), auth: "agent" }],
+    [route("GET", "/agent/images/:ref"), { fn: async ({ ref }) => ({ image: ref }), auth: "agent" }],
+    [route("POST", "/agents/:name/upgrade"), fd(async ({ name }) => {
+      const a = own(agents(), name);
+      if (!a) return { status: 404, body: { error: "unknown agent" } };
+      const r = await agentCall(a, "POST", "/admin/update", {});
+      return { status: r.status, body: { ...(r.data ?? {}), target: versionOf(cfg.repo_root) } };
+    })],
+    [route("DELETE", "/agents/:name"), fd(async ({ name }) => {
+      if (!own(agents(), name)) return { status: 404, body: { error: "unknown agent" } };
+      for (const [id, x] of Object.entries(sbx())) if (x.agent === name) delete sbx()[id];
+      delete agents()[name]; store.save();
+      return { status: 200, body: { ok: true } };
+    })],
+    [route("POST", "/agents/:name/resize"), fd(async ({ name }, body) => {
+      const a = own(agents(), name);
+      if (!a) return { status: 404, body: { error: "unknown agent" } };
+      const r = await agentCall(a, "POST", "/admin/resize", body ?? {});
+      return { status: r.status, body: r.data };
+    })],
+    [route("GET", "/agents/:name/usage"), fd(async ({ name }) => {
+      const a = own(agents(), name);
+      if (!a) return { status: 404, body: { error: "unknown agent" } };
+      const r = await agentCall(a, "GET", "/usage-history");
+      return { status: r.status, body: r.data };
+    })],
+    [route("GET", "/version"), fd(async () => ({ status: 200, body: versionOf(cfg.repo_root) }))],
+    [route("POST", "/enroll"), { fn: async (_p, body) => enroll(body), auth: "none" }],
+    [route("GET", "/bootstrap/install.ps1"), { fn: async (_p, _b, url) => ({ status: 200, body: bootstrapScript(url.searchParams.get("token"), url) }), auth: "enroll" }],
+    [route("GET", "/bootstrap/bundle.tar.gz"), { fn: async () => ({ bundle: true }), auth: "enroll" }],
+  ];
+
+  async function handle(req, res) {
+    const url = new URL(req.url, "http://router");
+    if (!url.pathname.startsWith("/health")) log.info?.(`${req.socket.remoteAddress} ${req.method} ${url.pathname}`); // query (tokens) never logged
+    try {
+      for (const [match, r] of routes) {
+        const p = match(req, url);
+        if (!p) continue;
+        if (r.auth === "forgedock" && !bearerOk(req, cfg.forgedock_token)) return send(res, 401, { error: "unauthorized" });
+        if (r.auth === "agent" && !agentFor(req)) return send(res, 401, { error: "unauthorized" });
+        if (r.auth === "enroll" && !enrollOk(url.searchParams.get("token"))) return send(res, 401, "unauthorized\n");
+        const body = req.method === "POST" ? await readJson(req) : null;
+        const out = await r.fn(p, body, url);
+        if (out.bundle) return sendBundle(res);
+        if (out.image) return sendImage(res, out.image);
+        return send(res, out.status, out.body, out.retryAfter ? { "retry-after": String(out.retryAfter) } : {});
+      }
+      send(res, 404, { error: "not found" });
+    } catch (e) {
+      log.error?.(e);
+      send(res, e.status ?? 500, { error: e.status ? e.message : "internal error" });
+    }
+  }
+
+  return { handle, launch, tick, enroll, issueCode, capacities, status, store };
+}
+
+export function startRouter(cfg, deps) {
+  const router = createRouter(cfg, deps);
+  const server = createServer(router.handle);
+  server.listen(cfg.listen.port, cfg.listen.host);
+  const timer = setInterval(() => router.tick().catch((e) => console.error("tick failed", e)), (cfg.lease_interval_s ?? 60) * 1000);
+  return { router, server, close: () => { clearInterval(timer); server.close(); } };
+}

package/bin/pool/store.mjs

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Small JSON state file written atomically (temp file + rename), so a crash never leaves it half-written. */
+export function jsonStore(path, initial) {
+  let data;
+  try { data = JSON.parse(readFileSync(path, "utf8")); } catch { data = structuredClone(initial); }
+  return {
+    get data() { return data; },
+    save() {
+      mkdirSync(dirname(path), { recursive: true });
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+      renameSync(tmp, path);
+    },
+  };
+}
+
+export function readSecret(path) {
+  const v = readFileSync(path, "utf8").trim();
+  if (!v) throw new Error(`empty secret file ${path}`);
+  return v;
+}

package/bin/pool/version.mjs

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Content hash of a directory's files (sorted, non-recursive is enough for pool/image/ and bin/pool/). */
+function dirHash(dir) {
+  const h = createHash("sha256");
+  for (const f of readdirSync(dir).sort()) {
+    try { h.update(f); h.update(readFileSync(join(dir, f))); } catch { /* subdirectory */ }
+  }
+  return h.digest("hex").slice(0, 12);
+}
+
+/** What an agent is running: package version, code hash and lane-image recipe hash. Agents and router compare these. */
+export function versionOf(root = repoRoot) {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  return { version: pkg.version, code: dirHash(join(root, "bin", "pool")), image: dirHash(join(root, "pool", "image")) };
+}
+
+/** The lane image is tagged and built from the ForgeDock package version (no separate pin). */
+export const laneImageTag = (version) => `forgedock-lane:${version}`;
+export const laneBuildArgs = (version) => ({ FORGEDOCK_VERSION: version });
+
+/**
+ * `forgedock update` hook: push the new code and lane image to every enrolled agent. A no-op on hosts without a
+ * pool router config; never throws (a failed push must not fail the update). Returns "skipped" | "upgraded" | "failed".
+ */
+export async function upgradeAgentsAfterUpdate({ configPath = process.env.COMPUTESHARE_CONFIG ?? join(homedir(), ".config/computeshare/router.json"), runPoolCli, warn = console.warn } = {}) {
+  if (!existsSync(configPath)) return "skipped";
+  try {
+    const run = runPoolCli ?? (await import("./cli.mjs")).runPoolCli;
+    await run(["upgrade", "--config", configPath]);
+    return "upgraded";
+  } catch (e) {
+    warn(`pool upgrade after update failed: ${e.message}`);
+    return "failed";
+  }
+}

package/bin/runner.mjs

@@ -1809,6 +1809,7 @@ export function runCliBackend({
           ` Invocation: ${bin} ${argvSummary} (cwd: ${cwd})`,
       );
       err.code = "CLI_BACKEND_FAILED";
+      err.status = result.status ?? null; err.signal = result.signal ?? null; // #4518: lets bin/lean/hostkill.mjs tell an external kill
       // forge#2241: attach the CLI's reported session-limit reset time (when
       // present) so callers (bin/engine.mjs) can surface *when* a
       // quota-exhaustion failure will clear without reading raw logs. Only

package/bin/stats/aggregate.mjs

@@ -295,6 +295,12 @@ export function computeAlerts(lanes = [], opts = {}) {
       const ex = failed.flatMap((l) => l.deps).find((d) => (d.eco ?? "unknown") === eco && d.status === "failed");
       add(`DEPS_PREPARED failed (${eco})`, failed.length, used.length, c.depsFailedPct / 100, ex?.reason ?? null);
     }
+    // #4522: a broken snapshot falls back to a fresh install; the lane has dependencies, but the cache still needs a look.
+    const fell = used.filter((l) => l.deps.some((d) => (d.eco ?? "unknown") === eco && d.status === "materialize-fallback"));
+    if (fell.length / used.length > c.depsFailedPct / 100) {
+      const ex = fell.flatMap((l) => l.deps).find((d) => (d.eco ?? "unknown") === eco && d.status === "materialize-fallback");
+      add(`DEPS_PREPARED materialize-fallback (${eco})`, fell.length, used.length, c.depsFailedPct / 100, ex?.reason ?? null);
+    }
   }
   const deferred = win.filter((l) => l.deferred.length);
   if (deferred.length / win.length > c.deferredPct / 100) add("deferred-to-ci", deferred.length, win.length, c.deferredPct / 100, deferred[deferred.length - 1].deferred[0]);

package/bin/stats/index.mjs

@@ -16,12 +16,14 @@ import { parseForgeYaml } from "../forge-utils.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
 import { edgeQuery, parseEdge, verdictMix, contextPackAb, renderContextAb, builderTierReport, renderTiers, exploreAb, renderExploreAb, laneProfileReport, renderLaneProfiles } from "./query.mjs";
 import { batchEfficiency, windowEfficiency, formatEfficiencyLines, parseWindows } from "./efficiency.mjs";
+import { poolUtilisation, formatPoolLines } from "./pool.mjs";
 import { batchRoot } from "../lean/batch.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
 export const HELP = `Usage: forgedock stats [--since <version|date>] [--repo <owner/repo>] [--json] [--refresh]
                       [--compact] [--no-local] [--no-cache] [--min-n N] [--release-times FILE]
+       forgedock stats --pool [--window 7d,30d] [--repo <owner/repo>] [--json]
        forgedock stats --efficiency [--batch <id>] [--window 7d,30d] [--repo <owner/repo>] [--json]
 
 Version-over-version report: Cost, Time, Flow, Review funnel, Gates and Issue flow per (version, repo), with a
@@ -56,6 +58,9 @@ Explorer A/B (forge#4418; local run logs only, every run of each log, no GitHub
   --explore-ab          builder turns, builder cache-read, merge and conformance rates per size (S, M, L) and
                         lean.explore mode (on, off), plus the same issues run in both modes; --json for JSON
 
+Pool (forge#4549; local batch reports, no gh):
+  --pool                remote lane minutes, lanes and share per pool agent over --window (default 7d,30d)
+
 Efficiency (forge#4402; local batch dirs and run logs, gh only for merged issues' bodies, labels and probes):
   --efficiency          $/merge, turns/merge, context/turn per size and model, retries/merge by cause, no-action
                         lanes, issue quality vs cost and the acceptance pass rate 7 days after promotion
@@ -73,7 +78,7 @@ Lane profile baseline (forge#4436; local run logs only, every run of each issue,
 `;
 
 export function parseArgs(argv) {
-  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, exploreAb: false, tiers: false, laneProfile: false, issues: null, efficiency: false, batch: null, windows: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, exploreAb: false, tiers: false, laneProfile: false, issues: null, efficiency: false, pool: false, batch: null, windows: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
   const val = (i, name) => {
     const v = argv[i + 1];
     if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
@@ -95,6 +100,7 @@ export function parseArgs(argv) {
     else if (name === "--lane-profile") o.laneProfile = true;
     else if (name === "--issues") { const v = take(); if (!/^[1-9]\d*(,[1-9]\d*)*$/.test(v)) throw new Error("--issues must be a comma list of issue numbers"); o.issues = v.split(",").map(Number); }
     else if (name === "--efficiency") o.efficiency = true;
+    else if (name === "--pool") o.pool = true;
     else if (name === "--batch") { const v = take(); if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v)) throw new Error(`invalid --batch id: ${v}`); o.batch = v; }
     else if (name === "--window") o.windows = parseWindows(take());
     else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
@@ -106,7 +112,8 @@ export function parseArgs(argv) {
     else if (name === "--help" || name === "-h") o.help = true;
     else throw new Error(`unknown argument: ${a}`);
   }
-  if ((o.batch || o.windows) && !o.efficiency) throw new Error("--batch and --window need --efficiency");
+  if (o.batch && !o.efficiency) throw new Error("--batch and --window need --efficiency");
+  if (o.windows && !o.efficiency && !o.pool) throw new Error("--batch and --window need --efficiency");
   return o;
 }
 
@@ -215,6 +222,10 @@ export async function buildReport(opts, deps = {}) {
   if (opts.releaseTimes) releaseTimes = parseReleaseTimes(readFileSync(opts.releaseTimes, "utf8"));
   else if (deps.releaseTimes) releaseTimes = deps.releaseTimes;
   else releaseTimes = gitTagTimes();
+  if (opts.pool) { // forge#4549: local batch reports only
+    const pool = poolUtilisation({ batchRoot: deps.batchRoot ?? batchRoot(env), repo, windows: opts.windows ?? parseWindows("7d,30d"), now: deps.now?.() ?? Date.now() });
+    return { repo, query: { pool } };
+  }
   if (opts.efficiency) { // forge#4402: local batch dirs + run logs; gh only for merged issues
     const root = deps.batchRoot ?? batchRoot(env), rd = deps.runsDir ?? runsDir(env), now = deps.now?.() ?? Date.now(), gh = deps.gh ?? defaultGh;
     const efficiency = {};
@@ -276,6 +287,7 @@ export async function runStats(argv, deps = {}) {
     const report = await buildReport(opts, { onProgress: makeProgressPrinter(), ...deps });
     if (report.query?.lane_profile && !opts.json) { process.stdout.write(`${renderLaneProfiles(report.query.lane_profile)}\n`); return 0; }
     if (report.query?.tiers && !opts.json) { process.stdout.write(`${renderTiers(report.query.tiers)}\n`); return 0; }
+    if (report.query?.pool && !opts.json) { process.stdout.write(`${formatPoolLines(report.query.pool).join("\n")}\n`); return 0; }
     if (report.query?.efficiency && !opts.json) {
       const e = report.query.efficiency;
       const lines = [...(e.batch ? formatEfficiencyLines(e.batch, `batch ${e.batch.batch ?? opts.batch}`) : []),

package/bin/stats/local-source.mjs

@@ -58,7 +58,7 @@ export function summariseLog(events, fallbackIssue = null) {
   const usage = ev.filter((e) => e.event === "PHASE_ATTEMPT_USAGE");
   const builderCalls = usage.filter((e) => e.phase === "implement");
   const reviewCalls = usage.filter((e) => e.phase === "review").length;
-  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null, ab: (term?.context_ab ?? cp?.context_ab) === true };
+  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null, ab: (term?.context_ab ?? cp?.context_ab) === true, light: term?.light === true };
   const startTs = start.ts ?? null;
   const endTs = finished ? ev[t].ts ?? null : null;
   const a = Date.parse(startTs ?? ""); const b = Date.parse(endTs ?? "");

package/bin/stats/pool.mjs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4549: pool utilisation for `forgedock stats --pool`: remote lane minutes, lanes and share per pool agent, from the
+ * repo's local batch report.json rows (`sandbox.by_agent`, written by the orchestrator). No network, no model.
+ * Live capacity stays in `forgedock pool status`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listBatches } from "../lean/batch.mjs";
+import { windowLabel } from "./efficiency.mjs";
+
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+const round1 = (x) => Math.round(x * 10) / 10;
+
+/** Per window: the repo's batches created in it; an issue in several batches counts once (latest row). */
+export function poolUtilisation({ batchRoot, repo = null, windows, now = Date.now() }) {
+  const batches = (existsSync(batchRoot) ? listBatches(batchRoot) : []).map((id) => {
+    const dir = join(batchRoot, id), plan = readJson(join(dir, "plan.json")) ?? {};
+    return { dir, plan, created: Date.parse(plan.created ?? "") };
+  }).filter((b) => Number.isFinite(b.created) && (!repo || b.plan.repo === repo)).sort((a, b) => a.created - b.created);
+  const out = {};
+  for (const w of windows) {
+    const inWin = batches.filter((b) => b.created <= now && now - b.created <= w);
+    const latest = new Map();
+    for (const b of inWin) for (const row of readJson(join(b.dir, "report.json"))?.rows ?? []) if (Number.isSafeInteger(row?.issue)) latest.set(row.issue, row);
+    const agents = {};
+    let remoteLanes = 0, minutes = 0;
+    for (const row of latest.values()) {
+      if (!row.sandbox) continue;
+      remoteLanes++; minutes += Number(row.sandbox.minutes) || 0;
+      for (const [a, m] of Object.entries(row.sandbox.by_agent ?? {})) {
+        const e = (agents[a] ??= { minutes: 0, lanes: 0 });
+        e.minutes += Number(m) || 0; e.lanes++;
+      }
+    }
+    const attributed = Object.values(agents).reduce((s, e) => s + e.minutes, 0);
+    for (const e of Object.values(agents)) { e.share = attributed > 0 ? Math.round((e.minutes / attributed) * 1000) / 1000 : null; e.minutes = round1(e.minutes); }
+    out[windowLabel(w)] = { batches: inWin.length, remote_lanes: remoteLanes, minutes: round1(minutes), agents };
+  }
+  return out;
+}
+
+export function formatPoolLines(windows) {
+  return Object.entries(windows).flatMap(([w, m]) => {
+    const head = `pool ${w}: ${m.batches} batch${m.batches === 1 ? "" : "es"}, ${m.remote_lanes} remote lane${m.remote_lanes === 1 ? "" : "s"}, ${m.minutes.toFixed(1)} min`;
+    const rows = Object.entries(m.agents).sort((a, b) => b[1].minutes - a[1].minutes || a[0].localeCompare(b[0]))
+      .map(([a, e]) => `  ${a}: ${e.minutes.toFixed(1)} min, ${e.lanes} lane${e.lanes === 1 ? "" : "s"}${e.share == null ? "" : `, ${Math.round(e.share * 100)}% of pool`}`);
+    return [head, ...(rows.length ? rows : ["  per-agent minutes: n/a"])];
+  });
+}

package/bin/stats/pool.test.mjs

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { poolUtilisation, formatPoolLines } from "./pool.mjs";
+import { parseArgs } from "./index.mjs";
+
+const NOW = Date.parse("2026-10-24T00:00:00Z"), DAY = 86400000;
+function batch(root, id, created, rows, repo = "o/r") {
+  const d = join(root, id); mkdirSync(d, { recursive: true });
+  writeFileSync(join(d, "plan.json"), JSON.stringify({ repo, created: new Date(created).toISOString() }));
+  writeFileSync(join(d, "report.json"), JSON.stringify({ rows }));
+}
+const sbx = (issue, by) => ({ issue, outcome: "merged", sandbox: { minutes: Object.values(by).reduce((a, b) => a + b, 0), by_agent: by } });
+
+test("poolUtilisation sums minutes, lanes and share per agent per window", () => {
+  const root = tmpDir("pool-stats-");
+  batch(root, "b1", NOW - 2 * DAY, [sbx(1, { legion: 30 }), sbx(2, { legion: 10, box2: 10 }), { issue: 3, outcome: "merged" }]);
+  batch(root, "b2", NOW - 20 * DAY, [sbx(4, { box2: 50 })]);
+  batch(root, "b3", NOW - DAY, [sbx(9, { other: 99 })], "x/y");
+  const w = poolUtilisation({ batchRoot: root, repo: "o/r", windows: [7 * DAY, 30 * DAY], now: NOW });
+  assert.equal(w["7d"].remote_lanes, 2);
+  assert.deepEqual(w["7d"].agents.legion, { minutes: 40, lanes: 2, share: 0.8 });
+  assert.equal(w["30d"].agents.box2.minutes, 60);
+  assert.equal(w["30d"].agents.other, undefined);
+  assert.match(formatPoolLines(w).join("\n"), /legion: 40\.0 min, 2 lanes, 80% of pool/);
+});
+
+test("poolUtilisation with no agent data prints n/a; --window works with --pool", () => {
+  const root = tmpDir("pool-stats-");
+  batch(root, "b1", NOW - DAY, [{ issue: 1, outcome: "merged", sandbox: { minutes: 3 } }]);
+  const w = poolUtilisation({ batchRoot: root, repo: "o/r", windows: [7 * DAY], now: NOW });
+  assert.match(formatPoolLines(w).join("\n"), /per-agent minutes: n\/a/);
+  assert.equal(poolUtilisation({ batchRoot: join(root, "none"), windows: [DAY], now: NOW })["1d"].batches, 0);
+  assert.equal(parseArgs(["--pool", "--window", "7d"]).pool, true);
+});

package/bin/stats/query.mjs

@@ -74,7 +74,7 @@ export function verdictMix(records, items = [], milestone = null) {
 /**
  * forge#4275: the context-pack A/B over local run summaries (local-source.mjs summariseLog), per lane type (rerun,
  * child, first) and mode (on, off, shadow), never one blended average. First-pass yield: merged with one plan + one
- * implement builder call and at most one review. Runs without a recorded lane type (older logs) are left out.
+ * implement builder call and at most one review. Runs without a recorded lane type (older logs) and light lanes (#4502: they skip the pack) are left out.
  */
 export const CONTEXT_LANE_TYPES = Object.freeze(["rerun", "child", "first"]);
 export function contextPackAb(runs) {
@@ -83,7 +83,7 @@ export function contextPackAb(runs) {
   for (const lt of CONTEXT_LANE_TYPES) {
     out[lt] = {};
     for (const mode of ["on", "off", "shadow"]) {
-      const rs = runs.filter((r) => r?.finished && r.contextPack?.laneType === lt && r.contextPack?.mode === mode);
+      const rs = runs.filter((r) => r?.finished && !r.contextPack?.light && r.contextPack?.laneType === lt && r.contextPack?.mode === mode);
       out[lt][mode] = { n: rs.length, first_pass_yield: mean(rs.map((r) => (r.firstPass ? 1 : 0))), builder_turns: mean(rs.map((r) => r.builderTurns ?? 0)),
         cache_tokens: mean(rs.map((r) => r.cacheTokens ?? 0)), cost_usd: mean(rs.map((r) => r.costUsd ?? 0)), ...perMerge(rs, lt) };
     }