fix(tests): remove Post_Assembler eval stub from SyncModeTest (breaks Publisher tests)

SyncModeTest runs alphabetically before GenerationCheckpointRunnerTest and
PublisherSideEffectsTest. Defining PRAutoBlogger_Post_Assembler via eval with
only amortize_research_costs() caused Publisher* and ResearchReaper tests to
fail with 'Call to undefined method sanitize_llm_content()' because the stub
registered before the autoloader could load the real class.

Fix: remove the Post_Assembler eval block entirely from both generate-tick
tests. The 'more ideas remain' path (2-idea queue, pop one) never calls
Post_Assembler::amortize_research_costs() -- that only runs in the last-idea
branch. No stub is needed.

Article_Worker stub is retained (it IS called in this path and needs a no-op
generate() to avoid real LLM calls).

Agent-Session: prab-reliability-test-fix-20260622

.github/mu-plugins/prautoblogger-deploy-receiver.php

@@ -35,25 +35,33 @@ add_action( 'rest_api_init', 'prautoblogger_deploy_register_route' );
  * Register the deploy REST route.
  */
 function prautoblogger_deploy_register_route(): void {
-	register_rest_route( 'prautoblogger-deploy/v1', '/deploy', [
-		'methods'             => 'POST',
-		'callback'            => 'prautoblogger_deploy_handle',
-		'permission_callback' => 'prautoblogger_deploy_check_auth',
-	] );
+	register_rest_route(
+		'prautoblogger-deploy/v1',
+		'/deploy',
+		array(
+			'methods'             => 'POST',
+			'callback'            => 'prautoblogger_deploy_handle',
+			'permission_callback' => 'prautoblogger_deploy_check_auth',
+		)
+	);
 
 	// Health check endpoint (GET) — useful for monitoring.
-	register_rest_route( 'prautoblogger-deploy/v1', '/status', [
-		'methods'             => 'GET',
-		'callback'            => function () {
-			return [
-				'status'  => 'ready',
-				'plugin'  => is_dir( WP_PLUGIN_DIR . '/prautoblogger' ) ? 'installed' : 'not_installed',
-				'active'  => is_plugin_active( 'prautoblogger/prautoblogger.php' ),
-				'version' => prautoblogger_deploy_get_installed_version(),
-			];
-		},
-		'permission_callback' => 'prautoblogger_deploy_check_auth',
-	] );
+	register_rest_route(
+		'prautoblogger-deploy/v1',
+		'/status',
+		array(
+			'methods'             => 'GET',
+			'callback'            => function () {
+				return array(
+					'status'  => 'ready',
+					'plugin'  => is_dir( WP_PLUGIN_DIR . '/prautoblogger' ) ? 'installed' : 'not_installed',
+					'active'  => is_plugin_active( 'prautoblogger/prautoblogger.php' ),
+					'version' => prautoblogger_deploy_get_installed_version(),
+				);
+			},
+			'permission_callback' => 'prautoblogger_deploy_check_auth',
+		)
+	);
 }
 
 /**
@@ -78,7 +86,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 		return new WP_Error(
 			'rate_limited',
 			'Deploy in progress or recently completed. Wait 60 seconds.',
-			[ 'status' => 429 ]
+			array( 'status' => 429 )
 		);
 	}
 	set_transient( 'prautoblogger_deploy_lock', time(), 60 );
@@ -87,7 +95,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 	$files = $request->get_file_params();
 	if ( empty( $files['plugin']['tmp_name'] ) || ! is_uploaded_file( $files['plugin']['tmp_name'] ) ) {
 		delete_transient( 'prautoblogger_deploy_lock' );
-		return new WP_Error( 'no_file', 'No plugin zip uploaded.', [ 'status' => 400 ] );
+		return new WP_Error( 'no_file', 'No plugin zip uploaded.', array( 'status' => 400 ) );
 	}
 
 	$tmp_file = $files['plugin']['tmp_name'];
@@ -96,11 +104,11 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 	$zip = new ZipArchive();
 	if ( true !== $zip->open( $tmp_file ) ) {
 		delete_transient( 'prautoblogger_deploy_lock' );
-		return new WP_Error( 'invalid_zip', 'Uploaded file is not a valid zip.', [ 'status' => 400 ] );
+		return new WP_Error( 'invalid_zip', 'Uploaded file is not a valid zip.', array( 'status' => 400 ) );
 	}
 
 	$has_main_file = false;
-	for ( $i = 0; $i < $zip->numFiles; $i++ ) {
+	for ( $i = 0; $i < $zip->numFiles; $i++ ) { // phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
 		if ( 'prautoblogger/prautoblogger.php' === $zip->getNameIndex( $i ) ) {
 			$has_main_file = true;
 			break;
@@ -113,7 +121,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 		return new WP_Error(
 			'invalid_plugin',
 			'Zip must contain prautoblogger/prautoblogger.php at root.',
-			[ 'status' => 400 ]
+			array( 'status' => 400 )
 		);
 	}
 
@@ -143,7 +151,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 				activate_plugin( 'prautoblogger/prautoblogger.php' );
 			}
 			delete_transient( 'prautoblogger_deploy_lock' );
-			return new WP_Error( 'backup_failed', 'Could not backup current plugin.', [ 'status' => 500 ] );
+			return new WP_Error( 'backup_failed', 'Could not backup current plugin.', array( 'status' => 500 ) );
 		}
 	}
 
@@ -161,7 +169,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 		}
 		delete_transient( 'prautoblogger_deploy_lock' );
 		error_log( '[PRAutoBlogger Deploy] Extraction failed. Rolled back to previous version.' );
-		return new WP_Error( 'extract_failed', 'Zip extraction failed. Rolled back.', [ 'status' => 500 ] );
+		return new WP_Error( 'extract_failed', 'Zip extraction failed. Rolled back.', array( 'status' => 500 ) );
 	}
 
 	// 7. Activate plugin.
@@ -178,7 +186,7 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 		return new WP_Error(
 			'activation_failed',
 			'Plugin activation failed: ' . $activation_result->get_error_message() . '. Rolled back.',
-			[ 'status' => 500 ]
+			array( 'status' => 500 )
 		);
 	}
 
@@ -188,18 +196,23 @@ function prautoblogger_deploy_handle( WP_REST_Request $request ): WP_REST_Respon
 	}
 
 	$old_version = prautoblogger_deploy_get_installed_version();
-	error_log( sprintf(
-		'[PRAutoBlogger Deploy] Successfully deployed v%s (was: %s) at %s',
-		$incoming_version,
-		$old_version ?: 'fresh install',
-		gmdate( 'Y-m-d H:i:s' )
-	) );
+	error_log(
+		sprintf(
+			'[PRAutoBlogger Deploy] Successfully deployed v%s (was: %s) at %s',
+			$incoming_version,
+			$old_version ? $old_version : 'fresh install',
+			gmdate( 'Y-m-d H:i:s' )
+		)
+	);
 
-	return new WP_REST_Response( [
-		'success' => true,
-		'version' => $incoming_version,
-		'message' => "PRAutoBlogger v{$incoming_version} deployed and activated.",
-	], 200 );
+	return new WP_REST_Response(
+		array(
+			'success' => true,
+			'version' => $incoming_version,
+			'message' => "PRAutoBlogger v{$incoming_version} deployed and activated.",
+		),
+		200
+	);
 }
 
 /**
@@ -210,7 +223,7 @@ function prautoblogger_deploy_get_installed_version(): string {
 	if ( ! file_exists( $main_file ) ) {
 		return '';
 	}
-	$data = get_file_data( $main_file, [ 'Version' => 'Version' ] );
+	$data = get_file_data( $main_file, array( 'Version' => 'Version' ) );
 	return $data['Version'] ?? '';
 }
 

.github/workflows/ci.yml

@@ -1,111 +1,53 @@
-name: CI — Lint & Test
-
-# Runs on every PR and every push to main. Validates PHPUnit tests + lint +
-# coding standards before deploy can happen. deploy.yml on main continues to
-# run its own validate job as a belt-and-suspenders check, but this CI workflow
-# is what gives PRs an immediate signal so fixes happen before merge.
+##
+# CI caller — PRAutoBlogger
+#
+# Thin caller that delegates to the reusable estate CI workflow in peptide-e2e.
+# workflow_call is required so deploy.yml can gate on this workflow via
+# `uses: ./.github/workflows/ci.yml` (the workflow_call trigger enables that).
+#
+# Permissions: contents: write is required at the caller level so the reusable
+# workflow's phpcbf auto-commit job can push fixes back to the PR branch.
+# (GitHub enforces that callers cannot be escalated beyond their declared scope.)
+#
+# tests: brain-monkey — no WP install or DB required; Brain Monkey mocking only.
+# line_limit_paths: includes — estate hard 300-line rule applied to includes/.
+##
+name: CI
 
 on:
+  pull_request: {}
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
+  workflow_call: {}
 
 permissions:
-  contents: read
+  contents: write
 
 jobs:
-  php-lint:
-    name: PHP Lint (${{ matrix.php }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        php: ['8.1', '8.2', '8.3']
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup PHP ${{ matrix.php }}
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: none
-      - name: Syntax check all PHP files
-        # Exclude .github/mu-plugins — those run on the production server (PHP 8+)
-        # and may use PHP 8+ syntax (union types etc.) that older versions reject.
-        run: |
-          set -e
-          find . -name '*.php' \
-            -not -path './vendor/*' \
-            -not -path './node_modules/*' \
-            -not -path './.git/*' \
-            -not -path './.github/*' \
-            -print0 | xargs -0 -n1 -P4 php -l > /dev/null
+  ci:
+    uses: peptide-repo/peptide-e2e/.github/workflows/ci.yml@main
+    with:
+      tests: brain-monkey
+    secrets: inherit
 
-  phpcs:
-    name: PHPCS (WordPress standards)
+  check-constants:
+    name: Check PRAUTOBLOGGER_* constants
     runs-on: ubuntu-latest
-    continue-on-error: false  # strict after PHPCS cleanup in v0.8.3
-    permissions:
-      contents: write  # allows phpcbf auto-fix commits back to the PR branch
     steps:
       - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.head_ref || github.ref_name }}
-          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Setup PHP
+      - name: Setup PHP 8.1
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.1'
           coverage: none
-          tools: composer:v2, phpcs
-      - name: Install WordPress Coding Standards
-        run: |
-          composer global config --no-plugins allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
-          composer global require --no-interaction \
-            "dealerdirect/phpcodesniffer-composer-installer:^1.0" \
-            "wp-coding-standards/wpcs:^3.0" \
-            "phpcsstandards/phpcsutils:^1.0" \
-            "phpcsstandards/phpcsextra:^1.0"
-      - name: Auto-fix with phpcbf (commit back to branch if changed)
-        # phpcbf exits 1 when it makes fixes, 0 when nothing to fix — both are success here.
-        # Commits made via GITHUB_TOKEN do not trigger a new CI run (GitHub prevents loops).
-        run: |
-          phpcbf --standard=phpcs.xml \
-            --extensions=php \
-            --ignore=vendor/*,tests/*,node_modules/* \
-            includes/ prautoblogger.php uninstall.php || true
-          if ! git diff --quiet; then
-            git config user.name "peptiderepo"
-            git config user.email "peptiderepo@users.noreply.github.com"
-            git add -A
-            git commit -m "style: auto-fix PHPCS violations via phpcbf"
-            git push
-          fi
-      - name: Run PHPCS (only non-auto-fixable violations can fail here)
-        run: |
-          phpcs --standard=phpcs.xml \
-            --extensions=php \
-            --ignore=vendor/*,tests/*,node_modules/* \
-            --warning-severity=0 \
-            --report=full \
-            includes/ prautoblogger.php uninstall.php
-
-  phpunit:
-    name: PHPUnit (PHP ${{ matrix.php }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        php: ['8.1', '8.2', '8.3']
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup PHP ${{ matrix.php }}
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: none
-          tools: composer:v2
-      - name: Install composer dependencies
-        run: composer install --no-progress --no-interaction --prefer-dist
-      - name: Run PHPUnit (Brain Monkey — no WP install required)
-        run: vendor/bin/phpunit --testdox
+      - name: Check PRAUTOBLOGGER_* constants
+        # Fails if any PRAUTOBLOGGER_* constant referenced in the shipped
+        # plugin PHP is neither defined in prautoblogger.php nor guarded
+        # by defined() at the reference site. Prevents the v0.19.0 incident
+        # class (constant deleted from bootstrap, test fallback masks the gap).
+        run: php scripts/check-constants.php
+      - name: Self-test check-constants scanner
+        # Verifies the scanner itself can detect the failure cases it was
+        # designed to catch. If the scanner regresses, this step fails CI.
+        # Added v0.21.0; restored in v0.22.0 (was accidentally dropped in rewrite).
+        run: php scripts/check-constants.php --self-test

.github/workflows/cto-review.yml

@@ -1,20 +1,17 @@
 name: CTO Review
 
-# Automated PR review powered by Claude + DeepSeek + Kimi (via OpenRouter)
-# plus Neurometric PR-Summarizer (a Qwen3-4B task-specialist SLM).
+# Automated PR review powered by Claude Haiku (via OpenRouter).
 #
-# During the A/B window (until further notice), every PR gets reviewed by FOUR models
-# in parallel. The PR comment shows each model's verdict side-by-side so we can compare
-# quality/cost on real PRs before picking a permanent default.
+# A/B panel decision 2026-06-12: panel dropped to Haiku-only.
+# Evidence: convo/cto/threads/2026-06-qa-ab-review/02-analyst-findings.md
+# DeepSeek: high false-positive rate (absint()="code exec", PLUGIN_DIR="dir traversal").
+# Kimi: ~60% model failure rate across 13 PRs sampled.
+# Neurometric: summarizer only, zero unique-real findings, unreliable heuristic verdict.
+# Haiku: 0 failures, lowest noise, equivalent real-signal catch rate vs 4-voice panel.
 #
-# Neurometric is a "prose voice": it does not support OpenAI tool-calling, so its
-# contribution is raw markdown + a heuristic verdict. It is never the primary voice.
+# Does NOT merge. Posts formal APPROVE/REQUEST_CHANGES/COMMENT reviews.
 #
-# Does NOT merge. Does NOT post formal APPROVE/REQUEST_CHANGES reviews — always COMMENT
-# (GITHUB_TOKEN can't formally approve PRs without repo-setting toggle).
-#
-# Requires repo secrets: OPENROUTER_API_KEY, NEUROMETRIC_API_KEY (optional; the
-# Neurometric voice self-skips with an inline error note if the key is missing).
+# Requires repo secret: OPENROUTER_API_KEY
 #
 # Cost cap: tracked in Repository Variables (CTO_REVIEW_SPEND_CENTS, CTO_REVIEW_CAP_CENTS).
 # Default cap is 1000 cents ($10/month). Auto-resets on the 1st of each month.
@@ -125,8 +122,8 @@ jobs:
           HEAD_SHA="${{ github.event.pull_request.head.sha }}"
           # Write the diff to a file, not a step output / env var. Passing a
           # ~400KB diff through the process env (execve argv+envp) exceeds the
-          # runner ARG_MAX and fails the next step with "Argument list too long"
-          # (issue #110). File transport also sidesteps the ~1MB step-output cap.
+          # runner ARG_MAX and fails the next step with "Argument list too long".
+          # File transport also sidesteps the ~1MB step-output cap.
           git diff --no-color "$BASE_SHA" "$HEAD_SHA" | head -c 400000 > /tmp/cto-review-diff.txt
           FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")
           SIZE=$(wc -c < /tmp/cto-review-diff.txt)
@@ -151,12 +148,11 @@ jobs:
             echo "EOF_CONV"
           } >> "$GITHUB_OUTPUT"
 
-      - name: Call 4 models in parallel (OpenRouter + Neurometric)
+      - name: Call Haiku via OpenRouter
         if: steps.budget.outputs.skip != 'true'
         id: review
         env:
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
-          NEUROMETRIC_API_KEY: ${{ secrets.NEUROMETRIC_API_KEY }}
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_BODY: ${{ github.event.pull_request.body }}
           PR_AUTHOR: ${{ github.event.pull_request.user.login }}
@@ -184,24 +180,17 @@ jobs:
           fi
 
           python3 - <<'PY'
-          import json, os, sys, urllib.request, concurrent.futures
+          import json, os, sys, urllib.request
 
           api_key = os.environ["OPENROUTER_API_KEY"]
 
-          # A/B harness: four models. Each gets the same prompt.
-          # Primary model's verdict drives the heading. Others are labeled.
-          # Edit this list to change the roster (or drop to 1 after A/B window closes).
-          #
-          # provider_type semantics:
-          #   - "openrouter_tools": OpenAI tool-calling via OpenRouter; structured verdict.
-          #   - "neurometric_prose": Neurometric marketplace SLM; prose output + heuristic verdict.
-          MODELS = [
-              # (slug, display name, input_per_M_USD, output_per_M_USD, is_primary, provider_type)
-              ("anthropic/claude-haiku-4.5",       "Claude Haiku 4.5",                     1.00, 5.00, True,  "openrouter_tools"),
-              ("deepseek/deepseek-chat-v3.1",      "DeepSeek V3.1",                        0.15, 0.75, False, "openrouter_tools"),
-              ("moonshotai/kimi-k2-thinking",      "Kimi K2 Thinking",                     0.60, 2.50, False, "openrouter_tools"),
-              ("neurometric/pr-summarizer",        "Neurometric PR-Summarizer (Qwen3-4B)", 0.00, 0.00, False, "neurometric_prose"),
-          ]
+          # Haiku-only reviewer. A/B panel dropped 2026-06-12 per QA data:
+          # DeepSeek high false-positive rate, Kimi ~60% failure rate,
+          # Neurometric zero unique-real findings. Haiku retained as sole voice.
+          MODEL_SLUG = "anthropic/claude-haiku-4.5"
+          MODEL_DISPLAY = "Claude Haiku 4.5"
+          INPUT_PER_M_USD = 1.00
+          OUTPUT_PER_M_USD = 5.00
 
           system = """You are the CTO and lead reviewer for the peptiderepo project. You are reviewing a pull request opened by an autonomous agent or human contributor.
 
@@ -264,218 +253,100 @@ jobs:
               }
           }]
 
-          PER_MODEL_TIMEOUT = 60  # seconds; one hung model should not block siblings
+          body = {
+              "model": MODEL_SLUG,
+              "max_tokens": 2048,
+              "messages": [
+                  {"role": "system", "content": system},
+                  {"role": "user", "content": user_message}
+              ],
+              "tools": tools,
+              "tool_choice": {"type": "function", "function": {"name": "submit_review"}}
+          }
+          req = urllib.request.Request(
+              "https://openrouter.ai/api/v1/chat/completions",
+              data=json.dumps(body).encode(),
+              headers={
+                  "Authorization": f"Bearer {api_key}",
+                  "content-type": "application/json",
+                  "HTTP-Referer": "https://github.com/peptiderepo",
+                  "X-Title": f"peptiderepo CTO reviewer ({MODEL_DISPLAY})"
+              },
+              method="POST"
+          )
 
-          # Heuristic verdict inference for prose-voice models that can't do tool-calling.
-          # Keyword order matters: block markers beat approve markers.
-          PROSE_BLOCK_MARKERS = [
-              "do not merge", "do not approve", "should not be merged", "reject this",
-              "critical security", "critical issue", "critical vulnerability",
-              "blocker", "blocking issue", "request_changes", "request changes",
-              "**critical**", "sql injection", "must be addressed before",
-          ]
-          PROSE_APPROVE_MARKERS = [
-              "safe to merge", "ready to merge", "no blocking issues", "lgtm",
-              "approve this", "looks good to merge", "no concerns",
-          ]
+          error = None
+          review = None
+          cost_cents = 0.0
+          ptok = 0
+          ctok = 0
 
-          def infer_verdict_from_prose(text):
-              t = (text or "").lower()
-              if any(m in t for m in PROSE_BLOCK_MARKERS):
-                  return "REQUEST_CHANGES"
-              if any(m in t for m in PROSE_APPROVE_MARKERS):
-                  return "APPROVE"
-              return "COMMENT"
-
-          def call_openrouter_tools(slug, display, in_rate, out_rate, is_primary):
-              body = {
-                  "model": slug,
-                  "max_tokens": 2048,
-                  "messages": [
-                      {"role": "system", "content": system},
-                      {"role": "user", "content": user_message}
-                  ],
-                  "tools": tools,
-                  "tool_choice": {"type": "function", "function": {"name": "submit_review"}}
-              }
-              req = urllib.request.Request(
-                  "https://openrouter.ai/api/v1/chat/completions",
-                  data=json.dumps(body).encode(),
-                  headers={
-                      "Authorization": f"Bearer {api_key}",
-                      "content-type": "application/json",
-                      "HTTP-Referer": "https://github.com/peptiderepo",
-                      "X-Title": f"peptiderepo CTO reviewer ({display})"
-                  },
-                  method="POST"
-              )
-              try:
-                  with urllib.request.urlopen(req, timeout=PER_MODEL_TIMEOUT) as resp:
-                      data = json.loads(resp.read())
-              except Exception as e:
-                  return {
-                      "slug": slug, "display": display, "is_primary": is_primary,
-                      "provider_type": "openrouter_tools",
-                      "error": str(e)[:300],
-                      "cost_cents": 0,
-                  }
+          try:
+              with urllib.request.urlopen(req, timeout=60) as resp:
+                  data = json.loads(resp.read())
+          except Exception as e:
+              error = str(e)[:300]
+              data = {}
 
+          if not error:
               choice = data.get("choices", [{}])[0].get("message", {})
               tool_calls = choice.get("tool_calls", [])
               if not tool_calls:
-                  return {
-                      "slug": slug, "display": display, "is_primary": is_primary,
-                      "provider_type": "openrouter_tools",
-                      "error": f"No tool_call in response. Raw content: {str(choice)[:300]}",
-                      "cost_cents": 0,
-                  }
+                  error = f"No tool_call in response. Raw content: {str(choice)[:300]}"
+              else:
+                  try:
+                      review = json.loads(tool_calls[0]["function"]["arguments"])
+                  except Exception as e:
+                      error = f"Malformed tool args: {e}"
 
-              try:
-                  review = json.loads(tool_calls[0]["function"]["arguments"])
-              except Exception as e:
-                  return {
-                      "slug": slug, "display": display, "is_primary": is_primary,
-                      "provider_type": "openrouter_tools",
-                      "error": f"Malformed tool args: {e}",
-                      "cost_cents": 0,
-                  }
+              if not error:
+                  usage = data.get("usage", {})
+                  ptok = usage.get("prompt_tokens", 0)
+                  ctok = usage.get("completion_tokens", 0)
+                  cost_usd = (ptok * INPUT_PER_M_USD / 1_000_000) + (ctok * OUTPUT_PER_M_USD / 1_000_000)
+                  cost_cents = cost_usd * 100
 
-              usage = data.get("usage", {})
-              ptok = usage.get("prompt_tokens", 0)
-              ctok = usage.get("completion_tokens", 0)
-              cost_usd = (ptok * in_rate / 1_000_000) + (ctok * out_rate / 1_000_000)
-              cost_cents = cost_usd * 100
-              return {
-                  "slug": slug, "display": display, "is_primary": is_primary,
-                  "provider_type": "openrouter_tools",
-                  "review": review, "prompt_tokens": ptok, "completion_tokens": ctok,
-                  "cost_cents": cost_cents,
-              }
-
-          def call_neurometric_prose(slug, display, is_primary):
-              nm_key = os.environ.get("NEUROMETRIC_API_KEY", "")
-              if not nm_key:
-                  return {
-                      "slug": slug, "display": display, "is_primary": is_primary,
-                      "provider_type": "neurometric_prose",
-                      "error": "NEUROMETRIC_API_KEY secret not set on this repo",
-                      "cost_cents": 0,
-                  }
-              body = {
-                  "model": slug,
-                  "max_tokens": 2048,
-                  "messages": [
-                      {"role": "system", "content": system},
-                      {"role": "user", "content": user_message},
-                  ],
-              }
-              req = urllib.request.Request(
-                  "https://api.neurometric.ai/v1/chat/completions",
-                  data=json.dumps(body).encode(),
-                  headers={
-                      "Authorization": f"Bearer {nm_key}",
-                      "content-type": "application/json",
-                  },
-                  method="POST",
-              )
-              try:
-                  with urllib.request.urlopen(req, timeout=PER_MODEL_TIMEOUT) as resp:
-                      data = json.loads(resp.read())
-              except Exception as e:
-                  return {
-                      "slug": slug, "display": display, "is_primary": is_primary,
-                      "provider_type": "neurometric_prose",
-                      "error": str(e)[:300],
-                      "cost_cents": 0,
-                  }
-              prose = data.get("choices", [{}])[0].get("message", {}).get("content") or ""
-              verdict = infer_verdict_from_prose(prose)
-              return {
-                  "slug": slug, "display": display, "is_primary": is_primary,
-                  "provider_type": "neurometric_prose",
-                  "review": {"verdict": verdict, "prose": prose},
-                  "prompt_tokens": 0, "completion_tokens": 0,
-                  "cost_cents": 0,
-              }
-
-          def call_model(slug, display, in_rate, out_rate, is_primary, provider_type="openrouter_tools"):
-              if provider_type == "neurometric_prose":
-                  return call_neurometric_prose(slug, display, is_primary)
-              return call_openrouter_tools(slug, display, in_rate, out_rate, is_primary)
-
-          results = []
-          with concurrent.futures.ThreadPoolExecutor(max_workers=len(MODELS)) as pool:
-              futures = [pool.submit(call_model, *m) for m in MODELS]
-              for f in concurrent.futures.as_completed(futures):
-                  results.append(f.result())
-
-          # Order: primary first, then alphabetical for stable comparison
-          results.sort(key=lambda r: (not r.get("is_primary"), r["display"]))
-
-          # Build combined comment
-          primary = next((r for r in results if r.get("is_primary") and "review" in r), None)
-          heading_verdict = primary["review"]["verdict"] if primary else "MIXED"
-
-          lines = [f"## CTO Review — {heading_verdict}", ""]
-          lines.append(f"_A/B harness active: {len(results)} models reviewing in parallel. Primary verdict drives heading; others are advisory._")
-          lines.append("")
-
-          total_cents = 0.0
-          for r in results:
-              lines.append(f"---")
-              primary_tag = " (primary)" if r.get("is_primary") else ""
-              lines.append(f"### {r['display']}{primary_tag}")
-              if "error" in r:
-                  lines.append("")
-                  lines.append(f"⚠️ Model failed: `{r['error']}`")
-                  lines.append("")
-                  continue
-              rev = r["review"]
+          # Build comment
+          if error:
+              heading_verdict = "ERROR"
+              lines = [f"## CTO Review — {heading_verdict}", ""]
+              lines.append(f"Model failed: `{error}`")
               lines.append("")
-              if r.get("provider_type") == "neurometric_prose":
-                  lines.append(f"**Verdict:** {rev['verdict']} _(heuristic, inferred from prose)_")
-                  lines.append("")
-                  # Cap at 6KB to keep PR comments readable; 4B model output is rarely over this
-                  prose = rev.get("prose", "")
-                  if len(prose) > 6000:
-                      prose = prose[:6000] + "\n\n_…output truncated for comment length…_"
-                  lines.append(prose)
-                  lines.append("")
-                  lines.append("_free tier; per-call token usage not tracked_")
-                  lines.append("")
-                  continue
-              lines.append(f"**Verdict:** {rev.get('verdict', 'COMMENT')}")
+              lines.append(f"_reviewer: {MODEL_DISPLAY}_")
+          else:
+              heading_verdict = review.get("verdict", "COMMENT")
+              lines = [f"## CTO Review — {heading_verdict}", ""]
+              lines.append(f"**Verdict:** {heading_verdict}")
               lines.append("")
-              lines.append(rev.get("summary") or "_(model returned no summary)_")
+              lines.append(review.get("summary") or "_(model returned no summary)_")
               lines.append("")
-              if rev.get("concerns"):
+              if review.get("concerns"):
                   lines.append("**Concerns:**")
-                  for c in rev["concerns"]:
+                  for c in review["concerns"]:
                       sev = c.get("severity", "UNKNOWN").upper()
                       f = f"`{c['file']}`" if c.get("file") else ""
                       lines.append(f"- **{sev}** {f} — {c['issue']}")
                   lines.append("")
-              if rev.get("positives"):
-                  lines.append("**Positives:** " + "; ".join(rev["positives"]))
+              if review.get("positives"):
+                  lines.append("**Positives:** " + "; ".join(review["positives"]))
                   lines.append("")
-              lines.append(f"_tokens in/out: {r['prompt_tokens']}/{r['completion_tokens']} · cost: ${r['cost_cents']/100:.4f}_")
-              total_cents += r["cost_cents"]
+              lines.append(f"_tokens in/out: {ptok}/{ctok} · cost: ${cost_cents/100:.4f}_")
               lines.append("")
 
           lines.append("---")
-          lines.append(f"_Total review cost: **${total_cents/100:.4f}**. A/B roster configured in `.github/workflows/cto-review.yml`._")
+          lines.append(f"_Total review cost: **${cost_cents/100:.4f}**. Reviewer: {MODEL_DISPLAY}. Roster configured in `.github/workflows/cto-review.yml`._")
 
           with open("/tmp/review-body.md", "w") as f:
               f.write("\n".join(lines))
           with open(os.environ["GITHUB_OUTPUT"], "a") as f:
-              f.write(f"added_cents={int(round(total_cents))}\n")
+              f.write(f"added_cents={int(round(cost_cents))}\n")
               f.write(f"skipped=0\n")
               f.write(f"primary_verdict={heading_verdict}\n")
           PY
 
       - name: Post PR review (formal APPROVE / REQUEST_CHANGES / COMMENT)
-        # Uses primary model's verdict as the formal event. Falls back to COMMENT
-        # if the primary model failed or returned something unexpected.
+        # Uses Haiku's verdict as the formal event. Falls back to COMMENT
+        # if the model failed or returned something unexpected.
         if: steps.budget.outputs.skip != 'true' && steps.review.outputs.skipped != '1'
         uses: actions/github-script@v7
         env:

.github/workflows/deploy.yml

@@ -9,29 +9,17 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  validate:
-    name: PHP Lint Gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.1'
-          coverage: none
-      - name: PHP Lint Check
-        run: |
-          set -e
-          find . -name '*.php' \
-            -not -path './vendor/*' \
-            -not -path './node_modules/*' \
-            -not -path './.git/*' \
-            -not -path './.github/*' \
-            -print0 | xargs -0 -n1 -P4 php -l > /dev/null
+  ci:
+    name: CI Gate (reusable)
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: write
+    secrets: inherit
 
   deploy:
     name: Deploy (shared pipeline)
-    needs: validate
-    uses: peptiderepo/peptide-e2e/.github/workflows/deploy-app.yml@main
+    needs: ci
+    uses: peptide-repo/peptide-e2e/.github/workflows/deploy-app.yml@main
     with:
       target_path: wp-content/plugins/prautoblogger
     secrets: inherit

ARCHITECTURE.md

@@ -2,6 +2,8 @@
 
 > **Cross-app context:** decisions that affect multiple plugins (Cloudflare AI Gateway routing, OpenRouter account sharing, the interface pattern, image-generation stack, social distributor choice) are recorded in `Peptide Repo CTO/docs/engineering/decisions/`. The incident runbook for cross-app failure modes is at `Peptide Repo CTO/docs/engineering/INCIDENT-RUNBOOK.md`. Engineer PRAutoBlogger should read both before making decisions that cross plugin boundaries.
 
+> **App-local decisions:** choices that affect only this plugin are recorded in [`docs/adr/`](docs/adr/README.md) — a per-repo numbered log (0001, 0002, …). Read `docs/adr/README.md` for the index. The routing rule and required template live centrally in `Peptide Repo CTO/docs/engineering/ADR-PROCESS.md`.
+
 PRAutoBlogger is a WordPress plugin that monitors social media (starting with Reddit) for recurring questions, complaints, and comparisons in a configured niche, uses LLM agents (via OpenRouter) to generate high-quality blog articles from those insights, runs them through a chief editor agent for quality review, and auto-publishes them on a configurable daily schedule. All collected data and generation metrics are stored for a self-improvement feedback loop.
 
 ---
@@ -121,17 +123,19 @@ prautoblogger/
 │   │   ├── admin.css                  # Admin page styles (wp-admin conventions)
 │   │   ├── board.css                  # Kanban board styles -- warm editorial palette (v0.19.0)
 │   │   ├── dossier.css                # Article dossier page styles: verdict pills, cost receipt, trace toggle (v0.19.2)
+│   │   ├── dossier-edit.css           # M3 edit/re-run layer: chips, edit panel, image grid, spend warning (v0.20.0)
 │   │   └── posts-widget.css           # Frontend posts widget styles (uses theme CSS vars)
 │   └── js/
 │       ├── admin.js                   # Admin page interactivity (vanilla JS / Alpine.js)
 │       ├── board.js                   # Board poller: AJAX poll + DOM updates + backoff (v0.19.0)
 │       ├── dossier.js                 # Per-stage raw-trace toggle: aria-expanded / aria-controls (v0.19.2)
+│       ├── dossier-edit.js            # M3 edit/re-run actions + stage-status polling (queued -> pickup -> result) (v0.20.0)
 │       └── posts-widget.js            # React component for frontend post cards (wp.element)
 │
 ├── includes/
-│   ├── class-prautoblogger.php        # Main orchestrator — registers all hooks, delegates execution (258 lines; split v0.19.2)
+│   ├── class-prautoblogger.php        # Main orchestrator — registers all hooks, delegates execution (split v0.19.2)
 │   ├── class-db-migrations.php        # DB migration methods extracted from class-prautoblogger.php (v0.19.2 split, binding 1)
-│   ├── class-pipeline-schema-installer.php # v0.18.0 substrate tables (prompts, run_sources, run_decisions, runs, run_stages)
+│   ├── class-pipeline-schema-installer.php # Pipeline substrate tables (prompts, run_sources, run_decisions, runs, run_stages, stage_inputs)
 │   ├── class-migrate-prompt-seed-v0180.php # One-shot v0.18.0 prompt-registry seed migration
 │   ├── 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
@@ -148,6 +152,9 @@ prautoblogger/
 │   │   ├── class-dossier-page.php     # Article dossier admin page: options.php-parent hidden-page, priority 12, enqueue, nonce (v0.19.3)
 │   │   ├── class-dossier-data-assembler.php # 5-query view-model builder: runs+stages+gen_log+decisions+meta (v0.19.2)
 │   │   ├── class-dossier-gen-log-query.php  # Dossier gen_log queries: per-stage cost receipt + raw trace (v0.19.2)
+│   │   ├── class-dossier-actions.php        # M3 AJAX: save fork / queue replay / queue rebuild / stage-status poll (v0.20.0)
+│   │   ├── class-dossier-rerun-panel-data.php # M3 per-stage affordance + spend view model (v0.20.0)
+│   │   ├── class-dossier-image-data.php     # F3: post's pipeline attachments via _prautoblogger_image_role (v0.20.0)
 │   │   ├── class-admin-page.php       # Main settings page (tabbed SaaS-style UI)
 │   │   ├── class-settings-fields.php  # Declarative settings: sections + core fields (API/Models/Content/Sources)
 │   │   ├── class-settings-fields-extended.php # Operational fields: schedule, publishing, display, analytics, images
@@ -194,7 +201,15 @@ prautoblogger/
 │   │   ├── class-run-state.php        # runs-table ledger + lifecycle row (ceiling/reserved/settled, pins, status)
 │   │   ├── class-cost-governor.php    # Per-run reserve-before-call enforcement (atomic conditional UPDATE)
 │   │   ├── class-cost-ceiling-exception.php # Thrown on ceiling breach (run already halted)
-│   │   ├── class-run-stage-state.php  # Per-run per-stage state machine (idempotent resume, output snapshots)
+│   │   ├── class-run-stage-state.php  # Per-run per-stage state machine: read API + thin write proxies (split v0.20.0)
+│   │   ├── class-run-stage-writes.php # Pipeline-path writes (start/done/fail; done clears stale) — extracted v0.20.0
+│   │   ├── class-run-stage-rerun-state.php # M3 operator-action mutations: restart/mark_stale/demote (v0.20.0)
+│   │   ├── class-stage-input-store.php # INSERT-only stage_inputs store: edit forks + idea seeds (v0.20.0)
+│   │   ├── class-rerun-eligibility.php # M3 policy gates: frozen posts, editable stages, chain order (v0.20.0)
+│   │   ├── class-stage-replay.php     # M3 governed single-stage replay from a fork body (v0.20.0)
+│   │   ├── class-rerun-executor.php   # M3 cron handlers: replay + rebuild jobs (v0.20.0)
+│   │   ├── class-rerun-job-support.php # M3 queue/lock/budget/status-transient plumbing (v0.20.0)
+│   │   ├── class-request-recorder.php # B1: process-scoped outbound request-body stash -> generation_log.request_json (v0.20.0)
 │   │   ├── class-run-reaper.php       # Stuck-run sweep + audit-payload retention (rides the #19 cron)
 │   │   ├── class-audit-writer.php     # run_sources / run_decisions insert layer
 │   │   ├── class-pipeline-status.php  # Status-transient + summary helpers (extracted from runner/worker)
@@ -252,6 +267,10 @@ prautoblogger/
 │   └── admin/
 │       ├── board-page.php             # Kanban board template (4-column editorial layout) (v0.19.0)
 │       ├── dossier-page.php           # Article dossier: two-column layout, sidebar, stage sections (v0.19.2)
+│       ├── dossier-stage-section.php  # Stage section partial: output, raw trace, M3 chips + rerun footer
+│       ├── dossier-edit-panel.php     # M3 per-stage edit panel: message textareas, fork info, spend strip (v0.20.0)
+│       ├── dossier-log-stage-section.php # F3 log-only stage sections incl. image attachment grid (v0.20.0)
+│       ├── dossier-sidebar-cards.php  # M3 sidebar: run spend (guardrail 4) + models/pv consolidation (F2) (v0.20.0)
 │       ├── dossier-stage-section.php  # Per-stage block: rendered output + raw-trace toggle + cost receipt (v0.19.2)
 │       ├── metabox-dossier-link.php   # Slim post metabox: "View generation dossier →" link (v0.19.2)
 │       ├── settings-page.php          # Settings page template (tabbed sidebar layout)
@@ -532,6 +551,7 @@ dropped on uninstall.
 | verdict        | VARCHAR(50) | e.g. 'approved', 'revised', 'rejected', 'halted' |
 | rationale      | TEXT        | Decision rationale (nullable)                 |
 | citation_score | FLOAT       | Nullable until the Phase-2 editorial loop computes it |
+| human_modified | TINYINT(1)  | v0.20.0 — decision derives from a human-edited input (set on replay of the stage, or on decisions recorded while rebuilding a human-modified item) |
 | created_at     | DATETIME    | Row creation time                             |
 
 - INDEX: `run_id`
@@ -568,12 +588,38 @@ dropped on uninstall.
 | attempt     | SMALLINT UNSIGNED | Re-entry counter                                 |
 | cost_usd    | DECIMAL(10,6)   | Cost attributed to the stage                       |
 | meta_json   | LONGTEXT        | Stage output snapshot — lets resume reuse a done stage instead of re-charging it (payload pruned on the retention cron) |
+| human_modified | TINYINT(1)   | v0.20.0 — set (sticky, never cleared) when an edited input fork enters execution for this row (CPO guardrail 2) |
+| stale       | TINYINT(1)      | v0.20.0 — upstream changed after this row completed; row STAYS 'done' so resume never silently re-runs it; cleared only by a fresh done() |
 | started_at  | DATETIME        | First entry                                        |
 | updated_at  | DATETIME        | Last transition                                    |
 | finished_at | DATETIME        | Set on done/failed (nullable)                      |
 
 - UNIQUE: `run_id, stage, agent_role, item_key` (the idempotency key) · INDEX: `status, updated_at`
 
+##### `prautoblogger_stage_inputs` — immutable input-version store (v0.20.0, db 1.3.0)
+
+| Column       | Type            | Description                                      |
+|--------------|-----------------|--------------------------------------------------|
+| id           | BIGINT UNSIGNED | Auto-increment PK                                |
+| run_id       | VARCHAR(36)     | Pipeline run UUID                                |
+| stage        | VARCHAR(50)     | Stage name ('' for idea seeds)                   |
+| agent_role   | VARCHAR(50)     | Stage row agent role                             |
+| item_key     | VARCHAR(64)     | Article scope                                    |
+| version      | INT UNSIGNED    | Monotonic per scope; **rows are INSERT-only** — edits create the next version, originals are never overwritten |
+| source       | VARCHAR(20)     | 'human' (edit fork) or 'seed' (Article_Idea payload persisted at worker start) |
+| request_json | LONGTEXT        | Fork body / idea JSON. Human fork bodies pruned by the retention cron after R days; seed rows (~1KB) kept |
+| author       | VARCHAR(100)    | WP user login, or 'pipeline' for seeds           |
+| created_at   | DATETIME        | Row creation time                                |
+
+- UNIQUE: `run_id, stage, agent_role, item_key, version` · INDEX: `run_id`
+- The ORIGINAL executed input of a stage is `generation_log.request_json` (B1) — it is
+  never copied or modified here; forks are the edit history (CPO guardrail 1).
+
+**db version note:** `PRAUTOBLOGGER_DB_VERSION` moved 1.1.0 → 1.3.0 in v0.20.0. The
+constant never actually carried the "db 1.2.0" this document used as shorthand for the
+v0.18.0 substrate; 1.3.0 leapfrogs the phantom value so the version-compare self-healing
+migration fires exactly once everywhere.
+
 ### WordPress Options (`wp_options`)
 
 All prefixed with `prautoblogger_`:
@@ -964,6 +1010,70 @@ the file `class-db-migrations.php`. Explicit loading is the canonical pattern fo
 whose names do not round-trip cleanly through the kebab converter. `class-prautoblogger.php`
 uses the same pattern (also explicitly required in `prautoblogger.php`).
 
+### #24: Edit + single-step re-run under CPO guardrails (v0.20.0, db 1.3.0, June 2026)
+
+Phase 2 admin M3 (design contract: cpo seq 8 Proposal C + the five guardrails of the
+edit+rerun delta ruling; decision `2026-06-12-admin-redesign-direction-c.md`).
+
+**B1 — request_json persistence.** The OpenRouter provider stashes every outgoing chat
+request BODY in the process-scoped `PRAutoBlogger_Request_Recorder` (the Run_Context
+pattern) right after `build_body()`; `Cost_Tracker::log_api_call()` consumes it into
+`generation_log.request_json`. Consume-once + overwrite-on-record means a stale body can
+never attach to an unrelated row; recording happens pre-dispatch so error rows carry the
+request too. Authorization can never be recorded: headers are built separately
+(`build_headers()`) and `build_body()` copies only whitelisted option keys. Retention
+rides the existing `prautoblogger_request_json_retention_days` prune unchanged.
+
+**Two re-run primitives, both chained-cron (never synchronous):** the dossier AJAX layer
+(`Dossier_Actions`) only validates + queues; the cron handlers (`Rerun_Executor`)
+re-validate eligibility UNDER the generation lock before mutating anything.
+
+1. **Replay** — one governed chat call from the latest edited input fork
+   (`stage_inputs`, INSERT-only versions). `Stage_Replay::options_from_body()` is the
+   exact inverse of `build_body()`+`apply_reasoning_budget()` (reasoning headroom
+   subtracted back out; reasoning pinned explicitly so global-setting drift cannot
+   reshape a replay). The call goes through `send_chat_completion`, so the cost
+   governor reserves against the SAME run ledger row (guardrail 4), with the normal
+   retry/empty-completion machinery. Output lands in the stage's run_stages snapshot —
+   the same place downstream rebuilds read from.
+2. **Rebuild ("re-run from here")** — demotes the target + downstream chain stages to
+   `pending` and re-enters `Article_Worker` with the idea reconstructed from the stored
+   seed (`stage_inputs`, source='seed', persisted at worker start because re-deriving
+   the idea from post fields could break the item_key hash and duplicate a post).
+   Upstream done stages are reused (never re-charged); demoted stages rebuild their
+   prompts from CURRENT upstream snapshots — this is how an edit propagates downstream.
+
+**Stale is a column, not a status.** A stale stage stays `done`, so
+resume-without-recharge logic can never silently re-run it — guardrail 3 (no silent
+auto-rerun; each downstream re-run is a deliberate operator action) holds by
+construction. Only `Run_Stage_Writes::done()` clears `stale`; only
+`Run_Stage_Rerun_State` (operator-action paths) may demote a done row. `human_modified`
+is sticky for the life of the run (set when a fork enters execution, surfaced as header/
+stage chips in the dossier, a board-card chip, and a Review Queue link-chip — the
+run-list-level visibility the product AC requires).
+
+**Run reopening.** `Run_State::reopen()` is the atomic terminal→running gate for re-run
+spend; it RE-SNAPSHOTS `ceiling_usd` from the current setting (a deliberate re-run
+adopts the operator's current per-run policy, exactly like a new run) and never resets
+reserved/settled — re-runs are new spend on the same run. Handlers always restore a
+terminal status (or record failed/halted) so the run-reaper's stuck-running sweep stays
+meaningful; jobs hold the global generation lock and ride the M1 status transient, so
+board/dossier polling shows queued → pickup → result and the existing R2/R3 orphan
+recovery covers dead re-run processes unchanged.
+
+**Eligibility (guardrail 5).** Posts with status publish/future/private freeze their
+run server-side (and `Publisher` refuses to touch them: re-run output refreshes only
+UNPUBLISHED posts, preserving their status — re-runs never publish). Editable stages
+are the item-scoped writer chat stages (outline/draft/polish); review/publish re-run
+via rebuild (their inputs are derived), run-level and image stages are excluded with
+visible in-UI reasons. Phase-2b stages inherit the mechanism when they exist as
+item-scoped chat calls.
+
+**F2/F3 (QA M2):** the sidebar consolidates per-stage model/pv/role; image (and other
+log-only) stages render from generation_log + the `_prautoblogger_image_role`
+attachment set — wiring the dossier to real data was deliberately chosen over teaching
+the live image pipeline to write run_stages (that belongs to the Phase-2b restructure).
+
 ## Cross-System LLM Budget Coordination
 
 PRAutoBlogger and Peptide News both call OpenRouter and may share a single API key / billing account. Their combined spend should be considered when setting per-plugin budgets.
@@ -976,3 +1086,66 @@ PRAutoBlogger and Peptide News both call OpenRouter and may share a single API k
 **Important:** If your OpenRouter account has a global spending limit, set each plugin's budget to less than half the total. PRAutoBlogger will hard-stop when its budget is exhausted, but Peptide News currently has no budget enforcement — a spike in news fetches could consume shared quota.
 
 **Future improvement:** A shared `wp_options` key (e.g., `ecosystem_monthly_llm_budget`) that both plugins read, with each plugin reserving its allocation on startup. This requires coordination at the ecosystem level and is tracked as a medium-term goal.
+
+## §25 Chained-Cron Checkpoint Generation Path (v0.21.0, M4)
+
+### Problem
+
+Hostinger shared hosting kills PHP background processes after ~120 s. The former
+`on_manual_generation()` path in `Executor` ran the complete orchestrate +
+generate pipeline in a single PHP process — meaning a host kill mid-run left the
+generation lock held, the run row stuck in `running`, and partially-generated
+articles orphaned with no status broadcast.
+
+### Solution: Two-Tick Checkpoint Machine
+
+`PRAutoBlogger_Generation_Checkpoint_Runner` (v0.21.0) splits the pipeline into
+independent cron ticks, each of which completes well within Hostinger's limit:
+
+| Tick | WP-Cron action | What happens |
+|------|---------------|-------------|
+| 1 | `prautoblogger_gen_orchestrate` | Collect sources → analyze → score ideas. Serialize ideas to `prautoblogger_article_queue` option. Schedule Tick 2. |
+| 2..N | `prautoblogger_gen_tick` | Pop ONE idea from queue. Call `Article_Worker::generate()`. Persist updated queue. Reschedule next Tick, or finalize. |
+
+If the host kills any tick:
+- The idea queue is persisted (option survived the crash).
+- The next CRON run picks up naturally (no orphan).
+- `Run_Reaper` reclaims truly stuck runs via its daily sweep.
+
+### Entry Points
+
+| Caller | Path |
+|--------|------|
+| Board "New Article" button | AJAX `prautoblogger_generate_now` → `Generation_Status_Poller::on_ajax_generate_now()` → schedules `prautoblogger_manual_generation` → `Executor::on_manual_generation()` → `kick_off()` |
+| WP-CLI (async) | `wp prautoblogger generate` → `WP_CLI_Commands::generate_command()` → `kick_off()` |
+| WP-CLI (sync / VPS) | `wp prautoblogger generate --sync` → `WP_CLI_Commands::run_sync()` → `set_sync_mode(true)` → `on_orchestrate_tick()` → tick loop `on_generate_tick()` (×N) → `set_sync_mode(false)` |
+| Old cron hook (retained) | `prautoblogger_manual_generation` → `Executor::on_manual_generation()` → `kick_off()` |
+
+### SSH Workaround Retirement
+
+The former `wp eval 'do_action("prautoblogger_manual_generation")'` workaround
+fired `on_manual_generation()` synchronously in the CLI PHP process, bypassing:
+- Nonce/capability checks (running as CLI user, not WP user)
+- Cron-based loopback spawning
+- Per-process time limits
+
+This path is retired. `Executor::on_manual_generation()` now delegates immediately
+to `Generation_Checkpoint_Runner::on_orchestrate_tick()` (the Tick 1 handler),
+which acquires the lock and runs orchestration within its own process. The
+`wp prautoblogger generate` WP-CLI command provides the supported CLI path.
+
+### Key State
+
+| Store | Key | Contents |
+|-------|-----|---------|
+| DB option | `prautoblogger_article_queue` | `{run_id, ideas[], results{}}` — persisted across ticks |
+| DB option | `prautoblogger_checkpoint_run_id` | Current run UUID (for finalize/cleanup paths) |
+| Transient | `prautoblogger_generation_status` | Status broadcast (polling by board/dossier JS) |
+| DB | `prautoblogger_runs` | Per-run ledger with status, cost ceiling |
+
+### Budget / Halt Contract
+
+`Cost_Tracker::is_budget_exceeded()` is checked at the START of Tick 1 and each
+generate tick. A halted run (`Run_State::get_status() = 'halted'`) causes the
+generate tick to abort without calling `Article_Worker`, clean up the queue, and
+release the lock — same guarantee as `Pipeline_Runner`'s queued-article path.

CHANGELOG.md

@@ -5,6 +5,234 @@ 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/).
 
+## [Unreleased - Internal]
+
+### Internal
+- ADR log scaffolded: `docs/adr/` created as the app-local decision log for this plugin; `docs/adr/README.md` is the index; ADR-0001 documents the v0.16.0 editorial illustration image-style pivot. `ARCHITECTURE.md` updated to point to the folder. No runtime changes; docs-only.
+- CI constants guard (`scripts/check-constants.php`): new required CI step (`Check PRAUTOBLOGGER_* constants`) fails the build when any `PRAUTOBLOGGER_*` constant referenced in shipped plugin PHP is neither defined in `prautoblogger.php` nor `defined()`-guarded at the reference site. Prevents a recurrence of the v0.19.0 admin-500 regression class.
+
+## [0.22.1] - 2026-06-22
+
+### Added
+- **`wp prautoblogger generate --sync`** (VPS orchestrator mode): runs the full
+  checkpoint pipeline synchronously in the calling process — acquires lock, calls
+  `on_orchestrate_tick()` in-process, then loops `on_generate_tick()` until the
+  queue is empty or a terminal state is reached (max 20 ticks). Exits 0 on
+  success with a JSON summary line; exits 1 on error. Designed to be called from
+  the Coolify VPS over a held-open SSH session, where Hostinger's ~10-min
+  background-process kill does not apply.
+
+### Fixed
+- **`$sync_mode` guard in `Generation_Checkpoint_Runner::on_generate_tick()`**:
+  when running under `--sync`, the internal `wp_schedule_single_event()` +
+  `fire_cron_now()` reschedule is suppressed so the VPS's external loop cannot
+  race with a competing background wp-cron tick. Existing async (cron/AJAX) paths
+  are unaffected.
+- **Reaper timezone fix** in `Run_Reaper::sweep_stuck_stages()` and
+  `sweep_stuck_runs()`: `$cutoff` was computed with `gmdate()` (UTC) while
+  `updated_at` is stored via `current_time('mysql')` (server local time, UTC+8).
+  Changed to `wp_date()` so the cutoff respects the site timezone. On this host
+  the 8-hour delta could suppress reaping of a same-day-stalled run; the 44h-old
+  run `ee6e7d91` was already far outside the threshold and unaffected.
+- **Scoped self-heal migration** in `DB_Migrations`: restores the low-stakes
+  maintenance cron events (`prautoblogger_reap_orphan_research_rows`,
+  `prautoblogger_collect_metrics`, `prautoblogger_sync_runware_models`) that
+  vanished after the 06-15 deploy cycle. **`prautoblogger_daily_generation` is
+  deliberately NOT re-registered** — the VPS systemd timer owns generation
+  scheduling as of v0.22.1. Note: wp-cron reliability on this Hostinger host is
+  suspect (background PHP killed ~10 min); maintenance crons are low-stakes and
+  acceptable on this transport; generation is not.
+- **Sync-mode guard tests** (QA NF-1 remediation 2026-06-23): moved sync-mode
+  tests to `GenerationCheckpointRunnerSyncModeTest.php`; fixed
+  `test_orchestrate_tick_in_sync_mode_does_not_schedule_background_event` to
+  return >= 1 idea from `orchestrate_only()` so execution reaches the sync guard
+  at line ~181 (was vacuous -- previous stub returned `[]` causing early return);
+  added `test_generate_tick_sync_mode_suppresses_reschedule` for the
+  `on_generate_tick()` guard; async regression test preserved in same file.
+- **Root `CONTEXT.md`**: created domain glossary (run/run_stages/checkpoint/
+  idea-queue/Generation_Lock) and execution mode comparison (async wp-cron vs.
+  `--sync` VPS).
+- **`ARCHITECTURE.md` SS25**: added `WP-CLI (sync / VPS)` row to Entry Points table.
+
+## [0.22.0] - 2026-06-16
+
+### Changed
+- **CI adopted estate standard (reusable workflow)**: `ci.yml` is now a thin
+  caller of `peptiderepo/peptide-e2e/.github/workflows/ci.yml@main` with
+  `tests: brain-monkey`. Removes duplicate per-repo lint, PHPCS, and PHPUnit
+  jobs (now provided by the reusable workflow). The phpcbf auto-fix commit-back
+  pattern (prautoblogger gold standard) is now the reusable implementation.
+- **Deploy gate upgraded**: `deploy.yml` no longer runs a standalone PHP-lint
+  validate job; it calls `./.github/workflows/ci.yml` (which includes the full
+  reusable suite) via `workflow_call`. This closes the gap where deploy's lint
+  gate was weaker than CI's PHPCS gate.
+- **Constants guard retained**: `check-constants` job kept as a second parallel
+  job in `ci.yml` alongside the reusable `ci` job. No regression from the
+  v0.19.0 protection.
+- **`composer.json` test script added**: `composer test` now runs
+  `vendor/bin/phpunit --testdox` (required by the reusable workflow's phpunit job).
+
+### Refactored (300-line rule compliance)
+- `PRAutoBlogger_Keyword_Extractor` (new, `core/class-keyword-extractor.php`):
+  shared keyword tokeniser extracted from `Idea_Scorer` and `Semantic_Dedup`;
+  both now delegate to `PRAutoBlogger_Keyword_Extractor::extract()`.
+- `PRAutoBlogger_Image_Aspect_Ratio` (new, `providers/class-image-aspect-ratio.php`):
+  aspect-ratio snap utility extracted from `OpenRouter_Image_Provider` and
+  `OpenRouter_Image_Batch`; both now call `PRAutoBlogger_Image_Aspect_Ratio::snap()`.
+- `PRAutoBlogger_Settings_Sanitizer` (new, `admin/class-settings-sanitizer.php`):
+  all option sanitization logic extracted from `Admin_Page::sanitize_field()`;
+  `Admin_Page` delegates via `PRAutoBlogger_Settings_Sanitizer::sanitize_field()`.
+- `PRAutoBlogger_Settings_Fields_Images` (new, `admin/class-settings-fields-images.php`):
+  image-section field definitions extracted from `Settings_Fields_Extended`;
+  `Settings_Fields_Extended::get_fields()` merges via array union.
+- `PRAutoBlogger_Runware_Validator` (new, `providers/class-runware-image-validator.php`):
+  `validate_credentials_detailed()` extracted from `Runware_Image_Provider`;
+  provider delegates via `PRAutoBlogger_Runware_Validator::validate()`.
+- `class-runware-image-batch.php`: 15 individual `phpcs:disable` lines collapsed
+  to a single grouped suppression (equivalent effect, saves 14 lines).
+- `class-open-router-image-provider.php`: `snap_aspect_ratio` private method and
+  `STANDARD_ASPECTS` constant removed (now handled by `Image_Aspect_Ratio`).
+
+## [0.21.0] - 2026-06-14
+
+### Added
+- **Board “New Article” button (Phase 2 admin M4)**. Manual generation is now
+  accessible from the kanban board (not just the Settings page). The button fires
+  the existing `prautoblogger_generate_now` AJAX action; the board status area
+  shows generation progress via the existing transient poller. Requires
+  `manage_options` capability.
+- **Chained-cron checkpoint machine** (`PRAutoBlogger_Generation_Checkpoint_Runner`).
+  Replaces the monolithic `on_manual_generation()` synchronous path with a
+  two-tick checkpoint machine so Hostinger’s PHP-process kill cannot abort a
+  mid-pipeline run:
+  - Tick 1 (`prautoblogger_gen_orchestrate`): collect → analyze → score ideas,
+    persist to `prautoblogger_article_queue` option, schedule Tick 2.
+  - Tick 2…N (`prautoblogger_gen_tick`): pop ONE idea, generate one article,
+    reschedule or finalize. Persists consumed queue BEFORE generating to prevent
+    orphan-recovery duplication on restart.
+  - Budget / halt: `Cost_Tracker::is_budget_exceeded()` checked per tick;
+    a halted run aborts all remaining ticks without calling `Article_Worker`.
+- **WP-CLI `wp prautoblogger generate` command**. Routes through the same
+  chained-cron checkpoints as the board button. Replaces the retired SSH-only
+  `wp eval 'do_action("prautoblogger_manual_generation")'` workaround.
+- **Settings-backed board pagination** (perf pass). All hardcoded LIMIT / `posts_per_page`
+  values in board queries replaced with two new settings:
+  - `prautoblogger_board_column_limit` (default 20, constant `PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT`)
+  - `prautoblogger_ideas_per_page` (default 30, constant `PRAUTOBLOGGER_DEFAULT_IDEAS_PER_PAGE`)
+- **DB indexes** (via `PRAUTOBLOGGER_DB_VERSION` → `1.4.0`):
+  - `generation_log`: `KEY run_id_post_id`, `KEY created_status` (board query + failed-cards).
+  - `analysis_results`: `KEY analyzed_type` (ideas-browser pagination + type filter).
+  - `runs`: `KEY started_at` (articles-list pagination `ORDER BY started_at DESC LIMIT n OFFSET m`).
+- **Query helper split**: `PRAutoBlogger_Ideas_Browser_Query` (new `class-ideas-browser-query.php`)
+  carries static query helpers extracted from `class-ideas-browser.php` to enforce the
+  300-line rule (CONVENTIONS §1).
+- **Guard P2s** (`scripts/check-constants.php`):
+  - Added `--self-test` mode: synthesizes a missing constant and asserts the scanner catches it.
+  - Added inline comment documenting `CONSTANTS_GUARD_WINDOW = 4`.
+  - Wired `--self-test` as a CI step after the main constants check.
+- **PHPUnit test** `tests/unit/Core/GenerationCheckpointRunnerTest.php`: tick-by-tick
+  state-machine proof (kick_off schedules only, empty queue finalizes, halted run aborts,
+  multi-idea queue pops one and reschedules).
+- **Pipeline_Status** now exports `write_initial()` and `write_error()` for the
+  checkpoint runner to set the status transient before the first cron tick fires.
+
+### Changed
+- `Executor::on_manual_generation()` now delegates to
+  `Generation_Checkpoint_Runner::on_orchestrate_tick()` instead of running the full
+  pipeline synchronously. The method body is 1 line; the synchronous path is retired.
+- `Pipeline_Runner::orchestrate_only()` added as a public wrapper exposing the private
+  `orchestrate()` method for use by `Generation_Checkpoint_Runner`.
+
+### Removed
+- **SSH-only workaround retired**: `wp eval 'do_action("prautoblogger_manual_generation")'` no
+  longer fires the pipeline synchronously in one PHP process. Use `wp prautoblogger generate`
+  instead (routes through the chained-cron checkpoint machine). See ARCHITECTURE.md §25.
+
+## [0.20.1] - 2026-06-12
+
+### Fixed
+- **Restore three bootstrap constants deleted by the v0.19.0 constants-block regression**
+  (`PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD` 0.50, `PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS` 14,
+  `PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS` 2048 — verbatim v0.18.3 values). PR #156 (v0.19.0)
+  dropped them from `prautoblogger.php`; the gap was latent because `tests/bootstrap.php` defines
+  its own fallbacks (CI green) and no exercised v0.19.x runtime path read them (prod reasoning
+  disabled). v0.20.0's activator defaults + run-state ceiling read them on the admin
+  migration path -> fatal 500 on all plugin admin pages immediately after the v0.20.0 deploy
+  (2026-06-12; front-of-site unaffected; hot-patched on prod within minutes, this commit makes
+  it canonical). Follow-up owed: CI guard asserting every referenced PRAUTOBLOGGER_* constant
+  is production-defined or defined()-guarded (maintenance thread).
+
+## [0.20.0] - 2026-06-12
+
+### Added
+- **Edit + single-step re-run (Phase 2 admin M3)** under the five CPO guardrails
+  (cpo seq 8, hard AC). From the Article Dossier, eligible stages can have their
+  input edited and re-run as QUEUED background jobs (chained-cron — the UI never
+  implies synchronous execution; board + dossier polling shows queued → pickup →
+  result).
+  - **Immutable input versions (guardrail 1).** Edits fork into the new INSERT-only
+    `prautoblogger_stage_inputs` table (monotonic versions per stage scope); the
+    executed original in `generation_log.request_json` is never overwritten. The
+    editor locks message structure (count/roles) so every fork stays replayable.
+  - **Visible human-modified audit (guardrail 2).** `run_stages.human_modified` +
+    `run_decisions.human_modified` set when an edited fork enters execution (sticky,
+    never cleared); surfaced as dossier header + stage chips, a board-card chip, and
+    decisions recorded while rebuilding a human-modified item are flagged too.
+  - **Explicit downstream invalidation (guardrail 3).** Re-running a stage marks all
+    downstream chain stages `stale` (new column — rows STAY 'done', so the resume
+    machinery can never silently auto-re-run them). Stale chips render per stage, in
+    the dossier header, and as a Review Queue warning chip linking to the dossier
+    (stale state visible at publish). Downstream re-runs are deliberate: per-stage
+    "Re-run from here" rebuilds the target + downstream from current upstream
+    snapshots via the existing worker resume path.
+  - **Cost governor applies to re-runs (guardrail 4).** Replays go through the normal
+    provider seam: reserve-before-call against the SAME run ledger row.
+    `Run_State::reopen()` re-snapshots the ceiling from the current setting and never
+    resets accumulated spend. The dossier shows a Run Spend card + per-panel spend
+    strip and warns when committed spend reaches the ceiling fraction (filterable,
+    `prautoblogger_rerun_ceiling_warn_fraction`, default 0.8).
+  - **Published posts are frozen (guardrail 5).** publish/future/private lock the run
+    server-side (not just hidden UI); `Publisher` refreshes re-run output onto
+    UNPUBLISHED posts only, preserving their status — a re-run never publishes.
+- **B1 — `request_json` persisted on every chat LLM call** (QA M2 F1). The provider
+  records the outgoing request BODY pre-dispatch (process-scoped recorder, consume-once);
+  `log_api_call()` writes it to the row. Authorization headers can never be recorded
+  (built separately; body keys whitelisted — covered by tests). Retention rides the
+  existing `prautoblogger_request_json_retention_days` prune; the dossier raw-trace
+  "Request payload" section now renders for new runs.
+- **Idea seeds.** `Article_Worker` persists the exact `Article_Idea` payload once per
+  item (stage_inputs, source='seed') so re-run-from-here reconstructs the precise idea
+  (re-deriving from post fields could break the item-key hash and duplicate a post).
+- **Dossier sidebar consolidation (QA M2 F2).** New "Models & Prompts" card: per-stage
+  model + prompt version + agent role at a glance, plus the "Run Spend" card.
+- **Image sections wired to real data (QA M2 F3).** image_a/image_b (and every
+  log-only stage: llm_research, image_prompt_rewrite, …) now render from their actual
+  generation_log rows, with the post's pipeline attachments (featured/og/square via
+  `_prautoblogger_image_role`) shown as an image grid — chosen/featured highlighted.
+- **Schema (db 1.3.0).** `run_stages` + `human_modified`/`stale`; `run_decisions` +
+  `human_modified`; new `stage_inputs` table. dbDelta-idempotent via the standard
+  self-healing migration path (admin_init + cron init); half-migrated sites degrade
+  gracefully (done() retries the legacy statement; M3 features no-op until migrated).
+  Uninstall drops the new table and clears the two new cron hooks.
+
+### Changed
+- **`PRAutoBlogger_Run_Stage_State` split** (300-line cap, M2 pattern): pipeline write
+  bodies moved verbatim to `Run_Stage_Writes` (public API unchanged via thin proxies);
+  operator-action mutations (restart / mark_stale / demote_to_pending) isolated in
+  `Run_Stage_Rerun_State` — the ONLY code allowed to demote a done row. `done()` now
+  clears `stale` on fresh output.
+- **Dossier is item-scoped** (M2 correctness fix): stage rows filter to THIS post's
+  item (idea-hash meta), and gen_log rows linked to OTHER posts of a multi-article run
+  are excluded (unlinked run-level rows are kept).
+- **`Publisher` idempotency short-circuit** now refreshes existing UNPUBLISHED posts
+  with re-run content (title/content/verdict meta; status untouched) instead of
+  silently discarding regenerated output. Published posts remain untouched.
+- Review Queue rows show a stale-stages warning chip linking to the dossier; board
+  cards show a "Human-modified" chip (single batched query, no N+1).
+
+### Fixed
+- Dossier "Request payload" raw trace was always empty (request_json never populated —
+  QA M2 F1); image sections always rendered the absent state (QA M2 F3).
 ## [0.19.4] - 2026-06-12
 
 ### Added
@@ -293,7 +521,6 @@ and this project uses [Semantic Versioning](https://semver.org/).
   the catalog + OpenRouter static list. Breaking change: callers that expect a
   specific static list should note the new dynamic Runware side.
 
-
 ### Fixed
 - Runware image generation now correctly uses the admin-selected model instead
   of silently falling back to FLUX.1 schnell (runware:100@1) for all non-schnell
@@ -393,7 +620,6 @@ and this project uses [Semantic Versioning](https://semver.org/).
 ### Fixed
 - Image prompt builder now properly delegates to static parser methods
 
-
 ### Fixed
 - **Opik autoloader gap** — `class-autoloader.php` listed `services/` as a scan directory but not `services/opik/`, where all four Opik classes live (`Opik_Client`, `Opik_Trace_Context`, `Opik_Span_Queue`, `Opik_Dispatcher`). Composer's classmap (used in PHPUnit) covers `includes/` recursively so tests passed, but the WordPress runtime autoloader would fatal on first Opik class reference in production. Added `services/opik/` to the scan list.
 

CONTEXT.md

@@ -0,0 +1,77 @@
+# PRAutoBlogger — Domain Glossary
+
+Quick reference for the generation pipeline domain model. For full design rationale
+see `ARCHITECTURE.md` (§21–§25) and `CONVENTIONS.md`.
+
+---
+
+## Core Domain Terms
+
+**run**
+A single end-to-end article generation cycle: orchestrate → generate idea(s) →
+finalize. Represented as a row in `wp_prautoblogger_runs` (status, cost ceiling,
+timestamps). One run may produce multiple articles if the daily idea-count > 1.
+
+**run\_stages** (`wp_prautoblogger_run_stages`)
+Sub-steps within a run (research, analysis, generation, publish). Each stage has
+its own status and can be replayed independently via `Rerun_Executor`. Generation
+checkpoint runs populate stages as Article_Worker progresses.
+
+**checkpoint**
+The persistence boundary between pipeline ticks. After each tick the idea queue
+and run state are written to `wp_options` so a process kill cannot lose work. The
+next tick reads the queue option and continues. See §25 of ARCHITECTURE.md.
+
+**idea queue** (`prautoblogger_article_queue` option)
+Serialized array of `Article_Idea` objects written by `on_orchestrate_tick()` and
+consumed one-at-a-time by successive `on_generate_tick()` calls. Deleted on
+finalize or cleanup.
+
+**Generation\_Lock** (`wp_prautoblogger_generation_lock` or `wp_options`)
+DB mutex that prevents two concurrent runs. Acquired at the start of
+`on_orchestrate_tick()`, released by `Helpers::finalize()` or on error/halt.
+
+---
+
+## Execution Modes
+
+### Async (wp-cron driven)
+
+Default path for the Board "New Article" button and the plain
+`wp prautoblogger generate` WP-CLI command.
+
+1. `kick_off()` schedules `prautoblogger_gen_orchestrate` and calls `fire_cron_now()`.
+2. `on_orchestrate_tick()` runs in a background PHP process, schedules
+   `prautoblogger_gen_tick`, and calls `fire_cron_now()` to spawn the next process.
+3. Each `on_generate_tick()` spawns the next until the queue drains.
+
+Limitation: Hostinger kills background PHP processes at ~10 min. Orchestrate tick
+(LLM-free) and individual generate ticks (one LLM call each) are both well within
+this limit; the checkpoint design is the mitigation.
+
+### Sync (VPS-driven / `--sync`)
+
+Used by the Coolify KVM8 VPS systemd timer via `infra/vps/orchestrate-generation.sh`
+in `peptide-e2e`. Introduced v0.22.1.
+
+1. `run_sync()` sets `Generation_Checkpoint_Runner::$sync_mode = true`.
+2. Calls `on_orchestrate_tick()` **in-process** (no background spawn).
+3. Loops calling `on_generate_tick()` directly until queue empty or terminal state.
+4. `$sync_mode = true` suppresses all `wp_schedule_single_event` +
+   `fire_cron_now` calls inside both tick methods, preventing a competing
+   background cron chain from forming in parallel.
+
+The VPS SSH session is held open; the process is not subject to Hostinger's
+background-kill constraint.
+
+---
+
+## Table Shorthand
+
+Throughout the codebase `wp_prautoblogger_*` tables are referenced by their
+`$wpdb->` property names (e.g. `$wpdb->prab_runs`, `$wpdb->prab_run_stages`).
+Full table names are defined in `class-activator.php`.
+
+---
+
+*See also: `ARCHITECTURE.md` §25 (checkpoint design), `CONVENTIONS.md` (coding rules).*

INFORMATION-ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# Information Architecture — PRAutoBlogger
+
+Auto-generated index of all admin surfaces, data flows, and integrations.
+Maintained per DoD v1.1.0 (same-PR update rule).
+
+---
+
+## Admin Pages
+
+| Slug | Class | Template | Purpose |
+|------|-------|----------|---------|
+| `prautoblogger-settings` | `PRAutoBlogger_Admin_Page` | `admin-page.php` | Main settings (schedule, models, budget, board limits) |
+| `prautoblogger-board` | `PRAutoBlogger_Board_Page` | `board-page.php` | Kanban board: Generating / Failed / In Review / Published columns. New Article button (v0.21.0). |
+| `prautoblogger-articles` | `PRAutoBlogger_Articles_Page` | `articles-page.php` | Paginated list of all articles/runs |
+| `prautoblogger-dossier` | `PRAutoBlogger_Dossier_Page` | `dossier-page.php` | Per-article generation log + stage edit/re-run (M3) |
+| `prautoblogger-ideas` | `PRAutoBlogger_Ideas_Browser` | `ideas-browser.php` | Analysis results browser with per-idea generation |
+| `prautoblogger-activity` | `PRAutoBlogger_Activity_Page` | `activity-page.php` | Cost + generation activity log |
+
+---
+
+## Generation Entry Points (v0.21.0)
+
+```
+Board "New Article" button
+  └─ AJAX prautoblogger_generate_now
+       └─ Generation_Status_Poller::on_ajax_generate_now()
+            └─ schedules prautoblogger_manual_generation cron
+                 └─ Executor::on_manual_generation()
+                      └─ Generation_Checkpoint_Runner::on_orchestrate_tick()  ← Tick 1
+                           └─ schedules prautoblogger_gen_tick
+                                └─ Generation_Checkpoint_Runner::on_generate_tick()  ← Tick 2..N
+
+WP-CLI: wp prautoblogger generate
+  └─ WP_CLI_Commands::generate_command()
+       └─ Generation_Checkpoint_Runner::kick_off()
+            └─ schedules prautoblogger_gen_orchestrate
+                 └─ Generation_Checkpoint_Runner::on_orchestrate_tick()  ← Tick 1
+
+Daily auto-generation cron
+  └─ prautoblogger_daily_generation
+       └─ Executor::on_cron_run()
+            └─ Pipeline_Runner::run()  (legacy synchronous path — runs in a single PHP process)
+```
+
+---
+
+## Database Tables
+
+| Table | DB Version | Purpose |
+|-------|-----------|---------|
+| `prautoblogger_sources` | 1.0.0 | Collected Reddit/RSS source content |
+| `prautoblogger_analysis_results` | 1.0.0 | Scored article ideas |
+| `prautoblogger_generation_log` | 1.0.0 | Per-LLM-call log (cost, tokens, status) |
+| `prautoblogger_runs` | 1.0.0 | Per-run ledger (status, ceiling_usd) |
+| `prautoblogger_run_stages` | 1.2.0 | Per-stage state for M3 re-run |
+| `prautoblogger_stage_inputs` | 1.3.0 | Immutable input versions for stage edits (M3) |
+| `prautoblogger_run_decisions` | 1.2.0 | Editorial decisions per run |
+
+DB version history: 1.0→1.1 (schema normalisation), 1.1→1.2 (M2 dossier), 1.2→1.3 (M3 stage inputs), 1.3→1.4 (M4 indexes).
+
+---
+
+## Key Options
+
+| Option | Type | Default | Purpose |
+|--------|------|---------|---------|
+| `prautoblogger_board_column_limit` | int | 20 | Max cards per board column |
+| `prautoblogger_ideas_per_page` | int | 30 | Ideas browser page size |
+| `prautoblogger_article_queue` | array | — | Checkpoint queue (run_id + ideas + results) |
+| `prautoblogger_checkpoint_run_id` | string | — | Current run UUID for Tick 2..N finalize path |
+| `prautoblogger_db_version` | string | — | Installed schema version (triggers dbDelta on mismatch) |
+
+---
+
+## WP-CLI Commands
+
+| Command | Since | Description |
+|---------|-------|-------------|
+| `wp prautoblogger generate` | 0.21.0 | Queue article generation via chained-cron checkpoints |
+| `wp prautoblogger opik:eval` | 0.12.0 | Trigger Opik eval run |
+
+---
+
+*Last updated: v0.21.0 (2026-06-14)*

assets/css/dossier-edit.css

@@ -0,0 +1,240 @@
+/**
+ * PRAutoBlogger dossier — edit + re-run styles (M3, v0.20.0).
+ * Extends dossier.css (kept separate: dossier.css predates the
+ * 300-line discipline and is not grown further).
+ */
+
+/* ── Audit chips (stale / human-edited / attempt) ─────────────────── */
+.prab-chip {
+	display: inline-block;
+	padding: 2px 8px;
+	border-radius: 10px;
+	font-size: 11px;
+	font-weight: 600;
+	line-height: 1.6;
+	vertical-align: middle;
+}
+
+.prab-chip--stale {
+	background: #fcf0e4;
+	color: #8a4a0b;
+	border: 1px solid #e8c9a8;
+}
+
+.prab-chip--human {
+	background: #e9f2f4;
+	color: #1b5e6b;
+	border: 1px solid #b8d8de;
+}
+
+.prab-chip--attempt {
+	background: #f0f0f1;
+	color: #50575e;
+	border: 1px solid #dcdcde;
+}
+
+.prab-chip--chosen {
+	background: #edf7ed;
+	color: #1e6b2e;
+	border: 1px solid #b9dfc0;
+}
+
+.prab-chip--header {
+	margin-left: 6px;
+	font-size: 12px;
+}
+
+.prab-stage--stale {
+	border-left: 3px solid #d98c2b;
+}
+
+/* ── Stage footer actions ─────────────────────────────────────────── */
+.prab-stage-rerun-footer {
+	display: flex;
+	align-items: center;
+	gap: 10px;
+	flex-wrap: wrap;
+	margin-top: 12px;
+	padding-top: 10px;
+	border-top: 1px dashed #e2dcd2;
+}
+
+.prab-edit-unavailable {
+	font-size: 12px;
+	color: #777;
+	font-style: italic;
+	max-width: 46em;
+}
+
+.prab-rerun-from--stale {
+	border-color: #d98c2b;
+	color: #8a4a0b;
+}
+
+/* ── Edit panel ───────────────────────────────────────────────────── */
+.prab-edit-panel {
+	margin-top: 12px;
+	padding: 14px 16px;
+	background: #fbf8f2;
+	border: 1px solid #e2dcd2;
+	border-radius: 6px;
+}
+
+.prab-edit-copy {
+	font-size: 13px;
+	color: #50575e;
+	max-width: 60em;
+}
+
+.prab-edit-spend {
+	font-size: 12px;
+	color: #50575e;
+}
+
+.prab-edit-spend--warn,
+.prab-spend-warning {
+	color: #8a2a0b;
+	font-weight: 600;
+}
+
+.prab-run-spend--warn {
+	border-left: 3px solid #c9501f;
+}
+
+.prab-edit-model {
+	font-size: 12px;
+	color: #777;
+	font-family: Consolas, Monaco, monospace;
+}
+
+.prab-edit-message {
+	margin-bottom: 10px;
+}
+
+.prab-edit-role {
+	display: block;
+	font-size: 11px;
+	font-weight: 700;
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+	color: #8c8f94;
+	margin-bottom: 3px;
+}
+
+.prab-edit-textarea {
+	width: 100%;
+	font-family: Consolas, Monaco, monospace;
+	font-size: 12px;
+	line-height: 1.5;
+}
+
+.prab-edit-actions {
+	display: flex;
+	align-items: center;
+	gap: 10px;
+	flex-wrap: wrap;
+	margin-top: 8px;
+}
+
+.prab-edit-forkinfo {
+	font-size: 12px;
+	color: #777;
+}
+
+.prab-edit-feedback {
+	font-size: 12px;
+	color: #1e6b2e;
+}
+
+.prab-edit-feedback--error {
+	color: #b32d2e;
+}
+
+/* ── Image grid (F3) ──────────────────────────────────────────────── */
+.prab-image-grid {
+	display: flex;
+	gap: 14px;
+	flex-wrap: wrap;
+	margin: 10px 0;
+}
+
+.prab-image-card {
+	margin: 0;
+	max-width: 220px;
+}
+
+.prab-image-card img {
+	width: 100%;
+	height: auto;
+	border-radius: 4px;
+	border: 1px solid #e2dcd2;
+}
+
+.prab-image-card--chosen img {
+	border: 2px solid #1b8a92;
+}
+
+.prab-image-card figcaption {
+	font-size: 12px;
+	color: #50575e;
+	margin-top: 4px;
+}
+
+/* ── Sidebar models card (F2) ─────────────────────────────────────── */
+.prab-models-table {
+	width: 100%;
+	border-collapse: collapse;
+	font-size: 12px;
+}
+
+.prab-models-table th {
+	text-align: left;
+	font-weight: 600;
+	padding: 4px 6px 4px 0;
+	vertical-align: top;
+	color: #50575e;
+	width: 38%;
+}
+
+.prab-models-table td {
+	padding: 4px 0;
+}
+
+.prab-models-model {
+	display: block;
+	font-family: Consolas, Monaco, monospace;
+	font-size: 11px;
+	word-break: break-all;
+}
+
+.prab-models-meta {
+	display: block;
+	color: #8c8f94;
+	font-size: 11px;
+}
+
+/* ── Board card human-modified dot ────────────────────────────────── */
+.prab-card-human-chip {
+	display: inline-block;
+	margin-top: 4px;
+	padding: 1px 7px;
+	border-radius: 9px;
+	font-size: 10px;
+	font-weight: 700;
+	background: #e9f2f4;
+	color: #1b5e6b;
+	border: 1px solid #b8d8de;
+}
+
+/* ── Review queue stale warning ───────────────────────────────────── */
+.prab-review-stale-chip {
+	display: inline-block;
+	margin-left: 6px;
+	padding: 1px 7px;
+	border-radius: 9px;
+	font-size: 10px;
+	font-weight: 700;
+	background: #fcf0e4;
+	color: #8a4a0b;
+	border: 1px solid #e8c9a8;
+}

assets/js/board-generate.js

@@ -0,0 +1,53 @@
+/**
+ * PRAutoBlogger Board -- "New Article" generate button handler (v0.21.0, M4).
+ *
+ * Loaded on the board page alongside board.js. Depends on the prabBoard config
+ * object and jQuery, both already present when board.js loads.
+ *
+ * @see assets/js/board.js          -- Board poller (loads first).
+ * @see includes/admin/class-board-page.php -- Enqueues + localizes prabBoard.
+ */
+( function ( $ ) {
+	'use strict';
+
+	var cfg = window.prabBoard || {};
+
+	/**
+	 * Handle click on the "New Article" button. Fires the existing generate_now
+	 * AJAX action and triggers board backoff reset so the new card appears fast.
+	 */
+	function onBoardGenerateNow() {
+		var $btn = $( '#prab-board-generate-now' );
+		if ( ! $btn.length || $btn.prop( 'disabled' ) ) {
+			return;
+		}
+		$btn.prop( 'disabled', true ).text( cfg.strings && cfg.strings.generatingBtn || 'Generating\u2026' );
+		var $status = $( '#prab-board-gen-status' );
+		$status.text( '' ).hide();
+
+		$.ajax( {
+			url: cfg.ajaxUrl,
+			method: 'POST',
+			data: { action: 'prautoblogger_generate_now', nonce: cfg.generateNonce },
+			success: function ( response ) {
+				if ( response && response.success ) {
+					$status.text( cfg.strings && cfg.strings.genStarted || 'Generation started.' ).show();
+					// Notify board poller to reset backoff (run is now active).
+					$( document ).trigger( 'prab:generation-started' );
+				} else {
+					$status.text( cfg.strings && cfg.strings.genError || 'Generation failed.' ).show();
+					$btn.prop( 'disabled', false ).text( cfg.strings && cfg.strings.newArticle || 'New Article' );
+				}
+			},
+			error: function () {
+				$status.text( cfg.strings && cfg.strings.genError || 'Generation failed.' ).show();
+				$btn.prop( 'disabled', false ).text( cfg.strings && cfg.strings.newArticle || 'New Article' );
+			}
+		} );
+	}
+
+	$( function () {
+		$( document ).on( 'click', '#prab-board-generate-now', onBoardGenerateNow );
+	} );
+
+}( jQuery ) );

assets/js/board.js

@@ -69,6 +69,11 @@
 
 		html += '<div class="prab-card-title">' + escHtml( card.title || cfg.strings.empty ) + '</div>';
 
+		// v0.20.0: human-modified runs are visually distinct at run-list level.
+		if ( card.human_modified ) {
+			html += '<span class="prab-card-human-chip">' + escHtml( cfg.strings.humanModified || 'Human-modified' ) + '</span>';
+		}
+
 		if ( card.cost_total ) {
 			html += '<div class="prab-card-meta"><span class="prab-card-cost">';
 			html += escHtml( formatCost( card.cost_total ) );
@@ -159,6 +164,11 @@
 		renderColumn( 'in_review',  snapshot.in_review   || [] );
 		renderColumn( 'published',  snapshot.published   || [] );
 		renderColumn( 'failed',     snapshot.failed      || [] );
+		// Re-enable board Generate button once no active runs remain.
+		if ( ! snapshot.has_active_runs ) {
+			$( '#prab-board-generate-now' ).prop( 'disabled', false )
+				.text( ( cfg.strings && cfg.strings.newArticle ) || 'New Article' );
+		}
 	}
 
 	/**
@@ -220,22 +230,7 @@
 		} );
 	}
 
-	/** Initialise the board poller on DOM ready. */
-	$( function () {
-		$board = $( '#prab-board' );
-		if ( ! $board.length ) {
-			return;
-		}
 
-		// Inject the error banner after the heading.
-		$errorBanner = $( '<div class="prab-board-error" role="alert">' + escHtml( cfg.strings.pollError || '' ) + '</div>' );
-		$board.before( $errorBanner );
-
-		// Check if any generating card is present in the initial server render.
-		var hasActive = ( $board.find( '[data-column="generating"] .prab-board-card' ).length > 0 );
-		backoffFactor = hasActive ? 1 : 1; // Always start at base on first load.
-
-		schedulePoll( nextDelay( hasActive ) );
 	} );
 
 }( jQuery ) );

assets/js/dossier-edit.js

@@ -0,0 +1,235 @@
+/**
+ * PRAutoBlogger Article Dossier — edit + re-run actions (M3, v0.20.0).
+ *
+ * Chained-cron UX contract (CPO hard constraint): clicking a re-run
+ * button QUEUES a background job — the UI says "queued", starts the
+ * stage-status poll, and renders pickup/result as the rows change.
+ * Nothing here implies synchronous execution.
+ *
+ * Vanilla JS, no build step. Config injected via wp_localize_script
+ * ('prabDossierEdit': ajaxUrl, nonce, postId, pollInterval, strings).
+ *
+ * @see admin/class-dossier-actions.php — The endpoints this calls.
+ * @see admin/class-dossier-page.php    — Enqueue + localization.
+ */
+( function () {
+	'use strict';
+
+	var cfg = window.prabDossierEdit || null;
+
+	function post( action, fields ) {
+		var data = new window.FormData();
+		data.append( 'action', action );
+		data.append( 'nonce', cfg.nonce );
+		data.append( 'post_id', cfg.postId );
+		Object.keys( fields || {} ).forEach( function ( key ) {
+			data.append( key, fields[ key ] );
+		} );
+		return window.fetch( cfg.ajaxUrl, { method: 'POST', credentials: 'same-origin', body: data } )
+			.then( function ( res ) { return res.json(); } );
+	}
+
+	function feedback( panel, message, isError ) {
+		var el = panel.querySelector( '[data-feedback]' );
+		if ( el ) {
+			el.textContent = message || '';
+			el.classList.toggle( 'prab-edit-feedback--error', !! isError );
+		}
+	}
+
+	function sectionFor( el ) {
+		var node = el;
+		while ( node && ! node.classList.contains( 'prab-dossier-section--stage' ) ) {
+			node = node.parentElement;
+		}
+		return node;
+	}
+
+	// ── Stage-status polling (queued → pickup → result) ────────────────
+	var pollTimer = null;
+	var sawActivity = false;
+
+	function applyStageState( state ) {
+		var selector = '.prab-dossier-section--stage[data-stage="' + state.stage + '"][data-agent-role="' + state.agent_role + '"]';
+		var section  = document.querySelector( selector );
+		if ( ! section ) {
+			return;
+		}
+		var pill = section.querySelector( '.prab-stage-status-pill' );
+		if ( pill ) {
+			pill.className   = 'prab-stage-status-pill prab-stage-status-pill--' + state.status;
+			pill.textContent = state.status.charAt( 0 ).toUpperCase() + state.status.slice( 1 );
+		}
+		var staleChip = section.querySelector( '[data-chip="stale"]' );
+		if ( staleChip ) {
+			staleChip.hidden = ! state.stale;
+		}
+		section.classList.toggle( 'prab-stage--stale', !! state.stale );
+		var humanChip = section.querySelector( '[data-chip="human"]' );
+		if ( humanChip ) {
+			humanChip.hidden = ! state.human_modified;
+		}
+	}
+
+	function poll() {
+		post( 'prautoblogger_dossier_stage_status', {} ).then( function ( res ) {
+			if ( ! res || ! res.success || ! res.data ) {
+				return;
+			}
+			var anyRunning = false;
+			var anyStale   = false;
+			var anyHuman   = false;
+			( res.data.stages || [] ).forEach( function ( state ) {
+				applyStageState( state );
+				if ( 'running' === state.status || 'pending' === state.status ) {
+					anyRunning = true;
+				}
+				anyStale = anyStale || !! state.stale;
+				anyHuman = anyHuman || !! state.human_modified;
+			} );
+			var headerHuman = document.querySelector( '[data-header-chip="human"]' );
+			if ( headerHuman ) {
+				headerHuman.hidden = ! anyHuman;
+			}
+			var headerStale = document.querySelector( '[data-header-chip="stale"]' );
+			if ( headerStale ) {
+				headerStale.hidden = ! anyStale;
+			}
+
+			var terminal = -1 === [ 'running', 'pending' ].indexOf( res.data.run_status );
+			if ( anyRunning || ! terminal ) {
+				sawActivity = true;
+				return;
+			}
+			// Run settled after activity we watched: re-render the dossier
+			// fresh (server-rendered outputs, receipts, fork info).
+			if ( sawActivity ) {
+				window.clearInterval( pollTimer );
+				pollTimer = null;
+				window.location.reload();
+			}
+		} ).catch( function () { /* transient poll errors are ignored */ } );
+	}
+
+	function startPolling() {
+		sawActivity = true;
+		if ( ! pollTimer ) {
+			pollTimer = window.setInterval( poll, cfg.pollInterval * 1000 );
+		}
+	}
+
+	// ── Wiring ──────────────────────────────────────────────────────────
+	document.addEventListener( 'DOMContentLoaded', function () {
+		if ( ! cfg ) {
+			return;
+		}
+
+		// Edit panel toggles.
+		document.querySelectorAll( '.prab-edit-toggle' ).forEach( function ( btn ) {
+			btn.addEventListener( 'click', function () {
+				var panel = document.getElementById( btn.getAttribute( 'aria-controls' ) );
+				if ( ! panel ) {
+					return;
+				}
+				var open = btn.getAttribute( 'aria-expanded' ) === 'true';
+				panel.hidden = open;
+				btn.setAttribute( 'aria-expanded', open ? 'false' : 'true' );
+			} );
+		} );
+
+		// Save fork.
+		document.querySelectorAll( '.prab-edit-save' ).forEach( function ( btn ) {
+			btn.addEventListener( 'click', function () {
+				var panel    = btn.closest( '.prab-edit-panel' );
+				var messages = [];
+				panel.querySelectorAll( '.prab-edit-textarea' ).forEach( function ( area ) {
+					messages.push( { role: area.getAttribute( 'data-role' ), content: area.value } );
+				} );
+				btn.disabled = true;
+				feedback( panel, cfg.strings.saving, false );
+				post( 'prautoblogger_dossier_save_input', {
+					stage: panel.getAttribute( 'data-stage' ),
+					agent_role: panel.getAttribute( 'data-agent-role' ),
+					messages: JSON.stringify( messages )
+				} ).then( function ( res ) {
+					btn.disabled = false;
+					if ( res && res.success ) {
+						feedback( panel, res.data.message, false );
+						var rerunBtn = panel.querySelector( '.prab-edit-rerun' );
+						if ( rerunBtn ) {
+							rerunBtn.disabled = false;
+						}
+						var info = panel.querySelector( '[data-forkinfo]' );
+						if ( info && res.data.version ) {
+							info.textContent = 'v' + res.data.version;
+						}
+					} else {
+						feedback( panel, ( res && res.data && res.data.message ) || cfg.strings.error, true );
+					}
+				} ).catch( function () {
+					btn.disabled = false;
+					feedback( panel, cfg.strings.error, true );
+				} );
+			} );
+		} );
+
+		// Replay latest fork (queued).
+		document.querySelectorAll( '.prab-edit-rerun' ).forEach( function ( btn ) {
+			btn.addEventListener( 'click', function () {
+				var panel = btn.closest( '.prab-edit-panel' );
+				if ( ! window.confirm( cfg.strings.confirmReplay ) ) {
+					return;
+				}
+				btn.disabled = true;
+				post( 'prautoblogger_dossier_rerun_stage', {
+					stage: panel.getAttribute( 'data-stage' ),
+					agent_role: panel.getAttribute( 'data-agent-role' )
+				} ).then( function ( res ) {
+					if ( res && res.success ) {
+						feedback( panel, res.data.message, false );
+						startPolling();
+					} else {
+						btn.disabled = false;
+						feedback( panel, ( res && res.data && res.data.message ) || cfg.strings.error, true );
+					}
+				} ).catch( function () {
+					btn.disabled = false;
+					feedback( panel, cfg.strings.error, true );
+				} );
+			} );
+		} );
+
+		// Re-run from here (queued rebuild).
+		document.querySelectorAll( '.prab-rerun-from' ).forEach( function ( btn ) {
+			btn.addEventListener( 'click', function () {
+				var section = sectionFor( btn );
+				if ( ! window.confirm( cfg.strings.confirmRerunFrom ) ) {
+					return;
+				}
+				btn.disabled = true;
+				btn.textContent = cfg.strings.queued;
+				post( 'prautoblogger_dossier_rerun_from', {
+					stage: btn.getAttribute( 'data-stage' ),
+					agent_role: section ? section.getAttribute( 'data-agent-role' ) : ''
+				} ).then( function ( res ) {
+					if ( res && res.success ) {
+						startPolling();
+					} else {
+						btn.disabled = false;
+						btn.textContent = cfg.strings.rerunFromLabel;
+						window.alert( ( res && res.data && res.data.message ) || cfg.strings.error );
+					}
+				} ).catch( function () {
+					btn.disabled = false;
+					btn.textContent = cfg.strings.rerunFromLabel;
+					window.alert( cfg.strings.error );
+				} );
+			} );
+		} );
+
+		// A stage already running (e.g. revisit mid-job): poll from load.
+		if ( document.querySelector( '.prab-stage-status-pill--running' ) ) {
+			startPolling();
+		}
+	} );
+}() );

composer.json

@@ -1,23 +1,26 @@
 {
-"name": "peptiderepo/prautoblogger",
-"description": "WordPress plugin that auto-researches and publishes blog content using AI.",
-"type": "wordpress-plugin",
-"license": "GPL-2.0-or-later",
-"require": {
-"php": ">=7.4"
-},
-"require-dev": {
-"phpunit/phpunit": "^9.5",
-"brain/monkey": "^2.6"
-},
-"autoload": {
-"classmap": [
-"includes/"
-]
-},
-"autoload-dev": {
-"psr-4": {
-"PRAutoBlogger\\Tests\\": "tests/unit/"
+    "name": "peptiderepo/prautoblogger",
+    "description": "WordPress plugin that auto-researches and publishes blog content using AI.",
+    "type": "wordpress-plugin",
+    "license": "GPL-2.0-or-later",
+    "require": {
+        "php": ">=7.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5",
+        "brain/monkey": "^2.6"
+    },
+    "autoload": {
+        "classmap": [
+            "includes/"
+        ]
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "PRAutoBlogger\\Tests\\": "tests/unit/"
+        }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit --testdox"
+    }
 }
-}
-}

docs/adr/0001-editorial-illustration-image-style.md

@@ -0,0 +1,163 @@
+# ADR-0001: Editorial illustration image style — pivot from comic to text-free illustration with caption-as-HTML
+
+- **Status:** Accepted
+- **Date:** 2026-05-29
+- **Deciders:** CTO, Engineer PRAutoBlogger
+- **Supersedes:** —
+- **Superseded by:** —
+- **Related:** ARCHITECTURE.md §#20; CHANGELOG.md [0.16.0]; PR #146 (d00e746);
+  `docs/proposals/2026-05-29-image-pipeline-in-plugin-brief.md`;
+  ARCHITECTURE.md §#21 (v0.17.0 deterministic composer, the follow-on commit)
+
+---
+
+## Context
+
+PRAutoBlogger generates two AI images (A/B pair) for each article and publishes
+them as featured images. From the initial comic-strip launch (commit b17ed47,
+`feat: switch to single-panel newspaper comic style for article images`) through
+v0.15.x, the image style was a **single-panel newspaper comic** — the rewriter
+LLM was asked to produce a comic gag or visual pun, and the result was appended
+to a style suffix and sent to the diffusion model.
+
+By April 2026 two problems had accumulated:
+
+1. **Text legibility.** Small diffusion models (FLUX.1 schnell is the default
+   since v0.9.0 at ~$0.0006/image) cannot reliably render readable text inside
+   an image. Comic panels depend on legible speech bubbles or captions burned
+   into the image; both were routinely garbled (confirmed in the 2026-04-21 A/B
+   finding documented in ARCHITECTURE.md §#21).
+
+2. **Caption path already existed.** A separate HTML caption below the image had
+   been extracted as early as commit 214f57b (`Separate comic captions from
+   generated images`, 2026-04-18). The scene/caption split in
+   `Image_Scene_Parser` was already live, meaning there was an established path
+   for readable text that did not depend on the diffusion model rendering it.
+
+Together these created pressure to stop asking the diffusion model to render
+text at all, and instead shift all readable copy to the HTML caption path that
+was already in place.
+
+## Decision drivers
+
+1. **Image quality on default model.** FLUX.1 schnell (the default since v0.9.0)
+   produces garbled text in generated images. A style that depends on readable
+   in-image text degrades silently on the model we actually ship.
+2. **Editorial trust signal.** Peptide Repo's editorial direction is
+   science-informational; comic gags undercut the authority the site needs for
+   health-adjacent content.
+3. **Reuse the existing caption path.** The scene/caption split and HTML caption
+   path were already live; the change is a prompt rewrite + template substitution
+   with no new infrastructure.
+4. **Admin configurability.** The style suffix was a single string appended to
+   every prompt; a template with a named substitution token (`{{ topic_summary
+   }}`) is more maintainable and admin-overridable without a code deploy.
+5. **Cost and provider neutrality.** The change is prompt-only; provider, model,
+   and pricing are unchanged.
+
+## Options considered
+
+### Option A — Keep the comic style, fix text rendering per-model
+
+Ask the rewriter LLM to omit text from comic panels (no speech bubbles, no
+caption burns), and describe a visual scene instead. Keep the style suffix
+pattern.
+
+**Pros:**
+- Minimal code change — just a prompt edit.
+- Comic aesthetic is recognisable and differentiating.
+
+**Cons:**
+- Does not solve the underlying mismatch: the style suffix is a static string
+  that gives no per-article context to the diffusion model. The rewriter scene
+  still has no slot to insert topic-specific imagery.
+- Comic gags require the LLM to invent a joke per peptide, which is inconsistent
+  in tone.
+- Comic aesthetic conflicts with the editorial trust direction for health content.
+
+### Option B — Pivot to text-free editorial scientific illustration + template substitution (chosen)
+
+Change the rewriter system prompt so the LLM emits a concise 1-2 sentence
+topic/mechanism summary as the SCENE — one concrete centered focal subject, no
+text, no people-as-gag, no logos. Replace the style suffix with an editable
+template (`prautoblogger_image_style_template`) that contains a single
+`{{ topic_summary }}` token filled per-article by
+`PRAutoBlogger_Image_Template_Filler`. The CAPTION line from the scene/caption
+split continues to flow to the HTML-caption-below-image path unchanged.
+
+**Pros:**
+- Diffusion model is never asked to render text; garbled-text failures are
+  eliminated.
+- The editorial scientific illustration style is consistent with the site's
+  authority positioning.
+- Template substitution gives admins a single editable field to control the
+  entire visual style without touching the per-article rewriter logic.
+- Degradation is explicit: missing token → append + warning; empty summary →
+  style-only prompt; a blank prompt is never sent to the provider.
+- Provider, model, and cost are unchanged.
+
+**Cons:**
+- Breaks the comic gag aesthetic for any site running PRAutoBlogger in a
+  context where that was intentional (low risk for this deployment).
+- The old `prautoblogger_image_style_suffix` option must be migrated
+  (handled via one-time migration `prautoblogger_migrated_style_template_v0160`
+  and mirroring to `_deprecated` for one cycle).
+
+### Option C — Generate text overlays in PHP (deterministic composer only)
+
+Skip the style change; solve legibility by compositing text onto images in PHP
+after the diffusion model runs.
+
+**Pros:**
+- Diffusion model input is unchanged (comic style preserved).
+- Composited text is always readable regardless of model.
+
+**Cons:**
+- Compositing a comic-style gag is much harder than compositing a caption band
+  (arbitrary layout vs. a fixed panel at the bottom).
+- Does not address the editorial direction mismatch.
+- The deterministic PHP composer (ARCHITECTURE.md §#21) was already planned as
+  a follow-on commit specifically for OG/social variants — pursuing it as the
+  sole fix conflates two separate problems.
+
+## Decision
+
+**Option B** — pivot to text-free editorial scientific illustration with
+caption-as-HTML and template substitution.
+
+This was shipped as v0.16.0 (2026-05-29, PR #146, commit d00e746). The changes
+are entirely in the prompt layer:
+
+- `Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT` now asks for a concise
+  topic/mechanism SCENE and keeps the CAPTION line for the HTML path.
+- `PRAutoBlogger_Image_Template_Filler::fill()` replaces the old
+  `trim($scene . ' ' . $style_suffix)` concat at all three entry points
+  (`build_article_prompt`, `build_source_prompt`, `build_fallback_prompt`).
+- New admin setting `prautoblogger_image_style_template` with
+  single-token validation replaces the Style Suffix field.
+- One-time migration preserves the old suffix value for one cycle.
+
+The deterministic PHP composer for OG/social branding (ARCHITECTURE.md §#21)
+was deliberately deferred to a follow-on commit (v0.17.0, #152) so that the
+prompt-only change could ship and be verified first.
+
+## Consequences
+
+**Accepted benefits:**
+- Garbled-text image failures are eliminated on the default FLUX.1 schnell model.
+- The editorial scientific illustration style is consistent with the site's
+  health-content positioning and sustainable across future model changes.
+- The template + token pattern makes style updates admin-configurable without
+  code changes.
+
+**Accepted costs:**
+- The comic aesthetic is gone and cannot be restored by toggling a setting;
+  switching back requires a prompt and template change.
+- The `prautoblogger_image_style_suffix` option is deprecated; the migration
+  runs once on upgrade and the old option is not deleted until a future cycle.
+
+**Follow-up created:**
+- ARCHITECTURE.md §#21 (v0.17.0): deterministic PHP image composer to composite
+  branded OG and square card variants — necessary because the social/OG image
+  travels without the HTML caption and therefore needs text burned in by PHP,
+  not by the diffusion model.

docs/adr/README.md

@@ -0,0 +1,26 @@
+# PRAutoBlogger — App-Local ADR Log
+
+This folder is the per-repo decision log for the **PRAutoBlogger** plugin.
+It records architectural choices that affect this codebase alone.
+
+**Cross-cutting decisions** (spanning multiple plugins, shared infra, or
+CI/deploy standards) live centrally in
+`Peptide Repo CTO/docs/engineering/decisions/`.
+
+For the routing rule, required sections, and status lifecycle, read the
+canonical process document:
+`Peptide Repo CTO/docs/engineering/ADR-PROCESS.md`
+
+The canonical template for new ADRs is:
+`Peptide Repo CTO/docs/engineering/adr-template.md`
+
+## Numbering
+
+ADRs in this folder use a per-repo zero-padded sequence starting at `0001`.
+A new ADR always gets the next unused number; numbers are never reused.
+
+## Index
+
+| Number | Title | Status | Date |
+|--------|-------|--------|------|
+| [0001](0001-editorial-illustration-image-style.md) | Editorial illustration image style — pivot from comic to text-free illustration with caption-as-HTML | Accepted | 2026-05-29 |

includes/admin/class-admin-page.php

@@ -270,84 +270,14 @@ class PRAutoBlogger_Admin_Page {
 	/**
 	 * Sanitize a settings field value.
 	 *
+	 * Delegates to PRAutoBlogger_Settings_Sanitizer (extracted for 300-line compliance).
+	 *
 	 * @param mixed $value The submitted value.
 	 * @return mixed Sanitized value.
+	 *
+	 * @see admin/class-settings-sanitizer.php
 	 */
 	public function sanitize_field( $value ) {
-		$option_name = '';
-		$filter      = current_filter();
-		if ( 0 === strpos( $filter, 'sanitize_option_' ) ) {
-			$option_name = substr( $filter, strlen( 'sanitize_option_' ) );
-		}
-
-		$encrypted = array( 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json', 'prautoblogger_runware_api_key' );
-		if ( in_array( $option_name, $encrypted, true ) ) {
-			// Empty value means password field wasn't touched — keep existing.
-			if ( '' === $value ) {
-				return get_option( $option_name, '' );
-			}
-
-			// Already encrypted (has "enc:" prefix) — return as-is.
-			// This is the primary defence against double-encryption:
-			// PRAutoBlogger_Encryption::encrypt() also checks for this prefix,
-			// so even if this callback is called multiple times, the value
-			// is encrypted exactly once and never re-encrypted.
-			if ( PRAutoBlogger_Encryption::is_encrypted( $value ) ) {
-				return $value;
-			}
-
-			// New plaintext value — encrypt it (adds "enc:" prefix).
-			return PRAutoBlogger_Encryption::encrypt( sanitize_text_field( $value ) );
-		}
-
-		$json_fields = array( 'prautoblogger_target_subreddits', 'prautoblogger_topic_exclusions', 'prautoblogger_enabled_sources' );
-		if ( in_array( $option_name, $json_fields, true ) ) {
-			// PHP array from checkboxes — sanitize each item and re-encode.
-			if ( is_array( $value ) ) {
-				return wp_json_encode( array_values( array_map( 'sanitize_text_field', $value ) ) );
-			}
-
-			$trimmed = trim( (string) $value );
-
-			// Already JSON-encoded array — decode, sanitize each item, re-encode.
-			// This prevents sanitize_text_field() from mangling the JSON string,
-			// which caused json_decode() on read to return null → empty subreddits.
-			if ( '[' === substr( $trimmed, 0, 1 ) ) {
-				$decoded = json_decode( $trimmed, true );
-				if ( is_array( $decoded ) ) {
-					return wp_json_encode( array_values( array_map( 'sanitize_text_field', $decoded ) ) );
-				}
-			}
-
-			// Comma-separated plain text — split, sanitize, encode as JSON array.
-			$items = array_filter( array_map( 'trim', explode( ',', $trimmed ) ) );
-			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', 'prautoblogger_board_poll_interval', 'prautoblogger_board_published_window_days' );
-		if ( in_array( $option_name, $numeric, true ) ) {
-			return is_numeric( $value ) ? $value : 0;
-		}
-		if ( 'prautoblogger_image_model' === $option_name ) {
-			return $this->sanitize_image_model( (string) $value );
-		}
-		if ( 'prautoblogger_image_style_template' === $option_name ) {
-			// Multi-line template: validation + textarea-safe sanitisation
-			// (incl. the single-token check, brief A5) lives in the filler.
-			return PRAutoBlogger_Image_Template_Filler::sanitize_for_save( (string) $value );
-		}
-		return sanitize_text_field( (string) $value );
-	}
-
-	/** Validate model id against the registry and persist the derived provider. */
-	private function sanitize_image_model( string $value ): string {
-		$candidate = sanitize_text_field( $value );
-		$provider  = PRAutoBlogger_Image_Model_Registry::provider_for( $candidate );
-		if ( '' !== $provider ) {
-			update_option( 'prautoblogger_image_provider', $provider );
-			return $candidate;
-		}
-		add_settings_error( 'prautoblogger_image_model', 'prautoblogger_image_model_unknown', sprintf( esc_html__( 'Image model "%s" is not in the registry. Keeping the previous selection.', 'prautoblogger' ), esc_html( $candidate ) ) );
-		return (string) get_option( 'prautoblogger_image_model', PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL );
+		return PRAutoBlogger_Settings_Sanitizer::sanitize_field( $value );
 	}
 }

includes/admin/class-board-data-provider.php

@@ -94,7 +94,7 @@ class PRAutoBlogger_Board_Data_Provider {
 			array(
 				'post_type'      => 'post',
 				'post_status'    => 'draft',
-				'posts_per_page' => 20,
+				'posts_per_page' => max( 5, (int) get_option( 'prautoblogger_board_column_limit', PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT ) ),
 				'meta_query'     => array(
 					array(
 						'key'   => '_prautoblogger_generated',
@@ -127,7 +127,7 @@ class PRAutoBlogger_Board_Data_Provider {
 			);
 		}
 
-		return $cards;
+		return $this->flag_human_modified( $cards );
 	}
 
 	/**
@@ -144,7 +144,7 @@ class PRAutoBlogger_Board_Data_Provider {
 			array(
 				'post_type'      => 'post',
 				'post_status'    => 'publish',
-				'posts_per_page' => 20,
+				'posts_per_page' => max( 5, (int) get_option( 'prautoblogger_board_column_limit', PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT ) ),
 				'date_query'     => array(
 					array(
 						'after'     => $date_after,
@@ -183,6 +183,48 @@ class PRAutoBlogger_Board_Data_Provider {
 			);
 		}
 
+		return $this->flag_human_modified( $cards );
+	}
+
+	/**
+	 * Set 'human_modified' on each card in ONE batched query (v0.20.0 —
+	 * CPO product AC: human-modified runs are visually distinct at the
+	 * run-list level). No per-card queries; self-healing on a missing
+	 * table/column (flag simply stays false).
+	 *
+	 * @param array<int, array<string, mixed>> $cards Column cards.
+	 * @return array<int, array<string, mixed>> Cards with the flag set.
+	 */
+	private function flag_human_modified( array $cards ): array {
+		$run_ids = array();
+		foreach ( $cards as $i => $card ) {
+			$cards[ $i ]['human_modified'] = false;
+			if ( ! empty( $card['run_id'] ) ) {
+				$run_ids[] = (string) $card['run_id'];
+			}
+		}
+		if ( empty( $run_ids ) || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return $cards;
+		}
+		global $wpdb;
+		$table        = PRAutoBlogger_Run_Stage_State::table_name();
+		$placeholders = implode( ',', array_fill( 0, count( $run_ids ), '%s' ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %s list.
+		$flagged = $wpdb->get_col(
+			$wpdb->prepare(
+				"SELECT DISTINCT run_id FROM {$table} WHERE human_modified = 1 AND run_id IN ({$placeholders})",
+				$run_ids
+			)
+		);
+		if ( ! is_array( $flagged ) || empty( $flagged ) ) {
+			return $cards;
+		}
+		$flagged = array_flip( array_map( 'strval', $flagged ) );
+		foreach ( $cards as $i => $card ) {
+			if ( isset( $flagged[ (string) ( $card['run_id'] ?? '' ) ] ) ) {
+				$cards[ $i ]['human_modified'] = true;
+			}
+		}
 		return $cards;
 	}
 }

includes/admin/class-board-gen-log-query.php

@@ -76,8 +76,9 @@ class PRAutoBlogger_Board_Gen_Log_Query {
 				  AND post_id IS NULL
 				GROUP BY run_id
 				ORDER BY started_at DESC
-				LIMIT 10",
-				$since
+				LIMIT %d",
+				$since,
+				(int) max( 5, get_option( 'prautoblogger_board_column_limit', PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT ) )
 			),
 			ARRAY_A
 		);
@@ -148,8 +149,9 @@ class PRAutoBlogger_Board_Gen_Log_Query {
 				  AND post_id IS NULL
 				GROUP BY run_id
 				ORDER BY started_at DESC
-				LIMIT 20",
-				$since
+				LIMIT %d",
+				$since,
+				(int) max( 5, get_option( 'prautoblogger_board_column_limit', PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT ) )
 			),
 			ARRAY_A
 		);

includes/admin/class-board-page.php

@@ -4,27 +4,27 @@ declare(strict_types=1);
 /**
  * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
  *
- * Registers and renders the kanban board — the primary landing screen for PRAutoBlogger.
+ * Registers and renders the kanban board -- the primary landing screen for PRAutoBlogger.
  *
  * Board columns: Generating | In Review | Published | Failed.
  * Cards live-update via AJAX polling at a settings-backed interval (default 5s),
- * backing off to 2× when no active generating run is detected.
+ * backing off to 2x when no active generating run is detected.
  *
  * Card click-throughs (M1):
- *   - Generating → Activity Log filtered to run context
- *   - In Review  → Review Queue
- *   - Published  → Post edit screen
- *   - Failed     → Activity Log
+ *   - Generating -> Activity Log filtered to run context
+ *   - In Review  -> Review Queue
+ *   - Published  -> Post edit screen
+ *   - Failed     -> Activity Log
  *
  * M2 will rewire all click-throughs to the Article Dossier page.
  *
  * Triggered by: PRAutoBlogger::register_admin_hooks() on `admin_menu`.
  * Dependencies: PRAutoBlogger_Board_Data_Provider, wp_localize_script.
  *
- * @see admin/class-board-data-provider.php — Supplies card data.
- * @see templates/admin/board-page.php      — HTML template.
- * @see assets/js/board.js                  — Polling + DOM updates.
- * @see ARCHITECTURE.md                     — §Board (kanban dashboard).
+ * @see admin/class-board-data-provider.php -- Supplies card data.
+ * @see templates/admin/board-page.php      -- HTML template.
+ * @see assets/js/board.js                  -- Polling + DOM updates.
+ * @see ARCHITECTURE.md                     -- Section: Board (kanban dashboard).
  */
 class PRAutoBlogger_Board_Page {
 
@@ -48,7 +48,7 @@ class PRAutoBlogger_Board_Page {
 	 * $admin_page_hooks['prautoblogger-settings'] before add_submenu_page()
 	 * runs here, so get_plugin_page_hookname() resolves to the correct
 	 * 'prautoblogger_page_prautoblogger-board' suffix rather than the fallback
-	 * 'admin_page_prautoblogger-board'. See ARCHITECTURE.md §Board.
+	 * 'admin_page_prautoblogger-board'. See ARCHITECTURE.md Section: Board.
 	 *
 	 * @return void
 	 */
@@ -128,6 +128,13 @@ class PRAutoBlogger_Board_Page {
 			PRAUTOBLOGGER_VERSION,
 			true
 		);
+		wp_enqueue_script(
+			'prautoblogger-board-generate',
+			PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/board-generate.js',
+			array( 'jquery', 'prautoblogger-board' ),
+			PRAUTOBLOGGER_VERSION,
+			true
+		);
 
 		$poll_interval   = max( 3, (int) get_option( 'prautoblogger_board_poll_interval', 5 ) );
 		$published_days  = max( 1, (int) get_option( 'prautoblogger_board_published_window_days', 7 ) );
@@ -138,6 +145,7 @@ class PRAutoBlogger_Board_Page {
 			array(
 				'ajaxUrl'           => admin_url( 'admin-ajax.php' ),
 				'nonce'             => wp_create_nonce( self::NONCE_ACTION ),
+				'generateNonce'     => wp_create_nonce( 'prautoblogger_generate_now' ),
 				'pollInterval'      => $poll_interval * 1000,
 				'publishedWindowDays' => $published_days,
 				'action'            => self::AJAX_ACTION,
@@ -151,7 +159,12 @@ class PRAutoBlogger_Board_Page {
 					'view'         => __( 'View', 'prautoblogger' ),
 					'edit'         => __( 'Edit', 'prautoblogger' ),
 					'viewLog'      => __( 'View Log', 'prautoblogger' ),
-					'pollError'    => __( 'Board update failed — retrying.', 'prautoblogger' ),
+					'pollError'    => __( 'Board update failed -- retrying.', 'prautoblogger' ),
+					'humanModified'  => __( 'Human-modified', 'prautoblogger' ),
+					'newArticle'     => __( 'New Article', 'prautoblogger' ),
+					'generatingBtn'  => __( 'Generating...', 'prautoblogger' ),
+					'genStarted'     => __( 'Generation started. Board will update automatically.', 'prautoblogger' ),
+					'genError'       => __( 'Generation failed to start. Check the Activity Log.', 'prautoblogger' ),
 				),
 			)
 		);
@@ -162,7 +175,7 @@ class PRAutoBlogger_Board_Page {
 	 *
 	 * Nonce: `prautoblogger_board`. Requires `manage_options` capability.
 	 *
-	 * Side effects: DB reads only — no writes.
+	 * Side effects: DB reads only -- no writes.
 	 *
 	 * @return void
 	 */

includes/admin/class-dossier-actions.php

@@ -0,0 +1,299 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * AJAX endpoints for the dossier's edit + re-run actions (v0.20.0, M3).
+ *
+ * What: Four manage_options + nonce gated endpoints. The mutation
+ *       endpoints follow the chained-cron contract strictly: save_input
+ *       only INSERTs an immutable fork version; the two rerun endpoints
+ *       only validate + queue (Rerun_Job_Support::queue) — execution and
+ *       ALL run/stage state mutations happen in the cron handler after
+ *       re-validation under the generation lock. Run identity (run_id /
+ *       item_key) is always derived server-side from the post's meta —
+ *       never trusted from the client; the client only names the stage
+ *       row it acted on, which is validated against an existing row.
+ *       stage_status is the read-only poll the dossier JS uses to show
+ *       queued -> pickup -> result.
+ * Who triggers it: assets/js/dossier-edit.js via admin-ajax.php;
+ *       registered in class-prautoblogger.php.
+ * Dependencies: Rerun_Eligibility, Stage_Input_Store, Stage_Replay
+ *       (decode), Rerun_Job_Support/Executor, Run_Stage_State.
+ *
+ * @see assets/js/dossier-edit.js     — The frontend caller.
+ * @see core/class-rerun-executor.php — The cron handlers jobs land in.
+ * @see ARCHITECTURE.md #24           — Edit + re-run design.
+ */
+class PRAutoBlogger_Dossier_Actions {
+
+	/** Nonce action shared by all four endpoints. */
+	public const NONCE_ACTION = 'prautoblogger_dossier_actions';
+
+	/**
+	 * AJAX: save an edited stage input as a new immutable fork version.
+	 *
+	 * The fork body is the stage's base request (latest fork, else the
+	 * recorded request_json) with ONLY the message contents substituted —
+	 * roles, message count, model and call options are not editable, so
+	 * a fork is always a well-formed replayable chat body. Prompt text
+	 * is stored raw (it is LLM input, never rendered unescaped).
+	 *
+	 * Side effects: one stage_inputs INSERT.
+	 *
+	 * @return void Sends JSON.
+	 */
+	public function on_save_input(): void {
+		$request = $this->authorize_and_resolve();
+
+		$check = PRAutoBlogger_Rerun_Eligibility::check( $request['run_id'], $request['post_id'] );
+		if ( ! PRAutoBlogger_Rerun_Eligibility::is_editable_stage( $request['stage'] ) || ! $check['ok'] ) {
+			$reason = $check['ok'] ? __( 'This stage cannot be replayed with an edited input.', 'prautoblogger' ) : $check['reason'];
+			wp_send_json_error( array( 'message' => $reason ), 400 );
+			return;
+		}
+
+		$base_body = $this->resolve_base_body( $request );
+		if ( null === $base_body ) {
+			wp_send_json_error( array( 'message' => __( 'No persisted input exists for this stage.', 'prautoblogger' ) ), 400 );
+			return;
+		}
+
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- raw prompt text for the LLM; structure-validated below, stored raw, escaped at render.
+		$raw      = isset( $_POST['messages'] ) ? wp_unslash( (string) $_POST['messages'] ) : '';
+		$messages = json_decode( $raw, true );
+		$merged   = $this->merge_messages( $base_body, is_array( $messages ) ? $messages : null );
+		if ( null === $merged ) {
+			wp_send_json_error( array( 'message' => __( 'Edited messages must match the original structure (same count and roles, non-empty contents).', 'prautoblogger' ) ), 400 );
+			return;
+		}
+
+		$user    = wp_get_current_user();
+		$version = PRAutoBlogger_Stage_Input_Store::save_fork(
+			$request['run_id'],
+			$request['stage'],
+			$request['agent_role'],
+			$request['item_key'],
+			(string) wp_json_encode( $merged ),
+			(string) $user->user_login
+		);
+		if ( null === $version ) {
+			wp_send_json_error( array( 'message' => __( 'The edited input could not be saved.', 'prautoblogger' ) ), 500 );
+			return;
+		}
+
+		wp_send_json_success(
+			array(
+				'version' => $version,
+				'message' => sprintf(
+					/* translators: %d: fork version number. */
+					__( 'Saved as version %d. The original input is preserved unchanged; re-running this stage will use your edited version and mark all downstream stages stale.', 'prautoblogger' ),
+					$version
+				),
+			)
+		);
+	}
+
+	/**
+	 * AJAX: queue a single-stage replay of the latest edited fork.
+	 *
+	 * Validates, then ONLY schedules — chained-cron semantics. The UI
+	 * copy never implies synchronous execution.
+	 *
+	 * @return void Sends JSON.
+	 */
+	public function on_rerun_stage(): void {
+		$request = $this->authorize_and_resolve();
+
+		$check = PRAutoBlogger_Rerun_Eligibility::check_replay(
+			$request['run_id'],
+			$request['post_id'],
+			$request['stage'],
+			$request['agent_role'],
+			$request['item_key']
+		);
+		if ( ! $check['ok'] ) {
+			wp_send_json_error( array( 'message' => $check['reason'] ), 400 );
+			return;
+		}
+
+		PRAutoBlogger_Rerun_Job_Support::queue(
+			PRAutoBlogger_Rerun_Executor::REPLAY_ACTION,
+			array( $request['run_id'], $request['post_id'], $request['stage'], $request['agent_role'], $request['item_key'] ),
+			sprintf(
+				/* translators: %s: stage display label. */
+				__( 'Queued: re-running %s with the edited input…', 'prautoblogger' ),
+				PRAutoBlogger_Stage_Display_Map::label( $request['stage'] )
+			)
+		);
+
+		wp_send_json_success(
+			array(
+				'queued'  => true,
+				'message' => __( 'Re-run queued. The pipeline will pick it up shortly — progress appears here and on the board.', 'prautoblogger' ),
+			)
+		);
+	}
+
+	/**
+	 * AJAX: queue re-run-from-here (rebuild this stage + downstream).
+	 *
+	 * @return void Sends JSON.
+	 */
+	public function on_rerun_from(): void {
+		$request = $this->authorize_and_resolve();
+
+		$check = PRAutoBlogger_Rerun_Eligibility::check_rebuild(
+			$request['run_id'],
+			$request['post_id'],
+			$request['stage'],
+			$request['item_key']
+		);
+		if ( ! $check['ok'] ) {
+			wp_send_json_error( array( 'message' => $check['reason'] ), 400 );
+			return;
+		}
+
+		PRAutoBlogger_Rerun_Job_Support::queue(
+			PRAutoBlogger_Rerun_Executor::REBUILD_ACTION,
+			array( $request['run_id'], $request['post_id'], $request['stage'], $request['item_key'] ),
+			sprintf(
+				/* translators: %s: stage display label. */
+				__( 'Queued: re-running the pipeline from %s…', 'prautoblogger' ),
+				PRAutoBlogger_Stage_Display_Map::label( $request['stage'] )
+			)
+		);
+
+		wp_send_json_success(
+			array(
+				'queued'  => true,
+				'message' => __( 'Re-run from here queued. Stages will rebuild in sequence — progress appears here and on the board.', 'prautoblogger' ),
+			)
+		);
+	}
+
+	/**
+	 * AJAX: read-only stage-status poll for the dossier.
+	 *
+	 * @return void Sends JSON: run status, per-stage state, live message.
+	 */
+	public function on_stage_status(): void {
+		$request = $this->authorize_and_resolve( false );
+
+		$stages = array();
+		foreach ( PRAutoBlogger_Run_Stage_State::stages_for_item( $request['run_id'], $request['item_key'] ) as $row ) {
+			$stages[] = array(
+				'stage'          => (string) ( $row['stage'] ?? '' ),
+				'agent_role'     => (string) ( $row['agent_role'] ?? '' ),
+				'status'         => (string) ( $row['status'] ?? '' ),
+				'stale'          => ! empty( $row['stale'] ),
+				'human_modified' => ! empty( $row['human_modified'] ),
+				'attempt'        => (int) ( $row['attempt'] ?? 1 ),
+				'finished_at'    => (string) ( $row['finished_at'] ?? '' ),
+			);
+		}
+
+		$live = get_transient( PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT );
+
+		wp_send_json_success(
+			array(
+				'run_status' => (string) ( PRAutoBlogger_Run_State::get_status( $request['run_id'] ) ?? '' ),
+				'stages'     => $stages,
+				'live'       => is_array( $live ) ? $live : null,
+			)
+		);
+	}
+
+	/**
+	 * Shared gate: nonce + capability, then derive run identity from the
+	 * POSTed post_id server-side. Sends a JSON error (and exits) on any
+	 * failure.
+	 *
+	 * @param bool $require_stage Whether the request must name a stage row.
+	 * @return array{post_id: int, run_id: string, item_key: string, stage: string, agent_role: string}
+	 */
+	private function authorize_and_resolve( bool $require_stage = true ): array {
+		check_ajax_referer( self::NONCE_ACTION, 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+		}
+
+		$post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;
+		$run_id  = $post_id > 0 ? (string) get_post_meta( $post_id, '_prautoblogger_run_id', true ) : '';
+		if ( 0 === $post_id || '' === $run_id ) {
+			wp_send_json_error( array( 'message' => __( 'No generation run is recorded for this article.', 'prautoblogger' ) ), 400 );
+		}
+		$idea_hash = (string) get_post_meta( $post_id, '_prautoblogger_idea_hash', true );
+		$item_key  = '' !== $idea_hash ? 'idea:' . $idea_hash : '';
+
+		$stage      = isset( $_POST['stage'] ) ? sanitize_key( (string) wp_unslash( $_POST['stage'] ) ) : '';
+		$agent_role = isset( $_POST['agent_role'] ) ? sanitize_key( (string) wp_unslash( $_POST['agent_role'] ) ) : '';
+		if ( $require_stage && '' === $stage ) {
+			wp_send_json_error( array( 'message' => __( 'No stage specified.', 'prautoblogger' ) ), 400 );
+		}
+
+		return array(
+			'post_id'    => $post_id,
+			'run_id'     => $run_id,
+			'item_key'   => $item_key,
+			'stage'      => $stage,
+			'agent_role' => $agent_role,
+		);
+	}
+
+	/**
+	 * The base body an edit forks from: latest saved fork, else the
+	 * stage's recorded request_json.
+	 *
+	 * @param array<string, mixed> $request Resolved request context.
+	 * @return array<string, mixed>|null Decoded body, or null when absent.
+	 */
+	private function resolve_base_body( array $request ): ?array {
+		$fork = PRAutoBlogger_Stage_Input_Store::latest_fork( $request['run_id'], $request['stage'], $request['agent_role'], $request['item_key'] );
+		if ( null !== $fork && ! empty( $fork['request_json'] ) ) {
+			return PRAutoBlogger_Stage_Replay::decode_body( (string) $fork['request_json'] );
+		}
+		$log_rows = ( new PRAutoBlogger_Dossier_Gen_Log_Query() )->get_by_run( $request['run_id'] );
+		$rows     = $log_rows[ $request['stage'] ] ?? array();
+		foreach ( array_reverse( $rows ) as $row ) {
+			if ( ! empty( $row['request_json'] ) ) {
+				$body = PRAutoBlogger_Stage_Replay::decode_body( (string) $row['request_json'] );
+				if ( null !== $body ) {
+					return $body;
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Substitute edited message contents into the base body. Structure
+	 * is locked: same message count, same roles, all contents non-empty
+	 * strings — so every fork stays a replayable chat body.
+	 *
+	 * @param array<string, mixed>     $base     Decoded base body.
+	 * @param array<int, mixed>|null   $messages Edited messages payload.
+	 * @return array<string, mixed>|null Merged body, or null when invalid.
+	 */
+	private function merge_messages( array $base, ?array $messages ): ?array {
+		if ( null === $messages || count( $messages ) !== count( $base['messages'] ) ) {
+			return null;
+		}
+		$merged = $base;
+		foreach ( array_values( $messages ) as $i => $message ) {
+			if ( ! is_array( $message ) || ! isset( $message['role'], $message['content'] )
+				|| ! is_string( $message['role'] ) || ! is_string( $message['content'] ) ) {
+				return null;
+			}
+			if ( ( $base['messages'][ $i ]['role'] ?? null ) !== $message['role'] ) {
+				return null;
+			}
+			if ( '' === trim( $message['content'] ) ) {
+				return null;
+			}
+			$merged['messages'][ $i ]['content'] = $message['content'];
+		}
+		return $merged;
+	}
+}

includes/admin/class-dossier-data-assembler.php

@@ -16,6 +16,15 @@ declare(strict_types=1);
  * Legacy posts (no run row) return ['has_run' => false] -- never notices.
  * Amortized research rows (pv=null, role='') render gracefully.
  *
+ * v0.20.0 (M3): stage rows are filtered to THIS post's item (item_key
+ * from the idea-hash meta; multi-article runs no longer collide) and
+ * gen_log rows exclude entries linked to OTHER posts; per-stage edit/
+ * re-run affordance data + run spend ride the view model
+ * (Dossier_Rerun_Panel_Data); log-only stages (image_a/image_b/
+ * llm_research/... -- generation_log rows with no run_stages row) and
+ * the post's pipeline attachments are exposed so the image sections
+ * render from their REAL data sources (QA M2 F3).
+ *
  * Triggered by: PRAutoBlogger_Dossier_Page::render_page().
  * Dependencies: PRAutoBlogger_Dossier_Gen_Log_Query, PRAutoBlogger_Stage_Display_Map,
  *               PRAutoBlogger_Run_Stage_State.
@@ -55,6 +64,16 @@ class PRAutoBlogger_Dossier_Data_Assembler {
 			'stages'        => array(),
 			'decisions'     => array(),
 			'gen_log_index' => array(),
+			'item_key'      => '',
+			'eligibility'   => array(
+				'ok'     => false,
+				'reason' => '',
+			),
+			'spend'              => PRAutoBlogger_Dossier_Rerun_Panel_Data::spend( null ),
+			'human_modified_any' => false,
+			'stale_any'          => false,
+			'log_only_stages'    => array(),
+			'images'             => array(),
 		);
 
 		if ( $post_id <= 0 ) {
@@ -82,11 +101,40 @@ class PRAutoBlogger_Dossier_Data_Assembler {
 			return $base;
 		}
 
+		$idea_hash         = (string) get_post_meta( $post_id, '_prautoblogger_idea_hash', true );
+		$item_key          = '' !== $idea_hash ? 'idea:' . $idea_hash : '';
+		$base['item_key']  = $item_key;
+
 		$base['has_run']       = true;
 		$base['run']           = $run;
-		$base['stages']        = $this->get_stage_rows( $run_id );
+		$base['stages']        = $this->get_stage_rows( $run_id, $item_key );
 		$base['decisions']     = $this->get_decision_rows( $run_id );
-		$base['gen_log_index'] = $this->log_query->get_by_run( $run_id );
+		$base['gen_log_index'] = $this->filter_log_for_post( $this->log_query->get_by_run( $run_id ), $post_id );
+		$base['eligibility']   = PRAutoBlogger_Rerun_Eligibility::check( $run_id, $post_id );
+		$base['spend']         = PRAutoBlogger_Dossier_Rerun_Panel_Data::spend( $run );
+
+		foreach ( $base['stages'] as $role_key => $stage_row ) {
+			$stage_name = (string) ( $stage_row['stage'] ?? '' );
+			$rerun      = PRAutoBlogger_Dossier_Rerun_Panel_Data::for_stage(
+				$stage_row,
+				$base['gen_log_index'][ $stage_name ] ?? array(),
+				$run_id,
+				$base['eligibility']
+			);
+			$base['stages'][ $role_key ]['rerun'] = $rerun;
+			$base['human_modified_any']           = $base['human_modified_any'] || $rerun['human_modified'];
+			$base['stale_any']                    = $base['stale_any'] || $rerun['stale'];
+		}
+
+		// QA M2 F3: stages that exist only in generation_log (image_a/
+		// image_b, llm_research, image_prompt_rewrite, ...) render from
+		// their real source instead of silently disappearing.
+		$run_stage_names         = array();
+		foreach ( $base['stages'] as $stage_row ) {
+			$run_stage_names[ (string) ( $stage_row['stage'] ?? '' ) ] = true;
+		}
+		$base['log_only_stages'] = array_values( array_diff( array_keys( $base['gen_log_index'] ), array_keys( $run_stage_names ) ) );
+		$base['images']          = PRAutoBlogger_Dossier_Image_Data::for_post( $post_id );
 
 		return $base;
 	}
@@ -112,12 +160,14 @@ class PRAutoBlogger_Dossier_Data_Assembler {
 	}
 
 	/**
-	 * Fetch all run_stages rows for a run, indexed by stage name.
+	 * Fetch run_stages rows for a run, indexed by stage name — scoped to
+	 * one item (+ run-level rows) when an item key is known.
 	 *
-	 * @param string $run_id Pipeline run UUID.
+	 * @param string $run_id   Pipeline run UUID.
+	 * @param string $item_key Item key ('' = no scoping, M2 behavior).
 	 * @return array<string, array<string, mixed>> Stage rows keyed by stage name.
 	 */
-	private function get_stage_rows( string $run_id ): array {
+	private function get_stage_rows( string $run_id, string $item_key = '' ): array {
 		if ( ! PRAutoBlogger_Run_Stage_State::is_available() ) {
 			return array();
 		}
@@ -126,11 +176,22 @@ class PRAutoBlogger_Dossier_Data_Assembler {
 			return array();
 		}
 		$table = PRAutoBlogger_Run_Stage_State::table_name();
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
-		$rows = $wpdb->get_results(
-			$wpdb->prepare( "SELECT * FROM {$table} WHERE run_id = %s ORDER BY id ASC", $run_id ),
-			ARRAY_A
-		);
+		// v0.20.0: scope to THIS post's item + run-level rows. When the
+		// idea-hash meta is absent (pre-v0.18 posts) fall back to the
+		// unfiltered M2 behavior (single-item runs are unaffected).
+		if ( '' !== $item_key ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+			$rows = $wpdb->get_results(
+				$wpdb->prepare( "SELECT * FROM {$table} WHERE run_id = %s AND item_key IN (%s, '') ORDER BY id ASC", $run_id, $item_key ),
+				ARRAY_A
+			);
+		} else {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+			$rows = $wpdb->get_results(
+				$wpdb->prepare( "SELECT * FROM {$table} WHERE run_id = %s ORDER BY id ASC", $run_id ),
+				ARRAY_A
+			);
+		}
 
 		$index = array();
 		foreach ( ( $rows ?? array() ) as $row ) {
@@ -145,6 +206,29 @@ class PRAutoBlogger_Dossier_Data_Assembler {
 		return $index;
 	}
 
+	/**
+	 * Drop gen_log rows linked to OTHER posts (multi-article runs share
+	 * one run_id). Rows with no post linkage (NULL/0 — run-level work
+	 * and pre-link entries) are kept.
+	 *
+	 * @param array<string, array<int, array<string, mixed>>> $log_index Rows keyed by stage.
+	 * @param int                                             $post_id   This dossier's post.
+	 * @return array<string, array<int, array<string, mixed>>>
+	 */
+	private function filter_log_for_post( array $log_index, int $post_id ): array {
+		$filtered = array();
+		foreach ( $log_index as $stage => $rows ) {
+			foreach ( $rows as $row ) {
+				$row_post = (int) ( $row['post_id'] ?? 0 );
+				if ( 0 !== $row_post && $row_post !== $post_id ) {
+					continue;
+				}
+				$filtered[ $stage ][] = $row;
+			}
+		}
+		return $filtered;
+	}
+
 	/**
 	 * Extract the text output from a run_stages meta_json blob.
 	 * Returns null when meta_json is NULL (pruned) or absent.

includes/admin/class-dossier-image-data.php

@@ -0,0 +1,82 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Resolves a post's pipeline image attachments for the dossier (M3/F3).
+ *
+ * What: The image sections' REAL data source — the attachments the
+ *       image pipeline produced (featured + composed og/square variants,
+ *       discovered via the `_prautoblogger_image_role` attachment meta
+ *       and the post thumbnail), paired in the template with the
+ *       image_a/image_b generation_log rows. Replaces the M2 sections
+ *       that keyed off run_stages rows the image pipeline never writes
+ *       (QA M2 F3 — wiring the dossier to real data was the smaller,
+ *       safer change vs. teaching the live image pipeline to write
+ *       run_stages; the pipeline restructure is Phase 2b).
+ * Who triggers it: PRAutoBlogger_Dossier_Data_Assembler::assemble().
+ * Dependencies: get_children(), attachment meta, wp_get_attachment_image_url().
+ *
+ * @see admin/class-dossier-data-assembler.php   — Caller.
+ * @see templates/admin/dossier-log-stage-section.php — Renders the pairs.
+ * @see ARCHITECTURE.md #24                      — M3 design (F3 note).
+ */
+class PRAutoBlogger_Dossier_Image_Data {
+
+	/**
+	 * The post's pipeline attachments (featured/og/square) via the
+	 * `_prautoblogger_image_role` attachment meta — the image sections'
+	 * real data source (QA M2 F3).
+	 *
+	 * @param int $post_id Post ID.
+	 * @return array<int, array{id: int, role: string, url: string, is_featured: bool}>
+	 */
+	public static function for_post( int $post_id ): array {
+		$featured_id = (int) get_post_thumbnail_id( $post_id );
+		$children    = get_children(
+			array(
+				'post_parent' => $post_id,
+				'post_type'   => 'attachment',
+				'numberposts' => 12,
+			)
+		);
+
+		$images = array();
+		$seen   = array();
+		foreach ( (array) $children as $attachment ) {
+			$att_id = (int) ( $attachment->ID ?? 0 );
+			if ( $att_id <= 0 ) {
+				continue;
+			}
+			$role = (string) get_post_meta( $att_id, '_prautoblogger_image_role', true );
+			if ( '' === $role && $att_id !== $featured_id ) {
+				continue; // Not a pipeline attachment.
+			}
+			$url = (string) wp_get_attachment_image_url( $att_id, 'medium' );
+			if ( '' === $url ) {
+				continue;
+			}
+			$seen[ $att_id ] = true;
+			$images[]        = array(
+				'id'          => $att_id,
+				'role'        => '' !== $role ? $role : 'featured',
+				'url'         => $url,
+				'is_featured' => $att_id === $featured_id,
+			);
+		}
+		// Featured image attached elsewhere (not a child) still renders.
+		if ( $featured_id > 0 && ! isset( $seen[ $featured_id ] ) ) {
+			$url = (string) wp_get_attachment_image_url( $featured_id, 'medium' );
+			if ( '' !== $url ) {
+				$images[] = array(
+					'id'          => $featured_id,
+					'role'        => 'featured',
+					'url'         => $url,
+					'is_featured' => true,
+				);
+			}
+		}
+		return $images;
+	}
+}

includes/admin/class-dossier-page.php

@@ -119,6 +119,42 @@ class PRAutoBlogger_Dossier_Page {
 			PRAUTOBLOGGER_VERSION,
 			true
 		);
+
+		// M3: edit + re-run layer (separate files; dossier.css is not grown).
+		wp_enqueue_style(
+			'prautoblogger-dossier-edit',
+			PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/dossier-edit.css',
+			array( 'prautoblogger-dossier' ),
+			PRAUTOBLOGGER_VERSION
+		);
+		wp_enqueue_script(
+			'prautoblogger-dossier-edit',
+			PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/dossier-edit.js',
+			array(),
+			PRAUTOBLOGGER_VERSION,
+			true
+		);
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only context resolution for script config.
+		$post_id = isset( $_GET['post_id'] ) ? absint( $_GET['post_id'] ) : 0;
+		wp_localize_script(
+			'prautoblogger-dossier-edit',
+			'prabDossierEdit',
+			array(
+				'ajaxUrl'      => admin_url( 'admin-ajax.php' ),
+				'nonce'        => wp_create_nonce( PRAutoBlogger_Dossier_Actions::NONCE_ACTION ),
+				'postId'       => $post_id,
+				// Settings read at point of use -- same poll setting as the board.
+				'pollInterval' => max( 3, (int) get_option( 'prautoblogger_board_poll_interval', 5 ) ),
+				'strings'      => array(
+					'saving'         => __( 'Saving…', 'prautoblogger' ),
+					'error'          => __( 'Request failed — try again.', 'prautoblogger' ),
+					'queued'         => __( 'Queued…', 'prautoblogger' ),
+					'rerunFromLabel' => __( 'Re-run from here', 'prautoblogger' ),
+					'confirmReplay'  => __( 'Queue a re-run of this stage with your edited input? This makes a new LLM call billed against this run\'s ceiling, and all downstream stages will be marked stale (nothing re-runs automatically).', 'prautoblogger' ),
+					'confirmRerunFrom' => __( 'Queue a re-run of this stage AND every stage after it? Each re-run stage makes new LLM calls billed against this run\'s ceiling. The article draft will be refreshed; published posts are never touched.', 'prautoblogger' ),
+				),
+			)
+		);
 	}
 
 	/**

includes/admin/class-dossier-rerun-panel-data.php

@@ -0,0 +1,181 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Builds the edit + re-run view-model layer for the dossier (v0.20.0, M3).
+ *
+ * What: Per-stage affordance data (editable? why not? latest fork,
+ *       prefill messages from the fork or the stage's recorded
+ *       request_json) plus the run-level spend strip (settled + reserved
+ *       vs ceiling, warn fraction — guardrail 4's visible cost
+ *       implication) and the overall eligibility verdict. Pure
+ *       assembly: reads the rows the Dossier_Data_Assembler already
+ *       fetched plus the stage_inputs store; performs NO mutations.
+ *       Disabled affordances always carry an operator-readable reason —
+ *       the UI never hides why an edit is unavailable.
+ * Who triggers it: PRAutoBlogger_Dossier_Data_Assembler::assemble().
+ * Dependencies: Rerun_Eligibility (policy), Stage_Input_Store (forks),
+ *               Stage_Replay (body decode).
+ *
+ * @see admin/class-dossier-data-assembler.php — Caller.
+ * @see templates/admin/dossier-edit-panel.php — Renders this data.
+ * @see ARCHITECTURE.md #24                    — Edit + re-run design.
+ */
+class PRAutoBlogger_Dossier_Rerun_Panel_Data {
+
+	/** Default warn threshold as a fraction of the per-run ceiling. */
+	private const DEFAULT_WARN_FRACTION = 0.8;
+
+	/**
+	 * Run-level spend strip data (guardrail 4 visibility).
+	 *
+	 * @param array<string, mixed>|null $run Run ledger row, or null.
+	 * @return array{settled: float, reserved: float, ceiling: float, fraction: float, warn: bool}
+	 */
+	public static function spend( ?array $run ): array {
+		$settled  = null !== $run ? (float) ( $run['settled_usd'] ?? 0 ) : 0.0;
+		$reserved = null !== $run ? (float) ( $run['reserved_usd'] ?? 0 ) : 0.0;
+		$ceiling  = null !== $run ? (float) ( $run['ceiling_usd'] ?? 0 ) : 0.0;
+		$fraction = $ceiling > 0 ? ( $settled + $reserved ) / $ceiling : 0.0;
+
+		/**
+		 * Filters the spend fraction at which re-run confirms warn about
+		 * approaching the per-run ceiling.
+		 *
+		 * @param float $warn_fraction Fraction of ceiling (default 0.8).
+		 */
+		$warn_fraction = (float) apply_filters( 'prautoblogger_rerun_ceiling_warn_fraction', self::DEFAULT_WARN_FRACTION );
+
+		return array(
+			'settled'  => $settled,
+			'reserved' => $reserved,
+			'ceiling'  => $ceiling,
+			'fraction' => $fraction,
+			'warn'     => $ceiling > 0 && $fraction >= $warn_fraction,
+		);
+	}
+
+	/**
+	 * Edit + re-run affordance data for one stage row.
+	 *
+	 * @param array<string, mixed>                            $stage_row   run_stages row.
+	 * @param array<int, array<string, mixed>>                $log_rows    generation_log rows for the stage.
+	 * @param string                                          $run_id      Run UUID.
+	 * @param array{ok: bool, reason: string}                 $eligibility Overall run eligibility.
+	 * @return array<string, mixed> Affordance view model (see keys below).
+	 */
+	public static function for_stage( array $stage_row, array $log_rows, string $run_id, array $eligibility ): array {
+		$stage    = (string) ( $stage_row['stage'] ?? '' );
+		$role     = (string) ( $stage_row['agent_role'] ?? '' );
+		$item_key = (string) ( $stage_row['item_key'] ?? '' );
+
+		$data = array(
+			'stale'          => ! empty( $stage_row['stale'] ),
+			'human_modified' => ! empty( $stage_row['human_modified'] ),
+			'attempt'        => (int) ( $stage_row['attempt'] ?? 1 ),
+			'editable'       => false,
+			'edit_reason'    => '',
+			'fork'           => null,
+			'prefill'        => null,
+			'rerun_from'     => $eligibility['ok'] && PRAutoBlogger_Rerun_Eligibility::is_chain_stage( $stage ),
+		);
+
+		if ( ! PRAutoBlogger_Rerun_Eligibility::is_editable_stage( $stage ) ) {
+			$data['edit_reason'] = self::policy_reason( $stage );
+			return $data;
+		}
+		if ( ! $eligibility['ok'] ) {
+			$data['edit_reason'] = $eligibility['reason'];
+			return $data;
+		}
+
+		$fork = PRAutoBlogger_Stage_Input_Store::latest_fork( $run_id, $stage, $role, $item_key );
+		if ( null !== $fork ) {
+			$data['fork'] = array(
+				'version'    => (int) $fork['version'],
+				'author'     => (string) $fork['author'],
+				'created_at' => (string) $fork['created_at'],
+				'has_body'   => ! empty( $fork['request_json'] ),
+			);
+		}
+
+		$base_json = ( null !== $fork && ! empty( $fork['request_json'] ) )
+			? (string) $fork['request_json']
+			: self::latest_request_json( $log_rows );
+
+		if ( null === $base_json ) {
+			$days                = (int) get_option( 'prautoblogger_request_json_retention_days', PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS );
+			$data['edit_reason'] = sprintf(
+				/* translators: %d: retention days. */
+				__( 'No persisted input for this stage — request bodies are recorded from v0.20.0 onward and retained for %d days.', 'prautoblogger' ),
+				$days
+			);
+			return $data;
+		}
+
+		$body = PRAutoBlogger_Stage_Replay::decode_body( $base_json );
+		if ( null === $body ) {
+			$data['edit_reason'] = __( 'The persisted input for this stage is not a replayable chat request.', 'prautoblogger' );
+			return $data;
+		}
+
+		$data['editable'] = true;
+		$data['prefill']  = array(
+			'model'    => (string) $body['model'],
+			'messages' => $body['messages'],
+		);
+		return $data;
+	}
+
+	/**
+	 * Why a non-writer stage has no edit affordance (always shown —
+	 * the UI never silently hides the option).
+	 *
+	 * @param string $stage Stage name.
+	 * @return string Operator-readable reason.
+	 */
+	private static function policy_reason( string $stage ): string {
+		if ( 'review' === $stage ) {
+			return __( 'The review input is derived entirely from the article content — edit a writing stage, then use "Re-run from here" on this one.', 'prautoblogger' );
+		}
+		if ( 'publish' === $stage ) {
+			return __( 'Publish is not an LLM stage — use "Re-run from here" to refresh the post from current outputs.', 'prautoblogger' );
+		}
+		if ( in_array( $stage, array( 'analysis', 'research', 'llm_research' ), true ) ) {
+			return __( 'Run-level stage: its output fed idea selection for the whole run and cannot be re-flowed into a single article.', 'prautoblogger' );
+		}
+		if ( 0 === strpos( $stage, 'image' ) ) {
+			return __( 'Image stages are not replayable yet (Phase 2b restructure).', 'prautoblogger' );
+		}
+		return __( 'This stage cannot be replayed with an edited input.', 'prautoblogger' );
+	}
+
+	/**
+	 * The most recent recorded request body among a stage's log rows
+	 * (success rows preferred, then latest id).
+	 *
+	 * @param array<int, array<string, mixed>> $log_rows generation_log rows.
+	 * @return string|null
+	 */
+	private static function latest_request_json( array $log_rows ): ?string {
+		$best = null;
+		foreach ( $log_rows as $row ) {
+			if ( empty( $row['request_json'] ) ) {
+				continue;
+			}
+			if ( null === $best ) {
+				$best = $row;
+				continue;
+			}
+			$row_success  = ( 'success' === ( $row['response_status'] ?? '' ) );
+			$best_success = ( 'success' === ( $best['response_status'] ?? '' ) );
+			if ( ( $row_success && ! $best_success )
+				|| ( $row_success === $best_success && (int) ( $row['id'] ?? 0 ) > (int) ( $best['id'] ?? 0 ) ) ) {
+				$best = $row;
+			}
+		}
+		return null !== $best ? (string) $best['request_json'] : null;
+	}
+}

includes/admin/class-ideas-browser-query.php

@@ -0,0 +1,136 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Query helpers for PRAutoBlogger_Ideas_Browser.
+ *
+ * Extracted to keep class-ideas-browser.php under 300 lines (CONVENTIONS §1).
+ * All methods are static; class is never instantiated.
+ */
+class PRAutoBlogger_Ideas_Browser_Query {
+
+	/** Fall-through if setting is absent. */
+	public const PER_PAGE_DEFAULT = 30;
+
+	/** Transient key prefix for per-idea generation status. */
+	public const STATUS_PREFIX = 'prab_idea_gen_';
+
+	/** How long to keep per-idea status (seconds). */
+	public const STATUS_TTL = 600;
+
+	/** Query analysis results with optional filtering and pagination. */
+	public static function query_ideas( int $paged, string $type ): array {
+		global $wpdb;
+		$table  = $wpdb->prefix . 'prautoblogger_analysis_results';
+		$where  = array();
+		$params = array();
+
+		if ( '' !== $type ) {
+			$where[]  = 'analysis_type = %s';
+			$params[] = $type;
+		}
+
+		$where_sql = empty( $where ) ? '' : 'WHERE ' . implode( ' AND ', $where );
+		$per_page  = max( 5, (int) get_option( 'prautoblogger_ideas_per_page', self::PER_PAGE_DEFAULT ) );
+		$offset    = ( $paged - 1 ) * $per_page;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$total = (int) $wpdb->get_var(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+			? "SELECT COUNT(*) FROM {$table} {$where_sql}"  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+			: $wpdb->prepare( "SELECT COUNT(*) FROM {$table} {$where_sql}", ...$params )  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
+		);
+
+		$order_sql = 'ORDER BY analyzed_at DESC, relevance_score DESC';
+		$limit_sql = sprintf( 'LIMIT %d OFFSET %d', $per_page, $offset );
+		$full_sql  = "SELECT * FROM {$table} {$where_sql} {$order_sql} {$limit_sql}";
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$rows = empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+		? $wpdb->get_results( $full_sql, ARRAY_A )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+		: $wpdb->get_results( $wpdb->prepare( $full_sql, ...$params ), ARRAY_A );  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
+
+		return array(
+			'rows'  => $rows ?? array(),
+			'total' => $total,
+		);
+	}
+
+	/** Get counts per analysis_type for the filter badges. */
+	public static function get_type_counts(): array {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$rows = $wpdb->get_results(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			"SELECT analysis_type, COUNT(*) AS cnt FROM {$table} GROUP BY analysis_type ORDER BY cnt DESC",
+			ARRAY_A
+		);
+
+		$counts = array();
+		foreach ( $rows ?? array() as $row ) {
+			$counts[ $row['analysis_type'] ] = (int) $row['cnt'];
+		}
+		return $counts;
+	}
+
+	/**
+	 * Load an analysis result row and map it to Article_Idea constructor data.
+	 *
+	 * @param int $idea_id Analysis result row ID.
+	 * @return array<string, mixed>|null Article_Idea-compatible array, or null.
+	 */
+	public static function load_idea_data( int $idea_id ): ?array {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$row = $wpdb->get_row(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			$wpdb->prepare( "SELECT * FROM {$table} WHERE id = %d", $idea_id ),
+			ARRAY_A
+		);
+		if ( ! $row ) {
+			return null;
+		}
+
+		$meta = json_decode( $row['metadata_json'] ?? '{}', true ) ?? array();
+		return array(
+			'topic'           => $row['topic'],
+			'article_type'    => $row['analysis_type'],
+			'suggested_title' => $meta['suggested_title'] ?? $row['topic'],
+			'summary'         => $row['summary'] ?? '',
+			'score'           => (float) $row['relevance_score'],
+			'analysis_id'     => (int) $row['id'],
+			'source_ids'      => json_decode( $row['source_ids_json'] ?? '[]', true ) ?? array(),
+			'key_points'      => $meta['key_points'] ?? array(),
+			'target_keywords' => $meta['target_keywords'] ?? array(),
+		);
+	}
+
+	/** Find the most recent post created by a specific run_id. */
+	public static function find_post_by_run_id( string $run_id ): ?int {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$post_id = $wpdb->get_var(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT DISTINCT post_id FROM {$table} WHERE run_id = %s AND post_id IS NOT NULL LIMIT 1",
+				$run_id
+			)
+		);
+		return null !== $post_id ? (int) $post_id : null;
+	}
+
+	/** Update the per-idea status transient with a stage message. */
+	public static function update_idea_stage( int $idea_id, string $stage ): void {
+		$key     = self::STATUS_PREFIX . $idea_id;
+		$current = get_transient( $key );
+		if ( is_array( $current ) ) {
+			$current['stage'] = $stage;
+			set_transient( $key, $current, self::STATUS_TTL );
+		}
+	}
+}

includes/admin/class-ideas-browser.php

@@ -8,20 +8,14 @@ declare(strict_types=1);
  *
  * Triggered by: PRAutoBlogger::register_admin_hooks() on `admin_menu`.
  * Dependencies: WordPress $wpdb, Article_Worker, Cost_Tracker, Generation_Lock.
+ * Query helpers: class-ideas-browser-query.php (split for 300-line rule, CONVENTIONS §1).
  *
  * @see core/class-article-worker.php         — Generates articles from ideas.
  * @see templates/admin/ideas-browser.php     — Renders the HTML.
+ * @see class-ideas-browser-query.php         — Static query helpers.
  */
 class PRAutoBlogger_Ideas_Browser {
 
-	private const PER_PAGE = 30;
-
-	/** Transient prefix for per-idea generation status. */
-	private const STATUS_PREFIX = 'prab_idea_gen_';
-
-	/** How long to keep per-idea status (seconds). */
-	private const STATUS_TTL = 600;
-
 	/** Register the Ideas submenu page under PRAutoBlogger. */
 	public function on_register_menu(): void {
 		add_submenu_page(
@@ -43,11 +37,12 @@ class PRAutoBlogger_Ideas_Browser {
 		$paged       = isset( $_GET['paged'] ) ? absint( $_GET['paged'] ) : 1;
 		$type_filter = isset( $_GET['type'] ) ? sanitize_key( $_GET['type'] ) : '';
 
-		$result      = $this->query_ideas( $paged, $type_filter );
-		$rows        = $result['rows'];
-		$total       = $result['total'];
-		$total_pages = (int) ceil( $total / self::PER_PAGE );
-		$type_counts = $this->get_type_counts();
+		$result        = PRAutoBlogger_Ideas_Browser_Query::query_ideas( $paged, $type_filter );
+		$rows          = $result['rows'];
+		$total         = $result['total'];
+		$per_page_view = max( 5, (int) get_option( 'prautoblogger_ideas_per_page', PRAutoBlogger_Ideas_Browser_Query::PER_PAGE_DEFAULT ) );
+		$total_pages   = (int) ceil( $total / $per_page_view );
+		$type_counts   = PRAutoBlogger_Ideas_Browser_Query::get_type_counts();
 
 		include PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/ideas-browser.php';
 	}
@@ -74,23 +69,26 @@ class PRAutoBlogger_Ideas_Browser {
 			return;
 		}
 
+		$status_prefix = PRAutoBlogger_Ideas_Browser_Query::STATUS_PREFIX;
+		$status_ttl    = PRAutoBlogger_Ideas_Browser_Query::STATUS_TTL;
+
 		// Build Article_Idea from the analysis row.
-		$idea_data = self::load_idea_data( $idea_id );
+		$idea_data = PRAutoBlogger_Ideas_Browser_Query::load_idea_data( $idea_id );
 		if ( null === $idea_data ) {
 			wp_send_json_error( array( 'message' => 'Idea not found.' ) );
 			return;
 		}
 
 		// Store idea for the cron handler and set initial "running" status.
-		set_transient( self::STATUS_PREFIX . 'data_' . $idea_id, $idea_data, self::STATUS_TTL );
+		set_transient( $status_prefix . 'data_' . $idea_id, $idea_data, $status_ttl );
 		set_transient(
-			self::STATUS_PREFIX . $idea_id,
+			$status_prefix . $idea_id,
 			array(
 				'status'  => 'running',
 				'stage'   => __( 'Starting generation…', 'prautoblogger' ),
 				'started' => time(),
 			),
-			self::STATUS_TTL
+			$status_ttl
 		);
 
 		// Schedule background cron — passes idea_id as argument.
@@ -124,7 +122,7 @@ class PRAutoBlogger_Ideas_Browser {
 		}
 
 		$idea_id = absint( $_POST['idea_id'] ?? 0 );
-		$status  = get_transient( self::STATUS_PREFIX . $idea_id );
+		$status  = get_transient( PRAutoBlogger_Ideas_Browser_Query::STATUS_PREFIX . $idea_id );
 		if ( ! is_array( $status ) ) {
 			wp_send_json_success( array( 'status' => 'idle' ) );
 			return;
@@ -149,16 +147,19 @@ class PRAutoBlogger_Ideas_Browser {
 		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
 		@set_time_limit( 300 );
 
-		$key       = self::STATUS_PREFIX . $idea_id;
-		$idea_data = get_transient( self::STATUS_PREFIX . 'data_' . $idea_id );
+		$prefix = PRAutoBlogger_Ideas_Browser_Query::STATUS_PREFIX;
+		$ttl    = PRAutoBlogger_Ideas_Browser_Query::STATUS_TTL;
+		$key    = $prefix . $idea_id;
+
+		$idea_data = get_transient( $prefix . 'data_' . $idea_id );
 		if ( ! is_array( $idea_data ) ) {
 			set_transient(
 				$key,
 				array(
-					'status'  => 'error',
+					'status' => 'error',
 					'message' => 'Idea data expired.',
 				),
-				self::STATUS_TTL
+				$ttl
 			);
 			return;
 		}
@@ -167,10 +168,10 @@ class PRAutoBlogger_Ideas_Browser {
 			set_transient(
 				$key,
 				array(
-					'status'  => 'error',
+					'status' => 'error',
 					'message' => 'Another generation is running.',
 				),
-				self::STATUS_TTL
+				$ttl
 			);
 			return;
 		}
@@ -180,7 +181,7 @@ class PRAutoBlogger_Ideas_Browser {
 			$cost_tracker = new PRAutoBlogger_Cost_Tracker();
 			$cost_tracker->set_run_id( wp_generate_uuid4() );
 
-			self::update_idea_stage( $idea_id, __( 'Generating article draft…', 'prautoblogger' ) );
+			PRAutoBlogger_Ideas_Browser_Query::update_idea_stage( $idea_id, __( 'Generating article draft…', 'prautoblogger' ) );
 			$worker = new PRAutoBlogger_Article_Worker( $cost_tracker );
 			$result = $worker->generate( $idea );
 
@@ -188,7 +189,7 @@ class PRAutoBlogger_Ideas_Browser {
 			PRAutoBlogger_Post_Assembler::amortize_research_costs( $cost_tracker->get_run_id() );
 
 			// Find the generated post ID for the "View" link.
-			$post_id = self::find_post_by_run_id( $cost_tracker->get_run_id() );
+			$post_id = PRAutoBlogger_Ideas_Browser_Query::find_post_by_run_id( $cost_tracker->get_run_id() );
 
 			set_transient(
 				$key,
@@ -199,7 +200,7 @@ class PRAutoBlogger_Ideas_Browser {
 					'cost'      => $result['cost'],
 					'post_id'   => $post_id,
 				),
-				self::STATUS_TTL
+				$ttl
 			);
 		} catch ( \Throwable $e ) {
 			PRAutoBlogger_Logger::instance()->error(
@@ -209,129 +210,14 @@ class PRAutoBlogger_Ideas_Browser {
 			set_transient(
 				$key,
 				array(
-					'status'  => 'error',
+					'status' => 'error',
 					'message' => $e->getMessage(),
 				),
-				self::STATUS_TTL
+				$ttl
 			);
 		}
 
 		PRAutoBlogger_Generation_Lock::release();
-		delete_transient( self::STATUS_PREFIX . 'data_' . $idea_id );
-	}
-
-	// ── Private helpers ─────────────────────────────────────────────────
-
-	/** Update the per-idea status transient with a stage message. */
-	private static function update_idea_stage( int $idea_id, string $stage ): void {
-		$key     = self::STATUS_PREFIX . $idea_id;
-		$current = get_transient( $key );
-		if ( is_array( $current ) ) {
-			$current['stage'] = $stage;
-			set_transient( $key, $current, self::STATUS_TTL );
-		}
-	}
-
-	/** Find the most recent post created by a specific run_id. */
-	private static function find_post_by_run_id( string $run_id ): ?int {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_generation_log';
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$post_id = $wpdb->get_var(
-			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
-				"SELECT DISTINCT post_id FROM {$table} WHERE run_id = %s AND post_id IS NOT NULL LIMIT 1",
-				$run_id
-			)
-		);
-		return null !== $post_id ? (int) $post_id : null;
-	}
-
-	/**
-	 * Load an analysis result row and map it to Article_Idea constructor data.
-	 *
-	 * @param int $idea_id Analysis result row ID.
-	 * @return array<string, mixed>|null Article_Idea-compatible array, or null.
-	 */
-	private static function load_idea_data( int $idea_id ): ?array {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$row = $wpdb->get_row(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
-			$wpdb->prepare( "SELECT * FROM {$table} WHERE id = %d", $idea_id ),
-			ARRAY_A
-		);
-		if ( ! $row ) {
-			return null;
-		}
-
-		$meta = json_decode( $row['metadata_json'] ?? '{}', true ) ?? array();
-		return array(
-			'topic'           => $row['topic'],
-			'article_type'    => $row['analysis_type'],
-			'suggested_title' => $meta['suggested_title'] ?? $row['topic'],
-			'summary'         => $row['summary'] ?? '',
-			'score'           => (float) $row['relevance_score'],
-			'analysis_id'     => (int) $row['id'],
-			'source_ids'      => json_decode( $row['source_ids_json'] ?? '[]', true ) ?? array(),
-			'key_points'      => $meta['key_points'] ?? array(),
-			'target_keywords' => $meta['target_keywords'] ?? array(),
-		);
-	}
-
-	/** Query analysis results with optional filtering and pagination. */
-	private function query_ideas( int $paged, string $type ): array {
-		global $wpdb;
-		$table  = $wpdb->prefix . 'prautoblogger_analysis_results';
-		$where  = array();
-		$params = array();
-
-		if ( '' !== $type ) {
-			$where[]  = 'analysis_type = %s';
-			$params[] = $type;
-		}
-
-		$where_sql = empty( $where ) ? '' : 'WHERE ' . implode( ' AND ', $where );
-		$offset    = ( $paged - 1 ) * self::PER_PAGE;
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$total = (int) $wpdb->get_var(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
-			empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
-			? "SELECT COUNT(*) FROM {$table} {$where_sql}"  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
-			: $wpdb->prepare( "SELECT COUNT(*) FROM {$table} {$where_sql}", ...$params )  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
-		);
-
-		$order_sql = 'ORDER BY analyzed_at DESC, relevance_score DESC';
-		$limit_sql = sprintf( 'LIMIT %d OFFSET %d', self::PER_PAGE, $offset );
-		$full_sql  = "SELECT * FROM {$table} {$where_sql} {$order_sql} {$limit_sql}";
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$rows = empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
-		? $wpdb->get_results( $full_sql, ARRAY_A )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
-		: $wpdb->get_results( $wpdb->prepare( $full_sql, ...$params ), ARRAY_A );  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
-
-		return array(
-			'rows'  => $rows ?? array(),
-			'total' => $total,
-		);
-	}
-
-	/** Get counts per analysis_type for the filter badges. */
-	private function get_type_counts(): array {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$rows = $wpdb->get_results(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
-			"SELECT analysis_type, COUNT(*) AS cnt FROM {$table} GROUP BY analysis_type ORDER BY cnt DESC",
-			ARRAY_A
-		);
-
-		$counts = array();
-		foreach ( $rows ?? array() as $row ) {
-			$counts[ $row['analysis_type'] ] = (int) $row['cnt'];
-		}
-		return $counts;
+		delete_transient( $prefix . 'data_' . $idea_id );
 	}
 }

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

@@ -35,282 +35,194 @@ class PRAutoBlogger_Settings_Fields_Extended {
 	 * @return array<int, array<string, mixed>>
 	 */
 	public static function get_fields(): array {
-		return array(
-			// ── Sources (extended) ──────────────────────────────────────
+		return array_merge(
 			array(
-				'id'          => 'prautoblogger_research_model',
-				'label'       => __( 'Research Model', 'prautoblogger' ),
-				'type'        => 'model_select',
-				'section'     => 'prautoblogger_sources',
-				'default'     => PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL,
-				'capability'  => 'text→text',
-				'description' => __( 'Model for LLM Deep Research. Pick a reasoning-capable model (e.g. Grok 4.1 Fast, DeepSeek-R1) for best results. Only used when LLM Deep Research is enabled above.', 'prautoblogger' ),
-				'badge'       => __( 'Reasoning', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_research_prompt',
-				'label'       => __( 'Research Prompt', 'prautoblogger' ),
-				'type'        => 'textarea',
-				'section'     => 'prautoblogger_sources',
-				'default'     => 'Conduct a deep research sweep of the {niche} space and identify the most substantive, actionable topics that practitioners and curious newcomers are searching for or actively discussing.' . "\n\n" . 'Focus on:' . "\n" . '- Practical questions real readers would search for (not theoretical debates)' . "\n" . '- Emerging trends gaining momentum in the community' . "\n" . '- Common misconceptions that deserve clarification' . "\n" . '- Comparative analysis (product vs. product, protocol vs. protocol)' . "\n" . '- Safety and efficacy topics that drive concern or curiosity' . "\n" . '- Beginner-to-advanced mix — cover entry-level and depth-focused topics' . "\n\n" . 'Aim for topics that feel timely, underserved by existing content, and likely to drive reader engagement. Return 8-12 findings with detailed analysis in each.',
-				'description' => __( 'The research brief sent to the LLM. Use {niche} as a placeholder for your niche description. The system prompt handles output format — this controls WHAT to research.', 'prautoblogger' ),
-			),
-
-			// ── AI Models (extended) ────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_reasoning_enabled',
-				'label'       => __( 'Enable Reasoning', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_models',
-				'default'     => '0',
-				'description' => __( 'Send reasoning instructions to models that support it (e.g. Grok, DeepSeek-R1). Reasoning tokens are billed as output tokens — expect higher costs per call. Models that don\'t support reasoning will ignore this.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_reasoning_effort',
-				'label'       => __( 'Reasoning Effort', 'prautoblogger' ),
-				'type'        => 'select',
-				'section'     => 'prautoblogger_models',
-				'default'     => 'medium',
-				'options'     => array(
-					'xhigh'   => __( 'Extra High — maximum depth, highest cost', 'prautoblogger' ),
-					'high'    => __( 'High — thorough reasoning', 'prautoblogger' ),
-					'medium'  => __( 'Medium — balanced (recommended)', 'prautoblogger' ),
-					'low'     => __( 'Low — light reasoning, lower cost', 'prautoblogger' ),
-					'minimal' => __( 'Minimal — barely any reasoning', 'prautoblogger' ),
+				// ── Sources (extended) ──────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_research_model',
+					'label'       => __( 'Research Model', 'prautoblogger' ),
+					'type'        => 'model_select',
+					'section'     => 'prautoblogger_sources',
+					'default'     => PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL,
+					'capability'  => 'text→text',
+					'description' => __( 'Model for LLM Deep Research. Pick a reasoning-capable model (e.g. Grok 4.1 Fast, DeepSeek-R1) for best results. Only used when LLM Deep Research is enabled above.', 'prautoblogger' ),
+					'badge'       => __( 'Reasoning', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_research_prompt',
+					'label'       => __( 'Research Prompt', 'prautoblogger' ),
+					'type'        => 'textarea',
+					'section'     => 'prautoblogger_sources',
+					'default'     => 'Conduct a deep research sweep of the {niche} space and identify the most substantive, actionable topics that practitioners and curious newcomers are searching for or actively discussing.' . "\n\n" . 'Focus on:' . "\n" . '- Practical questions real readers would search for (not theoretical debates)' . "\n" . '- Emerging trends gaining momentum in the community' . "\n" . '- Common misconceptions that deserve clarification' . "\n" . '- Comparative analysis (product vs. product, protocol vs. protocol)' . "\n" . '- Safety and efficacy topics that drive concern or curiosity' . "\n" . '- Beginner-to-advanced mix — cover entry-level and depth-focused topics' . "\n\n" . 'Aim for topics that feel timely, underserved by existing content, and likely to drive reader engagement. Return 8-12 findings with detailed analysis in each.',
+					'description' => __( 'The research brief sent to the LLM. Use {niche} as a placeholder for your niche description. The system prompt handles output format — this controls WHAT to research.', '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' ),
-			),
 
-			// ── Board Settings ─────────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_board_poll_interval',
-				'label'       => __( 'Board Poll Interval (seconds)', 'prautoblogger' ),
-				'type'        => 'number',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => 5,
-				'min'         => 3,
-				'max'         => 60,
-				'description' => __( 'How often the kanban board polls for status updates (seconds). Minimum 3s. Doubles automatically when no article is actively generating.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_board_published_window_days',
-				'label'       => __( 'Published Column Window (days)', 'prautoblogger' ),
-				'type'        => 'number',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => 7,
-				'min'         => 1,
-				'max'         => 90,
-				'description' => __( 'How many days back the Published column shows articles. Increase to see older published articles on the board.', 'prautoblogger' ),
-			),
+				// ── AI Models (extended) ────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_reasoning_enabled',
+					'label'       => __( 'Enable Reasoning', 'prautoblogger' ),
+					'type'        => 'toggle',
+					'section'     => 'prautoblogger_models',
+					'default'     => '0',
+					'description' => __( 'Send reasoning instructions to models that support it (e.g. Grok, DeepSeek-R1). Reasoning tokens are billed as output tokens — expect higher costs per call. Models that don\'t support reasoning will ignore this.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_reasoning_effort',
+					'label'       => __( 'Reasoning Effort', 'prautoblogger' ),
+					'type'        => 'select',
+					'section'     => 'prautoblogger_models',
+					'default'     => 'medium',
+					'options'     => array(
+						'xhigh'   => __( 'Extra High — maximum depth, highest cost', 'prautoblogger' ),
+						'high'    => __( 'High — thorough reasoning', 'prautoblogger' ),
+						'medium'  => __( 'Medium — balanced (recommended)', 'prautoblogger' ),
+						'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' ),
+				),
 
-			// ── Schedule & Budget ───────────────────────────────────────
-			array(
-				'id'      => 'prautoblogger_daily_article_target',
-				'label'   => __( 'Articles per Day', 'prautoblogger' ),
-				'type'    => 'number',
-				'section' => 'prautoblogger_schedule',
-				'default' => 1,
-				'min'     => 1,
-				'max'     => 10,
-			),
-			array(
-				'id'          => 'prautoblogger_schedule_time',
-				'label'       => __( 'Generation Time', 'prautoblogger' ),
-				'type'        => 'time',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => '03:00',
-				'description' => sprintf(
-					/* translators: %s: site timezone string, e.g. "Asia/Singapore". */
-					esc_html__( "Daily generation runs at this time in your site's configured timezone (Settings → General → Timezone). Current site timezone: %s.", 'prautoblogger' ),
-					esc_html( function_exists( 'wp_timezone_string' ) ? wp_timezone_string() : 'UTC' )
+				// ── Board Settings ─────────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_board_poll_interval',
+					'label'       => __( 'Board Poll Interval (seconds)', 'prautoblogger' ),
+					'type'        => 'number',
+					'section'     => 'prautoblogger_schedule',
+					'default'     => 5,
+					'min'         => 3,
+					'max'         => 60,
+					'description' => __( 'How often the kanban board polls for status updates (seconds). Minimum 3s. Doubles automatically when no article is actively generating.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_board_published_window_days',
+					'label'       => __( 'Published Column Window (days)', 'prautoblogger' ),
+					'type'        => 'number',
+					'section'     => 'prautoblogger_schedule',
+					'default'     => 7,
+					'min'         => 1,
+					'max'         => 90,
+					'description' => __( 'How many days back the Published column shows articles. Increase to see older published articles on the board.', 'prautoblogger' ),
+				),
+
+				// ── Schedule & Budget ───────────────────────────────────────
+				array(
+					'id'      => 'prautoblogger_daily_article_target',
+					'label'   => __( 'Articles per Day', 'prautoblogger' ),
+					'type'    => 'number',
+					'section' => 'prautoblogger_schedule',
+					'default' => 1,
+					'min'     => 1,
+					'max'     => 10,
+				),
+				array(
+					'id'          => 'prautoblogger_schedule_time',
+					'label'       => __( 'Generation Time', 'prautoblogger' ),
+					'type'        => 'time',
+					'section'     => 'prautoblogger_schedule',
+					'default'     => '03:00',
+					'description' => sprintf(
+						/* translators: %s: site timezone string, e.g. "Asia/Singapore". */
+						esc_html__( "Daily generation runs at this time in your site's configured timezone (Settings → General → Timezone). Current site timezone: %s.", 'prautoblogger' ),
+						esc_html( function_exists( 'wp_timezone_string' ) ? wp_timezone_string() : 'UTC' )
+					),
+				),
+				array(
+					'id'          => 'prautoblogger_monthly_budget_usd',
+					'label'       => __( 'Monthly Budget (USD)', 'prautoblogger' ),
+					'type'        => 'number',
+					'section'     => 'prautoblogger_schedule',
+					'default'     => 50,
+					'min'         => 0,
+					'step'        => '0.01',
+					'description' => __( 'Hard stop when reached. 0 = unlimited.', 'prautoblogger' ),
+				),
+
+				// ── Publishing ──────────────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_auto_publish',
+					'label'       => __( 'Auto-Publish', 'prautoblogger' ),
+					'type'        => 'toggle',
+					'section'     => 'prautoblogger_publishing',
+					'default'     => '0',
+					'description' => __( 'Automatically publish editor-approved posts. When off, all posts go to the Review Queue as drafts.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_default_author',
+					'label'       => __( 'Default Author', 'prautoblogger' ),
+					'type'        => 'author_select',
+					'section'     => 'prautoblogger_publishing',
+					'default'     => 0,
+					'description' => __( 'WordPress user assigned as author of generated posts.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_default_category',
+					'label'       => __( 'Default Category', 'prautoblogger' ),
+					'type'        => 'category_select',
+					'section'     => 'prautoblogger_publishing',
+					'default'     => 0,
+					'description' => __( 'Fallback category for generated posts.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_log_level',
+					'label'       => __( 'Log Level', 'prautoblogger' ),
+					'type'        => 'select',
+					'section'     => 'prautoblogger_publishing',
+					'default'     => 'info',
+					'options'     => array(
+						'error'   => __( 'Error — only failures', 'prautoblogger' ),
+						'warning' => __( 'Warning — errors + warnings', 'prautoblogger' ),
+						'info'    => __( 'Info — key events (recommended)', 'prautoblogger' ),
+						'debug'   => __( 'Debug — everything (verbose)', 'prautoblogger' ),
+					),
+					'description' => __( 'Controls detail level in the Activity Log.', 'prautoblogger' ),
+				),
+
+				// ── Analytics ───────────────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_ga4_property_id',
+					'label'       => __( 'GA4 Property ID', 'prautoblogger' ),
+					'type'        => 'text',
+					'section'     => 'prautoblogger_analytics',
+					'description' => __( 'Your GA4 Property ID — digits only, e.g. 123456789 (the code adds the "properties/" prefix internally). Find it in GA4 → Admin → Property details. Leave blank to skip GA4.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_ga4_credentials_json',
+					'label'       => __( 'Service Account JSON', 'prautoblogger' ),
+					'type'        => 'password',
+					'section'     => 'prautoblogger_analytics',
+					'description' => __( 'Paste the full JSON key file for a service account with Analytics read access.', 'prautoblogger' ),
+				),
+
+				// ── Display ────────────────────────────────────────────────
+				array(
+					'id'          => 'prautoblogger_article_font_family',
+					'label'       => __( 'Article Font', 'prautoblogger' ),
+					'type'        => 'select',
+					'section'     => 'prautoblogger_display',
+					'default'     => 'default',
+					'options'     => PRAutoBlogger_Article_Typography::get_font_choices(),
+					'description' => __( 'Font family used for generated article body text. Serif fonts improve long-form readability.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_article_font_size',
+					'label'       => __( 'Article Font Size (px)', 'prautoblogger' ),
+					'type'        => 'number',
+					'section'     => 'prautoblogger_display',
+					'default'     => 0,
+					'min'         => 0,
+					'max'         => 32,
+					'description' => __( 'Base font size for article body text. 0 uses the theme default (13px). Recommended: 16–18px for comfortable reading.', 'prautoblogger' ),
+				),
+				array(
+					'id'          => 'prautoblogger_table_borders',
+					'label'       => __( 'Table Borders', 'prautoblogger' ),
+					'type'        => 'toggle',
+					'section'     => 'prautoblogger_display',
+					'default'     => '1',
+					'description' => __( 'Add visible borders, padding, and alternating row colors to tables in generated articles.', 'prautoblogger' ),
 				),
 			),
-			array(
-				'id'          => 'prautoblogger_monthly_budget_usd',
-				'label'       => __( 'Monthly Budget (USD)', 'prautoblogger' ),
-				'type'        => 'number',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => 50,
-				'min'         => 0,
-				'step'        => '0.01',
-				'description' => __( 'Hard stop when reached. 0 = unlimited.', 'prautoblogger' ),
-			),
-
-			// ── Publishing ──────────────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_auto_publish',
-				'label'       => __( 'Auto-Publish', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => '0',
-				'description' => __( 'Automatically publish editor-approved posts. When off, all posts go to the Review Queue as drafts.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_default_author',
-				'label'       => __( 'Default Author', 'prautoblogger' ),
-				'type'        => 'author_select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 0,
-				'description' => __( 'WordPress user assigned as author of generated posts.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_default_category',
-				'label'       => __( 'Default Category', 'prautoblogger' ),
-				'type'        => 'category_select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 0,
-				'description' => __( 'Fallback category for generated posts.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_log_level',
-				'label'       => __( 'Log Level', 'prautoblogger' ),
-				'type'        => 'select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 'info',
-				'options'     => array(
-					'error'   => __( 'Error — only failures', 'prautoblogger' ),
-					'warning' => __( 'Warning — errors + warnings', 'prautoblogger' ),
-					'info'    => __( 'Info — key events (recommended)', 'prautoblogger' ),
-					'debug'   => __( 'Debug — everything (verbose)', 'prautoblogger' ),
-				),
-				'description' => __( 'Controls detail level in the Activity Log.', 'prautoblogger' ),
-			),
-
-			// ── Analytics ───────────────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_ga4_property_id',
-				'label'       => __( 'GA4 Property ID', 'prautoblogger' ),
-				'type'        => 'text',
-				'section'     => 'prautoblogger_analytics',
-				'description' => __( 'Your GA4 Property ID — digits only, e.g. 123456789 (the code adds the "properties/" prefix internally). Find it in GA4 → Admin → Property details. Leave blank to skip GA4.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_ga4_credentials_json',
-				'label'       => __( 'Service Account JSON', 'prautoblogger' ),
-				'type'        => 'password',
-				'section'     => 'prautoblogger_analytics',
-				'description' => __( 'Paste the full JSON key file for a service account with Analytics read access.', 'prautoblogger' ),
-			),
-
-			// ── Display ────────────────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_article_font_family',
-				'label'       => __( 'Article Font', 'prautoblogger' ),
-				'type'        => 'select',
-				'section'     => 'prautoblogger_display',
-				'default'     => 'default',
-				'options'     => PRAutoBlogger_Article_Typography::get_font_choices(),
-				'description' => __( 'Font family used for generated article body text. Serif fonts improve long-form readability.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_article_font_size',
-				'label'       => __( 'Article Font Size (px)', 'prautoblogger' ),
-				'type'        => 'number',
-				'section'     => 'prautoblogger_display',
-				'default'     => 0,
-				'min'         => 0,
-				'max'         => 32,
-				'description' => __( 'Base font size for article body text. 0 uses the theme default (13px). Recommended: 16–18px for comfortable reading.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_table_borders',
-				'label'       => __( 'Table Borders', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_display',
-				'default'     => '1',
-				'description' => __( 'Add visible borders, padding, and alternating row colors to tables in generated articles.', 'prautoblogger' ),
-			),
-
-			// ── Images ─────────────────────────────────────────────────
-			array(
-				'id'          => 'prautoblogger_image_enabled',
-				'label'       => __( 'Enable Image Generation', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_images',
-				'default'     => '0',
-				'description' => __( 'Generate images for each published article.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_b_enabled',
-				'label'       => __( 'Generate Second Image (B)', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_images',
-				'default'     => '1',
-				'description' => __( 'Generate a second image from source data for A/B testing. Disabling saves one image generation + one LLM prompt rewrite per article.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_model',
-				'label'       => __( 'Image Model', 'prautoblogger' ),
-				'type'        => 'model_select',
-				'section'     => 'prautoblogger_images',
-				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL,
-				'capability'  => 'image_generation',
-				'description' => __( 'Pick an image model. The provider (Runware or OpenRouter) is derived from the model registry on save, so mismatched pairs are no longer possible.', 'prautoblogger' ),
-				'badge'       => __( 'Quality', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_runware_api_key',
-				'label'       => __( 'Runware API Key', 'prautoblogger' ),
-				'type'        => 'password',
-				'section'     => 'prautoblogger_images',
-				'description' => __( 'Required when using a Runware FLUX model. Get your key at runware.ai/signup.', 'prautoblogger' ),
-				'icon'        => '🔑',
-			),
-			array(
-				'id'          => 'prautoblogger_image_style_template',
-				'label'       => __( 'Style Template', 'prautoblogger' ),
-				'type'        => 'textarea',
-				'section'     => 'prautoblogger_images',
-				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE,
-				'description' => __( 'The full image prompt template. Must contain exactly one {{ topic_summary }} token, which is filled with a 1-2 sentence topic/mechanism summary per article. The rest is brand-locked editorial style. Replaces the old Style Suffix (now deprecated). Changing mid-run causes visible style drift.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_prompt_instructions',
-				'label'       => __( 'Image Prompt Instructions', 'prautoblogger' ),
-				'type'        => 'textarea',
-				'section'     => 'prautoblogger_images',
-				'default'     => PRAutoBlogger_Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT,
-				'description' => __( 'System prompt given to the rewriter LLM that turns each article into a SCENE (a 1-2 sentence editorial topic/mechanism summary, substituted into the Style Template) plus a CAPTION (HTML text shown below the image). Changing this reshapes the look of all future images. Leave blank to use the default.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_nsfw_retry',
-				'label'       => __( 'Retry NSFW-Blocked Images', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_images',
-				'default'     => '1',
-				'description' => __( 'When the provider rejects an image prompt as NSFW, retry once with a generic fallback scene built from the article title. Disable to fail fast if the filter gets trigger-happy.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_compose_enabled',
-				'label'       => __( 'Compose Branded Variants', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_images',
-				'default'     => '1',
-				'description' => __( 'Render branded social variants (teal band, logo, baked caption) from each generated image via the local deterministic composer. Auto-degrades to plain resizing or pass-through if the server lacks an image library — publishing is never blocked.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_compose_variants',
-				'label'       => __( 'Composed Variant Set', 'prautoblogger' ),
-				'type'        => 'text',
-				'section'     => 'prautoblogger_images',
-				'default'     => 'og,square',
-				'description' => __( 'Comma-separated variants to render for Image A. Supported: og (1200×630 social share), square (1080×1080 card). Unknown values are ignored.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_image_featured_mark_enabled',
-				'label'       => __( 'Featured Image Corner Mark', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_images',
-				'default'     => '1',
-				'description' => __( 'Overlay a small semi-transparent Peptide Repo mark in the bottom-right corner of featured images, so scraped or re-shared images carry attribution.', 'prautoblogger' ),
-			),
-			array(
-				'id'          => 'prautoblogger_runware_model_catalog',
-				'label'       => __( 'Runware Model Catalog', 'prautoblogger' ),
-				'type'        => 'runware_catalog_sync',
-				'section'     => 'prautoblogger_images',
-				'description' => __( 'Live model catalog sync status and on-demand refresh.', 'prautoblogger' ),
-			),
+			PRAutoBlogger_Settings_Fields_Images::get_fields()
 		);
 	}
 }

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

@@ -0,0 +1,123 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Image settings fields for PRAutoBlogger.
+ *
+ * Declarative field definitions for the Images section of the settings page.
+ * Extracted from PRAutoBlogger_Settings_Fields_Extended for 300-line compliance.
+ *
+ * What: Returns the images-section field array consumed by the settings registry.
+ * Who triggers: PRAutoBlogger_Settings_Fields_Extended::get_fields() via merge.
+ * Dependencies: PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL, PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE,
+ *               PRAutoBlogger_Image_Prompt_Builder, PRAutoBlogger_Image_Model_Registry.
+ *
+ * @see admin/class-settings-fields-extended.php -- Merges these fields in get_fields().
+ * @see admin/class-admin-page.php               -- Renders the fields.
+ * @see CONVENTIONS.md                           -- "How To: Add a New Admin Setting".
+ */
+class PRAutoBlogger_Settings_Fields_Images {
+
+	/**
+	 * Get image generation settings fields.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_fields(): array {
+		return array(
+
+			// ── Images ─────────────────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_image_enabled',
+				'label'       => __( 'Enable Image Generation', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '0',
+				'description' => __( 'Generate images for each published article.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_b_enabled',
+				'label'       => __( 'Generate Second Image (B)', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Generate a second image from source data for A/B testing. Disabling saves one image generation + one LLM prompt rewrite per article.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_model',
+				'label'       => __( 'Image Model', 'prautoblogger' ),
+				'type'        => 'model_select',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL,
+				'capability'  => 'image_generation',
+				'description' => __( 'Pick an image model. The provider (Runware or OpenRouter) is derived from the model registry on save, so mismatched pairs are no longer possible.', 'prautoblogger' ),
+				'badge'       => __( 'Quality', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_runware_api_key',
+				'label'       => __( 'Runware API Key', 'prautoblogger' ),
+				'type'        => 'password',
+				'section'     => 'prautoblogger_images',
+				'description' => __( 'Required when using a Runware FLUX model. Get your key at runware.ai/signup.', 'prautoblogger' ),
+				'icon'        => '🔑',
+			),
+			array(
+				'id'          => 'prautoblogger_image_style_template',
+				'label'       => __( 'Style Template', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE,
+				'description' => __( 'The full image prompt template. Must contain exactly one {{ topic_summary }} token, which is filled with a 1-2 sentence topic/mechanism summary per article. The rest is brand-locked editorial style. Replaces the old Style Suffix (now deprecated). Changing mid-run causes visible style drift.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_prompt_instructions',
+				'label'       => __( 'Image Prompt Instructions', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAutoBlogger_Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT,
+				'description' => __( 'System prompt given to the rewriter LLM that turns each article into a SCENE (a 1-2 sentence editorial topic/mechanism summary, substituted into the Style Template) plus a CAPTION (HTML text shown below the image). Changing this reshapes the look of all future images. Leave blank to use the default.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_nsfw_retry',
+				'label'       => __( 'Retry NSFW-Blocked Images', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'When the provider rejects an image prompt as NSFW, retry once with a generic fallback scene built from the article title. Disable to fail fast if the filter gets trigger-happy.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_compose_enabled',
+				'label'       => __( 'Compose Branded Variants', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Render branded social variants (teal band, logo, baked caption) from each generated image via the local deterministic composer. Auto-degrades to plain resizing or pass-through if the server lacks an image library — publishing is never blocked.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_compose_variants',
+				'label'       => __( 'Composed Variant Set', 'prautoblogger' ),
+				'type'        => 'text',
+				'section'     => 'prautoblogger_images',
+				'default'     => 'og,square',
+				'description' => __( 'Comma-separated variants to render for Image A. Supported: og (1200×630 social share), square (1080×1080 card). Unknown values are ignored.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_featured_mark_enabled',
+				'label'       => __( 'Featured Image Corner Mark', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Overlay a small semi-transparent Peptide Repo mark in the bottom-right corner of featured images, so scraped or re-shared images carry attribution.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_runware_model_catalog',
+				'label'       => __( 'Runware Model Catalog', 'prautoblogger' ),
+				'type'        => 'runware_catalog_sync',
+				'section'     => 'prautoblogger_images',
+				'description' => __( 'Live model catalog sync status and on-demand refresh.', 'prautoblogger' ),
+			),
+		);
+	}
+}

includes/admin/class-settings-sanitizer.php

@@ -0,0 +1,107 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Settings field sanitizer for PRAutoBlogger.
+ *
+ * Centralises all option sanitization logic: encryption for API keys, JSON
+ * encoding for multi-value fields, numeric coercion, image-model registry
+ * validation. Extracted from PRAutoBlogger_Admin_Page for 300-line compliance.
+ *
+ * What: Static utility called by register_setting() sanitize_callback.
+ * Who triggers: WordPress Settings API on option save; PRAutoBlogger_Admin_Page::sanitize_field().
+ * Dependencies: PRAutoBlogger_Encryption, PRAutoBlogger_Image_Model_Registry,
+ *               PRAutoBlogger_Image_Template_Filler.
+ *
+ * @see admin/class-admin-page.php            -- Registers settings and delegates here.
+ * @see admin/class-image-model-registry.php  -- Validates image model slug on save.
+ * @see CONVENTIONS.md                        -- "How To: Add a New Admin Setting".
+ */
+class PRAutoBlogger_Settings_Sanitizer {
+
+	/**
+	 * Sanitize a settings field value.
+	 *
+	 * @param mixed $value The submitted value.
+	 * @return mixed Sanitized value.
+	 */
+	public static function sanitize_field( $value ) {
+		$option_name = '';
+		$filter      = current_filter();
+		if ( 0 === strpos( $filter, 'sanitize_option_' ) ) {
+			$option_name = substr( $filter, strlen( 'sanitize_option_' ) );
+		}
+
+		$encrypted = array( 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json', 'prautoblogger_runware_api_key' );
+		if ( in_array( $option_name, $encrypted, true ) ) {
+			// Empty value means password field wasn't touched — keep existing.
+			if ( '' === $value ) {
+				return get_option( $option_name, '' );
+			}
+
+			// Already encrypted (has "enc:" prefix) — return as-is.
+			// This is the primary defence against double-encryption:
+			// PRAutoBlogger_Encryption::encrypt() also checks for this prefix,
+			// so even if this callback is called multiple times, the value
+			// is encrypted exactly once and never re-encrypted.
+			if ( PRAutoBlogger_Encryption::is_encrypted( $value ) ) {
+				return $value;
+			}
+
+			// New plaintext value — encrypt it (adds "enc:" prefix).
+			return PRAutoBlogger_Encryption::encrypt( sanitize_text_field( $value ) );
+		}
+
+		$json_fields = array( 'prautoblogger_target_subreddits', 'prautoblogger_topic_exclusions', 'prautoblogger_enabled_sources' );
+		if ( in_array( $option_name, $json_fields, true ) ) {
+			// PHP array from checkboxes — sanitize each item and re-encode.
+			if ( is_array( $value ) ) {
+				return wp_json_encode( array_values( array_map( 'sanitize_text_field', $value ) ) );
+			}
+
+			$trimmed = trim( (string) $value );
+
+			// Already JSON-encoded array — decode, sanitize each item, re-encode.
+			// This prevents sanitize_text_field() from mangling the JSON string,
+			// which caused json_decode() on read to return null → empty subreddits.
+			if ( '[' === substr( $trimmed, 0, 1 ) ) {
+				$decoded = json_decode( $trimmed, true );
+				if ( is_array( $decoded ) ) {
+					return wp_json_encode( array_values( array_map( 'sanitize_text_field', $decoded ) ) );
+				}
+			}
+
+			// Comma-separated plain text — split, sanitize, encode as JSON array.
+			$items = array_filter( array_map( 'trim', explode( ',', $trimmed ) ) );
+			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', 'prautoblogger_board_poll_interval', 'prautoblogger_board_published_window_days', 'prautoblogger_board_column_limit', 'prautoblogger_ideas_per_page' );
+		if ( in_array( $option_name, $numeric, true ) ) {
+			return is_numeric( $value ) ? $value : 0;
+		}
+		if ( 'prautoblogger_image_model' === $option_name ) {
+			return self::sanitize_image_model( (string) $value );
+		}
+		if ( 'prautoblogger_image_style_template' === $option_name ) {
+			// Multi-line template: validation + textarea-safe sanitisation
+			// (incl. the single-token check, brief A5) lives in the filler.
+			return PRAutoBlogger_Image_Template_Filler::sanitize_for_save( (string) $value );
+		}
+		return sanitize_text_field( (string) $value );
+	}
+
+	/** Validate model id against the registry and persist the derived provider. */
+	private static function sanitize_image_model( string $value ): string {
+		$candidate = sanitize_text_field( $value );
+		$provider  = PRAutoBlogger_Image_Model_Registry::provider_for( $candidate );
+		if ( '' !== $provider ) {
+			update_option( 'prautoblogger_image_provider', $provider );
+			return $candidate;
+		}
+		add_settings_error( 'prautoblogger_image_model', 'prautoblogger_image_model_unknown', sprintf( esc_html__( 'Image model "%s" is not in the registry. Keeping the previous selection.', 'prautoblogger' ), esc_html( $candidate ) ) );
+		return (string) get_option( 'prautoblogger_image_model', PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL );
+	}
+}

includes/admin/class-wp-cli-commands.php

@@ -8,6 +8,14 @@ declare(strict_types=1);
  */
 class PRAutoBlogger_WP_CLI_Commands {
 
+	/**
+	 * Max generate-tick iterations for the --sync loop (covers daily_article_target = 1
+	 * with ample headroom; prevents infinite loops if the queue never drains).
+	 *
+	 * @var int
+	 */
+	private const SYNC_MAX_TICKS = 20;
+
 	/**
 	 * Register WP-CLI commands.
 	 *
@@ -18,7 +26,22 @@ class PRAutoBlogger_WP_CLI_Commands {
 			return;
 		}
 
-		// Command: wp prautoblogger opik:eval
+		\WP_CLI::add_command(
+			'prautoblogger generate',
+			array( self::class, 'generate_command' ),
+			array(
+				'shortdesc' => 'Queue (or synchronously run) a new article generation run',
+				'synopsis'  => array(
+					array(
+						'type'        => 'flag',
+						'name'        => 'sync',
+						'description' => 'Run the full pipeline synchronously in this process (VPS orchestrator mode). Blocks until complete.',
+						'optional'    => true,
+					),
+				),
+			)
+		);
+
 		\WP_CLI::add_command(
 			'prautoblogger opik:eval',
 			array( self::class, 'opik_eval_command' ),
@@ -43,6 +66,148 @@ class PRAutoBlogger_WP_CLI_Commands {
 		);
 	}
 
+	/**
+	 * Queue or synchronously run a new article generation run.
+	 *
+	 * Without --sync: routes through kick_off() (same as the board "New Article"
+	 * button). Returns immediately; all pipeline work happens in cron.
+	 *
+	 * With --sync: runs the pipeline synchronously in this SSH/CLI process.
+	 *   1. Acquires the generation lock (skips if a live run is in progress).
+	 *   2. Calls on_orchestrate_tick() to collect/score ideas in-process.
+	 *   3. Loops calling on_generate_tick() until the queue is empty or the run
+	 *      reaches a terminal state, up to SYNC_MAX_TICKS iterations.
+	 *   4. Emits a JSON summary line on stdout and exits 0 (success) or 1 (error).
+	 *
+	 * The --sync path suppresses wp-cron reschedule inside on_generate_tick() so
+	 * the external loop cannot race with a background cron tick.
+	 *
+	 * ## OPTIONS
+	 *
+	 * [--sync]
+	 * : Run synchronously (VPS orchestrator mode).
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     wp prautoblogger generate
+	 *     wp prautoblogger generate --sync
+	 *
+	 * @param array $args       Positional args (unused).
+	 * @param array $assoc_args Associative args: sync.
+	 * @return void
+	 */
+	public static function generate_command( array $args, array $assoc_args ): void {
+		if ( isset( $assoc_args['sync'] ) ) {
+			self::run_sync();
+			return;
+		}
+
+		PRAutoBlogger_Generation_Checkpoint_Runner::kick_off();
+		\WP_CLI::success( 'Generation queued on chained-cron checkpoints. Check the board or Activity Log for progress.' );
+	}
+
+	/**
+	 * Run the full pipeline synchronously in this process (--sync mode).
+	 *
+	 * Called only from generate_command(); never from wp-cron or AJAX paths.
+	 *
+	 * @return void
+	 */
+	private static function run_sync(): void {
+		// Honour ignore_user_abort so a dropped SSH session does not kill us.
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+
+		// Check for a live (non-expired) lock. Generation_Lock::acquire() already
+		// cleans expired locks on its DELETE pass, so if acquire() returns false
+		// there is a genuinely live concurrent run — skip cleanly.
+		if ( ! PRAutoBlogger_Generation_Lock::is_locked() ) {
+			// Lock is not held; proceed. acquire() is called inside on_orchestrate_tick().
+		} else {
+			$acquired_at = PRAutoBlogger_Generation_Lock::get_acquired_at();
+			$age         = null !== $acquired_at ? ( time() - $acquired_at ) : HOUR_IN_SECONDS;
+			if ( $age < HOUR_IN_SECONDS ) {
+				\WP_CLI::log(
+					json_encode(
+						array(
+							'status' => 'skipped',
+							'reason' => 'run_in_progress',
+							'lock_age_s' => $age,
+						)
+					)
+				);
+				exit( 0 );
+			}
+			// Expired lock — on_orchestrate_tick()'s acquire() will clean it.
+		}
+
+		// Enable sync-mode: on_generate_tick() will skip the wp-cron reschedule.
+		PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( true );
+
+		\WP_CLI::log( 'PRAB-SYNC: starting orchestrate tick' );
+		PRAutoBlogger_Generation_Checkpoint_Runner::on_orchestrate_tick();
+
+		// If the orchestrate tick failed to acquire the lock or found no ideas,
+		// the RUN_ID option will be absent. Detect and exit cleanly.
+		$run_id = (string) get_option( 'prautoblogger_checkpoint_run_id', '' );
+		if ( '' === $run_id ) {
+			$queue = get_option( 'prautoblogger_article_queue' );
+			if ( ! is_array( $queue ) || empty( $queue['ideas'] ) ) {
+				\WP_CLI::log(
+					json_encode(
+						array(
+							'status' => 'done',
+							'generated' => 0,
+							'reason' => 'no_ideas_or_lock_failed',
+						)
+					)
+				);
+				exit( 0 );
+			}
+		}
+
+		// Tick loop: drive generate ticks synchronously.
+		$ticks = 0;
+		while ( $ticks < self::SYNC_MAX_TICKS ) {
+			$queue = get_option( 'prautoblogger_article_queue' );
+			if ( ! is_array( $queue ) || empty( $queue['ideas'] ) ) {
+				break; // Queue drained or finalized.
+			}
+			++$ticks;
+			\WP_CLI::log( sprintf( 'PRAB-SYNC: generate tick %d (ideas remaining: %d)', $ticks, count( $queue['ideas'] ) ) );
+			PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+		}
+
+		PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( false );
+
+		if ( $ticks >= self::SYNC_MAX_TICKS ) {
+			\WP_CLI::warning( 'PRAB-SYNC: hit max-tick guard (' . self::SYNC_MAX_TICKS . '). Queue may not be fully drained.' );
+		}
+
+		// Read final status transient for summary.
+		$status = get_transient( 'prautoblogger_generation_status' );
+		$result = is_array( $status ) ? $status : array();
+
+		$summary = array(
+			'status'     => 'done',
+			'generated'  => (int) ( $result['generated'] ?? 0 ),
+			'published'  => (int) ( $result['published'] ?? 0 ),
+			'rejected'   => (int) ( $result['rejected'] ?? 0 ),
+			'cost_usd'   => round( (float) ( $result['cost'] ?? 0.0 ), 4 ),
+			'ticks'      => $ticks,
+		);
+
+		\WP_CLI::log( json_encode( $summary ) );
+
+		if ( 'error' === ( $result['status'] ?? '' ) ) {
+			\WP_CLI::error( 'PRAB-SYNC: generation completed with error: ' . ( $result['message'] ?? 'unknown' ), false );
+			exit( 1 );
+		}
+
+		\WP_CLI::success( 'PRAB-SYNC: generation complete.' );
+		exit( 0 );
+	}
+
 	/**
 	 * Run eval on the frozen dataset.
 	 *

includes/class-activator.php

@@ -80,7 +80,10 @@ class PRAutoBlogger_Activator {
 			'prautoblogger_table_borders'        => '1',
 			'prautoblogger_schedule_time'        => '03:00',
 			'prautoblogger_log_level'            => 'info',
-			'prautoblogger_image_nsfw_retry'     => '1',
+			'prautoblogger_image_nsfw_retry'       => '1',
+			// M4 (v0.21.0): board column card limit + ideas page size -- settings-backed.
+			'prautoblogger_board_column_limit'     => PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT,
+			'prautoblogger_ideas_per_page'         => PRAUTOBLOGGER_DEFAULT_IDEAS_PER_PAGE,
 		);
 
 		foreach ( $defaults as $key => $value ) {

includes/class-db-migrations.php

@@ -125,5 +125,32 @@ class PRAutoBlogger_DB_Migrations {
 			}
 			update_option( 'prautoblogger_migrated_enc_prefix', '1' );
 		}
+
+		// v0.22.1 self-heal: restore low-stakes maintenance cron events that were
+		// lost when the WP-Cron schedule vanished after the 06-15 deploy cycle.
+		// NOTE: wp-cron reliability on this Hostinger host is suspect (background
+		// PHP processes are killed at ~10 min). These low-stakes events (metrics,
+		// reaper, Runware sync) are acceptable on wp-cron; daily GENERATION is NOT
+		// re-registered here — the VPS systemd timer owns generation scheduling.
+		// The prautoblogger_migrated_schedule_tz_v082 guard is intentionally NOT
+		// re-used here; this migration targets the missing events themselves.
+		if ( ! get_option( 'prautoblogger_migrated_maintenance_crons_v0221' ) ) {
+			// Re-register maintenance crons only — daily_generation deliberately excluded.
+			// Activator::schedule_cron() uses wp_next_scheduled() guards so it is
+			// idempotent and will not overwrite events that are already present.
+			if ( ! wp_next_scheduled( 'prautoblogger_reap_orphan_research_rows' ) ) {
+				$tomorrow_reap = strtotime( 'tomorrow 03:15' );
+				if ( false !== $tomorrow_reap ) {
+					wp_schedule_event( (int) $tomorrow_reap, 'daily', 'prautoblogger_reap_orphan_research_rows' );
+				}
+			}
+			if ( ! wp_next_scheduled( 'prautoblogger_collect_metrics' ) ) {
+				wp_schedule_event( time() + HOUR_IN_SECONDS, 'prautoblogger_six_hours', 'prautoblogger_collect_metrics' );
+			}
+			if ( ! wp_next_scheduled( 'prautoblogger_sync_runware_models' ) ) {
+				wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', 'prautoblogger_sync_runware_models' );
+			}
+			update_option( 'prautoblogger_migrated_maintenance_crons_v0221', '1' );
+		}
 	}
 }

includes/class-executor.php

@@ -85,68 +85,21 @@ class PRAutoBlogger_Executor {
 	}
 
 	/**
-	 * Cron handler: runs pipeline orchestration + first article.
+	 * Cron handler: kick off the chained-cron orchestration tick (v0.21.0, M4).
 	 *
-	 * If the pipeline queues additional articles (2..N), they will fire as
-	 * chained cron events — each in its own PHP process. The lock is released
-	 * by the pipeline when the last article completes, not here.
+	 * Delegates to Generation_Checkpoint_Runner::on_orchestrate_tick() which
+	 * runs Tick 1 (collect -> analyze -> score), then schedules Tick 2..N for
+	 * article generation. This replaces the former monolithic pipeline run and
+	 * retires the SSH-only `do_action("prautoblogger_manual_generation")` workaround
+	 * (see ARCHITECTURE.md ss25).
+	 *
+	 * Lock acquisition and status transient writes are fully owned by the
+	 * checkpoint runner; this method is a thin routing wrapper.
+	 *
+	 * @return void
 	 */
 	public function on_manual_generation(): void {
-		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
-		@ignore_user_abort( true );
-		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
-		@set_time_limit( 300 );
-
-		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
-			set_transient(
-				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
-				array(
-					'status'  => 'error',
-					'message' => __( 'Could not acquire generation lock. Another run may be in progress.', 'prautoblogger' ),
-				),
-				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
-			);
-			return;
-		}
-
-		try {
-			$this->poller()->update_generation_stage( __( 'Collecting sources from Reddit...', 'prautoblogger' ) );
-
-			$runner  = ( new PRAutoBlogger_Pipeline_Runner() )->set_skip_dedup( true );
-			$results = $runner->run();
-
-			// If no articles were queued (target=1 or 0 ideas), finalize here.
-			// When articles ARE queued, the pipeline handles status + lock release.
-			if ( ! get_option( 'prautoblogger_article_queue' ) ) {
-				set_transient(
-					PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
-					array(
-						'status'    => 'complete',
-						'generated' => $results['generated'],
-						'published' => $results['published'],
-						'rejected'  => $results['rejected'],
-						'cost'      => $results['cost'],
-					),
-					PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
-				);
-				PRAutoBlogger_Generation_Lock::release();
-			}
-		} catch ( \Throwable $e ) {
-			PRAutoBlogger_Logger::instance()->error(
-				sprintf( 'Manual generation %s: %s', get_class( $e ), $e->getMessage() ),
-				'pipeline'
-			);
-			set_transient(
-				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
-				array(
-					'status'  => 'error',
-					'message' => $e->getMessage(),
-				),
-				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
-			);
-			$this->mark_current_run_failed();
-			PRAutoBlogger_Generation_Lock::release();
-		}
+		PRAutoBlogger_Generation_Checkpoint_Runner::on_orchestrate_tick();
 	}
 
 	/** Cron handler: process next queued article. Chained by Pipeline_Runner. */

includes/class-pipeline-schema-installer.php

@@ -4,12 +4,14 @@ declare(strict_types=1);
 /**
  * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
  *
- * Creates / updates the Pipeline v2 substrate tables via `dbDelta` (db 1.2.0).
+ * Creates / updates the Pipeline v2 substrate tables via `dbDelta` (db 1.3.0).
  *
- * What: Owns the five v0.18.0 substrate tables — the versioned prompt
+ * What: Owns the six pipeline substrate tables — the versioned prompt
  *       registry (`prompts`), the audit child tables (`run_sources`,
  *       `run_decisions`), and the run ledger / state machine tables
- *       (`runs`, `run_stages`). Kept separate from the original
+ *       (`runs`, `run_stages`), and the immutable stage-input version
+ *       store (`stage_inputs`, v0.20.0 / db 1.3.0 — edit + re-run forks
+ *       and idea seeds). Kept separate from the original
  *       PRAutoBlogger_Schema_Installer so both classes stay under the
  *       300-line cap and the v1.1.0 schema remains byte-stable.
  * Who triggers it: PRAutoBlogger_Activator::activate() — on activation and
@@ -33,7 +35,7 @@ class PRAutoBlogger_Pipeline_Schema_Installer {
 	 * plugin's forward-only schema policy. Safe to re-run on every
 	 * version mismatch.
 	 *
-	 * Side effects: up to five CREATE TABLE / ALTER TABLE statements.
+	 * Side effects: up to six CREATE TABLE / ALTER TABLE statements.
 	 *
 	 * @return void
 	 */
@@ -91,6 +93,7 @@ class PRAutoBlogger_Pipeline_Schema_Installer {
 			verdict VARCHAR(50) NOT NULL,
 			rationale TEXT DEFAULT NULL,
 			citation_score FLOAT DEFAULT NULL,
+			human_modified TINYINT(1) NOT NULL DEFAULT 0,
 			created_at DATETIME NOT NULL,
 			PRIMARY KEY (id),
 			KEY run_id (run_id)
@@ -112,7 +115,8 @@ class PRAutoBlogger_Pipeline_Schema_Installer {
 			updated_at DATETIME NOT NULL,
 			finished_at DATETIME DEFAULT NULL,
 			PRIMARY KEY (run_id),
-			KEY status (status)
+			KEY status (status),
+			KEY started_at (started_at)
 		) {$charset_collate};";
 
 		// Per-run per-stage state rows. The idempotency key is
@@ -130,6 +134,8 @@ class PRAutoBlogger_Pipeline_Schema_Installer {
 			attempt SMALLINT UNSIGNED NOT NULL DEFAULT 1,
 			cost_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
 			meta_json LONGTEXT DEFAULT NULL,
+			human_modified TINYINT(1) NOT NULL DEFAULT 0,
+			stale TINYINT(1) NOT NULL DEFAULT 0,
 			started_at DATETIME NOT NULL,
 			updated_at DATETIME NOT NULL,
 			finished_at DATETIME DEFAULT NULL,
@@ -138,10 +144,37 @@ class PRAutoBlogger_Pipeline_Schema_Installer {
 			KEY status_updated (status, updated_at)
 		) {$charset_collate};";
 
+		// Immutable stage-input version store (v0.20.0 / db 1.3.0, M3
+		// edit + re-run). Rows are INSERT-only: a human edit creates the
+		// next (scope, version) row -- the original input (the
+		// generation_log.request_json of the executed call) is never
+		// overwritten (CPO guardrail 1). source='seed' rows persist the
+		// Article_Idea payload at worker start so re-run-from-here can
+		// reconstruct the exact idea (item_key hash stability); 'human'
+		// rows are edit forks. Human fork bodies are retention-pruned
+		// like all heavy payloads; seed rows (~1KB) are structural and
+		// kept for the life of the run.
+		$sql_stage_inputs = "CREATE TABLE {$prefix}stage_inputs (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			run_id VARCHAR(36) NOT NULL,
+			stage VARCHAR(50) NOT NULL DEFAULT '',
+			agent_role VARCHAR(50) NOT NULL DEFAULT '',
+			item_key VARCHAR(64) NOT NULL DEFAULT '',
+			version INT UNSIGNED NOT NULL DEFAULT 1,
+			source VARCHAR(20) NOT NULL DEFAULT 'human',
+			request_json LONGTEXT DEFAULT NULL,
+			author VARCHAR(100) NOT NULL DEFAULT '',
+			created_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			UNIQUE KEY scope_version (run_id, stage, agent_role, item_key, version),
+			KEY run_id (run_id)
+		) {$charset_collate};";
+
 		dbDelta( $sql_prompts );
 		dbDelta( $sql_run_sources );
 		dbDelta( $sql_run_decisions );
 		dbDelta( $sql_runs );
 		dbDelta( $sql_run_stages );
+		dbDelta( $sql_stage_inputs );
 	}
 }

includes/class-prautoblogger.php

@@ -141,6 +141,15 @@ class PRAutoBlogger {
 			new PRAutoBlogger_Opik_Settings();
 		}
 
+		// v0.20.0 (M3): operator re-run jobs — chained-cron, never synchronous.
+		$rerun_executor = new PRAutoBlogger_Rerun_Executor();
+		add_action( PRAutoBlogger_Rerun_Executor::REPLAY_ACTION, array( $rerun_executor, 'on_replay_job' ), 10, 5 );
+		add_action( PRAutoBlogger_Rerun_Executor::REBUILD_ACTION, array( $rerun_executor, 'on_rebuild_job' ), 10, 4 );
+
+		// v0.21.0 (M4): chained-cron checkpoint ticks for new article generation.
+		add_action( PRAutoBlogger_Generation_Checkpoint_Runner::ORCHESTRATE_ACTION, array( 'PRAutoBlogger_Generation_Checkpoint_Runner', 'on_orchestrate_tick' ) );
+		add_action( PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION, array( 'PRAutoBlogger_Generation_Checkpoint_Runner', 'on_generate_tick' ) );
+
 		add_action( 'prautoblogger_generate_from_idea', array( 'PRAutoBlogger_Ideas_Browser', 'on_cron_generate_from_idea' ) );
 		add_action( 'prautoblogger_reap_orphan_research_rows', array( 'PRAutoBlogger_Research_Reaper', 'on_cron' ) );
 		add_action( 'prautoblogger_reap_orphan_research_rows', array( 'PRAutoBlogger_Run_Reaper', 'on_cron' ) );
@@ -174,6 +183,13 @@ class PRAutoBlogger {
 		add_action( 'wp_ajax_prautoblogger_clear_logs', array( new PRAutoBlogger_Log_Viewer(), 'on_ajax_clear_logs' ) );
 		add_action( 'wp_ajax_' . PRAutoBlogger_Board_Page::AJAX_ACTION, array( new PRAutoBlogger_Board_Page(), 'on_ajax_board_status' ) );
 
+		// v0.20.0 (M3): dossier edit + re-run endpoints (validate + queue only).
+		$dossier_actions = new PRAutoBlogger_Dossier_Actions();
+		add_action( 'wp_ajax_prautoblogger_dossier_save_input', array( $dossier_actions, 'on_save_input' ) );
+		add_action( 'wp_ajax_prautoblogger_dossier_rerun_stage', array( $dossier_actions, 'on_rerun_stage' ) );
+		add_action( 'wp_ajax_prautoblogger_dossier_rerun_from', array( $dossier_actions, 'on_rerun_from' ) );
+		add_action( 'wp_ajax_prautoblogger_dossier_stage_status', array( $dossier_actions, 'on_stage_status' ) );
+
 		$ideas = new PRAutoBlogger_Ideas_Browser();
 		add_action( 'wp_ajax_prautoblogger_generate_from_idea', array( $ideas, 'on_ajax_generate_from_idea' ) );
 		add_action( 'wp_ajax_prautoblogger_idea_gen_status', array( $ideas, 'on_ajax_idea_gen_status' ) );

includes/class-schema-installer.php

@@ -71,7 +71,8 @@ class PRAutoBlogger_Schema_Installer {
 			metadata_json LONGTEXT DEFAULT NULL,
 			PRIMARY KEY (id),
 			KEY type_relevance (analysis_type, relevance_score),
-			KEY analyzed_at (analyzed_at)
+			KEY analyzed_at (analyzed_at),
+			KEY analyzed_type (analyzed_at, analysis_type)
 		) {$charset_collate};";
 
 		// Generation log — every API call with cost tracking. `run_id`
@@ -100,7 +101,9 @@ class PRAutoBlogger_Schema_Installer {
 			KEY post_id (post_id),
 			KEY run_id (run_id),
 			KEY created_at (created_at),
-			KEY stage (stage)
+			KEY stage (stage),
+			KEY run_id_post_id (run_id, post_id),
+			KEY created_status (created_at, response_status)
 		) {$charset_collate};";
 
 		// Content scores — post performance metrics for self-improvement.

includes/core/class-article-worker.php

@@ -58,6 +58,13 @@ class PRAutoBlogger_Article_Worker {
 		$run_id = (string) ( $this->cost_tracker->get_run_id() ?? '' );
 		$item   = PRAutoBlogger_Run_Stage_State::item_key_for_idea( $idea );
 
+		// v0.20.0: persist the EXACT idea payload once per item so
+		// re-run-from-here can reconstruct it (rebuilding from post
+		// fields would risk an item_key hash mismatch -> duplicate post).
+		if ( '' !== $run_id ) {
+			PRAutoBlogger_Stage_Input_Store::save_seed( $run_id, $item, (string) wp_json_encode( $idea->to_array() ) );
+		}
+
 		$result = array(
 			'generated' => 0,
 			'published' => 0,

includes/core/class-audit-writer.php

@@ -125,6 +125,37 @@ class PRAutoBlogger_Audit_Writer {
 		}
 	}
 
+	/**
+	 * Flag the run_decisions rows of given stages as human-modified
+	 * (v0.20.0 / CPO guardrail 2). Used in two cases: the decision rows of
+	 * a stage whose edited input enters execution, and decisions recorded
+	 * during a re-run-from-here window on an item that carries a human
+	 * edit (derived-from-edited-content). Self-healing no-op when the
+	 * column/table is missing.
+	 *
+	 * @param string        $run_id Run UUID.
+	 * @param array<string> $stages Stage names to flag.
+	 * @param string|null   $since  Optional MySQL datetime — only flag rows created at/after it.
+	 * @return int Rows flagged.
+	 */
+	public static function flag_decisions_human_modified( string $run_id, array $stages, ?string $since = null ): int {
+		if ( '' === $run_id || empty( $stages ) || ! self::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table        = $wpdb->prefix . 'prautoblogger_run_decisions';
+		$placeholders = implode( ',', array_fill( 0, count( $stages ), '%s' ) );
+		$sql          = "UPDATE {$table} SET human_modified = 1 WHERE run_id = %s AND stage IN ({$placeholders})";
+		$params       = array_merge( array( $run_id ), array_values( $stages ) );
+		if ( null !== $since ) {
+			$sql     .= ' AND created_at >= %s';
+			$params[] = $since;
+		}
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %s list.
+		$updated = $wpdb->query( $wpdb->prepare( $sql, $params ) );
+		return is_numeric( $updated ) ? (int) $updated : 0;
+	}
+
 	/** Reset per-request caches (tests). */
 	public static function flush_cache(): void {
 		self::$tables_ok = null;

includes/core/class-cost-tracker.php

@@ -69,7 +69,9 @@ class PRAutoBlogger_Cost_Tracker {
 	/**
 	 * Log an API call with its token usage and estimated cost.
 	 *
-	 * Side effects: database insert into prab_generation_log.
+	 * Side effects: database insert into prab_generation_log. Consumes the
+	 * Request_Recorder stash (v0.20.0 / B1) into the row's request_json so
+	 * every chat call's input is persisted (retention-pruned after R days).
 	 *
 	 * @param int|null    $post_id           WordPress post ID (null during generation, set later).
 	 * @param string      $stage             Pipeline stage (see PRAutoBlogger_Stage_Display_Map).
@@ -117,6 +119,7 @@ class PRAutoBlogger_Cost_Tracker {
 				'estimated_cost'    => $cost,
 				'response_status'   => $response_status,
 				'error_message'     => $error_message,
+				'request_json'      => PRAutoBlogger_Request_Recorder::consume(),
 				'agent_role'        => $agent_role ?? PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage ),
 				'prompt_version'    => $this->resolve_prompt_version( $stage, $prompt_key ),
 				'created_at'        => current_time( 'mysql' ),

includes/core/class-generation-checkpoint-helpers.php

@@ -0,0 +1,71 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Private helpers for PRAutoBlogger_Generation_Checkpoint_Runner (v0.21.0, M4).
+ *
+ * Extracted to keep class-generation-checkpoint-runner.php under the 300-line
+ * cap (CONVENTIONS §1). Contains the three internal-only static methods:
+ *   finalize()       — write final transient, mark run done, release lock.
+ *   cleanup_queue()  — delete queue + run-id options on abort paths.
+ *   fire_cron_now()  — non-blocking loopback to fire cron events immediately.
+ *
+ * Only PRAutoBlogger_Generation_Checkpoint_Runner should call this class.
+ *
+ * @see core/class-generation-checkpoint-runner.php — Caller / orchestrator.
+ * @see ARCHITECTURE.md ss25                        — Checkpoint design.
+ */
+class PRAutoBlogger_Generation_Checkpoint_Helpers {
+
+	/** Option key for the checkpoint queue (mirrors Runner constant). */
+	private const QUEUE_KEY = 'prautoblogger_article_queue';
+
+	/** Option key for the in-progress run UUID (mirrors Runner constant). */
+	private const RUN_ID_KEY = 'prautoblogger_checkpoint_run_id';
+
+	/**
+	 * Finalize a completed run: write final transient, mark run done, release lock.
+	 *
+	 * @param array  $results Generation counters (generated/published/rejected/cost).
+	 * @param string $run_id  Run UUID (read from option if blank).
+	 * @return void
+	 */
+	public static function finalize( array $results, string $run_id = '' ): void {
+		if ( '' === $run_id ) {
+			$run_id = (string) get_option( self::RUN_ID_KEY, '' );
+		}
+		if ( '' !== $run_id ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'done' );
+		}
+		PRAutoBlogger_Pipeline_Status::write_final( $results );
+		PRAutoBlogger_Pipeline_Status::log_summary( $results );
+		PRAutoBlogger_Generation_Lock::release();
+		delete_option( self::RUN_ID_KEY );
+	}
+
+	/** Remove the persistent queue and run-id option on abort paths. */
+	public static function cleanup_queue(): void {
+		delete_option( self::QUEUE_KEY );
+		delete_option( self::RUN_ID_KEY );
+	}
+
+	/**
+	 * Non-blocking loopback to fire cron events immediately.
+	 * Mirrors Pipeline_Runner::schedule_next() exactly.
+	 *
+	 * @return void
+	 */
+	public static function fire_cron_now(): void {
+		spawn_cron();
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+	}
+}

includes/core/class-generation-checkpoint-runner.php

@@ -0,0 +1,295 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Chained-cron checkpoint runner for in-admin manual article generation (v0.21.0, M4).
+ *
+ * What: Replaces the monolithic on_manual_generation() path with a two-tick
+ *       checkpoint machine so Hostinger's background-PHP-process kill cannot
+ *       abort a mid-pipeline run:
+ *         Tick 1 (ORCHESTRATE): collect sources -> analyze patterns -> score ideas ->
+ *                                persist idea queue to option -> schedule Tick 2.
+ *         Tick 2..N (GENERATE): pop one idea from queue -> Article_Worker ->
+ *                                update transient -> schedule next tick or finalize.
+ *
+ * Why separate from Rerun_Executor: Rerun_Executor targets existing run_stages
+ * rows (replay/rebuild). This class creates a brand-new run from scratch.
+ *
+ * SSH retirement (v0.21.0): the former `wp eval 'do_action("prautoblogger_manual_generation")'`
+ * workaround fired on_manual_generation() synchronously in one PHP process --
+ * bypassing the nonce and running the full pipeline without checkpoints.
+ * That path is retired: Executor::on_manual_generation() now delegates here,
+ * and `wp prautoblogger generate` queues via kick_off() (see ARCHITECTURE.md ss25).
+ *
+ * Cost governor: Run_State::ceiling_setting() is applied per-run; a halted run
+ * aborts all remaining ticks (same guarantee as Pipeline_Runner's queued-article path).
+ *
+ * Who triggers it: PRAutoBlogger_Executor::on_manual_generation() (cron),
+ *                  PRAutoBlogger_WP_CLI_Commands (wp prautoblogger generate).
+ * Dependencies: Pipeline_Runner (orchestration), Run_State (run ledger),
+ *               Pipeline_Status (transient), Generation_Lock, Cost_Tracker, Logger.
+ *
+ * @see includes/class-executor.php                       -- Cron/AJAX entry points.
+ * @see core/class-pipeline-runner.php                    -- Orchestration + article worker.
+ * @see core/class-run-state.php                          -- Per-run ledger (cost governor).
+ * @see core/class-pipeline-status.php                    -- Transient broadcast helpers.
+ * @see core/class-generation-checkpoint-helpers.php      -- finalize/cleanup/fire helpers.
+ * @see ARCHITECTURE.md ss25                              -- Checkpoint generation path design.
+ */
+class PRAutoBlogger_Generation_Checkpoint_Runner {
+
+	/** Option key for the checkpoint queue (shared with Pipeline_Runner article queue). */
+	private const QUEUE_KEY = 'prautoblogger_article_queue';
+
+	/** Option key for the in-progress run UUID (generation tick). */
+	private const RUN_ID_KEY = 'prautoblogger_checkpoint_run_id';
+
+	/** WP-Cron action for the orchestration tick. */
+	public const ORCHESTRATE_ACTION = 'prautoblogger_gen_orchestrate';
+
+	/** WP-Cron action for each article-generation tick. */
+	public const GENERATE_ACTION = 'prautoblogger_gen_tick';
+
+	/**
+	 * When true, on_generate_tick() skips wp-cron rescheduling so the VPS
+	 * orchestrator's external loop is the sole driver. Set via set_sync_mode().
+	 * Never true on the wp-cron path; reset to false after the sync run.
+	 *
+	 * @var bool
+	 */
+	private static bool $sync_mode = false;
+
+	/**
+	 * Enable or disable synchronous-driver mode.
+	 * Called by WP_CLI_Commands::run_sync() before and after the tick loop.
+	 *
+	 * @param bool $enabled True to suppress internal cron reschedule.
+	 * @return void
+	 */
+	public static function set_sync_mode( bool $enabled ): void {
+		self::$sync_mode = $enabled;
+	}
+
+	/**
+	 * Schedule the orchestration tick and write the initial status transient.
+	 * Called by on_ajax_generate_now() (via Executor) and by the WP-CLI command.
+	 * Returns immediately -- ALL pipeline work happens in cron.
+	 *
+	 * Side effects: cron scheduling, transient write.
+	 *
+	 * @return void
+	 */
+	public static function kick_off(): void {
+		if ( wp_next_scheduled( self::ORCHESTRATE_ACTION ) ) {
+			return; // Idempotent: already queued.
+		}
+		wp_schedule_single_event( time(), self::ORCHESTRATE_ACTION );
+		PRAutoBlogger_Pipeline_Status::write_initial();
+		PRAutoBlogger_Generation_Checkpoint_Helpers::fire_cron_now();
+	}
+
+	/**
+	 * Cron Tick 1: collect -> analyze -> score. Persists ideas, creates run row,
+	 * schedules Tick 2 for the first article, then returns.
+	 *
+	 * Side effects: source/analysis DB writes, run row insert, option write,
+	 * status transient update, cron scheduling.
+	 *
+	 * @return void
+	 */
+	public static function on_orchestrate_tick(): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+
+		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
+			PRAutoBlogger_Pipeline_Status::write_error(
+				__( 'Could not acquire generation lock. Another run may be in progress.', 'prautoblogger' )
+			);
+			return;
+		}
+
+		$run_id = wp_generate_uuid4();
+		update_option( self::RUN_ID_KEY, $run_id, false );
+		PRAutoBlogger_Run_State::ensure_run( $run_id );
+
+		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+		$cost_tracker->set_run_id( $run_id );
+
+		try {
+			if ( $cost_tracker->is_budget_exceeded() ) {
+				PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+				PRAutoBlogger_Pipeline_Status::write_error(
+					__( 'Monthly API budget exceeded. Generation halted.', 'prautoblogger' )
+				);
+				PRAutoBlogger_Generation_Lock::release();
+				return;
+			}
+
+			PRAutoBlogger_Pipeline_Status::broadcast( __( 'Collecting sources…', 'prautoblogger' ) );
+			$runner = ( new PRAutoBlogger_Pipeline_Runner() )->set_skip_dedup( true );
+			$ideas  = $runner->orchestrate_only( $cost_tracker );
+
+			if ( empty( $ideas ) ) {
+				PRAutoBlogger_Run_State::mark_status( $run_id, 'done' );
+				PRAutoBlogger_Pipeline_Status::write_final(
+					array(
+						'generated' => 0,
+						'published' => 0,
+						'rejected' => 0,
+						'cost' => 0.0,
+					)
+				);
+				PRAutoBlogger_Generation_Lock::release();
+				delete_option( self::RUN_ID_KEY );
+				return;
+			}
+
+			$serialized = array_map(
+				static fn( PRAutoBlogger_Article_Idea $i ) => $i->to_array(),
+				$ideas
+			);
+			update_option(
+				self::QUEUE_KEY,
+				array(
+					'run_id'  => $run_id,
+					'ideas'   => $serialized,
+					'results' => array(
+						'generated' => 0,
+						'published' => 0,
+						'rejected' => 0,
+						'cost' => 0.0,
+					),
+				),
+				false
+			);
+
+			PRAutoBlogger_Pipeline_Status::broadcast(
+				sprintf(
+					/* translators: %d: number of ideas found */
+					__( 'Found %d idea(s) — starting generation…', 'prautoblogger' ),
+					count( $ideas )
+				)
+			);
+
+			// In sync mode the VPS tick loop is the external driver; skip
+			// wp-cron reschedule to prevent a competing background tick.
+			// on_generate_tick() has the same guard for subsequent reschedules.
+			if ( ! self::$sync_mode ) {
+				if ( ! wp_next_scheduled( self::GENERATE_ACTION ) ) {
+					wp_schedule_single_event( time(), self::GENERATE_ACTION );
+				}
+				PRAutoBlogger_Generation_Checkpoint_Helpers::fire_cron_now();
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Orchestrate tick %s: %s', get_class( $e ), $e->getMessage() ),
+				'pipeline'
+			);
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+			PRAutoBlogger_Pipeline_Status::write_error( $e->getMessage() );
+			PRAutoBlogger_Generation_Lock::release();
+			delete_option( self::RUN_ID_KEY );
+		}
+	}
+
+	/**
+	 * Cron Tick 2..N: generate one article, persist totals, reschedule or finalize.
+	 *
+	 * Side effects: LLM API calls, DB writes, post creation, transient updates,
+	 * cron scheduling.
+	 *
+	 * @return void
+	 */
+	public static function on_generate_tick(): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+
+		$queue = get_option( self::QUEUE_KEY );
+		if ( ! is_array( $queue ) || empty( $queue['ideas'] ) ) {
+			PRAutoBlogger_Generation_Checkpoint_Helpers::finalize(
+				array(
+					'generated' => 0,
+					'published' => 0,
+					'rejected' => 0,
+					'cost' => 0.0,
+				)
+			);
+			return;
+		}
+
+		$run_id     = (string) ( $queue['run_id'] ?? '' );
+		$run_status = PRAutoBlogger_Run_State::get_status( $run_id );
+		if ( in_array( $run_status, array( 'halted', 'failed' ), true ) ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf( 'Generate tick: run %s is %s -- aborting.', $run_id, $run_status ),
+				'pipeline'
+			);
+			PRAutoBlogger_Generation_Checkpoint_Helpers::cleanup_queue();
+			PRAutoBlogger_Generation_Lock::release();
+			return;
+		}
+
+		$idea_data    = array_shift( $queue['ideas'] );
+		$idea         = new PRAutoBlogger_Article_Idea( $idea_data );
+		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+		$cost_tracker->set_run_id( $run_id );
+
+		if ( $cost_tracker->is_budget_exceeded() ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+			PRAutoBlogger_Generation_Checkpoint_Helpers::cleanup_queue();
+			PRAutoBlogger_Generation_Lock::release();
+			PRAutoBlogger_Pipeline_Status::write_error(
+				__( 'Monthly API budget exceeded. Generation halted.', 'prautoblogger' )
+			);
+			return;
+		}
+
+		// Persist consumed queue BEFORE generating (prevents orphan-recovery duplication).
+		if ( ! empty( $queue['ideas'] ) ) {
+			update_option( self::QUEUE_KEY, $queue, false );
+		} else {
+			delete_option( self::QUEUE_KEY );
+		}
+
+		try {
+			$worker = new PRAutoBlogger_Article_Worker( $cost_tracker );
+			$result = $worker->generate( $idea );
+
+			$queue['results']['generated'] += $result['generated'];
+			$queue['results']['published'] += $result['published'];
+			$queue['results']['rejected']  += $result['rejected'];
+			$queue['results']['cost']      += $result['cost'];
+
+			if ( ! empty( $queue['ideas'] ) ) {
+				update_option( self::QUEUE_KEY, $queue, false );
+				PRAutoBlogger_Pipeline_Status::update_queue_progress( $queue );
+				// In sync mode the VPS tick loop is the external driver; skip
+				// wp-cron reschedule to prevent a competing background tick.
+				if ( ! self::$sync_mode ) {
+					if ( ! wp_next_scheduled( self::GENERATE_ACTION ) ) {
+						wp_schedule_single_event( time(), self::GENERATE_ACTION );
+					}
+					PRAutoBlogger_Generation_Checkpoint_Helpers::fire_cron_now();
+				}
+			} else {
+				PRAutoBlogger_Post_Assembler::amortize_research_costs( $run_id );
+				PRAutoBlogger_Generation_Checkpoint_Helpers::finalize( $queue['results'], $run_id );
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Generate tick %s for run %s: %s', get_class( $e ), $run_id, $e->getMessage() ),
+				'pipeline'
+			);
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+			PRAutoBlogger_Generation_Checkpoint_Helpers::cleanup_queue();
+			PRAutoBlogger_Generation_Lock::release();
+			PRAutoBlogger_Pipeline_Status::write_error( $e->getMessage() );
+		}
+	}
+}

includes/core/class-idea-scorer.php

@@ -11,9 +11,10 @@ declare(strict_types=1);
  * API is unavailable.
  *
  * Triggered by: PRAutoBlogger_Pipeline_Runner (step 3).
- * Dependencies: Semantic_Dedup, WP_Query.
+ * Dependencies: Semantic_Dedup, Keyword_Extractor, WP_Query.
  *
- * @see core/class-semantic-dedup.php    — Embedding + keyword dedup engine.
+ * @see core/class-semantic-dedup.php      — Embedding + keyword dedup engine.
+ * @see core/class-keyword-extractor.php  — Keyword tokeniser (fallback dedup).
  * @see core/class-content-analyzer.php  — Produces the analysis results we consume.
  * @see core/class-content-generator.php — Consumes the ranked ideas we produce.
  * @see ARCHITECTURE.md                  — Data flow step 3.
@@ -67,7 +68,7 @@ class PRAutoBlogger_Idea_Scorer {
 
 			if ( ! $this->skip_dedup ) {
 				$topic          = $result->get_topic();
-				$topic_keywords = $this->extract_meaningful_keywords( $topic );
+				$topic_keywords = PRAutoBlogger_Keyword_Extractor::extract( $topic );
 
 				if ( $dedup->is_batch_duplicate( $topic, $topic_keywords, $accepted_keyword_sets ) ) {
 					++$deduped_count;
@@ -165,133 +166,6 @@ class PRAutoBlogger_Idea_Scorer {
 		return false;
 	}
 
-	/**
-	 * Extract meaningful keywords from a text string (for fallback dedup).
-	 *
-	 * @param string $text Input text.
-	 * @return string[] Unique lowercase keywords.
-	 */
-	private function extract_meaningful_keywords( string $text ): array {
-		static $stopwords = array(
-			'a',
-			'an',
-			'the',
-			'and',
-			'or',
-			'but',
-			'is',
-			'are',
-			'was',
-			'were',
-			'in',
-			'on',
-			'at',
-			'to',
-			'for',
-			'of',
-			'with',
-			'by',
-			'from',
-			'as',
-			'it',
-			'its',
-			'this',
-			'that',
-			'your',
-			'you',
-			'how',
-			'what',
-			'when',
-			'why',
-			'where',
-			'which',
-			'who',
-			'do',
-			'does',
-			'did',
-			'not',
-			'no',
-			'can',
-			'will',
-			'should',
-			'could',
-			'would',
-			'may',
-			'might',
-			'have',
-			'has',
-			'had',
-			'be',
-			'been',
-			'being',
-			'about',
-			'into',
-			'through',
-			'during',
-			'before',
-			'after',
-			'above',
-			'below',
-			'between',
-			'same',
-			'up',
-			'down',
-			'out',
-			'off',
-			'over',
-			'under',
-			'again',
-			'then',
-			'here',
-			'there',
-			'all',
-			'each',
-			'every',
-			'both',
-			'few',
-			'more',
-			'most',
-			'other',
-			'some',
-			'such',
-			'than',
-			'too',
-			'very',
-			'just',
-			'also',
-			'only',
-			'own',
-			'so',
-			'if',
-			'while',
-			'because',
-			'until',
-			'vs',
-			'versus',
-			'guide',
-			'complete',
-			'ultimate',
-			'best',
-			'top',
-			'new',
-			'first',
-			'need',
-			'know',
-			'everything',
-		);
-
-		$text  = strtolower( $text );
-		$words = preg_split( '/[^a-z0-9-]+/', $text, -1, PREG_SPLIT_NO_EMPTY );
-		$words = array_filter(
-			$words,
-			static function ( string $w ) use ( $stopwords ): bool {
-				return strlen( $w ) >= 2 && ! in_array( $w, $stopwords, true );
-			}
-		);
-
-		return array_values( array_unique( $words ) );
-	}
-
 	/**
 	 * Map analysis type to a reader-friendly article type.
 	 *

includes/core/class-keyword-extractor.php

@@ -0,0 +1,156 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Shared keyword-extraction utility for the scoring and dedup pipeline.
+ *
+ * Extracts meaningful lowercase tokens from free text by stripping stop-words.
+ * Used by both PRAutoBlogger_Idea_Scorer and PRAutoBlogger_Semantic_Dedup as the
+ * fallback path when embedding similarity is unavailable.
+ *
+ * What: Static utility; no state.
+ * Who triggers: PRAutoBlogger_Idea_Scorer, PRAutoBlogger_Semantic_Dedup.
+ * Dependencies: none.
+ *
+ * @see core/class-idea-scorer.php    -- Primary consumer (scoring pipeline).
+ * @see core/class-semantic-dedup.php -- Secondary consumer (embedding fallback).
+ */
+class PRAutoBlogger_Keyword_Extractor {
+
+	/**
+	 * Common English stop-words filtered out before keyword matching.
+	 *
+	 * @var string[]
+	 */
+	private const STOPWORDS = array(
+		'a',
+		'an',
+		'the',
+		'and',
+		'or',
+		'but',
+		'is',
+		'are',
+		'was',
+		'were',
+		'in',
+		'on',
+		'at',
+		'to',
+		'for',
+		'of',
+		'with',
+		'by',
+		'from',
+		'as',
+		'it',
+		'its',
+		'this',
+		'that',
+		'your',
+		'you',
+		'how',
+		'what',
+		'when',
+		'why',
+		'where',
+		'which',
+		'who',
+		'do',
+		'does',
+		'did',
+		'not',
+		'no',
+		'can',
+		'will',
+		'should',
+		'could',
+		'would',
+		'may',
+		'might',
+		'have',
+		'has',
+		'had',
+		'be',
+		'been',
+		'being',
+		'about',
+		'into',
+		'through',
+		'during',
+		'before',
+		'after',
+		'above',
+		'below',
+		'between',
+		'same',
+		'up',
+		'down',
+		'out',
+		'off',
+		'over',
+		'under',
+		'again',
+		'then',
+		'here',
+		'there',
+		'all',
+		'each',
+		'every',
+		'both',
+		'few',
+		'more',
+		'most',
+		'other',
+		'some',
+		'such',
+		'than',
+		'too',
+		'very',
+		'just',
+		'also',
+		'only',
+		'own',
+		'so',
+		'if',
+		'while',
+		'because',
+		'until',
+		'vs',
+		'versus',
+		'guide',
+		'complete',
+		'ultimate',
+		'best',
+		'top',
+		'new',
+		'first',
+		'need',
+		'know',
+		'everything',
+	);
+
+	/**
+	 * Extract meaningful keywords from text.
+	 *
+	 * Lowercases input, splits on non-alphanumeric characters, filters
+	 * stop-words and single-character tokens, and de-duplicates.
+	 *
+	 * @param string $text Input text.
+	 * @return string[] Unique lowercase keyword tokens.
+	 */
+	public static function extract( string $text ): array {
+		$text  = strtolower( $text );
+		$words = preg_split( '/[^a-z0-9-]+/', $text, -1, PREG_SPLIT_NO_EMPTY );
+		$words = array_filter(
+			$words,
+			static function ( string $w ): bool {
+				return strlen( $w ) >= 2 && ! in_array( $w, self::STOPWORDS, true );
+			}
+		);
+
+		return array_values( array_unique( $words ) );
+	}
+}

includes/core/class-pipeline-runner.php

@@ -168,6 +168,19 @@ class PRAutoBlogger_Pipeline_Runner {
 		}
 	}
 
+
+	/**
+	 * Public wrapper for orchestrate(): collect -> analyze -> score.
+	 * Used by Generation_Checkpoint_Runner (Tick 1) so orchestration and
+	 * article generation happen in separate cron ticks.
+	 *
+	 * @param PRAutoBlogger_Cost_Tracker $cost_tracker
+	 * @return PRAutoBlogger_Article_Idea[]
+	 */
+	public function orchestrate_only( PRAutoBlogger_Cost_Tracker $cost_tracker ): array {
+		return $this->orchestrate( $cost_tracker );
+	}
+
 	// ── Private helpers ─────────────────────────────────────────────────
 
 	/**

includes/core/class-pipeline-status.php

@@ -103,4 +103,41 @@ class PRAutoBlogger_Pipeline_Status {
 			'pipeline'
 		);
 	}
+
+	/**
+	 * Write an initial "running" status before the first tick fires.
+	 * Mirrors the shape on_ajax_generate_now() already writes so the poller
+	 * sees a consistent "running" state whether triggered from board or settings page.
+	 *
+	 * @return void
+	 */
+	public static function write_initial(): void {
+		set_transient(
+			self::KEY,
+			array(
+				'status'       => 'running',
+				'stage'        => __( 'Starting generation…', 'prautoblogger' ),
+				'started'      => time(),
+				'last_updated' => time(),
+			),
+			self::TTL
+		);
+	}
+
+	/**
+	 * Write a terminal "error" status.
+	 *
+	 * @param string $message Operator-facing error description.
+	 * @return void
+	 */
+	public static function write_error( string $message ): void {
+		set_transient(
+			self::KEY,
+			array(
+				'status'  => 'error',
+				'message' => $message,
+			),
+			self::TTL
+		);
+	}
 }

includes/core/class-publisher.php

@@ -107,11 +107,11 @@ class PRAutoBlogger_Publisher {
 		if ( null !== $run_id && '' !== $run_id ) {
 			$existing_id = $this->find_existing_post( $run_id, $idea_hash );
 			if ( $existing_id > 0 ) {
-				PRAutoBlogger_Logger::instance()->info(
-					sprintf( 'Post for run %s / idea %s already exists (ID=%d) — skipping duplicate insert.', $run_id, $idea_hash, $existing_id ),
-					'publisher'
-				);
-				return $existing_id;
+				// v0.20.0: a re-run's regenerated content must land on the
+				// existing UNPUBLISHED post (otherwise re-runs silently
+				// discard their output). Published posts stay frozen
+				// (CPO guardrail 5) — refresh skips them untouched.
+				return $this->refresh_unpublished_post( $existing_id, $content, $idea, $review );
 			}
 		}
 
@@ -157,6 +157,60 @@ class PRAutoBlogger_Publisher {
 		return $post_id;
 	}
 
+	/**
+	 * Refresh an existing post from re-run output — unpublished only.
+	 *
+	 * Idempotent-resume calls land here too (same content in = same
+	 * content out, so behavior is unchanged for plain resumes). The post
+	 * keeps its CURRENT status: a re-run never publishes an unpublished
+	 * post — publication stays an explicit Review Queue / WP editor
+	 * action. Published (and scheduled/private) posts are returned
+	 * untouched: the run is frozen (CPO guardrail 5).
+	 *
+	 * Side effects: wp_update_post + post meta updates (unpublished only).
+	 *
+	 * @param int                            $post_id Existing post ID.
+	 * @param string                         $content Regenerated HTML content.
+	 * @param PRAutoBlogger_Article_Idea     $idea    The idea.
+	 * @param PRAutoBlogger_Editorial_Review $review  The fresh review.
+	 * @return int The post ID.
+	 */
+	private function refresh_unpublished_post( int $post_id, string $content, PRAutoBlogger_Article_Idea $idea, PRAutoBlogger_Editorial_Review $review ): int {
+		$post = get_post( $post_id );
+		if ( PRAutoBlogger_Rerun_Eligibility::post_frozen( $post ) ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Post %d already exists and is published — frozen, skipping content refresh.', $post_id ),
+				'publisher'
+			);
+			return $post_id;
+		}
+
+		// Same sanitize chain as create_post().
+		$clean_content  = PRAutoBlogger_Post_Assembler::sanitize_llm_content( $content );
+		$linked_content = PRAutoBlogger_Peptide_Linker::inject_links( $clean_content );
+
+		wp_update_post(
+			array(
+				'ID'           => $post_id,
+				'post_title'   => sanitize_text_field( $idea->get_suggested_title() ),
+				'post_content' => wp_kses_post( $linked_content ),
+			)
+		);
+
+		update_post_meta( $post_id, '_prautoblogger_editor_verdict', $review->get_verdict() );
+		update_post_meta( $post_id, '_prautoblogger_editor_notes', $review->get_notes() );
+		update_post_meta( $post_id, '_prautoblogger_quality_score', $review->get_quality_score() );
+		update_post_meta( $post_id, '_prautoblogger_seo_score', $review->get_seo_score() );
+		update_post_meta( $post_id, '_prautoblogger_generated_at', gmdate( 'c' ) );
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf( 'Post %d refreshed from re-run output (status preserved: %s).', $post_id, (string) ( $post->post_status ?? '' ) ),
+			'publisher'
+		);
+
+		return $post_id;
+	}
+
 	/**
 	 * Build post_meta array for generation metadata.
 	 *

includes/core/class-request-recorder.php

@@ -0,0 +1,73 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Per-PHP-process stash for the most recent outgoing LLM request body.
+ *
+ * What: A process-scoped static slot recording the JSON request body the
+ *       OpenRouter provider is about to dispatch, so Cost_Tracker::
+ *       log_api_call() can persist it to `generation_log.request_json`
+ *       (v0.20.0 / B1) without threading the body through every call
+ *       site. Mirrors the Run_Context precedent (v0.18.0).
+ *
+ *       SECURITY GUARANTEE: only the request BODY is ever recorded.
+ *       Authorization headers are built separately
+ *       (Request_Builder::build_headers()) and can never reach this
+ *       class; build_body() copies only whitelisted option keys.
+ *
+ *       Consume-once semantics: consume() clears the slot, and record()
+ *       overwrites it at every dispatch — so a stale body from an
+ *       unlogged failed call can never attach to a later, unrelated
+ *       log row.
+ * Who triggers it: OpenRouter_Provider::send_chat_completion() (record,
+ *       pre-dispatch so error rows carry the request too);
+ *       Cost_Tracker::log_api_call() (consume).
+ * Dependencies: none.
+ *
+ * @see providers/class-open-router-provider.php — Records before dispatch.
+ * @see core/class-cost-tracker.php              — Consumes into the log row.
+ * @see core/class-run-context.php               — The pattern this mirrors.
+ * @see ARCHITECTURE.md #24                      — Edit + re-run substrate (B1).
+ */
+class PRAutoBlogger_Request_Recorder {
+
+	/** @var string|null JSON-encoded request body of the in-flight LLM call. */
+	private static ?string $request_json = null;
+
+	/**
+	 * Record the outgoing request body for the next log row.
+	 *
+	 * Overwrites any previous stash (one in-flight chat call per PHP
+	 * process). Bodies that fail JSON encoding are skipped silently —
+	 * the log row's request_json stays NULL, never blocking the call.
+	 *
+	 * @param array<string, mixed> $body Request body from Request_Builder::build_body().
+	 * @return void
+	 */
+	public static function record( array $body ): void {
+		$encoded            = wp_json_encode( $body );
+		self::$request_json = is_string( $encoded ) ? $encoded : null;
+	}
+
+	/**
+	 * Return the stashed request body and clear the slot (consume-once).
+	 *
+	 * @return string|null JSON request body, or null when nothing is stashed.
+	 */
+	public static function consume(): ?string {
+		$json               = self::$request_json;
+		self::$request_json = null;
+		return $json;
+	}
+
+	/**
+	 * Clear the stash (tests / defensive teardown).
+	 *
+	 * @return void
+	 */
+	public static function clear(): void {
+		self::$request_json = null;
+	}
+}

includes/core/class-rerun-eligibility.php

@@ -0,0 +1,214 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Policy gates for edit + single-step re-run (v0.20.0, M3).
+ *
+ * What: Single source of truth for WHO may re-run WHAT:
+ *       - Published posts are frozen (CPO guardrail 5): publish/future/
+ *         private statuses lock the run; edits go through the WP editor.
+ *       - Runs that are actively executing (status pending/running or
+ *         the global generation lock held) cannot be re-run — "in
+ *         progress" in the CPO sense means in the WORKFLOW (unpublished),
+ *         not mid-execution.
+ *       - Editable stages (input fork + replay) are the item-scoped
+ *         writer chat stages of the CURRENT pipeline vocabulary:
+ *         outline/draft/polish (single-pass uses draft only). review's
+ *         input is fully derived from content (re-run it from here
+ *         instead); analysis/research are run-level idea-selection
+ *         stages; image stages are not chat-replayable (Phase 2b).
+ *       - The canonical per-item chain orders downstream computation
+ *         for stale-marking and rebuild sets.
+ * Who triggers it: Dossier_Actions (UI affordances + request validation),
+ *       Rerun_Executor (re-validation under the lock before mutating).
+ * Dependencies: get_post(), Run_State, Generation_Lock, Stage_Input_Store.
+ *
+ * @see admin/class-dossier-actions.php — AJAX validation.
+ * @see core/class-rerun-executor.php   — Cron-side re-validation.
+ * @see ARCHITECTURE.md #24             — Edit + re-run design.
+ */
+class PRAutoBlogger_Rerun_Eligibility {
+
+	/** Post statuses that freeze a run (CPO guardrail 5). */
+	public const FROZEN_STATUSES = array( 'publish', 'future', 'private' );
+
+	/** Stages whose input may be edited and replayed (chat writer stages). */
+	public const EDITABLE_STAGES = array( 'outline', 'draft', 'polish' );
+
+	/** Canonical per-item stage chain (current pipeline vocabulary). */
+	public const ITEM_STAGE_CHAIN = array( 'outline', 'draft', 'polish', 'review', 'publish' );
+
+	/**
+	 * Whether a stage's input may be edited + replayed.
+	 *
+	 * @param string $stage Stage name.
+	 * @return bool
+	 */
+	public static function is_editable_stage( string $stage ): bool {
+		return in_array( $stage, self::EDITABLE_STAGES, true );
+	}
+
+	/**
+	 * Whether re-run-from-here may target this stage (any chain stage).
+	 *
+	 * @param string $stage Stage name.
+	 * @return bool
+	 */
+	public static function is_chain_stage( string $stage ): bool {
+		return in_array( $stage, self::ITEM_STAGE_CHAIN, true );
+	}
+
+	/**
+	 * Stages strictly AFTER a stage in the canonical chain — the set that
+	 * goes stale when the stage is re-run. Stages absent from an item
+	 * (e.g. outline/polish on single-pass runs) simply match no rows.
+	 *
+	 * @param string $stage Stage name.
+	 * @return array<string> Downstream stage names ([] for non-chain stages).
+	 */
+	public static function downstream_of( string $stage ): array {
+		$idx = array_search( $stage, self::ITEM_STAGE_CHAIN, true );
+		if ( false === $idx ) {
+			return array();
+		}
+		return array_slice( self::ITEM_STAGE_CHAIN, $idx + 1 );
+	}
+
+	/**
+	 * The demotion set for re-run-from-here: the stage itself plus all
+	 * downstream chain stages.
+	 *
+	 * @param string $stage Stage name.
+	 * @return array<string>
+	 */
+	public static function rebuild_set( string $stage ): array {
+		$idx = array_search( $stage, self::ITEM_STAGE_CHAIN, true );
+		if ( false === $idx ) {
+			return array();
+		}
+		return array_slice( self::ITEM_STAGE_CHAIN, $idx );
+	}
+
+	/**
+	 * Whether a post is frozen for pipeline re-runs (guardrail 5).
+	 *
+	 * @param WP_Post|null $post The post, or null when none exists yet.
+	 * @return bool
+	 */
+	public static function post_frozen( ?WP_Post $post ): bool {
+		return ( $post instanceof WP_Post )
+			&& in_array( (string) $post->post_status, self::FROZEN_STATUSES, true );
+	}
+
+	/**
+	 * Full re-run eligibility check for a (run, post) pair.
+	 *
+	 * Returns ok=false with an operator-readable reason for: missing/
+	 * frozen post, missing run row, run actively executing, or the
+	 * global generation lock being held. Called from the AJAX layer for
+	 * UI affordances AND re-validated by the cron handler under the lock
+	 * (state can change between click and pickup).
+	 *
+	 * @param string $run_id  Run UUID.
+	 * @param int    $post_id Post ID (0 = run has no post yet).
+	 * @param bool   $require_idle_lock Whether a held generation lock blocks (true for actions).
+	 * @return array{ok: bool, reason: string} Verdict + reason ('' when ok).
+	 */
+	public static function check( string $run_id, int $post_id, bool $require_idle_lock = true ): array {
+		if ( '' === $run_id ) {
+			return self::no( __( 'This article has no recorded generation run.', 'prautoblogger' ) );
+		}
+
+		$post = $post_id > 0 ? get_post( $post_id ) : null;
+		if ( self::post_frozen( $post ) ) {
+			return self::no( __( 'This article is published — its run is frozen. Edit the article in the WordPress editor instead.', 'prautoblogger' ) );
+		}
+
+		$run = PRAutoBlogger_Run_State::get_run( $run_id );
+		if ( null === $run ) {
+			return self::no( __( 'No run ledger row exists for this article (pre-substrate run).', 'prautoblogger' ) );
+		}
+		if ( in_array( (string) $run['status'], array( 'pending', 'running' ), true ) ) {
+			return self::no( __( 'This run is currently executing. Wait for it to finish (or for the reaper to mark it failed).', 'prautoblogger' ) );
+		}
+
+		if ( $require_idle_lock && null !== PRAutoBlogger_Generation_Lock::get_acquired_at() ) {
+			return self::no( __( 'Another generation is in progress (lock held). Try again when it completes.', 'prautoblogger' ) );
+		}
+
+		return array(
+			'ok'     => true,
+			'reason' => '',
+		);
+	}
+
+	/**
+	 * Replay-specific check: base eligibility + editable stage + a saved
+	 * input fork whose body has not been retention-pruned.
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param int    $post_id    Post ID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Stage row agent role.
+	 * @param string $item_key   Stage row item key.
+	 * @param bool   $require_idle_lock False when the caller already owns the lock (cron handler).
+	 * @return array{ok: bool, reason: string}
+	 */
+	public static function check_replay( string $run_id, int $post_id, string $stage, string $agent_role, string $item_key, bool $require_idle_lock = true ): array {
+		if ( ! self::is_editable_stage( $stage ) ) {
+			return self::no( __( 'This stage cannot be replayed with an edited input.', 'prautoblogger' ) );
+		}
+		$base = self::check( $run_id, $post_id, $require_idle_lock );
+		if ( ! $base['ok'] ) {
+			return $base;
+		}
+		$fork = PRAutoBlogger_Stage_Input_Store::latest_fork( $run_id, $stage, $agent_role, $item_key );
+		if ( null === $fork ) {
+			return self::no( __( 'Save an edited input for this stage first — re-run executes your latest saved version.', 'prautoblogger' ) );
+		}
+		if ( empty( $fork['request_json'] ) ) {
+			return self::no( __( 'The saved input for this stage was pruned by the retention cron and can no longer be replayed.', 'prautoblogger' ) );
+		}
+		return $base;
+	}
+
+	/**
+	 * Rebuild-specific check: base eligibility + chain stage + idea seed
+	 * available (runs started before v0.20.0 have no seed).
+	 *
+	 * @param string $run_id   Run UUID.
+	 * @param int    $post_id  Post ID.
+	 * @param string $stage    Target stage.
+	 * @param string $item_key Item key.
+	 * @param bool   $require_idle_lock False when the caller already owns the lock (cron handler).
+	 * @return array{ok: bool, reason: string}
+	 */
+	public static function check_rebuild( string $run_id, int $post_id, string $stage, string $item_key, bool $require_idle_lock = true ): array {
+		if ( ! self::is_chain_stage( $stage ) ) {
+			return self::no( __( 'Re-run from here is only available on article pipeline stages.', 'prautoblogger' ) );
+		}
+		$base = self::check( $run_id, $post_id, $require_idle_lock );
+		if ( ! $base['ok'] ) {
+			return $base;
+		}
+		if ( null === PRAutoBlogger_Stage_Input_Store::get_seed( $run_id, $item_key ) ) {
+			return self::no( __( 'No idea seed is stored for this run (recorded from v0.20.0 onward) — the pipeline cannot rebuild it safely.', 'prautoblogger' ) );
+		}
+		return $base;
+	}
+
+	/**
+	 * Shorthand for a negative verdict.
+	 *
+	 * @param string $reason Operator-readable reason.
+	 * @return array{ok: bool, reason: string}
+	 */
+	private static function no( string $reason ): array {
+		return array(
+			'ok'     => false,
+			'reason' => $reason,
+		);
+	}
+}

includes/core/class-rerun-executor.php

@@ -0,0 +1,221 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Queues and executes operator re-runs as chained cron jobs (v0.20.0, M3).
+ *
+ * What: The chained-cron seam for the dossier's two re-run actions —
+ *       NEVER synchronous (CPO hard constraint): the AJAX layer only
+ *       schedules; ALL state mutations happen in the cron handler after
+ *       re-validating eligibility under the global generation lock.
+ *       - Replay job: single-stage re-run of the latest edited input
+ *         fork (Stage_Replay). Demotes the one stage row to running
+ *         (human_modified=1), stale-marks downstream, executes, restores
+ *         a terminal run status.
+ *       - Rebuild job ("re-run from here"): demotes the target + all
+ *         downstream chain stages to pending, then re-enters
+ *         Article_Worker with the idea reconstructed from the stored
+ *         seed — upstream done stages are reused (never re-charged),
+ *         demoted stages re-run with prompts rebuilt from CURRENT
+ *         upstream snapshots, and the publisher refreshes the
+ *         unpublished post.
+ *       Both jobs: monthly budget check, Run_State::reopen() (ceiling
+ *       re-snapshotted from the current setting — a deliberate new-spend
+ *       decision), M1 status transient for board/dossier pickup
+ *       visibility, lock released in finally. Failures restore/record a
+ *       terminal run status so the run-reaper's stuck-running sweep
+ *       stays meaningful.
+ * Who triggers it: Dossier_Actions (queue_*), WP-Cron (on_* handlers via
+ *       class-prautoblogger.php registration).
+ * Dependencies: Rerun_Job_Support (lock/budget/transient plumbing),
+ *               Run_State, Run_Stage_Rerun_State, Stage_Input_Store,
+ *               Stage_Replay, Article_Worker, Rerun_Eligibility.
+ *
+ * @see admin/class-dossier-actions.php — The AJAX layer (queues via Job_Support).
+ * @see core/class-rerun-job-support.php — Shared queue/lock/status plumbing.
+ * @see core/class-stage-replay.php     — The governed replay call.
+ * @see ARCHITECTURE.md #24             — Edit + re-run design.
+ */
+class PRAutoBlogger_Rerun_Executor {
+
+	/** Cron action for single-stage replay jobs. */
+	public const REPLAY_ACTION = 'prautoblogger_rerun_stage_replay';
+
+	/** Cron action for re-run-from-here rebuild jobs. */
+	public const REBUILD_ACTION = 'prautoblogger_rerun_from_stage';
+
+	/**
+	 * Cron handler: replay one stage from its latest edited input fork.
+	 *
+	 * Side effects: run_stages/runs mutations, one governed LLM call,
+	 * generation_log row, status transient, lock acquire/release.
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param int    $post_id    Post the dossier acted on.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Stage row agent role.
+	 * @param string $item_key   Stage row item key.
+	 * @return void
+	 */
+	public function on_replay_job( string $run_id, int $post_id, string $stage, string $agent_role, string $item_key ): void {
+		PRAutoBlogger_Rerun_Job_Support::harden_process();
+		if ( ! PRAutoBlogger_Rerun_Job_Support::acquire_lock_or_report() ) {
+			return;
+		}
+
+		$previous_status = null;
+		try {
+			// Re-validate under the lock — state may have changed between
+			// click and pickup (e.g. the post was published).
+			// require_idle_lock=false: THIS handler owns the lock.
+			$check = PRAutoBlogger_Rerun_Eligibility::check_replay( $run_id, $post_id, $stage, $agent_role, $item_key, false );
+			if ( ! $check['ok'] ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( $check['reason'] );
+				return;
+			}
+			if ( PRAutoBlogger_Rerun_Job_Support::monthly_budget_exceeded() ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'Monthly API budget exceeded. Re-run not started.', 'prautoblogger' ) );
+				return;
+			}
+
+			$fork = PRAutoBlogger_Stage_Input_Store::latest_fork( $run_id, $stage, $agent_role, $item_key );
+			$body = null !== $fork ? PRAutoBlogger_Stage_Replay::decode_body( (string) $fork['request_json'] ) : null;
+			if ( null === $body ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The saved input could not be decoded as a replayable request.', 'prautoblogger' ) );
+				return;
+			}
+
+			$previous_status = PRAutoBlogger_Run_State::get_status( $run_id );
+			if ( ! PRAutoBlogger_Run_State::reopen( $run_id ) ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The run could not be reopened for new spend.', 'prautoblogger' ) );
+				return;
+			}
+
+			if ( ! PRAutoBlogger_Run_Stage_Rerun_State::restart( $run_id, $stage, $agent_role, $item_key, true ) ) {
+				PRAutoBlogger_Rerun_Job_Support::restore_terminal( $run_id, $previous_status );
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The stage row could not be demoted for replay (it may be executing).', 'prautoblogger' ) );
+				return;
+			}
+			// Guardrail 3: explicit, visible downstream invalidation.
+			PRAutoBlogger_Run_Stage_Rerun_State::mark_stale( $run_id, $item_key, PRAutoBlogger_Rerun_Eligibility::downstream_of( $stage ) );
+
+			PRAutoBlogger_Rerun_Job_Support::broadcast(
+				sprintf(
+					/* translators: %s: stage display label. */
+					__( 'Re-running %s with the edited input…', 'prautoblogger' ),
+					PRAutoBlogger_Stage_Display_Map::label( $stage )
+				)
+			);
+
+			$result = PRAutoBlogger_Stage_Replay::run( $run_id, $stage, $agent_role, $item_key, $body );
+
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'done' );
+			PRAutoBlogger_Rerun_Job_Support::finish_complete( $result['cost'] );
+		} catch ( PRAutoBlogger_Cost_Ceiling_Exception $e ) {
+			// Governor already halted the run + recorded the overage.
+			PRAutoBlogger_Run_Stage_State::fail( $run_id, $stage, $agent_role, $item_key );
+			PRAutoBlogger_Rerun_Job_Support::finish_error( $e->getMessage() );
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Run_Stage_State::fail( $run_id, $stage, $agent_role, $item_key );
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Stage replay %s for run %s/%s: %s', get_class( $e ), $run_id, $stage, $e->getMessage() ),
+				'rerun'
+			);
+			PRAutoBlogger_Rerun_Job_Support::finish_error( $e->getMessage() );
+		} finally {
+			PRAutoBlogger_Generation_Lock::release();
+		}
+	}
+
+	/**
+	 * Cron handler: re-run from a stage — demote it + downstream, then
+	 * re-enter the worker so demoted stages rebuild from current
+	 * upstream snapshots.
+	 *
+	 * Side effects: run_stages/runs mutations, worker LLM calls
+	 * (governed), post refresh, status transient, lock acquire/release.
+	 *
+	 * @param string $run_id   Run UUID.
+	 * @param int    $post_id  Post the dossier acted on.
+	 * @param string $stage    Target stage (start of the rebuild set).
+	 * @param string $item_key Item key.
+	 * @return void
+	 */
+	public function on_rebuild_job( string $run_id, int $post_id, string $stage, string $item_key ): void {
+		PRAutoBlogger_Rerun_Job_Support::harden_process();
+		if ( ! PRAutoBlogger_Rerun_Job_Support::acquire_lock_or_report() ) {
+			return;
+		}
+
+		try {
+			// require_idle_lock=false: THIS handler owns the lock.
+			$check = PRAutoBlogger_Rerun_Eligibility::check_rebuild( $run_id, $post_id, $stage, $item_key, false );
+			if ( ! $check['ok'] ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( $check['reason'] );
+				return;
+			}
+			if ( PRAutoBlogger_Rerun_Job_Support::monthly_budget_exceeded() ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'Monthly API budget exceeded. Re-run not started.', 'prautoblogger' ) );
+				return;
+			}
+
+			$idea_json = PRAutoBlogger_Stage_Input_Store::get_seed( $run_id, $item_key );
+			$idea_data = null !== $idea_json ? json_decode( $idea_json, true ) : null;
+			if ( ! is_array( $idea_data ) ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The stored idea seed could not be decoded.', 'prautoblogger' ) );
+				return;
+			}
+			$idea = new PRAutoBlogger_Article_Idea( $idea_data );
+
+			$job_start = current_time( 'mysql' );
+			$demoted   = PRAutoBlogger_Rerun_Eligibility::rebuild_set( $stage );
+
+			if ( ! PRAutoBlogger_Run_State::reopen( $run_id ) ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The run could not be reopened for new spend.', 'prautoblogger' ) );
+				return;
+			}
+			PRAutoBlogger_Run_Stage_Rerun_State::demote_to_pending( $run_id, $item_key, $demoted );
+
+			PRAutoBlogger_Rerun_Job_Support::broadcast(
+				sprintf(
+					/* translators: %s: stage display label. */
+					__( 'Re-running the pipeline from %s…', 'prautoblogger' ),
+					PRAutoBlogger_Stage_Display_Map::label( $stage )
+				)
+			);
+
+			$tracker = new PRAutoBlogger_Cost_Tracker();
+			$tracker->set_run_id( $run_id );
+			$result = ( new PRAutoBlogger_Article_Worker( $tracker ) )->generate( $idea );
+
+			// The worker traps its own failures (fail_open_for_item);
+			// publish-done is the success signal.
+			$succeeded = PRAutoBlogger_Run_Stage_State::is_done( $run_id, 'publish', '', $item_key );
+
+			// Decisions recorded while rebuilding a human-modified item
+			// derive from edited content — flag them (guardrail 2).
+			if ( PRAutoBlogger_Run_Stage_Rerun_State::item_has_human_modified( $run_id, $item_key ) ) {
+				PRAutoBlogger_Audit_Writer::flag_decisions_human_modified( $run_id, $demoted, $job_start );
+			}
+
+			PRAutoBlogger_Run_State::mark_status( $run_id, $succeeded ? 'done' : 'failed' );
+			if ( $succeeded ) {
+				PRAutoBlogger_Rerun_Job_Support::finish_complete( (float) $result['cost'] );
+			} else {
+				PRAutoBlogger_Rerun_Job_Support::finish_error( __( 'The re-run did not complete — check the Activity Log and the dossier stage states.', 'prautoblogger' ) );
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Rebuild from %s %s for run %s: %s', $stage, get_class( $e ), $run_id, $e->getMessage() ),
+				'rerun'
+			);
+			PRAutoBlogger_Rerun_Job_Support::finish_error( $e->getMessage() );
+		} finally {
+			PRAutoBlogger_Generation_Lock::release();
+		}
+	}
+}

includes/core/class-rerun-job-support.php

@@ -0,0 +1,158 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Shared plumbing for re-run cron jobs (v0.20.0, M3).
+ *
+ * What: The queue/lock/budget/status-transient helpers both
+ *       Rerun_Executor handlers share — extracted so the executor stays
+ *       under the 300-line cap. The status transient writes use the M1
+ *       Generation_Status_Poller shape so the kanban board (and the
+ *       dossier's poll) show queued → pickup → result without any new
+ *       polling infrastructure; the poller's existing R2/R3 orphan
+ *       recovery covers a dead re-run process unchanged.
+ * Who triggers it: PRAutoBlogger_Rerun_Executor (handlers) and
+ *       PRAutoBlogger_Dossier_Actions (queue()).
+ * Dependencies: Generation_Lock, Generation_Status_Poller (constants),
+ *               Cost_Tracker, Run_State, Logger, WP-Cron.
+ *
+ * @see core/class-rerun-executor.php — The job handlers.
+ * @see ARCHITECTURE.md #24           — Edit + re-run design.
+ */
+class PRAutoBlogger_Rerun_Job_Support {
+
+	/**
+	 * Schedule a re-run job and fire the cron spawner (non-blocking).
+	 *
+	 * The uniq argument keeps wp_schedule_single_event()'s identical-
+	 * args dedup from swallowing a legitimate second click after a
+	 * failed attempt within the 10-minute window.
+	 *
+	 * Side effects: one single cron event, status transient write,
+	 * non-blocking loopback request.
+	 *
+	 * @param string $action         Cron action name.
+	 * @param array  $args           Handler args.
+	 * @param string $queued_message Operator-facing "queued" copy.
+	 * @return void
+	 */
+	public static function queue( string $action, array $args, string $queued_message ): void {
+		$args[] = (string) microtime( true ); // Uniqueness token.
+		wp_schedule_single_event( time(), $action, $args );
+
+		self::broadcast( $queued_message );
+
+		spawn_cron();
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+	}
+
+	/** Raise process limits for a background LLM job (cron context). */
+	public static function harden_process(): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+	}
+
+	/**
+	 * Acquire the global generation mutex or report the conflict.
+	 *
+	 * @return bool Whether the lock was acquired.
+	 */
+	public static function acquire_lock_or_report(): bool {
+		if ( PRAutoBlogger_Generation_Lock::acquire() ) {
+			return true;
+		}
+		self::finish_error( __( 'Could not acquire the generation lock — another run is in progress. Re-run again when it completes.', 'prautoblogger' ) );
+		return false;
+	}
+
+	/**
+	 * Whether the monthly budget hard-stop blocks new spend.
+	 *
+	 * @return bool
+	 */
+	public static function monthly_budget_exceeded(): bool {
+		return ( new PRAutoBlogger_Cost_Tracker() )->is_budget_exceeded();
+	}
+
+	/**
+	 * Restore a terminal run status after an aborted-but-reopened job.
+	 *
+	 * @param string      $run_id Run UUID.
+	 * @param string|null $status The pre-reopen status (done/failed/halted).
+	 * @return void
+	 */
+	public static function restore_terminal( string $run_id, ?string $status ): void {
+		if ( null !== $status && in_array( $status, array( 'done', 'failed', 'halted' ), true ) ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, $status );
+		}
+	}
+
+	/**
+	 * Update the live status transient (board + dossier polling).
+	 *
+	 * @param string $message Stage message.
+	 * @return void
+	 */
+	public static function broadcast( string $message ): void {
+		set_transient(
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+			array(
+				'status'       => 'running',
+				'stage'        => $message,
+				'started'      => time(),
+				'last_updated' => time(),
+			),
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+		);
+	}
+
+	/**
+	 * Final transient: success (board-compatible shape).
+	 *
+	 * @param float $cost Job spend in USD.
+	 * @return void
+	 */
+	public static function finish_complete( float $cost ): void {
+		set_transient(
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+			array(
+				'status'    => 'complete',
+				'generated' => 0,
+				'published' => 0,
+				'rejected'  => 0,
+				'cost'      => $cost,
+				'message'   => __( 'Re-run complete.', 'prautoblogger' ),
+			),
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+		);
+	}
+
+	/**
+	 * Final transient: error (board-compatible shape) + log.
+	 *
+	 * @param string $message Operator-facing error.
+	 * @return void
+	 */
+	public static function finish_error( string $message ): void {
+		PRAutoBlogger_Logger::instance()->warning( 'Re-run job: ' . $message, 'rerun' );
+		set_transient(
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+			array(
+				'status'  => 'error',
+				'message' => $message,
+			),
+			PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+		);
+	}
+}

includes/core/class-run-reaper.php

@@ -16,8 +16,9 @@ declare(strict_types=1);
  *          ledger/state activity for 2× the expected run wall-clock are
  *          marked `failed` and their non-done stages reaped to `failed`;
  *          such runs render as "incomplete" via incomplete_runs().
- *       3. Retention — `request_json` on generation_log and stage output
+ *       3. Retention — `request_json` on generation_log, stage output
  *          payloads (`meta_json` on run_stages) are NULLed after R days;
+ *          payloads, and stage_inputs human-fork bodies (v0.20.0);
  *          R comes from the `prautoblogger_request_json_retention_days`
  *          SETTING (default constant 14; 0 = keep forever) — never a
  *          literal at the point of use.
@@ -132,7 +133,9 @@ class PRAutoBlogger_Run_Reaper {
 		 * @param int $seconds Expected seconds (default 300).
 		 */
 		$expected = (int) apply_filters( 'prautoblogger_filter_stage_expected_seconds', self::EXPECTED_STAGE_SECONDS );
-		$cutoff   = gmdate( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
+		// Use wp_date() so the cutoff is expressed in the site's local timezone,
+		// matching the updated_at values written by current_time('mysql') (v0.22.1 TZ fix).
+		$cutoff   = wp_date( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
 		$now      = current_time( 'mysql' );
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
@@ -168,7 +171,8 @@ class PRAutoBlogger_Run_Reaper {
 		 * @param int $seconds Expected seconds (default 1800).
 		 */
 		$expected = (int) apply_filters( 'prautoblogger_filter_expected_run_seconds', self::EXPECTED_RUN_SECONDS );
-		$cutoff   = gmdate( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
+		// Use wp_date() so the cutoff matches updated_at's local-timezone storage (v0.22.1 TZ fix).
+		$cutoff   = wp_date( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
 		$stuck = $wpdb->get_col(
@@ -265,6 +269,11 @@ class PRAutoBlogger_Run_Reaper {
 			$pruned += is_numeric( $result ) ? (int) $result : 0;
 		}
 
+		// v0.20.0: human edit-fork bodies ride the same retention (seed
+		// rows are kept — structural, ~1KB). A pruned fork can no longer
+		// be replayed; the dossier explains that state honestly.
+		$pruned += PRAutoBlogger_Stage_Input_Store::prune_human_bodies( $cutoff );
+
 		return $pruned;
 	}
 }

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

@@ -0,0 +1,172 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Operator-action state mutations for edit + re-run (v0.20.0, M3).
+ *
+ * What: The ONLY paths that may demote a 'done' run_stages row — and all
+ *       of them are deliberate operator actions dispatched from the
+ *       dossier (never reachable from pipeline resume code):
+ *       - restart(): done/failed/halted/pending → running for a single-
+ *         stage replay; bumps attempt, clears stale, sets human_modified
+ *         when the replay uses an edited input fork (CPO guardrail 2).
+ *       - mark_stale(): flags downstream 'done' stages as stale after an
+ *         upstream edit enters execution. Stale is a COLUMN, not a
+ *         status: the stage stays 'done', so resume-without-recharge
+ *         logic can never silently re-run it (CPO guardrail 3 holds by
+ *         construction). Only Run_Stage_Writes::done() clears it.
+ *       - demote_to_pending(): re-run-from-here demotion; the worker
+ *         re-entry then rebuilds those stages from current upstream
+ *         snapshots. Audit columns (attempt, human_modified) survive;
+ *         old meta_json survives until overwritten by the fresh done().
+ *       Every method no-ops when the run_stages table is missing.
+ * Who triggers it: PRAutoBlogger_Rerun_Executor (cron handlers, after
+ *       re-validating eligibility under the generation lock).
+ * Dependencies: Run_Stage_State (probe/table), $wpdb.
+ *
+ * @see core/class-rerun-executor.php      — Sole caller.
+ * @see core/class-run-stage-writes.php    — Pipeline-path writes (done clears stale).
+ * @see core/class-rerun-eligibility.php   — Policy gates before any mutation.
+ * @see ARCHITECTURE.md #24                — Edit + re-run design.
+ */
+class PRAutoBlogger_Run_Stage_Rerun_State {
+
+	/**
+	 * Demote one stage row to 'running' for an operator replay.
+	 *
+	 * Allowed from done/failed/halted/pending — never from 'running'
+	 * (a concurrently executing stage cannot be restarted). Bumps the
+	 * attempt counter, clears `stale` (the row is being refreshed) and
+	 * sets `human_modified` when the replay executes an edited fork.
+	 * `human_modified` is never cleared by any code path — it is sticky
+	 * audit state for the life of the run.
+	 *
+	 * Side effects: one UPDATE on run_stages.
+	 *
+	 * @param string $run_id         Run UUID.
+	 * @param string $stage          Stage name.
+	 * @param string $agent_role     Agent role (resolved by the caller from the actual row).
+	 * @param string $item_key       Item key.
+	 * @param bool   $human_modified Whether an edited input fork drives this replay.
+	 * @return bool Whether a row was demoted.
+	 */
+	public static function restart( string $run_id, string $stage, string $agent_role, string $item_key, bool $human_modified ): bool {
+		if ( '' === $run_id || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return false;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table}
+				SET status = 'running', attempt = attempt + 1, stale = 0,
+					human_modified = IF(%d = 1, 1, human_modified),
+					updated_at = %s, finished_at = NULL
+				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s
+					AND status IN ('done','failed','halted','pending')",
+				$human_modified ? 1 : 0,
+				$now,
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key
+			)
+		);
+		return 1 === (int) $updated;
+	}
+
+	/**
+	 * Flag a set of 'done' stages as stale (explicit downstream
+	 * invalidation after an upstream edit/re-run — CPO guardrail 3).
+	 *
+	 * Nothing is demoted and nothing auto-re-runs: the rows stay 'done'
+	 * and visible; the operator triggers each subsequent stage (or
+	 * re-run-from-here) deliberately.
+	 *
+	 * @param string        $run_id   Run UUID.
+	 * @param string        $item_key Item key.
+	 * @param array<string> $stages   Stage names to flag.
+	 * @return int Rows flagged.
+	 */
+	public static function mark_stale( string $run_id, string $item_key, array $stages ): int {
+		if ( '' === $run_id || empty( $stages ) || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table        = PRAutoBlogger_Run_Stage_State::table_name();
+		$placeholders = implode( ',', array_fill( 0, count( $stages ), '%s' ) );
+		$params       = array_merge( array( current_time( 'mysql' ), $run_id, $item_key ), array_values( $stages ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %s list.
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET stale = 1, updated_at = %s
+				WHERE run_id = %s AND item_key = %s AND status = 'done' AND stage IN ({$placeholders})",
+				$params
+			)
+		);
+		return is_numeric( $updated ) ? (int) $updated : 0;
+	}
+
+	/**
+	 * Demote a set of stages to 'pending' for re-run-from-here.
+	 *
+	 * The pipeline's resume machinery treats pending stages as not-done
+	 * and re-executes them with prompts REBUILT from current upstream
+	 * snapshots — that is how an upstream edit propagates downstream.
+	 * Rows keep attempt/human_modified (audit) and their old meta_json
+	 * until the fresh completion overwrites it; `stale` stays 1 until
+	 * Run_Stage_Writes::done() clears it on fresh output. Never touches
+	 * a 'running' row.
+	 *
+	 * @param string        $run_id   Run UUID.
+	 * @param string        $item_key Item key.
+	 * @param array<string> $stages   Stage names to demote.
+	 * @return int Rows demoted.
+	 */
+	public static function demote_to_pending( string $run_id, string $item_key, array $stages ): int {
+		if ( '' === $run_id || empty( $stages ) || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table        = PRAutoBlogger_Run_Stage_State::table_name();
+		$placeholders = implode( ',', array_fill( 0, count( $stages ), '%s' ) );
+		$params       = array_merge( array( current_time( 'mysql' ), $run_id, $item_key ), array_values( $stages ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %s list.
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'pending', stale = 1, updated_at = %s, finished_at = NULL
+				WHERE run_id = %s AND item_key = %s AND status != 'running' AND stage IN ({$placeholders})",
+				$params
+			)
+		);
+		return is_numeric( $updated ) ? (int) $updated : 0;
+	}
+	/**
+	 * Whether any stage row of this item carries the human_modified flag
+	 * (drives derived-decision flagging during rebuilds — guardrail 2).
+	 *
+	 * @param string $run_id   Run UUID.
+	 * @param string $item_key Item key.
+	 * @return bool
+	 */
+	public static function item_has_human_modified( string $run_id, string $item_key ): bool {
+		if ( '' === $run_id || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return false;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT 1 FROM {$table} WHERE run_id = %s AND item_key = %s AND human_modified = 1 LIMIT 1",
+				$run_id,
+				$item_key
+			)
+		);
+		return null !== $found;
+	}
+}

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

@@ -16,9 +16,17 @@ declare(strict_types=1);
  * 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.
  *
+ * v0.20.0: write bodies extracted to PRAutoBlogger_Run_Stage_Writes (the
+ * M2 split pattern — this class was at the 300-line cap); the public API
+ * here is unchanged and delegates. Operator-action mutations (replay
+ * restart, stale marking, re-run demotion) live in
+ * PRAutoBlogger_Run_Stage_Rerun_State only.
+ *
+ * @see core/class-run-stage-writes.php      — Extracted write bodies.
+ * @see core/class-run-stage-rerun-state.php — M3 operator-action writes.
  * @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 #22       — Pipeline v2 Phase 1 substrate.
+ * @see ARCHITECTURE.md #22 / #24 — Substrate + edit/re-run design.
  */
 class PRAutoBlogger_Run_Stage_State {
 
@@ -73,6 +81,7 @@ class PRAutoBlogger_Run_Stage_State {
 
 	/**
 	 * Mark a stage as running. Sticky: done stages are never demoted.
+	 * Delegates to Run_Stage_Writes (v0.20.0 split — behavior unchanged).
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name (see Stage_Display_Map).
@@ -80,35 +89,13 @@ class PRAutoBlogger_Run_Stage_State {
 	 * @param string $item_key   Article scope ('' for run-level stages).
 	 */
 	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' );
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->query(
-			$wpdb->prepare(
-				"INSERT INTO {$table}
-				(run_id, stage, agent_role, item_key, status, attempt, started_at, updated_at)
-				VALUES (%s, %s, %s, %s, 'running', 1, %s, %s)
-				ON DUPLICATE KEY UPDATE
-					attempt = IF(status = 'done', attempt, attempt + 1),
-					status = IF(status = 'done', 'done', 'running'),
-					updated_at = VALUES(updated_at)",
-				$run_id,
-				$stage,
-				$agent_role,
-				$item_key,
-				$now,
-				$now
-			)
-		);
+		PRAutoBlogger_Run_Stage_Writes::start( $run_id, $stage, $agent_role, $item_key );
 	}
 
 	/**
 	 * Mark a stage done and persist its output for resume-without-recharge.
+	 * Delegates to Run_Stage_Writes (v0.20.0 split; fresh completion also
+	 * clears the `stale` flag there).
 	 *
 	 * @param string      $run_id     Run UUID.
 	 * @param string      $stage      Stage name.
@@ -118,41 +105,12 @@ class PRAutoBlogger_Run_Stage_State {
 	 * @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' );
-		$meta  = null !== $output ? wp_json_encode( array( 'output' => $output ) ) : null;
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->query(
-			$wpdb->prepare(
-				"INSERT INTO {$table}
-				(run_id, stage, agent_role, item_key, status, attempt, cost_usd, meta_json, started_at, updated_at, finished_at)
-				VALUES (%s, %s, %s, %s, 'done', 1, %f, %s, %s, %s, %s)
-				ON DUPLICATE KEY UPDATE
-					status = 'done',
-					cost_usd = VALUES(cost_usd),
-					meta_json = VALUES(meta_json),
-					updated_at = VALUES(updated_at),
-					finished_at = VALUES(finished_at)",
-				$run_id,
-				$stage,
-				$agent_role,
-				$item_key,
-				$cost_usd,
-				$meta,
-				$now,
-				$now,
-				$now
-			)
-		);
+		PRAutoBlogger_Run_Stage_Writes::done( $run_id, $stage, $agent_role, $item_key, $output, $cost_usd );
 	}
 
 	/**
-	 * Mark a stage failed (does not demote a done stage).
+	 * Mark a stage failed (does not demote a done stage). Delegates to
+	 * Run_Stage_Writes (v0.20.0 split — behavior unchanged).
 	 *
 	 * @param string $run_id     Run UUID.
 	 * @param string $stage      Stage name.
@@ -160,26 +118,7 @@ class PRAutoBlogger_Run_Stage_State {
 	 * @param string $item_key   Article scope.
 	 */
 	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' );
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->query(
-			$wpdb->prepare(
-				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
-				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s AND status != 'done'",
-				$now,
-				$now,
-				$run_id,
-				$stage,
-				$agent_role,
-				$item_key
-			)
-		);
+		PRAutoBlogger_Run_Stage_Writes::fail( $run_id, $stage, $agent_role, $item_key );
 	}
 
 	/**
@@ -196,7 +135,7 @@ class PRAutoBlogger_Run_Stage_State {
 		if ( '' === $run_id || ! self::is_available() ) {
 			return null;
 		}
-		$agent_role = self::resolve_role( $stage, $agent_role );
+		$agent_role = PRAutoBlogger_Run_Stage_Writes::resolve_role( $stage, $agent_role );
 		global $wpdb;
 		$table = self::table_name();
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
@@ -265,49 +204,68 @@ class PRAutoBlogger_Run_Stage_State {
 
 	/**
 	 * Fail every still-open stage of one item. Done stages are untouched.
+	 * Delegates to Run_Stage_Writes (v0.20.0 split — behavior unchanged).
 	 *
 	 * @param string $run_id   Run UUID.
 	 * @param string $item_key Stage item key ('' = run-level stages).
 	 */
 	public static function fail_open_for_item( string $run_id, string $item_key ): void {
+		PRAutoBlogger_Run_Stage_Writes::fail_open_for_item( $run_id, $item_key );
+	}
+
+	/**
+	 * All stage rows for one item of a run (plus run-level rows when
+	 * $include_run_level), ordered by id. Read API for the rerun engine
+	 * and the dossier's item-scoped assembly (v0.20.0).
+	 *
+	 * @param string $run_id            Run UUID.
+	 * @param string $item_key          Item key ('idea:<hash>').
+	 * @param bool   $include_run_level Include item_key='' rows too.
+	 * @return array<int, array<string, mixed>> Stage rows (ARRAY_A).
+	 */
+	public static function stages_for_item( string $run_id, string $item_key, bool $include_run_level = true ): array {
 		if ( '' === $run_id || ! self::is_available() ) {
-			return;
+			return array();
 		}
 		global $wpdb;
 		$table = self::table_name();
-		$now   = current_time( 'mysql' );
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->query(
+		$sql   = $include_run_level
+			? "SELECT * FROM {$table} WHERE run_id = %s AND item_key IN (%s, '') ORDER BY id ASC"
+			: "SELECT * FROM {$table} WHERE run_id = %s AND item_key = %s ORDER BY id ASC";
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared -- assembled from two fixed literals above.
+		$rows = $wpdb->get_results( $wpdb->prepare( $sql, $run_id, $item_key ), ARRAY_A );
+		return is_array( $rows ) ? $rows : array();
+	}
+
+	/**
+	 * Which of the given runs carry at least one stale stage (batched --
+	 * feeds the Review Queue warning chips without N+1; CPO product AC:
+	 * a stale flag is present at publish). Self-healing: missing table
+	 * or column returns [].
+	 *
+	 * @param array<string> $run_ids Run UUIDs.
+	 * @return array<string> Subset of $run_ids having stale stages.
+	 */
+	public static function runs_with_stale_stages( array $run_ids ): array {
+		$run_ids = array_values( array_filter( array_map( 'strval', $run_ids ) ) );
+		if ( empty( $run_ids ) || ! self::is_available() ) {
+			return array();
+		}
+		global $wpdb;
+		$table        = self::table_name();
+		$placeholders = implode( ',', array_fill( 0, count( $run_ids ), '%s' ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %s list.
+		$rows = $wpdb->get_col(
 			$wpdb->prepare(
-				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
-				WHERE run_id = %s AND item_key = %s AND status IN ('pending','running')",
-				$now,
-				$now,
-				$run_id,
-				$item_key
+				"SELECT DISTINCT run_id FROM {$table} WHERE stale = 1 AND run_id IN ({$placeholders})",
+				$run_ids
 			)
 		);
+		return is_array( $rows ) ? array_map( 'strval', $rows ) : array();
 	}
 
 	/** Reset per-request caches (tests). */
 	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-run-stage-writes.php

@@ -0,0 +1,222 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Pipeline-path write operations over `wp_prautoblogger_run_stages`.
+ *
+ * Extracted from PRAutoBlogger_Run_Stage_State in v0.20.0 so that class
+ * stays under the 300-line cap (the M2 class-split pattern): start/done/
+ * fail/fail_open_for_item bodies moved here verbatim; Run_Stage_State
+ * keeps thin delegating proxies, so every existing call site is
+ * unchanged. One M3 behavior delta, isolated in done(): a freshly
+ * completed stage clears its `stale` flag (fresh output is never stale),
+ * with a self-healing legacy retry for half-migrated schemas that lack
+ * the v0.20.0 columns (same retry pattern as Cost_Tracker v0.18.0).
+ *
+ * Operator-action mutations (restart/mark_stale/demote) live in
+ * PRAutoBlogger_Run_Stage_Rerun_State, not here.
+ *
+ * Triggered by: PRAutoBlogger_Run_Stage_State proxies (pipeline call sites).
+ * Dependencies: Run_Stage_State (table probe), Stage_Display_Map (role).
+ *
+ * @see core/class-run-stage-state.php       — Public API + read methods.
+ * @see core/class-run-stage-rerun-state.php — M3 operator-action writes.
+ * @see ARCHITECTURE.md #22 / #24            — Substrate + edit/re-run design.
+ */
+class PRAutoBlogger_Run_Stage_Writes {
+
+	/**
+	 * 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 ('' = resolve from stage map).
+	 * @param string $item_key   Article scope ('' for run-level stages).
+	 */
+	public static function start( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
+		if ( '' === $run_id || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"INSERT INTO {$table}
+				(run_id, stage, agent_role, item_key, status, attempt, started_at, updated_at)
+				VALUES (%s, %s, %s, %s, 'running', 1, %s, %s)
+				ON DUPLICATE KEY UPDATE
+					attempt = IF(status = 'done', attempt, attempt + 1),
+					status = IF(status = 'done', 'done', 'running'),
+					updated_at = VALUES(updated_at)",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key,
+				$now,
+				$now
+			)
+		);
+	}
+
+	/**
+	 * Mark a stage done and persist its output for resume-without-recharge.
+	 *
+	 * v0.20.0: a fresh completion clears the `stale` flag (and never
+	 * touches `human_modified` — that flag is sticky run audit). When the
+	 * site's schema predates the v0.20.0 columns (cron fired before the
+	 * admin_init migration pass), the write self-heals by retrying the
+	 * pre-v0.20.0 statement instead of losing the checkpoint.
+	 *
+	 * @param string      $run_id     Run UUID.
+	 * @param string      $stage      Stage name.
+	 * @param string      $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string      $item_key   Article scope.
+	 * @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 || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		$meta  = null !== $output ? wp_json_encode( array( 'output' => $output ) ) : null;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$result = $wpdb->query(
+			$wpdb->prepare(
+				"INSERT INTO {$table}
+				(run_id, stage, agent_role, item_key, status, attempt, cost_usd, meta_json, stale, started_at, updated_at, finished_at)
+				VALUES (%s, %s, %s, %s, 'done', 1, %f, %s, 0, %s, %s, %s)
+				ON DUPLICATE KEY UPDATE
+					status = 'done',
+					cost_usd = VALUES(cost_usd),
+					meta_json = VALUES(meta_json),
+					stale = 0,
+					updated_at = VALUES(updated_at),
+					finished_at = VALUES(finished_at)",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key,
+				$cost_usd,
+				$meta,
+				$now,
+				$now,
+				$now
+			)
+		);
+
+		// Self-healing on a half-migrated schema (no `stale` column yet):
+		// retry with the pre-v0.20.0 statement rather than losing the
+		// resume checkpoint. Same pattern as Cost_Tracker (v0.18.0).
+		if ( false === $result ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->query(
+				$wpdb->prepare(
+					"INSERT INTO {$table}
+					(run_id, stage, agent_role, item_key, status, attempt, cost_usd, meta_json, started_at, updated_at, finished_at)
+					VALUES (%s, %s, %s, %s, 'done', 1, %f, %s, %s, %s, %s)
+					ON DUPLICATE KEY UPDATE
+						status = 'done',
+						cost_usd = VALUES(cost_usd),
+						meta_json = VALUES(meta_json),
+						updated_at = VALUES(updated_at),
+						finished_at = VALUES(finished_at)",
+					$run_id,
+					$stage,
+					$agent_role,
+					$item_key,
+					$cost_usd,
+					$meta,
+					$now,
+					$now,
+					$now
+				)
+			);
+		}
+	}
+
+	/**
+	 * 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 ('' = resolve from stage map).
+	 * @param string $item_key   Article scope.
+	 */
+	public static function fail( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
+		if ( '' === $run_id || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s AND status != 'done'",
+				$now,
+				$now,
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key
+			)
+		);
+	}
+
+	/**
+	 * 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).
+	 */
+	public static function fail_open_for_item( string $run_id, string $item_key ): void {
+		if ( '' === $run_id || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND item_key = %s AND status IN ('pending','running')",
+				$now,
+				$now,
+				$run_id,
+				$item_key
+			)
+		);
+	}
+
+	/**
+	 * 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).
+	 *
+	 * Public in v0.20.0 (was private on Run_Stage_State) so the read API
+	 * and the rerun classes share one resolution source.
+	 *
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Caller-supplied role ('' = auto-resolve).
+	 * @return string Effective agent role.
+	 */
+	public 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-run-state.php

@@ -252,6 +252,41 @@ class PRAutoBlogger_Run_State {
 		return is_array( $rows ) ? $rows : array();
 	}
 
+	/**
+	 * Reopen a terminal run for operator-deliberate new spend (M3
+	 * re-runs). done/failed/halted -> running; finished_at cleared; the
+	 * cost ceiling is RE-SNAPSHOTTED from the current setting — the
+	 * deliberate re-run action adopts the operator's current per-run
+	 * policy (can lower as well as raise), exactly as a new run would.
+	 * Accumulated reserved/settled spend is kept: the governor treats
+	 * re-runs as new spend on the SAME run (CPO guardrail 4).
+	 *
+	 * The conditional UPDATE is the atomic gate: an actively executing
+	 * run (pending/running) can never be reopened.
+	 *
+	 * @param string $run_id Run UUID.
+	 * @return bool Whether the run transitioned to running.
+	 */
+	public static function reopen( string $run_id ): bool {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return false;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table}
+				SET status = 'running', ceiling_usd = %f, updated_at = %s, finished_at = NULL
+				WHERE run_id = %s AND status IN ('done','failed','halted')",
+				self::ceiling_setting(),
+				current_time( 'mysql' ),
+				$run_id
+			)
+		);
+		return 1 === (int) $updated;
+	}
+
 	/** Reset per-request caches (tests). */
 	public static function flush_cache(): void {
 		self::$table_ok = null;

includes/core/class-semantic-dedup.php

@@ -204,7 +204,7 @@ class PRAutoBlogger_Semantic_Dedup {
 			return false;
 		}
 		foreach ( $this->recent_titles as $title ) {
-			$title_keywords = $this->extract_meaningful_keywords( $title );
+			$title_keywords = PRAutoBlogger_Keyword_Extractor::extract( $title );
 			$overlap        = count( array_intersect( $topic_keywords, $title_keywords ) );
 			if ( $overlap / count( $topic_keywords ) >= 0.6 ) {
 				return true;
@@ -241,131 +241,4 @@ class PRAutoBlogger_Semantic_Dedup {
 		}
 		return $titles;
 	}
-
-	/**
-	 * Extract meaningful keywords from text (fallback dedup).
-	 *
-	 * @param string $text Input text.
-	 * @return string[] Unique lowercase keywords.
-	 */
-	private function extract_meaningful_keywords( string $text ): array {
-		static $stopwords = array(
-			'a',
-			'an',
-			'the',
-			'and',
-			'or',
-			'but',
-			'is',
-			'are',
-			'was',
-			'were',
-			'in',
-			'on',
-			'at',
-			'to',
-			'for',
-			'of',
-			'with',
-			'by',
-			'from',
-			'as',
-			'it',
-			'its',
-			'this',
-			'that',
-			'your',
-			'you',
-			'how',
-			'what',
-			'when',
-			'why',
-			'where',
-			'which',
-			'who',
-			'do',
-			'does',
-			'did',
-			'not',
-			'no',
-			'can',
-			'will',
-			'should',
-			'could',
-			'would',
-			'may',
-			'might',
-			'have',
-			'has',
-			'had',
-			'be',
-			'been',
-			'being',
-			'about',
-			'into',
-			'through',
-			'during',
-			'before',
-			'after',
-			'above',
-			'below',
-			'between',
-			'same',
-			'up',
-			'down',
-			'out',
-			'off',
-			'over',
-			'under',
-			'again',
-			'then',
-			'here',
-			'there',
-			'all',
-			'each',
-			'every',
-			'both',
-			'few',
-			'more',
-			'most',
-			'other',
-			'some',
-			'such',
-			'than',
-			'too',
-			'very',
-			'just',
-			'also',
-			'only',
-			'own',
-			'so',
-			'if',
-			'while',
-			'because',
-			'until',
-			'vs',
-			'versus',
-			'guide',
-			'complete',
-			'ultimate',
-			'best',
-			'top',
-			'new',
-			'first',
-			'need',
-			'know',
-			'everything',
-		);
-
-		$text  = strtolower( $text );
-		$words = preg_split( '/[^a-z0-9-]+/', $text, -1, PREG_SPLIT_NO_EMPTY );
-		$words = array_filter(
-			$words,
-			static function ( string $w ) use ( $stopwords ): bool {
-				return strlen( $w ) >= 2 && ! in_array( $w, $stopwords, true );
-			}
-		);
-
-		return array_values( array_unique( $words ) );
-	}
 }

includes/core/class-stage-input-store.php

@@ -0,0 +1,269 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * INSERT-only store over `wp_prautoblogger_stage_inputs` (v0.20.0, M3).
+ *
+ * What: Immutable input-version rows for the edit + re-run feature.
+ *       Two row kinds, discriminated by `source`:
+ *       - 'human': an operator's edited request body for one stage. Each
+ *         save creates the NEXT version for the (run, stage, role, item)
+ *         scope — there is deliberately no UPDATE path in this class, so
+ *         originals (and earlier forks) can never be overwritten (CPO
+ *         guardrail 1; the executed original lives untouched in
+ *         generation_log.request_json).
+ *       - 'seed': the serialized Article_Idea persisted at worker start
+ *         (stage='', version=1). Re-run-from-here reconstructs the EXACT
+ *         idea from it — rebuilding the idea from post fields would risk
+ *         an item_key hash mismatch (post_title is sanitized at insert)
+ *         and a duplicate post.
+ *       Self-healing: every method no-ops (null/false/empty) when the
+ *       table is missing (half-migrated schema).
+ *       Retention: human fork bodies are NULLed by the run-reaper after
+ *       R days (same setting as all heavy payloads); seed rows are ~1KB
+ *       structural state and are kept.
+ * Who triggers it: Dossier_Actions (save fork), Rerun_Executor (read fork
+ *       / seed), Article_Worker (save seed), Run_Reaper (prune).
+ * Dependencies: WordPress $wpdb.
+ *
+ * @see admin/class-dossier-actions.php — Fork save endpoint.
+ * @see core/class-rerun-executor.php   — Fork/seed consumption.
+ * @see core/class-run-reaper.php       — Retention prune.
+ * @see ARCHITECTURE.md #24             — Edit + re-run design.
+ */
+class PRAutoBlogger_Stage_Input_Store {
+
+	/** Source discriminator: operator edit fork. */
+	public const SOURCE_HUMAN = 'human';
+
+	/** Source discriminator: idea seed persisted at worker start. */
+	public const SOURCE_SEED = 'seed';
+
+	/** @var bool|null Per-request "stage_inputs table exists" probe result. */
+	private static ?bool $table_ok = null;
+
+	/** @return string Fully-qualified stage_inputs table name. */
+	public static function table_name(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'prautoblogger_stage_inputs';
+	}
+
+	/**
+	 * Whether the stage_inputs table exists. Cached per request.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		if ( null !== self::$table_ok ) {
+			return self::$table_ok;
+		}
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return false; // Not cached: $wpdb may appear later in boot.
+		}
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found          = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
+		self::$table_ok = ( $found === $table );
+		return self::$table_ok;
+	}
+
+	/**
+	 * Save a human edit fork as the next version for its scope.
+	 *
+	 * INSERT-only by design. The version number is MAX(version)+1 for the
+	 * scope; a concurrent-save collision on the UNIQUE key is retried
+	 * once with a refreshed version.
+	 *
+	 * Side effects: one (rarely two) INSERTs into stage_inputs.
+	 *
+	 * @param string $run_id       Run UUID.
+	 * @param string $stage        Stage name.
+	 * @param string $agent_role   Stage row's agent role.
+	 * @param string $item_key     Stage row's item key.
+	 * @param string $request_json Edited request body (full JSON, no headers).
+	 * @param string $author       WP user login of the editor.
+	 * @return int|null New version number, or null on failure/missing table.
+	 */
+	public static function save_fork( string $run_id, string $stage, string $agent_role, string $item_key, string $request_json, string $author ): ?int {
+		if ( '' === $run_id || '' === $stage || ! self::is_available() ) {
+			return null;
+		}
+		for ( $attempt = 0; $attempt < 2; $attempt++ ) {
+			$version  = self::next_version( $run_id, $stage, $agent_role, $item_key );
+			$inserted = self::insert_row( $run_id, $stage, $agent_role, $item_key, $version, self::SOURCE_HUMAN, $request_json, $author );
+			if ( $inserted ) {
+				return $version;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Latest human fork row for a scope, or null when none exist.
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Agent role.
+	 * @param string $item_key   Item key.
+	 * @return array<string, mixed>|null Row incl. version/request_json/author/created_at.
+	 */
+	public static function latest_fork( string $run_id, string $stage, string $agent_role, string $item_key ): ?array {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return null;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_row(
+			$wpdb->prepare(
+				"SELECT * FROM {$table}
+				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s AND source = %s
+				ORDER BY version DESC LIMIT 1",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key,
+				self::SOURCE_HUMAN
+			),
+			ARRAY_A
+		);
+		return is_array( $row ) ? $row : null;
+	}
+
+	/**
+	 * Persist the idea seed for one run item (INSERT-once; replays no-op).
+	 *
+	 * @param string $run_id    Run UUID.
+	 * @param string $item_key  Item key from Run_Stage_State::item_key_for_idea().
+	 * @param string $idea_json Serialized Article_Idea::to_array() payload.
+	 * @return void
+	 */
+	public static function save_seed( string $run_id, string $item_key, string $idea_json ): void {
+		if ( '' === $run_id || '' === $item_key || ! self::is_available() ) {
+			return;
+		}
+		if ( null !== self::get_seed( $run_id, $item_key ) ) {
+			return; // Seed already persisted (idempotent resume).
+		}
+		self::insert_row( $run_id, '', '', $item_key, 1, self::SOURCE_SEED, $idea_json, 'pipeline' );
+	}
+
+	/**
+	 * The idea seed JSON for one run item, or null when absent.
+	 *
+	 * @param string $run_id   Run UUID.
+	 * @param string $item_key Item key.
+	 * @return string|null
+	 */
+	public static function get_seed( string $run_id, string $item_key ): ?string {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return null;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$json = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT request_json FROM {$table}
+				WHERE run_id = %s AND stage = '' AND item_key = %s AND source = %s LIMIT 1",
+				$run_id,
+				$item_key,
+				self::SOURCE_SEED
+			)
+		);
+		return ( is_string( $json ) && '' !== $json ) ? $json : null;
+	}
+
+	/**
+	 * Retention: NULL human fork bodies older than the cutoff. Seed rows
+	 * are kept (structural, ~1KB). Version/author/flag metadata survives
+	 * as the permanent audit trail.
+	 *
+	 * @param string $cutoff MySQL datetime; rows created before it are pruned.
+	 * @return int Rows pruned.
+	 */
+	public static function prune_human_bodies( string $cutoff ): int {
+		if ( ! self::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$result = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET request_json = NULL
+				WHERE source = %s AND request_json IS NOT NULL AND created_at < %s",
+				self::SOURCE_HUMAN,
+				$cutoff
+			)
+		);
+		return is_numeric( $result ) ? (int) $result : 0;
+	}
+
+	/** Reset per-request caches (tests). */
+	public static function flush_cache(): void {
+		self::$table_ok = null;
+	}
+
+	/**
+	 * Next version number for a scope (1 when none exist).
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Agent role.
+	 * @param string $item_key   Item key.
+	 * @return int
+	 */
+	private static function next_version( string $run_id, string $stage, string $agent_role, string $item_key ): int {
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$max = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT MAX(version) FROM {$table}
+				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key
+			)
+		);
+		return ( null !== $max ? (int) $max : 0 ) + 1;
+	}
+
+	/**
+	 * Raw row INSERT (the only write path — INSERT-only by construction).
+	 *
+	 * @param string $run_id       Run UUID.
+	 * @param string $stage        Stage name ('' for seeds).
+	 * @param string $agent_role   Agent role.
+	 * @param string $item_key     Item key.
+	 * @param int    $version      Version number.
+	 * @param string $source       'human' or 'seed'.
+	 * @param string $request_json Payload JSON.
+	 * @param string $author       Author label.
+	 * @return bool Whether the row was inserted.
+	 */
+	private static function insert_row( string $run_id, string $stage, string $agent_role, string $item_key, int $version, string $source, string $request_json, string $author ): bool {
+		global $wpdb;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$inserted = $wpdb->insert(
+			self::table_name(),
+			array(
+				'run_id'       => $run_id,
+				'stage'        => $stage,
+				'agent_role'   => $agent_role,
+				'item_key'     => $item_key,
+				'version'      => $version,
+				'source'       => $source,
+				'request_json' => $request_json,
+				'author'       => $author,
+				'created_at'   => current_time( 'mysql' ),
+			)
+		);
+		return false !== $inserted;
+	}
+}

includes/core/class-stage-replay.php

@@ -0,0 +1,189 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Executes one stage replay from a saved input fork (v0.20.0, M3).
+ *
+ * What: Decodes an immutable stage_inputs fork body back into the
+ *       (messages, model, options) triple and sends it through the
+ *       normal provider seam — so the cost governor's reserve-before-
+ *       call (on the SAME run ledger row), the retry/backoff loop, the
+ *       empty-completion guard, and the B1 request recorder all apply
+ *       to replays exactly as to pipeline calls (CPO guardrail 4). The
+ *       fresh output lands in the stage's run_stages snapshot (the same
+ *       place downstream rebuilds read from) and a generation_log row
+ *       is written with the replayed request body.
+ *
+ *       options_from_body() is the exact inverse of Request_Builder::
+ *       build_body() + apply_reasoning_budget(): the v0.18.1 reasoning
+ *       headroom is subtracted back out (the builder re-adds it), and
+ *       reasoning is pinned explicitly — enabled:false when the original
+ *       body had none — so a later change to the global reasoning
+ *       setting can never alter the replay's shape.
+ * Who triggers it: PRAutoBlogger_Rerun_Executor::on_replay_job() only
+ *       (after eligibility re-validation, lock, reopen, restart and
+ *       stale-marking).
+ * Dependencies: OpenRouter_Provider, Cost_Tracker, Run_Stage_State,
+ *               Audit_Writer, Stage_Display_Map.
+ *
+ * @see core/class-rerun-executor.php                 — Orchestration around this.
+ * @see providers/class-open-router-request-builder.php — The forward transform.
+ * @see ARCHITECTURE.md #24                           — Edit + re-run design.
+ */
+class PRAutoBlogger_Stage_Replay {
+
+	/**
+	 * Reconstruct provider options from a stored request body.
+	 *
+	 * Inverse of build_body()/apply_reasoning_budget(): copies
+	 * temperature/response_format; recovers the caller's max_tokens by
+	 * subtracting the reasoning cap the builder added as headroom; pins
+	 * reasoning explicitly (the stored body is the contract — global
+	 * setting drift must not leak in). Adds the caller-metadata keys
+	 * (stage, prompt_key) used by the guard's logging — never sent
+	 * upstream.
+	 *
+	 * @param array<string, mixed> $body  Decoded request body.
+	 * @param string               $stage Stage being replayed.
+	 * @return array<string, mixed> Options for send_chat_completion().
+	 */
+	public static function options_from_body( array $body, string $stage ): array {
+		$options = array();
+		if ( isset( $body['temperature'] ) ) {
+			$options['temperature'] = $body['temperature'];
+		}
+		if ( isset( $body['response_format'] ) ) {
+			$options['response_format'] = $body['response_format'];
+		}
+
+		$reasoning_active = isset( $body['reasoning'] ) && false !== ( $body['reasoning']['enabled'] ?? true );
+		if ( $reasoning_active ) {
+			$options['reasoning'] = $body['reasoning'];
+			if ( isset( $body['max_tokens'] ) ) {
+				$cap = isset( $body['reasoning']['max_tokens'] ) ? (int) $body['reasoning']['max_tokens'] : 0;
+				// The builder raised max_tokens by the cap (completion
+				// headroom); hand back the caller-level value so the
+				// builder's re-application is not compounded.
+				$options['max_tokens'] = max( 1, (int) $body['max_tokens'] - $cap );
+			}
+		} else {
+			// Pin reasoning OFF (same per-call override shape the
+			// empty-completion retry uses) so a globally-enabled
+			// reasoning setting cannot reshape the replay.
+			$options['reasoning'] = array( 'enabled' => false );
+			if ( isset( $body['max_tokens'] ) ) {
+				$options['max_tokens'] = (int) $body['max_tokens'];
+			}
+		}
+
+		$options['stage']      = $stage;
+		$options['prompt_key'] = PRAutoBlogger_Stage_Display_Map::default_prompt_key( $stage );
+
+		return $options;
+	}
+
+	/**
+	 * Decode + validate a fork body. Returns null when the JSON is not a
+	 * replayable chat body (model string + non-empty messages list of
+	 * role/content pairs).
+	 *
+	 * @param string $request_json Stored fork body.
+	 * @return array<string, mixed>|null Decoded body, or null when invalid.
+	 */
+	public static function decode_body( string $request_json ): ?array {
+		$body = json_decode( $request_json, true );
+		if ( ! is_array( $body ) || empty( $body['model'] ) || ! is_string( $body['model'] ) ) {
+			return null;
+		}
+		if ( empty( $body['messages'] ) || ! is_array( $body['messages'] ) ) {
+			return null;
+		}
+		foreach ( $body['messages'] as $message ) {
+			if ( ! is_array( $message ) || ! isset( $message['role'], $message['content'] )
+				|| ! is_string( $message['role'] ) || ! is_string( $message['content'] ) ) {
+				return null;
+			}
+		}
+		return $body;
+	}
+
+	/**
+	 * Execute the replay call and persist its results.
+	 *
+	 * The caller (Rerun_Executor) has already: re-validated eligibility,
+	 * taken the generation lock, reopened the run, demoted the stage row
+	 * to running and stale-marked downstream. This method performs the
+	 * governed LLM call and the success-path writes.
+	 *
+	 * Side effects: one OpenRouter call (governor-reserved), run_stages
+	 * done-write, one generation_log row (with the replayed request via
+	 * the B1 recorder), run_decisions human_modified flags.
+	 *
+	 * @param string               $run_id     Run UUID.
+	 * @param string               $stage      Stage name.
+	 * @param string               $agent_role Stage row agent role.
+	 * @param string               $item_key   Stage row item key.
+	 * @param array<string, mixed> $body       Decoded fork body (from decode_body()).
+	 * @return array{content: string, cost: float, model: string} Replay result.
+	 *
+	 * @throws \RuntimeException                    On provider failure or empty output.
+	 * @throws PRAutoBlogger_Cost_Ceiling_Exception When the governor blocks the call.
+	 */
+	public static function run( string $run_id, string $stage, string $agent_role, string $item_key, array $body ): array {
+		$tracker = new PRAutoBlogger_Cost_Tracker();
+		// Joins this process to the run: Run_Context (governor guard),
+		// ledger row, prompt pins — replay spend reserves against the
+		// SAME per-run ceiling as the original calls (guardrail 4).
+		$tracker->set_run_id( $run_id );
+
+		$llm      = new PRAutoBlogger_OpenRouter_Provider();
+		$options  = self::options_from_body( $body, $stage );
+		$response = $llm->send_chat_completion( $body['messages'], (string) $body['model'], $options );
+
+		// Same belt as the writer path: an empty replay output must fail
+		// the stage, never overwrite a good snapshot with nothing.
+		if ( '' === trim( (string) $response['content'] ) ) {
+			throw new \RuntimeException(
+				sprintf(
+					/* translators: 1: stage name, 2: model identifier. */
+					__( 'Replay of stage "%1$s" produced empty content (model %2$s) — failing the replay instead of storing an empty output.', 'prautoblogger' ),
+					$stage,
+					(string) $response['model']
+				)
+			);
+		}
+
+		$cost = $llm->estimate_cost(
+			(string) $response['model'],
+			(int) $response['prompt_tokens'],
+			(int) $response['completion_tokens']
+		);
+
+		PRAutoBlogger_Run_Stage_State::done( $run_id, $stage, $agent_role, $item_key, (string) $response['content'], $cost );
+
+		$tracker->log_api_call(
+			null,
+			$stage,
+			$llm->get_provider_name(),
+			(string) $response['model'],
+			(int) $response['prompt_tokens'],
+			(int) $response['completion_tokens'],
+			'success',
+			'',
+			'' !== $agent_role ? $agent_role : null,
+			null
+		);
+
+		// Guardrail 2: decision rows for the replayed stage carry the
+		// human_modified flag (no-op when the stage has none).
+		PRAutoBlogger_Audit_Writer::flag_decisions_human_modified( $run_id, array( $stage ) );
+
+		return array(
+			'content' => (string) $response['content'],
+			'cost'    => $cost,
+			'model'   => (string) $response['model'],
+		);
+	}
+}

includes/providers/class-image-aspect-ratio.php

@@ -0,0 +1,88 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Aspect-ratio snap utility for image generation providers.
+ *
+ * Converts pixel dimensions to the nearest supported W:H string for APIs
+ * that require an aspect-ratio parameter rather than raw pixel sizes.
+ *
+ * What: Static utility; no state.
+ * Who triggers: PRAutoBlogger_OpenRouter_Image_Provider, PRAutoBlogger_OpenRouter_Image_Batch,
+ *               PRAutoBlogger_Runware_Image_Batch.
+ * Dependencies: none.
+ *
+ * @see providers/class-open-router-image-provider.php -- generate_image() path.
+ * @see providers/class-open-router-image-batch.php    -- parallel batch path.
+ * @see providers/class-runware-image-batch.php        -- Runware parallel batch.
+ */
+class PRAutoBlogger_Image_Aspect_Ratio {
+
+	/**
+	 * Standard aspect ratios supported by OpenRouter / Runware image models.
+	 *
+	 * @var array<int, array{w: int, h: int, ratio: float}>
+	 */
+	private const STANDARD_ASPECTS = array(
+		array(
+			'w' => 1,
+			'h' => 1,
+			'ratio' => 1.0,
+		),
+		array(
+			'w' => 3,
+			'h' => 2,
+			'ratio' => 1.5,
+		),
+		array(
+			'w' => 2,
+			'h' => 3,
+			'ratio' => 0.6667,
+		),
+		array(
+			'w' => 4,
+			'h' => 3,
+			'ratio' => 1.3333,
+		),
+		array(
+			'w' => 3,
+			'h' => 4,
+			'ratio' => 0.75,
+		),
+		array(
+			'w' => 16,
+			'h' => 9,
+			'ratio' => 1.7778,
+		),
+		array(
+			'w' => 9,
+			'h' => 16,
+			'ratio' => 0.5625,
+		),
+	);
+
+	/**
+	 * Snap pixel dimensions to the nearest supported aspect ratio string.
+	 *
+	 * @param int $width  Width in pixels.
+	 * @param int $height Height in pixels (must be > 0 to avoid division by zero).
+	 * @return string Ratio string e.g. "16:9". Returns "1:1" when height is 0.
+	 */
+	public static function snap( int $width, int $height ): string {
+		$target = $height > 0 ? (float) $width / (float) $height : 1.0;
+		$best   = self::STANDARD_ASPECTS[0];
+		$best_d = abs( $target - $best['ratio'] );
+
+		foreach ( self::STANDARD_ASPECTS as $candidate ) {
+			$d = abs( $target - $candidate['ratio'] );
+			if ( $d < $best_d ) {
+				$best   = $candidate;
+				$best_d = $d;
+			}
+		}
+
+		return $best['w'] . ':' . $best['h'];
+	}
+}

includes/providers/class-open-router-image-batch.php

@@ -262,56 +262,7 @@ class PRAutoBlogger_OpenRouter_Image_Batch {
 	 * @return array<string, mixed>
 	 */
 	private function build_request_body( string $prompt, int $width, int $height, string $model ): array {
-		$target = $height > 0 ? (float) $width / (float) $height : 1.0;
-
-		// Snap to nearest standard aspect ratio.
-		$aspects = array(
-			array(
-				'w' => 1,
-				'h' => 1,
-				'r' => 1.0,
-			),
-			array(
-				'w' => 3,
-				'h' => 2,
-				'r' => 1.5,
-			),
-			array(
-				'w' => 2,
-				'h' => 3,
-				'r' => 0.6667,
-			),
-			array(
-				'w' => 4,
-				'h' => 3,
-				'r' => 1.3333,
-			),
-			array(
-				'w' => 3,
-				'h' => 4,
-				'r' => 0.75,
-			),
-			array(
-				'w' => 16,
-				'h' => 9,
-				'r' => 1.7778,
-			),
-			array(
-				'w' => 9,
-				'h' => 16,
-				'r' => 0.5625,
-			),
-		);
-		$best    = $aspects[0];
-		$best_d  = abs( $target - $best['r'] );
-		foreach ( $aspects as $c ) {
-			$d = abs( $target - $c['r'] );
-			if ( $d < $best_d ) {
-				$best   = $c;
-				$best_d = $d;
-			}
-		}
-		$aspect = $best['w'] . ':' . $best['h'];
+		$aspect = PRAutoBlogger_Image_Aspect_Ratio::snap( $width, $height );
 
 		return array(
 			'model'        => $model,

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

@@ -233,51 +233,10 @@ class PRAutoBlogger_OpenRouter_Image_Provider implements PRAutoBlogger_Image_Pro
 		);
 	}
 
-	/**
-	 * Supported aspect ratios for OpenRouter image models.
-	 *
-	 * @var array<int, array{w: int, h: int, ratio: float}>
-	 */
-	private const STANDARD_ASPECTS = array(
-		array(
-			'w'     => 1,
-			'h'     => 1,
-			'ratio' => 1.0,
-		),
-		array(
-			'w'     => 3,
-			'h'     => 2,
-			'ratio' => 1.5,
-		),
-		array(
-			'w'     => 2,
-			'h'     => 3,
-			'ratio' => 0.6667,
-		),
-		array(
-			'w'     => 4,
-			'h'     => 3,
-			'ratio' => 1.3333,
-		),
-		array(
-			'w'     => 3,
-			'h'     => 4,
-			'ratio' => 0.75,
-		),
-		array(
-			'w'     => 16,
-			'h'     => 9,
-			'ratio' => 1.7778,
-		),
-		array(
-			'w'     => 9,
-			'h'     => 16,
-			'ratio' => 0.5625,
-		),
-	);
+
 
 	private function build_request_body( string $prompt, int $width, int $height, string $model ): array {
-		$aspect = $this->snap_aspect_ratio( $width, $height );
+		$aspect = PRAutoBlogger_Image_Aspect_Ratio::snap( $width, $height );
 
 		return array(
 			'model'        => $model,
@@ -296,29 +255,6 @@ class PRAutoBlogger_OpenRouter_Image_Provider implements PRAutoBlogger_Image_Pro
 		);
 	}
 
-	/**
-	 * Snap pixel dimensions to the nearest supported aspect ratio string.
-	 *
-	 * @param int $width  Width in pixels.
-	 * @param int $height Height in pixels.
-	 * @return string Aspect ratio string like "16:9".
-	 */
-	private function snap_aspect_ratio( int $width, int $height ): string {
-		$target = $height > 0 ? (float) $width / (float) $height : 1.0;
-		$best   = self::STANDARD_ASPECTS[0];
-		$best_d = abs( $target - $best['ratio'] );
-
-		foreach ( self::STANDARD_ASPECTS as $candidate ) {
-			$d = abs( $target - $candidate['ratio'] );
-			if ( $d < $best_d ) {
-				$best   = $candidate;
-				$best_d = $d;
-			}
-		}
-
-		return $best['w'] . ':' . $best['h'];
-	}
-
 	/**
 	 * Enforce the interface's dimension contract.
 	 *

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

@@ -78,6 +78,13 @@ class PRAutoBlogger_OpenRouter_Provider implements PRAutoBlogger_LLM_Provider_In
 		// reasoning token cap + completion headroom — lives in the builder.
 		$body = $builder->build_body( $messages, $model, $options );
 
+		// v0.20.0 (B1): stash the outgoing request body so the next
+		// log_api_call() persists it to generation_log.request_json.
+		// Only the BODY is recorded -- Authorization lives exclusively in
+		// build_headers()' return and can never reach the recorder.
+		// Recorded BEFORE dispatch so error/timeout rows carry it too.
+		PRAutoBlogger_Request_Recorder::record( $body );
+
 		// 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 );

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

@@ -2,19 +2,7 @@
 // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
 declare(strict_types=1);
 
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_init
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_setopt
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_close
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_errno
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_error
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_getinfo
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_init
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_add_handle
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_exec
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_select
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_getcontent
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_remove_handle
-// phpcs:disable WordPress.WP.AlternativeFunctions.curl_curl_multi_close
+// phpcs:disable WordPress.WP.AlternativeFunctions -- curl_multi required for parallel image generation; no WP HTTP equivalent.
 
 /**
  * Parallel image generation via curl_multi for Runware.

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

@@ -178,72 +178,15 @@ class PRAutoBlogger_Runware_Image_Provider implements PRAutoBlogger_Image_Provid
 	/**
 	 * {@inheritDoc}
 	 *
-	 * Runware has no dedicated "validate key" endpoint, so we send a minimal
-	 * authentication task and look for `taskType=authentication` in the
-	 * response data with no accompanying errors.
+	 * Delegates to PRAutoBlogger_Runware_Validator (extracted for 300-line compliance).
+	 *
+	 * @see providers/class-runware-image-validator.php
 	 */
 	public function validate_credentials_detailed(): array {
-		try {
-			$api_key = $this->support->get_api_key();
-		} catch ( \RuntimeException $e ) {
-			return array(
-				'status'  => 'error',
-				'message' => $e->getMessage(),
-			);
-		}
-
-		$body = array(
-			array(
-				'taskType' => 'authentication',
-				'apiKey'   => $api_key,
-			),
-		);
-
-		$response = wp_remote_post(
-			PRAutoBlogger_Runware_Image_Support::API_URL,
-			array(
-				'timeout' => 15,
-				'headers' => array( 'Content-Type' => 'application/json' ),
-				'body'    => wp_json_encode( $body ),
-			)
-		);
-
-		if ( is_wp_error( $response ) ) {
-			return array(
-				'status'  => 'error',
-				'message' => __( 'Could not reach Runware API.', 'prautoblogger' ),
-				'debug'   => $response->get_error_message(),
-			);
-		}
-
-		$status = (int) wp_remote_retrieve_response_code( $response );
-		$raw    = (string) wp_remote_retrieve_body( $response );
-
-		if ( 200 !== $status ) {
-			return array(
-				'status'  => 'error',
-				'message' => sprintf( __( 'Runware returned HTTP %d.', 'prautoblogger' ), $status ),
-				'debug'   => substr( $raw, 0, 200 ),
-			);
-		}
-
-		$decoded = json_decode( $raw, true );
-		if ( is_array( $decoded ) && isset( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
-			$first = $decoded['errors'][0] ?? array();
-			$msg   = is_array( $first ) ? (string) ( $first['message'] ?? '' ) : (string) $first;
-			return array(
-				'status'  => 'error',
-				'message' => __( 'Runware rejected the API key.', 'prautoblogger' ),
-				'debug'   => substr( $msg, 0, 200 ),
-			);
-		}
-
-		return array(
-			'status'  => 'ok',
-			'message' => __( 'Runware API key valid.', 'prautoblogger' ),
-		);
+		return PRAutoBlogger_Runware_Validator::validate( $this->support );
 	}
 
+
 	/**
 	 * Build the JSON task-array body for a single imageInference request.
 	 *

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

@@ -0,0 +1,89 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Credential validator for the Runware image provider.
+ *
+ * Extracted from PRAutoBlogger_Runware_Image_Provider for 300-line compliance.
+ * Sends a minimal authentication task to Runware's API to confirm the key is valid.
+ *
+ * What: Static utility; no state.
+ * Who triggers: PRAutoBlogger_Runware_Image_Provider::validate_credentials_detailed().
+ * Dependencies: PRAutoBlogger_Runware_Image_Support (API_URL constant, get_api_key()).
+ *
+ * @see providers/class-runware-image-provider.php -- Sole caller.
+ * @see providers/class-runware-image-support.php  -- API key retrieval + URL.
+ */
+class PRAutoBlogger_Runware_Validator {
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * Runware has no dedicated "validate key" endpoint, so we send a minimal
+	 * authentication task and look for `taskType=authentication` in the
+	 * response data with no accompanying errors.
+	 */
+	public static function validate( PRAutoBlogger_Runware_Image_Support $support ): array {
+		try {
+			$api_key = $support->get_api_key();
+		} catch ( \RuntimeException $e ) {
+			return array(
+				'status'  => 'error',
+				'message' => $e->getMessage(),
+			);
+		}
+
+		$body = array(
+			array(
+				'taskType' => 'authentication',
+				'apiKey'   => $api_key,
+			),
+		);
+
+		$response = wp_remote_post(
+			PRAutoBlogger_Runware_Image_Support::API_URL,
+			array(
+				'timeout' => 15,
+				'headers' => array( 'Content-Type' => 'application/json' ),
+				'body'    => wp_json_encode( $body ),
+			)
+		);
+
+		if ( is_wp_error( $response ) ) {
+			return array(
+				'status'  => 'error',
+				'message' => __( 'Could not reach Runware API.', 'prautoblogger' ),
+				'debug'   => $response->get_error_message(),
+			);
+		}
+
+		$status = (int) wp_remote_retrieve_response_code( $response );
+		$raw    = (string) wp_remote_retrieve_body( $response );
+
+		if ( 200 !== $status ) {
+			return array(
+				'status'  => 'error',
+				'message' => sprintf( __( 'Runware returned HTTP %d.', 'prautoblogger' ), $status ),
+				'debug'   => substr( $raw, 0, 200 ),
+			);
+		}
+
+		$decoded = json_decode( $raw, true );
+		if ( is_array( $decoded ) && isset( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
+			$first = $decoded['errors'][0] ?? array();
+			$msg   = is_array( $first ) ? (string) ( $first['message'] ?? '' ) : (string) $first;
+			return array(
+				'status'  => 'error',
+				'message' => __( 'Runware rejected the API key.', 'prautoblogger' ),
+				'debug'   => substr( $msg, 0, 200 ),
+			);
+		}
+
+		return array(
+			'status'  => 'ok',
+			'message' => __( 'Runware API key valid.', 'prautoblogger' ),
+		);
+	}
+}

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.19.4
+ * Version:           0.22.1
  * Requires at least: 6.0
  * Requires PHP:      7.4
  * Author:            PeptideRepo
@@ -35,8 +35,20 @@ if ( ! defined( 'ABSPATH' ) ) {
 | Defined here so every file in the plugin can reference paths, versions,
 | and limits without magic strings.
 */
-define( 'PRAUTOBLOGGER_VERSION', '0.19.4' );
-define( 'PRAUTOBLOGGER_DB_VERSION', '1.1.0' );
+define( 'PRAUTOBLOGGER_VERSION', '0.22.1' );
+define( 'PRAUTOBLOGGER_DB_VERSION', '1.4.0' );
+define( 'PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD', 0.50 );
+define( 'PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS', 14 );
+// Default max cards shown per board column and per ideas-browser page.
+// Settings-backed (prautoblogger_board_column_limit, prautoblogger_ideas_per_page).
+define( 'PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT', 20 );
+define( 'PRAUTOBLOGGER_DEFAULT_IDEAS_PER_PAGE', 30 );
+// 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_PLUGIN_FILE', __FILE__ );
 define( 'PRAUTOBLOGGER_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
 define( 'PRAUTOBLOGGER_PLUGIN_URL', plugin_dir_url( __FILE__ ) );

scripts/check-constants.php

@@ -0,0 +1,252 @@
+<?php
+/**
+ * CI guard: every PRAUTOBLOGGER_* constant referenced in the shipped plugin PHP
+ * must be either (a) defined in prautoblogger.php, or (b) protected by a
+ * defined() guard at the reference site.
+ *
+ * Purpose: prevent the class of regression that caused the v0.19.0 admin-500
+ * incident — a constant deleted from prautoblogger.php while tests/bootstrap.php
+ * kept a fallback copy, masking the gap until prod boot.
+ *
+ * Usage (from repo root):
+ *   php scripts/check-constants.php [--verbose] [--self-test]
+ *
+ * Exit 0 = all clear. Exit 1 = unguarded undefined constants found. Exit 2 = --self-test failed.
+ *
+ * Include/exclude summary (relative to repo root):
+ *   Defined-set source  prautoblogger.php only
+ *   Scanned for refs    prautoblogger.php, includes/, templates/, uninstall.php
+ *   Excluded from refs  tests/ vendor/ .github/ .git/ node_modules/
+ *   Excluded from defs  everything except prautoblogger.php
+ *
+ * Guard window: a bare constant use is considered guarded if a defined() call
+ * for the same constant appears within GUARD_WINDOW lines above it in the same
+ * file (covers if/elseif blocks and multi-line && chains).
+ *
+ * @package PRAutoBlogger
+ */
+
+declare(strict_types=1);
+
+// How many lines above the bare use to look for a defined() guard.
+const CONSTANTS_GUARD_WINDOW = 4; // 4 covers if/elseif blocks and multi-line && chains (wider risks false-positives).
+
+// Source of truth for define()d constants -- test-bootstrap fallbacks excluded.
+const CONSTANTS_BOOTSTRAP_FILE = 'prautoblogger.php';
+
+// Directories skipped when walking the shipped tree for references.
+const CONSTANTS_EXCLUDE_DIRS = array( 'tests', 'vendor', '.github', '.git', 'node_modules' );
+
+// Entry points for the reference scan (files and dirs relative to repo root).
+const CONSTANTS_SCAN_ROOTS = array(
+	'prautoblogger.php',
+	'uninstall.php',
+	'includes',
+	'templates',
+);
+
+$verbose   = in_array( '--verbose', $argv ?? array(), true );
+$self_test = in_array( '--self-test', $argv ?? array(), true );
+
+// -------------------------------------------------------------------------
+// 1. Build the defined set from prautoblogger.php only.
+// -------------------------------------------------------------------------
+
+if ( ! file_exists( CONSTANTS_BOOTSTRAP_FILE ) ) {
+	fwrite( STDERR, "ERROR: bootstrap file not found -- run from repo root.\n" );
+	fwrite( STDERR, '  Expected: ' . CONSTANTS_BOOTSTRAP_FILE . "\n" );
+	exit( 1 );
+}
+
+$bootstrap_src = (string) file_get_contents( CONSTANTS_BOOTSTRAP_FILE );
+
+preg_match_all(
+	"/define\s*\(\s*'(PRAUTOBLOGGER_[A-Z0-9_]+)'/",
+	$bootstrap_src,
+	$def_matches
+);
+
+/** @var array<string, int> $defined_set constant name => 1 */
+$defined_set = array_flip( $def_matches[1] ?? array() );
+
+if ( $verbose ) {
+	echo 'Defined in ' . CONSTANTS_BOOTSTRAP_FILE . ' (' . count( $defined_set ) . "):\n";
+	foreach ( array_keys( $defined_set ) as $constant_name ) {
+		echo "  {$constant_name}\n";
+	}
+	echo "\n";
+}
+
+// -------------------------------------------------------------------------
+// 2. Collect shipped PHP files to scan.
+// -------------------------------------------------------------------------
+
+/**
+ * Recursively collect *.php paths under a directory, skipping excluded dirs.
+ *
+ * @param string   $dir   Directory to walk.
+ * @param string[] $files Accumulator (modified by reference).
+ * @return void
+ */
+function constants_collect_php_files( string $dir, array &$files ): void {
+	$dir_iter = new DirectoryIterator( $dir );
+	foreach ( $dir_iter as $entry ) {
+		if ( $entry->isDot() ) {
+			continue;
+		}
+		$basename = $entry->getBasename();
+		if ( $entry->isDir() ) {
+			if ( ! in_array( $basename, CONSTANTS_EXCLUDE_DIRS, true ) ) {
+				constants_collect_php_files( $entry->getPathname(), $files );
+			}
+			continue;
+		}
+		if ( $entry->isFile() && $entry->getExtension() === 'php' ) {
+			$files[] = $entry->getPathname();
+		}
+	}
+}
+
+/** @var string[] $php_files */
+$php_files = array();
+
+foreach ( CONSTANTS_SCAN_ROOTS as $root ) {
+	if ( ! file_exists( $root ) ) {
+		// Template dir may not exist in very early checkouts -- skip silently.
+		continue;
+	}
+	if ( is_file( $root ) ) {
+		$php_files[] = $root;
+	} else {
+		constants_collect_php_files( $root, $php_files );
+	}
+}
+
+sort( $php_files );
+
+if ( $verbose ) {
+	echo 'Scanning ' . count( $php_files ) . " PHP files\n\n";
+}
+
+// -------------------------------------------------------------------------
+// 3. Scan each file for bare PRAUTOBLOGGER_* references.
+// -------------------------------------------------------------------------
+
+/** @var array<int, array{string, int, string, string}> $errors */
+$errors = array();
+
+foreach ( $php_files as $php_path ) {
+	$raw = file_get_contents( $php_path );
+	if ( false === $raw ) {
+		fwrite( STDERR, "WARNING: cannot read {$php_path} -- skipping\n" );
+		continue;
+	}
+
+	$lines = explode( "\n", $raw );
+
+	foreach ( $lines as $idx => $raw_line ) {
+		// Fast pre-check: skip lines with no PRAUTOBLOGGER_ token.
+		if ( strpos( $raw_line, 'PRAUTOBLOGGER_' ) === false ) {
+			continue;
+		}
+
+		// Skip pure comment lines (docblock * lines, // comments, # lines).
+		$trimmed = ltrim( $raw_line );
+		if (
+			str_starts_with( $trimmed, '*' ) ||
+			str_starts_with( $trimmed, '//' ) ||
+			str_starts_with( $trimmed, '#' )
+		) {
+			continue;
+		}
+
+		// Extract all constant names from this line.
+		if ( ! preg_match_all( '/PRAUTOBLOGGER_[A-Z0-9_]+/', $raw_line, $match ) ) {
+			continue;
+		}
+
+		foreach ( $match[0] as $name ) {
+			// Skip if this line is itself a define() call for this name.
+			if ( preg_match( "/define\s*\(\s*'" . preg_quote( $name, '/' ) . "'/", $raw_line ) ) {
+				continue;
+			}
+
+			// Skip if the constant is production-defined in prautoblogger.php.
+			if ( isset( $defined_set[ $name ] ) ) {
+				continue;
+			}
+
+			// Check for a defined() guard in the preceding GUARD_WINDOW lines
+			// (inclusive of the current line to catch same-line chained &&).
+			$window_start = max( 0, $idx - CONSTANTS_GUARD_WINDOW );
+			$guarded      = false;
+			for ( $w = $window_start; $w <= $idx; $w++ ) {
+				if ( preg_match( "/defined\s*\(\s*'" . preg_quote( $name, '/' ) . "'/", $lines[ $w ] ) ) {
+					$guarded = true;
+					break;
+				}
+			}
+
+			if ( ! $guarded ) {
+				$errors[] = array( $php_path, $idx + 1, $name, $raw_line );
+			}
+		}
+	}
+}
+
+// -------------------------------------------------------------------------
+// 4. Report results.
+// -------------------------------------------------------------------------
+
+if ( array() !== $errors ) {
+	fwrite( STDERR, "\nFAIL -- Unguarded undefined PRAUTOBLOGGER_* constants:\n\n" );
+	foreach ( $errors as [ $php_path, $lineno, $name, $line_text ] ) {
+		fwrite( STDERR, "  {$php_path}:{$lineno}: {$name}\n" );
+		fwrite( STDERR, '    ' . trim( $line_text ) . "\n" );
+	}
+	fwrite( STDERR, "\nTo fix: add  define( '" . $errors[0][2] . "', ... )  to prautoblogger.php,\n" );
+	fwrite( STDERR, "or guard the reference with  if ( defined( '" . $errors[0][2] . "' ) ) { ... }\n\n" );
+	exit( 1 );
+}
+
+// -------------------------------------------------------------------------
+// 5. Self-test mode: synthesize a missing constant and assert non-zero exit.
+// -------------------------------------------------------------------------
+
+if ( $self_test ) {
+	// Temporarily inject a fake reference that must NOT be in prautoblogger.php.
+	// The scan above will flag PRAUTOBLOGGER_SELFTEST_SENTINEL as unguarded.
+	// We verify this script would have exited non-zero in that scenario.
+	$sentinel      = 'PRAUTOBLOGGER_SELFTEST_SENTINEL';
+	$bootstrap_src = (string) file_get_contents( CONSTANTS_BOOTSTRAP_FILE );
+	if ( false !== strpos( $bootstrap_src, $sentinel ) ) {
+		fwrite( STDERR, "SELF-TEST FAIL: sentinel constant already defined in prautoblogger.php -- pick a unique name.\n" );
+		exit( 2 );
+	}
+
+	// If $errors is empty at this point, the real codebase is clean (good).
+	// Now simulate an unguarded reference by re-running the scan on a temp file.
+	$tmp_file = tempnam( sys_get_temp_dir(), 'prab_selftest_' ) . '.php';
+	file_put_contents( $tmp_file, "<?php\necho {$sentinel};\n" );
+	$tmp_errors = array();
+	$tmp_lines  = explode( "\n", (string) file_get_contents( $tmp_file ) );
+	foreach ( $tmp_lines as $idx => $raw_line ) {
+		if ( preg_match_all( '/PRAUTOBLOGGER_[A-Z0-9_]+/', $raw_line, $m ) ) {
+			foreach ( $m[0] as $n ) {
+				if ( ! isset( $defined_set[ $n ] ) ) {
+					$tmp_errors[] = $n;
+				}
+			}
+		}
+	}
+	@unlink( $tmp_file );
+	if ( ! in_array( $sentinel, $tmp_errors, true ) ) {
+		fwrite( STDERR, "SELF-TEST FAIL: scanner did not detect unguarded sentinel constant.\n" );
+		exit( 2 );
+	}
+	echo "SELF-TEST OK -- scanner correctly detected the synthetic missing constant.\n";
+	exit( 0 );
+}
+
+echo "OK -- All PRAUTOBLOGGER_* constants are production-defined or defined()-guarded.\n";
+exit( 0 );

templates/admin/board-page.php

@@ -98,7 +98,16 @@ function prab_render_board_card( array $card, string $column_key ): void {
 	<h1 class="prab-board-heading">
 		<?php esc_html_e( 'PRAutoBlogger', 'prautoblogger' ); ?>
 		<span class="prab-board-heading-sub"><?php esc_html_e( 'Article Board', 'prautoblogger' ); ?></span>
+		<?php if ( current_user_can( 'manage_options' ) ) : ?>
+		<button type="button"
+			id="prab-board-generate-now"
+			class="prab-board-generate-btn button button-primary"
+			aria-label="<?php esc_attr_e( 'Generate a new article now', 'prautoblogger' ); ?>">
+			<?php esc_html_e( 'New Article', 'prautoblogger' ); ?>
+		</button>
+		<?php endif; ?>
 	</h1>
+	<div id="prab-board-gen-status" class="prab-board-gen-status" aria-live="polite" style="display:none;"></div>
 
 	<div id="prab-board" class="prab-board" aria-live="polite" aria-label="<?php esc_attr_e( 'Article generation board', 'prautoblogger' ); ?>">
 

templates/admin/dossier-edit-panel.php

@@ -0,0 +1,109 @@
+<?php
+/**
+ * Partial: per-stage edit + replay panel (M3, v0.20.0).
+ *
+ * Rendered only for editable stages (writer chat stages with a
+ * persisted input). Included by dossier-stage-section.php; inherits its
+ * scope: $stage_name, $s_role, $section_id, $rerun (panel data),
+ * $dossier (spend/eligibility/post_id).
+ *
+ * UX contract (CPO guardrails): the copy states explicitly that saving
+ * forks a NEW version (original preserved), that re-running marks
+ * downstream stages stale, that execution is QUEUED (never implied
+ * synchronous), and what the run has already spent against its ceiling.
+ *
+ * Security: message contents via esc_textarea(); all attributes
+ * esc_attr(); spend numbers via number_format + esc_html.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$panel_prefill = is_array( $rerun['prefill'] ?? null ) ? $rerun['prefill'] : array(
+	'model'    => '',
+	'messages' => array(),
+);
+$panel_fork    = is_array( $rerun['fork'] ?? null ) ? $rerun['fork'] : null;
+$panel_spend   = is_array( $dossier['spend'] ?? null ) ? $dossier['spend'] : array(
+	'settled'  => 0.0,
+	'reserved' => 0.0,
+	'ceiling'  => 0.0,
+	'warn'     => false,
+);
+$held_usd      = (float) $panel_spend['settled'] + (float) $panel_spend['reserved'];
+?>
+<div class="prab-edit-panel" id="<?php echo $section_id; // Already escaped. ?>-edit" hidden
+	 data-stage="<?php echo esc_attr( $stage_name ); ?>"
+	 data-agent-role="<?php echo esc_attr( $s_role ); ?>">
+
+	<p class="prab-edit-copy">
+		<?php esc_html_e( 'You are editing a copy of this stage\'s input. Saving creates a new version — the original is preserved unchanged. Re-running this stage executes your latest saved version as a queued background job and marks all downstream stages stale; nothing downstream re-runs until you trigger it.', 'prautoblogger' ); ?>
+	</p>
+
+	<p class="prab-edit-spend<?php echo ! empty( $panel_spend['warn'] ) ? ' prab-edit-spend--warn' : ''; ?>">
+		<?php if ( (float) $panel_spend['ceiling'] > 0 ) : ?>
+			<?php
+			printf(
+				/* translators: 1: spent USD, 2: ceiling USD. */
+				esc_html__( 'Run spend so far: $%1$s of the $%2$s per-run ceiling. Re-runs are new spend on this run.', 'prautoblogger' ),
+				esc_html( number_format( $held_usd, 4 ) ),
+				esc_html( number_format( (float) $panel_spend['ceiling'], 2 ) )
+			);
+			if ( ! empty( $panel_spend['warn'] ) ) {
+				echo ' ';
+				esc_html_e( 'Warning: this run is approaching its ceiling — the re-run may halt. Raise the per-run ceiling setting first if needed.', 'prautoblogger' );
+			}
+			?>
+		<?php else : ?>
+			<?php esc_html_e( 'No per-run cost ceiling is configured for this run (monthly budget still applies).', 'prautoblogger' ); ?>
+		<?php endif; ?>
+	</p>
+
+	<p class="prab-edit-model">
+		<?php
+		printf(
+			/* translators: %s: model identifier. */
+			esc_html__( 'Model (fixed for replay): %s', 'prautoblogger' ),
+			esc_html( (string) $panel_prefill['model'] )
+		);
+		?>
+	</p>
+
+	<?php foreach ( $panel_prefill['messages'] as $i => $panel_message ) : ?>
+		<div class="prab-edit-message">
+			<label class="prab-edit-role" for="<?php echo $section_id; // Already escaped. ?>-msg-<?php echo (int) $i; ?>">
+				<?php echo esc_html( ucfirst( (string) ( $panel_message['role'] ?? '' ) ) ); ?>
+			</label>
+			<textarea class="prab-edit-textarea large-text"
+					id="<?php echo $section_id; // Already escaped. ?>-msg-<?php echo (int) $i; ?>"
+					rows="<?php echo 'system' === ( $panel_message['role'] ?? '' ) ? 4 : 10; ?>"
+					data-role="<?php echo esc_attr( (string) ( $panel_message['role'] ?? '' ) ); ?>"><?php echo esc_textarea( (string) ( $panel_message['content'] ?? '' ) ); ?></textarea>
+		</div>
+	<?php endforeach; ?>
+
+	<div class="prab-edit-actions">
+		<button type="button" class="button button-primary prab-edit-save">
+			<?php esc_html_e( 'Save as new version', 'prautoblogger' ); ?>
+		</button>
+		<button type="button" class="button prab-edit-rerun" <?php disabled( null === $panel_fork ); ?>>
+			<?php esc_html_e( 'Re-run this stage (queued)', 'prautoblogger' ); ?>
+		</button>
+		<span class="prab-edit-forkinfo" data-forkinfo>
+			<?php
+			if ( null !== $panel_fork ) {
+				printf(
+					/* translators: 1: version number, 2: author login, 3: datetime. */
+					esc_html__( 'Latest saved version: v%1$d by %2$s at %3$s', 'prautoblogger' ),
+					(int) $panel_fork['version'],
+					esc_html( (string) $panel_fork['author'] ),
+					esc_html( (string) $panel_fork['created_at'] )
+				);
+			} else {
+				esc_html_e( 'No edited version saved yet.', 'prautoblogger' );
+			}
+			?>
+		</span>
+		<span class="prab-edit-feedback" aria-live="polite" data-feedback></span>
+	</div>
+</div>

templates/admin/dossier-log-stage-section.php

@@ -0,0 +1,118 @@
+<?php
+/**
+ * Partial: log-only stage section (M3/F3, v0.20.0).
+ *
+ * Renders stages that exist ONLY in generation_log — image_a/image_b,
+ * image_prompt_rewrite, llm_research, opik_eval_judge, ... — which the
+ * M2 dossier silently dropped because the image pipeline (and the
+ * research providers) never write run_stages rows (QA M2 F3). These
+ * sections show the call record (model, tokens, cost, status, raw
+ * trace) from their REAL data source; image stages additionally render
+ * the post's actual pipeline attachments ($dossier['images']).
+ *
+ * Variables injected by dossier-page.php:
+ *   $stage_name (string) -- stage key
+ *   $log_rows (array)    -- generation_log rows for this stage
+ *   $dossier (array)     -- page view model (images)
+ *
+ * Security: identical escaping discipline to dossier-stage-section.php.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$lo_label    = PRAutoBlogger_Stage_Display_Map::label( $stage_name );
+$lo_is_image = in_array( $stage_name, array( 'image_a', 'image_b' ), true );
+$lo_images   = $lo_is_image && ! empty( $dossier['images'] ) ? (array) $dossier['images'] : array();
+$lo_cost     = 0.0;
+$lo_status   = '';
+$lo_model    = '—';
+foreach ( $log_rows as $lo_row ) {
+	$lo_cost  += (float) ( $lo_row['estimated_cost'] ?? 0 );
+	$lo_status = (string) ( $lo_row['response_status'] ?? '' );
+	if ( ! empty( $lo_row['model'] ) ) {
+		$lo_model = (string) $lo_row['model'];
+	}
+}
+$lo_section_id = 'prab-logstage-' . esc_attr( $stage_name );
+?>
+<div class="prab-dossier-section prab-dossier-section--stage prab-dossier-section--log-only"
+	 data-stage="<?php echo esc_attr( $stage_name ); ?>"
+	 id="<?php echo $lo_section_id; // Already escaped. ?>">
+
+	<div class="prab-stage-header">
+		<h2 class="prab-section-title"><?php echo esc_html( $lo_label ); ?></h2>
+		<div class="prab-stage-header-meta">
+			<?php if ( '' !== $lo_status ) : ?>
+				<span class="prab-trace-status prab-trace-status--<?php echo esc_attr( $lo_status ); ?>">
+					<?php echo esc_html( $lo_status ); ?>
+				</span>
+			<?php endif; ?>
+			<?php if ( $lo_cost > 0 ) : ?>
+				<span class="prab-stage-cost">$<?php echo esc_html( number_format( $lo_cost, 5 ) ); ?></span>
+			<?php endif; ?>
+			<span class="prab-stage-model"><?php echo esc_html( $lo_model ); ?></span>
+		</div>
+	</div>
+
+	<?php if ( ! empty( $lo_images ) ) : ?>
+		<div class="prab-image-grid">
+			<?php foreach ( $lo_images as $lo_image ) : ?>
+				<figure class="prab-image-card<?php echo ! empty( $lo_image['is_featured'] ) ? ' prab-image-card--chosen' : ''; ?>">
+					<img src="<?php echo esc_url( (string) $lo_image['url'] ); ?>" alt="<?php echo esc_attr( (string) $lo_image['role'] ); ?>" loading="lazy" />
+					<figcaption>
+						<?php echo esc_html( ucfirst( (string) $lo_image['role'] ) ); ?>
+						<?php if ( ! empty( $lo_image['is_featured'] ) ) : ?>
+							<span class="prab-chip prab-chip--chosen"><?php esc_html_e( 'Chosen (featured)', 'prautoblogger' ); ?></span>
+						<?php endif; ?>
+					</figcaption>
+				</figure>
+			<?php endforeach; ?>
+		</div>
+	<?php elseif ( $lo_is_image ) : ?>
+		<p class="prab-output-absent"><?php esc_html_e( 'No pipeline attachments recorded for this article (images attach on publish).', 'prautoblogger' ); ?></p>
+	<?php endif; ?>
+
+	<div class="prab-stage-trace">
+		<button type="button" class="prab-trace-toggle button-link"
+				aria-expanded="false"
+				aria-controls="<?php echo $lo_section_id; // Already escaped. ?>-trace">
+			<?php esc_html_e( 'Show raw trace', 'prautoblogger' ); ?>
+		</button>
+		<div id="<?php echo $lo_section_id; // Already escaped. ?>-trace" class="prab-trace-detail" hidden>
+			<?php foreach ( $log_rows as $log_row ) : ?>
+				<div class="prab-trace-entry">
+					<div class="prab-trace-meta">
+						<span><?php echo esc_html( (string) ( $log_row['model'] ?? '—' ) ); ?></span>
+						<span>
+						<?php
+						printf(
+							/* translators: 1: prompt tokens, 2: completion tokens. */
+							esc_html__( '%1$d prompt + %2$d completion tokens', 'prautoblogger' ),
+							(int) ( $log_row['prompt_tokens'] ?? 0 ),
+							(int) ( $log_row['completion_tokens'] ?? 0 )
+						);
+						?>
+						</span>
+						<span>$<?php echo esc_html( number_format( (float) ( $log_row['estimated_cost'] ?? 0 ), 6 ) ); ?></span>
+						<span class="prab-trace-status prab-trace-status--<?php echo esc_attr( (string) ( $log_row['response_status'] ?? '' ) ); ?>">
+							<?php echo esc_html( (string) ( $log_row['response_status'] ?? '' ) ); ?>
+						</span>
+					</div>
+					<?php if ( ! empty( $log_row['request_json'] ) ) : ?>
+						<details class="prab-trace-request">
+							<summary><?php esc_html_e( 'Request payload', 'prautoblogger' ); ?></summary>
+							<?php // SECURITY: esc_html() treats model output as untrusted HTML. ?>
+							<pre class="prab-trace-pre"><?php echo esc_html( (string) $log_row['request_json'] ); ?></pre>
+						</details>
+					<?php endif; ?>
+					<?php if ( ! empty( $log_row['error_message'] ) ) : ?>
+						<p class="prab-trace-error"><?php echo esc_html( (string) $log_row['error_message'] ); ?></p>
+					<?php endif; ?>
+				</div>
+			<?php endforeach; ?>
+		</div>
+	</div>
+
+</div><!-- .prab-dossier-section--log-only -->

templates/admin/dossier-page.php

@@ -101,6 +101,13 @@ $back_url = admin_url( 'admin.php?page=prautoblogger-board' );
 					<span class="prab-dossier-status prab-dossier-status--<?php echo esc_attr( $dossier['post_status'] ?? '' ); ?>">
 						<?php echo esc_html( ucfirst( $dossier['post_status'] ?? '' ) ); ?>
 					</span>
+					<?php // M3: run-summary audit badges -- visible, never tooltip-buried (CPO guardrail 2). ?>
+					<span class="prab-chip prab-chip--human prab-chip--header" data-header-chip="human" <?php echo ! empty( $dossier['human_modified_any'] ) ? '' : 'hidden'; ?>>
+						<?php esc_html_e( 'Human-modified', 'prautoblogger' ); ?>
+					</span>
+					<span class="prab-chip prab-chip--stale prab-chip--header" data-header-chip="stale" <?php echo ! empty( $dossier['stale_any'] ) ? '' : 'hidden'; ?>>
+						<?php esc_html_e( 'Has stale stages', 'prautoblogger' ); ?>
+					</span>
 				</div>
 			</div>
 			<?php if ( $post_id > 0 ) : ?>
@@ -142,6 +149,16 @@ $back_url = admin_url( 'admin.php?page=prautoblogger-board' );
 				require PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/dossier-stage-section.php';
 			}
 
+			// M3/F3: stages that exist only in generation_log (images,
+			// llm_research, ...) render from their real data source.
+			foreach ( ( $dossier['log_only_stages'] ?? array() ) as $stage_name ) {
+				$log_rows = $log_index[ $stage_name ] ?? array();
+				if ( empty( $log_rows ) ) {
+					continue;
+				}
+				require PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/dossier-log-stage-section.php';
+			}
+
 			if ( empty( $stages ) ) :
 				?>
 				<div class="prab-dossier-no-stages">
@@ -190,6 +207,8 @@ $back_url = admin_url( 'admin.php?page=prautoblogger-board' );
 					<?php endif; ?>
 				</div>
 
+				<?php require PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/dossier-sidebar-cards.php'; ?>
+
 				<div class="prab-sidebar-card prab-cost-receipt">
 					<h3 class="prab-sidebar-heading"><?php esc_html_e( 'Cost Receipt', 'prautoblogger' ); ?></h3>
 					<table class="prab-receipt-table">

templates/admin/dossier-sidebar-cards.php

@@ -0,0 +1,86 @@
+<?php
+/**
+ * Partial: M3 sidebar cards — run spend (guardrail 4 visibility) and
+ * the per-stage model/prompt-version consolidation (QA M2 F2).
+ *
+ * Included by dossier-page.php; inherits its scope: $dossier, $run,
+ * $log_index, $stages.
+ *
+ * Security: all db-sourced values esc_html(); numbers via number_format.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$sc_spend = is_array( $dossier['spend'] ?? null ) ? $dossier['spend'] : array(
+	'settled'  => 0.0,
+	'reserved' => 0.0,
+	'ceiling'  => 0.0,
+	'warn'     => false,
+);
+$sc_held  = (float) $sc_spend['settled'] + (float) $sc_spend['reserved'];
+?>
+<div class="prab-sidebar-card prab-run-spend<?php echo ! empty( $sc_spend['warn'] ) ? ' prab-run-spend--warn' : ''; ?>">
+	<h3 class="prab-sidebar-heading"><?php esc_html_e( 'Run Spend', 'prautoblogger' ); ?></h3>
+	<dl class="prab-sidebar-dl">
+		<dt><?php esc_html_e( 'Settled', 'prautoblogger' ); ?></dt>
+		<dd>$<?php echo esc_html( number_format( (float) $sc_spend['settled'], 4 ) ); ?></dd>
+		<?php if ( (float) $sc_spend['reserved'] > 0 ) : ?>
+			<dt><?php esc_html_e( 'Reserved', 'prautoblogger' ); ?></dt>
+			<dd>$<?php echo esc_html( number_format( (float) $sc_spend['reserved'], 4 ) ); ?></dd>
+		<?php endif; ?>
+		<dt><?php esc_html_e( 'Ceiling', 'prautoblogger' ); ?></dt>
+		<dd>
+			<?php if ( (float) $sc_spend['ceiling'] > 0 ) : ?>
+				$<?php echo esc_html( number_format( (float) $sc_spend['ceiling'], 2 ) ); ?>
+			<?php else : ?>
+				<?php esc_html_e( 'none configured', 'prautoblogger' ); ?>
+			<?php endif; ?>
+		</dd>
+	</dl>
+	<?php if ( ! empty( $sc_spend['warn'] ) ) : ?>
+		<p class="prab-spend-warning">
+			<?php
+			printf(
+				/* translators: 1: spent USD, 2: ceiling USD. */
+				esc_html__( 'This run has committed $%1$s of its $%2$s ceiling — further re-runs may halt.', 'prautoblogger' ),
+				esc_html( number_format( $sc_held, 4 ) ),
+				esc_html( number_format( (float) $sc_spend['ceiling'], 2 ) )
+			);
+			?>
+		</p>
+	<?php endif; ?>
+</div>
+
+<div class="prab-sidebar-card prab-models-card">
+	<h3 class="prab-sidebar-heading"><?php esc_html_e( 'Models & Prompts', 'prautoblogger' ); ?></h3>
+	<table class="prab-models-table">
+		<tbody>
+			<?php foreach ( $log_index as $sc_stage => $sc_rows ) : ?>
+				<?php
+				$sc_first = $sc_rows[0] ?? array();
+				$sc_model = ! empty( $sc_first['model'] ) ? (string) $sc_first['model'] : '—';
+				$sc_pv    = ! empty( $sc_first['prompt_version'] ) ? (string) $sc_first['prompt_version'] : '—';
+				$sc_role  = ! empty( $sc_first['agent_role'] ) ? (string) $sc_first['agent_role'] : '—';
+				?>
+				<tr>
+					<th scope="row"><?php echo esc_html( PRAutoBlogger_Stage_Display_Map::label( (string) $sc_stage ) ); ?></th>
+					<td>
+						<span class="prab-models-model"><?php echo esc_html( $sc_model ); ?></span>
+						<span class="prab-models-meta">
+							<?php
+							printf(
+								/* translators: 1: prompt version, 2: agent role. */
+								esc_html__( 'pv %1$s · %2$s', 'prautoblogger' ),
+								esc_html( $sc_pv ),
+								esc_html( $sc_role )
+							);
+							?>
+						</span>
+					</td>
+				</tr>
+			<?php endforeach; ?>
+		</tbody>
+	</table>
+</div>

templates/admin/dossier-stage-section.php

@@ -3,9 +3,10 @@
  * Partial: single stage section for the Article Dossier.
  *
  * Variables injected by dossier-page.php:
- *   $stage_row (array)  -- run_stages row incl. display_output
+ *   $stage_row (array)  -- run_stages row incl. display_output + ['rerun'] panel data (M3)
  *   $stage_name (string) -- stage key
  *   $log_rows (array)   -- generation_log rows for this stage
+ *   $dossier (array)    -- page view model (spend/eligibility/post_id)
  *
  * Security: all model output escaped via esc_html() or wp_kses_post().
  * request_json escaped via esc_html() -- treat as untrusted HTML.
@@ -30,9 +31,14 @@ $s_model       = ( null !== $first_log && ! empty( $first_log['model'] ) ) ? $fi
 $s_pv          = ( null !== $first_log && ! empty( $first_log['prompt_version'] ) ) ? $first_log['prompt_version'] : '—';
 $has_raw_trace = ! empty( $log_rows );
 $section_id    = 'prab-stage-' . esc_attr( $stage_name ) . '-' . esc_attr( $s_role );
+$rerun         = is_array( $stage_row['rerun'] ?? null ) ? $stage_row['rerun'] : array();
+$is_stale      = ! empty( $rerun['stale'] );
+$is_human      = ! empty( $rerun['human_modified'] );
+$attempts      = (int) ( $rerun['attempt'] ?? 1 );
 ?>
-<div class="prab-dossier-section prab-dossier-section--stage prab-stage-status--<?php echo esc_attr( $s_status ); ?>"
+<div class="prab-dossier-section prab-dossier-section--stage prab-stage-status--<?php echo esc_attr( $s_status ); ?><?php echo $is_stale ? ' prab-stage--stale' : ''; ?>"
 	 data-stage="<?php echo esc_attr( $stage_name ); ?>"
+	 data-agent-role="<?php echo esc_attr( $s_role ); ?>"
 	 id="<?php echo $section_id; // Already escaped. ?>">
 
 	<div class="prab-stage-header">
@@ -46,6 +52,24 @@ $section_id    = 'prab-stage-' . esc_attr( $stage_name ) . '-' . esc_attr( $s_ro
 			<span class="prab-stage-status-pill prab-stage-status-pill--<?php echo esc_attr( $s_status ); ?>">
 				<?php echo esc_html( ucfirst( $s_status ) ); ?>
 			</span>
+			<?php // M3 audit chips -- visible, never tooltip-buried (CPO guardrails 2+3). ?>
+			<span class="prab-chip prab-chip--stale" data-chip="stale" <?php echo $is_stale ? '' : 'hidden'; ?>>
+				<?php esc_html_e( 'Stale — upstream changed', 'prautoblogger' ); ?>
+			</span>
+			<span class="prab-chip prab-chip--human" data-chip="human" <?php echo $is_human ? '' : 'hidden'; ?>>
+				<?php esc_html_e( 'Human-edited input', 'prautoblogger' ); ?>
+			</span>
+			<?php if ( $attempts > 1 ) : ?>
+				<span class="prab-chip prab-chip--attempt">
+					<?php
+					printf(
+						/* translators: %d: attempt count. */
+						esc_html__( 'Attempt %d', 'prautoblogger' ),
+						(int) $attempts
+					);
+					?>
+				</span>
+			<?php endif; ?>
 			<?php if ( $s_cost > 0 ) : ?>
 				<span class="prab-stage-cost">$<?php echo esc_html( number_format( $s_cost, 5 ) ); ?></span>
 			<?php endif; ?>
@@ -123,4 +147,27 @@ $section_id    = 'prab-stage-' . esc_attr( $stage_name ) . '-' . esc_attr( $s_ro
 		</div>
 	<?php endif; ?>
 
+	<?php // ── M3: edit + re-run affordances (chained-cron; nothing is synchronous) ── ?>
+	<div class="prab-stage-rerun-footer">
+		<?php if ( ! empty( $rerun['editable'] ) ) : ?>
+			<button type="button" class="button prab-edit-toggle"
+					aria-expanded="false" aria-controls="<?php echo $section_id; // Already escaped. ?>-edit">
+				<?php esc_html_e( 'Edit input', 'prautoblogger' ); ?>
+			</button>
+		<?php elseif ( ! empty( $rerun['edit_reason'] ) ) : ?>
+			<span class="prab-edit-unavailable"><?php echo esc_html( (string) $rerun['edit_reason'] ); ?></span>
+		<?php endif; ?>
+		<?php if ( ! empty( $rerun['rerun_from'] ) ) : ?>
+			<button type="button" class="button prab-rerun-from<?php echo $is_stale ? ' prab-rerun-from--stale' : ''; ?>"
+					data-stage="<?php echo esc_attr( $stage_name ); ?>">
+				<?php esc_html_e( 'Re-run from here', 'prautoblogger' ); ?>
+			</button>
+		<?php endif; ?>
+	</div>
+	<?php
+	if ( ! empty( $rerun['editable'] ) ) {
+		require PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/dossier-edit-panel.php';
+	}
+	?>
+
 </div><!-- .prab-dossier-section--stage -->

templates/admin/ideas-browser.php

@@ -72,10 +72,11 @@ $base_url = admin_url( 'admin.php?page=prautoblogger-ideas' );
 			<tbody>
 				<?php foreach ( $rows as $row ) : ?>
 					<?php
-					$meta       = json_decode( $row['metadata_json'] ?? '{}', true ) ?: [];
+					$decoded    = json_decode( $row['metadata_json'] ?? '{}', true );
+					$meta       = is_array( $decoded ) ? $decoded : array();
 					$suggested  = $meta['suggested_title'] ?? '';
-					$key_points = $meta['key_points'] ?? [];
-					$keywords   = $meta['target_keywords'] ?? [];
+					$key_points = $meta['key_points'] ?? array();
+					$keywords   = $meta['target_keywords'] ?? array();
 					$score_pct  = round( (float) $row['relevance_score'] * 100 );
 					$type_label = ucfirst( $row['analysis_type'] ?? 'unknown' );
 					$type_class = 'prab-type-' . sanitize_html_class( $row['analysis_type'] );
@@ -164,14 +165,18 @@ $base_url = admin_url( 'admin.php?page=prautoblogger-ideas' );
 		<?php if ( $total_pages > 1 ) : ?>
 			<div class="prautoblogger-pagination" style="margin-top: 12px;">
 				<?php
-				echo wp_kses_post( paginate_links( [
-					'base'      => add_query_arg( 'paged', '%#%' ),
-					'format'    => '',
-					'current'   => $paged,
-					'total'     => $total_pages,
-					'prev_text' => '&laquo;',
-					'next_text' => '&raquo;',
-				] ) );
+				echo wp_kses_post(
+					paginate_links(
+						array(
+							'base'      => add_query_arg( 'paged', '%#%' ),
+							'format'    => '',
+							'current'   => $paged,
+							'total'     => $total_pages,
+							'prev_text' => '&laquo;',
+							'next_text' => '&raquo;',
+						)
+					)
+				);
 				?>
 			</div>
 		<?php endif; ?>

templates/admin/log-viewer.php

@@ -18,13 +18,13 @@ if ( ! defined( 'ABSPATH' ) ) {
 }
 
 $base_url    = admin_url( 'admin.php?page=prautoblogger-logs' );
-$level_counts = [
+$level_counts = array(
 	'all'     => __( 'All', 'prautoblogger' ),
 	'error'   => __( 'Errors', 'prautoblogger' ),
 	'warning' => __( 'Warnings', 'prautoblogger' ),
 	'info'    => __( 'Info', 'prautoblogger' ),
 	'debug'   => __( 'Debug', 'prautoblogger' ),
-];
+);
 ?>
 <div class="wrap ab-wrap">
 	<div class="ab-header">
@@ -46,7 +46,20 @@ $level_counts = [
 	<div class="ab-log-filters">
 		<div class="ab-log-level-tabs">
 			<?php foreach ( $level_counts as $lv => $lv_label ) : ?>
-				<a href="<?php echo esc_url( add_query_arg( [ 'level' => $lv, 's' => $search, 'paged' => 1 ], $base_url ) ); ?>"
+				<a href="
+				<?php
+				echo esc_url(
+					add_query_arg(
+						array(
+							'level' => $lv,
+							's' => $search,
+							'paged' => 1,
+						),
+						$base_url
+					)
+				);
+				?>
+							"
 				   class="ab-log-level-tab <?php echo $level === $lv ? 'ab-log-level-active' : ''; ?>">
 					<?php echo esc_html( $lv_label ); ?>
 				</a>
@@ -119,14 +132,18 @@ $level_counts = [
 		<?php if ( $total_pages > 1 ) : ?>
 			<div class="ab-log-pagination">
 				<?php
-				echo wp_kses_post( paginate_links( [
-					'base'      => add_query_arg( 'paged', '%#%' ),
-					'format'    => '',
-					'current'   => $paged,
-					'total'     => $total_pages,
-					'prev_text' => '&laquo;',
-					'next_text' => '&raquo;',
-				] ) );
+				echo wp_kses_post(
+					paginate_links(
+						array(
+							'base'      => add_query_arg( 'paged', '%#%' ),
+							'format'    => '',
+							'current'   => $paged,
+							'total'     => $total_pages,
+							'prev_text' => '&laquo;',
+							'next_text' => '&raquo;',
+						)
+					)
+				);
 				?>
 			</div>
 		<?php endif; ?>

templates/admin/metabox-generation-info.php

@@ -11,7 +11,7 @@ if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
-$meta = [
+$meta = array(
 	'topic'          => get_post_meta( $post->ID, '_prautoblogger_topic', true ),
 	'type'           => get_post_meta( $post->ID, '_prautoblogger_article_type', true ),
 	'model'          => get_post_meta( $post->ID, '_prautoblogger_model_used', true ),
@@ -22,24 +22,24 @@ $meta = [
 	'seo_score'      => get_post_meta( $post->ID, '_prautoblogger_seo_score', true ),
 	'generated_at'   => get_post_meta( $post->ID, '_prautoblogger_generated_at', true ),
 	'keywords'       => get_post_meta( $post->ID, '_prautoblogger_target_keywords', true ),
-];
+);
 ?>
 <div class="prautoblogger-metabox">
 	<p>
 		<strong><?php esc_html_e( 'Generated:', 'prautoblogger' ); ?></strong>
-		<?php echo esc_html( $meta['generated_at'] ?: __( 'Unknown', 'prautoblogger' ) ); ?>
+		<?php echo esc_html( $meta['generated_at'] ? $meta['generated_at'] : __( 'Unknown', 'prautoblogger' ) ); ?>
 	</p>
 	<p>
 		<strong><?php esc_html_e( 'Topic:', 'prautoblogger' ); ?></strong>
-		<?php echo esc_html( $meta['topic'] ?: '—' ); ?>
+		<?php echo esc_html( $meta['topic'] ? $meta['topic'] : '—' ); ?>
 	</p>
 	<p>
 		<strong><?php esc_html_e( 'Type:', 'prautoblogger' ); ?></strong>
-		<?php echo esc_html( ucfirst( $meta['type'] ?: 'article' ) ); ?>
+		<?php echo esc_html( ucfirst( $meta['type'] ? $meta['type'] : 'article' ) ); ?>
 	</p>
 	<p>
 		<strong><?php esc_html_e( 'Model:', 'prautoblogger' ); ?></strong>
-		<?php echo esc_html( $meta['model'] ?: '—' ); ?>
+		<?php echo esc_html( $meta['model'] ? $meta['model'] : '—' ); ?>
 	</p>
 	<p>
 		<strong><?php esc_html_e( 'Pipeline:', 'prautoblogger' ); ?></strong>
@@ -47,8 +47,8 @@ $meta = [
 	</p>
 	<p>
 		<strong><?php esc_html_e( 'Editor Verdict:', 'prautoblogger' ); ?></strong>
-		<span class="prautoblogger-verdict-<?php echo esc_attr( $meta['verdict'] ?: 'unknown' ); ?>">
-			<?php echo esc_html( ucfirst( $meta['verdict'] ?: __( 'Unknown', 'prautoblogger' ) ) ); ?>
+		<span class="prautoblogger-verdict-<?php echo esc_attr( $meta['verdict'] ? $meta['verdict'] : 'unknown' ); ?>">
+			<?php echo esc_html( ucfirst( $meta['verdict'] ? $meta['verdict'] : __( 'Unknown', 'prautoblogger' ) ) ); ?>
 		</span>
 	</p>
 	<?php if ( $meta['quality_score'] ) : ?>
@@ -69,7 +69,7 @@ $meta = [
 	<?php if ( $meta['keywords'] ) : ?>
 		<p>
 			<strong><?php esc_html_e( 'Keywords:', 'prautoblogger' ); ?></strong>
-			<?php echo esc_html( implode( ', ', json_decode( $meta['keywords'], true ) ?: [] ) ); ?>
+			<?php echo esc_html( implode( ', ', ( json_decode( $meta['keywords'], true ) ? json_decode( $meta['keywords'], true ) : array() ) ) ); ?>
 		</p>
 	<?php endif; ?>
 </div>

templates/admin/review-queue.php

@@ -103,6 +103,18 @@ $bulk_type = isset( $_GET['prautoblogger_bulk_type'] ) ? sanitize_text_field( wp
 				</span>
 			</div>
 
+			<?php
+			// v0.20.0: stale-stage warning chips (one batched query; CPO
+			// product AC -- the stale flag is visible at publish time).
+			$rq_post_runs = array();
+			foreach ( $query->posts as $rq_post ) {
+				$rq_run_id = (string) get_post_meta( $rq_post->ID, '_prautoblogger_run_id', true );
+				if ( '' !== $rq_run_id ) {
+					$rq_post_runs[ $rq_post->ID ] = $rq_run_id;
+				}
+			}
+			$rq_stale_runs = array_flip( PRAutoBlogger_Run_Stage_State::runs_with_stale_stages( array_values( $rq_post_runs ) ) );
+			?>
 			<table class="widefat striped prautoblogger-queue-table">
 				<thead>
 					<tr>
@@ -129,7 +141,7 @@ $bulk_type = isset( $_GET['prautoblogger_bulk_type'] ) ? sanitize_text_field( wp
 						$quality_score = get_post_meta( $post_id, '_prautoblogger_quality_score', true );
 						$generated_at  = get_post_meta( $post_id, '_prautoblogger_generated_at', true );
 						$editor_notes  = get_post_meta( $post_id, '_prautoblogger_editor_notes', true );
-						$verdict_class = 'prautoblogger-verdict-' . sanitize_html_class( $verdict ?: 'pending' );
+						$verdict_class = 'prautoblogger-verdict-' . sanitize_html_class( $verdict ? $verdict : 'pending' );
 						?>
 						<tr data-post-id="<?php echo esc_attr( (string) $post_id ); ?>">
 							<td class="check-column">
@@ -137,13 +149,18 @@ $bulk_type = isset( $_GET['prautoblogger_bulk_type'] ) ? sanitize_text_field( wp
 							</td>
 							<td>
 								<strong><?php the_title(); ?></strong>
+								<?php if ( isset( $rq_post_runs[ $post_id ], $rq_stale_runs[ $rq_post_runs[ $post_id ] ] ) ) : ?>
+									<a class="prab-review-stale-chip" href="<?php echo esc_url( PRAutoBlogger_Dossier_Page::url_for_post( (int) $post_id ) ); ?>">
+										<?php esc_html_e( 'Stale stages -- review dossier', 'prautoblogger' ); ?>
+									</a>
+								<?php endif; ?>
 								<?php if ( $editor_notes ) : ?>
 									<div class="prautoblogger-editor-notes"><?php echo esc_html( $editor_notes ); ?></div>
 								<?php endif; ?>
 							</td>
-							<td><?php echo esc_html( $topic ?: '—' ); ?></td>
-							<td><?php echo esc_html( ucfirst( $article_type ?: 'article' ) ); ?></td>
-							<td><span class="<?php echo esc_attr( $verdict_class ); ?>"><?php echo esc_html( ucfirst( $verdict ?: 'pending' ) ); ?></span></td>
+							<td><?php echo esc_html( $topic ? $topic : '—' ); ?></td>
+							<td><?php echo esc_html( ucfirst( $article_type ? $article_type : 'article' ) ); ?></td>
+							<td><span class="<?php echo esc_attr( $verdict_class ); ?>"><?php echo esc_html( ucfirst( $verdict ? $verdict : 'pending' ) ); ?></span></td>
 							<td><?php echo '' !== $quality_score ? esc_html( $quality_score . '/10' ) : '—'; ?></td>
 							<td><?php echo $generated_at ? esc_html( wp_date( 'M j, g:i A', strtotime( $generated_at ) ) ) : '—'; ?></td>
 							<td class="prautoblogger-queue-actions">

tests/bootstrap.php

@@ -209,6 +209,11 @@ if ( ! class_exists( 'WP_Post' ) ) {
 // Plugin URL and version constants used by admin enqueue methods.
 // Defined here so all tests that load admin classes can stub WP enqueue calls
 // without hitting "Undefined constant" errors.
+if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT' ) ) {
+    define( 'PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT', 20 );
+}
+
+// Plugin URL and version constants used by admin enqueue methods.
 if ( ! defined( 'PRAUTOBLOGGER_PLUGIN_URL' ) ) {
     define( 'PRAUTOBLOGGER_PLUGIN_URL', 'https://test.example.com/wp-content/plugins/prautoblogger/' );
 }

tests/unit/Admin/BoardGenLogQueryTest.php

@@ -0,0 +1,239 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Board_Gen_Log_Query — binding order and result shape.
+ *
+ * The key regression: both get_generating_cards() and get_failed_cards() had
+ * (a) a missing comma between bound args and (b) reversed argument order — the
+ * integer limit was passed first, the datetime string second, which bound
+ * created_at >= <int> and LIMIT <datetime>. These tests assert the correct
+ * binding order (string first, int second) so any future regression is caught
+ * before CI.
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class BoardGenLogQueryTest extends BaseTestCase {
+
+	/**
+	 * Captured prepare() calls: each entry is ['sql' => string, 'args' => array].
+	 *
+	 * @var array<int, array{sql: string, args: array}>
+	 */
+	private array $prepare_calls = array();
+
+	/**
+	 * Build a fresh mock $wpdb whose get_results() always returns $rows.
+	 *
+	 * @param array $rows Rows to return from get_results().
+	 * @return \PHPUnit\Framework\MockObject\MockObject
+	 */
+	private function make_wpdb( array $rows = array() ): object {
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->prefix    = 'wp_';
+		$GLOBALS['wpdb'] = $wpdb;
+		$self            = $this;
+
+		$wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( string $sql, ...$args ) use ( $self ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				$self->prepare_calls[] = array( 'sql' => $sql, 'args' => $args );
+				return 'PREPARED_SQL';
+			}
+		);
+
+		$wpdb->method( 'get_results' )->willReturn( $rows );
+		return $wpdb;
+	}
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->prepare_calls = array();
+
+		Functions\when( 'get_transient' )->justReturn( false );
+		Functions\when( 'admin_url' )->alias(
+			function ( string $path = '' ) {
+				return 'https://test.example.com/wp-admin/' . ltrim( $path, '/' );
+			}
+		);
+		Functions\when( 'get_option' )->alias(
+			function ( string $name, $default = false ) {
+				if ( 'prautoblogger_board_column_limit' === $name ) {
+					return 10;
+				}
+				return $default;
+			}
+		);
+	}
+
+	protected function tearDown(): void {
+		$this->prepare_calls = array();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	// ── get_generating_cards() binding order ────────────────────────────────
+
+	/**
+	 * get_generating_cards() must pass $since (string) as the FIRST bound arg
+	 * and the integer limit as the SECOND — matching placeholder order %s … %d.
+	 *
+	 * This would have caught the reversed-order bug (limit int passed first,
+	 * datetime string second) that silently bound created_at >= <int>.
+	 */
+	public function test_generating_cards_prepare_arg_order(): void {
+		$this->make_wpdb();
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$query->get_generating_cards();
+
+		// Find the prepare() call containing LIMIT %d (the gen-log secondary query).
+		$gen_call = null;
+		foreach ( $this->prepare_calls as $call ) {
+			if (
+				str_contains( $call['sql'], 'LIMIT %d' ) &&
+				str_contains( $call['sql'], 'post_id IS NULL' ) &&
+				! str_contains( $call['sql'], "response_status = 'error'" )
+			) {
+				$gen_call = $call;
+				break;
+			}
+		}
+
+		$this->assertNotNull( $gen_call, 'get_generating_cards() must call $wpdb->prepare() with LIMIT %d' );
+		$this->assertCount( 2, $gen_call['args'], 'prepare() must receive exactly 2 bound args' );
+
+		// First arg must be a string (the $since datetime).
+		$this->assertIsString( $gen_call['args'][0], 'First arg to prepare() must be the $since string (for %s)' );
+		// Second arg must be an integer (the column limit).
+		$this->assertIsInt( $gen_call['args'][1], 'Second arg to prepare() must be the integer limit (for %d)' );
+	}
+
+	/**
+	 * get_generating_cards() must return an empty array (not error) when DB returns nothing.
+	 */
+	public function test_generating_cards_returns_empty_array_on_no_results(): void {
+		$this->make_wpdb();
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$cards = $query->get_generating_cards();
+		$this->assertIsArray( $cards );
+	}
+
+	/**
+	 * When the status transient signals a running job, get_generating_cards()
+	 * returns a card from the transient (no DB call needed for that card).
+	 */
+	public function test_generating_cards_returns_transient_card_when_running(): void {
+		$this->make_wpdb();
+
+		Functions\when( 'get_transient' )->alias(
+			function ( $key ) {
+				if ( 'prautoblogger_generation_status' === $key ) {
+					return array(
+						'status'  => 'running',
+						'stage'   => 'Drafting…',
+						'started' => time() - 30,
+					);
+				}
+				return false;
+			}
+		);
+
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$cards = $query->get_generating_cards();
+
+		$this->assertNotEmpty( $cards, 'Transient running state must produce at least one card' );
+		$this->assertSame( '', $cards[0]['run_id'], 'Transient card has empty run_id' );
+		$this->assertSame( 'logs', $cards[0]['click_action'] );
+	}
+
+	// ── get_failed_cards() binding order ────────────────────────────────────
+
+	/**
+	 * get_failed_cards() must pass $since (string) as the FIRST bound arg
+	 * and the integer limit as the SECOND — matching placeholder order %s … %d.
+	 */
+	public function test_failed_cards_prepare_arg_order(): void {
+		$this->make_wpdb();
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$query->get_failed_cards();
+
+		// Find the prepare() call for the failed query.
+		$fail_call = null;
+		foreach ( $this->prepare_calls as $call ) {
+			if ( str_contains( $call['sql'], "response_status = 'error'" ) ) {
+				$fail_call = $call;
+				break;
+			}
+		}
+
+		$this->assertNotNull( $fail_call, 'get_failed_cards() must call $wpdb->prepare() with response_status filter' );
+		$this->assertCount( 2, $fail_call['args'], 'prepare() must receive exactly 2 bound args' );
+
+		// First arg must be a string (the $since datetime).
+		$this->assertIsString( $fail_call['args'][0], 'First arg to prepare() must be the $since string (for %s)' );
+		// Second arg must be an integer (the column limit).
+		$this->assertIsInt( $fail_call['args'][1], 'Second arg to prepare() must be the integer limit (for %d)' );
+	}
+
+	/**
+	 * get_failed_cards() returns the correct card shape from a seeded result row.
+	 */
+	public function test_failed_cards_returns_correct_shape(): void {
+		// Use a fresh wpdb with non-empty get_results rows.
+		$this->make_wpdb(
+			array(
+				array(
+					'run_id'     => 'fail-run-abc',
+					'started_at' => gmdate( 'Y-m-d H:i:s', time() - 3600 ),
+					'last_error' => 'Rate limit exceeded',
+					'last_stage' => 'draft',
+					'call_count' => '3',
+				),
+			)
+		);
+
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$cards = $query->get_failed_cards();
+
+		$this->assertCount( 1, $cards );
+		$this->assertSame( 'fail-run-abc', $cards[0]['run_id'] );
+		$this->assertStringContainsString( 'Rate limit', $cards[0]['error_message'] );
+		$this->assertSame( 'logs', $cards[0]['click_action'] );
+		$this->assertArrayHasKey( 'started_at', $cards[0] );
+	}
+
+	/**
+	 * Column-limit option is honoured: limit 7 → second arg to prepare() is 7.
+	 */
+	public function test_column_limit_option_is_respected(): void {
+		Functions\when( 'get_option' )->alias(
+			function ( string $name, $default = false ) {
+				if ( 'prautoblogger_board_column_limit' === $name ) {
+					return 7;
+				}
+				return $default;
+			}
+		);
+
+		$this->make_wpdb();
+		$query = new \PRAutoBlogger_Board_Gen_Log_Query();
+		$query->get_generating_cards();
+
+		$gen_call = null;
+		foreach ( $this->prepare_calls as $call ) {
+			if ( str_contains( $call['sql'], 'LIMIT %d' ) && ! str_contains( $call['sql'], "response_status = 'error'" ) ) {
+				$gen_call = $call;
+				break;
+			}
+		}
+
+		$this->assertNotNull( $gen_call );
+		$this->assertSame( 7, $gen_call['args'][1], 'Limit arg must match the option value' );
+	}
+}

tests/unit/Admin/BoardHumanModifiedFlagTest.php

@@ -0,0 +1,129 @@
+<?php
+/**
+ * Tests for the v0.20.0 board-card human_modified flag (CPO product AC:
+ * human-modified runs are visually distinct at the run-list level).
+ *
+ * Locks: ONE batched query flags all cards (no N+1), unflagged runs and
+ * missing-table sites degrade to false.
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class BoardHumanModifiedFlagTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	/**
+	 * Number of get_col calls (N+1 guard).
+	 *
+	 * @var int
+	 */
+	private int $col_queries = 0;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->col_queries = 0;
+		$this->wpdb        = $this->create_mock_wpdb();
+		$GLOBALS['wpdb']   = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		Functions\when( 'get_post_meta' )->alias(
+			static function ( $post_id, $key ) {
+				if ( '_prautoblogger_run_id' === $key ) {
+					return 'run-' . $post_id;
+				}
+				if ( '_prautoblogger_total_cost' === $key ) {
+					return '0.05';
+				}
+				return '';
+			}
+		);
+		Functions\when( 'get_edit_post_link' )->justReturn( 'https://example.com/edit' );
+		Functions\when( 'admin_url' )->alias( static fn( $p = '' ) => 'https://example.com/wp-admin/' . $p );
+		Functions\when( 'get_option' )->alias(
+			function ( string $name, $default = false ) {
+				$map = array(
+					'prautoblogger_board_column_limit'         => PRAUTOBLOGGER_DEFAULT_BOARD_COLUMN_LIMIT,
+					'prautoblogger_board_published_window_days' => 7,
+				);
+				return $map[ $name ] ?? $default;
+			}
+		);
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\WP_Query::$_test_posts_queue = array();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Build a WP_Post for the queue. */
+	private function make_post( int $id ): \WP_Post {
+		$post                = new \WP_Post();
+		$post->ID            = $id;
+		$post->post_title    = 'Post ' . $id;
+		$post->post_date_gmt = '2026-06-12 00:00:00';
+		return $post;
+	}
+
+	/**
+	 * Cards whose runs carry human_modified rows get the flag; others
+	 * stay false; exactly ONE batched query runs for the whole column.
+	 */
+	public function test_cards_flagged_in_one_batched_query(): void {
+		\WP_Query::$_test_posts_queue[] = array( $this->make_post( 1 ), $this->make_post( 2 ), $this->make_post( 3 ) );
+
+		$this->wpdb->method( 'get_var' )->willReturn( 'wp_prautoblogger_run_stages' );
+		$this->wpdb->method( 'get_col' )->willReturnCallback(
+			function ( $sql ) {
+				++$this->col_queries;
+				$this->assertStringContainsString( 'human_modified = 1', (string) $sql );
+				return array( 'run-2' ); // Only post 2's run was edited.
+			}
+		);
+
+		$cards = ( new \PRAutoBlogger_Board_Data_Provider() )->get_in_review_cards();
+
+		$this->assertCount( 3, $cards );
+		$this->assertFalse( $cards[0]['human_modified'] );
+		$this->assertTrue( $cards[1]['human_modified'] );
+		$this->assertFalse( $cards[2]['human_modified'] );
+		$this->assertSame( 1, $this->col_queries, 'one batched query, never per-card' );
+	}
+
+	/**
+	 * Missing substrate table: flags default false, zero flag queries.
+	 */
+	public function test_missing_table_degrades_to_false(): void {
+		\WP_Query::$_test_posts_queue[] = array( $this->make_post( 1 ) );
+
+		$this->wpdb->method( 'get_var' )->willReturn( null );
+		$this->wpdb->method( 'get_col' )->willReturnCallback(
+			function () {
+				++$this->col_queries;
+				return array();
+			}
+		);
+
+		$cards = ( new \PRAutoBlogger_Board_Data_Provider() )->get_in_review_cards();
+
+		$this->assertFalse( $cards[0]['human_modified'] );
+		$this->assertSame( 0, $this->col_queries );
+	}
+}

tests/unit/Admin/DossierActionsRerunTest.php

@@ -0,0 +1,103 @@
+<?php
+/**
+ * Dossier_Actions: rerun + status endpoint tests (v0.20.0, M3).
+ *
+ * Locks the chained-cron contract (queue only — ZERO state mutations in
+ * the AJAX layer) and the read-only stage-status poll shape.
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use Brain\Monkey\Functions;
+
+class DossierActionsRerunTest extends DossierActionsTestCase {
+
+	/**
+	 * Chained-cron contract: rerun_stage only schedules — no run/stage
+	 * state is mutated by the AJAX layer, and the response says queued.
+	 */
+	public function test_rerun_stage_queues_without_any_state_mutation(): void {
+		$this->wire_eligible_context();
+		// A saved fork exists for the replay check.
+		$wpdb_get_row_fork = array(
+			'version'      => '1',
+			'request_json' => '{"model":"m","messages":[{"role":"user","content":"edited"}]}',
+		);
+		// Rebuild get_row: forks resolve, run row terminal.
+		$_POST = array(
+			'post_id'    => '99',
+			'stage'      => 'draft',
+			'agent_role' => 'writer',
+		);
+		// Replace the get_row wiring (fork now exists).
+		$wpdb          = $this->create_mock_wpdb();
+		$wpdb->options = 'wp_options';
+		$wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		$wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				if ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) {
+					return ( false !== strpos( (string) $sql, 'stage_inputs' ) ) ? 'wp_prautoblogger_stage_inputs' : 'wp_prautoblogger_runs';
+				}
+				return null; // Lock free.
+			}
+		);
+		$wpdb->method( 'get_row' )->willReturnCallback(
+			static function ( $sql ) use ( $wpdb_get_row_fork ) {
+				if ( false !== strpos( (string) $sql, 'stage_inputs' ) ) {
+					return $wpdb_get_row_fork;
+				}
+				return array(
+					'run_id' => 'run-1',
+					'status' => 'done',
+				);
+			}
+		);
+		$wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+		$GLOBALS['wpdb'] = $wpdb;
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+
+		$actions = new \PRAutoBlogger_Dossier_Actions();
+		$this->dispatch( array( $actions, 'on_rerun_stage' ) );
+
+		$this->assertTrue( $this->json['ok'] );
+		$this->assertTrue( $this->json['data']['queued'] );
+		$this->assertCount( 1, $this->scheduled );
+		$this->assertSame( \PRAutoBlogger_Rerun_Executor::REPLAY_ACTION, $this->scheduled[0]['hook'] );
+		$this->assertSame( array( 'run-1', 99, 'draft', 'writer', 'idea:abc123' ), array_slice( $this->scheduled[0]['args'], 0, 5 ) );
+		foreach ( $this->queries as $sql ) {
+			$this->assertStringNotContainsString( 'UPDATE', $sql, 'the AJAX layer must not mutate state' );
+		}
+	}
+
+	/**
+	 * stage_status: read-only poll returns run status + per-stage state
+	 * with stale/human_modified flags.
+	 */
+	public function test_stage_status_returns_stage_states(): void {
+		$this->wire_eligible_context();
+		$this->wpdb->method( 'get_results' )->willReturn( array() );
+		$_POST = array( 'post_id' => '99' );
+
+		$actions = new \PRAutoBlogger_Dossier_Actions();
+		$this->dispatch( array( $actions, 'on_stage_status' ) );
+
+		$this->assertTrue( $this->json['ok'] );
+		$this->assertArrayHasKey( 'run_status', $this->json['data'] );
+		$this->assertArrayHasKey( 'stages', $this->json['data'] );
+	}
+}

tests/unit/Admin/DossierActionsSaveInputTest.php

@@ -0,0 +1,87 @@
+<?php
+/**
+ * Dossier_Actions: save_input endpoint tests (v0.20.0, M3).
+ *
+ * Locks: published-post rejection (guardrail 5 server-side), fork
+ * structure validation (count/roles locked, contents non-empty), and
+ * the merged-fork save (model/options from the base, never the client).
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use Brain\Monkey\Functions;
+
+class DossierActionsSaveInputTest extends DossierActionsTestCase {
+
+	/**
+	 * Frozen post: save_input rejects server-side with 400 and inserts
+	 * nothing (guardrail 5 is not just hidden UI).
+	 */
+	public function test_save_input_rejects_published_post(): void {
+		$this->wire_eligible_context( 'publish' );
+		$_POST = array(
+			'post_id'    => '99',
+			'stage'      => 'draft',
+			'agent_role' => 'writer',
+			'messages'   => '[]',
+		);
+
+		$actions = new \PRAutoBlogger_Dossier_Actions();
+		$this->dispatch( array( $actions, 'on_save_input' ) );
+
+		$this->assertFalse( $this->json['ok'] );
+		$this->assertSame( 400, $this->json['status'] );
+		$this->assertCount( 0, $this->inserted );
+	}
+
+	/**
+	 * Structure lock: changing a message ROLE (or count, or emptying a
+	 * content) is rejected — forks are always replayable chat bodies.
+	 */
+	public function test_save_input_rejects_structure_mismatch(): void {
+		$this->wire_eligible_context();
+		$_POST = array(
+			'post_id'    => '99',
+			'stage'      => 'draft',
+			'agent_role' => 'writer',
+			// Role flipped user->assistant vs the base body.
+			'messages'   => '[{"role":"system","content":"sys"},{"role":"assistant","content":"edited"}]',
+		);
+
+		$actions = new \PRAutoBlogger_Dossier_Actions();
+		$this->dispatch( array( $actions, 'on_save_input' ) );
+
+		$this->assertFalse( $this->json['ok'] );
+		$this->assertCount( 0, $this->inserted );
+	}
+
+	/**
+	 * Valid edit: fork v1 saved with the edited content merged into the
+	 * base body; model/options come from the base, not the client.
+	 */
+	public function test_save_input_saves_merged_fork(): void {
+		$this->wire_eligible_context();
+		$_POST = array(
+			'post_id'    => '99',
+			'stage'      => 'draft',
+			'agent_role' => 'writer',
+			'messages'   => '[{"role":"system","content":"sys"},{"role":"user","content":"EDITED PROMPT"}]',
+		);
+
+		$actions = new \PRAutoBlogger_Dossier_Actions();
+		$this->dispatch( array( $actions, 'on_save_input' ) );
+
+		$this->assertTrue( $this->json['ok'] );
+		$this->assertSame( 1, $this->json['data']['version'] );
+		$this->assertCount( 1, $this->inserted );
+		$row = $this->inserted[0];
+		$this->assertSame( 'human', $row['source'] );
+		$this->assertSame( 'rhys', $row['author'] );
+		$this->assertSame( 'idea:abc123', $row['item_key'] );
+		$body = json_decode( (string) $row['request_json'], true );
+		$this->assertSame( 'EDITED PROMPT', $body['messages'][1]['content'] );
+		$this->assertSame( 'm', $body['model'] ); // From the base, not the client.
+	}
+}

tests/unit/Admin/DossierActionsTestCase.php

@@ -0,0 +1,212 @@
+<?php
+/**
+ * Shared harness for the Dossier_Actions endpoint tests (v0.20.0, M3).
+ *
+ * Provides: mock wpdb with SQL-pattern wiring, JSON-response capture
+ * (wp_send_json_* throw a sentinel), cron-schedule capture, and the
+ * eligible-context fixture (draft post, terminal run, free lock).
+ * Split across two test classes for the 300-line file cap (the M2
+ * split-precedent applies to test files too).
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+abstract class DossierActionsTestCase extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	protected $wpdb;
+
+	/**
+	 * Captured JSON response (success/error + payload + status).
+	 *
+	 * @var array|null
+	 */
+	protected $json = null;
+
+	/**
+	 * SQL captured from $wpdb->query().
+	 *
+	 * @var string[]
+	 */
+	protected array $queries = array();
+
+	/**
+	 * Rows captured from $wpdb->insert().
+	 *
+	 * @var array<int, array>
+	 */
+	protected array $inserted = array();
+
+	/**
+	 * Cron events captured from wp_schedule_single_event().
+	 *
+	 * @var array<int, array>
+	 */
+	protected array $scheduled = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->json      = null;
+		$this->queries   = array();
+		$this->inserted  = array();
+		$this->scheduled = array();
+		$_POST           = array();
+
+		$this->wpdb          = $this->create_mock_wpdb();
+		$this->wpdb->options = 'wp_options';
+		$GLOBALS['wpdb']     = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+		$this->wpdb->method( 'insert' )->willReturnCallback(
+			function ( $table, $row ) {
+				$this->inserted[] = (array) $row;
+				return 1;
+			}
+		);
+
+		Functions\when( 'check_ajax_referer' )->justReturn( true );
+		Functions\when( 'current_user_can' )->justReturn( true );
+		Functions\when( 'absint' )->alias( static function ( $val ) { return abs( (int) $val ); } );
+		Functions\when( 'sanitize_key' )->alias( static function ( $val ) { return preg_replace( '/[^a-z0-9_\-]/', '', strtolower( (string) $val ) ); } );
+		Functions\when( 'wp_unslash' )->returnArg();
+		Functions\when( 'wp_schedule_single_event' )->alias(
+			function ( $ts, $hook, $args ) {
+				$this->scheduled[] = array(
+					'hook' => $hook,
+					'args' => $args,
+				);
+				return true;
+			}
+		);
+		Functions\when( 'spawn_cron' )->justReturn( true );
+		Functions\when( 'wp_remote_post' )->justReturn( array() );
+		Functions\when( 'site_url' )->justReturn( 'https://example.com' );
+		Functions\when( 'wp_send_json_success' )->alias(
+			function ( $data = null ) {
+				$this->json = array(
+					'ok'   => true,
+					'data' => $data,
+				);
+				throw new \RuntimeException( 'json_sent' );
+			}
+		);
+		Functions\when( 'wp_send_json_error' )->alias(
+			function ( $data = null, $status = 0 ) {
+				$this->json = array(
+					'ok'     => false,
+					'data'   => $data,
+					'status' => $status,
+				);
+				throw new \RuntimeException( 'json_sent' );
+			}
+		);
+		$user             = new \stdClass();
+		$user->user_login = 'rhys';
+		Functions\when( 'wp_get_current_user' )->justReturn( $user );
+
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		$_POST = array();
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Run an endpoint, swallowing the wp_send_json sentinel. */
+	protected function dispatch( callable $endpoint ): void {
+		try {
+			$endpoint();
+		} catch ( \RuntimeException $e ) {
+			if ( 'json_sent' !== $e->getMessage() ) {
+				throw $e;
+			}
+		}
+	}
+
+	/** Wire post meta + a draft post + a terminal run + free lock. */
+	protected function wire_eligible_context( string $post_status = 'draft', string $run_status = 'done' ): void {
+		Functions\when( 'get_post_meta' )->alias(
+			static function ( $post_id, $key ) {
+				if ( '_prautoblogger_run_id' === $key ) {
+					return 'run-1';
+				}
+				if ( '_prautoblogger_idea_hash' === $key ) {
+					return 'abc123';
+				}
+				return '';
+			}
+		);
+		$post              = new \WP_Post();
+		$post->ID          = 99;
+		$post->post_status = $post_status;
+		Functions\when( 'get_post' )->justReturn( $post );
+
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) use ( $run_status ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'SHOW TABLES' ) ) {
+					if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+						return 'wp_prautoblogger_stage_inputs';
+					}
+					if ( false !== strpos( $sql, 'run_stages' ) ) {
+						return 'wp_prautoblogger_run_stages';
+					}
+					return 'wp_prautoblogger_runs';
+				}
+				if ( false !== strpos( $sql, 'MAX(version)' ) ) {
+					return null; // First fork version.
+				}
+				return null; // Lock free; no seed.
+			}
+		);
+		$this->wpdb->method( 'get_row' )->willReturnCallback(
+			static function ( $sql ) use ( $run_status ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+					return null; // No fork yet.
+				}
+				return array(
+					'run_id'      => 'run-1',
+					'status'      => $run_status,
+					'ceiling_usd' => '0.50',
+				);
+			}
+		);
+		// resolve_base_body falls through to the gen_log query.
+		$this->wpdb->method( 'get_results' )->willReturn(
+			array(
+				array(
+					'id'              => '11',
+					'stage'           => 'draft',
+					'request_json'    => '{"model":"m","messages":[{"role":"system","content":"sys"},{"role":"user","content":"orig"}]}',
+					'response_status' => 'success',
+				),
+			)
+		);
+	}
+}

tests/unit/Admin/DossierAssemblerRerunDataTest.php

@@ -0,0 +1,236 @@
+<?php
+/**
+ * Tests for the v0.20.0 dossier view-model additions (M3 + F2/F3).
+ *
+ * Locks: item-scoped stage filtering (multi-article runs no longer
+ * collide), other-post gen_log row exclusion, per-stage rerun panel
+ * data (policy reasons on non-editable stages; editable writer stage
+ * with recorded input), log-only stage exposure (F3) and the spend
+ * strip shape (guardrail 4 visibility).
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class DossierAssemblerRerunDataTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->wpdb          = $this->create_mock_wpdb();
+		$this->wpdb->options = 'wp_options';
+		$GLOBALS['wpdb']     = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		Functions\when( 'get_post_thumbnail_id' )->justReturn( 0 );
+		Functions\when( 'get_children' )->justReturn( array() );
+		Functions\when( 'wp_get_attachment_image_url' )->justReturn( '' );
+		Functions\when( 'apply_filters' )->returnArg( 2 );
+
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Build the standard post + meta wiring. */
+	private function wire_post(): void {
+		$post              = new \WP_Post();
+		$post->ID          = 99;
+		$post->post_title  = 'Test Article';
+		$post->post_status = 'draft';
+		Functions\when( 'get_post' )->justReturn( $post );
+		Functions\when( 'get_post_meta' )->alias(
+			static function ( $post_id, $key ) {
+				$map = array(
+					'_prautoblogger_run_id'         => 'run-1',
+					'_prautoblogger_idea_hash'      => 'abc123',
+					'_prautoblogger_editor_verdict' => 'approved',
+					'_prautoblogger_article_type'   => 'guide',
+				);
+				return $map[ $key ] ?? '';
+			}
+		);
+	}
+
+	/** Wire wpdb for: tables exist, run row, stage rows, gen_log rows, lock free. */
+	private function wire_data( array $stage_rows, array $log_rows ): void {
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'SHOW TABLES' ) ) {
+					if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+						return 'wp_prautoblogger_stage_inputs';
+					}
+					if ( false !== strpos( $sql, 'run_stages' ) ) {
+						return 'wp_prautoblogger_run_stages';
+					}
+					return 'wp_prautoblogger_runs';
+				}
+				return null; // Lock free.
+			}
+		);
+		$this->wpdb->method( 'get_row' )->willReturnCallback(
+			static function ( $sql ) {
+				if ( false !== strpos( (string) $sql, 'stage_inputs' ) ) {
+					return null; // No forks saved.
+				}
+				return array(
+					'run_id'       => 'run-1',
+					'status'       => 'done',
+					'ceiling_usd'  => '0.50',
+					'settled_usd'  => '0.30',
+					'reserved_usd' => '0.15',
+				);
+			}
+		);
+		$this->wpdb->method( 'get_results' )->willReturnCallback(
+			static function ( $sql ) use ( $stage_rows, $log_rows ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'run_stages' ) ) {
+					return $stage_rows;
+				}
+				if ( false !== strpos( $sql, 'generation_log' ) ) {
+					return $log_rows;
+				}
+				return array(); // run_decisions.
+			}
+		);
+	}
+
+	/**
+	 * The stage query is item-scoped (idea hash -> item_key IN (item, ''))
+	 * and gen_log rows belonging to OTHER posts are dropped while
+	 * unlinked (post_id NULL/0) rows are kept.
+	 */
+	public function test_item_scoping_and_other_post_log_exclusion(): void {
+		$this->wire_post();
+		$captured_stage_sql = null;
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				if ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) {
+					return false !== strpos( (string) $sql, 'stage_inputs' ) ? 'wp_prautoblogger_stage_inputs'
+						: ( false !== strpos( (string) $sql, 'run_stages' ) ? 'wp_prautoblogger_run_stages' : 'wp_prautoblogger_runs' );
+				}
+				return null;
+			}
+		);
+		$this->wpdb->method( 'get_row' )->willReturn( array( 'run_id' => 'run-1', 'status' => 'done', 'ceiling_usd' => '0' ) );
+		$this->wpdb->method( 'get_results' )->willReturnCallback(
+			static function ( $sql ) use ( &$captured_stage_sql ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'run_stages' ) ) {
+					$captured_stage_sql = $sql;
+					return array();
+				}
+				if ( false !== strpos( $sql, 'generation_log' ) ) {
+					return array(
+						array( 'id' => '1', 'stage' => 'draft', 'post_id' => '99', 'model' => 'm', 'request_json' => null ),
+						array( 'id' => '2', 'stage' => 'draft', 'post_id' => '77', 'model' => 'm', 'request_json' => null ),
+						array( 'id' => '3', 'stage' => 'llm_research', 'post_id' => null, 'model' => 'm', 'request_json' => null ),
+					);
+				}
+				return array();
+			}
+		);
+
+		$dossier = ( new \PRAutoBlogger_Dossier_Data_Assembler() )->assemble( 99 );
+
+		$this->assertSame( 'idea:abc123', $dossier['item_key'] );
+		$this->assertStringContainsString( "item_key IN (%s, '')", (string) $captured_stage_sql );
+		// Post 77's draft row dropped; this post's row + unlinked research row kept.
+		$this->assertCount( 1, $dossier['gen_log_index']['draft'] );
+		$this->assertSame( '1', $dossier['gen_log_index']['draft'][0]['id'] );
+		$this->assertCount( 1, $dossier['gen_log_index']['llm_research'] );
+		// F3: llm_research has no run_stages row -> exposed as log-only.
+		$this->assertContains( 'llm_research', $dossier['log_only_stages'] );
+	}
+
+	/**
+	 * Per-stage rerun data: a writer stage with a recorded request is
+	 * editable with prefill; review carries a policy reason instead; the
+	 * spend strip reflects the ledger row (guardrail 4 visibility).
+	 */
+	public function test_stage_rerun_panel_data_and_spend(): void {
+		$this->wire_post();
+		$stage_rows = array(
+			array(
+				'id'             => '1',
+				'run_id'         => 'run-1',
+				'stage'          => 'draft',
+				'agent_role'     => 'writer',
+				'item_key'       => 'idea:abc123',
+				'status'         => 'done',
+				'attempt'        => '1',
+				'cost_usd'       => '0.01',
+				'meta_json'      => '{"output":"text"}',
+				'stale'          => '0',
+				'human_modified' => '1',
+			),
+			array(
+				'id'         => '2',
+				'run_id'     => 'run-1',
+				'stage'      => 'review',
+				'agent_role' => 'editor',
+				'item_key'   => 'idea:abc123',
+				'status'     => 'done',
+				'attempt'    => '1',
+				'cost_usd'   => '0.005',
+				'meta_json'  => null,
+				'stale'      => '1',
+			),
+		);
+		$log_rows   = array(
+			array(
+				'id'              => '10',
+				'stage'           => 'draft',
+				'post_id'         => '99',
+				'model'           => 'google/gemini-2.5-flash-lite',
+				'request_json'    => '{"model":"google/gemini-2.5-flash-lite","messages":[{"role":"user","content":"draft prompt"}]}',
+				'response_status' => 'success',
+			),
+		);
+		$this->wire_data( $stage_rows, $log_rows );
+
+		$dossier = ( new \PRAutoBlogger_Dossier_Data_Assembler() )->assemble( 99 );
+
+		$draft = $dossier['stages']['draft:writer']['rerun'];
+		$this->assertTrue( $draft['editable'] );
+		$this->assertSame( 'draft prompt', $draft['prefill']['messages'][0]['content'] );
+		$this->assertTrue( $draft['human_modified'] );
+		$this->assertTrue( $dossier['human_modified_any'] );
+
+		$review = $dossier['stages']['review:editor']['rerun'];
+		$this->assertFalse( $review['editable'] );
+		$this->assertStringContainsString( 'Re-run from here', $review['edit_reason'] );
+		$this->assertTrue( $review['stale'] );
+		$this->assertTrue( $review['rerun_from'] );
+		$this->assertTrue( $dossier['stale_any'] );
+
+		$this->assertSame( 0.30, $dossier['spend']['settled'] );
+		$this->assertSame( 0.15, $dossier['spend']['reserved'] );
+		$this->assertSame( 0.50, $dossier['spend']['ceiling'] );
+		$this->assertTrue( $dossier['spend']['warn'] ); // 0.45/0.50 = 90% >= 80%.
+	}
+}

tests/unit/Admin/DossierDataAssemblerTest.php

@@ -37,6 +37,14 @@ class DossierDataAssemblerTest extends BaseTestCase {
 		// Stub PRAutoBlogger_Run_Stage_State::is_available() to return true.
 		// Static method -- stubbed via wpdb table check returning the table name.
 		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+
+		// v0.20.0 additions: image data + eligibility paths.
+		Functions\when( 'get_post_thumbnail_id' )->justReturn( 0 );
+		Functions\when( 'get_children' )->justReturn( array() );
+		Functions\when( 'wp_get_attachment_image_url' )->justReturn( '' );
+		Functions\when( 'apply_filters' )->returnArg( 2 );
 
 		// table_name returns wp_prautoblogger_run_stages.
 		$this->wpdb->prefix = 'wp_';

tests/unit/Admin/DossierMenuRegistrationTestCase.php

@@ -51,6 +51,11 @@ abstract class DossierMenuRegistrationTestCase extends BaseTestCase {
 		$this->captured_menu_slug    = null;
 		$this->registration_hookname = null;
 
+		// v0.20.0: the dossier enqueue path localizes the edit/re-run config.
+		Functions\when( 'wp_localize_script' )->justReturn( true );
+		Functions\when( 'wp_create_nonce' )->justReturn( 'test-nonce' );
+		Functions\when( 'absint' )->alias( static function ( $val ) { return abs( (int) $val ); } );
+
 		// Spy stub: tracks call order, captures slugs, returns a hookname that
 		// reflects how WordPress actually resolves it for known parents.
 		Functions\when( 'add_menu_page' )->alias(

tests/unit/Admin/SettingsFieldsExtendedTest.php

@@ -0,0 +1,77 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Settings_Fields_Extended.
+ *
+ * Pins the cardinality contract on get_fields() so any future split that
+ * accidentally re-introduces a + array union (dropping keys) fails CI
+ * rather than silently at runtime.
+ *
+ * @package PRAutoBlogger\Tests\Admin
+ */
+
+namespace PRAutoBlogger\Tests\Admin;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class SettingsFieldsExtendedTest extends BaseTestCase {
+
+	/**
+	 * Stub WP functions that the settings-field classes invoke.
+	 */
+	protected function setUp(): void {
+		parent::setUp();
+		// Image_Model_Registry checks option cache; return false to use hardcoded list.
+		\Brain\Monkey\Functions\when( 'get_option' )->justReturn( false );
+		\Brain\Monkey\Functions\when( 'update_option' )->justReturn( true );
+		// wp_timezone_string is referenced in schedule-time field description.
+		\Brain\Monkey\Functions\when( 'wp_timezone_string' )->justReturn( 'UTC' );
+	}
+
+	/**
+	 * get_fields() must return exactly 29 fields (18 local + 11 image).
+	 *
+	 * This pins the array_merge fix: if a + operator re-appears the image
+	 * fields are silently dropped to 18 and this test fails CI.
+	 * Count breakdown: 18 schedule/publishing/analytics/display/sources fields
+	 * from the local array + 11 image fields from Settings_Fields_Images.
+	 */
+	public function test_get_fields_returns_29_fields(): void {
+		$fields = \PRAutoBlogger_Settings_Fields_Extended::get_fields();
+		$this->assertCount(
+			29,
+			$fields,
+			'Expected 29 fields (18 local + 11 image). A + union instead of array_merge would return only 18.'
+		);
+	}
+
+	/**
+	 * Every field must carry a non-empty id and a section string.
+	 * This catches a malformed field entry that would fail register_setting().
+	 */
+	public function test_every_field_has_id_and_section(): void {
+		$fields = \PRAutoBlogger_Settings_Fields_Extended::get_fields();
+		foreach ( $fields as $field ) {
+			$this->assertArrayHasKey( 'id', $field, 'Field missing id key' );
+			$this->assertNotEmpty( $field['id'], 'Field has empty id' );
+			$this->assertArrayHasKey( 'section', $field, sprintf( 'Field %s missing section key', $field['id'] ) );
+		}
+	}
+
+	/**
+	 * The image fields from Settings_Fields_Images must all be present.
+	 *
+	 * Checks that prautoblogger_image_enabled (first image field)
+	 * exists in the merged result — if the + union regresses, this field
+	 * would be missing because it is at index 0 in the image array (which
+	 * collides with index 0 in the local array under +).
+	 */
+	public function test_image_fields_present_in_merged_result(): void {
+		$fields = \PRAutoBlogger_Settings_Fields_Extended::get_fields();
+		$ids    = array_column( $fields, 'id' );
+		$this->assertContains(
+			'prautoblogger_image_enabled',
+			$ids,
+			'Enable Image Generation toggle missing — array_merge may have regressed to +'
+		);
+	}
+}

tests/unit/BaseTestCase.php

@@ -147,7 +147,7 @@ abstract class BaseTestCase extends TestCase {
      */
     protected function create_mock_wpdb() {
         $wpdb = $this->getMockBuilder( \stdClass::class )
-            ->addMethods( [ 'prepare', 'get_var', 'get_results', 'insert', 'query', 'get_row', 'update' ] )
+            ->addMethods( [ 'prepare', 'get_var', 'get_results', 'insert', 'query', 'get_row', 'get_col', 'update' ] )
             ->getMock();
 
         $wpdb->prefix         = 'wp_';

tests/unit/Core/CostTrackerRequestJsonTest.php

@@ -0,0 +1,181 @@
+<?php
+/**
+ * Tests for the v0.20.0 (B1) request_json persistence in
+ * PRAutoBlogger_Cost_Tracker::log_api_call().
+ *
+ * Every chat call's request body must land on its generation_log row
+ * (stage inputs exist for edit + re-run; the dossier raw-input trace is
+ * no longer hollow — QA M2 F1), with consume-once isolation between rows.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class CostTrackerRequestJsonTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb instance.
+	 */
+	private $wpdb;
+
+	/**
+	 * Rows captured from $wpdb->insert().
+	 *
+	 * @var array<int, array<string, mixed>>
+	 */
+	private array $inserted = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->inserted  = array();
+		$this->wpdb      = $this->create_mock_wpdb();
+		$GLOBALS['wpdb'] = $this->wpdb;
+		$this->wpdb->insert_id = 7;
+		$this->wpdb->method( 'insert' )->willReturnCallback(
+			function ( $table, $row ) {
+				// Capture generation_log rows only — the Logger also
+				// inserts (event_log) when e.g. Pricing warns on an
+				// unknown model; those rows are not under test.
+				if ( false !== strpos( (string) $table, 'generation_log' ) ) {
+					$this->inserted[] = (array) $row;
+				}
+				return 1;
+			}
+		);
+		$this->stub_get_option( array() );
+		\PRAutoBlogger_Request_Recorder::clear();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Request_Recorder::clear();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/**
+	 * log_api_call() persists the recorder stash into request_json.
+	 */
+	public function test_log_api_call_persists_recorded_request_json(): void {
+		\PRAutoBlogger_Request_Recorder::record(
+			array(
+				'model'    => 'google/gemini-2.5-flash-lite',
+				'messages' => array( array( 'role' => 'user', 'content' => 'draft prompt' ) ),
+			)
+		);
+
+		( new \PRAutoBlogger_Cost_Tracker() )->log_api_call(
+			null,
+			'draft',
+			'OpenRouter',
+			'google/gemini-2.5-flash-lite',
+			100,
+			500
+		);
+
+		$this->assertCount( 1, $this->inserted );
+		$row = $this->inserted[0];
+		$this->assertArrayHasKey( 'request_json', $row );
+		$decoded = json_decode( (string) $row['request_json'], true );
+		$this->assertSame( 'draft prompt', $decoded['messages'][0]['content'] );
+	}
+
+	/**
+	 * Consume-once isolation: a second log row written with no new send
+	 * in between must get NULL, never the previous call's body.
+	 */
+	public function test_second_log_row_without_new_record_gets_null(): void {
+		\PRAutoBlogger_Request_Recorder::record( array( 'model' => 'm1' ) );
+
+		$tracker = new \PRAutoBlogger_Cost_Tracker();
+		$tracker->log_api_call( null, 'draft', 'OpenRouter', 'm1', 10, 10 );
+		$tracker->log_api_call( null, 'polish', 'OpenRouter', 'm1', 10, 10 );
+
+		$this->assertCount( 2, $this->inserted );
+		$this->assertNotNull( $this->inserted[0]['request_json'] );
+		$this->assertNull( $this->inserted[1]['request_json'] );
+	}
+
+	/**
+	 * Historical behavior preserved: nothing recorded -> request_json NULL.
+	 */
+	public function test_log_api_call_without_stash_writes_null(): void {
+		( new \PRAutoBlogger_Cost_Tracker() )->log_api_call(
+			null,
+			'analysis',
+			'OpenRouter',
+			'google/gemini-2.5-flash-lite',
+			10,
+			10
+		);
+
+		$this->assertCount( 1, $this->inserted );
+		$this->assertNull( $this->inserted[0]['request_json'] );
+	}
+
+	/**
+	 * The persisted payload can never contain credential material — the
+	 * provider records only build_body() output (headers are separate).
+	 * Belt-and-braces audit on the exact column value.
+	 */
+	public function test_persisted_request_json_contains_no_auth_header(): void {
+		$this->stub_get_option( array() );
+		$builder = new \PRAutoBlogger_OpenRouter_Request_Builder();
+		\PRAutoBlogger_Request_Recorder::record(
+			$builder->build_body(
+				array( array( 'role' => 'user', 'content' => 'x' ) ),
+				'google/gemini-2.5-flash-lite',
+				array( 'max_tokens' => 100 )
+			)
+		);
+
+		( new \PRAutoBlogger_Cost_Tracker() )->log_api_call(
+			null,
+			'draft',
+			'OpenRouter',
+			'google/gemini-2.5-flash-lite',
+			10,
+			10
+		);
+
+		$json = (string) $this->inserted[0]['request_json'];
+		$this->assertStringNotContainsString( 'Authorization', $json );
+		$this->assertStringNotContainsString( 'Bearer', $json );
+		$this->assertStringNotContainsString( 'sk-or-', $json );
+	}
+
+	/**
+	 * The half-migrated-schema legacy retry (v0.18.0 pattern) keeps
+	 * request_json — the column predates the audit columns (v1.1.0
+	 * schema) and exists on every site.
+	 */
+	public function test_legacy_schema_retry_keeps_request_json(): void {
+		$this->inserted = array();
+		$wpdb           = $this->create_mock_wpdb();
+		$wpdb->insert_id = 7;
+		$calls           = 0;
+		$wpdb->method( 'insert' )->willReturnCallback(
+			function ( $table, $row ) use ( &$calls ) {
+				if ( false === strpos( (string) $table, 'generation_log' ) ) {
+					return 1; // Logger/event_log noise — not under test.
+				}
+				++$calls;
+				$this->inserted[] = (array) $row;
+				return 1 === $calls ? false : 1; // First insert fails (missing v0.18.0 columns).
+			}
+		);
+		$GLOBALS['wpdb'] = $wpdb;
+
+		\PRAutoBlogger_Request_Recorder::record( array( 'model' => 'm1' ) );
+		( new \PRAutoBlogger_Cost_Tracker() )->log_api_call( null, 'draft', 'OpenRouter', 'm1', 10, 10 );
+
+		$this->assertCount( 2, $this->inserted );
+		$retry_row = $this->inserted[1];
+		$this->assertArrayNotHasKey( 'agent_role', $retry_row );
+		$this->assertArrayNotHasKey( 'prompt_version', $retry_row );
+		$this->assertArrayHasKey( 'request_json', $retry_row );
+		$this->assertNotNull( $retry_row['request_json'] );
+	}
+}

tests/unit/Core/GenerationCheckpointRunnerSyncModeTest.php

@@ -0,0 +1,249 @@
+<?php
+/**
+ * Sync-mode guard tests for PRAutoBlogger_Generation_Checkpoint_Runner (v0.22.1).
+ *
+ * Isolated from GenerationCheckpointRunnerTest to keep both files under 300 lines.
+ *
+ * Contract under test:
+ *   set_sync_mode(true) -> on_orchestrate_tick() must NOT schedule GENERATE_ACTION
+ *     or call spawn_cron/fire_cron_now (VPS loop drives ticks directly).
+ *     NON-VACUOUS: orchestrate_only() returns 1 idea so execution reaches the guard
+ *     at line ~181, not the empty-ideas early return at ~148.
+ *   set_sync_mode(true) -> on_generate_tick() with ideas remaining must NOT schedule
+ *     GENERATE_ACTION or call spawn_cron/fire_cron_now.
+ *   set_sync_mode(false) -> on_generate_tick() with ideas remaining DOES schedule
+ *     GENERATE_ACTION (regression guard -- async path unaffected by sync guard).
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class GenerationCheckpointRunnerSyncModeTest extends BaseTestCase {
+
+	/** @var string[] Cron hooks captured from wp_schedule_single_event(). */
+	private array $scheduled = array();
+
+	/** @var array<string, mixed> Option writes captured from update_option(). */
+	private array $options = array();
+
+	/** @var bool Tracks whether spawn_cron was called. */
+	private bool $spawn_called = false;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->scheduled    = array();
+		$this->options      = array();
+		$this->spawn_called = false;
+
+		Functions\when( 'wp_schedule_single_event' )->alias(
+			function ( $ts, $hook, $args = array() ) {
+				$this->scheduled[] = $hook;
+				return true;
+			}
+		);
+		Functions\when( 'wp_next_scheduled' )->justReturn( false );
+		Functions\when( 'spawn_cron' )->alias( function () {
+			$this->spawn_called = true;
+			return true;
+		} );
+		Functions\when( 'wp_remote_post' )->justReturn( array() );
+		Functions\when( 'site_url' )->justReturn( 'https://example.com' );
+
+		Functions\when( 'set_transient' )->justReturn( true );
+		Functions\when( 'update_option' )->alias(
+			function ( $name, $value, $autoload = null ) {
+				$this->options[ $name ] = $value;
+				return true;
+			}
+		);
+		Functions\when( 'delete_option' )->alias(
+			function ( $name ) {
+				unset( $this->options[ $name ] );
+				return true;
+			}
+		);
+		Functions\when( 'get_option' )->alias(
+			function ( $name, $default = false ) {
+				return $this->options[ $name ] ?? $default;
+			}
+		);
+		Functions\when( 'wp_generate_uuid4' )->justReturn( 'sync-test-uuid-001' );
+		$this->options['prautoblogger_monthly_budget_usd'] = '0';
+		Functions\when( 'wp_cache_get' )->justReturn( false );
+		Functions\when( 'wp_cache_set' )->justReturn( true );
+		Functions\when( 'wp_cache_delete' )->justReturn( true );
+		\PRAutoBlogger_Run_State::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( false );
+		\PRAutoBlogger_Run_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Stub the generation lock to always succeed. */
+	private function wire_wpdb_for_lock(): void {
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+	}
+
+	/** Build a minimal Article_Idea-compatible array. */
+	private function make_idea( string $topic = 'Sync Topic' ): array {
+		return array(
+			'topic'           => $topic,
+			'article_type'    => 'guide',
+			'suggested_title' => 'Guide to ' . $topic,
+			'summary'         => '',
+			'score'           => 0.9,
+			'analysis_id'     => 1,
+			'source_ids'      => array(),
+			'key_points'      => array(),
+			'target_keywords' => array(),
+		);
+	}
+
+	// __ sync-mode guard: on_orchestrate_tick() ______________________________________________
+
+	/**
+	 * sync_mode=true + >=1 idea returned: on_orchestrate_tick() must not schedule
+	 * GENERATE_ACTION or call spawn_cron (VPS loop drives generate ticks directly).
+	 *
+	 * NON-VACUOUS: orchestrate_only() returns 1 idea so execution reaches the sync
+	 * guard at line ~181, not the empty-ideas early return at ~148.
+	 */
+	public function test_orchestrate_tick_in_sync_mode_does_not_schedule_background_event(): void {
+		$this->wire_wpdb_for_lock();
+
+		// Provide Pipeline_Runner stub that returns 1 idea -- forces execution past
+		// the empty-ideas early return so the sync guard at line ~181 is exercised.
+		if ( ! class_exists( 'PRAutoBlogger_Pipeline_Runner', false ) ) {
+			// phpcs:ignore Squiz.Strings.DoubleQuoteUsage.NotRequired
+			eval( 'class PRAutoBlogger_Pipeline_Runner {
+				public function set_skip_dedup($v){ return $this; }
+				public function orchestrate_only($ct){
+					$idea = new PRAutoBlogger_Article_Idea([
+						"topic"=>"Sync Topic","article_type"=>"guide",
+						"suggested_title"=>"Guide","summary"=>"","score"=>0.9,
+						"analysis_id"=>1,"source_ids"=>[],"key_points"=>[],
+						"target_keywords"=>[]
+					]);
+					return [$idea];
+				}
+			}' );
+		}
+
+		\PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( true );
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_orchestrate_tick();
+
+		$this->assertNotContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'sync mode: on_orchestrate_tick must not schedule GENERATE_ACTION'
+		);
+		$this->assertFalse(
+			$this->spawn_called,
+			'sync mode: on_orchestrate_tick must not call spawn_cron'
+		);
+	}
+
+	// __ sync-mode guard: on_generate_tick() _________________________________________________
+
+	/**
+	 * sync_mode=true + 2 ideas in queue: on_generate_tick() must not reschedule
+	 * GENERATE_ACTION or call spawn_cron (VPS loop is the sole driver of next tick).
+	 *
+	 * Uses 2 ideas so the code stays in the "more ideas remain" branch -- this
+	 * path calls Article_Worker->generate() and then the sync guard, never
+	 * Post_Assembler::amortize_research_costs() (that is in the last-idea branch).
+	 * Article_Worker is stubbed; Post_Assembler is not needed and must NOT be
+	 * redefined here to avoid clobbering the real class for downstream tests.
+	 */
+	public function test_generate_tick_sync_mode_suppresses_reschedule(): void {
+		$run_id = 'sync-gen-tick-uuid';
+		$this->options['prautoblogger_article_queue'] = array(
+			'run_id'  => $run_id,
+			'ideas'   => array( $this->make_idea( 'A' ), $this->make_idea( 'B' ) ),
+			'results' => array( 'generated' => 0, 'published' => 0, 'rejected' => 0, 'cost' => 0.0 ),
+		);
+
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'get_row' )->willReturn( array( 'status' => 'running', 'ceiling_usd' => '0' ) );
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+
+		// Stub Article_Worker only -- Post_Assembler is NOT stubbed here because
+		// amortize_research_costs() is not called on the "more ideas remain" path,
+		// and redefining it with an incomplete stub breaks Publisher tests that run
+		// after this file (alphabetical: SyncModeTest < Test).
+		if ( ! class_exists( 'PRAutoBlogger_Article_Worker', false ) ) {
+			// phpcs:ignore Squiz.Strings.DoubleQuoteUsage.NotRequired
+			eval( 'class PRAutoBlogger_Article_Worker {
+				public function __construct($ct){}
+				public function generate($idea){ return ["generated"=>1,"published"=>1,"rejected"=>0,"cost"=>0.01]; }
+			}' );
+		}
+
+		\PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( true );
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+
+		$this->assertNotContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'sync mode: on_generate_tick must not schedule GENERATE_ACTION'
+		);
+		$this->assertFalse(
+			$this->spawn_called,
+			'sync mode: on_generate_tick must not call spawn_cron'
+		);
+	}
+
+	// __ async regression guard ______________________________________________________________
+
+	/**
+	 * sync_mode=false: on_generate_tick() with ideas remaining DOES schedule
+	 * GENERATE_ACTION (regression guard -- async path must be unaffected by sync guard).
+	 */
+	public function test_generate_tick_async_mode_schedules_generate_action(): void {
+		$run_id = 'async-regression-uuid';
+		$this->options['prautoblogger_article_queue'] = array(
+			'run_id'  => $run_id,
+			'ideas'   => array( $this->make_idea( 'A' ), $this->make_idea( 'B' ) ),
+			'results' => array( 'generated' => 0, 'published' => 0, 'rejected' => 0, 'cost' => 0.0 ),
+		);
+
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'get_row' )->willReturn( array( 'status' => 'running', 'ceiling_usd' => '0' ) );
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+
+		// Article_Worker stub only -- see note in test_generate_tick_sync_mode_suppresses_reschedule.
+		if ( ! class_exists( 'PRAutoBlogger_Article_Worker', false ) ) {
+			// phpcs:ignore Squiz.Strings.DoubleQuoteUsage.NotRequired
+			eval( 'class PRAutoBlogger_Article_Worker {
+				public function __construct($ct){}
+				public function generate($idea){ return ["generated"=>1,"published"=>1,"rejected"=>0,"cost"=>0.01]; }
+			}' );
+		}
+
+		\PRAutoBlogger_Generation_Checkpoint_Runner::set_sync_mode( false );
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+
+		$this->assertContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'async mode: on_generate_tick must schedule GENERATE_ACTION when ideas remain'
+		);
+	}
+}

tests/unit/Core/GenerationCheckpointRunnerTest.php

@@ -0,0 +1,233 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Generation_Checkpoint_Runner (v0.21.0, M4).
+ *
+ * Locks the chained-cron checkpoint contract:
+ *   kick_off()         -- schedules cron + writes initial transient, no pipeline call.
+ *   on_generate_tick() -- pops ONE idea, reschedules or finalizes; halted run aborts early.
+ *
+ * Sync-mode guard tests live in GenerationCheckpointRunnerSyncModeTest.php
+ * (split to comply with the 300-line rule).
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class GenerationCheckpointRunnerTest extends BaseTestCase {
+
+	/** @var string[] Cron hooks captured from wp_schedule_single_event(). */
+	private array $scheduled = array();
+
+	/** @var array<string, mixed> Option writes captured from update_option(). */
+	private array $options = array();
+
+	/** @var array<int, array> Transient writes captured from set_transient(). */
+	private array $transients = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->scheduled  = array();
+		$this->options    = array();
+		$this->transients = array();
+
+		Functions\when( 'wp_schedule_single_event' )->alias(
+			function ( $ts, $hook, $args = array() ) {
+				$this->scheduled[] = $hook;
+				return true;
+			}
+		);
+		Functions\when( 'wp_next_scheduled' )->justReturn( false );
+		Functions\when( 'spawn_cron' )->justReturn( true );
+		Functions\when( 'wp_remote_post' )->justReturn( array() );
+		Functions\when( 'site_url' )->justReturn( 'https://example.com' );
+
+		Functions\when( 'set_transient' )->alias(
+			function ( $key, $value, $ttl = 0 ) {
+				$this->transients[] = array( 'key' => $key, 'value' => (array) $value );
+				return true;
+			}
+		);
+		Functions\when( 'update_option' )->alias(
+			function ( $name, $value, $autoload = null ) {
+				$this->options[ $name ] = $value;
+				return true;
+			}
+		);
+		Functions\when( 'delete_option' )->alias(
+			function ( $name ) {
+				unset( $this->options[ $name ] );
+				return true;
+			}
+		);
+		Functions\when( 'get_option' )->alias(
+			function ( $name, $default = false ) {
+				return $this->options[ $name ] ?? $default;
+			}
+		);
+		Functions\when( 'wp_generate_uuid4' )->justReturn( 'test-run-uuid-001' );
+		// Monthly budget 0 = no limit.
+		$this->options['prautoblogger_monthly_budget_usd'] = '0';
+		Functions\when( 'wp_cache_get' )->justReturn( false );
+		Functions\when( 'wp_cache_set' )->justReturn( true );
+		Functions\when( 'wp_cache_delete' )->justReturn( true );
+		\PRAutoBlogger_Run_State::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Stub the generation lock to always succeed. */
+	private function wire_wpdb_for_lock(): void {
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+	}
+
+	/** Build a minimal Article_Idea-compatible array. */
+	private function make_idea( string $topic = 'Test Topic' ): array {
+		return array(
+			'topic'           => $topic,
+			'article_type'    => 'guide',
+			'suggested_title' => 'Guide to ' . $topic,
+			'summary'         => '',
+			'score'           => 0.9,
+			'analysis_id'     => 1,
+			'source_ids'      => array(),
+			'key_points'      => array(),
+			'target_keywords' => array(),
+		);
+	}
+
+	// __ kick_off() __________________________________________________________________________
+
+	/**
+	 * kick_off() schedules exactly the ORCHESTRATE cron action and writes
+	 * an initial 'running' status transient. The pipeline is NOT called.
+	 */
+	public function test_kick_off_schedules_orchestrate_cron_and_writes_initial_transient(): void {
+		\PRAutoBlogger_Generation_Checkpoint_Runner::kick_off();
+
+		$this->assertContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::ORCHESTRATE_ACTION,
+			$this->scheduled,
+			'kick_off() must schedule ORCHESTRATE_ACTION'
+		);
+
+		$found_running_transient = false;
+		foreach ( $this->transients as $t ) {
+			if ( isset( $t['value']['status'] ) && 'running' === $t['value']['status'] ) {
+				$found_running_transient = true;
+				break;
+			}
+		}
+		$this->assertTrue( $found_running_transient, 'kick_off() must write a running status transient' );
+	}
+
+	// __ on_generate_tick() __________________________________________________________________
+
+	/**
+	 * An empty queue causes generate tick to finalize without scheduling
+	 * another GENERATE action (no Article_Worker call).
+	 */
+	public function test_generate_tick_finalizes_when_queue_is_empty(): void {
+		// No queue option => get_option returns false (default from setUp alias).
+		// wire_wpdb_for_lock() provides $wpdb so Helpers::finalize() ->
+		// Generation_Lock::release() can run without "Call to member on null".
+		$this->wire_wpdb_for_lock();
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+
+		$this->assertNotContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'Empty queue must not reschedule GENERATE'
+		);
+	}
+
+	/**
+	 * A halted run causes generate tick to abort: queue is cleaned up and
+	 * GENERATE is not rescheduled (Article_Worker would not be called again).
+	 */
+	public function test_generate_tick_aborts_on_halted_run_without_rescheduling(): void {
+		$run_id = 'halted-run-uuid';
+		$this->options['prautoblogger_article_queue'] = array(
+			'run_id'  => $run_id,
+			'ideas'   => array( $this->make_idea() ),
+			'results' => array( 'generated' => 0, 'published' => 0, 'rejected' => 0, 'cost' => 0.0 ),
+		);
+
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'get_row' )->willReturn( array( 'status' => 'halted', 'ceiling_usd' => '0' ) );
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+
+		$this->assertArrayNotHasKey(
+			'prautoblogger_article_queue',
+			$this->options,
+			'Halted run must trigger queue cleanup'
+		);
+		$this->assertNotContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'Halted run must not reschedule GENERATE'
+		);
+	}
+
+	/**
+	 * With 2 ideas in queue, first generate tick pops one, reschedules GENERATE,
+	 * and leaves 1 idea remaining in the persisted queue.
+	 */
+	public function test_generate_tick_pops_one_idea_and_reschedules_when_more_remain(): void {
+		$run_id = 'multi-idea-run-uuid';
+		$this->options['prautoblogger_article_queue'] = array(
+			'run_id'  => $run_id,
+			'ideas'   => array( $this->make_idea( 'Idea A' ), $this->make_idea( 'Idea B' ) ),
+			'results' => array( 'generated' => 0, 'published' => 0, 'rejected' => 0, 'cost' => 0.0 ),
+		);
+		$this->options['prautoblogger_checkpoint_run_id'] = $run_id;
+
+		$wpdb            = $this->create_mock_wpdb();
+		$wpdb->options   = 'wp_options';
+		$GLOBALS['wpdb'] = $wpdb;
+		$wpdb->method( 'get_row' )->willReturn( array( 'status' => 'running', 'ceiling_usd' => '0' ) );
+		$wpdb->method( 'query' )->willReturn( 1 );
+		$wpdb->method( 'get_var' )->willReturn( null );
+
+		// Provide stub Article_Worker so CI doesn't need real LLM dependencies.
+		if ( ! class_exists( 'PRAutoBlogger_Article_Worker', false ) ) {
+			// phpcs:ignore Squiz.Strings.DoubleQuoteUsage.NotRequired
+			eval( 'class PRAutoBlogger_Article_Worker {
+				public function __construct($ct){}
+				public function generate($idea){ return ["generated"=>1,"published"=>1,"rejected"=>0,"cost"=>0.01]; }
+			}' );
+		}
+		if ( ! class_exists( 'PRAutoBlogger_Post_Assembler', false ) ) {
+			// phpcs:ignore Squiz.Strings.DoubleQuoteUsage.NotRequired
+			eval( 'class PRAutoBlogger_Post_Assembler { public static function amortize_research_costs($r){} }' );
+		}
+
+		\PRAutoBlogger_Generation_Checkpoint_Runner::on_generate_tick();
+
+		$this->assertContains(
+			\PRAutoBlogger_Generation_Checkpoint_Runner::GENERATE_ACTION,
+			$this->scheduled,
+			'More ideas remaining: GENERATE must be rescheduled'
+		);
+		if ( isset( $this->options['prautoblogger_article_queue'] ) ) {
+			$remaining = $this->options['prautoblogger_article_queue']['ideas'] ?? array();
+			$this->assertCount( 1, $remaining, 'Queue must have exactly 1 idea left after first tick' );
+		}
+	}
+}

tests/unit/Core/PublisherRerunUpdateTest.php

@@ -0,0 +1,134 @@
+<?php
+/**
+ * Tests for the v0.20.0 Publisher refresh-unpublished behavior.
+ *
+ * A re-run's regenerated content must land on the existing UNPUBLISHED
+ * post (idempotency previously skip-returned and silently discarded
+ * re-run output); published posts remain frozen and untouched (CPO
+ * guardrail 5 enforced at the data layer).
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class PublisherRerunUpdateTest extends BaseTestCase {
+
+	private \PRAutoBlogger_Article_Idea $idea;
+	private \PRAutoBlogger_Editorial_Review $review;
+
+	/**
+	 * Args captured from wp_update_post().
+	 *
+	 * @var array|null
+	 */
+	private $updated_args = null;
+
+	/**
+	 * Meta captured from update_post_meta().
+	 *
+	 * @var array<string, mixed>
+	 */
+	private array $updated_meta = array();
+
+	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() );
+
+		$this->stub_get_option( array() );
+		Functions\when( 'sanitize_text_field' )->returnArg();
+		Functions\when( 'wp_kses_post' )->returnArg();
+		Functions\when( 'wp_strip_all_tags' )->alias(
+			static function ( $text ) {
+				return trim( strip_tags( (string) $text ) );
+			}
+		);
+		Functions\when( 'is_wp_error' )->justReturn( false );
+		Functions\when( 'apply_filters' )->returnArg( 2 );
+
+		$this->updated_args = null;
+		$this->updated_meta = array();
+		Functions\when( 'wp_update_post' )->alias(
+			function ( $args ) {
+				$this->updated_args = (array) $args;
+				return $args['ID'] ?? 0;
+			}
+		);
+		Functions\when( 'update_post_meta' )->alias(
+			function ( $post_id, $key, $value ) {
+				$this->updated_meta[ (string) $key ] = $value;
+				return true;
+			}
+		);
+
+		// find_existing_post() resolves post 55 for this (run, idea).
+		$wpdb = $this->create_mock_wpdb();
+		$wpdb->method( 'prepare' )->willReturn( 'prepared' );
+		$wpdb->method( 'get_var' )->willReturn( '55' );
+		$GLOBALS['wpdb'] = $wpdb;
+	}
+
+	protected function tearDown(): void {
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Stub get_post for post 55 with a status. */
+	private function stub_existing_post( string $status ): void {
+		$post              = new \WP_Post();
+		$post->ID          = 55;
+		$post->post_status = $status;
+		Functions\when( 'get_post' )->justReturn( $post );
+	}
+
+	/**
+	 * Re-run output refreshes the existing draft: content + title are
+	 * updated, verdict meta refreshed — and the post status is NEVER
+	 * touched (a re-run must not publish; publication stays an explicit
+	 * operator action).
+	 */
+	public function test_rerun_refreshes_existing_draft_without_status_change(): void {
+		$this->stub_existing_post( 'draft' );
+		Functions\when( 'wp_insert_post' )->alias(
+			static function () {
+				throw new \RuntimeException( 'wp_insert_post must not be called for an existing post' );
+			}
+		);
+
+		$publisher = new \PRAutoBlogger_Publisher();
+		$post_id   = $publisher->save_as_draft( '<p>Regenerated content</p>', $this->idea, $this->review, 'run-1' );
+
+		$this->assertSame( 55, $post_id );
+		$this->assertIsArray( $this->updated_args );
+		$this->assertSame( 55, $this->updated_args['ID'] );
+		$this->assertStringContainsString( 'Regenerated content', (string) $this->updated_args['post_content'] );
+		$this->assertArrayNotHasKey( 'post_status', $this->updated_args );
+		$this->assertSame( $this->review->get_verdict(), $this->updated_meta['_prautoblogger_editor_verdict'] );
+		$this->assertArrayHasKey( '_prautoblogger_generated_at', $this->updated_meta );
+	}
+
+	/**
+	 * Published post: frozen — returned untouched, no wp_update_post, no
+	 * meta writes, no duplicate insert (guardrail 5 at the data layer).
+	 */
+	public function test_published_post_is_never_updated(): void {
+		$this->stub_existing_post( 'publish' );
+		Functions\when( 'wp_insert_post' )->alias(
+			static function () {
+				throw new \RuntimeException( 'wp_insert_post must not be called for an existing post' );
+			}
+		);
+
+		$publisher = new \PRAutoBlogger_Publisher();
+		$post_id   = $publisher->save_as_draft( '<p>Regenerated content</p>', $this->idea, $this->review, 'run-1' );
+
+		$this->assertSame( 55, $post_id );
+		$this->assertNull( $this->updated_args );
+		$this->assertSame( array(), $this->updated_meta );
+	}
+}

tests/unit/Core/RequestRecorderTest.php

@@ -0,0 +1,120 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Request_Recorder (v0.20.0 / B1).
+ *
+ * Locks the consume-once + overwrite-on-record semantics that make it
+ * impossible for a stale request body to attach to an unrelated log row,
+ * and the no-Authorization guarantee of the record path.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class RequestRecorderTest extends BaseTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		\PRAutoBlogger_Request_Recorder::clear();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Request_Recorder::clear();
+		parent::tearDown();
+	}
+
+	/**
+	 * consume() returns the recorded body exactly once, then null.
+	 */
+	public function test_consume_returns_recorded_body_exactly_once(): void {
+		\PRAutoBlogger_Request_Recorder::record(
+			array(
+				'model'    => 'google/gemini-2.5-flash-lite',
+				'messages' => array( array( 'role' => 'user', 'content' => 'hi' ) ),
+			)
+		);
+
+		$first = \PRAutoBlogger_Request_Recorder::consume();
+		$this->assertIsString( $first );
+		$decoded = json_decode( $first, true );
+		$this->assertSame( 'google/gemini-2.5-flash-lite', $decoded['model'] );
+		$this->assertSame( 'hi', $decoded['messages'][0]['content'] );
+
+		// Consume-once: the slot is cleared by the first read.
+		$this->assertNull( \PRAutoBlogger_Request_Recorder::consume() );
+	}
+
+	/**
+	 * record() overwrites the previous stash — a stale body from an
+	 * unlogged earlier call can never survive into the next dispatch.
+	 */
+	public function test_record_overwrites_previous_stash(): void {
+		\PRAutoBlogger_Request_Recorder::record( array( 'model' => 'first/model' ) );
+		\PRAutoBlogger_Request_Recorder::record( array( 'model' => 'second/model' ) );
+
+		$decoded = json_decode( (string) \PRAutoBlogger_Request_Recorder::consume(), true );
+		$this->assertSame( 'second/model', $decoded['model'] );
+	}
+
+	/**
+	 * consume() with nothing recorded returns null (historical rows /
+	 * non-chat log writes keep request_json NULL).
+	 */
+	public function test_consume_without_record_returns_null(): void {
+		$this->assertNull( \PRAutoBlogger_Request_Recorder::consume() );
+	}
+
+	/**
+	 * clear() empties the slot.
+	 */
+	public function test_clear_empties_slot(): void {
+		\PRAutoBlogger_Request_Recorder::record( array( 'model' => 'm' ) );
+		\PRAutoBlogger_Request_Recorder::clear();
+		$this->assertNull( \PRAutoBlogger_Request_Recorder::consume() );
+	}
+
+	/**
+	 * The full record path for a body built by the real Request_Builder
+	 * from poisoned options can never contain credential material:
+	 * build_body() copies only whitelisted keys and headers are built
+	 * separately, so the recorder's JSON has no Authorization shape.
+	 */
+	public function test_recorded_builder_body_never_contains_auth_material(): void {
+		$this->stub_get_option( array() );
+
+		$builder = new \PRAutoBlogger_OpenRouter_Request_Builder();
+		$body    = $builder->build_body(
+			array( array( 'role' => 'user', 'content' => 'write about BPC-157' ) ),
+			'google/gemini-2.5-flash-lite',
+			array(
+				'temperature'   => 0.7,
+				'max_tokens'    => 4000,
+				// Hostile/accidental injection attempts — must all be dropped.
+				'Authorization' => 'Bearer sk-or-secret-key-123',
+				'headers'       => array( 'Authorization' => 'Bearer sk-or-secret-key-123' ),
+				'api_key'       => 'sk-or-secret-key-123',
+				// Caller metadata — never sent upstream, never recorded.
+				'stage'         => 'draft',
+				'prompt_key'    => 'content.draft',
+				'empty_retry'   => true,
+			)
+		);
+		\PRAutoBlogger_Request_Recorder::record( $body );
+
+		$json = (string) \PRAutoBlogger_Request_Recorder::consume();
+		$this->assertStringNotContainsString( 'Authorization', $json );
+		$this->assertStringNotContainsString( 'Bearer', $json );
+		$this->assertStringNotContainsString( 'sk-or-', $json );
+		$this->assertStringNotContainsString( 'api_key', $json );
+		$this->assertStringNotContainsString( 'empty_retry', $json );
+		$this->assertStringNotContainsString( 'prompt_key', $json );
+
+		$decoded = json_decode( $json, true );
+		$this->assertSame(
+			array( 'model', 'messages', 'temperature', 'max_tokens' ),
+			array_keys( $decoded )
+		);
+	}
+}

tests/unit/Core/RerunEligibilityTest.php

@@ -0,0 +1,182 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Rerun_Eligibility (v0.20.0, M3).
+ *
+ * Locks the published-post lockout (CPO guardrail 5 incl. future/private),
+ * the actively-executing-run block, the editable-stage policy, and the
+ * downstream/rebuild set computation that drives stale marking.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class RerunEligibilityTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->wpdb           = $this->create_mock_wpdb();
+		$this->wpdb->options  = 'wp_options';
+		$GLOBALS['wpdb']      = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', array_filter( $args, 'is_scalar' ) ) ) . ' */';
+			}
+		);
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/**
+	 * Wire the mock for: runs table exists, run row with given status,
+	 * generation lock free.
+	 */
+	private function wire_run( string $run_status ): void {
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'SHOW TABLES' ) ) {
+					// Both runs + stage_inputs probes succeed.
+					if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+						return 'wp_prautoblogger_stage_inputs';
+					}
+					return 'wp_prautoblogger_runs';
+				}
+				return null; // Lock option absent -> lock free; seed absent.
+			}
+		);
+		$this->wpdb->method( 'get_row' )->willReturn(
+			array(
+				'run_id'      => 'run-1',
+				'status'      => $run_status,
+				'ceiling_usd' => '0.50',
+			)
+		);
+	}
+
+	/** Stub get_post to return a post with the given status. */
+	private function stub_post( string $status ): void {
+		$post              = new \WP_Post();
+		$post->ID          = 99;
+		$post->post_status = $status;
+		Functions\when( 'get_post' )->justReturn( $post );
+	}
+
+	/**
+	 * Published, scheduled, and private posts are all frozen — no
+	 * edit+rerun (CPO guardrail 5). Draft and pending are not.
+	 */
+	public function test_published_post_lockout_covers_all_frozen_statuses(): void {
+		foreach ( array( 'publish', 'future', 'private' ) as $frozen ) {
+			$post              = new \WP_Post();
+			$post->post_status = $frozen;
+			$this->assertTrue( \PRAutoBlogger_Rerun_Eligibility::post_frozen( $post ), "status {$frozen} must freeze" );
+		}
+		foreach ( array( 'draft', 'pending' ) as $open ) {
+			$post              = new \WP_Post();
+			$post->post_status = $open;
+			$this->assertFalse( \PRAutoBlogger_Rerun_Eligibility::post_frozen( $post ), "status {$open} must not freeze" );
+		}
+		// A run with no post yet is not frozen.
+		$this->assertFalse( \PRAutoBlogger_Rerun_Eligibility::post_frozen( null ) );
+	}
+
+	/**
+	 * check() rejects a published post with the WP-editor redirect copy
+	 * (server-side enforcement, not just hidden UI).
+	 */
+	public function test_check_rejects_published_post(): void {
+		$this->wire_run( 'done' );
+		$this->stub_post( 'publish' );
+
+		$verdict = \PRAutoBlogger_Rerun_Eligibility::check( 'run-1', 99 );
+
+		$this->assertFalse( $verdict['ok'] );
+		$this->assertStringContainsString( 'published', $verdict['reason'] );
+	}
+
+	/**
+	 * check() rejects an actively executing run — "in progress" in the
+	 * CPO sense means unpublished workflow state, not mid-execution.
+	 */
+	public function test_check_rejects_actively_executing_run(): void {
+		$this->wire_run( 'running' );
+		$this->stub_post( 'draft' );
+
+		$verdict = \PRAutoBlogger_Rerun_Eligibility::check( 'run-1', 99 );
+
+		$this->assertFalse( $verdict['ok'] );
+		$this->assertStringContainsString( 'currently executing', $verdict['reason'] );
+	}
+
+	/**
+	 * A terminal run on an unpublished post is eligible: done, failed
+	 * and halted (held) runs can all be re-run.
+	 */
+	public function test_check_accepts_terminal_runs_on_unpublished_posts(): void {
+		foreach ( array( 'done', 'failed', 'halted' ) as $status ) {
+			$wpdb          = $this->create_mock_wpdb();
+			$wpdb->options = 'wp_options';
+			$wpdb->method( 'prepare' )->willReturnCallback( static fn( $sql, ...$a ) => (string) $sql );
+			$wpdb->method( 'get_var' )->willReturnCallback(
+				static function ( $sql ) {
+					return ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) ? 'wp_prautoblogger_runs' : null;
+				}
+			);
+			$wpdb->method( 'get_row' )->willReturn( array( 'status' => $status ) );
+			$GLOBALS['wpdb'] = $wpdb;
+			\PRAutoBlogger_Run_State::flush_cache();
+			$this->stub_post( 'draft' );
+
+			$verdict = \PRAutoBlogger_Rerun_Eligibility::check( 'run-1', 99 );
+			$this->assertTrue( $verdict['ok'], "run status {$status} must be eligible: {$verdict['reason']}" );
+		}
+	}
+
+	/**
+	 * Editable-stage policy: writer chat stages only. review/analysis/
+	 * image stages get the replay affordance refused at the policy layer.
+	 */
+	public function test_editable_stage_policy(): void {
+		foreach ( array( 'outline', 'draft', 'polish' ) as $stage ) {
+			$this->assertTrue( \PRAutoBlogger_Rerun_Eligibility::is_editable_stage( $stage ) );
+		}
+		foreach ( array( 'review', 'publish', 'analysis', 'research', 'llm_research', 'image_a', 'image_b', 'curate' ) as $stage ) {
+			$this->assertFalse( \PRAutoBlogger_Rerun_Eligibility::is_editable_stage( $stage ) );
+		}
+
+		$verdict = \PRAutoBlogger_Rerun_Eligibility::check_replay( 'run-1', 99, 'review', 'editor', 'idea:abc' );
+		$this->assertFalse( $verdict['ok'] );
+	}
+
+	/**
+	 * Downstream/rebuild sets follow the canonical chain — these sets
+	 * drive stale marking and demotion, so order and bounds matter.
+	 */
+	public function test_downstream_and_rebuild_sets(): void {
+		$this->assertSame( array( 'polish', 'review', 'publish' ), \PRAutoBlogger_Rerun_Eligibility::downstream_of( 'draft' ) );
+		$this->assertSame( array( 'publish' ), \PRAutoBlogger_Rerun_Eligibility::downstream_of( 'review' ) );
+		$this->assertSame( array(), \PRAutoBlogger_Rerun_Eligibility::downstream_of( 'publish' ) );
+		$this->assertSame( array(), \PRAutoBlogger_Rerun_Eligibility::downstream_of( 'image_a' ) );
+		$this->assertSame( array( 'review', 'publish' ), \PRAutoBlogger_Rerun_Eligibility::rebuild_set( 'review' ) );
+		$this->assertSame(
+			array( 'outline', 'draft', 'polish', 'review', 'publish' ),
+			\PRAutoBlogger_Rerun_Eligibility::rebuild_set( 'outline' )
+		);
+	}
+}

tests/unit/Core/RerunExecutorTest.php

@@ -0,0 +1,217 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Rerun_Executor + Job_Support (v0.20.0, M3).
+ *
+ * Locks the chained-cron contract (queue() schedules + writes the
+ * queued transient — nothing executes synchronously), the under-lock
+ * re-validation (a post published between click and pickup aborts the
+ * job with ZERO stage mutations), and the terminal-status restore when
+ * the stage demotion fails after the run was reopened.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class RerunExecutorTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	/**
+	 * SQL captured from $wpdb->query().
+	 *
+	 * @var string[]
+	 */
+	private array $queries = array();
+
+	/**
+	 * Transients captured from set_transient().
+	 *
+	 * @var array<int, array>
+	 */
+	private array $transients = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->queries    = array();
+		$this->transients = array();
+		$this->wpdb          = $this->create_mock_wpdb();
+		$this->wpdb->options = 'wp_options';
+		$GLOBALS['wpdb']     = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		Functions\when( 'set_transient' )->alias(
+			function ( $key, $value, $ttl = 0 ) {
+				$this->transients[] = (array) $value;
+				return true;
+			}
+		);
+		// Monthly budget 0 = no limit (fast false path).
+		$this->stub_get_option( array( 'prautoblogger_monthly_budget_usd' => '0' ) );
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** SHOW TABLES probes succeed for every substrate table. */
+	private function tables_exist(): void {
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'SHOW TABLES' ) ) {
+					if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+						return 'wp_prautoblogger_stage_inputs';
+					}
+					if ( false !== strpos( $sql, 'run_stages' ) ) {
+						return 'wp_prautoblogger_run_stages';
+					}
+					return 'wp_prautoblogger_runs';
+				}
+				return null;
+			}
+		);
+	}
+
+	/**
+	 * queue() never executes anything: it schedules a single cron event
+	 * with a uniqueness token appended and broadcasts a 'running' status
+	 * transient so board/dossier polling shows the queued state
+	 * (chained-cron semantics — the CPO hard constraint).
+	 */
+	public function test_queue_schedules_cron_and_broadcasts_queued_state(): void {
+		$scheduled = null;
+		Functions\when( 'wp_schedule_single_event' )->alias(
+			static function ( $ts, $hook, $args ) use ( &$scheduled ) {
+				$scheduled = array(
+					'hook' => $hook,
+					'args' => $args,
+				);
+				return true;
+			}
+		);
+		Functions\when( 'spawn_cron' )->justReturn( true );
+		Functions\when( 'wp_remote_post' )->justReturn( array() );
+		Functions\when( 'site_url' )->justReturn( 'https://example.com' );
+
+		\PRAutoBlogger_Rerun_Job_Support::queue(
+			\PRAutoBlogger_Rerun_Executor::REPLAY_ACTION,
+			array( 'run-1', 99, 'draft', 'writer', 'idea:abc' ),
+			'Queued: re-running Draft…'
+		);
+
+		$this->assertSame( \PRAutoBlogger_Rerun_Executor::REPLAY_ACTION, $scheduled['hook'] );
+		$this->assertCount( 6, $scheduled['args'] ); // 5 args + uniqueness token.
+		$this->assertSame( 'run-1', $scheduled['args'][0] );
+		$this->assertCount( 1, $this->transients );
+		$this->assertSame( 'running', $this->transients[0]['status'] );
+		$this->assertSame( 'Queued: re-running Draft…', $this->transients[0]['stage'] );
+	}
+
+	/**
+	 * Under-lock re-validation: a post published between click and cron
+	 * pickup aborts the replay with an error transient and ZERO
+	 * run_stages mutations (guardrail 5 cannot be raced).
+	 */
+	public function test_replay_job_aborts_on_frozen_post_without_mutations(): void {
+		$this->tables_exist();
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1; // Lock cleanup + acquire succeed.
+			}
+		);
+		$post              = new \WP_Post();
+		$post->ID          = 99;
+		$post->post_status = 'publish';
+		Functions\when( 'get_post' )->justReturn( $post );
+
+		( new \PRAutoBlogger_Rerun_Executor() )->on_replay_job( 'run-1', 99, 'draft', 'writer', 'idea:abc' );
+
+		foreach ( $this->queries as $sql ) {
+			$this->assertStringNotContainsString( 'run_stages', $sql, 'no stage mutation may happen on a frozen post' );
+			$this->assertStringNotContainsString( 'run_id = %s AND status IN', $sql, 'the run must not be reopened' );
+		}
+		$last = end( $this->transients );
+		$this->assertSame( 'error', $last['status'] );
+		$this->assertStringContainsString( 'published', $last['message'] );
+	}
+
+	/**
+	 * When the stage demotion fails after the run was reopened (e.g. the
+	 * row is concurrently 'running'), the previous terminal status is
+	 * restored — the run cannot be left dangling in 'running' for the
+	 * reaper to misread.
+	 */
+	public function test_replay_job_restores_terminal_status_when_restart_fails(): void {
+		$this->tables_exist();
+		$this->wpdb->method( 'get_row' )->willReturnCallback(
+			static function ( $sql ) {
+				$sql = (string) $sql;
+				if ( false !== strpos( $sql, 'stage_inputs' ) ) {
+					return array(
+						'version'      => '2',
+						'request_json' => '{"model":"m","messages":[{"role":"user","content":"edited"}]}',
+					);
+				}
+				return array(
+					'run_id'      => 'run-1',
+					'status'      => 'done',
+					'ceiling_usd' => '0.50',
+				);
+			}
+		);
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$sql             = (string) $sql;
+				$this->queries[] = $sql;
+				if ( false !== strpos( $sql, 'attempt = attempt + 1' ) ) {
+					return 0; // restart() fails — row not demotable.
+				}
+				return 1;
+			}
+		);
+		$post              = new \WP_Post();
+		$post->ID          = 99;
+		$post->post_status = 'draft';
+		Functions\when( 'get_post' )->justReturn( $post );
+
+		( new \PRAutoBlogger_Rerun_Executor() )->on_replay_job( 'run-1', 99, 'draft', 'writer', 'idea:abc' );
+
+		$reopened = false;
+		$restored = false;
+		foreach ( $this->queries as $sql ) {
+			if ( false !== strpos( $sql, "ceiling_usd = %f" ) ) {
+				$reopened = true;
+			}
+			// restore_terminal -> mark_status('done') over the reopened 'running' row.
+			if ( false !== strpos( $sql, 'SET status = %s' ) && false !== strpos( $sql, 'done' )
+				&& false !== strpos( $sql, "status IN ('pending','running')" ) ) {
+				$restored = true;
+			}
+		}
+		$this->assertTrue( $reopened, 'run must have been reopened before restart' );
+		$this->assertTrue( $restored, 'terminal status must be restored after the aborted demotion' );
+		$last = end( $this->transients );
+		$this->assertSame( 'error', $last['status'] );
+	}
+}

tests/unit/Core/RunReaperTest.php

@@ -46,6 +46,13 @@ class RunReaperTest extends BaseTestCase {
 			}
 		);
 		Functions\when( 'apply_filters' )->returnArg( 2 );
+		// wp_date() is called by the reaper's stuck-sweep cutoff (v0.22.1 TZ fix).
+		// Alias to gmdate() so tests remain timezone-agnostic.
+		Functions\when( 'wp_date' )->alias(
+			static function ( string $format, ?int $timestamp = null ): string {
+				return gmdate( $format, null !== $timestamp ? $timestamp : time() );
+			}
+		);
 		\PRAutoBlogger_Run_State::flush_cache();
 		\PRAutoBlogger_Run_Stage_State::flush_cache();
 	}

tests/unit/Core/RunStageRerunStateTest.php

@@ -0,0 +1,185 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Run_Stage_Writes (M3 done() delta) and
+ * PRAutoBlogger_Run_Stage_Rerun_State (operator-action mutations).
+ *
+ * Locks: fresh done() clears stale but never touches human_modified;
+ * the half-migrated-schema self-heal retry; restart() demotion rules
+ * (never from 'running', human_modified is sticky); mark_stale() flags
+ * only 'done' rows; demote_to_pending() preserves audit columns.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class RunStageRerunStateTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	/**
+	 * SQL captured from $wpdb->query().
+	 *
+	 * @var string[]
+	 */
+	private array $queries = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->queries   = array();
+		$this->wpdb      = $this->create_mock_wpdb();
+		$GLOBALS['wpdb'] = $this->wpdb;
+		$this->wpdb->method( 'get_var' )->willReturn( 'wp_prautoblogger_run_stages' );
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_Stage_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Capture queries, all succeeding. */
+	private function capture_queries(): void {
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+	}
+
+	/**
+	 * done() writes stale = 0 on both INSERT and duplicate-key paths and
+	 * never references human_modified (sticky audit — set only by
+	 * Rerun_State::restart()).
+	 */
+	public function test_done_clears_stale_and_never_touches_human_modified(): void {
+		$this->capture_queries();
+
+		\PRAutoBlogger_Run_Stage_State::done( 'run-1', 'draft', '', 'idea:abc', 'output text', 0.01 );
+
+		$this->assertCount( 1, $this->queries );
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( 'stale', $sql );
+		$this->assertStringContainsString( 'stale = 0', $sql );
+		$this->assertStringNotContainsString( 'human_modified', $sql );
+	}
+
+	/**
+	 * Half-migrated schema (no stale column yet): the failed write is
+	 * retried with the pre-v0.20.0 statement — the resume checkpoint is
+	 * never lost (Cost_Tracker v0.18.0 retry pattern).
+	 */
+	public function test_done_self_heals_on_missing_stale_column(): void {
+		$calls = 0;
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) use ( &$calls ) {
+				$this->queries[] = (string) $sql;
+				++$calls;
+				return 1 === $calls ? false : 1; // First write fails (unknown column).
+			}
+		);
+
+		\PRAutoBlogger_Run_Stage_State::done( 'run-1', 'draft', '', 'idea:abc', 'output', 0.01 );
+
+		$this->assertCount( 2, $this->queries );
+		$this->assertStringContainsString( 'stale', $this->queries[0] );
+		$this->assertStringNotContainsString( 'stale', $this->queries[1] );
+		$this->assertStringContainsString( "status = 'done'", $this->queries[1] );
+	}
+
+	/**
+	 * restart() demotes terminal/pending rows only — a 'running' row can
+	 * never be restarted (the WHERE excludes it), the attempt counter is
+	 * bumped, stale clears, and human_modified can only be raised
+	 * (IF(...,1,human_modified)), never reset.
+	 */
+	public function test_restart_rules(): void {
+		$this->capture_queries();
+
+		$ok = \PRAutoBlogger_Run_Stage_Rerun_State::restart( 'run-1', 'draft', 'writer', 'idea:abc', true );
+
+		$this->assertTrue( $ok );
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( "status = 'running'", $sql );
+		$this->assertStringContainsString( 'attempt = attempt + 1', $sql );
+		$this->assertStringContainsString( 'stale = 0', $sql );
+		$this->assertStringContainsString( 'IF(%d = 1, 1, human_modified)', $sql );
+		$this->assertStringContainsString( "IN ('done','failed','halted','pending')", $sql );
+		$this->assertStringNotContainsString( "'running')", str_replace( "status = 'running'", '', $sql ) );
+	}
+
+	/**
+	 * restart() reports false when no row matched (e.g. concurrently
+	 * running stage) so the executor can abort cleanly.
+	 */
+	public function test_restart_returns_false_when_no_row_demoted(): void {
+		$this->wpdb->method( 'query' )->willReturn( 0 );
+
+		$this->assertFalse(
+			\PRAutoBlogger_Run_Stage_Rerun_State::restart( 'run-1', 'draft', 'writer', 'idea:abc', false )
+		);
+	}
+
+	/**
+	 * mark_stale() flags only 'done' rows of the given stages — pending/
+	 * failed rows are not "stale", they are simply not run. Nothing is
+	 * demoted (no status write): guardrail 3's no-silent-auto-rerun holds
+	 * by construction.
+	 */
+	public function test_mark_stale_targets_done_rows_only_and_never_demotes(): void {
+		$this->capture_queries();
+
+		$count = \PRAutoBlogger_Run_Stage_Rerun_State::mark_stale( 'run-1', 'idea:abc', array( 'polish', 'review', 'publish' ) );
+
+		$this->assertSame( 1, $count );
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( 'SET stale = 1', $sql );
+		$this->assertStringContainsString( "status = 'done'", $sql );
+		$this->assertStringContainsString( 'IN (%s,%s,%s)', $sql );
+		$this->assertStringNotContainsString( "SET status", $sql );
+	}
+
+	/**
+	 * demote_to_pending() sets pending+stale, keeps meta_json/attempt/
+	 * human_modified untouched (audit survives), and never touches a
+	 * 'running' row.
+	 */
+	public function test_demote_to_pending_preserves_audit_columns(): void {
+		$this->capture_queries();
+
+		\PRAutoBlogger_Run_Stage_Rerun_State::demote_to_pending( 'run-1', 'idea:abc', array( 'review', 'publish' ) );
+
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( "SET status = 'pending', stale = 1", $sql );
+		$this->assertStringContainsString( "status != 'running'", $sql );
+		$this->assertStringNotContainsString( 'meta_json', $sql );
+		$this->assertStringNotContainsString( 'attempt', $sql );
+		$this->assertStringNotContainsString( 'human_modified', $sql );
+	}
+
+	/**
+	 * Empty stage lists and missing tables degrade to 0 / no queries.
+	 */
+	public function test_noop_paths(): void {
+		$this->capture_queries();
+
+		$this->assertSame( 0, \PRAutoBlogger_Run_Stage_Rerun_State::mark_stale( 'run-1', 'i', array() ) );
+		$this->assertSame( 0, \PRAutoBlogger_Run_Stage_Rerun_State::demote_to_pending( '', 'i', array( 'draft' ) ) );
+		$this->assertCount( 0, $this->queries );
+	}
+}

tests/unit/Core/RunStateReopenTest.php

@@ -0,0 +1,102 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Run_State::reopen() (v0.20.0, M3).
+ *
+ * Locks: terminal-only atomic gate, ceiling re-snapshot from the
+ * CURRENT setting, and — critical for CPO guardrail 4 — that the
+ * accumulated reserved/settled spend is never reset, so re-runs are
+ * new spend on the same run ledger.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class RunStateReopenTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	/**
+	 * SQL captured from $wpdb->query().
+	 *
+	 * @var string[]
+	 */
+	private array $queries = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->queries   = array();
+		$this->wpdb      = $this->create_mock_wpdb();
+		$GLOBALS['wpdb'] = $this->wpdb;
+		$this->wpdb->method( 'get_var' )->willReturn( 'wp_prautoblogger_runs' );
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		$this->stub_get_option( array( 'prautoblogger_per_run_cost_ceiling_usd' => '0.75' ) );
+		\PRAutoBlogger_Run_State::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Run_State::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/**
+	 * reopen() transitions ONLY terminal runs (atomic conditional UPDATE)
+	 * and re-snapshots the ceiling from the current setting.
+	 */
+	public function test_reopen_gates_on_terminal_status_and_resnapshots_ceiling(): void {
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+
+		$this->assertTrue( \PRAutoBlogger_Run_State::reopen( 'run-1' ) );
+
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( "SET status = 'running'", $sql );
+		$this->assertStringContainsString( "status IN ('done','failed','halted')", $sql );
+		$this->assertStringContainsString( 'ceiling_usd = %f', $sql );
+		$this->assertStringContainsString( '0.75', $sql ); // Current setting value.
+		$this->assertStringContainsString( 'finished_at = NULL', $sql );
+		// Guardrail 4: accumulated spend is NEVER reset by a reopen.
+		$this->assertStringNotContainsString( 'reserved_usd', $sql );
+		$this->assertStringNotContainsString( 'settled_usd', $sql );
+		$this->assertStringNotContainsString( 'overage_usd', $sql );
+	}
+
+	/**
+	 * No row matched (run is pending/running or absent) -> false, so the
+	 * executor aborts instead of replaying against a closed gate.
+	 */
+	public function test_reopen_returns_false_when_not_terminal(): void {
+		$this->wpdb->method( 'query' )->willReturn( 0 );
+
+		$this->assertFalse( \PRAutoBlogger_Run_State::reopen( 'run-1' ) );
+	}
+
+	/**
+	 * Self-healing: missing table / empty run id -> false, no query.
+	 */
+	public function test_reopen_noop_paths(): void {
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+
+		$this->assertFalse( \PRAutoBlogger_Run_State::reopen( '' ) );
+		$this->assertCount( 0, $this->queries );
+	}
+}

tests/unit/Core/StageInputStoreTest.php

@@ -0,0 +1,193 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Stage_Input_Store (v0.20.0, M3).
+ *
+ * Locks the INSERT-only immutability contract (fork saves create new
+ * versions, nothing is ever updated), seed persist-once semantics, the
+ * retention prune scope (human bodies only, seeds kept), and the
+ * self-healing missing-table degradation.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class StageInputStoreTest extends BaseTestCase {
+
+	/**
+	 * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb.
+	 */
+	private $wpdb;
+
+	/**
+	 * Rows captured from $wpdb->insert().
+	 *
+	 * @var array<int, array<string, mixed>>
+	 */
+	private array $inserted = array();
+
+	/**
+	 * SQL captured from $wpdb->query().
+	 *
+	 * @var string[]
+	 */
+	private array $queries = array();
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->inserted  = array();
+		$this->queries   = array();
+		$this->wpdb      = $this->create_mock_wpdb();
+		$GLOBALS['wpdb'] = $this->wpdb;
+		$this->wpdb->method( 'prepare' )->willReturnCallback(
+			static function ( $sql, ...$args ) {
+				if ( 1 === count( $args ) && is_array( $args[0] ) ) {
+					$args = $args[0];
+				}
+				return $sql . ' /* ' . implode( ',', array_map( 'strval', $args ) ) . ' */';
+			}
+		);
+		$this->wpdb->method( 'insert' )->willReturnCallback(
+			function ( $table, $row ) {
+				$this->inserted[] = (array) $row;
+				return 1;
+			}
+		);
+		$this->wpdb->method( 'query' )->willReturnCallback(
+			function ( $sql ) {
+				$this->queries[] = (string) $sql;
+				return 1;
+			}
+		);
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+	}
+
+	protected function tearDown(): void {
+		\PRAutoBlogger_Stage_Input_Store::flush_cache();
+		unset( $GLOBALS['wpdb'] );
+		parent::tearDown();
+	}
+
+	/** Make the availability probe succeed. */
+	private function table_exists(): void {
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				if ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) {
+					return 'wp_prautoblogger_stage_inputs';
+				}
+				return null; // MAX(version) on an empty scope.
+			}
+		);
+	}
+
+	/**
+	 * First fork for a scope gets version 1 via INSERT — and the write
+	 * path is INSERT-only: no UPDATE statement may ever be issued.
+	 */
+	public function test_save_fork_inserts_version_one_and_never_updates(): void {
+		$this->table_exists();
+
+		$version = \PRAutoBlogger_Stage_Input_Store::save_fork(
+			'run-1',
+			'draft',
+			'writer',
+			'idea:abc',
+			'{"model":"m","messages":[]}',
+			'rhys'
+		);
+
+		$this->assertSame( 1, $version );
+		$this->assertCount( 1, $this->inserted );
+		$row = $this->inserted[0];
+		$this->assertSame( 'human', $row['source'] );
+		$this->assertSame( 1, $row['version'] );
+		$this->assertSame( 'rhys', $row['author'] );
+		// Immutability: the store issued no UPDATE of any kind.
+		foreach ( $this->queries as $sql ) {
+			$this->assertStringNotContainsString( 'UPDATE', $sql );
+		}
+	}
+
+	/**
+	 * The next fork for the same scope gets MAX(version)+1 — the original
+	 * version row is never overwritten (CPO guardrail 1).
+	 */
+	public function test_save_fork_increments_version_from_existing_max(): void {
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) {
+				if ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) {
+					return 'wp_prautoblogger_stage_inputs';
+				}
+				return '3'; // Existing max version.
+			}
+		);
+
+		$version = \PRAutoBlogger_Stage_Input_Store::save_fork( 'run-1', 'draft', 'writer', 'idea:abc', '{}', 'rhys' );
+
+		$this->assertSame( 4, $version );
+		$this->assertSame( 4, $this->inserted[0]['version'] );
+	}
+
+	/**
+	 * Seed persists once: a second save for the same item is a no-op
+	 * (idempotent worker resume).
+	 */
+	public function test_save_seed_is_insert_once(): void {
+		$seeded = false;
+		$this->wpdb->method( 'get_var' )->willReturnCallback(
+			static function ( $sql ) use ( &$seeded ) {
+				if ( false !== strpos( (string) $sql, 'SHOW TABLES' ) ) {
+					return 'wp_prautoblogger_stage_inputs';
+				}
+				if ( false !== strpos( (string) $sql, 'SELECT request_json' ) ) {
+					return $seeded ? '{"topic":"t"}' : null;
+				}
+				return null;
+			}
+		);
+
+		\PRAutoBlogger_Stage_Input_Store::save_seed( 'run-1', 'idea:abc', '{"topic":"t"}' );
+		$seeded = true;
+		\PRAutoBlogger_Stage_Input_Store::save_seed( 'run-1', 'idea:abc', '{"topic":"other"}' );
+
+		$this->assertCount( 1, $this->inserted );
+		$this->assertSame( 'seed', $this->inserted[0]['source'] );
+		$this->assertSame( '', $this->inserted[0]['stage'] );
+	}
+
+	/**
+	 * Retention prune targets ONLY human fork bodies — the WHERE clause
+	 * pins source='human', so seed rows survive (re-run-from-here keeps
+	 * working for the life of the run).
+	 */
+	public function test_prune_targets_human_bodies_only(): void {
+		$this->table_exists();
+
+		\PRAutoBlogger_Stage_Input_Store::prune_human_bodies( '2026-05-29 00:00:00' );
+
+		$this->assertCount( 1, $this->queries );
+		$sql = $this->queries[0];
+		$this->assertStringContainsString( 'SET request_json = NULL', $sql );
+		$this->assertStringContainsString( "source = %s", $sql );
+		$this->assertStringContainsString( 'human', $sql );
+		$this->assertStringNotContainsString( "seed", $sql );
+	}
+
+	/**
+	 * Missing table (half-migrated schema): every method degrades to a
+	 * silent no-op / null — never a query, never a notice.
+	 */
+	public function test_missing_table_degrades_to_noop(): void {
+		$this->wpdb->method( 'get_var' )->willReturn( null );
+
+		$this->assertNull( \PRAutoBlogger_Stage_Input_Store::save_fork( 'r', 'draft', 'w', 'i', '{}', 'a' ) );
+		\PRAutoBlogger_Stage_Input_Store::save_seed( 'r', 'i', '{}' );
+		$this->assertNull( \PRAutoBlogger_Stage_Input_Store::get_seed( 'r', 'i' ) );
+		$this->assertNull( \PRAutoBlogger_Stage_Input_Store::latest_fork( 'r', 'draft', 'w', 'i' ) );
+		$this->assertSame( 0, \PRAutoBlogger_Stage_Input_Store::prune_human_bodies( '2026-05-29 00:00:00' ) );
+		$this->assertCount( 0, $this->inserted );
+		$this->assertCount( 0, $this->queries );
+	}
+}

tests/unit/Core/StageReplayTest.php

@@ -0,0 +1,157 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Stage_Replay (v0.20.0, M3).
+ *
+ * Locks the body -> options inverse transform (the replay must
+ * round-trip through Request_Builder::build_body() to the SAME wire
+ * shape, including the v0.18.1 reasoning headroom) and the decode
+ * validation that guards the replay path against non-chat payloads.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+
+class StageReplayTest extends BaseTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		// Builder reads the global reasoning setting; pin it OFF here and
+		// flip it in the drift test below.
+		$this->stub_get_option( array( 'prautoblogger_reasoning_enabled' => '0' ) );
+	}
+
+	/**
+	 * Round-trip: a body WITHOUT reasoning replayed through build_body()
+	 * reproduces the original wire shape byte-for-byte.
+	 */
+	public function test_round_trip_without_reasoning(): void {
+		$original = array(
+			'model'       => 'google/gemini-2.5-flash-lite',
+			'messages'    => array(
+				array( 'role' => 'system', 'content' => 'sys' ),
+				array( 'role' => 'user', 'content' => 'edited prompt' ),
+			),
+			'temperature' => 0.7,
+			'max_tokens'  => 4000,
+		);
+
+		$options = \PRAutoBlogger_Stage_Replay::options_from_body( $original, 'draft' );
+		$rebuilt = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )->build_body(
+			$original['messages'],
+			$original['model'],
+			$options
+		);
+
+		// The explicit reasoning-off pin is the only permitted delta
+		// (same shape the empty-completion retry sends upstream).
+		$this->assertSame( array( 'enabled' => false ), $rebuilt['reasoning'] );
+		unset( $rebuilt['reasoning'] );
+		$this->assertSame( $original, array_merge( array( 'model' => $original['model'], 'messages' => $original['messages'] ), $rebuilt ) );
+		$this->assertSame( 4000, $rebuilt['max_tokens'] );
+	}
+
+	/**
+	 * Round-trip WITH reasoning: the stored body's max_tokens carries the
+	 * builder's +cap headroom; the inverse subtracts it so the rebuilt
+	 * body is identical (headroom applied once, never compounded).
+	 */
+	public function test_round_trip_with_reasoning_headroom(): void {
+		$original = array(
+			'model'      => 'deepseek/deepseek-v4-flash',
+			'messages'   => array( array( 'role' => 'user', 'content' => 'p' ) ),
+			'max_tokens' => 6048, // Caller asked 4000; builder added the 2048 cap.
+			'reasoning'  => array(
+				'enabled'    => true,
+				'max_tokens' => 2048,
+			),
+		);
+
+		$options = \PRAutoBlogger_Stage_Replay::options_from_body( $original, 'draft' );
+		$this->assertSame( 4000, $options['max_tokens'] );
+
+		$rebuilt = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )->build_body(
+			$original['messages'],
+			$original['model'],
+			$options
+		);
+
+		$this->assertSame( 6048, $rebuilt['max_tokens'] );
+		$this->assertSame( $original['reasoning'], $rebuilt['reasoning'] );
+	}
+
+	/**
+	 * Global-setting drift cannot reshape a replay: even with reasoning
+	 * globally ENABLED, a body stored without reasoning replays with the
+	 * explicit off-pin (build_body honours the per-call override).
+	 */
+	public function test_global_reasoning_drift_cannot_leak_into_replay(): void {
+		$this->stub_get_option(
+			array(
+				'prautoblogger_reasoning_enabled' => '1',
+				'prautoblogger_reasoning_effort'  => 'high',
+			)
+		);
+
+		$body    = array(
+			'model'      => 'google/gemini-2.5-flash-lite',
+			'messages'   => array( array( 'role' => 'user', 'content' => 'p' ) ),
+			'max_tokens' => 1000,
+		);
+		$options = \PRAutoBlogger_Stage_Replay::options_from_body( $body, 'polish' );
+		$rebuilt = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )->build_body( $body['messages'], $body['model'], $options );
+
+		$this->assertSame( array( 'enabled' => false ), $rebuilt['reasoning'] );
+		$this->assertSame( 1000, $rebuilt['max_tokens'] ); // No headroom added.
+	}
+
+	/**
+	 * Caller metadata (stage/prompt_key) rides options for the guard's
+	 * audit rows but never reaches the wire body.
+	 */
+	public function test_options_carry_stage_metadata_not_sent_upstream(): void {
+		$body    = array(
+			'model'    => 'm',
+			'messages' => array( array( 'role' => 'user', 'content' => 'p' ) ),
+		);
+		$options = \PRAutoBlogger_Stage_Replay::options_from_body( $body, 'draft' );
+
+		$this->assertSame( 'draft', $options['stage'] );
+		$this->assertSame( 'content.draft', $options['prompt_key'] );
+
+		$rebuilt = ( new \PRAutoBlogger_OpenRouter_Request_Builder() )->build_body( $body['messages'], $body['model'], $options );
+		$this->assertArrayNotHasKey( 'stage', $rebuilt );
+		$this->assertArrayNotHasKey( 'prompt_key', $rebuilt );
+	}
+
+	/**
+	 * decode_body() accepts only well-formed chat bodies — model string +
+	 * non-empty role/content message list. Everything else returns null
+	 * (the executor aborts cleanly instead of replaying garbage).
+	 */
+	public function test_decode_body_validation(): void {
+		$valid = wp_json_encode(
+			array(
+				'model'    => 'm',
+				'messages' => array( array( 'role' => 'user', 'content' => 'p' ) ),
+			)
+		);
+		$this->assertIsArray( \PRAutoBlogger_Stage_Replay::decode_body( (string) $valid ) );
+
+		$invalid = array(
+			'not json at all',
+			'"just a string"',
+			'{"messages":[{"role":"user","content":"p"}]}',           // No model.
+			'{"model":"m"}',                                           // No messages.
+			'{"model":"m","messages":[]}',                             // Empty messages.
+			'{"model":"m","messages":["plain string"]}',               // Malformed message.
+			'{"model":"m","messages":[{"role":"user"}]}',              // No content.
+			'{"model":"m","messages":[{"role":1,"content":"p"}]}',     // Non-string role.
+		);
+		foreach ( $invalid as $payload ) {
+			$this->assertNull( \PRAutoBlogger_Stage_Replay::decode_body( $payload ), "must reject: {$payload}" );
+		}
+	}
+}