feat: add resumable review threads to /codex:review and /codex:adversarial-review

[rrva]

Opt-in, non-breaking feature: lets an iterative review → fix → re-review loop reuse a Codex review thread instead of re-exploring the repo cold on every pass, which sharply cuts token/quota burn.

Summary

• Adds --resume, --fresh, and --within-hours <n> to /codex:review and /codex:adversarial-review.
• --resume reuses-or-creates: it reuses this git worktree's recent review thread if one exists, and otherwise starts a fresh resumable thread — safe to use on every review, never has to be seeded with --fresh.
• Reuse is scoped to the git worktree and bounded by recency (default 3h, override with --within-hours).
• --fresh forces a new thread for the worktree (discard prior context).
• Default (no-flag) behavior is byte-identical to before — /codex:review still uses the native one-shot reviewer and the no-flag prompt is unchanged. The change is purely additive (new flags only).

Why turn-based, and why prompts/review.md is included

Native review/start spawns a fresh reviewer task each run (in openai/codex, codex-rs/core/src/tasks/review.rs seeds it with initial_history: None), so it can't carry context between runs — resume fundamentally requires a turn/start instead, and a turn needs a prompt. /codex:adversarial-review already has one (prompts/adversarial-review.md); plain /codex:review did not, because its reviewer is Codex's built-in one.

So prompts/review.md is the prompt for the resumable plain-review path only. It is adapted from Codex's own native reviewer system prompt (codex-rs/core/review_prompt.md) — same bug-flagging rubric, the same P0–P3 priorities, the same overall-correctness verdict — with only the output section remapped to this plugin's schemas/review-output.schema.json. The intent is for /codex:review --resume to review as much like native /codex:review as a structured turn allows. It can't be identical: the native reviewer's rubric is injected as the review thread's base_instructions, which a normal turn/start can't set, so the rubric is carried in the turn prompt instead.

On this repo's own diff (measured runs), the resumed pass re-explored only a fraction of the repo — roughly 1–10 exploration commands vs 26–35 for the cold pass — and finished several× faster.

Changes

• scripts/lib/codex.mjs: persistent review-thread naming; opt-in resumeFallback in runAppServerTurn (start a fresh thread if a pruned/expired thread can't be resumed — resume fails before any turn starts, so no tokens are wasted). The prompt is built from the actual outcome, so a fresh-fallback thread is never told to reuse context it doesn't have.
• scripts/codex-companion.mjs: parse --resume/--fresh/--within-hours; worktree-scoped, recency-bounded thread resolution that only selects persisted session-mode review jobs. Native one-shot review jobs persist a thread id too, but those threads are ephemeral, so they are tagged non-resumable and never selected.
• prompts/review.md: the resumable plain-review prompt, adapted from Codex's native review_prompt.md (see above). The resume continuation note is injected programmatically only when resuming, so the no-flag path is unaffected.
• commands/review.md, commands/adversarial-review.md: document the flags.

A cleaner long-term fix (in Codex itself)

This plugin-side prompt would be unnecessary if native review could carry context — and the machinery already exists upstream. run_codex_thread_one_shot accepts initial_history: Option<InitialHistory> with Resumed/Forked variants (used by normal thread resume), but the review task always passes None (codex-rs/core/src/tasks/review.rs). A small change to openai/codex would make native review resumable:

1. add an optional resume reference to ReviewStartParams (clients already receive a reviewThreadId from a detached review);
2. persist detached review threads' rollouts;
3. when resuming, load that rollout and pass InitialHistory::Resumed(...) instead of None, keeping base_instructions = REVIEW_PROMPT and appending the new per-target prompt.

That would give native review context reuse for every client. After it lands, /codex:review --resume here collapses to a native review/start call, and prompts/review.md plus the whole turn-based plain-review path can be deleted. I'm happy to open that PR against openai/codex as well.

Test plan

• npm test — green. New coverage: tests/commands.test.mjs (flag surface on both commands) and tests/runtime.test.mjs (--fresh→--resume reuse, recency fallback, native-thread exclusion, pruned-thread fallback).
• npm run build (tsc) — green.

Not in scope

• No version bump or CHANGELOG entry (left to the maintainer release flow).
• Default behavior is unchanged; reuse is strictly opt-in.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2214d4db27

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2921634835

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 217572a3a6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[rrva]

Both Codex review findings are addressed as of 217572a:

• Restrict resume candidates to completed jobs — resolveLatestReviewThread now selects the newest resumable review run that reached a thread and reuses it only if that run completed, so a cancelled/failed/in-progress run is never resumed (and it does not fall back past a newer interrupted run to an older completed run that shares the same thread id).
• Each fix has a regression test in tests/runtime.test.mjs.

For reviewer context: the change is opt-in and non-breaking — --resume / --fresh / --within-hours are added to /codex:review and /codex:adversarial-review, and the default no-flag behavior is byte-identical (native one-shot reviewer, unchanged prompt). npm test and npm run build are green.

The PR description also sketches a small upstream openai/codex change (make native review resumable by threading a resume id into ReviewStartParams and passing InitialHistory::Resumed instead of None in codex-rs/core/src/tasks/review.rs). If that lands, /codex:review --resume here collapses to a native review/start call and prompts/review.md plus the turn-based plain-review path can be deleted — happy to open that PR too.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57db7b6027

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".