amont-agent 2.17.0

//! `amont-agent` — a guard that inspects a shell command before Claude Code
//! runs it.
//!
//! Amont gates `git commit` and `git push`. Neither can see the command string
//! itself, and some defects live only there: `git push … | tail -5` reports the
//! pipe's exit status, so a rejected push reads as success and no git hook is
//! ever in a position to notice.
//!
//! This binary is not on the commit path and takes dependencies. It is a
//! sibling of `amont-fleet` in that respect: opt-in, installed separately, and
//! free to buy features with crates.
//!
//! ## argv
//!
//! The parse follows `crates/amont/src/main.rs` exactly, including its
//! hardest-won rule: **only position 0 is ever tested against the subcommand
//! table.** Everything after it is data. In `amont` that rule exists because a
//! git remote named `install` once ran the installer mid-push; the same class
//! of accident is available to anything that scans argv for a verb.

mod assertions;
mod atomic;
mod backtest;
mod civil;
mod compliance;
mod corpus;
mod decision;
mod doctor;
mod git;
mod gitconfig;
mod graduate;
mod guidance;
mod hook;
mod journal;
mod json;
mod mine;
mod payload;
mod rules;
mod session_state;
mod settings;
mod shape;
mod shell;
mod shim;
mod stale;
mod stance;
mod term;
mod transcript;
mod ui;

use std::ffi::OsString;
use std::path::PathBuf;
use std::process::ExitCode;

const USAGE: &str = "\
usage: amont-agent <command>

  hook                  read a Claude Code payload on stdin, decide
  install [--write]     add the hook to settings.json (prints it by default)
  uninstall [--write]   remove exactly what install added
  status                every rule, its stance, and what it has seen
  doctor                is the guard installed, runnable, and actually firing?
  corpus check          replay every reviewed judgement through the rules
  graduate <rule> --to advise|deny
  demote <rule>         back to observing, no questions asked
  mine [flags]          shapes the model got wrong that no rule names yet
  backtest [flags]      replay your transcripts through the rules
  explain <rule>        every match for one rule, for review
  check '<command>'     run the rules over one command, no stdin
  rules                 every rule, its default stance and its evidence

install/uninstall flags:
  --write               actually edit the file
  --reformat            accept a normalised file when we cannot match its style
  --project             .claude/settings.json instead of ~/.claude
  --local               .claude/settings.local.json

backtest/explain/mine flags:
  --transcripts <dir>   where the .jsonl transcripts live
  --since <YYYY-MM-DD>  ignore entries before this day
  --rule <id>           restrict to one rule (repeatable)
  --sample <n>          sample matches to print per rule
  --format cases        emit matches as reviewable case lines (explain, mine)
  --json                machine-readable output

mine flags:
  --window <n>          tool calls a correction may arrive within (default 3)
  --min-support <n>     calls a shape needs before it is proposed (default 5)
  --min-rate <0..1>     share of them that must have gone wrong (default 0.3)

explain flags:
  --rank novelty        label the matches least like the ones already reviewed

backtest flags:
  --compliance          per model, per week: what the model did NEXT after a
                        rule fired — did the advice change anything?
";

enum Sub {
    Hook,
    Install,
    Uninstall,
    Status,
    Doctor,
    Corpus,
    Graduate,
    Demote,
    Backtest,
    Explain,
    Mine,
    Check,
    Rules,
}

const SUBCOMMANDS: [(&str, Sub); 13] = [
    ("hook", Sub::Hook),
    ("install", Sub::Install),
    ("uninstall", Sub::Uninstall),
    ("status", Sub::Status),
    ("doctor", Sub::Doctor),
    ("corpus", Sub::Corpus),
    ("graduate", Sub::Graduate),
    ("demote", Sub::Demote),
    ("backtest", Sub::Backtest),
    ("explain", Sub::Explain),
    ("mine", Sub::Mine),
    ("check", Sub::Check),
    ("rules", Sub::Rules),
];

enum Invocation {
    Sub { name: Sub, args: Vec<OsString> },
    Help,
    Version,
    Usage(String),
}

fn parse(argv: Vec<OsString>) -> Invocation {
    let Some(first) = argv.first() else {
        return Invocation::Usage("no command given".into());
    };
    let head = first.to_string_lossy().into_owned();
    if head == "--help" || head == "-h" || head == "help" {
        return Invocation::Help;
    }
    if head == "--version" || head == "-V" {
        return Invocation::Version;
    }
    for (name, sub) in SUBCOMMANDS {
        if head == name {
            return Invocation::Sub {
                name: sub,
                args: argv[1..].to_vec(),
            };
        }
    }
    Invocation::Usage(format!("unknown command `{head}`"))
}

/// Die quietly when the reader hangs up, like every other Unix filter.
///
/// Rust ignores SIGPIPE at startup, so `amont-agent rules | head` panicked
/// with a backtrace the moment `head` closed the pipe — `println!` hit EPIPE
/// and EPIPE is a panic. Restoring SIGPIPE's default disposition makes the
/// exit what a shell user expects (killed by the signal, status 141).
///
/// It matters more here than in an ordinary filter. This binary's entire
/// claim is that it is composed and predictable in front of somebody's
/// shell; a stack trace out of `rules | head` reads as a crash in exactly
/// the tool you were deciding whether to trust with your commands. It is
/// also the one thing this crate did NOT inherit when it left the amont
/// workspace: amont's `main` has carried this since `list | head` panicked,
/// and the split copied the modules the crate imported rather than the ones
/// it should have.
///
/// `extern "C"` rather than a crate: std already links libc, and a signal
/// disposition is not worth a dependency. Windows has no SIGPIPE; there the
/// pipe-closed write fails an `Err` path instead of raising a signal, and
/// this is a no-op.
#[cfg(unix)]
fn die_on_sigpipe() {
    extern "C" {
        fn signal(signum: i32, handler: usize) -> usize;
    }
    const SIGPIPE: i32 = 13;
    const SIG_DFL: usize = 0;
    unsafe {
        signal(SIGPIPE, SIG_DFL);
    }
}

#[cfg(not(unix))]
fn die_on_sigpipe() {}

fn main() -> ExitCode {
    die_on_sigpipe();
    // Claude Code does not spawn us from git, but a session started inside a
    // git hook still carries GIT_DIR / GIT_WORK_TREE, and those beat
    // `current_dir` for every git command we run. `crate::git` builds
    // its own Commands and has no seam to pass an environment through, so the
    // scrub has to happen here. This is the same failure the test harness's
    // `strip_git_env` exists to prevent; it committed to the wrong repository
    // once.
    //
    // NAMED, not a `GIT_` prefix sweep. The sweep took `GIT_CONFIG_GLOBAL`
    // and `GIT_CONFIG_SYSTEM` with it, and those two say where config LIVES
    // rather than which repository this is — so a person who keeps their git
    // config somewhere other than `~/.gitconfig` had every stance they set
    // silently ignored, and this crate's own tests could not point the
    // reader at a fixture. amont's `rehearsal::strip_repo_env` draws the
    // line in the same place and for the same reason.
    for key in [
        "GIT_DIR",
        "GIT_WORK_TREE",
        "GIT_INDEX_FILE",
        "GIT_COMMON_DIR",
        "GIT_PREFIX",
        "GIT_OBJECT_DIRECTORY",
        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
        "GIT_NAMESPACE",
        "GIT_REFLOG_ACTION",
        "GIT_EXEC_PATH",
    ] {
        std::env::remove_var(key);
    }

    match parse(std::env::args_os().skip(1).collect()) {
        Invocation::Help => {
            print!("{USAGE}");
            ExitCode::SUCCESS
        }
        Invocation::Version => {
            println!("amont-agent {}", env!("CARGO_PKG_VERSION"));
            ExitCode::SUCCESS
        }
        Invocation::Usage(why) => {
            eprintln!("amont-agent: {why}\n");
            eprint!("{USAGE}");
            ExitCode::from(2)
        }
        Invocation::Sub { name, args } => match name {
            // `hook` takes no flags: everything it needs arrives on stdin.
            // Claude Code may pass `--event <name>` for readability, and it is
            // accepted and ignored — the payload names its own event, and
            // trusting argv over the payload would let the two disagree.
            Sub::Hook => {
                let _ = args;
                hook::run()
            }
            Sub::Install => run_install(&args, true),
            Sub::Uninstall => run_install(&args, false),
            Sub::Status => run_status(),
            Sub::Doctor => {
                // Non-zero when the guard is not doing anything, so this is
                // usable from a cron job or a SessionStart check without
                // anybody having to read the text.
                if doctor::report(&doctor::run()) {
                    ExitCode::SUCCESS
                } else {
                    ExitCode::FAILURE
                }
            }
            Sub::Corpus => run_corpus(&args),
            Sub::Graduate => run_graduate(&args, true),
            Sub::Demote => run_graduate(&args, false),
            Sub::Backtest => run_backtest(&args, false),
            Sub::Explain => run_backtest(&args, true),
            Sub::Mine => run_mine(&args),
            Sub::Check => run_check(&args),
            Sub::Rules => run_rules(),
        },
    }
}

#[derive(Default)]
struct Flags {
    write: bool,
    reformat: bool,
    project: bool,
    local: bool,
    transcripts: Vec<PathBuf>,
    since: Option<civil::Day>,
    only: Vec<String>,
    sample: Option<usize>,
    json: bool,
    format: Option<String>,
    to: Option<String>,
    force: bool,
    window: Option<usize>,
    min_support: Option<u32>,
    min_rate: Option<f64>,
    rank: Option<String>,
    compliance: bool,
    rest: Vec<String>,
}

fn flags(args: &[OsString]) -> Result<Flags, String> {
    let mut f = Flags::default();
    let mut i = 0;
    while i < args.len() {
        let a = args[i].to_string_lossy().into_owned();
        let value = |i: &mut usize, what: &str| -> Result<String, String> {
            *i += 1;
            args.get(*i)
                .map(|v| v.to_string_lossy().into_owned())
                .ok_or_else(|| format!("{what} needs a value"))
        };
        match a.as_str() {
            "--transcripts" => f.transcripts.push(PathBuf::from(value(&mut i, &a)?)),
            "--since" => {
                let v = value(&mut i, &a)?;
                f.since =
                    Some(civil::day_of(&v).ok_or_else(|| format!("--since: `{v}` is not a date"))?);
            }
            "--rule" => f.only.push(value(&mut i, &a)?),
            "--sample" => {
                let v = value(&mut i, &a)?;
                f.sample = Some(
                    v.parse()
                        .map_err(|_| format!("--sample: `{v}` is not a number"))?,
                );
            }
            "--window" => {
                let v = value(&mut i, &a)?;
                f.window = Some(
                    v.parse()
                        .map_err(|_| format!("--window: `{v}` is not a number"))?,
                );
            }
            "--min-support" => {
                let v = value(&mut i, &a)?;
                f.min_support = Some(
                    v.parse()
                        .map_err(|_| format!("--min-support: `{v}` is not a number"))?,
                );
            }
            "--min-rate" => {
                let v = value(&mut i, &a)?;
                let rate: f64 = v
                    .parse()
                    .map_err(|_| format!("--min-rate: `{v}` is not a number"))?;
                if !(0.0..=1.0).contains(&rate) {
                    return Err(format!("--min-rate: `{v}` is not a share between 0 and 1"));
                }
                f.min_rate = Some(rate);
            }
            "--rank" => f.rank = Some(value(&mut i, &a)?),
            "--compliance" => f.compliance = true,
            "--json" => f.json = true,
            "--format" => f.format = Some(value(&mut i, &a)?),
            "--to" => f.to = Some(value(&mut i, &a)?),
            "--force" => f.force = true,
            "--write" => f.write = true,
            "--reformat" => f.reformat = true,
            "--project" => f.project = true,
            "--local" => f.local = true,
            other if other.starts_with('-') => return Err(format!("unknown flag `{other}`")),
            other => f.rest.push(other.to_string()),
        }
        i += 1;
    }
    Ok(f)
}

/// Which rules and assertions a backtest replays.
///
/// Both kinds answer to an id, and somebody asking "how often would this have
/// fired" does not care which list it came from.
fn selected(only: &[String]) -> Result<Vec<backtest::Subject>, String> {
    let everything = || {
        rules::RULES
            .iter()
            .map(backtest::Subject::Rule)
            .chain(
                assertions::ASSERTIONS
                    .iter()
                    .map(backtest::Subject::Assertion),
            )
            .collect::<Vec<_>>()
    };
    if only.is_empty() {
        return Ok(everything());
    }
    only.iter()
        .map(|id| {
            rules::by_id(id)
                .map(backtest::Subject::Rule)
                .or_else(|| assertions::by_id(id).map(backtest::Subject::Assertion))
                .ok_or_else(|| {
                    let known: Vec<&str> = everything().iter().map(|s| s.id()).collect();
                    format!("no rule `{id}` — known rules: {}", known.join(", "))
                })
        })
        .collect()
}

fn run_backtest(args: &[OsString], explain: bool) -> ExitCode {
    let mut f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    if explain {
        match f.rest.len() {
            1 => f.only.push(f.rest[0].clone()),
            _ => {
                eprintln!("amont-agent: explain needs exactly one rule");
                return ExitCode::from(2);
            }
        }
    }
    let chosen = match selected(&f.only) {
        Ok(c) => c,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    let roots = match transcript::roots(&f.transcripts) {
        Ok(r) => r,
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            return ExitCode::from(2);
        }
    };
    let scan = transcript::Scan {
        roots: &roots,
        tool: "Bash",
        since: f.since,
    };
    let as_cases = explain && f.format.as_deref() == Some("cases");
    if let Some(other) = f.format.as_deref() {
        if other != "cases" {
            eprintln!("amont-agent: --format takes `cases`, not `{other}`");
            return ExitCode::from(2);
        }
    }
    let novelty = match f.rank.as_deref() {
        None => false,
        Some("novelty") if explain => true,
        Some("novelty") => {
            eprintln!("amont-agent: --rank novelty is for `explain`, which prints the matches");
            return ExitCode::from(2);
        }
        Some(other) => {
            eprintln!("amont-agent: --rank takes `novelty`, not `{other}`");
            return ExitCode::from(2);
        }
    };
    if f.compliance {
        return run_compliance(&f, &roots, &scan, &chosen);
    }
    // A review dump wants everything, not a sample: the point is to look at
    // each match once and decide. Novelty ranking is the exception — it
    // answers "which twenty are worth an hour", and ordering every match by
    // novelty is quadratic in a number that runs to thousands.
    let samples = if novelty {
        usize::MAX
    } else {
        f.sample.unwrap_or(if as_cases {
            usize::MAX
        } else if explain {
            40
        } else {
            2
        })
    };
    match backtest::run(&scan, &chosen, samples) {
        Ok(mut report) => {
            if novelty {
                rank_by_novelty(&mut report, f.sample.unwrap_or(20));
            }
            if as_cases {
                // Every line starts unreviewed. The file this is appended to is
                // the same format the reviewer edits in place — one format, so
                // the review is a single pass with no export step to forget.
                println!("{}", corpus::HEADER);
                let mut seen = std::collections::BTreeSet::new();
                for group in &report.samples {
                    for sample in group {
                        if seen.insert(sample.command.clone()) {
                            print!(
                                "{}",
                                corpus::line_for(corpus::Verdict::Unreviewed, &sample.command)
                            );
                        }
                    }
                }
            } else if f.json {
                println!("{}", report.to_json(&roots));
            } else {
                print!("{}", report.render(&roots));
            }
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            ExitCode::from(2)
        }
    }
}

/// Keep the `n` matches least like the cases already reviewed, and least like
/// each other.
///
/// The default sample is the first `n` matches the walk met, which is the
/// oldest project, the oldest session, and — because a habit repeats — very
/// often twenty spellings of one command. Labelling those costs the same
/// hour and moves the precision estimate by almost nothing. This picks the
/// hour's worth that moves it most.
fn rank_by_novelty(report: &mut backtest::Report, n: usize) {
    for (i, subject) in report.rules.iter().enumerate() {
        // Already-labelled cases are seeds: they are the neighbourhoods the
        // corpus already covers, and a second review pass should not hand
        // back the first pass's cases.
        let seeds: Vec<shape::Shape> = corpus::read(subject.id())
            .iter()
            .map(|c| shape::Shape::of_command(&c.command))
            .collect();
        let candidates: Vec<shape::Shape> = report.samples[i]
            .iter()
            .map(|s| shape::Shape::of_command(&s.command))
            .collect();
        let picked = shape::pick_novel(&candidates, &seeds, n);
        // In the greedy order, which is "most novel first": a reviewer who
        // stops halfway has still labelled the half that was worth most.
        let mut held: Vec<Option<backtest::Sample>> =
            report.samples[i].drain(..).map(Some).collect();
        report.samples[i] = picked.iter().filter_map(|&j| held[j].take()).collect();
    }
}

fn run_compliance(
    f: &Flags,
    roots: &transcript::Roots,
    scan: &transcript::Scan,
    chosen: &[backtest::Subject],
) -> ExitCode {
    // Assertions check what a command that already ran actually did, so
    // "what did the model do next" is a different question with a different
    // answer. Named rather than silently dropped.
    let rules: Vec<&'static rules::Rule> = chosen
        .iter()
        .filter_map(|s| match s {
            backtest::Subject::Rule(r) => Some(*r),
            backtest::Subject::Assertion(_) => None,
        })
        .collect();
    if rules.is_empty() {
        eprintln!("amont-agent: --compliance is about rules, and none were selected");
        return ExitCode::from(2);
    }
    let options = compliance::Options {
        window: f.window.unwrap_or(compliance::Options::default().window),
    };
    match compliance::run(scan, &rules, options) {
        Ok(report) => {
            if f.json {
                println!("{}", report.to_json(roots));
            } else {
                print!("{}", report.render(roots));
            }
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            ExitCode::from(2)
        }
    }
}

fn run_mine(args: &[OsString]) -> ExitCode {
    let f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    if !f.only.is_empty() {
        eprintln!("amont-agent: mine looks for what no rule names yet, so --rule means nothing");
        return ExitCode::from(2);
    }
    let as_cases = f.format.as_deref() == Some("cases");
    if let Some(other) = f.format.as_deref() {
        if other != "cases" {
            eprintln!("amont-agent: --format takes `cases`, not `{other}`");
            return ExitCode::from(2);
        }
    }
    let roots = match transcript::roots(&f.transcripts) {
        Ok(r) => r,
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            return ExitCode::from(2);
        }
    };
    let scan = transcript::Scan {
        roots: &roots,
        tool: "Bash",
        since: f.since,
    };
    let default = mine::Options::default();
    let options = mine::Options {
        window: f.window.unwrap_or(default.window),
        min_support: f.min_support.unwrap_or(default.min_support),
        min_rate: f.min_rate.unwrap_or(default.min_rate),
        samples: f.sample.unwrap_or(default.samples),
    };
    match mine::run(&scan, options) {
        Ok(report) => {
            if as_cases {
                // The same file `explain --format cases` writes, and the same
                // one `corpus check` reads — so a shape mined today is a
                // reviewable case today, before anybody has written the rule
                // it might become.
                println!("{}", corpus::HEADER);
                let mut seen = std::collections::BTreeSet::new();
                for command in report.sample_commands() {
                    if seen.insert(command.to_string()) {
                        print!("{}", corpus::line_for(corpus::Verdict::Unreviewed, command));
                    }
                }
            } else if f.json {
                println!("{}", report.to_json(&roots));
            } else {
                print!("{}", report.render(&roots));
            }
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            ExitCode::from(2)
        }
    }
}

fn run_check(args: &[OsString]) -> ExitCode {
    let f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    if f.rest.len() != 1 {
        eprintln!("amont-agent: check needs exactly one command, quoted");
        return ExitCode::from(2);
    }
    let src = &f.rest[0];
    let parsed = shell::lex(src);
    if let shell::Parsed::Opaque(why) = &parsed {
        println!("no opinion: {}", why.why());
        return ExitCode::SUCCESS;
    }
    let found = rules::examine_all(&parsed);
    if found.is_empty() {
        println!("no rule fires");
        return ExitCode::SUCCESS;
    }
    for (rule, finding) in found {
        // The stance in force on THIS machine, which is what the hook would
        // do — with the shipped one beside it when they differ. Printing
        // only the default read `[advise]` for a rule long graduated to deny,
        // and the reader took it for the verdict.
        let now = stance::resolve(rule);
        if now == rule.default_stance {
            println!("{} [{}]", rule.id, now.as_str());
        } else {
            println!(
                "{} [{}, ships as {}]",
                rule.id,
                now.as_str(),
                rule.default_stance.as_str()
            );
        }
        println!("  {}", finding.reason);
        println!("  → {}", finding.remedy);
        println!(
            "  ▸ {}",
            backtest::excerpt(src, finding.span.start, finding.span.end)
        );
    }
    name_the_unread(src, &parsed);
    ExitCode::SUCCESS
}

/// Say which pipelines went unread, after the verdict.
///
/// The verdict stays on the first line so that "no rule fires" and "no
/// opinion" keep meaning what they meant. What follows is the difference
/// between having looked and having been able to look.
fn name_the_unread(src: &str, parsed: &shell::Parsed) {
    let clauses = parsed.clauses();
    for (i, cmd) in clauses.iter().enumerate() {
        let Some(why) = &cmd.opaque else { continue };
        // One line per unreadable PIPELINE: a clause whose predecessor pipes
        // into it is a later stage of a run already named.
        if cmd.prev.is_some_and(|c| c.is_pipe()) {
            continue;
        }
        let mut end = i;
        while clauses[end].next.is_some_and(|c| c.is_pipe()) && end + 1 < clauses.len() {
            end += 1;
        }
        println!("  ⋯ not read: {}", why.why());
        println!("    {}", backtest::excerpt(src, cmd.at, clauses[end].end));
    }
}

fn run_rules() -> ExitCode {
    let w = ui::id_column();
    for r in rules::RULES {
        println!(
            "{:<w$}{:<8} {:>6.1}/1000  measured {}",
            r.id,
            r.default_stance.as_str(),
            r.evidence.per_1000,
            r.evidence.measured
        );
    }
    // Listed apart, because they answer a different question: a rule judges a
    // command before it runs, an assertion checks what a command that already
    // reported success actually did.
    for a in assertions::ASSERTIONS {
        println!(
            "{:<w$}{:<8} {:>6.1}/1000  measured {}  (assertion)",
            a.id,
            a.default_stance.as_str(),
            a.evidence.per_1000,
            a.evidence.measured
        );
    }
    ExitCode::SUCCESS
}

fn run_install(args: &[OsString], adding: bool) -> ExitCode {
    let f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    let scope = if f.local {
        settings::Scope::ProjectLocal
    } else if f.project {
        settings::Scope::Project
    } else {
        settings::Scope::User
    };
    let project = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
    let Some(path) = scope.path(&project) else {
        eprintln!("amont-agent: cannot find your Claude Code settings directory");
        return ExitCode::from(2);
    };
    // The absolute path of THIS binary. A `PATH`-resolved command exits 127
    // into Claude Code's non-blocking bucket the moment PATH differs, which
    // disables the guard with nothing to notice it.
    let bin = match std::env::current_exe() {
        Ok(b) => b,
        Err(e) => {
            eprintln!("amont-agent: cannot resolve my own path: {e}");
            return ExitCode::from(2);
        }
    };

    let planned = if adding {
        settings::plan_install(&path, &bin, f.reformat)
    } else {
        settings::plan_uninstall(&path, f.reformat)
    };
    let plan = match planned {
        Ok(p) => p,
        Err(e) => {
            eprintln!("amont-agent: {}", e.explain());
            if adding {
                eprintln!("\n{}", settings::snippet(&bin));
            }
            return ExitCode::from(2);
        }
    };

    if !f.write {
        println!("{}", plan.change.describe(&plan.path));
        println!("Nothing written. Re-run with --write to apply:\n");
        print!("{}", plan.after);
        return ExitCode::SUCCESS;
    }
    if matches!(plan.change, settings::Change::WouldReformat) {
        eprintln!("{}\n", plan.change.describe(&plan.path));
        eprint!("{}", settings::snippet(&bin));
        return ExitCode::from(2);
    }
    match settings::apply(&plan) {
        Ok(()) => {
            println!("{}", plan.change.describe(&plan.path));
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("amont-agent: could not write {}: {e}", plan.path.display());
            ExitCode::from(2)
        }
    }
}

/// How far back `status` reads the journal. Long enough for a rule that
/// fires a few times a week to show a shape; short enough that a rule fixed a
/// month ago stops being judged on what it did before.
const SEEN_WINDOW: u64 = 30 * 24 * 60 * 60;

fn run_status() -> ExitCode {
    let w = ui::id_column();
    let seen = journal::tally(SEEN_WINDOW);
    println!(
        "{:<w$}{:<10}{:<10}  {:<31}  seen, last 30 days",
        "rule", "ships as", "now", "evidence"
    );
    for r in rules::RULES {
        let now = stance::resolve(r);
        println!(
            "{:<w$}{:<10}{:<10}  {:<31}  {}",
            r.id,
            r.default_stance.as_str(),
            now.as_str(),
            format!(
                "{:.1}/1000 measured {}",
                r.evidence.per_1000, r.evidence.measured
            ),
            describe_seen(seen.get(r.id))
        );
    }
    if let Some(p) = journal::path() {
        println!("\njournal: {}", p.display());
    }
    ExitCode::SUCCESS
}

/// One cell of the `seen` column.
///
/// The counts are what happened; the reason is why it did not. A rule whose
/// `confirm` declined a hundred times for `already in a linked worktree` is a
/// rule watching a convention being followed, and that is the sentence that
/// tells a reader whether the rule is precise or merely quiet.
fn describe_seen(seen: Option<&journal::Seen>) -> String {
    let Some(s) = seen.filter(|s| s.total() > 0) else {
        return "-".to_string();
    };
    let mut parts = Vec::new();
    for (n, what) in [
        (s.denied, "denied"),
        (s.advised, "advised"),
        (s.watched, "watched"),
    ] {
        if n > 0 {
            parts.push(format!("{n} {what}"));
        }
    }
    if s.unconfirmed > 0 {
        match s.top_reason() {
            // Records written before the reason was carried say `skipped`,
            // which is not a reason. Show the count and nothing invented.
            Some((why, n)) if why != "skipped" => parts.push(format!(
                "{} unconfirmed ({} \u{d7}{n})",
                s.unconfirmed,
                why.replace('_', " ")
            )),
            _ => parts.push(format!("{} unconfirmed", s.unconfirmed)),
        }
    }
    parts.join(", ")
}

fn run_corpus(args: &[OsString]) -> ExitCode {
    let f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    match f.rest.first().map(String::as_str) {
        Some("check") | None => {}
        Some(other) => {
            eprintln!("amont-agent: corpus takes `check`, not `{other}`");
            return ExitCode::from(2);
        }
    }
    let mut healthy = true;
    let w = ui::id_column();
    for rule in rules::RULES {
        let score = corpus::score(rule);
        if score.reviewed == 0 && score.unreviewed == 0 {
            println!("{:<w$}no cases yet", rule.id);
            continue;
        }
        let precision = match score.precision() {
            Some(p) => format!("{:.0}%", p * 100.0),
            None => "unmeasured".to_string(),
        };
        println!(
            "{:<w$}{} reviewed ({} negative), {} unreviewed, precision {precision}",
            rule.id, score.reviewed, score.negatives, score.unreviewed
        );
        for d in &score.disagreements {
            healthy = false;
            println!(
                "  {}:{} expected {} — {}",
                corpus::path_for(rule.id).display(),
                d.line,
                d.expected.as_str(),
                corpus::escape(&d.command)
            );
        }
    }
    if healthy {
        ExitCode::SUCCESS
    } else {
        ExitCode::FAILURE
    }
}

fn run_graduate(args: &[OsString], promoting: bool) -> ExitCode {
    let f = match flags(args) {
        Ok(f) => f,
        Err(why) => {
            eprintln!("amont-agent: {why}");
            return ExitCode::from(2);
        }
    };
    let Some(id) = f.rest.first() else {
        eprintln!("amont-agent: name a rule");
        return ExitCode::from(2);
    };
    let Some(rule) = rules::by_id(id) else {
        let known: Vec<&str> = rules::RULES.iter().map(|r| r.id).collect();
        eprintln!("amont-agent: no rule `{id}` — known: {}", known.join(", "));
        return ExitCode::from(2);
    };
    let to = if promoting {
        let Some(to) = f.to.as_deref().and_then(rules::Stance::parse) else {
            eprintln!("amont-agent: graduate needs --to advise|deny");
            return ExitCode::from(2);
        };
        to
    } else {
        rules::Stance::Observe
    };

    let verdict = graduate::assess(rule, to);
    for (ok, line) in &verdict.lines {
        println!(
            "  {} {line}",
            if *ok {
                crate::ui::valid_sign()
            } else {
                crate::ui::error_sign()
            }
        );
    }
    if !verdict.allowed && !f.force {
        // The file to append to is the checkout's. An installed copy has no
        // checkout, and naming the path of the machine that built it would
        // send the reader to a directory that exists nowhere near them.
        let where_ = if corpus::checkout_present() {
            corpus::path_for(rule.id).display().to_string()
        } else {
            format!(
                "tests/corpus/{}.cases   # in a checkout of amont-agent",
                rule.id
            )
        };
        eprintln!(
            "\nrefusing to move {} to {}: not enough evidence.\n\
             Review its matches first:\n  \
             amont-agent explain {} --format cases >> {}\n\
             then label each line and re-run. `--force` overrides and is recorded as forced.",
            rule.id,
            to.as_str(),
            rule.id,
            where_
        );
        return ExitCode::from(2);
    }
    match graduate::set(rule, to) {
        Ok(()) => {
            println!(
                "{} is now `{}`{}",
                rule.id,
                to.as_str(),
                if verdict.allowed { "" } else { " (forced)" }
            );
            ExitCode::SUCCESS
        }
        Err(why) => {
            eprintln!("amont-agent: could not record the stance: {why}");
            ExitCode::from(2)
        }
    }
}