forgedock 1.27.0 → 1.28.0

package/bin/lean/batch.mjs

@@ -4,12 +4,14 @@
  * Durable batch state and detached lanes for `forgedock orchestrate` (#4121).
  *
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
- * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K) and
- * `lanes/<issue>.{json,log}` (each lane's result and output). Every write is tmp + fsync + rename, and the root must be
+ * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
+ * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
+ * when the scheduler loop returns; `forgedock orchestrate --resume` on a finished batch replays it, #4192). Every write is tmp + fsync + rename, and the root must be
  * on disk, never tmpfs. A lane is its own session (`setsid` through `detached`), so killing the dispatcher leaves it
- * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path.
+ * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path. These
+ * detached lanes are the `local` execution (#4253); `execution.mjs` is the sandbox-provider seam for remote lanes.
  */
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
@@ -63,6 +65,13 @@ export function newBatchId(now = Date.now(), pid = process.pid) {
   return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
 }
 
+/** Ids of the batches under `root` (directories with a `plan.json`). */
+export function listBatches(root) {
+  let names = [];
+  try { names = readdirSync(root); } catch { return []; }
+  return names.filter((n) => ID_RE.test(n) && existsSync(join(root, n, "plan.json"))).sort();
+}
+
 /** Handle on one batch directory. */
 export function openBatch(root, id) {
   if (!ID_RE.test(String(id ?? ""))) throw new Error(`invalid batch id ${JSON.stringify(id)}`);
@@ -84,6 +93,15 @@ export function openBatch(root, id) {
       if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
       writeAtomic(f("parallel"), `${k}\n`);
     },
+    /** The lane updates in `log.jsonl`, in order (unparsable lines skipped). */
+    readLog: () => {
+      let text = "";
+      try { text = readFileSync(f("log.jsonl"), "utf8"); } catch { return []; }
+      return text.split("\n").flatMap((l) => { try { return l ? [JSON.parse(l)] : []; } catch { return []; } });
+    },
+    readReport: () => readJson(f("report.json")),
+    writeReport: (report) => writeAtomic(f("report.json"), JSON.stringify(report) + "\n"),
+    clearReport: () => rmSync(f("report.json"), { force: true }),
     resultFile: (n) => f(join("lanes", `${n}.json`)),
     logFile: (n) => f(join("lanes", `${n}.log`)),
   };

package/bin/lean/batch.test.mjs

@@ -10,6 +10,8 @@ import { orchestrate, deferPolicy, DEFER_BACKOFF_S } from "./orchestrate.mjs";
 import { openBatch, fsTypeOf, assertDiskPath, isLaneAlive, writeAtomic, launchLane } from "./batch.mjs";
 import { orchestrateFromCli, runFromCli, readOrchestration } from "../engine-cli.mjs";
 
+// orchestrateFromCli opens the host lane registry (#4191): keep it in a temp dir, also for spawned dispatchers.
+process.env.FORGEDOCK_SCHED_DIR = tmpDir("batch-sched-");
 const quiet = async (fn) => { const l = console.log; console.log = () => {}; try { return await fn(); } finally { console.log = l; } };
 const until = async (cond, ms = 15000) => {
   const end = Date.now() + ms;
@@ -201,9 +203,9 @@ await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--
     assert.doesNotThrow(() => assertDiskPath("/home/u/.forge/batches", mounts));
     assert.equal(isLaneAlive(process.pid, "--definitely-not-in-my-cmdline"), false);
     assert.equal(isLaneAlive(2 ** 22 + 12345, null), false);
-    assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3 });
-    writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n");
-    assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2 });
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 3, window_min: 30 }, maxDeferrals: 3, globalParallel: null });
+    writeFileSync(join(root, "forge.yaml"), "orchestration:\n  breaker:\n    errors: 5\n    window_min: 10\n  max_deferrals: 2\n  global_parallel: 4\n");
+    assert.deepEqual(readOrchestration(root), { breaker: { errors: 5, window_min: 10 }, maxDeferrals: 2, globalParallel: 4 });
   });
 
   it("run-issue --result-file writes the lane result, also when the run throws", async () => {

package/bin/lean/checks.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Change-scoped lane checks (#4218): discover the repo's typecheck/lint/test commands, narrow each to what the lane's
+ * change can affect with the ci-local scoper (widening to the full command when impact is unknown), and share the
+ * tsc/eslint incremental caches across worktrees keyed by base commit: a shared entry is read-only and is copied into
+ * the worktree (hydrate); a lane publishes its caches only when no entry exists yet (copy on write, first writer wins).
+ *
+ *   node bin/lean/checks.mjs [--repo DIR] --base REF [--json]   print the scoped checks (hydrates the cache first)
+ *   node bin/lean/checks.mjs [--repo DIR] --base REF --publish  publish this worktree's caches for the base commit
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { git, changedFiles, sha256, homeForgeDir, shellSplit, shellQuote, globToRegex } from "../../scripts/ci-local/lib.mjs";
+import { makeScopeCtx, scopeCommand } from "../../scripts/ci-local/scoping.mjs";
+
+const px = path.posix;
+/** Lane-local cache dir, at the same relative path in every worktree so tsbuildinfo's relative paths match. */
+export const LOCAL_CACHE = "node_modules/.cache/forge-verify";
+const SCRIPT_KINDS = { typecheck: "typecheck", "type-check": "typecheck", tsc: "typecheck", lint: "lint", test: "test" };
+/** Runs a resolved script body's binary from node_modules/.bin, as `<pm> run` would. */
+const EXEC = { pnpm: "pnpm exec", yarn: "yarn", npm: "npx" };
+/** Commands a script body runs from PATH, never from node_modules/.bin. */
+const SYSTEM_BINS = new Set(["pnpm", "yarn", "npx", "npm", "bun", "bunx", "node", "bash", "sh", "env", "make", "python", "python3", "uv", "poetry"]);
+const exists = (repo, f) => fs.existsSync(path.join(repo, f));
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+const readText = (file) => { try { return fs.readFileSync(file, "utf8"); } catch { return ""; } };
+
+function packageManager(repo) {
+  if (exists(repo, "pnpm-lock.yaml")) return "pnpm";
+  if (exists(repo, "yarn.lock")) return "yarn";
+  return "npm";
+}
+
+function turboTasks(repo) {
+  const t = readJson(path.join(repo, "turbo.json"));
+  return new Set(Object.keys((t && (t.tasks || t.pipeline)) || {}));
+}
+
+/** The root package plus its declared workspace packages (package.json `workspaces`, pnpm-workspace.yaml `packages`). */
+function workspaceDirs(repo, tracked) {
+  const root = readJson(path.join(repo, "package.json"));
+  if (!root) return [];
+  const ws = root.workspaces;
+  const globs = Array.isArray(ws) ? ws : Array.isArray(ws?.packages) ? ws.packages : [];
+  const pnpm = readText(path.join(repo, "pnpm-workspace.yaml"));
+  for (const m of pnpm.matchAll(/^\s*-\s*['"]?([^'"\s#]+)['"]?/gm)) globs.push(m[1]);
+  const res = globs.filter((g) => typeof g === "string" && !g.startsWith("!")).map((g) => globToRegex(g.replace(/^\.\//, "").replace(/\/$/, "")));
+  const dirs = tracked.filter((f) => px.basename(f) === "package.json" && f !== "package.json" && !f.split("/").includes("node_modules") && exists(repo, f))
+    .map((f) => px.dirname(f)).filter((d) => res.some((re) => re.test(d)));
+  return [".", ...dirs];
+}
+
+/**
+ * The repo's typecheck/lint/test commands: [{kind, command, cwd}] (cwd repo-relative). JS: a turbo task when turbo.json
+ * defines it, else the workspace packages' scripts when any defines it, else the root script. Python: pytest and ruff
+ * when configured, run through `uv run` / `poetry run` when that lockfile exists.
+ */
+export function discoverChecks(repo) {
+  const out = [];
+  const tracked = git(repo, ["ls-files", "--cached", "--others", "--exclude-standard"]).out.split("\n").filter(Boolean);
+  const pkgDirs = workspaceDirs(repo, tracked);
+  if (pkgDirs.length) {
+    const pm = packageManager(repo);
+    const turbo = turboTasks(repo);
+    const scripts = new Map(pkgDirs.map((d) => [d, (readJson(path.join(repo, d, "package.json")) || {}).scripts || {}]));
+    for (const [script, kind] of Object.entries(SCRIPT_KINDS)) {
+      if (turbo.has(script)) { out.push({ kind, command: `${exists(repo, "node_modules/.bin/turbo") ? "" : "npx "}turbo run ${script}`, cwd: "." }); continue; }
+      const ws = pkgDirs.filter((d) => d !== "." && typeof scripts.get(d)[script] === "string").sort();
+      const dirs = ws.length ? ws : typeof (scripts.get(".") || {})[script] === "string" ? ["."] : [];
+      for (const d of dirs) out.push({ kind, command: `${pm} run ${script}`, cwd: d, exec: EXEC[pm] });
+    }
+  }
+  const pyproject = readText(path.join(repo, "pyproject.toml"));
+  const run = exists(repo, "uv.lock") ? "uv run " : exists(repo, "poetry.lock") ? "poetry run " : "";
+  if (/^\[tool\.ruff/m.test(pyproject) || exists(repo, "ruff.toml") || exists(repo, ".ruff.toml")) out.push({ kind: "lint", command: `${run}ruff check .`, cwd: "." });
+  if (/^\[tool\.pytest/m.test(pyproject) || exists(repo, "pytest.ini") || tracked.some((f) => px.basename(f) === "conftest.py")) out.push({ kind: "test", command: `${run}pytest`, cwd: "." });
+  return out;
+}
+
+/** The shared cache entry for this repo (all its worktrees share the git common dir) at the base commit. */
+export function cacheEntry(repo, baseSha) {
+  const gc = git(repo, ["rev-parse", "--git-common-dir"]).out.trim();
+  const common = fs.realpathSync(path.resolve(repo, gc || ".git"));
+  return path.join(homeForgeDir(), "verify-cache", sha256(common).slice(0, 16), baseSha);
+}
+
+/** Copy the shared entry's files into the worktree's local cache (files the lane already has are kept). */
+export function hydrate(repo, entry) {
+  if (!exists(repo, "node_modules") || !fs.existsSync(entry)) return { hydrated: [] };
+  const local = path.join(repo, LOCAL_CACHE);
+  fs.mkdirSync(local, { recursive: true });
+  const hydrated = [];
+  for (const f of fs.readdirSync(entry)) {
+    const to = path.join(local, f);
+    if (fs.existsSync(to)) continue;
+    fs.copyFileSync(path.join(entry, f), to);
+    hydrated.push(f);
+  }
+  return { hydrated };
+}
+
+/** Publish the worktree's caches as the shared entry, only when none exists yet: tmp dir + rename, never overwrite. */
+export function publish(repo, entry) {
+  const local = path.join(repo, LOCAL_CACHE);
+  const files = fs.existsSync(local) ? fs.readdirSync(local).filter((f) => fs.statSync(path.join(local, f)).isFile()) : [];
+  if (!files.length) return { published: false, reason: "no local cache" };
+  if (fs.existsSync(entry)) return { published: false, reason: "entry exists" };
+  fs.mkdirSync(path.dirname(entry), { recursive: true });
+  const tmp = `${entry}.tmp-${process.pid}-${Date.now()}`;
+  fs.mkdirSync(tmp);
+  try {
+    for (const f of files) fs.copyFileSync(path.join(local, f), path.join(tmp, f));
+    fs.renameSync(tmp, entry);
+    return { published: true, files };
+  } catch (e) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    if (["EEXIST", "ENOTEMPTY", "EPERM"].includes(e.code)) return { published: false, reason: "entry exists" };
+    throw e;
+  }
+}
+
+/** Add the shared-cache flags to a tsc (-p or plain; not -b, which keeps per-project buildinfo) or eslint command. */
+export function withCacheFlags(check, repo) {
+  if (!check.command || !exists(repo, "node_modules")) return check;
+  const toks = shellSplit(check.command);
+  if (!toks) return check;
+  const local = px.relative(check.cwd || ".", LOCAL_CACHE);
+  const i = toks.findIndex((t) => ["tsc", "eslint"].includes(px.basename(t)));
+  if (i < 0) return check;
+  const rest = toks.slice(i + 1);
+  let add = [];
+  if (px.basename(toks[i]) === "tsc") {
+    if (rest.some((t) => ["-b", "--build", "--tsBuildInfoFile", "--incremental", "-w", "--watch"].includes(t) || t.startsWith("--incremental="))) return check;
+    const p = rest.indexOf("-p") >= 0 ? rest[rest.indexOf("-p") + 1] : rest.indexOf("--project") >= 0 ? rest[rest.indexOf("--project") + 1] : ".";
+    const project = px.normalize(px.join(check.cwd || ".", p || "."));
+    add = ["--incremental", "--tsBuildInfoFile", `${local}/tsc-${sha256(project).slice(0, 12)}.tsbuildinfo`];
+  } else {
+    if (rest.some((t) => t === "--cache-location" || t.startsWith("--cache-location="))) return check;
+    add = [...(rest.includes("--cache") ? [] : ["--cache"]), ...(rest.includes("--cache-strategy") ? [] : ["--cache-strategy", "content"]), "--cache-location", `${local}/eslintcache`];
+  }
+  return { ...check, command: [...toks.slice(0, i + 1), ...add, ...rest].map(shellQuote).join(" "), cache: true };
+}
+
+/** Changed files vs the merge base with `base` (the engine's .forge-lean/ hand-off files excluded). */
+export function laneChanges(repo, base) {
+  const { files, from } = changedFiles(repo, base);
+  return { files: files.filter((f) => !f.startsWith(".forge-lean/")), from };
+}
+
+/** The scoped checks for this lane: [{kind, command, cwd, mode, widen_reason, selector, reason}]. */
+export function scopedChecks({ repo, base, checks = discoverChecks(repo) }) {
+  const { files, from } = laneChanges(repo, base);
+  const sctx = makeScopeCtx({ repo, baseRef: base, from, changed: files });
+  return checks.map((c) => {
+    const r = scopeCommand(c.command, c.cwd === "." ? "" : c.cwd, sctx);
+    // A resolved script body (`pnpm run typecheck` -> `tsc -p apps/web`) runs its binary through the package manager.
+    const resolved = r.action !== "skip" && c.exec && r.command !== c.command && !SYSTEM_BINS.has(px.basename((shellSplit(r.command) || [""])[0]));
+    const out = { kind: c.kind, cwd: c.cwd, command: r.action === "skip" ? "" : resolved ? `${c.exec} ${r.command}` : r.command, mode: r.mode, widen_reason: r.widen_reason || "", selector: r.selector || "" };
+    if (r.reason) out.reason = r.reason;
+    return r.action === "skip" ? out : withCacheFlags(out, repo);
+  });
+}
+
+function parseArgs(argv) {
+  const o = { repo: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--repo") o.repo = argv[++i]; else if (t === "--base") o.base = argv[++i];
+    else if (t === "--json") o.json = true; else if (t === "--publish") o.publish = true;
+    else throw new Error(`unknown option ${t}`);
+  }
+  return o;
+}
+
+function main(argv) {
+  let o;
+  try { o = parseArgs(argv); } catch (e) { console.error(`checks: ${e.message}`); return 2; }
+  if (!o.base) { console.error("usage: checks.mjs [--repo DIR] --base REF [--json] [--publish]"); return 2; }
+  const repo = path.resolve(o.repo);
+  const mb = git(repo, ["merge-base", o.base, "HEAD"]);
+  if (mb.code !== 0) { console.error(`checks: cannot resolve base ${o.base}`); return 2; }
+  const entry = cacheEntry(repo, mb.out.trim());
+  if (o.publish) { console.log(JSON.stringify(publish(repo, entry))); return 0; }
+  hydrate(repo, entry);
+  const checks = scopedChecks({ repo, base: o.base });
+  if (o.json) { console.log(JSON.stringify(checks, null, 2)); return 0; }
+  if (!checks.length) console.log("# no typecheck/lint/test command found");
+  for (const c of checks) {
+    const where = c.cwd && c.cwd !== "." ? `(cd ${shellQuote(c.cwd)} && ${c.command})` : c.command;
+    if (c.mode === "skip") console.log(`${c.kind} skip  # skipped: ${c.reason || "not affected"}`);
+    else console.log(`${c.kind} ${c.mode} ${where}${c.widen_reason ? `  # widened: ${c.widen_reason}` : ""}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/bin/lean/checks.test.mjs

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** #4218: change-scoped typecheck/lint/test commands and the shared tsc/eslint cache (fixture repos, no tool runs). */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { discoverChecks, scopedChecks, cacheEntry, hydrate, publish, withCacheFlags, LOCAL_CACHE } from "./checks.mjs";
+
+const TMP = tmpDir("checks-4218-");
+process.env.FORGE_CI_LOCAL_HOME = path.join(TMP, "forge-home");
+const GIT_ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+const git = (repo, ...a) => execFileSync("git", ["-C", repo, ...a], { env: GIT_ENV, encoding: "utf8" });
+let n = 0;
+
+/** A throwaway repo: `files` committed on main, then branch feat checked out; node_modules/ is ignored. */
+function repo(files) {
+  const r = path.join(TMP, `repo${n++}`);
+  write(r, { ".gitignore": "node_modules/\n", ...files });
+  git(r, "init", "-q", "-b", "main");
+  git(r, "add", "-A");
+  git(r, "commit", "-qm", "base");
+  git(r, "checkout", "-qb", "feat");
+  fs.mkdirSync(path.join(r, "node_modules"), { recursive: true });
+  return r;
+}
+function write(r, files) {
+  for (const [f, body] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(r, f)), { recursive: true });
+    fs.writeFileSync(path.join(r, f), body);
+  }
+}
+const touch = (r, ...fs_) => { for (const f of fs_) fs.appendFileSync(path.join(r, f), "\n// change\n"); };
+const byKind = (checks) => Object.fromEntries(checks.map((c) => [c.kind, c]));
+
+const pnpmMonorepo = () => repo({
+  "package.json": JSON.stringify({ name: "root", private: true, scripts: { typecheck: "tsc --noEmit", lint: "eslint .", test: "vitest run" } }),
+  "pnpm-lock.yaml": "lockfileVersion: '9.0'\n",
+  "tsconfig.json": JSON.stringify({ files: [], references: [{ path: "apps/web" }, { path: "packages/ui" }] }),
+  "apps/web/package.json": JSON.stringify({ name: "web" }),
+  "apps/web/tsconfig.json": "{\n  // web app\n  \"compilerOptions\": { \"jsx\": \"preserve\", },\n  \"references\": [{ \"path\": \"../../packages/ui\" }]\n}\n",
+  "apps/web/src/page.tsx": "import { Button } from \"../../../packages/ui/src/button\";\nexport const Page = () => Button;\n",
+  "apps/web/src/page.test.tsx": "import { Page } from \"./page\";\ntest(\"page\", () => Page);\n",
+  "packages/ui/package.json": JSON.stringify({ name: "ui" }),
+  "packages/ui/tsconfig.json": JSON.stringify({ compilerOptions: { composite: true } }),
+  "packages/ui/src/button.tsx": "export const Button = 1;\n",
+  "packages/ui/src/button.test.tsx": "import { Button } from \"./button\";\ntest(\"button\", () => Button);\n",
+  ".github/workflows/ci.yml": "on: pull_request\n",
+});
+
+test("JS/TS pnpm monorepo: one web file scopes typecheck to its project, lint to the file, tests to related", () => {
+  const r = pnpmMonorepo();
+  assert.deepEqual(discoverChecks(r).map((c) => `${c.kind}:${c.command}:${c.cwd}`), ["typecheck:pnpm run typecheck:.", "lint:pnpm run lint:.", "test:pnpm run test:."]);
+  touch(r, "apps/web/src/page.tsx");
+  const c = byKind(scopedChecks({ repo: r, base: "main" }));
+  assert.equal(c.typecheck.mode, "scoped");
+  assert.equal(c.typecheck.selector, "tsc-project");
+  assert.match(c.typecheck.command, /^pnpm exec tsc --incremental --tsBuildInfoFile node_modules\/\.cache\/forge-verify\/tsc-[0-9a-f]{12}\.tsbuildinfo -p apps\/web --noEmit$/);
+  assert.equal(c.lint.mode, "scoped");
+  assert.equal(c.lint.command, "pnpm exec eslint --cache --cache-strategy content --cache-location node_modules/.cache/forge-verify/eslintcache apps/web/src/page.tsx");
+  assert.equal(c.test.mode, "scoped");
+  assert.match(c.test.command, /vitest related --run --passWithNoTests apps\/web\/src\/page\.tsx$/);
+});
+
+test("JS/TS pnpm monorepo: a shared package change builds every reached composite/referenced project with tsc -b", () => {
+  const r = pnpmMonorepo();
+  touch(r, "packages/ui/src/button.tsx");
+  const c = byKind(scopedChecks({ repo: r, base: "main" }));
+  assert.equal(c.typecheck.mode, "scoped");
+  assert.equal(c.typecheck.command, "pnpm exec tsc -b apps/web packages/ui");
+});
+
+test("npm single-package TS repo: the root project runs the full typecheck", () => {
+  const r = repo({
+    "package.json": JSON.stringify({ name: "one", scripts: { typecheck: "tsc --noEmit" } }),
+    "package-lock.json": "{}\n",
+    "tsconfig.json": "{}\n",
+    "src/a.ts": "export const a = 1;\n",
+    "src/a.test.ts": "import { a } from './a';\n",
+  });
+  touch(r, "src/a.ts");
+  const [c] = scopedChecks({ repo: r, base: "main" });
+  assert.equal(c.command.startsWith("npx tsc --incremental"), true);
+  assert.equal(c.mode, "full");
+  assert.equal(c.widen_reason, "root-project");
+});
+
+// Regression (#4218 AC2): unknown impact never narrows.
+for (const [file, reason] of [["pnpm-lock.yaml", "lockfile"], ["apps/web/tsconfig.json", "build-config"], [".github/workflows/ci.yml", "ci-config"]]) {
+  test(`unknown impact (${file}) runs every check in full`, () => {
+    const r = pnpmMonorepo();
+    fs.appendFileSync(path.join(r, file), "\n");
+    touch(r, "apps/web/src/page.tsx");
+    const checks = scopedChecks({ repo: r, base: "main" });
+    assert.equal(checks.length, 3);
+    for (const c of checks) {
+      assert.equal(c.mode, "full", `${c.kind} ${c.command}`);
+      assert.match(c.widen_reason, new RegExp(`^${reason}: ${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`));
+    }
+  });
+}
+
+const pyRepo = (lock, lockBody) => repo({
+  "pyproject.toml": "[project]\nname = \"pkg\"\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\n\n[tool.ruff]\nline-length = 100\n",
+  [lock]: lockBody,
+  "pkg/__init__.py": "",
+  "pkg/alpha.py": "def f():\n    return 1\n",
+  "pkg/beta.py": "def g():\n    return 2\n",
+  "tests/test_alpha.py": "from pkg.alpha import f\n\ndef test_f():\n    assert f() == 1\n",
+  "tests/test_beta.py": "from pkg.beta import g\n\ndef test_g():\n    assert g() == 2\n",
+});
+
+test("Python uv repo: one module scopes pytest to its tests and ruff to the file; uv.lock widens", () => {
+  const r = pyRepo("uv.lock", "version = 1\n");
+  assert.deepEqual(discoverChecks(r).map((c) => c.command), ["uv run ruff check .", "uv run pytest"]);
+  fs.appendFileSync(path.join(r, "pkg/alpha.py"), "# change\n");
+  const c = byKind(scopedChecks({ repo: r, base: "main" }));
+  assert.equal(c.test.mode, "scoped");
+  assert.equal(c.test.command, "uv run pytest tests/test_alpha.py");
+  assert.equal(c.lint.command, "uv run ruff check pkg/alpha.py");
+  fs.appendFileSync(path.join(r, "uv.lock"), "# change\n");
+  for (const x of scopedChecks({ repo: r, base: "main" })) { assert.equal(x.mode, "full"); assert.equal(x.widen_reason, "lockfile: uv.lock"); }
+});
+
+test("Python poetry repo: poetry run prefix; poetry.lock widens", () => {
+  const r = pyRepo("poetry.lock", "# lock\n");
+  fs.appendFileSync(path.join(r, "pkg/beta.py"), "# change\n");
+  const c = byKind(scopedChecks({ repo: r, base: "main" }));
+  assert.equal(c.test.command, "poetry run pytest tests/test_beta.py");
+  fs.appendFileSync(path.join(r, "poetry.lock"), "# change\n");
+  const t = byKind(scopedChecks({ repo: r, base: "main" })).test;
+  assert.equal(t.mode, "full");
+  assert.equal(t.command, "poetry run pytest");
+  assert.equal(t.widen_reason, "lockfile: poetry.lock");
+});
+
+test("shared cache: keyed by base commit, hydrated by copy, published once and never modified", () => {
+  const a = pnpmMonorepo();
+  const base = git(a, "rev-parse", "main").trim();
+  const entry = cacheEntry(a, base);
+  assert.ok(entry.startsWith(path.join(process.env.FORGE_CI_LOCAL_HOME, "verify-cache")));
+  assert.ok(entry.endsWith(base));
+  assert.deepEqual(publish(a, entry), { published: false, reason: "no local cache" });
+  write(a, { [`${LOCAL_CACHE}/eslintcache`]: "v1", [`${LOCAL_CACHE}/tsc-x.tsbuildinfo`]: "b1" });
+  assert.equal(publish(a, entry).published, true);
+  assert.equal(fs.readFileSync(path.join(entry, "eslintcache"), "utf8"), "v1");
+  // A second lane's different caches never overwrite the entry (first writer wins).
+  write(a, { [`${LOCAL_CACHE}/eslintcache`]: "v2" });
+  assert.deepEqual(publish(a, entry), { published: false, reason: "entry exists" });
+  assert.equal(fs.readFileSync(path.join(entry, "eslintcache"), "utf8"), "v1");
+  // Another worktree of the same repo shares the entry; hydrate copies, and a later local write leaves the entry alone.
+  const wt = path.join(TMP, `wt${n++}`);
+  git(a, "worktree", "add", "-q", wt, "main");
+  assert.equal(cacheEntry(wt, base), entry);
+  fs.mkdirSync(path.join(wt, "node_modules"));
+  assert.deepEqual(hydrate(wt, entry).hydrated.sort(), ["eslintcache", "tsc-x.tsbuildinfo"]);
+  fs.writeFileSync(path.join(wt, LOCAL_CACHE, "eslintcache"), "lane-write");
+  assert.equal(fs.readFileSync(path.join(entry, "eslintcache"), "utf8"), "v1");
+  assert.deepEqual(hydrate(wt, entry).hydrated, [], "files the lane already has are kept");
+  assert.equal(fs.readFileSync(path.join(wt, LOCAL_CACHE, "eslintcache"), "utf8"), "lane-write");
+});
+
+test("withCacheFlags: tsc -p and eslint get cache flags relative to cwd; tsc -b and no node_modules are untouched", () => {
+  const r = pnpmMonorepo();
+  assert.match(withCacheFlags({ command: "tsc --noEmit", cwd: "apps/web" }, r).command, /^tsc --incremental --tsBuildInfoFile \.\.\/\.\.\/node_modules\/\.cache\/forge-verify\/tsc-[0-9a-f]{12}\.tsbuildinfo --noEmit$/);
+  assert.equal(withCacheFlags({ command: "tsc -b apps/web", cwd: "." }, r).command, "tsc -b apps/web");
+  assert.equal(withCacheFlags({ command: "eslint --cache-location x a.ts", cwd: "." }, r).command, "eslint --cache-location x a.ts");
+  fs.rmSync(path.join(r, "node_modules"), { recursive: true });
+  assert.equal(withCacheFlags({ command: "eslint a.ts", cwd: "." }, r).command, "eslint a.ts");
+});
+
+test("discovery: declared workspace packages' scripts win over the root; undeclared package.json files are ignored", () => {
+  const r = repo({
+    "package.json": JSON.stringify({ name: "root", private: true, scripts: { test: "node --test" } }),
+    "pnpm-lock.yaml": "lockfileVersion: '9.0'\n",
+    "pnpm-workspace.yaml": "packages:\n  - 'apps/*'\n",
+    "apps/web/package.json": JSON.stringify({ name: "web", scripts: { typecheck: "tsc --noEmit" } }),
+    "scripts/fixtures/demo/package.json": JSON.stringify({ name: "demo", scripts: { test: "jest", lint: "eslint ." } }),
+  });
+  assert.deepEqual(discoverChecks(r).map((c) => `${c.kind}:${c.command}:${c.cwd}`), ["typecheck:pnpm run typecheck:apps/web", "test:pnpm run test:."]);
+});