Rework durable Background Review around upstream review primitives #231

Finish Line

Codex Lab retains durable Background Review as an Every Code product capability, but the implementation is rebuilt as a thin scheduler/artifact layer on top of upstream manual Review, Approval Review/Guardian, hooks, and bounded context primitives instead of carrying the current forked review runtime unchanged.

Current Status

State: later Background Review thinning owner; the obsolete dependency on future milestone-8 work is removed. #909/#911 remain closed. #927/#928 measure convergence first, and #787 remains the protected instruction-delivery product slice.

Research #926 is incorporated as open hook feasibility questions. Preserve the thin scheduler/artifact objective, native fallback contracts, worktree coordination #318, immutable snapshots #572, terminology #303 and distinct Guardian/manual review/Validation semantics.

Next action when promoted: choose a measured small thinning slice from actual repair or dogfood evidence. No second review engine or wholesale unmodified-runtime replacement is qualified. #149 owns generic quality-hook lifecycle; #895 remains independent bounded fingerprint hardening. Last verified: September 16, 2026.

Priority clarification after the resumed convergence decision: #787 instruction delivery remains the next protected product slice after #928, before promoting broad extraction or Background Review thinning.

Acceptance Criteria

• Upstream-owned manual Review files are restored or minimized toward upstream shapes wherever possible.
• The local durable Background Review layer has a bounded data model: run id, source, target fingerprint, status, model, timestamps, bounded rendered findings, and raw detail with hard caps.
• Background scheduling uses captured completed-turn diffs and upstream ReviewTarget::Custom or an equivalent supported target, not a competing manual-review protocol fork.
• Model-visible awareness is implemented only as a bounded ContextualUserFragment and follows Codex Lab code-review context rules.
• App-server summary/detail/control APIs are retained only if TUI/WebUI/client needs justify them after upstream sync.
• Quality gates are mapped to upstream hooks where that preserves behavior.
• Approval Review/Guardian remains approval and safety review, not the general code-review findings engine.
• Product surfaces consistently use the Adopt Background Review terminology across product surfaces #303 terminology while preserving compatibility-sensitive wire and storage identifiers.
• Future upstream review/hook branches are watched as inputs but are not treated as landed mainline dependencies.

Relationships

• Post-release product workstream under Launch Codex Lab and establish post-cutover roadmap #498; historically decomposed from closed Upstream sync and Codex Lab feature reclassification #229.
• Completed child: Preserve Background Review across same-turn commits #302 same-turn Background Review lifecycle repair.
• Open children: Adopt Background Review terminology across product surfaces #303 terminology and compatibility migration; Share Background Review coordination across linked worktrees #318 linked-worktree coordination.
• Sync Codex Lab with current openai/codex substrate #230 is the related continuous upstream-maintenance lane, not a current blocker.
• Make Background Review trustworthy for daily dogfood #570 is the completed daily-dogfood reliability baseline.
• Run Background Review in an immutable snapshot worktree #572 is a separate deferred immutable-snapshot isolation improvement.

Research incorporated from #926

Upstream async hooks exist, but only synchronous handlers can apply turn-control effects. Blocking Stop feedback can request continuation; an async reviewer needs a separately proven result-delivery path.

A future hook-based review trial must account for exact revision targeting, persistence/resume, deduplication/stale suppression, cancellation, bounded findings, complete applicable instructions and reliable desktop/mobile surfacing. A status-cell loss is not the full lifecycle tradeoff. Verify the exact released binary, since upstream main can expose features absent from a release.

These are open research notes, not new blockers for existing #787/product work or mandatory spikes before this issue may advance. No plugin is enabled by this plan; #926 closes only as superseded.