review: clamp the run budget to the effective credit cap; land before the cap

[jwbron]

Closes the budget-shed gap the v1.4.0-preview behavior test exposed (Khan/webapp#40737, run 29051903691): the tier budget table is sized inside the workflow's assumed $10 ceiling, but the per-run credit cap is enforced runner-side by the firewall api-proxy and is invisible in-container. A consumer with a tighter max-ai-credits therefore got soft targets the hard cap could not pay for: the 400-credit test run planned against the high tier's $10 targets (its own words: the cap was 'unobservable to me mid-run'), shed only the opt-in reviewers, spent 390 credits on the finder phase, and was killed by the api-proxy mid-persist with findings in hand and nothing posted.

Changes

• Frontmatter: max-ai-credits: 1000 is now explicit (matches the gh-aw default) and mirrored into the agent environment as env: REVIEW_MAX_AI_CREDITS, with a keep-in-sync note for consumer overrides. gh-aw compiles env: to workflow-level env and the firewall's --env-all forwards it into the agent container (verified against a scratch compile and the v0.81.6 lock).
• Router (lib/router.ts): resolveCreditCap resolves the effective cap (mirror env, GH_AW_MAX_AI_CREDITS, a visible awf config's apiProxy.maxAiCredits, then the 1000-credit default); clampBudgetToCreditCap scales the selected tier's soft targets proportionally, floored at the trivial tier's values, and marks runBudget.capClamped + runBudget.effectiveCreditCap in routing.json. Zero/negative caps mean explicitly uncapped; the pure route() core takes the cap as config, so non-CLI callers (eval suite) are unaffected.
• Prompt (budget section): notes that runBudget is cap-clamped and that capClamped means dispatch-conservatively; adds an estimated-credits proxy (sum of in-band subagent_tokens over completed sub-agents divided by 5,000, derivation documented inline from measured runs at ~9,000 summed tokens per credit); makes two proxy checkpoints mandatory, the critical one immediately after the last finder returns and before Phase 3 validation, the exact boundary the observed run died at.

With the clamp, the 400-credit scenario's targets become 4 invocations / 8 minutes / $4, so the existing three-quarters rule trips during the finder phase and the run sheds stages 2-3 and lands a partial review instead of dying.

Test plan

• pnpm run test --run: 708 tests green (new: clamp scaling incl. the 400-credit incident shape, trivial floors, uncapped sentinels, resolveCreditCap source priority and fallbacks, runCli env integration).
• pnpm run typecheck: clean.
• Re-running the webapp budget-shed behavior test on this branch is the acceptance check; expected: shed stages observed in order and a verdict lands with skipped-dimension notes.

Stacked on #243 (batch two).

Human steps (non-review)

• Acceptance re-run (the budget-shed behavior test this PR exists to fix, per the Khan/webapp#40737 record): branch off webapp's review-bot-v1.4.0-preview (still alive), re-pin review-preview.md's pre-agent-steps ref and source: to jwies/review-budget-cap, set max-ai-credits: 400, gh aw compile, push, and stack a copy of the seeded PR on it. Pass = the run lands a verdict with skipped-dimension notes instead of dying at the cap. ~$4 of credits.
• Record the outcome here and in the round-two doc before merge.

---

Update 2026-07-09: landing reserve

The acceptance re-run showed the clamp engaging and the run still dying at the hard cap (416/400 mid-skill-audit): the clamped soft target equaled the cap, and spend that is unobservable mid-run plus in-flight work billing after the last checkpoint left no room to land. The clamp now sets the soft dollar target to 75% of the effective cap (LANDING_RESERVE_RATIO) and scales the other targets to match, engages whenever the tier target sits above the reserve-adjusted cap (not only above the raw cap), and review.md now tells the orchestrator that maxUsd is a landing target, never money it may finish spending. Acceptance: re-run the budget-shed test on the kept-alive webapp scaffold at cap 400; expected shape is shed-early, land inside 400.

[github-actions]

nitpick (non-blocking): This PR inserts a blank line after the runCli doc-comment's */, so that doc block now floats above extractFileList (which has its own comment) rather than sitting on runCli. Move the Read + parse the staged inputs... block down to sit immediately above export const runCli.

[jeresig]

Can this read that env at all? Looking at https://github.github.com/gh-aw/reference/environment-variables it's not apparent to me how ENV variables are made available to an agent?

[jwbron]

It can, verified two ways: a scratch compile at v0.81.6 shows frontmatter env: rendering as a workflow-level env: block in the lock (so it's in the agent step's environment), and the agent step launches the firewall with sudo -E awf ... --env-all, which forwards the step environment into the agent container minus the excluded secrets. The router CLI runs inside that container and reads it from process.env. The docs page covers gh-aw's own runtime variables, and notably GH_AW_MAX_AI_CREDITS is only set in the later conclusion job, not the agent step; that gap is why the mirror exists.

Two caveats worth recording: consumers that override max-ai-credits (this repo's own wrapper sets 2500) must add the matching mirror when they bump to the release carrying this, or the clamp falls back to the 1000 default (safe direction, but under-uses the cap); and the clean long-term fix is upstream, asking gh-aw to expose the cap in the agent step env natively, which would delete the mirror and its keep-in-sync rule.

[github-actions]

Review Guidance

github-actions (3 files)

File	Reason
credit-cap.ts	New shared enforcement module (credit-cap resolution + budget clamp) that bounds every consumer PR's review, so a defect changes how reviews are scoped across all consumers.
router.ts	Deterministic routing/budget core for the shared reviewer; this change wires the new clamp into computeRunBudget and threads env through runCli.
review.md	The executable reviewer prompt plus its security-bearing frontmatter; this diff changes the frontmatter (max-ai-credits + the REVIEW_MAX_AI_CREDITS env mirror).

Common patterns

2 files: Split the DEFAULT_TIER_BUDGETS table and DEFAULT_MISROUTED_FLOOR_TIER constant verbatim out of router.ts into a new budgets.ts (router.ts was over the max-lines limit after the main merge), re-exported through router.ts so it stays the single routing entry point.

- export const DEFAULT_TIER_BUDGETS: Record<RiskTier, RunBudget> = { ... }  // removed from router.ts
+ import {DEFAULT_MISROUTED_FLOOR_TIER, DEFAULT_TIER_BUDGETS} from "./budgets";
+ export {DEFAULT_MISROUTED_FLOOR_TIER, DEFAULT_TIER_BUDGETS};               // re-export in router.ts

Excluded from review (1 file)

Not individually reviewed — generated, formatting-only, or fully explained by a common pattern above:

• workflows/review/lib/budgets.ts — pattern-only (Common patterns)