=== Scheduler Watchdog — Stop Runaway Background Jobs ===
Contributors: tillfoundry
Tags: woocommerce, action scheduler, background jobs, queue, monitoring
Requires at least: 6.0
Tested up to: 7.1.2
Requires PHP: 7.4
Stable tag: 0.1.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Watch, alert on and clean up runaway WooCommerce background jobs before they take the store down.

== Description ==

Every WooCommerce background job runs through Action Scheduler: marketing and CRM sync, ERP and 3PL pushes, subscription renewals, review requests, email follow-ups, importers. When one integration misbehaves it can enqueue hundreds of thousands of actions or fire them in an ever-tightening loop. PHP workers are consumed, the database is hammered, and the storefront starts returning errors.

Scheduler Watchdog sits beside Action Scheduler and watches it continuously.

* It samples queue depth and per-hook backlog.
* It times every action and records failures through Action Scheduler's own execution hooks.
* It shows one screen: total pending and past-due counts, the hooks with the highest failure rate, the slowest hooks, the biggest backlogs and the active alerts.
* It emails you the moment a hook breaks, stalls, or the queue runner stops firing.
* It cleans up old completed, failed and canceled actions under your retention rules, using Action Scheduler's own cleaner so nothing is deleted behind its back.

**Built for real stores**

* Zero configuration to get started — activate it and the defaults are sensible.
* Every feature in this plugin is free, with no licence key and no locked capability.
* No tracking. The plugin makes no outbound request unless you enter a licence key.
* WooCommerce High-Performance Order Storage (HPOS) compatible.
* Works with Action Scheduler 3.9.x and 4.x, whether it is bundled inside WooCommerce or installed standalone.

**What you get**

* A dashboard of queue depth, pending, past-due, in-progress and failed-in-window counts.
* Top failing hooks, slowest hooks and largest backlogs.
* A WordPress dashboard widget.
* Email alerts for failed actions, stalled/past-due hooks, a missing or overdue queue runner, and stale in-progress claims.
* A per-alert cooldown so you are not flooded.
* Safe, retention-based cleanup of old complete, failed and canceled actions — one click or on a daily schedule.
* Stale-claim recovery.
* Full control of alert recipients, thresholds and retention.

Scheduler Watchdog never reads or writes orders, order items, refunds or customer records. It operates only on Action Scheduler's own queue. It stores no order, customer, refund or order-item data. The personal data it does store is limited to the alert-recipient email addresses you configure in its settings, and a small per-user notice flag that remembers which of the plugin's admin notices you have dismissed or still need to see.

== Installation ==

1. Upload the `scheduler-watchdog` folder to `/wp-content/plugins/`, or install the ZIP through **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Open **WooCommerce → Scheduler Watchdog** (or **Tools → Scheduler Watchdog** when WooCommerce is not active).
4. Review the settings. No licence key is needed.

Action Scheduler must be present. It ships inside WooCommerce, or can be installed as a standalone plugin. Without it, the plugin shows a notice and stays inert.

== Frequently Asked Questions ==

= Does this plugin require WooCommerce? =

No. Action Scheduler is the real dependency. WooCommerce bundles Action Scheduler, so on a normal store it is already there. If you run Action Scheduler standalone, monitoring, alerting and cleanup all work; only the WooCommerce-specific HPOS declaration is skipped.

= What is Action Scheduler? =

Action Scheduler is the background job queue used by WooCommerce and many extensions. Every scheduled task is stored as an "action" with a hook name, a due date and a status. Scheduler Watchdog reads that queue to measure it.

= What does the paid plan include? =

Every feature of Scheduler Watchdog is free and unlocked: there is no trial, no time limit and no capability that switches off. The optional annual plans fund a year of plugin updates and priority email support. A Pro plan covers up to 3 site activations and an Agency plan up to 25. They add no extra features, because none are held back.

= Does the plugin delete my jobs? =

Never pending or in-progress work. Cleanup only ever removes old **complete**, **failed** and **canceled** actions, through Action Scheduler's own cleaner. There are hard minimum ages of 7 days for complete/canceled actions and 30 days for failed actions, regardless of what the settings say. A longer "keep" value is also applied to Action Scheduler's own cleaner — which otherwise removes complete/canceled actions after 31 days and failed actions after about 90 days on its own schedule — so raising the setting to keep a year of history is actually honoured. Cleanup is off until you enable it, and a preview button shows exactly what would be removed first.

= Where are the debug logs? =

Enable **Debug logging** on the **Advanced** tab, then open **WooCommerce → Status → Logs** and select the `scheduler-watchdog` source. Without WooCommerce, entries go to the PHP error log instead.

= Does it work on a high-volume store? =

Yes. The metrics table is time-bucketed and pruned on a daily retention run (14 days by default), the dashboard caps the number of hooks it reads, and the shutdown fallback sampler is throttled to once a minute. On stores processing 500+ orders a day, sampling remains cheap because the hot path only writes to memory and flushes once per request.

= Is it HPOS compatible? =

Yes. Scheduler Watchdog does not touch order storage at all. WooCommerce → Status → Compatibility lists it as HPOS compatible.

= Does the plugin send my data anywhere? =

Only if you enter a licence key, and then only to the licence server at `https://tillfoundry.com` to activate or validate that key. See **External Services** below for the exact endpoints and the data sent. Nothing is sent when no key is entered. No analytics, no telemetry, no external alerting service.

= What does GDPR erasure mean for this plugin? =

Scheduler Watchdog stores no order, customer, refund or order-item data. It records the Action Scheduler hook names, counts, durations and action IDs it needs to measure the queue. It also stores two things that can contain personal data: the alert-recipient email addresses you configure, kept in the `scheduler_watchdog_settings` option, and per-user notice state kept in the `scheduler_watchdog_dismissed_notices` and `scheduler_watchdog_queued_notices` user-meta keys, which remembers which plugin notices a user has dismissed or still needs to see. To remove the recipient addresses, clear the **Alert recipients** field in the plugin settings. The per-user notice state is removed automatically when the affected WordPress user account is deleted. Enabling **Delete data on uninstall** removes the plugin's settings, custom tables and transients when the plugin is deleted. Failed actions can also record the error text returned by the failing integration in the plugin's own events log.

== External Services ==

This free plugin contacts no external service on its own: it declares only free capabilities, every one of them works with no licence key, and a site that never enters a key makes no outbound request. The optional licence client is retained so a paid updates-and-support plan can validate its key against the same stack; it stays dormant until a key is entered. If you do enter a key, it is sent to the TillFoundry licence server at `https://tillfoundry.com` **only after you save it**.

The licence endpoints are:

* `https://tillfoundry.com/api/v1/activate` — called when you save a licence key, to register this installation against the key.
* `https://tillfoundry.com/api/v1/validate` — called when you press **Verify licence now**, and automatically in the background at most every twelve hours while a key is stored, to confirm the key is still valid.
* `https://tillfoundry.com/api/v1/deactivate` — called when you press **Deactivate this site**, to release the activation slot.

Each request sends the same installation record plus the licence key:

* the licence key;
* the site URL and home URL;
* the plugin slug and plugin version;
* the WordPress version and PHP version;
* whether the site is multisite;
* the site locale.

The request also carries the site URL in an `X-Site-URL` header and in the user-agent string. The service records the request IP address. See the provider's [privacy policy](https://tillfoundry.com/privacy-policy/) and [terms of service](https://tillfoundry.com/terms/).

If the licence server is unreachable, the plugin keeps working: monitoring, alerting and cleanup never depend on it, and a previously validated licence stays valid until the server can be reached again. No error from the licence service blocks a page or an admin action.

== Screenshots ==

1. The queue health dashboard: pending, past-due, in-progress and failed-in-window counts, plus the top failing, slowest and largest-backlog hooks.
2. The Action Scheduler events log, filtered by severity, hook and date.
3. Alert settings: recipients, failure and stall thresholds, and the per-alert cooldown.
4. Cleanup settings showing the dry-run preview count before anything is removed.
5. The WordPress dashboard widget with queue health at a glance.

== Changelog ==

= 0.1.2 =
* Fixed: rebuilt the distributed package so the release ZIP is byte-identical to the current source tree. No functional changes.

= 0.1.1 =
* Fixed: "Keep complete actions (days)", "Keep canceled actions (days)" and "Keep failed actions (days)" are now applied to Action Scheduler's own cleaner as well. A value above Action Scheduler's 31-day (complete/canceled) or ~90-day (failed) default is no longer cut short by Action Scheduler's separate daily cleanup.
* Changed: the Cleanup settings now explain which retention value wins and where the hard minimum ages apply.
* Changed: the privacy wording is now specific. The readme makes no blanket no-personal-data claim; it states that no order, customer, refund or order-item data is stored and names the alert-recipient addresses and per-user notice state that are.

= 0.1.0 =
* Initial release.
* Queue health dashboard: pending, past-due, in-progress and failed-in-window counts, plus a WordPress dashboard widget.
* Top failing hooks, slowest hooks and largest backlogs.
* Email alerts for failed actions, stalled/past-due hooks, a missing or overdue queue runner, and stale in-progress claims, with a per-alert cooldown.
* Safe, retention-based cleanup of old complete, failed and canceled actions through Action Scheduler's own cleaner, with hard minimum ages and a preview.
* Stale-claim recovery.
* Configurable recipients, thresholds and retention.
* HPOS compatibility declaration and multisite-aware uninstall behind an explicit opt-in.

== Upgrade Notice ==

= 0.1.2 =
Maintenance release: the package is rebuilt from the current source. No functional changes.

= 0.1.1 =
Recommended for anyone who has raised a "Keep ... (days)" retention setting, so older complete, canceled or failed actions are not deleted earlier than configured by Action Scheduler's own cleaner.

= 0.1.0 =
Initial release. No action needed.
