forgedock 1.37.0 → 1.38.1

package/bin/lean/issuewatch.test.mjs

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { join } from "node:path";
+import { unclaimedOrOwn, parseWatches, validateWatch, loadWatches, matchesSelectors, issueVersion, hasUnresolvedDefer, classifyIssue, laneFor, dagOrder, claimIssue, acquireLock, tick, runWatch, formatStatus, repoDir, watchDir, issueWatchFromCli } from "./issuewatch.mjs";
+import { openBatch } from "./batch.mjs";
+
+const tmp = () => tmpDir("iw-");
+const iss = (n, o = {}) => ({ number: n, title: `t${n}`, body: "", labels: [], milestone: null, authorAssociation: "OWNER", author: { login: "me" }, createdAt: "2026-10-01T00:00:00Z", ...o });
+const lbl = (...n) => n.map((name) => ({ name }));
+const W = (o = {}) => validateWatch("w", o);
+
+/** gh fake: `issues` open list, `closed` set of closed numbers, `bodies` for view/edit. */
+function fakeIo(env, issues, { closed = new Set(), exit = () => 0, bodies = {} } = {}) {
+  const calls = [], launched = [], batchOps = [];
+  let clock = Date.parse("2026-10-30T00:00:00Z"), nb = 0;
+  const io = { env: { FORGEDOCK_WATCH_DIR: env }, calls, launched, batchOps, closed, bodies, tickClock: (ms) => { clock += ms; }, now: () => clock, sleep: async () => {},
+    gh: async (a) => {
+      calls.push(a);
+      if (a[1] === "list") return JSON.stringify(issues.filter((i) => !closed.has(i.number)));
+      if (a[1] === "view" && a.includes("state")) return JSON.stringify({ state: closed.has(+a[2]) ? "CLOSED" : "OPEN" });
+      if (a[1] === "view") return JSON.stringify({ body: bodies[a[2]] ?? "" });
+      if (a[1] === "edit") { bodies[a[2]] = a[a.indexOf("--body") + 1]; return ""; }
+      return "";
+    },
+    launch: (n, lane) => { launched.push([n, lane]); return { poll: () => ({ code: exit(n) }) }; },
+    batch: { add: (id, nums) => batchOps.push(["add", id, nums]), start: async (nums, k, lane) => { batchOps.push(["start", nums, k, lane]); return `b${++nb}`; }, reported: (id) => io.reported?.has(id) ?? false } };
+  return io;
+}
+
+test("parseWatches reads three nesting levels, lists, quotes and ISO times", () => {
+  const w = loadWatches(`project:\n  name: x\nissue_watch:\n  watches:\n    nomilestone:\n      milestone: none\n      exclude_labels: [epic, post-deploy]\n      include_followups: defer-only\n      mode: batch\n      parallel: 12\n    release-1-4:\n      version: "1.4"\n      max_issues: 300\n      until: 2026-11-15T00:00:00Z\nother:\n  a: b\n`);
+  assert.deepEqual(Object.keys(w), ["nomilestone", "release-1-4"]);
+  assert.deepEqual(w.nomilestone.exclude_labels, ["epic", "post-deploy"]);
+  assert.equal(w.nomilestone.parallel, 12);
+  assert.equal(w["release-1-4"].max_issues, 300);
+  assert.equal(w["release-1-4"].until, "2026-11-15T00:00:00Z");
+  assert.equal(w["release-1-4"].version, "1.4");
+  assert.deepEqual(parseWatches("project:\n  a: b\n"), {});
+});
+
+test("validateWatch rejects unknown keys, bad mode, regex, date, numbers", () => {
+  assert.throws(() => W({ bogus: 1 }), /unknown key/);
+  assert.throws(() => W({ mode: "x" }), /mode/);
+  assert.throws(() => W({ title_regex: "(" }), /title_regex/);
+  assert.throws(() => W({ until: "soon" }), /until/);
+  assert.throws(() => W({ max_issues: "0" }), /max_issues/);
+  assert.throws(() => W({ version: "1" }), /version/);
+  assert.equal(W().mode, "per-issue");
+  assert.equal(W().max_issues, null);
+});
+
+test("selectors: milestone slug / none, labels, exclude_labels, title_regex, since", () => {
+  const m = iss(1, { milestone: { title: "Release 1.4" } });
+  assert.ok(matchesSelectors(m, W({ milestone: "release-1.4" }))); // slug form
+  assert.ok(!matchesSelectors(m, W({ milestone: "other" })));
+  assert.ok(!matchesSelectors(m, W({ milestone: "none" })));
+  assert.ok(matchesSelectors(iss(2), W({ milestone: "none" })));
+  assert.ok(!matchesSelectors(iss(2), W({ milestone: "some" })));
+  assert.ok(matchesSelectors(iss(3, { labels: lbl("a", "b") }), W({ labels: ["a"] })));
+  assert.ok(!matchesSelectors(iss(3, { labels: lbl("a") }), W({ labels: ["a", "b"] })));
+  assert.ok(!matchesSelectors(iss(4, { labels: lbl("epic") }), W({ exclude_labels: ["epic"] })));
+  assert.ok(matchesSelectors(iss(4, { labels: lbl("x") }), W({ exclude_labels: ["epic"] })));
+  assert.ok(matchesSelectors(iss(5, { title: "fix: a" }), W({ title_regex: "^fix:" })));
+  assert.ok(!matchesSelectors(iss(5, { title: "feat: a" }), W({ title_regex: "^fix:" })));
+  assert.ok(matchesSelectors(iss(6), W({ since: "2026-09-01T00:00:00Z" })));
+  assert.ok(!matchesSelectors(iss(6), W({ since: "2026-10-02T00:00:00Z" })));
+});
+
+test("version: from the milestone title, from a version:x.y label, title wins", () => {
+  assert.equal(issueVersion(iss(1, { milestone: { title: "v1.4 hardening" } })), "1.4");
+  assert.equal(issueVersion(iss(2, { labels: lbl("version:1.5") })), "1.5");
+  assert.equal(issueVersion(iss(3, { milestone: { title: "Release 1.4" }, labels: lbl("version:1.5") })), "1.4");
+  assert.equal(issueVersion(iss(4)), null);
+  const w = W({ version: "1.4" });
+  assert.ok(matchesSelectors(iss(1, { milestone: { title: "Release 1.4" } }), w));
+  assert.ok(matchesSelectors(iss(2, { labels: lbl("version:1.4") }), w));
+  assert.ok(!matchesSelectors(iss(3, { labels: lbl("version:1.5") }), w));
+});
+
+test("search is passed to gh", async () => {
+  const dir = tmp(), io = fakeIo(dir, [iss(1)]);
+  await tick({ watch: W({ search: "label:bug sort:created-asc" }), repo: "o/r", io, state: { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" } });
+  const list = io.calls.find((a) => a[1] === "list");
+  assert.equal(list[list.indexOf("--search") + 1], "label:bug sort:created-asc");
+});
+
+test("lane: milestone → pattern, else staging, pin allowed, default branch refused", () => {
+  const b = { staging: "staging", featurePattern: "milestone/{slug}" };
+  assert.equal(laneFor(iss(1, { milestone: { title: "Release 1.4" } }), W(), { branches: b, defaults: ["main"] }), "milestone/release-14");
+  assert.equal(laneFor(iss(2), W(), { branches: b, defaults: ["main"] }), "staging");
+  assert.equal(laneFor(iss(2), W({ lane: "dev" }), { branches: b, defaults: ["main"] }), "dev");
+  assert.throws(() => laneFor(iss(2), W({ lane: "main" }), { branches: b, defaults: ["main"] }), /default branch/);
+});
+
+test("follow-ups: defer-only claims bot follow-ups with an unchecked defer item; plain bot issues and post-deploy-only excluded", () => {
+  const bot = (body, title = "follow-up: 1 deferred item(s)") => iss(9, { title, body, authorAssociation: "CONTRIBUTOR", author: { login: "forge[bot]" } });
+  const defer = "- [ ] `R1: x` — defer: separate work\n";
+  const pd = "- [ ] `R2: y` — post-deploy: check later\n";
+  assert.ok(hasUnresolvedDefer(defer));
+  assert.ok(!hasUnresolvedDefer("- [x] `R1: x` — defer: done\n"));
+  assert.ok(!hasUnresolvedDefer(pd));
+  assert.equal(classifyIssue(bot(defer), W({ include_followups: "defer-only" })), "claim");
+  assert.equal(classifyIssue(bot(defer + pd), W({ include_followups: "defer-only" })), "claim");
+  assert.equal(classifyIssue(bot(defer), W()), null);
+  assert.equal(classifyIssue(bot(defer, "chore: bot issue"), W({ include_followups: "defer-only" })), null);
+  assert.equal(classifyIssue(bot(pd), W({ include_followups: "defer-only" })), null);
+  assert.equal(classifyIssue(bot(pd), W({ include_followups: "defer-only", postdeploy_rollup: "50" })), "fold");
+  assert.equal(classifyIssue(iss(1, { authorAssociation: "NONE" }), W()), null);
+  // release #4820 AUTH-1: a FORGE:DEFERRED marker in the body never makes an outsider a bot
+  const spoof = iss(11, { title: "follow-up: 1 deferred item(s)", body: `<!-- FORGE:DEFERRED_FROM: #1 -->\n${defer}`, authorAssociation: "NONE", author: { login: "mallory" } });
+  assert.equal(classifyIssue(spoof, W({ include_followups: "defer-only" })), null);
+  assert.equal(classifyIssue({ ...spoof, body: `<!-- FORGE:DEFERRED_FROM: #1 -->\n${pd}` }, W({ include_followups: "defer-only", postdeploy_rollup: "50" })), null);
+  // the App as gh reports it (bare login, CONTRIBUTOR) still counts as the bot
+  const app = iss(12, { title: "follow-up: 1 deferred item(s)", body: defer, authorAssociation: "CONTRIBUTOR", author: { login: "rapiercraft-forgedock" } });
+  assert.equal(classifyIssue(app, W({ include_followups: "defer-only" })), "claim");
+});
+
+test("postdeploy_rollup folds a post-deploy-only follow-up into the release checklist once", async () => {
+  const dir = tmp();
+  const f = iss(9, { title: "follow-up: 1 deferred item(s)", body: "- [ ] `R2: y` — post-deploy: check\n", authorAssociation: "CONTRIBUTOR", author: { login: "forge[bot]" } });
+  const io = fakeIo(dir, [f], { bodies: { 50: "## Release\n- [ ] ship\n" } });
+  const watch = W({ include_followups: "defer-only", postdeploy_rollup: "50" });
+  const state = { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" };
+  await tick({ watch, repo: "o/r", io, state });
+  await tick({ watch, repo: "o/r", io, state });
+  assert.match(io.bodies[50], /- \[ \] #9 follow-up: 1 deferred item\(s\) — post-deploy/);
+  assert.equal(io.bodies[50].match(/#9\b/g).length, 1);
+  assert.deepEqual(io.launched, []);
+  assert.deepEqual(state.claimed, []);
+});
+
+test("two named watches on one repo never double-claim", async () => {
+  const dir = tmp();
+  const issues = [1, 2, 3, 4].map((n) => iss(n));
+  const mk = () => ({ claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" });
+  const a = { watch: validateWatch("a", { max_inflight: "3" }), io: fakeIo(dir, issues), state: mk() };
+  const b = { watch: validateWatch("b", { max_inflight: "3" }), io: fakeIo(dir, issues), state: mk() };
+  await Promise.all([a, b].map((x) => tick({ ...x, repo: "o/r", handles: new Map() })));
+  await Promise.all([a, b].map((x) => tick({ ...x, repo: "o/r", handles: new Map() })));
+  const all = [...a.state.claimed, ...b.state.claimed];
+  assert.equal(new Set(all).size, all.length);
+  assert.deepEqual([...all].sort(), [1, 2, 3, 4]);
+  assert.equal(claimIssue(repoDir("o/r", { FORGEDOCK_WATCH_DIR: dir }), 1, "c"), false);
+});
+
+test("release #4820 BUG-1: a throwing batch.start loses no claim; the same watch re-claims on the next pass", async () => {
+  const dir = tmp();
+  const mk = () => ({ claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" });
+  const watch = validateWatch("w", { mode: "batch", max_inflight: "3" });
+  const io = fakeIo(dir, [iss(1), iss(2)]);
+  const start = io.batch.start;
+  io.batch.start = async () => { throw new Error("schedd unreachable"); };
+  await assert.rejects(tick({ watch, repo: "o/r", io, state: mk() }), /schedd unreachable/); // status.json never saved
+  io.batch.start = start;
+  const state = await tick({ watch, repo: "o/r", io, state: mk() }); // restart from the last saved (empty) state
+  assert.deepEqual([...state.claimed].sort(), [1, 2]);
+  assert.deepEqual(io.batchOps, [["start", [1, 2], watch.parallel, "staging"]]);
+  assert.equal(claimIssue(repoDir("o/r", { FORGEDOCK_WATCH_DIR: dir }), 1, "other"), false, "another watch still cannot take it");
+});
+
+test("max_issues stops claiming at N, drains, then finishes", async () => {
+  const dir = tmp();
+  const io = fakeIo(dir, [1, 2, 3, 4, 5].map((n) => iss(n)), { exit: () => 0 });
+  const watch = W({ max_issues: "3", max_inflight: "2" });
+  const state = await runWatch({ watch, repo: "o/r", io, dir: watchDir("o/r", "w", { FORGEDOCK_WATCH_DIR: dir }), once: false, intervalMs: 1 });
+  assert.equal(state.claimed.length, 3);
+  assert.equal(state.phase, "done");
+  assert.equal(io.launched.length, 3);
+  assert.match(formatStatus(state, watch, io.now()), /claims: 3\/3/);
+});
+
+test("max_issues drain keeps retrying: a deferred (75) lane relaunches until it merges", async () => {
+  const dir = tmp();
+  let n75 = 1;
+  const io = fakeIo(dir, [iss(1), iss(2)], { exit: () => (n75-- > 0 ? 75 : 0) });
+  const state = await runWatch({ watch: W({ max_issues: "1" }), repo: "o/r", io, dir: watchDir("o/r", "w", { FORGEDOCK_WATCH_DIR: dir }), intervalMs: 1 });
+  assert.equal(io.launched.length, 2); // launch + one retry
+  assert.deepEqual(state.merged, [1]);
+  assert.equal(state.claimed.length, 1);
+});
+
+test("until stops claiming and drains; a failed lane is counted", async () => {
+  const dir = tmp();
+  const io = fakeIo(dir, [iss(1), iss(2)], { exit: () => 1 });
+  const watch = W({ until: "2026-10-30T00:10:00Z", max_inflight: "1" });
+  const state = { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" };
+  const handles = new Map();
+  await tick({ watch, repo: "o/r", io, state, handles });
+  assert.deepEqual(state.inflight, [1]);
+  io.tickClock(20 * 60 * 1000);
+  await tick({ watch, repo: "o/r", io, state, handles });
+  assert.deepEqual(state.failed, [1]);
+  assert.equal(state.phase, "done");
+  assert.deepEqual(state.claimed, [1]); // nothing claimed after until
+});
+
+test("no cap: keeps claiming across passes (forever)", async () => {
+  const dir = tmp();
+  const io = fakeIo(dir, [iss(1)], { exit: () => 0 });
+  const watch = W();
+  const state = { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running" };
+  const handles = new Map();
+  for (let i = 0; i < 3; i++) await tick({ watch, repo: "o/r", io, state, handles });
+  io.closed.add(1);
+  await tick({ watch, repo: "o/r", io, state, handles });
+  assert.equal(state.phase, "running");
+  assert.equal(watch.max_issues, null);
+});
+
+test("lock is per (repo, name): a live holder blocks, another name does not, a dead holder is taken over", () => {
+  const d = tmp(), a = join(d, "a"), b = join(d, "b");
+  mkdirSync(a); mkdirSync(b);
+  acquireLock(a, { pid: 111, host: "h", alive: () => true });
+  assert.throws(() => acquireLock(a, { pid: 222, host: "h", alive: () => true }), /already running/);
+  acquireLock(b, { pid: 222, host: "h", alive: () => true });
+  acquireLock(a, { pid: 222, host: "h", alive: () => false });
+});
+
+test("batch mode adds to one batch, rolls to a new one after the report, and orders by Depends on", async () => {
+  const dir = tmp();
+  const issues = [iss(1, { body: "Depends on #2" }), iss(2), iss(3)];
+  const io = fakeIo(dir, issues);
+  const watch = W({ mode: "batch", parallel: "7", max_inflight: "2" });
+  const state = { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running", batch: null };
+  await tick({ watch, repo: "o/r", io, state });
+  assert.deepEqual(io.batchOps[0], ["start", [2, 1], 7, "staging"]); // dependency first
+  io.closed.add(2); io.closed.add(1);
+  await tick({ watch, repo: "o/r", io, state });
+  assert.deepEqual(io.batchOps[1], ["add", "b1", [3]]);
+  io.reported = new Set(["b1"]);
+  io.closed.add(3);
+  await tick({ watch, repo: "o/r", io, state });
+  assert.equal(state.batch, null);
+  assert.deepEqual(state.verified.sort(), [1, 2, 3]);
+  io.reported = new Set();
+  issues.push(iss(4));
+  await tick({ watch, repo: "o/r", io, state });
+  assert.deepEqual(io.batchOps[2], ["start", [4], 7, "staging"]); // a new batch
+  assert.deepEqual(dagOrder([iss(1, { body: "Depends on: #2, #3" }), iss(2), iss(3)]).map((i) => i.number), [2, 3, 1]);
+});
+
+test("batch mode with the real batch file: addIssues lands in the batch's add file", async () => {
+  const root = tmp();
+  const b = openBatch(root, "b1"); mkdirSync(b.dir, { recursive: true });
+  b.writePlan({ issues: [1] }); b.store.save({ order: [1] });
+  const io = fakeIo(tmp(), [iss(5)]);
+  io.batch.add = (id, nums) => openBatch(root, id).addIssues(nums);
+  const state = { claimed: [], inflight: [], merged: [], verified: [], failed: [], folded: [], retries: {}, lanes: {}, phase: "running", batch: "b1" };
+  await tick({ watch: W({ mode: "batch" }), repo: "o/r", io, state });
+  assert.deepEqual(b.readAdded(), [5]);
+});
+
+test("status prints selector, claims, inflight, merged, verified, failed, time remaining; CLI status/run", async () => {
+  const dir = tmp(), cwd = tmp();
+  writeFileSync(join(cwd, "forge.yaml"), "branches:\n  default: main\nissue_watch:\n  watches:\n    r:\n      version: \"1.4\"\n      max_issues: 5\n      until: 2026-10-30T02:00:00Z\n");
+  const io = fakeIo(dir, [iss(1, { labels: lbl("version:1.4") })], { exit: () => 0 });
+  io.gh = ((orig) => async (a) => (a[0] === "repo" ? (a.includes("nameWithOwner") ? JSON.stringify({ nameWithOwner: "o/r" }) : "main") : orig(a)))(io.gh);
+  const out = [];
+  await issueWatchFromCli(["run", "--name", "r", "--once"], { cwd, env: { FORGEDOCK_WATCH_DIR: dir }, io, print: (l) => out.push(l) });
+  assert.ok(existsSync(join(watchDir("o/r", "r", { FORGEDOCK_WATCH_DIR: dir }), "status.json")));
+  out.length = 0;
+  await issueWatchFromCli(["status", "--name", "r"], { cwd, env: { FORGEDOCK_WATCH_DIR: dir }, io, print: (l) => out.push(l) });
+  const t = out.join("\n");
+  assert.match(t, /selector: version=1\.4/);
+  assert.match(t, /claims: 1\/5\s+inflight: 0\s+merged: 1\s+verified: 0|claims: 1\/5\s+inflight: 1/);
+  assert.match(t, /time remaining: 120m/);
+  await assert.rejects(issueWatchFromCli(["bogus"], { cwd, env: { FORGEDOCK_WATCH_DIR: dir }, io }), /usage/);
+});
+
+test("release #4820 CONC-1: release mode keeps this watch's own registry claims eligible; others' stay excluded", () => {
+  const reg = { 1: "r", 2: "other" };
+  assert.equal(unclaimedOrOwn(reg, 1, "r"), true, "own claim left by a crash is re-eligible");
+  assert.equal(unclaimedOrOwn(reg, 2, "r"), false, "another watch's claim is not");
+  assert.equal(unclaimedOrOwn(reg, 3, "r"), true);
+  assert.equal(unclaimedOrOwn(null, 3, "r"), true);
+});

package/bin/lean/lane.mjs

@@ -47,15 +47,16 @@ export async function defaultBranches({ repo, io, branches = {} }) {
  */
 export async function resolveLane({ issue, repo, io, cwd, branches = {}, requested = null, override = false }) {
   const refuse = (code, detail) => ({ ok: false, code, detail });
+  const transient = (detail) => ({ ...refuse(OUTCOME_CODES.LANE_UNRESOLVED, detail), transient: true }); // #4791: a gh/git command failed; retry
   const staging = branches.staging || DEFAULT_STAGING_BRANCH;
   const pattern = branches.featurePattern || DEFAULT_FEATURE_PATTERN;
   if (!pattern.includes("{slug}")) return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `forge.yaml branches.feature_pattern "${pattern}" has no {slug}`);
   let milestone = null, defaults;
   try {
     milestone = JSON.parse(String(await io.gh(["issue", "view", String(issue), "-R", repo, "--json", "milestone"])))?.milestone?.title || null;
-  } catch (e) { return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot read the milestone of #${issue}: ${String(e?.message ?? e).slice(0, 200)}`); }
+  } catch (e) { return transient(`cannot read the milestone of #${issue}: ${String(e?.message ?? e).slice(0, 200)}`); }
   try { defaults = await defaultBranches({ repo, io, branches }); } catch (e) {
-    return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot read the default branch of ${repo}: ${String(e?.message ?? e).slice(0, 200)}`);
+    return transient(`cannot read the default branch of ${repo}: ${String(e?.message ?? e).slice(0, 200)}`);
   }
   let expected = staging;
   if (milestone) {
@@ -78,7 +79,7 @@ export async function resolveLane({ issue, repo, io, cwd, branches = {}, request
   if (!LANE_RE.test(lane) || lane.includes("..")) return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `invalid lane ${JSON.stringify(lane)}`);
   let out;
   try { out = String(await io.git(["ls-remote", "--heads", "origin", `refs/heads/${lane}`], { cwd })); } catch (e) {
-    return refuse(OUTCOME_CODES.LANE_UNRESOLVED, `cannot check origin for ${lane}: ${String(e?.message ?? e).slice(0, 200)}`);
+    return transient(`cannot check origin for ${lane}: ${String(e?.message ?? e).slice(0, 200)}`);
   }
   if (!out.trim()) return refuse(OUTCOME_CODES.LANE_BRANCH_MISSING, `lane branch ${lane} (${why}) does not exist on origin; create it first (e.g. /milestone start) or fix the milestone title`);
   return { ok: true, lane, expected, milestone, overridden, defaults };

package/bin/lean/lane.test.mjs

@@ -88,4 +88,16 @@ describe("lane resolution (#4125)", () => {
     assert.deepEqual(readBranches(d), { default: "main", staging: "develop", featurePattern: "milestone/{slug}" });
     assert.deepEqual(readBranches(tmpDir("lane-")), { default: null, staging: null, featurePattern: null });
   });
+
+  it("#4791 a failed gh/git command is transient; a genuine refusal is not", async () => {
+    for (const o of [{ ghFails: "issue" }, { ghFails: "repo" }, { gitFails: true }]) {
+      const r = await resolve(o);
+      assert.deepEqual([r.ok, r.code, r.transient], [false, "lane.unresolved", true]);
+    }
+    const missing = await resolve({ onOrigin: ["main"] });
+    assert.equal(missing.ok, false);
+    assert.ok(!missing.transient);
+    const slug = await resolve({ milestone: "🚀" });
+    assert.deepEqual([slug.code, !!slug.transient], ["lane.unresolved", false]);
+  });
 });

package/bin/lean/lean.mjs

@@ -13,10 +13,11 @@ import { codeForTerminalReason, OUTCOME_CODES } from "../engine/outcome-codes.mj
 import { ciPollDelayMs, ENGINE_VERSION, DEFAULT_MAX_SESSION_LIMIT_PAUSES, DEFAULT_SESSION_LIMIT_WAIT_MS, parseLeaseHolder, sanitizeLeaseHost } from "../engine.mjs";
 import { openDependency, laneMergedPrs, dependencyOnLane, isTrustedComment, decomposedSubissues, isDecomposedRecord, reopenRevokedDecomposition } from "../engine/phases.mjs";
 import { createHash } from "node:crypto";
-import { TRACKED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, applyAmendments, precheck, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote } from "./conformance.mjs";
+import { TRACKED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, cliUsageError, normalizeRunnerCommand, applyAmendments, precheck, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote } from "./conformance.mjs";
 import { checkAdmission, hostParallelism, ADMISSION_RETRY_SECONDS } from "./admission.mjs";
 import { namedPaths, isTrustedIssueComment } from "./prefilter.mjs";
 import { checksAt } from "./postdeploy-check.mjs";
+import { readRollouts, detectNewOffKeys } from "./activation.mjs";
 import { preflightProbes, preflightProblems, unsetEnvVars, runPreflight, knownToContract } from "./preflight.mjs";
 import { resolveLane, isDefaultLane, isShippedLane, DEFAULT_STAGING_BRANCH } from "./lane.mjs";
 import { splitGate, rationaleLine } from "./decompose.mjs";
@@ -30,12 +31,12 @@ import { retrying, ghCacheRetry, refreshAuthOnce, runRefreshScript, GH_AUTH_RE,
 import { renderInvestigation, renderImplementation, renderReview, renderPrBody, renderTrajectory, renderContract, renderAmendments, renderShadowReview, parseContractComment, contractJson, capComment, sanitizeMd, MAX_COMMENT_CHARS, recoveryEvidence } from "./render.mjs";
 import { parseVerifierConfig, pickVerifierModel, changedSymbols, callersOf, verifierBudget, verifierPrompt, parseVerifierFindings, findingsToFailures, renderVerifierNote, VERIFIER_SYSTEM } from "./verifier.mjs";
 import { computeTrigger, riskPathHits, TRIGGER_MODES } from "./review-trigger.mjs";
-import { hostCapabilityBlock } from "./execution.mjs";
+import { hostCapabilityBlock, contractHostNeeds } from "./execution.mjs";
 
 const MISSING_TOOL_RE = /command not found|not found in PATH|no such file or directory.*\b(?:docker|promtool)\b|\b(?:docker|promtool)\b[^\n]{0,80}(?:not (?:installed|found|available)|no such file|cannot connect|daemon)|cannot connect to the docker daemon|no docker daemon|no module named|ModuleNotFoundError|\bENOENT\b[^\n]{0,60}spawn/i;
 /** #4685: true when a builder's block summary names a missing tool or module (environment), not a credential. */
 export function missingToolBlock(summary) { return MISSING_TOOL_RE.test(String(summary ?? "")); }
-import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, sequenceSyncPrompt, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
 import { postMergeCommands } from "./postmerge.mjs";
 import { guardAfterMerge, withHistoryRows } from "./guards.mjs";
 import { loadGuards, selectGuards, runGuards, supersededIds, supersessionComment } from "./guardgate.mjs";
@@ -58,8 +59,9 @@ import { readDecisionIndex, withDecisionRows, recordDecisions } from "./decision
 import { parseContextPackConfig, contextArm, contextPackFor, renderContextRecord, laneType, priorAttempts, linkStateStamp, stateOf } from "./context.mjs";
 import { isExternalKill } from "./hostkill.mjs";
 import { buildResumeDigest } from "./resume.mjs";
+import { parsePredicate, evalPredicate, premiseAnnotation, registerAsk, registryPkgVersion, closedEdgeNote, onlyAsk, fileRemainder } from "./needs-human-premise.mjs";
 import { lightEligibility } from "./light.mjs";
-import { untrackToolState, unstageToolState } from "./toolstate.mjs";
+import { untrackToolState, unstageToolState, isToolState } from "./toolstate.mjs";
 import { ensureSignedOff } from "./signoff.mjs";
 import { runLightStep, runLightTests, lightBuildPrompt, upgradeNote, renderLiteReceipt } from "./lightlane.mjs";
 
@@ -71,14 +73,15 @@ export const RECOVER_HOW = Object.freeze({
   [OUTCOME_CODES.CI_RED]: "the PR's required checks failed. Read the failed checks' logs (`gh run view <run-id> --log-failed`, or the repo's declared check commands), fix the causes, re-run those checks locally and push new commits only (never rewrite history)",
   [OUTCOME_CODES.BASE_CONFLICT]: "the PR conflicts with origin/BASE. Merge origin/BASE, resolve every conflict keeping both sides' intent, re-run the validate commands and push new commits only",
   [OUTCOME_CODES.BUILDER_BLOCK_UNTYPED]: "an earlier run escalated an in-scope technical choice. Do not block on it: pick the option most consistent with the issue, the repo's conventions and prior merged decisions, and name the alternative you did not take in your summary",
-  [OUTCOME_CODES.CONTRACT_INVALID]: "the issue was edited while the earlier run planned. Plan against the current issue text",
+  [OUTCOME_CODES.CONTRACT_INVALID]: "the issue was edited while the earlier run planned, or its requirement quotes did not match the issue text. Plan against the current issue text and quote each requirement verbatim from it",
   [OUTCOME_CODES.BUDGET_EXCEEDED]: "an earlier run spent the implement turn budget for this issue's size; its digest is in the earlier run's detail and the branch holds its checkpointed work. Continue from the checkpoint against the frozen contract without starting over; if the remaining work cannot fit the budget, stop with a typed split-required block naming the sub-issues instead of grinding",
+  [OUTCOME_CODES.CONTRACT_INVALID_COMMAND]: "a frozen validate command was rejected by its runner's CLI (vitest 3 rejects -q). The change may already be correct: rerun the validate with the runner's own flags (vitest: --reporter=dot) and amend the command, do not rewrite the deliverables",
   [OUTCOME_CODES.ENV_TOOL_MISSING]: "a validate command could not run because the host lacks the tool or module named in the earlier run's detail; the change may already be correct. Do not edit the deliverables for it and never install anything globally: run the same check through the repo's own toolchain (its virtualenv, lockfile-pinned runner or package scripts), record that exit under the same validate id and name the command you used in your summary",
   [OUTCOME_CODES.ENV_CAPABILITY_REMOTE]: "the earlier run ran in a remote sandbox that lacks a host-only capability (SOPS/age key, ops credentials, read-only prod monitor SSH); this host has it. Do the work that needed it now, with the host's own tools and credentials, and never print or commit a secret in the clear",
   [OUTCOME_CODES.ENV_REPRO_UNRUNNABLE]: "the repro harness could not run the contract's repro_test on head (timeout, missing runner or dependencies); the change may already be correct. Do not edit the deliverables or stub dependencies for it and never install anything globally: run the repro command through the repo's own toolchain and installed dependencies, and when it cannot run in this checkout, fix the repro_test command (not the code) so it does",
 });
 /** #4323/#4334: precheck failure codes that are environment errors (state "environment"), never a builder resume. */
-const ENV_CODES = Object.freeze([OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE]);
+const ENV_CODES = Object.freeze([OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.CONTRACT_INVALID_COMMAND]);
 export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
 /** forge.yaml engine.conformance: "shadow" (default) posts and logs the gate's verdict without enforcing it; "enforce" blocks on it. */
 export const CONFORMANCE_MODES = Object.freeze(["shadow", "enforce"]);
@@ -149,7 +152,8 @@ export function classifyBlock(result, issue) {
     return { kind: "split", rationale: gate.rationale, subissues, serialized: serializeShared(subissues) };
   }
   if (b.kind === "human") {
-    return HUMAN_BLOCK_REASONS.includes(b.why) ? { kind: "human", why: b.why }
+    const remainder = (Array.isArray(b.remainder) ? b.remainder : []).filter((x) => x && typeof x.title === "string" && x.title.trim() && typeof x.body === "string").slice(0, MAX_SUBISSUES).map((x) => ({ title: x.title.trim(), body: x.body })); // #4730
+    return HUMAN_BLOCK_REASONS.includes(b.why) ? { kind: "human", why: b.why, ...(remainder.length ? { remainder } : {}) }
       : { kind: "untyped", problem: `"${String(b.why ?? "").slice(0, 80)}" is not a human-only reason (${HUMAN_BLOCK_REASONS.join(", ")})` };
   }
   return { kind: "untyped", problem: `block kind "${String(b.kind ?? "").slice(0, 40)}" is unknown` };
@@ -198,6 +202,7 @@ export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, de
  * @param {string} [o.laneInstructions] forge.yaml engine.lane_instructions (#4395): repo-relative file appended to fresh sessions instead of CLAUDE.md
  * @param {number} [o.sparseMaxKb]   forge.yaml env.sparse_max_kb: tracked blobs >= this many KB stay out of the lane checkout (default 1024; 0 = off, #4221)
  * @param {object} [o.hostCaps]      {hostCapabilities, hostCapabilityPatterns}: forge.yaml execution.host_capabilities (#4542); a remote credentials block naming one is env.capability_remote
+ * @param {string[]} [o.relayCaps]   capabilities the dispatching host relays to this sandbox (#4778, env CS_RELAY_CAPS): no env.capability_remote end before building for them
  * @param {object} [o.placement]     {where: local|remote, reason, mode}: the dispatcher's lane placement (#4256), kept in FORGE:STATE
  * @param {object} [o.explore]       {mode: on|off, model}: forge.yaml lean.explore / lean.explore_model (#4391, default off): the explorer subagent
  * @param {object} [o.contextPack]   {mode: shadow|on|off, sources, bytes, days}: forge.yaml engine.context_pack* (#4275, default shadow)
@@ -480,9 +485,34 @@ export async function runCore(o) {
   }
   /** #4297/#4316: a recovery lane that ended unmerged keeps needs-human with this evidence (shared text in render.mjs). */
   const laneRecoveryEvidence = (reason, code, detail) => recoveryEvidence({ code: recover.code, attempt: recover.attempt, outcome: reason, resultCode: code, detail });
-  async function needsHuman(why, code = OUTCOME_CODES.ENGINE_ERROR, extra = {}) {
+  let closedDeps = []; // #4725: `Depends on` edges the live check found closed: satisfied, flagged in the needs-human comment
+  /** #4730: an issue whose only content is an ask already registered on #existing is closed as a duplicate, linked; any extra content keeps it open. */
+  async function duplicateAskIssue(existing, asks) {
+    try {
+      const v = JSON.parse(String(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "title,body"])));
+      if (!asks.some((a) => a && onlyAsk(v.title, v.body, a))) return false;
+      await ghw(["issue", "close", String(issue), "-R", repo, "--reason", "not planned", "--comment", `Duplicate owner ask: its only content is the ask already recorded on #${existing}. Answering #${existing} covers this issue.`]);
+      await label("invalid");
+      T.decisions.push(`Closed as a duplicate of the owner ask on #${existing}`);
+      return true;
+    } catch { return false; }
+  }
+  async function needsHuman(why, code = OUTCOME_CODES.ENGINE_ERROR, { ask: askText, note: askNote = "", ...extra } = {}) {
+    // #4725: a recorded premise (`Premise: <kind>:<arg>`) that already holds is no blocker: no label, the lane runs again.
+    const predicate = parsePredicate(why);
+    if (predicate && (!recover || recover.final) && await evalPredicate(predicate, { repo, io: { gh: ghc, pkgVersion: io.pkgVersion ?? registryPkgVersion } }) === true) {
+      try { await post("FORGE:DECISION", `## Decision: no needs-human\n**What**: the recorded premise \`${predicate.kind}:${predicate.arg}\` already holds, so the label was not applied.\n**Why**: the blocker named an external fact that has since changed.\n**Alternative**: label needs-human and wait for the sweep to clear it.`); } catch { /* best effort */ }
+      return finish("deferred", `premise ${predicate.kind}:${predicate.arg} holds; re-queued instead of needs-human`, { retryInSeconds: 30 });
+    }
     if (!recover || recover.final) try {
-      await post("FORGE:NEEDS_HUMAN", `## Needs human\n${why}${recoverUnlabelled ? `\n\n${laneRecoveryEvidence("needs-human", code, "")}` : ""}\n\n_${usageLine()}_`);
+      let link = "";
+      if (code === OUTCOME_CODES.BUILDER_BLOCKED) { // #4725: one owner ask, linked across issues
+        const reg = await registerAsk({ repo, io: { gh: ghc }, issue, ask: why });
+        if (reg.existing && (!recover || recover.final) && await duplicateAskIssue(reg.existing, [why, askText])) return finish("invalid", `only content is the owner ask of #${reg.existing}; closed as a duplicate`); // #4730
+        link = reg.existing ? `Same owner ask as #${reg.existing} (one ask, linked): answering it unblocks this issue too.` : reg.entry ?? "";
+      }
+      const notes = [premiseAnnotation(predicate), closedEdgeNote(closedDeps), link, askNote].filter(Boolean).join("\n");
+      await post("FORGE:NEEDS_HUMAN", `## Needs human\n${why}${notes ? `\n\n${notes}` : ""}${recoverUnlabelled ? `\n\n${laneRecoveryEvidence("needs-human", code, "")}` : ""}\n\n_${usageLine()}_`);
       await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]);
     } catch { /* best effort */ }
     return finish("needs-human", why, { code, ...extra, ...(recover ? { recovery: true } : {}) }, code);
@@ -812,7 +842,7 @@ export async function runCore(o) {
       // #4153 / #4337: a decomposed parent, open or closed, resolves to its open sub-issues; it is satisfied once they all
       // close. Without a usable trail the parent itself is the dependency, even when closed (fail closed).
       const decomposed = isDecomposedRecord(v) && ["OPEN", "CLOSED"].includes(String(v?.state).toUpperCase());
-      if (!decomposed && String(v?.state).toUpperCase() !== "OPEN") continue;
+      if (!decomposed && String(v?.state).toUpperCase() !== "OPEN") { if (String(v?.state).toUpperCase() === "CLOSED" && !closedDeps.includes(d)) closedDeps.push(d); continue; }
       const subs = decomposed ? await decomposedSubissues(d, io) : null;
       const recs = [];
       if (!subs) recs.push([d, { ...v, state: "OPEN" }]);
@@ -846,7 +876,18 @@ export async function runCore(o) {
       // #4685: a tool the sandbox lacks (docker, promtool, a Python module) is an environment gap the host recovers, never a credential.
       return await needsHuman(`Remote sandbox lacks a validate tool (Builder is blocked (credentials)): ${s}\n\nNot a credential: the lane is recovered where the tool exists.`, OUTCOME_CODES.ENV_TOOL_MISSING);
     }
-    if (b.kind === "human") return await needsHuman(`Builder is blocked (${b.why}): ${s}`, OUTCOME_CODES.BUILDER_BLOCKED);
+    if (b.kind === "human") {
+      // #4730: the agent-doable remainder is re-queued as its own lane; only the owner step keeps needs-human.
+      let note = "";
+      if (b.remainder?.length) {
+        try {
+          const filed = await fileRemainder({ repo, io: { gh: ghc, create: ghw }, issue, items: b.remainder, milestone });
+          T.decisions.push(`Builder block: remainder re-queued as ${refs(filed)}; #${issue} keeps only the owner step`);
+          note = `The agent-doable remainder was re-queued as ${refs(filed)}; this issue keeps only the owner step.`;
+        } catch (e) { return await finish("engine-error", `filing the remainder issues failed: ${e?.message ?? e}`); }
+      }
+      return await needsHuman(`Builder is blocked (${b.why}): ${s}`, OUTCOME_CODES.BUILDER_BLOCKED, { ask: s, note });
+    }
     if (b.kind === "unreadable") return await finish("dependency-unreadable", b.detail);
     if (b.kind === "dependency") {
       const blocked = b.blockers.length > 0;
@@ -1042,12 +1083,16 @@ export async function runCore(o) {
       }
     };
     if (resumed) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* remote branch may not exist (PR-less resume) */ } }
+    // #4786: an open-PR-less remote branch whose only changes vs the base are tool state (.forge-lean/ scratch) holds no work: plan fresh, never resume its stale contract.
+    const toolOnly = async (ref) => { const n = String(await io.git(["diff", "--name-only", `${base}...${ref}`], { cwd })).split("\n").map((x) => x.trim()).filter(Boolean); return n.every((f) => isToolState(f)); };
+    let scratchOnly = false;
+    if (resumed && !resumed.pr) { try { scratchOnly = await toolOnly(`origin/${branch}`); } catch { /* unreadable: resume as before */ } }
     // #4118: a local lane branch with commits not yet pushed (e.g. a reviewed commit whose push failed) must never be reset.
     // Reuse it when it is ahead of the base and contains everything the remote branch has.
     let keepLocal = false;
     try {
       const ahead = Number(String(await io.git(["rev-list", "--count", `${base}..refs/heads/${branch}`], { cwd })).trim());
-      if (ahead > 0) {
+      if (ahead > 0 && !(await toolOnly(`refs/heads/${branch}`).catch(() => false))) { // #4786: a scratch-only local branch is not reused
         let containsRemote = true;
         if (resumed) { try { await io.git(["merge-base", "--is-ancestor", `origin/${branch}`, `refs/heads/${branch}`], { cwd }); } catch { containsRemote = false; } }
         keepLocal = containsRemote;
@@ -1061,6 +1106,13 @@ export async function runCore(o) {
       ev({ event: "LOCAL_BRANCH_REUSED", branch });
     } else if (resumed) {
       wtInfo = await addWorktree(["worktree", "add", "-B", branch, wt, `origin/${branch}`], `origin/${branch}`);
+      if (scratchOnly) { // from origin/<branch> so the later plain push stays fast-forward; the scratch goes out in a normal commit
+        await io.git(["rm", "-r", "-f", "-q", "--ignore-unmatch", "--", LEAN_DIR], { cwd: wt }).catch(() => {});
+        if (String(await io.git(["diff", "--cached", "--name-only"], { cwd: wt }).catch(() => "")).trim()) await io.git(["commit", "--no-verify", "-m", "chore(forge): drop stale .forge-lean scratch from the lane branch"], { cwd: wt }).catch(() => {});
+        resumed = null;
+        ev({ event: "SCRATCH_BRANCH_DROPPED", branch });
+        T.decisions.push(`Lane branch ${branch} held only ${LEAN_DIR}/ scratch: its stale checkpoint was dropped and the issue is planned fresh`);
+      }
     } else {
       wtInfo = await addWorktree(["worktree", "add", "-B", branch, wt, base], base);
     }
@@ -1140,7 +1192,7 @@ export async function runCore(o) {
     // #4160: files the branch touched (three-dot) whose content still differs from the base tip (two-dot); a file merged
     // in from the base by a base-sync equals the base and drops out of the scope check.
     const changedFiles = async () => {
-      const touched = names(await git(["diff", "--name-only", `${base}...HEAD`]));
+      const touched = names(await git(["diff", "--name-only", `${base}...HEAD`])).filter((f) => !isToolState(f)); // #4786
       if (!touched.length) return touched;
       const differs = new Set(names(await git(["diff", "--name-only", base, "HEAD"])));
       return touched.filter((f) => differs.has(f));
@@ -1550,7 +1602,7 @@ export async function runCore(o) {
           }
         }
         await flushStages(result ?? { status: "fixed" }, ["investigation"]); // always posted: FORGE:INVESTIGATION/VALIDATE are read downstream
-        if (!vc.ok) return await needsHuman(`The builder's contract is still invalid after one correction:\n${vc.problems.slice(0, 12).map((x) => `- ${x}`).join("\n")}`, OUTCOME_CODES.CONTRACT_INVALID, issueEdited ? { issueEdited: true } : {});
+        if (!vc.ok) return await needsHuman(`The builder's contract is still invalid after one correction:\n${vc.problems.slice(0, 12).map((x) => `- ${x}`).join("\n")}`, OUTCOME_CODES.CONTRACT_INVALID, { ...(issueEdited ? { issueEdited: true } : {}), ...(vc.problems.every((x) => /: quote is not verbatim/.test(x)) ? { quoteMismatch: true } : {}) });
         frozen = historyRows(contract); // #4694 guards
         frozen = withDecisionRows(frozen, readDecisionIndex(repo)); // #4695: anchored decisions on the deliverable paths; one index read
         const hRows = (frozen.preserve ?? []).filter((p) => p.source === "decision");
@@ -1566,6 +1618,11 @@ export async function runCore(o) {
       } else {
         T.validate = lightDone ? "light lane (no plan session)" : "resumed (existing branch)";
       }
+      if (o.placement?.where === "remote" && !recover) { // #4785: the frozen validate commands need a tool only the host has
+        const relayed = new Set(o.relayCaps ?? []); // #4778: a relayed capability is served to the sandbox, so the lane builds there
+        const hn = contractHostNeeds(frozen, o.hostCaps && { ...o.hostCaps, hostCapabilities: (o.hostCaps.hostCapabilities ?? []).filter((c) => !relayed.has(c)) });
+        if (hn.caps.length) return await needsHuman(`Remote sandbox lacks host capability ${hn.caps.join(", ")}, which the frozen contract's validate command(s) ${hn.ids.join(", ")} need.\n\nThe dispatching host has it; the lane is recovered locally with the frozen contract.`, OUTCOME_CODES.ENV_CAPABILITY_REMOTE);
+      }
       T.plan = [`contract ${hash}${lightDone ? " (derived, light lane)" : ""}`, `${frozen.requirements.length} requirement(s)`];
       { // #4392, #4505: next size on a budget recovery; #4587: a big L contract and an L recovery get extra turns
         const sz = recoverySize(laneSize({ contract: frozen, labels: (iss?.labels ?? []).map((l) => l?.name ?? l) }), recover);
@@ -1740,7 +1797,21 @@ export async function runCore(o) {
       ev({ event: "SEQUENCE_COLLISION", trigger, files: collisions.map((c) => c.lane) });
       const taken = collisions.filter((c) => c.base.length).map((c) => `${c.lane} vs ${c.base.join(", ")}`).join("; ");
       if (io.sequenceRenumber) {
-        const det = (await io.sequenceRenumber({ cwd: wt, base, ...(laneRef ? { laneRef } : {}), regenerate: o.sequenceRegenerate ?? null, reserve: io.sequenceLease?.reserve ? (x) => io.sequenceLease.reserve({ repo, lane, issue, ...x }) : null }).catch((e) => ({ unsupported: String(e?.message ?? e) }))) ?? { unsupported: "no result" };
+        const renumber = async (ref) => (await io.sequenceRenumber({ cwd: wt, base, ...(ref ? { laneRef: ref } : {}), regenerate: o.sequenceRegenerate ?? null, reserve: io.sequenceLease?.reserve ? (x) => io.sequenceLease.reserve({ repo, lane, issue, ...x }) : null, openNumbers: io.sequenceOpenNumbers ? (x) => io.sequenceOpenNumbers({ cwd: wt, lane, ...x }) : null }).catch((e) => ({ unsupported: String(e?.message ?? e) }))) ?? { unsupported: "no result" };
+        let det = await renumber(laneRef);
+        if (det.nonSequence?.length && !laneRef) { // #4732: base-sync first (sequence files take the base side, the builder resolves the rest), then renumber deterministically
+          const pre = String(await git(["rev-parse", "HEAD"])).trim(), left = async () => String(await git(["diff", "--name-only", "--diff-filter=U"]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean);
+          let synced = true;
+          try { await git(["merge", "--no-edit", base]); } catch {
+            const rs = await io.sequenceResolve?.({ cwd: wt, files: await left(), partial: true }).catch(() => null);
+            if (rs?.remaining?.length) {
+              T.decisions.push(`Sequence renumber (${trigger}): base-sync conflicts in ${rs.remaining.join(", ")}; builder resolves, then the engine renumbers`);
+              await fixRound("sequence", sequenceSyncPrompt(base, rs.remaining, vcfg.mode), [], "sequence", `base-sync conflict: ${rs.remaining.join(", ")}`);
+            } else synced = Boolean(rs?.ok);
+            if (!synced || (await left()).length) { try { await git(["merge", "--abort"]); } catch { /* none */ } try { await git(["reset", "-q", "--hard", pre]); } catch { /* best effort */ } synced = false; }
+          }
+          if (synced) { det = await renumber(pre); if (det.ok) ev({ event: "SEQUENCE_SYNC_FIRST", trigger, files: det.moves?.length ?? 0 }); }
+        }
         if (det.ok && det.moves?.length) {
           ev({ event: "SEQUENCE_RENUMBERED", trigger, mode: "deterministic", moves: det.moves });
           T.decisions.push(`Sequence number(s) taken on ${lane} (${trigger}): ${taken}; renumbered deterministically (no builder): ${det.moves.map((m) => `${m.from} → ${m.to}`).join(", ")}`);
@@ -2058,6 +2129,13 @@ export async function runCore(o) {
         if (!r || r.exit === undefined || r.exit === 0) continue;
         let x;
         try { x = await heavyStep("precheck", async () => (await runWithTimeoutRetry((timeoutMs) => io.runCommand({ command: String(v.command), cwd: wt, timeoutMs, env }), vcfg.precheckTimeoutSeconds * 1000)).r); } catch (e) { x = { rc: 127, output: String(e?.message ?? e) }; }
+        // #4761: a runner usage error (vitest -q) is the frozen command's defect: try the normalised command once
+        const fixed = cliUsageError(x ?? {}) ? normalizeRunnerCommand(v.command) : null;
+        if (fixed && fixed !== String(v.command)) {
+          try { x = await heavyStep("precheck", async () => (await runWithTimeoutRetry((timeoutMs) => io.runCommand({ command: fixed, cwd: wt, timeoutMs, env }), vcfg.precheckTimeoutSeconds * 1000)).r); } catch (e) { x = { rc: 127, output: String(e?.message ?? e) }; }
+          const note = `Validate ${v.id} hit a runner usage error; reran normalised (\`${fixed}\`): exit ${x?.rc}`;
+          if (!T.decisions.includes(note)) T.decisions.push(note);
+        }
         out[v.id] = { rc: Number.isInteger(x?.rc) ? x.rc : 1, output: String(x?.output ?? "") };
       }
       if (Object.keys(out).length) ev({ event: "VALIDATE_RERUN", runs: Object.entries(out).map(([id, x]) => ({ id, rc: x.rc })) });
@@ -2081,6 +2159,11 @@ export async function runCore(o) {
       return r.failures;
     }
     /** Precheck then review, on the current result and changed files (also the base-sync re-review). */
+    /** #4769: default-off keys the diff adds to the forge.yaml `rollouts` registry; [] when none is declared. */
+    async function newOffKeysOf() {
+      const cfg = readRollouts(wt);
+      return cfg ? detectNewOffKeys(cfg, String(await git(["diff", "-U0", `${base}...HEAD`, "--", ...cfg.files]).catch(() => ""))) : [];
+    }
     async function gate() {
       await refreshIssue("conformance");
       result = (await readResult()) ?? result;
@@ -2106,7 +2189,7 @@ export async function runCore(o) {
       const repoHas = validateRuns && Object.keys(validateRuns).length ? repoTracks(String(await git(["ls-files"]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean)) : undefined;
       // #4626: post-deploy check ids resolve against the lane base's checks file or this PR's
       const checkIds = effective.requirements?.some((r) => r.disposition === "post-deploy") ? new Set(Object.keys(await checksAt(git, [base, "HEAD"], wt))) : null;
-      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures });
+      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures, newOffKeys: await newOffKeysOf() });
       // #4350: a scope-check validate stale only by amended deliverables is judged by the engine's scope gate instead
       if (pc.superseded?.length) {
         ev({ event: "VALIDATE_SUPERSEDED", runs: pc.superseded });
@@ -2186,6 +2269,10 @@ export async function runCore(o) {
         T.anomalies.push("Environment error: the repro harness could not run the repro test on head");
         return await needsHuman(`Environment error (not a conformance failure): the repro harness could not run the repro test on head; no builder resume was spent and nothing merged:\n${failures.map((f) => `- ${f.code}: ${f.detail}`).join("\n")}\n\nRun the repro command through the repo's own toolchain and installed dependencies, then rerun.`, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE);
       }
+      if (failures.every((f) => f.code === OUTCOME_CODES.CONTRACT_INVALID_COMMAND)) {
+        T.anomalies.push("Contract defect: a frozen validate command is a runner CLI usage error");
+        return await needsHuman(`Contract defect (not a conformance failure): a frozen validate command is rejected by its runner's CLI, so no builder resume was spent and nothing merged:\n${failures.map((f) => `- ${f.code}: ${f.detail}`).join("\n")}\n\nRecovery re-plans the command (vitest: --reporter=dot, not -q).`, OUTCOME_CODES.CONTRACT_INVALID_COMMAND);
+      }
       const tools = [...new Set(failures.filter((f) => f.tool).map((f) => f.tool))].join(", ");
       T.anomalies.push(`Environment error: validate command(s) could not run, the host is missing ${tools}`);
       return await needsHuman(`Environment error (not a conformance failure): the host is missing ${tools}, so validate command(s) could not run; no builder resume was spent and nothing merged:\n${failures.map((f) => `- ${f.code}: ${f.detail}`).join("\n")}\n\nInstall it on the host or run the check through the repo's own toolchain, then rerun.`, OUTCOME_CODES.ENV_TOOL_MISSING);