harness_loop/

lib.rs

//! ReAct agent loop with self-correction.
//!
//! Minimal v0.0.1 implementation:
//! - Applies guides once at the start.
//! - Sends `Context` (with `tools`) to the model.
//! - Dispatches each returned tool call via [`ToolRegistry`].
//! - Runs `Sensor::SelfCorrect` sensors after each action; auto-fix patches are
//!   applied directly to the world, blocking signals are fed back to the model.
//! - Stops when the model returns no tool calls, or when `policy.max_iters` is hit.

pub mod acceptance;
pub mod goal;
pub mod learning;
pub mod memory_layer;
#[cfg(feature = "otel")]
pub mod otel;
pub mod profile_guide;
pub mod recall_layer;
pub mod receipt;
pub mod registry;
pub mod seal;
pub use acceptance::{Acceptance, FilesExist, NonEmptyAnswer, Verdict};
pub use goal::{Goal, GoalStore, Phase, PhaseStatus};
pub use receipt::{Receipt, ReceiptBuilder};
pub use seal::{SealBreach, SealSet};
pub mod replay;
pub mod subagent;
pub mod telemetry;

pub use learning::*;
pub use memory_layer::*;
pub mod boundary_guide;
pub use boundary_guide::*;
pub use profile_guide::*;
pub use recall_layer::*;
pub use registry::*;
pub use replay::*;
pub use subagent::*;
pub use telemetry::*;

use harness_compactor::{CALIBRATION_KEY, DefaultCompactor};
use harness_core::{
    Action, Block, CompactionStage, Compactor, Context, Event, Guide, HarnessError, HookOutcome,
    Model, ModelDelta, ModelOutput, ResponseFormat, Sensor, SessionSource, SignalSet, Stage,
    StopReason, Task, ToolCall, ToolResult, Turn, TurnRole, Usage, World,
};
use harness_hooks::HookBus;
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

/// Governs the loop's stuck-detector. When the model repeats the *same* tool
/// call (name + args) round after round without making progress, the loop first
/// nudges it to change approach, then terminates cleanly with [`Outcome::Stuck`]
/// rather than burning the rest of the budget spinning on a loop.
///
/// Enabled by default with conservative thresholds — the calls must be
/// *byte-identical*, so genuine "read the same file twice" work never trips it.
#[derive(Debug, Clone)]
pub struct StuckPolicy {
    pub enabled: bool,
    /// Consecutive identical tool-call rounds before injecting a "you are
    /// repeating yourself, change your approach" feedback signal.
    pub nudge_after: u32,
    /// Consecutive identical rounds before terminating with [`Outcome::Stuck`].
    pub abort_after: u32,
}

impl Default for StuckPolicy {
    fn default() -> Self {
        Self {
            enabled: true,
            nudge_after: 3,
            abort_after: 6,
        }
    }
}

/// A ceiling on how much of one tool result reaches the context.
///
/// A single call can return more than the whole conversation: a lock file, a
/// `SELECT *`, an MCP tool the framework does not control. Measured on a real
/// run, "search these files for a word" cost 53,487 input tokens because one
/// `read_file` returned a lock file — the model then paid for it on every
/// subsequent turn, and compaction started throwing away real history to make
/// room. A per-result ceiling is the only place to stop that: the tools cannot
/// all be trusted (third-party MCP), and the compactor only runs after the
/// damage is in the context.
#[derive(Debug, Clone)]
pub struct ToolResultPolicy {
    /// Max serialized bytes of a single tool result. `None` disables the guard.
    /// Default ~24 KiB — roughly 6k tokens of English, generous for a file page
    /// or a query result, far below what blows a window.
    pub max_bytes: Option<usize>,
    /// Replace the payload of a read-only call that exactly repeats an earlier
    /// one in the same run, when nothing has modified the world in between.
    ///
    /// [`StuckPolicy`] only sees *consecutive* identical rounds. Reading a file
    /// at iteration 1 and again at iteration 5 is not that, and looks like
    /// progress — but the same bytes land in the context twice and the model
    /// learns nothing the second time. Measured on a real run, model wait was
    /// 36.7s against 3ms of tool execution: a repeat costs context, not time,
    /// so what is suppressed is the payload, not the call.
    ///
    /// Only `ToolRisk::ReadOnly` qualifies (`Network` is a separate risk, and an
    /// external endpoint may answer differently), and any non-read-only call
    /// clears the record — after a write, re-reading is the correct move.
    ///
    /// **Off by default, on the evidence.** Measured on the completion
    /// benchmark: ceilings alone solved 6/6 tasks for 160k effective tokens;
    /// adding repeat-suppression cut that to 32k — and lost a task. An agent
    /// working through a file larger than one page re-reads it because it cannot
    /// hold it, gets told it already has the answer, and does not: the content
    /// was paged away. Five times cheaper is not worth a task a framework could
    /// otherwise do, so this is opt-in for callers who would rather have the
    /// tokens. (Suppressing from the *third* identical call rather than the
    /// second would likely keep most of the saving without the failure — it
    /// needs measuring before it becomes the default.)
    pub dedupe_repeats: bool,
    /// When a result exceeds `max_bytes`, save the *full* payload to a file
    /// under `.harness/spill/` in the workspace and inline a bounded preview
    /// plus the path, instead of cutting the tail off and throwing it away.
    ///
    /// Truncation destroys information: the model is told "narrow your
    /// request", but the bytes it needed may be exactly the ones dropped, and
    /// the only recovery is re-running the call to be truncated again.
    /// Measured on the completion benchmark, that loop is visible as a single
    /// task paying 184k input tokens. Spilling keeps the ceiling — the context
    /// gets a preview, never the flood — while the whole result stays
    /// retrievable through the file tools the agent already has (`read_file`
    /// with offset/limit, `grep` on the spill path), because the spill lives
    /// inside the workspace jail. Borrowed from DeepSeek Harness's `spill`
    /// family (preview + retrieval locator), which is the same judgement.
    ///
    /// Costs nothing until it fires: the write happens only on the oversized
    /// path, which the default ceiling makes rare. When the write fails (e.g.
    /// read-only workspace) the guard falls back to plain truncation.
    pub spill: bool,
}

impl Default for ToolResultPolicy {
    fn default() -> Self {
        Self {
            max_bytes: Some(24 * 1024),
            dedupe_repeats: false,
            spill: true,
        }
    }
}

/// Governs *when* and *how far* the loop compacts context. Hysteresis: only
/// start compacting once usage crosses `high_water`, and stop as soon as it's
/// back under `target` — instead of running every stage above a threshold on
/// every turn. This avoids over-compacting (needlessly reaching the lossy,
/// main-model `AutoCompact` stage) and, because compaction rewrites history and
/// invalidates the provider prefix cache, avoids nibbling the context every
/// single turn.
#[derive(Debug, Clone)]
pub struct CompactPolicy {
    /// Start compacting when `used/window` exceeds this. Default 0.75.
    pub high_water: f32,
    /// Stop as soon as `used/window` is back at/under this. Default 0.55.
    pub target: f32,
}

impl Default for CompactPolicy {
    fn default() -> Self {
        Self {
            high_water: 0.75,
            target: 0.55,
        }
    }
}

/// Inline preview size for a spilled result. Deliberately smaller than the
/// ceiling: the point of spilling is that the context gets a *glimpse* and a
/// path, not four-fifths of the flood.
const SPILL_PREVIEW_BYTES: usize = 4 * 1024;

/// First `n` bytes of `s`, cut on a char boundary.
fn head_of(s: &str, n: usize) -> &str {
    let mut end = n.min(s.len());
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }
    &s[..end]
}

/// The string field that dominates an oversized result, if one does.
///
/// Most oversized results are one big string in a small envelope — a file
/// body, a command's stdout — and the right spill for those is the *raw text*:
/// multi-line, so `read_file`'s line paging and `grep`'s line matching work on
/// it. Spilling the serialized JSON instead would fold the whole payload onto
/// one escaped line that line-oriented tools can neither page nor match
/// (`read_file` pages by line; a 68 KB single-line file is unreachable past
/// the first 16 KB). Returns the dotted path and the string when one field is
/// ≥ 80% of the serialized size.
fn dominant_string(v: &serde_json::Value, total: usize) -> Option<(String, &str)> {
    fn walk<'a>(v: &'a serde_json::Value, path: &str, best: &mut Option<(String, &'a str)>) {
        match v {
            serde_json::Value::String(s) => {
                if best.as_ref().is_none_or(|(_, b)| s.len() > b.len()) {
                    *best = Some((path.to_string(), s.as_str()));
                }
            }
            serde_json::Value::Object(m) => {
                for (k, x) in m {
                    let p = if path.is_empty() {
                        k.clone()
                    } else {
                        format!("{path}.{k}")
                    };
                    walk(x, &p, best);
                }
            }
            serde_json::Value::Array(a) => {
                for (i, x) in a.iter().enumerate() {
                    walk(x, &format!("{path}[{i}]"), best);
                }
            }
            _ => {}
        }
    }
    let mut best = None;
    walk(v, "", &mut best);
    best.filter(|(_, s)| s.len() * 5 >= total * 4)
}

/// Replace the value at a `dominant_string` dotted path with `with`.
fn replace_at(v: &mut serde_json::Value, path: &str, with: serde_json::Value) {
    let mut cur = v;
    let mut rest = path;
    loop {
        // Next segment: `key`, `key[i]`, or a bare `[i]`.
        let (seg, tail) = match rest.find('.') {
            Some(dot) => (&rest[..dot], &rest[dot + 1..]),
            None => (rest, ""),
        };
        let (key, idx) = match seg.find('[') {
            Some(b) => (&seg[..b], seg[b + 1..seg.len() - 1].parse::<usize>().ok()),
            None => (seg, None),
        };
        if !key.is_empty() {
            match cur.get_mut(key) {
                Some(next) => cur = next,
                None => return,
            }
        }
        if let Some(i) = idx {
            match cur.get_mut(i) {
                Some(next) => cur = next,
                None => return,
            }
        }
        if tail.is_empty() {
            *cur = with;
            return;
        }
        rest = tail;
    }
}

/// Persist an oversized result under `.harness/spill/` in the workspace and
/// build the inline marker. `None` on any IO failure — the caller falls back
/// to truncation, because a guard that can error a run to protect a context
/// window has its priorities backwards.
fn spill_oversized(
    action: &Action,
    content: &serde_json::Value,
    serialized: &str,
    root: &std::path::Path,
) -> Option<serde_json::Value> {
    let dir = root.join(".harness").join("spill");
    std::fs::create_dir_all(&dir).ok()?;
    let id: String = action
        .call_id
        .chars()
        .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
        .take(48)
        .collect();
    let id = if id.is_empty() { "call".into() } else { id };

    let (rel, preview, meta) = match dominant_string(content, serialized.len()) {
        // One big string in a small envelope: spill the raw text, keep the
        // envelope inline with the big field swapped for a pointer.
        Some((field, text)) => {
            let rel = format!(".harness/spill/{id}-{}.txt", action.tool);
            std::fs::write(root.join(&rel), text).ok()?;
            let mut meta = content.clone();
            replace_at(
                &mut meta,
                &field,
                serde_json::Value::String(format!("[{} bytes spilled to {rel}]", text.len())),
            );
            (
                rel,
                head_of(text, SPILL_PREVIEW_BYTES).to_string(),
                Some(meta),
            )
        }
        // Structured payload (e.g. a long match list): spill pretty-printed,
        // one element per line, so line-oriented retrieval still works.
        None => {
            let rel = format!(".harness/spill/{id}-{}.json", action.tool);
            let pretty =
                serde_json::to_string_pretty(content).unwrap_or_else(|_| serialized.to_string());
            std::fs::write(root.join(&rel), &pretty).ok()?;
            (rel, head_of(&pretty, SPILL_PREVIEW_BYTES).to_string(), None)
        }
    };
    tracing::warn!(
        target: "harness.telemetry",
        event = "tool.result.spilled",
        "gen_ai.tool.name" = %action.tool,
        bytes = serialized.len(),
        path = %rel,
    );
    let mut marker = serde_json::json!({
        "spilled": true,
        "tool": action.tool,
        "bytes_total": serialized.len(),
        "path": rel,
        "preview": preview,
        "note": format!(
            "This result was {} bytes — too large to inline, so the FULL content was \
             saved to '{rel}' (workspace-relative). Nothing was lost. Retrieve exactly \
             the part you need: grep(path=\"{rel}\", pattern=...) or \
             read_file(path=\"{rel}\", offset=..., limit=...). Do not repeat the \
             original call — it will spill again.",
            serialized.len()
        ),
    });
    // The envelope metadata (paths, flags) rides along when it is small; a
    // pathological envelope that is itself oversized is dropped, not inlined.
    if let Some(meta) = meta
        && meta.to_string().len() <= SPILL_PREVIEW_BYTES
    {
        marker["meta"] = meta;
    }
    Some(marker)
}

/// A stable fingerprint of a round's tool calls (names + args, ignoring the
/// volatile call id). Two rounds with the same fingerprint asked for the exact
/// same actions — the signal the stuck-detector keys on.
fn tool_call_fingerprint(calls: &[ToolCall]) -> String {
    calls
        .iter()
        .map(|c| format!("{}({})", c.name, c.args))
        .collect::<Vec<_>>()
        .join("|")
}

/// Where a run finished. Each variant is `#[non_exhaustive]` so new *fields*
/// don't break downstream matches — always include `..` when destructuring.
#[derive(Debug, Clone)]
pub enum Outcome {
    /// Model returned text with no tool calls (natural end).
    #[non_exhaustive]
    Done {
        text: Option<String>,
        iters: u32,
        tools_called: u32,
        usage: harness_core::Usage,
        /// What the acceptance checks said. `None` means nothing was asked —
        /// so "the model stopped" is all this outcome claims.
        verified: Option<Verdict>,
        /// The sealed contract as it stood before the model's first turn.
        ///
        /// Carried out of the run because a receipt has to say *what* was
        /// measured, not only that the measurement held. Empty when nothing
        /// was sealed.
        contract: crate::seal::SealSet,
        /// Set when a sealed acceptance contract changed during the run.
        ///
        /// Distinct from a plain failed `verified` because the two mean
        /// different things to a caller: a failed check is work not finished,
        /// this is the measuring instrument having been moved. A host may want
        /// to fail a build on the first and page someone on the second.
        seal_breach: Option<String>,
    },
    /// Policy budget exhausted before the model stopped requesting tools.
    /// Carries everything we know so the caller can recover partial work
    /// (saved notes, files written by tools, the last assistant text, etc.)
    /// instead of seeing a single bare "budget out" string.
    #[non_exhaustive]
    BudgetExhausted {
        iters: u32,
        last_text: Option<String>,
        tools_called: u32,
        usage: harness_core::Usage,
    },
    /// The agent got stuck: it repeated the *same* tool call for
    /// `StuckPolicy::abort_after` consecutive rounds without progress, so the
    /// loop terminated early to save the rest of the budget. Carries partial
    /// work (last text, files already written by tools) like `BudgetExhausted`.
    #[non_exhaustive]
    Stuck {
        /// Human-readable reason, e.g. "repeated `read_file(...)` 6× without progress".
        reason: String,
        /// How many consecutive identical rounds were observed.
        repeated: u32,
        iters: u32,
        last_text: Option<String>,
        tools_called: u32,
        usage: harness_core::Usage,
    },
}

/// The agent loop.
pub struct AgentLoop<M: Model> {
    pub model: M,
    pub tools: ToolRegistry,
    pub guides: Vec<Arc<dyn Guide>>,
    pub sensors: Vec<Arc<dyn Sensor>>,
    pub hooks: HookBus,
    pub compactor: Arc<dyn Compactor>,
    /// A deadline on each individual tool call. One hung call — a network tool
    /// on a dead endpoint, a shell command waiting on stdin — otherwise takes
    /// the whole run down with it, and the host's only recourse is a run-level
    /// timeout that throws away every turn of finished work (measured on the
    /// completion benchmark: a run that had already done the job was billed as
    /// a 0-token timeout). A per-call deadline converts the hang into an error
    /// *result* the model sees and can route around. `None` disables. The
    /// default is generous — 120s covers a slow build — because a false
    /// deadline on a legitimately long tool is worse than a late one.
    pub tool_timeout: Option<Duration>,
    /// Default response format applied to every run unless overridden by
    /// `run_typed`. See [`ResponseFormat`].
    pub response_format: ResponseFormat,
    /// When `true`, the loop drives each model turn via `Model::stream()`
    /// instead of `complete()`, firing `Event::ModelTokenDelta` for each
    /// text fragment. Tool-call deltas are still assembled inside the loop;
    /// only the terminal `ModelOutput` shape is observable downstream.
    pub streaming: bool,
    /// Optional cross-session recall store. When set, the loop captures every
    /// turn and the `session_search` tool is registered. See `with_recall`.
    pub recall: Option<Arc<dyn harness_core::RecallStore>>,
    /// When true (and `recall` is set), a `RecallGuide` auto-injects top-k
    /// past context at session start.
    pub recall_auto_inject: bool,
    pub learning: Option<LearningConfig>,
    /// Loop-detection policy. Enabled by default — see [`StuckPolicy`].
    pub stuck: StuckPolicy,
    /// Context-compaction hysteresis. See [`CompactPolicy`].
    pub compaction: CompactPolicy,
    /// Ceiling on a single tool result. See [`ToolResultPolicy`].
    pub tool_results: ToolResultPolicy,
    /// Conditions the run must satisfy before the loop reports success. The
    /// model stopping is evidence it *believes* it is finished; these say
    /// whether it is. See [`acceptance`].
    pub acceptance: Vec<Arc<dyn Acceptance>>,
    /// How many times a failed acceptance is handed back to the model before
    /// the loop gives up and reports what there is. One is usually enough: a
    /// model that ignores the first correction rarely takes the second.
    pub acceptance_retries: u32,
    /// System instruction injected into every run's `Context.system` (unless the
    /// built context already carries its own). Set via [`with_system`](Self::with_system).
    pub system: Vec<Block>,
}

impl AgentLoop<harness_core::DynModel> {
    /// Build a loop from a boxed model — what every model factory hands back
    /// (`ApiKind::build`, a router, anything stored behind a trait object).
    ///
    /// `Arc<dyn Model>` deliberately does not implement `Model` (see
    /// [`DynModel`](harness_core::DynModel) for why), so `AgentLoop::new` cannot
    /// take one. Without this constructor every caller writes the wrapper
    /// themselves, and the first thing a new user meets is a trait-bound error
    /// naming a type they have never heard of.
    ///
    /// ```ignore
    /// let model = ApiKind::OpenAI.build(base_url, model_id, key);
    /// let agent = AgentLoop::boxed(model).with_tool(Arc::new(ReadFile));
    /// ```
    pub fn boxed(model: Arc<dyn Model>) -> Self {
        Self::new(harness_core::DynModel(model))
    }
}

impl<M: Model> AgentLoop<M> {
    pub fn new(model: M) -> Self {
        Self {
            model,
            tools: ToolRegistry::new(),
            guides: Vec::new(),
            sensors: Vec::new(),
            hooks: HookBus::new(),
            compactor: Arc::new(DefaultCompactor::new()),
            tool_timeout: Some(Duration::from_secs(120)),
            response_format: ResponseFormat::Free,
            streaming: false,
            recall: None,
            recall_auto_inject: false,
            learning: None,
            stuck: StuckPolicy::default(),
            compaction: CompactPolicy::default(),
            // On by default, because the failure it catches is invisible: a
            // turn that produced nothing is reported as a turn that finished.
            tool_results: ToolResultPolicy::default(),
            acceptance: vec![Arc::new(acceptance::NonEmptyAnswer)],
            acceptance_retries: 1,
            system: Vec::new(),
        }
    }

    /// Set a system instruction applied to every run (into `Context.system`) —
    /// e.g. "answer only via the governed tools; never claim you can't access
    /// data; never invent numbers". This is the first-class seam for a system
    /// prompt; small local models in particular need it to reliably call tools
    /// instead of refusing or hallucinating.
    pub fn with_system(mut self, text: impl Into<String>) -> Self {
        self.system = vec![Block::Text(text.into())];
        self
    }

    /// Override the loop-detection policy (thresholds, or disable entirely).
    pub fn with_stuck_policy(mut self, policy: StuckPolicy) -> Self {
        self.stuck = policy;
        self
    }

    /// Override the compaction hysteresis policy. See [`CompactPolicy`].
    /// Set the ceiling on a single tool result. See [`ToolResultPolicy`].
    pub fn with_tool_result_policy(mut self, policy: ToolResultPolicy) -> Self {
        self.tool_results = policy;
        self
    }

    pub fn with_compact_policy(mut self, policy: CompactPolicy) -> Self {
        self.compaction = policy;
        self
    }

    /// Opt in to streaming the model's terminal turn token-by-token via
    /// `Model::stream()`. Hooks subscribed to `Event::ModelTokenDelta` see
    /// each fragment as it arrives; the rest of the loop is unchanged.
    pub fn with_streaming(mut self, enable: bool) -> Self {
        self.streaming = enable;
        self
    }

    /// Add a condition the run must satisfy before it can report success.
    pub fn with_acceptance(mut self, a: Arc<dyn Acceptance>) -> Self {
        self.acceptance.push(a);
        self
    }

    /// Replace the acceptance set outright (including the default).
    pub fn with_acceptance_set(mut self, set: Vec<Arc<dyn Acceptance>>) -> Self {
        self.acceptance = set;
        self
    }

    pub fn with_acceptance_retries(mut self, n: u32) -> Self {
        self.acceptance_retries = n;
        self
    }

    pub fn with_tool_timeout(mut self, t: Option<Duration>) -> Self {
        self.tool_timeout = t;
        self
    }

    pub fn with_compactor(mut self, c: Arc<dyn Compactor>) -> Self {
        self.compactor = c;
        self
    }

    pub fn with_tool(mut self, t: Arc<dyn harness_core::Tool>) -> Self {
        self.tools.insert(t);
        self
    }

    pub fn with_guide(mut self, g: Arc<dyn Guide>) -> Self {
        self.guides.push(g);
        self
    }

    pub fn with_sensor(mut self, s: Arc<dyn Sensor>) -> Self {
        self.sensors.push(s);
        self
    }

    pub fn with_hook(mut self, h: Arc<dyn harness_core::Hook>) -> Self {
        self.hooks.register(h);
        self
    }

    /// Pull in every `#[hook]`-registered hook.
    pub fn with_macro_hooks(mut self) -> Self {
        self.hooks = self.hooks.with_macro_hooks_take();
        self
    }

    /// Enable cross-session recall: capture every turn into `store` and
    /// register the `session_search` tool. Owner + session id are read from
    /// `world.profile.extra["recall_owner"|"recall_session"]` at run time.
    pub fn with_recall(mut self, store: Arc<dyn harness_core::RecallStore>) -> Self {
        self.tools
            .insert(Arc::new(crate::SessionSearchTool::new(store.clone())));
        self.recall = Some(store);
        self
    }

    /// Capture every turn into `store` **without** registering a search tool.
    ///
    /// Ingest and retrieval are separate concerns that [`with_recall`] happens
    /// to bundle, and the bundling is a trap: capture only ever happens when
    /// `self.recall` is set, so a host that wants a different search tool — one
    /// scoped per tenant, or one that copes with a language the backend's index
    /// does not — has no way to get the writes without also getting
    /// `session_search`, and ends up offering the model two overlapping tools
    /// to choose between.
    ///
    /// Use this, then register whichever retrieval tool suits the deployment.
    pub fn with_recall_ingest(mut self, store: Arc<dyn harness_core::RecallStore>) -> Self {
        self.recall = Some(store);
        self
    }

    /// After `with_recall`, also auto-inject top-k relevant past context at
    /// session start (off by default — tool-only is prompt-cache friendly).
    pub fn auto_inject(mut self) -> Self {
        self.recall_auto_inject = true;
        self
    }

    /// Enable the self-evolving learning loop: after a session that made
    /// `>= cfg.nudge_interval` tool calls, fork a review subagent (white-listed to
    /// `cfg.tools`) to update skills + memory from the transcript. Best-effort.
    pub fn with_learning_loop(mut self, cfg: LearningConfig) -> Self {
        self.learning = Some(cfg);
        self
    }

    /// Set the default response format for all runs through this loop. See
    /// [`ResponseFormat`]. For typed deserialisation, prefer `run_typed::<T>()`.
    pub fn with_response_format(mut self, fmt: ResponseFormat) -> Self {
        self.response_format = fmt;
        self
    }

    /// Shortcut for `with_response_format(ResponseFormat::JsonSchema { name, schema })`.
    /// Accepts a raw `serde_json::Value` so callers can hand-roll the schema or
    /// pull it from `schemars::schema_for!(T)`.
    pub fn with_response_schema(self, name: impl Into<String>, schema: serde_json::Value) -> Self {
        self.with_response_format(ResponseFormat::JsonSchema {
            name: name.into(),
            schema,
        })
    }

    pub async fn run(&self, task: Task, world: &mut World) -> Result<Outcome, HarnessError> {
        let max = harness_core::Policy::default().max_iters;
        self.run_with_max_iters(task, world, max).await
    }

    /// Run, and hand back the evidence alongside the result.
    ///
    /// The [`Receipt`] is built here rather than by the caller because the loop
    /// already knows the two things a caller would otherwise have to restate —
    /// the task and the model — and restating them is how a receipt ends up
    /// describing a different run than the one that happened. `now_ms` stays a
    /// parameter: this crate does not read the clock, so a receipt is
    /// reproducible in a test.
    pub async fn run_receipted(
        &self,
        task: Task,
        world: &mut World,
        now_ms: i64,
    ) -> Result<(Outcome, Receipt), HarnessError> {
        let description = task.description.clone();
        let handle = self.model.info().handle;
        let outcome = self.run(task, world).await?;
        let receipt = ReceiptBuilder::new(description, handle, now_ms).build(&outcome);
        Ok((outcome, receipt))
    }

    /// Advance a [`Goal`] by one phase, recording the result durably.
    ///
    /// Returns `None` when every phase is done — so a resume loop is
    /// `while let Some(..) = loop_.run_goal(..).await?`.
    ///
    /// The phase is marked `Running` and **saved before the model starts**, so
    /// a process that dies mid-run leaves a goal that says where it was rather
    /// than one that looks untouched. It is saved again afterwards on both
    /// paths. That second save on the failure path is the whole reason this
    /// method exists: written out by hand at each call site it is four lines,
    /// and the failure branch is the one that gets forgotten — which loses
    /// exactly the run you most wanted a record of.
    pub async fn run_goal(
        &self,
        goal: &mut Goal,
        store: &GoalStore,
        world: &mut World,
        now_ms: i64,
    ) -> Result<Option<(Outcome, Receipt)>, HarnessError> {
        let Some(i) = goal.start_current(now_ms) else {
            return Ok(None);
        };
        let _ = store.save(goal);

        let task = Task {
            description: goal.brief(),
            source: None,
            deadline: None,
        };
        let result = self.run_receipted(task, world, now_ms).await;

        match &result {
            Ok((_, receipt)) => {
                if receipt.passed {
                    goal.finish(i, receipt.summary(), now_ms);
                } else {
                    goal.fail(i, receipt.summary(), now_ms);
                }
            }
            // A run that errored outright still happened, and the goal has to
            // say so or a resume will retry it as though it were untouched.
            Err(e) => goal.fail(i, format!("the run errored: {e}"), now_ms),
        }
        let _ = store.save(goal);

        result.map(Some)
    }

    pub async fn run_with_max_iters(
        &self,
        task: Task,
        world: &mut World,
        max_iters: u32,
    ) -> Result<Outcome, HarnessError> {
        self.run_with_seed_history(task, Vec::new(), world, max_iters)
            .await
    }

    /// Run the agent and deserialise the terminal reply into `T`.
    ///
    /// The schema for `T` is derived via `schemars::schema_for!(T)` and
    /// installed as `ResponseFormat::JsonSchema` for this run only — any
    /// pre-existing `self.response_format` is ignored. On success the
    /// returned `T` is parsed from `Outcome::Done.text` (or, on budget
    /// exhaustion, from `Outcome::BudgetExhausted.last_text`).
    ///
    /// Errors:
    /// - `HarnessError::Other` if the model returns no text at all
    /// - `HarnessError::Other` if `serde_json::from_str::<T>(text)` fails —
    ///   the original text is included in the message for debugging.
    pub async fn run_typed<T>(&self, task: Task, world: &mut World) -> Result<T, HarnessError>
    where
        T: serde::de::DeserializeOwned + schemars::JsonSchema + 'static,
    {
        let max = harness_core::Policy::default().max_iters;
        self.run_typed_with_max_iters::<T>(task, world, max).await
    }

    /// Like `run_typed` but with explicit `max_iters`.
    pub async fn run_typed_with_max_iters<T>(
        &self,
        task: Task,
        world: &mut World,
        max_iters: u32,
    ) -> Result<T, HarnessError>
    where
        T: serde::de::DeserializeOwned + schemars::JsonSchema + 'static,
    {
        let schema_root = schemars::schema_for!(T);
        let schema = serde_json::to_value(&schema_root)
            .map_err(|e| HarnessError::Other(format!("response schema: {e}")))?;
        let name = std::any::type_name::<T>()
            .rsplit("::")
            .next()
            .unwrap_or("response")
            .to_string();
        let fmt = ResponseFormat::JsonSchema { name, schema };
        let outcome = self
            .run_with_response_format(task, world, max_iters, fmt)
            .await?;
        let text = match outcome {
            Outcome::Done { text: Some(t), .. }
            | Outcome::BudgetExhausted {
                last_text: Some(t), ..
            }
            | Outcome::Stuck {
                last_text: Some(t), ..
            } => t,
            Outcome::Done { text: None, .. } => {
                return Err(HarnessError::Other(
                    "run_typed: model returned no text".into(),
                ));
            }
            Outcome::Stuck {
                last_text: None, ..
            } => {
                return Err(HarnessError::Other(
                    "run_typed: agent stuck with no text".into(),
                ));
            }
            Outcome::BudgetExhausted {
                last_text: None, ..
            } => {
                return Err(HarnessError::Other(
                    "run_typed: budget exhausted with no text".into(),
                ));
            }
        };
        serde_json::from_str::<T>(&text).map_err(|e| {
            HarnessError::Other(format!(
                "run_typed: decode {} failed: {e} — raw text was: {text}",
                std::any::type_name::<T>()
            ))
        })
    }

    /// Run with a one-off `ResponseFormat` override (doesn't touch `self`).
    pub async fn run_with_response_format(
        &self,
        task: Task,
        world: &mut World,
        max_iters: u32,
        fmt: ResponseFormat,
    ) -> Result<Outcome, HarnessError> {
        // Borrow checker won't let us swap `self.response_format` because
        // `self` is `&`. Easiest workaround: hand-roll the same setup that
        // `run_with_seed_history` does, but with our `fmt`. We do this by
        // calling through a private helper.
        self.run_with_seed_history_and_format(task, Vec::new(), world, max_iters, Some(fmt))
            .await
    }

    async fn run_with_seed_history_and_format(
        &self,
        task: Task,
        seed: Vec<Turn>,
        world: &mut World,
        max_iters: u32,
        fmt_override: Option<ResponseFormat>,
    ) -> Result<Outcome, HarnessError> {
        let mut ctx = Context::new(task);
        ctx.policy.max_iters = max_iters;
        ctx.tools = self.tools.schemas();
        ctx.history = seed;
        ctx.response_format = fmt_override.unwrap_or_else(|| self.response_format.clone());
        self.run_built_context(ctx, world).await
    }

    /// Like `run_with_max_iters` but seeds `ctx.history` with `seed` **before**
    /// the current user task is appended. Use this for multi-turn REPLs so
    /// prior conversation lives in `ctx.history` (where the Compactor can see
    /// it) instead of being concatenated into `task.description` (where it
    /// previously bypassed compaction entirely — see audit #2).
    pub async fn run_with_seed_history(
        &self,
        task: Task,
        seed: Vec<Turn>,
        world: &mut World,
        max_iters: u32,
    ) -> Result<Outcome, HarnessError> {
        self.run_with_seed_and_metadata(task, seed, Default::default(), world, max_iters)
            .await
    }

    /// Like [`run_with_seed_history`](Self::run_with_seed_history) but also seeds
    /// `ctx.metadata` with per-request key/values. Hooks and a
    /// [`ModelRouter`](harness_models::ModelRouter) read this map — e.g.
    /// `audit.actor` / `audit.session` for the audit trail, or
    /// `router.keep_local` to pin a request to the local model. This is the
    /// entry point a serving layer uses to pass caller identity and routing
    /// flags into a single, shared, reused loop.
    pub async fn run_with_seed_and_metadata(
        &self,
        task: Task,
        seed: Vec<Turn>,
        metadata: std::collections::BTreeMap<String, serde_json::Value>,
        world: &mut World,
        max_iters: u32,
    ) -> Result<Outcome, HarnessError> {
        let mut ctx = Context::new(task);
        ctx.policy.max_iters = max_iters;
        ctx.tools = self.tools.schemas();
        ctx.history = seed;
        ctx.metadata = metadata;
        ctx.response_format = self.response_format.clone();
        self.run_built_context(ctx, world).await
    }

    /// Start a persistent multi-turn [`Session`]. Each `turn` re-runs the loop
    /// against the accumulated history with a **stable prefix** (system +
    /// name-sorted tool schemas), so a provider's prefix cache (e.g. DeepSeek's,
    /// ~10% price on cache-hit tokens) hits across turns instead of paying full
    /// price to re-read the same bytes every round. For maximum hit rate, keep
    /// your guides' output stable (put per-turn volatile context in the message,
    /// not a recomputed system guide).
    pub fn session(&self) -> Session<'_, M> {
        Session {
            loop_: self,
            history: Vec::new(),
            max_iters: harness_core::Policy::default().max_iters,
        }
    }

    /// Inner ReAct loop on an already-prepared `Context`. Use the public
    /// `run*` methods unless you need to inject a non-standard `Context`
    /// (e.g. `run_with_response_format` does to apply a one-off
    /// `ResponseFormat` without mutating `self`).
    async fn run_built_context(
        &self,
        mut ctx: Context,
        world: &mut World,
    ) -> Result<Outcome, HarnessError> {
        if ctx.system.is_empty() && !self.system.is_empty() {
            ctx.system = self.system.clone();
        }

        // Size the context budget to the model actually in use.
        //
        // Compaction fires at a fraction of `max_input_tokens`, so a value
        // unrelated to the model is wrong in one of two directions: too high and
        // the provider rejects the request before the compactor ever runs (a 32k
        // model under the 150k default would need 112,500 tokens to trigger, and
        // it cannot hold that many); too low and the loop discards history it
        // could have kept. Nothing read `ModelInfo::context_window` before this —
        // the framework's own defaults disagreed, 150,000 against 128,000.
        //
        // Only when the caller left the default in place; an explicit policy is
        // a decision and stays untouched. The output allowance is reserved,
        // because the window is shared between the prompt and the reply.
        if ctx.policy.max_input_tokens == harness_core::Policy::default().max_input_tokens {
            let window = self.model.info().context_window;
            if window > 0 {
                // Reserve room for the reply, but never let the reservation eat
                // the window: an 8k model with the default 8k output allowance
                // would leave 0 tokens for input, and every turn — a 26-token
                // one included — would run all five compaction stages against a
                // budget of 1. Cap the reservation at a quarter of the window.
                let reserve = ctx.policy.max_output_tokens.min(window / 4);
                ctx.policy.max_input_tokens = window.saturating_sub(reserve).max(1);
            }
        }

        self.hooks.fire(
            &Event::SessionStart {
                source: SessionSource::Startup,
            },
            world,
        );

        // ── recall: resolve owner/session, ensure the session row ──
        let (recall_owner, recall_session) = if self.recall.is_some() {
            use std::sync::atomic::Ordering;
            let owner = crate::recall_owner(world);
            let session = world
                .profile
                .extra
                .get("recall_session")
                .and_then(|v| v.as_str())
                .map(|s| s.to_string())
                .unwrap_or_else(|| {
                    format!(
                        "sess-{}-{}",
                        world.clock.now_ms(),
                        RECALL_SEQ.fetch_add(1, Ordering::SeqCst)
                    )
                });
            if let Some(store) = &self.recall {
                let meta = harness_core::SessionMeta::new(&session, world.clock.now_ms());
                if let Err(e) = store.ensure_session(&owner, &session, &meta).await {
                    tracing::warn!(error = %e, "recall ensure_session failed");
                }
            }
            (owner, session)
        } else {
            (String::new(), String::new())
        };

        let recall_guide: Option<Arc<dyn Guide>> = if self.recall_auto_inject {
            if self.recall.is_none() {
                tracing::warn!(
                    "auto_inject() set but no recall store — call with_recall(store) first; skipping recall guide"
                );
                None
            } else {
                self.recall
                    .clone()
                    .map(|s| Arc::new(crate::RecallGuide::new(s)) as Arc<dyn Guide>)
            }
        } else {
            None
        };
        let all_guides: Vec<&Arc<dyn Guide>> =
            self.guides.iter().chain(recall_guide.iter()).collect();
        for g in &all_guides {
            if g.scope().matches(&ctx.task) {
                self.hooks.fire(&Event::PreGuide { guide: g.id() }, world);
                g.apply(&mut ctx, world).await?;
                self.hooks.fire(&Event::PostGuide { guide: g.id() }, world);
            }
        }

        ctx.history.push(Turn {
            role: TurnRole::User,
            blocks: vec![Block::Text(ctx.task.description.clone())],
        });

        if self.recall.is_some() {
            self.recall_append(
                &recall_owner,
                &recall_session,
                harness_core::RecallMessage::new(
                    "user",
                    ctx.task.description.clone(),
                    world.clock.now_ms(),
                ),
            )
            .await;
        }

        // Running totals — surface to caller even on BudgetExhausted.
        let mut tools_called: u32 = 0;
        let mut total_usage = harness_core::Usage::default();
        let mut last_text: Option<String> = None;

        // Stuck-detector state: the previous round's tool-call fingerprint and
        // how many consecutive rounds have repeated it.
        let mut last_fingerprint: Option<String> = None;
        let mut repeat_count: u32 = 0;
        // Read-only calls already answered this run, cleared whenever anything
        // mutates the world. See `ToolResultPolicy::dedupe_repeats`.
        let mut answered: std::collections::HashSet<String> = std::collections::HashSet::new();
        // How many times the model has stopped mid-work with nothing to show.
        let mut acceptance_retries_left = self.acceptance_retries;

        // The contract as it stood before the model touched anything. Taken
        // now, not at verdict time, because the whole point is to compare
        // against a state the model has not had the chance to influence.
        // Set once a sealed file is found to have moved; makes the failure
        // terminal and carries the reason out to the caller.
        let mut seal_breached: Option<String> = None;
        let sealed_before: crate::seal::SealSet = {
            let paths: Vec<std::path::PathBuf> =
                self.acceptance.iter().flat_map(|a| a.seals()).collect();
            if paths.is_empty() {
                crate::seal::SealSet::default()
            } else {
                crate::seal::SealSet::capture(&world.repo.root, paths)
            }
        };

        for iter in 0..ctx.policy.max_iters {
            self.hooks.fire(&Event::Heartbeat { iter }, world);

            // Compaction with hysteresis: only once over the high-water mark,
            // then escalate stage-by-stage, re-estimating after each, and stop
            // the moment we're back under target. Avoids over-compacting to the
            // lossy AutoCompact stage and avoids rewriting history (→ prefix
            // cache miss) every turn. Token estimate is calibrated against the
            // last real `input_tokens` via `CALIBRATION_KEY`.
            let mut budget = self.compactor.budget(&ctx);
            if budget.ratio() > self.compaction.high_water {
                for stage in CompactionStage::ALL {
                    if budget.ratio() <= self.compaction.target {
                        break;
                    }
                    self.hooks.fire(&Event::PreCompact { stage }, world);
                    let before = budget.used;
                    self.compactor.compact(stage, &mut ctx).await?;
                    budget = self.compactor.budget(&ctx);
                    self.hooks.fire(
                        &Event::PostCompact {
                            stage,
                            before,
                            after: budget.used,
                        },
                        world,
                    );
                }
            }

            // Per-iteration guides — recall-style adapters that want to
            // refresh their injected context every turn (e.g. MemoryGuide
            // re-recalling against the latest user message). Default
            // `apply_before_iter` is a no-op, so this loop is cheap for
            // guides that don't override it.
            for g in &all_guides {
                if g.scope().matches(&ctx.task)
                    && let Err(e) = g.apply_before_iter(&mut ctx, world).await
                {
                    tracing::warn!(guide = %g.id(), error = %e, "apply_before_iter failed; continuing");
                }
            }

            self.hooks.fire(&Event::PreModel { ctx: &ctx }, world);
            let out = if self.streaming {
                self.complete_via_stream(&ctx, world).await?
            } else {
                self.model.complete(&ctx).await?
            };
            self.hooks.fire(&Event::PostModel { out: &out }, world);

            // Calibrate the compactor against ground truth: `ctx` still holds
            // exactly what we just sent, so `budget().used` is the estimate for
            // it. Nudge the stored correction so estimate·correction ≈ the
            // model's real `input_tokens` next time. Self-correcting (converges
            // even as the raw estimate drifts); clamped so one odd turn can't
            // blow it up. This is what makes compaction fire at the right moment
            // for *this* model + language instead of a blind char heuristic.
            if out.usage.input_tokens > 0 {
                let used = self.compactor.budget(&ctx).used;
                if used > 0 {
                    let prev = ctx
                        .metadata
                        .get(CALIBRATION_KEY)
                        .and_then(|v| v.as_f64())
                        .filter(|f| f.is_finite() && *f > 0.0)
                        .unwrap_or(1.0);
                    let next =
                        (prev * out.usage.input_tokens as f64 / used as f64).clamp(0.1, 10.0);
                    ctx.metadata
                        .insert(CALIBRATION_KEY.into(), serde_json::json!(next));
                }
            }

            // Accumulate usage even if the run later exhausts budget.
            total_usage.input_tokens += out.usage.input_tokens;
            total_usage.output_tokens += out.usage.output_tokens;
            total_usage.cached_input_tokens += out.usage.cached_input_tokens;
            if let Some(t) = &out.text {
                last_text = Some(t.clone());
            }
            ctx.push_model_output(&out);

            if self.recall.is_some() {
                let calls = if out.tool_calls.is_empty() {
                    None
                } else {
                    serde_json::to_string(&out.tool_calls).ok()
                };
                let mut m = harness_core::RecallMessage::new(
                    "assistant",
                    out.text.clone().unwrap_or_default(),
                    world.clock.now_ms(),
                );
                m.tool_calls = calls;
                self.recall_append(&recall_owner, &recall_session, m).await;
            }

            if out.tool_calls.is_empty() {
                // The model stopping is its opinion that the work is done.
                // Before taking it as fact, run whatever the caller said
                // "done" actually means. A failure goes back as an instruction
                // and the loop carries on; the retry cap keeps a model that
                // ignores corrections from eating the budget.
                let mut verdict: Option<Verdict> = None;
                if !self.acceptance.is_empty() {
                    // Record this turn first — the checks read the transcript.
                    let mut probe = ctx.clone();
                    probe.history.push(Turn {
                        role: TurnRole::Assistant,
                        blocks: out
                            .text
                            .as_deref()
                            .filter(|t| !t.trim().is_empty())
                            .map(|t| vec![Block::Text(t.to_string())])
                            .unwrap_or_default(),
                    });
                    for check in &self.acceptance {
                        let v = check.check(&probe, world).await;
                        self.hooks.fire(
                            &Event::AcceptanceChecked {
                                name: check.name(),
                                passed: v.passed,
                                reason: &v.reason,
                            },
                            world,
                        );
                        if !v.passed {
                            tracing::info!(
                                check = check.name(),
                                reason = %v.reason,
                                "acceptance failed"
                            );
                            verdict = Some(v);
                            break;
                        }
                    }
                    // Everything passed. Say so explicitly: "checked, and it
                    // holds up" is a different claim from "nobody looked", and
                    // the host has to be able to tell them apart.
                    verdict = verdict.or_else(|| Some(Verdict::passed()));
                }

                // A pass is only worth the contract it was measured against.
                // Re-read the sealed files and refuse if any moved.
                if !sealed_before.is_empty() && verdict.as_ref().is_some_and(|v| v.passed) {
                    let paths: Vec<std::path::PathBuf> =
                        self.acceptance.iter().flat_map(|a| a.seals()).collect();
                    let now = crate::seal::SealSet::capture(&world.repo.root, paths);
                    let breaches = sealed_before.breaches(&now);
                    if !breaches.is_empty() {
                        let what = breaches
                            .iter()
                            .map(|b| b.describe())
                            .collect::<Vec<_>>()
                            .join("; ");
                        tracing::error!(
                            breaches = %what,
                            "acceptance contract changed during the run — refusing the pass"
                        );
                        self.hooks
                            .fire(&Event::SealBreached { detail: &what }, world);
                        // Deliberately NOT a retry. Every other acceptance
                        // failure is handed back as an instruction because the
                        // model can act on it; this one would be handing back
                        // "you edited the gate", to the party that edited it,
                        // with the file still writable. The run is over.
                        seal_breached = Some(what);
                        verdict = Some(Verdict::failed(
                            "the acceptance contract was modified during this run",
                        ));
                    }
                }

                if let Some(v) = verdict.clone().filter(|v| !v.passed)
                    && seal_breached.is_none()
                    && acceptance_retries_left > 0
                    && iter + 1 < ctx.policy.max_iters
                {
                    acceptance_retries_left -= 1;
                    ctx.history.push(Turn {
                        role: TurnRole::User,
                        blocks: vec![Block::Text(v.reason)],
                    });
                    continue;
                }

                self.hooks.fire(&Event::TaskCompleted, world);
                self.hooks.fire(&Event::SessionEnd, world);
                self.run_learning_review(&ctx, world, tools_called).await;
                // Thinking models (e.g. Qwen3 via Ollama) sometimes emit the
                // whole answer into the reasoning channel and leave `text`
                // empty. Fall back to the reasoning so the turn isn't blank —
                // but `verified` says whether anyone agreed it was done.
                let text = out
                    .text
                    .filter(|t| !t.trim().is_empty())
                    .or_else(|| out.reasoning.filter(|r| !r.trim().is_empty()));
                return Ok(Outcome::Done {
                    text,
                    iters: iter + 1,
                    tools_called,
                    usage: total_usage,
                    verified: verdict,
                    contract: sealed_before.clone(),
                    seal_breach: seal_breached,
                });
            }

            // ── stuck detection ─────────────────────────────────────────
            // The model asked for tools again. If it's the *same* request as
            // last round, it's spinning: nudge it to change tack, then abort
            // cleanly rather than burn the rest of the budget on the loop.
            if self.stuck.enabled {
                let fp = tool_call_fingerprint(&out.tool_calls);
                if last_fingerprint.as_ref() == Some(&fp) {
                    repeat_count += 1;
                } else {
                    repeat_count = 1;
                    last_fingerprint = Some(fp);
                }

                if repeat_count >= self.stuck.abort_after {
                    let reason =
                        format!("repeated the same tool call {repeat_count}× without progress");
                    tracing::warn!(repeated = repeat_count, "stuck: aborting run");
                    self.hooks.fire(&Event::SessionEnd, world);
                    return Ok(Outcome::Stuck {
                        reason,
                        repeated: repeat_count,
                        iters: iter + 1,
                        last_text,
                        tools_called,
                        usage: total_usage,
                    });
                }

                if repeat_count == self.stuck.nudge_after {
                    tracing::warn!(
                        repeated = repeat_count,
                        "stuck: nudging model to change approach"
                    );
                    ctx.push_feedback(vec![harness_core::Signal {
                        severity: harness_core::Severity::Warn,
                        origin: "stuck-detector".into(),
                        message: format!(
                            "You have issued the same tool call {repeat_count} rounds in a row \
                             without making progress."
                        ),
                        agent_hint: Some(
                            "Stop repeating it. Inspect the actual tool result/error, try a \
                             different approach, or give your final answer with no tool call."
                                .into(),
                        ),
                        auto_fix: None,
                        location: None,
                    }]);
                }
            }

            // Parallel-safe prefetch: dispatch the *leading run* of read-only
            // tool calls concurrently (a mutating tool is a serial barrier).
            // The sequential loop below still processes every call in order —
            // hooks, sensors, and history stay ordered — only the dispatch IO
            // overlaps. Reads before any write are safe; anything at/after the
            // first mutating call runs on the normal path.
            let mut prefetched: HashMap<String, ToolResult> = HashMap::new();
            {
                let lead: Vec<&_> = out
                    .tool_calls
                    .iter()
                    .take_while(|c| {
                        self.tools.risk(&c.name) == Some(harness_core::ToolRisk::ReadOnly)
                    })
                    .collect();
                if lead.len() > 1 {
                    let futs = lead.iter().map(|c| {
                        let mut w = world.clone();
                        let action = Action {
                            tool: c.name.clone(),
                            call_id: c.id.clone(),
                            args: c.args.clone(),
                        };
                        async move {
                            let r = self.dispatch_bounded(&action, &mut w).await;
                            (action.call_id, r)
                        }
                    });
                    for (id, r) in futures::future::join_all(futs).await {
                        prefetched.insert(id, r);
                    }
                }
            }

            for call in &out.tool_calls {
                let action = Action {
                    tool: call.name.clone(),
                    call_id: call.id.clone(),
                    args: call.args.clone(),
                };

                // PreToolUse hook can deny destructive actions
                if let HookOutcome::Deny { reason } = self
                    .hooks
                    .fire(&Event::PreToolUse { action: &action }, world)
                {
                    ctx.history.push(Turn {
                        role: TurnRole::Tool,
                        blocks: vec![Block::ToolResult {
                            call_id: action.call_id.clone(),
                            content: serde_json::json!({
                                "ok": false,
                                "denied_by_hook": reason,
                            }),
                        }],
                    });
                    if self.recall.is_some() {
                        self.recall_append(
                            &recall_owner,
                            &recall_session,
                            harness_core::RecallMessage::new(
                                "tool",
                                format!("[denied by hook] {reason}"),
                                world.clock.now_ms(),
                            )
                            .with_tool_name(action.tool.clone()),
                        )
                        .await;
                    }
                    continue;
                }

                // Use the concurrently-prefetched result if we have one;
                // otherwise dispatch now.
                let result = if let Some(r) = prefetched.remove(&action.call_id) {
                    r
                } else {
                    self.dispatch_bounded(&action, world).await
                };
                tools_called += 1;

                // Decide the final payload *before* announcing the result, so
                // hooks, telemetry and the context all describe the same thing:
                // an audit that logs a 200 KB blob the model never saw is not an
                // audit of what happened.
                let result = ToolResult {
                    content: self.shape_result(&action, &result, &mut answered, &world.repo.root),
                    ..result
                };
                self.hooks.fire(
                    &Event::PostToolUse {
                        action: &action,
                        result: &result,
                    },
                    world,
                );

                ctx.history.push(Turn {
                    role: TurnRole::Tool,
                    blocks: vec![Block::ToolResult {
                        call_id: action.call_id.clone(),
                        content: result.content.clone(),
                    }],
                });

                if self.recall.is_some() {
                    let body = serde_json::to_string(&result.content).unwrap_or_default();
                    self.recall_append(
                        &recall_owner,
                        &recall_session,
                        harness_core::RecallMessage::new("tool", body, world.clock.now_ms())
                            .with_tool_name(action.tool.clone()),
                    )
                    .await;
                }

                // run self-correct sensors
                let mut all_signals = Vec::new();
                for s in &self.sensors {
                    if s.stage() != Stage::SelfCorrect {
                        continue;
                    }
                    self.hooks.fire(&Event::PreSensor { sensor: s.id() }, world);
                    let sigs = s.observe(&action, world).await.unwrap_or_else(|e| {
                        tracing::warn!(?e, "sensor failed");
                        Vec::new()
                    });
                    self.hooks.fire(
                        &Event::PostSensor {
                            sensor: s.id(),
                            signals: &sigs,
                        },
                        world,
                    );
                    all_signals.extend(sigs);
                }
                if !all_signals.is_empty() {
                    let bundle = SignalSet::new(all_signals);
                    let (patches, remaining) = bundle.partition_auto_fix();

                    // audit #7: each patch goes through PreAutoFix.
                    // Hooks can Deny (skip silently). Default safelist on
                    // RunCommand catches the obvious misuses with no hook.
                    let approved: Vec<harness_core::FixPatch> = patches.into_iter().filter(|p| {
                        if !is_default_safe_fix(p) {
                            tracing::warn!(?p, "auto-fix rejected by default safelist (use PreAutoFix hook to override)");
                            self.hooks.fire(&Event::PostAutoFix { patch: p, applied: false }, world);
                            return false;
                        }
                        match self.hooks.fire(&Event::PreAutoFix { patch: p }, world) {
                            HookOutcome::Deny { reason } => {
                                tracing::warn!(?p, %reason, "auto-fix denied by hook");
                                self.hooks.fire(&Event::PostAutoFix { patch: p, applied: false }, world);
                                false
                            }
                            _ => true,
                        }
                    }).collect();

                    let applied = apply_patches(&approved, world).await;
                    // Emit PostAutoFix for each approved patch with the application result.
                    for (i, p) in approved.iter().enumerate() {
                        self.hooks.fire(
                            &Event::PostAutoFix {
                                patch: p,
                                applied: i < applied.len(),
                            },
                            world,
                        );
                    }
                    if !applied.is_empty() {
                        ctx.push_feedback(vec![harness_core::Signal {
                            severity: harness_core::Severity::Hint,
                            origin: "auto-fix".into(),
                            message: format!(
                                "applied {} auto-fix patch(es): {applied:?}",
                                applied.len()
                            ),
                            agent_hint: Some(
                                "re-check the affected files before continuing".into(),
                            ),
                            auto_fix: None,
                            location: None,
                        }]);
                    }
                    if remaining.has_blocking() {
                        ctx.push_feedback(remaining.signals);
                    }
                }
            }
        }
        // ── Budget exhausted ─────────────────────────────────────────
        // Force a final synthesis pass with tools DISABLED. Otherwise the
        // model often spins on tool calls right up to the budget cap and
        // never emits a text conclusion, leaving the caller with nothing
        // but `last_text` from some earlier intermediate turn (or None).
        //
        // The synthesis call is "free" — it costs one extra model call
        // beyond max_iters but doesn't count toward `iters`. The result
        // lands in `last_text` so callers display it as the answer.
        let synthesised = self
            .force_final_synthesis(&mut ctx, world, &mut total_usage)
            .await;
        if let Some(t) = synthesised {
            last_text = Some(t);
        }

        self.hooks.fire(&Event::SessionEnd, world);
        self.run_learning_review(&ctx, world, tools_called).await;
        Ok(Outcome::BudgetExhausted {
            iters: ctx.policy.max_iters,
            last_text,
            tools_called,
            usage: total_usage,
        })
    }

    /// Drive `Model::stream()` and assemble the result into a `ModelOutput`,
    /// firing `Event::ModelTokenDelta` for each text fragment along the way.
    ///
    /// Adapters that don't implement real streaming (e.g. `GeminiNative` /
    /// `AnthropicNative` today) fall back to the default trait impl, which
    /// runs `complete()` and emits the whole reply as a single delta. That
    /// works — the loop sees one big `ModelDelta::Text(...)` followed by
    /// `Stop`, fires one big `ModelTokenDelta`, and proceeds. So enabling
    /// `streaming` is safe regardless of which provider the user picked.
    async fn complete_via_stream(
        &self,
        ctx: &Context,
        world: &mut World,
    ) -> Result<ModelOutput, HarnessError> {
        use futures::StreamExt;
        let mut stream = self
            .model
            .stream(ctx)
            .await
            .map_err(harness_core::HarnessError::Model)?;
        let mut text = String::new();
        let mut reasoning = String::new();
        let mut usage = Usage::default();
        let mut stop_reason = StopReason::EndTurn;
        // Insertion-ordered map: index → (id, name, args). We can't use the
        // tool-call id as the primary key because the stream may emit args
        // chunks before the first chunk that carries the id; the OpenAI-compat
        // SSE parser already does its own buffering and surfaces `id` in
        // ToolCallStart, but be lenient with adapters that may interleave.
        let mut tool_starts: HashMap<String, (String, String)> = HashMap::new();
        let mut tool_order: Vec<String> = Vec::new();
        while let Some(item) = stream.next().await {
            let delta = item.map_err(harness_core::HarnessError::Model)?;
            match delta {
                ModelDelta::Text(t) => {
                    if !t.is_empty() {
                        self.hooks.fire(&Event::ModelTokenDelta { text: &t }, world);
                        text.push_str(&t);
                    }
                }
                ModelDelta::ToolCallStart { id, name } => {
                    if !tool_starts.contains_key(&id) {
                        tool_order.push(id.clone());
                    }
                    tool_starts
                        .entry(id)
                        .or_insert_with(|| (name, String::new()));
                }
                ModelDelta::ToolCallArgs { id, partial_json } => {
                    let entry = tool_starts
                        .entry(id.clone())
                        .or_insert_with(|| (String::new(), String::new()));
                    if !tool_order.iter().any(|k| k == &id) {
                        tool_order.push(id);
                    }
                    entry.1.push_str(&partial_json);
                }
                ModelDelta::ToolCallEnd { .. } => {}
                ModelDelta::Usage(u) => usage = u,
                ModelDelta::Stop(r) => stop_reason = r,
                ModelDelta::Reasoning(s) => {
                    // Streamed reasoning arrives as token fragments, not lines —
                    // concatenate verbatim (same as `text`), don't insert newlines.
                    reasoning.push_str(&s);
                }
                // ModelDelta is `#[non_exhaustive]`; ignore future variants
                // we don't yet understand.
                _ => {}
            }
        }
        let tool_calls: Vec<ToolCall> = tool_order
            .into_iter()
            .filter_map(|id| {
                tool_starts.remove(&id).map(|(name, args)| {
                    let args_v = serde_json::from_str::<serde_json::Value>(&args)
                        .unwrap_or(serde_json::Value::String(args));
                    ToolCall {
                        id,
                        name,
                        args: args_v,
                    }
                })
            })
            .collect();
        // Reconcile stop_reason with what actually came out — adapters
        // sometimes emit `Stop(EndTurn)` even after tool_calls, which would
        // confuse downstream consumers that branch on stop_reason alone.
        let stop_reason = if !tool_calls.is_empty() {
            StopReason::ToolUse
        } else {
            stop_reason
        };
        Ok(ModelOutput {
            text: if text.is_empty() { None } else { Some(text) },
            tool_calls,
            usage,
            stop_reason,
            reasoning: if reasoning.is_empty() {
                None
            } else {
                Some(reasoning)
            },
            // `ModelDelta` has no image variant: the verified image-output
            // path (Gemini image models over chat) answers non-streamed, so
            // there is nothing to accumulate here. A streaming provider that
            // emits images would need a `ModelDelta::Image` first.
            images: Vec::new(),
        })
    }

    /// Best-effort append to the recall store. Never fails the turn.
    /// One tool call, under the per-call deadline. A timeout becomes an error
    /// *result* — the model sees it and routes around it — never a hung run.
    /// Errors are folded the same way: the loop's contract is that a tool call
    /// always produces a result turn.
    async fn dispatch_bounded(&self, action: &Action, world: &mut World) -> ToolResult {
        let fut = self.tools.dispatch(action, world);
        let dispatched = match self.tool_timeout {
            Some(deadline) => match tokio::time::timeout(deadline, fut).await {
                Ok(r) => r,
                Err(_) => {
                    tracing::warn!(
                        target: "harness.telemetry",
                        event = "tool.deadline",
                        "gen_ai.tool.name" = %action.tool,
                        seconds = deadline.as_secs(),
                    );
                    return ToolResult {
                        ok: false,
                        content: serde_json::json!({
                            "error": format!(
                                "tool call exceeded its {}s deadline and was cancelled; \
                                 the operation may be too broad — narrow it or try a \
                                 different approach",
                                deadline.as_secs()
                            ),
                            "timeout": true,
                        }),
                        trace: None,
                    };
                }
            },
            None => fut.await,
        };
        dispatched.unwrap_or_else(|e| ToolResult {
            ok: false,
            content: serde_json::json!({"error": e.to_string()}),
            trace: None,
        })
    }

    /// What a tool result contributes to the context: repeat suppression first,
    /// then the size ceiling. A repeat that is also oversized collapses to the
    /// pointer rather than to a truncated copy of what the model already holds.
    fn shape_result(
        &self,
        action: &Action,
        result: &ToolResult,
        answered: &mut std::collections::HashSet<String>,
        root: &std::path::Path,
    ) -> serde_json::Value {
        if !(self.tool_results.dedupe_repeats && result.ok) {
            return self.cap_result(action, &result.content, root);
        }
        match self.tools.risk(&action.tool) {
            Some(harness_core::ToolRisk::ReadOnly) => {
                let fp = format!("{}({})", action.tool, action.args);
                if answered.contains(&fp) {
                    tracing::info!(
                        target: "harness.telemetry",
                        event = "tool.result.repeat",
                        "gen_ai.tool.name" = %action.tool,
                    );
                    serde_json::json!({
                        "repeat_of_earlier_call": true,
                        "tool": action.tool,
                        "note": "You already made this exact call in this run and nothing has \
                                 changed the workspace since. The earlier result above still \
                                 stands — use it rather than asking again.",
                    })
                } else {
                    answered.insert(fp);
                    self.cap_result(action, &result.content, root)
                }
            }
            // A write invalidates every earlier read.
            _ => {
                answered.clear();
                self.cap_result(action, &result.content, root)
            }
        }
    }

    /// Enforce [`ToolResultPolicy`] on one result before it reaches the context.
    ///
    /// Over the ceiling, the guard prefers to *spill*: full payload to a file
    /// inside the workspace, bounded preview plus the path inline — nothing is
    /// lost, and the model retrieves slices with the file tools it already has.
    /// Only when spilling is off (or the write fails) does it fall back to
    /// destructive truncation: a byte-level cut handed back as a marker object
    /// rather than mangled JSON, saying how much was dropped and what to do
    /// instead.
    fn cap_result(
        &self,
        action: &Action,
        content: &serde_json::Value,
        root: &std::path::Path,
    ) -> serde_json::Value {
        let Some(max) = self.tool_results.max_bytes else {
            return content.clone();
        };
        let serialized = content.to_string();
        if serialized.len() <= max {
            return content.clone();
        }
        if self.tool_results.spill
            && let Some(marker) = spill_oversized(action, content, &serialized, root)
        {
            return marker;
        }
        // Cut on a char boundary so the kept head is valid UTF-8.
        let mut end = max;
        while end > 0 && !serialized.is_char_boundary(end) {
            end -= 1;
        }
        tracing::warn!(
            target: "harness.telemetry",
            event = "tool.result.truncated",
            "gen_ai.tool.name" = %action.tool,
            bytes = serialized.len(),
            max_bytes = max,
        );
        serde_json::json!({
            "truncated": true,
            "tool": action.tool,
            "bytes_total": serialized.len(),
            "bytes_kept": end,
            "head": serialized[..end],
            "note": format!(
                "This result was {} bytes and was cut to {} to protect the context window. \
                 Do not ask for it again unchanged — narrow it: request a smaller range, \
                 a filter, or a specific field.",
                serialized.len(), end
            ),
        })
    }

    async fn recall_append(&self, owner: &str, session: &str, msg: harness_core::RecallMessage) {
        if let Some(store) = &self.recall
            && let Err(e) = store.append(owner, session, &msg).await
        {
            tracing::warn!(error = %e, "recall append failed");
        }
    }

    /// Best-effort post-session review. Never affects the finished run.
    async fn run_learning_review(&self, ctx: &Context, world: &mut World, tools_called: u32) {
        let Some(cfg) = &self.learning else { return };
        if tools_called < cfg.nudge_interval {
            return;
        }
        let transcript = crate::render_transcript(&ctx.history, 12_000);
        let task = harness_core::Task {
            description: format!(
                "{}\n\n## Conversation transcript\n{}",
                cfg.review_prompt, transcript
            ),
            source: None,
            deadline: None,
        };
        let mut spec =
            crate::SubagentSpec::new("learning-review", task).with_max_iters(cfg.max_iters);
        for t in &cfg.tools {
            spec = spec.with_tool(t.clone());
        }
        let sub = crate::Subagent::new(harness_core::DynModel(cfg.review_model.clone()), spec);
        // Box::pin breaks the recursive async-future cycle: AgentLoop<M> →
        // run_learning_review → Subagent<DynModel>::run →
        // AgentLoop<Arc<dyn Model>>::run_built_context. Without pinning the
        // compiler rejects the infinite-sized future.
        if let Err(e) = Box::pin(sub.run(world)).await {
            tracing::warn!(error = %e, "learning review failed");
        }
    }

    /// One final model call with tools removed, asking it to write the
    /// best-effort conclusion from whatever it has already gathered.
    ///
    /// Errors from the model are swallowed — observability is best-effort
    /// here, and a transport blip during synthesis should not turn a
    /// near-complete run into a hard failure.
    async fn force_final_synthesis(
        &self,
        ctx: &mut Context,
        world: &mut World,
        total_usage: &mut harness_core::Usage,
    ) -> Option<String> {
        const SYNTHESIS_PROMPT: &str = "[system: iteration budget exhausted] \
            You have run out of tool-calling iterations. Write your final answer \
            NOW using only the tool results already in this conversation. Do not \
            request more tools. Mark facts you could not verify as UNKNOWN. \
            Include source URLs for every claim that is not UNKNOWN.";

        // Signal to any observer (LiveProgressHook, SessionRecorder, custom
        // hooks) that we've used 100% of the budget and are about to force
        // synthesis. Pre-existing `BudgetWarning` event was unused; this is
        // its natural home.
        self.hooks.fire(&Event::BudgetWarning { ratio: 1.0 }, world);

        // Snapshot + clear tool schemas so the model has no choice but text.
        let saved_tools = std::mem::take(&mut ctx.tools);
        ctx.history.push(Turn {
            role: TurnRole::User,
            blocks: vec![Block::Text(SYNTHESIS_PROMPT.into())],
        });

        self.hooks.fire(&Event::PreModel { ctx }, world);
        let result = self.model.complete(ctx).await;
        ctx.tools = saved_tools;

        match result {
            Ok(out) => {
                self.hooks.fire(&Event::PostModel { out: &out }, world);
                total_usage.input_tokens += out.usage.input_tokens;
                total_usage.output_tokens += out.usage.output_tokens;
                total_usage.cached_input_tokens += out.usage.cached_input_tokens;
                ctx.push_model_output(&out);
                out.text
            }
            Err(_) => None,
        }
    }
}

/// A persistent multi-turn conversation over one [`AgentLoop`].
///
/// Holds the append-only history and, on each [`turn`](Session::turn), re-runs
/// the loop against a **stable prefix** (system + name-sorted tool schemas).
/// That byte-stable prefix is what lets a provider's prefix cache hit across
/// turns — the difference between paying full price to re-read the same context
/// every round and paying ~10% for the cached bytes (DeepSeek).
pub struct Session<'a, M: Model> {
    loop_: &'a AgentLoop<M>,
    history: Vec<Turn>,
    max_iters: u32,
}

impl<'a, M: Model> Session<'a, M> {
    pub fn with_max_iters(mut self, n: u32) -> Self {
        self.max_iters = n;
        self
    }
    /// Preload prior turns (e.g. resumed from disk).
    pub fn with_seed(mut self, seed: Vec<Turn>) -> Self {
        self.history = seed;
        self
    }
    /// The accumulated conversation so far.
    pub fn history(&self) -> &[Turn] {
        &self.history
    }
    /// Start over (branch): drop the accumulated turns.
    pub fn reset(&mut self) {
        self.history.clear();
    }

    /// Send one user message. Runs the ReAct loop against the accumulated
    /// history, then appends this user turn + the assistant reply so the next
    /// turn extends the same cached prefix.
    pub async fn turn(
        &mut self,
        message: impl Into<String>,
        world: &mut World,
    ) -> Result<Outcome, HarnessError> {
        let message = message.into();
        let task = Task {
            description: message.clone(),
            source: None,
            deadline: None,
        };
        let outcome = self
            .loop_
            .run_with_seed_history(task, self.history.clone(), world, self.max_iters)
            .await?;
        let reply = match &outcome {
            Outcome::Done { text, .. } => text.clone().unwrap_or_default(),
            Outcome::BudgetExhausted { last_text, .. } | Outcome::Stuck { last_text, .. } => {
                last_text.clone().unwrap_or_default()
            }
        };
        self.history.push(Turn {
            role: TurnRole::User,
            blocks: vec![Block::Text(message)],
        });
        self.history.push(Turn {
            role: TurnRole::Assistant,
            blocks: vec![Block::Text(reply)],
        });
        Ok(outcome)
    }
}

/// Audit #7: default safelist for `FixPatch::RunCommand`.
///
/// Sensors emitting `RunCommand` patches would otherwise be a silent
/// arbitrary-code-execution channel. We restrict the *program* by name to a
/// short list of well-known, side-effect-bounded formatters/fixers. Anything
/// else returns false and the patch is rejected (write your own `PreAutoFix`
/// hook returning `HookOutcome::Allow` to widen the policy).
///
/// `ReplaceFile` and `UnifiedDiff` are not restricted here — they only touch
/// files inside the workspace and are covered by the symlink-safe path
/// resolution in `harness-tools-fs`.
pub fn is_default_safe_fix(patch: &harness_core::FixPatch) -> bool {
    use harness_core::FixPatch;
    match patch {
        FixPatch::ReplaceFile { .. } | FixPatch::UnifiedDiff { .. } => true,
        FixPatch::RunCommand { program, args, .. } => match program.as_str() {
            // Cargo subcommands proven side-effect-bounded.
            "cargo" => matches!(
                args.first().map(String::as_str),
                Some("fmt" | "clippy" | "fix"),
            ),
            "rustfmt" | "gofmt" | "prettier" | "ruff" | "black" => true,
            _ => false,
        },
        // Future FixPatch variants: deny by default — review and add to the list above.
        _ => false,
    }
}

/// Monotonic counter for `.harness-patch-*.diff` temp filenames — millisecond
/// resolution alone collides under parallel agent runs.
static PATCH_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// Monotonic counter for fallback recall session ids (no `uuid` dep).
static RECALL_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// Apply auto-fix patches; return short descriptions of those that succeeded.
///
/// Made `pub` (was `pub(crate)`) so integration tests can call it directly.
pub async fn apply_patches(patches: &[harness_core::FixPatch], world: &mut World) -> Vec<String> {
    use harness_core::FixPatch;
    let mut applied = Vec::new();
    for p in patches {
        match p {
            FixPatch::ReplaceFile { path, content } => {
                let abs = world.repo.root.join(path);
                if let Some(parent) = abs.parent() {
                    let _ = tokio::fs::create_dir_all(parent).await;
                }
                if tokio::fs::write(&abs, content).await.is_ok() {
                    applied.push(format!("replaced {}", path.display()));
                }
            }
            FixPatch::UnifiedDiff { diff } => {
                if try_apply_diff(world, diff).await {
                    applied.push("unified diff applied".into());
                }
            }
            FixPatch::RunCommand { program, args, cwd } => {
                let cwd_ref = cwd.as_deref().unwrap_or(world.repo.root.as_path());
                let args_ref: Vec<&str> = args.iter().map(String::as_str).collect();
                if let Ok(out) = world.runner.exec(program, &args_ref, Some(cwd_ref)).await
                    && out.status == 0
                {
                    applied.push(format!("ran `{program} {}`", args.join(" ")));
                }
            }
            // FixPatch is `#[non_exhaustive]`; unknown variants are skipped.
            _ => tracing::warn!("apply_patches: unknown FixPatch variant — skipped"),
        }
    }
    applied
}

/// Write `diff` to a unique temp file and try `patch -p1` first, then `-p0`.
/// Returns whether either succeeded. The `-p1`-then-`-p0` order matches the
/// reality that most agent-emitted diffs are git-style (need `-p1`) but some
/// hand-rolled diffs use repo-relative paths (need `-p0`).
async fn try_apply_diff(world: &mut World, diff: &str) -> bool {
    use std::sync::atomic::Ordering;
    use tokio::io::AsyncWriteExt;

    let seq = PATCH_SEQ.fetch_add(1, Ordering::SeqCst);
    let pid = std::process::id();
    let now = world.clock.now_ms();
    let tmp = world
        .repo
        .root
        .join(format!(".harness-patch-{pid}-{now}-{seq}.diff"));

    let mut f = match tokio::fs::File::create(&tmp).await {
        Ok(f) => f,
        Err(e) => {
            tracing::warn!(error=%e, path=%tmp.display(), "could not create patch tempfile");
            return false;
        }
    };
    if let Err(e) = f.write_all(diff.as_bytes()).await {
        tracing::warn!(error=%e, "could not write patch tempfile");
        let _ = tokio::fs::remove_file(&tmp).await;
        return false;
    }
    drop(f);

    let tmp_str = tmp.to_string_lossy().to_string();
    let mut applied = false;
    for strip in ["-p1", "-p0"] {
        match world
            .runner
            .exec(
                "patch",
                &[strip, "--silent", "-i", tmp_str.as_str()],
                Some(world.repo.root.as_path()),
            )
            .await
        {
            Ok(out) if out.status == 0 => {
                tracing::info!(strip, "patch applied");
                applied = true;
                break;
            }
            Ok(out) => {
                tracing::debug!(strip, stderr=%out.stderr, "patch failed; trying next strip level");
            }
            Err(e) => {
                tracing::warn!(error=%e, "patch command not available");
                break; // patch tool missing — no point trying other strip
            }
        }
    }
    let _ = tokio::fs::remove_file(&tmp).await;
    applied
}