feat: yield background review under exact pressure

[vincentkoc]

Related: #542 (closed; superseded)

Depends on: #555 (merged as 41ea43b)

What Problem This Solves

Periodic and commit-review background work can consume the worker budget needed to drain an exact-review backlog. Operators had no opt-in admission policy that causes lower-priority broad-review lanes to yield when exact review is congested or saturated.

Why This Change Was Made

This is the scheduler/admission-policy portion of closed contributor PR #542. It deliberately consumes the durable exact_review_queue.generated_at and exact_review_queue.pressure.status contract published by #555 instead of duplicating pressure classification.

When explicitly enabled, the policy:

• caps shared background review at 16 workers when exact review is congested and 4 when it is saturated;
• subtracts already-active background workers before admitting another broad planner;
• serializes background admission through one shared workflow lock;
• re-evaluates caps on continuation and defers zero-cap commit work by requeueing the same range;
• fails open to normal capacity when telemetry is missing, malformed, stale, or unknown.

Exact-review, repair, apply, and other priority lanes remain outside this background cap. The default behavior remains unchanged until CLAWSWEEPER_ENABLE_EXACT_REVIEW_BACKGROUND_YIELD=1 is explicitly set.

User Impact

With the opt-in variable enabled, broad work yields capacity when the exact-review lane is under pressure. This is a safe guardrail, not a replacement for #545's recovery work and not a fix for post-review state-ledger/lease-completion contention.

Evidence

• The original exact-head GitHub CI passed 7/7, including pnpm check.
• After integrating merged feat(dashboard): expose exact-review pressure telemetry #555, disposable Linux-container proof passed: pnpm run build:all and node --test test/sweep-workflow.test.ts test/repair/workflow-utils.test.ts dist/repair/workflow-utils.test.js — 115/115 passing. The container copy normalized Windows checkout CRLF only; no tracked file was changed.
• pnpm run check:limits passed in the same Linux container.
• git diff --check origin/main...HEAD passed.
• Codex cleanup review: codex review --uncommitted clean for the release-owned changelog removal.
• Codex final review: codex review --base origin/main clean with no actionable findings after feat(dashboard): expose exact-review pressure telemetry #555 integration.
• The local actionlint image reports the repository's pre-existing queue: max concurrency extension, including occurrences already on main; GitHub Actions' own Analyze (actions) check is the authoritative validation for this workflow syntax.

Maintainer follow-up — 2026-07-14

• Removed the contributor-added unreleased CHANGELOG.md entry; release notes are release-owned in this repository.
• draft: optional exact-review background-yield experiment #542 was closed because feat(dashboard): expose exact-review pressure telemetry #555 is the observation/telemetry slice and this PR is the dependent scheduler-policy slice.
• Keep the feature disabled until maintainers decide to trial it and observe queue-drain, lease-completion, and publisher-health metrics.
• The policy and extraction retain attribution to brokemac79 in the original commits.

[brokemac79]

Confirmed against #542: this is the opt-in background-yield scheduler slice. #542 is being closed as superseded.

Please land #555 first: this PR consumes its durable exact_review_queue.generated_at and exact_review_queue.pressure.status contract. It is a contention guardrail, not a replacement for #545's completion-burst recovery, and remains disabled until CLAWSWEEPER_ENABLE_EXACT_REVIEW_BACKGROUND_YIELD=1 is explicitly set.

I am removing the release-owned CHANGELOG.md entry before merge; it is not part of this normal feature PR.