forgedock 1.16.0 → 1.16.2

package/bin/engine/phases.mjs

@@ -97,6 +97,10 @@ async function issueMarkers(issue, io) {
 
 /** Non-terminal held-resume record (remediate.md Phase M8, forge#3685): header and sentinel are the same line; never a COMPLETE marker. */
 const REMEDIATION_HELD_MARKER = "FORGE:REMEDIATION_HELD";
+/** Non-terminal deferral record (remediate.md Phase M0 liveness step): a live earlier run holds the lease. Never a COMPLETE/trail marker. */
+const REMEDIATION_DEFERRED_MARKER = "FORGE:REMEDIATION_DEFERRED";
+/** Lease holder ids the engine mints (`cli_<host>_<pid>`) are passed to remediate only when they match this shape (same as remediate-liveness.sh). */
+const LEASE_HOLDER_RE = /^[A-Za-z0-9._-]{1,128}$/;
 const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /** True when `body` STARTS with the typed header `<!-- {header}` (e.g. `FORGE:BUILDER`). */
 function startsWithHeader(body, header) {
@@ -227,6 +231,17 @@ async function hasTrajectory(issue, io) {
   return comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY"));
 }
 
+/**
+ * forge#3772: investigation close evidence, shared by close.reconcile and close.detectOutcome.
+ * A trusted FORGE:TRAJECTORY, or a trusted current-cycle FORGE:PHASE:COMPLETE (multi-phase body).
+ * Throws on fetch error; callers fail closed.
+ */
+async function hasInvestigationCloseEvidence(issue, io) {
+  const { comments } = await issueMarkers(issue, io);
+  return comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY"))
+    || hasPhaseComplete(sliceToCurrentCycle(comments));
+}
+
 /**
  * Trusted comment bodies, chronological — the same single fetch + trust predicate
  * as issueMarkers() (one path, forge#3542). Fail closed: a fetch error yields `[]` here (issueMarkers itself propagates it).
@@ -259,7 +274,7 @@ function sizeGateRoutesToDecompose(comments) {
   for (let i = comments.length - 1; i >= 0; i--) if (starts(comments[i], gate)) { idx = i; break; }
   if (idx < 0) return false;
   const body = comments[idx].replace(/\r\n/g, "\n");
-  const m = /^result:[ \t]*(OK|OVERRIDDEN|OVER)[ \t]*$/m.exec(body);
+  const m = /^result:[ \t]*(OK|OVERRIDDEN|COHESIVE|OVER)[ \t]*$/m.exec(body);
   if (!m || m[1] !== "OVER" || !/^###[ \t]+Split Proposal\b/m.test(body)) return false;
   return !comments.slice(idx + 1).some((c) => starts(c, override) && overrideHasJustification(c));
 }
@@ -529,6 +544,8 @@ async function reviewArgs(state, ctx, io) {
 
 /** Default `build.diff_size.estimate_factor` (docs/CONFIG.md); used when the report carries no valid `ESTIMATE_FACTOR:` field. */
 const DEFAULT_ESTIMATE_FACTOR = 1.2;
+/** Default `build.diff_size.batch_seam_min` (docs/CONFIG.md); the engine cannot read forge.yaml here. */
+const DEFAULT_BATCH_SEAM_MIN = 3;
 
 /**
  * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
@@ -550,23 +567,41 @@ function isDecomposed(report) {
     console.error(`[engine] conflicting decomposition signals (heading=${verdict ?? "none"}, markers=${[...markers].join("+") || "none"}); treating as not decomposed`);
     return false;
   }
-  if ((verdict ?? marker) === "YES") return true;
-  // forge#3573 safety net: an investigator NO whose own size estimate is clearly over
-  // the gate (estimate > threshold x factor) fails toward decompose. Own-line,
-  // whole-number fields only; absent/0/non-numeric fields have no effect. The factor is
-  // the investigator's effective `ESTIMATE_FACTOR:` (positive decimal); absent/invalid -> 1.2.
+  // forge#3573 safety net inputs: own-line, whole-number fields only; absent/0/non-numeric
+  // fields have no effect. The factor is the investigator's effective `ESTIMATE_FACTOR:`
+  // (positive decimal); absent/invalid -> 1.2.
   const est = /^ESTIMATED_DIFF_LINES:[ \t]*(\d+)[ \t]*$/m.exec(text);
   const gate = /^GATE_THRESHOLD:[ \t]*(\d+)[ \t]*$/m.exec(text);
   const fac = /^ESTIMATE_FACTOR:[ \t]*(\d+(?:\.\d+)?)[ \t]*$/m.exec(text);
+  const seamsM = /^INDEPENDENT_SEAMS:[ \t]*(\d+)[ \t]*$/m.exec(text);
   const parsedFactor = fac ? Number(fac[1]) : NaN;
   const factor = Number.isFinite(parsedFactor) && parsedFactor > 0 ? parsedFactor : DEFAULT_ESTIMATE_FACTOR;
-  if (est && gate) {
-    const estimate = Number(est[1]);
-    const threshold = Number(gate[1]);
-    if (threshold > 0 && estimate > threshold * factor) {
-      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
-      return true;
+  const sized = est && gate && Number(gate[1]) > 0;
+  const estimate = sized ? Number(est[1]) : 0;
+  const threshold = sized ? Number(gate[1]) : 0;
+  if ((verdict ?? marker) === "YES") {
+    // forge#3786: a YES the numbers do not require is downgraded to NO unless the report
+    // carries an own-line `DECOMPOSE_JUSTIFICATION:` line. Required = estimate over
+    // threshold x factor, or the seam clause (seams >= batch_seam_min and estimate over
+    // threshold / 2). The engine cannot see the `batch` label or the configured
+    // `batch_seam_min`, so it uses the default 3 and stays lenient for batches. Absent
+    // numeric fields keep the YES (no silent downgrade of a malformed report).
+    if (sized) {
+      const seams = seamsM ? Number(seamsM[1]) : 0;
+      const required = estimate > threshold * factor || (seams >= DEFAULT_BATCH_SEAM_MIN && estimate > threshold / 2);
+      const justified = /^DECOMPOSE_JUSTIFICATION:[ \t]*\S/m.test(text);
+      if (!required && !justified) {
+        console.error(`[engine] unsupported DECOMPOSE:YES (estimate ${estimate}, seams ${seams}, gate ${threshold} x ${factor}, no DECOMPOSE_JUSTIFICATION); treating as not decomposed`);
+        return false;
+      }
     }
+    return true;
+  }
+  // forge#3573 safety net: an investigator NO whose own size estimate is clearly over
+  // the gate (estimate > threshold x factor) fails toward decompose.
+  if (sized && estimate > threshold * factor) {
+    console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
+    return true;
   }
   return false;
 }
@@ -813,7 +848,9 @@ export const PHASES = [
     buildArgs: async (state, ctx, io) => {
       const pr = need(state.pr, "pr", /^[0-9]+$/);
       const kind = state.remediationKind ?? null;
-      const legacyArgs = () => [pr, "--issue", String(state.issue), ...repoArgs(ctx), ...baseArgs(state)];
+      // Pass the dispatching lease holder so remediate.md M0 can tell a live OTHER run from this engine's own lease.
+      const holderArgs = () => (typeof ctx.agentId === "string" && LEASE_HOLDER_RE.test(ctx.agentId) ? ["--lease-holder", ctx.agentId] : []);
+      const legacyArgs = () => [pr, "--issue", String(state.issue), ...repoArgs(ctx), ...baseArgs(state), ...holderArgs()];
       // Legacy handoff with no kind (needs-human label fallback, or no REVIEW_RESULT): there
       // is nothing to bind, so dispatch as before. remediate.md M0 then applies its default
       // single-attempt guard. A present-but-unknown kind is never dispatched.
@@ -893,6 +930,20 @@ export const PHASES = [
       }
       if (latest === null) {
         if (await prMerged()) return mergedResult("AUTO-LANDED");
+        // A deferral to a live earlier run (remediate.md M0 liveness step) is not a failed attempt. The
+        // decision was made by the script at M0 time, so the record is not re-judged against the clock (a
+        // lease that expired since is the NEXT dispatch's business). Only a trusted, full-line record for THIS
+        // PR counts, and only while it is newer than every `FORGE:REMEDIATION` trail comment: a later run
+        // that proceeded posts one, which retires the deferral.
+        let deferredAt = -1, trailAt = -1, deferred = null;
+        scoped.forEach((b, i) => {
+          if (startsWithHeader(b, REMEDIATION_DEFERRED_MARKER) && hasSentinelLine(b, REMEDIATION_DEFERRED_MARKER)) { deferredAt = i; deferred = b; }
+          else if (startsWithHeader(b, PHASE_MARKERS.remediate.header)) trailAt = i;
+        });
+        if (deferred !== null && deferredAt > trailAt && (state.pr == null || /^pr=(\d+)\s*$/m.exec(deferred)?.[1] === String(state.pr))) {
+          const kind = /^kind=(\w+)\s*$/m.exec(deferred)?.[1] ?? "lease";
+          return { status: "blocked", reason: "deferred", retryable: false, detail: `deferred-live-run: ${kind}` };
+        }
         return { status: "failed", detail: `no ${completion} marker` };
       }
       // Parse the **Re-gate outcome**: field remediate.md's Phase M8 posts
@@ -968,8 +1019,11 @@ export const PHASES = [
         // forge#3534: the implement child closes an investigation issue itself, so CLOSED is no
         // proof close.md ran (board, summary, trajectory). Its own idempotency key is the
         // FORGE:TRAJECTORY comment; only that makes this satisfied.
+        // forge#3772: investigation exits are normally single-phase (close.md C1 skips the
+        // multi-phase guard for them); a trusted current-cycle PHASE:COMPLETE is accepted as a
+        // safety net so a multi-phase body cannot make every retry fail.
         try {
-          return { satisfied: await hasTrajectory(state.issue, io), terminalReason: "investigation" };
+          return { satisfied: await hasInvestigationCloseEvidence(state.issue, io), terminalReason: "investigation" };
         } catch { return { satisfied: false }; }
       }
       if (snap.state === "CLOSED") return { satisfied: true };
@@ -1006,7 +1060,7 @@ export const PHASES = [
         // The issue is always already CLOSED for an investigation run, so require the same
         // positive evidence as reconcile (a trusted FORGE:TRAJECTORY); fail closed on error.
         let ran = false;
-        try { ran = await hasTrajectory(state.issue, io); } catch { ran = false; }
+        try { ran = await hasInvestigationCloseEvidence(state.issue, io); } catch { ran = false; }
         return ran
           ? { status: "committed", terminalReason: "investigation", outputs: {} }
           : { status: "failed", detail: "investigation close: no FORGE:TRAJECTORY" };

package/bin/engine/runlog.mjs

@@ -63,6 +63,9 @@ export function deriveState(events) {
   let lastCommitReason = null;
   // forge#3754: phase of the LAST PHASE_COMMIT, so a reopen can tell a remediate-terminal run.
   let lastCommitPhase = null;
+  // forge#3772: reason of the LAST RUN_TERMINAL, so a reopen can tell a needs-human terminal
+  // (label cleared by a human) from an engine-error retry.
+  let lastTerminalReason = null;
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -85,6 +88,7 @@ export function deriveState(events) {
         break;
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
+        lastTerminalReason = s.terminalReason;
         break;
       // forge#3511: an explicit `run-issue --retry` reopens an engine-error
       // terminal. Bumping `v` makes the local state newer than the stale
@@ -97,9 +101,15 @@ export function deriveState(events) {
         // forge#3754: a remediate that ended needs-human is re-run after a human clears the
         // label. Un-commit it (new array, no in-place mutation) so the forge#3506 resume guard
         // does not re-terminate and remediate's entryCondition re-selects it.
-        if (lastCommitPhase === "remediate" && lastCommitReason === "needs-human") {
+        // forge#3772: only when the terminal being reopened was itself needs-human (the engine
+        // reopens that only after a live read shows the label cleared). An engine-error retry
+        // keeps remediate committed so the resume guard is not bypassed.
+        if (lastCommitPhase === "remediate" && lastCommitReason === "needs-human"
+            && lastTerminalReason === "needs-human") {
           s.committed = s.committed.filter((p) => p !== "remediate");
         }
+        lastTerminalReason = null;
+        s.lastRateLimit = null; // forge#3791: an explicit reopen never re-enters a stale pause
         break;
       // forge#3562: an explicit `run-issue --retry` on a `phase-complete` run
       // (multi-phase issue: this phase merged, more remain) starts a NEW cycle.
@@ -111,7 +121,8 @@ export function deriveState(events) {
       case "RUN_NEXT_CYCLE":
         s.terminal = false; s.terminalReason = null; s.committed = [];
         s.branch = null; s.pr = null; s.remediationKind = null;
-        lastCommitReason = null; lastCommitPhase = null; s.v = e.seq;
+        lastCommitReason = null; lastCommitPhase = null; lastTerminalReason = null; s.v = e.seq;
+        s.lastRateLimit = null; // forge#3791
         break;
       // forge#2524: a session-limit pause is purely informational — it does
       // NOT touch committed/terminal/terminalReason. The phase that hit the
@@ -120,9 +131,16 @@ export function deriveState(events) {
       // run correctly re-enters pickPhase at the same phase with no special
       // casing needed here beyond recording the diagnostic below.
       case "PHASE_RATE_LIMITED":
-        s.lastRateLimit = { phase: e.phase, resetAt: e.resetAt ?? null, waitMs: e.waitMs ?? null };
+        // forge#3791: backendId is the non-secret identity of the backend/account that hit the limit.
+        s.lastRateLimit = { phase: e.phase, resetAt: e.resetAt ?? null, waitMs: e.waitMs ?? null, backendId: e.backendId ?? null };
         s.v = e.seq;
         break;
+      // forge#3791: the paused phase attempting again means the pause is over. A crash
+      // mid-pause appends no PHASE_START, so a same-backend relaunch still resumes the wait.
+      // `v` is intentionally not bumped.
+      case "PHASE_START":
+        if (s.lastRateLimit && e.phase === s.lastRateLimit.phase) s.lastRateLimit = null;
+        break;
       // PHASE_START / PHASE_FAILED do not change committed state
     }
   }

package/bin/engine.mjs

@@ -4,7 +4,8 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
-import { hostname as osHostname } from "node:os";
+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 { reconcileState } from "./engine/reconcile.mjs";
@@ -36,6 +37,21 @@ export const DEFAULT_MAX_SESSION_LIMIT_PAUSES = 5;
 // the engine and is still capped by `maxSessionLimitPauses`.
 export const DEFAULT_SESSION_LIMIT_WAIT_MS = 30 * 60 * 1000;
 
+/**
+ * forge#3791: non-secret identity of the backend/account a usage-limit pause belongs to.
+ * Truncated sha256 over the resolved backend, the Claude config dir, and a scrypt fingerprint of the
+ * API key (when set; a password KDF, not a bare hash, so the secret is never hashed cheaply). The raw key and path are never emitted.
+ * @param {{backend?: string, env?: object}} [p]
+ * @returns {string} 16 hex chars
+ */
+export function backendIdentity({ backend, env = process.env } = {}) {
+  const sha = (s) => createHash("sha256").update(String(s)).digest("hex");
+  const cfg = env.CLAUDE_CONFIG_DIR || `${homedir()}/.claude`;
+  const key = env.ANTHROPIC_API_KEY
+    ? scryptSync(String(env.ANTHROPIC_API_KEY), "forgedock-backend-identity", 16).toString("hex") : "";
+  return sha(JSON.stringify([backend ?? "auto", cfg, key])).slice(0, 16);
+}
+
 /**
  * Validates the subset of `runIssue()`'s options that must fail fast,
  * synchronously, before any state I/O or timer creation — `backend` and the
@@ -491,10 +507,22 @@ export async function runIssue(opts) {
   // the phase early. Same-host resume reads the LOCAL run-log's lastRateLimit
   // (the remote FORGE:STATE does not carry it). The lease is renewed while we
   // wait so a second relaunch still defers.
-  const rl = local?.lastRateLimit;
+  // forge#3791: after a --retry reopen/next-cycle the reducer cleared the pause, so read the
+  // post-reopen state, not the pre-reopen `local` derive.
+  const rl = (reopened ? state : local)?.lastRateLimit;
   const pendingPhase = pickPhase(state);
-  if (pendingPhase && rl && rl.phase === pendingPhase.id &&
-      typeof rl.resetAt === "number" && Number.isFinite(rl.resetAt) && rl.resetAt > now()) {
+  const currentBackendId = backendIdentity({ backend, env: process.env });
+  const rlApplies = !!(pendingPhase && rl && rl.phase === pendingPhase.id &&
+      typeof rl.resetAt === "number" && Number.isFinite(rl.resetAt) && rl.resetAt > now());
+  // forge#3791: only wait when the pause was recorded by this same backend/account. A record
+  // without backendId (pre-fix) cannot be attributed, so it does not wait.
+  if (rlApplies && rl.backendId !== currentBackendId) {
+    emitProgress({
+      event: "phase_resumed", phase: pendingPhase.id, reason: "session-limit",
+      detail: "rate-limit pause belongs to another backend; not waiting",
+    });
+  }
+  if (rlApplies && rl.backendId === currentBackendId) {
     const waitMs = Math.min(rl.resetAt - now(), MAX_RESUME_RATE_LIMIT_WAIT_MS);
     emitProgress({
       event: "phase_paused", phase: pendingPhase.id, reason: "session-limit", resetAt: rl.resetAt,
@@ -671,7 +699,7 @@ export async function runIssue(opts) {
         let pauseCount = 0;
         for (;;) {
           try {
-            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo });
+            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId });
             break;
           } catch (e) {
             const resetAtMs = e.resetAtEpochMs;
@@ -696,6 +724,7 @@ export async function runIssue(opts) {
             appendEvent(dir, issue, {
               event: "PHASE_RATE_LIMITED", phase: phase.id,
               resetAt: hasResetEpoch ? resetAtMs : null, resetAtDisplay: e.resetAt || null, waitMs,
+              backendId: backendIdentity({ backend, env: process.env }),
             });
             // forge#2524 AC6: progress observer sees the pause so a caller
             // (bin/engine-cli.mjs) can render the wait state instead of the
@@ -785,6 +814,13 @@ export async function runIssue(opts) {
       (outcome.outputs?.pr ?? state.pr) != null;
     if (outcome.status === "blocked") {
       emitProgress({ event: "phase_exit", phase: phase.id, status: "blocked", detail: outcome.detail });
+      // forge#3792: remediate deferring to a live earlier run is neither a commit nor a terminal: a RUN_TERMINAL or
+      // PHASE_COMMIT would strand the PR (`deferred` is not --retry-able, and a committed remediate lets `close` run on
+      // an unmerged PR). Release our lease and exit with nothing written; the next dispatch re-picks remediate.
+      if (phase.id === "remediate" && outcome.reason === "deferred") {
+        await projector.writeState(issue, { ...state, lease: null });
+        return { terminalReason: "deferred", detail: outcome.detail };
+      }
       if (!isRemediationHandoff)
         return await terminate(state, outcome.reason || "needs-human", outcome.detail);
     } else {
@@ -876,7 +912,7 @@ export async function runIssue(opts) {
 }
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo } = ctx;
+  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId } = ctx;
   // forge#3499: build the phase's full argument set ONCE, up front. Every
   // work-on phase sub-skill stops with BLOCKED when a required flag is absent,
   // so an incomplete/invalid set is a deterministic engine failure — fail
@@ -884,7 +920,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
   // `[issue]`-only invocation that burns the attempt budget.
   let phaseArgs;
   try {
-    phaseArgs = await phase.buildArgs(state, { repo: await resolveRepo() }, io);
+    phaseArgs = await phase.buildArgs(state, { repo: await resolveRepo(), agentId }, io);
   } catch (e) {
     if (e?.code !== "PHASE_ARGS_INVALID") throw e;
     const detail = `phase ${phase.id} args unresolved: ${e.message}`;

package/bin/runner.mjs

@@ -52,9 +52,28 @@ import { join, dirname, basename, relative, isAbsolute, extname, win32 as win32P
 import os from "os";
 import { execSync, spawnSync } from "child_process";
 import { createRequire } from "module";
+import { fileURLToPath } from "url";
 import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
 import { DEFAULT_SPAWN_MAX_BUFFER_BYTES } from "./cli-spawn-shared.mjs";
 
+// Package root (the directory that holds bin/, commands/ and scripts/). Exported to every
+// phase child as FORGEDOCK_HOME so spec fences can source scripts/lib/*.sh without a
+// cache scan. A value the operator already set is never overridden.
+/** Windows drive-letter path (C:\x or C:/x) -> /c/x, the form the bash helpers accept; other paths are returned unchanged. */
+export function toPosixRoot(p, platform = process.platform) {
+  if (platform !== "win32") return p;
+  const m = /^([A-Za-z]):[\\/](.*)$/.exec(p);
+  return m ? `/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}` : p.replace(/\\/g, "/");
+}
+
+const FORGEDOCK_PACKAGE_ROOT = toPosixRoot(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** Returns `env` with FORGEDOCK_HOME defaulted to the package root (never overriding a set value). */
+export function withForgedockHome(env) {
+  if (!env.FORGEDOCK_HOME) env.FORGEDOCK_HOME = FORGEDOCK_PACKAGE_ROOT;
+  return env;
+}
+
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_MAX_TOKENS = 16384;
@@ -1391,7 +1410,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 = { ...process.env };
+    const childEnv = withForgedockHome({ ...process.env });
     delete childEnv.ANTHROPIC_API_KEY;
 
     // No `shell` option (defaults to false): argv is passed as discrete,
@@ -2182,7 +2201,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 = { ...process.env };
+      const childEnv = withForgedockHome({ ...process.env });
       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

package/commands/forge-stats.md

@@ -57,8 +57,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 `scripts/check-spec-size.sh` (job `spec-size-budget` in `check-commands.yml`, PRs only) enforces a budget that is independent of the line-count `.baselines`; the baseline is refreshed on release via `/forge-stats baseline`. It compares bytes against the PR base:
 
 - `review-pr.md`, `review-pr-staging.md`, `work-on/remediate.md`, `work-on/review.md`, `work-on.md` may not grow by more than 2% or 4 KB. Shrinking always passes.
-- No `commands/**` file may gain a copy of a canonical block (FORGE_ROOT bootstrap, TRUSTED_SCRIPT/HELPER_SCRIPT resolver, FENCE_BOOTSTRAP anchor); the per-file marker count may not rise. Tighten to an outright ban once the shared helper (#3493) lands.
-- Exemption: the `spec-size-exempt` PR label, or a `<!-- spec-size-exempt: <reason> -->` line in the PR body (non-empty reason). The job summary lists the per-file delta and any waiver.
+- No `commands/**` file may gain a copy of a canonical block (FORGE_ROOT bootstrap, TRUSTED_SCRIPT/HELPER_SCRIPT resolver, FENCE_BOOTSTRAP anchor); the per-file marker count may not rise. The shared helpers (`scripts/lib/forge-resolve.sh`, `scripts/lib/fence-bootstrap.sh`) are sourced through marker-free stubs, so a conversion reads as a net reduction.
+- Exemption: the `spec-size-exempt` PR label only (needs triage rights; a PR-body marker is not honoured). The job summary lists the per-file delta and any waiver.
 
 ---
 

package/commands/orchestrate/phase-1-resolve.md

@@ -204,26 +204,9 @@ Phase 1 resolves `$ARGUMENTS` to a concrete issue-number list exactly once, at T
 Classify `$ARGUMENTS` and persist that classification alongside the resolved issue-number list, so Phase 4 (`phase-4-execution.md` Step 4B) can decide whether to re-run the query later in the batch:
 
 ```bash
-# FORGE_ROOT bootstrap (canonical; keep byte-identical across specs, guarded by scripts/forge-root.test.sh)
-FORGE_ROOT=""
-# Windows drive-letter FORGEDOCK_HOME (C:/x or C:\x) is normalized to /c/x (cygpath when present); relative values stay rejected.
-_h="${FORGEDOCK_HOME:-}"; case "$_h" in [A-Za-z]:[/\\]*) _w="$_h"; _h="$(cygpath -u "$_w" 2>/dev/null || true)"; [ -n "$_h" ] || _h="/$(printf %s "$_w" | cut -c1 | tr 'A-Z' 'a-z')$(printf %s "${_w#??}" | tr '\\' '/')" ;; esac
-# Only the official marketplace is trusted (name pinned; override only via the trusted FORGEDOCK_MARKETPLACE env, never repo files).
-_mk="${FORGEDOCK_MARKETPLACE:-forgedock}"; case "$_mk" in ""|.|..|*[!A-Za-z0-9._-]*) _mk="forgedock" ;; esac
-if [ -n "${FORGEDOCK_HOME:-}" ]; then case "$_h" in /*) FORGE_ROOT="$_h" ;; esac; else
-  # Portable to bash 3.2 (macOS), BSD/GNU coreutils and zsh: no mapfile, no sort -V, no bare globs (zsh aborts on no match). Every assignment ends in || true so the block survives set -e / pipefail.
-  _l="$HOME/.claude/commands/work-on.md"; _l="$(readlink -f "$_l" 2>/dev/null || readlink "$_l" 2>/dev/null || true)"; [ -n "$_l" ] && _l="$(dirname "$(dirname "$_l")")"
-  # Codex: install-codex.sh records the clone path in $CODEX_HOME/forge-home (one absolute path); skills are generated files, not symlinks.
-  _cx="${CODEX_HOME:-$HOME/.codex}"; case "$_cx" in /*) _x="$(head -n 1 "$_cx/forge-home" 2>/dev/null || true)" ;; *) _x="" ;; esac
-  # newest cached version first: numeric major.minor.patch of the version dir name only (non-semver names such as commit SHAs are skipped); a release outranks its pre-release (1.10.0 > 1.9.0 > 1.9.0-rc1)
-  _v="$(find -L "$HOME/.claude/plugins/cache" -mindepth 3 -maxdepth 3 -type d 2>/dev/null | awk -F/ -v mk="$_mk" '$(NF-2)==mk && $(NF-1)=="forgedock" && $NF ~ /^[0-9]+\.[0-9]+\.[0-9]+(-.*)?$/{v=$NF;p=index(v,"-");r=1;if(p){v=substr(v,1,p-1);r=0};split(v,a,".");printf "%d %d %d %d %s\n",a[1],a[2],a[3],r,$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr -k4,4nr | cut -d' ' -f5- || true)"
-  _m="$HOME/.claude/plugins/marketplaces/$_mk"
-  # '${CLAUDE_PLUGIN_ROOT}' is substituted by Claude Code when it loads a plugin spec (the exact spelling only, never as an env var), so a running plugin resolves to its own root first; unsubstituted (other runtimes) it stays a literal that the /* check rejects.
-  _k="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_HOME:-}" "$_l" "$_x" "$_v" "$_m")"
-  while IFS= read -r _c; do
-    case "$_c" in /*) [ -z "$FORGE_ROOT" ] && [ -f "$_c/scripts/verify-phase-trail.sh" ] && [ -f "$_c/scripts/lint-dispatch-prompt.sh" ] && [ -f "$_c/scripts/is-docs-only.sh" ] && [ -f "$_c/bin/engine/resolve.mjs" ] && [ -f "$_c/bin/engine/orchestrate-canary.mjs" ] && [ -f "$_c/bin/engine/admission.mjs" ] && FORGE_ROOT="$_c" ;; esac
-  done <<< "$_k"
-fi
+# FORGE_ROOT: shared resolver scripts/lib/forge-resolve.sh (empty when unresolved => callers fail closed)
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+FORGE_ROOT="$(forge_root 2>/dev/null || true)"
 # Import ForgeDock's OWN resolve.mjs from FORGE_ROOT, never from the consumer {REPO_PATH}
 # (inert on non-ForgeDock repos, and would execute repo-controlled JS). Unresolved/missing => no output,
 # which Phase 4 treats as "literal" (never re-resolve) — fail closed, loudly.
@@ -394,26 +377,9 @@ After executing the plan, retain every ungrouped finding in the registry for the
 # batch metadata as `{number, affectedFile, members, memberCount}`.
 # Run this after initial resolution and every later admission event; execute the
 # returned `groups`/`extensions` member numbers against the repo each candidate came from.
-# FORGE_ROOT bootstrap (canonical; keep byte-identical across specs, guarded by scripts/forge-root.test.sh)
-FORGE_ROOT=""
-# Windows drive-letter FORGEDOCK_HOME (C:/x or C:\x) is normalized to /c/x (cygpath when present); relative values stay rejected.
-_h="${FORGEDOCK_HOME:-}"; case "$_h" in [A-Za-z]:[/\\]*) _w="$_h"; _h="$(cygpath -u "$_w" 2>/dev/null || true)"; [ -n "$_h" ] || _h="/$(printf %s "$_w" | cut -c1 | tr 'A-Z' 'a-z')$(printf %s "${_w#??}" | tr '\\' '/')" ;; esac
-# Only the official marketplace is trusted (name pinned; override only via the trusted FORGEDOCK_MARKETPLACE env, never repo files).
-_mk="${FORGEDOCK_MARKETPLACE:-forgedock}"; case "$_mk" in ""|.|..|*[!A-Za-z0-9._-]*) _mk="forgedock" ;; esac
-if [ -n "${FORGEDOCK_HOME:-}" ]; then case "$_h" in /*) FORGE_ROOT="$_h" ;; esac; else
-  # Portable to bash 3.2 (macOS), BSD/GNU coreutils and zsh: no mapfile, no sort -V, no bare globs (zsh aborts on no match). Every assignment ends in || true so the block survives set -e / pipefail.
-  _l="$HOME/.claude/commands/work-on.md"; _l="$(readlink -f "$_l" 2>/dev/null || readlink "$_l" 2>/dev/null || true)"; [ -n "$_l" ] && _l="$(dirname "$(dirname "$_l")")"
-  # Codex: install-codex.sh records the clone path in $CODEX_HOME/forge-home (one absolute path); skills are generated files, not symlinks.
-  _cx="${CODEX_HOME:-$HOME/.codex}"; case "$_cx" in /*) _x="$(head -n 1 "$_cx/forge-home" 2>/dev/null || true)" ;; *) _x="" ;; esac
-  # newest cached version first: numeric major.minor.patch of the version dir name only (non-semver names such as commit SHAs are skipped); a release outranks its pre-release (1.10.0 > 1.9.0 > 1.9.0-rc1)
-  _v="$(find -L "$HOME/.claude/plugins/cache" -mindepth 3 -maxdepth 3 -type d 2>/dev/null | awk -F/ -v mk="$_mk" '$(NF-2)==mk && $(NF-1)=="forgedock" && $NF ~ /^[0-9]+\.[0-9]+\.[0-9]+(-.*)?$/{v=$NF;p=index(v,"-");r=1;if(p){v=substr(v,1,p-1);r=0};split(v,a,".");printf "%d %d %d %d %s\n",a[1],a[2],a[3],r,$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr -k4,4nr | cut -d' ' -f5- || true)"
-  _m="$HOME/.claude/plugins/marketplaces/$_mk"
-  # '${CLAUDE_PLUGIN_ROOT}' is substituted by Claude Code when it loads a plugin spec (the exact spelling only, never as an env var), so a running plugin resolves to its own root first; unsubstituted (other runtimes) it stays a literal that the /* check rejects.
-  _k="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_HOME:-}" "$_l" "$_x" "$_v" "$_m")"
-  while IFS= read -r _c; do
-    case "$_c" in /*) [ -z "$FORGE_ROOT" ] && [ -f "$_c/scripts/verify-phase-trail.sh" ] && [ -f "$_c/scripts/lint-dispatch-prompt.sh" ] && [ -f "$_c/scripts/is-docs-only.sh" ] && [ -f "$_c/bin/engine/resolve.mjs" ] && [ -f "$_c/bin/engine/orchestrate-canary.mjs" ] && [ -f "$_c/bin/engine/admission.mjs" ] && FORGE_ROOT="$_c" ;; esac
-  done <<< "$_k"
-fi
+# FORGE_ROOT: shared resolver scripts/lib/forge-resolve.sh (empty when unresolved => callers fail closed)
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+FORGE_ROOT="$(forge_root 2>/dev/null || true)"
 # Import ForgeDock's OWN admission.mjs from FORGE_ROOT, never from the consumer {REPO_PATH}.
 # Unresolved/missing => no plan: every candidate stays an ungrouped singleton (fail closed, loudly).
 BATCH_PLAN=""