warble-cli 0.15.1

//! `warble` — the Warble CLI.
//!
//! One native binary across the CLI-target path:
//! - `compile`  — a Warble project → IR JSON (front-end compiler; host reads files, injects into
//!   the sans-IO `warble` core).
//! - `dispatch` — IR → a runtime target: Claude Code agent files (the `claude-code-cli` back-end)
//!   or a vercel bundle (the `vercel` back-end); both in Rust.
//! - `render`   — a captured agent envelope → deterministic `dashboard.html` (reference renderer).
//! - `manifest` — IR → capability manifest (interop advertisement).
//! - `eval compare` — result-set comparison for the eval loop (reads stdin JSON).

use clap::{Parser, Subcommand};
use std::io::Read;
use std::path::{Path, PathBuf};
use std::process::ExitCode;
use std::{fs, io};

use warble_claude_code::{
    build_manifest,
    ir::{validate_ir_version, WarbleIr},
    parse_envelope, render_envelope_to_html,
    slots::{resolve_ir_json, SlotSupply},
    ContextInjection, HybridRealization, ModelConfig, NativeMcpDescriptor, NativePurpose,
    NativeSessionScope, RenderFlavor, RenderOptions, DEFAULT_CONTEXT_INJECTION,
};
use warble_cli::{
    asset_dir_for_ir, blast_radius_for_project, check_compliance_ir_version,
    compile_project_to_ir_with_assets, default_component_sources_with_hub_version, gate,
    land_assets, BuiltinContextResolver, ComponentSource,
};
use warble_eval_compare::{compare, CompareRequest, CompareResult};
use warble_eval_runner::{
    build_candidate_yaml, candidates_header, effective_record_answers, format_ablation,
    format_compliance, format_gate, format_monitor_report, format_pareto, run_ablation, run_eval,
    run_gate, score_compliance, score_monitor_pair, stamp_context_version, verify_context,
    AblationConfig, Backend, CaptureInput, CaseFilter, ComplianceIr, ComplianceTrace, Freshness,
    Report, RunConfig,
};
use warble_vercel::{
    emit_vercel, known_target_names, parse_provider_fragments,
    validate_ir_version as validate_vercel_ir_version, ProviderFragment,
    TargetId as VercelTargetId, DEFAULT_TARGET,
};

mod context_check;
mod mcp_serve;

#[derive(Parser)]
#[command(
    name = "warble",
    version,
    about = "Warble — declarative data-agent behavior framework"
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Evaluate resolved context preconditions against a prepared-context snapshot from stdin.
    CheckContext,
    /// Compile a Warble project (profile + components + context binding) into IR JSON.
    Compile {
        project_dir: PathBuf,
        #[arg(short, long)]
        out: PathBuf,
        /// An additional Local-precedence component source directory (immediate children are
        /// `<id>/component.yml`). Repeatable. This is how a host outside this checkout mounts its
        /// own component library alongside the Hub, e.g. a product-specific set of components.
        /// Local sources (this flag + the project's own `components/` dir) all outrank Hub, but
        /// two Local sources defining the same id is an ambiguous, loud-fail configuration — no
        /// rule says which wins.
        #[arg(long = "component-dir")]
        component_dir: Vec<PathBuf>,
        /// Override the Hub component library root (defaults to this checkout's own
        /// `hub/components` when present, else a fetched-and-cached copy of the published Hub —
        /// see --hub-version). Lets a host point at a Hub library that lives outside this
        /// checkout, and fully bypasses network resolution: default resolution failing (e.g. no
        /// network) never affects this override.
        #[arg(long = "hub-dir", conflicts_with = "hub_version")]
        hub_dir: Option<PathBuf>,
        /// Fetch this Hub version instead of the CLI's own version, when resolving the Hub by
        /// default (i.e. no in-repo `hub/components` and no --hub-dir). A fixed release version
        /// only (e.g. "0.7.0") — a mutable ref such as "main" cannot be checksum-verified and is
        /// rejected.
        #[arg(long = "hub-version", conflicts_with = "hub_dir")]
        hub_version: Option<String>,
        /// Apply an overlay document to the profile before compiling: a small patch selecting
        /// which behaviors are mounted, the values bound to them, and which charter is used. This
        /// is how one set of behaviors serves several accounts without a profile file per
        /// account. It adds no IR field and carries its own format version, unrelated to
        /// `warble_ir_version`. Every ambiguous request in it is refused rather than resolved.
        #[arg(long = "overlay")]
        overlay: Option<PathBuf>,
    },
    /// Produce a versioned step plan for a host-owned session; never launches a runtime.
    ProduceSession {
        ir: PathBuf,
        /// Exact advertised entrypoint to prepare (not an internal component).
        #[arg(long)]
        component: String,
        /// Versioned host implementation claims; no credentials or vendor configuration.
        #[arg(long)]
        host_contract: PathBuf,
        /// New output JSON file. Existing files are never overwritten.
        #[arg(long)]
        out: PathBuf,
        /// Resolve a prompt slot with NAME=VARIANT, or NAME= to omit it.
        #[arg(long = "slot")]
        slot: Vec<String>,
    },
    /// Dispatch a compiled IR to a runtime target: Claude Code agent files, or a vercel bundle.
    Dispatch {
        ir: PathBuf,
        /// Target runtime (claude-code:headless | claude-code:interactive | codex:interactive |
        /// vercel | vercel:headless | vercel:interactive).
        #[arg(long, default_value = "claude-code:headless")]
        target: String,
        #[arg(long)]
        out: PathBuf,
        /// (claude-code target only) Render flavor for render-contract components (programmatic | prompt).
        #[arg(long = "render-flavor", default_value = "programmatic")]
        render_flavor: String,
        /// (claude-code target only) Tier→model config YAML (a `tiers:` map). Takes
        /// precedence over the inline --strong/--cheap/--orchestrator flags when given.
        #[arg(long = "models-config")]
        models_config: Option<PathBuf>,
        /// (claude-code target only) Model for the `strong` tier (inline tier→model binding; ignored if --models-config given).
        #[arg(long, default_value = "opus")]
        strong: String,
        /// (claude-code target only) Model for the `cheap` tier.
        #[arg(long, default_value = "haiku")]
        cheap: String,
        /// (claude-code target only) Model for the per-step-tier driver's routing loop.
        #[arg(long, default_value = "sonnet")]
        orchestrator: String,
        /// (claude-code target only) How a HYBRID binding's local step is realized on the file target (bash-script | mcp-server).
        #[arg(long = "hybrid-realization", default_value = "bash-script")]
        hybrid_realization: String,
        /// (native interactive targets only) Server-selected session purpose
        /// (analysis | setup | context_enrichment). Omitting this preserves the v1 enrichment
        /// launch contract for existing consumers.
        #[arg(long)]
        purpose: Option<String>,
        /// (native interactive targets with --purpose only) Immutable server-derived scope
        /// descriptor. Its canonical cwd must be exactly --out; Setup additionally carries its
        /// separate server-authorized bootstrap root, while bound projects carry the opaque
        /// binding identity, generation, and revision.
        #[arg(long = "native-scope")]
        native_scope: Option<PathBuf>,
        /// (native interactive targets with --purpose only) Exact server-derived MCP descriptor.
        /// Its opaque credential is materialized only into vendor-owned discovery configuration;
        /// it upgrades the native Sessions launch contract to v3.
        #[arg(long = "native-mcp")]
        native_mcp: Option<PathBuf>,
        /// Native composition host claims; requires v5 launch support and host-owned execution.
        #[arg(long = "native-host")]
        native_host: Option<PathBuf>,
        /// (Claude Code file and vercel targets only) A provider fragment file (YAML) contributing
        /// domain capabilities + tool bindings on top of the base substrate profile — repeatable.
        /// The fragment's engine must match the selected target. A bare dispatch with no matching
        /// provider loud-fails any domain capability the base target does not realize, naming which
        /// one is unresolved. Rejected by codex:interactive, which realizes no fragment capability.
        #[arg(long = "provider")]
        provider: Vec<PathBuf>,
        /// (vercel only) Closed host execution contract for bundle format 0.2.
        /// Requires a compatible host runtime; this declaration does not certify it.
        #[arg(long = "host-contract")]
        host_contract: Option<PathBuf>,
        /// Fill a named prompt slot: `--slot name=variant` renders that variant, `--slot name=`
        /// removes the slot because its condition does not hold. Repeatable. A slot nobody names
        /// takes its declared default — except one carrying a `present_when` condition, which is a
        /// loud failure when unanswered rather than a silent default, because shipping wording for
        /// something that may have been withheld is worse than shipping none.
        #[arg(long = "slot", value_name = "NAME=VARIANT")]
        slot: Vec<String>,
    },
    /// Render a captured agent envelope into a self-contained dashboard.html.
    Render {
        /// Envelope JSON file, or `-` for stdin.
        input: String,
        #[arg(short, long)]
        out: PathBuf,
        #[arg(long)]
        title: Option<String>,
    },
    /// Emit a profile's capability manifest from its IR.
    Manifest {
        ir: PathBuf,
        /// Write to this path instead of stdout.
        #[arg(short, long)]
        out: Option<PathBuf>,
    },
    /// Run the stdio MCP server for the file target's hybrid (mcp-server) realization: exposes a
    /// `local_infer` tool that runs a binding's local step on an OpenAI-compatible endpoint. Registered
    /// by the emitted `.mcp.json`; spawned by `claude` over stdio (not run by hand).
    McpServe {
        /// Path to the emitted `mcp-steps.json` (local step → endpoint/model/system).
        #[arg(long)]
        steps: PathBuf,
    },
    /// Eval utilities.
    #[command(subcommand)]
    Eval(EvalCommand),
    /// Compute a node's blast radius against a Warble project's bound wren project, and gate a
    /// pending mutating apply against it (Phase 4a).
    ///
    /// Exit codes: 0 = allow, 10 = escalate (route to human approval), 11 = block (protected
    /// asset — no escalation path). A resolution/parse error prints `error: ...` to stderr and
    /// exits 1.
    BlastRadius {
        /// The Warble project directory (contains profile.yml + context/binding.yml).
        project_dir: PathBuf,
        /// The lineage node id to compute the blast radius of (e.g. `model:orders`).
        #[arg(long)]
        node: String,
        /// Escalate when the radius severity rank is strictly above this. Ranks come from the
        /// bound layer's own severity scale — higher is worse — because what makes one impact
        /// worse than another is the layer's judgement, not warble's.
        #[arg(long = "max-severity-rank")]
        max_severity_rank: Option<u32>,
        /// Escalate when the downstream count is strictly above this.
        #[arg(long = "max-downstream")]
        max_downstream: Option<usize>,
        /// Comma-separated node ids that force a hard block if touched.
        #[arg(long, default_value = "")]
        protected: String,
    },
}

#[derive(Subcommand)]
enum EvalCommand {
    /// Compare an expected vs actual result set (reads a CompareRequest JSON from stdin).
    Compare,
    /// Replay golden questions through a dispatched agent under each tier→model binding and print a Pareto.
    Run {
        /// A queryable wren project (connection + data); agent files are installed here for the run.
        #[arg(long)]
        project: PathBuf,
        /// A dispatched agent output dir (contains `.claude/agents/…`). Required for
        /// `--backend claude-code-cli` (the default); mutually exclusive with `--ir`, which the
        /// other backends need instead.
        #[arg(long = "agent-dir")]
        agent_dir: Option<PathBuf>,
        /// Required for `--backend claude-agent-sdk` and `--backend codex-local`; unused by
        /// `claude-code-cli`. What it must point at differs per back-end:
        ///   - `claude-agent-sdk` dispatches directly from the IR (no pre-installed agent dir), so
        ///     pass the compiled IR JSON itself (from `warble compile`) here — it must compile to
        ///     a single-component IR, since the SDK's `dispatch` subcommand runs the question
        ///     against every component in the file, with no per-component filter.
        ///   - `codex-local` needs an external MCP server binding and a `--component` its own
        ///     `dispatch` CLI requires, neither of which fits the IR file itself — pass a small
        ///     JSON dispatch spec instead. The original implicit setup shape remains
        ///     `{ir_path, component, mcp: {command, ...}}`; answer work uses an explicit
        ///     `{shape: "ask", ir_path, component, codex_home, mcp: {command,
        ///     tools_by_step, ...}}` shape. Passing the compiled IR directly here (as you would
        ///     for `claude-agent-sdk`) fails loudly and names both accepted shapes. See the
        ///     "codex-local" section of
        ///     `docs/site/docs/guides/evaluating.md` for the full shape and a worked example.
        #[arg(long)]
        ir: Option<PathBuf>,
        /// Golden cases YAML.
        #[arg(long)]
        golden: PathBuf,
        /// Comma-separated model bindings to ablate.
        #[arg(long, default_value = "opus,haiku")]
        models: String,
        /// Write the full JSON report here.
        #[arg(long)]
        out: Option<PathBuf>,
        /// Concurrent cases per binding (1 = serial). 4-8 is a good speedup; note that under
        /// contention the per-case latency column also measures queueing.
        #[arg(long, default_value_t = 1)]
        parallel: usize,
        /// Only run goldens carrying at least one of these tags (comma-separated). Empty = all.
        #[arg(long, default_value = "")]
        tags: String,
        /// Sub-sample the (tag-filtered) goldens for a smoke run: `N` (count), a fraction `0.2` /
        /// `20%`, or `per-tag[:K]` (K per tag; the smoke default). Omit for a full run.
        #[arg(long)]
        sample: Option<String>,
        /// Bypass the trace cache: re-run every case (new LLM calls) and refresh its cached result.
        /// Without this, cases whose `(case, agent, model, context)` is unchanged are re-scored from
        /// cache with 0 LLM calls, so changing only a golden's `expected` re-scores in seconds.
        #[arg(long = "no-cache")]
        no_cache: bool,
        /// Trace cache directory. Default: `<project>/.warble/eval-cache`.
        #[arg(long = "cache-dir")]
        cache_dir: Option<PathBuf>,
        /// Repeated samples per case (pass-rate methodology). `1` (the default) is today's
        /// single-run behavior; `>1` distinguishes a genuinely flaky case from run-to-run noise.
        #[arg(long, default_value_t = 1)]
        samples: usize,
        /// Also record each sample's actual result value, or its raw final output when parsing
        /// fails, so a flaky or malformed case remains diagnosable. Off by default — heavier to
        /// store.
        #[arg(long = "record-answers")]
        record_answers: bool,
        /// Which back-end/runtime to replay the goldens through — a different axis from the
        /// per-back-end capability `--target` some subcommands take (e.g. `eval ablate`'s
        /// `claude-code:headless`): this picks *which dispatcher ran at all*, not a capability
        /// posture within one. Only back-ends with a real eval-runner adapter are accepted; an
        /// unrecognized spelling is rejected by clap, and a recognized-but-unsupported one (every
        /// back-end but the default, today) fails loudly at run time naming the supported set.
        /// Defaults to `claude-code-cli` so an invocation that never mentions this flag keeps
        /// measuring exactly what it always measured.
        #[arg(long, value_enum, default_value_t = Backend::ClaudeCodeCli)]
        backend: Backend,
        /// Cap the back-end's own dispatch on a turn budget instead of its default. Only
        /// `--backend claude-agent-sdk` has a `--max-turns` knob to honor this with (its dispatch
        /// CLI already parses and forwards one); passing this with any other `--backend` fails
        /// loudly naming the mismatch, rather than being silently ignored. Also part of the trace
        /// cache key, so a capped run never hits an uncapped (or differently-capped) run's cache.
        #[arg(long = "max-turns")]
        max_turns: Option<u32>,
        /// A differentiated tier→model binding for this run, matching `warble dispatch
        /// --models-config` (a `tiers:` map YAML). Takes precedence over the inline
        /// --strong/--cheap/--orchestrator flags when given. Only `--backend claude-agent-sdk` can
        /// honor a differentiated binding (its dispatch CLI has tier flags); any other `--backend`
        /// fails loudly naming the mismatch. Passing this bypasses the `--models` sweep entirely
        /// and runs one pass with the resolved binding instead; omit it (and the three inline
        /// flags below) to keep the pre-existing `--models` sweep unchanged.
        #[arg(long = "models-config")]
        models_config: Option<PathBuf>,
        /// Model for the `strong` tier (inline differentiated binding; ignored if
        /// --models-config is given). A differentiated binding needs all three of
        /// --strong/--cheap/--orchestrator — passing only some of them fails loudly rather than
        /// silently defaulting the rest.
        #[arg(long)]
        strong: Option<String>,
        /// Model for the `cheap` tier. See --strong.
        #[arg(long)]
        cheap: Option<String>,
        /// Model for the per-step-tier driver's routing loop. See --strong.
        #[arg(long)]
        orchestrator: Option<String>,
    },
    /// Per-step tier ablation (closed loop): re-dispatch the IR binding one named step at a time to
    /// each swept tier (others held at --base-tier), re-run the goldens, and print a per-step Pareto.
    Ablate {
        /// A queryable wren project (connection + data); agent files are installed here per dispatch.
        #[arg(long)]
        project: PathBuf,
        /// Compiled IR JSON (from `warble compile`). Re-dispatched per ablation point.
        #[arg(long)]
        ir: PathBuf,
        /// Golden cases YAML.
        #[arg(long)]
        golden: PathBuf,
        /// Dispatch target.
        #[arg(long, default_value = "claude-code:headless")]
        target: String,
        /// Optional tier→model config YAML (`tiers:` map). Defaults to strong/cheap/orchestrator.
        #[arg(long = "models-config")]
        models_config: Option<PathBuf>,
        /// Comma-separated tiers to try per step.
        #[arg(long, default_value = "cheap,strong")]
        sweep: String,
        /// Tier every non-ablated step is pinned to (the reference point).
        #[arg(long = "base-tier", default_value = "strong")]
        base_tier: String,
        /// A tier qualifies for the recommendation if within this accuracy of the baseline.
        #[arg(long = "accuracy-drop-tolerance", default_value = "0.0")]
        accuracy_drop_tolerance: f64,
        /// Write the full JSON report here.
        #[arg(long)]
        out: Option<PathBuf>,
        /// Concurrent cases per dispatched point (1 = serial); see `eval run --parallel`.
        #[arg(long, default_value_t = 1)]
        parallel: usize,
        /// Only ablate against goldens carrying one of these tags (comma-separated). Empty = all.
        #[arg(long, default_value = "")]
        tags: String,
        /// Sub-sample the (tag-filtered) goldens; see `eval run --sample`. Omit for a full run.
        #[arg(long)]
        sample: Option<String>,
        /// Bypass the trace cache: re-run every case at every point (see `eval run --no-cache`).
        #[arg(long = "no-cache")]
        no_cache: bool,
        /// Trace cache directory. Default: `<project>/.warble/eval-cache`.
        #[arg(long = "cache-dir")]
        cache_dir: Option<PathBuf>,
        /// Which back-end/runtime to run the ablation through — see `eval run --backend` for what
        /// this axis means and how it differs from `--target` above. The ablation loop re-dispatches
        /// IR via `claude-code-cli`'s own Rust emitter directly, so only that one back-end is
        /// supported here today; naming any other fails loudly at run time.
        #[arg(long, value_enum, default_value_t = Backend::ClaudeCodeCli)]
        backend: Backend,
    },
    /// Check a golden's `context_version` against the bound project's current MDL SHA (stale
    /// detection). `--stamp` re-pins to the current SHA; `--reverify` re-runs the goldens on a stale
    /// MDL to surface which cases the change actually moved. Non-zero exit when stale.
    VerifyContext {
        /// Golden cases YAML (its `context_version` is the pin being checked).
        #[arg(long)]
        golden: PathBuf,
        /// The bound wren project whose MDL SHA is computed.
        #[arg(long)]
        project: PathBuf,
        /// Re-pin the golden's `context_version` to the current MDL SHA (accept the new MDL).
        #[arg(long)]
        stamp: bool,
        /// Treat a symbolic (unpinned) `context_version` as a failure too.
        #[arg(long)]
        strict: bool,
        /// On stale, re-run the goldens through this dispatched agent dir to surface the diff.
        #[arg(long = "agent-dir")]
        agent_dir: Option<PathBuf>,
        /// Model bindings for `--reverify` (comma-separated).
        #[arg(long, default_value = "haiku")]
        models: String,
        /// Re-run the goldens when stale (requires --agent-dir).
        #[arg(long)]
        reverify: bool,
    },
    /// Capture one confirmed run into a candidate golden case (local hook; NOT auto-accepted).
    Capture {
        /// The question that was answered.
        #[arg(long)]
        question: String,
        /// A stable case id for the golden.
        #[arg(long)]
        id: String,
        /// The captured result: a file with the agent's final text / `claude … --output-format json`
        /// envelope / a bare `{columns,rows}` object, or `-` for stdin.
        #[arg(long, default_value = "-")]
        result: String,
        /// Result comparison mode: scalar | set | ordered.
        #[arg(long = "match", default_value = "set")]
        match_mode: String,
        /// Numeric tolerance for the expected result.
        #[arg(long, default_value = "0.01")]
        tolerance: f64,
        /// Comma-separated tags.
        #[arg(long, default_value = "")]
        tags: String,
        /// The context version the result was confirmed against (used in a new candidates file header).
        #[arg(long = "context-version")]
        context_version: Option<String>,
        /// Dataset label (used in a new candidates file header).
        #[arg(long)]
        dataset: Option<String>,
        /// Append the candidate to this candidates file (created golden-shaped if absent). Omit for stdout.
        #[arg(long)]
        out: Option<PathBuf>,
    },
    /// CI gate (G4): fail (non-zero exit) if a candidate report regresses vs a baseline report.
    Gate {
        /// Baseline report JSON (a committed `warble eval run --out`).
        #[arg(long)]
        baseline: PathBuf,
        /// Candidate report JSON (the PR's `warble eval run --out`).
        #[arg(long)]
        report: PathBuf,
        /// A metric regresses only when it drops more than this below baseline.
        #[arg(long, default_value = "0.0")]
        tolerance: f64,
        /// Assert both reports were recorded against this back-end before gating (a belt-and-braces
        /// check distinct from the unconditional baseline-vs-candidate backend check `run_gate`
        /// itself always performs — that one catches "baseline and candidate disagree with each
        /// other"; this one catches "both agree, but not on the back-end this CI job intended to
        /// gate"). Omit to skip this extra assertion and rely on the built-in cross-check alone.
        #[arg(long, value_enum)]
        backend: Option<Backend>,
    },
    /// Join clean + injected verdict runs with a fault-injection manifest and gate the live
    /// precision / recall / false-alarm report.
    MonitorReport {
        /// Fault-injection manifest YAML produced by the driftwood generator.
        #[arg(long)]
        manifest: PathBuf,
        /// Clean-baseline `eval run --record-answers --out` report JSON.
        #[arg(long = "clean-report")]
        clean_report: PathBuf,
        /// Injected `eval run --record-answers --out` report JSON.
        #[arg(long = "injected-report")]
        injected_report: PathBuf,
        /// Write the joined monitor report JSON here as well as printing it.
        #[arg(long)]
        out: Option<PathBuf>,
    },
    /// Score a dispatched agent's tool-call trace against the IR's declared guardrails — a
    /// pure, deterministic, zero-LLM compliance check (exit 1 on any violation).
    Compliance {
        /// A trace JSON (`ComplianceTrace`): the component dispatched + its ordered tool-call events.
        #[arg(long)]
        trace: PathBuf,
        /// The compiled IR JSON the trace's component was dispatched from. Must carry a
        /// `warble_ir_version` this build understands — checked before scoring, same gate as
        /// `dispatch`/`manifest`.
        #[arg(long)]
        ir: PathBuf,
        /// Write the compliance report JSON here as well as printing it. Omit for print-only.
        #[arg(long)]
        out: Option<PathBuf>,
    },
}

fn main() -> ExitCode {
    let cli = Cli::parse();
    let result = match cli.command {
        Command::CheckContext => context_check::run(),
        Command::Compile {
            project_dir,
            out,
            component_dir,
            hub_dir,
            hub_version,
            overlay,
        } => run_compile(
            &project_dir,
            &out,
            &component_dir,
            hub_dir.as_deref(),
            hub_version.as_deref(),
            overlay.as_deref(),
        ),
        Command::ProduceSession {
            ir,
            component,
            host_contract,
            out,
            slot,
        } => run_produce_session(&ir, &host_contract, &component, &out, &slot),
        Command::Dispatch {
            ir,
            target,
            out,
            render_flavor,
            models_config,
            strong,
            cheap,
            orchestrator,
            hybrid_realization,
            purpose,
            native_scope,
            native_mcp,
            native_host,
            provider,
            host_contract,
            slot,
        } => run_dispatch(
            &ir,
            &target,
            &out,
            &render_flavor,
            models_config.as_deref(),
            strong,
            cheap,
            orchestrator,
            &hybrid_realization,
            purpose.as_deref(),
            native_scope.as_deref(),
            native_mcp.as_deref(),
            native_host.as_deref(),
            &provider,
            host_contract.as_deref(),
            &slot,
        ),
        Command::Render { input, out, title } => run_render(&input, &out, title.as_deref()),
        Command::Manifest { ir, out } => run_manifest(&ir, out.as_deref()),
        Command::McpServe { steps } => mcp_serve::run_mcp_serve(&steps),
        Command::Eval(EvalCommand::Compare) => return run_eval_compare(),
        Command::Eval(EvalCommand::Capture {
            question,
            id,
            result,
            match_mode,
            tolerance,
            tags,
            context_version,
            dataset,
            out,
        }) => run_eval_capture(
            &question,
            &id,
            &result,
            &match_mode,
            tolerance,
            &tags,
            context_version.as_deref(),
            dataset.as_deref(),
            out.as_deref(),
        ),
        Command::Eval(EvalCommand::Gate {
            baseline,
            report,
            tolerance,
            backend,
        }) => return run_eval_gate(&baseline, &report, tolerance, backend),
        Command::Eval(EvalCommand::MonitorReport {
            manifest,
            clean_report,
            injected_report,
            out,
        }) => {
            return run_eval_monitor_report(
                &manifest,
                &clean_report,
                &injected_report,
                out.as_deref(),
            )
        }
        Command::Eval(EvalCommand::Compliance { trace, ir, out }) => {
            return run_eval_compliance(&trace, &ir, out.as_deref())
        }
        Command::Eval(EvalCommand::VerifyContext {
            golden,
            project,
            stamp,
            strict,
            agent_dir,
            models,
            reverify,
        }) => {
            return run_eval_verify_context(
                &golden,
                &project,
                stamp,
                strict,
                agent_dir.as_deref(),
                &models,
                reverify,
            )
        }
        Command::Eval(EvalCommand::Run {
            project,
            agent_dir,
            ir,
            golden,
            models,
            out,
            parallel,
            tags,
            sample,
            no_cache,
            cache_dir,
            samples,
            record_answers,
            backend,
            max_turns,
            models_config,
            strong,
            cheap,
            orchestrator,
        }) => run_eval_run(
            &project,
            agent_dir.as_deref(),
            ir.as_deref(),
            &golden,
            &models,
            out.as_deref(),
            parallel,
            &tags,
            sample.as_deref(),
            no_cache,
            cache_dir,
            samples,
            record_answers,
            backend,
            max_turns,
            models_config.as_deref(),
            strong,
            cheap,
            orchestrator,
        ),
        Command::Eval(EvalCommand::Ablate {
            project,
            ir,
            golden,
            target,
            models_config,
            sweep,
            base_tier,
            accuracy_drop_tolerance,
            out,
            parallel,
            tags,
            sample,
            no_cache,
            cache_dir,
            backend,
        }) => run_eval_ablate(
            &project,
            &ir,
            &golden,
            &target,
            models_config.as_deref(),
            &sweep,
            &base_tier,
            accuracy_drop_tolerance,
            out.as_deref(),
            parallel,
            &tags,
            sample.as_deref(),
            no_cache,
            cache_dir,
            backend,
        ),
        Command::BlastRadius {
            project_dir,
            node,
            max_severity_rank,
            max_downstream,
            protected,
        } => {
            return run_blast_radius(
                &project_dir,
                &node,
                max_severity_rank,
                max_downstream,
                &protected,
            )
        }
    };
    match result {
        Ok(()) => ExitCode::SUCCESS,
        Err(message) => {
            eprintln!("error: {message}");
            ExitCode::FAILURE
        }
    }
}

// --- compile --------------------------------------------------------------------------------------

fn run_compile(
    project_dir: &Path,
    out: &Path,
    extra_component_dirs: &[PathBuf],
    hub_dir: Option<&Path>,
    hub_version: Option<&str>,
    overlay: Option<&Path>,
) -> Result<(), String> {
    // `--hub-dir` must short-circuit default resolution entirely rather than build the default
    // list and then swap the Hub entry out of it: default resolution can now fail outright (a
    // network fetch that finds no cached copy), and an explicit override must keep working
    // regardless — this is what makes `--hub-dir` a genuine escape hatch, not merely a preference,
    // when there is no network. `clap`'s `conflicts_with` on the two flags means `hub_version` is
    // never `Some` here.
    let mut sources = match hub_dir {
        Some(hub_dir) => vec![
            ComponentSource::local(project_dir.join("components")),
            ComponentSource::hub(hub_dir),
        ],
        None => default_component_sources_with_hub_version(project_dir, hub_version)?,
    };
    sources.extend(
        extra_component_dirs
            .iter()
            .map(|dir| ComponentSource::local(dir.clone())),
    );

    let (ir, assets) =
        compile_project_to_ir_with_assets(project_dir, &sources, &BuiltinContextResolver, overlay)?;
    let rendered = serde_json::to_string_pretty(&ir).map_err(|e| e.to_string())?;
    fs::write(out, rendered).map_err(|e| format!("failed to write {}: {e}", out.display()))?;
    // Assets travel beside the IR, because this is the only point that has their content: the
    // compiler is sans-IO and a dispatch has no component directory to re-read. An IR copied
    // without this directory fails loudly at dispatch rather than running without its files.
    // See decision-101.
    warble_cli::write_assets(&asset_dir_for_ir(out), &assets)
}

// --- dispatch -------------------------------------------------------------------------------------

fn run_produce_session(
    ir: &Path,
    host: &Path,
    component: &str,
    out: &Path,
    slots: &[String],
) -> Result<(), String> {
    use std::io::{Read, Write};
    let read_bounded = |path: &Path| -> Result<String, String> {
        let mut bytes = String::new();
        fs::File::open(path)
            .map_err(|e| format!("cannot open producer input: {e}"))?
            .take(warble_claude_code::session::MAX_INPUT_BYTES as u64 + 1)
            .read_to_string(&mut bytes)
            .map_err(|e| format!("cannot read producer input: {e}"))?;
        Ok(bytes)
    };
    let plan = warble_claude_code::session::produce_session(
        &read_bounded(ir)?,
        &read_bounded(host)?,
        component,
        &parse_slot_flags(slots)?,
    )
    .map_err(|e| e.to_string())?;
    let bytes = serde_json::to_vec(&plan).map_err(|e| e.to_string())?;
    // Validate everything before creating the sole artifact. Never write vendor discovery files.
    let mut options = fs::OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.mode(0o600);
    }
    let mut output = options
        .open(out)
        .map_err(|e| format!("cannot create session plan: {e}"))?;
    if let Err(error) = output.write_all(&bytes).and_then(|()| output.sync_all()) {
        drop(output);
        let _ = fs::remove_file(out);
        return Err(format!("cannot write session plan: {error}"));
    }
    Ok(())
}

#[allow(clippy::too_many_arguments)]
fn run_dispatch(
    ir_path: &Path,
    target: &str,
    out: &Path,
    render_flavor: &str,
    models_config: Option<&Path>,
    strong: String,
    cheap: String,
    orchestrator: String,
    hybrid_realization: &str,
    purpose: Option<&str>,
    native_scope_path: Option<&Path>,
    native_mcp_path: Option<&Path>,
    native_host_path: Option<&Path>,
    provider_paths: &[PathBuf],
    host_contract: Option<&Path>,
    slot_flags: &[String],
) -> Result<(), String> {
    let slots = parse_slot_flags(slot_flags)?;
    let purpose = purpose
        .map(|value| {
            NativePurpose::parse(value).ok_or_else(|| {
                format!(
                    "unknown --purpose '{value}' (expected: analysis, setup, context_enrichment)"
                )
            })
        })
        .transpose()?;
    if purpose.is_some() && target != "claude-code:interactive" && target != "codex:interactive" {
        return Err("--purpose is supported only by native interactive targets".to_string());
    }
    let native_scope = match (purpose, native_scope_path) {
        (Some(_), Some(path)) => {
            Some(NativeSessionScope::from_file(path).map_err(|e| e.to_string())?)
        }
        (Some(_), None) => {
            return Err(
                "native Sessions purpose requires a server-derived --native-scope descriptor"
                    .to_string(),
            )
        }
        (None, Some(_)) => {
            return Err("--native-scope requires a native Sessions --purpose".to_string())
        }
        (None, None) => None,
    };
    let native_mcp = match (purpose, native_mcp_path) {
        (Some(_), Some(path)) => {
            Some(NativeMcpDescriptor::from_file(path).map_err(|e| e.to_string())?)
        }
        (Some(_), None) | (None, None) => None,
        (None, Some(_)) => {
            return Err("--native-mcp requires a native Sessions --purpose".to_string())
        }
    };
    let native_host = if let Some(path) = native_host_path {
        if !slots.is_empty() {
            return Err("--native-host does not support --slot".into());
        }
        if native_mcp.is_none() {
            return Err("--native-host requires --native-mcp".into());
        }
        Some(
            warble_claude_code::native_host::NativeHost::prepare(
                &read_file(ir_path)?,
                &read_file(path)?,
                target,
                purpose.ok_or("--native-host requires --purpose analysis")?,
                native_scope
                    .as_ref()
                    .ok_or("--native-host requires --native-scope")?,
            )
            .map_err(|e| e.to_string())?,
        )
    } else {
        None
    };
    let hosted_native = native_host.is_some();
    // Validate every enum-shaped knob before target routing, so no target silently accepts a typo
    // by returning early. `vercel` and `codex:interactive` realize neither of these, but ignoring
    // a misspelled value is indistinguishable from honouring it; the caller asked for something
    // this build cannot do either way.
    let flavor = RenderFlavor::parse(render_flavor).ok_or_else(|| {
        format!("unknown --render-flavor '{render_flavor}' (expected: programmatic, prompt)")
    })?;
    let hybrid = HybridRealization::parse(hybrid_realization).ok_or_else(|| {
        format!(
            "unknown --hybrid-realization '{hybrid_realization}' (expected: bash-script, mcp-server)"
        )
    })?;
    // The vercel target is a wholly separate back-end (its own IR type, no render-flavor/model-tier/
    // hybrid-realization knobs), so it branches off before any claude-code-specific flag parsing.
    if is_vercel_target(target) {
        return run_vercel_dispatch(ir_path, target, out, provider_paths, host_contract, &slots);
    }
    if host_contract.is_some() {
        return Err("--host-contract is supported only by vercel targets".to_string());
    }
    if target == "codex:interactive" {
        // The claude-code target composes its domain capabilities from provider fragments, but
        // this one hands the session to Codex's own CLI and realizes no capability itself, so a
        // fragment here would silently do nothing. Say so rather than accept and ignore it.
        if !provider_paths.is_empty() {
            return Err("--provider is not supported for the codex:interactive target".to_string());
        }
        let ir = match native_host.as_ref() {
            Some(host) => host.ir().clone(),
            None => load_ir(ir_path, &slots)?,
        };
        warble_claude_code::emit_codex_interactive_with_host(
            &ir,
            out,
            purpose,
            native_scope,
            native_mcp,
            native_host,
        )
        .map_err(|e| e.to_string())?;
        return if hosted_native {
            Ok(())
        } else {
            land_ir_assets(ir_path, out)
        };
    }
    // A --models-config YAML wins; otherwise build a two-tier config from the inline flags.
    let models = match models_config {
        Some(path) => ModelConfig::from_yaml(&read_file(path)?).map_err(|e| e.to_string())?,
        None => ModelConfig::from_flags(strong, cheap, orchestrator),
    };
    let ir = match native_host.as_ref() {
        Some(host) => host.ir().clone(),
        None => load_ir(ir_path, &slots)?,
    };
    // The dispatcher receives only normalized context derived from the IR and never probes an
    // arbitrary path from it, so no host-side project read happens here at all.
    let context = ContextInjection::from_ir(&ir, DEFAULT_CONTEXT_INJECTION);
    // Domain capabilities reach this back-end the same way they reach the vercel one: through
    // provider fragments supplied at dispatch, never hardcoded in the target.
    let providers = load_claude_code_provider_fragments(provider_paths)?;
    warble_claude_code::emit_claude_code_with_native_host(
        &ir,
        out,
        target,
        flavor,
        &models,
        hybrid,
        &context,
        &providers,
        purpose,
        native_scope,
        native_mcp,
        native_host,
    )
    .map_err(|e| e.to_string())?;
    // After a successful emit: the agent needs its declared files present when it runs, and a
    // rejected dispatch must not leave a directory of them behind.
    if hosted_native {
        Ok(())
    } else {
        land_ir_assets(ir_path, out)
    }
}

/// Whether `--target` names the vercel back-end (`vercel` or `vercel:<mode>`), as opposed to the
/// default claude-code back-end.
fn is_vercel_target(target: &str) -> bool {
    target == "vercel" || target.starts_with("vercel:")
}

fn run_vercel_dispatch(
    ir_path: &Path,
    target: &str,
    out: &Path,
    provider_paths: &[PathBuf],
    host_contract: Option<&Path>,
    slots: &SlotSupply,
) -> Result<(), String> {
    let target_id = if target == "vercel" {
        DEFAULT_TARGET
    } else {
        VercelTargetId::parse(target).ok_or_else(|| {
            format!(
                "unknown --target '{target}' (expected: vercel, {})",
                known_target_names().join(", ")
            )
        })?
    };
    let providers = load_provider_fragments(provider_paths)?;
    if let Some(path) = host_contract {
        if !slots.is_empty() {
            return Err("hosted vercel does not support --slot".to_string());
        }
        warble_vercel::hosted::emit_hosted_vercel(
            &read_file(ir_path)?,
            &read_file(path)?,
            target_id,
            out,
            &providers,
        )
        .map_err(|e| e.to_string())?;
        return Ok(());
    }
    let ir = load_vercel_ir(ir_path, slots)?;
    emit_vercel(&ir, target_id, out, &providers).map_err(|e| e.to_string())?;
    land_ir_assets(ir_path, out)
}

/// Read and parse every `--provider` file into a flat list of fragments (a file may itself declare
/// one fragment or a `providers:` list of several). File I/O lives here, in the CLI — `emit_vercel`
/// and `compose_target` only ever see already-parsed `ProviderFragment` values.
/// The claude-code back-end's fragment loader. Deliberately separate from the vercel one: the two
/// back-ends parse the same fragment format into their own types, the arrangement `binding-spec.md`
/// describes for the tier→model binding. Sharing a parser would mean sharing their capability types,
/// which are per-target by design.
fn load_claude_code_provider_fragments(
    paths: &[PathBuf],
) -> Result<Vec<warble_claude_code::ProviderFragment>, String> {
    let mut fragments = Vec::new();
    for path in paths {
        let raw = read_file(path)?;
        let parsed = warble_claude_code::parse_provider_fragments(&raw)
            .map_err(|e| format!("failed to parse provider fragment {}: {e}", path.display()))?;
        fragments.extend(parsed);
    }
    Ok(fragments)
}

fn load_provider_fragments(paths: &[PathBuf]) -> Result<Vec<ProviderFragment>, String> {
    let mut fragments = Vec::new();
    for path in paths {
        let raw = read_file(path)?;
        let parsed = parse_provider_fragments(&raw)
            .map_err(|e| format!("failed to parse provider fragment {}: {e}", path.display()))?;
        fragments.extend(parsed);
    }
    Ok(fragments)
}

// --- render ---------------------------------------------------------------------------------------

fn run_render(input: &str, out: &Path, title: Option<&str>) -> Result<(), String> {
    let raw = read_input(input)?;
    let envelope = parse_envelope(&unwrap_cli_result(&raw)).map_err(|e| e.to_string())?;
    let options = RenderOptions {
        title: title.map(|t| t.to_string()),
    };
    let html = render_envelope_to_html(&envelope, &options);
    fs::write(out, html).map_err(|e| format!("failed to write {}: {e}", out.display()))?;
    eprintln!(
        "warble render: wrote {} ({} block(s))",
        out.display(),
        envelope.blocks.len()
    );
    Ok(())
}

/// Unwrap `claude -p --output-format json`, whose top-level object carries the agent's final text
/// under `.result`. Otherwise pass the input through to the envelope extractor.
fn unwrap_cli_result(raw: &str) -> String {
    if let Ok(serde_json::Value::Object(map)) = serde_json::from_str::<serde_json::Value>(raw) {
        if let Some(serde_json::Value::String(result)) = map.get("result") {
            return result.clone();
        }
    }
    raw.to_string()
}

// --- manifest -------------------------------------------------------------------------------------

fn run_manifest(ir_path: &Path, out: Option<&Path>) -> Result<(), String> {
    // Deliberately unresolved. The rule that an unanswered `present_when` is a loud failure exists
    // because wording for a capability that may have been withheld must never reach a model; a
    // structural snapshot reaches nobody but a reader, so applying it here would refuse to display
    // a perfectly valid profile. What a reader sees is the profile as authored, placeholders and
    // all, which is what a structural view should show.
    let ir = load_ir_unresolved(ir_path)?;
    let manifest = build_manifest(&ir);
    let json = format!(
        "{}\n",
        serde_json::to_string_pretty(&manifest).map_err(|e| e.to_string())?
    );
    match out {
        Some(path) => {
            fs::write(path, json)
                .map_err(|e| format!("failed to write {}: {e}", path.display()))?;
            eprintln!("warble manifest: wrote {}", path.display());
            Ok(())
        }
        None => {
            print!("{json}");
            Ok(())
        }
    }
}

// --- eval compare ---------------------------------------------------------------------------------

fn run_eval_compare() -> ExitCode {
    let mut input = String::new();
    if let Err(e) = io::stdin().read_to_string(&mut input) {
        eprintln!("{}", compare_error(format!("failed to read stdin: {e}")));
        return ExitCode::FAILURE;
    }
    match serde_json::from_str::<CompareRequest>(&input) {
        Ok(request) => {
            let result = compare(&request);
            println!(
                "{}",
                serde_json::to_string(&result).expect("result serializes")
            );
            if result.pass {
                ExitCode::SUCCESS
            } else {
                ExitCode::FAILURE
            }
        }
        Err(e) => {
            eprintln!("{}", compare_error(format!("invalid input JSON: {e}")));
            ExitCode::FAILURE
        }
    }
}

fn compare_error(reason: String) -> String {
    serde_json::to_string(&CompareResult {
        pass: false,
        reason,
    })
    .expect("result serializes")
}

// --- eval capture ---------------------------------------------------------------------------------

#[allow(clippy::too_many_arguments)]
fn run_eval_capture(
    question: &str,
    id: &str,
    result: &str,
    match_mode: &str,
    tolerance: f64,
    tags: &str,
    context_version: Option<&str>,
    dataset: Option<&str>,
    out: Option<&Path>,
) -> Result<(), String> {
    let raw = read_input(result)?;
    let result_text = unwrap_cli_result(&raw);
    let tags: Vec<String> = tags
        .split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_string)
        .collect();
    let input = CaptureInput {
        id,
        question,
        match_mode,
        numeric_tolerance: tolerance,
        tags,
        result_text: &result_text,
    };
    let block = build_candidate_yaml(&input)?;

    match out {
        Some(path) => {
            // Golden-shaped candidates file: write the header on first creation, else append the case.
            let body = if path.exists() {
                let existing = read_file(path)?;
                format!("{existing}{block}")
            } else {
                format!("{}{block}", candidates_header(dataset, context_version))
            };
            fs::write(path, body)
                .map_err(|e| format!("failed to write {}: {e}", path.display()))?;
            eprintln!(
                "warble eval capture: candidate '{id}' → {} (review, then move into the golden set)",
                path.display()
            );
            Ok(())
        }
        None => {
            print!("{}{block}", candidates_header(dataset, context_version));
            Ok(())
        }
    }
}

// --- eval gate ------------------------------------------------------------------------------------

/// Gate a candidate report against a baseline; non-zero exit on regression (the G4 hard line).
fn run_eval_gate(
    baseline: &Path,
    report: &Path,
    tolerance: f64,
    backend: Option<Backend>,
) -> ExitCode {
    let load = |path: &Path| -> Result<Report, String> {
        let raw = read_file(path)?;
        serde_json::from_str(&raw).map_err(|e| format!("parse {}: {e}", path.display()))
    };
    let (mut base, mut cur) = match (load(baseline), load(report)) {
        (Ok(b), Ok(c)) => (b, c),
        (Err(e), _) | (_, Err(e)) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    // Either report may predate repeated sampling (a `samples == 0` sentinel per case); migrate
    // both forward so the pass-rate-based gate logic always has real samples/pass_rate to compare.
    base.backfill_legacy();
    cur.backfill_legacy();
    // Belt-and-braces: `run_gate` itself unconditionally fails when baseline/candidate disagree on
    // backend, but that says nothing about whether they're BOTH the backend this CI job actually
    // intended to gate. `--backend`, when given, asserts that explicitly before the diff even runs.
    if let Some(want) = backend {
        if base.backend != want || cur.backend != want {
            eprintln!(
                "error: --backend {want} requested, but baseline is '{}' and candidate is '{}'",
                base.backend, cur.backend
            );
            return ExitCode::FAILURE;
        }
    }
    let result = run_gate(&base, &cur, tolerance);
    print!("{}", format_gate(&result));
    if result.passed {
        ExitCode::SUCCESS
    } else {
        ExitCode::FAILURE
    }
}

// --- eval monitor-report -------------------------------------------------------------------------

fn run_eval_monitor_report(
    manifest_path: &Path,
    clean_path: &Path,
    injected_path: &Path,
    out: Option<&Path>,
) -> ExitCode {
    let load_report = |path: &Path| -> Result<Report, String> {
        let raw = read_file(path)?;
        serde_json::from_str(&raw).map_err(|e| format!("parse {}: {e}", path.display()))
    };
    let manifest = match read_file(manifest_path) {
        Ok(raw) => raw,
        Err(e) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    let (clean, injected) = match (load_report(clean_path), load_report(injected_path)) {
        (Ok(clean), Ok(injected)) => (clean, injected),
        (Err(e), _) | (_, Err(e)) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    let report = match score_monitor_pair(&manifest, &clean, &injected) {
        Ok(report) => report,
        Err(e) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    print!("{}", format_monitor_report(&report));
    if let Some(path) = out {
        let json = match serde_json::to_string_pretty(&report) {
            Ok(json) => format!("{json}\n"),
            Err(e) => {
                eprintln!("error: failed to serialize monitor report: {e}");
                return ExitCode::FAILURE;
            }
        };
        if let Err(e) = fs::write(path, json) {
            eprintln!("error: failed to write {}: {e}", path.display());
            return ExitCode::FAILURE;
        }
        println!("report → {}", path.display());
    }
    if report.passed {
        ExitCode::SUCCESS
    } else {
        ExitCode::FAILURE
    }
}

// --- eval compliance --------------------------------------------------------------------------------

/// Score a dispatched agent's tool-call trace against the IR's declared guardrails. Pure and
/// zero-LLM: this function does the I/O (read + parse), `score_compliance` does the (equally
/// zero-LLM) reasoning. Non-zero exit on any guardrail violation — usable as a CI gate.
///
/// Validates `warble_ir_version` on the raw JSON before ever deserializing into `ComplianceIr` —
/// see [`check_compliance_ir_version`] for why the check lives here rather than on that type.
fn run_eval_compliance(trace_path: &Path, ir_path: &Path, out: Option<&Path>) -> ExitCode {
    let trace: ComplianceTrace = match read_file(trace_path)
        .and_then(|raw| serde_json::from_str(&raw).map_err(|e| format!("parse trace: {e}")))
    {
        Ok(t) => t,
        Err(e) => {
            eprintln!("error: failed to read trace {}: {e}", trace_path.display());
            return ExitCode::FAILURE;
        }
    };
    let ir_raw = match read_file(ir_path) {
        Ok(raw) => raw,
        Err(e) => {
            eprintln!("error: failed to read IR {}: {e}", ir_path.display());
            return ExitCode::FAILURE;
        }
    };
    if let Err(e) = check_compliance_ir_version(&ir_raw, ir_path) {
        eprintln!("error: {e}");
        return ExitCode::FAILURE;
    }
    let ir: ComplianceIr = match serde_json::from_str(&ir_raw).map_err(|e| format!("parse IR: {e}"))
    {
        Ok(i) => i,
        Err(e) => {
            eprintln!("error: failed to read IR {}: {e}", ir_path.display());
            return ExitCode::FAILURE;
        }
    };

    let report = score_compliance(&trace, &ir);
    print!("{}", format_compliance(&report));

    if let Some(out_path) = out {
        match serde_json::to_string_pretty(&report) {
            Ok(json) => {
                if let Err(e) = fs::write(out_path, json) {
                    eprintln!("error: failed to write {}: {e}", out_path.display());
                    return ExitCode::FAILURE;
                }
                println!("report → {}", out_path.display());
            }
            Err(e) => {
                eprintln!("error: failed to serialize report: {e}");
                return ExitCode::FAILURE;
            }
        }
    }

    if report.compliant {
        ExitCode::SUCCESS
    } else {
        ExitCode::from(1)
    }
}

// --- eval verify-context --------------------------------------------------------------------------

/// Check the golden's pin against the current MDL SHA; optionally stamp or reverify. Non-zero exit
/// when stale (or unpinned under --strict).
#[allow(clippy::too_many_arguments)]
fn run_eval_verify_context(
    golden: &Path,
    project: &Path,
    stamp: bool,
    strict: bool,
    agent_dir: Option<&Path>,
    models: &str,
    reverify: bool,
) -> ExitCode {
    let golden_text = match read_file(golden) {
        Ok(t) => t,
        Err(e) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    let meta: serde_yaml::Value = match serde_yaml::from_str(&golden_text) {
        Ok(m) => m,
        Err(e) => {
            eprintln!("error: parse golden: {e}");
            return ExitCode::FAILURE;
        }
    };
    let context_version = meta
        .get("context_version")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let dataset = meta
        .get("dataset")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    let result = match verify_context(context_version.as_deref(), project) {
        Ok(r) => r,
        Err(e) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    println!("\n=== Warble eval — context version check ===");
    println!("golden:      {}", golden.display());
    println!("current MDL: {}", result.current_sha);
    println!("freshness:   {:?} — {}", result.freshness, result.detail);

    // --stamp: re-pin to the current MDL SHA and exit clean (an explicit "accept this MDL").
    if stamp {
        match stamp_context_version(&golden_text, &result.current_sha, dataset.as_deref()) {
            Ok(updated) => {
                if let Err(e) = fs::write(golden, updated) {
                    eprintln!("error: write {}: {e}", golden.display());
                    return ExitCode::FAILURE;
                }
                println!("stamped: context_version re-pinned to current MDL SHA.");
                return ExitCode::SUCCESS;
            }
            Err(e) => {
                eprintln!("error: {e}");
                return ExitCode::FAILURE;
            }
        }
    }

    let is_failure = matches!(result.freshness, Freshness::Stale)
        || (strict && matches!(result.freshness, Freshness::Unpinned));

    // --reverify: on a stale MDL, re-run the goldens to show which cases the change actually moved
    // (a case that now fails against its pinned expected is a candidate for re-confirmation/retirement).
    if is_failure && reverify {
        match agent_dir {
            Some(dir) => {
                println!("\nreverify: re-running goldens against the changed MDL …");
                let cfg = RunConfig {
                    project: project.to_path_buf(),
                    agent_dir: Some(dir.to_path_buf()),
                    ir_path: None,
                    golden_path: golden.to_path_buf(),
                    models: models.split(',').map(|s| s.trim().to_string()).collect(),
                    out: None,
                    // Diagnostic re-run; serial keeps its latency column comparable to the
                    // original (parallel runs measure queueing too).
                    parallel: 1,
                    // Reverify surfaces which cases the MDL change moved — always the full set.
                    filter: CaseFilter::default(),
                    // Must actually re-run the agent against the changed MDL to see the diff, so
                    // bypass the cache (the new context_sha would miss anyway; this is explicit).
                    no_cache: true,
                    cache_dir: None,
                    // A diagnostic re-run — single-sample is all this needs.
                    samples: 1,
                    record_answers: false,
                    // `verify-context --reverify` has no `--backend` flag of its own (it's a
                    // diagnostic re-run of `eval run`, not a first-class eval invocation) — default
                    // to the reference back-end, matching this command's pre-existing behavior.
                    backend: Backend::default(),
                    // Same rationale as `backend` above: no `--max-turns` flag on this subcommand,
                    // so leave the back-end's own default turn budget in place.
                    max_turns: None,
                    // `verify-context --reverify` has no differentiated-binding flags of its own
                    // either — same rationale as `backend`/`max_turns` above.
                    tier_models: None,
                };
                match run_eval(&cfg) {
                    Ok(report) => {
                        print!("{}", format_pareto(&report));
                        println!(
                            "\nreverify: cases that now FAIL against their pinned expected are the \
diff — re-confirm the new result or retire the golden."
                        );
                    }
                    Err(e) => {
                        eprintln!("error: reverify run failed: {e}");
                        return ExitCode::FAILURE;
                    }
                }
            }
            None => eprintln!("note: --reverify needs --agent-dir; skipping the re-run."),
        }
    }

    if is_failure {
        println!("\nCONTEXT STALE — re-verify the goldens, then --stamp to re-pin (or retire).");
        ExitCode::FAILURE
    } else {
        ExitCode::SUCCESS
    }
}

// --- eval run -------------------------------------------------------------------------------------

/// Resolve `eval run`'s differentiated `--strong`/`--cheap`/`--orchestrator` (or
/// `--models-config`) binding, mirroring `warble dispatch`'s own precedence (`--models-config`
/// wins over the inline flags — see `run_dispatch`). Returns `None` when none of the four flags
/// were given, which keeps the pre-existing `--models` sweep behaving exactly as before (see
/// `RunConfig::tier_models`); a partial inline combination (e.g. only `--strong`) is an ambiguous
/// binding and fails loudly here, before `run_eval` ever validates it against the backend, rather
/// than silently filling in a default for the missing tier(s).
fn resolve_tier_models(
    models_config: Option<&Path>,
    strong: Option<String>,
    cheap: Option<String>,
    orchestrator: Option<String>,
) -> Result<Option<ModelConfig>, String> {
    if let Some(path) = models_config {
        return Ok(Some(
            ModelConfig::from_yaml(&read_file(path)?).map_err(|e| e.to_string())?,
        ));
    }
    match (strong, cheap, orchestrator) {
        (None, None, None) => Ok(None),
        (Some(strong), Some(cheap), Some(orchestrator)) => {
            Ok(Some(ModelConfig::from_flags(strong, cheap, orchestrator)))
        }
        (strong, cheap, orchestrator) => Err(format!(
            "a differentiated tier binding needs all three of --strong/--cheap/--orchestrator \
(or --models-config); got strong={strong:?}, cheap={cheap:?}, orchestrator={orchestrator:?} — \
pass all three, or omit all of them to keep the --models sweep"
        )),
    }
}

#[allow(clippy::too_many_arguments)]
fn run_eval_run(
    project: &Path,
    agent_dir: Option<&Path>,
    ir: Option<&Path>,
    golden: &Path,
    models: &str,
    out: Option<&Path>,
    parallel: usize,
    tags: &str,
    sample: Option<&str>,
    no_cache: bool,
    cache_dir: Option<PathBuf>,
    samples: usize,
    record_answers: bool,
    backend: Backend,
    max_turns: Option<u32>,
    models_config: Option<&Path>,
    strong: Option<String>,
    cheap: Option<String>,
    orchestrator: Option<String>,
) -> Result<(), String> {
    // Repeated sampling exists to check reproducibility, so recording each sample's answer
    // (`--record-answers`) defaults on once `--samples` > 1 even without the explicit flag — an
    // explicit flag still works and `samples == 1` behavior is untouched. See
    // `effective_record_answers`'s doc comment for the full rationale.
    let record_answers = effective_record_answers(record_answers, samples);
    let tier_models = resolve_tier_models(models_config, strong, cheap, orchestrator)?;
    let cfg = RunConfig {
        project: project.to_path_buf(),
        agent_dir: agent_dir.map(Path::to_path_buf),
        ir_path: ir.map(Path::to_path_buf),
        golden_path: golden.to_path_buf(),
        models: models.split(',').map(|s| s.trim().to_string()).collect(),
        out: out.map(Path::to_path_buf),
        parallel,
        filter: CaseFilter::from_flags(tags, sample)?,
        no_cache,
        cache_dir,
        samples,
        record_answers,
        backend,
        max_turns,
        tier_models,
    };
    let report = run_eval(&cfg)?;
    print!("{}", format_pareto(&report));
    if let Some(path) = out {
        let json = format!(
            "{}\n",
            serde_json::to_string_pretty(&report).map_err(|e| e.to_string())?
        );
        fs::write(path, json).map_err(|e| format!("failed to write {}: {e}", path.display()))?;
        println!("\nreport → {}", path.display());
    }
    Ok(())
}

// --- eval ablate ----------------------------------------------------------------------------------

#[allow(clippy::too_many_arguments)]
fn run_eval_ablate(
    project: &Path,
    ir: &Path,
    golden: &Path,
    target: &str,
    models_config: Option<&Path>,
    sweep: &str,
    base_tier: &str,
    accuracy_drop_tolerance: f64,
    out: Option<&Path>,
    parallel: usize,
    tags: &str,
    sample: Option<&str>,
    no_cache: bool,
    cache_dir: Option<PathBuf>,
    backend: Backend,
) -> Result<(), String> {
    let cfg = AblationConfig {
        project: project.to_path_buf(),
        ir_path: ir.to_path_buf(),
        golden_path: golden.to_path_buf(),
        target: target.to_string(),
        models_config_path: models_config.map(Path::to_path_buf),
        sweep_tiers: sweep.split(',').map(|s| s.trim().to_string()).collect(),
        base_tier: base_tier.to_string(),
        accuracy_drop_tolerance,
        out: out.map(Path::to_path_buf),
        parallel,
        filter: CaseFilter::from_flags(tags, sample)?,
        no_cache,
        cache_dir,
        backend,
    };
    let report = run_ablation(&cfg)?;
    print!("{}", format_ablation(&report));
    if let Some(path) = out {
        let json = format!(
            "{}\n",
            serde_json::to_string_pretty(&report).map_err(|e| e.to_string())?
        );
        fs::write(path, json).map_err(|e| format!("failed to write {}: {e}", path.display()))?;
        println!("\nreport → {}", path.display());
    }
    Ok(())
}

// --- blast-radius -----------------------------------------------------------------------------------

/// Compute `node`'s blast radius in the project bound at `project_dir`, gate it against the given
/// thresholds, and print a single pretty JSON object to stdout. Exit code carries the decision
/// (0 = allow, 10 = escalate, 11 = block) so a caller can branch on it without parsing output.
fn run_blast_radius(
    project_dir: &Path,
    node: &str,
    max_severity_rank: Option<u32>,
    max_downstream: Option<usize>,
    protected: &str,
) -> ExitCode {
    let protected: Vec<String> = protected
        .split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_string)
        .collect();
    let threshold = gate::GateThreshold {
        max_severity_rank,
        max_downstream,
        protected,
    };

    let impact = match blast_radius_for_project(project_dir, node) {
        Ok(r) => r,
        Err(e) => {
            eprintln!("error: {e}");
            return ExitCode::FAILURE;
        }
    };
    let (decision, reason) = gate::decide(node, impact.as_ref(), &threshold);

    // The severity is reported as the layer named and ranked it. Warble carries both through and
    // acts only on the rank.
    let output = serde_json::json!({
        "seed": node,
        "downstream": impact.as_ref().map(|i| i.downstream.clone()).unwrap_or_default(),
        "severity": impact.as_ref().map(|i| serde_json::json!({
            "rank": i.severity.rank,
            "name": i.severity.name,
        })),
        "decision": decision.as_str(),
        "reason": reason,
    });
    match serde_json::to_string_pretty(&output) {
        Ok(json) => println!("{json}"),
        Err(e) => {
            eprintln!("error: failed to serialize blast-radius result: {e}");
            return ExitCode::FAILURE;
        }
    }

    match decision {
        gate::GateDecision::Allow => ExitCode::SUCCESS,
        gate::GateDecision::Escalate => ExitCode::from(10),
        gate::GateDecision::Block => ExitCode::from(11),
    }
}

// --- helpers --------------------------------------------------------------------------------------

/// Reads and parses an `ir.json` for the claude-code target, validating `warble_ir_version` right
/// here at parse time (via the dispatcher's own `validate_ir_version`, not a `cli`-local copy of
/// the constant) — so every subcommand that goes through this function, not just `dispatch`, is
/// gated. `emit_claude_code_with_realization` also validates on its own path (belt-and-braces for
/// direct callers of the dispatcher crate), so the check here is intentionally redundant for
/// `dispatch` but is what closes the gap for `manifest` and any future subcommand that reads an IR.
/// Load an IR without resolving slots — for read-only, display-only paths (see `run_manifest`).
fn load_ir_unresolved(path: &Path) -> Result<WarbleIr, String> {
    let raw = read_file(path)?;
    let ir: WarbleIr = serde_json::from_str(&raw)
        .map_err(|e| format!("failed to parse IR {}: {e}", path.display()))?;
    validate_ir_version(&ir).map_err(|e| e.to_string())?;
    Ok(ir)
}

/// Land an IR's declared assets into the dispatch output directory, before anything is emitted.
///
/// Placed here rather than inside a back-end because every target the CLI dispatches needs the
/// files, and the manifest is target-neutral. A back-end embedded as a library lands them itself.
fn land_ir_assets(ir_path: &Path, out: &Path) -> Result<(), String> {
    let raw = read_file(ir_path)?;
    let ir: serde_json::Value = serde_json::from_str(&raw)
        .map_err(|e| format!("failed to parse IR {}: {e}", ir_path.display()))?;
    // Deliberately does NOT create `out` itself. Several targets guarantee they leave no output
    // directory behind on a rejected dispatch, and creating one here to hold files for a run that
    // never happened would break that. `land_assets` creates only the parents of files it writes,
    // so an IR with no assets touches nothing, and this is called after a successful emit.
    land_assets(&ir, ir_path, out).map(|_| ())
}

fn load_ir(path: &Path, slots: &SlotSupply) -> Result<WarbleIr, String> {
    let raw = resolve_ir_slots(path, slots)?;
    let ir: WarbleIr = serde_json::from_str(&raw)
        .map_err(|e| format!("failed to parse IR {}: {e}", path.display()))?;
    validate_ir_version(&ir).map_err(|e| e.to_string())?;
    Ok(ir)
}

/// Read an IR file and resolve its prompt slots before any target-specific type sees it.
///
/// Deliberately at the JSON level and shared by every loader here: the two Rust back-ends
/// deserialize the same document into two distinct `WarbleIr` types, so resolving after
/// deserialization would mean two implementations that could drift. Resolving once, here, means the
/// text every target receives came out of the same pass.
fn resolve_ir_slots(path: &Path, slots: &SlotSupply) -> Result<String, String> {
    let raw = read_file(path)?;
    resolve_ir_json(&raw, slots)
        .map_err(|e| format!("failed to resolve prompt slots in {}: {e}", path.display()))
}

/// Parse repeated `--slot name=variant` / `--slot name=` flags into a supply table.
///
/// An empty value is not an empty variant name: it is the host saying the slot's condition does not
/// hold and the wording must not appear at all. That distinction is the whole reason the flag takes
/// `name=` rather than requiring a variant.
fn parse_slot_flags(flags: &[String]) -> Result<SlotSupply, String> {
    let mut supply = SlotSupply::new();
    for flag in flags {
        let Some((name, variant)) = flag.split_once('=') else {
            return Err(format!(
                "--slot '{flag}' must be NAME=VARIANT, or NAME= to remove a conditional slot"
            ));
        };
        if name.is_empty() {
            return Err(format!("--slot '{flag}' has an empty slot name"));
        }
        let value = if variant.is_empty() {
            None
        } else {
            Some(variant.to_string())
        };
        if supply.insert(name.to_string(), value).is_some() {
            return Err(format!("--slot {name} was given more than once"));
        }
    }
    Ok(supply)
}

/// `emit_vercel` takes `warble_vercel`'s own `WarbleIr` type (distinct from
/// `warble_claude_code::ir::WarbleIr`, even though both deserialize the same IR JSON), so the
/// vercel dispatch path needs its own load function — validated the same way, via
/// `warble_vercel::validate_ir_version`, right at parse time.
fn load_vercel_ir(path: &Path, slots: &SlotSupply) -> Result<warble_vercel::ir::WarbleIr, String> {
    let raw = resolve_ir_slots(path, slots)?;
    let ir: warble_vercel::ir::WarbleIr = serde_json::from_str(&raw)
        .map_err(|e| format!("failed to parse IR {}: {e}", path.display()))?;
    validate_vercel_ir_version(&ir).map_err(|e| e.to_string())?;
    Ok(ir)
}

fn read_file(path: &Path) -> Result<String, String> {
    fs::read_to_string(path).map_err(|e| format!("failed to read {}: {e}", path.display()))
}

fn read_input(input: &str) -> Result<String, String> {
    if input == "-" {
        let mut buf = String::new();
        io::stdin()
            .read_to_string(&mut buf)
            .map_err(|e| format!("failed to read stdin: {e}"))?;
        Ok(buf)
    } else {
        read_file(Path::new(input))
    }
}

#[cfg(test)]
mod slot_flag_tests {
    use super::parse_slot_flags;

    #[test]
    fn slot_flags_distinguish_a_chosen_variant_from_a_removed_slot() {
        let supply = parse_slot_flags(&["charter=terse".to_string(), "verification=".to_string()])
            .expect("parses");
        assert_eq!(supply.get("charter"), Some(&Some("terse".to_string())));
        // `name=` is not an empty variant name; it is the host saying the condition does not hold,
        // which is why the flag takes a trailing `=` rather than requiring a variant.
        assert_eq!(supply.get("verification"), Some(&None));
    }

    #[test]
    fn slot_flags_refuse_a_missing_separator_an_empty_name_and_a_repeat() {
        assert!(parse_slot_flags(&["charter".to_string()])
            .expect_err("no separator")
            .contains("must be NAME=VARIANT"));
        assert!(parse_slot_flags(&["=terse".to_string()])
            .expect_err("empty name")
            .contains("empty slot name"));
        assert!(parse_slot_flags(&["a=b".to_string(), "a=c".to_string()])
            .expect_err("repeat")
            .contains("was given more than once"));
    }
}

#[cfg(test)]
mod resolve_tier_models_tests {
    use super::resolve_tier_models;

    /// No `--models-config` and none of the three inline flags: `eval run`'s pre-existing
    /// `--models` sweep must be untouched — this is the signal `run_eval_run` reads to skip
    /// setting `RunConfig::tier_models` at all.
    #[test]
    fn no_flags_at_all_resolves_to_none() {
        let resolved = resolve_tier_models(None, None, None, None).expect("not an error");
        assert!(
            resolved.is_none(),
            "absent flags must preserve the --models sweep path"
        );
    }

    /// All three inline flags given (and no `--models-config`): the three distinct values must
    /// reach `ModelConfig` unchanged.
    #[test]
    fn three_inline_flags_produce_a_config_with_the_three_distinct_values() {
        let resolved = resolve_tier_models(
            None,
            Some("sonnet".to_string()),
            Some("haiku".to_string()),
            Some("sonnet".to_string()),
        )
        .expect("three flags is a valid binding")
        .expect("three flags must resolve to Some");
        assert_eq!(resolved.require("strong").unwrap(), "sonnet");
        assert_eq!(resolved.require("cheap").unwrap(), "haiku");
        assert_eq!(resolved.require("orchestrator").unwrap(), "sonnet");
    }

    /// A partial inline combination (only `--strong`) is an ambiguous binding and must fail
    /// loudly, with an actionable message, before `run_eval` is ever reached — never silently
    /// default the missing tiers.
    #[test]
    fn partial_inline_flags_fail_loudly_with_an_actionable_message() {
        let err = resolve_tier_models(None, Some("sonnet".to_string()), None, None)
            .expect_err("a partial binding must be rejected");
        assert!(
            err.contains("--strong") && err.contains("--cheap") && err.contains("--orchestrator"),
            "error should name all three flags so the user knows what to add: {err}"
        );
    }

    /// `--models-config` wins over inline flags even when both are given, mirroring
    /// `warble dispatch`'s own `run_dispatch` precedence.
    #[test]
    fn models_config_wins_over_inline_flags_even_when_both_given() {
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("models.yaml");
        std::fs::write(
            &path,
            "tiers:\n  strong: opus\n  cheap: haiku\n  orchestrator: sonnet\n",
        )
        .expect("write models.yaml");

        // Inline flags are also present, but must be ignored once --models-config is given.
        let resolved = resolve_tier_models(
            Some(path.as_path()),
            Some("ignored-strong".to_string()),
            Some("ignored-cheap".to_string()),
            Some("ignored-orchestrator".to_string()),
        )
        .expect("models-config is a valid binding")
        .expect("models-config must resolve to Some");
        assert_eq!(resolved.require("strong").unwrap(), "opus");
        assert_eq!(resolved.require("cheap").unwrap(), "haiku");
        assert_eq!(resolved.require("orchestrator").unwrap(), "sonnet");
    }
}