forgedock 1.17.0 → 1.19.0

package/bin/hooks/pre-tool-use.mjs

@@ -116,14 +116,12 @@ async function getInvariants() {
  *    starting Claude Code (operator-set only — same process.env semantics as
  *    the gist guard above).
  *
- * 9. Main-checkout mutation guard (issue #3650) — ADVISORY by default
- *    Enforced (exit 2) only when FORGE_ENFORCE_MAIN_CHECKOUT_GIT=1. Otherwise it
- *    writes a warning to stderr and allows the call: shipped specs (fix-ci,
- *    milestone, test-gate, cleanup, rollback, recover-orphans, spec-doctor,
- *    orchestrate phase-4) still run these verbs in the main checkout on purpose,
- *    and a denial blocks the whole Bash call (their `|| true` fallbacks never run).
- *    Enforcement becomes the default once those specs use worktrees (#3873).
- *    When enforced it denies `git checkout|switch|stash|merge`, `git reset --hard`, and
+ * 9. Main-checkout mutation guard (issue #3650) — enforced by default
+ *    Enforced (exit 2) unless FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0, which downgrades it
+ *    to a stderr warning (#3873). Ref-only verbs are narrowed: `git branch -d/-D/-m/-f`
+ *    is denied only for the branch checked out in the target dir, and
+ *    `git restore --staged` (index only) is allowed.
+ *    It denies `git checkout|switch|stash|merge`, `git reset --hard`, and
  *    `gh pr checkout` when the shell's cwd is the main (non-worktree) checkout
  *    (`git rev-parse --git-dir` equals `--git-common-dir`). Pipeline workers and
  *    reviewers share that tree with the operator; mutating it races with them.
@@ -589,12 +587,12 @@ async function main() {
   // forge.yaml), and `git -C <main> ...` from there is the case this rule exists for.
   const mainCheckoutViolation = checkMainCheckoutMutation(command);
   if (mainCheckoutViolation) {
-    if (process.env.FORGE_ENFORCE_MAIN_CHECKOUT_GIT === "1") {
+    if (process.env.FORGE_ENFORCE_MAIN_CHECKOUT_GIT !== "0") {
       process.stderr.write(mainCheckoutViolation);
       process.exit(2);
       return;
     }
-    // Advisory (default): several shipped specs still mutate the main checkout on purpose (#3873).
+    // Advisory only when the operator opts out with FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0 (#3873).
     process.stderr.write("WARNING (advisory, not blocked): " + mainCheckoutViolation.replace(/^BLOCKED: /, ""));
   }
 
@@ -1304,9 +1302,11 @@ function mutatingGitCommand(tokens, depth = 0) {
       const k = w === "eval" ? i + 1 : tokens.findIndex((t, n) => n > i && /^-[a-z]*c$/.test(t)) + 1;
       if (k <= i || k >= tokens.length) return null;
       const inner = w === "eval" ? tokens.slice(k).join(" ") : tokens[k];
-      let hit = null;
-      for (const seg of extractCommandSegments(inner)) hit = hit || mutatingGitCommand(seg, depth + 1);
-      return hit;
+      // Every hit of the payload, not just the first (#3920): an allowed ref-only segment (`git branch -d other`)
+      // must not mask a later mutating one. The caller decides per hit.
+      const hits = [];
+      for (const seg of extractCommandSegments(inner)) hits.push(...mutatingGitHits(seg, depth + 1));
+      return hits.length ? { name: hits[0].name, dir: hits[0].dir, hits } : null;
     }
     break;
   }
@@ -1338,12 +1338,27 @@ function mutatingGitCommand(tokens, depth = 0) {
       return opts.some((t) => t === "-b") ? null : hit("git checkout");
     case "switch":
       return opts.some((t) => t === "-c" || t === "--create") ? null : hit("git switch");
-    case "merge": case "pull": case "rebase": case "cherry-pick": case "revert": case "am": case "restore":
+    case "merge": case "pull": case "rebase": case "cherry-pick": case "revert": case "am":
       return hit(`git ${sub}`);
+    case "restore": {
+      // `restore --staged` only rewrites the index (not the working tree); anything else (or --worktree/-W) does.
+      const flag = (long, ch) => opts.some((t) => t === long || (/^-[a-zA-Z]+$/.test(t) && t.includes(ch)));
+      return flag("--worktree", "W") || !flag("--staged", "S") ? hit("git restore") : null;
+    }
     case "clean":
       return opts.some((t) => t === "-n" || t === "--dry-run") ? null : hit("git clean");
-    case "branch":
-      return opts.some((t) => /^(?:-[a-zA-Z]*[fFmMdD][a-zA-Z]*|--force|--move|--delete)$/.test(t)) ? hit("git branch") : null;
+    case "branch": {
+      // Ref-only verbs: a hit only when the delete/move/force target is the branch checked out at the
+      // target dir (resolved by the caller). `-m <new>` with one positional renames the current branch.
+      if (!opts.some((t) => /^(?:-[a-zA-Z]*[fFmMdD][a-zA-Z]*|--force|--move|--delete)$/.test(t))) return null;
+      // Positionals after `--` count too (`git branch -m -- renamed` renames the checked-out branch, #3920).
+      const pos = [...opts.filter((t) => !t.startsWith("-")), ...(dd >= 0 ? rest.slice(dd + 1) : [])];
+      if (!pos.length) return null;
+      const moves = opts.some((t) => t === "--move" || /^-[a-zA-Z]*[mM][a-zA-Z]*$/.test(t));
+      const deletes = opts.some((t) => t === "--delete" || /^-[a-zA-Z]*[dD][a-zA-Z]*$/.test(t));
+      const branches = moves && !deletes ? (pos.length === 1 ? ["@current"] : [pos[0]]) : deletes ? pos : [pos[0]];
+      return { name: "git branch", dir, branches };
+    }
     case "reset":
       return opts.some((t) => t === "--hard" || t === "--merge" || t === "--keep") ? hit("git reset") : null;
     case "stash": {
@@ -1355,6 +1370,18 @@ function mutatingGitCommand(tokens, depth = 0) {
   }
 }
 
+/**
+ * All main-checkout mutation hits in one command segment, flattening `bash -c` / `eval` payloads (#3920).
+ * @param {string[]} tokens
+ * @param {number} [depth]
+ * @returns {Array<{name: string, dir: string|null, branches?: string[]}>}
+ */
+function mutatingGitHits(tokens, depth = 0) {
+  const h = mutatingGitCommand(tokens, depth);
+  if (!h) return [];
+  return h.hits ? h.hits : [h];
+}
+
 /**
  * Is `cwd` the main (non-linked-worktree) checkout of a git repo?
  * Fails closed-to-allow: any error or non-git dir returns false.
@@ -1386,9 +1413,8 @@ function checkMainCheckoutMutation(command) {
   if (process.env.FORGE_ALLOW_MAIN_CHECKOUT_GIT === "1") return null;
   if (!/\b(?:git|gh)\b/.test(command)) return null;
   try {
-    let offender = null;
     let baseDir = process.cwd();
-    let targetDir = baseDir;
+    // Decide per segment: an allowed ref-only verb (`git branch -d other`) must not mask a later mutating segment.
     for (const tokens of extractCommandSegments(command)) {
       const head = tokens.slice();
       while (head.length && (/^[({]+$/.test(head[0]) || ["then", "do", "else", "!"].includes(head[0]))) head.shift();
@@ -1400,21 +1426,28 @@ function checkMainCheckoutMutation(command) {
         baseDir = resolvePath(baseDir, t);
         continue;
       }
-      const hit = mutatingGitCommand(tokens);
-      if (hit) { offender = hit.name; targetDir = hit.dir === null ? baseDir : resolvePath(baseDir, hit.dir); break; }
+      for (const hit of mutatingGitHits(tokens)) {
+      const targetDir = hit.dir === null ? baseDir : resolvePath(baseDir, hit.dir);
+      if (!isMainCheckout(targetDir)) continue;
+      if (hit.branches) {
+        // Ref-only verb: only the checked-out branch matters; unresolvable (detached HEAD, error) = allow.
+        const cur = spawnSync("git", ["-C", targetDir, "branch", "--show-current"], { encoding: "utf-8", timeout: 5000 });
+        const current = cur.status === 0 ? String(cur.stdout).trim() : "";
+        if (!current || !hit.branches.some((b) => b === "@current" || b === current)) continue;
+      }
+      // Hook is global: only protect ForgeDock-managed main checkouts (issue #1591 scoping), never unrelated repos.
+      if (!existsSync(join(targetDir, "forge.yaml")) && !existsSync(join(targetDir, ".forgedock"))) continue;
+      return (
+        `BLOCKED: \`${hit.name}\` would mutate the main checkout (${targetDir}).\n` +
+        "The main checkout is shared with the operator and other agents. Work in a git worktree " +
+        "(`git worktree list`, `git worktree add`) and use `git -C <worktree> ...`, or read code with " +
+        "`git show <sha>:<path>`, `gh pr diff`, or `gh api`.\n" +
+        "Operator override: set FORGE_ALLOW_MAIN_CHECKOUT_GIT=1 in the shell before starting Claude Code " +
+        "(set FORGE_ENFORCE_MAIN_CHECKOUT_GIT=0 to make this advisory only).\n"
+      );
+      }
     }
-    if (!offender) return null;
-    if (!isMainCheckout(targetDir)) return null;
-    // Hook is global: only protect ForgeDock-managed main checkouts (issue #1591 scoping), never unrelated repos.
-    if (!existsSync(join(targetDir, "forge.yaml")) && !existsSync(join(targetDir, ".forgedock"))) return null;
-    return (
-      `BLOCKED: \`${offender}\` would mutate the main checkout (${targetDir}).\n` +
-      "The main checkout is shared with the operator and other agents. Work in a git worktree " +
-      "(`git worktree list`, `git worktree add`) and use `git -C <worktree> ...`, or read code with " +
-      "`git show <sha>:<path>`, `gh pr diff`, or `gh api`.\n" +
-      "Operator override: set FORGE_ALLOW_MAIN_CHECKOUT_GIT=1 in the shell before starting Claude Code " +
-      "(enforcement itself is opt-in: FORGE_ENFORCE_MAIN_CHECKOUT_GIT=1).\n"
-    );
+    return null;
   } catch {
     return null; // fail open
   }

package/bin/runner.mjs

@@ -47,8 +47,11 @@ import {
   mkdtempSync,
   rmSync,
   realpathSync,
+  lstatSync,
+  chmodSync,
 } from "fs";
-import { join, dirname, basename, relative, isAbsolute, extname, win32 as win32Path } from "path";
+import { createHash } from "crypto";
+import { join, dirname, basename, resolve, relative, isAbsolute, extname, win32 as win32Path } from "path";
 import os from "os";
 import { execSync, spawnSync } from "child_process";
 import { createRequire } from "module";
@@ -74,6 +77,89 @@ export function withForgedockHome(env) {
   return env;
 }
 
+/** Expand a leading `~` and require an absolute result; anything else -> null. */
+function absoluteTmpRoot(value) {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (!v) return null;
+  const expanded = v === "~" || v.startsWith("~/") ? join(os.homedir(), v.slice(1)) : v;
+  return isAbsolute(expanded) ? expanded : null;
+}
+
+/**
+ * Root of the per-run scratch dirs (forge#3572). Precedence: forge.yaml `engine.tmp_root`
+ * (absolute or `~`-prefixed), else null when the operator exported their own
+ * CLAUDE_CODE_TMPDIR/TMPDIR (their choice is respected and never cleaned), else `~/.forge/tmp`.
+ * A null return means "operator-managed: leave the child env untouched".
+ *
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function resolveRunTmpRoot(cwd, env = process.env) {
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (existsSync(forgeYamlPath)) {
+      const configured = absoluteTmpRoot(parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.engine?.tmp_root);
+      if (configured) return configured;
+    }
+  } catch { /* unreadable config: fall through to the defaults */ }
+  if (env.CLAUDE_CODE_TMPDIR || env.TMPDIR) return null;
+  return join(os.homedir(), ".forge", "tmp");
+}
+
+/**
+ * Stable, path-safe identity of the repo checkout: `<sanitized basename>-<8 hex of sha1(realpath)>`.
+ * Local only (no network), identical across a `--retry` from the same checkout, distinct per checkout.
+ * Never empty, never `.`/`..`, never contains a path separator.
+ */
+export function repoKey(cwd = process.cwd()) {
+  let real;
+  try { real = realpathSync(cwd); } catch { real = resolve(String(cwd)); }
+  const name = basename(real).replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "") || "repo";
+  return `${name}-${createHash("sha1").update(real).digest("hex").slice(0, 8)}`;
+}
+
+/** `<root>/<repoKey>/<issue>` for a numeric issue; null for an empty root or non-numeric issue (no path-escape, never the root). */
+export function runTmpDir(root, issue, cwd = process.cwd()) {
+  const id = String(issue ?? "").trim();
+  return root && /^[0-9]+$/.test(id) ? join(root, repoKey(cwd), id) : null;
+}
+
+/** True when `p` is a real directory (not a symlink) owned by the current uid (uid check skipped where unavailable). */
+function isOwnedRealDir(p) {
+  const st = lstatSync(p);
+  if (!st.isDirectory() || st.isSymbolicLink()) return false;
+  return typeof process.getuid !== "function" || st.uid === process.getuid();
+}
+
+/**
+ * Point TMPDIR and CLAUDE_CODE_TMPDIR at a per-run, disk-backed dir so venvs and Claude session data
+ * stay off a size-limited /tmp. The dir is repo-scoped and created 0700; an existing dir that is a symlink
+ * or owned by another uid is not used. No-op when the issue is unknown or the operator owns the tmp root.
+ * Best-effort: any failure leaves the env unchanged.
+ */
+export function withRunTmpdir(env, { issue, cwd = process.cwd() } = {}) {
+  const dir = runTmpDir(resolveRunTmpRoot(cwd, env), issue, cwd);
+  if (!dir) return env;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const parent = dirname(dir);
+    for (const d of [parent, dir]) {
+      if (!isOwnedRealDir(d)) return env;
+      chmodSync(d, 0o700);
+    }
+    env.TMPDIR = dir;
+    env.CLAUDE_CODE_TMPDIR = dir;
+  } catch { /* scratch stays on the inherited tmp */ }
+  return env;
+}
+
+/** First positional arg when it is an issue number (the phase arg convention), else null. */
+function issueFromArgs(args) {
+  const first = Array.isArray(args) ? args[0] : String(args ?? "").trim().split(/\s+/)[0];
+  return /^[0-9]+$/.test(String(first ?? "")) ? String(first) : null;
+}
+
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_MAX_TOKENS = 16384;
@@ -1410,7 +1496,7 @@ export function runCliBackend({
     // Mirrors the existing scrub in the `run_bash` tool handler below.
     // GH_TOKEN/GITHUB_TOKEN and all other env vars are intentionally left
     // intact — only the Anthropic key is removed.
-    const childEnv = withForgedockHome({ ...process.env });
+    const childEnv = withRunTmpdir(withForgedockHome({ ...process.env }), { issue: issueFromArgs(args), cwd });
     delete childEnv.ANTHROPIC_API_KEY;
 
     // No `shell` option (defaults to false): argv is passed as discrete,
@@ -1435,6 +1521,9 @@ export function runCliBackend({
     // intentionally omitted here since spawnSync's own `timeout` + ETIMEDOUT is
     // reliable for this single, non-looped invocation.
     const timedOut = result.status === null && result.error?.code === "ETIMEDOUT";
+    // forge#4037: only a spawn-stage failure is transient infra. A wall-clock kill leaves evidence that the child ran
+    // (a kill signal, a pid, or captured output); an ETIMEDOUT with none of those never started the child.
+    const childRan = !!result.signal || (Number.isInteger(result.pid) && result.pid > 0) || (stdout + stderr).trim().length > 0;
     if (timedOut) {
       const timeoutSecs = Math.round(timeoutMs / 1000);
       // forge#2360: spawnSync's `timeout` option kills the child outright on
@@ -1452,15 +1541,44 @@ export function runCliBackend({
       // review findings — #2277, #2292, #2293, #2355 — for that defect
       // class).
       const partial = (stdout + stderr).trim();
-      throw new Error(
+      const timeoutError = new Error(
         `claude CLI invocation timed out after ${timeoutSecs}s and was killed. ` +
           `Set FORGEDOCK_CLI_TIMEOUT_MS (ms) to adjust, or use --backend api.` +
           (partial ? ` Partial output: ${sanitizeOutputExcerptForLog(partial)}` : ""),
       );
+      if (!childRan) {
+        // forge#4021: stable transient-infra class; the engine retries it on a
+        // separate bounded counter without consuming a phase attempt.
+        timeoutError.code = "CLI_SPAWN_TRANSIENT";
+        timeoutError.spawnErrno = "ETIMEDOUT";
+        throw timeoutError;
+      }
+      // forge#4037: the child ran and was killed at the wall-clock limit: a normal, attempt-consuming failure
+      // (`cli.timeout`), with usage attached when the CLI had already emitted a parseable envelope.
+      timeoutError.code = "CLI_TIMEOUT";
+      timeoutError.usage = null;
+      try {
+        const u = JSON.parse(stdout.trim())?.usage;
+        if (u && typeof u === "object") {
+          timeoutError.usage = {
+            input_tokens: toFiniteUsageNumber(u.input_tokens),
+            output_tokens: toFiniteUsageNumber(u.output_tokens),
+            cache_creation_input_tokens: toFiniteUsageNumber(u.cache_creation_input_tokens),
+            cache_read_input_tokens: toFiniteUsageNumber(u.cache_read_input_tokens),
+          };
+        }
+      } catch {
+        // No parseable envelope from a killed child: usage stays null (never fabricated).
+      }
+      throw timeoutError;
     }
     if (result.error) {
       const error = new Error(`Failed to invoke claude CLI: ${result.error.message}`);
       error.code = result.error.code;
+      if (["EAGAIN", "ENOMEM", "EMFILE"].includes(result.error.code)) {
+        error.spawnErrno = result.error.code;
+        error.code = "CLI_SPAWN_TRANSIENT";
+      }
       throw error;
     }
 
@@ -2186,9 +2304,10 @@ export function resolveBashShell() {
  * the loop catches and reports the error back to the model as an error result.
  *
  * @param {string} cwd
+ * @param {string|null} [runIssueNumber] - issue number scoping the per-run TMPDIR (forge#3572)
  * @returns {Record<string, (input: object) => string>}
  */
-export function getToolHandlers(cwd) {
+export function getToolHandlers(cwd, runIssueNumber = null) {
   return {
     read_file: ({ path }) => {
       if (!path) throw new Error("read_file requires a 'path'");
@@ -2208,7 +2327,7 @@ export function getToolHandlers(cwd) {
       // into the model loop, so a prompt-injection payload could otherwise issue
       // a run_bash command that exfiltrates the key. gh/git auth tokens
       // (GH_TOKEN/GITHUB_TOKEN) are intentionally left intact.
-      const childEnv = withForgedockHome({ ...process.env });
+      const childEnv = withRunTmpdir(withForgedockHome({ ...process.env }), { issue: runIssueNumber, cwd });
       delete childEnv.ANTHROPIC_API_KEY;
       // Run under bash when available so bash-style commands the model emits
       // (heredocs, scripts/*.sh, single-quote semantics) behave consistently
@@ -2648,7 +2767,7 @@ export async function runCommand(opts = {}) {
   // is a known Linux limitation at the OS level; closing it would require
   // a native module (e.g. prctl PR_SET_DUMPABLE) or process isolation.
   // See: issue #1370 for tracking this known limitation.
-  const handlers = getToolHandlers(cwd);
+  const handlers = getToolHandlers(cwd, issueFromArgs(args));
   const messages = [{ role: "user", content: userMessage }];
 
   // Accumulate token usage across all messages.create() calls in this run.

package/bin/stats/aggregate.mjs

@@ -127,8 +127,10 @@ function funnelSection(events, issues) {
   for (const d of Object.values(bySeverity)) d.perReview = reviews.size ? d.total / reviews.size : null;
   const dispositions = { ISSUE: 0, NOTE: 0, INPR_FIX: 0 };
   for (const f of findings) if (f.disposition in dispositions) dispositions[f.disposition]++;
+  // Events written before the scope field existed carry none and are not counted.
+  const introduced = findings.filter((f) => f.scope === "introduced").length;
   return {
-    reviews: reviews.size, findings: findings.length, perReview: ratio(findings.length, reviews.size),
+    reviews: reviews.size, findings: findings.length, introduced, perReview: ratio(findings.length, reviews.size),
     bySeverity, dispositions,
     validated: issues.filter((i) => i.labels.includes("validated")).length,
     falsePositive: issues.filter((i) => i.labels.includes("false-positive")).length,
@@ -150,7 +152,7 @@ function gatesSection(events) {
   };
 }
 
-function issueFlowSection(issues) {
+function issueFlowSection(issues, introduced = 0) {
   const real = issues.filter((i) => !i.isPr);
   const created = {};
   for (const i of real) { const s = issueSource(i); created[s] = (created[s] ?? 0) + 1; }
@@ -162,6 +164,7 @@ function issueFlowSection(issues) {
     n: real.length, created, createdTotal: real.length, closed, closedTotal: closedIssues.length,
     net: real.length ? real.length - closedIssues.length : null,
     findingsPerMerge: ratio(created["review-finding"] ?? 0, merged),
+    introducedPerMerge: ratio(introduced, merged),
   };
 }
 
@@ -214,7 +217,8 @@ export function aggregate({ runs = [], events = [], issues = [] } = {}, opts = {
   let groups = [...keys.values()].map(({ version, repo }) => {
     const sel = (list) => list.filter((x) => x.version === version && x.repo === repo);
     const g = { version, repo, cost: costSection(sel(counted)), time: timeSection(sel(counted)), flow: flowSection(sel(counted)),
-      funnel: funnelSection(sel(evs), sel(iss)), gates: gatesSection(sel(evs)), issueFlow: issueFlowSection(sel(iss)) };
+      funnel: funnelSection(sel(evs), sel(iss)), gates: gatesSection(sel(evs)), issueFlow: null };
+    g.issueFlow = issueFlowSection(sel(iss), g.funnel.introduced);
     g.n = g.flow.n;
     g.lowN = g.n < minN;
     g.minN = minN;

package/bin/stats/cache.mjs

@@ -17,13 +17,17 @@ export function cacheDir(repo, env = process.env) {
   return join(root, repo.replace("/", "_"));
 }
 
-/** { watermark: ISO string | null, items: { "<number>": item } } */
-export const emptyCache = () => ({ v: CACHE_VERSION, watermark: null, items: {} });
+/**
+ * { watermark: ISO string | null, coveredFrom: ISO string | null, items: { "<number>": item } }
+ * The cache covers activity in [coveredFrom, watermark]; coveredFrom null means "from the beginning". A cache written
+ * before the field existed loads with coveredFrom undefined (floor unknown), never as full coverage.
+ */
+export const emptyCache = () => ({ v: CACHE_VERSION, watermark: null, coveredFrom: null, items: {} });
 
 export function loadCache(repo, env = process.env) {
   try {
     const c = JSON.parse(readFileSync(join(cacheDir(repo, env), "cache.json"), "utf8"));
-    if (c && c.v === CACHE_VERSION && c.items && typeof c.items === "object") return { ...emptyCache(), ...c };
+    if (c && c.v === CACHE_VERSION && c.items && typeof c.items === "object") return { ...emptyCache(), ...c, coveredFrom: "coveredFrom" in c ? c.coveredFrom : undefined };
   } catch { /* missing or corrupt: refetch */ }
   return emptyCache();
 }