forgedock 1.37.0 → 1.38.1

package/bin/lean/lean.test.mjs

@@ -391,6 +391,21 @@ describe("core work-on", () => {
     assert.doesNotMatch(p, /complete what is missing/);
   });
 
+  it("#4786: a remote lane branch holding only .forge-lean scratch plans fresh and drops the scratch", async () => {
+    const w = world({ prList: [], remote: "abc\trefs/heads/feat/issue-7-lean", changed: [".forge-lean/contract.json", ".forge-lean/checkpoint.json"] });
+    await run(w);
+    assert.doesNotMatch(builders(w)[0][4], /This is a rerun/);
+    assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "rm" && c.includes(".forge-lean")), "scratch removed from the branch");
+    assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "commit" && c.join(" ").includes("drop stale .forge-lean scratch")));
+  });
+
+  it("#4786: a remote lane branch with a code change besides scratch still resumes", async () => {
+    const w = world({ prList: [], remote: "abc\trefs/heads/feat/issue-7-lean", changed: [".forge-lean/contract.json", "src/foo.js"] });
+    await run(w);
+    assert.match(builders(w)[0][4], /This is a rerun/);
+    assert.ok(!w.calls.some((c) => c[0] === "git" && c[1] === "rm" && c.includes(".forge-lean")));
+  });
+
   it("a reviewer that returns no JSON twice ends review.no_verdict", async () => {
     const w = world({ reviews: ["no json", "still none"] });
     const r = await run(w);
@@ -419,6 +434,54 @@ describe("core work-on", () => {
     assert.ok(!w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN")));
   };
 
+  // #4730: owner step + agent-doable remainder, and duplicate owner asks
+  const ownerWorld = (block, o = {}, existing = null) => {
+    const w = depWorld({ changed: [], result: { status: "blocked", summary: "sign the contract", block }, ...o }, {});
+    const gh = w.io.gh;
+    w.io.gh = async (a) => {
+      if (a[0] === "issue" && a[1] === "list" && existing && a.some((x) => String(x).includes("FORGE:ASK"))) return JSON.stringify([existing]);
+      if (a[0] === "issue" && a[1] === "list") return JSON.stringify(w.listed ?? []);
+      return gh(a);
+    };
+    return w;
+  };
+  it("#4730 a human block with a remainder re-queues it as its own issue; only the owner step keeps needs-human", async () => {
+    const w = ownerWorld({ kind: "human", why: "credentials", remainder: [{ title: "wire the client", body: "do the code part" }, { title: "", body: "dropped" }] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(w.created.length, 1);
+    const body = w.created[0][w.created[0].indexOf("--body") + 1];
+    assert.match(body, /\*\*Parent\*\*: #7/); assert.match(body, /FORGE:REMAINDER of=#7/);
+    assert.ok(!w.created[0].includes("needs-human"));
+    assert.ok(w.edits.some((e) => e.includes("--add-label") && e.includes("needs-human")));
+    assert.ok(w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN") && c.includes("re-queued as #201")));
+  });
+  it("#4730 a rerun reuses the remainder issue it already filed", async () => {
+    const w = ownerWorld({ kind: "human", why: "credentials", remainder: [{ title: "wire the client", body: "x" }] });
+    const key = (await import("./needs-human-premise.mjs")).askKey("wire the client");
+    w.listed = [{ number: 150, body: `x\n<!-- FORGE:REMAINDER of=#7 key=${key} -->` }];
+    await run(w);
+    assert.equal(w.created.length, 0);
+    assert.ok(w.comments.some((c) => c.includes("re-queued as #150")));
+  });
+  it("#4730 a human block without a remainder files nothing", async () => {
+    const w = ownerWorld({ kind: "human", why: "credentials" });
+    assert.equal((await run(w)).terminalReason, "needs-human");
+    assert.equal(w.created.length, 0);
+  });
+  it("#4730 an issue whose only content is an existing owner ask is closed as a duplicate; extra content only links", async () => {
+    const { askKey } = await import("./needs-human-premise.mjs");
+    const existing = { number: 40, comments: [{ author: { login: "rapiercraft-forgedock" }, body: `<!-- FORGE:ASK key=${askKey("Builder is blocked (credentials): sign the contract")} -->\n## Owner ask\n{}` }] };
+    const dup = ownerWorld({ kind: "human", why: "credentials" }, { body: "sign the contract" }, existing);
+    const r = await run(dup);
+    assert.equal(r.terminalReason, "invalid");
+    assert.ok(dup.closed.some((c) => c.includes("not planned") && c.join(" ").includes("#40")));
+    noNeedsHuman(dup);
+    const more = ownerWorld({ kind: "human", why: "credentials" }, { body: "sign the contract and then also rework the importer" }, existing);
+    assert.equal((await run(more)).terminalReason, "needs-human");
+    assert.equal(more.closed.length, 0);
+  });
+
   it("#4124 a builder block naming an open issue ends dependency-open with dependencies, not needs-human", async () => {
     const w = depWorld({ changed: [], result: { status: "blocked", summary: "needs #34927 first", block: { kind: "dependency", issues: ["#3", 7] } } },
       { 3: { state: "OPEN", labels: [] } });
@@ -659,6 +722,30 @@ describe("core work-on", () => {
     assert.equal(w2.calls.filter((c) => c[1] === "worktree" && c[2] === "add").length, 5);
   });
 
+  it("#4785 a remote lane whose frozen validate commands name a declared host capability ends env.capability_remote before building", async () => {
+    const contract = { ...CONTRACT, validate: [...CONTRACT.validate, { id: "V2", command: "promtool test rules r.yml" }] };
+    const remote = { placement: { where: "remote", reason: "mode remote" }, hostCaps: { hostCapabilities: ["promtool"] } };
+    const dir = tmpDir("lean-4785-");
+    const w = world({ contract });
+    const r = await run(w, { dir, ...remote });
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(r.code, "env.capability_remote");
+    assert.equal(builders(w).length, 1); // the plan session only: no implementation turn
+    assert.match(w.comments.map((c) => c.body ?? c).join("\n"), /promtool[\s\S]*V2/);
+    // local placement, no declared capability, or a recovery run: unchanged
+    assert.equal((await run(world({ contract }), { ...remote, placement: { where: "local", reason: "x" } })).terminalReason, "merged");
+    assert.equal((await run(world({ contract }), { ...remote, hostCaps: { hostCapabilities: ["sops"] } })).terminalReason, "merged");
+  });
+
+  it("#4778 a relayed host capability does not end the remote lane before building; a failed relay still recovers locally", async () => {
+    const contract = { ...CONTRACT, validate: [...CONTRACT.validate, { id: "V2", command: "promtool test rules r.yml" }] };
+    const remote = { placement: { where: "remote", reason: "mode remote" }, hostCaps: { hostCapabilities: ["promtool"] } };
+    assert.equal((await run(world({ contract }), { ...remote, relayCaps: ["promtool"] })).terminalReason, "merged");
+    assert.equal((await run(world({ contract }), { ...remote, relayCaps: ["sops"] })).code, "env.capability_remote");
+    const blocked = world({ result: { status: "blocked", summary: "promtool relay unavailable", block: { kind: "human", why: "credentials" } } });
+    assert.equal((await run(blocked, { ...remote, relayCaps: ["promtool"] })).code, "env.capability_remote");
+  });
+
   it("needs-human terminals carry a specific outcome code, never unclassified", async () => {
     const code = async (w, extra) => {
       const dir = tmpDir("lean-code-");
@@ -862,6 +949,7 @@ describe("conformance gate (frozen contract, precheck, structured review)", () =
     const r = await run(w);
     assert.equal(r.code, "contract.invalid");
     assert.match(builders(w)[1][4], /R1: quote is not verbatim from the issue/);
+    assert.equal(r.quoteMismatch, true, "#4789: quote-only problems are recoverable");
     assert.equal(builders(w).length, 2, "plan + one correction, no implement call");
     assert.match(nhBody(w), /still invalid after one correction/);
     const w2 = world({ contract: bad1, fixedContract: CONTRACT });
@@ -1660,7 +1748,7 @@ describe("hotspot prevention (forge#4195): plan facts, build rule, unexempted gr
     assert.equal(hotspotBuildRule(null), ""); assert.equal(hotspotBuildRule(facts([], { enabled: false })), "");
     const plan = builderPlanPrompt(7) + hotspotPlanNote(facts([HOT, { ...HOT, path: "a/b.py" }, { ...HOT, path: "c/d.py" }]));
     // 1850: #4404 (verify out_of_band) and #4396 (split size rule) grew the plan prompt to ~1803 tokens on CI paths; 1900: #4589 (check timeout is not a block, one block-rule line). 2050: #4724 (deferred-row bucket rule).
-    assert.ok(approxTokens(plan) <= 2050, `plan prompt with hotspots is ${approxTokens(plan)} tokens`);
+    assert.ok(approxTokens(plan) <= 2150, `plan prompt with hotspots is ${approxTokens(plan)} tokens`);
     assert.ok(approxTokens(builderImplementPrompt() + hotspotBuildRule(facts([]))) <= 1650); // 1600: #4591 (never hand-name migration files) and #4596 (i18n translate rule), one line each; 1650: #4726 (e2e rule)
   });
 
@@ -2096,7 +2184,7 @@ describe("comment templates", () => {
 
   it("plan and implement prompts carry the stage templates and the contract schema within budget", () => {
     const plan = builderPlanPrompt(7), impl = builderImplementPrompt();
-    assert.ok(approxTokens(plan) <= 1950, `plan prompt is ${approxTokens(plan)} tokens`); // 1950: #4724 (deferred-row bucket rule)
+    assert.ok(approxTokens(plan) <= 2050, `plan prompt is ${approxTokens(plan)} tokens`); // 2050: #4769 (activation-row rule); 2000: #4730 (owner-step remainder); 1950: #4724 (deferred-row bucket rule)
     assert.ok(approxTokens(impl) <= 1650, `implement prompt is ${approxTokens(impl)} tokens`); // 1650: #4726 e2e rule; 1550: #4596 i18n translate rule
     for (const h of ["### What Was Claimed", "### What We Found", "### Root Cause", "### Affected Files", "### Sibling Sweep", "### History", "### Recommendation", "### Related Issues",
       "investigation.md", "contract.json", "PLANNING ONLY", '"requirements"', '"deliverables"', '"preserve"', '"validate"', "verbatim", "defer", "post-deploy"]) assert.ok(plan.includes(h), h);
@@ -2560,7 +2648,7 @@ describe("orchestrate", () => {
       gh: async (a) => {
         if (a[0] === "repo" && a[1] === "view") return "main\n";
         if (a.includes("milestone")) return JSON.stringify({ milestone: milestones[a[2]] ? { title: milestones[a[2]] } : null });
-        return JSON.stringify({ body: a[2] === "1" ? "**Depends on**: #2" : "" });
+        return JSON.stringify({ body: a[2] === "1" ? "**Depends on**: #2" : "", authorAssociation: "OWNER" });
       },
       git: async (a) => (a[0] === "ls-remote" && ["refs/heads/staging", "refs/heads/milestone/m-one"].includes(a.at(-1)) ? "abc\tref\n" : ""),
     };
@@ -2749,7 +2837,7 @@ describe("orchestrate maintenance budget (#4197)", () => {
       // No maintenance scan without the budget; labels (host priority, #4191) ride on the body call, never a call of their own.
       // #4399: the batch-start acceptance-probe sweep (`forge-probe` search) is not a maintenance scan.
       assert.ok(calls.some((c) => c.startsWith("issue list") && c.includes("forge-probe")), calls.join("\n"));
-      assert.ok(!calls.some((c) => (c.startsWith("issue list") && !c.includes("forge-probe")) || c.endsWith("--json labels")), calls.join("\n"));
+      assert.ok(!calls.some((c) => (c.startsWith("issue list") && !c.includes("forge-probe") && !c.includes("--label blocked")) || c.endsWith("--json labels")), calls.join("\n"));
       ran.length = 0; calls.length = 0;
       const res = await orchestrateFromCli(["1", "--repo", "o/r", "--no-prefilter"], { ...mk(), maintenance: { share: 0.5, whenIdle: true, labels: ["maintenance"] } });
       assert.deepEqual(ran, [1, 9]);
@@ -4173,6 +4261,24 @@ describe("large diffs never reach argv (#4129)", () => {
     assert.equal(seen[1].args[1], "go"); assert.equal(seen[1].input, undefined);
   });
 
+  it("#4763 promptGoesViaStdin is platform-aware and counts the other argv", async () => {
+    const { promptGoesViaStdin, runCliBackend } = await import("../runner.mjs");
+    assert.equal(promptGoesViaStdin("x".repeat(40 * 1024), [], "win32"), true);
+    assert.equal(promptGoesViaStdin("x".repeat(10 * 1024), ["--print"], "win32"), false);
+    assert.equal(promptGoesViaStdin("x".repeat(16 * 1024 - 10), ["--a".repeat(10)], "win32"), true);
+    assert.equal(promptGoesViaStdin("x".repeat(40 * 1024), [], "linux"), false);
+    assert.equal(promptGoesViaStdin("x".repeat(65 * 1024), [], "linux"), true);
+    const prev = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", { value: "win32" });
+    try {
+      const seen = [];
+      runCliBackend({ spec: { name: "t" }, userMessage: "y".repeat(40 * 1024), systemPrompt: "sys", args: ["1"], cwd: tmpDir("core-4763-"), logger: { log() {} },
+        spawnFn: (_b, args, o2) => { seen.push({ args, input: o2.input }); return { status: 0, stdout: "{}", stderr: "" }; } });
+      assert.equal(seen[0].input.length, 40 * 1024);
+      assert.ok(!seen[0].args.some((x) => x.length > 1000));
+    } finally { Object.defineProperty(process, "platform", prev); }
+  });
+
   it("runCliBackendAsync pipes a 300 KiB prompt to a real child (no E2BIG)", async () => {
     const { writeFileSync, chmodSync } = await import("node:fs");
     const { runCliBackendAsync } = await import("../runner.mjs");
@@ -5619,6 +5725,22 @@ describe("enumerating tests + sequence numbers at hand-off (#4322)", () => {
       assert.match(traj(w).at(-1), /renumbered deterministically \(no builder\): db\/0007_usage\.sql → db\/0008_usage\.sql/);
     });
 
+    it("#4732: a collision plus an unrelated text conflict is base-synced (builder resolves only that file) and then renumbered by the engine; open-lane numbers reach the renumber", async () => {
+      const NON = "non-sequence conflict: .env.example";
+      const w = dworld({ seq: [COLL, []], mergeResults: ["conflict"], conflictFiles: [".env.example"], det: [{ unsupported: NON, nonSequence: [".env.example"] }, { ok: true, moves: MOVES, commit: "d".repeat(40) }], resolve: { remaining: [".env.example"] } });
+      w.io.sequenceOpenNumbers = async (x) => { w.openArgs = x; return [9]; };
+      const r = await run(w);
+      assert.equal(r.terminalReason, "merged");
+      assert.equal(w.renumbers.length, 2, "renumber, sync, renumber again");
+      assert.ok(w.renumbers[1].laneRef, "second renumber reads the pre-merge lane head");
+      assert.deepEqual(await w.renumbers[0].openNumbers({ dir: "db" }), [9]);
+      assert.equal(w.openArgs.dir, "db");
+      assert.equal(builders(w).length, 3, "plan + implement + the conflict resolution; no builder renumber");
+      assert.match(builders(w)[2][4], /conflicts in: \.env\.example[\s\S]*do not renumber/);
+      assert.deepEqual(w.resolveArgs.files, [".env.example"]);
+      assert.equal(w.resolveArgs.partial, true);
+    });
+
     it("#4526: the renumber gets a reserve hook bound to (repo, lane, issue), and the run's reservations are dropped at finish", async () => {
       const w = dworld({ seq: [COLL, []] }), reserved = [], unreserved = [];
       w.io.sequenceLease.reserve = async (x) => { reserved.push(x); return { numbers: [9] }; };
@@ -6510,7 +6632,7 @@ describe("#4395 lane profile", () => {
       assert.match(p, /Issue independent read-only calls \(reads, greps, git log\/blame, gh\) in the same turn or one shell call\./);
       assert.match(p, /Read each file's ranges once .* and keep notes; don't re-read it\./);
     }
-    assert.ok(approxTokens(builderImplementPrompt()) <= 1650 && approxTokens(builderPlanPrompt(7)) <= 1950);
+    assert.ok(approxTokens(builderImplementPrompt()) <= 1650 && approxTokens(builderPlanPrompt(7)) <= 2050);
   });
 
   it("runCliBackendAsync reports the first stream turn's context as baselineTokens; makeLeanRunner drops it on resume", async () => {

package/bin/lean/needs-human-premise.mjs

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * needs-human premises and the owner-ask registry (#4725).
+ *
+ * A blocker that names an external fact records it as a machine-checkable predicate, `Premise: <kind>:<args>`:
+ *   issue-closed:<N>            issue #N is closed
+ *   date-after:<ISO date>       now is at or past the date
+ *   pkg-version:<name>@<ver>    the registry's latest version of <name> is >= <ver> (`io.pkgVersion(name)`)
+ * It is re-evaluated before the label is applied (`needsHuman`, lean.mjs) and on the daemon timer (`sweepPremises`): a predicate
+ * that holds clears needs-human so the next scheduler pass picks the issue up. An unknown answer (unreadable, no resolver) never clears.
+ *
+ * Every owner ask is recorded once on GitHub as a `FORGE:ASK key=<hash>` annotation ({ask, unblocks:[issues]}); a new needs-human
+ * with the same normalized ask links to the existing entry. GitHub is the register: nothing here is a local cache. Pure apart from `io`.
+ */
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { isTrustedIssueComment } from "./prefilter.mjs";
+
+export const PREMISE_MARKER = "FORGE:PREMISE";
+export const ASK_MARKER = "FORGE:ASK";
+const PREMISE_RE = /^\s*Premise:\s*(issue-closed|date-after|pkg-version):(\S+)\s*$/im;
+
+/** The first `Premise:` line of a text as `{kind, arg}`, or null. */
+export function parsePredicate(text) {
+  const m = PREMISE_RE.exec(String(text ?? ""));
+  if (!m) return null;
+  const kind = m[1].toLowerCase(), arg = m[2];
+  if (kind === "issue-closed") return /^#?\d+$/.test(arg) ? { kind, arg: String(Number(arg.replace("#", ""))) } : null;
+  if (kind === "date-after") return Number.isFinite(Date.parse(arg)) ? { kind, arg } : null;
+  return /^[^@\s]+@\d+(\.\d+)*[\w.+-]*$/.test(arg) ? { kind, arg } : null;
+}
+
+export const formatPredicate = (p) => (p ? `Premise: ${p.kind}:${p.arg}` : "");
+
+/** Numeric dotted-version compare (pre-release tails are ignored): -1 | 0 | 1. */
+export function comparePremiseVersions(a, b) {
+  const pa = String(a).split(/[.-]/).map((x) => parseInt(x, 10) || 0), pb = String(b).split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) { const d = (pa[i] ?? 0) - (pb[i] ?? 0); if (d) return d < 0 ? -1 : 1; }
+  return 0;
+}
+
+/** Production `io.pkgVersion`: the npm registry's latest version of `name`, or null when unreachable. */
+export function registryPkgVersion(name) {
+  return new Promise((resolve) => {
+    if (!/^(@[\w.-]+\/)?[\w.-]+$/.test(String(name))) return resolve(null);
+    execFile("npm", ["view", String(name), "version"], { timeout: 15000 }, (err, out) => resolve(err ? null : String(out).trim() || null));
+  });
+}
+
+/** true | false | null (unknown). Never throws. */
+export async function evalPredicate(p, { repo, io, now = Date.now() } = {}) {
+  try {
+    if (!p) return null;
+    if (p.kind === "date-after") return now >= Date.parse(p.arg);
+    if (p.kind === "issue-closed") {
+      const v = JSON.parse(String(await io.gh(["issue", "view", p.arg, "-R", repo, "--json", "state"])));
+      const s = String(v?.state ?? "").toUpperCase();
+      return s === "CLOSED" ? true : s === "OPEN" ? false : null;
+    }
+    if (p.kind === "pkg-version") {
+      if (typeof io?.pkgVersion !== "function") return null;
+      const at = p.arg.lastIndexOf("@");
+      const cur = await io.pkgVersion(p.arg.slice(0, at));
+      return typeof cur === "string" && cur ? comparePremiseVersions(cur, p.arg.slice(at + 1)) >= 0 : null;
+    }
+  } catch { /* unknown */ }
+  return null;
+}
+
+/** The dependencies of `deps` whose issue is closed (`stateOf(n)` → "CLOSED"|"OPEN"|other): satisfied edges, never blockers. */
+export async function closedEdges(deps, stateOf) {
+  const out = [];
+  for (const d of deps ?? []) {
+    let s = "";
+    try { s = String((await stateOf(d)) ?? "").toUpperCase(); } catch { s = ""; }
+    if (s === "CLOSED") out.push(d);
+  }
+  return out;
+}
+
+export const closedEdgeNote = (closed) => (closed?.length ? `Note: ${closed.map((n) => `#${n}`).join(", ")} ${closed.length > 1 ? "are" : "is"} closed, so ${closed.length > 1 ? "those" : "that"} \`Depends on\` edge${closed.length > 1 ? "s are" : " is"} satisfied and not a blocker.` : "");
+
+/** The ask text lower-cased with issue refs, punctuation and spacing removed: the dedup key's input. */
+export function normalizeAsk(text) {
+  return String(text ?? "").toLowerCase().replace(/#\d+/g, " ").replace(/[^a-z0-9]+/g, " ").trim();
+}
+export const askKey = (text) => createHash("sha256").update(normalizeAsk(text)).digest("hex").slice(0, 12);
+
+const askComment = (key, ask, unblocks) => `<!-- ${ASK_MARKER} key=${key} -->\n## Owner ask\n${JSON.stringify({ ask: String(ask).slice(0, 500), unblocks })}`;
+const readAsk = (body) => { try { return JSON.parse(String(body).split("\n").slice(2).join("\n")); } catch { return null; } };
+
+/**
+ * Records `ask` for `issue` once. Returns `{key, existing}`: `existing` is the issue holding the entry (the new issue is added to its
+ * `unblocks`, nothing new is created) or null when this issue now holds it. Fail-open: an unreadable registry means a fresh entry.
+ */
+export async function registerAsk({ repo, io, issue, ask }) {
+  const key = askKey(ask);
+  if (!normalizeAsk(ask)) return { key, existing: null };
+  try {
+    const list = JSON.parse(String(await io.gh(["issue", "list", "-R", repo, "--state", "open", "--label", "needs-human", "--limit", "100", "--search", `"${ASK_MARKER} key=${key}" in:comments`, "--json", "number,comments"])));
+    for (const i of Array.isArray(list) ? list : []) {
+      if (i?.number === issue) continue;
+      const c = (i.comments ?? []).find((x) => String(x?.body ?? "").includes(`${ASK_MARKER} key=${key}`) && isTrustedIssueComment(x)); // only trusted authors may register an ask
+      if (!c) continue;
+      const cur = readAsk(c.body) ?? { ask, unblocks: [i.number] };
+      const unblocks = [...new Set([...(cur.unblocks ?? []), i.number, issue])].sort((a, b) => a - b);
+      await io.gh(["issue", "comment", String(i.number), "-R", repo, "--body", askComment(key, cur.ask ?? ask, unblocks)]);
+      return { key, existing: i.number, unblocks };
+    }
+  } catch { /* fail-open */ }
+  return { key, existing: null, entry: askComment(key, ask, [issue]) };
+}
+
+/**
+ * The needs-human issues whose recorded premise now holds lose the label (and `needs-human:external`) with a comment; the next
+ * scheduler pass picks them up. Rows: cleared | still-blocked | unknown | error. Never throws.
+ */
+export async function sweepPremises({ repo, io, now = Date.now(), dryRun = false, onResult = null } = {}) {
+  const rows = [];
+  let list = [];
+  try { list = JSON.parse(String(await io.gh(["issue", "list", "-R", repo, "--state", "open", "--label", "needs-human", "--limit", "100", "--json", "number,comments"]))); } catch { return rows; }
+  for (const i of (Array.isArray(list) ? list : []).sort((a, b) => a.number - b.number)) {
+    // Only the current block counts: the newest trusted FORGE:NEEDS_HUMAN comment, and only when it carries the premise. A
+    // later block without one (credentials, spend, ci.red) supersedes an older premise; an untrusted premise never counts.
+    const c = [...(i.comments ?? [])].reverse().find((x) => String(x?.body ?? "").includes("FORGE:NEEDS_HUMAN") && isTrustedIssueComment(x));
+    if (!c || !String(c.body).includes(`${PREMISE_MARKER} `)) continue;
+    let row;
+    try {
+      const p = parsePredicate(String(c.body).replace(/<!--\s*FORGE:PREMISE\s+(.*?)\s*-->/s, "Premise: $1"));
+      const held = await evalPredicate(p, { repo, io, now });
+      row = { issue: i.number, outcome: held === true ? "cleared" : held === false ? "still-blocked" : "unknown", predicate: formatPredicate(p) };
+      if (held === true && !dryRun) {
+        await io.gh(["issue", "edit", String(i.number), "-R", repo, "--remove-label", "needs-human", "--remove-label", "needs-human:external"]);
+        await io.gh(["issue", "comment", String(i.number), "-R", repo, "--body", `## Premise no longer holds\n\`${formatPredicate(p)}\` is now true: \`needs-human\` was cleared and the issue is back in the queue.`]);
+      }
+    } catch (e) { row = { issue: i.number, outcome: "error", detail: String(e?.message ?? e).slice(0, 160) }; }
+    rows.push(row);
+    try { if (!dryRun) await onResult?.(row); } catch { /* an event sink never fails the sweep */ }
+  }
+  return rows;
+}
+
+/** The marker line a needs-human comment carries so the sweep can re-read the predicate. */
+export const premiseAnnotation = (p) => (p ? `<!-- ${PREMISE_MARKER} ${p.kind}:${p.arg} -->` : "");
+
+const strip = (t) => String(t ?? "").replace(/<!--[\s\S]*?-->/g, " ").replace(/^\s*\**(parent|depends on)\**\s*:.*$/gim, " ");
+/** #4730: true when an issue's content (markers and Parent/Depends lines ignored) is nothing beyond `ask`: strict normalized equality of the body, or of the title when the body is empty. */
+export function onlyAsk(title, body, ask) {
+  const a = normalizeAsk(ask), b = normalizeAsk(strip(body));
+  return Boolean(a) && (b ? b === a : normalizeAsk(title) === a);
+}
+
+export const REMAINDER_MARKER = "FORGE:REMAINDER";
+/**
+ * #4730: files the agent-doable remainder of an owner-blocked lane as its own issues (no needs-human, `Parent: #N`). Idempotent: an
+ * item whose `FORGE:REMAINDER of=#N key=<hash>` marker already exists on an issue is reused. Returns the issue numbers, in item order.
+ */
+export async function fileRemainder({ repo, io, issue, items, milestone = null }) {
+  const out = [];
+  for (const it of items ?? []) {
+    const key = askKey(it.title), mark = `<!-- ${REMAINDER_MARKER} of=#${issue} key=${key} -->`;
+    let n = null;
+    try {
+      const list = JSON.parse(String(await io.gh(["issue", "list", "-R", repo, "--state", "all", "--limit", "20", "--search", `"${REMAINDER_MARKER} of=#${issue} key=${key}" in:body`, "--json", "number,body"])));
+      n = (Array.isArray(list) ? list : []).find((i) => String(i?.body ?? "").includes(mark))?.number ?? null;
+    } catch { /* fail-open: file it */ }
+    if (n == null) {
+      const body = `${it.body.trim()}\n\n**Parent**: #${issue}\n${mark}`;
+      const res = String(await io.create(["issue", "create", "-R", repo, "--title", it.title, "--body", body, ...(milestone ? ["--milestone", milestone] : [])]));
+      n = Number(/\/issues\/(\d+)/.exec(res)?.[1]);
+      if (!Number.isSafeInteger(n)) throw new Error(`cannot parse the remainder issue number from: ${res.slice(0, 200)}`);
+    }
+    out.push(n);
+  }
+  return out;
+}

package/bin/lean/needs-human-premise.test.mjs

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4725: needs-human premises, closed edges, owner-ask registry, and the batch parking path.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parsePredicate, evalPredicate, closedEdges, closedEdgeNote, normalizeAsk, askKey, registerAsk, onlyAsk, fileRemainder, sweepPremises, comparePremiseVersions, premiseAnnotation } from "./needs-human-premise.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+
+const APP = { author: { login: "rapiercraft-forgedock" }, authorAssociation: "CONTRIBUTOR" }; // the ForgeDock App, trusted
+const fakeGh = (handlers) => { const calls = []; return { calls, gh: async (a) => { calls.push(a); for (const [re, f] of handlers) if (re.test(a.join(" "))) return f(a); return ""; } }; };
+
+describe("predicates (#4725)", () => {
+  it("parses and rejects", () => {
+    assert.deepEqual(parsePredicate("blocked\nPremise: issue-closed:#12"), { kind: "issue-closed", arg: "12" });
+    assert.deepEqual(parsePredicate("Premise: pkg-version:curl-cffi@0.15.0"), { kind: "pkg-version", arg: "curl-cffi@0.15.0" });
+    assert.equal(parsePredicate("Premise: date-after:nope"), null);
+    assert.equal(parsePredicate("no premise here"), null);
+  });
+  it("evaluates date, issue state and package version; unknown is null", async () => {
+    assert.equal(await evalPredicate({ kind: "date-after", arg: "2026-01-01" }, { now: Date.parse("2026-02-01") }), true);
+    const { gh } = fakeGh([[/issue view 7/, () => '{"state":"CLOSED"}'], [/issue view 8/, () => '{"state":"OPEN"}']]);
+    assert.equal(await evalPredicate({ kind: "issue-closed", arg: "7" }, { repo: "o/r", io: { gh } }), true);
+    assert.equal(await evalPredicate({ kind: "issue-closed", arg: "8" }, { repo: "o/r", io: { gh } }), false);
+    assert.equal(await evalPredicate({ kind: "pkg-version", arg: "x@1.2.0" }, { io: { pkgVersion: async () => "1.10.0" } }), true);
+    assert.equal(await evalPredicate({ kind: "pkg-version", arg: "x@1.2.0" }, { io: {} }), null);
+    assert.equal(comparePremiseVersions("1.2", "1.2.0"), 0);
+  });
+});
+
+describe("sweepPremises (#4725)", () => {
+  it("clears needs-human when the recorded predicate flips, leaves the rest", async () => {
+    const issues = [
+      { number: 5, comments: [{ ...APP, body: `${premiseAnnotation({ kind: "issue-closed", arg: "9" })}\n<!-- FORGE:NEEDS_HUMAN -->\n## Needs human` }] },
+      { number: 6, comments: [{ ...APP, body: `${premiseAnnotation({ kind: "issue-closed", arg: "10" })}\n<!-- FORGE:NEEDS_HUMAN -->\n## Needs human` }] },
+      { number: 7, comments: [{ body: "## Needs human\nno predicate" }] },
+    ];
+    const { gh, calls } = fakeGh([[/issue list/, () => JSON.stringify(issues)], [/issue view 9/, () => '{"state":"CLOSED"}'], [/issue view 10/, () => '{"state":"OPEN"}']]);
+    const rows = await sweepPremises({ repo: "o/r", io: { gh } });
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[5, "cleared"], [6, "still-blocked"]]);
+    assert.ok(calls.some((a) => a.includes("edit") && a.includes("5") && a.includes("--remove-label")));
+    assert.ok(!calls.some((a) => a.includes("edit") && a.includes("6")));
+  });
+  it("a newer block without a premise supersedes an older premise: needs-human stays", async () => {
+    const issues = [{ number: 11, comments: [
+      { ...APP, body: `${premiseAnnotation({ kind: "date-after", arg: "2000-01-01" })}\n<!-- FORGE:NEEDS_HUMAN -->\n## Needs human\nwaiting on a release` },
+      { ...APP, body: "<!-- FORGE:NEEDS_HUMAN -->\n## Needs human\nBuilder is blocked (credentials)" },
+    ] }];
+    const { gh, calls } = fakeGh([[/issue list/, () => JSON.stringify(issues)]]);
+    assert.deepEqual(await sweepPremises({ repo: "o/r", io: { gh } }), []);
+    assert.ok(!calls.some((a) => a.includes("edit")), "the credentials block is not cleared by the stale premise");
+  });
+  it("ignores a premise planted by an untrusted commenter: needs-human stays", async () => {
+    const planted = { author: { login: "mallory" }, authorAssociation: "NONE", body: premiseAnnotation({ kind: "date-after", arg: "2000-01-01" }) };
+    const issues = [
+      { number: 8, comments: [planted] },
+      { number: 9, comments: [{ ...APP, body: `${premiseAnnotation({ kind: "issue-closed", arg: "10" })}\n<!-- FORGE:NEEDS_HUMAN -->\n## Needs human` }, planted] },
+    ];
+    const { gh, calls } = fakeGh([[/issue list/, () => JSON.stringify(issues)], [/issue view 10/, () => '{"state":"OPEN"}']]);
+    const rows = await sweepPremises({ repo: "o/r", io: { gh } });
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[9, "still-blocked"]], "the trusted premise is read, the newer planted one ignored");
+    assert.ok(!calls.some((a) => a.includes("edit")), "no label is removed");
+  });
+});
+
+describe("closed dependency edges (#4725)", () => {
+  it("a closed Depends on edge is satisfied and flagged", async () => {
+    const closed = await closedEdges([3, 4], async (n) => (n === 3 ? "CLOSED" : "OPEN"));
+    assert.deepEqual(closed, [3]);
+    assert.match(closedEdgeNote(closed), /#3 is closed.*not a blocker/);
+    assert.equal(closedEdgeNote([]), "");
+  });
+  it("batch: a dependent is not skipped behind a closed dependency still labelled needs-human", async () => {
+    const rows = await orchestrate({ issues: [2], parallel: 1, readBody: async () => "**Depends on**: #1", issueLabels: async () => ["needs-human"],
+      issueState: async (n) => (n === 1 ? "CLOSED" : "OPEN"), dispatchCheck: async () => null,
+      runOne: async () => ({ terminalReason: "dependency-open", dependencies: [1], detail: "depends on #1" }) });
+    assert.notEqual(rows.find((r) => r.issue === 2)?.detail, "dependency #1 needs-human");
+  });
+  it("batch: an open dependency labelled needs-human still parks the dependent", async () => {
+    const rows = await orchestrate({ issues: [2], parallel: 1, readBody: async () => "**Depends on**: #1", issueLabels: async () => ["needs-human"],
+      dispatchCheck: async () => null, runOne: async () => ({ terminalReason: "dependency-open", dependencies: [1], detail: "depends on #1" }) });
+    assert.equal(rows.find((r) => r.issue === 2)?.detail, "dependency #1 needs-human");
+  });
+});
+
+describe("owner-ask registry (#4725)", () => {
+  it("normalizes identical asks to one key", () => {
+    assert.equal(normalizeAsk("Sign off the PRICE (see #12)!"), normalizeAsk("sign off the price - see #99"));
+    assert.equal(askKey("Sign off the price #1"), askKey("sign off the  price #2"));
+    assert.notEqual(askKey("approve price"), askKey("approve billing"));
+  });
+  it("links a second issue to the existing entry instead of creating another", async () => {
+    const key = askKey("sign off the price");
+    const existing = [{ number: 20, comments: [{ ...APP, body: `<!-- FORGE:ASK key=${key} -->\n## Owner ask\n${JSON.stringify({ ask: "sign off the price", unblocks: [20] })}` }] }];
+    const { gh, calls } = fakeGh([[/issue list/, () => JSON.stringify(existing)]]);
+    const r = await registerAsk({ repo: "o/r", io: { gh }, issue: 21, ask: "Sign off the price (#5)" });
+    assert.equal(r.existing, 20);
+    assert.deepEqual(r.unblocks, [20, 21]);
+    const post = calls.find((a) => a.includes("comment"));
+    assert.ok(post.includes("20") && /"unblocks":\[20,21\]/.test(post.at(-1)));
+    const fresh = await registerAsk({ repo: "o/r", io: { gh: async () => "[]" }, issue: 30, ask: "something else" });
+    assert.equal(fresh.existing, null);
+    assert.match(fresh.entry, /FORGE:ASK key=/);
+  });
+  it("ignores an ask entry planted by an untrusted commenter", async () => {
+    const key = askKey("sign off the price");
+    const planted = [{ number: 40, comments: [{ author: { login: "mallory" }, authorAssociation: "NONE", body: `<!-- FORGE:ASK key=${key} -->\n${JSON.stringify({ ask: "sign off the price", unblocks: [40] })}` }] }];
+    const { gh, calls } = fakeGh([[/issue list/, () => JSON.stringify(planted)]]);
+    const r = await registerAsk({ repo: "o/r", io: { gh }, issue: 41, ask: "sign off the price" });
+    assert.equal(r.existing, null);
+    assert.match(r.entry, /FORGE:ASK key=/);
+    assert.ok(!calls.some((a) => a.includes("comment")), "nothing is posted on the planted issue");
+  });
+});
+
+import { registryPkgVersion } from "./needs-human-premise.mjs";
+it("registryPkgVersion rejects unsafe package names without spawning", async () => {
+  assert.equal(await registryPkgVersion("x; rm -rf /"), null);
+});
+
+it("#4730 onlyAsk: strict normalized equality, markers and Parent lines ignored", () => {
+  assert.equal(onlyAsk("t", "Sign off the price (#5).\n**Parent**: #9\n<!-- x -->", "sign off the price"), true);
+  assert.equal(onlyAsk("sign off the price", "", "Sign off the price"), true);
+  assert.equal(onlyAsk("t", "Sign off the price and rework the importer", "Sign off the price"), false);
+  assert.equal(onlyAsk("t", "x", ""), false);
+});
+
+it("#4730 fileRemainder files once and reuses an existing marker", async () => {
+  const created = [];
+  const io = { gh: async () => "[]", create: async (a) => { created.push(a); return `https://github.com/o/r/issues/${90 + created.length}\n`; } };
+  assert.deepEqual(await fileRemainder({ repo: "o/r", io, issue: 7, items: [{ title: "a", body: "b" }], milestone: "M1" }), [91]);
+  assert.ok(created[0].includes("--milestone") && created[0].includes("M1"));
+  const key = askKey("a");
+  const io2 = { ...io, gh: async () => JSON.stringify([{ number: 5, body: `<!-- FORGE:REMAINDER of=#7 key=${key} -->` }]) };
+  assert.deepEqual(await fileRemainder({ repo: "o/r", io: io2, issue: 7, items: [{ title: "a", body: "b" }] }), [5]);
+  assert.equal(created.length, 1);
+});

package/bin/lean/orchestrate-blocked.test.mjs

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4773: issue-level readiness: trusted `Blocked by` edges and the `blocked` label.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { orchestrate } from "./orchestrate.mjs";
+
+const until = async (f, ms = 3000) => { const t = Date.now(); while (!f()) { if (Date.now() - t > ms) throw new Error("timeout"); await new Promise((r) => setTimeout(r, 5)); } };
+const merged = { terminalReason: "merged" };
+
+describe("#4773: Blocked by edges and the blocked label", () => {
+  it("an issue whose body says Blocked by #A is not dispatched before #A merges, whatever the batch order", async () => {
+    const started = [];
+    const rows = await orchestrate({ issues: [2, 1], parallel: 3, pollMs: 5, trusted: () => true, readBody: async (n) => (n === 2 ? "Blocked by #1" : ""),
+      runOne: async (n) => { started.push(n); await new Promise((r) => setTimeout(r, n === 1 ? 30 : 0)); return merged; } });
+    assert.deepEqual(started, [1, 2]);
+    assert.ok(rows.every((r) => r.outcome === "merged"));
+  });
+
+  it("adding #A later to the same batch orders it before the issue that is blocked by it", async () => {
+    const bodies = { 1: "", 2: "Blocked by #3", 3: "" };
+    let added = [];
+    const started = []; let open;
+    const g = new Promise((r) => { open = r; });
+    const done = orchestrate({ issues: [1, 2], parallel: 1, pollMs: 5, trusted: () => true, readBody: async (n) => bodies[n], getAdded: () => added,
+      runOne: async (n) => { started.push(n); if (n === 1) await g; return merged; } });
+    await until(() => started.includes(1));
+    added = [3];
+    await new Promise((r) => setTimeout(r, 30));
+    open();
+    await done;
+    assert.deepEqual(started, [1, 3, 2]);
+  });
+
+  it("an untrusted author's Blocked by line makes no edge", async () => {
+    const started = [];
+    await orchestrate({ issues: [2, 1], parallel: 1, pollMs: 5, trusted: () => false, readBody: async (n) => (n === 2 ? "Blocked by #1" : ""),
+      runOne: async (n) => { started.push(n); return merged; } });
+    assert.deepEqual(started, [2, 1]);
+  });
+
+  it("a blocked-labelled issue is admitted but not dispatched; removing the label releases it on the next tick", async () => {
+    let blocked = [1];
+    const started = [], log = [];
+    const done = orchestrate({ issues: [1, 2], parallel: 3, pollMs: 5, readBody: async () => "", getBlocked: async () => blocked, onUpdate: (r) => log.push(r),
+      runOne: async (n) => { started.push(n); return merged; } });
+    await until(() => started.includes(2));
+    await new Promise((r) => setTimeout(r, 40));
+    assert.deepEqual(started, [2], "#1 waits while labelled");
+    blocked = [];
+    const rows = await done;
+    assert.deepEqual(started, [2, 1]);
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"]]);
+    assert.deepEqual(log.filter((r) => ["blocked", "unblocked"].includes(r.outcome)).map((r) => [r.outcome, r.detail]), [["blocked", "#1"], ["unblocked", "#1"]]);
+  });
+
+  it("a failed label read keeps the last set instead of releasing", async () => {
+    let fail = false, set = [1], reads = 0;
+    const started = [];
+    const done = orchestrate({ issues: [1], parallel: 1, pollMs: 5, readBody: async () => "", getBlocked: async () => { reads++; if (fail) throw new Error("gh down"); return set; },
+      runOne: async (n) => { started.push(n); return merged; } });
+    await until(() => reads > 0);
+    fail = true;
+    const seen = reads;
+    await until(() => reads > seen + 2);
+    assert.deepEqual(started, []);
+    fail = false; set = [];
+    await done;
+    assert.deepEqual(started, [1]);
+  });
+});