forgedock 1.27.0 → 1.29.0

package/bin/lean/worktree.mjs

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Sparse lane worktrees (#4221). A lane checks out every tracked file except regular blobs at or above
+ * `maxBlobBytes` (forge.yaml `env.sparse_max_kb`, default 1024; 0 = off). Lockfiles, manifests, toolchain pins and
+ * git/forge config are always checked out (the #4220 dep cache and #4163 toolchain pins read them). The patterns are
+ * non-cone (`/*` then `!/<path>`), kept in the worktree's own `info/sparse-checkout`; `core.sparseCheckout` is per-worktree
+ * config (git sets `extensions.worktreeConfig` in the shared config), so the main checkout is untouched. A repo with no
+ * such blob gets today's plain `git worktree add`. A failed sparse step falls back to a full checkout; never fails a lane.
+ */
+import { join } from "node:path";
+
+export const DEFAULT_SPARSE_MAX_KB = 1024;
+
+const KEEP_RE = /^(package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|\.yarnrc\.yml|uv\.lock|poetry\.lock|pyproject\.toml|requirements.*\.txt|setup\.py|setup\.cfg|\.nvmrc|\.node-version|\.tool-versions|tsconfig.*\.json|forge\.yaml|\.gitattributes|\.gitignore)$/;
+
+/** Blobs to leave out, from `git ls-tree -r -l -z <ref>` output: {excludes, bytes}. Symlinks, gitlinks and kept files never. */
+export function sparsePlan(lsTree, { maxBlobBytes = DEFAULT_SPARSE_MAX_KB * 1024 } = {}) {
+  const excludes = [];
+  let bytes = 0;
+  if (!(maxBlobBytes > 0)) return { excludes, bytes };
+  for (const rec of String(lsTree ?? "").split("\0")) {
+    const m = /^(\d{6}) blob [0-9a-f]+ +(\d+)\t([\s\S]+)$/.exec(rec.replace(/^\n+/, ""));
+    if (!m || !["100644", "100755"].includes(m[1])) continue;
+    const size = Number(m[2]), path = m[3];
+    if (size < maxBlobBytes || /[\n\r]/.test(path) || KEEP_RE.test(path.split("/").at(-1))) continue;
+    excludes.push(path);
+    bytes += size;
+  }
+  return { excludes, bytes };
+}
+
+/** gitignore-syntax escape for a literal path: \ * ? [ anywhere, trailing spaces. */
+const esc = (p) => p.replace(/[\\*?[]| (?= *$)/g, (c) => `\\${c}`);
+
+/** Non-cone sparse patterns that include everything except `excludes`. */
+export function sparsePatterns(excludes) {
+  return ["/*", ...excludes.map((p) => `!/${esc(p)}`)];
+}
+
+/**
+ * Add a lane worktree, sparse when the plan is non-empty. `git(args, {cwd})` is the injected io.git; `write(path, text)`
+ * writes the pattern file (argv-safe for any number of patterns). `addArgs` is the plain `["worktree","add",...]` argv.
+ * A failing `worktree add` is rethrown unchanged (the caller retries lock races). Returns {sparse, excluded, bytes, fallback?}.
+ */
+export async function addLaneWorktree(git, write, { cwd, wt, addArgs, ref, maxBlobBytes = DEFAULT_SPARSE_MAX_KB * 1024 }) {
+  let plan = { excludes: [], bytes: 0 };
+  if (maxBlobBytes > 0 && typeof write === "function") {
+    try { plan = sparsePlan(await git(["ls-tree", "-r", "-l", "-z", ref], { cwd }), { maxBlobBytes }); } catch { /* no plan: full checkout */ }
+  }
+  if (!plan.excludes.length) {
+    await git(addArgs, { cwd });
+    return { sparse: false, excluded: 0, bytes: 0 };
+  }
+  await git([...addArgs.slice(0, 2), "--no-checkout", ...addArgs.slice(2)], { cwd });
+  const g = (a) => git(a, { cwd: wt });
+  try {
+    await g(["sparse-checkout", "set", "--no-cone", "/*"]);
+    const file = String(await g(["rev-parse", "--git-path", "info/sparse-checkout"])).trim();
+    await write(file.startsWith("/") ? file : join(wt, file), `${sparsePatterns(plan.excludes).join("\n")}\n`);
+    await g(["read-tree", "-mu", "HEAD"]);
+    return { sparse: true, excluded: plan.excludes.length, bytes: plan.bytes };
+  } catch (e) {
+    const reason = String(e?.stderr || e?.message || e).trim().split("\n").slice(-2).join(" ").slice(0, 300);
+    try { await g(["sparse-checkout", "disable"]); } catch { /* full read-tree below */ }
+    await g(["read-tree", "-mu", "HEAD"]);
+    return { sparse: false, excluded: 0, bytes: 0, fallback: reason || "sparse checkout failed" };
+  }
+}

package/bin/lean/worktree.test.mjs

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, readdirSync, statSync, existsSync, rmSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { join, dirname } from "node:path";
+import { sparsePlan, sparsePatterns, addLaneWorktree } from "./worktree.mjs";
+
+const MiB = 1024 * 1024;
+const gitSync = (args, cwd) => execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * MiB, stdio: ["ignore", "pipe", "pipe"] });
+const git = async (args, { cwd } = {}) => gitSync(args, cwd);
+const write = async (p, t) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, t); };
+const blob = (n, ch = "x") => ch.repeat(n);
+
+/** A fixture repo: {path: content}. Returns its dir. */
+function repo(files) {
+  const dir = tmpDir("wt4221-");
+  const r = join(dir, "r");
+  mkdirSync(r);
+  gitSync(["init", "-q", "-b", "main"], r);
+  for (const [p, c] of Object.entries(files)) { mkdirSync(dirname(join(r, p)), { recursive: true }); writeFileSync(join(r, p), c); }
+  gitSync(["add", "-A"], r);
+  gitSync(["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "init"], r);
+  return { dir, r, wt: join(dir, "wt") };
+}
+/** Bytes of regular files on disk under `d`, skipping .git. */
+function diskBytes(d) {
+  let n = 0;
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (e.name === ".git") continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) n += diskBytes(p); else if (e.isFile()) n += statSync(p).size;
+  }
+  return n;
+}
+
+const FIXTURES = {
+  "npm JS/TS": {
+    files: { "package.json": '{"name":"a","version":"1.0.0"}\n', "package-lock.json": `{"lockfileVersion":3,"pad":"${blob(MiB + 10)}"}\n`,
+      "tsconfig.json": "{}\n", "src/index.ts": "export const x = 1;\n", "public/asset.json": blob(2 * MiB) },
+    big: "public/asset.json", kept: ["package.json", "package-lock.json", "src/index.ts", "tsconfig.json"],
+  },
+  "uv Python": {
+    files: { "pyproject.toml": '[project]\nname = "a"\nversion = "0.1.0"\n', "uv.lock": `version = 1\n# ${blob(MiB + 10)}\n`,
+      "app/main.py": "print(1)\n", "data/blob.bin": blob(2 * MiB, "\u0001") },
+    big: "data/blob.bin", kept: ["pyproject.toml", "uv.lock", "app/main.py"],
+  },
+};
+
+describe("sparse lane worktrees (#4221)", () => {
+  for (const [name, fx] of Object.entries(FIXTURES)) {
+    it(`${name}: large blobs stay out, lockfiles and manifests stay in, git sees no change`, async () => {
+      const { dir, r, wt } = repo(fx.files);
+      try {
+        const res = await addLaneWorktree(git, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "feat/issue-1-lean", wt, "main"], ref: "main", maxBlobBytes: MiB });
+        assert.deepEqual(res, { sparse: true, excluded: 1, bytes: 2 * MiB });
+        assert.equal(existsSync(join(wt, fx.big)), false);
+        assert.match(gitSync(["ls-files", "-t", fx.big], wt), /^S /);
+        for (const k of fx.kept) assert.ok(existsSync(join(wt, k)), `${k} checked out`);
+        assert.equal(gitSync(["status", "--porcelain"], wt), "");
+        gitSync(["add", "-A"], wt);
+        assert.equal(gitSync(["diff", "--cached", "--name-only"], wt), "", "git add -A stages no deletion");
+        // R5: on-disk checkout is no more than the included blobs (+1 MiB slack): the left-out blob costs nothing.
+        const included = Object.entries(fx.files).filter(([p]) => p !== fx.big).reduce((n, [, c]) => n + Buffer.byteLength(c), 0);
+        assert.ok(diskBytes(wt) <= included + MiB, `disk ${diskBytes(wt)} <= ${included + MiB}`);
+        assert.throws(() => gitSync(["config", "--get", "core.sparseCheckout"], r), "main checkout has no core.sparseCheckout");
+        assert.equal(Object.keys(fx.files).every((p) => existsSync(join(r, p))), true);
+        mkdirSync(dirname(join(wt, fx.big)), { recursive: true });
+        writeFileSync(join(wt, fx.big), "regenerated\n");
+        assert.match(gitSync(["status", "--porcelain"], wt), new RegExp(` M ${fx.big}`));
+        gitSync(["checkout", "--", fx.big], wt);
+        gitSync(["sparse-checkout", "add", `/${fx.big}`], wt);
+        assert.equal(statSync(join(wt, fx.big)).size, 2 * MiB);
+      } finally { rmSync(dir, { recursive: true, force: true }); }
+    });
+  }
+
+  it("a repo with no large blob gets today's plain worktree add", async () => {
+    const { dir, r, wt } = repo({ "package.json": "{}\n", "src/a.js": "1\n" });
+    try {
+      const calls = [];
+      const spy = async (a, o) => { calls.push(a); return git(a, o); };
+      const addArgs = ["worktree", "add", "-B", "feat/issue-1-lean", wt, "main"];
+      assert.deepEqual(await addLaneWorktree(spy, write, { cwd: r, wt, addArgs, ref: "main" }), { sparse: false, excluded: 0, bytes: 0 });
+      assert.deepEqual(calls.filter((a) => a[0] === "worktree"), [addArgs]);
+      assert.equal(calls.some((a) => a[0] === "sparse-checkout"), false);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  it("maxBlobBytes 0 disables it; a failing sparse step falls back to a full checkout", async () => {
+    const { dir, r, wt } = repo({ "a.bin": blob(2 * MiB), "b.txt": "1\n" });
+    try {
+      const calls = [];
+      const spy = async (a, o) => { calls.push(a); return git(a, o); };
+      await addLaneWorktree(spy, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: 0 });
+      assert.equal(calls.some((a) => a[0] === "ls-tree" || a.includes("--no-checkout")), false);
+      assert.ok(existsSync(join(wt, "a.bin")));
+      gitSync(["worktree", "remove", "--force", wt], r);
+      const failing = async (a, o) => { if (a[0] === "read-tree" && !failing.done) { failing.done = true; throw Object.assign(new Error("boom"), { stderr: "fatal: boom" }); } return git(a, o); };
+      const res = await addLaneWorktree(failing, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: MiB });
+      assert.equal(res.sparse, false);
+      assert.match(res.fallback, /boom/);
+      assert.ok(existsSync(join(wt, "a.bin")) && existsSync(join(wt, "b.txt")));
+      assert.equal(gitSync(["status", "--porcelain"], wt), "");
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  it("a failing worktree add is rethrown unchanged (the caller retries lock races)", async () => {
+    const e = Object.assign(new Error("lock"), { stderr: "could not lock config file" });
+    const g = async (a) => { if (a[0] === "worktree") throw e; return "100644 blob " + "a".repeat(40) + " 2000000\tbig.bin\0"; };
+    await assert.rejects(addLaneWorktree(g, write, { cwd: "/x", wt: "/x/wt", addArgs: ["worktree", "add", "/x/wt", "main"], ref: "main" }), (x) => x === e);
+  });
+
+  it("sparsePlan: threshold, keep-list, symlinks and gitlinks; patterns escape glob characters", () => {
+    const h = "a".repeat(40);
+    const out = [
+      `100644 blob ${h} 2000000\tweb/openapi.json`, `100755 blob ${h} 1048576\tbin/tool`, `100644 blob ${h}  1048575\tsmall.txt`,
+      `120000 blob ${h}      40\tlink`, `160000 commit ${h}       -\tsub`, `100644 blob ${h} 3000000\tpnpm-lock.yaml`,
+      `100644 blob ${h} 3000000\tsvc/requirements-dev.txt`, `100644 blob ${h} 3000000\tpkg/tsconfig.base.json`, `100644 blob ${h} 5000000\ta [x]*?.bin `,
+    ].join("\0") + "\0";
+    const p = sparsePlan(out, { maxBlobBytes: MiB });
+    assert.deepEqual(p.excludes, ["web/openapi.json", "bin/tool", "a [x]*?.bin "]);
+    assert.equal(p.bytes, 2000000 + 1048576 + 5000000);
+    assert.deepEqual(sparsePlan(out, { maxBlobBytes: 0 }).excludes, []);
+    assert.deepEqual(sparsePatterns(p.excludes), ["/*", "!/web/openapi.json", "!/bin/tool", "!/a \\[x]\\*\\?.bin\\ "]);
+  });
+
+  it("an escaped pattern really matches its odd path", async () => {
+    const odd = "d/a [x]*?.bin";
+    const { dir, r, wt } = repo({ [odd]: blob(2 * MiB), "d/a x.bin": "keep\n", "f.txt": "1\n" });
+    try {
+      const res = await addLaneWorktree(git, write, { cwd: r, wt, addArgs: ["worktree", "add", "-B", "lane", wt, "main"], ref: "main", maxBlobBytes: MiB });
+      assert.equal(res.sparse, true);
+      assert.equal(existsSync(join(wt, odd)), false);
+      assert.ok(existsSync(join(wt, "d/a x.bin")));
+      assert.equal(gitSync(["status", "--porcelain"], wt), "");
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+});

package/bin/runner.mjs

@@ -359,6 +359,37 @@ export function resolveConfiguredDefaultModel(cwd) {
   }
 }
 
+/**
+ * Whether the owner approved the paid API backend as the `auto` fallback (#4257).
+ * Needs both forge.yaml `execution.agent_backend: api` in `cwd` (repo owner) and
+ * env `FORGEDOCK_ALLOW_API_BACKEND=1` (host owner), so a committed config edit
+ * alone cannot start billing an API key. Never throws.
+ *
+ * @param {{cwd?: string, env?: object}} [opts]
+ * @returns {boolean}
+ */
+export function isApiBackendApproved({ cwd = process.cwd(), env = process.env } = {}) {
+  if (String(env?.FORGEDOCK_ALLOW_API_BACKEND ?? "").trim() !== "1") return false;
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return false;
+    return parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.execution?.agent_backend === "api";
+  } catch {
+    return false;
+  }
+}
+
+/** #4257: typed error when `auto` finds no usable CLI and the API backend is not approved. */
+function cliUnavailableError(detail = "The claude CLI is not available") {
+  const err = new Error(
+    `${detail}, and the API backend is never used implicitly. Install and authenticate the \`claude\` CLI, ` +
+      "or opt in to the API backend (forge.yaml `execution.agent_backend: api` plus FORGEDOCK_ALLOW_API_BACKEND=1), " +
+      "or pass --backend api.",
+  );
+  err.code = "CLI_BACKEND_UNAVAILABLE";
+  return err;
+}
+
 /**
  * Resolve the CLI backend timeout from forge.yaml's
  * `pipeline.cli_timeout_minutes` field, if it is a positive integer.
@@ -854,6 +885,7 @@ export function checkExecutionBackend({
   apiKey = env.ANTHROPIC_API_KEY,
   resolveCliFn = resolveClaudeCliBinary,
   spawnImpl = spawnSync,
+  apiApproved = isApiBackendApproved({ cwd, env }),
   sdkAvailableFn = () => {
     try {
       createRequire(import.meta.url).resolve("@anthropic-ai/sdk");
@@ -884,7 +916,8 @@ export function checkExecutionBackend({
         return { ready: true, backend: "cli", reason: "resolved-cli" };
       }
     }
-    if (requested === "cli") {
+    // #4257: auto never crosses to the paid API backend without the owner's opt-in.
+    if (requested === "cli" || !apiApproved) {
       return { ready: false, backend: "cli", reason: "cli-unavailable" };
     }
   }
@@ -905,7 +938,8 @@ export function checkExecutionBackend({
  * CLI and prefer it when present — but diverge on (a) which override
  * values are valid and whether an invalid one throws or is silently
  * ignored, and (b) what to return when the CLI probe fails (`resolveBackend`
- * always falls back to `"api"`; `resolveEnrichBackend` falls back to `"api"`
+ * falls back to `"api"` only with the owner's opt-in, else `"cli"` (#4257);
+ * `resolveEnrichBackend` falls back to `"api"`
  * only if `ANTHROPIC_API_KEY` is set, else `"none"`). Rather than force
  * those into one shape, this shared helper implements exactly the common
  * two steps and defers to a `cliFallback` callback for the diverging tail,
@@ -954,24 +988,27 @@ export function resolveBackendLadder({
  *   2. `"auto"` (the default) probes `isClaudeCliAvailable()`: prefers the
  *      CLI backend when a working `claude` install is detected (reuses
  *      whatever credentials the CLI already has — Pro/Max OAuth or a
- *      CLI-managed key — with no ANTHROPIC_API_KEY required), otherwise
- *      falls back to the API backend unchanged (existing behavior for every
- *      caller that never opts in to this feature).
+ *      CLI-managed key — with no ANTHROPIC_API_KEY required). Without a CLI it
+ *      falls back to the API backend ONLY when the owner opted in
+ *      (`isApiBackendApproved()`, #4257); otherwise it returns `"cli"` and
+ *      `runCommand()` fails with a typed `CLI_BACKEND_UNAVAILABLE`. The API
+ *      backend is never the implicit default.
  *
  * Delegates its shared "override-or-probe-CLI" shape to
  * `resolveBackendLadder()` (issue #2026) — this function retains its own
  * `VALID_BACKENDS` throw-on-invalid check (NOT shared; see that helper's
- * doc comment) and its own no-API-key-check fallback (always `"api"`,
- * unconditionally — the API key itself is validated lazily downstream, only
+ * doc comment) and its own opt-in-gated fallback (`"api"` only when
+ * approved — the API key itself is validated lazily downstream, only
  * if/when the api backend is actually selected).
  *
  * @param {object} [opts]
  * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
  * @param {string} [opts.cwd]       - Working directory for the CLI probe.
  * @param {object} [opts.env]       - Runtime environment used for capability checks.
+ * @param {Function} [opts.isCliAvailableFn] - Injectable CLI-presence probe (test seam).
  * @returns {"cli"|"api"}
  */
-export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env } = {}) {
+export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env, isCliAvailableFn = isClaudeCliAvailable } = {}) {
   if (!VALID_BACKENDS.has(requested)) {
     throw new Error(
       `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
@@ -982,7 +1019,8 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd(), env =
     override: requested === "auto" ? undefined : requested,
     validOverrides: new Set(["cli", "api"]),
     cwd,
-    cliFallback: () => "api",
+    isCliAvailableFn,
+    cliFallback: () => (isApiBackendApproved({ cwd, env }) ? "api" : "cli"),
   });
 }
 
@@ -2789,7 +2827,9 @@ export function renderSummaryCard(ctx) {
  * @param {string} [opts.backend]            - "cli" | "api" | "auto" (default
  *   "auto"). Resolution order when omitted: $FORGEDOCK_BACKEND env > "auto".
  *   "auto" prefers the local Claude Code CLI when detected (no
- *   ANTHROPIC_API_KEY needed), else falls back to the API backend. This
+ *   ANTHROPIC_API_KEY needed); without a CLI it uses the API backend only
+ *   with the owner's opt-in (`isApiBackendApproved()`, #4257), else it fails
+ *   with a typed CLI_BACKEND_UNAVAILABLE — api is never the default. This
  *   precedence is intentional/shipped (issue #2003's accepted acceptance
  *   criteria) and is NOT changed by issue #2020 — that issue only adds a
  *   discoverability notice (below) for the case where the ladder silently
@@ -2840,6 +2880,7 @@ export async function runCommand(opts = {}) {
 
   if (resolvedBackend === "cli" && backend === "auto") {
     const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
+    // #4257: readiness only reports api when the owner approved it.
     if (readiness.backend === "api") resolvedBackend = "api";
   }
 
@@ -2938,6 +2979,8 @@ export async function runCommand(opts = {}) {
       sessionFlags = buildMinimalSessionFlags(commandName, caps);
     }
     if (!resolvedBin && backend === "auto") {
+      // #4257: never cross to the paid API backend without the owner's opt-in.
+      if (!isApiBackendApproved({ cwd, env: runtimeEnv })) throw cliUnavailableError();
       resolvedBackend = "api";
     } else if (!resolvedBin) {
       const err = new Error("The configured claude CLI path disappeared before invocation.");

package/bin/stats/github-source.mjs

@@ -163,7 +163,7 @@ async function* listIssuePages(gh, repo, startSince) {
 }
 
 const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), createdAt: it.created_at ?? null, closedAt: it.closed_at ?? null,
-  updatedAt: it.updated_at ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
+  updatedAt: it.updated_at ?? null, milestone: it.milestone?.title ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
 
 const CHECKPOINT_EVERY = 1000;
 const RATE_CHECK_EVERY = 50;

package/bin/stats/index.mjs

@@ -13,6 +13,7 @@ import { aggregate, DEFAULT_MIN_N } from "./aggregate.mjs";
 import { fetchGithubRecords, isValidRepo, toModel } from "./github-source.mjs";
 import { readLocalRuns, runsDir } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
+import { edgeQuery, parseEdge, verdictMix, contextPackAb, renderContextAb } from "./query.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -34,10 +35,18 @@ delta against the previous version and a low-n flag for samples under 10. Missin
   --min-n N             low-n threshold (default ${DEFAULT_MIN_N})
   --release-times FILE  "<version> <epoch-seconds>" lines used to estimate versions of unversioned records
                         (default: git tags v* of the ForgeDock checkout)
+
+Audit queries (forge#4165; JSON, from structure_delta / run_terminal telemetry, no comment bodies read):
+  --edge FROM:TO        merged PRs that added the dependency or import edge FROM -> TO (e.g. @s/web:@s/db)
+  --milestone M         conformance verdict mix and per-day structure series for milestone M
+
+Context-pack A/B (forge#4275; local run logs only, no GitHub crawl):
+  --context-ab          first-pass yield, builder turns, cache tokens and cost per lane type (rerun, child,
+                        first) and context_pack mode (on, off, shadow); --json for JSON
 `;
 
 export function parseArgs(argv) {
-  const o = { since: null, repo: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const o = { since: null, repo: null, edge: null, milestone: null, contextAb: false, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
   const val = (i, name) => {
     const v = argv[i + 1];
     if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
@@ -51,6 +60,9 @@ export function parseArgs(argv) {
     if (name === "--since") o.since = take();
     else if (name === "--repo") o.repo = take();
     else if (name === "--release-times") o.releaseTimes = take();
+    else if (name === "--edge") { const v = take(); if (!parseEdge(v)) throw new Error("--edge must be FROM:TO"); o.edge = v; }
+    else if (name === "--milestone") o.milestone = take();
+    else if (name === "--context-ab") o.contextAb = true;
     else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
     else if (name === "--json") o.json = true;
     else if (name === "--refresh") o.refresh = true;
@@ -149,10 +161,19 @@ export async function buildReport(opts, deps = {}) {
   if (opts.releaseTimes) releaseTimes = parseReleaseTimes(readFileSync(opts.releaseTimes, "utf8"));
   else if (deps.releaseTimes) releaseTimes = deps.releaseTimes;
   else releaseTimes = gitTagTimes();
+  if (opts.contextAb) { // forge#4275: run logs only
+    const runs = (deps.localRuns ?? readLocalRuns(runsDir(env))).filter((r) => r.repo == null || r.repo === repo);
+    return { repo, sources: { local: { runs: runs.length } }, query: { context_ab: contextPackAb(runs) } };
+  }
   const bound = sinceToTimestamp(opts.since, releaseTimes);
   if (bound.note) (deps.warn ?? ((m) => process.stderr.write(`forgedock stats: ${m}\n`)))(bound.note);
   const gh = await fetchGithubRecords({ repo, since: bound.since, refresh: opts.refresh, useCache: opts.cache, gh: deps.gh, env,
     onProgress: deps.onProgress, sleep: deps.sleep, now: deps.now });
+  if (opts.edge || opts.milestone) { // forge#4165: audit query instead of the version report
+    const e = opts.edge ? parseEdge(opts.edge) : null;
+    const query = { ...(e ? { edge: { ...e, prs: edgeQuery(gh.records, e.from, e.to) } } : {}), ...(opts.milestone ? { mix: verdictMix(gh.records, gh.items, opts.milestone) } : {}) };
+    return { repo, sources: { github: { items: gh.items.length, records: gh.records.length, cached: gh.fromCache } }, query };
+  }
   const model = toModel(repo, gh);
   const ghKeys = new Set(model.runs.map((r) => `${r.repo}#${r.issue}`));
   let local = [];
@@ -178,7 +199,8 @@ export async function runStats(argv, deps = {}) {
   }
   try {
     const report = await buildReport(opts, { onProgress: makeProgressPrinter(), ...deps });
-    process.stdout.write(`${opts.json ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
+    if (report.query?.context_ab && !opts.json) { process.stdout.write(`${renderContextAb(report.query.context_ab)}\n`); return 0; }
+    process.stdout.write(`${opts.json || report.query ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
     return 0;
   } catch (err) {
     process.stderr.write(`forgedock stats: ${err.message}\n`);

package/bin/stats/local-source.mjs

@@ -50,6 +50,13 @@ export function summariseLog(events, fallbackIssue = null) {
     if (attempt && Number.isFinite(e.cost_usd)) p.usd = (p.usd ?? 0) + e.cost_usd;
   }
   const finished = t >= 0 && (r < 0 || t > r);
+  // forge#4275: the context-pack A/B inputs. Builder calls log as phase "implement" (the plan call is the first).
+  const term = finished ? ev[t] : null;
+  const cp = [...ev].reverse().find((e) => e.event === "CONTEXT_PACK");
+  const usage = ev.filter((e) => e.event === "PHASE_ATTEMPT_USAGE");
+  const builderCalls = usage.filter((e) => e.phase === "implement");
+  const reviewCalls = usage.filter((e) => e.phase === "review").length;
+  const contextPack = { mode: term?.context_pack ?? cp?.mode ?? "off", laneType: term?.lane_type ?? cp?.lane_type ?? null };
   const startTs = start.ts ?? null;
   const endTs = finished ? ev[t].ts ?? null : null;
   const a = Date.parse(startTs ?? ""); const b = Date.parse(endTs ?? "");
@@ -60,6 +67,12 @@ export function summariseLog(events, fallbackIssue = null) {
     remediated: ev.some((e) => e.event === "PHASE_COMMIT" && e.phase === "remediate"),
     startTs, endTs, wallMs: finished && !Number.isNaN(a) && !Number.isNaN(b) ? Math.max(0, b - a) : null,
     phases,
+    contextPack,
+    builderTurns: builderCalls.reduce((x, e) => x + n(e.turns), 0),
+    cacheTokens: usage.reduce((x, e) => x + n(e.usage?.cache_read_input_tokens) + n(e.usage?.cache_creation_input_tokens), 0),
+    costUsd: usage.reduce((x, e) => x + n(e.cost_usd), 0),
+    // first pass: merged off one plan + one implement call, at most one review, no CI fix round
+    firstPass: finished && term?.reason === "merged" && builderCalls.length <= 2 && reviewCalls <= 1 && !ev.some((e) => e.event === "CI_FIX_ROUND"),
   };
 }
 

package/bin/stats/query.mjs

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4165: deterministic audit queries over FORGE:TELEMETRY records, so `/audit` answers "which PRs added A→B?" and
+ * "what is the conformance verdict mix for milestone M?" from structured events instead of comment archaeology.
+ * Inputs are the records and issue metadata `fetchGithubRecords` already returns; no extra API call, no model.
+ *   structure_delta (lean, merge-time): deps_added / new_edges / removed_edges as "from:to" comma lists, pr, milestone
+ *   run_terminal: reason, pr, milestone, conformance_mode, shadow_would
+ */
+
+const list = (v) => (typeof v === "string" && v !== "none" ? v.split(",").filter(Boolean) : []);
+const day = (ts) => (typeof ts === "string" ? ts.slice(0, 10) : "unknown");
+
+/** "from:to" -> {from, to}; package names hold no ":" so the last ":" splits (a scoped name keeps its "/"). */
+export function parseEdge(s) {
+  const i = String(s ?? "").lastIndexOf(":");
+  if (i <= 0 || i === String(s).length - 1) return null;
+  return { from: String(s).slice(0, i), to: String(s).slice(i + 1) };
+}
+
+/**
+ * Milestone of a record: its issue's milestone from the crawled metadata (the exact title), else the record's own field
+ * (the emitter replaces characters outside [A-Za-z0-9 _.:/#@+=,-] with "_", so it may differ from the title).
+ */
+function milestoneOf(r, byIssue) {
+  return byIssue.get(r.issue)?.milestone ?? (typeof r.milestone === "string" && r.milestone ? r.milestone : null);
+}
+
+/**
+ * PRs (and issues) whose merged change added the edge from→to: `kind` "package" (a package.json dependency) or
+ * "import" (value imports). Oldest first; one row per issue and kind (the latest record wins).
+ */
+export function edgeQuery(records, from, to) {
+  const key = `${from}:${to}`;
+  const rows = new Map();
+  for (const r of records) {
+    if (r?.event !== "structure_delta") continue;
+    for (const [field, kind] of [["deps_added", "package"], ["new_edges", "import"]]) {
+      if (!list(r[field]).includes(key)) continue;
+      const k = `${r.issue}\u0000${kind}`;
+      const prev = rows.get(k);
+      if (!prev || String(r.ts ?? "") >= String(prev.ts ?? "")) rows.set(k, { issue: r.issue ?? null, pr: r.pr ?? null, ts: r.ts ?? null, kind, milestone: r.milestone ?? null });
+    }
+  }
+  return [...rows.values()].sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")) || (a.issue ?? 0) - (b.issue ?? 0));
+}
+
+/**
+ * Conformance verdict mix of finished runs (run_terminal) and the per-day structure series (structure_delta), for one
+ * milestone or, with `milestone` null, for the whole repo. `items` is the crawled issue metadata ({number, milestone}).
+ */
+export function verdictMix(records, items = [], milestone = null) {
+  const byIssue = new Map(items.map((i) => [i.number, i]));
+  const sel = (r) => milestone == null || milestoneOf(r, byIssue) === milestone;
+  const terms = records.filter((r) => r?.event === "run_terminal" && sel(r));
+  const count = (xs, f) => xs.reduce((m, x) => { const k = f(x); if (k != null) m[k] = (m[k] ?? 0) + 1; return m; }, {});
+  const series = new Map();
+  for (const r of records) {
+    if (r?.event !== "structure_delta" || r.phase !== "merge" || !sel(r)) continue;
+    const d = day(r.ts);
+    const s = series.get(d) ?? { date: d, merged: 0, deps_added: 0, new_edges: 0, removed_edges: 0 };
+    s.merged++; s.deps_added += list(r.deps_added).length; s.new_edges += list(r.new_edges).length; s.removed_edges += list(r.removed_edges).length;
+    series.set(d, s);
+  }
+  return {
+    milestone, runs: terms.length,
+    verdicts: count(terms, (r) => (typeof r.shadow_would === "string" ? r.shadow_would : null)),
+    modes: count(terms, (r) => (typeof r.conformance_mode === "string" ? r.conformance_mode : null)),
+    reasons: count(terms, (r) => (typeof r.reason === "string" ? r.reason : null)),
+    series: [...series.values()].sort((a, b) => a.date.localeCompare(b.date)),
+  };
+}
+
+/**
+ * forge#4275: the context-pack A/B over local run summaries (local-source.mjs summariseLog), per lane type (rerun,
+ * child, first) and mode (on, off, shadow), never one blended average. First-pass yield: merged with one plan + one
+ * implement builder call and at most one review. Runs without a recorded lane type (older logs) are left out.
+ */
+export const CONTEXT_LANE_TYPES = Object.freeze(["rerun", "child", "first"]);
+export function contextPackAb(runs) {
+  const out = {};
+  const mean = (xs) => (xs.length ? Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 1e4) / 1e4 : null);
+  for (const lt of CONTEXT_LANE_TYPES) {
+    out[lt] = {};
+    for (const mode of ["on", "off", "shadow"]) {
+      const rs = runs.filter((r) => r?.finished && r.contextPack?.laneType === lt && r.contextPack?.mode === mode);
+      out[lt][mode] = { n: rs.length, first_pass_yield: mean(rs.map((r) => (r.firstPass ? 1 : 0))), builder_turns: mean(rs.map((r) => r.builderTurns ?? 0)),
+        cache_tokens: mean(rs.map((r) => r.cacheTokens ?? 0)), cost_usd: mean(rs.map((r) => r.costUsd ?? 0)) };
+    }
+  }
+  return out;
+}
+
+/** Markdown table for contextPackAb. */
+export function renderContextAb(ab) {
+  const f = (v) => (v == null ? "n/a" : String(v));
+  const rows = CONTEXT_LANE_TYPES.flatMap((lt) => ["on", "off", "shadow"].map((m) => { const g = ab[lt][m]; return `| ${lt} | ${m} | ${g.n} | ${f(g.first_pass_yield)} | ${f(g.builder_turns)} | ${f(g.cache_tokens)} | ${f(g.cost_usd)} |`; }));
+  return `| Lane type | Mode | n | First-pass yield | Builder turns | Cache tokens | Cost USD |\n| --- | --- | --- | --- | --- | --- | --- |\n${rows.join("\n")}`;
+}