newt-agent 0.8.0

//! The observability-contract record `newt headless` emits (W0 #1511, epic
//! #1506) — the wire format the EXTERNAL evaluator consumes.
//!
//! The contract (`gilamonster-bench/CONTRACT.md`, `contract_version: "2"`) is
//! **data, deliberately re-declared per consumer**: this module is newt's
//! emitter-side declaration, and the bench keeps its own consumer-side
//! structs. Do NOT extract a shared `-contract` crate — that re-introduces
//! the circularity the versioned wire format exists to prevent.
//!
//! Everything here is pure (inputs → `serde_json::Value`) so the record
//! shape is unit-tested without a run; `headless::run` supplies the inputs and
//! appends the lines to `--events`. Exactly ONE contract record is emitted
//! per headless — the bench keys on the presence of `contract_version` and
//! rejects ambiguous traces.

use newt_core::agentic::InstantiatedFeatures;
use newt_core::{BehaviorSignal, ErrorClass, ParseSignal, TurnEndReason};

/// The contract version this emitter declares. Bumped only on a breaking
/// change to field names/semantics; adding an optional field is not breaking.
///
/// `"2"` (psyche slice 1b): `effective_config.tenacity` changed meaning and
/// vocabulary (`normal` | `relentless`: pursuit only), and the
/// read-before-acting level it used to carry is the new
/// `effective_config.initiative` (`patient` | `measured` | `decisive` |
/// `eager`). A v1 row's `tenacity` is not comparable with a v2 row's.
pub const CONTRACT_VERSION: &str = "2";

/// Provenance: which family member emitted the record.
pub const AGENT: &str = "newt-agent";

/// Everything the contract record serializes, already resolved by the caller.
/// `model_digest` is operator-supplied ONLY (flag / env twin) — when absent
/// it is omitted from the record, never fabricated: a made-up digest would
/// defeat the exact reason the field exists (silent same-name re-uploads).
pub struct ContractInputs<'a> {
    /// What the matrix asked the agent to run (the resolved request model).
    pub requested_model: &'a str,
    /// What the backend actually resolved/served: the response body's `model`
    /// field when the backend reported one, else the request model (the
    /// caller documents which it had).
    pub effective_model: &'a str,
    /// Operator-supplied sha256 of the served weights; `None` ⇒ omitted.
    pub model_digest: Option<&'a str>,
    /// The resolved backend driven for this headless.
    pub backend_name: &'a str,
    /// Wire kind label (`openai` / `ollama` / `embedded`).
    pub backend_kind: &'a str,
    /// One of the [`outcome_label`] strings.
    pub outcome: &'static str,
    /// The `--context-window` pin the agent ran with; `None` ⇒ omitted (the
    /// agent used its defaults — nothing authoritative to report).
    pub context_window: Option<u32>,
    /// The tenacity level the run resolved (the explicit choice, else `normal`).
    pub tenacity: &'a str,
    /// The initiative level the run resolved (explicit / persona / family
    /// default / config default).
    pub initiative: &'a str,
    /// Effective cognition label (`default` when Newt sends no selection, or
    /// one of the explicit cognition levels).
    pub cognition: &'a str,
    /// Semantic selection captured by the instantiated core turn, even when
    /// the backend has no supported cognition projection. Absent without a turn.
    pub semantic_cognition: Option<Option<newt_core::role_profile::Cognition>>,
    /// The declaration and effort the Responses loop actually admitted.
    pub responses_capability: Option<&'a newt_core::model_card::ResponsesCapability>,
    pub reasoning_effort: Option<newt_core::model_card::ReasoningEffort>,
    /// `on` / `off` — whether a real crew runner was installed for the turn.
    pub crew: &'static str,
    /// `"on"` / `"off"` — whether OCAP enforcement was live for the run.
    pub ocap: &'static str,
    /// The max tool-rounds cap the driver actually used.
    pub max_rounds: u32,
    /// Wall-clock duration of the headless in milliseconds.
    pub wall_ms: u64,
    /// Generated (output) tokens, when the backend reported usage.
    pub gen_tokens: Option<u64>,
    /// Accounted session, chosen auxiliary, and independent budgets when enabled.
    pub smart_harness: Option<&'a serde_json::Value>,
    /// The output cap the turn's wire applied, and who enforced it (#2312).
    pub output_allowance: Option<newt_core::agentic::OutputAllowance>,
    /// The configured run-level call-count allowance, when one was set
    /// (#2313). Unlike `output_allowance` there is no server-vs-local
    /// enforcement distinction to report: a run allowance is always a local,
    /// pre-dispatch admission check.
    pub run_allowance: Option<u32>,
    /// What the turn's constructed context carried; `None` when no turn
    /// outcome exists to read it from (the `receipt` stanza is then omitted).
    pub features: Option<InstantiatedFeatures>,
    /// The signed OCAP `approve.toml` durable grants admitted into this run's
    /// caveats (#2524 item 1), as `"<axis>:<target>"` labels (e.g.
    /// `"fs_read:/opt/canvas-token"`) — empty when none were configured or
    /// none applied. Observability requirement: every folded-in grant must be
    /// visible on the contract record, not just effective silently.
    pub durable_grants: &'a [String],
    /// The self-verify gate's receipt entry (#2315); `None` omits it, and so
    /// does a record with no turn outcome (`features` is `None`), whose gate
    /// never ran.
    pub verification: Option<serde_json::Value>,
    /// Content id of the explicit scratchpad seed, when the run supplied one.
    pub scratchpad_seed: Option<&'a str>,
    /// The features the run was told to require (`--require-feature`).
    pub required: &'a [Feature],
}

/// How a turn ended, decided ONCE (#2212, corrected by #2218).
///
/// Two fields render this, and they answer DIFFERENT questions — which is why
/// they legitimately differ rather than drifting:
///
/// * `outcome`, in the versioned contract record, answers **"was this a real
///   attempt?"**. `gilamonster-bench/CONTRACT.md` is explicit: *"`completed` —
///   the agent drove the model to a terminal state. Pass/fail is the suite
///   verifier's call, not this field's."* The taxonomy's whole purpose is a
///   *Real attempt?* column; `transport_error` / `timeout` / `harness_error`
///   are ❌ because the model was never meaningfully exercised.
/// * `status`, in newt's own trace line, answers **"did this run finish what
///   it set out to do?"**. That is the question #2212 found being answered
///   dishonestly, and it has no external consumer.
///
/// Deciding once and rendering twice is what keeps them from drifting the way
/// they did before #2215, while still letting them disagree where the two
/// questions genuinely have different answers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Terminal {
    /// A final answer, or the historical legacy final-round narration outcome.
    Completed,
    /// No error, but the loop stopped before finishing — a wall, not a
    /// failure. The model was reached and did real work, so this is still a
    /// real attempt in contract terms.
    StoppedShort(TurnEndReason),
    /// The turn failed; the TYPED class decides which failure.
    Failed(Option<ErrorClass>),
}

/// Classify the turn from every signal that can end it.
pub fn terminal(
    clean: bool,
    class: Option<ErrorClass>,
    end_reason: Option<TurnEndReason>,
    smart_harness: bool,
) -> Terminal {
    if !clean {
        return Terminal::Failed(class);
    }
    // Matched explicitly, with no `_` arm: a NEW `TurnEndReason` variant must
    // fail to compile here and be classified deliberately rather than silently
    // inherit a terminal state. Silent inheritance is how #2212 arrived.
    match end_reason {
        // Preserve #2218's legacy benchmark classification. Smart adjudication
        // explicitly distinguishes an answer from final-round narration.
        Some(TurnEndReason::NarrationFinalRound) if !smart_harness => Terminal::Completed,
        Some(
            reason @ (TurnEndReason::RoundCap
            | TurnEndReason::RunAllowance
            | TurnEndReason::NoProgress
            | TurnEndReason::Empty
            | TurnEndReason::Cancelled
            | TurnEndReason::AwaitingOperator
            | TurnEndReason::NarrationCapExhausted
            | TurnEndReason::NarrationFinalRound
            | TurnEndReason::RepairExhausted
            | TurnEndReason::VerificationIncomplete),
        ) => Terminal::StoppedShort(reason),
        Some(TurnEndReason::Completed) | None => Terminal::Completed,
        // `Failed` implies an error, so `clean` is false and this is
        // unreachable. Classified anyway rather than left to a wildcard.
        Some(TurnEndReason::Failed) => Terminal::Failed(Some(ErrorClass::Harness)),
    }
}

/// The contract record's `outcome` — the closed set pinned in
/// `contract/bench_outcome_values_v1.txt`. #2268 adds `context_exceeded` as an
/// explicit extension that requires a matching bench consumer update.
/// The bench's `Outcome` is a CLOSED serde enum with
/// no `serde(other)` (`gilamonster-bench/src/contract.rs:20`), so an unknown
/// value does not deserialize: the run does not score badly, it DROPS OUT of
/// the matrix. #2215 emitted `round_cap` here and silently deleted rows.
///
/// **A cap exit maps to `timeout`, and that is defensible on the merits rather
/// than a compromise (#2218).** The contract needs a bucket for "exhausted its
/// budget without achieving the goal", and at v1 granularity both flavours of
/// budget belong in it: `is_real_attempt()` is `Completed | ModelError`, so
/// `timeout` correctly excludes a run that did not finish from capability
/// scoring. A cap exit without any continuation — and newt offers none today —
/// is a failure, not a terminal state worth scoring.
///
/// **What this conflates, recorded so the next reader knows it was decided:**
/// a wall-clock timeout and a round-cap grind become indistinguishable here.
/// They want different fixes (more time vs. stop the grinding). v2 should split
/// them, ideally distinguishing a cap exit that leaves resumable state from one
/// that leaves nothing, since only the second is unambiguously a failure. The
/// true reason is not lost meanwhile — `status` and `end_reason` both carry it
/// on newt's own trace line, where no external vocabulary is at stake.
pub fn outcome_label(t: Terminal) -> &'static str {
    match t {
        Terminal::Completed => "completed",
        // Budget exhausted without reaching the goal. `Cancelled` is
        // unreachable from this binary — it is set only in
        // `newt-tui/src/chat.rs` on an operator interrupt — but an abandoned
        // run did not finish either, so it files the same way rather than
        // falling through to a wildcard.
        // `RunAllowance` (#2313, `--run-allowance`) is a budget wall just like the
        // round cap: same bucket, no new vocabulary value.
        Terminal::StoppedShort(
            TurnEndReason::RoundCap
            | TurnEndReason::RunAllowance
            | TurnEndReason::NoProgress
            | TurnEndReason::Cancelled,
        ) => "timeout",
        // #2315: the model delivered an answer the harness's own verification
        // did not confirm. That is a real attempt at a terminal state; whether
        // it passes is the suite verifier's call (A13), so it is never `timeout`,
        // which would drop it from capability scoring. `status` says incomplete.
        Terminal::StoppedShort(
            TurnEndReason::RepairExhausted | TurnEndReason::VerificationIncomplete,
        ) => "completed",
        // The model was exercised but did not deliver an answer. A question is
        // a valid interactive pause, yet a headless still needs an answer.
        // Smart final-round narration remains a scored attempt. The legacy
        // final-round classification is preserved by `terminal` above.
        Terminal::StoppedShort(
            TurnEndReason::Empty
            | TurnEndReason::AwaitingOperator
            | TurnEndReason::NarrationCapExhausted
            | TurnEndReason::NarrationFinalRound,
        ) => "model_error",
        // The remaining variants cannot construct `StoppedShort`; listed so a
        // new one fails to compile rather than inheriting a bucket.
        Terminal::StoppedShort(TurnEndReason::Completed | TurnEndReason::Failed) => "harness_error",
        Terminal::Failed(Some(ErrorClass::Model)) => "model_error",
        Terminal::Failed(Some(ErrorClass::ContextExceeded)) => "context_exceeded",
        Terminal::Failed(Some(ErrorClass::Transport)) => "transport_error",
        Terminal::Failed(Some(ErrorClass::Timeout)) => "timeout",
        Terminal::Failed(Some(ErrorClass::Harness) | None) => "harness_error",
    }
}

/// The `solve_result` trace line's `status` — newt's own field, free to carry
/// a vocabulary no external contract constrains.
///
/// This is the half of #2212 that was a real defect: a run that stopped at a
/// wall reported itself `completed`, and every downstream signal — eval scores,
/// CI gates, an operator reading a summary — rested on that.
pub fn status_label(t: Terminal) -> &'static str {
    match t {
        Terminal::Completed => "completed",
        Terminal::StoppedShort(TurnEndReason::AwaitingOperator) => "awaiting_operator",
        Terminal::StoppedShort(_) => "incomplete",
        Terminal::Failed(_) => "failed",
    }
}

/// How many tool calls the run spent AFTER its last SUCCESSFUL workspace
/// write — the write-complete-then-grind measurement (#2214).
///
/// `RoundCap` alone cannot separate three runs that all hit the same wall:
/// thrash (rounds spent on failures), a genuinely-too-small cap (rounds spent
/// on real remaining work), and grind (rounds spent re-verifying work already
/// finished). This is the third one as a value a gate can assert, rather than
/// a substring of the advice prose the reply happens to carry.
///
/// `None` when the run never landed a successful write. That is the "never
/// acted" case — a distinct failure class, not a grind of length zero — and
/// collapsing the two would report every unproductive run as a grind.
///
/// Note it gates on `ok`, while the neighbouring `write_calls` on the same
/// line counts by NAME only. The two can legitimately disagree: a run whose
/// three writes were all DENIED reports `write_calls: 3` and `null` here.
pub fn calls_after_last_write(events: &[newt_core::ToolEvent]) -> Option<usize> {
    let last = events
        .iter()
        .rposition(|e| e.ok && newt_core::agentic::is_workspace_write_call(&e.tool))?;
    Some(events.len() - 1 - last)
}

/// Most paths `handback` names; the rest are counted by the truncation flag.
pub(crate) const HANDBACK_MAX_FILES: usize = 200;

/// [`handback`]'s `files_changed` AND `uncommitted_files` inputs share this
/// shape — both are "a list of paths, sourced either from the workspace
/// root's own git status or from probing nested repos" — one type, not two
/// near-identical enums (multi-repo recon PR2).
pub enum RepoFileList {
    /// The workspace root's own probe (today's single-repo case, unchanged):
    /// a status DELTA for `files_changed` (source `"git_status_delta"`), or
    /// the CURRENT dirty set for `uncommitted_files` (source `"git_status"`).
    Root(Vec<String>),
    /// A non-repo workspace root, probed per first-level nested repo
    /// (`claim_check::nested_files_changed_between` for the delta,
    /// `claim_check::nested_current_paths` for the current set): the union
    /// of every probed repo's paths (already prefixed `<repo>/` by the
    /// caller), the same union broken out per repo, and the repos that could
    /// not be probed. Source renders `"nested-repos"` either way.
    Nested {
        files: Vec<String>,
        by_repo: Vec<(String, Vec<String>)>,
        unprobed: Vec<String>,
    },
    /// #2552 round 3: `workspace` is a SUBDIRECTORY of a larger repo
    /// (`WorkspaceRepoLocation::InsideRepo`) — `claim_check::
    /// snapshot_workspace_subtree`'s scoped-and-prefix-stripped status,
    /// workspace-relative, UNION'd with any first-level nested repos the
    /// subdirectory itself contains (`<repo>/`-prefixed, same as
    /// [`RepoFileList::Nested`]). `files` is the flat union of both;
    /// `by_repo`/`unprobed` cover ONLY the nested repos (the subtree's own
    /// loose files have no "repo" to attribute them to). A DISTINCT source,
    /// `"git_status_subtree"`, so a consumer can tell the list is scoped to
    /// a subdirectory rather than a genuine repo root — round 2 dropped this
    /// case entirely, which round 2's review named a regression: at the
    /// everyday `--cwd repo/crate` invocation (no nested repos to fall back
    /// on), everything rendered `"unavailable"` — the exact "nothing
    /// changed" answer this PR exists to stop.
    Subtree {
        files: Vec<String>,
        by_repo: Vec<(String, Vec<String>)>,
        unprobed: Vec<String>,
    },
}

/// One conversion, shared by `handback`'s `files_changed` and
/// `uncommitted_files` stanzas — the ONE place that knows how a
/// [`RepoFileList`] renders, so the two fields cannot drift in how they cap,
/// truncate, or name a source.
struct RepoFileListStanza {
    value: serde_json::Value,
    source: &'static str,
    truncated: bool,
    by_repo: Option<Vec<(String, Vec<String>)>>,
    unprobed: Vec<String>,
}

fn repo_file_list_stanza(
    list: Option<RepoFileList>,
    root_source: &'static str,
) -> RepoFileListStanza {
    match list {
        Some(RepoFileList::Root(mut files)) => {
            let truncated = files.len() > HANDBACK_MAX_FILES;
            files.truncate(HANDBACK_MAX_FILES);
            RepoFileListStanza {
                value: serde_json::json!(files),
                source: root_source,
                truncated,
                by_repo: None,
                unprobed: Vec::new(),
            }
        }
        Some(RepoFileList::Nested {
            mut files,
            by_repo,
            unprobed,
        }) => {
            let truncated = files.len() > HANDBACK_MAX_FILES;
            files.truncate(HANDBACK_MAX_FILES);
            RepoFileListStanza {
                value: serde_json::json!(files),
                source: "nested-repos",
                truncated,
                by_repo: Some(by_repo),
                unprobed,
            }
        }
        Some(RepoFileList::Subtree {
            mut files,
            by_repo,
            unprobed,
        }) => {
            let truncated = files.len() > HANDBACK_MAX_FILES;
            files.truncate(HANDBACK_MAX_FILES);
            RepoFileListStanza {
                value: serde_json::json!(files),
                source: "git_status_subtree",
                truncated,
                by_repo: Some(by_repo),
                unprobed,
            }
        }
        None => RepoFileListStanza {
            value: serde_json::Value::Null,
            source: "unavailable",
            truncated: false,
            by_repo: None,
            unprobed: Vec::new(),
        },
    }
}

/// #2552 round 2 should-fix: the flat union in [`repo_file_list_stanza`] is
/// capped at `HANDBACK_MAX_FILES`, but `by_repo` carried every repo's FULL
/// list uncapped — one nested repo with an un-ignored `node_modules/` could
/// put tens of thousands of paths on a single JSON line. Cap PER REPO, with
/// a per-repo `truncated` flag, same convention as the flat union.
fn by_repo_json(by_repo: Vec<(String, Vec<String>)>) -> serde_json::Value {
    serde_json::json!(by_repo
        .into_iter()
        .map(|(repo, mut files)| {
            let truncated = files.len() > HANDBACK_MAX_FILES;
            files.truncate(HANDBACK_MAX_FILES);
            serde_json::json!({"repo": repo, "files": files, "truncated": truncated})
        })
        .collect::<Vec<_>>())
}

/// U7: the harness-written account of how a run ended, on the solve_result line
/// only (never the contract record). Everything here is the harness's own
/// knowledge — none of it is the model's claim, and it holds no hash or id:
/// - `files_changed`: the git status DELTA between run start and exit, or `null`
///   with `files_changed_source: "unavailable"` when there is no repo — never an
///   empty list that would read as "nothing changed";
/// - `last_exec_outcome`: the exec CLASS of the last shell call (no command text —
///   `ToolEvent` deliberately retains none);
/// - `model_reply_present`: whether the model said anything at all.
///
/// `end_reason` deliberately repeats the top-level field so the object is
/// self-contained for a dispatcher; both come from the same value. This is U7
/// part 1 (what changed); "what was verified" and "what it is unsure of" are not
/// covered here.
///
/// Blind spots of a status DELTA, which a reader must not mistake for "nothing
/// else changed": (a) a file dirty before AND after in the same status is
/// invisible; (b) paths git ignores (a stray under `target/`, a written `.env`)
/// are invisible; (c) a file that was dirty at start and was reverted to clean
/// is absent from the exit snapshot and so is not reported.
///
/// #2537: two more fields answer "was it committed, or just left dirty",
/// which `files_changed` alone cannot — it is a status DELTA, not a
/// commit-truth check, so it reads the same whether a change landed as a
/// commit or is still sitting in the working tree.
/// - `uncommitted_files`: the workspace's CURRENT staged+unstaged+untracked
///   paths at hand-back time, bounded the same way as `files_changed`
///   (`null` and `"unavailable"` off-repo, never a fake `[]`; capped at
///   `HANDBACK_MAX_FILES` with a truncated flag).
/// - `commits`: the commit id(s) created on the task branch during this run,
///   from newt-git's own `status`/`log` (never a shelled-out `git`). Present
///   only when at least one commit landed — nothing to commit (a clean repo,
///   or no repo at all) omits the field rather than writing an empty list or
///   inventing an id.
///
/// Multi-repo recon PR2: at a workspace root that is NOT itself a git repo,
/// `files_changed` used to fall straight to `"unavailable"` — read by an
/// operator as "nothing changed" even when a nested checkout (a bare folder
/// holding several repos) has a real uncommitted edit. [`RepoFileList::
/// Nested`] carries that case instead: the union of every probed nested
/// repo's changed files, prefixed `<repo>/`, source `"nested-repos"`, plus a
/// per-repo breakdown (`files_changed_by_repo`) and the repos that could not
/// be probed (`files_changed_unprobed`, present only when non-empty) — named
/// rather than silently folded into the union or dropped. This does NOT
/// touch the pinned contract record (`contract_version`, #2218's
/// unknown-field question) — `handback` is solely on the free-form
/// `solve_result` line, so these are new OPTIONAL fields on an
/// already-free-form object, not a versioned shape change.
#[must_use]
pub fn handback(
    delta: Option<RepoFileList>,
    events: &[newt_core::ToolEvent],
    end_reason: &str,
    reply_present: bool,
    uncommitted: Option<RepoFileList>,
    commits: Option<Vec<String>>,
) -> serde_json::Value {
    let stanza = repo_file_list_stanza(delta, "git_status_delta");
    let (files, source, truncated, by_repo, unprobed) = (
        stanza.value,
        stanza.source,
        stanza.truncated,
        stanza.by_repo,
        stanza.unprobed,
    );
    let uncommitted_stanza = repo_file_list_stanza(uncommitted, "git_status");
    let (
        uncommitted_files,
        uncommitted_source,
        uncommitted_truncated,
        uncommitted_by_repo,
        uncommitted_unprobed,
    ) = (
        uncommitted_stanza.value,
        uncommitted_stanza.source,
        uncommitted_stanza.truncated,
        uncommitted_stanza.by_repo,
        uncommitted_stanza.unprobed,
    );
    let last_exec = events
        .iter()
        .rev()
        .find_map(|e| e.execution.as_ref())
        .and_then(|x| serde_json::to_value(x).ok());
    let mut record = serde_json::json!({
        "files_changed": files,
        "files_changed_source": source,
        "files_changed_truncated": truncated,
        "uncommitted_files": uncommitted_files,
        "uncommitted_files_source": uncommitted_source,
        "uncommitted_files_truncated": uncommitted_truncated,
        "last_exec_outcome": last_exec,
        "end_reason": end_reason,
        "model_reply_present": reply_present,
    });
    conditional_stanza(
        &mut record,
        "files_changed_by_repo",
        by_repo.map(by_repo_json),
    );
    conditional_stanza(
        &mut record,
        "files_changed_unprobed",
        (!unprobed.is_empty()).then_some(unprobed),
    );
    conditional_stanza(
        &mut record,
        "uncommitted_files_by_repo",
        uncommitted_by_repo.map(by_repo_json),
    );
    conditional_stanza(
        &mut record,
        "uncommitted_files_unprobed",
        (!uncommitted_unprobed.is_empty()).then_some(uncommitted_unprobed),
    );
    conditional_stanza(
        &mut record,
        "commits",
        commits.filter(|c| !c.is_empty()).map(|mut c| {
            c.truncate(HANDBACK_MAX_FILES);
            serde_json::json!(c)
        }),
    );
    record
}

/// One JSONL trace line per parse signal (the ADR §5 events
/// `recovered_tool_call{dialect}` / `no_parseable_tool_call`). These lines
/// carry no `contract_version`, so the bench's contract scan skips them.
pub fn parse_signal_line(signal: &ParseSignal) -> serde_json::Value {
    serde_json::to_value(signal).expect("ParseSignal serializes infallibly")
}

/// One JSONL trace line per output-behavior signal. Like parse signals, these
/// carry no `contract_version`, so they cannot be mistaken for contract rows.
pub fn behavior_signal_line(signal: &BehaviorSignal) -> serde_json::Value {
    serde_json::to_value(signal).expect("BehaviorSignal serializes infallibly")
}

/// THE conditional-stanza convention, for the contract record and newt's own
/// trace lines alike: an optional key is written only when known — omitted,
/// never nulled-in or invented. Every optional field goes through here.
///
/// An addition never overwrites a field already present. A stanza that lands
/// on an existing key is a rename of that key, which consumers cannot see.
pub fn conditional_stanza(
    target: &mut serde_json::Value,
    key: &str,
    value: Option<impl Into<serde_json::Value>>,
) {
    if let Some(value) = value {
        debug_assert!(
            target.get(key).is_none(),
            "conditional stanza `{key}` would overwrite an existing field"
        );
        target[key] = value.into();
    }
}

/// The `usage` stanza on the `solve_result` line (#2313): what the run's
/// inference attempts sent and generated, summed per attempt.
///
/// `cost_usd` is present only when every attempt reported usage and the model
/// is priced, so a real `0.0` stays and unknown is never zero. `ledger_head` is
/// present only when the ledger's lines were emitted into the same trace, since
/// a head with no lines to walk cannot be verified.
pub fn usage_stanza(
    totals: &newt_core::attempts::UsageTotals,
    cost_usd: Option<f64>,
    ledger_head: Option<&str>,
) -> serde_json::Value {
    let mut stanza = serde_json::json!({
        "attempts": totals.attempts,
        "in_tokens": totals.in_tokens,
        "out_tokens": totals.out_tokens,
        "usage_missing": totals.usage_missing,
        "usage_complete": totals.usage_complete,
    });
    conditional_stanza(&mut stanza, "cost_usd", cost_usd);
    conditional_stanza(&mut stanza, "ledger_head", ledger_head);
    stanza
}

/// One attempt-ledger chain line as a trace event: the journal line itself,
/// tagged `kind: "attempt"`, so it still deserializes as a `JournalLine`.
pub fn attempt_line(
    line: &newt_core::event_journal::JournalLine<newt_core::attempts::AttemptRecord>,
) -> serde_json::Value {
    let mut value = serde_json::to_value(line).unwrap_or(serde_json::Value::Null);
    conditional_stanza(&mut value, "kind", Some("attempt"));
    value
}

/// A `receipt.features` entry a run can be told to require (#2314), spelled on
/// the command line exactly as in the receipt.
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
#[value(rename_all = "snake_case")]
pub enum Feature {
    Scratchpad,
    CodeSearch,
    Crew,
}

impl Feature {
    fn key(self) -> &'static str {
        match self {
            Self::Scratchpad => "scratchpad",
            Self::CodeSearch => "code_search",
            Self::Crew => "crew",
        }
    }

    fn instantiated(self, f: InstantiatedFeatures) -> bool {
        match self {
            Self::Scratchpad => f.scratchpad,
            Self::CodeSearch => f.code_search,
            Self::Crew => f.crew,
        }
    }

    /// THE absence table: why `newt headless` did not supply this feature, as the
    /// receipt's `(state, reason)`. Admission reads it too, so a refusal and
    /// the receipt cannot disagree.
    fn absence(self) -> (&'static str, &'static str) {
        match self {
            Self::Scratchpad => ("unavailable", "no --scratchpad-state was supplied"),
            Self::CodeSearch => ("unsupported", "headless builds no retrieval index"),
            Self::Crew => (
                "unavailable",
                "crew is not enabled for this run (NEWT_TEAM)",
            ),
        }
    }
}

/// Refuse, before any model request, a required feature this run cannot
/// supply; `supplies` answers for the run.
pub fn admit_required(
    required: &[Feature],
    supplies: impl Fn(Feature) -> bool,
) -> anyhow::Result<()> {
    for &feature in required {
        if !supplies(feature) {
            let (state, reason) = feature.absence();
            anyhow::bail!("required feature `{}` is {state}: {reason}", feature.key());
        }
    }
    Ok(())
}

/// The `receipt` stanza's `features` section (#2314): what participated in
/// the turn, derived from its constructed context. Each entry's `state` is
///
/// * `instantiated` — in the context: advertised and executable;
/// * `unsupported` — `newt headless` has no way to supply it;
/// * `unavailable` — `newt headless` can supply it, but did not for this run;
/// * `requested` — required, but the turn did not confirm it was instantiated.
///
/// A feature that did not participate carries a `reason`, and a required one
/// says `required: true`. With no turn outcome (`f` is `None`) only the
/// requirements are known, so only they are listed; with none, the section is
/// omitted. An instantiated scratchpad also names its `scope` and `seed`:
/// headless's only state source is the explicit seed, so the scope is `fresh`.
pub fn feature_receipt(
    f: Option<InstantiatedFeatures>,
    required: &[Feature],
    scratchpad_seed: Option<&str>,
) -> Option<serde_json::Value> {
    use clap::ValueEnum;
    let mut features = serde_json::Map::new();
    for &feature in Feature::value_variants() {
        let is_required = required.contains(&feature);
        let mut entry = match f {
            Some(f) if feature.instantiated(f) => serde_json::json!({ "state": "instantiated" }),
            _ if is_required => serde_json::json!({
                "state": "requested",
                "reason": "required, but the turn did not confirm it was instantiated",
            }),
            Some(_) => {
                let (state, reason) = feature.absence();
                serde_json::json!({ "state": state, "reason": reason })
            }
            None => continue,
        };
        conditional_stanza(&mut entry, "required", is_required.then_some(true));
        if feature == Feature::Scratchpad && entry["state"] == "instantiated" {
            conditional_stanza(&mut entry, "scope", scratchpad_seed.map(|_| "fresh"));
            conditional_stanza(&mut entry, "seed", scratchpad_seed);
        }
        features.insert(feature.key().into(), entry);
    }
    (!features.is_empty()).then(|| serde_json::json!({ "features": features }))
}

/// Build THE contract record — exactly the `contract_version: "2"` fields.
/// Optional fields go through [`conditional_stanza`].
pub fn contract_record(i: &ContractInputs<'_>) -> serde_json::Value {
    let mut timing = serde_json::json!({ "wall_ms": i.wall_ms });
    conditional_stanza(&mut timing, "gen_tokens", i.gen_tokens);
    // tok_s only when derivable: tokens AND a non-zero wall clock.
    let tok_s = i
        .gen_tokens
        .filter(|_| i.wall_ms > 0)
        .map(|gen| gen as f64 * 1000.0 / i.wall_ms as f64);
    conditional_stanza(&mut timing, "tok_s", tok_s);
    let mut effective_config = serde_json::json!({
        "tenacity": i.tenacity,
        "initiative": i.initiative,
        "cognition": i.cognition,
        "crew": i.crew,
        "ocap": i.ocap,
        "max_rounds": i.max_rounds,
    });
    conditional_stanza(
        &mut effective_config,
        "semantic_cognition",
        i.semantic_cognition.map(|value| serde_json::json!(value)),
    );
    if let Some(capability) = i.responses_capability {
        conditional_stanza(
            &mut effective_config,
            "responses_capability",
            Some(serde_json::json!(capability)),
        );
        conditional_stanza(
            &mut effective_config,
            "reasoning_effort",
            Some(serde_json::json!(i.reasoning_effort)),
        );
    }
    conditional_stanza(&mut effective_config, "context_window", i.context_window);
    let output_allowance = i
        .output_allowance
        .map(|a| serde_json::to_value(a).expect("OutputAllowance serializes infallibly"));
    conditional_stanza(&mut effective_config, "output_allowance", output_allowance);
    conditional_stanza(&mut effective_config, "run_allowance", i.run_allowance);
    conditional_stanza(
        &mut effective_config,
        "smart_harness",
        i.smart_harness.cloned(),
    );
    conditional_stanza(
        &mut effective_config,
        "durable_grants",
        (!i.durable_grants.is_empty()).then(|| serde_json::json!(i.durable_grants)),
    );
    let mut record = serde_json::json!({
        "contract_version": CONTRACT_VERSION,
        "requested_model": i.requested_model,
        "effective_model": i.effective_model,
        "outcome": i.outcome,
        "backend": { "name": i.backend_name, "kind": i.backend_kind },
        "agent": AGENT,
        "agent_version": newt_core::build_info::VERSION_WITH_COMMIT,
        "effective_config": effective_config,
        "timing": timing,
    });
    conditional_stanza(&mut record, "model_digest", i.model_digest);
    let mut receipt = feature_receipt(i.features, i.required, i.scratchpad_seed);
    if let (Some(verification), Some(_)) = (&i.verification, &i.features) {
        receipt.get_or_insert_with(|| serde_json::json!({}))["verification"] = verification.clone();
    }
    conditional_stanza(&mut record, "receipt", receipt);
    record
}

/// The consumer's permitted `outcome` values, checked in beside this code.
///
/// See the file's own header for why a copy is the right shape here. In short:
/// the authority lives in another repository that deliberately shares no type
/// with this one, so nothing in this workspace can fail on a contract
/// violation — and #2218 recorded that gap after `round_cap` silently deleted
/// bench rows. This constant, and the test that drives every reachable
/// classification through it, is that gap closed at the one place newt chooses
/// a wire value.
#[cfg(test)]
const BENCH_OUTCOME_VALUES: &str = include_str!("../contract/bench_outcome_values_v1.txt");

/// Parse the checked-in permitted set: one value per line, `#` comments and
/// blank lines ignored.
#[cfg(test)]
fn permitted_outcomes() -> Vec<&'static str> {
    BENCH_OUTCOME_VALUES
        .lines()
        .map(str::trim)
        .filter(|l| !l.is_empty() && !l.starts_with('#'))
        .collect()
}

#[cfg(test)]
mod tests {
    include!("headless_contract_cognition_tests.rs");
    use super::*;

    #[test]
    fn handback_reports_delta_caps_it_and_never_fakes_an_empty_list() {
        let h = handback(
            Some(RepoFileList::Root(vec!["a.rs".into()])),
            &[],
            "None",
            false,
            None,
            None,
        );
        assert_eq!(h["files_changed"], serde_json::json!(["a.rs"]));
        assert_eq!(h["files_changed_source"], "git_status_delta");
        assert_eq!(h["model_reply_present"], false);
        assert!(h["last_exec_outcome"].is_null());

        let mut shell =
            newt_core::ToolEvent::from_call("run_command", &serde_json::json!({}), false, None);
        shell.execution = Some(newt_core::ExecOutcome::TimedOut);
        let later =
            newt_core::ToolEvent::from_call("read_file", &serde_json::json!({}), true, None);
        let h = handback(None, &[shell, later], "None", true, None, None);
        assert_eq!(
            h["last_exec_outcome"], "timed_out",
            "class only, from the last SHELL call"
        );

        let many: Vec<String> = (0..201).map(|i| format!("f{i}")).collect();
        let h = handback(
            Some(RepoFileList::Root(many)),
            &[],
            "RoundCap",
            true,
            None,
            None,
        );
        assert_eq!(h["files_changed"].as_array().unwrap().len(), 200);
        assert_eq!(h["files_changed_truncated"], true);

        // No repo: null + "unavailable", never [] (which reads as "nothing changed").
        let h = handback(None, &[], "None", false, None, None);
        assert!(h["files_changed"].is_null());
        assert_eq!(h["files_changed_source"], "unavailable");
        // A clean repo IS an empty list, distinguishable from unavailable.
        let h = handback(
            Some(RepoFileList::Root(vec![])),
            &[],
            "None",
            false,
            None,
            None,
        );
        assert_eq!(h["files_changed"], serde_json::json!([]));
    }

    /// #2537 item 2: a run that ends with modified-but-uncommitted files must
    /// NAME them, bounded the same way `files_changed` already is (null +
    /// "unavailable" off-repo, never a fake empty list; capped at 200 with a
    /// truncated flag). Red before the field existed: this assertion could
    /// not even compile against the old 4-arg `handback`.
    #[test]
    fn handback_names_uncommitted_files_bounded_like_files_changed() {
        let h = handback(
            None,
            &[],
            "None",
            false,
            Some(RepoFileList::Root(vec!["dirty.rs".into()])),
            None,
        );
        assert_eq!(h["uncommitted_files"], serde_json::json!(["dirty.rs"]));
        assert_eq!(h["uncommitted_files_source"], "git_status");
        assert_eq!(h["uncommitted_files_truncated"], false);

        // Off-repo: null + "unavailable", never [] read as "nothing dirty".
        let h = handback(None, &[], "None", false, None, None);
        assert!(h["uncommitted_files"].is_null());
        assert_eq!(h["uncommitted_files_source"], "unavailable");

        // A clean repo IS an empty list, distinguishable from unavailable.
        let h = handback(
            None,
            &[],
            "None",
            false,
            Some(RepoFileList::Root(vec![])),
            None,
        );
        assert_eq!(h["uncommitted_files"], serde_json::json!([]));

        let many: Vec<String> = (0..201).map(|i| format!("d{i}")).collect();
        let h = handback(
            None,
            &[],
            "None",
            false,
            Some(RepoFileList::Root(many)),
            None,
        );
        assert_eq!(h["uncommitted_files"].as_array().unwrap().len(), 200);
        assert_eq!(h["uncommitted_files_truncated"], true);
    }

    /// #2537 item 3: when the run committed on the task branch, the hand-back
    /// carries the commit id(s) it produced, so "the work landed" is
    /// verifiable. Nothing to commit (repo with no new commits, or no repo at
    /// all) omits the `commits` field entirely rather than an empty list or a
    /// lie.
    #[test]
    fn handback_carries_commit_ids_or_omits_the_field() {
        let h = handback(None, &[], "None", false, None, Some(vec!["abc123".into()]));
        assert_eq!(h["commits"], serde_json::json!(["abc123"]));

        // Nothing committed: field is ABSENT, not an empty array.
        let h = handback(None, &[], "None", false, None, Some(vec![]));
        assert!(h.get("commits").is_none());

        // No repo at all: also absent.
        let h = handback(None, &[], "None", false, None, None);
        assert!(h.get("commits").is_none());
    }

    /// Multi-repo recon PR2 (red first): `RepoFileList::Nested` renders the
    /// new `"nested-repos"` source for BOTH `files_changed` and
    /// `uncommitted_files`, the union prefixed `<repo>/`, a per-repo
    /// breakdown, and the unprobed list — present only when non-empty.
    #[test]
    fn handback_renders_the_nested_repos_source_and_per_repo_breakdown() {
        let h = handback(
            Some(RepoFileList::Nested {
                files: vec!["repoA/a.txt".into()],
                by_repo: vec![
                    ("repoA".into(), vec!["a.txt".into()]),
                    ("repoB".into(), vec![]),
                ],
                unprobed: vec!["repoC".into()],
            }),
            &[],
            "None",
            false,
            Some(RepoFileList::Nested {
                files: vec!["repoA/a.txt".into()],
                by_repo: vec![("repoA".into(), vec!["a.txt".into()])],
                unprobed: vec![],
            }),
            None,
        );
        assert_eq!(h["files_changed"], serde_json::json!(["repoA/a.txt"]));
        assert_eq!(h["files_changed_source"], "nested-repos");
        assert_eq!(
            h["files_changed_by_repo"],
            serde_json::json!([
                {"repo": "repoA", "files": ["a.txt"], "truncated": false},
                {"repo": "repoB", "files": [], "truncated": false},
            ])
        );
        assert_eq!(h["files_changed_unprobed"], serde_json::json!(["repoC"]));

        assert_eq!(h["uncommitted_files"], serde_json::json!(["repoA/a.txt"]));
        assert_eq!(h["uncommitted_files_source"], "nested-repos");
        assert_eq!(
            h["uncommitted_files_by_repo"],
            serde_json::json!([{"repo": "repoA", "files": ["a.txt"], "truncated": false}])
        );
        // Empty unprobed list is ABSENT, not a fake `[]` — same convention
        // as `commits`.
        assert!(h.get("uncommitted_files_unprobed").is_none(), "{h}");
    }

    /// #2552 round 2 should-fix (red first): one nested repo with a huge
    /// dirty set (a stand-in for an un-ignored `node_modules/`) must not put
    /// its whole uncapped list on the wire via `*_by_repo` — only the flat
    /// union was capped before this fix.
    #[test]
    fn handback_caps_each_repos_by_repo_file_list_independently() {
        let huge: Vec<String> = (0..HANDBACK_MAX_FILES + 5)
            .map(|n| format!("f{n}.txt"))
            .collect();
        let h = handback(
            Some(RepoFileList::Nested {
                files: vec!["big/f0.txt".into()],
                by_repo: vec![("big".into(), huge.clone())],
                unprobed: vec![],
            }),
            &[],
            "None",
            false,
            None,
            None,
        );
        let by_repo = h["files_changed_by_repo"].as_array().expect("array");
        assert_eq!(by_repo.len(), 1);
        let files = by_repo[0]["files"].as_array().expect("files array");
        assert_eq!(files.len(), HANDBACK_MAX_FILES, "{files:?}");
        assert_eq!(by_repo[0]["truncated"], true, "{h}");
    }

    use newt_core::{BehaviorSignal, ToolCallDialect};

    /// Every `TurnEndReason`, and a compile-time guard that this list stays
    /// complete.
    ///
    /// The guard is the load-bearing half. A hand-written list of variants is
    /// the classic vacuous negative (#2150): add an eighth variant and the
    /// coverage test still passes, having simply stopped looking at it. The
    /// index match below has no wildcard arm, so a new variant fails to
    /// COMPILE; and the density assertion in
    /// `every_reachable_outcome_is_a_value_the_bench_can_parse` fails unless
    /// the new arm's index is also added to this array. Neither direction can
    /// be satisfied by ignoring it.
    const ALL_END_REASONS: &[TurnEndReason] = &[
        TurnEndReason::Completed,
        TurnEndReason::NarrationCapExhausted,
        TurnEndReason::NarrationFinalRound,
        TurnEndReason::RoundCap,
        TurnEndReason::Empty,
        TurnEndReason::Cancelled,
        TurnEndReason::Failed,
        TurnEndReason::AwaitingOperator,
        TurnEndReason::RepairExhausted,
        TurnEndReason::VerificationIncomplete,
        TurnEndReason::RunAllowance,
        TurnEndReason::NoProgress,
    ];

    fn tool_event(tool: &str, ok: bool) -> newt_core::ToolEvent {
        newt_core::ToolEvent::from_call(tool, &serde_json::json!({"path": tool}), ok, None)
    }

    /// The "never acted" run is NOT a grind of length zero. `write_calls`
    /// already distinguishes a run that never wrote; this field must not
    /// re-report that run as "finished the work then ground", which is what
    /// any `unwrap_or(0)` or `unwrap_or(len)` fallback would do.
    #[test]
    fn a_run_that_never_landed_a_write_has_no_grind_measurement() {
        let events = [
            tool_event("read_file", true),
            // A write that FAILED is not a write. This is the ok-gate that
            // separates this field from `write_calls`, which counts by name.
            tool_event("write_file", false),
            tool_event("run_command", true),
        ];
        assert_eq!(calls_after_last_write(&events), None);
        assert_eq!(calls_after_last_write(&[]), None);
    }

    /// The other end: a run whose last act WAS the write ground for zero
    /// calls. Distinguishing this from `None` is the whole point of the
    /// `Option` — both are "no grind", for opposite reasons.
    #[test]
    fn a_write_as_the_final_call_is_a_grind_of_zero() {
        assert_eq!(
            calls_after_last_write(&[tool_event("read_file", true), tool_event("edit_file", true)]),
            Some(0)
        );
    }

    /// The measured shape from #2212, in miniature: writes early, then a tail
    /// of succeeding, redundant calls. Only the LAST successful write counts —
    /// an implementation keying on the FIRST would say 4 here.
    #[test]
    fn the_grind_is_measured_from_the_last_successful_write() {
        let events = [
            tool_event("write_file", true),
            tool_event("edit_file", true),
            tool_event("read_file", true),
            tool_event("text_search", true),
        ];
        assert_eq!(calls_after_last_write(&events), Some(2));
    }

    fn end_reason_index(r: TurnEndReason) -> usize {
        match r {
            TurnEndReason::Completed => 0,
            TurnEndReason::NarrationCapExhausted => 1,
            TurnEndReason::NarrationFinalRound => 2,
            TurnEndReason::RoundCap => 3,
            TurnEndReason::Empty => 4,
            TurnEndReason::Cancelled => 5,
            TurnEndReason::Failed => 6,
            TurnEndReason::AwaitingOperator => 7,
            TurnEndReason::RepairExhausted => 8,
            TurnEndReason::VerificationIncomplete => 9,
            TurnEndReason::RunAllowance => 10,
            TurnEndReason::NoProgress => 11,
        }
    }

    /// Every `ErrorClass`, guarded the same way.
    const ALL_ERROR_CLASSES: &[ErrorClass] = &[
        ErrorClass::Model,
        ErrorClass::Transport,
        ErrorClass::Timeout,
        ErrorClass::Harness,
        ErrorClass::ContextExceeded,
    ];

    fn error_class_index(c: ErrorClass) -> usize {
        match c {
            ErrorClass::Model => 0,
            ErrorClass::Transport => 1,
            ErrorClass::Timeout => 2,
            ErrorClass::Harness => 3,
            ErrorClass::ContextExceeded => 4,
        }
    }

    /// Every `Terminal` this binary can construct.
    fn all_terminals() -> Vec<Terminal> {
        let mut out = vec![Terminal::Completed, Terminal::Failed(None)];
        out.extend(ALL_END_REASONS.iter().copied().map(Terminal::StoppedShort));
        out.extend(
            ALL_ERROR_CLASSES
                .iter()
                .copied()
                .map(|c| Terminal::Failed(Some(c))),
        );
        out
    }

    /// **#2227 layer 2, and the specific gate that failed in #2215.**
    ///
    /// A green CI in this repo cannot mean "contract-conforming": the bench
    /// re-declares its own structs so the ruler stays independent of the thing
    /// it measures, which is correct and must not be traded away. The cost is
    /// that a wire value newt invents is caught by nobody — and because the
    /// consumer's enum is closed, an unparseable value does not score badly,
    /// it removes the row from the matrix.
    ///
    /// This drives EVERY reachable classification through `outcome_label` and
    /// requires the result to be a value the checked-in permitted set contains.
    /// It would have failed on `round_cap` before #2215 merged.
    #[test]
    fn every_reachable_outcome_is_a_value_the_bench_can_parse() {
        // The variant lists must be complete before anything derived from them
        // proves a thing. Indices are dense and unique iff every arm of the
        // (wildcard-free) index match appears exactly once in the array.
        let mut seen: Vec<usize> = ALL_END_REASONS
            .iter()
            .copied()
            .map(end_reason_index)
            .collect();
        seen.sort_unstable();
        assert_eq!(
            seen,
            (0..ALL_END_REASONS.len()).collect::<Vec<_>>(),
            "ALL_END_REASONS stopped covering TurnEndReason — a variant was \
             added to the index match but not to the array, so the coverage \
             below is measuring less than it appears to"
        );
        let mut seen: Vec<usize> = ALL_ERROR_CLASSES
            .iter()
            .copied()
            .map(error_class_index)
            .collect();
        seen.sort_unstable();
        assert_eq!(
            seen,
            (0..ALL_ERROR_CLASSES.len()).collect::<Vec<_>>(),
            "ALL_ERROR_CLASSES stopped covering ErrorClass"
        );

        let permitted = permitted_outcomes();
        assert!(
            !permitted.is_empty(),
            "the permitted set parsed empty — a checked-in file that reads as \
             'nothing is allowed' would fail every case below for the wrong \
             reason, and one that reads as 'everything' would pass them all"
        );
        for t in all_terminals() {
            let label = outcome_label(t);
            assert!(
                permitted.contains(&label),
                "outcome_label({t:?}) emitted {label:?}, which \
                 gilamonster-bench's closed `Outcome` enum cannot deserialize. \
                 The run will not score badly — its row will VANISH from the \
                 matrix. Permitted: {permitted:?}. If the contract genuinely \
                 moved, update contract/bench_outcome_values_v1.txt against the \
                 upstream enum, in its own commit."
            );
        }
    }

    /// **#2239.** A turn the loop gave up on must not be recorded as an
    /// ordinary success.
    ///
    /// The reported transcript's entire stored reply was the rescue nudge's own
    /// sentence — "I'm finished — the answer above is the complete deliverable"
    /// — with no answer above it. `end_reason` was `NarrationCapExhausted`, and
    /// the operator's only signal was a `⚠` glyph in a footer. Everything a
    /// consumer reads said `completed`: the contract record's `outcome`, the
    /// trace line's `status`, and `Terminal` itself.
    ///
    /// This asserts all three, because the defect was that all three agreed on
    /// the wrong answer. Before the fix each `assert` below reads "completed".
    #[test]
    fn an_exhausted_narration_rescue_is_not_recorded_as_a_completion() {
        let t = terminal(
            true,
            None,
            Some(TurnEndReason::NarrationCapExhausted),
            false,
        );
        assert_eq!(
            t,
            Terminal::StoppedShort(TurnEndReason::NarrationCapExhausted),
            "the loop stopped before finishing — that is StoppedShort, not a \
             genuine final answer"
        );
        assert_eq!(
            status_label(t),
            "incomplete",
            "newt's own trace line must say the run did not finish what it set \
             out to do (#2212's question, asked of a second exit)"
        );
        assert_eq!(
            outcome_label(t),
            "model_error",
            "the model WAS reached and emitted unusable content — a real \
             attempt that failed, not a budget wall and not a clean completion"
        );

        // A genuine answer remains deliverable after a nudge.
        assert_eq!(
            terminal(true, None, Some(TurnEndReason::Completed), false),
            Terminal::Completed
        );
        assert_eq!(outcome_label(Terminal::Completed), "completed");
    }

    #[test]
    fn final_round_narration_preserves_legacy_outcomes_and_accounts_for_smart_runs() {
        for (smart_harness, expected, status, outcome) in [
            (false, Terminal::Completed, "completed", "completed"),
            (
                true,
                Terminal::StoppedShort(TurnEndReason::NarrationFinalRound),
                "incomplete",
                "model_error",
            ),
        ] {
            let actual = terminal(
                true,
                None,
                Some(TurnEndReason::NarrationFinalRound),
                smart_harness,
            );
            assert_eq!(actual, expected);
            assert_eq!(status_label(actual), status);
            assert_eq!(outcome_label(actual), outcome);
        }
        for reason in ALL_END_REASONS
            .iter()
            .copied()
            .filter(|reason| *reason != TurnEndReason::NarrationFinalRound)
        {
            assert_eq!(
                terminal(true, None, Some(reason), false),
                terminal(true, None, Some(reason), true)
            );
        }
    }

    /// #2315 (A14): the verification receipt entry rides the contract record
    /// when headless supplies it, even with no features section, and is absent
    /// otherwise (never invented).
    ///
    /// #2374 round three, item 8: a record with no turn outcome (`features` is
    /// `None`: the turn task failed to start, panicked or was cancelled) ran no
    /// gate, so it claims no mode even when headless supplied one.
    #[test]
    fn the_verification_receipt_is_carried_only_when_supplied() {
        let entry = serde_json::json!({"mode": "result_aware", "repair_allowance": 3});
        let mut with = inputs();
        with.verification = Some(entry.clone());
        assert_eq!(contract_record(&with)["receipt"]["verification"], entry);
        let without = inputs();
        assert!(contract_record(&without)["receipt"]
            .get("verification")
            .is_none());
        let mut no_outcome = inputs();
        no_outcome.features = None;
        no_outcome.verification = Some(entry);
        assert!(
            contract_record(&no_outcome)["receipt"]
                .get("verification")
                .is_none(),
            "{}",
            contract_record(&no_outcome)
        );
    }

    /// #2315 (A10/A13): an unconfirmed-verification ending is a scored attempt
    /// (`completed`) whose own trace status is `incomplete`, never `timeout`.
    #[test]
    fn verification_endings_are_completed_attempts_with_incomplete_status() {
        for reason in [
            TurnEndReason::RepairExhausted,
            TurnEndReason::VerificationIncomplete,
        ] {
            let t = terminal(true, None, Some(reason), false);
            assert_eq!(t, Terminal::StoppedShort(reason));
            assert_eq!(outcome_label(t), "completed");
            assert_eq!(status_label(t), "incomplete");
        }
    }

    #[test]
    fn a_question_awaits_the_operator_instead_of_completing_the_task() {
        let t = terminal(true, None, Some(TurnEndReason::AwaitingOperator), false);
        assert_eq!(t, Terminal::StoppedShort(TurnEndReason::AwaitingOperator));
        assert_eq!(status_label(t), "awaiting_operator");
        assert_eq!(outcome_label(t), "model_error");
        assert!(permitted_outcomes().contains(&outcome_label(t)));
    }

    /// The permitted set is a copy of a specific upstream shape, so it is
    /// pinned exactly rather than merely non-empty. A silent edit — adding a
    /// value to make a failing case pass — is the failure mode the file exists
    /// to prevent, and changing this list is how a reviewer is made to look.
    /// #2268 authorizes `context_exceeded` explicitly; the file documents the
    /// still-required matching consumer update rather than claiming it ran.
    #[test]
    fn the_checked_in_permitted_set_matches_the_contract() {
        assert_eq!(
            permitted_outcomes(),
            vec![
                "completed",
                "model_error",
                "transport_error",
                "timeout",
                "harness_error",
                "context_exceeded"
            ],
            "the declared gilamonster-bench `Outcome` set changed. That requires \
             an explicit contract decision and a coordinated consumer update, \
             not a way to make a test pass — re-read gilamonster-bench/src/\
             contract.rs and confirm contract_version before editing this."
        );
    }

    fn inputs() -> ContractInputs<'static> {
        ContractInputs {
            requested_model: "qwen3.6_35b",
            effective_model: "qwen3.6_35b",
            model_digest: None,
            backend_name: "dgx",
            backend_kind: "openai",
            outcome: "completed",
            context_window: Some(32768),
            tenacity: "normal",
            initiative: "measured",
            cognition: "default",
            semantic_cognition: None,
            responses_capability: None,
            reasoning_effort: None,
            crew: "off",
            ocap: "off",
            max_rounds: 40,
            wall_ms: 10_000,
            gen_tokens: Some(500),
            smart_harness: None,
            output_allowance: None,
            run_allowance: None,
            features: Some(InstantiatedFeatures {
                crew: true,
                ..InstantiatedFeatures::default()
            }),
            verification: None,
            scratchpad_seed: None,
            required: &[],
            durable_grants: &[],
        }
    }

    // --- one test per outcome class ---

    /// **The #2212 defect, as a test.** Tonight's dogfood run produced a
    /// correct implementation, ran out of rounds, never ran the test the task
    /// required, and reported `outcome: completed` with `end_reason: RoundCap`
    /// in the same JSON line. A cap-exit is not an error, and `outcome` was
    /// derived only from the absence of one.
    #[test]
    fn a_round_cap_exit_files_as_timeout_not_completed() {
        assert_eq!(
            outcome_label(terminal(true, None, Some(TurnEndReason::RoundCap), false)),
            "timeout",
            "a run that exhausted its round budget without reaching the goal \
             must be excluded from capability scoring — is_real_attempt() is \
             Completed|ModelError. #2215 emitted `round_cap`, which the bench's \
             closed enum cannot parse, so the row vanished instead."
        );
    }

    /// U4a: an exhausted `--run-allowance` is filed like the round cap — a
    /// budget wall (`timeout`, `incomplete`), never `harness_error`, and no new
    /// value in the pinned outcome vocabulary.
    #[test]
    fn a_run_allowance_exit_files_like_a_round_cap() {
        for reason in [TurnEndReason::RunAllowance, TurnEndReason::NoProgress] {
            let t = terminal(true, None, Some(reason), false);
            assert_eq!(outcome_label(t), "timeout", "{reason:?}");
            assert_eq!(status_label(t), "incomplete", "{reason:?}");
            assert!(permitted_outcomes().contains(&outcome_label(t)));
        }
    }

    #[test]
    fn a_round_cap_exit_reports_an_incomplete_run() {
        assert_eq!(
            status_label(terminal(true, None, Some(TurnEndReason::RoundCap), false)),
            "incomplete",
            "a run that ended at the tool-round cap reported itself finished"
        );
    }

    /// The two fields answer different questions, so the SAME turn renders
    /// differently — deliberately, from one classification.
    #[test]
    fn one_classification_renders_two_honest_answers() {
        let t = terminal(true, None, Some(TurnEndReason::RoundCap), false);
        assert_eq!(outcome_label(t), "timeout", "excluded from scoring");
        assert_eq!(
            status_label(t),
            "incomplete",
            "and honestly named on our own line"
        );
    }

    #[test]
    fn clean_turn_is_completed() {
        assert_eq!(
            outcome_label(terminal(true, None, None, false)),
            "completed"
        );
    }

    #[test]
    fn model_class_is_model_error() {
        assert_eq!(
            outcome_label(terminal(false, Some(ErrorClass::Model), None, false)),
            "model_error"
        );
    }

    #[test]
    fn transport_class_is_transport_error() {
        assert_eq!(
            outcome_label(terminal(false, Some(ErrorClass::Transport), None, false)),
            "transport_error"
        );
    }

    #[test]
    fn timeout_class_is_timeout() {
        assert_eq!(
            outcome_label(terminal(false, Some(ErrorClass::Timeout), None, false)),
            "timeout"
        );
    }

    #[test]
    fn harness_class_and_unclassified_failures_are_harness_error() {
        assert_eq!(
            outcome_label(terminal(false, Some(ErrorClass::Harness), None, false)),
            "harness_error"
        );
        // A spawn/thread failure never reached a dispatch — no class at all.
        // Fail-closed: it must not masquerade as a model result.
        assert_eq!(
            outcome_label(terminal(false, None, None, false)),
            "harness_error"
        );
    }

    // --- one test per parse-status signal line ---

    #[test]
    fn no_parseable_tool_call_line_shape() {
        assert_eq!(
            parse_signal_line(&ParseSignal::NoParseableToolCall { round: 3 }),
            serde_json::json!({"kind": "no_parseable_tool_call", "round": 3})
        );
    }

    #[test]
    fn recovered_tool_call_line_names_the_dialect() {
        assert_eq!(
            parse_signal_line(&ParseSignal::RecoveredToolCall {
                round: 1,
                dialect: ToolCallDialect::FunctionTag,
                calls: vec![],
            }),
            serde_json::json!({
                "kind": "recovered_tool_call", "round": 1, "dialect": "function_tag"
            })
        );
    }

    #[test]
    fn reasoning_overflow_line_carries_the_bounded_recovery_result() {
        let signal = BehaviorSignal::ReasoningOverflow {
            round: 0,
            reasoning_overflow_detected: true,
            continuation_attempted: true,
            continuation_succeeded: true,
            finish_reason: "length".into(),
            reasoning_tokens_estimate: 2500,
        };
        assert_eq!(
            behavior_signal_line(&signal),
            serde_json::json!({
                "kind": "reasoning_overflow",
                "round": 0,
                "reasoning_overflow_detected": true,
                "continuation_attempted": true,
                "continuation_succeeded": true,
                "finish_reason": "length",
                "reasoning_tokens_estimate": 2500,
            })
        );
    }

    #[test]
    fn chat_completion_finish_line_records_backend_reason() {
        let signal = BehaviorSignal::ChatCompletionFinish {
            round: 3,
            finish_reason: Some("length".into()),
        };
        assert_eq!(
            behavior_signal_line(&signal),
            serde_json::json!({
                "kind": "chat_completion_finish",
                "round": 3,
                "finish_reason": "length",
            })
        );
    }

    // --- the record itself ---

    /// The record round-trips as valid JSON with EXACTLY the contract-v2
    /// fields — no extras for the bench to trip on, none of ours missing.
    #[test]
    fn record_round_trips_with_exactly_the_contract_fields() {
        let record = contract_record(&inputs());
        // Round-trip through the wire form.
        let wire = record.to_string();
        let parsed: serde_json::Value = serde_json::from_str(&wire).expect("valid JSON");
        let keys: Vec<&str> = {
            let mut k: Vec<&str> = parsed.as_object().unwrap().keys().map(|s| &**s).collect();
            k.sort_unstable();
            k
        };
        assert_eq!(
            keys,
            vec![
                "agent",
                "agent_version",
                "backend",
                "contract_version",
                "effective_config",
                "effective_model",
                "outcome",
                "receipt",
                "requested_model",
                "timing",
            ],
            "exactly the contract fields (model_digest absent: not supplied)"
        );
        assert_eq!(parsed["contract_version"], "2");
        assert_eq!(parsed["agent"], "newt-agent");
        assert_eq!(
            parsed["agent_version"],
            newt_core::build_info::VERSION_WITH_COMMIT
        );
        assert_eq!(
            parsed["backend"],
            serde_json::json!({"name": "dgx", "kind": "openai"})
        );
        assert_eq!(
            parsed["effective_config"],
            serde_json::json!({
                "context_window": 32768, "tenacity": "normal",
                "initiative": "measured",
                "cognition": "default", "crew": "off", "ocap": "off",
                "max_rounds": 40
            })
        );
        // 500 tokens over 10s ⇒ 50 tok/s, derived — never measured twice.
        assert_eq!(
            parsed["timing"],
            serde_json::json!({"wall_ms": 10_000, "gen_tokens": 500, "tok_s": 50.0})
        );
        // #2314: the whole receipt, pinned — a new entry or a renamed state is
        // a deliberate edit here, not a silent widening.
        assert_eq!(
            parsed["receipt"],
            serde_json::json!({"features": {
                "scratchpad": {"state": "unavailable", "reason": "no --scratchpad-state was supplied"},
                "code_search": {"state": "unsupported", "reason": "headless builds no retrieval index"},
                "crew": {"state": "instantiated"},
            }})
        );
    }

    /// An opted-in scratchpad names what a reader needs to reproduce it; the
    /// seed id is the caller's, carried verbatim.
    #[test]
    fn an_instantiated_scratchpad_names_its_fresh_scope_and_seed() {
        let f = InstantiatedFeatures {
            scratchpad: true,
            ..InstantiatedFeatures::default()
        };
        assert_eq!(
            feature_receipt(Some(f), &[], Some("bseed")).unwrap()["features"]["scratchpad"],
            serde_json::json!({"state": "instantiated", "scope": "fresh", "seed": "bseed"})
        );
    }

    /// `requested` is what a required feature reports when the turn did not
    /// confirm it: a drift past admission, or no outcome at all. Unrequired
    /// entries keep their ordinary states, and with no outcome and no
    /// requirement nothing is known, so nothing is written.
    #[test]
    fn a_required_feature_the_turn_did_not_confirm_is_requested() {
        let requested = serde_json::json!({
            "state": "requested",
            "reason": "required, but the turn did not confirm it was instantiated",
            "required": true,
        });
        let crew_only = InstantiatedFeatures {
            crew: true,
            ..InstantiatedFeatures::default()
        };
        let receipt =
            feature_receipt(Some(crew_only), &[Feature::Crew, Feature::Scratchpad], None).unwrap();
        assert_eq!(
            receipt["features"]["crew"],
            serde_json::json!({"state": "instantiated", "required": true})
        );
        assert_eq!(receipt["features"]["scratchpad"], requested);
        assert_eq!(receipt["features"]["code_search"]["state"], "unsupported");

        assert_eq!(
            feature_receipt(None, &[Feature::Scratchpad], None),
            Some(serde_json::json!({"features": {"scratchpad": requested}}))
        );
        assert_eq!(feature_receipt(None, &[], None), None);
    }

    /// Admission refuses with the receipt's own state and reason, and admits a
    /// requirement the run supplies.
    #[test]
    fn admission_names_the_receipts_state_and_reason() {
        let refused = admit_required(&[Feature::Crew, Feature::CodeSearch], |f| {
            f == Feature::Crew
        })
        .unwrap_err()
        .to_string();
        assert_eq!(
            refused,
            "required feature `code_search` is unsupported: headless builds no retrieval index"
        );
        assert!(admit_required(&[Feature::Crew], |f| f == Feature::Crew).is_ok());
    }

    /// The guard's twin: an optional stanza that collides with a field already
    /// written is a silent rename, and must not pass.
    #[test]
    #[cfg(debug_assertions)]
    #[should_panic(expected = "would overwrite an existing field")]
    fn a_conditional_stanza_never_overwrites_an_existing_field() {
        let mut record = contract_record(&inputs());
        conditional_stanza(&mut record, "outcome", Some("completed"));
    }

    #[test]
    fn smart_harness_configuration_is_declared_with_a_permitted_v1_outcome() {
        let manifest = serde_json::json!({"head":"retained-head", "invocation_mode":"fresh", "configuration":{"auxiliary":{"placement":"cpu","max_calls":4}}});
        let mut inputs = inputs();
        inputs.smart_harness = Some(&manifest);
        let record = contract_record(&inputs);
        assert_eq!(record["effective_config"]["smart_harness"], manifest);
        assert_eq!(record["contract_version"], "2");
        assert!(permitted_outcomes().contains(&record["outcome"].as_str().unwrap()));
    }

    /// #2524 item 1 observability requirement: every OCAP durable grant
    /// admitted into the run's caveats must be visible on the contract
    /// record, and an empty admission list must not fabricate a stanza.
    #[test]
    fn durable_grants_are_listed_when_admitted_and_omitted_when_none() {
        let i = inputs();
        assert!(
            contract_record(&i)["effective_config"]
                .get("durable_grants")
                .is_none(),
            "no admitted grants must mean no stanza, not an empty array"
        );
        let mut with_grants = inputs();
        let admitted = vec!["fs_read:/opt/canvas-token".to_string()];
        with_grants.durable_grants = &admitted;
        assert_eq!(
            contract_record(&with_grants)["effective_config"]["durable_grants"],
            serde_json::json!(["fs_read:/opt/canvas-token"])
        );
    }

    /// `model_digest` appears ONLY when operator-supplied — never fabricated.
    #[test]
    fn model_digest_only_when_supplied() {
        let mut i = inputs();
        assert!(contract_record(&i).get("model_digest").is_none());
        i.model_digest = Some("a3f6…deadbeef");
        assert_eq!(contract_record(&i)["model_digest"], "a3f6…deadbeef");
    }

    /// Unknown optionals are OMITTED, not nulled: no usage ⇒ no `gen_tokens`
    /// / `tok_s`; no `--context-window` pin ⇒ no `context_window`.
    #[test]
    fn unknown_optionals_are_omitted_not_invented() {
        let mut i = inputs();
        i.gen_tokens = None;
        i.context_window = None;
        i.features = None;
        let record = contract_record(&i);
        assert_eq!(record["timing"], serde_json::json!({"wall_ms": 10_000}));
        assert!(record["effective_config"].get("context_window").is_none());
        assert!(record.get("receipt").is_none());
        // A zero wall clock cannot derive a rate.
        i.gen_tokens = Some(500);
        i.wall_ms = 0;
        assert!(contract_record(&i)["timing"].get("tok_s").is_none());
    }
}

#[cfg(test)]
#[path = "headless_contract_context_tests.rs"]
mod context_tests;