forgedock 1.34.0 → 1.36.0

package/bin/lean/prompts.mjs

@@ -63,6 +63,18 @@ export function duplicateExportsPrompt(findings, mode = "local") {
   return `This change exports names that another module of the same app or package already exports:\n${rows}\n\nRename the new export or reuse the existing one, and update every reference and any registry, map or test keyed by the name (same-named entries collide or leave one unprobed). ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
 }
 
+/** #4596: new keys the lane copied from the source-locale catalog into another locale's catalog. */
+export function i18nCopiesPrompt(findings, mode = "local") {
+  const rows = findings.slice(0, 30).map((d) => `- ${d.path}: ${d.key} = ${JSON.stringify(d.value)} (same as ${d.source})`).join("\n");
+  return `This change adds keys to locale catalogs as English copies of the source locale:\n${rows}\n\nTranslate each into that catalog's language (keep placeholders), and add any translation-status entry the repo tracks as a minimal diff: insert in place, never re-sort or reformat the file. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
+/** #4591: lane-added migrations the repo's generator did not produce. */
+export function migrationGeneratorPrompt(problems, mode = "local") {
+  const rows = problems.slice(0, 30).map((p) => `- ${p}`).join("\n");
+  return `These migration files were named by hand, not produced by the repo's migration generator:\n${rows}\n\nA made-up name or timestamp collides with another lane's migration. Delete each such file, then recreate it with the generator (hand-written SQL: the generator's \`--custom\` mode, e.g. \`drizzle-kit generate --custom --name=<name>\`, then put your SQL in the file it wrote), so the journal entry and snapshot come from it. Never name or number migration files by hand. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
 /** #4390: byte cap of the diff hunks a context-ceiling restart carries (the stat is always kept). */
 export const RESTART_DIFF_MAX_BYTES = 40 * 1024;
 
@@ -142,7 +154,7 @@ ${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}
 If the issue is already fixed or invalid, write ${RESULT_FILE} {"status":"already-fixed|invalid","summary":"one line","evidence":["file:line ..."]} and stop. If it is blocked, write {"status":"blocked","summary":"",...} with a typed "block" (rules below) and stop.
 
 2. Otherwise write ${CONTRACT_FILE}, the frozen hand-off: a developer who never saw the issue must be able to implement and verify it from this file alone.
-{"requirements":[{"id":"R1","quote":"<verbatim sentence or checklist item from the issue>","disposition":"deliver|defer|post-deploy|not-applicable","why":"<required for defer and post-deploy>","evidence":"<file:line, required for not-applicable>","verify":"<optional: in_lane|out_of_band>"}],
+{"requirements":[{"id":"R1","quote":"<verbatim sentence or checklist item from the issue>","disposition":"deliver|defer|post-deploy|not-applicable","why":"<defer, post-deploy>","check":"<post-deploy: id in .forge/post-deploy-checks.json>","evidence":"<file:line, required for not-applicable>","verify":"<optional: in_lane|out_of_band>"}],
  "deliverables":[{"id":"D1","path":"<file to change>","change":"<what>","requirements":["R1"]}],
  "preserve":[{"id":"P1","what":"<caller, contract or behaviour that must not change, with its path>"}],
  "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change; a git diff compares against the merge base (origin/<lane>...HEAD), never the moving origin/<lane> tip>"}],
@@ -171,13 +183,16 @@ export function builderImplementPrompt(mode = "local", { toolchain = null, spars
 
 ${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}${remote ? `\n\n${VERIFY_RULES[mode]}` : ""}
 
-The contract changes only through typed amendments in ${RESULT_FILE}, each with a why, which the engine posts on the issue:
-- {"kind":"add-deliverable","path":"<file>","why":""}: a file you must change that the contract did not list.
+The contract changes only through typed amendments in ${RESULT_FILE}, each with a why:
+- {"kind":"add-deliverable","path":"<file>","why":""}: a file the contract did not list.
 - {"kind":"add-requirement","requirement":{"id":"R9","quote":"<verbatim from the issue>","disposition":"deliver|defer|post-deploy"},"why":""}: an issue requirement the contract missed.
-- {"kind":"defer|post-deploy","requirement":"R#","why":""}: a contracted requirement that becomes separate work or a post-deploy check. The engine files it as a tracked follow-up. Not "type"; other kinds are rejected.
+- {"kind":"defer|post-deploy","requirement":"R#","why":"","check":"<id>"}: a requirement that becomes separate work or a post-deploy check. Filed as a tracked follow-up. Not "type"; other kinds are rejected.
+- {"kind":"amend-requirement","requirement":"R#","text":"<revised wording>","why":""}: reworded; judged against text.
+New keys: translate, never copy English; status entries in place.
 Never report a deliver requirement as "deferred" or "follow-up" without an amendment.
-A new dependency between workspace packages in a package.json that no deliverable names is blocked by the engine: add it through add-deliverable with a why naming the package, or do not add it.
-If the repository has scripts/check-devdocs-freshness.sh, a behaviour change under the paths it checks must update the matching dossier (devdocs/modules/*.md, per devdocs/index.yaml) in the same change. Run it against the base before writing the result; the engine runs it too.
+Never name or number migration files by hand; use the generator.
+A new workspace-package dependency in a package.json no deliverable names is blocked by the engine: add it through add-deliverable with a why naming the package, or do not add it.
+If the repository has scripts/check-devdocs-freshness.sh, a behaviour change under the paths it checks must update the matching dossier (devdocs/modules/*.md, per devdocs/index.yaml) in the same change. Run it against the base first; the engine runs it too.
 
 Before writing ${RESULT_FILE}, after your last edit, run \`node ${FORGEDOCK_CLI} check\` in the worktree and fix until it passes; if it cannot pass, report the problem as blocked.
 
@@ -244,6 +259,18 @@ export function enumeratingPlanNote(list) {
   return `\n\nEnumerating tests (found by the engine): these tests list every member of a module or directory this issue names, so a new export, table, job, action, namespace or file there must join their list or CI goes red. List each one you will touch under Affected Files in ${INVESTIGATION_FILE}, and add a validate command that runs only those tests.\n${list.slice(0, 40).map((e) => `- ${e.module} -> ${e.test}:${e.line} (${e.why})`).join("\n")}`;
 }
 
+/** #4585: the repo's verify.invariants as a checklist for the plan; "" when none. */
+export function invariantsPlanNote(list) {
+  if (!Array.isArray(list) || !list.length) return "";
+  return `\n\nRepo-wide invariants (verify.invariants): these commands run before every push whichever tests you choose, and each lists every table, export, key, namespace or file of its kind. A new one needs an entry in every such registry (e.g. registry, export, purge order, seeder, translation status, boundary or placeholder lists). Name each registry you will touch under Affected Files in ${INVESTIGATION_FILE}.\n${list.slice(0, 20).map((c) => `- \`${c}\``).join("\n")}`;
+}
+
+/** #4585: the builder rule for verify.invariants; "" when none. */
+export function invariantsBuildRule(list) {
+  if (!Array.isArray(list) || !list.length) return "";
+  return `\n\nInvariants checklist: for each new table, export, key, namespace, page or file, add its entry to every registry or coverage list that enumerates its kind (e.g. a new table needs registry, export, purge and seeder entries; a new i18n key needs every locale). Then run each command below and fix any failure before you finish.\n${list.slice(0, 20).map((c) => `- \`${c}\``).join("\n")}`;
+}
+
 const NOT_MEMBER = `or, when the symbol is not a member of that list, record {"symbol":"<name>","test":"<test path>","why":"<why it is not a member>"} in ${RESULT_FILE} "not_members"`;
 
 /** #4322: the builder rule citing the plan's enumerating tests; "" when none. */
@@ -311,6 +338,7 @@ const BLOCK_RULES = `"blocked" needs a typed "block" in ${RESULT_FILE}, one of:
 - {"kind":"split-required","subissues":[{"title":"","body":"","depends_on":[0],"files":["<path>"]}],"size":{"files":N,"lines":N}}: too big for one change. The engine files the sub-issues (depends_on = indexes of earlier sub-issues; files = the files or dirs each will edit, also accepted as "paths") only when every sub-issue's files are disjoint from the others' or the whole change's size estimate exceeds ${SPLIT_MIN_FILES} files or ${SPLIT_MIN_LINES} lines; otherwise keep one lane: an ordered checklist in the contract with a validate per item. In an admitted split, when siblings would edit the same hub (a barrel or index export list, a union type, a shared test fixture, an index doc), pre-stage its slots in the earliest sub-issue and make the others depend on it, or give each sibling its own per-feature file; the engine serialises sub-issues that still share a file.
 - {"kind":"human","why":"${HUMAN_BLOCK_REASONS.join("|")}"}: only an external action agents cannot take, or a product decision too critical for agents.
 "An upstream issue must land first", "needs a split" and "needs prod data that read-only monitoring can read" are never "human".
+A check that times out (rc 124) is host load, never a block or "human" product-decision: run the narrowest targeted command for your changed files and say the full one could not finish in time.
 Remote sandbox lacking a host-only capability (sops, prod_monitor, ops_credentials): name it in the summary; the host reruns the lane.`;
 
 export function blockCorrectionPrompt(problem) {
@@ -342,7 +370,9 @@ export const REVIEWER_SYSTEM = `You are an independent conformance reviewer of o
 
 You receive the GitHub issue with its comments, the frozen contract (requirements quoted from the issue, deliverables, preserve constraints, validate commands) with typed amendments, the builder's result with validation output, the changed files, the diff, and a row skeleton with one row per contract id and changed file. The engine computes the verdict from your rows; a reply without rows is rejected, so fill the skeleton rather than composing rows: fill EVERY row (set each empty status, evidence and validated_by, and each null deferral_ok; keep the ids and files as given):
 - issue_coverage: one row per requirement or acceptance criterion in the issue, quoted verbatim, saying whether the contract covers it, narrows it, or misses it. The skeleton lists the contract's quotes; add a row for any issue requirement the contract does not quote.
+- amendment: a requirement with an \`amendment\` is judged against amendment.text and its why, not the quote; its issue_coverage row is covered when the amendment follows from its why. If it does not hold, mark the row partial with note "amendment: <what to change>".
 - requirements: one row per contract requirement id: implemented|partial|missing|deferred|post-deploy|not-applicable, with evidence as a backtick-quoted repo-relative path:line copied verbatim from the changed files, including (group), [slug] and [...slug] folders (e.g. \`apps/web/app/(console)/layout.tsx:12\`, not route.ts:12) and the validate id or test that proves it (validated_by). For a defer or post-deploy requirement add deferral_ok: true only if it is genuinely separate work or only checkable after a deploy, false if it belongs in this change. For a verify out_of_band row (measured by the named job, not in this lane) set instrumented: true only when its budget test or bench is committed and that job is configured, with that path:line as evidence; false otherwise. Do not judge the measured result.
+- post-deploy requirements: deferral_ok is false when the requirement has no \`check\` id, or its check is neither in .forge/post-deploy-checks.json on the default branch nor added by this change (the commands run from that file only).
 - scope: one row per changed file, pre-filled with the engine's authorization: the deliverable id that authorizes it (deliverables may be directories or globs), "test", "incidental" (changelog, lockfile), or "none" with what it changes. Change it only if the diff shows the file does something its deliverable does not cover.
 - preserve: one row per preserve id: intact|violated|unverified, with path:line. The skeleton starts each at "unverified"; set intact only after checking it.
 - regressions: concrete breakages only, each with path:line.

package/bin/lean/sandbox-provider.contract.test.mjs

@@ -328,3 +328,31 @@ describe("remote capacity (GET /status, #4540)", () => {
     assert.equal(await p({ capacity: async () => { throw new Error("x"); } }).capacity(), null);
   });
 });
+
+describe("remote stop at the checkpoint (#4612)", () => {
+  it("httpTransport.stop: POST .../stop, 2xx true, 404/405 false, other statuses throw", async () => {
+    const calls = [];
+    const mk = (status) => httpTransport({ endpoint: "https://pool.example/v1", fetchFn: async (url, init) => { calls.push([init.method, url]); return { status, ok: status < 400, text: async () => "", headers: { get: () => null } }; } });
+    assert.equal(await mk(202).stop("a b"), true);
+    assert.deepEqual(calls[0], ["POST", "https://pool.example/v1/sandboxes/a%20b/stop"]);
+    assert.equal(await mk(404).stop("x"), false);
+    assert.equal(await mk(405).stop("x"), false);
+    await assert.rejects(mk(500).stop("x"), /stop: HTTP 500/);
+  });
+
+  it("provider.stop and providerLanes.stopLane signal the transport, never destroy; no transport stop = false", async () => {
+    const root = tmpDir("remote-stop-");
+    const batch = openBatch(root, "bt");
+    const { provider, transport } = remoteFixture(batch);
+    const stopped = [];
+    const lanes = providerLanes({ provider, laneArgs: () => [], ledgerFor: () => null });
+    assert.equal(await lanes.stopLane(1, { handle: { id: "sbx" } }), false, "the transport has no stop");
+    transport.stop = async (id) => { stopped.push(id); return true; };
+    assert.equal(await lanes.stopLane(1, { handle: { id: "sbx" } }), true);
+    assert.equal(await lanes.stopLane(1, {}), false, "no handle");
+    transport.stop = async () => { throw new Error("boom"); };
+    assert.equal(await provider.stop({ id: "sbx" }), false);
+    assert.deepEqual(stopped, ["sbx"]);
+    assert.deepEqual(transport.destroyed, []);
+  });
+});

package/bin/lean/sandbox-remote.mjs

@@ -44,6 +44,7 @@ export function isActionsEndpoint(endpoint) {
  * GET /sandboxes/:id/logs?cursor=N -> {text, cursor}, GET /sandboxes/:id/result -> lane result (404 = none yet),
  * GET /sandboxes/:id/usage -> {minutes, agent?} (agent: the pool agent that ran it, #4549), DELETE /sandboxes/:id (404 = gone). `Authorization: Bearer <token>`.
  * 429/503 on launch is a retryable capacity error (`Retry-After` seconds). Error text never carries the token.
+ * Optional `POST /sandboxes/:id/stop` (#4612) asks the pool to SIGTERM the lane so its teardown checkpoints and it reports `deferred run.interrupted`; 2xx = sent, 404/405 = unsupported or gone (never a DELETE fallback).
  * Optional `GET /status -> {free: N}` is the pool's free slots (#4540); anything else (404, error, malformed) is unknown (null).
  */
 export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fetch }) {
@@ -73,6 +74,7 @@ export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fet
     async logs(id, cursor = 0) { const r = await call("GET", `${p(id)}/logs?cursor=${encodeURIComponent(cursor)}`); return r.ok ? { text: String(r.data?.text ?? ""), cursor: r.data?.cursor ?? cursor } : { text: "", cursor }; },
     async result(id) { const r = await call("GET", `${p(id)}/result`); return r.ok && r.data && typeof r.data === "object" ? r.data : null; },
     async usage(id) { const r = await call("GET", `${p(id)}/usage`); return r.ok && Number.isFinite(Number(r.data?.minutes)) ? { minutes: Number(r.data.minutes), ...(typeof r.data.agent === "string" && r.data.agent ? { agent: r.data.agent } : {}) } : null; }, // agent: #4549, optional
+    async stop(id) { const r = await call("POST", `${p(id)}/stop`); if (r.ok) return true; if (r.status === 404 || r.status === 405) return false; throw fail("stop", r); },
     async destroy(id) { const r = await call("DELETE", p(id)); if (r.ok || r.status === 404) return true; throw fail("destroy", r); },
     async capacity() {
       // `free` (#4540) and agent liveness `online`/`total` (#4547) are each optional; none valid is unknown.
@@ -167,6 +169,11 @@ export function remoteProvider({ batch, repo, settings = {}, name = "remote", tr
     async capacity() {
       try { return (await transport.capacity?.()) ?? null; } catch { return null; }
     },
+    /** #4612: a graceful stop at the lane's checkpoint; false when unsupported or failed. Never destroys the sandbox. */
+    async stop(h) {
+      if (typeof transport.stop !== "function") return false;
+      try { return (await transport.stop(h.id)) === true; } catch { return false; }
+    },
     async teardown(h) {
       await minutesOf(h);
       try { return (await transport.destroy(h.id)) !== false; } catch { return false; }

package/bin/lean/schedd.mjs

@@ -8,15 +8,18 @@
  *
  * Protocol: newline-delimited JSON, one request per connection.
  *   {op:"submit", argv, cwd, env} → {type:"batch", id, dir}, {type:"row", row}…, {type:"line", text}…, {type:"done", result, report}
- *   {op:"attach", id}             → log.jsonl rows replayed, then live rows/lines and done; a finished batch replays report.json
+ *   {op:"attach", id, resume?}    → (`resume` also clears a pending cancel, #4592) log.jsonl rows replayed, then live rows/lines and done; a finished batch replays report.json
  *                                   ({type:"done", replay:true}) unless it has unrun added issues; a batch nobody hosts is resumed here
  *   {op:"set-parallel", id, k}    → {type:"ok", parallel}
+ *   {op:"requeue", id, issues, reason, by} → {type:"ok", requeued, refused, hosted, reopened} (#4550): see batch.requeue; a finished batch is hosted again
  *   {op:"add", id, issues}        → {type:"ok", added, skipped, hosted} (#4408): merged into the batch's `add` file, which a
  *                                   hosted runner reads on its next pass and an unhosted batch on its next resume
- *   {op:"cancel", id}             → {type:"ok", cancelled:true, hosted} (#4376): writes the batch's `cancel` file; that batch
+ *   {op:"cancel", id, stopRemote?}           → {type:"ok", cancelled:true, hosted} (#4376): writes the batch's `cancel` file; that batch
  *                                   admits nothing more, its running local lanes get SIGTERM (their teardown saves the work)
  *                                   and the rest end held; no other batch and not the daemon. A finished, unhosted batch:
  *                                   {type:"ok", cancelled:false, finished:true}, nothing written
+ *   {op:"hold"|"release", id, issues} → {type:"ok", changed, hosted} (#4592): merges into / removes from the batch's `hold` file; a hosted
+ *                                   runner admits no held issue from its next pass (running lanes are not stopped)
  *   {op:"status"}                 → {type:"status", pid, batches:[{id, running}]}
  * Failures answer {type:"error", message}. A client closing its connection never cancels a batch (only `cancel` stops one), and stopping the daemon
  * never stops a lane (lanes are detached sessions). On start the daemon resumes every daemon-hosted batch without a
@@ -39,6 +42,7 @@ import { batchRoot, listBatches, openBatch } from "./batch.mjs";
 export const IDLE_MS = 10 * 60 * 1000;
 export const STOP_MS = 10 * 1000;
 export const LOCK_CHECK_MS = 5 * 1000;
+export const DUE_MS = 15 * 60 * 1000; // #4627: how often the due callback (windowed post-deploy monitoring) runs while the daemon is up
 
 export function scheddPaths(dir = schedDir()) {
   return { dir, sock: join(dir, "schedd.sock"), lock: join(dir, "schedd.lock"), log: join(dir, "schedd.log") };
@@ -81,7 +85,7 @@ function takeLock(lock, pid, alive) {
  */
 export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(process.env.FORGEDOCK_SCHEDD_IDLE_MS) || IDLE_MS,
   root = batchRoot(), log = (m) => console.log(m), pid = process.pid, alive = pidAlive, resumeOnStart = true, stopMs = STOP_MS,
-  lockCheckMs = LOCK_CHECK_MS } = {}) {
+  lockCheckMs = LOCK_CHECK_MS, due = null, dueMs = Number(process.env.FORGEDOCK_SCHEDD_DUE_MS) || DUE_MS } = {}) {
   const p = scheddPaths(dir);
   mkdirSync(dir, { recursive: true });
   const lock = takeLock(p.lock, pid, alive);
@@ -140,11 +144,26 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
       const { added, skipped } = b.addIssues(req.issues ?? []);
       return send({ type: "ok", added, skipped, hosted: hosted.has(req.id) }, true);
     }
+    if (req.op === "requeue") {
+      // #4550: the runner applies the entries on its next pass; a finished, unhosted batch is reopened (hosted as a resume).
+      const b = openBatch(root, req.id);
+      if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);
+      const { requeued, refused } = b.requeue(req.issues ?? [], { reason: req.reason, by: req.by });
+      const reopen = requeued.length > 0 && !hosted.has(req.id) && !starting.has(req.id);
+      if (reopen) await host({ argv: ["--resume", req.id], cwd: process.cwd(), env: {} });
+      return send({ type: "ok", requeued, refused, hosted: hosted.has(req.id), reopened: reopen }, true);
+    }
+    if (req.op === "hold" || req.op === "release") {
+      const b = openBatch(root, req.id);
+      if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);
+      const changed = req.op === "hold" ? b.holdIssues(req.issues ?? []) : b.releaseIssues(req.issues ?? []);
+      return send({ type: "ok", changed, hosted: hosted.has(req.id) }, true);
+    }
     if (req.op === "cancel") {
       const b = openBatch(root, req.id);
       if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);
       if (!hosted.has(req.id) && b.readReport()) return send({ type: "ok", cancelled: false, finished: true }, true);
-      b.requestCancel({ reason: "operator" });
+      b.requestCancel({ reason: "operator", stopRemote: req.stopRemote === true });
       return send({ type: "ok", cancelled: true, hosted: hosted.has(req.id) }, true);
     }
     const sub = (m) => send(m, m.type === "done" || m.type === "error");
@@ -153,6 +172,7 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
       return send({ type: "batch", id: ent.id, dir: ent.dir });
     }
     if (req.op === "attach") {
+      if (req.resume) { const rb = openBatch(root, req.id); if (rb.exists()) rb.clearCancel(); } // #4592: the operator's resume continues a cancelled batch the daemon still hosts
       if (!hosted.has(req.id) && starting.has(req.id)) await starting.get(req.id).catch(() => {});
       const live = hosted.get(req.id);
       if (live) {
@@ -164,7 +184,7 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
       const b = openBatch(root, req.id);
       if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);
       const rep = b.readReport();
-      if (rep && !(rep.rows ?? []).some((r) => r.outcome === "held") && !b.unrunAdds().length) {
+      if (rep && !(rep.rows ?? []).some((r) => r.outcome === "held") && !b.unrunAdds().length && !b.unrunRequeues().length) {
         return send({ type: "done", replay: true, result: { rows: rep.rows ?? [], crossLane: rep.crossLane ?? [], batch: b.id, ok: !!rep.ok }, report: rep.report ?? null }, true);
       }
       const ent = await host({ argv: ["--resume", req.id], cwd: process.cwd(), env: {} }, sub);
@@ -203,6 +223,7 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
     if (closing) return closing;
     clearInterval(idleTimer);
     clearInterval(lockTimer);
+    if (dueTimer) clearInterval(dueTimer);
     for (const c of conns) c.destroy();
     const stopping = [...runs.keys()];
     for (const ac of runs.values()) ac.abort();
@@ -232,6 +253,14 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
     else if (!existsSync(p.sock)) { log(`schedd: lost socket ${p.sock}, exiting`); close(); }
   }, lockCheckMs);
   lockTimer.unref?.();
+  // #4627: windowed post-deploy checks. One run at a time; a failure is logged and never stops the daemon.
+  let dueRunning = false;
+  const dueTimer = due ? setInterval(async () => {
+    if (closing || dueRunning) return;
+    dueRunning = true;
+    try { await due(); } catch (e) { log(`schedd: due run failed: ${e?.message ?? e}`); } finally { dueRunning = false; }
+  }, dueMs) : null;
+  dueTimer?.unref?.();
 
   // Daemon restart: resume every daemon-hosted batch that never wrote its report; live lanes are re-adopted.
   if (resumeOnStart) {

package/bin/lean/schedd.test.mjs

@@ -208,6 +208,32 @@ await orchestrateFromCli(["1", "2", "--parallel", "2", "--repo", "o/r", "--no-pr
     } finally { await h.cleanup(); }
   });
 
+  it("#4550: --requeue on a finished batch with a report reopens it through the daemon and runs the issue again; --add still skips it", async () => {
+    const h = host();
+    try {
+      await h.daemon();
+      const client = { ...h.client, io: { gh: async (a) => (a[0] === "issue" ? JSON.stringify({ state: "OPEN", labels: [] }) : "o/r\n") } };
+      await withRoot(h, () => capture(async () => {
+        writeFileSync(h.release, "");
+        const first = await orchestrateFromCli(["1", "--parallel", "2", "--repo", "o/r", "--no-prefilter"], h.client);
+        assert.deepEqual(first.rows.map((r) => [r.issue, r.outcome]), [[1, "merged"]]);
+        const [id] = listBatches(h.root);
+        const b = openBatch(h.root, id);
+        // The lane ended needs-human and the operator decided it: the finished batch holds that terminal row.
+        b.store.save({ ...b.store.load(), results: { 1: { issue: 1, outcome: "needs-human", pr: null, cost_usd: 0, minutes: 0 } } });
+        const rep = b.readReport();
+        b.writeReport({ ...rep, rows: [{ issue: 1, outcome: "needs-human" }] });
+        assert.deepEqual((await orchestrateFromCli(["--add", id, "1"], client)).skipped.map((x) => x.reason), ["already in batch"]);
+        const res = await orchestrateFromCli(["--requeue", id, "1", "--reason", "decided"], client);
+        assert.deepEqual(res.requeued, [1]);
+        await until(() => h.launched().length === 2);
+        await until(() => b.store.load()?.results?.[1]?.outcome === "merged" && b.readReport()?.rows?.[0]?.outcome === "merged");
+        assert.deepEqual(listBatches(h.root), [id], "no second batch");
+        assert.equal(b.readReport().rows[0].requeued.reason, "decided");
+      }));
+    } finally { await h.cleanup(); }
+  });
+
   it("#4376: --cancel stops one batch (its lane torn down, the rest held, report written); the other batch and the daemon run on", async () => {
     const h = host();
     try {
@@ -238,6 +264,36 @@ await orchestrateFromCli(["1", "2", "--parallel", "2", "--repo", "o/r", "--no-pr
     } finally { await h.cleanup(); }
   });
 
+  it("#4592: --hold keeps #2 from running on a live batch; --resume <id> 2 after a cancel re-admits it", async () => {
+    const h = host();
+    try {
+      await h.daemon();
+      await withRoot(h, () => capture(async () => {
+        const first = orchestrateFromCli(["1", "2", "--parallel", "1", "--repo", "o/r", "--no-prefilter"], h.client);
+        await until(() => h.launched().length === 1 && h.lanePids().length === 1);
+        const [id] = listBatches(h.root);
+        const b = openBatch(h.root, id);
+        const held = await orchestrateFromCli(["--hold", id, "2", "x"], h.client);
+        assert.deepEqual(held.changed, [2]);
+        assert.deepEqual(b.readHeld(), [2]);
+        await assert.rejects(orchestrateFromCli(["--hold", id], h.client), /usage/);
+        await assert.rejects(orchestrateFromCli(["--release", "nope", "2"], h.client), /no batch nope/);
+        const res = await orchestrateFromCli(["--cancel", id], h.client);
+        assert.equal(res.cancelled, true);
+        const cancelled = await first;
+        assert.deepEqual(cancelled.rows.map((r) => [r.issue, r.outcome]), [[1, "held"], [2, "held"]]);
+        assert.deepEqual(b.readHeld(), [2], "the hold survives the cancel");
+        // The issue's case: a resume naming the issue re-admits it (it used to print `skipped #2 (already in batch)`).
+        const io = { gh: async (x) => (x[0] === "issue" ? JSON.stringify({ state: "OPEN" }) : "o/r\n") };
+        const resumed = orchestrateFromCli(["--resume", id, "2"], { ...h.client, io });
+        await until(() => b.readCancel() === null && b.readHeld().length === 0);
+        setTimeout(() => writeFileSync(h.release, ""), 300);
+        const done = await resumed;
+        assert.deepEqual(done.rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"]]);
+      }));
+    } finally { await h.cleanup(); }
+  });
+
   it("#4481: a batch cancelled through the daemon is not resumed by a schedd restart", async () => {
     const h = host();
     try {
@@ -457,3 +513,31 @@ await orchestrateFromCli(["1", "2", "--parallel", "2", "--repo", "o/r", "--no-pr
     assert.deepEqual(env, { NODE_OPTIONS: "x", PATH: "/c", CLAUDE_CONFIG_DIR: "/acct-b", FORGEDOCK_SCHED_DIR: "/s" });
   });
 });
+
+describe("schedd due timer (#4627)", () => {
+  const boot = async (opts) => startDaemon({ dir: tmpDir("schedd-due-"), root: tmpDir("schedd-due-b-"), runBatch: async () => ({}), resumeOnStart: false, log: () => {}, ...opts });
+
+  it("runs the due callback on its interval, never overlapped, and survives a throwing callback", async () => {
+    let calls = 0, active = 0, overlap = false;
+    const logs = [];
+    const d = await boot({ dueMs: 15, log: (m) => logs.push(m), due: async () => {
+      calls++; active++; if (active > 1) overlap = true;
+      await new Promise((r) => setTimeout(r, 40));
+      active--; if (calls === 1) throw new Error("boom");
+    } });
+    try {
+      await until(() => calls >= 3);
+      assert.equal(overlap, false);
+      assert.ok(logs.some((m) => /due run failed: boom/.test(m)));
+      assert.ok(existsSync(d.sock));
+    } finally { await d.close(); }
+    const n = calls;
+    await new Promise((r) => setTimeout(r, 80));
+    assert.equal(calls, n, "the timer is cleared on close");
+  });
+
+  it("without a due callback there is no timer", async () => {
+    const d = await boot({ dueMs: 10 });
+    await d.close();
+  });
+});

package/bin/lean/sequence.mjs

@@ -431,3 +431,29 @@ export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerat
     return { ok: true, moves: moves.map(({ from, to }) => ({ from, to })), commit: (await g(["rev-parse", "HEAD"])).trim() || null };
   } catch (e) { return await fail(`deterministic renumber failed: ${String(e?.message ?? e).split("\n")[0]}`); }
 }
+
+/**
+ * #4591: hand-named migrations. In a drizzle-style dir (`<dir>/meta/_journal.json` at `ref`) a lane-added `<tag>.sql` the
+ * generator wrote always has a journal entry the lane added and a `<dir>/meta/<prefix>_snapshot.json` the lane added
+ * (`generate --custom` too); a file named by hand has neither, and its made-up timestamp collides with a sibling lane's.
+ * No journal dir: []. @returns {Promise<string[]>} one problem per file
+ */
+export async function generatorProblems({ git, base, ref = "HEAD" }) {
+  const g = out(git), problems = [];
+  const added = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=A", `${base}...${ref}`])).filter((f) => !SKIP_RE.test(f));
+  const tagsAt = async (r, jp) => { try { return new Set((JSON.parse(await g(["show", `${r}:${jp}`])).entries ?? []).map((e) => e?.tag)); } catch { return new Set(); } };
+  for (const dir of [...new Set(added.filter((f) => f.endsWith(".sql")).map((f) => dirname(f)))]) {
+    const jp = posix.join(dir, "meta", "_journal.json");
+    if (!(await g(["show", `${ref}:${jp}`])).trim()) continue;
+    const [was, now] = [await tagsAt(base, jp), await tagsAt(ref, jp)];
+    for (const f of added.filter((x) => dirname(x) === dir && x.endsWith(".sql"))) {
+      const tag = basename(f, ".sql"), prefix = /^(\d+)[_-]/.exec(tag)?.[1];
+      if (!prefix) continue;
+      const why = [];
+      if (!now.has(tag) || was.has(tag)) why.push("no journal entry added for it");
+      if (!added.includes(posix.join(dir, "meta", `${prefix}_snapshot.json`))) why.push(`no meta/${prefix}_snapshot.json added`);
+      if (why.length) problems.push(`${f}: not produced by the migration generator (${why.join("; ")})`);
+    }
+  }
+  return problems;
+}

package/bin/lean/sequence.test.mjs

@@ -8,9 +8,9 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber, numberOnlyChange, headerOnlyChange, renumberLane, resolveSequenceConflicts } from "./sequence.mjs";
+import { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber, numberOnlyChange, headerOnlyChange, renumberLane, resolveSequenceConflicts, generatorProblems } from "./sequence.mjs";
 import { makeSequenceLeaseIo } from "./seqlease.mjs";
-import { sequencePrompt, sequenceSyncNote } from "./prompts.mjs";
+import { sequencePrompt, sequenceSyncNote, migrationGeneratorPrompt, builderImplementPrompt } from "./prompts.mjs";
 
 const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
 const gitIn = (cwd) => async (a) => sh(cwd, ...a);
@@ -453,3 +453,42 @@ describe("sequence-numbered documents: two siblings each add an ADR (#4385)", ()
     assert.match(p, /series index/);
   });
 });
+
+describe("hand-named migrations (#4591)", () => {
+  const T1 = "20261025020000_sso_domain_verification", T2 = "20261025020100_next";
+  function base() {
+    const d = tmpDir("gen-");
+    sh(d, "init", "-q", "-b", "main");
+    put(d, { "db/meta/_journal.json": journal("20261024000000_init"), "db/meta/20261024000000_snapshot.json": "{}\n", "db/20261024000000_init.sql": "x;\n" });
+    commit(d, "init");
+    sh(d, "checkout", "-qb", "lane");
+    return d;
+  }
+  it("flags a hand-named file with no journal entry and no snapshot, naming both gaps", async () => {
+    const d = base();
+    put(d, { [`db/${T1}.sql`]: "y;\n" });
+    commit(d, "hand");
+    const p = await generatorProblems({ git: gitIn(d), base: "main" });
+    assert.equal(p.length, 1);
+    assert.match(p[0], /20261025020000_sso_domain_verification\.sql: not produced by the migration generator \(no journal entry added for it; no meta\/20261025020000_snapshot\.json added\)/);
+  });
+  it("accepts generator output (journal entry + snapshot, also --custom) and dirs without a journal", async () => {
+    const d = base();
+    put(d, { [`db/${T1}.sql`]: "y;\n", [`db/${T2}.sql`]: "z;\n", "db/meta/_journal.json": journal("20261024000000_init", T1, T2), "db/meta/20261025020000_snapshot.json": "{}\n", "db/meta/20261025020100_snapshot.json": "{}\n", "plain/0001_a.sql": "a;\n" });
+    commit(d, "generated");
+    assert.deepEqual(await generatorProblems({ git: gitIn(d), base: "main" }), []);
+  });
+  it("flags an entry without a snapshot, and accepts an engine renumber (P3)", async () => {
+    const d = base();
+    put(d, { [`db/${T1}.sql`]: "y;\n", "db/meta/_journal.json": journal("20261024000000_init", T1) });
+    commit(d, "journal only");
+    assert.match((await generatorProblems({ git: gitIn(d), base: "main" }))[0], /\(no meta\/20261025020000_snapshot\.json added\)/);
+    const f = fixture();
+    renumber(f);
+    assert.deepEqual(await generatorProblems({ git: gitIn(f), base: "main" }), []);
+  });
+  it("the fix prompt and the builder rule forbid naming migrations by hand", () => {
+    assert.match(migrationGeneratorPrompt(["db/x.sql: not produced by the migration generator (no journal entry added for it)"]), /drizzle-kit generate --custom[\s\S]*Never name or number migration files by hand/);
+    assert.match(builderImplementPrompt("local"), /Never name or number migration files by hand/);
+  });
+});

package/bin/lean/toolstate.mjs

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4590: tool state that must never ride a lane branch: the engine's own scratch (.forge-lean/) and tool caches
+ * (.eslintcache, *.tsbuildinfo, and a generated next-env.d.ts when the repo ignores it). `info/exclude` only hides untracked
+ * files, so a force-added or checkpoint-staged one gets committed and then conflicts in every base merge. This is the
+ * deterministic gate: before a push, files the branch ADDED against the merge base are removed from the index (a file the
+ * base itself tracks is the repo's own choice and is never touched). Git is injected: `git(args) -> stdout`, throws on failure.
+ */
+export const LEAN_SCRATCH = ".forge-lean/";
+const CACHE_BASENAMES = [/^\.eslintcache$/, /\.tsbuildinfo$/];
+const NEXT_ENV = "next-env.d.ts";
+
+/** Lines `forgedock init` adds to a repo's .gitignore (next-env.d.ts only for Next.js repos). */
+export const GITIGNORE_LINES = [".forge-lean/", ".eslintcache", "*.tsbuildinfo"];
+export const GITIGNORE_NEXT_LINE = NEXT_ENV;
+
+const base = (p) => p.slice(p.lastIndexOf("/") + 1);
+/** Deny-listed path? `nextEnvIgnored`: the repo's own .gitignore ignores next-env.d.ts, so a tracked copy is stray. */
+export function isToolState(path, { nextEnvIgnored = false } = {}) {
+  const p = String(path ?? "").replace(/^\.\//, "");
+  if (!p) return false;
+  if (p.startsWith(LEAN_SCRATCH) || p === LEAN_SCRATCH.slice(0, -1)) return true;
+  const b = base(p);
+  return CACHE_BASENAMES.some((re) => re.test(b)) || (nextEnvIgnored && b === NEXT_ENV);
+}
+export const denied = (paths, opts) => paths.filter((p) => isToolState(p, opts));
+
+const zlist = (out) => String(out ?? "").split("\0").filter(Boolean);
+const quiet = async (git, args) => { try { await git(args); return true; } catch { return false; } };
+
+/** The subset of `paths` the repo's .gitignore ignores (`--no-index`: tracked copies count). */
+async function ignoredNextEnv(git, paths) {
+  const out = [];
+  for (const p of paths) if (base(p) === NEXT_ENV && await quiet(git, ["check-ignore", "-q", "--no-index", "--", p])) out.push(p);
+  return out;
+}
+
+/** Deny-listed paths among `paths`, including next-env.d.ts copies the repo ignores. */
+export async function strayPaths(git, paths) {
+  const plain = denied(paths);
+  const nexts = await ignoredNextEnv(git, paths.filter((p) => !plain.includes(p)));
+  return [...plain, ...nexts];
+}
+
+/** After `git add -A`: unstage deny-listed paths so a checkpoint never commits them. Returns true when something else is staged. */
+export async function unstageToolState(git) {
+  const staged = zlist(await git(["diff", "--cached", "--name-only", "-z"]));
+  const stray = await strayPaths(git, staged);
+  if (stray.length) await git(["reset", "-q", "--", ...stray]);
+  return stray.length ? (await git(["diff", "--cached", "--name-only"])).trim() !== "" : staged.length > 0;
+}
+
+/**
+ * Remove from the index (and commit) the deny-listed files this branch added against `base`. Returns the removed paths ([]
+ * when the branch is clean). Never throws: a failure leaves the branch as it was and the push proceeds.
+ */
+export async function untrackToolState({ git, base: ref, ev = () => {} }) {
+  try {
+    const added = zlist(await git(["diff", "--diff-filter=A", "--name-only", "-z", `${ref}...HEAD`]));
+    const stray = await strayPaths(git, added);
+    if (!stray.length) return [];
+    await git(["rm", "--cached", "-r", "-q", "--ignore-unmatch", "--", ...stray]);
+    await git(["commit", "--no-verify", "-m", "chore: untrack lane tool state (#4590)", "-m", stray.slice(0, 20).join("\n")]);
+    ev({ event: "TOOLSTATE_UNTRACKED", files: stray.slice(0, 20), count: stray.length });
+    return stray;
+  } catch (e) {
+    ev({ event: "TOOLSTATE_UNTRACK_FAILED", error: String(e?.message ?? e).slice(0, 200) });
+    return [];
+  }
+}
+
+/** The deny-list lines a repo's .gitignore text lacks (append-only; `next`: also next-env.d.ts, for Next.js repos). */
+export function gitignoreAdditions(text, { next = false } = {}) {
+  const have = new Set(String(text ?? "").split(/\r?\n/).map((l) => l.trim().replace(/^\//, "")));
+  return [...GITIGNORE_LINES, ...(next ? [GITIGNORE_NEXT_LINE] : [])].filter((l) => !have.has(l));
+}

package/bin/lean/toolstate.test.mjs

@@ -0,0 +1,83 @@
+// 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 { join, dirname } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { isToolState, denied, untrackToolState, unstageToolState, gitignoreAdditions } from "./toolstate.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8" });
+const put = (cwd, f, t = "x\n") => { mkdirSync(dirname(join(cwd, f)), { recursive: true }); writeFileSync(join(cwd, f), t); };
+const repo = () => {
+  const d = tmpDir("toolstate-repo-");
+  sh(d, "init", "-q", "-b", "main"); sh(d, "config", "user.email", "t@t"); sh(d, "config", "user.name", "t");
+  put(d, "src/a.js"); put(d, ".gitignore", "next-env.d.ts\n"); sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "base");
+  sh(d, "checkout", "-q", "-b", "lane");
+  return d;
+};
+const gitIn = (d) => async (args) => execFileSync("git", args, { cwd: d, encoding: "utf8" });
+
+describe("isToolState (#4590)", () => {
+  it("matches scratch and caches at any depth, nothing else", () => {
+    for (const p of [".forge-lean/result.json", ".forge-lean/logs/x", "apps/worker/.eslintcache", ".eslintcache", "a/b/tsconfig.tsbuildinfo"]) assert.ok(isToolState(p), p);
+    for (const p of ["src/eslintcache.ts", "src/.eslintcache.md", "forge-lean/x", "docs/.forge-lean.md", "apps/web/next-env.d.ts", "x.tsbuildinfo.json"]) assert.ok(!isToolState(p), p);
+  });
+  it("next-env.d.ts only when the repo ignores it", () => {
+    assert.ok(isToolState("apps/web/next-env.d.ts", { nextEnvIgnored: true }));
+    assert.deepEqual(denied(["a", ".eslintcache"]), [".eslintcache"]);
+  });
+});
+
+describe("untrackToolState on a real repo (#4590)", () => {
+  it("removes what the lane added, keeps product files and files the base tracks, then a second run is a no-op", async () => {
+    const d = repo();
+    put(d, "src/b.js"); put(d, ".forge-lean/result.json"); put(d, "apps/worker/.eslintcache"); put(d, "apps/web/next-env.d.ts");
+    sh(d, "add", "-f", "-A");
+    sh(d, "commit", "-q", "-m", "lane");
+    const events = [];
+    const removed = await untrackToolState({ git: gitIn(d), base: "main", ev: (e) => events.push(e) });
+    assert.deepEqual(removed.sort(), [".forge-lean/result.json", "apps/web/next-env.d.ts", "apps/worker/.eslintcache"]);
+    assert.equal(events[0].event, "TOOLSTATE_UNTRACKED");
+    assert.deepEqual(sh(d, "diff", "--name-only", "main...HEAD").trim().split("\n"), ["src/b.js"]);
+    assert.ok(sh(d, "status", "--porcelain").includes("?? .forge-lean/") || sh(d, "ls-files", "--others").includes(".forge-lean"), "files stay on disk");
+    assert.deepEqual(await untrackToolState({ git: gitIn(d), base: "main" }), []);
+  });
+
+  it("a cache the base already tracks is the repo's own choice and stays", async () => {
+    const d = repo(); sh(d, "checkout", "-q", "main");
+    put(d, "pkg/.eslintcache"); sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "base cache"); sh(d, "checkout", "-q", "lane"); sh(d, "merge", "-q", "main");
+    put(d, "src/c.js"); sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "lane");
+    assert.deepEqual(await untrackToolState({ git: gitIn(d), base: "main" }), []);
+    assert.ok(sh(d, "ls-files").includes("pkg/.eslintcache"));
+  });
+
+  it("a git failure never throws", async () => {
+    const events = [];
+    assert.deepEqual(await untrackToolState({ git: async () => { throw new Error("boom"); }, base: "main", ev: (e) => events.push(e) }), []);
+    assert.equal(events[0].event, "TOOLSTATE_UNTRACK_FAILED");
+  });
+});
+
+describe("unstageToolState (#4590)", () => {
+  it("a checkpoint's add -A stages the work but not the scratch or caches", async () => {
+    const d = repo(); put(d, "src/b.js"); put(d, ".eslintcache"); put(d, ".forge-lean/x");
+    sh(d, "add", "-A", "-f");
+    assert.equal(await unstageToolState(gitIn(d)), true);
+    assert.equal(sh(d, "diff", "--cached", "--name-only").trim(), "src/b.js");
+  });
+  it("only tool state staged: nothing to commit", async () => {
+    const d = repo(); put(d, ".eslintcache"); sh(d, "add", "-f", ".eslintcache");
+    assert.equal(await unstageToolState(gitIn(d)), false);
+  });
+});
+
+describe("gitignoreAdditions (#4590)", () => {
+  it("adds only the missing lines, and next-env.d.ts only for Next.js", () => {
+    assert.deepEqual(gitignoreAdditions(""), [".forge-lean/", ".eslintcache", "*.tsbuildinfo"]);
+    assert.deepEqual(gitignoreAdditions("node_modules\n/.eslintcache\n.forge-lean/\n"), ["*.tsbuildinfo"]);
+    assert.deepEqual(gitignoreAdditions(".forge-lean/\n.eslintcache\n*.tsbuildinfo\n"), []);
+    assert.deepEqual(gitignoreAdditions(".forge-lean/\n.eslintcache\n*.tsbuildinfo\n", { next: true }), ["next-env.d.ts"]);
+  });
+});