ci: harden cto-review.yml severity KeyError (v0.18.3)

QA (seq 43) identified a content-triggered KeyError in the CTO-Review
postprocessor: when a model returns a concerns[] item without a 'severity'
key, line 454 crashed with KeyError instead of degrading.

  sev = c[severity].upper()        # before — hard KeyError
  sev = c.get("severity", "UNKNOWN").upper()  # after — degrades gracefully

The JSON schema marks severity as required but the postprocessor does not
enforce it — a model deviating on a large diff (91K bytes for f10e177 vs
41K for 02e9aab) triggered the crash. The fix surfaces UNKNOWN-severity
concerns rather than killing the check.

No other workflow changes.

Agent-Session: prab-v0183-20260612

.github/workflows/cto-review.yml

@@ -451,7 +451,7 @@ jobs:
               if rev.get("concerns"):
                   lines.append("**Concerns:**")
                   for c in rev["concerns"]:
-                      sev = c["severity"].upper()
+                      sev = c.get("severity", "UNKNOWN").upper()
                       f = f"`{c['file']}`" if c.get("file") else ""
                       lines.append(f"- **{sev}** {f} — {c['issue']}")
                   lines.append("")

ARCHITECTURE.md

@@ -128,7 +128,8 @@ prautoblogger/
 │   ├── class-prautoblogger.php        # Main orchestrator — registers all hooks, delegates execution
 │   ├── class-pipeline-schema-installer.php # v0.18.0 substrate tables (prompts, run_sources, run_decisions, runs, run_stages)
 │   ├── class-migrate-prompt-seed-v0180.php # One-shot v0.18.0 prompt-registry seed migration
-│   ├── class-executor.php             # Cron handlers, generation AJAX (start + status), model registry
+│   ├── class-executor.php             # Cron handlers, generation AJAX (delegates start + status to poller), model registry
+│   ├── class-generation-status-poller.php # Generation AJAX handlers: status transient renewal, lock-age orphan detection (R2b/R3), abort_orphaned_run
 │   ├── class-ajax-handlers.php        # Non-generation AJAX: images, models, test connections
 │   ├── class-generation-lock.php      # DB-level atomic mutex for single-writer generation
 │   ├── class-activator.php            # Activation: create DB tables, set defaults, schedule cron
@@ -195,6 +196,7 @@ prautoblogger/
 │   ├── providers/
 │   │   ├── interface-llm-provider.php    # Contract for any LLM provider
 │   │   ├── class-open-router-provider.php # OpenRouter API implementation (chat completions)
+│   │   ├── class-open-router-completion-guard.php # Empty-completion guard: warn on finish_reason=length, one reasoning-off retry, audited failure (v0.18.1)
 │   │   ├── class-open-router-embedding-provider.php # Text embeddings for semantic dedup
 │   │   ├── class-open-router-pricing.php  # Model pricing lookup and cost estimation
 │   │   ├── interface-source-provider.php # Contract for any social media source
@@ -207,11 +209,13 @@ prautoblogger/
 │   │   ├── class-open-router-image-support.php   # API key, response parsing, retry/backoff helpers
 │   │   ├── class-open-router-image-pricing.php   # Model resolution + per-image cost estimation
 │   │   ├── class-open-router-config.php          # API base URL (direct vs AI Gateway)
-│   │   ├── class-open-router-request-builder.php # Header building + Hostinger cURL auth workaround
+│   │   ├── class-open-router-request-builder.php # Request body assembly + reasoning token cap/headroom (v0.18.1) + headers + Hostinger cURL auth workaround
 │   │   ├── class-runware-image-provider.php     # Runware FLUX.1 (default v0.9.0+)
 │   │   ├── class-runware-image-pricing.php      # FLUX schnell/dev cost table + resolver
 │   │   ├── class-runware-image-support.php      # Key, response parsing, retry, dimension snap
 │   │   ├── class-runware-image-batch.php        # True parallel curl_multi batch dispatcher
+│   │   ├── class-runware-model-catalog.php      # Live model catalog sync: modelSearch pagination, cache v2, failure cooldown
+│   │   ├── class-runware-catalog-fetcher.php    # HTTP fetch + normalize_models for Runware modelSearch (extracted for 300-line rule)
 │   │   └── (new providers go here — see CONVENTIONS.md)
 │   │
 │   ├── services/
@@ -336,11 +340,19 @@ Hostinger's 120-second LiteSpeed connection timeout. The frontend polls for stat
 └──────────────────────────────┘
 ```
 
-**Fallback detection:** If Hostinger kills the PHP process before it updates the
-transient (despite `ignore_user_abort`), the status endpoint detects the orphan after
-180 seconds by checking for recently-created posts with `_prautoblogger_run_id` meta.
-It also releases any stale generation lock. After 600 seconds (STATUS_TTL), it gives
-up unconditionally and reports a timeout.
+**Fallback detection (v0.18.3 R2b/R3):** The status transient is renewed on every stage
+transition via `update_generation_stage()` (`Pipeline_Status::broadcast()`), so its TTL
+always counts from the last activity rather than run start. When a status poll finds the
+transient absent:
+
+- **Lock within TTL (`lock_age ≤ STATUS_TTL = 600s`):** the background process is still alive
+  but has not broadcast yet (or the transient was evicted). `handle_missing_transient()` returns
+  `status: running` (R3) — button stays in-progress, no state change.
+- **Lock exceeded TTL (`lock_age > STATUS_TTL`):** background process died without releasing the
+  lock. `abort_orphaned_run()` marks the `runs` row `failed`, releases the generation lock, deletes
+  the status transient and queue option, and returns `status: error` with "infrastructure timeout"
+  (R2b). A daily `Run_Reaper::sweep_stuck_runs()` at 2× `EXPECTED_RUN_SECONDS` (~3600s) remains
+  the backstop for runs the poll path never sees.
 
 ---
 
@@ -535,7 +547,7 @@ dropped on uninstall.
 | id          | BIGINT UNSIGNED | Auto-increment PK                                  |
 | run_id      | VARCHAR(36)     | Pipeline run UUID                                  |
 | stage       | VARCHAR(50)     | Stage name (see stage vocabulary)                  |
-| agent_role  | VARCHAR(50)     | Fan-out dimension for Phase-2 quorum ('' default)  |
+| agent_role  | VARCHAR(50)     | Fan-out dimension. Populated in Phase 1 from `Stage_Display_Map::default_agent_role()` (e.g. 'writer', 'editor', 'publisher'). Phase-2 quorum passes multiple roles for the same stage. |
 | item_key    | VARCHAR(64)     | Scopes article-level stages within multi-article runs ('' for run-level) |
 | status      | VARCHAR(20)     | pending / running / done / failed / halted         |
 | attempt     | SMALLINT UNSIGNED | Re-entry counter                                 |
@@ -561,6 +573,7 @@ All prefixed with `prautoblogger_`:
 | `prautoblogger_analysis_model`         | OpenRouter model for analysis (default: cheap)        |
 | `prautoblogger_writing_model`          | OpenRouter model for writing (default: quality)       |
 | `prautoblogger_editor_model`           | OpenRouter model for chief editor (default: quality)  |
+| `prautoblogger_reasoning_max_tokens`   | v0.18.1 — hard cap on thinking tokens per call when reasoning is enabled; sent as OpenRouter `reasoning.max_tokens` (replaces `effort` when active) and the request `max_tokens` is raised by the cap so reasoning can never consume the visible-content budget; 0 = legacy uncapped effort mode. Default `PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS` (2048) |
 | `prautoblogger_daily_article_target`   | Number of articles per day (1-10, default: 1)         |
 | `prautoblogger_writing_pipeline`       | 'single_pass' or 'multi_step' (default: multi_step)  |
 | `prautoblogger_niche_description`      | Text description of the site's niche                  |
@@ -829,8 +842,9 @@ multi-step publish paths. Four subsystems:
    keyed by `_prautoblogger_run_id` + `_prautoblogger_idea_hash` (check-before-insert) so a
    retried run cannot duplicate a post. `PRAutoBlogger_Run_Reaper` (same daily cron as #19)
    marks runs stuck `running` > 2× expected stage wall-clock as `failed`; such runs render
-   as **"incomplete"** in audit queries. Quorum logic itself is Phase 2 — the schema just
-   reserves its dimensions.
+   as **"incomplete"** in audit queries. Quorum logic (multiple roles per stage) itself is Phase 2. In Phase 1,
+   `agent_role` is populated on every row from `Stage_Display_Map::default_agent_role()`
+   so the run timeline is self-describing and the idempotency key is fully populated.
 
 ### #20: PHPUnit test infrastructure + WordPress-Core PHPCS compliance (v0.10.1)
 

CHANGELOG.md

@@ -5,6 +5,147 @@ All notable changes to PRAutoBlogger will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project uses [Semantic Versioning](https://semver.org/).
 
+## [0.18.3] - 2026-06-12
+
+GA4-context SQL fix, manual-run resilience, and honest status on transient expiry
+(CTO thread `2026-06-pipeline-v2-phase1` seq 38).
+
+### Fixed
+- **Analysis-prompts SQL / GA4 self-improvement loop (R1 — P2)**: `phpcs:ignore` annotation
+  was embedded inside the SQL string literal in `class-analysis-prompts.php:81` (same pattern
+  as the v0.18.2 cost-reporter fix). MariaDB rejected the query on every pipeline run,
+  causing `get_performance_context()` to always return `''` — the LLM research/analysis
+  stage has had no historical performance context since v0.16.0. Annotation moved to the
+  `// phpcs:ignore` pragma above `get_results()`. Sibling occurrence also fixed in
+  `class-post-assembler.php:112` (same pattern). Regression + behavioral tests added to
+  `AnalysisPromptsTest`.
+- **Manual-run resilience — transient renewal (R2a)**: `update_generation_stage()` in the
+  new `PRAutoBlogger_Generation_Status_Poller` now renews the STATUS_TTL on every stage
+  update, ensuring the status transient outlasts any single LLM call even when `Pipeline_
+  Status::broadcast()` is delayed by a long model call.
+- **Manual-run resilience — stuck-run detection (R2b)**: `on_ajax_generation_status()`
+  now detects when the status transient is absent but the generation lock has been held
+  longer than STATUS_TTL seconds — indicative of a Hostinger background-process kill.
+  Marks the stuck run `failed` in the audit ledger, releases the lock, and returns
+  `status: error` with an "infrastructure timeout" message instead of silently resetting
+  to idle.
+- **Honest status when transient gone but lock held (R3)**: when the status transient is
+  absent but the lock is held within TTL, `on_ajax_generation_status()` now returns
+  `status: running` with `started_at` from the lock timestamp (rather than `status: idle`)
+  so the Generate Now button reflects reality during long background runs.
+
+### Changed
+- **Executor split (300-line rule)**: `class-executor.php` was at 351 lines. AJAX generation
+  handlers (`on_ajax_generate_now`, `on_ajax_generation_status`, `abort_orphaned_run`,
+  `update_generation_stage`) extracted to new `class-generation-status-poller.php` (260 lines).
+  Executor retains cron handlers and delegates AJAX calls to the poller. Public API unchanged.
+- **Generation_Lock**: new `get_acquired_at()` method returns the Unix timestamp when the
+  lock was set, used by R2b/R3 to determine lock age without touching the pipeline run table.
+
+### Added
+- **Runware catalog `modelSearch` migration**: `class-runware-model-catalog.php` migrated
+  from the retired `taskType:models` endpoint to the current `taskType:modelSearch` API.
+  Payload format: `[{taskType:authentication,apiKey:...},{taskType:modelSearch,
+  taskUUID:<uuid4>,offset:N,limit:N}]`. Response normalization updated for the new shape:
+  `air` identifier replaces `id`, `capabilities[]` array replaces `taskType`/`requiresImage`
+  (filter: entry must contain `"io:text-to-image"`), `comment` field maps to `description`.
+  Logic extracted to `class-runware-catalog-fetcher.php` companion (300-line rule). Cache
+  option key bumped to `prautoblogger_runware_model_cache_v2` to cleanly invalidate v1 rows.
+- **Pagination for `modelSearch`**: fetcher paginates via `offset`/`limit` up to 5 pages of
+  100 results = 500 models inspected. Runware's catalog has 320k+ entries (mostly community
+  checkpoints); 5 pages reliably captures all curated text-to-image models. A page-cap
+  warning is logged if the cap is reached before exhausting `totalResults`. Client-side
+  `io:text-to-image` capability filter applied — no server-side filter is available.
+- **Negative-result failure cooldown**: `sync()` records a failure timestamp in
+  `prautoblogger_runware_catalog_last_failure_at` on every error path. `get_models()`
+  gates re-trigger through `is_in_failure_cooldown()`, which respects a configurable
+  window from `prautoblogger_runware_catalog_failure_cooldown_seconds` (default 3600s / 1h,
+  never hardcoded at point of use). A successful sync clears the timestamp. This caps the
+  admin-page-load cascade (42 errors/day observed) to ~24/day even when the cache is absent.
+- **Hardcoded fallback list preserved**: unchanged; carried prod through the entire
+  `taskType:models` outage. Tests verify it is always non-empty and correctly priced.
+
+
+## [0.18.2] - 2026-06-12
+
+Four confirmed-live maintenance fixes (CTO thread `2026-06-pipeline-v2-phase1` seq 25).
+
+### Fixed
+- **Cost-reporter SQL (P2)**: `phpcs:ignore` annotations were embedded inside two SQL string
+  literals in `class-cost-reporter.php` (`get_daily_spend` and `get_spend_by_stage`). MariaDB
+  received the comment text as literal SQL and rejected both queries, breaking the Metrics &
+  Costs admin page. Annotations moved above the `$wpdb->prepare()` calls. Regression tests
+  added to `CostReporterTest` asserting no `// phpcs:ignore` text appears in the SQL passed
+  to `prepare()`.
+- **Collector failure observability (P2)**: `RuntimeException` catch in
+  `Source_Collector::collect_from_all_sources()` now logs structured meta — model slug,
+  HTTP status parsed from the exception message, and the first 200 chars of the error body —
+  so a 27-day outage like the seq-22 llm_research 404 incident is diagnosable after the fact.
+  No behaviour change; logging only.
+- **`run_stages.agent_role` symmetric write (P3)**: `Pipeline_Runner`, `Article_Worker`, and
+  `Content_Generator` were calling `start()` with the mapped role but leaving `done()`,
+  `is_done()`, and `get_output()` with `agent_role = ''`. With `agent_role` in the UNIQUE key,
+  the mismatch addressed different rows — stranding `start()` rows in `running` forever and
+  breaking idempotent resume (duplicate-post vector). Fixed via an in-class seam in
+  `Run_Stage_State::resolve_role()`: when the caller passes `''`, the role is derived from
+  `Stage_Display_Map::default_agent_role($stage)` before any DB query, ensuring every method
+  addresses the same row. Explicit non-empty roles (Phase-2 fan-out) are passed through
+  unchanged. `get()` falls back to `role=''` on miss for mid-run-upgrade compat with v0.18.1
+  rows. Two new `RunStageStateTest` cases lock the symmetric-role and fallback contracts.
+  ARCHITECTURE.md §22 updated to document Phase 1 role population.
+- **Runware float deprecation (P3)**: `normalize_seed()` in `class-runware-image-support.php`
+  applied the modulo operator to a float (`microtime(true) * 1000`), triggering
+  `Deprecated: Implicit conversion from float … to int` on every image generation. Fixed
+  with `(int) round(...)` before the `%` operator.
+
+## [0.18.1] - 2026-06-11
+
+Empty-draft hotfix (CTO diagnosis: convo thread `2026-06-pipeline-v2-phase1` seq 12; prod run
+`acf24029`, draft post 921). A true reasoning model at a high reasoning effort could spend the
+entire `max_tokens` completion budget on thinking, return zero visible content with
+`finish_reason=length`, and the empty article flowed writer → editor (reject: "draft text is
+missing") → empty draft post in the Review Queue, with the cost booked as `success`.
+
+### Fixed
+- **Empty-completion guard at the call seam** (`PRAutoBlogger_OpenRouter_Completion_Guard`):
+  a chat completion whose visible content is empty/whitespace is now a **failure**, never a
+  success. When the empty result co-occurs with `finish_reason=length` or an active reasoning
+  request, the call is retried **once** with reasoning disabled (per-call `reasoning`
+  override) before the stage fails. Failed/retried attempts land in `generation_log` with
+  `response_status='error'`, the failure note, and the real token burn; inside a v0.18.0 run a
+  `run_decisions` row records the verdict (`retry_reasoning_disabled` /
+  `failed_empty_completion`).
+- **Writer-path guard**: a writing stage (outline/draft/polish/single-pass) whose output is
+  empty throws instead of passing an empty article to the editor (belt over the seam guard,
+  covers any future non-OpenRouter provider).
+- **Publisher belt-and-braces**: `Publisher::create_post()` refuses to create any post —
+  publish or draft — whose content is empty after tag stripping. No empty draft post can ever
+  be created again.
+- `finish_reason=length` is now always warning-logged with model, stage, and
+  prompt/completion/reasoning token counts (previously silent — the truncated `llm_research`
+  call in the incident run was invisible).
+
+### Added
+- **Reasoning token cap + completion headroom**: when a request enables reasoning, the
+  thinking budget is capped via OpenRouter's `reasoning.max_tokens` and the request's
+  `max_tokens` is **raised** by the same amount, so no reasoning effort (incl. `xhigh`) can
+  consume the visible-content budget. New setting `prautoblogger_reasoning_max_tokens`
+  (Settings → AI Models, default `PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS` = 2048; 0
+  restores the previous uncapped effort mode; the option is sanitized server-side as
+  numeric). When the cap is active it replaces `effort`
+  (OpenRouter treats them as alternative budget controls); the `xhigh`/`high` effort options
+  stay available but are bounded by default. Cost-governor reservations use the effective
+  (raised) ceiling.
+- LLM call sites now pass their pipeline stage to the provider (`stage` option, never sent
+  upstream) so guard warnings and failure rows are attributable: `analysis`, `review`,
+  `llm_research`, `image_prompt_rewrite`, `opik_eval_judge`, and the writer stages (which
+  also pass `prompt_key`).
+
+### Notes
+- `OpenRouter_Provider::send_chat_completion()` body assembly moved to
+  `OpenRouter_Request_Builder::build_body()` (300-line cap; behavior unchanged apart from the
+  reasoning budget above).
+
 ## [0.18.0] - 2026-06-12
 
 Pipeline v2 — Phase 1 substrate (plan of record: CPO thread

includes/admin/class-admin-page.php

@@ -323,7 +323,7 @@ class PRAutoBlogger_Admin_Page {
 			return wp_json_encode( array_values( array_map( 'sanitize_text_field', $items ) ) );
 		}
 
-		$numeric = array( 'prautoblogger_daily_article_target', 'prautoblogger_monthly_budget_usd', 'prautoblogger_min_word_count', 'prautoblogger_max_word_count', 'prautoblogger_default_author', 'prautoblogger_default_category', 'prautoblogger_pullpush_cache_ttl', 'prautoblogger_reddit_posts_per_subreddit' );
+		$numeric = array( 'prautoblogger_daily_article_target', 'prautoblogger_monthly_budget_usd', 'prautoblogger_min_word_count', 'prautoblogger_max_word_count', 'prautoblogger_default_author', 'prautoblogger_default_category', 'prautoblogger_pullpush_cache_ttl', 'prautoblogger_reddit_posts_per_subreddit', 'prautoblogger_reasoning_max_tokens' );
 		if ( in_array( $option_name, $numeric, true ) ) {
 			return is_numeric( $value ) ? $value : 0;
 		}

includes/admin/class-settings-fields-extended.php

@@ -78,7 +78,17 @@ class PRAutoBlogger_Settings_Fields_Extended {
 					'low'     => __( 'Low — light reasoning, lower cost', 'prautoblogger' ),
 					'minimal' => __( 'Minimal — barely any reasoning', 'prautoblogger' ),
 				),
-				'description' => __( 'How much effort the model spends reasoning before answering. Higher effort = more reasoning tokens = higher cost. Only applies when reasoning is enabled above.', 'prautoblogger' ),
+				'description' => __( 'How much effort the model spends reasoning before answering. Higher effort = more reasoning tokens = higher cost. Only applies when reasoning is enabled above. When the Reasoning Token Cap below is set (default), the cap is sent instead of the effort level — set the cap to 0 to use effort only.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_reasoning_max_tokens',
+				'label'       => __( 'Reasoning Token Cap', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_models',
+				'default'     => PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS,
+				'min'         => 0,
+				'max'         => 32000,
+				'description' => __( 'Hard ceiling on thinking tokens per call when reasoning is enabled. The completion budget is raised by this amount so reasoning can never crowd out the article text — an uncapped high effort can spend the entire budget thinking and return an empty draft. 0 = no cap (uncapped effort mode, not recommended).', 'prautoblogger' ),
 			),
 
 			// ── Schedule & Budget ───────────────────────────────────────

includes/class-executor.php

@@ -4,11 +4,15 @@ declare(strict_types=1);
 /**
  * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
  *
- * Cron/AJAX handlers for content generation, metrics collection, model registry.
+ * Cron handlers for content generation and metrics collection.
  *
+ * What: Daily generation, manual generation, queued-article processing,
+ *       and metrics collection cron handlers. AJAX generation handlers
+ *       live in PRAutoBlogger_Generation_Status_Poller (v0.18.3 split).
  * Triggered by: PRAutoBlogger hook registration.
  * Dependencies: Pipeline_Runner, Metrics_Collector, Generation_Lock, Logger.
  *
+ * @see class-generation-status-poller.php — "Generate Now" AJAX + status poll.
  * @see class-prautoblogger.php            — Hook wiring.
  * @see core/class-pipeline-runner.php     — Actual generation pipeline.
  * @see class-generation-lock.php          — DB mutex.
@@ -18,11 +22,8 @@ class PRAutoBlogger_Executor {
 	/** @var PRAutoBlogger_OpenRouter_Model_Registry|null Lazy-loaded singleton. */
 	private ?PRAutoBlogger_OpenRouter_Model_Registry $model_registry = null;
 
-	/** Transient key for background generation status. */
-	private const STATUS_TRANSIENT = 'prautoblogger_generation_status';
-
-	/** How long to keep the result available for polling (seconds). */
-	private const STATUS_TTL = 600;
+	/** @var PRAutoBlogger_Generation_Status_Poller|null Lazy-loaded poller. */
+	private ?PRAutoBlogger_Generation_Status_Poller $poller = null;
 
 	/**
 	 * Handle the daily generation cron event.
@@ -58,20 +59,6 @@ class PRAutoBlogger_Executor {
 		}
 	}
 
-	/**
-	 * Mark this process's run failed after a fatal pipeline error
-	 * (no-op outside a run; a governor-halted run stays halted — final
-	 * states are sticky).
-	 *
-	 * @return void
-	 */
-	private function mark_current_run_failed(): void {
-		$run_id = PRAutoBlogger_Run_Context::current_run_id();
-		if ( null !== $run_id ) {
-			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
-		}
-	}
-
 	/**
 	 * Handle the metrics collection cron event.
 	 * Side effects: API calls to GA4, database writes to ab_content_scores.
@@ -89,79 +76,12 @@ class PRAutoBlogger_Executor {
 
 	/**
 	 * AJAX handler: kick off manual generation as a background cron job.
-	 *
-	 * Returns immediately so the browser never hits Hostinger's 120-second
-	 * connection timeout. The frontend polls on_ajax_generation_status()
-	 * every few seconds to get progress and final results.
+	 * Delegates to PRAutoBlogger_Generation_Status_Poller.
 	 *
 	 * Side effects: schedules a WP-Cron event, writes a status transient.
 	 */
 	public function on_ajax_generate_now(): void {
-		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
-
-		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
-			return;
-		}
-
-		$force = isset( $_POST['force'] ) && '1' === $_POST['force'];
-		if ( $force ) {
-			PRAutoBlogger_Generation_Lock::release();
-			delete_transient( self::STATUS_TRANSIENT );
-		}
-
-		// Check if a run is already in progress.
-		$current = get_transient( self::STATUS_TRANSIENT );
-		if ( is_array( $current ) && 'running' === ( $current['status'] ?? '' ) ) {
-			wp_send_json_success(
-				array(
-					'background' => true,
-					'message'    => __( 'Generation already in progress.', 'prautoblogger' ),
-				)
-			);
-			return;
-		}
-
-		// Write initial "running" status for the frontend to poll.
-		set_transient(
-			self::STATUS_TRANSIENT,
-			array(
-				'status'       => 'running',
-				'stage'        => __( 'Starting generation...', 'prautoblogger' ),
-				'started'      => time(),
-				'last_updated' => time(),
-			),
-			self::STATUS_TTL
-		);
-
-		// Schedule immediate one-shot cron event. WordPress will fire this
-		// on the next page load (or via wp-cron.php) in a separate PHP process
-		// that is not subject to the 120-second connection timeout.
-		if ( ! wp_next_scheduled( 'prautoblogger_manual_generation' ) ) {
-			wp_schedule_single_event( time(), 'prautoblogger_manual_generation' );
-		}
-
-		// Spawn the cron immediately via a non-blocking loopback request
-		// so we don't depend on the next visitor to trigger it.
-		spawn_cron();
-
-		// Direct non-blocking loopback to wp-cron.php — ensures the event
-		// fires even if DISABLE_WP_CRON is true or spawn_cron() no-ops.
-		wp_remote_post(
-			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
-			array(
-				'timeout'   => 0.01,
-				'blocking'  => false,
-				'sslverify' => false,
-			)
-		);
-
-		wp_send_json_success(
-			array(
-				'background' => true,
-				'message'    => __( 'Generation started in background. Polling for status...', 'prautoblogger' ),
-			)
-		);
+		$this->poller()->on_ajax_generate_now();
 	}
 
 	/**
@@ -179,18 +99,18 @@ class PRAutoBlogger_Executor {
 
 		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
 			set_transient(
-				self::STATUS_TRANSIENT,
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
 				array(
 					'status'  => 'error',
 					'message' => __( 'Could not acquire generation lock. Another run may be in progress.', 'prautoblogger' ),
 				),
-				self::STATUS_TTL
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
 			);
 			return;
 		}
 
 		try {
-			$this->update_generation_stage( __( 'Collecting sources from Reddit...', 'prautoblogger' ) );
+			$this->poller()->update_generation_stage( __( 'Collecting sources from Reddit...', 'prautoblogger' ) );
 
 			$runner  = ( new PRAutoBlogger_Pipeline_Runner() )->set_skip_dedup( true );
 			$results = $runner->run();
@@ -199,7 +119,7 @@ class PRAutoBlogger_Executor {
 			// When articles ARE queued, the pipeline handles status + lock release.
 			if ( ! get_option( 'prautoblogger_article_queue' ) ) {
 				set_transient(
-					self::STATUS_TRANSIENT,
+					PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
 					array(
 						'status'    => 'complete',
 						'generated' => $results['generated'],
@@ -207,7 +127,7 @@ class PRAutoBlogger_Executor {
 						'rejected'  => $results['rejected'],
 						'cost'      => $results['cost'],
 					),
-					self::STATUS_TTL
+					PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
 				);
 				PRAutoBlogger_Generation_Lock::release();
 			}
@@ -217,12 +137,12 @@ class PRAutoBlogger_Executor {
 				'pipeline'
 			);
 			set_transient(
-				self::STATUS_TRANSIENT,
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
 				array(
 					'status'  => 'error',
 					'message' => $e->getMessage(),
 				),
-				self::STATUS_TTL
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
 			);
 			$this->mark_current_run_failed();
 			PRAutoBlogger_Generation_Lock::release();
@@ -247,89 +167,44 @@ class PRAutoBlogger_Executor {
 			delete_option( 'prautoblogger_article_queue' );
 			PRAutoBlogger_Generation_Lock::release();
 			set_transient(
-				self::STATUS_TRANSIENT,
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
 				array(
 					'status'  => 'error',
 					'message' => $e->getMessage(),
 				),
-				self::STATUS_TTL
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
 			);
 		}
 	}
 
-	/** AJAX: return generation status for frontend polling. Recovers orphaned runs. */
+	/** AJAX: return generation status for frontend polling. Delegates to poller. */
 	public function on_ajax_generation_status(): void {
-		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
-		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
-			return;
-		}
-
-		$status = get_transient( self::STATUS_TRANSIENT );
-		if ( ! is_array( $status ) ) {
-			wp_send_json_success( array( 'status' => 'idle' ) );
-			return;
-		}
-
-		if ( 'running' === $status['status'] ) {
-			$elapsed = time() - ( $status['started'] ?? 0 );
-
-			// Absolute timeout — give up after 10 minutes.
-			if ( $elapsed > self::STATUS_TTL ) {
-				$this->abort_orphaned_run( __( 'Generation timed out. Check the Activity Log.', 'prautoblogger' ) );
-				return;
-			}
-
-			// After 90s, check if a queued job died and needs re-scheduling.
-			if ( $elapsed > 90 && get_option( 'prautoblogger_article_queue' ) ) {
-				if ( ! wp_next_scheduled( PRAutoBlogger_Pipeline_Runner::CRON_ACTION ) ) {
-					wp_schedule_single_event( time(), PRAutoBlogger_Pipeline_Runner::CRON_ACTION );
-					spawn_cron();
-				}
-			}
-
-			// Stall = 5 min since last stage update (not since start).
-			$last_activity = $status['last_updated'] ?? $status['started'] ?? 0;
-			$idle_seconds  = time() - $last_activity;
-			if ( $idle_seconds > 300 ) {
-				$this->abort_orphaned_run( __( 'Generation stalled. Check Activity Log.', 'prautoblogger' ) );
-				return;
-			}
-		}
-
-		wp_send_json_success( $status );
-	}
-
-	/** Clean up an orphaned generation run and report error. */
-	private function abort_orphaned_run( string $message ): void {
-		// v0.18.0: the dead run renders as failed/"incomplete" in audit
-		// queries instead of silently lingering as 'running'.
-		$queue = get_option( 'prautoblogger_article_queue' );
-		if ( is_array( $queue ) && ! empty( $queue['run_id'] ) ) {
-			PRAutoBlogger_Run_State::mark_status( (string) $queue['run_id'], 'failed' );
-		}
-		delete_transient( self::STATUS_TRANSIENT );
-		delete_option( 'prautoblogger_article_queue' );
-		PRAutoBlogger_Generation_Lock::release();
-		wp_send_json_success(
-			array(
-				'status'  => 'error',
-				'message' => $message,
-			)
-		);
+		$this->poller()->on_ajax_generation_status();
 	}
 
 	/**
-	 * Helper: update the generation stage for frontend polling.
+	 * Lazy-load the generation status poller.
 	 *
-	 * @param string $stage Human-readable stage description.
+	 * @return PRAutoBlogger_Generation_Status_Poller
 	 */
-	private function update_generation_stage( string $stage ): void {
-		$current = get_transient( self::STATUS_TRANSIENT );
-		if ( is_array( $current ) ) {
-			$current['stage']        = $stage;
-			$current['last_updated'] = time();
-			set_transient( self::STATUS_TRANSIENT, $current, self::STATUS_TTL );
+	private function poller(): PRAutoBlogger_Generation_Status_Poller {
+		if ( null === $this->poller ) {
+			$this->poller = new PRAutoBlogger_Generation_Status_Poller();
+		}
+		return $this->poller;
+	}
+
+	/**
+	 * Mark this process's run failed after a fatal pipeline error
+	 * (no-op outside a run; a governor-halted run stays halted — final
+	 * states are sticky).
+	 *
+	 * @return void
+	 */
+	private function mark_current_run_failed(): void {
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+		if ( null !== $run_id ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
 		}
 	}
 

includes/class-generation-lock.php

@@ -76,6 +76,29 @@ class PRAutoBlogger_Generation_Lock {
 		return null !== $row;
 	}
 
+	/**
+	 * Get the Unix timestamp when the lock was acquired, or null if not held.
+	 *
+	 * Returns null when the lock is not set. The timestamp is the value written
+	 * by acquire() — used by the status poller to detect infrastructure-timeout
+	 * runs (lock held longer than STATUS_TTL → background PHP process died).
+	 *
+	 * @return int|null Unix timestamp, or null when the lock is absent.
+	 */
+	public static function get_acquired_at(): ?int {
+		global $wpdb;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+				self::LOCK_NAME
+			)
+		);
+
+		return null !== $row ? (int) $row : null;
+	}
+
 	/**
 	 * Release the generation mutex.
 	 *

includes/class-generation-status-poller.php

@@ -0,0 +1,260 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * AJAX handlers for "Generate Now" + status polling.
+ *
+ * What: Two AJAX endpoints: kick-off (fire-and-forget cron spawn) and the
+ *       status poll that drives the admin UI spinner. Extracted from
+ *       PRAutoBlogger_Executor in v0.18.3 to keep each file under 300 lines.
+ *
+ * R2/R3 resilience (v0.18.3):
+ *   - R2(a): on_ajax_generate_now() renews the transient with the
+ *     full STATUS_TTL on every stage update via update_generation_stage().
+ *   - R2(b): on_ajax_generation_status() detects lock-held-but-transient-gone
+ *     when the lock has been held > STATUS_TTL seconds (Hostinger background-
+ *     process death); marks the stuck run failed + surfaces a human-readable
+ *     "infrastructure timeout" message for the Activity Log.
+ *   - R3: on_ajax_generation_status() returns status:running (with
+ *     started_at) when the transient is absent but the lock IS held and
+ *     within TTL — so the button reflects reality during long runs rather
+ *     than silently resetting to idle.
+ *
+ * Who calls it: PRAutoBlogger hook registration (wp_ajax_prautoblogger_*).
+ * Dependencies: PRAutoBlogger_Generation_Lock, PRAutoBlogger_Run_State,
+ *               PRAutoBlogger_Run_Context, PRAutoBlogger_Pipeline_Runner,
+ *               PRAutoBlogger_Logger.
+ *
+ * @see class-executor.php         — Cron handlers (daily, manual, queued).
+ * @see class-generation-lock.php  — DB mutex (acquire/release/timestamps).
+ * @see core/class-pipeline-status.php — Transient broadcast helpers.
+ * @see ARCHITECTURE.md #21        — Run lifecycle and reaper design.
+ */
+class PRAutoBlogger_Generation_Status_Poller {
+
+	/** Transient key for background generation status (shared with Pipeline_Status). */
+	public const STATUS_TRANSIENT = 'prautoblogger_generation_status';
+
+	/**
+	 * How long (seconds) to keep the status transient readable.
+	 * Renewed on every stage transition so a long run doesn't expire it early.
+	 */
+	public const STATUS_TTL = 600;
+
+	/**
+	 * AJAX handler: kick off manual generation as a background cron job.
+	 *
+	 * Returns immediately so the browser never hits Hostinger's connection
+	 * timeout. The frontend polls on_ajax_generation_status() every few
+	 * seconds for progress and final results.
+	 *
+	 * Side effects: schedules a WP-Cron event, writes a status transient.
+	 */
+	public function on_ajax_generate_now(): void {
+		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$force = isset( $_POST['force'] ) && '1' === $_POST['force'];
+		if ( $force ) {
+			PRAutoBlogger_Generation_Lock::release();
+			delete_transient( self::STATUS_TRANSIENT );
+		}
+
+		// Check if a run is already in progress.
+		$current = get_transient( self::STATUS_TRANSIENT );
+		if ( is_array( $current ) && 'running' === ( $current['status'] ?? '' ) ) {
+			wp_send_json_success(
+				array(
+					'background' => true,
+					'message'    => __( 'Generation already in progress.', 'prautoblogger' ),
+				)
+			);
+			return;
+		}
+
+		// Write initial "running" status for the frontend to poll.
+		set_transient(
+			self::STATUS_TRANSIENT,
+			array(
+				'status'       => 'running',
+				'stage'        => __( 'Starting generation...', 'prautoblogger' ),
+				'started'      => time(),
+				'last_updated' => time(),
+			),
+			self::STATUS_TTL
+		);
+
+		// Schedule immediate one-shot cron event. WordPress will fire this
+		// on the next page load (or via wp-cron.php) in a separate PHP process
+		// not subject to the connection timeout.
+		if ( ! wp_next_scheduled( 'prautoblogger_manual_generation' ) ) {
+			wp_schedule_single_event( time(), 'prautoblogger_manual_generation' );
+		}
+
+		// Spawn the cron immediately via a non-blocking loopback request
+		// so we don't depend on the next visitor to trigger it.
+		spawn_cron();
+
+		// Direct non-blocking loopback to wp-cron.php — ensures the event
+		// fires even if DISABLE_WP_CRON is true or spawn_cron() no-ops.
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+
+		wp_send_json_success(
+			array(
+				'background' => true,
+				'message'    => __( 'Generation started in background. Polling for status...', 'prautoblogger' ),
+			)
+		);
+	}
+
+	/** AJAX: return generation status for frontend polling. Recovers orphaned runs. */
+	public function on_ajax_generation_status(): void {
+		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$status = get_transient( self::STATUS_TRANSIENT );
+
+		// R2(b) + R3: transient is gone — check the lock before returning idle.
+		if ( ! is_array( $status ) ) {
+			$this->handle_missing_transient();
+			return;
+		}
+
+		if ( 'running' === $status['status'] ) {
+			$elapsed = time() - ( $status['started'] ?? 0 );
+
+			// Absolute timeout — give up after STATUS_TTL.
+			if ( $elapsed > self::STATUS_TTL ) {
+				$this->abort_orphaned_run( __( 'Generation timed out. Check the Activity Log.', 'prautoblogger' ) );
+				return;
+			}
+
+			// After 90s, check if a queued job died and needs re-scheduling.
+			if ( $elapsed > 90 && get_option( 'prautoblogger_article_queue' ) ) {
+				if ( ! wp_next_scheduled( PRAutoBlogger_Pipeline_Runner::CRON_ACTION ) ) {
+					wp_schedule_single_event( time(), PRAutoBlogger_Pipeline_Runner::CRON_ACTION );
+					spawn_cron();
+				}
+			}
+
+			// Stall = 5 min since last stage update (not since start).
+			$last_activity = $status['last_updated'] ?? $status['started'] ?? 0;
+			$idle_seconds  = time() - $last_activity;
+			if ( $idle_seconds > 300 ) {
+				$this->abort_orphaned_run( __( 'Generation stalled. Check Activity Log.', 'prautoblogger' ) );
+				return;
+			}
+		}
+
+		wp_send_json_success( $status );
+	}
+
+	/**
+	 * Handle the case where the status transient is absent.
+	 *
+	 * R3: if lock is HELD and within TTL → return status:running so the
+	 *     button reflects reality during long background runs.
+	 * R2(b): if lock is held but has been held > STATUS_TTL → the background
+	 *     PHP process died without releasing it; mark the run failed and
+	 *     surface "infrastructure timeout" to the UI.
+	 *
+	 * @return void Sends JSON and exits.
+	 */
+	private function handle_missing_transient(): void {
+		$acquired_at = PRAutoBlogger_Generation_Lock::get_acquired_at();
+
+		if ( null === $acquired_at ) {
+			// Lock not held — genuinely idle.
+			wp_send_json_success( array( 'status' => 'idle' ) );
+			return;
+		}
+
+		$lock_age = time() - $acquired_at;
+
+		if ( $lock_age > self::STATUS_TTL ) {
+			// Lock held longer than STATUS_TTL: background process died.
+			// R2(b): mark the stuck run failed + surface a clear error.
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf(
+					'Status transient absent and lock held for %ds (> %ds TTL) — background process died; marking run failed.',
+					$lock_age,
+					self::STATUS_TTL
+				),
+				'pipeline'
+			);
+			$this->abort_orphaned_run(
+				__( 'Generation failed — infrastructure timeout. Check Activity Log for details.', 'prautoblogger' )
+			);
+			return;
+		}
+
+		// R3: lock is fresh (within TTL) but transient is gone — long run in
+		// progress (pipeline broadcast hasn't fired yet, or transient was
+		// evicted by object-cache pressure). Return running so the button
+		// does not silently reset to idle.
+		wp_send_json_success(
+			array(
+				'status'       => 'running',
+				'stage'        => __( 'Generation in progress (background). Check Activity Log for details.', 'prautoblogger' ),
+				'started'      => $acquired_at,
+				'last_updated' => $acquired_at,
+			)
+		);
+	}
+
+	/** Clean up an orphaned generation run and report error. */
+	private function abort_orphaned_run( string $message ): void {
+		// Mark the stuck run as failed in the audit ledger.
+		$queue = get_option( 'prautoblogger_article_queue' );
+		if ( is_array( $queue ) && ! empty( $queue['run_id'] ) ) {
+			PRAutoBlogger_Run_State::mark_status( (string) $queue['run_id'], 'failed' );
+		}
+		// Also attempt to close the current active run from Run_Context.
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+		if ( null !== $run_id ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+		}
+		delete_transient( self::STATUS_TRANSIENT );
+		delete_option( 'prautoblogger_article_queue' );
+		PRAutoBlogger_Generation_Lock::release();
+		wp_send_json_success(
+			array(
+				'status'  => 'error',
+				'message' => $message,
+			)
+		);
+	}
+
+	/**
+	 * Update the generation stage text for frontend polling.
+	 * Renews the transient TTL at every call so a long run doesn't expire it.
+	 *
+	 * @param string $stage Human-readable stage description.
+	 */
+	public function update_generation_stage( string $stage ): void {
+		$current = get_transient( self::STATUS_TRANSIENT );
+		if ( is_array( $current ) ) {
+			$current['stage']        = $stage;
+			$current['last_updated'] = time();
+			// R2(a): renew the TTL on every stage update so the transient
+			// outlives any single LLM call (STATUS_TTL from last activity).
+			set_transient( self::STATUS_TRANSIENT, $current, self::STATUS_TTL );
+		}
+	}
+}

includes/core/class-analysis-prompts.php

@@ -76,9 +76,9 @@ class PRAutoBlogger_Analysis_Prompts {
 		global $wpdb;
 		$scores_table = $wpdb->prefix . 'prautoblogger_content_scores';
 
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 		$top_posts = $wpdb->get_results(
-			"SELECT cs.post_id, cs.composite_score, p.post_title  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			"SELECT cs.post_id, cs.composite_score, p.post_title
 			FROM {$scores_table} cs
 			JOIN {$wpdb->posts} p ON p.ID = cs.post_id
 			WHERE cs.composite_score > 0

includes/core/class-article-worker.php

@@ -103,7 +103,7 @@ class PRAutoBlogger_Article_Worker {
 			$review = $this->review_with_state( $editor, $content, $idea, $run_id, $item );
 
 			PRAutoBlogger_Pipeline_Status::broadcast( __( 'Saving and publishing…', 'prautoblogger' ) );
-			PRAutoBlogger_Run_Stage_State::start( $run_id, 'publish', '', $item );
+			PRAutoBlogger_Run_Stage_State::start( $run_id, 'publish', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'publish' ), $item );
 			$this->publish_or_draft(
 				$content,
 				$idea,
@@ -174,7 +174,7 @@ class PRAutoBlogger_Article_Worker {
 					return new PRAutoBlogger_Editorial_Review( $data );
 				}
 			}
-			PRAutoBlogger_Run_Stage_State::start( $run_id, 'review', '', $item );
+			PRAutoBlogger_Run_Stage_State::start( $run_id, 'review', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'review' ), $item );
 		}
 
 		$review = $editor->review( $content, $idea );

includes/core/class-chief-editor.php

@@ -64,6 +64,7 @@ class PRAutoBlogger_Chief_Editor {
 				'temperature'     => 0.3,
 				'max_tokens'      => 5000,
 				'response_format' => array( 'type' => 'json_object' ),
+				'stage'           => 'review',
 			)
 		);
 

includes/core/class-content-analyzer.php

@@ -78,6 +78,7 @@ class PRAutoBlogger_Content_Analyzer {
 				'temperature'     => 0.5,
 				'max_tokens'      => 8000,
 				'response_format' => array( 'type' => 'json_object' ),
+				'stage'           => 'analysis',
 			)
 		);
 

includes/core/class-content-generator.php

@@ -194,9 +194,15 @@ class PRAutoBlogger_Content_Generator {
 				);
 				return $cached;
 			}
-			PRAutoBlogger_Run_Stage_State::start( $this->run_id, $stage, '', $this->item_key );
+			PRAutoBlogger_Run_Stage_State::start( $this->run_id, $stage, (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage ), $this->item_key );
 		}
 
+		// v0.18.1: stage metadata for the provider's empty-completion
+		// guard — warning logs and failed-attempt audit rows carry the
+		// real stage + registry key (never sent upstream).
+		$options['stage']      = $stage;
+		$options['prompt_key'] = $prompt_key;
+
 		$ctx = PRAutoBlogger_Opik_Trace_Context::current();
 
 		$span_id = $ctx->start_span(
@@ -223,6 +229,21 @@ class PRAutoBlogger_Content_Generator {
 			$options
 		);
 
+		// v0.18.1 writer-path guard (belt over the provider seam, which
+		// already throws for OpenRouter): no empty article may ever leave
+		// a writing stage — it would flow to the editor, be rejected as
+		// "draft text is missing", and land as an empty draft post.
+		if ( '' === trim( (string) $response['content'] ) ) {
+			throw new \RuntimeException(
+				sprintf(
+					/* translators: 1: writing stage name, 2: model identifier. */
+					__( 'Writing stage "%1$s" produced empty content (model %2$s) — failing the stage instead of passing an empty article downstream.', 'prautoblogger' ),
+					$stage,
+					(string) $response['model']
+				)
+			);
+		}
+
 		$ctx->end_span(
 			$span_id,
 			array(

includes/core/class-cost-reporter.php

@@ -65,8 +65,9 @@ class PRAutoBlogger_Cost_Reporter {
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		$results = $wpdb->get_results(
+			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 			$wpdb->prepare(
-				"SELECT DATE(created_at) as day, SUM(estimated_cost) as total_cost  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT DATE(created_at) as day, SUM(estimated_cost) as total_cost
 				FROM {$table}
 				WHERE created_at >= %s AND response_status = 'success'
 				GROUP BY DATE(created_at)
@@ -102,11 +103,12 @@ class PRAutoBlogger_Cost_Reporter {
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		$results = $wpdb->get_results(
+			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 			$wpdb->prepare(
 				"SELECT stage,
 					SUM(estimated_cost) as total_cost,
 					SUM(prompt_tokens + completion_tokens) as total_tokens,
-					COUNT(*) as call_count  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+					COUNT(*) as call_count
 				FROM {$table}
 				WHERE created_at BETWEEN %s AND %s AND response_status = 'success'
 				GROUP BY stage",

includes/core/class-image-prompt-builder.php

@@ -200,6 +200,7 @@ PROMPT;
 				array(
 					'temperature' => 0.7,
 					'max_tokens'  => self::REWRITER_MAX_TOKENS,
+					'stage'       => 'image_prompt_rewrite',
 				)
 			);
 

includes/core/class-pipeline-runner.php

@@ -185,14 +185,14 @@ class PRAutoBlogger_Pipeline_Runner {
 		$source_labels = is_array( $enabled ) ? implode( ', ', $enabled ) : 'reddit';
 		/* translators: %s is a comma-separated list of enabled source names, e.g. "reddit, llm_research". */
 		PRAutoBlogger_Pipeline_Status::broadcast( sprintf( __( 'Collecting sources from %s…', 'prautoblogger' ), $source_labels ) );
-		PRAutoBlogger_Run_Stage_State::start( $run_id, 'research' );
+		PRAutoBlogger_Run_Stage_State::start( $run_id, 'research', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'research' ) );
 		( new PRAutoBlogger_Source_Collector() )
 			->set_cost_tracker( $cost_tracker )
 			->collect_from_all_sources();
 		PRAutoBlogger_Run_Stage_State::done( $run_id, 'research' );
 
 		PRAutoBlogger_Pipeline_Status::broadcast( __( 'Analyzing topics and scoring…', 'prautoblogger' ) );
-		PRAutoBlogger_Run_Stage_State::start( $run_id, 'analysis' );
+		PRAutoBlogger_Run_Stage_State::start( $run_id, 'analysis', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'analysis' ) );
 		$llm      = new PRAutoBlogger_OpenRouter_Provider();
 		$analyzer = new PRAutoBlogger_Content_Analyzer( $llm, $cost_tracker );
 		$analysis = $analyzer->analyze_recent_data( max( $target * 2, 6 ) );

includes/core/class-post-assembler.php

@@ -108,8 +108,8 @@ class PRAutoBlogger_Post_Assembler {
 		// Find the unlinked research cost row for this run.
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		$research_row = $wpdb->get_row(
-			$wpdb->prepare(
-				"SELECT id, estimated_cost, provider, model, prompt_tokens, completion_tokens  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			$wpdb->prepare( // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT id, estimated_cost, provider, model, prompt_tokens, completion_tokens
 				FROM {$table}
 				WHERE run_id = %s AND stage = 'llm_research' AND post_id IS NULL
 				LIMIT 1",

includes/core/class-publisher.php

@@ -82,6 +82,23 @@ class PRAutoBlogger_Publisher {
 		?string $run_id = null,
 		?PRAutoBlogger_Cost_Tracker $cost_tracker = null
 	): int {
+		// v0.18.1 belt-and-braces: never create a post whose content is
+		// empty once tags and whitespace are stripped — an empty "draft
+		// for human review" (2026-06-11 incident, post 921) reviews
+		// nothing and hides the underlying generation failure. The
+		// provider/writer guards make this unreachable on OpenRouter
+		// paths; this protects every other path into post creation.
+		if ( '' === trim( wp_strip_all_tags( $content ) ) ) {
+			throw new \RuntimeException(
+				sprintf(
+					/* translators: 1: intended post status, 2: article title. */
+					__( 'Refusing to create %1$s post "%2$s": generated content is empty.', 'prautoblogger' ),
+					$post_status,
+					$idea->get_suggested_title()
+				)
+			);
+		}
+
 		// v0.18.0 idempotency: post creation is keyed by run + idea
 		// (check-before-insert) so a retried/resumed run cannot create a
 		// duplicate post. One run_id spans all N articles of a batch, so

includes/core/class-run-stage-state.php

@@ -6,40 +6,33 @@ declare(strict_types=1);
  *
  * Per-run per-stage state machine over `wp_prautoblogger_run_stages`.
  *
- * What: One row per (run_id, stage, agent_role, item_key) holding
- *       pending|running|done|failed|halted plus the stage's output
- *       snapshot (meta_json). This is what makes resume idempotent on the
- *       chained-cron architecture: a `done` stage is NEVER re-run or
- *       re-charged — re-entry reuses its stored output; `done` is sticky
- *       (an upsert cannot demote it). agent_role is the Phase-2 fan-out
- *       dimension (quorum members; the quorum logic itself is Phase 2);
- *       item_key scopes article-level stages because one run_id spans all
- *       N articles of a batch run ('' for run-level stages). Self-healing:
+ * One row per (run_id, stage, agent_role, item_key) holding
+ * pending|running|done|failed|halted plus the output snapshot (meta_json).
+ * Done stages are sticky and never re-charged on resume. Self-healing:
  * a missing table degrades every method to a no-op/false.
- * Who triggers it: Pipeline_Runner (run-level research/analysis),
- *       Article_Worker (per-article generate/review/publish),
- *       Content_Generator (per-LLM-stage outline/draft/polish),
- *       Run_Reaper (stuck-stage sweep + payload pruning).
- * Dependencies: WordPress $wpdb, wp_json_encode.
+ *
+ * v0.18.2: role is resolved from Stage_Display_Map when caller passes ''
+ * so start/done/is_done/get_output are always symmetric. Explicit non-empty
+ * roles (Phase-2 fan-out) are honoured as-is. get() falls back to role=''
+ * on miss for mid-run-upgrade compat with v0.18.1 rows.
  *
  * @see core/class-run-state.php  — Run-level lifecycle + ledger row.
  * @see core/class-run-reaper.php — Sweeps stages stuck in 'running'.
- * @see ARCHITECTURE.md #21        — Idempotency-key design.
+ * @see ARCHITECTURE.md #22       — Pipeline v2 Phase 1 substrate.
  */
 class PRAutoBlogger_Run_Stage_State {
 
 	/** @var bool|null Per-request "run_stages table exists" probe result. */
 	private static ?bool $table_ok = null;
 
-	/** Fully-qualified run_stages table name. */
+	/** @return string Fully-qualified run_stages table name. */
 	public static function table_name(): string {
 		global $wpdb;
 		return $wpdb->prefix . 'prautoblogger_run_stages';
 	}
 
 	/**
-	 * Whether the run_stages table exists and is queryable. Cached per
-	 * request; never throws.
+	 * Whether the run_stages table exists and is queryable. Cached per request.
 	 *
 	 * @return bool
 	 */
@@ -49,7 +42,7 @@ class PRAutoBlogger_Run_Stage_State {
 		}
 		global $wpdb;
 		if ( null === $wpdb ) {
-			return false; // Not cached: $wpdb may appear later in boot.
+			return false;
 		}
 		$table = self::table_name();
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
@@ -59,18 +52,17 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Stable hash identifying one article idea within a run (post-creation
-	 * idempotency + stage item scoping both key off this).
+	 * Stable 16-hex hash for one article idea within a run.
 	 *
 	 * @param PRAutoBlogger_Article_Idea $idea The idea.
-	 * @return string 16-hex-char hash.
+	 * @return string
 	 */
 	public static function idea_hash( PRAutoBlogger_Article_Idea $idea ): string {
 		return substr( md5( $idea->get_suggested_title() . '|' . $idea->get_topic() ), 0, 16 );
 	}
 
 	/**
-	 * Stage item_key for an article idea ('' is reserved for run-level stages).
+	 * Stage item_key for an article idea ('' reserved for run-level stages).
 	 *
 	 * @param PRAutoBlogger_Article_Idea $idea The idea.
 	 * @return string e.g. 'idea:1a2b3c4d5e6f7a8b'.
@@ -80,22 +72,18 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Mark a stage as entered (running). Upsert: first entry inserts the
-	 * row; re-entry bumps `attempt` — but a `done` stage is sticky and is
-	 * neither demoted nor re-counted.
-	 *
-	 * Side effects: one INSERT … ON DUPLICATE KEY UPDATE.
+	 * Mark a stage as running. Sticky: done stages are never demoted.
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name (see Stage_Display_Map).
-	 * @param string $agent_role Fan-out dimension ('' default in Phase 1).
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string $item_key   Article scope ('' for run-level stages).
-	 * @return void
 	 */
 	public static function start( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
 		if ( '' === $run_id || ! self::is_available() ) {
 			return;
 		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
 		global $wpdb;
 		$table = self::table_name();
 		$now   = current_time( 'mysql' );
@@ -120,22 +108,20 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Mark a stage done, persisting its output for resume-without-recharge.
-	 *
-	 * Side effects: one INSERT … ON DUPLICATE KEY UPDATE.
+	 * Mark a stage done and persist its output for resume-without-recharge.
 	 *
 	 * @param string      $run_id     Run UUID.
 	 * @param string      $stage      Stage name.
-	 * @param string      $agent_role Fan-out dimension.
+	 * @param string      $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string      $item_key   Article scope.
-	 * @param string|null $output     Stage output to snapshot (pruned after R days).
-	 * @param float       $cost_usd   Cost attributed to the stage.
-	 * @return void
+	 * @param string|null $output     Stage output snapshot (pruned after R days).
+	 * @param float       $cost_usd   Cost attributed to this stage.
 	 */
 	public static function done( string $run_id, string $stage, string $agent_role = '', string $item_key = '', ?string $output = null, float $cost_usd = 0.0 ): void {
 		if ( '' === $run_id || ! self::is_available() ) {
 			return;
 		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
 		global $wpdb;
 		$table = self::table_name();
 		$now   = current_time( 'mysql' );
@@ -166,18 +152,18 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Mark a stage failed (does not demote a `done` stage).
+	 * Mark a stage failed (does not demote a done stage).
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name.
-	 * @param string $agent_role Fan-out dimension.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string $item_key   Article scope.
-	 * @return void
 	 */
 	public static function fail( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
 		if ( '' === $run_id || ! self::is_available() ) {
 			return;
 		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
 		global $wpdb;
 		$table = self::table_name();
 		$now   = current_time( 'mysql' );
@@ -197,18 +183,20 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Fetch one stage row.
+	 * Fetch one stage row. Falls back to role='' on miss for mid-run-upgrade
+	 * compat with v0.18.1 rows (one extra indexed query, only on miss).
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name.
-	 * @param string $agent_role Fan-out dimension.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string $item_key   Article scope.
-	 * @return array<string, mixed>|null Row or null.
+	 * @return array<string, mixed>|null
 	 */
 	public static function get( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): ?array {
 		if ( '' === $run_id || ! self::is_available() ) {
 			return null;
 		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
 		global $wpdb;
 		$table = self::table_name();
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
@@ -222,7 +210,25 @@ class PRAutoBlogger_Run_Stage_State {
 			),
 			ARRAY_A
 		);
-		return is_array( $row ) ? $row : null;
+		if ( is_array( $row ) ) {
+			return $row;
+		}
+		// v0.18.1 upgrade compat: rows started before this fix carry role=''.
+		// One extra indexed query, only on miss, only for known stages.
+		if ( '' !== $agent_role ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+			$legacy = $wpdb->get_row(
+				$wpdb->prepare(
+					"SELECT * FROM {$table} WHERE run_id = %s AND stage = %s AND agent_role = '' AND item_key = %s",
+					$run_id,
+					$stage,
+					$item_key
+				),
+				ARRAY_A
+			);
+			return is_array( $legacy ) ? $legacy : null;
+		}
+		return null;
 	}
 
 	/**
@@ -230,7 +236,7 @@ class PRAutoBlogger_Run_Stage_State {
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name.
-	 * @param string $agent_role Fan-out dimension.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string $item_key   Article scope.
 	 * @return bool
 	 */
@@ -244,7 +250,7 @@ class PRAutoBlogger_Run_Stage_State {
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name.
-	 * @param string $agent_role Fan-out dimension.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
 	 * @param string $item_key   Article scope.
 	 * @return string|null
 	 */
@@ -258,13 +264,10 @@ class PRAutoBlogger_Run_Stage_State {
 	}
 
 	/**
-	 * Fail every still-open (pending/running) stage of one item — used by
-	 * the worker's catch-all so a crashed article leaves no stage stuck
-	 * in 'running' until the reaper. Done stages are untouched.
+	 * Fail every still-open stage of one item. Done stages are untouched.
 	 *
 	 * @param string $run_id   Run UUID.
 	 * @param string $item_key Stage item key ('' = run-level stages).
-	 * @return void
 	 */
 	public static function fail_open_for_item( string $run_id, string $item_key ): void {
 		if ( '' === $run_id || ! self::is_available() ) {
@@ -290,4 +293,21 @@ class PRAutoBlogger_Run_Stage_State {
 	public static function flush_cache(): void {
 		self::$table_ok = null;
 	}
+
+	/**
+	 * Resolve the effective agent role for a stage.
+	 *
+	 * '' → derive from Stage_Display_Map (unknown stages map to '').
+	 * Non-empty → returned as-is (Phase-2 explicit fan-out role).
+	 *
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Caller-supplied role ('' = auto-resolve).
+	 * @return string Effective agent role.
+	 */
+	private static function resolve_role( string $stage, string $agent_role ): string {
+		if ( '' !== $agent_role ) {
+			return $agent_role;
+		}
+		return (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage );
+	}
 }

includes/core/class-source-collector.php

@@ -76,8 +76,33 @@ class PRAutoBlogger_Source_Collector {
 					'collector'
 				);
 			} catch ( \Throwable $e ) {
-				PRAutoBlogger_Logger::instance()->error( sprintf( 'Collection %s from %s: %s', get_class( $e ), $source_type, $e->getMessage() ), 'collector' );
-				// Continue with other sources — one failure shouldn't stop everything.
+				// Structured failure meta: model slug, HTTP status (parsed from message),
+				// and first ~200 chars of the error body — enables post-incident diagnosis
+				// without needing to re-run the failing collection. Added v0.18.2.
+				$config_for_log = $this->get_config_for_source( $source_type );
+				$model_slug     = (string) ( $config_for_log['model'] ?? '' );
+				$err_msg        = $e->getMessage();
+				// Extract HTTP status from "OpenRouter API error (HTTP NNN): ..." pattern.
+				$http_status = 0;
+				if ( preg_match( '/HTTP (\d{3})/', $err_msg, $m ) ) {
+					$http_status = (int) $m[1];
+				}
+				PRAutoBlogger_Logger::instance()->error(
+					sprintf(
+						'Collection %s from %s: %s',
+						get_class( $e ),
+						$source_type,
+						$e->getMessage()
+					),
+					'collector',
+					array(
+						'source'      => $source_type,
+						'model'       => $model_slug,
+						'http_status' => $http_status,
+						'error_body'  => mb_substr( $err_msg, 0, 200 ),
+					)
+				);
+				// Continue with other sources — one failure should not stop everything.
 			}
 		}
 

includes/providers/class-llm-research-provider.php

@@ -70,6 +70,7 @@ class PRAutoBlogger_LLM_Research_Provider implements PRAutoBlogger_Source_Provid
 				'temperature'     => 0.7,
 				'max_tokens'      => 8000,
 				'response_format' => array( 'type' => 'json_object' ),
+				'stage'           => 'llm_research',
 			)
 		);
 

includes/providers/class-open-router-completion-guard.php

@@ -0,0 +1,168 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Empty-completion guard for OpenRouter chat responses (v0.18.1).
+ *
+ * What: Treats a chat completion whose visible content is empty/whitespace
+ *       as a FAILURE, never a success — per the LLM-call discipline:
+ *       schema-validate every output, retry/fall back, never silently
+ *       pass. The incident this prevents (2026-06-11, prod run acf24029,
+ *       draft post 921): a true reasoning model at a high reasoning effort
+ *       spent the entire max_tokens completion budget on thinking,
+ *       finished with finish_reason='length', and emitted zero visible
+ *       content — which flowed writer → editor (reject: "draft text is
+ *       missing") → an empty draft post in the Review Queue, with the
+ *       cost booked as 'success'.
+ *
+ *       Behavior on every parsed response:
+ *       - finish_reason='length' is warning-logged (model, stage, prompt/
+ *         completion/reasoning tokens) whether or not content survived.
+ *       - Empty content + (finish_reason='length' OR reasoning active on
+ *         the request) → ONE retry with reasoning disabled for that call
+ *         (per-call `reasoning` override), then fail the stage.
+ *       - Every failed/retried attempt lands in generation_log with its
+ *         REAL response_status ('error') and token burn, and — inside a
+ *         v0.18.0 run — a run_decisions row records the verdict.
+ * Who triggers it: PRAutoBlogger_OpenRouter_Provider::send_chat_completion()
+ *       on every successfully parsed response.
+ * Dependencies: Logger, Cost_Tracker (failure rows), Run_Context (run
+ *       attribution), Audit_Writer (run_decisions verdicts).
+ *
+ * @see class-open-router-provider.php        — Integration point; supplies the retry callable.
+ * @see class-open-router-response-parser.php — Produces the parsed array assessed here.
+ * @see class-open-router-request-builder.php — Reasoning token cap (first line of defense).
+ * @see core/class-audit-writer.php           — run_decisions verdict rows.
+ */
+class PRAutoBlogger_OpenRouter_Completion_Guard {
+
+	/** Verdict recorded when an empty attempt is retried with reasoning disabled. */
+	public const VERDICT_RETRY = 'retry_reasoning_disabled';
+
+	/** Verdict recorded when a call finally fails for empty content. */
+	public const VERDICT_FAIL = 'failed_empty_completion';
+
+	/**
+	 * Assess a parsed completion: pass it through, retry once, or fail loudly.
+	 *
+	 * @param array<string, mixed> $parsed           Parsed response from Response_Parser::parse_success().
+	 * @param array<string, mixed> $options          Original call options. Reads the caller-metadata keys
+	 *                                               'stage' / 'prompt_key' (audit attribution) and
+	 *                                               'empty_retry' (marks the retry attempt — never retried twice).
+	 * @param bool                 $reasoning_active Whether the dispatched request had reasoning enabled.
+	 * @param callable             $retry            Re-dispatches the call with the options it is given.
+	 *                                               Invoked at most once, with reasoning disabled.
+	 *
+	 * @return array<string, mixed> A completion whose visible content is non-empty.
+	 *
+	 * @throws \RuntimeException When content is empty and the retry budget is spent or a retry
+	 *                           cannot plausibly help.
+	 */
+	public function finalize( array $parsed, array $options, bool $reasoning_active, callable $retry ): array {
+		$stage         = (string) ( $options['stage'] ?? 'unknown' );
+		$finish_reason = (string) ( $parsed['finish_reason'] ?? 'unknown' );
+
+		if ( 'length' === $finish_reason ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf(
+					'Completion hit its max_tokens ceiling (finish_reason=length): model=%s, stage=%s, prompt_tokens=%d, completion_tokens=%d, reasoning_tokens=%d.',
+					(string) $parsed['model'],
+					$stage,
+					(int) $parsed['prompt_tokens'],
+					(int) $parsed['completion_tokens'],
+					(int) $parsed['reasoning_tokens']
+				),
+				'openrouter'
+			);
+		}
+
+		if ( '' !== trim( (string) ( $parsed['content'] ?? '' ) ) ) {
+			return $parsed; // Healthy completion — visible content present.
+		}
+
+		$already_retried = ! empty( $options['empty_retry'] );
+		// A reasoning-disabled retry can plausibly help when the budget was
+		// exhausted (length) or when reasoning was eating the budget.
+		$retry_can_help = 'length' === $finish_reason || $reasoning_active;
+
+		if ( $retry_can_help && ! $already_retried ) {
+			$note = sprintf(
+				'Empty completion (finish_reason=%s, completion_tokens=%d, reasoning_tokens=%d) — retrying once with reasoning disabled.',
+				$finish_reason,
+				(int) $parsed['completion_tokens'],
+				(int) $parsed['reasoning_tokens']
+			);
+			$this->record_attempt( $parsed, $options, $stage, self::VERDICT_RETRY, $note );
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf( 'Stage %s: %s (model %s)', $stage, $note, (string) $parsed['model'] ),
+				'openrouter'
+			);
+
+			$retry_options                = $options;
+			$retry_options['reasoning']   = array( 'enabled' => false );
+			$retry_options['empty_retry'] = true;
+			return $retry( $retry_options );
+		}
+
+		$note = sprintf(
+			'Empty completion (finish_reason=%s, completion_tokens=%d, reasoning_tokens=%d)%s — failing the call.',
+			$finish_reason,
+			(int) $parsed['completion_tokens'],
+			(int) $parsed['reasoning_tokens'],
+			$already_retried ? ' after a reasoning-disabled retry' : ''
+		);
+		$this->record_attempt( $parsed, $options, $stage, self::VERDICT_FAIL, $note );
+
+		throw new \RuntimeException(
+			sprintf(
+				/* translators: 1: pipeline stage, 2: model identifier, 3: finish_reason value, 4: retry note. */
+				__( 'LLM call for stage "%1$s" returned empty content (model %2$s, finish_reason=%3$s)%4$s.', 'prautoblogger' ),
+				$stage,
+				(string) $parsed['model'],
+				$finish_reason,
+				$already_retried ? __( ' after a reasoning-disabled retry', 'prautoblogger' ) : ''
+			)
+		);
+	}
+
+	/**
+	 * Book a failed/retried attempt: a generation_log row with the REAL
+	 * response_status and token burn (the empty call still cost money),
+	 * plus a run_decisions verdict for new-style runs. Both writes are
+	 * self-healing no-ops on a half-migrated schema; neither can throw.
+	 *
+	 * @param array<string, mixed> $parsed  Parsed response of the failed attempt.
+	 * @param array<string, mixed> $options Call options ('prompt_key' attribution).
+	 * @param string               $stage   Stage label for the log row.
+	 * @param string               $verdict VERDICT_RETRY or VERDICT_FAIL.
+	 * @param string               $note    Human-readable failure note.
+	 * @return void
+	 */
+	private function record_attempt( array $parsed, array $options, string $stage, string $verdict, string $note ): void {
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+
+		$tracker = new PRAutoBlogger_Cost_Tracker();
+		if ( null !== $run_id && '' !== $run_id ) {
+			// Attribute the row to the surrounding run. Idempotent: the
+			// run context, ledger row, and prompt pins already exist.
+			$tracker->set_run_id( $run_id );
+		}
+		$tracker->log_api_call(
+			null,
+			$stage,
+			'OpenRouter',
+			(string) $parsed['model'],
+			(int) $parsed['prompt_tokens'],
+			(int) $parsed['completion_tokens'],
+			'error',
+			$note,
+			null,
+			isset( $options['prompt_key'] ) ? (string) $options['prompt_key'] : null
+		);
+
+		// run_decisions verdict — no-op outside a run or pre-1.2.0 schema.
+		PRAutoBlogger_Audit_Writer::record_decision( (string) ( $run_id ?? '' ), $stage, $verdict, $note );
+	}
+}

includes/providers/class-open-router-provider.php

@@ -19,8 +19,9 @@ declare(strict_types=1);
  * @see class-open-router-config.php          — Config helpers (base URL, cache TTL).
  * @see class-open-router-pricing.php         — Pricing and model list lookups.
  * @see class-open-router-validator.php       — Credential validation (delegated).
- * @see class-open-router-request-builder.php — Request header building + cURL filter.
+ * @see class-open-router-request-builder.php — Request body/header building + cURL filter.
  * @see class-open-router-response-parser.php — Response parsing + error classification.
+ * @see class-open-router-completion-guard.php — Empty-completion guard + reasoning-off retry (v0.18.1).
  * @see class-cost-tracker.php                — Called after every request to log token usage.
  * @see ARCHITECTURE.md                       — Data flow diagram showing where this fits.
  */
@@ -40,8 +41,15 @@ class PRAutoBlogger_OpenRouter_Provider implements PRAutoBlogger_LLM_Provider_In
 	 *     temperature?: float,
 	 *     max_tokens?: int,
 	 *     response_format?: array{type: string},
-	 *     reasoning?: array{enabled: bool, effort?: string},
-	 * } $options Optional parameters. Pass 'reasoning' to override the global setting.
+	 *     reasoning?: array{enabled: bool, effort?: string, max_tokens?: int},
+	 *     stage?: string,
+	 *     prompt_key?: string,
+	 *     empty_retry?: bool,
+	 * } $options Optional parameters. Pass 'reasoning' to override the global
+	 *            setting. 'stage'/'prompt_key' are caller metadata for the
+	 *            empty-completion guard's logging + audit rows (never sent
+	 *            upstream); 'empty_retry' is set internally by the guard's
+	 *            single reasoning-disabled retry.
 	 *
 	 * @return array{
 	 *     content: string,
@@ -52,46 +60,39 @@ class PRAutoBlogger_OpenRouter_Provider implements PRAutoBlogger_LLM_Provider_In
 	 *     finish_reason: string,
 	 * }
 	 *
-	 * @throws \RuntimeException On API error after retries exhausted.
+	 * @throws \RuntimeException On API error after retries exhausted, or when the
+	 *                           completion's visible content is empty/whitespace
+	 *                           (v0.18.1 guard — after at most one reasoning-disabled retry).
 	 * @throws PRAutoBlogger_Cost_Ceiling_Exception When the per-run cost governor blocks
 	 *                                              the call (run already halted).
 	 */
 	public function send_chat_completion( array $messages, string $model, array $options = array() ): array {
+		$builder = new PRAutoBlogger_OpenRouter_Request_Builder();
+
 		// Fetch + format-validate the key (moved to Request_Builder in
 		// v0.18.0 for the 300-line cap; behavior unchanged — throws the
 		// same messages on missing/corrupted keys).
-		$api_key = ( new PRAutoBlogger_OpenRouter_Request_Builder() )->resolve_api_key();
+		$api_key = $builder->resolve_api_key();
 
-		$body = array(
-			'model'    => $model,
-			'messages' => $messages,
-		);
+		// Body assembly — incl. global/per-call reasoning and the v0.18.1
+		// reasoning token cap + completion headroom — lives in the builder.
+		$body = $builder->build_body( $messages, $model, $options );
 
-		if ( isset( $options['temperature'] ) ) {
-			$body['temperature'] = $options['temperature'];
-		}
-		if ( isset( $options['max_tokens'] ) ) {
-			$body['max_tokens'] = $options['max_tokens'];
-		}
-		if ( isset( $options['response_format'] ) ) {
-			$body['response_format'] = $options['response_format'];
-		}
-
-		// Reasoning mode: explicit caller override takes priority, then global setting.
-		if ( isset( $options['reasoning'] ) ) {
-			$body['reasoning'] = $options['reasoning'];
-		} elseif ( '1' === get_option( 'prautoblogger_reasoning_enabled', '0' ) ) {
-			$body['reasoning'] = array(
-				'enabled' => true,
-				'effort'  => get_option( 'prautoblogger_reasoning_effort', 'medium' ),
-			);
-		}
+		// Whether the outgoing request has reasoning enabled — drives the
+		// empty-completion retry decision after parse.
+		$reasoning_active = isset( $body['reasoning'] ) && false !== ( $body['reasoning']['enabled'] ?? true );
 
 		// v0.18.0 — per-run cost governor: reserve the worst-case estimate
 		// BEFORE any dispatch. Throws (and the run is already halted) when
 		// the reservation would breach the run ceiling; returns null when
 		// this process is not inside a governed run (historical behavior).
-		$reservation = PRAutoBlogger_Cost_Governor::open_chat_reservation( $model, $messages, $options );
+		// v0.18.1: the estimate uses the EFFECTIVE completion ceiling from
+		// the built body (incl. reasoning headroom), not the raw option.
+		$govern_options = $options;
+		if ( isset( $body['max_tokens'] ) ) {
+			$govern_options['max_tokens'] = $body['max_tokens'];
+		}
+		$reservation = PRAutoBlogger_Cost_Governor::open_chat_reservation( $model, $messages, $govern_options );
 
 		$last_error = '';
 
@@ -101,7 +102,6 @@ class PRAutoBlogger_OpenRouter_Provider implements PRAutoBlogger_LLM_Provider_In
 		$cache_ttl   = $config->get_cache_ttl_seconds();
 		$via_gateway = $config->is_via_gateway();
 
-		$builder          = new PRAutoBlogger_OpenRouter_Request_Builder();
 		$request_headers  = $builder->build_headers( $api_key, $via_gateway, $cache_ttl );
 		$curl_auth_filter = $builder->register_curl_auth_filter( $request_headers, $base_host );
 
@@ -190,7 +190,21 @@ class PRAutoBlogger_OpenRouter_Provider implements PRAutoBlogger_LLM_Provider_In
 					$this->estimate_cost( $model, (int) $parsed['prompt_tokens'], (int) $parsed['completion_tokens'] )
 				);
 				$reservation = null;
-				return $parsed;
+
+				// v0.18.1 — empty-completion guard: empty visible content
+				// is a FAILURE, never a success. Warns on finish_reason=
+				// length, retries ONCE with reasoning disabled when that
+				// can plausibly help, books failed attempts with their
+				// real status, and otherwise throws. The recursive retry
+				// manages its own reservation and cURL filter.
+				return ( new PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+					$parsed,
+					$options,
+					$reasoning_active,
+					function ( array $retry_options ) use ( $messages, $model ): array {
+						return $this->send_chat_completion( $messages, $model, $retry_options );
+					}
+				);
 			}
 
 			// All retries exhausted.

includes/providers/class-open-router-request-builder.php

@@ -18,6 +18,100 @@ declare(strict_types=1);
  */
 class PRAutoBlogger_OpenRouter_Request_Builder {
 
+	/**
+	 * Build the JSON request body for a chat-completion call.
+	 *
+	 * Centralizes option handling (v0.18.1, moved from the provider for
+	 * the 300-line cap): temperature, max_tokens, response_format, and
+	 * the reasoning block — an explicit caller override takes priority
+	 * over the global setting (that per-call override is how the
+	 * empty-completion retry disables reasoning for its second attempt).
+	 *
+	 * Caller-metadata keys ('stage', 'prompt_key', 'empty_retry') are
+	 * deliberately NOT copied into the HTTP body.
+	 *
+	 * @param array<int, array{role: string, content: string}> $messages Chat messages.
+	 * @param string                                           $model    Model identifier.
+	 * @param array<string, mixed>                             $options  Call options.
+	 *
+	 * @return array<string, mixed> Request body ready for wp_json_encode().
+	 */
+	public function build_body( array $messages, string $model, array $options ): array {
+		$body = array(
+			'model'    => $model,
+			'messages' => $messages,
+		);
+
+		if ( isset( $options['temperature'] ) ) {
+			$body['temperature'] = $options['temperature'];
+		}
+		if ( isset( $options['max_tokens'] ) ) {
+			$body['max_tokens'] = $options['max_tokens'];
+		}
+		if ( isset( $options['response_format'] ) ) {
+			$body['response_format'] = $options['response_format'];
+		}
+
+		// Reasoning mode: explicit caller override takes priority, then global setting.
+		if ( isset( $options['reasoning'] ) ) {
+			$body['reasoning'] = $options['reasoning'];
+		} elseif ( '1' === get_option( 'prautoblogger_reasoning_enabled', '0' ) ) {
+			$body['reasoning'] = array(
+				'enabled' => true,
+				'effort'  => get_option( 'prautoblogger_reasoning_effort', 'medium' ),
+			);
+		}
+
+		return $this->apply_reasoning_budget( $body );
+	}
+
+	/**
+	 * Reasoning budget sanity (v0.18.1): cap thinking, protect content.
+	 *
+	 * When the outgoing request enables reasoning and carries a completion
+	 * ceiling, the thinking budget is capped via OpenRouter's
+	 * `reasoning.max_tokens` and the completion ceiling is raised by the
+	 * same amount — so no reasoning effort (incl. xhigh) can consume the
+	 * entire completion budget and emit an empty message (the 2026-06-11
+	 * empty-draft incident, prod run acf24029). The cap is SETTINGS-backed
+	 * (`prautoblogger_reasoning_max_tokens`, default
+	 * PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS, 0 = pure effort mode:
+	 * no cap, no headroom — the historical behavior). When the cap is
+	 * active it replaces `effort` — OpenRouter treats the two as
+	 * alternative budget controls and normalizes max_tokens per model.
+	 *
+	 * No-op when reasoning is absent/disabled on the request, when the
+	 * request has no completion ceiling, or when the cap setting is 0.
+	 *
+	 * @param array<string, mixed> $body Assembled request body.
+	 *
+	 * @return array<string, mixed> Body with the reasoning budget applied.
+	 */
+	private function apply_reasoning_budget( array $body ): array {
+		if ( ! isset( $body['reasoning'] ) || false === ( $body['reasoning']['enabled'] ?? true ) ) {
+			return $body;
+		}
+		if ( ! isset( $body['max_tokens'] ) ) {
+			return $body; // No completion ceiling to protect.
+		}
+
+		if ( ! isset( $body['reasoning']['max_tokens'] ) ) {
+			$cap = absint( get_option( 'prautoblogger_reasoning_max_tokens', PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS ) );
+			if ( $cap < 1 ) {
+				return $body; // Cap disabled — pure effort mode.
+			}
+			$body['reasoning']['max_tokens'] = $cap;
+			unset( $body['reasoning']['effort'] );
+		}
+
+		// Headroom: models that spend reasoning from the completion budget
+		// (e.g. deepseek/deepseek-v4-flash) must still have the caller's
+		// full max_tokens available for visible content.
+		$body['max_tokens'] = (int) $body['max_tokens'] + (int) $body['reasoning']['max_tokens'];
+
+		return $body;
+	}
+
 	/**
 	 * Build request headers for OpenRouter API call.
 	 *

includes/providers/class-runware-catalog-fetcher.php

@@ -0,0 +1,211 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Runware modelSearch API fetcher — handles pagination and response normalization
+ * for the Runware model catalog sync.
+ *
+ * Extracted from PRAutoBlogger_Runware_Model_Catalog for the 300-line rule.
+ * Provides two public methods consumed by the catalog class:
+ *   - fetch_all_text_to_image(): paginates modelSearch and returns raw results.
+ *   - normalize_models(): converts raw results to Image_Model_Registry shape.
+ *
+ * API note (2026-06-12): Runware retired taskType:models. The replacement is
+ * taskType:modelSearch — requires auth+modelSearch tasks, returns paginated
+ * results with `air` identifiers and `capabilities[]`. Text-to-image filtering
+ * is client-side (no server-side capability filter is available). The catalog
+ * has 320k+ entries (mostly community checkpoints); we cap at PAGE_CAP pages
+ * of PAGE_SIZE results to bound request cost while covering curated t2i models.
+ *
+ * @see class-runware-model-catalog.php  — Caller; owns caching, cooldown, and fallback.
+ * @see class-image-model-registry.php  — Consumes the normalized model shape.
+ */
+class PRAutoBlogger_Runware_Catalog_Fetcher {
+
+	private const RUNWARE_API_URL  = 'https://api.runware.ai/v1';
+	private const HTTP_TIMEOUT_SEC = 30;
+
+	/**
+	 * Maximum pages to fetch per sync cycle.
+	 * 5 pages × 100 results = 500 models inspected.
+	 * Curated Runware-native text-to-image models number ~50 in the first 500.
+	 */
+	private const PAGE_CAP  = 5;
+	private const PAGE_SIZE = 100;
+
+	/**
+	 * Fetch all text-to-image model results via paginated modelSearch calls.
+	 *
+	 * Issues up to PAGE_CAP requests against the Runware /v1 endpoint, each
+	 * sending an auth task + a modelSearch task with offset/limit. Stops early
+	 * when all available results have been fetched. Returns the raw result
+	 * objects (unfiltered — normalize_models() applies the capability filter).
+	 *
+	 * @param string $api_key Decrypted Runware API key.
+	 * @return array<int, array<string, mixed>> Raw modelSearch result objects.
+	 * @throws \RuntimeException On HTTP error or malformed response for any page.
+	 */
+	public function fetch_all_text_to_image( string $api_key ): array {
+		$all_results   = array();
+		$offset        = 0;
+		$pages_fetched = 0;
+		$total         = PHP_INT_MAX; // Set after first page.
+
+		do {
+			$page = $this->fetch_page( $api_key, $offset, self::PAGE_SIZE );
+			if ( empty( $page['results'] ) ) {
+				break;
+			}
+
+			$all_results   = array_merge( $all_results, $page['results'] );
+			$total         = (int) $page['totalResults'];
+			$offset       += self::PAGE_SIZE;
+			++$pages_fetched;
+
+			if ( count( $all_results ) >= $total ) {
+				break;
+			}
+		} while ( $pages_fetched < self::PAGE_CAP );
+
+		if ( $pages_fetched >= self::PAGE_CAP && count( $all_results ) < $total ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf(
+					'Runware catalog: reached page cap (%d pages, %d models fetched of %d total). '
+					. 'Increase PAGE_CAP if curated models are being missed.',
+					self::PAGE_CAP,
+					count( $all_results ),
+					$total
+				),
+				'runware-catalog'
+			);
+		}
+
+		return $all_results;
+	}
+
+	/**
+	 * Normalize raw modelSearch result objects to the Image_Model_Registry shape.
+	 *
+	 * Filters to models with "io:text-to-image" in capabilities[].
+	 * Uses the `air` field as the model id (e.g. "runware:100@1").
+	 * Uses the `comment` field as the human-readable description.
+	 * cost_per_image is always null here — merged by the catalog class.
+	 *
+	 * @param array<int, array<string, mixed>> $raw_models Raw modelSearch results.
+	 * @return array<int, array<string, mixed>> Normalized models.
+	 */
+	public function normalize_models( array $raw_models ): array {
+		$normalized = array();
+
+		foreach ( $raw_models as $raw ) {
+			if ( ! is_array( $raw ) ) {
+				continue;
+			}
+
+			$capabilities = is_array( $raw['capabilities'] ?? null ) ? $raw['capabilities'] : array();
+			if ( ! in_array( 'io:text-to-image', $capabilities, true ) ) {
+				continue;
+			}
+
+			$air = (string) ( $raw['air'] ?? '' );
+			if ( '' === $air ) {
+				continue;
+			}
+
+			$normalized[] = array(
+				'id'             => $air,
+				'name'           => (string) ( $raw['name'] ?? $air ),
+				'provider'       => 'runware',
+				'cost_per_image' => null,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => (string) ( $raw['comment'] ?? '' ),
+			);
+		}
+
+		return $normalized;
+	}
+
+	/**
+	 * Fetch a single page of modelSearch results.
+	 *
+	 * Sends [authentication, modelSearch] task pair to /v1.
+	 * A fresh auth task is required per request per Runware's WebSocket-based
+	 * API contract (each HTTP POST is a stateless task array).
+	 *
+	 * @param string $api_key Decrypted Runware API key.
+	 * @param int    $offset  Pagination offset (0-based).
+	 * @param int    $limit   Page size.
+	 * @return array{results: array<int, array<string, mixed>>, totalResults: int}
+	 * @throws \RuntimeException On HTTP error or malformed response.
+	 */
+	private function fetch_page( string $api_key, int $offset, int $limit ): array {
+		$payload = array(
+			array(
+				'taskType' => 'authentication',
+				'apiKey'   => $api_key,
+			),
+			array(
+				'taskType' => 'modelSearch',
+				'taskUUID' => wp_generate_uuid4(),
+				'offset'   => $offset,
+				'limit'    => $limit,
+			),
+		);
+
+		$response = wp_remote_post(
+			self::RUNWARE_API_URL,
+			array(
+				'timeout' => self::HTTP_TIMEOUT_SEC,
+				'headers' => array( 'Content-Type' => 'application/json' ),
+				'body'    => wp_json_encode( $payload ),
+			)
+		);
+
+		if ( is_wp_error( $response ) ) {
+			throw new \RuntimeException(
+				sprintf( 'Runware modelSearch unreachable: %s', $response->get_error_message() )
+			);
+		}
+
+		$status = (int) wp_remote_retrieve_response_code( $response );
+		if ( 200 !== $status ) {
+			throw new \RuntimeException(
+				sprintf( 'Runware modelSearch returned HTTP %d', $status )
+			);
+		}
+
+		$raw     = (string) wp_remote_retrieve_body( $response );
+		$decoded = json_decode( $raw, true );
+
+		if ( ! is_array( $decoded ) ) {
+			throw new \RuntimeException( 'Runware modelSearch response is not valid JSON.' );
+		}
+
+		if ( isset( $decoded['errors'] ) && is_array( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
+			$first_msg = '';
+			if ( ! empty( $decoded['errors'][0]['message'] ) ) {
+				$first_msg = ': ' . (string) $decoded['errors'][0]['message'];
+			}
+			throw new \RuntimeException( 'Runware modelSearch API error' . $first_msg );
+		}
+
+		$data = $decoded['data'] ?? array();
+		if ( ! is_array( $data ) || empty( $data ) ) {
+			return array(
+				'results' => array(),
+				'totalResults' => 0,
+			);
+		}
+
+		$item    = $data[0];
+		$results = is_array( $item['results'] ?? null ) ? $item['results'] : array();
+		$total   = isset( $item['totalResults'] ) ? (int) $item['totalResults'] : 0;
+
+		return array(
+			'results' => $results,
+			'totalResults' => $total,
+		);
+	}
+}

includes/providers/class-runware-image-support.php

@@ -181,7 +181,8 @@ class PRAutoBlogger_Runware_Image_Support {
 	 */
 	public function normalize_seed( ?int $seed ): int {
 		if ( null === $seed || $seed < 1 ) {
-			$derived = (int) ( ( microtime( true ) * 1000 ) % 2147483647 );
+			// Cast to int before modulo — float % int is deprecated in PHP 8 (v0.18.2).
+			$derived = (int) round( microtime( true ) * 1000 ) % 2147483647;
 			return $derived > 0 ? $derived : 1;
 		}
 		return $seed;

includes/providers/class-runware-model-catalog.php

@@ -4,18 +4,30 @@ declare(strict_types=1);
 /**
  * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
  *
- * Runware model catalog sync — fetches live model list via Runware's /v1 endpoint,
- * filters to text-to-image tasks, caches normalized results, and falls back to
- * hardcoded list on API failure.
+ * Runware model catalog sync — orchestrates periodic fetching, caching, failure
+ * cooldown, and fallback for the Runware model list.
  *
- * What: Syncs Runware's model catalog periodically (daily cron + on-demand AJAX),
- *       caches the results in WP options, and merges pricing data from the pricing
- *       class when Runware's API doesn't expose it.
+ * What: Syncs Runware's model catalog (daily cron + on-demand AJAX), caches
+ *       normalized results in WP options (v2 schema key — see below), merges
+ *       pricing, and enforces a per-failure cooldown to stop admin-page-load
+ *       cascades when the API is broken or the key is misconfigured.
  * Who triggers it: Daily cron (prautoblogger_sync_runware_models), AJAX "Sync now"
  *                  button in PRAdmin, and lazy-load via PRAutoBlogger_Image_Model_Registry.
- * Dependencies: PRAutoBlogger_Logger, PRAutoBlogger_Runware_Image_Pricing,
- *               PRAutoBlogger_Image_Model_Registry.
+ * Dependencies: PRAutoBlogger_Runware_Catalog_Fetcher, PRAutoBlogger_Logger,
+ *               PRAutoBlogger_Runware_Image_Pricing, PRAutoBlogger_Image_Model_Registry.
  *
+ * Cache schema note: option key is prautoblogger_runware_model_cache_v2 (bumped
+ * from v1) to cleanly invalidate cached rows that used the old taskType:models
+ * response shape (taskType/requiresImage fields). The v1 option is left in place
+ * and will be purged by the next WP options cleanup pass.
+ *
+ * Failure cooldown: prautoblogger_runware_catalog_last_failure_at records the
+ * last failure timestamp. is_in_failure_cooldown() checks it against
+ * prautoblogger_runware_catalog_failure_cooldown_seconds (default 3600s). This
+ * caps errors from admin page loads to ~24/day (24h / 1h cooldown) rather than
+ * 40+/day from every Settings/picker page load triggering a live sync.
+ *
+ * @see class-runware-catalog-fetcher.php      — Pagination + normalize (extracted for 300-line rule).
  * @see class-runware-image-pricing.php        — Authoritative pricing source & fallback models.
  * @see admin/class-image-model-registry.php   — Caller; merges Runware + OpenRouter lists.
  * @see class-prautoblogger.php                — Registers daily cron + AJAX hook.
@@ -23,20 +35,27 @@ declare(strict_types=1);
  */
 class PRAutoBlogger_Runware_Model_Catalog {
 
-	private const RUNWARE_API_URL = 'https://api.runware.ai/v1';
 	private const CACHE_TTL_SECONDS = 86400;
-	private const HTTP_TIMEOUT_SECONDS = 30;
 
 	/**
-	 * Fetch the Runware model catalog, normalize to the Image_Model_Registry
-	 * shape, and write to WP options cache. Returns true on success, false on
-	 * API failure or parse error.
+	 * Option key for the v2 normalized model cache (air-identifier schema).
+	 * Bumped from v1 (prautoblogger_runware_model_cache) to force re-sync.
+	 */
+	private const CACHE_OPTION      = 'prautoblogger_runware_model_cache_v2';
+	private const CACHE_TS_OPTION   = 'prautoblogger_runware_model_cache_updated_at';
+	private const FAILURE_TS_OPTION = 'prautoblogger_runware_catalog_last_failure_at';
+	private const COOLDOWN_SETTING  = 'prautoblogger_runware_catalog_failure_cooldown_seconds';
+	private const COOLDOWN_DEFAULT  = 3600;
+
+	/**
+	 * Fetch, normalize, merge pricing, and cache the Runware model catalog.
+	 * On success: writes cache + clears failure timestamp. Returns true.
+	 * On failure: writes failure timestamp for cooldown. Returns false.
 	 *
-	 * Side effects: makes HTTP request to Runware API, writes WP options.
 	 * Error handling: logs via PRAutoBlogger_Logger, never throws, always
-	 *                 returns bool to allow fallback to cached list.
+	 *                 returns bool to allow fallback to cached/hardcoded list.
 	 *
-	 * @return bool True on successful fetch and cache update; false on API or parse error.
+	 * @return bool True on successful fetch and cache update; false otherwise.
 	 */
 	public function sync(): bool {
 		try {
@@ -49,16 +68,19 @@ class PRAutoBlogger_Runware_Model_Catalog {
 				return false;
 			}
 
-			$raw_models = $this->fetch_models_from_api( $api_key );
+			$fetcher    = new PRAutoBlogger_Runware_Catalog_Fetcher();
+			$raw_models = $fetcher->fetch_all_text_to_image( $api_key );
+
 			if ( empty( $raw_models ) ) {
 				PRAutoBlogger_Logger::instance()->warning(
 					'Runware model catalog fetch returned empty list. Using cached/fallback models.',
 					'runware-catalog'
 				);
+				$this->record_failure();
 				return false;
 			}
 
-			$normalized = $this->normalize_models( $raw_models );
+			$normalized   = $fetcher->normalize_models( $raw_models );
 			$with_pricing = $this->merge_pricing( $normalized );
 
 			if ( empty( $with_pricing ) ) {
@@ -66,11 +88,13 @@ class PRAutoBlogger_Runware_Model_Catalog {
 					'Runware model catalog normalization resulted in empty list. Using cached/fallback models.',
 					'runware-catalog'
 				);
+				$this->record_failure();
 				return false;
 			}
 
-			update_option( 'prautoblogger_runware_model_cache', $with_pricing, false );
-			update_option( 'prautoblogger_runware_model_cache_updated_at', time(), false );
+			update_option( self::CACHE_OPTION, $with_pricing, false );
+			update_option( self::CACHE_TS_OPTION, time(), false );
+			delete_option( self::FAILURE_TS_OPTION );
 
 			PRAutoBlogger_Logger::instance()->info(
 				sprintf( 'Runware model catalog synced: %d models cached.', count( $with_pricing ) ),
@@ -82,38 +106,37 @@ class PRAutoBlogger_Runware_Model_Catalog {
 				sprintf( 'Runware model catalog sync failed: %s (%s)', $e->getMessage(), get_class( $e ) ),
 				'runware-catalog'
 			);
+			$this->record_failure();
 			return false;
 		}
 	}
 
 	/**
-	 * Get the normalized model list, with smart caching logic:
-	 * - If cache is fresh (< 24h), return it.
-	 * - If cache is stale or absent, trigger a sync.
-	 * - If sync fails, return the last-known-good cache.
-	 * - If no cache exists, return the hardcoded fallback (never empty).
+	 * Return the normalized model list, using smart cache + fallback logic:
+	 * fresh cache → cached; stale + not in cooldown → sync; stale cache fallback;
+	 * no cache → hardcoded fallback (never empty).
 	 *
 	 * @return array<int, array<string, mixed>> Normalized model list.
 	 */
 	public function get_models(): array {
 		if ( ! $this->is_stale() ) {
-			$cached = get_option( 'prautoblogger_runware_model_cache', array() );
+			$cached = get_option( self::CACHE_OPTION, array() );
 			if ( is_array( $cached ) && ! empty( $cached ) ) {
 				return $cached;
 			}
 		}
 
-		if ( $this->sync() ) {
-			$cached = get_option( 'prautoblogger_runware_model_cache', array() );
+		if ( ! $this->is_in_failure_cooldown() && $this->sync() ) {
+			$cached = get_option( self::CACHE_OPTION, array() );
 			if ( is_array( $cached ) && ! empty( $cached ) ) {
 				return $cached;
 			}
 		}
 
-		$cached = get_option( 'prautoblogger_runware_model_cache', array() );
+		$cached = get_option( self::CACHE_OPTION, array() );
 		if ( is_array( $cached ) && ! empty( $cached ) ) {
 			PRAutoBlogger_Logger::instance()->info(
-				'Using stale Runware model cache (live sync failed).',
+				'Using stale Runware model cache (live sync failed or suppressed by cooldown).',
 				'runware-catalog'
 			);
 			return $cached;
@@ -131,12 +154,12 @@ class PRAutoBlogger_Runware_Model_Catalog {
 	}
 
 	/**
-	 * Get the Unix timestamp of the last successful sync, or null if never synced.
+	 * Unix timestamp of the last successful sync, or null if never synced.
 	 *
-	 * @return int|null Unix timestamp, or null if never synced.
+	 * @return int|null
 	 */
 	public function get_last_synced_at(): ?int {
-		$ts = get_option( 'prautoblogger_runware_model_cache_updated_at', null );
+		$ts = get_option( self::CACHE_TS_OPTION, null );
 		if ( null === $ts ) {
 			return null;
 		}
@@ -145,9 +168,23 @@ class PRAutoBlogger_Runware_Model_Catalog {
 	}
 
 	/**
-	 * Check if the cache is stale (older than 24h) or absent.
+	 * Unix timestamp of the last sync failure, or null if no failure on record.
 	 *
-	 * @return bool True if cache should be refreshed; false if still fresh.
+	 * @return int|null
+	 */
+	public function get_last_failure_at(): ?int {
+		$ts = get_option( self::FAILURE_TS_OPTION, null );
+		if ( null === $ts ) {
+			return null;
+		}
+		$ts = (int) $ts;
+		return $ts > 0 ? $ts : null;
+	}
+
+	/**
+	 * Whether the cache is stale (older than 24h) or absent.
+	 *
+	 * @return bool True if a refresh is warranted; false if still fresh.
 	 */
 	public function is_stale(): bool {
 		$updated_at = $this->get_last_synced_at();
@@ -158,125 +195,53 @@ class PRAutoBlogger_Runware_Model_Catalog {
 	}
 
 	/**
-	 * Fetch the raw model list from Runware's /v1 endpoint via a models task.
+	 * Whether a sync attempt should be suppressed due to a recent failure.
 	 *
-	 * @param string $api_key Decrypted Runware API key.
-	 * @return array Raw model list (may be empty).
-	 * @throws \RuntimeException On HTTP error or malformed response.
+	 * The cooldown window is read from prautoblogger_runware_catalog_failure_cooldown_seconds
+	 * (default 3600s). This prevents admin-page-load cascades (40+ errors/day)
+	 * when the API endpoint or key is broken. A successful sync clears it.
+	 *
+	 * @return bool True if a sync should be suppressed; false if retry is permitted.
 	 */
-	private function fetch_models_from_api( string $api_key ): array {
-		$body = wp_json_encode(
-			array(
-				array(
-					'taskType' => 'models',
-					'apiKey'   => $api_key,
-				),
-			)
-		);
-
-		$response = wp_remote_post(
-			self::RUNWARE_API_URL,
-			array(
-				'timeout' => self::HTTP_TIMEOUT_SECONDS,
-				'headers' => array( 'Content-Type' => 'application/json' ),
-				'body'    => $body,
-			)
-		);
-
-		if ( is_wp_error( $response ) ) {
-			throw new \RuntimeException(
-				sprintf( 'Runware models endpoint unreachable: %s', $response->get_error_message() )
-			);
+	public function is_in_failure_cooldown(): bool {
+		$last_failure = $this->get_last_failure_at();
+		if ( null === $last_failure ) {
+			return false;
 		}
-
-		$status = (int) wp_remote_retrieve_response_code( $response );
-		if ( 200 !== $status ) {
-			$raw = wp_remote_retrieve_body( $response );
-			throw new \RuntimeException(
-				sprintf( 'Runware models endpoint returned HTTP %d', $status )
-			);
+		$cooldown = (int) get_option( self::COOLDOWN_SETTING, self::COOLDOWN_DEFAULT );
+		if ( $cooldown <= 0 ) {
+			$cooldown = self::COOLDOWN_DEFAULT;
 		}
-
-		$raw = (string) wp_remote_retrieve_body( $response );
-		$decoded = json_decode( $raw, true );
-
-		if ( ! is_array( $decoded ) ) {
-			throw new \RuntimeException( 'Runware models response is not valid JSON.' );
-		}
-
-		if ( isset( $decoded['errors'] ) && is_array( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
-			throw new \RuntimeException( 'Runware API returned an error.' );
-		}
-
-		$data = $decoded['data'] ?? array();
-		return is_array( $data ) ? $data : array();
+		return ( time() - $last_failure ) < $cooldown;
 	}
 
 	/**
-	 * Normalize raw Runware model objects to the PRAutoBlogger_Image_Model_Registry
-	 * shape: id, name, provider, cost_per_image, capabilities, description.
-	 *
-	 * Filters to taskType='imageInference' (text-to-image only), excluding
-	 * inpainting (imageInference + requiresImage=true), img2img, video, upscalers.
-	 *
-	 * @param array<int, array<string, mixed>> $raw_models Raw API response.
-	 * @return array<int, array<string, mixed>> Normalized models.
-	 */
-	private function normalize_models( array $raw_models ): array {
-		$normalized = array();
-
-		foreach ( $raw_models as $raw ) {
-			if ( ! is_array( $raw ) ) {
-				continue;
-			}
-
-			$task_type = $raw['taskType'] ?? '';
-			if ( 'imageInference' !== $task_type ) {
-				continue;
-			}
-
-			if ( isset( $raw['requiresImage'] ) && true === $raw['requiresImage'] ) {
-				continue;
-			}
-
-			$model_id = (string) ( $raw['id'] ?? '' );
-			if ( '' === $model_id ) {
-				continue;
-			}
-
-			$normalized[] = array(
-				'id'             => $model_id,
-				'name'           => (string) ( $raw['name'] ?? $model_id ),
-				'provider'       => 'runware',
-				'cost_per_image' => null,
-				'capabilities'   => array( 'image_generation' ),
-				'description'    => (string) ( $raw['description'] ?? '' ),
-			);
-		}
-
-		return $normalized;
-	}
-
-	/**
-	 * Merge pricing data from PRAutoBlogger_Runware_Image_Pricing into the
-	 * normalized catalog. Models without pricing data get cost_per_image=null.
+	 * Merge pricing from PRAutoBlogger_Runware_Image_Pricing into normalized models.
+	 * Models without a pricing entry get cost_per_image=null.
 	 *
 	 * @param array<int, array<string, mixed>> $normalized Normalized models.
 	 * @return array<int, array<string, mixed>> Models with pricing merged.
 	 */
 	private function merge_pricing( array $normalized ): array {
 		$pricing_table = PRAutoBlogger_Runware_Image_Pricing::get_model_costs();
-
 		foreach ( $normalized as &$model ) {
 			$model_id = $model['id'] ?? '';
 			if ( isset( $pricing_table[ $model_id ] ) ) {
 				$model['cost_per_image'] = (float) $pricing_table[ $model_id ];
 			}
 		}
-
 		return $normalized;
 	}
 
+	/**
+	 * Record the current time as the last sync failure timestamp.
+	 *
+	 * @return void
+	 */
+	private function record_failure(): void {
+		update_option( self::FAILURE_TS_OPTION, time(), false );
+	}
+
 	/**
 	 * Get the decrypted Runware API key from settings.
 	 *
@@ -287,12 +252,10 @@ class PRAutoBlogger_Runware_Model_Catalog {
 		if ( '' === $stored ) {
 			return '';
 		}
-
 		if ( PRAutoBlogger_Encryption::is_encrypted( $stored ) ) {
 			$decrypted = PRAutoBlogger_Encryption::decrypt( $stored );
 			return '' === $decrypted ? '' : $decrypted;
 		}
-
 		return $stored;
 	}
 }

includes/services/opik/class-opik-eval-scorer.php

@@ -82,6 +82,7 @@ class PRAutoBlogger_Opik_Eval_Scorer {
 				array(
 					'temperature' => 0.1,
 					'max_tokens'  => 200,
+					'stage'       => 'opik_eval_judge',
 				)
 			);
 

prautoblogger.php

@@ -9,7 +9,7 @@
  * Plugin Name:       PRAutoBlogger
  * Plugin URI:        https://peptiderepo.com/prautoblogger
  * Description:       Monitors social media for trending topics, generates SEO-friendly blog posts using AI, and publishes them on a daily schedule with full cost tracking and self-improvement metrics.
- * Version:           0.18.0
+ * Version:           0.18.3
  * Requires at least: 6.0
  * Requires PHP:      7.4
  * Author:            PeptideRepo
@@ -35,13 +35,18 @@ if ( ! defined( 'ABSPATH' ) ) {
 | Defined here so every file in the plugin can reference paths, versions,
 | and limits without magic strings.
 */
-define( 'PRAUTOBLOGGER_VERSION', '0.18.0' );
+define( 'PRAUTOBLOGGER_VERSION', '0.18.3' );
 define( 'PRAUTOBLOGGER_DB_VERSION', '1.2.0' );
 define( 'PRAUTOBLOGGER_PLUGIN_FILE', __FILE__ );
 define( 'PRAUTOBLOGGER_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
 define( 'PRAUTOBLOGGER_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
 define( 'PRAUTOBLOGGER_PLUGIN_BASENAME', plugin_basename( __FILE__ ) );
 // API and retry limits — named constants instead of magic numbers.
+// SAFETY INVARIANT: API_TIMEOUT_SECONDS × MAX_RETRIES must stay < STATUS_TTL (600s,
+// defined in PRAutoBlogger_Generation_Status_Poller). The current product
+// (180s × 3 = 540s) leaves a 60s margin. If either constant is raised, verify the
+// inequality still holds — otherwise a fully-retrying LLM call can exhaust the
+// status transient TTL within a single stage and trigger a false orphan-run abort.
 define( 'PRAUTOBLOGGER_MAX_RETRIES', 3 );
 // Pipeline v2 Phase 1 (v0.18.0) defaults. Both are SETTINGS-backed at every
 // read site (prautoblogger_per_run_cost_ceiling_usd /
@@ -49,6 +54,12 @@ define( 'PRAUTOBLOGGER_MAX_RETRIES', 3 );
 // the named get_option() fallbacks — never inline the literals.
 define( 'PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD', 0.50 );
 define( 'PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS', 14 );
+// v0.18.1: ceiling on "thinking" tokens per reasoning-enabled LLM call. The
+// request's completion budget (max_tokens) is RAISED by this amount so
+// reasoning can never consume the visible-content budget and return an empty
+// message (the 2026-06-11 empty-draft incident). SETTINGS-backed
+// (prautoblogger_reasoning_max_tokens); 0 disables the cap (pure effort mode).
+define( 'PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS', 2048 );
 define( 'PRAUTOBLOGGER_RETRY_BASE_DELAY_SECONDS', 2 );
 define( 'PRAUTOBLOGGER_API_TIMEOUT_SECONDS', 180 );
 define( 'PRAUTOBLOGGER_CACHE_TTL_SECONDS', 3600 );

tests/bootstrap.php

@@ -28,6 +28,9 @@ if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD' ) ) {
 if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS' ) ) {
     define( 'PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS', 14 );
 }
+if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS' ) ) {
+    define( 'PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS', 2048 );
+}
 
 // WordPress time constants used by CostTracker and ContentAnalyzer.
 if ( ! defined( 'DAY_IN_SECONDS' ) ) {

tests/fixtures/runware-model-search-page1.json

@@ -0,0 +1,131 @@
+{
+  "data": [
+    {
+      "taskType": "modelSearch",
+      "taskUUID": "aabbccdd-0000-0000-0000-000000000001",
+      "totalResults": 5,
+      "results": [
+        {
+          "air": "runware:100@1",
+          "name": "FLUX.1 schnell",
+          "nameContent": "FLUX.1 schnell",
+          "comment": "Fast 4-step text-to-image model",
+          "category": "checkpoint",
+          "private": false,
+          "capabilities": ["io:text-to-image", "form:checkpoint"],
+          "tags": [],
+          "heroImage": "",
+          "version": "",
+          "architecture": "",
+          "nsfwLevel": null,
+          "downloadCount": 0,
+          "inferenceCount24h": 0,
+          "rating": 0,
+          "ratingCount": 0,
+          "thumbsUpCount": 0,
+          "thumbsDownCount": 0,
+          "featured": 1,
+          "addedUnixTimestamp": 0,
+          "updatedDateUnixTimestamp": 0,
+          "source": "curated"
+        },
+        {
+          "air": "runware:101@1",
+          "name": "FLUX.1 dev",
+          "nameContent": "FLUX.1 dev",
+          "comment": "High fidelity 28-step text-to-image model",
+          "category": "checkpoint",
+          "private": false,
+          "capabilities": ["io:text-to-image", "form:checkpoint"],
+          "tags": [],
+          "heroImage": "",
+          "version": "",
+          "architecture": "",
+          "nsfwLevel": null,
+          "downloadCount": 0,
+          "inferenceCount24h": 0,
+          "rating": 0,
+          "ratingCount": 0,
+          "thumbsUpCount": 0,
+          "thumbsDownCount": 0,
+          "featured": 0,
+          "addedUnixTimestamp": 0,
+          "updatedDateUnixTimestamp": 0,
+          "source": "curated"
+        },
+        {
+          "air": "some-text-model:llm@1",
+          "name": "Some Text LLM",
+          "nameContent": "Some Text LLM",
+          "comment": "A text-to-text model that should be excluded",
+          "category": "text",
+          "private": false,
+          "capabilities": ["io:text-to-text", "form:checkpoint"],
+          "tags": [],
+          "heroImage": "",
+          "version": "",
+          "architecture": "",
+          "nsfwLevel": null,
+          "downloadCount": 0,
+          "inferenceCount24h": 0,
+          "rating": 0,
+          "ratingCount": 0,
+          "thumbsUpCount": 0,
+          "thumbsDownCount": 0,
+          "featured": 0,
+          "addedUnixTimestamp": 0,
+          "updatedDateUnixTimestamp": 0,
+          "source": "curated"
+        },
+        {
+          "air": "runware:400@2",
+          "name": "FLUX.2 klein 9B",
+          "nameContent": "FLUX.2 klein 9B",
+          "comment": "Compact 9B text-to-image model",
+          "category": "checkpoint",
+          "private": false,
+          "capabilities": ["io:text-to-image", "form:checkpoint"],
+          "tags": [],
+          "heroImage": "",
+          "version": "",
+          "architecture": "",
+          "nsfwLevel": null,
+          "downloadCount": 0,
+          "inferenceCount24h": 0,
+          "rating": 0,
+          "ratingCount": 0,
+          "thumbsUpCount": 0,
+          "thumbsDownCount": 0,
+          "featured": 0,
+          "addedUnixTimestamp": 0,
+          "updatedDateUnixTimestamp": 0,
+          "source": "curated"
+        },
+        {
+          "air": "upscale-model:upscaler@1",
+          "name": "Upscale Model",
+          "nameContent": "Upscale Model",
+          "comment": "Image upscaler — should be excluded from t2i list",
+          "category": "checkpoint",
+          "private": false,
+          "capabilities": ["io:image-to-image", "op:upscale", "form:checkpoint"],
+          "tags": [],
+          "heroImage": "",
+          "version": "",
+          "architecture": "",
+          "nsfwLevel": null,
+          "downloadCount": 0,
+          "inferenceCount24h": 0,
+          "rating": 0,
+          "ratingCount": 0,
+          "thumbsUpCount": 0,
+          "thumbsDownCount": 0,
+          "featured": 0,
+          "addedUnixTimestamp": 0,
+          "updatedDateUnixTimestamp": 0,
+          "source": "curated"
+        }
+      ]
+    }
+  ]
+}

tests/unit/Core/AnalysisPromptsTest.php

@@ -0,0 +1,126 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Analysis_Prompts.
+ *
+ * Regression + behavioral coverage for the GA4 self-improvement loop:
+ * - SQL passed to $wpdb->get_results() must not embed phpcs:ignore comments
+ *   (MariaDB rejects the query if it does).
+ * - get_performance_context() returns a non-empty, correctly-shaped string
+ *   when seeded content_scores rows are present.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class AnalysisPromptsTest extends BaseTestCase {
+
+	/** @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb. */
+	private $wpdb;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->wpdb         = $this->create_mock_wpdb();
+		// Analysis prompts uses $wpdb->posts (JOIN {->posts}) and prefix.
+		$this->wpdb->posts  = 'wp_posts';
+		$GLOBALS['wpdb']    = $this->wpdb;
+	}
+
+	protected function tearDown(): void {
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/**
+	 * Regression: get_performance_context() SQL must not embed phpcs:ignore
+	 * inside the string literal — MariaDB rejects the query if it does,
+	 * causing get_performance_context() to silently return '' on every run.
+	 *
+	 * @see includes/core/class-analysis-prompts.php — fixed in v0.18.3
+	 */
+	public function test_get_performance_context_sql_has_no_inline_phpcs_ignore(): void {
+		$captured_sql = null;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			function ( $sql ) use ( &$captured_sql ) {
+				// get_results is called WITHOUT prepare (direct string interpolation
+				// of a table prefix); capture the first arg to get_results instead.
+				return $sql;
+			}
+		);
+		$this->wpdb->method( 'get_results' )->willReturnCallback(
+			function ( $sql ) use ( &$captured_sql ) {
+				$captured_sql = $sql;
+				return array();
+			}
+		);
+
+		\PRAutoBlogger_Analysis_Prompts::get_performance_context();
+
+		$this->assertNotNull( $captured_sql, 'get_results() was not called' );
+		$this->assertStringNotContainsString(
+			'// phpcs:ignore',
+			(string) $captured_sql,
+			'SQL passed to get_results() must not contain a phpcs:ignore comment — MariaDB rejects it as a syntax error'
+		);
+	}
+
+	/**
+	 * Behavioral: get_performance_context() returns a non-empty, correctly-shaped
+	 * string when the scores table contains rows with composite_score > 0.
+	 *
+	 * The returned string must:
+	 *   - start with the "Top performing" header line
+	 *   - contain at least one bullet entry of the form '- "…" (score: N.N)'
+	 *   - not be empty
+	 */
+	public function test_get_performance_context_returns_shaped_context_with_seeded_rows(): void {
+		// Simulate two content_scores rows returned from the DB query.
+		$rows = array(
+			array(
+				'post_id'         => 100,
+				'composite_score' => '9.2',
+				'post_title'      => 'BPC-157 and Gut Healing — What the Research Shows',
+			),
+			array(
+				'post_id'         => 101,
+				'composite_score' => '7.8',
+				'post_title'      => 'Semaglutide Dosing Guide for Weight Loss',
+			),
+		);
+
+		$this->wpdb->method( 'get_results' )->willReturn( $rows );
+
+		$context = \PRAutoBlogger_Analysis_Prompts::get_performance_context();
+
+		$this->assertNotEmpty( $context, 'get_performance_context() returned empty string with seeded rows' );
+		$this->assertStringContainsString(
+			'Top performing past articles',
+			$context,
+			'Context block must start with the header line'
+		);
+		$this->assertStringContainsString(
+			'BPC-157 and Gut Healing',
+			$context,
+			'Context block must contain the first seeded article title'
+		);
+		$this->assertStringContainsString(
+			'score: 9.2',
+			$context,
+			'Context block must include formatted composite_score'
+		);
+	}
+
+	/**
+	 * Edge case: get_performance_context() returns '' when no rows exist.
+	 */
+	public function test_get_performance_context_returns_empty_string_when_no_rows(): void {
+		$this->wpdb->method( 'get_results' )->willReturn( array() );
+
+		$context = \PRAutoBlogger_Analysis_Prompts::get_performance_context();
+
+		$this->assertSame( '', $context, 'get_performance_context() must return empty string when scores table is empty' );
+	}
+}

tests/unit/Core/ContentGeneratorTest.php

@@ -0,0 +1,164 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Content_Generator (v0.18.1 writer-path guard).
+ *
+ * Validates that a writing stage whose LLM output is empty/whitespace
+ * throws instead of passing an empty article downstream, that healthy
+ * output passes through, and that the stage metadata for the provider's
+ * empty-completion guard rides the options array.
+ *
+ * execute_stage() is exercised via reflection: generate() defines the
+ * PRAUTOBLOGGER_EVAL_MODE constant, which cannot be redefined across
+ * tests in one PHP process.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class ContentGeneratorTest extends BaseTestCase {
+
+    private \PRAutoBlogger_Content_Request $request;
+
+    protected function setUp(): void {
+        parent::setUp();
+
+        \PRAutoBlogger_Prompt_Registry::flush_cache();
+
+        $this->stub_get_option( [
+            'prautoblogger_log_level' => 'error',
+        ] );
+
+        // Content_Prompts::build_system() lists recent posts for the
+        // linking rules — none exist in the unit environment.
+        Functions\when( 'get_posts' )->justReturn( [] );
+
+        $idea = new \PRAutoBlogger_Article_Idea( $this->get_article_idea_fixture() );
+
+        $this->request = new \PRAutoBlogger_Content_Request(
+            $idea,
+            'single_pass',
+            'informational',
+            800,
+            2000,
+            '',
+            [],
+            ''
+        );
+    }
+
+    protected function tearDown(): void {
+        \PRAutoBlogger_Prompt_Registry::flush_cache();
+        parent::tearDown();
+    }
+
+    /**
+     * Invoke the private execute_stage() on a generator wired to the
+     * given LLM response.
+     *
+     * @param array $llm_response   Response the mock provider returns.
+     * @param array|null $captured  Receives the options passed to the LLM.
+     * @return string Stage output.
+     */
+    private function run_stage( array $llm_response, ?array &$captured = null ): string {
+        $llm = $this->createMock( \PRAutoBlogger_LLM_Provider_Interface::class );
+        $llm->method( 'send_chat_completion' )->willReturnCallback(
+            function ( array $messages, string $model, array $options ) use ( $llm_response, &$captured ) {
+                $captured = $options;
+                return $llm_response;
+            }
+        );
+        $llm->method( 'get_provider_name' )->willReturn( 'OpenRouter' );
+        $llm->method( 'estimate_cost' )->willReturn( 0.001 );
+
+        $cost_tracker = $this->createMock( \PRAutoBlogger_Cost_Tracker::class );
+
+        $generator = new \PRAutoBlogger_Content_Generator( $llm, $cost_tracker );
+
+        $method = new \ReflectionMethod( \PRAutoBlogger_Content_Generator::class, 'execute_stage' );
+        $method->setAccessible( true );
+
+        return $method->invoke(
+            $generator,
+            'draft',
+            'draft_generation',
+            'Write the article.',
+            $this->request,
+            'model/test',
+            [
+                'temperature' => 0.7,
+                'max_tokens'  => 4000,
+            ],
+            'content.single_pass'
+        );
+    }
+
+    /**
+     * Healthy stage output passes through unchanged.
+     */
+    public function test_non_empty_stage_output_passes_through(): void {
+        $output = $this->run_stage( [
+            'content'           => '<p>A real article.</p>',
+            'model'             => 'model/test',
+            'prompt_tokens'     => 100,
+            'completion_tokens' => 200,
+        ] );
+
+        $this->assertSame( '<p>A real article.</p>', $output );
+    }
+
+    /**
+     * Empty stage output throws — no empty article may leave the writer.
+     */
+    public function test_empty_stage_output_throws(): void {
+        $this->expectException( \RuntimeException::class );
+        $this->expectExceptionMessage( 'produced empty content' );
+
+        $this->run_stage( [
+            'content'           => '',
+            'model'             => 'model/test',
+            'prompt_tokens'     => 100,
+            'completion_tokens' => 4000,
+        ] );
+    }
+
+    /**
+     * Whitespace-only output counts as empty (the guard trims).
+     */
+    public function test_whitespace_stage_output_throws(): void {
+        $this->expectException( \RuntimeException::class );
+        $this->expectExceptionMessage( 'draft' );
+
+        $this->run_stage( [
+            'content'           => "  \n\t  ",
+            'model'             => 'model/test',
+            'prompt_tokens'     => 100,
+            'completion_tokens' => 4000,
+        ] );
+    }
+
+    /**
+     * The stage + prompt_key metadata for the provider's empty-completion
+     * guard rides the LLM options (v0.18.1).
+     */
+    public function test_stage_metadata_rides_the_llm_options(): void {
+        $captured = null;
+
+        $this->run_stage(
+            [
+                'content'           => 'ok',
+                'model'             => 'model/test',
+                'prompt_tokens'     => 1,
+                'completion_tokens' => 1,
+            ],
+            $captured
+        );
+
+        $this->assertSame( 'draft', $captured['stage'] );
+        $this->assertSame( 'content.single_pass', $captured['prompt_key'] );
+        $this->assertSame( 4000, $captured['max_tokens'] );
+    }
+}

tests/unit/Core/CostReporterTest.php

@@ -90,4 +90,60 @@ class CostReporterTest extends BaseTestCase {
         $this->assertIsFloat( $utilization );
         $this->assertGreaterThanOrEqual( 0.0, $utilization );
     }
+
+    /**
+     * Regression: get_daily_spend SQL must not embed phpcs:ignore inside the
+     * string literal (MariaDB would receive the comment as literal SQL text and
+     * reject the query). Captures the first argument passed to prepare() and
+     * asserts the SQL is clean.
+     *
+     * @see includes/core/class-cost-reporter.php — fixed in v0.18.2
+     */
+    public function test_get_daily_spend_sql_contains_no_inline_phpcs_ignore(): void {
+        $captured_sql = null;
+        $this->wpdb->method( 'prepare' )->willReturnCallback(
+            function ( $sql, ...$args ) use ( &$captured_sql ) {
+                $captured_sql = $sql;
+                return 'prepared';
+            }
+        );
+        $this->wpdb->method( 'get_results' )->willReturn( [] );
+
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $reporter->get_daily_spend( 7 );
+
+        $this->assertNotNull( $captured_sql, 'prepare() was not called' );
+        $this->assertStringNotContainsString(
+            '// phpcs:ignore',
+            (string) $captured_sql,
+            'SQL string must not contain phpcs:ignore comment — MariaDB rejects it'
+        );
+    }
+
+    /**
+     * Regression: get_spend_by_stage SQL must not embed phpcs:ignore inside
+     * the string literal.
+     *
+     * @see includes/core/class-cost-reporter.php — fixed in v0.18.2
+     */
+    public function test_get_spend_by_stage_sql_contains_no_inline_phpcs_ignore(): void {
+        $captured_sql = null;
+        $this->wpdb->method( 'prepare' )->willReturnCallback(
+            function ( $sql, ...$args ) use ( &$captured_sql ) {
+                $captured_sql = $sql;
+                return 'prepared';
+            }
+        );
+        $this->wpdb->method( 'get_results' )->willReturn( [] );
+
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $reporter->get_spend_by_stage( '2026-06-01', '2026-06-30' );
+
+        $this->assertNotNull( $captured_sql, 'prepare() was not called' );
+        $this->assertStringNotContainsString(
+            '// phpcs:ignore',
+            (string) $captured_sql,
+            'SQL string must not contain phpcs:ignore comment — MariaDB rejects it'
+        );
+    }
 }

tests/unit/Core/GenerationStatusPollerTest.php

@@ -0,0 +1,226 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Generation_Status_Poller (R2/R3 resilience).
+ *
+ * Covers:
+ *  - R2(a): update_generation_stage() renews the transient TTL on every call.
+ *  - R2(b): on_ajax_generation_status() detects lock-held-but-transient-gone
+ *    when lock age > STATUS_TTL and returns status:error with an infrastructure
+ *    timeout message.
+ *  - R3: on_ajax_generation_status() returns status:running (with started_at)
+ *    when the transient is absent but the lock is held within TTL.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class GenerationStatusPollerTest extends BaseTestCase {
+
+	/** @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb. */
+	private $wpdb;
+
+	/** @var array Captured wp_send_json_success payloads. */
+	private array $json_success = array();
+
+	/** @var array Captured wp_send_json_error payloads. */
+	private array $json_error = array();
+
+	/** @var array Captured transient writes: [key, value, ttl]. */
+	private array $transient_writes = array();
+
+	/** @var mixed Current transient value. */
+	private $transient_value = false;
+
+	/** @var int|null Mocked lock acquired_at timestamp (null = not held). */
+	private ?int $lock_acquired_at = null;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->json_success     = array();
+		$this->json_error       = array();
+		$this->transient_writes = array();
+		$this->transient_value  = false;
+		$this->lock_acquired_at = null;
+
+		$this->wpdb          = $this->create_mock_wpdb();
+		// Generation_Lock uses $wpdb->options in acquire/release/get_acquired_at.
+		$this->wpdb->options = 'wp_options';
+		$GLOBALS['wpdb']     = $this->wpdb;
+
+		// Stub nonce check and capability check (always pass in unit tests).
+		Functions\when( 'check_ajax_referer' )->justReturn( true );
+		Functions\when( 'current_user_can' )->justReturn( true );
+
+		// Transient stubs.
+		Functions\when( 'get_transient' )->alias( function( $key ) {
+			return $this->transient_value;
+		} );
+		Functions\when( 'set_transient' )->alias( function( $key, $value, $ttl ) {
+			$this->transient_writes[] = array( $key, $value, $ttl );
+			return true;
+		} );
+
+		// wp_send_json stubs — capture payload, mark test as "sent".
+		Functions\when( 'wp_send_json_success' )->alias( function( $data ) {
+			$this->json_success[] = $data;
+		} );
+		Functions\when( 'wp_send_json_error' )->alias( function( $data ) {
+			$this->json_error[] = $data;
+		} );
+
+		// Generation_Lock::get_acquired_at() — return our test value.
+		// We stub the static method via $wpdb since it does a DB query.
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			function ( $sql, ...$args ) {
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			function ( $sql ) {
+				// Return the lock timestamp when querying the lock option.
+				if ( false !== strpos( (string) $sql, 'prautoblogger_generation_lock' ) ) {
+					return null !== $this->lock_acquired_at ? (string) $this->lock_acquired_at : null;
+				}
+				return null;
+			}
+		);
+
+		// Run_State and Run_Context stubs — no DB tables in unit tests.
+		\PRAutoBlogger_Run_State::flush_cache();
+		Functions\when( 'get_option' )->justReturn( false );
+		Functions\when( 'delete_option' )->justReturn( true );
+		Functions\when( 'delete_transient' )->justReturn( true );
+
+		// Logger stub.
+		Functions\when( 'wp_date' )->returnArg();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	// -------------------------------------------------------------------------
+	// R2(a): update_generation_stage() renews transient TTL
+	// -------------------------------------------------------------------------
+
+	/**
+	 * update_generation_stage() must renew the transient with STATUS_TTL on
+	 * every call so the transient outlasts a long LLM call.
+	 */
+	public function test_update_generation_stage_renews_transient_ttl(): void {
+		// Seed an existing running transient.
+		$this->transient_value = array(
+			'status'       => 'running',
+			'stage'        => 'old stage',
+			'started'      => time() - 30,
+			'last_updated' => time() - 30,
+		);
+
+		$poller = new \PRAutoBlogger_Generation_Status_Poller();
+		$poller->update_generation_stage( 'Analyzing sources...' );
+
+		$this->assertCount( 1, $this->transient_writes, 'set_transient must be called once' );
+		[ $key, $value, $ttl ] = $this->transient_writes[0];
+		$this->assertSame( \PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT, $key );
+		$this->assertSame( \PRAutoBlogger_Generation_Status_Poller::STATUS_TTL, $ttl,
+			'TTL must be renewed to STATUS_TTL on every stage update' );
+		$this->assertSame( 'Analyzing sources...', $value['stage'] );
+	}
+
+	/**
+	 * update_generation_stage() is a no-op when the transient is absent
+	 * (prevents spurious "running" writes after a run has completed).
+	 */
+	public function test_update_generation_stage_no_op_when_transient_absent(): void {
+		$this->transient_value = false; // absent.
+
+		$poller = new \PRAutoBlogger_Generation_Status_Poller();
+		$poller->update_generation_stage( 'Stage text' );
+
+		$this->assertEmpty( $this->transient_writes, 'set_transient must NOT be called when transient is absent' );
+	}
+
+	// -------------------------------------------------------------------------
+	// R3: transient absent, lock held within TTL → return status:running
+	// -------------------------------------------------------------------------
+
+	/**
+	 * R3: When the status transient has expired but the lock is held within
+	 * STATUS_TTL, the poller must return status:running so the Generate Now
+	 * button does not silently reset to idle during long background runs.
+	 */
+	public function test_missing_transient_but_fresh_lock_returns_running(): void {
+		$this->transient_value  = false;           // transient gone.
+		$this->lock_acquired_at = time() - 60;     // lock held 60s — well within TTL.
+
+		// Stub _POST for the nonce.
+		$_POST = array( 'nonce' => 'fake' );
+		$poller = new \PRAutoBlogger_Generation_Status_Poller();
+		$poller->on_ajax_generation_status();
+
+		$this->assertCount( 1, $this->json_success, 'wp_send_json_success must be called once' );
+		$response = $this->json_success[0];
+		$this->assertSame( 'running', $response['status'],
+			'R3: status must be running when transient absent but lock held within TTL' );
+		$this->assertArrayHasKey( 'started', $response,
+			'R3: response must include started timestamp from lock' );
+		$this->assertSame( $this->lock_acquired_at, $response['started'],
+			'R3: started must equal the lock acquired_at timestamp' );
+	}
+
+	// -------------------------------------------------------------------------
+	// R2(b): transient absent, lock held > STATUS_TTL → abort + status:error
+	// -------------------------------------------------------------------------
+
+	/**
+	 * R2(b): When the status transient is absent and the lock has been held
+	 * longer than STATUS_TTL, the poller must mark the run failed and return
+	 * status:error with an "infrastructure timeout" message.
+	 */
+	public function test_missing_transient_with_expired_lock_marks_failed_and_returns_error(): void {
+		$this->transient_value  = false;
+		$ttl                    = \PRAutoBlogger_Generation_Status_Poller::STATUS_TTL;
+		$this->lock_acquired_at = time() - ( $ttl + 60 ); // Lock held TTL+60s.
+
+		$_POST = array( 'nonce' => 'fake' );
+		$poller = new \PRAutoBlogger_Generation_Status_Poller();
+		$poller->on_ajax_generation_status();
+
+		$this->assertCount( 1, $this->json_success, 'wp_send_json_success must be called' );
+		$response = $this->json_success[0];
+		$this->assertSame( 'error', $response['status'],
+			'R2(b): status must be error when lock is expired-stale' );
+		$this->assertStringContainsString(
+			'infrastructure timeout',
+			strtolower( $response['message'] ?? '' ),
+			'R2(b): error message must mention infrastructure timeout'
+		);
+	}
+
+	// -------------------------------------------------------------------------
+	// Idle path: no transient, no lock
+	// -------------------------------------------------------------------------
+
+	/**
+	 * When both the transient and the lock are absent, the poller must
+	 * return status:idle (normal rest state between runs).
+	 */
+	public function test_no_transient_no_lock_returns_idle(): void {
+		$this->transient_value  = false;
+		$this->lock_acquired_at = null; // no lock.
+
+		$_POST = array( 'nonce' => 'fake' );
+		$poller = new \PRAutoBlogger_Generation_Status_Poller();
+		$poller->on_ajax_generation_status();
+
+		$this->assertCount( 1, $this->json_success );
+		$this->assertSame( 'idle', $this->json_success[0]['status'] );
+	}
+}

tests/unit/Core/PublisherSideEffectsTest.php

@@ -0,0 +1,183 @@
+<?php
+/**
+ * Side-effect tests for PRAutoBlogger_Publisher::publish().
+ *
+ * Validates the post-creation side effects: taxonomy assignment
+ * (category from article_type, tags from keywords), generation-log
+ * linking by run_id, and the public action/filter hooks. Split from
+ * PublisherTest.php to keep both files under the 300-line rule;
+ * post-creation/status/metadata/guard tests stay in PublisherTest.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+use Brain\Monkey\Actions;
+use Brain\Monkey\Filters;
+
+class PublisherSideEffectsTest extends BaseTestCase {
+
+    private \PRAutoBlogger_Article_Idea $idea;
+    private \PRAutoBlogger_Editorial_Review $review;
+
+    protected function setUp(): void {
+        parent::setUp();
+
+        $this->idea   = new \PRAutoBlogger_Article_Idea( $this->get_article_idea_fixture() );
+        $this->review = new \PRAutoBlogger_Editorial_Review( $this->get_editorial_review_fixture() );
+
+        // Common stubs needed by Publisher.
+        $this->stub_get_option( [
+            'prautoblogger_writing_pipeline'  => 'multi_step',
+            'prautoblogger_writing_model'     => 'anthropic/claude-sonnet-4',
+            'prautoblogger_default_author'    => 1,
+        ] );
+
+        Functions\when( 'sanitize_text_field' )->returnArg();
+        Functions\when( 'wp_kses_post' )->returnArg();
+        // v0.18.1 empty-content guard strips tags before the emptiness check.
+        Functions\when( 'wp_strip_all_tags' )->alias( function ( $text ) {
+            return trim( strip_tags( (string) $text ) );
+        } );
+        Functions\when( 'is_wp_error' )->justReturn( false );
+        Functions\when( 'apply_filters' )->returnArg( 2 );
+        Functions\when( 'absint' )->alias( function ( $val ) { return abs( (int) $val ); } );
+        Functions\when( 'get_users' )->justReturn( [ 1 ] );
+        Functions\when( 'get_term_by' )->justReturn( false );
+        Functions\when( 'wp_insert_term' )->justReturn( [ 'term_id' => 5 ] );
+        Functions\when( 'wp_set_post_categories' )->justReturn( true );
+        Functions\when( 'wp_set_post_tags' )->justReturn( true );
+    }
+
+    /**
+     * Test that taxonomy terms are assigned based on article_type from the idea.
+     */
+    public function test_publish_assigns_category_from_article_type(): void {
+        Functions\when( 'wp_insert_post' )->justReturn( 46 );
+
+        // get_term_by returns false (category doesn't exist), so wp_insert_term is called.
+        $captured_category = null;
+        Functions\when( 'wp_insert_term' )->alias( function ( $name, $taxonomy ) use ( &$captured_category ) {
+            $captured_category = $name;
+            return [ 'term_id' => 10 ];
+        } );
+
+        $captured_category_ids = null;
+        Functions\when( 'wp_set_post_categories' )->alias( function ( $post_id, $cat_ids ) use ( &$captured_category_ids ) {
+            $captured_category_ids = $cat_ids;
+            return true;
+        } );
+
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'query' )->willReturn( 0 );
+        $wpdb->method( 'prepare' )->willReturn( '' );
+        $GLOBALS['wpdb'] = $wpdb;
+
+        $publisher = new \PRAutoBlogger_Publisher();
+        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
+
+        // Article type is 'guide' → category should be 'Guides'.
+        $this->assertSame( 'Guides', $captured_category );
+        $this->assertSame( [ 10 ], $captured_category_ids );
+    }
+
+    /**
+     * Test that target keywords are set as post tags.
+     */
+    public function test_publish_sets_tags_from_keywords(): void {
+        Functions\when( 'wp_insert_post' )->justReturn( 47 );
+
+        $captured_tags = null;
+        Functions\when( 'wp_set_post_tags' )->alias( function ( $post_id, $tags, $append ) use ( &$captured_tags ) {
+            $captured_tags = $tags;
+            return true;
+        } );
+
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'query' )->willReturn( 0 );
+        $wpdb->method( 'prepare' )->willReturn( '' );
+        $GLOBALS['wpdb'] = $wpdb;
+
+        $publisher = new \PRAutoBlogger_Publisher();
+        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
+
+        $this->assertSame( [ 'test', 'keyword', 'example' ], $captured_tags );
+    }
+
+    /**
+     * Test that generation log entries are linked via run_id.
+     */
+    public function test_publish_links_generation_logs_by_run_id(): void {
+        Functions\when( 'wp_insert_post' )->justReturn( 48 );
+
+        // Create an idea fixture without source_ids to avoid triggering SourceCollector
+        // queries that would overwrite captured_query in the mock.
+        $fixture = $this->get_article_idea_fixture();
+        $fixture['source_ids'] = [];
+        $idea = new \PRAutoBlogger_Article_Idea( $fixture );
+
+        $captured_query = null;
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'prepare' )->willReturnCallback( function ( $sql, ...$args ) use ( &$captured_query ) {
+            $captured_query = $sql;
+            return $sql;
+        } );
+        $wpdb->method( 'query' )->willReturn( 1 );
+        $GLOBALS['wpdb'] = $wpdb;
+
+        $publisher = new \PRAutoBlogger_Publisher();
+        $publisher->publish( '<p>Content</p>', $idea, $this->review, 'run_link_test' );
+
+        // Should use run_id-based query, not timestamp-based.
+        $this->assertStringContainsString( 'run_id', $captured_query );
+        $this->assertStringNotContainsString( 'created_at', $captured_query );
+    }
+
+    /**
+     * Test that the prautoblogger_post_created action is fired after publishing.
+     */
+    public function test_publish_fires_post_created_action(): void {
+        // TODO(peptiderepo): this test is latently broken — Mockery expects do_action_prautoblogger_post_created
+        // to be called, but Publisher::publish() is not firing it in the current mock setup. Track in a follow-up
+        // PR; skipping for now so CI parity can land. The bug is likely a mis-mocked do_action or a refactor
+        // that removed the action fire.
+        $this->markTestSkipped( 'Latent bug — see TODO; tracked for follow-up PR.' );
+        Functions\when( 'wp_insert_post' )->justReturn( 49 );
+        Functions\when( 'do_action' )->alias( function () {} );
+
+        Actions\expectDone( 'prautoblogger_post_created' )
+            ->once()
+            ->with( 49, 'publish', $this->idea, $this->review );
+
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'query' )->willReturn( 0 );
+        $wpdb->method( 'prepare' )->willReturn( '' );
+        $GLOBALS['wpdb'] = $wpdb;
+
+        $publisher = new \PRAutoBlogger_Publisher();
+        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
+    }
+
+    /**
+     * Test that the prautoblogger_filter_post_data filter is applied.
+     */
+    public function test_publish_applies_post_data_filter(): void {
+        // TODO(peptiderepo): latently broken alongside test_publish_fires_post_created_action.
+        // apply_filters('prautoblogger_post_data', ...) expected but not called. Follow-up PR.
+        $this->markTestSkipped( 'Latent bug — see TODO; tracked for follow-up PR.' );
+        Functions\when( 'wp_insert_post' )->justReturn( 50 );
+
+        Filters\expectApplied( 'prautoblogger_filter_post_data' )->once();
+
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'query' )->willReturn( 0 );
+        $wpdb->method( 'prepare' )->willReturn( '' );
+        $GLOBALS['wpdb'] = $wpdb;
+
+        $publisher = new \PRAutoBlogger_Publisher();
+        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
+    }
+}

tests/unit/Core/PublisherTest.php

@@ -13,8 +13,6 @@ namespace PRAutoBlogger\Tests\Core;
 
 use PRAutoBlogger\Tests\BaseTestCase;
 use Brain\Monkey\Functions;
-use Brain\Monkey\Actions;
-use Brain\Monkey\Filters;
 
 class PublisherTest extends BaseTestCase {
 
@@ -36,6 +34,10 @@ class PublisherTest extends BaseTestCase {
 
         Functions\when( 'sanitize_text_field' )->returnArg();
         Functions\when( 'wp_kses_post' )->returnArg();
+        // v0.18.1 empty-content guard strips tags before the emptiness check.
+        Functions\when( 'wp_strip_all_tags' )->alias( function ( $text ) {
+            return trim( strip_tags( (string) $text ) );
+        } );
         Functions\when( 'is_wp_error' )->justReturn( false );
         Functions\when( 'apply_filters' )->returnArg( 2 );
         Functions\when( 'absint' )->alias( function ( $val ) { return abs( (int) $val ); } );
@@ -168,131 +170,33 @@ class PublisherTest extends BaseTestCase {
     }
 
     /**
-     * Test that taxonomy terms are assigned based on article_type from the idea.
+     * v0.18.1 belt-and-braces: save_as_draft() with empty content throws
+     * and never reaches wp_insert_post — no empty draft post can be
+     * created (the 2026-06-11 post-921 incident shape).
      */
-    public function test_publish_assigns_category_from_article_type(): void {
-        Functions\when( 'wp_insert_post' )->justReturn( 46 );
-
-        // get_term_by returns false (category doesn't exist), so wp_insert_term is called.
-        $captured_category = null;
-        Functions\when( 'wp_insert_term' )->alias( function ( $name, $taxonomy ) use ( &$captured_category ) {
-            $captured_category = $name;
-            return [ 'term_id' => 10 ];
-        } );
-
-        $captured_category_ids = null;
-        Functions\when( 'wp_set_post_categories' )->alias( function ( $post_id, $cat_ids ) use ( &$captured_category_ids ) {
-            $captured_category_ids = $cat_ids;
-            return true;
-        } );
-
-        $wpdb = $this->create_mock_wpdb();
-        $wpdb->method( 'query' )->willReturn( 0 );
-        $wpdb->method( 'prepare' )->willReturn( '' );
-        $GLOBALS['wpdb'] = $wpdb;
+    public function test_save_as_draft_refuses_empty_content(): void {
+        Functions\expect( 'wp_insert_post' )->never();
 
         $publisher = new \PRAutoBlogger_Publisher();
-        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
 
-        // Article type is 'guide' → category should be 'Guides'.
-        $this->assertSame( 'Guides', $captured_category );
-        $this->assertSame( [ 10 ], $captured_category_ids );
+        $this->expectException( \RuntimeException::class );
+        $this->expectExceptionMessage( 'generated content is empty' );
+
+        $publisher->save_as_draft( '', $this->idea, $this->review, 'run_empty_draft' );
     }
 
     /**
-     * Test that target keywords are set as post tags.
+     * v0.18.1 belt-and-braces: publish() refuses content that is empty
+     * once tags and whitespace are stripped (an empty HTML shell).
      */
-    public function test_publish_sets_tags_from_keywords(): void {
-        Functions\when( 'wp_insert_post' )->justReturn( 47 );
-
-        $captured_tags = null;
-        Functions\when( 'wp_set_post_tags' )->alias( function ( $post_id, $tags, $append ) use ( &$captured_tags ) {
-            $captured_tags = $tags;
-            return true;
-        } );
-
-        $wpdb = $this->create_mock_wpdb();
-        $wpdb->method( 'query' )->willReturn( 0 );
-        $wpdb->method( 'prepare' )->willReturn( '' );
-        $GLOBALS['wpdb'] = $wpdb;
+    public function test_publish_refuses_whitespace_only_html_content(): void {
+        Functions\expect( 'wp_insert_post' )->never();
 
         $publisher = new \PRAutoBlogger_Publisher();
-        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
 
-        $this->assertSame( [ 'test', 'keyword', 'example' ], $captured_tags );
-    }
+        $this->expectException( \RuntimeException::class );
+        $this->expectExceptionMessage( 'generated content is empty' );
 
-    /**
-     * Test that generation log entries are linked via run_id.
-     */
-    public function test_publish_links_generation_logs_by_run_id(): void {
-        Functions\when( 'wp_insert_post' )->justReturn( 48 );
-
-        // Create an idea fixture without source_ids to avoid triggering SourceCollector
-        // queries that would overwrite captured_query in the mock.
-        $fixture = $this->get_article_idea_fixture();
-        $fixture['source_ids'] = [];
-        $idea = new \PRAutoBlogger_Article_Idea( $fixture );
-
-        $captured_query = null;
-        $wpdb = $this->create_mock_wpdb();
-        $wpdb->method( 'prepare' )->willReturnCallback( function ( $sql, ...$args ) use ( &$captured_query ) {
-            $captured_query = $sql;
-            return $sql;
-        } );
-        $wpdb->method( 'query' )->willReturn( 1 );
-        $GLOBALS['wpdb'] = $wpdb;
-
-        $publisher = new \PRAutoBlogger_Publisher();
-        $publisher->publish( '<p>Content</p>', $idea, $this->review, 'run_link_test' );
-
-        // Should use run_id-based query, not timestamp-based.
-        $this->assertStringContainsString( 'run_id', $captured_query );
-        $this->assertStringNotContainsString( 'created_at', $captured_query );
-    }
-
-    /**
-     * Test that the prautoblogger_post_created action is fired after publishing.
-     */
-    public function test_publish_fires_post_created_action(): void {
-        // TODO(peptiderepo): this test is latently broken — Mockery expects do_action_prautoblogger_post_created
-        // to be called, but Publisher::publish() is not firing it in the current mock setup. Track in a follow-up
-        // PR; skipping for now so CI parity can land. The bug is likely a mis-mocked do_action or a refactor
-        // that removed the action fire.
-        $this->markTestSkipped( 'Latent bug — see TODO; tracked for follow-up PR.' );
-        Functions\when( 'wp_insert_post' )->justReturn( 49 );
-        Functions\when( 'do_action' )->alias( function () {} );
-
-        Actions\expectDone( 'prautoblogger_post_created' )
-            ->once()
-            ->with( 49, 'publish', $this->idea, $this->review );
-
-        $wpdb = $this->create_mock_wpdb();
-        $wpdb->method( 'query' )->willReturn( 0 );
-        $wpdb->method( 'prepare' )->willReturn( '' );
-        $GLOBALS['wpdb'] = $wpdb;
-
-        $publisher = new \PRAutoBlogger_Publisher();
-        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
-    }
-
-    /**
-     * Test that the prautoblogger_filter_post_data filter is applied.
-     */
-    public function test_publish_applies_post_data_filter(): void {
-        // TODO(peptiderepo): latently broken alongside test_publish_fires_post_created_action.
-        // apply_filters('prautoblogger_post_data', ...) expected but not called. Follow-up PR.
-        $this->markTestSkipped( 'Latent bug — see TODO; tracked for follow-up PR.' );
-        Functions\when( 'wp_insert_post' )->justReturn( 50 );
-
-        Filters\expectApplied( 'prautoblogger_filter_post_data' )->once();
-
-        $wpdb = $this->create_mock_wpdb();
-        $wpdb->method( 'query' )->willReturn( 0 );
-        $wpdb->method( 'prepare' )->willReturn( '' );
-        $GLOBALS['wpdb'] = $wpdb;
-
-        $publisher = new \PRAutoBlogger_Publisher();
-        $publisher->publish( '<p>Content</p>', $this->idea, $this->review );
+        $publisher->publish( "<p> \n\t </p>", $this->idea, $this->review );
     }
 }

tests/unit/Core/RunStageStateTest.php

@@ -137,4 +137,76 @@ class RunStageStateTest extends BaseTestCase {
 		$this->assertFalse( \PRAutoBlogger_Run_Stage_State::is_done( 'run-1', 'draft' ) );
 		$this->assertNull( \PRAutoBlogger_Run_Stage_State::get_output( 'run-1', 'draft' ) );
 	}
+
+	/**
+	 * start(role) → done(role) → is_done(role) must be true; is_done('') must
+	 * be false — this catches the v0.18.2 regression where done() passed ''
+	 * while start() passed a real role, so done() addressed a different row.
+	 *
+	 * In this test the wpdb mock records inserts via query() and simulates
+	 * the SELECT via get_row():
+	 *   is_done('review','editor') → get_row finds the done row → true.
+	 *   is_done('review','')      → resolve_role→'editor'; primary: miss;
+	 *                               legacy fallback (role=''): miss → false.
+	 */
+	public function test_role_tagged_start_and_done_are_symmetric(): void {
+		$get_row_results = array(
+			array( 'status' => 'done', 'meta_json' => null ), // primary hit for 'editor'.
+			null,   // primary miss for legacy check (role='editor' resolved, not '').
+			null,   // legacy fallback (role='') also not found.
+		);
+		$call_index      = 0;
+		$this->wpdb->method( 'get_var' )->willReturn( 'wp_prautoblogger_run_stages' );
+		$this->wpdb->method( 'query' )->willReturn( 1 );
+		$this->wpdb->method( 'get_row' )->willReturnCallback(
+			static function () use ( &$get_row_results, &$call_index ) {
+				$result = $get_row_results[ $call_index ] ?? null;
+				++$call_index;
+				return $result;
+			}
+		);
+
+		\PRAutoBlogger_Run_Stage_State::start( 'run-2', 'review', 'editor', 'idea:xyz' );
+		\PRAutoBlogger_Run_Stage_State::done( 'run-2', 'review', 'editor', 'idea:xyz' );
+
+		// Explicit role finds the done row.
+		$this->assertTrue(
+			\PRAutoBlogger_Run_Stage_State::is_done( 'run-2', 'review', 'editor', 'idea:xyz' ),
+			'is_done with explicit role should be true'
+		);
+		// '' resolves to 'editor'; primary misses; legacy '' fallback also misses.
+		$this->assertFalse(
+			\PRAutoBlogger_Run_Stage_State::is_done( 'run-2', 'review', '', 'idea:xyz' ),
+			'is_done with legacy empty role should be false (no legacy row exists)'
+		);
+	}
+
+	/**
+	 * Mid-run-upgrade resume: a row created by v0.18.1 (agent_role='') must
+	 * still be found by is_done('') under v0.18.2 via the legacy fallback.
+	 * resolve_role('review','') → 'editor'; primary query misses; legacy
+	 * fallback (role='') hits → is_done returns true.
+	 */
+	public function test_legacy_empty_role_row_is_found_on_fallback(): void {
+		$call_index      = 0;
+		$get_row_results = array(
+			null,   // primary query (role='editor'): miss.
+			array( 'status' => 'done', 'meta_json' => null ), // legacy fallback (role=''): hit.
+		);
+		$this->wpdb->method( 'get_var' )->willReturn( 'wp_prautoblogger_run_stages' );
+		$this->wpdb->method( 'get_row' )->willReturnCallback(
+			static function () use ( &$get_row_results, &$call_index ) {
+				$result = $get_row_results[ $call_index ] ?? null;
+				++$call_index;
+				return $result;
+			}
+		);
+
+		// is_done('') resolves to 'editor', misses, falls back to role='',
+		// finds the v0.18.1 row → true.
+		$this->assertTrue(
+			\PRAutoBlogger_Run_Stage_State::is_done( 'run-3', 'review', '', 'idea:abc' ),
+			'v0.18.1 empty-role row must be found via legacy fallback'
+		);
+	}
 }

tests/unit/Providers/OpenRouterCompletionGuardTest.php

@@ -0,0 +1,240 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_OpenRouter_Completion_Guard (v0.18.1).
+ *
+ * Validates the empty-completion verdict matrix: healthy pass-through,
+ * the single reasoning-disabled retry on length/reasoning empties, the
+ * never-retry-twice rule, and the hard failure for unexplained empties.
+ *
+ * @package PRAutoBlogger\Tests\Providers
+ */
+
+namespace PRAutoBlogger\Tests\Providers;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class OpenRouterCompletionGuardTest extends BaseTestCase {
+
+    protected function setUp(): void {
+        parent::setUp();
+
+        \PRAutoBlogger_Run_Context::clear();
+        \PRAutoBlogger_Audit_Writer::flush_cache();
+
+        $this->stub_get_option( [
+            'prautoblogger_log_level' => 'error',
+        ] );
+
+        // Cost_Tracker::log_api_call() (failed-attempt booking) inserts a
+        // generation_log row and prices the burn via the pricing chain.
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'insert' )->willReturn( 1 );
+        $wpdb->insert_id = 7;
+        $GLOBALS['wpdb'] = $wpdb;
+    }
+
+    protected function tearDown(): void {
+        unset( $GLOBALS['wpdb'] );
+        \PRAutoBlogger_Run_Context::clear();
+        \PRAutoBlogger_Audit_Writer::flush_cache();
+        parent::tearDown();
+    }
+
+    /**
+     * Build a parsed-response fixture in the Response_Parser shape.
+     *
+     * @param string $content Visible content.
+     * @param string $finish  finish_reason value.
+     * @return array
+     */
+    private function parsed( string $content, string $finish ): array {
+        return [
+            'content'           => $content,
+            'model'             => 'deepseek/deepseek-v4-flash',
+            'prompt_tokens'     => 1200,
+            'completion_tokens' => 4000,
+            'reasoning_tokens'  => 4000,
+            'total_tokens'      => 5200,
+            'finish_reason'     => $finish,
+            'reasoning_content' => 'thinking…',
+        ];
+    }
+
+    /**
+     * Healthy completion passes through untouched; the retry callable is
+     * never invoked.
+     */
+    public function test_healthy_completion_passes_through(): void {
+        $parsed  = $this->parsed( 'A full article.', 'stop' );
+        $invoked = 0;
+
+        $result = ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+            $parsed,
+            [ 'stage' => 'draft' ],
+            false,
+            function () use ( &$invoked ) {
+                ++$invoked;
+                return [];
+            }
+        );
+
+        $this->assertSame( $parsed, $result );
+        $this->assertSame( 0, $invoked );
+    }
+
+    /**
+     * The incident shape — empty content + finish_reason=length — retries
+     * exactly once with reasoning disabled and the empty_retry marker set,
+     * and returns the retry's result.
+     */
+    public function test_empty_plus_length_retries_once_with_reasoning_disabled(): void {
+        $recovered     = $this->parsed( 'Recovered article.', 'stop' );
+        $captured_opts = null;
+
+        $result = ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+            $this->parsed( '', 'length' ),
+            [ 'stage' => 'draft', 'prompt_key' => 'content.single_pass' ],
+            true,
+            function ( array $retry_options ) use ( &$captured_opts, $recovered ) {
+                $captured_opts = $retry_options;
+                return $recovered;
+            }
+        );
+
+        $this->assertSame( $recovered, $result );
+        $this->assertSame( [ 'enabled' => false ], $captured_opts['reasoning'] );
+        $this->assertTrue( $captured_opts['empty_retry'] );
+        $this->assertSame( 'draft', $captured_opts['stage'] );
+    }
+
+    /**
+     * Whitespace-only content counts as empty (the guard trims).
+     */
+    public function test_whitespace_only_content_counts_as_empty(): void {
+        $invoked = 0;
+
+        ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+            $this->parsed( "  \n\t ", 'length' ),
+            [ 'stage' => 'polish' ],
+            true,
+            function ( array $retry_options ) use ( &$invoked ) {
+                ++$invoked;
+                return $this->parsed( 'ok', 'stop' );
+            }
+        );
+
+        $this->assertSame( 1, $invoked );
+    }
+
+    /**
+     * An attempt already marked empty_retry is never retried again — the
+     * guard fails the call instead (no infinite retry loops).
+     */
+    public function test_already_retried_empty_fails_without_second_retry(): void {
+        $invoked = 0;
+
+        try {
+            ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+                $this->parsed( '', 'length' ),
+                [ 'stage' => 'draft', 'empty_retry' => true ],
+                false,
+                function () use ( &$invoked ) {
+                    ++$invoked;
+                    return [];
+                }
+            );
+            $this->fail( 'Expected RuntimeException for retried-and-still-empty completion.' );
+        } catch ( \RuntimeException $e ) {
+            $this->assertStringContainsString( 'empty content', $e->getMessage() );
+            $this->assertStringContainsString( 'after a reasoning-disabled retry', $e->getMessage() );
+        }
+
+        $this->assertSame( 0, $invoked );
+    }
+
+    /**
+     * Empty content with finish_reason=stop and no reasoning active: a
+     * reasoning-disabled retry cannot plausibly help — fail immediately.
+     */
+    public function test_unexplained_empty_fails_without_retry(): void {
+        $invoked = 0;
+
+        try {
+            ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+                $this->parsed( '', 'stop' ),
+                [ 'stage' => 'review' ],
+                false,
+                function () use ( &$invoked ) {
+                    ++$invoked;
+                    return [];
+                }
+            );
+            $this->fail( 'Expected RuntimeException for unexplained empty completion.' );
+        } catch ( \RuntimeException $e ) {
+            $this->assertStringContainsString( 'stage "review"', $e->getMessage() );
+            $this->assertStringContainsString( 'finish_reason=stop', $e->getMessage() );
+        }
+
+        $this->assertSame( 0, $invoked );
+    }
+
+    /**
+     * Empty content with reasoning active retries even when finish_reason
+     * is not 'length' (reasoning can eat the budget without a length flag).
+     */
+    public function test_empty_with_reasoning_active_retries_on_any_finish_reason(): void {
+        $invoked = 0;
+
+        ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+            $this->parsed( '', 'stop' ),
+            [ 'stage' => 'draft' ],
+            true,
+            function ( array $retry_options ) use ( &$invoked ) {
+                ++$invoked;
+                return $this->parsed( 'ok', 'stop' );
+            }
+        );
+
+        $this->assertSame( 1, $invoked );
+    }
+
+    /**
+     * The failed attempt is booked to generation_log with its REAL status:
+     * response_status='error', the stage, the model, and the token burn.
+     */
+    public function test_failed_attempt_books_generation_log_row_with_error_status(): void {
+        $captured_row = null;
+
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'insert' )->willReturnCallback(
+            function ( $table, $row ) use ( &$captured_row ) {
+                if ( false !== strpos( (string) $table, 'generation_log' ) ) {
+                    $captured_row = $row;
+                }
+                return 1;
+            }
+        );
+        $wpdb->insert_id = 9;
+        $GLOBALS['wpdb'] = $wpdb;
+
+        try {
+            ( new \PRAutoBlogger_OpenRouter_Completion_Guard() )->finalize(
+                $this->parsed( '', 'stop' ),
+                [ 'stage' => 'draft' ],
+                false,
+                function () {
+                    return [];
+                }
+            );
+            $this->fail( 'Expected RuntimeException.' );
+        } catch ( \RuntimeException $e ) {
+            $this->assertIsArray( $captured_row );
+            $this->assertSame( 'error', $captured_row['response_status'] );
+            $this->assertSame( 'draft', $captured_row['stage'] );
+            $this->assertSame( 'deepseek/deepseek-v4-flash', $captured_row['model'] );
+            $this->assertSame( 4000, $captured_row['completion_tokens'] );
+            $this->assertStringContainsString( 'Empty completion', $captured_row['error_message'] );
+        }
+    }
+}

tests/unit/Providers/OpenRouterProviderRetryTest.php

@@ -0,0 +1,223 @@
+<?php
+/**
+ * Retry-path integration tests for PRAutoBlogger_OpenRouter_Provider.
+ *
+ * Wires the full send_chat_completion() path (decryptable API key,
+ * scripted HTTP responses, wpdb mock for failure bookkeeping) to verify
+ * the v0.18.1 empty-completion guard end to end: the incident-shape
+ * single retry with reasoning disabled, and the reasoning token cap
+ * shaping the outgoing request. Split from OpenRouterProviderTest.php
+ * to keep both files under the 300-line rule. All HTTP calls are
+ * mocked — no real API calls.
+ *
+ * @package PRAutoBlogger\Tests\Providers
+ */
+
+namespace PRAutoBlogger\Tests\Providers;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class OpenRouterProviderRetryTest extends BaseTestCase {
+
+    protected function setUp(): void {
+        parent::setUp();
+
+        // Stub get_option — provider calls get_option('prautoblogger_openrouter_api_key', '')
+        // for API key retrieval via private get_api_key() method.
+        // Return empty string so decryption is skipped (no key = empty return).
+        // Also include prautoblogger_log_level for Logger singleton.
+        $this->stub_get_option( [
+            'prautoblogger_openrouter_api_key' => '',
+            'prautoblogger_log_level'          => 'info',
+        ] );
+
+        // Stub wp_salt — called by PRAutoBlogger_Encryption during API key decryption.
+        Functions\when( 'wp_salt' )->justReturn( 'test_salt_key_for_unit_tests' );
+
+        // Stub get_transient/set_transient — used by OpenRouter_Pricing (called internally).
+        Functions\when( 'get_transient' )->alias(
+            function ( string $key ) {
+                if ( 'prautoblogger_openrouter_models' === $key ) {
+                    return [
+                        [
+                            'id'             => 'model/test',
+                            'name'           => 'Test Model',
+                            'context_length' => 4096,
+                            'pricing'        => [ 'prompt' => 1.00, 'completion' => 2.00 ],
+                        ],
+                    ];
+                }
+                return false;
+            }
+        );
+        Functions\when( 'set_transient' )->justReturn( true );
+
+        // Stub URL parsing.
+        Functions\when( 'wp_parse_url' )->alias( 'parse_url' );
+
+        // Stub HTTP functions for API calls.
+        Functions\when( 'wp_remote_post' )->justReturn( [
+            'body'     => '{"choices":[{"message":{"content":"test"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}',
+            'response' => [ 'code' => 200 ],
+        ] );
+        Functions\when( 'wp_remote_get' )->justReturn( [
+            'body'     => '{}',
+            'response' => [ 'code' => 200 ],
+        ] );
+        Functions\when( 'wp_remote_retrieve_response_code' )->justReturn( 200 );
+        Functions\when( 'wp_remote_retrieve_body' )->justReturn(
+            '{"choices":[{"message":{"content":"test"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}'
+        );
+        Functions\when( 'is_wp_error' )->justReturn( false );
+    }
+
+    /**
+     * Wire the provider for a full send_chat_completion run: decryptable
+     * API key, reasoning settings, HTTP stubs that replay scripted
+     * responses, and a wpdb mock for the guard's failure bookkeeping.
+     *
+     * @param array $option_overrides Extra get_option values.
+     * @param array $responses        Scripted JSON-decodable response bodies.
+     * @param array $requests         (by ref) captures decoded request bodies.
+     */
+    private function wire_full_provider( array $option_overrides, array $responses, array &$requests ): void {
+        \PRAutoBlogger_Run_Context::clear();
+
+        $encrypted_key = \PRAutoBlogger_Encryption::encrypt( 'sk-or-v1-unit-test-key-0000' );
+
+        $this->stub_get_option( array_merge( [
+            'prautoblogger_openrouter_api_key' => $encrypted_key,
+            'prautoblogger_log_level'          => 'error',
+        ], $option_overrides ) );
+
+        Functions\when( 'absint' )->alias( function ( $val ) {
+            return abs( (int) $val );
+        } );
+
+        Functions\when( 'wp_remote_post' )->alias(
+            function ( $url, $args ) use ( &$requests, $responses ) {
+                $requests[] = json_decode( $args['body'], true );
+                $body       = $responses[ count( $requests ) - 1 ];
+                return [
+                    'body'     => $body,
+                    'response' => [ 'code' => 200 ],
+                ];
+            }
+        );
+        Functions\when( 'wp_remote_retrieve_response_code' )->alias(
+            function ( $response ) {
+                return $response['response']['code'];
+            }
+        );
+        Functions\when( 'wp_remote_retrieve_body' )->alias(
+            function ( $response ) {
+                return $response['body'];
+            }
+        );
+
+        // The guard books failed attempts through Cost_Tracker + Logger.
+        $wpdb = $this->create_mock_wpdb();
+        $wpdb->method( 'insert' )->willReturn( 1 );
+        $wpdb->insert_id = 11;
+        $GLOBALS['wpdb'] = $wpdb;
+    }
+
+    /**
+     * v0.18.1 incident shape, end to end: reasoning enabled (uncapped
+     * effort mode), the first response burns the whole completion budget
+     * on thinking and returns empty content with finish_reason=length —
+     * the provider retries exactly once with reasoning disabled and
+     * returns the recovered completion.
+     */
+    public function test_empty_length_completion_retries_once_with_reasoning_disabled(): void {
+        $requests = [];
+
+        $empty_response = json_encode( [
+            'model'   => 'deepseek/deepseek-v4-flash',
+            'choices' => [ [ 'message' => [ 'content' => '', 'reasoning' => 'endless thinking…' ], 'finish_reason' => 'length' ] ],
+            'usage'   => [ 'prompt_tokens' => 1200, 'completion_tokens' => 4000, 'reasoning_tokens' => 4000, 'total_tokens' => 5200 ],
+        ] );
+        $good_response = json_encode( [
+            'model'   => 'deepseek/deepseek-v4-flash',
+            'choices' => [ [ 'message' => [ 'content' => 'Recovered article.' ], 'finish_reason' => 'stop' ] ],
+            'usage'   => [ 'prompt_tokens' => 1200, 'completion_tokens' => 900, 'total_tokens' => 2100 ],
+        ] );
+
+        $this->wire_full_provider(
+            [
+                'prautoblogger_reasoning_enabled'    => '1',
+                'prautoblogger_reasoning_effort'     => 'xhigh',
+                'prautoblogger_reasoning_max_tokens' => 0,
+            ],
+            [ $empty_response, $good_response ],
+            $requests
+        );
+
+        try {
+            $provider = new \PRAutoBlogger_OpenRouter_Provider();
+            $result   = $provider->send_chat_completion(
+                [ [ 'role' => 'user', 'content' => 'Write the article.' ] ],
+                'deepseek/deepseek-v4-flash',
+                [ 'temperature' => 0.7, 'max_tokens' => 4000, 'stage' => 'draft' ]
+            );
+
+            $this->assertSame( 'Recovered article.', $result['content'] );
+            $this->assertCount( 2, $requests );
+            // First attempt: global reasoning, uncapped effort mode.
+            $this->assertSame( [ 'enabled' => true, 'effort' => 'xhigh' ], $requests[0]['reasoning'] );
+            $this->assertSame( 4000, $requests[0]['max_tokens'] );
+            // Retry: reasoning disabled per call.
+            $this->assertSame( [ 'enabled' => false ], $requests[1]['reasoning'] );
+            // Caller metadata never reaches the HTTP body.
+            $this->assertArrayNotHasKey( 'stage', $requests[0] );
+            $this->assertArrayNotHasKey( 'empty_retry', $requests[1] );
+        } finally {
+            unset( $GLOBALS['wpdb'] );
+            \PRAutoBlogger_Run_Context::clear();
+        }
+    }
+
+    /**
+     * v0.18.1 reasoning budget: with the token cap active (default), the
+     * outgoing request caps thinking via reasoning.max_tokens and raises
+     * max_tokens by the cap — and a healthy completion needs no retry.
+     */
+    public function test_reasoning_cap_shapes_the_outgoing_request(): void {
+        $requests = [];
+
+        $good_response = json_encode( [
+            'model'   => 'deepseek/deepseek-v4-flash',
+            'choices' => [ [ 'message' => [ 'content' => 'Article text.' ], 'finish_reason' => 'stop' ] ],
+            'usage'   => [ 'prompt_tokens' => 1200, 'completion_tokens' => 900, 'total_tokens' => 2100 ],
+        ] );
+
+        $this->wire_full_provider(
+            [
+                'prautoblogger_reasoning_enabled'    => '1',
+                'prautoblogger_reasoning_effort'     => 'xhigh',
+                'prautoblogger_reasoning_max_tokens' => 2048,
+            ],
+            [ $good_response ],
+            $requests
+        );
+
+        try {
+            $provider = new \PRAutoBlogger_OpenRouter_Provider();
+            $result   = $provider->send_chat_completion(
+                [ [ 'role' => 'user', 'content' => 'Write the article.' ] ],
+                'deepseek/deepseek-v4-flash',
+                [ 'temperature' => 0.7, 'max_tokens' => 4000, 'stage' => 'draft' ]
+            );
+
+            $this->assertSame( 'Article text.', $result['content'] );
+            $this->assertCount( 1, $requests );
+            $this->assertSame( 2048, $requests[0]['reasoning']['max_tokens'] );
+            $this->assertArrayNotHasKey( 'effort', $requests[0]['reasoning'] );
+            $this->assertSame( 6048, $requests[0]['max_tokens'] );
+        } finally {
+            unset( $GLOBALS['wpdb'] );
+            \PRAutoBlogger_Run_Context::clear();
+        }
+    }
+}

tests/unit/Providers/OpenRouterRequestBuilderTest.php

@@ -0,0 +1,189 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_OpenRouter_Request_Builder::build_body() (v0.18.1).
+ *
+ * Validates body assembly, the global-vs-per-call reasoning precedence, the
+ * reasoning token cap + completion headroom, and that caller-metadata keys
+ * never leak into the HTTP body.
+ *
+ * @package PRAutoBlogger\Tests\Providers
+ */
+
+namespace PRAutoBlogger\Tests\Providers;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class OpenRouterRequestBuilderTest extends BaseTestCase {
+
+    private const MESSAGES = [
+        [ 'role' => 'system', 'content' => 'sys' ],
+        [ 'role' => 'user', 'content' => 'usr' ],
+    ];
+
+    protected function setUp(): void {
+        parent::setUp();
+        Functions\when( 'absint' )->alias( function ( $val ) {
+            return abs( (int) $val );
+        } );
+    }
+
+    /**
+     * Reasoning enabled globally + cap set: thinking is capped via
+     * reasoning.max_tokens, effort is dropped, and the completion budget
+     * is raised by the cap so content keeps its full allowance.
+     */
+    public function test_reasoning_cap_replaces_effort_and_raises_headroom(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled'    => '1',
+            'prautoblogger_reasoning_effort'     => 'xhigh',
+            'prautoblogger_reasoning_max_tokens' => 2048,
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body( self::MESSAGES, 'deepseek/deepseek-v4-flash', [ 'max_tokens' => 4000 ] );
+
+        $this->assertSame( 2048, $body['reasoning']['max_tokens'] );
+        $this->assertArrayNotHasKey( 'effort', $body['reasoning'] );
+        $this->assertSame( 6048, $body['max_tokens'] );
+        $this->assertTrue( $body['reasoning']['enabled'] );
+    }
+
+    /**
+     * Cap setting 0 = pure effort mode: the historical body shape is
+     * preserved exactly (effort kept, no reasoning.max_tokens, no headroom).
+     */
+    public function test_cap_zero_keeps_pure_effort_mode(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled'    => '1',
+            'prautoblogger_reasoning_effort'     => 'xhigh',
+            'prautoblogger_reasoning_max_tokens' => 0,
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body( self::MESSAGES, 'deepseek/deepseek-v4-flash', [ 'max_tokens' => 4000 ] );
+
+        $this->assertSame( [ 'enabled' => true, 'effort' => 'xhigh' ], $body['reasoning'] );
+        $this->assertSame( 4000, $body['max_tokens'] );
+    }
+
+    /**
+     * Per-call reasoning override (the guard's retry) beats the global
+     * setting; a disabled override gets no cap and no headroom.
+     */
+    public function test_per_call_disabled_override_beats_global_setting(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled'    => '1',
+            'prautoblogger_reasoning_effort'     => 'xhigh',
+            'prautoblogger_reasoning_max_tokens' => 2048,
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body(
+                self::MESSAGES,
+                'deepseek/deepseek-v4-flash',
+                [
+                    'max_tokens' => 4000,
+                    'reasoning'  => [ 'enabled' => false ],
+                ]
+            );
+
+        $this->assertSame( [ 'enabled' => false ], $body['reasoning'] );
+        $this->assertSame( 4000, $body['max_tokens'] );
+    }
+
+    /**
+     * Global reasoning off + no override: no reasoning key at all and no
+     * budget math (historical default path).
+     */
+    public function test_reasoning_off_produces_no_reasoning_key(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled' => '0',
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body(
+                self::MESSAGES,
+                'google/gemini-2.5-flash-lite',
+                [
+                    'temperature'     => 0.7,
+                    'max_tokens'      => 4000,
+                    'response_format' => [ 'type' => 'json_object' ],
+                ]
+            );
+
+        $this->assertArrayNotHasKey( 'reasoning', $body );
+        $this->assertSame( 0.7, $body['temperature'] );
+        $this->assertSame( 4000, $body['max_tokens'] );
+        $this->assertSame( [ 'type' => 'json_object' ], $body['response_format'] );
+    }
+
+    /**
+     * An explicit caller reasoning config with its own max_tokens is
+     * respected (no cap overwrite) but still gets completion headroom.
+     */
+    public function test_caller_reasoning_max_tokens_respected_with_headroom(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled'    => '0',
+            'prautoblogger_reasoning_max_tokens' => 2048,
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body(
+                self::MESSAGES,
+                'deepseek/deepseek-v4-flash',
+                [
+                    'max_tokens' => 1000,
+                    'reasoning'  => [ 'enabled' => true, 'max_tokens' => 512 ],
+                ]
+            );
+
+        $this->assertSame( 512, $body['reasoning']['max_tokens'] );
+        $this->assertSame( 1512, $body['max_tokens'] );
+    }
+
+    /**
+     * Caller-metadata keys (stage, prompt_key, empty_retry) must never
+     * appear in the HTTP body.
+     */
+    public function test_caller_metadata_keys_never_leak_into_body(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled' => '0',
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body(
+                self::MESSAGES,
+                'google/gemini-2.5-flash-lite',
+                [
+                    'max_tokens'  => 4000,
+                    'stage'       => 'draft',
+                    'prompt_key'  => 'content.single_pass',
+                    'empty_retry' => true,
+                ]
+            );
+
+        $this->assertArrayNotHasKey( 'stage', $body );
+        $this->assertArrayNotHasKey( 'prompt_key', $body );
+        $this->assertArrayNotHasKey( 'empty_retry', $body );
+        $this->assertSame( [ 'model', 'messages', 'max_tokens' ], array_keys( $body ) );
+    }
+
+    /**
+     * Reasoning enabled but the call has no completion ceiling: nothing to
+     * protect, body passes through with effort untouched.
+     */
+    public function test_no_max_tokens_means_no_budget_math(): void {
+        $this->stub_get_option( [
+            'prautoblogger_reasoning_enabled'    => '1',
+            'prautoblogger_reasoning_effort'     => 'high',
+            'prautoblogger_reasoning_max_tokens' => 2048,
+        ] );
+
+        $body = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )
+            ->build_body( self::MESSAGES, 'deepseek/deepseek-v4-flash', [] );
+
+        $this->assertSame( [ 'enabled' => true, 'effort' => 'high' ], $body['reasoning'] );
+        $this->assertArrayNotHasKey( 'max_tokens', $body );
+    }
+}

tests/unit/Providers/RunwareModelCatalogTest.php

@@ -2,7 +2,9 @@
 /**
  * Tests for PRAutoBlogger_Runware_Model_Catalog.
  *
- * Validates live sync, fallback logic, cache staleness, and pricing merge.
+ * Validates: normalize_models against real modelSearch fixture; cooldown behavior
+ * (failure → no retry within window → retry after); fallback served when cache empty;
+ * success path clears failure timestamp; cache version key v2 is used throughout.
  *
  * @package PRAutoBlogger\Tests\Providers
  */
@@ -11,47 +13,267 @@ namespace PRAutoBlogger\Tests\Providers;
 
 use PRAutoBlogger\Tests\BaseTestCase;
 use Brain\Monkey\Functions;
-use Brain\Monkey\Actions;
 
 class RunwareModelCatalogTest extends BaseTestCase {
 
+	/** Shared in-memory option store reset per test. */
+	private array $options = array();
+
 	protected function setUp(): void {
 		parent::setUp();
-		// Mock WP options for cache simulation.
-		Functions\when( 'get_option' )->alias( function ( $key, $default = false ) {
-			static $options = array();
-			return $options[ $key ] ?? $default;
-		} );
-		Functions\when( 'update_option' )->alias( function ( $key, $value ) {
-			static $options = array();
-			$options[ $key ] = $value;
-			return true;
-		} );
-		Functions\when( 'time' )->justReturn( 1704067200 ); // 2024-01-01 00:00:00
+		$this->options = array();
+		$this->stub_options();
 	}
 
-	/** Sync with empty or missing API key returns false. */
-	public function test_sync_no_api_key(): void {
+	// ── Helpers ────────────────────────────────────────────────────────────────
+
+	private function stub_options(): void {
+		Functions\when( 'get_option' )->alias(
+			function ( $key, $default = false ) {
+				return $this->options[ $key ] ?? $default;
+			}
+		);
+		Functions\when( 'update_option' )->alias(
+			function ( $key, $value ) {
+				$this->options[ $key ] = $value;
+				return true;
+			}
+		);
+		Functions\when( 'delete_option' )->alias(
+			function ( $key ) {
+				unset( $this->options[ $key ] );
+				return true;
+			}
+		);
+		Functions\when( 'time' )->justReturn( 1704067200 ); // 2024-01-01 00:00:00 UTC
+	}
+
+	/**
+	 * Return the fixture as a decoded page array matching fetch_page() output.
+	 *
+	 * @return array{results: array, totalResults: int}
+	 */
+	private function get_fixture_page(): array {
+		$fixture_path = __DIR__ . '/../../fixtures/runware-model-search-page1.json';
+		$json = file_get_contents( $fixture_path );
+		$decoded = json_decode( $json, true );
+		$item = $decoded['data'][0];
+		return array(
+			'results'      => $item['results'],
+			'totalResults' => $item['totalResults'],
+		);
+	}
+
+	/**
+	 * Build a fake HTTP response array for wp_remote_post stubs.
+	 *
+	 * @param int    $status HTTP status code.
+	 * @param string $body   Response body JSON.
+	 * @return array
+	 */
+	private function make_http_response( int $status, string $body ): array {
+		return array(
+			'response' => array( 'code' => $status ),
+			'body'     => $body,
+		);
+	}
+
+	private function stub_http_helpers(): void {
+		Functions\when( 'wp_remote_retrieve_response_code' )->alias(
+			function ( $r ) { return (int) ( $r['response']['code'] ?? 0 ); }
+		);
+		Functions\when( 'wp_remote_retrieve_body' )->alias(
+			function ( $r ) { return (string) ( $r['body'] ?? '' ); }
+		);
+		Functions\when( 'is_wp_error' )->justReturn( false );
+	}
+
+	// ── normalize_models tests (via Fetcher) ──────────────────────────────────
+
+	/**
+	 * normalize_models filters to io:text-to-image and maps air → id,
+	 * comment → description. Non-t2i models are excluded.
+	 *
+	 * Uses the real modelSearch fixture (3 t2i + 1 text LLM + 1 upscaler).
+	 * Expects only the 3 t2i models to pass through.
+	 */
+	public function test_normalize_models_filters_to_text_to_image(): void {
+		$fixture = $this->get_fixture_page();
+		$fetcher = new \PRAutoBlogger_Runware_Catalog_Fetcher();
+		$result  = $fetcher->normalize_models( $fixture['results'] );
+
+		// Fixture has 3 t2i models (runware:100@1, runware:101@1, runware:400@2)
+		// and 2 non-t2i (text LLM + upscaler).
+		$this->assertCount( 3, $result, 'Should include exactly 3 io:text-to-image models' );
+
+		$ids = array_column( $result, 'id' );
+		$this->assertContains( 'runware:100@1', $ids );
+		$this->assertContains( 'runware:101@1', $ids );
+		$this->assertContains( 'runware:400@2', $ids );
+		$this->assertNotContains( 'some-text-model:llm@1', $ids, 'Text LLM must be excluded' );
+		$this->assertNotContains( 'upscale-model:upscaler@1', $ids, 'Upscaler must be excluded' );
+	}
+
+	/** normalize_models uses air as id, name as name, comment as description. */
+	public function test_normalize_models_maps_fields_correctly(): void {
+		$fixture = $this->get_fixture_page();
+		$fetcher = new \PRAutoBlogger_Runware_Catalog_Fetcher();
+		$result  = $fetcher->normalize_models( $fixture['results'] );
+
+		$schnell = null;
+		foreach ( $result as $m ) {
+			if ( 'runware:100@1' === $m['id'] ) {
+				$schnell = $m;
+				break;
+			}
+		}
+
+		$this->assertNotNull( $schnell );
+		$this->assertSame( 'runware:100@1', $schnell['id'] );
+		$this->assertSame( 'FLUX.1 schnell', $schnell['name'] );
+		$this->assertSame( 'runware', $schnell['provider'] );
+		$this->assertNull( $schnell['cost_per_image'], 'Pricing is null before merge_pricing runs' );
+		$this->assertSame( array( 'image_generation' ), $schnell['capabilities'] );
+		$this->assertSame( 'Fast 4-step text-to-image model', $schnell['description'] );
+	}
+
+	/** normalize_models skips entries with empty air field. */
+	public function test_normalize_models_skips_empty_air(): void {
+		$fetcher = new \PRAutoBlogger_Runware_Catalog_Fetcher();
+		$raw     = array(
+			array(
+				'air'          => '',
+				'name'         => 'No Air Model',
+				'capabilities' => array( 'io:text-to-image' ),
+				'comment'      => '',
+			),
+			array(
+				'air'          => 'runware:100@1',
+				'name'         => 'Valid',
+				'capabilities' => array( 'io:text-to-image' ),
+				'comment'      => 'OK',
+			),
+		);
+
+		$result = $fetcher->normalize_models( $raw );
+		$this->assertCount( 1, $result );
+		$this->assertSame( 'runware:100@1', $result[0]['id'] );
+	}
+
+	/** normalize_models returns empty array for empty input. */
+	public function test_normalize_models_empty_input(): void {
+		$fetcher = new \PRAutoBlogger_Runware_Catalog_Fetcher();
+		$this->assertSame( array(), $fetcher->normalize_models( array() ) );
+	}
+
+	// ── Failure cooldown tests ────────────────────────────────────────────────
+
+	/** No failure on record → is_in_failure_cooldown returns false. */
+	public function test_no_failure_cooldown_when_no_failure_recorded(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertFalse( $catalog->is_in_failure_cooldown() );
+	}
+
+	/** Failure recorded at t=now → cooldown active within 1h window. */
+	public function test_cooldown_active_within_window(): void {
+		$now = 1704067200;
+		$this->options['prautoblogger_runware_catalog_last_failure_at'] = $now;
+		// time() is stubbed to $now, so age = 0 < 3600 = cooldown.
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertTrue( $catalog->is_in_failure_cooldown() );
+	}
+
+	/** Failure recorded > 1h ago → cooldown expired, retry permitted. */
+	public function test_cooldown_expired_after_window(): void {
+		$now      = 1704067200;
+		$past     = $now - 3601; // More than 1h ago.
+		$this->options['prautoblogger_runware_catalog_last_failure_at'] = $past;
+
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertFalse( $catalog->is_in_failure_cooldown() );
+	}
+
+	/** Custom cooldown from settings is respected. */
+	public function test_cooldown_uses_setting_value(): void {
+		$now  = 1704067200;
+		$this->options['prautoblogger_runware_catalog_last_failure_at']        = $now - 100;
+		// Default 3600s would make this expired (100 < 3600), but set custom = 60s.
+		// 100s > 60s so it should be expired.
+		$this->options['prautoblogger_runware_catalog_failure_cooldown_seconds'] = 60;
+
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertFalse( $catalog->is_in_failure_cooldown() );
+	}
+
+	/** Sync failure sets last_failure_at and does not clear success timestamp. */
+	public function test_sync_failure_records_failure_timestamp(): void {
+		// Mock HTTP 401 to force sync failure.
+		$this->options['prautoblogger_runware_api_key'] = 'test-api-key-plain';
+		$this->stub_http_helpers();
+		Functions\when( 'wp_remote_post' )->justReturn(
+			$this->make_http_response( 401, '{"errors":[{"message":"Unauthorized"}]}' )
+		);
+
 		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
 		$result  = $catalog->sync();
+
 		$this->assertFalse( $result );
+		$this->assertNotNull( $catalog->get_last_failure_at(), 'Failure timestamp should be recorded' );
 	}
 
-	/** get_models returns fallback if no cache and sync fails. */
-	public function test_get_models_fallback_on_sync_failure(): void {
+	/** After failure, get_models suppresses sync within cooldown window. */
+	public function test_get_models_suppresses_sync_during_cooldown(): void {
+		$now = 1704067200;
+		$this->options['prautoblogger_runware_api_key']                    = 'test-api-key-plain';
+		$this->options['prautoblogger_runware_catalog_last_failure_at']    = $now; // just failed.
+		$this->options['prautoblogger_runware_model_cache_updated_at']     = $now - 90000; // stale cache.
+
+		$this->stub_http_helpers();
+		// wp_remote_post should NOT be called during cooldown.
+		Functions\expect( 'wp_remote_post' )->never();
+
 		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
 		$models  = $catalog->get_models();
 
-		// Should have the fallback list (15 Runware models).
-		$this->assertIsArray( $models );
-		$this->assertGreaterThan( 0, count( $models ) );
+		// Should fall back to hardcoded fallback list.
+		$this->assertNotEmpty( $models );
+		$ids = array_column( $models, 'id' );
+		$this->assertContains( 'runware:100@1', $ids, 'Fallback schnell model should be present' );
+	}
+
+	/** Successful sync clears failure timestamp. */
+	public function test_successful_sync_clears_failure_timestamp(): void {
+		$now = 1704067200;
+		$this->options['prautoblogger_runware_api_key']                 = 'test-api-key-plain';
+		$this->options['prautoblogger_runware_catalog_last_failure_at'] = $now - 7200; // old failure.
+
+		$fixture_body = file_get_contents( __DIR__ . '/../../fixtures/runware-model-search-page1.json' );
+		$this->stub_http_helpers();
+		Functions\when( 'wp_remote_post' )->justReturn(
+			$this->make_http_response( 200, $fixture_body )
+		);
+
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$result  = $catalog->sync();
+
+		$this->assertTrue( $result, 'Sync should succeed with valid fixture response' );
+		$this->assertNull( $catalog->get_last_failure_at(), 'Success should clear failure timestamp' );
+	}
+
+	// ── Fallback list tests ───────────────────────────────────────────────────
+
+	/** get_models returns fallback when no cache and sync fails. */
+	public function test_get_models_returns_fallback_when_no_cache(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$models  = $catalog->get_models();
+
+		$this->assertIsArray( $models );
+		$this->assertNotEmpty( $models );
 
-		// Check at least one expected fallback model exists.
 		$schnell_exists = false;
 		foreach ( $models as $model ) {
 			if ( 'runware:100@1' === ( $model['id'] ?? '' ) ) {
 				$schnell_exists = true;
-				$this->assertSame( 'FLUX.1 schnell (Runware)', $model['name'] );
 				$this->assertSame( 'runware', $model['provider'] );
 				break;
 			}
@@ -59,28 +281,12 @@ class RunwareModelCatalogTest extends BaseTestCase {
 		$this->assertTrue( $schnell_exists, 'Fallback should include FLUX.1 schnell' );
 	}
 
-	/** is_stale returns true if never synced. */
-	public function test_is_stale_never_synced(): void {
-		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
-		$this->assertTrue( $catalog->is_stale() );
-	}
-
-	/** get_last_synced_at returns null if never synced. */
-	public function test_get_last_synced_at_never(): void {
-		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
-		$this->assertNull( $catalog->get_last_synced_at() );
-	}
-
-	/** Fallback list is never empty. */
+	/** Fallback list is never empty (even with no key configured). */
 	public function test_get_models_never_empty(): void {
 		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
-
-		// Even with no cache and failed sync, get_models should return the fallback.
 		$models  = $catalog->get_models();
-		$this->assertIsArray( $models );
 		$this->assertNotEmpty( $models );
 
-		// All models should have required fields.
 		foreach ( $models as $model ) {
 			$this->assertArrayHasKey( 'id', $model );
 			$this->assertArrayHasKey( 'name', $model );
@@ -89,7 +295,18 @@ class RunwareModelCatalogTest extends BaseTestCase {
 		}
 	}
 
-	/** Fallback models have correct pricing. */
+	/** All fallback models carry the image_generation capability. */
+	public function test_fallback_models_have_image_generation_capability(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$models  = $catalog->get_models();
+
+		foreach ( $models as $model ) {
+			$this->assertIsArray( $model['capabilities'] );
+			$this->assertContains( 'image_generation', $model['capabilities'] );
+		}
+	}
+
+	/** Fallback schnell and dev have correct pricing. */
 	public function test_fallback_models_have_pricing(): void {
 		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
 		$models  = $catalog->get_models();
@@ -107,83 +324,98 @@ class RunwareModelCatalogTest extends BaseTestCase {
 
 		$this->assertNotNull( $schnell );
 		$this->assertEqualsWithDelta( 0.0006, $schnell['cost_per_image'], 0.000001 );
-
 		$this->assertNotNull( $dev );
 		$this->assertEqualsWithDelta( 0.02, $dev['cost_per_image'], 0.000001 );
 	}
 
-	/** Fallback models all have 'image_generation' capability. */
-	public function test_fallback_models_have_capabilities(): void {
-		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
-		$models = $catalog->get_models();
+	// ── Happy path (sync → cache → get_models) ───────────────────────────────
 
-		foreach ( $models as $model ) {
-			$this->assertIsArray( $model['capabilities'] );
-			$this->assertContains( 'image_generation', $model['capabilities'] );
-		}
-	}
-
-	/** Happy path: successful sync caches models and get_models returns them. */
+	/** Successful sync caches models; get_models returns them from cache. */
 	public function test_sync_success_caches_and_returns_models(): void {
-		// The mocked API response body — models must have taskType=imageInference
-		// so normalize_models() doesn't filter them out.
-		$fake_body = json_encode(
-			array(
-				'data' => array(
-					array(
-						'id'       => 'test-model-1',
-						'name'     => 'Test Model 1',
-						'taskType' => 'imageInference',
-					),
-					array(
-						'id'       => 'test-model-2',
-						'name'     => 'Test Model 2',
-						'taskType' => 'imageInference',
-					),
-				),
-			)
+		$fixture_body = file_get_contents( __DIR__ . '/../../fixtures/runware-model-search-page1.json' );
+		$this->options['prautoblogger_runware_api_key'] = 'test-api-key-plain';
+
+		$this->stub_http_helpers();
+		Functions\when( 'wp_remote_post' )->justReturn(
+			$this->make_http_response( 200, $fixture_body )
 		);
 
-		$fake_response = array(
-			'response' => array( 'code' => 200 ),
-			'body'     => $fake_body,
-		);
-
-		Functions\when( 'wp_remote_post' )->justReturn( $fake_response );
-		// Alias the WP response-parsing helpers so they work against our array.
-		Functions\when( 'wp_remote_retrieve_response_code' )->alias(
-			function ( $r ) { return (int) ( $r['response']['code'] ?? 0 ); }
-		);
-		Functions\when( 'wp_remote_retrieve_body' )->alias(
-			function ( $r ) { return (string) ( $r['body'] ?? '' ); }
-		);
-		Functions\when( 'is_wp_error' )->justReturn( false );
-
-		// Shared options store so get_option/update_option stay in sync
-		// within this test. The API key must be non-empty for sync() to proceed.
-		$store = array( 'prautoblogger_runware_api_key' => 'test-api-key-plain' );
-		Functions\when( 'get_option' )->alias(
-			function ( $key, $default = false ) use ( &$store ) {
-				return $store[ $key ] ?? $default;
-			}
-		);
-		Functions\when( 'update_option' )->alias(
-			function ( $key, $value ) use ( &$store ) {
-				$store[ $key ] = $value;
-				return true;
-			}
-		);
-
-		// Sync should succeed: API key present, HTTP 200, 2 imageInference models.
 		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
 		$result  = $catalog->sync();
-		$this->assertTrue( $result, 'Sync should return true on HTTP 200 with valid models' );
 
-		// get_models() should now return the synced list from cache.
+		$this->assertTrue( $result, 'Sync should return true on HTTP 200 with valid fixture' );
+
 		$models = $catalog->get_models();
 		$this->assertIsArray( $models );
-		$this->assertCount( 2, $models );
-		$this->assertSame( 'test-model-1', $models[0]['id'] );
-		$this->assertSame( 'test-model-2', $models[1]['id'] );
+		// Fixture has 3 t2i models (schnell, dev, klein 9B).
+		$this->assertCount( 3, $models, 'get_models should return the 3 cached t2i models' );
+
+		$ids = array_column( $models, 'id' );
+		$this->assertContains( 'runware:100@1', $ids );
+		$this->assertContains( 'runware:101@1', $ids );
+		$this->assertContains( 'runware:400@2', $ids );
+	}
+
+	/** Synced models have pricing merged from the pricing class. */
+	public function test_synced_models_have_pricing_merged(): void {
+		$fixture_body = file_get_contents( __DIR__ . '/../../fixtures/runware-model-search-page1.json' );
+		$this->options['prautoblogger_runware_api_key'] = 'test-api-key-plain';
+
+		$this->stub_http_helpers();
+		Functions\when( 'wp_remote_post' )->justReturn(
+			$this->make_http_response( 200, $fixture_body )
+		);
+
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$catalog->sync();
+		$models = $catalog->get_models();
+
+		$schnell = null;
+		foreach ( $models as $m ) {
+			if ( 'runware:100@1' === $m['id'] ) {
+				$schnell = $m;
+			}
+		}
+		$this->assertNotNull( $schnell );
+		$this->assertEqualsWithDelta( 0.0006, (float) $schnell['cost_per_image'], 0.000001 );
+	}
+
+	// ── Stale / absent cache tests ────────────────────────────────────────────
+
+	/** is_stale returns true if never synced. */
+	public function test_is_stale_never_synced(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertTrue( $catalog->is_stale() );
+	}
+
+	/** is_stale returns false for a fresh cache (synced < 24h ago). */
+	public function test_is_stale_fresh_cache(): void {
+		$now = 1704067200;
+		$this->options['prautoblogger_runware_model_cache_updated_at'] = $now - 3600; // 1h ago.
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertFalse( $catalog->is_stale() );
+	}
+
+	/** is_stale returns true when cache is older than 24h. */
+	public function test_is_stale_old_cache(): void {
+		$now = 1704067200;
+		$this->options['prautoblogger_runware_model_cache_updated_at'] = $now - 90000; // > 24h ago.
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertTrue( $catalog->is_stale() );
+	}
+
+	/** get_last_synced_at returns null if never synced. */
+	public function test_get_last_synced_at_never(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$this->assertNull( $catalog->get_last_synced_at() );
+	}
+
+	/** Sync with no API key returns false without recording a failure. */
+	public function test_sync_no_api_key(): void {
+		$catalog = new \PRAutoBlogger_Runware_Model_Catalog();
+		$result  = $catalog->sync();
+		$this->assertFalse( $result );
+		// No key → not a transient failure, no cooldown recorded.
+		$this->assertNull( $catalog->get_last_failure_at() );
 	}
 }