forgedock 1.32.1 → 1.33.0

package/bin/lean/prompts.mjs

@@ -215,18 +215,27 @@ export function reproPlanNote(on) {
   return `\n\nThis issue is a bug. When it is testable, ${CONTRACT_FILE} must also carry "repro_test":{"path":"<test file>","id":"<test name>","command":"<exact command that runs only that test>"}: a test that fails on the base and passes after the fix. The engine proves it with scripts/acceptance-red-green.sh (head's changed test files are overlaid on the base) and fails the run if it is not red on base and green on head. When it is not testable (specs, docs, workflows, environment), write "repro_test":"none","repro_test_reason":"<one line why>" instead.`;
 }
 
+/** forge#4519: the repo's generated, bot-owned globs (forge.yaml maintenance.generated_paths via hotspots.sh); "" when none. */
+function generatedNote(facts) {
+  const globs = Array.isArray(facts?.generated_paths) ? facts.generated_paths.filter((g) => typeof g === "string" && g) : [];
+  if (!globs.length) return "";
+  return `\n\nGenerated paths (forge.yaml maintenance.generated_paths, owned by the repo's generator): ${globs.join(", ")}. Never list or amend them in as deliverables and never commit changes to them; the engine refuses such amendments.`;
+}
+
 /** forge#4195: hotspot facts for the plan prompt: one sentence plus one line per over-threshold file; "" when none. */
 export function hotspotPlanNote(facts) {
-  if (!facts || facts.enabled === false || !Array.isArray(facts.files)) return "";
+  const gen = generatedNote(facts);
+  if (!facts || facts.enabled === false || !Array.isArray(facts.files)) return gen;
   const hot = facts.files.filter((f) => f?.over && !f.excluded);
-  if (!hot.length) return "";
-  return `\n\nHotspots (scripts/hotspots.sh): an Affected File below is over ${facts.file_lines} lines, so the contract must put new logic in a new or neighbouring module and give the hotspot only wiring (an import and a call); growing it by more than ${facts.growth_lines} lines needs "hotspot-exempt: <reason>" in that deliverable's change.\n${hot.map((f) => `- ${f.path}: ${f.lines} lines, ${f.commits_90d} commits/90d`).join("\n")}`;
+  if (!hot.length) return gen;
+  return gen + `\n\nHotspots (scripts/hotspots.sh): an Affected File below is over ${facts.file_lines} lines, so the contract must put new logic in a new or neighbouring module and give the hotspot only wiring (an import and a call); growing it by more than ${facts.growth_lines} lines needs "hotspot-exempt: <reason>" in that deliverable's change.\n${hot.map((f) => `- ${f.path}: ${f.lines} lines, ${f.commits_90d} commits/90d`).join("\n")}`;
 }
 
 /** forge#4195: the builder's growth rule with the effective thresholds; "" when the check is off. */
 export function hotspotBuildRule(facts) {
-  if (!facts || facts.enabled === false || !(facts.file_lines > 0) || !(facts.growth_lines > 0)) return "";
-  return `\n\nDon't grow a file over ${facts.file_lines} lines by more than ${facts.growth_lines} lines. Put new code next to it.`;
+  const gen = generatedNote(facts);
+  if (!facts || facts.enabled === false || !(facts.file_lines > 0) || !(facts.growth_lines > 0)) return gen;
+  return gen + `\n\nDon't grow a file over ${facts.file_lines} lines by more than ${facts.growth_lines} lines. Put new code next to it.`;
 }
 
 /** #4322: tests that enumerate the siblings of a module the issue names (bin/lean/enumerating.mjs), for the plan; "" when none. */
@@ -248,7 +257,7 @@ export function missingEntriesPrompt(missing, mode = "local") {
   return `These tests enumerate the siblings of symbols or files this change adds, but do not name them (CI will fail on the stale list):\n${missing.slice(0, 30).map((m) => `- ${m.symbol} (${m.module}) -> ${m.test}:${m.line}`).join("\n")}\n\nFor each, add the symbol to that test's list, ${NOT_MEMBER}. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
 }
 
-const RENUMBER_RULE = "Renumber the lane's files, never the base's: rename each with git mv to its new number, keep the SQL (or other migration source) byte-identical, change a numbered document (e.g. an ADR) only in its own number (its title), regenerate the snapshot and journal with the repo's own migration generator (never hand- or text-merge the journal), keep journal entries strictly ordered, and update every reference to the old name, including the series index (e.g. docs/adr/README.md) so it lists both the base's entry and yours.";
+const RENUMBER_RULE = "Renumber the lane's files, never the base's: rename each with git mv to its new number, keep the SQL (or other migration source) byte-identical except a first-line header naming its own number/tag, which follows the new one, change a numbered document (e.g. an ADR) only in its own number (its title), regenerate the snapshot and journal with the repo's own migration generator (never hand- or text-merge the journal), keep journal entries strictly ordered, and update every reference to the old name, including the series index (e.g. docs/adr/README.md) so it lists both the base's entry and yours.";
 
 /** #4322: lane-added sequence-numbered files whose number the base already uses, at hand-off or after a base-sync. */
 export function sequencePrompt(collisions, lane, mode = "local") {
@@ -301,7 +310,8 @@ const BLOCK_RULES = `"blocked" needs a typed "block" in ${RESULT_FILE}, one of:
 - {"kind":"dependency","issues":[N]}: an open upstream issue must land first. The engine requeues this issue behind it.
 - {"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".`;
+"An upstream issue must land first", "needs a split" and "needs prod data that read-only monitoring can read" are never "human".
+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) {
   return `Your ${RESULT_FILE} says "blocked", but ${String(problem).slice(0, 1000)}. That is not a block that needs a human.\n\n${BLOCK_RULES}\n\nEither do the work (fix, commit, update the stage notes and ${RESULT_FILE}) or write a valid typed "block". Do not push or touch GitHub.`;

package/bin/lean/recovery.test.mjs

@@ -56,6 +56,32 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     assert.equal(lines.length, 1); assert.match(lines[0], /^unrecovered: #1 \(ci\.red: recovery ci\.red ended needs-human: CI verification failed again\)$/);
   });
 
+  it("#4505 budget-exceeded: one recovery lane from the checkpoint at the next size; dependents stay queued; no relabel while it recovers", async () => {
+    const BE = (detail, more = {}) => ({ terminalReason: "budget-exceeded", code: "budget.exceeded", detail, branch: "feat/issue-1-lean", ...more });
+    const relabels = [];
+    const { rows, calls, decisions } = await batch({ 1: [BE("Implement turn budget spent (size S, 25 turns; 30 used)"), { terminalReason: "merged", pr: 101 }], 2: [{ terminalReason: "merged", pr: 102 }] },
+      { 2: "**Depends on**: #1" }, { relabelNeedsHuman: async (x) => { relabels.push(x); } });
+    const r = byIssue(rows);
+    assert.deepEqual(calls.filter((c) => c.n === 1).map((c) => c.recover), [null, { code: "budget.exceeded", attempt: 1, final: true }]);
+    assert.equal(r[1].outcome, "merged"); assert.equal(r[1].recovered, "budget.exceeded");
+    assert.equal(r[2].outcome, "merged", "the dependent stayed queued and ran");
+    assert.ok(calls.findIndex((c) => c.n === 2) > calls.findLastIndex((c) => c.n === 1), "the dependent ran after the recovered merge");
+    assert.ok(decisions.some((d) => d.issue === 1 && /recovery lane for budget\.exceeded .*dependents stay queued/.test(d.what)));
+    assert.equal(relabels.length, 0, "never labelled needs-human");
+  });
+
+  it("#4505 an unrecovered budget-exceeded (recovery off) is relabelled once by the runner, parks dependents and is listed unrecovered", async () => {
+    const relabels = [];
+    const { rows, calls } = await batch({ 1: [{ terminalReason: "budget-exceeded", code: "budget.exceeded", detail: "Implement turn budget spent (size S)" }], 2: [] },
+      { 2: "**Depends on**: #1" }, { maxAttempts: 0, relabelNeedsHuman: async (x) => { relabels.push(x); } });
+    const r = byIssue(rows);
+    assert.equal(calls.filter((c) => c.n === 1).length, 1);
+    assert.equal(r[1].outcome, "budget-exceeded");
+    assert.equal(relabels.length, 1); assert.equal(relabels[0].issue, 1); assert.match(relabels[0].evidence, /budget\.exceeded[\s\S]*size S/);
+    assert.equal(r[2].outcome, "skipped"); assert.ok(!calls.some((c) => c.n === 2));
+    assert.ok(formatOutcomeLists(rows).some((l) => /^unrecovered: #1 \(budget\.exceeded: Implement turn budget spent/.test(l)));
+  });
+
   it("human codes (product-decision, spend) are never recovered, still skip dependents and are the only escalations, asked once while other lanes keep running", async () => {
     const { rows, calls, decisions } = await batch({
       1: [NH("builder.blocked", "Builder is blocked (product-decision): pick a pricing model")],

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

@@ -54,7 +54,7 @@ function fakeTransport({ launchError = null } = {}) {
 function remoteFixture(batch, { launchError = null } = {}) {
   const transport = fakeTransport({ launchError });
   const provider = remoteProvider({ batch, repo: "o/r", settings: { image: "img:1", cacheStore: "s3://cache", tokenEnv: "FD_TOKEN", secrets: ["GH_TOKEN"] }, transport,
-    env: { GH_TOKEN: SECRET, FD_TOKEN: TOKEN }, credentials: (n) => ({ GH_TOKEN: SECRET, FD_TOKEN: TOKEN })[n] ?? null });
+    env: { GH_TOKEN: SECRET, FD_TOKEN: TOKEN }, credentials: (n) => ({ GH_TOKEN: SECRET, FD_TOKEN: TOKEN })[n] ?? null, gitIdentity: () => ({}) });
   return {
     provider, transport,
     finish: (h, result) => { const b = transport.boxes.get(h.id); b.log += `lane done; token ${SECRET} and ${TOKEN}\n`; b.result = result; b.state = "exited"; b.minutes = 3.5; },
@@ -147,6 +147,23 @@ describe("remote adapter (#4254)", () => {
     assert.equal(transport.specs[0].env.GH_TOKEN, "from-keychain");
   });
 
+  it("the sandbox commits as the dispatching host's git identity; a lane env identity wins", async () => {
+    const batch = openBatch(join(tmpDir("remote-git-"), "batches"), "bt");
+    const transport = fakeTransport();
+    const p = remoteProvider({ batch, repo: "o/r", transport, env: {}, credentials: () => null, gitIdentity: () => ({ name: "bot[bot]", email: "1+bot[bot]@users.noreply.github.com" }) });
+    await p.start({ issue: 1, args: [], env: {} });
+    const env = transport.specs[0].env;
+    for (const role of ["AUTHOR", "COMMITTER"]) {
+      assert.equal(env[`GIT_${role}_NAME`], "bot[bot]");
+      assert.equal(env[`GIT_${role}_EMAIL`], "1+bot[bot]@users.noreply.github.com");
+    }
+    await p.start({ issue: 2, args: [], env: { GIT_AUTHOR_NAME: "lane", GIT_AUTHOR_EMAIL: "lane@example.invalid" } });
+    assert.equal(transport.specs[1].env.GIT_AUTHOR_EMAIL, "lane@example.invalid");
+    const none = remoteProvider({ batch, repo: "o/r", transport, env: {}, credentials: () => null, gitIdentity: () => ({ name: "", email: "" }) });
+    await none.start({ issue: 3, args: [], env: {} });
+    assert.equal("GIT_AUTHOR_EMAIL" in transport.specs[2].env, false);
+  });
+
   it("streams the lane log into the batch log, redacted; billable minutes on the handle and on the lane result", async () => {
     const { provider, finish, batch } = setup();
     const lanes = providerLanes({ provider: { ...provider, start: async (a) => { const h = await provider.start(a); setTimeout(() => finish(h, { terminalReason: "merged", pr: 2 }), 5); return h; } },
@@ -255,3 +272,59 @@ describe("gc reaps a remote sandbox left by a dead dispatcher (#4254)", () => {
     assert.equal(existsSync(led.path), false);
   });
 });
+
+describe("pool provider (#4546)", () => {
+  const setupPool = () => {
+    const dir = tmpDir("pool-cfg-");
+    const cfg = join(dir, "router.json");
+    writeFileSync(cfg, JSON.stringify({ listen: { host: "100.64.0.1", port: 8123 } }));
+    writeFileSync(join(dir, "forgedock.token"), "pool-token-789\n");
+    return { dir, cfg };
+  };
+  const launchOnce = async (makeProvider) => {
+    const calls = [];
+    const real = globalThis.fetch;
+    globalThis.fetch = async (url, init) => { calls.push({ url: String(url), init }); return { status: 201, ok: true, headers: { get: () => null }, text: async () => "{}" }; };
+    try { await makeProvider().start({ issue: 5, args: ["--lane", "main"], env: {}, secrets: [] }); } finally { globalThis.fetch = real; }
+    return calls[0];
+  };
+
+  it("defaults the endpoint and token to the local router and injects the cwd forge.yaml", async () => {
+    const { cfg } = setupPool();
+    const cwd = tmpDir("pool-cwd-");
+    writeFileSync(join(cwd, "forge.yaml"), "verify:\n  mode: ci\n");
+    const batch = openBatch(tmpDir("pool-b-"), "bt");
+    const make = () => providerByName("pool", { batch, repo: "o/r", cwd, exec: parseExecution({ mode: "remote", provider: "pool" }), env: {}, poolConfigPath: cfg });
+    assert.equal(make().name, "pool");
+    const c = await launchOnce(make);
+    assert.equal(c.url, "http://100.64.0.1:8123/sandboxes");
+    assert.equal(c.init.headers.authorization, "Bearer pool-token-789");
+    const spec = JSON.parse(c.init.body);
+    assert.equal(Buffer.from(spec.env.CS_FORGE_YAML_B64, "base64").toString(), "verify:\n  mode: ci\n");
+  });
+
+  it("an explicit endpoint wins; no forge.yaml adds no env; a missing router config is misconfigured", async () => {
+    const { dir } = setupPool();
+    const batch = openBatch(tmpDir("pool-b2-"), "bt");
+    const c = await launchOnce(() => providerByName("pool", { batch, repo: "o/r", cwd: dir, exec: parseExecution({ provider: "pool", endpoint: "https://pool.example/v1" }), env: {}, poolConfigPath: join(dir, "router.json") }));
+    assert.equal(c.url, "https://pool.example/v1/sandboxes");
+    assert.equal(JSON.parse(c.init.body).env.CS_FORGE_YAML_B64, undefined);
+    assert.throws(() => providerByName("pool", { batch, repo: "o/r", cwd: dir, exec: parseExecution({ provider: "pool" }), env: {}, poolConfigPath: join(dir, "none.json") }), (e) => e.code === "execution.provider.misconfigured");
+  });
+});
+
+describe("remote capacity (GET /status, #4540)", () => {
+  const mk = (res) => httpTransport({ endpoint: "https://pool.example/v1", fetchFn: async (url) => { if (res instanceof Error) throw res; assert.equal(url, "https://pool.example/v1/status"); return { status: res.status, ok: res.status < 400, text: async () => res.body ?? "", headers: { get: () => null } }; } });
+  it("free integer is reported; 404, malformed, negative and transport errors are unknown (null)", async () => {
+    assert.deepEqual(await mk({ status: 200, body: '{"free":3}' }).capacity(), { free: 3 });
+    assert.deepEqual(await mk({ status: 200, body: '{"free":0}' }).capacity(), { free: 0 });
+    for (const r of [{ status: 404 }, { status: 200, body: "nope" }, { status: 200, body: '{"free":"2"}' }, { status: 200, body: '{"free":-1}' }, new Error("down")]) assert.equal(await mk(r).capacity(), null);
+  });
+  it("remoteProvider.capacity delegates, and is null without a transport capability or on a throw", async () => {
+    const batch = openBatch(join(tmpDir("cap-"), "batches"), "bt");
+    const p = (transport) => remoteProvider({ batch, repo: "o/r", transport, env: {}, credentials: () => null });
+    assert.deepEqual(await p({ capacity: async () => ({ free: 1 }) }).capacity(), { free: 1 });
+    assert.equal(await p({}).capacity(), null);
+    assert.equal(await p({ capacity: async () => { throw new Error("x"); } }).capacity(), null);
+  });
+});

package/bin/lean/sandbox-remote.mjs

@@ -15,6 +15,7 @@
  * `httpTransport` is the one shipped transport: a small JSON protocol (docs/CONFIG.md `execution`) that a runner pool
  * or a session gateway fronts. Tests use an in-memory transport.
  */
+import { execFileSync } from "node:child_process";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { safeSegment } from "./ledger.mjs";
@@ -41,8 +42,9 @@ export function isActionsEndpoint(endpoint) {
 /**
  * Generic HTTP transport: POST {endpoint}/sandboxes (body = launch spec), GET /sandboxes/:id -> {state},
  * GET /sandboxes/:id/logs?cursor=N -> {text, cursor}, GET /sandboxes/:id/result -> lane result (404 = none yet),
- * GET /sandboxes/:id/usage -> {minutes}, DELETE /sandboxes/:id (404 = gone). `Authorization: Bearer <token>`.
+ * 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 `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 }) {
   const root = String(endpoint ?? "").replace(/\/+$/, "");
@@ -70,8 +72,19 @@ 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) } : 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 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.
+      try {
+        const r = await call("GET", "/status");
+        if (!r.ok) return null;
+        const ok = (v) => Number.isInteger(v) && v >= 0;
+        const { free, online, total } = r.data ?? {};
+        const out = { ...(ok(free) ? { free } : {}), ...(ok(online) ? { online } : {}), ...(ok(total) ? { total } : {}) };
+        return Object.keys(out).length ? out : null;
+      } catch { return null; }
+    },
   };
 }
 
@@ -79,7 +92,23 @@ export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fet
  * The remote provider. `settings` is parseExecution's output (image, cacheStore, tokenEnv, secrets); `env` is the
  * dispatcher's env (secret values for redaction on adopt); `credentials(name)` resolves a secret (env, then keychain).
  */
-export function remoteProvider({ batch, repo, settings = {}, transport, env = process.env, credentials = (name) => resolveCredential(name, { env }), now = () => Date.now() }) {
+/** The dispatching host's git identity (`git config user.name/email`), so sandbox commits carry the same author as local lanes. */
+export function hostGitIdentity() {
+  const get = (k) => { try { return execFileSync("git", ["config", k], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch { return ""; } };
+  return { name: get("user.name"), email: get("user.email") };
+}
+
+/** GIT_AUTHOR_* and GIT_COMMITTER_* for the sandbox, unless the lane env already sets them; empty when the host has no identity. */
+export function gitIdentityEnv(identity, laneEnv = {}) {
+  const out = {};
+  for (const role of ["AUTHOR", "COMMITTER"]) {
+    const n = laneEnv[`GIT_${role}_NAME`] || identity?.name, e = laneEnv[`GIT_${role}_EMAIL`] || identity?.email;
+    if (n && e) { out[`GIT_${role}_NAME`] = n; out[`GIT_${role}_EMAIL`] = e; }
+  }
+  return out;
+}
+
+export function remoteProvider({ batch, repo, settings = {}, name = "remote", transport, env = process.env, credentials = (name) => resolveCredential(name, { env }), now = () => Date.now(), gitIdentity = hostGitIdentity }) {
   if (!transport) throw new Error("remote provider needs a transport");
   const idFor = (issue) => `fdrsbx-${safeSegment(batch.id)}-${issue}`;
   const errs = new Map(); // sandbox id -> consecutive status errors
@@ -89,7 +118,7 @@ export function remoteProvider({ batch, repo, settings = {}, transport, env = pr
   if (settings.tokenEnv) remember(credentials(settings.tokenEnv));
   const minutesOf = async (h) => {
     let m = null;
-    try { const u = await transport.usage?.(h.id); if (u && Number.isFinite(Number(u.minutes))) m = Number(u.minutes); } catch { m = null; }
+    try { const u = await transport.usage?.(h.id); if (u && Number.isFinite(Number(u.minutes))) m = Number(u.minutes); if (typeof u?.agent === "string" && u.agent) h.agent = u.agent; } catch { m = null; }
     if (m === null && Number.isFinite(h.startedAt)) m = Math.round(((now() - h.startedAt) / 60000) * 10) / 10;
     if (m !== null) h.minutes = Math.max(h.minutes ?? 0, m);
   };
@@ -102,7 +131,7 @@ export function remoteProvider({ batch, repo, settings = {}, transport, env = pr
     } catch { /* the next poll retries */ }
   };
   return {
-    name: "remote",
+    name,
     idFor,
     async start({ issue, args = [], env: laneEnv = env, secrets = settings.secrets ?? [] }) {
       const id = idFor(issue);
@@ -115,12 +144,13 @@ export function remoteProvider({ batch, repo, settings = {}, transport, env = pr
         id, issue, batch: batch.id, image: settings.image ?? null,
         repo: { slug: repo, url: repo ? `https://github.com/${repo}.git` : null, ref: li >= 0 ? args[li + 1] ?? null : null },
         cache: settings.cacheStore ? { store: settings.cacheStore, key: safeSegment(String(repo ?? "repo")) } : null,
-        env: scopedEnv({ env: resolved, secrets, batchId: batch.id, repo }),
+        // The host's git identity: without it the lane image falls back to a placeholder author that fails DCO.
+        env: { ...gitIdentityEnv(gitIdentity(), laneEnv ?? {}), ...scopedEnv({ env: resolved, secrets, batchId: batch.id, repo }), ...(settings.forgeYaml ? { CS_FORGE_YAML_B64: Buffer.from(settings.forgeYaml).toString("base64") } : {}) }, // #4546: the dispatcher's forge.yaml (gitignored in the repo)
         command: ["forgedock", "run-issue", String(issue), ...args, "--result-file", resultFile], result_file: resultFile,
       };
       const startedAt = now();
       await transport.launch(spec);
-      return { provider: "remote", id, issue, startedAt, minutes: 0 };
+      return { provider: name, id, issue, startedAt, minutes: 0 };
     },
     async status(h) {
       let s;
@@ -134,6 +164,9 @@ export function remoteProvider({ batch, repo, settings = {}, transport, env = pr
       if (r) { await pullLogs(h); await minutesOf(h); }
       return r ?? null;
     },
+    async capacity() {
+      try { return (await transport.capacity?.()) ?? null; } catch { return null; }
+    },
     async teardown(h) {
       await minutesOf(h);
       try { return (await transport.destroy(h.id)) !== false; } catch { return false; }

package/bin/lean/seqlease.mjs

@@ -6,23 +6,70 @@
  * Each key is a one-slot `heavy.mjs` semaphore in its own registry dir (`schedDir()/seq-lease/<key>/heavy.json`):
  * file-locked, FIFO, dead holders dropped by pid. The heavy-step registry and its env caps are never touched.
  * Fail-open: a wait over `maxWaitS` (or an unreadable registry) proceeds without the lease; CI and base-sync stay the gate.
+ * #4526: number reservations. `reserve` picks the numbers of a renumber under a short host lock per (repo, base, dir) in
+ * its own registry (`schedDir()/seq-pick/<key>/`, never the lease above: its holder renumbers while it holds it) and
+ * records them in `reserved.json` until `unreserve` (run end), the holder's death or 24h, so concurrent lanes renumbering
+ * against the same base get distinct numbers without holding a lock across regenerate and push. Fail-open.
  */
 import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { acquireHeavy, openHeavy } from "./heavy.mjs";
-import { schedDir } from "./sched.mjs";
+import { pidAlive, schedDir } from "./sched.mjs";
 
 /** The lease key of one sequence dir of one lane branch of one repo. */
 export const sequenceLeaseKey = (repo, lane, dir) => createHash("sha1").update(`${repo}\0${lane}\0${dir}`).digest("hex").slice(0, 16);
 
 const NO_MEM = Object.freeze({ cores: () => 2, memAvailableMb: () => null });
+const RESERVE_TTL_MS = 24 * 3600 * 1000;
 
 /**
  * `acquire({repo, lane, dirs, issue, maxWaitS})` takes every dir's lease in sorted order (no lock-order deadlock).
  * @returns {{acquire: (e:object) => Promise<{waitMs:number, timedOut:boolean, release:Function}>}}
  */
-export function makeSequenceLeaseIo({ dir = join(schedDir(), "seq-lease"), open = openHeavy, acquire = acquireHeavy, pollMs } = {}) {
+export function makeSequenceLeaseIo({ dir = join(schedDir(), "seq-lease"), pickDir = join(schedDir(), "seq-pick"), open = openHeavy, acquire = acquireHeavy, pollMs, alive = pidAlive, now = () => Date.now() } = {}) {
+  const reservedDirs = new Map(); // `${repo}\0${lane}\0${issue}` -> dirs reserved in, for unreserve
+  /** Run `fn(entries) => entries'` on one key's reservations under its pick lock; returns what `fn` set as `out`. */
+  const locked = async ({ repo, lane, dir: d }, fn) => {
+    const kd = join(pickDir, sequenceLeaseKey(repo, lane, d)), file = join(kd, "reserved.json");
+    const h = open(kd, { cfg: { max: 1, max_wait_s: 60 }, env: {}, host: NO_MEM });
+    const g = await acquire(h, { phase: "sequence-pick" }, ...(pollMs ? [{ pollMs }] : []));
+    try {
+      let entries = [];
+      try { const o = JSON.parse(readFileSync(file, "utf8")); if (Array.isArray(o?.entries)) entries = o.entries; } catch { /* none yet */ }
+      const t = now();
+      entries = entries.filter((e) => Array.isArray(e?.numbers) && alive(e.pid) && t - Number(e.at ?? 0) < RESERVE_TTL_MS);
+      const r = fn(entries);
+      mkdirSync(kd, { recursive: true });
+      writeFileSync(`${file}.tmp`, `${JSON.stringify({ entries: r.entries }, null, 2)}\n`);
+      renameSync(`${file}.tmp`, file);
+      return r.out;
+    } finally { try { g.release(); } catch { /* fail-open */ } }
+  };
   return {
+    /**
+     * #4526: `count` consecutive numbers above max(floor, every other issue's live reservation) in (repo, lane, dir),
+     * recorded for `issue` (its earlier entries there replaced). @returns {Promise<{numbers:number[]}|null>} null on error.
+     */
+    async reserve({ repo, lane, dir: d, issue = null, floor = 0, count = 1, pid = process.pid } = {}) {
+      try {
+        const k = `${repo}\0${lane}\0${issue}`;
+        reservedDirs.set(k, new Set([...(reservedDirs.get(k) ?? []), d]));
+        return await locked({ repo, lane, dir: d }, (entries) => {
+          const others = entries.filter((e) => String(e.issue) !== String(issue));
+          let n = Math.max(Number(floor) || 0, ...others.flatMap((e) => e.numbers.map(Number)).filter(Number.isFinite));
+          const numbers = Array.from({ length: Math.max(0, count) }, () => ++n);
+          return { entries: [...others, { issue, pid, numbers, at: now() }], out: { numbers } };
+        });
+      } catch { return null; }
+    },
+    /** #4526: drop `issue`'s reservations in every dir of (repo, lane) it reserved in this process. Never throws. */
+    async unreserve({ repo, lane, issue = null } = {}) {
+      for (const d of [...(reservedDirs.get(`${repo}\0${lane}\0${issue}`) ?? [])]) {
+        try { await locked({ repo, lane, dir: d }, (entries) => ({ entries: entries.filter((e) => String(e.issue) !== String(issue)) })); } catch { /* fail-open */ }
+      }
+      reservedDirs.delete(`${repo}\0${lane}\0${issue}`);
+    },
     async acquire({ repo, lane, dirs = [], issue = null, maxWaitS = 1800 } = {}) {
       const held = [];
       let waitMs = 0, timedOut = false;

package/bin/lean/seqlease.test.mjs

@@ -39,6 +39,20 @@ describe("sequence lease (#4386)", () => {
     assert.equal(b.timedOut, true);
     b.release(); a.release();
   });
+
+  it("#4526: reserve gives each issue distinct numbers above the floor and other issues' live reservations; dead or unreserved entries free them", async () => {
+    const dead = new Set();
+    const io = makeSequenceLeaseIo({ dir: tmpDir("seqlease-"), pickDir: tmpDir("seqpick-"), pollMs: 20, alive: (pid) => !dead.has(pid) });
+    const k = { repo: "o/r", lane: "staging", dir: "db" };
+    const [a, b] = await Promise.all([io.reserve({ ...k, issue: 1, floor: 51, count: 1, pid: 101 }), io.reserve({ ...k, issue: 2, floor: 51, count: 2, pid: 102 })]);
+    assert.deepEqual([...a.numbers, ...b.numbers].sort((x, y) => x - y), [52, 53, 54]);
+    assert.deepEqual((await io.reserve({ ...k, issue: 1, floor: 51, count: 1, pid: 101 })).numbers, [Math.max(...b.numbers) + 1], "own entry replaced, others kept");
+    assert.deepEqual((await io.reserve({ ...k, dir: "docs/adr", issue: 3, floor: 51, pid: 103 })).numbers, [52], "other dir: own registry");
+    assert.deepEqual((await io.reserve({ ...k, lane: "main", issue: 3, floor: 51, pid: 103 })).numbers, [52], "other base: own registry");
+    dead.add(102);
+    await io.unreserve({ repo: "o/r", lane: "staging", issue: 1 });
+    assert.deepEqual((await io.reserve({ ...k, issue: 4, floor: 51, pid: 104 })).numbers, [52], "dead holder and unreserved issue dropped");
+  });
 });
 
 const env = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };

package/bin/lean/sequence.mjs

@@ -11,6 +11,9 @@
  * #4343: a leading calendar date (YYYY-MM-DD, YYYYMMDD) is not a number, and a directory only counts when it holds a
  * series on the base: a migration journal (`<dir>/meta/_journal.json`, `<dir>/_journal.json`), or >=2 distinct numbers
  * of the lane file's width that fill at least half of their min..max range (sparse issue-numbered docs are no series).
+ * #4526: renumberLane takes its numbers from a host reservation (`reserve`, seqlease.mjs) so concurrent lanes get distinct
+ * ones; verifyRenumber accepts a first-line header that only swaps the file's own tag (`headerOnlyChange`); a hand-written
+ * migration the generator writes nothing for gets the generator's `--custom` snapshot and keeps the lane's SQL.
  */
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -123,6 +126,21 @@ export function numberOnlyChange(was, now, from, to) {
   return new RegExp(`^${parts.map((p, i) => (i % 2 ? alt(p) : esc(p))).join("")}$`).test(String(now));
 }
 
+/**
+ * #4526: everything after the first line is byte-identical, and the first line of `now` is that of `was` with the old
+ * stem (`fromPath` without extension) mapped to the new one, then the old number (padded or bare, not next to another
+ * digit) to the new number: a migration's `-- Migration 0067_x` or an ADR's `# 0029. Title` header following a renumber.
+ */
+export function headerOnlyChange(was, now, fromPath, toPath) {
+  const from = numOf(fromPath), to = numOf(toPath);
+  if (!from || !to) return false;
+  const split = (t) => { const s = String(t), i = s.indexOf("\n"); return i < 0 ? [s, ""] : [s.slice(0, i), s.slice(i)]; };
+  const [h1, r1] = split(was), [h2, r2] = split(now);
+  if (r1 !== r2) return false;
+  const mapped = h1.replaceAll(stemOf(fromPath), stemOf(toPath)).replace(new RegExp(`(?<!\\d)0*${Number(from)}(?!\\d)`, "g"), (tok) => (tok.length >= to.length ? to : String(Number(to))));
+  return mapped === h2;
+}
+
 /** Lane-added numbered files with their blobs, recorded before a renumber so verifyRenumber can prove the SQL kept. */
 export const snapshotLane = ({ git, base }) => laneNumbered(git, base).catch(() => []);
 
@@ -173,7 +191,7 @@ export async function verifyRenumber({ git, base, before = [], moves = null }) {
       for (const f of peers) {
         if (kept || f.path === b.path) continue;
         const text = await g(["cat-file", "-p", f.blob]);
-        kept = numberOnlyChange(was, text, numOf(b.path), numOf(f.path)) || (rest(f.path) === rest(b.path) && text === mapped);
+        kept = numberOnlyChange(was, text, numOf(b.path), numOf(f.path)) || (rest(f.path) === rest(b.path) && text === mapped) || headerOnlyChange(was, text, b.path, f.path);
       }
       if (!kept) problems.push(`${b.path}: content changed or file gone after renumbering (keep it byte-identical, rename only)`);
     }
@@ -269,7 +287,8 @@ const writeJson = (p, o) => writeFileSync(p, `${JSON.stringify(o, null, 2)}\n`);
  * where it started. Never throws.
  * @returns {Promise<{ok:true, moves:Array<{from,to}>, commit:string|null}|{unsupported:string}>}
  */
-export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerate = null, run = null, uuid = randomUUID }) {
+export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerate = null, regenerateCustom = null, run = null, uuid = randomUUID, reserve = null }) {
+  const custom = regenerateCustom ?? (regenerate ? `${regenerate} --custom` : null);
   const g = out(git);
   const start = (await g(["rev-parse", "HEAD"])).trim();
   const written = [];
@@ -286,6 +305,16 @@ export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerat
     if (!collisions.length) return { ok: true, moves: [], commit: null };
     const odd = collisions.find((c) => !SUPPORTED_RE.test(c.lane));
     if (odd) return { unsupported: `${odd.lane}: no deterministic renumber for .${basename(odd.lane).split(".").pop()} migrations` };
+    // #4526: numbers above every other live lane's host reservation, not only above the base (fail-open: base-derived).
+    if (reserve) {
+      for (const dir of [...new Set(collisions.map((c) => c.dir))].sort()) {
+        const cs = collisions.filter((c) => c.dir === dir), width = cs[0].next.length;
+        let got = null;
+        try { got = await reserve({ dir, floor: Number(cs[0].next) - 1, count: cs.length }); } catch { /* fail-open */ }
+        const nums = Array.isArray(got?.numbers) ? got.numbers.map(Number) : [];
+        if (nums.length === cs.length && nums.every(Number.isInteger)) cs.forEach((c, i) => { c.next = String(nums[i]).padStart(width, "0"); });
+      }
+    }
     const moves = collisions.map((c) => ({ from: c.lane, to: posix.join(c.dir, c.next + basename(c.lane).slice(c.number.length)), dir: c.dir, oldNum: c.number, newNum: c.next }));
     // Plan the journals and snapshots before touching anything, so an unsupported migration leaves the branch as it was.
     const baseList = lines(await g(["-c", "core.quotepath=off", "ls-tree", "-r", "--name-only", base]));
@@ -296,12 +325,14 @@ export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerat
       if (!jp) continue;
       const meta = dirname(jp), mine = moves.filter((m) => m.dir === dir && /\.sql$/i.test(m.from));
       const snaps = [];
+      let chained = false; // #4526: after a schema-changing move, a data-only one's predecessor is not the base tip
       for (const m of mine) {
         const laneSnap = await json(g, `${lane}:${posix.join(meta, `${m.oldNum}_snapshot.json`)}`);
         if (!laneSnap) continue;
         const laneMeta = lines(await g(["-c", "core.quotepath=off", "ls-tree", "--name-only", lane, `${meta}/`])).filter((p) => SNAPSHOT_RE.test(p) && Number(numOf(p)) < Number(m.oldNum));
         const pred = laneMeta.sort((a, b) => Number(numOf(a)) - Number(numOf(b))).at(-1);
-        const dataOnly = Boolean(pred) && strip(await json(g, `${lane}:${pred}`)) === strip(laneSnap);
+        const dataOnly = !chained && Boolean(pred) && strip(await json(g, `${lane}:${pred}`)) === strip(laneSnap);
+        if (!dataOnly) chained = true;
         if (!dataOnly && !regenerate) return { unsupported: `schema-changing migration ${m.from} needs lean.sequence.regenerate (its snapshot cannot be cloned)` };
         if (!dataOnly) needRegen = true;
         snaps.push({ m, dataOnly });
@@ -339,7 +370,8 @@ export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerat
       const tags = new Set(baseEntries.map((e) => e?.tag));
       let idx = Math.max(-1, ...baseEntries.map((e) => Number(e?.idx)).filter(Number.isFinite));
       const add = (Array.isArray(lj.entries) ? lj.entries : []).filter((e) => !tags.has(e?.tag)).map((e) => ({ ...e, idx: ++idx, tag: stem.get(e.tag) ?? e.tag }));
-      writeJson(join(cwd, p.jp), { ...bj, entries: [...baseEntries, ...add] });
+      p.journal = { ...bj, entries: [...baseEntries, ...add] };
+      writeJson(join(cwd, p.jp), p.journal);
       touched.add(p.jp);
       const baseSnaps = baseList.filter((x) => dirname(x) === p.meta && SNAPSHOT_RE.test(x)).sort((a, b) => Number(numOf(a)) - Number(numOf(b)));
       let tip = baseSnaps.length ? await json(g, `${base}:${baseSnaps.at(-1)}`) : null;
@@ -360,11 +392,27 @@ export async function renumberLane({ git, base, cwd, laneRef = "HEAD", regenerat
     }
     if (needRegen) {
       try { await (run ?? defaultRun)(regenerate, { cwd }); } catch (e) { return await fail(`lean.sequence.regenerate failed: ${String(e?.stderr || e?.message || e).trim().split("\n")[0]}`); }
+      const exists = (p) => { try { readFileSync(join(cwd, p)); return true; } catch { return false; } };
       for (const p of plans) {
         touched.add(p.meta);
-        for (const { m, dataOnly } of p.snaps) {
+        // #4526: a hand-written migration (no schema diff) gets nothing from the regular run: the generator's --custom
+        // writes an empty migration and its snapshot at that number (its SQL and later ones withheld), then the lane's
+        // SQL and the planned journal come back.
+        for (const { m, dataOnly } of [...p.snaps].sort((a, b) => Number(a.m.newNum) - Number(b.m.newNum))) {
           const want = posix.join(p.meta, `${m.newNum}_snapshot.json`);
-          if (!dataOnly) { try { readFileSync(join(cwd, want)); } catch { return await fail(`lean.sequence.regenerate did not write ${want}`); } }
+          if (dataOnly || exists(want)) continue;
+          if (!custom) return await fail(`lean.sequence.regenerate did not write ${want}`);
+          const held = moves.filter((w) => w.dir === p.dir && /\.sql$/i.test(w.to) && Number(w.newNum) >= Number(m.newNum));
+          const heldTags = new Set(held.map((w) => stemOf(w.to)));
+          for (const w of held) rmSync(join(cwd, w.to), { force: true });
+          writeJson(join(cwd, p.jp), { ...p.journal, entries: p.journal.entries.filter((e) => !heldTags.has(e?.tag)) });
+          try { await (run ?? defaultRun)(custom, { cwd }); } catch (e) { return await fail(`lean.sequence.regenerate --custom failed: ${String(e?.stderr || e?.message || e).trim().split("\n")[0]}`); }
+          for (const f of lines(await g(["-c", "core.quotepath=off", "ls-files", "--others", "--exclude-standard", "--", `${p.dir}/`]))) {
+            if (dirname(f) === p.dir && /\.sql$/i.test(f) && numOf(f) === m.newNum && f !== m.to) rmSync(join(cwd, f), { force: true });
+          }
+          for (const w of held) writeFileSync(join(cwd, w.to), await g(["cat-file", "blob", `${lane}:${w.from}`]));
+          writeJson(join(cwd, p.jp), p.journal);
+          if (!exists(want)) return await fail(`lean.sequence.regenerate did not write ${want}`);
         }
       }
     }

package/bin/lean/sequence.test.mjs

@@ -8,7 +8,8 @@ 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, renumberLane, resolveSequenceConflicts } from "./sequence.mjs";
+import { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber, numberOnlyChange, headerOnlyChange, renumberLane, resolveSequenceConflicts } from "./sequence.mjs";
+import { makeSequenceLeaseIo } from "./seqlease.mjs";
 import { sequencePrompt, sequenceSyncNote } 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" } });
@@ -301,6 +302,87 @@ describe("deterministic renumber (#4386)", () => {
     // both add the same numbered name in a directory without a series
     await conflict({ "src/a.ts": "1\n" }, { "src/500_error.html": "LANE\n" }, { "src/500_error.html": "BASE\n" }, "src/500_error.html");
   });
+
+  it("#4526: two lanes renumbering at once against the same base get distinct numbers (host reservation), and free them at the end", async () => {
+    const io = makeSequenceLeaseIo({ dir: tmpDir("seqlease-"), pickDir: tmpDir("seqpick-"), pollMs: 20 });
+    const reserveFor = (issue) => (x) => io.reserve({ repo: "o/r", lane: "main", issue, ...x });
+    const lanes = [drizzle(), drizzle()];
+    const rs = await Promise.all(lanes.map((d, i) => renumberLane({ git: gitIn(d), base: "main", cwd: d, uuid: () => `u${i}`, reserve: reserveFor(i + 1) })));
+    for (const r of rs) assert.ok(r.ok, r.unsupported);
+    assert.deepEqual(rs.map((r) => r.moves[0].to).sort(), ["db/0052_nclt.sql", "db/0053_nclt.sql"]);
+    for (const d of lanes) {
+      assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+      assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+    }
+    await io.unreserve({ repo: "o/r", lane: "main", issue: 1 });
+    await io.unreserve({ repo: "o/r", lane: "main", issue: 2 });
+    const d = drizzle();
+    assert.deepEqual((await renumberLane({ git: gitIn(d), base: "main", cwd: d, reserve: reserveFor(3) })).moves, [{ from: "db/0049_nclt.sql", to: "db/0052_nclt.sql" }]);
+    const failing = drizzle(); // a broken reservation keeps the base-derived number (fail-open)
+    assert.deepEqual((await renumberLane({ git: gitIn(failing), base: "main", cwd: failing, reserve: async () => { throw new Error("x"); } })).moves[0].to, "db/0052_nclt.sql");
+  });
+
+  it("#4526: a renumber that changes only the header line's tag passes verifyRenumber; any other change does not", async () => {
+    const lane = (header, body = "INSERT INTO t VALUES (1);\n") => {
+      const d = repo({ "db/0047_a.sql": "a;\n", "db/0048_init.sql": "b;\n" }, { "db/0049_x.sql": "-- Migration 0049_x\nINSERT INTO t VALUES (1);\n" }, { "db/0049_a.sql": "c;\n" });
+      return { d, header, body };
+    };
+    for (const [header, body, ok] of [["-- Migration 0050_brave_hulk", undefined, true], ["-- Migration 0050_brave_hulk (edited)", undefined, false], ["-- Migration 0050_brave_hulk", "INSERT INTO t VALUES (2);\n", false]]) {
+      const { d } = lane(header);
+      const before = await snapshotLane({ git: gitIn(d), base: "main" });
+      sh(d, "merge", "--no-edit", "main");
+      sh(d, "mv", "db/0049_x.sql", "db/0050_brave_hulk.sql");
+      put(d, { "db/0050_brave_hulk.sql": `${header}\n${body ?? "INSERT INTO t VALUES (1);\n"}` });
+      commit(d, "renumber");
+      const v = await verifyRenumber({ git: gitIn(d), base: "main", before });
+      assert.equal(v.ok, ok, `${header} / ${body}: ${v.problems.join("; ")}`);
+      if (!ok) assert.match(v.problems.join("\n"), /db\/0049_x\.sql: content changed/);
+    }
+    assert.equal(headerOnlyChange("# 0029. Title\nbody\n", "# 0030. Title\nbody\n", "docs/adr/0029-title.md", "docs/adr/0030-title.md"), true);
+    assert.equal(headerOnlyChange("# 29. Title\nbody\n", "# 30. Title\nbody\n", "docs/adr/0029-title.md", "docs/adr/0030-title.md"), true);
+    assert.equal(headerOnlyChange("-- 0067_x\nSELECT 1;\n", "-- 0068_x\nSELECT 1;\n", "db/0067_x.sql", "db/0068_x.sql"), true);
+    assert.equal(headerOnlyChange("-- 0067_x\nSELECT 1;\n", "-- 0068_x\nSELECT 2;\n", "db/0067_x.sql", "db/0068_x.sql"), false);
+    assert.equal(headerOnlyChange("-- 0067_x 10067\nSELECT 1;\n", "-- 0068_x 10068\nSELECT 1;\n", "db/0067_x.sql", "db/0068_x.sql"), false, "another number containing the tag is not the tag");
+  });
+
+  it("#4526: a hand-written migration with no schema diff after a schema-changing one gets the generator's --custom snapshot and keeps its SQL byte-for-byte", async () => {
+    const FN_SQL = "-- hand-written: no schema diff\nCREATE FUNCTION f() RETURNS int AS $$ SELECT 1 $$ LANGUAGE sql;\n";
+    const d = repo(
+      { "db/0048_init.sql": "CREATE TABLE t (id int);\n", "db/meta/_journal.json": journal("0048_init"), "db/meta/0048_snapshot.json": snap("s48", "s47") },
+      { "db/0049_s.sql": "CREATE TABLE s (id int);\n", "db/0050_fn.sql": FN_SQL, "db/meta/_journal.json": journal("0048_init", "0049_s", "0050_fn"),
+        "db/meta/0049_snapshot.json": snap("lane49", "s48", { t: 1, s: 1 }), "db/meta/0050_snapshot.json": snap("lane50", "lane49", { t: 1, s: 1 }) },
+      {
+        "db/0049_a.sql": "a;\n", "db/0050_b.sql": "b;\n", "db/0051_c.sql": "CREATE TABLE u (id int);\n",
+        "db/meta/_journal.json": journal("0048_init", "0049_a", "0050_b", "0051_c"),
+        "db/meta/0049_snapshot.json": snap("s49", "s48"), "db/meta/0050_snapshot.json": snap("s50", "s49"), "db/meta/0051_snapshot.json": snap("s51", "s50", { t: 1, u: 1 }),
+      },
+    );
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    const calls = [];
+    /** A drizzle-kit stand-in: the regular run writes only the schema-changing snapshot; --custom adds an empty migration at the journal's next number. */
+    const run = async (cmd, { cwd }) => {
+      calls.push(cmd);
+      if (!cmd.endsWith("--custom")) { writeFileSync(join(cwd, "db/meta/0052_snapshot.json"), snap("gen52", "s51", { t: 1, u: 1, s: 1 })); return; }
+      assert.ok(!existsSync(join(cwd, "db/0053_fn.sql")), "the lane's SQL is withheld while the generator runs");
+      const j = JSON.parse(readFileSync(join(cwd, "db/meta/_journal.json"), "utf8"));
+      const n = String(Number(j.entries.at(-1).tag.slice(0, 4)) + 1).padStart(4, "0");
+      writeFileSync(join(cwd, `db/${n}_wise_owl.sql`), "-- Custom SQL migration file, put your code below! --\n");
+      writeFileSync(join(cwd, `db/meta/${n}_snapshot.json`), snap("custom", "gen52", { t: 1, u: 1, s: 1 }));
+      j.entries.push({ idx: j.entries.length, tag: `${n}_wise_owl`, when: 9 });
+      writeFileSync(join(cwd, "db/meta/_journal.json"), JSON.stringify(j));
+    };
+    const r = await renumberLane({ git: gitIn(d), base: "main", cwd: d, regenerate: "pnpm db:generate", run });
+    assert.ok(r.ok, r.unsupported);
+    assert.deepEqual(r.moves, [{ from: "db/0049_s.sql", to: "db/0052_s.sql" }, { from: "db/0050_fn.sql", to: "db/0053_fn.sql" }]);
+    assert.deepEqual(calls, ["pnpm db:generate", "pnpm db:generate --custom"]);
+    assert.equal(show(d, "db/0053_fn.sql"), FN_SQL, "hand-written SQL byte-identical");
+    assert.ok(!existsSync(join(d, "db/0053_wise_owl.sql")), "the generator's empty migration is dropped");
+    assert.equal(JSON.parse(show(d, "db/meta/0053_snapshot.json")).id, "custom");
+    assert.deepEqual(JSON.parse(show(d, "db/meta/_journal.json")).entries.map((e) => e.tag), ["0048_init", "0049_a", "0050_b", "0051_c", "0052_s", "0053_fn"]);
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+    assert.equal(sh(d, "status", "--porcelain").trim(), "");
+    assert.deepEqual(await verifyRenumber({ git: gitIn(d), base: "main", before, moves: r.moves }), { ok: true, problems: [] });
+  });
 });
 
 describe("sequence-numbered documents: two siblings each add an ADR (#4385)", () => {