car_server_core/coder/

contract.rs

//! Outcome contracts — the verifiable definition of "done" for a coder session.
//!
//! A contract is a set of shell commands that must pass inside the worktree.
//! It is derived from the user's intent by a model (with a bounded repair loop
//! mirroring `car-builder`: generation is an injected closure, so tests run
//! without inference) and then becomes the trust boundary for the whole
//! session: whatever engine did the work — the native loop or an external CLI
//! — the runtime re-runs the checks itself before asking for merge approval.
//!
//! # What a contract can and cannot assert
//!
//! The point-in-time assertion vocabulary is
//! [`ContractCheck::expect_exit_zero`] and
//! [`ContractCheck::output_contains`]. The latter normally checks a substring;
//! its reserved `$json:<pointer>=<json>` form performs runtime-owned JSON value
//! equality. That is not the boundary, though: the command is graded on its exit code, so a threshold
//! against a live system (`[ "$(…)" -lt 100000 ]`) is a legal check today, and
//! contract checks are deliberately not de-credentialed, which is why they run
//! through `WorktreeExecutor::run_check_shell` rather than the model's own
//! `run_shell`.
//!
//! **Before/after claims are expressible too** (Parslee-ai/car#1067). A check
//! marked [`ContractCheck::baseline`] is a *capture*: it runs once, at session
//! start, inside [`evaluate_contract_baseline`]'s pass over the unmodified
//! worktree, and its output is kept ([`BaselineCaptures`], built by
//! [`collect_baseline_captures`]). A check carrying a
//! [`ContractCheck::differential`] runs at every later evaluation and its
//! output is compared against the named capture by the RUNTIME — exhaustively
//! one of [`DifferentialExpect::Changed`], [`DifferentialExpect::Unchanged`]
//! (the control-group claim), or [`DifferentialExpect::DeltaWithin`] (numeric
//! delta bounds). The command is arbitrary — a row count, a file digest, a
//! `curl` body — so the external subject falls out of the command, subject to
//! the same policy chain as every check (car#1066); what this adds is the
//! before/after structure. Both executions are runtime-owned and both results
//! are stamped into the session's events (the capture in `contract_baseline`,
//! the comparison in `check_completed`): model claims count for nothing.
//!
//! What is still missing is an **evaluation point past delivery**. Every
//! evaluation is on this side of it:
//! [`evaluate_contract_baseline`] against the unmodified worktree, then
//! [`evaluate_contract`] once per repair round inside the loop, then
//! [`evaluate_contract_within`] as the gate that admits delivery. Only
//! `car code-task` runs that gate as a *separate* pass after the loop, holding
//! the loop's own verdict advisory; a daemon session finalizes straight off the
//! loop's last evaluation, which is the same call one layer down. Nothing runs
//! after either way. So a claim about what a DEPLOY changed ("the row count
//! fell *after the deploy*") still belongs to the orchestrator wrapping the
//! session, which owns the deploy and both sides of that window — the
//! differential machinery here measures across the session's *work*, not
//! across a deploy the session never performs. See `docs/car-code-task.md`.

use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::HashMap;
use std::future::Future;
use std::time::Duration;

/// Per-attempt cap on the contract-derivation generation call. Without it, a
/// hung inference backend (e.g. no usable local model — see PAR-7169/PAR-7264)
/// makes `derive_contract` block indefinitely, so `Derive contract` / `car code`
/// just sits on "deriving outcome contract…" forever and orphans a 0-byte event
/// log (PAR-7170). With it, a stuck attempt fails fast with an actionable error.
const CONTRACT_GEN_TIMEOUT: Duration = Duration::from_secs(120);

use super::budget::SessionDeadline;
use super::session::{CoderEventKind, EventSink};
use super::shell_tool::WorktreeExecutor;

fn default_true() -> bool {
    true
}

fn default_check_timeout() -> u64 {
    120
}

/// The verifiable definition of done for a coding session.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct OutcomeContract {
    /// Human summary of what success means.
    pub description: String,
    /// Checks that must all pass. Evaluated through the same policy-gated
    /// shell inspector chain as the agent's own calls, so a project
    /// `deny_tool` rule refuses a "check" exactly as it would a tool call.
    /// The *credential* posture differs — see the module docs.
    pub checks: Vec<ContractCheck>,
}

/// One acceptance check: a shell command run at the worktree root.
///
/// [`expect_exit_zero`](Self::expect_exit_zero) and
/// [`output_contains`](Self::output_contains) are the point-in-time assertion
/// vocabulary (including its reserved semantic JSON form). Before/after claims
/// use [`baseline`](Self::baseline) + [`differential`](Self::differential) —
/// see the module docs for the model and its limits.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ContractCheck {
    /// Short, unique label ("tests_pass", "file_created").
    pub name: String,
    /// Command run via the worktree shell tool.
    pub command: String,
    /// Require exit code 0 (default true).
    #[serde(default = "default_true")]
    pub expect_exit_zero: bool,
    /// Additionally require this substring in the combined output. A value in
    /// the reserved `$json:<pointer>=<json>` form is instead evaluated by the
    /// runtime as a semantic assertion against the command's JSON output.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output_contains: Option<String>,
    /// Per-check timeout (default 120s; the shell tool clamps further).
    #[serde(default = "default_check_timeout")]
    pub timeout_secs: u64,
    /// Capture-only check: run once at session start (during the baseline
    /// pass) and its output kept as the before-value other checks may diff
    /// against by [`name`](Self::name). At the gating evaluations it is NOT
    /// re-run — re-capturing "before" after the work would destroy the
    /// comparison — its capture-time result is carried into the results
    /// instead, so a failed capture keeps the gate red rather than vanishing.
    ///
    /// Additive and `serde(default)`, so every existing contract parses
    /// unchanged.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub baseline: bool,
    /// Differential assertion: after this check's command runs, compare its
    /// output against the named baseline capture. Evaluated by the runtime —
    /// exhaustively one of changed / unchanged / delta-within-bounds — in
    /// ADDITION to `expect_exit_zero` / `output_contains`, never instead.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub differential: Option<DifferentialCheck>,
}

/// A before/after claim: compare this check's output against a named
/// [`baseline`](ContractCheck::baseline) capture.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DifferentialCheck {
    /// Name of the baseline-marked check whose captured output is the
    /// before-value. Must be declared BEFORE this check in the contract —
    /// captures accumulate in declaration order during the baseline pass.
    pub baseline: String,
    /// The claim itself.
    pub expect: DifferentialExpect,
}

/// The differential claims the runtime can decide. Matching is exhaustive
/// everywhere — a new variant must be handled at every site or the build
/// fails, which is the point.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DifferentialExpect {
    /// The output must differ from the captured baseline ("this trace now
    /// appears and did not before", "the heartbeat flipped").
    Changed,
    /// The output must be identical to the captured baseline — the
    /// control-group claim ("the other tenant's rows did not move").
    Unchanged,
    /// Both outputs must carry a number, and `after - before` must fall within
    /// the stated bounds (either side optional, at least one required —
    /// [`OutcomeContract::validate`] rejects the unbounded form). "Orphaned
    /// rows fell by at least 100" is `{ "max": -100.0 }`.
    DeltaWithin {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        min: Option<f64>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        max: Option<f64>,
    },
}

/// Baseline captures by capturing check name — the before-values differential
/// checks compare against. Built from the session-start baseline pass by
/// [`collect_baseline_captures`]; the capture is the check's [`CheckResult`],
/// whose `output_tail` (the 4 KiB tail) is the compared value, so keep a
/// capture command's output small and deterministic (a count, a digest, a
/// status line — not a full dump).
pub type BaselineCaptures = HashMap<String, CheckResult>;

/// Extract the baseline captures from a session-start baseline pass: the
/// results of every check the contract marks [`ContractCheck::baseline`].
pub fn collect_baseline_captures(
    contract: &OutcomeContract,
    baseline_results: &[CheckResult],
) -> BaselineCaptures {
    contract
        .checks
        .iter()
        .filter(|c| c.baseline)
        .filter_map(|c| {
            baseline_results
                .iter()
                .find(|r| r.name == c.name)
                .map(|r| (c.name.clone(), r.clone()))
        })
        .collect()
}

/// Result of evaluating one [`ContractCheck`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CheckResult {
    pub name: String,
    pub passed: bool,
    /// None when the command could not run at all (spawn/policy failure).
    pub exit_code: Option<i64>,
    /// Tail of combined stdout+stderr — enough for repair prompts and the UI.
    pub output_tail: String,
    pub duration_ms: u64,
    /// The command was killed at a timeout instead of exiting on its own.
    ///
    /// Additive and `serde(default)`, so results persisted before this field
    /// existed still deserialize.
    #[serde(default)]
    pub timed_out: bool,
    /// The timeout it was killed at was the SESSION's remaining budget, not the
    /// check's own effective ceiling — see [`deadline_set_the_timeout`], which
    /// is where "effective" is load-bearing: the ceiling is
    /// `min(timeout_secs, max_check_timeout_secs)`, not the declared
    /// `timeout_secs`.
    #[serde(default)]
    pub deadline_clamped: bool,
}

impl CheckResult {
    /// This result is **not a verdict on the work**: the check was killed by
    /// the session clock before it could reach one.
    ///
    /// Anyone deciding what to book a red gate as has to ask this first. A
    /// starved check says nothing about whether the change is correct — it says
    /// the run was out of time — so scoring it as a task loss books a budget
    /// decision against the model. Both bits are needed to tell them apart: a
    /// check that blew its OWN `timeout_secs` is a genuine red (a hang is a
    /// defect), and only one clamped down to the session's leftover seconds is
    /// starved.
    pub fn starved_by_deadline(&self) -> bool {
        self.timed_out && self.deadline_clamped
    }
}

impl OutcomeContract {
    /// Structural problems that make a contract unusable. Empty = valid.
    ///
    /// Beyond pure structure (empty/duplicate names, assertion-less checks)
    /// this also rejects two failure modes seen live from small local models
    /// (issue #168 follow-up): the prompt's literal placeholder name leaking
    /// through verbatim, and "toolchain-only" no-op commands like
    /// `cargo --version` that prove nothing about the change. Both pass the
    /// structural checks but make a contract that gates nothing, so they're
    /// surfaced as validation issues to drive the repair loop rather than
    /// silently becoming the trust boundary.
    pub fn validate(&self) -> Vec<String> {
        let mut issues = Vec::new();
        if self.checks.is_empty() {
            issues.push("contract has no checks — at least one is required".to_string());
        }
        let mut seen = std::collections::HashSet::new();
        for (i, c) in self.checks.iter().enumerate() {
            let name = c.name.trim();
            if name.is_empty() {
                issues.push(format!("check #{i} has an empty name"));
            }
            if name == "unique_snake_case_label" {
                issues.push(format!(
                    "check #{i} kept the literal placeholder name \
                     'unique_snake_case_label' — give it a real descriptive label"
                ));
            }
            if c.command.trim().is_empty() {
                issues.push(format!("check '{}' has an empty command", c.name));
            } else if is_toolchain_only(c.command.trim()) {
                issues.push(format!(
                    "check '{}' runs a toolchain-only no-op (`{}`) that verifies the \
                     tool is installed, not the task — replace it with a command that \
                     exercises the actual change",
                    c.name,
                    c.command.trim()
                ));
            }
            if !seen.insert(name.to_string()) {
                issues.push(format!("duplicate check name '{}'", c.name));
            }
            // A baseline capture is exempt from the asserts-nothing rule: its
            // job is to CAPTURE a before-value, and demanding an assertion
            // would force a vacuous one onto every capture.
            if !c.expect_exit_zero && c.output_contains.is_none() && !c.baseline {
                issues.push(format!(
                    "check '{}' asserts nothing (expect_exit_zero=false and no output_contains)",
                    c.name
                ));
            }
            if c.baseline && c.differential.is_some() {
                issues.push(format!(
                    "check '{}' is both a baseline capture and a differential — a capture is \
                     the before-value, it cannot also diff against one; split it into two \
                     checks",
                    c.name
                ));
            }
            if let Some(diff) = &c.differential {
                // The referenced capture must exist, be marked baseline, and be
                // declared BEFORE this check — captures accumulate in
                // declaration order during the baseline pass.
                let target = self
                    .checks
                    .iter()
                    .position(|t| t.name == diff.baseline && t.baseline);
                match target {
                    None => issues.push(format!(
                        "check '{}' diffs against baseline '{}', but no check by that name is \
                         marked baseline: true",
                        c.name, diff.baseline
                    )),
                    Some(pos) if pos >= i => issues.push(format!(
                        "check '{}' diffs against baseline '{}', which is declared after it — \
                         declare the capture first",
                        c.name, diff.baseline
                    )),
                    Some(_) => {}
                }
                // Exhaustive on purpose: a new differential kind must state its
                // validation here or the build fails.
                match &diff.expect {
                    DifferentialExpect::Changed | DifferentialExpect::Unchanged => {}
                    DifferentialExpect::DeltaWithin { min, max } => {
                        if min.is_none() && max.is_none() {
                            issues.push(format!(
                                "check '{}' declares delta_within with no bounds — an unbounded \
                                 delta asserts nothing; state min, max, or both",
                                c.name
                            ));
                        }
                        if let (Some(lo), Some(hi)) = (min, max) {
                            if lo > hi {
                                issues.push(format!(
                                    "check '{}' declares delta_within bounds [{lo}, {hi}] with \
                                     min above max — no delta can satisfy that",
                                    c.name
                                ));
                            }
                        }
                    }
                }
            }
        }
        if !self.checks.is_empty() && self.checks.iter().all(|c| c.baseline) {
            issues.push(
                "every check is a baseline capture — nothing evaluates the outcome; add at \
                 least one non-baseline check"
                    .to_string(),
            );
        }
        issues
    }

    /// Repair *cosmetic* naming problems weak local models commonly produce —
    /// the literal `unique_snake_case_label` placeholder leaking through, an
    /// empty name, or a duplicate — by assigning deterministic fallback labels
    /// (`check_1`, `check_2`, …, suffixed on collision).
    ///
    /// Dogfooding finding (2026-07-12): a small local model repeatedly echoed
    /// the schema placeholder as a check name, and `derive_contract`'s bounded
    /// repair loop couldn't coax a better one out of it in 3 attempts, so the
    /// entire coder session aborted *before any coding* over a name. A check's
    /// NAME is cosmetic — the `command` is the trust boundary — so a naming slip
    /// must not be a hard failure. Substance problems (empty/toolchain-only/
    /// assertion-less commands) are deliberately left for [`validate`](crate::coder::contract::OutcomeContract::validate) to drive
    /// the repair loop, since those DO make the contract gate nothing.
    pub fn repair_cosmetic_names(&mut self) {
        let mut seen = std::collections::HashSet::new();
        for i in 0..self.checks.len() {
            let name = self.checks[i].name.trim().to_string();
            let base = if name.is_empty() || name == "unique_snake_case_label" {
                format!("check_{}", i + 1)
            } else {
                name
            };
            let mut candidate = base.clone();
            let mut k = 2;
            while !seen.insert(candidate.clone()) {
                candidate = format!("{base}_{k}");
                k += 1;
            }
            self.checks[i].name = candidate;
        }
    }

    /// Strip a hallucinated absolute-path `cd` prefix from each check command.
    ///
    /// Checks run at the worktree root — the runtime sets CWD. But the derivation
    /// model, trained on Docker-based coding harnesses, sometimes prefixes a check
    /// with `cd /repo && …` (or another absolute mount that does not exist here).
    /// That command then dies on `cd: /repo: No such file or directory` for EVERY
    /// check, so a correctly-solved task self-verifies as failed and the session
    /// ends "failed" — a false negative (surfaced by the coder A/B on a bytes2human
    /// fix the coder got right in one iteration). We drop only a *leading*
    /// `cd <absolute> &&` / `cd <absolute> ;` (the runtime owns CWD, so it is
    /// redundant at best and wrong at worst); a relative `cd subdir && …` is a
    /// legitimate intra-repo move and is left untouched.
    pub fn strip_absolute_cd_prefixes(&mut self) {
        for check in &mut self.checks {
            check.command = strip_leading_absolute_cd(&check.command);
        }
    }

    /// Drop a trailing output-limiting pipe (`… | tail -20`, `| head -n 50`,
    /// `| cat`) from each check command.
    ///
    /// A shell pipeline exits with the status of its **last** command, so
    /// `pytest … | tail -20` exits 0 no matter how badly pytest failed. The
    /// derivation model adds these to keep output short, and thereby makes the
    /// check *structurally incapable of failing*: `expect_exit_zero` ends up
    /// asserting that `tail` ran, which it always does. The coder then
    /// self-verifies green on broken code, reports `needs_approval`, and prints a
    /// merge command — which is the exact opposite of this runtime's promise that
    /// success means "a real command exited 0".
    ///
    /// Worse, it is self-concealing: a masked check can never report the failure
    /// that would let the repair loop notice its command is wrong, so the session
    /// converges instantly on a lie. Surfaced by the coder A/B, where a gpt-5.4
    /// arm derived `python -m pytest tests/ -x -q 2>&1 | tail -20`, went green in
    /// 31s without `flask` even importable, and lost every task to the manifest's
    /// (unpiped) contract.
    ///
    /// Only *output filters* are stripped — `tail`/`head`/`cat` exist purely to
    /// truncate and always succeed. A pipe into `grep` is left alone: its exit
    /// status is a real assertion ("output contains X"), which is a legitimate
    /// check the model may intend.
    pub fn strip_exit_masking_pipes(&mut self) {
        for check in &mut self.checks {
            if check.expect_exit_zero {
                check.command = strip_trailing_output_filter(&check.command);
            }
        }
    }

    /// Render for prompts and CLI display.
    pub fn render(&self) -> String {
        let mut out = format!("{}\nChecks:\n", self.description.trim());
        for c in &self.checks {
            out.push_str(&format!("- {}: `{}`", c.name, c.command));
            let mut expects = Vec::new();
            if c.baseline {
                expects.push("baseline capture at session start".to_string());
            }
            if c.expect_exit_zero {
                expects.push("exit 0".to_string());
            }
            if let Some(s) = &c.output_contains {
                if let Some(assertion) = s.strip_prefix("$json:") {
                    expects.push(format!("JSON asserts {assertion}"));
                } else {
                    expects.push(format!("output contains {s:?}"));
                }
            }
            if let Some(diff) = &c.differential {
                // Exhaustive: a new kind must say how it renders.
                let claim = match &diff.expect {
                    DifferentialExpect::Changed => "changed".to_string(),
                    DifferentialExpect::Unchanged => "unchanged".to_string(),
                    DifferentialExpect::DeltaWithin { min, max } => format!(
                        "delta within [{}, {}]",
                        min.map_or("-inf".to_string(), |m| m.to_string()),
                        max.map_or("+inf".to_string(), |m| m.to_string()),
                    ),
                };
                expects.push(format!("vs baseline '{}': {claim}", diff.baseline));
            }
            if !expects.is_empty() {
                out.push_str(&format!(" (expects {})", expects.join(", ")));
            }
            out.push('\n');
        }
        out
    }
}

/// Drop a single leading `cd <absolute-path> &&` (or `;`) from a shell command,
/// repeatedly, returning the remainder that runs at the worktree root. A relative
/// `cd` (not starting with `/`) is preserved — it is a legitimate intra-repo move.
/// Only the *leading* separator form is handled: an absolute `cd` buried later in
/// the command is left alone (rare, and rewriting it risks changing semantics).
/// Commands that exist only to truncate output and therefore always exit 0.
/// Piping into one of these discards the real command's exit status.
const OUTPUT_FILTERS: [&str; 3] = ["tail", "head", "cat"];

/// Drop trailing `| tail …` / `| head …` / `| cat` segments, repeatedly, so the
/// pipeline's exit status is the real command's again. `||` is an or-list, not a
/// pipe, and pipes inside quotes are not separators — neither is treated as one.
fn strip_trailing_output_filter(command: &str) -> String {
    let mut rest = command.trim().to_string();
    loop {
        let Some(idx) = last_top_level_pipe(&rest) else {
            return rest;
        };
        let tail_seg = rest[idx + 1..].trim();
        let head_word = tail_seg.split_whitespace().next().unwrap_or("");
        if !OUTPUT_FILTERS.contains(&head_word) {
            return rest;
        }
        // Only strip when the segment is *just* the filter and its flags — a
        // `| tail -5 && something` is not a plain truncation, leave it be.
        if tail_seg.contains("&&") || tail_seg.contains(';') || tail_seg.contains("||") {
            return rest;
        }
        rest = rest[..idx].trim_end().to_string();
        if rest.is_empty() {
            return command.trim().to_string(); // degenerate; leave untouched
        }
    }
}

/// Byte index of the last `|` that is a real pipe separator: not inside quotes,
/// and not part of a `||`.
fn last_top_level_pipe(s: &str) -> Option<usize> {
    let b = s.as_bytes();
    let (mut sq, mut dq) = (false, false);
    let mut found = None;
    let mut i = 0;
    while i < b.len() {
        match b[i] {
            b'\\' => i += 1, // skip escaped char
            b'\'' if !dq => sq = !sq,
            b'"' if !sq => dq = !dq,
            b'|' if !sq && !dq => {
                if b.get(i + 1) == Some(&b'|') {
                    i += 1; // `||` — an or-list, not a pipe
                } else if i > 0 && b[i - 1] == b'|' {
                    // trailing half of a `||` already consumed
                } else {
                    found = Some(i);
                }
            }
            _ => {}
        }
        i += 1;
    }
    found
}

fn strip_leading_absolute_cd(command: &str) -> String {
    let mut rest = command.trim();
    while let Some(after_cd) = rest.strip_prefix("cd ") {
        // Find the separator that ends the `cd` clause.
        let sep = after_cd
            .find("&&")
            .map(|i| (i, 2))
            .into_iter()
            .chain(after_cd.find(';').map(|i| (i, 1)))
            .min_by_key(|(i, _)| *i);
        let Some((idx, sep_len)) = sep else {
            break;
        };
        let path = after_cd[..idx].trim();
        // Only strip when the cd target is an absolute path (a single token). A
        // relative target, or a compound like `cd a || b`, is left as-is.
        if !path.starts_with('/') || path.split_whitespace().count() != 1 {
            break;
        }
        rest = after_cd[idx + sep_len..].trim_start();
    }
    rest.to_string()
}

/// True when a command only probes that a build tool is installed (e.g.
/// `cargo --version`, `rustc --version`, `node -v`) — it proves nothing about
/// the task. Conservative by design: it only fires on a bare
/// `<tool> --version` / `-V` / `--help` / `-v` invocation with no other
/// subcommand or shell composition, so real checks like `cargo run -- --version`,
/// `cargo build`, or `cargo test --version-of-something` are never flagged.
fn is_toolchain_only(command: &str) -> bool {
    // Any shell composition means it's doing more than a bare version probe.
    if command.contains("&&")
        || command.contains("||")
        || command.contains('|')
        || command.contains(';')
        || command.contains('\n')
    {
        return false;
    }
    let tokens: Vec<&str> = command.split_whitespace().collect();
    // Expect exactly `<tool> <version-or-help-flag>`. Anything longer (e.g.
    // `cargo run -- --version`, `cargo build`) has a subcommand and is real.
    let [tool, flag] = tokens.as_slice() else {
        return false;
    };
    const TOOLS: &[&str] = &[
        "cargo", "rustc", "rustup", "node", "npm", "npx", "yarn", "pnpm", "python", "python3",
        "pip", "pip3", "go", "java", "javac", "ruby", "gem", "dotnet", "deno", "bun", "tsc", "gcc",
        "clang", "make", "cmake",
    ];
    const FLAGS: &[&str] = &["--version", "-V", "-v", "--help", "-h", "version"];
    TOOLS.contains(tool) && FLAGS.contains(flag)
}

/// Build the contract-derivation prompt. `issues` carries repair feedback from
/// a prior failed attempt (car-builder pattern).
fn build_contract_prompt(intent: &str, repo_summary: &str, issues: &[String]) -> String {
    let mut p = format!(
        "You are deriving an OUTCOME CONTRACT for a coding task: a small set of shell \
         commands that objectively verify the task is done. The commands run at the root of a \
         fresh git checkout of the repository, non-interactively, with no TTY.\n\n\
         Task intent:\n{intent}\n\n\
         Repository summary:\n{repo_summary}\n\n\
         Respond with ONLY a JSON object, no prose, no markdown fences, in this shape:\n\
         {{\n  \"description\": \"one-sentence definition of done\",\n  \"checks\": [\n    \
         {{\"name\": \"unique_snake_case_label\", \"command\": \"shell command\", \
         \"expect_exit_zero\": true, \"output_contains\": null, \"timeout_secs\": 120}}\n  ]\n}}\n\n\
         Rules:\n\
         - Commands run at the repository root ALREADY (the runtime sets the working \
           directory). Do NOT prefix a command with `cd` into an absolute path, and do NOT \
           assume a specific mount like `/repo`, `/workspace`, or `/app` — those paths do not \
           exist here and every such command fails before it runs. Write commands relative to \
           the repo root (e.g. `python -m pytest tests/test_x.py`, not `cd /repo && python …`).\n\
           A RELATIVE `cd` is different and is often REQUIRED: when the repository \
           summary places a build system in a subdirectory, run its commands from there \
           (e.g. `cd car-rs && cargo test -p some-crate`). The prohibition is on absolute \
           paths and invented mounts, not on `cd` itself.\n\
           Do NOT pipe a check into `tail`/`head`/`cat` to shorten output: a pipeline exits with \
           the LAST command's status, so `pytest … | tail -20` always exits 0 and the check can \
           never fail. The runtime captures full output itself.\n\
         - `timeout_secs` must fit the command on a COLD checkout, where nothing is \
           cached. 120 (the shape example above) suits a fast script or a single unit \
           test. A compiled-language build or test suite — cargo, go, gradle, swift, \
           cmake — routinely needs 900–3000. A check killed at its timeout is reported \
           as a FAILURE, so an under-sized timeout makes the contract permanently red no \
           matter what the code does; a check that finishes early costs nothing. Size it \
           generously.\n\
         - 1 to 5 checks. Each must verify THE TASK ITSELF, not just that the toolchain works \
           (e.g. `rustc --version` or `cargo --version` prove nothing about the change).\n\
         - At least one check should exercise the actual new behaviour the intent describes \
           (run the program/test that the change affects).\n\
         - For a \"make the failing tests pass\" task, verify by running the failing test's \
           own FILE (e.g. `python -m pytest tests/test_x.py`), NOT a bespoke reproduction \
           snippet and NOT a narrow `-k` filter — a hand-written snippet or a guessed filter \
           routinely passes while the real failing test is untouched, so the session reports \
           done on an incomplete fix. If specific failing tests are listed below, name them \
           explicitly. Do NOT run the whole suite (`pytest tests/`): it may contain unrelated \
           pre-existing failures that your change is not responsible for.\n\
         - `name` must be a real, descriptive snake_case label unique within the contract — \
           never the literal placeholder `unique_snake_case_label`.\n\
         - Every command must run non-interactively and deterministically (no prompts, no \
           watchers, no servers that don't exit). Use the repo's own build/test commands when \
           the summary reveals them — a build that must compile the change is a strong check.\n\
         - `expect_exit_zero: true` (the default) is usually enough. Only set `output_contains` \
           to a substring you are CERTAIN will appear verbatim in stdout/stderr; if unsure, \
           leave it null. Do NOT invent example output or placeholder values.\n\
         - Never use git push, network access, sudo, or anything destructive outside the \
           checkout. Timeouts are in seconds; keep them realistic for a build.\n"
    );
    if !issues.is_empty() {
        p.push_str("\nYour previous attempt FAILED validation with these issues — fix them:\n");
        for i in issues {
            p.push_str(&format!("- {i}\n"));
        }
    }
    p
}

/// Extract the first JSON object from model output, tolerating code fences and
/// surrounding prose.
pub(crate) fn extract_json_object(text: &str) -> Result<Value, String> {
    let start = text.find('{').ok_or("no JSON object found in output")?;
    let end = text.rfind('}').ok_or("no closing brace found in output")?;
    if end < start {
        return Err("malformed JSON object in output".to_string());
    }
    serde_json::from_str(&text[start..=end]).map_err(|e| format!("invalid JSON: {e}"))
}

/// Whether the intent is a "the tests fail, make them pass" task — the case
/// where the contract must be grounded in the *actually failing* tests rather
/// than guessed. Deliberately narrow: the observe-then-derive path runs the test
/// suite, so it only fires when the intent clearly asks for it.
pub fn intent_targets_tests(intent: &str) -> bool {
    let i = intent.to_ascii_lowercase();
    let mentions_tests = i.contains("test");
    let mentions_failure = [
        "fail",
        "failing",
        "broken",
        "passing",
        "pass the",
        "make the tests",
    ]
    .iter()
    .any(|k| i.contains(k));
    mentions_tests && mentions_failure
}

/// Parse pytest's short-summary `FAILED` lines into node ids
/// (`tests/test_x.py::test_name`). Best-effort and format-tolerant: the line is
/// `FAILED <node id> - <reason>`, so the second whitespace token is the id.
/// Deduplicated, order-preserving. Anything unrecognized yields nothing — the
/// caller treats an empty result as "learned nothing", not "no failures".
///
/// **`ERROR` lines are deliberately excluded.** A pytest `ERROR` is a collection/
/// setup failure — the module couldn't even be imported (a stdlib API removed in
/// a newer Python, a missing dep, an unsupported kwarg) — which is *environment
/// drift*, never the behavioural bug the intent describes, and never what the
/// task's own contract targets (the extractor scopes to tests that flip
/// fail→pass under the fix, i.e. `FAILED`s). Grounding on an `ERROR` would import
/// an unfixable check into the coder's self-contract and burn its whole budget
/// on drift it can't resolve (the #7 false-negative). Verified live: grounding on
/// all failures pulled `test_instance_config.py`'s `pkgutil.get_loader` collection
/// error (gone in 3.14) into the contract; `FAILED`-only drops it and keeps the
/// real `AssertionError` bug.
pub fn parse_test_failures(output: &str) -> Vec<String> {
    let mut seen = std::collections::HashSet::new();
    let mut ids = Vec::new();
    for line in output.lines() {
        let Some(rest) = line.trim().strip_prefix("FAILED ") else {
            continue;
        };
        let id = rest.split_whitespace().next().unwrap_or("").trim();
        if id.is_empty() || !id.contains(".py") {
            continue;
        }
        if seen.insert(id.to_string()) {
            ids.push(id.to_string());
        }
    }
    ids
}

/// Fold observed failing tests into the repo summary handed to derivation, so
/// the model's contract is grounded in what actually fails instead of guessed.
/// Empty input returns the summary unchanged.
pub fn summary_with_failures(repo_summary: &str, failing: &[String]) -> String {
    if failing.is_empty() {
        return repo_summary.to_string();
    }
    let list = failing
        .iter()
        .map(|f| format!("  - {f}"))
        .collect::<Vec<_>>()
        .join("\n");
    format!(
        "{repo_summary}\n\nObserved failing tests (the suite was run before you; these node \
         ids currently FAIL). Your contract MUST verify that the ones your change addresses \
         now pass — run them by their exact node id or their file:\n{list}"
    )
}

/// What one derivation attempt asks of the injected generator: the prompt, plus
/// whether this attempt must be routed to a DIFFERENT model than the last one.
///
/// Derivation is the one place in the coder that needs a raw JSON object back
/// and parses it strictly. Routing does not know that, so when the preferred
/// lane is down the adaptive arm can fall back to a capable code model that
/// reliably wraps or truncates the object — and the repair loop then re-sends
/// the repair prompt through the same routing, landing on the same ill-suited
/// model all three attempts (Parslee-ai/car#889).
pub struct ContractDraftRequest {
    /// The derivation (or repair) prompt for this attempt.
    pub prompt: String,
    /// True when the PREVIOUS attempt returned text derivation could not use as
    /// JSON at all. The generator must route this attempt AWAY from the model it
    /// used last: a repair prompt cannot fix a model that will not hold strict
    /// JSON, and re-asking it just burns the budget (Parslee-ai/car#889).
    pub rotate_model: bool,
}

/// Derive a contract from `intent` via the injected `generate` closure, with a
/// bounded validate→repair loop.
///
/// `constraints` are rules the operator stated elsewhere — today, agreed in a
/// `coder.discuss` conversation and carried through `coder.start
/// { discussion_id }`. They are already spliced into `repo_summary` for the
/// drafting model, but a prompt is a request, not a guarantee: measured 1
/// success in 3 trials, the model simply dropped them. So each is **verified**
/// against the finished draft here, inside the existing attempt budget, and a
/// miss re-prompts naming the ungated constraint verbatim. Pass `&[]` when
/// there are none and this costs nothing.
///
/// "Verified" means **gated by a check** — see [`ungated_constraints`]. A
/// constraint that reached only the `description` is treated exactly like one
/// that was dropped: it drives the repair loop, and if the budget runs out it
/// is named in the `NOT VERIFIED BY THIS CONTRACT` disclosure. Reaching the
/// description is not reaching the contract; the loop can self-verify green
/// against prose.
pub async fn derive_contract<F, Fut>(
    generate: F,
    intent: &str,
    repo_summary: &str,
    max_attempts: u32,
    constraints: &[String],
) -> Result<OutcomeContract, String>
where
    F: Fn(ContractDraftRequest) -> Fut + Send + Sync,
    Fut: Future<Output = Result<String, String>> + Send,
{
    let max = max_attempts.max(1);
    let mut issues: Vec<String> = Vec::new();
    let mut last_err = String::new();
    // Set only by the JSON-shape failures below, and cleared as soon as an
    // attempt's output parses — one bad reply must not pin rotation on for the
    // rest of the budget.
    let mut rotate_model = false;
    // The best draft seen so far that was structurally valid but still dropped
    // a constraint. If the budget runs out we return it with the gap stated
    // rather than nothing — a contract that gates most of the task beats no
    // session at all, provided the operator is told what is not covered.
    let mut best_incomplete: Option<(OutcomeContract, Vec<UngatedConstraint>)> = None;

    for _ in 0..max {
        let prompt = build_contract_prompt(intent, repo_summary, &issues);
        let request = ContractDraftRequest {
            prompt,
            rotate_model,
        };
        let text = match tokio::time::timeout(CONTRACT_GEN_TIMEOUT, generate(request)).await {
            Ok(Ok(t)) => t,
            Ok(Err(e)) => {
                // Transient model/transport failure — retry with the same prompt.
                // Deliberately does NOT set rotation: the model produced no text
                // to judge, so there is nothing to hold against it, and the
                // fallback the router already performs is the right response.
                last_err = format!("generation failed: {e}");
                continue;
            }
            Err(_) => {
                // Hung backend — bound it instead of blocking forever (PAR-7170).
                // No rotation here either: a model that never answered told us
                // nothing about whether it can hold JSON, and the retry
                // behaviour below is deliberate.
                //
                // Don't blame "no model available": the overwhelmingly common
                // cause is the opposite — a model WAS selected, and it was one
                // that had to be downloaded first, so the fetch ate the whole
                // budget (Parslee-ai/car#638). The old wording sent users to
                // `car models list`, which cheerfully showed the model as
                // available, and told them nothing.
                last_err = format!(
                    "contract generation timed out after {}s. The selected model may still \
                     be downloading — a first-use fetch can far exceed this budget. Check \
                     `car models list` for what is actually on disk, pre-pull with \
                     `car models pull <id>`, or sign in for a cloud model that needs no \
                     download.",
                    CONTRACT_GEN_TIMEOUT.as_secs()
                );
                continue;
            }
        };
        let value = match extract_json_object(&text) {
            Ok(v) => v,
            Err(e) => {
                // The model answered with something that is not the JSON object
                // at all (prose, a truncated object, an unclosed fence). That is
                // a property of the MODEL, not of this prompt — asking the same
                // one to "return ONLY the JSON object" is what burned all three
                // attempts on a fallback lane and killed sessions at zero
                // iterations (Parslee-ai/car#889). Route the next attempt away
                // from it and let the repair prompt do its work on a model that
                // can hold the shape.
                rotate_model = true;
                issues = vec![format!(
                    "output did not parse: {e}. Return ONLY the JSON object."
                )];
                last_err = issues.join("; ");
                continue;
            }
        };
        let mut contract: OutcomeContract = match serde_json::from_value(value) {
            Ok(c) => c,
            Err(e) => {
                // Valid JSON, wrong object — the model did not honour the schema
                // it was handed verbatim. Same judgement as above: this is the
                // model failing to follow a structural instruction, so rotate
                // rather than re-ask.
                rotate_model = true;
                issues = vec![format!("JSON did not match the contract schema: {e}")];
                last_err = issues.join("; ");
                continue;
            }
        };
        // The output parsed, so whatever model produced it CAN hold the shape.
        // Clear rotation: from here on the loop is arguing about substance, and
        // substance is what the repair prompt is good at.
        rotate_model = false;
        // Fix cosmetic naming slips (placeholder/empty/duplicate labels) in place
        // rather than burning a repair attempt — and potentially the whole
        // session — on them. Substance problems still fall through to validate().
        contract.repair_cosmetic_names();
        // Drop any hallucinated `cd /repo && …` prefix the derivation model added:
        // checks run at the worktree root, and a nonexistent absolute cd fails
        // every check, self-failing a correctly-solved task.
        contract.strip_absolute_cd_prefixes();
        // A `… | tail -20` makes the check exit 0 unconditionally — the coder
        // would then self-verify green on broken code. Drop the mask.
        contract.strip_exit_masking_pipes();
        let problems = contract.validate();
        if !problems.is_empty() {
            last_err = problems.join("; ");
            issues = problems;
            continue;
        }
        // Structurally sound. Now: is each constraint actually GATED by a
        // check — not merely mentioned in the prose?
        let ungated = ungated_constraints(&generate, &contract, constraints).await;
        if ungated.is_empty() {
            return Ok(contract);
        }
        // Keep the BEST draft seen, not the newest: attempt 1 can express two
        // of three constraints and attempt 2 only the third, and returning the
        // newest then hands back the weaker contract of the two.
        if best_incomplete
            .as_ref()
            .is_none_or(|(_, prior)| ungated.len() < prior.len())
        {
            best_incomplete = Some((contract, ungated.clone()));
        }
        // Re-prompt naming exactly what is not gated — a blind redraw would be
        // as likely to drop it again — and say which of the two failures it is,
        // because "you never mentioned it" and "you mentioned it but nothing
        // checks it" need different fixes.
        issues = ungated
            .iter()
            .map(|c| match c.coverage {
                Coverage::Absent => format!(
                    "you DROPPED this constraint, which the operator agreed and which is not \
                     optional: \"{}\". Express it as a CHECK whose command actually verifies \
                     it. Keep every check you already had.",
                    c.text
                ),
                Coverage::ProseOnly => format!(
                    "this constraint appears only in `description`, where NOTHING VERIFIES \
                     IT: \"{}\". A contract's force is its checks — prose gates nothing. Add \
                     a check whose command fails when the constraint is violated (a grep, a \
                     test, a diff), and keep every check you already had.",
                    c.text
                ),
            })
            .collect();
        last_err = format!(
            "ungated constraint(s): {}",
            ungated
                .iter()
                .map(|c| c.text.as_str())
                .collect::<Vec<_>>()
                .join("; ")
        );
    }
    // Budget spent. A valid draft that leaves a constraint ungated is worth
    // more than an error, but the operator must never be left believing a
    // constraint was captured when it was not — so it goes in the description,
    // which is what the confirmation gate and the merge commit both show.
    //
    // This fires for prose-only capture too, and that is the point: a
    // constraint restated in `description` with no check behind it is exactly
    // as ungated as one that was dropped, and the operator cannot tell the two
    // apart by reading. The judge used to accept "stated in the description" as
    // satisfaction, so this disclosure never fired for the case that most looks
    // like success.
    if let Some((mut contract, ungated)) = best_incomplete {
        contract.description = format!(
            "{}\n\nNOT VERIFIED BY THIS CONTRACT — these constraints from the discussion are \
             not gated by any check here, so nothing enforces them (a mention above is not a \
             check); review them by hand before approving:\n{}",
            contract.description.trim_end(),
            ungated
                .iter()
                .map(|c| format!("  - {}", c.text))
                .collect::<Vec<_>>()
                .join("\n")
        );
        return Ok(contract);
    }
    Err(format!(
        "could not derive a valid outcome contract after {max} attempts: {last_err}"
    ))
}

/// How a constraint failed to be gated by the drafted contract.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Coverage {
    /// Not in the contract at all.
    Absent,
    /// Stated in `description`, but no check verifies it. As ungated as
    /// [`Absent`](Coverage::Absent) — and far more likely to be mistaken for
    /// success, by the model that wrote it and by the operator reading it.
    ProseOnly,
}

/// One constraint the drafted contract does not gate, and why.
#[derive(Debug, Clone)]
struct UngatedConstraint {
    text: String,
    coverage: Coverage,
}

/// Which of `constraints` the drafted contract does not GATE — i.e. which have
/// no check that would fail if they were violated.
///
/// The distinction this draws is the whole point. The judge used to accept a
/// constraint as satisfied when it was "stated in the description", and the
/// repair prompt offered that as an explicit escape hatch — so the model's
/// cheapest way out was to append a sentence to `description`, the judge
/// returned nothing missing, and derivation returned `Ok` with **no
/// disclosure**. A contract's force is its checks: prose in the description
/// gates nothing, so a constraint that reached only the description has not
/// reached the contract in any sense the loop or the merge gate can act on.
/// Two identical end-states were being reported differently depending on which
/// code path produced them; now both drive the repair loop, and both fire the
/// `NOT VERIFIED BY THIS CONTRACT` disclosure if the budget runs out.
///
/// Judging "does this check verify that rule" is itself model work, so it runs
/// through the same injected generation path the draft did — no second seam to
/// keep in sync, and tests script it like everything else. Fails OPEN: any
/// transport, timeout, or parse problem yields "nothing ungated" rather than
/// burning the caller's attempt budget on the judge's flakiness. That is the
/// safe direction — the worst case is the pre-existing behaviour.
async fn ungated_constraints<F, Fut>(
    generate: &F,
    contract: &OutcomeContract,
    constraints: &[String],
) -> Vec<UngatedConstraint>
where
    F: Fn(ContractDraftRequest) -> Fut + Send + Sync,
    Fut: Future<Output = Result<String, String>> + Send,
{
    if constraints.is_empty() {
        return Vec::new();
    }
    let rendered = constraints
        .iter()
        .enumerate()
        .map(|(i, c)| format!("{}. {c}", i + 1))
        .collect::<Vec<_>>()
        .join("\n");
    let contract_json = serde_json::to_string_pretty(contract).unwrap_or_default();
    let prompt = format!(
        "A verifiable outcome contract was drafted for a coding task. The operator agreed \
         these constraints beforehand. A constraint counts as SATISFIED only when some \
         check's `command` would actually FAIL if the constraint were violated. Being \
         mentioned in `description` does NOT count — the description is prose and runs \
         nothing.\n\n\
         CONSTRAINTS\n{rendered}\n\n\
         CONTRACT\n{contract_json}\n\n\
         Return ONLY a JSON object with the 1-based numbers of the constraints that are NOT \
         satisfied, split by which failure it is:\n\
         {{\"missing\": [1], \"prose_only\": [2]}}\n\n\
         - `missing`: the constraint appears nowhere in the contract.\n\
         - `prose_only`: the constraint is stated in `description` (or a check NAME) but no \
         check command verifies it.\n\n\
         Return both arrays empty if every constraint is verified by a check. Judge \
         substance, not wording — a check that genuinely verifies the constraint counts even \
         if it uses completely different words. Judge the COMMAND, never the name."
    );
    // Never rotates: the judge only runs once a draft has already parsed, and it
    // fails open anyway — routing it away from a working model would buy nothing.
    let request = ContractDraftRequest {
        prompt,
        rotate_model: false,
    };
    let text = match tokio::time::timeout(CONTRACT_GEN_TIMEOUT, generate(request)).await {
        Ok(Ok(t)) => t,
        _ => return Vec::new(),
    };
    let Ok(value) = extract_json_object(&text) else {
        return Vec::new();
    };
    let indices = |field: &str| -> Vec<usize> {
        value
            .get(field)
            .and_then(Value::as_array)
            .map(|a| {
                a.iter()
                    .filter_map(Value::as_u64)
                    .filter(|n| *n >= 1 && (*n as usize) <= constraints.len())
                    .map(|n| n as usize - 1)
                    .collect()
            })
            .unwrap_or_default()
    };
    let absent = indices("missing");
    let prose_only = indices("prose_only");
    // Report in constraint order, and let `missing` win a duplicate: a judge
    // that lists the same constraint twice is telling us the harsher of the two.
    (0..constraints.len())
        .filter_map(|i| {
            let coverage = if absent.contains(&i) {
                Coverage::Absent
            } else if prose_only.contains(&i) {
                Coverage::ProseOnly
            } else {
                return None;
            };
            Some(UngatedConstraint {
                text: constraints[i].clone(),
                coverage,
            })
        })
        .collect()
}

pub(crate) fn check_assertions(
    check: &ContractCheck,
    exit_code: Option<i64>,
    output: &str,
    timed_out: bool,
) -> bool {
    let exit_ok = !check.expect_exit_zero || exit_code == Some(0);
    let output_ok = check
        .output_contains
        .as_deref()
        .map(|assertion| output_assertion_passes(assertion, output))
        .unwrap_or(true);
    exit_ok && output_ok && !timed_out
}

fn output_assertion_passes(assertion: &str, output: &str) -> bool {
    let Some(expression) = assertion.strip_prefix("$json:") else {
        return output.contains(assertion);
    };
    let Some((pointer, expected)) = expression.split_once('=') else {
        return false;
    };
    let Ok(expected) = serde_json::from_str::<Value>(expected) else {
        return false;
    };
    serde_json::from_str::<Value>(output.trim())
        .ok()
        .and_then(|value| value.pointer(pointer).cloned())
        .is_some_and(|actual| actual == expected)
}

/// A short, quoted preview of an output for a failure message — enough to see
/// what was compared, never the whole capture.
fn preview(s: &str) -> String {
    const CAP: usize = 120;
    let trimmed = s.trim();
    if trimmed.len() <= CAP {
        format!("{trimmed:?}")
    } else {
        let cut = trimmed
            .char_indices()
            .take_while(|(i, _)| *i < CAP)
            .last()
            .map(|(i, c)| i + c.len_utf8())
            .unwrap_or(0);
        format!("{:?}…", &trimmed[..cut])
    }
}

/// The first numeric token in an output, for [`DifferentialExpect::DeltaWithin`].
///
/// Tokens are whitespace-split; each is stripped of surrounding punctuation and
/// of thousands-separator commas (`435,594` → `435594`) before the parse, so a
/// counter embedded in prose (`"orphaned rows: 435,594"`) is still found. First
/// match wins — keep a capture command's output down to the one number that
/// matters.
fn first_number(s: &str) -> Option<f64> {
    for token in s.split_whitespace() {
        let cleaned: String = token
            .trim_matches(|c: char| !c.is_ascii_digit() && c != '-' && c != '+' && c != '.')
            .replace(',', "");
        if cleaned.is_empty() {
            continue;
        }
        if let Ok(n) = cleaned.parse::<f64>() {
            return Some(n);
        }
    }
    None
}

/// Decide one differential claim: `after_output` against the named capture.
/// `Err` is the failure message that lands in the check's `output_tail`, so it
/// has to say what was compared and how it missed — it is what the repair
/// prompt and the operator read.
fn evaluate_differential(
    diff: &DifferentialCheck,
    baselines: &BaselineCaptures,
    after_output: &str,
) -> Result<(), String> {
    let Some(capture) = baselines.get(&diff.baseline) else {
        return Err(format!(
            "baseline '{}' was never captured — baseline checks run once at session start, and \
             no capture by that name reached this evaluation",
            diff.baseline
        ));
    };
    if !capture.passed {
        return Err(format!(
            "baseline '{}' failed at capture time (exit code {:?}), so there is no trustworthy \
             before-value to compare against",
            diff.baseline, capture.exit_code
        ));
    }
    // Both sides compared at the same 4 KiB tail the capture was stored at.
    let before = capture.output_tail.trim().to_string();
    let after_tail = super::shell_tool::tail(after_output, 4 * 1024);
    let after = after_tail.trim();

    // Exhaustive — a new differential kind must decide its semantics here.
    match &diff.expect {
        DifferentialExpect::Changed => {
            if before == after {
                Err(format!(
                    "expected the output to CHANGE from baseline '{}', but it is identical to \
                     the captured value ({})",
                    diff.baseline,
                    preview(&before)
                ))
            } else {
                Ok(())
            }
        }
        DifferentialExpect::Unchanged => {
            if before == after {
                Ok(())
            } else {
                Err(format!(
                    "expected the output to be UNCHANGED from baseline '{}' (the control-group \
                     claim), but it moved: baseline {} vs current {}",
                    diff.baseline,
                    preview(&before),
                    preview(after)
                ))
            }
        }
        DifferentialExpect::DeltaWithin { min, max } => {
            let b = first_number(&before).ok_or_else(|| {
                format!(
                    "baseline '{}' captured no numeric value to diff against: {}",
                    diff.baseline,
                    preview(&before)
                )
            })?;
            let a = first_number(after).ok_or_else(|| {
                format!(
                    "the check output carries no numeric value to diff: {}",
                    preview(after)
                )
            })?;
            let delta = a - b;
            let lo_ok = min.is_none_or(|m| delta >= m);
            let hi_ok = max.is_none_or(|m| delta <= m);
            if lo_ok && hi_ok {
                Ok(())
            } else {
                Err(format!(
                    "delta {delta} from baseline '{}' ({b} -> {a}) is outside the allowed \
                     bounds [{}, {}]",
                    diff.baseline,
                    min.map_or("-inf".to_string(), |m| m.to_string()),
                    max.map_or("+inf".to_string(), |m| m.to_string()),
                ))
            }
        }
    }
}

/// Run one check through the worktree shell tool. The shared core of
/// [`evaluate_contract`] and [`evaluate_contract_baseline`], which differ only
/// in whether they narrate. `baselines` supplies the before-values any
/// differential on this check compares against.
async fn run_check(
    check: &ContractCheck,
    executor: &WorktreeExecutor,
    deadline: Option<&SessionDeadline>,
    baselines: &BaselineCaptures,
) -> CheckResult {
    let started = std::time::Instant::now();
    let remaining = deadline.and_then(SessionDeadline::remaining_secs);
    // Recorded here rather than derived afterwards: once the check has run the
    // session clock has moved on, and `remaining_secs` no longer says what this
    // check was actually given.
    let ceiling = executor.check_timeout_ceiling();
    let clamped = deadline_set_the_timeout(check.timeout_secs, remaining, ceiling);
    let timeout = effective_check_timeout(check.timeout_secs, remaining, ceiling);
    let outcome = executor
        .run_check_shell(&check.command, Some(timeout))
        .await;
    let duration_ms = started.elapsed().as_millis() as u64;

    match outcome {
        Ok(v) => {
            let exit_code = v.get("exit_code").and_then(Value::as_i64);
            let output = v.get("output").and_then(Value::as_str).unwrap_or_default();
            let timed_out = v.get("timed_out").and_then(Value::as_bool).unwrap_or(false);
            let mut passed = check_assertions(check, exit_code, output, timed_out);
            let mut output_tail = super::shell_tool::tail(output, 4 * 1024);
            // The differential is decided only when the point-in-time
            // assertions held: a nonzero exit already fails the check, and its
            // output is not a measurement worth diffing.
            if passed {
                if let Some(diff) = &check.differential {
                    if let Err(msg) = evaluate_differential(diff, baselines, output) {
                        passed = false;
                        output_tail = format!("{output_tail}\n[differential] {msg}")
                            .trim_start()
                            .to_string();
                    }
                }
            }
            CheckResult {
                name: check.name.clone(),
                // Unchanged: a starved check is still not a pass. The two
                // fields below say WHY it is not, which is a different
                // question and the one a scorer needs answered.
                passed,
                exit_code,
                output_tail,
                duration_ms,
                timed_out,
                deadline_clamped: clamped,
            }
        }
        Err(e) => CheckResult {
            name: check.name.clone(),
            passed: false,
            exit_code: None,
            output_tail: format!("check failed to run: {e}"),
            duration_ms,
            // A spawn/policy failure is a verdict the runtime reached itself;
            // nothing was killed by a clock.
            timed_out: false,
            deadline_clamped: clamped,
        },
    }
}

/// Run every check through the worktree shell tool and report results.
///
/// All checks run even after a failure — repair prompts and the UI want the
/// full picture, and checks are independent by construction.
pub async fn evaluate_contract(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
    sink: &EventSink,
) -> Vec<CheckResult> {
    evaluate_contract_within(contract, executor, sink, None).await
}

/// [`evaluate_contract`], with the session-start baseline captures that
/// differential checks compare against. Callers that hold captures (the coder
/// loops) use this; the capture-less signatures delegate here with an empty
/// map, under which a differential check FAILS with a "never captured"
/// message rather than silently passing — fail closed, never open.
pub async fn evaluate_contract_with_baselines(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
    sink: &EventSink,
    baselines: &BaselineCaptures,
) -> Vec<CheckResult> {
    evaluate_contract_within_baselines(contract, executor, sink, None, baselines).await
}

/// The timeout one check may take: its own, never more than the session has
/// left on the wall clock.
///
/// `None` means the caller keeps no session clock and the check's own timeout
/// stands. `Some(0)` means the budget is spent; `run_shell` clamps a timeout up
/// to at least 1s, so such a check gets one second and reports a timeout rather
/// than running to completion outside a budget that is already gone. That is
/// the honest answer — a run declared as ten minutes should say it ran out, not
/// quietly take three hours.
///
/// The 1s floor is deliberate, and so is NOT short-circuiting a spent budget
/// into "skip every check". A cheap check (`test -f target/x`) finishes inside
/// that second and still passes, so a run whose budget expired between the
/// loop's last green iteration and the runtime's own gate can still deliver its
/// pull request; skipping would forfeit deliverable runs to save one second.
/// What the floor costs instead is legibility, and
/// [`CheckResult::starved_by_deadline`] is what pays that back — a check killed
/// at a clamped timeout is marked as such, so a caller can tell "the run was
/// out of time" from "the work is red".
pub fn clamp_check_timeout(check_timeout_secs: u64, remaining_secs: Option<u64>) -> u64 {
    match remaining_secs {
        None => check_timeout_secs,
        Some(remaining) => check_timeout_secs.min(remaining),
    }
}

/// Was the timeout this check was killed at set by the SESSION clock, or by the
/// check's own ceiling?
///
/// The comparison has to be against the **effective** ceiling, not the declared
/// one, and that is the whole content of this function. Every command the
/// contract runs goes through
/// [`run_check_shell`](super::shell_tool::WorktreeExecutor::run_check_shell),
/// which clamps to the executor's
/// [`check_timeout_ceiling`](super::shell_tool::WorktreeExecutor::check_timeout_ceiling)
/// — [`MAX_SHELL_TIMEOUT_SECS`](super::shell_tool::MAX_SHELL_TIMEOUT_SECS), 600s,
/// unless the operator raised it — so at the default a check declaring
/// `timeout_secs: 900` (the workspace-suite example in [`clamp_check_timeout`]'s
/// own doc above, and `timeout_secs` carries no validation cap) is killed at
/// 600s regardless of what the session has left.
///
/// Comparing against the declared 900 marked the whole `600 < remaining < 900`
/// window as deadline-clamped. A genuine 600s hang in that window then reported
/// [`CheckResult::starved_by_deadline`], and `car code-task` booked it as
/// `session_wall_exhausted` — a class the orchestrator doc tells callers not to
/// score. That is precisely the laundering the two-bit encoding exists to
/// prevent: a hang is a defect, not a budget excuse.
///
/// Walk the three cases with `timeout_secs: 900` at the default `ceiling: 600`:
/// `remaining: 500` → killed at 500 by the session → true. `remaining: 700` →
/// killed at 600 by the shell ceiling, with 100s of session budget to spare →
/// false. `remaining: 3600` → false. Raise the ceiling to 900 and the middle
/// case flips to true, which is the point: the check was allowed its full 900s
/// and only the session clock cut it short (car#1065).
pub(crate) fn deadline_set_the_timeout(
    check_timeout_secs: u64,
    remaining_secs: Option<u64>,
    ceiling_secs: u64,
) -> bool {
    remaining_secs.is_some_and(|r| r < effective_check_ceiling(check_timeout_secs, ceiling_secs))
}

/// The ceiling one check actually runs under: its own declared `timeout_secs`,
/// capped by the executor's contract-check ceiling.
///
/// Pulled out as a pure function so the raised-ceiling path is unit-testable
/// without sitting through a real ten-minute command.
pub(crate) fn effective_check_ceiling(check_timeout_secs: u64, ceiling_secs: u64) -> u64 {
    check_timeout_secs.min(ceiling_secs)
}

/// The number of seconds the check's process is actually given: the whole clamp
/// in one place — [`clamp_check_timeout`] against the session's remaining
/// budget, then the executor's contract-check ceiling with the shell's own 1s
/// floor.
///
/// `run_check_shell` applies the same ceiling again on the way to the process,
/// so this is not the enforcement point; stating the composed arithmetic here
/// is what makes the raised-ceiling path checkable in a unit test instead of
/// only observable by sitting through a real ten-minute command.
pub(crate) fn effective_check_timeout(
    check_timeout_secs: u64,
    remaining_secs: Option<u64>,
    ceiling_secs: u64,
) -> u64 {
    clamp_check_timeout(check_timeout_secs, remaining_secs).clamp(1, ceiling_secs.max(1))
}

/// [`evaluate_contract`], bounded by a session deadline.
///
/// `--max-session-wall-secs` used to bound only the LOOP. The baseline run and
/// the runtime's own gate sat outside it, so total process wall time was
/// `baseline + wall_secs + gate`, where the first and third terms were bounded
/// only by the sum of the per-check `timeout_secs` a `--contract-file` supplies
/// — with no cap on check count. Six checks at `timeout_secs: 900` (a
/// workspace-wide suite is not an exotic contract) could burn 90 minutes before
/// the clock even started and another 90 after it stopped: roughly three hours
/// for a run an orchestrator declared as ten minutes, and the orchestrator has
/// no way to see it coming.
///
/// The deadline is consulted PER CHECK rather than once per evaluation, and
/// that is what makes the bound real: a single snapshot clamp would give every
/// one of six checks the same remaining budget and cap the total at six times
/// it. Reading it as each check starts means the budget genuinely shrinks.
///
/// This does not interrupt a check already running — see [`super::budget`] on
/// why mid-flight interruption is deliberately not how this works. It bounds
/// what a check is ALLOWED to take, which is the part a caller can promise.
pub async fn evaluate_contract_within(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
    sink: &EventSink,
    deadline: Option<&SessionDeadline>,
) -> Vec<CheckResult> {
    // Empty captures: a differential check under this signature fails with a
    // "never captured" message. Callers that hold the session's captures use
    // the `_baselines` variant.
    evaluate_contract_within_baselines(contract, executor, sink, deadline, &BaselineCaptures::new())
        .await
}

/// [`evaluate_contract_within`], with baseline captures.
///
/// A [`ContractCheck::baseline`] capture check is NOT re-run here: it already
/// ran at session start, and re-capturing "before" after the work would
/// destroy the comparison. Its capture-time result is carried into the results
/// (and narrated like any check), so a failed capture keeps the gate red
/// instead of vanishing, and both executions of a before/after pair are
/// visible in the session's events.
pub async fn evaluate_contract_within_baselines(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
    sink: &EventSink,
    deadline: Option<&SessionDeadline>,
    baselines: &BaselineCaptures,
) -> Vec<CheckResult> {
    let mut results = Vec::with_capacity(contract.checks.len());
    for check in &contract.checks {
        sink.emit(CoderEventKind::CheckStarted {
            name: check.name.clone(),
        });
        let result = if check.baseline {
            baselines.get(&check.name).cloned().unwrap_or(CheckResult {
                name: check.name.clone(),
                passed: false,
                exit_code: None,
                output_tail: "baseline check was never captured — the runtime runs baseline \
                              checks once at session start, and no capture reached this \
                              evaluation"
                    .to_string(),
                duration_ms: 0,
                timed_out: false,
                deadline_clamped: false,
            })
        } else {
            run_check(check, executor, deadline, baselines).await
        };
        sink.emit(CoderEventKind::CheckCompleted {
            result: result.clone(),
        });
        results.push(result);
    }
    results
}

/// Evaluate the contract against the **unmodified** worktree, before the first
/// edit — the red-green baseline.
///
/// [`OutcomeContract::validate`] already rejects contracts that gate nothing for
/// *structural* reasons (assertion-less checks, toolchain-only no-ops, empty
/// commands). What it cannot see is semantic vacuity: a check that is
/// well-formed, task-specific, and **already passing before any code is
/// written**. Such a check clears validation, becomes the session's trust
/// boundary, and then reports done for a session that changed nothing relevant.
/// Running the contract once up front is what makes that distinguishable:
///
/// * a check that **fails** here is verifying something the change must fix;
/// * a check that **passes** here is not gating this task.
///
/// Deliberately silent — no `CheckStarted`/`CheckCompleted`. Those events mean
/// "the contract is being evaluated on the work", and a UI replaying them for a
/// baseline run would show checks going green before a line was written, which
/// is precisely the confusion this exists to remove. The results are surfaced as
/// baseline instead, on the confirmation the user already sees.
pub async fn evaluate_contract_baseline(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
) -> Vec<CheckResult> {
    evaluate_contract_baseline_within(contract, executor, None).await
}

/// [`evaluate_contract_baseline`], bounded by a session deadline. See
/// [`evaluate_contract_within`] for why the baseline needs one at all.
pub async fn evaluate_contract_baseline_within(
    contract: &OutcomeContract,
    executor: &WorktreeExecutor,
    deadline: Option<&SessionDeadline>,
) -> Vec<CheckResult> {
    let mut results = Vec::with_capacity(contract.checks.len());
    // This pass IS the capture pass: a `baseline: true` check's result is
    // recorded as it lands, in declaration order, so a differential check
    // later in the same pass compares against the value captured moments
    // before. That gives the red-green story its honest baseline reading:
    // `changed` and a decreasing `delta_within` are red here (nothing has
    // changed yet), while `unchanged` — the control-group claim — is green
    // here and must STAY green.
    let mut captures = BaselineCaptures::new();
    for check in &contract.checks {
        let result = run_check(check, executor, deadline, &captures).await;
        if check.baseline {
            captures.insert(check.name.clone(), result.clone());
        }
        results.push(result);
    }
    results
}

/// Whether a baseline run means the contract gates nothing at all.
///
/// Only an **all**-green baseline qualifies, and that asymmetry is the load-
/// bearing part. Plenty of legitimate checks pass at baseline: a refactor task
/// ("keep behavior identical, restructure X") *should* have checks green before
/// and after — that is the point of it. So a single passing check is
/// information, not a fault, and escalating on one would reproduce the failure
/// mode `repair_cosmetic_names` exists to avoid: a session aborting before any
/// coding over a contract nit. A contract where *every* check already passes is
/// unambiguous — there is nothing for the session to turn red-to-green.
///
/// Empty is not all-green: a contract with no checks is `validate`'s problem.
pub fn baseline_gates_nothing(results: &[CheckResult]) -> bool {
    !results.is_empty() && results.iter().all(|r| r.passed)
}

/// Checks whose COMMAND could not run at all, by name.
///
/// A check that fails because the code is broken is the point — that is the red
/// half of the red-green baseline. A check that fails because its program does
/// not exist is a different thing wearing the same exit status: the contract
/// can never go green no matter what the session writes, so the run is doomed
/// before the first edit and will spend its whole iteration budget discovering
/// that.
///
/// Found on a live run: derivation produced `python -m pytest ...` on a machine
/// with only `python3`, and twelve iterations of real inference went into a
/// contract that was unsatisfiable from the start. Nothing distinguished it
/// from an ordinary red baseline.
///
/// Exit 127 is the shell's "command not found"; `None` means the runtime could
/// not spawn it at all. Both mean the same to a caller: this check is not a
/// test of anything yet.
pub fn baseline_cannot_run(results: &[CheckResult]) -> Vec<String> {
    results
        .iter()
        .filter(|r| {
            // A timeout is NOT "cannot run". The command exists and started; a
            // clock killed it. Both cases report `exit_code: None`, so without
            // this guard a slow check is reported as a missing program.
            //
            // Two ways that bites, and the second is the common one:
            //
            //   - "fix the hang in X" is a real task whose baseline check
            //     SHOULD time out and SHOULD pass once the hang is fixed.
            //     Refusing it rejects exactly the work the item describes.
            //   - `ContractCheck::timeout_secs` defaults to 120s, which does
            //     not compile a Rust or Swift workspace on a cold checkout.
            //     Measured on this repository:
            //
            //         {"name":"cargo_check_car_server_core","exit_code":null,
            //          "duration_ms":120009,"timed_out":true,
            //          "output_tail":"command timed out after 120s and was killed"}
            //
            //     Reported as "the command does not exist here", that makes an
            //     unattended loop permanently refuse every item in a repo whose
            //     build outruns the default — and the message sends whoever
            //     reads it looking for a missing binary.
            !r.timed_out && !r.passed && (r.exit_code.is_none() || r.exit_code == Some(127))
        })
        .map(|r| r.name.clone())
        .collect()
}

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

    fn result(name: &str, passed: bool, exit_code: Option<i64>) -> CheckResult {
        CheckResult {
            name: name.into(),
            passed,
            exit_code,
            output_tail: String::new(),
            duration_ms: 0,
            timed_out: false,
            deadline_clamped: false,
        }
    }

    /// A check killed by its own clock reports `exit_code: None`, exactly like
    /// a spawn failure — so without an explicit guard the two are the same
    /// value and a slow check is reported as a missing program.
    ///
    /// The measured case, on this repository:
    ///
    /// ```text
    /// {"name":"cargo_check_car_server_core","exit_code":null,
    ///  "duration_ms":120009,"timed_out":true,
    ///  "output_tail":"command timed out after 120s and was killed"}
    /// ```
    ///
    /// `ContractCheck::timeout_secs` defaults to 120s, which does not compile a
    /// Rust workspace cold — so treating this as unrunnable makes the
    /// unattended loop permanently refuse every item in such a repository.
    #[test]
    fn a_timed_out_check_is_not_unrunnable() {
        let mut timed_out = result("slow_build", false, None);
        timed_out.timed_out = true;
        timed_out.duration_ms = 120_009;
        assert!(
            baseline_cannot_run(&[timed_out]).is_empty(),
            "a check killed by a clock is not a missing command"
        );
    }

    /// The guard must key on `timed_out`, not on the absence of an exit code —
    /// a genuine spawn or policy failure still has to be caught.
    #[test]
    fn a_spawn_failure_is_still_unrunnable_alongside_a_timeout() {
        let mut timed_out = result("slow_build", false, None);
        timed_out.timed_out = true;
        assert_eq!(
            baseline_cannot_run(&[timed_out, result("never_spawned", false, None)]),
            vec!["never_spawned".to_string()]
        );
    }

    #[test]
    fn an_ordinary_red_check_is_not_unrunnable() {
        // The red half of the red-green baseline is the POINT. Reporting it as
        // unrunnable would refuse every contract worth having.
        assert!(baseline_cannot_run(&[result("tests", false, Some(1))]).is_empty());
    }

    #[test]
    fn a_missing_command_is_unrunnable() {
        // 127 is the shell's "command not found". This is the case that cost a
        // live trial twelve iterations of real inference against a contract
        // that could not go green.
        assert_eq!(
            baseline_cannot_run(&[result("tests", false, Some(127))]),
            vec!["tests".to_string()]
        );
    }

    #[test]
    fn a_check_that_never_spawned_is_unrunnable() {
        // `None` means the runtime could not start it — a policy refusal or a
        // spawn failure. Same verdict: it is not a test of anything yet.
        assert_eq!(
            baseline_cannot_run(&[result("tests", false, None)]),
            vec!["tests".to_string()]
        );
    }

    #[test]
    fn a_passing_check_is_never_unrunnable() {
        // Belt and braces: a check that PASSED obviously ran, whatever its
        // reported exit code.
        assert!(baseline_cannot_run(&[result("tests", true, Some(127))]).is_empty());
    }
}

#[cfg(test)]
mod tests {

    /// The exact divergence the coder A/B surfaced: derivation guesses which
    /// tests prove doneness, and when the guess is a bespoke snippet or a narrow
    /// filter it can pass while the real failing test is untouched — self-green,
    /// ground-truth-red. These pure helpers ground the guess in the observed
    /// pytest failures instead.
    #[test]
    fn parse_test_failures_pulls_node_ids_from_pytest_summary() {
        let out = "=========================== short test summary info ============================
FAILED tests/test_basic.py::test_session_using_session_settings - AssertionError
FAILED tests/test_reqctx.py::test_environ_for_valid_idna - ValueError: x
ERROR tests/test_instance_config.py::test_installed_package_paths[True] - AttributeError
FAILED tests/test_basic.py::test_session_using_session_settings - AssertionError
1 failed in 0.10s";
        let ids = parse_test_failures(out);
        assert_eq!(
            ids,
            vec![
                "tests/test_basic.py::test_session_using_session_settings".to_string(),
                "tests/test_reqctx.py::test_environ_for_valid_idna".to_string(),
            ],
            "FAILED node ids only, deduped, order-preserved — the ERROR \
             (collection/environment drift) is excluded"
        );
        // A run with no failures learns nothing.
        assert!(parse_test_failures("125 passed in 0.12s").is_empty());
        // A bare non-file token is not a node id.
        assert!(parse_test_failures("FAILED something-weird - boom").is_empty());
    }

    #[test]
    fn intent_targets_tests_fires_only_on_test_fixing_intents() {
        assert!(intent_targets_tests(
            "In this repository, the tests fail because of a bug. Fix the source so the tests pass."
        ));
        assert!(intent_targets_tests("make the failing tests pass"));
        // Not a test-fixing task: no suite run should be triggered.
        assert!(!intent_targets_tests("Add a --json flag to the CLI"));
        assert!(!intent_targets_tests("Refactor the parser for clarity"));
    }

    #[test]
    fn summary_with_failures_injects_observed_ids_and_is_a_noop_when_empty() {
        let base = "Top-level entries: src, tests";
        assert_eq!(summary_with_failures(base, &[]), base);
        let with = summary_with_failures(
            base,
            &["tests/test_basic.py::test_session_using_session_settings".to_string()],
        );
        assert!(with.contains("Observed failing tests"));
        assert!(with.contains("tests/test_basic.py::test_session_using_session_settings"));
        assert!(with.starts_with(base));
    }

    /// A pipeline exits with its LAST command's status, so `pytest … | tail -20`
    /// exits 0 however badly pytest failed — the check becomes structurally
    /// incapable of failing and the coder self-verifies green on broken code.
    /// Surfaced by the coder A/B: a gpt-5.4 arm derived exactly this, went green
    /// in 31s with `flask` not even importable, and printed a merge command.
    #[test]
    fn strips_trailing_output_filters_that_mask_the_exit_code() {
        let mut c = OutcomeContract {
            description: "tests pass".into(),
            checks: vec![
                ContractCheck {
                    name: "run_full_test_suite".into(),
                    command: "python -m pytest tests/ -x -q 2>&1 | tail -20".into(),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 120,
                    baseline: false,
                    differential: None,
                },
                ContractCheck {
                    name: "chained".into(),
                    command: "pytest -q | head -n 50 | tail -5".into(),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 120,
                    baseline: false,
                    differential: None,
                },
            ],
        };
        c.strip_exit_masking_pipes();
        // `2>&1` is a redirection, not a pipe — it must survive.
        assert_eq!(c.checks[0].command, "python -m pytest tests/ -x -q 2>&1");
        assert_eq!(c.checks[1].command, "pytest -q");
    }

    /// `grep`'s exit status IS the assertion ("output contains X"), and `||` is an
    /// or-list rather than a pipe. Neither may be rewritten.
    #[test]
    fn leaves_meaningful_pipes_and_or_lists_alone() {
        let keep = [
            "pytest -q | grep -q PASSED",
            "cmd || echo fallback",
            "python -c \"print('a|b')\"",
            "pytest -q",
        ];
        for cmd in keep {
            let mut c = OutcomeContract {
                description: "d".into(),
                checks: vec![ContractCheck {
                    name: "k".into(),
                    command: cmd.into(),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 120,
                    baseline: false,
                    differential: None,
                }],
            };
            c.strip_exit_masking_pipes();
            assert_eq!(c.checks[0].command, cmd, "must not rewrite: {cmd}");
        }
    }
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};

    const VALID: &str = r#"{
        "description": "file exists",
        "checks": [{"name": "exists", "command": "test -f x.txt"}]
    }"#;

    #[test]
    fn prompt_steers_toward_verifying_the_task_and_real_labels() {
        let p = build_contract_prompt(
            "add a --version flag",
            "Top-level entries: Cargo.toml, src\nBuild systems detected: Rust (cargo)",
            &[],
        );
        // Carries the task and repo orientation.
        assert!(p.contains("add a --version flag"));
        assert!(p.contains("Rust (cargo)"));
        // Steers away from toolchain-only checks and placeholder labels.
        assert!(p.contains("verify THE TASK ITSELF"));
        assert!(
            p.contains("rustc --version"),
            "names the toolchain-only anti-pattern"
        );
        assert!(p.contains("never the literal placeholder"));
        // Guards the common small-model failure modes.
        assert!(p.contains("non-interactively"));
        assert!(
            p.contains("CERTAIN will appear"),
            "output_contains caution present"
        );
        assert!(p.contains("no markdown fences"));
    }

    #[test]
    fn repair_prompt_appends_prior_issues() {
        let p = build_contract_prompt("t", "r", &["check 'a' has an empty command".into()]);
        assert!(p.contains("FAILED validation"));
        assert!(p.contains("empty command"));
    }

    #[tokio::test]
    async fn derives_on_first_valid_attempt() {
        let c = derive_contract(
            |_r| async { Ok::<_, String>(VALID.into()) },
            "make x",
            "repo",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
        assert!(c.checks[0].expect_exit_zero, "default applies");
        assert_eq!(c.checks[0].timeout_secs, 120);
    }

    #[tokio::test(start_paused = true)]
    async fn times_out_when_generation_hangs() {
        // A hung inference backend (no usable model — PAR-7169/7264) must not make
        // derivation block forever; it should fail fast with an actionable error
        // (PAR-7170). With the clock paused the 120s timeout fires via virtual
        // time, so this test is instant rather than taking two minutes.
        let err = derive_contract(
            |_r| async {
                tokio::time::sleep(std::time::Duration::from_secs(10_000)).await;
                Ok::<_, String>(VALID.into())
            },
            "make x",
            "repo",
            1,
            &[],
        )
        .await
        .unwrap_err();
        assert!(
            err.contains("timed out"),
            "expected timeout error, got: {err}"
        );
    }

    #[tokio::test]
    async fn repairs_fenced_and_chatty_output() {
        let fenced = format!("Sure! Here is the contract:\n```json\n{VALID}\n```");
        let c = derive_contract(
            |_r| {
                let text = fenced.clone();
                async move { Ok::<_, String>(text) }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks[0].name, "exists");
    }

    #[tokio::test]
    async fn invalid_then_repaired() {
        let calls = AtomicUsize::new(0);
        let c = derive_contract(
            |req: ContractDraftRequest| {
                let prompt = req.prompt;
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    if n == 1 {
                        Ok::<_, String>(r#"{"description": "no checks", "checks": []}"#.into())
                    } else {
                        assert!(
                            prompt.contains("FAILED validation"),
                            "repair prompt carries issues"
                        );
                        Ok(VALID.into())
                    }
                }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
    }

    #[tokio::test]
    async fn gives_up_with_error_after_max() {
        let err = derive_contract(
            |_r| async { Ok::<_, String>("not json at all".into()) },
            "x",
            "r",
            2,
            &[],
        )
        .await
        .unwrap_err();
        assert!(err.contains("after 2 attempts"), "{err}");
    }

    // --- Model rotation on JSON-shape failure (Parslee-ai/car#889) ----------

    /// Record the `rotate_model` flag of every attempt, so a test can assert
    /// exactly which attempts asked routing for a different model.
    fn rotation_recorder() -> std::sync::Arc<std::sync::Mutex<Vec<bool>>> {
        std::sync::Arc::new(std::sync::Mutex::new(Vec::new()))
    }

    /// The live failure: when the preferred lane is down, routing falls back to
    /// a capable code model that will not hold strict JSON, and the repair
    /// prompt goes back through the SAME routing — so all three attempts land on
    /// the same model and the session dies at zero iterations. A model that
    /// cannot return the object is not a prompt problem; the next attempt must
    /// be routed away from it.
    #[tokio::test]
    async fn rotates_model_after_unparseable_output() {
        let rotations = rotation_recorder();
        let seen = rotations.clone();
        let calls = AtomicUsize::new(0);
        let c = derive_contract(
            move |req: ContractDraftRequest| {
                seen.lock().unwrap().push(req.rotate_model);
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    if n == 1 {
                        // The 2026-08-11 shape verbatim: chatty preamble and a
                        // truncated object, so there is no closing brace.
                        Ok::<_, String>(
                            "Sure! Here is the outcome contract:\n\
                             {\"description\": \"tests pass\", \"checks\": ["
                                .to_string(),
                        )
                    } else {
                        Ok(VALID.into())
                    }
                }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
        assert_eq!(
            *rotations.lock().unwrap(),
            vec![false, true],
            "only the attempt AFTER the unusable reply asks routing to rotate"
        );
    }

    /// Valid JSON, wrong object. The model honoured "return JSON" but not the
    /// schema it was handed verbatim — still a structural failure of the model,
    /// so the retry gets a different one rather than the same one again.
    #[tokio::test]
    async fn rotates_model_after_output_that_is_json_but_not_a_contract() {
        let rotations = rotation_recorder();
        let seen = rotations.clone();
        let calls = AtomicUsize::new(0);
        let c = derive_contract(
            move |req: ContractDraftRequest| {
                seen.lock().unwrap().push(req.rotate_model);
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    if n == 1 {
                        Ok::<_, String>(
                            r#"{"result": "ok", "steps": ["run the tests"]}"#.to_string(),
                        )
                    } else {
                        Ok(VALID.into())
                    }
                }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
        assert_eq!(
            *rotations.lock().unwrap(),
            vec![false, true],
            "a schema mismatch is a JSON-shape failure and rotates too"
        );
    }

    /// A validation problem is SUBSTANCE — the model returned exactly the right
    /// shape and merely drafted a bad contract. The repair prompt genuinely
    /// fixes that on the same model, and rotating would throw away the one
    /// model we have just proven can hold the format.
    #[tokio::test]
    async fn validation_failure_does_not_rotate_model() {
        let rotations = rotation_recorder();
        let seen = rotations.clone();
        let calls = AtomicUsize::new(0);
        let c = derive_contract(
            move |req: ContractDraftRequest| {
                seen.lock().unwrap().push(req.rotate_model);
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    if n == 1 {
                        Ok::<_, String>(r#"{"description": "no checks", "checks": []}"#.to_string())
                    } else {
                        Ok(VALID.into())
                    }
                }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
        assert_eq!(
            *rotations.lock().unwrap(),
            vec![false, false],
            "a contract that parsed but failed validate() must stay on its model"
        );
    }

    /// One unusable reply must not pin rotation on for the rest of the budget:
    /// once an attempt's output parses, the model has proven it can hold the
    /// shape, and any later repair is about substance again.
    #[tokio::test]
    async fn rotation_clears_once_an_attempt_parses() {
        let rotations = rotation_recorder();
        let seen = rotations.clone();
        let calls = AtomicUsize::new(0);
        let c = derive_contract(
            move |req: ContractDraftRequest| {
                seen.lock().unwrap().push(req.rotate_model);
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    match n {
                        // Unusable as JSON — attempt 2 must rotate.
                        1 => Ok::<_, String>("I'd be happy to help!".to_string()),
                        // Parses, but gates nothing — substance, so attempt 3
                        // stays where it is.
                        2 => Ok(r#"{"description": "no checks", "checks": []}"#.to_string()),
                        _ => Ok(VALID.into()),
                    }
                }
            },
            "x",
            "r",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks.len(), 1);
        assert_eq!(
            *rotations.lock().unwrap(),
            vec![false, true, false],
            "rotation is set by the shape failure and cleared by the next parse"
        );
    }

    #[test]
    fn is_toolchain_only_flags_bare_version_probes_only() {
        // Bare version/help probes of build tools — these gate nothing.
        for c in [
            "cargo --version",
            "cargo -V",
            "rustc --version",
            "node -v",
            "npm --version",
            "python3 --version",
            "go version",
            "make --help",
        ] {
            assert!(is_toolchain_only(c), "should flag `{c}`");
        }
        // Real checks that exercise the change must NOT be flagged.
        for c in [
            "cargo build",
            "cargo test",
            "cargo run -- --version",
            "cargo run --release -- --version",
            "./target/debug/greeter --version",
            "cargo --version && cargo build",
            "test -f src/main.rs",
            "grep -q version Cargo.toml",
            "rustc src/main.rs -o /tmp/x",
        ] {
            assert!(!is_toolchain_only(c), "should NOT flag `{c}`");
        }
    }

    #[test]
    fn validate_rejects_toolchain_only_and_placeholder_name() {
        let c = OutcomeContract {
            description: "d".into(),
            checks: vec![ContractCheck {
                // The literal placeholder leaking through, paired with a
                // toolchain-only command — both seen live from a 1.7B model.
                name: "unique_snake_case_label".into(),
                command: "cargo --version".into(),
                expect_exit_zero: true,
                output_contains: None,
                timeout_secs: 120,
                baseline: false,
                differential: None,
            }],
        };
        let issues = c.validate();
        assert!(
            issues.iter().any(|i| i.contains("placeholder name")),
            "{issues:?}"
        );
        assert!(
            issues.iter().any(|i| i.contains("toolchain-only no-op")),
            "{issues:?}"
        );
    }

    #[test]
    fn repair_cosmetic_names_fixes_placeholder_empty_and_duplicates() {
        let mk = |name: &str, cmd: &str| ContractCheck {
            name: name.into(),
            command: cmd.into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 60,
            baseline: false,
            differential: None,
        };
        let mut c = OutcomeContract {
            description: "d".into(),
            checks: vec![
                mk("unique_snake_case_label", "pytest a"),
                mk("", "pytest b"),
                mk("run_tests", "pytest c"),
                mk("run_tests", "pytest d"),
            ],
        };
        c.repair_cosmetic_names();
        let names: Vec<&str> = c.checks.iter().map(|x| x.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["check_1", "check_2", "run_tests", "run_tests_2"]
        );
        assert_eq!(c.checks[0].command, "pytest a");
        assert!(c.validate().is_empty(), "{:?}", c.validate());
    }

    #[test]
    fn strip_absolute_cd_prefixes_drops_repo_but_keeps_relative_and_body() {
        let mk = |cmd: &str| ContractCheck {
            name: "c".into(),
            command: cmd.into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 60,
            baseline: false,
            differential: None,
        };
        let mut c = OutcomeContract {
            description: "d".into(),
            checks: vec![
                // The exact hallucination the A/B surfaced.
                mk("cd /repo && python -m pytest tests/ -v 2>&1"),
                // Semicolon separator + absolute path.
                mk("cd /workspace ; ./run.sh"),
                // A relative cd is a legitimate intra-repo move — keep it.
                mk("cd subpkg && cargo test"),
                // No cd — untouched.
                mk("python -m pytest -q tests/test_x.py"),
                // Absolute cd nested later (not leading) — left alone.
                mk("echo hi && cd /repo && pytest"),
            ],
        };
        c.strip_absolute_cd_prefixes();
        let cmds: Vec<&str> = c.checks.iter().map(|x| x.command.as_str()).collect();
        assert_eq!(
            cmds,
            vec![
                "python -m pytest tests/ -v 2>&1",
                "./run.sh",
                "cd subpkg && cargo test",
                "python -m pytest -q tests/test_x.py",
                "echo hi && cd /repo && pytest",
            ]
        );
    }

    #[tokio::test]
    async fn derive_strips_hallucinated_repo_cd_first_try() {
        // A model that returns a valid contract but prefixes the check with the
        // nonexistent `/repo` mount must not need a repair round — the derived
        // contract comes back runnable at the worktree root.
        let with_repo_cd = r#"{"description":"tests pass","checks":[
            {"name":"run_tests","command":"cd /repo && python -m pytest -q tests/test_x.py"}]}"#;
        let c = derive_contract(
            |_r: ContractDraftRequest| async move { Ok::<_, String>(with_repo_cd.into()) },
            "fix the bug so pytest passes",
            "Python",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(
            c.checks[0].command, "python -m pytest -q tests/test_x.py",
            "the hallucinated `cd /repo &&` prefix must be stripped"
        );
    }

    #[tokio::test]
    async fn derive_succeeds_first_try_when_model_only_leaves_placeholder_name() {
        let calls = AtomicUsize::new(0);
        let placeholder_named = r#"{"description":"tests pass","checks":[
            {"name":"unique_snake_case_label","command":"python3 -m pytest -q"}]}"#;
        let c = derive_contract(
            |_r: ContractDraftRequest| {
                calls.fetch_add(1, Ordering::SeqCst);
                async move { Ok::<_, String>(placeholder_named.into()) }
            },
            "fix the bug so pytest passes",
            "Python",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(calls.load(Ordering::SeqCst), 1, "no repair attempt needed");
        assert_eq!(c.checks[0].name, "check_1");
        assert_eq!(c.checks[0].command, "python3 -m pytest -q");
    }

    #[tokio::test]
    async fn derive_repairs_a_toolchain_only_first_attempt() {
        let calls = AtomicUsize::new(0);
        let toolchain_only = r#"{"description":"v","checks":[
            {"name":"unique_snake_case_label","command":"cargo --version"}]}"#;
        let real = r#"{"description":"v","checks":[
            {"name":"version_flag_prints","command":"cargo run -- --version"}]}"#;
        let c = derive_contract(
            |req: ContractDraftRequest| {
                let prompt = req.prompt;
                let n = calls.fetch_add(1, Ordering::SeqCst) + 1;
                async move {
                    if n == 1 {
                        Ok::<_, String>(toolchain_only.into())
                    } else {
                        // Repair prompt carries the SUBSTANCE rejection
                        // (toolchain-only). The placeholder name was auto-repaired
                        // by repair_cosmetic_names before validate, so a naming
                        // slip never burns a repair attempt or reaches the model.
                        assert!(prompt.contains("toolchain-only no-op"), "{prompt}");
                        assert!(!prompt.contains("placeholder name"), "{prompt}");
                        Ok(real.into())
                    }
                }
            },
            "add a --version flag",
            "Rust (cargo)",
            3,
            &[],
        )
        .await
        .unwrap();
        assert_eq!(c.checks[0].command, "cargo run -- --version");
        assert_eq!(calls.load(Ordering::SeqCst), 2, "took exactly one repair");
    }

    #[test]
    fn validate_catches_empty_and_duplicate_and_assertless() {
        let c = OutcomeContract {
            description: "d".into(),
            checks: vec![
                ContractCheck {
                    name: "a".into(),
                    command: "true".into(),
                    expect_exit_zero: false,
                    output_contains: None,
                    timeout_secs: 5,
                    baseline: false,
                    differential: None,
                },
                ContractCheck {
                    name: "a".into(),
                    command: "".into(),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 5,
                    baseline: false,
                    differential: None,
                },
            ],
        };
        let issues = c.validate();
        assert!(issues.iter().any(|i| i.contains("asserts nothing")));
        assert!(issues.iter().any(|i| i.contains("empty command")));
        assert!(issues.iter().any(|i| i.contains("duplicate")));
    }

    #[tokio::test]
    async fn evaluate_passes_and_fails_checks_in_a_real_dir() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("present.txt"), "hello needle").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![
                ContractCheck {
                    name: "exists".into(),
                    command: crate::coder::test_cmds::file_exists("present.txt"),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 10,
                    baseline: false,
                    differential: None,
                },
                ContractCheck {
                    name: "content".into(),
                    command: crate::coder::test_cmds::cat("present.txt"),
                    expect_exit_zero: true,
                    output_contains: Some("needle".into()),
                    timeout_secs: 10,
                    baseline: false,
                    differential: None,
                },
                ContractCheck {
                    name: "missing".into(),
                    command: crate::coder::test_cmds::file_exists("absent.txt"),
                    expect_exit_zero: true,
                    output_contains: None,
                    timeout_secs: 10,
                    baseline: false,
                    differential: None,
                },
            ],
        };
        let results = evaluate_contract(&contract, &exec, &sink).await;
        assert_eq!(results.len(), 3, "all checks run even after a failure");
        assert!(results[0].passed);
        assert!(results[1].passed);
        assert!(!results[2].passed);
        assert_eq!(results[2].exit_code, Some(1));
    }

    #[tokio::test]
    async fn evaluate_fails_on_missing_substring() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![ContractCheck {
                name: "needle".into(),
                command: "echo haystack".into(),
                expect_exit_zero: true,
                output_contains: Some("needle".into()),
                timeout_secs: 10,
                baseline: false,
                differential: None,
            }],
        };
        let results = evaluate_contract(&contract, &exec, &sink).await;
        assert!(!results[0].passed, "exit 0 but substring missing must fail");
        assert_eq!(results[0].exit_code, Some(0));
    }

    // --- Red-green baseline (car#707) -------------------------------------

    fn check(name: &str, command: &str) -> ContractCheck {
        ContractCheck {
            name: name.into(),
            command: command.into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 10,
            baseline: false,
            differential: None,
        }
    }

    // --- The session clock bounds the checks, not just the loop ------------

    /// A check may take its own timeout, and never more than the session has
    /// left.
    #[test]
    fn a_check_never_outlives_the_session_budget() {
        // No session clock: the check's own timeout stands.
        assert_eq!(clamp_check_timeout(900, None), 900);
        // Plenty left: unchanged.
        assert_eq!(clamp_check_timeout(900, Some(3600)), 900);
        // Less left than the check wants: the session wins.
        assert_eq!(clamp_check_timeout(900, Some(30)), 30);
        // Spent. `run_shell` floors this at 1s, so the check reports a timeout
        // instead of running to completion outside a budget already gone.
        assert_eq!(clamp_check_timeout(900, Some(0)), 0);
    }

    /// The baseline run is INSIDE the session clock.
    ///
    /// `--max-session-wall-secs` used to bound only the loop, so a contract
    /// holding checks with long `timeout_secs` could burn its full sum before
    /// the clock started — a ten-minute budget buying a three-hour run. The
    /// check here would take five seconds on its own timeout; with the session
    /// budget exhausted it must be cut off in about one.
    #[tokio::test]
    async fn an_exhausted_session_budget_cuts_the_baseline_short() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![ContractCheck {
                name: "slow".into(),
                command: "sleep 5".into(),
                expect_exit_zero: true,
                output_contains: None,
                timeout_secs: 30,
                baseline: false,
                differential: None,
            }],
        };

        let spent = SessionDeadline::new(Some(0));
        let started = std::time::Instant::now();
        let baseline = evaluate_contract_baseline_within(&contract, &exec, Some(&spent)).await;
        let elapsed = started.elapsed();

        assert!(!baseline[0].passed, "a cut-off check is not a pass");
        assert!(
            elapsed < std::time::Duration::from_secs(4),
            "the baseline ran for {elapsed:?}; a spent session budget must cut it short"
        );
    }

    /// A check the session clock killed says so on the result itself.
    ///
    /// Without this the gate's red is unreadable: `passed: false` covers both
    /// "the tests failed" and "the budget expired before the tests could run",
    /// and `car code-task` booked the second as `contract_not_green` — a
    /// scorable no-progress round charged to the model for work the loop had
    /// already verified green (car#1053).
    #[tokio::test]
    async fn a_check_starved_by_the_session_clock_is_marked_as_such() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let slow = ContractCheck {
            name: "suite".into(),
            command: "sleep 5".into(),
            expect_exit_zero: true,
            output_contains: None,
            // Generous on its own terms: nothing here is the check's fault.
            timeout_secs: 900,
            baseline: false,
            differential: None,
        };
        let spent = SessionDeadline::new(Some(0));

        let r = run_check(&slow, &exec, Some(&spent), &BaselineCaptures::new()).await;

        assert!(!r.passed, "a cut-off check is still not a pass");
        assert!(r.timed_out, "it was killed at a timeout, not exited");
        assert!(
            r.deadline_clamped,
            "the timeout it died at was the session's leftover budget, not its own 900s"
        );
        assert!(
            r.starved_by_deadline(),
            "so this is not a verdict on the work"
        );
    }

    /// And the other half of the pair: a check that blows its OWN timeout is a
    /// genuine red. A hang is a defect, and laundering one into a budget excuse
    /// is exactly the failure the two-bit encoding exists to prevent.
    #[tokio::test]
    async fn a_check_that_blows_its_own_timeout_is_not_starved() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let hang = ContractCheck {
            name: "suite".into(),
            command: "sleep 5".into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 1,
            baseline: false,
            differential: None,
        };
        let plenty = SessionDeadline::new(Some(3600));

        let r = run_check(&hang, &exec, Some(&plenty), &BaselineCaptures::new()).await;

        assert!(!r.passed);
        assert!(r.timed_out, "it ran past its own one-second ceiling");
        assert!(
            !r.deadline_clamped,
            "the session had an hour left — nothing was clamped"
        );
        assert!(
            !r.starved_by_deadline(),
            "a genuine hang must stay a red verdict"
        );
    }

    /// The half of that pair no test can run: a check is killed at
    /// `min(timeout_secs, remaining).clamp(1, MAX_SHELL_TIMEOUT_SECS)`, so a
    /// declared `timeout_secs` above 600 is cut by the SHELL ceiling, not by the
    /// session — and a 600-second hang is not something a unit test can sit
    /// through. So the derivation is pinned directly.
    ///
    /// The window this closes is real, not theoretical: `timeout_secs` has no
    /// validation cap and `clamp_check_timeout`'s own doc uses `900` as the
    /// realistic workspace-suite figure, which against the default 3600s session
    /// leaves ~300 seconds per run in which a genuine hang would have been
    /// laundered into `session_wall_exhausted`.
    #[test]
    fn the_clamp_flag_is_derived_against_the_shell_ceiling_not_the_declared_one() {
        use super::super::shell_tool::MAX_SHELL_TIMEOUT_SECS;
        assert_eq!(
            MAX_SHELL_TIMEOUT_SECS, 600,
            "the cases below are read at 600"
        );
        let default = MAX_SHELL_TIMEOUT_SECS;

        // Session cut it: 500 < 600, so the check really did lose seconds it
        // would otherwise have had.
        assert!(deadline_set_the_timeout(900, Some(500), default));

        // The one that was wrong. 700s of budget left, but the check dies at the
        // 600s shell ceiling — the session had time to spare, so this is a hang.
        assert!(
            !deadline_set_the_timeout(900, Some(700), default),
            "600 < remaining < timeout_secs is the shell ceiling cutting the \
             check, not the session clock — marking it clamped would let a hang \
             report as session_wall_exhausted"
        );

        // Plenty of budget, nothing clamped.
        assert!(!deadline_set_the_timeout(900, Some(3600), default));
        // Exactly at the ceiling is not below it.
        assert!(!deadline_set_the_timeout(900, Some(600), default));
        // Below the check's own sub-ceiling timeout: the session did cut it.
        assert!(deadline_set_the_timeout(120, Some(30), default));
        assert!(!deadline_set_the_timeout(120, Some(200), default));
        // No deadline at all clamps nothing.
        assert!(!deadline_set_the_timeout(900, None, default));

        // And the case this one exists to complement (car#1065). The operator
        // raised the ceiling to 900, so the check really was allowed its full
        // declared timeout — 700s of remaining budget is then the session clock
        // cutting it and nothing else. That classification was unreachable while
        // the ceiling was a constant.
        assert!(
            deadline_set_the_timeout(900, Some(700), 900),
            "with the ceiling raised to the declared timeout, a shorter remaining \
             budget is the session clock cutting the check"
        );
        // Raising it PAST the declared timeout changes nothing: the check's own
        // `timeout_secs` is still the binding ceiling.
        assert!(!deadline_set_the_timeout(900, Some(950), 3600));
        assert!(deadline_set_the_timeout(900, Some(800), 3600));
    }

    /// The composed two-step clamp, pinned as arithmetic: the session budget
    /// first, then the executor's contract-check ceiling with the shell's own 1s
    /// floor.
    #[test]
    fn the_effective_check_timeout_composes_budget_then_ceiling() {
        // Default ceiling: a 900s declaration is cut to 600 whatever the budget.
        assert_eq!(effective_check_timeout(900, None, 600), 600);
        assert_eq!(effective_check_timeout(900, Some(3600), 600), 600);
        // A session budget below the ceiling wins.
        assert_eq!(effective_check_timeout(900, Some(120), 600), 120);
        // Raised ceiling: the declaration finally stands. This is the fix.
        assert_eq!(effective_check_timeout(900, Some(3600), 900), 900);
        assert_eq!(effective_check_timeout(900, None, 1200), 900);
        // A spent budget still gets the 1s floor rather than zero, and a `0`
        // ceiling cannot take that floor away either.
        assert_eq!(effective_check_timeout(900, Some(0), 600), 1);
        assert_eq!(effective_check_timeout(900, None, 0), 1);
    }

    /// And the ceiling reaches the PROCESS, not only the flag: with a
    /// one-second ceiling a `sleep 5` declaring 30s is killed at one second and
    /// reports a plain timeout — the session had an hour left, so nothing was
    /// deadline-clamped.
    ///
    /// The cheap direction of the same proof: checking the raised ceiling
    /// directly would mean sitting through ten real minutes.
    #[tokio::test]
    async fn the_check_ceiling_bounds_the_process_not_just_the_flag() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path()).with_check_timeout_ceiling(1);
        assert_eq!(exec.check_timeout_ceiling(), 1);
        let slow = ContractCheck {
            name: "slow".into(),
            command: "sleep 5".into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 30,
            baseline: false,
            differential: None,
        };
        let plenty = SessionDeadline::new(Some(3600));

        let r = run_check(&slow, &exec, Some(&plenty), &BaselineCaptures::new()).await;

        assert!(!r.passed);
        assert!(
            r.timed_out,
            "the 1s check ceiling killed it, not the declared 30s"
        );
        assert!(
            !r.deadline_clamped,
            "the session had an hour left — the check ceiling cut it"
        );
        assert!(r.duration_ms < 5_000, "it must not have slept the full 5s");
    }

    /// A zero from config cannot make every check die instantly: the builder
    /// floors the ceiling at one second.
    #[test]
    fn a_zero_check_ceiling_is_floored_not_honored() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path()).with_check_timeout_ceiling(0);
        assert_eq!(exec.check_timeout_ceiling(), 1);
    }

    /// The default is unchanged, and the MODEL-facing `shell` tool keeps the
    /// advertised 600s ceiling even on an executor whose CHECK ceiling is
    /// raised — a slow test gate is the operator's decision about their own
    /// repository, not a licence for the model to sit on one command for an
    /// hour.
    #[test]
    fn raising_the_check_ceiling_leaves_the_model_facing_shell_alone() {
        use super::super::shell_tool::MAX_SHELL_TIMEOUT_SECS;
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        assert_eq!(exec.check_timeout_ceiling(), MAX_SHELL_TIMEOUT_SECS);

        let raised = WorktreeExecutor::new(dir.path()).with_check_timeout_ceiling(3600);
        assert_eq!(raised.check_timeout_ceiling(), 3600);
        let shell_def = WorktreeExecutor::tool_defs()
            .into_iter()
            .find(|d| d["name"] == "shell")
            .expect("shell tool is advertised");
        assert!(
            shell_def["parameters"]["properties"]["timeout_secs"]["description"]
                .as_str()
                .unwrap()
                .contains("max 600"),
            "the model-facing description still promises 600"
        );
    }

    /// And an unspent budget leaves the check's own timeout alone — the clamp
    /// must not truncate a run that is inside its declared ceiling.
    #[tokio::test]
    async fn a_healthy_session_budget_does_not_truncate_the_baseline() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![check("quick", "exit 0")],
        };
        let plenty = SessionDeadline::new(Some(3600));
        let baseline = evaluate_contract_baseline_within(&contract, &exec, Some(&plenty)).await;
        assert!(baseline[0].passed);
    }

    /// The case the baseline exists to catch: every check is well-formed and
    /// task-specific enough to clear `validate()`, and every one already passes
    /// on an unmodified worktree — so the contract gates nothing for this task.
    #[tokio::test]
    async fn an_all_green_baseline_is_flagged_as_gating_nothing() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![check("a", "exit 0"), check("b", "exit 0")],
        };

        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        assert_eq!(baseline.len(), 2);
        assert!(baseline.iter().all(|r| r.passed));
        assert!(baseline_gates_nothing(&baseline));
    }

    /// A mixed baseline must NOT be flagged. Checks that pass before the change
    /// are ordinary — a refactor's checks are green before and after by design —
    /// so escalating on one would abort sessions over a non-fault.
    #[tokio::test]
    async fn a_mixed_baseline_is_not_flagged() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![
                check("already_green", "exit 0"),
                check("must_fix", "exit 1"),
            ],
        };

        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        assert!(baseline[0].passed);
        assert!(
            !baseline[1].passed,
            "the red check is what gates the session"
        );
        assert!(
            !baseline_gates_nothing(&baseline),
            "one green check among red ones is information, not a fault"
        );
    }

    #[tokio::test]
    async fn an_all_red_baseline_is_not_flagged() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![check("must_fix", "exit 1")],
        };
        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        assert!(!baseline_gates_nothing(&baseline));
    }

    /// An empty result set is not "all green" — vacuous truth would report a
    /// checkless contract as gating nothing *here*, stealing the diagnosis from
    /// `validate()`, which owns that case and gives a better message.
    #[test]
    fn an_empty_baseline_is_not_all_green() {
        assert!(!baseline_gates_nothing(&[]));
    }

    /// The baseline must produce the same verdicts as a narrated evaluation —
    /// it is the same checks against the same worktree, differing only in
    /// whether it emits events.
    #[tokio::test]
    async fn baseline_agrees_with_the_narrated_evaluation() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();
        let contract = OutcomeContract {
            description: "d".into(),
            checks: vec![check("green", "exit 0"), check("red", "exit 1")],
        };

        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        let narrated = evaluate_contract(&contract, &exec, &sink).await;

        let verdicts = |rs: &[CheckResult]| -> Vec<(String, bool)> {
            rs.iter().map(|r| (r.name.clone(), r.passed)).collect()
        };
        assert_eq!(verdicts(&baseline), verdicts(&narrated));
    }

    /// Outcomes line 44: a constraint stated only in the discussion must reach
    /// the drafted contract. The drafting model demonstrably drops them
    /// (measured 1 success / 3 trials), so carry-through is VERIFIED inside the
    /// existing attempt budget, and a miss re-prompts naming the dropped
    /// constraint verbatim rather than redrawing blindly.
    #[tokio::test]
    async fn a_dropped_constraint_is_repaired_into_the_contract() {
        use std::sync::Mutex;
        // Turn 1: a draft that ignores the constraint.
        // Turn 2: the judge, reporting constraint 1 missing.
        // Turn 3: the repaired draft.
        // Turn 4: the judge again, now satisfied.
        let script = Mutex::new(vec![
            r#"{"description":"tests pass","checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[1]}"#.to_string(),
            r#"{"description":"tests pass and the public signature is untouched",
                "checks":[{"name":"tests","command":"exit 0"},
                          {"name":"signature_unchanged","command":"grep -q 'fn add(a: i32, b: i32)' src/lib.rs"}]}"#
                .to_string(),
            r#"{"missing":[]}"#.to_string(),
        ]);
        let prompts: Mutex<Vec<String>> = Mutex::new(Vec::new());
        let constraint = "The public signature of add() must stay exactly as it is.";

        let contract = derive_contract(
            |r: ContractDraftRequest| {
                prompts.lock().unwrap().push(r.prompt);
                let next = script.lock().unwrap().remove(0);
                async move { Ok::<_, String>(next) }
            },
            "make the failing tests pass",
            "Top-level entries: src, Cargo.toml",
            3,
            &[constraint.to_string()],
        )
        .await
        .expect("the repair pass must produce a contract");

        // The constraint is now expressed as a real check.
        assert!(
            contract
                .checks
                .iter()
                .any(|c| c.name == "signature_unchanged"),
            "the dropped constraint must be repaired into the contract: {contract:?}"
        );
        // ...and the repair prompt named it verbatim rather than redrawing blind.
        let prompts = prompts.lock().unwrap();
        assert!(
            prompts[2].contains(constraint) && prompts[2].contains("DROPPED"),
            "the retry must name the dropped constraint verbatim: {}",
            prompts[2]
        );
    }

    /// When the budget runs out with a constraint still unexpressed, the
    /// contract still comes back — but says so. An operator who stated a
    /// constraint must never be left believing it was captured when it was not.
    #[tokio::test]
    async fn an_unexpressible_constraint_is_disclosed_not_dropped() {
        use std::sync::Mutex;
        let script = Mutex::new(vec![
            r#"{"description":"tests pass","checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[1]}"#.to_string(),
            r#"{"description":"tests pass","checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[1]}"#.to_string(),
        ]);
        let constraint = "Get written sign-off from the CFO before merging.";

        let contract = derive_contract(
            |_r: ContractDraftRequest| {
                let next = script.lock().unwrap().remove(0);
                async move { Ok::<_, String>(next) }
            },
            "make the failing tests pass",
            "Top-level entries: src",
            2,
            &[constraint.to_string()],
        )
        .await
        .expect("a valid draft beats no session, provided the gap is stated");

        assert!(
            contract
                .description
                .contains("NOT VERIFIED BY THIS CONTRACT")
                && contract.description.contains(constraint),
            "an unexpressible constraint must be disclosed in the description: {}",
            contract.description
        );
        // The real check survived — disclosure is additive, not a replacement.
        assert!(contract.checks.iter().any(|c| c.name == "tests"));
    }

    /// A constraint that reaches only the `description` has NOT been captured:
    /// prose gates nothing, and the loop can self-verify green against it.
    ///
    /// The judge used to accept "stated in the description" as satisfaction and
    /// the repair prompt offered it as an explicit escape hatch, so the model's
    /// cheapest move — append a sentence — ended derivation with `Ok` and **no**
    /// disclosure. Two identical end-states (constraint present as prose only)
    /// were reported differently depending on the code path that produced them.
    #[tokio::test]
    async fn a_constraint_captured_only_in_prose_fires_the_disclosure() {
        use std::sync::Mutex;
        let script = Mutex::new(vec![
            // 1: a draft that ignores the constraint entirely.
            r#"{"description":"tests pass","checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[1],"prose_only":[]}"#.to_string(),
            // 2: the cheap way out — the constraint restated in prose, no check.
            r#"{"description":"tests pass, and the public signature of add() is unchanged",
                "checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[],"prose_only":[1]}"#.to_string(),
            // 3: it does it again.
            r#"{"description":"tests pass, and the public signature of add() is unchanged",
                "checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[],"prose_only":[1]}"#.to_string(),
        ]);
        let prompts: Mutex<Vec<String>> = Mutex::new(Vec::new());
        let constraint = "The public signature of add() must stay exactly as it is.";

        let contract = derive_contract(
            |r: ContractDraftRequest| {
                prompts.lock().unwrap().push(r.prompt);
                let next = script.lock().unwrap().remove(0);
                async move { Ok::<_, String>(next) }
            },
            "make the failing tests pass",
            "Top-level entries: src",
            3,
            &[constraint.to_string()],
        )
        .await
        .expect("a valid draft beats no session, provided the gap is stated");

        assert!(
            contract
                .description
                .contains("NOT VERIFIED BY THIS CONTRACT")
                && contract.description.contains(constraint),
            "a prose-only constraint must be disclosed, not passed off as captured: {}",
            contract.description
        );
        assert!(
            contract.checks.iter().all(|c| c.name == "tests"),
            "nothing here gates the constraint: {contract:?}"
        );
        // The third draft prompt named the prose failure specifically — "you
        // never mentioned it" and "you mentioned it but nothing checks it" need
        // different fixes.
        let prompts = prompts.lock().unwrap();
        assert!(
            prompts[4].contains(constraint) && prompts[4].contains("NOTHING VERIFIES IT"),
            "the repair must name the prose-only failure: {}",
            prompts[4]
        );
    }

    /// When the budget runs out, the draft that covered the MOST constraints
    /// comes back — not merely the last one drafted. Attempt 1 covering two of
    /// three and attempt 2 covering one used to return attempt 2.
    #[tokio::test]
    async fn the_disclosed_draft_is_the_best_one_seen_not_the_newest() {
        use std::sync::Mutex;
        let script = Mutex::new(vec![
            // 1: gates the first constraint, drops the second.
            r#"{"description":"d","checks":[{"name":"first_gated","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[2],"prose_only":[]}"#.to_string(),
            // 2: a worse draft — it now gates neither.
            r#"{"description":"d","checks":[{"name":"gates_neither","command":"exit 0"}]}"#
                .to_string(),
            r#"{"missing":[1,2],"prose_only":[]}"#.to_string(),
        ]);
        let contract = derive_contract(
            |_r: ContractDraftRequest| {
                let next = script.lock().unwrap().remove(0);
                async move { Ok::<_, String>(next) }
            },
            "do the thing",
            "Top-level entries: src",
            2,
            &["constraint one".to_string(), "constraint two".to_string()],
        )
        .await
        .unwrap();

        assert!(
            contract.checks.iter().any(|c| c.name == "first_gated"),
            "the better draft must survive: {contract:?}"
        );
        assert!(
            contract.description.contains("constraint two")
                && !contract.description.contains("constraint one"),
            "only the genuinely ungated constraint is disclosed: {}",
            contract.description
        );
    }

    /// A judge that fails (transport, timeout, garbage) must not burn the
    /// caller's attempt budget: carry-through verification fails OPEN.
    #[tokio::test]
    async fn a_failing_constraint_judge_does_not_block_derivation() {
        use std::sync::Mutex;
        let script = Mutex::new(vec![
            r#"{"description":"tests pass","checks":[{"name":"tests","command":"exit 0"}]}"#
                .to_string(),
            "the judge returned prose, not JSON".to_string(),
        ]);
        let contract = derive_contract(
            |_r: ContractDraftRequest| {
                let next = script.lock().unwrap().remove(0);
                async move { Ok::<_, String>(next) }
            },
            "make the failing tests pass",
            "Top-level entries: src",
            3,
            &["some constraint".to_string()],
        )
        .await
        .expect("an unusable judge must not fail the derivation");
        assert_eq!(contract.checks.len(), 1);
    }
}

#[cfg(test)]
mod differential_tests {
    use super::*;
    use crate::coder::session::EventSink;
    use crate::coder::shell_tool::WorktreeExecutor;

    fn check(name: &str, command: &str) -> ContractCheck {
        ContractCheck {
            name: name.into(),
            command: command.into(),
            expect_exit_zero: true,
            output_contains: None,
            timeout_secs: 10,
            baseline: false,
            differential: None,
        }
    }

    fn capture(name: &str, output: &str, passed: bool) -> CheckResult {
        CheckResult {
            name: name.into(),
            passed,
            exit_code: Some(if passed { 0 } else { 1 }),
            output_tail: output.into(),
            duration_ms: 1,
            timed_out: false,
            deadline_clamped: false,
        }
    }

    fn captures(name: &str, output: &str) -> BaselineCaptures {
        let mut m = BaselineCaptures::new();
        m.insert(name.into(), capture(name, output, true));
        m
    }

    fn diff(baseline: &str, expect: DifferentialExpect) -> DifferentialCheck {
        DifferentialCheck {
            baseline: baseline.into(),
            expect,
        }
    }

    // ---- schema ---------------------------------------------------------

    /// The pre-#1067 wire shape parses unchanged: both fields are additive.
    #[test]
    fn a_contract_without_the_new_fields_still_parses() {
        let c: ContractCheck = serde_json::from_str(
            r#"{"name": "tests", "command": "cargo test", "timeout_secs": 600}"#,
        )
        .unwrap();
        assert!(!c.baseline);
        assert!(c.differential.is_none());
        // And the default serialization does not grow the wire shape.
        let v = serde_json::to_value(&c).unwrap();
        assert!(v.get("baseline").is_none());
        assert!(v.get("differential").is_none());
    }

    /// Each differential kind round-trips through its wire spelling.
    #[test]
    fn differential_kinds_round_trip_on_the_wire() {
        let json = r#"{
            "name": "rows_decreased",
            "command": "cat counter.txt",
            "differential": {
                "baseline": "orphan_rows",
                "expect": { "delta_within": { "max": -100.0 } }
            }
        }"#;
        let c: ContractCheck = serde_json::from_str(json).unwrap();
        // Exhaustive: a new kind must extend this match or the build fails.
        match &c.differential.as_ref().unwrap().expect {
            DifferentialExpect::DeltaWithin { min, max } => {
                assert_eq!(*min, None);
                assert_eq!(*max, Some(-100.0));
            }
            DifferentialExpect::Changed | DifferentialExpect::Unchanged => {
                panic!("parsed the wrong kind")
            }
        }
        for (wire, expect) in [
            ("\"changed\"", DifferentialExpect::Changed),
            ("\"unchanged\"", DifferentialExpect::Unchanged),
        ] {
            let parsed: DifferentialExpect = serde_json::from_str(wire).unwrap();
            assert_eq!(parsed, expect);
        }
    }

    // ---- validation -------------------------------------------------------

    fn contract(checks: Vec<ContractCheck>) -> OutcomeContract {
        OutcomeContract {
            description: "d".into(),
            checks,
        }
    }

    #[test]
    fn a_baseline_capture_needs_no_assertion_but_a_normal_check_still_does() {
        let mut cap = check("before", "cat counter.txt");
        cap.baseline = true;
        cap.expect_exit_zero = false;
        let mut gate = check("after", "cat counter.txt");
        gate.differential = Some(diff("before", DifferentialExpect::Changed));
        assert!(contract(vec![cap, gate]).validate().is_empty());

        let mut bare = check("nothing", "true");
        bare.expect_exit_zero = false;
        let issues = contract(vec![bare]).validate();
        assert!(issues.iter().any(|i| i.contains("asserts nothing")));
    }

    #[test]
    fn validation_rejects_the_malformed_differential_shapes() {
        // A capture that also diffs.
        let mut both = check("x", "true");
        both.baseline = true;
        both.differential = Some(diff("x", DifferentialExpect::Changed));
        let issues = contract(vec![both, check("y", "true")]).validate();
        assert!(
            issues
                .iter()
                .any(|i| i.contains("both a baseline capture and a differential")),
            "{issues:?}"
        );

        // A reference to a capture that does not exist.
        let mut orphan = check("after", "true");
        orphan.differential = Some(diff("nowhere", DifferentialExpect::Changed));
        let issues = contract(vec![orphan]).validate();
        assert!(
            issues
                .iter()
                .any(|i| i.contains("no check by that name is marked baseline")),
            "{issues:?}"
        );

        // A reference to a capture declared after the differential.
        let mut early = check("after", "true");
        early.differential = Some(diff("before", DifferentialExpect::Changed));
        let mut late_cap = check("before", "true");
        late_cap.baseline = true;
        let issues = contract(vec![early, late_cap]).validate();
        assert!(
            issues.iter().any(|i| i.contains("declared after it")),
            "{issues:?}"
        );

        // delta_within with no bounds asserts nothing.
        let mut cap = check("before", "true");
        cap.baseline = true;
        let mut unbounded = check("after", "true");
        unbounded.differential = Some(diff(
            "before",
            DifferentialExpect::DeltaWithin {
                min: None,
                max: None,
            },
        ));
        let issues = contract(vec![cap.clone(), unbounded]).validate();
        assert!(issues.iter().any(|i| i.contains("no bounds")), "{issues:?}");

        // min above max is unsatisfiable.
        let mut inverted = check("after", "true");
        inverted.differential = Some(diff(
            "before",
            DifferentialExpect::DeltaWithin {
                min: Some(5.0),
                max: Some(1.0),
            },
        ));
        let issues = contract(vec![cap.clone(), inverted]).validate();
        assert!(
            issues.iter().any(|i| i.contains("min above max")),
            "{issues:?}"
        );

        // A contract that only captures gates nothing.
        let issues = contract(vec![cap]).validate();
        assert!(
            issues
                .iter()
                .any(|i| i.contains("every check is a baseline capture")),
            "{issues:?}"
        );
    }

    // ---- the three kinds, decided by the runtime --------------------------

    #[test]
    fn changed_passes_on_a_move_and_fails_identical_with_the_message() {
        let d = diff("hb", DifferentialExpect::Changed);
        let caps = captures("hb", "ERROR");
        assert!(evaluate_differential(&d, &caps, "HEALTHY").is_ok());
        let err = evaluate_differential(&d, &caps, "ERROR").unwrap_err();
        assert!(
            err.contains("expected the output to CHANGE from baseline 'hb'"),
            "{err}"
        );
        assert!(err.contains("identical to the captured value"), "{err}");
    }

    #[test]
    fn unchanged_holds_the_control_group_and_names_the_violation() {
        let d = diff("control", DifferentialExpect::Unchanged);
        let caps = captures("control", "rows=42");
        assert!(evaluate_differential(&d, &caps, "rows=42\n").is_ok());
        let err = evaluate_differential(&d, &caps, "rows=41").unwrap_err();
        assert!(err.contains("UNCHANGED from baseline 'control'"), "{err}");
        assert!(err.contains("control-group"), "{err}");
        assert!(
            err.contains("\"rows=42\"") && err.contains("\"rows=41\""),
            "{err}"
        );
    }

    #[test]
    fn delta_within_bounds_both_sides_and_reports_the_numbers() {
        let caps = captures("orphans", "orphaned rows: 435,594");
        // "fell by at least 100": delta <= -100.
        let d = diff(
            "orphans",
            DifferentialExpect::DeltaWithin {
                min: None,
                max: Some(-100.0),
            },
        );
        assert!(evaluate_differential(&d, &caps, "orphaned rows: 76,330").is_ok());
        let err = evaluate_differential(&d, &caps, "orphaned rows: 435,600").unwrap_err();
        assert!(err.contains("delta 6"), "{err}");
        assert!(err.contains("435594 -> 435600"), "{err}");
        assert!(
            err.contains("outside the allowed bounds [-inf, -100]"),
            "{err}"
        );

        // A lower bound alone works too ("grew by at least 5").
        let up = diff(
            "orphans",
            DifferentialExpect::DeltaWithin {
                min: Some(5.0),
                max: None,
            },
        );
        assert!(evaluate_differential(&up, &caps, "435600").is_ok());
        let err = evaluate_differential(&up, &caps, "435595").unwrap_err();
        assert!(
            err.contains("outside the allowed bounds [5, +inf]"),
            "{err}"
        );
    }

    #[test]
    fn delta_within_names_which_side_was_not_numeric() {
        let d = diff(
            "n",
            DifferentialExpect::DeltaWithin {
                min: None,
                max: Some(0.0),
            },
        );
        let err = evaluate_differential(&d, &captures("n", "no digits here"), "7").unwrap_err();
        assert!(
            err.contains("baseline 'n' captured no numeric value"),
            "{err}"
        );
        let err = evaluate_differential(&d, &captures("n", "7"), "no digits here").unwrap_err();
        assert!(
            err.contains("the check output carries no numeric value"),
            "{err}"
        );
    }

    #[test]
    fn a_missing_or_failed_capture_fails_closed_with_the_reason() {
        let d = diff("gone", DifferentialExpect::Changed);
        let err = evaluate_differential(&d, &BaselineCaptures::new(), "x").unwrap_err();
        assert!(err.contains("baseline 'gone' was never captured"), "{err}");

        let mut caps = BaselineCaptures::new();
        caps.insert("gone".into(), capture("gone", "x", false));
        let err = evaluate_differential(&d, &caps, "y").unwrap_err();
        assert!(err.contains("failed at capture time"), "{err}");
    }

    #[test]
    fn first_number_reads_counters_out_of_prose() {
        assert_eq!(first_number("orphaned rows: 435,594"), Some(435_594.0));
        assert_eq!(first_number("-12.5 degrees"), Some(-12.5));
        assert_eq!(first_number("count=76330"), Some(76_330.0));
        assert_eq!(first_number("no digits"), None);
        assert_eq!(first_number(""), None);
    }

    // ---- end to end: the bead's probe --------------------------------------

    /// A fixture "system" (a counter file), a baseline capture of it, and a
    /// differential final check asserting the value decreased. Before #1067 no
    /// baseline concept parsed; now the capture pass records the before-value,
    /// the work moves the counter, and the gate decides the differential — with
    /// BOTH executions present in the results the events narrate.
    #[tokio::test]
    async fn a_counter_decrease_is_expressible_and_enforced_end_to_end() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("counter.txt"), "435594\n").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();

        let mut cap = check("orphan_rows", "cat counter.txt");
        cap.baseline = true;
        let mut gate = check("orphan_rows_decreased", "cat counter.txt");
        gate.differential = Some(diff(
            "orphan_rows",
            DifferentialExpect::DeltaWithin {
                min: None,
                max: Some(-100.0),
            },
        ));
        let contract = contract(vec![cap, gate]);
        assert!(contract.validate().is_empty());

        // Session start: the baseline pass IS the capture execution — and the
        // differential is RED here (delta 0), so this contract never reads as
        // gating nothing.
        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        assert!(baseline[0].passed, "the capture itself succeeds");
        assert!(
            !baseline[1].passed,
            "nothing has changed yet, so the differential must be red at baseline"
        );
        assert!(!baseline_gates_nothing(&baseline));
        let caps = collect_baseline_captures(&contract, &baseline);
        assert_eq!(caps.len(), 1);
        assert!(caps["orphan_rows"].output_tail.contains("435594"));

        // The "work": the fixture system's counter falls.
        std::fs::write(dir.path().join("counter.txt"), "76330\n").unwrap();

        // The gate: capture carried over (not re-run), differential decided.
        let results =
            evaluate_contract_within_baselines(&contract, &exec, &sink, None, &caps).await;
        assert_eq!(results.len(), 2, "both executions are present");
        assert!(
            results[0].output_tail.contains("435594"),
            "the capture result is the session-start one, not a re-run: {}",
            results[0].output_tail
        );
        assert!(results[1].passed, "435594 -> 76330 is a delta of -359264");
        assert!(results.iter().all(|r| r.passed));

        // And had the counter RISEN instead, the same gate refuses.
        std::fs::write(dir.path().join("counter.txt"), "500000\n").unwrap();
        let results =
            evaluate_contract_within_baselines(&contract, &exec, &sink, None, &caps).await;
        assert!(!results[1].passed);
        assert!(
            results[1]
                .output_tail
                .contains("outside the allowed bounds"),
            "{}",
            results[1].output_tail
        );
    }

    /// The control-group claim: a file the work must not touch, captured and
    /// asserted unchanged.
    #[tokio::test]
    async fn a_control_group_unchanged_claim_is_expressible_and_enforced() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("control.txt"), "tenant-b rows: 42\n").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();

        let mut cap = check("control_before", "cat control.txt");
        cap.baseline = true;
        let mut gate = check("control_unmoved", "cat control.txt");
        gate.differential = Some(diff("control_before", DifferentialExpect::Unchanged));
        let contract = contract(vec![cap, gate]);
        assert!(contract.validate().is_empty());

        let baseline = evaluate_contract_baseline(&contract, &exec).await;
        // The control-group claim is legitimately green at baseline — and the
        // capture pass compares against the value captured moments before.
        assert!(baseline.iter().all(|r| r.passed));
        let caps = collect_baseline_captures(&contract, &baseline);

        // Untouched: green.
        let results =
            evaluate_contract_within_baselines(&contract, &exec, &sink, None, &caps).await;
        assert!(results.iter().all(|r| r.passed));

        // Touched: the violation is named.
        std::fs::write(dir.path().join("control.txt"), "tenant-b rows: 41\n").unwrap();
        let results =
            evaluate_contract_within_baselines(&contract, &exec, &sink, None, &caps).await;
        assert!(!results[1].passed);
        assert!(
            results[1].output_tail.contains("control-group"),
            "{}",
            results[1].output_tail
        );
    }

    /// The capture-less signatures fail CLOSED on a differential contract: a
    /// caller that never captured cannot have its differentials silently pass.
    #[tokio::test]
    async fn without_captures_a_differential_check_fails_closed() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("counter.txt"), "1\n").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let sink = EventSink::test_sink();

        let mut cap = check("before", "cat counter.txt");
        cap.baseline = true;
        let mut gate = check("after", "cat counter.txt");
        gate.differential = Some(diff("before", DifferentialExpect::Changed));
        let contract = contract(vec![cap, gate]);

        let results = evaluate_contract(&contract, &exec, &sink).await;
        assert!(
            !results[0].passed && results[0].output_tail.contains("never captured"),
            "{}",
            results[0].output_tail
        );
        assert!(
            !results[1].passed && results[1].output_tail.contains("never captured"),
            "{}",
            results[1].output_tail
        );
    }

    /// Render names the before/after structure so the confirmation the operator
    /// reads shows the claim, not just the command.
    #[test]
    fn render_states_captures_and_differentials() {
        let mut cap = check("orphan_rows", "cat counter.txt");
        cap.baseline = true;
        let mut gate = check("decreased", "cat counter.txt");
        gate.differential = Some(diff(
            "orphan_rows",
            DifferentialExpect::DeltaWithin {
                min: None,
                max: Some(-100.0),
            },
        ));
        let rendered = contract(vec![cap, gate]).render();
        assert!(
            rendered.contains("baseline capture at session start"),
            "{rendered}"
        );
        assert!(
            rendered.contains("vs baseline 'orphan_rows': delta within [-inf, -100]"),
            "{rendered}"
        );
    }
}