Skip to content

armgit / muxin

Public Imported from GitHub
0

All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.

66.8 KB
Raw Blame
//! Agent workspaces: a folder on a fleet machine (optionally a git checkout)
//! that an AI agent working elsewhere checks out as its work environment —
//! runs commands, reads and writes files, syncs a local tree. An agent that
//! lives in its environment and works by itself is a box (fleet::boxes).
//!
//! Workspaces persist until destroyed; nothing is cleaned up automatically.
//! They live in `<config dir>/workspaces.json` so the window and every agent
//! process (MCP server, CLI) see the same set.
//!
//! Path checks keep agents from wandering out of a workspace by mistake; they
//! aren't a sandbox — `workspace_exec` runs whatever it's given as the
//! machine's ssh user.
//!
//! PUBLIC API — the UI, the MCP server and the CLI depend on these signatures.

mod demo;
mod registry;
pub(crate) mod transport;

use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, Instant};

use base64::Engine as _;
use base64::engine::general_purpose::STANDARD as B64;
use chrono::Utc;
use serde::{Deserialize, Serialize};

use super::Engine;
use super::model::{Machine, WorkspaceCommand, WorkspaceInfo};
use crate::config::MachineSpec;
use crate::ops::remote::{self, Param, ps_quote, sh_quote, with_params};
use crate::probe::Shell;
pub(crate) use registry::WorkspaceRecord;
use transport::{Limits, Output};

pub use demo::DemoTree;

const LIB_SH: &str = include_str!("scripts/lib.sh");
const EXEC_SH: &str = include_str!("scripts/exec.sh");
const EXEC_PS1: &str = include_str!("scripts/exec.ps1");
const FILES_SH: &str = include_str!("scripts/files.sh");
const FILES_PS1: &str = include_str!("scripts/files.ps1");
const CHANGES_SH: &str = include_str!("scripts/changes.sh");
const CREATE_SH: &str = include_str!("scripts/create.sh");
const DESTROY_SH: &str = include_str!("scripts/destroy.sh");
const WORKTREE_SH: &str = include_str!("scripts/worktree.sh");
const OTHER_PS1: &str = include_str!("scripts/other.ps1");
const DOCKER_SH: &str = include_str!("scripts/docker.sh");
const EXEC_DOCKER_SH: &str = include_str!("scripts/exec_docker.sh");

/// Image for docker workspaces when none is given: Debian with git, curl and
/// a compiler toolchain (what the official language images build on).
pub const DEFAULT_IMAGE: &str = "buildpack-deps:bookworm";

const DEFAULT_ROOT: &str = "~/muxen/workspaces";
const DEFAULT_ROOT_WINDOWS: &str = "~\\muxen\\workspaces";

pub const EXEC_TIMEOUT_DEFAULT: u64 = 600;
pub const EXEC_TIMEOUT_MAX: u64 = 3600;
/// Extra time Muxin waits beyond the command's own timeout before hanging up.
const EXEC_GRACE: u64 = 30;
const FILE_TIMEOUT: Duration = Duration::from_secs(60);
const CREATE_TIMEOUT: Duration = Duration::from_secs(15 * 60);
const DESTROY_TIMEOUT: Duration = Duration::from_secs(2 * 60);
const SYNC_TIMEOUT: Duration = Duration::from_secs(30 * 60);
pub const READ_DEFAULT: usize = 256 * 1024;
pub const READ_MAX: usize = 1024 * 1024;
pub const WRITE_MAX: usize = 5 * 1024 * 1024;
pub const LIST_DEPTH_DEFAULT: u32 = 2;
pub const LIST_DEPTH_MAX: u32 = 10;
pub const LIST_MAX_ENTRIES: usize = 2000;
const CHANGES_LIMITS: Limits = Limits { head: 60 * 1024, tail: 4 * 1024, line: 4 * 1024 };
const COMMAND_MAX: usize = 64 * 1024;
const TAIL_LINE_MAX: usize = 400;
/// Machines with less free disk than this aren't picked automatically.
const MIN_FREE_DISK: u64 = 5_000_000_000;

/// Where and what to create.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct CreateWorkspace {
    /// Machine id. None picks the least-loaded online machine that allows workspaces
    /// (and matches `platform` when given).
    pub machine: Option<String>,
    /// Platform prefix to match when picking a machine: "linux", "linux-x64", "darwin-arm64", "windows".
    pub platform: Option<String>,
    /// Label; defaults to the repo name, else the id.
    pub name: Option<String>,
    /// Git URL, or "owner/repo" for GitHub.
    pub repo: Option<String>,
    /// Branch, tag or commit to check out.
    pub git_ref: Option<String>,
    /// Create and switch to a new branch after checkout.
    pub branch: Option<String>,
    /// Who is creating it ("claude-code", "cli", "app", ...).
    pub owner: Option<String>,
    /// A git checkout on the machine (its folder): the workspace is a git
    /// worktree of it, on `branch` (from `git_ref`, else the default branch),
    /// instead of a fresh clone. Several agents can then work on one
    /// repository there at once. Needs `machine`; not with docker.
    pub worktree_of: Option<String>,
}

/// How a workspace's commands run. Separate from `CreateWorkspace` so existing
/// callers keep compiling; `create_workspace` uses the default (host).
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct WorkspaceIsolation {
    /// "host" (default): commands run directly on the machine as the ssh user.
    /// "docker": a fresh container per workspace, with the folder mounted at /workspace.
    pub isolation: Option<String>,
    /// Docker image, e.g. "node:22", "rust:1", "python:3.13". Defaults to `DEFAULT_IMAGE`.
    pub image: Option<String>,
    /// Share the host's docker socket with the container (docker-in-docker). Off by default.
    pub docker_socket: bool,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct ExecOptions {
    /// Seconds before the command is killed (default 600, max 3600). Ignored for background commands.
    pub timeout_secs: Option<u64>,
    pub env: Vec<(String, String)>,
    /// Folder relative to the workspace to run in.
    pub cwd: Option<String>,
    /// Start it detached (dev servers, watchers); output goes to a log file in the workspace.
    pub background: bool,
    pub by: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ExecResult {
    /// None if it timed out or runs in the background.
    pub exit_code: Option<i32>,
    pub stdout: String,
    pub stderr: String,
    pub duration_ms: u64,
    pub timed_out: bool,
    /// Output was longer than the cap; the middle was dropped.
    pub truncated: bool,
    pub background_pid: Option<u32>,
    /// Background commands: log file path relative to the workspace.
    pub log_path: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct FileContent {
    pub path: String,
    pub content: String,
    pub size: u64,
    pub truncated: bool,
    /// Not valid UTF-8; `content` is empty.
    pub binary: bool,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct FileEntry {
    /// Relative to the workspace.
    pub path: String,
    /// "file" | "dir" | "link"
    pub kind: String,
    pub size: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum SyncDirection {
    /// Local folder → workspace.
    Push,
    /// Workspace → local folder.
    Pull,
}

impl Engine {
    /// Creates a workspace and waits until it's ready (folder made, repo cloned).
    #[cfg_attr(not(test), allow(dead_code))]
    pub async fn create_workspace(self: &Arc<Self>, req: CreateWorkspace) -> Result<WorkspaceInfo, String> {
        self.create_workspace_with(req, WorkspaceIsolation::default()).await
    }

    /// Like `create_workspace`, choosing how commands run: on the host, or in a
    /// fresh docker container (folder mounted at /workspace).
    pub async fn create_workspace_with(self: &Arc<Self>, req: CreateWorkspace, iso: WorkspaceIsolation) -> Result<WorkspaceInfo, String> {
        self.refresh_from_disk();
        let docker = match clean_opt(iso.isolation).map(|s| s.to_ascii_lowercase()).as_deref() {
            None | Some("host") | Some("none") => false,
            Some("docker") | Some("container") => true,
            Some(other) => return Err(format!("\"{other}\" isn't an isolation Muxin knows. Use \"host\" or \"docker\".")),
        };
        let image_req = clean_opt(iso.image);
        if !docker && image_req.is_some() {
            return Err("An image only applies to docker workspaces; pass isolation \"docker\" too.".into());
        }
        let image = if docker { Some(validate_image(image_req.as_deref().unwrap_or(DEFAULT_IMAGE))?) } else { None };
        let name = clean_opt(req.name);
        if let Some(n) = &name {
            if n.chars().count() > 80 || n.chars().any(char::is_control) {
                return Err("The workspace name is too long or has odd characters.".into());
            }
        }
        let git_ref = clean_opt(req.git_ref);
        let branch = clean_opt(req.branch);
        for r in git_ref.iter().chain(branch.iter()) {
            validate_git_ref(r)?;
        }
        let settings = self.settings();
        let gh_host = github_web_host(&settings.github.api_url);
        let worktree_of = clean_opt(req.worktree_of);
        if let Some(src) = &worktree_of {
            if docker {
                return Err("A worktree runs on the machine itself, not in a container: leave out isolation \"docker\".".into());
            }
            if clean_opt(req.machine.clone()).is_none() {
                return Err(format!("Say which machine {src} is on (machine)."));
            }
            if src.chars().any(char::is_control) {
                return Err("That checkout's folder has odd characters.".into());
            }
        }
        // A worktree's repository is the checkout's; nothing is cloned.
        let repo = match &worktree_of {
            Some(_) => None,
            None => clean_opt(req.repo.clone()).map(|r| normalize_repo(&r, &gh_host)).transpose()?,
        };
        if repo.is_none() && worktree_of.is_none() && (git_ref.is_some() || branch.is_some()) {
            return Err("gitRef and branch need a repo to clone.".into());
        }

        // Pick the machine and make sure we know what it runs.
        let snap = self.current();
        let machine_id = match clean_opt(req.machine) {
            Some(m) => {
                let found = snap
                    .machines
                    .iter()
                    .find(|x| x.id == m || x.name.eq_ignore_ascii_case(&m))
                    .ok_or_else(|| format!("Machine \"{m}\" not found. Known machines: {}.", machine_names(&snap.machines)))?;
                if found.host.is_empty() {
                    return Err(format!("{} has no host in config.toml, so Muxin can't reach it.", found.name));
                }
                if !found.workspaces_allowed {
                    return Err(format!(
                        "Workspaces are turned off for {}. Turn them on from its page in Muxin, or remove `workspaces = false` from its entry in config.toml.",
                        found.name
                    ));
                }
                found.id.clone()
            }
            None => pick_machine_for(&snap.machines, clean_opt(req.platform).as_deref(), docker)?.id.clone(),
        };
        let (spec, mut probe) = self.machine(&machine_id).ok_or("Machine not found in config.toml anymore.")?;
        if self.demo_world().is_none() && !probe.as_ref().is_some_and(|p| p.ok) {
            self.run_check(Some(vec![spec.id.clone()])).await;
            probe = self.machine(&spec.id).and_then(|(_, p)| p);
            match &probe {
                Some(p) if p.ok => {}
                Some(p) => return Err(format!("{} is unreachable: {}", spec.name, p.error.clone().unwrap_or_default())),
                None => return Err(format!("{} is unreachable: the check didn't run.", spec.name)),
            }
        }
        let windows = remote::shell_for(&spec, probe.as_ref()) == Shell::Powershell;
        if docker && windows {
            return Err(format!("Docker workspaces aren't supported on Windows machines yet ({}). Use isolation \"host\" there.", spec.name));
        }
        let machine = self.current().machines.iter().find(|m| m.id == spec.id).cloned();
        // A worktree's repository is its checkout's: look at the machine's checkouts if that's not been done.
        if worktree_of.is_some() && self.checkouts_of(&spec.id).is_empty() {
            let _ = self.refresh_checkouts(&spec.id).await;
        }

        let id = self.unused_workspace_id();
        let root = spec.workspace_root.clone().filter(|r| !r.trim().is_empty()).unwrap_or_else(|| {
            if windows { DEFAULT_ROOT_WINDOWS.into() } else { DEFAULT_ROOT.into() }
        });
        let sep = if windows { "\\" } else { "/" };
        let now = Utc::now();
        let info = WorkspaceInfo {
            id: id.clone(),
            name: name.unwrap_or_else(|| repo.as_ref().map(|r| r.short_name.clone()).unwrap_or_else(|| id.clone())),
            machine_id: spec.id.clone(),
            machine_name: spec.name.clone(),
            host: spec.host.trim().to_string(),
            platform: machine.as_ref().map(|m| m.platform.clone()).unwrap_or_default(),
            path: format!("{}{sep}{id}", root.trim_end_matches(['/', '\\'])),
            repo: match &worktree_of {
                Some(src) => self.checkouts_of(&spec.id).into_iter().find(|c| same_folder(&c.path, src)).and_then(|c| c.repo).or_else(|| clean_opt(req.repo.clone())),
                None => repo.as_ref().map(|r| r.shown.clone()),
            },
            git_ref: git_ref.clone(),
            // A worktree works on a branch of its own: the one asked for, else one named after it.
            branch: match (&worktree_of, &branch, &git_ref) {
                (Some(_), None, None) => Some(id.clone()),
                _ => branch.clone(),
            },
            owner: clean_opt(req.owner),
            status: "creating".into(),
            error: None,
            created_at: now,
            last_used_at: now,
            commands: 0,
            history: Vec::new(),
            shell: String::new(),
            isolation: if docker { "docker" } else { "host" }.into(),
            image: image.clone(),
            container: docker.then(|| container_name(&id)),
            worktree_of: worktree_of.clone(),
            git: None,
        };
        let record = WorkspaceRecord { info, background_pids: Vec::new(), windows, next_log: 1, docker_socket: docker && iso.docker_socket };
        self.update_workspaces(|list| list.push(record.clone()))?;

        let title = match &image {
            Some(img) => format!("Create workspace {id} on {} ({img})", spec.name),
            None => format!("Create workspace {id} on {}", spec.name),
        };
        let op = self.begin_op("workspace", title, Some(spec.id.clone()), None);
        let result = match self.demo_world() {
            Some(_) => demo::create(self, op, &record, repo.as_ref().map(|r| r.shown.as_str())).await.map_err(|e| (e, None)),
            None => self.run_create(op, &spec, &record, &root, repo.as_ref()).await,
        };
        let finished = match result {
            Ok(path) => {
                self.update_workspaces(|list| {
                    if let Some(r) = list.iter_mut().find(|r| r.info.id == id) {
                        r.info.status = "ready".into();
                        r.info.path = path.clone();
                        r.info.last_used_at = Utc::now();
                    }
                })?;
                self.op_log(op, format!("✓ Workspace {id} is ready at {path}"));
                self.op_finish(op, Ok(()));
                Ok(())
            }
            Err((e, folder)) => {
                // Keep the folder's path (if one was made) so destroying the workspace cleans it up.
                let _ = self.update_workspaces(|list| {
                    if let Some(r) = list.iter_mut().find(|r| r.info.id == id) {
                        r.info.status = "failed".into();
                        r.info.error = Some(e.clone());
                        if let Some(p) = folder.clone() {
                            r.info.path = p;
                        }
                    }
                });
                self.op_log(op, format!("error: {e}"));
                self.op_finish(op, Err(e.clone()));
                Err(e)
            }
        };
        finished?;
        self.workspace_info(&id).ok_or_else(|| "The workspace was created but then disappeared.".to_string())
    }

    /// Runs a shell command in the workspace with the machine user's login environment.
    pub async fn workspace_exec(self: &Arc<Self>, id: &str, command: &str, opts: ExecOptions) -> Result<ExecResult, String> {
        let command = command.trim();
        if command.is_empty() {
            return Err("Give a command to run.".into());
        }
        if command.len() > COMMAND_MAX {
            return Err("That command is too long; write a script file with workspace_write_file and run it.".into());
        }
        let rec = self.ready_workspace(id)?;
        let cwd = match opts.cwd.as_deref() {
            Some(c) => rel_path(c)?,
            None => String::new(),
        };
        for (k, v) in &opts.env {
            validate_env(k, v)?;
        }
        let timeout = opts.timeout_secs.unwrap_or(EXEC_TIMEOUT_DEFAULT).clamp(1, EXEC_TIMEOUT_MAX);
        let started_at = Utc::now();
        let started = Instant::now();

        let result = match self.demo_world() {
            Some(_) => demo::exec(self, &rec, command, &cwd, opts.background).await?,
            None => {
                let spec = self.workspace_machine(&rec)?;
                let log = if opts.background {
                    let n = self.update_workspaces(|list| {
                        list.iter_mut().find(|r| r.info.id == rec.info.id).map(|r| {
                            let n = r.next_log.max(1);
                            r.next_log = n + 1;
                            n
                        })
                    })?;
                    Some(format!(".muxen/logs/{}.log", n.unwrap_or(1)))
                } else {
                    None
                };
                self.run_exec(&spec, &rec, command, &cwd, &opts.env, timeout, log).await?
            }
        };

        let duration_ms = started.elapsed().as_millis() as u64;
        let result = ExecResult { duration_ms, ..result };
        let entry = WorkspaceCommand {
            command: command.to_string(),
            exit_code: result.exit_code,
            started_at,
            duration_ms,
            output_tail: output_tail(&result.stdout, &result.stderr),
            background: opts.background,
            timed_out: result.timed_out,
            by: clean_opt(opts.by),
        };
        let pid = result.background_pid;
        self.update_workspaces(|list| {
            if let Some(r) = list.iter_mut().find(|r| r.info.id == rec.info.id) {
                r.info.history.push(entry);
                registry::cap_history(&mut r.info);
                r.info.commands += 1;
                r.info.last_used_at = Utc::now();
                // Container pids mean nothing on the host; removing the container stops those.
                if let (Some(p), None) = (pid, &r.info.container) {
                    r.background_pids.push(p);
                }
            }
        })?;
        Ok(result)
    }

    pub async fn workspace_read_file(&self, id: &str, path: &str, max_bytes: usize) -> Result<FileContent, String> {
        let rec = self.ready_workspace(id)?;
        let rel = rel_path(path)?;
        if rel.is_empty() {
            return Err("Give the path of a file in the workspace.".into());
        }
        let max = if max_bytes == 0 { READ_DEFAULT } else { max_bytes.min(READ_MAX) };
        if let Some(w) = self.demo_world() {
            return demo::read(w, &rec, &rel, max);
        }
        let spec = self.workspace_machine(&rec)?;
        let max_s = max.to_string();
        let out = self
            .run_files(&spec, &rec, &[("OR_ACTION", Param::Str("read")), ("OR_REL", Param::Str(&rel)), ("OR_MAX", Param::Str(&max_s))])
            .await?;
        let size: u64 = field(&out.stdout, "size").and_then(|s| s.parse().ok()).unwrap_or(0);
        let data = field(&out.stdout, "data").unwrap_or_default();
        let bytes = B64.decode(data.trim()).map_err(|e| format!("Couldn't decode the file from the machine: {e}"))?;
        Ok(file_content(rel, bytes, size, max))
    }

    /// Writes (or appends) a text file, creating parent folders. Returns the new size.
    pub async fn workspace_write_file(&self, id: &str, path: &str, content: &str, append: bool) -> Result<u64, String> {
        let rec = self.ready_workspace(id)?;
        let rel = rel_path(path)?;
        if rel.is_empty() {
            return Err("Give the path of a file in the workspace.".into());
        }
        if content.len() > WRITE_MAX {
            return Err(format!("That's more than {} — copy big files with workspace_sync instead.", crate::util::bytes(WRITE_MAX as u64)));
        }
        let size = match self.demo_world() {
            Some(w) => demo::write(w, &rec, &rel, content, append),
            None => {
                let spec = self.workspace_machine(&rec)?;
                let encoded = B64.encode(content.as_bytes());
                let out = self
                    .run_files(
                        &spec,
                        &rec,
                        &[
                            ("OR_ACTION", Param::Str("write")),
                            ("OR_REL", Param::Str(&rel)),
                            ("OR_B64", Param::Str(&encoded)),
                            ("OR_APPEND", Param::Bool(append)),
                        ],
                    )
                    .await?;
                field(&out.stdout, "size").and_then(|s| s.parse().ok()).unwrap_or(content.len() as u64)
            }
        };
        self.touch_workspace(&rec.info.id);
        Ok(size)
    }

    pub async fn workspace_list_files(&self, id: &str, path: &str, depth: u32) -> Result<Vec<FileEntry>, String> {
        let rec = self.ready_workspace(id)?;
        let rel = rel_path(path)?;
        let depth = if depth == 0 { LIST_DEPTH_DEFAULT } else { depth.min(LIST_DEPTH_MAX) };
        if let Some(w) = self.demo_world() {
            return demo::list(w, &rec, &rel, depth);
        }
        let spec = self.workspace_machine(&rec)?;
        let depth_s = depth.to_string();
        let out = self
            .run_files(&spec, &rec, &[("OR_ACTION", Param::Str("list")), ("OR_REL", Param::Str(&rel)), ("OR_DEPTH", Param::Str(&depth_s))])
            .await?;
        Ok(parse_listing(&out.stdout, &rel))
    }

    /// `git status` plus the diff of uncommitted changes (capped), or a note when it isn't a git checkout.
    pub async fn workspace_changes(&self, id: &str) -> Result<String, String> {
        let rec = self.ready_workspace(id)?;
        if let Some(w) = self.demo_world() {
            return Ok(demo::changes(w, &rec));
        }
        let spec = self.workspace_machine(&rec)?;
        let (script, windows) = if rec.windows {
            (with_params(Shell::Powershell, &[("OR_ACTION", Param::Str("changes")), ("OR_DIR", Param::Str(&rec.info.path))], OTHER_PS1), true)
        } else {
            (with_params(Shell::Sh, &[("OR_DIR", Param::Str(&rec.info.path))], CHANGES_SH), false)
        };
        let out = run_checked(&spec, windows, script, FILE_TIMEOUT, CHANGES_LIMITS, &[], None).await?;
        let mut text = out.stdout;
        if out.truncated {
            text.push_str("\n[the diff was cut; run `git diff` with workspace_exec for the rest]");
        }
        Ok(text)
    }

    /// rsync between a folder on this computer and the workspace. Returns rsync's summary.
    pub async fn workspace_sync(self: &Arc<Self>, id: &str, local_path: &str, direction: SyncDirection, delete: bool) -> Result<String, String> {
        let rec = self.ready_workspace(id)?;
        let local = expand_home(local_path.trim());
        if local.as_os_str().is_empty() {
            return Err("Give a local folder to sync.".into());
        }
        if let Some(_w) = self.demo_world() {
            let summary = demo::sync(&rec, &local, direction, delete).await;
            self.touch_workspace(&rec.info.id);
            return Ok(summary);
        }
        let spec = self.workspace_machine(&rec)?;
        if rec.windows {
            // Boxed: a copy's future is big, and this one sits inside every caller's.
            return Box::pin(self.sync_through_agent(&rec, &spec, &local, direction, delete)).await;
        }
        let have_rsync = tokio::process::Command::new("rsync")
            .arg("--version")
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .status()
            .await
            .is_ok_and(|s| s.success());
        if !have_rsync {
            return Err("rsync isn't installed on this computer, so Muxin can't sync folders.".into());
        }
        match direction {
            SyncDirection::Push if !local.is_dir() => return Err(format!("{} isn't a folder on this computer.", local.display())),
            SyncDirection::Pull => std::fs::create_dir_all(&local).map_err(|e| format!("Couldn't create {}: {e}", local.display()))?,
            _ => {}
        }
        let args = rsync_args(&spec, &rec.info.path, &local.to_string_lossy(), direction, delete);
        let run = tokio::process::Command::new("rsync").args(&args).kill_on_drop(true).output();
        let output = tokio::time::timeout(SYNC_TIMEOUT, run)
            .await
            .map_err(|_| "The sync took longer than 30 minutes and was stopped.".to_string())?
            .map_err(|e| format!("Couldn't run rsync: {e}"))?;
        if !output.status.success() {
            let err = String::from_utf8_lossy(&output.stderr);
            let tail: Vec<&str> = err.lines().filter(|l| !l.trim().is_empty()).rev().take(4).collect();
            return Err(format!("rsync failed: {}", tail.into_iter().rev().collect::<Vec<_>>().join(" ")));
        }
        self.touch_workspace(&rec.info.id);
        let out = String::from_utf8_lossy(&output.stdout);
        let lines: Vec<&str> = out.lines().filter(|l| !l.trim().is_empty()).collect();
        Ok(lines[lines.len().saturating_sub(16)..].join("\n"))
    }

    /// Sync with a Windows machine (no rsync there): the folder's contents
    /// copied over through the agents, as Copy files does. Files are added and
    /// replaced; nothing is deleted.
    async fn sync_through_agent(self: &Arc<Self>, rec: &WorkspaceRecord, spec: &MachineSpec, local: &std::path::Path, direction: SyncDirection, delete: bool) -> Result<String, String> {
        if delete {
            return Err(format!("Syncing with {} adds and replaces files but doesn't delete any (it's a Windows machine): sync without delete.", spec.name));
        }
        let here = crate::config::Inventory::parse("[[machine]]\nname = \"This computer\"\nhost = \"local\"\n").map_err(|e| e.to_string())?.machines.remove(0);
        let here = self.current().machines.iter().find(|m| m.local).and_then(|m| self.machine(&m.id)).map(|(s, _)| s).unwrap_or(here);
        let skip = [".muxen", ".git", "node_modules", "target"];
        let (from, dir, to, to_dir) = match direction {
            SyncDirection::Push => {
                if !local.is_dir() {
                    return Err(format!("{} isn't a folder on this computer.", local.display()));
                }
                (here.clone(), local.display().to_string(), spec.clone(), rec.info.path.clone())
            }
            SyncDirection::Pull => {
                std::fs::create_dir_all(local).map_err(|e| format!("Couldn't create {}: {e}", local.display()))?;
                (spec.clone(), rec.info.path.clone(), here.clone(), local.display().to_string())
            }
        };
        let listing = self.list_files(&from.id, &dir).await?;
        let names: Vec<String> = listing.entries.iter().map(|e| e.name.clone()).filter(|n| !skip.contains(&n.as_str())).collect();
        if names.is_empty() {
            return Ok("Nothing to copy.".into());
        }
        let op = self.begin_op("copy", format!("Sync {} with {}", rec.info.id, spec.name), Some(spec.id.clone()), None);
        let no_git = direction == SyncDirection::Pull;
        let result = self.run_copy(op, &from, &dir, &names, &to, &to_dir, &std::sync::atomic::AtomicBool::new(false), no_git).await;
        self.op_finish(op, result.as_ref().map(|_| ()).map_err(|e| e.clone()));
        let bytes = result?;
        self.touch_workspace(&rec.info.id);
        Ok(format!("Copied {} item{} ({}) {} {}.", names.len(), if names.len() == 1 { "" } else { "s" }, crate::util::bytes(bytes), if matches!(direction, SyncDirection::Push) { "to" } else { "from" }, spec.name))
    }

    /// Stops background commands and removes the workspace (and its folder unless `keep_files`).
    pub async fn destroy_workspace(self: &Arc<Self>, id: &str, keep_files: bool) -> Result<(), String> {
        self.refresh_from_disk();
        let rec = self.find_workspace(id)?;
        let wid = rec.info.id.clone();
        let title = if keep_files { format!("Forget workspace {wid}") } else { format!("Delete workspace {wid}") };
        let op = self.begin_op("workspace", title, Some(rec.info.machine_id.clone()), None);
        let previous = rec.info.status.clone();
        self.update_workspaces(|list| {
            if let Some(r) = list.iter_mut().find(|r| r.info.id == wid) {
                r.info.status = "destroying".into();
            }
        })?;

        // A path still starting with "~" was never confirmed by the machine: no folder was made.
        let has_folder = !rec.info.path.starts_with('~');
        let cleaned: Result<(), String> = match (self.demo_world(), self.machine(&rec.info.machine_id)) {
            (Some(_), _) => demo::destroy(self, op, &rec, keep_files).await,
            (None, Some((spec, _))) if spec.is_checkable() && has_folder => self.run_destroy(op, &spec, &rec, keep_files).await,
            (None, Some(_)) => {
                self.op_log(op, format!("No folder was created on {}; forgetting the workspace.", rec.info.machine_name));
                Ok(())
            }
            (None, None) => {
                self.op_log(op, format!("warning: {} isn't in config.toml anymore, so its files can't be cleaned up; forgetting the workspace.", rec.info.machine_name));
                Ok(())
            }
        };
        match cleaned {
            Ok(()) => {
                self.update_workspaces(|list| list.retain(|r| r.info.id != wid))?;
                self.op_log(op, format!("✓ Workspace {wid} is gone"));
                self.op_finish(op, Ok(()));
                Ok(())
            }
            Err(e) => {
                let _ = self.update_workspaces(|list| {
                    if let Some(r) = list.iter_mut().find(|r| r.info.id == wid) {
                        r.info.status = previous.clone();
                    }
                });
                self.op_log(op, format!("error: {e}"));
                self.op_finish(op, Err(e.clone()));
                Err(e)
            }
        }
    }

    /// Current workspaces, most recently used first.
    pub fn workspaces(&self) -> Vec<WorkspaceInfo> {
        self.current().workspaces.clone()
    }

    /// Turns agent workspaces on or off for a machine (edits config.toml).
    pub fn set_workspaces_allowed(self: &Arc<Self>, machine_id: &str, allowed: bool) -> Result<(), String> {
        if self.machine(machine_id).is_none() {
            return Err(format!("Machine \"{machine_id}\" not found in config.toml."));
        }
        let edit = |text: &str| crate::ops::inventory_edit::set_workspaces(text, machine_id, allowed);
        match self.demo_world() {
            Some(w) => w.edit_inventory(edit)?,
            None => crate::ops::inventory_edit::edit_file(self.inventory_path(), edit)?,
        }
        self.reload_inventory_now();
        Ok(())
    }

    // -----------------------------------------------------------------------

    fn find_workspace(&self, id: &str) -> Result<WorkspaceRecord, String> {
        let id = id.trim();
        let records = self.workspace_records();
        if let Some(r) = records.iter().find(|r| r.info.id == id) {
            return Ok(r.clone());
        }
        let by_name: Vec<&WorkspaceRecord> = records.iter().filter(|r| r.info.name.eq_ignore_ascii_case(id)).collect();
        match by_name.as_slice() {
            [one] => Ok((*one).clone()),
            [] => Err(format!("Workspace \"{id}\" not found. Use list_workspaces to see the workspaces.")),
            _ => Err(format!("Several workspaces are called \"{id}\"; use the id (ws-…).")),
        }
    }

    /// The workspace, if it's ready for commands.
    fn ready_workspace(&self, id: &str) -> Result<WorkspaceRecord, String> {
        self.refresh_from_disk();
        let rec = self.find_workspace(id)?;
        match rec.info.status.as_str() {
            "ready" => Ok(rec),
            "creating" => Err(format!("Workspace {} is being created; try again once it's ready.", rec.info.id)),
            "destroying" => Err(format!("Workspace {} is being destroyed.", rec.info.id)),
            _ => Err(format!(
                "Workspace {} failed to set up ({}). Destroy it and create a new one.",
                rec.info.id,
                rec.info.error.clone().unwrap_or_default()
            )),
        }
    }

    fn workspace_machine(&self, rec: &WorkspaceRecord) -> Result<MachineSpec, String> {
        let (spec, _) = self.machine(&rec.info.machine_id).ok_or_else(|| {
            format!(
                "Machine {} not found in config.toml anymore, so Muxin can't reach workspace {}. Destroy it with keepFiles to forget it.",
                rec.info.machine_name, rec.info.id
            )
        })?;
        if !spec.is_checkable() {
            return Err(format!("{} has no host in config.toml.", spec.name));
        }
        Ok(spec)
    }

    fn workspace_info(&self, id: &str) -> Option<WorkspaceInfo> {
        self.current().workspaces.iter().find(|w| w.id == id).cloned()
    }

    fn unused_workspace_id(&self) -> String {
        let taken: Vec<String> = self.workspace_records().into_iter().map(|r| r.info.id).collect();
        loop {
            let id = format!("ws-{}", random_id(6));
            if !taken.contains(&id) {
                return id;
            }
        }
    }

    fn touch_workspace(&self, id: &str) {
        let _ = self.update_workspaces(|list| {
            if let Some(r) = list.iter_mut().find(|r| r.info.id == id) {
                r.info.last_used_at = Utc::now();
            }
        });
    }

    async fn run_create(
        self: &Arc<Self>,
        op: u64,
        spec: &MachineSpec,
        rec: &WorkspaceRecord,
        root: &str,
        repo: Option<&Repo>,
    ) -> Result<String, (String, Option<String>)> {
        self.op_log(op, format!("▸ Creating {} on {} ({})", rec.info.id, spec.name, spec.host.trim()));
        let folder: Arc<std::sync::Mutex<Option<String>>> = Arc::default();
        let attempt = |auth: Option<String>| {
            let folder = folder.clone();
            async move {
            let auth_s = auth.clone().unwrap_or_default();
            let repo_url = repo.map(|r| r.url.clone()).unwrap_or_default();
            let repo_shown = repo.map(|r| r.shown.clone()).unwrap_or_default();
            let git_ref = rec.info.git_ref.clone().unwrap_or_default();
            let branch = rec.info.branch.clone().unwrap_or_default();
            let container = rec.info.container.clone().unwrap_or_default();
            let image = rec.info.image.clone().unwrap_or_default();
            let mut params = vec![
                ("OR_ROOT", Param::Str(root)),
                ("OR_ID", Param::Str(&rec.info.id)),
                ("OR_REPO", Param::Str(&repo_url)),
                ("OR_REPO_SHOWN", Param::Str(&repo_shown)),
                ("OR_REF", Param::Str(&git_ref)),
                ("OR_BRANCH", Param::Str(&branch)),
                ("OR_AUTH", Param::Str(&auth_s)),
            ];
            let worktree_of = rec.info.worktree_of.clone().unwrap_or_default();
            let script = if !worktree_of.is_empty() {
                // A worktree of a checkout there: nothing to clone.
                let mut params = vec![
                    ("OR_ROOT", Param::Str(root)),
                    ("OR_ID", Param::Str(&rec.info.id)),
                    ("OR_SRC", Param::Str(&worktree_of)),
                    ("OR_REF", Param::Str(&git_ref)),
                    ("OR_BRANCH", Param::Str(&branch)),
                ];
                if rec.windows {
                    params.insert(0, ("OR_ACTION", Param::Str("worktree")));
                    with_params(Shell::Powershell, &params, OTHER_PS1)
                } else {
                    with_params(Shell::Sh, &params, WORKTREE_SH)
                }
            } else if rec.windows {
                params.insert(0, ("OR_ACTION", Param::Str("create")));
                with_params(Shell::Powershell, &params, OTHER_PS1)
            } else {
                params.extend([
                    ("OR_CONTAINER", Param::Str(&container)),
                    ("OR_IMAGE", Param::Str(&image)),
                    ("OR_SOCKET", Param::Bool(rec.docker_socket)),
                ]);
                with_params(Shell::Sh, &params, &create_script(!container.is_empty()))
            };
            let mut secrets = Vec::new();
            if let Some(a) = &auth {
                secrets.push(a.clone());
                if let Some(enc) = a.strip_prefix("AUTHORIZATION: basic ") {
                    secrets.push(enc.to_string());
                    if let Some(tok) = B64.decode(enc).ok().and_then(|b| String::from_utf8(b).ok()) {
                        if let Some(t) = tok.strip_prefix("x-access-token:") {
                            secrets.push(t.to_string());
                        }
                    }
                }
            }
            let me = self.clone();
            let log = move |line: &str| match line.strip_prefix("path=") {
                Some(p) => {
                    *folder.lock().unwrap() = Some(p.trim().to_string());
                    me.op_log(op, format!("Folder: {p}"))
                }
                None if line == "ready" => {}
                None => me.op_log(op, line.to_string()),
            };
            run_checked(spec, rec.windows, script, CREATE_TIMEOUT, Limits::OUTPUT, &secrets, Some(&log)).await
            }
        };
        let fail = |message: String| (message, folder.lock().unwrap().clone());

        let out = match attempt(None).await {
            Ok(out) => out,
            Err(e) => {
                // A private GitHub repo: try again with the user's token, passed only through the environment.
                // The machine's exit code only says it wants credentials, and it could say so for any repo;
                // whether this one is private is asked of GitHub from here. A public repo never gets the token.
                let retry = match repo {
                    Some(r) if r.on_github && e.code == Some(4) => {
                        let settings = self.settings().github;
                        let private = match github_full_name(r) {
                            Some(name) => self.github().repo(&settings, &name).await.is_ok_and(|info| info.private),
                            None => false,
                        };
                        if private {
                            self.github().git_credentials(&settings).await.filter(|(host, _)| *host == r.host)
                        } else {
                            self.op_log(op, format!("▸ GitHub doesn't list {} as a private repository you can reach, so your token isn't sent", r.shown));
                            None
                        }
                    }
                    _ => None,
                };
                let Some((_, token)) = retry else { return Err(fail(e.message)) };
                self.op_log(op, "▸ The clone needs credentials; retrying with your GitHub token");
                let header = format!("AUTHORIZATION: basic {}", B64.encode(format!("x-access-token:{token}")));
                attempt(Some(header)).await.map_err(|e| fail(e.message))?
            }
        };
        field(&out.stdout, "path").ok_or_else(|| fail("The machine didn't report the workspace folder.".to_string()))
    }

    #[allow(clippy::too_many_arguments)]
    async fn run_exec(
        &self,
        spec: &MachineSpec,
        rec: &WorkspaceRecord,
        command: &str,
        cwd: &str,
        env: &[(String, String)],
        timeout: u64,
        log: Option<String>,
    ) -> Result<ExecResult, String> {
        let timeout_s = timeout.to_string();
        let log_s = log.clone().unwrap_or_default();
        let shell = if rec.windows { Shell::Powershell } else { Shell::Sh };
        let exports = env_exports(shell, env);
        let mut params = vec![
            ("OR_DIR", Param::Str(&rec.info.path)),
            ("OR_CWD", Param::Str(cwd)),
            ("OR_CMD", Param::Str(command)),
            ("OR_TIMEOUT", Param::Str(&timeout_s)),
            ("OR_BG", Param::Bool(log.is_some())),
            ("OR_LOG", Param::Str(&log_s)),
            ("OR_ID", Param::Str(&rec.info.id)),
        ];
        // A background run on Windows doesn't inherit the environment: its script sets it.
        if shell == Shell::Powershell {
            params.push(("OR_ENVPS", Param::Str(&exports)));
        }
        let script = match (&rec.info.container, shell) {
            (Some(container), Shell::Sh) => {
                let image = rec.info.image.clone().unwrap_or_else(|| DEFAULT_IMAGE.to_string());
                let names: Vec<&str> = env.iter().map(|(k, _)| k.as_str()).collect();
                let names = names.join(" ");
                let all = [
                    ("OR_DIR", Param::Str(&rec.info.path)),
                    ("OR_CWD", Param::Str(cwd)),
                    ("OR_CMD", Param::Str(command)),
                    ("OR_TIMEOUT", Param::Str(&timeout_s)),
                    ("OR_BG", Param::Bool(log.is_some())),
                    ("OR_LOG", Param::Str(&log_s)),
                    ("OR_ID", Param::Str(&rec.info.id)),
                    ("OR_CONTAINER", Param::Str(container)),
                    ("OR_IMAGE", Param::Str(&image)),
                    ("OR_SOCKET", Param::Bool(rec.docker_socket)),
                    ("OR_ENV", Param::Str(&names)),
                ];
                with_params(shell, &all, &format!("{exports}{LIB_SH}\n{DOCKER_SH}\n{EXEC_DOCKER_SH}"))
            }
            (_, Shell::Sh) => with_params(shell, &params, &format!("{exports}{LIB_SH}\n{EXEC_SH}")),
            (_, Shell::Powershell) => with_params(shell, &params, &format!("{exports}{EXEC_PS1}")),
        };
        let marker = transport::new_marker();
        let out = transport::run(
            spec,
            rec.windows,
            &marker,
            transport::with_marker(&marker, rec.windows, &script),
            Duration::from_secs(timeout + EXEC_GRACE),
            Limits::OUTPUT,
            &[],
            None,
        )
        .await?;
        exec_result(out, &spec.name, log)
    }

    async fn run_files(&self, spec: &MachineSpec, rec: &WorkspaceRecord, params: &[(&str, Param<'_>)]) -> Result<Output, String> {
        let mut all = vec![("OR_DIR", Param::Str(&rec.info.path))];
        for (k, v) in params {
            all.push((k, match v {
                Param::Str(s) => Param::Str(s),
                Param::List(l) => Param::List(l),
                Param::Bool(b) => Param::Bool(*b),
            }));
        }
        let (script, windows) = if rec.windows {
            (with_params(Shell::Powershell, &all, FILES_PS1), true)
        } else {
            (with_params(Shell::Sh, &all, FILES_SH), false)
        };
        run_checked(spec, windows, script, FILE_TIMEOUT, Limits::DATA, &[], None).await.map_err(|e| e.message)
    }

    async fn run_destroy(self: &Arc<Self>, op: u64, spec: &MachineSpec, rec: &WorkspaceRecord, keep: bool) -> Result<(), String> {
        self.op_log(op, format!("▸ Cleaning up on {} ({})", spec.name, spec.host.trim()));
        let pids: Vec<String> = rec.background_pids.iter().map(u32::to_string).collect();
        let pids = pids.join(" ");
        let script = if rec.windows {
            with_params(
                Shell::Powershell,
                &[
                    ("OR_ACTION", Param::Str("destroy")),
                    ("OR_DIR", Param::Str(&rec.info.path)),
                    ("OR_ID", Param::Str(&rec.info.id)),
                    ("OR_PIDS", Param::Str(&pids)),
                    ("OR_KEEP", Param::Bool(keep)),
                    ("OR_SRC", Param::Str(rec.info.worktree_of.as_deref().unwrap_or_default())),
                ],
                OTHER_PS1,
            )
        } else {
            let container = rec.info.container.clone().unwrap_or_default();
            let image = rec.info.image.clone().unwrap_or_default();
            with_params(
                Shell::Sh,
                &[
                    ("OR_DIR", Param::Str(&rec.info.path)),
                    ("OR_ID", Param::Str(&rec.info.id)),
                    ("OR_PIDS", Param::Str(&pids)),
                    ("OR_KEEP", Param::Bool(keep)),
                    ("OR_CONTAINER", Param::Str(&container)),
                    ("OR_IMAGE", Param::Str(&image)),
                    ("OR_SRC", Param::Str(rec.info.worktree_of.as_deref().unwrap_or_default())),
                ],
                &format!("{LIB_SH}\n{DESTROY_SH}"),
            )
        };
        let me = self.clone();
        let log = move |line: &str| me.op_log(op, line.to_string());
        run_checked(spec, rec.windows, script, DESTROY_TIMEOUT, Limits::OUTPUT, &[], Some(&log)).await.map(|_| ()).map_err(|e| e.message)
    }
}

// ---------------------------------------------------------------------------
// Registry plumbing used by the engine.

pub(crate) fn load_registry(path: &std::path::Path) -> Vec<WorkspaceRecord> {
    registry::load(path)
}

pub(crate) fn update_registry<R>(
    path: &std::path::Path,
    f: impl FnOnce(&mut Vec<WorkspaceRecord>) -> R,
) -> Result<(R, Vec<WorkspaceRecord>, Option<std::time::SystemTime>), String> {
    registry::update(path, f)
}

pub(crate) fn demo_seed(world: &crate::demo::World) -> Vec<WorkspaceRecord> {
    demo::seed(world)
}

/// What the snapshot shows: stored records with current machine names and a
/// ready-to-run shell command, most recently used first.
pub(crate) fn snapshot_infos(records: &[WorkspaceRecord], machines: &[Machine], specs: &[MachineSpec]) -> Vec<WorkspaceInfo> {
    let mut out: Vec<WorkspaceInfo> = records
        .iter()
        .map(|r| {
            let mut info = r.info.clone();
            if let Some(m) = machines.iter().find(|m| m.id == info.machine_id) {
                info.machine_name = m.name.clone();
                info.host = m.host.clone();
                if !m.platform.is_empty() {
                    info.platform = m.platform.clone();
                }
            }
            if let Some(spec) = specs.iter().find(|s| s.id == info.machine_id) {
                info.shell = match &info.container {
                    Some(c) => docker_shell_command(spec, c),
                    None => shell_command(spec, &info.path, r.windows),
                };
            }
            info
        })
        .collect();
    out.sort_by(|a, b| b.last_used_at.cmp(&a.last_used_at));
    out
}

// ---------------------------------------------------------------------------
// Helpers

/// A failure from a workspace script: the reason and the script's exit code.
struct ScriptError {
    message: String,
    code: Option<i32>,
}

/// Runs a script that reports failure through its exit status (`error: ...` on stderr).
async fn run_checked(
    spec: &MachineSpec,
    windows: bool,
    script: String,
    timeout: Duration,
    limits: Limits,
    secrets: &[String],
    on_line: Option<&(dyn Fn(&str) + Send + Sync)>,
) -> Result<Output, ScriptError> {
    let marker = transport::new_marker();
    let out = transport::run(spec, windows, &marker, transport::with_marker(&marker, windows, &script), timeout, limits, secrets, on_line)
        .await
        .map_err(|message| ScriptError { message, code: None })?;
    if out.timed_out {
        return Err(ScriptError { message: format!("{} is unreachable: no answer within {}s.", spec.name, timeout.as_secs()), code: None });
    }
    if !out.started {
        return Err(ScriptError { message: format!("{} is unreachable: {}", spec.name, out.reason()), code: out.status });
    }
    match out.status {
        Some(0) => Ok(out),
        code => Err(ScriptError { message: out.reason(), code }),
    }
}

impl From<ScriptError> for String {
    fn from(e: ScriptError) -> String {
        e.message
    }
}

fn exec_result(out: Output, machine: &str, log: Option<String>) -> Result<ExecResult, String> {
    if !out.started {
        return Err(format!("{machine} is unreachable: {}", out.reason()));
    }
    const SETUP: [&str; 5] = [
        "error: the workspace folder is gone",
        "error: there's no folder",
        "error: docker isn't available",
        "error: couldn't pull",
        "error: couldn't start a container",
    ];
    let setup_error = out.exit == Some(97) && out.stderr.lines().next().is_some_and(|l| SETUP.iter().any(|p| l.starts_with(p)));
    if setup_error {
        return Err(out.reason());
    }
    if out.exit.is_none() && !out.timed_out {
        return Err(format!("The ssh connection to {machine} dropped while the command ran: {}", out.reason()));
    }
    let background_pid = if log.is_some() { field(&out.stdout, "pid").and_then(|p| p.parse().ok()) } else { None };
    Ok(ExecResult {
        exit_code: if out.timed_out || log.is_some() { None } else { out.exit },
        stdout: if log.is_some() { String::new() } else { out.stdout },
        stderr: out.stderr,
        duration_ms: 0,
        timed_out: out.timed_out,
        truncated: out.truncated,
        background_pid,
        log_path: log,
    })
}

/// `export NAME='value'` (sh) or `$env:NAME = 'value'` (PowerShell) lines.
fn env_exports(shell: Shell, env: &[(String, String)]) -> String {
    env.iter()
        .map(|(k, v)| match shell {
            Shell::Sh => format!("export {k}={}\n", sh_quote(v)),
            Shell::Powershell => format!("$env:{k} = {}\n", ps_quote(v)),
        })
        .collect()
}

/// The value of a `key=value` line in script output.
fn field(text: &str, key: &str) -> Option<String> {
    let prefix = format!("{key}=");
    text.lines().find_map(|l| l.strip_prefix(&prefix)).map(|v| v.trim().to_string())
}

fn file_content(path: String, bytes: Vec<u8>, size: u64, max: usize) -> FileContent {
    let truncated = size > max as u64 || bytes.len() < size as usize;
    let text = match String::from_utf8(bytes) {
        Ok(t) => Some(t),
        // A cut can land inside a multi-byte character; keep the valid part.
        Err(e) if truncated && e.utf8_error().error_len().is_none() => {
            let valid = e.utf8_error().valid_up_to();
            let mut b = e.into_bytes();
            b.truncate(valid);
            String::from_utf8(b).ok()
        }
        Err(_) => None,
    };
    match text.filter(|t| !t.contains('\0')) {
        Some(content) => FileContent { path, content, size, truncated, binary: false },
        None => FileContent { path, content: String::new(), size, truncated, binary: true },
    }
}

fn parse_listing(text: &str, base: &str) -> Vec<FileEntry> {
    text.lines()
        .filter_map(|l| {
            let mut parts = l.splitn(3, '\t');
            let kind = match parts.next()? {
                "d" => "dir",
                "l" => "link",
                _ => "file",
            };
            let size = parts.next()?.trim().parse().unwrap_or(0);
            let rel = parts.next()?.trim_start_matches("./");
            if rel.is_empty() {
                return None;
            }
            let path = if base.is_empty() { rel.to_string() } else { format!("{base}/{rel}") };
            Some(FileEntry { path, kind: kind.into(), size: if kind == "dir" { 0 } else { size } })
        })
        .take(LIST_MAX_ENTRIES)
        .collect()
}

/// The last lines of a command's output, for history.
fn output_tail(stdout: &str, stderr: &str) -> Vec<String> {
    let lines: Vec<String> = stdout
        .lines()
        .chain(stderr.lines())
        .filter(|l| !l.trim().is_empty())
        .map(|l| if l.chars().count() > TAIL_LINE_MAX { format!("{}…", l.chars().take(TAIL_LINE_MAX).collect::<String>()) } else { l.to_string() })
        .collect();
    lines[lines.len().saturating_sub(registry::TAIL_LINES)..].to_vec()
}

fn clean_opt(s: Option<String>) -> Option<String> {
    s.map(|s| s.trim().to_string()).filter(|s| !s.is_empty())
}

/// A path relative to the workspace, normalized to forward slashes. Rejects
/// absolute paths and `..`, so agents don't wander out by accident.
pub fn rel_path(p: &str) -> Result<String, String> {
    let p = p.trim();
    let drive = p.len() >= 2 && p.as_bytes()[1] == b':' && p.as_bytes()[0].is_ascii_alphabetic();
    if p.starts_with('/') || p.starts_with('\\') || p.starts_with('~') || drive {
        return Err(format!("\"{p}\" isn't inside the workspace. Paths are relative to the workspace folder."));
    }
    let mut parts = Vec::new();
    for seg in p.split(['/', '\\']) {
        match seg {
            "" | "." => {}
            ".." => return Err(format!("\"{p}\" leaves the workspace. Paths can't use \"..\".")),
            s if s.chars().any(char::is_control) => return Err(format!("\"{p}\" has control characters.")),
            s => parts.push(s),
        }
    }
    Ok(parts.join("/"))
}

fn validate_env(name: &str, value: &str) -> Result<(), String> {
    let ok = !name.is_empty()
        && name.len() <= 128
        && name.chars().next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
    if !ok {
        return Err(format!("\"{name}\" isn't a valid environment variable name."));
    }
    if value.contains('\0') {
        return Err(format!("The value of {name} contains a NUL byte."));
    }
    Ok(())
}

pub(crate) fn validate_git_ref(r: &str) -> Result<(), String> {
    let bad = r.len() > 200
        || r.starts_with('-')
        || r.contains("..")
        || r.ends_with('/')
        || r.ends_with(".lock")
        || r.chars().any(|c| c.is_whitespace() || c.is_control() || "~^:?*[\\".contains(c));
    if bad { Err(format!("\"{r}\" isn't a valid git branch, tag or commit.")) } else { Ok(()) }
}

/// A repository to clone.
pub(crate) struct Repo {
    /// What git clones.
    pub url: String,
    /// Shown in the UI and logs (no credentials).
    pub shown: String,
    /// "api" for acme/api.
    pub short_name: String,
    pub host: String,
    /// https on the GitHub host Muxin has a token for.
    pub on_github: bool,
}

/// "owner/name" of a repository on the GitHub host, from "owner/name" or its https URL.
pub(crate) fn github_full_name(r: &Repo) -> Option<String> {
    let path = match r.shown.split_once("://") {
        Some((_, rest)) => rest.split_once('/')?.1,
        None => r.shown.as_str(),
    };
    let path = path.trim_end_matches('/').trim_end_matches(".git");
    let mut parts = path.split('/');
    let (owner, name) = (parts.next()?, parts.next()?);
    (parts.next().is_none() && !owner.is_empty() && !name.is_empty()).then(|| format!("{owner}/{name}"))
}

pub(crate) fn github_web_host(api_url: &str) -> String {
    let host = api_url.split("://").nth(1).unwrap_or(api_url).split('/').next().unwrap_or("api.github.com");
    if host == "api.github.com" { "github.com".into() } else { host.to_string() }
}

/// "owner/repo" means GitHub; anything else must look like a git URL or a path on the machine.
pub(crate) fn normalize_repo(raw: &str, gh_host: &str) -> Result<Repo, String> {
    let raw = raw.trim();
    if raw.starts_with('-') || raw.chars().any(|c| c.is_whitespace() || c.is_control()) {
        return Err(format!("\"{raw}\" isn't a repository Muxin can clone."));
    }
    let short = |s: &str| {
        s.trim_end_matches('/').rsplit(['/', ':']).next().unwrap_or(s).trim_end_matches(".git").to_string()
    };
    let simple = raw.split('/').count() == 2
        && !raw.contains(':')
        && !raw.starts_with('.')
        && raw.split('/').all(|p| !p.is_empty() && p.chars().all(|c| c.is_ascii_alphanumeric() || "-_.".contains(c)));
    if simple {
        let path = raw.trim_end_matches(".git");
        return Ok(Repo {
            url: format!("https://{gh_host}/{path}.git"),
            shown: path.to_string(),
            short_name: short(path),
            host: gh_host.to_string(),
            on_github: true,
        });
    }
    let is_url = ["https://", "http://", "ssh://", "git://", "file://"].iter().any(|p| raw.starts_with(p));
    let scp_like = raw.contains('@') && raw.contains(':') && !raw.contains("://");
    let path_like = raw.starts_with('/') || raw.starts_with("~/");
    if !(is_url || scp_like || path_like) {
        return Err(format!("\"{raw}\" isn't a repository. Use owner/repo for GitHub, or a git URL."));
    }
    // Never echo credentials embedded in a URL.
    let shown = match raw.split_once("://") {
        Some((scheme, rest)) => match rest.split_once('@') {
            Some((_, after)) if rest.find('@') < rest.find('/') => format!("{scheme}://{after}"),
            _ => raw.to_string(),
        },
        None => raw.to_string(),
    };
    let host = raw
        .split_once("://")
        .map(|(_, rest)| rest.split('/').next().unwrap_or("").rsplit('@').next().unwrap_or("").to_string())
        .unwrap_or_default();
    Ok(Repo {
        url: raw.to_string(),
        short_name: short(&shown),
        on_github: raw.starts_with("https://") && host.eq_ignore_ascii_case(gh_host),
        host,
        shown,
    })
}

fn machine_names(machines: &[Machine]) -> String {
    machines.iter().map(|m| m.id.as_str()).collect::<Vec<_>>().join(", ")
}

/// "macos" → "darwin", "x86_64" → "x64", ... so agents can say it however they like.
fn normalize_platform(p: &str) -> String {
    let p = p.trim().to_ascii_lowercase().replace('_', "-");
    let (os, arch) = p.split_once('-').map(|(o, a)| (o.to_string(), Some(a.to_string()))).unwrap_or((p.clone(), None));
    let os = match os.as_str() {
        "mac" | "macos" | "osx" | "apple" => "darwin".to_string(),
        "win" | "win32" => "windows".to_string(),
        o => o.to_string(),
    };
    let arch = arch.map(|a| match a.as_str() {
        "amd64" | "x86-64" | "x8664" | "86-64" => "x64".to_string(),
        "aarch64" => "arm64".to_string(),
        a => a.to_string(),
    });
    match arch {
        Some(a) => format!("{os}-{a}"),
        None => os,
    }
}

/// The online machine that allows workspaces with the most headroom.
#[cfg_attr(not(test), allow(dead_code))]
pub(crate) fn pick_machine<'a>(machines: &'a [Machine], platform: Option<&str>) -> Result<&'a Machine, String> {
    pick_machine_for(machines, platform, false)
}

/// Like `pick_machine`; for docker workspaces, prefers machines whose last
/// check found docker (when no check has reported docker yet, any will do —
/// the create step checks for real).
pub(crate) fn pick_machine_for<'a>(machines: &'a [Machine], platform: Option<&str>, docker: bool) -> Result<&'a Machine, String> {
    let want = platform.map(normalize_platform);
    let platform_ok = |m: &Machine| want.as_deref().is_none_or(|w| m.platform.starts_with(w));
    let disk_ok = |m: &Machine| m.probe.as_ref().and_then(|p| p.disk_free).is_none_or(|f| f >= MIN_FREE_DISK);
    let mut candidates: Vec<&Machine> = machines
        .iter()
        .filter(|m| m.status == "online" && m.workspaces_allowed && platform_ok(m) && disk_ok(m) && !(docker && m.platform.starts_with("windows")))
        .collect();
    if docker && candidates.iter().any(|m| m.probe.as_ref().is_some_and(|p| p.docker.is_some())) {
        candidates.retain(|m| m.probe.as_ref().is_some_and(|p| p.docker.is_some()));
    }
    let score = |m: &Machine| {
        let p = m.probe.as_ref();
        let cpu = p.and_then(|p| p.cpu_pct).unwrap_or(50.0);
        let mem = p.and_then(|p| Some(p.mem_used? as f64 / p.mem_total?.max(1) as f64 * 100.0)).unwrap_or(50.0);
        let low_disk = p.and_then(|p| p.disk_free).is_some_and(|f| f < 20_000_000_000);
        cpu + mem + m.summary.working as f64 * 20.0 + if low_disk { 100.0 } else { 0.0 }
    };
    candidates
        .into_iter()
        .min_by(|a, b| score(a).total_cmp(&score(b)).then_with(|| a.name.cmp(&b.name)))
        .ok_or_else(|| {
            let what = match (&want, docker) {
                (Some(w), true) => format!("allows workspaces, runs {w} and can run docker"),
                (Some(w), false) => format!("allows workspaces and runs {w}"),
                (None, true) => "allows workspaces and can run docker".into(),
                (None, false) => "allows workspaces".into(),
            };
            let online: Vec<String> = machines
                .iter()
                .filter(|m| m.status == "online")
                .map(|m| format!("{} ({}{})", m.id, m.platform, if m.workspaces_allowed { "" } else { ", workspaces off" }))
                .collect();
            if online.is_empty() {
                format!("No machine is online right now. Run check_machines, or add a machine.")
            } else {
                format!("No online machine {what} and has free disk. Online: {}.", online.join(", "))
            }
        })
}

/// A command a human can paste to get a shell inside the workspace.
pub(crate) fn shell_command(spec: &MachineSpec, path: &str, windows: bool) -> String {
    if spec.is_local() {
        return if windows { format!("Set-Location {}", ps_quote(path)) } else { format!("cd {} && exec \"$SHELL\" -l", sh_quote(path)) };
    }
    let mut parts = vec!["ssh".to_string(), "-t".to_string()];
    if let Some(port) = spec.port {
        parts.push(format!("-p {port}"));
    }
    if let Some(user) = spec.user.as_deref().filter(|u| !u.is_empty()) {
        parts.push(format!("-l {user}"));
    }
    parts.extend(spec.ssh_options.iter().map(|o| display_arg(o)));
    parts.push(spec.host.trim().to_string());
    let inner = if windows {
        format!("\"powershell -NoExit -Command Set-Location '{path}'\"")
    } else {
        format!("\"cd '{path}' && exec \\$SHELL -l\"")
    };
    parts.push(inner);
    parts.join(" ")
}

/// `muxen-ws-<id>`.
pub(crate) fn container_name(id: &str) -> String {
    format!("muxen-ws-{}", id.trim_start_matches("ws-"))
}

/// A docker image reference: registry/name:tag or name@sha256:..., nothing that
/// could be read as a flag.
fn validate_image(image: &str) -> Result<String, String> {
    let ok = !image.is_empty()
        && image.len() <= 255
        && !image.starts_with(['-', '.', '/', ':', '@'])
        && image.chars().all(|c| c.is_ascii_alphanumeric() || "-_./:@".contains(c));
    if ok { Ok(image.to_string()) } else { Err(format!("\"{image}\" isn't a docker image name (like node:22 or ghcr.io/acme/dev:latest).")) }
}

/// The create script: make the folder (and clone) on the host, then, for docker
/// workspaces, check docker first and start the container last.
/// The same folder, however it's written: "~/code/api" is "/home/me/code/api/".
pub(crate) fn same_folder(a: &str, b: &str) -> bool {
    let (a, b) = (a.trim_end_matches(['/', '\\']), b.trim_end_matches(['/', '\\']));
    let home_relative = |short: &str, full: &str| {
        let Some(rest) = short.strip_prefix('~').filter(|r| r.starts_with(['/', '\\'])) else { return false };
        // What's before the rest is a home folder: /home/me, /Users/me, /root, C:\Users\me.
        full.strip_suffix(rest).is_some_and(|home| !home.is_empty() && home.matches(['/', '\\']).count() <= 2)
    };
    a == b || home_relative(a, b) || home_relative(b, a)
}

fn create_script(docker: bool) -> String {
    if docker {
        format!(
            "{DOCKER_SH}\nor_docker_check || exit 6\n{CREATE_SH}\nor_docker_up \"$(pwd -P)\" || exit 6\necho \"Container $OR_CONTAINER is running\"\n"
        )
    } else {
        CREATE_SH.to_string()
    }
}

/// A shell inside a docker workspace's container, for a human.
pub(crate) fn docker_shell_command(spec: &MachineSpec, container: &str) -> String {
    let inner = format!("docker start {container} >/dev/null && docker exec -it -w /workspace {container} sh -c 'exec bash 2>/dev/null || exec sh'");
    if spec.is_local() {
        return inner;
    }
    let mut parts = vec!["ssh".to_string(), "-t".to_string()];
    if let Some(port) = spec.port {
        parts.push(format!("-p {port}"));
    }
    if let Some(user) = spec.user.as_deref().filter(|u| !u.is_empty()) {
        parts.push(format!("-l {user}"));
    }
    parts.extend(spec.ssh_options.iter().map(|o| display_arg(o)));
    parts.push(spec.host.trim().to_string());
    parts.push(format!("\"{inner}\""));
    parts.join(" ")
}

fn display_arg(a: &str) -> String {
    if a.chars().all(|c| c.is_ascii_alphanumeric() || "-_./=:@~,".contains(c)) { a.to_string() } else { sh_quote(a) }
}

fn rsync_args(spec: &MachineSpec, remote_path: &str, local: &str, direction: SyncDirection, delete: bool) -> Vec<String> {
    let mut args = vec!["-az".to_string(), "--stats".to_string(), "--exclude=/.muxen/".to_string()];
    if direction == SyncDirection::Pull {
        // Files come back, git's own folder doesn't (nor a worktree's or a
        // submodule's .git file): the machine could set a command in .git/config
        // (core.fsmonitor, hooks) that the next `git status` here would run. Your
        // .git isn't deleted either; --delete leaves excluded paths alone.
        args.push("--exclude=.git".into());
    }
    if delete {
        args.push("--delete".into());
    }
    let remote = if spec.is_local() {
        format!("{}/", remote_path.trim_end_matches('/'))
    } else {
        let mut ssh = crate::probe::ssh_args(spec);
        ssh.pop(); // the host goes in the remote path
        let ssh: Vec<String> = ssh.iter().map(|a| display_arg(a)).collect();
        args.push("-e".into());
        args.push(format!("ssh {}", ssh.join(" ")));
        format!("{}:{}/", spec.host.trim(), remote_path.trim_end_matches('/'))
    };
    let local = format!("{}/", local.trim_end_matches('/'));
    match direction {
        SyncDirection::Push => {
            args.push(local);
            args.push(remote);
        }
        SyncDirection::Pull => {
            args.push(remote);
            args.push(local);
        }
    }
    args
}

fn expand_home(p: &str) -> std::path::PathBuf {
    match (p.strip_prefix("~/"), dirs::home_dir()) {
        (Some(rest), Some(home)) => home.join(rest),
        _ if p == "~" => dirs::home_dir().unwrap_or_default(),
        _ => std::path::PathBuf::from(p),
    }
}

/// Lowercase base36, from a small per-process generator (no extra dependency).
pub(crate) fn random_id(len: usize) -> String {
    static STATE: AtomicU64 = AtomicU64::new(0);
    let seed = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_nanos() as u64).unwrap_or(1)
        ^ (std::process::id() as u64).rotate_left(32);
    let mut x = STATE.fetch_add(0x9E37_79B9_7F4A_7C15, Ordering::Relaxed).wrapping_add(seed);
    const DIGITS: &[u8] = b"0123456789abcdefghijklmnopqrstuvwxyz";
    (0..len)
        .map(|_| {
            // splitmix64
            x = x.wrapping_add(0x9E37_79B9_7F4A_7C15);
            let mut z = x;
            z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
            z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
            z ^= z >> 31;
            DIGITS[(z % 36) as usize] as char
        })
        .collect()
}

#[cfg(test)]
mod tests;