` (unchanged from v0.19.2 --
deep-link URLs are parent-agnostic). Secured by `manage_options` capability. Static
`url_for_post(int $post_id): string` provides the canonical deep-link.
v0.19.2 used `prautoblogger-settings` as parent with post-registration `unset($submenu[...])` to
hide the page. This caused `get_admin_page_parent()` to fail at request time -> orphan
`admin_page_*` hookname -> no handler registered -> `wp_die(403)`. Fixed in v0.19.3 by switching
to `options.php` parent and removing all `$submenu` mutation. See CONVENTIONS.md §Hidden Admin
Pages for the full rule and ARCHITECTURE.md §22b for both incident records.
Regression test: `tests/unit/Admin/DossierMenuRegistrationTest.php` -- the
`test_request_time_hookname_matches_registration_hookname` test replicates the request-time
resolution algorithm (simulate `get_admin_page_parent()`) so it FAILS on hide-by-unset and
PASSES on options.php-parent.
**5-query data assembly** (`class-dossier-data-assembler.php`):
```
1. wp_prautoblogger_runs WHERE run_id = %s -- 1 row (run metadata)
2. wp_prautoblogger_run_stages WHERE run_id = %s -- N rows (per-stage status/cost)
3. wp_prautoblogger_generation_log WHERE run_id = %s -- N rows (model/pv/tokens/request)
4. wp_prautoblogger_run_decisions WHERE run_id = %s -- N rows (editorial rationale)
5. get_post_meta($post_id) -- WP object cache hit
```
All queries are keyed on `run_id` (indexed). No N+1. Stage output is reconstructed from
`run_stages.meta_json → json_decode → meta['output']` (same path as `Run_Stage_State::
get_output()`). The dossier assembler does NOT call `Run_Stage_State` directly; it performs
its own raw queries so the view is not coupled to the cache layer.
**Legacy graceful state (binding 5):** Posts published before v0.18.0 (no runs/run_stages
rows) and posts where `_prautoblogger_run_id` is absent or blank return `['has_run' => false]`.
The template renders a clean "No generation record for this article" notice. No PHP notices
or fatals.
**Amortized research rows:** `generation_log` rows with `prompt_version = NULL` and
`agent_role = ''` (from the `llm_research` stage orphan-reaper path) are rendered with
model shown as "—" and no raw-trace toggle (request_json may be NULL). No fatal/notice.
**Raw-trace security (binding 4):** `request_json` stores the OpenRouter request body —
model identifier, messages array, temperature. Authorization headers are never logged (the
outbound HTTP client strips them before logging, per the original architecture decision on
`wp_prautoblogger_generation_log`). The dossier template renders `request_json` via
`esc_html()` inside a `` block. All model-generated text rendered via `wp_kses_post()`
(rendered view) or `esc_html()` (raw trace). Both paths treat content as untrusted HTML.
**File naming note:** `PRAutoBlogger_DB_Migrations` is loaded via explicit `require_once`
in `prautoblogger.php` (not the autoloader). The autoloader converts `DB_Migrations` to the
kebab segment `d-b-migrations`, producing `class-d-b-migrations.php` — which does not match
the file `class-db-migrations.php`. Explicit loading is the canonical pattern for classes
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.
| Plugin | Default Models | Typical Daily Spend | Budget Control |
|--------|---------------|--------------------:|----------------|
| PRAutoBlogger | Gemini 2.5 Flash Lite (analysis + editing), Claude Sonnet 4 (writing) | $0.05–$0.30 depending on article count | Hard-stop monthly budget in plugin settings |
| Peptide News | Google Gemini 2.0 Flash (keywords + summaries) | $0.01–$0.05 | No hard budget yet (planned) |
**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 |
| DB option | `prautoblogger_editorial_max_rounds` | Max editorial loop rounds (int, default 3, range 1–10). P2b.2 (v0.29.0). |
### 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.