forgedock 1.35.0 → 1.36.0

package/bin/experiment.mjs

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4629: live A/B experiments. forge.yaml `experiment:` section (flat keys, the parser has one nesting level):
+ *   id: light-vs-full          arms: light,full         ratio: 1,1 (weights, default equal)
+ *   metrics: usd_median,wall_p50_ms,first_pass_rate,needs_human_rate (default all)
+ *   targets: light.usd_median<=1.2xfull,light.first_pass_rate>=0.8   min_n: 10
+ * The arm is a hash of (id, issue), so a re-run or resume keeps its arm. Pure; the stats report is bin/stats/experiment.mjs.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseForgeYaml } from "./forge-utils.mjs";
+
+export const EXPERIMENT_METRICS = ["usd_median", "wall_p50_ms", "first_pass_rate", "needs_human_rate"];
+export const BENCH_SCHEMA = "forge.bench.v1";
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TARGET = /^([A-Za-z0-9][A-Za-z0-9._-]*)\.([a-z_0-9]+)(<=|>=)(\d+(?:\.\d+)?)(?:x([A-Za-z0-9][A-Za-z0-9._-]*))?$/;
+const list = (v) => String(v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+
+/** Parsed declaration {id, arms, ratio, metrics, targets, minN}, or null when absent or invalid. */
+export function parseExperiment(sec, { defaultMinN = 10 } = {}) {
+  if (!sec || typeof sec !== "object") return null;
+  const id = String(sec.id ?? "").trim(), arms = list(sec.arms);
+  if (!NAME.test(id) || arms.length < 2 || new Set(arms).size !== arms.length || !arms.every((a) => NAME.test(a))) return null;
+  const ratio = sec.ratio == null || sec.ratio === "" ? arms.map(() => 1) : list(sec.ratio).map((x) => (/^[1-9]\d*$/.test(x) ? Number(x) : NaN));
+  if (ratio.length !== arms.length || ratio.some(Number.isNaN)) return null;
+  const metrics = sec.metrics ? list(sec.metrics) : [...EXPERIMENT_METRICS];
+  if (!metrics.length || metrics.some((m) => !EXPERIMENT_METRICS.includes(m))) return null;
+  const targets = [];
+  for (const t of list(sec.targets)) {
+    const m = TARGET.exec(t);
+    if (!m || !arms.includes(m[1]) || !metrics.includes(m[2]) || (m[5] && !arms.includes(m[5]))) return null;
+    targets.push({ arm: m[1], metric: m[2], op: m[3], limit: Number(m[4]), vs: m[5] ?? null, text: t });
+  }
+  const mn = String(sec.min_n ?? "").trim();
+  if (mn && !/^\d+$/.test(mn)) return null;
+  return { id, arms, ratio, metrics, targets, minN: mn ? Number(mn) : defaultMinN };
+}
+
+/** forge.yaml `experiment:` of `cwd`, or null. */
+export function readExperiment(cwd = process.cwd()) {
+  try { return parseExperiment(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.experiment); } catch { return null; }
+}
+
+/** Deterministic arm of an issue: sha1(id:issue) mod the ratio total, walked over the arms in declared order. */
+export function assignArm(exp, issue) {
+  const total = exp.ratio.reduce((a, b) => a + b, 0);
+  let pick = createHash("sha1").update(`${exp.id}:${issue}`).digest().readUInt32BE(0) % total;
+  for (let i = 0; i < exp.arms.length; i++) { if (pick < exp.ratio[i]) return exp.arms[i]; pick -= exp.ratio[i]; }
+  return exp.arms[0];
+}
+
+/** The shared result record of the bench harness, the eval gate and `stats --experiment`: targets are {pass: true|false|null, value, limit}. */
+export const benchRecord = ({ source, arms = {}, targets = {} }) => ({ schema: BENCH_SCHEMA, source, arms, targets });

package/bin/forgedock.mjs

@@ -3315,7 +3315,7 @@ function help() {
     ["npx forgedock bootstrap <idea|docs> [--dry-run] [--spike <path>] | --plan <plan.json> [--dry-run]", "Headless /bootstrap: idea to orchestrate-ready backlog (--dry-run previews milestones, titles, DAG and estimated agent cost without GitHub writes); --plan validates and creates (or previews) a plan, and re-running resumes from GitHub"],
     ["npx forgedock run-issue <issue> [--lane <lane>] [--lane-override] [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline; the lane comes from the issue: milestone → milestone/<slug>, else staging; --lane is an assertion, never the default branch) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering; each issue on its own lane, cross-lane dependencies reported"],
-    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --cancel <id> | --hold <id> N... | --release <id> N...", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), change its concurrency live, add issues to a running (or held) batch under its K and DAG, or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume), or hold/release single issues of a batch (a held issue is not admitted until released or named by --resume)"],
+    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --requeue <id> N... [--reason \"...\"] | --cancel <id> | --hold <id> N... | --release <id> N...", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), change its concurrency live, add issues to a running (or held) batch under its K and DAG, requeue a terminal issue (and the dependents skipped behind it) after an operator decision (refused while it is labelled needs-human or closed; a finished batch is reopened), or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume), or hold/release single issues of a batch (a held issue is not admitted until released or named by --resume)"],
     ["npx forgedock triage <issue...> [--lane L] [--dry-run]", "Already-fixed pre-filter: close issues a merged PR or green CI already resolved; print the rest"],
     ["npx forgedock probe [issue...] [--dry-run]", "Run declared acceptance probes for closed issues whose fix is on the default branch; a fail reopens the issue"],
     ["npx forgedock check [--base REF] [--json]", "Run the lane's frozen validate commands and change-scoped pre-PR checks locally in this worktree, as the engine will (no GitHub, no Actions)"],

package/bin/hooks/reread-nudge.mjs

@@ -9,6 +9,8 @@
  * #4580: the same script is also a PreToolUse guard on Read: a full-file Read (no offset/limit) of a path already read
  * REREAD_MIN-1 times whose mtime is unchanged since its last read is denied with a reason that points at notes or a line
  * range. Ranged reads and Bash never deny, and any error allows. A changed mtime resets the path's count.
+ * #4622: the guard counts only full-file Reads ({path: count} in <session_id>.full.json), so ranged Reads and Bash samples never
+ * make a first full Read look like a re-read; the nudge still counts every read.
  * State: {path: count} in <tmpdir>/forgedock-reread/<session_id>.json plus {path: mtimeMs} in <session_id>.mtime.json (per-run caches).
  */
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -44,7 +46,13 @@ export const stateFile = (sessionId, dir = join(tmpdir(), "forgedock-reread")) =
 const mtimeOf = (p) => { try { return statSync(p).mtimeMs; } catch { return null; } };
 const loadJson = (file) => { try { const v = JSON.parse(readFileSync(file, "utf8")); return v && typeof v === "object" ? v : {}; } catch { return {}; } };
 
-/** Pure core of the guard: the deny reason for a payload, or null. `mtimeNow(path)` is the file's current mtime. */
+/** Paths a payload reads whole: a Read with no offset/limit (what the guard counts, #4622). */
+export function fullReads(payload) {
+  const inp = payload?.tool_input ?? {};
+  return payload?.tool_name === "Read" && inp.offset == null && inp.limit == null ? payloadReads(payload) : [];
+}
+
+/** Pure core of the guard: the deny reason for a payload, or null. `counts` are full-read counts; `mtimeNow(path)` is the file's current mtime. */
 export function guardFor(payload, counts = {}, mtimes = {}, mtimeNow = mtimeOf) {
   const inp = payload?.tool_input ?? {};
   if (payload?.tool_name !== "Read" || inp.offset != null || inp.limit != null) return null;
@@ -64,20 +72,23 @@ export function main(input, { dir } = {}) {
     if (!payload?.session_id) return "";
     if (!payloadReads(payload).length) return "";
     const file = stateFile(payload.session_id, dir), mfile = file.replace(/\.json$/, ".mtime.json");
-    const counts = loadJson(file), mtimes = loadJson(mfile);
+    const ffile = file.replace(/\.json$/, ".full.json");
+    const counts = loadJson(file), mtimes = loadJson(mfile), full = loadJson(ffile);
     if (payload.hook_event_name === "PreToolUse") {
-      const reason = guardFor(payload, counts, mtimes);
+      const reason = guardFor(payload, full, mtimes);
       return reason ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } })}\n` : "";
     }
     for (const p of payloadReads(payload)) {
       const now = mtimeOf(p);
-      if (now != null && mtimes[p] !== now) delete counts[p]; // the file changed (or is new): earlier reads no longer count
+      if (now != null && mtimes[p] !== now) { delete counts[p]; delete full[p]; } // the file changed (or is new): earlier reads no longer count
       if (now != null) mtimes[p] = now;
     }
+    for (const p of fullReads(payload)) full[p] = (full[p] ?? 0) + 1;
     const r = nudgeFor(payload, counts);
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(r.counts));
     writeFileSync(mfile, JSON.stringify(mtimes));
+    writeFileSync(ffile, JSON.stringify(full));
     return r.message ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: r.message } })}\n` : "";
   } catch {
     return "";

package/bin/lean/batch.mjs

@@ -6,6 +6,7 @@
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
  * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
  * `add` (issues added to the batch by `--add`, #4408: a cumulative JSON set the runner re-reads every pass),
+ * `requeue` (`--requeue`, #4550: a cumulative JSON list of `{issue, reason, by, at}` the runner applies once each, moving a terminal issue back to pending),
  * `hold` (issues held by `--hold`, #4592: a cumulative JSON set; the runner admits none of them until `--release` or a `--resume` names them),
  * `cancel` (`{at, reason}` written by `--cancel`, #4376: the runner stops admitting and stops its local lanes; a resume clears it),
  * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
@@ -69,6 +70,16 @@ const readAdded = (file) => {
   return Array.isArray(v) ? [...new Set(v.filter((n) => Number.isSafeInteger(n) && n > 0))].sort((a, b) => a - b) : [];
 };
 
+/** `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));
+/** Key of one requeue entry; the runner records the applied keys in state.json `requeueApplied`. */
+export const requeueKey = (e) => `${e.issue}@${e.at}`;
+
+const readRequeueFile = (file) => {
+  const v = readJson(file);
+  return Array.isArray(v) ? v.filter((e) => e && Number.isSafeInteger(e.issue) && e.issue > 0 && typeof e.at === "string") : [];
+};
+
 /** The positive integers among `list` (numbers, `7`, `#7`). */
 const ints = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN)).filter((n) => Number.isSafeInteger(n) && n > 0);
 
@@ -122,6 +133,35 @@ export function openBatch(root, id) {
       if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
       return { added, skipped };
     },
+    /**
+     * `--requeue` (#4550): record that each issue returns to pending. Refused: not a positive integer, not in the batch's
+     * `order`, no terminal result yet (`not terminal`), or already requeued and not yet applied. The needs-human label and
+     * closed checks need GitHub and live in the CLI. @returns {{requeued:number[], refused:Array<{issue, reason}>}}
+     */
+    requeue: (list, { reason = "operator decision", by = "operator" } = {}) => {
+      const st = readJson(f("state.json")) ?? {};
+      const order = new Set(st.order ?? []), applied = new Set(st.requeueApplied ?? []);
+      const entries = readRequeueFile(f("requeue"));
+      const pend = new Set(entries.filter((e) => !applied.has(requeueKey(e))).map((e) => e.issue));
+      const requeued = [], refused = [];
+      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) refused.push({ issue: x, reason: "not an integer" });
+        else if (!order.has(n)) refused.push({ issue: n, reason: "not in batch" });
+        else if (pend.has(n)) refused.push({ issue: n, reason: "already requeued" });
+        else if (!REQUEUABLE(st.results?.[n]?.outcome)) refused.push({ issue: n, reason: "not terminal" });
+        else { pend.add(n); requeued.push(n); }
+      }
+      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");
+      }
+      return { requeued, refused };
+    },
+    /** Every `--requeue` entry, in order; [] when missing or invalid. */
+    readRequeued: () => readRequeueFile(f("requeue")),
+    /** Entries the runner has not applied yet (a finished or unhosted batch with a pending requeue). */
+    unrunRequeues: () => { const done = new Set(readJson(f("state.json"))?.requeueApplied ?? []); return readRequeueFile(f("requeue")).filter((e) => !done.has(requeueKey(e))); },
     /** Issues held by `--hold` (#4592): the `hold` file, sorted unique positive integers; [] when missing or invalid. */
     readHeld: () => readAdded(f("hold")),
     /** Merge the positive integers of `list` into the `hold` file. @returns {number[]} the issues newly held */
@@ -138,8 +178,8 @@ export function openBatch(root, id) {
       if (freed.length) writeAtomic(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
       return freed;
     },
-    /** `--cancel` (#4376): `{at, reason}` in the `cancel` file; the runner re-reads it every pass. */
-    requestCancel: ({ reason = "operator" } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason) }) + "\n"),
+    /** `--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"),
     /** 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 }),

package/bin/lean/batch.test.mjs

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { orchestrate, deferPolicy, DEFER_BACKOFF_S } from "./orchestrate.mjs";
+import { orchestrate, deferPolicy, DEFER_BACKOFF_S, formatOutcomeLists } from "./orchestrate.mjs";
 import { openBatch, fsTypeOf, assertDiskPath, isLaneAlive, writeAtomic, launchLane, detachedLanes } from "./batch.mjs";
 import { orchestrateFromCli, runFromCli, readOrchestration, makeRelabelNeedsHuman, makeDispatchCheck } from "../engine-cli.mjs";
 
@@ -528,6 +528,37 @@ describe("#4376: forgedock orchestrate --cancel", () => {
     assert.deepEqual(saved.deferrals, { 1: 1 });
   });
 
+  for (const stopRemote of [false, true]) {
+    it(`a cancel ${stopRemote ? "with" : "without"} stopRemote ${stopRemote ? "stops" : "leaves"} a remote lane (#4612)`, async () => {
+      let cancel = null, saved = null;
+      const store = { load: () => saved, save: (s) => { saved = s; }, log: () => {} };
+      const started = [], stops = [];
+      let release;
+      const gate = new Promise((r) => { release = r; });
+      const done = orchestrate({ issues: [1], parallel: 1, pollMs: 5, readBody: async () => "", store, getCancelled: () => cancel,
+        stopLane: (n, rec) => { stops.push([n, rec.remote]); release(); },
+        runOne: async (n, _lane, ctx) => {
+          started.push(n);
+          ctx.onStart?.({ remote: true, handle: { id: "sbx-1" } });
+          if (!stopRemote) setTimeout(release, 100);
+          await gate;
+          return { terminalReason: "deferred", code: "run.interrupted" };
+        } });
+      await until(() => started.includes(1));
+      cancel = { at: new Date().toISOString(), reason: "operator", ...(stopRemote ? { stopRemote: true } : {}) };
+      await done;
+      assert.deepEqual(stops, stopRemote ? [[1, true]] : []);
+    });
+  }
+
+  it("requestCancel records stopRemote only when asked (#4612)", () => {
+    const b = openBatch(tmpDir("batch-cancel-stop-"), "b1");
+    b.requestCancel({});
+    assert.equal(b.readCancel().stopRemote, undefined);
+    b.requestCancel({ stopRemote: true });
+    assert.equal(b.readCancel().stopRemote, true);
+  });
+
   it("through the CLI: --cancel during a lane holds the rest, a finished batch is left alone, unknown ids reject, --resume clears it", async () => {
     const root = tmpDir("batch-cancel-cli-");
     const leanIo = {
@@ -711,6 +742,75 @@ describe("#4528: a full sandbox pool (sandbox.capacity) is never capped", () =>
   });
 });
 
+describe("#4550: forgedock orchestrate --requeue", () => {
+  const gate = () => { let open; const p = new Promise((r) => { open = r; }); return { p, open }; };
+  it("a needs-human issue is requeued and relaunched; its skipped dependent returns to pending and runs after it merges; one row per issue", async () => {
+    const bodies = { 1: "", 2: "Depends on #1", 3: "" };
+    let entries = [];
+    const started = [], g3 = gate(), log = [], decisions = [];
+    const done = orchestrate({ issues: [1, 2, 3], parallel: 3, pollMs: 5, readBody: async (n) => bodies[n] ?? "", getRequeued: () => entries,
+      decide: (d) => { decisions.push(d); }, onUpdate: (r) => log.push(r),
+      runOne: async (n) => {
+        started.push(n);
+        if (n === 3) { await g3.p; return { terminalReason: "merged" }; }
+        if (n === 1 && started.filter((x) => x === 1).length === 1) return { terminalReason: "needs-human", detail: "builder.blocked: product-decision" };
+        return { terminalReason: "merged" };
+      } });
+    await until(() => log.some((r) => r.issue === 2 && r.outcome === "skipped"));
+    entries = [{ issue: 1, reason: "decided in scope", by: "operator", at: "2026-10-24T00:00:00Z" }];
+    await until(() => started.filter((x) => x === 2).length === 1, 3000);
+    g3.open();
+    const rows = await done;
+    assert.deepEqual(started.filter((x) => x === 1).length, 2, "relaunched once");
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [3, "merged"]]);
+    assert.equal(rows[0].requeued.reason, "decided in scope");
+    assert.equal(rows[0].requeued.prior[0].outcome, "needs-human");
+    assert.deepEqual(formatOutcomeLists(rows), ["requeued: #1 (decided in scope)"]);
+    assert.ok(decisions.some((d) => d.issue === 1 && /requeued/.test(d.what) && d.why === "decided in scope"));
+    assert.ok(started.indexOf(2) > started.lastIndexOf(1) - 1 && started.filter((x) => x === 2).length === 1, "#2 ran once, after #1 was relaunched");
+  });
+
+  it("an entry is applied once; one for an issue that is not terminal changes nothing", async () => {
+    const entries = [{ issue: 1, reason: "r", by: "operator", at: "t1" }];
+    let runs = 0;
+    const rows = await orchestrate({ issues: [1], parallel: 1, pollMs: 5, readBody: async () => "", getRequeued: () => entries,
+      runOne: async () => { runs++; return { terminalReason: "merged" }; } });
+    assert.equal(runs, 1);
+    assert.equal(rows[0].requeued, undefined);
+  });
+
+  it("batch.requeue: terminal issues are recorded; unknown, merged and double requests are refused; --add still says already in batch", () => {
+    const b = openBatch(tmpDir("batch-requeue-"), "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [1, 2, 3, 4], results: { 1: { outcome: "needs-human" }, 2: { outcome: "merged" }, 3: { outcome: "dependency-blocked" } } });
+    const r = b.requeue([1, 2, 3, 4, 9, "x", 1], { reason: "why", by: "me" });
+    assert.deepEqual(r.requeued, [1, 3]);
+    assert.deepEqual(r.refused.map((x) => [x.issue, x.reason]), [[2, "not terminal"], [4, "not terminal"], [9, "not in batch"], ["x", "not an integer"], [1, "already requeued"]]);
+    assert.deepEqual(b.readRequeued().map((e) => [e.issue, e.reason, e.by]), [[1, "why", "me"], [3, "why", "me"]]);
+    assert.equal(b.unrunRequeues().length, 2);
+    assert.deepEqual(b.addIssues([1]).skipped, [{ issue: 1, reason: "already in batch" }]);
+  });
+
+  it("the CLI refuses a needs-human-labelled or closed issue and writes nothing; an open, cleared one is requeued (a finished batch's report is cleared)", async () => {
+    const root = tmpDir("batch-requeue-cli-");
+    const b = openBatch(root, "b1");
+    b.writePlan({ argv: ["1"], repo: "o/r" });
+    b.store.save({ order: [5, 6, 7], results: { 5: { outcome: "needs-human" }, 6: { outcome: "needs-human" }, 7: { outcome: "needs-human" } } });
+    b.writeReport({ rows: [], report: "x" });
+    const io = { gh: async (a) => JSON.stringify({ state: a[2] === "6" ? "CLOSED" : "OPEN", labels: a[2] === "7" ? [{ name: "needs-human" }] : [] }) };
+    const bad = await quiet(() => orchestrateFromCli(["--requeue", "b1", "6", "7", "--reason", "r"], { batchRoot: root, io }));
+    assert.deepEqual(bad.requeued, []);
+    assert.deepEqual(bad.refused.map((x) => x.issue), [6, 7]);
+    assert.match(bad.refused[1].reason, /needs-human/);
+    assert.deepEqual(b.readRequeued(), []);
+    assert.ok(b.readReport(), "nothing changed");
+    const ok = await quiet(() => orchestrateFromCli(["--requeue", "b1", "5", "--reason", "decided"], { batchRoot: root, io }));
+    assert.deepEqual(ok.requeued, [5]);
+    assert.equal(b.readRequeued()[0].reason, "decided");
+    assert.equal(b.readReport(), null, "the finished batch is reopened for --resume");
+  });
+});
+
 describe("#4540: remote admissions are capped to the provider's free capacity", () => {
   const run = async (capacity) => {
     const c = { t: 1_000_000 };

package/bin/lean/conformance.mjs

@@ -27,6 +27,7 @@ const INCIDENTAL_RE = /(^|\/)(CHANGELOG|CHANGES|HISTORY)(\.[a-z]+)?$|(^|\/)(pack
 export const MIN_QUOTE_CHARS = 12;
 /** A contract larger than this cannot be posted whole in one comment (the comment cap is 60k). */
 export const MAX_CONTRACT_CHARS = 40000;
+import { CHECK_ID_RE } from "./postdeploy-check.mjs";
 const C = OUTCOME_CODES;
 
 export const norm = (s) => String(s ?? "").replace(/[`*_>]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
@@ -231,6 +232,7 @@ export function validateContract(c, issueText, { repro = false } = {}) {
     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 (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`);
     if (r?.verify != null && !VERIFY_MODES.includes(r.verify)) problems.push(`${id}: verify must be one of ${VERIFY_MODES.join("|")}`);
     if (isOutOfBand(r) && r?.disposition !== "deliver") problems.push(`${id}: verify out_of_band applies only to a deliver requirement`);
@@ -331,7 +333,11 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
     } else if (TRACKED.includes(a.kind) && a.requirement) {
       const r = c.requirements.find((x) => x.id === a.requirement);
       if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
-      if (!TRACKED.includes(r.disposition)) { r.disposition = a.kind; r.why = a.why; r.amended = true; toTrack.push(r); }
+      if (!TRACKED.includes(r.disposition)) {
+        if (a.kind === "post-deploy" && !CHECK_ID_RE.test(String(a.check ?? r.check ?? ""))) { problems.push(`amendment post-deploy ${a.requirement} needs a check id (check)`); continue; }
+        r.disposition = a.kind; r.why = a.why; r.amended = true; toTrack.push(r);
+        if (a.kind === "post-deploy") r.check = a.check ?? r.check; // #4626
+      }
     } else { problems.push(amendmentProblem(a, tag)); continue; }
     applied.push({ kind: a.kind, target: a.path ?? a.requirement?.id ?? a.requirement, why: String(a.why).trim() });
   }
@@ -387,8 +393,12 @@ 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 }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = 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)` });
+  }
   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);
@@ -745,7 +755,8 @@ export function formatShadowSummary(rows) {
 /** One line per requirement for the follow-up script: a stable key (id + quote) and a why. Tabs and newlines removed. */
 export function followupItems(reqs) {
   const flat = (s) => String(s ?? "").replace(/[\t\r\n`]+/g, " ").replace(/\s+/g, " ").trim();
-  return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240).trim(), why: flat(`${r.disposition}: ${r.why ?? ""}`).slice(0, 400).trim() }));
+  const check = (r) => (r.disposition === "post-deploy" && r.check ? `[check:${flat(r.check)}] ` : ""); // #4626: the follow-up item names its check
+  return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240).trim(), why: flat(`${r.disposition}: ${check(r)}${r.why ?? ""}`).slice(0, 400).trim() }));
 }
 
 /** #4388: the follow-up script's `key\tissue` lines as {[item.key]: issue}, matched on trimmed keys (the script trims what it echoes); unmatched items omitted. */

package/bin/lean/conformance.test.mjs

@@ -670,3 +670,29 @@ describe("#4594 amend-requirement", () => {
     assert.match(explainFailures([{ code: "x", detail: "R1 partial" }], c)[0].detail, /amended to "regenerate and reveal/);
   });
 });
+
+describe("post-deploy check ids (#4626)", () => {
+  const pd = (extra = {}) => ({ ...C, requirements: [{ id: "R1", quote: Q1, disposition: "post-deploy", why: "needs prod", ...extra }, C.requirements[1]] });
+  it("validateContract: a post-deploy requirement needs a well-formed check id", () => {
+    assert.ok(validateContract(pd(), ISSUE).problems.some((p) => /post-deploy needs a check id/.test(p)));
+    assert.ok(validateContract(pd({ check: "Bad Id" }), ISSUE).problems.some((p) => /post-deploy needs a check id/.test(p)));
+    assert.ok(!validateContract(pd({ check: "login-smoke" }), ISSUE).problems.some((p) => /check id/.test(p)));
+  });
+  it("applyAmendments: a post-deploy amendment needs a check id", () => {
+    const bad = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w" }], ISSUE);
+    assert.ok(bad.problems.some((p) => /needs a check id/.test(p)));
+    const ok = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w", check: "login-smoke" }], ISSUE);
+    assert.equal(ok.contract.requirements[0].check, "login-smoke");
+  });
+  it("precheck: a check id on neither branch is unimplemented; null checkIds skips the rule", () => {
+    const res = { requirements: [{ id: "R1", status: "post-deploy" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
+    const c = pd({ check: "login-smoke" });
+    assert.ok(precheck({ contract: c, result: res, changedFiles: files, checkIds: new Set() }).failures.some((f) => f.kind === "check_unknown"));
+    assert.ok(!precheck({ contract: c, result: res, changedFiles: files, checkIds: new Set(["login-smoke"]) }).failures.some((f) => f.kind === "check_unknown"));
+    assert.ok(!precheck({ contract: c, result: res, changedFiles: files }).failures.some((f) => f.kind === "check_unknown"));
+  });
+  it("followupItems names the check in a post-deploy item", () => {
+    const [i] = followupItems([{ id: "R1", quote: Q1, disposition: "post-deploy", why: "w", check: "login-smoke" }]);
+    assert.match(i.why, /^post-deploy: \[check:login-smoke\] w$/);
+  });
+});

package/bin/lean/effects.mjs

@@ -20,6 +20,7 @@ import { enumeratingTests, missingEntries } from "./enumerating.mjs";
 import { resolveBaseConflicts } from "./conflictres.mjs";
 import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems } from "./sequence.mjs";
 import { duplicateExports } from "./postmerge.mjs";
+import { englishCopies } from "./i18n.mjs";
 import { scopedChecks } from "./checks.mjs";
 import { makeSequenceLeaseIo } from "./seqlease.mjs";
 import { followupMap } from "./conformance.mjs";
@@ -384,6 +385,8 @@ export function makeLeanIo({ repo }) {
     /** #4406: the lane's scoped checks after a base merge (bin/lean/checks.mjs; [] on failure), and same-app duplicate exports (bin/lean/postmerge.mjs). */
     postMergeChecks: async ({ cwd, base }) => { try { return scopedChecks({ repo: cwd, base }); } catch { return []; } },
     duplicateExports: ({ cwd, base }) => duplicateExports({ git: (a) => run("git")(a, { cwd }), cwd, base }),
+    /** #4596: keys added to a non-en locale catalog as English copies (bin/lean/i18n.mjs). */
+    englishCopies: ({ cwd, base }) => englishCopies({ git: (a) => run("git")(a, { cwd }), base }),
     /**
      * #4271: scripts/acceptance-red-green.sh for the frozen repro_test in cwd; {base, head} words, or null on any failure.
      * `env` (#4325): the lane env (run TMPDIR, toolchain), merged over process.env, so the command sees what the builder saw.

package/bin/lean/execution.mjs

@@ -480,6 +480,8 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_CAPACITY, detail: `sandbox ${id} could not start (capacity): ${errText(e)}`, ...(Number(e.retryInSeconds) > 0 ? { retryInSeconds: Number(e.retryInSeconds) } : {}) }
     : { terminalReason: "needs-human", code: OUTCOME_CODES.SANDBOX_START_FAILED, detail: `sandbox ${id} failed to start: ${errText(e)}` });
   return {
+    // #4612: a graceful stop of a live sandbox (the provider's checkpoint stop); false when it has none.
+    stopLane: async (n, rec) => (typeof provider.stop === "function" && rec?.handle ? (await provider.stop(rec.handle)) === true : false),
     runOne: async (n, lane, ctx = {}) => {
       const led = ledgerFor(n);
       const base = { provider: provider.name, id: provider.idFor(n), issue: n, startedAt: now() };

package/bin/lean/i18n.mjs

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

package/bin/lean/i18n.test.mjs

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

package/bin/lean/lane.mjs

@@ -85,7 +85,7 @@ export async function resolveLane({ issue, repo, io, cwd, branches = {}, request
 }
 
 /**
- * #4593: true when `lane` is a non-staging branch fully merged into `staging` (a shipped milestone branch).
+ * #4593: true when `lane` is a non-staging branch fully merged into `staging` by a merge commit (a shipped milestone branch).
  * Fail closed: any git error (no such ref, offline) is "not shipped".
  */
 export async function isShippedLane({ lane, staging = DEFAULT_STAGING_BRANCH, io, cwd }) {
@@ -93,6 +93,9 @@ export async function isShippedLane({ lane, staging = DEFAULT_STAGING_BRANCH, io
   try {
     try { await io.git(["fetch", "origin", lane, staging], { cwd }); } catch { /* offline: use the local refs */ }
     await io.git(["merge-base", "--is-ancestor", `origin/${lane}`, `origin/${staging}`], { cwd });
-    return true;
+    // #4623: an unused lane cut from staging is trivially an ancestor; shipped also needs a merge commit that took the lane tip.
+    const tip = String(await io.git(["rev-parse", `origin/${lane}`], { cwd })).trim();
+    const merges = String(await io.git(["rev-list", "--merges", "--parents", `origin/${staging}`, `^origin/${lane}`], { cwd }));
+    return !!tip && merges.split("\n").some((l) => l.trim().split(/\s+/).slice(2).includes(tip));
   } catch { return false; }
 }