orch/engine/

review.rs

//! PR review pipeline — review agent orchestration.
//!
//! This module handles running the review agent on completed tasks, parsing its
//! decision, and posting automated review comments.
//!
//! Related modules:
//! - [`super::review_poll`] — polling open PRs for human review feedback
//! - [`super::auto_merge`] — merging approved PRs and handling change requests

/// Maximum consecutive review agent failures before the task is blocked
/// for human intervention. Exported so `tick` and `sync` use the same threshold.
pub(crate) const MAX_REVIEW_AGENT_FAILURES: u64 = 3;

/// Maximum consecutive PR-creation failures before blocking the task.
const MAX_PR_CREATE_FAILURES: u64 = 3;

/// Map an [`AgentError`] to the structured outcome string stored in `task_runs.outcome`.
///
/// Mirrors the logic in `runner::classify_run_outcome` so review runs carry the
/// same outcome fidelity as agent runs.
fn outcome_for_agent_error(err: &runner::agents::AgentError) -> &'static str {
    match err {
        runner::agents::AgentError::Timeout { .. } => "timeout",
        runner::agents::AgentError::Interrupted { .. } => "interrupted",
        // Consult credit-exhaustion detection first — generic rate-limit patterns
        // (e.g. "usage limit") also match billing-cycle exhaustion messages, so
        // reviews on a billing-cycle-exhausted model must not be stored as a
        // plain "rate_limit"/"auth_error" outcome (issue #3529).
        runner::agents::AgentError::RateLimit { message } => {
            crate::engine::cooldown::detect_credit_exhaustion_outcome(message)
                .unwrap_or("rate_limit")
        }
        runner::agents::AgentError::Auth { message } => {
            crate::engine::cooldown::detect_credit_exhaustion_outcome(message)
                .unwrap_or("auth_error")
        }
        runner::agents::AgentError::InvalidResponse { .. } => "parse_error",
        _ => "failed",
    }
}

/// Format an [`AgentError`] as the compact string persisted to `task_runs.error`
/// and surfaced via [`ReviewDecision::Failed`].
///
/// Mirrors the per-variant formatting in `runner::fallback::handle_error` so review
/// runs never leak raw provider payloads (e.g. truncated `api_retry` NDJSON
/// fragments) into the audit trail. Without this, `err.to_string()` would expand
/// `AgentError::RateLimit { message }` via its `Display` impl and persist hundreds
/// of bytes of raw JSON into `task_runs.error` (issue #3149, regression of #2881).
fn format_review_error(agent: &str, err: &runner::agents::AgentError) -> String {
    match err {
        runner::agents::AgentError::RateLimit { message } => format!(
            "{agent} rate limit: {}",
            runner::fallback::summarize_rate_limit_error(message)
        ),
        runner::agents::AgentError::Auth { message } => format!("{agent} auth error: {message}"),
        runner::agents::AgentError::Timeout { elapsed } => {
            format!("{agent} timed out after {}s", elapsed.as_secs())
        }
        other => format!("{agent} agent error: {other}"),
    }
}

/// Parse a PR number from a GitHub PR URL.
///
/// Validates that the URL matches the expected GitHub PR URL format
/// (`https://github.com/<owner>/<repo>/pull/<number>`) before extracting the
/// number. Returns `Err` with a descriptive message for any URL that doesn't
/// conform to this structure, including URLs with wrong domains, missing
/// `/pull/` segments, or non-numeric trailing components.
///
/// The extracted segment is stripped of any query string (`?`) or hash
/// fragment (`#`) before parsing so that URLs like
/// `https://github.com/owner/repo/pull/42?tab=files` are handled correctly.
pub(crate) fn parse_pr_number_from_url(url: &str) -> Result<u64, String> {
    let url = url.trim();
    if url.is_empty() {
        return Err("URL is empty".to_string());
    }
    if !url.starts_with("https://github.com/") {
        return Err(format!(
            "URL does not start with 'https://github.com/': {url}"
        ));
    }
    if !url.contains("/pull/") {
        return Err(format!("URL missing '/pull/' segment: {url}"));
    }
    let last_segment = url
        .trim_end_matches('/')
        .rsplit('/')
        .next()
        .ok_or_else(|| format!("No segment after '/pull/' in URL: {url}"))?;
    let number_part = last_segment
        .split(['?', '#'])
        .next()
        .filter(|s| !s.is_empty())
        .ok_or_else(|| format!("PR number segment is empty in URL: {url}"))?;
    let pr_num: u64 = number_part.parse().map_err(|_| {
        format!("PR number is not a valid positive integer: '{number_part}' in URL: {url}")
    })?;
    if pr_num == 0 {
        return Err(format!("PR number cannot be zero in URL: {url}"));
    }
    Ok(pr_num)
}

fn review_started_comment(review_agent: &str, review_model: &str) -> String {
    let footer = attribution_footer("Review started", review_agent, Some(review_model));
    format!("🔍 Automated review started{footer}")
}

fn should_skip_no_code_reroute_increment(last_error: &str) -> bool {
    crate::engine::runner::git_ops::is_transient_github_api_error(last_error)
}

use crate::backends::{ExternalBackend, ExternalTask, Status};
use crate::cmd::CommandErrorContext;
use crate::config;
use crate::engine::attribution_footer;
use crate::engine::auto_merge::{auto_merge_pr, handle_review_changes};
use crate::engine::runner;
use crate::engine::runner::worktree;
use crate::engine::tasks::TaskManager;
use crate::github::http::GhHttp;
use crate::store::TaskStore;
use crate::store::store_log_activity;
use crate::store::{CompleteRun, RunTokenUsage, StartRun};
use crate::store::{opt_store_get_task, store_increment};
use crate::store::{store_set, store_set_result};
use crate::tmux::TmuxManager;
use anyhow::Context;
use std::collections::HashSet;
use std::sync::Arc;
use tokio::process::Command;
use tokio::sync::RwLock;

use super::router::Router;

/// Review agent decision result.
#[derive(Debug, Clone)]
pub(crate) enum ReviewDecision {
    /// Review approved, PR can be merged.
    Approve {
        issues: Vec<crate::engine::runner::response::ReviewIssue>,
    },
    /// Changes requested, PR needs fixes.
    RequestChanges {
        notes: String,
        issues: Vec<crate::engine::runner::response::ReviewIssue>,
    },
    /// Review agent failed or crashed (reason stored for logging).
    Failed(String),
    /// Unrecoverable failure — task should be blocked for human intervention.
    Blocked(String),
    /// No PR exists — nothing to review, task marked done directly.
    Skipped,
    /// No PR and no commits — task re-routed for retry (no_code_reroutes counter must not be reset).
    Rerouted,
}

/// Outcome of [`ensure_pr_exists`]: either a ready PR number or an early return decision.
enum EnsurePrResult {
    /// PR exists (found in store or via API, or just created). Proceed with review.
    Ready(u64),
    /// No PR and status already updated — return this decision to the caller.
    EarlyReturn(ReviewDecision),
}

enum ReviewPhase<T> {
    Ready(T),
    EarlyReturn(ReviewDecision),
}

struct ReviewContext {
    store_id: Option<i64>,
    had_prev_push_failure: bool,
    review_attempt: u32,
    worktree_path: std::path::PathBuf,
    branch_name: String,
    pr_number: u64,
    /// PR head SHA when the review started, the commit the decision applies to
    head_sha: Option<String>,
    default_branch: String,
    review_agent: String,
    review_model: Option<String>,
    review_task_id: String,
    review_attempt_dir: std::path::PathBuf,
    output_file: std::path::PathBuf,
    invocation: runner::agent::AgentInvocation,
    same_agent_fallback: bool,
}

impl ReviewContext {
    fn review_model_str(&self) -> &str {
        self.review_model.as_deref().unwrap_or("")
    }
}

struct ReviewRun {
    run_id: Option<i64>,
}

struct ParsedReview {
    run_id: Option<i64>,
    exit_code: i32,
    stderr: String,
    raw_output: String,
    text_for_review: String,
    token_usage: RunTokenUsage,
    review_notes_for_comment: String,
    decision: ReviewDecision,
}

/// KV key holding the commit an approving review was already written for
fn approved_sha_key(repo: &str, task_id: &str, pr_number: u64) -> String {
    format!("review_approved_sha:{repo}#{task_id}#{pr_number}")
}

const REVIEW_TIMEOUT_DEFAULT_SECS: u64 = 900;
const REVIEW_TIMEOUT_MIN_SECS: u64 = 300;

// A review reads a diff and runs the tests, so it gets its own limit, shorter than a task's
fn review_timeout_secs(configured: Option<u64>) -> u64 {
    configured
        .unwrap_or(REVIEW_TIMEOUT_DEFAULT_SECS)
        .max(REVIEW_TIMEOUT_MIN_SECS)
}

/// Read `HEAD` of a worktree. `None` when the worktree is gone or not a repository
pub(crate) async fn worktree_head_sha(dir: &std::path::Path) -> Option<String> {
    let out = tokio::process::Command::new("git")
        .args(["rev-parse", "HEAD"])
        .current_dir(dir)
        .kill_on_drop(true)
        .output()
        .await
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let sha = String::from_utf8_lossy(&out.stdout).trim().to_string();
    (!sha.is_empty()).then_some(sha)
}

/// What an approving review approved: the commit and the PR it was on. A carried approval must
/// match every field
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub(crate) struct ApprovalEvent {
    sha: String,
    repo: String,
    branch: String,
    base: String,
}

impl ApprovalEvent {
    /// A record from before events held only the sha, it approves that head and never carries
    fn parse(raw: &str) -> Option<Self> {
        let raw = raw.trim();
        if raw.is_empty() {
            return None;
        }
        serde_json::from_str(raw).ok().or_else(|| {
            Some(Self {
                sha: raw.to_string(),
                repo: String::new(),
                branch: String::new(),
                base: String::new(),
            })
        })
    }
}

async fn read_approval(
    store: &Arc<TaskStore>,
    repo: &str,
    task_id: &str,
    pr_number: u64,
) -> anyhow::Result<Option<ApprovalEvent>> {
    Ok(store
        .kv_get(&approved_sha_key(repo, task_id, pr_number))
        .await?
        .as_deref()
        .and_then(ApprovalEvent::parse))
}

async fn write_approval(
    store: &Arc<TaskStore>,
    task_id: &str,
    pr_number: u64,
    event: &ApprovalEvent,
) {
    let key = approved_sha_key(&event.repo, task_id, pr_number);
    let value = serde_json::to_string(event).unwrap_or_default();
    if let Err(e) = store.kv_set(&key, &value).await {
        tracing::warn!(task_id, err = %e, "failed to record the approval");
    }
}

/// Record that the commit just pushed to the PR carries an approving review, so a later
/// NeedsReview event on the same commit skips the review agent
async fn record_approved_sha(
    store: &Arc<TaskStore>,
    repo: &str,
    task_id: &str,
    pr_number: u64,
    dir: &std::path::Path,
    branch: &str,
    base: &str,
) {
    let Some(sha) = worktree_head_sha(dir).await else {
        return;
    };
    let event = ApprovalEvent {
        sha,
        repo: repo.to_string(),
        branch: branch.to_string(),
        base: base.to_string(),
    };
    write_approval(store, task_id, pr_number, &event).await;
}

/// Drop a recorded approval so the next NeedsReview event runs a real review
async fn clear_approved_sha(store: &Arc<TaskStore>, repo: &str, task_id: &str, pr_number: u64) {
    if let Err(e) = store
        .kv_delete(&approved_sha_key(repo, task_id, pr_number))
        .await
    {
        tracing::warn!(task_id, err = %e, "failed to clear approved commit sha");
    }
}

/// Records the earlier approval as this review round's decision. Without it the stale
/// in_review check sees a round with no decision and resets the task every minute
async fn record_carried_approval(
    store: &Arc<TaskStore>,
    repo: &str,
    task_id: &str,
    pr_number: u64,
) {
    store_log_activity(
        &Some(Arc::clone(store)),
        repo,
        task_id,
        "review_decision",
        None,
        None,
        None::<&str>,
        None::<&str>,
        Some(&serde_json::json!({
            "decision": "approve",
            "pr_number": pr_number,
            "reason": "head_already_approved",
        })),
    )
    .await;
}

/**
 * True when the PR's current head is the commit a previous review approved.
 *
 * Compared against the live PR head, not the worktree: a force-push from another clone
 * moves the head while the worktree stays on the approved commit, and skipping the
 * review there would merge code nobody reviewed. Any lookup failure returns false, so
 * the fallback is to review again (#3783)
 **/
async fn pr_head_already_approved(
    store: &Arc<TaskStore>,
    repo: &str,
    task_id: &str,
    pr_number: u64,
) -> bool {
    let approved = match read_approval(store, repo, task_id, pr_number).await {
        Ok(event) => event.map(|e| e.sha),
        Err(e) => {
            tracing::warn!(task_id, err = %e, "failed to read approved commit sha");
            return false;
        }
    };
    if approved.is_none() {
        return false;
    }
    let gh = match crate::github::http::GhHttp::new() {
        Ok(gh) => gh,
        Err(e) => {
            tracing::warn!(task_id, err = %e, "cannot check PR head against recorded approval");
            return false;
        }
    };
    let pr_head = match gh.get_pr(repo, pr_number).await {
        Ok(pr) => Some(pr.head.sha),
        Err(e) => {
            tracing::warn!(task_id, pr_number, err = %e, "failed to read PR head sha");
            None
        }
    };
    approval_covers_head(approved.as_deref(), pr_head.as_deref())
}

/// The task, PR and approval a carried approval must all agree on
struct CarryContext {
    approval: ApprovalEvent,
    worktree: std::path::PathBuf,
}

/**
 * Checks shared by both ways an approval moves to a new head: an approval event is on record,
 * and the PR still matches it. The head lives in the approved repository (not a fork) on the
 * approved branch, which is the task's branch, it targets the approved base, and the task
 * worktree tracks that branch and base. `None` means the approval stays where it was
 **/
async fn carry_context(
    store: &Arc<TaskStore>,
    repo: &str,
    task_id: &str,
    pr: &crate::github::types::GitHubPullRequest,
    pr_number: u64,
) -> Option<CarryContext> {
    let approval = read_approval(store, repo, task_id, pr_number)
        .await
        .ok()
        .flatten()?;
    let task = opt_store_get_task(&Some(Arc::clone(store)), repo, task_id).await?;
    if !pr_matches_approval(pr, &approval, &task.branch) || task.worktree.is_empty() {
        tracing::warn!(
            task_id,
            pr_number,
            "the PR does not match the approved repository, branch and base, approval not carried"
        );
        return None;
    }
    let worktree = std::path::PathBuf::from(&task.worktree);
    if runner::git_ops::get_current_branch(&worktree).await != approval.branch
        || crate::engine::runner::worktree::detect_default_branch(&worktree).await != approval.base
    {
        tracing::warn!(
            task_id,
            pr_number,
            "the task worktree does not track the approved branch and base, approval not carried"
        );
        return None;
    }
    Some(CarryContext { approval, worktree })
}

/// The PR's head repository, head branch and base are the approved ones, and the head branch is
/// the task's. A record without these fields (written before events) never matches
fn pr_matches_approval(
    pr: &crate::github::types::GitHubPullRequest,
    approval: &ApprovalEvent,
    task_branch: &str,
) -> bool {
    let same_repo = !approval.repo.is_empty()
        && pr
            .head
            .repo
            .as_ref()
            .is_some_and(|r| r.full_name.eq_ignore_ascii_case(&approval.repo));
    same_repo
        && !approval.branch.is_empty()
        && pr.head.ref_ == approval.branch
        && approval.branch == task_branch
        && !approval.base.is_empty()
        && pr.base.ref_ == approval.base
}

/**
 * Carry an approval to a head that only merged the base branch in, as GitHub's update-branch
 * does. On top of `carry_context`: the head is a merge whose first parent is the approved commit
 * and whose second parent the base branch already holds, GitHub made it (committer `web-flow`)
 * for a repository collaborator, and its tree is exactly the clean merge of the two, recomputed
 * in the task worktree. Anything else keeps the approval where it was and the head gets a review
 **/
pub(crate) async fn carry_approval_across_base_update(
    store: &Arc<TaskStore>,
    gh: &GhHttp,
    repo: &str,
    task_id: &str,
    pr: &crate::github::types::GitHubPullRequest,
    pr_number: u64,
) {
    let head_sha = pr.head.sha.as_str();
    let Ok(Some(recorded)) = read_approval(store, repo, task_id, pr_number).await else {
        return;
    };
    if recorded.sha == head_sha {
        return;
    }
    let Some(ctx) = carry_context(store, repo, task_id, pr, pr_number).await else {
        return;
    };
    let meta = match gh.commit_meta(repo, head_sha).await {
        Ok(meta) => meta,
        Err(e) => {
            tracing::warn!(task_id, err = %e, "cannot read the PR head commit to carry the approval");
            return;
        }
    };
    let Some(base_parent) = base_merge_parent(&ctx.approval.sha, &meta.parents) else {
        return;
    };
    if meta.committer_login.as_deref() != Some("web-flow") {
        tracing::warn!(
            task_id,
            pr_number,
            head_sha,
            "the base merge was not made by GitHub, approval not carried"
        );
        return;
    }
    let Some(author) = meta.author_login.as_deref() else {
        return;
    };
    if !matches!(gh.is_collaborator(repo, author).await, Ok(true)) {
        tracing::warn!(
            task_id,
            pr_number,
            author,
            "the base merge author is not a collaborator, approval not carried"
        );
        return;
    }
    if !matches!(
        gh.branch_contains(repo, &pr.base.ref_, base_parent).await,
        Ok(true)
    ) {
        return;
    }
    let _ = runner::git_ops::git()
        .await
        .args(["fetch", "origin"])
        .current_dir(&ctx.worktree)
        .output()
        .await;
    if !is_clean_merge(&ctx.worktree, &ctx.approval.sha, base_parent, head_sha).await {
        tracing::warn!(
            task_id,
            pr_number,
            head_sha,
            "the PR head is not a clean merge of the base, approval not carried"
        );
        return;
    }

    publish_carried_approval(store, gh, repo, task_id, pr_number, &ctx.approval, head_sha).await;
}

/**
 * After orch rebased the approved head onto the base, move the approval to the rebased head. On
 * top of `carry_context`: the rebase started from the approved commit, the new head holds the same
 * commits with the same patches and authors in the same order on top of the base tip, and GitHub
 * shows the new head as the PR head
 **/
pub(crate) async fn carry_approval_after_rebase(
    store: &Arc<TaskStore>,
    gh: &GhHttp,
    repo: &str,
    task_id: &str,
    pr: &crate::github::types::GitHubPullRequest,
    pr_number: u64,
) {
    let Some(ctx) = carry_context(store, repo, task_id, pr, pr_number).await else {
        return;
    };
    let rebased_from = pr.head.sha.as_str();
    if ctx.approval.sha != rebased_from {
        return;
    }
    let Some(new_head) = worktree_head_sha(&ctx.worktree).await else {
        return;
    };
    let base = format!("origin/{}", pr.base.ref_);
    if !same_commits_rebased(&ctx.worktree, rebased_from, &base, &new_head).await {
        tracing::warn!(
            task_id,
            pr_number,
            "the rebased commits differ from the approved ones, approval not carried"
        );
        return;
    }
    let mut pushed = false;
    for _ in 0..3 {
        if gh
            .get_pr(repo, pr_number)
            .await
            .is_ok_and(|p| p.head.sha == new_head)
        {
            pushed = true;
            break;
        }
        tokio::time::sleep(std::time::Duration::from_secs(2)).await;
    }
    if !pushed {
        tracing::warn!(
            task_id,
            pr_number,
            "GitHub does not show the rebased head yet, approval not carried"
        );
        return;
    }

    publish_carried_approval(
        store,
        gh,
        repo,
        task_id,
        pr_number,
        &ctx.approval,
        &new_head,
    )
    .await;
}

/// The commits from the merge base of `old_head` and `base` up to `old_head`, replayed onto `base`
/// as `new_head`: same count, same patch ids, same authors, same order, and `new_head` sits on `base`
async fn same_commits_rebased(
    dir: &std::path::Path,
    old_head: &str,
    base: &str,
    new_head: &str,
) -> bool {
    let Some(fork_point) = git_output(dir, &["merge-base", old_head, base]).await else {
        return false;
    };
    let on_base = git_output(dir, &["merge-base", "--is-ancestor", base, new_head])
        .await
        .is_some();
    let old = commit_fingerprints(dir, &format!("{fork_point}..{old_head}")).await;
    let new = commit_fingerprints(dir, &format!("{base}..{new_head}")).await;
    on_base && old.is_some() && !old.as_ref().is_some_and(Vec::is_empty) && old == new
}

/// `(patch id, author)` for each commit in `range`, oldest first. `None` for a merge commit or
/// any git failure
async fn commit_fingerprints(dir: &std::path::Path, range: &str) -> Option<Vec<(String, String)>> {
    let log = git_output(
        dir,
        &["log", "--reverse", "--format=%H %P%x00%an <%ae>", range],
    )
    .await?;
    let mut prints = Vec::new();
    for line in log.lines().filter(|l| !l.is_empty()) {
        let (shas, author) = line.split_once('\0')?;
        let mut shas = shas.split(' ');
        let sha = shas.next()?;
        if shas.count() != 1 {
            return None;
        }
        prints.push((patch_id(dir, sha).await?, author.to_string()));
    }
    Some(prints)
}

/// `git patch-id --stable` of one commit, identical for the same change on another base
async fn patch_id(dir: &std::path::Path, sha: &str) -> Option<String> {
    use tokio::io::AsyncWriteExt;
    let diff = git_output(dir, &["show", "--format=", sha]).await?;
    let mut child = tokio::process::Command::new("git")
        .args(["patch-id", "--stable"])
        .current_dir(dir)
        .stdin(std::process::Stdio::piped())
        .stdout(std::process::Stdio::piped())
        .kill_on_drop(true)
        .spawn()
        .ok()?;
    let mut stdin = child.stdin.take()?;
    stdin.write_all(diff.as_bytes()).await.ok()?;
    stdin.write_all(b"\n").await.ok()?;
    drop(stdin);
    let out = child.wait_with_output().await.ok()?;
    String::from_utf8_lossy(&out.stdout)
        .split_whitespace()
        .next()
        .map(String::from)
}

/// Record `head_sha` as approved and pass `orch/review` on it: the App check run in app mode, the
/// commit status in comment mode. The App review stays on the PR, a second one would repeat it
async fn publish_carried_approval(
    store: &Arc<TaskStore>,
    gh: &GhHttp,
    repo: &str,
    task_id: &str,
    pr_number: u64,
    approval: &ApprovalEvent,
    head_sha: &str,
) {
    let carried = ApprovalEvent {
        sha: head_sha.to_string(),
        ..approval.clone()
    };
    write_approval(store, task_id, pr_number, &carried).await;
    let note = "Approval carried across a base branch update";
    let app = review_app(repo).await;
    post_review_decision(
        app.as_deref(),
        gh,
        repo,
        Some(head_sha),
        &ReviewDecision::Approve { issues: vec![] },
        note,
    )
    .await;
    tracing::info!(
        task_id,
        pr_number,
        head_sha,
        "approval carried across a base branch update"
    );
}

/// Trimmed stdout of a git command, `None` when it fails
async fn git_output(dir: &std::path::Path, args: &[&str]) -> Option<String> {
    let out = tokio::process::Command::new("git")
        .args(args)
        .current_dir(dir)
        .kill_on_drop(true)
        .output()
        .await
        .ok()?;
    out.status
        .success()
        .then(|| String::from_utf8_lossy(&out.stdout).trim().to_string())
}

/// True when `head` holds exactly the tree of a conflict-free merge of `approved` and `base_parent`
async fn is_clean_merge(
    dir: &std::path::Path,
    approved: &str,
    base_parent: &str,
    head: &str,
) -> bool {
    let merged = git_output(dir, &["merge-tree", "--write-tree", approved, base_parent]).await;
    let head_tree = git_output(dir, &["rev-parse", &format!("{head}^{{tree}}")]).await;
    match (merged, head_tree) {
        (Some(merged), Some(head_tree)) => merged.lines().next() == Some(head_tree.as_str()),
        _ => false,
    }
}

/// The second parent of a merge of `approved` with another commit, the commit to check against the base
fn base_merge_parent<'a>(approved: &str, parents: &'a [String]) -> Option<&'a str> {
    match parents {
        [first, second] if first == approved => Some(second.as_str()),
        _ => None,
    }
}

/// Whether a recorded approval still applies to the PR's current head commit
fn approval_covers_head(approved: Option<&str>, pr_head: Option<&str>) -> bool {
    match (approved, pr_head) {
        (Some(approved), Some(head)) => !approved.is_empty() && approved == head,
        _ => false,
    }
}

fn build_review_disallowed_tools(worktree_path: &std::path::Path) -> Vec<String> {
    let mut tools = vec![
        "Bash(rm *)".to_string(),
        "Bash(rm -*)".to_string(),
        "Bash(git push*)".to_string(),
        // Pushing and opening the PR are orch's steps, never the agent's (#3783)
        "Bash(gh pr create*)".to_string(),
    ];
    tools.extend(runner::git_ops::remote_change_tools());
    let orch_yml = worktree_path.join(".orch.yml");
    let orch_yml_str = orch_yml.to_string_lossy();
    tools.extend([
        format!("Write({orch_yml_str})"),
        format!("Edit({orch_yml_str})"),
    ]);
    if let Ok(orch_home) = crate::home::orch_home() {
        for path in [
            orch_home.join("config.yml"),
            orch_home.join("config.example.yml"),
        ] {
            let path_str = path.to_string_lossy();
            tools.extend([
                format!("Read({path_str})"),
                format!("Write({path_str})"),
                format!("Edit({path_str})"),
            ]);
        }
    }
    tools
}

async fn select_review_agent(
    task_id: &str,
    task_agent: &str,
    store_id: Option<i64>,
    router: &Arc<RwLock<Router>>,
    store: &Arc<TaskStore>,
) -> anyhow::Result<(String, Option<String>, bool)> {
    let mut exclude_set: HashSet<String> = HashSet::new();
    if !task_agent.is_empty() {
        exclude_set.insert(task_agent.to_string());
    }
    if let Some(store_id) = store_id
        && let Ok(failed) = store.previous_review_agents(store_id).await
    {
        for agent in failed {
            exclude_set.insert(agent);
        }
    }

    let mut r = router.write().await;
    let mut tried_agents: HashSet<String> = HashSet::new();
    let mut chosen_agent: Option<String> = None;
    let mut chosen_model: Option<String> = None;
    let available_count = r.available_agents.len().max(1);

    loop {
        let tmp_exclude_refs: Vec<&str> = exclude_set
            .iter()
            .map(std::string::String::as_str)
            .collect();
        let Some(agent) = r.next_round_robin_agent(&tmp_exclude_refs, "review") else {
            break;
        };

        if tried_agents.contains(&agent) {
            break;
        }
        tried_agents.insert(agent.clone());

        let model = r.config.model_for_complexity(&agent, "review", task_id);
        if model.is_some() {
            chosen_agent = Some(agent);
            chosen_model = model;
            break;
        }

        exclude_set.insert(agent);
        if exclude_set.len() >= available_count {
            break;
        }
    }

    if let Some(agent) = chosen_agent {
        let same = !task_agent.is_empty() && agent == task_agent;
        Ok((agent, chosen_model, same))
    } else {
        let final_exclude_refs: Vec<&str> = exclude_set
            .iter()
            .map(std::string::String::as_str)
            .collect();
        let fallback_agent = r
            .next_round_robin_agent(&final_exclude_refs, "review")
            .unwrap_or_else(|| "claude".to_string());
        let fallback_model = r
            .config
            .model_for_complexity(&fallback_agent, "review", task_id);
        if fallback_model.is_none() {
            anyhow::bail!(
                "no review agent with a configured review model is available for task {task_id}"
            );
        }
        let same = !task_agent.is_empty() && fallback_agent == task_agent;
        Ok((fallback_agent, fallback_model, same))
    }
}

async fn build_review_context(
    task: &ExternalTask,
    repo: &str,
    router: &Arc<RwLock<Router>>,
    task_manager: &Arc<TaskManager>,
    store: &Arc<TaskStore>,
) -> anyhow::Result<ReviewPhase<ReviewContext>> {
    let stored_task = store
        .get_by_external_id(repo, &task.id.0)
        .await
        .with_context(|| format!("store lookup failed for task {}", task.id.0))?;

    let store_id: Option<i64> = stored_task.as_ref().map(|t| t.id);

    // A commit that already has an approval must not be reviewed again. Checked before
    // the review_invocations increment so a stuck merge cannot exhaust the review quota
    if let Some(pr_number) = stored_task
        .as_ref()
        .and_then(|t| t.pr_number)
        .and_then(|n| u64::try_from(n).ok())
        && pr_head_already_approved(store, repo, &task.id.0, pr_number).await
    {
        tracing::info!(
            task_id = task.id.0,
            pr_number,
            "PR head already approved — skipping review, merge retry continues"
        );
        record_carried_approval(store, repo, &task.id.0, pr_number).await;
        return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Approve {
            issues: Vec::new(),
        }));
    }

    let had_prev_push_failure = stored_task
        .as_ref()
        .is_some_and(|t| t.last_error.contains("push failed"));
    let review_attempt: u32 = match store_increment(
        &Some(Arc::clone(store)),
        repo,
        &task.id.0,
        "review_invocations",
    )
    .await
    {
        Ok(v) => u32::try_from(v).unwrap_or(u32::MAX),
        Err(e) => {
            tracing::warn!(task_id = task.id.0, err = %e, "failed to increment review_invocations — using fallback attempt=1");
            1
        }
    };

    let no_code_review = stored_task.as_ref().is_some_and(|t| {
        t.worktree.trim().is_empty() && t.branch.trim().is_empty() && t.pr_number.is_none()
    });
    if no_code_review {
        if crate::engine::tasks::is_internal_id(&task.id.0) {
            // Internal tasks legitimately reach needs_review with nothing to review.
            tracing::info!(
                task_id = task.id.0,
                "no worktree/branch/pr for internal needs_review task — skipping review and marking done"
            );
            if let Err(e) = task_manager
                .update_task_status(&task.id, Status::Done)
                .await
            {
                tracing::error!(
                    task_id = task.id.0,
                    err = %e,
                    "update_task_status(Done) failed for no-code review skip"
                );
            }
            return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Skipped));
        }

        // External task with no code produced: re-route instead of marking done.
        // Shares the no_code_reroutes circuit breaker with the no-PR/no-commits path below.
        let max_reroutes: u32 = config::get("workflow.max_reroute_attempts")
            .ok()
            .and_then(|s| s.parse().ok())
            .or_else(|| {
                config::get("workflow.max_attempts")
                    .ok()
                    .and_then(|s| s.parse().ok())
            })
            .unwrap_or(3);

        let reroutes = match store_increment(
            &Some(Arc::clone(store)),
            repo,
            &task.id.0,
            "no_code_reroutes",
        )
        .await
        {
            Ok(v) => v,
            Err(e) => {
                tracing::warn!(task_id = task.id.0, err = %e, "failed to increment no_code_reroutes — skipping reroute/block decision this tick");
                return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Failed(format!(
                    "transient store error: {e}"
                ))));
            }
        };

        if reroutes >= u64::from(max_reroutes) {
            tracing::error!(
                task_id = task.id.0,
                reroutes,
                max_reroutes,
                "reached max reroute attempts for no-worktree/branch/pr result — blocking for human review"
            );
            let msg =
                format!("no worktree/branch/pr after {reroutes}/{max_reroutes} reroute attempts");
            let fields = [
                (
                    "block_reason",
                    serde_json::json!(format!(
                        "max reroute attempts ({}) reached — no worktree/branch/pr produced",
                        max_reroutes
                    )),
                ),
                ("last_error", serde_json::json!(msg)),
                ("agent", serde_json::json!(null)),
                ("model", serde_json::json!(null)),
            ];
            if let Err(e) = task_manager
                .update_task_status_and_result(&task.id, Status::Blocked, &fields)
                .await
            {
                tracing::error!(task_id = task.id.0, err = %e, "update_task_status_and_result(Blocked) failed — skipping block to avoid silent auto-unblock loop");
            }
            return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Blocked(msg)));
        }

        tracing::warn!(
            task_id = task.id.0,
            reroutes,
            max_reroutes,
            "no worktree/branch/pr for external needs_review task — re-routing to a different agent"
        );
        match store_set_result(
            &Some(Arc::clone(store)),
            repo,
            &task.id.0,
            &[
                ("agent", serde_json::json!(null)),
                ("model", serde_json::json!(null)),
                (
                    "last_error",
                    serde_json::json!("no worktree/branch/pr produced"),
                ),
            ],
        )
        .await
        {
            Err(e) => {
                tracing::error!(task_id = task.id.0, err = %e, "failed to clear agent/model for reroute — skipping status transition");
            }
            _ => {
                if let Err(e) = task_manager.update_task_status(&task.id, Status::New).await {
                    tracing::error!(task_id = task.id.0, err = %e, "update_task_status(New) failed — task may be stuck in InReview");
                }
            }
        }
        return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Rerouted));
    }

    let mut worktree_path = match stored_task.as_ref().map(|t| t.worktree.as_str()) {
        Some(w) if !w.is_empty() => std::path::PathBuf::from(w),
        _ => {
            tracing::warn!(task_id = task.id.0, "no worktree found for review");
            return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Failed(
                "no worktree found".to_string(),
            )));
        }
    };

    let mut branch_name = match stored_task.as_ref().map(|t| t.branch.as_str()) {
        Some(b) if !b.is_empty() => b.to_string(),
        _ => {
            tracing::warn!(task_id = task.id.0, "no branch found for review");
            return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Failed(
                "no branch found".to_string(),
            )));
        }
    };

    let mut missing_worktree_recovered = false;
    if !worktree_path.exists() {
        match recover_missing_review_worktree(task, repo, store).await {
            Ok(recovered) => {
                branch_name = recovered.branch;
                worktree_path = recovered.work_dir;
                missing_worktree_recovered = true;
            }
            Err(e) => {
                let reason = format!("missing review worktree recovery failed: {e}");
                tracing::error!(task_id = task.id.0, error = %reason, "cannot recover review worktree");
                store_set(
                    &Some(Arc::clone(store)),
                    repo,
                    &task.id.0,
                    &[("last_error", serde_json::json!(reason.clone()))],
                )
                .await;
                return Ok(ReviewPhase::EarlyReturn(ReviewDecision::Blocked(reason)));
            }
        }
    }

    if missing_worktree_recovered {
        store_set(
            &Some(Arc::clone(store)),
            repo,
            &task.id.0,
            &[("last_error", serde_json::json!(""))],
        )
        .await;
    }

    let agent_summary = stored_task
        .as_ref()
        .map(|t| t.summary.clone())
        .unwrap_or_default();
    let stored_pr_number = stored_task
        .as_ref()
        .and_then(|t| t.pr_number)
        .and_then(|n| u64::try_from(n).ok())
        .filter(|&n| n > 0);

    let pr_number = match ensure_pr_exists(
        task,
        &branch_name,
        &worktree_path,
        repo,
        &agent_summary,
        store,
        task_manager,
        stored_pr_number,
    )
    .await?
    {
        EnsurePrResult::Ready(n) => n,
        EnsurePrResult::EarlyReturn(decision) => return Ok(ReviewPhase::EarlyReturn(decision)),
    };

    // Run `git fetch` with a timeout so a hung network call cannot stall the
    // review pipeline indefinitely. Treat a timeout or non-zero exit as a
    // non-fatal warning (stale remote refs are acceptable for the review).
    {
        let fetch_timeout = std::time::Duration::from_secs(60);
        let fetch_future = async {
            let mut cmd = runner::git_ops::git().await;
            cmd.args(["fetch", "origin", "--prune"])
                .current_dir(&worktree_path);
            // Ensure the child is killed if the timeout elapses
            cmd.kill_on_drop(true);
            cmd.output_with_context().await
        };

        match tokio::time::timeout(fetch_timeout, fetch_future).await {
            Ok(Ok(o)) if o.status.success() => {
                // ok
            }
            Ok(Ok(o)) => {
                tracing::warn!(
                    task_id = task.id.0,
                    exit_code = ?o.status.code(),
                    stdout = %String::from_utf8_lossy(&o.stdout),
                    stderr = %String::from_utf8_lossy(&o.stderr),
                    "review: git fetch failed (non-zero exit) — diff/log may use stale remote refs"
                );
            }
            Ok(Err(e)) => {
                tracing::warn!(
                    task_id = task.id.0,
                    error = %e,
                    "review: git fetch failed — diff/log may use stale remote refs"
                );
            }
            Err(_) => {
                tracing::warn!(
                    task_id = task.id.0,
                    "review: git fetch timed out after 60s — diff/log may use stale remote refs"
                );
            }
        }
    }

    let default_branch = runner::worktree::detect_default_branch(&worktree_path).await;
    let git_diff = runner::context::build_git_diff(&worktree_path, &default_branch).await;
    let git_log = runner::context::build_git_log(&worktree_path, &default_branch).await;
    // An unknown project falls back to the global config, never to the worktree's .orch.yml,
    // which the task agent may have written
    let project_dir = review_project_dir(repo);
    let sandboxed = sandboxed_in(project_dir.as_deref());
    let main_project_dir = project_dir.unwrap_or_else(|| worktree_path.clone());
    let review_prompt = runner::agent::build_review_prompt(
        task,
        &agent_summary,
        &git_diff,
        &git_log,
        &default_branch,
        pr_number,
        runner::agent::Shipcheck::detect(&worktree_path)
            .await
            .for_prompt(sandboxed),
    );

    let task_agent = stored_task
        .as_ref()
        .and_then(|t| t.agent.clone())
        .unwrap_or_default();
    let (review_agent, review_model, same_agent_fallback) =
        select_review_agent(&task.id.0, &task_agent, store_id, router, store).await?;

    anyhow::ensure!(
        review_model.is_some(),
        "review model missing for task {} after agent selection — refusing to dispatch",
        task.id.0
    );

    if same_agent_fallback {
        tracing::warn!(
            task_id = task.id.0,
            agent = %review_agent,
            "no other agent available for review — falling back to the agent that wrote the code"
        );
        store_log_activity(
            &Some(Arc::clone(store)),
            repo,
            &task.id.0,
            "review_agent_fallback",
            None,
            None,
            Some(&review_agent),
            review_model.as_deref(),
            Some(&serde_json::json!({
                "reason": "all available agents excluded (author + previous reviewers)",
            })),
        )
        .await;
    }

    tracing::info!(
        task_id = task.id.0,
        agent = %review_agent,
        model = ?review_model,
        "spawning review agent"
    );

    let review_task_id = format!("{}-review", task.id.0);
    let review_attempt_dir =
        crate::home::task_attempt_dir_async(repo, &review_task_id, review_attempt).await?;
    let output_file = review_attempt_dir.join("output.json");

    let git_name =
        crate::config::get("git.name").unwrap_or_else(|_| format!("{review_agent}[bot]"));
    let git_email = crate::config::get("git.email")
        .unwrap_or_else(|_| format!("{review_agent}[bot]@users.noreply.github.com"));
    let review_timeout_secs = review_timeout_seconds();

    let invocation = runner::agent::AgentInvocation {
        agent: review_agent.clone(),
        model: review_model.clone(),
        work_dir: worktree_path.clone(),
        system_prompt: runner::agent::review_system_prompt(),
        agent_message: review_prompt,
        task_id: review_task_id.clone(),
        disallowed_tools: build_review_disallowed_tools(&worktree_path),
        git_author_name: git_name,
        git_author_email: git_email,
        output_file: output_file.clone(),
        timeout_seconds: review_timeout_secs,
        repo: repo.to_string(),
        attempt: review_attempt,
        sandbox: sandboxed,
        main_project_dir,
        branch: branch_name.clone(),
    };

    let head_sha = match GhHttp::new() {
        Ok(gh) => gh.get_pr(repo, pr_number).await.ok().map(|pr| pr.head.sha),
        Err(_) => None,
    };

    Ok(ReviewPhase::Ready(ReviewContext {
        store_id,
        had_prev_push_failure,
        review_attempt,
        worktree_path,
        branch_name,
        pr_number,
        head_sha,
        default_branch,
        review_agent,
        review_model,
        review_task_id,
        review_attempt_dir,
        output_file,
        invocation,
        same_agent_fallback,
    }))
}

#[expect(
    clippy::too_many_arguments,
    reason = "the run record needs the outcome, the agent and the timing together"
)]
async fn complete_review_run(
    store: &Arc<TaskStore>,
    run_id: Option<i64>,
    exit_code: Option<i32>,
    stdout: &str,
    stderr: &str,
    parsed: &str,
    outcome: &str,
    error: &str,
    tokens: RunTokenUsage,
) {
    if let Some(run_id) = run_id
        && let Err(e) = store
            .complete_run(&CompleteRun {
                run_id,
                exit_code,
                stdout,
                stderr,
                parsed,
                outcome,
                error,
                tokens,
            })
            .await
    {
        tracing::warn!(
            run_id,
            error = %e,
            "failed to record review run completion in audit trail"
        );
    }
}

async fn invoke_review_agent(
    task: &ExternalTask,
    tmux: &Arc<TmuxManager>,
    ctx: &ReviewContext,
    repo: &str,
    store: &Arc<TaskStore>,
) -> ReviewPhase<ReviewRun> {
    let run_id = if let Some(sid) = ctx.store_id {
        match store
            .start_run(&StartRun {
                task_id: sid,
                attempt: i32::try_from(ctx.review_attempt).unwrap_or(i32::MAX),
                run_type: "review",
                agent: &ctx.review_agent,
                model: ctx.review_model.as_deref().unwrap_or(""),
                command: "",
                prompt: "",
            })
            .await
        {
            Ok(run_id) => Some(run_id),
            Err(e) => {
                tracing::warn!(
                    task_id = task.id.0,
                    error = %e,
                    "failed to record review run start in audit trail"
                );
                None
            }
        }
    } else {
        None
    };

    let session = match runner::agent::spawn_in_tmux(tmux, &ctx.invocation).await {
        Ok(session) => session,
        Err(e) => {
            tracing::error!(task_id = task.id.0, error = %e, "failed to spawn review agent");
            complete_review_run(
                store,
                run_id,
                None,
                "",
                &e.to_string(),
                "",
                "failed",
                &format!("spawn failed: {e}"),
                RunTokenUsage::default(),
            )
            .await;
            return ReviewPhase::EarlyReturn(ReviewDecision::Failed(format!("spawn failed: {e}")));
        }
    };

    let start_comment = review_started_comment(&ctx.review_agent, ctx.review_model_str());
    match GhHttp::new() {
        Ok(gh) => {
            let app = review_app(repo).await;
            post_review_started(app.as_deref(), &gh, repo, ctx.head_sha.as_deref()).await;
            // The comment is comment mode's only start signal, the App's check run shows it already
            if app.is_none()
                && let Err(e) = gh
                    .add_comment(repo, &ctx.pr_number.to_string(), &start_comment)
                    .await
            {
                tracing::debug!(
                    task_id = task.id.0,
                    pr_number = ctx.pr_number,
                    error = %e,
                    "failed to post review-started comment"
                );
            }
        }
        Err(e) => {
            tracing::debug!(
                task_id = task.id.0,
                pr_number = ctx.pr_number,
                error = %e,
                "failed to create GitHub client for review-started comment"
            );
        }
    }

    let poll_interval = std::time::Duration::from_secs(5);
    let timeout_duration = std::time::Duration::from_secs(ctx.invocation.timeout_seconds);
    let wait_result = tokio::time::timeout(timeout_duration, async {
        tokio::select! {
            result = tmux.wait_for_completion(&session, poll_interval) => result,
            // An agent can write its decision and still hold the session open
            () = wait_for_review_decision(ctx, poll_interval) => {
                tracing::info!(task_id = task.id.0, "review decision is in while the session is still open, ending it");
                Ok(String::new())
            }
        }
    })
    .await;

    match wait_result {
        Ok(Ok(_)) => {
            tracing::info!(task_id = task.id.0, "review agent completed");
            let _ = tmux.kill_session(&session).await;
            ReviewPhase::Ready(ReviewRun { run_id })
        }
        Ok(Err(e)) => {
            tracing::warn!(task_id = task.id.0, error = %e, "review agent process exited with error");
            let _ = tmux.kill_session(&session).await;

            // Before recording failure, check if this is a "successful exit with non-zero
            // code" agent like kimi/minimax. Read the output file and check for a valid
            // result with is_error=false — if found, treat as success and proceed to
            // parse_review_output where the real result will be extracted.
            let exit_code: i32 = tokio::task::spawn_blocking({
                let review_attempt_dir = ctx.review_attempt_dir.clone();
                move || {
                    std::fs::read_to_string(review_attempt_dir.join("exit.txt"))
                        .ok()
                        .and_then(|s| s.trim().parse().ok())
                        .unwrap_or(-1)
                }
            })
            .await
            .unwrap_or(-1);

            if exit_code != 0 {
                // Try reading output via read_output_file which checks both the primary path
                // and all prior attempt dirs as a fallback. This handles agents like kimi/minimax
                // that exit non-zero even on success, as well as cases where the current attempt's
                // output.json was not written but a prior attempt's output contains a valid result.
                let raw_output =
                    runner::response::read_output_file(&ctx.review_task_id, &ctx.output_file, repo)
                        .await;
                let agent_result =
                    runner::agents::find_agent_result(&ctx.review_agent, &raw_output);
                // Treat as success if we found a valid result without is_error set
                if agent_result.as_ref().is_some_and(|r| !r.is_error) {
                    tracing::info!(
                        task_id = task.id.0,
                        agent = %ctx.review_agent,
                        exit_code,
                        output_found = !raw_output.is_empty(),
                        "review agent succeeded despite non-zero exit — proceeding to parse output"
                    );
                    return ReviewPhase::Ready(ReviewRun { run_id });
                }
            }

            tracing::error!(task_id = task.id.0, error = %e, "review agent failed");
            complete_review_run(
                store,
                run_id,
                Some(exit_code),
                "",
                &e.to_string(),
                "",
                "failed",
                &format!("agent error: {e}"),
                RunTokenUsage::default(),
            )
            .await;
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(format!("agent error: {e}")))
        }
        Err(_) => {
            let _ = tmux.kill_session(&session).await;
            if review_output_has_decision(ctx).await {
                tracing::warn!(
                    task_id = task.id.0,
                    "review agent timed out after writing its decision, using it"
                );
                return ReviewPhase::Ready(ReviewRun { run_id });
            }

            tracing::error!(task_id = task.id.0, "review agent timed out");
            store_review_timeout(store, run_id, -1, "", "timeout").await
        }
    }
}

/// Exit code of the `timeout` command that wraps the review agent
const REVIEW_TIMEOUT_EXIT_CODE: i32 = 124;

/// A slow review says nothing about the model, so no cooldown: the task goes back
/// to needs_review and the next review picks an agent as usual
async fn store_review_timeout<T>(
    store: &Arc<TaskStore>,
    run_id: Option<i64>,
    exit_code: i32,
    raw_output: &str,
    stderr: &str,
) -> ReviewPhase<T> {
    complete_review_run(
        store,
        run_id,
        Some(exit_code),
        raw_output,
        stderr,
        "",
        "timeout",
        "timeout",
        RunTokenUsage::default(),
    )
    .await;
    ReviewPhase::EarlyReturn(ReviewDecision::Failed("timeout".to_string()))
}

/// The decision is in when this attempt's final result parses as a review, whatever the session
/// does. Only this attempt's file counts, an older attempt may have reviewed another commit
async fn review_output_has_decision(ctx: &ReviewContext) -> bool {
    let raw = tokio::fs::read_to_string(&ctx.output_file)
        .await
        .unwrap_or_default();
    output_has_review_decision(&ctx.review_agent, &raw)
}

fn output_has_review_decision(agent: &str, raw: &str) -> bool {
    let raw = runner::agents::claude::strip_tty_control_lines(raw);
    runner::agents::find_agent_result(agent, &raw)
        .filter(|result| !result.is_error)
        .is_some_and(|result| runner::response::parse_review_response(&result.result_text).is_ok())
}

async fn wait_for_review_decision(ctx: &ReviewContext, poll_interval: std::time::Duration) {
    loop {
        tokio::time::sleep(poll_interval).await;
        if review_output_has_decision(ctx).await {
            return;
        }
    }
}

async fn record_review_agent_failure(
    task_id: &str,
    review_agent: &str,
    review_model: Option<&str>,
    err: &runner::agents::AgentError,
) {
    match err {
        runner::agents::AgentError::RateLimit { message }
        | runner::agents::AgentError::Auth { message } => {
            tracing::warn!(
                task_id,
                agent = %review_agent,
                "review agent hit error — adding to cooldown"
            );
            if let Some(reason) = crate::engine::cooldown::detect_credit_exhaustion(message) {
                if reason == crate::engine::cooldown::CreditExhaustionReason::BillingCycleExhausted
                {
                    if let Some(model) = review_model {
                        // Quota is model-scoped: don't penalize the whole agent.
                        crate::engine::cooldown::record_persistent_model_failure(
                            review_agent,
                            model,
                        )
                        .await;
                    } else {
                        crate::engine::cooldown::record_credit_exhaustion(review_agent, reason)
                            .await;
                    }
                } else {
                    crate::engine::cooldown::record_credit_exhaustion(review_agent, reason).await;
                }
            } else {
                runner::response::record_agent_failure_with_message(review_agent, &err.to_string())
                    .await;
            }
        }
        // Killed or truncated review run, not a model fault
        runner::agents::AgentError::Interrupted { .. } => {}
        runner::agents::AgentError::InvalidResponse { .. } => {
            // No usable review output, a short backoff since the model itself still works
            if let Some(model) = review_model {
                crate::engine::cooldown::record_transient_model_failure(review_agent, model).await;
            }
        }
        runner::agents::AgentError::ModelUnavailable { message, .. } => {
            // The agent is not penalized, its other models still route normally
            if let Some(model) = review_model {
                crate::engine::cooldown::record_model_unavailable(review_agent, model, message)
                    .await;
            }
        }
        _ => {
            // Generic failure (AgentFailed, NetworkError, etc.)
            // Apply standard model backoff (5min→4h max) to prevent immediate re-selection.
            if let Some(model) = review_model {
                crate::engine::cooldown::record_model_failure(review_agent, model).await;
            }
        }
    }
}

fn review_decision_from_response(
    review_response: runner::response::ReviewResponse,
) -> ReviewDecision {
    match review_response.decision.as_str() {
        "approve" => approve_from_evidence(review_response),
        "request_changes" => ReviewDecision::RequestChanges {
            notes: review_response.notes,
            issues: review_response.issues,
        },
        _ => ReviewDecision::Failed(format!("unknown decision: {}", review_response.decision)),
    }
}

/// An approve that reports failing tests or error-severity issues is treated as request_changes
fn approve_from_evidence(review_response: runner::response::ReviewResponse) -> ReviewDecision {
    let tests_failed = review_response
        .test_results
        .as_deref()
        .is_some_and(|s| s.trim().eq_ignore_ascii_case("fail"));
    let has_error = review_response
        .issues
        .iter()
        .any(|issue| issue.severity.trim().eq_ignore_ascii_case("error"));
    if tests_failed || has_error {
        let notes = if tests_failed {
            notes_for_failed_tests(review_response.notes)
        } else {
            review_response.notes
        };
        ReviewDecision::RequestChanges {
            notes,
            issues: review_response.issues,
        }
    } else {
        ReviewDecision::Approve {
            issues: review_response.issues,
        }
    }
}

fn notes_for_failed_tests(notes: String) -> String {
    const MARK: &str = "Review reported test_results: fail";
    if notes.trim().is_empty() {
        MARK.to_string()
    } else if notes.contains("test_results: fail") {
        notes
    } else {
        format!("{notes}\n\n{MARK}")
    }
}

fn review_decision_name(decision: &ReviewDecision) -> &'static str {
    match decision {
        ReviewDecision::Approve { .. } => "approve",
        ReviewDecision::RequestChanges { .. } => "request_changes",
        ReviewDecision::Failed(_) => "failed",
        ReviewDecision::Blocked(_) => "blocked",
        ReviewDecision::Skipped => "skipped",
        ReviewDecision::Rerouted => "rerouted",
    }
}

async fn parse_review_output(
    task: &ExternalTask,
    repo: &str,
    ctx: &ReviewContext,
    run: ReviewRun,
    store: &Arc<TaskStore>,
) -> ReviewPhase<ParsedReview> {
    let (file_exists, file_size, exit_code, stderr) = {
        let output_file_clone = ctx.output_file.clone();
        let review_attempt_dir_clone = ctx.review_attempt_dir.clone();
        match tokio::task::spawn_blocking(move || {
            let file_exists = output_file_clone.exists();
            let file_size = std::fs::metadata(&output_file_clone).map_or(0, |m| m.len());
            let exit_code = std::fs::read_to_string(review_attempt_dir_clone.join("exit.txt"))
                .ok()
                .and_then(|s| s.trim().parse::<i32>().ok())
                .unwrap_or(-1);
            let stderr = std::fs::read_to_string(review_attempt_dir_clone.join("stderr.txt"))
                .unwrap_or_default();
            (file_exists, file_size, exit_code, stderr)
        })
        .await
        {
            Ok(tuple) => tuple,
            Err(e) => {
                tracing::error!(
                    task_id = task.id.0,
                    error = %e,
                    "spawn_blocking panicked reading review output metadata"
                );
                (false, 0, -1, format!("spawn_blocking failed: {e}"))
            }
        }
    };

    tracing::info!(
        task_id = task.id.0,
        path = %ctx.output_file.display(),
        file_exists,
        file_size,
        "reading review agent output"
    );

    let raw_output =
        runner::response::read_output_file(&ctx.review_task_id, &ctx.output_file, repo).await;
    let raw_output = runner::agents::claude::strip_tty_control_lines(&raw_output);
    let has_result_envelope =
        runner::agents::claude::find_ndjson_result_line(&raw_output).is_some();
    let agent_result = runner::agents::find_agent_result(&ctx.review_agent, &raw_output);
    let token_usage = RunTokenUsage {
        input_tokens: agent_result
            .as_ref()
            .and_then(|r| r.input_tokens)
            .unwrap_or(0),
        output_tokens: agent_result
            .as_ref()
            .and_then(|r| r.output_tokens)
            .unwrap_or(0),
        total_cost_usd: agent_result
            .as_ref()
            .and_then(|r| r.cost_usd)
            .unwrap_or(0.0),
        duration_secs: 0.0,
    };

    let agent_result_is_error = agent_result.as_ref().is_some_and(|r| r.is_error);
    let ndjson_completed_no_error = raw_output.contains("\"terminal_reason\":\"completed\"")
        && !raw_output.contains("\"is_error\":true");
    // Do not short-circuit completed NDJSON sessions before rescue parsing.
    let is_hard_failure =
        !ndjson_completed_no_error && (raw_output.is_empty() || agent_result_is_error);

    if exit_code == REVIEW_TIMEOUT_EXIT_CODE
        && !output_has_review_decision(&ctx.review_agent, &raw_output)
    {
        tracing::error!(
            task_id = task.id.0,
            "review agent killed by its own timeout without a decision"
        );
        return store_review_timeout(store, run.run_id, exit_code, &raw_output, &stderr).await;
    }

    if is_hard_failure {
        tracing::warn!(
            task_id = task.id.0,
            exit_code,
            raw_output_len = raw_output.len(),
            stderr_len = stderr.len(),
            "review agent: entering error path"
        );
        let agent_runner = runner::agents::get_runner(&ctx.review_agent);
        let err = agent_runner.classify_error(exit_code, &raw_output, &stderr);
        record_review_agent_failure(
            &task.id.0,
            &ctx.review_agent,
            ctx.review_model.as_deref(),
            &err,
        )
        .await;
        tracing::error!(task_id = task.id.0, error = %err, "review agent failed");
        let stored_error = format_review_error(&ctx.review_agent, &err);
        complete_review_run(
            store,
            run.run_id,
            Some(exit_code),
            &raw_output,
            &stderr,
            "",
            outcome_for_agent_error(&err),
            &stored_error,
            token_usage,
        )
        .await;
        return ReviewPhase::EarlyReturn(ReviewDecision::Failed(stored_error));
    }

    let text_for_review = agent_result
        .as_ref()
        .map(|r| r.result_text.clone())
        .filter(|text| !text.is_empty())
        .unwrap_or_else(|| {
            tracing::debug!(
                task_id = task.id.0,
                agent = %ctx.review_agent,
                "review agent: per-agent extractor returned no text, using raw output"
            );
            raw_output.clone()
        });

    let review_response = match runner::response::parse_review_response(&text_for_review) {
        Ok(response) => response,
        Err(e) => {
            if let Some(response) = runner::response::infer_review_response(&text_for_review) {
                tracing::warn!(
                    task_id = task.id.0,
                    agent = %ctx.review_agent,
                    "review response parsed via keyword fallback"
                );
                response
            } else {
                // Guard: if the raw NDJSON signals a completed session
                // (terminal_reason:completed without is_error:true), do NOT run
                // generic pattern-based rate-limit detection over it. Token
                // counts in the telemetry blob can contain bare "429" values
                // that would otherwise be misclassified as HTTP 429 errors.
                let ndjson_completed = ndjson_completed_no_error;

                // Missing type:result (kimi/minimax) or terminal_reason:completed: recover
                // from assistant text. Never MiniMax parse_response, which synthesizes status=done
                if ndjson_completed || !has_result_envelope {
                    let assistant_text = runner::agents::collect_assistant_messages_text(
                        &ctx.review_agent,
                        &raw_output,
                    );
                    if !assistant_text.is_empty() {
                        if let Ok(response) =
                            runner::response::parse_review_response(&assistant_text)
                        {
                            tracing::debug!(
                                task_id = task.id.0,
                                agent = %ctx.review_agent,
                                "found review response JSON in assistant message (terminal_reason:completed)"
                            );
                            let review_notes_for_comment = response.notes.clone();
                            let decision = review_decision_from_response(response);
                            return ReviewPhase::Ready(ParsedReview {
                                run_id: run.run_id,
                                exit_code,
                                stderr,
                                raw_output,
                                text_for_review: assistant_text,
                                token_usage,
                                review_notes_for_comment,
                                decision,
                            });
                        }
                        if let Some(response) =
                            runner::response::infer_review_response(&assistant_text)
                        {
                            tracing::warn!(
                                task_id = task.id.0,
                                agent = %ctx.review_agent,
                                "inferred review response from assistant message (terminal_reason:completed)"
                            );
                            let review_notes_for_comment = response.notes.clone();
                            let decision = review_decision_from_response(response);
                            return ReviewPhase::Ready(ParsedReview {
                                run_id: run.run_id,
                                exit_code,
                                stderr,
                                raw_output,
                                text_for_review: assistant_text,
                                token_usage,
                                review_notes_for_comment,
                                decision,
                            });
                        }
                    }
                }

                // Scan only bounded head/tail windows, not the full review text.
                // The full transcript may contain agent work product (e.g. a
                // diff or markdown report quoting an `outcome`/`rate_limit`
                // table cell) that incidentally matches these patterns; real
                // CLI errors appear at the start or end of the output. See
                // `classify_from_text` in runner::agents for the same rationale.
                let scan_head = runner::agents::patterns::safe_head(
                    &text_for_review,
                    runner::agents::patterns::RATE_LIMIT_SCAN_HEAD_BYTES,
                );
                let scan_tail = runner::agents::patterns::safe_tail(
                    &text_for_review,
                    runner::agents::patterns::RATE_LIMIT_SCAN_TAIL_BYTES,
                );

                if let Some(err) = (!ndjson_completed)
                    .then(|| {
                        runner::agents::patterns::detect_rate_limit(scan_head)
                            .or_else(|| runner::agents::patterns::detect_rate_limit(scan_tail))
                    })
                    .flatten()
                {
                    let runner::agents::AgentError::RateLimit { message } = &err else {
                        unreachable!("detect_rate_limit only returns AgentError::RateLimit")
                    };
                    tracing::warn!(
                        task_id = task.id.0,
                        agent = %ctx.review_agent,
                        "review agent hit rate limit — adding to cooldown"
                    );
                    // Route through record_review_agent_failure/outcome_for_agent_error
                    // (not the generic record_agent_failure_with_message + hardcoded
                    // "rate_limit" string) so billing-cycle exhaustion messages caught by
                    // this inline text scan get the same model-scoped persistent cooldown
                    // and outcome classification as the AgentError-based failure path
                    // above (issue #3551, gap left by #3530).
                    let summary = runner::fallback::summarize_rate_limit_error(message);
                    let stored_error = format!("{} rate limit: {summary}", ctx.review_agent);
                    record_review_agent_failure(
                        &task.id.0,
                        &ctx.review_agent,
                        ctx.review_model.as_deref(),
                        &err,
                    )
                    .await;
                    complete_review_run(
                        store,
                        run.run_id,
                        Some(exit_code),
                        &raw_output,
                        &stderr,
                        &text_for_review,
                        outcome_for_agent_error(&err),
                        &stored_error,
                        token_usage,
                    )
                    .await;
                    return ReviewPhase::EarlyReturn(ReviewDecision::Failed(stored_error));
                }

                if let Some(err) = runner::agents::patterns::detect_auth_error(scan_tail) {
                    let runner::agents::AgentError::Auth { message } = &err else {
                        unreachable!("detect_auth_error only returns AgentError::Auth")
                    };
                    tracing::warn!(
                        task_id = task.id.0,
                        agent = %ctx.review_agent,
                        "review agent hit auth error — adding to cooldown"
                    );
                    let stored_error = format!("auth error: {message}");
                    record_review_agent_failure(
                        &task.id.0,
                        &ctx.review_agent,
                        ctx.review_model.as_deref(),
                        &err,
                    )
                    .await;
                    complete_review_run(
                        store,
                        run.run_id,
                        Some(exit_code),
                        &raw_output,
                        &stderr,
                        &text_for_review,
                        outcome_for_agent_error(&err),
                        &stored_error,
                        token_usage,
                    )
                    .await;
                    return ReviewPhase::EarlyReturn(ReviewDecision::Failed(stored_error));
                }

                // Cut off at the output token limit (opencode step_finish reason=length)
                if agent_result.as_ref().is_some_and(|r| r.truncated_by_length) {
                    tracing::warn!(
                        task_id = task.id.0,
                        agent = %ctx.review_agent,
                        model = ?ctx.review_model,
                        "review agent output truncated: step_finish reason=length \
                         (token budget exceeded before completion)"
                    );
                    if let Some(model) = ctx.review_model.as_deref() {
                        crate::engine::cooldown::record_transient_model_failure(
                            &ctx.review_agent,
                            model,
                        )
                        .await;
                    }
                    let stored_error = "truncated: review output was cut off before completion \
                        (output/reasoning token budget exceeded)"
                        .to_string();
                    complete_review_run(
                        store,
                        run.run_id,
                        Some(exit_code),
                        &raw_output,
                        &stderr,
                        &text_for_review,
                        "truncated",
                        &stored_error,
                        token_usage,
                    )
                    .await;
                    return ReviewPhase::EarlyReturn(ReviewDecision::Failed(stored_error));
                }

                // No envelope and last content is thinking/tool_use: retry without
                // the format-failure cooldown (issue #3734)
                if runner::agents::claude::review_session_exited_mid_thought(&raw_output) {
                    tracing::warn!(
                        task_id = task.id.0,
                        agent = %ctx.review_agent,
                        model = ?ctx.review_model,
                        "review session exited mid-thought with no result envelope \
                         — storing as incomplete and retrying without persistent cooldown"
                    );
                    let stored_error =
                        "incomplete: review session exited before producing a decision".to_string();
                    complete_review_run(
                        store,
                        run.run_id,
                        Some(exit_code),
                        &raw_output,
                        &stderr,
                        &text_for_review,
                        "incomplete",
                        &stored_error,
                        token_usage,
                    )
                    .await;
                    return ReviewPhase::EarlyReturn(ReviewDecision::Failed(stored_error));
                }

                tracing::error!(
                    task_id = task.id.0,
                    error = %e,
                    agent = %ctx.review_agent,
                    output = %text_for_review.chars().take(300).collect::<String>(),
                    raw_output = %raw_output.chars().take(1000).collect::<String>(),
                    "failed to parse review response"
                );
                if let Some(model) = ctx.review_model.as_deref() {
                    crate::engine::cooldown::record_transient_model_failure(
                        &ctx.review_agent,
                        model,
                    )
                    .await;
                }
                complete_review_run(
                    store,
                    run.run_id,
                    Some(exit_code),
                    &raw_output,
                    &stderr,
                    &text_for_review,
                    "parse_error",
                    &format!("parse error: {e}"),
                    token_usage,
                )
                .await;
                return ReviewPhase::EarlyReturn(ReviewDecision::Failed(format!(
                    "parse error: {e}"
                )));
            }
        }
    };

    let review_notes_for_comment = review_response.notes.clone();
    let decision = review_decision_from_response(review_response);

    tracing::info!(
        task_id = task.id.0,
        pr_number = ctx.pr_number,
        decision = ?decision,
        "review agent decision received"
    );
    store_log_activity(
        &Some(Arc::clone(store)),
        repo,
        &task.id.0,
        "review_decision",
        None,
        None,
        Some(&ctx.review_agent),
        ctx.review_model.as_deref(),
        Some(&serde_json::json!({
            "decision": review_decision_name(&decision),
            "pr_number": ctx.pr_number,
        })),
    )
    .await;
    if let Err(e) = crate::store::store_set_result(
        &Some(Arc::clone(store)),
        repo,
        &task.id.0,
        &[("review_resets", serde_json::json!(0))],
    )
    .await
    {
        tracing::warn!(task_id = task.id.0, err = %e, "failed to clear review_resets after a decision");
    }

    ReviewPhase::Ready(ParsedReview {
        run_id: run.run_id,
        exit_code,
        stderr,
        raw_output,
        text_for_review,
        token_usage,
        review_notes_for_comment,
        decision,
    })
}

async fn finalize_review_run(
    task: &ExternalTask,
    ctx: &ReviewContext,
    parsed: &ParsedReview,
    store: &Arc<TaskStore>,
) {
    let outcome = match &parsed.decision {
        ReviewDecision::Approve { .. }
        | ReviewDecision::RequestChanges { .. }
        | ReviewDecision::Skipped
        | ReviewDecision::Rerouted => "success",
        ReviewDecision::Failed(_) | ReviewDecision::Blocked(_) => "failed",
    };
    let error = match &parsed.decision {
        ReviewDecision::Failed(error) | ReviewDecision::Blocked(error) => error.as_str(),
        _ => "",
    };

    if outcome == "success" {
        // Mirror the runner's success path so review-only models don't ratchet
        // into multi-day cooldowns from isolated failures never offset by resets.
        crate::engine::cooldown::record_agent_success(&ctx.review_agent, ctx.review_model_str())
            .await;
    }

    complete_review_run(
        store,
        parsed.run_id,
        Some(parsed.exit_code),
        &parsed.raw_output,
        &parsed.stderr,
        &parsed.text_for_review,
        outcome,
        error,
        parsed.token_usage,
    )
    .await;

    if let Some(store_id) = ctx.store_id
        && (parsed.token_usage.input_tokens > 0 || parsed.token_usage.output_tokens > 0)
    {
        let model = if ctx.review_model_str().is_empty() {
            "unknown"
        } else {
            ctx.review_model_str()
        };
        if let Err(e) = store
            .store_tokens(
                store_id,
                parsed.token_usage.input_tokens,
                parsed.token_usage.output_tokens,
                model,
            )
            .await
        {
            tracing::warn!(
                task_id = task.id.0,
                ?e,
                "failed to store review agent token usage"
            );
        }
    }
}

async fn restore_review_config_if_needed(
    task_id: &str,
    worktree_path: &std::path::Path,
    default_branch: &str,
) {
    let _ = Command::new("git")
        .args(["checkout", "HEAD", "--", ".orch.yml"])
        .current_dir(worktree_path)
        .status()
        .await;

    let merge_base = Command::new("git")
        .args(["merge-base", "HEAD", default_branch])
        .current_dir(worktree_path)
        .output()
        .await
        .ok()
        .filter(|output| output.status.success())
        .and_then(|output| String::from_utf8(output.stdout).ok())
        .map(|s| s.trim().to_string())
        .unwrap_or_default();

    if merge_base.is_empty() {
        return;
    }

    let orch_yml_changed = Command::new("git")
        .args([
            "diff",
            "--name-only",
            &merge_base,
            "HEAD",
            "--",
            ".orch.yml",
        ])
        .current_dir(worktree_path)
        .output()
        .await
        .ok()
        .filter(|output| output.status.success())
        .is_some_and(|output| !output.stdout.is_empty());

    if !orch_yml_changed {
        return;
    }

    tracing::warn!(
        task_id,
        "review agent modified .orch.yml (forbidden); restoring to merge-base version"
    );
    let restore_ok = Command::new("git")
        .args(["checkout", &merge_base, "--", ".orch.yml"])
        .current_dir(worktree_path)
        .status()
        .await
        .is_ok_and(|status| status.success());

    if !restore_ok {
        return;
    }

    let staged = Command::new("git")
        .args(["diff", "--cached", "--name-only", "--", ".orch.yml"])
        .current_dir(worktree_path)
        .output()
        .await
        .ok()
        .filter(|output| output.status.success())
        .is_some_and(|output| !output.stdout.is_empty());

    if staged {
        let _ = Command::new("git")
            .args([
                "-c",
                "commit.gpgsign=false",
                "commit",
                "-m",
                "revert: restore .orch.yml (review agent must not modify project config)",
            ])
            .current_dir(worktree_path)
            .status()
            .await;
    }
}

fn is_missing_path_error_message(err: &str) -> bool {
    err.to_ascii_lowercase()
        .contains("no such file or directory")
}

async fn push_review_branch(
    task: &ExternalTask,
    repo: &str,
    ctx: &ReviewContext,
    store: &Arc<TaskStore>,
) -> Result<(), String> {
    let mut worktree_path = ctx.worktree_path.clone();
    let mut branch_name = ctx.branch_name.clone();
    let mut retried_missing_worktree = false;

    let push_result = loop {
        match runner::git_ops::push_branch(&worktree_path, &branch_name, &ctx.default_branch).await
        {
            Ok(ok) => break Ok(ok),
            Err(e)
                if !retried_missing_worktree
                    && !worktree_path.exists()
                    && is_missing_path_error_message(&e.to_string()) =>
            {
                retried_missing_worktree = true;
                tracing::warn!(
                    task_id = task.id.0,
                    worktree = %worktree_path.display(),
                    branch = %branch_name,
                    "review push failed because worktree disappeared; attempting one-time recovery"
                );
                match recover_missing_review_worktree(task, repo, store).await {
                    Ok(recovered) => {
                        worktree_path = recovered.work_dir;
                        branch_name = recovered.branch;
                    }
                    Err(recover_err) => {
                        break Err(anyhow::anyhow!(
                            "missing review worktree recovery failed after push error: {recover_err}"
                        ));
                    }
                }
            }
            Err(e) => break Err(e),
        }
    };

    match push_result {
        Ok(_) => {
            store_log_activity(
                &Some(Arc::clone(store)),
                repo,
                &task.id.0,
                "push",
                None,
                None,
                Some(&ctx.review_agent),
                ctx.review_model.as_deref(),
                Some(&serde_json::json!({
                    "status": "ok",
                    "branch": branch_name.clone(),
                    "default_branch": ctx.default_branch.clone(),
                    "phase": "review",
                })),
            )
            .await;
            if ctx.had_prev_push_failure
                && let Err(e) = store_set_result(
                    &Some(Arc::clone(store)),
                    repo,
                    &task.id.0,
                    &[
                        ("last_error", serde_json::json!("")),
                        ("push_failures", serde_json::json!(0)),
                    ],
                )
                .await
            {
                tracing::warn!(task_id = task.id.0, err = %e, "failed to reset push_failures — counter may drift");
            }
            Ok(())
        }
        Err(e) => {
            store_log_activity(
                &Some(Arc::clone(store)),
                repo,
                &task.id.0,
                "push",
                None,
                None,
                Some(&ctx.review_agent),
                ctx.review_model.as_deref(),
                Some(&serde_json::json!({
                    "status": "error",
                    "branch": branch_name.clone(),
                    "default_branch": ctx.default_branch.clone(),
                    "phase": "review",
                    "error": e.to_string(),
                })),
            )
            .await;
            tracing::error!(
                task_id = task.id.0,
                branch = %ctx.branch_name,
                error = %e,
                "review push failed"
            );
            store_set(
                &Some(Arc::clone(store)),
                repo,
                &task.id.0,
                &[("last_error", serde_json::json!(format!("push failed: {e}")))],
            )
            .await;
            Err(e.to_string())
        }
    }
}

fn append_review_issues(
    body: &mut String,
    issues: &[crate::engine::runner::response::ReviewIssue],
) {
    use std::fmt::Write as _;
    if issues.is_empty() {
        return;
    }
    body.push_str("\n**Issues Found:**\n");
    for issue in issues {
        let _ = writeln!(
            body,
            "- `{}` line {}: {} [{}]",
            issue.file,
            issue
                .line
                .map_or_else(|| "?".to_string(), |line| line.to_string()),
            issue.description,
            issue.severity
        );
    }
}

fn build_pr_review_comment(decision: &ReviewDecision, review_notes_for_comment: &str) -> String {
    match decision {
        ReviewDecision::Approve { issues } => {
            let mut body =
                format!("## Automated Review \u{2014} Approve\n\n{review_notes_for_comment}");
            if !issues.is_empty() && !body.ends_with('\n') {
                body.push('\n');
            }
            append_review_issues(&mut body, issues);
            body
        }
        ReviewDecision::RequestChanges { notes, issues } => {
            let mut body = format!("## Automated Review \u{2014} Changes Requested\n\n{notes}\n");
            append_review_issues(&mut body, issues);
            body
        }
        _ => String::new(),
    }
}

const REVIEW_STATUS_CONTEXT: &str = "orch/review";

/// Commit status state and description for a review decision. Other decisions post nothing.
fn review_status(decision: &ReviewDecision) -> Option<(&'static str, &'static str)> {
    match decision {
        ReviewDecision::Approve { .. } => Some(("success", "Approved by automated review")),
        ReviewDecision::RequestChanges { .. } => {
            Some(("failure", "Automated review requested changes"))
        }
        _ => None,
    }
}

/// Post `orch/review` on the SHA the review started from. A new push moves the PR head, so an
/// old decision never covers a new commit.
async fn post_review_status(
    gh: &GhHttp,
    repo: &str,
    sha: Option<&str>,
    state: &str,
    description: &str,
) {
    let Some(sha) = sha else {
        return;
    };
    if let Err(e) = gh
        .post_commit_status(repo, sha, state, REVIEW_STATUS_CONTEXT, description)
        .await
    {
        tracing::warn!(sha, error = %e, "failed to post orch/review commit status");
    }
}

async fn post_review_comment(
    task: &ExternalTask,
    repo: &str,
    ctx: &ReviewContext,
    decision: &ReviewDecision,
    review_notes_for_comment: &str,
) -> anyhow::Result<()> {
    let gh = match GhHttp::new() {
        Ok(gh) => gh,
        Err(e) => {
            tracing::warn!(
                task_id = task.id.0,
                error = %e,
                "failed to create GH client for review comment"
            );
            return Ok(());
        }
    };
    let mut pr_comment = build_pr_review_comment(decision, review_notes_for_comment);
    if ctx.same_agent_fallback && !pr_comment.is_empty() {
        pr_comment.push_str(
            "\n> Note: no other agent was available, so this PR was reviewed by the same agent in a new session.\n",
        );
    }

    // The agent may have rebased or committed a fix, pushed just before this, so the head read
    // before the review is stale and an App review on it would be refused or ignored
    let head_sha = worktree_head_sha(&ctx.worktree_path)
        .await
        .or_else(|| ctx.head_sha.clone());

    let app = review_app(repo).await;
    post_review_decision(
        app.as_deref(),
        &gh,
        repo,
        head_sha.as_deref(),
        decision,
        review_notes_for_comment,
    )
    .await;

    if !pr_comment.is_empty() {
        let footer =
            attribution_footer("Reviewed", &ctx.review_agent, Some(ctx.review_model_str()));
        let pr_comment_with_footer = format!("{pr_comment}{footer}");
        if let Err(e) = publish_review(
            app.as_deref(),
            &gh,
            repo,
            ctx.pr_number,
            head_sha.as_deref(),
            decision,
            &pr_comment_with_footer,
        )
        .await
        {
            tracing::warn!(
                task_id = task.id.0,
                pr_number = ctx.pr_number,
                error = %e,
                "failed to post automated review comment on PR"
            );
        }
    }

    Ok(())
}

/// The App to review `repo` with, `None` in comment mode or where the App is not installed
async fn review_app(repo: &str) -> Option<Arc<crate::github::app::AppAuth>> {
    let mode = crate::review_mode::for_repo(repo);
    review_app_for(mode, crate::github::app::shared(), repo).await
}

async fn review_app_for(
    mode: crate::review_mode::ReviewMode,
    app: Option<Arc<crate::github::app::AppAuth>>,
    repo: &str,
) -> Option<Arc<crate::github::app::AppAuth>> {
    if mode != crate::review_mode::ReviewMode::App {
        return None;
    }

    let app = app?;
    match app.token_for_repo(repo).await {
        Ok(Some(_)) => Some(app),
        Ok(None) => {
            tracing::info!(
                repo,
                "review.mode is app but the App is not installed here, reviewing with a comment"
            );
            None
        }
        Err(e) => {
            tracing::warn!(repo, error = %e, "App installation lookup failed, reviewing with a comment");
            None
        }
    }
}

/// `orch/review` as an App check run in app mode, as a commit status in comment mode
async fn post_review_started(
    app: Option<&crate::github::app::AppAuth>,
    gh: &GhHttp,
    repo: &str,
    sha: Option<&str>,
) {
    use crate::github::app::CheckRunState;
    match (app, sha) {
        (Some(app), Some(sha)) => {
            if let Err(e) = app
                .post_check_run(repo, sha, CheckRunState::InProgress)
                .await
            {
                tracing::warn!(sha, error = %e, "failed to post the orch/review check run");
            }
        }
        _ => post_review_status(gh, repo, sha, "pending", "Automated review running").await,
    }
}

async fn post_review_decision(
    app: Option<&crate::github::app::AppAuth>,
    gh: &GhHttp,
    repo: &str,
    sha: Option<&str>,
    decision: &ReviewDecision,
    notes: &str,
) {
    use crate::github::app::CheckRunState;
    let Some((state, description)) = review_status(decision) else {
        return;
    };

    match (app, sha) {
        (Some(app), Some(sha)) => {
            let approved = state == "success";
            let completed = CheckRunState::Completed {
                approved,
                summary: if notes.is_empty() { description } else { notes },
            };
            if let Err(e) = app.post_check_run(repo, sha, completed).await {
                tracing::warn!(sha, error = %e, "failed to complete the orch/review check run");
            }
        }
        _ => post_review_status(gh, repo, sha, state, description).await,
    }
}

/// Submit the decision as an App review on the sha the agent read, with the issues on diff lines
/// as inline comments. The `## Automated Review` comment goes out only without an App or when
/// GitHub refuses the review, so the decision always lands somewhere
async fn publish_review(
    app: Option<&crate::github::app::AppAuth>,
    gh: &GhHttp,
    repo: &str,
    pr_number: u64,
    head_sha: Option<&str>,
    decision: &ReviewDecision,
    comment: &str,
) -> anyhow::Result<()> {
    use crate::github::app::ReviewEvent;
    let event = match decision {
        ReviewDecision::Approve { .. } => Some(ReviewEvent::Approve),
        ReviewDecision::RequestChanges { .. } => Some(ReviewEvent::RequestChanges),
        _ => None,
    };
    if let (Some(app), Some(sha), Some(event)) = (app, head_sha, event) {
        let inline = inline_comments(app, repo, pr_number, decision).await;
        match app
            .submit_review(repo, pr_number, event, comment, sha, &inline)
            .await
        {
            Ok(()) => return Ok(()),
            Err(e) => {
                tracing::warn!(pr_number, sha, error = %e, "failed to submit App review, posting the decision as a comment");
            }
        }
    }
    gh.add_comment(repo, &pr_number.to_string(), comment).await
}

/// Issues on a changed line become inline comments, the rest stay in the review body, which
/// already lists every issue. GitHub refuses a review whose comment points outside the diff
async fn inline_comments(
    app: &crate::github::app::AppAuth,
    repo: &str,
    pr_number: u64,
    decision: &ReviewDecision,
) -> Vec<crate::github::app::InlineComment> {
    let ReviewDecision::RequestChanges { issues, .. } = decision else {
        return Vec::new();
    };

    if issues.is_empty() {
        return Vec::new();
    }

    match app.pull_request_hunks(repo, pr_number).await {
        Ok(hunks) => crate::github::app::split_inline(issues, &hunks).0,
        Err(e) => {
            tracing::warn!(pr_number, error = %e, "could not read the PR diff, issues stay in the review body");
            Vec::new()
        }
    }
}

#[expect(
    clippy::too_many_arguments,
    reason = "applying a decision touches the backend, the store, tmux and the router"
)]
async fn apply_review_decision(
    task: &ExternalTask,
    backend: &Arc<dyn ExternalBackend>,
    repo: &str,
    task_manager: &Arc<TaskManager>,
    store: &Arc<TaskStore>,
    ctx: &ReviewContext,
    parsed: &ParsedReview,
    router_config: &crate::engine::router::RouterConfig,
) -> anyhow::Result<ReviewDecision> {
    restore_review_config_if_needed(&task.id.0, &ctx.worktree_path, &ctx.default_branch).await;

    if let Err(e) = push_review_branch(task, repo, ctx, store).await {
        return Ok(ReviewDecision::Failed(format!("push failed: {e}")));
    }

    post_review_comment(
        task,
        repo,
        ctx,
        &parsed.decision,
        &parsed.review_notes_for_comment,
    )
    .await?;

    match &parsed.decision {
        ReviewDecision::Approve { .. } => {
            record_approved_sha(
                store,
                repo,
                &task.id.0,
                ctx.pr_number,
                &ctx.worktree_path,
                &ctx.branch_name,
                &ctx.default_branch,
            )
            .await;
            // Always attempt auto-merge on approval. Tasks are only marked
            // Done when the PR is actually merged (detected by review_poll).
            // Never mark Done on approval alone — that closes the issue
            // before the code lands.
            if let Err(e) = auto_merge_pr(
                task,
                &ctx.branch_name,
                backend,
                repo,
                &ctx.review_agent,
                ctx.review_model_str(),
                task_manager,
                store,
            )
            .await
            {
                let error_msg = e.to_string();
                if error_msg.contains("not yet computed") {
                    tracing::warn!(
                        task_id = task.id.0,
                        pr_number = ctx.pr_number,
                        branch = %ctx.branch_name,
                        error = %e,
                        "auto-merge deferred — PR mergeability not yet computed"
                    );
                } else {
                    tracing::error!(
                        task_id = task.id.0,
                        pr_number = ctx.pr_number,
                        branch = %ctx.branch_name,
                        error = %e,
                        "auto-merge failed"
                    );
                }
                return Ok(ReviewDecision::Failed(format!("merge failed: {e}")));
            }
            Ok(parsed.decision.clone())
        }
        ReviewDecision::RequestChanges { notes, issues } => {
            clear_approved_sha(store, repo, &task.id.0, ctx.pr_number).await;
            handle_review_changes(
                task,
                notes,
                issues,
                backend,
                repo,
                ctx.pr_number,
                &ctx.review_agent,
                ctx.review_model_str(),
                task_manager,
                store,
                router_config,
            )
            .await?;
            Ok(parsed.decision.clone())
        }
        _ => Ok(parsed.decision.clone()),
    }
}

async fn recover_missing_review_worktree(
    task: &ExternalTask,
    repo: &str,
    store: &Arc<TaskStore>,
) -> anyhow::Result<worktree::WorktreeSetup> {
    let project_dir = crate::config::get_projects_with_paths()?
        .into_iter()
        .find(|(candidate_repo, _)| candidate_repo == repo)
        .map(|(_, project_dir)| project_dir)
        .ok_or_else(|| anyhow::anyhow!("no project directory configured for repo {repo}"))?;

    tracing::warn!(
        task_id = task.id.0,
        repo,
        project_dir = %project_dir.display(),
        "review worktree missing, recreating via normal setup"
    );

    let store_ref = Some(Arc::clone(store));
    let wt = worktree::setup_worktree(&task.id.0, &task.title, &project_dir, &store_ref, repo)
        .await
        .context("recreating missing review worktree")?;

    if !wt.work_dir.exists() {
        anyhow::bail!(
            "recreated review worktree at {} for task {} is still missing",
            wt.work_dir.display(),
            task.id.0
        );
    }

    Ok(wt)
}

/// Count commits on the worktree branch that are ahead of `origin/<default_branch>`.
///
/// Returns `Err` when the git command cannot determine the count (e.g., missing
/// remote ref, non-zero exit, unparseable output). Callers must NOT treat this
/// as zero — a failure means the ancestry relationship is unknown.
async fn count_ahead_commits(
    worktree_path: &std::path::Path,
    default_branch: &str,
) -> Result<u64, String> {
    let worktree_str = worktree_path.to_str().ok_or_else(|| {
        format!(
            "worktree path contains non-UTF-8 characters: {}",
            worktree_path.display()
        )
    })?;

    let output = tokio::process::Command::new("git")
        .args([
            "-C",
            worktree_str,
            "rev-list",
            "--count",
            &format!("origin/{default_branch}..HEAD"),
        ])
        .output()
        .await
        .map_err(|e| format!("git rev-list command failed to start: {e}"))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
        return Err(format!(
            "git rev-list exited with {:?}: {}",
            output.status.code(),
            if stderr.is_empty() {
                String::from_utf8_lossy(&output.stdout).trim().to_string()
            } else {
                stderr
            }
        ));
    }

    String::from_utf8_lossy(&output.stdout)
        .trim()
        .parse::<u64>()
        .map_err(|e| format!("could not parse git rev-list output as u64: {e}"))
}

/// Ensure an open PR exists for the task branch before running the review agent.
///
/// Checks the store first (avoids GitHub list-API cache race), then the API.
/// If no PR exists but the branch has commits, attempts to create one and
/// continues with the same review pass.
/// All error and no-op paths update task status and return [`EnsurePrResult::EarlyReturn`].
#[expect(
    clippy::too_many_arguments,
    reason = "every early return path needs its own piece of review state"
)]
async fn ensure_pr_exists(
    task: &ExternalTask,
    branch_name: &str,
    worktree_path: &std::path::Path,
    repo: &str,
    agent_summary: &str,
    store: &Arc<TaskStore>,
    task_manager: &Arc<TaskManager>,
    stored_pr_number: Option<u64>,
) -> anyhow::Result<EnsurePrResult> {
    let gh_check = GhHttp::new()?;

    if let Some(n) = stored_pr_number {
        tracing::info!(
            task_id = task.id.0,
            pr_number = n,
            branch = %branch_name,
            "open PR found in store, proceeding with review"
        );
        return Ok(EnsurePrResult::Ready(n));
    }

    match gh_check.get_pr_number(repo, branch_name).await {
        Ok(Some(n)) => {
            tracing::info!(
                task_id = task.id.0,
                pr_number = n,
                branch = %branch_name,
                "open PR found, proceeding with review"
            );
            Ok(EnsurePrResult::Ready(n))
        }
        Ok(None) => {
            // No open PR — check if branch has commits ahead of default branch.
            let default_branch = worktree::detect_default_branch(worktree_path).await;
            let has_commits = match count_ahead_commits(worktree_path, &default_branch).await {
                Ok(count) => count > 0,
                Err(e) => {
                    tracing::error!(
                        task_id = task.id.0,
                        branch = %branch_name,
                        default_branch = %default_branch,
                        err = %e,
                        "could not determine if branch has commits ahead of default"
                    );
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                        format!("git ancestry check failed: {e}"),
                    )));
                }
            };

            if has_commits {
                // Branch has unpushed or un-PR'd work — try to create a PR
                tracing::warn!(
                    task_id = task.id.0,
                    branch = %branch_name,
                    "no open PR but branch has commits — attempting to create PR"
                );
                let worktree_str = worktree_path.to_str().ok_or_else(|| {
                    anyhow::anyhow!(
                        "worktree path contains non-UTF-8 characters: {}",
                        worktree_path.display()
                    )
                })?;
                // Push first in case agent forgot (use token auth like git_ops::push_branch)

                // Run a credentialed push and log any errors so failures are
                // visible in logs instead of being silently discarded.
                // Wrap with a timeout to prevent indefinitely blocking a Tokio worker on a
                // hung network connection (corporate proxy, partial GitHub outage, TCP hang).
                let push_timeout = std::time::Duration::from_secs(120);
                match tokio::time::timeout(
                    push_timeout,
                    crate::engine::runner::git_ops::git()
                        .await
                        .args(["-C", worktree_str, "push", "-u", "origin", branch_name])
                        .output(),
                )
                .await
                {
                    Err(_elapsed) => {
                        tracing::warn!(
                            task_id = task.id.0,
                            branch = %branch_name,
                            timeout_secs = push_timeout.as_secs(),
                            "review gate fallback push timed out"
                        );
                    }
                    Ok(Ok(o)) => {
                        if o.status.success() {
                            tracing::info!(task_id = task.id.0, branch = %branch_name, "review gate fallback push succeeded");
                        } else {
                            tracing::warn!(
                                task_id = task.id.0,
                                branch = %branch_name,
                                exit_code = ?o.status.code(),
                                stdout = %String::from_utf8_lossy(&o.stdout),
                                stderr = %String::from_utf8_lossy(&o.stderr),
                                "review gate fallback push failed"
                            );
                        }
                    }
                    Ok(Err(e)) => {
                        tracing::error!(
                            task_id = task.id.0,
                            branch = %branch_name,
                            error = %e,
                            "review gate fallback push command failed to run"
                        );
                    }
                }

                let task_ref = runner::git_ops::format_task_ref(&task.id.0);
                let pr_body = format!(
                    "Resolves {task_ref}\n\nAuto-created by orch review gate (agent forgot to open PR)"
                );
                let gh = GhHttp::new()?;
                match gh
                    .create_pr(repo, &task.title, &pr_body, branch_name, &default_branch)
                    .await
                {
                    Ok(url) => match parse_pr_number_from_url(&url) {
                        Ok(pr_num) => {
                            store_set_result(
                                &Some(Arc::clone(store)),
                                repo,
                                &task.id.0,
                                &[("pr_number", serde_json::json!(pr_num))],
                            )
                            .await?;
                            tracing::info!(
                                task_id = task.id.0,
                                branch = %branch_name,
                                pr_url = %url,
                                "created missing PR via GhHttp — continuing review"
                            );
                            Ok(EnsurePrResult::Ready(pr_num))
                        }
                        Err(e) => {
                            tracing::warn!(
                                task_id = task.id.0,
                                branch = %branch_name,
                                pr_url = %url,
                                error = %e,
                                "created missing PR via GhHttp, but failed to parse PR number"
                            );
                            Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                                format!("created missing PR, but could not parse PR number: {e}"),
                            )))
                        }
                    },
                    Err(e) => {
                        let e_str = format!("{e}");
                        if e_str.contains("already exists") {
                            // GitHub list-API cache may be stale immediately after a 422.
                            // Use two attempts with exponential backoff (2s → 4s) to avoid
                            // racing into a duplicate `gh pr create` call.
                            let backoff_delays = [2u64, 4u64];
                            let mut found_pr: Option<u64> = None;
                            for delay_secs in backoff_delays {
                                tokio::time::sleep(tokio::time::Duration::from_secs(delay_secs))
                                    .await;
                                if let Ok(Some(n)) = gh_check.get_pr_number(repo, branch_name).await
                                {
                                    found_pr = Some(n);
                                    break;
                                }
                            }
                            if let Some(n) = found_pr {
                                tracing::info!(
                                    task_id = task.id.0,
                                    pr_number = n,
                                    branch = %branch_name,
                                    "found existing PR after create_pr 422 — retrying review"
                                );
                                store_set_result(
                                    &Some(Arc::clone(store)),
                                    repo,
                                    &task.id.0,
                                    &[("pr_number", serde_json::json!(n))],
                                )
                                .await?;
                                return Ok(EnsurePrResult::Ready(n));
                            }
                        }
                        tracing::warn!(
                            task_id = task.id.0,
                            branch = %branch_name,
                            error = %e,
                            "create_pr failed via GhHttp, falling back to CLI"
                        );
                        // Fall back to CLI. Wrap the `gh pr create` call in a timeout so
                        // a hung CLI/network does not block the review pipeline.
                        let pr_timeout = std::time::Duration::from_secs(120);
                        let mut gh_cmd = tokio::process::Command::new("gh");
                        gh_cmd.args([
                            "pr",
                            "create",
                            "--repo",
                            repo,
                            "--head",
                            branch_name,
                            "--title",
                            &task.title,
                            "--body",
                            &pr_body,
                        ]);
                        gh_cmd.current_dir(worktree_path);
                        gh_cmd.kill_on_drop(true);

                        let pr_result = tokio::time::timeout(pr_timeout, gh_cmd.output()).await;
                        match pr_result {
                            Ok(Ok(o)) if o.status.success() => {
                                let stdout = String::from_utf8_lossy(&o.stdout);
                                match parse_pr_number_from_url(stdout.trim()) {
                                    Ok(pr_num) => {
                                        store_set_result(
                                            &Some(Arc::clone(store)),
                                            repo,
                                            &task.id.0,
                                            &[("pr_number", serde_json::json!(pr_num))],
                                        )
                                        .await?;
                                        tracing::info!(
                                            task_id = task.id.0,
                                            branch = %branch_name,
                                            "created missing PR via CLI — continuing review"
                                        );
                                        Ok(EnsurePrResult::Ready(pr_num))
                                    }
                                    Err(e) => {
                                        tracing::warn!(
                                            task_id = task.id.0,
                                            branch = %branch_name,
                                            stdout = %stdout,
                                            error = %e,
                                            "created missing PR via CLI, but failed to parse PR number"
                                        );
                                        Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                                            format!(
                                                "created missing PR via CLI, but could not parse PR number: {e}"
                                            ),
                                        )))
                                    }
                                }
                            }
                            Ok(Ok(o)) => {
                                let stderr = String::from_utf8_lossy(&o.stderr);
                                if stderr.contains("already exists")
                                    && let Some(pr_url) =
                                        stderr.lines().find(|l| l.trim().starts_with("https://"))
                                {
                                    match parse_pr_number_from_url(pr_url.trim()) {
                                        Ok(pr_num) => {
                                            if let Err(e) = store_set_result(
                                                &Some(Arc::clone(store)),
                                                repo,
                                                &task.id.0,
                                                &[("pr_number", serde_json::json!(pr_num))],
                                            )
                                            .await
                                            {
                                                tracing::warn!(
                                                    task_id = task.id.0,
                                                    pr_num,
                                                    err = %e,
                                                    "failed to persist pr_number from already-exists recovery — downstream may retry PR creation"
                                                );
                                            }
                                            tracing::info!(
                                                task_id = task.id.0,
                                                branch = %branch_name,
                                                pr_url = %pr_url,
                                                "PR already exists (from CLI stderr) — retrying review"
                                            );
                                            return Ok(EnsurePrResult::Ready(pr_num));
                                        }
                                        Err(e) => {
                                            tracing::warn!(
                                                task_id = task.id.0,
                                                branch = %branch_name,
                                                pr_url = %pr_url,
                                                error = %e,
                                                "found existing PR URL in CLI stderr, but failed to parse PR number"
                                            );
                                            // Continue to the error handling below
                                        }
                                    }
                                }
                                tracing::error!(
                                    task_id = task.id.0,
                                    branch = %branch_name,
                                    stderr = %stderr,
                                    "failed to create missing PR — work may be stuck"
                                );

                                // If this was a transient GitHub 5xx or transport error,
                                // do NOT increment the persistent pr_create_failures counter
                                // (which would eventually block the task). Let the
                                // engine retry later. Detect via git_ops::is_transient_github_api_error
                                // so generic agent/model transport errors (e.g. broken pipe)
                                // are NOT mis-classified as GitHub API transients.
                                if crate::engine::runner::git_ops::is_transient_github_api_error(
                                    &stderr,
                                ) {
                                    tracing::warn!(
                                        task_id = task.id.0,
                                        branch = %branch_name,
                                        "transient GitHub error creating PR; will retry later without incrementing persistent failure counter"
                                    );
                                    return Ok(EnsurePrResult::EarlyReturn(
                                        ReviewDecision::Failed(format!(
                                            "transient github error creating PR: {stderr}"
                                        )),
                                    ));
                                }

                                match store_increment(
                                    &Some(Arc::clone(store)),
                                    repo,
                                    &task.id.0,
                                    "pr_create_failures",
                                )
                                .await
                                {
                                    Ok(failures) if failures >= MAX_PR_CREATE_FAILURES => {
                                        return Ok(EnsurePrResult::EarlyReturn(
                                            ReviewDecision::Blocked(format!(
                                                "no PR, create failed {failures} times: {stderr}"
                                            )),
                                        ));
                                    }
                                    Ok(_) => {}
                                    Err(e) => {
                                        tracing::warn!(task_id = task.id.0, err = %e, "failed to increment pr_create_failures — skipping blocking decision this tick");
                                    }
                                }
                                Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                                    format!("no PR, create failed: {stderr}"),
                                )))
                            }
                            Ok(Err(e)) => {
                                tracing::error!(
                                    task_id = task.id.0,
                                    error = %e,
                                    "failed to run gh pr create"
                                );
                                let e_str = format!("{e}");
                                if crate::engine::runner::git_ops::is_transient_github_api_error(
                                    &e_str,
                                ) {
                                    tracing::warn!(
                                        task_id = task.id.0,
                                        branch = %branch_name,
                                        "transient GitHub error from gh CLI fallback; will retry later without incrementing persistent failure counter"
                                    );
                                    return Ok(EnsurePrResult::EarlyReturn(
                                        ReviewDecision::Failed(format!("transient gh error: {e}")),
                                    ));
                                }

                                match store_increment(
                                    &Some(Arc::clone(store)),
                                    repo,
                                    &task.id.0,
                                    "pr_create_failures",
                                )
                                .await
                                {
                                    Ok(failures) if failures >= MAX_PR_CREATE_FAILURES => {
                                        return Ok(EnsurePrResult::EarlyReturn(
                                            ReviewDecision::Blocked(format!(
                                                "no PR, gh error {failures} times: {e}"
                                            )),
                                        ));
                                    }
                                    Ok(_) => {}
                                    Err(e) => {
                                        tracing::warn!(task_id = task.id.0, err = %e, "failed to increment pr_create_failures — skipping blocking decision this tick");
                                    }
                                }
                                Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                                    format!("no PR, gh error: {e}"),
                                )))
                            }
                            Err(_elapsed) => {
                                // Timeout from tokio::time::timeout
                                tracing::error!(
                                    task_id = task.id.0,
                                    timeout_secs = pr_timeout.as_secs(),
                                    "gh pr create CLI fallback timed out"
                                );
                                let e_str = format!(
                                    "gh pr create timed out after {}s",
                                    pr_timeout.as_secs()
                                );
                                if crate::engine::runner::git_ops::is_transient_github_api_error(
                                    &e_str,
                                ) {
                                    tracing::warn!(
                                        task_id = task.id.0,
                                        branch = %branch_name,
                                        "transient GitHub timeout from gh CLI fallback; will retry later without incrementing persistent failure counter"
                                    );
                                    return Ok(EnsurePrResult::EarlyReturn(
                                        ReviewDecision::Failed(format!(
                                            "transient gh error: {e_str}"
                                        )),
                                    ));
                                }

                                match store_increment(
                                    &Some(Arc::clone(store)),
                                    repo,
                                    &task.id.0,
                                    "pr_create_failures",
                                )
                                .await
                                {
                                    Ok(failures) if failures >= MAX_PR_CREATE_FAILURES => {
                                        return Ok(EnsurePrResult::EarlyReturn(
                                            ReviewDecision::Blocked(format!(
                                                "no PR, gh timeout {failures} times: {e_str}"
                                            )),
                                        ));
                                    }
                                    Ok(_) => {}
                                    Err(e) => {
                                        tracing::warn!(task_id = task.id.0, err = %e, "failed to increment pr_create_failures — skipping blocking decision this tick");
                                    }
                                }
                                Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                                    format!("no PR, gh timeout: {e_str}"),
                                )))
                            }
                        }
                    }
                }
            } else {
                // No PR and no commits — agent either failed or completed a read-only task.
                let merged = match gh_check.is_pr_merged(repo, branch_name).await {
                    Ok(v) => v,
                    Err(e) => {
                        tracing::warn!(task_id = task.id.0, branch = %branch_name, err = %e, "merge check failed, skipping task this tick");
                        return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                            format!("merge check failed: {e}"),
                        )));
                    }
                };
                if merged {
                    tracing::info!(
                        task_id = task.id.0,
                        branch = %branch_name,
                        "PR already merged, marking done"
                    );
                    if let Err(e) = task_manager
                        .update_task_status(&task.id, Status::Done)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status(Done) failed — task may be stuck in InReview");
                    }
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Skipped));
                }

                let last_error = opt_store_get_task(&Some(Arc::clone(store)), repo, &task.id.0)
                    .await
                    .map(|t| t.last_error)
                    .unwrap_or_default();
                let reason = if agent_summary.is_empty() {
                    last_error.clone()
                } else {
                    agent_summary.to_string()
                };

                if last_error.contains("exceeded max attempts") {
                    tracing::warn!(
                        task_id = task.id.0,
                        branch = %branch_name,
                        "no PR and no commits after max attempts — marking blocked to stop loop"
                    );
                    // Write block_reason atomically with the status transition to prevent
                    // auto_unblock_blocked_tasks (block_reason.is_none() gate) from
                    // re-dispatching this task.
                    let fields = [
                        (
                            "block_reason",
                            serde_json::json!("max attempts exceeded — no PR or commits produced"),
                        ),
                        ("last_error", serde_json::json!(last_error)),
                    ];
                    if let Err(e) = task_manager
                        .update_task_status_and_result(&task.id, Status::Blocked, &fields)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status_and_result(Blocked) failed — skipping block to avoid silent auto-unblock loop");
                        return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                            format!("failed to write block_reason: {e}"),
                        )));
                    }
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Skipped));
                }

                if last_error.contains("422") && last_error.contains("head") {
                    tracing::info!(
                        task_id = task.id.0,
                        branch = %branch_name,
                        "no PR — 422/head-invalid means work already merged, marking done"
                    );
                    if let Err(e) = task_manager
                        .update_task_status(&task.id, Status::Done)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status(Done) failed");
                    }
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Skipped));
                }

                if last_error.contains("no fallback agents")
                    || last_error.contains("all agents exhausted")
                {
                    tracing::warn!(
                        task_id = task.id.0,
                        branch = %branch_name,
                        last_error = %last_error,
                        "no PR and no commits after failover exhaustion — marking blocked to stop loop"
                    );
                    // Write block_reason atomically with the status transition to prevent
                    // auto_unblock_blocked_tasks (block_reason.is_none() gate) from
                    // re-dispatching this task.
                    let fields = [
                        (
                            "block_reason",
                            serde_json::json!("all agents exhausted — no PR or commits produced"),
                        ),
                        ("last_error", serde_json::json!(last_error)),
                    ];
                    if let Err(e) = task_manager
                        .update_task_status_and_result(&task.id, Status::Blocked, &fields)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status_and_result(Blocked) failed — skipping block to avoid silent auto-unblock loop");
                        return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                            format!("failed to write block_reason: {e}"),
                        )));
                    }
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Skipped));
                }

                // No PR and no commits — agent either failed or completed a read-only task.
                // Use a dedicated circuit-breaker counter persisted in the store so
                // repeated reroutes across separate runs are counted. This prevents
                // internal tasks from looping new→in_progress→needs_review→new indefinitely.
                // Prefer a dedicated config key `workflow.max_reroute_attempts` (fallback to
                // `workflow.max_attempts` for backwards compatibility).
                let max_reroutes: u32 = config::get("workflow.max_reroute_attempts")
                    .ok()
                    .and_then(|s| s.parse().ok())
                    .or_else(|| {
                        config::get("workflow.max_attempts")
                            .ok()
                            .and_then(|s| s.parse().ok())
                    })
                    .unwrap_or(3);

                tracing::warn!(
                    task_id = task.id.0,
                    branch = %branch_name,
                    reason = %reason,
                    "no PR and no commits — re-routing for retry"
                );

                // If the last_error indicates a transient GitHub 5xx/transport error,
                // do NOT increment the persistent reroute counter which would
                // eventually block the task. Instead, retry later.
                if should_skip_no_code_reroute_increment(&last_error) {
                    tracing::warn!(
                        task_id = task.id.0,
                        last_error = %last_error,
                        "transient GitHub error recorded; skipping persistent no_pr_reroutes increment"
                    );
                    return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                        format!("transient github error: {last_error}"),
                    )));
                }

                // Atomically increment the persistent reroute counter and decide.
                let reroutes = match store_increment(
                    &Some(Arc::clone(store)),
                    repo,
                    &task.id.0,
                    "no_code_reroutes",
                )
                .await
                {
                    Ok(v) => v,
                    Err(e) => {
                        tracing::warn!(task_id = task.id.0, err = %e, "failed to increment no_code_reroutes — skipping reroute/block decision this tick");
                        // Skip action this tick
                        return Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                            format!("transient store error: {e}"),
                        )));
                    }
                };

                if reroutes >= u64::from(max_reroutes) {
                    tracing::error!(
                        task_id = task.id.0,
                        reroutes,
                        max_reroutes,
                        "reached max reroute attempts for no-pr-result — blocking for human review"
                    );
                    let msg = format!(
                        "no PR or code changes after {reroutes}/{max_reroutes} reroute attempts"
                    );
                    // Write block_reason atomically with the status transition to prevent
                    // auto_unblock_blocked_tasks (block_reason.is_none() gate) from
                    // re-dispatching this task.
                    let fields = [
                        (
                            "block_reason",
                            serde_json::json!(format!(
                                "max reroute attempts ({}) reached — no PR or code changes produced",
                                max_reroutes
                            )),
                        ),
                        ("last_error", serde_json::json!(msg)),
                        ("agent", serde_json::json!(null)),
                        ("model", serde_json::json!(null)),
                    ];
                    if let Err(e) = task_manager
                        .update_task_status_and_result(&task.id, Status::Blocked, &fields)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status_and_result(Blocked) failed — skipping block to avoid silent auto-unblock loop");
                    }
                    Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Blocked(msg)))
                } else if task.id.0.starts_with("internal:") {
                    // Internal tasks with no PR or code changes are read-only/analysis
                    // tasks (e.g. morning briefing, evening retrospective) that
                    // legitimately produce no git-visible changes. Mark them done
                    // instead of re-routing, which would create a loop: needs_review
                    // → review agent → no PR/no commits → reroute to New → agent
                    // runs → needs_review → ...
                    tracing::info!(
                        task_id = task.id.0,
                        "no PR and no commits for internal task — marking done"
                    );
                    if let Err(e) = task_manager
                        .update_task_status(&task.id, Status::Done)
                        .await
                    {
                        tracing::error!(task_id = task.id.0, err = %e, "update_task_status(Done) failed — task may be stuck in InReview");
                    }
                    Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Skipped))
                } else {
                    // Clear agent/model so router picks a different one and note the
                    // fact that this attempt produced no PR or code changes.
                    // Use store_set_result so we only transition status when the
                    // store write succeeds — partial failure would orphan the task.
                    match store_set_result(
                        &Some(Arc::clone(store)),
                        repo,
                        &task.id.0,
                        &[
                            ("agent", serde_json::json!(null)),
                            ("model", serde_json::json!(null)),
                            (
                                "last_error",
                                serde_json::json!("no PR or code changes produced"),
                            ),
                        ],
                    )
                    .await
                    {
                        Err(e) => {
                            tracing::error!(task_id = task.id.0, err = %e, "failed to clear agent/model for reroute — skipping status transition");
                            // Don't update status — task stays in InReview and will be retried next tick
                        }
                        _ => {
                            if let Err(e) =
                                task_manager.update_task_status(&task.id, Status::New).await
                            {
                                tracing::error!(task_id = task.id.0, err = %e, "update_task_status(New) failed — task may be stuck in InReview");
                            }
                        }
                    }
                    Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Rerouted))
                }
            }
        }
        Err(e) => {
            tracing::warn!(
                task_id = task.id.0,
                branch = %branch_name,
                error = %e,
                "failed to check PR status"
            );
            Ok(EnsurePrResult::EarlyReturn(ReviewDecision::Failed(
                format!("PR check failed: {e}"),
            )))
        }
    }
}

fn review_project_dir(repo: &str) -> Option<std::path::PathBuf> {
    crate::config::get_projects_with_paths()
        .unwrap_or_default()
        .into_iter()
        .find(|(candidate, _)| candidate == repo)
        .map(|(_, dir)| dir)
}

fn sandboxed_in(project_dir: Option<&std::path::Path>) -> bool {
    match project_dir {
        Some(dir) => runner::sandbox::enabled(dir),
        None => runner::sandbox::enabled_globally(),
    }
}

/// Whether the review agent for `repo` runs in the OS sandbox
pub(crate) fn review_sandboxed(repo: &str) -> bool {
    sandboxed_in(review_project_dir(repo).as_deref())
}

/// The review agent's own time limit, as configured.
pub(crate) fn review_timeout_seconds() -> u64 {
    review_timeout_secs(
        crate::config::get("workflow.review_timeout_seconds")
            .ok()
            .and_then(|s| s.parse().ok()),
    )
}

/// Seconds a finished review needs to get its result from the agent's output file into the engine.
/// The agent ends its tmux session first, so the no-session recovery sees a dead session while the
/// result is still in flight
pub(crate) const REVIEW_RESULT_DELIVERY_SECS: u64 = 120;

/// Smallest no-session recovery limit that cannot cut a review short. Below the review agent's own
/// timeout plus delivery time, recovery resets a task whose finished review is still arriving and
/// the result is dropped as stale
pub(crate) fn no_session_review_floor(configured: u64, review_timeout: u64) -> u64 {
    configured.max(review_timeout + REVIEW_RESULT_DELIVERY_SECS)
}

/// Run the review agent on a completed task and handle the outcome.
///
/// Called after a task completes with status:done and a PR is created.
/// The review agent checks the changes and either approves (triggers auto-merge)
/// or requests changes (re-dispatches the original agent).
pub(crate) async fn review_and_merge(
    task: &ExternalTask,
    backend: &Arc<dyn ExternalBackend>,
    tmux: &Arc<TmuxManager>,
    repo: &str,
    router: &Arc<RwLock<Router>>,
    task_manager: &Arc<TaskManager>,
    store: &Arc<TaskStore>,
) -> anyhow::Result<ReviewDecision> {
    let ctx = match build_review_context(task, repo, router, task_manager, store).await? {
        ReviewPhase::Ready(ctx) => ctx,
        ReviewPhase::EarlyReturn(decision) => return Ok(decision),
    };

    let run = match invoke_review_agent(task, tmux, &ctx, repo, store).await {
        ReviewPhase::Ready(run) => run,
        ReviewPhase::EarlyReturn(decision) => return Ok(decision),
    };

    let parsed = match parse_review_output(task, repo, &ctx, run, store).await {
        ReviewPhase::Ready(parsed) => parsed,
        ReviewPhase::EarlyReturn(decision) => return Ok(decision),
    };

    finalize_review_run(task, &ctx, &parsed, store).await;

    let router_config = router.read().await.config.clone();
    apply_review_decision(
        task,
        backend,
        repo,
        task_manager,
        store,
        &ctx,
        &parsed,
        &router_config,
    )
    .await
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_review_decision_counts_only_from_a_successful_result() {
        let approve = r#"{"type":"result","subtype":"success","is_error":false,"result":"{\"decision\":\"approve\",\"notes\":\"LGTM\",\"issues\":[]}"}"#;
        let prose = r#"{"type":"result","subtype":"success","is_error":false,"result":"I have finished looking at the code."}"#;
        let failed = r#"{"type":"result","subtype":"error","is_error":true,"result":"{\"decision\":\"approve\",\"notes\":\"\",\"issues\":[]}"}"#;
        let thinking = r#"{"type":"assistant","message":{"content":[{"type":"text","text":"Reading the diff"}]}}"#;

        assert!(output_has_review_decision("claude", approve));
        assert!(!output_has_review_decision("claude", prose));
        assert!(!output_has_review_decision("claude", failed));
        assert!(!output_has_review_decision("claude", thinking));
        assert!(!output_has_review_decision("claude", ""));
    }

    #[test]
    fn a_review_gets_15_minutes_unless_configured_and_never_under_5() {
        assert_eq!(review_timeout_secs(None), 900);
        assert_eq!(review_timeout_secs(Some(600)), 600);
        assert_eq!(review_timeout_secs(Some(60)), 300);
        assert_eq!(review_timeout_secs(Some(3600)), 3600);
    }

    use crate::backends::ExternalTask;
    use crate::engine::router::RouterConfig;
    use crate::github::types::{GitHubReview, GitHubReviewComment, GitHubUser, PullRequestReview};
    use crate::store::{TaskStatus, TaskStore};
    use tempfile::TempDir;

    // ── outcome_for_agent_error ─────────────────────────────────────────────

    // ── no_session_review_floor ─────────────────────────────────────────────

    #[test]
    fn no_session_review_floor_raises_a_limit_under_the_review_timeout() {
        assert_eq!(
            no_session_review_floor(600, 900),
            900 + REVIEW_RESULT_DELIVERY_SECS
        );
    }

    #[test]
    fn no_session_review_floor_keeps_a_limit_over_the_review_timeout() {
        assert_eq!(no_session_review_floor(1800, 900), 1800);
    }

    #[test]
    fn no_session_review_floor_clears_the_review_timeout_by_the_delivery_margin() {
        for (configured, review_timeout) in [(0, 0), (1800, 1800), (120, 7200)] {
            let floored = no_session_review_floor(configured, review_timeout);
            assert!(
                floored >= review_timeout + REVIEW_RESULT_DELIVERY_SECS,
                "{floored} must leave a finished review time to deliver its result"
            );
        }
    }

    #[test]
    fn outcome_for_agent_error_kimi_billing_cycle_is_not_rate_limit() {
        // Regression test for issue #3529: a review run hitting Kimi's billing-cycle
        // exhaustion (task 156734 in the bug report) must not be stored as a plain
        // "rate_limit" outcome.
        let err = runner::agents::AgentError::RateLimit {
            message: "Failed to authenticate. API Error: 403 You've reached your usage limit \
                      for this billing cycle. Your quota will be refreshed soon."
                .to_string(),
        };
        assert_eq!(outcome_for_agent_error(&err), "billing_cycle_exhausted");
    }

    #[test]
    fn outcome_for_agent_error_generic_rate_limit_unaffected() {
        let err = runner::agents::AgentError::RateLimit {
            message: "429 Too Many Requests".to_string(),
        };
        assert_eq!(outcome_for_agent_error(&err), "rate_limit");
    }

    #[test]
    fn outcome_for_agent_error_generic_auth_unaffected() {
        let err = runner::agents::AgentError::Auth {
            message: "401 Unauthorized".to_string(),
        };
        assert_eq!(outcome_for_agent_error(&err), "auth_error");
    }

    // ── parse_pr_number_from_url ────────────────────────────────────────────

    #[test]
    fn parse_pr_number_standard_url() {
        assert_eq!(
            parse_pr_number_from_url("https://github.com/owner/repo/pull/42"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_trailing_slash() {
        assert_eq!(
            parse_pr_number_from_url("https://github.com/owner/repo/pull/42/"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_with_query_string() {
        assert_eq!(
            parse_pr_number_from_url("https://github.com/owner/repo/pull/42?tab=files"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_with_hash_fragment() {
        assert_eq!(
            parse_pr_number_from_url("https://github.com/owner/repo/pull/42#issuecomment-123"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_with_query_and_hash() {
        assert_eq!(
            parse_pr_number_from_url("https://github.com/owner/repo/pull/42?quick_pull=1#top"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_with_leading_whitespace() {
        assert_eq!(
            parse_pr_number_from_url("  https://github.com/owner/repo/pull/42\n"),
            Ok(42)
        );
    }

    #[test]
    fn parse_pr_number_wrong_domain() {
        let url = "https://gitlab.com/owner/repo/merge_requests/42";
        let result = parse_pr_number_from_url(url);
        assert!(result.is_err());
        assert!(
            result
                .unwrap_err()
                .contains("does not start with 'https://github.com/'")
        );
    }

    #[test]
    fn parse_pr_number_missing_pull_segment() {
        // Issue URL — not a PR URL
        let url = "https://github.com/owner/repo/issues/42";
        let result = parse_pr_number_from_url(url);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("missing '/pull/' segment"));
    }

    #[test]
    fn parse_pr_number_zero_is_rejected() {
        let url = "https://github.com/owner/repo/pull/0";
        let result = parse_pr_number_from_url(url);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("cannot be zero"));
    }

    #[test]
    fn parse_pr_number_non_numeric_segment() {
        let url = "https://github.com/owner/repo/pull/abc";
        let result = parse_pr_number_from_url(url);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("not a valid positive integer"));
    }

    #[test]
    fn parse_pr_number_empty_string() {
        let result = parse_pr_number_from_url("");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("empty"));
    }

    #[test]
    fn parse_pr_number_http_not_https() {
        // HTTP URLs are not accepted — only HTTPS
        let url = "http://github.com/owner/repo/pull/42";
        let result = parse_pr_number_from_url(url);
        assert!(result.is_err());
        assert!(
            result
                .unwrap_err()
                .contains("does not start with 'https://github.com/'")
        );
    }

    // ── format_review_error ─────────────────────────────────────────────────
    //
    // Regression coverage for issue #3149: review runs were persisting raw
    // `api_retry` NDJSON fragments into `task_runs.error` because the review
    // pipeline formatted rate-limit errors with `err.to_string()` instead of
    // routing the raw provider message through `summarize_rate_limit_error`.

    #[test]
    fn format_review_error_summarises_rate_limit_fragment_with_api_retry() {
        // Real-world fragment captured from a minimax review run (issue #3149).
        // The provider message contains a complete api_retry JSON line so the
        // summariser should produce a clean `status=… after … attempts` summary.
        let raw_fragment = "{\"attempt\":6,\"max_retries\":10,\"retry_delay_ms\":17266.789,\"error_status\":429,\"error\":\"rate_limit\",\"session_id\":\"5c7148ee\"}\n\
                            {\"type\":\"system\",\"subtype\":\"api_retry\",\"attempt\":7,\"max_retries\":10,\"retry_delay_ms\":35162.66,\"error_status\":429,\"error\":\"rate_limit\",\"session_id\":\"5c7148ee\"}";
        let err = runner::agents::AgentError::RateLimit {
            message: raw_fragment.to_string(),
        };

        let stored = format_review_error("minimax", &err);

        // Must not contain raw JSON braces or the api_retry marker — these are
        // exactly the leaks that filled `task_runs.error` with noisy payloads.
        assert!(
            !stored.contains("{\"type\""),
            "stored error must not contain raw NDJSON envelope, got: {stored}"
        );
        assert!(
            !stored.contains("subtype"),
            "stored error must not contain raw api_retry fragment, got: {stored}"
        );
        assert!(
            !stored.contains("session_id"),
            "stored error must not contain session_id from provider payload, got: {stored}"
        );
        assert_eq!(
            stored,
            "minimax rate limit: status=429 after 7 attempts (last delay 35s)"
        );
    }

    #[test]
    fn format_review_error_summarises_truncated_fragment_without_subtype_marker() {
        // Mid-object fragment that begins after the `subtype` key was cut off — this
        // is the shape that landed in `task_runs.error` for rows 13634/13542/9821
        // before the fix. The summariser's fallback path should emit a compact
        // hint rather than echoing the raw payload.
        let raw_fragment = ",\"attempt\":5,\"max_retries\":10,\"retry_delay_ms\":9034.81,\"error_status\":429,\"error\":\"rate_limit\",\"session_id\":\"992e17d3\"";
        let err = runner::agents::AgentError::RateLimit {
            message: raw_fragment.to_string(),
        };

        let stored = format_review_error("glm", &err);

        assert!(stored.starts_with("glm rate limit:"));
        assert!(
            !stored.contains("session_id"),
            "stored error must not leak session_id from truncated fragment, got: {stored}"
        );
        // The fragment first-line truncation path is bounded — verify the stored
        // string stays well under the 512-char cap suggested by the bug report.
        assert!(
            stored.len() <= 200,
            "stored error should be compact (<=200 chars), got {} chars: {stored}",
            stored.len()
        );
    }

    #[test]
    fn format_review_error_preserves_non_rate_limit_variants() {
        let err = runner::agents::AgentError::Auth {
            message: "invalid bearer token".to_string(),
        };
        assert_eq!(
            format_review_error("kimi", &err),
            "kimi auth error: invalid bearer token"
        );

        let err = runner::agents::AgentError::Timeout {
            elapsed: std::time::Duration::from_secs(1801),
        };
        assert_eq!(
            format_review_error("kimi", &err),
            "kimi timed out after 1801s"
        );
    }

    fn git(dir: &std::path::Path, args: &[&str]) {
        let mut cmd = std::process::Command::new("git");
        cmd.current_dir(dir);
        // Global commit.gpgsign calls the operator's signer (1Password)
        if args.first() == Some(&"commit") {
            cmd.args(["-c", "commit.gpgsign=false"]);
        }
        let status = cmd.args(args).status().unwrap();
        assert!(status.success(), "git {args:?} failed");
    }

    #[test]
    fn test_pull_request_review_requests_changes() {
        let review = PullRequestReview {
            review: GitHubReview {
                id: 1,
                user: GitHubUser {
                    login: "reviewer".to_string(),
                },
                body: Some("Please fix".to_string()),
                state: "CHANGES_REQUESTED".to_string(),
                html_url: None,
                submitted_at: "2024-01-01T00:00:00Z".to_string(),
                commit_id: None,
            },
            comments: vec![],
        };
        assert!(review.requests_changes());
    }

    #[test]
    fn test_pull_request_review_does_not_request_changes() {
        let review = PullRequestReview {
            review: GitHubReview {
                id: 1,
                user: GitHubUser {
                    login: "reviewer".to_string(),
                },
                body: Some("LGTM".to_string()),
                state: "APPROVED".to_string(),
                html_url: None,
                submitted_at: "2024-01-01T00:00:00Z".to_string(),
                commit_id: None,
            },
            comments: vec![],
        };
        assert!(!review.requests_changes());
    }

    #[test]
    fn test_pull_request_review_actionable_comments_filters_empty_and_replies() {
        let review = PullRequestReview {
            review: GitHubReview {
                id: 1,
                user: GitHubUser {
                    login: "reviewer".to_string(),
                },
                body: None,
                state: "CHANGES_REQUESTED".to_string(),
                html_url: None,
                submitted_at: "2024-01-01T00:00:00Z".to_string(),
                commit_id: None,
            },
            comments: vec![
                GitHubReviewComment {
                    id: 1,
                    user: GitHubUser {
                        login: "reviewer".to_string(),
                    },
                    body: "Fix this issue".to_string(),
                    path: "src/main.rs".to_string(),
                    line: Some(10),
                    original_line: Some(10),
                    commit_id: "abc".to_string(),
                    original_commit_id: "abc".to_string(),
                    html_url: "url".to_string(),
                    created_at: "2024-01-01T00:00:00Z".to_string(),
                    updated_at: "2024-01-01T00:00:00Z".to_string(),
                    in_reply_to_id: None,
                    diff_hunk: Some(
                        "@@ -8,5 +8,5 @@ fn main() {\n-    let x = 1;\n+    let x = 2;".to_string(),
                    ),
                },
                GitHubReviewComment {
                    id: 2,
                    user: GitHubUser {
                        login: "reviewer".to_string(),
                    },
                    body: String::new(),
                    path: "src/lib.rs".to_string(),
                    line: Some(20),
                    original_line: Some(20),
                    commit_id: "abc".to_string(),
                    original_commit_id: "abc".to_string(),
                    html_url: "url".to_string(),
                    created_at: "2024-01-01T00:00:00Z".to_string(),
                    updated_at: "2024-01-01T00:00:00Z".to_string(),
                    in_reply_to_id: None,
                    diff_hunk: None,
                },
                GitHubReviewComment {
                    id: 3,
                    user: GitHubUser {
                        login: "reviewer".to_string(),
                    },
                    body: "Reply to this".to_string(),
                    path: "src/lib.rs".to_string(),
                    line: Some(30),
                    original_line: Some(30),
                    commit_id: "abc".to_string(),
                    original_commit_id: "abc".to_string(),
                    html_url: "url".to_string(),
                    created_at: "2024-01-01T00:00:00Z".to_string(),
                    updated_at: "2024-01-01T00:00:00Z".to_string(),
                    in_reply_to_id: Some(1),
                    diff_hunk: None,
                },
            ],
        };
        let actionable = review.actionable_comments();
        assert_eq!(actionable.len(), 1);
        assert_eq!(actionable[0].id, 1);
        assert_eq!(actionable[0].body, "Fix this issue");
        assert_eq!(actionable[0].path, "src/main.rs");
        assert_eq!(
            actionable[0].diff_hunk.as_ref().unwrap(),
            "@@ -8,5 +8,5 @@ fn main() {\n-    let x = 1;\n+    let x = 2;"
        );
    }

    #[test]
    fn test_router_config_model_for_complexity_returns_none_without_config() {
        // With no model_map configured, model_for_complexity must return None rather than
        // silently using a hardcoded model that may not exist for the given agent.
        let cfg = RouterConfig::default();
        assert!(cfg.model_for_complexity("claude", "simple", "").is_none());
        assert!(cfg.model_for_complexity("opencode", "review", "").is_none());
        assert!(
            cfg.model_for_complexity("unknown_agent_xyz", "simple", "")
                .is_none()
        );
    }

    #[test]
    fn review_status_maps_decisions() {
        assert_eq!(
            review_status(&ReviewDecision::Approve { issues: vec![] })
                .unwrap()
                .0,
            "success"
        );
        let changes = ReviewDecision::RequestChanges {
            notes: String::new(),
            issues: vec![],
        };
        assert_eq!(review_status(&changes).unwrap().0, "failure");
        assert!(review_status(&ReviewDecision::Failed("x".into())).is_none());
    }

    fn sample_review_issue(severity: &str) -> runner::response::ReviewIssue {
        runner::response::ReviewIssue {
            file: "src/engine/tick.rs".into(),
            line: Some(142),
            severity: severity.into(),
            description: "index out of bounds on the last element".into(),
        }
    }

    fn sample_review_response(
        decision: &str,
        test_results: Option<&str>,
        issues: Vec<runner::response::ReviewIssue>,
    ) -> runner::response::ReviewResponse {
        runner::response::ReviewResponse {
            decision: decision.into(),
            notes: "looks fine".into(),
            test_results: test_results.map(str::to_string),
            issues,
        }
    }

    #[test]
    fn approve_with_failing_tests_becomes_request_changes() {
        let decision =
            review_decision_from_response(sample_review_response("approve", Some("fail"), vec![]));
        match decision {
            ReviewDecision::RequestChanges { notes, issues } => {
                assert!(
                    notes.contains("test_results: fail"),
                    "notes must name the failing test run, got {notes:?}"
                );
                assert!(issues.is_empty(), "{issues:?}");
            }
            other => panic!("expected RequestChanges, got {other:?}"),
        }
    }

    #[test]
    fn approve_with_error_issue_becomes_request_changes() {
        let issue = sample_review_issue("error");
        let decision = review_decision_from_response(sample_review_response(
            "approve",
            Some("pass"),
            vec![issue.clone()],
        ));
        match decision {
            ReviewDecision::RequestChanges { issues, .. } => {
                assert_eq!(issues, vec![issue]);
            }
            other => panic!("expected RequestChanges, got {other:?}"),
        }
    }

    #[test]
    fn approve_with_warning_issue_stays_approve_and_comment_lists_it() {
        let issue = sample_review_issue("warning");
        let decision = review_decision_from_response(sample_review_response(
            "approve",
            Some("pass"),
            vec![issue.clone()],
        ));
        match &decision {
            ReviewDecision::Approve { issues } => {
                assert_eq!(issues, &vec![issue.clone()]);
            }
            other => panic!("expected Approve, got {other:?}"),
        }
        let comment = build_pr_review_comment(&decision, "looks fine");
        assert!(
            comment.contains("Approve"),
            "approve header missing from {comment}"
        );
        assert!(
            comment.contains(&issue.description),
            "warning issue missing from {comment}"
        );
        assert!(
            comment.contains("warning"),
            "warning severity missing from {comment}"
        );
    }

    #[test]
    fn review_started_comment_includes_agent_and_model() {
        let expected_footer = attribution_footer("Review started", "kimi", Some("opus"));
        let expected = format!("🔍 Automated review started{expected_footer}");
        assert_eq!(review_started_comment("kimi", "opus"), expected);
    }

    // ── build_review_context: no worktree/branch/pr (issue #3623) ───────────

    fn no_code_review_task(id: &str) -> ExternalTask {
        ExternalTask {
            id: crate::backends::ExternalId(id.to_string()),
            title: "opencode discovery timeout".to_string(),
            body: String::new(),
            state: "open".to_string(),
            labels: vec![],
            author: "tester".to_string(),
            created_at: "2026-01-01T00:00:00Z".to_string(),
            updated_at: "2026-01-01T00:00:00Z".to_string(),
            url: "https://example.com/issues/1".to_string(),
        }
    }

    /// An approval only carries over while the PR head is still the commit that was
    /// approved. A force-push from another clone moves the head, and reviewing again is
    /// the safe answer in every other case (#3783)
    #[tokio::test]
    async fn carried_approval_counts_as_this_rounds_decision() {
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let id = store
            .create_internal("owner/repo", "Approved head", "", "test", "carried", None)
            .await
            .unwrap();
        let task_id = format!("internal:{id}");
        store
            .update_status(id, crate::store::TaskStatus::InReview)
            .await
            .unwrap();
        assert_eq!(
            store.in_review_entry(id).await.unwrap().map(|e| e.1),
            Some(false)
        );

        record_carried_approval(&store, "owner/repo", &task_id, 7).await;

        assert_eq!(
            store.in_review_entry(id).await.unwrap().map(|e| e.1),
            Some(true),
            "the stale in_review check must see this round as decided"
        );
    }

    #[test]
    fn approval_covers_head_only_for_the_exact_commit() {
        assert!(approval_covers_head(Some("abc123"), Some("abc123")));
        assert!(
            !approval_covers_head(Some("abc123"), Some("def456")),
            "a moved PR head must be reviewed"
        );
        assert!(
            !approval_covers_head(None, Some("abc123")),
            "no recorded approval means review"
        );
        assert!(
            !approval_covers_head(Some("abc123"), None),
            "an unreadable PR head must not skip the review"
        );
        assert!(!approval_covers_head(Some(""), Some("")));
    }

    fn pr_for(
        head_repo: Option<&str>,
        head: &str,
        base: &str,
    ) -> crate::github::types::GitHubPullRequest {
        serde_json::from_value(serde_json::json!({
            "number": 7,
            "title": "t",
            "state": "open",
            "head": {"ref": head, "sha": "h", "repo": head_repo.map(|r| serde_json::json!({"full_name": r}))},
            "base": {"ref": base, "sha": "b"},
            "html_url": "https://github.com/owner/repo/pull/7",
        }))
        .unwrap()
    }

    #[test]
    fn a_carried_approval_must_match_the_approved_repo_branch_and_base() {
        let approval = ApprovalEvent {
            sha: "a".into(),
            repo: "owner/repo".into(),
            branch: "gh-issue-1".into(),
            base: "main".into(),
        };
        let ok = pr_for(Some("owner/repo"), "gh-issue-1", "main");
        assert!(pr_matches_approval(&ok, &approval, "gh-issue-1"));
        assert!(!pr_matches_approval(
            &pr_for(Some("fork/repo"), "gh-issue-1", "main"),
            &approval,
            "gh-issue-1"
        ));
        assert!(!pr_matches_approval(
            &pr_for(None, "gh-issue-1", "main"),
            &approval,
            "gh-issue-1"
        ));
        assert!(!pr_matches_approval(
            &pr_for(Some("owner/repo"), "other", "main"),
            &approval,
            "gh-issue-1"
        ));
        assert!(!pr_matches_approval(
            &pr_for(Some("owner/repo"), "gh-issue-1", "release"),
            &approval,
            "gh-issue-1"
        ));
        assert!(!pr_matches_approval(&ok, &approval, "another-task-branch"));

        let legacy = ApprovalEvent::parse("abc123").unwrap();
        assert_eq!(legacy.sha, "abc123");
        assert!(!pr_matches_approval(&ok, &legacy, "gh-issue-1"));
        let json = serde_json::to_string(&approval).unwrap();
        assert_eq!(ApprovalEvent::parse(&json), Some(approval));
        assert_eq!(ApprovalEvent::parse("  "), None);
    }

    #[tokio::test]
    async fn only_the_same_commits_rebased_onto_the_base_carry_the_approval() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .args([
                    "-c",
                    "user.name=agent",
                    "-c",
                    "user.email=agent@t",
                    "-c",
                    "commit.gpgsign=false",
                ])
                .args(args)
                .env_remove("GIT_AUTHOR_NAME")
                .env_remove("GIT_AUTHOR_EMAIL")
                .env_remove("GIT_COMMITTER_NAME")
                .env_remove("GIT_COMMITTER_EMAIL")
                .current_dir(path)
                .output()
                .unwrap();
            assert!(
                out.status.success(),
                "git {args:?}: {}",
                String::from_utf8_lossy(&out.stderr)
            );
            String::from_utf8_lossy(&out.stdout).trim().to_string()
        };
        let write_commit = |file: &str, body: &str| {
            std::fs::write(path.join(file), body).unwrap();
            git(&["add", file]);
            git(&["commit", "-q", "-m", body]);
        };
        git(&["init", "-q", "-b", "main"]);
        write_commit("a", "base");
        git(&["checkout", "-q", "-b", "pr"]);
        write_commit("b", "first");
        write_commit("c", "second");
        let approved = git(&["rev-parse", "HEAD"]);
        git(&["checkout", "-q", "main"]);
        write_commit("d", "base moved");
        git(&["checkout", "-q", "-b", "rebased", &approved]);
        git(&["rebase", "-q", "main"]);
        let rebased = git(&["rev-parse", "HEAD"]);
        assert!(same_commits_rebased(path, &approved, "main", &rebased).await);

        // A changed patch on top of the rebase is not the approved change
        write_commit("c", "second, changed");
        let changed = git(&["rev-parse", "HEAD"]);
        assert!(!same_commits_rebased(path, &approved, "main", &changed).await);

        // The same patches under another author are not the approved commits
        git(&["checkout", "-q", "-b", "other-author", &rebased]);
        git(&[
            "-c",
            "user.name=someone",
            "-c",
            "user.email=someone@t",
            "commit",
            "-q",
            "--amend",
            "--reset-author",
            "--no-edit",
        ]);
        let reauthored = git(&["rev-parse", "HEAD"]);
        assert!(!same_commits_rebased(path, &approved, "main", &reauthored).await);
    }

    #[tokio::test]
    async fn only_a_clean_merge_of_the_base_counts_as_base_only() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .args([
                    "-c",
                    "user.name=t",
                    "-c",
                    "user.email=t@t",
                    "-c",
                    "commit.gpgsign=false",
                ])
                .args(args)
                .env_remove("GIT_AUTHOR_NAME")
                .env_remove("GIT_AUTHOR_EMAIL")
                .env_remove("GIT_COMMITTER_NAME")
                .env_remove("GIT_COMMITTER_EMAIL")
                .current_dir(path)
                .output()
                .unwrap();
            assert!(
                out.status.success(),
                "git {args:?}: {}",
                String::from_utf8_lossy(&out.stderr)
            );
            String::from_utf8_lossy(&out.stdout).trim().to_string()
        };
        let commit = |file: &str, msg: &str| {
            std::fs::write(path.join(file), msg).unwrap();
            git(&["add", file]);
            git(&["commit", "-q", "-m", msg]);
            git(&["rev-parse", "HEAD"])
        };
        git(&["init", "-q", "-b", "main"]);
        commit("a", "base");
        git(&["checkout", "-q", "-b", "pr"]);
        let approved = commit("b", "approved change");
        git(&["checkout", "-q", "main"]);
        let base_tip = commit("c", "base moved");
        git(&["checkout", "-q", "pr"]);
        git(&["merge", "-q", "--no-edit", "main"]);
        let clean = git(&["rev-parse", "HEAD"]);
        assert!(is_clean_merge(path, &approved, &base_tip, &clean).await);

        std::fs::write(path.join("d"), "unreviewed").unwrap();
        git(&["add", "d"]);
        git(&["commit", "-q", "--amend", "--no-edit"]);
        let forged = git(&["rev-parse", "HEAD"]);
        assert!(!is_clean_merge(path, &approved, &base_tip, &forged).await);
    }

    #[test]
    fn a_review_agent_cannot_change_the_repository_remotes() {
        let tools = build_review_disallowed_tools(std::path::Path::new("/tmp/wt"));
        for guard in runner::git_ops::remote_change_tools() {
            assert!(tools.contains(&guard), "missing {guard}");
        }
    }

    #[test]
    fn only_a_merge_of_the_approved_commit_carries_the_approval() {
        let parents = |p: &[&str]| {
            p.iter()
                .map(std::string::ToString::to_string)
                .collect::<Vec<_>>()
        };
        assert_eq!(
            base_merge_parent("approved", &parents(&["approved", "base"])),
            Some("base")
        );
        // A new commit on top of the approval, or a merge of something else, needs a review
        assert_eq!(base_merge_parent("approved", &parents(&["approved"])), None);
        assert_eq!(
            base_merge_parent("approved", &parents(&["other", "base"])),
            None
        );
        assert_eq!(
            base_merge_parent("approved", &parents(&["approved", "a", "b"])),
            None
        );
    }

    /**
     * The approval is recorded against the commit pushed to the PR and is dropped when a
     * review asks for changes, so the next NeedsReview event reviews the new work (#3783)
     **/
    #[tokio::test]
    async fn approved_sha_round_trips_through_the_kv_store() {
        let temp = TempDir::new().unwrap();
        let wt = temp.path();
        git(wt, &["init", "-b", "main"]);
        git(wt, &["config", "user.name", "Test"]);
        git(wt, &["config", "user.email", "test@test.com"]);
        std::fs::write(wt.join("fix.txt"), "the fix").unwrap();
        git(wt, &["add", "."]);
        git(wt, &["commit", "-m", "apply the fix"]);

        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let repo = "owner/repo";
        let task_id = "3783";

        record_approved_sha(&store, repo, task_id, 77, wt, "gh-issue-3783", "main").await;
        let recorded = read_approval(&store, repo, task_id, 77)
            .await
            .unwrap()
            .expect("approval must be recorded");
        assert_eq!(recorded.repo, repo);
        assert_eq!(recorded.branch, "gh-issue-3783");
        assert_eq!(recorded.base, "main");
        assert_eq!(
            recorded.sha,
            worktree_head_sha(wt).await.unwrap(),
            "the recorded sha must be the commit that was pushed to the PR"
        );
        assert!(
            store
                .kv_get(&approved_sha_key(repo, task_id, 78))
                .await
                .unwrap()
                .is_none(),
            "an approval must not leak to another PR"
        );

        clear_approved_sha(&store, repo, task_id, 77).await;
        assert!(
            store
                .kv_get(&approved_sha_key(repo, task_id, 77))
                .await
                .unwrap()
                .is_none(),
            "requesting changes must drop the approval"
        );
    }

    #[tokio::test]
    async fn build_review_context_reroutes_external_task_with_no_code() {
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let repo = "owner/repo";
        let ext = no_code_review_task("3617");
        store.ensure_external_task(repo, &ext).await.unwrap();

        let backend = Arc::new(crate::backends::test_helpers::NoopBackend);
        let task_manager = Arc::new(TaskManager::with_store(
            backend,
            Arc::clone(&store),
            repo.to_string(),
        ));
        let router = Arc::new(RwLock::new(Router::new(RouterConfig::default())));

        let phase = build_review_context(&ext, repo, &router, &task_manager, &store)
            .await
            .unwrap();

        assert!(
            matches!(phase, ReviewPhase::EarlyReturn(ReviewDecision::Rerouted)),
            "external task with no worktree/branch/pr must reroute, not skip-to-done"
        );

        let stored = store
            .get_by_external_id(repo, &ext.id.0)
            .await
            .unwrap()
            .expect("task must still exist");
        assert_eq!(stored.status, TaskStatus::New);
        assert!(stored.agent.is_none());
        assert!(stored.model.is_none());
    }

    #[tokio::test]
    async fn build_review_context_blocks_external_task_after_max_reroutes() {
        // Isolate from the real ~/.orch/config.yml (which may set a different
        // workflow.max_attempts) so the default of 3 reroutes is deterministic.
        let temp_home = TempDir::new().unwrap();
        let orch_dir = temp_home.path().join(".orch");
        std::fs::create_dir_all(&orch_dir).unwrap();
        let old_orch_home = std::env::var_os("ORCH_HOME");
        // SAFETY: nextest runs each test in its own process, so no other test touches the environment
        unsafe { std::env::set_var("ORCH_HOME", &orch_dir) };

        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let repo = "owner/repo";
        let ext = no_code_review_task("3618");
        store.ensure_external_task(repo, &ext).await.unwrap();

        let backend = Arc::new(crate::backends::test_helpers::NoopBackend);
        let task_manager = Arc::new(TaskManager::with_store(
            backend,
            Arc::clone(&store),
            repo.to_string(),
        ));
        let router = Arc::new(RwLock::new(Router::new(RouterConfig::default())));

        // Default max_reroute_attempts is 3 — exhaust it.
        for _ in 0..3 {
            let phase = build_review_context(&ext, repo, &router, &task_manager, &store)
                .await
                .unwrap();
            if let ReviewPhase::EarlyReturn(ReviewDecision::Blocked(_)) = phase {
                break;
            }
        }

        let stored = store
            .get_by_external_id(repo, &ext.id.0)
            .await
            .unwrap()
            .expect("task must still exist");
        assert_eq!(stored.status, TaskStatus::Blocked);

        if let Some(old) = old_orch_home {
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            unsafe { std::env::set_var("ORCH_HOME", old) };
        } else {
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            unsafe { std::env::remove_var("ORCH_HOME") };
        }
    }

    #[tokio::test]
    async fn build_review_context_marks_internal_task_done_with_no_code() {
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let repo = "owner/repo";
        let internal_id = store
            .create_internal(repo, "Daily retrospective", "", "job", "job-1", None)
            .await
            .unwrap();
        let ext_id = format!("internal:{internal_id}");
        let ext = no_code_review_task(&ext_id);

        let backend = Arc::new(crate::backends::test_helpers::NoopBackend);
        let task_manager = Arc::new(TaskManager::with_store(
            backend,
            Arc::clone(&store),
            repo.to_string(),
        ));
        let router = Arc::new(RwLock::new(Router::new(RouterConfig::default())));

        let phase = build_review_context(&ext, repo, &router, &task_manager, &store)
            .await
            .unwrap();

        assert!(matches!(
            phase,
            ReviewPhase::EarlyReturn(ReviewDecision::Skipped)
        ));
        let stored = store.get(internal_id).await.unwrap();
        assert_eq!(stored.status, TaskStatus::Done);
    }

    #[test]
    fn no_code_reroute_skip_check_rejects_agent_stream_disconnects() {
        let last_error =
            "codex failed: Reconnecting... (stream disconnected before completion: Broken pipe)";
        assert!(!should_skip_no_code_reroute_increment(last_error));
    }

    // ── review fallback rate-limit/auth scan is bounded, not full-text ──────
    //
    // Regression test for a review transcript whose unparseable fallback text
    // is a long report/diff quoting a status table (`outcome` column values
    // like `rate_limit`, `failed`, `timeout`). Scanning the full text falsely
    // classified the review run as rate-limited even though the review agent
    // never actually hit a rate limit.

    #[test]
    fn review_fallback_scan_ignores_rate_limit_word_buried_in_long_report() {
        let padding = "x".repeat(10_000);
        let text_for_review = format!(
            "{padding}\n+| codex | gpt-5.4 | failed | 1 |\n+| codex | gpt-5.5 | failed / aborted / (empty) | 1 each |\n+| kimi | opus | rate_limit | 1 |\n{padding}"
        );

        let scan_head = runner::agents::patterns::safe_head(
            &text_for_review,
            runner::agents::patterns::RATE_LIMIT_SCAN_HEAD_BYTES,
        );
        let scan_tail = runner::agents::patterns::safe_tail(
            &text_for_review,
            runner::agents::patterns::RATE_LIMIT_SCAN_TAIL_BYTES,
        );

        assert!(runner::agents::patterns::detect_rate_limit(scan_head).is_none());
        assert!(runner::agents::patterns::detect_rate_limit(scan_tail).is_none());
    }

    #[test]
    fn review_fallback_scan_still_detects_real_rate_limit_at_tail() {
        let padding = "x".repeat(10_000);
        let text_for_review =
            format!("{padding}\nError: rate limit exceeded, please try again later");

        let scan_tail = runner::agents::patterns::safe_tail(
            &text_for_review,
            runner::agents::patterns::RATE_LIMIT_SCAN_TAIL_BYTES,
        );

        assert!(runner::agents::patterns::detect_rate_limit(scan_tail).is_some());
    }

    #[tokio::test]
    async fn recover_missing_review_worktree_recreates_worktree() {
        let temp_home = TempDir::new().unwrap();
        let orch_dir = temp_home.path().join(".orch");
        std::fs::create_dir_all(&orch_dir).unwrap();
        let old_orch_home = std::env::var_os("ORCH_HOME");
        // SAFETY: nextest runs each test in its own process, so no other test touches the environment
        unsafe { std::env::set_var("ORCH_HOME", &orch_dir) };

        let project_dir = temp_home.path().join("project");
        std::fs::create_dir_all(&project_dir).unwrap();
        git(&project_dir, &["init", "-b", "main"]);
        git(&project_dir, &["config", "user.name", "Test User"]);
        git(&project_dir, &["config", "user.email", "test@example.com"]);
        std::fs::write(project_dir.join("README.md"), "hello").unwrap();
        git(&project_dir, &["add", "README.md"]);
        git(&project_dir, &["commit", "-m", "init"]);

        std::fs::write(
            orch_dir.join("config.yml"),
            format!("projects:\n  - {}\n", project_dir.display()),
        )
        .unwrap();
        std::fs::write(project_dir.join(".orch.yml"), "gh:\n  repo: owner/repo\n").unwrap();

        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let repo = "owner/repo";
        store
            .create_internal(repo, "Fix review recovery", "", "review", "review-1", None)
            .await
            .unwrap();
        let ext = ExternalTask {
            id: crate::backends::ExternalId("1".to_string()),
            title: "Fix review recovery".to_string(),
            body: String::new(),
            state: "open".to_string(),
            labels: vec![],
            author: "tester".to_string(),
            created_at: "2026-01-01T00:00:00Z".to_string(),
            updated_at: "2026-01-01T00:00:00Z".to_string(),
            url: "https://example.com/issues/1".to_string(),
        };
        store.ensure_external_task(repo, &ext).await.unwrap();

        let recovered = recover_missing_review_worktree(&ext, repo, &store)
            .await
            .unwrap();

        assert!(recovered.work_dir.exists());
        assert!(recovered.branch.starts_with("gh-issue-1-"));

        if let Some(old) = old_orch_home {
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            unsafe { std::env::set_var("ORCH_HOME", old) };
        } else {
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            unsafe { std::env::remove_var("ORCH_HOME") };
        }
    }

    // ── count_ahead_commits ─────────────────────────────────────────────────

    #[tokio::test]
    async fn count_ahead_commits_returns_zero_when_no_ahead_commits() {
        let temp = TempDir::new().unwrap();
        let dir = temp.path();

        // Create a bare repo to act as the 'origin' remote
        let bare = temp.path().join("bare.git");
        std::fs::create_dir_all(&bare).unwrap();
        std::process::Command::new("git")
            .args(["init", "--bare"])
            .current_dir(&bare)
            .output()
            .unwrap();

        git(dir, &["init", "-b", "main"]);
        git(dir, &["config", "user.name", "Test"]);
        git(dir, &["config", "user.email", "test@test.com"]);
        std::fs::write(dir.join("f"), "a").unwrap();
        git(dir, &["add", "f"]);
        git(dir, &["commit", "-m", "init"]);
        std::process::Command::new("git")
            .args(["remote", "add", "origin", bare.to_str().unwrap()])
            .current_dir(dir)
            .output()
            .unwrap();
        std::process::Command::new("git")
            .args(["push", "origin", "main"])
            .current_dir(dir)
            .output()
            .unwrap();

        // origin/main now exists and HEAD is at the same commit — zero ahead
        let result = count_ahead_commits(dir, "main").await;
        assert!(
            result.is_ok(),
            "expected Ok when origin/main exists, got {result:?}"
        );
        assert_eq!(
            result.unwrap(),
            0,
            "expected 0 commits ahead when branch matches origin/main"
        );
    }

    #[tokio::test]
    async fn count_ahead_commits_returns_error_when_remote_ref_missing() {
        let temp = TempDir::new().unwrap();
        let dir = temp.path();
        git(dir, &["init", "-b", "main"]);
        git(dir, &["config", "user.name", "Test"]);
        git(dir, &["config", "user.email", "test@test.com"]);
        std::fs::write(dir.join("f"), "a").unwrap();
        git(dir, &["add", "f"]);
        git(dir, &["commit", "-m", "init"]);
        // No remote 'origin' configured — rev-list will fail
        let result = count_ahead_commits(dir, "main").await;
        assert!(
            result.is_err(),
            "expected Err when origin/main does not exist, got {result:?}"
        );
        let err = result.unwrap_err();
        assert!(
            err.contains("git rev-list exited"),
            "error should mention exit failure, got: {err}"
        );
    }

    #[tokio::test]
    async fn count_ahead_commits_returns_error_when_git_cannot_start() {
        // Use a path that is not a git repo — git will fail with non-zero exit
        let temp = TempDir::new().unwrap();
        let dir = temp.path();
        // Not a git repo at all
        let result = count_ahead_commits(dir, "main").await;
        assert!(
            result.is_err(),
            "expected Err when directory is not a git repo, got {result:?}"
        );
    }

    // ── review cooldown escalation (issue #3314) ────────────────────────────

    /// Review `InvalidResponse` applies the short review output backoff: 5 minutes first
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn review_invalid_response_applies_short_model_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let agent = "opencode-3314-review-invalid";
        let model = "opencode/north-mini-code-free";
        let key = format!("{agent}:{model}");

        assert!(
            !crate::engine::cooldown::is_model_in_cooldown(agent, model),
            "model should not be in cooldown before record_review_agent_failure"
        );

        let err = runner::agents::AgentError::InvalidResponse {
            raw: "empty review output".to_string(),
        };
        record_review_agent_failure("test-3314-a", agent, Some(model), &err).await;

        let now = chrono::Utc::now().timestamp();
        let until = crate::engine::cooldown::cooldown_until(&key)
            .expect("review InvalidResponse should set model cooldown");
        let remaining = until.saturating_sub(now);
        let base = crate::engine::cooldown::TRANSIENT_MODEL_BACKOFF_BASE_SECS;
        assert!(
            (base - 30..=base).contains(&remaining),
            "first unusable review output must cool the model for 5 minutes, got {remaining}s"
        );
    }

    /// A review `ModelUnavailable` that does not say the model is gone gets the generic backoff
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn review_model_unavailable_transient_applies_short_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let agent = "test-review-unavailable-transient";
        let model = "test-model";
        let key = format!("{agent}:{model}");

        let err = runner::agents::AgentError::ModelUnavailable {
            message: "model is temporarily overloaded".to_string(),
            model: model.to_string(),
        };
        record_review_agent_failure("test-unavailable-a", agent, Some(model), &err).await;

        let now = chrono::Utc::now().timestamp();
        let until = crate::engine::cooldown::cooldown_until(&key)
            .expect("review ModelUnavailable should set model cooldown");
        let remaining = until.saturating_sub(now);
        let base = crate::engine::cooldown::BACKOFF_BASE_SECS;
        assert!(
            (base - 30..=base).contains(&remaining),
            "a non-permanent ModelUnavailable must get the 5 minute base, got {remaining}s"
        );
    }

    /// A review `ModelUnavailable` that says "model not found" gets the persistent backoff
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn review_model_not_found_applies_persistent_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let agent = "test-review-unavailable-gone";
        let model = "test-model";
        let key = format!("{agent}:{model}");

        let err = runner::agents::AgentError::ModelUnavailable {
            message: "Model not found: test-model".to_string(),
            model: model.to_string(),
        };
        record_review_agent_failure("test-unavailable-b", agent, Some(model), &err).await;

        let now = chrono::Utc::now().timestamp();
        let until = crate::engine::cooldown::cooldown_until(&key)
            .expect("review model not found should set model cooldown");
        let remaining = until.saturating_sub(now);
        let base = crate::engine::cooldown::PERSISTENT_MODEL_BACKOFF_BASE_SECS;
        assert!(
            (base - 30..=base).contains(&remaining),
            "model not found must get the 4 hour persistent base, got {remaining}s"
        );
    }

    /// Repeated unusable review output escalates to 15 minutes and stays there
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn review_output_cooldown_caps_at_fifteen_minutes() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        crate::engine::cooldown::init_cooldown_store(store).await;
        let agent = "opencode-review-output-cap";
        let model = "opencode/north-mini-code-free";
        let key = format!("{agent}:{model}");
        let base = crate::engine::cooldown::TRANSIENT_MODEL_BACKOFF_BASE_SECS;
        let max = crate::engine::cooldown::TRANSIENT_MODEL_BACKOFF_MAX_SECS;

        for (i, expected) in [base, max, max].into_iter().enumerate() {
            let err = runner::agents::AgentError::InvalidResponse {
                raw: format!("failed to parse review response {i}"),
            };
            record_review_agent_failure("test-review-output-cap", agent, Some(model), &err).await;
            let now = chrono::Utc::now().timestamp();
            let remaining = crate::engine::cooldown::cooldown_until(&key)
                .expect("unusable review output should set model cooldown")
                .saturating_sub(now);
            assert!(
                (expected - 30..=expected).contains(&remaining),
                "failure {} should cool the model for {expected}s, got {remaining}s",
                i + 1
            );
        }
    }

    /// Regression test for issue #3551: a billing-cycle-exhaustion message caught by
    /// the review module's *inline text scan* (`detect_rate_limit` on raw review
    /// output, used when the review process exits without a clean `AgentError`) must
    /// get the same treatment as the `AgentError`-based failure path fixed by #3530 —
    /// not a hardcoded `"rate_limit"` outcome plus a generic short agent cooldown.
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn review_inline_scan_billing_cycle_message_gets_model_scoped_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let agent = "kimi-3551-review-inline";
        let model = "opus";
        let key = format!("{agent}:{model}");

        // Verbatim text from the observed kimi failure (issue #3551).
        let text_for_review = "kimi rate limit: Failed to authenticate. API Error: 403 \
            You've reached your usage limit for this billing cycle. Your quota will be \
            refreshed next cycle.";

        let scan_tail = runner::agents::patterns::safe_tail(
            text_for_review,
            runner::agents::patterns::RATE_LIMIT_SCAN_TAIL_BYTES,
        );
        let err = runner::agents::patterns::detect_rate_limit(scan_tail)
            .expect("billing-cycle message must still be caught by the rate-limit scan");

        assert_eq!(
            outcome_for_agent_error(&err),
            "billing_cycle_exhausted",
            "inline-scanned billing-cycle message must not be stored as plain rate_limit"
        );

        record_review_agent_failure("test-3551", agent, Some(model), &err).await;

        let now = chrono::Utc::now().timestamp();
        let until = crate::engine::cooldown::cooldown_until(&key)
            .expect("billing-cycle exhaustion must set a model-scoped cooldown");
        let remaining = until.saturating_sub(now);
        // Known model + BillingCycleExhausted routes to record_persistent_model_failure
        // (~4h base, 7d cap), not the agent-wide record_credit_exhaustion (~24h) path —
        // the quota is scoped to this model, so unrelated models on the same agent must
        // stay routable.
        assert!(
            remaining >= crate::engine::cooldown::PERSISTENT_MODEL_BACKOFF_BASE_SECS - 30,
            "billing-cycle exhaustion for a known model must apply the ~4h persistent \
             model cooldown, got {remaining}s — may have used the generic short agent \
             cooldown instead"
        );
    }

    // ── review success resets failure_count (issue #3478) ──────────────────

    fn test_review_task(id: &str) -> ExternalTask {
        ExternalTask {
            id: crate::backends::ExternalId(id.to_string()),
            title: "Test review task".to_string(),
            body: String::new(),
            state: "open".to_string(),
            labels: vec![],
            author: "tester".to_string(),
            created_at: "2026-01-01T00:00:00Z".to_string(),
            updated_at: "2026-01-01T00:00:00Z".to_string(),
            url: "https://example.com/issues/1".to_string(),
        }
    }

    fn test_review_context(agent: &str, model: &str, work_dir: &std::path::Path) -> ReviewContext {
        ReviewContext {
            store_id: None,
            had_prev_push_failure: false,
            review_attempt: 1,
            worktree_path: work_dir.to_path_buf(),
            branch_name: "gh-issue-1-test".to_string(),
            pr_number: 1,
            head_sha: None,
            default_branch: "main".to_string(),
            review_agent: agent.to_string(),
            review_model: Some(model.to_string()),
            review_task_id: "review-1".to_string(),
            review_attempt_dir: work_dir.to_path_buf(),
            output_file: work_dir.join("output.txt"),
            invocation: runner::agent::AgentInvocation {
                agent: agent.to_string(),
                model: Some(model.to_string()),
                work_dir: work_dir.to_path_buf(),
                system_prompt: String::new(),
                agent_message: String::new(),
                task_id: "review-1".to_string(),
                disallowed_tools: vec![],
                git_author_name: "Test".to_string(),
                git_author_email: "test@example.com".to_string(),
                output_file: work_dir.join("output.txt"),
                timeout_seconds: 0,
                repo: "owner/repo".to_string(),
                attempt: 1,
                sandbox: false,
                main_project_dir: work_dir.to_path_buf(),
                branch: String::new(),
            },
            same_agent_fallback: false,
        }
    }

    fn test_parsed_review(decision: ReviewDecision) -> ParsedReview {
        ParsedReview {
            run_id: None,
            exit_code: 0,
            stderr: String::new(),
            raw_output: String::new(),
            text_for_review: String::new(),
            token_usage: RunTokenUsage::default(),
            review_notes_for_comment: String::new(),
            decision,
        }
    }

    fn write_review_output(dir: &std::path::Path, stdout: &str, exit_code: i32) {
        std::fs::write(dir.join("output.txt"), stdout).unwrap();
        std::fs::write(dir.join("exit.txt"), exit_code.to_string()).unwrap();
        std::fs::write(dir.join("stderr.txt"), "").unwrap();
    }

    /// A kimi review that exits mid-thought (no result envelope, last content is a
    /// thinking block) must be stored as incomplete and must not apply the 4h
    /// persistent model cooldown (issue #3734).
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_mid_thought_is_incomplete_without_persistent_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "kimi";
        let model = "opus-3734-mid-thought";
        let ctx = test_review_context(agent, model, work_dir.path());
        let redraw = "^D\u{0008}".repeat(20);
        let ndjson = format!(
            "{}\n{}\n{}\n{}\n{}",
            r#"{"type":"system","subtype":"thinking_tokens","tokens":1945}"#,
            r#"{"type":"assistant","message":{"content":[{"type":"text","text":"CI passes. Now verifying callers and the lease logic edge cases:"}],"stop_reason":null,"usage":{"input_tokens":10,"output_tokens":0}}}"#,
            r#"{"type":"assistant","message":{"content":[{"type":"thinking","thinking":"checking lease edge cases"}],"stop_reason":null,"usage":{"input_tokens":10,"output_tokens":0}}}"#,
            "\x1b[?25h",
            redraw,
        );
        write_review_output(work_dir.path(), &ndjson, 0);

        let task = test_review_task("3734");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(reason)) => {
                assert!(
                    reason.contains("incomplete:"),
                    "mid-thought review must be stored as incomplete, got {reason}"
                );
            }
            ReviewPhase::EarlyReturn(_) => panic!("expected Failed(incomplete)"),
            ReviewPhase::Ready(_) => panic!("expected Failed(incomplete), got Ready"),
        }
        assert!(
            !crate::engine::cooldown::is_model_in_cooldown(agent, model),
            "mid-thought incomplete must not apply persistent model cooldown"
        );
    }

    /// A review ended by the shell `timeout` (exit 124) with no decision is a timeout,
    /// not a parse error, and puts no model in cooldown (issue #3942)
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_exit_124_is_timeout_without_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "claude";
        let model = "opus-3942-timeout";
        let ctx = test_review_context(agent, model, work_dir.path());
        let ndjson = r#"{"type":"assistant","message":{"content":[{"type":"text","text":"`shipcheck run` is still going. I am waiting on that local CI run before I decide."}]}}"#;
        write_review_output(work_dir.path(), ndjson, 124);

        let task = test_review_task("3942");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(reason)) => {
                assert_eq!(reason, "timeout");
            }
            ReviewPhase::EarlyReturn(_) => panic!("expected Failed(timeout)"),
            ReviewPhase::Ready(_) => panic!("expected Failed(timeout), got Ready"),
        }
        assert!(!crate::engine::cooldown::is_model_in_cooldown(agent, model));
    }

    /// A tool_use as the last assistant content with no result envelope is the
    /// same incomplete shape as a thinking block (issue #3734).
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_tool_use_without_envelope_is_incomplete() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "kimi";
        let model = "opus-3734-tool-use";
        let ctx = test_review_context(agent, model, work_dir.path());
        let ndjson = r#"{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"src/lib.rs"}}]}}"#;
        write_review_output(work_dir.path(), ndjson, 0);

        let task = test_review_task("3734-tool");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(reason)) => {
                assert!(
                    reason.contains("incomplete:"),
                    "tool_use without envelope must be incomplete, got {reason}"
                );
            }
            ReviewPhase::EarlyReturn(_) => panic!("expected Failed(incomplete)"),
            ReviewPhase::Ready(_) => panic!("expected Failed(incomplete), got Ready"),
        }
        assert!(!crate::engine::cooldown::is_model_in_cooldown(agent, model));
    }

    /// A finished result envelope whose text is not a review decision still
    /// gets the short format-failure cooldown.
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_unparseable_envelope_applies_short_cooldown() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "kimi";
        let model = "opus-3734-format";
        let ctx = test_review_context(agent, model, work_dir.path());
        let ndjson = concat!(
            r#"{"type":"assistant","message":{"content":[{"type":"text","text":"I have finished looking at the code."}]}}"#,
            "\n",
            r#"{"type":"result","subtype":"success","is_error":false,"result":"I have finished looking at the code."}"#,
        );
        write_review_output(work_dir.path(), ndjson, 0);

        let task = test_review_task("3734-format");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(reason)) => {
                assert!(
                    reason.contains("parse error"),
                    "finished unparseable envelope must stay a parse error, got {reason}"
                );
            }
            ReviewPhase::EarlyReturn(_) => panic!("expected Failed(parse error)"),
            ReviewPhase::Ready(_) => panic!("expected Failed(parse error), got Ready"),
        }
        let now = chrono::Utc::now().timestamp();
        let remaining = crate::engine::cooldown::cooldown_until(&format!("{agent}:{model}"))
            .expect("finished format failure must apply a model cooldown")
            .saturating_sub(now);
        assert!(
            remaining <= crate::engine::cooldown::TRANSIENT_MODEL_BACKOFF_BASE_SECS,
            "finished format failure must apply the 5 minute cooldown, got {remaining}s"
        );
    }

    /// Missing result envelope with a review decision in assistant text uses
    /// the assistant-text extractor, not MiniMax status=done synthesis.
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_missing_envelope_uses_assistant_decision() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "kimi";
        let model = "opus-3734-assistant";
        let ctx = test_review_context(agent, model, work_dir.path());
        let ndjson = r#"{"type":"assistant","message":{"content":[{"type":"text","text":"{\"decision\":\"approve\",\"notes\":\"LGTM\",\"issues\":[]}"}]}}"#;
        write_review_output(work_dir.path(), ndjson, 0);

        let task = test_review_task("3734-asst");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::Ready(parsed) => {
                assert!(matches!(parsed.decision, ReviewDecision::Approve { .. }));
            }
            ReviewPhase::EarlyReturn(_) => {
                panic!("expected Ready(Approve) from assistant text, got EarlyReturn")
            }
        }
        assert!(!crate::engine::cooldown::is_model_in_cooldown(agent, model));
    }

    /// MiniMax/Kimi parse_response synthesizes status=done from any assistant
    /// text. That task-path fallback must not be treated as a review approval.
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn parse_review_output_does_not_treat_task_done_synthesis_as_approval() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        let work_dir = TempDir::new().unwrap();
        let agent = "kimi";
        let model = "opus-3734-done";
        let ctx = test_review_context(agent, model, work_dir.path());
        let ndjson = r#"{"type":"assistant","message":{"content":[{"type":"text","text":"analyzing the diff"}]}}"#;
        write_review_output(work_dir.path(), ndjson, 0);

        let task = test_review_task("3734-done");
        let phase = parse_review_output(
            &task,
            "owner/repo",
            &ctx,
            ReviewRun { run_id: None },
            &store,
        )
        .await;

        match phase {
            ReviewPhase::EarlyReturn(ReviewDecision::Failed(reason)) => {
                assert!(
                    reason.contains("parse error"),
                    "unfinished prose without a decision must not approve, got {reason}"
                );
            }
            ReviewPhase::Ready(_) => {
                panic!("task-path status=done synthesis must not become a review approval")
            }
            ReviewPhase::EarlyReturn(_) => panic!("expected Failed(parse error)"),
        }
    }

    /// Regression test for issue #3478: a successful review run must reset
    /// `failure_count:{agent}:{model}`, mirroring the runner's task-agent
    /// success path, for generic/transient failures (not the persistent-model
    /// path — see issue #3571, which deliberately gives persistent failures
    /// their own counter that a success does NOT reset).
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn finalize_review_run_success_resets_generic_model_failure_count() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        crate::engine::cooldown::init_cooldown_store(std::sync::Arc::clone(&store)).await;

        let agent = "test-3478-agent";
        let model = "test-3478-model";
        let failure_key = format!("failure_count:{agent}:{model}");

        // AgentFailed is a generic/transient error, routed to record_model_failure
        // (not record_persistent_model_failure), so it should still be reset by
        // an intervening success.
        let err = runner::agents::AgentError::AgentFailed {
            message: "agent reported a generic failure".to_string(),
        };
        record_review_agent_failure("task-3478-a", agent, Some(model), &err).await;
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        assert_eq!(
            store.kv_get(&failure_key).await.unwrap().as_deref(),
            Some("1"),
            "sanity check: failure should have incremented the persisted count"
        );

        let work_dir = TempDir::new().unwrap();
        let ctx = test_review_context(agent, model, work_dir.path());
        let parsed = test_parsed_review(ReviewDecision::Approve { issues: vec![] });
        let task = test_review_task("1");

        finalize_review_run(&task, &ctx, &parsed, &store).await;
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

        assert_eq!(
            store.kv_get(&failure_key).await.unwrap().as_deref(),
            Some("0"),
            "successful review must reset failure_count:{{agent}}:{{model}} (issue #3478)"
        );
    }

    /// Regression test for issue #3478: successful reviews interleaved between
    /// isolated generic failures must keep each failure's backoff at the base
    /// duration instead of escalating, since the previous success reset the
    /// counter. Uses AgentFailed (generic/transient), not ModelUnavailable
    /// (persistent-model path, see issue #3571).
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn finalize_review_run_interleaved_success_keeps_generic_cooldown_at_base() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        crate::engine::cooldown::init_cooldown_store(std::sync::Arc::clone(&store)).await;

        let agent = "test-3478-interleave-agent";
        let model = "test-3478-interleave-model";
        let cooldown_key = format!("{agent}:{model}");

        let work_dir = TempDir::new().unwrap();
        let ctx = test_review_context(agent, model, work_dir.path());
        let task = test_review_task("2");

        for i in 0..4 {
            let err = runner::agents::AgentError::AgentFailed {
                message: format!("failure {i}"),
            };
            record_review_agent_failure("task-3478-b", agent, Some(model), &err).await;

            let now = chrono::Utc::now().timestamp();
            let until = crate::engine::cooldown::cooldown_until(&cooldown_key)
                .expect("failure should set cooldown");
            let remaining = until.saturating_sub(now);

            assert!(
                remaining <= crate::engine::cooldown::BACKOFF_BASE_SECS + 60,
                "failure #{} must stay at base backoff since the prior success reset the \
                 counter (issue #3478); got {remaining}s, base is {}s — an escalating value \
                 here means review successes are not resetting failure_count",
                i + 1,
                crate::engine::cooldown::BACKOFF_BASE_SECS
            );

            // A successful review interleaves between each failure, mirroring the
            // real-world pattern from issue #3478 (reviews for other tasks succeed
            // in between isolated failures for this model).
            let parsed = test_parsed_review(ReviewDecision::Approve { issues: vec![] });
            finalize_review_run(&task, &ctx, &parsed, &store).await;
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
    }

    /// Regression test for issue #3571: unlike generic failures, persistent
    /// model failures (e.g. ModelUnavailable) must NOT be
    /// reset by an intervening successful review. Otherwise a model that fails
    /// structurally every so often — but succeeds most of the time — never
    /// escalates past the 4h base cooldown and stays in rotation indefinitely.
    #[serial_test::serial(cooldown_state)]
    #[tokio::test]
    async fn finalize_review_run_success_does_not_reset_persistent_model_failure_count() {
        crate::engine::cooldown::reset_global_state().await;
        let store = Arc::new(TaskStore::open_memory().await.unwrap());
        crate::engine::cooldown::init_cooldown_store(std::sync::Arc::clone(&store)).await;

        let agent = "test-3571-agent";
        let model = "test-3571-model";
        let cooldown_key = format!("{agent}:{model}");

        let work_dir = TempDir::new().unwrap();
        let ctx = test_review_context(agent, model, work_dir.path());
        let task = test_review_task("3");

        // First persistent model failure -> base 4h cooldown.
        let err = runner::agents::AgentError::ModelUnavailable {
            message: "model not found".to_string(),
            model: model.to_string(),
        };
        record_review_agent_failure("task-3571-a", agent, Some(model), &err).await;
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        // A successful review for the same model interleaves, exactly like the
        // real-world pattern from issue #3571.
        let parsed = test_parsed_review(ReviewDecision::Approve { issues: vec![] });
        finalize_review_run(&task, &ctx, &parsed, &store).await;
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        // Second persistent failure must escalate from count 2 (~12h), not
        // reset back to the 4h base, despite the intervening success.
        let err2 = runner::agents::AgentError::ModelUnavailable {
            message: "model not found again".to_string(),
            model: model.to_string(),
        };
        record_review_agent_failure("task-3571-b", agent, Some(model), &err2).await;
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        let now = chrono::Utc::now().timestamp();
        let until = crate::engine::cooldown::cooldown_until(&cooldown_key)
            .expect("second failure should set cooldown");
        let remaining = until.saturating_sub(now);

        assert!(
            remaining > crate::engine::cooldown::PERSISTENT_MODEL_BACKOFF_BASE_SECS,
            "second persistent model failure should escalate past the 4h base despite an \
             intervening success (issue #3571); got {remaining}s, base is {}s",
            crate::engine::cooldown::PERSISTENT_MODEL_BACKOFF_BASE_SECS
        );
    }

    fn app_for_test(server: &wiremock::MockServer) -> Arc<crate::github::app::AppAuth> {
        Arc::new(crate::github::app::AppAuth::new(
            "12345".to_string(),
            crate::github::app::test_pem().to_string(),
            server.uri(),
        ))
    }

    async fn mount_installed(server: &wiremock::MockServer, repo: &str) {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, ResponseTemplate};
        Mock::given(method("GET"))
            .and(path(format!("/repos/{repo}/installation")))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"id": 42})))
            .mount(server)
            .await;
        Mock::given(method("POST"))
            .and(path("/app/installations/42/access_tokens"))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({
                "token": "inst-1",
                "expires_at": "2099-01-01T00:00:00Z",
            })))
            .mount(server)
            .await;
    }

    #[tokio::test]
    async fn app_mode_falls_back_to_comments_where_the_app_is_not_installed() {
        use crate::review_mode::ReviewMode;
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/repos/org/b/installation"))
            .respond_with(ResponseTemplate::new(404))
            .expect(1)
            .mount(&server)
            .await;
        let app = app_for_test(&server);

        assert!(
            review_app_for(ReviewMode::App, Some(Arc::clone(&app)), "org/b")
                .await
                .is_none()
        );
        // Comment mode never asks GitHub, the expect(1) above counts the only lookup
        assert!(
            review_app_for(ReviewMode::Comment, Some(Arc::clone(&app)), "org/b")
                .await
                .is_none()
        );
        assert!(
            review_app_for(ReviewMode::App, None, "org/b")
                .await
                .is_none()
        );
    }

    #[tokio::test]
    async fn the_check_run_starts_and_completes_on_the_reviewed_sha() {
        use wiremock::matchers::{body_partial_json, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};
        let server = MockServer::start().await;
        mount_installed(&server, "o/r").await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/check-runs"))
            .and(body_partial_json(serde_json::json!({
                "name": "orch/review", "head_sha": "abc123", "status": "in_progress",
            })))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 1})))
            .expect(1)
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/check-runs"))
            .and(body_partial_json(serde_json::json!({
                "name": "orch/review", "head_sha": "abc123", "status": "completed",
                "conclusion": "failure", "output": {"summary": "fix it"},
            })))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 2})))
            .expect(1)
            .mount(&server)
            .await;
        let app = app_for_test(&server);
        let gh = GhHttp::for_test(server.uri(), Some(Arc::clone(&app)));
        let decision = ReviewDecision::RequestChanges {
            notes: "fix it".to_string(),
            issues: vec![],
        };

        post_review_started(Some(&app), &gh, "o/r", Some("abc123")).await;
        post_review_decision(Some(&app), &gh, "o/r", Some("abc123"), &decision, "fix it").await;
        let requests = server.received_requests().await.expect("requests");
        assert!(
            requests
                .iter()
                .all(|req| !req.url.path().contains("/statuses/"))
        );
    }

    #[tokio::test]
    async fn issues_on_diff_lines_go_inline_and_the_rest_stay_in_the_body() {
        use crate::engine::runner::response::ReviewIssue;
        use wiremock::matchers::{method, path, query_param};
        use wiremock::{Mock, MockServer, ResponseTemplate};
        let server = MockServer::start().await;
        mount_installed(&server, "o/r").await;
        Mock::given(method("GET"))
            .and(path("/repos/o/r/pulls/9/files"))
            .and(query_param("page", "1"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([
                {"filename": "src/a.rs", "patch": "@@ -1,2 +10,3 @@\n ctx\n+new\n+new"},
            ])))
            .expect(1)
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/pulls/9/reviews"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"id": 1})))
            .expect(1)
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/issues/9/comments"))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 2})))
            .mount(&server)
            .await;
        let issue = |file: &str, line: Option<u32>| ReviewIssue {
            file: file.to_string(),
            line,
            severity: "error".to_string(),
            description: "wrong".to_string(),
        };
        let decision = ReviewDecision::RequestChanges {
            notes: "fix".to_string(),
            issues: vec![
                issue("src/a.rs", Some(11)),
                issue("src/a.rs", Some(50)),
                issue("src/b.rs", Some(3)),
                issue("src/a.rs", None),
            ],
        };
        let app = app_for_test(&server);
        let gh = GhHttp::for_test(server.uri(), Some(Arc::clone(&app)));

        publish_review(Some(&app), &gh, "o/r", 9, Some("abc123"), &decision, "body")
            .await
            .expect("comment posted");
        let requests = server.received_requests().await.expect("requests");
        let review = requests
            .iter()
            .find(|req| req.url.path().ends_with("/reviews"))
            .expect("review submitted");
        let body: serde_json::Value = serde_json::from_slice(&review.body).unwrap();
        assert_eq!(
            body["comments"],
            serde_json::json!([{"path": "src/a.rs", "line": 11, "side": "RIGHT", "body": "**error:** wrong"}])
        );
    }

    #[expect(
        clippy::await_holding_lock,
        reason = "the env lock must stay held across the awaited review call"
    )]
    #[tokio::test]
    async fn without_an_app_the_review_path_posts_only_the_comment() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};
        let _env = crate::github::token::ENV_LOCK.lock().unwrap();
        let prev = std::env::var_os("GH_TOKEN");
        // SAFETY: nextest runs each test in its own process, so no other test touches the environment
        unsafe { std::env::set_var("GH_TOKEN", "owner-token") };
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/issues/9/comments"))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 1})))
            .expect(1)
            .mount(&server)
            .await;
        let gh = GhHttp::for_test(server.uri(), None);
        let result = publish_review(
            None,
            &gh,
            "o/r",
            9,
            Some("abc123"),
            &ReviewDecision::Approve { issues: vec![] },
            "## Automated Review \u{2014} Approve\n\nok",
        )
        .await;
        match prev {
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            Some(value) => unsafe { std::env::set_var("GH_TOKEN", value) },
            // SAFETY: nextest runs each test in its own process, so no other test touches the environment
            None => unsafe { std::env::remove_var("GH_TOKEN") },
        }
        result.expect("comment posted");
        let requests = server.received_requests().await.expect("requests");
        assert!(
            requests
                .iter()
                .all(|req| !req.url.path().contains("/reviews"))
        );
    }

    #[tokio::test]
    async fn with_an_app_the_review_is_submitted_on_the_reviewed_sha() {
        use wiremock::matchers::{body_partial_json, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/app/installations/42/access_tokens"))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({
                "token": "inst-1",
                "expires_at": "2099-01-01T00:00:00Z",
            })))
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/pulls/9/reviews"))
            .and(body_partial_json(serde_json::json!({
                "event": "REQUEST_CHANGES",
                "commit_id": "abc123",
            })))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"id": 1})))
            .expect(1)
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/repos/o/r/issues/9/comments"))
            .respond_with(ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 2})))
            .expect(0)
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/repos/o/r/installation"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"id": 42})))
            .mount(&server)
            .await;
        let app = Arc::new(crate::github::app::AppAuth::new(
            "12345".to_string(),
            crate::github::app::test_pem().to_string(),
            server.uri(),
        ));
        let gh = GhHttp::for_test(server.uri(), Some(Arc::clone(&app)));
        let decision = ReviewDecision::RequestChanges {
            notes: "fix it".to_string(),
            issues: vec![],
        };
        publish_review(
            Some(&app),
            &gh,
            "o/r",
            9,
            Some("abc123"),
            &decision,
            "## Automated Review \u{2014} Changes Requested\n\nfix it",
        )
        .await
        .expect("comment posted");
    }
}