forgedock 1.3.0 → 1.4.0

package/bin/batch-runner.mjs

@@ -112,6 +112,33 @@ export function classifyRunnerResult(result) {
   return "incomplete";
 }
 
+/**
+ * forge#2377: derive a numeric "cost" (docs/spec/eval-run-result.md's
+ * `cost: null | number` field — a billed-token proxy, not a USD amount; see
+ * forge#2397) from a runCommand() result's `usage` object. `runCommand()`
+ * (bin/runner.mjs, since #1295/PR #1421) already accumulates
+ * `{input_tokens, output_tokens, cache_creation_input_tokens,
+ * cache_read_input_tokens}` for the API backend. The CLI backend
+ * (`runCliBackend()`) also returns a best-effort-parsed `usage` object on its
+ * success path since forge#2398/PR #2421 — `usage: null` from the CLI
+ * backend now only occurs when the CLI's `--output-format json` envelope
+ * could not be parsed (older CLI version, or a non-JSON stdout), not
+ * unconditionally. This reports total billed tokens (input + output; cache
+ * reads/writes are not separately billed at the standard rate and are
+ * omitted from this proxy) as the numeric cost signal — converting to a USD
+ * amount requires a per-model pricing table, which is out of this issue's
+ * scope (recording usage, not pricing it) and is left to a follow-up.
+ *
+ * @param {{input_tokens?: number, output_tokens?: number}|null|undefined} usage
+ * @returns {number|null}
+ */
+export function tokenCost(usage) {
+  if (!usage) return null;
+  const input = usage.input_tokens ?? 0;
+  const output = usage.output_tokens ?? 0;
+  return input + output;
+}
+
 /**
  * Construct a per-run result object conforming to docs/spec/eval-run-result.md.
  *
@@ -120,7 +147,9 @@ export function classifyRunnerResult(result) {
  * @param {object} [opts]
  * @param {number} [opts.wallClockMs]        - Wall-clock duration (ms).
  * @param {number} [opts.interventionCount]  - Human intervention count.
- * @param {number|null} [opts.cost]          - Token cost (null until #1255).
+ * @param {number|null} [opts.cost]          - Total billed tokens (input + output), or null when
+ *                                              the run produced no usage data (CLI backend, or an
+ *                                              errored run). See tokenCost() (forge#2377).
  * @param {number} [opts.iterations]         - Tool-loop iteration count.
  * @param {string} [opts.stopReason]         - Anthropic stop_reason or "max_iterations".
  * @param {string|null} [opts.error]         - Error message when status === "error".
@@ -236,7 +265,7 @@ export async function runCorpus(opts = {}) {
         makeRunResult(issue, status, {
           wallClockMs,
           interventionCount: 0,
-          cost: null, // wired in once #1255 lands
+          cost: tokenCost(result.usage),
           iterations: result.iterations ?? null,
           stopReason: result.stopReason ?? null,
           model: model ?? result.model ?? null,

package/bin/engine/admission.mjs

@@ -0,0 +1,294 @@
+/**
+ * Cascade admission policy — orchestration.cascade config surface (forge#2234).
+ *
+ * `/orchestrate`'s resource limits (`orchestration.max_concurrent`,
+ * `pipeline.token_budget_per_batch`, `pipeline.stall_timeout_minutes`, ...)
+ * were configurable, but the *admission policy* deciding whether a
+ * cascade-spawned review-finding is picked up was not — every rule
+ * (generation >= 2 cap, BATCH_FULLY_GATED idle defer, comment/typo keyword
+ * heuristic, P3 + same-file overlap) was a hardcoded constant baked into
+ * `commands/orchestrate/phase-4-execution.md` prose (see forge#1814,
+ * forge#1858, forge#2231). This module gives that policy a typed, unit-tested
+ * home: preset expansion + independently-settable granular levers, with the
+ * same validate-warn-fall-back idiom the rest of `orchestration.*`/`pipeline.*`
+ * already uses (see phase-4-execution.md L108-119 for the bash mirror of this
+ * idiom applied to `orchestration.max_concurrent`).
+ *
+ * This module is the typed reference implementation of the policy the prose
+ * specs (`commands/orchestrate/phase-4-execution.md`,
+ * `commands/orchestrate/phase-1-resolve.md`) read via `yq` at runtime — the
+ * bash blocks in those files mirror the resolution rules below by hand
+ * (the orchestrator is LLM-executed prose, not a `bin/engine/` call site),
+ * so any change to the preset table or defaults here MUST be mirrored there
+ * too. Keeping this module in `bin/engine/` gives the resolution logic a
+ * place to be unit-tested in isolation from the prose pipeline.
+ *
+ * Evidence this config surface addresses (see forge#2234 issue body): a
+ * cascade admitted via the pre-#2234 `--allow-gen2` all-or-nothing CLI flag
+ * (forge#2231) ran generation 2 -> 3 -> 4, drifting from "the engine silently
+ * kills entire batches" (gen 2, real value) to "a log sanitizer does not
+ * neutralize Unicode bidi-override characters" (gen 4, diminishing value).
+ * A binary flag cannot express "admit gen-2, stop at gen-3" or "admit
+ * cascade until N tokens spent" — `max_generation` and `token_budget` below
+ * are independent levers precisely so that shape of policy is expressible.
+ *
+ * Hard invariant (NOT configurable by design): safety exclusions — findings
+ * whose `## Problem` section indicates security/billing/anti-bot/auth
+ * concerns — are never batched and never auto-admitted by ANY policy,
+ * including `all`. That exclusion lives upstream of this module (the P3
+ * batching eligibility check in `phase-1-resolve.md` / the surface-area
+ * batching check in `phase-4-execution.md`) and is intentionally absent
+ * from the levers this module resolves.
+ */
+
+/** Sentinel string accepted anywhere an "int | unlimited" lever is read. */
+export const UNLIMITED = "unlimited";
+
+/**
+ * @typedef {Object} CascadePolicy
+ * @property {number|typeof UNLIMITED} maxGeneration - Max cascade generation depth
+ *   admitted. 1 = only original (non-review-finding-spawned) issues; a
+ *   review-finding whose source is itself a review-finding is generation 2,
+ *   and so on up the chain. `unlimited` removes the cap entirely.
+ * @property {number|typeof UNLIMITED} tokenBudget - Per-batch token ceiling for
+ *   Step 4C's review-finding cascade dispatch (mirrors, and by default reads
+ *   through to, `pipeline.token_budget_per_batch`). `unlimited` removes the cap.
+ * @property {boolean} deferOnBatchGated - Whether a fully-human-gated original
+ *   batch (forge#1814's `BATCH_FULLY_GATED`) suppresses further cascade dispatch.
+ * @property {boolean} keywordHeuristic - Whether the comment/typo title keyword
+ *   heuristic defers P3-and-below findings.
+ * @property {boolean} p3SameFileDefer - Whether a P3 finding sharing a file with
+ *   the active batch is deferred.
+ */
+
+/**
+ * Named presets. Each expands to a full `CascadePolicy` — every field can
+ * still be overridden individually on top of a preset (see `resolveCascadePolicy`).
+ *
+ * - `balanced` (default): the pre-#2234 hardcoded behavior, unchanged so an
+ *   absent `orchestration.cascade` section is a no-op.
+ * - `all`: "pick up everything" — a maintainer draining a backlog. Removes
+ *   both caps and disables every heuristic-based defer. Safety exclusions
+ *   (see module docstring) still apply — they are not part of this table.
+ * - `conservative`: same admission shape as `balanced`, but a materially
+ *   lower token ceiling for cost-sensitive or noisy repos.
+ *
+ * @type {Record<string, CascadePolicy>}
+ */
+export const CASCADE_PRESETS = Object.freeze({
+  all: Object.freeze({
+    maxGeneration: UNLIMITED,
+    tokenBudget: UNLIMITED,
+    deferOnBatchGated: false,
+    keywordHeuristic: false,
+    p3SameFileDefer: false,
+  }),
+  balanced: Object.freeze({
+    maxGeneration: 1,
+    tokenBudget: 900000,
+    deferOnBatchGated: true,
+    keywordHeuristic: true,
+    p3SameFileDefer: true,
+  }),
+  conservative: Object.freeze({
+    maxGeneration: 1,
+    tokenBudget: 450000,
+    deferOnBatchGated: true,
+    keywordHeuristic: true,
+    p3SameFileDefer: true,
+  }),
+});
+
+export const DEFAULT_CASCADE_POLICY_NAME = "balanced";
+
+/**
+ * Parse a raw config value that may be a positive integer, the literal
+ * string "unlimited" (case-insensitive), or absent/invalid. Mirrors the
+ * validate-warn-fall-back idiom used for `orchestration.max_concurrent`
+ * (phase-4-execution.md L112-119: `grep -qP '^[1-9][0-9]*$'` -> warn + default)
+ * but additionally threads the `unlimited` sentinel through, which that
+ * plain positive-int check would otherwise reject (see forge#2234 "Known
+ * Pitfalls": an `unlimited` value hitting the un-updated int-only validator
+ * silently degrades to the default and the uncap becomes a no-op).
+ *
+ * @param {unknown} raw
+ * @param {number|typeof UNLIMITED} fallback
+ * @returns {{ value: number|typeof UNLIMITED, warning: string|null }}
+ */
+export function parseIntOrUnlimited(raw, fallback) {
+  if (raw === undefined || raw === null || raw === "null" || raw === "") {
+    return { value: fallback, warning: null };
+  }
+  if (typeof raw === "string" && raw.trim().toLowerCase() === UNLIMITED) {
+    return { value: UNLIMITED, warning: null };
+  }
+  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
+  if (Number.isInteger(n) && n > 0) {
+    return { value: n, warning: null };
+  }
+  return {
+    value: fallback,
+    warning: `not a positive integer or "unlimited" ("${raw}") — falling back to default ${fallback}`,
+  };
+}
+
+/**
+ * Expand `orchestration.cascade` config into a fully-resolved `CascadePolicy`.
+ * Precedence: explicit granular key > preset value > `balanced` preset value.
+ * An unrecognized `policy` name falls back to `balanced` with a warning,
+ * following the same validate-warn-fall-back idiom as every other
+ * `orchestration.*`/`pipeline.*` key.
+ *
+ * @param {Object} [config] - Parsed `orchestration.cascade` object from
+ *   forge.yaml (or undefined/empty when the section is absent — a no-op
+ *   that resolves to `balanced` exactly like today's hardcoded behavior).
+ * @param {string} [config.policy]
+ * @param {number|string} [config.max_generation]
+ * @param {number|string} [config.token_budget]
+ * @param {boolean} [config.defer_on_batch_gated]
+ * @param {boolean} [config.keyword_heuristic]
+ * @param {boolean} [config.p3_same_file_defer]
+ * @param {number|string} [legacyTokenBudgetPerBatch] - Deprecated-alias fallback:
+ *   `pipeline.token_budget_per_batch`, read when `config.token_budget` is absent
+ *   so existing configs keep working unchanged (see forge#1858).
+ * @returns {{ policy: CascadePolicy, policyName: string, bothUncapped: boolean, warnings: string[] }}
+ */
+export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
+  const warnings = [];
+  const requestedName =
+    typeof config.policy === "string" && config.policy.trim() !== ""
+      ? config.policy.trim()
+      : DEFAULT_CASCADE_POLICY_NAME;
+
+  let policyName = requestedName;
+  let preset = CASCADE_PRESETS[requestedName];
+  if (!preset) {
+    warnings.push(
+      `orchestration.cascade.policy "${requestedName}" is not one of: ${Object.keys(CASCADE_PRESETS).join(", ")} — falling back to "${DEFAULT_CASCADE_POLICY_NAME}"`,
+    );
+    policyName = DEFAULT_CASCADE_POLICY_NAME;
+    preset = CASCADE_PRESETS[DEFAULT_CASCADE_POLICY_NAME];
+  }
+
+  const maxGen = parseIntOrUnlimited(config.max_generation, preset.maxGeneration);
+  if (maxGen.warning) warnings.push(`orchestration.cascade.max_generation ${maxGen.warning}`);
+
+  // token_budget precedence: orchestration.cascade.token_budget (new home) >
+  // pipeline.token_budget_per_batch (deprecated alias, forge#1858) > preset default.
+  // The legacy fallback is validated through parseIntOrUnlimited itself before use —
+  // NOT trusted as-is — so a malformed legacy value (0, negative, NaN, a
+  // case-mismatched sentinel like "UNLIMITED") cannot silently bypass validation
+  // the way a bare pass-through would (forge#2302).
+  const { value: validatedLegacyFallback, warning: legacyWarning } = parseIntOrUnlimited(
+    legacyTokenBudgetPerBatch,
+    preset.tokenBudget,
+  );
+  if (legacyWarning) warnings.push(`pipeline.token_budget_per_batch (legacy alias) ${legacyWarning}`);
+  const tokenBudgetFallback =
+    legacyTokenBudgetPerBatch !== undefined ? validatedLegacyFallback : preset.tokenBudget;
+  const tokenBudget = parseIntOrUnlimited(config.token_budget, tokenBudgetFallback);
+  if (tokenBudget.warning) warnings.push(`orchestration.cascade.token_budget ${tokenBudget.warning}`);
+
+  const deferOnBatchGated =
+    typeof config.defer_on_batch_gated === "boolean" ? config.defer_on_batch_gated : preset.deferOnBatchGated;
+  const keywordHeuristic =
+    typeof config.keyword_heuristic === "boolean" ? config.keyword_heuristic : preset.keywordHeuristic;
+  const p3SameFileDefer =
+    typeof config.p3_same_file_defer === "boolean" ? config.p3_same_file_defer : preset.p3SameFileDefer;
+
+  // Both-uncapped notice: neither generation depth nor token spend is bounded this
+  // run. This is never a preset default (no preset in CASCADE_PRESETS sets both to
+  // UNLIMITED... except "all", which does so deliberately) — surface it loudly so an
+  // operator running `policy: all` (or an equivalent granular-override combination)
+  // sees the tradeoff explicitly rather than discovering it from an unexpectedly long
+  // cascade tail. Distinct from the per-parse `warnings` above (which flag malformed
+  // config); this is a policy-shape notice about a valid, fully-resolved configuration.
+  const bothUncapped = maxGen.value === UNLIMITED && tokenBudget.value === UNLIMITED;
+  if (bothUncapped) {
+    warnings.push(
+      "orchestration.cascade: both max_generation and token_budget are unlimited — cascade admission has no upper bound on generation depth or token spend for this run.",
+    );
+  }
+
+  return {
+    policy: {
+      maxGeneration: maxGen.value,
+      tokenBudget: tokenBudget.value,
+      deferOnBatchGated,
+      keywordHeuristic,
+      p3SameFileDefer,
+    },
+    policyName,
+    bothUncapped,
+    warnings,
+  };
+}
+
+/**
+ * @param {number|typeof UNLIMITED} generation - 1-indexed cascade depth of the
+ *   finding being evaluated (1 = original issue, not spawned from a
+ *   review-finding; 2 = spawned from a review-finding; 3 = spawned from a
+ *   finding that was itself spawned from a review-finding; ...).
+ * @param {CascadePolicy} policy
+ * @returns {boolean} true if this generation is admitted by the policy.
+ */
+export function admitsGeneration(generation, policy) {
+  if (policy.maxGeneration === UNLIMITED) return true;
+  return generation <= policy.maxGeneration;
+}
+
+/**
+ * @param {number} projectedSpend - BATCH_TOKEN_SPEND if this unit were admitted.
+ * @param {CascadePolicy} policy
+ * @returns {boolean} true if there is still headroom under the token budget.
+ */
+export function admitsTokenSpend(projectedSpend, policy) {
+  if (policy.tokenBudget === UNLIMITED) return true;
+  return projectedSpend <= policy.tokenBudget;
+}
+
+/**
+ * Evaluate the Step 4C rule chain for a single cascade-spawned finding.
+ * Mirrors `commands/orchestrate/phase-4-execution.md` Step 4C's "Evaluation
+ * order" (rules 0-5) exactly, with rules 0/3/4 gated by the policy's
+ * corresponding toggle and rule 1 governed by `admitsGeneration`. Rule 1
+ * (generation cap) is evaluated for the finding's *computed* generation —
+ * NOT hardcoded to a single-hop "is my source a review-finding" boolean —
+ * so a `max_generation: 3` policy actually distinguishes gen 2 from gen 3,
+ * per the exact gap forge#2234 exists to close (a binary flag cannot say
+ * "admit gen-2, stop at gen-3").
+ *
+ * @param {Object} finding
+ * @param {number} finding.generation - 1-indexed, see `admitsGeneration`.
+ * @param {"P1"|"P2"|"P3"|string} finding.priority
+ * @param {string} finding.title
+ * @param {boolean} finding.sameFileAsBatch
+ * @param {boolean} finding.batchFullyGated
+ * @param {number} finding.projectedTokenSpend
+ * @param {CascadePolicy} policy
+ * @returns {{ admit: boolean, reason: string|null }}
+ */
+export function evaluateCascadeFinding(finding, policy) {
+  if (policy.deferOnBatchGated && finding.batchFullyGated) {
+    return { admit: false, reason: "batch fully human-gated — idle policy" };
+  }
+  if (!admitsGeneration(finding.generation, policy)) {
+    return {
+      admit: false,
+      reason: `generation ${finding.generation} exceeds orchestration.cascade.max_generation (${policy.maxGeneration})`,
+    };
+  }
+  if (finding.priority === "P1" || finding.priority === "P2") {
+    return { admit: true, reason: null };
+  }
+  if (policy.keywordHeuristic && /comment|typo/i.test(finding.title || "")) {
+    return { admit: false, reason: "comment/typo heuristic" };
+  }
+  if (policy.p3SameFileDefer && finding.priority === "P3" && finding.sameFileAsBatch) {
+    return { admit: false, reason: "P3 + same file as batch" };
+  }
+  if (!admitsTokenSpend(finding.projectedTokenSpend, policy)) {
+    return { admit: false, reason: `per-batch token budget exhausted (orchestration.cascade.token_budget=${policy.tokenBudget})` };
+  }
+  return { admit: true, reason: null };
+}

package/bin/engine/admission.test.mjs

@@ -0,0 +1,265 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  UNLIMITED,
+  CASCADE_PRESETS,
+  DEFAULT_CASCADE_POLICY_NAME,
+  parseIntOrUnlimited,
+  resolveCascadePolicy,
+  admitsGeneration,
+  admitsTokenSpend,
+  evaluateCascadeFinding,
+} from "./admission.mjs";
+
+describe("parseIntOrUnlimited", () => {
+  it("parses a positive integer", () => {
+    assert.deepEqual(parseIntOrUnlimited("3", 1), { value: 3, warning: null });
+    assert.deepEqual(parseIntOrUnlimited(3, 1), { value: 3, warning: null });
+  });
+
+  it("parses the unlimited sentinel case-insensitively", () => {
+    assert.deepEqual(parseIntOrUnlimited("unlimited", 1), { value: UNLIMITED, warning: null });
+    assert.deepEqual(parseIntOrUnlimited("UNLIMITED", 1), { value: UNLIMITED, warning: null });
+    assert.deepEqual(parseIntOrUnlimited(" Unlimited ", 1), { value: UNLIMITED, warning: null });
+  });
+
+  it("falls back to default on absent/null/empty with no warning (no-op case)", () => {
+    assert.deepEqual(parseIntOrUnlimited(undefined, 12), { value: 12, warning: null });
+    assert.deepEqual(parseIntOrUnlimited(null, 12), { value: 12, warning: null });
+    assert.deepEqual(parseIntOrUnlimited("null", 12), { value: 12, warning: null });
+    assert.deepEqual(parseIntOrUnlimited("", 12), { value: 12, warning: null });
+  });
+
+  it("warns and falls back on invalid values (zero, negative, non-numeric)", () => {
+    for (const bad of ["0", "-1", "abc", "3.5"]) {
+      const r = parseIntOrUnlimited(bad, 5);
+      assert.equal(r.value, 5);
+      assert.match(r.warning, /falling back to default 5/);
+    }
+  });
+});
+
+describe("resolveCascadePolicy — presets", () => {
+  it("defaults to balanced when no config is given (no-op, matches pre-#2234 hardcoded behavior)", () => {
+    const { policy, policyName, warnings } = resolveCascadePolicy();
+    assert.equal(policyName, DEFAULT_CASCADE_POLICY_NAME);
+    assert.deepEqual(policy, CASCADE_PRESETS.balanced);
+    assert.deepEqual(warnings, []);
+  });
+
+  it("policy: all removes both caps and disables every heuristic", () => {
+    const { policy, warnings } = resolveCascadePolicy({ policy: "all" });
+    assert.equal(policy.maxGeneration, UNLIMITED);
+    assert.equal(policy.tokenBudget, UNLIMITED);
+    assert.equal(policy.deferOnBatchGated, false);
+    assert.equal(policy.keywordHeuristic, false);
+    assert.equal(policy.p3SameFileDefer, false);
+    // "all" leaves both levers uncapped by design — this is the one preset expected to
+    // carry the both-uncapped notice (see "resolveCascadePolicy — both-uncapped notice"
+    // describe block below for the dedicated coverage of that behavior).
+    assert.deepEqual(warnings, [
+      "orchestration.cascade: both max_generation and token_budget are unlimited — cascade admission has no upper bound on generation depth or token spend for this run.",
+    ]);
+  });
+
+  it("policy: conservative keeps balanced's shape but lowers the token budget", () => {
+    const { policy } = resolveCascadePolicy({ policy: "conservative" });
+    assert.equal(policy.maxGeneration, 1);
+    assert.equal(policy.tokenBudget, 450000);
+    assert.equal(policy.deferOnBatchGated, true);
+  });
+
+  it("unrecognized policy name falls back to balanced with a warning", () => {
+    const { policy, policyName, warnings } = resolveCascadePolicy({ policy: "yolo" });
+    assert.equal(policyName, "balanced");
+    assert.deepEqual(policy, CASCADE_PRESETS.balanced);
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], /not one of/);
+  });
+});
+
+describe("resolveCascadePolicy — granular overrides compose with a preset", () => {
+  it("a single granular key overrides just that field, preset supplies the rest", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced", max_generation: "unlimited" });
+    assert.equal(policy.maxGeneration, UNLIMITED);
+    // Everything else still comes from the balanced preset.
+    assert.equal(policy.tokenBudget, 900000);
+    assert.equal(policy.deferOnBatchGated, true);
+    assert.equal(policy.keywordHeuristic, true);
+    assert.equal(policy.p3SameFileDefer, true);
+  });
+
+  it("granular boolean overrides on top of the all preset", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all", defer_on_batch_gated: true });
+    assert.equal(policy.deferOnBatchGated, true);
+    // Unrelated fields remain the all-preset's.
+    assert.equal(policy.maxGeneration, UNLIMITED);
+    assert.equal(policy.keywordHeuristic, false);
+  });
+
+  it("max_generation can express admit-gen-2-stop-at-gen-3 (the case a binary flag cannot)", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all", max_generation: 3 });
+    assert.equal(admitsGeneration(1, policy), true);
+    assert.equal(admitsGeneration(2, policy), true);
+    assert.equal(admitsGeneration(3, policy), true);
+    assert.equal(admitsGeneration(4, policy), false);
+  });
+});
+
+describe("resolveCascadePolicy — token_budget deprecated-alias fallback", () => {
+  it("falls back to legacy pipeline.token_budget_per_batch when orchestration.cascade.token_budget is absent", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" }, 300000);
+    assert.equal(policy.tokenBudget, 300000);
+  });
+
+  it("orchestration.cascade.token_budget wins over the legacy alias when both are set", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced", token_budget: 50000 }, 300000);
+    assert.equal(policy.tokenBudget, 50000);
+  });
+
+  it("validates the legacy fallback itself — a malformed legacy value does not silently bypass validation (forge#2302)", () => {
+    const { policy, warnings } = resolveCascadePolicy({ policy: "balanced" }, -1);
+    // -1 is invalid — must NOT be silently adopted; falls back to the balanced preset default.
+    assert.equal(policy.tokenBudget, 900000);
+    assert.ok(warnings.some((w) => /token_budget_per_batch \(legacy alias\)/.test(w)));
+  });
+
+  it("accepts a valid legacy fallback with no warning", () => {
+    const { policy, warnings } = resolveCascadePolicy({ policy: "balanced" }, 123456);
+    assert.equal(policy.tokenBudget, 123456);
+    assert.ok(!warnings.some((w) => /legacy alias/.test(w)));
+  });
+});
+
+describe("resolveCascadePolicy — both-uncapped notice", () => {
+  it("flags bothUncapped and adds a warning when policy: all leaves both levers unlimited", () => {
+    const { policy, bothUncapped, warnings } = resolveCascadePolicy({ policy: "all" });
+    assert.equal(policy.maxGeneration, UNLIMITED);
+    assert.equal(policy.tokenBudget, UNLIMITED);
+    assert.equal(bothUncapped, true);
+    assert.ok(warnings.some((w) => /both max_generation and token_budget are unlimited/.test(w)));
+  });
+
+  it("flags bothUncapped via a granular override combination, not just the all preset", () => {
+    const { bothUncapped } = resolveCascadePolicy({
+      policy: "balanced",
+      max_generation: "unlimited",
+      token_budget: "unlimited",
+    });
+    assert.equal(bothUncapped, true);
+  });
+
+  it("does not flag bothUncapped when only one lever is uncapped", () => {
+    const { bothUncapped: onlyGenUncapped } = resolveCascadePolicy({
+      policy: "balanced",
+      max_generation: "unlimited",
+    });
+    assert.equal(onlyGenUncapped, false);
+
+    const { bothUncapped: onlyTokenUncapped } = resolveCascadePolicy({
+      policy: "balanced",
+      token_budget: "unlimited",
+    });
+    assert.equal(onlyTokenUncapped, false);
+  });
+
+  it("balanced preset (default, no config) never flags bothUncapped", () => {
+    const { bothUncapped } = resolveCascadePolicy();
+    assert.equal(bothUncapped, false);
+  });
+});
+
+describe("admitsGeneration / admitsTokenSpend", () => {
+  it("unlimited admits any generation and any spend", () => {
+    const policy = CASCADE_PRESETS.all;
+    assert.equal(admitsGeneration(1, policy), true);
+    assert.equal(admitsGeneration(99, policy), true);
+    assert.equal(admitsTokenSpend(0, policy), true);
+    assert.equal(admitsTokenSpend(Number.MAX_SAFE_INTEGER, policy), true);
+  });
+
+  it("balanced caps generation at 1 and token spend at 900000", () => {
+    const policy = CASCADE_PRESETS.balanced;
+    assert.equal(admitsGeneration(1, policy), true);
+    assert.equal(admitsGeneration(2, policy), false);
+    assert.equal(admitsTokenSpend(900000, policy), true);
+    assert.equal(admitsTokenSpend(900001, policy), false);
+  });
+});
+
+describe("evaluateCascadeFinding — Step 4C rule-chain parity", () => {
+  const baseFinding = {
+    generation: 1,
+    priority: "P3",
+    title: "fix: something",
+    sameFileAsBatch: false,
+    batchFullyGated: false,
+    projectedTokenSpend: 0,
+  };
+
+  it("policy: all admits a gen >= 3 finding (the regression this issue's AC requires)", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all" });
+    const result = evaluateCascadeFinding({ ...baseFinding, generation: 3 }, policy);
+    assert.equal(result.admit, true);
+    assert.equal(result.reason, null);
+  });
+
+  it("balanced defers a gen 2 finding even at P3", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding({ ...baseFinding, generation: 2 }, policy);
+    assert.equal(result.admit, false);
+    assert.match(result.reason, /generation 2 exceeds/);
+  });
+
+  it("rule 0: batch fully gated always defers when deferOnBatchGated is true, even for P1", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding(
+      { ...baseFinding, priority: "P1", batchFullyGated: true },
+      policy,
+    );
+    assert.equal(result.admit, false);
+    assert.match(result.reason, /batch fully human-gated/);
+  });
+
+  it("rule 0 is a no-op under policy: all (deferOnBatchGated: false)", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all" });
+    const result = evaluateCascadeFinding({ ...baseFinding, batchFullyGated: true }, policy);
+    assert.equal(result.admit, true);
+  });
+
+  it("priority override: P1/P2 always execute, skipping keyword/same-file heuristics", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding(
+      { ...baseFinding, priority: "P2", title: "comment: typo fix", sameFileAsBatch: true },
+      policy,
+    );
+    assert.equal(result.admit, true);
+  });
+
+  it("keyword heuristic defers a P3 comment/typo finding when enabled", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding({ ...baseFinding, title: "fix: typo in README" }, policy);
+    assert.equal(result.admit, false);
+    assert.match(result.reason, /comment\/typo/);
+  });
+
+  it("keyword heuristic is disabled under policy: all", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all" });
+    const result = evaluateCascadeFinding({ ...baseFinding, title: "fix: typo in README" }, policy);
+    assert.equal(result.admit, true);
+  });
+
+  it("P3 + same-file defers when enabled", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding({ ...baseFinding, sameFileAsBatch: true }, policy);
+    assert.equal(result.admit, false);
+    assert.match(result.reason, /same file/);
+  });
+
+  it("token budget defers a P3 finding once projected spend exceeds the ceiling", () => {
+    const { policy } = resolveCascadePolicy({ policy: "balanced" });
+    const result = evaluateCascadeFinding({ ...baseFinding, projectedTokenSpend: 900001 }, policy);
+    assert.equal(result.admit, false);
+    assert.match(result.reason, /token budget exhausted/);
+  });
+});

package/bin/engine/invariants.mjs

@@ -319,10 +319,23 @@ function evaluateOneCloseAssertion(assertion, events) {
     }
 
     case "issue_closed_at_terminal":
-      // This assertion is evaluated externally (requires a gh CLI call in the
-      // close phase). The evaluator returns ok=true here so callers that do
-      // not pass GitHub state still pass without error. The close.md phase
-      // block implements the actual gh issue view check.
+      // forge#2352: this assertion is enforced inside the engine itself now —
+      // not just "evaluated externally" as the previous version of this
+      // comment claimed. Two real, wired-up call sites cover it:
+      //   1. bin/engine.mjs's runIssue() phase loop: a per-iteration
+      //      divergence guard (`issueSnapshot()` from bin/engine/phases.mjs)
+      //      that terminates the run ("invalid" or "needs-human") the moment
+      //      the issue's live GitHub state/labels diverge from the local
+      //      run-log, for every phase except `close`.
+      //   2. The `close` phase's own reconcile/detectOutcome
+      //      (bin/engine/phases.mjs), which is exempt from (1) because
+      //      reading and acting on exactly this state IS its job.
+      // This function has no GitHub I/O access (it's a pure assertion
+      // evaluator — see the module header), so it cannot re-verify the live
+      // issue state itself; it stays a structural pass-through by design.
+      // The real enforcement lives in the two call sites above — this case
+      // exists so `assertCloseInvariants` callers get a defined, non-throwing
+      // result for this assertion id rather than an unhandled default.
       return { ok: true, id: assertion.id };
 
     default: