Skip to content

The design language that makes your AI harness better at design.

JavaScript
43.4 KB
Raw Blame
//! `impeccable live-generate`: agent-initiated element targeting for the
//! `generate` command.
//!
//! Asks the live overlay to find an element by CSS selector, scroll to it,
//! enter the picked state, and fire the normal Go pipeline with the given
//! action and count. On success the browser starts a standard generate
//! session and the verb collects that session's `generate` event into its
//! own output, so the agent's next move is the edit. With `--boot` it runs
//! the lane's boot itself first (reusing a running helper), and with
//! `--open` it opens the dev URL in the browser when no page is connected:
//! one command from a cold project to a leased generate event.

use crate::live_resume::self_cmd;
use crate::paths::read_live_server_info;
use crate::roots::enter_live_root;
use crate::util::println;
use crate::vocabulary::VISUAL_ACTIONS;
use impeccable_common::Io;
use serde_json::{json, Map, Value};
use std::time::{Duration, Instant};

const HELP: &str = "Usage: impeccable live-generate --selector <css> [--text <snippet>] [--index <n>] [--action <name>] [--count <n>] [--prompt <text>] [--dry-run] [--wait-for-browser <ms>] [--no-live-bar] [--boot] [--open] [--target <path>]

Flags:
  --boot             optional; run the generate lane's boot first (impeccable live
                     --allow-missing-context --dev-url --no-live-bar, with --target
                     when given), reusing a running helper; the boot's context and
                     devUrl ride along in the output as `boot`
  --open             optional; when no page with the overlay is connected, open the
                     dev URL in the browser (IMPECCABLE_BROWSER, then `browser` in
                     .impeccable/config.local.json or config.json, then BROWSER, then
                     the platform opener) and wait for it (60 s unless
                     --wait-for-browser says otherwise). On a harness with its own
                     browser (Cursor, Claude Code) the flag is ignored unless
                     IMPECCABLE_BROWSER or the config's `browser` names one: the
                     page comes from the harness browser, never a second window
  --target <path>    optional; the file that renders the element (the boot's --target)
  --dev-url <url>    optional; the dev server you already know (a server the
                     harness runs, a tab on the app, the user's message); probed
                     first, reported as devUrl either way
  --selector <css>   required; resolved with document.querySelectorAll
  --text <snippet>   optional; keeps only matches whose textContent contains it
  --index <n>        optional; 1-based pick among the remaining matches
  --action <name>    optional; one of the live action vocabulary (default: impeccable)
  --count <n>        optional; variants to request, 1-8 (default: 3)
  --prompt <text>    optional; freeform direction, same as typing before Go
  --dry-run          optional; resolve and report without starting anything
  --wait-for-browser <ms>  optional; poll the helper until a page with the
                     overlay connects (or the budget runs out) before sending
                     the target.

With no page connected and neither --open nor --wait-for-browser, the verdict
is browser_needed with devUrl and the harness's way to open it (Cursor
browser_navigate, Claude Code's Browser pane, Codex: --open or the user), so no
second browser is ever launched behind a harness that has one.

On success the output carries the session's generate event as `event` (already
leased, with its _instructions), so the next command is the edit, then
`live-poll --reply <id> done --file <path> --then-poll` for the accept.
";

/// Client-side cap just above the server's 15s hold, so a hung helper still
/// fails fast.
const REQUEST_TIMEOUT_MS: u64 = 20_000;

struct Flags {
    values: Map<String, Value>,
    dry_run: bool,
    no_live_bar: bool,
    boot: bool,
    open: bool,
}

fn parse_flags(argv: &[String]) -> Result<Flags, Value> {
    let mut values = Map::new();
    let mut dry_run = false;
    let mut no_live_bar = false;
    let mut boot = false;
    let mut open = false;
    let mut i = 0;
    while i < argv.len() {
        let arg = &argv[i];
        if !arg.starts_with("--") {
            i += 1;
            continue;
        }
        let key = &arg[2..];
        if key == "dry-run" {
            dry_run = true;
            i += 1;
            continue;
        }
        if key == "no-live-bar" {
            no_live_bar = true;
            i += 1;
            continue;
        }
        if key == "boot" {
            boot = true;
            i += 1;
            continue;
        }
        if key == "open" {
            open = true;
            i += 1;
            continue;
        }
        // The boot's own opt-in, tolerated here so a caller that spells the
        // lane's boot flags on this verb is not refused.
        if key == "allow-missing-context" {
            i += 1;
            continue;
        }
        // `--dev-url` alone is the boot's probe flag (tolerated); with a
        // value it is the dev server the caller already knows.
        if key == "dev-url" {
            match argv.get(i + 1) {
                Some(v) if !v.starts_with("--") => {
                    values.insert(key.to_string(), json!(v));
                    i += 2;
                }
                _ => i += 1,
            }
            continue;
        }
        match argv.get(i + 1) {
            Some(v) if !v.starts_with("--") => {
                values.insert(key.to_string(), json!(v));
                i += 2;
            }
            _ => {
                return Err(json!({ "ok": false, "error": "missing_flag_value", "flag": arg }));
            }
        }
    }
    Ok(Flags {
        values,
        dry_run,
        no_live_bar,
        boot,
        open,
    })
}

fn flag<'a>(flags: &'a Flags, key: &str) -> Option<&'a str> {
    flags.values.get(key).and_then(Value::as_str)
}

/// JS `Number(v)` then `Number.isInteger`: an integer literal only.
fn int_flag(v: &str) -> Option<i64> {
    let t = v.trim();
    if t.is_empty() {
        return None;
    }
    if let Ok(i) = t.parse::<i64>() {
        return Some(i);
    }
    t.parse::<f64>()
        .ok()
        .filter(|f| f.is_finite() && f.fract() == 0.0)
        .map(|f| f as i64)
}

fn print_json(io: &mut Io, v: &Value) {
    println(io, &serde_json::to_string_pretty(v).unwrap_or_default());
}

fn fail(io: &mut Io, v: Value) -> i32 {
    print_json(io, &v);
    1
}

/// The follow-up the agent runs after each verdict. Like the poll loop's
/// `_instructions`, regenerated locally from the verdict, never taken from
/// the wire.
fn instructions_for(result: &Map<String, Value>, self_cmd: &str) -> Option<String> {
    let s = |k: &str| result.get(k).and_then(Value::as_str).unwrap_or("").to_string();
    let n = |k: &str| result.get(k).and_then(Value::as_i64).unwrap_or(0);
    if result.get("ok").and_then(Value::as_bool) == Some(true) {
        if result.get("dryRun").and_then(Value::as_bool) == Some(true) {
            let el = result.get("element").and_then(Value::as_object);
            let tag = el.and_then(|e| e.get("tag")).and_then(Value::as_str).unwrap_or("");
            let id = el
                .and_then(|e| e.get("id"))
                .and_then(Value::as_str)
                .filter(|i| !i.is_empty())
                .map(|i| format!("#{}", i))
                .unwrap_or_default();
            return Some(format!(
                "Dry run only: the selector resolves to one element ({}{}) and no session was started. Rerun without --dry-run to generate.",
                tag, id
            ));
        }
        let reply = format!("{} live-poll --reply {} done --file <project-root-relative path you wrote> --then-poll", self_cmd, s("sessionId"));
        if result.get("event").map(|e| e.is_object()).unwrap_or(false) {
            return Some(format!(
                "Session {} started: the browser scrolled to the target and fired Go (action \"{}\", count {}). Its generate event is in this output as `event`, already leased: handle it exactly per live.md's Handle generate, as event._instructions say (the action's reference, section 4 planning, knobs per section 7, all variants in ONE edit at the scaffold's splice). When the edit is written, reply and wait for the user's choice in one call: {}. The accept it returns carbonizes like plain live's: finish live.md's Required after accept, run live-complete, then stop the helper.",
                s("sessionId"), s("action"), n("count"), reply
            ));
        }
        return Some(format!(
            "Session {} started: the browser scrolled to the target and fired Go (action \"{}\", count {}). Its generate event had not arrived yet: run {} live-poll to collect it and handle it exactly per live.md's Handle generate, as its _instructions say; then reply and wait for the accept in one call: {}.",
            s("sessionId"), s("action"), n("count"), self_cmd, reply
        ));
    }
    let text = match s("error").as_str() {
        "dev_server_gone" => format!(
            "The dev server at {} stopped answering while this command waited for the page, so no page can load the overlay from it (a server another chat or session started dies with it). {}",
            s("devUrl"),
            start_dev_server_hint(&s("harness"))
        ),
        "no_dev_server" => format!("No dev server is serving this app: none of the usual ports answered with the page carrying the helper's tag (pass --dev-url <url> when you know where it runs). {}", start_dev_server_hint(&s("harness"))),
        "browser_needed" => format!("{}The helper is up and no page is connected yet. {} Then rerun this exact command with --wait-for-browser 60000.", open_ignored_note(result), open_in_harness_hint(&s("harness"), &s("devUrl"), self_cmd)),
        "browser_open_failed" => format!("The browser could not be launched ({}). Open {} yourself with your harness browser tool, or give the user the URL, then rerun this command with --wait-for-browser 120000.", s("detail"), s("url")),
        "no_browser_connected" if result.get("opened").map(|o| o.is_object()).unwrap_or(false) => format!("The page was opened in the browser but no overlay connected within {} ms. The dev server may still be compiling, or the page does not carry the injected tag (check pageFiles). Reload the page, then rerun this command.", n("waitedMs")),
        "no_browser_connected" if !s("devUrl").is_empty() => format!("{}No page with the live overlay connected within {} ms. {} Then rerun this exact command with --wait-for-browser 60000.", open_ignored_note(result), n("waitedMs"), open_in_harness_hint(&s("harness"), &s("devUrl"), self_cmd)),
        "no_browser_connected" => "No page with the live overlay is connected. Open the app URL that serves a pageFiles entry yourself with your harness browser tool, then rerun this command. Only when no browser tool exists: give the user the URL and rerun with --wait-for-browser 120000 so the command fires as soon as they open the page.".to_string(),
        "browser_timeout" => "The overlay did not answer in time, and no session was started for this request (a Go that lands late is refused). The page may be mid-reload: reload the app page, then rerun this command.".to_string(),
        "invalid_selector" => "The selector is not valid CSS. Fix the selector syntax and rerun.".to_string(),
        "no_match" => {
            if n("rawMatchCount") > 0 {
                format!("The selector hit {} node(s) but none is pickable (too small, chrome, or filtered by --text). Target a larger element or adjust --text.", n("rawMatchCount"))
            } else {
                "The selector matched nothing on the open page. Derive a better selector from the page source (an id, a unique class, or a landmark), or add --text with a snippet of the element's visible text.".to_string()
            }
        }
        "ambiguous" => format!("The selector matched {} elements. Either target their common container instead, or disambiguate with --text \"<visible text>\" or --index <1-based position>. The candidates are listed in this output.", n("matchCount")),
        "index_out_of_range" => format!("--index is out of range: only {} match(es). Use an index from 1 to {}.", n("matchCount"), n("matchCount")),
        "busy" => {
            if s("reason") == "agent_target_in_flight" {
                "That tab is already acting on another generate request. Handle that request's pending event in your poll loop, or wait for its session to end, then rerun.".to_string()
            } else {
                format!("A live session is already mid-flight (browser state {}). Let the user finish or discard it in the browser, or handle the pending event in your poll loop, then rerun.", s("state"))
            }
        }
        "go_failed" => format!("The overlay could not start generation from the picked state (browser state {}). Reload the app page and rerun this command.", s("state")),
        "server_stopping" => format!("The live helper server is shutting down. Re-run the live boot ({} live), reopen the page, then rerun this command.", self_cmd),
        _ => return None,
    };
    Some(text)
}

/// Said first when `--open` was passed on a harness with its own browser.
fn open_ignored_note(result: &Map<String, Value>) -> &'static str {
    if result.get("openIgnored").is_some() {
        "--open was ignored: this harness has its own browser, and a second window is exactly what the lane avoids. "
    } else {
        ""
    }
}

/// How this harness opens a page: its own browser when it has one (no second
/// browser behind it), the system browser or the user otherwise.
fn open_in_harness_hint(harness: &str, dev_url: &str, self_cmd: &str) -> String {
    let _ = self_cmd;
    match harness {
        "cursor" => format!("Open {} with browser_navigate (Cursor's browser; it reuses the tab already on that origin).", dev_url),
        "claude-code" => format!("Open {} in the Browser pane: navigate the tab already on that origin (tabs_context lists them), or preview_start with that URL when the pane is closed.", dev_url),
        "codex" => format!("Codex has no browser tool: rerun this command with --open (the system browser opens {}), or give the user that URL.", dev_url),
        _ => format!("Open {} with your harness's browser tool, reusing a tab already on that origin; without one, rerun this command with --open (the system browser), or give the user that URL.", dev_url),
    }
}

/// Where a dev server gets started in this harness, so the one already
/// running there is the one the page comes from.
fn start_dev_server_hint(harness: &str) -> String {
    match harness {
        "claude-code" => "Start it the way the harness runs servers (preview_start with the project's dev configuration, or the dev script in a background shell), wait for its URL, then rerun this exact command with --dev-url <that url>; never kill or restart that server afterwards.".to_string(),
        "cursor" => "Start the project's dev script in a background terminal (npm run dev or the framework's equivalent), wait for it to print its URL, then rerun this exact command with --dev-url <that url>; never kill or restart that server afterwards.".to_string(),
        _ => "Start the project's dev script in a background terminal (npm run dev or the framework's equivalent), wait for it to print its URL, then rerun this exact command with --dev-url <that url>; never kill or restart that server afterwards.".to_string(),
    }
}

fn server_died(self_cmd: &str, detail: Option<String>, waiting: bool) -> Value {
    let mut v = Map::new();
    v.insert("ok".into(), json!(false));
    v.insert("error".into(), json!("server_unreachable"));
    if let Some(d) = detail {
        v.insert("detail".into(), json!(d));
    }
    let text = if waiting {
        format!("The recorded live server did not answer while waiting for a browser; it likely died. Re-run the live boot ({} live), reopen the app page, then rerun this command.", self_cmd)
    } else {
        format!("The recorded live server did not answer; it likely died. Re-run the live boot ({} live), reopen the app page, then rerun this command.", self_cmd)
    };
    v.insert("_instructions".into(), json!(text));
    Value::Object(v)
}

fn server_not_running(self_cmd: &str) -> Value {
    json!({
        "ok": false,
        "error": "server_not_running",
        "_instructions": format!("No live helper server is recorded for this project. Run the live boot first ({} live), open the app URL that serves a pageFiles entry, then rerun this command.", self_cmd),
    })
}

/// The lane's boot flags, run in-process from the caller's original cwd
/// (`--target` is a path relative to it). Ok: the boot payload. Err: a
/// verdict to print, exit 1.
fn run_boot(args: &[String], original_cwd: &std::path::Path, io: &Io, dev_url_hint: Option<&str>) -> Result<Map<String, Value>, Value> {
    let mut boot_args: Vec<String> = Vec::new();
    if let Some(i) = args.iter().position(|a| a == "--target") {
        if let Some(t) = args.get(i + 1).filter(|t| !t.starts_with("--")) {
            boot_args.push("--target".into());
            boot_args.push(t.clone());
        }
    }
    for a in args {
        if let Some(t) = a.strip_prefix("--target=") {
            boot_args.push("--target".into());
            boot_args.push(t.to_string());
        }
    }
    boot_args.push("--allow-missing-context".into());
    boot_args.push("--dev-url".into());
    boot_args.push("--no-live-bar".into());
    let mut env = io.env.clone();
    if let Some(hint) = dev_url_hint {
        // The known server first, the usual ports behind it, unless the
        // caller already narrowed the list.
        if !env.contains_key("IMPECCABLE_DEV_URL_CANDIDATES") {
            let mut list = vec![hint.trim_end_matches('/').to_string() + "/"];
            list.extend(crate::dev_url::candidates(None));
            env.insert("IMPECCABLE_DEV_URL_CANDIDATES".into(), list.join(","));
        }
    }
    let (mut child, captured) = Io::captured("", original_cwd.to_path_buf(), env);
    let code = crate::live_boot::run(&boot_args, &mut child);
    let out = String::from_utf8_lossy(&captured.stdout.borrow()).into_owned();
    let err = String::from_utf8_lossy(&captured.stderr.borrow()).into_owned();
    let payload: Option<Map<String, Value>> = serde_json::from_str::<Value>(out.trim())
        .ok()
        .and_then(|v| v.as_object().cloned());
    let Some(mut payload) = payload else {
        return Err(json!({
            "ok": false,
            "error": "boot_failed",
            "exitCode": code,
            "detail": if err.trim().is_empty() { out.trim().to_string() } else { err.trim().to_string() },
            "_instructions": "The live boot did not produce a verdict. Run `impeccable live --allow-missing-context --dev-url --no-live-bar` on its own, read its output, and fix what it names before rerunning this command.",
        }));
    };
    if payload.get("ok").and_then(Value::as_bool) != Some(true) {
        let error = payload.get("error").and_then(Value::as_str).unwrap_or("").to_string();
        let text = match error.as_str() {
            "config_missing" | "config_invalid" => "The live config is missing or invalid: follow reference/live-setup.md to create .impeccable/live/config.json, then rerun this command.",
            "target_selection_required" => "Several apps live here: ask the user which one, then rerun this command with --target <a file inside that app>.",
            "context_missing" => "The boot refused for missing context even though this verb asks it to proceed; rerun with the boot's own flags to see why.",
            _ => "The boot refused; its fields say why. Fix that, then rerun this command.",
        };
        payload.insert("ok".into(), json!(false));
        payload.insert("bootError".into(), json!(error));
        payload.insert("_instructions".into(), json!(text));
        return Err(Value::Object(payload));
    }
    Ok(payload)
}

/// What the verdict repeats from the boot: the context the edit needs and
/// where the page is. Plumbing (token, roots, drift) stays out.
fn boot_summary(boot: &Map<String, Value>) -> Value {
    let mut m = Map::new();
    for key in [
        "devUrl", "pageFiles", "projectRoot", "targetPath", "liveBarHidden", "contextMissing", "contextNote",
        "hasProduct", "product", "productPath", "hasDesign", "design", "designPath", "hasSurfaceBrief",
        "surfaceBrief", "surfaceBriefPath",
    ] {
        if let Some(v) = boot.get(key) {
            m.insert(key.into(), v.clone());
        }
    }
    Value::Object(m)
}

/// Collect the session's own generate event (`GET /poll?types=generate&id=`)
/// so the caller's next move is the edit. The event is leased exactly as a
/// poll would lease it; nothing else in the queue is touched.
fn fetch_generate_event(port: i64, token: &str, session_id: &str, budget: Duration, self_cmd: &str) -> Option<Value> {
    let deadline = Instant::now() + budget;
    while Instant::now() < deadline {
        let remaining = deadline.saturating_duration_since(Instant::now()).as_millis() as u64;
        let slice = remaining.clamp(1_000, 5_000);
        let url = format!(
            "http://127.0.0.1:{}/poll?token={}&timeout={}&leaseMs={}&types=generate&id={}",
            port,
            crate::live_poll::form_encode(token),
            slice,
            crate::live_poll::DEFAULT_EVENT_LEASE_MS,
            crate::live_poll::form_encode(session_id)
        );
        let agent = ureq::AgentBuilder::new()
            .timeout(Duration::from_millis(slice + 30_000))
            .build();
        let Ok(res) = agent.get(&url).call() else { return None };
        let Ok(mut event) = res.into_json::<Value>() else { return None };
        match event.get("type").and_then(Value::as_str) {
            Some("generate") => {
                if let Some(obj) = event.as_object_mut() {
                    match crate::instructions::instructions_for_event(obj, self_cmd) {
                        Some(text) if !text.is_empty() => {
                            obj.insert("_instructions".into(), json!(text));
                        }
                        _ => {
                            obj.remove("_instructions");
                        }
                    }
                }
                return Some(event);
            }
            Some("timeout") => continue,
            _ => return None,
        }
    }
    None
}

/// How long the verb waits for the generate event after a started session.
const EVENT_BUDGET_MS: u64 = 20_000;
/// The wait `--open` implies when `--wait-for-browser` was not given.
const OPEN_WAIT_MS: u64 = 60_000;

pub fn run(args: &[String], io: &mut Io) -> i32 {
    if args.iter().any(|a| a == "--help" || a == "-h") {
        println(io, HELP);
        return 0;
    }
    let flags_probe = match parse_flags(args) {
        Ok(f) => f,
        Err(v) => return fail(io, v),
    };
    // `--boot` runs before the root switch: the boot writes the roots
    // manifest the switch reads, and reads --target relative to this cwd.
    let original_cwd = io.cwd.clone();
    let dev_url_hint: Option<String> = flag(&flags_probe, "dev-url").map(str::trim).filter(|u| !u.is_empty()).map(str::to_string);
    let mut boot: Option<Map<String, Value>> = None;
    if flags_probe.boot {
        match run_boot(args, &original_cwd, io, dev_url_hint.as_deref()) {
            Ok(b) => boot = Some(b),
            Err(v) => return fail(io, v),
        }
    }
    let mut argv: Vec<String> = args.to_vec();
    if let Err(code) = enter_live_root(&mut argv, io) {
        return code;
    }
    let cwd = io.cwd.to_string_lossy().into_owned();
    let env = io.env.clone();
    let me = self_cmd(io);
    let flags = match parse_flags(&argv) {
        Ok(f) => f,
        Err(v) => return fail(io, v),
    };

    let selector = flag(&flags, "selector").map(str::trim).unwrap_or("").to_string();
    if selector.is_empty() {
        return fail(io, json!({
            "ok": false,
            "error": "selector_required",
            "_instructions": "Pass --selector with a CSS selector for the element to target. Derive it from the page source: prefer an id, a unique class, or a landmark section, and add --text \"<visible text>\" when the class repeats.",
        }));
    }
    let action = flag(&flags, "action").unwrap_or("impeccable").to_string();
    if !VISUAL_ACTIONS.contains(&action.as_str()) {
        return fail(io, json!({
            "ok": false,
            "error": "invalid_action",
            "action": action,
            "validActions": VISUAL_ACTIONS,
            "_instructions": "Map the request wording onto the closest listed action (bold -> bolder, quiet/calmer -> quieter, simplify -> distill). When no action fits, use --action impeccable and carry the wording via --prompt.",
        }));
    }
    let count = match flag(&flags, "count") {
        None => 3,
        Some(raw) => match int_flag(raw) {
            Some(c) if (1..=8).contains(&c) => c,
            _ => {
                return fail(io, json!({ "ok": false, "error": "invalid_count", "count": raw, "_instructions": "Pass --count as an integer from 1 to 8." }));
            }
        },
    };
    let index = match flag(&flags, "index") {
        None => None,
        Some(raw) => match int_flag(raw) {
            Some(i) if i >= 1 => Some(i),
            _ => {
                return fail(io, json!({ "ok": false, "error": "invalid_index", "index": raw, "_instructions": "Pass --index as a 1-based integer position among the matches." }));
            }
        },
    };
    let mut wait_for_browser_ms = match flag(&flags, "wait-for-browser") {
        None => 0,
        Some(raw) => match int_flag(raw) {
            Some(ms) if ms >= 1 => ms as u64,
            _ => {
                return fail(io, json!({ "ok": false, "error": "invalid_wait", "wait": raw, "_instructions": "Pass --wait-for-browser as a positive integer of milliseconds, e.g. --wait-for-browser 120000." }));
            }
        },
    };

    let Some((info, _)) = read_live_server_info(&cwd, &env) else {
        return fail(io, server_not_running(&me));
    };
    let port = info.raw.get("port").and_then(Value::as_i64);
    let token = info.raw.get("token").and_then(Value::as_str).map(str::to_string);
    let (Some(port), Some(token)) = (port, token) else {
        return fail(io, server_not_running(&me));
    };
    let harness = impeccable_context::provider::detect(&env, &cwd).id;
    // Every verdict from here on repeats what the boot found, so a refusal
    // still hands the caller its context and dev URL.
    let with_boot = |mut v: Map<String, Value>| -> Value {
        if let Some(b) = &boot {
            v.insert("boot".into(), boot_summary(b));
        }
        v.insert("harness".into(), json!(harness));
        Value::Object(v)
    };

    // Where the page is: the boot's probe, else a probe led by the caller's
    // hint, else the hint itself (a server the harness runs that answers
    // without our tag yet, before its first reload).
    let resolve_dev_url = |boot: &Option<Map<String, Value>>| -> (Option<String>, bool) {
        if let Some(u) = boot.as_ref().and_then(|b| b.get("devUrl")).and_then(Value::as_str).filter(|u| !u.is_empty()) {
            return (Some(u.to_string()), true);
        }
        let mut candidates: Vec<String> = Vec::new();
        if let Some(h) = &dev_url_hint {
            candidates.push(h.trim_end_matches('/').to_string() + "/");
        }
        candidates.extend(crate::dev_url::candidates(env.get("IMPECCABLE_DEV_URL_CANDIDATES").map(String::as_str)));
        if let Some(u) = crate::dev_url::probe(&candidates, &token) {
            return (Some(u), true);
        }
        (dev_url_hint.clone(), false)
    };

    // A harness with its own browser never gets a second window from this
    // verb: `--open` there is ignored unless the user chose a browser
    // explicitly (IMPECCABLE_BROWSER or the config's `browser`; the generic
    // BROWSER variable is not that choice).
    let harness_has_browser = matches!(harness.as_str(), "cursor" | "claude-code");
    let open_ignored = flags.open && harness_has_browser && crate::browser_open::explicit_browser(&cwd, &env).is_none();
    let open = flags.open && !open_ignored;
    let with_open_note = |mut v: Map<String, Value>| -> Map<String, Value> {
        if open_ignored {
            v.insert("openIgnored".into(), json!("harness browser"));
        }
        v
    };

    // Nothing connected, nothing asked to open, nothing to wait for: the
    // caller opens the page itself (its harness's browser, never a second
    // one behind it) and comes back.
    let mut opened: Option<Value> = None;
    if !open && wait_for_browser_ms == 0 && !flags.dry_run {
        let Some(status) = crate::server::fetch_status(port, &token) else {
            return fail(io, server_died(&me, None, false));
        };
        if status.get("connectedClients").and_then(Value::as_i64).unwrap_or(0) == 0 {
            let (dev_url, verified) = resolve_dev_url(&boot);
            let mut v = Map::new();
            v.insert("ok".into(), json!(false));
            if let Some(u) = dev_url {
                v.insert("error".into(), json!("browser_needed"));
                v.insert("devUrl".into(), json!(u));
                v.insert("devUrlVerified".into(), json!(verified));
            } else {
                v.insert("error".into(), json!("no_dev_server"));
            }
            v.insert("harness".into(), json!(harness));
            let mut v = with_open_note(v);
            let text = instructions_for(&v, &me).unwrap_or_default();
            v.insert("_instructions".into(), json!(text));
            return fail(io, with_boot(v));
        }
    }

    // `--open`: hand the page to the browser when nothing is connected yet.
    if open {
        let Some(status) = crate::server::fetch_status(port, &token) else {
            return fail(io, server_died(&me, None, false));
        };
        let connected = status.get("connectedClients").and_then(Value::as_i64).unwrap_or(0) > 0;
        if !connected {
            let (dev_url, _) = resolve_dev_url(&boot);
            let Some(url) = dev_url else {
                let mut v = Map::new();
                v.insert("ok".into(), json!(false));
                v.insert("error".into(), json!("no_dev_server"));
                v.insert("harness".into(), json!(harness));
                let text = instructions_for(&v, &me).unwrap_or_default();
                v.insert("_instructions".into(), json!(text));
                return fail(io, with_boot(v));
            };
            match crate::browser_open::open_url(&url, &cwd, &env) {
                Ok(via) => {
                    opened = Some(json!({ "url": url, "via": via }));
                    if wait_for_browser_ms == 0 {
                        wait_for_browser_ms = OPEN_WAIT_MS;
                    }
                }
                Err(detail) => {
                    let mut v = Map::new();
                    v.insert("ok".into(), json!(false));
                    v.insert("error".into(), json!("browser_open_failed"));
                    v.insert("url".into(), json!(url));
                    v.insert("detail".into(), json!(detail));
                    let text = instructions_for(&v, &me).unwrap_or_default();
                    v.insert("_instructions".into(), json!(text));
                    return fail(io, with_boot(v));
                }
            }
        }
    }

    if wait_for_browser_ms > 0 {
        let deadline = Instant::now() + Duration::from_millis(wait_for_browser_ms);
        // No page can load the overlay from a dead dev server, so the wait
        // watches the one this command knows (the URL it opened, else the
        // boot's or the caller's) and ends the moment it stops answering,
        // instead of running out the budget on a page that will never
        // reload. Two misses in a row, so a server mid-restart gets a grace.
        let watched_dev_url: Option<String> = opened
            .as_ref()
            .and_then(|o| o.get("url"))
            .and_then(Value::as_str)
            .map(String::from)
            .or_else(|| resolve_dev_url(&boot).0);
        let started = Instant::now();
        let mut ticks: u32 = 0;
        let mut dev_misses: u32 = 0;
        loop {
            let Some(status) = crate::server::fetch_status(port, &token) else {
                return fail(io, server_died(&me, None, true));
            };
            if status.get("connectedClients").and_then(Value::as_i64).unwrap_or(0) > 0 {
                break;
            }
            if let Some(url) = &watched_dev_url {
                ticks += 1;
                if ticks % 3 == 0 {
                    if crate::dev_url::answers(url) {
                        dev_misses = 0;
                    } else {
                        dev_misses += 1;
                    }
                    if dev_misses >= 2 {
                        let mut v = Map::new();
                        v.insert("ok".into(), json!(false));
                        v.insert("error".into(), json!("dev_server_gone"));
                        v.insert("devUrl".into(), json!(url));
                        v.insert("waitedMs".into(), json!(started.elapsed().as_millis() as u64));
                        v.insert("harness".into(), json!(harness));
                        let mut v = with_open_note(v);
                        let text = instructions_for(&v, &me).unwrap_or_default();
                        v.insert("_instructions".into(), json!(text));
                        return fail(io, with_boot(v));
                    }
                }
            }
            if Instant::now() >= deadline {
                let mut v = Map::new();
                v.insert("ok".into(), json!(false));
                v.insert("error".into(), json!("no_browser_connected"));
                v.insert("waitedMs".into(), json!(wait_for_browser_ms));
                if let Some(o) = &opened {
                    v.insert("opened".into(), o.clone());
                } else if let (Some(u), _) = resolve_dev_url(&boot) {
                    v.insert("devUrl".into(), json!(u));
                }
                v.insert("harness".into(), json!(harness));
                let mut v = with_open_note(v);
                let text = instructions_for(&v, &me).unwrap_or_default();
                v.insert("_instructions".into(), json!(text));
                return fail(io, with_boot(v));
            }
            std::thread::sleep(Duration::from_millis(1_000));
        }
    }

    let mut body = Map::new();
    body.insert("token".into(), json!(token));
    body.insert("selector".into(), json!(selector));
    body.insert("action".into(), json!(action));
    body.insert("count".into(), json!(count));
    if let Some(text) = flag(&flags, "text").filter(|t| !t.is_empty()) {
        body.insert("text".into(), json!(text));
    }
    if let Some(i) = index {
        body.insert("index".into(), json!(i));
    }
    if let Some(prompt) = flag(&flags, "prompt").filter(|p| !p.is_empty()) {
        body.insert("prompt".into(), json!(prompt));
    }
    if flags.dry_run {
        body.insert("dryRun".into(), json!(true));
    }
    if flags.no_live_bar || flags.boot {
        body.insert("hideLiveBar".into(), json!(true));
    }

    let url = format!("http://127.0.0.1:{}/agent-target", port);
    let agent = ureq::AgentBuilder::new()
        .timeout(Duration::from_millis(REQUEST_TIMEOUT_MS))
        .build();
    let sent = agent
        .post(&url)
        .set("Content-Type", "application/json")
        .send_string(&serde_json::to_string(&Value::Object(body)).unwrap_or_default());
    let (status, result) = match sent {
        Ok(res) => {
            let status = res.status();
            match res.into_json::<Value>() {
                Ok(v) => (status, v),
                Err(_) => return fail(io, json!({ "ok": false, "error": "bad_server_response", "status": status })),
            }
        }
        Err(ureq::Error::Status(status, res)) => match res.into_json::<Value>() {
            Ok(v) => (status, v),
            Err(_) => return fail(io, json!({ "ok": false, "error": "bad_server_response", "status": status })),
        },
        Err(ureq::Error::Transport(t)) => {
            let detail = t.to_string();
            let lower = detail.to_ascii_lowercase();
            if lower.contains("timed out") || lower.contains("timeout") {
                let mut v = Map::new();
                v.insert("ok".into(), json!(false));
                v.insert("error".into(), json!("request_timeout"));
                v.insert("detail".into(), json!(detail));
                let mut probe = Map::new();
                probe.insert("error".into(), json!("browser_timeout"));
                let text = instructions_for(&probe, &me).unwrap_or_default();
                v.insert("_instructions".into(), json!(text));
                return fail(io, Value::Object(v));
            }
            return fail(io, server_died(&me, Some(detail), false));
        }
    };
    let mut fields = result.as_object().cloned().unwrap_or_default();
    if !(200..300).contains(&status) {
        let mut v = Map::new();
        v.insert("ok".into(), json!(false));
        let code = fields
            .get("error")
            .and_then(Value::as_str)
            .map(str::to_string)
            .unwrap_or_else(|| format!("http_{}", status));
        v.insert("error".into(), json!(code));
        for (k, val) in fields {
            if k != "ok" && k != "error" {
                v.insert(k, val);
            }
        }
        return fail(io, with_boot(v));
    }
    let ok = fields.get("ok").and_then(Value::as_bool) == Some(true);
    let dry_run = fields.get("dryRun").and_then(Value::as_bool) == Some(true);
    if let Some(b) = &boot {
        fields.insert("boot".into(), boot_summary(b));
    }
    if let Some(o) = &opened {
        fields.insert("opened".into(), o.clone());
    }
    if ok && !dry_run {
        let session_id = fields.get("sessionId").and_then(Value::as_str).map(str::to_string);
        if let Some(sid) = session_id.filter(|s| !s.is_empty()) {
            let event = fetch_generate_event(port, &token, &sid, Duration::from_millis(EVENT_BUDGET_MS), &me);
            fields.insert("event".into(), event.unwrap_or(Value::Null));
        }
    }
    if let Some(text) = instructions_for(&fields, &me) {
        fields.insert("_instructions".into(), json!(text));
    }
    print_json(io, &Value::Object(fields));
    if ok {
        0
    } else {
        1
    }
}

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

    fn busy(reason: &str) -> Map<String, Value> {
        let mut m = Map::new();
        m.insert("ok".into(), json!(false));
        m.insert("error".into(), json!("busy"));
        m.insert("state".into(), json!("CONFIGURING"));
        m.insert("reason".into(), json!(reason));
        m
    }

    #[test]
    fn no_live_bar_is_a_boolean_flag() {
        let flags = parse_flags(&["--selector".to_string(), "h1".to_string(), "--no-live-bar".to_string(), "--count".to_string(), "3".to_string()]).unwrap();
        assert!(flags.no_live_bar);
        assert_eq!(flags.values.get("selector").and_then(Value::as_str), Some("h1"));
        assert_eq!(flags.values.get("count").and_then(Value::as_str), Some("3"));
        assert!(!parse_flags(&["--selector".to_string(), "h1".to_string()]).unwrap().no_live_bar);
    }

    #[test]
    fn dev_url_takes_a_value_and_still_works_bare() {
        let with = parse_flags(&["--dev-url".to_string(), "http://127.0.0.1:5173/".to_string(), "--selector".to_string(), "h1".to_string()]).unwrap();
        assert_eq!(with.values.get("dev-url").and_then(Value::as_str), Some("http://127.0.0.1:5173/"));
        let bare = parse_flags(&["--dev-url".to_string(), "--selector".to_string(), "h1".to_string()]).unwrap();
        assert!(bare.values.get("dev-url").is_none());
        assert_eq!(bare.values.get("selector").and_then(Value::as_str), Some("h1"));
    }

    #[test]
    fn a_dev_server_that_dies_mid_wait_gets_the_start_it_instructions() {
        let mut m = Map::new();
        m.insert("error".into(), json!("dev_server_gone"));
        m.insert("devUrl".into(), json!("http://127.0.0.1:5173/"));
        m.insert("harness".into(), json!("cursor"));
        let text = instructions_for(&m, "impeccable").unwrap();
        assert!(text.contains("stopped answering"), "{text}");
        assert!(text.contains("http://127.0.0.1:5173/"), "{text}");
        assert!(text.contains("background terminal") && text.contains("--dev-url"), "{text}");
    }

    #[test]
    fn browser_needed_names_the_harness_browser_and_never_a_second_one() {
        let mut m = Map::new();
        m.insert("ok".into(), json!(false));
        m.insert("error".into(), json!("browser_needed"));
        m.insert("devUrl".into(), json!("http://127.0.0.1:5173/"));
        m.insert("harness".into(), json!("cursor"));
        let cursor = instructions_for(&m, "impeccable").unwrap();
        assert!(cursor.contains("browser_navigate"), "{cursor}");
        assert!(cursor.contains("--wait-for-browser 60000"), "{cursor}");
        assert!(!cursor.contains("--open"), "a harness with a browser is never told to open a second one: {cursor}");
        m.insert("harness".into(), json!("claude-code"));
        let claude = instructions_for(&m, "impeccable").unwrap();
        assert!(claude.contains("Browser pane") && claude.contains("navigate") && claude.contains("preview_start"), "{claude}");
        assert!(!claude.contains("--open"), "{claude}");
        m.insert("harness".into(), json!("codex"));
        let codex = instructions_for(&m, "impeccable").unwrap();
        assert!(codex.contains("--open") && codex.contains("give the user"), "{codex}");
        m.insert("harness".into(), json!("source"));
        let other = instructions_for(&m, "impeccable").unwrap();
        assert!(other.contains("browser tool") && other.contains("--open"), "{other}");
    }

    #[test]
    fn an_ignored_open_says_so_before_the_harness_hint() {
        let mut m = Map::new();
        m.insert("ok".into(), json!(false));
        m.insert("error".into(), json!("browser_needed"));
        m.insert("devUrl".into(), json!("http://127.0.0.1:5173/"));
        m.insert("harness".into(), json!("cursor"));
        m.insert("openIgnored".into(), json!("harness browser"));
        let text = instructions_for(&m, "impeccable").unwrap();
        assert!(text.starts_with("--open was ignored"), "{text}");
        assert!(text.contains("browser_navigate"), "{text}");
    }

    #[test]
    fn a_missing_dev_server_points_at_the_harness_way_to_start_one() {
        let mut m = Map::new();
        m.insert("ok".into(), json!(false));
        m.insert("error".into(), json!("no_dev_server"));
        m.insert("harness".into(), json!("claude-code"));
        let text = instructions_for(&m, "impeccable").unwrap();
        assert!(text.contains("preview_start") && text.contains("--dev-url"), "{text}");
        m.insert("harness".into(), json!("cursor"));
        let text = instructions_for(&m, "impeccable").unwrap();
        assert!(text.contains("background terminal") && text.contains("--dev-url"), "{text}");
    }

    #[test]
    fn timeout_instructions_promise_no_stray_session() {
        let mut m = Map::new();
        m.insert("ok".into(), json!(false));
        m.insert("error".into(), json!("browser_timeout"));
        let text = instructions_for(&m, "impeccable").unwrap();
        assert!(text.contains("no session was started"), "{text}");
    }

    #[test]
    fn busy_instructions_tell_the_agent_whose_session_is_in_the_way() {
        let own = instructions_for(&busy("agent_target_in_flight"), "impeccable").unwrap();
        assert!(own.contains("already acting on another generate request"), "{own}");
        let user = instructions_for(&busy("session_active"), "impeccable").unwrap();
        assert!(user.contains("browser state CONFIGURING"), "{user}");
    }
}