forgedock 1.37.0 → 1.38.1

package/bin/lean/execution.test.mjs

@@ -6,7 +6,8 @@ import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { renderContract } from "./render.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -726,6 +727,68 @@ describe("host capabilities in placement (#4542)", () => {
     assert.deepEqual(hostCapabilityBlock("owner must create an account", caps), []);
   });
 
+  it("#4785 placementText: body, FORGE:DECISION comments and the last frozen contract's validate commands", () => {
+    const exec = parseExecution({ mode: "remote", max_remote: 2, host_capabilities: "promtool" });
+    const k = (cmd) => "<!-- FORGE:CONTRACT -->\n<!-- FORGE:PLAN -->\n" + renderContract({ requirements: [], deliverables: [], validate: [{ id: "V1", command: cmd }] }, "abcdef123456");
+    const comments = [{ body: "<!-- FORGE:DECISION -->\n## Decision\ngather the data via `ssh ovh-monitor obs-psql`" }, { body: k("node --test a.mjs") },
+      { body: k("promtool test rules x.yml") }, { body: "just chatter about sops" }, "not an object", null];
+    const t = placementText({ body: "add an alert", comments });
+    assert.deepEqual(detectNeeds(t, exec), ["prod_monitor", "promtool"]);
+    assert.doesNotMatch(t, /chatter|node --test a\.mjs/);
+    assert.deepEqual(detectNeeds("add an alert", exec), []); // the body alone: what placement read before #4785
+    assert.equal(placementText({ body: "b", comments: undefined }), "b");
+    assert.equal(placementText(), "");
+  });
+
+  it("#4785 contractHostNeeds: only declared capabilities in validate commands", () => {
+    const caps = { hostCapabilities: ["promtool"] };
+    const c = { validate: [{ id: "V1", command: "node --test a.mjs" }, { id: "V2", command: "promtool check rules r.yml" }, { id: "V3", command: "sops -d x.enc.yaml" }] };
+    assert.deepEqual(contractHostNeeds(c, caps), { caps: ["promtool"], ids: ["V2"] });
+    assert.deepEqual(contractHostNeeds(c, null), { caps: [], ids: [] });
+    assert.deepEqual(contractHostNeeds(null, caps), { caps: [], ids: [] });
+  });
+
+  it("#4776 placementText ignores quoted evidence in the body (AlterLab #37290-#37317 fixture)", () => {
+    const rows = JSON.parse(readFileSync(new URL("../tests/fixtures/alterlab-capability-bodies.json", import.meta.url), "utf8"));
+    assert.equal(rows.length, 6);
+    for (const r of rows) {
+      assert.deepEqual(detectNeeds(placementText({ body: r.body })), r.needs, `#${r.issue}: ${r.note}`);
+      if (!r.needs.length) assert.ok(detectNeeds(r.body).includes("prod_monitor"), `#${r.issue} pinned before #4776`);
+    }
+  });
+
+  it("#4776 placementText: fences, quotes, comments and evidence sections are dropped, prose and decisions stay", () => {
+    const body = "Intro.\n```sh\nssh ovh-monitor obs-psql\n```\n> ssh ovh-monitor\n<!-- FORGE:STATE\n{\"reason\":\"prod_monitor\"}\n-->\n## Logs\nobs-psql here\n### Sub\nobs-psql sub\n## Plan\nneeds sops access\n";
+    assert.deepEqual(detectNeeds(placementText({ body })), ["sops"]);
+    assert.deepEqual(detectNeeds(placementText({ body: "~~~\nobs-psql\n~~~\nrun `obs-psql`" })), []);
+    assert.deepEqual(detectNeeds(placementText({ body: "needs the prod monitor" })), ["prod_monitor"]);
+    assert.deepEqual(detectNeeds(placementText({ body: "x", comments: [{ body: "<!-- FORGE:DECISION -->\nuse `ssh ovh-monitor obs-psql`" }] })), ["prod_monitor"]);
+  });
+
+  it("#4776 repro_test commands count: placementText and contractHostNeeds", () => {
+    const exec = parseExecution({ mode: "remote", max_remote: 2, host_capabilities: "promtool" });
+    const caps = { hostCapabilities: ["promtool"] };
+    const c = { validate: [{ id: "V1", command: "node --test a.mjs" }], repro_test: { command: "promtool test rules x.yml" } };
+    assert.deepEqual(contractHostNeeds(c, caps), { caps: ["promtool"], ids: ["repro_test"] });
+    assert.deepEqual(contractHostNeeds({ validate: [], repro_test: "none" }, caps), { caps: [], ids: [] });
+    const comment = "<!-- FORGE:CONTRACT -->\n<!-- FORGE:PLAN -->\n" + renderContract({ requirements: [], deliverables: [], validate: [{ id: "V1", command: "node --test a.mjs" }], repro_test: { command: "promtool test rules x.yml" } }, "abcdef123456");
+    const t = placementText({ body: "b", comments: [{ body: comment }] });
+    assert.deepEqual(detectNeeds(t, exec), ["promtool"]);
+  });
+
+  it("#4785 orchestrate: a remote lane that ends env.tool_missing is relaunched locally", async () => {
+    const calls = [];
+    const rows = await orchestrate({ issues: [5], parallel: 2, recovery: { maxAttempts: 1 }, readBody: async () => "",
+      remote: { max: 2, isRemote: () => true, place: () => ({ where: "remote", reason: "mode remote" }), admit: () => ({ ok: true }), onBudget: "stop", costPerMinute: 0 },
+      runOne: async (n, _l, ctx = {}) => {
+        calls.push({ placement: ctx.placement?.where, reason: ctx.placement?.reason, recover: ctx.recover?.code ?? null });
+        return ctx.recover ? { terminalReason: "merged", pr: 9 } : { terminalReason: "needs-human", code: "env.tool_missing", detail: "promtool: command not found" };
+      } });
+    assert.deepEqual(calls.map((c) => [c.placement, c.recover]), [["remote", null], ["local", "env.tool_missing"]]);
+    assert.equal(calls[1].reason, "host capability: recovering env.tool_missing");
+    assert.equal(rows.find((r) => r.issue === 5).outcome, "merged");
+  });
+
   it("orchestrate: a remote lane that ends env.capability_remote is relaunched locally once", async () => {
     const calls = [];
     const rows = await orchestrate({ issues: [5], parallel: 2, recovery: { maxAttempts: 1 }, readBody: async () => "",

package/bin/lean/explore.test.mjs

@@ -42,7 +42,7 @@ describe("explorer subagent config (#4391)", () => {
     const [plain, withAgents] = seen;
     assert.ok(!plain.includes("--agents"));
     const i = withAgents.indexOf("--agents");
-    assert.deepEqual(withAgents.slice(0, i), plain);
+    assert.deepEqual([...withAgents.slice(0, i), ...withAgents.slice(i + 2)], plain, "only the --agents pair is added");
     assert.deepEqual(JSON.parse(withAgents[i + 1]), agents);
   });
 

package/bin/lean/guards.mjs

@@ -13,6 +13,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { isTestPath } from "./enumerating.mjs";
 import { parseContractComment } from "./render.mjs";
+import { isTrustedIssueComment } from "./prefilter.mjs";
 
 export const GUARD_MARKER = "FORGE:GUARD";
 const GUARD_RE = /<!-- FORGE:GUARD (\{[\s\S]*?\}) -->/;
@@ -98,7 +99,7 @@ export async function guardIssue({ gh, git, repo, issue, pr = null, post = null,
   const iss = json(await gh(["issue", "view", String(issue), "-R", repo, "--json", "number,title,comments"]), null);
   if (!iss) return { skipped: true, reason: `#${issue}: issue not readable` };
   const bodies = (iss.comments ?? []).map((c) => c?.body ?? "");
-  const existing = bodies.map(parseGuard).find(Boolean);
+  const existing = (iss.comments ?? []).filter(isTrustedIssueComment).map((c) => parseGuard(c?.body)).find(Boolean); // #4750: only trusted authors may plant a guard
   if (existing) return { exists: true, guard: existing };
   const cb = [...bodies].reverse().find((b) => b.startsWith("<!-- FORGE:CONTRACT -->") && parseContractComment(b));
   if (!cb) return { skipped: true, reason: `no guard for #${issue}: no frozen FORGE:CONTRACT comment` };
@@ -126,7 +127,7 @@ export async function guardIssue({ gh, git, repo, issue, pr = null, post = null,
 export async function collectGuards({ gh, repo, limit = 500 }) {
   const rows = json(await gh(["issue", "list", "-R", repo, "--state", "all", "--search", `${GUARD_MARKER} in:comments`, "--limit", String(limit), "--json", "number,comments"]), []);
   const guards = [];
-  for (const r of rows) for (const c of r.comments ?? []) { const g = hasMarker(c?.body) ? parseGuard(c.body) : null; if (g) { guards.push(g); break; } }
+  for (const r of rows) for (const c of r.comments ?? []) { const g = hasMarker(c?.body) && isTrustedIssueComment(c) ? parseGuard(c.body) : null; if (g) { guards.push(g); break; } }
   return guards;
 }
 

package/bin/lean/guards.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import test from "node:test";
 import assert from "node:assert/strict";
-import { buildGuard, guardTests, parseHunks, renderGuard, parseGuard, guardIssue, listGuards, backfill, guardsCli, readIndex, guardAfterMerge, historyPreserve, withHistoryRows, writeIndex } from "./guards.mjs";
+import { buildGuard, guardTests, parseHunks, renderGuard, parseGuard, guardIssue, collectGuards, listGuards, backfill, guardsCli, readIndex, guardAfterMerge, historyPreserve, withHistoryRows, writeIndex } from "./guards.mjs";
 import { renderContract } from "./render.mjs";
 import { tmpDir } from "../tests/_tmp.mjs";
 
@@ -55,7 +55,7 @@ function fakeGh({ contract, comments = [], title = "Fix the thing" }) {
   const posted = [];
   const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], validate: [], ...contract }, "abcdef123456")}`;
   const gh = async (a) => {
-    if (a[0] === "issue" && a[1] === "view") return JSON.stringify({ number: 7, title, comments: [{ body }, ...comments, ...posted.map((b) => ({ body: b }))] });
+    if (a[0] === "issue" && a[1] === "view") return JSON.stringify({ number: 7, title, comments: [{ body }, ...comments, ...posted.map((b) => ({ body: b, authorAssociation: "OWNER" }))] });
     if (a[0] === "pr" && a[1] === "view") return JSON.stringify({ number: 9, mergeCommit: { oid: "deadbeefcafe" } });
     if (a[0] === "issue" && a[1] === "comment") { posted.push(a[a.indexOf("--body") + 1]); return ""; }
     throw new Error(`unexpected gh ${a.join(" ")}`);
@@ -74,6 +74,27 @@ test("guardIssue posts exactly one FORGE:GUARD and is idempotent on rerun", asyn
   assert.equal(parseGuard(f.posted[0]).merge_sha, "deadbeefcafe");
 });
 
+test("guardIssue ignores a planted FORGE:GUARD from an untrusted author and still posts the real one", async () => {
+  const planted = buildGuard({ issue: 7, title: "t", contract: nodeContract, diff: DIFF }).guard;
+  const f = fakeGh({ contract: nodeContract, comments: [{ body: renderGuard(planted), authorAssociation: "NONE", author: { login: "mallory" } }] });
+  assert.ok((await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 })).posted);
+  const t = fakeGh({ contract: nodeContract, comments: [{ body: renderGuard(planted), authorAssociation: "MEMBER" }] });
+  assert.ok((await guardIssue({ gh: t.gh, git, repo: "o/r", issue: 7, pr: 9 })).exists);
+});
+
+test("collectGuards ignores a FORGE:GUARD comment from an untrusted author", async () => {
+  const mk = (issue) => renderGuard(buildGuard({ issue, title: "t", contract: nodeContract, diff: DIFF }).guard);
+  const gh = async () => JSON.stringify([
+    { number: 1, comments: [{ body: mk(1), authorAssociation: "OWNER" }] },
+    { number: 2, comments: [{ body: mk(2), authorAssociation: "CONTRIBUTOR", author: { login: "mallory" } }] },
+    { number: 3, comments: [{ body: mk(3), authorAssociation: "NONE" }, { body: mk(3), authorAssociation: "MEMBER" }] },
+  ]);
+  assert.deepEqual((await collectGuards({ gh, repo: "o/r" })).map((g) => g.issue), [1, 3]);
+  const root = tmpDir("guards-");
+  await guardsCli(["list"], { gh, repo: "o/r", print: () => {}, root });
+  assert.deepEqual(readIndex("o/r", { root }).map((g) => g.issue), [1, 3]);
+});
+
 test("guardIssue: no test posts nothing; unavailable merge commit is a logged skip", async () => {
   const f = fakeGh({ contract: { repro_test: "none", repro_test_reason: "n/a" } });
   assert.ok((await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 })).skipped);
@@ -111,7 +132,7 @@ test("guards list prints guards for a path and caches the index; falls back to i
   const root = tmpDir("guards-");
   {
     const g = buildGuard({ issue: 7, title: "t", contract: nodeContract, diff: DIFF }).guard;
-    const gh = async () => JSON.stringify([{ number: 7, comments: [{ body: renderGuard(g) }] }]);
+    const gh = async () => JSON.stringify([{ number: 7, comments: [{ body: renderGuard(g), authorAssociation: "OWNER" }] }]);
     const out = [];
     assert.equal(await guardsCli(["list", "--path", "src/a.mjs"], { gh, repo: "o/r", print: (m) => out.push(m), root }), 0);
     assert.match(out[0], /#7/);

package/bin/lean/heavy.mjs

@@ -36,15 +36,22 @@ const PMS = new Set(["npm", "pnpm", "yarn", "bun"]);
 const PM_LIGHT = new Set(["version", "help", "view", "info", "show", "ls", "list", "why", "outdated", "config", "get", "set", "whoami", "root", "bin", "prefix", "store", "cache", "pack", "publish", "login", "logout", "search", "owner", "dist-tag"]);
 const PM_VALUE_FLAGS = new Set(["-w", "-C", "-F", "--filter", "--dir", "--cwd", "--prefix", "--workspace"]);
 const RUNNERS = new Set(["npx", "bunx", "pnpx"]);
-const TOOLS = new Set(["tsc", "eslint", "jest", "vitest", "playwright", "pytest", "mypy", "pyright", "tox", "gradle", "gradlew", "mvn"]);
+const TOOLS = new Set(["tsc", "eslint", "jest", "vitest", "playwright", "pytest", "mypy", "pyright", "tox", "gradle", "gradlew", "mvn", "ruff", "black", "flake8", "pylint", "make", "cmake", "ninja"]);
 const SUBTOOLS = {
   cargo: new Set(["build", "b", "test", "t", "check", "c", "clippy", "run", "r", "bench", "doc", "install"]),
   go: new Set(["build", "test", "vet", "run", "install", "generate"]),
   docker: new Set(["run", "build", "compose", "buildx"]),
   "docker-compose": new Set(["up", "run", "build", "create", "start"]),
+  promtool: new Set(["check", "test"]),
+  pip: new Set(["install", "wheel", "download"]),
+  pip3: new Set(["install", "wheel", "download"]),
 };
+/** #4777: Python project managers; `run <cmd>` takes the class of <cmd>, these subcommands install or build. */
+const PY_MANAGERS = new Set(["poetry", "uv", "pipenv", "pdm", "hatch"]);
+const PY_MGR_HEAVY = new Set(["install", "sync", "build", "add", "lock", "update"]);
+const PY_SHIMS = ["python", "python3"];
 /** Every command name a heavy shim is written for (only those found on the lane PATH get one). */
-export const HEAVY_BINS = Object.freeze([...PMS, ...RUNNERS, ...TOOLS, ...Object.keys(SUBTOOLS)]);
+export const HEAVY_BINS = Object.freeze([...PMS, ...RUNNERS, ...TOOLS, ...Object.keys(SUBTOOLS), ...PY_MANAGERS, ...PY_SHIMS]);
 const INFO = new Set(["-v", "-V", "--version", "version", "-h", "--help", "help"]);
 
 /** 'heavy' | 'llm' for one command line (`name` is the basename, `args` its argv). Unknown commands are llm. */
@@ -61,6 +68,12 @@ export function classifyStep(name, args = []) {
     return PM_LIGHT.has(sub) || INFO.has(sub) ? "llm" : "heavy";
   }
   if (RUNNERS.has(n) || TOOLS.has(n)) return a.length === 0 && RUNNERS.has(n) ? "llm" : onlyInfo ? "llm" : "heavy";
+  if (PY_MANAGERS.has(n)) {
+    const i = a.findIndex((x) => !x.startsWith("-")), sub = a[i];
+    if (sub === "run") { const inner = a.slice(i + 1).filter((x, j, all) => !(j === 0 && x === "--") || all.length === 1); return inner.length ? (classifyStep(inner[0], inner.slice(1)) === "heavy" || isHeavyProcess(inner.join(" ")) ? "heavy" : "llm") : "llm"; }
+    return PY_MGR_HEAVY.has(sub) ? "heavy" : "llm";
+  }
+  if (PY_SHIMS.includes(n)) { const mi = a.indexOf("-m"); return mi >= 0 && PY_HEAVY_MODULES.has(a[mi + 1]) ? "heavy" : "llm"; }
   if (SUBTOOLS[n]) { const sub = a.find((x) => !x.startsWith("-")); return sub && SUBTOOLS[n].has(sub) ? "heavy" : "llm"; }
   return "llm";
 }

package/bin/lean/heavy.test.mjs

@@ -7,9 +7,9 @@ import { writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from "n
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.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 { checkAdmission, ADMISSION_DEFAULTS, localLaneCap } from "./admission.mjs";
 import { formatAlertLines, formatWaitSummary } from "./orchestrate.mjs";
-import { readHeavy } from "../engine-cli.mjs";
+import { readHeavy, liveLaneCap } from "../engine-cli.mjs";
 
 // Injected pids, clock and host: `live` is the set of pids the registry sees as alive; `mem` the MemAvailable in MB.
 const world = ({ mem = 12000, cores = 4, swapFree = 0 } = {}) => {
@@ -308,3 +308,32 @@ describe("shim re-entry through a pass-through wrapper (#4680)", () => {
     assert.ok(!existsSync(join(bin, "docker")));
   });
 });
+
+describe("validation steps and the local lane cap (#4777)", () => {
+  it("python project managers, promtool, pip, make and python -m <test runner> are heavy; metadata and plain scripts are llm", () => {
+    const heavy = [["poetry", ["run", "pytest", "-q"]], ["poetry", ["run", "python", "-m", "pytest"]], ["uv", ["run", "--", "pytest"]], ["poetry", ["install"]], ["uv", ["sync"]],
+      ["promtool", ["test", "rules", "r.yml"]], ["promtool", ["check", "config", "p.yml"]], ["pip", ["install", "x"]], ["python3", ["-m", "pytest"]], ["ruff", ["check", "."]], ["make", ["test"]]];
+    for (const [n, a] of heavy) assert.equal(classifyStep(n, a), "heavy", `${n} ${a.join(" ")}`);
+    const llm = [["poetry", ["--version"]], ["poetry", ["run", "python", "x.py"]], ["poetry", ["show"]], ["promtool", ["query", "instant", "u", "q"]], ["python", ["x.py"]], ["python3", ["-c", "print(1)"]], ["make", ["--version"]]];
+    for (const [n, a] of llm) assert.equal(classifyStep(n, a), "llm", `${n} ${a.join(" ")}`);
+    for (const n of ["poetry", "uv", "promtool", "pip", "python3", "make"]) assert.ok(HEAVY_BINS.includes(n), n);
+  });
+
+  it("localLaneCap follows cores and free memory, keeps at least one lane, and is off when admission is disabled or probes are unknown", () => {
+    assert.equal(localLaneCap({ cores: 4, memAvailableMb: 64000 }), 4);
+    assert.equal(localLaneCap({ cores: 4, memAvailableMb: 64000, cfg: { lane_cpu_reservation: 2 } }), 2);
+    assert.equal(localLaneCap({ cores: 16, memAvailableMb: 2048 + 3 * 2048 + 10 }), 3, "memory binds: (free - min_free_mem_mb) / lane_mem_mb");
+    assert.equal(localLaneCap({ cores: 4, memAvailableMb: 100 }), 1);
+    assert.equal(localLaneCap({ cores: 4, memAvailableMb: 64000, cfg: { enabled: false } }), null);
+    assert.equal(localLaneCap({}), null);
+    assert.equal(localLaneCap({ cores: 8 }), 8);
+  });
+
+  it("liveLaneCap re-probes at each call and honours global_parallel", () => {
+    const h = { c: 4, m: 64000 };
+    const cap = liveLaneCap(null, { cfg: {}, host: { cores: () => h.c, memAvailableMb: () => h.m } });
+    assert.equal(cap(), 4); h.c = 2; assert.equal(cap(), 2);
+    assert.equal(liveLaneCap(1, { cfg: {}, host: { cores: () => 8, memAvailableMb: () => 64000 } })(), 1);
+    assert.equal(liveLaneCap(3, { cfg: { enabled: false }, host: { cores: () => 8, memAvailableMb: () => 64000 } })(), 3);
+  });
+});

package/bin/lean/issuewatch-release.mjs

@@ -0,0 +1,245 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * `mode: release` of `forgedock issue-watch` (#4767): pool eligible issues, cut a themed release when a threshold is crossed,
+ * orchestrate it as one batch and open the deploy PR. Deterministic first: score, triggers, theme rules, the `Depends on`
+ * closure and the cap are pure functions; the only judgment is one injected `io.classify` call for issues no `theme_map` rule
+ * classifies (counted in `state.llm`). The watch never merges: the deploy PR is only created, promotion stays human-only.
+ */
+import { milestoneSlug } from "./lane.mjs";
+import { noComments } from "./render.mjs";
+
+export const PRIORITY_WEIGHT = { P0: 8, P1: 4, P2: 2, P3: 1 };
+export const GENERAL_THEME = "general";
+const DAY = 86400000;
+const labelNames = (i) => (i.labels ?? []).map((l) => (typeof l === "string" ? l : l?.name)).filter(Boolean);
+
+/** `P0`..`P3` from a `P1` or `priority:P1` label; null when none. */
+export function priorityOf(issue) {
+  for (const l of labelNames(issue)) { const m = /^(?:priority[:/ -]?)?(P[0-3])$/i.exec(l); if (m) return m[1].toUpperCase(); }
+  return null;
+}
+/** Priority weight; an unprioritised issue weighs 1 (P3). */
+export const weightOf = (issue) => PRIORITY_WEIGHT[priorityOf(issue)] ?? 1;
+export const ageDays = (issue, now) => Math.max(0, (now - Date.parse(issue.createdAt)) / DAY);
+export const poolScore = (issues) => issues.reduce((s, i) => s + weightOf(i), 0);
+
+/** True when `issue` matches an `immediate` entry: `label:<name>` or `priority:<P0..P3>`. */
+export function isImmediate(issue, immediate = []) {
+  const names = labelNames(issue).map((l) => l.toLowerCase());
+  return immediate.some((r) => { const [k, ...v] = String(r).split(":"), val = v.join(":").trim().toLowerCase(); return k === "label" ? names.includes(val) : k === "priority" ? priorityOf(issue)?.toLowerCase() === val : false; });
+}
+
+/** Every trigger that fires for the pool: `[{kind, detail}]` (min_issues, min_score, max_age_days, immediate). */
+export function triggers(pool, watch, now) {
+  const t = watch.threshold ?? {}, out = [];
+  if (!pool.length) return out;
+  if (t.min_issues && pool.length >= t.min_issues) out.push({ kind: "min_issues", detail: `${pool.length} >= ${t.min_issues}` });
+  const score = poolScore(pool);
+  if (t.min_score && score >= t.min_score) out.push({ kind: "min_score", detail: `score ${score} >= ${t.min_score}` });
+  const oldest = Math.max(...pool.map((i) => ageDays(i, now)));
+  if (t.max_age_days && oldest >= t.max_age_days) out.push({ kind: "max_age_days", detail: `oldest ${oldest.toFixed(1)}d >= ${t.max_age_days}d` });
+  const imm = pool.filter((i) => isImmediate(i, watch.immediate));
+  if (imm.length) out.push({ kind: "immediate", detail: `#${imm.map((i) => i.number).join(", #")}` });
+  return out;
+}
+
+// ── themes ──────────────────────────────────────────────────────────────────────────────────────────────────
+/** The conventional-commit scope of a title: `feat(security): x` → `security`. */
+export const titleScope = (title) => /^\w+\(([^)]+)\)!?:/.exec(String(title ?? ""))?.[1].trim().toLowerCase() ?? null;
+const globRe = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\u0000").replace(/\*\*/g, "\u0001").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, "(?:.*/)?").replace(/\u0001/g, ".*")}$`);
+/** Paths an issue names: slash-containing tokens of title and body (backticks, quotes and trailing punctuation stripped). */
+export const pathsNamed = (issue) => [...new Set(noComments(`${issue.title ?? ""}\n${issue.body ?? ""}`).split(/[\s`'"()<>,;]+/).map((t) => t.replace(/^\.\//, "").replace(/[.:]+$/, "")).filter((t) => /^[\w.@-][\w.@*-]*(\/[\w.@*-]+)+\/?$/.test(t) && !/^https?:/.test(t)))];
+
+/** Theme of an issue from `theme_map` rules (`label:`, `path:` glob, `scope:`; the first theme in config order wins), else a title scope equal to a theme name; null when no rule classifies it. */
+export function classifyTheme(issue, themeMap = {}) {
+  const names = labelNames(issue).map((l) => l.toLowerCase()), scope = titleScope(issue.title), paths = pathsNamed(issue);
+  for (const [theme, rules] of Object.entries(themeMap)) {
+    for (const r of [].concat(rules)) {
+      const [k, ...v] = String(r).split(":"), val = v.join(":").trim();
+      if (k === "label" && names.includes(val.toLowerCase())) return { theme, via: r };
+      if (k === "scope" && scope === val.toLowerCase()) return { theme, via: r };
+      if (k === "path" && paths.some((p) => globRe(val).test(p))) return { theme, via: r };
+    }
+  }
+  const byScope = Object.keys(themeMap).find((t) => t.toLowerCase() === scope);
+  return byScope ? { theme: byScope, via: `scope:${scope}` } : null;
+}
+
+/**
+ * Classify the pool: rules first, then one `io.classify(issues, themes) → {number: theme}` call for the rest (counted).
+ * `cache` (state.themes) keeps earlier answers so a rolled-over issue costs no second call. Returns `{themes: {n: {theme, via}}, llm}`.
+ */
+export async function classifyPool(pool, watch, { classify, cache = {} } = {}) {
+  const themes = {}, rest = [];
+  for (const i of pool) {
+    const c = classifyTheme(i, watch.theme_map);
+    if (c) themes[i.number] = c; else if (cache[i.number]) themes[i.number] = cache[i.number]; else rest.push(i);
+  }
+  let llm = 0;
+  if (rest.length) {
+    let ans = null;
+    if (classify) { try { ans = await classify(rest, Object.keys(watch.theme_map ?? {})); llm = rest.length; } catch { ans = null; } }
+    for (const i of rest) { const t = ans?.[i.number]; themes[i.number] = Object.hasOwn(watch.theme_map ?? {}, t) ? { theme: t, via: "llm" } : { theme: GENERAL_THEME, via: ans ? "llm" : "unclassified" }; }
+  }
+  return { themes, llm };
+}
+
+/** The ordered `Release priorities:` list of a NORTHSTAR text (inline `a, b` or following `- a` bullets), lower-cased; [] when absent. */
+export function releasePriorities(text) {
+  const lines = String(text ?? "").split(/\r?\n/), at = lines.findIndex((l) => /^\s*(?:[-*]\s*)?\**release priorities\**:/i.test(l));
+  if (at < 0) return [];
+  const inline = lines[at].replace(/^[^:]*:\**/, "").trim();
+  if (inline) return inline.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const out = [];
+  for (const l of lines.slice(at + 1)) { const m = /^\s*(?:[-*]|\d+\.)\s+`?([\w./-]+)`?/.exec(l); if (!m) break; out.push(m[1].toLowerCase()); }
+  return out;
+}
+
+/** Theme scores, best first: Σ priority weight + age (0.1/day, max 3 per issue) + a NORTHSTAR rank bonus; ties by priorities order then name. */
+export function scoreThemes(pool, themes, now, priorities = []) {
+  const by = {};
+  for (const i of pool) (by[themes[i.number].theme] ??= []).push(i);
+  return Object.entries(by).map(([theme, issues]) => {
+    const idx = priorities.indexOf(theme.toLowerCase());
+    const score = Math.round(poolScore(issues) + issues.reduce((s, i) => s + Math.min(3, ageDays(i, now) * 0.1), 0) + (idx >= 0 ? priorities.length - idx : 0));
+    return { theme, count: issues.length, score, rank: idx >= 0 ? idx : Infinity };
+  }).sort((a, b) => b.score - a.score || a.rank - b.rank || a.theme.localeCompare(b.theme));
+}
+
+// ── the release set ─────────────────────────────────────────────────────────────────────────────────────────
+const depsOf = (i) => [...String(i.body ?? "").matchAll(/^\s*(?:[-*]\s*)?\**depends on\**:?\s*(.+)$/gim)].flatMap((m) => [...m[1].matchAll(/#(\d+)/g)].map((x) => +x[1])).filter((n) => n !== i.number);
+
+/** `issue` plus every open prerequisite, transitively (`openByNum`: all open issues); closed or unknown prerequisites are not part of it. */
+export function closure(issue, openByNum) {
+  const out = new Map();
+  const visit = (i) => { if (out.has(i.number)) return; out.set(i.number, i); for (const d of depsOf(i)) if (openByNum.has(d)) visit(openByNum.get(d)); };
+  visit(issue);
+  return [...out.values()];
+}
+
+/**
+ * The release of `theme`: its issues (immediate first, then priority, then age) each with its `Depends on` closure, in order, while
+ * the set fits `max`; an issue whose closure does not fit stays out (rolls over). Prerequisites from another theme are marked `pulled`.
+ * Returns `{set: [issue], pulled: [{number, theme, for}], excluded: [{number, reason}]}`.
+ */
+export function pickRelease(theme, pool, themes, openByNum, watch, now) {
+  const max = watch.max_release_issues ?? 40;
+  const mine = pool.filter((i) => themes[i.number].theme === theme)
+    .sort((a, b) => (isImmediate(b, watch.immediate) - isImmediate(a, watch.immediate)) || weightOf(b) - weightOf(a) || ageDays(b, now) - ageDays(a, now) || a.number - b.number);
+  const set = new Map(), pulled = [], excluded = [];
+  for (const i of mine) {
+    if (set.has(i.number)) continue;
+    const add = closure(i, openByNum).filter((x) => !set.has(x.number));
+    if (set.size + add.length > max) { excluded.push({ number: i.number, reason: `release cap ${max}` }); continue; }
+    for (const x of add) { set.set(x.number, x); if (themes[x.number]?.theme !== theme && !mine.includes(x)) pulled.push({ number: x.number, theme: themes[x.number]?.theme ?? classifyTheme(x, watch.theme_map)?.theme ?? "outside pool", for: i.number }); }
+  }
+  for (const i of pool) if (!set.has(i.number) && !excluded.some((e) => e.number === i.number)) excluded.push({ number: i.number, reason: themes[i.number].theme === theme ? "release cap" : `theme ${themes[i.number].theme}` });
+  return { set: [...set.values()], pulled, excluded };
+}
+
+/**
+ * The decision for a pool: `{fired, ranking, theme, release, forced, below}`. `release` is null (nothing cut) when no trigger fires.
+ * An immediate trigger forces the theme of its highest-priority issue and ships only that theme (plus its prerequisites).
+ */
+export function decideRelease({ pool, openByNum, themes, watch, now, priorities = [] }) {
+  const fired = triggers(pool, watch, now), ranking = pool.length ? scoreThemes(pool, themes, now, priorities) : [];
+  const below = ranking.filter((r) => r.count < (watch.threshold?.min_issues ?? Infinity)).map((r) => `${r.theme} pool ${r.count} < threshold`);
+  if (!fired.length) return { fired, ranking, theme: null, release: null, forced: false, below };
+  const imm = pool.filter((i) => isImmediate(i, watch.immediate)).sort((a, b) => weightOf(b) - weightOf(a) || a.number - b.number);
+  const forced = imm.length > 0, theme = forced ? themes[imm[0].number].theme : ranking[0].theme;
+  return { fired, ranking, theme, release: pickRelease(theme, pool, themes, openByNum, watch, now), forced, below: below.filter((b) => !b.startsWith(`${theme} `)) };
+}
+
+/** `would cut: stealth (14 issues, score 46; security pool 1 < threshold)` plus triggers and per-issue theme lines. */
+export function formatDryRun(d, pool, themes) {
+  const lines = [];
+  if (!d.release) lines.push(`would not cut: ${pool.length} pooled, no trigger fired`);
+  else {
+    const sc = d.ranking.find((r) => r.theme === d.theme)?.score;
+    lines.push(`would cut: ${d.theme} (${d.release.set.length} issues, score ${sc}${d.below.length ? `; ${d.below.join("; ")}` : ""})`);
+    lines.push(`  triggers: ${d.fired.map((f) => `${f.kind} (${f.detail})`).join(", ")}${d.forced ? " [immediate: theme forced]" : ""}`);
+    lines.push(`  set: ${d.release.set.map((i) => `#${i.number}`).join(" ")}`);
+    if (d.release.pulled.length) lines.push(`  pulled prerequisites: ${d.release.pulled.map((p) => `#${p.number} (${p.theme}, for #${p.for})`).join(", ")}`);
+  }
+  lines.push("  theme scores: " + (d.ranking.map((r) => `${r.theme}=${r.score} (${r.count})`).join(", ") || "(empty pool)"));
+  for (const i of pool) lines.push(`  #${i.number} ${themes[i.number].theme} [${themes[i.number].via}]${d.release?.set.some((s) => s.number === i.number) ? "" : " (stays pooled)"}`);
+  return lines.join("\n");
+}
+
+/** The trusted `FORGE:RELEASE_PLAN` comment: theme, reasons, included and excluded issues, cited policy. */
+export function releasePlanComment({ theme, tag, decision, policy, now }) {
+  const r = decision.release, data = { v: 1, theme, tag, at: new Date(now).toISOString(), included: r.set.map((i) => i.number), pulled: r.pulled, excluded: r.excluded, triggers: decision.fired, policy: policy ?? null };
+  return [`<!-- FORGE:RELEASE_PLAN ${JSON.stringify(data)} -->`, `## Release plan: ${theme} (${tag})`,
+    `**Why:** ${decision.fired.map((f) => `${f.kind} (${f.detail})`).join(", ")}${decision.forced ? "; immediate trigger, theme forced" : ""}`,
+    `**Policy:** ${policy ?? "none (score, then theme name)"}`,
+    `**Included:** ${r.set.map((i) => `#${i.number}`).join(" ")}`,
+    ...(r.pulled.length ? [`**Pulled prerequisites:** ${r.pulled.map((p) => `#${p.number} (${p.theme}, for #${p.for})`).join(", ")}`] : []),
+    `**Excluded (stay pooled):** ${r.excluded.map((e) => `#${e.number} (${e.reason})`).join(", ") || "none"}`,
+    "Promotion to the default branch stays human-only; the watch opens the deploy PR and never merges it."].join("\n");
+}
+
+// ── the tick ─────────────────────────────────────────────────────────────────────────────────────────────────
+const isoDate = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+/**
+ * One release-mode pass. Settles the active release (opens the deploy PR once its batch reports), else pools, decides and cuts.
+ * `listOpen()→[issue]` all open issues, `eligible(issue)` selector + trust + unclaimed, `claim(n)→bool` repo-wide claim,
+ * `laneFor(issue)`, `dagOrder(issues)`, `policy {path,text}`. `dryRun` writes nothing and returns `{state, decision, pool, themes}`.
+ */
+export async function releaseTick({ watch, repo, io, state, defaults = [], listOpen, eligible, claim, laneFor, dagOrder, policy = {}, dryRun = false }) {
+  const now = io.now(), gh = async (a) => String(await io.gh(a));
+  state.started ??= now;
+  const rel = state.release;
+  if (rel && !dryRun) {
+    for (const n of [...state.inflight]) if (JSON.parse(await gh(["issue", "view", String(n), "-R", repo, "--json", "state"])).state === "CLOSED") { state.inflight = state.inflight.filter((x) => x !== n); state.merged.push(n); state.verified.push(n); }
+    if (!io.batch.reported(rel.batch)) return state;
+    state.inflight.forEach((n) => state.failed.push(n)); state.inflight = [];
+    if (!rel.deployPr) {
+      const base = defaults[0];
+      if (!base) throw new Error("no default branch known; cannot open the deploy PR");
+      const open = JSON.parse(await gh(["pr", "list", "-R", repo, "--head", rel.lane, "--base", base, "--state", "open", "--json", "number"]));
+      rel.deployPr = open[0]?.number ?? (+(/(\d+)\s*$/.exec(await gh(["pr", "create", "-R", repo, "--base", base, "--head", rel.lane, "--title", `release(${rel.theme}): ${rel.tag}`,
+        "--body", `Themed release **${rel.theme}** (${rel.tag}).\n\nIssues: ${rel.issues.map((n) => `#${n}`).join(" ")}\nMerged: ${state.merged.filter((n) => rel.issues.includes(n)).map((n) => `#${n}`).join(" ") || "none"}\nFailed: ${state.failed.filter((n) => rel.issues.includes(n)).map((n) => `#${n}`).join(" ") || "none"}\n\nPromotion is human-only: the issue watch opened this PR and never merges it.`]))?.[1]) || true);
+    }
+    (state.releases ??= []).push(rel); state.release = null;
+  }
+  if (state.release && dryRun) return { state, decision: null, pool: [], themes: {} };
+  const capped = (watch.max_issues && state.claimed.length >= watch.max_issues) || (watch.until && now >= Date.parse(watch.until));
+  if (capped && !dryRun) { state.phase = "done"; return state; }
+
+  const open = await listOpen(), openByNum = new Map(open.map((i) => [i.number, i]));
+  const pool = open.filter(eligible).sort((a, b) => a.number - b.number);
+  const { themes, llm } = await classifyPool(pool, watch, { classify: io.classify, cache: state.themes });
+  const decision = decideRelease({ pool, openByNum, themes, watch, now, priorities: releasePriorities(policy.text) });
+  if (dryRun) return { state, decision, pool, themes };
+  state.llm = (state.llm ?? 0) + llm;
+  state.themes = { ...(state.themes ?? {}), ...Object.fromEntries(Object.entries(themes).filter(([, v]) => v.via === "llm").map(([n, v]) => [n, v])) };
+  state.pool = pool.map((i) => i.number);
+  if (!decision.release?.set.length) return state;
+
+  const taken = [];
+  // Only pool members are claimed: a Depends-on prerequisite that never passed `eligible` (an outsider's issue, an excluded label)
+  // is not launched by this watch; its dependent waits on the edge in the batch (release #4820 SPEC-2).
+  const inPool = new Set(pool.map((i) => i.number));
+  for (const i of dagOrder(decision.release.set)) { if (!inPool.has(i.number)) continue; if (watch.max_issues && state.claimed.length + taken.length >= watch.max_issues) break; if (claim(i.number)) taken.push(i); }
+  if (!taken.length) return state;
+  const lane = taken.map((i) => laneFor(i))[0], tag = `${milestoneSlug(decision.theme) || decision.theme}-${isoDate(now)}`, nums = taken.map((i) => i.number);
+  const plan = releasePlanComment({ theme: decision.theme, tag, decision: { ...decision, release: { ...decision.release, set: taken } }, policy: policy.path, now });
+  const tracker = watch.tracker ?? nums[0];
+  await gh(["issue", "comment", String(tracker), "-R", repo, "--body", plan]);
+  if (watch.milestone && watch.milestone !== "none") {
+    const title = `release/${tag}`;
+    // A second cut of the same theme on the same day reuses the milestone: GitHub answers 422 already_exists (release #4820 CONC-1).
+    try { await gh(["api", `repos/${repo}/milestones`, "-f", `title=${title}`]); } catch (e) { if (!/already_exists|HTTP 422/i.test(String(e?.stderr ?? e?.message ?? e))) throw e; }
+    for (const n of nums) await gh(["issue", "edit", String(n), "-R", repo, "--milestone", title]);
+  } else {
+    const label = `release:${tag}`;
+    await gh(["label", "create", label, "-R", repo, "--force"]);
+    for (const n of nums) await gh(["issue", "edit", String(n), "-R", repo, "--add-label", label]);
+  }
+  for (const i of taken) { state.claimed.push(i.number); state.inflight.push(i.number); state.lanes[i.number] = lane; }
+  const batch = await io.batch.start(nums, watch.parallel, lane);
+  state.release = { theme: decision.theme, tag, lane, batch, issues: nums, tracker, at: now, deployPr: null };
+  return state;
+}