car_server_core/coder/

heal_live.rs

//! The real [`TickIo`]: live GitHub, live provenance, live coder session.
//!
//! Everything above this file was tested against a fake. This is the half that
//! actually touches the world, and it is deliberately thin — it fetches facts
//! and performs effects, and decides nothing. Every judgement the loop makes
//! lives in the pure cores (`heal_select`, `heal_gate`) so it can be reasoned
//! about without a network.
//!
//! ## Tiering is lazy, and that is a correctness property
//!
//! Resolving an author's permission is one `gh api` call, and
//! [`super::provenance::resolve_tier`] deliberately memoizes nothing —
//! "Nothing in this function memoizes, and nothing should be added that does."
//! Tiering all 200 scanned issues up front would be 200 calls per tick per
//! target, and worse, the chosen item's tier would be minutes stale by the time
//! it is used, past the freshness window the gate enforces.
//!
//! So candidates are built cheaply first — number, label, creation time — and
//! tiered only when one is actually reached, in [`TickIo::intent_for`]. That is
//! why [`Candidate::tier`] is `None` here: nobody has asked yet.
//!
//! It used to be `ProvenanceTier::Public`, on the reasoning that the absence of
//! a claim about the author should authorise nothing. The reasoning was right
//! and the encoding was wrong. `Public` is a *resolved* tier meaning "this
//! author is untrusted", and `heal_select::ineligible` checks authorisation
//! before anything else — correctly — so every candidate the live path produced
//! was rejected as `UntrustedAuthor` before selection ever looked at a label.
//! The loop could not select an item at all, and reported a reason that was not
//! true of any of those authors. Every unit test set a tier by hand, so only a
//! live run against a real tracker showed it.
//!
//! `None` says the true thing, and it does not widen what may run: nothing
//! starts a session on an unresolved tier, because `intent_for` below resolves
//! it for real and yields no seed when it refuses.
//!
//! ## What this file may not do
//!
//! It may not construct a [`GateOutcome`] — only `heal_gate::decide` can — and
//! it may not turn an issue body into anything a coder session or a reviewer
//! sees except through [`SessionSeed`]. Both are enforced by types rather than
//! by this comment.

use std::path::Path;
use std::sync::Arc;

use super::heal_gate::{GateOutcome, Unreachable, Verdict};
use super::heal_intake::{HealTarget, PullRequestApi, RawPullRequest};
use super::heal_select::{Candidate, CandidateKind};
use super::heal_tick::{Attempt, DeliverRefusal, Intent, RunFailure, TickIo};
use super::merge::PrDeliveryOutcome;
use super::provenance::{
    resolve_tier, LocalSignatures, PermissionOracle, ProvenanceRefusal, SessionSeed,
};

/// Runs a coder session and a review panel for one item.
///
/// Separate from [`LiveTickIo`] because it is the piece that needs the daemon's
/// runtime, its inference engine and a worktree, while everything else here
/// needs only `gh`. Keeping the seam means the GitHub half is testable — and
/// reviewable — without standing up an engine.
#[async_trait::async_trait]
pub trait CoderRunner: Send + Sync {
    /// Run the session, evaluate the outcome contract, and poll the review
    /// panel. Returns the evidence; the verdict is computed by the caller.
    async fn run(
        &self,
        target: &HealTarget,
        item: &Candidate,
        seed: &SessionSeed,
    ) -> Result<Attempt, RunFailure>;

    /// Commit, push, and reconcile exactly one pull request for the item.
    ///
    /// `body` is supplied by the caller rather than built here because it must
    /// be redacted, and the redactor lives with the GitHub half.
    async fn deliver(
        &self,
        target: &HealTarget,
        item: &Candidate,
        session_id: &str,
        body: &str,
    ) -> Result<PrDeliveryOutcome, DeliverRefusal>;

    /// Close a session out without delivering, releasing its worktree.
    async fn abandon(&self, session_id: &str);
}

/// The live implementation.
pub struct LiveTickIo {
    pub issues: Arc<dyn super::fix_issues::IssueApi>,
    pub prs: Arc<dyn PullRequestApi>,
    pub oracle: Arc<dyn PermissionOracle>,
    pub coder: Arc<dyn CoderRunner>,
    /// Signatures this runtime authored, for the `Runtime` tier.
    pub local_signatures: LocalSignatures,
    pub redactor: car_selfheal::redact::Redactor,
    /// The review panel with each seat resolved to the vendor serving it.
    ///
    /// Carried down to DELIVERY, not left in `heal.status`, because the pull
    /// request body is where the gate's verdict is actually read. "approved by
    /// 3/3 reviewers" is the number a human uses to decide how closely to read
    /// the change, and three seats served by one vendor approve at close to a
    /// single model's false-approval rate. Reporting that only to an operator
    /// who runs `car heal status` corrects the claim everywhere except where it
    /// is made.
    pub panel: Vec<super::heal_review::PanelSeat>,
}

/// The pull-request body: what the gate decided, and what decided it.
///
/// Pure so the thing a human actually reads can be asserted directly. The gate
/// summary alone says "approved by 3/3 reviewers", and a reader given only that
/// count cannot tell three reviewers from one vendor asked three times — so the
/// seats and, when it applies, the caveat travel WITH the verdict. A correction
/// that lives only in `heal.status` or a boot-time log corrects the claim
/// everywhere except where the claim is made.
fn pr_body(reference: &str, gate_summary: &str, panel: &[super::heal_review::PanelSeat]) -> String {
    let seats = if panel.is_empty() {
        String::new()
    } else {
        let rendered: Vec<String> = panel
            .iter()
            .map(|s| match &s.vendor {
                Some(v) => format!("{} ({v})", s.model),
                None => format!("{} (vendor unknown)", s.model),
            })
            .collect();
        format!("\n\nPanel: {}", rendered.join(", "))
    };
    let caveat = match super::heal_review::correlation_warning(panel) {
        Some(w) => format!("\n\n> **This panel is not demonstrably independent.** {w}"),
        None => String::new(),
    };
    format!(
        "Opened by CAR's self-healing loop for {reference}.\n\n\
         Gate: {gate_summary}{seats}{caveat}\n\n\
         This was written by an automated run. It is a pull request, not a merge: \
         a human decides."
    )
}

/// Build the candidate list without spending a permission call on any of them.
/// See the module docs on lazy tiering.
///
/// Free rather than a method because it is pure — the whole point of the split
/// is that what the loop *decides* can be tested without a network.
fn untiered_candidates(
    target: &HealTarget,
    issues: &[super::provenance::RawIssue],
    prs: &[RawPullRequest],
) -> Vec<Candidate> {
    let out: Vec<Candidate> = issues
        .iter()
        .map(|i| Candidate {
            repo: i.repo().to_string(),
            number: i.number(),
            // Nobody has asked yet. NOT `Public`, which is a resolved
            // "this author is untrusted" and made selection reject every
            // candidate before it ever looked at the label. `intent_for`
            // resolves this for the one item that is actually reached.
            tier: None,
            labelled: i.has_label(&target.label),
            created_ms: i.created_ms(),
            kind: CandidateKind::Issue,
        })
        .collect();

    // Failing pull requests are NOT candidates, and adding them back needs
    // more than deleting this comment.
    //
    // They were, and the path was dead in a way that starved the whole target.
    // `intent_for` resolves an item by number against `gh issue list`, which
    // does not return pull requests, so every such candidate resolved to
    // `Intent::Gone` — and `Gone`, correctly for the case it was written for,
    // records no failure. Combined with `created_ms: 0`, which sorts a pull
    // request ahead of every real issue, ONE labelled red pull request pinned
    // the target permanently: chosen first on every tick, reported `Gone`, with
    // no issue behind it ever reached.
    //
    // Two things must be settled before this returns. (1) Tiering is
    // issue-shaped — the only `resolve_tier` call site reads the issue list —
    // so a pull-request candidate has no route to a provenance tier at all.
    // (2) The proposal's open question 3 has not been answered: pushing to
    // someone else's pull-request branch is a different act from opening one,
    // and `delivery_branch` would mint `car/heal/<repo>-<pr>`, a fresh branch
    // unrelated to that pull request's head — so a "fix" would open a SECOND
    // pull request for the same work.
    let _ = prs;
    out
}

#[async_trait::async_trait]
impl TickIo for LiveTickIo {
    async fn candidates(&self, target: &HealTarget) -> Result<Vec<Candidate>, String> {
        let issues = self
            .issues
            .list_open_issues(&target.repo)
            .map_err(|e| format!("list issues on {}: {}", target.repo, e.message))?;
        let prs = self
            .prs
            .list_open_prs(target.coverage_repo())
            .map_err(|e| {
                format!(
                    "list pull requests on {}: {}",
                    target.coverage_repo(),
                    e.message
                )
            })?;
        Ok(untiered_candidates(target, &issues, &prs))
    }

    async fn open_prs(&self, target: &HealTarget) -> Result<Vec<RawPullRequest>, String> {
        // The COVERAGE repo, not the queue repo. A pull request lands where its
        // branch was pushed, so asking the tracker whether an issue is covered
        // queries a repository that can never hold the answer.
        self.prs.list_open_prs(target.coverage_repo()).map_err(|e| {
            format!(
                "list pull requests on {}: {}",
                target.coverage_repo(),
                e.message
            )
        })
    }

    async fn intent_for(&self, item: &Candidate) -> Result<Intent, String> {
        // Re-read the item and tier it NOW. The candidate's tier is a
        // placeholder; this is where the authorisation actually happens, on
        // fresh permission data, for the one item that was selected.
        let open = self
            .issues
            .list_open_issues(&item.repo)
            .map_err(|e| format!("re-read {}: {}", item.repo, e.message))?;
        let Some(raw) = open.into_iter().find(|i| i.number() == item.number) else {
            // Closed or edited between the scan and now. Not an error: the
            // queue moved, which is the normal case for a human-authored one.
            return Ok(Intent::Gone);
        };

        let tiered = resolve_tier(
            raw,
            self.oracle.as_ref(),
            &self.local_signatures,
            std::time::SystemTime::now(),
        );
        let tier = tiered.tier();
        match tiered.seed_session(std::time::SystemTime::now()) {
            Ok(seed) => Ok(Intent::Seed(seed)),
            Err(refusal) => {
                // A refusal is not a failure of the loop. It is the gate doing
                // its job, and it is logged at the tier rather than surfaced as
                // an error the operator must act on.
                tracing::info!(
                    repo = %item.repo,
                    number = item.number,
                    refusal = ?refusal,
                    "self-heal: item not cleared to seed a session"
                );
                Ok(Intent::Refused {
                    tier,
                    stale: matches!(refusal, ProvenanceRefusal::StaleTier { .. }),
                })
            }
        }
    }

    fn redact(&self, text: &str) -> String {
        self.redactor.redact(text)
    }

    async fn run_coder(
        &self,
        target: &HealTarget,
        item: &Candidate,
        seed: &SessionSeed,
    ) -> Result<Attempt, RunFailure> {
        self.coder.run(target, item, seed).await
    }

    async fn deliver(
        &self,
        target: &HealTarget,
        item: &Candidate,
        session_id: &str,
        gate: &GateOutcome,
    ) -> Result<PrDeliveryOutcome, DeliverRefusal> {
        // The body MUST reference the issue. Coverage is what stops a later
        // tick redoing this work once the claim expires, and it matches on that
        // reference — so a pull request that omits it is a pull request the
        // loop will duplicate.
        let reference = if target.is_cross_repo() {
            format!("{}#{}", item.repo, item.number)
        } else {
            format!("#{}", item.number)
        };
        // Redacted, for the same reason every issue comment is: the gate
        // summary carries contract output and vendor error strings, and a pull
        // request body is exactly as public — and exactly as unpostable after
        // the fact — as a comment. The successful path is the one that carries
        // the most contract output, so leaving it raw here would have leaked
        // more than the failure path it was guarded on.
        let body = pr_body(
            &reference,
            &self.redactor.redact(&gate.summary()),
            &self.panel,
        );

        self.coder.deliver(target, item, session_id, &body).await
    }

    async fn abandon(&self, session_id: &str) {
        self.coder.abandon(session_id).await;
    }

    async fn comment(&self, item: &Candidate, text: &str) -> Result<(), String> {
        let args: Vec<String> = vec![
            "issue".into(),
            "comment".into(),
            item.number.to_string(),
            "--repo".into(),
            item.repo.clone(),
            "--body".into(),
            text.to_string(),
        ];
        super::merge::gh(Path::new("."), &args)
            .map(|_| ())
            .map_err(|e| format!("comment on {}#{}: {}", item.repo, item.number, e.message))
    }

    fn now_ms(&self) -> u64 {
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_millis() as u64)
            .unwrap_or(0)
    }
}

/// Turn a panel's raw answers into verdicts, refusing to guess.
///
/// An answer that cannot be read as PASS or FAIL is [`Unreachable`], never a
/// pass. There are already two PASS/FAIL parsers in this workspace
/// (`car-agents::verifier` and `car-multi`'s adversarial review, which has an
/// explicit inconclusive path); this is the third place that has to make the
/// same call, and the only safe reading of "I could not tell what the reviewer
/// said" is that the reviewer did not approve.
pub fn parse_verdict(model: &str, answer: &str) -> Result<Verdict, Unreachable> {
    // The FIRST verdict token, not a substring scan of the whole answer.
    //
    // Scanning for "PASS" and "FAIL" anywhere and calling both-or-neither
    // unreadable looks conservative and is not: the prompt asks for a verdict
    // followed by a sentence of reason, and a sentence justifying a pass
    // routinely contains the word "fail". "PASS — nothing here would fail the
    // existing checks" matched both and became `Unreachable`. Two of those on
    // a panel of three is `PanelIncomplete`, which costs a full coder session
    // and a backoff — and every test of this function used hand-written
    // strings shaped to avoid the collision, so the whole suite was blind to
    // it.
    //
    // A verdict is a word, so read it as one: scan tokens in order and take
    // the first that IS "pass" or "fail", ignoring surrounding punctuation.
    // Anything before it is a preamble; anything after is the reason.
    let verdict = answer
        .split(|c: char| c.is_whitespace())
        .map(|t| t.trim_matches(|c: char| !c.is_ascii_alphabetic()))
        .find_map(|t| match t.to_ascii_uppercase().as_str() {
            "PASS" => Some(true),
            "FAIL" => Some(false),
            _ => None,
        });

    // No verdict token at all is unreadable — never a pass. There are two other
    // PASS/FAIL parsers in this workspace and this is the third place that has
    // to make the same call; the only safe reading of "I could not tell what
    // the reviewer said" is that the reviewer did not approve.
    let Some(pass) = verdict else {
        return Err(Unreachable {
            model: model.to_string(),
            error: "reviewer answer contained neither a PASS nor a FAIL verdict".into(),
        });
    };
    Ok(Verdict {
        model: model.to_string(),
        pass,
        reason: answer.trim().chars().take(280).collect(),
    })
}

#[cfg(test)]
mod tests {

    use super::super::heal_review::PanelSeat;

    fn seat(model: &str, vendor: Option<&str>) -> PanelSeat {
        PanelSeat {
            model: model.to_string(),
            vendor: vendor.map(str::to_string),
        }
    }

    /// The verdict and what produced it travel together.
    ///
    /// car#1263: the body said "approved by 3/3 reviewers" and nothing else, so
    /// three seats served by one vendor were indistinguishable from three
    /// independent ones — to the human using that number to decide how closely
    /// to read the change.
    #[test]
    fn the_pull_request_body_carries_the_panel_and_its_caveat() {
        let body = pr_body(
            "#42",
            "approved by 3/3 reviewers, checks green",
            &[
                seat("gpt-5.5", Some("openai")),
                seat("gpt-5.4", Some("openai")),
                seat("gpt-5.6-sol", Some("openai")),
            ],
        );
        // The reference coverage matches on is still there.
        assert!(body.contains("#42"), "{body}");
        assert!(body.contains("approved by 3/3 reviewers"), "{body}");
        // ...and so is who approved it, and why that is worth less than it looks.
        assert!(body.contains("gpt-5.5 (openai)"), "{body}");
        assert!(body.contains("not demonstrably independent"), "{body}");
        assert!(body.contains("openai serves 3 of the 3 seats"), "{body}");
    }

    /// A genuinely independent panel is reported without a caveat — the warning
    /// has to mean something when it appears.
    #[test]
    fn an_independent_panel_gets_seats_but_no_caveat() {
        let body = pr_body(
            "acme/repo#7",
            "approved by 2/3 reviewers, checks green",
            &[
                seat("gpt-5.5", Some("openai")),
                seat("claude-opus-5", Some("anthropic")),
                seat("gemini-3.1", Some("google")),
            ],
        );
        assert!(body.contains("acme/repo#7"), "{body}");
        assert!(body.contains("claude-opus-5 (anthropic)"), "{body}");
        assert!(!body.contains("not demonstrably independent"), "{body}");
    }

    /// An empty panel must not add a stray blank section — the loop refuses a
    /// panel of zero anyway, so this is only about the rendering.
    #[test]
    fn no_panel_adds_no_panel_section() {
        let body = pr_body("#1", "approved by 1/1 reviewers, checks green", &[]);
        assert!(!body.contains("Panel:"), "{body}");
        assert!(!body.contains("not demonstrably independent"), "{body}");
    }

    use super::*;

    #[test]
    fn a_clear_pass_and_a_clear_fail_are_read() {
        assert!(parse_verdict("a", "PASS — scoped correctly").unwrap().pass);
        assert!(
            !parse_verdict("a", "FAIL: changes unrelated code")
                .unwrap()
                .pass
        );
    }

    #[test]
    fn an_unreadable_answer_is_unreachable_never_a_pass() {
        // The safe reading of "I could not tell what the reviewer said" is that
        // the reviewer did not approve.
        assert!(parse_verdict("a", "I think it's probably fine?").is_err());
        assert!(parse_verdict("a", "").is_err());
    }

    #[test]
    fn a_reason_mentioning_the_other_word_does_not_destroy_the_verdict() {
        // THE regression, and the likeliest thing to have gone wrong on the
        // first real panel: the prompt asks for a verdict plus a sentence, and
        // a sentence justifying a pass routinely says "fail".
        let v = parse_verdict("a", "PASS — nothing here would fail the existing checks").unwrap();
        assert!(v.pass);
        let v = parse_verdict("a", "FAIL — this would not pass review by a human").unwrap();
        assert!(!v.pass);
    }

    #[test]
    fn the_first_verdict_token_wins() {
        // A reviewer that leads with FAIL and later muses about passing has
        // given a FAIL. Reading the last token instead would let a trailing
        // aside overturn the verdict.
        let v = parse_verdict("a", "FAIL. It might pass once the test is added.").unwrap();
        assert!(!v.pass);
    }

    #[test]
    fn a_verdict_inside_prose_is_still_read() {
        // Models do not reliably lead with the token, and refusing an answer
        // that plainly contains one would fail the item for formatting.
        assert!(
            parse_verdict("a", "My verdict: PASS, it matches the intent")
                .unwrap()
                .pass
        );
    }

    #[test]
    fn a_word_containing_pass_is_not_a_verdict() {
        // `contains` matched "passed", "passes", "bypass", "compass". A verdict
        // is a word.
        assert!(parse_verdict("a", "the tests bypassed the new branch").is_err());
        assert!(parse_verdict("a", "this passes muster").is_err());
    }

    #[test]
    fn a_reason_is_bounded() {
        let long = "PASS ".to_string() + &"x".repeat(1000);
        let v = parse_verdict("a", &long).unwrap();
        assert!(
            v.reason.len() <= 280,
            "an unbounded reason reaches a tracker"
        );
    }

    #[test]
    fn scanned_candidates_are_untiered_not_public() {
        // The regression this pins: `Public` is a RESOLVED "untrusted", and
        // `heal_select::ineligible` rejects a resolved denial before it looks
        // at anything else — so building candidates as `Public` made the live
        // loop skip every issue as `UntrustedAuthor` and select nothing, ever.
        let issues = vec![crate::coder::provenance::RawIssue::new(
            "acme/widgets",
            7,
            "maintainer",
            "a title",
            "a body",
            vec!["self-heal".to_string()],
            1,
        )];
        let target = HealTarget {
            repo: "acme/widgets".into(),
            fix_repo: None,
            checkout: Some(crate::coder::heal_intake::Checkout::Local("/tmp/x".into())),
            label: "self-heal".into(),
            base: "main".into(),
        };
        let out = untiered_candidates(&target, &issues, &[]);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].tier, None, "a scanned candidate is untiered");
        assert!(out[0].labelled, "the cheap checks still ran");
    }

    #[test]
    fn public_still_authorises_nothing_where_it_is_resolved() {
        // The tier itself is unchanged; only the encoding of "not yet asked".
        assert!(!crate::coder::provenance::ProvenanceTier::Public.may_seed_session());
        assert!(!crate::coder::provenance::ProvenanceTier::Public.may_source_contract());
    }
}