forgedock 1.32.0 → 1.33.0

package/bin/lean/lean.test.mjs

@@ -19,8 +19,8 @@ import { mapRecord } from "../engine/telemetry-seam.mjs";
 import { readLog as readRepoLog } from "../engine/runlog.mjs";
 // #4432: the run log is keyed by repo + issue; every lane in this file runs in repo o/r.
 const readLog = (dir, issue, repo = "o/r") => readRepoLog(dir, issue, { repo });
-import { makeRunTmp, wrapLaneLimits, systemdRunAvailable, makeLeanRunner, requiredChecksFor, procsInDir, makeLeanIo } from "./effects.mjs";
-import { retrying, PUSH_TRANSIENT_RE } from "./retry.mjs";
+import { makeRunTmp, wrapLaneLimits, systemdRunAvailable, makeLeanRunner, requiredChecksFor, procsInDir, makeLeanIo, makeGhCache } from "./effects.mjs";
+import { retrying, ghCacheRetry, PUSH_TRANSIENT_RE } from "./retry.mjs";
 import { checkAdmission, hostParallelism } from "./admission.mjs";
 import { OUTCOME_CODES, classifyNeedsHuman } from "../engine/outcome-codes.mjs";
 import * as refactorMod from "./refactor.mjs";
@@ -73,8 +73,10 @@ function world(o = {}) {
   w.writeStages = writeStages;
   w.io = {
     now: () => w.clock, sleep: async (ms) => { w.clock += ms; },
-    gh: async (a) => {
+    gh: async (a, opts) => {
       const k = a.slice(0, 2).join(" ");
+      if (opts?.env) (w.ghEnvs ??= []).push(opts.env);
+      if (k === "pr view" && a.at(-1) === "state" && a.at(-2) === "--json") return JSON.stringify({ state: o.prState ?? "OPEN" });
       if (a[0] === "api" && a.includes("PATCH")) { w.patches.push(a); return "{}"; }
       if (a[0] === "api") return a.some((x) => /\/comments$/.test(x)) ? (w.issueComments ?? []).map((c) => JSON.stringify(c)).join("\n") : "";
       if (k === "pr list") return JSON.stringify(w.prList);
@@ -646,6 +648,13 @@ describe("core work-on", () => {
     };
     assert.equal(await code(world({ result: { status: "blocked", summary: "need creds", block: { kind: "human", why: "credentials" } } })), "builder.blocked");
     assert.equal(await code(world({ result: { status: "blocked", summary: "need creds" } })), "builder.block_untyped");
+    // #4542: a remote lane that names only a declared host capability is the recoverable env code; anything else stays human.
+    const rb = (summary, extra) => code(world({ result: { status: "blocked", summary, block: { kind: "human", why: "credentials" } } }), extra);
+    const remote = { placement: { where: "remote", reason: "mode remote" }, hostCaps: { hostCapabilities: ["sops"] } };
+    assert.equal(await rb("this lane has no sops/age key", remote), "env.capability_remote");
+    assert.equal(await rb("owner must create a third-party account", remote), "builder.blocked");
+    assert.equal(await rb("this lane has no sops/age key", { ...remote, hostCaps: undefined }), "builder.blocked");
+    assert.equal(await rb("this lane has no sops/age key", { ...remote, placement: { where: "local", reason: "x" } }), "builder.blocked");
     assert.equal(await code(world({ changed: [] })), "builder.no_commit");
     assert.equal(await code(world({ waits: [{ rc: 1, text: "lint failed" }] }), { mergeWait: "all" }), "ci.red");
   });
@@ -1614,6 +1623,20 @@ describe("hotspot prevention (forge#4195): plan facts, build rule, unexempted gr
     assert.ok(approxTokens(builderImplementPrompt() + hotspotBuildRule(facts([]))) <= 1500);
   });
 
+  it("#4519 generated_paths: both prompts name the globs (even with the gate off), and an amendment adding one blocks", async () => {
+    const G = ["web/public/openapi*.json"];
+    for (const f of [facts([], { generated_paths: G }), facts([HOT], { enabled: false, generated_paths: G })]) {
+      assert.match(hotspotPlanNote(f), /Generated paths \(forge\.yaml maintenance\.generated_paths, owned by the repo's generator\): web\/public\/openapi\*\.json\. Never list or amend them in/);
+      assert.match(hotspotBuildRule(f), /Generated paths .*web\/public\/openapi\*\.json/);
+    }
+    assert.equal(hotspotPlanNote(facts([], { generated_paths: [] })), "", "no generated_paths: unchanged");
+    const w = hworld(facts([], { generated_paths: G }), [facts([])], { amendments: [{ kind: "add-deliverable", path: "web/public/openapi.json", why: "sync the spec" }] });
+    const r = await run(w);
+    assert.equal(r.code, "conformance.unimplemented"); assert.equal(w.merges.length, 0);
+    assert.match(builders(w)[0][4], /Generated paths .*openapi/);
+    assert.match(nh(w), /add-deliverable web\/public\/openapi\.json: generated path/);
+  });
+
   it("the plan prompt carries the facts, the implement prompt the configured rule; growth within the limit merges; no extra runner calls", async () => {
     const w = hworld(facts([HOT, COLD], { file_lines: 2000, growth_lines: 150 }), [facts([SMALL])]);
     assert.equal((await run(w)).terminalReason, "merged");
@@ -2146,6 +2169,17 @@ describe("orchestrate", () => {
     assert.deepEqual(parseDeps("This is blocked by #2 and depends on #4\nsee **Depends on**: #5", 1), []);
   });
 
+  it("#4506 parseDeps reads every #N to the end of a declaration line", () => {
+    assert.deepEqual(parseDeps("Depends on #36648 (action results must reach …) and #36649 (the included action budget …)", 1), [36648, 36649]);
+    assert.deepEqual(parseDeps("Depends on #36651 (executor test harness) and #36648.", 1), [36651, 36648]);
+    assert.deepEqual(parseDeps("**Depends on** #2, #3 and #4", 1), [2, 3, 4]);
+    assert.deepEqual(parseDeps("__Depends on__: #5 (x) and #6", 1), [5, 6]);
+    assert.deepEqual(parseDeps("**Blocked by:** #7 (why) & #8", 1), [7, 8]);
+    assert.deepEqual(parseDeps("- depends on: #9 (a), #10", 1), [9, 10]);
+    assert.deepEqual(parseDeps("Depends on #11 and other/repo#12", 1), [11]);
+    assert.deepEqual(parseDeps("This is blocked by #2 and depends on #4", 1), []);
+  });
+
   it("runs at most K at once", async () => {
     const h = harness({});
     const rows = await orchestrate({ issues: [1, 2, 3, 4, 5, 6], parallel: 2, ...h });
@@ -3222,6 +3256,78 @@ describe("batch robustness (#4112-#4115)", () => {
     assert.ok(w.comments.some((c) => c.includes("FORGE:BASE_SYNC")));
   });
 
+  // ---- #4507 ----
+  const CORRUPT = "invalid character '{' looking for beginning of object key string";
+  it("#4507 a gh JSON parse error at merge (corrupt gh cache) is retried and ends merged", async () => {
+    const w = world({ mergeErrors: [CORRUPT] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.mergeAttempts, 2);
+    assert.equal(w.merges.length, 1);
+  });
+
+  it("#4507 a merge error on a PR that is already MERGED records merged, not engine-error", async () => {
+    const w = world({ mergeErrors: ["GraphQL: validation failed (422)"], prState: "MERGED" });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.mergeAttempts, 1);
+    assert.equal(w.closed.length, 1);
+    assert.ok(traj(w)[0].includes("is MERGED: recorded merged"));
+  });
+
+  it("#4507 a persistent gh parse error at merge ends deferred merge.transient, never engine-error", async () => {
+    const w = world({ mergeErrors: Array(40).fill(CORRUPT) });
+    const r = await run(w, { maxMergeRetries: 2 });
+    assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "merge.transient");
+    assert.equal(w.mergeAttempts, 6, "each merge attempt is retried once with a fresh cache");
+  });
+
+  it("#4507 with io.ghCache every engine gh call carries the run's own XDG_CACHE_HOME", async () => {
+    const w = world();
+    w.io.runTmp = { prune: async () => {}, make: async (_i, id) => `/rt/${id}`, remove: async () => true };
+    let made = null, disposed = 0;
+    w.io.ghCache = (root) => { made = root; return { env: () => ({ XDG_CACHE_HOME: `${root}/gh-cache` }), reset() {}, dispose() { disposed++; } }; };
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.match(made, /^\/rt\//);
+    assert.ok(w.ghEnvs.length > 0 && w.ghEnvs.every((e) => e.XDG_CACHE_HOME === `${made}/gh-cache`));
+    assert.equal(disposed, 1);
+  });
+
+  it("#4507 ghCacheRetry retries exactly once on a parse error and rethrows other errors untouched", async () => {
+    let n = 0, resets = 0;
+    const cache = { env: () => ({ XDG_CACHE_HOME: `/c${resets}` }), reset: () => { resets++; } };
+    const seen = [];
+    assert.equal(await ghCacheRetry(async (env) => { seen.push(env.XDG_CACHE_HOME); if (n++ === 0) throw new Error(CORRUPT); return "ok"; }, cache), "ok");
+    assert.deepEqual(seen, ["/c0", "/c1"]); assert.equal(resets, 1);
+    n = 0;
+    await assert.rejects(ghCacheRetry(async () => { n++; throw new Error(CORRUPT); }, null), /invalid character/);
+    assert.equal(n, 2);
+    n = 0;
+    const other = new Error("HTTP 404: Not Found");
+    await assert.rejects(ghCacheRetry(async () => { n++; throw other; }, cache), (e) => e === other);
+    assert.equal(n, 1);
+  });
+
+  it("#4507 makeGhCache: a per-root cache dir, reset swaps in a fresh dir, the no-root fallback is disposed", () => {
+    const root = tmpDir("ghcache-");
+    const c = makeGhCache({ root });
+    const first = c.env().XDG_CACHE_HOME;
+    assert.equal(first, join(root, "gh-cache")); assert.ok(existsSync(first));
+    c.reset();
+    const second = c.env().XDG_CACHE_HOME;
+    assert.notEqual(second, first); assert.ok(existsSync(second)); assert.ok(!existsSync(first));
+    const tmp = tmpDir("ghcache-tmp-");
+    const f = makeGhCache({ tmp });
+    assert.equal(f.env(), undefined);
+    f.reset();
+    const fb = f.env().XDG_CACHE_HOME;
+    assert.ok(fb.startsWith(join(tmp, "forge-gh-cache-")) && existsSync(fb));
+    f.dispose();
+    assert.ok(!existsSync(fb));
+    c.dispose();
+    assert.ok(!existsSync(second)); assert.equal(c.env(), undefined, "no dir is re-created after the run tears down");
+  });
+
   // ---- #4114 ----
   it("#4114 a push failing once with 'remote unpack failed' then succeeding completes the run", async () => {
     const w = world({ pushErrors: ["error: remote unpack failed: unable to create temporary object directory"] });
@@ -3405,6 +3511,28 @@ describe("batch robustness (#4112-#4115)", () => {
     }
   });
 
+  it("#4518 a builder paused for longer than maxMs still gets its full ceiling of active time", async () => {
+    const { runCliBackendAsync } = await import("../runner.mjs");
+    const { d, bin } = await fakeCli("paused", `${TOOL}\nsleep 1\n${RESULT}`);
+    const control = {};
+    const call = runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin, logger: { log() {} }, stream: true, idleMs: 0, maxMs: 1200, control });
+    await new Promise((res) => setTimeout(res, 100)); control.pause();
+    await new Promise((res) => setTimeout(res, 2200)); control.resume();
+    assert.equal((await call).text, "all done");
+  });
+
+  it("#4518 external SIGTERM (status 143) restarts the builder once, then ends deferred cli.host_killed, never engine-error", async () => {
+    const kill = () => Object.assign(new Error("claude CLI exited with status 143. No output was captured"), { code: "CLI_BACKEND_FAILED", status: 143, signal: null });
+    const w = world({ dirty: true }); const orig = w.io.runner; let n = 0;
+    w.io.runner = async (c) => { if (c.role === "builder" && n++ === 1) throw kill(); return orig(c); };
+    assert.equal((await run(w)).terminalReason, "merged");
+    const w2 = world({ dirty: true });
+    w2.io.runner = async (c) => { if (c.role === "builder") throw kill(); return { text: "" }; };
+    const r = await run(w2);
+    assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "cli.host_killed");
+    assert.equal(w2.edits.some((e) => e.includes("needs-human")), false);
+  });
+
   // ---- #4405 ----
   const HEAVY_CHILD = (d) => `printf '#!/bin/sh\\nsleep 1.5\\n' > ${d}/vitest; chmod +x ${d}/vitest`;
   it("#4405 a silent session with a running heavy-step child is not idle-killed within the extended window", async () => {
@@ -3788,6 +3916,17 @@ describe("verify-by-CI (#4167): ci mode runs the heavy checks on CI and feeds fa
     assert.equal(r.terminalReason, "needs-human"); assert.equal(w.merges.length, 0);
   });
 
+  it("#4527 base-sync re-review FAIL: the fix round's head is CI-verified before the retry review, which accepts validates left to CI and notes them", async () => {
+    const CONFLICTING = { mergeable: "CONFLICTING", mergeStateStatus: "DIRTY" }, OKSTATE = { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" };
+    const w = withCi(world({ validation: ciValidation, prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), bad("src/foo.js:4 lost base change"), ok()] }));
+    const r = await run(w, { verify: CI });
+    assert.equal(r.terminalReason, "merged", r.reason);
+    assert.equal(reviewers(w).length, 3);
+    assert.equal(new Set(w.ci.runs.map((x) => x.headSha)).size, w.ci.runs.length, "every reviewed head was verified once");
+    assert.equal(w.ci.runs[0].headSha, w.head, "the retry head is CI-verified");
+    assert.match(traj(w)[0], /Validate V1 verified by CI at [0-9a-f]{0,12}/);
+  });
+
   it("docs-only lane: no push for CI, no dispatch; the decision is recorded", async () => {
     const w = withCi(world({ changed: ["README.md", "docs/guide.md"], validation: ciValidation }));
     const r = await run(w, { verify: CI, conformance: "shadow" });
@@ -5021,6 +5160,20 @@ describe("enumerating tests + sequence numbers at hand-off (#4322)", () => {
       assert.match(traj(w).at(-1), /renumbered deterministically \(no builder\): db\/0007_usage\.sql → db\/0008_usage\.sql/);
     });
 
+    it("#4526: the renumber gets a reserve hook bound to (repo, lane, issue), and the run's reservations are dropped at finish", async () => {
+      const w = dworld({ seq: [COLL, []] }), reserved = [], unreserved = [];
+      w.io.sequenceLease.reserve = async (x) => { reserved.push(x); return { numbers: [9] }; };
+      w.io.sequenceLease.unreserve = async (x) => { unreserved.push(x); };
+      assert.equal((await run(w)).terminalReason, "merged");
+      assert.equal(typeof w.renumbers[0].reserve, "function");
+      assert.deepEqual(await w.renumbers[0].reserve({ dir: "db", floor: 7, count: 1 }), { numbers: [9] });
+      assert.equal(reserved[0].dir, "db");
+      assert.equal(reserved[0].floor, 7);
+      assert.ok(reserved[0].repo && reserved[0].lane && reserved[0].issue, JSON.stringify(reserved[0]));
+      assert.equal(unreserved.length, 1);
+      assert.deepEqual(unreserved[0], { repo: reserved[0].repo, lane: reserved[0].lane, issue: reserved[0].issue });
+    });
+
     it("base-sync with conflicts only in sequence files: base side taken and renumbered by the engine, zero builder sessions, zero re-reviews", async () => {
       const w = dworld({ seq: [[], COLL, []], prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], conflictFiles: ["db/meta/_journal.json", "db/meta/0007_snapshot.json"] });
       assert.equal((await run(w)).terminalReason, "merged");
@@ -5315,10 +5468,10 @@ describe("#4392: implement turn budget", () => {
   const TB = { S: 25, M: 60, L: 100 }; // the CLI defaults (readCoreLimits); runCore alone is unbudgeted
   const stopWith = (digest) => (w) => { w.files[`${WT}/.forge-lean/result.json`] = JSON.stringify({ status: "budget-exceeded", summary: "too big", digest }); };
 
-  it("an overrun ends needs-human budget.exceeded with the builder's digest, checkpointed, recoverable once", async () => {
+  it("an overrun ends budget-exceeded (#4505) with the builder's digest, checkpointed, recoverable once", async () => {
     const w = budgetWorld(stopWith("done: parser. remaining: 3 adapters. recommend split")); const dir = tmpDir("core-tb-");
     const r = await run(w, { dir, turnBudgets: TB });
-    assert.equal(r.terminalReason, "needs-human"); assert.equal(r.code, OUTCOME_CODES.BUDGET_EXCEEDED);
+    assert.equal(r.terminalReason, "budget-exceeded"); assert.equal(r.code, OUTCOME_CODES.BUDGET_EXCEEDED);
     assert.match(r.detail, /size S, 25 turns/); assert.match(r.detail, /remaining: 3 adapters/);
     assert.equal(classifyNeedsHuman({ outcome: r.terminalReason, code: r.code }), "recoverable");
     assert.deepEqual(r.turns, { size: "S", budget: 25, build: 28, total: 31, exceeded: true });
@@ -5326,7 +5479,7 @@ describe("#4392: implement turn budget", () => {
     assert.equal(w.seen[2].resume, null, "the wrap-up is a fresh session");
     assert.match(w.seen[2].prompt, /The engine froze \.forge-lean\/contract\.json/); assert.match(w.seen[2].prompt, /at most 5 turns/);
     assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "commit" && c.some((x) => /checkpoint after turn budget/.test(x))), "work checkpointed");
-    assert.ok(w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN") && c.includes("remaining: 3 adapters")));
+    assert.ok(!w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN")), "#4505: no human escalation");
     const log = readLog(dir, 7);
     assert.ok(log.some((e) => e.event === "TURN_BUDGET_EXCEEDED" && e.size === "S" && e.budget === 25 && e.turns === 25 && e.grant === 5));
     assert.deepEqual(log.find((e) => e.event === "RUN_TERMINAL").turns, r.turns);
@@ -5342,6 +5495,35 @@ describe("#4392: implement turn budget", () => {
     assert.equal(o2.code, OUTCOME_CODES.BUDGET_EXCEEDED); assert.match(o2.detail, /No builder digest; changes so far/);
   });
 
+  const addNH = (w) => w.edits.filter((e) => e.join(" ") === "issue edit 7 -R o/r --add-label needs-human").length;
+  it("#4505 a turn overrun ends budget-exceeded, not needs-human: no label, no NEEDS_HUMAN comment, recoverable", async () => {
+    const w = budgetWorld(stopWith("done: parser. remaining: tests")); const dir = tmpDir("core-tb-");
+    const r = await run(w, { dir, turnBudgets: TB });
+    assert.equal(r.terminalReason, "budget-exceeded"); assert.equal(r.code, OUTCOME_CODES.BUDGET_EXCEEDED);
+    assert.equal(r.branch, "feat/issue-7-lean", "the checkpoint branch rides on the result"); assert.match(r.detail, /remaining: tests/);
+    assert.equal(addNH(w), 0, "no needs-human label"); assert.ok(!w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN")), "no Needs human comment");
+    assert.equal(classifyNeedsHuman({ outcome: r.terminalReason, code: r.code }), "recoverable");
+    const term = readLog(dir, 7).find((e) => e.event === "RUN_TERMINAL");
+    assert.equal(term.reason, "budget-exceeded"); assert.equal(term.code, OUTCOME_CODES.BUDGET_EXCEEDED);
+    assert.ok(w.comments.some((c) => c.includes("FORGE:TRAJECTORY") && /recoverable budget\.exceeded/.test(c)), "the trajectory records the recoverable end");
+  });
+
+  it("#4505 a budget.exceeded recovery lane runs at the next size budget; non-final stays unlabelled, a final overrun is needs-human", async () => {
+    const nonFinal = budgetWorld(stopWith("still more"));
+    const r1 = await run(nonFinal, { dir: tmpDir("core-tb-"), turnBudgets: TB, recover: { code: OUTCOME_CODES.BUDGET_EXCEEDED, attempt: 1, final: false } });
+    assert.deepEqual(nonFinal.seen.map((x) => x.turnMax), [0, 60, 12], "S lane retried at M: 60 turns, wrap-up grant 12");
+    assert.equal(r1.turns.size, "M"); assert.equal(r1.terminalReason, "budget-exceeded"); assert.equal(r1.recovery, true);
+    assert.equal(addNH(nonFinal), 0);
+    assert.ok(builders(nonFinal).some((b) => /Recovery pass \(budget\.exceeded\): .*Continue from the checkpoint/.test(b[4])));
+    const fin = budgetWorld(stopWith("still more"));
+    const r2 = await run(fin, { dir: tmpDir("core-tb-"), turnBudgets: TB, recover: { code: OUTCOME_CODES.BUDGET_EXCEEDED, attempt: 1, final: true } });
+    assert.equal(r2.terminalReason, "needs-human"); assert.equal(r2.code, OUTCOME_CODES.BUDGET_EXCEEDED);
+    assert.equal(addNH(fin), 1, "the failed recovery is a human escalation"); assert.ok(fin.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN")));
+    const other = budgetWorld(stopWith("still more")); // another code's recovery keeps the lane's size
+    const r3 = await run(other, { dir: tmpDir("core-tb-"), turnBudgets: TB, recover: { code: "ci.red", attempt: 1, final: false } });
+    assert.equal(r3.turns.size, "S"); assert.equal(r3.terminalReason, "budget-exceeded");
+  });
+
   it("size comes from a size: label over the contract; 0 disables the budget and nothing is capped", async () => {
     const w = world({ labels: [{ name: "size:L" }] }); const caps = []; const orig = w.io.runner;
     w.io.runner = async (c) => { if (c.role === "builder") caps.push(c.turnMax ?? 0); return orig(c); };
@@ -5896,6 +6078,36 @@ describe("#4450 light lane: one builder session, derived contract, upgrade to th
     assert.equal(typeof events(dir, "LIGHT_DONE")[0].cost_usd, "number");
   });
 
+  it("#4502 a light lane that adds an undeclared package edge gets the structure gate: one builder resume, then merges", async () => {
+    const EDGE = { from: "@s/db", to: "@s/core", kind: "dependencies", manifest: "packages/db/package.json" };
+    const quiet = { package_edges_added: [], package_edges_removed: [], import_pairs: [], boundary_config_changed: { changed: false, files: [], loosens: false, tightens: false } };
+    const w = lworld(), dir = tmpDir("light-struct-"); const q = [{ ...quiet, package_edges_added: [EDGE] }, quiet];
+    w.io.structureDelta = async () => (q.length > 1 ? q.shift() : q[0]);
+    const r = await run(w, { dir, ...ON });
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(events(dir, "LIGHT_DONE").length, 1, "stayed light");
+    assert.equal(builders(w).length, 2, "the light session plus one structure resume");
+    assert.match(builders(w)[1][4], /@s\/db -> @s\/core/);
+    assert.equal(events(dir, "STRUCTURE_DELTA").length >= 1, true);
+  });
+
+  it("#4502 a typed budget error in the light step ends as in the full lane: no second builder session, no upgrade", async () => {
+    const w = lworld(), dir = tmpDir("light-typed-"); const orig = w.io.runner;
+    let tries = 0;
+    w.io.runner = async (c) => { if (c.role === "builder") { tries++; throw Object.assign(new Error("turn budget spent"), { laneCode: OUTCOME_CODES.BUDGET_EXCEEDED }); } return orig(c); };
+    const r = await run(w, { dir, ...ON });
+    assert.equal(r.code, OUTCOME_CODES.BUDGET_EXCEEDED);
+    assert.equal(tries, 1, "no upgrade session");
+    assert.equal(events(dir, "LIGHT_UPGRADE").length, 0);
+  });
+
+  it("#4502 the targeted light tests run with the configured precheck timeout", async () => {
+    const w = lworld(), dir = tmpDir("light-timeout-"); const seen = [];
+    w.io.runCommand = async (a) => { seen.push(a.timeoutMs); return { rc: 0, output: "" }; };
+    await run(w, { dir, ...ON });
+    assert.ok(seen.length && seen.every((t) => Number.isFinite(t) && t > 0 && t < 2 ** 40), `timeouts: ${seen}`);
+  });
+
   for (const [name, code, o] of [
     ["oversized diff", "diff_lines", { numstat: "80\t3\tsrc/foo.js\n20\t0\ttest/foo.test.js\n" }],
     ["non-red repro", "repro_not_red", { repro: { base: "PASSED", head: "RAN" } }],
@@ -5954,15 +6166,14 @@ describe("#4450 light lane: one builder session, derived contract, upgrade to th
     w.io.structureDelta = async () => { w.over.structure.push(w.calls.length); return { package_edges_added: [], package_edges_removed: [], import_pairs: [] }; };
     return w;
   };
-  it("#4451 a light lane that is not upgraded makes no context-pack, structure or hotspot calls", async () => {
+  it("#4451/#4502 a light lane that is not upgraded makes no context-pack call but runs the structure and hotspot gates", async () => {
     const w = overhead(), dir = tmpDir("light-over-");
     const r = await run(w, { dir, ...ON, contextPack: { mode: "on" } });
     assert.equal(r.terminalReason, "merged");
     assert.equal(events(dir, "LIGHT_DONE").length, 1);
-    assert.deepEqual(w.over, { pack: [], hot: [], structure: [] });
+    assert.deepEqual(w.over.pack, []);
+    assert.ok(w.over.hot.length >= 1 && w.over.structure.length >= 1, "#4502: the full lane's gates run");
     assert.equal(events(dir, "CONTEXT_PACK").length, 0);
-    // only the merge-time record (local numstat, no structure-delta call) remains; no implement-time delta
-    assert.deepEqual(events(dir, "STRUCTURE_DELTA").map((e) => e.phase), ["merge"]);
     assert.equal(events(dir, "RUN_TERMINAL")[0].light, true);
   });
   it("#4451 an upgraded light lane computes the hotspots and the context pack before the plan call and runs the structure delta", async () => {

package/bin/lean/lightlane.mjs

@@ -23,14 +23,14 @@ const one = (s, max = DETAIL_MAX) => {
 
 /** The one builder session of a light lane: failing test, fix, targeted tests, result.json with what the contract is derived from. */
 export function lightBuildPrompt(n, opts = {}) {
-  return `Resolve issue #${n} (read it with gh issue view ${n} --comments) in ONE session; this is a light lane for a small, well-specified issue. There is no plan step and no frozen contract: the engine derives the contract from your diff and your test.
+  return `Resolve issue #${n} (read it with gh issue view ${n} --comments) in ONE session; this is a light lane for a small, well-specified issue. There is no plan step and no frozen contract: the engine derives the contract from the files the issue names and your test.
 
 ${hostRules(opts)}
 
 1. Write the failing regression test first and run it: it must fail on the current code for the reason the issue describes.
 2. Make the smallest fix that makes it pass. Keep the public API shape unchanged (signatures, sync/async, generator/function, exported names); the engine checks it.
 3. Run the targeted tests (the new test plus the existing tests of the files you changed), run the repo's formatter on the files you changed, and commit. Do not push or touch GitHub.
-4. Run \`node ${FORGEDOCK_CLI} check\` in the worktree and fix until it passes.
+4. Re-run the targeted tests once more on the committed tree and make sure \`git status\` is clean (the engine runs its own gates afterwards; there is no contract file to check yet).
 
 When done and committed, write ${IMPLEMENTATION_FILE} (markdown, no HTML comments):
 ### Approach
@@ -79,19 +79,22 @@ export function apiShapeReasons(r) {
  * issue sentence, else the issue title; deliverables: the changed non-test files; validate: the repro command plus each
  * targeted test command; repro_test: the builder's, else "none" with a reason. validateContract judges it like any other.
  */
-export function deriveLightContract({ title = "", issueText = "", result = null, files = [] } = {}) {
+export function deriveLightContract({ title = "", issueText = "", result = null, files = [], predictedFiles = null } = {}) {
   const r = result && typeof result === "object" ? result : {};
   const said = typeof r.requirement === "string" ? r.requirement.trim() : "";
   const quote = said && inIssue(said, issueText) ? said : String(title ?? "").trim();
   const paths = [...new Set((Array.isArray(files) ? files : []).map((f) => String(f ?? "").trim()).filter((f) => f && f !== LEAN_DIR && !f.startsWith(`${LEAN_DIR}/`)))];
-  const code = paths.filter((f) => classifyPath(f) !== "test");
+  const changed = paths.filter((f) => classifyPath(f) !== "test");
+  // #4502: deliverables are what the issue names (the diff cannot fail its own scope check); no named files: the diff, as before
+  const named = Array.isArray(predictedFiles) ? new Set(predictedFiles.map((f) => String(f ?? "").trim())) : null;
+  const code = named ? changed.filter((f) => named.has(f)) : changed;
   const t = r.repro_test;
   const repro = t && typeof t === "object" && !Array.isArray(t) && String(t.path ?? "").trim() && String(t.command ?? "").trim()
     ? { path: String(t.path).trim(), id: String(t.id ?? "").trim(), command: String(t.command).trim() } : null;
   const commands = [...new Set([repro?.command, ...(Array.isArray(r.tests) ? r.tests : []).map((x) => (x && typeof x === "object" ? String(x.command ?? "").trim() : ""))].filter(Boolean))];
   return {
     requirements: [{ id: "R1", quote, disposition: "deliver" }],
-    deliverables: code.map((path, i) => ({ id: `D${i + 1}`, path, change: "light-lane fix (derived from the diff)", requirements: ["R1"] })),
+    deliverables: code.map((path, i) => ({ id: `D${i + 1}`, path, change: "light-lane fix (issue-named file)", requirements: ["R1"] })),
     validate: commands.map((command, i) => ({ id: `V${i + 1}`, command })),
     ...(repro ? { repro_test: repro } : { repro_test: "none", repro_test_reason: "the light-lane builder named no repro test" }),
   };
@@ -109,14 +112,28 @@ export function upgradeNote(reasons) {
 /**
  * #4451: the light targeted tests, concurrently through precheck.mjs runChecks (one heavy slot per running command, the
  * worker cap `parallelism` divided among them) with no round budget: every command runs, none is deferred to CI.
- * run({command, workers}) -> {rc, output}. Returns [{command, rc, output}] in input order.
+ * run({command, timeoutMs, workers}) -> {rc, output}. Returns [{command, rc, output}] in input order.
  */
-export async function runLightTests({ commands, parallelism = 1, run, acquire, now = () => Date.now() }) {
-  // the per-command limit stays far below the budget, so runChecks never sees a budget cut: a timeout (rc 124) stays a failure
-  const { results } = await runChecks({ commands, parallelism, budgetMs: Number.MAX_SAFE_INTEGER, perCommandMs: 2 ** 40, now, acquire, run: ({ command, workers }) => run({ command, workers }) });
+export async function runLightTests({ commands, parallelism = 1, run, acquire, now = () => Date.now(), timeoutMs }) {
+  // #4502: the configured per-command timeout reaches the runner (else io.runCommand's 300 s default applies); the budget stays far above it,
+  // so runChecks never sees a budget cut: a timeout (rc 124) stays a failure
+  const per = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 2 ** 40;
+  const { results } = await runChecks({ commands, parallelism, budgetMs: Number.MAX_SAFE_INTEGER, perCommandMs: per, now, acquire, run: ({ command, timeoutMs: t, workers }) => run({ command, timeoutMs: t, workers }) });
   return results.map(({ command, rc, output }) => ({ command, rc, output }));
 }
 
+/** Non-test changed files (engine dir skipped) that the issue does not name. */
+function scopeCreep(files, predicted) {
+  const named = new Set(predicted.map((f) => String(f ?? "").trim()));
+  return (files ?? []).map((f) => String(f ?? "").trim()).filter((f) => f && f !== LEAN_DIR && !f.startsWith(`${LEAN_DIR}/`) && classifyPath(f) !== "test" && !named.has(f));
+}
+
+/** #4502: a typed builder error (budget, idle/timeout deferral, spawn failure, usage limit) belongs to the lane's own catch, not to an upgrade. */
+export function isTypedBuilderError(e) {
+  if (!e || typeof e !== "object") return false;
+  return Boolean(e.laneCode || e.deferCode || e.spawnDeterministic === true || e.usageLimit || /^CLI_/.test(String(e.code ?? "")) || /usage limit/i.test(String(e.message ?? "")));
+}
+
 /**
  * One light lane step. ctx callbacks (all async unless noted): build() runs the one builder session; readResult();
  * checkpoint() commits uncommitted work; changedFiles(); numstat() -> `git diff --numstat` text; runTests(commands) ->
@@ -124,7 +141,7 @@ export async function runLightTests({ commands, parallelism = 1, run, acquire, n
  * or null; apiShape() -> detectApiShape output or null; validate(contract) -> {ok, problems} (sync). Plus title, issueText,
  * riskPaths, cfg. Returns {upgrade:false, contract, files, repro, testFailures} or {upgrade:true, reasons, files, ...}, plus the
  * gate inputs of the FORGE:LITE receipt (#4452): diff (parseNumstat), apiShape (apiShapeReasons), testCommands, testRuns.
- * Never throws: an internal error is the upgrade reason light_error.
+ * An internal error is the upgrade reason light_error; a typed builder error (isTypedBuilderError) is rethrown.
  */
 export async function runLightStep(ctx) {
   const up = (reasons, extra = {}) => ({ upgrade: true, reasons, contract: null, files: [], repro: null, testFailures: 0, diff: null, apiShape: null, testCommands: [], testRuns: null, ...extra });
@@ -135,8 +152,13 @@ export async function runLightStep(ctx) {
     const files = await ctx.changedFiles();
     if (!files.length) return up([{ code: "no_commit", detail: `the light builder made no commit (status ${one(result?.status ?? "none", 40)})` }]);
     if (result?.status !== "fixed") return up([{ code: "not_fixed", detail: `light builder status ${one(result?.status ?? "none", 40)}${result?.summary ? `: ${one(result.summary)}` : ""}` }], { files });
-    const contract = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result, files });
+    const predicted = Array.isArray(ctx.predictedFiles) ? ctx.predictedFiles : null;
+    const contract = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result, files, predictedFiles: predicted });
     const vc = ctx.validate(contract);
+    if (!vc?.ok && predicted && scopeCreep(files, predicted).length) { // the issue-named deliverables are empty: the diff left the issue's scope
+      const t = upgradeTriggers({ diff: parseNumstat(await ctx.numstat()), repro: null, testFailures: 0, riskPaths: ctx.riskPaths ?? [], apiShape: [], cfg: ctx.cfg ?? {} });
+      return up([{ code: "scope_creep", detail: `changed file(s) the issue does not name: ${one(scopeCreep(files, predicted).slice(0, 5).join(", "))}` }, ...t.reasons], { files });
+    }
     if (!vc?.ok) return up([{ code: "contract_invalid", detail: `derived contract: ${one((vc?.problems ?? [])[0] ?? "invalid")}` }], { files });
 
     let testFailures = 0;
@@ -155,10 +177,13 @@ export async function runLightStep(ctx) {
     const [repro, numstat, shape] = await Promise.all([ctx.reproOf(contract), ctx.numstat(), ctx.apiShape()]);
     const diff = parseNumstat(numstat), apiShape = apiShapeReasons(shape);
     const t = upgradeTriggers({ diff, repro, testFailures, riskPaths: ctx.riskPaths ?? [], apiShape, cfg: ctx.cfg ?? {} });
-    const latest = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result: (await ctx.readResult()) ?? result, files: now });
-    return { upgrade: t.upgrade, reasons: t.reasons, contract: t.upgrade ? null : (ctx.validate(latest)?.ok ? latest : contract), files: now, repro, testFailures,
+    const outside = predicted ? scopeCreep(now, predicted) : [];
+    const reasons = outside.length ? [...t.reasons, { code: "scope_creep", detail: `changed file(s) the issue does not name: ${one(outside.slice(0, 5).join(", "))}` }] : t.reasons;
+    const latest = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result: (await ctx.readResult()) ?? result, files: now, predictedFiles: predicted });
+    return { upgrade: t.upgrade || outside.length > 0, reasons, contract: t.upgrade || outside.length ? null : (ctx.validate(latest)?.ok ? latest : contract), files: now, repro, testFailures,
       diff, apiShape, testCommands: commands, testRuns: runs == null ? null : (runs ?? []).length };
   } catch (e) {
+    if (isTypedBuilderError(e)) throw e; // #4502: the lane's own catch ends it as in the full lane, no second builder session
     return up([{ code: "light_error", detail: one(e?.message ?? e) }]);
   }
 }

package/bin/lean/lightlane.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { deriveLightContract, runLightStep, runLightTests, parseNumstat, apiShapeReasons, upgradeNote, lightBuildPrompt, renderLiteReceipt } from "./lightlane.mjs";
+import { isTypedBuilderError, deriveLightContract, runLightStep, runLightTests, parseNumstat, apiShapeReasons, upgradeNote, lightBuildPrompt, renderLiteReceipt } from "./lightlane.mjs";
 import { validateContract } from "./conformance.mjs";
 
 const TITLE = "foo crashes on null input";
@@ -235,3 +235,37 @@ describe("renderLiteReceipt (#4452)", () => {
     for (const k of ["upgrade", "reasons", "contract", "files", "repro", "testFailures"]) assert.ok(k in r, k);
   });
 });
+
+describe("#4502 light lane fixes", () => {
+  it("runLightStep rethrows typed builder errors; internal errors stay light_error", async () => {
+    for (const e of [{ laneCode: "budget.exceeded" }, { deferCode: "cli.idle" }, { code: "CLI_SPAWN_FAILED" }, { code: "CLI_TIMEOUT" }, { spawnDeterministic: true }, { usageLimit: true }]) {
+      const { ctx } = step({ ctx: { build: async () => { throw Object.assign(new Error("typed"), e); } } });
+      await assert.rejects(runLightStep(ctx), (x) => isTypedBuilderError(x) && x.message === "typed");
+    }
+    const { ctx } = step({ ctx: { build: async () => { throw new Error("git broke"); } } });
+    assert.deepEqual(codes(await runLightStep(ctx)), ["light_error"]);
+    assert.equal(isTypedBuilderError(null), false);
+  });
+  it("the light prompt no longer asks for a check that cannot pass", () => {
+    const p = lightBuildPrompt(7);
+    assert.doesNotMatch(p, /forgedock[^\n]* check/);
+    assert.doesNotMatch(p, /\bcheck\b[^\n]*until it passes/);
+    assert.match(p, /git status/);
+  });
+  it("deliverables come from the issue-named files; a diff file outside them upgrades with scope_creep", () => {
+    const c = deriveLightContract({ title: TITLE, issueText: ISSUE, result: RESULT, files: ["src/foo.js", "src/other.js", "test/foo.test.js"], predictedFiles: ["src/foo.js"] });
+    assert.deepEqual(c.deliverables.map((d) => d.path), ["src/foo.js"]);
+  });
+  it("scope_creep: a changed non-test file the issue does not name is an upgrade reason", async () => {
+    const { ctx } = step({ files: ["src/foo.js", "src/other.js", "test/foo.test.js"], numstat: "5\t1\tsrc/foo.js\n2\t0\tsrc/other.js\n20\t0\ttest/foo.test.js\n", ctx: { predictedFiles: ["src/foo.js"] } });
+    const r = await runLightStep(ctx);
+    assert.equal(r.upgrade, true); assert.ok(codes(r).includes("scope_creep"), JSON.stringify(r.reasons));
+    const ok = await runLightStep(step({ ctx: { predictedFiles: ["src/foo.js"] } }).ctx);
+    assert.equal(ok.upgrade, false, JSON.stringify(ok.reasons));
+  });
+  it("runLightTests forwards the configured timeout to the runner", async () => {
+    const seen = [];
+    await runLightTests({ commands: ["a", "b"], timeoutMs: 900000, run: async (x) => { seen.push(x.timeoutMs); return { rc: 0, output: "" }; } });
+    assert.deepEqual(seen, [900000, 900000]);
+  });
+});