Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

46.3 KB
Raw Blame
//! Every machine on the account and every harness on them, kept live from the machines' pushed
//! frames — the same facts the desktop's rail and ⌘O are drawn from.

use std::collections::HashMap;
use std::time::{Instant, SystemTime, UNIX_EPOCH};

use serde_json::Value;

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Reach {
    Unknown,
    Connecting,
    Ready,
    NeedsLink,
    Offline,
    Error(String),
}

#[derive(Clone, Debug)]
pub struct Machine {
    pub id: String,
    pub name: String,
    pub local: bool,
    /// A shared machine is view-only; watching another client on an owned machine is not.
    pub shared: bool,
    /// The control plane's word: running, offline, …
    pub status: String,
    pub reach: Reach,
}

impl Machine {
    pub fn online(&self) -> bool {
        self.local || matches!(self.status.to_ascii_lowercase().as_str(), "running" | "online" | "connected" | "ready")
    }
    pub fn usable(&self) -> bool { self.reach == Reach::Ready }
}

#[derive(Clone, Debug)]
pub struct Question {
    pub request_id: String,
    pub answer_key: String,
    pub prompt: String,
    pub options: Vec<String>,
    /// Several of its options may be chosen (the answer is them joined with ", ").
    pub multi: bool,
    pub since: Instant,
}

#[derive(Clone, Debug)]
pub struct Agent {
    pub machine_id: String,
    pub id: String,
    pub session_id: String,
    pub name: String,
    pub engine: String,
    pub status: String,
    pub launch: String,
    pub cwd: String,
    pub project: String,
    pub branch: String,
    pub created_at: u64,
    /// Keep the daemon's exact lifecycle identity. Millisecond sorting timestamps are not
    /// sufficient to authorize a stop against a replacement session.
    pub created_at_wire: String,
    pub close_supported: bool,
    pub terminal_available: bool,
    /// Package identity, separate from the display name in `dsh`.
    pub dsh_id: String,
    pub permission_mode: String,
    /// When its conversation last moved (the daemon's `updatedAt`: dated work in its transcript,
    /// else its engine's last word, else its creation) — what the desktop and phone sort by.
    pub updated_at: u64,
    /// When this client first had it (a list's row, or one it just made).
    pub known_at: Instant,
    pub active_at: u64,
    pub working: bool,
    pub activity: crate::activity::Activity,
    pub last_beat: Option<Instant>,
    pub question: Option<Question>,
    pub unread: bool,
    pub dsh: String,
    pub viewer_url: String,
    pub viewer_name: String,
    pub viewer_error: String,
    /// The runtime profile it runs (`runtime-v1:…:claude:opus@high`) — what ⌥I switches.
    pub model: String,
    pub project_root: String,
    /// What it is doing now — its current tool, as a line (`Running npm test`), or what it is
    /// thinking about — from the live events; none between turns.
    pub doing: Option<String>,
    /// What it has written since its last tool call this turn: its final message, once the turn
    /// ends (the start of it is enough).
    pub said: String,
    /// What its last finished turn came to: the first line of its final message.
    pub did: Option<String>,
    /// When its state began (ms since the epoch): the turn it is on, or the turn it finished.
    pub since: u64,
    /// Its tokens so far (the daemon's tokenUsage), and the lines it changed and the pull requests
    /// it made (outputStats).
    pub tokens: u64,
    pub added: u64,
    pub removed: u64,
    pub prs_made: u64,
    /// Why its start failed, in the daemon's words (launch.detail, else its error code).
    pub launch_error: String,
    /// What it was last asked: the first line of the turn's message.
    pub asked: Option<String>,
    /// The pull request for its branch (git_pull_request), and when that was last asked.
    pub pr: Option<Pr>,
    pub pr_checked: Option<Instant>,
    /// Its last recap was asked of the daemon (agent_recent), once.
    pub recap_asked: bool,
    /// Its to-do list as it last wrote it (TodoWrite): each item's words and its state (pending,
    /// in_progress, completed).
    pub todos: Vec<(String, String)>,
    /// The sub-agents it has running (a Task's tool call, until its end): id and what each does.
    pub subagents: Vec<(String, String)>,
    /// Its last turn ended in an error (the daemon's `error`: an API error, a message not
    /// delivered) — failed, until you look at it or its next turn starts.
    pub errored: bool,
    /// Its last turn's final message, whole (to read it without opening the harness).
    pub last_text: String,
    /// When its transcript last changed, as the daemon last read it (tokenUsage.updatedAt, ms):
    /// what it last did, while no window was watching too.
    pub usage_at: u64,
    // ── models: the model its engine is pointed at (the frame's `grid`) ──
    /// A grid's or a saved API's model (`grid.model`; empty on its own login), that endpoint
    /// (`grid.baseUrl`, which tells one API from another), whether the computers serving it rest
    /// (`grid.state`: asleep, waking), and why it will not answer now (`grid.note`: its reason —
    /// offline, not_served — the model, and the computer).
    pub grid_model: String,
    pub grid_base_url: String,
    pub grid_state: String,
    pub grid_note: Option<(String, String, String)>,
    /// The tmux pane it runs in on its machine (`tmuxPane`), kept once the daemon no longer says it: a
    /// harness whose engine exited is retired with its conversation, and the shell left in that pane
    /// goes on under a new id (`releaseEngine`) — this is how a pane still on the old one finds it.
    pub tmux_pane: String,
}

/// `grid.note`, read as the desktop reads it: a reason it does not know, or one missing the names
/// its sentence needs, is no note.
fn grid_note(note: &Value) -> Option<(String, String, String)> {
    let model = s(note, "model");
    let machine = s(note, "machine");
    match s(note, "reason").as_str() {
        _ if model.is_empty() => None,
        "not_served" => Some(("not_served".into(), model, machine)),
        "offline" if !machine.is_empty() => Some(("offline".into(), model, machine)),
        _ => None,
    }
}

/// A pull request for an agent's branch: its number, state (Open, Draft, Merged, Closed), link.
#[derive(Clone, Debug, PartialEq)]
pub struct Pr { pub number: u64, pub state: String, pub url: String }

impl Pr {
    /// As a list or a title says it: `#123`, `#123 draft`, `#123 merged`, `#123 closed`.
    pub fn label(&self) -> String {
        match self.state.as_str() { "Open" | "" => format!("#{}", self.number), s => format!("#{} {}", self.number, s.to_lowercase()) }
    }
}

/// A rate limit's window as its vendor reports it: its name (5h, week, fable…), how much of it is
/// used (percent) and when it resets.
#[derive(Clone, Debug, PartialEq)]
pub struct Window { pub label: String, pub used: f64, pub resets: Option<String> }

/// One agent account's limits (usage_read's reading of Claude's or Codex's), read as the desktop
/// reads them (claude_usage_source.dart, codex_usage_source.dart).
#[derive(Clone, Debug, PartialEq)]
pub struct Usage { pub provider: String, pub account: Option<String>, pub windows: Vec<Window> }

impl Usage {
    /// `claude 5h 42% week 18%`.
    pub fn line(&self) -> String {
        let windows: Vec<String> = self.windows.iter().map(|w| format!("{} {:.0}%", w.label, w.used)).collect();
        format!("{} {}", self.provider, windows.join(" "))
    }
}

/// A usage_read reading, when the vendor answered with limits.
pub fn usage_from(reading: &Value) -> Option<Usage> {
    if reading.get("outcome").and_then(Value::as_str) != Some("answered") { return None }
    if reading.get("httpStatus").and_then(Value::as_u64).map(|s| s >= 300).unwrap_or(false) { return None }
    let body = reading.get("body")?;
    let provider = reading.get("provider").and_then(Value::as_str)?;
    // parseUsedPercent: a number or a numeral, held to 0–100.
    let percent = |v: Option<&Value>| v.and_then(|x| x.as_f64().or_else(|| x.as_str().and_then(|s| s.trim().parse().ok()))).filter(|f: &f64| f.is_finite()).map(|f| f.clamp(0.0, 100.0));
    let text = |w: &Value, k: &str| w.get(k).and_then(|v| v.as_str().map(str::to_string).or_else(|| v.as_i64().map(|n| n.to_string())));
    let windows: Vec<Window> = match provider {
        "claude" => {
            let one = |label: &str, w: Option<&Value>| w.and_then(|w| Some(Window { label: label.into(), used: percent(w.get("utilization")).or_else(|| percent(w.get("used_percentage")))?, resets: text(w, "resets_at") }));
            let fable = ["fable_weekly", "fable_seven_day", "seven_day_fable"].iter().find_map(|k| body.get(*k));
            [one("5h", body.get("five_hour")), one("week", body.get("seven_day")), one("fable", fable)].into_iter().flatten().collect()
        }
        "codex" => {
            // A window named by how long it is (_labelFor).
            let label = |w: &Value| match w.get("limit_window_seconds").and_then(Value::as_f64).filter(|s| *s > 0.0).map(|s| s.round() as u64) {
                None => "limit".to_string(),
                Some(s) if s < 3600 => format!("{}m", s / 60),
                Some(s) if s < 86400 => format!("{}h", s / 3600),
                Some(s) if s / 86400 == 7 => "week".to_string(),
                Some(s) => format!("{}d", s / 86400),
            };
            let limits = body.get("rate_limit");
            ["primary_window", "secondary_window"].iter().filter_map(|k| limits.and_then(|l| l.get(*k))).filter_map(|w| Some(Window { label: label(w), used: percent(w.get("used_percent"))?, resets: text(w, "reset_at") })).collect()
        }
        _ => Vec::new(),
    };
    (!windows.is_empty()).then(|| Usage { provider: provider.to_string(), account: reading.get("account").and_then(Value::as_str).map(str::to_string), windows })
}

/// A count of tokens as a list says it: 950, 12k, 1.2M.
pub fn compact(n: u64) -> String {
    match n {
        0..=999 => n.to_string(),
        1_000..=99_999 => format!("{:.1}k", n as f64 / 1e3).replace(".0k", "k"),
        100_000..=999_999 => format!("{}k", n / 1000),
        _ => format!("{:.1}M", n as f64 / 1e6).replace(".0M", "M"),
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum State {
    NeedsInput,
    Working,
    Done,
    Ready,
    Unknown,
    Starting,
    Failed,
    Paused,
    Offline,
}

impl Agent {
    pub fn key(&self) -> (String, String) { (self.machine_id.clone(), self.id.clone()) }

    pub fn state(&self, machine: Option<&Machine>) -> State {
        // Offline only when the machine is known to be unreachable — not while it is still being
        // dialled (a cached roster at startup), which lasts a second and is not news.
        let down = machine.map(|m| matches!(m.reach, Reach::Offline | Reach::NeedsLink | Reach::Error(_)) || (!m.online() && !m.local)).unwrap_or(false);
        if down || self.status == "offline" { return State::Offline }
        if self.status == "stopped" { return State::Paused }
        if self.launch == "starting" { return State::Starting }
        if self.launch == "failed" { return State::Failed }
        if self.question.is_some() { return State::NeedsInput }
        if self.working { return State::Working }
        if self.errored { return State::Failed }
        if self.unread { return State::Done }
        if self.activity.unknown { return State::Unknown }
        State::Ready
    }

    /// When it was last active: its conversation's time (updatedAt), or later what this client saw
    /// it do — never a bookkeeping stamp (its token count's refresh moves every harness at once).
    pub fn recency(&self) -> u64 { let t = self.updated_at.max(self.active_at); if t > 0 { t } else { self.created_at } }

    /// When it came to be as it is (ms since the epoch): waiting on you since its question, working
    /// since its turn began, done or failed since it ended; idle, paused or offline since it last
    /// did anything.
    pub fn state_since(&self, state: State) -> u64 {
        match &self.question {
            Some(q) => now_ms().saturating_sub(q.since.elapsed().as_millis() as u64),
            None if self.since > 0 && !matches!(state, State::Ready | State::Paused | State::Offline) => self.since,
            None => self.recency(),
        }
    }
}

pub fn now_ms() -> u64 {
    SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis() as u64).unwrap_or(0)
}

fn s(v: &Value, key: &str) -> String { v.get(key).and_then(Value::as_str).unwrap_or("").to_string() }

fn time(v: &Value, key: &str) -> u64 {
    // RFC 3339 → ms, without a date crate: the daemon always writes `YYYY-MM-DDTHH:MM:SS.sssZ`.
    let text = s(v, key);
    parse_iso(&text).unwrap_or(0)
}

pub fn parse_iso(text: &str) -> Option<u64> {
    let b = text.as_bytes();
    if b.len() < 19 { return None }
    let n = |from: usize, to: usize| text.get(from..to)?.parse::<i64>().ok();
    let (y, mo, d, h, mi, se) = (n(0, 4)?, n(5, 7)?, n(8, 10)?, n(11, 13)?, n(14, 16)?, n(17, 19)?);
    let ms = if b.len() > 20 && b[19] == b'.' { text.get(20..23).and_then(|x| x.parse::<i64>().ok()).unwrap_or(0) } else { 0 };
    // Days from civil (Howard Hinnant).
    let y2 = if mo <= 2 { y - 1 } else { y };
    let era = if y2 >= 0 { y2 } else { y2 - 399 } / 400;
    let yoe = y2 - era * 400;
    let doy = (153 * (mo + if mo > 2 { -3 } else { 9 }) + 2) / 5 + d - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    let days = era * 146097 + doe - 719468;
    Some(((days * 86400 + h * 3600 + mi * 60 + se) * 1000 + ms) as u64)
}

pub fn agent_from(machine_id: &str, row: &Value, previous: Option<&Agent>) -> Agent {
    if let Some(agent) = previous {
        if agent.session_id != s(row, "sessionId") && agent.activity.older(&row["activity"]) { return agent.clone() }
    }
    let activity = previous.map(|p| p.activity.clone()).unwrap_or_default();
    // (The pane outlives the engine's session: kept across one, and after the row no longer says it.)
    let last_pane = previous.map(|p| p.tmux_pane.clone()).unwrap_or_default();
    let previous = previous.filter(|agent| agent.session_id == s(row, "sessionId"));
    let project = row.get("project").cloned().unwrap_or(Value::Null);
    let launch = row.get("launch").cloned().unwrap_or(Value::Null);
    let title = s(row, "title");
    let mut name = s(row, "name");
    if name.is_empty() { name = if !title.is_empty() { title } else { s(&project, "name") } }
    if name.is_empty() { name = s(row, "engine") }
    let dsh = { let n = s(row, "dshName"); if n.is_empty() { s(row, "dsh") } else { n } };
    let mut agent = Agent {
        machine_id: machine_id.to_string(),
        id: s(row, "id"),
        session_id: s(row, "sessionId"),
        name,
        engine: { let e = s(row, "engine"); if e.is_empty() { "terminal".into() } else { e } },
        status: { let st = s(row, "status"); if st.is_empty() { "active".into() } else { st } },
        launch: { let l = s(&launch, "state"); if l.is_empty() { "ready".into() } else { l } },
        cwd: s(&project, "cwd"),
        project: s(&project, "name"),
        branch: s(&project, "branch"),
        created_at: time(row, "createdAt"),
        created_at_wire: s(row, "createdAt"),
        close_supported: row["closeSupported"] == true,
        terminal_available: row.pointer("/terminal/available").and_then(Value::as_bool).unwrap_or_else(|| {
            row.pointer("/terminal/runtimes").and_then(Value::as_array).is_some_and(|r| r.iter().any(|r| r["backend"] == "tmux"))
        }),
        dsh_id: s(row, "dsh"),
        permission_mode: s(row, "permissionMode"),
        updated_at: time(row, "updatedAt"),
        known_at: previous.map(|p| p.known_at).unwrap_or_else(Instant::now),
        // Not `updatedAt`: the daemon restamps every row on each reconcile.
        active_at: previous.map(|p| p.active_at).unwrap_or(0),
        activity,
        working: previous.map(|p| p.working).unwrap_or(false),
        last_beat: previous.and_then(|p| p.last_beat),
        question: previous.and_then(|p| p.question.clone()),
        unread: previous.map(|p| p.unread).unwrap_or(false),
        dsh,
        viewer_url: s(row, "viewerUrl"),
        viewer_name: s(row, "viewerName"),
        viewer_error: s(row, "viewerError"),
        model: s(row, "selectedModel"),
        project_root: { let r = s(&project, "root"); if r.is_empty() { s(&project, "cwd") } else { r } },
        doing: previous.and_then(|p| p.doing.clone()),
        said: previous.map(|p| p.said.clone()).unwrap_or_default(),
        did: previous.and_then(|p| p.did.clone()),
        since: previous.map(|p| p.since).unwrap_or(0),
        tokens: row.pointer("/tokenUsage/totalTokens").and_then(Value::as_u64).or(previous.map(|p| p.tokens)).unwrap_or(0),
        added: row.pointer("/outputStats/linesAdded").and_then(Value::as_u64).or(previous.map(|p| p.added)).unwrap_or(0),
        removed: row.pointer("/outputStats/linesRemoved").and_then(Value::as_u64).or(previous.map(|p| p.removed)).unwrap_or(0),
        prs_made: row.pointer("/outputStats/pullRequestsCreated").and_then(Value::as_u64).or(previous.map(|p| p.prs_made)).unwrap_or(0),
        launch_error: {
            let detail = s(&launch, "detail");
            let code = s(&launch, "error");
            match first_line(&detail) { Some(d) => d, None if !code.is_empty() => { let t = code.to_lowercase().replace('_', " "); let mut c = t.chars(); c.next().map(|f| f.to_uppercase().collect::<String>() + c.as_str()).unwrap_or_default() } None => String::new() }
        },
        asked: previous.and_then(|p| p.asked.clone()),
        pr: previous.and_then(|p| p.pr.clone()),
        pr_checked: previous.and_then(|p| p.pr_checked),
        recap_asked: previous.map(|p| p.recap_asked).unwrap_or(false),
        errored: previous.map(|p| p.errored).unwrap_or(false),
        last_text: previous.map(|p| p.last_text.clone()).unwrap_or_default(),
        usage_at: row.get("tokenUsage").map(|u| time(u, "updatedAt")).filter(|t| *t > 0).or(previous.map(|p| p.usage_at)).unwrap_or(0),
        todos: previous.map(|p| p.todos.clone()).unwrap_or_default(),
        subagents: previous.map(|p| p.subagents.clone()).unwrap_or_default(),
        // ── models ── (the daemon pushes the row again when its note clears)
        grid_model: s(&row["grid"], "model"),
        grid_base_url: s(&row["grid"], "baseUrl"),
        grid_state: s(&row["grid"], "state"),
        grid_note: grid_note(&row["grid"]["note"]),
        tmux_pane: { let pane = s(row, "tmuxPane"); if pane.is_empty() { last_pane } else { pane } },
    };
    if let Some(working) = agent.activity.accept(&row["activity"], Instant::now()) { agent.working = working; }
    if matches!(agent.status.as_str(), "stopped" | "offline") { agent.working = false; agent.activity.unknown = false; }
    agent
}

/// TodoWrite's list: each item's words (its present-tense form while it is in progress) and state.
pub fn todos_of(input: &Value) -> Vec<(String, String)> {
    input.get("todos").and_then(Value::as_array).map(|todos| todos.iter().filter_map(|t| {
        let status = t.get("status").and_then(Value::as_str).unwrap_or("pending").to_string();
        let words = if status == "in_progress" { t.get("activeForm").or_else(|| t.get("content")) } else { t.get("content") }.and_then(Value::as_str)?;
        Some((words.to_string(), status))
    }).collect()).unwrap_or_default()
}

/// A tool call as the one line that says what an agent is doing (Claude Code's own words where
/// it gives them: a Bash call's description).
pub fn describe_tool(tool: &str, input: &Value) -> String {
    let text = |k: &str| input.get(k).and_then(Value::as_str).map(str::trim).filter(|v| !v.is_empty()).map(str::to_string);
    let file = |k: &str| text(k).map(|p| crate::sys::path_name(&p).to_string());
    let first = |v: String| v.lines().next().unwrap_or("").trim().to_string();
    let command = || match input.get("command") {
        Some(Value::Array(parts)) => parts.iter().filter_map(Value::as_str).collect::<Vec<_>>().join(" "),
        Some(Value::String(c)) => c.clone(),
        _ => String::new(),
    };
    let line = match tool {
        "Bash" | "shell" | "exec_command" | "local_shell" => text("description").unwrap_or_else(|| format!("$ {}", first(command()))),
        "Read" | "read_file" => format!("Reading {}", file("file_path").or_else(|| file("path")).unwrap_or_default()),
        "Edit" | "MultiEdit" | "Write" | "NotebookEdit" | "apply_patch" | "edit_file" | "write_file" =>
            match file("file_path").or_else(|| file("path")).or_else(|| file("notebook_path")) { Some(f) => format!("Editing {f}"), None => "Editing".into() },
        "Grep" | "grep" => format!("Searching for {}", text("pattern").unwrap_or_default()),
        "Glob" | "glob" => format!("Finding {}", text("pattern").unwrap_or_default()),
        "WebSearch" | "web_search" => format!("Searching the web for {}", text("query").unwrap_or_default()),
        "WebFetch" | "web_fetch" => format!("Reading {}", text("url").unwrap_or_default()),
        "Task" | "Agent" => text("description").map(|d| format!("Agent: {d}")).unwrap_or_else(|| "Running an agent".into()),
        "TodoWrite" => input.get("todos").and_then(Value::as_array)
            .and_then(|todos| todos.iter().find(|t| t.get("status").and_then(Value::as_str) == Some("in_progress")))
            .and_then(|t| t.get("activeForm").or_else(|| t.get("content")).and_then(Value::as_str).map(str::to_string))
            .unwrap_or_else(|| "Planning".into()),
        t => match t.strip_prefix("mcp__").and_then(|r| r.split_once("__")) { Some((server, name)) => format!("{name} ({server})"), None => t.to_string() },
    };
    line.chars().take(160).collect()
}

/// The line a message comes to: its first line with words in it, markdown taken off.
pub fn first_line(text: &str) -> Option<String> {
    let line = text.lines().map(str::trim).find(|l| l.chars().any(char::is_alphanumeric))?;
    let line = line.trim_start_matches(['#', '>', '-', '*', '•', ' ']).replace("**", "").replace('`', "");
    let line = line.trim();
    (!line.is_empty()).then(|| line.chars().take(160).collect())
}

pub fn question_from(payload: &Value, previous: Option<&Question>) -> Option<Question> {
    let request_id = s(payload, "requestId");
    let first = payload.get("questions")?.as_array()?.first()?.clone();
    let prompt = first.get("q").or_else(|| first.get("key")).and_then(Value::as_str).unwrap_or("").trim().to_string();
    if request_id.is_empty() || prompt.is_empty() { return None }
    let options = first.get("options").and_then(Value::as_array).map(|a| a.iter().filter_map(|o| o.as_str().map(|x| x.trim().to_string())).filter(|x| !x.is_empty()).collect()).unwrap_or_default();
    Some(Question {
        answer_key: first.get("key").and_then(Value::as_str).map(str::to_string).unwrap_or_else(|| prompt.clone()),
        since: previous.filter(|p| p.request_id == request_id).map(|p| p.since).unwrap_or_else(Instant::now),
        multi: first.get("multi").and_then(Value::as_bool).unwrap_or(false),
        request_id,
        prompt,
        options,
    })
}

/// An answer as typed: numbers (`2`, `1,3`) are those options (several joined with ", ", as the
/// daemon keys a multi-choice answer); anything else is the answer in your own words.
/// An error's line without the JSON an API wraps it in: `API Error: 529 {"type":"error","error":
/// {"type":"overloaded_error","message":"Overloaded"}}` is `API Error: 529 Overloaded`.
pub fn tidy_error(line: &str) -> String {
    if let Some(i) = line.find('{') {
        if let Ok(v) = serde_json::from_str::<Value>(&line[i..]) {
            let what = v.pointer("/error/message").or_else(|| v.pointer("/error/type")).or_else(|| v.get("message")).and_then(Value::as_str);
            if let Some(w) = what { return format!("{} {w}", line[..i].trim_end()).trim().to_string() }
        }
    }
    line.to_string()
}

/// An answer given by its choices' numbers (`2`; `1,3` for a question that takes several): the
/// choices' words — anything else is refused, never sent as words (answer -l for words).
pub fn choices(q: &Question, typed: &str) -> Result<String, String> {
    let parts: Vec<&str> = typed.split([',', ' ']).filter(|s| !s.is_empty()).collect();
    let n = q.options.len();
    if n == 0 { return Err("this question has no choices: answer -l with words".into()) }
    let mut picked = Vec::new();
    for p in &parts {
        match p.parse::<usize>() {
            Ok(k) if k >= 1 && k <= n => picked.push(q.options[k - 1].clone()),
            _ => return Err(format!("{p} is not a choice (1–{n}; -l for words)")),
        }
    }
    if picked.is_empty() { return Err("no choice given".into()) }
    if picked.len() > 1 && !q.multi { return Err(format!("one choice only (1–{n})")) }
    Ok(picked.join(", "))
}

pub fn answer_text(q: &Question, typed: &str) -> Option<String> {
    let typed = typed.trim();
    if typed.is_empty() { return None }
    let numbers: Option<Vec<usize>> = typed.split([',', ' ']).filter(|s| !s.is_empty()).map(|s| s.parse::<usize>().ok().filter(|n| *n >= 1 && *n <= q.options.len())).collect();
    match numbers {
        Some(ns) if !ns.is_empty() && (q.multi || ns.len() == 1) => Some(ns.iter().map(|n| q.options[n - 1].clone()).collect::<Vec<_>>().join(", ")),
        _ => Some(typed.to_string()),
    }
}

/// A whole machine another account shares with this one (backend lib/machineAccess.ts): its owner
/// named this account's address, or shared it with everyone at their domain ([team]) and this account
/// added it. Used as the account's own; its owner alone renames, removes or shares it.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct MachineShare {
    pub owner: String,
    pub email: String,
    pub team: bool,
}

impl MachineShare {
    /// From a `sharedMachines` row's `share`.
    pub fn of(share: &Value) -> MachineShare {
        let text = |key: &str| share.get(key).and_then(Value::as_str).unwrap_or("").trim().to_string();
        let (name, email) = (text("ownerName"), text("ownerEmail"));
        MachineShare { owner: if name.is_empty() { email.clone() } else { name }, email, team: share.get("via").and_then(Value::as_str) == Some("domain") }
    }
}

#[derive(Default)]
pub struct Fleet {
    pub local_id: String,
    pub machines: Vec<Machine>,
    pub agents: HashMap<(String, String), Agent>,
    /// The machines in [machines] another account shares with this one, by id.
    pub shares: HashMap<String, MachineShare>,
    /// Machines shared with this account's domain, not added yet: (id, name, share). Machines &
    /// devices lists them, and Enter adds one.
    pub to_add: Vec<(String, String, MachineShare)>,
}

/// Match the desktop and phone: the app's saved name, or its stable machine-id label.
pub fn machine_display_name(id: &str, name: Option<&str>) -> String {
    name.map(str::trim).filter(|name| !name.is_empty()).map(str::to_string)
        .unwrap_or_else(|| format!("machine-{}", id.chars().take(8).collect::<String>()))
}

impl Fleet {
    /// The machine list's rows to keep: the account's own ([owned]) and the whole machines other
    /// accounts share with it that are its to use (named for it, or added), noted in [shares]; one
    /// shared with its domain and not added goes to [to_add]. A list that could not say ([shared]
    /// absent) keeps the shared machines it had.
    pub fn take_shared(&mut self, owned: &[Value], shared: Option<&Vec<Value>>) -> Vec<Value> {
        let mut rows = owned.to_vec();
        let Some(shared) = shared else {
            rows.extend(self.shares.keys().filter_map(|id| self.machine(id))
                .map(|m| serde_json::json!({ "machineId": m.id, "name": m.name, "status": m.status })));
            return rows;
        };
        self.shares.clear();
        self.to_add.clear();
        for row in shared {
            let id = row.get("machineId").and_then(Value::as_str).unwrap_or("").to_string();
            if id.is_empty() || owned.iter().any(|o| o["machineId"] == row["machineId"]) { continue }
            let share = MachineShare::of(&row["share"]);
            if row["share"]["added"] == true {
                self.shares.insert(id, share);
                rows.push(row.clone());
            } else {
                let name = machine_display_name(&id, row.get("name").and_then(Value::as_str));
                self.to_add.push((id, name, share));
            }
        }
        rows
    }

    pub fn machine(&self, id: &str) -> Option<&Machine> { self.machines.iter().find(|m| m.id == id) }
    /// Another account's machine, shared view-only ([Machine::shared]) or whole ([shares]): its daemon
    /// answers as its owner, so a harness there is never this account's to move (desktop's
    /// `belongsToOtherAccount`).
    pub fn belongs_to_other_account(&self, id: &str) -> bool { self.shares.contains_key(id) || self.machine(id).is_some_and(|m| m.shared) }
    pub fn machine_mut(&mut self, id: &str) -> Option<&mut Machine> { self.machines.iter_mut().find(|m| m.id == id) }
    /// The account's record for this computer; the local PTY transport is not another machine.
    pub fn registered_local_machine(&self) -> Option<&Machine> {
        self.machine(&self.local_id).filter(|m| !crate::local::is_local(&m.id))
            .or_else(|| self.machines.iter().find(|m| m.local && !crate::local::is_local(&m.id)))
    }
    pub fn local_machine_name(&self) -> String {
        self.registered_local_machine().map(|m| machine_display_name(&m.id, Some(&m.name)))
            .unwrap_or_else(|| "This computer".into())
    }
    pub fn machine_name(&self, id: &str) -> String {
        if crate::local::is_local(id) { return self.local_machine_name() }
        machine_display_name(id, self.machine(id).map(|m| m.name.as_str()))
    }
    /// New work from a local shell goes through Harness when its daemon is connected.
    /// Existing PTYs keep their transport identity so their sessions survive reconnects.
    pub fn launch_machine_id<'a>(&'a self, id: &'a str) -> &'a str {
        if crate::local::is_local(id) {
            if let Some(machine) = self.registered_local_machine().filter(|m| m.usable()) { return &machine.id }
        }
        id
    }
    pub fn visible_machines(&self) -> impl Iterator<Item = &Machine> {
        let connected_local = self.registered_local_machine().is_some_and(Machine::usable);
        self.machines.iter().filter(move |m| !connected_local || !crate::local::is_local(&m.id))
    }
    pub fn agent(&self, machine: &str, id: &str) -> Option<&Agent> { self.agents.get(&(machine.to_string(), id.to_string())) }

    pub fn state_of(&self, agent: &Agent) -> State { agent.state(self.machine(&agent.machine_id)) }

    /// Replace one machine's roster from an `agents_list` reply, keeping live state on survivors.
    /// A machine's roster from an `agents_list` reply asked for at [asked]: one this client made
    /// after it was asked (a shell just started) stays, though the list could not have it.
    pub fn replace_roster(&mut self, machine_id: &str, rows: &[Value], asked: Instant) {
        let mut next = HashMap::new();
        for row in rows {
            let id = s(row, "id");
            if id.is_empty() { continue }
            let key = (machine_id.to_string(), id);
            let agent = agent_from(machine_id, row, self.agents.get(&key));
            next.insert(key, agent);
        }
        self.agents.retain(|(m, _), a| m != machine_id || a.known_at > asked);
        self.agents.extend(next);
    }

    /// Upsert rows without dropping anyone — the fast live-only list arriving before the full one.
    pub fn merge_roster(&mut self, machine_id: &str, rows: &[Value]) {
        for row in rows {
            let id = s(row, "id");
            if id.is_empty() { continue }
            let key = (machine_id.to_string(), id);
            let agent = agent_from(machine_id, row, self.agents.get(&key));
            self.agents.insert(key, agent);
        }
    }

    pub fn find_by_session(&mut self, machine_id: &str, session: &str) -> Option<&mut Agent> {
        self.agents.values_mut().find(|a| a.machine_id == machine_id && a.session_id == session)
    }

    /// The agent a pushed event is about: `agentId`, else its session.
    pub fn event_agent(&mut self, machine_id: &str, payload: &Value) -> Option<&mut Agent> {
        let id = s(payload, "agentId");
        if !id.is_empty() && self.agents.contains_key(&(machine_id.to_string(), id.clone())) {
            let agent = self.agents.get_mut(&(machine_id.to_string(), id))?;
            let session = payload.get("sessionId").or_else(|| payload.get("dbSessionId")).and_then(Value::as_str);
            if agent.status == "stopped" || session.is_some_and(|s| !agent.session_id.is_empty() && s != agent.session_id) { return None }
            return Some(agent);
        }
        let session = { let x = s(payload, "sessionId"); if x.is_empty() { s(payload, "dbSessionId") } else { x } };
        if session.is_empty() { return None }
        self.find_by_session(machine_id, &session)
    }

    /// Sorted the way ⌥O lists them: waiting on you, working, running by recency, paused, offline.
    /// Every harness in the order it needs you: waiting on you, failed, done and unread, working,
    /// starting, idle, paused, offline — within the first three and working, the one that has
    /// waited (or run) longest first; the rest most recent first.
    pub fn ranked(&self) -> Vec<&Agent> {
        let bucket = |st: State| match st { State::NeedsInput => 0, State::Failed => 1, State::Done => 2, State::Working => 3, State::Starting => 4, State::Unknown => 5, State::Ready => 6, State::Paused => 7, State::Offline => 8 };
        // Each one's key once (the clock read once for all: a comparison that read it again could
        // order two alike harnesses both ways, which a sort must never see).
        let now = now_ms();
        let mut keyed: Vec<((u8, u64, &str), &Agent)> = self.agents.values().map(|a| {
            let b = bucket(self.state_of(a));
            let age = match &a.question { Some(q) => now.saturating_sub(q.since.elapsed().as_millis() as u64), None => a.since };
            // The urgent ones longest waiting first; the rest most recent first.
            let order = if b <= 3 { age } else { u64::MAX - a.recency() };
            ((b, order, a.name.as_str()), a)
        }).collect();
        keyed.sort_by(|x, y| x.0.cmp(&y.0));
        keyed.into_iter().map(|(_, a)| a).collect()
    }

    /// How many harnesses (shells aside) are in each state: the status line's counts.
    pub fn count(&self, state: State) -> usize {
        self.agents.values().filter(|a| a.engine != "terminal" && self.state_of(a) == state).count()
    }

    pub fn waiting(&self) -> usize { self.agents.values().filter(|a| a.question.is_some() && a.status != "stopped").count() }
}

// ── the roster between runs ────────────────────────────────────────────────────

fn cache_path() -> std::path::PathBuf {
    crate::app::state_dir().join("fleet.json")
}

pub(crate) fn cached_owner() -> Option<String> {
    let value: Value = serde_json::from_str(&std::fs::read_to_string(cache_path()).ok()?).ok()?;
    value["owner"].as_str().filter(|id| !id.is_empty() && !crate::local::is_local(id)).map(str::to_string)
}

impl Fleet {
    /// Restore only after this user's daemon identifies the current account's machine. Old caches
    /// had no owner and may have come from another OS user's TCP listener; never adopt those.
    pub fn load_cache(&mut self, owner: &str) {
        let Ok(text) = std::fs::read_to_string(cache_path()) else { return };
        let Ok(value) = serde_json::from_str::<Value>(&text) else { return };
        self.restore_cache(&value, owner);
    }

    fn restore_cache(&mut self, value: &Value, owner: &str) {
        if owner.is_empty() || value.get("owner").and_then(Value::as_str) != Some(owner) { return }
        for m in value.get("machines").and_then(Value::as_array).into_iter().flatten() {
            let id = s(m, "id");
            if id.is_empty() || self.machine(&id).is_some() { continue }
            self.machines.push(Machine { shared: m["shared"] == true, name: s(m, "name"), local: m.get("local").and_then(Value::as_bool).unwrap_or(false), status: s(m, "status"), reach: Reach::Unknown, id });
        }
        for a in value.get("agents").and_then(Value::as_array).into_iter().flatten() {
            let machine = s(a, "machine");
            let row = a.get("row").cloned().unwrap_or(Value::Null);
            let id = s(&row, "id");
            if machine.is_empty() || id.is_empty() { continue }
            let mut agent = agent_from(&machine, &row, None);
            agent.active_at = a.get("activeAt").and_then(Value::as_u64).unwrap_or(0);
            self.agents.entry((machine, id)).or_insert(agent);
        }
    }

    pub fn save_cache(&self) {
        if self.agents.is_empty() || self.local_id.is_empty() || crate::local::is_local(&self.local_id) { return }
        let machines: Vec<Value> = self.machines.iter().map(|m| serde_json::json!({ "id": m.id, "name": m.name, "local": m.local, "shared": m.shared, "status": m.status })).collect();
        let agents: Vec<Value> = self.agents.values().map(|a| serde_json::json!({
            "machine": a.machine_id, "activeAt": a.active_at,
            "row": { "id": a.id, "sessionId": a.session_id, "name": a.name, "engine": a.engine, "status": a.status,
                     "launch": { "state": a.launch }, "selectedModel": a.model, "dshName": a.dsh,
                     "project": { "cwd": a.cwd, "name": a.project, "branch": a.branch, "root": a.project_root } },
        })).collect();
        let path = cache_path();
        if let Some(dir) = path.parent() { let _ = std::fs::create_dir_all(dir); }
        let temp = path.with_extension("json.tmp");
        if std::fs::write(&temp, serde_json::json!({ "owner": self.local_id, "machines": machines, "agents": agents }).to_string()).is_ok() { let _ = std::fs::rename(temp, path); }
    }
}

/// "3m", "2h", "4d".
pub fn ago(ms: u64) -> String {
    if ms == 0 { return String::new() }
    let secs = now_ms().saturating_sub(ms) / 1000;
    match secs {
        0..=59 => format!("{secs}s"),
        60..=3599 => format!("{}m", secs / 60),
        3600..=86_399 => format!("{}h", secs / 3600),
        _ => format!("{}d", secs / 86_400),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn whole_machines_shared_with_the_account_are_kept_and_one_for_the_team_waits_to_be_added() {
        use serde_json::json;
        let mut fleet = Fleet::default();
        let owned = vec![json!({ "machineId": "own", "name": "studio" })];
        let share = |via: &str, added: bool| json!({ "ownerName": "Dee", "ownerEmail": "[email protected]", "via": via, "added": added });
        let shared = vec![
            json!({ "machineId": "named", "name": "Dee's Mac", "share": share("email", true) }),
            json!({ "machineId": "team", "name": "GPU box", "share": share("domain", true) }),
            json!({ "machineId": "waiting", "name": null, "share": share("domain", false) }),
            // Also the account's own: its own row wins.
            json!({ "machineId": "own", "share": share("email", true) }),
        ];
        let rows = fleet.take_shared(&owned, Some(&shared));
        assert_eq!(rows.iter().map(|r| r["machineId"].as_str().unwrap()).collect::<Vec<_>>(), ["own", "named", "team"]);
        assert_eq!(fleet.shares.get("named"), Some(&MachineShare { owner: "Dee".into(), email: "[email protected]".into(), team: false }));
        assert!(fleet.shares["team"].team);
        assert_eq!(fleet.to_add, vec![("waiting".to_string(), "machine-waiting".to_string(), MachineShare { owner: "Dee".into(), email: "[email protected]".into(), team: true })]);
        // A list that could not say what is shared keeps what it had.
        fleet.machines.push(Machine { shared: false, id: "named".into(), name: "Dee's Mac".into(), local: false, status: "running".into(), reach: Reach::Ready });
        let kept = fleet.take_shared(&owned, None);
        assert_eq!(kept.iter().map(|r| r["machineId"].as_str().unwrap()).collect::<Vec<_>>(), ["own", "named"]);
        assert!(fleet.shares.contains_key("named"));
        // An owner with no name is shown by address.
        assert_eq!(MachineShare::of(&json!({ "ownerName": " ", "ownerEmail": "[email protected]" })).owner, "[email protected]");
    }

    #[test]
    fn cache_needs_the_current_accounts_owner_and_drops_legacy_unscoped_data() {
        let mut cached = serde_json::json!({
            "owner": "account-a", "machines": [{"id": "remote-a", "name": "private-machine"}],
            "agents": [{"machine": "remote-a", "row": {"id": "private-agent", "name": "private work"}}]
        });
        let mut fleet = Fleet::default();
        fleet.restore_cache(&cached, "account-b");
        assert!(fleet.machines.is_empty() && fleet.agents.is_empty());
        cached.as_object_mut().unwrap().remove("owner");
        fleet.restore_cache(&cached, "account-a");
        fleet.restore_cache(&cached, "");
        assert!(fleet.machines.is_empty() && fleet.agents.is_empty());
        cached["owner"] = serde_json::json!("account-a");
        fleet.restore_cache(&cached, "account-a");
        assert_eq!(fleet.machines.len(), 1);
        assert_eq!(fleet.agents.len(), 1);
    }

    #[test]
    fn local_shells_share_the_app_name_without_changing_their_transport() {
        let shell = crate::local::MACHINE;
        let mut fleet = Fleet { local_id: "registered-local".into(), ..Default::default() };
        for (id, name, local) in [(shell, "m0", true), ("registered-local", "office", true), ("remote", "GPU rig", false)] {
            fleet.machines.push(Machine { shared: false, id: id.into(), name: name.into(), local, status: "running".into(), reach: Reach::Ready });
        }
        assert_eq!(fleet.machine_name(shell), "office");
        assert_eq!(fleet.machine_name("registered-local"), "office");
        assert_eq!(fleet.machine_name("remote"), "GPU rig");
        assert_eq!(fleet.launch_machine_id(shell), "registered-local");
        assert_eq!(fleet.visible_machines().map(|m| m.id.as_str()).collect::<Vec<_>>(), ["registered-local", "remote"]);
        assert_eq!(fleet.machine(shell).unwrap().id, shell);
        // A rename is visible even to existing shell panes. Offline boot keeps the cached app name.
        fleet.machine_mut("registered-local").unwrap().name = "Work Mac".into();
        assert_eq!(fleet.machine_name(shell), "Work Mac");
        fleet.local_id = shell.into();
        fleet.machine_mut("registered-local").unwrap().reach = Reach::Offline;
        assert_eq!(fleet.local_machine_name(), "Work Mac");
        assert_eq!(fleet.machine_name(shell), "Work Mac");
        assert_eq!(fleet.launch_machine_id(shell), shell);
        // An unnamed account machine follows the desktop/phone convention, not its hostname.
        fleet.machine_mut("registered-local").unwrap().name.clear();
        assert_eq!(fleet.machine_name(shell), "machine-register");
        assert_eq!(Fleet::default().machine_name(shell), "This computer");
    }

    #[test]
    fn parses_iso() {
        assert_eq!(parse_iso("1970-01-01T00:00:01.500Z"), Some(1500));
        assert_eq!(parse_iso("2026-09-25T17:13:11.614Z"), Some(1790356391614));
    }
}

#[cfg(test)]
mod usage_tests {
    use super::*;

    #[test]
    fn limits_read_as_the_desktop_reads_them() {
        let claude = serde_json::json!({ "provider": "claude", "account": "a", "outcome": "answered", "httpStatus": 200, "body": { "five_hour": { "utilization": 92.4 }, "seven_day": { "utilization": "18" }, "seven_day_fable": { "used_percentage": 5 } } });
        assert_eq!(usage_from(&claude).unwrap().line(), "claude 5h 92% week 18% fable 5%");
        let codex = serde_json::json!({ "provider": "codex", "outcome": "answered", "body": { "rate_limit": { "primary_window": { "used_percent": 3, "limit_window_seconds": 18000 }, "secondary_window": { "used_percent": 150, "limit_window_seconds": 604800 } } } });
        assert_eq!(usage_from(&codex).unwrap().line(), "codex 5h 3% week 100%");
        assert!(usage_from(&serde_json::json!({ "provider": "claude", "outcome": "signedOut" })).is_none());
        assert!(usage_from(&serde_json::json!({ "provider": "claude", "outcome": "answered", "httpStatus": 401, "body": {} })).is_none());
        assert_eq!(compact(1_240_000), "1.2M");
        assert_eq!(compact(88_400), "88.4k");
        assert_eq!(compact(12_000), "12k");
        assert_eq!(compact(356_000), "356k");
    }
}

#[cfg(test)]
mod tidy_tests {
    #[test]
    fn api_errors_without_their_json() {
        assert_eq!(super::tidy_error(r#"API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}"#), "API Error: 529 Overloaded");
        assert_eq!(super::tidy_error("API Error: 529 overloaded"), "API Error: 529 overloaded");
        assert_eq!(super::tidy_error("a {not json"), "a {not json");
    }
}

#[cfg(test)]
mod answer_tests {
    use super::*;

    #[test]
    fn typed_answers() {
        let q = |multi| Question { request_id: "r".into(), answer_key: "k".into(), prompt: "p".into(), options: vec!["Per API key".into(), "Per IP".into(), "Both".into()], multi, since: Instant::now() };
        assert_eq!(answer_text(&q(false), "2").as_deref(), Some("Per IP"));
        assert_eq!(answer_text(&q(true), "1,3").as_deref(), Some("Per API key, Both"));
        assert_eq!(answer_text(&q(true), "1 3").as_deref(), Some("Per API key, Both"));
        // Several numbers for a one-choice question, a number out of range, words: as typed.
        assert_eq!(answer_text(&q(false), "1,3").as_deref(), Some("1,3"));
        assert_eq!(answer_text(&q(false), "9").as_deref(), Some("9"));
        assert_eq!(answer_text(&q(false), " per user, please ").as_deref(), Some("per user, please"));
        assert_eq!(answer_text(&q(false), "  "), None);
    }
}

#[cfg(test)]
mod activity_evidence_tests {
    use super::*;
    use serde_json::json;
    #[test]
    fn late_snapshot_cannot_restore_an_old_conversation() {
        let old = json!({"id":"agent","sessionId":"old","activity":{"state":"working","epoch":"daemon","revision":1,"validForMs":30000}});
        let new = json!({"id":"agent","sessionId":"new","activity":{"state":"idle","epoch":"daemon","revision":2,"validForMs":0}});
        let first = agent_from("m", &old, None);
        let replacement = agent_from("m", &new, Some(&first));
        let late = agent_from("m", &old, Some(&replacement));
        assert_eq!(late.session_id, "new"); assert!(!late.working);
    }
    #[test]
    fn unavailable_activity_is_neither_working_nor_done() {
        let row = json!({"id":"agent","sessionId":"s","activity":{"state":"unknown","epoch":"daemon","revision":1,"validForMs":0}});
        let agent = agent_from("m", &row, None);
        assert_eq!(agent.state(None), State::Unknown); assert!(!agent.unread);
    }
}