devflow_core/

agent_result.rs

//! Agent completion detection — parses DEVFLOW_RESULT markers and evaluates
//! exit codes to determine whether a coding agent succeeded or failed.
//!
//! Four-layer decision engine:
//! 0. Run operator-authored external post-condition probes (authoritative failure)
//! 1. Parse DEVFLOW_RESULT from agent stdout (authoritative for ordinary plans)
//! 2. Exit code + commit count gate (reliable fallback)
//! 3. Process gone + commits exist (last resort warning)

use crate::config::GitFlowConfig;
use crate::git::git_command;
use crate::phase_id::PhaseId;
use crate::stage::Stage;
use crate::state::State;
use std::path::{Path, PathBuf};

/// Parsed agent completion result.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct AgentResult {
    pub status: AgentStatus,
    pub exit_code: Option<i32>,
    pub reason: Option<String>,
    pub commits: Option<u32>,
    pub summary: Option<String>,
    /// The Validate stage's self-reported verdict — distinct from `status`.
    /// `status` reports whether the stage's task (running `/gsd-validate-phase`)
    /// completed; `verdict` reports whether validation ITSELF passed. Only
    /// `Some(Verdict::Pass)` should advance Validate to Ship; `Some(Verdict::Gaps)`
    /// and `None` both gate/loop back to Code (see `advance()`'s Validate arm).
    /// Ignored entirely for non-Validate stages.
    ///
    /// Deserialized leniently via [`deserialize_verdict_lenient`]: an absent,
    /// unknown, or mis-cased value becomes `None` rather than failing the
    /// whole `AgentResult` parse (T-13-14) — a malformed verdict must never
    /// silently drop a valid `status` to Layer 2.
    #[serde(default, deserialize_with = "deserialize_verdict_lenient")]
    pub verdict: Option<Verdict>,
    /// Which evaluation layer (0-3) produced this result (D-10, 17-01). Set by
    /// every constructor in this module; `None` is reserved for test-only
    /// fixture literals that don't route through the real cascade.
    #[serde(default)]
    pub decided_by_layer: Option<u8>,
}

/// Agent completion status determined by DevFlow.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum AgentStatus {
    /// Agent self-reported success via DEVFLOW_RESULT.
    Success,
    /// Agent self-reported failure, or exit code + commit gate indicated failure.
    Failed,
    /// Agent stopped because an upstream API or usage quota rate-limited it.
    RateLimited,
    /// No signal received — fallback to exit code / commit heuristic.
    Unknown,
    /// Layer 2 classified the process as killed for resource exhaustion
    /// (exit code 137, typically SIGKILL from an OOM killer) (D-07, 17b).
    #[serde(rename = "resource_killed")]
    ResourceKilled,
    /// Layer 2 classified the process as unable to start (exit code 127,
    /// typically "command not found") (D-07, 17b).
    #[serde(rename = "agent_unavailable")]
    AgentUnavailable,
    /// The pipe-owning monitor gave up waiting: the child's stream went silent
    /// for longer than the idle window and DevFlow terminated it (D-06, 31-02).
    ///
    /// Deliberately distinct from BOTH neighbours it would otherwise collapse
    /// into. Against `Failed`: nothing reported a failure — the agent simply
    /// stopped talking, and a graceful close would fall through to Layer 2,
    /// which scores partial commits as `Success` (999.64 reborn inside its own
    /// fix). Against `ResourceKilled`: the box did not run out of memory;
    /// DevFlow itself did the killing. Only a third variant lets the completion
    /// oracle tell "we gave up waiting" from either.
    ///
    /// The explicit `#[serde(rename)]` is required, not stylistic: the
    /// enum-level `rename_all = "lowercase"` would collapse the two words into
    /// `idletimeout`. The two existing two-word variants above carry the same
    /// rename for the same reason.
    #[serde(rename = "idle_timeout")]
    IdleTimeout,
}

impl AgentStatus {
    /// The wire-format name for this variant, pinned equal to
    /// `serde_json::to_string(&self)` with the surrounding quotes stripped
    /// (see the `as_wire_str_matches_serde_form` test). Exhaustive match with
    /// NO wildcard arm — adding a variant without updating this is a compile
    /// error. This is the sanctioned replacement for
    /// `format!("{:?}", status).to_ascii_lowercase()`, which collapses word
    /// boundaries on multi-word variants (review consensus #1).
    pub fn as_wire_str(&self) -> &'static str {
        match self {
            AgentStatus::Success => "success",
            AgentStatus::Failed => "failed",
            AgentStatus::RateLimited => "ratelimited",
            AgentStatus::Unknown => "unknown",
            AgentStatus::ResourceKilled => "resource_killed",
            AgentStatus::AgentUnavailable => "agent_unavailable",
            AgentStatus::IdleTimeout => "idle_timeout",
        }
    }
}

/// The Validate stage's self-reported verdict (13b verdict-vs-ran split).
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Verdict {
    /// Validation found no gaps — ready to advance to Ship.
    Pass,
    /// Validation found gaps that still need fixing — must loop back to Code
    /// (or gate, depending on the consecutive-failure threshold).
    Gaps,
}

/// Deserialize `verdict` leniently: an absent, unknown, or mis-cased value
/// (e.g. `"wat"`, `"Pass"`) becomes `Ok(None)` rather than an error, so a
/// malformed verdict never fails the whole `from_str::<AgentResult>` parse
/// and silently drops a valid `status` to Layer 2 (T-13-14, consensus #5).
///
/// Matching is intentionally exact-case (only the wire-format lowercase
/// strings `"pass"`/`"gaps"` are accepted) — a mis-cased value like `"Pass"`
/// is NOT case-folded into a match; it is treated the same as an unknown
/// value and maps to `None`, so a subtly wrong-case verdict fails safe
/// (gate/loop) instead of silently passing.
///
/// WR-09 (13-REVIEW.md): decodes as `serde_json::Value` first, then only
/// pattern-matches the string case — a non-string JSON type (`true`, `123`,
/// an object) is a wrong *type*, not a malformed string value, and must
/// still fall through to `None` rather than erroring out the entire
/// `AgentResult` parse (the same guarantee this deserializer already gives
/// mis-cased/unknown string values).
fn deserialize_verdict_lenient<'de, D>(deserializer: D) -> Result<Option<Verdict>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw = <Option<serde_json::Value> as serde::Deserialize>::deserialize(deserializer)?;
    Ok(raw.and_then(|v| {
        v.as_str().and_then(|s| match s {
            "pass" => Some(Verdict::Pass),
            "gaps" => Some(Verdict::Gaps),
            _ => None,
        })
    }))
}

/// Errors produced by agent result evaluation.
#[derive(Debug, thiserror::Error)]
pub enum ResultError {
    #[error("I/O error reading agent output: {0}")]
    Io(#[from] std::io::Error),
    #[error("phase directory not found")]
    NoPhaseDir,
}

/// Search stdout for a DEVFLOW_RESULT marker.
///
/// The marker is a single line starting with `DEVFLOW_RESULT:` followed by
/// a JSON object with at minimum a `status` field. Matching is case-insensitive.
///
/// When an agent is run with `--output-format json` (e.g. Claude), its final
/// message is wrapped in a JSON result envelope with the text — and its
/// embedded newlines — escaped inside a `result` field. In that case the
/// marker never appears at the start of a line, so we first unwrap the
/// envelope and search the inner text.
pub fn parse_devflow_result(stdout: &str) -> Option<AgentResult> {
    // normalise_stream_marker_provenance on BOTH arms: parse_marker_lines
    // deserializes the agent's own JSON, so without the overwrite an agent
    // writing `"decided_by_layer":0` into its marker forges Layer-0
    // external-verification provenance, which `classify_validate_outcome`
    // (pipeline_outcomes.rs) trusts when classifying a Validate stage. The
    // stream path has normalised since 30-01; this generic path — the one
    // production hits today — did not (fourth adversarial pass, Medium 1;
    // the class 999.67 tracks).
    if let Some(inner) = extract_json_result_text(stdout)
        && let Some(result) = parse_marker_lines(&inner)
    {
        return Some(normalise_stream_marker_provenance(result));
    }
    parse_marker_lines(stdout).map(normalise_stream_marker_provenance)
}

/// Detect agent-specific rate-limit output and return the retry description.
///
/// Claude can emit a JSON result envelope when run with `--output-format json`;
/// Codex commonly emits plain text such as "Try again at ...". This function is
/// intentionally conservative so ordinary progress text does not become a
/// false positive.
pub fn detect_rate_limit(stdout: &str) -> Option<String> {
    detect_claude_rate_limit(stdout).or_else(|| detect_codex_rate_limit(stdout))
}

fn detect_claude_rate_limit(stdout: &str) -> Option<String> {
    // strip_corruption_padding, not trim(): this detector OUTRANKS the generic
    // envelope-failure detector, and rate-limit envelopes carry `is_error:
    // true`. When only the lower-precedence detector stripped edge corruption,
    // one stray byte inverted the precedence — a RateLimited envelope (routes
    // to auto-resume) decayed into a generic Failed (routes to review/gating).
    // Fifth adversarial pass, Medium 1.
    let value: serde_json::Value = serde_json::from_str(strip_corruption_padding(stdout)).ok()?;
    let rate_limited = json_has_str(&value, "subtype", "error_rate_limit")
        || json_has_i64(&value, "api_error_status", 429)
        || json_has_i64(&value, "status", 429)
        || json_has_i64(&value, "status_code", 429);
    if !rate_limited {
        return None;
    }
    json_find_key(&value, "retry_after")
        .and_then(json_scalar_to_string)
        .or_else(|| json_find_key(&value, "message").and_then(json_scalar_to_string))
        .or_else(|| json_find_key(&value, "error").and_then(json_scalar_to_string))
        .or_else(|| Some("usage limit".to_string()))
}

fn detect_codex_rate_limit(stdout: &str) -> Option<String> {
    // This heuristic exists for Codex's PLAIN-TEXT output. JSONL event lines
    // are authoritative and handled by parse_codex_event_result — scanning
    // them here false-positives on document content echoed into events
    // (13-06 dogfood finding: GSD reference tables mentioning "rate limiting"
    // were read by the agent, echoed into an `item.completed` payload, and
    // this scan returned that entire multi-KB line as the "retry time").
    // The JSON-line exclusion applies the SAME edge-strip policy as
    // ParsedCapture::parse (sixth-pass Medium 4): an event line whose leading
    // byte was corrupted to U+FFFD failed the bare parse here and was treated
    // as prose — re-admitting the exact multi-KB echoed-document false
    // positive this filter exists to exclude, after ParsedCapture had already
    // correctly recovered the line as an event.
    let stdout: String = stdout
        .lines()
        .filter(|line| {
            serde_json::from_str::<serde_json::Value>(strip_corruption_padding(line))
                .map(|v| !v.is_object())
                .unwrap_or(true)
        })
        .collect::<Vec<_>>()
        .join("\n");
    let stdout = stdout.as_str();
    let lower = stdout.to_ascii_lowercase();
    if let Some(idx) = lower.find("try again at ") {
        let start = idx + "try again at ".len();
        let retry = stdout[start..]
            .lines()
            .next()
            .unwrap_or_default()
            .trim()
            .trim_end_matches(['.', ',', ';'])
            .trim();
        if !retry.is_empty() {
            return Some(retry.to_string());
        }
    }

    // "429" counts as rate-limit evidence only as a STANDALONE token
    // (sixth-pass Medium 5): a bare substring check fired on "processed issue
    // #429 successfully" and any number containing 429, routing a healthy run
    // into auto-resume. A neighbor that is alphanumeric or '#' means the
    // digits belong to something else.
    fn standalone_429(line: &str) -> bool {
        let bytes = line.as_bytes();
        line.match_indices("429").any(|(i, _)| {
            let before_ok = i == 0 || {
                let b = bytes[i - 1];
                !b.is_ascii_alphanumeric() && b != b'#'
            };
            let after_ok = i + 3 >= bytes.len() || !bytes[i + 3].is_ascii_alphanumeric();
            before_ok && after_ok
        })
    }

    if lower.contains("usage limit") || lower.contains("rate limit") || standalone_429(&lower) {
        stdout
            .lines()
            .find(|line| {
                let line = line.to_ascii_lowercase();
                line.contains("usage limit") || line.contains("rate limit") || standalone_429(&line)
            })
            .map(str::trim)
            .filter(|line| !line.is_empty())
            .map(str::to_string)
            .or_else(|| Some("usage limit".to_string()))
    } else {
        None
    }
}

/// If `stdout` is a JSON result envelope, return the decoded `result` text
/// field (with escapes such as `\n` resolved). Returns `None` for plain text.
fn extract_json_result_text(stdout: &str) -> Option<String> {
    // strip_corruption_padding, not trim(): a stray invalid byte decoded to
    // U+FFFD at either EDGE of the envelope must not defeat the `{` guard
    // (third-pass High). Interior corruption still fails the parse, by design.
    let trimmed = strip_corruption_padding(stdout);
    if !trimmed.starts_with('{') {
        return None;
    }
    let value: serde_json::Value = serde_json::from_str(trimmed).ok()?;
    value.get("result")?.as_str().map(str::to_string)
}

/// Read the top-level `session_id` string from a Claude JSON result envelope
/// (`--output-format json`). Returns `None` for plain-text stdout, a
/// non-JSON-object envelope, an envelope with no `session_id` key, or a
/// `session_id` of a non-string JSON type — never panics.
///
/// D-04 / T-28-04 (this plan's `<threat_model>`): deliberately reads ONLY the
/// envelope's TOP-LEVEL `session_id` key via a direct [`serde_json::Value::get`],
/// never the module's [`json_find_key`]/[`json_scan`] traversal helpers. Those
/// helpers descend into nested objects, and the agent-authored `DEVFLOW_RESULT`
/// marker payload — embedded inside this same envelope's `result` text and
/// deserialized by [`parse_marker_lines`] directly into [`AgentResult`] — is
/// reachable that way. A top-level `get` makes it true BY CONSTRUCTION that an
/// agent cannot redirect the session DevFlow later resumes into by planting a
/// different `session_id` key inside its own self-authored marker JSON.
/// Regression test: `session_id_in_devflow_result_marker_is_not_returned`.
///
/// Deliberate deviation from RESEARCH.md § "Discretion Resolutions" item 5,
/// which suggested adding a `session_id` field directly to [`AgentResult`].
/// NOT done: `parse_marker_lines` deserializes the agent's own
/// `DEVFLOW_RESULT` JSON straight into `AgentResult` via `serde_json::from_str`,
/// so a `#[serde(default)]` field there would be agent-settable — the agent
/// could name the session DevFlow resumes into (T-28-04). A standalone reader
/// over the top-level envelope key carries no such surface and is equally
/// available to every caller; D-04's persistence target (`State::session_id`)
/// is unchanged, only the carrier differs.
pub fn claude_session_id(stdout: &str) -> Option<String> {
    // strip_corruption_padding, not trim(): a stray invalid byte decoded to
    // U+FFFD at either EDGE of the envelope must not defeat the `{` guard
    // (third-pass High). Interior corruption still fails the parse, by design.
    let trimmed = strip_corruption_padding(stdout);
    if !trimmed.starts_with('{') {
        return None;
    }
    let value: serde_json::Value = serde_json::from_str(trimmed).ok()?;
    value.get("session_id")?.as_str().map(str::to_string)
}

/// Read the CLI-emitted `session_id` from a Claude `--output-format
/// stream-json` JSONL capture: the top-level `session_id` of the LAST
/// `system`/`init` event. `None` for any other capture shape.
///
/// The stream sibling of [`claude_session_id`], and it carries that function's
/// D-04 / T-28-04 discipline **for the same reason** — read its doc comment
/// before changing anything here. Only the event's TOP-LEVEL `session_id` is
/// read, via a direct [`serde_json::Value::get`]; the
/// [`json_find_key`]/[`json_scan`] traversal helpers are NOT to be used. They
/// descend into nested objects, and a stream carries agent-authored text in
/// every `result` event — including the `DEVFLOW_RESULT` marker JSON that
/// [`parse_marker_lines`] deserializes. A traversal would make a `session_id`
/// the agent planted in its own marker reachable, handing it the ability to
/// name the session DevFlow later resumes into (T-30-11). Regression test:
/// `claude_stream_session_id_ignores_agent_planted_value`.
///
/// The LAST `init` event wins, consistent with the last-`result`-wins
/// convention. Verified against the archived capture: its three `init` events
/// (lines 5, 32 and 47) all carry the same `session_id`, so last-wins and
/// first-wins agree on today's evidence — but only last-wins stays correct if a
/// future capture rotates the value mid-stream. Three `init` events do NOT mean
/// three sessions: session continuity must never be keyed off "have I seen an
/// `init` event".
///
/// No `session_id` field is added to [`AgentResult`] — see
/// [`claude_session_id`]'s doc comment for why that design stays rejected.
pub fn claude_stream_session_id(stdout: &str) -> Option<String> {
    let capture = ParsedCapture::parse(stdout);
    if classify(&capture) != CaptureKind::ClaudeStream {
        return None;
    }

    // A session can rotate mid-capture: each turn opens with its own `init`, and
    // the LAST one carries the id a resume must target. A torn later `init` is
    // invisible to the scan below, which would silently return an EARLIER
    // session's id — resuming the wrong session with a token that looks
    // perfectly valid. Fail closed on any TORN JSON line: it could have been a
    // newer `init`. `None` costs a resume; the wrong id corrupts one. (Third
    // adversarial pass, 2026-08-02.)
    //
    // Prose noise lines do NOT block recovery — an `init` is a JSON line, so a
    // non-`{` line can never be a torn one. The first version of this guard
    // failed closed on ANY unparsed line and rejected captures with benign
    // interleaved progress output (fourth adversarial pass, Medium 3).
    if capture.torn_json_line_present() {
        return None;
    }

    capture
        .events
        .iter()
        .rev()
        .find(|v| {
            v.get("type").and_then(serde_json::Value::as_str) == Some("system")
                && v.get("subtype").and_then(serde_json::Value::as_str) == Some("init")
        })?
        .get("session_id")?
        .as_str()
        .map(str::to_string)
}

/// Thin file-reading wrapper over the two session-id readers: reads the phase's
/// captured stdout file (via [`stdout_path`]) and delegates. `None` for a
/// missing capture file, never an `Err` — mirrors [`evaluate_layer1`]'s
/// lossy-read convention (CR-01: one invalid UTF-8 byte from raw `sh`
/// redirection must not silently disable this reader).
///
/// [`claude_stream_session_id`] is tried FIRST, then [`claude_session_id`].
/// Stream-first is safe and behavior-preserving: the stream gate
/// ([`is_claude_event_stream`]) declines a single-document envelope, so every
/// capture shape that ships today still resolves through `claude_session_id`
/// bit-for-bit. Without this chain the Phase 28 checkpoint-resume path — whose
/// whole delivery is reconstructing a session via `claude --resume` — returns
/// `None` for every `stream-json` capture.
pub fn session_id_from_capture(project_root: &Path, phase: PhaseId) -> Option<String> {
    let stdout = read_capture(&stdout_path(project_root, phase))?;
    claude_stream_session_id(&stdout).or_else(|| claude_session_id(&stdout))
}

/// The ONE decode policy for capture files: read the bytes and replace invalid
/// UTF-8 with U+FFFD. Every capture-file consumer (`evaluate_layer1`,
/// `checkpoint_reported_in_capture`, `session_id_from_capture`) reads through
/// here, so the policy cannot silently diverge per call site again.
///
/// REPLACE, never drop. A drop-based decode was tried (third adversarial pass
/// remediation) and refuted by the fourth pass: deleting invalid bytes JOINS
/// the tokens on either side, and `DEVFLOW_RESULT: {"status":"suc<FF>cess"}`
/// decoded to a fabricated, VALID success marker that short-circuited a
/// nonzero exit code. Replacement keeps corruption visible: the marker parser
/// sees `suc\u{FFFD}cess`, which is not a recognized status, and correctly
/// refuses to trust it. Consumers that need to tolerate corruption at the
/// EDGES of a single-document capture strip it explicitly via
/// [`strip_corruption_padding`] — bounded, and incapable of joining tokens.
fn read_capture(path: &Path) -> Option<String> {
    let bytes = std::fs::read(path).ok()?;
    Some(String::from_utf8_lossy(&bytes).into_owned())
}

/// Trim whitespace and U+FFFD replacement characters from both ends of a
/// single-document capture.
///
/// U+FFFD is what [`read_capture`] substitutes for invalid bytes, and it is a
/// printing, non-whitespace character — so a stray byte written before or after
/// the JSON envelope survives `trim()` and defeats every `starts_with('{')`
/// guard. That was the third pass's High: Layer 1 abstained on an authoritative
/// `is_error: true` and the exit-code fallback turned a reported failure into a
/// Ship-gate success. Stripping only the EDGES is deliberate: corruption inside
/// the envelope must stay visible and fail the parse, because "repairing" it is
/// how the fourth pass's marker-fabrication High happened.
fn strip_corruption_padding(s: &str) -> &str {
    s.trim_matches(|c: char| c.is_whitespace() || c == '\u{FFFD}')
}

// WR-12 (13-REVIEW.md), revised: these traversal helpers run on the coding
// agent's raw stdout (via detect_claude_rate_limit, which every `devflow
// advance` invocation runs through evaluate_layer1), so deeply nested JSON —
// accidental or adversarial — must not stack-overflow the process. The
// traversal is iterative (an explicit worklist), so nesting depth never
// consumes call stack and no depth cap is needed. The first WR-12 fix capped
// recursion at 64, which silently missed keys at depths 64–128 — nesting
// serde_json's default 128-level parse recursion limit (the only producer of
// these `Value`s) accepts just fine.

/// Depth-first pre-order scan over every JSON object in `value`, returning
/// the first `Some` produced by `visit` on an object's map.
fn json_scan<'a, T>(
    value: &'a serde_json::Value,
    visit: impl Fn(&'a serde_json::Map<String, serde_json::Value>) -> Option<T>,
) -> Option<T> {
    let mut stack = vec![value];
    while let Some(current) = stack.pop() {
        match current {
            serde_json::Value::Object(map) => {
                if let Some(found) = visit(map) {
                    return Some(found);
                }
                // Push in reverse so pop order preserves document order.
                for child in map.values().rev() {
                    stack.push(child);
                }
            }
            serde_json::Value::Array(values) => {
                for child in values.iter().rev() {
                    stack.push(child);
                }
            }
            _ => {}
        }
    }
    None
}

fn json_has_str(value: &serde_json::Value, key: &str, expected: &str) -> bool {
    json_scan(value, |map| {
        (map.get(key)?.as_str()? == expected).then_some(())
    })
    .is_some()
}

fn json_has_i64(value: &serde_json::Value, key: &str, expected: i64) -> bool {
    json_scan(value, |map| {
        (map.get(key)?.as_i64()? == expected).then_some(())
    })
    .is_some()
}

fn json_find_key<'a>(value: &'a serde_json::Value, key: &str) -> Option<&'a serde_json::Value> {
    json_scan(value, |map| map.get(key))
}

fn json_scalar_to_string(value: &serde_json::Value) -> Option<String> {
    match value {
        serde_json::Value::String(s) => Some(s.clone()),
        serde_json::Value::Number(n) => Some(n.to_string()),
        _ => None,
    }
}

/// Read the top-level `is_error` boolean (and, if present, `num_turns`) from
/// a Claude JSON result envelope (`--output-format json`) and treat
/// `is_error: true` as an authoritative Layer-1 failure.
///
/// This is checked BEFORE the `DEVFLOW_RESULT` marker path in
/// [`evaluate_layer1`], so `is_error: true` OVERRIDES a stale/echoed success
/// marker embedded in the same envelope's `result` text — the envelope is
/// authoritative for errors. `is_error` absent or `false` returns `None`,
/// deferring to the marker path and, ultimately, Layer 2. It runs AFTER
/// `detect_claude_rate_limit`, though: rate-limit envelopes also carry
/// `is_error: true`, and the specific `RateLimited` classification (which
/// drives the primary rate-limit resume cron) must win over this
/// generic `Failed`.
///
/// Per RESEARCH Pitfall 5, `is_error` (not specific `subtype` strings) is
/// the documented, stable signal — this does not special-case non-success
/// subtype values beyond what already exists in `detect_claude_rate_limit`.
fn detect_claude_envelope_failure(stdout: &str) -> Option<AgentResult> {
    // strip_corruption_padding, not trim(): a stray invalid byte decoded to
    // U+FFFD at either EDGE of the envelope must not defeat the `{` guard
    // (third-pass High). Interior corruption still fails the parse, by design.
    let trimmed = strip_corruption_padding(stdout);
    if !trimmed.starts_with('{') {
        return None;
    }
    let value: serde_json::Value = serde_json::from_str(trimmed).ok()?;
    let is_error = value.get("is_error")?.as_bool()?;
    if !is_error {
        return None;
    }

    let num_turns = value.get("num_turns").and_then(serde_json::Value::as_u64);
    let base_reason = value
        .get("result")
        .and_then(serde_json::Value::as_str)
        .map(str::to_string)
        .or_else(|| {
            value
                .get("subtype")
                .and_then(serde_json::Value::as_str)
                .map(str::to_string)
        })
        .unwrap_or_else(|| "agent reported is_error".to_string());
    let reason = match num_turns {
        Some(n) => format!("{base_reason} (num_turns: {n})"),
        None => base_reason,
    };

    Some(AgentResult {
        status: AgentStatus::Failed,
        exit_code: None,
        reason: Some(reason),
        commits: None,
        summary: None,
        verdict: None,
        decided_by_layer: Some(1),
    })
}

/// The rendered VALUE of a human-blocking checkpoint's `**Gate:**` line.
///
/// **CONFIRMED against a live end-to-end run (2026-07-31).** Assumption A1 is
/// closed. A real `devflow start` run drove a synthetic phase declaring a
/// `gate="blocking-human"` task through DevFlow's own monitor process (not a
/// Claude Code agent session, which is what blocked `28-PROBE.md`'s original
/// attempt at the Bash-tool permission classifier). The checkpoint fired and
/// `.devflow/phase-NN-stdout` captured it inside the JSON envelope's `result`
/// text as:
///
/// ```text
/// **Gate:** `blocking-human`
/// ```
///
/// The VALUE is what this constant holds. The surrounding markdown — bold
/// label, and a **code span around the value** — is handled by
/// [`text_reports_human_gate`]'s trim set, not by this constant.
///
/// The code span is the part RESEARCH.md did not predict. Its § "Architecture
/// Patterns / Pattern 2" derived the literal by reading the *emitting* source
/// (`gsd-executor.md:356`, `execute-phase.md:1053`) and predicted a bare
/// `**Gate:** blocking-human`. The real relay renders the value as a code
/// span, which defeated the original matcher entirely — see
/// [`text_reports_human_gate`] for that failure and its fix. Lesson worth
/// keeping: the emitting source told us the value, not the rendering.
const HUMAN_GATE_VALUE: &str = "blocking-human";

/// Confirm whether captured stdout reports a human-blocking checkpoint, by
/// searching for a `**Gate:**`-labeled line whose VALUE is exactly
/// [`HUMAN_GATE_VALUE`] — see that constant's doc comment for the live
/// observation (2026-07-31) the matched rendering is built from.
///
/// This is the CONFIRMATION half of D-01: it is only ever consulted AFTER
/// [`crate::verify::phase_has_blocking_human_checkpoint`] has already
/// returned `true` for the stage's plan(s) (D-01's static half, plan 28-01).
/// A false negative here is the SAFE direction — it falls back to today's
/// never-silent generic gate, losing nothing. A false positive is bounded by
/// the resume ceiling (`mode::MAX_CHECKPOINT_RESUMES`, plan 28-03) and
/// unconditionally recorded by the `checkpoint_auto_decided` audit event
/// (plan 28-03) — it can never silently authorize anything.
///
/// Searches BOTH the raw stdout text and — when the stdout is a Claude JSON
/// result envelope — the unescaped inner `result` text obtained via
/// [`extract_json_result_text`], because the `Gate:` line typically crosses
/// into the capture escaped inside that envelope (RESEARCH § "Common
/// Pitfalls / Pitfall 2": two indirections, subagent emission → orchestrator
/// relay → DevFlow's captured top-level stdout). Matching is
/// case-insensitive on the `Gate` LABEL and tolerates surrounding markdown
/// emphasis (`*`) and whitespace, but the VALUE comparison is exact — this
/// deliberately does NOT widen into a general "does this look like a
/// checkpoint" heuristic (D-02 rejected that class of predicate); the scope
/// is one declared field label with one enumerated value.
///
/// **A Claude `stream-json` capture takes a separate branch** and is answered
/// by [`claude_stream_reports_human_gate`] ALONE — it never consults raw stdout.
/// That is not an oversight to be "completed" later: under a stream capture the
/// raw stdout contains the operator's prompt echoed back as a `user` event, so
/// also scanning it would reinstate the exact false positive the branch exists
/// to remove (review constraint 3 — the unbounded raw scan is the reader that
/// "survives by accident" once the single-document invariant is gone). See that
/// function for which events are eligible and why.
///
/// The branch is taken when [`classify`] says [`CaptureKind::ClaudeStream`], so
/// a single-document envelope, plain text and a Codex stream all fall through to
/// the two-target logic below, unchanged (T-30-25). Classification is
/// deliberately weaker than [`is_claude_event_stream`]: requiring a parsed
/// `system`/`init` here made a single torn line fail OPEN back to the raw scan,
/// reinstating the echoed-prompt false positive this branch exists to remove.
/// See [`classify`] for the full rule set and the defects each rule encodes;
/// see [`is_claude_event_stream`] for why the verdict path keeps its stricter
/// init-only gate.
pub fn blocking_human_checkpoint_reported(stdout: &str) -> bool {
    let capture = ParsedCapture::parse(stdout);
    if classify(&capture) == CaptureKind::ClaudeStream {
        return claude_stream_reports_human_gate(&capture.events);
    }
    if text_reports_human_gate(stdout) {
        return true;
    }
    extract_json_result_text(stdout)
        .as_deref()
        .is_some_and(text_reports_human_gate)
}

/// Core matcher shared by both search targets (raw stdout and the unescaped
/// inner envelope text) in [`blocking_human_checkpoint_reported`]. Scans for
/// a case-insensitive `gate` label, tolerating surrounding markdown emphasis
/// (`*`), code-span backticks (`` ` ``), and whitespace up to the following
/// `:`, then compares the VALUE token immediately after the colon exactly
/// against [`HUMAN_GATE_VALUE`].
///
/// The backtick tolerance is not speculative — it is the single reason this
/// matcher failed against the first real checkpoint ever observed. The live
/// A1 run (2026-07-31) captured the value as a markdown code span,
/// ``**Gate:** `blocking-human` ``, and the original trim set (`*` and space
/// only) left the leading backtick in place, so the `take_while` below
/// terminated immediately and produced an EMPTY value token. The reader
/// returned `false` and a genuine checkpoint fell through to the generic
/// gate. Trimming the backtick is what makes the observed rendering match;
/// do not narrow this set back without re-running that live probe.
///
/// Note the closing backtick needs no handling: `take_while` already stops
/// at it, since a backtick is neither alphanumeric nor `-`.
fn text_reports_human_gate(text: &str) -> bool {
    let lower = text.to_ascii_lowercase();
    let mut search_from = 0;
    while let Some(rel_idx) = lower[search_from..].find("gate") {
        let idx = search_from + rel_idx;
        let after_label = &lower[idx + "gate".len()..];
        let after_label = after_label.trim_start_matches(['*', ' ', '`']);
        if let Some(rest) = after_label.strip_prefix(':') {
            let value_region = rest.trim_start_matches(['*', ' ', '`']);
            let value_token: String = value_region
                .chars()
                .take_while(|c| c.is_ascii_alphanumeric() || *c == '-')
                .collect();
            if value_token == HUMAN_GATE_VALUE {
                return true;
            }
        }
        search_from = idx + "gate".len();
    }
    false
}

/// Thin file-reading wrapper over [`blocking_human_checkpoint_reported`]:
/// reads the phase's captured stdout file (via [`stdout_path`]) and
/// delegates. `false` for a missing capture file, never an error.
pub fn checkpoint_reported_in_capture(project_root: &Path, phase: PhaseId) -> bool {
    let Some(stdout) = read_capture(&stdout_path(project_root, phase)) else {
        return false;
    };
    blocking_human_checkpoint_reported(&stdout)
}

/// Determine whether a set of parsed JSONL lines look like a Codex `--json`
/// event stream (as opposed to a single-document Claude envelope or plain
/// text) — i.e. at least one line is a `thread.started` or `turn.*` event.
pub(crate) fn is_codex_event_stream(events: &[serde_json::Value]) -> bool {
    events.iter().any(|v| {
        v.get("type")
            .and_then(serde_json::Value::as_str)
            .is_some_and(|t| t == "thread.started" || t.starts_with("turn."))
    })
}

/// Parse a Codex `--json` JSONL event stream (one JSON object per line) and
/// look at the LAST terminal event (`turn.completed` / `turn.failed`).
///
/// Only decisive when the captured stdout is actually a Codex event stream
/// (per [`is_codex_event_stream`]) — a single-document Claude envelope
/// (`type: "result"`, no `turn.*` lines) is not consumed here and returns
/// `None`, so the Claude envelope/marker paths handle it instead.
///
/// `turn.failed` is decisive: returns `AgentStatus::Failed` with `reason`
/// from `error.message`. A final `turn.completed` with no `DEVFLOW_RESULT`
/// marker returns `None` (defers to Layer 2) rather than an unconditional
/// Success — a marker-less turn must not silently advance a stage (this is
/// the composition fix that keeps a marker-less Validate run from
/// false-passing to Ship).
///
/// NOTE: written against the documented `--json` event schema (thread.started
/// / turn.started / item.* / turn.completed with usage / turn.failed with
/// error.message) but not yet verified against the installed Codex CLI
/// version — the 13-06 dogfood run captures real output and reconciles any
/// delta, the same empirical practice 12-12-SUMMARY.md used for Claude.
pub(crate) fn parse_codex_event_result(stdout: &str) -> Option<AgentResult> {
    let capture = ParsedCapture::parse(stdout);
    let events = &capture.events;

    if !is_codex_event_stream(events) {
        return None;
    }

    // Same trailing-torn rule as the Claude stream parser, same R1 root cause:
    // a torn JSON line after the last parsed event means the capture's tail —
    // where `turn.failed` would be — may be among the casualties. An earlier
    // `agent_message` success marker must not decide the stage over a tail we
    // provably failed to read. The Codex adapter is live in production, so
    // this is not a Phase-31 deferral.
    if capture.torn_json_after_last_matching(|_| true) {
        return Some(indeterminate_capture_failure());
    }

    // 999.107 #1: a terminal `turn.failed` must not be overridden by an
    // earlier `agent_message` success marker. Resolve BOTH the terminal event
    // and the marker once, then apply precedence: `turn.failed` is decisive
    // regardless of any success marker that preceded it (the pre-fix order
    // returned the marker before ever reading the terminal, so a stream ending
    // `success marker → turn.failed` was misread as Success).
    let terminal = events.iter().rev().find(|v| {
        matches!(
            v.get("type").and_then(serde_json::Value::as_str),
            Some("turn.completed") | Some("turn.failed")
        )
    });

    // Codex delivers the agent's DEVFLOW_RESULT self-report inside an
    // `agent_message` item's `text` — never as a raw stdout line — so the
    // top-level marker scan cannot see it (13-06 dogfood finding). The decoded
    // `text` is a plain marker line; reuse the marker parser on it. Last
    // marker wins, matching parse_marker_lines.
    let marker = events.iter().rev().find_map(|v| {
        if v.get("type").and_then(serde_json::Value::as_str) != Some("item.completed") {
            return None;
        }
        let item = v.get("item")?;
        if item.get("type").and_then(serde_json::Value::as_str) != Some("agent_message") {
            return None;
        }
        let text = item.get("text").and_then(serde_json::Value::as_str)?;
        parse_marker_lines(text)
    });

    if let Some(terminal) = terminal
        && terminal.get("type").and_then(serde_json::Value::as_str) == Some("turn.failed")
    {
        let reason = terminal
            .get("error")
            .and_then(|e| e.get("message"))
            .and_then(serde_json::Value::as_str)
            .map(str::to_string)
            .unwrap_or_else(|| "codex turn failed".to_string());

        // The failure direction is safe, but keep whatever the agent did
        // self-report (commits/summary/verdict/exit_code) so the gate context
        // isn't silently discarded (999.107 #1 review). `decided_by_layer` is
        // deliberately NOT copied — it is the forgeable provenance field, and
        // Layer 1 owns this verdict.
        let mut result = AgentResult {
            status: AgentStatus::Failed,
            exit_code: None,
            reason: Some(reason),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(1),
        };
        if let Some(m) = marker.as_ref() {
            result.exit_code = m.exit_code;
            result.commits = m.commits;
            result.summary = m.summary.clone();
            result.verdict = m.verdict;
        }
        return Some(result);
    }

    if let Some(result) = marker {
        // Same provenance overwrite as parse_devflow_result and the Claude
        // stream path (T-30-26): this AgentResult was deserialized from the
        // agent's own marker JSON, so a planted `"decided_by_layer":0` would
        // otherwise forge Layer-0 external-verification provenance. Found by
        // reading, while closing the identical hole one function over.
        return Some(normalise_stream_marker_provenance(result));
    }

    // turn.completed (or no terminal event at all) with no marker defers to
    // Layer 2 rather than an unconditional Success.
    None
}

/// Parse a captured stdout as JSONL: one `serde_json::Value` per non-blank,
/// parseable line. Lines that are not valid JSON are dropped, so a stream
/// interleaved with plain-text progress noise still yields its events.
///
/// Shared by [`is_claude_event_stream`] and [`last_top_level_result`], which
/// both need the same parsed vector. Deliberately NOT retrofitted into
/// [`parse_codex_event_result`], which open-codes the identical idiom: that
/// parser is correct and shipping, and rewriting it would put an unrelated
/// adapter's behavior at risk for a cosmetic dedupe.
/// Determine whether parsed JSONL lines are a Claude `--output-format
/// stream-json` event stream, as opposed to a single-document Claude envelope,
/// a Codex `--json` stream, or plain text.
///
/// **Gates on `type: "system"` + `subtype: "init"` and NOTHING ELSE.**
/// 30-RESEARCH.md offered an alternative — also gate on `type: "result"`
/// carrying a `session_id` — and that alternative is WRONG; do not "restore"
/// it. The single-document envelope that ships today is literally
/// `{"type":"result",...,"session_id":"abc"}`, so a `result`-keyed gate would
/// swallow every production capture in use and silently displace
/// [`parse_devflow_result`] in the [`evaluate_layer1`] cascade — a change to
/// the shipped Layer-1 verdict path, disguised as adding stream support
/// (T-30-02). The `init` event is both stronger and earlier: it opens the
/// stream and is present in all three archived captures
/// (`30a-evidence/raw_output_v3.jsonl` lines 5, 32 and 47).
///
/// `single_doc_envelope_not_consumed_by_claude_stream_parser` is the test that
/// fails if this gate is widened.
fn is_claude_event_stream(events: &[serde_json::Value]) -> bool {
    events.iter().any(|v| {
        v.get("type").and_then(serde_json::Value::as_str) == Some("system")
            && v.get("subtype").and_then(serde_json::Value::as_str) == Some("init")
    })
}

/// The shape of one non-empty capture line after a parse attempt.
///
/// `TornJson` vs `Noise` is the load-bearing distinction everywhere below: a
/// line that failed to parse but still opens with `{` could be a torn event —
/// a truncated write, or a read of a capture still being appended to — while a
/// prose line cannot be (every stream event line opens with `{`). Conflating
/// the two produced both prior misclassification defects: requiring ALL lines
/// to parse sent torn streams back to the raw scan (second-pass fail-open),
/// and counting any malformed line as suspicious rejected benign interleaved
/// progress noise (fourth-pass Medium 3).
#[derive(Clone, Copy, PartialEq, Eq)]
enum LineShape {
    /// Parsed as JSON; the value lives at the same index in
    /// [`ParsedCapture::events`]' insertion order.
    Event,
    /// Failed to parse but opens with `{` — potentially a torn event.
    TornJson,
    /// Failed to parse and does not open with `{` — cannot be a torn event.
    Noise,
}

/// A capture parsed ONCE, keeping both the surviving events and the shape of
/// every non-empty line — including the ones that did not parse.
///
/// This is the R1 root-cause fix from the phase-30 adversarial series: the old
/// `claude_stream_events` returned a bare `Vec<Value>`, so "I dropped
/// something" was unrepresentable and every consumer silently assumed the
/// survivors were complete. Four separate defects came from that assumption
/// (torn-init gate fail-open, stale-success verdict resurrection, stale
/// session-id resurrection, torn-user gate reopening). Consumers now see the
/// full line record and must decide explicitly what a torn line means for them.
struct ParsedCapture {
    events: Vec<serde_json::Value>,
    line_shapes: Vec<LineShape>,
}

impl ParsedCapture {
    fn parse(stdout: &str) -> Self {
        let mut events = Vec::new();
        let mut line_shapes = Vec::new();
        for line in stdout.lines() {
            let trimmed = line.trim();
            if trimmed.is_empty() {
                continue;
            }
            match serde_json::from_str::<serde_json::Value>(trimmed) {
                Ok(v) => {
                    events.push(v);
                    line_shapes.push(LineShape::Event);
                }
                Err(_) => {
                    // Apply the SAME edge-corruption policy per line that
                    // strip_corruption_padding applies per capture. Without
                    // this, `read_capture`'s U+FFFD replacement in front of an
                    // otherwise-intact line made it classify as Noise — not
                    // `{`-prefixed — so the torn-tail guard could not see a
                    // corrupt superseding event and an earlier success marker
                    // decided the stage (fifth adversarial pass, High 1).
                    //
                    // Retry the parse on the stripped line first: edge
                    // corruption around an intact event RECOVERS the event and
                    // its true verdict. Stripping edges cannot join tokens —
                    // the fabrication hazard was DROPPING bytes inside content
                    // (fourth pass) — and interior corruption still fails the
                    // parse. A line that strips to empty was pure corruption:
                    // torn, fail closed.
                    let stripped = strip_corruption_padding(trimmed);
                    if stripped != trimmed
                        && let Ok(v) = serde_json::from_str::<serde_json::Value>(stripped)
                    {
                        events.push(v);
                        line_shapes.push(LineShape::Event);
                    } else {
                        line_shapes.push(if stripped.starts_with('{') || stripped.is_empty() {
                            LineShape::TornJson
                        } else {
                            LineShape::Noise
                        });
                    }
                }
            }
        }
        Self {
            events,
            line_shapes,
        }
    }

    fn torn_json_line_present(&self) -> bool {
        self.line_shapes.contains(&LineShape::TornJson)
    }

    /// Whether a torn JSON line sits AFTER the last parsed event matching
    /// `pred` — or anywhere at all, when no event matches.
    ///
    /// This is the question behind constraint 9 item 1: the capture's REAL
    /// final verdict may be among the casualties, so nothing that survives
    /// before the tear is allowed to stand in for it. Prose noise lines are
    /// not counted — they cannot be a torn event (events open with `{`).
    fn torn_json_after_last_matching(&self, pred: impl Fn(&serde_json::Value) -> bool) -> bool {
        let mut last_match_line = None;
        let mut event_idx = 0usize;
        for (line_idx, shape) in self.line_shapes.iter().enumerate() {
            if *shape == LineShape::Event {
                if pred(&self.events[event_idx]) {
                    last_match_line = Some(line_idx);
                }
                event_idx += 1;
            }
        }
        self.line_shapes
            .iter()
            .enumerate()
            .any(|(line_idx, shape)| {
                *shape == LineShape::TornJson && last_match_line.is_none_or(|last| line_idx > last)
            })
    }
}

/// What kind of capture this is — decided ONCE, here, instead of re-derived by
/// per-call-site heuristics.
///
/// This is the R2 root-cause fix from the phase-30 adversarial series. Four
/// generations of ad-hoc shape checks (`starts_with('{')` guards, "any event of
/// type X", all-lines-JSON, line counts) each got one case wrong: a torn `init`
/// un-recognised a stream (fail-open), one stray JSON line hijacked plain text
/// (V-01, fail-closed), a torn gate-bearing `user` event un-recognised a stream
/// again, and an interleaved prose line was treated as tearing. One classifier
/// carries all of those lessons in one place.
#[derive(Clone, Copy, PartialEq, Eq)]
enum CaptureKind {
    /// Not JSONL-shaped in the majority — the raw-scan paths own it.
    PlainText,
    /// Exactly one parsed `{"type":"result",…}` line: the envelope the shipped
    /// `--output-format json` adapter emits (T-30-25). Raw-scan paths own it.
    SingleDocEnvelope,
    /// A Claude `stream-json` capture — possibly torn, possibly noisy.
    ClaudeStream,
    /// A Codex `--json` capture: dotted top-level types (`thread.started`,
    /// `item.completed`, `turn.*`). Raw-scan paths own it, as before.
    CodexStream,
}

/// Classification rules, in order — each carries the defect that forced it:
///
/// 1. **Majority of non-empty lines must be JSON-shaped** (parsed OR torn-`{`),
///    else `PlainText`. Counting only PARSED lines fails: truncating a real
///    stream drops its parsed count below any threshold while every surviving
///    line is still `{`-shaped (the truncation sweep caught exactly that). One
///    stray JSON line in prose stays under the majority (V-01).
/// 2. **Any parsed `system`/`user`/`assistant` event → `ClaudeStream`.** Claude
///    types win over dotted deterministically — the old event loop returned
///    whichever it happened to iterate first. Real Codex captures never carry
///    these types, and on a corrupt mixed capture the scoped path is the
///    fail-closed direction for the gate.
/// 3. **Any parsed dotted type → `CodexStream`.**
/// 4. **A single parsed `result` line → `SingleDocEnvelope`** — today's shipped
///    format, which must keep the raw-scan path (T-30-02 / T-30-25).
/// 5. **Multi-line with a `result` event or a torn JSON line → `ClaudeStream`.**
///    A stream whose gate-bearing `user` event tore, leaving only a later
///    `result`, is still a stream (fourth-pass Low / third-pass Medium shape).
/// 6. Everything else → `PlainText`.
///
/// A LONE torn JSON line is deliberately `PlainText`, not `ClaudeStream`: under
/// today's format that shape is a torn single-document envelope, and raw-scanning
/// it preserves detection of a REAL gate declaration inside (dropping one is the
/// T-30-24 harm — worse than the echo false positive). The residual — a stream
/// that died with only its echoed-prompt line, torn, and nothing else — requires
/// the `init` line to have never flushed while the echo line partially did.
/// Accepted and recorded rather than silently traded away.
fn classify(capture: &ParsedCapture) -> CaptureKind {
    let total = capture.line_shapes.len();
    if total == 0 {
        return CaptureKind::PlainText;
    }
    let noise = capture
        .line_shapes
        .iter()
        .filter(|s| **s == LineShape::Noise)
        .count();
    if (total - noise) * 2 <= total {
        return CaptureKind::PlainText;
    }

    if capture.events.iter().any(|v| {
        matches!(
            v.get("type").and_then(serde_json::Value::as_str),
            Some("system" | "user" | "assistant")
        )
    }) {
        return CaptureKind::ClaudeStream;
    }
    if capture.events.iter().any(|v| {
        v.get("type")
            .and_then(serde_json::Value::as_str)
            .is_some_and(|t| t.contains('.'))
    }) {
        return CaptureKind::CodexStream;
    }

    let result_events = capture
        .events
        .iter()
        .filter(|v| v.get("type").and_then(serde_json::Value::as_str) == Some("result"))
        .count();
    if total == 1 {
        return if result_events == 1 {
            CaptureKind::SingleDocEnvelope
        } else {
            CaptureKind::PlainText
        };
    }
    if result_events > 0 || capture.torn_json_line_present() {
        CaptureKind::ClaudeStream
    } else {
        CaptureKind::PlainText
    }
}

/// Test-only accessor: does [`classify`] call this capture text a Claude
/// `stream-json` capture?
///
/// Exists so `monitor.rs`'s end-to-end tracer test can assert on the REAL
/// classifier rather than re-deriving "looks like a stream" with its own
/// heuristic — which is precisely the per-call-site divergence [`classify`]
/// was introduced to end. `classify`/`CaptureKind`/`ParsedCapture` stay
/// private; only this yes/no question crosses the module boundary, and only
/// under `cfg(test)`.
#[cfg(test)]
pub(crate) fn capture_is_claude_stream(capture: &str) -> bool {
    classify(&ParsedCapture::parse(capture)) == CaptureKind::ClaudeStream
}

/// Whether an event is TOP-LEVEL — authored by the orchestrator session, not
/// forwarded from a subagent. `parent_tool_use_id` JSON-null or absent.
///
/// The ONE provenance predicate, shared by gate scanning and verdict selection
/// (constraint 9 item 2 / code-review M2: the two paths previously held
/// different notions — gate scanning enforced provenance while
/// [`last_top_level_result`] silently did not, despite its name and doc).
///
/// The absent case must stay top-level: `result` events carry no such key at
/// all in any archived capture. Treating absence as positive provenance remains
/// NECESSARY for today's captures and UNPROVEN safe — no archived capture
/// contains a subagent-origin `result`, so if one can omit the key it would be
/// admitted. Recorded, not solved; the type filter is the second, independent
/// guard on the gate path.
fn is_top_level(event: &serde_json::Value) -> bool {
    matches!(
        event.get("parent_tool_use_id"),
        None | Some(serde_json::Value::Null)
    )
}

/// The LAST top-level `type: "result"` event in a Claude stream capture.
///
/// One capture can hold several: a session kept alive across turns emits one
/// terminal `result` per turn (the archived v3 stream carries three, at lines
/// 19, 37 and 54, produced across task-notification wake-ups). The last is the
/// session's final verdict, so an earlier turn must never decide the stage.
///
/// T-30-01: selection runs over TOP-LEVEL objects only — each value here is one
/// whole JSONL line. A `result`-shaped structure the agent writes inside its own
/// message text is inert string content and structurally unreachable from this
/// scan. Never route this through [`json_scan`]/[`json_find_key`], which descend
/// into nested objects; that is the same protection class as D-04/T-28-04's
/// top-level-only `session_id` read.
///
/// Provenance is ENFORCED via [`is_top_level`], not merely documented — the
/// first version of this function selected on `type == "result"` alone, so a
/// subagent-origin `result` event would have decided the stage (code-review
/// M2, constraint 9 item 2).
fn last_top_level_result(events: &[serde_json::Value]) -> Option<&serde_json::Value> {
    events.iter().rev().find(|v| {
        v.get("type").and_then(serde_json::Value::as_str) == Some("result") && is_top_level(v)
    })
}

/// Whether a declared canary `token` came back inside a TOP-LEVEL `result`
/// event of this capture (D-13).
///
/// **Why this takes capture TEXT rather than a project root and phase**, unlike
/// its siblings [`checkpoint_reported_in_capture`] and
/// [`session_id_from_capture`]: the delivery canary runs against its own
/// throwaway capture file, not the phase capture. A canary that read (and
/// therefore implied writing) `stdout_path(project_root, phase)` would clobber
/// the stage's own capture — the one artifact the entire Layer 1 cascade
/// decides on.
///
/// **D-13 trap 1 — this may not be a NEW trust path.** The CLI echoes the
/// operator's prompt back into the same stdout as a `user` event, so the
/// planted token *will* appear in the stream regardless of whether anything was
/// delivered. That echo is exactly what produced the checkpoint false positive
/// 30-05 fixed. Matching is therefore confined to events that are both
/// `type: "result"` and [`is_top_level`] — the same provenance predicate
/// [`last_top_level_result`] enforces, reused rather than reinvented.
///
/// **D-13 trap 2 — a match proves DELIVERY, never WORK.** The agent can see the
/// token in its own prompt and emit it without doing anything (999.67's shape).
/// A hit means "the task-notification path is alive"; it never means the
/// dispatched work happened. Summaries and merges remain the evidence of work
/// (D-16/D-18).
///
/// Scans EVERY top-level `result`, not just the last one, which is the one
/// place this deliberately differs from [`last_top_level_result`]. That
/// function selects the session's final *verdict*, so later turns must
/// supersede earlier ones. The canary asks a different question — "did the
/// token ever come back?" — and a token returned on an earlier
/// task-notification turn is a complete answer to it.
pub fn token_reported_in_capture(capture: &str, token: &str) -> bool {
    ParsedCapture::parse(capture)
        .events
        .iter()
        .filter(|v| {
            v.get("type").and_then(serde_json::Value::as_str) == Some("result") && is_top_level(v)
        })
        .any(|v| {
            v.get("result")
                .and_then(serde_json::Value::as_str)
                .is_some_and(|text| text.contains(token))
        })
}

/// Whether ONE parsed stream event is a top-level `result` carrying a
/// `DEVFLOW_RESULT` marker in its `result` text.
///
/// Exposed for the pipe-owning monitor's close rule (Phase 31, constraint 4),
/// which must decide line-by-line and in real time whether the marker arm is
/// satisfied — it cannot wait for a whole capture and re-parse it.
///
/// This is a COMPOSITION of the two existing predicates, deliberately not a
/// second implementation of either. T-31-01: the CLI echoes the operator's
/// prompt back into the same stdout as a `user` event — that echo is what
/// produced the checkpoint false positive 30-05 fixed — so a marker seen
/// anywhere but inside an event that is BOTH `type: "result"` AND
/// [`is_top_level`] must not close the stream. Reusing [`parse_marker_lines`]
/// keeps the marker grammar (case-insensitive prefix, edge-corruption
/// stripping, JSON body) in one place rather than letting the monitor grow a
/// looser `contains("DEVFLOW_RESULT")` of its own.
pub(crate) fn event_is_top_level_result_marker(event: &serde_json::Value) -> bool {
    event.get("type").and_then(serde_json::Value::as_str) == Some("result")
        && is_top_level(event)
        && event
            .get("result")
            .and_then(serde_json::Value::as_str)
            .and_then(parse_marker_lines)
            .is_some()
}

/// Whether any AGENT-AUTHORED text in a Claude stream capture declares a
/// human-blocking gate. The stream-capture half of
/// [`blocking_human_checkpoint_reported`]; the pure matcher it delegates to,
/// [`text_reports_human_gate`], is unchanged.
///
/// **Why this exists (review constraint 3).** Scanning raw stdout is safe under
/// the single-document envelope, because the only place gate text can appear
/// there is the one `result` field the agent authored. A stream capture breaks
/// that invariant: the operator's prompt is echoed back into the same stdout as
/// a `user` event, so a prompt that merely DOCUMENTS a checkpoint gate
/// rendering becomes textually indistinguishable from a live declaration. The
/// failure is silent — a checkpoint auto-decide fires, or the resume ceiling is
/// consumed, on a stage whose prompt only discussed checkpoints. DevFlow's own
/// planning documents are exactly that kind of prompt content.
///
/// Two independent filters, both required, neither a substitute for the other:
///
/// 1. **Type — keep ONLY `result` events.** `user` events are always either the
///    echoed prompt or a `task_notification` summary re-injected as user-role
///    content; neither is the agent declaring anything. `system` events carry
///    the `init` tool and agent inventory, inert text with no business in a gate
///    scan. `assistant` events are excluded too, and that exclusion is
///    deliberate — do NOT "restore" it for completeness. Turn-FINAL assistant
///    text is duplicated verbatim into the `result` event that follows it
///    (`30a-evidence/raw_output_v3.jsonl` lines 17→19, 36→37, 53→54), so
///    admitting the class buys no detection the `result` events do not already
///    give. What it buys is a new false-positive surface: v3 line 6's top-level
///    assistant narration ("I'll spawn both subagents in the background now.")
///    reaches no `result` event at all, so an agent narrating "next I'll handle
///    the task whose gate the plan declares" would recreate the prompt-echo
///    false positive one layer inward.
/// 2. **Provenance — keep only top-level events.** An event is top-level when
///    `parent_tool_use_id` is JSON null OR the key is absent entirely. The
///    absent case is load-bearing: `result` events carry no such key at all
///    (confirmed across all three archived captures), so a naive presence check
///    would drop exactly the events that matter most. Mistaking
///    subagent-forwarded narration for orchestrator output is the error that
///    invalidated the v1 experiment outright. Kept even though filter 1 already
///    makes it redundant for today's captures — the two guards are meant to
///    fail independently, so a future widening of the type filter cannot
///    silently inherit subagent content.
///
/// **ALL eligible `result` events are scanned, not only the last.** This
/// deliberately diverges from [`last_top_level_result`]'s last-result-wins
/// verdict semantics, and the two conventions must not be "harmonised": a
/// verdict is a single final answer, whereas this asks whether a gate was
/// reported ANYWHERE in the stage's output. A gate declared in turn N followed
/// by task-notification wake-up turns N+1/N+2 — the exact turn shape the v3
/// capture archives — would be silently dropped by last-result-only, losing a
/// human authorization request to the generic gate. That is the
/// opposite-direction harm, and the worse of the two.
///
/// Text is read with a direct [`serde_json::Value::get`] chain. Never route
/// this through [`json_scan`]/[`json_find_key`]: a recursive traversal descends
/// straight back into the nested message content both filters just excluded,
/// silently undoing the fix while the tests on the outer shape still pass
/// (T-30-23).
///
/// Returns `bool` and short-circuits on the first match rather than collecting
/// the eligible text: this runs on every `devflow advance` over a capture that
/// grows for the whole stage, and there is no reason to allocate a copy of it.
fn claude_stream_reports_human_gate(events: &[serde_json::Value]) -> bool {
    events
        .iter()
        .filter(|event| event.get("type").and_then(serde_json::Value::as_str) == Some("result"))
        .filter(|event| is_top_level(event))
        .filter_map(|event| event.get("result").and_then(serde_json::Value::as_str))
        .any(text_reports_human_gate)
}

/// The `rate_limit_info.status` values that mean the CLI DENIED the request.
///
/// Provenance, per entry — required reading before adding one:
///
/// - `rejected` — drawn from the observed vocabulary of this schema: it is the
///   value the CLI writes for `overageStatus` in the only archived
///   `rate_limit_event`
///   (`.planning/phases/30-keep-the-session-alive-past-turn-end/30a-evidence/raw_output_v3.jsonl`
///   line 15), so it is the denial token this schema actually speaks. It has
///   NOT been observed as a `status` value — no archived capture is of a
///   blocked stream, and every capture DevFlow has taken carries
///   `status: "allowed"`.
///
/// Nothing else is listed, deliberately. Speculatively adding tokens is how the
/// false positive this list exists to prevent comes back: an unrecognised
/// status must DEFER (see [`detect_claude_stream_rate_limit`]), never classify.
/// Correct this list the first time a real blocked capture is archived — that
/// is the only evidence that settles the vocabulary.
const CLAUDE_STREAM_RATE_LIMIT_DENIAL_STATUSES: &[&str] = &["rejected"];

/// Detect an explicit quota DENIAL in a Claude `stream-json` capture and return
/// the retry description, mirroring what [`detect_claude_rate_limit`] returns
/// for the single-document envelope.
///
/// **A `rate_limit_event` is not a rate limit.** The CLI emits these routinely
/// as quota telemetry on healthy streams: the only archived one
/// (`raw_output_v3.jsonl` line 15) says `rate_limit_info.status: "allowed"` and
/// sits in a stream that then completed three turns successfully. Classifying
/// on the event's PRESENCE would mark every healthy Claude stream stage
/// `RateLimited`, and `outcome_policy.rs` maps that to `Action::AutoResume` —
/// so every stage would be auto-resumed against a fabricated retry time
/// instead of advancing (T-30-26). Note the second trap in the same object:
/// `overageStatus` is `rejected` one level below `status: "allowed"`, so any
/// nested search for the token also false-positives. Hence every field here is
/// read with a direct [`serde_json::Value::get`] on the top-level event and its
/// `rate_limit_info` child — never [`json_find_key`]/[`json_scan`], which
/// descend into nested (and, elsewhere in the stream, agent-authored) content
/// and would let the agent supply the retry hint that drives the resume cron's
/// scheduling (T-30-12).
///
/// Two independent guards, both required, neither a substitute for the other:
///
/// 1. **Positional** — only events after the SECOND-TO-LAST `result` event are
///    eligible, i.e. the final turn. A session kept alive across turns emits one
///    `result` per turn, and rate-limit chatter from an earlier turn must never
///    outrank the outcome of a turn that finished later. (In the archived
///    capture the rate event is at line 15 and the results at 19/37/54, so it is
///    excluded on position alone.) With fewer than two `result` events the whole
///    stream IS the final turn.
/// 2. **Semantic** — only a `status` in
///    [`CLAUDE_STREAM_RATE_LIMIT_DENIAL_STATUSES`] classifies. A missing
///    `rate_limit_info`, a missing or non-string `status`, or any unrecognised
///    value returns `None`.
///
/// **Deferring is the deliberately safe direction, not an oversight.**
/// Under-classifying means an unknown denial status falls through to the
/// envelope-failure path and is reported `Failed` — a real degradation (the
/// operator loses automatic resume) but a never-silent one that still gates.
/// Over-classifying means a healthy stream is auto-resumed against a retry time
/// the parser invented. The asymmetry is the whole reason this function reads
/// one field instead of matching a shape.
fn detect_claude_stream_rate_limit(events: &[serde_json::Value]) -> Option<String> {
    // Index of the second-to-last `result` event: everything at or before it is
    // previous-turn history. `None` (fewer than two results) means the whole
    // stream is the final turn.
    let boundary = events
        .iter()
        .enumerate()
        .filter(|(_, v)| v.get("type").and_then(serde_json::Value::as_str) == Some("result"))
        .map(|(idx, _)| idx)
        .rev()
        .nth(1);
    let eligible = match boundary {
        Some(idx) => &events[idx + 1..],
        None => events,
    };

    // Last eligible event wins, matching the last-`result`-wins convention.
    let event = eligible
        .iter()
        .rev()
        .find(|v| v.get("type").and_then(serde_json::Value::as_str) == Some("rate_limit_event"))?;

    let info = event.get("rate_limit_info")?;
    let status = info.get("status")?.as_str()?;
    if !CLAUDE_STREAM_RATE_LIMIT_DENIAL_STATUSES.contains(&status) {
        return None;
    }

    // `resetsAt` is epoch seconds, rendered from the JSON number as-is: nothing
    // parses this string. `outcome_policy.rs` routes on the
    // `AgentStatus::RateLimited` variant alone and the `reason` text is
    // operator-facing. Mirrors `detect_claude_rate_limit`'s `retry_after` →
    // `message` → `error` chain; its final `"usage limit"` default has no
    // counterpart here because a matched `status` is by construction one of the
    // non-empty enumerated strings above, so a third rung would be unreachable.
    Some(
        info.get("resetsAt")
            .and_then(json_scalar_to_string)
            .unwrap_or_else(|| status.to_string()),
    )
}

/// The stream-path counterpart of [`detect_claude_envelope_failure`]: treat
/// `is_error: true` on a stream's last `result` event as an authoritative
/// Layer-1 failure.
///
/// The `reason` shape is reproduced deliberately rather than shared — `result`
/// text, else `subtype`, else `agent reported is_error`, with a
/// ` (num_turns: {n})` suffix when present. This phase's scope fence keeps the
/// four shipped single-document parsers unmodified, so factoring the common
/// body out of `detect_claude_envelope_failure` is out of bounds here; the two
/// must be kept in step by hand. `is_error` absent, non-bool, or `false`
/// returns `None`, deferring exactly as the single-document path does.
fn claude_stream_envelope_failure(result_event: &serde_json::Value) -> Option<AgentResult> {
    if !result_event.get("is_error")?.as_bool()? {
        return None;
    }

    let num_turns = result_event
        .get("num_turns")
        .and_then(serde_json::Value::as_u64);
    let base_reason = result_event
        .get("result")
        .and_then(serde_json::Value::as_str)
        .map(str::to_string)
        .or_else(|| {
            result_event
                .get("subtype")
                .and_then(serde_json::Value::as_str)
                .map(str::to_string)
        })
        .unwrap_or_else(|| "agent reported is_error".to_string());
    let reason = match num_turns {
        Some(n) => format!("{base_reason} (num_turns: {n})"),
        None => base_reason,
    };

    Some(AgentResult {
        status: AgentStatus::Failed,
        exit_code: None,
        reason: Some(reason),
        commits: None,
        summary: None,
        verdict: None,
        decided_by_layer: Some(1),
    })
}

/// Parse a Claude `--output-format stream-json` JSONL capture and read the
/// `DEVFLOW_RESULT` marker out of its LAST `result` event.
///
/// The new sibling of [`parse_codex_event_result`], mirroring its shape. Only
/// decisive when the capture is actually a Claude event stream (per
/// [`is_claude_event_stream`]); every other shape returns `None` and falls
/// through to the parser that owns it. Before this existed, a JSONL capture
/// returned `None` from all four single-document parsers —
/// `serde_json::from_str` on the whole multi-line document is a hard "trailing
/// characters" error — so every Claude-driven stage fell through to Layer 2's
/// coarse exit-code+commit heuristic.
///
/// **Precedence, mirroring [`evaluate_layer1`]'s single-document ordering
/// rather than inventing a new one** — do not reshuffle without reading the
/// reasons:
///
/// 1. Format gate ([`is_claude_event_stream`]); every other shape declines here.
/// 2. [`detect_claude_stream_rate_limit`] — a final-turn explicit quota denial
///    wins over EVERYTHING below it, for the same reason `evaluate_layer1`
///    already puts `detect_claude_rate_limit` ahead of the generic failure
///    check: a rate-limited run classified as plain `Failed` kills the primary
///    rate-limit resume cron, the one automated path that exists to recover
///    from it (T-30-13). The precedence is narrow, not broad — the detector
///    only fires on an explicit denial inside the final turn, so it cannot
///    shadow the outcome of a stream that completed.
/// 3. The `DEVFLOW_RESULT` marker in the last `result` event. A non-success
///    marker is decisive and returns immediately; a success marker is HELD, not
///    returned, because step 4 may override it.
/// 4. [`claude_stream_envelope_failure`] — `is_error: true` on that same event
///    overrides a held success marker, matching the single-document rule that
///    the envelope is authoritative for errors and a stale or echoed success
///    marker must not win (T-30-15).
/// 5. The held success marker, else `None`.
///
/// A last `result` event with no marker and no `is_error` returns `None`
/// (defer to Layer 2) rather than an unconditional Success, matching the
/// `turn.completed` convention: a marker-less turn must never silently advance
/// a stage.
///
/// Passing the isolated `result` text to [`parse_marker_lines`] is the correct
/// scoping, not a workaround. The marker is JSON-escaped inside a
/// `"result":"..."` string value, so it can never appear as a line starting
/// with `DEVFLOW_RESULT:` in the raw capture, and that parser's 4000-character
/// tail window is smaller than a single stream `result` line. Once serde
/// decodes the field the escaped newlines become real newlines and the existing
/// tail scan works on it as designed.
fn parse_claude_event_result(stdout: &str) -> Option<AgentResult> {
    let capture = ParsedCapture::parse(stdout);
    if !is_claude_event_stream(&capture.events) {
        return None;
    }

    // Constraint 9 item 1 (code-review H1): a torn JSON line at or after the
    // last surviving top-level result means the session's REAL final verdict
    // may be among the casualties — a capture read while the CLI was still
    // appending, or a truncated write. Nothing that survives before the tear
    // is allowed to stand in for it; in particular an earlier turn's SUCCESS
    // must never advance the stage. Returning a Failed verdict rather than
    // None is deliberate: None would fall through to `parse_devflow_result`'s
    // raw tail scan, which can find the stale marker TEXT inside the surviving
    // JSON lines and resurrect it through the back door. The cost is a false
    // failure when the torn trailing line was a quiet task-notification turn;
    // that reads as loop-back noise, not a silent wrong advance.
    if capture.torn_json_after_last_matching(|v| {
        v.get("type").and_then(serde_json::Value::as_str) == Some("result") && is_top_level(v)
    }) {
        return Some(indeterminate_capture_failure());
    }

    if let Some(retry) = detect_claude_stream_rate_limit(&capture.events) {
        return Some(rate_limited_result(retry));
    }

    let last_result = last_top_level_result(&capture.events)?;

    let marker = last_result
        .get("result")
        .and_then(serde_json::Value::as_str)
        .and_then(parse_marker_lines)
        .map(normalise_stream_marker_provenance);

    let held_success = match marker {
        // A non-success marker is the agent's own final word and nothing below
        // can improve on it.
        //
        // 31-02 audit (non-exhaustive equality site 1 of 3). This `!= Success`
        // is CORRECT AS-IS for `AgentStatus::IdleTimeout` and is deliberately
        // left unchanged. The compiler cannot flag this site — an equality test
        // compiles fine against a new variant — so it is audited by hand here
        // rather than left to the wildcard-free-match mechanism, which does not
        // reach it.
        //
        // The only way `IdleTimeout` arrives here is an agent writing
        // `DEVFLOW_RESULT: {"status":"idle_timeout"}` into its own output,
        // claiming a verdict only DevFlow's monitor is supposed to produce.
        // The predicate handles that in the fail-safe direction: it is not
        // `Success`, so it returns immediately as decisive non-success and
        // `decide_action` gates it for review. A forged idle timeout can
        // therefore only make a run gate, never advance. The REAL
        // monitor-produced verdict does not travel this path at all — it is
        // read from its own side-channel file at the top of `evaluate_layer1`,
        // before this parser ever runs.
        Some(result) if result.status != AgentStatus::Success => return Some(result),
        other => other,
    };

    if let Some(failure) = claude_stream_envelope_failure(last_result) {
        return Some(failure);
    }

    held_success
}

/// The Layer-1 verdict for a stream capture whose TAIL is provably unreadable:
/// a torn JSON line after the last surviving result (constraint 9 item 1).
///
/// Failed, not `None`, and not the pre-tear result. `None` hands the same
/// stdout to `parse_devflow_result`'s raw tail scan, which can resurrect the
/// stale marker text out of the surviving JSON lines; the pre-tear result is
/// exactly the stale-success defect this exists to close. A false failure on a
/// torn-but-benign tail surfaces as a retried stage, never as a silent wrong
/// advance — the asymmetry this whole module is built around.
fn indeterminate_capture_failure() -> AgentResult {
    AgentResult {
        status: AgentStatus::Failed,
        exit_code: None,
        reason: Some(
            "stream capture ends in an unparseable line; the final verdict is indeterminate"
                .to_string(),
        ),
        commits: None,
        summary: None,
        verdict: None,
        decided_by_layer: Some(1),
    }
}

/// T-30-26: overwrite the agent-supplied `decided_by_layer` unconditionally.
///
/// [`parse_marker_lines`] deserializes the agent's own marker JSON straight
/// into [`AgentResult`], and the field is `#[serde(default)]`, so an ordinary
/// `{"status":"success"}` marker leaves it `None` while a hostile
/// `{"status":"success","decided_by_layer":0}` leaves it `Some(0)`. Neither is
/// acceptable: every other Layer-1 constructor in this module sets `Some(1)`
/// explicitly, and `Some(0)` is a Layer-0 external-probe provenance that
/// `classify_validate_outcome` (devflow-cli's `pipeline_outcomes.rs`) reads as
/// `external` when classifying a Validate stage. An agent must not be able to
/// claim a probe verdict it did not earn, so the value is derived here rather
/// than trusted.
fn normalise_stream_marker_provenance(mut result: AgentResult) -> AgentResult {
    result.decided_by_layer = Some(1);
    result
}

/// Scan a bounded tail of `stdout` in reverse line order for the last
/// `DEVFLOW_RESULT` marker.
///
/// `DEVFLOW_RESULT` markers are ASCII. Searching the bounded tail and returning
/// the last valid marker ensures the agent's final status wins over an earlier
/// prompt echo without requiring the surrounding output to be ASCII.
///
/// Three sixth-pass corrections, each with a paired regression:
/// - The tail budget counts WHOLE LINES, never bisecting one (High 2): the old
///   fixed 4000-char window could cut through the final marker line itself
///   when it carried a long `reason`, silently dropping the authoritative
///   failure and handing the verdict to the exit code.
/// - Each line is edge-stripped before prefix matching (High 1): the capture
///   is read lossily, so one stray byte became U+FFFD glued to the prefix or
///   the JSON and the marker vanished. Same policy as every other reader:
///   edges stripped, interior corruption stays visible and untrusted.
/// - The prefix match is genuinely case-insensitive (High 3), as this
///   parser's contract has promised all along — the old strip_prefix chain
///   accepted only ALL-upper or ALL-lower.
fn parse_marker_lines(stdout: &str) -> Option<AgentResult> {
    const TAIL_BUDGET_CHARS: usize = 4000;
    const PREFIX: &str = "DEVFLOW_RESULT:";

    let mut budget_used = 0usize;
    for line in stdout.lines().rev() {
        // The line that crosses the budget is still scanned whole; only the
        // NEXT one stops the walk. The last line is always scanned, however
        // long — that is the line the fixed window used to bisect.
        if budget_used > TAIL_BUDGET_CHARS {
            break;
        }
        budget_used += line.chars().count() + 1;

        let line = strip_corruption_padding(line);
        let Some(head) = line.get(..PREFIX.len()) else {
            continue;
        };
        if !head.eq_ignore_ascii_case(PREFIX) {
            continue;
        }

        let json_str = line[PREFIX.len()..].trim();
        if let Ok(result) = serde_json::from_str::<AgentResult>(json_str) {
            return Some(result);
        }
    }
    None
}

/// One commit the agent made before its stream went silent (D-07, 31-02).
///
/// The subject is carried alongside the sha because a bare sha list is not
/// operator-actionable — D-07's requirement is that the commits be *named*, so
/// that a silent miscount becomes something a human can act on.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IdleTimeoutCommit {
    /// Full commit sha, as `git log --format=%H` emits it.
    pub sha: String,
    /// Commit subject line (`%s`).
    pub subject: String,
}

/// The pipe-owning monitor's authoritative idle-timeout verdict, as written to
/// [`idle_timeout_path`] BEFORE the child is terminated (D-05, 31-02).
///
/// This is a SIDE CHANNEL, deliberately not the stdout capture. See
/// [`parse_idle_timeout_side_channel`] for why that distinction is a
/// correctness requirement rather than a filing preference.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IdleTimeoutRecord {
    /// Always [`AgentStatus::IdleTimeout`]'s wire string. Recorded so the file
    /// is self-describing to a human reading `.devflow/` by hand.
    pub status: String,
    /// The idle window that elapsed with no line on the child's stdout.
    pub idle_secs: u64,
    /// The supervised child's pid, from the in-memory `Child` handle — never
    /// re-read from the on-disk pid file, which is exposed to pid reuse
    /// (T-31-07).
    pub agent_pid: u32,
    /// Unix seconds at which the monitor wrote this record.
    pub written_at: u64,
    /// Every commit on the phase branch when the timeout fired. NONE of these
    /// is rolled back — see [`parse_idle_timeout_side_channel`].
    pub commits: Vec<IdleTimeoutCommit>,
}

/// Read the monitor's own idle-timeout verdict, if it wrote one.
///
/// **This is consulted as the FIRST statement of [`evaluate_layer1`], before
/// `read_capture` and before every marker parser. That placement is
/// load-bearing and must not be "tidied" into the `.or_else` chain below it.**
///
/// The obvious-looking alternative — appending the verdict to the stdout
/// capture — is a real correctness bug, not a style choice.
/// `evaluate_layer1`'s chain reaches `parse_devflow_result`'s tail scan only
/// when `parse_claude_event_result` returns `None`, and that parser resolves to
/// the LAST top-level `result` event regardless of what text follows it. On any
/// stream that already completed one successful turn — the normal shape of a
/// run long enough to idle out at all — an appended verdict is therefore never
/// reached, and a stale success stands as the recorded outcome of a run DevFlow
/// itself killed (T-31-06, 31-RESEARCH Pitfall 3).
///
/// Reading before `read_capture` matters for a second reason: that call is an
/// early `return None` when the capture is missing, so a timeout that fired
/// before the child emitted anything at all would otherwise be discarded
/// entirely.
///
/// `decided_by_layer` stays `1`. This is a Layer-1-CLASS authoritative verdict
/// — it just comes from the monitor that supervised the run rather than from
/// parsing what the agent said about itself. It is emphatically not `0`, which
/// is reserved for operator-authored external probe provenance that
/// `classify_validate_outcome` reads as `external`.
///
/// **The file's PRESENCE is the signal; its contents are enrichment.** A record
/// that exists but cannot be read still returns an `IdleTimeout` verdict,
/// carrying a reason that says the details were lost. Returning `None` there
/// would drop the verdict back into the cascade and let precisely the stale
/// success above win — turning a corrupt file into a silent wrong advance,
/// which is the exact failure this function exists to prevent. The asymmetry is
/// the one this whole module is built around: a false failure surfaces as a
/// gate, never as a wrong advance.
///
/// **Nothing here rolls anything back** (D-07, T-31-09). The commits are read
/// and named, never reverted: an idle timeout may be a false positive, and
/// destroying real work on a false positive is unrecoverable.
/// Whether the phase's live capture already carries an explicit quota DENIAL.
///
/// Exists for exactly one caller: [`crate::monitor`]'s idle-timeout path, which
/// must know *why* the stream went quiet before it records a verdict about the
/// silence.
///
/// **The problem this solves.** A quota denial makes the agent go silent — it
/// has nothing left to say. The monitor's idle timer then fires, writes an
/// idle-timeout record, and kills the child. Because
/// [`parse_idle_timeout_side_channel`] is `evaluate_layer1`'s first statement
/// and returns unconditionally (T-31-06), that record shadows
/// [`detect_claude_stream_rate_limit`] — which was sitting in the same capture
/// with the answer. The run is then reported as an idle timeout, "TERMINAL and
/// not retried automatically", when the truth is `RateLimited`, which
/// `outcome_policy` routes to auto-resume.
///
/// Observed 2026-08-08 on a real Code stage: `rate_limit_event` with
/// `status: "rejected"`, `rateLimitType: "seven_day"`,
/// `overageDisabledReason: "out_of_credits"`. Replaying the classifier over that
/// capture returns the denial; the operator was instead told the stream had been
/// silent for 120s. Running out of quota is the likeliest way a long unattended
/// run stops, so it is the failure this phase can least afford to misreport.
///
/// Deliberately delegates to the SAME detector the read path uses rather than
/// re-implementing the check. Two independent notions of "is this a rate limit"
/// would be free to disagree, and the disagreement would be invisible.
#[must_use]
pub fn capture_shows_rate_limit_denial(project_root: &Path, phase: PhaseId) -> bool {
    let Some(raw) = read_capture(&stdout_path(project_root, phase)) else {
        return false;
    };
    detect_claude_stream_rate_limit(&ParsedCapture::parse(&raw).events).is_some()
}

fn parse_idle_timeout_side_channel(project_root: &Path, phase: PhaseId) -> Option<AgentResult> {
    let path = idle_timeout_path(project_root, phase);
    let raw = read_capture(&path)?;

    let Ok(record) = serde_json::from_str::<IdleTimeoutRecord>(&raw) else {
        return Some(idle_timeout_result(
            format!(
                "idle timeout: DevFlow's monitor recorded a timeout verdict at {} but the \
                 record itself is unreadable, so the commit list and idle duration are lost. \
                 The timeout stands regardless — the file's presence is the authoritative \
                 signal. Inspect the phase branch by hand; nothing was rolled back.",
                path.display()
            ),
            None,
        ));
    };

    let named: Vec<String> = record
        .commits
        .iter()
        .map(|commit| {
            let short: String = commit.sha.chars().take(7).collect();
            format!("{short} {}", commit.subject)
        })
        .collect();

    let commit_phrase = if named.is_empty() {
        "No commits were found on the phase branch.".to_string()
    } else {
        format!(
            "The agent made {} commit(s) before going quiet and NONE of them were rolled \
             back: {}.",
            named.len(),
            named.join("; ")
        )
    };

    Some(idle_timeout_result(
        format!(
            "idle timeout: the agent's output stream was silent for {}s, so DevFlow \
             terminated it (agent pid {}). {commit_phrase} Review the branch before deciding \
             what to keep — this run is TERMINAL and is not retried automatically.",
            record.idle_secs, record.agent_pid
        ),
        Some(record.commits.len() as u32),
    ))
}

/// Build the `IdleTimeout` verdict Layer 1 reports for a monitor-recorded
/// timeout.
///
/// `verdict` stays `None` deliberately: at `Stage::Validate`,
/// `classify_validate_outcome` matches `Some(Verdict::Pass)` FIRST and would
/// classify the stage as passed on the strength of that field alone, whatever
/// the status says. A timeout has no verdict to offer, and inventing one here
/// would advance a run that never reported.
fn idle_timeout_result(reason: String, commits: Option<u32>) -> AgentResult {
    AgentResult {
        status: AgentStatus::IdleTimeout,
        exit_code: None,
        reason: Some(reason),
        commits,
        summary: None,
        verdict: None,
        decided_by_layer: Some(1),
    }
}

/// Layer 1: Try to detect agent result from the native per-adapter envelope
/// or the DEVFLOW_RESULT marker in stdout.
///
/// The monitor's own idle-timeout side channel is consulted FIRST, ahead of
/// everything below including `read_capture` itself — see
/// [`parse_idle_timeout_side_channel`], where that ordering is a correctness
/// requirement rather than a preference.
///
/// Precedence: Claude rate-limit envelope (a SPECIFIC failure that must
/// outrank the generic `is_error` check — rate-limit envelopes carry
/// `is_error: true`, and classifying them `Failed` would kill the primary
/// rate-limit resume cron path) → Claude envelope `is_error: true` (authoritative,
/// overrides a success marker) → Claude `stream-json` JSONL event stream (the
/// last `result` event's marker decides; a marker-less last turn defers) →
/// DEVFLOW_RESULT marker (portable; works for plain text and a Claude
/// envelope's unwrapped `result` text) → Codex JSONL event stream
/// (`turn.failed` decisive; `turn.completed` defers) → Codex plain-text
/// rate-limit heuristic (least authoritative, stays last).
///
/// The Claude stream parser's position is load-bearing in BOTH directions
/// (T-30-03). The two single-document detectors stay ahead of it because they
/// remain authoritative for the `--output-format json` envelope that ships
/// today. It goes ahead of `parse_devflow_result` so that an adapter-specific
/// stream capture is owned whole by the parser that understands its framing,
/// rather than letting the generic 4000-character tail scan take a bite of a
/// mid-line window of JSONL first.
pub fn evaluate_layer1(project_root: &Path, phase: PhaseId) -> Option<AgentResult> {
    // FIRST STATEMENT, before `read_capture` and before every parser below.
    // Do not move this into the `.or_else` chain: `parse_claude_event_result`
    // resolves the LAST top-level `result` event and would shadow it on any
    // stream that already had one successful turn. See
    // `parse_idle_timeout_side_channel`'s doc comment (T-31-06).
    if let Some(timed_out) = parse_idle_timeout_side_channel(project_root, phase) {
        return Some(timed_out);
    }

    let stdout = read_capture(&stdout_path(project_root, phase))?;
    detect_claude_rate_limit(&stdout)
        .map(rate_limited_result)
        .or_else(|| detect_claude_envelope_failure(&stdout))
        .or_else(|| parse_claude_event_result(&stdout))
        .or_else(|| parse_devflow_result(&stdout))
        .or_else(|| parse_codex_event_result(&stdout))
        .or_else(|| detect_codex_rate_limit(&stdout).map(rate_limited_result))
}

/// Build the `RateLimited` result Layer 1 reports for a detected retry hint.
fn rate_limited_result(retry: String) -> AgentResult {
    AgentResult {
        status: AgentStatus::RateLimited,
        exit_code: None,
        reason: Some(format!("rate limited until {retry}")),
        commits: None,
        summary: None,
        verdict: None,
        decided_by_layer: Some(1),
    }
}

/// Commits on the phase's feature branch that are not on `develop`.
///
/// Derives the branch name from `git_flow.feature_prefix` and the zero-padded
/// `phase`, verifies the branch exists with `rev-parse --verify`, and on
/// success counts `{git_flow.develop}..{branch}` with `rev-list --count`.
/// This is the single implementation of that count — [`evaluate_layer2`],
/// [`evaluate_layer3`] and `pipeline_outcomes::handle_validate_outcome`'s
/// forward-progress check all call it rather than each re-deriving the branch
/// name and re-running the same two git commands, which is what made the
/// counts able to silently diverge before this extraction. That claim was
/// aspirational until 35-01: [`evaluate_layer3`] carried its own inline
/// `rev-list --count` with an independent copy of the lossy zero collapse, and
/// deleting it is what makes "single implementation" true.
///
/// Must be called with the main `project_root`, never a worktree path — git
/// worktrees share refs and the object database, so a commit made inside a
/// linked worktree is immediately visible to a count run from the main
/// checkout, which is the property every caller already relies on.
///
/// The return distinguishes a MEASUREMENT from a measurement FAILURE, which
/// is the whole point of the `Option` (999.77 / D-08, A-06):
///
/// - `Some(n)` — git ran and reported a real number. This includes
///   `Some(0)` for a branch that genuinely does not exist yet, which is
///   normal on a phase's first Validate and is a real observation, not a
///   failure to observe.
/// - `None` — the count could not be established: either the `git` child
///   could not be executed at all (`.output()` returned `Err`), or it ran but
///   produced stdout that does not parse as a `u32`. A-06 splits only the
///   ran/did-not-run axis; the unparseable case is mapped to `None` here
///   because the child produced no usable count, and reporting a forged zero
///   for it would recreate exactly the hazard this signature removes.
///
/// **The two consumers now handle `None` distinctly, and neither collapses it
/// to zero.** `pipeline_outcomes::handle_validate_outcome` treats an
/// unmeasurable cycle as not-progress and leaves its persisted baseline
/// untouched, so the next real measurement still compares against the last
/// real observation. [`evaluate_layer2`] returns `Ok(None)` and falls through
/// to [`evaluate_layer3`], which classifies an unmeasurable count as
/// [`AgentStatus::Unknown`] rather than asserting the negative that no work
/// was done.
///
/// # Changed in v2.5.0 — breaking
///
/// The return type was `u32` before this release; it is now `Option<u32>`
/// (999.77 / 999.87). A call site updating from the old form must decide which
/// of the two states it means, because the old type conflated them:
///
/// - `Some(0)` — git RAN and the branch genuinely has no commits. This is the
///   old `0` in its legitimate sense, and is normal on a phase's first Validate.
/// - `None` — no count was established at all. This is the case the old
///   signature could not express, and `.unwrap_or(0)` is precisely the wrong
///   way to restore it: collapsing it back to zero is the defect this change
///   exists to remove. A transient `git` failure then reads as "no work done",
///   which forged a `consecutive_failures` baseline reset (999.77) and made the
///   result cascade classify a successful agent as `Failed` (999.87).
///
/// The enumeration of this and every other public-surface change in the release
/// is in `CHANGELOG.md` under 2.5.0.
pub fn phase_commit_count(
    project_root: &Path,
    git_flow: &GitFlowConfig,
    phase: PhaseId,
) -> Option<u32> {
    let branch = format!("{}phase-{}", git_flow.feature_prefix, phase.padded());

    // A-06: split on whether the command RAN, not on what it answered. An
    // `Err` means the child could not be executed — a measurement failure. An
    // `Ok` with an unsuccessful status means git ran and reported the branch
    // absent, which is a real observation of zero commits.
    match git_command(project_root)
        .args(["rev-parse", "--verify", &branch])
        .output()
    {
        Err(_) => return None,
        Ok(output) if !output.status.success() => return Some(0),
        Ok(_) => {}
    }

    let range = format!("{}..{branch}", git_flow.develop);
    // A-06 again, applied to the second step (CR-01, 35-REVIEW). This arm used
    // to be `.output().ok()?` followed by `.parse().ok()`, which split on
    // whether the output PARSED rather than on whether the command RAN — the
    // opposite of the rule the `rev-parse` step above states and follows. A
    // `rev-list` that runs and exits non-zero writes an empty stdout, so any
    // condition making the range invalid (the configured `develop` absent from
    // the checkout, a shallow clone) parsed to nothing and returned `None`
    // *permanently*, not transiently. That is a measurement the command DID
    // make; it belongs with the branch-absent case above as a real zero.
    let output = match git_command(project_root)
        .args(["rev-list", "--count", &range])
        .output()
    {
        Err(_) => return None,
        Ok(output) => output,
    };
    if !output.status.success() {
        return Some(0);
    }
    // A success whose stdout does not parse is a different animal: git ran,
    // succeeded, and said something this function cannot read. Nothing was
    // established, so it stays `None` rather than being asserted as zero.
    String::from_utf8_lossy(&output.stdout).trim().parse().ok()
}

/// Layer 2: Use exit code + commit count to determine result.
///
/// Reads exit code from `.devflow/phase-NN-exit` file.
/// Counts commits in `feature/phase-NN` branch (if it exists), via
/// [`phase_commit_count`].
///
/// The commit-count gate ("no commits → failed") is scoped to `stage` — it
/// only applies to `Stage::Plan`/`Stage::Code` (checked via an explicit
/// `matches!`, NOT `Stage::is_agent_stage()`, since that also includes
/// `Define`, which legitimately produces zero commits). `exit≠0` is ALWAYS
/// `Failed`, for every stage — only the `exit=0`/zero-commits branch is
/// stage-scoped.
///
/// Decision matrix:
///   exit=137                                             → ResourceKilled (ALL stages, D-07)
///   exit=127                                             → AgentUnavailable (ALL stages, D-07)
///   exit≠0 (excluding 137/127)                           → Failed (ALL stages)
///   exit=0, stage in {Plan, Code}, commits=0             → Failed ("no work done")
///   exit=0, stage in {Plan, Code}, commits>0             → Success
///   exit=0, stage NOT in {Plan, Code} (Define/Validate/Ship), commits=0 → Success
///           (not commit-gated; Validate's real pass signal is its verdict,
///           not a bare zero-commit — see Task 2's turn.completed deferral)
///   exit unknown                                         → fall to Layer 3 (return None)
///   exit=0, stage in {Plan, Code}, commits UNMEASURABLE  → fall to Layer 3 (return None)
///           (CR-01: the ONLY row an unmeasurable count changes. Every other
///           row above is decided by the exit code alone and keeps its verdict
///           with the count rendered as "unknown" in the reason string.)
///
/// WR-06 (13-REVIEW.md): takes only the explicit `project_root` parameter
/// for both the `.devflow/` file paths and the git subprocess `current_dir`
/// — previously it also accepted `state: &State` and used `state.project_root`
/// for the git calls, which every caller happened to pass consistently with
/// `project_root` but which the function itself had no way to enforce.
pub fn evaluate_layer2(
    project_root: &Path,
    phase: PhaseId,
    git_flow: &GitFlowConfig,
    stage: Stage,
) -> Result<Option<AgentResult>, ResultError> {
    let exit_path = devflow_dir(project_root).join(format!("phase-{}-exit", phase.padded()));
    let exit_code: i32 = match std::fs::read_to_string(&exit_path) {
        Ok(s) => s.trim().parse().unwrap_or(-1),
        Err(_) => return Ok(None), // fall to Layer 3
    };

    let branch = format!("{}phase-{}", git_flow.feature_prefix, phase.padded());
    let commits = phase_commit_count(project_root, git_flow, phase);
    let commit_gated = matches!(stage, Stage::Plan | Stage::Code);

    // D-09 (999.87): an unmeasurable commit count is NOT evidence that no work
    // was done, and the commit gate below would classify it as
    // `Failed — no work done` if it were collapsed to zero.
    //
    // CR-01 (35-REVIEW): the guard belongs HERE, not above the exit-code
    // classification. `commits` is load-bearing for exactly one term —
    // `no_work_done`, which only exists when `commit_gated` holds. Returning
    // early on any `None` also discarded the 137 / 127 / `exit != 0` verdicts
    // and the non-commit-gated `Success`, none of which read the count at all.
    // That mattered because Layer 2 is the SOLE classifier for 137 and 127
    // (Layer 1 sees no marker from a SIGKILLed or never-launched agent, and
    // Layer 3 has no ResourceKilled/AgentUnavailable arm), and the same host
    // fault that OOM-kills an agent also makes the `fork` for `git` fail — so
    // the two observations arrive together, and an infra fault was routed into
    // the Validate loop it is explicitly forbidden from entering
    // (`pipeline_launch.rs`, review consensus #4 / D-08).
    //
    // Fall through ONLY when the missing count is what would have decided.
    if commit_gated && exit_code == 0 && commits.is_none() {
        return Ok(None); // fall to Layer 3
    }

    let no_work_done = commit_gated && commits == Some(0);
    // Reason strings must not invent a number they do not have. Every
    // surviving arm below interpolates the count for context only.
    let commits_desc = match commits {
        Some(n) => format!("{n} commits"),
        None => "an unmeasurable number of commits".to_string(),
    };

    // 137 (SIGKILL, typically OOM) and 127 (command not found) are classified
    // BEFORE the generic `exit_code != 0 -> Failed` catch-all, using the same
    // trusted plain-i32 already parsed above from the monitor-written exit
    // file (D-07, 17b — no ExitStatusExt/signal API per Pitfall 1a).
    let status = if exit_code == 137 {
        AgentStatus::ResourceKilled
    } else if exit_code == 127 {
        AgentStatus::AgentUnavailable
    } else if exit_code != 0 || no_work_done {
        AgentStatus::Failed
    } else {
        AgentStatus::Success
    };

    Ok(Some(AgentResult {
        status,
        exit_code: Some(exit_code),
        reason: if exit_code == 137 {
            Some(format!(
                "agent process was killed (exit code 137, likely OOM) ({commits_desc} on {branch})"
            ))
        } else if exit_code == 127 {
            Some(format!(
                "agent command was unavailable (exit code 127, command not found) \
                 ({commits_desc} on {branch})"
            ))
        } else if exit_code != 0 {
            Some(format!(
                "agent exited with code {exit_code} ({commits_desc} on {branch})"
            ))
        } else if no_work_done {
            Some(format!(
                "no commits found on {branch} (agent exit code was {exit_code})"
            ))
        } else {
            Some(format!(
                "{commits_desc} on {branch} (agent exit code was {exit_code})"
            ))
        },
        commits,
        summary: None,
        verdict: None,
        decided_by_layer: Some(2),
    }))
}

/// Layer 3: Last resort — agent process is gone.
///
/// Split per D-02/D-03 case 3 (17-03): "process gone, commits exist" stays
/// `Unknown` — unverified but there is SOMETHING to account for, and Plan
/// 04's never-advance dispatch gates it downstream (D-04) rather than
/// reclassifying it here. "Process gone, zero commits, nothing declared" is
/// no longer a blanket advanceable `Unknown` — it is reclassified to
/// `Failed` so a vanished agent that produced and declared nothing cannot
/// masquerade as ambiguous-but-fine; the reason flags that human review is
/// needed. This only fires when neither Layer 1 nor Layer 2 produced a
/// definitive result.
///
/// **The split is three-way, not two-way (35-01/F-4).** The two cases above
/// both assume the commit count was actually established. A third case —
/// the count could not be MEASURED at all — is classified `Unknown` with
/// `commits` left absent and a reason naming the measurement failure. It is
/// not `Failed`: that asserts a negative the evidence does not support, and
/// on a transient `git` fault it is the exact misclassification this layer
/// used to produce. An unmeasurable count is strictly less certain than the
/// `commits > 0` case already called `Unknown`, so `Unknown` is the
/// consistent answer.
///
/// The count now comes from [`phase_commit_count`] rather than a second
/// inline derivation. This layer previously ran its own `rev-list --count`
/// that fell soft to a zero default, an independent copy of the same lossy
/// collapse — so fixing only [`evaluate_layer2`] relocated the
/// misclassification here instead of removing it. The two measurable arms'
/// behaviour and reason strings are unchanged.
pub fn evaluate_layer3(
    project_root: &Path,
    phase: PhaseId,
    git_flow: &GitFlowConfig,
) -> Result<AgentResult, ResultError> {
    let branch = format!("{}phase-{}", git_flow.feature_prefix, phase.padded());
    // F-4 (35-01): this layer used to run its OWN inline `rev-list --count`
    // that fell soft to a zero default, an independent copy of the same lossy
    // collapse `phase_commit_count` carried. Because every path that reaches
    // Layer 2 also reaches Layer 3, fixing only Layer 2 relocated the
    // misclassification here instead of removing it. Routed through the shared
    // counter so the cascade's last layer measures the same way every other
    // consumer does.
    let commits = phase_commit_count(project_root, git_flow, phase);

    let (status, reason) = match commits {
        Some(n) if n > 0 => (
            AgentStatus::Unknown,
            format!(
                "unverified — agent process is gone but {} commits exist on {}",
                n, branch
            ),
        ),
        Some(_) => (
            AgentStatus::Failed,
            "no work accounted for — agent process is gone with no commits and no declared \
             external post-condition; human review needed"
                .to_string(),
        ),
        // F-4: an unmeasurable count is not evidence of absent work here
        // either. `Failed` asserts a negative the evidence does not support,
        // and it is the classification this phase exists to stop producing on
        // a transient fault. Layer 3 already reserves `Unknown` for "there is
        // something here I cannot verify"; a count that could not be taken at
        // all is strictly less certain than that, so `Unknown` is the
        // consistent answer. `commits` is left absent rather than forged to
        // zero — "no work" and "could not tell" are different facts.
        None => (
            AgentStatus::Unknown,
            format!(
                "unverified — agent process is gone and the work could not be accounted for: \
                 the commit count on {} could not be measured; human review needed",
                branch
            ),
        ),
    };

    Ok(AgentResult {
        status,
        exit_code: None,
        reason: Some(reason),
        commits,
        summary: None,
        verdict: None,
        decided_by_layer: Some(3),
    })
}

/// Layer 0: run explicitly operator-approved external post-condition probes.
///
/// A failed probe outranks every agent-controlled signal. An approved,
/// all-passing set of declared probes is itself affirmative completion
/// evidence — `Success` — so a legitimately external-only stage with zero
/// commits can still complete cleanly (D-05 gap 2). Evaluated for EVERY
/// stage, not only Code (D-05 gap 1 / D-06). With no declarations (or when
/// disabled), behavior is byte-for-byte the pre-Phase-16 cascade.
///
/// Both DISCOVERY and probe EXECUTION read `execution_root` — the worktree
/// when one is set, `project_root` otherwise (999.76, ROADMAP criterion 6).
///
/// This knowingly OVERTURNS a recorded prior peer-review decision
/// (review Plan 03 MEDIUM, OpenCode). That decision held the two roots must
/// stay distinct, discovery reading `project_root` because
/// `.planning/phases/` "lives there, not in a worktree checkout". **The
/// premise has the direction backwards.** `.planning/` is TRACKED content,
/// so an in-flight phase's `{N}-PLAN.md` is committed on `feature/phase-{N}`
/// and therefore exists INSIDE the worktree while absent from the main checkout for
/// the phase's whole duration. Discovering from `project_root` meant a
/// correctly-declared probe set silently never ran in worktree mode —
/// DevFlow's default operating shape — with no error and no log, and the
/// "PLAN removed" veto below fired in its place. Recorded as an overturn
/// rather than patched quietly, so a later reader can see the direction was
/// reconsidered on evidence rather than overlooked.
///
/// Three sibling reads deliberately KEEP `project_root` and must not be
/// "corrected" to match: [`phase_commit_count`] (git worktrees share refs and
/// the object database, so counting from the main checkout is right), and
/// [`checkpoint_reported_in_capture`] and [`evaluate_layer1`] (both read the
/// stdout capture under `.devflow/`, which lives in the project root).
fn evaluate_layer0(
    project_root: &Path,
    state: &State,
    approved_commands: Option<&[String]>,
) -> Option<AgentResult> {
    if !crate::config::external_verify_enabled(project_root) {
        return None;
    }

    let execution_root = state.worktree_path.as_deref().unwrap_or(project_root);
    let commands = crate::verify::external_verify_commands(execution_root, state.phase);
    if commands.is_empty() {
        return approved_commands.map(|_| AgentResult {
            status: AgentStatus::Failed,
            exit_code: None,
            reason: Some(
                "external verification approval mismatch; PLAN declaration was removed".into(),
            ),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(0),
        });
    }
    let Some(approved_commands) = approved_commands else {
        return Some(AgentResult {
            status: AgentStatus::Failed,
            exit_code: None,
            reason: Some(format!(
                "external verification is not approved; set {} to the reviewed JSON command array",
                crate::verify::TRUST_EXTERNAL_VERIFY_ENV
            )),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(0),
        });
    };
    if commands != approved_commands {
        return Some(AgentResult {
            status: AgentStatus::Failed,
            exit_code: None,
            reason: Some("external verification approval mismatch; PLAN commands changed".into()),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(0),
        });
    }
    match commands
        .into_iter()
        .find(|command| !crate::verify::run_external_verification(command, execution_root))
    {
        Some(command) => Some(AgentResult {
            status: AgentStatus::Failed,
            exit_code: None,
            reason: Some(format!("external verification failed: {command}")),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(0),
        }),
        // Every declared, approved probe passed — affirmative completion
        // evidence on its own (D-05 gap 2), even with zero commits.
        None => Some(AgentResult {
            status: AgentStatus::Success,
            exit_code: None,
            reason: Some(
                "external verification passed — all declared, approved probes succeeded".into(),
            ),
            commits: None,
            summary: None,
            verdict: None,
            decided_by_layer: Some(0),
        }),
    }
}

/// Reconciles Layer 0's affirmative-success result with Layer 1's
/// self-reported verdict at `Stage::Validate` (18e).
///
/// Layer 0's affirmative-success arm above short-circuits the cascade before
/// Layer 1 ever runs (`evaluate_agent_result_inner` returns immediately on
/// any `Some(..)` from Layer 0), but Layer 1 is the ONLY carrier of a
/// `verdict` — `status` reports whether the stage's task ran; `verdict`
/// reports whether validation itself passed (see `AgentResult::verdict`'s
/// doc comment). At `Stage::Validate` that meant an agent's explicit
/// `verdict: pass` was silently discarded and `advance()` computed a failure
/// from it — a regression introduced by this project's own 17-03, fixed
/// here.
///
/// `decided_by_layer` deliberately stays `Some(0)` — Layer 0 still DECIDED
/// the `status`; Layer 1 only supplies the `verdict`. The CLI relies on that
/// value to tell an `external_verify` Validate apart from an ordinary one
/// (`classify_validate_outcome`, 18e).
///
/// Scoped to `Stage::Validate` only (flagged assumption in 18-05-PLAN.md): at
/// every other stage an affirmative Layer 0 success keeps `verdict: None`,
/// unchanged from current behavior. A Layer 0 FAILURE is never passed here —
/// only its affirmative-success arm is, so a failed probe still outranks
/// every agent-controlled signal.
///
/// 31-02 audit (non-exhaustive equality site 2 of 3). The `!= Success` guard
/// below is CORRECT AS-IS for `AgentStatus::IdleTimeout` and is left unchanged.
/// The compiler cannot flag an equality test against a new variant, so this is
/// audited by hand. An idle-timeout result is rejected here by BOTH independent
/// guards, not just one: its status is not `Success`, and its
/// `decided_by_layer` is `Some(1)` (the monitor's side-channel verdict is a
/// Layer-1-class fact), never `Some(0)`. It returns unchanged, which is right —
/// this function exists only to graft Layer 1's `verdict` onto an affirmative
/// Layer 0 probe success, and a timeout is neither.
///
/// # This function is 999.74's real defect site (D-15, ROADMAP criterion 4)
///
/// Until 34-01 the graft read Layer 1's `verdict` and nothing else. A marker of
/// `{"status":"failed","verdict":"pass"}` therefore produced `(Success,
/// Some(Pass), Some(0))`: an agent's self-reported FAILURE laundered into an
/// affirmative pair, which `outcome_policy::decide_action` advances and
/// `classify_validate_outcome` reads as `Passed` — Ship, in `Mode::Auto`, on a
/// run whose agent said it had failed. The status was never inspected, so
/// nothing downstream could see the contradiction; by the time the classifier
/// ran, the status genuinely WAS `Success`.
///
/// The fix consults Layer 1's own `AgentStatus` before transplanting its
/// verdict, because **a verdict attached to a self-reported failure is not a
/// pass**. Only `AgentStatus::Success` from Layer 1 may contribute a verdict;
/// everything else leaves `verdict: None` and the stage classifies `Ambiguous`,
/// which gates.
///
/// The classifier fix (plan 34-03, ROADMAP criterion 3) does **not** close this
/// and never could: gating `classify_validate_outcome`'s `Passed` arm on the
/// derived status passes cleanly here, because the derived status is `Success`.
/// Criterion 3 and criterion 4 are separate deliverables. Regression-pinned by
/// `layer0_verdict_graft_declines_when_layer1_status_is_not_success`, with
/// `layer0_verdict_graft_still_transplants_a_passing_layer1_verdict` as its
/// mandatory opposite-result control.
///
/// `evaluate_layer1` is called on `project_root`, NOT on the execution root,
/// and that asymmetry is deliberate rather than an oversight: Layer 1 reads the
/// stdout capture under `.devflow/`, which lives in the project root, while
/// Layer 0 above DISCOVERS declarations in `.planning/phases/` (project root)
/// and RUNS probes in the worktree. Plan 34-04 moves Layer 0's *discovery* to
/// the execution root; this call stays on `project_root` and is still correct
/// afterwards. Recorded here so a later reader does not "fix" the asymmetry.
fn reconcile_layer0_verdict(
    project_root: &Path,
    state: &State,
    result: AgentResult,
) -> AgentResult {
    if state.stage != Stage::Validate
        || result.status != AgentStatus::Success
        || result.decided_by_layer != Some(0)
    {
        return result;
    }
    let verdict = evaluate_layer1(project_root, state.phase)
        .filter(|layer1| layer1.status == AgentStatus::Success)
        .and_then(|layer1| layer1.verdict);
    AgentResult { verdict, ..result }
}

/// Refuse to let a stream-derived `Success` outrank a contradicting exit code
/// (constraint 9's residual, T-31-15, 31-04).
///
/// # Why this cannot be a parser assertion
///
/// Constraint 9's items 1 and 2 — a torn line at or after the last surviving
/// top-level `result`, and provenance on verdict selection — were closed at the
/// root by the `a557805` refactor that made lossiness and capture kind
/// first-class ([`ParsedCapture`], [`classify`]). What survives is precisely
/// the case no parser can detect: **a capture cut at an exact line boundary is
/// byte-identical to a healthy shorter run.** There is nothing in the bytes to
/// assert on. The writer that died between flushing turn N and turn N+1 also
/// died non-zero, so the exit code is the only remaining signal — and it lives
/// one layer up, in the wiring, which is where this defence had to go.
///
/// # Why the fix is narrow rather than a cascade reordering
///
/// [`evaluate_agent_result_inner`] consults Layer 2 only when Layer 1 abstains,
/// which is why a Layer 1 `Success` wins over a contradicting exit code today.
/// That ordering is correct in the ordinary case: Layer 1 is authoritative
/// precisely so it does not need Layer 2's slower `git rev-list` fallback.
/// Making Layer 2 run first would trade a rare wrong answer for a slow one on
/// every stage. So this arbitrates one verdict rather than reordering anything.
///
/// # Scope
///
/// Fires ONLY on `AgentStatus::Success`. `RateLimited`, `IdleTimeout`,
/// `ResourceKilled`, `AgentUnavailable`, `Failed` and `Unknown` all return
/// untouched, each with a named test. Two of those exclusions are load-bearing
/// rather than tidy: a `RateLimited` downgraded to `Failed` would route the run
/// to a human gate instead of the auto-resume cron it needs, and an
/// `IdleTimeout` downgraded to `Failed` would erase the distinction plan 31-02
/// exists to create — 999.64 reborn inside its own fix.
///
/// 31-02 audit convention (non-exhaustive equality site): the `!= Success`
/// guard below is correct as-is for every current and future variant. Anything
/// that is not an affirmative claimed success has nothing to arbitrate, so
/// passing it through unchanged is the right default for a variant added later.
///
/// # `verdict: None` is load-bearing — do not carry it over for symmetry
///
/// `classify_validate_outcome` (`devflow-cli/src/pipeline_outcomes.rs`) matches
/// `(_, Some(Verdict::Pass)) => ValidateOutcome::Passed` FIRST, with `_`
/// discarding the status entirely. A downgraded result has no verdict to offer
/// and must not invent one. [`idle_timeout_result`] dodges the same trap the
/// same way, and says so. That instruction is unchanged and still binding.
///
/// **Correction (34-01, D-15).** An earlier version of this note went further
/// and claimed a kept `verdict: Pass` on a `status: Failed` "would still
/// classify Validate as **Passed**", making this function a no-op at Validate.
/// That overstated the reachability. `outcome_policy::decide_action` intercepts
/// every non-`Success` status and routes it to a gate BEFORE
/// `classify_validate_outcome` is ever reached, so THIS path is protected and
/// this function is not a no-op. The `verdict: None` above is defence in depth,
/// which is why it stays.
///
/// The route into the inversion that IS reachable is
/// [`reconcile_layer0_verdict`]'s graft — it produced `status: Success` with a
/// self-reported failure's verdict attached, so `decide_action` had nothing to
/// intercept. See that function's own doc comment for the full record. It is
/// closed in plan 34-01; the classifier's own structural fix (gating the
/// `Passed` arm on the derived status) lands in plan 34-03.
///
/// **999.74 / DEN-95** is therefore being CLOSED in Phase 34 rather than
/// deliberately deferred. The caution that motivated the earlier deferral still
/// applies to the classifier half and is discharged there, not here: changing
/// that match arm re-routes `Failed`, `Unknown` and `ResourceKilled`, so 34-03
/// audits all of them explicitly.
///
/// # Exit-code fidelity
///
/// 137 → `ResourceKilled` and 127 → `AgentUnavailable` are preserved rather
/// than collapsed into `Failed`, mirroring [`evaluate_layer2`] exactly:
/// `outcome_policy::decide_action` routes those two to `GateInfra` rather than
/// `GateReview`, and the same exit code must not reach two different operator
/// gates depending on whether a stale Layer 1 success happened to be present.
///
/// Note the `ResourceKilled` arm is currently **unreachable via the
/// `MonitorLaunch::PipeOwning` path**: `run_pipe_owning_monitor` records
/// `status.code().unwrap_or(-1)`, so a SIGKILLed child writes `-1`, not `137`.
/// Recorded rather than silently relabelling a real OOM as `Failed` — the arm
/// is still reachable from the `Legacy` arm's `sh` monitor, whose `$?` does
/// carry `128 + signal`.
///
/// Unreadable or unparseable exit-file content is tolerated exactly as
/// [`evaluate_layer2`] tolerates it — a missing file returns the result
/// unchanged (an absent file is not evidence of failure), and garbage parses to
/// `-1`. Neither is invented behaviour; both match the sibling reader.
fn reconcile_stream_success_against_exit_code(
    project_root: &Path,
    phase: PhaseId,
    result: AgentResult,
) -> AgentResult {
    if result.status != AgentStatus::Success {
        return result;
    }

    let Ok(raw) = std::fs::read_to_string(exit_code_path(project_root, phase)) else {
        return result;
    };
    let exit_code: i32 = raw.trim().parse().unwrap_or(-1);
    if exit_code == 0 {
        return result;
    }

    let (status, lead) = if exit_code == 137 {
        (
            AgentStatus::ResourceKilled,
            format!(
                "the agent's output stream reported SUCCESS but the process was killed \
                 (exit code {exit_code}, likely OOM)"
            ),
        )
    } else if exit_code == 127 {
        (
            AgentStatus::AgentUnavailable,
            format!(
                "the agent's output stream reported SUCCESS but the agent command was \
                 unavailable (exit code {exit_code}, command not found)"
            ),
        )
    } else {
        (
            AgentStatus::Failed,
            format!(
                "the agent's output stream reported SUCCESS but the agent exited with \
                 code {exit_code}"
            ),
        )
    };

    AgentResult {
        status,
        exit_code: Some(exit_code),
        reason: Some(format!(
            "{lead}. A capture cut at an exact line boundary is byte-identical to a healthy \
             shorter run, so no parser assertion can tell the two apart — the exit code is the \
             only remaining signal, and it contradicts the claim. Review the phase branch before \
             deciding what to keep; nothing was rolled back."
        )),
        verdict: None,
        ..result
    }
}

/// Full four-layer evaluation: returns the best available AgentResult.
pub fn evaluate_agent_result(
    project_root: &Path,
    state: &State,
    git_flow: &GitFlowConfig,
) -> Result<AgentResult, ResultError> {
    let approval = crate::verify::external_verification_approval();
    evaluate_agent_result_inner(project_root, state, git_flow, approval.as_deref())
}

fn evaluate_agent_result_inner(
    project_root: &Path,
    state: &State,
    git_flow: &GitFlowConfig,
    approved_commands: Option<&[String]>,
) -> Result<AgentResult, ResultError> {
    // Layer 0: operator-authored external post-condition (authoritative failure)
    if let Some(result) = evaluate_layer0(project_root, state, approved_commands) {
        return Ok(reconcile_layer0_verdict(project_root, state, result));
    }

    // Layer 1: DEVFLOW_RESULT marker (authoritative)
    //
    // Authoritative, but not unconditionally: a CLAIMED success is arbitrated
    // against the recorded exit code before it is returned (31-04, T-31-15).
    // The cascade below is deliberately NOT reordered — see
    // `reconcile_stream_success_against_exit_code` for why Layer 2 running
    // first would be the wrong trade.
    if let Some(result) = evaluate_layer1(project_root, state.phase) {
        return Ok(reconcile_stream_success_against_exit_code(
            project_root,
            state.phase,
            result,
        ));
    }

    // Layer 2: Exit code + commit gate
    if let Some(result) = evaluate_layer2(project_root, state.phase, git_flow, state.stage)? {
        return Ok(result);
    }

    // Layer 3: Process existence + commits
    evaluate_layer3(project_root, state.phase, git_flow)
}

/// Path to the .devflow directory for a project root.
fn devflow_dir(project_root: &Path) -> PathBuf {
    project_root.join(".devflow")
}

/// Path to the stdout file for a given phase.
pub fn stdout_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-stdout", phase.padded()))
}

/// Path where the agent's stderr is captured for a given phase.
/// Lives alongside `stdout_path` under `.devflow/`.
pub fn stderr_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!(
        "phase-{padded}-stderr.log",
        padded = phase.padded()
    ))
}

/// Path to the exit code file for a given phase.
pub fn exit_code_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-exit", phase.padded()))
}

/// Path to the file where the monitor records the launched agent's PID.
pub fn agent_pid_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-agent-pid", phase.padded()))
}

/// Path to the file holding the stage prompt handed to the pipe-owning
/// monitor (Phase 31).
///
/// The prompt travels `spawn_monitor` → detached monitor process as a FILE,
/// never as argv: DevFlow stage prompts are large and argv has a hard length
/// ceiling, so a prompt passed positionally would fail on exactly the
/// context-heavy stages that matter most.
pub fn prompt_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-prompt", phase.padded()))
}

/// Path to the pipe-owning monitor's own log for a phase (Phase 31).
///
/// The monitor is a detached process whose stdio is not the operator's
/// terminal — anything it prints to its own stdout goes nowhere. Every "log
/// loudly" obligation in this phase (the D-04 idle-timeout clamp, the D-11
/// opt-out notice) writes here instead, so a loud message is actually
/// readable after the fact.
pub fn monitor_log_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-monitor.log", phase.padded()))
}

/// Path to the pipe-owning monitor's idle-timeout verdict for a phase
/// (D-05/D-06, 31-02).
///
/// A SIDE CHANNEL, deliberately separate from the stdout capture: the capture
/// is the agent's own narration, and a verdict appended to it is shadowed by
/// any earlier genuine `result` event the stream already contained. See
/// [`parse_idle_timeout_side_channel`] — that separation is a correctness
/// requirement (T-31-06), not a filing convention.
///
/// Holds a JSON [`IdleTimeoutRecord`]. Written and fsynced by the monitor
/// BEFORE the child is signalled, so nothing can race the verdict.
pub fn idle_timeout_path(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root).join(format!("phase-{}-idle-timeout", phase.padded()))
}

/// Path to the archived-capture-history directory for a phase (16b).
///
/// `.devflow/history/phase-NN/` holds retained per-stage capture generations
/// so a false-positive self-report can be diagnosed after the fact. Exposed
/// as a constructor (rather than inlined at each call site) so downstream
/// tooling (16h in 16-07's correlation, 16i in 16-05's enumeration) always
/// derives the path from here instead of hardcoding it.
pub fn history_dir(project_root: &Path, phase: PhaseId) -> PathBuf {
    devflow_dir(project_root)
        .join("history")
        .join(format!("phase-{}", phase.padded()))
}

/// Monotonically increasing tie-breaker appended to the nanosecond timestamp
/// used to stamp archived generations, so two archives issued within the
/// same nanosecond (possible in a tight test loop) never collide.
static ARCHIVE_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// A stamp unique within this process, used to name an archived generation.
/// The outgoing stage's name is not available at the `archive_phase_files`
/// call site (see `launch_stage` in main.rs), so a monotonic timestamp is
/// used instead — sufficient to order and identify generations.
fn archive_stamp() -> String {
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    let seq = ARCHIVE_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    format!("{nanos}-{seq}")
}

/// Archive the prior stage's stdout/exit captures into bounded per-phase
/// history instead of wiping them outright, so a false-positive self-report
/// can be diagnosed after the fact (16b). Replaces the old
/// `cleanup_phase_files`, which deleted these files unconditionally.
///
/// At most `retain` capture generations are kept per phase; older ones are
/// pruned (see [`prune_history`]). The agent-pid file is still removed
/// outright — it is process bookkeeping, not diagnostic output. When there
/// is nothing to archive (first launch), this is a no-op success.
pub fn archive_phase_files(
    project_root: &Path,
    evidence_root: &Path,
    phase: PhaseId,
    retain: usize,
) -> Result<Option<String>, std::io::Error> {
    archive_phase_files_with_stamp(project_root, evidence_root, phase, retain, &archive_stamp())
}

fn archive_phase_files_with_stamp(
    project_root: &Path,
    evidence_root: &Path,
    phase: PhaseId,
    retain: usize,
    stamp: &str,
) -> Result<Option<String>, std::io::Error> {
    let _ = std::fs::remove_file(agent_pid_path(project_root, phase));
    // The idle-timeout record has the SAME lifetime as the pid file above: it
    // describes one stage attempt and must not outlive it. Clearing it here was
    // simply missed when the side channel was introduced (31-02), and the
    // omission is not benign — [`parse_idle_timeout_side_channel`] is
    // `evaluate_layer1`'s FIRST statement and returns unconditionally
    // (T-31-06), by design, so that nothing can shadow a real timeout. A record
    // that survives its attempt therefore outranks every later stage's real
    // result, forever, for that phase.
    //
    // Observed 2026-08-08: a record written at 22:48 by a killed Plan stage
    // condemned a Define stage that had succeeded 15s earlier, in a 22-second
    // stage, with a message quoting a 120s silence and a pid dead for 14
    // minutes. It survived both `gate reject --note abort` and
    // `devflow start --force`, because nothing anywhere unlinked it.
    //
    // Deleting rather than archiving loses nothing: the verdict is already
    // durable in `advance_evaluated`'s `reason` in `events.jsonl` and in the
    // gate context that quotes it.
    //
    // This must stay ABOVE the "nothing to archive" early return below — the
    // case with a stale record and no capture beside it is exactly the one that
    // needs clearing.
    let _ = std::fs::remove_file(idle_timeout_path(project_root, phase));

    let stdout_src = stdout_path(project_root, phase);
    let exit_src = exit_code_path(project_root, phase);
    let stdout_exists = stdout_src.exists();
    let exit_exists = exit_src.exists();
    if !stdout_exists && !exit_exists {
        return Ok(None); // Nothing to archive — first launch.
    }

    let history_dir = history_dir(project_root, phase);
    crate::workflow::ensure_devflow_dir(&history_dir)?;

    let staging_dir = history_dir.join(format!(".pending-{stamp}"));
    std::fs::create_dir(&staging_dir)?;
    let stdout_stage = staging_dir.join("stdout");
    let exit_stage = staging_dir.join("exit");
    let review_stage = staging_dir.join("REVIEW.md");
    let stdout_dest = history_dir.join(format!("{stamp}-stdout"));
    let exit_dest = history_dir.join(format!("{stamp}-exit"));
    let review_dest = history_dir.join(format!("{stamp}-REVIEW.md"));
    let review_src = phase_review_path(evidence_root, phase);

    let mut stdout_staged = false;
    let mut exit_staged = false;
    let mut stdout_published = false;
    let mut exit_published = false;
    let mut review_published = false;

    let archive_result = (|| -> Result<(), std::io::Error> {
        if stdout_exists {
            std::fs::rename(&stdout_src, &stdout_stage)?;
            stdout_staged = true;
        }
        if exit_exists {
            std::fs::rename(&exit_src, &exit_stage)?;
            exit_staged = true;
        }
        if let Some(review) = &review_src {
            std::fs::copy(review, &review_stage)?;
        }

        if stdout_exists {
            std::fs::rename(&stdout_stage, &stdout_dest)?;
            stdout_staged = false;
            stdout_published = true;
        }
        if exit_exists {
            std::fs::rename(&exit_stage, &exit_dest)?;
            exit_staged = false;
            exit_published = true;
        }
        if review_src.is_some() {
            std::fs::rename(&review_stage, &review_dest)?;
            review_published = true;
        }
        Ok(())
    })();

    if let Err(error) = archive_result {
        let mut rollback_error = None;
        let mut restore = |from: &Path, to: &Path| {
            if let Err(error) = std::fs::rename(from, to)
                && rollback_error.is_none()
            {
                rollback_error = Some(error);
            }
        };
        if stdout_published {
            restore(&stdout_dest, &stdout_src);
        } else if stdout_staged {
            restore(&stdout_stage, &stdout_src);
        }
        if exit_published {
            restore(&exit_dest, &exit_src);
        } else if exit_staged {
            restore(&exit_stage, &exit_src);
        }
        if review_published {
            let _ = std::fs::remove_file(&review_dest);
        }
        let _ = std::fs::remove_dir_all(&staging_dir);

        if let Some(rollback_error) = rollback_error {
            return Err(std::io::Error::new(
                error.kind(),
                format!("{error}; archive rollback failed: {rollback_error}"),
            ));
        }
        return Err(error);
    }

    let _ = std::fs::remove_dir(&staging_dir);

    prune_history(&history_dir, retain);
    Ok(Some(stamp.to_string()))
}

fn phase_review_path(evidence_root: &Path, phase: PhaseId) -> Option<PathBuf> {
    let phases = std::fs::read_dir(evidence_root.join(".planning/phases")).ok()?;
    let prefix = format!("{padded}-", padded = phase.padded());
    for entry in phases.flatten() {
        if entry
            .file_name()
            .to_str()
            .is_some_and(|name| name.starts_with(&prefix))
        {
            let review = entry
                .path()
                .join(format!("{padded}-REVIEW.md", padded = phase.padded()));
            if review.exists() {
                return Some(review);
            }
        }
    }
    None
}

/// Whether `/gsd-verify-work` has produced a `{phase:02}-VERIFICATION.md`
/// artifact for `phase` yet.
///
/// Per D-01 (33-CONTEXT.md), this is the sole mid-arc-vs-genuine-gaps signal
/// a Validate→Code loop-back consults: a phase with no verification artifact
/// is still mid-arc (its remaining plans have not been judged at all), so a
/// loop-back must re-run the phase in full rather than dispatch `--gaps-only`,
/// which matches zero plans and gates unresolvably. Mirrors
/// [`phase_review_path`]'s directory-prefix-scan idiom exactly, but returns a
/// `bool` — no caller needs the artifact's path, only whether it exists. A
/// missing `.planning/phases` directory returns `false` rather than panicking.
///
/// `evidence_root` is the root the Validate agent actually wrote to — the
/// phase's worktree when `state.worktree_path` is set, else the project root.
/// `.planning/` is tracked, so in worktree mode the artifact lands on
/// `feature/phase-N` and is invisible from the main checkout for the phase's
/// entire in-flight duration. Passing the project root in worktree mode is
/// exactly the defect this parameter name exists to prevent (33-CONTEXT.md
/// CR-01); it is NOT interchangeable with the root used for git reads such as
/// [`phase_commit_count`], whose refs and object database are shared across
/// worktrees and which therefore correctly takes the project root.
pub fn phase_verification_exists(evidence_root: &Path, phase: PhaseId) -> bool {
    phase_verification_path(evidence_root, phase).is_some()
}

/// The `{phase:02}-VERIFICATION.md` artifact's path under `evidence_root`, or
/// `None` when no phase directory carries one.
///
/// Extracted from [`phase_verification_exists`] (999.79, 35-05) so the
/// existence probe and the content fingerprint below scan for the artifact in
/// exactly ONE place. Duplicating the prefix scan would let the two answer
/// about different files after any future change to the directory layout — and
/// the freshness rule is only sound while "does it exist" and "what are its
/// bytes" are questions about the same path.
///
/// `evidence_root` carries the same meaning and the same prohibition as it does
/// for [`phase_verification_exists`]: it is the root the Validate agent
/// actually wrote to, never the main checkout in worktree mode.
fn phase_verification_path(evidence_root: &Path, phase: PhaseId) -> Option<PathBuf> {
    let phases = std::fs::read_dir(evidence_root.join(".planning/phases")).ok()?;
    let prefix = format!("{padded}-", padded = phase.padded());
    for entry in phases.flatten() {
        if entry
            .file_name()
            .to_str()
            .is_some_and(|name| name.starts_with(&prefix))
        {
            let verification = entry
                .path()
                .join(format!("{padded}-VERIFICATION.md", padded = phase.padded()));
            if verification.exists() {
                return Some(verification);
            }
        }
    }
    None
}

/// A content fingerprint of the phase's `{phase:02}-VERIFICATION.md`, or `None`
/// when no such artifact exists under `evidence_root` (999.79, 35-05).
///
/// **What it is for.** Nothing deletes, dates or invalidates the artifact, and
/// `devflow start --phase N --force` checks out a branch that still carries the
/// PREVIOUS run's committed copy. That re-run is mid-arc by construction, so its
/// first Validate failure would find the stale artifact, read it as a verdict,
/// and dispatch a `--gaps-only` pass against zero matching plans — gating
/// unresolvably. Comparing this value against the one recorded at the start of
/// the run distinguishes "the Validate agent authored this during this run"
/// from "this was inherited".
///
/// **Why the algorithm is written out rather than borrowed from `std`.** This
/// value is persisted by one process (`devflow start`) and compared by a later
/// one (`devflow advance`), so it must mean the same thing in both.
/// `std::collections::hash_map::DefaultHasher` explicitly does NOT guarantee a
/// stable output across toolchain versions, so an operator who upgraded Rust
/// mid-phase would see every artifact read as "changed" — which is the
/// fail-OPEN direction, dispatching gaps-only exactly where a full execute was
/// correct. This is FNV-1a/64, fixed by these two constants and nothing else.
///
/// **No security property is claimed.** This is change detection over a
/// planning document that is already committed to the repository. It is not
/// collision-resistant and must never be used to authenticate anything; an
/// adversary who can write the artifact can already write whatever verdict they
/// like into it.
///
/// # Companion: [`phase_verification_mtime_nanos`]
///
/// Content alone cannot see an IDEMPOTENT rewrite (WR-06, 35-REVIEW): a
/// Validate agent that re-authors byte-identical content on a later cycle
/// produces the same fingerprint as an artifact nobody touched, and the
/// consumer then classifies its own agent's work as inherited. The mtime is
/// the second input that separates "unchanged because inherited" from
/// "unchanged because idempotent"; it is read from the same resolved path and
/// returns `None` on exactly the same "no artifact" condition, so the two are
/// always consistent about whether an artifact exists.
pub fn phase_verification_fingerprint(evidence_root: &Path, phase: PhaseId) -> Option<u64> {
    let path = phase_verification_path(evidence_root, phase)?;
    let bytes = std::fs::read(path).ok()?;
    // FNV-1a, 64-bit: offset basis and prime are the published constants.
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for byte in bytes {
        hash ^= u64::from(byte);
        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
    }
    Some(hash)
}

/// The mtime of the same `{phase:02}-VERIFICATION.md`
/// [`phase_verification_fingerprint`] hashes, in nanoseconds since the Unix
/// epoch, or `None` when no such artifact exists under `evidence_root`.
///
/// WR-06 (35-REVIEW): the second input the freshness rule needs. A content
/// fingerprint cannot see an IDEMPOTENT rewrite — a Validate agent that
/// re-authors byte-identical content on a later cycle produces the same hash as
/// an artifact nobody touched — so a hash-only rule classifies its own agent's
/// work as inherited and re-runs every plan in the phase from then on. An
/// inherited file's mtime does not advance during a run; a rewritten one's
/// does, whatever the bytes say.
///
/// Resolved through the same [`phase_verification_path`] and returning `None`
/// on the same "no artifact" condition, so the two readings can never disagree
/// about whether the artifact exists.
///
/// **This is not provenance either.** Any writer advances an mtime, so the
/// limitation the fingerprint's doc comment records — a mid-run branch switch
/// or an operator edit reading as authored-this-run — is not closed by this and
/// is marginally widened by it: a checkout restoring byte-identical content
/// used to read as inherited and now reads as authored. That is accepted
/// deliberately, because the case it fixes (a deterministic verification writer
/// on cycle 2 of an unresolved gap) is ordinary rather than exotic.
pub fn phase_verification_mtime_nanos(evidence_root: &Path, phase: PhaseId) -> Option<u64> {
    let path = phase_verification_path(evidence_root, phase)?;
    let modified = std::fs::metadata(path).ok()?.modified().ok()?;
    let since_epoch = modified.duration_since(std::time::UNIX_EPOCH).ok()?;
    // `as` would silently wrap past year 2554; a `None` here degrades to the
    // content-only comparison, which is the pre-WR-06 behaviour.
    u64::try_from(since_epoch.as_nanos()).ok()
}

/// Keep only the newest `retain` capture generations under `history_dir`,
/// deleting older ones. Generations are grouped by their stamp (the shared
/// prefix of a `{stamp}-stdout`/`{stamp}-exit` pair, split off the trailing
/// `-stdout`/`-exit` suffix via `rsplit_once`) and ordered lexicographically,
/// which matches numeric/chronological order for the fixed-width nanosecond
/// stamps `archive_stamp` produces. Ordering parses both numeric components;
/// the process-local sequence is intentionally not fixed-width.
fn prune_history(history_dir: &Path, retain: usize) {
    let Ok(entries) = std::fs::read_dir(history_dir) else {
        return;
    };

    let mut stamps: Vec<String> = entries
        .flatten()
        .filter_map(|entry| {
            let name = entry.file_name().to_str()?.to_string();
            name.rsplit_once('-')
                .map(|(stamp, _suffix)| stamp.to_string())
        })
        .collect();
    stamps.sort_by_key(|stamp| {
        let mut parts = stamp.split('-');
        let nanos = parts
            .next()
            .and_then(|part| part.parse::<u128>().ok())
            .unwrap_or(0);
        let sequence = parts
            .next()
            .and_then(|part| part.parse::<u64>().ok())
            .unwrap_or(0);
        (nanos, sequence)
    });
    stamps.dedup();

    if stamps.len() <= retain {
        return;
    }

    let to_remove = stamps.len() - retain;
    for stamp in &stamps[..to_remove] {
        let _ = std::fs::remove_file(history_dir.join(format!("{stamp}-stdout")));
        let _ = std::fs::remove_file(history_dir.join(format!("{stamp}-exit")));
        let _ = std::fs::remove_file(history_dir.join(format!("{stamp}-REVIEW.md")));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::GitFlowConfig;
    use crate::mode::Mode;
    use crate::stage::Stage;
    use crate::state::{AgentKind, State};

    fn state_in(root: &Path, phase: PhaseId) -> State {
        let mut state = State::new(phase, AgentKind::Claude, Mode::Auto, root.to_path_buf());
        state.stage = Stage::Code;
        state
    }

    fn git(root: &Path, args: &[&str]) {
        let output = crate::test_support::git_command(root)
            .args(args)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "git {:?} failed\nstdout: {}\nstderr: {}",
            args,
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
    }

    fn init_repo_with_feature_commit(root: &Path, phase: PhaseId) {
        git(root, &["init"]);
        git(root, &["config", "user.email", "devflow@example.com"]);
        git(root, &["config", "user.name", "DevFlow Tests"]);
        git(root, &["config", "commit.gpgsign", "false"]);
        git(root, &["config", "tag.gpgsign", "false"]);
        git(root, &["config", "core.hooksPath", "/dev/null"]);
        git(root, &["checkout", "-b", "develop"]);
        std::fs::write(root.join("README.md"), "base\n").unwrap();
        git(root, &["add", "README.md"]);
        git(root, &["commit", "-m", "base"]);

        let branch = format!("feature/phase-{padded}", padded = phase.padded());
        git(root, &["checkout", "-b", &branch]);
        std::fs::write(root.join("phase.txt"), "feature work\n").unwrap();
        git(root, &["add", "phase.txt"]);
        git(root, &["commit", "-m", "feature work"]);
    }

    /// Like `init_repo_with_feature_commit`, but the feature branch sits at
    /// develop's tip with **no** extra commit (0 commits ahead).
    fn init_repo_with_feature_no_commit(root: &Path, phase: PhaseId) {
        git(root, &["init"]);
        git(root, &["config", "user.email", "devflow@example.com"]);
        git(root, &["config", "user.name", "DevFlow Tests"]);
        git(root, &["config", "commit.gpgsign", "false"]);
        git(root, &["config", "tag.gpgsign", "false"]);
        git(root, &["config", "core.hooksPath", "/dev/null"]);
        git(root, &["checkout", "-b", "develop"]);
        std::fs::write(root.join("README.md"), "base\n").unwrap();
        git(root, &["add", "README.md"]);
        git(root, &["commit", "-m", "base"]);

        let branch = format!("feature/phase-{padded}", padded = phase.padded());
        git(root, &["checkout", "-b", &branch]);
    }

    #[test]
    fn parse_success_marker() {
        let stdout = "some output\nDEVFLOW_RESULT: {\"status\":\"success\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_failed_marker_with_reason() {
        let stdout =
            "work done\nDEVFLOW_RESULT: {\"status\":\"failed\",\"reason\":\"clippy errors\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.unwrap(), "clippy errors");
    }

    #[test]
    fn parse_missing_marker_returns_none() {
        let stdout = "just some output\nno marker here\n";
        assert!(parse_devflow_result(stdout).is_none());
    }

    #[test]
    fn parse_malformed_json_returns_none() {
        let stdout = "DEVFLOW_RESULT: {not valid json}\n";
        assert!(parse_devflow_result(stdout).is_none());
    }

    #[test]
    fn parse_lowercase_marker() {
        let stdout = "devflow_result: {\"status\":\"success\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_marker_without_space_after_colon() {
        let stdout = "DEVFLOW_RESULT:{\"status\":\"success\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_lowercase_no_space_marker() {
        // Lowercase prefix AND no space after the colon — the combination that
        // the Phase 6 review flagged as uncovered.
        let stdout = "devflow_result:{\"status\":\"success\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_finds_last_marker_in_tail() {
        // Multiple markers — should find the last one.
        let stdout = "DEVFLOW_RESULT: {\"status\":\"failed\"}\nsome more output\nDEVFLOW_RESULT: {\"status\":\"success\"}\n";
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_marker_lines_returns_last_marker_in_long_output() {
        let stdout = format!(
            "{}\nDEVFLOW_RESULT: {{\"status\":\"failed\"}}\n{}\n\
             DEVFLOW_RESULT: {{\"status\":\"success\"}}\n",
            "prefix".repeat(900),
            "tail output".repeat(100)
        );

        let result = parse_marker_lines(&stdout).unwrap();

        assert_eq!(result.status, AgentStatus::Success);
    }

    #[test]
    fn parse_marker_only_in_last_4000_chars() {
        // Marker beyond 4000 chars from end should not be found.
        let prefix = "a".repeat(5000);
        let stdout = format!("DEVFLOW_RESULT: {{\"status\":\"success\"}}\n{prefix}");
        assert!(parse_devflow_result(&stdout).is_none());
    }

    #[test]
    fn parse_marker_with_commits_and_summary() {
        let stdout = r#"DEVFLOW_RESULT: {"status":"success","commits":3,"summary":"added tests"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.commits, Some(3));
        assert_eq!(result.summary.unwrap(), "added tests");
    }

    #[test]
    fn parse_marker_inside_json_result_envelope() {
        // Claude --output-format json wraps the final text in a `result` field
        // with embedded newlines escaped.
        let stdout = r#"{"type":"result","subtype":"success","result":"All done.\nDEVFLOW_RESULT: {\"status\": \"success\", \"commits\": 2}","session_id":"abc"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.commits, Some(2));
    }

    #[test]
    fn parse_failed_marker_inside_json_envelope() {
        let stdout = r#"{"result":"work\nDEVFLOW_RESULT: {\"status\": \"failed\", \"reason\": \"tests failed\"}"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.unwrap(), "tests failed");
    }

    #[test]
    fn parse_json_envelope_without_marker_returns_none() {
        let stdout = r#"{"result":"did some work but forgot the marker","session_id":"x"}"#;
        assert!(parse_devflow_result(stdout).is_none());
    }

    #[test]
    fn detect_claude_json_rate_limit_by_subtype() {
        let stdout = r#"{"type":"result","subtype":"error_rate_limit","retry_after":"2026-06-18T15:45:30Z","result":"rate limited"}"#;
        assert_eq!(
            detect_rate_limit(stdout).as_deref(),
            Some("2026-06-18T15:45:30Z")
        );
    }

    #[test]
    fn detect_claude_json_rate_limit_by_429() {
        let stdout = r#"{"type":"result","api_error_status":429,"error":{"message":"Too many requests. Try later."}}"#;
        assert_eq!(
            detect_rate_limit(stdout).as_deref(),
            Some("Too many requests. Try later.")
        );
    }

    #[test]
    fn detect_codex_try_again_rate_limit() {
        let stdout = "Usage limit reached. Try again at 3:45 PM.\n";
        assert_eq!(detect_rate_limit(stdout).as_deref(), Some("3:45 PM"));
    }

    /// WR-12 (13-REVIEW.md), revised: `json_has_str`/`json_has_i64`/
    /// `json_find_key` run on the coding agent's raw stdout via
    /// `detect_claude_rate_limit`, which every `devflow advance` invocation
    /// goes through. Deeply nested JSON — accidental or adversarial — must
    /// not stack-overflow the process, and a real marker at any depth
    /// serde_json will parse (its default recursion limit is exactly 128)
    /// must still be FOUND — the first WR-12 fix capped traversal at 64 and
    /// silently misclassified rate-limit markers at depths 64–128.
    #[test]
    fn detect_rate_limit_finds_marker_in_deeply_nested_json_without_overflow() {
        // 100 levels: parseable by serde_json (limit 128), deeper than the
        // removed 64-level traversal cap that used to hide the marker.
        const DEPTH: usize = 100;
        let mut stdout = String::new();
        for _ in 0..DEPTH {
            stdout.push_str(r#"{"nested":"#);
        }
        stdout.push_str(r#"{"type":"result","subtype":"error_rate_limit","retry_after":"deep"}"#);
        for _ in 0..DEPTH {
            stdout.push('}');
        }

        // Must return promptly without crashing AND find the buried marker —
        // the iterative worklist traversal has no silent-miss window.
        assert_eq!(detect_rate_limit(&stdout).as_deref(), Some("deep"));
    }

    #[test]
    fn detect_rate_limit_ignores_normal_stdout() {
        let stdout = "implemented feature\nDEVFLOW_RESULT: {\"status\":\"success\"}\n";
        assert!(detect_rate_limit(stdout).is_none());
    }

    #[test]
    fn claude_envelope_is_error_detected() {
        let stdout = r#"{"type":"result","subtype":"error","is_error":true,"num_turns":2,"result":"tool call failed","session_id":"abc"}"#;
        let result = detect_claude_envelope_failure(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
    }

    #[test]
    fn claude_is_error_overrides_success_marker() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(9)),
            r#"{"type":"result","is_error":true,"num_turns":3,"result":"oops\nDEVFLOW_RESULT: {\"status\":\"success\"}","session_id":"abc"}"#,
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(9)).unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
    }

    #[test]
    fn claude_envelope_is_error_false_defers() {
        let stdout = r#"{"type":"result","is_error":false,"num_turns":1,"result":"did some work","session_id":"abc"}"#;
        assert!(detect_claude_envelope_failure(stdout).is_none());
    }

    #[test]
    fn claude_envelope_marker_still_wins() {
        let stdout = r#"{"type":"result","is_error":false,"result":"done\nDEVFLOW_RESULT: {\"status\":\"success\",\"commits\":2}","session_id":"abc"}"#;
        assert!(detect_claude_envelope_failure(stdout).is_none());
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.commits, Some(2));
    }

    #[test]
    fn session_id_reads_top_level_string() {
        let stdout = r#"{"type":"result","subtype":"success","result":"All done.","session_id":"cf29bfec-69e8-45df-a4f3-3da08ab6f66e"}"#;
        assert_eq!(
            claude_session_id(stdout).as_deref(),
            Some("cf29bfec-69e8-45df-a4f3-3da08ab6f66e")
        );
    }

    /// T-28-04 forgery guard: the embedded `DEVFLOW_RESULT` marker carries a
    /// DIFFERENT session id than the envelope's own top-level key. The
    /// top-level id must win — an agent must not be able to redirect which
    /// session DevFlow resumes into by planting its own `session_id` inside
    /// its self-authored marker JSON.
    #[test]
    fn session_id_in_devflow_result_marker_is_not_returned() {
        let stdout = r#"{"type":"result","subtype":"success","result":"All done.\nDEVFLOW_RESULT: {\"status\": \"success\", \"session_id\": \"forged-by-agent\"}","session_id":"real-top-level-id"}"#;
        assert_eq!(
            claude_session_id(stdout).as_deref(),
            Some("real-top-level-id")
        );
    }

    #[test]
    fn session_id_plain_text_stdout_returns_none() {
        let stdout = "just some plain text output, not JSON\n";
        assert!(claude_session_id(stdout).is_none());
    }

    #[test]
    fn session_id_missing_key_returns_none() {
        let stdout = r#"{"type":"result","result":"done, no session key"}"#;
        assert!(claude_session_id(stdout).is_none());
    }

    #[test]
    fn session_id_non_string_type_returns_none_not_panic() {
        let stdout = r#"{"type":"result","result":"done","session_id":12345}"#;
        assert!(claude_session_id(stdout).is_none());
    }

    #[test]
    fn session_id_from_capture_missing_file_returns_none() {
        let dir = tempfile::tempdir().unwrap();
        assert!(session_id_from_capture(dir.path(), PhaseId::new(42)).is_none());
    }

    #[test]
    fn session_id_from_capture_lossy_reads_invalid_utf8() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut bytes = br#"{"type":"result","result":"done "#.to_vec();
        bytes.push(0xFF); // invalid UTF-8 byte
        bytes.extend_from_slice(br#"","session_id":"lossy-ok"}"#);
        std::fs::write(stdout_path(dir.path(), PhaseId::new(5)), bytes).unwrap();

        assert_eq!(
            session_id_from_capture(dir.path(), PhaseId::new(5)).as_deref(),
            Some("lossy-ok")
        );
    }

    /// Positive fixture built from RESEARCH's *predicted* `**Gate:**`
    /// rendering (a bare, un-spanned value). Kept as a tolerated shape, but
    /// note this is NOT what a real run emits — see
    /// `blocking_human_checkpoint_reported_matches_live_observed_rendering`
    /// for the rendering actually captured on 2026-07-31, which this
    /// prediction missed.
    #[test]
    fn blocking_human_checkpoint_reported_detects_human_gate_line() {
        let stdout = format!(
            "## CHECKPOINT REACHED\n\n**Type:** human-verify\n**Gate:** {HUMAN_GATE_VALUE} — copy the task's `gate` attribute verbatim so the orchestrator's carve-out sees it\n"
        );
        assert!(blocking_human_checkpoint_reported(&stdout));
    }

    /// The Phase 26 near-miss distinction: a plain `blocking` gate must NOT
    /// be classified as a human-blocking checkpoint. `PLAIN_GATE_VALUE` is
    /// local to this test (not a module-level const) — it has no production
    /// use, only this negative fixture's.
    #[test]
    fn blocking_human_checkpoint_reported_false_for_plain_blocking() {
        const PLAIN_GATE_VALUE: &str = "blocking";
        let stdout = format!(
            "## CHECKPOINT REACHED\n\n**Type:** human-verify\n**Gate:** {PLAIN_GATE_VALUE} — copy the task's `gate` attribute verbatim so the orchestrator's carve-out sees it\n"
        );
        assert!(!blocking_human_checkpoint_reported(&stdout));
    }

    #[test]
    fn blocking_human_checkpoint_reported_false_when_no_gate_field() {
        let stdout = "some ordinary agent failure output, no checkpoint at all\n";
        assert!(!blocking_human_checkpoint_reported(stdout));
    }

    /// The `Gate:` line arrives inside an escaped Claude JSON result
    /// envelope's `result` field — must be found via the unescaped inner
    /// text, not the raw (escaped) JSON string.
    #[test]
    fn blocking_human_checkpoint_reported_true_inside_escaped_envelope() {
        let inner = format!(
            "## CHECKPOINT REACHED\\n\\n**Gate:** {HUMAN_GATE_VALUE} — copy the task's `gate` attribute verbatim so the orchestrator's carve-out sees it\\n"
        );
        let stdout = format!(
            r#"{{"type":"result","subtype":"success","result":"{inner}","session_id":"abc"}}"#
        );
        assert!(blocking_human_checkpoint_reported(&stdout));
    }

    #[test]
    fn blocking_human_checkpoint_reported_tolerates_whitespace_and_emphasis() {
        let stdout = format!("  **Gate:**   {HUMAN_GATE_VALUE}   \n");
        assert!(blocking_human_checkpoint_reported(&stdout));
    }

    /// REGRESSION — the rendering a real headless run actually produces.
    ///
    /// Transcribed verbatim from `.devflow/phase-91-stdout` of the live A1
    /// run on 2026-07-31 (a genuine `gate="blocking-human"` task driven
    /// through DevFlow's own monitor). The value arrives as a markdown CODE
    /// SPAN, not the bare token RESEARCH.md predicted.
    ///
    /// Before the backtick was added to `text_reports_human_gate`'s trim set
    /// this returned `false`: the leading backtick survived the trim, so the
    /// value `take_while` terminated at once and yielded an empty token. A
    /// real checkpoint was therefore never recognized, and the run fell
    /// through to the generic gate. If this test ever goes red, DevFlow has
    /// stopped recognizing real checkpoints — do not "fix" it by relaxing
    /// the assertion.
    #[test]
    fn blocking_human_checkpoint_reported_matches_live_observed_rendering() {
        let stdout = format!(
            "---\n\n## Checkpoint: Decision\n\n**Plan:** 91-01 Emit the checkpoint\n**Gate:** `{HUMAN_GATE_VALUE}`\n**Progress:** 0/1 tasks complete\n**Task:** Task 1 — Ask the operator to authorize writing the marker file\n"
        );
        assert!(
            blocking_human_checkpoint_reported(&stdout),
            "the live-observed code-span rendering must be recognized; \
             a false negative here means real checkpoints fall through to \
             the generic gate (the 2026-07-31 A1 defect)"
        );
    }

    /// The same live rendering as it actually crosses into DevFlow's capture:
    /// escaped inside the Claude JSON result envelope. This is the exact
    /// path `checkpoint_reported_in_capture` reads in production.
    #[test]
    fn blocking_human_checkpoint_reported_matches_live_rendering_in_envelope() {
        let inner = format!(
            "## Checkpoint: Decision\\n\\n**Gate:** `{HUMAN_GATE_VALUE}`\\n**Progress:** 0/1 tasks complete\\n"
        );
        let stdout = format!(
            r#"{{"type":"result","subtype":"success","result":"{inner}","session_id":"live-a1"}}"#
        );
        assert!(
            blocking_human_checkpoint_reported(&stdout),
            "the code-span rendering must also be found inside the escaped envelope"
        );
    }

    /// The backtick tolerance must not erode the Phase 26 near-miss
    /// distinction: a code-spanned PLAIN `blocking` gate is still not a
    /// human-blocking checkpoint.
    #[test]
    fn blocking_human_checkpoint_reported_false_for_code_spanned_plain_blocking() {
        let stdout = "## Checkpoint: Decision\n\n**Gate:** `blocking`\n";
        assert!(!blocking_human_checkpoint_reported(stdout));
    }

    #[test]
    fn checkpoint_reported_in_capture_missing_file_returns_false() {
        let dir = tempfile::tempdir().unwrap();
        assert!(!checkpoint_reported_in_capture(
            dir.path(),
            PhaseId::new(42)
        ));
    }

    #[test]
    fn checkpoint_reported_in_capture_reads_true_from_file() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(11)),
            format!("**Gate:** {HUMAN_GATE_VALUE}\n"),
        )
        .unwrap();
        assert!(checkpoint_reported_in_capture(dir.path(), PhaseId::new(11)));
    }

    // ---- stream-capture gate scoping (plan 30-05) --------------------------
    //
    // Fixtures for this cluster live with the other v3 envelopes further down:
    // `V3_USER_EVENT`, `V3_ASSISTANT_TOP_LEVEL_EVENT`,
    // `V3_ASSISTANT_SUBAGENT_EVENT`, `gate_declaration_text` and
    // `gate_documenting_text`. Read their doc comments before adding a case —
    // they record which capture line each envelope came from and that every
    // gate payload is synthetic.
    //
    // Each negative asserts a NEGATIVE CONTROL first: `text_reports_human_gate`
    // must still match the raw capture. Without it a negative would also pass
    // against a fixture that simply contains no gate text, and would keep
    // passing if someone deleted the gate line from the fixture.

    /// **REGRESSION — review constraint 3, the prompt-echo false positive.**
    ///
    /// Under a single-document envelope the only place gate text can appear is
    /// the one `result` field the agent authored, so scanning raw stdout is
    /// safe. A stream capture breaks that invariant: text DevFlow never
    /// authored is echoed back into the same stdout, and a substring scan
    /// cannot tell which event it is inside.
    ///
    /// A failure here means a checkpoint auto-decide can fire, or the resume
    /// ceiling be consumed, on a stage whose prompt merely DISCUSSED
    /// checkpoints — and DevFlow's own planning documents are exactly that kind
    /// of prompt content.
    #[test]
    fn blocking_human_checkpoint_reported_false_for_gate_text_in_user_event() {
        let capture = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        assert!(
            text_reports_human_gate(&capture),
            "negative control: the raw capture must still contain matchable \
             gate text, or this test asserts nothing"
        );
        assert!(
            !blocking_human_checkpoint_reported(&capture),
            "gate text inside a `user` event is echoed input, not an agent \
             declaration (review constraint 3)"
        );
    }

    /// **REGRESSION — T-30-22.** Gate text forwarded from a subagent is not the
    /// orchestrator declaring a gate. Mistaking subagent-forwarded content for
    /// orchestrator output is the error that invalidated the v1 experiment
    /// outright and got its whole capture discarded.
    ///
    /// Two independent guards reject this event — the type filter (it is an
    /// `assistant` event) and the provenance filter (its `parent_tool_use_id`
    /// is non-null). The case is kept even though either alone suffices: they
    /// are meant to fail independently, so a future widening of the type filter
    /// cannot silently inherit subagent content.
    #[test]
    fn blocking_human_checkpoint_reported_false_for_subagent_forwarded_gate_text() {
        let capture = stream_capture_of(&[
            &v3_message_event(V3_ASSISTANT_SUBAGENT_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        assert!(
            text_reports_human_gate(&capture),
            "negative control: the raw capture must still contain matchable \
             gate text, or this test asserts nothing"
        );
        assert!(
            !blocking_human_checkpoint_reported(&capture),
            "a subagent's forwarded text cannot present as the orchestrator's \
             own gate declaration"
        );
    }

    /// **REGRESSION — T-30-26, the surface cross-AI review found.**
    ///
    /// Narration is not declaration. The envelope is v3 line 6, whose captured
    /// payload is mid-turn narration appearing in NO `result` event of the
    /// capture — so admitting top-level `assistant` events would add a
    /// genuinely new trusted surface, not merely duplicate the result text.
    /// An agent narrating the checkpoint task it is about to work on would then
    /// trip the gate: the prompt-echo false positive, recreated one layer
    /// inward.
    ///
    /// Nothing observed is lost by excluding the class: turn-FINAL assistant
    /// text is duplicated verbatim into the `result` event that follows it
    /// (v3 lines 17→19, 36→37, 53→54).
    #[test]
    fn blocking_human_checkpoint_reported_false_for_top_level_assistant_narration() {
        let capture = stream_capture_of(&[
            &v3_message_event(V3_ASSISTANT_TOP_LEVEL_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        assert!(
            text_reports_human_gate(&capture),
            "negative control: the raw capture must still contain matchable \
             gate text, or this test asserts nothing"
        );
        assert!(
            !blocking_human_checkpoint_reported(&capture),
            "intermediate assistant narration discussing a gate is not a live \
             gate declaration"
        );
    }

    /// The positive that stops the scoping from degenerating into always-false
    /// — which would pass every negative above while silently dropping every
    /// real human authorization request (T-30-24).
    #[test]
    fn blocking_human_checkpoint_reported_true_for_top_level_result_declaration() {
        let capture = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, "Execute the plan."),
            &v3_result_event(V3_RESULT_TURN1, &gate_declaration_text()),
        ]);
        assert!(
            blocking_human_checkpoint_reported(&capture),
            "a gate declared in a top-level `result` event's own result text \
             must still be detected under a stream capture"
        );
    }

    /// **T-30-27.** Detection asks whether a gate fired ANYWHERE in the stage,
    /// so it deliberately does NOT inherit plan 30-01's last-result-wins
    /// verdict semantics. A gate declared in turn 1 followed by
    /// task-notification wake-up turns — the exact turn shape the v3 capture
    /// archives — must not be dropped in favour of the later, silent results.
    ///
    /// Losing a checkpoint report is the opposite-direction harm from the false
    /// positive this plan closes, and the worse of the two: it silently drops a
    /// request for human authorization to the generic gate.
    #[test]
    fn blocking_human_checkpoint_reported_true_when_only_first_result_declares_gate() {
        let capture = v3_stream_capture(&gate_declaration_text(), NO_MARKER, NO_MARKER);
        assert!(
            blocking_human_checkpoint_reported(&capture),
            "detection must scan every top-level `result` event, not only the \
             last one"
        );
    }

    /// The overcorrection guard: an echo and a genuine declaration can coexist
    /// in one capture, and the scoping must resolve per event rather than
    /// suppressing any capture that contains an echo.
    #[test]
    fn blocking_human_checkpoint_reported_true_when_echo_co_occurs_with_declaration() {
        let capture = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, &gate_declaration_text()),
        ]);
        assert!(
            blocking_human_checkpoint_reported(&capture),
            "an echoed prompt in the same capture must not suppress a genuine \
             declaration"
        );
    }

    /// The same scoping, proven on the path production actually consumes —
    /// `checkpoint_reported_in_capture` reading `.devflow/phase-NN-stdout` from
    /// disk. Both directions are asserted in one test on purpose: the negative
    /// alone cannot distinguish correct scoping from a wrapper that stopped
    /// reading the file at all.
    #[test]
    fn checkpoint_reported_in_capture_scopes_stream_gate_text_to_result_events() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();

        let echo_only = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        std::fs::write(stdout_path(dir.path(), PhaseId::new(30)), &echo_only).unwrap();
        assert!(
            !checkpoint_reported_in_capture(dir.path(), PhaseId::new(30)),
            "an echoed gate mention read from the capture file must not report \
             a checkpoint"
        );

        let declared = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, &gate_declaration_text()),
        ]);
        std::fs::write(stdout_path(dir.path(), PhaseId::new(31)), &declared).unwrap();
        assert!(
            checkpoint_reported_in_capture(dir.path(), PhaseId::new(31)),
            "a genuine declaration read from the capture file must still \
             report a checkpoint"
        );
    }

    /// **The fail-open regression.** A torn `system`/`init` line must not send
    /// gate scanning back to raw stdout.
    ///
    /// `claude_stream_events` silently drops any line that fails to parse, and
    /// recognition used to require a successfully parsed `init`. So one
    /// truncated first line — a partial write, or a read of a capture still
    /// being appended to — made the whole capture unrecognised, and
    /// `blocking_human_checkpoint_reported` fell back to scanning raw stdout,
    /// which under a stream capture contains the echoed prompt. The constraint-3
    /// scoping failed OPEN, into the exact false positive it exists to close.
    /// Found by cross-AI code review (gpt-5.6-sol, 2026-08-02, High finding 2).
    ///
    /// Envelopes are real (v3 `user` + `result`); the `init` line is a real one
    /// truncated mid-token, and the gate text payload is synthetic — no archived
    /// capture contains gate text or a prompt echo.
    #[test]
    fn blocking_human_checkpoint_reported_false_when_init_is_torn() {
        let torn_init = &V3_INIT_EVENT[..40];
        assert!(
            serde_json::from_str::<serde_json::Value>(torn_init).is_err(),
            "fixture precondition: the truncated init must actually fail to parse"
        );

        let capture = format!(
            "{}\n{}\n{}\n",
            torn_init,
            v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            !blocking_human_checkpoint_reported(&capture),
            "a torn init must not re-enable the raw-stdout scan and let the \
             echoed prompt read as a gate declaration"
        );

        // Same capture, init intact — proves the negative above is the torn-init
        // path being handled, not the fixture simply lacking gate text.
        let intact = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        assert!(
            !blocking_human_checkpoint_reported(&intact),
            "control: the same capture with a valid init is also false"
        );

        // And a real declaration is still detected with the init torn, so the
        // fix did not degenerate into always-false (T-30-24).
        let declared = format!(
            "{}\n{}\n{}\n",
            torn_init,
            v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            v3_result_event(V3_RESULT_TURN1, &gate_declaration_text()),
        );
        assert!(
            blocking_human_checkpoint_reported(&declared),
            "a genuine declaration must still be detected when init is torn"
        );
    }

    /// A stream with NO `init` at all is likewise scoped rather than raw-scanned.
    /// Same fail-open class as the torn-init case; reported by the same review.
    #[test]
    fn blocking_human_checkpoint_reported_false_when_init_is_absent() {
        let capture = format!(
            "{}\n{}\n",
            v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            !blocking_human_checkpoint_reported(&capture),
            "an init-less stream must still scope the gate scan to result events"
        );
    }

    /// **The mandatory over-correction controls.** Widening stream recognition
    /// must not divert the three non-stream inputs off the raw-scan path they
    /// have always used (T-30-25). Each carries genuine gate text and must
    /// still report `true`; if any flips to `false`, the widening has started
    /// suppressing real gates.
    #[test]
    fn non_stream_captures_still_use_the_raw_scan_after_widening() {
        let plain = format!("Some narration.\n{}\n", gate_declaration_text());
        assert!(
            blocking_human_checkpoint_reported(&plain),
            "plain text must still be raw-scanned"
        );

        let single_doc = v3_result_event(V3_RESULT_TURN1, &gate_declaration_text());
        assert!(
            blocking_human_checkpoint_reported(&single_doc),
            "a single-document envelope must still be raw-scanned — it is \
             `{{\"type\":\"result\"}}`, which claude_stream_gate_shape excludes"
        );

        let codex = format!(
            "{{\"type\":\"thread.started\",\"thread_id\":\"t1\"}}\n\
             {{\"type\":\"item.completed\",\"item\":{{\"type\":\"agent_message\",\
             \"text\":\"{}\"}}}}\n",
            gate_declaration_text().replace('"', "\\\"")
        );
        assert!(
            blocking_human_checkpoint_reported(&codex),
            "a Codex stream must still be raw-scanned — its top-level types are \
             dotted, so claude_stream_gate_shape excludes it"
        );
    }

    /// **Fourth-pass High.** Decoding must never JOIN tokens across corrupt
    /// bytes. The third pass's remediation dropped invalid bytes, and
    /// `DEVFLOW_RESULT: {"status":"suc<FF>cess"}` with exit 1 decoded to a
    /// fabricated, VALID success marker — Layer 1 then short-circuited the
    /// nonzero exit. Replacement (U+FFFD) keeps the corruption visible: the
    /// status reads `suc\u{FFFD}cess`, no parser trusts it, and the exit code
    /// decides. Edge corruption stays covered by [`strip_corruption_padding`]
    /// — see the sibling third-pass test, which must pass alongside this one.
    #[test]
    fn corrupt_byte_inside_a_marker_is_never_repaired_into_success() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();

        let mut poisoned = b"DEVFLOW_RESULT: {\"status\":\"suc".to_vec();
        poisoned.push(0xff);
        poisoned.extend_from_slice(b"cess\"}");
        std::fs::write(stdout_path(dir.path(), PhaseId::new(30)), &poisoned).unwrap();
        assert_ne!(
            evaluate_layer1(dir.path(), PhaseId::new(30)).map(|r| r.status),
            Some(AgentStatus::Success),
            "a corrupt capture with no valid success marker must not be \
             repaired into an authoritative one"
        );

        // Control: the same marker with the byte absent IS a real success.
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(31)),
            br#"DEVFLOW_RESULT: {"status":"success"}"#,
        )
        .unwrap();
        assert_eq!(
            evaluate_layer1(dir.path(), PhaseId::new(31)).map(|r| r.status),
            Some(AgentStatus::Success),
            "control: the intact marker must still parse as success"
        );
    }

    /// **Third-pass High.** A stray invalid byte outside the JSON envelope must
    /// not convert an authoritative failure into a Layer-2 success.
    ///
    /// `from_utf8_lossy` substitutes U+FFFD, which survives `trim()`, so
    /// `detect_claude_envelope_failure`'s `starts_with('{')` guard went false and
    /// Layer 1 abstained on `is_error: true`. The cascade then fell through to
    /// the exit-code check — Ship proceeding on a reported failure. Reachable on
    /// the shipped `--output-format json` envelope; nothing to do with
    /// stream-json.
    #[test]
    fn stray_invalid_byte_does_not_hide_an_envelope_failure() {
        let envelope = br#"{"type":"result","subtype":"error","is_error":true,"result":"boom","session_id":"s"}"#;
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();

        std::fs::write(stdout_path(dir.path(), PhaseId::new(30)), envelope).unwrap();
        assert_eq!(
            evaluate_layer1(dir.path(), PhaseId::new(30)).map(|r| r.status),
            Some(AgentStatus::Failed),
            "control: the intact envelope is an authoritative Layer-1 failure"
        );

        let mut poisoned = vec![0xffu8];
        poisoned.extend_from_slice(envelope);
        std::fs::write(stdout_path(dir.path(), PhaseId::new(31)), &poisoned).unwrap();
        assert_eq!(
            evaluate_layer1(dir.path(), PhaseId::new(31)).map(|r| r.status),
            Some(AgentStatus::Failed),
            "one invalid byte before the envelope must not make Layer 1 abstain \
             and hand a FAILURE to the exit-code fallback"
        );
    }

    /// **Third-pass Medium.** A torn gate-bearing `user` event must not reopen
    /// raw-stdout scanning.
    ///
    /// `claude_stream_gate_shape` keyed stream recognition on system/user/
    /// assistant events. If the echoed `user` event tore *after* carrying the
    /// full gate text and only a later `result` parsed, none of those types
    /// survived, the capture stopped looking like a stream, and the raw scan
    /// read the echoed prompt as a declaration. Every line is still `{`-shaped,
    /// so this is neither the torn-`init` case nor V-01.
    #[test]
    fn torn_gate_bearing_user_event_does_not_reopen_raw_scanning() {
        let echo = v3_message_event(V3_USER_EVENT, &gate_documenting_text());
        let quiet_result = v3_result_event(V3_RESULT_TURN1, NO_MARKER);

        let closed = format!("{}\n{}\n{}\n", V3_INIT_EVENT, echo, quiet_result);
        assert!(
            !blocking_human_checkpoint_reported(&closed),
            "control: with the echo intact the gate mention is correctly scoped out"
        );

        let torn = format!("{}\n{}\n", &echo[..echo.len() - 12], quiet_result);
        assert!(
            !blocking_human_checkpoint_reported(&torn),
            "a torn echo leaving only a result must stay scoped, not fall back to \
             the raw scan that reads the echoed prompt as a declaration"
        );

        // The shipped single-document envelope is ONE result line and must keep
        // taking the raw path (T-30-25).
        let single_doc = v3_result_event(V3_RESULT_TURN1, &gate_declaration_text());
        assert!(
            blocking_human_checkpoint_reported(&single_doc),
            "control: the single-document envelope still uses the raw scan"
        );
    }

    /// **Fourth-pass Medium 3.** Benign prose noise must not block session
    /// recovery — only a torn JSON line can conceal a newer `init`.
    ///
    /// The first fail-closed guard rejected the capture when ANY non-empty line
    /// failed to parse, so one interleaved progress line disabled checkpoint
    /// auto-resume while the verdict parser accepted the same capture. An
    /// `init` is a JSON line; a non-`{` line can never be a torn one.
    #[test]
    fn prose_noise_does_not_block_session_recovery() {
        let stream = format!(
            "{}\nprogress: still working…\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            claude_stream_session_id(&stream).is_some(),
            "a prose progress line must not fail session recovery closed"
        );

        // Control: the same capture with the noise line made JSON-shaped-but-torn
        // MUST fail closed — that shape could be a torn newer init.
        let torn = format!(
            "{}\n{{\"type\":\"system\",\"subty\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            claude_stream_session_id(&torn).is_none(),
            "a torn JSON line could be a newer init and must fail closed"
        );
    }

    /// **Third-pass High.** A torn *later* `init` must not resurrect an earlier
    /// session's id.
    ///
    /// Each turn opens its own `init`; the last carries the id a resume must
    /// target. Dropped lines are invisible, so the scan returned the last
    /// PARSEABLE init — a stale token that looks entirely valid. Fails closed
    /// now: `None` costs a resume, the wrong id corrupts one.
    #[test]
    fn torn_later_init_does_not_resurrect_a_stale_session_id() {
        let init =
            |id: &str| format!(r#"{{"type":"system","subtype":"init","session_id":"{id}"}}"#);

        let rotated = format!("{}\n{}\n", init("session-a"), init("session-b"));
        assert_eq!(
            claude_stream_session_id(&rotated).as_deref(),
            Some("session-b"),
            "control: with both init events intact the LAST id wins"
        );

        let init_c = init("session-c");
        let torn = format!(
            "{}\n{}\n{}\n",
            init("session-a"),
            init("session-b"),
            &init_c[..init_c.len() - 10],
        );
        assert_ne!(
            claude_stream_session_id(&torn).as_deref(),
            Some("session-b"),
            "a torn newer init must not hand back the previous session's id"
        );
    }

    /// **V-01 regression.** One stray JSONL-shaped line must not divert a
    /// plain-text capture onto the stream branch and suppress a real gate.
    ///
    /// The first `claude_stream_gate_shape` asked only whether ANY event carried
    /// a stream type. Since the stream branch never consults raw stdout, a single
    /// `{"type":"assistant",…}` line was enough to hide a genuine declaration
    /// sitting in the surrounding plain text — turning the fail-OPEN this
    /// predicate was written to close into a fail-CLOSED that drops a human
    /// authorization request. Found by phase-30 verification after the fix
    /// shipped in `06675da`.
    #[test]
    fn one_stray_json_line_does_not_suppress_a_plain_text_gate() {
        let gate = gate_declaration_text();

        assert!(
            blocking_human_checkpoint_reported(&gate),
            "positive control: the gate text alone must be detected"
        );

        let poisoned =
            format!("{gate}\n{{\"type\":\"assistant\",\"message\":{{\"content\":[]}}}}\n");
        assert!(
            blocking_human_checkpoint_reported(&poisoned),
            "one stray JSONL line must not suppress a real plain-text gate (V-01)"
        );

        // The torn-init capture is still recognised as a stream — the majority
        // rule must not undo the fail-open fix it was added to preserve.
        let torn_init = &V3_INIT_EVENT[..40];
        let torn = format!(
            "{}\n{}\n{}\n",
            torn_init,
            v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            !blocking_human_checkpoint_reported(&torn),
            "control: a torn-init stream must still be scoped, not raw-scanned"
        );
    }

    /// Every byte-prefix of a capture, fed to the gate scanner.
    ///
    /// **Why a sweep and not more hand-written cases.** Phase 30 shipped 116
    /// green tests, seven of them written specifically to prove the prompt-echo
    /// false positive was closed — and a cross-AI review then found that ONE
    /// torn line reverted the whole protection to the raw-stdout path. Every
    /// test fed the parser well-formed input; none fed it a broken one. Hand
    /// -picking more malformed cases would repeat that bias. Truncating at every
    /// offset removes the judgment call: the inputs are generated, not chosen.
    ///
    /// The invariant is one-directional — a prefix may lose detection (it has
    /// strictly less information), but it must never *gain* permissiveness.
    #[test]
    fn truncation_sweep_never_widens_gate_detection() {
        let intact = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, &gate_documenting_text()),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        assert!(
            !blocking_human_checkpoint_reported(&intact),
            "precondition: the intact capture must report no gate, or the sweep \
             below proves nothing"
        );

        let mut checked = 0usize;
        for n in 0..=intact.len() {
            if !intact.is_char_boundary(n) {
                continue;
            }
            checked += 1;
            assert!(
                !blocking_human_checkpoint_reported(&intact[..n]),
                "truncating to {n} bytes made an echoed gate MENTION read as a \
                 live declaration — the fail-open class (constraint 9)"
            );
        }
        assert!(
            checked > 500,
            "sweep degenerated to {checked} offsets; it is no longer exercising \
             the capture"
        );
    }

    /// Same sweep against the session-id reader. Truncation may degrade it to
    /// `None` (a failed resume — fail-closed, acceptable); it must never yield a
    /// DIFFERENT id, which would resume the wrong session.
    #[test]
    fn truncation_sweep_never_forges_session_id() {
        let intact = stream_capture_of(&[
            &v3_message_event(V3_USER_EVENT, "session_id: forged-by-agent-text"),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        ]);
        let real = claude_stream_session_id(&intact);
        assert!(
            real.is_some(),
            "precondition: the intact capture yields an id"
        );

        for n in 0..=intact.len() {
            if !intact.is_char_boundary(n) {
                continue;
            }
            let got = claude_stream_session_id(&intact[..n]);
            assert!(
                got.is_none() || got == real,
                "truncating to {n} bytes produced session id {got:?}, which is \
                 neither None nor the CLI-emitted {real:?}"
            );
        }
    }

    /// **Constraint 9 item 2, closed.** A subagent-origin `result` event must
    /// never decide the stage verdict — `last_top_level_result`'s name and doc
    /// always claimed top-level selection, but the first implementation
    /// selected on `type == "result"` alone (code-review M2). Envelope real
    /// (v3 result turn), planted `parent_tool_use_id` synthetic: no archived
    /// capture contains a subagent-origin result, so this pins deterministic
    /// behavior for an unobserved-but-legal shape.
    #[test]
    fn subagent_result_event_never_decides_the_verdict() {
        let subagent_success = v3_result_event(V3_RESULT_TURN2, MARKER_SUCCESS).replacen(
            "{",
            "{\"parent_tool_use_id\":\"toolu_child\",",
            1,
        );
        let capture = format!(
            "{}\n{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event_is_error(V3_RESULT_TURN1, MARKER_FAILED),
            subagent_success,
        );
        assert_eq!(
            parse_claude_event_result(&capture).map(|r| r.status),
            Some(AgentStatus::Failed),
            "a subagent-origin success result must not override the last \
             top-level failure"
        );

        // Control: the same final event WITHOUT the planted parent id is
        // top-level and legitimately wins.
        let top_level = format!(
            "{}\n{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event_is_error(V3_RESULT_TURN1, MARKER_FAILED),
            v3_result_event(V3_RESULT_TURN2, MARKER_SUCCESS),
        );
        assert_eq!(
            parse_claude_event_result(&top_level).map(|r| r.status),
            Some(AgentStatus::Success),
            "control: the same event without a parent id is the final verdict"
        );
    }

    /// D-13 trap 1, pinned: the delivery canary's declared token appears in the
    /// stream as a PROMPT ECHO before it can ever appear as an answer, so a
    /// naive text scan reports delivery on every run — including runs where the
    /// notification path is dead. That echo is what produced the checkpoint
    /// false positive 30-05 fixed.
    ///
    /// Three cases, and the first two are the negative controls that give the
    /// third its meaning: the same token, in the same capture shape, must read
    /// `false` from an echo and from a subagent-origin result, and `true` only
    /// from a top-level `result`.
    #[test]
    fn token_matches_only_inside_top_level_result() {
        const TOKEN: &str = "DEVFLOW-CANARY-7f3a";

        // 1. Echo only: the token is in the operator's own turn, forwarded back
        //    into stdout, and in no result at all.
        let echoed = format!(
            "{}\n{}\n{}\n",
            V3_INIT_EVENT,
            V3_USER_EVENT.replace("__MARKER__", &format!("please return {TOKEN} when done")),
            v3_result_event(V3_RESULT_TURN1, NO_MARKER),
        );
        assert!(
            !token_reported_in_capture(&echoed, TOKEN),
            "a token echoed back in the prompt is not delivery evidence — \
             the CLI forwards the operator's own turn into the same stdout"
        );

        // 2. Subagent-origin result: right event type, wrong provenance.
        let subagent = format!(
            "{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN2, TOKEN).replacen(
                "{",
                "{\"parent_tool_use_id\":\"toolu_child\",",
                1,
            ),
        );
        assert!(
            !token_reported_in_capture(&subagent, TOKEN),
            "a subagent-origin result must not satisfy the canary — it is the \
             same provenance hole constraint 9 item 2 closed for the verdict"
        );

        // 3. Authoritative: a top-level `result` carrying the token.
        let authoritative = format!(
            "{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN1, TOKEN),
        );
        assert!(
            token_reported_in_capture(&authoritative, TOKEN),
            "a token inside a top-level result IS the canary's answer"
        );
    }

    /// The Codex arm of the trailing-torn rule — same R1 root cause, and the
    /// Codex adapter is live in production.
    ///
    /// A torn tail must not resurrect an earlier success marker: the torn-tail
    /// check runs before both the terminal and marker scans. (The
    /// terminal-vs-marker precedence is now `turn.failed`-over-marker —
    /// 999.107 #1 — superseding the pre-fix marker-first order.)
    #[test]
    fn codex_torn_tail_does_not_resurrect_earlier_success_marker() {
        let intact = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"success\\\"}\"}}\n",
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"failed\\\"}\"}}\n",
        );
        assert_eq!(
            parse_codex_event_result(intact).map(|r| r.status),
            Some(AgentStatus::Failed),
            "control: intact capture — the LAST marker wins and it is a failure"
        );

        let torn = &intact[..intact.len() - 20];
        assert_ne!(
            parse_codex_event_result(torn).map(|r| r.status),
            Some(AgentStatus::Success),
            "a torn superseding marker must not let the earlier success marker \
             decide the stage"
        );
    }

    /// **Sixth-pass Highs 1–3.** The marker tail scanner — the reader that
    /// decides most production stages today — must survive edge corruption, a
    /// marker line longer than the tail budget, and mixed-case prefixes (its
    /// contract has always said case-insensitive).
    #[test]
    fn marker_tail_scan_survives_corruption_length_and_case() {
        let m = "DEVFLOW_RESULT: {\"status\":\"failed\"}";
        assert_eq!(
            parse_devflow_result(m).map(|r| r.status),
            Some(AgentStatus::Failed),
            "control: the plain marker parses"
        );

        // High 1 — edge corruption on either side must not hide the marker.
        for poisoned in [format!("\u{FFFD}{m}"), format!("{m}\u{FFFD}")] {
            assert_eq!(
                parse_devflow_result(&poisoned).map(|r| r.status),
                Some(AgentStatus::Failed),
                "one stray byte at a line edge must not hide a failure marker"
            );
        }
        // …while interior corruption stays untrusted (fourth-pass hazard).
        assert!(
            parse_devflow_result("DEVFLOW_RESULT: {\"status\":\"fai\u{FFFD}led\"}").is_none(),
            "interior corruption must not parse as a valid status"
        );

        // High 2 — a marker line longer than the tail budget is scanned whole.
        let long_reason = "x".repeat(5000);
        let long =
            format!("DEVFLOW_RESULT: {{\"status\":\"failed\",\"reason\":\"{long_reason}\"}}");
        assert_eq!(
            parse_devflow_result(&long).map(|r| r.status),
            Some(AgentStatus::Failed),
            "the tail budget must never bisect the final marker line"
        );
        // …and the budget still bounds the walk: a marker buried beyond the
        // budget with newer non-marker output after it stays out of reach.
        let buried = format!("{m}\n{}\n", "y\n".repeat(4100));
        assert!(
            parse_devflow_result(&buried).is_none(),
            "control: the budget still cuts off markers deep in old output"
        );

        // High 3 — mixed case matches, per the documented contract.
        assert_eq!(
            parse_devflow_result("DevFlow_Result: {\"status\":\"failed\"}").map(|r| r.status),
            Some(AgentStatus::Failed),
            "mixed-case prefix must match — the contract says case-insensitive"
        );
    }

    /// **Sixth-pass Mediums 4–5.** The codex plain-text rate-limit heuristic:
    /// an edge-corrupt JSON event line must stay excluded from prose scanning,
    /// and "429" only counts as a standalone token.
    #[test]
    fn codex_rate_limit_heuristic_excludes_recovered_json_and_embedded_429() {
        // M4 — a corrupt-prefixed event line is still a JSON line, not prose.
        let doc_line = concat!(
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"docs mention rate limiting policies\"}}",
        );
        let poisoned =
            format!("{{\"type\":\"thread.started\",\"thread_id\":\"t\"}}\n\u{FFFD}{doc_line}\n");
        assert!(
            detect_codex_rate_limit(&poisoned).is_none(),
            "an edge-corrupt event line must not be prose-scanned for \
             rate-limit vocabulary"
        );
        // Control: genuine plain-text rate-limit output is still detected.
        assert!(
            detect_codex_rate_limit("Rate limit exceeded. Try again at 17:00.").is_some(),
            "control: real plain-text rate-limit output must still be detected"
        );

        // M5 — embedded digits are not rate-limit evidence…
        assert!(
            detect_codex_rate_limit("processed issue #429 successfully").is_none(),
            "'#429' is an issue number, not a rate limit"
        );
        assert!(
            detect_codex_rate_limit("transferred 14290 bytes").is_none(),
            "digits containing 429 are not a rate limit"
        );
        // …while a genuine standalone 429 still is.
        assert!(
            detect_codex_rate_limit("HTTP 429 Too Many Requests").is_some(),
            "control: a standalone 429 status is still detected"
        );
    }

    /// **Fifth-pass High 1.** A replacement-character-prefixed event line must
    /// not classify as prose Noise and slip past the torn-tail guard.
    ///
    /// `read_capture` turns an invalid byte into U+FFFD; a line reading
    /// `\u{FFFD}{"type":…}` fails to parse and does not start with `{`, so it
    /// became Noise — invisible to `torn_json_after_last_matching`. A corrupt
    /// byte in front of a superseding failed marker let the earlier success
    /// marker decide the stage, with the contradicting exit code never
    /// consulted. Live today on the Codex `--json` adapter. The fix recovers
    /// an edge-corrupt-but-intact event by re-parsing the stripped line, so
    /// the TRUE verdict decides — better than merely failing indeterminate.
    #[test]
    fn corruption_prefixed_event_line_is_not_prose_noise() {
        let good = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"success\\\"}\"}}\n",
        );
        let failed_line = concat!(
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"failed\\\"}\"}}\n",
        );

        let intact = format!("{good}{failed_line}");
        assert_eq!(
            parse_codex_event_result(&intact).map(|r| r.status),
            Some(AgentStatus::Failed),
            "control: intact capture — the last (failed) marker decides"
        );

        let poisoned = format!("{good}\u{FFFD}{failed_line}");
        assert_eq!(
            parse_codex_event_result(&poisoned).map(|r| r.status),
            Some(AgentStatus::Failed),
            "an edge-corrupt superseding marker must be recovered (or at worst \
             fail indeterminate) — never let the earlier success decide"
        );

        // Interior corruption stays visible and untrusted: a FFFD INSIDE the
        // marker's status string must not parse as a valid status (the
        // fourth-pass fabrication hazard, still guarded).
        let interior = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"suc\u{FFFD}cess\\\"}\"}}\n",
        );
        assert_ne!(
            parse_codex_event_result(interior).map(|r| r.status),
            Some(AgentStatus::Success),
            "interior corruption must never be repaired into a success"
        );
    }

    /// **Fifth-pass Medium 1.** An edge-corrupt rate-limit envelope must stay
    /// `RateLimited`, not decay into a generic `Failed`.
    ///
    /// The rate-limit detector outranks the generic envelope-failure detector
    /// precisely because rate-limit envelopes carry `is_error: true`. It was
    /// the one single-document reader without `strip_corruption_padding`, so a
    /// stray byte inverted the precedence — auto-resume became review/gating.
    #[test]
    fn edge_corrupt_rate_limit_envelope_stays_rate_limited() {
        let envelope = r#"{"type":"result","subtype":"error_rate_limit","is_error":true,"result":"rate limited","retry_after":"17:00"}"#;
        assert!(
            detect_claude_rate_limit(envelope).is_some(),
            "control: the intact envelope is detected as a rate limit"
        );
        assert!(
            detect_claude_rate_limit(&format!("\u{FFFD}{envelope}")).is_some(),
            "one stray byte must not demote RateLimited to generic Failed"
        );
    }

    /// **Fourth-pass Medium 1.** The generic marker path — the one production
    /// hits today — must overwrite a planted `decided_by_layer`, exactly as the
    /// stream path has since 30-01. `Some(0)` is Layer-0 external-verification
    /// provenance, which `classify_validate_outcome` trusts when classifying a
    /// Validate stage: an agent could force the ambiguous-validation gate with
    /// a verdict it never earned (999.67's class, live instance).
    #[test]
    fn generic_marker_cannot_forge_layer0_provenance() {
        let stdout = r#"DEVFLOW_RESULT: {"status":"success","decided_by_layer":0}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(
            result.decided_by_layer,
            Some(1),
            "a planted decided_by_layer:0 must be overwritten to Layer 1"
        );

        // Control: an honest marker without the field also normalises to
        // Some(1) — provenance is DERIVED here, never deserialized.
        let honest = r#"DEVFLOW_RESULT: {"status":"success"}"#;
        assert_eq!(
            parse_devflow_result(honest).unwrap().decided_by_layer,
            Some(1)
        );
    }

    /// Codex arm of the T-30-26 provenance overwrite (fourth-pass Medium 1's
    /// class): a `decided_by_layer` planted in the codex marker JSON must be
    /// overwritten, exactly as on the generic and Claude-stream marker paths.
    #[test]
    fn codex_marker_cannot_forge_layer0_provenance() {
        let capture = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",",
            "\"text\":\"DEVFLOW_RESULT: {\\\"status\\\":\\\"success\\\",\\\"decided_by_layer\\\":0}\"}}\n",
        );
        let result = parse_codex_event_result(capture).unwrap();
        assert_eq!(
            result.decided_by_layer,
            Some(1),
            "a planted decided_by_layer:0 must be overwritten to Layer 1"
        );
    }

    /// **Constraint 9 item 1, closed for every DETECTABLE truncation**
    /// (originally committed `#[ignore]`d as a known-red deferral to Phase 31;
    /// the operator's "fix root causes before proceeding" decision pulled it
    /// back into phase 30).
    ///
    /// A truncated terminal `result` used to vanish from the parsed events, so
    /// `last_top_level_result` returned an EARLIER turn's result — a stale
    /// SUCCESS advancing a stage whose real terminal turn failed. Now every
    /// prefix with a torn trailing line yields an indeterminate FAILURE.
    ///
    /// **The named residual — line-boundary truncation is UNDETECTABLE from
    /// content.** A prefix cut exactly at the newline after the success turn is
    /// a well-formed capture: two parsed events, no torn line, byte-identical
    /// to a healthy one-turn-success capture plus nothing. The evidence of loss
    /// is in the bytes that never arrived, so no parser assertion can exist for
    /// it. The remaining defense belongs to the layer that HAS the missing
    /// information: Phase 31's wiring must not let a stream-derived Success
    /// short-circuit a contradicting exit code (a writer that died between
    /// flushing turn N and turn N+1 also died with a non-zero exit). Recorded
    /// in ROADMAP constraint 9.
    #[test]
    fn truncation_sweep_never_upgrades_verdict_to_success() {
        let intact = format!(
            "{}\n{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN1, MARKER_SUCCESS),
            v3_result_event_is_error(V3_RESULT_TURN2, MARKER_FAILED),
        );
        assert_eq!(
            parse_claude_event_result(&intact).map(|r| r.status),
            Some(AgentStatus::Failed),
            "precondition: intact capture ends in a failure verdict"
        );

        let mut torn_prefixes = 0usize;
        let mut clean_prefixes = 0usize;
        for n in 0..=intact.len() {
            if !intact.is_char_boundary(n) {
                continue;
            }
            let prefix = &intact[..n];
            let got = parse_claude_event_result(prefix).map(|r| r.status);
            if ParsedCapture::parse(prefix).torn_json_line_present() {
                torn_prefixes += 1;
                assert_ne!(
                    got,
                    Some(AgentStatus::Success),
                    "truncating to {n} bytes left a torn tail yet resurrected \
                     an earlier turn's SUCCESS over a failed terminal turn"
                );
            } else {
                clean_prefixes += 1;
            }
        }
        // Negative controls on the sweep itself: both branches must have been
        // exercised, or the loop is asserting over nothing.
        assert!(
            torn_prefixes > 500,
            "sweep degenerated: only {torn_prefixes} torn prefixes"
        );
        assert!(
            clean_prefixes > 2,
            "sweep never produced a well-formed prefix; the residual case \
             documented above is not being exercised"
        );
    }

    #[test]
    fn codex_event_stream_parses_turn_failed() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"turn.started\"}\n",
            "{\"type\":\"item.started\",\"item\":{}}\n",
            "{\"type\":\"turn.failed\",\"error\":{\"message\":\"sandbox denied write\"}}\n",
        );
        let result = parse_codex_event_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("sandbox denied write"));
    }

    #[test]
    fn codex_turn_completed_no_marker_defers() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"turn.started\"}\n",
            "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n",
        );
        assert!(parse_codex_event_result(stdout).is_none());
    }

    /// 13-06 dogfood regression: Codex delivers the DEVFLOW_RESULT marker
    /// inside an `agent_message` item's text, never as a raw stdout line. A
    /// self-reported failure followed by a bare `turn.completed` must parse
    /// as Failed with the agent's reason — not defer to Layer 2 (which would
    /// see exit 0 and call it a success).
    #[test]
    fn codex_agent_message_marker_failed_wins_over_bare_turn_completed() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_7\",\"type\":\"agent_message\",\"text\":\"DEVFLOW_RESULT: {\\\"status\\\": \\\"failed\\\", \\\"reason\\\": \\\"interactive input unavailable\\\"}\"}}\n",
            "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n",
        );
        let result = parse_codex_event_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(
            result.reason.as_deref(),
            Some("interactive input unavailable")
        );
    }

    #[test]
    fn codex_agent_message_marker_success_short_circuits() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_2\",\"type\":\"agent_message\",\"text\":\"DEVFLOW_RESULT: {\\\"status\\\": \\\"success\\\"}\"}}\n",
            "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n",
        );
        let result = parse_codex_event_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
    }

    /// 999.107 #1: the pre-fix parser returned the `agent_message` success
    /// marker before examining the terminal event, so a stream that ended
    /// `success marker → turn.failed` was misread as Success and the stage
    /// could advance despite the terminal failure. A terminal `turn.failed`
    /// must win over any earlier success marker.
    #[test]
    fn codex_turn_failed_beats_an_earlier_success_marker() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_2\",\"type\":\"agent_message\",\"text\":\"DEVFLOW_RESULT: {\\\"status\\\": \\\"success\\\"}\"}}\n",
            "{\"type\":\"turn.failed\",\"error\":{\"message\":\"sandbox denied write\"}}\n",
        );
        let result = parse_codex_event_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("sandbox denied write"));
    }

    /// 13-06 dogfood regression: document content echoed into a JSONL event
    /// (GSD reference tables mentioning "rate limiting") must not trip the
    /// plain-text rate-limit heuristic — it returned the entire multi-KB
    /// event line as the "retry time" and that reached the desktop
    /// notification verbatim.
    #[test]
    fn detect_rate_limit_ignores_json_event_lines() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_4\",\"type\":\"command_execution\",\"aggregated_output\":\"| API keys | Rate limiting per key? |\"}}\n",
            "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n",
        );
        assert_eq!(detect_rate_limit(stdout), None);
    }

    #[test]
    fn detect_rate_limit_still_reads_codex_plain_text() {
        let stdout = "Rate limit reached.\nTry again at 3:45 PM.\n";
        assert_eq!(detect_rate_limit(stdout).as_deref(), Some("3:45 PM"));
    }

    #[test]
    fn codex_event_stream_ignores_progress_and_unparseable_lines() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "not json at all\n",
            "{\"type\":\"item.started\",\"item\":{}}\n",
            "{\"type\":\"item.updated\",\"item\":{}}\n",
            "{\"type\":\"turn.failed\",\"error\":{\"message\":\"boom\"}}\n",
        );
        let result = parse_codex_event_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("boom"));
    }

    #[test]
    fn claude_envelope_not_consumed_by_codex_parser() {
        let stdout = r#"{"type":"result","subtype":"success","is_error":false,"num_turns":4,"result":"All done.","session_id":"abc"}"#;
        assert!(parse_codex_event_result(stdout).is_none());
    }

    /// The highest-value isolation test in plan 30-01 (T-30-02).
    ///
    /// The single-document `--output-format json` envelope that ships TODAY
    /// carries `type: "result"` AND a `session_id` — precisely the gate shape
    /// 30-RESEARCH.md offered as an alternative to `system`/`init`. If anyone
    /// widens [`is_claude_event_stream`] to accept it, the stream parser starts
    /// consuming every production capture in use and silently displaces
    /// `parse_devflow_result` in the Layer-1 cascade. This test fails first.
    ///
    /// The first literal is reused verbatim from
    /// `claude_envelope_not_consumed_by_codex_parser` above so the two read as
    /// a matched pair.
    #[test]
    fn single_doc_envelope_not_consumed_by_claude_stream_parser() {
        let stdout = r#"{"type":"result","subtype":"success","is_error":false,"num_turns":4,"result":"All done.","session_id":"abc"}"#;
        assert!(parse_claude_event_result(stdout).is_none());

        // Non-vacuity: the literal above carries no marker, so it would return
        // None even from a WRONGLY-widened gate — on its own it proves little.
        // This envelope does carry one, so it can only return None because the
        // gate declined the document, not because the marker scan came up dry.
        let with_marker = r#"{"type":"result","subtype":"success","is_error":false,"num_turns":4,"result":"Done.\nDEVFLOW_RESULT: {\"status\":\"success\"}","session_id":"abc"}"#;
        assert!(parse_claude_event_result(with_marker).is_none());

        // ...and the shipped path still owns it, so declining costs no verdict.
        assert_eq!(
            parse_devflow_result(with_marker).unwrap().status,
            AgentStatus::Success
        );
    }

    /// Cross-adapter isolation: a Codex `--json` event stream is not consumed
    /// by the Claude stream parser. The two gates are mutually exclusive by
    /// construction — Codex keys on `thread.started`/`turn.*`, Claude on
    /// `system`/`init` — and this pins that.
    #[test]
    fn codex_stream_not_consumed_by_claude_stream_parser() {
        let stdout = concat!(
            "{\"type\":\"thread.started\",\"thread_id\":\"t1\"}\n",
            "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_2\",\"type\":\"agent_message\",\"text\":\"DEVFLOW_RESULT: {\\\"status\\\": \\\"success\\\"}\"}}\n",
            "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n",
        );
        assert!(parse_claude_event_result(stdout).is_none());

        // The Codex parser still decides it — isolation costs no verdict.
        assert_eq!(
            parse_codex_event_result(stdout).unwrap().status,
            AgentStatus::Success
        );
    }

    /// The same isolation claim in the other direction: a Claude stream capture
    /// is not consumed by the Codex parser, so the two never collide.
    #[test]
    fn claude_stream_not_consumed_by_codex_parser() {
        let capture = v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS);
        assert!(parse_codex_event_result(&capture).is_none());
    }

    /// Plain-text stdout is not consumed by the Claude stream parser.
    ///
    /// Non-vacuous by construction: the text carries a real marker, so a gate
    /// that wrongly fired on non-JSON input would change the verdict rather
    /// than merely returning None. The second assertion pins that the marker
    /// path still decides it — the cascade must lose nothing.
    #[test]
    fn plain_text_not_consumed_by_claude_stream_parser() {
        let stdout = "Running the plan...\nDEVFLOW_RESULT: {\"status\":\"success\"}\n";
        assert!(parse_claude_event_result(stdout).is_none());
        assert_eq!(
            parse_devflow_result(stdout).unwrap().status,
            AgentStatus::Success
        );
    }

    // ---- Claude `--output-format stream-json` fixtures (plan 30-01) --------
    //
    // Sourced from the archived capture
    // `.planning/phases/30-keep-the-session-alive-past-turn-end/30a-evidence/raw_output_v3.jsonl`,
    // a real 54-line stream from a session that survived three orchestrator
    // turns via task-notification wake-ups. The `init` event is line 5; the
    // three `result` events are lines 19, 37 and 54.
    //
    // TWO documented modifications, both labelled where they occur:
    //   1. Each envelope's `result` string value is replaced with the sentinel
    //      `__MARKER__`, which each test fills in. NO archived capture contains
    //      a real `DEVFLOW_RESULT` marker — the v3 harness produced
    //      acknowledgment prose, not GSD stage output — so every marker payload
    //      below is SYNTHETIC. Envelope shape is real; marker text is not.
    //   2. The `init` event's three inert array payloads are truncated and its
    //      `cwd` is redacted (see `V3_INIT_EVENT`).
    // Everything else is byte-for-byte as captured, including field ORDER —
    // note that `"type":"result"` appears near the END of each result line,
    // long after `result` itself, which is exactly why the parser must key on
    // the parsed object rather than on textual position.

    /// v3 line 5 — the `system`/`init` event that opens the stream and is the
    /// ONLY thing `is_claude_event_stream` gates on.
    ///
    /// Modification 2: verbatim except that `tools`, `mcp_servers` and
    /// `slash_commands` are truncated to a real prefix (verbatim they run to
    /// 5,523 characters of tool and slash-command names that no code path here
    /// reads) and `cwd` is redacted to a neutral path — the captured value
    /// embeds a developer's home directory, and `devflow-core` is published to
    /// crates.io. Both fields are inert for every function under test.
    const V3_INIT_EVENT: &str = r#"{"type":"system","subtype":"init","cwd":"/tmp/scratchpad/999.64-experiment","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","tools":["Task","Bash","Read","Write"],"mcp_servers":[{"name":"github","status":"pending"}],"model":"claude-opus-5[1m]","permissionMode":"bypassPermissions","slash_commands":["gsd-execute-phase"],"capabilities":["interrupt_receipt_v1","interrupt_cancel_queued_v1","msg_lifecycle_v1"],"uuid":"597e1613-77cb-4cdd-a716-2aa75dc58c0b"}"#;

    /// v3 line 19 — the FIRST turn's terminal `result` event.
    const V3_RESULT_TURN1: &str = r#"{"is_error":false,"duration_api_ms":8087,"num_turns":3,"stop_reason":"end_turn","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","total_cost_usd":0.2401795,"usage":{"input_tokens":4,"cache_creation_input_tokens":20120,"cache_read_input_tokens":49219,"output_tokens":574,"service_tier":"standard","inference_geo":"not_available","speed":"standard"},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","subtype":"success","api_error_status":null,"result":"__MARKER__","ttft_ms":1381,"time_to_request_ms":91,"type":"result","duration_ms":8315,"uuid":"3dce3044-2d33-4c4d-bfcb-80e1756a5522"}"#;

    /// v3 line 37 — the SECOND turn's terminal `result` event, produced after a
    /// task-notification wake-up. Carries the `origin` key the later turns have
    /// and the first does not.
    const V3_RESULT_TURN2: &str = r#"{"is_error":false,"duration_api_ms":27809,"num_turns":1,"stop_reason":"end_turn","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","total_cost_usd":0.53654625,"usage":{"input_tokens":2,"cache_creation_input_tokens":3147,"cache_read_input_tokens":35393,"output_tokens":124,"service_tier":"standard","inference_geo":"not_available","speed":"standard"},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","origin":{"kind":"task-notification"},"subtype":"success","api_error_status":null,"result":"__MARKER__","ttft_ms":5476,"time_to_request_ms":18,"type":"result","duration_ms":6195,"uuid":"ca58693c-2599-4eb6-955b-e9d1e7444255"}"#;

    /// v3 line 54 — the THIRD and LAST turn's terminal `result` event. This is
    /// the one whose marker must decide the stage.
    const V3_RESULT_TURN3: &str = r#"{"is_error":false,"duration_api_ms":39273,"num_turns":2,"stop_reason":"end_turn","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","total_cost_usd":0.6599295,"usage":{"input_tokens":4,"cache_creation_input_tokens":999,"cache_read_input_tokens":77871,"output_tokens":302,"service_tier":"standard","inference_geo":"not_available","speed":"standard"},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","origin":{"kind":"task-notification"},"subtype":"success","api_error_status":null,"result":"__MARKER__","ttft_ms":2099,"time_to_request_ms":14,"type":"result","duration_ms":5276,"uuid":"dc76186e-3e9a-4d52-9152-27aa5012bc41"}"#;

    // ---- prompt-echo regression fixtures (plan 30-05) ----------------------
    //
    // Message-event envelopes from the same archived capture. Same sentinel
    // discipline as the `result` envelopes above — the innermost text payload
    // is replaced with `__MARKER__` and each test fills it — plus a third
    // documented modification noted per constant where inert bulk is dropped.
    // The ENVELOPE is real: every `type`, `parent_tool_use_id`, `session_id`
    // and `uuid` value, and the nesting shape the extraction path walks, is
    // exactly as captured.
    //
    // NO archived capture contains checkpoint gate text at all — the 30a
    // harness prompt was about background tasks and never mentioned gates. So
    // every gate payload below is SYNTHETIC and must not be described as an
    // observed rendering. What IS observed is the gate VALUE's markdown
    // code-span rendering, transcribed from the live 2026-07-31 A1 run (see
    // `HUMAN_GATE_VALUE`), which every fixture here reproduces.

    /// v3 line 10 — a TOP-LEVEL `user` event (`parent_tool_use_id` null).
    ///
    /// Modification 3: the trailing `tool_use_result` object is dropped. It is
    /// inert for every function under test and embeds both a developer home
    /// directory and the child agent's full prompt; `devflow-core` is published
    /// to crates.io.
    ///
    /// **The archived capture contains no echoed prompt.** Every `user` event
    /// in it is a `tool_result` relay, because the 30a harness ran a single
    /// prompt with no re-injection. This fixture's payload therefore STANDS IN
    /// for an echoed prompt rather than reproducing one. The substitution is
    /// sound for what is under test: the scan's first filter keys on the
    /// event's `type`, which is `user` in both cases, and
    /// `claude_stream_reports_human_gate` excludes that whole class — an echoed
    /// prompt and a re-injected notification summary are the two members of it.
    const V3_USER_EVENT: &str = r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01FVk15W8zxiazXutJYn8rsv","type":"tool_result","content":[{"type":"text","text":"__MARKER__"}]}]},"parent_tool_use_id":null,"session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","uuid":"60c5839e-40b3-492a-83e7-00882189f1d3","timestamp":"2026-08-02T00:22:22.603Z"}"#;

    /// v3 line 6 — a TOP-LEVEL `assistant` event (`parent_tool_use_id` null).
    ///
    /// Its captured payload is `I'll spawn both subagents in the background
    /// now.` — mid-turn narration that appears in NO `result` event of the
    /// capture, re-confirmed by re-parsing all 54 lines at execution time. That
    /// property is the entire reason this envelope was chosen: it proves
    /// top-level assistant text is not merely a preview of the result text, so
    /// admitting the class would add a genuinely new trusted surface.
    ///
    /// Modification 3: the `usage.cache_creation` sub-object is dropped (inert).
    const V3_ASSISTANT_TOP_LEVEL_EVENT: &str = r#"{"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011Cdcy3oC1a4rcmbp3avDYX","type":"message","role":"assistant","content":[{"type":"text","text":"__MARKER__"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":18673,"cache_read_input_tokens":15273,"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","uuid":"85e8747b-e551-47b7-af38-fcd3bb1e06f8","timestamp":"2026-08-02T00:22:18.742Z","request_id":"req_011Cdcy3ngzpMCk3bijt1nkE"}"#;

    /// v3 line 11 — a SUBAGENT-forwarded `assistant` event. Its captured
    /// `parent_tool_use_id` (`toolu_01FVk15W8zxiazXutJYn8rsv`, the Task call
    /// that spawned child A) is preserved verbatim: it is the whole point of
    /// the fixture, and the discrimination whose absence invalidated the v1
    /// experiment outright.
    ///
    /// Modification 3: the `usage.cache_creation` sub-object is dropped (inert).
    const V3_ASSISTANT_SUBAGENT_EVENT: &str = r#"{"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011Cdcy4BNkfziogNMFM8V7K","type":"message","role":"assistant","content":[{"type":"text","text":"__MARKER__"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":17705,"cache_read_input_tokens":0,"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":"toolu_01FVk15W8zxiazXutJYn8rsv","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790","uuid":"3fb37d43-86af-48b1-ace4-55147ed47b15","timestamp":"2026-08-02T00:22:23.850Z","request_id":"req_011Cdcy4ASSvG8gf8fRwiWZW","subagent_type":"general-purpose","task_description":"Signal A after 10s"}"#;

    /// Fill a message envelope's innermost text payload. Mirrors
    /// [`v3_result_event`] and is kept separate from it so the assertion names
    /// the right fixture family when a sentinel is lost.
    fn v3_message_event(envelope: &str, text: &str) -> String {
        assert!(
            envelope.contains("__MARKER__"),
            "fixture envelope lost its message-text sentinel"
        );
        envelope.replace("__MARKER__", text)
    }

    /// A checkpoint DECLARATION, as an agent's final message would render it,
    /// escaped for a JSON string field (literal `\n`, the way `claude` emits
    /// an agent's result text).
    ///
    /// The gate value carries the markdown CODE SPAN the live 2026-07-31 run
    /// captured — see [`HUMAN_GATE_VALUE`]. A bare unquoted value would test a
    /// rendering that has never been observed in production.
    fn gate_declaration_text() -> String {
        format!(
            "## CHECKPOINT REACHED\\n\\n**Type:** decision\\n**Gate:** `{HUMAN_GATE_VALUE}`\\n**Plan:** 30-05\\n"
        )
    }

    /// Text that merely DOCUMENTS a gate rendering — the shape a plan file, a
    /// GSD reference document, or an agent narrating its next task carries.
    /// Same code-span rendering as a real declaration, which is precisely why a
    /// substring scan cannot tell the two apart and the EVENT must decide.
    ///
    /// Single line, no double quotes, so it drops into a JSON string field
    /// without further escaping.
    fn gate_documenting_text() -> String {
        format!(
            "The next task is declared **Gate:** `{HUMAN_GATE_VALUE}` in the plan, so the executor must stop rather than auto-select."
        )
    }

    // Synthetic `result`-text payloads (modification 1). Written exactly as
    // they appear INSIDE the envelope's `result` JSON string — escaped quotes
    // and an escaped newline — because that is how `claude` emits an agent's
    // final message. Once serde decodes the field the `\n` becomes a real
    // newline and `parse_marker_lines`' line scan works on it unmodified.
    const MARKER_SUCCESS: &str = r#"Plan complete.\nDEVFLOW_RESULT: {\"status\":\"success\"}"#;
    const MARKER_FAILED: &str =
        r#"Blocked.\nDEVFLOW_RESULT: {\"status\":\"failed\",\"reason\":\"earlier turn aborted\"}"#;
    const MARKER_PLANTED_LAYER: &str =
        r#"Done.\nDEVFLOW_RESULT: {\"status\":\"success\",\"decided_by_layer\":0}"#;
    const NO_MARKER: &str = r#"Acknowledged; nothing to report."#;

    /// Fill one real envelope's `result` field with a synthetic payload.
    fn v3_result_event(envelope: &str, escaped_result_text: &str) -> String {
        assert!(
            envelope.contains("__MARKER__"),
            "fixture envelope lost its result-text sentinel"
        );
        envelope.replace("__MARKER__", escaped_result_text)
    }

    /// Assemble a three-turn Claude stream capture: the real `init` event
    /// followed by all three real `result` envelopes, each carrying the given
    /// payload. Three result events (not two) is load-bearing — a two-event
    /// fixture cannot tell "last wins" apart from "highest index of two".
    fn v3_stream_capture(turn1: &str, turn2: &str, turn3: &str) -> String {
        format!(
            "{}\n{}\n{}\n{}\n",
            V3_INIT_EVENT,
            v3_result_event(V3_RESULT_TURN1, turn1),
            v3_result_event(V3_RESULT_TURN2, turn2),
            v3_result_event(V3_RESULT_TURN3, turn3),
        )
    }

    // ---- rate-limit / envelope-failure fixtures (plan 30-03) --------------

    /// v3 line 15, **VERBATIM** — the only `rate_limit_event` in any archived
    /// capture, and the reason this plan exists in its current form.
    ///
    /// Read it before touching [`detect_claude_stream_rate_limit`]: its
    /// `rate_limit_info.status` is **`allowed`**. The CLI emits these events as
    /// routine quota telemetry on healthy streams — this one sits at line 15 of
    /// a capture that then completed three turns successfully (results at 19,
    /// 37 and 54). Presence of the event type carries NO information about
    /// whether the run was blocked.
    ///
    /// Note the second trap one level down: `overageStatus` is `rejected`. Any
    /// nested search for the token `rejected` (e.g. via [`json_find_key`]) also
    /// misclassifies this healthy event, which is why the classifier reads
    /// `rate_limit_info.status` and nothing else, by direct `.get()`.
    const V3_RATE_LIMIT_EVENT_ALLOWED: &str = r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1785645600,"rateLimitType":"five_hour","overageStatus":"rejected","overageDisabledReason":"out_of_credits","isUsingOverage":false},"uuid":"e73e6774-a79d-4cdf-90bd-53a695f44f5a","session_id":"559fef4d-2053-459e-b7a7-f3200c3b3790"}"#;

    /// A `rate_limit_event` with the given `rate_limit_info.status`, built by
    /// substituting one field of the real archived event above.
    ///
    /// **SYNTHETIC for every status except `allowed`.** No archived capture
    /// contains a blocked stream — the denial fixtures below are constructed,
    /// not observed, and are labelled as such at each use. Every other field
    /// (including `resetsAt`, which supplies the retry hint) is exactly as
    /// captured.
    fn v3_rate_limit_event(status: &str) -> String {
        assert!(
            V3_RATE_LIMIT_EVENT_ALLOWED.contains(r#""status":"allowed""#),
            "fixture lost its status field"
        );
        V3_RATE_LIMIT_EVENT_ALLOWED
            .replace(r#""status":"allowed""#, &format!(r#""status":"{status}""#))
    }

    /// One real `result` envelope with its captured `is_error":false` flipped
    /// to `true`, every other field untouched. The assertion makes the
    /// substitution non-silent: if the fixture text ever changes, the test
    /// fails loudly rather than quietly testing an `is_error: false` envelope.
    fn v3_result_event_is_error(envelope: &str, escaped_result_text: &str) -> String {
        let filled = v3_result_event(envelope, escaped_result_text);
        assert!(
            filled.contains(r#""is_error":false"#),
            "fixture envelope lost its is_error field"
        );
        filled.replace(r#""is_error":false"#, r#""is_error":true"#)
    }

    /// Assemble a capture from the real `init` event followed by the given
    /// lines in order. Unlike [`v3_stream_capture`] this lets a test position a
    /// `rate_limit_event` at an arbitrary index, which is the whole point of
    /// the final-turn scoping assertions.
    fn stream_capture_of(lines: &[&str]) -> String {
        let mut out = String::from(V3_INIT_EVENT);
        for line in lines {
            out.push('\n');
            out.push_str(line);
        }
        out.push('\n');
        out
    }

    /// **The mandatory negative regression.** The real archived stream — whose
    /// `rate_limit_event` says `status: "allowed"` and which then completed
    /// three turns — must NOT classify as `RateLimited`.
    ///
    /// This event is routine quota telemetry, not a block. Classifying its mere
    /// presence as a rate limit would route EVERY healthy Claude stream stage
    /// into `Action::AutoResume` against a fabricated retry time, instead of
    /// advancing the pipeline. That mapping is
    /// `crates/devflow-core/src/outcome_policy.rs:41` — `AgentStatus::RateLimited
    /// => Action::AutoResume`, re-read in this crate at execution time; 30-03's
    /// plan and threat register cite it as `outcome_policy.rs:41` without a
    /// crate, and it is NOT in `devflow-cli`. This is a denial of service on
    /// the whole product, produced by a one-line "detect the event type"
    /// shortcut.
    ///
    /// Two independent guards must both hold here, and the second assertion
    /// pins the one the positioning guard alone would hide: the event is placed
    /// at its real position (before the first `result`, mirroring line 15 vs
    /// 19), AND its status is not a denial. `detect_claude_stream_rate_limit`
    /// is asserted directly on a final-turn placement of the same real event so
    /// the status guard cannot be dropped without this test failing.
    #[test]
    fn claude_stream_real_allowed_rate_limit_event_is_not_rate_limited() {
        let capture = stream_capture_of(&[
            V3_RATE_LIMIT_EVENT_ALLOWED,
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);

        let result = parse_claude_event_result(&capture)
            .expect("the final turn's success marker still decides this stream");
        assert_eq!(result.status, AgentStatus::Success);
        assert_ne!(result.status, AgentStatus::RateLimited);

        // The status guard on its own: the SAME real event moved into the final
        // turn (after the second-to-last `result`) is still not a rate limit.
        // Without this, deleting the status check would leave the test green.
        let final_turn = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            V3_RATE_LIMIT_EVENT_ALLOWED,
            &v3_result_event(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);
        assert!(
            detect_claude_stream_rate_limit(&ParsedCapture::parse(&final_turn).events).is_none()
        );
    }

    /// The positive: an explicit quota DENIAL inside the final turn classifies
    /// as `RateLimited`, so the rate-limit resume path stays reachable under
    /// `stream-json`.
    ///
    /// **The denial fixture is SYNTHETIC.** No archived capture contains a
    /// blocked stream, so the `rejected` status is constructed from the
    /// observed vocabulary of this schema rather than observed in the wild —
    /// the same honest-fixture rule this phase applies to marker payloads. The
    /// retry hint comes from the real `resetsAt` value.
    #[test]
    fn claude_stream_final_turn_denial_rate_limit_event_is_rate_limited() {
        let denial = v3_rate_limit_event("rejected");
        let capture = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &denial,
            &v3_result_event(V3_RESULT_TURN3, NO_MARKER),
        ]);

        let result = parse_claude_event_result(&capture)
            .expect("a final-turn quota denial must produce a Layer-1 verdict");
        assert_eq!(result.status, AgentStatus::RateLimited);
        assert_eq!(
            result.reason.as_deref(),
            Some("rate limited until 1785645600")
        );
        assert_eq!(result.decided_by_layer, Some(1));

        // Fewer than two `result` events means the whole stream IS the final
        // turn — a run blocked before it ever completed a turn must still
        // classify, or the boundary logic silently swallows the common case.
        let single_turn =
            stream_capture_of(&[&denial, &v3_result_event(V3_RESULT_TURN1, NO_MARKER)]);
        assert_eq!(
            parse_claude_event_result(&single_turn).map(|r| r.status),
            Some(AgentStatus::RateLimited)
        );
    }

    /// Scoping: a denial that predates the final turn cannot outrank the final
    /// turn's own outcome. Rate-limit chatter from an earlier turn must not
    /// decide a stream that later completed — in the real capture the rate
    /// event (line 15) precedes all three results, so an unscoped detector
    /// would let a first-turn event decide a stream that finished forty seconds
    /// later.
    ///
    /// The denial status here is the SAME one the positive test proves does
    /// classify, so this test can only pass because of the POSITION guard.
    #[test]
    fn claude_stream_denial_before_final_turn_does_not_outrank_final_result() {
        let capture = stream_capture_of(&[
            &v3_rate_limit_event("rejected"),
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);

        let result = parse_claude_event_result(&capture)
            .expect("the final turn's success marker decides this stream");
        assert_eq!(result.status, AgentStatus::Success);
    }

    /// An unrecognised `rate_limit_info.status` DEFERS rather than classifying.
    ///
    /// Deferring is the deliberately safe direction: an unknown denial status
    /// falls through to the envelope/marker paths and is reported `Failed` — a
    /// real degradation (the operator loses automatic resume) but a never-silent
    /// one that still gates. The opposite error auto-resumes a healthy stream
    /// against a retry time the parser invented.
    ///
    /// Positioned in the FINAL turn, so only the status check can decline it.
    #[test]
    fn claude_stream_unrecognised_rate_limit_status_defers() {
        let capture = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_rate_limit_event("some_future_status"),
            &v3_result_event(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);

        assert!(detect_claude_stream_rate_limit(&ParsedCapture::parse(&capture).events).is_none());
        let result = parse_claude_event_result(&capture)
            .expect("the parser must fall through to the marker path");
        assert_eq!(result.status, AgentStatus::Success);
    }

    /// Precedence (T-30-13): when the detector fires, rate limit outranks the
    /// marker path. A rate-limited run classified as generic `Failed` kills the
    /// primary rate-limit resume cron — the one path that exists to recover
    /// from it — which is exactly why `evaluate_layer1` already orders
    /// `detect_claude_rate_limit` ahead of `detect_claude_envelope_failure` for
    /// the single-document path.
    ///
    /// Non-vacuous: the same capture WITHOUT the rate event yields `Failed`, so
    /// this test fails the moment the ordering is reshuffled.
    #[test]
    fn claude_stream_final_turn_denial_outranks_failed_marker() {
        let with_denial = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_rate_limit_event("rejected"),
            &v3_result_event(V3_RESULT_TURN3, MARKER_FAILED),
        ]);
        assert_eq!(
            parse_claude_event_result(&with_denial).map(|r| r.status),
            Some(AgentStatus::RateLimited)
        );

        let without_denial = v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_FAILED);
        assert_eq!(
            parse_claude_event_result(&without_denial).map(|r| r.status),
            Some(AgentStatus::Failed)
        );
    }

    /// A last `result` event with `is_error: true` and NO marker is an
    /// authoritative Layer-1 failure, not a deferral to Layer 2's coarse
    /// exit-code heuristic — matching `detect_claude_envelope_failure` for the
    /// single-document envelope. The reason is drawn from the event's own
    /// `result` text with the `num_turns` suffix, the same shape that function
    /// produces.
    #[test]
    fn claude_stream_last_result_is_error_without_marker_is_failed() {
        let capture = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_result_event_is_error(V3_RESULT_TURN3, r#"Execution error: context exhausted"#),
        ]);

        let result = parse_claude_event_result(&capture)
            .expect("is_error on the last result must not defer to Layer 2");
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(
            result.reason.as_deref(),
            Some("Execution error: context exhausted (num_turns: 2)")
        );
        assert_eq!(result.decided_by_layer, Some(1));
    }

    /// Envelope-over-marker (T-30-15): `is_error: true` overrides a SUCCESS
    /// marker in the same event, matching `detect_claude_envelope_failure`'s
    /// documented precedence over a stale or echoed success marker.
    ///
    /// Non-vacuous: the identical capture with `is_error: false` yields
    /// `Success`, so the assertion below can only pass because the envelope
    /// check overrode the marker.
    #[test]
    fn claude_stream_is_error_overrides_success_marker() {
        let capture = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            &v3_result_event_is_error(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);
        let result = parse_claude_event_result(&capture)
            .expect("is_error must produce a verdict even with a success marker");
        assert_eq!(result.status, AgentStatus::Failed);

        let healthy = v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS);
        assert_eq!(
            parse_claude_event_result(&healthy).map(|r| r.status),
            Some(AgentStatus::Success)
        );
    }

    // ---- session id from a stream capture (plan 30-03 Task 2) -------------

    /// The single `session_id` every event in the archived v3 capture carries —
    /// all three `init` events (lines 5, 32 and 47) and all three `result`
    /// events agree on it, confirmed by reading the capture.
    const V3_SESSION_ID: &str = "559fef4d-2053-459e-b7a7-f3200c3b3790";

    /// The real `init` event with its `session_id` substituted. Used only to
    /// build a SYNTHETIC mid-stream rotation — no archived capture rotates.
    fn v3_init_event_with_session(session_id: &str) -> String {
        assert!(
            V3_INIT_EVENT.contains(V3_SESSION_ID),
            "fixture lost its session_id"
        );
        V3_INIT_EVENT.replace(V3_SESSION_ID, session_id)
    }

    /// `claude_stream_session_id` reads the CLI-emitted id out of a JSONL
    /// capture built from the archived `init` events (v3 lines 5, 32 and 47 —
    /// all three carry this same value).
    ///
    /// The second half pins LAST-init-wins with a synthetic rotation: the real
    /// capture's three `init` events are identical, so first-wins and last-wins
    /// agree on today's evidence and a fixture built only from it cannot tell
    /// the two apart. Three `init` events do NOT mean three sessions.
    #[test]
    fn claude_stream_session_id_reads_cli_emitted_init_value() {
        let capture = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            V3_INIT_EVENT,
            &v3_result_event(V3_RESULT_TURN2, NO_MARKER),
            V3_INIT_EVENT,
            &v3_result_event(V3_RESULT_TURN3, MARKER_SUCCESS),
        ]);
        assert_eq!(
            claude_stream_session_id(&capture).as_deref(),
            Some(V3_SESSION_ID)
        );

        let rotated = stream_capture_of(&[
            &v3_result_event(V3_RESULT_TURN1, NO_MARKER),
            &v3_init_event_with_session("second-session-id"),
            &v3_result_event(V3_RESULT_TURN2, MARKER_SUCCESS),
        ]);
        assert_eq!(
            claude_stream_session_id(&rotated).as_deref(),
            Some("second-session-id")
        );
    }

    /// D-04 / T-28-04 forgery guard for the stream path — the analog of
    /// `session_id_in_devflow_result_marker_is_not_returned`, which pins the
    /// same contract for the single-document envelope.
    ///
    /// The fixture defeats BOTH plausible wrong implementations at once: a
    /// nested traversal (`json_find_key`/`json_scan`) would reach the
    /// `session_id` the agent planted inside its own `DEVFLOW_RESULT` marker
    /// text, and a "last event carrying a `session_id`" scan would return the
    /// final `result` event's own key. Both are wrong; only the `init` event's
    /// top-level value is CLI-emitted. The divergence between the `result`
    /// event's id and the `init` event's is synthetic — no archived capture
    /// diverges — and exists purely so those two implementations cannot pass.
    #[test]
    fn claude_stream_session_id_ignores_agent_planted_value() {
        const PLANTED_MARKER: &str =
            r#"Done.\nDEVFLOW_RESULT: {\"status\":\"success\",\"session_id\":\"forged-by-agent\"}"#;

        let last_result = v3_result_event(V3_RESULT_TURN3, PLANTED_MARKER)
            .replace(V3_SESSION_ID, "result-event-session-id");
        let capture =
            stream_capture_of(&[&v3_result_event(V3_RESULT_TURN1, NO_MARKER), &last_result]);

        // Non-vacuity: both decoys really are present in the capture text, so a
        // wrong implementation has something wrong to find.
        assert!(capture.contains("forged-by-agent"));
        assert!(capture.contains("result-event-session-id"));

        assert_eq!(
            claude_stream_session_id(&capture).as_deref(),
            Some(V3_SESSION_ID)
        );
    }

    /// The stream reader does not shadow or duplicate `claude_session_id`: it
    /// declines the single-document envelope (the exact literal
    /// `session_id_reads_top_level_string` asserts on) and plain text, so the
    /// wrapper's stream-first ordering cannot change today's behavior.
    #[test]
    fn claude_stream_session_id_declines_non_stream_shapes() {
        let envelope = r#"{"type":"result","subtype":"success","result":"All done.","session_id":"cf29bfec-69e8-45df-a4f3-3da08ab6f66e"}"#;
        assert!(claude_stream_session_id(envelope).is_none());
        // ...and the shipped reader still owns it, so declining costs nothing.
        assert_eq!(
            claude_session_id(envelope).as_deref(),
            Some("cf29bfec-69e8-45df-a4f3-3da08ab6f66e")
        );

        assert!(claude_stream_session_id("just some plain text output\n").is_none());
    }

    /// The wiring that matters: `session_id_from_capture` — the Phase 28
    /// checkpoint-resume reader (`claude --resume` needs an id DevFlow can
    /// read) — returns an id for a JSONL capture, where before this plan it
    /// returned `None` for every stream capture.
    #[test]
    fn claude_stream_session_id_from_capture_reads_jsonl() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(30)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS),
        )
        .unwrap();

        assert_eq!(
            session_id_from_capture(dir.path(), PhaseId::new(30)).as_deref(),
            Some(V3_SESSION_ID)
        );
    }

    /// The other half of the wiring claim: a single-document envelope capture
    /// still yields exactly what it did before the stream reader was inserted
    /// ahead of `claude_session_id` in the fallback chain.
    #[test]
    fn claude_stream_wiring_leaves_single_document_capture_unchanged() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let envelope = r#"{"type":"result","subtype":"success","result":"All done.","session_id":"cf29bfec-69e8-45df-a4f3-3da08ab6f66e"}"#;
        std::fs::write(stdout_path(dir.path(), PhaseId::new(8)), envelope).unwrap();

        assert_eq!(
            session_id_from_capture(dir.path(), PhaseId::new(8)).as_deref(),
            claude_session_id(envelope).as_deref()
        );
        assert_eq!(
            session_id_from_capture(dir.path(), PhaseId::new(8)).as_deref(),
            Some("cf29bfec-69e8-45df-a4f3-3da08ab6f66e")
        );
    }

    /// The tracer: a real archived `stream-json` capture written to
    /// `.devflow/phase-NN-stdout` produces a Layer-1 verdict out of
    /// `evaluate_layer1`. Before plan 30-01 this returned `None` for every
    /// JSONL capture — `serde_json::from_str` on the whole multi-line document
    /// is a hard "trailing characters" error, so all four single-document
    /// parsers declined it and the stage fell through to Layer 2's coarse
    /// exit-code+commit heuristic.
    ///
    /// Fixture provenance and its two modifications are documented on
    /// `V3_INIT_EVENT` / `V3_RESULT_TURN1..3` above.
    #[test]
    fn evaluate_layer1_parses_claude_stream_capture() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(30)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS),
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(30)).unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(1));

        // Non-vacuity guard for the assertion above: this marker omits
        // `decided_by_layer`, and the field is `#[serde(default)]`, so
        // `parse_marker_lines` alone yields `None`. `Some(1)` can therefore
        // only have come from the parser's explicit overwrite.
        assert_eq!(
            parse_marker_lines(r#"DEVFLOW_RESULT: {"status":"success"}"#)
                .unwrap()
                .decided_by_layer,
            None
        );
    }

    // ---- idle-timeout side channel (31-02, D-05/D-06/D-07) ---------------

    /// Write a monitor-shaped idle-timeout record. Field names and types match
    /// `IdleTimeoutRecord` exactly; the monitor writes it via serde, so a drift
    /// between the two shows up as a failing deserialize here.
    fn write_idle_timeout_record(root: &Path, phase: PhaseId, commits: &[(&str, &str)]) {
        let record = IdleTimeoutRecord {
            status: AgentStatus::IdleTimeout.as_wire_str().to_string(),
            idle_secs: 30,
            agent_pid: 4242,
            written_at: 1_700_000_000,
            commits: commits
                .iter()
                .map(|(sha, subject)| IdleTimeoutCommit {
                    sha: (*sha).to_string(),
                    subject: (*subject).to_string(),
                })
                .collect(),
        };
        std::fs::write(
            idle_timeout_path(root, phase),
            serde_json::to_string(&record).unwrap(),
        )
        .unwrap();
    }

    /// T-31-06, and the single most important test in plan 31-02.
    ///
    /// The fixture is a REAL archived three-turn capture in which every
    /// top-level `result` event carries a success marker — the normal shape of
    /// a run that got far enough to idle out. A fixture without a prior
    /// `result` event would pass vacuously while the same mechanism silently
    /// failed in production.
    ///
    /// The negative control is encoded INSIDE the test rather than described in
    /// prose: the same fixture is evaluated first WITHOUT the side channel and
    /// must return `Success`. If that ever stops holding, the `IdleTimeout`
    /// assertion below is proving a verdict nothing was competing with.
    #[test]
    fn idle_timeout_side_channel_wins_over_stale_stream_result() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(40)),
            v3_stream_capture(MARKER_SUCCESS, MARKER_SUCCESS, MARKER_SUCCESS),
        )
        .unwrap();

        // NEGATIVE CONTROL — must produce the OPPOSITE result.
        assert_eq!(
            evaluate_layer1(dir.path(), PhaseId::new(40))
                .unwrap()
                .status,
            AgentStatus::Success,
            "negative control: without the side channel this fixture must decide Success, \
             otherwise the assertion below is vacuous"
        );

        write_idle_timeout_record(
            dir.path(),
            PhaseId::new(40),
            &[("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "feat: partial")],
        );

        let result = evaluate_layer1(dir.path(), PhaseId::new(40)).unwrap();
        assert_eq!(
            result.status,
            AgentStatus::IdleTimeout,
            "a stale success already in the capture must not shadow the monitor's verdict"
        );
        assert_eq!(result.decided_by_layer, Some(1));
    }

    /// The read must precede `read_capture`'s early `return None`, so a
    /// timeout that fired before the child emitted anything at all is still
    /// authoritative rather than discarded.
    #[test]
    fn idle_timeout_side_channel_is_read_even_when_the_capture_is_missing() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        assert!(
            !stdout_path(dir.path(), PhaseId::new(41)).exists(),
            "fixture precondition: there must be no capture at all"
        );

        // NEGATIVE CONTROL: with neither file present Layer 1 abstains, so the
        // verdict below can only have come from the side channel.
        assert!(evaluate_layer1(dir.path(), PhaseId::new(41)).is_none());

        write_idle_timeout_record(dir.path(), PhaseId::new(41), &[]);

        let result = evaluate_layer1(dir.path(), PhaseId::new(41)).unwrap();
        assert_eq!(result.status, AgentStatus::IdleTimeout);
        assert_eq!(result.commits, Some(0));
    }

    /// D-07: the verdict names the commits, and says they were not rolled back.
    #[test]
    fn idle_timeout_result_carries_the_commits_it_enumerated() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        write_idle_timeout_record(
            dir.path(),
            PhaseId::new(42),
            &[
                ("1111111abcdef0000000000000000000000000000", "feat: first"),
                ("2222222abcdef0000000000000000000000000000", "fix: second"),
            ],
        );

        let result = evaluate_layer1(dir.path(), PhaseId::new(42)).unwrap();

        assert_eq!(result.commits, Some(2));
        let reason = result.reason.expect("an idle timeout must explain itself");
        for fragment in [
            "1111111",     // short sha, first commit
            "feat: first", // its subject
            "2222222",
            "fix: second",
            "30s",                           // how long the stream was silent
            "NONE of them were rolled back", // D-07's non-destruction promise
        ] {
            assert!(
                reason.contains(fragment),
                "reason must name {fragment:?}; got: {reason}"
            );
        }
        // The full sha must not be what is printed — a 40-char sha in a gate
        // message is noise, and the short form is what an operator pastes.
        assert!(!reason.contains("1111111abcdef0000000000000000000000000000"));
    }

    /// Nothing about the pre-existing cascade changes when no timeout fired.
    /// Three shapes, each asserted against the verdict it produced before this
    /// plan existed, with the side channel confirmed absent in every one.
    #[test]
    fn absent_side_channel_leaves_the_cascade_unchanged() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();

        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(43)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS),
        )
        .unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(44)),
            v3_stream_capture(MARKER_SUCCESS, MARKER_SUCCESS, MARKER_FAILED),
        )
        .unwrap();

        for (phase, expected) in [
            (PhaseId::new(43), Some(AgentStatus::Success)),
            (PhaseId::new(44), Some(AgentStatus::Failed)),
            (PhaseId::new(45), None), // no capture, no side channel
        ] {
            assert!(
                !idle_timeout_path(dir.path(), phase).exists(),
                "fixture precondition: phase {phase} must have no side channel"
            );
            assert_eq!(
                evaluate_layer1(dir.path(), phase).map(|r| r.status),
                expected,
                "the cascade changed for phase {phase} with no timeout on disk"
            );
        }
    }

    /// The file's PRESENCE is the signal; its contents are enrichment.
    ///
    /// A corrupt record must NOT fall back into the cascade — that would let
    /// the stale success in the capture win, converting a damaged file into a
    /// silent wrong advance. This is the same fixture as
    /// `idle_timeout_side_channel_wins_over_stale_stream_result`, so the
    /// Success it would otherwise decide is real and not hypothetical.
    #[test]
    fn an_unreadable_idle_timeout_record_still_produces_the_verdict() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(46)),
            v3_stream_capture(MARKER_SUCCESS, MARKER_SUCCESS, MARKER_SUCCESS),
        )
        .unwrap();

        // NEGATIVE CONTROL: this capture decides Success on its own.
        assert_eq!(
            evaluate_layer1(dir.path(), PhaseId::new(46))
                .unwrap()
                .status,
            AgentStatus::Success
        );

        std::fs::write(
            idle_timeout_path(dir.path(), PhaseId::new(46)),
            "{ this is not json",
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(46)).unwrap();
        assert_eq!(result.status, AgentStatus::IdleTimeout);
        assert_eq!(
            result.commits, None,
            "an unreadable record must not invent a commit count"
        );
        assert!(result.reason.unwrap().contains("unreadable"));
    }

    /// Last-result-wins. A session kept alive across turns emits one `result`
    /// event per turn; only the final one is the session's verdict.
    ///
    /// Asserts BOTH directions so the test cannot pass by a parser that merely
    /// prefers `success`: failed-then-success yields Success, and
    /// success-then-failed yields Failed. The middle event carries the same
    /// payload as the first, so a parser that stopped at index 1 would also
    /// fail.
    #[test]
    fn claude_stream_last_result_event_wins_over_earlier_results() {
        let last_success = v3_stream_capture(MARKER_FAILED, MARKER_FAILED, MARKER_SUCCESS);
        let result = parse_claude_event_result(&last_success).unwrap();
        assert_eq!(result.status, AgentStatus::Success);

        let last_failed = v3_stream_capture(MARKER_SUCCESS, MARKER_SUCCESS, MARKER_FAILED);
        let result = parse_claude_event_result(&last_failed).unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("earlier turn aborted"));
    }

    /// T-30-26: `decided_by_layer` is provenance, not decoration.
    /// `crates/devflow-cli/src/pipeline_outcomes.rs` (`classify_validate_outcome`)
    /// computes `external = decided_by_layer == Some(0) && status == Success`
    /// and uses it to tell an externally-probe-verified Validate stage apart
    /// from an ordinary one. An agent that writes `"decided_by_layer": 0` into
    /// its own marker is claiming a Layer-0 probe provenance it did not earn,
    /// so the stream parser overwrites the field unconditionally.
    ///
    /// This is a runtime assertion on the returned struct, not a source grep —
    /// it fails the moment the overwrite is dropped.
    #[test]
    fn claude_stream_overwrites_agent_planted_decided_by_layer() {
        // Non-vacuity guard: prove the planted value really would survive
        // deserialization, so the `Some(1)` below is the overwrite at work and
        // not an artifact of a marker that failed to parse.
        assert_eq!(
            parse_marker_lines(r#"DEVFLOW_RESULT: {"status":"success","decided_by_layer":0}"#)
                .unwrap()
                .decided_by_layer,
            Some(0)
        );

        let capture = v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_PLANTED_LAYER);
        let result = parse_claude_event_result(&capture).unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(1));
    }

    /// A marker-less final turn defers to Layer 2 rather than reporting an
    /// unconditional Success — the same convention `parse_codex_event_result`
    /// applies to a bare `turn.completed`. A marker-less turn must never
    /// silently advance a stage.
    ///
    /// The FIRST turn carries a success marker, so this also proves the parser
    /// does not fall back to an earlier turn's marker when the last one has
    /// none.
    ///
    /// Plan 30-03 addendum: the deferral must hold specifically for
    /// `is_error: false`, which is what the real captured envelope carries —
    /// asserted below so this reads as a deliberate is_error case rather than
    /// an incidental one. Only `is_error: true` may promote a marker-less turn
    /// to `Failed`.
    #[test]
    fn claude_stream_last_result_without_marker_defers() {
        let capture = v3_stream_capture(MARKER_SUCCESS, NO_MARKER, NO_MARKER);
        assert!(
            capture.contains(r#""is_error":false"#),
            "the archived envelopes carry is_error:false; this test is about that case"
        );
        assert!(parse_claude_event_result(&capture).is_none());
    }

    #[test]
    fn evaluate_layer1_reports_rate_limited_without_marker() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(7)),
            r#"{"type":"result","subtype":"error_rate_limit","retry_after":"2026-06-18T15:45:30Z"}"#,
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(7)).unwrap();

        assert_eq!(result.status, AgentStatus::RateLimited);
        assert_eq!(
            result.reason.as_deref(),
            Some("rate limited until 2026-06-18T15:45:30Z")
        );
    }

    /// A real Claude rate-limit envelope carries `is_error: true` alongside
    /// `subtype: "error_rate_limit"`. The specific RateLimited classification
    /// must outrank the generic is_error → Failed path, or the primary
    /// rate-limit resume cron never triggers for the exact case it exists for.
    #[test]
    fn evaluate_layer1_rate_limit_envelope_with_is_error_is_rate_limited() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(7)),
            r#"{"type":"result","subtype":"error_rate_limit","is_error":true,"retry_after":"2026-06-18T15:45:30Z"}"#,
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(7)).unwrap();

        assert_eq!(result.status, AgentStatus::RateLimited);
        assert_eq!(
            result.reason.as_deref(),
            Some("rate limited until 2026-06-18T15:45:30Z")
        );
    }

    /// CR-01 (13-REVIEW.md) completion: the monitor path writes raw agent
    /// bytes to the stdout file via sh redirection, so evaluate_layer1 must
    /// tolerate invalid UTF-8 rather than silently disabling all Layer-1
    /// detection (the blocking-mode capture was fixed; the file read here is
    /// the other half of the same bug).
    #[test]
    fn evaluate_layer1_finds_marker_despite_invalid_utf8_bytes() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut bytes = b"progress \xff\xfe garbage\n".to_vec();
        bytes.extend_from_slice(
            b"DEVFLOW_RESULT: {\"status\":\"failed\",\"reason\":\"review: bad\"}\n",
        );
        std::fs::write(stdout_path(dir.path(), PhaseId::new(5)), bytes).unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(5)).unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("review: bad"));
    }

    #[test]
    fn failing_external_probe_outranks_success_marker() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir
            .path()
            .join(".planning/phases/16-pipeline-reliability-hardening");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-03-PLAN.md"),
            "---\nphase: 16\nexternal_verify: \"test -f externally-shipped\"\n---\n",
        )
        .unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\"}\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16));

        let approval = vec!["test -f externally-shipped".to_string()];
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert!(
            result
                .reason
                .as_deref()
                .is_some_and(|reason| reason.contains("external verification failed"))
        );
    }

    /// D-05 gap 1 / D-06 (17-03): Layer 0 now evaluates on every stage, not
    /// only Code.
    ///
    /// This is the MAIN-CHECKOUT MIRROR of
    /// `external_probe_discovers_from_the_worktree_when_the_main_checkout_lacks_the_plan`,
    /// and the two must be read together: with no worktree set, discovery and
    /// probe execution resolve to the SAME root, so 999.76's relocation of
    /// discovery to `execution_root` provably leaves this path untouched.
    /// Without this mirror the worktree fixture alone could not distinguish
    /// "discovery reads the execution root" from "discovery reads any root
    /// that happens to hold the PLAN".
    ///
    /// It previously set `state.worktree_path` and asserted the opposite
    /// direction — that discovery must read `project_root` while probes run in
    /// the worktree (review Plan 03 MEDIUM, OpenCode). 999.76 overturned that
    /// premise (see [`evaluate_layer0`]'s doc comment), so the fixture was
    /// converted rather than deleted: every assertion below is the original
    /// one, including the `"external verification failed"` reason text and the
    /// final `Success` assertion. Only the two roots' coincidence changed.
    #[test]
    fn external_probe_discovers_from_project_root_across_every_stage_without_a_worktree() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f implemented\"\n---\n",
        )
        .unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\"}\n",
        )
        .unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        // No worktree: `execution_root` falls back to `project_root`, so
        // discovery and probe execution read the same directory.
        state.worktree_path = None;
        state.stage = Stage::Plan;

        let approval = vec!["test -f implemented".to_string()];

        // Layer 0 now fires on Plan too — the probe file does not yet exist,
        // so this must fail on the probe itself (NOT a false PLAN-removed
        // veto, which would mean discovery silently returned zero commands).
        let plan_result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(plan_result.status, AgentStatus::Failed);
        assert!(
            plan_result
                .reason
                .as_deref()
                .is_some_and(|reason| reason.contains("external verification failed")),
            "expected a failing-probe reason, not a false PLAN-removed veto: {:?}",
            plan_result.reason
        );

        state.stage = Stage::Code;
        let code_result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(code_result.status, AgentStatus::Failed);

        // The probe executes against execution_root, which without a worktree
        // IS project_root — the coincidence this mirror exists to pin.
        std::fs::write(dir.path().join("implemented"), "done").unwrap();
        let passing = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(passing.status, AgentStatus::Success);
        assert_eq!(passing.decided_by_layer, Some(0));
    }

    /// 999.76 (ROADMAP criterion 6): the INVERSE of the fixture above. The
    /// PLAN lives only under the worktree and `project_root`'s own
    /// `.planning/phases/` is absent entirely — which is what an in-flight
    /// phase actually looks like. `.planning/` is tracked content, so a phase's
    /// `{N}-PLAN.md` sits on `feature/phase-{N}` INSIDE the worktree and is
    /// absent from the main checkout for the phase's whole duration.
    ///
    /// The live provenance measurement for that layout claim is **NC-7**,
    /// recorded in this phase's `34-04-SUMMARY.md`: `git ls-tree -r develop`
    /// vs `git ls-tree -r HEAD` over `.planning/phases`, reported with both
    /// refs' counts. NC-7 is evidence that the layout manufactured here is the
    /// real one — it says nothing about whether this code is correct. That
    /// claim is carried by this fixture and by its main-checkout mirror
    /// `external_probe_discovers_from_project_root_across_every_stage_without_a_worktree`,
    /// which must be read together with it.
    #[test]
    fn external_probe_discovers_from_the_worktree_when_the_main_checkout_lacks_the_plan() {
        let dir = tempfile::tempdir().unwrap();
        let worktree = dir.path().join("phase-worktree");
        // The PLAN exists ONLY under the worktree — `dir.path()`'s own
        // `.planning/phases/` is deliberately never created.
        let phase_dir = worktree.join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f implemented\"\n---\n",
        )
        .unwrap();
        // Captures live in the project root, not the worktree.
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\"}\n",
        )
        .unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.worktree_path = Some(worktree.clone());

        let approval = vec!["test -f implemented".to_string()];

        // The probe file does not exist yet, so this must fail ON THE PROBE.
        let failing = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(failing.status, AgentStatus::Failed);
        assert!(
            failing
                .reason
                .as_deref()
                .is_some_and(|reason| reason.contains("external verification failed")),
            "expected a failing-probe reason; a PLAN-removed reason means discovery \
             silently returned zero commands — i.e. discovery still reads project_root \
             and 999.76's fix did not land: {:?}",
            failing.reason
        );

        std::fs::write(worktree.join("implemented"), "done").unwrap();
        let passing = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(passing.status, AgentStatus::Success);
        assert_eq!(passing.decided_by_layer, Some(0));
    }

    #[test]
    fn changed_external_probe_never_inherits_prior_approval() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"touch escaped\"\n---\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16));
        let approved = vec!["test -f reviewed-artifact".to_string()];

        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approved),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert!(result.reason.unwrap().contains("approval mismatch"));
        assert!(!dir.path().join("escaped").exists());
    }

    #[test]
    fn removed_external_probe_fails_closed_against_prior_approval() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\"}\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16));
        let approved = vec!["test -f shipped".to_string()];

        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approved),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert!(result.reason.unwrap().contains("declaration was removed"));
    }

    #[test]
    fn no_external_declaration_preserves_layer1_result() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\",\"commits\":2,\"summary\":\"done\"}\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16));
        let layer1 = evaluate_layer1(dir.path(), PhaseId::new(16)).unwrap();

        let full = evaluate_agent_result(dir.path(), &state, &GitFlowConfig::default()).unwrap();

        assert_eq!(
            serde_json::to_value(full).unwrap(),
            serde_json::to_value(layer1).unwrap()
        );
    }

    /// D-05 gap 2 (17-03): a declared, operator-approved external
    /// post-condition whose probe passes is affirmative Success evidence on
    /// its own — even with zero commits and on a non-Code stage (Define
    /// here). No agent stdout is written at all, so if Layer 0 did not
    /// short-circuit, there would be nothing for Layer 1 to find and Layer 2
    /// would fall through for lack of an exit-code file.
    #[test]
    fn layer0_affirmative_success_on_non_code_stage_with_zero_commits() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("shipped"), "done").unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Define;

        let approval = vec!["test -f shipped".to_string()];
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
        assert_eq!(result.commits, None);
        // Off-Validate stage: verdict reconciliation does not apply (18e).
        assert_eq!(result.verdict, None);
    }

    /// Review Plan 03 LOW (Codex+OpenCode), 16a: an approved all-passing
    /// Layer 0 probe intentionally outranks a Layer 1 self-reported failure
    /// marker — proven here at the cascade level (`evaluate_agent_result_inner`),
    /// not merely in isolation on `evaluate_layer0`.
    #[test]
    fn layer0_affirmative_success_outranks_layer1_failure_marker() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir
            .path()
            .join(".planning/phases/16-pipeline-reliability-hardening");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-03-PLAN.md"),
            "---\nphase: 16\nexternal_verify: \"test -f externally-shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("externally-shipped"), "done").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\",\"reason\":\"agent self-reported failure\"}\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16));

        let approval = vec!["test -f externally-shipped".to_string()];
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
        // Off-Validate stage (Code): verdict reconciliation does not apply,
        // even though Layer 1's marker here reports a (failure) status (18e).
        assert_eq!(result.verdict, None);
    }

    /// D-05/18e: Layer 0's affirmative-success arm at `Stage::Validate` must
    /// consult Layer 1's verdict rather than discard it — the two-signal
    /// reconciliation `reconcile_layer0_verdict` adds. Covers all three
    /// verdict states Layer 1 can produce: pass, gaps, and no marker at all.
    ///
    /// D-15 (34-01) adds a FOURTH case: the self-contradictory marker
    /// `{"status":"failed","verdict":"pass"}`. "Consult Layer 1's verdict" was
    /// implemented as "read Layer 1's verdict and nothing else", so an agent
    /// that reported its own failure while claiming a passing verdict had that
    /// verdict grafted onto Layer 0's `Success` — 999.74's real route. The
    /// fourth case pins `verdict: None` for it; before the fix it observed
    /// `Some(Pass)`.
    #[test]
    fn layer0_affirmative_success_consults_layer1_verdict_at_validate() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("shipped"), "done").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Validate;
        let approval = vec!["test -f shipped".to_string()];

        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
        assert_eq!(result.verdict, Some(Verdict::Pass));

        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\",\"verdict\":\"gaps\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(result.verdict, Some(Verdict::Gaps));

        std::fs::remove_file(stdout_path(dir.path(), PhaseId::new(16))).unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(result.verdict, None);

        // D-15: the self-contradictory marker. Layer 1 reports its own run
        // FAILED and simultaneously claims a passing verdict. Pre-fix the graft
        // read only `.verdict` and produced `Some(Pass)`, i.e. an affirmative
        // pair `decide_action` advances and `classify_validate_outcome` reads
        // as Passed — Ship, unattended, on a run whose agent reported failure.
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(
            result.verdict, None,
            "a verdict attached to a self-reported failure must not be grafted (D-15)"
        );
        // The fix touches `.verdict` only — Layer 0 still decided the status.
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
    }

    /// D-15 / ROADMAP criterion 4: `reconcile_layer0_verdict` must consult
    /// Layer 1's own `AgentStatus` before transplanting its `verdict`.
    ///
    /// A regression here costs an unattended Ship on a run whose agent reported
    /// failure: the graft would rebuild `(Success, Some(Pass), Some(0))` from a
    /// self-contradictory marker, `decide_action` would advance it, and
    /// `classify_validate_outcome` would classify Validate as `Passed`.
    ///
    /// Also carries NC-5's two discrimination cases, which share this fixture.
    /// The exploit needs BOTH marker fields; removing either must not reach an
    /// affirmative pair. The mandatory opposite-result control lives in
    /// `layer0_verdict_graft_still_transplants_a_passing_layer1_verdict` — if
    /// that test also produced `None` the fix would be indiscriminate and this
    /// one would prove nothing.
    #[test]
    fn layer0_verdict_graft_declines_when_layer1_status_is_not_success() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("shipped"), "done").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Validate;
        let approval = vec!["test -f shipped".to_string()];

        // The exploit itself: both fields present and mutually contradictory.
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(
            result.verdict, None,
            "self-contradictory marker: the verdict must be declined (D-15)"
        );
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));

        // NC-5a: removes the `verdict` FIELD, keeps the failed status. `None`
        // both pre- and post-fix, so this case cannot discriminate the fix —
        // that is the point. The failed status alone is not the exploit.
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(
            result.verdict, None,
            "NC-5a removes the `verdict` field: there is no verdict to graft, \
             so the result must be None whether or not the fix is present"
        );

        // NC-5b: removes `verdict: pass` SPECIFICALLY by downgrading it to
        // `gaps`, keeping both fields present. Pre-fix this grafted
        // `Some(Gaps)`; post-fix it declines like any other non-Success
        // Layer 1. Neither state is an affirmative pair — the exploit needs
        // `pass`, not merely any verdict.
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\",\"verdict\":\"gaps\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_ne!(
            result.verdict,
            Some(Verdict::Pass),
            "NC-5b removes `verdict: pass` by downgrading it to `gaps`: this \
             case must never reach an affirmative pair"
        );
        assert_eq!(result.verdict, None);
    }

    /// NC-5's positive half: the fix declines ONLY when Layer 1's own status is
    /// not `Success`, never indiscriminately.
    ///
    /// This is the case that must produce the OPPOSITE result from
    /// `layer0_verdict_graft_declines_when_layer1_status_is_not_success`. If
    /// both produced `None` the fix would have disabled 18e's legitimate
    /// reconciliation wholesale — re-introducing the 17-03 regression that
    /// `reconcile_layer0_verdict` exists to fix — and the pair would prove
    /// nothing about D-15, because a measurement whose two arms agree is
    /// broken rather than informative.
    #[test]
    fn layer0_verdict_graft_still_transplants_a_passing_layer1_verdict() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("shipped"), "done").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Validate;
        let approval = vec!["test -f shipped".to_string()];

        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(
            result.verdict,
            Some(Verdict::Pass),
            "a passing verdict from a Layer 1 that reported its OWN success \
             must still be transplanted (18e); a None here would mean the \
             D-15 fix is indiscriminate"
        );
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
    }

    /// NC-6: with Layer 0 disabled, the same self-contradictory marker never
    /// gets laundered at all — Layer 1 reports `Failed` verbatim and
    /// `decide_action` routes it to `GateReview`.
    ///
    /// What the control proves: the GRAFT is the mechanism, not the classifier
    /// and not `decide_action`. Removing Layer 0 removes the laundering
    /// entirely, so the exploit's precondition is an affirmative Layer-0 probe
    /// success — which is exactly why plan 34-04 (999.76), by making
    /// `decided_by_layer == Some(0)` common in worktree mode, must not land
    /// without the fix this test pins.
    ///
    /// The routing consequence is asserted here rather than assumed, so a
    /// future change to `decide_action`'s `Failed` arm breaks this test rather
    /// than silently invalidating the control.
    #[test]
    fn layer0_disabled_routes_a_self_reported_failure_to_gate_review() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        // The difference from the fixtures above: Layer 0 is switched off, so
        // the cascade falls through to Layer 1 instead of short-circuiting on
        // an affirmative probe success.
        std::fs::write(
            dir.path().join("devflow.toml"),
            "external_verify_enabled = false\n",
        )
        .unwrap();
        // Belt AND braces, deliberately. `config::external_verify_enabled`
        // consults `DEVFLOW_EXTERNAL_VERIFY_ENABLED` BEFORE `devflow.toml`, and
        // `config::tests::env_overrides_file_external_verification` sets that
        // variable to "true" process-globally under a mutex private to its own
        // module — which cannot serialize against this one. A PLAN declaring
        // `external_verify` would therefore let a parallel run of that test
        // re-enable Layer 0 here and flake this control into a green.
        // Declaring no probe closes that window: with no declared commands and
        // no approval vector, `evaluate_layer0` abstains whatever the env says,
        // so this test is deterministic under every value of the variable.
        std::fs::write(phase_dir.join("16-01-PLAN.md"), "---\nplan: 01\n---\n").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Validate;

        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"failed\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        // No approval vector — Layer 0 is disabled, so there is nothing to
        // approve, and supplying one would re-arm the very arm being removed.
        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(
            result.status,
            AgentStatus::Failed,
            "with Layer 0 disabled, Layer 1's self-reported failure stands \
             verbatim — there is no affirmative probe success to graft onto"
        );
        assert_eq!(result.decided_by_layer, Some(1));
        assert_eq!(
            crate::outcome_policy::decide_action(Stage::Validate, result.status),
            crate::outcome_policy::Action::GateReview,
            "a self-reported failure must gate for review, never advance"
        );
    }

    /// 18e's reconciliation is scoped to `Stage::Validate` only (flagged
    /// assumption in 18-05-PLAN.md): at every other stage an affirmative
    /// Layer 0 success must keep `verdict: None`, even when Layer 1's marker
    /// carries an explicit verdict.
    #[test]
    fn layer0_affirmative_success_keeps_none_verdict_off_validate() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f shipped\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("shipped"), "done").unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(16)),
            "DEVFLOW_RESULT: {\"status\":\"success\",\"verdict\":\"pass\"}\n",
        )
        .unwrap();
        let state = state_in(dir.path(), PhaseId::new(16)); // Stage::Code by default
        let approval = vec!["test -f shipped".to_string()];

        let result = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(0));
        assert_eq!(result.verdict, None);
    }

    /// Ordering edge (17a): with multiple declared probes, ALL must pass for
    /// affirmative Success — the first failing probe vetoes the outcome
    /// regardless of which position it occupies among the declarations.
    #[test]
    fn multiple_declared_probes_first_failure_vetoes_regardless_of_order() {
        let dir = tempfile::tempdir().unwrap();
        let phase_dir = dir.path().join(".planning/phases/16-reliability");
        std::fs::create_dir_all(&phase_dir).unwrap();
        // 16-01 comes first alphabetically and passes; 16-02 comes second and fails.
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f passing-artifact\"\n---\n",
        )
        .unwrap();
        std::fs::write(
            phase_dir.join("16-02-PLAN.md"),
            "---\nexternal_verify: \"test -f never-created\"\n---\n",
        )
        .unwrap();
        std::fs::write(dir.path().join("passing-artifact"), "done").unwrap();
        let mut state = state_in(dir.path(), PhaseId::new(16));
        state.stage = Stage::Define;

        let approval = vec![
            "test -f passing-artifact".to_string(),
            "test -f never-created".to_string(),
        ];
        let result_a = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval),
        )
        .unwrap();
        assert_eq!(result_a.status, AgentStatus::Failed);
        assert!(
            result_a
                .reason
                .as_deref()
                .is_some_and(|reason| reason.contains("never-created")),
            "unexpected reason: {:?}",
            result_a.reason
        );

        // Swap which position fails: 16-01 now fails, 16-02 passes. The
        // overall outcome must still veto — order of declaration must not
        // matter.
        std::fs::write(
            phase_dir.join("16-01-PLAN.md"),
            "---\nexternal_verify: \"test -f still-missing\"\n---\n",
        )
        .unwrap();
        std::fs::write(
            phase_dir.join("16-02-PLAN.md"),
            "---\nexternal_verify: \"test -f passing-artifact\"\n---\n",
        )
        .unwrap();
        let approval_swapped = vec![
            "test -f still-missing".to_string(),
            "test -f passing-artifact".to_string(),
        ];
        let result_b = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval_swapped),
        )
        .unwrap();
        assert_eq!(result_b.status, AgentStatus::Failed);

        // Now make BOTH pass: only then is the outcome Success.
        std::fs::write(dir.path().join("still-missing"), "done").unwrap();
        let result_c = evaluate_agent_result_inner(
            dir.path(),
            &state,
            &GitFlowConfig::default(),
            Some(&approval_swapped),
        )
        .unwrap();
        assert_eq!(result_c.status, AgentStatus::Success);
        assert_eq!(result_c.decided_by_layer, Some(0));
    }

    /// A quota denial in the capture must be visible to the monitor BEFORE it
    /// records a verdict about the silence that denial caused.
    ///
    /// The positive arm of the 2026-08-08 misclassification: a real `seven_day`
    /// / `out_of_credits` denial silenced the agent, the idle timer fired, and
    /// the resulting record shadowed the classifier that had the right answer.
    #[test]
    fn a_quota_denial_in_the_capture_is_visible_to_the_monitor() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let phase = PhaseId::new(3);
        std::fs::create_dir_all(root.join(".devflow")).unwrap();

        std::fs::write(
            stdout_path(root, phase),
            format!("{V3_INIT_EVENT}\n{}\n", v3_rate_limit_event("rejected")),
        )
        .unwrap();

        assert!(
            capture_shows_rate_limit_denial(root, phase),
            "an explicit `rejected` quota denial must be detectable, or the monitor \
             will record a hang for a pause that is resumable"
        );
    }

    /// Negative control, and the more important half: this must NOT fire on an
    /// ordinary capture, or every genuine hang stops being recorded as one.
    ///
    /// The `allowed` arm is the specific trap — the CLI emits `rate_limit_event`
    /// routinely while healthy, and `overageStatus: "rejected"` sits one level
    /// below `status: "allowed"`, so any loose nested search matches it.
    #[test]
    fn an_ordinary_capture_is_not_mistaken_for_a_quota_denial() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::create_dir_all(root.join(".devflow")).unwrap();

        let quiet = PhaseId::new(4);
        std::fs::write(stdout_path(root, quiet), format!("{V3_INIT_EVENT}\n")).unwrap();
        assert!(
            !capture_shows_rate_limit_denial(root, quiet),
            "a capture with no rate-limit event at all must read as no denial"
        );

        let healthy = PhaseId::new(5);
        std::fs::write(
            stdout_path(root, healthy),
            format!("{V3_INIT_EVENT}\n{V3_RATE_LIMIT_EVENT_ALLOWED}\n"),
        )
        .unwrap();
        assert!(
            !capture_shows_rate_limit_denial(root, healthy),
            "a healthy `status: allowed` event carries `overageStatus: rejected` one \
             level down — matching it would suppress the idle timeout on every run"
        );

        let absent = PhaseId::new(6);
        assert!(
            !capture_shows_rate_limit_denial(root, absent),
            "a missing capture must read as no denial, never as one"
        );
    }

    /// A stage attempt's idle-timeout verdict must not survive into the next
    /// attempt.
    ///
    /// Reproduces the 2026-08-08 observation directly: a record written by a
    /// killed Plan stage was still authoritative when the next stage launched,
    /// and because `evaluate_layer1` consults it FIRST and returns
    /// unconditionally, it overrode a stage that had genuinely succeeded.
    #[test]
    fn archive_clears_a_previous_attempts_idle_timeout_verdict() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let phase = PhaseId::new(1);
        std::fs::create_dir_all(root.join(".devflow")).unwrap();

        // A verdict left behind by an earlier, killed attempt.
        std::fs::write(
            idle_timeout_path(root, phase),
            r#"{"status":"idle_timeout","idle_secs":120,"agent_pid":501757,"written_at":1786157328,"commits":[]}"#,
        )
        .unwrap();
        // Precondition, asserted rather than assumed: while it exists it is
        // authoritative, which is precisely why it must not persist.
        assert!(
            evaluate_layer1(root, phase).is_some(),
            "fixture precondition: the stale record must be readable as a verdict"
        );

        archive_phase_files(root, root, phase, 5).unwrap();

        assert!(
            !idle_timeout_path(root, phase).exists(),
            "a previous attempt's timeout verdict survived a stage launch — it \
             will now outrank the next stage's real result, for this phase, forever"
        );
    }

    /// Negative control for the test above. The clearing happens at stage
    /// LAUNCH, and it must not be reachable in a way that discards a verdict
    /// before it has been read: a record with no capture beside it is the
    /// stale case, but a record is only ever written mid-attempt, after the
    /// launch that would have cleared it.
    ///
    /// This pins the other half — that clearing the file did not neuter the
    /// mechanism, only its lifetime.
    #[test]
    fn a_current_attempts_idle_timeout_verdict_is_still_authoritative() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let phase = PhaseId::new(2);
        std::fs::create_dir_all(root.join(".devflow")).unwrap();

        // Stage launched (archive ran), THEN the monitor recorded a timeout —
        // the real ordering within one attempt.
        archive_phase_files(root, root, phase, 5).unwrap();
        std::fs::write(
            idle_timeout_path(root, phase),
            r#"{"status":"idle_timeout","idle_secs":120,"agent_pid":4242,"written_at":1786159637,"commits":[]}"#,
        )
        .unwrap();

        let verdict = evaluate_layer1(root, phase)
            .expect("a verdict recorded during this attempt must still be honoured");
        assert_eq!(
            verdict.status,
            AgentStatus::IdleTimeout,
            "the timeout mechanism itself must survive the lifetime fix"
        );
    }

    #[test]
    fn archive_moves_captures_into_history_and_removes_pid_file() {
        // 16b: prior-stage captures must survive a simulated next-launch by
        // appearing under .devflow/history/phase-NN/, not be wiped outright.
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::create_dir_all(root.join(".devflow")).unwrap();
        std::fs::write(root.join(".devflow/phase-01-stdout"), "prior stdout").unwrap();
        std::fs::write(root.join(".devflow/phase-01-exit"), "0").unwrap();
        std::fs::write(root.join(".devflow/phase-01-agent-pid"), "1234").unwrap();

        archive_phase_files(root, root, PhaseId::new(1), 5).unwrap();

        // The live capture paths are gone (moved, not merely deleted).
        assert!(!root.join(".devflow/phase-01-stdout").exists());
        assert!(!root.join(".devflow/phase-01-exit").exists());
        // Agent-pid is bookkeeping, not diagnostic — still removed outright.
        assert!(!root.join(".devflow/phase-01-agent-pid").exists());

        let history = history_dir(root, PhaseId::new(1));
        let archived: Vec<_> = std::fs::read_dir(&history)
            .unwrap()
            .flatten()
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .collect();
        let archived_stdout = archived
            .iter()
            .find(|name| name.ends_with("-stdout"))
            .expect("stdout capture should be archived into history");
        assert!(archived.iter().any(|name| name.ends_with("-exit")));
        let contents = std::fs::read_to_string(history.join(archived_stdout)).unwrap();
        assert_eq!(contents, "prior stdout");
    }

    #[test]
    fn archive_is_noop_when_nothing_to_archive() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        // Should not panic when there is nothing to archive (first launch).
        archive_phase_files(root, root, PhaseId::new(1), 5).unwrap();
        assert!(!history_dir(root, PhaseId::new(1)).exists());
    }

    #[test]
    fn archive_handles_missing_devflow_dir() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        // No .devflow dir at all — should not panic.
        archive_phase_files(root, root, PhaseId::new(1), 5).unwrap();
    }

    #[test]
    fn archive_failure_preserves_live_capture_for_retry() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::create_dir_all(root.join(".devflow")).unwrap();
        std::fs::write(stdout_path(root, PhaseId::new(1)), "evidence").unwrap();
        // A file where the history directory must be forces create_dir_all
        // to fail before the live capture is moved or a monitor can truncate it.
        std::fs::write(root.join(".devflow/history"), "blocked").unwrap();

        assert!(archive_phase_files(root, root, PhaseId::new(1), 5).is_err());
        assert_eq!(
            std::fs::read_to_string(stdout_path(root, PhaseId::new(1))).unwrap(),
            "evidence"
        );
    }

    #[test]
    fn archive_second_publish_failure_rolls_back_complete_live_pair() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::create_dir_all(root.join(".devflow")).unwrap();
        std::fs::write(stdout_path(root, PhaseId::new(1)), "stdout evidence").unwrap();
        std::fs::write(exit_code_path(root, PhaseId::new(1)), "17").unwrap();
        let history = history_dir(root, PhaseId::new(1));
        std::fs::create_dir_all(history.join("fixed-exit/blocker")).unwrap();

        assert!(archive_phase_files_with_stamp(root, root, PhaseId::new(1), 5, "fixed").is_err());

        assert_eq!(
            std::fs::read_to_string(stdout_path(root, PhaseId::new(1))).unwrap(),
            "stdout evidence"
        );
        assert_eq!(
            std::fs::read_to_string(exit_code_path(root, PhaseId::new(1))).unwrap(),
            "17"
        );
        assert!(!history.join("fixed-stdout").exists());
        assert!(!history.join(".pending-fixed").exists());
    }

    #[test]
    fn archive_review_copy_failure_rolls_back_complete_live_pair() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let evidence_root = root.join("phase-worktree");
        std::fs::create_dir_all(root.join(".devflow")).unwrap();
        std::fs::write(stdout_path(root, PhaseId::new(1)), "stdout evidence").unwrap();
        std::fs::write(exit_code_path(root, PhaseId::new(1)), "23").unwrap();
        let review = evidence_root.join(".planning/phases/01-example/01-REVIEW.md");
        std::fs::create_dir_all(&review).unwrap();

        assert!(
            archive_phase_files_with_stamp(root, &evidence_root, PhaseId::new(1), 5, "review-copy")
                .is_err()
        );

        assert_eq!(
            std::fs::read_to_string(stdout_path(root, PhaseId::new(1))).unwrap(),
            "stdout evidence"
        );
        assert_eq!(
            std::fs::read_to_string(exit_code_path(root, PhaseId::new(1))).unwrap(),
            "23"
        );
        let history = history_dir(root, PhaseId::new(1));
        assert!(!history.join("review-copy-stdout").exists());
        assert!(!history.join("review-copy-exit").exists());
        assert!(!history.join(".pending-review-copy").exists());
    }

    #[test]
    fn archive_snapshots_current_review_into_same_generation() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let evidence_root = root.join("phase-worktree");
        std::fs::create_dir_all(root.join(".devflow")).unwrap();
        std::fs::write(stdout_path(root, PhaseId::new(1)), "attempt").unwrap();
        let phase_dir = evidence_root.join(".planning/phases/01-example");
        std::fs::create_dir_all(&phase_dir).unwrap();
        std::fs::write(phase_dir.join("01-REVIEW.md"), "review one").unwrap();

        let stamp = archive_phase_files(root, &evidence_root, PhaseId::new(1), 5)
            .unwrap()
            .unwrap();

        assert_eq!(
            std::fs::read_to_string(
                history_dir(root, PhaseId::new(1)).join(format!("{stamp}-REVIEW.md"))
            )
            .unwrap(),
            "review one"
        );
    }

    #[test]
    fn archive_prunes_history_to_retain_count() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        std::fs::create_dir_all(root.join(".devflow")).unwrap();

        for i in 0..7 {
            std::fs::write(root.join(".devflow/phase-01-stdout"), format!("gen {i}")).unwrap();
            std::fs::write(root.join(".devflow/phase-01-exit"), "0").unwrap();
            archive_phase_files(root, root, PhaseId::new(1), 3).unwrap();
        }

        let history = history_dir(root, PhaseId::new(1));
        let stdout_count = std::fs::read_dir(&history)
            .unwrap()
            .flatten()
            .filter(|e| e.file_name().to_string_lossy().ends_with("-stdout"))
            .count();
        let exit_count = std::fs::read_dir(&history)
            .unwrap()
            .flatten()
            .filter(|e| e.file_name().to_string_lossy().ends_with("-exit"))
            .count();
        assert_eq!(stdout_count, 3, "expected at most 3 retained generations");
        assert_eq!(exit_count, 3, "expected at most 3 retained generations");
    }

    /// The set of stamp groups currently surviving in a history directory,
    /// derived the same way `prune_history` derives them (`rsplit_once('-')`,
    /// keep the left part) so the assertion measures grouping rather than a
    /// listing length.
    fn surviving_stamps(history: &Path) -> std::collections::BTreeSet<String> {
        std::fs::read_dir(history)
            .unwrap()
            .flatten()
            .filter_map(|entry| {
                let name = entry.file_name().to_str()?.to_string();
                name.rsplit_once('-')
                    .map(|(stamp, _suffix)| stamp.to_string())
            })
            .collect()
    }

    /// ROADMAP criterion 7's retention half. `DEFAULT_CAPTURE_RETENTION` was
    /// `5`, and `archive_phase_files` runs once per launch: a clean five-stage
    /// Define→Plan→Code→Validate→Ship run produces 4 archive events and each
    /// Validate→Code loop-back adds 2. At `5`, the first loop-back's sixth
    /// event evicted Define's capture — silently, with no error and no log.
    ///
    /// What a regression here costs: a stage capture destroyed before the
    /// phase that requested it has read it, which is unrecoverable after the
    /// fact because `.devflow/` is the only copy until it is deliberately
    /// copied out.
    #[test]
    fn prune_history_retains_a_full_five_stage_run_with_loop_backs() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let history = history_dir(root, PhaseId::new(1));
        std::fs::create_dir_all(&history).unwrap();

        let retain = crate::config::DEFAULT_CAPTURE_RETENTION;

        // Twelve generations, strictly increasing. The suffix is load-bearing:
        // `prune_history` derives a stamp with `rsplit_once('-')` and keeps the
        // LEFT part, so a bare `{nanos}-{seq}` name would yield the stamp
        // `{nanos}` and then delete `{nanos}-stdout`, which never exists — the
        // retain half would false-pass via the `stamps.len() <= retain` early
        // return while the evict half could never pass at all.
        let stamps: Vec<String> = (0..12)
            .map(|i| format!("{}-0", 1_700_000_000_000_000_000u128 + i))
            .collect();
        for stamp in &stamps {
            std::fs::write(history.join(format!("{stamp}-stdout")), "capture").unwrap();
        }
        // The oldest generation gets a second suffix so eviction-by-stamp-group
        // is actually exercised rather than assumed: one evicted stamp must
        // take BOTH its files.
        std::fs::write(history.join(format!("{}-exit", stamps[0])), "0").unwrap();

        prune_history(&history, retain);

        let survivors = surviving_stamps(&history);
        assert_eq!(
            survivors.len(),
            12,
            "a five-stage run with loop-backs must not lose a capture at the default \
             retention; found {survivors:?}"
        );
        for stamp in &stamps {
            assert!(
                survivors.contains(stamp),
                "generation {stamp} was evicted at exactly the retention boundary"
            );
        }

        // Opposite-result control. Without this half the test would be
        // measuring a directory listing, not pruning: `prune_history` returns
        // early whenever `stamps.len() <= retain`, so a fixture that never
        // crosses the boundary passes identically against a `prune_history`
        // that does nothing at all.
        let thirteenth = format!("{}-0", 1_700_000_000_000_000_000u128 + 12);
        std::fs::write(history.join(format!("{thirteenth}-stdout")), "capture").unwrap();

        prune_history(&history, retain);

        let after = surviving_stamps(&history);
        assert_eq!(
            after.len(),
            12,
            "crossing the boundary by one must evict exactly one stamp group, not zero \
             and not several; found {after:?}"
        );
        assert!(
            !after.contains(&stamps[0]),
            "the evicted generation must be the OLDEST by stamp order"
        );
        assert!(
            !history.join(format!("{}-exit", stamps[0])).exists(),
            "eviction operates on the stamp GROUP: the oldest generation's -exit file must \
             go with its -stdout, or pruning is leaking partial generations"
        );
        assert!(
            after.contains(&thirteenth),
            "the newest generation must survive its own arrival"
        );
    }

    #[test]
    fn evaluate_agent_result_reads_files_end_to_end() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(6)),
            "done\nDEVFLOW_RESULT: {\"status\":\"success\",\"commits\":2,\"summary\":\"ok\"}\n",
        )
        .unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(6)), "0").unwrap();
        let state = state_in(dir.path(), PhaseId::new(6));

        let result = evaluate_agent_result(dir.path(), &state, &GitFlowConfig::default()).unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.commits, Some(2));
        assert_eq!(result.summary.as_deref(), Some("ok"));
    }

    // ---- exit-code arbitration on a claimed success (31-04, T-31-15) -----
    //
    // Every test below drives the FULL cascade through
    // `evaluate_agent_result_inner`, never the parser's own return value.
    // 31-RESEARCH.md § Pitfall 4 records why: a truncation-boundary test that
    // checks only `parse_claude_event_result` exercises constraint 9's items 1
    // and 2, which the `a557805` root-cause refactor already closed. The
    // residual this arbitration exists for lives in the WIRING — Layer 1
    // returning before Layer 2 is ever consulted — and only the cascade
    // exercises it.

    /// A success marker that also claims `verdict: pass` — the shape a naive
    /// "carry every other field over" downgrade would have preserved. Used to
    /// prove `verdict` is dropped.
    ///
    /// Correction (34-01, D-15): an earlier version of this comment asserted
    /// that keeping the field would classify Validate as Passed because
    /// `classify_validate_outcome` matches `Some(Verdict::Pass)` first with the
    /// status discarded. That overstated the reachability — `decide_action`
    /// intercepts a non-`Success` status before the classifier runs. The
    /// corrected record of how the inversion is actually reached lives on
    /// [`super::reconcile_layer0_verdict`].
    const MARKER_SUCCESS_CLAIMING_PASS: &str =
        r#"Done.\nDEVFLOW_RESULT: {\"status\":\"success\",\"verdict\":\"pass\"}"#;

    /// The residual of constraint 9 that no parser assertion can reach.
    ///
    /// A capture cut at an exact line boundary is byte-identical to a healthy
    /// shorter run, so the stream itself carries no evidence of the tear. The
    /// writer that died between flushing turn N and turn N+1 also died
    /// non-zero, and that exit code is the only signal left.
    #[test]
    fn stream_success_cannot_stand_against_nonzero_exit_code() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(31)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS_CLAIMING_PASS),
        )
        .unwrap();

        // NEGATIVE CONTROL, encoded in the test rather than described in prose:
        // Layer 1 on its own decides Success here AND reports `verdict: Pass`.
        // Without this the assertions below cannot distinguish "the arbitration
        // downgraded a success" from "nothing ever claimed success", nor
        // "`verdict` was dropped" from "`verdict` was never set".
        let layer1 = evaluate_layer1(dir.path(), PhaseId::new(31)).unwrap();
        assert_eq!(layer1.status, AgentStatus::Success);
        assert_eq!(layer1.verdict, Some(Verdict::Pass));

        std::fs::write(exit_code_path(dir.path(), PhaseId::new(31)), "1\n").unwrap();
        let state = state_in(dir.path(), PhaseId::new(31));

        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.exit_code, Some(1));
        assert!(
            result.reason.as_deref().is_some_and(|r| r.contains("1")),
            "the reason must name the exit code: {:?}",
            result.reason
        );
        // Layer 1 still decided this — the arbitration corrects its verdict, it
        // does not hand the decision to Layer 2.
        assert_eq!(result.decided_by_layer, Some(1));
        // Load-bearing: a downgraded result has no verdict to offer. Carrying
        // `Some(Verdict::Pass)` over would leave Validate classified Passed and
        // make this whole test's premise false at the stage that matters most
        // (999.74 / DEN-95).
        assert_eq!(result.verdict, None);
    }

    /// The matched negative control for the test above. Without it, that test
    /// cannot tell "the arbitration works" from "the arbitration fires on
    /// everything".
    #[test]
    fn stream_success_stands_when_the_exit_code_is_zero() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(32)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS_CLAIMING_PASS),
        )
        .unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(32)), "0\n").unwrap();
        let state = state_in(dir.path(), PhaseId::new(32));

        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(1));
        // The verdict survives an untouched result — proof that the `None`
        // asserted in the downgrade test is the arbitration's doing and not a
        // property of the fixture.
        assert_eq!(result.verdict, Some(Verdict::Pass));
    }

    /// A missing exit file is not evidence of failure. This matches
    /// `evaluate_layer2`'s own tolerance (`Err(_) => return Ok(None)`); a
    /// stricter reading here would fail every stage whose monitor had not yet
    /// written the file.
    #[test]
    fn stream_success_stands_when_no_exit_file_exists() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(33)),
            v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS),
        )
        .unwrap();
        assert!(
            !exit_code_path(dir.path(), PhaseId::new(33)).exists(),
            "fixture precondition: there must be no exit file"
        );
        let state = state_in(dir.path(), PhaseId::new(33));

        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.decided_by_layer, Some(1));
    }

    /// Only a *claimed success* is arbitrated. Downgrading a rate limit to a
    /// generic failure would route the run to a human gate instead of the
    /// auto-resume cron it needs — the exact harm `rate_limited_result`'s
    /// precedence over `detect_claude_envelope_failure` exists to prevent.
    #[test]
    fn rate_limited_verdict_is_not_arbitrated_by_exit_code() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(34)),
            r#"{"type":"result","subtype":"error_rate_limit","is_error":true,"retry_after":"2026-06-18T15:45:30Z"}"#,
        )
        .unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(34)), "1\n").unwrap();
        let state = state_in(dir.path(), PhaseId::new(34));

        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(result.status, AgentStatus::RateLimited);
        assert_eq!(
            result.reason.as_deref(),
            Some("rate limited until 2026-06-18T15:45:30Z"),
            "the rate-limit reason must survive verbatim — the resume cron reads it"
        );
    }

    /// Plan 31-02's side-channel verdict survives arbitration unchanged. An
    /// `IdleTimeout` collapsed into `Failed` would lose exactly the distinction
    /// 31-02 exists to create, and the monitor writes a NON-zero exit for a
    /// child it killed, so this is not a hypothetical pairing.
    #[test]
    fn idle_timeout_verdict_is_not_arbitrated_by_exit_code() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(35)),
            v3_stream_capture(MARKER_SUCCESS, MARKER_SUCCESS, MARKER_SUCCESS),
        )
        .unwrap();
        write_idle_timeout_record(
            dir.path(),
            PhaseId::new(35),
            &[("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "feat: partial")],
        );
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(35)), "143\n").unwrap();
        let state = state_in(dir.path(), PhaseId::new(35));

        let result =
            evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                .unwrap();

        assert_eq!(result.status, AgentStatus::IdleTimeout);
        assert_eq!(
            result.exit_code, None,
            "the arbitration must not graft an exit code onto a timeout verdict"
        );
    }

    /// Exit-code fidelity (adversarial review of 31-04, W1). A blanket `Failed`
    /// would flatten the two codes `evaluate_layer2` classifies specially, and
    /// `outcome_policy::decide_action` routes those to `GateInfra` rather than
    /// `GateReview`. The same exit code must not reach two different operator
    /// gates depending on whether a stale Layer 1 success happened to be there.
    #[test]
    fn arbitration_preserves_layer2s_resource_and_unavailable_codes() {
        for (code, expected) in [
            (137, AgentStatus::ResourceKilled),
            (127, AgentStatus::AgentUnavailable),
            (2, AgentStatus::Failed),
        ] {
            let dir = tempfile::tempdir().unwrap();
            std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
            std::fs::write(
                stdout_path(dir.path(), PhaseId::new(36)),
                v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS),
            )
            .unwrap();
            std::fs::write(
                exit_code_path(dir.path(), PhaseId::new(36)),
                format!("{code}\n"),
            )
            .unwrap();
            let state = state_in(dir.path(), PhaseId::new(36));

            let arbitrated =
                evaluate_agent_result_inner(dir.path(), &state, &GitFlowConfig::default(), None)
                    .unwrap();

            assert_eq!(
                arbitrated.status, expected,
                "exit {code} must arbitrate to {expected:?}, matching evaluate_layer2"
            );
            assert_eq!(arbitrated.exit_code, Some(code));
        }
    }

    /// D-12's inverse assertion, and the mirror of
    /// [`single_doc_envelope_not_consumed_by_claude_stream_parser`].
    ///
    /// That test pins one direction: today's shipped `--output-format json`
    /// envelope must NOT be consumed by the stream parser. This pins the other:
    /// a capture produced by plan 31-01's new `stream-json` argv classifies as
    /// [`CaptureKind::ClaudeStream`] and is NOT consumed by the
    /// single-document envelope path. Without both directions, widening either
    /// gate is only half-guarded.
    ///
    /// Cites `classify()` / `CaptureKind::ClaudeStream` deliberately: the gate
    /// predicate `31-CONTEXT.md` and `30-VERIFICATION.md` W-02 still name is no
    /// longer a live function — the `a557805` refactor replaced it.
    #[test]
    fn stream_json_capture_is_not_consumed_by_the_single_document_path() {
        let capture = v3_stream_capture(NO_MARKER, NO_MARKER, MARKER_SUCCESS);

        // The classifier owns it.
        assert!(capture_is_claude_stream(&capture));

        // Every single-document reader declines it...
        assert!(claude_session_id(&capture).is_none());
        assert!(detect_claude_envelope_failure(&capture).is_none());
        assert!(detect_claude_rate_limit(&capture).is_none());

        // ...and the stream parser still owns it, so declining costs no verdict.
        assert_eq!(
            parse_claude_event_result(&capture).unwrap().status,
            AgentStatus::Success
        );

        // Non-vacuity: the single-document readers are not simply broken — the
        // same three answer a real envelope. Without this, the `is_none()`
        // assertions above would pass against a reader that returned `None` for
        // everything.
        let envelope = r#"{"type":"result","subtype":"error_rate_limit","is_error":true,"retry_after":"2026-06-18T15:45:30Z","session_id":"abc"}"#;
        assert_eq!(claude_session_id(envelope).as_deref(), Some("abc"));
        assert!(detect_claude_envelope_failure(envelope).is_some());
        assert!(detect_claude_rate_limit(envelope).is_some());
        assert!(!capture_is_claude_stream(envelope));
    }

    #[test]
    fn evaluate_layer1_finds_devflow_result_in_file() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(
            stdout_path(dir.path(), PhaseId::new(3)),
            "output\ndevflow_result: {\"status\":\"failed\",\"reason\":\"bad output\"}\n",
        )
        .unwrap();

        let result = evaluate_layer1(dir.path(), PhaseId::new(3)).unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.reason.as_deref(), Some("bad output"));
    }

    /// The case `consecutive_failures_reaches_ceiling_across_cycles`
    /// (`pipeline_outcomes.rs`) silently depends on: a repository with no
    /// `feature/phase-NN` branch at all must report 0, not error or panic.
    #[test]
    fn phase_commit_count_reports_zero_without_a_branch() {
        let dir = tempfile::tempdir().unwrap();
        git(dir.path(), &["init"]);
        git(dir.path(), &["config", "user.email", "devflow@example.com"]);
        git(dir.path(), &["config", "user.name", "DevFlow Tests"]);
        git(dir.path(), &["config", "commit.gpgsign", "false"]);
        git(dir.path(), &["config", "tag.gpgsign", "false"]);
        git(dir.path(), &["config", "core.hooksPath", "/dev/null"]);
        git(dir.path(), &["checkout", "-b", "develop"]);
        std::fs::write(dir.path().join("README.md"), "base\n").unwrap();
        git(dir.path(), &["add", "README.md"]);
        git(dir.path(), &["commit", "-m", "base"]);

        let count = phase_commit_count(dir.path(), &GitFlowConfig::default(), PhaseId::new(999));

        assert_eq!(
            count,
            Some(0),
            "git RAN and reported the branch absent — a real observation of zero, \
             not a failure to measure"
        );
    }

    /// The paired opposite-result case for
    /// `phase_commit_count_reports_zero_without_a_branch` directly above, and
    /// the pair is what makes either one mean anything (NC-4).
    ///
    /// The two differ in exactly one respect: whether the `git` child could be
    /// executed at all. The repository is identical in both — no
    /// `feature/phase-NN` branch — so a `Some(0)` here would prove the split
    /// was made on "was the answer zero" rather than on "did the command run",
    /// which is the distinction the whole `Option` exists to carry.
    ///
    /// Deliberately NOT built on a `git` shim that runs and exits non-zero:
    /// that path returns `Ok(status)` from `.output()` and is a real
    /// observation, so it would exercise the case above while appearing to
    /// cover this one (F-1).
    ///
    /// **Why an unspawnable working directory rather than `NoGitPath` here —
    /// F-1b's recorded fallback, taken on measured evidence.** `NoGitPath`
    /// makes `git` unresolvable *process-wide*, and `devflow-core`'s tests
    /// shell out to `git` from eight modules that all compile into ONE
    /// parallel test binary. Installing it here failed 1-5 unrelated sibling
    /// tests per run, nondeterministically, depending on which of them
    /// happened to invoke `git` inside the guarded window. Serializing them
    /// would mean every present and future `git`-touching test in the crate
    /// opting into the same mutex — discipline, not structure, and silently
    /// reopened by the next test that forgets.
    ///
    /// `hermetic_command` sets `cmd.current_dir(dir)`, so a directory that
    /// does not exist makes the spawn itself fail and `.output()` return
    /// `Err` — the identical arm, reached with no environment mutation at all
    /// and therefore no effect on any other test. `phase_commit_count` cannot
    /// tell the two causes apart: it sees only `Err`.
    ///
    /// This route is also independent of the PATH-resolution property C5
    /// flags as a latent fragility of `NoGitPath` (a future refactor to an
    /// absolute `git` path would disarm that guard silently; it would not
    /// disarm this).
    #[test]
    fn phase_commit_count_reports_none_when_git_cannot_run() {
        let dir = tempfile::tempdir().unwrap();
        let unspawnable_root = dir.path().join("this-directory-does-not-exist");
        assert!(
            !unspawnable_root.exists(),
            "the fixture depends on this path being absent"
        );

        let count = phase_commit_count(
            &unspawnable_root,
            &GitFlowConfig::default(),
            PhaseId::new(999),
        );

        assert_eq!(
            count, None,
            "a git child that could not be executed is a measurement FAILURE and must \
             never be reported as a measured zero"
        );
    }

    /// CR-01 (35-REVIEW), the `rev-list` half. The branch EXISTS, so the
    /// `rev-parse` step succeeds and the function reaches its second git call
    /// — but `develop` is absent from the checkout, so `A..B` is an invalid
    /// range and `rev-list` runs, exits non-zero, and writes nothing to
    /// stdout. That used to fall out of `.parse().ok()` as `None`, splitting
    /// on whether the output PARSED rather than on whether the command RAN,
    /// which contradicts this function's own A-06 rule and the `rev-parse`
    /// step directly above it.
    ///
    /// It is the *permanence* that makes this worth a test: unlike a fork
    /// failure, a misconfigured or absent `develop` does not clear on retry,
    /// so before the fix every stage of every phase in such a checkout
    /// measured as unmeasurable, forever.
    ///
    /// `phase_commit_count_reports_none_when_git_cannot_run` is the NC-4
    /// control — the one case that must still be `None`.
    #[test]
    fn phase_commit_count_reports_zero_when_the_range_is_invalid() {
        let dir = tempfile::tempdir().unwrap();
        git(dir.path(), &["init"]);
        git(dir.path(), &["config", "user.email", "devflow@example.com"]);
        git(dir.path(), &["config", "user.name", "DevFlow Tests"]);
        git(dir.path(), &["config", "commit.gpgsign", "false"]);
        git(dir.path(), &["config", "tag.gpgsign", "false"]);
        git(dir.path(), &["config", "core.hooksPath", "/dev/null"]);
        // The feature branch exists; `develop` deliberately does not.
        git(dir.path(), &["checkout", "-b", "feature/phase-999"]);
        std::fs::write(dir.path().join("README.md"), "base\n").unwrap();
        git(dir.path(), &["add", "README.md"]);
        git(dir.path(), &["commit", "-m", "base"]);

        // The fixture is only meaningful if the second git call really is the
        // one that fails, so assert the first one would have succeeded.
        assert!(
            git_command(dir.path())
                .args(["rev-parse", "--verify", "feature/phase-999"])
                .output()
                .expect("git must be runnable for this fixture")
                .status
                .success(),
            "the branch must verify, or this test exercises the rev-parse arm instead"
        );

        let count = phase_commit_count(dir.path(), &GitFlowConfig::default(), PhaseId::new(999));

        assert_eq!(
            count,
            Some(0),
            "git RAN and reported the range unusable — a measurement, not a failure to \
             measure; `None` here is permanent for the whole checkout"
        );
    }

    #[test]
    fn evaluate_layer2_falls_back_to_exit_code_and_commit_count() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_commit(dir.path(), PhaseId::new(4));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(4)), "0").unwrap();
        let state = state_in(dir.path(), PhaseId::new(4));

        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(4),
            &GitFlowConfig::default(),
            state.stage,
        )
        .unwrap()
        .unwrap();

        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.exit_code, Some(0));
        assert_eq!(result.commits, Some(1));
        assert!(result.reason.unwrap().contains("1 commits"));
    }

    #[test]
    fn evaluate_layer2_exit_zero_no_commits_is_failed() {
        // exit=0 but the feature branch has 0 commits ahead of develop →
        // "no work done" failure (the Layer 2 middle branch).
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_no_commit(dir.path(), PhaseId::new(4));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(4)), "0").unwrap();
        let state = state_in(dir.path(), PhaseId::new(4));

        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(4),
            &GitFlowConfig::default(),
            state.stage,
        )
        .unwrap()
        .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.exit_code, Some(0));
        assert_eq!(result.commits, Some(0));
        assert!(result.reason.unwrap().contains("no commits"));
    }

    // HARDEN-07 / criterion 6's two discriminating tests — the layer-level one
    // on `evaluate_layer2` and the cascade-level one on
    // `evaluate_agent_result` — do NOT live here. They need `git` to be
    // unresolvable while `project_root` still EXISTS (Layer 2 reads its exit
    // file from that root, so an unspawnable working directory would make the
    // exit read fail and return `Ok(None)` for the wrong reason), and only a
    // `PATH` guard delivers that combination.
    //
    // A process-global `PATH` guard is not viable in THIS test binary:
    // `devflow-core` shells out to `git` from eight modules that run in
    // parallel, and tests call production code that spawns `git` directly, so
    // no fixture-helper lock can cover them. Measured twice — 1-5 unrelated
    // failures per run before any serialization, and still 1 failure in 8 runs
    // after this module's own `git()` helper took the lock
    // (`evaluate_layer2_exit_zero_no_commits_is_failed`, whose `git` call
    // happens inside `evaluate_layer2` itself).
    //
    // Both tests therefore live in `devflow-cli`'s `pipeline_outcomes.rs`,
    // whose test binary routes every `PATH` mutation through one `ENV_MUTEX`
    // its `git`-touching tests already hold. They call these same `pub`
    // functions directly, so the assertion is unchanged — only the binary it
    // runs in differs. `evaluate_layer2_exit_zero_no_commits_is_failed` below
    // remains their NC-11 opposite-result control and is unedited.

    #[test]
    fn evaluate_layer2_nonzero_exit_is_failed() {
        // Non-zero exit code → failure regardless of commit count.
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_commit(dir.path(), PhaseId::new(4));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(4)), "1").unwrap();
        let state = state_in(dir.path(), PhaseId::new(4));

        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(4),
            &GitFlowConfig::default(),
            state.stage,
        )
        .unwrap()
        .unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.exit_code, Some(1));
        assert!(result.reason.unwrap().contains("exited with code 1"));
    }

    #[test]
    fn layer2_nonzero_exit_is_failed_all_stages() {
        // Non-zero exit is Failed regardless of stage — including Define and
        // Validate, which are exempt from the zero-commit gate but NOT from
        // the exit-code check.
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_no_commit(dir.path(), PhaseId::new(10));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(10)), "1").unwrap();

        for stage in [
            Stage::Define,
            Stage::Plan,
            Stage::Code,
            Stage::Validate,
            Stage::Ship,
        ] {
            let result = evaluate_layer2(
                dir.path(),
                PhaseId::new(10),
                &GitFlowConfig::default(),
                stage,
            )
            .unwrap()
            .unwrap();
            assert_eq!(
                result.status,
                AgentStatus::Failed,
                "stage {stage:?} should be Failed on nonzero exit"
            );
        }
    }

    #[test]
    fn layer2_skips_commit_gate_for_define_and_validate() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_no_commit(dir.path(), PhaseId::new(11));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(11)), "0").unwrap();

        for stage in [Stage::Define, Stage::Validate] {
            let result = evaluate_layer2(
                dir.path(),
                PhaseId::new(11),
                &GitFlowConfig::default(),
                stage,
            )
            .unwrap()
            .unwrap();
            assert_ne!(
                result.status,
                AgentStatus::Failed,
                "stage {stage:?} should not be Failed for zero commits"
            );
        }

        // Code stage with the same zero-commit inputs is still Failed
        // (existing behavior preserved).
        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(11),
            &GitFlowConfig::default(),
            Stage::Code,
        )
        .unwrap()
        .unwrap();
        assert_eq!(result.status, AgentStatus::Failed);
    }

    #[test]
    fn evaluate_layer3_falls_back_to_commit_count() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_commit(dir.path(), PhaseId::new(5));

        let result =
            evaluate_layer3(dir.path(), PhaseId::new(5), &GitFlowConfig::default()).unwrap();

        assert_eq!(result.status, AgentStatus::Unknown);
        assert_eq!(result.exit_code, None);
        assert_eq!(result.commits, Some(1));
        assert!(result.reason.unwrap().contains("1 commits"));
        assert_eq!(result.decided_by_layer, Some(3));
    }

    /// D-02/D-03 case 3 (17-03): "process gone, nothing accounted for" — zero
    /// commits and no declared external post-condition — is a fail-closed
    /// `Failed` outcome that flags human review, not a blanket advanceable
    /// `Unknown`. The commits-present case above stays `Unknown` (gated
    /// downstream by Plan 04's never-advance dispatch, D-04) — only the
    /// zero-commit sub-case is reclassified here.
    #[test]
    fn evaluate_layer3_zero_commits_is_failed_and_flags_human_review() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_no_commit(dir.path(), PhaseId::new(5));

        let result =
            evaluate_layer3(dir.path(), PhaseId::new(5), &GitFlowConfig::default()).unwrap();

        assert_eq!(result.status, AgentStatus::Failed);
        assert_eq!(result.exit_code, None);
        assert_eq!(result.commits, Some(0));
        assert_eq!(result.decided_by_layer, Some(3));
        let reason = result.reason.unwrap();
        assert!(reason.contains("no work"), "reason was: {reason}");
        assert!(
            reason.to_ascii_lowercase().contains("human review"),
            "reason was: {reason}"
        );
    }

    /// F-4 (35-01) / HARDEN-07: Layer 3 used to carry its OWN inline commit
    /// count with the same lossy `.unwrap_or(0)` collapse `phase_commit_count`
    /// had, and classified the resulting zero as `Failed`. Since every path
    /// that reaches Layer 2 also reaches Layer 3, fixing only Layer 2 would
    /// have relocated the misclassification one layer down rather than
    /// removing it.
    ///
    /// A count that could not be measured is not evidence of absent work. It
    /// is strictly less certain than the `commits > 0` case Layer 3 already
    /// calls `Unknown`, so `Unknown` is the consistent classification and
    /// `Failed` — which asserts a negative — is not.
    ///
    /// The two tests directly above are this one's required opposite-result
    /// controls, and they run in the same suite with their bodies unedited: a
    /// branch with one commit still gives `Unknown`/`Some(1)`, and a branch
    /// with no commits still gives `Failed`/`Some(0)`. Without them, an
    /// implementation that returned `Unknown` unconditionally would pass this
    /// test.
    ///
    /// **No assertion here touches `Action` or anything downstream of
    /// `outcome_policy::decide_action` (F-5).** `Failed` and `Unknown` map
    /// identically to `Action::GateReview` today, so a dispatch-level
    /// assertion would pass against the buggy code too. The observable
    /// difference is entirely in the `AgentResult`.
    ///
    /// Uses the same unspawnable-working-directory route as
    /// `phase_commit_count_reports_none_when_git_cannot_run`, for the reason
    /// recorded there (F-1b): a process-wide `PATH` guard broke unrelated
    /// sibling tests in this crate nondeterministically, and this route
    /// reaches the identical `Err` arm with no environment mutation.
    #[test]
    fn evaluate_layer3_unmeasurable_count_is_unknown_not_failed() {
        let dir = tempfile::tempdir().unwrap();
        let unspawnable_root = dir.path().join("this-directory-does-not-exist");
        assert!(
            !unspawnable_root.exists(),
            "the fixture depends on this path being absent"
        );

        let result = evaluate_layer3(
            &unspawnable_root,
            PhaseId::new(5),
            &GitFlowConfig::default(),
        )
        .unwrap();

        assert_ne!(
            result.status,
            AgentStatus::Failed,
            "an unmeasurable commit count must never be classified as absent work — \
             this is the outcome criterion 6 exists to remove"
        );
        assert_eq!(
            result.status,
            AgentStatus::Unknown,
            "asserted positively as well as negatively, so a future change to some \
             other non-Failed value still has to confront this test"
        );
        assert_eq!(
            result.commits, None,
            "the commit figure must be absent, not a forged Some(0) — the difference \
             between 'no work' and 'could not tell' is the whole point"
        );
        assert_eq!(result.decided_by_layer, Some(3));
        let reason = result.reason.unwrap();
        assert!(
            reason.contains("could not be measured"),
            "the reason must name the measurement failure rather than absent work, \
             reason was: {reason}"
        );
    }

    #[test]
    fn parse_devflow_result_reads_verdict() {
        let stdout = r#"DEVFLOW_RESULT: {"status":"success","verdict":"gaps"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, Some(Verdict::Gaps));
    }

    #[test]
    fn parse_devflow_result_reads_verdict_pass() {
        let stdout = r#"DEVFLOW_RESULT: {"status":"success","verdict":"pass"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, Some(Verdict::Pass));
    }

    #[test]
    fn parse_devflow_result_verdict_absent_is_none() {
        let stdout = r#"DEVFLOW_RESULT: {"status":"success"}"#;
        let result = parse_devflow_result(stdout).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);
    }

    #[test]
    fn parse_devflow_result_malformed_verdict_is_none_not_parse_error() {
        // An unknown verdict string must not fail the whole marker parse —
        // status must still come through as Success with verdict None (T-13-14).
        let unknown = r#"DEVFLOW_RESULT: {"status":"success","verdict":"wat"}"#;
        let result = parse_devflow_result(unknown).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);

        // Mis-cased ("Pass" instead of "pass") must also be lenient, not an error.
        let miscased = r#"DEVFLOW_RESULT: {"status":"success","verdict":"Pass"}"#;
        let result = parse_devflow_result(miscased).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);
    }

    /// WR-09 (13-REVIEW.md): a `verdict` field present with a non-string
    /// JSON *type* (bool, number, object) must be just as lenient as a
    /// malformed string value — before the fix, deserializing straight to
    /// `Option<String>` errored out the entire `AgentResult` parse for a
    /// type mismatch, defeating the doc comment's "a malformed verdict must
    /// never silently drop a valid status" guarantee for this specific case.
    #[test]
    fn parse_devflow_result_non_string_verdict_type_is_none_not_parse_error() {
        let bool_verdict = r#"DEVFLOW_RESULT: {"status":"success","verdict":true}"#;
        let result = parse_devflow_result(bool_verdict).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);

        let numeric_verdict = r#"DEVFLOW_RESULT: {"status":"success","verdict":123}"#;
        let result = parse_devflow_result(numeric_verdict).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);

        let object_verdict = r#"DEVFLOW_RESULT: {"status":"success","verdict":{"x":1}}"#;
        let result = parse_devflow_result(object_verdict).unwrap();
        assert_eq!(result.status, AgentStatus::Success);
        assert_eq!(result.verdict, None);
    }

    /// D-07 (17-01): the two new multi-word variants must serialize with
    /// their word boundary preserved — `#[serde(rename_all = "lowercase")]`
    /// alone would collapse `ResourceKilled` to `"resourcekilled"` (Pitfall 1).
    #[test]
    fn multi_word_variants_serialize_with_word_boundary() {
        assert_eq!(
            serde_json::to_string(&AgentStatus::ResourceKilled).unwrap(),
            "\"resource_killed\""
        );
        assert_eq!(
            serde_json::to_string(&AgentStatus::AgentUnavailable).unwrap(),
            "\"agent_unavailable\""
        );
        assert_eq!(
            serde_json::from_str::<AgentStatus>("\"resource_killed\"").unwrap(),
            AgentStatus::ResourceKilled
        );
        assert_eq!(
            serde_json::from_str::<AgentStatus>("\"agent_unavailable\"").unwrap(),
            AgentStatus::AgentUnavailable
        );
    }

    /// Existing variants must keep their pre-existing lowercase wire form
    /// unchanged by the two new variants' additions.
    #[test]
    fn existing_variants_keep_wire_form() {
        assert_eq!(
            serde_json::to_string(&AgentStatus::Success).unwrap(),
            "\"success\""
        );
        assert_eq!(
            serde_json::to_string(&AgentStatus::Failed).unwrap(),
            "\"failed\""
        );
        assert_eq!(
            serde_json::to_string(&AgentStatus::RateLimited).unwrap(),
            "\"ratelimited\""
        );
        assert_eq!(
            serde_json::to_string(&AgentStatus::Unknown).unwrap(),
            "\"unknown\""
        );
    }

    /// review consensus #1: `as_wire_str()` must never diverge from the serde
    /// form for ANY variant — pin it for all seven via a single round-trip
    /// assertion (quotes stripped).
    ///
    /// 31-02: `IdleTimeout` is enumerated here explicitly rather than left to
    /// the compiler. `as_wire_str`'s wildcard-free match makes a MISSING arm a
    /// compile error, but it cannot catch a WRONG one — an arm returning
    /// `"idletimeout"` compiles happily and diverges from the serde form the
    /// `#[serde(rename)]` produces. Only enumerating the variant here pins that.
    #[test]
    fn as_wire_str_matches_serde_form_for_every_variant() {
        for variant in [
            AgentStatus::Success,
            AgentStatus::Failed,
            AgentStatus::RateLimited,
            AgentStatus::Unknown,
            AgentStatus::ResourceKilled,
            AgentStatus::AgentUnavailable,
            AgentStatus::IdleTimeout,
        ] {
            let serde_form = serde_json::to_string(&variant).unwrap();
            let stripped = serde_form.trim_matches('"');
            assert_eq!(
                variant.as_wire_str(),
                stripped,
                "as_wire_str() diverged from serde form for {variant:?}"
            );
        }
    }

    #[test]
    fn evaluate_layer2_exit_137_is_resource_killed() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_commit(dir.path(), PhaseId::new(20));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(20)), "137").unwrap();
        let state = state_in(dir.path(), PhaseId::new(20));

        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(20),
            &GitFlowConfig::default(),
            state.stage,
        )
        .unwrap()
        .unwrap();

        assert_eq!(result.status, AgentStatus::ResourceKilled);
        assert_eq!(result.exit_code, Some(137));
    }

    #[test]
    fn evaluate_layer2_exit_127_is_agent_unavailable() {
        let dir = tempfile::tempdir().unwrap();
        init_repo_with_feature_commit(dir.path(), PhaseId::new(21));
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), PhaseId::new(21)), "127").unwrap();
        let state = state_in(dir.path(), PhaseId::new(21));

        let result = evaluate_layer2(
            dir.path(),
            PhaseId::new(21),
            &GitFlowConfig::default(),
            state.stage,
        )
        .unwrap()
        .unwrap();

        assert_eq!(result.status, AgentStatus::AgentUnavailable);
        assert_eq!(result.exit_code, Some(127));
    }

    // -----------------------------------------------------------------
    // 27-03 (D-01/D-03): branch-exists + commit-count evidence resolves
    // the caller's own repository under a hostile GIT_DIR, not an
    // unrelated one.
    // -----------------------------------------------------------------

    /// D-03/T-27-08: `evaluate_layer2`'s branch-exists and commit-count
    /// evidence (the two production sites at what were base-commit lines
    /// 574/583) resolves `project_root`'s own repository even when the
    /// process inherited a hostile `GIT_DIR` pointed at an unrelated
    /// repository — proven with a real spawned `git` process, not by
    /// inspecting a `Command` object alone. Mirrors
    /// `version::tests::tag_reads_resolve_caller_root_under_a_hostile_git_dir`
    /// (27-03) and `origin_main_ancestor_status_holds_under_a_hostile_git_dir`
    /// (`git.rs`, 27-01): the hostile `GIT_DIR` this test's own `<verify>`
    /// entries exercise (`GIT_DIR=<hostile>/.git cargo test ... this test`)
    /// is injected the same way any inherited-env attack reaches
    /// `evaluate_layer2` in production — via the whole process's
    /// environment, then down into the spawned child unless the
    /// constructor scrubs it.
    ///
    /// Deliberately tests the mirror direction from the plan's literal
    /// framing (real repo HAS the feature branch with a real commit;
    /// the standard hostile-`GIT_DIR` harness's throwaway repository does
    /// NOT), because the standard harness (`git init -q "$HOSTILE"`, no
    /// `feature/phase-NN` branch) cannot itself manufacture a false
    /// *positive* — an empty repository has no branch to spuriously
    /// report as present. It can, however, still prove the scrub's
    /// necessity by manufacturing a false *negative*: before this plan's
    /// migration, the two unmigrated `Command::new("git")` sites inherit
    /// the poisoned `GIT_DIR` and silently read the hostile repository
    /// instead of `project_root` — `rev-parse --verify` reports the real
    /// branch absent, the commit count is undercounted to zero, and a
    /// real agent's completed work is wrongly classified `Failed`. This
    /// is the same trust-boundary violation T-27-08 names (a foreign
    /// repository's state substituting for the real one), reached from
    /// the opposite direction; the scrub this plan adds removes `GIT_DIR`'s
    /// ability to redirect the spawned child at all, closing both
    /// directions identically.
    /// 27-REVIEW WR-01: this test previously set no hostile environment at
    /// all — it asserted ordinary-path behavior and claimed a hostile-
    /// `GIT_DIR` proof, so it passed identically with or without the scrub
    /// and could never have caught a regression back to a bare
    /// `Command::new("git")`. It now uses the spawned-child shape this
    /// phase established in `staleness.rs`
    /// (`embedded_commit_is_stale_resolves_execution_root_under_a_hostile_git_dir`):
    /// `GIT_DIR` is never set on this process (Rust 2024 `unsafe`, unsound
    /// under threaded tests — Phase 25 D-14), only on one freshly spawned
    /// child that re-invokes this same binary filtered to this one test.
    #[test]
    fn branch_evidence_resolves_caller_root_under_a_hostile_git_dir() {
        const INNER_ROOT: &str = "DEVFLOW_27_03_BRANCH_EVIDENCE_INNER_ROOT";

        if let Ok(root) = std::env::var(INNER_ROOT) {
            // Inner mode: spawned by the outer half below with GIT_DIR
            // pointed at an unrelated foreign repository, scoped to this
            // child process only.
            let root = std::path::PathBuf::from(root);
            let phase = PhaseId::new(27);
            let state = state_in(&root, phase);

            let result = evaluate_layer2(&root, phase, &GitFlowConfig::default(), state.stage)
                .unwrap()
                .unwrap();

            assert_eq!(
                result.status,
                AgentStatus::Success,
                "evaluate_layer2 must see project_root's own branch/commits, \
                 not a hostile GIT_DIR's repository: {result:?}"
            );
            assert_eq!(result.commits, Some(1));
            return;
        }

        // Outer mode: build the real repository (which HAS the feature
        // branch and its commit) plus a second, unrelated foreign
        // repository that has neither. Unscrubbed, the child would read the
        // foreign repo, find no branch, count zero commits, and misreport a
        // real agent's completed work as Failed.
        let dir = tempfile::tempdir().unwrap();
        let phase = PhaseId::new(27);
        init_repo_with_feature_commit(dir.path(), phase);
        std::fs::create_dir_all(dir.path().join(".devflow")).unwrap();
        std::fs::write(exit_code_path(dir.path(), phase), "0").unwrap();

        let foreign = tempfile::tempdir().unwrap();
        git(foreign.path(), &["init", "-q"]);

        let exe = std::env::current_exe().expect("current_exe for child re-invocation");
        let out = std::process::Command::new(&exe)
            // Substring filter, NOT `--exact`: the binary's real test name is
            // module-qualified (`agent_result::tests::branch_evidence_...`),
            // so `--exact` against the bare name matches nothing, runs zero
            // tests, and still exits 0 — a false green.
            .arg("branch_evidence_resolves_caller_root_under_a_hostile_git_dir")
            .arg("--test-threads=1")
            .env(INNER_ROOT, dir.path().to_str().unwrap())
            .env("GIT_DIR", foreign.path().join(".git"))
            .output()
            .expect("spawn hostile child test process");

        let stdout = String::from_utf8_lossy(&out.stdout);
        // Assert the child actually RAN the test, not merely that it exited
        // 0. A filter matching nothing exits 0 with "0 passed".
        assert!(
            stdout.contains("1 passed"),
            "child test process must have run exactly the inner test; \
             stdout:\n{stdout}"
        );
        assert!(
            out.status.success(),
            "child test process (hostile GIT_DIR pointed at an unrelated \
             foreign repository) must still resolve project_root's own \
             branch and commits; child exit status {:?}\nstdout:\n{stdout}",
            out.status
        );
    }

    /// D-01 (33-CONTEXT.md): `phase_verification_exists` is the sole signal
    /// a Validate→Code loop-back consults to tell a mid-arc phase apart from
    /// a genuinely gap-flagged one. Covers all three states: no
    /// `.planning/phases` directory at all, a phase directory with no
    /// verification artifact, and a phase directory that has one — mirroring
    /// `phase_review_path`'s directory-prefix-scan idiom.
    #[test]
    fn phase_verification_exists_finds_the_artifact_by_prefix() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();

        assert!(
            !phase_verification_exists(root, PhaseId::new(82)),
            "no .planning/phases directory at all must return false, not panic"
        );

        let phase_dir = root.join(".planning/phases/82-loop-back-fix");
        std::fs::create_dir_all(&phase_dir).unwrap();
        assert!(
            !phase_verification_exists(root, PhaseId::new(82)),
            "a phase directory with no {{N}}-VERIFICATION.md must return false"
        );

        std::fs::write(phase_dir.join("82-VERIFICATION.md"), "verified\n").unwrap();
        assert!(
            phase_verification_exists(root, PhaseId::new(82)),
            "a phase directory holding {{N}}-VERIFICATION.md must return true"
        );
    }

    /// 999.79 (35-05): the fingerprint must be a function of the artifact's
    /// BYTES, not of its existence.
    ///
    /// Both halves are required and neither is redundant. The first half
    /// (different bytes → different values) is satisfied by any hash. The
    /// second half (identical bytes → identical values) is what rules out a
    /// value derived from something incidental — a timestamp, an inode, a
    /// counter — which would make every check read "changed" and permanently
    /// disable the gaps-only path. A constant-returning implementation fails
    /// the first half; a nondeterministic one fails the second.
    #[test]
    fn phase_verification_fingerprint_differs_when_content_differs() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let phase_dir = root.join(".planning/phases/84-fingerprint");
        std::fs::create_dir_all(&phase_dir).unwrap();
        let artifact = phase_dir.join("84-VERIFICATION.md");

        std::fs::write(&artifact, "verdict: gaps\n").unwrap();
        let first = phase_verification_fingerprint(root, PhaseId::new(84))
            .expect("an artifact that exists must produce a fingerprint");

        let first_again = phase_verification_fingerprint(root, PhaseId::new(84))
            .expect("an artifact that exists must produce a fingerprint");
        assert_eq!(
            first, first_again,
            "identical bytes must produce identical fingerprints — a value that changes on \
             its own would mark every artifact fresh forever and disable the stale check"
        );

        std::fs::write(&artifact, "verdict: pass\n").unwrap();
        let second = phase_verification_fingerprint(root, PhaseId::new(84))
            .expect("an artifact that exists must produce a fingerprint");
        assert_ne!(
            first, second,
            "different bytes must produce different fingerprints — a constant implementation \
             would report every re-authored artifact as unchanged"
        );
    }

    /// 999.79 (35-05): an absent artifact yields no fingerprint, which is
    /// distinguishable from an artifact whose content happens to hash to zero.
    /// Both are asserted here so "absent" can never be conflated with "hashed
    /// to the zero value".
    #[test]
    fn phase_verification_fingerprint_is_none_when_the_artifact_is_absent() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();

        assert_eq!(
            phase_verification_fingerprint(root, PhaseId::new(85)),
            None,
            "no .planning/phases directory at all must yield None, not panic"
        );

        let phase_dir = root.join(".planning/phases/85-fingerprint");
        std::fs::create_dir_all(&phase_dir).unwrap();
        assert_eq!(
            phase_verification_fingerprint(root, PhaseId::new(85)),
            None,
            "a phase directory with no {{N}}-VERIFICATION.md must yield None"
        );

        std::fs::write(phase_dir.join("85-VERIFICATION.md"), "").unwrap();
        let empty = phase_verification_fingerprint(root, PhaseId::new(85));
        assert!(
            empty.is_some(),
            "an EMPTY artifact still exists and must yield Some — the control against an \
             implementation that conflates 'absent' with 'no bytes'"
        );
    }
}