supercode_harness/

teams.rs

//! Where supercode-teams lives on this box, and the service unit that keeps
//! its machine daemon up (`docs/plans/teams-server.md` §11).
//!
//! supercode does not implement teams; the `sdk/teams` package does. This
//! module holds the two facts the Rust CLI needs about it:
//!
//! * **where its Node entry is** — [`teams_entry`], resolved exactly the way
//!   [`crate::orchestrator::daemon_entry`] resolves the orchestrator's:
//!   `SUPERCODE_TEAMS_ENTRY` first, then the checkout the running binary sits
//!   in, then the checkout it was built from, then the globally installed
//!   `@volter/supercode-teams` package (`npm root -g`).
//! * **what a service unit for its node would say** — [`service_unit`] renders
//!   the launchd plist / systemd unit / Windows Scheduled Task that runs
//!   `node <entry> machine start`, written under `<home>/service/`;
//!   [`install_service`] and [`uninstall_service`] drive `launchctl` /
//!   `systemctl --user` / `schtasks` over it.
//!
//! Everything else about teams — its host key, log, contexts, enrollments — is the Node
//! package's own state, written by its own CLI. There is no second writer of
//! that home in this binary.

use std::path::{Path, PathBuf};

use crate::orchestrator::{absolute_program, resolve_program, ServiceState, ServiceUnit};

/// The teams CLI entry inside the `sdk/teams` package.
pub const TEAMS_ENTRY: &str = "bin/teams.mjs";

/// The npm name the `sdk/teams` package is published under.
pub const TEAMS_PACKAGE: &str = "@volter/supercode-teams";

/// Directory the rendered service unit is written into, relative to the home.
pub const SERVICE_DIR: &str = "service";

/// launchd label / systemd unit name for this machine's teams daemon.
pub const SERVICE_NAME: &str = "dev.volter.supercode-teams-machine";

/// Stable, context-scoped label for one workspace connector service.
pub fn connector_service_name(server_id: &str, team_id: &str, context: &str) -> String {
    // FNV-1a is sufficient here: this is a stable filesystem/service label,
    // not an authorization decision or secret digest.
    let mut hash = 0xcbf29ce484222325_u64;
    for byte in [server_id, team_id, context].join("\0").bytes() {
        hash ^= u64::from(byte);
        hash = hash.wrapping_mul(0x100000001b3);
    }
    format!("dev.volter.supercode-teams-connector-{hash:016x}")
}

fn plist_text(value: &str) -> String {
    value
        .replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

fn service_text(value: &str) -> Result<&str, TeamsError> {
    if value.chars().any(char::is_control) {
        return Err(TeamsError::Service {
            action: "render",
            detail: "service parameters cannot contain control characters".into(),
        });
    }
    Ok(value)
}

fn systemd_arg(value: &str) -> String {
    format!(
        "\"{}\"",
        value
            .replace('\\', "\\\\")
            .replace('"', "\\\"")
            .replace('%', "%%")
            .replace('$', "$$")
    )
}

/// Render the persistent foreground connector command for one saved context.
pub fn connector_service_unit(
    teams_home: &Path,
    supercode_home: &Path,
    entry: &Path,
    node: &str,
    supercode: &Path,
    context: &str,
    cwd: &Path,
    server_id: &str,
    team_id: &str,
) -> Result<ServiceUnit, TeamsError> {
    let teams_home_text = teams_home.display().to_string();
    let supercode_home_text = supercode_home.display().to_string();
    let entry_text = entry.display().to_string();
    let supercode_text = supercode.display().to_string();
    let workspace_text = cwd.display().to_string();
    for value in [
        teams_home_text.as_str(),
        supercode_home_text.as_str(),
        entry_text.as_str(),
        node,
        supercode_text.as_str(),
        context,
        workspace_text.as_str(),
        server_id,
        team_id,
    ] {
        service_text(value)?;
    }
    let label = connector_service_name(server_id, team_id, context);
    let path = teams_home
        .join(SERVICE_DIR)
        .join(format!("{label}.{}", connector_unit_suffix()));
    let node = absolute_program(node);
    let entry = entry_text;
    let workspace = workspace_text;
    let home = supercode_home_text;
    let supercode = supercode_text;
    if cfg!(windows) {
        let log_path = teams_home.join(SERVICE_DIR).join(format!("{label}.log"));
        return windows_task(
            &path,
            &label,
            &format!("supercode Teams connector ({context})"),
            &service_env_path(teams_home, &label),
            &[
                ("SUPERCODE_HOME", home.as_str()),
                ("SUPERCODE_BIN", supercode.as_str()),
                ("SUPERCODE_TEAMS_LOG", &log_path.display().to_string()),
            ],
            &node,
            &[
                entry.as_str(),
                "teams",
                "connect",
                "--foreground",
                "--context",
                context,
                "--cwd",
                workspace.as_str(),
            ],
            &workspace,
        );
    }
    if cfg!(target_os = "macos") {
        let node = plist_text(&node);
        let entry = plist_text(&entry);
        let workspace = plist_text(&workspace);
        let home = plist_text(&home);
        let supercode = plist_text(&supercode);
        let context = plist_text(context);
        let search_path = plist_text(&service_path());
        let text = 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>{node}</string><string>{entry}</string><string>teams</string><string>connect</string><string>--context</string><string>{context}</string><string>--cwd</string><string>{workspace}</string></array>
  <key>EnvironmentVariables</key><dict><key>SUPERCODE_HOME</key><string>{home}</string><key>SUPERCODE_BIN</key><string>{supercode}</string><key>PATH</key><string>{search_path}</string></dict>
  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>{}/service/{label}.out.log</string>
  <key>StandardErrorPath</key><string>{}/service/{label}.err.log</string>
</dict></plist>
"#,
            plist_text(&teams_home_text),
            plist_text(&teams_home_text)
        );
        Ok(ServiceUnit {
            kind: "launchd",
            path: path.clone(),
            text,
            install_command: format!("launchctl bootstrap gui/$(id -u) {}", path.display()),
            files: Vec::new(),
        })
    } else {
        let environment_home = systemd_arg(&format!("SUPERCODE_HOME={home}"));
        let environment_bin = systemd_arg(&format!("SUPERCODE_BIN={supercode}"));
        let environment_path = systemd_arg(&format!("PATH={}", service_path()));
        let node = systemd_arg(&node);
        let entry = systemd_arg(&entry);
        let workspace = systemd_arg(&workspace);
        let context_description = context.replace('%', "%%").replace('$', "$$");
        let context = systemd_arg(context);
        // KillMode=process: the tmux server holding the machine's panes forks into this unit's cgroup, and a
        // restart must end only the connector, never the panes.
        let text = format!("[Unit]\nDescription=supercode Teams connector ({context_description})\nAfter=network.target\n\n[Service]\nEnvironment={environment_home}\nEnvironment={environment_bin}\nEnvironment={environment_path}\nExecStart={node} {entry} teams connect --context {context} --cwd {workspace}\nRestart=on-failure\nKillSignal=SIGTERM\nKillMode=process\n\n[Install]\nWantedBy=default.target\n");
        Ok(ServiceUnit {
            kind: "systemd",
            path: path.clone(),
            text,
            install_command: format!(
                "systemctl --user link {} && systemctl --user enable --now {label}",
                path.display()
            ),
            files: Vec::new(),
        })
    }
}

/// The connector unit's file suffix on this platform.
fn connector_unit_suffix() -> &'static str {
    if cfg!(windows) {
        "xml"
    } else if cfg!(target_os = "macos") {
        "plist"
    } else {
        "service"
    }
}

/// The environment file a Windows service task hands to node (`--env-file`).
fn service_env_path(teams_home: &Path, label: &str) -> PathBuf {
    teams_home.join(SERVICE_DIR).join(format!("{label}.env"))
}

/// Render a per-user Scheduled Task that keeps `node --env-file=<env_path> <node_args…>` running, written to `path`
/// with its environment file beside it. Shared by the connector and the machine daemon.
#[allow(clippy::too_many_arguments)]
fn windows_task(
    path: &Path,
    label: &str,
    description: &str,
    env_path: &Path,
    env: &[(&str, &str)],
    node: &str,
    node_args: &[&str],
    working_directory: &str,
) -> Result<ServiceUnit, TeamsError> {
    // A scheduled task sets no environment and keeps no output, so node reads both from a file beside the
    // task (`--env-file`); the user's own PATH is the task's. `conhost --headless` runs it without a window,
    // and hides node's exit code too, so restart-on-failure never sees one fail: a trigger every minute
    // starts the service again instead, and while it runs the task's IgnoreNew makes that tick a no-op.
    // The trigger's fixed past start keeps the rendered unit the same on every install.
    let env_text = env
        .iter()
        .map(|(key, value)| env_file_value(value).map(|value| format!("{key}={value}\n")))
        .collect::<Result<String, _>>()?;
    let env_flag = format!("--env-file={}", env_path.display());
    let mut arguments = vec![node, env_flag.as_str()];
    arguments.extend_from_slice(node_args);
    // Task Scheduler expands `%NAME%` in a task's arguments, and there is no escape for it.
    for value in arguments.iter().chain([&working_directory]) {
        if value.contains('%') {
            return Err(TeamsError::Service {
                action: "render",
                detail: format!("a Windows task cannot carry a path containing `%`: {value}"),
            });
        }
    }
    let arguments = arguments
        .iter()
        .map(|argument| windows_arg(argument))
        .collect::<Vec<_>>()
        .join(" ");
    let user = windows_user();
    let conhost = Path::new(&std::env::var("SystemRoot").unwrap_or_else(|_| r"C:\Windows".into()))
        .join(r"System32\conhost.exe")
        .display()
        .to_string();
    let text = 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>{}</Description></RegistrationInfo>
  <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>{}</UserId></LogonTrigger><TimeTrigger><StartBoundary>2000-01-01T00:00:00</StartBoundary><Enabled>true</Enabled><Repetition><Interval>PT1M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition></TimeTrigger></Triggers>
  <Principals><Principal id="Author"><UserId>{}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
  <Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure><StartWhenAvailable>true</StartWhenAvailable></Settings>
  <Actions Context="Author"><Exec><Command>{}</Command><Arguments>--headless {}</Arguments><WorkingDirectory>{}</WorkingDirectory></Exec></Actions>
</Task>
"#,
        xml_text(description),
        xml_text(&user),
        xml_text(&user),
        xml_text(&conhost),
        xml_text(&arguments),
        xml_text(working_directory),
    );
    Ok(ServiceUnit {
        kind: "schtasks",
        path: path.to_path_buf(),
        text,
        install_command: format!("schtasks /Create /TN {label} /XML {} /F", path.display()),
        files: vec![(env_path.to_path_buf(), env_text)],
    })
}

/// Text inside a Task Scheduler XML element or attribute.
fn xml_text(value: &str) -> String {
    plist_text(value).replace('"', "&quot;")
}

/// One argument of a Windows command line, quoted so the C runtime (node.exe's) splits it back out whole:
/// backslashes are literal except before a quote, where they and the quote are escaped.
fn windows_arg(value: &str) -> String {
    if !value.is_empty() && !value.contains([' ', '\t', '"']) {
        return value.to_string();
    }
    let mut quoted = String::from("\"");
    let mut backslashes = 0;
    for character in value.chars() {
        match character {
            '\\' => backslashes += 1,
            '"' => {
                quoted.push_str(&"\\".repeat(backslashes * 2 + 1));
                quoted.push('"');
                backslashes = 0;
            }
            other => {
                quoted.push_str(&"\\".repeat(backslashes));
                quoted.push(other);
                backslashes = 0;
            }
        }
    }
    quoted.push_str(&"\\".repeat(backslashes * 2));
    quoted.push('"');
    quoted
}

/// A value in a node `--env-file`, quoted with a quote character the value does not contain. Single and backtick
/// quotes are literal; double quotes would turn a path's `\n` into a newline, so they are the last choice.
fn env_file_value(value: &str) -> Result<String, TeamsError> {
    ['\'', '`']
        .into_iter()
        .find(|quote| !value.contains(*quote))
        .map(|quote| format!("{quote}{value}{quote}"))
        .or_else(|| (!value.contains(['"', '\\'])).then(|| format!("\"{value}\"")))
        .ok_or_else(|| TeamsError::Service {
            action: "render",
            detail: format!("cannot write `{value}` into a service's environment file"),
        })
}

/// The Windows account a task runs as: `DOMAIN\user`, the one installing it.
fn windows_user() -> String {
    let user = std::env::var("USERNAME").unwrap_or_default();
    match std::env::var("USERDOMAIN") {
        Ok(domain) if !domain.is_empty() => format!("{domain}\\{user}"),
        _ => user,
    }
}

/// The binary an installed connector runs. On Windows a running `.exe` cannot be replaced, so a
/// connector that ran the npm package's own binary made `npm install -g` fail with EBUSY for as long
/// as it ran: there the service runs a copy kept per version under the teams service directory, and
/// installing again after an upgrade moves it to the new copy. Copies of other versions that no
/// process holds any more are removed. Everywhere else the binary itself is replaceable in place.
pub fn connector_service_binary(
    teams_home: &Path,
    supercode: &Path,
) -> Result<PathBuf, TeamsError> {
    if !cfg!(windows) {
        return Ok(supercode.to_path_buf());
    }
    let file = |path: &Path, source: std::io::Error| TeamsError::File {
        path: path.to_path_buf(),
        source,
    };
    let copies = teams_home.join(SERVICE_DIR).join("bin");
    let version = env!("CARGO_PKG_VERSION");
    let dir = copies.join(version);
    let copy = dir.join(
        supercode
            .file_name()
            .unwrap_or_else(|| "supercode.exe".as_ref()),
    );
    let size = |path: &Path| std::fs::metadata(path).map(|meta| meta.len()).ok();
    if size(&copy).is_none() || size(&copy) != size(supercode) {
        std::fs::create_dir_all(&dir).map_err(|source| file(&dir, source))?;
        std::fs::copy(supercode, &copy).map_err(|source| file(&copy, source))?;
    }
    if let Ok(entries) = std::fs::read_dir(&copies) {
        for entry in entries.flatten() {
            if entry.file_name() != version {
                let _ = std::fs::remove_dir_all(entry.path());
            }
        }
    }
    Ok(copy)
}

/// Why a teams verb could not do its work.
#[derive(Debug, thiserror::Error)]
pub enum TeamsError {
    /// The Node teams entry could not be located.
    #[error("no teams entry found (looked for `sdk/teams/{TEAMS_ENTRY}` under: {searched}); install it with `npm install -g {TEAMS_PACKAGE}`")]
    NoEntry {
        /// The candidate paths that were searched, joined.
        searched: String,
    },
    /// A service manager refused, or there is none on this platform.
    #[error("teams service: {action} failed: {detail}")]
    Service {
        /// What was attempted (`install`, `uninstall`).
        action: &'static str,
        /// What the service manager (or this module) said about it.
        detail: String,
    },
    /// A file under the teams home could not be written or removed.
    #[error("teams file `{}`: {source}", path.display())]
    File {
        /// The path involved.
        path: PathBuf,
        /// The underlying I/O failure.
        source: std::io::Error,
    },
}

/// The search path a service runs with: the installing shell's own, so a
/// service finds the same `tmux`, `node` and harness CLIs its installer did
/// (a launchd or systemd default path has none of them).
fn service_path() -> String {
    std::env::var("PATH")
        .ok()
        .filter(|path| !path.trim().is_empty())
        .unwrap_or_else(|| "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin".into())
}

/// The teams home: `SUPERCODE_TEAMS_HOME`, else `<SUPERCODE_HOME>/teams`.
///
/// The same precedence `sdk/volter-teams/home.mjs` uses, so a unit installed from
/// here serves the home the Node CLI reads.
pub fn teams_home() -> PathBuf {
    if let Ok(home) = std::env::var("SUPERCODE_TEAMS_HOME") {
        if !home.is_empty() {
            return PathBuf::from(home);
        }
    }
    crate::agent::global_instructions_dir().join("teams")
}

/// Locate the Node teams entry (`sdk/teams/bin/teams.mjs`).
///
/// Candidates, in order: `SUPERCODE_TEAMS_ENTRY` (an explicit override, which
/// is also how a test points at a fake), the repo checkout the running binary
/// sits in, the workspace this crate was built from,
/// and the globally installed npm package — an installed binary has no
/// checkout, so `npm install -g @volter/supercode-teams` is how a
/// Machine gets its node. The current directory is never a candidate: the
/// code a binary runs does not change with where it is run.
pub fn teams_entry() -> Result<PathBuf, TeamsError> {
    let mut searched = Vec::new();
    if let Some(explicit) = std::env::var_os("SUPERCODE_TEAMS_ENTRY") {
        let path = PathBuf::from(explicit);
        if path.is_file() {
            return Ok(path);
        }
        searched.push(path.display().to_string());
    }
    let mut roots: Vec<PathBuf> = Vec::new();
    if let Ok(exe) = std::env::current_exe() {
        // target/<profile>/supercode → the workspace root is two levels up.
        roots.extend(exe.ancestors().skip(1).take(4).map(Path::to_path_buf));
    }
    // A locally built binary's target directory can live anywhere (a shared
    // cargo build dir, another volume), so the checkout it was built from is
    // the last candidate. On an installed binary this path simply does not
    // exist and is skipped like any other miss.
    if let Some(workspace) = Path::new(env!("CARGO_MANIFEST_DIR")).ancestors().nth(2) {
        roots.push(workspace.to_path_buf());
    }
    for root in roots {
        let candidate = root.join("sdk/teams").join(TEAMS_ENTRY);
        if candidate.is_file() {
            return Ok(candidate);
        }
        searched.push(candidate.display().to_string());
    }
    // Installed from npm, this binary sits inside the global node_modules that
    // also holds the Teams package, so that directory is found from the
    // binary's own path first (`npm root -g` masks path segments it takes for
    // secrets, a UUID among them).
    if let Ok(exe) = std::env::current_exe() {
        for modules in exe
            .ancestors()
            .filter(|dir| dir.file_name().is_some_and(|name| name == "node_modules"))
        {
            let candidate = modules.join(TEAMS_PACKAGE).join(TEAMS_ENTRY);
            if candidate.is_file() {
                return Ok(candidate);
            }
            searched.push(candidate.display().to_string());
        }
    }
    if let Some(global) = global_npm_root() {
        let candidate = global.join(TEAMS_PACKAGE).join(TEAMS_ENTRY);
        if candidate.is_file() {
            return Ok(candidate);
        }
        searched.push(candidate.display().to_string());
    }
    Err(TeamsError::NoEntry {
        searched: searched.join(", "),
    })
}

/// Where npm installs global packages (`npm root -g`), when npm is present.
fn global_npm_root() -> Option<PathBuf> {
    let output = std::process::Command::new(resolve_program("npm"))
        .args(["root", "-g"])
        .stdin(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .output()
        .ok()?;
    if !output.status.success() {
        return None;
    }
    let text = String::from_utf8_lossy(&output.stdout);
    let root = text.trim();
    if root.is_empty() {
        return None;
    }
    Some(PathBuf::from(root))
}

/// Render the per-platform service unit for this machine's teams daemon.
///
/// The node takes no `--root`: it serves the home its own environment
/// resolves (`SUPERCODE_TEAMS_HOME`, else `<SUPERCODE_HOME>/teams`), so the
/// unit names the listen address and nothing else. A port of `0` means the
/// node picks one and publishes it in `<home>/node.json`.
///
/// On Windows it is a per-user Scheduled Task, rendered exactly as a connector's is (see [`windows_task`]).
pub fn service_unit(home: &Path, entry: &Path, node: &str) -> Result<ServiceUnit, TeamsError> {
    let home_display = home.display().to_string();
    let entry_display = entry.display().to_string();
    // A control character would break out of any unit's syntax (a plist string, a systemd line, task XML).
    for value in [home_display.as_str(), entry_display.as_str(), node] {
        service_text(value)?;
    }
    if cfg!(windows) {
        let log_path = home.join(SERVICE_DIR).join(format!("{SERVICE_NAME}.log"));
        return windows_task(
            &home.join(SERVICE_DIR).join(unit_file_name()),
            SERVICE_NAME,
            &format!("supercode teams machine daemon ({home_display})"),
            &service_env_path(home, SERVICE_NAME),
            &[
                ("SUPERCODE_TEAMS_HOME", home_display.as_str()),
                ("SUPERCODE_TEAMS_LOG", &log_path.display().to_string()),
            ],
            node,
            &[entry_display.as_str(), "machine", "start"],
            &home_display,
        );
    }
    if cfg!(target_os = "macos") {
        let path = home.join(SERVICE_DIR).join(format!("{SERVICE_NAME}.plist"));
        let text = 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>{SERVICE_NAME}</string>
  <key>ProgramArguments</key>
  <array>
    <string>{node}</string>
    <string>{entry_display}</string>
    <string>machine</string>
    <string>start</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>SUPERCODE_TEAMS_HOME</key><string>{home_display}</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>{home_display}/service/teams-machine.out.log</string>
  <key>StandardErrorPath</key><string>{home_display}/service/teams-machine.err.log</string>
</dict>
</plist>
"#
        );
        let install = format!("launchctl bootstrap gui/$(id -u) {}", path.display());
        Ok(ServiceUnit {
            kind: "launchd",
            path,
            text,
            install_command: install,
            files: Vec::new(),
        })
    } else {
        let path = home
            .join(SERVICE_DIR)
            .join(format!("{SERVICE_NAME}.service"));
        let text = format!(
            "[Unit]\n\
             Description=supercode teams machine daemon ({home_display})\n\
             After=network.target\n\
             \n\
             [Service]\n\
             Environment=SUPERCODE_TEAMS_HOME={home_display}\n\
             ExecStart={node} {entry_display} machine start\n\
             Restart=on-failure\n\
             KillSignal=SIGTERM\n\
             KillMode=process\n\
             \n\
             [Install]\n\
             WantedBy=default.target\n"
        );
        let install = format!(
            "systemctl --user link {} && systemctl --user enable --now {SERVICE_NAME}",
            path.display()
        );
        Ok(ServiceUnit {
            kind: "systemd",
            path,
            text,
            install_command: install,
            files: Vec::new(),
        })
    }
}

/// Write a rendered unit under `<home>/service/`.
pub fn write_unit(unit: &ServiceUnit) -> Result<(), TeamsError> {
    if let Some(parent) = unit.path.parent() {
        std::fs::create_dir_all(parent).map_err(|source| TeamsError::File {
            path: unit.path.clone(),
            source,
        })?;
    }
    std::fs::write(&unit.path, &unit.text).map_err(|source| TeamsError::File {
        path: unit.path.clone(),
        source,
    })?;
    for (path, text) in &unit.files {
        std::fs::write(path, text).map_err(|source| TeamsError::File {
            path: path.clone(),
            source,
        })?;
    }
    Ok(())
}

/// Run a service-manager command and return (success, stdout+stderr).
fn run_tool(program: &str, args: &[&str]) -> Result<(bool, String), std::io::Error> {
    let output = std::process::Command::new(program).args(args).output()?;
    let mut text = String::from_utf8_lossy(&output.stdout).into_owned();
    text.push_str(&String::from_utf8_lossy(&output.stderr));
    Ok((output.status.success(), text.trim().to_string()))
}

#[cfg(target_os = "macos")]
fn gui_domain() -> String {
    // SAFETY: `getuid` reads this process's own real user id and cannot fail.
    format!("gui/{}", unsafe { libc::getuid() })
}

/// What the platform's service manager says about the teams daemon unit.
///
/// Never starts or installs anything.
pub fn service_status() -> ServiceState {
    platform_status()
}

#[cfg(target_os = "macos")]
fn platform_status() -> ServiceState {
    let label = SERVICE_NAME.to_string();
    let target = format!("{}/{SERVICE_NAME}", gui_domain());
    match run_tool("launchctl", &["print", &target]) {
        Ok((true, text)) => ServiceState {
            kind: "launchd",
            label,
            installed: true,
            pid: field_of(&text, "pid = ").and_then(|value| value.parse().ok()),
            detail: field_of(&text, "state = ").unwrap_or_else(|| "loaded".into()),
        },
        Ok((false, _)) => ServiceState {
            kind: "launchd",
            label,
            installed: false,
            pid: None,
            detail: format!("not bootstrapped in {}", gui_domain()),
        },
        Err(error) => ServiceState {
            kind: "launchd",
            label,
            installed: false,
            pid: None,
            detail: format!("launchctl unavailable: {error}"),
        },
    }
}

#[cfg(all(unix, not(target_os = "macos")))]
fn platform_status() -> ServiceState {
    let label = SERVICE_NAME.to_string();
    match run_tool("systemctl", &["--user", "is-active", SERVICE_NAME]) {
        Ok((active, text)) => {
            let known = run_tool("systemctl", &["--user", "is-enabled", SERVICE_NAME])
                .map(|(ok, _)| ok)
                .unwrap_or(false);
            ServiceState {
                kind: "systemd",
                label,
                installed: active || known,
                pid: None,
                detail: if text.is_empty() {
                    "unknown".into()
                } else {
                    text
                },
            }
        }
        Err(error) => ServiceState {
            kind: "systemd",
            label,
            installed: false,
            pid: None,
            detail: format!("systemctl unavailable: {error}"),
        },
    }
}

#[cfg(not(unix))]
fn platform_status() -> ServiceState {
    named_service_status(SERVICE_NAME)
}

/// `key = value` out of a service manager's block output.
#[cfg(target_os = "macos")]
fn field_of(text: &str, key: &str) -> Option<String> {
    text.lines()
        .find_map(|line| line.trim().strip_prefix(key))
        .map(|value| value.trim().to_string())
}

/// The file name the unit takes on this platform.
fn unit_file_name() -> String {
    if cfg!(windows) {
        format!("{SERVICE_NAME}.xml")
    } else if cfg!(target_os = "macos") {
        format!("{SERVICE_NAME}.plist")
    } else {
        format!("{SERVICE_NAME}.service")
    }
}

/// Render the unit, hand it to the platform's service manager, and start it.
///
/// Refuses a label the manager already holds rather than replacing it: two
/// homes share one label, so an install that silently took it over would point
/// a running node at a different folder.
pub fn install_service(
    home: &Path,
    entry: &Path,
    node: &str,
) -> Result<(ServiceUnit, ServiceState), TeamsError> {
    let existing = service_status();
    if existing.installed {
        return Err(TeamsError::Service {
            action: "install",
            detail: format!(
                "`{}` is already installed ({}); `supercode teams machine uninstall` first",
                existing.label, existing.detail
            ),
        });
    }
    let unit = service_unit(home, entry, &absolute_program(node))?;
    write_unit(&unit)?;
    platform_install(&unit)?;
    Ok((unit, service_status()))
}

/// Install a rendered context connector. An identical installed unit is an
/// idempotent success. A different unit in this home's own service folder is
/// this home's connector with new parameters (a new build, PATH or folder), so
/// it is replaced and restarted; a label the manager holds with no unit here
/// belongs to another home and is refused.
pub fn install_connector_service(
    unit: &ServiceUnit,
    label: &str,
) -> Result<ServiceState, TeamsError> {
    let existing = named_service_status(label);
    if unit.path.exists() {
        let old = std::fs::read_to_string(&unit.path).map_err(|source| TeamsError::File {
            path: unit.path.clone(),
            source,
        })?;
        // A Windows unit's environment lives in its companion file, so that is compared too.
        let same = old == unit.text
            && unit
                .files
                .iter()
                .all(|(path, text)| std::fs::read_to_string(path).is_ok_and(|old| &old == text));
        if same && existing.installed {
            return Ok(existing);
        }
        if !same && existing.installed {
            named_platform_uninstall(label)?;
        }
    } else if existing.installed {
        return Err(TeamsError::Service {
            action: "install",
            detail: format!(
                "service manager already owns `{label}` without its expected unit file"
            ),
        });
    }
    write_unit(unit)?;
    named_platform_install(unit, label)?;
    Ok(named_service_status(label))
}

/// Give every installed harness supercode's messaging tools: register
/// `<supercode> message mcp` as a user-scope MCP server named `supercode`
/// through each harness's own `mcp add`. An entry that runs another binary
/// (an older install, a build that is gone) is replaced through the harness's
/// own `mcp remove`: a session loads only a server that starts. A harness
/// whose CLI is absent is left as it is. One line per harness says what
/// happened.
pub fn register_message_tools(supercode: &Path) -> Vec<String> {
    let program = supercode.display().to_string();
    let mut report = Vec::new();
    for (harness, get, remove, add) in [
        (
            "claude",
            vec!["mcp", "get", "supercode"],
            vec!["mcp", "remove", "--scope", "user", "supercode"],
            vec![
                "mcp",
                "add",
                "--scope",
                "user",
                "supercode",
                "--",
                &program,
                "message",
                "mcp",
            ],
        ),
        (
            "codex",
            vec!["mcp", "get", "supercode"],
            vec!["mcp", "remove", "supercode"],
            vec!["mcp", "add", "supercode", "--", &program, "message", "mcp"],
        ),
    ] {
        let run = |args: &[&str]| {
            std::process::Command::new(resolve_program(harness))
                .args(args)
                .stdin(std::process::Stdio::null())
                .output()
        };
        // Paths compare as text, and Windows paths without regard to case.
        let names_program = |text: &str| {
            if cfg!(windows) {
                text.to_lowercase().contains(&program.to_lowercase())
            } else {
                text.contains(&program)
            }
        };
        let replaced = match run(&get) {
            Err(_) => {
                report.push(format!("{harness}: not installed"));
                continue;
            }
            Ok(found)
                if found.status.success()
                    && names_program(&String::from_utf8_lossy(&found.stdout)) =>
            {
                report.push(format!("{harness}: already has supercode's tools"));
                continue;
            }
            Ok(found) if found.status.success() => {
                let _ = run(&remove);
                true
            }
            Ok(_) => false,
        };
        match run(&add) {
            Ok(added) if added.status.success() => report.push(if replaced {
                format!("{harness}: supercode's tools now run {program} (new sessions load them)")
            } else {
                format!("{harness}: supercode's tools added (new sessions load them)")
            }),
            Ok(added) => report.push(format!(
                "{harness}: could not add supercode's tools: {}",
                String::from_utf8_lossy(&added.stderr).trim()
            )),
            Err(error) => report.push(format!(
                "{harness}: could not add supercode's tools: {error}"
            )),
        }
    }
    report
}

/// Stop and remove exactly one context connector service.
pub fn uninstall_connector_service(
    teams_home: &Path,
    label: &str,
) -> Result<ServiceState, TeamsError> {
    named_platform_uninstall(label)?;
    let unit = teams_home
        .join(SERVICE_DIR)
        .join(format!("{label}.{}", connector_unit_suffix()));
    for path in [unit, service_env_path(teams_home, label)] {
        match std::fs::remove_file(&path) {
            Ok(()) => {}
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(source) => return Err(TeamsError::File { path, source }),
        }
    }
    Ok(named_service_status(label))
}

/// Read-only service-manager status for one context connector.
pub fn connector_service_status(label: &str) -> ServiceState {
    named_service_status(label)
}

/// Whether a service manager runs this OS user's machine daemon: the machine
/// unit, or a context connector unit written under the teams home, is
/// installed. Such a daemon is brought back by its service manager; nothing
/// else should start one in its place. Never starts or installs anything.
pub fn service_owns_daemon() -> bool {
    if service_status().installed {
        return true;
    }
    let Ok(entries) = std::fs::read_dir(teams_home().join(SERVICE_DIR)) else {
        return false;
    };
    entries.flatten().any(|entry| {
        let name = entry.file_name().to_string_lossy().into_owned();
        let label = name
            .strip_suffix(".plist")
            .or_else(|| name.strip_suffix(".service"))
            .unwrap_or(&name);
        label.starts_with("dev.volter.supercode-teams-connector-")
            && (name.ends_with(".plist") || name.ends_with(".service"))
            && connector_service_status(label).installed
    })
}

#[cfg(target_os = "macos")]
fn named_service_status(label: &str) -> ServiceState {
    let target = format!("{}/{label}", gui_domain());
    match run_tool("launchctl", &["print", &target]) {
        Ok((true, text)) => ServiceState {
            kind: "launchd",
            label: label.into(),
            installed: true,
            pid: field_of(&text, "pid = ").and_then(|value| value.parse().ok()),
            detail: field_of(&text, "state = ").unwrap_or_else(|| "loaded".into()),
        },
        Ok((false, _)) => ServiceState {
            kind: "launchd",
            label: label.into(),
            installed: false,
            pid: None,
            detail: format!("not bootstrapped in {}", gui_domain()),
        },
        Err(error) => ServiceState {
            kind: "launchd",
            label: label.into(),
            installed: false,
            pid: None,
            detail: format!("launchctl unavailable: {error}"),
        },
    }
}

#[cfg(all(unix, not(target_os = "macos")))]
fn named_service_status(label: &str) -> ServiceState {
    match run_tool("systemctl", &["--user", "is-active", label]) {
        Ok((active, text)) => {
            let known = run_tool("systemctl", &["--user", "is-enabled", label])
                .map(|(ok, _)| ok)
                .unwrap_or(false);
            ServiceState {
                kind: "systemd",
                label: label.into(),
                installed: active || known,
                pid: None,
                detail: if text.is_empty() {
                    "unknown".into()
                } else {
                    text
                },
            }
        }
        Err(error) => ServiceState {
            kind: "systemd",
            label: label.into(),
            installed: false,
            pid: None,
            detail: format!("systemctl unavailable: {error}"),
        },
    }
}

#[cfg(not(unix))]
fn named_service_status(label: &str) -> ServiceState {
    match run_tool("schtasks", &["/Query", "/TN", label, "/FO", "CSV", "/NH"]) {
        // `"TaskName","Next Run Time","Status"`: the last field is the task's state, in the system's language.
        Ok((true, text)) => ServiceState {
            kind: "schtasks",
            label: label.into(),
            installed: true,
            pid: None,
            detail: text
                .lines()
                .next()
                .and_then(|line| line.rsplit(',').next())
                .map(|state| state.trim_matches('"').to_string())
                .filter(|state| !state.is_empty())
                .unwrap_or_else(|| "registered".into()),
        },
        Ok((false, _)) => ServiceState {
            kind: "schtasks",
            label: label.into(),
            installed: false,
            pid: None,
            detail: "no scheduled task".into(),
        },
        Err(error) => ServiceState {
            kind: "schtasks",
            label: label.into(),
            installed: false,
            pid: None,
            detail: format!("schtasks unavailable: {error}"),
        },
    }
}

#[cfg(target_os = "macos")]
fn named_platform_install(unit: &ServiceUnit, _label: &str) -> Result<(), TeamsError> {
    platform_install(unit)
}
#[cfg(all(unix, not(target_os = "macos")))]
fn named_platform_install(unit: &ServiceUnit, label: &str) -> Result<(), TeamsError> {
    let path = unit.path.display().to_string();
    for args in [
        vec!["--user", "link", path.as_str()],
        vec!["--user", "enable", "--now", label],
    ] {
        let (ok, text) = run_tool("systemctl", &args).map_err(|error| TeamsError::Service {
            action: "install",
            detail: format!("systemctl: {error}"),
        })?;
        if !ok {
            return Err(TeamsError::Service {
                action: "install",
                detail: format!("systemctl {}: {text}", args.join(" ")),
            });
        }
    }
    Ok(())
}
#[cfg(not(unix))]
fn named_platform_install(unit: &ServiceUnit, label: &str) -> Result<(), TeamsError> {
    // Task Scheduler reads task XML only as UTF-16; the unit itself stays UTF-8 so an install can compare it.
    let task = unit.path.with_extension("utf16.xml");
    let bytes: Vec<u8> = [0xFF, 0xFE]
        .into_iter()
        .chain(unit.text.encode_utf16().flat_map(u16::to_le_bytes))
        .collect();
    std::fs::write(&task, bytes).map_err(|source| TeamsError::File {
        path: task.clone(),
        source,
    })?;
    let task_path = task.display().to_string();
    let created = run_tool(
        "schtasks",
        &["/Create", "/TN", label, "/XML", task_path.as_str(), "/F"],
    )
    .map_err(|error| TeamsError::Service {
        action: "install",
        detail: format!("schtasks: {error}"),
    })
    .and_then(|(ok, text)| {
        if ok {
            Ok(())
        } else {
            Err(TeamsError::Service {
                action: "install",
                detail: format!("schtasks /Create: {text}"),
            })
        }
    });
    if let Err(error) = created {
        let _ = std::fs::remove_file(&task);
        return Err(error);
    }
    // A task already running keeps its old instance: Task Scheduler refuses a
    // second one (0x800710E0) while `/Run` still reports success, so the
    // replaced connector would go on running the old code. End it first; a
    // task that is not running answers an error here, which is fine.
    let _ = run_tool("schtasks", &["/End", "/TN", label]);
    let result = [vec!["/Run", "/TN", label]].iter().try_for_each(|args| {
        let (ok, text) = run_tool("schtasks", args).map_err(|error| TeamsError::Service {
            action: "install",
            detail: format!("schtasks: {error}"),
        })?;
        if ok {
            Ok(())
        } else {
            Err(TeamsError::Service {
                action: "install",
                detail: format!("schtasks {}: {text}", args[0]),
            })
        }
    });
    let _ = std::fs::remove_file(&task);
    result
}

#[cfg(target_os = "macos")]
fn named_platform_uninstall(label: &str) -> Result<(), TeamsError> {
    let target = format!("{}/{label}", gui_domain());
    let (ok, text) =
        run_tool("launchctl", &["bootout", &target]).map_err(|error| TeamsError::Service {
            action: "uninstall",
            detail: format!("launchctl: {error}"),
        })?;
    if !ok && !text.contains("No such process") && !text.contains("not find") {
        return Err(TeamsError::Service {
            action: "uninstall",
            detail: format!("launchctl bootout {target}: {text}"),
        });
    }
    // bootout returns before launchd has let the label go, and a bootstrap
    // in that window fails with an I/O error; wait for it to be released.
    for _ in 0..50 {
        if !named_service_status(label).installed {
            break;
        }
        std::thread::sleep(std::time::Duration::from_millis(100));
    }
    Ok(())
}
#[cfg(all(unix, not(target_os = "macos")))]
fn named_platform_uninstall(label: &str) -> Result<(), TeamsError> {
    let _ = run_tool("systemctl", &["--user", "disable", "--now", label]);
    Ok(())
}
#[cfg(not(unix))]
fn named_platform_uninstall(label: &str) -> Result<(), TeamsError> {
    // The task goes first, so its minute trigger cannot start the service again while it is being stopped.
    let (ok, text) = run_tool("schtasks", &["/Delete", "/TN", label, "/F"]).map_err(|error| {
        TeamsError::Service {
            action: "uninstall",
            detail: format!("schtasks: {error}"),
        }
    })?;
    if !ok && named_service_status(label).installed {
        return Err(TeamsError::Service {
            action: "uninstall",
            detail: format!("schtasks /Delete: {text}"),
        });
    }
    // Deleting a task leaves what it started running, so the service is stopped by the one thing on its command
    // line that is its own: the environment file, on a node or its conhost. The path rides in the environment, not
    // the command line, so this query does not match itself.
    let env_path = service_env_path(&teams_home(), label);
    let stopped = std::process::Command::new("powershell.exe")
        .args([
            "-NoProfile",
            "-NonInteractive",
            "-Command",
            "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='conhost.exe'\" | Where-Object { $_.CommandLine -and $_.CommandLine.Contains($env:SUPERCODE_SERVICE_ENV_FILE) } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
        ])
        .env("SUPERCODE_SERVICE_ENV_FILE", env_path.display().to_string())
        .stdin(std::process::Stdio::null())
        .output();
    match stopped {
        Ok(output) if output.status.success() => Ok(()),
        Ok(output) => Err(TeamsError::Service {
            action: "uninstall",
            detail: format!(
                "the task is gone, but what it started may still run: {}",
                String::from_utf8_lossy(&output.stderr).trim()
            ),
        }),
        Err(error) => Err(TeamsError::Service {
            action: "uninstall",
            detail: format!(
                "the task is gone, but what it started may still run: powershell: {error}"
            ),
        }),
    }
}

#[cfg(target_os = "macos")]
fn platform_install(unit: &ServiceUnit) -> Result<(), TeamsError> {
    let path = unit.path.display().to_string();
    let (ok, text) =
        run_tool("launchctl", &["bootstrap", &gui_domain(), &path]).map_err(|error| {
            TeamsError::Service {
                action: "install",
                detail: format!("launchctl: {error}"),
            }
        })?;
    if !ok {
        return Err(TeamsError::Service {
            action: "install",
            detail: format!("launchctl bootstrap {}: {text}", gui_domain()),
        });
    }
    Ok(())
}

/// Untested on this box (the receipt is macOS); these are the commands
/// `service_unit` prints as its `install_command`.
#[cfg(all(unix, not(target_os = "macos")))]
fn platform_install(unit: &ServiceUnit) -> Result<(), TeamsError> {
    let path = unit.path.display().to_string();
    for args in [
        vec!["--user", "link", path.as_str()],
        vec!["--user", "enable", "--now", SERVICE_NAME],
    ] {
        let (ok, text) = run_tool("systemctl", &args).map_err(|error| TeamsError::Service {
            action: "install",
            detail: format!("systemctl: {error}"),
        })?;
        if !ok {
            return Err(TeamsError::Service {
                action: "install",
                detail: format!("systemctl {}: {text}", args.join(" ")),
            });
        }
    }
    Ok(())
}

#[cfg(not(unix))]
fn platform_install(unit: &ServiceUnit) -> Result<(), TeamsError> {
    named_platform_install(unit, SERVICE_NAME)
}

/// Stop and unregister the unit, and remove the rendered file.
///
/// Idempotent: a unit the manager does not hold is not an error, because the
/// state the operator asked for is the state they get.
pub fn uninstall_service(home: &Path) -> Result<ServiceState, TeamsError> {
    platform_uninstall()?;
    let unit_path = home.join(SERVICE_DIR).join(unit_file_name());
    // A Windows unit's environment file goes with it; elsewhere there is none and its absence is fine.
    for path in [unit_path, service_env_path(home, SERVICE_NAME)] {
        match std::fs::remove_file(&path) {
            Ok(()) => {}
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(source) => return Err(TeamsError::File { path, source }),
        }
    }
    // `launchctl bootout` returns before the job is torn down, so the state
    // this reports is the settled one, not the manager mid-teardown.
    let mut state = service_status();
    for _ in 0..40 {
        if !state.installed {
            break;
        }
        std::thread::sleep(std::time::Duration::from_millis(100));
        state = service_status();
    }
    Ok(state)
}

#[cfg(target_os = "macos")]
fn platform_uninstall() -> Result<(), TeamsError> {
    let target = format!("{}/{SERVICE_NAME}", gui_domain());
    let (ok, text) =
        run_tool("launchctl", &["bootout", &target]).map_err(|error| TeamsError::Service {
            action: "uninstall",
            detail: format!("launchctl: {error}"),
        })?;
    // `bootout` on a label nobody holds says so and exits non-zero.
    if !ok && !text.contains("No such process") && !text.contains("not find") {
        return Err(TeamsError::Service {
            action: "uninstall",
            detail: format!("launchctl bootout {target}: {text}"),
        });
    }
    Ok(())
}

#[cfg(all(unix, not(target_os = "macos")))]
fn platform_uninstall() -> Result<(), TeamsError> {
    let _ = run_tool("systemctl", &["--user", "disable", "--now", SERVICE_NAME]);
    Ok(())
}

#[cfg(not(unix))]
fn platform_uninstall() -> Result<(), TeamsError> {
    named_platform_uninstall(SERVICE_NAME)
}