=== QueueRay - Background Job Diagnostics ===
Tags: action scheduler, woocommerce, cron, scheduled actions, diagnostics
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.5.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Understand recent Action Scheduler failures, overdue jobs, likely owners, possible impact, and what to inspect next — without changing queue data.

== Description ==

QueueRay is a read-only diagnostic dashboard for WordPress sites that use Action Scheduler, including many WooCommerce stores.

Instead of showing only raw failed and past-due totals, QueueRay groups active problems by hook and adds a conservative diagnosis:

* what kind of background workflow the hook appears to represent;
* which plugin likely owns it;
* whether ownership came from a registered callback or a naming heuristic;
* what may be affected if the problem continues;
* what to inspect before retrying, canceling, or deleting queue data.

QueueRay does not delete, retry, cancel, or edit scheduled actions.

Current features:

* Action Scheduler queue totals and past-due counts
* Failed actions in the last 24 hours and 7 days
* Diagnosis cards for active failures and overdue hooks
* Conservative impact categories for payments, subscriptions, marketing sync, analytics, email, shipping, integrations, and unknown jobs
* Historical failed rows are not promoted into active diagnoses unless the same hook failed in the last 24 hours
* Likely-owner detection from registered callback source files when available
* Naming heuristics as a fallback, with explicit confidence
* WP-Cron and Action Scheduler queue-runner signals
* Estimated standard Action Scheduler table size
* Privacy-conscious support report that excludes action arguments and Action Scheduler group names
* Reserved QueueRay QA fixtures are excluded from health severity, diagnosis cards, operational totals, and hook rankings

= Why read-only? =

Deleting a failed or overdue background job without understanding what owns it can hide a symptom or interfere with plugin workflows. QueueRay diagnoses first and leaves queue changes to the site owner or developer.

= What does "possible impact" mean? =

QueueRay intentionally uses cautious language. A hook name can suggest that a job relates to payments, subscriptions, analytics, marketing sync, or another workflow, but it cannot prove that a customer-facing feature is broken. Always inspect the affected Scheduled Action log before making changes.

== Installation ==

1. Upload the `queueray` folder to `/wp-content/plugins/`, or install the ZIP from Plugins > Add New > Upload Plugin.
2. Activate QueueRay.
3. Make sure WooCommerce or another plugin that loads Action Scheduler is active.
4. Open Tools > QueueRay.
5. Review the scan and, when useful, copy the diagnostic report.

== Frequently Asked Questions ==

= Does this plugin repair failed scheduled actions? =

No. QueueRay is intentionally read-only. It helps you understand what is failing before you make changes.

= Does it require WooCommerce? =

No. It requires an active Action Scheduler instance. WooCommerce is one common source of Action Scheduler.

= Does it send site data anywhere? =

No. QueueRay runs locally in WordPress and does not make external API calls.

= How does owner detection work? =

When a scheduled-action hook has a callback registered on the current request, QueueRay attempts to map the callback source file to an installed plugin. When that evidence is unavailable, it uses conservative hook naming heuristics and then lower-confidence group naming heuristics. Ownership is always shown as likely rather than certain.

= Why can old failed actions exist on a healthy site? =

A failed row can remain in Action Scheduler after the underlying issue has recovered. QueueRay separates recent failures from historical failed rows so a large old failure total is not automatically treated as a current outage.

= Why can WP-Cron be disabled without being an error? =

Some hosts disable WordPress's traffic-triggered cron and replace it with a real server cron. QueueRay reports this cautiously because it cannot verify an external scheduler from inside WordPress.

= How are QueueRay development fixtures handled? =

Actions in the reserved `queueray-fixtures` QA group, including recognized suffix variants, are excluded from operational health severity, diagnosis cards, operational queue totals, and top-hook rankings. When fixtures are present, raw Action Scheduler totals remain visible only in the support report for comparison. Real non-fixture failures and overdue actions are still diagnosed normally, including when they use the same hook names as fixtures.

== Privacy ==

QueueRay 0.5.3 does not transmit data externally. The copyable support report excludes Action Scheduler action arguments and group names because either can contain plugin-specific identifiers.

== Changelog ==

= 0.5.3 =
* Updates the WordPress.org tested-up-to metadata for WordPress 7.1.
* No diagnostic behavior or queue-writing behavior changed.

= 0.5.2 =
* Renames the plugin to QueueRay - Background Job Diagnostics.
* Aligns the plugin slug, text domain, admin identifiers, and release metadata with `queueray`.
* Keeps the diagnostic behavior read-only and otherwise unchanged.

= 0.5.1 =
* Excludes reserved QueueRay QA fixtures from health severity, diagnosis cards, operational queue totals, and top-hook rankings.
* Preserves raw Action Scheduler totals in the support report so test environments remain auditable.
* Correctly separates real actions from fixtures even when they share the same hook name.
* Samples beyond fixture-heavy queue rows while keeping scan work bounded.
* Groups diagnoses at hook level to prevent duplicate or overlapping counts across Action Scheduler groups.
* Reports unsupported exact fixture or active aggregates as n/a with a warning instead of promoting raw test data or claiming a healthy queue.
* Improves admin accessibility with labeled report output, scoped table headers, and readable release CSS.
* Localizes clipboard status messages and hardens callback-source inspection for invokable objects.
* Simplifies the public plugin name to QueueRay and synchronizes release metadata.

= 0.5.0 =
* Adds a development-fixture notice for local QA data.
* Simplifies diagnosis cards by moving Action Scheduler group slugs out of the primary non-technical view.
* Renames owner wording to "Likely source" and "Source confidence" to reduce false certainty.
* Broadens read-error handling to PHP Throwables so an unexpected store or runtime error is less likely to break the diagnostics page.
* Keeps all scans read-only, local, and free of external requests.

= 0.4.0 =
* Adds an at-a-glance decision summary and moves raw queue details into an expandable technical section.
* Caps exact per-hook follow-up queries to the eight displayed buckets, reducing worst-case database-query amplification on large, diverse queues.
* Separates hook-based owner evidence from lower-confidence group-only heuristics.
* Adds transparent sampling notices when more than 150 recent failures or overdue actions exist.
* Keeps overdue severity age-aware so a large but freshly late queue is not marked high priority from count alone.
* Removes Action Scheduler group names from the copied support report for stronger privacy defaults.
* Adds scan-duration metadata for performance troubleshooting.
* Removes the placeholder Plugin URI from the production header.

= 0.3.1 =
* Keeps the "Top failed hooks" table aligned with the 24-hour active-failure window.
* Historical failed rows remain in Failed total but no longer appear under a recent table label.

= 0.3.0 =
* Adds queue-age and runner-lag signals for overdue queues.
* Adds exact diagnosis profiles for Stripe cache jobs, WooCommerce webhooks, Analytics order imports, and Mailchimp order sync.
* Keeps cron wording conservative when a custom or server runner may exist.
* Expands the support report with queue-runner timestamp and lag signals.

= 0.2.0 =
* Adds per-hook diagnosis cards for active failed and overdue jobs.
* Adds cautious possible-impact and next-check guidance.
* Adds exact per-hook recent-failure and past-due counts where supported by the loaded Action Scheduler store.
* Adds callback-source owner detection with confidence labels.
* Changes unknown ownership so an Action Scheduler group is no longer presented as a plugin owner.
* Prevents historical failed rows from becoming active diagnoses unless the hook failed in the last 24 hours.
* Expands the privacy-conscious support report with diagnosis summaries.

= 0.1.1 =
* Corrects Action Scheduler default queue-runner detection to use `action_scheduler_run_queue`.
* Avoids treating a missing default runner as critical when no overdue queue exists.

= 0.1.0 =
* Initial read-only diagnostic prototype.
