Skip to main content

magi/
agent.rs

1//! Driving agent CLIs.
2//!
3//! Every agent in magi is a subscription CLI (`claude`, `opencode`, `agy`) or
4//! an arbitrary command, invoked headless in a working directory. There is no
5//! API-key path on purpose: the CLIs carry the operator's own plan, and they
6//! are the only interface that exposes an agent's whole tool loop rather than a
7//! single completion.
8//!
9//! # Seats, not agents
10//!
11//! Conversations are keyed by *seat* ([`SeatState::key`]), never by agent id. A
12//! model that implements candidate B and also sits as judge 3 gets two
13//! unrelated conversations, so the judge cannot recognise its own work from
14//! having written it. Sessions are what make deliberation affordable — a judge
15//! remembers its own argument instead of being re-fed the entire candidate set
16//! — and seat scoping is what keeps that from destroying blindness.
17//!
18//! # Session mechanics per CLI
19//!
20//! | CLI | open | resume |
21//! |-----|------|--------|
22//! | `claude` | `--session-id <uuid>` (magi mints it) | `--resume <uuid>` |
23//! | `opencode` | `--format json` reports `sessionID` | `-s <id>` |
24//! | `agy` | `--output-format json` reports `conversation_id` | `--conversation <id>` |
25//! | `codex` | `exec --json` reports `thread.started.thread_id` | `exec … resume <id>` |
26//! | `omp` | `-p --mode=json` reports `id` on its `"type":"session"` line | `--resume <id>` |
27//!
28//! Claude is the only one magi can address before the first turn; the others
29//! report an id back, so [`SeatState::captured_session`] stays `None` until a
30//! turn has completed and [`has_session`] answers honestly instead of
31//! optimistically.
32use std::collections::BTreeMap;
33use std::path::{Path, PathBuf};
34use std::process::Stdio;
35use std::time::{Duration, Instant};
36
37use anyhow::{Context as _, Result, bail};
38use serde::{Deserialize, Serialize};
39use std::sync::{Arc, Mutex};
40
41use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
42use tokio::process::Command;
43
44use crate::config::{AgentChoice, AgentKind, AgentSpec, Delivery};
45use crate::proc::Quiet as _;
46use crate::rng::SplitMix64;
47
48/// Conversation state for one seat, persisted with the run so `magi run
49/// --resume` continues the same CLI conversations.
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51pub struct SeatState {
52    /// Stable seat name, e.g. `impl-A`, `judge-2`, `review-1`, `fix`.
53    pub key: String,
54    /// Agent id occupying the seat.
55    pub agent: String,
56    /// Turns already taken in this seat.
57    pub turns: usize,
58    /// Claude session uuid, minted up front so the first turn and every resume
59    /// agree on it without parsing anything back.
60    pub claude_session: Option<String>,
61    /// Session id reported by a CLI that mints its own (`opencode`, `agy`).
62    pub captured_session: Option<String>,
63}
64
65impl SeatState {
66    /// New seat. `run_seed` scopes the minted Claude uuid to this run.
67    pub fn new(key: &str, agent: &str, run_seed: u64) -> Self {
68        let mut rng = SplitMix64::new(run_seed ^ crate::rng::fnv1a(key));
69        Self {
70            key: key.to_owned(),
71            agent: agent.to_owned(),
72            turns: 0,
73            claude_session: Some(rng.uuid_v4()),
74            captured_session: None,
75        }
76    }
77}
78
79/// Can a follow-up prompt rely on this seat remembering the conversation?
80pub fn has_session(kind: AgentKind, seat: &SeatState, sessions_enabled: bool) -> bool {
81    if !sessions_enabled || seat.turns == 0 {
82        return false;
83    }
84    match kind {
85        AgentKind::Claude => seat.claude_session.is_some(),
86        AgentKind::Opencode | AgentKind::Antigravity | AgentKind::Codex | AgentKind::Omp => {
87            seat.captured_session.is_some()
88        }
89        AgentKind::Command => true,
90    }
91}
92
93/// One agent invocation.
94#[derive(Debug, Clone)]
95pub struct Invocation<'a> {
96    /// Rendered repository coordination policy for this invocation.
97    pub coordination: Option<&'a crate::config::Coordination>,
98    /// Launcher fetch evidence, unchanged on session resume.
99    pub fetched_base: Option<&'a crate::run::FetchedBase>,
100    /// Working directory. Always a real checkout, so every CLI can read the
101    /// repository without per-vendor "extra directory" flags.
102    pub cwd: &'a Path,
103    /// The full prompt.
104    pub prompt: &'a str,
105    /// Wall-clock limit; the process tree is killed when it elapses.
106    pub timeout: Duration,
107    /// May the agent modify files? Judges and reviewers may not. Together
108    /// with an editing node (see [`repository_writer`]) it also drops a codex
109    /// seat's OS sandbox and approval gate, as claude's `bypassPermissions`
110    /// does for every claude seat.
111    pub allow_write: bool,
112    /// Continue this seat's conversation when the CLI supports it.
113    pub sessions: bool,
114    /// Directory for prompt / stdout / stderr artifacts.
115    pub artifacts: &'a Path,
116    /// Artifact filename stem.
117    pub stem: &'a str,
118    /// Run this invocation belongs to. Exported as `MAGI_RUN` so an agent that
119    /// files a task with `magi task add` is attributed to the run that was
120    /// paying for it, rather than looking like a human wandered by.
121    pub run: &'a str,
122    /// Graph node being executed, e.g. `implement` or `review`. Exported as
123    /// `MAGI_NODE` for the same reason: "who asked for this" is the first
124    /// question about an autonomously created task.
125    pub node: &'a str,
126    /// Shared build cache the seat should build into, from the rendered
127    /// `CARGO_TARGET_DIR=` in the verify commands. Exported as
128    /// `CARGO_TARGET_DIR` so the implementer's compile lands inside the same
129    /// directory `verify` reads back from - one cache, one prune, and the
130    /// build the agent just paid for is the build the gate reuses.
131    pub cache_dir: Option<&'a Path>,
132    /// Absolute paths of images the operator attached to this conversation,
133    /// outside `cwd` - see `chat`/`talk`'s `attachments_dir`. Empty for every
134    /// invocation that is not a chat or talk turn. [`build_command`] uses
135    /// this only to decide whether a CLI's sandbox needs widening to read
136    /// them; the prompt text naming each path and its mime is built by the
137    /// caller, not here.
138    pub attachments: &'a [PathBuf],
139    /// Directories outside `cwd` the seat may write, when it may write at all.
140    /// Explicit, purpose-specific grants (for example a deputy's stores).
141    /// Repository editing seats also receive the shared Git directory and
142    /// question control-plane directories in [`invoke`]; adapters that widen
143    /// a workspace per directory (agy's `--add-dir`) need them, while a codex
144    /// editing seat runs without a sandbox and ignores them.
145    pub writable: &'a [PathBuf],
146}
147
148/// A repository editing seat: implementer, fixer, grafter, gate fixer, land
149/// or rebase resolver, or a chat turn the repository opted into writing.
150///
151/// For codex this is also the whole sandbox policy: these seats run with
152/// `--dangerously-bypass-approvals-and-sandbox` (owner decision 2026-10-27),
153/// matching claude's `bypassPermissions`, because codex's seatbelt sandbox
154/// refuses `$TMPDIR` and aborts Chrome, so repository tests cannot run inside
155/// it. Every other seat keeps its sandbox.
156fn repository_writer(inv: &Invocation<'_>) -> bool {
157    inv.allow_write
158        && (matches!(
159            inv.node,
160            "implement"
161                | "fix"
162                | "graft"
163                | "gate-fix"
164                | "land"
165                | "rebase"
166                | "base-conflict"
167                | "external-chat"
168        ) || inv.node == crate::queue::CHAT_NODE)
169}
170
171fn repository_seat(inv: &Invocation<'_>) -> bool {
172    // These roles consume supplied state, prompts and conversation history.
173    // In particular, they must be able to deliver an answer or make queue
174    // decisions while an editor holds its reservation waiting for that answer.
175    // Chat turns and their transcript-only title seats bypass repository
176    // scheduling, including waiter delivery.
177    !matches!(
178        inv.node,
179        crate::queue::CHAT_NODE | "external-chat" | "talk-title" | "deputy" | "conduct" | "dupes"
180    )
181}
182
183/// Resolve the additional write scope for a repository editing seat.
184///
185/// Resolve Git's common directory from the actual seat checkout, never by
186/// assuming `.git` is a directory. Canonicalize directories before handing
187/// them to a sandbox (notably `/tmp` aliases on macOS). Failure is a startup
188/// error: do not start work with an unusable lock/question route.
189pub async fn worktree_writable_roots(cwd: &Path, home: &Path) -> Result<Vec<PathBuf>> {
190    let mut roots = Vec::new();
191    if let Some(common) = crate::repo_lock::common_dir(cwd).await? {
192        let cwd = std::fs::canonicalize(cwd).context("canonicalize seat working directory")?;
193        if !common.starts_with(&cwd) {
194            roots.push(common);
195        }
196    }
197    // Questions::put/update/beat/panels write questions. Its quiet_for hook
198    // updates matching notifications. Neither needs queue, runs, talks, nor
199    // the entire state directory.
200    for name in ["questions", "notifications"] {
201        let dir = home.join(name);
202        std::fs::create_dir_all(&dir).with_context(|| format!("prepare seat {name} directory"))?;
203        roots.push(std::fs::canonicalize(dir)?);
204    }
205    Ok(roots)
206}
207
208/// Current-turn instructions override stale fetch requirements in history.
209fn editing_access_note(base: Option<&crate::run::FetchedBase>) -> String {
210    let mut note = String::from(
211        "Launcher repository access contract (applies to this turn and overrides earlier fetch instructions):\n",
212    );
213    if let Some(base) = base {
214        note.push_str(&format!(
215            "The launcher successfully fetched `{}/{}` at {} and pinned the run base to `{}`. Use this exact local commit as the verified fetched base; this is a snapshot, not a claim that the remote has not moved since. Do not fetch again as a prerequisite, move the base, or refresh it on resume. Base updates belong to the launcher's existing base-sync path.\n",
216            base.remote, base.branch, base.fetched_at, base.commit,
217        ));
218    } else {
219        note.push_str("No successful launcher fetch evidence is supplied for this invocation. Do not describe local tracking refs as freshly fetched. If fresh remote evidence is essential, report an infrastructure blocker requiring a launcher fetch and a new prepared turn.\n");
220    }
221    note
222}
223
224/// Evidence of a CLI usage limit or authentication outage, distinct from an
225/// ordinary task failure.
226///
227/// `reset` is free text: CLIs render the reset time in their own locale, and
228/// parsing it exactly would be a bug factory. When it is not readable we say
229/// nothing rather than invent a format.
230#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
231pub struct Quota {
232    /// Machine-side cause; old records describe a usage limit.
233    #[serde(default)]
234    pub cause: QuotaCause,
235    /// Agent id, filled by the invocation boundary.
236    #[serde(default)]
237    pub agent: String,
238    /// Human-readable reset time, when the CLI printed one.
239    #[serde(default)]
240    pub reset: Option<String>,
241}
242
243/// Why an invocation needs machine-side recovery rather than a task retry.
244#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
245#[serde(rename_all = "snake_case")]
246pub enum QuotaCause {
247    /// Subscription usage must reset or be replenished.
248    #[default]
249    UsageLimit,
250    /// The operator must restore the CLI's authenticated session.
251    Authentication,
252}
253
254/// A CLI hung up on its own stream while the agent was working.
255///
256/// Separate from a failure because the work was done and billed, and separate
257/// from a [`Quota`] because it is worth asking again: the answer is in the
258/// conversation, not lost to a limit that has to reset first. See
259/// [`dropped_stream`].
260#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
261pub struct Dropped {
262    /// What the CLI said as it hung up, verbatim.
263    pub why: String,
264    /// Output tokens the CLI reported before it did - the evidence that this
265    /// was a delivery failure and not an agent that produced nothing.
266    pub output_tokens: u64,
267}
268
269/// One command a CLI's own structured event stream reported running, with
270/// the result it reported for it.
271///
272/// This is evidence the CLI chose to report about its own tool loop — never
273/// something magi polled, supervised, or inferred from a process list. Only
274/// the Codex arm of [`extract`] currently populates it (its `item.completed`
275/// / `command_execution` events name `id`, `command`, `exit_code` and
276/// `aggregated_output` directly); every other backend's CLI does not expose
277/// this in what magi currently captures, so its seats simply never produce
278/// any. A command a CLI never reported finishing (still running when the
279/// turn ended, or the event stream never named it) has no entry here either
280/// — there is no event to build one from, and this type must never be used
281/// to *guess* that a command is still in flight.
282#[derive(Debug, Clone, Serialize, Deserialize)]
283pub struct CommandEvidence {
284    /// The CLI's own id for this command.
285    pub id: String,
286    /// The command itself, as the CLI reported it.
287    pub description: String,
288    /// Exit code the CLI reported for it.
289    pub exit_code: Option<i32>,
290    /// Tail of the command's own output, when the CLI reported one.
291    pub result_summary: String,
292    /// Which CLI/event stream this came from, e.g. `"codex"`.
293    pub source: String,
294}
295
296/// Result of an agent invocation.
297#[derive(Debug, Clone, Serialize, Deserialize)]
298pub struct AgentOutput {
299    /// The agent's final message, extracted from whatever the CLI printed.
300    pub text: String,
301    /// Exit status code.
302    pub exit_code: Option<i32>,
303    /// Did the invocation hit its timeout?
304    pub timed_out: bool,
305    /// Wall-clock duration.
306    pub duration_ms: u64,
307    /// Artifact file names, relative to the run's `artifacts/` directory.
308    pub artifacts: Vec<String>,
309    /// Usage limit or authentication outage, when distinguishable from a normal
310    /// failure. `None` for a normal failure, a timeout, or a CLI we cannot
311    /// read — the conservative default.
312    #[serde(default)]
313    pub quota: Option<Quota>,
314    /// The CLI hung up on its own stream after the agent had done billed
315    /// work. `None` unless that exact shape was recognised — see
316    /// [`dropped_stream`].
317    #[serde(default)]
318    pub dropped: Option<Dropped>,
319    /// Commands the CLI's own event stream reported running, see
320    /// [`CommandEvidence`]. Always empty for a backend this crate does not
321    /// currently read structured job events from.
322    #[serde(default)]
323    pub commands: Vec<CommandEvidence>,
324    /// Input-side tokens the CLI reported for this turn - approximately the
325    /// size of the context the model just read. `None` when the CLI reports
326    /// no usage (or in a shape this build does not read): unknown, never 0.
327    /// See [`context_tokens`].
328    #[serde(default)]
329    pub context_tokens: Option<u64>,
330}
331
332impl AgentOutput {
333    /// Did the CLI exit cleanly with something to say?
334    pub fn usable(&self) -> bool {
335        !self.quota_exhausted()
336            && !self.timed_out
337            && self.exit_code == Some(0)
338            && !self.text.trim().is_empty()
339    }
340
341    /// Does this invocation need machine-side quota or authentication recovery?
342    pub fn quota_exhausted(&self) -> bool {
343        self.quota.is_some()
344    }
345
346    /// Did the agent work and the CLI fail to deliver it?
347    ///
348    /// Worth re-asking, unlike [`AgentOutput::quota_exhausted`]: the answer is
349    /// in a conversation this process can resume.
350    pub fn work_undelivered(&self) -> bool {
351        self.dropped.is_some()
352    }
353}
354
355/// Typed context distinguishing an interrupted process from admission that
356/// never spawned one. ResourceBlocked remains in the error chain for parking.
357#[derive(Debug)]
358pub(crate) struct ExecutionInterrupted(pub String);
359
360impl std::fmt::Display for ExecutionInterrupted {
361    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
362        write!(f, "execution interrupted: {}", self.0)
363    }
364}
365
366impl std::error::Error for ExecutionInterrupted {}
367
368/// How long to keep reading a pipe after the child is gone.
369///
370/// Bounded on purpose: a surviving grandchild can hold the write end open
371/// forever, and the graph must not hang on a process it has already killed.
372const PIPE_GRACE: Duration = Duration::from_secs(3);
373
374/// Bytes a pipe reader has accumulated so far, shared with whoever spawned it.
375pub(crate) type Captured = Arc<Mutex<Vec<u8>>>;
376
377/// Read `pipe` to end in its own task, appending into a buffer the caller can
378/// inspect at any time.
379///
380/// The buffer is shared rather than returned because the interesting moment is
381/// exactly the one where the reader has *not* finished: a killed agent's pipe
382/// may still be held open by a surviving grandchild, and the bytes that did
383/// arrive are the only evidence of what it was doing. An earlier version
384/// returned the buffer from the task and dropped it on timeout, which is how
385/// `<stem>.out` came to be empty on every timeout.
386pub(crate) fn drain<R>(pipe: Option<R>) -> (Captured, Option<tokio::task::JoinHandle<()>>)
387where
388    R: tokio::io::AsyncRead + Unpin + Send + 'static,
389{
390    let buf: Captured = Arc::new(Mutex::new(Vec::new()));
391    let Some(mut pipe) = pipe else {
392        return (buf, None);
393    };
394    let sink = Arc::clone(&buf);
395    let handle = tokio::spawn(async move {
396        let mut chunk = [0u8; 8192];
397        loop {
398            match pipe.read(&mut chunk).await {
399                Ok(0) | Err(_) => break,
400                Ok(n) => {
401                    if let Ok(mut guard) = sink.lock() {
402                        guard.extend_from_slice(&chunk[..n]);
403                    }
404                }
405            }
406        }
407    });
408    (buf, Some(handle))
409}
410
411/// Take whatever a reader has captured, giving it at most `grace` to finish.
412///
413/// A reader still blocked after that is abandoned, not awaited — but its bytes
414/// come back either way, which is the whole point.
415pub(crate) async fn collect(
416    buf: &Captured,
417    handle: Option<tokio::task::JoinHandle<()>>,
418    grace: Duration,
419) -> String {
420    if let Some(handle) = handle {
421        if tokio::time::timeout(grace, handle).await.is_err() {
422            tracing::debug!("a pipe is still held open after the child exited");
423        }
424    }
425    let bytes = buf.lock().map(|g| g.clone()).unwrap_or_default();
426    String::from_utf8_lossy(&bytes).into_owned()
427}
428
429/// Invoke `spec` for `seat`, updating the seat's conversation state.
430pub async fn invoke(
431    spec: &AgentSpec,
432    seat: &mut SeatState,
433    inv: &Invocation<'_>,
434) -> Result<AgentOutput> {
435    // Wait for repository scheduling before spawning or starting a seat's
436    // budget. Readers hold the real lock; editors exclude local readers while
437    // taking their own repository-prescribed lock inside the seat. Running
438    // owns the lease through descendant cleanup on cancel.
439    let lease = if repository_seat(inv) {
440        crate::repo_lock::SeatLease::for_checkout(inv.cwd, inv.allow_write, inv.coordination)
441            .await?
442    } else {
443        None
444    };
445    let inv = &Invocation {
446        timeout: spec.turn_timeout(inv.timeout),
447        ..inv.clone()
448    };
449    let mut outputs = Vec::new();
450    if repository_writer(inv) {
451        let min_free = crate::run::RunState::load_under(inv.run, &crate::run::home())
452            .map_or(0, |state| state.config.disk.min_free_bytes);
453        let mut paths = vec![inv.cwd.to_owned()];
454        if let Some(cache) = inv.cache_dir {
455            paths.push(cache.to_owned());
456        }
457        outputs.extend(
458            crate::retention::OutputLease::admit(&crate::run::home(), &paths, min_free)
459                .map_err(|e| crate::repo_lock::ResourceBlocked(format!("disk admission: {e:#}")))?,
460        );
461    }
462    if repository_seat(inv) {
463        if let Some(guard) = crate::retention::OutputLease::borrow(inv.cwd).map_err(|e| {
464            crate::repo_lock::ResourceBlocked(format!("worktree output ownership: {e:#}"))
465        })? {
466            outputs.push(guard);
467        }
468        if let Some(cache) = inv.cache_dir {
469            outputs.push(crate::retention::OutputLease::cache(
470                &crate::run::home(),
471                cache,
472                false,
473            )?);
474        }
475    }
476
477    let mut prompt = inv.prompt.to_owned();
478    if inv.node == crate::queue::CHAT_NODE {
479        prompt.push_str("\n\n");
480        prompt.push_str(crate::prompt::CHAT_FOLLOW_THROUGH);
481    }
482    if let Some(lease) = lease.as_ref().filter(|lease| lease.delegated) {
483        prompt.push_str(&format!("\n\nRepository coordination: the launcher holds the exclusive repository lock at {} for this invocation. Do not acquire a second lock or release/delete it. Repository access remains read-only.", lease.path.display()));
484    }
485    // Apply once for initial, resumed, fallback and waiter invocations alike.
486    // Deputies/chat retain their explicit grants; read-only stays read-only.
487    let home = repository_writer(inv).then(crate::run::home);
488    let mut writable = inv.writable.to_vec();
489    if let Some(home) = &home {
490        for root in worktree_writable_roots(inv.cwd, home).await? {
491            if !writable.contains(&root) {
492                writable.push(root);
493            }
494        }
495    }
496    if repository_writer(inv) {
497        prompt.push_str("\n\n");
498        prompt.push_str(&editing_access_note(inv.fetched_base));
499    }
500    let inv = &Invocation {
501        writable: &writable,
502        prompt: &prompt,
503        ..inv.clone()
504    };
505    tokio::fs::create_dir_all(inv.artifacts)
506        .await
507        .with_context(|| format!("create {}", inv.artifacts.display()))?;
508    let prompt_path = inv.artifacts.join(format!("{}.prompt.md", inv.stem));
509    tokio::fs::write(&prompt_path, inv.prompt)
510        .await
511        .with_context(|| format!("write {}", prompt_path.display()))?;
512
513    let plan = build_command(spec, seat, inv, &prompt_path)?;
514    tracing::debug!(seat = %seat.key, agent = %spec.id, argv = ?plan.logged_argv(), "spawning agent");
515    // Store scope evidence without environment values or arbitrary extra args.
516    tokio::fs::write(
517        inv.artifacts.join(format!("{}.access.json", inv.stem)),
518        serde_json::to_vec_pretty(&serde_json::json!({
519            "launcher_version": env!("CARGO_PKG_VERSION"),
520            "kind": spec.kind,
521            "allow_write": inv.allow_write,
522            "unsandboxed": repository_writer(inv),
523            "writable_roots": inv.writable,
524            "fetched_base": inv.fetched_base,
525        }))?,
526    )
527    .await
528    .context("write seat access evidence")?;
529
530    let started = Instant::now();
531    // Resolve against the PATH the child will actually see: `spec.env` may
532    // override it, and the resolved absolute path bypasses any later lookup.
533    let child_path = spec
534        .env
535        .iter()
536        .find(|(k, _)| k.eq_ignore_ascii_case("PATH"))
537        .map(|(_, v)| std::ffi::OsString::from(v))
538        .or_else(|| std::env::var_os("PATH"))
539        .unwrap_or_default();
540    let program = crate::config::find_program_on(&plan.argv[0], &child_path).map_or_else(
541        || plan.argv[0].clone().into(),
542        std::path::PathBuf::into_os_string,
543    );
544    let mut cmd = Command::new(program);
545    cmd.args(&plan.argv[1..])
546        .current_dir(inv.cwd)
547        .envs(&spec.env)
548        .env("MAGI_SEAT", &seat.key)
549        .env("MAGI_TURN", seat.turns.to_string())
550        .env("MAGI_RUN", inv.run)
551        .env("MAGI_NODE", inv.node)
552        .env("MAGI_PROMPT_FILE", &prompt_path)
553        .env("MAGI_ALLOW_WRITE", if inv.allow_write { "1" } else { "0" })
554        .env("GIT_TERMINAL_PROMPT", "0")
555        .stdin(if plan.stdin.is_some() {
556            Stdio::piped()
557        } else {
558            Stdio::null()
559        })
560        .stdout(Stdio::piped())
561        .stderr(Stdio::piped())
562        .kill_on_drop(true)
563        // No console window. `magi web` has no console of its own, so Windows
564        // would give each agent a fresh one - and draw it. See `crate::proc`.
565        .quiet();
566    crate::incremental::default_environment(&mut cmd);
567    if repository_writer(inv) {
568        crate::incremental::configure(&mut cmd, inv.cwd)?;
569    }
570    if let Some(home) = home {
571        // Match the control-plane store we granted, even with a relative
572        // MAGI_HOME or a per-agent environment override.
573        cmd.env("MAGI_HOME", std::fs::canonicalize(home)?);
574    }
575    if let Some(cache) = inv.cache_dir {
576        // Same directory the verify commands build into: one cache to prune,
577        // and the compile the seat pays for is the compile the gate reuses.
578        cmd.env("CARGO_TARGET_DIR", cache);
579    } else {
580        // `Command` inherits this process's environment by default, so
581        // simply not setting the variable here is not the same as the seat
582        // not seeing it: if the magi process itself is running under a
583        // shared `CARGO_TARGET_DIR` (the ordinary case), a read-only seat
584        // would otherwise inherit that exact path and try to build there
585        // anyway - the write refusal this is meant to prevent in the first
586        // place. Strip it explicitly.
587        cmd.env_remove("CARGO_TARGET_DIR");
588    }
589
590    #[cfg(any(unix, windows))]
591    let _chat_controls = {
592        use crate::chat_control::bridge::{self, Bridge};
593        // Strip inherited and per-agent capabilities for every invocation,
594        // including external-chat; only an ordinary owner chat gets a new one.
595        bridge::clear_environment(&mut cmd);
596        let bridge = if inv.node == crate::queue::CHAT_NODE {
597            crate::run::try_home().and_then(|home| {
598                match Bridge::start(&home, inv.run, inv.artifacts) {
599                    Ok(bridge) => Some(bridge),
600                    Err(error) => {
601                        tracing::warn!(%error, "chat controls unavailable; continuing conversation");
602                        None
603                    }
604                }
605            })
606        } else {
607            None
608        };
609        if let Some(bridge) = &bridge {
610            // Read-only chat CLIs also authorize against the launcher's talk
611            // store before dispatching through the bridge. Match its home
612            // without granting the child filesystem write access.
613            cmd.env("MAGI_HOME", std::fs::canonicalize(crate::run::home())?);
614            bridge.attach(&mut cmd);
615        }
616        bridge
617    };
618
619    let mut running = crate::seat_process::Running::spawn(cmd, lease, outputs)
620        .with_context(|| format!("spawn `{}` for seat {}", plan.argv[0], seat.key))?;
621    // Feed stdin from a task rather than inline: a `command` agent that never
622    // reads its stdin, or a prompt larger than the pipe buffer, would
623    // otherwise deadlock here before the process is ever waited on.
624    if let (Some(body), Some(mut sink)) = (plan.stdin.clone(), running.child().stdin.take()) {
625        tokio::spawn(async move {
626            sink.write_all(body.as_bytes()).await.ok();
627            sink.shutdown().await.ok();
628        });
629    }
630
631    // Drain the pipes in their own tasks, and wait on the *process*, not on
632    // end-of-file. Two failures come out of conflating those:
633    //
634    // 1. `wait_with_output` returns when both pipes reach EOF, which is not
635    //    when the child exits. A CLI that leaves a helper process holding the
636    //    inherited stdout handle - normal on Windows, where a `.cmd` shim and
637    //    its grandchildren share handles - never closes the pipe, so a seat
638    //    that answered in five minutes was billed the full hour and then
639    //    recorded as a timeout. The answer was thrown away with it.
640    // 2. Cancelling `wait_with_output` at the timeout drops the buffers it
641    //    owned, so `<stem>.out` and `<stem>.err` were written empty exactly
642    //    when an operator needs them most. "It printed nothing" and "we
643    //    discarded what it printed" looked identical on disk.
644    //
645    // Now the readers own the bytes, so a timeout keeps whatever arrived, and
646    // the wait ends at exit even if a stray handle stays open.
647    let (out_buf, out_reader) = drain(running.child().stdout.take());
648    let (err_buf, err_reader) = drain(running.child().stderr.take());
649
650    let min_free = crate::run::RunState::load_under(inv.run, &crate::run::home())
651        .ok()
652        .map_or(0, |state| state.config.disk.min_free_bytes);
653    #[cfg(all(test, unix))]
654    let min_free = test_watchdog::floor(inv.run, min_free);
655    let mut paths = vec![inv.cwd.to_owned()];
656    if let Some(cache) = inv.cache_dir {
657        paths.push(cache.to_owned());
658    }
659    let mut pressure = None;
660    let waited = tokio::select! {
661        waited = tokio::time::timeout(inv.timeout, running.child().wait()) => Some(waited),
662        reason = crate::retention::emergency(paths, min_free) => {
663            pressure = Some(reason);
664            None
665        }
666    };
667    let (code, timed_out) = match waited {
668        Some(Ok(res)) => {
669            let status = res.with_context(|| format!("wait for seat {}", seat.key))?;
670            (status.code(), false)
671        }
672        Some(Err(_)) | None => {
673            if let Some(reason) = &pressure {
674                tracing::warn!(seat = %seat.key, %reason, "agent execution interrupted");
675            } else {
676                tracing::warn!(seat = %seat.key, secs = inv.timeout.as_secs(), "agent timed out");
677            }
678            // Wait for CLI termination before releasing its repository lease.
679            if !running.coordinated() {
680                running
681                    .child()
682                    .kill()
683                    .await
684                    .context("stop timed-out seat")?;
685            }
686            (None, true)
687        }
688    };
689    running.finish().await;
690
691    // The child is gone either way, so the readers are bounded now. A grace
692    // window rather than an unbounded await: a surviving grandchild can still
693    // hold the write end open, and losing a few trailing bytes beats hanging
694    // the graph on a process we no longer control.
695    let stdout = collect(&out_buf, out_reader, PIPE_GRACE).await;
696    let stderr = collect(&err_buf, err_reader, PIPE_GRACE).await;
697
698    let out_path = inv.artifacts.join(format!("{}.out", inv.stem));
699    let err_path = inv.artifacts.join(format!("{}.err", inv.stem));
700    tokio::fs::write(&out_path, &stdout).await.ok();
701    tokio::fs::write(&err_path, &stderr).await.ok();
702    if let Some(reason) = pressure {
703        return Err(
704            anyhow::Error::new(crate::repo_lock::ResourceBlocked(reason.clone()))
705                .context(ExecutionInterrupted(reason)),
706        );
707    }
708
709    if code != Some(0)
710        && (stdout.contains(crate::incremental::BLOCKED)
711            || stderr.contains(crate::incremental::BLOCKED))
712    {
713        let detail = if stderr.contains(crate::incremental::BLOCKED) {
714            &stderr
715        } else {
716            &stdout
717        };
718        return Err(crate::repo_lock::ResourceBlocked(tail_chars(detail, 2000)).into());
719    }
720
721    let mut extracted = extract(spec.kind, &stdout);
722    if spec.kind == AgentKind::Antigravity && extracted.quota.is_none() {
723        extracted.quota = agy_quota(&stdout, &stderr);
724    }
725    if let Some(quota) = &mut extracted.quota {
726        quota.agent.clone_from(&spec.id);
727        if quota.cause == QuotaCause::Authentication {
728            let _ = crate::notices::Notices::open().raise(crate::notices::Notice::warn(
729                &format!("agent-authentication:{}", spec.id),
730                format!("Agent `{}` cannot authenticate. Re-authenticate this agent, then resume the held task.", spec.id),
731            ));
732        }
733        // A quota response carries usage too, so it can look like a dropped
734        // stream; a rate limit is never worth re-asking, so it wins.
735        extracted.dropped = None;
736        tracing::warn!(
737            seat = %seat.key,
738            agent = %spec.id,
739            reset = ?quota.reset,
740            cause = ?quota.cause,
741            "agent needs machine-side recovery"
742        );
743    }
744    if let Some(session) = extracted.session {
745        match spec.kind {
746            AgentKind::Claude => seat.claude_session = Some(session),
747            AgentKind::Opencode | AgentKind::Antigravity | AgentKind::Codex | AgentKind::Omp => {
748                seat.captured_session = Some(session);
749            }
750            AgentKind::Command => {}
751        }
752    }
753    if let Some(status) = &extracted.status
754        && !status.eq_ignore_ascii_case("success")
755    {
756        tracing::warn!(seat = %seat.key, status = %status, "agent reported a non-success status");
757    }
758    let text = if extracted.text.trim().is_empty() {
759        // A CLI that printed only to stderr still told us something.
760        if stdout.trim().is_empty() {
761            stderr.trim().to_owned()
762        } else {
763            stdout.trim().to_owned()
764        }
765    } else {
766        extracted.text
767    };
768    seat.turns += 1;
769
770    Ok(AgentOutput {
771        text,
772        exit_code: code,
773        timed_out,
774        duration_ms: started.elapsed().as_millis() as u64,
775        artifacts: vec![
776            file_name(&prompt_path),
777            file_name(&out_path),
778            file_name(&err_path),
779        ],
780        quota: extracted.quota,
781        dropped: extracted.dropped,
782        commands: extracted.commands,
783        context_tokens: extracted.context_tokens,
784    })
785}
786
787fn file_name(p: &Path) -> String {
788    p.file_name()
789        .unwrap_or_default()
790        .to_string_lossy()
791        .into_owned()
792}
793
794/// The argv plus optional stdin body for one invocation.
795#[derive(Debug)]
796struct Plan {
797    argv: Vec<String>,
798    stdin: Option<String>,
799}
800
801impl Plan {
802    /// Settings may have been loaded from a file containing credentials.
803    /// Log the option, never its value, including repeated and equals forms.
804    fn logged_argv(&self) -> Vec<&str> {
805        let mut settings_value = false;
806        self.argv
807            .iter()
808            .map(|arg| {
809                if settings_value {
810                    settings_value = false;
811                    "[redacted]"
812                } else if arg == "--settings" {
813                    settings_value = true;
814                    arg.as_str()
815                } else if arg.starts_with("--settings=") {
816                    "--settings=[redacted]"
817                } else {
818                    arg.as_str()
819                }
820            })
821            .collect()
822    }
823}
824
825/// How a file-delivered prompt is pointed at, per CLI.
826///
827/// `agy` has a native file-context syntax, `@<path>`, and it is measurably the
828/// better contract: on the same trivial task it finished in 17s against 73s for
829/// the prose form, because prose makes the model spend a tool round-trip
830/// deciding to read the file. It is also the form yukimemi/rvpm proved out.
831///
832/// opencode has no equivalent, so it gets the prose. That is not a fallback
833/// worth apologising for — it works, and it is what the winning opencode
834/// candidates on this repository have been driven by all along.
835fn pointer(kind: AgentKind, prompt_path: &Path) -> String {
836    if matches!(kind, AgentKind::Antigravity) {
837        return format!("@{}", prompt_path.display());
838    }
839    format!(
840        "Read the file at {} and follow every instruction in it exactly. That \
841         file is your complete task description; this message contains nothing \
842         else.",
843        prompt_path.display()
844    )
845}
846
847fn build_command(
848    spec: &AgentSpec,
849    seat: &SeatState,
850    inv: &Invocation<'_>,
851    prompt_path: &Path,
852) -> Result<Plan> {
853    let mut argv: Vec<String> = Vec::new();
854    let mut stdin: Option<String> = None;
855    let delivery = spec.delivery();
856    let resuming = has_session(spec.kind, seat, inv.sessions);
857
858    match spec.kind {
859        AgentKind::Claude => {
860            // Claude's own tools have no cwd-confined sandbox - the CLI can
861            // already `Read` any absolute path magi hands it, an attachment
862            // outside the repository included - so no extra flag is needed
863            // here.
864            argv.push("claude".to_owned());
865            argv.push("-p".to_owned());
866            argv.push("--output-format".to_owned());
867            argv.push("json".to_owned());
868            if let Some(m) = &spec.model {
869                argv.push("--model".to_owned());
870                argv.push(m.clone());
871            }
872            if inv.sessions {
873                let uuid = seat
874                    .claude_session
875                    .as_deref()
876                    .context("claude seat is missing its session uuid")?;
877                argv.push(if resuming { "--resume" } else { "--session-id" }.to_owned());
878                argv.push(uuid.to_owned());
879            }
880            argv.push("--permission-mode".to_owned());
881            argv.push("bypassPermissions".to_owned());
882            if !inv.allow_write {
883                argv.push("--disallowed-tools".to_owned());
884                argv.push("Edit,Write,MultiEdit,NotebookEdit".to_owned());
885            }
886        }
887        AgentKind::Opencode => {
888            // `--auto` below already bypasses every permission, reads of a
889            // path outside `--dir` included, so an attachment elsewhere
890            // needs no extra flag.
891            argv.push("opencode".to_owned());
892            argv.push("run".to_owned());
893            argv.push("--format".to_owned());
894            argv.push("json".to_owned());
895            argv.push("--dir".to_owned());
896            argv.push(inv.cwd.to_string_lossy().into_owned());
897            // `--auto` gates *every* permission, reads included: without it a
898            // non-interactive opencode cannot even open the prompt file, and
899            // the seat drops out of the panel with "the user rejected
900            // permission to use this specific tool call". opencode has no
901            // read-only mode, so read-only seats rely on the prompt plus the
902            // fact that judge and reviewer worktrees are disposable — judges'
903            // are deleted after the tally, reviewers' are reset to the commit
904            // under review every round.
905            argv.push("--auto".to_owned());
906            if let Some(m) = &spec.model {
907                argv.push("-m".to_owned());
908                argv.push(m.clone());
909            }
910            if resuming {
911                argv.push("-s".to_owned());
912                argv.push(
913                    seat.captured_session
914                        .clone()
915                        .expect("has_session checked the id is present"),
916                );
917            }
918        }
919        AgentKind::Antigravity => {
920            argv.push("agy".to_owned());
921            argv.push("--output-format".to_owned());
922            argv.push("json".to_owned());
923            // agy's print mode gives up after 5 minutes by default, which is
924            // far below an implementation node's budget.
925            argv.push("--print-timeout".to_owned());
926            argv.push(format!("{}s", inv.timeout.as_secs()));
927            argv.push("--mode".to_owned());
928            argv.push(
929                if inv.allow_write {
930                    "accept-edits"
931                } else {
932                    "plan"
933                }
934                .to_owned(),
935            );
936            if inv.allow_write {
937                argv.push("--dangerously-skip-permissions".to_owned());
938            }
939            if let Some(m) = &spec.model {
940                argv.push("--model".to_owned());
941                argv.push(m.clone());
942            }
943            if resuming {
944                argv.push("--conversation".to_owned());
945                argv.push(
946                    seat.captured_session
947                        .clone()
948                        .expect("has_session checked the id is present"),
949                );
950            }
951            // The prompt file lives outside the worktree, so the workspace has
952            // to be widened to reach it - and so does an attachment's own
953            // directory, which usually lives right beside it under the
954            // conversation's `artifacts_dir` (see `chat`/`talk`). "Usually":
955            // a chat derived from another one (`chat::derived_background`)
956            // can carry attachment paths that live under the *source*
957            // conversation's own artifacts dir instead, so each attachment
958            // outside `inv.artifacts` gets its own `--add-dir` rather than
959            // assuming one directory covers all of `inv.attachments`.
960            let mut add_dirs: Vec<String> = Vec::new();
961            if delivery == Delivery::File || !inv.attachments.is_empty() {
962                add_dirs.push(inv.artifacts.to_string_lossy().into_owned());
963            }
964            for path in inv.attachments {
965                let Some(parent) = path.parent() else {
966                    continue;
967                };
968                if parent.starts_with(inv.artifacts) {
969                    continue;
970                }
971                let dir = parent.to_string_lossy().into_owned();
972                if !add_dirs.contains(&dir) {
973                    add_dirs.push(dir);
974                }
975            }
976            if inv.allow_write {
977                for path in inv.writable {
978                    let dir = path.to_string_lossy().into_owned();
979                    if !add_dirs.contains(&dir) {
980                        add_dirs.push(dir);
981                    }
982                }
983            }
984            for dir in add_dirs {
985                argv.push("--add-dir".to_owned());
986                argv.push(dir);
987            }
988        }
989        AgentKind::Codex => {
990            // `--sandbox` below governs writes, not reads (see the module
991            // doc: it is what makes codex the one kind whose *read-only*
992            // mode is enforced, by refusing edits) - both presets can read
993            // anywhere the OS lets the process, so an attachment outside
994            // `cwd` is already reachable without an extra flag.
995            argv.push("codex".to_owned());
996            argv.push("exec".to_owned());
997            argv.push("--json".to_owned());
998            // The worktrees magi hands out are real checkouts, but a judge's
999            // is detached and a fixture's may be no repository at all.
1000            argv.push("--skip-git-repo-check".to_owned());
1001            argv.push("-C".to_owned());
1002            argv.push(inv.cwd.to_string_lossy().into_owned());
1003            // Codex is the only kind whose read-only-ness is enforced by the
1004            // CLI rather than by the prompt: a judge or reviewer seat cannot
1005            // write even if it decides to try. Repository editing seats
1006            // (implementer, fixer, grafter, gate fixer, land, rebase and an
1007            // opted-in chat turn - see `repository_writer`) drop sandbox and
1008            // approvals altogether, as claude's `bypassPermissions` does: the
1009            // seatbelt sandbox refuses `$TMPDIR` and aborts Chrome, so the
1010            // repository's own tests could not run (owner decision
1011            // 2026-10-27). Every other seat keeps its sandbox.
1012            if repository_writer(inv) {
1013                argv.push("--dangerously-bypass-approvals-and-sandbox".to_owned());
1014            } else {
1015                argv.push("--sandbox".to_owned());
1016                argv.push(
1017                    if inv.allow_write {
1018                        "workspace-write"
1019                    } else {
1020                        "read-only"
1021                    }
1022                    .to_owned(),
1023                );
1024                // Nothing is watching to approve anything: an unattended seat
1025                // that asks blocks until its timeout kills it.
1026                argv.push("-c".to_owned());
1027                argv.push("approval_policy=\"never\"".to_owned());
1028                if inv.allow_write && !inv.writable.is_empty() {
1029                    let roots: Vec<String> = inv
1030                        .writable
1031                        .iter()
1032                        .map(|p| p.to_string_lossy().into_owned())
1033                        .collect();
1034                    argv.push("-c".to_owned());
1035                    argv.push(format!(
1036                        "sandbox_workspace_write.writable_roots={}",
1037                        serde_json::to_string(&roots).unwrap_or_else(|_| "[]".to_owned())
1038                    ));
1039                }
1040            }
1041            if let Some(m) = &spec.model {
1042                argv.push("-m".to_owned());
1043                argv.push(m.clone());
1044            }
1045            // `resume` is a subcommand of `exec`, and it rejects the flags
1046            // above when they follow it - so every option is emitted first and
1047            // the subcommand last. Established by hand against codex-cli
1048            // 0.153.4: with the order reversed the CLI exits on
1049            // `unexpected argument '--sandbox'`.
1050            if resuming {
1051                argv.push("resume".to_owned());
1052                argv.push(
1053                    seat.captured_session
1054                        .clone()
1055                        .expect("has_session checked the id is present"),
1056                );
1057            }
1058        }
1059        AgentKind::Omp => {
1060            // `omp` reads the prompt from stdin in print mode (see
1061            // `AgentSpec::delivery`), so the whole instruction arrives without
1062            // an argv length limit - the same reason codex gets stdin.
1063            argv.push("omp".to_owned());
1064            argv.push("-p".to_owned());
1065            argv.push("--mode=json".to_owned());
1066            // `--auto-approve` is required, and is the same trade opencode's
1067            // `--auto` makes: it gates *every* permission, reads included, so
1068            // without it a non-interactive seat cannot even open the prompt
1069            // file magi wrote and drops out of the panel on a permission
1070            // rejection. `omp` has no read-only mode of its own, so a judge or
1071            // reviewer seat rests on the prompt plus the worktree discipline
1072            // (judge worktrees are deleted after the tally, reviewer worktrees
1073            // are reset to the commit under review every round) - never on this
1074            // flag, and never on a bypass flag.
1075            argv.push("--auto-approve".to_owned());
1076            if let Some(m) = &spec.model {
1077                argv.push("--model".to_owned());
1078                argv.push(m.clone());
1079            }
1080            // Established by hand against omp 18.1.19: `-p --mode=json` reports
1081            // the session id on its `"type":"session"` line, and
1082            // `--resume <id>` continues that conversation. `--continue` is
1083            // deliberately not used - it opens a *new* session rather than the
1084            // stored one, which silently loses the seat's memory.
1085            if resuming {
1086                argv.push("--resume".to_owned());
1087                argv.push(
1088                    seat.captured_session
1089                        .clone()
1090                        .expect("has_session checked the id is present"),
1091                );
1092            }
1093        }
1094        AgentKind::Command => {
1095            // The operator's own command line, not one of the roster CLIs -
1096            // there is no flag this function could add on its behalf, so an
1097            // attachment's path has to reach it the same way the prompt
1098            // does, through the substitutions below.
1099            if spec.command.is_empty() {
1100                bail!("agent `{}` has kind = \"command\" but no command", spec.id);
1101            }
1102            let vars: BTreeMap<&str, String> = BTreeMap::from([
1103                ("{prompt_file}", prompt_path.to_string_lossy().into_owned()),
1104                ("{cwd}", inv.cwd.to_string_lossy().into_owned()),
1105                ("{label}", seat.key.clone()),
1106                ("{session}", seat.claude_session.clone().unwrap_or_default()),
1107            ]);
1108            for raw in &spec.command {
1109                let mut arg = raw.clone();
1110                for (k, v) in &vars {
1111                    if arg.contains(k) {
1112                        arg = arg.replace(k, v);
1113                    }
1114                }
1115                argv.push(arg);
1116            }
1117        }
1118    }
1119
1120    argv.extend(spec.extra_args.iter().cloned());
1121
1122    // `agy` takes the prompt as the value of `-p`, so the flag has to be
1123    // emitted right before whatever the delivery mode produces.
1124    if spec.kind == AgentKind::Antigravity {
1125        argv.push("-p".to_owned());
1126    }
1127    // `codex exec` reads stdin only when its prompt argument is `-`; without
1128    // it the CLI waits on a prompt it will never be given.
1129    if spec.kind == AgentKind::Codex && delivery == Delivery::Stdin {
1130        argv.push("-".to_owned());
1131    }
1132    match delivery {
1133        Delivery::Stdin if spec.kind == AgentKind::Antigravity => {
1134            // agy has no text stdin path; fall back to the pointer file.
1135            argv.push(pointer(spec.kind, prompt_path));
1136        }
1137        Delivery::Stdin => stdin = Some(inv.prompt.to_owned()),
1138        Delivery::Argv => argv.push(inv.prompt.to_owned()),
1139        Delivery::File => argv.push(pointer(spec.kind, prompt_path)),
1140    }
1141
1142    Ok(Plan { argv, stdin })
1143}
1144
1145/// What a CLI's stdout yielded.
1146#[derive(Debug, Default)]
1147struct Extracted {
1148    text: String,
1149    session: Option<String>,
1150    status: Option<String>,
1151    quota: Option<Quota>,
1152    dropped: Option<Dropped>,
1153    commands: Vec<CommandEvidence>,
1154    context_tokens: Option<u64>,
1155}
1156
1157/// Pull the agent's message (and any session id) out of a CLI's stdout.
1158fn extract(kind: AgentKind, stdout: &str) -> Extracted {
1159    let mut extracted = extract_answer(kind, stdout);
1160    extracted.context_tokens = context_tokens(kind, stdout);
1161    extracted
1162}
1163
1164/// `v[key]` as an unsigned integer, or `None` when absent or not a number.
1165fn uint(v: &serde_json::Value, key: &str) -> Option<u64> {
1166    v.get(key).and_then(serde_json::Value::as_u64)
1167}
1168
1169/// The input side of a usage object: `input` plus whatever the cache served
1170/// or stored, each key read under the names the CLIs use. A missing cache
1171/// counter is 0 (the CLI simply had no cache traffic to report) but a missing
1172/// *input* counter makes the whole thing unknown - `None`, never a made-up 0.
1173fn input_side(usage: &serde_json::Value, input: &[&str], cache: &[&str]) -> Option<u64> {
1174    let first = |keys: &[&str]| keys.iter().find_map(|k| uint(usage, k));
1175    let base = first(input)?;
1176    let cached: u64 = cache.iter().filter_map(|k| uint(usage, k)).sum();
1177    Some(base.saturating_add(cached))
1178}
1179
1180/// The context size a CLI reported for its last turn: its input-side token
1181/// count, which approximates how much of the model's window the conversation
1182/// occupies. A pure function of stdout, so each CLI's shape is unit-testable.
1183///
1184/// Rules, all deliberate:
1185/// - **Last report wins, never a sum.** A multi-event stream (opencode's
1186///   `step_finish`, codex's `turn.completed`, omp's `message_end`) reports the
1187///   input of each model call; the final one is the largest context the
1188///   conversation reached this turn, and adding them would count the same
1189///   prefix once per tool round-trip.
1190/// - **Missing or mistyped usage is `None`**, which the UI shows as "unknown".
1191/// - **A cumulative total is not a context size, so it is `None`.** claude's
1192///   result `usage` sums every model call of the turn and, on a resumed
1193///   session, carries the session's earlier usage too, so even `num_turns == 1`
1194///   does not make it one call's context. codex's `turn.completed.usage` is the
1195///   session's running input total, and agy's `usage` aggregates the whole
1196///   print-mode call (the observed sample exceeds any window). None of the
1197///   three carries a per-call figure, so each is unknown rather than made up.
1198///   Only the streams that report each model call (opencode `step_finish`, omp
1199///   message usage) yield a number.
1200fn context_tokens(kind: AgentKind, stdout: &str) -> Option<u64> {
1201    use serde_json::Value;
1202    let lines = || {
1203        stdout
1204            .lines()
1205            .filter_map(|l| serde_json::from_str::<Value>(l.trim()).ok())
1206    };
1207    match kind {
1208        AgentKind::Claude => None,
1209        AgentKind::Opencode => lines()
1210            .filter(|v| {
1211                // The event is `step_finish`; its part is `step-finish`.
1212                v.get("type").and_then(|t| t.as_str()) == Some("step_finish")
1213                    || v.get("part")
1214                        .and_then(|p| p.get("type"))
1215                        .and_then(|t| t.as_str())
1216                        == Some("step-finish")
1217            })
1218            .filter_map(|v| {
1219                let tokens = v.get("part")?.get("tokens")?;
1220                let base = uint(tokens, "input")?;
1221                let cache = tokens.get("cache");
1222                let cached = ["read", "write"]
1223                    .iter()
1224                    .filter_map(|k| cache.and_then(|c| uint(c, k)))
1225                    .sum::<u64>();
1226                Some(base.saturating_add(cached))
1227            })
1228            .next_back(),
1229        AgentKind::Antigravity => None,
1230        AgentKind::Codex => None,
1231        AgentKind::Omp => lines()
1232            .flat_map(|v| {
1233                // Same walk as the answer: `agent_end` carries the thread,
1234                // `turn_end` / `message_end` one message each.
1235                match v.get("type").and_then(|t| t.as_str()) {
1236                    Some("agent_end") => v
1237                        .get("messages")
1238                        .and_then(|m| m.as_array())
1239                        .cloned()
1240                        .unwrap_or_default(),
1241                    Some("turn_end") | Some("message_end") => {
1242                        v.get("message").cloned().into_iter().collect()
1243                    }
1244                    _ => Vec::new(),
1245                }
1246            })
1247            .filter(|m| m.get("role").and_then(|r| r.as_str()) == Some("assistant"))
1248            .filter_map(|m| {
1249                input_side(
1250                    m.get("usage")?,
1251                    &["input", "input_tokens"],
1252                    &[
1253                        "cacheRead",
1254                        "cacheWrite",
1255                        "cache_read_tokens",
1256                        "cache_write_tokens",
1257                    ],
1258                )
1259            })
1260            .next_back(),
1261        AgentKind::Command => None,
1262    }
1263}
1264
1265/// The answer text of a stored `<stem>.out`, through the same per-CLI
1266/// extraction a live call uses. Never the raw event stream.
1267pub(crate) fn answer_text(kind: AgentKind, stdout: &str) -> String {
1268    extract_answer(kind, stdout).text
1269}
1270
1271fn extract_answer(kind: AgentKind, stdout: &str) -> Extracted {
1272    match kind {
1273        AgentKind::Claude => {
1274            let Ok(v) = serde_json::from_str::<serde_json::Value>(stdout.trim()) else {
1275                return Extracted {
1276                    text: stdout.trim().to_owned(),
1277                    ..Extracted::default()
1278                };
1279            };
1280            Extracted {
1281                text: v
1282                    .get("result")
1283                    .and_then(|r| r.as_str())
1284                    .unwrap_or_default()
1285                    .to_owned(),
1286                session: v
1287                    .get("session_id")
1288                    .and_then(|s| s.as_str())
1289                    .map(str::to_owned),
1290                status: v.get("is_error").and_then(|e| e.as_bool()).map(|e| {
1291                    if e {
1292                        "error".to_owned()
1293                    } else {
1294                        "success".to_owned()
1295                    }
1296                }),
1297                quota: claude_quota(&v),
1298                // Claude reports a truncated stream as an ordinary error; the
1299                // shape `dropped_stream` keys on is agy's.
1300                dropped: None,
1301                commands: Vec::new(),
1302                context_tokens: None,
1303            }
1304        }
1305        AgentKind::Opencode => {
1306            // A JSONL event stream: text parts concatenated in arrival order.
1307            let mut text = String::new();
1308            let mut session = None;
1309            for line in stdout.lines() {
1310                let Ok(v) = serde_json::from_str::<serde_json::Value>(line.trim()) else {
1311                    continue;
1312                };
1313                if session.is_none() {
1314                    session = v
1315                        .get("sessionID")
1316                        .and_then(|s| s.as_str())
1317                        .map(str::to_owned);
1318                }
1319                let part = v.get("part").unwrap_or(&serde_json::Value::Null);
1320                if part.get("type").and_then(|t| t.as_str()) == Some("text")
1321                    && let Some(t) = part.get("text").and_then(|t| t.as_str())
1322                {
1323                    if !text.is_empty() {
1324                        text.push('\n');
1325                    }
1326                    text.push_str(t);
1327                }
1328            }
1329            Extracted {
1330                text,
1331                session,
1332                status: None,
1333                quota: None,
1334                dropped: None,
1335                commands: Vec::new(),
1336                context_tokens: None,
1337            }
1338        }
1339        AgentKind::Antigravity => {
1340            // agy prints warnings before the JSON object, so parse the last
1341            // line that is one rather than the whole stream.
1342            let obj = stdout
1343                .lines()
1344                .rev()
1345                .find_map(|l| serde_json::from_str::<serde_json::Value>(l.trim()).ok());
1346            let Some(v) = obj else {
1347                return Extracted {
1348                    text: stdout.trim().to_owned(),
1349                    ..Extracted::default()
1350                };
1351            };
1352            Extracted {
1353                text: v
1354                    .get("response")
1355                    .and_then(|r| r.as_str())
1356                    .unwrap_or_default()
1357                    .trim()
1358                    .to_owned(),
1359                session: v
1360                    .get("conversation_id")
1361                    .and_then(|s| s.as_str())
1362                    .map(str::to_owned),
1363                status: v.get("status").and_then(|s| s.as_str()).map(str::to_owned),
1364                quota: None,
1365                dropped: dropped_stream(&v),
1366                commands: Vec::new(),
1367                context_tokens: None,
1368            }
1369        }
1370        AgentKind::Codex => {
1371            // A JSONL event stream, prefixed on a real machine by tracing
1372            // lines the CLI writes about its own config and skills - so
1373            // non-JSON lines are skipped rather than treated as the answer.
1374            //
1375            // The thread id arrives once, in `thread.started`, and a resumed
1376            // turn reports the same one. The answer is the last
1377            // `item.completed` carrying an `agent_message`: earlier ones are
1378            // the model narrating its way through the tool loop, and taking
1379            // the first would hand the caller a progress note instead of a
1380            // verdict.
1381            //
1382            // A `command_execution` item is different evidence entirely: the
1383            // CLI's own record that it ran a command and what that command
1384            // reported back, kept as `CommandEvidence` — see run
1385            // 20260912-214939-b3bb's artifacts, where these very fields
1386            // (`id`/`command`/`exit_code`/`aggregated_output`) were what
1387            // caught a paired test result magi's own agent prose had missed.
1388            // Only what `item.completed` actually reports: a command still
1389            // running when the turn ended emits no such event at all, and is
1390            // not something this can detect — see [`CommandEvidence`]'s own
1391            // doc for why that must not be guessed at instead.
1392            let mut text = String::new();
1393            let mut session = None;
1394            let mut status = None;
1395            let mut commands = Vec::new();
1396            for line in stdout.lines() {
1397                let Ok(v) = serde_json::from_str::<serde_json::Value>(line.trim()) else {
1398                    continue;
1399                };
1400                match v.get("type").and_then(|t| t.as_str()) {
1401                    Some("thread.started") => {
1402                        session = v
1403                            .get("thread_id")
1404                            .and_then(|s| s.as_str())
1405                            .map(str::to_owned);
1406                    }
1407                    Some("item.completed") => {
1408                        let item = v.get("item").unwrap_or(&serde_json::Value::Null);
1409                        match item.get("type").and_then(|t| t.as_str()) {
1410                            Some("agent_message") => {
1411                                if let Some(t) = item.get("text").and_then(|t| t.as_str()) {
1412                                    text = t.trim().to_owned();
1413                                }
1414                            }
1415                            Some("command_execution") => {
1416                                commands.push(command_evidence(item));
1417                            }
1418                            _ => {}
1419                        }
1420                    }
1421                    Some("turn.completed") => status = Some("success".to_owned()),
1422                    Some("turn.failed") => status = Some("error".to_owned()),
1423                    _ => {}
1424                }
1425            }
1426            Extracted {
1427                text,
1428                session,
1429                status,
1430                quota: codex_quota(stdout),
1431                dropped: None,
1432                commands,
1433                context_tokens: None,
1434            }
1435        }
1436        AgentKind::Omp => {
1437            // A JSONL event stream. The session id arrives once, on the
1438            // `"type":"session"` line that opens the run.
1439            //
1440            // The answer is the *last* non-empty assistant text block anywhere
1441            // in the stream, and neither of the two obvious shortcuts works:
1442            //
1443            // 1. Do not key on `agent_end`. `omp` emits it only for a run that
1444            //    quiesces on a message turn; a turn that ends on a tool call
1445            //    (`stopReason: "toolUse"`) ends the run with **no `agent_end`
1446            //    line at all**, and the answer is in `message_end` / `turn_end`
1447            //    instead. Reading only `agent_end` silently discards a complete
1448            //    review - which is exactly what the first hand-written wrapper
1449            //    did, three times, before this arm existed.
1450            // 2. Do not take the first assistant text. Earlier ones narrate the
1451            //    tool loop (sometimes with a single `.`), so the last non-empty
1452            //    block is the answer and the one before it is a progress note.
1453            //
1454            // Every line is parsed independently: a non-JSON line (a CLI
1455            // warning, a truncated write) is skipped rather than treated as the
1456            // answer, the same way the codex arm treats its tracing prefix.
1457            let mut text = String::new();
1458            let mut session = None;
1459            for line in stdout.lines() {
1460                let Ok(v) = serde_json::from_str::<serde_json::Value>(line.trim()) else {
1461                    continue;
1462                };
1463                if v.get("type").and_then(|t| t.as_str()) == Some("session") {
1464                    session = v.get("id").and_then(|s| s.as_str()).map(str::to_owned);
1465                    continue;
1466                }
1467                // `agent_end` carries the whole thread; `turn_end` and
1468                // `message_end` each carry one message. Whichever appears, the
1469                // messages are walked the same way.
1470                let messages: Vec<&serde_json::Value> = match v.get("type").and_then(|t| t.as_str())
1471                {
1472                    Some("agent_end") => v
1473                        .get("messages")
1474                        .and_then(|m| m.as_array())
1475                        .map(|m| m.iter().collect())
1476                        .unwrap_or_default(),
1477                    Some("turn_end") | Some("message_end") => {
1478                        v.get("message").into_iter().collect()
1479                    }
1480                    _ => continue,
1481                };
1482                for message in messages {
1483                    if message.get("role").and_then(|r| r.as_str()) != Some("assistant") {
1484                        continue;
1485                    }
1486                    let Some(parts) = message.get("content").and_then(|c| c.as_array()) else {
1487                        continue;
1488                    };
1489                    for part in parts {
1490                        if part.get("type").and_then(|t| t.as_str()) != Some("text") {
1491                            continue;
1492                        }
1493                        if let Some(t) = part.get("text").and_then(|t| t.as_str())
1494                            && !t.trim().is_empty()
1495                        {
1496                            text = t.trim().to_owned();
1497                        }
1498                    }
1499                }
1500            }
1501            Extracted {
1502                text,
1503                session,
1504                status: None,
1505                quota: None,
1506                dropped: None,
1507                commands: Vec::new(),
1508                context_tokens: None,
1509            }
1510        }
1511        AgentKind::Command => {
1512            // A `command` agent may wrap a subscription CLI (a fixture, or a
1513            // thin shim around `claude`). If its output is the claude error
1514            // shape we recognise the quota the same way, so tests and wrappers
1515            // do not need their own detection; anything else is just text.
1516            let parsed = serde_json::from_str::<serde_json::Value>(stdout.trim()).ok();
1517            let quota = parsed.as_ref().and_then(claude_quota);
1518            // A `command` fixture may also stand in for a CLI that hangs up on
1519            // its own stream, which is how that path is tested.
1520            let dropped = parsed.as_ref().and_then(dropped_stream);
1521            Extracted {
1522                text: stdout.trim().to_owned(),
1523                session: None,
1524                status: None,
1525                quota,
1526                dropped,
1527                commands: Vec::new(),
1528                context_tokens: None,
1529            }
1530        }
1531    }
1532}
1533
1534/// Build one [`CommandEvidence`] from a Codex `command_execution` item.
1535///
1536/// `command` arrives either as a single string or as an argv array,
1537/// depending on how the CLI shaped the call; both are read rather than
1538/// assuming one. Missing fields are left at their honest defaults (an empty
1539/// id/description, `exit_code: None`) rather than guessed at.
1540fn command_evidence(item: &serde_json::Value) -> CommandEvidence {
1541    let description = match item.get("command") {
1542        Some(serde_json::Value::String(s)) => s.clone(),
1543        Some(serde_json::Value::Array(parts)) => parts
1544            .iter()
1545            .filter_map(|p| p.as_str())
1546            .collect::<Vec<_>>()
1547            .join(" "),
1548        _ => String::new(),
1549    };
1550    let result_summary = item
1551        .get("aggregated_output")
1552        .and_then(|o| o.as_str())
1553        .map(|s| tail_chars(s.trim(), 400))
1554        .unwrap_or_default();
1555    CommandEvidence {
1556        id: item
1557            .get("id")
1558            .and_then(|s| s.as_str())
1559            .unwrap_or_default()
1560            .to_owned(),
1561        description,
1562        exit_code: item
1563            .get("exit_code")
1564            .and_then(serde_json::Value::as_i64)
1565            .map(|e| e as i32),
1566        result_summary,
1567        source: "codex".to_owned(),
1568    }
1569}
1570
1571/// The last `max` characters of `s`, cut on a char boundary.
1572fn tail_chars(s: &str, max: usize) -> String {
1573    let count = s.chars().count();
1574    if count <= max {
1575        return s.to_owned();
1576    }
1577    s.chars().skip(count - max).collect()
1578}
1579
1580/// Require both the observed top-level limit event and a failed turn. Text
1581/// inside an assistant message is never evidence of an outage.
1582fn codex_quota(stdout: &str) -> Option<Quota> {
1583    let mut message = None;
1584    let mut failed = false;
1585    for line in stdout.lines() {
1586        let Ok(v) = serde_json::from_str::<serde_json::Value>(line) else {
1587            continue;
1588        };
1589        match v.get("type").and_then(serde_json::Value::as_str) {
1590            Some("error") => {
1591                if let Some(m) = v.get("message").and_then(serde_json::Value::as_str)
1592                    && m.starts_with("You've hit your usage limit. Visit https://chatgpt.com/settings/usage to purchase more credits")
1593                {
1594                    message = Some(m.to_owned());
1595                }
1596            }
1597            Some("turn.failed") => failed = true,
1598            _ => {}
1599        }
1600    }
1601    if !failed {
1602        return None;
1603    }
1604    let message = message?;
1605    Some(Quota {
1606        reset: message
1607            .split_once("try again at ")
1608            .map(|(_, hint)| hint.trim().trim_end_matches('.').trim().to_owned())
1609            .filter(|hint| !hint.is_empty()),
1610        cause: QuotaCause::UsageLimit,
1611        agent: String::new(),
1612    })
1613}
1614
1615/// Recognise claude's usage-limit and expired OAuth error shapes, when it is present.
1616///
1617/// Recognises `is_error: true` with a session-limit result or the structured
1618/// pair `api_error_status: 429` (number or string), `api_error: usage_limit_reached`;
1619/// also accepts the observed api_error result for an expired OAuth session.
1620/// Unknown error shapes remain ordinary failures.
1621fn claude_quota(v: &serde_json::Value) -> Option<Quota> {
1622    let is_err = v.get("is_error").and_then(|e| e.as_bool()).unwrap_or(false);
1623    if !is_err {
1624        return None;
1625    }
1626    let result = v.get("result").and_then(|r| r.as_str()).unwrap_or("");
1627    if v.get("terminal_reason").and_then(serde_json::Value::as_str) == Some("api_error")
1628        && result.starts_with("Failed to authenticate:")
1629        && result.contains("OAuth session expired and could not be refreshed")
1630    {
1631        return Some(Quota {
1632            reset: None,
1633            cause: QuotaCause::Authentication,
1634            agent: String::new(),
1635        });
1636    }
1637    let status = v.get("api_error_status");
1638    let usage_limit = (status.and_then(serde_json::Value::as_u64) == Some(429)
1639        || status.and_then(serde_json::Value::as_str) == Some("429"))
1640        && v.get("api_error").and_then(serde_json::Value::as_str) == Some("usage_limit_reached");
1641    if !usage_limit && !result.to_lowercase().contains("session limit") {
1642        return None;
1643    }
1644    // "…session limit · resets 4:50am (Asia/Tokyo)". The timezone read is not
1645    // worth parsing exactly; keep the whole phrase after "resets" as free text.
1646    let reset = result
1647        .split("resets ")
1648        .nth(1)
1649        .map(str::trim)
1650        .filter(|s| !s.is_empty())
1651        .map(str::to_owned);
1652    Some(Quota {
1653        reset,
1654        cause: QuotaCause::UsageLimit,
1655        agent: String::new(),
1656    })
1657}
1658
1659/// Recognise `agy` running out of quota, from either stream.
1660///
1661/// Observed shape while out of quota: stdout carries the JSON object
1662/// `{"status":"ERROR","response":"","error":"Individual quota reached. … Resets
1663/// in 1h2m49s."}` and stderr carries `AGY_ERROR: {"status":"RESOURCE_EXHAUSTED",
1664/// "error_code":429,…}`. Either alone is enough (a mangled stdout must not hide
1665/// a quota that stderr states plainly), but each is keyed on a *pair* of
1666/// structured fields: `status: ERROR` with the quota text, or
1667/// `RESOURCE_EXHAUSTED` together with 429. An error status alone, or a 429
1668/// alone, stays an ordinary failure - the conservative side, as for
1669/// [`claude_quota`].
1670///
1671/// The reset hint is what follows `Resets ` (e.g. `in 1h2m49s`), trailing full
1672/// stop dropped.
1673fn agy_quota(stdout: &str, stderr: &str) -> Option<Quota> {
1674    let from_stdout = stdout
1675        .lines()
1676        .rev()
1677        .find_map(|l| serde_json::from_str::<serde_json::Value>(l.trim()).ok())
1678        .and_then(|v| {
1679            let status = v.get("status").and_then(|s| s.as_str()).unwrap_or("");
1680            let error = v.get("error").and_then(|e| e.as_str()).unwrap_or("");
1681            (status.eq_ignore_ascii_case("error") && error.to_lowercase().contains("quota reached"))
1682                .then(|| error.to_owned())
1683        });
1684    let from_stderr = || {
1685        stderr.lines().find_map(|l| {
1686            let v: serde_json::Value =
1687                serde_json::from_str(l.trim().strip_prefix("AGY_ERROR:")?.trim()).ok()?;
1688            let exhausted = v.get("status").and_then(|s| s.as_str()) == Some("RESOURCE_EXHAUSTED");
1689            let code = v.get("error_code").and_then(serde_json::Value::as_u64) == Some(429);
1690            (exhausted && code).then(|| {
1691                v.get("short_error")
1692                    .and_then(|e| e.as_str())
1693                    .unwrap_or_default()
1694                    .to_owned()
1695            })
1696        })
1697    };
1698    let text = from_stdout.or_else(from_stderr)?;
1699    let reset = text
1700        .split_once("Resets ")
1701        .map(|(_, rest)| rest.trim().trim_end_matches('.').trim())
1702        .filter(|s| !s.is_empty())
1703        .map(str::to_owned);
1704    Some(Quota {
1705        reset,
1706        cause: QuotaCause::UsageLimit,
1707        agent: String::new(),
1708    })
1709}
1710
1711/// Recognise a CLI that gave up on its own stream while the agent was working.
1712///
1713/// Observed once, verbatim, from `agy` on a candidate that produced nothing:
1714///
1715/// ```text
1716/// {"conversation_id":"36743d06-…","status":"ERROR","response":"",
1717///  "error":"the connection to the agent was interrupted before the response
1718///           finished: subscriber fell behind updates, stalled for 5s",
1719///  "duration_seconds":431.19,"num_turns":1,
1720///  "usage":{"input_tokens":260113,"output_tokens":14267,
1721///           "thinking_tokens":9695,"cache_read_tokens":2200925}}
1722/// ```
1723///
1724/// Seven minutes of work and fourteen thousand output tokens, billed, with an
1725/// empty `response`: the agent did the job and the CLI's own subscriber fell
1726/// behind and hung up. That is **not** an agent that failed to implement, and
1727/// counting it as one is how `agy` came to read as 0 wins in 4 entries with
1728/// five empty candidates - a number that has twice been used to argue the seat
1729/// out of the roster, and twice been wrong (see `cb6b830`, which reverted the
1730/// first removal: *"agy does not fail to implement, it fails to report"*).
1731///
1732/// The distinction that matters is **billed work with nothing delivered**, so
1733/// that is what this keys on: an error status, an empty response, and a usage
1734/// report showing output tokens. Everything else - including an error with no
1735/// usage at all - returns `None` and stays an ordinary failure, the
1736/// conservative side, exactly as [`claude_quota`] treats shapes it does not
1737/// recognise.
1738///
1739/// Unlike a quota, this **is** worth re-asking: the work exists in the
1740/// conversation the CLI just abandoned, and `conversation_id` is right there.
1741fn dropped_stream(v: &serde_json::Value) -> Option<Dropped> {
1742    let status = v.get("status").and_then(|s| s.as_str()).unwrap_or("");
1743    if !status.eq_ignore_ascii_case("error") {
1744        return None;
1745    }
1746    let response = v.get("response").and_then(|r| r.as_str()).unwrap_or("");
1747    if !response.trim().is_empty() {
1748        // It answered. Whatever the status says, there is something to read.
1749        return None;
1750    }
1751    let produced = v
1752        .get("usage")
1753        .and_then(|u| u.get("output_tokens"))
1754        .and_then(serde_json::Value::as_u64)
1755        .unwrap_or(0);
1756    if produced == 0 {
1757        // An error with nothing produced is just an error.
1758        return None;
1759    }
1760    Some(Dropped {
1761        why: v
1762            .get("error")
1763            .and_then(|e| e.as_str())
1764            .unwrap_or("the CLI ended the stream without delivering its answer")
1765            .trim()
1766            .to_owned(),
1767        output_tokens: produced,
1768    })
1769}
1770
1771/// Preflight: which configured agents are not runnable here?
1772pub fn missing_programs(specs: &[AgentSpec]) -> Vec<String> {
1773    let mut missing = Vec::new();
1774    for s in specs {
1775        let program = match s.kind {
1776            AgentKind::Command => s.command.first().map(String::as_str),
1777            other => other.program(),
1778        };
1779        if let Some(p) = program
1780            && !crate::config::which(p)
1781            && !Path::new(p).is_file()
1782            && !missing.iter().any(|m: &String| m == p)
1783        {
1784            missing.push(p.to_owned());
1785        }
1786    }
1787    missing
1788}
1789
1790/// Absolute path of a run's artifact directory.
1791pub fn artifacts_dir(run_dir: &Path) -> PathBuf {
1792    run_dir.join("artifacts")
1793}
1794
1795/// Can this agent's CLI actually be run on this machine?
1796pub fn installed(spec: &AgentSpec) -> bool {
1797    // A `command` agent has no program of its own to look for - its argv is the
1798    // operator's, and they are the authority on whether it runs.
1799    spec.kind.program().is_none_or(crate::config::which)
1800}
1801
1802/// Choose the agent for a seat that stands alone rather than rotating through
1803/// the roster: [`crate::talk`]'s standing conversation,
1804/// or anything else that needs one agent picked once
1805/// rather than a panel filled in.
1806///
1807/// `available` is a parameter rather than a call to [`installed`] so the order
1808/// below is assertable on a machine with none of these CLIs installed, which is
1809/// every CI runner.
1810///
1811/// The order, and why:
1812///
1813/// 1. An explicit id always wins, and is an error rather than a fallback when
1814///    it is unusable. Naming a seat has a reason, and silently substituting a
1815///    different model would waste whatever that reason was.
1816/// 2. Otherwise a [`AgentKind::Claude`] seat, ahead of the roster order: it is
1817///    the only one of the three CLIs magi can address before the first turn
1818///    (see this module's own doc on session mechanics), which matters most for
1819///    a conversation that opens with nothing typed yet.
1820/// 3. Otherwise the first runnable agent in roster order, because the roster
1821///    order is the operator's own stated preference and magi has nothing
1822///    better to go on.
1823pub fn pick(
1824    agents: &[AgentSpec],
1825    want: Option<&str>,
1826    available: &dyn Fn(&AgentSpec) -> bool,
1827) -> Result<AgentSpec> {
1828    if let Some(id) = want {
1829        let spec = agents
1830            .iter()
1831            .find(|a| a.id == id)
1832            .with_context(|| format!("no agent `{id}` in the roster; it has {}", ids(agents)))?;
1833        if !available(spec) {
1834            bail!(
1835                "agent `{}` needs `{}` on PATH; install it or pass a different \
1836                 --agent",
1837                spec.id,
1838                spec.kind.program().unwrap_or("its command")
1839            );
1840        }
1841        return Ok(spec.clone());
1842    }
1843
1844    if agents.is_empty() {
1845        bail!(
1846            "the agent roster is empty, so there is nobody to ask: install one \
1847             of claude, opencode or agy - magi derives a roster from what is on \
1848             PATH - or add an [[agents]] entry to magi.toml."
1849        );
1850    }
1851
1852    if let Some(spec) = agents
1853        .iter()
1854        .find(|a| a.kind == AgentKind::Claude && available(a))
1855    {
1856        return Ok(spec.clone());
1857    }
1858
1859    agents
1860        .iter()
1861        .find(|a| available(a))
1862        .cloned()
1863        .with_context(|| {
1864            let missing = agents
1865                .iter()
1866                .filter_map(|a| a.kind.program())
1867                .collect::<Vec<_>>()
1868                .join(", ");
1869            format!(
1870                "no agent in the roster can be run here: install one of \
1871                 {missing}, or add an [[agents]] entry to magi.toml for a CLI \
1872                 you do have"
1873            )
1874        })
1875}
1876
1877/// `spec` for a seat whose answer is posted to GitHub (a pull request title or
1878/// description, a release reason), so the answer comes back in
1879/// `github_language` whatever language the operator set for their own CLI.
1880///
1881/// claude applies the user-level `language` setting (`"language": "Japanese"`
1882/// in `~/.claude/settings.json`) over a sentence in the prompt: the change
1883/// summary prompt said "Write ... in English" and the description came back in
1884/// Japanese, three times out of three when replayed, and in English every time
1885/// with this override. A per-invocation `--settings` outranks the user file, so
1886/// it is the CLI's own mechanism rather than more prompt wording. The other
1887/// CLIs have no operator-level answer-language preference magi knows of and
1888/// are returned unchanged.
1889pub fn for_github_text(spec: &AgentSpec, github_language: &str, cwd: &Path) -> Result<AgentSpec> {
1890    let mut spec = spec.clone();
1891    if spec.kind == AgentKind::Claude {
1892        // The CLI uses the last --settings value. Replace that value in
1893        // place, preserving its settings and the precedence of earlier flags.
1894        let mut existing = None;
1895        let mut args = spec.extra_args.iter().enumerate();
1896        while let Some((index, arg)) = args.next() {
1897            if arg == "--settings" {
1898                let (value_index, value) = args.next().context("--settings requires a value")?;
1899                existing = Some((value_index, value.as_str(), false));
1900            } else if let Some(value) = arg.strip_prefix("--settings=") {
1901                existing = Some((index, value, true));
1902            }
1903        }
1904        let mut settings = if let Some((_, value, _)) = existing {
1905            let json = if value.trim_start().starts_with('{') {
1906                value.to_owned()
1907            } else {
1908                std::fs::read_to_string(cwd.join(value))
1909                    .context("cannot read existing seat --settings file")?
1910            };
1911            serde_json::from_str::<serde_json::Value>(&json)
1912                .context("cannot parse existing seat --settings JSON")?
1913        } else {
1914            serde_json::json!({})
1915        };
1916        settings
1917            .as_object_mut()
1918            .context("seat --settings must be a JSON object")?
1919            .insert(
1920                "language".to_owned(),
1921                serde_json::json!(crate::lang::name(github_language)),
1922            );
1923        let settings = settings.to_string();
1924        if let Some((index, _, equals)) = existing {
1925            spec.extra_args[index] = if equals {
1926                format!("--settings={settings}")
1927            } else {
1928                settings
1929            };
1930        } else {
1931            spec.extra_args.extend(["--settings".to_owned(), settings]);
1932        }
1933    }
1934    Ok(spec)
1935}
1936
1937/// Resolve a standalone seat's agent choice into the ordered chain to try.
1938///
1939/// Unset (or empty) is [`pick`]'s default order, one entry. Otherwise each
1940/// named id is kept at its first appearance only - that is what bounds a
1941/// chain to one attempt per agent - and an id that is not in the roster or
1942/// not installed is skipped with a warning rather than failing the chain.
1943/// Errors, naming `role`, only when nothing resolves.
1944pub fn pick_chain(
1945    agents: &[AgentSpec],
1946    choice: Option<&AgentChoice>,
1947    available: &dyn Fn(&AgentSpec) -> bool,
1948    role: &str,
1949) -> Result<Vec<AgentSpec>> {
1950    let wanted = choice.map(AgentChoice::ids).unwrap_or_default();
1951    if wanted.is_empty() {
1952        return pick(agents, None, available)
1953            .map(|s| vec![s])
1954            .with_context(|| format!("choose an agent for the {role} role"));
1955    }
1956    let mut chain: Vec<AgentSpec> = Vec::new();
1957    for id in wanted {
1958        if chain.iter().any(|s| s.id == id) {
1959            continue;
1960        }
1961        match pick(agents, Some(id), available) {
1962            Ok(spec) => chain.push(spec),
1963            Err(e) => tracing::warn!("[roles] {role}: skipping `{id}`: {e:#}"),
1964        }
1965    }
1966    if chain.is_empty() {
1967        bail!(
1968            "[roles] {role} names no agent that can run here; the roster has {}",
1969            ids(agents)
1970        );
1971    }
1972    Ok(chain)
1973}
1974
1975/// Should a chain move on to its next agent after this call?
1976///
1977/// The one place that decides it: an error, a quota hit (judged apart from
1978/// `usable`, since a CLI can exit 0 with a quota message), or an unusable
1979/// answer such as a timeout or empty reply.
1980pub fn chain_advances(outcome: &Result<AgentOutput>) -> bool {
1981    match outcome {
1982        Err(e) if e.is::<crate::repo_lock::ResourceBlocked>() => false,
1983        Err(_) => true,
1984        Ok(out) => output_advances(out),
1985    }
1986}
1987
1988/// [`chain_advances`] for a call that did return an output: the `Ok` half,
1989/// shared with callers that classify the call into their own outcome type
1990/// first (the graph's fixer chain).
1991pub fn output_advances(out: &AgentOutput) -> bool {
1992    out.quota_exhausted() || !out.usable()
1993}
1994
1995fn ids(agents: &[AgentSpec]) -> String {
1996    if agents.is_empty() {
1997        return "no agents at all".to_owned();
1998    }
1999    agents
2000        .iter()
2001        .map(|a| a.id.clone())
2002        .collect::<Vec<_>>()
2003        .join(", ")
2004}
2005
2006/// Isolate post-spawn pressure injection from real admission policy and from
2007/// other concurrent runs. This hook never exists in the shipped executable.
2008#[cfg(all(test, unix))]
2009pub(crate) mod test_watchdog {
2010    use super::*;
2011    static FLOORS: Mutex<BTreeMap<String, u64>> = Mutex::new(BTreeMap::new());
2012
2013    pub(crate) struct Guard(String);
2014
2015    pub(crate) fn set(run: &str, floor: u64) -> Guard {
2016        assert!(
2017            FLOORS
2018                .lock()
2019                .unwrap()
2020                .insert(run.to_owned(), floor)
2021                .is_none()
2022        );
2023        Guard(run.to_owned())
2024    }
2025
2026    pub(super) fn floor(run: &str, configured: u64) -> u64 {
2027        FLOORS
2028            .lock()
2029            .unwrap()
2030            .get(run)
2031            .copied()
2032            .unwrap_or(configured)
2033    }
2034
2035    impl Drop for Guard {
2036        fn drop(&mut self) {
2037            FLOORS.lock().unwrap().remove(&self.0);
2038        }
2039    }
2040}
2041
2042#[cfg(test)]
2043mod tests {
2044    use super::*;
2045
2046    const COMMAND_HELPER_MODE: &str = "MAGI_TEST_COMMAND_HELPER_MODE";
2047
2048    /// Test-only command agent implemented by this test binary itself. Unlike
2049    /// `echo` and `sleep`, it is available wherever the Rust tests run.
2050    fn command_helper(mode: &str) -> AgentSpec {
2051        // Invocation's disk monitor reads run state even without a build cache.
2052        crate::run::pin_test_home();
2053        AgentSpec {
2054            id: "helper".to_owned(),
2055            kind: AgentKind::Command,
2056            model: None,
2057            command: vec![
2058                std::env::current_exe()
2059                    .expect("locate test helper")
2060                    .to_string_lossy()
2061                    .into_owned(),
2062                "--exact".to_owned(),
2063                "agent::tests::command_agent_test_helper".to_owned(),
2064                "--nocapture".to_owned(),
2065            ],
2066            extra_args: Vec::new(),
2067            env: BTreeMap::from([(COMMAND_HELPER_MODE.to_owned(), mode.to_owned())]),
2068            prompt_delivery: None,
2069            max_turn_secs: None,
2070        }
2071    }
2072
2073    #[test]
2074    fn command_agent_test_helper() {
2075        match std::env::var(COMMAND_HELPER_MODE).as_deref() {
2076            Ok("reply") => println!("hello {}", std::env::var("MAGI_SEAT").unwrap()),
2077            Ok("cache") => println!("{}", std::env::var("CARGO_TARGET_DIR").unwrap()),
2078            Ok("no-cache") => println!(
2079                "{}",
2080                std::env::var("CARGO_TARGET_DIR").unwrap_or_else(|_| "ABSENT".to_owned())
2081            ),
2082            Ok("ignore-stdin") => println!("done"),
2083            Ok("chatty-sleep") => {
2084                println!("i-said-something");
2085                std::thread::sleep(Duration::from_secs(30));
2086            }
2087            Ok("sleep") => std::thread::sleep(Duration::from_secs(30)),
2088            Ok(other) => panic!("unknown command helper mode {other}"),
2089            Err(_) => {}
2090        }
2091    }
2092
2093    fn spec(kind: AgentKind, model: Option<&str>) -> AgentSpec {
2094        AgentSpec {
2095            id: "a".to_owned(),
2096            kind,
2097            model: model.map(str::to_owned),
2098            command: vec!["echo".to_owned(), "{label}".to_owned()],
2099            extra_args: Vec::new(),
2100            env: BTreeMap::new(),
2101            prompt_delivery: None,
2102            max_turn_secs: None,
2103        }
2104    }
2105
2106    fn inv<'a>(cwd: &'a Path, art: &'a Path, allow_write: bool) -> Invocation<'a> {
2107        Invocation {
2108            coordination: None,
2109            fetched_base: None,
2110            cwd,
2111            prompt: "do the thing",
2112            timeout: Duration::from_secs(900),
2113            allow_write,
2114            sessions: true,
2115            artifacts: art,
2116            stem: "t",
2117            run: "test-run",
2118            node: "test",
2119            cache_dir: None,
2120            attachments: &[],
2121            writable: &[],
2122        }
2123    }
2124
2125    fn plan_for(kind: AgentKind, seat: &SeatState, allow_write: bool) -> Plan {
2126        build_command(
2127            &spec(kind, None),
2128            seat,
2129            &inv(Path::new("."), Path::new("/art"), allow_write),
2130            Path::new("/art/p.md"),
2131        )
2132        .unwrap()
2133    }
2134
2135    #[test]
2136    fn editing_access_requires_fetch_evidence_and_keeps_snapshot() {
2137        let missing = editing_access_note(None);
2138        assert!(missing.contains("No successful launcher fetch evidence"));
2139        let base = crate::run::FetchedBase {
2140            remote: "origin".into(),
2141            branch: "main".into(),
2142            commit: "0123456789abcdef".into(),
2143            fetched_at: "2026-10-18T00:00:00Z".parse().unwrap(),
2144        };
2145        let note = editing_access_note(Some(&base));
2146        for expected in [
2147            "origin/main",
2148            "0123456789abcdef",
2149            "2026-10-18T00:00:00Z",
2150            "Do not fetch again",
2151        ] {
2152            assert!(note.contains(expected), "missing {expected}");
2153        }
2154        // Editing seats run without an OS sandbox, so nothing tells them
2155        // their network, Git or temporary-directory access is restricted.
2156        for text in [&missing, &note] {
2157            assert!(!text.to_lowercase().contains("sandbox"), "{text}");
2158            assert!(!text.contains("Network access is restricted"), "{text}");
2159        }
2160        let roundtrip: crate::run::FetchedBase =
2161            serde_json::from_str(&serde_json::to_string(&base).unwrap()).unwrap();
2162        assert_eq!(editing_access_note(Some(&roundtrip)), note);
2163    }
2164
2165    #[test]
2166    fn codex_editing_seats_bypass_the_sandbox_on_initial_and_resume() {
2167        const BYPASS: &str = "--dangerously-bypass-approvals-and-sandbox";
2168        let roots = [PathBuf::from("/shared/git"), PathBuf::from("/questions")];
2169        for resumed in [false, true] {
2170            let mut seat = SeatState::new("impl-A", "a", 7);
2171            if resumed {
2172                seat.turns = 1;
2173                seat.captured_session = Some("fixture-thread".into());
2174            }
2175            let build = |invocation: &Invocation<'_>| {
2176                build_command(
2177                    &spec(AgentKind::Codex, None),
2178                    &seat,
2179                    invocation,
2180                    Path::new("/art/p.md"),
2181                )
2182                .unwrap()
2183            };
2184            for node in [
2185                "implement",
2186                "fix",
2187                "graft",
2188                "gate-fix",
2189                "land",
2190                "rebase",
2191                "base-conflict",
2192                crate::queue::CHAT_NODE,
2193                "external-chat",
2194            ] {
2195                let mut invocation = inv(Path::new("."), Path::new("/art"), true);
2196                invocation.node = node;
2197                invocation.writable = &roots;
2198                let plan = build(&invocation);
2199                let at = plan.argv.iter().position(|s| s == BYPASS);
2200                assert!(at.is_some(), "{node}: {:?}", plan.argv);
2201                if resumed {
2202                    let resume = plan.argv.iter().position(|s| s == "resume").unwrap();
2203                    assert!(at.unwrap() < resume, "{node}: {:?}", plan.argv);
2204                }
2205                // No sandbox, approval or sandbox-scoped override survives.
2206                assert!(!plan.argv.iter().any(|s| s == "--sandbox"), "{node}");
2207                assert!(!plan.argv.iter().any(|s| s == "-c"), "{node}");
2208            }
2209            for (node, write) in [
2210                ("review", false),
2211                ("judge", false),
2212                ("advise", false),
2213                ("implement", false),
2214                ("fix", false),
2215                ("dupes", false),
2216                ("conduct", false),
2217                ("waiter", false),
2218                ("talk-title", false),
2219                (crate::queue::CHAT_NODE, false),
2220                ("external-chat", false),
2221                ("deputy", true),
2222            ] {
2223                let mut invocation = inv(Path::new("."), Path::new("/art"), write);
2224                invocation.node = node;
2225                let plan = build(&invocation);
2226                assert!(!plan.argv.iter().any(|s| s == BYPASS), "{node}");
2227                let mode = if write {
2228                    "workspace-write"
2229                } else {
2230                    "read-only"
2231                };
2232                assert!(
2233                    plan.argv.windows(2).any(|w| w == ["--sandbox", mode]),
2234                    "{node}: {:?}",
2235                    plan.argv
2236                );
2237                assert!(
2238                    plan.argv
2239                        .windows(2)
2240                        .any(|w| w == ["-c", "approval_policy=\"never\""]),
2241                    "{node}"
2242                );
2243            }
2244        }
2245    }
2246
2247    #[test]
2248    fn claude_mints_then_resumes_the_same_uuid() {
2249        let mut seat = SeatState::new("judge-1", "a", 7);
2250        let uuid = seat.claude_session.clone().unwrap();
2251        let first = plan_for(AgentKind::Claude, &seat, true);
2252        assert!(first.argv.windows(2).any(|w| w == ["--session-id", &uuid]));
2253        assert!(!first.argv.iter().any(|a| a == "--resume"));
2254
2255        seat.turns = 1;
2256        let second = plan_for(AgentKind::Claude, &seat, true);
2257        assert!(second.argv.windows(2).any(|w| w == ["--resume", &uuid]));
2258        assert!(!second.argv.iter().any(|a| a == "--session-id"));
2259    }
2260
2261    #[test]
2262    fn github_bound_claude_seats_override_the_operators_answer_language() {
2263        let seat = SeatState::new("change-summary", "a", 7);
2264        let art = Path::new("/art");
2265        for (language, name) in [("en", "English"), ("", "English"), ("ja", "Japanese")] {
2266            let claude =
2267                for_github_text(&spec(AgentKind::Claude, None), language, Path::new(".")).unwrap();
2268            let plan = build_command(
2269                &claude,
2270                &seat,
2271                &inv(Path::new("."), art, false),
2272                Path::new("/art/p.md"),
2273            )
2274            .unwrap();
2275            let settings = format!(r#"{{"language":"{name}"}}"#);
2276            assert!(
2277                plan.argv
2278                    .windows(2)
2279                    .any(|w| w == ["--settings", settings.as_str()]),
2280                "{:?}",
2281                plan.argv
2282            );
2283            // The prompt still arrives on stdin, not as an argument a
2284            // variadic flag could swallow.
2285            assert_eq!(plan.stdin.as_deref(), Some("do the thing"));
2286        }
2287        for kind in [
2288            AgentKind::Codex,
2289            AgentKind::Opencode,
2290            AgentKind::Antigravity,
2291            AgentKind::Omp,
2292        ] {
2293            assert!(
2294                for_github_text(&spec(kind, None), "en", Path::new("."))
2295                    .unwrap()
2296                    .extra_args
2297                    .is_empty()
2298            );
2299        }
2300    }
2301
2302    #[test]
2303    fn github_text_preserves_existing_settings() {
2304        let dir = tempfile::tempdir().unwrap();
2305        let original = serde_json::json!({
2306            "language": "Japanese",
2307            "env": { "SEAT_MODE": "configured" },
2308            "apiKeyHelper": "credential-helper",
2309            "hooks": { "Stop": [] }
2310        });
2311        std::fs::write(dir.path().join("seat-settings.json"), original.to_string()).unwrap();
2312        for value in [original.to_string(), "./seat-settings.json".to_owned()] {
2313            for equals in [false, true] {
2314                let mut spec = spec(AgentKind::Claude, None);
2315                // Earlier settings stay earlier; the CLI's last value wins.
2316                spec.extra_args = vec!["--settings={\"language\":\"French\"}".to_owned()];
2317                if equals {
2318                    spec.extra_args.push(format!("--settings={value}"));
2319                } else {
2320                    spec.extra_args
2321                        .extend(["--settings".to_owned(), value.clone()]);
2322                }
2323                spec.extra_args.push("--verbose".to_owned());
2324                let updated = for_github_text(&spec, "en", dir.path()).unwrap();
2325                assert_eq!(updated.extra_args.len(), spec.extra_args.len());
2326                assert_eq!(updated.extra_args[0], spec.extra_args[0]);
2327                assert_eq!(updated.extra_args.last(), spec.extra_args.last());
2328                let value = &updated.extra_args[updated.extra_args.len() - 2];
2329                let actual: serde_json::Value =
2330                    serde_json::from_str(value.strip_prefix("--settings=").unwrap_or(value))
2331                        .unwrap();
2332                let mut expected = original.clone();
2333                expected["language"] = serde_json::json!("English");
2334                assert_eq!(actual, expected);
2335            }
2336        }
2337        let on_disk: serde_json::Value = serde_json::from_str(
2338            &std::fs::read_to_string(dir.path().join("seat-settings.json")).unwrap(),
2339        )
2340        .unwrap();
2341        assert_eq!(on_disk, original);
2342    }
2343
2344    #[test]
2345    fn github_text_settings_are_redacted_from_command_logging() {
2346        let dir = tempfile::tempdir().unwrap();
2347        let settings = serde_json::json!({ "env": { "AUTH_TOKEN": "test-only-secret" } });
2348        std::fs::write(dir.path().join("seat-settings.json"), settings.to_string()).unwrap();
2349        for equals in [false, true] {
2350            let mut spec = spec(AgentKind::Claude, None);
2351            spec.extra_args =
2352                vec!["--settings={\"env\":{\"AUTH_TOKEN\":\"earlier-secret\"}}".to_owned()];
2353            if equals {
2354                spec.extra_args
2355                    .push("--settings=./seat-settings.json".to_owned());
2356            } else {
2357                spec.extra_args
2358                    .extend(["--settings".to_owned(), "./seat-settings.json".to_owned()]);
2359            }
2360            let spec = for_github_text(&spec, "en", dir.path()).unwrap();
2361            let plan = build_command(
2362                &spec,
2363                &SeatState::new("change-summary", "a", 7),
2364                &inv(dir.path(), dir.path(), false),
2365                &dir.path().join("prompt.md"),
2366            )
2367            .unwrap();
2368            // Execution still receives both the configured token and language.
2369            let actual = plan.argv.last().unwrap();
2370            let actual: serde_json::Value =
2371                serde_json::from_str(actual.strip_prefix("--settings=").unwrap_or(actual)).unwrap();
2372            assert_eq!(actual["env"]["AUTH_TOKEN"], "test-only-secret");
2373            assert_eq!(actual["language"], "English");
2374            let logged = format!("{:?}", plan.logged_argv());
2375            assert!(!logged.contains("secret"));
2376            assert!(!logged.contains("AUTH_TOKEN"));
2377            assert!(logged.contains("[redacted]"));
2378            assert_eq!(plan.logged_argv()[0], "claude");
2379            assert!(plan.logged_argv().contains(&"--output-format"));
2380        }
2381    }
2382
2383    #[test]
2384    fn github_text_rejects_unreadable_or_invalid_settings() {
2385        let dir = tempfile::tempdir().unwrap();
2386        std::fs::write(dir.path().join("bad.json"), "invalid json").unwrap();
2387        std::fs::write(dir.path().join("array.json"), "[]").unwrap();
2388        for args in [
2389            vec!["--settings"],
2390            vec!["--settings", "missing.json"],
2391            vec!["--settings=bad.json"],
2392            vec!["--settings", "array.json"],
2393        ] {
2394            let mut spec = spec(AgentKind::Claude, None);
2395            spec.extra_args = args.into_iter().map(str::to_owned).collect();
2396            assert!(for_github_text(&spec, "en", dir.path()).is_err());
2397        }
2398    }
2399
2400    #[test]
2401    fn read_only_seats_cannot_edit() {
2402        let seat = SeatState::new("judge-1", "a", 7);
2403        let claude = plan_for(AgentKind::Claude, &seat, false);
2404        assert!(claude.argv.iter().any(|a| a == "--disallowed-tools"));
2405        assert!(
2406            !plan_for(AgentKind::Claude, &seat, true)
2407                .argv
2408                .iter()
2409                .any(|a| a == "--disallowed-tools")
2410        );
2411
2412        let agy = plan_for(AgentKind::Antigravity, &seat, false);
2413        assert!(agy.argv.windows(2).any(|w| w == ["--mode", "plan"]));
2414        assert!(
2415            !agy.argv
2416                .iter()
2417                .any(|a| a == "--dangerously-skip-permissions")
2418        );
2419        let agy_rw = plan_for(AgentKind::Antigravity, &seat, true);
2420        assert!(
2421            agy_rw
2422                .argv
2423                .windows(2)
2424                .any(|w| w == ["--mode", "accept-edits"])
2425        );
2426        assert!(
2427            agy_rw
2428                .argv
2429                .iter()
2430                .any(|a| a == "--dangerously-skip-permissions")
2431        );
2432        // agy is pointed at its prompt with its own `@<path>` syntax, not with
2433        // prose asking it to read a file. Measured on one trivial task: 17s
2434        // against 73s, because prose costs a tool round-trip before the model
2435        // has even seen its instructions. It is also the form rvpm proved.
2436        let agy_prompt = agy_rw
2437            .argv
2438            .iter()
2439            .position(|a| a == "-p")
2440            .map(|i| agy_rw.argv[i + 1].clone())
2441            .expect("agy takes its prompt with -p");
2442        assert!(
2443            agy_prompt.starts_with('@'),
2444            "agy must get a file reference, got {agy_prompt:?}"
2445        );
2446        assert!(
2447            !agy_prompt.contains("Read the file at"),
2448            "the prose pointer is for CLIs with no file syntax"
2449        );
2450
2451        // opencode is the exception: `--auto` also gates reads, so withholding
2452        // it silently drops the seat out of the panel. Verified against the CLI
2453        // — a read-only judge failed with "the user rejected permission to use
2454        // this specific tool call" while trying to open its own prompt.
2455        for allow_write in [false, true] {
2456            assert!(
2457                plan_for(AgentKind::Opencode, &seat, allow_write)
2458                    .argv
2459                    .iter()
2460                    .any(|a| a == "--auto"),
2461                "opencode needs --auto even to read (allow_write = {allow_write})"
2462            );
2463        }
2464    }
2465
2466    /// The three things about `codex exec` that were established by hand and
2467    /// that a rewrite would silently get wrong.
2468    #[test]
2469    fn codex_gets_extra_writable_roots_only_when_it_may_write() {
2470        let seat = SeatState::new("deputy-x", "a", 7);
2471        let roots = [PathBuf::from("/data/questions")];
2472        let mk = |allow_write: bool| {
2473            let mut i = inv(Path::new("."), Path::new("/art"), allow_write);
2474            i.writable = &roots;
2475            build_command(
2476                &spec(AgentKind::Codex, None),
2477                &seat,
2478                &i,
2479                Path::new("/art/p.md"),
2480            )
2481            .unwrap()
2482        };
2483        let want = "sandbox_workspace_write.writable_roots=[\"/data/questions\"]";
2484        assert!(mk(true).argv.windows(2).any(|w| w == ["-c", want]));
2485        assert!(!mk(false).argv.iter().any(|a| a.contains("writable_roots")));
2486    }
2487
2488    #[test]
2489    fn repository_write_scope_covers_editing_nodes_without_changing_other_roles() {
2490        let mut i = inv(Path::new("."), Path::new("/art"), true);
2491        for node in [
2492            "implement",
2493            "fix",
2494            "graft",
2495            "gate-fix",
2496            "land",
2497            "rebase",
2498            "base-conflict",
2499            "chat",
2500            "external-chat",
2501        ] {
2502            i.node = node;
2503            assert!(repository_writer(&i), "{node}");
2504            i.allow_write = false;
2505            assert!(!repository_writer(&i), "{node}");
2506            i.allow_write = true;
2507        }
2508        for node in ["deputy", "judge", "review", "bump", "conduct", "talk-title"] {
2509            i.node = node;
2510            assert!(!repository_writer(&i), "{node}");
2511        }
2512        i.node = "chat";
2513        let roots = [PathBuf::from("/questions")];
2514        i.writable = &roots;
2515        assert!(
2516            repository_writer(&i),
2517            "explicit roots do not change the role"
2518        );
2519        assert!(
2520            !repository_seat(&i),
2521            "chat turns bypass repository scheduling"
2522        );
2523    }
2524
2525    #[test]
2526    fn coordination_classification_is_independent_of_write_grants() {
2527        let roots = [PathBuf::from("/questions")];
2528        for node in [
2529            crate::queue::CHAT_NODE,
2530            "external-chat",
2531            "implement",
2532            "fix",
2533            "graft",
2534            "gate-fix",
2535            "land",
2536            "rebase",
2537            "base-conflict",
2538            "review",
2539            "judge",
2540            "advise",
2541            "deputy",
2542            "waiter",
2543            "conduct",
2544            "dupes",
2545            "talk-title",
2546        ] {
2547            for allow_write in [false, true] {
2548                for writable in [&[][..], &roots[..]] {
2549                    let mut i = inv(Path::new("."), Path::new("/art"), allow_write);
2550                    i.node = node;
2551                    i.writable = writable;
2552                    assert_eq!(
2553                        repository_seat(&i),
2554                        !matches!(
2555                            node,
2556                            crate::queue::CHAT_NODE
2557                                | "external-chat"
2558                                | "talk-title"
2559                                | "deputy"
2560                                | "conduct"
2561                                | "dupes"
2562                        ),
2563                        "{node}, allow_write={allow_write}, writable={writable:?}"
2564                    );
2565                    if matches!(node, crate::queue::CHAT_NODE | "external-chat") {
2566                        assert_eq!(repository_writer(&i), allow_write);
2567                    }
2568                }
2569            }
2570        }
2571    }
2572
2573    #[test]
2574    fn writable_directories_reach_initial_and_resumed_adapter_commands() {
2575        let roots = [
2576            PathBuf::from("/shared/git"),
2577            PathBuf::from("/state/questions"),
2578        ];
2579        for kind in [AgentKind::Codex, AgentKind::Antigravity] {
2580            for resumed in [false, true] {
2581                let mut seat = SeatState::new("impl-A", "a", 7);
2582                if resumed {
2583                    seat.turns = 1;
2584                    seat.captured_session = Some("session-id".into());
2585                }
2586                for allow_write in [false, true] {
2587                    let mut i = inv(Path::new("."), Path::new("/art"), allow_write);
2588                    i.writable = &roots;
2589                    let plan = build_command(&spec(kind, None), &seat, &i, Path::new("/art/p.md"))
2590                        .unwrap();
2591                    for root in &roots {
2592                        if kind == AgentKind::Antigravity {
2593                            assert_eq!(
2594                                plan.argv.windows(2).any(|w| {
2595                                    w[0] == "--add-dir" && w[1] == root.to_str().unwrap()
2596                                }),
2597                                allow_write,
2598                                "resumed={resumed}: {:?}",
2599                                plan.argv
2600                            );
2601                        }
2602                        assert_eq!(
2603                            plan.argv
2604                                .iter()
2605                                .any(|arg| arg.contains(root.to_str().unwrap())),
2606                            allow_write,
2607                            "{kind:?}, resumed={resumed}: {:?}",
2608                            plan.argv
2609                        );
2610                    }
2611                    if kind == AgentKind::Codex && resumed {
2612                        let at = plan.argv.iter().position(|s| s == "resume").unwrap();
2613                        assert!(!plan.argv[at..].iter().any(|s| s == "-c"));
2614                    }
2615                }
2616            }
2617        }
2618    }
2619
2620    #[test]
2621    fn codex_is_sandboxed_reads_stdin_and_puts_resume_last() {
2622        let mut seat = SeatState::new("judge-1", "a", 7);
2623
2624        // 1. Read-only is enforced by the CLI, not by the prompt - the only
2625        //    roster member for which that is true - and only repository
2626        //    editing seats (see `codex_editing_seats_bypass_the_sandbox_on_initial_and_resume`)
2627        //    ever get the bypass. A seat that may write without editing the
2628        //    repository (a deputy's stores) keeps the workspace sandbox.
2629        let ro = plan_for(AgentKind::Codex, &seat, false);
2630        assert!(ro.argv.windows(2).any(|w| w == ["--sandbox", "read-only"]));
2631        let rw = plan_for(AgentKind::Codex, &seat, true);
2632        assert!(
2633            rw.argv
2634                .windows(2)
2635                .any(|w| w == ["--sandbox", "workspace-write"])
2636        );
2637        for p in [&ro, &rw] {
2638            assert!(
2639                !p.argv
2640                    .iter()
2641                    .any(|a| a == "--dangerously-bypass-approvals-and-sandbox"),
2642                "the bypass defeats the only enforced read-only mode we have"
2643            );
2644            // Nobody is watching to approve anything.
2645            assert!(
2646                p.argv
2647                    .windows(2)
2648                    .any(|w| w == ["-c", "approval_policy=\"never\""]),
2649                "an unattended seat that asks for approval blocks until timeout"
2650            );
2651        }
2652
2653        // 2. The prompt arrives on stdin, and `-` is what makes codex read it.
2654        assert_eq!(ro.stdin.as_deref(), Some("do the thing"));
2655        assert_eq!(
2656            ro.argv.last().map(String::as_str),
2657            Some("-"),
2658            "without the `-` argument codex waits for a prompt it never gets"
2659        );
2660
2661        // 3. `resume` is a subcommand and rejects the options above when they
2662        //    follow it, so it has to be emitted after all of them - and only
2663        //    once the CLI has reported a thread id.
2664        seat.turns = 1;
2665        assert!(!has_session(AgentKind::Codex, &seat, true));
2666        assert!(
2667            !plan_for(AgentKind::Codex, &seat, true)
2668                .argv
2669                .iter()
2670                .any(|a| a == "resume")
2671        );
2672        seat.captured_session = Some("01a07440-4545-7492-85c1-024e3259a90a".to_owned());
2673        let resumed = plan_for(AgentKind::Codex, &seat, true);
2674        let at = resumed
2675            .argv
2676            .iter()
2677            .position(|a| a == "resume")
2678            .expect("resumes by subcommand");
2679        assert_eq!(resumed.argv[at + 1], "01a07440-4545-7492-85c1-024e3259a90a");
2680        assert!(
2681            resumed.argv[..at].iter().any(|a| a == "--sandbox"),
2682            "every option precedes the subcommand"
2683        );
2684        assert_eq!(resumed.argv.last().map(String::as_str), Some("-"));
2685    }
2686
2687    /// The three things about `omp -p --mode=json` that were established by
2688    /// hand against omp 18.1.19 and that a rewrite would silently get wrong.
2689    #[test]
2690    fn omp_reads_stdin_auto_approves_and_resumes_by_id() {
2691        let mut seat = SeatState::new("review-1", "a", 7);
2692
2693        // 1. Print mode plus JSON, and the prompt on stdin: a judging prompt
2694        //    carrying three patches is past the Windows argv cap, so argv
2695        //    delivery is not an option for every node.
2696        let first = plan_for(AgentKind::Omp, &seat, false);
2697        assert!(first.argv.iter().any(|a| a == "-p"));
2698        assert!(first.argv.iter().any(|a| a == "--mode=json"));
2699        assert_eq!(first.stdin.as_deref(), Some("do the thing"));
2700        assert!(
2701            !first.argv.iter().any(|a| a == "do the thing"),
2702            "the prompt reached argv, where Windows caps it"
2703        );
2704
2705        // 2. `--auto-approve` is required (an unattended seat that stops to ask
2706        //    blocks until its node timeout kills it), and it is the *only*
2707        //    permission flag: omp has no read-only mode, so the bypass flag
2708        //    that would throw away codex's one enforced guarantee must never
2709        //    appear here either.
2710        for allow_write in [false, true] {
2711            let p = plan_for(AgentKind::Omp, &seat, allow_write);
2712            assert!(
2713                p.argv.iter().any(|a| a == "--auto-approve"),
2714                "omp needs --auto-approve even to read (allow_write = {allow_write})"
2715            );
2716            assert!(
2717                !p.argv
2718                    .iter()
2719                    .any(|a| a == "--dangerously-bypass-approvals-and-sandbox"),
2720                "nothing ever asks for the bypass"
2721            );
2722        }
2723
2724        // 3. The id omp reports is the only resume token - magi cannot mint it
2725        //    up front, so a seat resumes only once a turn has reported one.
2726        seat.turns = 1;
2727        assert!(!has_session(AgentKind::Omp, &seat, true));
2728        assert!(
2729            !plan_for(AgentKind::Omp, &seat, true)
2730                .argv
2731                .iter()
2732                .any(|a| a == "--resume")
2733        );
2734        seat.captured_session = Some("01a09fe9-4e31-7226-85b3-fda6f46689d5".to_owned());
2735        let resumed = plan_for(AgentKind::Omp, &seat, true);
2736        assert!(
2737            resumed
2738                .argv
2739                .windows(2)
2740                .any(|w| w == ["--resume", "01a09fe9-4e31-7226-85b3-fda6f46689d5"]),
2741            "a captured id is what makes the next turn a resume"
2742        );
2743        // `--continue` opens a *new* session instead of the stored one, which
2744        // would silently drop the seat's memory.
2745        assert!(!resumed.argv.iter().any(|a| a == "--continue"));
2746        // stdin still carries the prompt on a resumed turn.
2747        assert_eq!(resumed.stdin.as_deref(), Some("do the thing"));
2748    }
2749
2750    /// The extraction trap that cost three complete reviews when it was done by
2751    /// hand: a turn that ends on a tool call emits **no** `agent_end` line, so
2752    /// keying on `agent_end` finds nothing and the seat reads as one that
2753    /// produced no answer at all.
2754    #[test]
2755    fn omp_takes_the_answer_without_an_agent_end_line() {
2756        let stream = concat!(
2757            r#"{"type":"session","version":3,"id":"01a09fe9-4e31-7226-85b3-fda6f46689d5","cwd":"C:\\w"}"#,
2758            "\n",
2759            r#"{"type":"agent_start"}"#,
2760            "\n",
2761            r#"{"type":"turn_start"}"#,
2762            "\n",
2763            r#"{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":1,"delta":"."}}"#,
2764            "\n",
2765            r#"{"type":"message_end","message":{"role":"assistant","content":[{"type":"thinking","thinking":"checking"},{"type":"text","text":"."}]}}"#,
2766            "\n",
2767            r#"{"type":"turn_end","message":{"role":"assistant","content":[{"type":"thinking","thinking":"done"},{"type":"text","text":"{\"vote\":\"approve\"}"}]}}"#,
2768            "\n",
2769        );
2770        let out = extract(AgentKind::Omp, stream);
2771        assert_eq!(
2772            out.text, "{\"vote\":\"approve\"}",
2773            "the last assistant text block is the answer even with no agent_end"
2774        );
2775        assert_eq!(
2776            out.session.as_deref(),
2777            Some("01a09fe9-4e31-7226-85b3-fda6f46689d5")
2778        );
2779    }
2780
2781    /// A stream that *does* carry `agent_end` walks the whole thread, and the
2782    /// last non-empty assistant text still wins over the tool-loop narration
2783    /// that came before it.
2784    #[test]
2785    fn omp_walks_agent_end_and_ignores_tool_loop_narration() {
2786        let stream = concat!(
2787            r#"{"type":"session","version":3,"id":"s1"}"#,
2788            "\n",
2789            "{\"type\":\"agent_end\",\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"review this\"}]},{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Looking at the diff…\"}]},{\"role\":\"assistant\",\"content\":[{\"type\":\"thinking\",\"thinking\":\"…\"},{\"type\":\"text\",\"text\":\"## 判定\\n\\n問題ありません。\"}]}]}",
2790            "\n",
2791        );
2792        let out = extract(AgentKind::Omp, stream);
2793        assert_eq!(
2794            out.text, "## 判定\n\n問題ありません。",
2795            "the narration is not the answer, and non-ASCII survives intact"
2796        );
2797        assert_eq!(out.session.as_deref(), Some("s1"));
2798    }
2799
2800    /// A line that is not JSON - a CLI warning, a half-written line - is
2801    /// skipped rather than becoming the answer.
2802    #[test]
2803    fn omp_skips_non_json_lines() {
2804        let stream = concat!(
2805            "Warning: some omp notice\n",
2806            r#"{"type":"session","version":3,"id":"s2"}"#,
2807            "\n",
2808            r#"{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"the answer"}]}}"#,
2809            "\n",
2810            "trailing junk",
2811            "\n",
2812        );
2813        let out = extract(AgentKind::Omp, stream);
2814        assert_eq!(out.text, "the answer");
2815        assert_eq!(out.session.as_deref(), Some("s2"));
2816    }
2817
2818    /// A real `codex exec --json` stream, tracing prefix included.
2819    #[test]
2820    fn codex_takes_the_last_agent_message_and_the_thread_id() {
2821        let stream = concat!(
2822            "2026-09-06T01:05:49.394445Z ERROR codex_models_manager: failed to load models cache\n",
2823            r#"{"type":"thread.started","thread_id":"01a07440-4545-7492-85c1-024e3259a90a"}"#,
2824            "\n",
2825            r#"{"type":"turn.started"}"#,
2826            "\n",
2827            r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"Looking into it."}}"#,
2828            "\n",
2829            r#"{"type":"item.completed","item":{"id":"item_1","type":"command_execution","text":"cargo test"}}"#,
2830            "\n",
2831            r#"{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"{\"verdict\": \"ok\"}"}}"#,
2832            "\n",
2833            r#"{"type":"turn.completed","usage":{"input_tokens":17137}}"#,
2834            "\n",
2835        );
2836        let out = extract(AgentKind::Codex, stream);
2837        assert_eq!(
2838            out.text, "{\"verdict\": \"ok\"}",
2839            "the last agent message is the answer; earlier ones narrate"
2840        );
2841        assert_eq!(
2842            out.session.as_deref(),
2843            Some("01a07440-4545-7492-85c1-024e3259a90a")
2844        );
2845        assert_eq!(out.status.as_deref(), Some("success"));
2846
2847        let failed = concat!(
2848            r#"{"type":"thread.started","thread_id":"t1"}"#,
2849            "\n",
2850            r#"{"type":"turn.failed","error":{"message":"nope"}}"#,
2851            "\n",
2852        );
2853        assert_eq!(
2854            extract(AgentKind::Codex, failed).status.as_deref(),
2855            Some("error")
2856        );
2857    }
2858
2859    #[test]
2860    fn captured_sessions_resume_only_once_reported() {
2861        let mut seat = SeatState::new("impl-A", "a", 7);
2862        seat.turns = 1;
2863        for kind in [AgentKind::Opencode, AgentKind::Antigravity] {
2864            assert!(!has_session(kind, &seat, true));
2865            let p = plan_for(kind, &seat, true);
2866            assert!(!p.argv.iter().any(|a| a == "-s" || a == "--conversation"));
2867        }
2868
2869        seat.captured_session = Some("sid".to_owned());
2870        assert!(has_session(AgentKind::Opencode, &seat, true));
2871        assert!(
2872            plan_for(AgentKind::Opencode, &seat, true)
2873                .argv
2874                .windows(2)
2875                .any(|w| w == ["-s", "sid"])
2876        );
2877        assert!(
2878            plan_for(AgentKind::Antigravity, &seat, true)
2879                .argv
2880                .windows(2)
2881                .any(|w| w == ["--conversation", "sid"])
2882        );
2883    }
2884
2885    #[test]
2886    fn sessions_disabled_never_resumes() {
2887        let mut seat = SeatState::new("impl-A", "a", 7);
2888        seat.turns = 3;
2889        seat.captured_session = Some("sid".to_owned());
2890        for kind in [
2891            AgentKind::Claude,
2892            AgentKind::Opencode,
2893            AgentKind::Antigravity,
2894        ] {
2895            assert!(!has_session(kind, &seat, false));
2896        }
2897    }
2898
2899    #[test]
2900    fn long_prompts_never_reach_argv_for_file_delivery_clis() {
2901        let seat = SeatState::new("judge-1", "a", 7);
2902        for kind in [AgentKind::Opencode, AgentKind::Antigravity] {
2903            let p = plan_for(kind, &seat, false);
2904            assert!(
2905                p.argv.iter().all(|a| a != "do the thing"),
2906                "{kind:?} put the prompt on the command line"
2907            );
2908            assert!(p.argv.iter().any(|a| a.contains("/art/p.md")));
2909        }
2910        // agy has no text stdin, so its `-p` must always carry something.
2911        let p = plan_for(AgentKind::Antigravity, &seat, false);
2912        let at = p.argv.iter().position(|a| a == "-p").unwrap();
2913        assert!(p.argv.get(at + 1).is_some_and(|v| v.contains("p.md")));
2914        assert!(p.stdin.is_none());
2915    }
2916
2917    #[test]
2918    fn agy_print_timeout_tracks_the_node_budget() {
2919        let seat = SeatState::new("impl-A", "a", 7);
2920        let p = build_command(
2921            &spec(AgentKind::Antigravity, None),
2922            &seat,
2923            &Invocation {
2924                coordination: None,
2925                fetched_base: None,
2926                cwd: Path::new("."),
2927                prompt: "p",
2928                timeout: Duration::from_secs(3600),
2929                allow_write: true,
2930                sessions: true,
2931                artifacts: Path::new("/art"),
2932                stem: "t",
2933                run: "test-run",
2934                node: "test",
2935                cache_dir: None,
2936                attachments: &[],
2937                writable: &[],
2938            },
2939            Path::new("/art/p.md"),
2940        )
2941        .unwrap();
2942        assert!(p.argv.windows(2).any(|w| w == ["--print-timeout", "3600s"]));
2943    }
2944
2945    /// `--add-dir` is what lets antigravity open a file outside the
2946    /// worktree at all. Today that only happens when the delivery mode is
2947    /// already `File`, but an attachment can arrive on a seat whose delivery
2948    /// is `Stdin` or `Argv` (an explicit `prompt_delivery` override), and the
2949    /// image still lives outside `cwd` - so the flag has to widen for that
2950    /// reason too, independent of how the prompt itself is delivered.
2951    #[test]
2952    fn attachments_widen_antigravitys_add_dir_even_off_file_delivery() {
2953        let mut s = spec(AgentKind::Antigravity, None);
2954        s.prompt_delivery = Some(Delivery::Argv);
2955        let seat = SeatState::new("talk", "a", 7);
2956        let atts = [PathBuf::from("/art/attachments/abc.png")];
2957
2958        let without = build_command(
2959            &s,
2960            &seat,
2961            &Invocation {
2962                attachments: &[],
2963                writable: &[],
2964                ..inv(Path::new("."), Path::new("/art"), true)
2965            },
2966            Path::new("/art/p.md"),
2967        )
2968        .unwrap();
2969        assert!(
2970            !without.argv.iter().any(|a| a == "--add-dir"),
2971            "no attachment, no reason to widen the sandbox: {without:?}"
2972        );
2973
2974        let with = build_command(
2975            &s,
2976            &seat,
2977            &Invocation {
2978                attachments: &atts,
2979                writable: &[],
2980                ..inv(Path::new("."), Path::new("/art"), true)
2981            },
2982            Path::new("/art/p.md"),
2983        )
2984        .unwrap();
2985        assert!(
2986            with.argv.windows(2).any(|w| w == ["--add-dir", "/art"]),
2987            "an attachment outside cwd must widen the sandbox even off File delivery: {with:?}"
2988        );
2989    }
2990
2991    /// A chat derived from another one (`chat::derived_background`) can pass
2992    /// `turn` attachment paths that live under the *source* conversation's
2993    /// own artifacts dir, not this invocation's `artifacts`. A single
2994    /// `--add-dir` for `inv.artifacts` alone would leave those unreadable, so
2995    /// each attachment directory outside it must get its own grant.
2996    #[test]
2997    fn an_inherited_attachment_outside_this_conversations_artifacts_dir_gets_its_own_add_dir() {
2998        let seat = SeatState::new("plan", "a", 7);
2999        let atts = [
3000            PathBuf::from("/art/attachments/own.png"),
3001            PathBuf::from("/other-chat/attachments/inherited.png"),
3002        ];
3003
3004        let p = build_command(
3005            &spec(AgentKind::Antigravity, None),
3006            &seat,
3007            &Invocation {
3008                attachments: &atts,
3009                writable: &[],
3010                ..inv(Path::new("."), Path::new("/art"), true)
3011            },
3012            Path::new("/art/p.md"),
3013        )
3014        .unwrap();
3015
3016        assert!(
3017            p.argv.windows(2).any(|w| w == ["--add-dir", "/art"]),
3018            "this conversation's own artifacts dir must still be granted: {p:?}"
3019        );
3020        assert!(
3021            p.argv
3022                .windows(2)
3023                .any(|w| w == ["--add-dir", "/other-chat/attachments"]),
3024            "the inherited attachment's own directory must be granted too: {p:?}"
3025        );
3026    }
3027
3028    #[test]
3029    fn command_agents_get_placeholders_substituted() {
3030        let seat = SeatState::new("impl-A", "a", 7);
3031        let p = plan_for(AgentKind::Command, &seat, true);
3032        assert_eq!(p.argv[0], "echo");
3033        assert_eq!(p.argv[1], "impl-A");
3034        assert_eq!(p.stdin.as_deref(), Some("do the thing"));
3035    }
3036
3037    const EXPIRED_AUTH: &str = r#"{"is_error":true,"terminal_reason":"api_error","result":"Failed to authenticate: OAuth session expired and could not be refreshed"}"#;
3038    const CODEX_LIMIT: &str = r#"{"type":"error","message":"You've hit your usage limit. Visit https://chatgpt.com/settings/usage to purchase more credits or try again at Oct 27th, 2026 6:18 PM."}
3039{"type":"turn.failed","error":{"message":"You've hit your usage limit."}}"#;
3040
3041    #[test]
3042    fn observed_machine_failures_are_detected_conservatively() {
3043        let auth = extract(AgentKind::Claude, EXPIRED_AUTH).quota.unwrap();
3044        assert_eq!(auth.cause, QuotaCause::Authentication);
3045        assert_eq!(auth.reset, None);
3046        let limit = extract(AgentKind::Codex, CODEX_LIMIT).quota.unwrap();
3047        assert_eq!(limit.cause, QuotaCause::UsageLimit);
3048        assert_eq!(limit.reset.as_deref(), Some("Oct 27th, 2026 6:18 PM"));
3049        // Duplicate events still yield one classification.
3050        assert!(
3051            extract(AgentKind::Codex, &format!("{CODEX_LIMIT}\n{CODEX_LIMIT}"))
3052                .quota
3053                .is_some()
3054        );
3055        let without_reset = CODEX_LIMIT.replace(" or try again at Oct 27th, 2026 6:18 PM", "");
3056        assert!(
3057            extract(AgentKind::Codex, &without_reset)
3058                .quota
3059                .unwrap()
3060                .reset
3061                .is_none()
3062        );
3063        for text in [
3064            EXPIRED_AUTH.replace("true", "false"),
3065            EXPIRED_AUTH.replace("api_error", "unknown"),
3066            EXPIRED_AUTH.replace(
3067                "OAuth session expired and could not be refreshed",
3068                "unknown error",
3069            ),
3070        ] {
3071            assert!(extract(AgentKind::Claude, &text).quota.is_none());
3072        }
3073        assert!(
3074            extract(AgentKind::Codex, CODEX_LIMIT.lines().next().unwrap())
3075                .quota
3076                .is_none()
3077        );
3078        assert!(
3079            extract(
3080                AgentKind::Codex,
3081                &CODEX_LIMIT.replace("You've hit your usage limit.", "Something failed.")
3082            )
3083            .quota
3084            .is_none()
3085        );
3086        let quoted = serde_json::json!({"type":"item.completed","item":{"type":"agent_message","text":CODEX_LIMIT}}).to_string();
3087        assert!(extract(AgentKind::Codex, &quoted).quota.is_none());
3088        assert!(extract(AgentKind::Codex, EXPIRED_AUTH).quota.is_none());
3089        assert!(
3090            extract(AgentKind::Antigravity, EXPIRED_AUTH)
3091                .quota
3092                .is_none()
3093        );
3094        let legacy: Quota = serde_json::from_str(r#"{"reset":null}"#).unwrap();
3095        assert_eq!(legacy.cause, QuotaCause::UsageLimit);
3096    }
3097
3098    #[test]
3099    fn claude_rate_limit_is_detected_and_reset_read_when_present() {
3100        // The exact shape observed in the wild (run 20260831-031005-ae94).
3101        let stdout = r#"{"is_error": true, "terminal_reason": "api_error",
3102                        "result": "You've hit your session limit · resets 4:50am (Asia/Tokyo)",
3103                        "session_id": "b8e928f1-754e-4bd3-86c5-0567763654e3"}"#;
3104        let out = extract(AgentKind::Claude, stdout);
3105        let quota = out.quota.as_ref().expect("rate limit must be detected");
3106        assert_eq!(
3107            quota.reset.as_deref(),
3108            Some("4:50am (Asia/Tokyo)"),
3109            "reset time read from the body"
3110        );
3111    }
3112
3113    #[test]
3114    fn claude_rate_limit_without_a_readable_reset_is_still_detected() {
3115        let out = extract(
3116            AgentKind::Claude,
3117            r#"{"is_error":true,"result":"session limit reached"}"#,
3118        );
3119        let quota = out.quota.expect("rate limit detected without a reset");
3120        assert!(quota.reset.is_none(), "unknown reset is kept as unknown");
3121    }
3122
3123    #[test]
3124    fn claude_structured_usage_limit_requires_the_error_and_exact_pair() {
3125        for kind in [AgentKind::Claude, AgentKind::Command] {
3126            for reply in [
3127                r#"{"is_error":true,"api_error_status":429,"api_error":"usage_limit_reached"}"#,
3128                r#"{"is_error":true,"api_error_status":"429","api_error":"usage_limit_reached"}"#,
3129            ] {
3130                assert!(extract(kind, reply).quota.is_some(), "{reply}");
3131            }
3132            for reply in [
3133                r#"{"is_error":false,"api_error_status":429,"api_error":"usage_limit_reached"}"#,
3134                r#"{"is_error":true,"api_error_status":500,"api_error":"usage_limit_reached"}"#,
3135                r#"{"is_error":true,"api_error_status":429,"api_error":"other_error"}"#,
3136                r#"{"is_error":false,"api_error_status":"429","api_error":"usage_limit_reached"}"#,
3137                r#"{"is_error":true,"api_error_status":"500","api_error":"usage_limit_reached"}"#,
3138                r#"{"is_error":true,"api_error_status":"429","api_error":"other_error"}"#,
3139                r#"{"is_error":true,"api_error":"usage_limit_reached"}"#,
3140            ] {
3141                assert!(extract(kind, reply).quota.is_none(), "{reply}");
3142            }
3143        }
3144    }
3145
3146    #[test]
3147    fn ordinary_failures_are_never_quota() {
3148        // A normal failed claude call (is_error with a different message).
3149        let claude_fail = extract(
3150            AgentKind::Claude,
3151            r#"{"is_error":true,"result":"account does not exist"}"#,
3152        );
3153        assert!(claude_fail.quota.is_none());
3154
3155        // A command agent that exits 1 with plain text.
3156        let cmd_fail = extract(AgentKind::Command, "boom");
3157        assert!(cmd_fail.quota.is_none());
3158
3159        // A successful call is not quota even if it mentions the phrase.
3160        let success = extract(
3161            AgentKind::Command,
3162            r#"{"is_error":false,"result":"session limit is fine"}"#,
3163        );
3164        assert!(success.quota.is_none());
3165    }
3166
3167    /// Minimal, anonymised shape of run 20260912-214939-b3bb's
3168    /// artifacts/impl-A.out: `command_execution` items reporting a paired
3169    /// test run as `1 passed, 1 failed` twice, while the final
3170    /// `agent_message` nevertheless claimed the target passed. The point of
3171    /// `CommandEvidence` is that this claim and the CLI's own structured
3172    /// record of what actually ran are now two separate things a caller can
3173    /// compare, rather than the prose being the only account available.
3174    #[test]
3175    fn codex_command_execution_events_are_captured_alongside_the_final_message() {
3176        let stream = concat!(
3177            r#"{"type":"thread.started","thread_id":"t1"}"#,
3178            "\n",
3179            r#"{"type":"item.completed","item":{"id":"item49","type":"command_execution","command":["bash","-lc","cargo test --test graph_cached_gate"],"exit_code":1,"aggregated_output":"test result: 1 passed; 1 failed"}}"#,
3180            "\n",
3181            r#"{"type":"item.completed","item":{"id":"item52","type":"command_execution","command":["bash","-lc","cargo test --test graph_cached_gate a_single_test"],"exit_code":0,"aggregated_output":"test result: 1 passed; 0 failed"}}"#,
3182            "\n",
3183            r#"{"type":"item.completed","item":{"id":"item99","type":"agent_message","text":"Both tests in the target pass."}}"#,
3184            "\n",
3185            r#"{"type":"turn.completed"}"#,
3186            "\n",
3187        );
3188        let out = extract(AgentKind::Codex, stream);
3189        assert_eq!(out.text, "Both tests in the target pass.");
3190        assert_eq!(out.commands.len(), 2, "{:?}", out.commands);
3191
3192        let paired = &out.commands[0];
3193        assert_eq!(paired.id, "item49");
3194        assert_eq!(paired.exit_code, Some(1));
3195        assert!(paired.description.contains("graph_cached_gate"));
3196        assert!(paired.result_summary.contains("1 failed"));
3197
3198        let solo = &out.commands[1];
3199        assert_eq!(solo.exit_code, Some(0));
3200
3201        // The structured evidence disagrees with the final prose - exactly
3202        // what a caller must be able to see instead of trusting the message
3203        // alone: the full target never passed in one command.
3204        assert!(
3205            out.commands
3206                .iter()
3207                .any(|c| c.exit_code != Some(0) && c.description.contains("graph_cached_gate")),
3208            "a failed run of the actual target must still be visible: {:?}",
3209            out.commands
3210        );
3211    }
3212
3213    #[test]
3214    fn command_agent_can_carry_the_claude_quota_shape() {
3215        let out = extract(
3216            AgentKind::Command,
3217            r#"{"is_error":true,"result":"You've hit your session limit · resets 1:00am (UTC)"}"#,
3218        );
3219        assert!(
3220            out.quota.is_some(),
3221            "a wrapper emitting the claude shape counts as quota"
3222        );
3223    }
3224
3225    #[test]
3226    fn claude_json_result_is_extracted() {
3227        let out = extract(
3228            AgentKind::Claude,
3229            r#"{"result":"all done","session_id":"abc","is_error":false}"#,
3230        );
3231        assert_eq!(out.text, "all done");
3232        assert_eq!(out.session.as_deref(), Some("abc"));
3233        assert_eq!(out.status.as_deref(), Some("success"));
3234    }
3235
3236    /// The shape behind fix-2 in run 20260912-114326-d3b8, minimal and
3237    /// anonymised: a Claude CLI turn that ended `subtype: success`,
3238    /// `is_error: false`, `terminal_reason: completed`, `stop_reason:
3239    /// end_turn` — every signal this crate reads as a clean CLI turn — while
3240    /// `result` is a progress update, not the report the fixer node needed,
3241    /// and no `FixReport` JSON is anywhere in it.
3242    ///
3243    /// `AgentOutput::usable()` (a CLI fact: exit 0, not timed out, non-empty
3244    /// text) must stay true here — that is the honest reading of what the
3245    /// CLI reported — while `verdict::extract_json` on the same text must
3246    /// fail. Conflating the two is exactly the bug this fixture reproduces:
3247    /// `run.json` recorded `fix.failed = "unparsable fix report: the reply
3248    /// contained no JSON object"` and moved straight to the next review round
3249    /// with no report ever recovered from that seat.
3250    #[test]
3251    fn a_clean_cli_turn_is_not_the_same_fact_as_the_nodes_own_work_being_done() {
3252        let stdout = r#"{"type":"result","subtype":"success","is_error":false,"terminal_reason":"completed","stop_reason":"end_turn","result":"I'll pause here until the `cargo make check` background run reports back.","session_id":"11111111-1111-1111-1111-111111111111"}"#;
3253        let out = extract(AgentKind::Claude, stdout);
3254        assert_eq!(out.status.as_deref(), Some("success"));
3255        assert!(out.quota.is_none());
3256        assert!(!out.text.trim().is_empty());
3257
3258        let agent_out = AgentOutput {
3259            text: out.text.clone(),
3260            exit_code: Some(0),
3261            timed_out: false,
3262            duration_ms: 500,
3263            artifacts: Vec::new(),
3264            quota: out.quota,
3265            dropped: out.dropped,
3266            commands: out.commands,
3267            context_tokens: None,
3268        };
3269        assert!(
3270            agent_out.usable(),
3271            "the CLI turn itself ended cleanly and must read as usable"
3272        );
3273        assert!(
3274            crate::verdict::extract_json::<crate::verdict::FixReport>(&agent_out.text).is_err(),
3275            "a clean CLI turn is not proof the node's own report ever arrived"
3276        );
3277    }
3278
3279    #[test]
3280    fn opencode_event_stream_is_concatenated() {
3281        let stream = concat!(
3282            r#"{"type":"step_start","sessionID":"ses_1","part":{"type":"step-start"}}"#,
3283            "\n",
3284            r#"{"type":"text","sessionID":"ses_1","part":{"type":"text","text":"first"}}"#,
3285            "\n",
3286            "garbage line\n",
3287            r#"{"type":"text","sessionID":"ses_1","part":{"type":"text","text":"second"}}"#,
3288            "\n"
3289        );
3290        let out = extract(AgentKind::Opencode, stream);
3291        assert_eq!(out.text, "first\nsecond");
3292        assert_eq!(out.session.as_deref(), Some("ses_1"));
3293    }
3294
3295    #[test]
3296    fn agy_json_survives_a_leading_warning_line() {
3297        let stdout = concat!(
3298            "warning: --mode plan has no effect while slash commands are disabled.\n",
3299            r#"{"conversation_id":"eaf2d00a","status":"SUCCESS","response":"persimmon\n"}"#,
3300            "\n"
3301        );
3302        let out = extract(AgentKind::Antigravity, stdout);
3303        assert_eq!(out.text, "persimmon");
3304        assert_eq!(out.session.as_deref(), Some("eaf2d00a"));
3305        assert_eq!(out.status.as_deref(), Some("SUCCESS"));
3306    }
3307
3308    /// Run 26c7's candidate B, verbatim from `artifacts/impl-B.out`.
3309    ///
3310    /// The seat read as an empty candidate. It was seven minutes of work and
3311    /// 14,267 output tokens, billed, that the CLI then declined to hand over.
3312    /// Five such candidates are why `agy` reads as 0 wins in 4 entries, and
3313    /// that number has twice been used to argue the seat out of the roster.
3314    const AGY_DROPPED: &str = concat!(
3315        r#"{"conversation_id":"36743d06-c0b3-4b79-9fa2-23869289d7b6","status":"ERROR","#,
3316        r#""response":"","error":"the connection to the agent was interrupted before "#,
3317        r#"the response finished: subscriber fell behind updates, stalled for 5s","#,
3318        r#""duration_seconds":431.1941803,"num_turns":1,"usage":{"input_tokens":260113,"#,
3319        r#""output_tokens":14267,"thinking_tokens":9695,"cache_read_tokens":2200925,"#,
3320        r#""total_tokens":274380}}"#
3321    );
3322
3323    /// Run 1798's review seat, from `review-1-1.out` / `.err`.
3324    const AGY_QUOTA_OUT: &str = concat!(
3325        r#"{"conversation_id":"323c3b5b-0000","status":"ERROR","response":"","#,
3326        r#""error":"Individual quota reached. Please upgrade your subscription to "#,
3327        r#"increase your limits. Resets in 1h2m49s.","duration_seconds":265.9,"#,
3328        r#""num_turns":2,"usage":{"input_tokens":1000,"output_tokens":50}}"#
3329    );
3330    const AGY_QUOTA_ERR: &str = concat!(
3331        "error: Individual quota reached. Resets in 1h2m49s.\n",
3332        r#"AGY_ERROR: {"short_error":"RESOURCE_EXHAUSTED (code 429): Individual quota "#,
3333        r#"reached.","status":"RESOURCE_EXHAUSTED","error_code":429,"code_kind":"http","#,
3334        r#""retryable":true}"#,
3335        "\n"
3336    );
3337
3338    #[test]
3339    fn agy_out_of_quota_is_a_quota_with_the_reset_hint() {
3340        let both = agy_quota(AGY_QUOTA_OUT, AGY_QUOTA_ERR).expect("both streams");
3341        assert_eq!(both.reset.as_deref(), Some("in 1h2m49s"));
3342        let stdout_only = agy_quota(AGY_QUOTA_OUT, "").expect("stdout alone");
3343        assert_eq!(stdout_only.reset.as_deref(), Some("in 1h2m49s"));
3344        // stderr alone: the hint is not in `short_error`, so none is carried.
3345        let stderr_only = agy_quota("not json", AGY_QUOTA_ERR).expect("stderr alone");
3346        assert!(stderr_only.reset.is_none());
3347    }
3348
3349    #[test]
3350    fn ordinary_agy_failures_are_not_a_quota() {
3351        assert!(agy_quota(AGY_DROPPED, "").is_none());
3352        assert!(agy_quota(r#"{"status":"ERROR","error":"boom"}"#, "").is_none());
3353        assert!(
3354            agy_quota(
3355                "",
3356                r#"AGY_ERROR: {"status":"RESOURCE_EXHAUSTED","error_code":500}"#
3357            )
3358            .is_none()
3359        );
3360        assert!(
3361            agy_quota(
3362                "",
3363                r#"AGY_ERROR: {"status":"UNAVAILABLE","error_code":429}"#
3364            )
3365            .is_none()
3366        );
3367        assert!(agy_quota(r#"{"status":"SUCCESS","response":"ok"}"#, "").is_none());
3368    }
3369
3370    #[test]
3371    fn a_cli_that_hangs_up_on_billed_work_is_not_an_agent_that_produced_nothing() {
3372        let out = extract(AgentKind::Antigravity, AGY_DROPPED);
3373        let dropped = out.dropped.expect("recognised as undelivered work");
3374        assert_eq!(dropped.output_tokens, 14267);
3375        assert!(
3376            dropped.why.contains("subscriber fell behind"),
3377            "the CLI's own words are kept for the record: {}",
3378            dropped.why
3379        );
3380        // And the conversation is still there to resume, which is the whole
3381        // reason this is worth re-asking where a quota is not.
3382        assert_eq!(
3383            out.session.as_deref(),
3384            Some("36743d06-c0b3-4b79-9fa2-23869289d7b6")
3385        );
3386        assert!(out.quota.is_none(), "a dropped stream is not a rate limit");
3387    }
3388
3389    #[test]
3390    fn an_error_with_nothing_produced_stays_an_ordinary_failure() {
3391        // No usage at all: the agent never got going, so there is nothing in
3392        // the conversation to resume and nothing was billed. Treating this as
3393        // undelivered work would buy a second call for no reason.
3394        let bare = r#"{"conversation_id":"c1","status":"ERROR","response":"","error":"boom"}"#;
3395        assert!(extract(AgentKind::Antigravity, bare).dropped.is_none());
3396
3397        // Produced tokens, but it did answer - so there is something to read
3398        // and the status is not our business.
3399        let answered = concat!(
3400            r#"{"conversation_id":"c2","status":"ERROR","response":"here it is","#,
3401            r#""usage":{"output_tokens":10}}"#
3402        );
3403        assert!(extract(AgentKind::Antigravity, answered).dropped.is_none());
3404
3405        // A success is a success.
3406        let ok = concat!(
3407            r#"{"conversation_id":"c3","status":"SUCCESS","response":"done","#,
3408            r#""usage":{"output_tokens":10}}"#
3409        );
3410        assert!(extract(AgentKind::Antigravity, ok).dropped.is_none());
3411    }
3412
3413    #[test]
3414    fn an_undelivered_output_is_not_usable_but_is_worth_asking_again() {
3415        let out = AgentOutput {
3416            text: String::new(),
3417            exit_code: Some(1),
3418            timed_out: false,
3419            duration_ms: 431_194,
3420            artifacts: Vec::new(),
3421            quota: None,
3422            dropped: Some(Dropped {
3423                why: "subscriber fell behind updates".to_owned(),
3424                output_tokens: 14267,
3425            }),
3426            commands: Vec::new(),
3427            context_tokens: None,
3428        };
3429        assert!(!out.usable());
3430        assert!(out.work_undelivered());
3431        // The distinction the retry policy rests on: a quota fails the same way
3432        // until it resets, an abandoned conversation can be picked up.
3433        assert!(!out.quota_exhausted());
3434    }
3435
3436    #[test]
3437    fn non_json_stdout_falls_back_to_raw_text() {
3438        let out = extract(AgentKind::Antigravity, "plain answer\n");
3439        assert_eq!(out.text, "plain answer");
3440        assert!(out.session.is_none());
3441    }
3442
3443    #[tokio::test]
3444    async fn command_agent_round_trip_writes_artifacts() {
3445        let dir = tempfile::tempdir().unwrap();
3446        let art = dir.path().join("artifacts");
3447        let mut seat = SeatState::new("impl-A", "a", 7);
3448        let s = command_helper("reply");
3449        let out = invoke(
3450            &s,
3451            &mut seat,
3452            &Invocation {
3453                coordination: None,
3454                fetched_base: None,
3455                cwd: dir.path(),
3456                prompt: "unused",
3457                timeout: Duration::from_secs(30),
3458                allow_write: true,
3459                sessions: true,
3460                artifacts: &art,
3461                stem: "impl-A",
3462                run: "test-run",
3463                node: "test",
3464                cache_dir: None,
3465                attachments: &[],
3466                writable: &[],
3467            },
3468        )
3469        .await
3470        .unwrap();
3471        assert!(out.usable(), "{out:?}");
3472        assert!(out.text.contains("hello impl-A"), "{}", out.text);
3473        assert_eq!(seat.turns, 1);
3474        assert!(art.join("impl-A.prompt.md").is_file());
3475        assert!(art.join("impl-A.out").is_file());
3476    }
3477
3478    #[tokio::test]
3479    async fn the_invocation_cache_dir_reaches_the_seat_as_cargo_target_dir() {
3480        crate::run::pin_test_home();
3481        // The whole point of threading the cache path through `Invocation`:
3482        // the compile the agent pays for lands in the directory `verify` reads
3483        // back out of its rendered commands, so one cache has one prune.
3484        let dir = tempfile::tempdir().unwrap();
3485        let cache = dir.path().join("magi-cache");
3486        let mut seat = SeatState::new("impl-A", "a", 7);
3487        let s = command_helper("cache");
3488        let out = invoke(
3489            &s,
3490            &mut seat,
3491            &Invocation {
3492                coordination: None,
3493                fetched_base: None,
3494                cwd: dir.path(),
3495                prompt: "unused",
3496                timeout: Duration::from_secs(30),
3497                allow_write: true,
3498                sessions: true,
3499                artifacts: &dir.path().join("artifacts"),
3500                stem: "cache",
3501                run: "test-run",
3502                node: "test",
3503                cache_dir: Some(&cache),
3504                attachments: &[],
3505                writable: &[],
3506            },
3507        )
3508        .await
3509        .unwrap();
3510        assert!(out.usable(), "{out:?}");
3511        assert!(
3512            out.text.contains(cache.to_string_lossy().as_ref()),
3513            "the seat must see CARGO_TARGET_DIR = the shared cache"
3514        );
3515    }
3516
3517    #[tokio::test]
3518    async fn cache_dir_none_strips_a_cargo_target_dir_inherited_from_this_process() {
3519        // `Command` inherits the parent's environment by default, so
3520        // `cache_dir: None` alone is not the same as a seat never seeing
3521        // `CARGO_TARGET_DIR` - it also has to be true when *this* process
3522        // (standing in for the real magi process, which normally does have
3523        // one set, from its own `[verify]` config) already has the variable
3524        // set. Simulating that is the only way to exercise the inheritance
3525        // path at all.
3526        let previous = std::env::var("CARGO_TARGET_DIR").ok();
3527        // SAFETY: this crate's tests run single-threaded
3528        // (`RUST_TEST_THREADS=1`); see
3529        // `updater::tests::env_kill_switch_semantics` for the same
3530        // reasoning applied to another process-global env var.
3531        unsafe {
3532            std::env::set_var("CARGO_TARGET_DIR", "/should/never/reach/a/read-only/seat");
3533        }
3534        let dir = tempfile::tempdir().unwrap();
3535        let mut seat = SeatState::new("review-1", "a", 7);
3536        let s = command_helper("no-cache");
3537        let result = invoke(
3538            &s,
3539            &mut seat,
3540            &Invocation {
3541                coordination: None,
3542                fetched_base: None,
3543                cwd: dir.path(),
3544                prompt: "unused",
3545                timeout: Duration::from_secs(30),
3546                allow_write: false,
3547                sessions: true,
3548                artifacts: &dir.path().join("artifacts"),
3549                stem: "no-cache",
3550                run: "test-run",
3551                node: "test",
3552                cache_dir: None,
3553                attachments: &[],
3554                writable: &[],
3555            },
3556        )
3557        .await;
3558        // Restored before any assertion that could panic, so a failure here
3559        // never leaks a bogus `CARGO_TARGET_DIR` into whichever test runs
3560        // next in this same process.
3561        // SAFETY: see above.
3562        unsafe {
3563            match &previous {
3564                Some(v) => std::env::set_var("CARGO_TARGET_DIR", v),
3565                None => std::env::remove_var("CARGO_TARGET_DIR"),
3566            }
3567        }
3568        let out = result.unwrap();
3569        assert!(out.usable(), "{out:?}");
3570        assert!(
3571            out.text.contains("ABSENT"),
3572            "a read-only seat must never inherit the process's own CARGO_TARGET_DIR: {}",
3573            out.text
3574        );
3575    }
3576
3577    #[tokio::test]
3578    async fn a_prompt_larger_than_the_pipe_buffer_does_not_deadlock() {
3579        let dir = tempfile::tempdir().unwrap();
3580        let mut seat = SeatState::new("impl-A", "a", 7);
3581        // The helper never reads stdin, so an inline write_all would block once
3582        // the OS pipe buffer filled — long before the process could be waited on.
3583        let s = command_helper("ignore-stdin");
3584        let big = "x".repeat(1_000_000);
3585        let out = invoke(
3586            &s,
3587            &mut seat,
3588            &Invocation {
3589                coordination: None,
3590                fetched_base: None,
3591                cwd: dir.path(),
3592                prompt: &big,
3593                timeout: Duration::from_secs(60),
3594                allow_write: true,
3595                sessions: true,
3596                artifacts: &dir.path().join("artifacts"),
3597                stem: "big",
3598                run: "test-run",
3599                node: "test",
3600                cache_dir: None,
3601                attachments: &[],
3602                writable: &[],
3603            },
3604        )
3605        .await
3606        .unwrap();
3607        assert!(out.usable(), "{out:?}");
3608        assert!(out.text.contains("done"), "{}", out.text);
3609    }
3610
3611    #[tokio::test]
3612    async fn agent_turn_cap_limits_a_direct_invocation() {
3613        let dir = tempfile::tempdir().unwrap();
3614        let artifacts = dir.path().join("artifacts");
3615        let mut seat = SeatState::new("impl-A", "helper", 7);
3616        let mut s = command_helper("sleep");
3617        s.max_turn_secs = Some(2);
3618        let out = invoke(&s, &mut seat, &inv(dir.path(), &artifacts, false))
3619            .await
3620            .unwrap();
3621        assert!(out.timed_out, "{out:?}");
3622        // The caller supplies 900 seconds and the helper sleeps for 30:
3623        // neither may override the short per-agent cap.
3624        assert!(out.duration_ms < 20_000, "{out:?}");
3625    }
3626
3627    #[tokio::test]
3628    async fn timeout_is_reported_not_hung() {
3629        let dir = tempfile::tempdir().unwrap();
3630        let mut seat = SeatState::new("impl-A", "a", 7);
3631        let s = command_helper("sleep");
3632        let out = invoke(
3633            &s,
3634            &mut seat,
3635            &Invocation {
3636                coordination: None,
3637                fetched_base: None,
3638                cwd: dir.path(),
3639                prompt: "unused",
3640                timeout: Duration::from_millis(300),
3641                allow_write: true,
3642                sessions: true,
3643                artifacts: &dir.path().join("artifacts"),
3644                stem: "slow",
3645                run: "test-run",
3646                node: "test",
3647                cache_dir: None,
3648                attachments: &[],
3649                writable: &[],
3650            },
3651        )
3652        .await
3653        .unwrap();
3654        assert!(out.timed_out);
3655        assert!(!out.usable());
3656    }
3657
3658    #[tokio::test]
3659    async fn a_timeout_keeps_what_the_agent_had_already_printed() {
3660        // The old implementation cancelled `wait_with_output`, which dropped
3661        // the buffers it owned, so `<stem>.out` was written empty on every
3662        // timeout. "It printed nothing" and "we discarded what it printed"
3663        // looked identical on disk — and one real hour-long stall was
3664        // diagnosed wrongly twice because of it.
3665        let dir = tempfile::tempdir().unwrap();
3666        let artifacts = dir.path().join("artifacts");
3667        let mut seat = SeatState::new("impl-A", "a", 7);
3668        let s = command_helper("chatty-sleep");
3669        let out = invoke(
3670            &s,
3671            &mut seat,
3672            &Invocation {
3673                coordination: None,
3674                fetched_base: None,
3675                cwd: dir.path(),
3676                prompt: "unused",
3677                // Wide enough to cover process-spawn latency inside a loaded
3678                // parallel test run, not merely the helper's first write. At
3679                // two seconds this passed alone and failed in the full suite,
3680                // which is a dice roll rather than a test.
3681                timeout: Duration::from_secs(10),
3682                allow_write: true,
3683                sessions: true,
3684                artifacts: &artifacts,
3685                stem: "chatty",
3686                run: "test-run",
3687                node: "test",
3688                cache_dir: None,
3689                attachments: &[],
3690                writable: &[],
3691            },
3692        )
3693        .await
3694        .unwrap();
3695
3696        assert!(out.timed_out, "{out:?}");
3697        assert!(!out.usable(), "a cut-off answer is still not an answer");
3698        let recorded = std::fs::read_to_string(artifacts.join("chatty.out")).unwrap();
3699        assert!(
3700            recorded.contains("i-said-something"),
3701            "the artifact must keep what arrived before the kill, got {recorded:?}"
3702        );
3703        assert!(
3704            out.text.contains("i-said-something"),
3705            "and the graph must be able to see it too, got {:?}",
3706            out.text
3707        );
3708    }
3709
3710    #[test]
3711    fn missing_programs_reports_command_binaries() {
3712        let mut s = spec(AgentKind::Command, None);
3713        s.command = vec!["definitely-not-a-real-binary-xyz".to_owned()];
3714        assert_eq!(
3715            missing_programs(&[s]),
3716            ["definitely-not-a-real-binary-xyz".to_owned()]
3717        );
3718    }
3719
3720    fn pick_spec(id: &str, kind: AgentKind) -> AgentSpec {
3721        AgentSpec {
3722            id: id.to_owned(),
3723            kind,
3724            model: None,
3725            command: Vec::new(),
3726            extra_args: Vec::new(),
3727            env: BTreeMap::new(),
3728            prompt_delivery: None,
3729            max_turn_secs: None,
3730        }
3731    }
3732
3733    /// Availability stub: an agent is runnable unless its id was listed as
3734    /// missing. Keeps the selection tests off `PATH` entirely.
3735    fn without<'a>(missing: &'a [&'a str]) -> impl Fn(&AgentSpec) -> bool + 'a {
3736        move |a: &AgentSpec| !missing.contains(&a.id.as_str())
3737    }
3738
3739    #[test]
3740    fn pick_prefers_the_claude_seat_even_when_it_is_not_first_in_the_roster() {
3741        let agents = [
3742            pick_spec("oc", AgentKind::Opencode),
3743            pick_spec("opus", AgentKind::Claude),
3744            pick_spec("agy", AgentKind::Antigravity),
3745        ];
3746        let got = pick(&agents, None, &without(&[])).expect("a pick");
3747        assert_eq!(got.id, "opus");
3748    }
3749
3750    #[test]
3751    fn pick_falls_back_to_the_first_installed_agent_in_roster_order() {
3752        let agents = [
3753            pick_spec("opus", AgentKind::Claude),
3754            pick_spec("oc", AgentKind::Opencode),
3755            pick_spec("agy", AgentKind::Antigravity),
3756        ];
3757        let got = pick(&agents, None, &without(&["opus", "oc"])).expect("a pick");
3758        assert_eq!(got.id, "agy");
3759    }
3760
3761    #[test]
3762    fn pick_on_an_empty_roster_says_what_to_install() {
3763        let msg = pick(&[], None, &without(&[]))
3764            .expect_err("nobody to ask")
3765            .to_string();
3766        assert!(msg.contains("roster is empty"), "{msg}");
3767        assert!(msg.contains("claude"), "{msg}");
3768        assert!(msg.contains("magi.toml"), "{msg}");
3769    }
3770
3771    #[test]
3772    fn pick_on_a_roster_with_nothing_installed_names_the_programs_that_are_missing() {
3773        let agents = [
3774            pick_spec("opus", AgentKind::Claude),
3775            pick_spec("oc", AgentKind::Opencode),
3776        ];
3777        let err = pick(&agents, None, &without(&["opus", "oc"])).expect_err("nothing runnable");
3778        let msg = format!("{err:#}");
3779        assert!(msg.contains("claude"), "{msg}");
3780        assert!(msg.contains("opencode"), "{msg}");
3781    }
3782
3783    #[test]
3784    fn an_explicitly_named_agent_wins_over_the_claude_preference() {
3785        let agents = [
3786            pick_spec("opus", AgentKind::Claude),
3787            pick_spec("oc", AgentKind::Opencode),
3788        ];
3789        let got = pick(&agents, Some("oc"), &without(&[])).expect("a pick");
3790        assert_eq!(got.id, "oc");
3791    }
3792
3793    #[test]
3794    fn an_unknown_agent_id_lists_the_ids_that_do_exist() {
3795        let agents = [
3796            pick_spec("opus", AgentKind::Claude),
3797            pick_spec("oc", AgentKind::Opencode),
3798        ];
3799        let msg = pick(&agents, Some("gemini"), &without(&[]))
3800            .expect_err("no such agent")
3801            .to_string();
3802        assert!(msg.contains("gemini"), "{msg}");
3803        assert!(msg.contains("opus, oc"), "{msg}");
3804    }
3805
3806    #[test]
3807    fn an_explicitly_named_agent_that_is_not_installed_is_an_error_not_a_fallback() {
3808        let agents = [
3809            pick_spec("opus", AgentKind::Claude),
3810            pick_spec("oc", AgentKind::Opencode),
3811        ];
3812        let msg = pick(&agents, Some("oc"), &without(&["oc"]))
3813            .expect_err("must not silently substitute another model")
3814            .to_string();
3815        assert!(msg.contains("opencode"), "{msg}");
3816        assert!(msg.contains("--agent"), "{msg}");
3817    }
3818
3819    fn named(id: &str) -> AgentSpec {
3820        AgentSpec {
3821            id: id.to_owned(),
3822            ..spec(AgentKind::Command, None)
3823        }
3824    }
3825
3826    fn output(text: &str, exit: i32, quota: bool) -> AgentOutput {
3827        AgentOutput {
3828            text: text.to_owned(),
3829            exit_code: Some(exit),
3830            timed_out: false,
3831            duration_ms: 0,
3832            artifacts: Vec::new(),
3833            quota: quota.then_some(Quota {
3834                reset: None,
3835                cause: QuotaCause::UsageLimit,
3836                agent: String::new(),
3837            }),
3838            dropped: None,
3839            commands: Vec::new(),
3840            context_tokens: None,
3841        }
3842    }
3843
3844    #[test]
3845    fn a_chain_keeps_the_written_order_and_a_string_is_a_chain_of_one() {
3846        let agents = [named("a"), named("b"), named("c")];
3847        let all = |_: &AgentSpec| true;
3848        let chain = AgentChoice::Chain(vec!["c".into(), "a".into()]);
3849        let got = pick_chain(&agents, Some(&chain), &all, "synthesizer").unwrap();
3850        assert_eq!(
3851            got.iter().map(|s| s.id.as_str()).collect::<Vec<_>>(),
3852            ["c", "a"]
3853        );
3854
3855        let one = AgentChoice::from("b");
3856        let got = pick_chain(&agents, Some(&one), &all, "synthesizer").unwrap();
3857        assert_eq!(got.len(), 1);
3858        assert_eq!(got[0].id, "b");
3859
3860        let got = pick_chain(&agents, None, &all, "synthesizer").unwrap();
3861        assert_eq!(got.len(), 1, "unset keeps pick's default");
3862        assert_eq!(got[0].id, "a");
3863        let empty = AgentChoice::Chain(Vec::new());
3864        assert_eq!(
3865            pick_chain(&agents, Some(&empty), &all, "x").unwrap()[0].id,
3866            "a"
3867        );
3868    }
3869
3870    #[test]
3871    fn a_chain_skips_unknown_and_uninstalled_ids_and_tries_each_once() {
3872        let agents = [named("a"), named("b")];
3873        let not_a = |s: &AgentSpec| s.id != "a";
3874        let chain = AgentChoice::Chain(
3875            ["a", "ghost", "b", "b"]
3876                .iter()
3877                .map(|s| (*s).to_owned())
3878                .collect(),
3879        );
3880        let got = pick_chain(&agents, Some(&chain), &not_a, "chatter").unwrap();
3881        assert_eq!(got.iter().map(|s| s.id.as_str()).collect::<Vec<_>>(), ["b"]);
3882
3883        let dup = AgentChoice::Chain(vec!["b".into(), "a".into(), "b".into()]);
3884        let got = pick_chain(&agents, Some(&dup), &|_| true, "chatter").unwrap();
3885        assert_eq!(
3886            got.iter().map(|s| s.id.as_str()).collect::<Vec<_>>(),
3887            ["b", "a"]
3888        );
3889    }
3890
3891    #[test]
3892    fn a_chain_with_nothing_runnable_names_the_role() {
3893        let agents = [named("a")];
3894        let chain = AgentChoice::Chain(vec!["a".into(), "ghost".into()]);
3895        let err = pick_chain(&agents, Some(&chain), &|_| false, "conductor")
3896            .unwrap_err()
3897            .to_string();
3898        assert!(err.contains("conductor"), "{err}");
3899    }
3900
3901    #[test]
3902    fn a_chain_advances_on_error_quota_or_an_unusable_answer_only() {
3903        assert!(chain_advances(&Err(anyhow::anyhow!("spawn failed"))));
3904        assert!(chain_advances(&Ok(output("limit", 0, true))));
3905        assert!(chain_advances(&Ok(output("", 0, false))));
3906        assert!(chain_advances(&Ok(output("x", 1, false))));
3907        assert!(!chain_advances(&Ok(output("answer", 0, false))));
3908    }
3909
3910    #[test]
3911    fn claude_context_tokens_are_unknown_because_usage_is_aggregated() {
3912        for out in [
3913            r#"{"result":"ok","num_turns":1,"usage":{"input_tokens":10,"cache_read_input_tokens":3000}}"#,
3914            r#"{"result":"ok","num_turns":3,"usage":{"input_tokens":10}}"#,
3915            r#"{"result":"ok"}"#,
3916            "not json",
3917        ] {
3918            assert_eq!(context_tokens(AgentKind::Claude, out), None, "{out}");
3919        }
3920    }
3921
3922    #[test]
3923    fn opencode_context_tokens_take_the_last_step_finish() {
3924        let out = concat!(
3925            r#"{"type":"step_finish","sessionID":"s","part":{"type":"step-finish","tokens":{"input":100,"output":5,"cache":{"read":1000,"write":50}}}}"#,
3926            "\n",
3927            r#"{"type":"text","part":{"type":"text","text":"hi"}}"#,
3928            "\n",
3929            r#"{"type":"step_finish","sessionID":"s","part":{"type":"step-finish","tokens":{"input":120,"output":9,"cache":{"read":1500}}}}"#,
3930            "\n"
3931        );
3932        assert_eq!(context_tokens(AgentKind::Opencode, out), Some(1620));
3933        let none = r#"{"type":"step_finish","part":{"type":"step-finish"}}"#;
3934        assert_eq!(context_tokens(AgentKind::Opencode, none), None);
3935        assert_eq!(context_tokens(AgentKind::Opencode, ""), None);
3936    }
3937
3938    #[test]
3939    fn agy_context_tokens_are_unknown_because_usage_is_aggregated() {
3940        let out = r#"{"conversation_id":"c","status":"OK","response":"x","usage":{"input_tokens":260113,"cache_read_tokens":2200925}}"#;
3941        assert_eq!(context_tokens(AgentKind::Antigravity, out), None);
3942    }
3943
3944    #[test]
3945    fn codex_context_tokens_are_unknown_because_usage_is_cumulative() {
3946        let out = concat!(
3947            r#"{"type":"turn.completed","usage":{"input_tokens":1000,"cached_input_tokens":900}}"#,
3948            "\n"
3949        );
3950        assert_eq!(context_tokens(AgentKind::Codex, out), None);
3951    }
3952
3953    #[test]
3954    fn omp_context_tokens_come_from_messages_without_an_agent_end() {
3955        let out = concat!(
3956            r#"{"type":"session","id":"s"}"#,
3957            "\n",
3958            r#"{"type":"message_end","message":{"role":"assistant","content":[],"usage":{"input":50,"cacheRead":400,"cacheWrite":10}}}"#,
3959            "\n",
3960            r#"{"type":"turn_end","message":{"role":"assistant","content":[],"usage":{"input":70,"cacheRead":500}}}"#,
3961            "\n"
3962        );
3963        assert_eq!(context_tokens(AgentKind::Omp, out), Some(570));
3964        let user_only = r#"{"type":"message_end","message":{"role":"user","usage":{"input":9}}}"#;
3965        assert_eq!(context_tokens(AgentKind::Omp, user_only), None);
3966        let no_usage = r#"{"type":"message_end","message":{"role":"assistant","content":[]}}"#;
3967        assert_eq!(context_tokens(AgentKind::Omp, no_usage), None);
3968    }
3969
3970    #[test]
3971    fn command_agents_report_no_context_tokens() {
3972        let out = r#"{"usage":{"input_tokens":5}}"#;
3973        assert_eq!(context_tokens(AgentKind::Command, out), None);
3974    }
3975}