forgedock 1.37.0 → 1.38.1

package/bin/lean/admission.mjs

@@ -6,7 +6,7 @@
  */
 // #4169: load average lags by minutes and is phase-blind, so it is off unless configured; heavy steps are gated by
 // the host heavy-step semaphore (heavy.mjs) instead. An explicit `max_load_per_core` is still honoured.
-export const ADMISSION_DEFAULTS = Object.freeze({ enabled: true, min_free_mem_mb: 2048, min_free_tmp_mb: 1024, max_load_per_core: null });
+export const ADMISSION_DEFAULTS = Object.freeze({ enabled: true, min_free_mem_mb: 2048, min_free_tmp_mb: 1024, max_load_per_core: null, lane_cpu_reservation: 1, lane_mem_mb: 2048 });
 export const ADMISSION_RETRY_SECONDS = 60;
 
 /** Workers one verification step may use (#4182): max(1, floor(cores / lanes)); bad inputs count as 1. Heavy shims pass live heavy holders (#4169). */
@@ -15,6 +15,22 @@ export function hostParallelism({ cores, lanes } = {}) {
   return Math.max(1, Math.floor(c / l));
 }
 
+/**
+ * Local lane cap (#4777): how many lanes this host can run at once, from cores and free memory:
+ * max(1, min(floor(cores / lane_cpu_reservation), floor((memAvailableMb - min_free_mem_mb) / lane_mem_mb))). Evaluated per
+ * admission attempt, so it follows the host as lanes come and go; an unknown probe leaves that bound off, and with both
+ * unknown (or admission disabled) it is null (no derived cap).
+ */
+export function localLaneCap({ cfg = {}, cores, memAvailableMb } = {}) {
+  const c = { ...ADMISSION_DEFAULTS, ...Object.fromEntries(Object.entries(cfg ?? {}).filter(([, v]) => v !== undefined && v !== null)) };
+  if (c.enabled === false) return null;
+  const pos = (v, d) => (Number.isFinite(v) && v > 0 ? v : d);
+  const bounds = [];
+  if (Number.isFinite(cores) && cores > 0) bounds.push(Math.floor(cores / pos(c.lane_cpu_reservation, 1)));
+  if (Number.isFinite(memAvailableMb)) bounds.push(Math.floor((memAvailableMb - pos(c.min_free_mem_mb, 0)) / pos(c.lane_mem_mb, 2048)));
+  return bounds.length ? Math.max(1, Math.min(...bounds)) : null;
+}
+
 const gb = (mb) => { const g = mb / 1024; return `${Number.isInteger(g) ? g : g.toFixed(1)}G`; };
 
 /**

package/bin/lean/batch.mjs

@@ -15,7 +15,7 @@
  * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path. These
  * detached lanes are the `local` execution (#4253); `execution.mjs` is the sandbox-provider seam for remote lanes.
  */
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
@@ -54,15 +54,30 @@ export function assertDiskPath(path, mounts = readMounts()) {
   if (RAM_FS.has(type)) throw new Error(`batch state must be on disk, but ${path} is on ${type}; set FORGEDOCK_BATCH_DIR to a disk path`);
 }
 
-/** Write `data` to `file` atomically: a reader sees the old or the new content, never a truncated file. */
-export function writeAtomic(file, data) {
-  mkdirSync(dirname(file), { recursive: true });
+/**
+ * Write `data` to `file` atomically: a reader sees the old or the new content, never a truncated file.
+ * `private` creates the file 0600 and its directory 0700 (batch state can hold pinned secrets, #4751).
+ */
+export function writeAtomic(file, data, { private: priv = false } = {}) {
+  const dir = dirname(file);
+  mkdirSync(dir, priv ? { recursive: true, mode: 0o700 } : { recursive: true });
+  if (priv) chmodSync(dir, 0o700);
   const tmp = `${file}.tmp-${process.pid}`;
-  const fd = openSync(tmp, "w");
-  try { writeSync(fd, data); fsyncSync(fd); } finally { closeSync(fd); }
+  const fd = priv ? openSync(tmp, "w", 0o600) : openSync(tmp, "w");
+  try { if (priv) fchmodSync(fd, 0o600); writeSync(fd, data); fsyncSync(fd); } finally { closeSync(fd); }
   renameSync(tmp, file);
 }
 
+/** Env names whose values never reach batch state (#4787): tokens, keys, secrets and passwords. */
+export const SECRET_ENV = /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|PRIVATE_?KEY|(^|_)KEY$)/i;
+
+/** @returns {{env: object, names: string[]}} `env` without secret-named keys, and the dropped names (never values). */
+export function scrubEnv(env) {
+  if (!env || typeof env !== "object") return { env, names: [] };
+  const names = Object.keys(env).filter((k) => SECRET_ENV.test(k)).sort();
+  return { env: names.length ? Object.fromEntries(Object.entries(env).filter(([k]) => !SECRET_ENV.test(k))) : env, names };
+}
+
 const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
 
 const readAdded = (file) => {
@@ -71,7 +86,7 @@ const readAdded = (file) => {
 };
 
 /** `outcome`s `--requeue` may move back to pending (#4550). */
-export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded"].includes(outcome) || /^dependency-/.test(String(outcome));
+export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded", "lane-refused"].includes(outcome) || /^dependency-/.test(String(outcome));
 /** Key of one requeue entry; the runner records the applied keys in state.json `requeueApplied`. */
 export const requeueKey = (e) => `${e.issue}@${e.at}`;
 
@@ -99,21 +114,36 @@ export function openBatch(root, id) {
   if (!ID_RE.test(String(id ?? ""))) throw new Error(`invalid batch id ${JSON.stringify(id)}`);
   const dir = join(root, id);
   const f = (name) => join(dir, name);
+  const put = (file, data) => writeAtomic(file, data, { private: true });
   const self = {
     id, dir,
     exists: () => existsSync(f("plan.json")),
     readPlan: () => readJson(f("plan.json")),
-    writePlan: (plan) => writeAtomic(f("plan.json"), JSON.stringify(plan, null, 2) + "\n"),
+    /** Secret-named `plan.env` keys are never written: their names go to `envSecrets`, the value is re-read from the environment on resume (#4787). */
+    writePlan: (plan) => {
+      const { env, names } = scrubEnv(plan?.env);
+      const out = names.length ? { ...plan, env, envSecrets: [...new Set([...(plan.envSecrets ?? []), ...names])].sort() } : plan;
+      put(f("plan.json"), JSON.stringify(out, null, 2) + "\n");
+    },
+    /** Rewrite an existing plan.json that holds secret env values (or is not 0600) as private and scrubbed; @returns the scrubbed names. */
+    scrubPlan: () => {
+      const plan = readJson(f("plan.json"));
+      if (!plan) return [];
+      const { names } = scrubEnv(plan.env);
+      if (names.length) self.writePlan(plan);
+      else { try { chmodSync(f("plan.json"), 0o600); } catch { /* best effort */ } }
+      return names;
+    },
     store: {
       load: () => readJson(f("state.json")),
-      save: (state) => writeAtomic(f("state.json"), JSON.stringify(state) + "\n"),
-      log: (row) => { try { appendFileSync(f("log.jsonl"), JSON.stringify({ at: new Date().toISOString(), ...row }) + "\n"); } catch { /* the log is advisory */ } },
+      save: (state) => put(f("state.json"), JSON.stringify(state) + "\n"),
+      log: (row) => { try { appendFileSync(f("log.jsonl"), JSON.stringify({ at: new Date().toISOString(), ...row }) + "\n", { mode: 0o600 }); } catch { /* the log is advisory */ } },
     },
     /** Live K: the `parallel` file, read on every scheduler pass; null when missing or invalid. */
     readParallel: () => { try { const k = parseInt(readFileSync(f("parallel"), "utf8"), 10); return Number.isInteger(k) && k >= 1 ? k : null; } catch { return null; } },
     setParallel: (k) => {
       if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
-      writeAtomic(f("parallel"), `${k}\n`);
+      put(f("parallel"), `${k}\n`);
     },
     /** Issues added by `--add` (#4408): the `add` file, sorted unique positive integers; [] when missing or invalid. */
     readAdded: () => readAdded(f("add")),
@@ -128,12 +158,12 @@ export function openBatch(root, id) {
       for (const x of Array.isArray(list) ? list : []) {
         const n = typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN;
         if (!Number.isSafeInteger(n) || n < 1) { skipped.push({ issue: x, reason: "not an integer" }); continue; }
-        // #4687: an issue skipped in the batch (a dependency ended) is re-queued, not refused; any other row is "already in batch"
-        if (have.has(n) && st.results?.[n]?.outcome === "skipped" && !requeued.includes(n) && self.requeue([n], { reason: "--add", by: "operator" }).requeued.length) { requeued.push(n); continue; }
+        // #4687/#4791: an issue skipped (a dependency ended) or lane-refused in the batch is re-queued, not refused; any other row is "already in batch"
+        if (have.has(n) && ["skipped", "lane-refused"].includes(st.results?.[n]?.outcome) && !requeued.includes(n) && self.requeue([n], { reason: "--add", by: "operator" }).requeued.length) { requeued.push(n); continue; }
         if (have.has(n)) { skipped.push({ issue: n, reason: "already in batch" }); continue; }
         have.add(n); added.push(n);
       }
-      if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
+      if (added.length) put(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
       return { added, skipped, requeued };
     },
     /**
@@ -157,7 +187,7 @@ export function openBatch(root, id) {
       }
       if (requeued.length) {
         const at = new Date().toISOString();
-        writeAtomic(f("requeue"), JSON.stringify([...entries, ...requeued.map((issue) => ({ issue, reason: String(reason), by: String(by), at }))]) + "\n");
+        put(f("requeue"), JSON.stringify([...entries, ...requeued.map((issue) => ({ issue, reason: String(reason), by: String(by), at }))]) + "\n");
       }
       return { requeued, refused };
     },
@@ -173,18 +203,18 @@ export function openBatch(root, id) {
     holdIssues: (list) => {
       const have = new Set(readAdded(f("hold")));
       const added = [...new Set(ints(list))].filter((n) => !have.has(n)).sort((a, b) => a - b);
-      if (added.length) writeAtomic(f("hold"), JSON.stringify([...have, ...added].sort((a, b) => a - b)) + "\n");
+      if (added.length) put(f("hold"), JSON.stringify([...have, ...added].sort((a, b) => a - b)) + "\n");
       return added;
     },
     /** Remove `list` from the `hold` file. @returns {number[]} the issues that were held */
     releaseIssues: (list) => {
       const have = new Set(readAdded(f("hold")));
       const freed = [...new Set(ints(list))].filter((n) => have.has(n)).sort((a, b) => a - b);
-      if (freed.length) writeAtomic(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
+      if (freed.length) put(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
       return freed;
     },
     /** `--cancel` (#4376): `{at, reason, stopRemote?}` in the `cancel` file; the runner re-reads it every pass. `stopRemote` (#4612) also asks remote lanes to stop at their checkpoint. */
-    requestCancel: ({ reason = "operator", stopRemote = false } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason), ...(stopRemote === true ? { stopRemote: true } : {}) }) + "\n"),
+    requestCancel: ({ reason = "operator", stopRemote = false } = {}) => put(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason), ...(stopRemote === true ? { stopRemote: true } : {}) }) + "\n"),
     /** The cancel record, or null when missing or invalid. */
     readCancel: () => { const v = readJson(f("cancel")); return v && typeof v === "object" && !Array.isArray(v) && typeof v.at === "string" ? v : null; },
     clearCancel: () => rmSync(f("cancel"), { force: true }),
@@ -197,7 +227,7 @@ export function openBatch(root, id) {
       return text.split("\n").flatMap((l) => { try { return l ? [JSON.parse(l)] : []; } catch { return []; } });
     },
     readReport: () => readJson(f("report.json")),
-    writeReport: (report) => writeAtomic(f("report.json"), JSON.stringify(report) + "\n"),
+    writeReport: (report) => put(f("report.json"), JSON.stringify(report) + "\n"),
     clearReport: () => rmSync(f("report.json"), { force: true }),
     resultFile: (n) => f(join("lanes", `${n}.json`)),
     logFile: (n) => f(join("lanes", `${n}.log`)),
@@ -224,9 +254,9 @@ export function isLaneAlive(pid, marker, { kill = process.kill.bind(process), pr
  */
 export function launchLane({ batch, issue, args = [], bin = process.execPath, script, cwd = process.cwd(), env = process.env, spawnFn = spawn }) {
   const rf = batch.resultFile(issue);
-  mkdirSync(dirname(rf), { recursive: true });
+  mkdirSync(dirname(rf), { recursive: true, mode: 0o700 });
   rmSync(rf, { force: true });
-  const out = openSync(batch.logFile(issue), "a");
+  const out = openSync(batch.logFile(issue), "a", 0o600);
   try {
     // FORGEDOCK_BATCH_ID names the lane's resource ledger dir (~/.forge/ledger/<batch>/, #4179).
     const child = spawnFn(bin, [script, "run-issue", String(issue), ...args, "--result-file", rf], { cwd, env: { ...env, FORGEDOCK_BATCH_ID: batch.id }, detached: true, stdio: ["ignore", out, out] });

package/bin/lean/batch.test.mjs

@@ -3,7 +3,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { orchestrate, deferPolicy, DEFER_BACKOFF_S, formatOutcomeLists } from "./orchestrate.mjs";
@@ -261,9 +261,9 @@ await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--
     assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), true);
     writeFileSync(join(pd, "stat"), "42 (no) de) Z 1 42 42 0 -1\n");
     assert.equal(isLaneAlive(42, "lane", { kill: () => true, procDir: proc }), false);
-    assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3, blockedLabel: "blocked", globalParallel: null, recovery: { maxAttempts: 1, mechanicalMaxAttempts: 2 }, baseSync: { enabled: true, unionGlobs: [] } });
     writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n  global_parallel: 4\n");
-    assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2, globalParallel: 4, recovery: { maxAttempts: 1 }, baseSync: { enabled: true, unionGlobs: [] } });
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2, blockedLabel: "blocked", globalParallel: 4, recovery: { maxAttempts: 1, mechanicalMaxAttempts: 2 }, baseSync: { enabled: true, unionGlobs: [] } });
   });
 
   it("run-issue --result-file writes the lane result, also when the run throws", async () => {
@@ -340,12 +340,12 @@ describe("#4318: the batch dispatcher's signal relabel and the needs-human relab
     it("an expired lease relabels: the label first, then the comment", async () => {
       const h = hook({ state: "OPEN", body: LIVE(500) });
       assert.equal(await h.run(), true);
-      assert.deepEqual(h.calls, ["view", "edit", "comment"]);
+      assert.deepEqual(h.calls, ["view", "list", "edit", "comment"]); // #4725: the ask registry lookup
     });
     it("a failed label add posts no comment and reports failed; a failed comment keeps the label", async () => {
       const a = hook({ state: "OPEN", body: "" }, { edit: true });
       assert.equal(await a.run(), "failed");
-      assert.deepEqual(a.calls, ["view", "edit"]);
+      assert.deepEqual(a.calls, ["view", "list", "edit"]);
       const b = hook({ state: "OPEN", body: "" }, { comment: true });
       assert.equal(await b.run(), true);
     });
@@ -488,6 +488,30 @@ describe("#4408: issues added to a running batch (forgedock orchestrate --add)",
     assert.deepEqual(plain.map((r) => r.issue), [1]);
   });
 
+  it("#4791 --requeue and --add accept a lane-refused issue", () => {
+    const b = openBatch(tmpDir("batch-lane-refused-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1, 2], results: { 1: { outcome: "lane-refused", code: "lane.unresolved" }, 2: { outcome: "lane-refused" } } });
+    assert.deepEqual(b.requeue([1]).requeued, [1]);
+    assert.deepEqual(b.addIssues([2]).requeued, [2]);
+  });
+
+  it("#4791 a transient lane-resolution failure is retried with backoff, never capped, and not terminal", async () => {
+    const { now, sleep } = fakeClock();
+    const updates = [];
+    let tries = 0;
+    const launched = [];
+    const rows = await orchestrate({ issues: [1], readBody: async () => "", now, sleep, maxDeferrals: 1, onUpdate: (r) => updates.push(r),
+      resolveLane: async () => (++tries <= 3 ? { ok: false, code: "lane.unresolved", detail: "TLS handshake timeout", transient: true } : { ok: true, lane: "staging" }),
+      runOne: async (n, lane) => { launched.push(lane); return { terminalReason: "merged", pr: 5 }; } });
+    assert.equal(rows[0].outcome, "merged");
+    assert.deepEqual(launched, ["staging"]);
+    assert.ok(updates.some((u) => /requeued in 120s: lane.unresolved/.test(u.detail ?? "")));
+    assert.ok(updates.some((u) => /requeued in 240s: lane.unresolved/.test(u.detail ?? "")));
+    const hard = await orchestrate({ issues: [2], readBody: async () => "", now, sleep, resolveLane: async () => ({ ok: false, code: "lane.branch_missing", detail: "x" }), runOne: async () => { throw new Error("no"); } });
+    assert.equal(hard[0].outcome, "lane-refused");
+  });
+
   it("#4687 --add re-queues an issue that is skipped in the batch; any other ended issue stays 'already in batch'", () => {
     const root = tmpDir("batch-add-skipped-");
     const b = openBatch(root, "b1");
@@ -787,6 +811,7 @@ describe("#4528: a full sandbox pool (sandbox.capacity) is never capped", () =>
   it("sandbox.capacity is uncapped and honours retryInSeconds; other codes still cap at maxDeferrals", () => {
     assert.deepEqual(deferPolicy({ code: "sandbox.capacity" }, { now: 0, deferrals: 99 }), { delayMs: 60000, host: true });
     assert.deepEqual(deferPolicy({ code: "sandbox.capacity", retryInSeconds: 30 }, { now: 0, deferrals: 99, maxDeferrals: 3 }), { delayMs: 30000, host: true });
+    assert.deepEqual(deferPolicy({ code: "sandbox.unreachable", retryInSeconds: 60 }, { now: 0, deferrals: 99, maxDeferrals: 3 }), { delayMs: 60000, host: true }); // #4788
     for (const code of ["merge.transient", "gh.unavailable", "cli.idle", "rate_limited", "sandbox.start_failed"]) {
       assert.deepEqual(deferPolicy({ code, retryInSeconds: 60 }, { now: 0, deferrals: 3, maxDeferrals: 3 }), { capped: true }, code);
     }
@@ -943,6 +968,29 @@ describe("#4547: opt-in local fallback in mode remote when no pool agent is onli
   });
 });
 
+describe("#4788: a pool offline for longer than N minutes is reported once", () => {
+  const run = async (onlineAt) => {
+    const c = { t: 1_000_000 };
+    const sleep = async (ms) => { await new Promise((r) => setImmediate(r)); c.t += ms; };
+    const events = [];
+    let tries = 0;
+    await orchestrate({ issues: [1], parallel: 1, now: () => c.t, sleep, pollMs: 1, readBody: async () => "", onUpdate: (row) => events.push(row),
+      remote: { max: 1, isRemote: () => true, poolOfflineMin: 1, capacity: () => ({ free: null, online: onlineAt(c.t), at: 1 }) },
+      runOne: async () => { tries++; if (tries < 80) { c.t += 5000; return { terminalReason: "deferred", code: "sandbox.unreachable", retryInSeconds: 1, detail: "HTTP 502" }; } return { terminalReason: "merged", pr: 1 }; } });
+    return { events, tries };
+  };
+  it("zero live agents past the limit: one pool-offline event; unreachable never gives up", async () => {
+    const { events, tries } = await run(() => 0);
+    assert.equal(events.filter((e) => e.outcome === "pool-offline").length, 1);
+    assert.equal(tries, 80);
+    assert.equal(events.some((e) => /gave up/.test(e.detail ?? "")), false);
+  });
+  it("an agent online: no event", async () => {
+    const { events } = await run(() => 1);
+    assert.equal(events.some((e) => e.outcome === "pool-offline"), false);
+  });
+});
+
 describe("#4592: forgedock orchestrate --hold / --release", () => {
   it("the hold file: holdIssues / readHeld / releaseIssues merge sorted unique positive integers; invalid content reads as []", () => {
     const b = openBatch(tmpDir("batch-hold-"), "b1");
@@ -1009,3 +1057,45 @@ describe("#4592: forgedock orchestrate --hold / --release", () => {
     assert.deepEqual(b.readAdded(), [], "an issue already in the batch is not added again");
   });
 });
+
+describe("#4751: batch state is private", () => {
+  it("batch state files are private", () => {
+    const root = tmpDir("batch-private");
+    const old = process.umask(0o022);
+    try {
+      mkdirSync(join(root, "b1"), { mode: 0o755 });
+      const b = openBatch(root, "b1");
+      b.writePlan({ argv: ["1"], env: { TOKEN: "s3cret" } });
+      b.store.save({ v: 1 });
+      b.store.log({ ev: "x" });
+      const mode = (p) => statSync(p).mode & 0o777;
+      assert.equal(mode(b.dir), 0o700);
+      assert.equal(mode(join(b.dir, "plan.json")), 0o600);
+      assert.equal(mode(join(b.dir, "state.json")), 0o600);
+      assert.equal(mode(join(b.dir, "log.jsonl")), 0o600);
+      writeAtomic(join(root, "plain.json"), "{}");
+      assert.equal(mode(join(root, "plain.json")), 0o644);
+    } finally { process.umask(old); }
+  });
+});
+
+describe("batch plan secrets (#4787)", () => {
+  it("writePlan never writes secret env values and keeps the plan 0600", () => {
+    const b = openBatch(join(tmpDir("batch-sec-"), "batches"), "b20260101-000000-1");
+    b.writePlan({ v: 1, env: { PATH: "/bin", COMPUTESHARE_TOKEN: "tok-123", AWS_ACCESS_KEY: "k-456" } });
+    const raw = readFileSync(join(b.dir, "plan.json"), "utf8");
+    assert.ok(!raw.includes("tok-123") && !raw.includes("k-456"));
+    assert.deepEqual(b.readPlan().env, { PATH: "/bin" });
+    assert.deepEqual(b.readPlan().envSecrets, ["AWS_ACCESS_KEY", "COMPUTESHARE_TOKEN"]);
+    assert.equal(statSync(join(b.dir, "plan.json")).mode & 0o777, 0o600);
+  });
+  it("scrubPlan rewrites a pre-fix 0644 plan and is a no-op otherwise", () => {
+    const b = openBatch(join(tmpDir("batch-sec-"), "batches"), "b20260101-000000-2");
+    mkdirSync(b.dir, { recursive: true });
+    writeFileSync(join(b.dir, "plan.json"), JSON.stringify({ v: 1, env: { PATH: "/bin", COMPUTESHARE_TOKEN: "tok-123" } }), { mode: 0o644 });
+    assert.deepEqual(b.scrubPlan(), ["COMPUTESHARE_TOKEN"]);
+    assert.ok(!readFileSync(join(b.dir, "plan.json"), "utf8").includes("tok-123"));
+    assert.equal(statSync(join(b.dir, "plan.json")).mode & 0o777, 0o600);
+    assert.deepEqual(b.scrubPlan(), []);
+  });
+});

package/bin/lean/conformance.mjs

@@ -9,6 +9,7 @@
  */
 import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
 import { noComments } from "./context.mjs";
+import { activationFailures } from "./activation.mjs";
 
 export const DISPOSITIONS = Object.freeze(["deliver", "defer", "not-applicable", "post-deploy"]);
 /** Dispositions the engine files as a tracked follow-up issue before anything merges. */
@@ -31,7 +32,33 @@ import { CHECK_ID_RE } from "./postdeploy-check.mjs";
 import { normaliseDecision, deadAnchors } from "./decisions.mjs";
 const C = OUTCOME_CODES;
 
-export const norm = (s) => String(s ?? "").replace(/[`*_>]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+/** #4789: folds what a builder retyping a quote changes: unicode punctuation, markdown links/markup, escapes, invisible chars. */
+export const norm = (s) => String(s ?? "")
+  .normalize("NFKC")
+  .replace(/[\u200b-\u200d\u2060\ufeff\u00ad]/g, "")
+  .replace(/[\u2018\u2019\u201a\u201b\u2032]/g, "'").replace(/[\u201c\u201d\u201e\u201f\u2033]/g, '"')
+  .replace(/[\u2010-\u2015\u2212]/g, "-").replace(/\u2026/g, "...")
+  .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+  .replace(/\\([^A-Za-z0-9\s])/g, "$1")
+  .replace(/[`*_>~#]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+const WORD_RE = /[a-z0-9]{3,}/g;
+/** The issue line sharing the most words with a quote that missed (for the correction prompt); "" when none shares any. */
+export function nearestSpan(quote, issueText) {
+  const qw = new Set(norm(quote).match(WORD_RE) ?? []);
+  let best = "", bestN = 0;
+  for (const l of String(issueText ?? "").split("\n")) {
+    const n = norm(l);
+    if (!n) continue;
+    let hit = 0;
+    for (const w of new Set(n.match(WORD_RE) ?? [])) if (qw.has(w)) hit++;
+    if (hit > bestN) { bestN = hit; best = l.trim(); }
+  }
+  return bestN >= 2 ? best.slice(0, 120) : "";
+}
+const quoteMiss = (id, quote, issueText) => {
+  const near = nearestSpan(quote, issueText);
+  return `${id}: quote is not verbatim from the issue (at least ${MIN_QUOTE_CHARS} characters)${near ? `; nearest issue text: "${near}"` : ""}`;
+};
 const ITEM_PREFIX_RE = /^\s*(?:[-*+]\s+)?(?:\[[ xX]\]\s+)?(?:\d+[.)]\s+)?/;
 /**
  * A quote must be verbatim (whitespace and markdown emphasis aside) from the issue text: a substring of at least
@@ -231,7 +258,7 @@ export function validateContract(c, issueText, { repro = false } = {}) {
     if (!id || ids.has(id)) problems.push(`requirement id missing or duplicated: ${id}`);
     ids.add(id);
     if (!DISPOSITIONS.includes(r?.disposition)) problems.push(`${id}: disposition must be one of ${DISPOSITIONS.join("|")}`);
-    if (!inIssue(r?.quote, issueText)) problems.push(`${id}: quote is not verbatim from the issue (at least ${MIN_QUOTE_CHARS} characters)`);
+    if (!inIssue(r?.quote, issueText)) problems.push(quoteMiss(id, r?.quote, issueText));
     if (TRACKED.includes(r?.disposition) && blank(r?.why)) problems.push(`${id}: ${r.disposition} needs a why`);
     if (r?.disposition === "post-deploy" && !CHECK_ID_RE.test(String(r?.check ?? ""))) problems.push(`${id}: post-deploy needs a check id (\`check\`, e.g. "login-smoke") naming an entry of .forge/post-deploy-checks.json on the default branch`);
     if (r?.disposition === "not-applicable" && blank(r?.evidence)) problems.push(`${id}: not-applicable needs file:line evidence`);
@@ -257,12 +284,16 @@ export function validateContract(c, issueText, { repro = false } = {}) {
     const ref = movingBaseDiff(v.command);
     if (ref) problems.push(`${v.id}: \`git diff\` against the moving ${ref} tip fails as soon as the base moves on, even when the change is fine; compare against the merge base instead (\`${ref}...HEAD\` or \`$(git merge-base HEAD ${ref})\`)`);
     for (const p of tmpdirInputs(v.command)) problems.push(tmpInputProblem(v.id, p));
+    if (vitestQuietFlag(v.command)) problems.push(`${v.id}: vitest 3 rejects -q/--quiet (usage error before any test runs); use --reporter=dot`);
   }
   if (repro) {
     const t = c.repro_test;
     if (t === "none") { if (blank(c.repro_test_reason)) problems.push(`repro_test "none" needs a one-line repro_test_reason`); }
     else if (!t || typeof t !== "object" || Array.isArray(t) || blank(t.path) || blank(t.command)) problems.push(`this is a bug: repro_test must be {"path","id","command"} (a test that fails on the base and passes after the fix) or "none" with a repro_test_reason`);
-    else for (const p of tmpdirInputs(t.command)) problems.push(tmpInputProblem("repro_test", p));
+    else {
+      for (const p of tmpdirInputs(t.command)) problems.push(tmpInputProblem("repro_test", p));
+      if (vitestQuietFlag(t.command)) problems.push("repro_test: vitest 3 rejects -q/--quiet; use --reporter=dot");
+    }
   }
   if (JSON.stringify(c).length > MAX_CONTRACT_CHARS) problems.push(`the contract is over ${MAX_CONTRACT_CHARS} characters; keep quotes to the requirement sentence and descriptions short`);
   return { ok: problems.length === 0, problems };
@@ -393,6 +424,21 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
 const PY_MISSING_RE = /ModuleNotFoundError: No module named '([^']+)'|ImportError: No module named '?([\w.]+)'?/;
 const NODE_MISSING_RE = /Cannot find (?:module|package) '([^']+)'/;
 const CMD_NOT_FOUND_RE = /([^\s:'"`]+): command not found/, SH_NOT_FOUND_RE = /([^\s:'"`]+): not found\b/;
+// #4761: a runner rejecting its own flags is a defect of the frozen command, not of the change
+const CLI_USAGE_RE = /\bUnknown option\b|Unrecognized CLI Parameter|error: unrecognized arguments|unknown (?:shorthand )?flag\b|bad option:/i;
+const VITEST_QUIET_RE = /\bvitest\b[^&|;]*\s(?:-q|--quiet)(?=\s|$)/;
+/** #4761: a validate/repro command that passes vitest `-q`/`--quiet`, which vitest 3 rejects; null when fine. */
+export function vitestQuietFlag(command) {
+  return VITEST_QUIET_RE.test(String(command ?? "")) ? "-q" : null;
+}
+/** #4761: `-q`/`--quiet` on a vitest segment becomes `--reporter=dot`; other commands come back unchanged. */
+export function normalizeRunnerCommand(command) {
+  return String(command ?? "").split(/(&&|\|\||;|\|)/).map((seg) => (/\bvitest\b/.test(seg) ? seg.replace(/(\s)(?:-q|--quiet)(?=\s|$)/g, "$1--reporter=dot") : seg)).join("");
+}
+/** #4761: true when a failed command's {rc, output} is a runner CLI usage error (vitest `Unknown option`, jest `Unrecognized CLI Parameter`, pytest `unrecognized arguments`), not a test failure. */
+export function cliUsageError({ rc, output } = {}) {
+  return rc !== 0 && CLI_USAGE_RE.test(String(output ?? ""));
+}
 const KIND_NAME = { command: "command", "python-module": "Python module", "node-module": "Node package" };
 /**
  * forge#4323: the host tool or module a failed command could not find, from its {rc, output}: bash/sh "X: command not found"
@@ -439,12 +485,14 @@ export function repoTracks(paths) {
  * `ciCovered` (#4527): the validate ids accepted only because the head is CI-verified (no local result, or a missing host
  * tool), for the trajectory; always an array.
  */
-export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null, guardFailures = null }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null, guardFailures = null, newOffKeys = null }) {
   const failures = [], superseded = [], ciCovered = [];
   // #4626: a post-deploy check id must be on the default branch or added by this PR (`checkIds`: ids of both checks files; null = not resolved)
   if (checkIds) for (const r of contract.requirements ?? []) {
     if (r.disposition === "post-deploy" && !(r.check && checkIds.has(r.check))) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "check_unknown", detail: `${r.id} post-deploy check ${r.check ? `'${r.check}'` : "id"} is neither on the default branch nor added by this PR (.forge/post-deploy-checks.json)` });
   }
+  // #4769: a default-off rollout entry added by the diff needs an activation row
+  if (newOffKeys?.length) for (const f of activationFailures(contract, newOffKeys)) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, ...f });
   const outside = (k) => changedFiles.filter((f) => !ignore.some((p) => f.startsWith(p)) && !authorizationOf(k, f));
   const creep = outside(contract);
   const amendedOnly = frozenAmendedFiles(frozen, contract, outside, creep);
@@ -459,6 +507,7 @@ export function precheck({ contract, result, changedFiles, ignore = [], ciVerifi
     else if (r.exit !== 0) {
       const rerun = validateRuns?.[v.id];
       if (rerun?.rc === 0) continue;
+      if (rerun && cliUsageError(rerun)) { failures.push({ code: C.CONTRACT_INVALID_COMMAND, kind: "validate_command_invalid", detail: `validate ${v.id} (\`${v.command}\`) is a CLI usage error of the runner, a defect of the frozen command rather than of the change` }); continue; }
       const miss = rerun ? missingTool(rerun, { repoHas, command: v.command }) : null;
       if (miss && ciVerified) { ciCovered.push(v.id); continue; }
       if (miss) failures.push({ code: C.ENV_TOOL_MISSING, kind: "validate_env", tool: miss.tool, detail: `validate ${v.id} (\`${v.command}\`) could not run: the host is missing ${KIND_NAME[miss.kind]} '${miss.tool}' (environment, not the change)` });

package/bin/lean/conformance.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE, FOLLOWUP_CLASSES, followupClass, BUCKETS, bucketKind, bucketProblems, bucketTally, isE2eCommand, e2eVerified } from "./conformance.mjs";
+import { vitestQuietFlag, normalizeRunnerCommand, cliUsageError, validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE, FOLLOWUP_CLASSES, followupClass, BUCKETS, bucketKind, bucketProblems, bucketTally, isE2eCommand, e2eVerified } from "./conformance.mjs";
 
 const ISSUE = "## Requirements\n1. The scrape route must release the spend reservation on 429.\n2. The search route must release the spend reservation on 429.\n\n- [ ] Billing pricing is unchanged.";
 const Q1 = "The scrape route must release the spend reservation on 429.";
@@ -31,6 +31,14 @@ describe("contract", () => {
     assert.ok(!inIssue("scrape should free money", ISSUE));
     assert.ok(!inIssue("429.", ISSUE), "too short to identify a requirement");
   });
+  it("#4789: unicode punctuation and markdown markup do not break the verbatim check; a miss shows the nearest span", () => {
+    const issue = "## Problem\nThe \u201cscrape\u201d route \u2014 see [the spec](http://x.y) \u2014 must release the spend reservation\u2026 on 429.\n\nUnrelated line about billing.";
+    assert.ok(inIssue('The "scrape" route - see the spec - must release the spend reservation... on 429.', issue));
+    assert.ok(inIssue("The \u201cscrape\u201d route \\- see the spec", issue.replace("\u2014", "-")));
+    assert.ok(!inIssue("the scrape route must hold the reservation forever", issue));
+    const v = validateContract({ ...C, requirements: [{ ...C.requirements[0], quote: "the scrape route must hold the spend reservation on 429" }] }, issue);
+    assert.match(v.problems[0], /R1: quote is not verbatim from the issue.*nearest issue text: "The \u201cscrape\u201d route/);
+  });
   it("rejects paraphrases, a defer without why, not-applicable without evidence, missing validate, duplicate ids", () => {
     const v = validateContract({ ...C, validate: [], requirements: [
       { id: "R1", quote: "make scrape better", disposition: "deliver" }, { id: "R2", quote: Q2, disposition: "defer" },
@@ -108,6 +116,21 @@ describe("precheck (deterministic, no reviewer)", () => {
     assert.deepEqual(codes(precheck({ contract: C, result: { ...res, validation: [{ id: "V1", exit: 1 }] }, changedFiles: files })), ["conformance.unimplemented"]);
     assert.deepEqual(codes(precheck({ contract: C, result: { ...res, validation: [] }, changedFiles: files })), ["conformance.unimplemented"]);
   });
+  it("#4761 vitest -q is a contract problem; a runner usage error is contract.invalid_command, not conformance", () => {
+    const bad = { ...C, validate: [{ id: "V1", command: "pnpm --filter x exec vitest run a.test.ts -q" }] };
+    assert.ok(validateContract(bad, ISSUE).problems.some((p) => /V1: vitest 3 rejects -q/.test(p)));
+    assert.ok(!validateContract({ ...bad, validate: [{ id: "V1", command: "pnpm exec vitest run a.test.ts --reporter=dot" }] }, ISSUE).problems.some((p) => /vitest/.test(p)));
+    assert.equal(vitestQuietFlag("pytest -q"), null);
+    assert.equal(normalizeRunnerCommand("vitest run a -q && pytest -q"), "vitest run a --reporter=dot && pytest -q");
+    assert.ok(cliUsageError({ rc: 1, output: "CACError: Unknown option `-q`" }));
+    assert.ok(cliUsageError({ rc: 1, output: "Unrecognized CLI Parameter: --foo" }));
+    assert.ok(!cliUsageError({ rc: 1, output: "AssertionError: 1 !== 2" }));
+    assert.ok(!cliUsageError({ rc: 0, output: "Unknown option" }));
+    const failed = { ...res, validation: [{ id: "V1", exit: 1 }] };
+    const pc = precheck({ contract: C, result: failed, changedFiles: files, validateRuns: { V1: { rc: 1, output: "CACError: Unknown option `-q`" } } });
+    assert.deepEqual(codes(pc), ["contract.invalid_command"]);
+    assert.equal(pc.failures[0].kind, "validate_command_invalid");
+  });
   it("#4323 a failed validate whose rerun could not find a host tool or module is env.tool_missing naming it, not conformance", () => {
     const failed = { ...res, validation: [{ id: "V1", exit: 1 }] };
     const pc = precheck({ contract: C, result: failed, changedFiles: files, validateRuns: { V1: { rc: 1, output: "Traceback...\nModuleNotFoundError: No module named 'yaml'" } } });