PR Vision v0.2.0: admin/settings interface + correctness fixes (#3)

Model manager (UI-swappable models) + versioned/idempotent prv_models migration; metric comparability (config-version stamping); run-lock; projected cost + truncation state; per-model run-health; cadence reschedule; API-key 3-state; design/a11y fixes (dark v2).

QA: APPROVE-WITH-P2-NOTES — qa-reviews/pr-vision/2026-06-14-ee4371d9163f992f60e09c7e4ac6cf8cd1d3c5eb.md

Agent-Session: pr-vision admin v0.2.0 merge

includes/core/class-prv-cron.php

@@ -8,17 +8,21 @@
 declare(strict_types=1);
 
 /**
- * WP-Cron management for the weekly AI-visibility probe.
+ * WP-Cron management for the AI-visibility probe.
  *
  * Registers the prv_weekly_probe hook, schedules/clears the event, and
- * dispatches to PRV_Probe_Runner on each tick.
+ * dispatches to PRV_Probe_Runner on each tick.  Cadence changes clear the
+ * existing schedule and reschedule at the new recurrence so next-run
+ * timestamp reflects the actual cadence, not just the saved option.
  *
  * Who triggers: PRV_Plugin::init() (hook registration), PRV_Activator
- *               (schedule), PRV_Deactivator (clear).
- * Dependencies: PRV_Probe_Runner.
+ *               (schedule), PRV_Deactivator (clear), PRV_Settings_Page
+ *               (reschedule on cadence change).
+ * Dependencies: PRV_Probe_Runner, PRV_Run_Lock.
  *
- * @see class-prv-probe-runner.php — Runner invoked on each cron tick.
- * @see class-prv-activator.php    — Calls schedule_weekly() on activation.
+ * @see class-prv-probe-runner.php  -- Runner invoked on each cron tick.
+ * @see class-prv-activator.php     -- Calls schedule() on activation.
+ * @see class-prv-settings-page.php -- Calls reschedule() on cadence change.
  * @package PrVision
  */
 class PRV_Cron {
@@ -35,34 +39,85 @@ class PRV_Cron {
 	}
 
 	/**
-	 * Callback fired by WP-Cron on the weekly schedule.
+	 * Callback fired by WP-Cron on the scheduled cadence.
+	 *
+	 * Respects the run-lock; if already running (e.g. "Run now" is active)
+	 * the cron tick is skipped silently without double-spending.
 	 *
 	 * Side effects: Instantiates and runs PRV_Probe_Runner.
 	 *
 	 * @return void
 	 */
 	public function handle_cron_tick(): void {
+		if ( PRV_Run_Lock::is_locked() ) {
+			// Another run is in progress -- skip this tick.
+			return;
+		}
 		$runner = new PRV_Probe_Runner();
 		$runner->run();
 	}
 
 	/**
-	 * Schedule the weekly cron event if not already scheduled.
+	 * Schedule the probe cron event using the configured cadence.
 	 *
-	 * Safe to call on re-activation — no-op when already scheduled.
+	 * Safe to call on re-activation -- no-op when already scheduled at the
+	 * correct recurrence; clears and reschedules when recurrence differs.
 	 *
-	 * Side effects: Adds a WP-Cron event.
+	 * Side effects: Adds (or replaces) a WP-Cron event.
+	 *
+	 * @return void
+	 */
+	public static function schedule(): void {
+		$cadence = PRV_Config::get_cadence();
+		$next    = wp_next_scheduled( PRV_CRON_HOOK );
+
+		if ( false !== $next ) {
+			// Check if the current recurrence matches.
+			$events = _get_cron_array();
+			foreach ( $events as $timestamp => $hooks ) {
+				if ( isset( $hooks[ PRV_CRON_HOOK ] ) ) {
+					foreach ( $hooks[ PRV_CRON_HOOK ] as $event ) {
+						if ( isset( $event['schedule'] ) && $event['schedule'] === $cadence ) {
+							return; // Already scheduled at the right cadence.
+						}
+					}
+				}
+			}
+			// Wrong cadence -- clear and reschedule.
+			self::clear_schedule();
+		}
+
+		wp_schedule_event( time(), $cadence, PRV_CRON_HOOK );
+	}
+
+	/**
+	 * Reschedule the cron at a new cadence.
+	 *
+	 * Clears the existing event and creates a new one immediately.
+	 * Called by PRV_Settings_Page when the cadence option changes.
+	 *
+	 * Side effects: Removes existing cron event; adds new one.
+	 *
+	 * @param string $cadence New WP-Cron recurrence identifier.
+	 *
+	 * @return void
+	 */
+	public static function reschedule( string $cadence ): void {
+		self::clear_schedule();
+		wp_schedule_event( time(), $cadence, PRV_CRON_HOOK );
+	}
+
+	/**
+	 * Schedule using the legacy 'weekly' recurrence (activation compat).
 	 *
 	 * @return void
 	 */
 	public static function schedule_weekly(): void {
-		if ( ! wp_next_scheduled( PRV_CRON_HOOK ) ) {
-			wp_schedule_event( time(), 'weekly', PRV_CRON_HOOK );
-		}
+		self::schedule();
 	}
 
 	/**
-	 * Remove the weekly cron schedule.
+	 * Remove the cron schedule.
 	 *
 	 * Called on deactivation. Does not purge data.
 	 *
@@ -78,11 +133,20 @@ class PRV_Cron {
 	}
 
 	/**
-	 * Check whether the weekly event is currently scheduled.
+	 * Check whether the probe event is currently scheduled.
 	 *
 	 * @return bool
 	 */
 	public static function is_scheduled(): bool {
 		return false !== wp_next_scheduled( PRV_CRON_HOOK );
 	}
+
+	/**
+	 * Return the timestamp of the next scheduled run.
+	 *
+	 * @return int|false Timestamp or false if not scheduled.
+	 */
+	public static function next_run_timestamp() {
+		return wp_next_scheduled( PRV_CRON_HOOK );
+	}
 }