[aaronaltman]

Why

The first scheduled run of Control's client reports (Nov 1) compiled a month of drafts and held every one for review, which is intended. We audited those drafts against a copy of production data to see whether the reports are good enough to replace ManageWP's. Several reports contained wrong or misleading content, and some of the causes were fleet bugs rather than report bugs. This PR fixes them and adds the UI the team needs to review, navigate and send reports.

How we verified:

• Each fix was checked against production-shaped data, recompiling and rendering every held draft without sending anything.
• Every figure in every rendered email was then recomputed independently from the raw tables.
• No client data is in this PR: tests and fixtures use invented values.

Client reports: content

• Malware
  • A malware scan that stopped early reads "Partial scan", never "No malware found".
  • Review reasons name the finding kinds and the scan id.
  • Matches on the scanner's own signature file are ignored.
  • Operators can mark review-tier findings reviewed, which shows the client "Reviewed — no threat found". The mark survives Recompile.
• Partial months
  • Sites added, or put on a care plan, part-way through the month are measured from that date and held for review.
  • HTTP 429 (the monitor being rate-limited) is not downtime.
  • Outages of an hour or more are held for a person to add context.
• Updates
  • Dates use the report timezone.
  • Updates applied outside Control (WordPress auto-updates, other tools) are listed.
  • "No updates were needed" is never claimed.
  • The agency's own Companion/Renegade plugins and updates that didn't stick are left out.
  • A month with updates waiting but none applied is held.
• Security
  • "Malicious visitors blocked" counts only real bans, and only when lockouts reached Control all month.
  • The core-files row is omitted on hosts that can't run the check.
  • Vulnerable-plugin holds match by slug.
• Backups and traffic
  • Suspiciously small database backups, failing or late-starting off-site relay archives, and too few backup days are held.
  • Traffic gets a status (ok / partial / suspect / no data / unsupported) and is shown only when complete and believable, e.g. not when every request comes from a load balancer.
• Presentation
  • The greeting uses the actual recipient, otherwise "Hi there,".
  • The support URL never falls back to Control's private URL.
  • Periods are whole days.
  • The From name is explicit.
  • Uptime is coloured by value.
  • The plain-text email matches the HTML.
  • The preview, printout and public page use the same phrases as the email.
• Safety
  • Recompile, as a button and as clockwork:recompile-held-client-reports, rebuilds an unsent report from current data and never sends.
  • Reports compiled under older rules (schema < 7) can't be sent until recompiled.
  • wp-admin no longer shows reports as active for sites without a Control schedule.

Client reports: UI

• Clients tab (/client-reports, new landing page):
  • Clients grouped by care plan. Care-plan clients come first, with those needing attention at the top; clients without a care plan are collapsed.
  • Each site's care-plan badge, schedule, recipients, and a six-month report history whose cells link to each report.
  • A page per client with its full report history, previous/next client, and a switcher.
• Reports list (now /client-reports/reports):
  • Period, status, hold-reason and search filters, with summary counts.
  • Reason chips, labelled actions, and "Recompile all outdated / selected".
• Report review:
  • A toolbar with previous/next, Email version, Recompile, Print, Test to me, and Send. Send explains who gets the email and what a first send changes. Keyboard shortcuts are included.
  • Review reasons are grouped, with links to the relevant site tab.
  • The email version page uses the app layout, with HTML and plain-text tabs.
• Scheduling:
  • Care-plan schedules come first.
  • One-click (and "Create all") schedules for care-plan sites that have none.
• Site dashboard: a "Client reports" link in the site header.

Fleet fixes found through the reports

• Uptime: HTTP 429 moves a site to a probe_blocked state instead of down. Real outages stay open through 429s, so down alerts aren't re-sent.
• Plugin updates:
  • Advisories are matched on the plugin directory.
  • Auto-paused plugins are retried once per new release or security fix.
  • A successful update lifts the pause.
  • Real upgrader errors are recorded with a reason_code.
  • Repeated file-permission failures pause the site once.
  • The nightly run happens once per local date (DST).
• Redaction: licence keys, tokens and signed download URLs are stripped before storage, chat, or the Companion mirror.
• Vulnerabilities: exact-version advisories (== X) no longer match every older release. A migration repairs existing rows.
• Theme identity guard: the nightly updater won't replace a custom or child theme with an unrelated wordpress.org theme that shares its folder name.
• Observed updates: updates made outside Control are recorded from snapshot changes as local-only activity.
• Backup relay:
  • Relay can't be enabled without Companion backup-create.
  • Per-site last error and failing-since are stored.
  • Stale archive hashes are cleared.
• Malware scans:
  • Finding paths are normalized so suppressions work.
  • New PHP files in uploads alert once.
  • SSH scans must prove each check finished.
• Other fixes:
  • Contact-form tests no longer skip days.
  • Pressable traffic is recorded before the report run without zero-filling history.
  • Bill.com matching handles www. and every fleet TLD.
  • Standalone sites are flagged as WordPress.
  • Checksum runs skip hosts with no transport.
  • The performance rotation is stable, with a month-end catch-up.

Testing

• Full Pest suite: 3,476 / 3,479 pass. The 3 failures happen only in the sandbox: StorageWritableCheck "real permission error" (it runs as root) and two InstallerWizardTest "executes full installation" tests, which need a live MySQL server. All three fail the same way on main there.
• The merge of latest main (v1.12.0 and dependency bumps) was tested on its own as well.
• Every rendered email was checked for:
  • leaked internals (scan ids, file paths, review reasons);
  • localhost or private URLs;
  • unmeasured zeros;
  • partial scans shown as clean;
  • figures recomputed from the raw tables.

Upgrade notes

1. php artisan migrate. New columns on sites, plugin_update_jobs and plugin_update_failure_streaks, a backfill of sites.is_wordpress for standalone Companion sites, and a repair of exact-version vulnerability rows.
2. npm run build and clear the view cache.
3. php artisan queue:restart.
4. Run clockwork:sync-bill-customers --dry-run and clockwork:sync-bill-care-plans --dry-run and review them before the next real sync. Normalized matching can link www. sites and change care-plan flags.
5. Run php artisan clockwork:recompile-held-client-reports --outdated --dry-run, then again without --dry-run. It never sends.
6. Set CLOCKWORK_GTMETRIX_DAILY_CREDITS, and optionally CLOCKWORK_REPORTS_TIMEZONE. The app host needs HTTPS access to api.wordpress.org.
7. /client-reports now opens the Clients tab. The reports list moved to /client-reports/reports.
8. Rows stored before this release in plugin_update_jobs.messages and action_logs.details still contain unredacted upgrader output. Scrub them separately.

Not in this PR

• Operational items found during the audit are tracked separately, outside the repo: backup relay permissions, host file permissions, plugin licences, and Gatekeeper lockouts no longer arriving since the Companion 1.40 capability change.
• A follow-up to self-host the printable report page's CSS and icons. It currently loads the Tailwind Play CDN.

---

Generated by Claude Code