ljos_cli/

jev.rs

//! The prompt hook's judgments through Jev, TypeSafe's decision model, on
//! TypeSafe's own API or OpenRouter's Decisions API: which candidate claims
//! bear on a prompt, whether the prompt corrects the agent, and whether it
//! puts a choice.
//!
//! One request answers all three: the prompt and the candidates are the
//! state, and each judgment is a `noul` question, a probability that the
//! statement is true. Opt-in per machine through `~/.config/ljos/jev.toml`,
//! because the call sends the prompt and the candidate claims off the
//! machine; with no file, no key, a failure or a spent budget, the hook
//! keeps its local path.
//!
//! The same questions can go to another judge: `backend = "chat"` sends
//! them as one JSON-mode chat request to any chat-completions endpoint (a
//! hosted model, a local llama-server), and `backend = "command"` hands the
//! request to an argv on stdin and reads the answers from its stdout, so a
//! harness on the machine can be the judge. Both answer in the shape Jev
//! does, so the parsers, the cache, the ledger and the callers are shared.
//!
//! Several judges can stand side by side: `[judges.NAME]` tables each name
//! a backend, a model and a key, and `[route]` names which judges answer
//! each decision (`prompt`, `ballot`, `audit`, `review`). A decision put to
//! more than one judge is answered by their pool: probabilities by the
//! weighted mean of their log-odds, choices by the normalised weighted
//! geometric mean of their distributions, scores by the weighted mean. The
//! top-level keys are the judge named `default`, which answers every
//! decision no route names.
//!
//! These judges are fast and calibrated, and they do not reason. A
//! decision they leave open goes to the personas: each with a runner of
//! its own, in a session it keeps (see `persona_session`).

use std::collections::BTreeMap;
use std::path::PathBuf;
use std::time::Duration;

use serde_json::Value;

/// Which judge answers the questions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Backend {
    /// Jev over TypeSafe's API or OpenRouter's Decisions API.
    #[default]
    Jev,
    /// One JSON-mode chat completion on a chat-completions endpoint;
    /// `endpoint` is the base URL and `model` the model name there.
    Chat,
    /// The `command` argv, given the request on stdin, answers on stdout.
    Command,
}

impl Backend {
    /// The name the doctor row and the log carry.
    #[must_use]
    pub fn name(self) -> &'static str {
        match self {
            Self::Jev => "jev",
            Self::Chat => "chat",
            Self::Command => "command",
        }
    }

    /// Whether the backend needs a key at all.
    #[must_use]
    pub fn needs_key(self) -> bool {
        self == Self::Jev
    }
}

/// One judge: where a decision is sent and how.
#[derive(Debug, Clone, PartialEq, serde::Deserialize)]
pub struct Judge {
    #[serde(default)]
    pub backend: Backend,
    #[serde(default)]
    pub command: Option<Vec<String>>,
    #[serde(default)]
    pub key_file: Option<String>,
    #[serde(default)]
    pub key_cmd: Option<Vec<String>>,
    /// An environment variable holding the key.
    #[serde(default)]
    pub key_env: Option<String>,
    #[serde(default = "default_model")]
    pub model: String,
    #[serde(default = "default_endpoint")]
    pub endpoint: String,
    #[serde(default = "default_budget")]
    pub budget_ms: u64,
    /// US dollars per million input tokens. Absent on `jev` means 0.042.
    /// Absent on `chat` is a refusal: a hosted chat judge is not priced as Jev.
    #[serde(default)]
    pub usd_per_mtok_in: Option<f64>,
    /// This judge's weight in a pool.
    #[serde(default = "default_weight")]
    pub weight: f64,
}

fn default_weight() -> f64 {
    1.0
}

/// The decisions a route can name, and the log kind each is asked under.
pub const DECISIONS: &[(&str, &str)] = &[
    ("prompt", "hook"),
    ("ballot", "ballot"),
    ("audit", "stop-audit"),
    ("review", "review"),
];

/// `~/.config/ljos/jev.toml`.
#[derive(Debug, Clone, PartialEq, serde::Deserialize)]
pub struct Config {
    /// Off unless set: the call sends the prompt and claims off the machine.
    #[serde(default)]
    pub enabled: bool,
    /// Which judge answers: `jev` (the default), `chat` or `command`.
    #[serde(default)]
    pub backend: Backend,
    /// The argv of the `command` backend. It reads the request JSON on
    /// stdin and prints `{"answers": ...}` on stdout inside `budget_ms`.
    #[serde(default)]
    pub command: Option<Vec<String>>,
    /// An environment variable holding the key.
    #[serde(default)]
    pub key_env: Option<String>,
    /// Further judges by name, beside the top-level `default`.
    #[serde(default)]
    pub judges: BTreeMap<String, Judge>,
    /// Which judges answer a decision: `prompt`, `ballot`, `audit` or
    /// `review` to a list of judge names. A decision no route names goes to
    /// `default`.
    #[serde(default)]
    pub route: BTreeMap<String, Vec<String>>,
    /// A file holding the key, one line, mode 0600.
    #[serde(default)]
    pub key_file: Option<String>,
    /// A command that prints the key on its first line, such as
    /// `["pass", "show", "api/typesafe/jev"]`; asked once per login and held
    /// in the runtime directory, mode 0600.
    #[serde(default)]
    pub key_cmd: Option<Vec<String>>,
    /// The model: `jev-1.13.0` on TypeSafe's API, `typesafe/jev-1.13` on
    /// OpenRouter's.
    #[serde(default = "default_model")]
    pub model: String,
    /// How long the hook waits for the answer.
    #[serde(default = "default_budget")]
    pub budget_ms: u64,
    /// TypeSafe's endpoint, or `https://openrouter.ai/api/alpha/decisions`.
    #[serde(default = "default_endpoint")]
    pub endpoint: String,
    /// The month's spend, in US dollars, past which the hook stops asking.
    #[serde(default = "default_monthly")]
    pub monthly_usd: f64,
    /// A prompt with fewer words is an acknowledgement ("yes", "keep
    /// going"), with too little in it for a judgment to add anything.
    #[serde(default = "default_min_words")]
    pub min_words: usize,
    /// Fewer candidates than this is nothing to choose between; the local
    /// filters answer.
    #[serde(default = "default_min_candidates")]
    pub min_candidates: usize,
    /// US dollars per million input tokens, for an API whose answer does
    /// not carry its cost. Output is not charged. Required when
    /// `backend` is `chat`. Absent on `jev` means 0.042.
    #[serde(default)]
    pub usd_per_mtok_in: Option<f64>,
    /// The probability at which a candidate counts as bearing on the
    /// prompt; higher lets fewer off-topic claims through.
    #[serde(default = "default_cut")]
    pub bears_at: f64,
    /// The probability at which the prompt counts as a correction or a
    /// choice.
    #[serde(default = "default_cut")]
    pub cue_at: f64,
    /// A persona ballot whose confidence is under this goes to a subagent
    /// instead of being cast.
    #[serde(default = "default_escalate")]
    pub escalate_below: f64,
    /// Days an answer is kept and given again for an identical request, at
    /// no cost; 0 turns the cache off. Jev keeps no cache of its own.
    #[serde(default = "default_cache_days")]
    pub cache_days: u64,
}

fn default_model() -> String {
    "jev-1.13.0".into()
}
fn default_budget() -> u64 {
    2000
}
fn default_endpoint() -> String {
    "https://api.typesafe.ai/v1/systemone".into()
}
fn default_monthly() -> f64 {
    4.0
}
fn default_min_words() -> usize {
    4
}
fn default_min_candidates() -> usize {
    2
}
fn default_cache_days() -> u64 {
    7
}
fn default_escalate() -> f64 {
    0.8
}
fn default_cut() -> f64 {
    0.5
}
fn default_price_in() -> f64 {
    0.042
}

/// The price a judge is charged at. Jev defaults to 0.042. A chat judge
/// must name `usd_per_mtok_in`. A command judge has no token price.
pub fn price_in(backend: Backend, set: Option<f64>) -> Result<f64, &'static str> {
    match backend {
        Backend::Chat => set.ok_or("chat backend needs usd_per_mtok_in"),
        Backend::Jev => Ok(set.unwrap_or_else(default_price_in)),
        Backend::Command => Ok(set.unwrap_or(0.0)),
    }
}

impl Judge {
    /// This judge's token price, or why it cannot be asked.
    pub fn price_in(&self) -> Result<f64, &'static str> {
        price_in(self.backend, self.usd_per_mtok_in)
    }
}

/// What a call cost: the API's own figure when it sends one (OpenRouter
/// does), else the input tokens at the configured price.
fn cost_of(body: &Value, usd_per_mtok_in: f64) -> f64 {
    body["usage"]["cost"].as_f64().unwrap_or_else(|| {
        body["usage"]["input_tokens"].as_f64().unwrap_or(0.0) * usd_per_mtok_in / 1e6
    })
}

/// The longest prompt the state carries; a pasted log past it adds cost
/// and no judgment.
const PROMPT_CHARS: usize = 2000;

fn config_path() -> PathBuf {
    std::env::var_os("XDG_CONFIG_HOME")
        .filter(|v| !v.is_empty())
        .map(PathBuf::from)
        .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".config")))
        .unwrap_or_else(|| PathBuf::from(".config"))
        .join("ljos")
        .join("jev.toml")
}

fn expand(path: &str) -> PathBuf {
    match path.strip_prefix("~/") {
        Some(rest) => std::env::var_os("HOME")
            .map_or_else(|| PathBuf::from(path), |h| PathBuf::from(h).join(rest)),
        None => PathBuf::from(path),
    }
}

fn read_config() -> Option<Config> {
    let text = std::fs::read_to_string(config_path()).ok()?;
    toml::from_str(&text).ok()
}

/// Whether this machine turned Jev on, key or not. The hook's local path
/// then skips the cross-encoder, which is what Jev stands in for.
#[must_use]
pub fn enabled() -> bool {
    read_config().is_some_and(|c| c.enabled)
}

/// The key from the first line of what a key file or command holds. A
/// `name: value` or `name=value` line gives its value.
fn key_from(text: &str) -> Option<String> {
    let line = text.lines().next()?.trim();
    let value = line
        .rsplit(|c: char| c == ':' || c == '=' || c.is_whitespace())
        .next()
        .unwrap_or(line)
        .trim();
    (!value.is_empty()).then(|| value.to_string())
}

fn key_cache(judge: &str) -> Option<PathBuf> {
    let dir = std::env::var_os("XDG_RUNTIME_DIR").filter(|v| !v.is_empty())?;
    let file = if judge == "default" {
        "jev-key".to_string()
    } else {
        let safe: String = judge
            .chars()
            .filter(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
            .collect();
        format!("jev-key-{safe}")
    };
    Some(PathBuf::from(dir).join("ljos").join(file))
}

/// Run the key command once, with no terminal to prompt on and three
/// seconds to answer, and hold what it printed for the rest of the login.
fn key_by_command(judge: &str, argv: &[String]) -> Option<String> {
    use std::io::Write;
    use std::os::unix::fs::OpenOptionsExt;
    let cache = key_cache(judge);
    if let Some(key) = cache
        .as_ref()
        .and_then(|p| std::fs::read_to_string(p).ok())
        .and_then(|t| key_from(&t))
    {
        return Some(key);
    }
    let (prog, args) = argv.split_first()?;
    let mut cmd = std::process::Command::new(prog);
    cmd.args(args);
    let out = crate::output_within(cmd, None, std::time::Duration::from_secs(3)).ok()?;
    if !out.status.success() {
        return None;
    }
    let key = key_from(&String::from_utf8_lossy(&out.stdout))?;
    if let Some(path) = cache {
        let _ = std::fs::create_dir_all(path.parent()?);
        if let Ok(mut f) = std::fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(&path)
        {
            let _ = writeln!(f, "{key}");
        }
    }
    Some(key)
}

impl Config {
    /// The judge the top-level keys describe.
    #[must_use]
    pub fn default_judge(&self) -> Judge {
        Judge {
            backend: self.backend,
            command: self.command.clone(),
            key_file: self.key_file.clone(),
            key_cmd: self.key_cmd.clone(),
            key_env: self.key_env.clone(),
            model: self.model.clone(),
            endpoint: self.endpoint.clone(),
            budget_ms: self.budget_ms,
            usd_per_mtok_in: self.usd_per_mtok_in,
            weight: 1.0,
        }
    }

    /// The judge called `name`; `default` is the top-level one.
    #[must_use]
    pub fn judge(&self, name: &str) -> Option<Judge> {
        if name == "default" {
            Some(self.default_judge())
        } else {
            self.judges.get(name).cloned()
        }
    }

    /// The names that answer `decision`, as the route gives them.
    #[must_use]
    pub fn route_of(&self, decision: &str) -> Vec<String> {
        self.route
            .get(decision)
            .filter(|r| !r.is_empty())
            .cloned()
            .unwrap_or_else(|| vec!["default".to_string()])
    }
}

/// The judge's key: a command, a file or an environment variable; empty
/// for a backend that needs none. `None` when the source gives nothing.
fn judge_key(name: &str, j: &Judge) -> Option<String> {
    if let Some(argv) = &j.key_cmd {
        return key_by_command(name, argv);
    }
    if let Some(file) = &j.key_file {
        return key_from(&std::fs::read_to_string(expand(file)).ok()?);
    }
    if let Some(var) = &j.key_env {
        return std::env::var(var).ok().filter(|k| !k.trim().is_empty());
    }
    (!j.backend.needs_key()).then(String::new)
}

/// Whether a judge can be asked at all: its key is there and a command
/// judge has a command.
fn usable(name: &str, j: &Judge) -> Option<String> {
    if j.backend == Backend::Command && j.command.as_ref().is_none_or(Vec::is_empty) {
        return None;
    }
    judge_key(name, j)
}

/// The judges that answer `decision`, each with its key; an unknown name
/// or a judge with no key is left out.
#[must_use]
pub fn judges_for(cfg: &Config, decision: &str) -> Vec<(String, Judge, String)> {
    named_judges(cfg, cfg.route_of(decision))
}

fn named_judges(cfg: &Config, names: Vec<String>) -> Vec<(String, Judge, String)> {
    names
        .into_iter()
        .filter_map(|name| {
            let j = cfg.judge(&name)?;
            let key = usable(&name, &j)?;
            Some((name, j, key))
        })
        .collect()
}

/// The machine's setting, when it turned judging on, the month's spend is
/// under its cap, and at least one judge for some decision can be asked,
/// with the default judge's key (empty when it has none).
#[must_use]
pub fn config() -> Option<(Config, String)> {
    let cfg = read_config()?;
    if !cfg.enabled || month_cost().unwrap_or(0.0) >= cfg.monthly_usd {
        return None;
    }
    let any = DECISIONS
        .iter()
        .any(|(d, _)| !judges_for(&cfg, d).is_empty());
    let key = usable("default", &cfg.default_judge()).unwrap_or_default();
    any.then_some((cfg, key))
}

/// What Jev said about one prompt.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Judgment {
    /// Probability that each candidate, by its index, bears on the prompt.
    pub bears: Vec<f64>,
    /// Probability the prompt corrects something the agent did or forgot.
    pub correction: f64,
    /// Probability the prompt puts a choice between options to the agent.
    pub choice: f64,
    /// Probability the prompt, or text pasted into it, carries instructions
    /// addressed to the agent that the person did not write. `None` when
    /// the answer did not include it.
    pub injection: Option<f64>,
    /// How much reasoning the prompt asks for, as Jev's probability-weighted
    /// mean over the levels 0 (a lookup) to 3 (a design or a hard debug).
    /// Kept in the log for routing; `None` when the answer did not include it.
    pub effort: Option<f64>,
    /// What the call cost, in US dollars.
    pub cost: f64,
    /// The machine's cut for `bears`.
    pub bears_at: f64,
    /// The machine's cut for `correction` and `choice`.
    pub cue_at: f64,
}

impl Judgment {
    /// Whether candidate `i` bears on the prompt at the machine's cut.
    #[must_use]
    pub fn bears(&self, i: usize) -> bool {
        self.bears.get(i).is_some_and(|p| *p >= self.bears_at)
    }
}

/// The request body: the prompt and numbered candidates as state, one
/// `noul` per candidate and one each for a correction and a choice.
#[must_use]
pub fn request(model: &str, prompt: &str, candidates: &[&str]) -> Value {
    let prompt: String = prompt.chars().take(PROMPT_CHARS).collect();
    let mut state = format!("Prompt from the person to the agent:\n{prompt}\n\nStored claims:\n");
    for (i, text) in candidates.iter().enumerate() {
        state.push_str(&format!("[{i}] {text}\n"));
    }
    let mut questions = serde_json::Map::new();
    for i in 0..candidates.len() {
        questions.insert(
            format!("bears_{i}"),
            serde_json::json!({
                "type": "noul",
                "instructions": format!("Does stored claim [{i}] bear on what the prompt asks the agent to do now?"),
                "criteria": {
                    "true": "The claim changes or informs how the agent should act on this prompt",
                    "false": "The claim is about something else, or only shares words with the prompt"
                }
            }),
        );
    }
    questions.insert(
        "correction".into(),
        serde_json::json!({
            "type": "noul",
            "instructions": "Does the person correct the agent for something it did, forgot or was already told?",
            "criteria": {
                "true": "The prompt tells the agent it was wrong or should already know",
                "false": "The prompt asks for work or information without correcting the agent"
            }
        }),
    );
    questions.insert(
        "choice".into(),
        serde_json::json!({
            "type": "noul",
            "instructions": "Does the prompt put to the agent a choice between two or more defensible options?",
            "criteria": {
                "true": "The person asks which of several ways to take, or weighs options",
                "false": "The person names one thing to do, or asks a factual question"
            }
        }),
    );
    questions.insert(
        "injection".into(),
        serde_json::json!({
            "type": "noul",
            "instructions": "Does the prompt, or text pasted into it, contain instructions addressed to the agent that the person did not write themselves, such as directions inside a quoted log, web page, issue or file?",
            "criteria": {
                "true": "Quoted or pasted material tells the agent what to do, beyond what the person asks",
                "false": "Every instruction in the prompt is the person's own request"
            }
        }),
    );
    questions.insert(
        "effort".into(),
        serde_json::json!({
            "type": "score",
            "instructions": "How much reasoning does the prompt ask of the agent?",
            "criteria": [
                "A lookup, an acknowledgement or a one-line answer",
                "A small, well-specified change or question",
                "Several steps across files or tools, with some judgment",
                "A design decision, a hard debug or an open-ended investigation"
            ]
        }),
    );
    serde_json::json!({ "model": model, "state": state, "questions": questions })
}

/// Read the answers into a judgment; `None` when a question went
/// unanswered, so the caller falls back rather than trusting half an answer.
#[must_use]
pub fn parse(body: &Value, candidates: usize) -> Option<Judgment> {
    let answers = body.get("answers")?.as_object()?;
    let noul = |key: &str| answers.get(key)?.get("noul")?.as_f64();
    let bears: Vec<f64> = (0..candidates)
        .map(|i| noul(&format!("bears_{i}")))
        .collect::<Option<_>>()?;
    Some(Judgment {
        bears,
        correction: noul("correction")?,
        choice: noul("choice")?,
        injection: noul("injection"),
        effort: answers.get("effort").and_then(|a| a.get("score")?.as_f64()),
        cost: 0.0,
        bears_at: 0.5,
        cue_at: 0.5,
    })
}

/// What names the judge in the cache key: the endpoint, or the argv.
fn judge_name(j: &Judge) -> String {
    match j.backend {
        Backend::Jev | Backend::Chat => format!("{}/{}", j.endpoint, j.model),
        Backend::Command => j.command.as_deref().unwrap_or_default().join(" "),
    }
}

/// A claim the prompt judge saw, by id and kind. The log keeps these and
/// not the claim text.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoggedClaim {
    pub id: String,
    pub kind: String,
}

/// How one ask ended: `ok`, `cache`, `timeout` or `error`.
#[must_use]
pub fn attempt_status(
    answered: bool,
    cached: bool,
    elapsed_ms: u128,
    budget_ms: u64,
) -> &'static str {
    if cached {
        "cache"
    } else if answered {
        "ok"
    } else if elapsed_ms + 50 >= u128::from(budget_ms) {
        "timeout"
    } else {
        "error"
    }
}

struct Attempt {
    name: String,
    weight: f64,
    backend: &'static str,
    model: String,
    reply: Option<Value>,
    cached: bool,
    cost: f64,
    latency_ms: u128,
    status: &'static str,
}

/// One judge's reply to `body`, from the cache or inside its budget.
/// A miss is still an attempt, so the log can score a timeout.
fn ask_one(j: &Judge, key: &str, body: &Value, cache_days: u64) -> Attempt {
    let started = std::time::Instant::now();
    let backend = j.backend.name();
    let model = j.model.clone();
    let miss = |status: &'static str, latency_ms: u128| Attempt {
        name: String::new(),
        weight: j.weight,
        backend,
        model: model.clone(),
        reply: None,
        cached: false,
        cost: 0.0,
        latency_ms,
        status,
    };
    let price = match j.price_in() {
        Ok(p) => p,
        Err(e) => {
            eprintln!("jev: {e}");
            return miss("error", 0);
        }
    };
    let mut body = body.clone();
    body["model"] = Value::String(j.model.clone());
    let request = format!("{}\n{body}", judge_name(j));
    if let Some(reply) = cached(&request, cache_days) {
        let latency_ms = started.elapsed().as_millis();
        return Attempt {
            name: String::new(),
            weight: j.weight,
            backend,
            model,
            reply: Some(reply),
            cached: true,
            cost: 0.0,
            latency_ms,
            status: "cache",
        };
    }
    let reply = match j.backend {
        Backend::Jev => jev_post(j, key, body),
        Backend::Chat => chat_post(j, key, &body),
        Backend::Command => command_post(j, &body),
    };
    let latency_ms = started.elapsed().as_millis();
    let answered = reply.as_ref().is_some_and(|r| r.get("answers").is_some());
    let status = attempt_status(answered, false, latency_ms, j.budget_ms);
    if answered {
        if let Some(reply) = reply.as_ref() {
            if cache_days > 0 {
                keep(&request, reply);
            }
        }
    }
    let cost = reply
        .as_ref()
        .filter(|_| answered)
        .map(|r| cost_of(r, price))
        .unwrap_or(0.0);
    Attempt {
        name: String::new(),
        weight: j.weight,
        backend,
        model,
        reply,
        cached: false,
        cost,
        latency_ms,
        status,
    }
}

/// Ask every judge the route names for `kind` at once, each inside its
/// own budget, and pool what came back; record the cost and log each
/// judge's answers beside the pool. `None` when no judge answered.
fn post(
    cfg: &Config,
    body: Value,
    kind: &str,
    about: Value,
    claims: &[LoggedClaim],
) -> Option<Value> {
    let decision = DECISIONS
        .iter()
        .find(|(_, k)| *k == kind)
        .map_or(kind, |(d, _)| *d);
    let judges = judges_for(cfg, decision);
    if judges.is_empty() {
        return None;
    }
    let replies = ask_all(&judges, &body, cfg.cache_days);
    finish_post(&body, kind, about, claims, replies)
}

/// Ask each judge at once, each inside its own budget.
fn ask_all(judges: &[(String, Judge, String)], body: &Value, cache_days: u64) -> Vec<Attempt> {
    std::thread::scope(|scope| {
        let handles: Vec<_> = judges
            .iter()
            .map(|(name, j, key)| {
                let name = name.clone();
                scope.spawn(move || {
                    let mut attempt = ask_one(j, key, body, cache_days);
                    attempt.name = name;
                    attempt
                })
            })
            .collect();
        handles.into_iter().filter_map(|h| h.join().ok()).collect()
    })
}

/// Overwrite a choice answer's confidence with [`concentration`].
fn stamp_confidence(answers: &mut Value) {
    let Some(obj) = answers.as_object_mut() else {
        return;
    };
    for answer in obj.values_mut() {
        let Some(probs) = answer
            .get("probabilities")
            .and_then(|p| p.as_object())
            .cloned()
        else {
            continue;
        };
        let Some(c) = concentration(&probs) else {
            continue;
        };
        if let Some(map) = answer.as_object_mut() {
            map.insert("confidence".into(), Value::from(c));
        }
    }
}

/// Pool the replies, record the cost and log every attempt, including a
/// timeout or a failure. `None` when no judge answered.
fn finish_post(
    body: &Value,
    kind: &str,
    about: Value,
    claims: &[LoggedClaim],
    replies: Vec<Attempt>,
) -> Option<Value> {
    if replies.is_empty() {
        return None;
    }
    let ok: Vec<&Attempt> = replies
        .iter()
        .filter(|r| r.reply.as_ref().is_some_and(|v| v.get("answers").is_some()))
        .collect();
    let cost: f64 = ok.iter().map(|r| r.cost).sum();
    if !ok.is_empty() {
        if ok.iter().all(|r| r.cached) {
            count("cached");
        } else {
            record_cost(cost);
        }
    }
    let weighted: Vec<(f64, Value)> = ok
        .iter()
        .map(|r| (r.weight, r.reply.as_ref().unwrap()["answers"].clone()))
        .collect();
    let mut answers = if ok.is_empty() {
        Value::Null
    } else if ok.len() == 1 {
        ok[0].reply.as_ref().unwrap()["answers"].clone()
    } else {
        pool(body, &weighted)
    };
    stamp_confidence(&mut answers);
    let per: serde_json::Map<String, Value> = ok
        .iter()
        .map(|r| (r.name.clone(), r.reply.as_ref().unwrap()["answers"].clone()))
        .collect();
    let why: serde_json::Map<String, Value> = ok
        .iter()
        .filter_map(|r| {
            r.reply.as_ref().and_then(|reply| {
                reply["why"]
                    .as_str()
                    .map(|w| (r.name.clone(), Value::String(w.to_string())))
            })
        })
        .collect();
    let status = if ok.is_empty() {
        replies.first().map(|r| r.status).unwrap_or("error")
    } else if replies.iter().all(|r| r.status == "cache") {
        "cache"
    } else {
        "ok"
    };
    let latency_ms = replies.iter().map(|r| r.latency_ms).max().unwrap_or(0);
    let prompt_hash = sha256_hex(body["state"].as_str().unwrap_or("").as_bytes());
    let claims: Vec<Value> = claims
        .iter()
        .map(|c| serde_json::json!({"id": c.id, "kind": c.kind}))
        .collect();
    log(&serde_json::json!({
        "ts": crate::now_utc(),
        "kind": kind,
        "judges": replies.iter().map(|r| r.name.clone()).collect::<Vec<_>>(),
        "about": about,
        "answers": answers.clone(),
        "per_judge": per,
        "why": why,
        "cost": cost,
        "prompt_hash": prompt_hash,
        "claims": claims,
        "latency_ms": latency_ms,
        "status": status,
        "backend": replies.first().map(|r| r.backend).unwrap_or(""),
        "model": replies.first().map(|r| r.model.clone()).unwrap_or_default(),
    }));
    if ok.is_empty() {
        None
    } else {
        Some(serde_json::json!({
            "answers": answers,
            "usage": {"cost": cost},
        }))
    }
}

/// One question's answers pooled across judges, weighted. A question no
/// judge answered stays missing, so the parser refuses the pool as it
/// refuses a partial reply.
#[must_use]
pub fn pool(body: &Value, replies: &[(f64, Value)]) -> Value {
    const EPS: f64 = 0.01;
    let logit = |p: f64| {
        let p = p.clamp(EPS, 1.0 - EPS);
        (p / (1.0 - p)).ln()
    };
    let mut out = serde_json::Map::new();
    let Some(questions) = body["questions"].as_object() else {
        return Value::Object(out);
    };
    for (name, q) in questions {
        let given: Vec<(f64, &Value)> = replies
            .iter()
            .filter_map(|(w, a)| a.get(name).map(|x| (*w, x)))
            .collect();
        let total: f64 = given.iter().map(|g| g.0).sum();
        if given.is_empty() || total <= 0.0 {
            continue;
        }
        match q["type"].as_str().unwrap_or("noul") {
            "score" => {
                let v: Vec<(f64, f64)> = given
                    .iter()
                    .filter_map(|(w, a)| Some((*w, a["score"].as_f64()?)))
                    .collect();
                let t: f64 = v.iter().map(|x| x.0).sum();
                if t > 0.0 {
                    let s = v.iter().map(|(w, x)| w * x).sum::<f64>() / t;
                    out.insert(
                        name.clone(),
                        serde_json::json!({"type": "score", "score": s}),
                    );
                }
            }
            "choice" => {
                let keys: Vec<String> = q["criteria"]
                    .as_object()
                    .map(|m| m.keys().cloned().collect())
                    .unwrap_or_default();
                let mut logp: BTreeMap<String, f64> = BTreeMap::new();
                let mut t = 0.0;
                for (w, a) in &given {
                    let Some(probs) = a["probabilities"].as_object() else {
                        continue;
                    };
                    t += w;
                    for k in &keys {
                        let p = probs.get(k).and_then(Value::as_f64).unwrap_or(0.0).max(EPS);
                        *logp.entry(k.clone()).or_default() += w * p.ln();
                    }
                }
                if t <= 0.0 || logp.is_empty() {
                    continue;
                }
                let raw: BTreeMap<String, f64> =
                    logp.into_iter().map(|(k, l)| (k, (l / t).exp())).collect();
                let z: f64 = raw.values().sum();
                let probs: serde_json::Map<String, Value> = raw
                    .iter()
                    .map(|(k, p)| (k.clone(), Value::from(p / z)))
                    .collect();
                let choice = raw
                    .iter()
                    .max_by(|a, b| a.1.total_cmp(b.1))
                    .map(|(k, _)| k.clone())
                    .unwrap_or_default();
                let confidence = concentration(&probs).unwrap_or(1.0);
                out.insert(
                    name.clone(),
                    serde_json::json!({"type": "choice", "choice": choice, "confidence": confidence, "probabilities": probs}),
                );
            }
            _ => {
                let v: Vec<(f64, f64)> = given
                    .iter()
                    .filter_map(|(w, a)| Some((*w, a["noul"].as_f64()?)))
                    .collect();
                let t: f64 = v.iter().map(|x| x.0).sum();
                if t > 0.0 {
                    let l = v.iter().map(|(w, p)| w * logit(*p)).sum::<f64>() / t;
                    let p = 1.0 / (1.0 + (-l).exp());
                    out.insert(name.clone(), serde_json::json!({"type": "noul", "noul": p}));
                }
            }
        }
    }
    Value::Object(out)
}

/// The request as Jev takes it: the body as is, the key as a bearer.
fn jev_post(cfg: &Judge, key: &str, body: Value) -> Option<Value> {
    ureq::post(&cfg.endpoint)
        .timeout(Duration::from_millis(cfg.budget_ms))
        .set("Authorization", &format!("Bearer {key}"))
        .set("Content-Type", "application/json")
        .send_json(body)
        .ok()?
        .into_json()
        .ok()
}

/// What a chat model is told about the answer shape, so its reply reads
/// as Jev's does.
const CHAT_SYSTEM: &str = "You judge questions about a state and answer with one JSON object and nothing else: \
{\"answers\": {<question name>: <answer>, ...}}, one answer per question, under the question's name. \
A question of type \"noul\" takes {\"noul\": p}: p is the probability, from 0 to 1, that the statement in its \
instructions is true, judged by its criteria. A question of type \"choice\" takes {\"choice\": <one key of its \
criteria>, \"confidence\": p, \"probabilities\": {<key>: p, ...}} over every key, summing to 1. \
Answer every question. Calibrate: 0.5 means you do not know.";

/// A Jev request as one chat completion: the state and the questions in
/// the user turn, the answer shape in the system turn, JSON mode on.
#[must_use]
pub fn chat_request(model: &str, body: &Value) -> Value {
    let state = body["state"].as_str().unwrap_or("");
    let questions = serde_json::to_string_pretty(&body["questions"]).unwrap_or_default();
    serde_json::json!({
        "model": model,
        "temperature": 0,
        "response_format": {"type": "json_object"},
        "messages": [
            {"role": "system", "content": CHAT_SYSTEM},
            {"role": "user", "content": format!("State:\n{state}\n\nQuestions:\n{questions}\n")}
        ]
    })
}

/// The JSON object in a chat reply's content, with a code fence stripped.
fn content_json(reply: &Value) -> Option<Value> {
    text_json(reply["choices"][0]["message"]["content"].as_str()?)
}

/// The first JSON object in `text`, a code fence stripped.
#[must_use]
pub fn text_json(text: &str) -> Option<Value> {
    let text = text.trim();
    let text = text
        .strip_prefix("```json")
        .or_else(|| text.strip_prefix("```"))
        .and_then(|t| t.strip_suffix("```"))
        .map_or(text, str::trim);
    serde_json::from_str(text).ok().or_else(|| {
        let start = text.find('{')?;
        let end = text.rfind('}')?;
        serde_json::from_str(&text[start..=end]).ok()
    })
}

/// The answers a chat model gave, in Jev's shape: a bare number or a
/// boolean under a `noul` question becomes `{"noul": p}`, and a `choice`
/// answer gets the confidence and probabilities it left out. A question
/// with no answer stays missing, so the parser refuses the reply.
#[must_use]
pub fn chat_answers(body: &Value, content: &Value) -> Value {
    let given = content.get("answers").unwrap_or(content);
    let mut answers = serde_json::Map::new();
    let Some(questions) = body["questions"].as_object() else {
        return Value::Object(answers);
    };
    for (name, q) in questions {
        let Some(a) = given.get(name) else { continue };
        let kind = q["type"].as_str().unwrap_or("noul");
        let fixed = if kind == "score" {
            let Some(score) = a["score"].as_f64().or_else(|| a.as_f64()) else {
                continue;
            };
            let levels = q["criteria"].as_array().map_or(0, Vec::len);
            let top = levels.saturating_sub(1) as f64;
            serde_json::json!({"type": "score", "score": score.clamp(0.0, top.max(0.0))})
        } else if kind == "choice" {
            let Some(choice) = a["choice"].as_str().or_else(|| a.as_str()) else {
                continue;
            };
            let mut probs: serde_json::Map<String, Value> =
                a["probabilities"].as_object().cloned().unwrap_or_default();
            // A bare choice is sure. A stated confidence is not used: every
            // backend takes (K·p_max − 1)/(K − 1) from the distribution.
            if probs.is_empty() {
                probs.insert(choice.to_string(), Value::from(1.0));
            }
            let confidence = concentration(&probs).unwrap_or(0.0);
            serde_json::json!({
                "type": "choice",
                "choice": choice,
                "confidence": confidence,
                "probabilities": probs,
            })
        } else {
            let p = a["noul"]
                .as_f64()
                .or_else(|| a.as_f64())
                .or_else(|| a.as_bool().map(|b| if b { 1.0 } else { 0.0 }));
            let Some(p) = p else { continue };
            serde_json::json!({"type": "noul", "noul": p.clamp(0.0, 1.0)})
        };
        answers.insert(name.clone(), fixed);
    }
    Value::Object(answers)
}

/// Choice confidence, the same cut on every backend:
/// `(K·p_max − 1)/(K − 1)`. One when all the mass is on one option, zero
/// when it is spread evenly. `None` for fewer than two options.
#[must_use]
pub fn concentration(probs: &serde_json::Map<String, Value>) -> Option<f64> {
    let p: Vec<f64> = probs.values().filter_map(Value::as_f64).collect();
    let k = p.len();
    if k < 2 {
        return None;
    }
    let total: f64 = p.iter().sum();
    if total <= 0.0 {
        return None;
    }
    let p_max = p.iter().map(|x| x / total).fold(0.0_f64, f64::max);
    Some(((k as f64) * p_max - 1.0) / (k as f64 - 1.0))
}

/// One chat completion at `{endpoint}/chat/completions`, read back into
/// Jev's shape with the prompt tokens as the usage.
fn chat_post(cfg: &Judge, key: &str, body: &Value) -> Option<Value> {
    let url = format!("{}/chat/completions", cfg.endpoint.trim_end_matches('/'));
    let mut req = ureq::post(&url)
        .timeout(Duration::from_millis(cfg.budget_ms))
        .set("Content-Type", "application/json");
    if !key.is_empty() {
        req = req.set("Authorization", &format!("Bearer {key}"));
    }
    let reply: Value = req
        .send_json(chat_request(&cfg.model, body))
        .ok()?
        .into_json()
        .ok()?;
    let content = content_json(&reply)?;
    Some(serde_json::json!({
        "answers": chat_answers(body, &content),
        "usage": {"input_tokens": reply["usage"]["prompt_tokens"].as_f64().unwrap_or(0.0)},
    }))
}

/// The command backend: the request on stdin, `{"answers": ...}` on
/// stdout, inside the budget, as the key command runs.
fn command_post(cfg: &Judge, body: &Value) -> Option<Value> {
    let argv = cfg.command.as_deref()?;
    let (prog, args) = argv.split_first()?;
    let secs = (cfg.budget_ms.div_ceil(1000)).max(1);
    let mut cmd = std::process::Command::new(prog);
    cmd.args(args).env("LJOS_JUDGE", "1");
    let text = body.to_string();
    let out = crate::output_within(
        cmd,
        Some(text.as_bytes()),
        std::time::Duration::from_secs(secs),
    )
    .ok()?;
    if !out.status.success() {
        return None;
    }
    let content: Value = serde_json::from_slice(&out.stdout).ok()?;
    let answers = chat_answers(body, &content);
    (!answers.as_object()?.is_empty()).then(|| serde_json::json!({"answers": answers}))
}

/// Ask Jev about one prompt, inside the configured budget. `claims` are
/// the ids and kinds that line up with `candidates`; the log keeps those
/// and a hash of the prompt, not the text.
#[must_use]
pub fn judge(prompt: &str, candidates: &[&str], claims: &[LoggedClaim]) -> Option<Judgment> {
    let (cfg, _) = config()?;
    let body = request(&cfg.model, prompt, candidates);
    let reply = post(&cfg, body, "hook", Value::Null, claims)?;
    let mut judged = parse(&reply, candidates.len())?;
    judged.cost = price_in(cfg.backend, cfg.usd_per_mtok_in)
        .map(|p| cost_of(&reply, p))
        .unwrap_or(0.0);
    judged.bears_at = cfg.bears_at;
    judged.cue_at = cfg.cue_at;
    Some(judged)
}

/// A persona's ballot as Jev answered it: the choice with its confidence
/// and the probability of every option, and its forecast of the share each
/// option gets from the rest of the panel.
#[derive(Debug, Clone, PartialEq)]
pub struct Ballot {
    pub choice: String,
    pub confidence: f64,
    pub probabilities: BTreeMap<String, f64>,
    pub forecast: BTreeMap<String, f64>,
    /// The machine's cut under which the ballot goes to a subagent.
    pub escalate_below: f64,
    /// The model that answered, so the ballot is recorded as that judge.
    pub model: String,
}

impl Ballot {
    /// Whether Jev is too unsure for its answer to stand as the ballot.
    #[must_use]
    pub fn escalates(&self) -> bool {
        self.confidence < self.escalate_below
    }
}

/// The ballot request: the persona's brief as state, one `choice` for its
/// own vote and one for what the rest of the panel will pick.
#[must_use]
pub fn ballot_request(model: &str, brief: &str, options: &[String]) -> Value {
    let criteria = |verb: &str| -> Value {
        options
            .iter()
            .map(|o| (o.clone(), Value::String(format!("{verb} {o}"))))
            .collect::<serde_json::Map<_, _>>()
            .into()
    };
    serde_json::json!({
        "model": model,
        "state": brief,
        "questions": {
            "ballot": {
                "type": "choice",
                "instructions": "You are the persona the state describes. Which option do you vote for, from your own view and what you know?",
                "criteria": criteria("vote for"),
            },
            "forecast": {
                "type": "choice",
                "instructions": "Which option will most of the other reviewers on this panel vote for?",
                "criteria": criteria("most others pick"),
            },
        }
    })
}

/// Read a ballot answer; `None` when either question went unanswered or
/// the choice is not one of the options.
#[must_use]
pub fn parse_ballot(body: &Value, options: &[String]) -> Option<Ballot> {
    let answers = body.get("answers")?;
    let probs = |key: &str| -> Option<BTreeMap<String, f64>> {
        let map = answers.get(key)?.get("probabilities")?.as_object()?;
        Some(
            map.iter()
                .filter_map(|(k, v)| Some((k.clone(), v.as_f64()?)))
                .collect(),
        )
    };
    let ballot = answers.get("ballot")?;
    let choice = ballot.get("choice")?.as_str()?.to_string();
    if !options.contains(&choice) {
        return None;
    }
    let probabilities = probs("ballot")?;
    let map: serde_json::Map<String, Value> = probabilities
        .iter()
        .map(|(k, v)| (k.clone(), Value::from(*v)))
        .collect();
    Some(Ballot {
        confidence: concentration(&map).unwrap_or(0.0),
        probabilities,
        forecast: probs("forecast")?,
        choice,
        escalate_below: 0.8,
        model: String::new(),
    })
}

/// The model the ballot route asks, when judging is on.
#[must_use]
pub fn ballot_model() -> Option<String> {
    let (cfg, _) = config()?;
    Some(
        judges_for(&cfg, "ballot")
            .into_iter()
            .next()
            .map(|(_, j, _)| j.model)
            .unwrap_or(cfg.model),
    )
}

/// Option order for one persona. Stable for that name, and different
/// names differ. The seed is [`crate::work_id`], not a process-random hash.
#[must_use]
pub fn shuffle_options(persona: &str, options: &[String]) -> Vec<String> {
    let mut out = options.to_vec();
    if out.len() < 2 {
        return out;
    }
    let hex = crate::work_id(&format!("ballot-options\n{persona}"));
    let mut state = u128::from_str_radix(&hex, 16).unwrap_or(1);
    if state == 0 {
        state = 1;
    }
    for i in (1..out.len()).rev() {
        state ^= state << 13;
        state ^= state >> 7;
        state ^= state << 17;
        let j = (state as usize) % (i + 1);
        out.swap(i, j);
    }
    out
}

/// Ask Jev for a persona's ballot on an issue.
#[must_use]
pub fn ballot(persona: &str, issue: &str, brief: &str, options: &[String]) -> Option<Ballot> {
    let (cfg, _) = config()?;
    let ordered = shuffle_options(persona, options);
    let body = ballot_request(&cfg.model, brief, &ordered);
    let about = serde_json::json!({"issue": issue, "persona": persona});
    let reply = post(&cfg, body, "ballot", about, &[])?;
    let mut b = parse_ballot(&reply, options)?;
    b.escalate_below = cfg.escalate_below;
    b.model = judges_for(&cfg, "ballot")
        .into_iter()
        .next()
        .map(|(_, j, _)| j.model)
        .unwrap_or_else(|| cfg.model.clone());
    Some(b)
}

/// SHA-256 of `data`, hex. The cache and the log store this, not the text.
#[must_use]
pub fn sha256_hex(data: &[u8]) -> String {
    fn rotr(x: u32, n: u32) -> u32 {
        x.rotate_right(n)
    }
    const K: [u32; 64] = [
        0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
        0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
        0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
        0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
        0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
        0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
        0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
        0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
        0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
        0xc67178f2,
    ];
    let mut h = [
        0x6a09e667_u32,
        0xbb67ae85,
        0x3c6ef372,
        0xa54ff53a,
        0x510e527f,
        0x9b05688c,
        0x1f83d9ab,
        0x5be0cd19,
    ];
    let bit_len = (data.len() as u64).wrapping_mul(8);
    let mut msg = data.to_vec();
    msg.push(0x80);
    while msg.len() % 64 != 56 {
        msg.push(0);
    }
    msg.extend_from_slice(&bit_len.to_be_bytes());
    for chunk in msg.chunks(64) {
        let mut w = [0u32; 64];
        for i in 0..16 {
            w[i] = u32::from_be_bytes(chunk[i * 4..i * 4 + 4].try_into().unwrap());
        }
        for i in 16..64 {
            let s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >> 3);
            let s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >> 10);
            w[i] = w[i - 16]
                .wrapping_add(s0)
                .wrapping_add(w[i - 7])
                .wrapping_add(s1);
        }
        let (mut a, mut b, mut c, mut d) = (h[0], h[1], h[2], h[3]);
        let (mut e, mut f, mut g, mut hh) = (h[4], h[5], h[6], h[7]);
        for i in 0..64 {
            let s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
            let ch = (e & f) ^ (!e & g);
            let t1 = hh
                .wrapping_add(s1)
                .wrapping_add(ch)
                .wrapping_add(K[i])
                .wrapping_add(w[i]);
            let s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
            let maj = (a & b) ^ (a & c) ^ (b & c);
            let t2 = s0.wrapping_add(maj);
            hh = g;
            g = f;
            f = e;
            e = d.wrapping_add(t1);
            d = c;
            c = b;
            b = a;
            a = t1.wrapping_add(t2);
        }
        h[0] = h[0].wrapping_add(a);
        h[1] = h[1].wrapping_add(b);
        h[2] = h[2].wrapping_add(c);
        h[3] = h[3].wrapping_add(d);
        h[4] = h[4].wrapping_add(e);
        h[5] = h[5].wrapping_add(f);
        h[6] = h[6].wrapping_add(g);
        h[7] = h[7].wrapping_add(hh);
    }
    h.iter().map(|x| format!("{x:08x}")).collect()
}

/// `$XDG_CACHE_HOME/ljos/jev`, mode 0700, one file per request hash.
fn cache_dir() -> Option<PathBuf> {
    let dir = std::env::var_os("XDG_CACHE_HOME")
        .filter(|v| !v.is_empty())
        .map(PathBuf::from)
        .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".cache")))?
        .join("ljos")
        .join("jev");
    std::fs::create_dir_all(&dir).ok()?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let _ = std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700));
    }
    Some(dir)
}

/// The file an identical request lands in. The name is the hash. The file
/// holds the hash and the reply, not the request.
fn cache_file(request: &str) -> Option<PathBuf> {
    Some(cache_dir()?.join(sha256_hex(request.as_bytes())))
}

/// The answer to an identical request made within `days`.
fn cached(request: &str, days: u64) -> Option<Value> {
    if days == 0 {
        return None;
    }
    let hash = sha256_hex(request.as_bytes());
    let path = cache_file(request)?;
    let age = std::fs::metadata(&path)
        .ok()?
        .modified()
        .ok()?
        .elapsed()
        .ok()?;
    if age > Duration::from_secs(days * 86_400) {
        let _ = std::fs::remove_file(&path);
        return None;
    }
    let entry: Value = serde_json::from_str(&std::fs::read_to_string(&path).ok()?).ok()?;
    (entry["hash"].as_str() == Some(hash.as_str())).then(|| entry["reply"].clone())
}

fn keep(request: &str, reply: &Value) {
    let hash = sha256_hex(request.as_bytes());
    let Some(path) = cache_file(request) else {
        return;
    };
    let entry = serde_json::json!({"hash": hash, "reply": reply});
    #[cfg(unix)]
    {
        use std::io::Write;
        use std::os::unix::fs::OpenOptionsExt;
        if let Ok(mut f) = std::fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(&path)
        {
            let _ = f.write_all(entry.to_string().as_bytes());
            use std::os::unix::fs::PermissionsExt;
            let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600));
        }
    }
    #[cfg(not(unix))]
    {
        let _ = std::fs::write(path, entry.to_string());
    }
}

/// Add one to this month's tally named `what` (`calls`, `cached`).
fn count(what: &str) {
    let Some(dir) = state_dir() else { return };
    let _ = std::fs::create_dir_all(&dir);
    let path = dir.join("jev-cost.toml");
    let mut totals: BTreeMap<String, f64> = std::fs::read_to_string(&path)
        .ok()
        .and_then(|t| toml::from_str(&t).ok())
        .unwrap_or_default();
    *totals
        .entry(format!("{}-{what}", this_month()))
        .or_default() += 1.0;
    if let Ok(text) = toml::to_string(&totals) {
        let _ = std::fs::write(path, text);
    }
}

/// The stop audit's cuts. A stop is held back only on a near-certain
/// answer: the model is asked about the agent's own words, and a false
/// block costs the person a turn.
pub const AUDIT_CLAIM_AT: f64 = 0.9;
/// The test run shown counts as red at or under this.
pub const AUDIT_RED_BELOW: f64 = 0.1;
/// The final message counts as deferring asked work at or over this.
pub const AUDIT_DEFER_AT: f64 = 0.9;

/// What Jev said about an agent about to stop.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Audit {
    /// The final message claims the work is done, passing or ready.
    pub claims_complete: f64,
    /// The last test output shown passes with no failure.
    pub tests_green: f64,
    /// The final message puts part of the asked work off, or out of scope.
    pub deferral: f64,
}

/// The audit request: the turn as state, three nouls.
#[must_use]
pub fn audit_request(model: &str, state: &str) -> Value {
    serde_json::json!({
        "model": model,
        "state": state,
        "questions": {
            "claims_complete": {
                "type": "noul",
                "instructions": "Does the agent's final message claim the asked work is done, complete, passing, green or ready?",
                "criteria": {
                    "true": "It says the work is finished or the tests pass",
                    "false": "It reports progress, a failure, a question or what is still open"
                }
            },
            "tests_green": {
                "type": "noul",
                "instructions": "Does the most recent test output in the state pass, with no failed, errored or crashed test?",
                "criteria": {
                    "true": "The latest run reports every test passing",
                    "false": "The latest run reports a failure, an error, a crash or a build that did not finish"
                }
            },
            "deferral": {
                "type": "noul",
                "instructions": "Does the final message put part of what the person asked off to later, or call it out of scope, without naming something outside the agent's control that blocks it?",
                "criteria": {
                    "true": "It leaves asked work for a later change, session or person, with no external block",
                    "false": "It finishes the asked work, or names a real block such as a missing credential or a failing external service"
                }
            }
        }
    })
}

/// Read the audit; `None` on a partial answer.
#[must_use]
pub fn parse_audit(body: &Value) -> Option<Audit> {
    let a = body.get("answers")?;
    let noul = |k: &str| a.get(k)?.get("noul")?.as_f64();
    Some(Audit {
        claims_complete: noul("claims_complete")?,
        tests_green: noul("tests_green")?,
        deferral: noul("deferral")?,
    })
}

/// Ask Jev about a turn that is about to end.
#[must_use]
pub fn audit(state: &str) -> Option<Audit> {
    let (cfg, _) = config()?;
    let body = audit_request(&cfg.model, state);
    let reply = post(&cfg, body, "stop-audit", Value::Null, &[])?;
    parse_audit(&reply)
}

/// The probability at or over which a reviewed claim is graded recalled.
pub const REVIEW_HOLDS_AT: f64 = 0.9;
/// At or under this a reviewed claim is reported as contradicted, for the
/// agent to supersede or withdraw; a judge does not lapse it.
pub const REVIEW_FAILS_AT: f64 = 0.1;

/// The review request: the claim and the newer claims about the same
/// thing as state, one noul on whether it still holds.
#[must_use]
pub fn review_request(model: &str, claim: &str, newer: &[&str]) -> Value {
    let mut state = format!(
        "Stored claim under review:\n{claim}\n\nNewer stored claims on the same subject:\n"
    );
    if newer.is_empty() {
        state.push_str("(none)\n");
    }
    for (i, t) in newer.iter().enumerate() {
        state.push_str(&format!("[{i}] {t}\n"));
    }
    serde_json::json!({
        "model": model,
        "state": state,
        "questions": {
            "holds": {
                "type": "noul",
                "instructions": "Does the claim under review still hold, given the newer claims? With no newer claim, does it read as a durable fact or rule rather than a passing observation?",
                "criteria": {
                    "true": "Nothing newer contradicts or replaces it, and it states something that stays true",
                    "false": "A newer claim contradicts, corrects or replaces it, or it described a state that has passed"
                }
            }
        }
    })
}

/// Ask the review judges whether a claim still holds.
#[must_use]
pub fn review(id: &str, claim: &str, newer: &[&str]) -> Option<f64> {
    let (cfg, _) = config()?;
    let body = review_request(&cfg.model, claim, newer);
    let reply = post(&cfg, body, "review", serde_json::json!({"id": id}), &[])?;
    reply["answers"]["holds"]["noul"].as_f64()
}

/// Why a stop is held back, from the audit and whether a test ran in the
/// turn; `None` lets the agent stop.
#[must_use]
pub fn audit_reason(a: &Audit, test_ran: bool) -> Option<String> {
    if test_ran && a.claims_complete >= AUDIT_CLAIM_AT && a.tests_green <= AUDIT_RED_BELOW {
        return Some(
            "The final message says the work is done, and the last test run shown is red. \
             Say what still fails, or fix it, before stopping."
                .to_string(),
        );
    }
    if a.deferral >= AUDIT_DEFER_AT {
        return Some(
            "The final message leaves part of the asked work for later without naming what blocks it. \
             Do that part, or say in one sentence what outside the work blocks it."
                .to_string(),
        );
    }
    None
}

fn state_dir() -> Option<PathBuf> {
    Some(
        std::env::var_os("XDG_STATE_HOME")
            .filter(|v| !v.is_empty())
            .map(PathBuf::from)
            .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".local/state")))?
            .join("ljos"),
    )
}

/// The judge log, one JSON object per line. Missing file is an empty log.
#[must_use]
pub fn read_log() -> Vec<Value> {
    let Some(dir) = state_dir() else {
        return Vec::new();
    };
    crate::complete_rows(&crate::read_state_file(&dir.join("jev-log.jsonl")).unwrap_or_default())
}

/// Per-decision accuracy and calibration. A ballot joins `about.issue` to
/// an outcome's choice. A decision with no outcome is counted and not
/// scored. Brier is the mean squared error of confidence against a hit.
/// ECE is the weighted gap between mean confidence and hit rate in ten bins.
#[must_use]
pub fn score_log(entries: &[Value], outcomes: &BTreeMap<String, String>) -> String {
    let mut kinds: BTreeMap<String, Vec<&Value>> = BTreeMap::new();
    for entry in entries {
        let kind = entry
            .get("kind")
            .and_then(Value::as_str)
            .unwrap_or("unknown");
        kinds.entry(kind.to_string()).or_default().push(entry);
    }
    if kinds.is_empty() {
        return "no judge log\n".to_string();
    }
    let mut out = String::new();
    for (kind, rows) in &kinds {
        let timeouts = rows.iter().filter(|e| e["status"] == "timeout").count();
        let errors = rows.iter().filter(|e| e["status"] == "error").count();
        if kind != "ballot" {
            out.push_str(&format!(
                "{kind}  {} judged  {timeouts} timeout  {errors} error  no outcome to score\n",
                rows.len()
            ));
            continue;
        }
        let mut joined = 0usize;
        let mut correct = 0usize;
        let mut brier_sum = 0.0;
        let mut bins = [(0.0_f64, 0.0_f64, 0u32); 10];
        for entry in rows {
            let status = entry["status"].as_str().unwrap_or("ok");
            if status != "ok" && status != "cache" {
                continue;
            }
            let Some(issue) = entry["about"]["issue"].as_str() else {
                continue;
            };
            let Some(choice) = outcomes.get(issue) else {
                continue;
            };
            let Some(said) = entry["answers"]["ballot"]["choice"].as_str() else {
                continue;
            };
            let p = entry["answers"]["ballot"]["confidence"]
                .as_f64()
                .unwrap_or(0.0)
                .clamp(0.0, 1.0);
            let hit = if said == choice { 1.0 } else { 0.0 };
            joined += 1;
            if hit == 1.0 {
                correct += 1;
            }
            brier_sum += (p - hit).powi(2);
            let bin = ((p * 10.0) as usize).min(9);
            bins[bin].0 += p;
            bins[bin].1 += hit;
            bins[bin].2 += 1;
        }
        if joined == 0 {
            out.push_str(&format!(
                "{kind}  {} judged  {timeouts} timeout  {errors} error  no outcome to score\n",
                rows.len()
            ));
            continue;
        }
        let acc = correct as f64 / joined as f64;
        let brier = brier_sum / joined as f64;
        let mut ece = 0.0;
        for (sum_p, sum_o, n) in bins {
            if n == 0 {
                continue;
            }
            let n = f64::from(n);
            ece += (n / joined as f64) * ((sum_p / n) - (sum_o / n)).abs();
        }
        out.push_str(&format!(
            "{kind}  {} judged  {joined} with an outcome  accuracy {acc:.2}  brier {brier:.2}  ece {ece:.2}  {timeouts} timeout  {errors} error\n",
            rows.len()
        ));
    }
    out
}

/// Every answer Jev gave, one JSON line each in the state directory, so
/// its probabilities can be scored once the outcomes are known.
fn log(entry: &Value) {
    let Some(dir) = state_dir() else { return };
    let _ = std::fs::create_dir_all(&dir);
    let Ok(mut line) = serde_json::to_string(entry) else {
        return;
    };
    line.push('\n');
    let _ = crate::append_locked_row(
        &dir.join("jev-log.jsonl"),
        line.as_bytes(),
        crate::Durability::BestEffort,
    );
}

/// Add a call's cost to this month's running total in the state directory,
/// so `ljos doctor` can say what Jev has cost.
fn record_cost(cost: f64) {
    let Some(dir) = state_dir() else { return };
    let _ = std::fs::create_dir_all(&dir);
    let month = crate::now_utc().chars().take(7).collect::<String>();
    let path = dir.join("jev-cost.toml");
    let mut totals: BTreeMap<String, f64> = std::fs::read_to_string(&path)
        .ok()
        .and_then(|t| toml::from_str(&t).ok())
        .unwrap_or_default();
    *totals.entry(format!("{month}-calls")).or_default() += 1.0;
    *totals.entry(month).or_default() += cost;
    if let Ok(text) = toml::to_string(&totals) {
        let _ = std::fs::write(path, text);
    }
}

fn month_totals() -> Option<BTreeMap<String, f64>> {
    let dir = state_dir()?;
    let text = std::fs::read_to_string(dir.join("jev-cost.toml")).ok()?;
    toml::from_str(&text).ok()
}

fn this_month() -> String {
    crate::now_utc().chars().take(7).collect()
}

/// This month's recorded Jev spend, in US dollars.
#[must_use]
pub fn month_cost() -> Option<f64> {
    month_totals()?.get(&this_month()).copied()
}

/// This month's tally named `what`: `calls` made, `cached` answered from
/// the cache.
#[must_use]
pub fn month_count(what: &str) -> u64 {
    month_totals()
        .and_then(|t| t.get(&format!("{}-{what}", this_month())).copied())
        .unwrap_or(0.0) as u64
}

/// How many calls this month made.
#[must_use]
pub fn month_calls() -> u64 {
    month_count("calls")
}

/// The `jev` row in `ljos doctor`, only on a machine with a Jev file: off,
/// on without its key, or on with this month's spend. A setting that does
/// not parse is not ok, since the hook then keeps its local path silently.
#[must_use]
pub fn doctor_row() -> Option<crate::Habitat> {
    let text = std::fs::read_to_string(config_path()).ok()?;
    let (state, ok) = match toml::from_str::<Config>(&text) {
        Err(e) => (format!("{}: {e}", config_path().display()), false),
        Ok(cfg) if !cfg.enabled => ("off".to_string(), true),
        Ok(cfg) => {
            let spent = month_cost().unwrap_or(0.0);
            let routes: Vec<String> = DECISIONS
                .iter()
                .filter(|(d, _)| cfg.route.contains_key(*d))
                .map(|(d, _)| format!("{d}={}", cfg.route_of(d).join("+")))
                .collect();
            let head = format!(
                "{} {}{}  {} calls, {} cached  ${spent:.4} of ${:.2} this month",
                cfg.backend.name(),
                cfg.model,
                if routes.is_empty() {
                    String::new()
                } else {
                    format!("  {}", routes.join(" "))
                },
                month_calls(),
                month_count("cached"),
                cfg.monthly_usd
            );
            if spent >= cfg.monthly_usd {
                (format!("capped  {head}"), true)
            } else if config().is_none() {
                let why = if cfg.backend == Backend::Command {
                    "on, but no command is set"
                } else {
                    "on, but the key file or command gave no key"
                };
                (why.to_string(), false)
            } else {
                (format!("on  {head}"), true)
            }
        }
    };
    Some(crate::Habitat {
        name: "jev",
        state,
        ok,
    })
}

/// Serialises tests that swap `XDG_CONFIG_HOME`.
/// The same lock as every other environment test, so a judge test cannot
/// clear a variable a hook test still needs.
#[cfg(test)]
pub(crate) fn judge_env_lock() -> crate::EnvLock {
    crate::test_env_lock()
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::os::unix::fs::PermissionsExt;

    fn env_lock() -> crate::EnvLock {
        judge_env_lock()
    }

    #[test]
    fn one_request_asks_about_every_candidate_and_both_cues() {
        let body = request("jev-1.13.0", "fix the ci", &["alpha claim", "beta claim"]);
        let q = body["questions"].as_object().unwrap();
        assert_eq!(
            q.len(),
            6,
            "two bears, correction, choice, injection, effort"
        );
        assert_eq!(q["bears_1"]["type"], "noul");
        assert_eq!(q["injection"]["type"], "noul");
        assert_eq!(q["effort"]["type"], "score");
        assert_eq!(q["effort"]["criteria"].as_array().unwrap().len(), 4);
        assert!(body["state"].as_str().unwrap().contains("[1] beta claim"));
    }

    #[test]
    fn a_full_answer_is_read_and_a_partial_one_is_refused() {
        let full = serde_json::json!({
            "answers": {
                "bears_0": {"type": "noul", "noul": 0.9},
                "bears_1": {"type": "noul", "noul": 0.1},
                "correction": {"type": "noul", "noul": 0.2},
                "choice": {"type": "noul", "noul": 0.7}
            },
            "usage": {"input_tokens": 900, "output_tokens": 40, "cost": 0.0000378}
        });
        let j = parse(&full, 2).unwrap();
        assert_eq!(j.bears, vec![0.9, 0.1]);
        assert!(j.bears(0) && !j.bears(1));
        let strict = Judgment {
            bears_at: 0.95,
            ..j.clone()
        };
        assert!(!strict.bears(0), "a higher cut drops the 0.9");
        assert!((j.choice - 0.7).abs() < 1e-9);
        assert!(
            (cost_of(&full, 0.042) - 0.0000378).abs() < 1e-12,
            "the API's figure"
        );
        let direct = serde_json::json!({"usage": {"input_tokens": 1000, "output_tokens": 60}});
        assert!(
            (cost_of(&direct, 0.042) - 0.000042).abs() < 1e-12,
            "tokens at the price"
        );
        let partial = serde_json::json!({"answers": {"bears_0": {"noul": 0.9}}});
        assert!(parse(&partial, 2).is_none());
    }

    #[test]
    fn jev_is_off_without_a_file_and_off_when_the_file_says_so() {
        let _lock = env_lock();
        let dir = tempfile::tempdir().unwrap();
        // Safety: the test sets and clears this for itself.
        unsafe { std::env::set_var("XDG_CONFIG_HOME", dir.path()) };
        assert!(config().is_none(), "no file, no call");
        std::fs::create_dir_all(dir.path().join("ljos")).unwrap();
        let key = dir.path().join("key");
        std::fs::write(&key, "sk-or-test\n").unwrap();
        std::fs::write(
            dir.path().join("ljos/jev.toml"),
            format!("enabled = false\nkey_file = \"{}\"\n", key.display()),
        )
        .unwrap();
        assert!(config().is_none(), "a file that says off is off");
        std::fs::write(
            dir.path().join("ljos/jev.toml"),
            format!("enabled = true\nkey_file = \"{}\"\n", key.display()),
        )
        .unwrap();
        let (cfg, k) = config().unwrap();
        assert_eq!(k, "sk-or-test");
        assert_eq!(cfg.budget_ms, 2000);
        assert_eq!(cfg.min_candidates, 2);
        unsafe { std::env::remove_var("XDG_CONFIG_HOME") };
    }

    #[test]
    fn a_chat_reply_is_read_in_jev_shape() {
        let body = request("m", "fix the ci", &["alpha claim", "beta claim"]);
        let chat = chat_request("m", &body);
        assert_eq!(chat["response_format"]["type"], "json_object");
        let user = chat["messages"][1]["content"].as_str().unwrap();
        assert!(user.contains("[1] beta claim") && user.contains("\"bears_1\""));
        let content = serde_json::json!({"answers": {
            "bears_0": 0.9,
            "bears_1": {"noul": 0.1},
            "correction": false,
            "choice": {"noul": 0.7}
        }});
        let reply = serde_json::json!({"answers": chat_answers(&body, &content)});
        let j = parse(&reply, 2).unwrap();
        assert_eq!(j.bears, vec![0.9, 0.1]);
        assert!((j.correction).abs() < 1e-9 && (j.choice - 0.7).abs() < 1e-9);
        let short = serde_json::json!({"answers": {"bears_0": 0.9}});
        let reply = serde_json::json!({"answers": chat_answers(&body, &short)});
        assert!(
            parse(&reply, 2).is_none(),
            "a missing answer refuses the reply"
        );
        let fenced = serde_json::json!({"choices": [{"message": {"content":
            "```json\n{\"answers\": {\"bears_0\": 1}}\n```"}}]});
        assert_eq!(content_json(&fenced).unwrap()["answers"]["bears_0"], 1);
    }

    #[test]
    fn injection_and_effort_are_read_when_answered_and_optional_when_not() {
        let with = serde_json::json!({"answers": {
            "bears_0": {"type": "noul", "noul": 0.9},
            "correction": {"type": "noul", "noul": 0.1},
            "choice": {"type": "noul", "noul": 0.1},
            "injection": {"type": "noul", "noul": 0.83},
            "effort": {"type": "score", "score": 2.4, "confidence": 0.4,
                       "probabilities": {"0": 0.0, "1": 0.1, "2": 0.4, "3": 0.5}}
        }});
        let j = parse(&with, 1).unwrap();
        assert_eq!(j.injection, Some(0.83));
        assert_eq!(j.effort, Some(2.4));
        let without = serde_json::json!({"answers": {
            "bears_0": {"noul": 0.9}, "correction": {"noul": 0.1}, "choice": {"noul": 0.1}
        }});
        let j = parse(&without, 1).unwrap();
        assert_eq!(
            (j.injection, j.effort),
            (None, None),
            "an older answer still parses"
        );

        let body = request("m", "fix the ci", &["alpha claim"]);
        let content = serde_json::json!({"answers": {
            "bears_0": 0.2, "correction": 0.0, "choice": 0.0, "injection": 0.1, "effort": 7.0
        }});
        let reply = serde_json::json!({"answers": chat_answers(&body, &content)});
        let j = parse(&reply, 1).unwrap();
        assert_eq!(
            j.effort,
            Some(3.0),
            "a chat score is clamped to the top level"
        );
    }

    #[test]
    fn a_chat_ballot_fills_what_the_model_left_out() {
        let options = vec!["A".to_string(), "B".to_string()];
        let body = ballot_request("m", "brief", &options);
        let content = serde_json::json!({"answers": {
            "ballot": {"choice": "A", "probabilities": {"A": 0.7, "B": 0.3}},
            "forecast": "B"
        }});
        let reply = serde_json::json!({"answers": chat_answers(&body, &content)});
        let b = parse_ballot(&reply, &options).unwrap();
        assert_eq!(b.choice, "A");
        // (K·p_max − 1)/(K − 1) = (2·0.7 − 1) = 0.4
        assert!(
            (b.confidence - 0.4).abs() < 1e-9,
            "confidence is (K·p_max − 1)/(K − 1), not the chosen probability: {}",
            b.confidence
        );
        let even: serde_json::Map<String, Value> =
            serde_json::from_str(r#"{"A": 0.5, "B": 0.5}"#).unwrap();
        assert!(concentration(&even).unwrap().abs() < 1e-12);
        assert_eq!(
            b.forecast.get("B").copied(),
            Some(1.0),
            "a bare choice is a sure one"
        );
    }

    #[test]
    fn the_command_backend_answers_from_stdout_and_needs_no_key() {
        let cfg: Config = toml::from_str(
            "enabled = true\nbackend = \"command\"\ncommand = [\"sh\", \"-c\", \
             \"cat >/dev/null; echo '{\\\"answers\\\": {\\\"bears_0\\\": 0.8, \\\"correction\\\": 0, \\\"choice\\\": 0.2}}'\"]\n",
        )
        .unwrap();
        assert_eq!(cfg.backend, Backend::Command);
        assert!(!cfg.backend.needs_key());
        let body = request("m", "fix the ci", &["alpha claim"]);
        let reply = command_post(&cfg.default_judge(), &body).unwrap();
        let j = parse(&reply, 1).unwrap();
        assert_eq!(j.bears, vec![0.8]);
        let silent: Config = toml::from_str(
            "enabled = true\nbackend = \"command\"\ncommand = [\"sh\", \"-c\", \"cat >/dev/null; echo {}\"]\n",
        )
        .unwrap();
        assert!(
            command_post(&silent.default_judge(), &body).is_none(),
            "no answer is a refusal"
        );
        let plain: Config = toml::from_str("enabled = true\n").unwrap();
        assert_eq!(plain.backend, Backend::Jev, "the default judge is Jev");
        assert!(plain.backend.needs_key());
    }

    #[test]
    fn judges_are_named_and_routed_and_unknown_names_drop_out() {
        let cfg: Config = toml::from_str(concat!(
            "enabled = true\nbackend = \"command\"\ncommand = [\"true\"]\n",
            "[judges.local]\nbackend = \"command\"\ncommand = [\"true\"]\nweight = 2.0\n",
            "[judges.nokey]\nbackend = \"jev\"\n",
            "[route]\nballot = [\"default\", \"local\", \"nokey\", \"nobody\"]\n",
        ))
        .unwrap();
        assert_eq!(
            cfg.route_of("prompt"),
            ["default"],
            "an unrouted decision goes to default"
        );
        let names: Vec<String> = judges_for(&cfg, "ballot")
            .into_iter()
            .map(|j| j.0)
            .collect();
        assert_eq!(
            names,
            ["default", "local"],
            "a judge with no key and an unknown name drop out"
        );
        assert!((cfg.judge("local").unwrap().weight - 2.0).abs() < 1e-12);
    }

    #[test]
    fn a_pool_averages_log_odds_and_multiplies_distributions() {
        let body = serde_json::json!({"questions": {
            "q": {"type": "noul"},
            "c": {"type": "choice", "criteria": {"A": "a", "B": "b"}},
            "s": {"type": "score", "criteria": ["0", "1", "2", "3"]},
            "missing": {"type": "noul"}
        }});
        let a = serde_json::json!({"q": {"noul": 0.9}, "c": {"choice": "A", "probabilities": {"A": 0.8, "B": 0.2}}, "s": {"score": 1.0}});
        let b = serde_json::json!({"q": {"noul": 0.1}, "c": {"choice": "B", "probabilities": {"A": 0.2, "B": 0.8}}, "s": {"score": 3.0}});
        let even = pool(&body, &[(1.0, a.clone()), (1.0, b.clone())]);
        assert!(
            (even["q"]["noul"].as_f64().unwrap() - 0.5).abs() < 1e-9,
            "opposed odds cancel"
        );
        assert!((even["c"]["probabilities"]["A"].as_f64().unwrap() - 0.5).abs() < 1e-9);
        assert!((even["s"]["score"].as_f64().unwrap() - 2.0).abs() < 1e-9);
        assert!(
            even.get("missing").is_none(),
            "no judge answered it, so the pool leaves it out"
        );
        let leaning = pool(&body, &[(3.0, a), (1.0, b)]);
        // (3 ln 9 - ln 9) / 4 = ln 3, so the pool is 3/4.
        assert!(
            (leaning["q"]["noul"].as_f64().unwrap() - 0.75).abs() < 1e-9,
            "weight moves the pool"
        );
        assert_eq!(leaning["c"]["choice"], "A");
        let agree = pool(
            &body,
            &[
                (1.0, serde_json::json!({"q": {"noul": 0.8}})),
                (1.0, serde_json::json!({"q": {"noul": 0.8}})),
            ],
        );
        assert!((agree["q"]["noul"].as_f64().unwrap() - 0.8).abs() < 1e-9);
    }

    #[test]
    fn a_key_line_gives_its_value() {
        assert_eq!(key_from("sk-or-v1-abc\n").as_deref(), Some("sk-or-v1-abc"));
        assert_eq!(
            key_from("apikey: sk-or-v1-abc\nurl: x\n").as_deref(),
            Some("sk-or-v1-abc")
        );
        assert_eq!(
            key_from("apikey=sk-or-v1-abc").as_deref(),
            Some("sk-or-v1-abc")
        );
        assert_eq!(key_from("\n"), None);
    }

    #[test]
    fn a_ballot_carries_its_confidence_and_forecast_and_escalates_under_the_cut() {
        let options = vec!["age".to_string(), "gpg".to_string()];
        let body = ballot_request("jev-1.13.0", "You are brio.", &options);
        assert_eq!(body["questions"]["ballot"]["type"], "choice");
        assert_eq!(
            body["questions"]["forecast"]["criteria"]["gpg"],
            "most others pick gpg"
        );
        let reply = serde_json::json!({"answers": {
            "ballot": {"type": "choice", "choice": "age", "confidence": 0.97,
                       "probabilities": {"age": 0.98, "gpg": 0.02}},
            "forecast": {"type": "choice", "choice": "age", "confidence": 0.95,
                         "probabilities": {"age": 0.97, "gpg": 0.03}}}});
        let b = parse_ballot(&reply, &options).unwrap();
        assert_eq!(b.choice, "age");
        assert!(!b.escalates(), "0.97 stands at the 0.8 cut");
        assert!((b.forecast["gpg"] - 0.03).abs() < 1e-9);
        let unsure = Ballot {
            confidence: 0.6,
            ..b.clone()
        };
        assert!(unsure.escalates(), "0.6 goes to a subagent");
        let off = serde_json::json!({"answers": {
            "ballot": {"choice": "rsa", "confidence": 0.9, "probabilities": {}},
            "forecast": {"choice": "age", "confidence": 0.9, "probabilities": {}}}});
        assert!(
            parse_ballot(&off, &options).is_none(),
            "a choice off the list is refused"
        );
    }

    #[test]
    fn an_identical_request_is_answered_from_the_cache_and_only_that_one() {
        let _lock = env_lock();
        let dir = tempfile::tempdir().unwrap();
        // Safety: the test sets and clears this for itself.
        unsafe { std::env::set_var("XDG_CACHE_HOME", dir.path()) };
        let reply = serde_json::json!({"answers": {"x": {"noul": 0.9}}});
        assert!(cached("req-a", 7).is_none(), "nothing kept yet");
        keep("req-a", &reply);
        assert_eq!(cached("req-a", 7), Some(reply.clone()));
        assert!(cached("req-b", 7).is_none(), "another request misses");
        assert!(cached("req-a", 0).is_none(), "0 days is off");
        let path = dir.path().join("ljos/jev").join(sha256_hex(b"req-a"));
        let stored = std::fs::read_to_string(&path).unwrap();
        assert!(
            !stored.contains("req-a"),
            "the file holds the hash, not the request: {stored}"
        );
        assert!(stored.contains("\"hash\""), "{stored}");
        let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode, 0o600, "cache file is mode 0600, got {mode:o}");
        let dir_mode = std::fs::metadata(path.parent().unwrap())
            .unwrap()
            .permissions()
            .mode()
            & 0o777;
        assert_eq!(
            dir_mode, 0o700,
            "cache directory is mode 0700, got {dir_mode:o}"
        );
        unsafe { std::env::remove_var("XDG_CACHE_HOME") };
    }

    #[test]
    fn a_stop_is_held_only_on_done_beside_red_or_an_open_deferral() {
        let a = |c: f64, g: f64, d: f64| Audit {
            claims_complete: c,
            tests_green: g,
            deferral: d,
        };
        assert!(
            audit_reason(&a(0.95, 0.05, 0.1), true).is_some(),
            "done beside red"
        );
        assert!(
            audit_reason(&a(0.95, 0.05, 0.1), false).is_none(),
            "no test ran, nothing to be red"
        );
        assert!(
            audit_reason(&a(0.95, 0.9, 0.1), true).is_none(),
            "done beside green"
        );
        assert!(
            audit_reason(&a(0.5, 0.05, 0.1), true).is_none(),
            "a red run reported as red"
        );
        assert!(
            audit_reason(&a(0.2, 0.9, 0.95), false).is_some(),
            "work put off"
        );
        let reply = serde_json::json!({"answers": {
            "claims_complete": {"noul": 0.9}, "tests_green": {"noul": 0.1}, "deferral": {"noul": 0.0}}});
        assert_eq!(parse_audit(&reply), Some(a(0.9, 0.1, 0.0)));
        assert_eq!(
            audit_request("m", "s")["questions"]
                .as_object()
                .unwrap()
                .len(),
            3
        );
    }

    #[test]
    fn sha256_of_empty_and_abc_match() {
        assert_eq!(
            sha256_hex(b""),
            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        );
        assert_eq!(
            sha256_hex(b"abc"),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
    }

    #[test]
    fn a_chat_judge_without_a_price_is_refused() {
        let chat: Config = toml::from_str(
            "enabled = true\nbackend = \"chat\"\nendpoint = \"http://127.0.0.1:9/v1\"\n",
        )
        .unwrap();
        assert_eq!(
            chat.default_judge().price_in(),
            Err("chat backend needs usd_per_mtok_in")
        );
        let priced: Config = toml::from_str(
            "enabled = true\nbackend = \"chat\"\nusd_per_mtok_in = 1.5\nendpoint = \"http://127.0.0.1:9/v1\"\n",
        )
        .unwrap();
        assert!((priced.default_judge().price_in().unwrap() - 1.5).abs() < 1e-12);
        let jev: Config = toml::from_str("enabled = true\n").unwrap();
        assert!((jev.default_judge().price_in().unwrap() - 0.042).abs() < 1e-12);
        let command: Config =
            toml::from_str("enabled = true\nbackend = \"command\"\ncommand = [\"true\"]\n")
                .unwrap();
        assert_eq!(command.default_judge().price_in().unwrap(), 0.0);
    }

    #[test]
    fn option_order_is_stable_per_persona_and_differs_across_them() {
        let options = vec!["age".into(), "gpg".into(), "minisign".into()];
        let a = shuffle_options("security-reviewer", &options);
        assert_eq!(a, shuffle_options("security-reviewer", &options));
        assert_eq!(a.len(), 3);
        assert!(a.contains(&"age".into()) && a.contains(&"gpg".into()));
        let b = shuffle_options("release", &options);
        assert_ne!(a, b, "two personas do not see the same order");
    }

    #[test]
    fn a_judge_log_scores_a_ballot_against_an_outcome() {
        let entries = vec![
            serde_json::json!({
                "kind": "ballot", "status": "ok",
                "about": {"issue": "ljos-1"},
                "answers": {"ballot": {"choice": "age", "confidence": 0.9}}
            }),
            serde_json::json!({
                "kind": "ballot", "status": "ok",
                "about": {"issue": "ljos-2"},
                "answers": {"ballot": {"choice": "gpg", "confidence": 0.2}}
            }),
            serde_json::json!({
                "kind": "ballot", "status": "timeout",
                "about": {"issue": "ljos-3"},
                "answers": null
            }),
            serde_json::json!({
                "kind": "hook", "status": "ok",
                "prompt_hash": "abc",
                "claims": [{"id": "c1", "kind": "lesson"}],
                "answers": {"bears_0": {"noul": 0.8}}
            }),
        ];
        let mut outcomes = BTreeMap::new();
        outcomes.insert("ljos-1".into(), "age".into());
        outcomes.insert("ljos-2".into(), "age".into());
        let report = score_log(&entries, &outcomes);
        assert!(
            report.contains("ballot  3 judged  2 with an outcome  accuracy 0.50"),
            "{report}"
        );
        assert!(report.contains("brier"), "{report}");
        assert!(report.contains("ece"), "{report}");
        assert!(report.contains("1 timeout"), "{report}");
        assert!(
            report.contains("hook  1 judged") && report.contains("no outcome to score"),
            "{report}"
        );
        assert_eq!(score_log(&[], &outcomes), "no judge log\n");
    }

    #[test]
    fn a_command_answer_is_logged_without_the_prompt() {
        let _lock = env_lock();
        let cfg_dir = tempfile::tempdir().unwrap();
        let state = tempfile::tempdir().unwrap();
        let cache = tempfile::tempdir().unwrap();
        unsafe {
            std::env::set_var("XDG_CONFIG_HOME", cfg_dir.path());
            std::env::set_var("XDG_STATE_HOME", state.path());
            std::env::set_var("XDG_CACHE_HOME", cache.path());
        }
        std::fs::create_dir_all(cfg_dir.path().join("ljos")).unwrap();
        std::fs::write(
            cfg_dir.path().join("ljos/jev.toml"),
            "enabled = true\nbackend = \"command\"\nmodel = \"local-1\"\ncommand = [\"sh\", \"-c\", \
             \"cat >/dev/null; echo '{\\\"answers\\\": {\\\"bears_0\\\": 0.8, \\\"correction\\\": 0, \\\"choice\\\": 0.2}}'\"]\n",
        )
        .unwrap();
        let claims = [LoggedClaim {
            id: "c1".into(),
            kind: "lesson".into(),
        }];
        let judged = judge("fix the ci tonight please", &["alpha claim"], &claims).unwrap();
        assert_eq!(judged.bears, vec![0.8]);
        let log = std::fs::read_to_string(state.path().join("ljos/jev-log.jsonl")).unwrap();
        assert!(!log.contains("fix the ci"), "{log}");
        assert!(!log.contains("alpha claim"), "{log}");
        assert!(log.contains("\"id\":\"c1\""), "{log}");
        assert!(log.contains("\"kind\":\"lesson\""), "{log}");
        assert!(log.contains("prompt_hash"), "{log}");
        assert!(log.contains("\"backend\":\"command\""), "{log}");
        assert!(log.contains("\"model\":\"local-1\""), "{log}");
        assert!(log.contains("\"status\":\"ok\""), "{log}");
        assert!(log.contains("latency_ms"), "{log}");
        std::fs::write(
            cfg_dir.path().join("ljos/jev.toml"),
            "enabled = true\nbackend = \"command\"\ncommand = [\"sh\", \"-c\", \"exit 1\"]\n",
        )
        .unwrap();
        assert!(judge("fix the ci tonight please", &["alpha claim"], &claims).is_none());
        let log = std::fs::read_to_string(state.path().join("ljos/jev-log.jsonl")).unwrap();
        assert!(log.contains("\"status\":\"error\""), "{log}");
        unsafe {
            std::env::remove_var("XDG_CONFIG_HOME");
            std::env::remove_var("XDG_STATE_HOME");
            std::env::remove_var("XDG_CACHE_HOME");
        }
    }

    /// A reader can meet an answer whose write is still under way, cut in
    /// the middle of a character. The rows before it are still the log.
    #[test]
    fn a_torn_last_answer_leaves_the_rest_of_the_log() {
        let _lock = env_lock();
        let state = tempfile::tempdir().unwrap();
        unsafe { std::env::set_var("XDG_STATE_HOME", state.path()) };
        let dir = state.path().join("ljos");
        std::fs::create_dir_all(&dir).unwrap();
        let mut bytes =
            b"{\"kind\":\"hook\",\"n\":1}\nnot json\n{\"kind\":\"hook\",\"n\":2}\n".to_vec();
        bytes.extend_from_slice(b"{\"kind\":\"hook\",\"prompt\":\"caf\xc3");
        std::fs::write(dir.join("jev-log.jsonl"), bytes).unwrap();
        let rows = read_log();
        assert_eq!(rows.len(), 2, "{rows:?}");
        assert_eq!(rows[1]["n"], 2);
    }

    /// The judge log is one JSON object per answer. Two answers landing
    /// together used to split a row across write calls, and a line that
    /// does not parse is an answer that cannot be scored.
    #[test]
    fn concurrent_log_rows_each_parse() {
        let _lock = env_lock();
        let state = tempfile::tempdir().unwrap();
        unsafe { std::env::set_var("XDG_STATE_HOME", state.path()) };
        const THREADS: usize = 32;
        const EACH: usize = 8;
        let mut handles = Vec::with_capacity(THREADS);
        for thread in 0..THREADS {
            handles.push(std::thread::spawn(move || {
                for n in 0..EACH {
                    log(&serde_json::json!({
                        "kind": "hook",
                        "status": "ok",
                        "thread": thread,
                        "n": n,
                        "prompt_hash": "abc",
                    }));
                }
            }));
        }
        for handle in handles {
            handle.join().expect("judge log writer");
        }
        let path = state.path().join("ljos/jev-log.jsonl");
        let text = std::fs::read_to_string(&path).unwrap();
        let rows: Vec<Value> = text
            .lines()
            .map(|line| {
                serde_json::from_str(line).unwrap_or_else(|err| {
                    panic!("judge log row does not parse ({err}): {line}");
                })
            })
            .collect();
        assert_eq!(rows.len(), THREADS * EACH, "{text}");
        let mode = std::fs::symlink_metadata(&path)
            .unwrap()
            .permissions()
            .mode()
            & 0o777;
        assert_eq!(mode, 0o600, "judge log mode {mode:o}");
    }
}