forgedock 1.32.0 → 1.33.0

package/bin/pool/cli.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { startAgent } from "./agent.mjs";
+import { startRouter } from "./router.mjs";
+import { dockerCli } from "./docker.mjs";
+import { readSecret } from "./store.mjs";
+import { call as httpCall } from "./http.mjs";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const loadJson = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+/** The `forgedock pool` verbs (and the `computeshare` script). Throws on usage or router errors; `deps` injects the HTTP client and config. */
+export async function runPoolCli(argv, deps = {}) {
+  const [cmd, ...rest] = argv;
+  const call = deps.call ?? httpCall;
+  const flag = (name, dflt) => { const i = rest.indexOf(`--${name}`); return i >= 0 ? rest[i + 1] : dflt; };
+
+  function routerConfig() {
+    const path = flag("config", process.env.COMPUTESHARE_CONFIG ?? join(homedir(), ".config/computeshare/router.json"));
+    const c = loadJson(path);
+    const base = dirname(path);
+    return { ...c, repo_root: c.repo_root ?? repoRoot, state_dir: c.state_dir ?? join(base, "state"), forgedock_token: readSecret(c.forgedock_token_file ?? join(base, "forgedock.token")), enroll_token: readSecret(c.enroll_token_file ?? join(base, "enroll.token")) };
+  }
+
+  function agentConfig() {
+    const path = flag("config", process.env.COMPUTESHARE_CONFIG ?? "/etc/computeshare/agent.json");
+    const c = loadJson(path);
+    return { ...c, config_path: path, token: readSecret(c.token_file ?? join(dirname(path), "agent.token")) };
+  }
+
+  switch (cmd) {
+    case "router": {
+      if (rest[0] === "install") {
+        // The systemd --user unit (Restart=always), same as install-router.sh; the foreground form is its ExecStart.
+        const r = (deps.spawn ?? spawnSync)("bash", [join(repoRoot, "pool", "install", "install-router.sh")], { stdio: "inherit" });
+        if (r.status !== 0) throw new Error(`install-router.sh exited ${r.status}`);
+        break;
+      }
+      const cfg = routerConfig();
+      (deps.startRouter ?? startRouter)(cfg);
+      console.log(`computeshare router on ${cfg.listen.host}:${cfg.listen.port} (public ${cfg.public_url})`);
+      break;
+    }
+    case "agent": {
+      const cfg = agentConfig();
+      startAgent(cfg, { docker: dockerCli });
+      console.log(`computeshare agent ${cfg.name} on ${cfg.listen.host}:${cfg.listen.port}: ${cfg.allow_cpus} cpus, ${cfg.allow_mem_gb} GB reserved for lanes`);
+      break;
+    }
+    case "status": {
+      const cfg = routerConfig();
+      const r = await call(`http://${cfg.listen.host}:${cfg.listen.port}`, "GET", "/agents", { token: cfg.forgedock_token });
+      console.log(JSON.stringify(r.data, null, 2));
+      break;
+    }
+    case "enroll":
+    case "install-command": {
+      // Prints a command carrying a one-time code (single use, expires in 30 min), never the long-lived enroll token.
+      const cfg = routerConfig();
+      const r = await call(`http://${cfg.listen.host}:${cfg.listen.port}`, "POST", "/codes", { token: cfg.forgedock_token });
+      if (!r.ok) throw new Error(`router refused: HTTP ${r.status}`);
+      const size = `${flag("cpus") ? `&cpus=${Number(flag("cpus"))}` : ""}${flag("mem") ? `&mem=${Number(flag("mem"))}` : ""}`;
+      console.log(`powershell -NoProfile -ExecutionPolicy Bypass -Command "irm '${cfg.public_url}/bootstrap/install.ps1?token=${r.data.code}${size}' | iex"`);
+      console.error(`(one-time code, expires ${r.data.expires_at})`);
+      break;
+    }
+    case "resize": {
+      // computeshare resize <agent> --cpus N --mem GB [--vm-cpus N --vm-mem GB]: change a host's lane allowance remotely.
+      const cfg = routerConfig();
+      const name = rest.find((x) => !x.startsWith("--") && !/^\d+$/.test(x));
+      const body = { cpus: Number(flag("cpus")), mem_gb: Number(flag("mem")), vm_cpus: Number(flag("vm-cpus", flag("cpus"))), vm_mem_gb: Number(flag("vm-mem", Number(flag("mem")) + 2)), drain: rest.includes("--drain"), ...(flag("vm-swap") ? { vm_swap_gb: Number(flag("vm-swap")) } : {}) };
+      const r = await call(`http://${cfg.listen.host}:${cfg.listen.port}`, "POST", `/agents/${encodeURIComponent(name)}/resize`, { body, token: cfg.forgedock_token, timeoutMs: 30000 });
+      console.log(`${name}: HTTP ${r.status} ${JSON.stringify(r.data)}`);
+      break;
+    }
+    case "upgrade": {
+      // Push the current code (and lane image, when its recipe changed) to one agent or all of them.
+      const cfg = routerConfig();
+      const base = `http://${cfg.listen.host}:${cfg.listen.port}`;
+      const only = rest.find((x) => !x.startsWith("--") && x !== flag("config"));
+      const list = (await call(base, "GET", "/agents", { token: cfg.forgedock_token })).data?.agents ?? [];
+      for (const a of list.filter((x) => !only || x.name === only)) {
+        const r = await call(base, "POST", `/agents/${encodeURIComponent(a.name)}/upgrade`, { token: cfg.forgedock_token, timeoutMs: 30000 });
+        console.log(`${a.name}: HTTP ${r.status} ${JSON.stringify(r.data)}`);
+      }
+      break;
+    }
+    case "remove": {
+      const name = rest.find((x) => !x.startsWith("--") && x !== flag("config"));
+      if (!name) throw new Error("usage: forgedock pool remove <agent>");
+      const cfg = routerConfig();
+      const r = await call(`http://${cfg.listen.host}:${cfg.listen.port}`, "DELETE", `/agents/${encodeURIComponent(name)}`, { token: cfg.forgedock_token, timeoutMs: 30000 });
+      if (!r.ok) throw new Error(`${name}: HTTP ${r.status} ${JSON.stringify(r.data)}`);
+      console.log(`${name}: removed`);
+      break;
+    }
+    default:
+      throw new Error("usage: forgedock pool router [install] | enroll [--cpus N --mem GB] | status | upgrade [agent] | remove <agent>  [--config path]");
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runPoolCli(process.argv.slice(2)).catch((err) => { console.error(err.message); process.exit(String(err.message).startsWith("usage:") ? 2 : 1); });
+}

package/bin/pool/docker.mjs

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { execFile } from "node:child_process";
+
+function docker(args, { timeoutMs = 120000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile("docker", args, { timeout: timeoutMs, maxBuffer: 16 << 20 }, (err, stdout, stderr) => {
+      if (err) { err.stderr = String(stderr ?? "").slice(0, 2000); reject(err); } else resolve(String(stdout).trim());
+    });
+  });
+}
+
+/** The docker CLI operations the agent needs; swapped for a fake in tests. */
+export const dockerCli = {
+  async run(args) { return docker(["run", "-d", ...args]); },
+  async inspect(name) {
+    try {
+      const out = await docker(["inspect", "--format", "{{json .State}}", name], { timeoutMs: 20000 });
+      const s = JSON.parse(out);
+      return { running: Boolean(s.Running), exitCode: s.ExitCode, startedAt: s.StartedAt, finishedAt: s.FinishedAt };
+    } catch (e) {
+      if (/No such (object|container)/i.test(e.stderr ?? "")) return null;
+      throw e;
+    }
+  },
+  async remove(name) { try { await docker(["rm", "-f", "-v", name], { timeoutMs: 60000 }); } catch (e) { if (!/No such container/i.test(e.stderr ?? "")) throw e; } },
+  async listLabelled(label) {
+    const out = await docker(["ps", "-a", "--filter", `label=${label}`, "--format", "{{.Names}}"], { timeoutMs: 20000 });
+    return out ? out.split("\n").filter(Boolean) : [];
+  },
+  async removeVolume(name) { try { await docker(["volume", "rm", "-f", name], { timeoutMs: 120000 }); } catch (e) { if (!/no such volume/i.test(e.stderr ?? "")) throw e; } },
+  async listVolumes(prefix) {
+    const out = await docker(["volume", "ls", "-q", "--filter", `name=${prefix}`], { timeoutMs: 20000 });
+    return out ? out.split("\n").filter((v) => v.startsWith(prefix)) : [];
+  },
+  async pull(image) { return docker(["pull", "-q", image], { timeoutMs: 30 * 60000 }); },
+  async load(file) { return docker(["load", "-q", "-i", file], { timeoutMs: 30 * 60000 }); },
+  async hasImage(ref) { try { await docker(["image", "inspect", ref], { timeoutMs: 20000 }); return true; } catch { return false; } },
+  /** {name: {cpu (cores), mem_gb}} for running containers with the label. */
+  async stats(label) {
+    const names = await this.listLabelled(label);
+    if (!names.length) return {};
+    const out = await docker(["stats", "--no-stream", "--format", "{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}", ...names], { timeoutMs: 60000 });
+    const unit = { b: 1 / 2 ** 30, kib: 1 / 2 ** 20, mib: 1 / 2 ** 10, gib: 1, kb: 1e3 / 2 ** 30, mb: 1e6 / 2 ** 30, gb: 1e9 / 2 ** 30 };
+    const res = {};
+    for (const line of out.split("\n").filter(Boolean)) {
+      const [name, cpu, mem] = line.split("\t");
+      const m = /([\d.]+)\s*([a-zA-Z]+)/.exec(mem ?? "");
+      res[name] = { cpu: (parseFloat(cpu) || 0) / 100, mem_gb: m ? parseFloat(m[1]) * (unit[m[2].toLowerCase()] ?? 0) : 0 };
+    }
+    return res;
+  },
+  async build(dir, tag, buildArgs = {}) { return docker(["build", "-q", "-t", tag, ...Object.entries(buildArgs).flatMap(([k, v]) => ["--build-arg", `${k}=${v}`]), dir], { timeoutMs: 45 * 60000 }); },
+  /** Removes files the root-owned lane container wrote into a bind mount, using the lane image itself. */
+  async wipe(dir, image) { await docker(["run", "--rm", "--network", "none", "-v", `${dir}:/d`, "--entrypoint", "sh", image, "-c", "rm -rf /d/* /d/.[!.]* 2>/dev/null; true"], { timeoutMs: 120000 }); },
+};

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]);