agentmux_launcher/

main.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

// AgentMux Launcher — Sets DLL search path then spawns srv + the CEF host.
//
// Phase B.1: launcher now spawns srv directly (sibling of host) so srv
// survives host crashes. Both children are assigned to the launcher's
// Job Object J0 with KILL_ON_JOB_CLOSE; killing the launcher reaps
// the entire tree atomically via the OS.
//
// This was previously a tiny sync wrapper that just SetDllDirectoryW'd
// runtime/ then spawned the CEF host. Phase B grew it into the
// privileged owner per
// specs/SPEC_WINDOW_PROCESS_STATE_MACHINE_2026_04_27.md.
//
// Process tree after B.1:
//   launcher (J0)
//     ├── srv     (assigned to J0; survives host crash)
//     └── host    (assigned to J0; CEF render workers inherit J0)

#![cfg_attr(
    all(not(debug_assertions), target_os = "windows"),
    windows_subsystem = "windows"
)]

mod config;
mod data_dir;
mod diag;
mod event_log;
mod hash;
mod host_pipe;
mod ipc;
mod reducer;
mod saga;
#[cfg(target_os = "windows")]
mod splash;
mod srv_spawner;
mod state;
mod wrr;

/// Suppress the Windows "Application Error" / WER crash dialog so an unhandled
/// fault terminates the process immediately instead of wedging it behind a
/// modal. No-op off Windows. Spec:
/// docs/specs/SPEC_SERVICE_SUPERVISION_AND_RECOVERY_2026_05_20.md.
#[cfg(target_os = "windows")]
fn suppress_os_crash_dialogs() {
    use windows_sys::Win32::System::Diagnostics::Debug::{SetErrorMode, SEM_FAILCRITICALERRORS};
    use windows_sys::Win32::System::ErrorReporting::{WerSetFlags, WER_FAULT_REPORTING_NO_UI};
    unsafe {
        // Suppress the WER crash-dialog UI WITHOUT disabling WER itself —
        // SEM_NOGPFAULTERRORBOX would also kill WER/LocalDumps crash-dump
        // collection, the postmortem diagnostics this stability work needs.
        // WER_FAULT_REPORTING_NO_UI is the documented "no UI, keep
        // reports" path.
        let _ = WerSetFlags(WER_FAULT_REPORTING_NO_UI);
        // SEM_FAILCRITICALERRORS suppresses the critical-error handler
        // (e.g. "no disk in drive" popups) — unrelated to crash reporting.
        SetErrorMode(SEM_FAILCRITICALERRORS);
    }
}

#[cfg(not(target_os = "windows"))]
fn suppress_os_crash_dialogs() {}

/// Process entry point. `suppress_os_crash_dialogs()` runs FIRST — before the
/// Tokio runtime is built. The runtime is built explicitly here (rather than
/// via `#[tokio::main]`, whose generated wrapper would construct it before any
/// of our code runs) so a fault during runtime construction can't surface the
/// Windows crash modal either. Spec:
/// docs/specs/SPEC_SERVICE_SUPERVISION_AND_RECOVERY_2026_05_20.md.
fn main() {
    suppress_os_crash_dialogs();
    tokio::runtime::Runtime::new()
        .expect("failed to build Tokio runtime")
        .block_on(launcher_main());
}

async fn launcher_main() {
    let exe_path = std::env::current_exe().expect("cannot resolve exe path");
    let exe_dir = exe_path.parent().expect("exe has no parent directory");
    let runtime_dir = exe_dir.join("runtime");

    log(&format!(
        "starting — exe={} runtime={}",
        exe_path.display(),
        runtime_dir.display()
    ));

    // Set DLL search path so libcef.dll (in runtime/) is found by the
    // CEF host's load-time linker. SetDllDirectoryW is process-local
    // and inherited by child processes — both srv (which doesn't
    // need libcef but harmless) and host (which absolutely does).
    #[cfg(target_os = "windows")]
    {
        use std::os::windows::ffi::OsStrExt;
        let wide: Vec<u16> = runtime_dir
            .as_os_str()
            .encode_wide()
            .chain(Some(0))
            .collect();
        unsafe {
            windows_sys::Win32::System::LibraryLoader::SetDllDirectoryW(wide.as_ptr());
        }
    }
    log("SetDllDirectoryW done");

    let args: Vec<String> = std::env::args().skip(1).collect();

    // LSD-3 — `agentmux.exe --diag sagas` is OFFLINE: it reads the
    // launcher saga SQLite log directly, with no IPC and no running
    // launcher. So it MUST run BEFORE the CEF runtime existence
    // check below — the offline-diagnostic value is most needed
    // exactly when the launcher won't start (e.g. corrupt runtime
    // folder). (codex P1 + reagent P1 PR #647 round 3.)
    if matches!(
        (args.first().map(String::as_str), args.get(1).map(String::as_str)),
        (Some("--diag"), Some("sagas"))
    ) {
        match diag::run_sagas_diag(exe_dir).await {
            Ok(()) => std::process::exit(0),
            Err(msg) => {
                eprintln!("--diag sagas failed: {}", msg);
                std::process::exit(1);
            }
        }
    }

    let real_exe = find_cef_binary(&runtime_dir);
    log(&format!("resolved CEF binary: {}", real_exe.display()));
    if !real_exe.exists() {
        log(&format!(
            "FATAL: CEF binary not found at {}",
            real_exe.display()
        ));
        eprintln!(
            "AgentMux runtime not found in: {}\nMake sure the runtime/ folder is intact.",
            runtime_dir.display()
        );
        std::process::exit(1);
    }

    log(&format!("forwarding {} CLI args to host", args.len()));

    // Phase B.8 — `agentmux.exe --diag wrr` and `--diag srv` Tool
    // clients. Connect to the running launcher (or srv) over IPC,
    // capture events for a short window, print summary, exit.
    // (Note: --diag sagas is handled above, before the CEF runtime
    // check, since it doesn't need IPC.)
    if matches!(args.first().map(String::as_str), Some("--diag")) {
        let topic = args.get(1).map(String::as_str).unwrap_or("");
        match topic {
            "wrr" => match diag::run_wrr_diag(exe_dir).await {
                Ok(()) => std::process::exit(0),
                Err(msg) => {
                    eprintln!("--diag wrr failed: {}", msg);
                    std::process::exit(1);
                }
            },
            // Phase E.7 — operator visibility into the srv reducer's
            // canonical state (workspaces / tabs / blocks / sagas) +
            // recent activity. Same `Tool` IPC pattern as `--diag wrr`,
            // talks to the srv pipe instead of the launcher pipe.
            "srv" => match diag::run_srv_diag(exe_dir).await {
                Ok(()) => std::process::exit(0),
                Err(msg) => {
                    eprintln!("--diag srv failed: {}", msg);
                    std::process::exit(1);
                }
            },
            // sagas is handled above, before the runtime check.
            "sagas" => {
                // Should never reach here — `sagas` is matched + handled
                // above the CEF runtime check. Kept for completeness.
                unreachable!("--diag sagas is handled before runtime check");
            }
            "" => {
                eprintln!("usage: agentmux.exe --diag <topic>\nknown topics: wrr, srv, sagas");
                std::process::exit(2);
            }
            other => {
                eprintln!("unknown --diag topic: {} (known: wrr, srv, sagas)", other);
                std::process::exit(2);
            }
        }
    }

    #[cfg(target_os = "windows")]
    {
        run_windows(exe_dir, &real_exe, &args).await;
    }

    #[cfg(not(target_os = "windows"))]
    {
        // Phase 7 covers cross-platform parity. For now the legacy
        // exec-into-host path is preserved on macOS/Linux. Phase B.1
        // is Windows-only.
        log("exec into CEF host (Unix)");
        use std::os::unix::process::CommandExt;
        let err = std::process::Command::new(&real_exe).args(&args).exec();
        log(&format!("FATAL: exec failed: {}", err));
        eprintln!("Failed to launch AgentMux: {}", err);
        std::process::exit(1);
    }
}

/// Phase 1 host supervision (spec
/// `docs/specs/SPEC_SERVICE_SUPERVISION_AND_RECOVERY_2026_05_20.md`): on an
/// abnormal host exit the launcher relaunches the host, but at most
/// `HOST_RESTART_BUDGET` times within `HOST_RESTART_WINDOW` — a crash budget
/// so a deterministic crash cannot spin forever (spec §10-A).
#[cfg(target_os = "windows")]
const HOST_RESTART_BUDGET: usize = 3;
#[cfg(target_os = "windows")]
const HOST_RESTART_WINDOW: std::time::Duration = std::time::Duration::from_secs(60);

/// Spawn the CEF host suspended, assign it to the launcher's Job Object, and
/// resume it. Returns the running child, or `None` if any step failed — the
/// caller decides (fatal on first launch, give-up on a restart). `splash_event`
/// is passed on every launch — including restarts — so a relaunched host can
/// still dismiss a splash left pending by a host that crashed pre-first-frame.
/// `disable_gpu` is the retry ladder's rung-2 degraded mode (spec §7): when set
/// the host is launched with `--disable-gpu` (software rendering).
#[cfg(target_os = "windows")]
fn spawn_host_supervised(
    real_exe: &std::path::Path,
    args: &[String],
    srv: &srv_spawner::SrvSpawnResult,
    host_env: &[(&'static str, std::ffi::OsString)],
    pipe_path: &str,
    job_present: bool,
    job_handle: windows_sys::Win32::Foundation::HANDLE,
    splash_event: Option<&str>,
    disable_gpu: bool,
) -> Option<tokio::process::Child> {
    use windows_sys::Win32::System::Threading::CREATE_SUSPENDED;

    let mut host_cmd = tokio::process::Command::new(real_exe);
    host_cmd
        .args(args)
        .env("AGENTMUX_BACKEND_WS", &srv.ws_endpoint)
        .env("AGENTMUX_BACKEND_WEB", &srv.web_endpoint)
        .env("AGENTMUX_BACKEND_PID", srv.pid.to_string())
        .env("AGENTMUX_AUTH_KEY", &srv.auth_key)
        .env("AGENTMUX_INSTANCE_ID", &srv.instance_id)
        .envs(host_env.iter().cloned())
        .env("AGENTMUX_LAUNCHER_PIPE", pipe_path)
        .creation_flags(CREATE_SUSPENDED)
        .kill_on_drop(false); // J0 handles cleanup.
    if let Some(name) = splash_event {
        host_cmd.env("AGENTMUX_SPLASH_EVENT", name);
    }
    // Retry-ladder rung 2 (spec §7): software rendering — no GPU process to
    // crash. A Chromium switch the host forwards to CEF.
    if disable_gpu {
        host_cmd.arg("--disable-gpu");
    }

    let mut host_child = match host_cmd.spawn() {
        Ok(c) => c,
        Err(e) => {
            log(&format!("failed to spawn CEF host: {}", e));
            return None;
        }
    };
    let host_pid = host_child.id().unwrap_or(0);
    log(&format!("spawned CEF host pid={} (suspended)", host_pid));

    // Assign to J0 BEFORE resuming so CEF render children inherit the job.
    if job_present && host_pid != 0 {
        match srv_spawner::assign_pid_to_job(host_pid, job_handle) {
            Ok(()) => log(&format!(
                "Job Object assigned to host pid={}, KILL_ON_JOB_CLOSE active",
                host_pid
            )),
            Err(e) => log(&format!(
                "WARN: AssignProcessToJobObject(host) failed: {} — host children may escape job",
                e
            )),
        }
    }

    // Resume the suspended main thread.
    if let Err(e) = resume_main_thread(host_pid) {
        log(&format!("failed to resume host pid={}: {}", host_pid, e));
        let _ = host_child.start_kill();
        return None;
    }
    Some(host_child)
}

/// Windows main flow: resolve paths → create J0 → spawn srv → spawn
/// host with srv endpoints in env → supervised wait → cleanup.
#[cfg(target_os = "windows")]
async fn run_windows(
    launcher_exe_dir: &std::path::Path,
    real_exe: &std::path::Path,
    args: &[String],
) {

    let version = env!("CARGO_PKG_VERSION");

    // 1. Resolve data_dir / config_dir / user_home_dir. Both srv and
    // host receive these via env so they don't recompute (and so they
    // can't drift). Host's existing data_dir computation in sidecar.rs
    // still runs as a fallback for `task dev` mode where the launcher
    // is not in the loop.
    let paths = match data_dir::resolve_paths(launcher_exe_dir, version) {
        Ok(p) => p,
        Err(e) => {
            log(&format!("FATAL: path resolution failed: {}", e));
            eprintln!("Failed to resolve AgentMux data directories: {}", e);
            std::process::exit(1);
        }
    };
    log(&format!(
        "paths resolved: data={} config={} user_home={} portable={}",
        paths.data_dir.display(),
        paths.config_dir.display(),
        paths.user_home_dir.display(),
        paths.portable_root.is_some(),
    ));
    if let Err(e) = data_dir::ensure_dirs(&paths) {
        log(&format!("FATAL: failed to create data dirs: {}", e));
        eprintln!("{}", e);
        std::process::exit(1);
    }

    // 2. Create the launcher's Job Object J0 BEFORE any spawn. Both
    // srv and host will be assigned to it (so they're siblings under
    // a single OS-enforced cleanup contract). Failure here drops us
    // into "degraded mode" — children spawn but won't be reaped on
    // launcher death.
    let job: Option<JobHandle> = match create_job_object() {
        Ok(handle) => {
            log("Job Object created (KILL_ON_JOB_CLOSE active)");
            Some(JobHandle(handle))
        }
        Err(e) => {
            log(&format!(
                "WARN: Job Object setup failed: {} (process-tree cleanup degraded)",
                e
            ));
            None
        }
    };
    let job_handle: windows_sys::Win32::Foundation::HANDLE =
        job.as_ref().map(|j| j.0).unwrap_or(std::ptr::null_mut());

    // Phase B.2: start the named-pipe IPC server BEFORE spawning
    // any children. Host connects to this pipe at startup using the
    // AGENTMUX_LAUNCHER_PIPE env var the launcher passes below.
    //
    // The server runs in its own Tokio task; the JoinHandle is held
    // for the rest of run_windows so the task isn't cancelled mid-
    // accept. Server owns the namespace `\\.\pipe\agentmux-{hash}\
    // command` per data dir, so multi-instance launchers (different
    // data dirs) get distinct pipes.
    //
    // Phase B.6: the bind itself is the single-instance signal.
    // `bind_first_pipe_instance` synchronously reserves the pipe;
    // a second launcher pointing at the same data dir gets
    // ERROR_ACCESS_DENIED. We surface that to the user as
    // "AgentMux is already running for this data directory" and
    // exit cleanly BEFORE spawning srv/host (otherwise the second
    // host would briefly contend on the CEF cache lockfile).
    let dir_hash = hash::data_dir_hash16(&paths.data_dir);
    let pipe_path = ipc::pipe_name(&dir_hash);
    let first_pipe = match ipc::server::bind_first_pipe_instance(&pipe_path) {
        Ok(p) => p,
        Err(e) => {
            // ERROR_ACCESS_DENIED (5) means another launcher already
            // owns this pipe — i.e., another AgentMux is running for
            // this data dir. The user-facing behavior matches the
            // status-bar version popup's "new window": forward an
            // `open_new_window` IPC POST to the existing host and
            // exit 0. The named-pipe bind is the AUTHORITATIVE
            // single-instance signal; this HTTP call is just the
            // forwarding hint. Other errors (namespace misconfig,
            // security descriptor failure) genuinely fail — show
            // the dialog and exit 2.
            const ERROR_ACCESS_DENIED: i32 = 5;
            let already_running = e.raw_os_error() == Some(ERROR_ACCESS_DENIED);
            log(&format!(
                "pipe bind failed (already_running={}): {} pipe={}",
                already_running, e, pipe_path
            ));
            if already_running {
                match forward_open_new_window(&paths.data_dir) {
                    Ok(()) => {
                        log("forwarded open_new_window to existing instance — exiting 0");
                        std::process::exit(0);
                    }
                    Err(ForwardError::Transient(reason)) => {
                        // Transient race: the host is alive (pipe is
                        // held by the first launcher) but its
                        // forwarding hint isn't readable yet —
                        // typically because the host is mid-CEF-init
                        // and hasn't written `<data-dir>/ipc-port`
                        // yet. Silent exit so the user isn't punished
                        // for double-clicking quickly.
                        log(&format!("forward transient: {} — exiting 0 silently", reason));
                        std::process::exit(0);
                    }
                    Err(ForwardError::Fatal(reason)) => {
                        // Fatal forward failure: the port file IS
                        // readable, so the host got far enough to
                        // publish it, but the HTTP path is dead
                        // (connect refused, write failed). Could be
                        // a hung host, a port collision, or
                        // ERROR_ACCESS_DENIED that wasn't really
                        // "another instance" (namespace conflict).
                        // Surface the dialog so the user sees that
                        // something is genuinely broken rather than
                        // a silent no-op. (codex P2 PR #598.)
                        log(&format!("forward fatal: {} — surfacing dialog", reason));
                        show_fatal_dialog(
                            "AgentMux",
                            &format!(
                                "AgentMux appears to already be running but isn't responding.\n\nData dir: {}\nReason: {}\n\nClose any leftover AgentMux processes and try again. If the problem persists, check the launcher log.",
                                paths.data_dir.display(),
                                reason
                            ),
                        );
                        std::process::exit(2);
                    }
                }
            }
            // Genuine bind failure (not "already running"). Surface
            // it loudly because it indicates a system-level problem.
            show_fatal_dialog(
                "AgentMux",
                &format!(
                    "AgentMux failed to start: could not bind IPC pipe.\n\nPipe: {}\nError: {}\n\nIf the problem persists, check the launcher log.",
                    pipe_path, e
                ),
            );
            std::process::exit(2);
        }
    };
    // Spawn the native pre-splash immediately after claiming the
    // single-instance pipe — before srv spawn and CEF init.
    // The event name is forwarded to the CEF host as
    // AGENTMUX_SPLASH_EVENT so it can signal dismiss from on_load_end.
    #[cfg(target_os = "windows")]
    let splash_event_name = splash::spawn_splash(&dir_hash);
    #[cfg(not(target_os = "windows"))]
    let splash_event_name: Option<String> = None;

    // Phase B.8 — broadcast bus for reducer-emitted events. Capacity
    // 1024 is comfortable headroom for the launcher's event volume
    // (~10–50 events per user action × handful of subscribers); a
    // lagging client gets `RecvError::Lagged` and reconnects.
    let (events_tx, _) = tokio::sync::broadcast::channel::<agentmux_common::ipc::Event>(1024);

    // Phase D.2 — event log: in-memory ring (replay source for D.3's
    // GetEvents) + optional disk persistence at
    // `<data-dir>/launcher-events.log` for crash forensics.
    let log_disk_path = paths.data_dir.join("launcher-events.log");
    let event_log = std::sync::Arc::new(event_log::EventLog::new(Some(log_disk_path)));
    let event_log_for_writer = std::sync::Arc::clone(&event_log);
    let disk_writer_rx = events_tx.subscribe();
    tokio::spawn(event_log::run_disk_writer(event_log_for_writer, disk_writer_rx));

    // Phase E.1a — canonical state shared between IPC server + saga
    // coordinator (and, in E.5, individual sagas). Single Mutex
    // owner, multiple readers via Arc.
    let state = std::sync::Arc::new(tokio::sync::Mutex::new(state::State::default()));

    // LSD-2 — open the durable launcher saga log at
    // `<data-dir>/db/launcher-sagas.db` (separate file from
    // `launcher-events.log`; the saga log is structured SQLite, the
    // event log is append-only JSONL). Failure to open is a launcher
    // startup error — without the log, sagas have no crash-recovery
    // story (LSD-3 walks `unresolved_sagas` to mark interrupted
    // sagas `failed_compensation`). Spec
    // `docs/specs/SPEC_LAUNCHER_SAGA_DURABILITY_2026-05-01.md` §3.1.
    //
    // `launcher_saga_log_path` performs the back-compat move from
    // the pre-AUDIT_SQLITE_SYSTEMS_2026_05_19.md location
    // (`<data-dir>/launcher-sagas.db` — outside `db/`) into the
    // canonical `db/` subdir alongside srv's SQLite files.
    let saga_log_path = data_dir::launcher_saga_log_path(&paths.data_dir);
    let saga_log = match saga::LauncherSagaLog::open(&saga_log_path) {
        Ok(l) => std::sync::Arc::new(l),
        Err(e) => {
            log(&format!(
                "FATAL: failed to open launcher saga log at {:?}: {}",
                saga_log_path, e
            ));
            std::process::exit(2);
        }
    };

    // LSD-3 — startup recovery walker. Walks the durable saga log,
    // marks any saga still in `running` / `compensating` / `failed`
    // (left over from a crashed prior run) as `failed_compensation`
    // so operators see them in `--diag sagas` and the next coordinator
    // run can't accidentally double-act on partially-applied effects.
    // MUST run BEFORE `tokio::spawn(saga::run_coordinator(..))` below
    // (LSD spec §5 risk #5: don't spawn while recovery is in progress).
    // Runs BEFORE LSD-4 vacuum so just-recovered sagas land in their
    // failed_compensation state for the operator to see — vacuum
    // honors the 7-day retention window and won't immediately purge.
    // Spec `docs/specs/SPEC_LAUNCHER_SAGA_DURABILITY_2026-05-01.md` §3.5.
    if let Err(e) = saga::compensate_unresolved_launcher_sagas(&saga_log).await {
        log(&format!(
            "[saga-recovery] WARN: walker failed: {} — coordinator will still spawn; prior crashed sagas remain unresolved until next restart",
            e
        ));
    }

    // LSD-4 — startup retention vacuum. Runs once per launcher boot,
    // before the coordinator subscribes, so any rows it deletes are
    // already terminal and can't possibly belong to an in-flight saga
    // the coordinator is about to drive (see `vacuum_older_than` SQL —
    // `running` and `compensating` rows are unreachable by the DELETE
    // regardless of timing). Failure is non-fatal.
    // Spec §3.6.
    let retention_days =
        config::load_saga_retention_days(&paths.user_home_dir, |w| log(w));
    let cutoff = chrono::Utc::now() - chrono::Duration::days(retention_days);
    match saga_log.vacuum_older_than(cutoff) {
        Ok(removed) => log(&format!(
            "[saga-log] vacuumed {} sagas older than {} (retention {} days)",
            removed, cutoff, retention_days
        )),
        Err(e) => log(&format!("[saga-log] WARN: vacuum failed: {}", e)),
    }

    // CPD-2 — launcher → host pipe wrapper. Owns the writer half of
    // the host's IPC connection (installed by the per-connection
    // handler in `ipc::server` once the host registers) and exposes
    // `send_command` / `send_event` to the rest of the launcher.
    // CPD-2 wires the wrapper + refactors event fanout for the host
    // connection to flow through here. CPD-3 wires this into the
    // saga coordinator's `apply_action` so `IssueCmd::Host` actions
    // dispatch live (no longer log-only).
    let host_pipe = std::sync::Arc::new(host_pipe::HostPipe::new(
        events_tx.clone(),
        std::sync::Arc::clone(&state),
    ));

    // Phase E.1a — saga coordinator task. Subscribes to the broadcast
    // bus, drives in-flight sagas. E.1a registry is empty — framework
    // only. E.5 adds the first concrete saga consumer (tear-off).
    // LSD-2 — durable saga log is now installed; every lifecycle
    // transition is persisted.
    // CPD-3 — install `host_pipe` so saga `IssueCmd::Host` actions
    // dispatch through the launcher → host wire instead of being
    // log-only.
    //
    // Subscribe BEFORE spawning so the race window between construction
    // and first `recv()` doesn't drop early events. (reagent P2 PR #609.)
    // Same pattern as the disk writer above.
    // with_log() can fail if max_saga_id() fails (e.g. corrupted SQLite
    // file). Treat as fatal — continuing with a default next_saga_id=1
    // while the log is attached would let the coordinator silently
    // mutate prior saga history on restart. Better to crash loudly so
    // operators see + investigate. (codex P1 PR #645 round 2.)
    let saga_coord_inner = saga::SagaCoordinator::new(events_tx.clone(), std::sync::Arc::clone(&state))
        .with_log(std::sync::Arc::clone(&saga_log))
        .unwrap_or_else(|e| {
            log(&format!(
                "[main] FATAL: failed to seed saga_id allocator from launcher_saga.max(saga_id): {} — refusing to start with degraded coordinator",
                e
            ));
            std::process::exit(1);
        })
        .with_host_pipe(std::sync::Arc::clone(&host_pipe));
    let saga_coord = std::sync::Arc::new(saga_coord_inner);
    let saga_rx = events_tx.subscribe();
    tokio::spawn(saga::run_coordinator(
        std::sync::Arc::clone(&saga_coord),
        saga_rx,
    ));

    let _ipc_handle = ipc::run_ipc_server(
        pipe_path.clone(),
        first_pipe,
        ipc::server::ServerCtx {
            launcher_pid: std::process::id(),
            launcher_version: env!("CARGO_PKG_VERSION").to_string(),
            state,
            events_tx,
            event_log,
            host_pipe: std::sync::Arc::clone(&host_pipe),
        },
    );
    log(&format!("IPC server started on {}", pipe_path));

    // 3. Spawn srv first. Host needs srv's endpoints to skip its own
    // spawn_backend path. Srv signals readiness via AGENTMUXSRV-ESTART on
    // stderr; the spawner returns once we see that line (or after a
    // 30s timeout).
    // Phase E.1b — pre-compute srv's pipe path (same data-dir hash
    // as launcher's pipe) and pass via env so srv binds it on
    // startup. Launcher is the sole authority for the data-dir hash.
    let srv_pipe_path = ipc::srv_pipe_name(&dir_hash);
    log(&format!("[ipc] srv pipe path = {}", srv_pipe_path));

    let (srv_result, mut srv_child) = match srv_spawner::spawn_srv(
        launcher_exe_dir,
        &paths,
        &srv_pipe_path,
        job_handle,
    )
    .await
    {
        Ok(pair) => pair,
        Err(e) => {
            log(&format!("FATAL: srv spawn failed: {}", e));
            eprintln!("Failed to start backend: {}", e);
            drop(job);
            std::process::exit(1);
        }
    };

    // CRITICAL: tokio::process::Child::wait() proactively drops
    // self.stdin before waiting (tokio source comment: "Ensure stdin
    // is closed so the child can't read from it any more"). agentmux-
    // srv has a parent-watch loop on its own stdin — when stdin reads
    // 0 bytes (EOF from a closed write end), it interprets that as
    // "parent died" and shuts itself down. tokio's wait() would
    // trigger that within milliseconds, causing srv to exit before
    // the host even mounts its first browser. Move srv's stdin out
    // of the Child into a launcher-scope binding so tokio can't see
    // it (its take() returns None) and the pipe stays open for the
    // launcher's lifetime. (Smoke test on v0.33.447 caught this.)
    let _srv_stdin_keepalive = srv_child.stdin.take();

    // 4-6. Spawn the host (suspended) → assign to J0 → resume, via
    // spawn_host_supervised(). The splash event is passed on every launch
    // (including restarts) so a relaunched host still dismisses a pending
    // splash if the first host crashed before its first frame.
    let host_env = paths.common.to_env_vars();
    let mut host_child = match spawn_host_supervised(
        real_exe,
        args,
        &srv_result,
        &host_env,
        &pipe_path,
        job.is_some(),
        job_handle,
        splash_event_name.as_deref(),
        false,
    ) {
        Some(c) => c,
        None => {
            // First-launch failure is fatal. Happy path: drop(job) →
            // KILL_ON_JOB_CLOSE reaps srv. Degraded path (J0 absent):
            // kill srv explicitly or it orphans (kill_on_drop is false).
            log("FATAL: could not start CEF host — terminating");
            eprintln!("Failed to launch AgentMux.");
            if job.is_none() {
                let _ = srv_child.start_kill();
            }
            drop(job);
            std::process::exit(1);
        }
    };

    // 7. Supervised wait loop (Phase 1 — host supervision). The host is
    // auto-restarted on abnormal exit, bounded by a crash budget so a
    // deterministic crash can't spin forever (spec §10-A). A clean host
    // exit (code 0) ends the loop. srv is NOT yet supervised — an srv
    // exit still terminates the launcher; srv supervision is Phase 2.
    //
    // We don't manually kill the surviving child in the happy path:
    // dropping `job` below triggers KILL_ON_JOB_CLOSE which reaps the
    // entire J0 membership. The explicit start_kill is the backstop for
    // degraded mode (job == None) only.
    log("entering supervised host + srv wait");
    let mut host_restarts: Vec<std::time::Instant> = Vec::new();
    let mut last_abnormal_code: Option<i32> = None;
    let mut host_degraded = false;
    let exit_code = loop {
        tokio::select! {
            host_status = host_child.wait() => {
                let code = match host_status {
                    Ok(s) => s.code().unwrap_or(1),
                    Err(e) => {
                        log(&format!("FATAL: host wait failed: {}", e));
                        break 1;
                    }
                };
                if code == 0 {
                    log("CEF host exited cleanly (code 0) — shutting down");
                    break 0;
                }
                // Abnormal exit — relaunch within the crash budget.
                let now = std::time::Instant::now();
                host_restarts.retain(|t| now.duration_since(*t) < HOST_RESTART_WINDOW);
                if host_restarts.len() >= HOST_RESTART_BUDGET {
                    log(&format!(
                        "CEF host exited abnormally (code {}); restart budget exhausted \
                         ({} in {}s) — giving up",
                        code,
                        host_restarts.len(),
                        HOST_RESTART_WINDOW.as_secs()
                    ));
                    break code;
                }
                host_restarts.push(now);
                // Crash classification + retry ladder (spec §7): a crash that
                // reproduces the previous abnormal exit code is deterministic —
                // step down to a degraded (--disable-gpu) relaunch so the retry
                // isn't "the same thing again". Degraded is sticky; the ladder
                // only steps down.
                if last_abnormal_code == Some(code) {
                    host_degraded = true;
                }
                last_abnormal_code = Some(code);
                log(&format!(
                    "CEF host exited abnormally (code {}) — relaunching (restart {}/{}{})",
                    code,
                    host_restarts.len(),
                    HOST_RESTART_BUDGET,
                    if host_degraded { ", degraded: --disable-gpu" } else { "" }
                ));
                match spawn_host_supervised(
                    real_exe,
                    args,
                    &srv_result,
                    &host_env,
                    &pipe_path,
                    job.is_some(),
                    job_handle,
                    splash_event_name.as_deref(),
                    host_degraded,
                ) {
                    Some(c) => host_child = c,
                    None => {
                        log("host relaunch failed to spawn — giving up");
                        break code;
                    }
                }
            }
            srv_status = srv_child.wait() => {
                match srv_status {
                    Ok(s) => log(&format!(
                        "srv exited UNEXPECTEDLY (host still running) with code {} — terminating launcher",
                        s.code().unwrap_or(1)
                    )),
                    Err(e) => log(&format!("FATAL: srv wait failed: {}", e)),
                }
                break 1;
            }
        }
    };

    // 8. Cleanup. Happy path: drop(job) → KILL_ON_JOB_CLOSE reaps
    // the surviving child + CEF renderers. Degraded path (job is
    // None): explicit start_kill on both — neither will be reaped
    // by the OS, so we have to terminate them ourselves to avoid
    // orphans. (gemini PR #570 round-1 MEDIUM L105 / round-2 P1
    // backstop pattern.)
    if job.is_none() {
        log("WARN: J0 absent — explicitly killing surviving children");
        let _ = host_child.start_kill();
        let _ = srv_child.start_kill();
    }
    drop(job);
    log(&format!("launcher exiting with code {}", exit_code));
    std::process::exit(exit_code);
}

/// Append a timestamped line to ~/.agentmux/logs/agentmux-launcher.log.
/// Best-effort — silently no-ops if the log dir doesn't exist yet.
pub(crate) fn log(msg: &str) {
    let log_dir = dirs_fallback_home().join(".agentmux").join("logs");
    let _ = std::fs::create_dir_all(&log_dir);
    let path = log_dir.join("agentmux-launcher.log");
    if let Ok(mut f) = std::fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(&path)
    {
        use std::io::Write;
        let secs = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let _ = writeln!(f, "[{}] v{} {}", secs, env!("CARGO_PKG_VERSION"), msg);
    }
}

/// Home dir without depending on `dirs` for THIS specific lookup.
/// Kept to avoid a dirs dep cycle from log() — log() is called from
/// data_dir::resolve_paths via failure paths, and we want it to work
/// even if `dirs` itself is mid-failure.
fn dirs_fallback_home() -> std::path::PathBuf {
    std::env::var("USERPROFILE")
        .or_else(|_| std::env::var("HOME"))
        .map(std::path::PathBuf::from)
        .unwrap_or_else(|_| std::path::PathBuf::from("."))
}

/// Owns a Windows Job Object handle. CloseHandle on drop. The job's
/// `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` flag means closing the last handle
/// terminates every assigned process — which is what we want as a backstop
/// if this launcher dies abruptly.
#[cfg(target_os = "windows")]
struct JobHandle(windows_sys::Win32::Foundation::HANDLE);

#[cfg(target_os = "windows")]
unsafe impl Send for JobHandle {}

#[cfg(target_os = "windows")]
impl Drop for JobHandle {
    fn drop(&mut self) {
        if !self.0.is_null() {
            unsafe {
                windows_sys::Win32::Foundation::CloseHandle(self.0);
            }
        }
    }
}

/// Create a Job Object J0 with `KILL_ON_JOB_CLOSE`. Caller assigns
/// processes to it via `srv_spawner::assign_pid_to_job(pid, job)`.
#[cfg(target_os = "windows")]
fn create_job_object() -> Result<windows_sys::Win32::Foundation::HANDLE, String> {
    use windows_sys::Win32::Foundation::CloseHandle;
    use windows_sys::Win32::System::JobObjects::*;

    unsafe {
        let job = CreateJobObjectW(std::ptr::null(), std::ptr::null());
        if job.is_null() {
            return Err("CreateJobObjectW returned null".into());
        }
        let mut info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = std::mem::zeroed();
        info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
        let ok = SetInformationJobObject(
            job,
            JobObjectExtendedLimitInformation,
            &info as *const _ as *const std::ffi::c_void,
            std::mem::size_of::<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>() as u32,
        );
        if ok == 0 {
            CloseHandle(job);
            return Err("SetInformationJobObject failed".into());
        }
        Ok(job)
    }
}

/// Resume the (single) main thread of a CREATE_SUSPENDED process.
///
/// Walks a Toolhelp32 thread snapshot to find the one thread belonging
/// to `pid` (a freshly-spawned suspended process has only its main
/// thread), opens it with THREAD_SUSPEND_RESUME, and ResumeThread's it.
///
/// Errors come from snapshot creation, OpenThread, or ResumeThread
/// returning `(DWORD)-1`. A `ResumeThread` return of 0 means the thread
/// was already running (impossible if the process was just created
/// suspended) — treated as success.
#[cfg(target_os = "windows")]
pub(crate) fn resume_main_thread(pid: u32) -> Result<(), String> {
    use windows_sys::Win32::Foundation::{CloseHandle, INVALID_HANDLE_VALUE};
    use windows_sys::Win32::System::Diagnostics::ToolHelp::{
        CreateToolhelp32Snapshot, Thread32First, Thread32Next, TH32CS_SNAPTHREAD,
        THREADENTRY32,
    };
    use windows_sys::Win32::System::Threading::{
        OpenThread, ResumeThread, THREAD_SUSPEND_RESUME,
    };

    unsafe {
        let snap = CreateToolhelp32Snapshot(TH32CS_SNAPTHREAD, 0);
        if snap == INVALID_HANDLE_VALUE {
            return Err("CreateToolhelp32Snapshot failed".into());
        }

        let mut entry: THREADENTRY32 = std::mem::zeroed();
        entry.dwSize = std::mem::size_of::<THREADENTRY32>() as u32;

        let mut found = false;
        if Thread32First(snap, &mut entry) != 0 {
            loop {
                if entry.th32OwnerProcessID == pid {
                    let thread = OpenThread(THREAD_SUSPEND_RESUME, 0, entry.th32ThreadID);
                    if !thread.is_null() {
                        let prev = ResumeThread(thread);
                        CloseHandle(thread);
                        if prev == u32::MAX {
                            CloseHandle(snap);
                            return Err(format!(
                                "ResumeThread failed for tid={}",
                                entry.th32ThreadID
                            ));
                        }
                        found = true;
                        break;
                    }
                }
                entry.dwSize = std::mem::size_of::<THREADENTRY32>() as u32;
                if Thread32Next(snap, &mut entry) == 0 {
                    break;
                }
            }
        }

        CloseHandle(snap);
        if !found {
            return Err(format!("no thread found for pid={}", pid));
        }
        Ok(())
    }
}

/// Phase B.6 (post-fix) — forward an `open_new_window` request to
/// the already-running host and let this launcher exit 0.
///
/// The host writes `<data-dir>/ipc-port` after CEF init as
/// `port:token`. We open a TCP connection to 127.0.0.1:port, send a
/// minimal HTTP/1.1 POST to /ipc with the bearer token and a JSON
/// body, and bail. We deliberately do NOT pull in reqwest: the
/// launcher binary should stay tiny (~325 KB) and the protocol is
/// fixed, so a hand-rolled request is the right tool.
///
/// Failure classification (codex P2 PR #598):
/// - `Transient` — port file missing / unreadable / malformed.
///   The host is alive (pipe held) but mid-startup; caller exits
///   0 silently so the user isn't punished for double-clicking
///   quickly.
/// - `Fatal` — port file is readable, but the HTTP path failed
///   (connect refused, write failed, timeout). Either a hung
///   host or a non-running-instance source of
///   `ERROR_ACCESS_DENIED` (namespace conflict, security
///   descriptor failure). Caller surfaces the dialog so the user
///   sees a real problem rather than a silent no-op.
enum ForwardError {
    Transient(String),
    Fatal(String),
}

fn forward_open_new_window(data_dir: &std::path::Path) -> Result<(), ForwardError> {
    let port_file = data_dir.join("ipc-port");
    let contents = std::fs::read_to_string(&port_file).map_err(|e| {
        ForwardError::Transient(format!("read {}: {}", port_file.display(), e))
    })?;
    let trimmed = contents.trim();
    let (port_str, token) = trimmed.split_once(':').ok_or_else(|| {
        ForwardError::Transient(format!(
            "malformed port file (expected port:token): {}",
            trimmed
        ))
    })?;
    let port: u16 = port_str
        .parse()
        .map_err(|e| ForwardError::Transient(format!("invalid port {:?}: {}", port_str, e)))?;

    // From here on the file was readable: any failure is a fatal
    // forward (the host got far enough to publish but isn't
    // serving the IPC port).
    let addr: std::net::SocketAddr = ([127, 0, 0, 1], port).into();
    let mut stream = std::net::TcpStream::connect_timeout(&addr, std::time::Duration::from_secs(2))
        .map_err(|e| ForwardError::Fatal(format!("connect 127.0.0.1:{}: {}", port, e)))?;
    stream
        .set_write_timeout(Some(std::time::Duration::from_secs(2)))
        .ok();

    let body = r#"{"cmd":"open_new_window"}"#;
    let req = format!(
        "POST /ipc HTTP/1.1\r\nHost: 127.0.0.1\r\nContent-Type: application/json\r\nAuthorization: Bearer {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
        token,
        body.len(),
        body
    );
    use std::io::{Read, Write};
    stream
        .write_all(req.as_bytes())
        .map_err(|e| ForwardError::Fatal(format!("write request: {}", e)))?;
    // CRITICAL: read at least the status line. The host's axum
    // handler is async — if the launcher closes the TCP socket
    // before axum has finished parsing + dispatching to
    // `open_new_window`, the request can be dropped (smoke caught
    // exactly this on v0.33.481: the launcher logged "forwarded"
    // but no second window appeared because the process exited
    // before axum ran the handler). We don't care about the body
    // — `Connection: close` lets the server drop the socket once
    // the response is written, so a single short read is enough
    // to keep the connection alive past handler dispatch.
    stream
        .set_read_timeout(Some(std::time::Duration::from_secs(2)))
        .ok();
    let mut sink = [0u8; 64];
    let _ = stream.read(&mut sink);
    Ok(())
}

/// Show a modal error dialog before the launcher exits. Used for
/// genuine bind failures (NOT the "already running" path — that
/// silently forwards via `forward_open_new_window`). Without this,
/// the launcher exit is silent (it has the `windows` subsystem in
/// release, so eprintln! goes nowhere).
#[cfg(target_os = "windows")]
fn show_fatal_dialog(title: &str, body: &str) {
    use std::os::windows::ffi::OsStrExt;
    use windows_sys::Win32::UI::WindowsAndMessaging::{
        MessageBoxW, MB_ICONWARNING, MB_OK, MB_SETFOREGROUND, MB_TOPMOST,
    };
    let title_w: Vec<u16> = std::ffi::OsStr::new(title)
        .encode_wide()
        .chain(Some(0))
        .collect();
    let body_w: Vec<u16> = std::ffi::OsStr::new(body)
        .encode_wide()
        .chain(Some(0))
        .collect();
    unsafe {
        MessageBoxW(
            std::ptr::null_mut(),
            body_w.as_ptr(),
            title_w.as_ptr(),
            MB_OK | MB_ICONWARNING | MB_SETFOREGROUND | MB_TOPMOST,
        );
    }
}

#[cfg(not(target_os = "windows"))]
fn show_fatal_dialog(_title: &str, body: &str) {
    eprintln!("{}", body);
}

/// Find the CEF host binary in the runtime directory.
/// Tries versioned name first (agentmux-X.Y.Z.exe), then the old
/// agentmux-cef-X.Y.Z.exe pattern for backwards compat, then plain
/// agentmux-cef.exe (dev mode).
fn find_cef_binary(runtime_dir: &std::path::Path) -> std::path::PathBuf {
    let ext = if cfg!(target_os = "windows") { ".exe" } else { "" };

    let versioned = format!("agentmux-{}{}", env!("CARGO_PKG_VERSION"), ext);
    let versioned_path = runtime_dir.join(&versioned);
    if versioned_path.exists() {
        return versioned_path;
    }

    if let Ok(entries) = std::fs::read_dir(runtime_dir) {
        let prefix = "agentmux-";
        let cef_prefix = "agentmux-cef";
        for entry in entries.flatten() {
            let name = entry.file_name();
            let name = name.to_string_lossy();
            if name.starts_with(prefix)
                && !name.starts_with(cef_prefix)
                && !name.starts_with("agentmux-srv")
                && name.ends_with(ext)
            {
                return entry.path();
            }
        }
    }

    let versioned_old = format!("agentmux-cef-{}{}", env!("CARGO_PKG_VERSION"), ext);
    let versioned_old_path = runtime_dir.join(&versioned_old);
    if versioned_old_path.exists() {
        return versioned_old_path;
    }

    runtime_dir.join(format!("agentmux-cef{}", ext))
}