forgedock 1.36.0 → 1.37.0

package/bin/lean/train.test.mjs

@@ -0,0 +1,113 @@
+// 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 { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { openTrain, createTrain, insertMilestone, resolveCaps, runTrain, stopOf, trainCli, STOP_REASONS } from "./train.mjs";
+
+const live = { issues: [
+  { number: 1, milestone: "m1", state: "OPEN", body: "" },
+  { number: 2, milestone: "m2", state: "OPEN", body: "Depends on #1" },
+  { number: 3, milestone: "m3", state: "OPEN", body: "" },
+] };
+const tmp = () => tmpDir("train-");
+const okRun = (calls) => async (slug, o) => { calls.push([slug, o]); return { ok: true, batch: `b-${slug}`, rows: [] }; };
+const life = async (titles) => titles.map((title) => ({ title, state: "shipped:staging" }));
+
+test("createTrain keeps order, refuses a dependency on a later milestone", () => {
+  const s = createTrain({ slugs: ["m1", "m2"], live });
+  assert.deepEqual(s.order, ["m1", "m2"]);
+  assert.equal(s.milestones.m1.status, "pending");
+  assert.throws(() => createTrain({ slugs: ["m2", "m1"], live }), /train order invalid/);
+});
+
+test("insertMilestone re-validates and leaves the state unchanged on refusal", () => {
+  const s = createTrain({ slugs: ["m1", "m2"], live });
+  const n = insertMilestone(s, "m3", { after: "m1", live });
+  assert.deepEqual(n.order, ["m1", "m3", "m2"]);
+  assert.deepEqual(s.order, ["m1", "m2"]);
+  assert.throws(() => insertMilestone(s, "m1", { live }), /already in the train/);
+  const live2 = { issues: [...live.issues, { number: 4, milestone: "m4", state: "OPEN", body: "Depends on #2" }, { number: 5, milestone: "m2", state: "OPEN", body: "Depends on #4" }] };
+  assert.throws(() => insertMilestone(s, "m4", { live: live2 }), /train order invalid/);
+});
+
+test("runTrain runs in order, persists lifecycle, and resumes from the state file", async () => {
+  const root = tmp(), train = openTrain(root, "t1"), calls = [];
+  const r = await runTrain({ train, state: createTrain({ slugs: ["m1", "m2"], live }), runMilestone: okRun(calls), onBatchEnd: life, readLive: async () => live, caps: resolveCaps({}) });
+  assert.equal(r.ok, true);
+  assert.deepEqual(calls.map((c) => c[0]), ["m1", "m2"]);
+  const saved = train.load();
+  assert.equal(saved.milestones.m2.status, "done");
+  assert.equal(saved.milestones.m2.lifecycle, "shipped:staging");
+  assert.equal(saved.milestones.m1.batch, "b-m1");
+});
+
+test("a failed milestone ends in a typed STOP and --resume continues through its batch", async () => {
+  const root = tmp(), train = openTrain(root, "t2"), calls = [];
+  let fail = true;
+  const run = async (slug, o) => { calls.push([slug, o.resume]); return fail && slug === "m1" ? { ok: false, batch: "b1", rows: [{ issue: 1, outcome: "needs-human" }] } : { ok: true, rows: [] }; };
+  const args = { train, runMilestone: run, onBatchEnd: life, readLive: async () => live, caps: resolveCaps({}) };
+  const a = await runTrain({ ...args, state: createTrain({ slugs: ["m1", "m2"], live }) });
+  assert.equal(a.ok, false);
+  assert.equal(a.state.stop.reason, "needs-human");
+  assert.ok(STOP_REASONS.includes(a.state.stop.reason));
+  assert.equal(a.state.milestones.m2.status, "pending");
+  fail = false;
+  const b = await runTrain({ ...args, state: train.load() });
+  assert.equal(b.ok, true);
+  assert.deepEqual(calls.slice(1), [["m1", "b1"], ["m2", null]]);
+});
+
+test("open issues left after a batch stop the train with milestone-open", async () => {
+  const r = await runTrain({ train: openTrain(tmp(), "t3"), state: createTrain({ slugs: ["m1"] }), runMilestone: okRun([]), onBatchEnd: async (t) => [{ title: t[0], state: "building" }], caps: resolveCaps({}) });
+  assert.equal(r.state.stop.reason, "milestone-open");
+});
+
+test("stopOf maps row outcomes to typed reasons", () => {
+  assert.equal(stopOf({ rows: [{ outcome: "dependency-open" }] }), "dependency-unmet");
+  assert.equal(stopOf({ rows: [{ outcome: "budget-exceeded" }] }), "budget");
+  assert.equal(stopOf({ rows: [] }), "error");
+});
+
+test("parallel milestones run together and split one cap", async () => {
+  const caps = resolveCaps({ globalParallel: 6, parallelMilestones: 2 });
+  assert.equal(caps.perMilestone, 3);
+  let live_ = 0, max = 0;
+  const run = async () => { live_++; max = Math.max(max, live_); await new Promise((r) => setTimeout(r, 10)); live_--; return { ok: true, rows: [] }; };
+  const r = await runTrain({ train: openTrain(tmp(), "t4"), state: createTrain({ slugs: ["m1", "m3"], parallelMilestones: 2 }), runMilestone: run, onBatchEnd: life, caps });
+  assert.equal(r.ok, true);
+  assert.equal(max, 2);
+});
+
+test("a conflicting --parallel override warns and is ignored; the cap source is global_parallel", () => {
+  const c = resolveCaps({ requested: 32, globalParallel: 12 });
+  assert.equal(c.cap, 12);
+  assert.match(c.warnings[0], /conflicts.*ignored/);
+  assert.equal(resolveCaps({ requested: 12, globalParallel: 12 }).warnings.length, 0);
+});
+
+test("trainCli: forge.yaml is byte-identical after a run and lanes get no branches.staging override", async () => {
+  const root = tmp(), cwd = tmp(), out = [], calls = [];
+  const yaml = "branches:\n  staging: staging\norchestration:\n  global_parallel: 4\n";
+  writeFileSync(join(cwd, "forge.yaml"), yaml);
+  const before = readFileSync(join(cwd, "forge.yaml"));
+  const r = await trainCli(["m1", "m2", "--parallel", "32"], { root, id: "t5", globalParallel: 4, readLive: async () => live, runMilestone: okRun(calls), onBatchEnd: life, print: (l) => out.push(l) });
+  assert.equal(r.ok, true);
+  assert.ok(out.some((l) => /conflicts with the lane cap 4/.test(l)));
+  assert.equal(calls[0][1].parallel, 4);
+  assert.deepEqual(readFileSync(join(cwd, "forge.yaml")), before);
+  assert.equal(openTrain(root, "t5").load().milestones.m2.status, "done");
+});
+
+test("trainCli --insert adds a milestone explicitly; --resume clears nothing it did not own", async () => {
+  const root = tmp(), out = [];
+  const deps = { root, id: "t6", readLive: async () => live, runMilestone: okRun([]), onBatchEnd: life, print: (l) => out.push(l) };
+  await trainCli(["m1"], deps);
+  const r = await trainCli(["--insert", "t6", "m3"], deps);
+  assert.deepEqual(r.state.order, ["m1", "m3"]);
+  const done = await trainCli(["--resume", "t6"], deps);
+  assert.equal(done.state.milestones.m3.status, "done");
+  await assert.rejects(() => trainCli(["--resume", "nope"], deps), /no train/);
+});

package/bin/pool/cli.mjs

@@ -42,12 +42,14 @@ export async function runPoolCli(argv, deps = {}) {
         if (r.status !== 0) throw new Error(`install-router.sh exited ${r.status}`);
         break;
       }
+      process.title = "forgedock-pool-router"; // distinctive name for OOM-killer avoid lists and ps (#4673)
       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": {
+      process.title = "forgedock-pool-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`);

package/bin/pool/health.mjs

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { spawnSync } from "node:child_process";
+
+const sh = (cmd, args) => { const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 }); return r.status === 0 ? r.stdout : null; };
+
+/** Last exit reason in journal lines, or null. Matches systemd's "Main process exited, code=killed, status=15/TERM" and oom-kill results. */
+export function lastExitReason(lines) {
+  let reason = null;
+  for (const l of lines) {
+    const m = /Main process exited, (code=\S+, status=\S+)/.exec(l) || /(Failed with result '(?:oom-kill|signal|exit-code)')/.exec(l);
+    if (m) reason = m[1];
+  }
+  return reason;
+}
+
+/**
+ * Did a systemd --user unit restart in the last hour? `run(cmd,args)` returns stdout or null (injected for tests).
+ * "skip" when the unit is absent or systemd is unavailable. Restarts come from the journal because NRestarts is only cumulative.
+ */
+export function restartCheck({ unit, run = sh } = {}) {
+  const show = run("systemctl", ["--user", "show", unit, "-p", "NRestarts", "-p", "LoadState"]);
+  if (!show || /LoadState=not-found/.test(show)) return { status: "skip" };
+  const total = Number(/NRestarts=(\d+)/.exec(show)?.[1] ?? 0);
+  const lines = (run("journalctl", ["--user", "-u", unit, "--since", "1 hour ago", "--no-pager", "-o", "cat"]) ?? "").split("\n");
+  const recent = lines.filter((l) => /Scheduled restart job/.test(l)).length;
+  if (recent === 0) return { status: "pass", detail: `no restarts in the last hour (NRestarts=${total})` };
+  const why = lastExitReason(lines);
+  return { status: "warn", detail: `${unit} restarted ${recent}x in the last hour (NRestarts=${total})${why ? `; last exit: ${why}` : ""}. Check for OOM kills (earlyoom/systemd-oomd) under memory pressure` };
+}

package/bin/review-context.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * review-context.mjs — detect and refresh a stale forge.yaml `review.context` / `review.tech_stack` (#4666).
+ *
+ * The checks are deterministic (no LLM): manifests, the decision log and the context text are compared directly.
+ * Only `proposeRefresh` may use the enrichment backend, and only when the caller passes one in.
+ *
+ *   node bin/review-context.mjs check --config <forge.yaml> [--root <dir>] [--repo owner/name] --json
+ *
+ * Exit 0 always for `check` (a failing check must never block a review); the JSON carries the result.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+
+export const DEFAULT_MAX_MERGED_PRS = 50;
+export const DECISION_LOG_CANDIDATES = ["docs/decisions.md", "DECISIONS.md", "docs/decision-log.md", "devdocs/project/decisions.md"];
+
+// label as written in tech_stack -> package name as written in a manifest
+const FRAMEWORKS = [
+  ["Next.js", "next"], ["React", "react"], ["Vue", "vue"], ["Nuxt", "nuxt"], ["Svelte", "svelte"], ["SvelteKit", "@sveltejs/kit"],
+  ["Angular", "@angular/core"], ["Remix", "@remix-run/react"], ["Astro", "astro"], ["Express", "express"], ["Fastify", "fastify"],
+  ["NestJS", "@nestjs/core"], ["Tailwind", "tailwindcss"], ["Prisma", "prisma"], ["Drizzle", "drizzle-orm"],
+  ["FastAPI", "fastapi"], ["Django", "django"], ["Flask", "flask"], ["SQLAlchemy", "sqlalchemy"],
+  ["Rails", "rails"], ["Laravel", "laravel/framework"], ["Gin", "gin-gonic/gin"], ["Axum", "axum"], ["Actix", "actix-web"],
+];
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".venv", "venv", "vendor", "target", "__pycache__", ".claude", ".forge-lean"]);
+const MANIFEST_RE = /^(package\.json|pyproject\.toml|requirements[\w.-]*\.txt|go\.mod|Cargo\.toml|Gemfile|composer\.json)$/;
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+const wordRe = (w, flags = "i") => new RegExp(`(^|[^A-Za-z0-9_.-])${esc(w)}($|[^A-Za-z0-9_.-])`, flags);
+
+// ── forge.yaml review block (no YAML parser in this repo: a tolerant line scanner) ──────────────────────────────
+
+function reviewRange(lines) {
+  const start = lines.findIndex((l) => /^review:\s*(#.*)?$/.test(l));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) if (/^\S/.test(lines[i]) && !lines[i].startsWith("#")) { end = i; break; }
+  return { start, end };
+}
+
+function scalar(raw) {
+  const v = raw.trim();
+  if (v.startsWith('"')) { try { return JSON.parse(v.replace(/\s+#.*$/, "")); } catch { return v.slice(1, -1); } }
+  if (v.startsWith("'")) return v.slice(1, v.lastIndexOf("'")).replace(/''/g, "'");
+  return v.replace(/\s+#.*$/, "");
+}
+
+/** Reads the scalar keys of the top-level `review:` block (block scalars `|`/`>` included). Missing -> "". */
+export function readReviewFields(yamlText) {
+  const lines = yamlText.split(/\r?\n/);
+  const r = reviewRange(lines);
+  const out = {};
+  if (!r) return out;
+  for (let i = r.start + 1; i < r.end; i++) {
+    const m = /^  ([A-Za-z_]+):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, key, rest] = m;
+    if (/^[|>][+-]?\s*(#.*)?$/.test(rest)) {
+      const body = [];
+      let j = i + 1;
+      while (j < r.end && (/^\s*$/.test(lines[j]) || /^ {3,}/.test(lines[j]))) body.push(lines[j++].replace(/^ {4}/, "").replace(/^ +$/, ""));
+      out[key] = body.join("\n").replace(/\n+$/, "");
+      i = j - 1;
+    } else if (rest.trim() !== "") out[key] = scalar(rest);
+  }
+  return out;
+}
+
+/** Returns yamlText with the given review keys replaced (or added). Every other line is left untouched. */
+export function writeReviewFields(yamlText, fields) {
+  const lines = yamlText.split("\n");
+  let r = reviewRange(lines);
+  if (!r) {
+    if (lines[lines.length - 1] !== "") lines.push("");
+    lines.push("review:");
+    r = { start: lines.length - 1, end: lines.length };
+  }
+  const keys = Object.keys(fields);
+  const kept = [];
+  for (let i = r.start + 1; i < r.end; i++) {
+    const m = /^  ([A-Za-z_]+):/.exec(lines[i]);
+    if (m && keys.includes(m[1])) {
+      while (i + 1 < r.end && (/^ {3,}/.test(lines[i + 1]) || (/^\s*$/.test(lines[i + 1]) && /^ {3,}/.test(lines[i + 2] || "")))) i++;
+      continue;
+    }
+    kept.push(lines[i]);
+  }
+  const added = [];
+  for (const k of keys) {
+    const v = String(fields[k]);
+    if (v.includes("\n")) added.push(`  ${k}: |`, ...v.replace(/\n+$/, "").split("\n").map((l) => (l ? `    ${l}` : "")));
+    else added.push(`  ${k}: ${JSON.stringify(v)}`);
+  }
+  return [...lines.slice(0, r.start + 1), ...added, ...kept, ...lines.slice(r.end)].join("\n");
+}
+
+// ── facts: manifests and the decision log ────────────────────────────────────────────────────────────────────────
+
+/** Dependency names and raw manifest text under `root` (depth <= 3, skipping vendored dirs). */
+export function collectManifestFacts(root) {
+  const files = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      if (files.length >= 200) return;
+      const p = join(dir, name);
+      let st;
+      try { st = statSync(p); } catch { continue; }
+      if (st.isDirectory()) { if (depth < 3 && !SKIP_DIRS.has(name)) walk(p, depth + 1); }
+      else if (MANIFEST_RE.test(name) && st.size < 2_000_000) files.push(p);
+    }
+  };
+  walk(root, 0);
+  const parts = [];
+  let hasSourceManifest = false;
+  for (const f of files) {
+    let text;
+    try { text = readFileSync(f, "utf8"); } catch { continue; }
+    if (f.endsWith("package.json")) {
+      try {
+        const j = JSON.parse(text);
+        const deps = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].flatMap((k) => Object.keys(j[k] || {}));
+        if (deps.length) hasSourceManifest = true;
+        parts.push(deps.join("\n"));
+      } catch { /* unparsable manifest: ignore */ }
+    } else {
+      hasSourceManifest = true;
+      parts.push(text);
+    }
+  }
+  return { files, hasSourceManifest, haystack: parts.join("\n").toLowerCase() };
+}
+
+export function findDecisionLog(root, configured) {
+  for (const rel of [configured, ...DECISION_LOG_CANDIDATES].filter(Boolean)) {
+    const p = resolve(root, rel);
+    if (existsSync(p)) { try { return readFileSync(p, "utf8"); } catch { /* next */ } }
+  }
+  return "";
+}
+
+const ID_RE = /\b(?:[A-Z]{1,5}-?\d{1,4})\b/g;
+
+/** IDs the decision log marks superseded: "D-12 ... superseded", "Status: superseded" under a "## D-12" heading, "D-15 supersedes D-12". */
+export function supersededDecisionIds(logText) {
+  const out = new Set();
+  let lastId = [];
+  for (const line of logText.split(/\r?\n/)) {
+    const m = /supersed\w*/i.exec(line);
+    if (!m) {
+      const ids = line.match(ID_RE);
+      if (ids) lastId = ids;
+      continue;
+    }
+    if (/^supersedes$/i.test(m[0])) (line.slice(m.index).match(ID_RE) || []).forEach((i) => out.add(i));
+    else {
+      const before = line.slice(0, m.index).match(ID_RE) || [];
+      (before.length ? before : lastId).forEach((i) => out.add(i));
+    }
+  }
+  return out;
+}
+
+// ── detection ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Reasons the context is stale: [{code, detail}]. Empty = fresh (or nothing to compare against). */
+export function detectStale({ techStack = "", context = "", manifests, decisionLogText = "" }) {
+  const reasons = [];
+  if (manifests?.hasSourceManifest) {
+    const absent = FRAMEWORKS.filter(([label, pkg]) => wordRe(label).test(techStack) && !wordRe(pkg).test(manifests.haystack)).map(([l]) => l);
+    if (absent.length) reasons.push({ code: "tech_stack_absent", detail: `tech_stack names ${absent.join(", ")} but no manifest lists it` });
+    if (/docs[- ]only|\bno (?:product |source |application )?code\b/i.test(context)) {
+      reasons.push({ code: "docs_only_phrasing", detail: "context says the repo is docs-only / has no code, but source manifests exist" });
+    }
+  }
+  if (decisionLogText && context) {
+    const cited = [...supersededDecisionIds(decisionLogText)].filter((id) => wordRe(id, "").test(context));
+    if (cited.length) reasons.push({ code: "superseded_decision", detail: `context cites superseded decision(s) ${cited.join(", ")}` });
+  }
+  return reasons;
+}
+
+/** Advisory once more than `maxMergedPrs` PRs merged since the context was generated. Unknown count = not advisory. */
+export function contextAge({ generatedAt = "", mergedSince = null, maxMergedPrs = DEFAULT_MAX_MERGED_PRS }) {
+  const max = Number.isFinite(maxMergedPrs) && maxMergedPrs > 0 ? maxMergedPrs : DEFAULT_MAX_MERGED_PRS;
+  return { generatedAt, mergedSince, maxMergedPrs: max, advisory: Boolean(generatedAt) && mergedSince != null && mergedSince > max };
+}
+
+/** Merged PR count since `generatedAt` via gh; null when it cannot be determined. */
+export function countMergedSince(repo, generatedAt, run = execFileSync) {
+  if (!repo || !/^\d{4}-\d{2}-\d{2}/.test(generatedAt)) return null;
+  try {
+    const out = run("gh", ["pr", "list", "-R", repo, "--state", "merged", "--search", `merged:>=${generatedAt.slice(0, 10)}`, "--json", "number", "--limit", "200"], { encoding: "utf8", timeout: 20000, stdio: ["ignore", "pipe", "ignore"] });
+    const n = JSON.parse(out);
+    return Array.isArray(n) ? n.length : null;
+  } catch { return null; }
+}
+
+/** Full check of one forge.yaml. `mergedCount` is injectable for tests. */
+export function checkContext({ configPath, root, repo, mergedCount = countMergedSince }) {
+  let text = "";
+  try { text = readFileSync(configPath, "utf8"); } catch { return { stale: false, reasons: [], generated_at: "", merged_since: null, advisory: false, max_merged_prs: DEFAULT_MAX_MERGED_PRS }; }
+  const f = readReviewFields(text);
+  const manifests = collectManifestFacts(root);
+  const reasons = detectStale({ techStack: f.tech_stack || "", context: f.context || "", manifests, decisionLogText: findDecisionLog(root, f.decision_log) });
+  const generatedAt = f.context_generated_at || "";
+  const age = contextAge({ generatedAt, mergedSince: generatedAt ? mergedCount(repo, generatedAt) : null, maxMergedPrs: parseInt(f.context_max_merged_prs, 10) });
+  return { stale: reasons.length > 0, reasons, generated_at: generatedAt, merged_since: age.mergedSince, advisory: age.advisory, max_merged_prs: age.maxMergedPrs };
+}
+
+// ── refresh ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Tech stack from the frameworks the manifests actually list. */
+export function techStackFromManifests(manifests) {
+  return FRAMEWORKS.filter(([, pkg]) => wordRe(pkg).test(manifests.haystack)).map(([l]) => l).join(", ");
+}
+
+/** Drops the sentences that made the context stale (docs-only phrasing, superseded decision IDs). */
+export function pruneContext(context, { hasSourceManifest, superseded }) {
+  const stale = (s) => (hasSourceManifest && /docs[- ]only|\bno (?:product |source |application )?code\b/i.test(s)) || [...superseded].some((id) => wordRe(id, "").test(s));
+  return context.split("\n").map((line) => line.split(/(?<=[.!?])\s+/).filter((s) => !stale(s)).join(" ")).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/**
+ * Proposes new review fields from the current manifests and decision log, deterministically: tech_stack is rebuilt from
+ * the manifests, stale sentences are pruned from the context. `enrichFn({tech_stack, context, decisionLog, manifestFiles})`
+ * (optional, async) may rewrite them further.
+ */
+export async function proposeRefresh({ yamlText, root, now = new Date(), enrichFn, mergedTotal }) {
+  const cur = readReviewFields(yamlText);
+  const manifests = collectManifestFacts(root);
+  const log = findDecisionLog(root, cur.decision_log);
+  const names = manifests.files.map((p) => p.slice(root.length + 1));
+  const stack = techStackFromManifests(manifests) || cur.tech_stack || "";
+  const fields = {
+    tech_stack: stack,
+    context: pruneContext(cur.context || "", { hasSourceManifest: manifests.hasSourceManifest, superseded: supersededDecisionIds(log) }),
+  };
+  if (!fields.context && names.length) fields.context = `Source manifests: ${names.join(", ")}.`;
+  if (enrichFn) {
+    const e = await enrichFn({ ...fields, decisionLog: log, manifestFiles: names });
+    if (e && typeof e === "object") { if (e.tech_stack) fields.tech_stack = e.tech_stack; if (e.context) fields.context = e.context; }
+  }
+  fields.context_generated_at = now.toISOString().slice(0, 10);
+  if (mergedTotal != null) fields.context_generated_pr_count = String(mergedTotal);
+  const next = writeReviewFields(yamlText, fields);
+  return { next, diff: simpleDiff(yamlText, next), changed: next !== yamlText };
+}
+
+/**
+ * `forgedock init --refresh-context`: show the diff, write only on approval. `deps` = {confirm, backup, write, interactive}.
+ * Returns the exit code (0 written or nothing to do, 1 declined / non-interactive / no forge.yaml).
+ */
+export async function refreshContextFlow({ cwd, out, deps, enrichFn, mergedTotal }) {
+  const path = join(cwd, "forge.yaml");
+  if (!existsSync(path)) { out.write("\n  No forge.yaml here — run: npx forgedock init\n"); return 1; }
+  const { next, diff, changed } = await proposeRefresh({ yamlText: readFileSync(path, "utf8"), root: cwd, enrichFn, mergedTotal });
+  out.write(`\n  review.context / review.tech_stack refresh (from manifests + decision log):\n\n${diff.split("\n").map((l) => `    ${l}`).join("\n")}\n\n`);
+  if (!changed) { out.write("  Nothing to change.\n"); return 0; }
+  if (!deps.interactive) { out.write("  Non-interactive run — forge.yaml left untouched. Re-run in a terminal to approve.\n"); return 1; }
+  if (!(await deps.confirm("Apply this change to forge.yaml? A backup will be created.", false))) { out.write("  Refresh cancelled — forge.yaml left untouched.\n"); return 1; }
+  const backup = deps.backup(path);
+  if (backup) out.write(`  Backed up: forge.yaml → ${backup.backupName}\n`);
+  deps.write(path, next);
+  out.write("  forge.yaml updated.\n");
+  return 0;
+}
+
+/** Minimal line diff (removed `-`, added `+`) over the lines that differ; enough for an approval prompt. */
+export function simpleDiff(a, b) {
+  const x = a.split("\n"), y = b.split("\n");
+  let s = 0;
+  while (s < x.length && s < y.length && x[s] === y[s]) s++;
+  let e = 0;
+  while (e < x.length - s && e < y.length - s && x[x.length - 1 - e] === y[y.length - 1 - e]) e++;
+  return [...x.slice(s, x.length - e).map((l) => `- ${l}`), ...y.slice(s, y.length - e).map((l) => `+ ${l}`)].join("\n");
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opt = (n) => { const i = rest.indexOf(n); return i === -1 ? "" : rest[i + 1] || ""; };
+  if (cmd !== "check" || !opt("--config")) {
+    process.stderr.write("usage: review-context.mjs check --config <forge.yaml> [--root <dir>] [--repo owner/name] --json\n");
+    process.exit(2);
+  }
+  const configPath = resolve(opt("--config"));
+  const res = checkContext({ configPath, root: resolve(opt("--root") || dirname(configPath)), repo: opt("--repo") });
+  process.stdout.write(JSON.stringify(res) + "\n");
+}

package/bin/runner.mjs

@@ -2001,6 +2001,17 @@ export function listDescendants(pid, { psFn = null, maxCmd = 200 } = {}) {
 /** #4410: cap of the tool uses one stream session records. */
 const TOOL_USES_MAX = 5000;
 
+/**
+ * #4690: limit events of the systemd scope the process `pid` runs in: `tasks` (pids.events `max`: forks refused at TasksMax)
+ * and `memory` (memory.events `oom_kill`). null when its cgroup or the counters are unreadable (no cgroup v2, no scope).
+ */
+export function readScopeLimitEvents(pid, { procRoot = "/proc", cgroupRoot = "/sys/fs/cgroup" } = {}) {
+  const line = readFileSync(join(procRoot, String(pid), "cgroup"), "utf8").split("\n").find((l) => l.startsWith("0::"));
+  const path = line?.slice(3).trim();
+  if (!path || !path.endsWith(".scope")) return null;
+  const count = (file, key) => { try { return Number((readFileSync(join(cgroupRoot, path, file), "utf8").match(new RegExp(`^${key} (\\d+)`, "m")) ?? [])[1]) || 0; } catch { return 0; } };
+  return { tasks: count("pids.events", "max"), memory: count("memory.events", "oom_kill") };
+}
 /**
  * Async twin of runCliBackend (core work-on live comments): the CLI runs under child_process.spawn so the caller's event
  * loop keeps turning while the session runs. It returns the SAME envelope (and throws the same errors) because the
@@ -2024,7 +2035,7 @@ const TOOL_USES_MAX = 5000;
  * (deduped by tool_use id, capped at TOOL_USES_MAX), for bin/lean/toolstats.mjs; absent on the non-stream path.
  */
 export async function runCliBackendAsync(opts) {
-  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null, ...rest } = opts;
+  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null, limitProbe = readScopeLimitEvents, ...rest } = opts;
   let captured = null;
   try {
     runCliBackend({ ...rest, spawnFn: (bin, args, o) => {
@@ -2047,7 +2058,9 @@ export async function runCliBackendAsync(opts) {
     const j = args.indexOf("--output-format");
     if (j >= 0) { args[j + 1] = "stream-json"; if (!args.includes("--verbose")) args.splice(j + 2, 0, "--verbose"); }
   }
-  if (typeof wrap === "function") ({ bin, args } = wrap(bin, args));
+  let scopeUnit = null; // #4690: set when `wrap` put the child in a limited systemd scope
+  if (typeof wrap === "function") { const w = wrap(bin, args); ({ bin, args } = w); scopeUnit = w.unit ?? null; }
+  let limitInfo = null;
   const ceiling = maxMs > 0 ? maxMs : o.timeout;
   let collected, idleInfo = null, ctxInfo = null, turnInfo = null;
   const msgUsage = new Map(); // #4390: assistant message id -> its usage (a message spans several stream lines)
@@ -2099,7 +2112,12 @@ export async function runCliBackendAsync(opts) {
           }
         }
         // #4405: a separate check, so the absolute ceiling still applies while the idle kill is extended (busy) or settling.
-        if (!timedOut && !idleInfo && !ctxInfo && !turnInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
+        // #4690: the scope's pids/memory events say the lane hit its own limit (the scope cgroup is gone once the child exits, so sample live)
+        if (scopeUnit && !limitInfo && !timedOut && !idleInfo && !ctxInfo && !turnInfo) {
+          let ev = null; try { ev = limitProbe(child.pid); } catch { ev = null; }
+          if (ev && (ev.tasks > 0 || ev.memory > 0)) { limitInfo = { limit: ev.tasks > 0 ? "tasks" : "memory", unit: scopeUnit, events: ev }; kill(); }
+        }
+        if (!timedOut && !idleInfo && !ctxInfo && !turnInfo && !limitInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
       }, tick);
       timer.unref?.();
       const noteLine = (line) => {
@@ -2143,6 +2161,11 @@ export async function runCliBackendAsync(opts) {
   } finally { if (sysDir) rmSync(sysDir, { recursive: true, force: true }); }
   const sum = (k) => [...msgUsage.values()].reduce((a, u) => a + toFiniteUsageNumber(u[k]), 0);
   const streamUsage = () => (msgUsage.size ? { input_tokens: sum("input_tokens"), output_tokens: sum("output_tokens"), cache_creation_input_tokens: sum("cache_creation_input_tokens"), cache_read_input_tokens: sum("cache_read_input_tokens") } : null);
+  if (limitInfo) {
+    const err = new Error(`claude CLI lane hit its scope ${limitInfo.limit} limit (${limitInfo.unit}) and was stopped`);
+    err.code = "CLI_LANE_LIMIT"; err.limit = limitInfo.limit; err.unit = limitInfo.unit; err.events = limitInfo.events; err.toolUses = [...toolUses.values()];
+    throw err;
+  }
   if (turnInfo) {
     const err = new Error(`claude CLI session reached its turn budget (${turnMax} turns) and was stopped`);
     err.code = "CLI_TURNS"; err.turns = msgUsage.size; err.turnMax = turnMax; err.lastTool = turnInfo.lastTool; err.usage = streamUsage(); err.toolUses = [...toolUses.values()];