tgc.church#285: serialize WP-Cron batches per site

[superdav42]

Summary

• make WP-Cron tracking keys independent of bootstrap/domain-routing URLs
• identify Action Scheduler jobs by site ID and durable action ID
• serialize WP-Cron subprocess batches per site across Workerman children with renewable database leases
• preserve parallel processing across different sites and requeue batches when subprocess spawning fails
• document and regression-test the new execution model

Root cause

Production evidence from superdav42/tgc.church#285 showed that scanner and executor representations of the same recurring event could use different site URLs. Because the URL was part of the tracking key, both representations could bypass the shared job claim. Separate Workerman children could then execute overlapping batches for one site and race while updating WordPress's cron option.

The new per-site lease complements the route-independent event identity: one WP-Cron batch may write a site's cron state at a time, while other sites and Action Scheduler lanes retain their existing concurrency.

Refs superdav42/tgc.church#285.

Verification

• composer test:regression
• composer validate --strict
• php -l src/class-job-payload.php
• php -l src/class-worker-process.php
• php -l tests/regression.php
• git diff --check origin/main...HEAD
• aidevops pre-commit quality validation

PHPStan was also attempted after installing the declared development dependencies. Repository-wide analysis currently reports pre-existing dependency/stub and legacy findings (including Workerman, WP-CLI, and Action Scheduler symbols), so it is not a passing repository gate for this change.

---

aidevops.sh v3.32.229 plugin for OpenCode v1.18.9 with gpt-5.6-sol

Summary by CodeRabbit

• New Features

  • Added shared per-site locking for scheduled tasks to prevent overlapping WP-Cron processing across workers.
  • Active cron leases refresh during processing and are released when work completes, times out, or cannot start.
  • Failed task launches are restored for later processing.
  • Action Scheduler tracking now remains stable across routing changes.

• Documentation

  • Updated architecture documentation to describe cron lease handling and batch completion.

[coderabbitai]

Warning

Review limit reached

@superdav42, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b939739-39ab-4a5f-b370-09cb18480d10

📥 Commits

Reviewing files that changed from the base of the PR and between 7277e15 and 794923b.

📒 Files selected for processing (2)

• src/class-worker-process.php
• tests/regression.php

📝 Walkthrough

Walkthrough

WP-Cron batches now acquire shared per-site leases before spawning. Workers refresh leases during polling and release them after completion, timeout, or spawn failure. Tracking keys now use stable identifiers independent of routing URLs.

Changes

WP-Cron lease execution

Layer / File(s)	Summary
Tracking key identity src/class-job-payload.php, tests/regression.php	Action Scheduler keys use site and action IDs. WP-Cron keys no longer depend on site URLs.
Site lease storage and lifecycle src/class-worker-process.php, tests/regression.php	The worker creates the cron site-lock table and supports exclusive claims, expiry replacement, owner-only refresh, and owner-only release.
Worker lease orchestration src/class-worker-process.php, tests/regression.php, README.md	WP-Cron batches claim leases before spawning. Workers refresh and release leases, restore batches after spawn failures, and document the updated flow. Regression tests cover lease behavior and timer deduplication.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• Ultimate-Multisite/the-perfect-wp-cron#23: Both changes modify Job_Payload::tracking_key() and WP-Cron processing.
• Ultimate-Multisite/the-perfect-wp-cron#24: Both changes modify Action Scheduler handling in class-worker-process.php.
• Ultimate-Multisite/the-perfect-wp-cron#56: Both changes modify WP-Cron worker scheduling for per-site payloads.

Suggested labels: review-feedback-scanned, origin:interactive

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: serializing WP-Cron batches per site.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bugfix/gh285-cron-serialization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/class-worker-process.php`:
- Around line 16-17: Rename the class constants CRON_SITE_LOCK_TTL_SECONDS and
CRON_SITE_LOCK_REFRESH_SECONDS to QW_CRON_SITE_LOCK_TTL_SECONDS and
QW_CRON_SITE_LOCK_REFRESH_SECONDS, and update every reference to use the new
names.
- Around line 736-742: Update the cron lease renewal branch in the worker
process loop around refresh_cron_site_lock() so a false result immediately
terminates and reaps the subprocess, rather than continuing its batch. Preserve
the existing timestamp update on successful renewal, and add a regression test
that simulates renewal failure while the subprocess is active and verifies
termination and reaping.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 715afa90-aca6-44f1-a8ad-bbec69addd7d

📥 Commits

Reviewing files that changed from the base of the PR and between 7c153b0 and 7277e15.

📒 Files selected for processing (4)

• README.md
• src/class-job-payload.php
• src/class-worker-process.php
• tests/regression.php