Plugin Directory: Serve a release immediately when Gandalf reports no findings

[obenland]

The release delay (#650) buys a window for scanners and humans to flag a bad release before it reaches sites. Gandalf (#634) fills the automated half. The two don't talk to each other, so the window is spent in full on every release — including the overwhelming majority a scanner has already cleared.

This closes the loop: when a Gandalf scan completes with no findings, the version it scanned stops waiting and starts being served. Findings still go to Slack for a reviewer. A scan that fails or never reports back leaves the delay to elapse on its own — silence never shortens the wait.

Changes

serve_release_now() replaces force_release(). Both do the same thing — clear a release's delay and write it to update_source — so a reviewer force-releasing and a clean scan now share one path, differing only in the $reason they log.

The version is checked in one place. serve_release_now() takes the version explicitly and re-checks it against the plugin's current one. Callers act on a version they evaluated earlier — a reviewer reading the metabox, a scanner reading a ZIP — and a newer commit can land in between; serving a stale version would skip the wait on a release nobody evaluated. The metabox did this check itself and force_release() didn't; now there's one implementation.

The author's manual-updates-24hr window is preserved. Serving early still dates the release from the moment it goes public, not from the commit, so phased_rollout()'s author-set window runs its full length from availability. A clean scan that arrives after the delay already elapsed leaves the served version untouched.

Payload validation is restored, as an args schema on the route. #634 dropped it while the verdict was advisory, where the worst case was a wrong Slack message. That no longer holds now that the verdict publishes releases: (int) 'abc' is 0, so an absent or malformed findings_count would read as a clean scan. Failing toward "keep waiting" costs time; failing toward "serve" quietly removes a supply-chain control.

Test environment fixes (first commit) — update_source was never created, env-bin wasn't mapped, and PLUGINS_TABLE_PREFIX was undefined, which fatalled API\Base::load_routes() and 404'd every REST request in the test environment.

Tests

25 new tests. Release_Delay_Test covers the delay lifecycle — including the gate itself, and that serving early preserves the manual-updates window — which had no coverage. Gandalf_Scan_Callback_Test drives the real REST route end to end.

Test plan

• A callback with findings_count: 0 serves the scanned version immediately and zeroes release_delay; the audit log names the scan.
• A clean scan serves early without shortening the manual-updates-24hr window (auto-updates still gated for 24h from publication).
• A callback with findings leaves the release waiting and alerts Slack as before.
• A callback whose version no longer matches the plugin's current version is refused.
• A callback with a missing, non-numeric, or negative findings_count returns 400 and does not serve.
• A callback without a valid bearer secret returns 401.
• A failed scan records _gandalf_scan_last_error and leaves the delay running.
• Reviewer force-release from the Controls metabox still works, with the reason in the audit log.
• With WPORG_PLUGIN_THEME_RELEASE_DELAY unset (delay 0), nothing changes.

Notes for review

• This is a policy change, not just a code change. The delay's stated purpose is a window for "scanners and humans". Ending it on a clean scan removes the human half for the releases Gandalf clears — which is the intent, but worth agreeing on explicitly, since the releases that most need human eyes are the ones a scanner missed. A shorter-but-nonzero delay on clean scans is the alternative.
• Not addressed: notify_slack() still passes severity_counts and verdict_hash through unsanitized (verdict_hash becomes an unbounded post-meta array key).
• Not addressed: Plugin Directory: Send plugin updates to Gandalf for advisory scans #633's contract fixtures were dropped along with its tests, so nothing on our side catches drift between the callback we accept and the callback that's sent.

🤖 Generated with Claude Code

https://claude.ai/code/session_019ngq7zaYBfv2zS8dnjFoUG

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props obenland, lucasbustamante.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Luc45]

Thanks for putting this together.

I have limited context on the WPORG side, so my review will focus mostly on the Gandalf side.

Nonblocking follow-ups

There's two issues that I think we could tackle in a follow-up, that doesn't have to hold this PR.

• Same reference, different ZIP. A ZIP can change during a scan without changing its version or release ref, so WPORG could accelerate an artifact Gandalf never scanned. Follow up by returning the scanned ZIP digest and comparing it with the current ZIP before acceleration.
• Zero findings, incomplete coverage. Gandalf can complete with zero findings even when prompt-security could not scan everything within its budget; WPORG cannot currently tell. Follow up by returning coverage status so WPORG can withhold acceleration when coverage is incomplete.

Recent Gandalf data shows that about 99% of attempted scans complete, so I’m comfortable handling these separately.

WPORG clarification

Just to be clear, since I’m not familiar with the WPORG side, the way I understand it there are two separate cooldowns:

• The older one, from 2025: manual-updates-24hr. From the phased rollout work in Meta Trac #8009 and PR #498, once the version is offered through the update API this allows manual updates but disables automatic updates for 24 hours.
• The newer one, from 2026: release_delay. From PR #650, this happens first: the update API continues offering the previous version for the configured delay, leaving time for scanners and reviewers to act.

My understanding is that the intended effect of this PR is only to end release_delay early, which seems expected. I've created this diagram below to wrap my head around how those two cooldowns behave, and how this PR changes it, let me know if this looks accurate to you.

Before this PR
                                             ■ release_delay      □ manual-updates-24hr
                                        0h                      24h                     48h
                                        ├───────────────────────┼───────────────────────┤
No clean callback                       ■■■■■■■■■■■■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□□□□□□□□
                                                                ↑M                      ↑A
Clean result at +2h (not acted on)      ■■■■■■■■■■■■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□□□□□□□□
                                                                ↑M                      ↑A
Clean result at +26h (not acted on)     ■■■■■■■■■■■■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□□□□□□□□
                                                                ↑M                      ↑A

After this PR
                                             ■ release_delay      □ manual-updates-24hr
                                        0h                      24h                     48h
                                        ├───────────────────────┼───────────────────────┤
No clean callback                       ■■■■■■■■■■■■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□□□□□□□□
                                                                ↑M                      ↑A
Clean callback at +2h                   ■■□□□□□□□□□□□□□□□□□□□□□□
                                          ↑M                    ↑A
Clean callback at +26h                  ■■■■■■■■■■■■■■■■■■■■■■■■□□
                                                                ↑M↑A

Each square represents one hour. ↑M marks when the new version becomes available as a manual update to existing installations; ↑A marks when it becomes eligible for automatic updates.

That is what the code appears to do. Before merging, does this look accurate and intentional to you?

My review is limited to the Gandalf side, so it may be useful to have a WPORG reviewer confirm these points.

[obenland]

I'm not sure about the "Clean callback at +26h" section, but the rest looks good. 27cddb6 is meant to make that clearer, anchoring manual-updates-24hr to release time as intended, rather than commit time, which it was implicitly. Thanks for that review!