forgedock 1.35.0 → 1.37.0

package/bin/lean/heavy.mjs

@@ -14,12 +14,13 @@
  * host whose memory is used by something else. Fail-open: an unreadable registry or a lock timeout grants.
  *
  * Builder-run commands are gated by per-run PATH shims (`writeHeavyShims`) that call this file as a CLI:
- * `heavy.mjs run --name <n> -- <abs-real-bin> args...` (nested calls pass through via FORGE_HEAVY_HELD).
+ * `heavy.mjs run --name <n> -- <abs-real-bin> args...` (nested calls pass through via FORGE_HEAVY_HELD). A wrapper that
+ * re-resolves the name back to the shim is cut off by FORGE_HEAVY_CHAIN (`name:cmd|...`, see `runWrapped`, #4680).
  */
 import { spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, appendFileSync, writeFileSync, chmodSync } from "node:fs";
 import { cpus, freemem } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { writeAtomic } from "./batch.mjs";
 import { schedDir, pidAlive, DEFAULT_PRIORITY } from "./sched.mjs";
@@ -249,15 +250,34 @@ const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
 
 /** Shim script for one command: exec node heavy.mjs run --name <n> -- <real> "$@". */
 export function heavyShimScript(name, real, { node = process.execPath, script = fileURLToPath(import.meta.url) } = {}) {
-  return `${SHIM_HEADER}exec ${q(node)} ${q(script)} run --name ${q(name)} -- ${q(real)} "$@"\n`;
+  return `${SHIM_HEADER}export FORGE_HEAVY_SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"\nexec ${q(node)} ${q(script)} run --name ${q(name)} -- ${q(real)} "$@"\n`;
 }
 
+/** True when `text` is a shell-style script that looks `name` up on PATH itself (a pass-through wrapper, #4680). */
+export function isPassThroughWrapper(text, name) {
+  const t = String(text ?? "");
+  return t.startsWith("#!") && t.includes(name) && /\b(command\s+-v|which|type\s+-p)\b/.test(t);
+}
+const head = (p) => { try { return readFileSync(p, "utf8").slice(0, 4096); } catch { return ""; } };
+
 /**
  * Write 0755 shims into `binDir` for every HEAVY_BINS name found on `path` (binDir excluded, real path resolved now, so
- * a shim never calls itself). Returns the names written.
+ * a shim never calls itself). A target that is a pass-through wrapper is skipped for the next match past its dir, or the
+ * shim is skipped with a `warn` line when none is left (#4680). Returns the names written.
  */
-export async function writeHeavyShims(binDir, { path = process.env.PATH ?? "", find = which, node, script, mkdirp = (d) => mkdirSync(d, { recursive: true }), writeShim = (p, t) => { writeFileSync(p, t); chmodSync(p, 0o755); } } = {}) {
-  const found = HEAVY_BINS.map((n) => [n, find(n, path, [binDir])]).filter(([, r]) => r);
+export async function writeHeavyShims(binDir, { path = process.env.PATH ?? "", find = which, read = head, warn = (m) => process.stderr.write(`${m}\n`), node, script, mkdirp = (d) => mkdirSync(d, { recursive: true }), writeShim = (p, t) => { writeFileSync(p, t); chmodSync(p, 0o755); } } = {}) {
+  const found = [];
+  for (const n of HEAVY_BINS) {
+    const skip = [binDir];
+    let real = find(n, path, skip);
+    while (real && isPassThroughWrapper(read(real), n)) {
+      skip.push(dirname(real));
+      const next = find(n, path, skip);
+      if (!next) warn(`forgedock heavy: ${n} at ${real} is a PATH pass-through wrapper with no real binary behind it; shim skipped`);
+      real = next;
+    }
+    if (real) found.push([n, real]);
+  }
   if (!found.length) return [];
   await mkdirp(binDir);
   for (const [n, real] of found) await writeShim(join(binDir, n), heavyShimScript(n, real, { ...(node ? { node } : {}), ...(script ? { script } : {}) }));
@@ -277,17 +297,43 @@ export function sumWaits(text, waits = {}) {
   return { waits, queueMax };
 }
 
+export const SHIM_LOOP_MAX = 4;
+/**
+ * Re-entry guard (#4680): FORGE_HEAVY_CHAIN lists `name:cmd` per shim run. A repeat of the same name+cmd where cmd is a
+ * pass-through wrapper means it sent the call back to the shim; a repeat of a real binary is a legitimate nested call
+ * (`npm run` inside an npm script) and passes through unchanged, unrecorded. For a wrapper, resolve the next PATH match past the shim dir and every chain dir; none, or more
+ * than SHIM_LOOP_MAX entries, is a typed `env.shim_loop` error and nothing is spawned. Returns {cmd, env} or {error}.
+ */
+export function guardChain(name, cmd, env, read = head) {
+  const chain = String(env.FORGE_HEAVY_CHAIN ?? "").split("|").filter(Boolean);
+  const dirs = chain.map((e) => dirname(e.slice(e.indexOf(":") + 1)));
+  const loop = (why) => ({ error: `env.shim_loop: ${name} ${why} (PATH dirs: ${[env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean).join(", ") || "none"})` });
+  const repeat = chain.includes(`${name}:${cmd}`);
+  if (repeat && !isPassThroughWrapper(read(cmd), name)) return { cmd, env };
+  if (chain.length >= SHIM_LOOP_MAX) return loop(`re-entered the heavy shim more than ${SHIM_LOOP_MAX} times`);
+  if (repeat) {
+    const next = which(name, env.PATH ?? "", [env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean));
+    if (!next) return loop(`re-entered via ${cmd} and no other ${name} is on PATH`);
+    cmd = next;
+  }
+  return { cmd, env: { ...env, FORGE_HEAVY_CHAIN: [...chain, `${name}:${cmd}`].join("|") } };
+}
+
 /**
  * CLI body: `run --name <n> -- <real> args...`. Pass-through when FORGE_HEAVY_HELD is set or the step is llm; else
  * acquire, run with FORGE_HEAVY_HELD=1 and FORGE_HOST_PARALLELISM from live holders, release, propagate the exit.
  */
-export async function runWrapped(argv, { env = process.env, open = openHeavy, run = spawnInherit, host } = {}) {
+export async function runWrapped(argv, { env: env0 = process.env, open = openHeavy, run = spawnInherit, host } = {}) {
+  let env = env0;
   const sep = argv.indexOf("--");
   if (argv[0] !== "run" || sep < 0 || !argv[sep + 1]) throw new Error("usage: heavy.mjs run --name <name> -- <command> [args...]");
   const ni = argv.indexOf("--name");
   const name = ni >= 0 && ni < sep ? argv[ni + 1] : argv[sep + 1];
-  const [cmd, ...args] = argv.slice(sep + 1);
+  let [cmd, ...args] = argv.slice(sep + 1);
   const c = heavyConfig({}, env);
+  const g0 = guardChain(name, cmd, env);
+  if (g0.error) { process.stderr.write(`${g0.error}\n`); return { code: 126, signal: null }; }
+  cmd = g0.cmd; env = g0.env;
   if (env.FORGE_HEAVY_HELD || env.FORGE_HEAVY_DISABLED === "1" || classifyStep(name, args) === "llm") return run(cmd, args, env);
   const hostP = host ?? defaultHost();
   const h = open(env.FORGEDOCK_SCHED_DIR || schedDir(env), { env, host: hostP });

package/bin/lean/heavy.test.mjs

@@ -2,10 +2,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import { writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
+import { guardChain, isPassThroughWrapper, SHIM_LOOP_MAX, classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
 import { checkAdmission, ADMISSION_DEFAULTS } from "./admission.mjs";
 import { formatAlertLines, formatWaitSummary } from "./orchestrate.mjs";
 import { readHeavy } from "../engine-cli.mjs";
@@ -235,3 +236,75 @@ describe("heavy shims and the run wrapper (#4169)", () => {
       ["ALERTS", 'deferred-to-ci: 40% (4/10 lanes, threshold 30%), e.g. "npx tsc"']);
   });
 });
+
+describe("shim re-entry through a pass-through wrapper (#4680)", () => {
+  it("shim with pass-through wrapper runs once", async () => {
+    const d = tmpDir("heavy-wrap-"), wrap = join(d, "wrap"), real = join(d, "real"), bin = join(d, "bin"), log = join(d, "log");
+    mkdirSync(wrap, { recursive: true }); mkdirSync(real, { recursive: true });
+    writeFileSync(join(wrap, "docker"), `#!/bin/sh\necho w >> ${log}\nexec "$(PATH="\${PATH#${wrap}:}" command -v docker)" "$@"\n`);
+    writeFileSync(join(real, "docker"), `#!/bin/sh\necho r >> ${log}\necho "Docker version 1"\n`);
+    for (const dir of [wrap, real]) chmodSync(join(dir, "docker"), 0o755);
+    const path = `${wrap}:${bin}:${real}`;
+    const warnings = [];
+    assert.deepEqual(await writeHeavyShims(bin, { path, warn: (m) => warnings.push(m) }), ["docker"]);
+    assert.match(readFileSync(join(bin, "docker"), "utf8"), new RegExp(`-- '${real}/docker' "\\$@"`), "wrapper skipped at write time, real binary baked");
+    assert.deepEqual(warnings, []);
+    // Force the runtime guard: bake the wrapper itself, as a shim written before the wrapper appeared would.
+    writeFileSync(join(bin, "docker"), heavyShimScript("docker", join(wrap, "docker")));
+    chmodSync(join(bin, "docker"), 0o755);
+    const r = spawnSync(join(bin, "docker"), ["--version"], { env: { ...process.env, PATH: `${bin}:${wrap}:${real}:/usr/bin:/bin`, FORGE_HEAVY_DISABLED: "1" }, encoding: "utf8", timeout: 20000 });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /Docker version 1/);
+    assert.equal(readFileSync(log, "utf8"), "w\nr\n", "wrapper and real binary each ran once (two shim node processes at most)");
+  });
+
+  it("a name+cmd seen twice resolves past the shim and chain dirs; no match or depth above the cap is env.shim_loop", () => {
+    const d = tmpDir("heavy-chain-"), a = join(d, "a"), b = join(d, "b"), s = join(d, "s");
+    for (const x of [a, b, s]) { mkdirSync(x, { recursive: true }); writeFileSync(join(x, "tsc"), '#!/bin/sh\nexec "$(command -v tsc)" "$@"\n'); chmodSync(join(x, "tsc"), 0o755); }
+    const env = { PATH: [s, a, b].join(":"), FORGE_HEAVY_SHIM_DIR: s };
+    const first = guardChain("tsc", join(a, "tsc"), env);
+    assert.equal(first.cmd, join(a, "tsc")); assert.equal(first.env.FORGE_HEAVY_CHAIN, `tsc:${join(a, "tsc")}`);
+    const again = guardChain("tsc", join(a, "tsc"), first.env);
+    assert.equal(again.cmd, join(b, "tsc"));
+    assert.equal(again.env.FORGE_HEAVY_CHAIN, `tsc:${join(a, "tsc")}|tsc:${join(b, "tsc")}`);
+    const none = guardChain("tsc", join(b, "tsc"), { ...again.env, PATH: [s, a, b].join(":") });
+    assert.match(none.error, /^env\.shim_loop: tsc .*no other tsc/);
+    const deep = guardChain("tsc", "/x/tsc", { ...env, FORGE_HEAVY_CHAIN: Array.from({ length: SHIM_LOOP_MAX }, (_, i) => `tsc:/d${i}/tsc`).join("|") });
+    assert.match(deep.error, /^env\.shim_loop: tsc re-entered .*more than 4 times.*\/d0/);
+  });
+
+  it("a nested call to the same real binary (not a wrapper) passes through at any depth, unrecorded", async () => {
+    const real = "/home/u/.nvm/bin/npm", spawned = [];
+    const run = async (cmd, a, e) => { spawned.push([cmd, e.FORGE_HEAVY_CHAIN]); return { code: 0, signal: null }; };
+    const chain = Array.from({ length: SHIM_LOOP_MAX - 1 }, (_, i) => `npm:/d${i}/npm`).concat(`npm:${real}`).join("|");
+    for (const FORGE_HEAVY_CHAIN of [`npm:${real}`, chain]) {
+      const env = { PATH: "/shim:/home/u/.nvm/bin", FORGE_HEAVY_CHAIN, FORGE_HEAVY_HELD: "1" };
+      assert.equal((await runWrapped(["run", "--name", "npm", "--", real, "run", "build"], { env, run })).code, 0);
+    }
+    assert.equal(chain.split("|").length, SHIM_LOOP_MAX);
+    assert.deepEqual(spawned, [[real, `npm:${real}`], [real, chain]]);
+  });
+
+  it("runWrapped refuses to spawn on a loop and records the chain otherwise", async () => {
+    const spawned = [];
+    const run = async (cmd, a, e) => { spawned.push([cmd, e.FORGE_HEAVY_CHAIN]); return { code: 0, signal: null }; };
+    const env = { FORGE_HEAVY_HELD: "1", FORGE_HEAVY_CHAIN: Array.from({ length: SHIM_LOOP_MAX }, (_, i) => `x:/d${i}/x`).join("|") };
+    assert.equal((await runWrapped(["run", "--name", "x", "--", "/r/x"], { env, run })).code, 126);
+    assert.deepEqual(spawned, []);
+    await runWrapped(["run", "--name", "x", "--", "/r/x"], { env: { FORGE_HEAVY_HELD: "1" }, run });
+    assert.deepEqual(spawned, [["/r/x", "x:/r/x"]]);
+  });
+
+  it("wrapper detection: PATH-lookup shell scripts only; a wrapper with nothing behind it is skipped with a warning", async () => {
+    assert.ok(isPassThroughWrapper('#!/bin/sh\nexec "$(command -v docker)" "$@"', "docker"));
+    assert.ok(!isPassThroughWrapper("#!/bin/sh\necho hi\n", "docker"));
+    assert.ok(!isPassThroughWrapper("\x7fELF command -v docker", "docker"));
+    const d = tmpDir("heavy-skip-"), wrap = join(d, "wrap"), bin = join(d, "bin");
+    mkdirSync(wrap, { recursive: true });
+    writeFileSync(join(wrap, "docker"), '#!/bin/sh\nexec "$(command -v docker)" "$@"\n'); chmodSync(join(wrap, "docker"), 0o755);
+    const warnings = [];
+    assert.deepEqual(await writeHeavyShims(bin, { path: `${bin}:${wrap}`, warn: (m) => warnings.push(m) }), []);
+    assert.equal(warnings.length, 1); assert.match(warnings[0], /docker .*wrapper/);
+    assert.ok(!existsSync(join(bin, "docker")));
+  });
+});

package/bin/lean/hostkill.mjs

@@ -3,6 +3,6 @@
  * or status 143/137 and no timer of ours fired (our own kills throw CLI_TIMEOUT / CLI_IDLE / CLI_CONTEXT / CLI_TURNS).
  */
 export function isExternalKill(e) {
-  if (e?.code !== "CLI_BACKEND_FAILED") return false;
+  if (e?.code !== "CLI_BACKEND_FAILED") return false; // #4690: a scope-limit stop is CLI_LANE_LIMIT, never a host kill
   return e.signal === "SIGTERM" || e.signal === "SIGKILL" || e.status === 143 || e.status === 137;
 }

package/bin/lean/i18n.mjs

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * English copies in locale catalogs (#4596). A lane adds a key to the source-locale (en) JSON catalog and copies the
+ * English text into the other locales; the repo's own i18n check rejects it, but only on CI. Deterministic (git, no LLM):
+ * for each changed non-en JSON catalog whose en counterpart exists, the keys the lane added whose string value equals the
+ * en value. Counterpart: the path with its locale segment (a directory or the file stem) replaced by `en`.
+ */
+const LOCALE_RE = /^[a-z]{2,3}(?:[-_][A-Za-z]{2,4})?$/;
+const MAX_FINDINGS = 200;
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+const out = (git) => async (args) => { try { return String(await git(args)); } catch { return ""; } };
+
+/** The en counterpart path of a non-en catalog path, or null when no segment looks like a locale code. */
+export function sourcePath(path) {
+  const segs = String(path).split("/");
+  for (let i = segs.length - 1; i >= 0; i--) {
+    const last = i === segs.length - 1;
+    const m = last ? /^(.+)\.json$/.exec(segs[i]) : null;
+    const name = last ? (m ? m[1] : "") : segs[i];
+    if (!LOCALE_RE.test(name) || name === "en") continue;
+    const copy = [...segs];
+    copy[i] = last ? "en.json" : "en";
+    return copy.join("/");
+  }
+  return null;
+}
+
+/** Flattened string leaves of a JSON catalog as Map(dotted key -> value); an empty map on invalid JSON. */
+export function flatten(text) {
+  const res = new Map();
+  let doc;
+  try { doc = JSON.parse(String(text ?? "")); } catch { return res; }
+  const walk = (v, key) => {
+    if (typeof v === "string") res.set(key, v);
+    else if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) walk(x, key ? `${key}.${k}` : k);
+  };
+  walk(doc, "");
+  return res;
+}
+
+/** A value worth translating: three letters in a row once placeholders are removed (not "OK", "{{n}}", "12:00"). */
+const translatable = (v) => /\p{L}{3}/u.test(v.replace(/\{\{?[^}]*\}\}?/g, ""));
+
+/** @returns {Promise<Array<{path, key, value, source}>>}; never throws ([] on any failure). */
+export async function englishCopies({ git, base }) {
+  try {
+    const g = out(git);
+    const changed = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=AM", `${base}...HEAD`])).filter((f) => f.endsWith(".json"));
+    const res = [];
+    for (const f of changed) {
+      const src = sourcePath(f);
+      if (!src) continue;
+      const en = flatten(await g(["show", `HEAD:${src}`]));
+      if (!en.size) continue;
+      const was = flatten(await g(["show", `${base}:${f}`]));
+      for (const [key, value] of flatten(await g(["show", `HEAD:${f}`]))) {
+        if (was.has(key) || en.get(key) !== value || !translatable(value)) continue;
+        res.push({ path: f, key, value, source: src });
+        if (res.length >= MAX_FINDINGS) return res;
+      }
+    }
+    return res;
+  } catch { return []; }
+}

package/bin/lean/i18n.test.mjs

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { englishCopies, sourcePath, flatten } from "./i18n.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
+const put = (root, files) => { for (const [p, t] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), JSON.stringify(t)); } };
+function repo(base, lane) {
+  const d = tmpDir("i18n-");
+  sh(d, "init", "-q", "-b", "main");
+  put(d, base); sh(d, "add", "-A"); sh(d, "commit", "-qm", "base");
+  sh(d, "checkout", "-q", "-b", "lane");
+  put(d, lane); sh(d, "add", "-A"); sh(d, "commit", "-qm", "lane");
+  return d;
+}
+const copies = (d) => englishCopies({ git: async (a) => sh(d, ...a), base: "main" });
+
+describe("i18n english copies (#4596)", () => {
+  it("sourcePath maps a locale file or directory to en", () => {
+    assert.equal(sourcePath("messages/ta.json"), "messages/en.json");
+    assert.equal(sourcePath("locales/kn/common.json"), "locales/en/common.json");
+    assert.equal(sourcePath("messages/en.json"), null);
+    assert.equal(sourcePath("package.json"), null);
+  });
+  it("flatten reads nested string leaves", () => {
+    assert.deepEqual([...flatten('{"a":{"b":"x"},"n":1}')], [["a.b", "x"]]);
+    assert.equal(flatten("not json").size, 0);
+  });
+  it("flags added keys copied from en; ignores translated, pre-existing, short and placeholder values", async () => {
+    const d = repo(
+      { "messages/en.json": { old: "Old text", v: { a: "Calendar view" } }, "messages/ta.json": { old: "Old text" } },
+      { "messages/en.json": { old: "Old text", v: { a: "Calendar view", b: "Go", c: "OK", d: "{{count}}", e: "Week view" } },
+        "messages/ta.json": { old: "Old text", v: { a: "Calendar view", b: "Go", c: "OK", d: "{{count}}", e: "வாரக் காட்சி" } } });
+    const r = await copies(d);
+    assert.deepEqual(r.map((x) => `${x.path}:${x.key}`), ["messages/ta.json:v.a"]);
+  });
+  it("is empty without a source catalog and never throws", async () => {
+    const d = repo({ "messages/ta.json": { a: "Hello there" } }, { "messages/ta.json": { a: "Hello there", b: "Hello there" } });
+    assert.deepEqual(await copies(d), []);
+    assert.deepEqual(await englishCopies({ git: async () => { throw new Error("x"); }, base: "main" }), []);
+  });
+});

package/bin/lean/integration.mjs

@@ -0,0 +1,276 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Milestone integration runs (forge#4667). No LLM anywhere. Under "fast lane gate, heavy ship gate" the whole e2e suite
+ * only runs at the ship PR; this runs it (report-only) on every active milestone branch on a schedule or every N lane
+ * merges, so integration failures surface while the milestone is still open.
+ *
+ * - Config: forge.yaml `ci:` / `milestone_integration:` block (the parser flattens its keys under `ci`); inert without `workflow`.
+ * - State: one `<!-- FORGE:INTEGRATION {json} -->` block in the GitHub milestone description (GitHub is the register):
+ *   lastRun, lastGreen {sha, at, url}, redStreak, mergesSince, mergedPrs, issue.
+ * - Red run: ONE `integration-red` issue per milestone (marker FORGE:INTEGRATION:<slug>), created or its body updated,
+ *   with the failing specs and the merge range. Green: the issue is commented and closed, the streak resets.
+ * - block_admission_after: the orchestrate seam `holds` refuses new lanes of the milestone while the red streak is at
+ *   or over N, until a green run.
+ * The workflow is dispatched on the milestone branch and awaited through runCiVerify (verify.mjs).
+ */
+import { milestoneSlug, readBranches, DEFAULT_FEATURE_PATTERN } from "./lane.mjs";
+import { readMilestone } from "./drift.mjs";
+import { runCiVerify } from "./verify.mjs";
+import { parseForgeYaml } from "../forge-utils.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const STATE_MARKER = "FORGE:INTEGRATION";
+export const RED_LABEL = "integration-red";
+const STATE_RE = /<!-- FORGE:INTEGRATION (\{[\s\S]*?\}) -->/;
+const MAX_PRS = 100;
+
+const arr = (x) => (Array.isArray(x) ? x : []);
+const str = (v) => (v === undefined || v === null ? "" : String(v).trim());
+const posInt = (v) => { const n = Number(v); return str(v) !== "" && Number.isInteger(n) && n > 0 ? n : null; };
+const short = (s) => String(s ?? "").slice(0, 7);
+
+/**
+ * forge.yaml `ci` section → {workflow, project, projectInput, intervalHours, everyMerges, blockAdmissionAfter, maxMinutes}
+ * or null when no valid `workflow` is configured (the feature is off: nothing runs, files or holds).
+ */
+export function parseIntegration(sec) {
+  const s = sec && typeof sec === "object" ? sec : {};
+  const workflow = /^[A-Za-z0-9._/-]+$/.test(str(s.workflow)) ? str(s.workflow) : null;
+  if (!workflow) return null;
+  const hours = Number(s.interval_hours);
+  return {
+    workflow,
+    project: str(s.project) || null,
+    projectInput: /^[A-Za-z_][A-Za-z0-9_-]*$/.test(str(s.project_input)) ? str(s.project_input) : "project",
+    intervalHours: str(s.interval_hours) !== "" && Number.isFinite(hours) && hours > 0 ? hours : 24,
+    everyMerges: posInt(s.every_merges),
+    blockAdmissionAfter: posInt(s.block_admission_after),
+    maxMinutes: posInt(s.max_minutes) ?? 360,
+  };
+}
+
+/** forge.yaml `ci:` of the checkout through parseIntegration; null when absent or unreadable. */
+export function readIntegrationConfig(cwd = process.cwd()) {
+  try { return parseIntegration(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.ci); } catch { return null; }
+}
+
+export const emptyState = () => ({ v: 1, lastRun: null, lastGreen: null, redStreak: 0, mergesSince: 0, mergedPrs: [], issue: null });
+
+/** The FORGE:INTEGRATION state in a milestone description (defaults filled), or null when there is no block. */
+export function parseIntegrationState(description) {
+  const m = STATE_RE.exec(String(description ?? ""));
+  if (!m) return null;
+  try { const s = JSON.parse(m[1]); return s && typeof s === "object" && !Array.isArray(s) ? { ...emptyState(), ...s } : null; } catch { return null; }
+}
+
+/** `description` with its FORGE:INTEGRATION block replaced (or appended); the text around it is unchanged. */
+export function renderState(description, state) {
+  const d = String(description ?? "");
+  const block = `<!-- ${STATE_MARKER} ${JSON.stringify(state).replace(/>/g, "\\u003e")} -->`;
+  if (STATE_RE.test(d)) return d.replace(STATE_RE, () => block);
+  return d ? `${d}\n\n${block}` : block;
+}
+
+/** Due when never run, `intervalHours` elapsed, or `everyMerges` lane merges since the last run. */
+export function isDue(state, cfg, nowMs) {
+  const s = state ?? emptyState();
+  if (!s.lastRun?.at) return { due: true, reason: "never run" };
+  if (cfg.everyMerges && s.mergesSince >= cfg.everyMerges) return { due: true, reason: `${s.mergesSince} lane merge(s) since the last run` };
+  const age = nowMs - Date.parse(s.lastRun.at);
+  if (!Number.isFinite(age) || age >= cfg.intervalHours * 3600000) return { due: true, reason: `last run ${Number.isFinite(age) ? `${Math.round(age / 3600000)}h` : "unknown"} ago` };
+  return { due: false, reason: "not due" };
+}
+
+const SPEC_RE = /[\w@./-]+\.(?:e2e-spec|e2e|spec|test)\.[cm]?[jt]sx?/g;
+/** Spec files named in the failed-job logs (sorted, at most 50). */
+export function failingSpecs(failures) {
+  const out = new Set();
+  for (const f of arr(failures)) for (const m of String(f?.log ?? "").match(SPEC_RE) ?? []) out.add(m.replace(/^\.\//, ""));
+  return [...out].sort().slice(0, 50);
+}
+
+export const redMarker = (slug) => `${STATE_MARKER}:${slug}`;
+
+/** Title and body of the integration-red issue. */
+export function redIssue({ slug, milestone, head, state, failures, specs, runUrl, repo, at }) {
+  const g = state.lastGreen;
+  const range = g?.sha ? `\`${short(g.sha)}..${short(head)}\` ([compare](https://github.com/${repo}/compare/${g.sha}...${head}))` : `no green run yet; up to \`${short(head)}\``;
+  const prs = arr(state.mergedPrs);
+  const body = [
+    `The scheduled full-suite integration run on \`milestone/${slug}\` is red (${state.redStreak} consecutive red run${state.redStreak === 1 ? "" : "s"}). The run is report-only.`, "",
+    `- Run: ${runUrl ?? "n/a"} at \`${short(head)}\` (${at})`,
+    `- Merge range since the last green run: ${range}`,
+    `- Lane PRs merged in that range: ${prs.length ? prs.map((p) => `#${p}`).join(", ") : "none recorded"}`,
+    `- Failing jobs: ${arr(failures).map((f) => f.job).filter(Boolean).join(", ") || "n/a"}`, "",
+    "### Failing specs", "", ...(specs.length ? specs.map((s) => `- \`${s}\``) : ["- none named in the failed-job logs; see the run"]), "",
+    "This issue is a ship-gate risk for the milestone and closes itself on the next green integration run.", "",
+    `<!-- ${redMarker(slug)} -->`,
+  ].join("\n");
+  return { title: `integration-red(milestone/${slug}): full suite failing at ${short(head)}`, body, marker: redMarker(slug), milestone };
+}
+
+/** Open issue of the milestone carrying `marker`: its number, or null. */
+async function findRed({ gh, repo, milestone, marker }) {
+  const open = JSON.parse(String(await gh(["issue", "list", "-R", repo, "--milestone", milestone, "--state", "open", "--limit", "500", "--json", "number,body"])) || "[]");
+  const hit = arr(open).find((x) => String(x?.body ?? "").includes(`<!-- ${marker} -->`));
+  return hit ? Number(hit.number) : null;
+}
+
+/** Create the one integration-red issue, or replace the body of the open one. Resolves its number. */
+export async function fileOrUpdateRed({ gh, repo, issue }) {
+  const n = await findRed({ gh, repo, milestone: issue.milestone, marker: issue.marker });
+  if (n) { await gh(["issue", "edit", String(n), "-R", repo, "--title", issue.title, "--body", issue.body]); return { number: n, created: false }; }
+  const base = ["issue", "create", "-R", repo, "--title", issue.title, "--body", issue.body, "--milestone", issue.milestone];
+  let out;
+  try { out = String(await gh([...base, "--label", RED_LABEL])); } catch { out = String(await gh(base)); } // the label may not exist in the repo yet
+  return { number: Number(/\/issues\/(\d+)/.exec(out)?.[1]) || null, created: true };
+}
+
+/** Green: comment on and close the open integration-red issue of the milestone, if any. */
+export async function closeRed({ gh, repo, milestone, slug, head }) {
+  const n = await findRed({ gh, repo, milestone, marker: redMarker(slug) });
+  if (n) await gh(["issue", "close", String(n), "-R", repo, "--comment", `Integration run green at \`${short(head)}\`; closing.`]);
+  return n;
+}
+
+const branchOf = (pattern, title) => { const slug = milestoneSlug(title); return slug ? { slug, branch: String(pattern || DEFAULT_FEATURE_PATTERN).replace("{slug}", slug) } : null; };
+
+/** Head SHA of `branch`, or null when it does not exist. */
+async function branchHead(gh, repo, branch) {
+  try { return str(await gh(["api", `repos/${repo}/branches/${encodeURIComponent(branch)}`, "--jq", ".commit.sha"])) || null; } catch { return null; }
+}
+
+/**
+ * One integration run of one milestone: dispatch, wait, record. Resolves {title, ran, result, detail, state}. `ran` is
+ * false when the milestone is skipped (no branch, not due); a timeout or unavailable run records nothing and retries next time.
+ */
+export async function runMilestone({ io, repo, ms, cfg, pattern, nowFn = () => Date.now(), sleep, random, force = false, onPoll }) {
+  const gh = io.gh, b = branchOf(pattern, ms.title);
+  if (!b) return { title: ms.title, ran: false, detail: "milestone gives an empty branch slug" };
+  const head = await branchHead(gh, repo, b.branch);
+  if (!head) return { title: ms.title, ran: false, detail: `branch ${b.branch} not found` };
+  const before = parseIntegrationState(ms.description) ?? emptyState();
+  const due = isDue(before, cfg, nowFn());
+  if (!force && !due.due) return { title: ms.title, ran: false, detail: due.reason, state: before };
+  const v = await runCiVerify({ io, branch: b.branch, head, changedFiles: [cfg.project ?? "integration"], verify: { workflow: cfg.workflow, pathsInput: cfg.project ? cfg.projectInput : null, skipPaths: [] },
+    ciMaxMinutes: cfg.maxMinutes, now: nowFn, sleep, random, ...(onPoll ? { onPoll } : {}) });
+  if (v.result !== "pass" && v.result !== "fail") return { title: ms.title, ran: true, result: v.result, detail: v.detail, state: before };
+  const at = new Date(nowFn()).toISOString();
+  const state = { ...before, lastRun: { sha: head, at, result: v.result, url: v.runUrl ?? null }, mergesSince: 0 };
+  if (v.result === "pass") {
+    state.lastGreen = { sha: head, at, url: v.runUrl ?? null }; state.redStreak = 0; state.mergedPrs = []; state.issue = null;
+    await closeRed({ gh, repo, milestone: ms.title, slug: b.slug, head });
+  } else {
+    state.redStreak = (before.redStreak ?? 0) + 1;
+    const specs = failingSpecs(v.failures);
+    const filed = await fileOrUpdateRed({ gh, repo, issue: redIssue({ slug: b.slug, milestone: ms.title, head, state: { ...state, blockAdmissionAfter: cfg.blockAdmissionAfter }, failures: v.failures, specs, runUrl: v.runUrl, repo, at }) });
+    state.issue = filed.number;
+  }
+  await gh(["api", "-X", "PATCH", `repos/${repo}/milestones/${ms.number}`, "-f", `description=${renderState(ms.description, state)}`]);
+  return { title: ms.title, ran: true, result: v.result, detail: v.detail, state };
+}
+
+/** Every open milestone → {number, title, description}. */
+export async function listOpenMilestones({ gh, repo }) {
+  return arr(JSON.parse(String(await gh(["api", `repos/${repo}/milestones?state=open&per_page=100`])) || "[]")).map((m) => ({ number: m.number, title: m.title, description: m.description ?? "" }));
+}
+
+/** Run every due active milestone (optionally only `only`, a title). Sequential: one suite at a time. Resolves the per-milestone results. */
+export async function runIntegration({ io, repo, cfg, pattern, only = null, ...rest }) {
+  if (!cfg) return [];
+  const out = [];
+  for (const ms of await listOpenMilestones({ gh: io.gh, repo })) {
+    if (only && ms.title !== only) continue;
+    try { out.push(await runMilestone({ io, repo, ms, cfg, pattern, ...rest })); } catch (e) { out.push({ title: ms.title, ran: false, detail: `failed: ${String(e?.message ?? e).slice(0, 200)}` }); }
+  }
+  return out;
+}
+
+/**
+ * The orchestrate seam: `{ onMerged(issue, row, result), holds(issue, {lane}), prime(), settle() }`, or null when `cfg` is null.
+ * onMerged counts the merge into the milestone state and, at `every_merges`, starts a run in the background (never in the
+ * lane's slot); `settle()` waits for those. `prime()` loads the red streaks `holds` reads (synchronously) from the milestones.
+ */
+export function makeIntegration({ repo, io, cfg, pattern = DEFAULT_FEATURE_PATTERN, nowFn = () => Date.now(), sleep, random, onEvent = () => {} }) {
+  if (!cfg) return null;
+  const streaks = new Map(); // lane -> consecutive red runs
+  const running = new Set();
+  const pending = new Set();
+  let chain = Promise.resolve();
+  const lane = (title) => { const b = branchOf(pattern, title); return b ? b.branch : null; };
+  const note = (ms, state) => { const l = lane(ms.title); if (l) streaks.set(l, state?.redStreak ?? 0); };
+
+  async function count(issue, result) {
+    const title = result?.milestone;
+    if (!title) return;
+    const ms = await readMilestone({ gh: io.gh, repo, title });
+    if (!ms) return;
+    const full = { ...ms, title };
+    const s = parseIntegrationState(ms.description) ?? emptyState();
+    const pr = result.pr ?? null;
+    const next = { ...s, mergesSince: (s.mergesSince ?? 0) + 1, mergedPrs: pr != null && !s.mergedPrs.includes(pr) ? [...s.mergedPrs, pr].slice(-MAX_PRS) : s.mergedPrs };
+    const desc = renderState(ms.description, next);
+    await io.gh(["api", "-X", "PATCH", `repos/${repo}/milestones/${ms.number}`, "-f", `description=${desc}`]);
+    note(full, next);
+    if (!cfg.everyMerges || next.mergesSince < cfg.everyMerges || running.has(title)) return;
+    running.add(title);
+    const p = runMilestone({ io, repo, ms: { ...full, description: desc }, cfg, pattern, nowFn, sleep, random })
+      .then((r) => { if (r.state) note(full, r.state); onEvent({ issue, detail: `integration: ${title} ${r.result ?? r.detail}` }); })
+      .catch((e) => onEvent({ issue, detail: `integration run failed: ${String(e?.message ?? e).slice(0, 200)}` }))
+      .finally(() => { running.delete(title); pending.delete(p); });
+    pending.add(p);
+  }
+
+  return {
+    onMerged(issue, row, result) {
+      const p = chain.then(() => count(issue, result));
+      chain = p.catch(() => {});
+      return p;
+    },
+    holds(issue, { lane: l } = {}) {
+      if (!cfg.blockAdmissionAfter) return null;
+      const n = streaks.get(String(l ?? ""));
+      return n >= cfg.blockAdmissionAfter ? `${n} consecutive red integration runs on ${l}` : null;
+    },
+    async prime() {
+      for (const ms of await listOpenMilestones({ gh: io.gh, repo })) note(ms, parseIntegrationState(ms.description));
+    },
+    async settle() { await chain; while (pending.size) await Promise.allSettled([...pending]); },
+  };
+}
+
+/**
+ * `forgedock integration run [--repo owner/repo] [--milestone TITLE] [--force]`: one pass over the active milestones, for
+ * cron or a GitHub Actions schedule. Prints one line per milestone. Resolves the exit code (1 when a run was red).
+ * `forgedock integration status [--repo owner/repo]`: the last green full-suite run of each active milestone (those with
+ * a state block, or all when `ci.workflow` is set), for /pipeline-status.
+ */
+export async function runIntegrationCli(argv, deps = {}) {
+  const val = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : null; };
+  if (argv[0] === "status") {
+    const repo = val("--repo") ?? deps.repo;
+    if (!repo) throw new Error("integration needs the repo: pass --repo owner/repo");
+    const io = deps.io ?? (await import("./effects.mjs")).makeLeanIo({ repo });
+    const on = deps.cfg !== undefined ? !!deps.cfg : !!readIntegrationConfig(deps.cwd ?? process.cwd());
+    for (const ms of await listOpenMilestones({ gh: io.gh, repo })) {
+      const s = parseIntegrationState(ms.description);
+      if (s || on) (deps.print ?? ((t) => console.log(t)))(`  integration: ${ms.title}: last green full-suite run ${s?.lastGreen?.at ?? "never"} (red streak ${s?.redStreak ?? 0})`);
+    }
+    return 0;
+  }
+  if (argv[0] !== "run") throw new Error("usage: forgedock integration run|status [--repo owner/repo] [--milestone TITLE] [--force]");
+  const cwd = deps.cwd ?? process.cwd();
+  const cfg = deps.cfg !== undefined ? deps.cfg : readIntegrationConfig(cwd);
+  const print = deps.print ?? ((t) => console.log(t));
+  if (!cfg) { print("integration: no ci.workflow configured in forge.yaml; nothing to run"); return 0; }
+  const repo = val("--repo") ?? deps.repo;
+  if (!repo) throw new Error("integration needs the repo: pass --repo owner/repo");
+  const io = deps.io ?? (await import("./effects.mjs")).makeLeanIo({ repo });
+  const pattern = deps.pattern ?? readBranches(cwd).featurePattern ?? DEFAULT_FEATURE_PATTERN;
+  const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const res = await runIntegration({ io, repo, cfg, pattern, only: val("--milestone"), force: argv.includes("--force"), nowFn: deps.now ?? (() => Date.now()), sleep, random: deps.random ?? Math.random });
+  for (const r of res) print(`integration: ${r.title}: ${r.ran ? r.result ?? "n/a" : "skipped"}${r.detail ? ` (${r.detail})` : ""}`);
+  return res.some((r) => r.result === "fail") ? 1 : 0;
+}