car_server_core/coder/

declarative.rs

//! In-daemon execution of declarative agents, and the coder→agent build loop.
//!
//! Two pieces:
//! - [`DeclarativeAgentRunner`] runs a [`DeclarativeAgentSpec`] on an input —
//!   a model→tool loop executed entirely inside the daemon, with the tool set
//!   restricted to the spec's allowlist and policy-gated by the executor's
//!   `InspectorChain`. No external process.
//! - [`build_agent`] is the coder→agent loop: it asks the model for an agent
//!   spec that satisfies the user's intent, runs the spec's scenarios through
//!   the runner, and repairs until every scenario passes (or it gives up) —
//!   the same generate→verify→repair shape as contract derivation, so an
//!   Agent project never touches the file-editing native loop.

use crate::assistant::agent_loop::{
    compact_history_measured_with_recovery, history_budget, measure_scale, message_estimates,
    scaled_prompt_tokens, CompactionRecovery, PromptMeasure,
};
use async_trait::async_trait;
use car_engine::ToolExecutor;
use car_inference::tasks::generate::{Message, Provenance};
use car_inference::{GenerateParams, GenerateRequest};
use serde_json::Value;
use std::collections::HashSet;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

pub use car_registry::declarative::{
    ContextPolicy, DeclarativeAgentSpec, DeclarativeGoal, Scenario,
};

use super::native_loop::{InferenceFailureKind, TurnGenerationError, TurnGenerator};
use super::shell_tool::WorktreeExecutor;

/// Result of one declarative-agent run.
#[derive(Debug, Clone)]
pub struct AgentRunResult {
    pub output: String,
    pub turns: u32,
    pub tool_calls: u32,
    pub error: Option<String>,
    /// Preserves the model error for the agent builder. Ordinary invocations
    /// continue to consume `error` as operator-facing text.
    pub inference_error: Option<TurnGenerationError>,
    pub goal: Option<AgentGoalRun>,
}

#[derive(Debug, Clone)]
pub struct AgentGoalRun {
    pub check: String,
    pub max_iterations: u32,
    pub iterations: u32,
    pub met: bool,
    /// Whether the goal result came from deterministic verifier evidence.
    ///
    /// A nonzero shell exit is still grounded evidence: it proves the goal is
    /// not met yet. Keep this separate from `met` so hosts and observability do
    /// not count ordinary verifier failures as ungrounded model judgment.
    pub grounded: bool,
    pub last_exit_code: Option<i32>,
    pub last_reason: String,
}

/// One-shot log gates for a whole [`DeclarativeAgentRunner::run`] invocation.
///
/// A goal-bearing invoke re-drives `run_once` up to 50 times, and a policy
/// notice repeated 50 times is noise that trains the reader to skip it. These
/// live on the invoke, not the pass, so each says its piece once no matter how
/// many passes the verifier costs. Atomics rather than `Cell` so the futures
/// holding a reference stay `Send`.
#[derive(Default)]
struct RunNotices {
    self_managed: AtomicBool,
    unknown_window: AtomicBool,
    stale_window: AtomicBool,
}

impl RunNotices {
    /// `true` the FIRST time it is asked, `false` forever after.
    fn first(flag: &AtomicBool) -> bool {
        !flag.swap(true, Ordering::SeqCst)
    }
}

/// Filter the executor's available tool schemas to the spec's allowlist.
/// **Strict**: an empty intersection yields ZERO tools (NOT all) — a typo'd or
/// empty allowlist must never silently grant the full toolset. Denied tools
/// are removed even if allowlisted.
pub fn select_tool_defs_strict(all: &[Value], allow: &[String], deny: &[String]) -> Vec<Value> {
    all.iter()
        .filter(|d| {
            let name = d.get("name").and_then(Value::as_str).unwrap_or("");
            allow.iter().any(|a| a == name) && !deny.iter().any(|x| x == name)
        })
        .cloned()
        .collect()
}

/// Runs a declarative agent in-daemon.
pub struct DeclarativeAgentRunner<'a> {
    spec: &'a DeclarativeAgentSpec,
    generator: &'a dyn TurnGenerator,
    executor: &'a WorktreeExecutor,
    max_turns: u32,
    max_tokens_per_turn: usize,
    cancel: Option<Arc<AtomicBool>>,
    model: Option<String>,
    turn_observer: Option<&'a dyn RunTurnObserver>,
}

/// Told which model served each completed model turn of a run. The agent build
/// uses it so progress names the model running a scenario, not the one that
/// generated the spec.
#[async_trait]
trait RunTurnObserver: Send + Sync {
    async fn turn_served(&self, model_used: &str);
}

impl<'a> DeclarativeAgentRunner<'a> {
    pub fn new(
        spec: &'a DeclarativeAgentSpec,
        generator: &'a dyn TurnGenerator,
        executor: &'a WorktreeExecutor,
    ) -> Self {
        Self {
            spec,
            generator,
            executor,
            max_turns: 12,
            max_tokens_per_turn: 2048,
            cancel: None,
            model: None,
            turn_observer: None,
        }
    }

    pub fn with_cancel(mut self, cancel: Option<Arc<AtomicBool>>) -> Self {
        self.cancel = cancel;
        self
    }

    fn with_turn_observer(mut self, observer: &'a dyn RunTurnObserver) -> Self {
        self.turn_observer = Some(observer);
        self
    }

    /// Pin this invocation to an explicitly selected CAR model. `None`
    /// preserves the runner's adaptive, quality-first routing behavior.
    pub fn with_model(mut self, model: Option<String>) -> Self {
        self.model = model;
        self
    }

    fn system_prompt(&self) -> String {
        let mut p = self.spec.identity.trim().to_string();
        if !self.spec.standing_goal.trim().is_empty() {
            p.push_str("\n\nStanding goal: ");
            p.push_str(self.spec.standing_goal.trim());
        }
        p
    }

    /// Run the agent on `input`, returning its final text answer.
    pub async fn run(&self, input: &str) -> AgentRunResult {
        if self.is_cancelled() {
            return cancelled_result(0, 0, None);
        }
        // One set of notice gates for the whole invocation, so the context-policy
        // lines below fire once per invoke rather than once per goal pass.
        let notices = RunNotices::default();
        let Some(goal) = self.normalized_goal() else {
            return self.run_once(input, &notices).await;
        };

        let mut total_turns = 0u32;
        let mut total_tool_calls = 0u32;
        let mut last_output = String::new();
        let mut last_exit_code = None;
        let mut last_reason = String::new();

        for iteration in 1..=goal.max_iterations {
            if self.is_cancelled() {
                return AgentRunResult {
                    output: last_output,
                    turns: total_turns,
                    tool_calls: total_tool_calls,
                    error: Some("cancelled".into()),
                    inference_error: None,
                    goal: Some(AgentGoalRun {
                        check: goal.check,
                        max_iterations: goal.max_iterations,
                        iterations: iteration.saturating_sub(1),
                        met: false,
                        grounded: true,
                        last_exit_code,
                        last_reason: "cancelled".into(),
                    }),
                };
            }
            let directive = if last_reason.is_empty() {
                input.to_string()
            } else {
                format!(
                    "{input}\n\nThe previous deterministic goal check did not pass: \
                     {last_reason}. Keep working toward the original input until \
                     the check succeeds."
                )
            };
            let result = self.run_once(&directive, &notices).await;
            total_turns += result.turns;
            total_tool_calls += result.tool_calls;
            last_output = result.output;

            if self.is_cancelled() {
                return AgentRunResult {
                    output: last_output,
                    turns: total_turns,
                    tool_calls: total_tool_calls,
                    error: Some("cancelled".into()),
                    inference_error: None,
                    goal: Some(AgentGoalRun {
                        check: goal.check,
                        max_iterations: goal.max_iterations,
                        iterations: iteration,
                        met: false,
                        grounded: true,
                        last_exit_code,
                        last_reason: "cancelled".into(),
                    }),
                };
            }

            if let Some(error) = result.error {
                return AgentRunResult {
                    output: last_output,
                    turns: total_turns,
                    tool_calls: total_tool_calls,
                    error: Some(error),
                    inference_error: result.inference_error,
                    goal: Some(AgentGoalRun {
                        check: goal.check,
                        max_iterations: goal.max_iterations,
                        iterations: iteration,
                        met: false,
                        grounded: true,
                        last_exit_code,
                        last_reason: "agent run failed before goal check".into(),
                    }),
                };
            }

            match self.executor.run_shell(&goal.check, Some(120)).await {
                Ok(v) => {
                    let exit = v.get("exit_code").and_then(Value::as_i64).map(|n| n as i32);
                    last_exit_code = exit;
                    if exit == Some(0) {
                        return AgentRunResult {
                            output: last_output,
                            turns: total_turns,
                            tool_calls: total_tool_calls,
                            error: None,
                            inference_error: None,
                            goal: Some(AgentGoalRun {
                                check: goal.check,
                                max_iterations: goal.max_iterations,
                                iterations: iteration,
                                met: true,
                                grounded: true,
                                last_exit_code,
                                last_reason: "goal check exited 0".into(),
                            }),
                        };
                    }
                    let output = v.get("output").and_then(Value::as_str).unwrap_or("").trim();
                    // Exit 126 ("cannot execute") / 127 ("command not found"):
                    // the CHECK ITSELF is broken config, not unfinished work —
                    // re-driving the agent can never make a missing command
                    // exist, so stop at once with a defect-naming error the
                    // builder feeds back into spec repair (car#1523). Any
                    // other non-zero exit may still mean "not done yet" and
                    // keeps the retry path below, byte-for-byte.
                    if matches!(exit, Some(126) | Some(127)) {
                        last_reason = format!(
                            "goal check is not a runnable command (exit {}): {} — \
                             fix or remove goal.check",
                            exit.unwrap_or(-1),
                            truncate(output, 200)
                        );
                        return AgentRunResult {
                            output: last_output,
                            turns: total_turns,
                            tool_calls: total_tool_calls,
                            error: Some(last_reason.clone()),
                            inference_error: None,
                            goal: Some(AgentGoalRun {
                                check: goal.check,
                                max_iterations: goal.max_iterations,
                                iterations: iteration,
                                met: false,
                                grounded: true,
                                last_exit_code: exit,
                                last_reason,
                            }),
                        };
                    }
                    last_reason = if output.is_empty() {
                        format!("goal check exited {}", exit.unwrap_or(-1))
                    } else {
                        format!(
                            "goal check exited {}: {}",
                            exit.unwrap_or(-1),
                            truncate(output, 200)
                        )
                    };
                }
                Err(e) => {
                    last_reason = format!("goal check failed to run: {e}");
                    return AgentRunResult {
                        output: last_output,
                        turns: total_turns,
                        tool_calls: total_tool_calls,
                        error: Some(last_reason.clone()),
                        inference_error: None,
                        goal: Some(AgentGoalRun {
                            check: goal.check,
                            max_iterations: goal.max_iterations,
                            iterations: iteration,
                            met: false,
                            grounded: true,
                            last_exit_code,
                            last_reason,
                        }),
                    };
                }
            }
        }

        AgentRunResult {
            output: last_output,
            turns: total_turns,
            tool_calls: total_tool_calls,
            error: Some(format!(
                "goal_not_met after {} iteration(s): {}",
                goal.max_iterations, last_reason
            )),
            inference_error: None,
            goal: Some(AgentGoalRun {
                check: goal.check,
                max_iterations: goal.max_iterations,
                iterations: goal.max_iterations,
                met: false,
                grounded: true,
                last_exit_code,
                last_reason,
            }),
        }
    }

    fn is_cancelled(&self) -> bool {
        self.cancel
            .as_ref()
            .map(|flag| flag.load(Ordering::SeqCst))
            .unwrap_or(false)
    }

    fn normalized_goal(&self) -> Option<DeclarativeGoal> {
        self.spec.goal.as_ref().and_then(|goal| {
            let check = goal.check.trim();
            if check.is_empty() {
                None
            } else {
                Some(DeclarativeGoal {
                    check: check.to_string(),
                    max_iterations: goal.max_iterations.clamp(1, 50),
                })
            }
        })
    }

    async fn run_once(&self, input: &str, notices: &RunNotices) -> AgentRunResult {
        if self.is_cancelled() {
            return cancelled_result(0, 0, None);
        }
        let tools = select_tool_defs_strict(
            {
                // This run advertises the delegate surface, so it may call it.
                self.executor.advertise_delegates();
                &self.executor.all_tool_defs()
            },
            // Unlike the coding loop, this path does NOT consult
            // `permits_full_access` first, so a spec that allowlists a
            // `full_access` delegate (`http_request`, car#1073) is offered a tool
            // the per-agent gate will refuse until an operator grants the tier.
            // Left as-is deliberately: the spec author asked for that tool by
            // name, so the refusal names a permission they can go and grant,
            // rather than a capability that silently does not exist.
            &self.spec.tools,
            &self.spec.denied_tools,
        );
        let tools = if tools.is_empty() { None } else { Some(tools) };

        let mut messages = vec![
            Message::System {
                content: self.system_prompt(),
            },
            Message::User {
                content: input.to_string(),
            },
        ];

        // Who bounds this run's conversation (spec `context`). `car` — the
        // default, and what every agent written before the field gets — applies
        // the same compaction the assistant and coder loops use before each
        // model call. `self` means the spec author owns the transcript, so CAR
        // must not touch it; say so once, because a history that silently stops
        // being managed is exactly the failure the `[history compacted:` notice
        // exists to prevent in the other direction.
        let car_manages_context = self.spec.context.is_car_managed();
        if !car_manages_context && RunNotices::first(&notices.self_managed) {
            tracing::info!(
                agent = %self.spec.id,
                context = self.spec.context.as_str(),
                "CAR compaction is off for this agent (context: self); the spec owns its history"
            );
        }
        // The window compaction is measured against, seeded from a pinned model
        // when there is one and RE-RESOLVED after every call from the model that
        // actually served it (below). Adaptive routing (`model: None`) only
        // picks at call time, so turn 1 may have no window at all — which costs
        // nothing, because before that call the history is two messages and
        // cannot exceed any budget.
        let mut context_window = self
            .model
            .as_deref()
            .map(|m| self.generator.context_window(m))
            .unwrap_or(0);
        // The model this run's requests are addressed to. It starts as the
        // caller's pin (usually none) and becomes the model that served the
        // first turn, because the budget and the serving model must not be able
        // to diverge: unpinned, the window is only known AFTER a call, so a
        // large-window turn followed by a reroute would send a history sized for
        // the old model to the new one — one turn late is exactly when it
        // matters. Pinning is done only under `context: car`; an agent that
        // manages its own history keeps today's routing untouched.
        let mut route = self.model.clone();
        // Whether the ROUTE is the caller's to own. A caller-supplied pin is
        // never rewritten by this loop; an unpinned run's route is adopted from
        // whichever model serves it.
        let caller_pinned = self.model.is_some();
        // One line per pass when a caller's pin is not what served the turn.
        let mut route_divergence_logged = false;
        // What the per-message estimate cannot see: the tool definitions ride on
        // every turn. The provider's own prompt count is folded in after each
        // call, so the decision to compact runs on ground truth once there is
        // any (see `PromptMeasure`).
        // Tool-call ids whose results this run has already shortened.
        let mut shrunk_tool_results: HashSet<String> = HashSet::new();
        // Every tool-call id this run has handed out, so the next one can be
        // made distinct from all of them (see the assignment loop below).
        let mut used_call_ids: HashSet<String> = HashSet::new();
        let mut prompt_measure = PromptMeasure {
            fixed_overhead: car_inference::media_tokens::tool_defs_tokens(
                tools.as_deref().unwrap_or(&[]),
            ),
            reported: None,
        };
        let mut tool_calls_total = 0u32;
        for turn in 1..=self.max_turns {
            if self.is_cancelled() {
                return cancelled_result(turn.saturating_sub(1), tool_calls_total, None);
            }
            // Bound the running conversation BEFORE the call — an over-budget
            // history is only a failure once it is sent. Pins the system prompt
            // and the original input, drops the oldest middle turns on a turn
            // boundary, and leaves the `[history compacted:` notice. No-op on
            // turn 1, when the window is unknown, or when the history fits.
            if car_manages_context {
                // Compare CONTENT, not length, exactly as the assistant loop
                // does (agent_loop.rs): dropping one message and inserting the
                // notice in its place leaves the length identical while the
                // history is entirely different, and a stale reported count
                // then decides the next turn's compaction.
                let before_compaction = messages.clone();
                // Learn the provider-vs-estimate ratio from the history the
                // report actually described, BEFORE compaction rewrites it.
                let scale = measure_scale(&message_estimates(&messages), prompt_measure);
                // `Unrecoverable`, not the default notice: this runner binds no
                // event log and offers only the spec's allowlisted tools, so
                // telling the model to call `events_query` would promise a
                // recovery path that does not exist here.
                compact_history_measured_with_recovery(
                    &mut messages,
                    context_window,
                    prompt_measure,
                    CompactionRecovery::Unrecoverable,
                );
                // Dropping turns cannot fix a history whose ONE tool result is
                // the overflow, and the shared function's tail rule protects
                // exactly that message. Shrink what it cannot drop.
                let shrunk = shrink_oversized_tool_results(
                    &mut messages,
                    history_budget(context_window),
                    prompt_measure.fixed_overhead,
                    scale,
                    &mut shrunk_tool_results,
                );
                if shrunk > 0 {
                    tracing::info!(
                        agent = %self.spec.id,
                        tool_results_truncated = shrunk,
                        context_window,
                        "truncated oversized tool results to fit the model's context window"
                    );
                }
                if before_compaction != messages {
                    // The reported count described the pre-compaction history;
                    // the next call reports afresh.
                    prompt_measure.reported = None;
                }
            }
            // How many leading messages this request carries — the index the
            // provider's reported prompt size is attributed to next turn.
            let request_covers = messages.len();
            let req = GenerateRequest {
                prompt: input.to_string(),
                model: route.clone(),
                params: GenerateParams {
                    temperature: 0.0,
                    max_tokens: self.max_tokens_per_turn,
                    // `caller_pinned`, NOT `route.is_some()`: `strict_model`
                    // is a hard-failure switch, not a routing preference. It
                    // suppresses the on-device last-resort fallback
                    // (car-inference `should_append_local_last_resort`), which
                    // is right for a caller who named a backbone and must not
                    // be silently swapped off it — and wrong for the route this
                    // loop LEARNED, where flipping it true from turn 2 would
                    // make one transient cloud blip end an unpinned run with
                    // `inference failed` on a machine with a working local
                    // model. The learned route is still preferred (it rides in
                    // `model`); it is just allowed to degrade.
                    strict_model: caller_pinned,
                    // Deterministic tool use, not open reasoning: force thinking
                    // OFF. Hybrid-thinking models (Qwen3) otherwise burn the
                    // whole budget inside an unclosed `<think>` and return empty
                    // text — the same failure the coder's contract derivation
                    // hit. Route on the Code hint so a capable model wins.
                    thinking: car_inference::tasks::generate::ThinkingMode::Off,
                    ..Default::default()
                },
                tools: tools.clone(),
                messages: Some(messages.clone()),
                intent: Some(car_inference::IntentHint {
                    task: Some(car_inference::TaskHint::Code),
                    // A declarative agent's correctness matters more than its
                    // latency (it's verified against scenarios at build time and
                    // invoked deliberately) — run it on the most capable model.
                    prefer_quality: true,
                    ..Default::default()
                }),
                ..Default::default()
            };
            let result = match self.generator.generate_coder(req).await {
                Ok(r) => r,
                Err(error) => {
                    let message = format!("inference failed: {error}");
                    return AgentRunResult {
                        output: String::new(),
                        turns: turn,
                        tool_calls: tool_calls_total,
                        error: Some(message),
                        inference_error: Some(error),
                        goal: None,
                    };
                }
            };
            if let Some(observer) = self.turn_observer {
                observer.turn_served(&result.model_used).await;
            }

            if car_manages_context {
                // Re-resolve EVERY turn from the model that actually served it,
                // and take that value rather than the widest seen: routing can
                // fall back mid-run, and the next call must be measured against
                // the window in force for it. Latching the first non-zero window
                // would keep compacting a 5k fallback against a 200k budget —
                // the overflow this exists to prevent. The pinned case is
                // unaffected (a strict pin reports itself back).
                let resolved = self.generator.context_window(&result.model_used);
                match window_update(resolved, context_window) {
                    WindowUpdate::Adopted(window) => {
                        if window != context_window {
                            tracing::debug!(
                                agent = %self.spec.id,
                                model = %result.model_used,
                                previous_context_window = context_window,
                                context_window = window,
                                "declarative run's context window changed with the serving model"
                            );
                        }
                        context_window = window;
                    }
                    WindowUpdate::KeptLastKnown(window) => {
                        // Keeping the last known budget is the deliberate
                        // choice (losing it would unbind the run over a routing
                        // detail), but it must not be SILENT: the budget now
                        // describes a model that is no longer serving, and it
                        // may be the larger of the two.
                        if RunNotices::first(&notices.stale_window) {
                            tracing::warn!(
                                agent = %self.spec.id,
                                model = %result.model_used,
                                context_window = window,
                                "model {} has no known context window; keeping the last known \
                                 budget of {window} tokens — it may not fit the model now \
                                 serving this run. Add the model to the catalog to bound it \
                                 properly.",
                                result.model_used
                            );
                        }
                    }
                    WindowUpdate::StillUnknown => {}
                }
                // Keep the route and the budget on the SAME model. Only when
                // the caller pinned nothing: an explicit `--model` (or an alias
                // that is meant to route within a family) is the caller's
                // decision and this loop does not get to overwrite it — it only
                // says so when the engine served something else.
                if !caller_pinned {
                    if resolved != 0
                        && !result.model_used.is_empty()
                        && route.as_deref() != Some(result.model_used.as_str())
                    {
                        if route.is_some() {
                            tracing::warn!(
                                agent = %self.spec.id,
                                previous_route = route.as_deref().unwrap_or(""),
                                served = %result.model_used,
                                context_window,
                                "declarative run was served by a different model than its \
                                 pinned route; following it so the budget and the serving \
                                 model cannot diverge"
                            );
                        } else {
                            tracing::debug!(
                                agent = %self.spec.id,
                                model = %result.model_used,
                                context_window,
                                "pinning the declarative run to the model that served it"
                            );
                        }
                        route = Some(result.model_used.clone());
                    }
                } else if !route_divergence_logged
                    && !result.model_used.is_empty()
                    && route.as_deref() != Some(result.model_used.as_str())
                {
                    route_divergence_logged = true;
                    tracing::warn!(
                        agent = %self.spec.id,
                        pinned = route.as_deref().unwrap_or(""),
                        served = %result.model_used,
                        context_window,
                        "declarative run was served by a different model than the caller's \
                         pin; budgeting against the model that served it"
                    );
                }
                if context_window == 0 && RunNotices::first(&notices.unknown_window) {
                    // Loud, once per invocation: a model the catalog does not
                    // know leaves this run with NO history bound but its turn
                    // cap, and the quiet version of that is a local model
                    // overflowing its 5-10k window with nothing in the log to
                    // say why the answers got worse.
                    tracing::warn!(
                        agent = %self.spec.id,
                        model = %result.model_used,
                        max_turns = self.max_turns,
                        "compaction disabled: unknown context window for model {} \
                         — this agent's history is bounded only by its turn cap. \
                         Add the model to the catalog, or set `context: self` to \
                         own the transcript deliberately.",
                        result.model_used
                    );
                }
                // Ground truth for the next turn's decision. All three input
                // buckets: a cached prefix is billed separately but still
                // occupies the window.
                if let Some(usage) = &result.usage {
                    let input = usage.prompt_tokens
                        + usage.cache_read_input_tokens
                        + usage.cache_creation_input_tokens;
                    if input > 0 {
                        prompt_measure.reported = Some((input as usize, request_covers));
                    }
                }
            }

            if self.is_cancelled() {
                return cancelled_result(turn, tool_calls_total, None);
            }

            if result.tool_calls.is_empty() {
                return AgentRunResult {
                    output: result.text,
                    turns: turn,
                    tool_calls: tool_calls_total,
                    error: None,
                    inference_error: None,
                    goal: None,
                };
            }

            let mut calls = result.tool_calls.clone();
            for (i, call) in calls.iter_mut().enumerate() {
                // Tool-call ids must be unique across the whole RUN, not just
                // within a turn. The local tool-call parser restarts its index
                // at every completion (car-inference `tasks::generate`,
                // `parse_one_tool_call` + its per-call `idx`), so a local model
                // re-emits `call_0` turn after turn — and anything keyed by that
                // id, the shrink guard included, would treat two different
                // results as the same one.
                //
                // Rewrite only a MISSING or ALREADY-USED id. A provider whose
                // ids are genuinely unique keeps its own, because its replayed
                // continuity items (the Responses `ProviderOutputItems` this
                // runner forwards) reference those exact strings and a rewrite
                // would orphan them. Both sides of the pair — the assistant
                // record below and the `ToolResult` pushed after it — take the
                // id from this same vector, so the model always sees a matched
                // call/result pair either way.
                let unique = match &call.id {
                    Some(id) if !used_call_ids.contains(id) => id.clone(),
                    _ => {
                        let mut minted = format!("call_{turn}_{i}");
                        let mut collision = 0;
                        while used_call_ids.contains(&minted) {
                            collision += 1;
                            minted = format!("call_{turn}_{i}_{collision}");
                        }
                        minted
                    }
                };
                used_call_ids.insert(unique.clone());
                call.id = Some(unique);
            }
            result.append_assistant_history(&mut messages, calls.clone());
            for call in &calls {
                if self.is_cancelled() {
                    return cancelled_result(turn, tool_calls_total, Some(result.text.clone()));
                }
                let params = Value::Object(call.arguments.clone().into_iter().collect());
                // The allowlist already removed disallowed tools from the model's
                // view; this is the hard backstop if a name leaks in anyway.
                let (_, content) = if tools_contains(&self.spec.tools, &call.name)
                    && !self.spec.denied_tools.iter().any(|d| d == &call.name)
                {
                    match self.executor.execute(&call.name, &params).await {
                        Ok(v) => (true, v.to_string()),
                        Err(e) => (false, format!("ERROR: {e}")),
                    }
                } else {
                    (
                        false,
                        format!("ERROR: tool '{}' is not allowed for this agent", call.name),
                    )
                };
                tool_calls_total += 1;
                messages.push(Message::ToolResult {
                    tool_use_id: call.id.clone().expect("assigned above"),
                    content,
                    // The coder's tools are local: shell, file read/write, git. None
                    // reach the network, so nothing here crosses the trust boundary.
                    provenance: Provenance::Internal,
                });
            }
        }

        AgentRunResult {
            output: String::new(),
            turns: self.max_turns,
            tool_calls: tool_calls_total,
            error: Some("max_turns_exceeded".into()),
            inference_error: None,
            goal: None,
        }
    }
}

/// What a turn's window resolution means for the run's budget.
///
/// Pure, and separated from the logging, because the interesting cases are a
/// decision table and this crate has no tracing subscriber in its dev
/// dependencies — the table can be asserted directly, the emission cannot.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WindowUpdate {
    /// The catalog knows the serving model: adopt its window, larger or smaller.
    Adopted(usize),
    /// The serving model has no known window but an earlier turn's did. Keep
    /// that budget — losing it would unbind the run over a routing detail — and
    /// say so, because it now describes a model that is not serving.
    KeptLastKnown(usize),
    /// Nothing is known yet; compaction stays off and the unknown-window
    /// warning covers it.
    StillUnknown,
}

fn window_update(resolved: usize, current: usize) -> WindowUpdate {
    match (resolved, current) {
        (0, 0) => WindowUpdate::StillUnknown,
        (0, known) => WindowUpdate::KeptLastKnown(known),
        (window, _) => WindowUpdate::Adopted(window),
    }
}

/// How much of an oversized tool result survives truncation, at each end.
const TOOL_RESULT_KEEP_CHARS: usize = 600;

/// Marker left in a truncated tool result — for the MODEL's benefit only, so it
/// does not read the seam as content. It is deliberately NOT the "already
/// shrunk" test: a genuine tool output can contain this text. That guard is the
/// caller's `already_shrunk` set, keyed by the runner's own tool-call id.
const TOOL_RESULT_TRUNCATION_MARKER: &str =
    "[tool result truncated to fit the model's context window";

/// Shrink oversized tool results until the history fits `budget` — measured in
/// the same scaled accounting the compaction decision used — largest first. Returns how many were truncated; `already_shrunk` carries the
/// tool-call ids shortened on earlier turns of the same run, so each result is
/// only ever cut once and the guard cannot be spoofed by a tool output that
/// happens to contain the marker text.
///
/// Compaction alone cannot save this run. The shared function never drops into
/// the last `HISTORY_MIN_TAIL` messages, and after one tool turn a declarative
/// history is `[System, User, Assistant, ToolResult]` — every message either
/// pinned or in that tail. So a single unbounded tool result (a `read_file` of
/// a large file is the everyday case) ships whole, and on an 8k local window
/// one result can exceed the entire budget. Dropping turns cannot fix a run
/// whose ONE tool result is the overflow; shrinking that result can.
///
/// Only `ToolResult` content is touched, which by construction is never in the
/// pinned head (leading system prompts + the first user turn + any compaction
/// notice) and is never an assistant turn's text. Head and tail excerpts are
/// kept because the useful parts of a big tool output cluster at both ends, and
/// the marker names what went so the model does not read the seam as content.
fn shrink_oversized_tool_results(
    messages: &mut [Message],
    budget: usize,
    fixed_overhead: usize,
    scale: f64,
    already_shrunk: &mut HashSet<String>,
) -> usize {
    if budget == 0 {
        return 0;
    }
    // The SAME number compaction decided on, scale included. Measuring this
    // pass with the raw estimate instead would let it stop while the request is
    // still over budget in the tokens the provider bills: once a provider
    // reports 1.4× the estimate, compaction acts on 1.4× and this pass would act
    // on 1.0×, and the two would disagree about whether the history fits.
    let total = |messages: &[Message]| scaled_prompt_tokens(messages, fixed_overhead, scale);
    if total(messages) <= budget {
        return 0;
    }
    // Pick the candidates ONCE, largest first, measured in the same unit the
    // filter uses (characters — `len()` would order by bytes while the filter
    // counted chars, so a multibyte result could sort above a larger one). A
    // fixed list is also what makes this terminate: a `while over budget` loop
    // that re-scanned would spin forever the moment a candidate declined to
    // shrink.
    let mut candidates: Vec<(usize, usize, String)> = messages
        .iter()
        .enumerate()
        .filter_map(|(i, m)| match m {
            Message::ToolResult {
                tool_use_id,
                content,
                ..
            } if !already_shrunk.contains(tool_use_id) => {
                let chars = content.chars().count();
                (chars > TOOL_RESULT_KEEP_CHARS * 2).then(|| (i, chars, tool_use_id.clone()))
            }
            _ => None,
        })
        .collect();
    candidates.sort_by(|a, b| b.1.cmp(&a.1));

    let mut truncated = 0;
    for (index, _, tool_use_id) in candidates {
        if total(messages) <= budget {
            break;
        }
        if let Message::ToolResult { content, .. } = &mut messages[index] {
            if let Some(shorter) = truncate_tool_result(content) {
                *content = shorter;
                // Keyed by the tool-call id, not by looking for the marker in
                // the text: a genuine tool output can CONTAIN the marker (a
                // `read_file` of this very source file does), and a
                // content-sniffing guard would then treat a huge real result as
                // already shortened and let it through whole.
                //
                // The id is unique by assignment (see the append loop): a
                // missing or already-used id is replaced with `call_{turn}_{i}`,
                // and only a genuinely unique provider id is preserved — because
                // the Responses continuity items this runner forwards reference
                // those exact strings. Named assumption: a provider that BOTH
                // reuses call ids across turns AND emits continuity items would
                // have its duplicates renamed and its items desync. No provider
                // does both today — reuse is the local parser, which emits no
                // continuity items.
                already_shrunk.insert(tool_use_id);
                truncated += 1;
            }
        }
    }
    if total(messages) > budget {
        // Nothing left to shrink: the turn cap and the provider's own
        // truncation are what remain. Said out loud because an over-budget
        // request that ships anyway is exactly the silent failure this path
        // exists to remove.
        tracing::warn!(
            measured_prompt_tokens = total(messages),
            budget,
            tool_results_truncated = truncated,
            "declarative history is over the context budget and nothing is left to \
             shrink; the request ships as-is"
        );
    }
    truncated
}

/// Keep the first and last `TOOL_RESULT_KEEP_CHARS` characters, name what was
/// removed in between. Char-boundary safe.
///
/// `None` when truncating would not actually shrink the message. The marker is
/// ~180 characters of its own, so content just over `KEEP * 2` renders LONGER
/// than it started — a "fix" that grows the request it was called to shrink.
/// The length test is on the rendered form rather than a computed threshold
/// because the marker's own length varies with the numbers in it.
fn truncate_tool_result(content: &str) -> Option<String> {
    let chars: Vec<char> = content.chars().collect();
    debug_assert!(
        chars.len() > TOOL_RESULT_KEEP_CHARS * 2,
        "callers filter to content larger than the two kept excerpts"
    );
    // Not just the debug_assert: this is the indexing precondition below, and a
    // helper that panics when called directly is a trap for the next caller.
    if chars.len() <= TOOL_RESULT_KEEP_CHARS * 2 {
        return None;
    }
    let head: String = chars[..TOOL_RESULT_KEEP_CHARS].iter().collect();
    let tail: String = chars[chars.len() - TOOL_RESULT_KEEP_CHARS..]
        .iter()
        .collect();
    let dropped = chars.len() - TOOL_RESULT_KEEP_CHARS * 2;
    let rendered = format!(
        "{head}\n{TOOL_RESULT_TRUNCATION_MARKER}: {dropped} of {} characters removed from \
         the middle and not recoverable in this run; re-read a narrower slice if you need \
         them]\n{tail}",
        chars.len()
    );
    (rendered.chars().count() < chars.len()).then_some(rendered)
}

fn cancelled_result(turns: u32, tool_calls: u32, output: Option<String>) -> AgentRunResult {
    AgentRunResult {
        output: output.unwrap_or_default(),
        turns,
        tool_calls,
        error: Some("cancelled".into()),
        inference_error: None,
        goal: None,
    }
}

fn tools_contains(allow: &[String], name: &str) -> bool {
    allow.iter().any(|a| a == name)
}

/// Evaluate every scenario against the spec. Returns per-scenario pass/fail and
/// the failures rendered for a repair prompt.
pub struct ScenarioResults {
    pub passed: usize,
    pub total: usize,
    pub failures: Vec<String>,
    /// A serving failure that scenario repair cannot change.
    pub failure: Option<BuildFailure>,
}

impl ScenarioResults {
    pub fn all_passed(&self) -> bool {
        self.passed == self.total
    }
}

pub async fn run_scenarios(
    spec: &DeclarativeAgentSpec,
    generator: &dyn TurnGenerator,
    executor: &WorktreeExecutor,
) -> ScenarioResults {
    run_scenarios_with_progress(spec, generator, executor, 1, 1, None, &NoBuildProgress).await
}

fn cancel_requested(cancel: Option<&Arc<AtomicBool>>) -> bool {
    cancel.is_some_and(|flag| flag.load(Ordering::SeqCst))
}

/// Reports a scenario turn's serving model to the build's progress, once per
/// change, so a long scenario shows the model actually running it.
struct ScenarioTurnModels<'a> {
    progress: &'a dyn BuildAgentProgressReporter,
    attempt: u32,
    max_attempts: u32,
    scenario: u32,
    scenarios_total: u32,
    last: std::sync::Mutex<Option<String>>,
}

#[async_trait]
impl RunTurnObserver for ScenarioTurnModels<'_> {
    async fn turn_served(&self, model_used: &str) {
        let model_used = model_used.trim();
        if model_used.is_empty() {
            return;
        }
        {
            let mut last = self
                .last
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            if last.as_deref() == Some(model_used) {
                return;
            }
            *last = Some(model_used.to_string());
        }
        self.progress
            .report(BuildAgentProgressUpdate {
                phase: super::session::AgentBuildPhase::RunningScenario,
                attempt: self.attempt,
                max_attempts: self.max_attempts,
                scenario: Some(self.scenario),
                scenarios_total: Some(self.scenarios_total),
                model: BuildProgressModel::Served(model_used.to_string()),
            })
            .await;
    }
}

#[allow(clippy::too_many_arguments)]
async fn run_scenarios_with_progress(
    spec: &DeclarativeAgentSpec,
    generator: &dyn TurnGenerator,
    executor: &WorktreeExecutor,
    attempt: u32,
    max_attempts: u32,
    cancel: Option<&Arc<AtomicBool>>,
    progress: &dyn BuildAgentProgressReporter,
) -> ScenarioResults {
    let mut passed = 0;
    let mut failures = Vec::new();
    let total = spec.scenarios.len();
    for (i, scenario) in spec.scenarios.iter().enumerate() {
        if cancel_requested(cancel) {
            failures.push(format!(
                "scenario #{} not run: the build was cancelled",
                i + 1
            ));
            break;
        }
        let scenario_no = (i + 1) as u32;
        // Scenario runs are unpinned and route on their own, so the model that
        // generated the spec says nothing about the one about to serve.
        progress
            .report(BuildAgentProgressUpdate {
                phase: super::session::AgentBuildPhase::RunningScenario,
                attempt,
                max_attempts,
                scenario: Some(scenario_no),
                scenarios_total: Some(total as u32),
                model: BuildProgressModel::Clear,
            })
            .await;
        let turn_models = ScenarioTurnModels {
            progress,
            attempt,
            max_attempts,
            scenario: scenario_no,
            scenarios_total: total as u32,
            last: std::sync::Mutex::new(None),
        };
        // The session's cancel flag reaches the runner, so `coder.cancel` stops
        // an in-flight scenario at its next turn boundary.
        let runner = DeclarativeAgentRunner::new(spec, generator, executor)
            .with_cancel(cancel.cloned())
            .with_turn_observer(&turn_models);
        let result = runner.run(&scenario.input).await;
        if let Some(failure) = result
            .inference_error
            .as_ref()
            .and_then(BuildFailure::from_generation_error)
        {
            return ScenarioResults {
                passed,
                total,
                failures,
                failure: Some(failure),
            };
        }
        // Case-insensitive substring: the `expect` is a property the output
        // must contain, and small models vary capitalization freely. Exact
        // case would reject "Hello" against an expect of "hello".
        let ok = result.error.is_none()
            && result
                .output
                .to_lowercase()
                .contains(&scenario.expect.to_lowercase());
        if ok {
            passed += 1;
        } else {
            failures.push(format!(
                "scenario #{} (input {:?}) expected output containing {:?} but got {:?}{}",
                i + 1,
                scenario.input,
                scenario.expect,
                truncate(&result.output, 200),
                result
                    .error
                    .as_ref()
                    .map(|e| format!(" [error: {e}]"))
                    .unwrap_or_default()
            ));
        }
    }
    ScenarioResults {
        passed,
        total,
        failures,
        failure: None,
    }
}

fn truncate(s: &str, max: usize) -> String {
    if s.len() <= max {
        return s.to_string();
    }
    let mut end = max;
    while !s.is_char_boundary(end) {
        end -= 1;
    }
    format!("{}…", &s[..end])
}

// ---------------------------------------------------------------------------
// The coder→agent build loop
// ---------------------------------------------------------------------------

/// Tunables for [`build_agent`].
pub struct BuildAgentConfig {
    pub agent_id: String,
    pub available_tools: Vec<String>,
    pub max_attempts: u32,
}

/// What one progress transition says about the model on screen.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BuildProgressModel {
    /// Leave the displayed model as it is (before any generation has served,
    /// that is the session's requested pin).
    Keep,
    /// The step about to run routes on its own and has not served yet, so no
    /// model is known. Spec repairs and scenario runs are unpinned: the model
    /// that served the previous step says nothing about the one serving this.
    Clear,
    /// The model that served the most recent completed generation.
    Served(String),
}

/// One progress transition from the build loop. The RPC adapter persists these
/// in the coder session; other callers use the no-op reporter.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BuildAgentProgressUpdate {
    pub phase: super::session::AgentBuildPhase,
    pub attempt: u32,
    pub max_attempts: u32,
    pub scenario: Option<u32>,
    pub scenarios_total: Option<u32>,
    pub model: BuildProgressModel,
}

#[async_trait]
pub trait BuildAgentProgressReporter: Send + Sync {
    async fn report(&self, update: BuildAgentProgressUpdate);
}

struct NoBuildProgress;

#[async_trait]
impl BuildAgentProgressReporter for NoBuildProgress {
    async fn report(&self, _update: BuildAgentProgressUpdate) {}
}

/// A terminal agent-build cause that changing the generated spec cannot fix.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BuildFailure {
    Inference {
        kind: InferenceFailureKind,
        recovery: String,
    },
}

impl BuildFailure {
    fn from_generation_error(error: &TurnGenerationError) -> Option<Self> {
        error
            .terminal_inference()
            .map(|(kind, recovery)| Self::Inference { kind, recovery })
    }
}

/// Outcome of the build loop.
pub struct BuildAgentOutcome {
    /// The best spec produced (valid + scenarios pass on success; the last
    /// parseable attempt otherwise).
    pub spec: Option<DeclarativeAgentSpec>,
    pub passed: bool,
    /// Per-attempt issue summary (empty on first-try success).
    pub issues: Vec<String>,
    pub attempts: u32,
    pub failure: Option<BuildFailure>,
}

fn build_prompt(intent: &str, available_tools: &[String], feedback: &[String]) -> String {
    let mut p = format!(
        "You are designing an in-daemon CAR agent from a user's request. Output ONLY a JSON \
         object (no prose, no fences) describing the agent:\n\
         {{\n  \"name\": \"short human name\",\n  \"identity\": \"system prompt — who the agent \
         is and how it behaves\",\n  \"tools\": [\"only names from the AVAILABLE TOOLS list\"],\n  \
         \"standing_goal\": \"the agent's persistent objective\",\n  \"goal\": {{\"check\": \
         \"optional shell check run after each invocation\", \"max_iterations\": 8}},\n  \"scenarios\": [{{\"input\": \
         \"an example request\", \"expect\": \"a stable substring the correct output must \
         contain\"}}]\n}}\n\n\
         User request:\n{intent}\n\n\
         AVAILABLE TOOLS (use only these names; pick the minimal set, or [] for a pure-reasoning \
         agent):\n{}\n\n\
         Rules:\n\
         - 1 to 3 scenarios. CRITICAL: each `expect` must be the SHORTEST string that proves the \
           answer is correct — usually a single word, number, or short phrase taken from the \
           USER'S REQUEST itself. NEVER a full sentence you imagine the agent saying, and never \
           a value you haven't computed.\n\
           Example — request \"a greeter that always says hello\": a good scenario is \
           {{\"input\": \"hi\", \"expect\": \"hello\"}} (matched case-insensitively). A BAD scenario \
           invents a whole reply like \"Hello! How can I help you today?\".\n\
           Example — request \"converts Celsius to Fahrenheit\": for input \"100\" the `expect` is \
           \"212\" (you must actually compute 100*9/5+32), NOT \"273.15\" (that is Kelvin) and NOT a \
           sentence.\n\
         - `expect` is matched as a case-insensitive substring of the agent's output.\n\
         - Prefer no tools unless the task truly needs to read/write files or run commands.\n\
         - Include `goal` only when there is an obvious deterministic shell check for completion \
           (for example `test -f output.json`, `cargo test -q`, or `npm test`). Omit `goal` \
           for pure question-answering agents or vague quality checks. A goal check must be a \
           real, runnable shell command; if a previous attempt reported \"not a runnable \
           command\", remove `goal` or replace it with a real command.\n\
         - Write `identity` so the agent answers DIRECTLY and deterministically (it should perform \
           the task, not chat about it) — terse enough to reliably contain each `expect`.\n",
        if available_tools.is_empty() {
            "(none)".to_string()
        } else {
            available_tools.join(", ")
        }
    );
    if !feedback.is_empty() {
        p.push_str("\nYour previous attempt did not pass its own scenarios — revise so they do:\n");
        for f in feedback {
            p.push_str(&format!("- {f}\n"));
        }
    }
    p
}

pub(crate) fn extract_json_object(text: &str) -> Result<Value, String> {
    let start = text.find('{').ok_or("no JSON object in output")?;
    let end = text.rfind('}').ok_or("no closing brace in output")?;
    if end < start {
        return Err("malformed JSON object".into());
    }
    serde_json::from_str(&text[start..=end]).map_err(|e| format!("invalid JSON: {e}"))
}

/// Generate an agent spec from `intent`, run its scenarios, and repair until
/// they pass. Tool names the model invents that aren't in `available_tools`
/// are dropped (the allowlist can only contain real tools).
pub async fn build_agent(
    intent: &str,
    generator: &dyn TurnGenerator,
    executor: &WorktreeExecutor,
    cfg: &BuildAgentConfig,
) -> BuildAgentOutcome {
    build_agent_with_progress(intent, generator, executor, cfg, None, &NoBuildProgress).await
}

/// [`build_agent`] with progress transitions and the session's cancel flag for
/// a live coder session. A set flag ends the loop before its next attempt, and
/// an in-flight scenario stops at its next turn boundary.
pub async fn build_agent_with_progress(
    intent: &str,
    generator: &dyn TurnGenerator,
    executor: &WorktreeExecutor,
    cfg: &BuildAgentConfig,
    cancel: Option<Arc<AtomicBool>>,
    progress: &dyn BuildAgentProgressReporter,
) -> BuildAgentOutcome {
    let max = cfg.max_attempts.max(1);
    let mut feedback: Vec<String> = Vec::new();
    let mut last_spec: Option<DeclarativeAgentSpec> = None;
    let mut last_issues: Vec<String> = Vec::new();

    for attempt in 1..=max {
        if cancel_requested(cancel.as_ref()) {
            return BuildAgentOutcome {
                spec: last_spec,
                passed: false,
                issues: vec!["cancelled".into()],
                attempts: attempt - 1,
                failure: None,
            };
        }
        let (phase, model) = if attempt == 1 {
            (
                super::session::AgentBuildPhase::GeneratingSpec,
                BuildProgressModel::Keep,
            )
        } else {
            // A repair routes on its own; the previous scenario's model is stale.
            (
                super::session::AgentBuildPhase::Repairing,
                BuildProgressModel::Clear,
            )
        };
        progress
            .report(BuildAgentProgressUpdate {
                phase,
                attempt,
                max_attempts: max,
                scenario: None,
                scenarios_total: None,
                model,
            })
            .await;
        let prompt = build_prompt(intent, &cfg.available_tools, &feedback);
        let generated = match generator
            .generate_coder(GenerateRequest {
                prompt: prompt.clone(),
                params: GenerateParams {
                    temperature: 0.0,
                    // Structured JSON extraction — force thinking OFF and give
                    // room for the object (hybrid models otherwise return empty
                    // text after an unclosed `<think>`; surfaced live on
                    // Qwen3-1.7B during the agent-build shakedown).
                    max_tokens: 2048,
                    thinking: car_inference::tasks::generate::ThinkingMode::Off,
                    ..Default::default()
                },
                messages: Some(vec![Message::User { content: prompt }]),
                intent: Some(car_inference::IntentHint {
                    task: Some(car_inference::TaskHint::Code),
                    require: vec![car_inference::ModelCapability::Code],
                    // Building an agent is infrequent and quality-critical — a
                    // weak code model writes broken specs/scenarios (the live
                    // shakedown saw Qwen3-1.7B win on cost and fail). Prefer the
                    // most capable code model, not the cheapest.
                    prefer_quality: true,
                    ..Default::default()
                }),
                ..Default::default()
            })
            .await
        {
            Ok(r) => r,
            Err(error) => {
                if let Some(failure) = BuildFailure::from_generation_error(&error) {
                    return BuildAgentOutcome {
                        spec: last_spec,
                        passed: false,
                        issues: Vec::new(),
                        attempts: attempt,
                        failure: Some(failure),
                    };
                }
                last_issues = vec![format!("generation failed: {error}")];
                continue;
            }
        };
        let served = if generated.model_used.trim().is_empty() {
            BuildProgressModel::Keep
        } else {
            BuildProgressModel::Served(generated.model_used.clone())
        };
        progress
            .report(BuildAgentProgressUpdate {
                phase,
                attempt,
                max_attempts: max,
                scenario: None,
                scenarios_total: None,
                model: served,
            })
            .await;

        let value = match extract_json_object(&generated.text) {
            Ok(v) => v,
            Err(e) => {
                feedback = vec![format!(
                    "output did not parse: {e}. Return ONLY the JSON object."
                )];
                last_issues = feedback.clone();
                continue;
            }
        };

        // Build the spec; force the id, clamp tools to the real available set.
        let mut spec = match parse_spec(&value, &cfg.agent_id, &cfg.available_tools) {
            Ok(s) => s,
            Err(e) => {
                feedback = vec![e.clone()];
                last_issues = vec![e];
                continue;
            }
        };
        spec.enabled = true;

        let problems = spec.validate();
        if !problems.is_empty() {
            feedback = problems.clone();
            last_issues = problems;
            last_spec = Some(spec);
            continue;
        }
        if spec.scenarios.is_empty() {
            feedback = vec!["include at least one scenario".into()];
            last_issues = feedback.clone();
            last_spec = Some(spec);
            continue;
        }

        let results = run_scenarios_with_progress(
            &spec,
            generator,
            executor,
            attempt,
            max,
            cancel.as_ref(),
            progress,
        )
        .await;
        if let Some(failure) = results.failure {
            return BuildAgentOutcome {
                spec: Some(spec),
                passed: false,
                issues: Vec::new(),
                attempts: attempt,
                failure: Some(failure),
            };
        }
        // A scenario the user stopped proves nothing about the spec, so its red
        // result is not feedback worth a repair attempt.
        if cancel_requested(cancel.as_ref()) {
            return BuildAgentOutcome {
                spec: Some(spec),
                passed: false,
                issues: vec!["cancelled".into()],
                attempts: attempt,
                failure: None,
            };
        }
        if results.all_passed() {
            return BuildAgentOutcome {
                spec: Some(spec),
                passed: true,
                issues: Vec::new(),
                attempts: attempt,
                failure: None,
            };
        }
        feedback = results.failures.clone();
        last_issues = results.failures;
        last_spec = Some(spec);
    }

    BuildAgentOutcome {
        spec: last_spec,
        passed: false,
        issues: last_issues,
        attempts: max,
        failure: None,
    }
}

/// Parse a spec from model JSON, forcing the id and clamping the tool allowlist
/// to names that actually exist (the model can't invent tools).
fn parse_spec(
    value: &Value,
    agent_id: &str,
    available_tools: &[String],
) -> Result<DeclarativeAgentSpec, String> {
    let name = value
        .get("name")
        .and_then(Value::as_str)
        .unwrap_or("")
        .trim()
        .to_string();
    let identity = value
        .get("identity")
        .and_then(Value::as_str)
        .unwrap_or("")
        .trim()
        .to_string();
    let standing_goal = value
        .get("standing_goal")
        .and_then(Value::as_str)
        .unwrap_or("")
        .to_string();
    let tools: Vec<String> = value
        .get("tools")
        .and_then(Value::as_array)
        .map(|a| {
            a.iter()
                .filter_map(|t| t.as_str())
                .map(String::from)
                .filter(|t| available_tools.iter().any(|a| a == t))
                .collect()
        })
        .unwrap_or_default();
    let scenarios: Vec<Scenario> = value
        .get("scenarios")
        .and_then(Value::as_array)
        .map(|a| {
            a.iter()
                .filter_map(|s| {
                    Some(Scenario {
                        input: s.get("input")?.as_str()?.to_string(),
                        expect: s.get("expect")?.as_str()?.to_string(),
                    })
                })
                .collect()
        })
        .unwrap_or_default();

    Ok(DeclarativeAgentSpec {
        id: agent_id.to_string(),
        name: if name.is_empty() {
            agent_id.to_string()
        } else {
            name
        },
        identity,
        tools,
        denied_tools: Vec::new(),
        standing_goal,
        goal: parse_goal(value)?,
        cadence: None,
        scenarios,
        builder_draft: None,
        previous: None,
        enabled: true,
        // The build loop never asks the model to choose a context policy: the
        // CAR-managed default is the right answer for an agent whose author is
        // a prompt, and `self` is a deliberate hand-edit.
        context: ContextPolicy::default(),
    })
}

fn parse_goal(value: &Value) -> Result<Option<DeclarativeGoal>, String> {
    let Some(goal) = value.get("goal") else {
        return Ok(None);
    };
    if goal.is_null() {
        return Ok(None);
    }
    let obj = goal
        .as_object()
        .ok_or_else(|| "`goal` must be an object".to_string())?;
    let check = obj
        .get("check")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or_else(|| "`goal.check` must be a non-empty string".to_string())?;
    let max_iterations = obj
        .get("max_iterations")
        .and_then(Value::as_u64)
        .unwrap_or(8)
        .clamp(1, 50) as u32;
    Ok(Some(DeclarativeGoal {
        check: check.to_string(),
        max_iterations,
    }))
}

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

    use async_trait::async_trait;
    use car_inference::{GenerateRequest, InferenceResult};
    use serde_json::json;
    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
    use std::sync::{Arc, Mutex as StdMutex};

    struct Script {
        turns: Vec<InferenceResult>,
        cursor: AtomicUsize,
    }
    fn turn(text: &str, tool_calls: Value) -> InferenceResult {
        serde_json::from_value(json!({
            "text": text, "tool_calls": tool_calls,
            "trace_id": "t", "model_used": "scripted", "latency_ms": 0,
        }))
        .unwrap()
    }
    #[async_trait]
    impl TurnGenerator for Script {
        async fn generate(&self, _req: GenerateRequest) -> Result<InferenceResult, String> {
            let i = self.cursor.fetch_add(1, Ordering::SeqCst);
            self.turns
                .get(i)
                .cloned()
                .ok_or_else(|| "script exhausted".into())
        }
    }

    struct CapturingScript {
        turns: Vec<InferenceResult>,
        cursor: AtomicUsize,
        seen: Arc<StdMutex<Vec<GenerateRequest>>>,
    }

    #[async_trait]
    impl TurnGenerator for CapturingScript {
        async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
            self.seen.lock().unwrap().push(req);
            let i = self.cursor.fetch_add(1, Ordering::SeqCst);
            self.turns
                .get(i)
                .cloned()
                .ok_or_else(|| "script exhausted".into())
        }
    }

    /// A generator that never finishes: every turn returns a large assistant
    /// message and a DISTINCT tool call, so the runner's history grows by two
    /// messages per turn unless something bounds it. Records what each request
    /// actually carried.
    struct GrowingHistory {
        /// Per turn: (messages in the request, System first, the compaction
        /// notice's text when one is present).
        seen: Arc<StdMutex<Vec<(usize, bool, Option<String>)>>>,
        turn_no: AtomicUsize,
        /// What the catalog knows about this run's model. `0` = unknown.
        window: usize,
        /// A smaller window the catalog reports from the second completed call
        /// on — routing fell back to a smaller model mid-run.
        window_after_shrink: Option<usize>,
        /// The model the call reports having used — what adaptive routing
        /// picked, which the runner has no way to know before the first call.
        model_used: &'static str,
    }

    #[async_trait]
    impl TurnGenerator for GrowingHistory {
        async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
            let msgs = req
                .messages
                .as_ref()
                .expect("the runner always sets messages");
            let notice = msgs.iter().find_map(|m| match m {
                Message::System { content } if content.starts_with("[history compacted:") => {
                    Some(content.clone())
                }
                _ => None,
            });
            self.seen.lock().unwrap().push((
                msgs.len(),
                matches!(msgs.first(), Some(Message::System { .. })),
                notice,
            ));
            let n = self.turn_no.fetch_add(1, Ordering::SeqCst);
            // ~2k tokens of assistant text per turn: one turn alone dwarfs the
            // budget of the tiny window these tests use.
            let mut result = turn(
                &"x".repeat(8_000),
                json!([{
                    "id": format!("c{n}"),
                    "name": "write_file",
                    "arguments": {"path": format!("big{n}.txt"), "content": "y"}
                }]),
            );
            result.model_used = self.model_used.to_string();
            Ok(result)
        }

        fn context_window(&self, _model: &str) -> usize {
            match self.window_after_shrink {
                Some(smaller) if self.turn_no.load(Ordering::SeqCst) >= 2 => smaller,
                _ => self.window,
            }
        }
    }

    /// Run a `GrowingHistory` agent to its turn cap and return what each turn's
    /// request carried.
    async fn run_growing_history(
        spec: &DeclarativeAgentSpec,
        model: Option<&str>,
        window: usize,
    ) -> Vec<(usize, bool, Option<String>)> {
        run_growing_history_shrinking(spec, model, window, None).await
    }

    /// As above, with a window the catalog reports smaller from the second
    /// completed call on.
    async fn run_growing_history_shrinking(
        spec: &DeclarativeAgentSpec,
        model: Option<&str>,
        window: usize,
        window_after_shrink: Option<usize>,
    ) -> Vec<(usize, bool, Option<String>)> {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = GrowingHistory {
            seen: seen.clone(),
            turn_no: AtomicUsize::new(0),
            window,
            window_after_shrink,
            model_used: "tiny-local",
        };
        let runner = DeclarativeAgentRunner::new(spec, &generator, &exec)
            .with_model(model.map(String::from));
        let result = runner.run("grow the thread").await;
        assert_eq!(result.error.as_deref(), Some("max_turns_exceeded"));
        let seen = seen.lock().unwrap().clone();
        assert_eq!(seen.len(), 12, "all 12 turns generated");
        assert!(
            seen.iter().all(|(_, system_first, _)| *system_first),
            "the agent identity must stay pinned at the head of every request"
        );
        seen
    }

    /// Messages the 12th turn would carry with nothing bounding the history:
    /// the initial System + User, then an assistant message and a tool result
    /// for each of the 11 turns before it.
    const UNBOUNDED_TWELFTH_TURN: usize = 2 + 2 * 11;

    #[tokio::test]
    async fn runner_compacts_history_that_exceeds_the_model_context_budget() {
        // The gap this bead exists to close: `declagents.invoke` ran up to 12
        // turns appending history with NO window bound, so a tool-heavy agent
        // on a small model shipped an over-budget prompt and the provider
        // truncated its own task. With `context: car` (the default) the runner
        // now applies the same compaction the assistant and coder loops use.
        let spec = spec_with(vec!["write_file"]);
        assert!(spec.context.is_car_managed(), "default is CAR-managed");
        let seen = run_growing_history(&spec, Some("scripted"), 200).await;

        let max_len = seen.iter().map(|(n, _, _)| *n).max().unwrap();
        assert!(
            max_len < UNBOUNDED_TWELFTH_TURN,
            "history not bounded — max messages/turn = {max_len}"
        );
        // Not merely bounded: the existing marker is left behind, so a run that
        // degrades after compaction is distinguishable from a model that got
        // worse on its own (#815).
        let notice = seen
            .iter()
            .find_map(|(_, _, notice)| notice.clone())
            .expect("a compacted request must carry the `[history compacted:` notice");
        // …and it must not promise a recovery path this runner does not have:
        // no event log is bound to a declarative run and `events_query` is not
        // in any spec's allowlist, so the shared notice's default advice would
        // be a dead end dressed as a lifeline.
        assert!(
            !notice.contains("events_query") && !notice.contains("event log"),
            "declarative notice must not point at an events log it cannot read: {notice}"
        );
        assert!(
            notice.contains("not recoverable in this run"),
            "declarative notice must say the turns are gone: {notice}"
        );
    }

    #[tokio::test]
    async fn context_self_leaves_the_history_entirely_to_the_agent() {
        // The off switch. The author said they would manage the window; CAR
        // dropping turns underneath them would be the bug.
        let mut spec = spec_with(vec!["write_file"]);
        spec.context = ContextPolicy::SelfManaged;
        let seen = run_growing_history(&spec, Some("scripted"), 200).await;

        assert_eq!(
            seen.last().unwrap().0,
            UNBOUNDED_TWELFTH_TURN,
            "context: self must not drop a single message"
        );
        assert!(
            seen.iter().all(|(_, _, notice)| notice.is_none()),
            "context: self must never leave a compaction notice"
        );
    }

    #[tokio::test]
    async fn adaptive_routing_learns_the_window_from_the_model_that_ran() {
        // Most declarative runs pin no model — the runtime routes at call time,
        // so the window is unknowable before the first call and knowable right
        // after it. Resolving only from a pin would leave the common case
        // uncompacted while looking implemented.
        let spec = spec_with(vec!["write_file"]);
        let seen = run_growing_history(&spec, None, 200).await;

        let max_len = seen.iter().map(|(n, _, _)| *n).max().unwrap();
        assert!(
            max_len < UNBOUNDED_TWELFTH_TURN,
            "an unpinned run must still be bounded once the model is known — \
             max messages/turn = {max_len}"
        );
    }

    #[tokio::test]
    async fn a_mid_run_fallback_to_a_smaller_model_is_compacted_against_the_smaller_window() {
        // Routing can move a run onto a different model between turns. The
        // budget has to follow the model that will serve the NEXT call: a run
        // that started on a 100k window and fell back to a 200-token one must
        // not keep filling to the old budget, which is the overflow compaction
        // exists to prevent. Latching the first non-zero window looked correct
        // on a fixed-model run and was wrong exactly here.
        let spec = spec_with(vec!["write_file"]);
        let seen = run_growing_history_shrinking(&spec, Some("scripted"), 100_000, Some(200)).await;

        let max_len = seen.iter().map(|(n, _, _)| *n).max().unwrap();
        assert!(
            max_len < UNBOUNDED_TWELFTH_TURN,
            "the run must be bounded by the window in force after the fallback — \
             max messages/turn = {max_len}"
        );
        assert!(
            seen.iter().any(|(_, _, notice)| notice.is_some()),
            "the smaller window must actually have compacted something"
        );
        // The first turns ran under the large window, so nothing was dropped
        // before the fallback — the bound arrives with the smaller model, it was
        // not there all along.
        assert!(
            seen[0].2.is_none() && seen[1].2.is_none(),
            "no compaction before the window shrank"
        );
    }

    #[test]
    fn a_run_notice_fires_once_per_invocation_and_resets_with_a_new_one() {
        // The gate itself, asserted directly — the point of `RunNotices::first`
        // being a function rather than an inline `swap`. A goal-bearing invoke
        // re-drives `run_once` up to 50 times; a policy line repeated 50 times
        // trains the reader to skip it.
        let notices = RunNotices::default();
        assert!(RunNotices::first(&notices.stale_window), "first ask fires");
        assert!(
            !RunNotices::first(&notices.stale_window),
            "every later ask in the same invocation is silent"
        );
        assert!(
            RunNotices::first(&notices.unknown_window),
            "the gates are independent of one another"
        );
        assert!(!RunNotices::first(&notices.unknown_window));
        assert!(RunNotices::first(&notices.self_managed));

        let next_invocation = RunNotices::default();
        assert!(
            RunNotices::first(&next_invocation.stale_window),
            "a new invocation starts clean — once per invoke, not once per process"
        );
    }

    #[test]
    fn the_window_decision_table_is_exhaustive_and_never_silent() {
        // Three cases, and the middle one is the whole point: a zero from an
        // unresolvable model after a known turn KEEPS the last budget (losing it
        // would unbind the run) but is reported, because that budget now
        // describes a model that is not serving and may be the larger of the
        // two. The emission itself is not asserted here — car-server-core has no
        // tracing subscriber in its dev dependencies — but the arm wired to the
        // once-per-invoke warning is.
        assert_eq!(window_update(8_192, 0), WindowUpdate::Adopted(8_192));
        assert_eq!(window_update(4_096, 200_000), WindowUpdate::Adopted(4_096));
        assert_eq!(
            window_update(0, 200_000),
            WindowUpdate::KeptLastKnown(200_000),
            "a known budget is kept, and the caller warns"
        );
        assert_eq!(window_update(0, 0), WindowUpdate::StillUnknown);
    }

    #[tokio::test]
    async fn a_known_window_survives_a_model_the_catalog_cannot_resolve() {
        // `model_used` can be a string the catalog does not know — a dated
        // provider id, a local GGUF path — even on a run whose pin resolved
        // fine. Taking that 0 at face value would unbind the rest of the run on
        // a routing detail, so a 0 means "this turn taught us nothing", not
        // "there is no window". Observable form: the 200-token window learned
        // on turn 1 keeps compacting after the catalog goes blank.
        let spec = spec_with(vec!["write_file"]);
        let seen = run_growing_history_shrinking(&spec, Some("scripted"), 200, Some(0)).await;

        let max_len = seen.iter().map(|(n, _, _)| *n).max().unwrap();
        assert!(
            max_len < UNBOUNDED_TWELFTH_TURN,
            "a known window must survive an unresolvable model — max messages/turn = {max_len}"
        );
        assert!(
            seen.iter().any(|(_, _, notice)| notice.is_some()),
            "and must still be compacting"
        );
    }

    #[test]
    fn a_tool_result_too_small_to_pay_for_the_marker_is_left_alone() {
        // The marker is ~180 characters of its own, so content just over the
        // two kept excerpts renders LONGER than it started — a shrink pass that
        // grows the request it was called to shrink. The test is on the
        // rendered form, not a computed threshold, because the marker's length
        // varies with the numbers in it.
        let small = "x".repeat(TOOL_RESULT_KEEP_CHARS * 2 + 50);
        assert_eq!(truncate_tool_result(&small), None, "must not grow it");
        // Below the indexing precondition the helper returns None rather than
        // indexing out of bounds. Not asserted here on purpose: the same misuse
        // trips the `debug_assert!` that documents the caller contract, and the
        // early return is the release-build backstop, not a supported call.

        let big = "y".repeat(44_000);
        let shrunk = truncate_tool_result(&big).expect("44k must truncate");
        assert!(shrunk.chars().count() < big.chars().count());
        assert!(shrunk.contains(TOOL_RESULT_TRUNCATION_MARKER));
    }

    #[test]
    fn a_tool_output_that_quotes_the_truncation_marker_is_still_truncated() {
        // The already-shrunk guard is keyed by tool-call id, not by looking for
        // the marker in the text: a genuine tool output can contain it (a
        // `read_file` of this source file does), and a content-sniffing guard
        // would wave that huge result through whole.
        let mut messages = vec![
            Message::System {
                content: "identity".into(),
            },
            Message::User {
                content: "read the file".into(),
            },
            Message::ToolResult {
                tool_use_id: "call_1".into(),
                content: format!(
                    "{TOOL_RESULT_TRUNCATION_MARKER}: quoted by the file itself]{}",
                    "z".repeat(44_000)
                ),
                provenance: Provenance::Internal,
            },
        ];
        let mut already = HashSet::new();

        let truncated = shrink_oversized_tool_results(
            &mut messages,
            history_budget(8_192),
            0,
            1.0,
            &mut already,
        );

        assert_eq!(truncated, 1, "a marker-quoting result must still be cut");
        assert!(already.contains("call_1"), "and recorded by id");
        let Message::ToolResult { content, .. } = &messages[2] else {
            panic!("tool result");
        };
        assert!(content.chars().count() < 44_000);

        // Second pass: the id is remembered, so it is not cut again.
        let again = shrink_oversized_tool_results(
            &mut messages,
            history_budget(8_192),
            0,
            1.0,
            &mut already,
        );
        assert_eq!(again, 0, "identity guard stops a second cut");
    }

    #[tokio::test]
    async fn an_unpinned_run_pins_the_model_that_served_it_and_follows_a_reroute() {
        // Adaptive budgeting was one turn behind: the window is only known
        // AFTER a call, so a large-window turn followed by a reroute sent a
        // history sized for the old model to the new one. Once a model has
        // served a turn the run is addressed to it, and when the engine serves
        // something else anyway the budget follows the model that actually ran.
        struct Rerouting {
            /// Per turn: (the model the request was addressed to, whether that
            /// address was a HARD pin, the request's messages).
            seen: Arc<StdMutex<Vec<(Option<String>, bool, Vec<Message>)>>>,
            turn_no: AtomicUsize,
        }
        #[async_trait]
        impl TurnGenerator for Rerouting {
            async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
                let n = self.turn_no.fetch_add(1, Ordering::SeqCst);
                self.seen.lock().unwrap().push((
                    req.model.clone(),
                    req.params.strict_model,
                    req.messages
                        .clone()
                        .expect("the runner always sets messages"),
                ));
                let mut result = turn(
                    "",
                    json!([{
                        "id": format!("c{n}"),
                        "name": "read_file",
                        "arguments": {"path": "big.txt"}
                    }]),
                );
                // Turns 1-2 on the big model; the engine reroutes from turn 3.
                result.model_used = if n < 2 { "big-model" } else { "small-model" }.to_string();
                Ok(result)
            }
            fn context_window(&self, model: &str) -> usize {
                match model {
                    "big-model" => 100_000,
                    "small-model" => 4_096,
                    _ => 0,
                }
            }
        }

        let dir = tempfile::tempdir().unwrap();
        // ~6k characters per read: three of them overflow a 4k window's budget.
        std::fs::write(dir.path().join("big.txt"), "abcde\n".repeat(1_000)).unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = Rerouting {
            seen: seen.clone(),
            turn_no: AtomicUsize::new(0),
        };
        let spec = spec_with(vec!["read_file"]);

        // No caller pin: the adaptive case, which is most declarative runs.
        let _ = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .run("read big.txt")
            .await;

        let seen = seen.lock().unwrap();
        assert!(seen.len() >= 4, "at least four turns ran");
        assert_eq!(seen[0].0, None, "turn 1 is unpinned — nothing served yet");
        assert_eq!(
            seen[1].0.as_deref(),
            Some("big-model"),
            "turn 2 must be addressed to the model that served turn 1"
        );
        // …and preferring that model must not become a HARD pin. `strict_model`
        // suppresses the on-device last-resort fallback, so flipping it true on
        // a route this loop merely learned would let one transient cloud blip
        // end an unpinned run with `inference failed` on a machine with a
        // working local model.
        assert!(
            seen.iter().all(|(_, strict, _)| !*strict),
            "an unpinned run must never send strict_model"
        );
        // Turn 3 rerouted to the 4k model, so turn 4 must fit ITS budget.
        let fourth = &seen[3].2;
        let measured = car_inference::media_tokens::request_prompt_tokens(
            "",
            None,
            None,
            None,
            Some(fourth.as_slice()),
        );
        assert!(
            measured <= history_budget(4_096),
            "turn 4 must fit the rerouted model's budget: {measured} > {}",
            history_budget(4_096)
        );
    }

    /// Drive one turn against a generator that reports `multiplier` times the
    /// chars/4 estimate as its prompt size, and hand back the SECOND request's
    /// messages. The tool result is sized to sit UNDER an 8k budget by the raw
    /// estimate and OVER it once the provider's own accounting is applied —
    /// which is the whole point: the two passes must not disagree.
    const SCALE_TEST_WINDOW: usize = 200_000;

    async fn second_turn_under_reported_scale(multiplier: u64) -> Vec<Message> {
        struct Reporting {
            seen: Arc<StdMutex<Vec<Vec<Message>>>>,
            cursor: AtomicUsize,
            multiplier: u64,
        }
        #[async_trait]
        impl TurnGenerator for Reporting {
            async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
                let msgs = req
                    .messages
                    .clone()
                    .expect("the runner always sets messages");
                self.seen.lock().unwrap().push(msgs.clone());
                let estimate = car_inference::media_tokens::request_prompt_tokens(
                    "",
                    None,
                    None,
                    None,
                    Some(msgs.as_slice()),
                ) as u64;
                let i = self.cursor.fetch_add(1, Ordering::SeqCst);
                let mut result = if i == 0 {
                    turn(
                        "",
                        json!([{"id":"c1","name":"read_file","arguments":{"path":"medium.txt"}}]),
                    )
                } else {
                    turn("done", json!([]))
                };
                // Ground truth from the provider, the input the compaction
                // decision prefers over its own estimate.
                result.usage = Some(car_inference::TokenUsage {
                    prompt_tokens: estimate * self.multiplier,
                    ..Default::default()
                });
                Ok(result)
            }
            fn context_window(&self, _model: &str) -> usize {
                SCALE_TEST_WINDOW
            }
        }

        let dir = tempfile::tempdir().unwrap();
        // Sized so the second turn sits BETWEEN the two measures: under the
        // 150k-token budget by the raw chars/4 estimate (~90k), over it once the
        // provider's 2× accounting is applied (~180k). `read_file` numbers its
        // lines, so the result is wider than the file.
        std::fs::write(dir.path().join("medium.txt"), "abcdefghij\n".repeat(14_700)).unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = Reporting {
            seen: seen.clone(),
            cursor: AtomicUsize::new(0),
            multiplier,
        };
        let mut spec = spec_with(vec!["read_file"]);
        // A substantial system prompt, so the FIRST request (the one the
        // provider reports on) is dominated by the history rather than by the
        // tool definitions. `compact_history_measured` derives its scale from
        // reported-vs-estimated over the covered prefix INCLUDING the fixed
        // overhead; a two-line system prompt would leave the tool defs dwarfing
        // the prefix and the 25% gate would never open, which is a property of
        // the fixture, not of the code under test.
        spec.identity = "You answer questions carefully. ".repeat(2_500);

        let _ = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .with_model(Some("scripted".into()))
            .run("read medium.txt")
            .await;

        let seen = seen.lock().unwrap();
        assert_eq!(seen.len(), 2, "two turns");
        seen[1].clone()
    }

    #[tokio::test]
    async fn the_shrink_pass_measures_in_the_same_scale_compaction_decided_on() {
        // Compaction runs on the provider's reported prompt size; the fallback
        // shrink pass used the raw chars/4 estimate. Once a provider reports
        // more than the estimate — 1.4× was the observed case — the second pass
        // saw a history that "fits" and left the request over the real budget.
        const WINDOW: usize = SCALE_TEST_WINDOW;

        // 2×: under budget by the estimate, over it in the provider's tokens.
        let scaled = second_turn_under_reported_scale(2).await;
        let tool_result = scaled
            .iter()
            .find_map(|m| match m {
                Message::ToolResult { content, .. } => Some(content.clone()),
                _ => None,
            })
            .expect("the second turn carries the tool result");
        assert!(
            tool_result.contains(TOOL_RESULT_TRUNCATION_MARKER),
            "a history that only fits by the unscaled estimate must still be shrunk"
        );
        assert!(
            scaled_prompt_tokens(&scaled, 0, 2.0) <= history_budget(WINDOW),
            "and must land under the budget in the SAME scaled tokens: {} > {}",
            scaled_prompt_tokens(&scaled, 0, 2.0),
            history_budget(WINDOW)
        );

        // Control at 1×: the same history genuinely fits, so nothing is cut —
        // the fix must not shrink what the run can afford to keep.
        let unscaled = second_turn_under_reported_scale(1).await;
        let tool_result = unscaled
            .iter()
            .find_map(|m| match m {
                Message::ToolResult { content, .. } => Some(content.clone()),
                _ => None,
            })
            .expect("the second turn carries the tool result");
        assert!(
            scaled_prompt_tokens(&unscaled, 0, 1.0) <= history_budget(WINDOW),
            "the control only means something if the raw history genuinely fits: {} > {}",
            scaled_prompt_tokens(&unscaled, 0, 1.0),
            history_budget(WINDOW)
        );
        assert!(
            !tool_result.contains(TOOL_RESULT_TRUNCATION_MARKER),
            "a history that fits must be left alone"
        );
    }

    #[tokio::test]
    async fn a_model_that_reuses_call_0_every_turn_still_gets_every_result_truncated() {
        // The local tool-call parser restarts its index at every completion, so
        // a local model emits `call_0` turn after turn. Keying the shrink guard
        // by the model's string then makes turn 2's `call_0` look like turn 1's
        // already-shortened result, and every later oversized result ships
        // whole — an id collision replacing the content collision it fixed.
        struct RepeatIdGen {
            /// The messages each request carried.
            seen: Arc<StdMutex<Vec<Vec<Message>>>>,
        }
        #[async_trait]
        impl TurnGenerator for RepeatIdGen {
            async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
                self.seen.lock().unwrap().push(
                    req.messages
                        .clone()
                        .expect("the runner always sets messages"),
                );
                // The SAME id every turn, exactly as the local parser emits it.
                Ok(turn(
                    "",
                    json!([{"id":"call_0","name":"read_file","arguments":{"path":"big.txt"}}]),
                ))
            }
            fn context_window(&self, _model: &str) -> usize {
                8_192
            }
        }

        let dir = tempfile::tempdir().unwrap();
        // One read is ~11k tokens — bigger than the whole 6,144-token budget, so
        // every turn's fresh result is over on its own.
        std::fs::write(dir.path().join("big.txt"), "abcdefghij\n".repeat(4_000)).unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = RepeatIdGen { seen: seen.clone() };
        let spec = spec_with(vec!["read_file"]);

        let _ = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .with_model(Some("scripted".into()))
            .run("read it again")
            .await;

        let seen = seen.lock().unwrap();
        assert!(seen.len() >= 4, "at least four turns ran");
        // Turn 4 carries the three results from turns 1-3, and nothing has been
        // dropped yet (8 messages: the pinned head plus the protected tail).
        let results: Vec<(&String, &String)> = seen[3]
            .iter()
            .filter_map(|m| match m {
                Message::ToolResult {
                    tool_use_id,
                    content,
                    ..
                } => Some((tool_use_id, content)),
                _ => None,
            })
            .collect();
        assert_eq!(results.len(), 3, "three tool results by turn 4");
        for (id, content) in &results {
            assert!(
                content.contains(TOOL_RESULT_TRUNCATION_MARKER),
                "every oversized result must be truncated, not just the first: {id}"
            );
            assert_eq!(
                content.matches(TOOL_RESULT_TRUNCATION_MARKER).count(),
                1,
                "and truncated exactly once — the guard still blocks a second cut: {id}"
            );
        }
        let ids: HashSet<&String> = results.iter().map(|(id, _)| *id).collect();
        assert_eq!(
            ids.len(),
            3,
            "the runner must give colliding model ids distinct run-unique keys: {ids:?}"
        );
    }

    #[tokio::test]
    async fn a_caller_pin_stays_strict_while_a_learned_route_does_not() {
        // The two halves of the same switch. A caller who named a backbone
        // (`car agent run --model …`, an A/B arm) must get it or a loud error —
        // a silent swap to a weaker local model manufactures fake results. A
        // route this loop LEARNED carries no such promise, and `strict_model`
        // also suppresses the on-device last-resort fallback, so making it
        // strict would turn one transient cloud blip into a failed run.
        struct CapturingStrict {
            seen: Arc<StdMutex<Vec<(Option<String>, bool)>>>,
        }
        #[async_trait]
        impl TurnGenerator for CapturingStrict {
            async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
                self.seen
                    .lock()
                    .unwrap()
                    .push((req.model.clone(), req.params.strict_model));
                Ok(turn("done", json!([])))
            }
            fn context_window(&self, _model: &str) -> usize {
                100_000
            }
        }

        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let spec = spec_with(vec![]);

        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = CapturingStrict { seen: seen.clone() };
        let _ = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .with_model(Some("pinned-model".into()))
            .run("hello")
            .await;
        assert_eq!(
            seen.lock().unwrap().as_slice(),
            [(Some("pinned-model".to_string()), true)],
            "a caller's pin keeps strict_model"
        );

        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = CapturingStrict { seen: seen.clone() };
        let _ = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .run("hello")
            .await;
        assert_eq!(
            seen.lock().unwrap().as_slice(),
            [(None, false)],
            "an unpinned run never sends strict_model"
        );
    }

    #[tokio::test]
    async fn an_oversized_tool_result_is_truncated_to_fit_the_window() {
        // Compaction cannot save this run: after one tool turn the history is
        // [System, User, Assistant, ToolResult] — all of it pinned head or
        // protected tail — so the shared function drops nothing and a single
        // `read_file` of a large file ships whole. On an 8k window that one
        // result is bigger than the entire budget.
        struct WindowedCapture {
            turns: Vec<InferenceResult>,
            cursor: AtomicUsize,
            seen: Arc<StdMutex<Vec<Vec<Message>>>>,
            window: usize,
        }
        #[async_trait]
        impl TurnGenerator for WindowedCapture {
            async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
                self.seen.lock().unwrap().push(
                    req.messages
                        .clone()
                        .expect("the runner always sets messages"),
                );
                let i = self.cursor.fetch_add(1, Ordering::SeqCst);
                self.turns
                    .get(i)
                    .cloned()
                    .ok_or_else(|| "script exhausted".into())
            }
            fn context_window(&self, _model: &str) -> usize {
                self.window
            }
        }

        const WINDOW: usize = 8_192;
        let dir = tempfile::tempdir().unwrap();
        // ~40k characters: an ordinary source file, ~10k tokens, well past the
        // 6,144-token budget of an 8k window.
        std::fs::write(dir.path().join("big.txt"), "abcdefghij\n".repeat(4_000)).unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let generator = WindowedCapture {
            turns: vec![
                turn(
                    "",
                    json!([{"id":"c1","name":"read_file","arguments":{"path":"big.txt"}}]),
                ),
                turn("done", json!([])),
            ],
            cursor: AtomicUsize::new(0),
            seen: seen.clone(),
            window: WINDOW,
        };
        let spec = spec_with(vec!["read_file"]);

        let result = DeclarativeAgentRunner::new(&spec, &generator, &exec)
            .with_model(Some("scripted".into()))
            .run("read big.txt")
            .await;
        assert_eq!(result.output, "done");

        let seen = seen.lock().unwrap();
        assert_eq!(seen.len(), 2, "two turns");
        let second = &seen[1];
        let tool_result = second
            .iter()
            .find_map(|m| match m {
                Message::ToolResult { content, .. } => Some(content.clone()),
                _ => None,
            })
            .expect("the second turn carries the tool result");
        assert!(
            tool_result.contains(TOOL_RESULT_TRUNCATION_MARKER),
            "the oversized tool result must say it was truncated"
        );
        assert!(
            tool_result.contains("not recoverable in this run"),
            "and must not imply the middle can be recovered: {}",
            &tool_result[..tool_result.len().min(400)]
        );
        let measured = car_inference::media_tokens::request_prompt_tokens(
            "",
            None,
            None,
            None,
            Some(second.as_slice()),
        );
        assert!(
            measured <= history_budget(WINDOW),
            "the second request must fit the budget: {measured} > {}",
            history_budget(WINDOW)
        );
    }

    #[tokio::test]
    async fn an_unknown_context_window_leaves_the_history_unbounded_and_says_so() {
        // A model missing from the catalog resolves to 0, which disables
        // compaction — the honest behavior (there is no window to compact
        // against), and the reason the runner logs a loud warning on the first
        // turn instead of leaving the operator to infer it from degraded
        // answers. The warning is log-only; the observable contract is that
        // nothing is silently dropped.
        let spec = spec_with(vec!["write_file"]);
        let seen = run_growing_history(&spec, Some("unknown-model"), 0).await;

        assert_eq!(
            seen.last().unwrap().0,
            UNBOUNDED_TWELFTH_TURN,
            "an unknown window must not fabricate a budget"
        );
    }

    fn spec_with(tools: Vec<&str>) -> DeclarativeAgentSpec {
        DeclarativeAgentSpec {
            id: "t".into(),
            name: "T".into(),
            identity: "You answer.".into(),
            tools: tools.into_iter().map(String::from).collect(),
            denied_tools: vec![],
            standing_goal: "help".into(),
            goal: None,
            cadence: None,
            scenarios: vec![],
            builder_draft: None,
            previous: None,
            enabled: true,
            context: ContextPolicy::default(),
        }
    }

    #[test]
    fn strict_allowlist_empty_intersection_is_zero_tools() {
        let all = WorktreeExecutor::tool_defs();
        assert!(!all.is_empty());
        // Allowlist that matches nothing → ZERO, never all.
        assert!(select_tool_defs_strict(&all, &["nonexistent".into()], &[]).is_empty());
        // Empty allowlist → zero.
        assert!(select_tool_defs_strict(&all, &[], &[]).is_empty());
        // A real name → exactly that one.
        let sel = select_tool_defs_strict(&all, &["read_file".into()], &[]);
        assert_eq!(sel.len(), 1);
        assert_eq!(sel[0]["name"], "read_file");
        // Denied even if allowed.
        assert!(
            select_tool_defs_strict(&all, &["read_file".into()], &["read_file".into()]).is_empty()
        );
    }

    #[tokio::test]
    async fn runner_returns_text_answer_with_no_tools() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![turn("the answer is 42", json!([]))],
            cursor: AtomicUsize::new(0),
        };
        let spec = spec_with(vec![]);
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("what is the answer?").await;
        assert_eq!(r.output, "the answer is 42");
        assert_eq!(r.tool_calls, 0);
        assert!(r.error.is_none());
    }

    #[tokio::test]
    async fn runner_executes_an_allowed_tool() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("data.txt"), "secret content").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                turn(
                    "",
                    json!([{"id":"c1","name":"read_file","arguments":{"path":"data.txt"}}]),
                ),
                turn("the file says secret content", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let spec = spec_with(vec!["read_file"]);
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("read data.txt").await;
        assert!(r.output.contains("secret content"));
        assert_eq!(r.tool_calls, 1);
    }

    #[tokio::test]
    async fn runner_replays_managed_responses_continuity_on_second_turn() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("data.txt"), "secret content").unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let reasoning = json!({
            "type": "reasoning",
            "id": "rs_coder",
            "status": "completed",
            "summary": [{"type": "summary_text", "text": "safe"}],
            "encrypted_content": "opaque-coder",
        });
        let mut first = turn(
            "reading",
            json!([{"id":"c1","name":"read_file","arguments":{"path":"data.txt"}}]),
        );
        first.provider_output_items = vec![reasoning.clone()];
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let script = CapturingScript {
            turns: vec![first, turn("done", json!([]))],
            cursor: AtomicUsize::new(0),
            seen: seen.clone(),
        };
        let spec = spec_with(vec!["read_file"]);
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);

        let result = runner.run("read data.txt").await;

        assert_eq!(result.output, "done");
        assert!(!result.output.contains("opaque-coder"));
        let seen = seen.lock().unwrap();
        let second = seen[1].messages.as_ref().expect("second-turn history");
        assert!(matches!(
            &second[2],
            Message::ProviderOutputItems { protocol, items }
                if protocol == car_inference::protocol::OPENAI_RESPONSES_PROTOCOL
                    && items == &vec![reasoning]
        ));
        assert!(matches!(
            &second[3],
            Message::Assistant { content, .. } if content == "reading"
        ));
        assert!(matches!(&second[4], Message::ToolResult { .. }));
    }

    #[tokio::test]
    async fn runner_blocks_a_disallowed_tool_even_if_the_model_calls_it() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        // Agent allows only read_file, but the model tries write_file.
        let script = Script {
            turns: vec![
                turn(
                    "",
                    json!([{"id":"c1","name":"write_file","arguments":{"path":"x","content":"y"}}]),
                ),
                turn("done", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let spec = spec_with(vec!["read_file"]);
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let _ = runner.run("write a file").await;
        // The disallowed write must not have happened.
        assert!(!dir.path().join("x").exists(), "disallowed tool executed");
    }

    #[tokio::test]
    async fn runner_redrives_until_manifest_goal_check_passes() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                turn("not done yet", json!([])),
                turn(
                    "",
                    json!([{"id":"w1","name":"write_file","arguments":{"path":"done.txt","content":"ok"}}]),
                ),
                turn("done", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let mut spec = spec_with(vec!["write_file"]);
        spec.goal = Some(DeclarativeGoal {
            check: crate::coder::test_cmds::file_exists("done.txt"),
            max_iterations: 3,
        });
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("create done.txt").await;

        assert_eq!(r.output, "done");
        assert!(r.error.is_none(), "{:?}", r.error);
        assert_eq!(r.turns, 3);
        assert_eq!(r.tool_calls, 1);
        assert_eq!(
            std::fs::read_to_string(dir.path().join("done.txt")).unwrap(),
            "ok"
        );
        let goal = r.goal.expect("goal audit is present");
        assert!(goal.met, "{goal:?}");
        assert!(goal.grounded, "{goal:?}");
        assert_eq!(goal.iterations, 2);
        assert_eq!(goal.last_exit_code, Some(0));
    }

    #[tokio::test]
    async fn runner_reports_error_when_manifest_goal_never_passes() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                turn("still missing", json!([])),
                turn("still missing", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let mut spec = spec_with(vec![]);
        spec.goal = Some(DeclarativeGoal {
            check: crate::coder::test_cmds::file_exists("done.txt"),
            max_iterations: 2,
        });
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("create done.txt").await;

        assert!(r.error.as_deref().unwrap_or("").contains("goal_not_met"));
        let goal = r.goal.expect("goal audit is present");
        assert!(!goal.met);
        assert!(
            goal.grounded,
            "a deterministic nonzero shell exit is grounded evidence, not model judgment"
        );
        assert_eq!(goal.iterations, 2);
        assert_eq!(goal.last_exit_code, Some(1));
    }

    // Exit 127 is /bin/sh's "command not found". Windows' cmd reports a
    // missing command as 9009, which this fix deliberately does not treat
    // (car#1523 names it a follow-up), so the fixture is Unix-only.
    #[cfg(unix)]
    #[tokio::test]
    async fn runner_stops_once_when_goal_check_is_not_a_runnable_command() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        // Eight turns: the goal's full retry budget below. The old loop
        // burned every one of them re-driving the agent against a broken
        // check, so a regression fails on the iteration and cursor
        // assertions with all eight retries observed, not on an exhausted
        // script.
        let script = Script {
            turns: (0..8).map(|_| turn("working on it", json!([]))).collect(),
            cursor: AtomicUsize::new(0),
        };
        let mut spec = spec_with(vec![]);
        spec.goal = Some(DeclarativeGoal {
            check: "definitely-not-a-real-command-xyz".into(),
            max_iterations: 8,
        });
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("do the work").await;

        let error = r.error.as_deref().unwrap_or_default();
        assert!(
            error.contains("not a runnable command"),
            "error must name the defect: {error}"
        );
        assert!(error.contains("fix or remove goal.check"));
        let goal = r.goal.expect("goal audit is present");
        assert!(!goal.met);
        assert!(
            goal.grounded,
            "a deterministic shell exit is grounded evidence, not model judgment"
        );
        assert_eq!(goal.iterations, 1);
        assert_eq!(goal.last_exit_code, Some(127));
        assert_eq!(
            script.cursor.load(Ordering::SeqCst),
            1,
            "a broken check must not re-drive the agent"
        );
    }

    // Regression guard: only 126/127-style "cannot run" exits stop early;
    // plain exit 1 still means "not done yet" and keeps the full retry budget.
    // `exit 1` is a builtin of both sh and cmd (crate::coder::test_cmds::FAIL).
    #[tokio::test]
    async fn runner_still_retries_a_goal_check_that_exits_1() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: (0..8).map(|_| turn("not done yet", json!([]))).collect(),
            cursor: AtomicUsize::new(0),
        };
        let mut spec = spec_with(vec![]);
        spec.goal = Some(DeclarativeGoal {
            check: crate::coder::test_cmds::FAIL.to_string(),
            max_iterations: 8,
        });
        let runner = DeclarativeAgentRunner::new(&spec, &script, &exec);
        let r = runner.run("keep working").await;

        assert!(r.error.as_deref().unwrap_or("").contains("goal_not_met"));
        let goal = r.goal.expect("goal audit is present");
        assert!(!goal.met);
        assert_eq!(
            goal.iterations, 8,
            "exit 1 means 'not done yet', not broken config — full retry budget"
        );
        assert_eq!(goal.last_exit_code, Some(1));
    }

    #[tokio::test]
    async fn runner_honors_cancel_before_manifest_goal_redrive() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let cancel = Arc::new(AtomicBool::new(false));
        let script = Script {
            turns: vec![
                turn("still missing", json!([])),
                turn("should not run", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let mut spec = spec_with(vec![]);
        spec.goal = Some(DeclarativeGoal {
            check: crate::coder::test_cmds::file_exists("done.txt"),
            max_iterations: 3,
        });
        let runner =
            DeclarativeAgentRunner::new(&spec, &script, &exec).with_cancel(Some(cancel.clone()));

        cancel.store(true, Ordering::SeqCst);
        let r = runner.run("create done.txt").await;

        assert_eq!(r.error.as_deref(), Some("cancelled"));
        assert_eq!(r.turns, 0);
        assert_eq!(script.cursor.load(Ordering::SeqCst), 0);
    }

    #[test]
    fn build_prompt_preserves_a_400_character_description_as_the_spec_source() {
        let mut description = "Build an agent whose identity, standing goal, and scenarios follow this complete request: ".to_string();
        description.push_str(&"z".repeat(400 - description.len()));
        assert_eq!(description.chars().count(), 400);

        let prompt = build_prompt(&description, &["read_file".into()], &[]);

        assert!(prompt.contains(&format!("User request:\n{description}\n\nAVAILABLE TOOLS")));
        assert!(prompt.contains("\"identity\""));
        assert!(prompt.contains("\"standing_goal\""));
        assert!(prompt.contains("\"scenarios\""));
    }

    struct TypedFailureScript {
        spec: Option<InferenceResult>,
        error: super::super::native_loop::TurnGenerationError,
        calls: AtomicUsize,
    }

    #[async_trait]
    impl TurnGenerator for TypedFailureScript {
        async fn generate(&self, req: GenerateRequest) -> Result<InferenceResult, String> {
            self.generate_coder(req)
                .await
                .map_err(|error| error.to_string())
        }

        async fn generate_coder(
            &self,
            req: GenerateRequest,
        ) -> Result<InferenceResult, super::super::native_loop::TurnGenerationError> {
            self.calls.fetch_add(1, Ordering::SeqCst);
            if req.prompt.starts_with("You are designing") {
                if let Some(spec) = &self.spec {
                    return Ok(spec.clone());
                }
            }
            Err(self.error.clone())
        }
    }

    fn local_resource_failure() -> super::super::native_loop::TurnGenerationError {
        super::super::native_loop::TurnGenerationError::NonRetryableInference {
            kind: super::super::native_loop::InferenceFailureKind::LocalResourceBlocked,
            recovery: "Close memory-heavy apps or choose a smaller model.".into(),
        }
    }

    #[tokio::test]
    async fn build_agent_stops_after_one_spec_generation_resource_refusal() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = TypedFailureScript {
            spec: None,
            error: local_resource_failure(),
            calls: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "blocked".into(),
            available_tools: vec![],
            max_attempts: 3,
        };

        let outcome = build_agent("intent", &script, &exec, &cfg).await;

        assert_eq!(outcome.attempts, 1, "a resource refusal cannot be repaired");
        assert_eq!(script.calls.load(Ordering::SeqCst), 1, "no retry");
        assert_eq!(
            outcome.failure,
            Some(BuildFailure::Inference {
                kind: InferenceFailureKind::LocalResourceBlocked,
                recovery: "Close memory-heavy apps or choose a smaller model.".into(),
            })
        );
        assert!(outcome.issues.is_empty(), "no repair feedback is built");
    }

    #[tokio::test]
    async fn build_agent_stops_when_a_scenario_turn_has_a_resource_refusal() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = TypedFailureScript {
            spec: Some(turn(
                r#"{"name":"Greeter","identity":"Greet.","tools":[],
                    "standing_goal":"greet","scenarios":[{"input":"hi","expect":"hello"}]}"#,
                json!([]),
            )),
            error: local_resource_failure(),
            calls: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "blocked".into(),
            available_tools: vec![],
            max_attempts: 3,
        };

        let outcome = build_agent("intent", &script, &exec, &cfg).await;

        assert_eq!(outcome.attempts, 1, "a scenario refusal is not a mismatch");
        assert_eq!(
            script.calls.load(Ordering::SeqCst),
            2,
            "one spec turn and one scenario turn, with no repair"
        );
        assert_eq!(
            outcome.failure,
            Some(BuildFailure::Inference {
                kind: InferenceFailureKind::LocalResourceBlocked,
                recovery: "Close memory-heavy apps or choose a smaller model.".into(),
            })
        );
        assert!(
            outcome.issues.is_empty(),
            "the refusal is not mismatch feedback"
        );
    }

    /// The producer's own sentence, rebuilt from `InferenceError` rather than
    /// copied, so a reworded message in car-inference fails here instead of
    /// letting the builder's terminal screen drift away from Chat's.
    fn missing_provider_key_recovery() -> String {
        car_inference::InferenceError::ProviderKeyMissing {
            provider: "openrouter".into(),
            model: "openrouter/auto".into(),
            env_vars: vec!["OPENROUTER_API_KEY".into()],
            message: "OpenRouter requires a key — run `car keys set openrouter` or connect \
                      your OpenRouter account in CarHost"
                .into(),
        }
        .to_string()
    }

    /// The spec generated, and the FIRST scenario turn found no provider key.
    /// Nothing about the next two attempts sets a key that was never set, so
    /// the build has to end here — and the half-run agent is a configuration
    /// casualty, not a scenario mismatch that repair feedback could fix.
    #[tokio::test]
    async fn build_agent_stops_when_a_scenario_turn_has_no_provider_key() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let recovery = missing_provider_key_recovery();
        let script = TypedFailureScript {
            spec: Some(turn(
                r#"{"name":"Greeter","identity":"Greet.","tools":[],
                    "standing_goal":"greet","scenarios":[{"input":"hi","expect":"hello"}]}"#,
                json!([]),
            )),
            error: TurnGenerationError::NonRetryableInference {
                kind: InferenceFailureKind::ProviderKeyMissing,
                recovery: recovery.clone(),
            },
            calls: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "keyless".into(),
            available_tools: vec![],
            max_attempts: 3,
        };

        let outcome = build_agent("intent", &script, &exec, &cfg).await;

        assert_eq!(
            outcome.attempts, 1,
            "a key that was never set cannot appear on attempt two"
        );
        assert_eq!(
            script.calls.load(Ordering::SeqCst),
            2,
            "one spec turn and one scenario turn, with no repair"
        );
        assert_eq!(
            outcome.failure,
            Some(BuildFailure::Inference {
                kind: InferenceFailureKind::ProviderKeyMissing,
                recovery,
            })
        );
        assert!(
            outcome.issues.is_empty(),
            "a missing key is not mismatch feedback"
        );
    }

    #[tokio::test]
    async fn build_agent_still_retries_a_transient_generation_error() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = TypedFailureScript {
            spec: None,
            error: TurnGenerationError::Other("temporary provider failure".into()),
            calls: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "retry".into(),
            available_tools: vec![],
            max_attempts: 3,
        };

        let outcome = build_agent("intent", &script, &exec, &cfg).await;

        assert_eq!(outcome.attempts, 3);
        assert_eq!(script.calls.load(Ordering::SeqCst), 3);
        assert_eq!(outcome.failure, None);
        assert_eq!(
            outcome.issues,
            vec!["generation failed: temporary provider failure"]
        );
    }

    #[tokio::test]
    async fn build_agent_stops_on_credential_unavailable() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = TypedFailureScript {
            spec: None,
            error: TurnGenerationError::NonRetryableInference {
                kind: InferenceFailureKind::CredentialUnavailable,
                recovery: "Sign in again, then retry.".into(),
            },
            calls: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "signed-out".into(),
            available_tools: vec![],
            max_attempts: 3,
        };

        let outcome = build_agent("intent", &script, &exec, &cfg).await;

        assert_eq!(outcome.attempts, 1);
        assert_eq!(script.calls.load(Ordering::SeqCst), 1);
        assert_eq!(
            outcome.failure,
            Some(BuildFailure::Inference {
                kind: InferenceFailureKind::CredentialUnavailable,
                recovery: "Sign in again, then retry.".into(),
            })
        );
    }

    #[tokio::test]
    async fn build_agent_generates_then_passes_scenarios() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        // Turn 1: the agent spec (a greeter with one scenario).
        // Turn 2: the scenario run — agent answers containing "hello".
        let script = Script {
            turns: vec![
                turn(
                    r#"{"name":"Greeter","identity":"You greet people warmly.","tools":[],
                        "standing_goal":"greet","scenarios":[{"input":"hi","expect":"hello"}]}"#,
                    json!([]),
                ),
                turn("hello there, friend!", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "greeter".into(),
            available_tools: vec!["read_file".into(), "write_file".into()],
            max_attempts: 3,
        };
        let outcome = build_agent("make a friendly greeter", &script, &exec, &cfg).await;
        assert!(outcome.passed, "issues: {:?}", outcome.issues);
        let spec = outcome.spec.unwrap();
        assert_eq!(spec.id, "greeter");
        assert_eq!(spec.name, "Greeter");
        assert_eq!(spec.scenarios.len(), 1);
    }

    #[tokio::test]
    async fn build_agent_drops_invented_tool_names() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                turn(
                    r#"{"name":"X","identity":"You help.","tools":["send_email","read_file"],
                        "standing_goal":"g","scenarios":[{"input":"q","expect":"a"}]}"#,
                    json!([]),
                ),
                turn("answer: a", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "x".into(),
            available_tools: vec!["read_file".into()],
            max_attempts: 2,
        };
        let outcome = build_agent("intent", &script, &exec, &cfg).await;
        assert!(outcome.passed);
        // send_email isn't a real tool → dropped; read_file kept.
        assert_eq!(outcome.spec.unwrap().tools, vec!["read_file".to_string()]);
    }

    #[tokio::test]
    async fn build_agent_parses_optional_goal_contract() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                turn(
                    &json!({
                        "name":"Writer","identity":"You write the requested file.","tools":["write_file"],
                        "standing_goal":"write files",
                        // Surrounding whitespace exercises the parser's trim.
                        "goal":{"check": format!(" {} ", crate::coder::test_cmds::file_exists("done.txt")),
                                "max_iterations":99},
                        "scenarios":[{"input":"make it","expect":"done"}]
                    })
                    .to_string(),
                    json!([]),
                ),
                turn(
                    "",
                    json!([{"id":"w1","name":"write_file","arguments":{"path":"done.txt","content":"ok"}}]),
                ),
                turn("done", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "writer".into(),
            available_tools: vec!["write_file".into()],
            max_attempts: 1,
        };
        let outcome = build_agent("make a file writer", &script, &exec, &cfg).await;
        assert!(outcome.passed, "issues: {:?}", outcome.issues);
        let goal = outcome.spec.unwrap().goal.expect("goal parsed");
        assert_eq!(goal.check, crate::coder::test_cmds::file_exists("done.txt"));
        assert_eq!(goal.max_iterations, 50);
    }

    #[tokio::test]
    async fn build_agent_repairs_a_failing_scenario() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let script = Script {
            turns: vec![
                // Attempt 1 spec.
                turn(
                    r#"{"name":"A","identity":"v1","tools":[],"standing_goal":"g","scenarios":[{"input":"q","expect":"RIGHT"}]}"#,
                    json!([]),
                ),
                // Scenario run for attempt 1 → wrong.
                turn("WRONG", json!([])),
                // Attempt 2 spec (repaired).
                turn(
                    r#"{"name":"A","identity":"v2","tools":[],"standing_goal":"g","scenarios":[{"input":"q","expect":"RIGHT"}]}"#,
                    json!([]),
                ),
                // Scenario run for attempt 2 → right.
                turn("the RIGHT answer", json!([])),
            ],
            cursor: AtomicUsize::new(0),
        };
        let cfg = BuildAgentConfig {
            agent_id: "a".into(),
            available_tools: vec![],
            max_attempts: 3,
        };
        let outcome = build_agent("intent", &script, &exec, &cfg).await;
        assert!(outcome.passed);
        assert_eq!(outcome.attempts, 2);
        assert_eq!(outcome.spec.unwrap().identity, "v2");
    }

    // Attempt 1's spec carries a goal.check that is not a real command; the
    // scenario must fail with the defect error after one iteration, and
    // attempt 2's generation prompt must carry that text back to the model.
    // Unix-only like the runner fixture above: /bin/sh reports 127, Windows'
    // cmd reports 9009.
    #[cfg(unix)]
    #[tokio::test]
    async fn build_agent_feeds_a_not_runnable_goal_back_into_the_next_attempt() {
        let dir = tempfile::tempdir().unwrap();
        let exec = WorktreeExecutor::new(dir.path());
        let seen = Arc::new(StdMutex::new(Vec::new()));
        let script = CapturingScript {
            turns: vec![
                // Attempt 1 spec: goal.check is prose-shaped, not a command.
                turn(
                    r#"{"name":"A","identity":"v1","tools":[],"standing_goal":"g",
                        "goal":{"check":"definitely-not-a-real-command-xyz","max_iterations":8},
                        "scenarios":[{"input":"q","expect":"RIGHT"}]}"#,
                    json!([]),
                ),
                // Scenario run for attempt 1: the output matches `expect`, but
                // the broken goal check fails the scenario after one iteration.
                turn("the RIGHT answer", json!([])),
                // Attempt 2 spec (repaired: `goal` removed).
                turn(
                    r#"{"name":"A","identity":"v2","tools":[],"standing_goal":"g","scenarios":[{"input":"q","expect":"RIGHT"}]}"#,
                    json!([]),
                ),
                // Scenario run for attempt 2.
                turn("the RIGHT answer", json!([])),
            ],
            cursor: AtomicUsize::new(0),
            seen: seen.clone(),
        };
        let cfg = BuildAgentConfig {
            agent_id: "a".into(),
            available_tools: vec![],
            max_attempts: 3,
        };
        let outcome = build_agent("intent", &script, &exec, &cfg).await;
        assert!(outcome.passed, "issues: {:?}", outcome.issues);
        assert_eq!(outcome.attempts, 2);

        // Spec-generation prompts open with the design preamble; scenario-run
        // requests carry the scenario input instead, so this filter separates
        // the two request kinds sharing one generator.
        let prompts: Vec<String> = seen
            .lock()
            .unwrap()
            .iter()
            .map(|req| req.prompt.clone())
            .filter(|p| p.starts_with("You are designing"))
            .collect();
        assert_eq!(prompts.len(), 2, "exactly two spec-generation prompts");
        assert!(
            !prompts[0].contains("goal check is not a runnable command"),
            "attempt 1 has no feedback to carry yet"
        );
        assert!(
            prompts[1].contains("goal check is not a runnable command"),
            "attempt 2's generation prompt must carry attempt 1's defect text"
        );
        assert!(
            prompts[1].contains("definitely-not-a-real-command-xyz"),
            "the feedback must name the broken check so the model can repair it"
        );
    }
}