agentmux_launcher/autostart/

mod.rs

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

//! Auto-start-at-login registration — issue #2977 Workstream 2,
//! `docs/specs/SPEC_TRAY_OPTIONAL_BACKGROUND_SERVICE_2026_09_04.md` §4.
//!
//! ## Opt-in, off by default, and separate from "close to tray"
//!
//! Nothing here runs unless the user explicitly asks for it. The issue is
//! emphatic that these are two different decisions: "a user can have
//! 'close-to-tray keeps it running for this session' without 'starts
//! automatically at every login' being bundled into the same toggle". So
//! auto-start has its own state, its own enable/disable, and is never
//! implied by `AGENTMUX_TRAY` or `AGENTMUX_BACKGROUND_SERVICE`.
//!
//! ## Mechanism per platform, and what was rejected
//!
//! - **Windows — Scheduled Task, `LogonType=InteractiveToken`.** Not a
//!   Windows Service (needs admin to register, and Session-0 isolation means
//!   it structurally cannot show a tray icon), and not a bare `Run` registry
//!   key (no crash supervision, no delay control).
//! - **macOS — LaunchAgent plist. This DEVIATES from the governing spec, and
//!   the deviation has a user-visible consequence.**
//!   `SPEC_TRAY_OPTIONAL_BACKGROUND_SERVICE_2026_09_04.md` §4 calls
//!   `SMAppService` "unambiguously current best practice" and notes it is the
//!   only path that surfaces correctly in **System Settings → Login Items &
//!   Extensions**. Writing the LaunchAgent directly means the entry may not
//!   appear there the way a user expects, which matters more than usual here:
//!   Workstream 4 requires that a user be able to *see* and remove a
//!   background service, and Login Items is where they will look.
//!   `SMAppService` is only callable through its ObjC interface from inside a
//!   **bundled, signed** app, so adopting it means objc2 bindings plus a
//!   bundle identifier that matches the registered agent — real work that
//!   cannot be written blind or verified on a non-macOS machine. Recorded as
//!   a known gap rather than pretended away: macOS auto-start should move to
//!   `SMAppService` before it is offered to users. (ReAgent P1 on PR #2999.)
//! - **Linux — XDG autostart `.desktop`.** `systemd --user` is deliberately
//!   NOT the default: surviving logout needs `loginctl enable-linger`, which
//!   is a separate, consequential decision the issue says must never be
//!   silently enabled.
//!
//! ## Uninstall is a first-class operation (Workstream 4)
//!
//! WS4 requires "one complete, independently-testable uninstall path that
//! actually removes the LaunchAgent/Scheduled-Task/autostart artifact — not
//! just closes the window". `disable()` is that path, and `is_enabled()`
//! makes it independently checkable: the pair is the whole contract, and
//! `disable()` is idempotent so an uninstaller can call it unconditionally.
//!
//! ## Structure
//!
//! The artifact *content* (Task Scheduler XML, plist, desktop entry) is
//! generated by pure functions that take an exe path and return a string.
//! That keeps the part most likely to be subtly wrong — escaping, schema
//! fields, the `InteractiveToken` logon type — unit-testable without
//! touching the machine's real login configuration.

#[cfg(windows)]
use agentmux_common::win32::NoWindow;
use std::path::Path;

/// The flag every generated artifact passes to the launcher.
///
/// This is the ONLY thing that makes an auto-started instance behave like a
/// background service. Without it being interpreted, an auto-start entry
/// would just open an ordinary foreground window at login and still quit when
/// the user closed it — i.e. the feature would silently not work (Codex P1 on
/// PR #2999).
pub const BACKGROUND_FLAG: &str = "--background";

/// Did the launcher get started in background mode?
///
/// Pure so the argv parsing is testable. Callers turn this into the env the
/// host actually reads (`AGENTMUX_BACKGROUND_SERVICE`, plus `AGENTMUX_TRAY` —
/// see `background_env_for`).
pub fn background_requested(args: &[String]) -> bool {
    args.iter().any(|a| a == BACKGROUND_FLAG)
}

/// Was this process started by a login entry? Every artifact passes
/// `--background`, and nothing else does.
pub fn login_start() -> bool {
    background_requested(&std::env::args().collect::<Vec<_>>())
}

/// A launcher that finds AgentMux already running forwards `open_new_window`
/// to it, so a double-click opens a window. A login entry firing while the
/// user already has AgentMux open must not (`SPEC_START_WITH_OS_2026_09_25.md`
/// §3.6): it just exits.
pub fn second_instance_opens_window(args: &[String]) -> bool {
    !background_requested(args)
}

/// Environment the host must receive when the launcher was started with
/// `--background`.
///
/// Sets BOTH switches deliberately. Background mode without a tray icon is
/// the precise anti-pattern Workstream 4 exists to prevent: a process that
/// starts itself at login, keeps running with no window, and offers the user
/// no visible indicator that it is there or any way to stop it. Auto-start is
/// the one context where the indicator is not optional, so `--background`
/// implies the tray rather than leaving them independently settable.
///
/// Returns pairs rather than mutating a `Command` so the mapping is testable.
pub fn background_env_for(args: &[String]) -> Vec<(&'static str, &'static str)> {
    if background_requested(args) {
        vec![
            ("AGENTMUX_BACKGROUND_SERVICE", "1"),
            ("AGENTMUX_TRAY", "1"),
        ]
    } else {
        Vec::new()
    }
}

/// Identifier used for the artifact on every platform: the Scheduled Task
/// name, the LaunchAgent label's suffix, and the `.desktop` filename stem.
/// Stable, because `disable()` has to find what `enable()` created —
/// including across upgrades, so it deliberately carries no version.
#[cfg(any(target_os = "windows", target_os = "linux", test))]
pub const AUTOSTART_ID: &str = "AgentMux";

/// Reverse-DNS label for the macOS LaunchAgent, which requires that form.
#[cfg(any(not(target_os = "windows"), test))]
pub const MACOS_LABEL: &str = "com.agentmux.launcher";

/// Windows Task Scheduler registration XML.
///
/// `LogonType=InteractiveToken` is the load-bearing detail (issue WS2): it
/// runs the task as the logged-in user *in their interactive session*, which
/// is what lets the process own a tray icon and later spawn visible windows.
/// `RunLevel=LeastPrivilege` keeps it out of elevation prompts — auto-start
/// must not require admin.
///
/// `<Delay>PT30S</Delay>` staggers startup behind the desktop's own login
/// work; a background service racing Explorer for disk on every boot is a
/// bad citizen, and 30s is invisible for something meant to run all day.
///
/// `DisallowStartIfOnBatteries`/`StopIfGoingOnBatteries` are both false
/// deliberately: the defaults are *true*, which would make a laptop user's
/// background service silently not start, or die mid-turn on unplug — the
/// exact "is it actually running?" unreliability WS4 warns about.
#[cfg(any(target_os = "windows", test))]
pub fn scheduled_task_xml(exe: &Path, channel: &str) -> String {
    let exe = xml_escape(&exe.display().to_string());
    let channel = xml_escape(channel);
    format!(
        r#"<?xml version="1.0" encoding="UTF-16"?>
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
  <RegistrationInfo>
    <Description>Starts AgentMux in the background at logon. Created by AgentMux; remove it by turning off auto-start in AgentMux, or with: schtasks /Delete /TN "{id}" /F {marker}{channel}]</Description>
    <URI>\{id}</URI>
  </RegistrationInfo>
  <Triggers>
    <LogonTrigger>
      <Enabled>true</Enabled>
      <Delay>PT30S</Delay>
    </LogonTrigger>
  </Triggers>
  <Principals>
    <Principal id="Author">
      <LogonType>InteractiveToken</LogonType>
      <RunLevel>LeastPrivilege</RunLevel>
    </Principal>
  </Principals>
  <Settings>
    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
    <AllowHardTerminate>false</AllowHardTerminate>
    <StartWhenAvailable>false</StartWhenAvailable>
    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
    <IdleSettings>
      <StopOnIdleEnd>false</StopOnIdleEnd>
      <RestartOnIdle>false</RestartOnIdle>
    </IdleSettings>
    <AllowStartOnDemand>true</AllowStartOnDemand>
    <Enabled>true</Enabled>
    <Hidden>false</Hidden>
    <RunOnlyIfIdle>false</RunOnlyIfIdle>
    <WakeToRun>false</WakeToRun>
    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
    <Priority>7</Priority>
  </Settings>
  <Actions Context="Author">
    <Exec>
      <Command>"{exe}"</Command>
      <Arguments>--background</Arguments>
    </Exec>
  </Actions>
</Task>
"#,
        id = AUTOSTART_ID,
        exe = exe,
        marker = TASK_CHANNEL_MARKER,
        channel = channel,
    )
}

/// Marks the owning channel inside the Task's `<Description>`, the only
/// free-text field Task Scheduler keeps verbatim.
const TASK_CHANNEL_MARKER: &str = "[agentmux-channel=";

/// macOS LaunchAgent plist.
///
/// `RunAtLoad` starts it at login. `KeepAlive` is deliberately **false**: the
/// launcher already supervises `srv`/`host` and owns its own restart policy,
/// so letting `launchd` also restart it would give two supervisors fighting
/// over the same process — and would make a user-requested Quit from the tray
/// come straight back, which is worse than useless.
#[cfg(any(not(target_os = "windows"), test))]
pub fn launch_agent_plist(exe: &Path, channel: &str) -> String {
    let exe = xml_escape(&exe.display().to_string());
    let channel = xml_escape(channel);
    format!(
        r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>{label}</string>
    <key>ProgramArguments</key>
    <array>
        <string>{exe}</string>
        <string>--background</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>ProcessType</key>
    <string>Interactive</string>
    <key>{channel_key}</key>
    <string>{channel}</string>
</dict>
</plist>
"#,
        label = MACOS_LABEL,
        exe = exe,
        channel_key = PLIST_CHANNEL_KEY,
        channel = channel,
    )
}

/// Owning channel, as a plist key launchd ignores.
const PLIST_CHANNEL_KEY: &str = "AgentMuxChannel";

/// Linux XDG autostart desktop entry.
///
/// `X-GNOME-Autostart-enabled=true` is included because some desktops treat a
/// missing value as disabled. `Terminal=false` keeps it from spawning a
/// console window on desktops that honor it.
///
/// `TryExec` makes the entry inert once the target is gone (app removed,
/// AppImage deleted): the session skips it instead of failing at every login
/// (`SPEC_START_WITH_OS_2026_09_25.md` §3.1). `X-GNOME-Autostart-Delay` gives
/// the tray host time to come up first (§3.4). `X-AgentMux-Channel` records
/// which build owns the entry (§3.5).
#[cfg(any(not(target_os = "windows"), test))]
pub fn xdg_desktop_entry(exe: &Path, channel: &str) -> String {
    format!(
        "[Desktop Entry]\n\
         Type=Application\n\
         Name=AgentMux\n\
         Comment=Starts AgentMux in the background at login\n\
         TryExec={try_exec}\n\
         Exec=\"{exe}\" {flag}\n\
         Terminal=false\n\
         X-GNOME-Autostart-enabled=true\n\
         X-GNOME-Autostart-Delay=10\n\
         {channel_key}={channel}\n",
        try_exec = desktop_string_escape(&exe.display().to_string()),
        exe = desktop_exec_escape(exe),
        flag = BACKGROUND_FLAG,
        channel_key = XDG_CHANNEL_KEY,
        channel = desktop_string_escape(channel),
    )
}

/// Owning channel, as a vendor key (`X-` keys are ignored by the session).
const XDG_CHANNEL_KEY: &str = "X-AgentMux-Channel";

/// Escape a plain desktop-entry string value (`TryExec`, vendor keys), per the
/// Desktop Entry spec's `\\`, `\n`, `\t`, `\r` escapes. A raw newline would
/// end the line and let a path inject keys, as `desktop_exec_escape` explains.
#[cfg(any(not(target_os = "windows"), test))]
fn desktop_string_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\t' => out.push_str("\\t"),
            '\r' => out.push_str("\\r"),
            _ => out.push(c),
        }
    }
    out
}

fn desktop_string_unescape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut it = s.chars();
    while let Some(c) = it.next() {
        if c != '\\' {
            out.push(c);
            continue;
        }
        match it.next() {
            Some('n') => out.push('\n'),
            Some('t') => out.push('\t'),
            Some('r') => out.push('\r'),
            Some('s') => out.push(' '),
            Some(o) => out.push(o),
            None => out.push('\\'),
        }
    }
    out
}

/// Escape a path for use inside a **quoted argument** of a desktop entry's
/// `Exec=` value.
///
/// Stripping newlines is not enough (ReAgent/Codex P2 on PR #2999). All of
/// these are legal in a Unix path and all of them change how the desktop-entry
/// parser tokenizes the command:
///
/// - `"` terminates the quoted argument — the rest of the path becomes
///   separate argv entries, so the app is launched with the wrong executable.
/// - `\`, `` ` ``, `$` are reserved inside quoted arguments per the
///   Desktop Entry Specification and must be backslash-escaped.
/// - `%` introduces a **field code** (`%f`, `%U`, …); an unescaped one is
///   substituted by the launcher. The spec's escape for a literal is `%%`.
/// - newline/CR would end the `Exec=` line entirely and let the remainder be
///   parsed as further desktop-entry keys (the original guard, kept).
///
/// Same injection class the XML path already handles via `xml_escape`; this
/// is the desktop-entry grammar's version of it.
#[cfg(any(not(target_os = "windows"), test))]
fn desktop_exec_escape(exe: &Path) -> String {
    let raw = exe.display().to_string();
    let mut out = String::with_capacity(raw.len());
    for c in raw.chars() {
        match c {
            // Reserved inside a quoted argument — escape with a backslash.
            '"' | '\\' | '`' | '$' => {
                out.push('\\');
                out.push(c);
            }
            // Field-code introducer; `%%` is the literal.
            '%' => out.push_str("%%"),
            // Would terminate the Exec= line and allow key injection.
            '\n' | '\r' => {}
            _ => out.push(c),
        }
    }
    out
}

/// Minimal XML text escaping for the two generated XML documents.
///
/// Only the five predefined entities matter here, and the only untrusted-ish
/// input is a filesystem path (which can legitimately contain `&` and, on
/// Unix, `<`/`>`/quotes). Hand-rolled rather than pulling an XML crate into a
/// binary the codebase deliberately keeps tiny — the same reasoning
/// `second_instance.rs` gives for hand-rolling its HTTP request.
fn xml_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '"' => out.push_str("&quot;"),
            '\'' => out.push_str("&apos;"),
            _ => out.push(c),
        }
    }
    out
}

/// Where the artifact lives, for the platforms that use a plain file.
/// Not used on Windows, whose artifact lives in the Task Scheduler store
/// rather than a path we own.
#[cfg(not(target_os = "windows"))]
pub fn artifact_path() -> Option<std::path::PathBuf> {
    #[cfg(target_os = "macos")]
    {
        let home = std::env::var("HOME").ok()?;
        Some(
            Path::new(&home)
                .join("Library/LaunchAgents")
                .join(format!("{}.plist", MACOS_LABEL)),
        )
    }
    #[cfg(target_os = "linux")]
    {
        // Honor XDG_CONFIG_HOME; fall back to the spec's default.
        let base = std::env::var("XDG_CONFIG_HOME")
            .ok()
            .filter(|s| !s.is_empty())
            .unwrap_or_else(|| format!("{}/.config", std::env::var("HOME").unwrap_or_default()));
        Some(
            Path::new(&base)
                .join("autostart")
                .join(format!("{}.desktop", AUTOSTART_ID.to_lowercase())),
        )
    }
    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
    {
        None
    }
}

/// A `schtasks` command that never opens a console window.
///
/// The launcher is a GUI-subsystem process and `schtasks.exe` is a console
/// program, so a bare spawn flashes a console over the splash. The start-at-login
/// reconcile runs `schtasks /Query` on every startup.
#[cfg(target_os = "windows")]
fn schtasks_command() -> std::process::Command {
    let mut cmd = std::process::Command::new("schtasks");
    cmd.no_window();
    cmd
}

/// Is auto-start currently registered?
///
/// Half of the WS4 uninstall contract: an uninstall path is only
/// "independently testable" if something can answer this without trusting
/// whatever wrote it. So this inspects the real system state (the Task
/// Scheduler store, or the artifact file) rather than any bookkeeping of our
/// own.
pub fn is_enabled() -> bool {
    #[cfg(target_os = "windows")]
    {
        // `schtasks /Query` exits non-zero when the task does not exist.
        schtasks_command()
            .args(["/Query", "/TN", AUTOSTART_ID])
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .status()
            .map(|s| s.success())
            .unwrap_or(false)
    }
    #[cfg(not(target_os = "windows"))]
    {
        artifact_path().map(|p| p.exists()).unwrap_or(false)
    }
}

/// Register auto-start for `exe`. Idempotent: re-registering an existing
/// entry replaces it, which is also how an upgrade repoints the artifact at a
/// new install path.
pub fn enable(exe: &Path, channel: &str) -> Result<(), String> {
    #[cfg(target_os = "windows")]
    {
        // Register from XML — the only way to set LogonType/battery settings;
        // the flag-based `schtasks /Create /SC ONLOGON` form cannot express
        // them. The XML must be UTF-16 per the Task Scheduler schema
        // declaration, so it is written as UTF-16LE with a BOM.
        let xml = scheduled_task_xml(exe, channel);
        let dir = std::env::temp_dir();
        let path = dir.join(format!("agentmux-autostart-{}.xml", std::process::id()));
        let mut bytes: Vec<u8> = vec![0xFF, 0xFE]; // UTF-16LE BOM
        for unit in xml.encode_utf16() {
            bytes.extend_from_slice(&unit.to_le_bytes());
        }
        std::fs::write(&path, &bytes).map_err(|e| format!("write task xml: {}", e))?;

        // Capture output rather than discarding it: schtasks reports schema
        // and permission problems on stderr, and an autostart registration
        // that fails with only "exit code 1" is undiagnosable for a user or
        // in a bug report.
        let out = schtasks_command()
            .args(["/Create", "/TN", AUTOSTART_ID, "/XML"])
            .arg(&path)
            .arg("/F") // replace an existing registration
            .output();
        // Best-effort cleanup; the temp file is harmless if it survives.
        let _ = std::fs::remove_file(&path);

        match out {
            Ok(o) if o.status.success() => Ok(()),
            Ok(o) => Err(format!(
                "schtasks /Create failed ({}): {}{}",
                o.status,
                String::from_utf8_lossy(&o.stderr).trim(),
                String::from_utf8_lossy(&o.stdout).trim()
            )),
            Err(e) => Err(format!("run schtasks: {}", e)),
        }
    }
    #[cfg(not(target_os = "windows"))]
    {
        let path = artifact_path().ok_or_else(|| "unsupported platform".to_string())?;
        let contents = if cfg!(target_os = "macos") {
            launch_agent_plist(exe, channel)
        } else {
            xdg_desktop_entry(exe, channel)
        };
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| format!("create {}: {}", parent.display(), e))?;
        }
        std::fs::write(&path, contents).map_err(|e| format!("write {}: {}", path.display(), e))
    }
}

/// Remove auto-start registration. **Idempotent** — succeeds when nothing was
/// registered, so an uninstaller can call it unconditionally without first
/// asking whether the feature was ever turned on.
///
/// This is the WS4 "complete uninstall path": it removes the actual
/// Scheduled Task / LaunchAgent / desktop entry, not merely some internal
/// flag. `is_enabled()` afterwards is the independent check that it worked.
pub fn disable() -> Result<(), String> {
    #[cfg(target_os = "windows")]
    {
        if !is_enabled() {
            return Ok(());
        }
        match schtasks_command()
            .args(["/Delete", "/TN", AUTOSTART_ID, "/F"])
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .status()
        {
            Ok(s) if s.success() => Ok(()),
            Ok(s) => Err(format!("schtasks /Delete failed: {}", s)),
            Err(e) => Err(format!("run schtasks: {}", e)),
        }
    }
    #[cfg(not(target_os = "windows"))]
    {
        let Some(path) = artifact_path() else {
            return Ok(());
        };
        match std::fs::remove_file(&path) {
            Ok(()) => Ok(()),
            // Already gone is success, not an error — that is what makes this
            // safe to call unconditionally from an uninstaller.
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
            Err(e) => Err(format!("remove {}: {}", path.display(), e)),
        }
    }
}

/// Handle the auto-start CLI verbs, if present. Returns `true` when one was
/// handled and the process should exit.
///
/// Without this the module would be unreachable in a shipped build — nothing
/// could opt in, query, or remove the registration (Codex P1 on PR #2999).
/// A CLI surface rather than only a UI toggle is deliberate: it gives an
/// **uninstaller** something to call, which is precisely what Workstream 4's
/// "one complete, independently-testable uninstall path" needs. A GUI toggle
/// can be layered on later and should call the same functions.
///
/// Verbs (checked before any heavy startup work, so they are cheap and cannot
/// disturb a running instance):
/// - `--enable-autostart`  — register, using this executable's own path
/// - `--disable-autostart` — remove; idempotent, safe to run unconditionally
/// - `--autostart-status`  — print `enabled` / `disabled`, exit 0 either way
/// The channel this launcher belongs to, which owns any entry it writes
/// (`SPEC_START_WITH_OS_2026_09_25.md` §3.5). Resolved the same way as the
/// data dir; `"unknown"` only if that resolution fails.
pub fn current_channel() -> String {
    std::env::current_exe()
        .ok()
        .and_then(|exe| {
            let dir = exe.parent()?.to_path_buf();
            crate::data_dir::resolve_paths(&dir, env!("CARGO_PKG_VERSION")).ok()
        })
        .map(|p| p.common.channel)
        .unwrap_or_else(|| "unknown".to_string())
}

/// Env var the Linux AppRun and wrappers set to their own path right before
/// they exec the launcher.
const STABLE_EXE_ENV: &str = "AGENTMUX_STABLE_EXE";

static STABLE_EXE: std::sync::OnceLock<Option<std::ffi::OsString>> = std::sync::OnceLock::new();

/// Read `AGENTMUX_STABLE_EXE` and remove it from this process's env, so no
/// child (host, srv, agent shells, a dev build started from a pane) inherits
/// a path that belongs to this launch. `APPIMAGE` is not used for the same
/// reason: the AppImage runtime's copy leaks into every agent shell.
///
/// MUST be called from `main` before any thread exists (`remove_var`).
pub fn take_stable_exe_env() {
    let value = std::env::var_os(STABLE_EXE_ENV).filter(|v| !v.is_empty());
    std::env::remove_var(STABLE_EXE_ENV);
    let _ = STABLE_EXE.set(value);
}

/// What the login entry should run: something that survives updates
/// (`SPEC_START_WITH_OS_2026_09_25.md` §3.1), not this process's own path.
///
/// 1. `AGENTMUX_STABLE_EXE` as captured by `take_stable_exe_env`: the
///    AppImage file (set by AppRun), or the deb/rpm/tarball wrapper that sets
///    the `LD_LIBRARY_PATH` the raw launcher cannot run without.
/// 2. `current_exe()`: Windows and macOS installs, portable and dev builds.
pub fn stable_target() -> Result<std::path::PathBuf, String> {
    stable_target_from(
        STABLE_EXE.get().cloned().flatten(),
        std::env::current_exe().map_err(|e| e.to_string()),
    )
}

fn stable_target_from(
    stable: Option<std::ffi::OsString>,
    current: Result<std::path::PathBuf, String>,
) -> Result<std::path::PathBuf, String> {
    match stable.map(std::path::PathBuf::from) {
        Some(p) if p.is_file() => Ok(p),
        _ => current,
    }
}

/// The login entry as it stands on this machine.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Entry {
    /// What it runs, if readable.
    pub target: Option<String>,
    /// Which channel wrote it. `None` for an entry from before ownership was
    /// recorded.
    pub channel: Option<String>,
}

/// Read the current entry back from the platform. `None` when there is none.
pub fn read_entry() -> Option<Entry> {
    #[cfg(target_os = "windows")]
    {
        let out = schtasks_command()
            .args(["/Query", "/TN", AUTOSTART_ID, "/XML"])
            .stderr(std::process::Stdio::null())
            .output()
            .ok()?;
        if !out.status.success() {
            return None;
        }
        Some(parse_task_xml(&decode_console_output(&out.stdout)))
    }
    #[cfg(not(target_os = "windows"))]
    {
        let text = std::fs::read_to_string(artifact_path()?).ok()?;
        Some(if cfg!(target_os = "macos") {
            parse_plist(&text)
        } else {
            parse_desktop_entry(&text)
        })
    }
}

/// `schtasks /XML` writes UTF-16LE when its output is redirected.
#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
fn decode_console_output(bytes: &[u8]) -> String {
    let body = bytes.strip_prefix(&[0xFF, 0xFE]).unwrap_or(bytes);
    if body.len() >= 2 && body.len() % 2 == 0 && body.iter().skip(1).step_by(2).take(64).all(|b| *b == 0) {
        let units: Vec<u16> = body.chunks_exact(2).map(|c| u16::from_le_bytes([c[0], c[1]])).collect();
        return String::from_utf16_lossy(&units);
    }
    String::from_utf8_lossy(body).into_owned()
}

fn between<'a>(s: &'a str, start: &str, end: &str) -> Option<&'a str> {
    let from = s.find(start)? + start.len();
    let len = s[from..].find(end)?;
    Some(&s[from..from + len])
}

fn xml_unescape(s: &str) -> String {
    s.replace("&lt;", "<")
        .replace("&gt;", ">")
        .replace("&quot;", "\"")
        .replace("&apos;", "'")
        .replace("&amp;", "&")
}

#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
fn parse_task_xml(xml: &str) -> Entry {
    let target = between(xml, "<Command>", "</Command>")
        .map(|c| xml_unescape(c.trim()).trim_matches('"').to_string());
    let channel = between(xml, "<Description>", "</Description>")
        .and_then(|d| between(d, TASK_CHANNEL_MARKER, "]"))
        .map(xml_unescape);
    Entry { target, channel }
}

#[cfg_attr(not(target_os = "macos"), allow(dead_code))]
fn parse_plist(text: &str) -> Entry {
    let target = between(text, "<key>ProgramArguments</key>", "</array>")
        .and_then(|a| between(a, "<string>", "</string>"))
        .map(xml_unescape);
    let channel = between(text, &format!("<key>{PLIST_CHANNEL_KEY}</key>"), "</string>")
        .and_then(|rest| rest.split_once("<string>").map(|(_, v)| xml_unescape(v)));
    Entry { target, channel }
}

#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
fn parse_desktop_entry(text: &str) -> Entry {
    let value = |key: &str| {
        text.lines()
            .find_map(|l| l.strip_prefix(key).and_then(|r| r.strip_prefix('=')))
            .map(desktop_string_unescape)
    };
    // `TryExec` is the plain path; an entry from before it existed has none,
    // reads as "target unknown", and gets rewritten.
    Entry { target: value("TryExec"), channel: value(XDG_CHANNEL_KEY) }
}

/// What to do to bring the login entry in line with `app:startatlogin`
/// (`SPEC_START_WITH_OS_2026_09_25.md` §3.9).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Plan {
    /// Already right, or not ours to touch.
    Nothing,
    /// Write (or rewrite) the entry for this channel and target.
    Write,
    /// Remove this channel's entry.
    Remove,
    /// An entry from before the setting existed, and the setting was never
    /// set: the user turned start-at-login on with the old toggle, so record
    /// that as `app:startatlogin = true` instead of removing it.
    Adopt,
}

/// Pure decision. `setting` is `app:startatlogin`, `None` when never set.
/// `target` is `stable_target()`, `None` when it could not be resolved: only
/// writing needs it, so removing or adopting never waits on it (ReAgent P1 on
/// #3788).
///
/// - On: write unless the entry already runs `target` for this channel. This
///   also re-points an entry after an update or a move, and takes ownership
///   from another channel (last enabled wins).
/// - Off: remove only an entry this channel owns. Another build's entry, or
///   one from before ownership was recorded, is not this build's to remove.
/// - Never set: off, except that an unowned (pre-setting) entry is adopted.
pub fn plan(setting: Option<bool>, entry: Option<&Entry>, channel: &str, target: Option<&str>) -> Plan {
    let owned = |e: &Entry| e.channel.as_deref() == Some(channel);
    match (setting, entry) {
        (Some(true), Some(e)) if owned(e) && target.is_some() && e.target.as_deref() == target => Plan::Nothing,
        (Some(true), _) => Plan::Write,
        (Some(false), Some(e)) if owned(e) => Plan::Remove,
        (None, Some(e)) if e.channel.is_none() => Plan::Adopt,
        _ => Plan::Nothing,
    }
}

pub fn handle_cli(args: &[String]) -> bool {
    let has = |v: &str| args.iter().any(|a| a == v);

    if has("--autostart-status") {
        println!("{}", if is_enabled() { "enabled" } else { "disabled" });
        return true;
    }
    if has("--enable-autostart") {
        match stable_target() {
            Ok(exe) => match enable(&exe, &current_channel()) {
                Ok(()) => println!("auto-start enabled ({})", exe.display()),
                Err(e) => {
                    eprintln!("failed to enable auto-start: {}", e);
                    std::process::exit(1);
                }
            },
            Err(e) => {
                eprintln!("failed to resolve the auto-start target: {}", e);
                std::process::exit(1);
            }
        }
        return true;
    }
    if has("--disable-autostart") {
        match disable() {
            Ok(()) => println!("auto-start disabled"),
            Err(e) => {
                eprintln!("failed to disable auto-start: {}", e);
                std::process::exit(1);
            }
        }
        return true;
    }
    false
}

#[cfg(test)]
mod autostart_tests {
    use super::*;
    use std::path::PathBuf;

    fn exe() -> PathBuf {
        PathBuf::from(r"C:\Program Files\AgentMux\agentmux.exe")
    }

    #[test]
    fn scheduled_task_uses_interactive_token_not_a_service_account() {
        // The whole reason WS2 specifies a Scheduled Task over a Windows
        // Service: Session-0 isolation means a service can never own a tray
        // icon or show a window. InteractiveToken is what puts it in the
        // user's own session.
        let xml = scheduled_task_xml(&exe(), "test");
        assert!(xml.contains("<LogonType>InteractiveToken</LogonType>"));
        assert!(
            xml.contains("<RunLevel>LeastPrivilege</RunLevel>"),
            "auto-start must never require elevation"
        );
    }

    #[test]
    fn scheduled_task_survives_battery_power() {
        // Task Scheduler defaults BOTH of these to true, which would make a
        // laptop user's "background service" silently fail to start on
        // battery, or die mid-turn on unplug — the unreliable-indicator
        // failure WS4 exists to prevent.
        let xml = scheduled_task_xml(&exe(), "test");
        assert!(xml.contains("<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>"));
        assert!(xml.contains("<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>"));
    }

    #[test]
    fn scheduled_task_has_no_execution_time_limit() {
        // PT0S = unlimited. The default is 72 hours, after which Task
        // Scheduler would terminate a long-running background service.
        let xml = scheduled_task_xml(&exe(), "test");
        assert!(xml.contains("<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>"));
    }

    #[test]
    fn generated_xml_escapes_paths() {
        // Install paths can contain `&` (and on Unix, quotes/angle brackets).
        // Unescaped, that produces XML that Task Scheduler rejects — or worse,
        // silently misparses.
        let xml = scheduled_task_xml(Path::new(r"C:\Tools & Apps\<agentmux>.exe"), "test");
        assert!(xml.contains("Tools &amp; Apps"));
        assert!(xml.contains("&lt;agentmux&gt;"));
        assert!(
            !xml.contains("Tools & Apps"),
            "raw ampersand would make the document invalid"
        );
    }

    #[test]
    fn launch_agent_does_not_let_launchd_resurrect_a_user_quit() {
        // KeepAlive=false is deliberate: the launcher owns its own restart
        // policy, and a tray Quit that launchd immediately undid would be
        // worse than having no Quit at all.
        let plist = launch_agent_plist(Path::new("/Applications/AgentMux.app/Contents/MacOS/agentmux"), "test");
        assert!(plist.contains("<key>RunAtLoad</key>\n    <true/>"));
        assert!(plist.contains("<key>KeepAlive</key>\n    <false/>"));
        assert!(plist.contains(MACOS_LABEL));
    }

    #[test]
    fn xdg_entry_is_a_valid_autostart_desktop_file() {
        let d = xdg_desktop_entry(Path::new("/opt/agentmux/agentmux"), "test");
        assert!(d.starts_with("[Desktop Entry]\n"));
        assert!(d.contains("Type=Application\n"));
        assert!(d.contains("X-GNOME-Autostart-enabled=true\n"));
        assert!(
            d.contains("Exec=\"/opt/agentmux/agentmux\" --background\n"),
            "Exec must quote the path so spaces don't split the command"
        );
    }

    #[test]
    fn xdg_entry_cannot_be_injected_with_extra_keys_via_the_path() {
        // A newline in the path would otherwise terminate the Exec= line and
        // let the rest be parsed as further desktop-entry keys.
        let d = xdg_desktop_entry(Path::new("/opt/x\nHidden=true"), "test");
        assert!(!d.contains("\nHidden=true\n"), "newline must not survive into the file");
    }

    /// Full enable → is_enabled → disable → is_enabled round trip against the
    /// REAL platform registry (Task Scheduler / LaunchAgents / XDG autostart).
    ///
    /// `#[ignore]` on purpose: it mutates the machine's actual login
    /// configuration, which is not something a plain `cargo test` — least of
    /// all one on a shared CI runner — should ever do as a side effect. Run it
    /// deliberately:
    ///
    /// ```text
    /// cargo test -p agentmux-launcher --release -- --ignored autostart_round_trip
    /// ```
    ///
    /// This is the WS4 "independently-testable uninstall path" made literal:
    /// it verifies removal by asking the platform, not by trusting our own
    /// bookkeeping. Self-cleaning — it disables at the end, and asserts the
    /// artifact is actually gone.
    #[test]
    #[ignore = "mutates real login configuration; run explicitly with --ignored"]
    fn autostart_round_trip_against_the_real_platform_registry() {
        // Refuse to run if the user already has autostart configured, rather
        // than clobbering (and then deleting) their real registration.
        assert!(
            !is_enabled(),
            "autostart already enabled on this machine — refusing to overwrite a real registration"
        );

        let exe = std::env::current_exe().expect("current_exe");
        enable(&exe, "test").expect("enable should succeed");
        assert!(is_enabled(), "enable() must be observable through the platform");

        // Idempotent re-enable (the upgrade path: repoint at a new exe).
        enable(&exe, "test").expect("re-enable should replace, not fail");
        assert!(is_enabled());

        disable().expect("disable should succeed");
        assert!(!is_enabled(), "disable() must actually remove the artifact");

        // Safe to call unconditionally — the property an uninstaller needs.
        disable().expect("disable must be idempotent");
    }

    /// Codex P1 on PR #2999: `--background` was forwarded but interpreted
    /// nowhere, so an auto-started instance would open an ordinary foreground
    /// window and still quit on last-window-close. The flag must map onto the
    /// env the host actually reads.
    #[test]
    fn the_background_flag_maps_onto_the_env_the_host_actually_reads() {
        let args = vec!["agentmux.exe".to_string(), BACKGROUND_FLAG.to_string()];
        assert!(background_requested(&args));
        let env = background_env_for(&args);
        assert!(
            env.contains(&("AGENTMUX_BACKGROUND_SERVICE", "1")),
            "without this the auto-start entry is inert"
        );
    }

    /// Auto-start is the one context where the indicator is not optional:
    /// a process that starts itself at login and runs with no window and no
    /// icon is exactly the invisible-background-agent pattern WS4 exists to
    /// prevent. So `--background` implies the tray.
    #[test]
    fn background_mode_also_forces_the_visible_indicator_on() {
        let args = vec![BACKGROUND_FLAG.to_string()];
        assert!(background_env_for(&args).contains(&("AGENTMUX_TRAY", "1")));
    }

    #[test]
    fn a_normal_launch_sets_no_background_env() {
        let args = vec!["agentmux.exe".to_string(), "--url=http://x".to_string()];
        assert!(!background_requested(&args));
        assert!(
            background_env_for(&args).is_empty(),
            "an ordinary launch must be completely unaffected"
        );
    }

    #[test]
    fn exec_escaping_covers_the_desktop_entry_grammar() {
        // Every one of these is legal in a Unix path and each changes how the
        // Exec value tokenizes if left raw.
        let d = xdg_desktop_entry(Path::new(r#"/opt/a"b\c`d$e%f/agentmux"#), "test");
        assert!(d.contains(r#"\"b"#), "quote must be escaped, not end the argument");
        assert!(d.contains(r"\\c"), "backslash must be escaped");
        assert!(d.contains(r"\`d"), "backtick must be escaped");
        assert!(d.contains(r"\$e"), "dollar must be escaped");
        assert!(d.contains("%%f"), "percent must be doubled or it reads as a field code");
    }

    #[test]
    fn every_platform_artifact_launches_with_the_background_flag() {
        // All three must start the app in background mode; a plain launch
        // would pop a window in the user's face at every login, which is the
        // opposite of what auto-start is for.
        assert!(scheduled_task_xml(&exe(), "test").contains("--background"));
        assert!(launch_agent_plist(&exe(), "test").contains("<string>--background</string>"));
        assert!(xdg_desktop_entry(&exe(), "test").contains("--background"));
    }

    // ── SPEC_START_WITH_OS_2026_09_25 ─────────────────────────────────────

    #[test]
    fn a_login_start_that_finds_agentmux_running_opens_no_window() {
        let manual = vec!["agentmux".to_string()];
        let login = vec!["agentmux".to_string(), BACKGROUND_FLAG.to_string()];
        assert!(second_instance_opens_window(&manual));
        assert!(!second_instance_opens_window(&login));
    }

    fn entry(target: &str, channel: Option<&str>) -> Entry {
        Entry { target: Some(target.to_string()), channel: channel.map(str::to_string) }
    }

    #[test]
    fn plan_on_writes_unless_the_entry_is_already_ours_and_current() {
        let t = "/home/u/Desktop/AgentMux.AppImage";
        assert_eq!(plan(Some(true), None, "stable", Some(t)), Plan::Write);
        assert_eq!(plan(Some(true), Some(&entry(t, Some("stable"))), "stable", Some(t)), Plan::Nothing);
        // An update or a move: same owner, old path.
        assert_eq!(plan(Some(true), Some(&entry("/old/path", Some("stable"))), "stable", Some(t)), Plan::Write);
        // Another build's entry: turning it on here takes it over.
        assert_eq!(plan(Some(true), Some(&entry(t, Some("local-main-x"))), "stable", Some(t)), Plan::Write);
    }

    #[test]
    fn plan_off_removes_only_this_channels_entry() {
        let t = "/opt/agentmux/agentmux";
        assert_eq!(plan(Some(false), Some(&entry(t, Some("stable"))), "stable", Some(t)), Plan::Remove);
        assert_eq!(plan(Some(false), Some(&entry(t, Some("local-main-x"))), "stable", Some(t)), Plan::Nothing);
        assert_eq!(plan(Some(false), Some(&entry(t, None)), "stable", Some(t)), Plan::Nothing);
        assert_eq!(plan(Some(false), None, "stable", Some(t)), Plan::Nothing);
    }

    /// ReAgent P1 on #3788: an unresolvable target must not block turning it off.
    #[test]
    fn plan_needs_the_target_only_to_write() {
        let mine = entry("/x", Some("stable"));
        assert_eq!(plan(Some(false), Some(&mine), "stable", None), Plan::Remove);
        assert_eq!(plan(None, Some(&entry("/x", None)), "stable", None), Plan::Adopt);
        // On with no target: still a write, which then reports the missing target.
        assert_eq!(plan(Some(true), Some(&mine), "stable", None), Plan::Write);
    }

    /// Off by default, but a user who turned it on with the old toggle keeps it.
    #[test]
    fn plan_never_set_is_off_but_adopts_an_entry_from_before_the_setting() {
        let t = "/x";
        assert_eq!(plan(None, None, "stable", Some(t)), Plan::Nothing);
        assert_eq!(plan(None, Some(&entry(t, None)), "stable", Some(t)), Plan::Adopt);
        assert_eq!(plan(None, Some(&entry(t, Some("local-main-x"))), "stable", Some(t)), Plan::Nothing);
    }

    #[test]
    fn every_artifact_reads_back_its_own_target_and_channel() {
        let exe = Path::new("/home/u/My Apps/Agent&Mux.AppImage");
        let want = Entry { target: Some(exe.display().to_string()), channel: Some("local-main-b28b7a".into()) };
        assert_eq!(parse_desktop_entry(&xdg_desktop_entry(exe, "local-main-b28b7a")), want);
        assert_eq!(parse_plist(&launch_agent_plist(exe, "local-main-b28b7a")), want);
        let win = Path::new(r"C:\Users\u\AppData\Local\Programs\AgentMux & Co\agentmux.exe");
        assert_eq!(
            parse_task_xml(&scheduled_task_xml(win, "stable")),
            Entry { target: Some(win.display().to_string()), channel: Some("stable".into()) }
        );
    }

    /// An entry written before ownership existed has no channel and no TryExec.
    #[test]
    fn a_pre_ownership_desktop_entry_reads_as_unowned_with_no_target() {
        let old = "[Desktop Entry]\nType=Application\nExec=\"/x/agentmux-launcher\" --background\n";
        assert_eq!(parse_desktop_entry(old), Entry { target: None, channel: None });
    }

    #[test]
    fn the_desktop_entry_goes_inert_without_its_target_and_waits_for_the_session() {
        let d = xdg_desktop_entry(Path::new("/opt/agentmux/agentmux"), "stable");
        assert!(d.contains("\nTryExec=/opt/agentmux/agentmux\n"), "{d}");
        assert!(d.contains("\nX-GNOME-Autostart-Delay=10\n"), "{d}");
        assert!(d.contains("\nX-AgentMux-Channel=stable\n"), "{d}");
    }

    #[test]
    fn try_exec_cannot_be_used_to_inject_keys() {
        let d = xdg_desktop_entry(Path::new("/opt/x\nHidden=true"), "stable");
        assert!(!d.lines().any(|l| l == "Hidden=true"), "{d}");
    }

    #[test]
    fn schtasks_utf16_output_is_decoded() {
        let mut bytes = vec![0xFF, 0xFE];
        for u in "<Command>\"C:\\a.exe\"</Command>".encode_utf16() {
            bytes.extend_from_slice(&u.to_le_bytes());
        }
        assert_eq!(decode_console_output(&bytes), "<Command>\"C:\\a.exe\"</Command>");
        assert_eq!(decode_console_output(b"plain"), "plain");
    }

    #[test]
    fn the_stable_target_prefers_the_wrapper_path_then_this_exe() {
        let dir = std::env::temp_dir().join(format!("agentmux-stable-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let wrapper = dir.join("agentmux");
        std::fs::write(&wrapper, "").unwrap();
        let cur = || Ok(PathBuf::from("/cache/agentmux-launcher"));

        assert_eq!(stable_target_from(Some(wrapper.clone().into()), cur()), Ok(wrapper.clone()));
        // A value pointing nowhere is skipped, not written.
        assert_eq!(stable_target_from(Some(dir.join("gone").into()), cur()), cur());
        assert_eq!(stable_target_from(None, cur()), cur());
        let _ = std::fs::remove_dir_all(&dir);
    }
}