forgedock 1.4.0 → 1.5.0

package/bin/engine/runlog.mjs

@@ -57,7 +57,7 @@ export function deriveState(events) {
   /** @type {import("./phases.mjs").RunState} */
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
-              terminalReason: null, lease: null };
+              terminalReason: null, lease: null, lastRateLimit: null };
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -72,6 +72,16 @@ export function deriveState(events) {
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
         break;
+      // forge#2524: a session-limit pause is purely informational — it does
+      // NOT touch committed/terminal/terminalReason. The phase that hit the
+      // pause is, by construction, not yet committed (the engine is about to
+      // retry it from scratch once the wait elapses), so a resumed/hydrated
+      // 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 };
+        s.v = e.seq;
+        break;
       // PHASE_START / PHASE_FAILED do not change committed state
     }
   }

package/bin/engine-cli.mjs

@@ -365,6 +365,12 @@ export async function runFromCli(argv, deps = {}) {
     if (e.event === "phase_enter") console.log(`→ phase ${e.phase} started`);
     else if (e.event === "phase_exit" && e.status === "committed") console.log(`✓ phase ${e.phase} committed`);
     else if (e.event === "phase_exit" && e.status === "blocked") console.log(`✗ phase ${e.phase} blocked: ${e.detail ?? "no detail"}`);
+    // forge#2524: session-limit pause — the engine is waiting in-process
+    // until the reported reset time before retrying this same phase, rather
+    // than terminating. Distinct glyph from the exit/blocked lines above so
+    // an operator tailing this stdout can tell "still alive, just waiting"
+    // from "phase actually failed".
+    else if (e.event === "phase_paused") console.log(`⏸ phase ${e.phase} paused: ${e.detail ?? "session limit"}`);
   };
   const res = await runIssueFn({ issue, dir, agentId, lane, io,
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),

package/bin/engine.mjs

@@ -20,65 +20,31 @@ export const DEFAULT_MAX_ATTEMPTS = 3;
 export const DEFAULT_LEASE_TTL_MS = 600000;
 export const DEFAULT_LEASE_RENEW_INTERVAL_MS = 240000;
 
+// forge#2524: bounds how many consecutive session-limit pauses a single
+// phase attempt will ride out before falling through to the existing
+// engine-error terminate path. Exists purely as a defensive backstop against
+// a persistently-misparsed/misreported reset time (clock skew, a CLI that
+// always claims "resets in 1 minute" for some unrelated reason) spinning the
+// engine forever — a genuine multi-hour session-limit reset is expected to
+// need at most one or two pauses in practice.
+export const DEFAULT_MAX_SESSION_LIMIT_PAUSES = 5;
+
 /**
- * @param {object} opts
- * @param {string} [opts.backend] - "cli" | "api" | "auto" (forge#2028). Forwarded
- *   to every phase's `runner()` call when supplied. Omit to keep runner.mjs's own
- *   default ("auto" ladder — probes the `claude` CLI, falls back to the API).
- *   An invalid value throws synchronously (see below) rather than being forwarded.
- * @param {string} [opts.model] - Model id (forge#2028). Forwarded to every phase's
- *   `runner()` call when supplied; only applies on the "api" backend. Omit to keep
- *   runner.mjs's default (`FORGEDOCK_MODEL` env or its built-in default).
- * @param {number} [opts.leaseTtlMs] - forge#2239: how long a claimed lease is
- *   valid for. Defaults to DEFAULT_LEASE_TTL_MS. Overridable for tests.
- * @param {number} [opts.leaseRenewIntervalMs] - forge#2239: how often the lease
- *   is re-written while an unsatisfied phase's runner is executing. Defaults to
- *   DEFAULT_LEASE_RENEW_INTERVAL_MS. Overridable for tests.
- * @param {(event: {event: string, phase: string, status?: string, detail?: string}) => void} [opts.onProgress] -
- *   forge#2240: optional phase-boundary observer. Called with
- *   `{event: "phase_enter", phase}` right before a phase's runner is about to
- *   execute (i.e. the phase was NOT already satisfied on reconcile), and with
- *   `{event: "phase_exit", phase, status: "committed"|"blocked", detail?}`
- *   once that phase's outcome is known. Defaults to a no-op so every existing
- *   caller/test is unaffected. Deliberately engine.mjs's ONLY new surface for
- *   this issue — no `console.log`/stdout write is added here; printing is the
- *   CLI layer's job (bin/engine-cli.mjs), preserving the io-injection/testability
- *   convention this module already follows. Invocations are wrapped so a
- *   throwing callback can never crash a run.
+ * Validates the subset of `runIssue()`'s options that must fail fast,
+ * synchronously, before any state I/O or timer creation — `backend` and the
+ * lease-timing pair. Extracted from `runIssue()` (forge#2452) purely for
+ * readability; call-order and thrown-error shape are unchanged from the
+ * inline block this replaces, and MUST stay that way — see the per-check
+ * rationale comments below, all of which trace back to real review findings.
+ *
+ * @param {object} params
+ * @param {string} [params.backend] - "cli" | "api" | "auto" (forge#2028).
+ * @param {number} params.leaseTtlMs - forge#2239: how long a claimed lease is valid for.
+ * @param {number} params.leaseRenewIntervalMs - forge#2239: how often the lease is re-written.
+ * @param {number} params.maxSessionLimitPauses - forge#2524: bound on consecutive session-limit pauses.
+ * @throws {Error & {code: "INVALID_BACKEND"|"INVALID_LEASE_CONFIG"|"INVALID_SESSION_LIMIT_CONFIG"}}
  */
-export async function runIssue(opts) {
-  const { issue, dir, agentId, lane = "staging", io, runner,
-          now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
-          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)),
-          // Optional execution-backend override for every phase's `runner()`
-          // call (forge#2028 / MAT-3). Left undefined by default so existing
-          // callers keep runner.mjs's own "auto" ladder default unchanged —
-          // this is purely additive pass-through, not a new default.
-          backend, model,
-          leaseTtlMs = DEFAULT_LEASE_TTL_MS,
-          leaseRenewIntervalMs = DEFAULT_LEASE_RENEW_INTERVAL_MS,
-          onProgress = () => {} } = opts;
-
-  // forge#2240: defensive wrapper — a caller's onProgress must never be able
-  // to crash an otherwise-healthy run. A plain try/catch only guards a
-  // *synchronous* throw — if onProgress is (or becomes) async and its
-  // returned promise rejects, that rejection is never awaited/caught here,
-  // producing an unhandled promise rejection that terminates the whole
-  // Node process (Node >=15 default behavior) well after runIssue() itself
-  // has already resolved. That is strictly worse than the silent-hang bug
-  // this issue fixes. Detect a thenable return value and attach a no-op
-  // .catch() to it (fire-and-forget — onProgress is not awaited either way,
-  // consistent with its documented synchronous-observer contract) so a
-  // rejection can never escape as unhandled. (review finding, #2240)
-  const emitProgress = (event) => {
-    try {
-      const result = onProgress(event);
-      if (result && typeof result.then === "function") {
-        result.catch(() => { /* best-effort observer, never fatal */ });
-      }
-    } catch { /* best-effort observer, never fatal */ }
-  };
-
+function validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses }) {
   // forge#2054: validate `backend` before anything else — before state is
   // read/written and before the phase/retry loop begins below. An invalid
   // value must fail fast and non-retryably. Without this check, an invalid
@@ -147,6 +113,125 @@ export async function runIssue(opts) {
     );
   }
 
+  // forge#2524: same finite-number + non-negative guard precedent as the
+  // lease-timing pair above (forge#2329) — a NaN/negative pause bound would
+  // either silently disable the pause-count backstop (every relational
+  // comparison against NaN is false, so `pauseCount < maxSessionLimitPauses`
+  // would never trip) or reject every pause immediately (a negative bound).
+  // Validated eagerly here, synchronously, before any state I/O or timer
+  // creation — identical placement rationale to the checks above.
+  if (typeof maxSessionLimitPauses !== "number" || !Number.isFinite(maxSessionLimitPauses) || maxSessionLimitPauses < 0) {
+    throw Object.assign(
+      new Error(
+        `Invalid session-limit config: maxSessionLimitPauses must be a finite number >= 0, got ${typeof maxSessionLimitPauses === "number" ? maxSessionLimitPauses : `${typeof maxSessionLimitPauses} (${JSON.stringify(maxSessionLimitPauses)})`}.`,
+      ),
+      { code: "INVALID_SESSION_LIMIT_CONFIG" },
+    );
+  }
+}
+
+/**
+ * Builds the defensive `emitProgress` wrapper around a caller-supplied
+ * `onProgress` observer. Extracted from `runIssue()` (forge#2452) — purely a
+ * factory, no shared state beyond the `onProgress` closure itself, so this
+ * carries no behavioral risk.
+ *
+ * forge#2240: a caller's onProgress must never be able to crash an otherwise
+ * healthy run. A plain try/catch only guards a *synchronous* throw — if
+ * onProgress is (or becomes) async and its returned promise rejects, that
+ * rejection is never awaited/caught here, producing an unhandled promise
+ * rejection that terminates the whole Node process (Node >=15 default
+ * behavior) well after runIssue() itself has already resolved. That is
+ * strictly worse than the silent-hang bug this issue fixes. Detect a
+ * thenable return value and attach a no-op .catch() to it (fire-and-forget —
+ * onProgress is not awaited either way, consistent with its documented
+ * synchronous-observer contract) so a rejection can never escape as
+ * unhandled. (review finding, #2240)
+ *
+ * @param {(event: {event: string, phase: string, status?: string, detail?: string}) => void} onProgress
+ * @returns {(event: object) => void}
+ */
+function makeProgressEmitter(onProgress) {
+  return (event) => {
+    try {
+      const result = onProgress(event);
+      if (result && typeof result.then === "function") {
+        result.catch(() => { /* best-effort observer, never fatal */ });
+      }
+    } catch { /* best-effort observer, never fatal */ }
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.backend] - "cli" | "api" | "auto" (forge#2028). Forwarded
+ *   to every phase's `runner()` call when supplied. Omit to keep runner.mjs's own
+ *   default ("auto" ladder — probes the `claude` CLI, falls back to the API).
+ *   An invalid value throws synchronously (see below) rather than being forwarded.
+ * @param {string} [opts.model] - Model id (forge#2028). Forwarded to every phase's
+ *   `runner()` call when supplied; only applies on the "api" backend. Omit to keep
+ *   runner.mjs's default (`FORGEDOCK_MODEL` env or its built-in default).
+ * @param {number} [opts.leaseTtlMs] - forge#2239: how long a claimed lease is
+ *   valid for. Defaults to DEFAULT_LEASE_TTL_MS. Overridable for tests.
+ * @param {number} [opts.leaseRenewIntervalMs] - forge#2239: how often the lease
+ *   is re-written while an unsatisfied phase's runner is executing. Defaults to
+ *   DEFAULT_LEASE_RENEW_INTERVAL_MS. Overridable for tests.
+ * @param {(event: {event: string, phase: string, status?: string, detail?: string, resetAt?: number}) => void} [opts.onProgress] -
+ *   forge#2240: optional phase-boundary observer. Called with
+ *   `{event: "phase_enter", phase}` right before a phase's runner is about to
+ *   execute (i.e. the phase was NOT already satisfied on reconcile), with
+ *   `{event: "phase_exit", phase, status: "committed"|"blocked", detail?}`
+ *   once that phase's outcome is known, and (forge#2524) with
+ *   `{event: "phase_paused", phase, reason: "session-limit", resetAt, detail}`
+ *   when a session-limit hit pauses in-process (see the pause/retry loop
+ *   below). Defaults to a no-op so every existing caller/test is unaffected.
+ *   Deliberately engine.mjs's ONLY new surface for this issue — no
+ *   `console.log`/stdout write is added here; printing is the CLI layer's job
+ *   (bin/engine-cli.mjs), preserving the io-injection/testability convention
+ *   this module already follows. Invocations are wrapped so a throwing
+ *   callback can never crash a run.
+ * @param {() => number} [opts.now] - clock, overridable for tests.
+ * @param {(ms: number) => Promise<void>} [opts.sleep] - forge#2524: the wait
+ *   primitive used by the session-limit pause loop below. Defaults to a real
+ *   `setTimeout`-based sleep. Overridable for tests so the suite never
+ *   actually waits out a real (potentially multi-hour) session-limit reset —
+ *   a test injects a fast/no-op sleep and asserts the *requested* duration
+ *   instead of waiting for it. Mirrors the existing `now`/`onProgress`
+ *   injectability convention.
+ * @param {number} [opts.maxSessionLimitPauses] - forge#2524: caps how many
+ *   consecutive session-limit pauses a single phase attempt will ride out
+ *   before falling through to the existing engine-error terminate path.
+ *   Defaults to DEFAULT_MAX_SESSION_LIMIT_PAUSES. Purely a defensive backstop
+ *   against a persistently-misreported reset time; a genuine reset is
+ *   expected to need at most one or two pauses in practice.
+ */
+export async function runIssue(opts) {
+  const { issue, dir, agentId, lane = "staging", io, runner,
+          now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
+          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)),
+          // Optional execution-backend override for every phase's `runner()`
+          // call (forge#2028 / MAT-3). Left undefined by default so existing
+          // callers keep runner.mjs's own "auto" ladder default unchanged —
+          // this is purely additive pass-through, not a new default.
+          backend, model,
+          leaseTtlMs = DEFAULT_LEASE_TTL_MS,
+          leaseRenewIntervalMs = DEFAULT_LEASE_RENEW_INTERVAL_MS,
+          // forge#2524: real default is a genuine setTimeout-based wait —
+          // tests inject a fast/no-op replacement (see opts.sleep doc above).
+          sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+          maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES,
+          onProgress = () => {} } = opts;
+
+  // forge#2452: extracted into makeProgressEmitter() — see its docstring for
+  // the forge#2240 rationale this wrapper implements.
+  const emitProgress = makeProgressEmitter(onProgress);
+
+  // forge#2452: extracted into validateRunIssueOptions() — see its docstring
+  // for the forge#2054/#2313/#2329 rationale and required call-order (before
+  // any state I/O or timer creation, unchanged from the inline block this
+  // replaces).
+  validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses });
+
   const projector = makeProjector(io);
 
   // 1. Load + reconcile (GitHub wins).
@@ -328,7 +413,56 @@ export async function runIssue(opts) {
       const renewTimer = setInterval(renewLease, leaseRenewIntervalMs);
       if (typeof renewTimer.unref === "function") renewTimer.unref();
       try {
-        outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model });
+        // forge#2524: bounded pause/retry loop for a genuine, still-future
+        // session-limit hit. `runPhaseWithRetry()` itself remains fail-fast
+        // for CLI_BACKEND_FAILED (forge#2259 — a deterministic CLI crash
+        // reproduces identically on every attempt within one call) — this
+        // loop operates one layer up, deciding whether to call it again from
+        // scratch (fresh attempt budget) after waiting out a temporary usage
+        // cap, rather than treating every CLI_BACKEND_FAILED as equally
+        // fatal. `renewTimer` (started above) keeps renewing the lease for
+        // the entire duration of this loop, including any `sleep()` below —
+        // no separate heartbeat mechanism is needed for the wait itself.
+        let pauseCount = 0;
+        for (;;) {
+          try {
+            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model });
+            break;
+          } catch (e) {
+            const resetAtMs = e.resetAtEpochMs;
+            const canPause =
+              e.code === "CLI_BACKEND_FAILED" &&
+              typeof resetAtMs === "number" && Number.isFinite(resetAtMs) &&
+              resetAtMs > now() &&
+              pauseCount < maxSessionLimitPauses;
+            if (!canPause) throw e; // falls through to the unchanged outer catch below
+            pauseCount += 1;
+            const waitMs = Math.max(0, resetAtMs - now());
+            // forge#2524 AC4: append a run-log event so a crash mid-wait
+            // leaves a durable record of the pause (deriveState() folds this
+            // into RunState.lastRateLimit — see bin/engine/runlog.mjs). This
+            // does NOT touch committed/terminal state: the phase genuinely
+            // hasn't committed yet, so a resumed run correctly re-enters
+            // pickPhase at this same phase regardless of whether this event
+            // was ever written.
+            appendEvent(dir, issue, {
+              event: "PHASE_RATE_LIMITED", phase: phase.id,
+              resetAt: resetAtMs, resetAtDisplay: e.resetAt || null, waitMs,
+            });
+            // forge#2524 AC6: progress observer sees the pause so a caller
+            // (bin/engine-cli.mjs) can render the wait state instead of the
+            // process going silent for the duration.
+            emitProgress({
+              event: "phase_paused", phase: phase.id, reason: "session-limit",
+              resetAt: resetAtMs,
+              detail: `session limit hit — pausing until ${e.resetAt || new Date(resetAtMs).toISOString()}`,
+            });
+            await sleep(waitMs);
+            // Loop back and retry the same phase with a fresh attempt budget
+            // (a brand-new runPhaseWithRetry() call, not a continuation of
+            // the exhausted one) — AC2.
+          }
+        }
       } catch (e) {
         // forge#2261: NO_API_KEY/NO_SDK/CLI_BACKEND_FAILED are fail-fast
         // rethrown by runPhaseWithRetry() (see its own catch below) instead
@@ -569,5 +703,6 @@ function eventsFromIndex(idx) {
 
 function freshState(issue, lane) {
   return { v: 0, run: `r_${issue}_${lane}`, issue, lane, committed: [], phase: null,
-           branch: null, pr: null, terminal: false, terminalReason: null, lease: null };
+           branch: null, pr: null, terminal: false, terminalReason: null, lease: null,
+           lastRateLimit: null };
 }

package/bin/forgedock.mjs

@@ -1792,11 +1792,47 @@ async function update() {
         ).trim();
         if (porcelain) {
           console.log(
-            `  ${YELLOW}Working tree has uncommitted changes on branch ${branch} — skipping update.${RESET}`,
-          );
-          console.log(
-            `  ${YELLOW}Commit or stash your changes before updating, or run from a clean clone. HEAD was NOT moved.${RESET}`,
+            `  ${YELLOW}Working tree has uncommitted changes on branch ${branch} — skipping git-based update.${RESET}`,
           );
+
+          // forge#2460 — distinguish "developing on this checkout" from a
+          // dirty git-clone install elsewhere with unrelated changes. The
+          // former (npx-shadowing: FORGE_HOME resolves to the directory the
+          // user is physically running the CLI from) has a git-independent
+          // fallback available — relinkAndHint() only copies commands/hooks
+          // off disk, it never touches git state, so it's safe to run on a
+          // dirty tree. HEAD is still never moved in either case.
+          const cwdResolved = resolve(process.cwd());
+          const forgeHomeResolved = resolve(FORGE_HOME);
+          const isSourceRepoSelf =
+            cwdResolved === forgeHomeResolved ||
+            cwdResolved.startsWith(forgeHomeResolved + sep);
+
+          if (isSourceRepoSelf) {
+            console.log(
+              `  ${YELLOW}This looks like the ForgeDock source repo itself — syncing commands/hooks from the working tree instead (HEAD was NOT moved).${RESET}`,
+            );
+            // forge#2493 — relinkAndHint() is wrapped in its own try/catch
+            // here so a failure inside it (forge()/writeInstallReceipt()
+            // disk-write errors) doesn't fall through to the outer catch
+            // below, which prints a fast-forward/merge message that would be
+            // actively wrong for this path — no fast-forward or merge is
+            // ever attempted when isSourceRepoSelf is true.
+            try {
+              await relinkAndHint();
+            } catch (relinkErr) {
+              console.log(
+                `  ${YELLOW}Could not sync commands/hooks from the working tree: ${relinkErr.message}${RESET}`,
+              );
+            }
+            console.log(
+              `  To pull the latest published release instead: ${CYAN}npm install -g forgedock@latest && npx forgedock doctor --fix${RESET}`,
+            );
+          } else {
+            console.log(
+              `  ${YELLOW}Commit or stash your changes before updating, or run from a clean clone. HEAD was NOT moved.${RESET}`,
+            );
+          }
           return;
         }
 
@@ -3845,6 +3881,31 @@ switch (command) {
     const localVersion = getVersion();
     console.log(`forgedock ${localVersion ? `v${localVersion}` : `${YELLOW}version unknown${RESET}`}`);
 
+    // forge#2460 — getVersion() always reads FORGE_HOME/package.json. In a
+    // git-clone install (including the npx-shadowing case where FORGE_HOME
+    // resolves to whatever checkout the CLI is being run from), that's this
+    // checkout's own version — not necessarily what a separate global npm
+    // install elsewhere would report. Surface that ambiguity explicitly
+    // rather than letting this read as "the" installed version, mirroring
+    // the disambiguation messaging update() already prints (forge#2220).
+    // WIRE:PROVEN — manual: every existing "version command" test in
+    // bin/tests/router.test.mjs spawns this actual bin/forgedock.mjs file,
+    // whose FORGE_HOME resolves to this repo's own git-clone root (a real
+    // .git directory), so this guard evaluates true on every run of that
+    // suite (`node --test bin/tests/router.test.mjs`, confirmed passing).
+    // findSeparateGlobalInstall() itself fails closed to null on any error
+    // (see its JSDoc) and is exercised by the "update — global npm install
+    // self-update" suite below via the same resolveGlobalNpmForgedockDir()
+    // helper it shares with isGlobalNpmInstall().
+    if (existsSync(join(FORGE_HOME, ".git"))) {
+      const separateGlobalInstall = findSeparateGlobalInstall();
+      if (separateGlobalInstall) {
+        console.log(
+          `  ${YELLOW}Note: this is the git clone at ${FORGE_HOME}. Your global npm install at ${separateGlobalInstall} may report a different version.${RESET}`,
+        );
+      }
+    }
+
     const latestVersion = await fetchLatestVersion();
     if (latestVersion && localVersion && compareVersions(latestVersion, localVersion) > 0) {
       console.log(

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

@@ -720,12 +720,34 @@ function checkLabelTransition(command) {
 
   // Evidence precondition (#2326): reaching workflow:invalid from
   // ready-to-build/building/in-review is structurally allowed above, but
-  // still gated against *casual* invalidation — a bare relabel with no
-  // paper trail is blocked. Require a posted reversal comment (a second
-  // FORGE:INVESTIGATOR annotation carrying "**Verdict**: INVALID") already
-  // on the issue before allowing the transition through, from a trusted
-  // author (issue #2332 — marker text alone is forgeable by anyone who can
-  // comment on a public issue; see TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS).
+  // still gated against *casual* invalidation — see checkInvalidReversalEvidence()
+  // below for the full rationale and evidence requirements.
+  const evidenceError = checkInvalidReversalEvidence(newLabel, currentWorkflowLabel, comments);
+  if (evidenceError) return evidenceError;
+
+  return null; // valid transition — allow
+}
+
+/**
+ * Evidence precondition (#2326): reaching workflow:invalid from
+ * ready-to-build/building/in-review is structurally allowed by the label
+ * transition state machine, but still gated against *casual* invalidation —
+ * a bare relabel with no paper trail is blocked. Require a posted reversal
+ * comment (a second FORGE:INVESTIGATOR annotation carrying "**Verdict**:
+ * INVALID") already on the issue before allowing the transition through,
+ * from a trusted author (issue #2332 — marker text alone is forgeable by
+ * anyone who can comment on a public issue; see
+ * TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS).
+ *
+ * Extracted from checkLabelTransition() (issue #2453) as a separable
+ * sub-concern — same inputs/outputs, no behavior change.
+ *
+ * @param {string} newLabel
+ * @param {string|null} currentWorkflowLabel
+ * @param {Array|null} comments
+ * @returns {string|null} Error message to show, or null if allowed.
+ */
+function checkInvalidReversalEvidence(newLabel, currentWorkflowLabel, comments) {
   if (newLabel === "workflow:invalid" && EVIDENCE_REQUIRED_FOR_INVALID_FROM.has(currentWorkflowLabel)) {
     if (!hasInvalidReversalEvidence(comments)) {
       return [
@@ -747,7 +769,7 @@ function checkLabelTransition(command) {
     }
   }
 
-  return null; // valid transition — allow
+  return null; // no evidence required, or evidence present — allow
 }
 
 // ---------------------------------------------------------------------------