forgedock 1.17.0 → 1.18.0

package/bin/engine.mjs

@@ -4,15 +4,15 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { createHash, scryptSync } from "node:crypto";
 import { hostname as osHostname, homedir } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
-import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postCycleMarker, nextCycleNumber } from "./engine/phases.mjs";
+import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postCycleMarker, nextCycleNumber, newestCycle, cycleResetProvable, remediationHeadStale, decompositionRevoked, openDependency } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
-import { VALID_BACKENDS } from "./runner.mjs";
-import { OUTCOME_CODES, UNCLASSIFIED, normalizeCode, codeForRunnerError, codeForTerminalReason } from "./engine/outcome-codes.mjs";
+import { VALID_BACKENDS, resolveRunTmpRoot, runTmpDir } from "./runner.mjs";
+import { OUTCOME_CODES, UNCLASSIFIED, normalizeCode, codeForRunnerError, codeForTerminalReason, isDiskQuotaError, isDiskQuotaText } from "./engine/outcome-codes.mjs";
 
 // Exported (forge#2175) so bin/engine-cli.mjs can render "failed N/M attempts"
 // diagnostics without duplicating the retry budget constant.
@@ -390,6 +390,27 @@ export async function runIssue(opts) {
     remote = cur;
     ({ state, action } = reconcileState(local, remote));
   }
+  // forge#3932: `Depends on` admission. A trusted `**Depends on**: #N` line whose dependency is still OPEN
+  // refuses the run BEFORE any state/lease write (mirrors deferredResult), so building on top of an
+  // unmerged dependency cannot conflict with it. Checked on every start; a closed dependency, no
+  // declaration or an untrusted body proceeds. An unreadable body/dependency fails closed.
+  {
+    let dep = null;
+    try { dep = await openDependency(issue, io); } catch (e) {
+      dep = { unreadable: true, detail: `issue ${issue} **Depends on** check failed: ${e?.message || e}` };
+    }
+    if (dep?.unreadable) {
+      return { terminalReason: "dependency-unreadable", code: OUTCOME_CODES.DEPENDENCY_UNREADABLE, detail: dep.detail };
+    }
+    if (dep?.open?.length) {
+      return {
+        terminalReason: "dependency-open",
+        code: OUTCOME_CODES.DEPENDENCY_OPEN,
+        dependencies: dep.open,
+        detail: `issue ${issue} **Depends on** ${dep.open.map((n) => `#${n}`).join(", ")} which is still open; re-run once it is closed`,
+      };
+    }
+  }
   // forge#3824: hoisted so RUN_START can carry the repo (lazy, memoised; null when unresolved).
   let repoPromise = null;
   const resolveRepo = () => (repoPromise ??= (async () => {
@@ -412,6 +433,20 @@ export async function runIssue(opts) {
     // and regress committed/issue/v (C2).
     rewriteLog(dir, issue, eventsFromIndex(state, await runMeta()));
     state = deriveState(readLog(dir, issue));
+    // forge#3931: the index does not carry the cycle, so a hydrated log always starts at cycle 0. When a
+    // trusted FORGE:CYCLE exists, cycle-scoped progress (or a needs-human/phase-complete/engine-error terminal)
+    // belongs to an older cycle ONLY when provably so (cycleResetProvable: terminal index, issue OPEN, no needs-human/remediating label, no open PR): reset via the existing RUN_NEXT_CYCLE event so build runs again instead of
+    // terminating. An unreadable trail resets nothing (fail closed). merged/decomposed/invalid terminals stay.
+    if (state.committed.some((p) => ["build", "review", "remediate", "close"].includes(p)) &&
+        state.terminal && ["needs-human", "phase-complete", "engine-error"].includes(state.terminalReason) &&
+        await cycleResetProvable(state, io)) {
+      let cyc = 0;
+      try { cyc = await newestCycle(issue, io); } catch { cyc = 0; }
+      if (cyc > 0) {
+        appendEvent(dir, issue, { event: "RUN_NEXT_CYCLE", issue });
+        state = deriveState(readLog(dir, issue));
+      }
+    }
   }
 
   // forge#3511: explicit `--retry` reopens a transient `engine-error` terminal
@@ -424,12 +459,19 @@ export async function runIssue(opts) {
   // forge#3562: `phase-complete` is also retryable, but as a NEW cycle
   // (RUN_NEXT_CYCLE clears committed) rather than a reopen of the same one.
   let reopened = false;
+  let reopenUncommit = null;
   if (retry && state?.terminal) {
-    if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete" &&
+    // forge#3862 / forge#3932: a `decomposed` terminal is reopened at build when trusted GitHub state shows
+    // the decomposition revoked (a trusted FORGE:DECOMPOSED:REVOKED newer than FORGE:DECOMPOSED); the
+    // revocation alone suffices now that the size gate is gone. Anything else keeps the terminal; an
+    // unreadable comment trail fails closed.
+    if (state.terminalReason === "decomposed" && await decompositionRevoked(issue, io)) {
+      reopenUncommit = ["build", "decompose"];
+    } else if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete" &&
         state.terminalReason !== "needs-human") {
       return {
         terminalReason: "not-retryable",
-        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error, phase-complete or needs-human run`,
+        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error, phase-complete or needs-human run (or a decomposed run whose FORGE:DECOMPOSED was revoked by a trusted FORGE:DECOMPOSED:REVOKED)`,
       };
     }
     // forge#3571: a human clearing `needs-human` is the hand-back signal. Reopen
@@ -457,6 +499,13 @@ export async function runIssue(opts) {
         };
       }
     }
+    // forge#3931: a remediate that ended needs-human was recorded against an older PR head. When the
+    // live head differs from the head in its trusted trail, un-commit remediate AND review so review
+    // re-runs at the new head instead of the old RE-ESCALATED result replaying. Unreadable => no change.
+    if (state.terminalReason === "needs-human" && !reopenUncommit &&
+        state.committed[state.committed.length - 1] === "remediate" && await remediationHeadStale(state, io)) {
+      reopenUncommit = ["remediate", "review"];
+    }
     // forge#3562 (SEC-3): a new cycle discards `committed`, so check the live
     // issue first. A CLOSED issue has nothing left to run; an unreadable
     // snapshot fails closed rather than resetting a possibly-finished run.
@@ -486,6 +535,7 @@ export async function runIssue(opts) {
     appendEvent(dir, issue, {
       event: state.terminalReason === "phase-complete" ? "RUN_NEXT_CYCLE" : "RUN_REOPEN",
       issue,
+      ...(reopenUncommit ? { uncommit: reopenUncommit } : {}),
     });
     state = deriveState(readLog(dir, issue));
     reopened = true;
@@ -779,7 +829,7 @@ export async function runIssue(opts) {
         // "needs-human" — this is the engine/tool breaking, not a genuine
         // human-judgment block (see #2244/#2261). Any other thrown error is
         // a true unexpected crash and keeps propagating unchanged.
-        if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED" || e.code === "CLI_MAX_TURNS") {
+        if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED" || e.code === "CLI_MAX_TURNS" || isDiskQuotaError(e)) {
           // forge#2241: when the runner attached a session-limit reset time
           // (bin/runner.mjs's extractSessionLimitResetTime(), only ever set
           // for a genuine session-limit CLI_BACKEND_FAILED — never
@@ -789,7 +839,7 @@ export async function runIssue(opts) {
           const resetSuffix = e.resetAt ? ` (resets: ${e.resetAt})` : "";
           const detail = e.code === "CLI_MAX_TURNS"
             ? `phase ${phase.id}: CLI_MAX_TURNS - max-turns exhausted${e.numTurns != null ? ` after ${e.numTurns} turns` : ""}: ${e.message}`
-            : `phase ${phase.id}: ${e.code} - ${e.message}${resetSuffix}`;
+            : `phase ${phase.id}: ${e.code ?? "DISK_QUOTA"} - ${e.message}${resetSuffix}`;
           // forge#2240 (review finding): this fail-fast path previously left
           // phase_exit unreported — a caller tailing progress output would see
           // "→ phase X started" and then nothing, dangling exactly on the
@@ -845,6 +895,9 @@ export async function runIssue(opts) {
         await emitOutcome({ event: "PHASE_DEFERRED", phase: phase.id, code: normalizeCode(outcome.code), reason: outcome.detail });
         return { terminalReason: "deferred", code: normalizeCode(outcome.code), detail: outcome.detail };
       }
+      // forge#3572: a phase that returned blocked because the disk/quota ran out is a retryable infra failure.
+      if (isDiskQuotaText(outcome.detail))
+        return await terminate(state, "engine-error", outcome.detail, OUTCOME_CODES.INFRA_DISK_QUOTA);
       if (!isRemediationHandoff)
         return await terminate(state, outcome.reason || "needs-human", outcome.detail, outcome.code);
     } else {
@@ -910,8 +963,8 @@ export async function runIssue(opts) {
     // is seen), phase.id is "decompose" — not "investigate" — so this
     // exemption does not apply and the normal terminate() path below fires,
     // ending the run for real.
-    // build also hands off: the B5.5 size gate (NEEDS_DECOMPOSE) reports "decomposed".
-    const isDecomposeHandoff = (phase.id === "investigate" || phase.id === "build") && terminalReason === "decomposed";
+    // forge#3862: only investigate hands off (decomposition is a planning decision); build never reports "decomposed".
+    const isDecomposeHandoff = phase.id === "investigate" && terminalReason === "decomposed";
     // forge#3624: remediate AUTO-LANDED whose issue is not yet CLOSED+workflow:merged hands off
     // to `close` instead of ending the run (close is idempotent). Exempts BOTH terminate paths.
     const isCloseHandoff = phase.id === "remediate" && outcome.status === "committed" &&
@@ -980,10 +1033,24 @@ export async function runIssue(opts) {
         try { await projector.setLabel(issue, "needs-human"); } catch { /* best-effort */ }
       }
     }
+    // forge#3572: drop the per-run scratch dir (venvs, session data) on a terminal outcome. Kept for
+    // `engine-error` so `--retry` resumes with it, and when another live engine owns the issue.
+    if (reason !== "engine-error" && foreign === undefined) cleanupRunTmpdir(issue);
     return { terminalReason: reason, code: outcomeCode, detail };
   }
 }
 
+/** Best-effort removal of the issue's per-run scratch dir. Confined to the resolved tmp root; never throws. */
+export function cleanupRunTmpdir(issue, { cwd = process.cwd(), env = process.env, rm = rmSync } = {}) {
+  try {
+    const root = resolveRunTmpRoot(cwd, env);
+    const dir = runTmpDir(root, issue);
+    if (!dir || dir === root) return false;
+    rm(dir, { recursive: true, force: true });
+    return true;
+  } catch { return false; }
+}
+
 async function runPhaseWithRetry(phase, state, ctx) {
   const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry } = ctx;
   // forge#3499: build the phase's full argument set ONCE, up front. Every
@@ -1080,6 +1147,13 @@ async function runPhaseWithRetry(phase, state, ctx) {
         });
         throw e;
       }
+      // forge#3572: a full disk / exhausted quota (EDQUOT/ENOSPC) is infra, not content: retrying burns the budget on the same
+      // failure, so rethrow fail-fast and let runIssue end it as a retryable `engine-error` (never needs-human).
+      if (isDiskQuotaError(e)) {
+        await recordAttempt(attempt, null, t0, null);
+        appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts });
+        throw e;
+      }
       if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED") throw e;
       // forge#2377: no `usage` field here — the runner threw, so no result
       // (and therefore no usage data) was ever produced for this attempt.

package/bin/forgedock.mjs

@@ -3972,7 +3972,7 @@ switch (command) {
       // an uncaught throw, which already set exitCode = 1 below. Now that
       // runIssue() resolves cleanly with a terminalReason instead of throwing,
       // preserve that same non-zero exit code for this reason too.
-      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable")) exitCode = 1;
+      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable" || result.terminalReason === "dependency-open" || result.terminalReason === "dependency-unreadable")) exitCode = 1;
       // forge#3574: a lease-held deferral did NOT run the issue; exit 75
       // (EX_TEMPFAIL) so orchestrators neither count it as done nor as a failure.
       if (result && result.terminalReason === "deferred") exitCode = 75;

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

@@ -74,6 +74,64 @@ 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");
+}
+
+/** `<root>/<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) {
+  const id = String(issue ?? "").trim();
+  return root && /^[0-9]+$/.test(id) ? join(root, id) : null;
+}
+
+/**
+ * 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. No-op when the issue is unknown or the operator owns the tmp root.
+ * Best-effort: a failed mkdir leaves the env unchanged.
+ */
+export function withRunTmpdir(env, { issue, cwd = process.cwd() } = {}) {
+  const dir = runTmpDir(resolveRunTmpRoot(cwd, env), issue);
+  if (!dir) return env;
+  try {
+    mkdirSync(dir, { recursive: true });
+    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 +1468,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,
@@ -2186,9 +2244,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 +2267,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 +2707,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/github-source.mjs

@@ -5,7 +5,7 @@
  * Reads labels and ONLY trusted `<!-- FORGE:TELEMETRY v1 -->` comments (same predicate as
  * scripts/trusted-comments.sh: an author_association in FORGE_TRAIL_TRUSTED_ASSOCIATIONS, a Bot, or a login in
  * FORGE_TRAIL_TRUSTED_LOGINS). Every `gh` call is argv-based (no shell). The `gh` runner is injectable for tests.
- * Fetching is incremental: only items updated after the cached watermark are re-read.
+ * Fetching is incremental: only items updated after the cached watermark (minus a small overlap window) are re-read.
  */
 import { execFileSync } from "node:child_process";
 import { emptyCache, loadCache, saveCache } from "./cache.mjs";
@@ -58,8 +58,10 @@ export function parseTelemetryComments(comments, env = process.env) {
 const num = (x) => { const v = Number(x); return x != null && x !== "" && Number.isFinite(v) ? v : null; };
 
 /**
- * Turn `phase_attempt` / `run_terminal` records into run summaries (one per repo#issue#run, finished only when a
- * `run_terminal` exists). Field names are the ones bin/engine/telemetry-seam.mjs writes (docs/TELEMETRY.md).
+ * Turn `phase_attempt` / `run_terminal` records into run summaries, finished only when a `run_terminal` exists.
+ * The run id is per engine process, so a `--retry` yields several; they collapse to ONE run per repo#issue, the latest
+ * by start timestamp (tie: greater run id), matching scripts/cost-report.sh (last RUN_START slice). Finished/usage
+ * filtering stays downstream, so an unfinished latest run still excludes the issue. Field names are the ones bin/engine/telemetry-seam.mjs writes (docs/TELEMETRY.md).
  */
 export function runsFromRecords(records) {
   const byRun = new Map();
@@ -86,13 +88,74 @@ export function runsFromRecords(records) {
     if (num(r.cost_usd) != null) p.usd = (p.usd ?? 0) + num(r.cost_usd);
     if (id === "remediate") run.remediated = true;
   }
-  return [...byRun.values()].map(({ _first, ...run }) => ({ ...run, startTs: _first }));
+  const latest = new Map();
+  for (const run of byRun.values()) {
+    const k = `${run.repo}#${run.issue}`;
+    const cur = latest.get(k);
+    const a = run._first ?? "", b = cur?._first ?? "";
+    if (!cur || a > b || (a === b && (run.run ?? "") > (cur.run ?? ""))) latest.set(k, run);
+  }
+  return [...latest.values()].map(({ _first, ...run }) => ({ ...run, startTs: _first }));
 }
 
 /** Gate/review records (everything that is not a run record) become aggregate events. */
 export const gateEvents = (records) => records.filter((r) => r.event !== "phase_attempt" && r.event !== "run_terminal")
   .map((r) => ({ ...r, version: r.forge_version ?? null }));
 
+const CHECKPOINT_EVERY = 25;
+const PAGE_SIZE = 100;
+// The next incremental run re-reads this much before the persisted watermark (an overlap window), so a write that races a
+// crawl or a small clock skew is re-listed. Re-reads are idempotent: items are keyed by issue number.
+const WATERMARK_OVERLAP_MS = 5 * 60 * 1000;
+const MAX_LIST_REQUESTS = 100000;
+
+/** Shift an ISO-8601 timestamp by `ms`; an unparsable value is returned unchanged. */
+export function shiftIso(ts, ms) {
+  const t = Date.parse(ts);
+  return Number.isNaN(t) ? ts : new Date(t + ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+const sinceParam = (ts) => encodeURIComponent(ts).replace(/%3A/g, ":");
+
+/**
+ * Keyset crawl of the issue listing. The listing is sorted by a MUTABLE key (updated_at), so page-number pagination
+ * (`gh --paginate`) can skip an item updated mid-crawl: it moves to the end of the ordering and the items behind it shift
+ * one page earlier. Instead every request is page 1 from `since=CURSOR`, the cursor moves to the newest `updated_at` read,
+ * and already-seen (number, updated_at) pairs are dropped (the `since` boundary is inclusive). A full page that cannot move
+ * the cursor (more than PAGE_SIZE items share one timestamp) is drained with `page=N` for that timestamp only.
+ * Yields each page's unseen items sorted updated-asc.
+ */
+function* listIssuePages(gh, repo, startSince) {
+  const base = ["state=all", "sort=updated", "direction=asc", `per_page=${PAGE_SIZE}`];
+  const seen = new Set();
+  const key = (it) => `${it.number}@${it.updated_at}`;
+  const take = (page) => {
+    const fresh = page.filter((it) => Number.isInteger(it?.number) && !seen.has(key(it)));
+    for (const it of fresh) seen.add(key(it));
+    return fresh.sort((a, b) => String(a.updated_at).localeCompare(String(b.updated_at)));
+  };
+  const maxTs = (page) => page.reduce((m, it) => (it?.updated_at && (!m || it.updated_at > m) ? it.updated_at : m), null);
+  let cursor = startSince ?? null;
+  for (let n = 0; n < MAX_LIST_REQUESTS; n++) {
+    const get = (extra = []) => parsePages(gh(["api", `repos/${repo}/issues?${[...base, ...(cursor ? [`since=${sinceParam(cursor)}`] : []), ...extra].join("&")}`]));
+    const page = get();
+    const fresh = take(page);
+    if (fresh.length > 0) yield fresh;
+    if (page.length < PAGE_SIZE) return;
+    const next = maxTs(page);
+    if (next && next !== cursor) { cursor = next; continue; }
+    // No cursor progress on a full page: drain this timestamp by page number, then step past it.
+    for (let p = 2; p < MAX_LIST_REQUESTS; p++) {
+      const more = get([`page=${p}`]);
+      const freshMore = take(more);
+      if (freshMore.length > 0) yield freshMore;
+      if (more.length < PAGE_SIZE || freshMore.length === 0) break;
+    }
+    if (!cursor) return;
+    cursor = shiftIso(cursor, 1000);
+  }
+}
+
 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 });
 
@@ -103,25 +166,33 @@ const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), creat
 export function fetchGithubRecords({ repo, refresh = false, useCache = true, gh = defaultGh, env = process.env } = {}) {
   if (!isValidRepo(repo)) throw new Error(`invalid repo: ${repo}`);
   const cache = useCache && !refresh ? loadCache(repo, env) : emptyCache();
-  const q = ["state=all", "sort=updated", "direction=asc", "per_page=100", ...(cache.watermark ? [`since=${cache.watermark}`] : [])];
-  const listed = parsePages(gh(["api", "--paginate", `repos/${repo}/issues?${q.join("&")}`]));
+  const startSince = cache.watermark ? shiftIso(cache.watermark, -WATERMARK_OVERLAP_MS) : null;
   const items = { ...cache.items };
   let watermark = cache.watermark;
   let fetched = 0;
-  for (const it of listed) {
-    if (!Number.isInteger(it?.number)) continue;
-    const m = meta(it);
-    let records = items[it.number]?.records ?? [];
-    // A telemetry comment is edited in place (which may not bump the issue's updated_at), so every listed item with
-    // comments is re-read rather than trusting a cached copy.
-    if ((it.comments ?? 0) > 0) {
-      records = parseTelemetryComments(parsePages(gh(["api", "--paginate", `repos/${repo}/issues/${it.number}/comments`])), env);
-      fetched++;
+  // Checkpoint: the watermark is the newest updated_at actually processed, and the next run starts WATERMARK_OVERLAP_MS
+  // before it, so it is a safe resume point. A failure mid-crawl (rate limit, 5xx, a hook timeout) then keeps the
+  // progress instead of restarting at zero.
+  const checkpoint = () => { if (useCache) saveCache(repo, { ...emptyCache(), watermark, items }, env); };
+  try {
+    for (const page of listIssuePages(gh, repo, startSince)) for (const it of page) {
+      const m = meta(it);
+      let records = items[it.number]?.records ?? [];
+      // A telemetry comment is edited in place (which may not bump the issue's updated_at), so every listed item with
+      // comments is re-read rather than trusting a cached copy.
+      if ((it.comments ?? 0) > 0) {
+        records = parseTelemetryComments(parsePages(gh(["api", "--paginate", `repos/${repo}/issues/${it.number}/comments`])), env);
+        fetched++;
+      }
+      items[it.number] = { ...m, records };
+      if (m.updatedAt && (!watermark || m.updatedAt > watermark)) watermark = m.updatedAt;
+      if (fetched > 0 && fetched % CHECKPOINT_EVERY === 0 && (it.comments ?? 0) > 0) checkpoint();
     }
-    items[it.number] = { ...m, records };
-    if (m.updatedAt && (!watermark || m.updatedAt > watermark)) watermark = m.updatedAt;
+  } catch (err) {
+    checkpoint();
+    throw err;
   }
-  if (useCache) saveCache(repo, { ...emptyCache(), watermark, items }, env);
+  checkpoint();
   const seen = new Set();
   const records = [];
   for (const it of Object.values(items)) for (const r of it.records ?? []) {