marver 0.0.30

//! Making a fresh worktree usable.
//!
//! `git worktree add` hands over the tracked files and nothing else. The `.env`
//! the app reads, the `node_modules` the tests import, the `target/` that turns
//! a four-minute build into a four-second one — all of it is either ignored by
//! git or built from scratch, so none of it crosses. An agent that starts in a
//! worktree it cannot build spends its first turn finding that out, and its
//! second one guessing.
//!
//! Three optional files in a repo answer it:
//!
//! ```text
//! <repo>/.marver/include     paths to carry across, one per line
//! <repo>/.marver/setup       run once the worktree exists
//! <repo>/.marver/teardown    run before it is taken away
//! ```
//!
//! They live in the repo rather than in marver's data directory because the
//! answer is a property of the project — `api` needs a different `.env` from
//! `web`, and a task spanning both needs each. Committing them shares the setup
//! with everyone else working on the repo; leaving them ignored keeps it to one
//! machine. marver does not care which.
//!
//! **These run code the repository supplies.** `setup` is executed on the way
//! into every new worktree, so creating a task against a repo runs whatever
//! that repo's `.marver/setup` says, as the user, before any agent starts. For
//! a repo somebody wrote that is the point of the feature; for one that was
//! cloned to be read it is a thing to know before it is under the scan root.
//! Nothing here sandboxes it, and nothing could without taking the feature
//! away.
//!
//! [`include_list`] refusing a line that points outside the repo is worth
//! keeping — a repo may carry `include` and no `setup`, and then it really is
//! only a list of filenames — but it is not a boundary. `setup` sits in the
//! same directory and is strictly more than the check denies.
//!
//! **A script that fails does not fail the task.** The opposite was tempting —
//! provisioning is otherwise all-or-nothing, and a worktree whose setup failed
//! is exactly the half-existing thing that principle exists to prevent. But a
//! failed launch is terminal and has no retry edge, so a package registry
//! having a bad minute would destroy the task outright. Instead the failure is
//! written to `setup.log` beside the worktrees, where the agent can read it and
//! do something about it. It is, after all, an agent.

use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::mpsc::{RecvTimeoutError, channel};
use std::time::{Duration, Instant};

/// Directory in a repo holding the files below.
pub const DIR: &str = ".marver";
/// Paths to carry into a new worktree, one per line.
pub const INCLUDE: &str = "include";
/// Script run once a worktree exists.
pub const SETUP: &str = "setup";
/// Script run before a worktree is removed.
pub const TEARDOWN: &str = "teardown";
/// What the workspace keeps of everything the scripts said.
pub const LOG_FILE: &str = "setup.log";

/// Long enough for `npm ci` on a cold cache, short enough that a wedged script
/// does not hold the queue for ever. The daemon is busy for the duration, so
/// this is a real cost and not just a safety net.
const SETUP_TIMEOUT: Duration = Duration::from_secs(300);
/// Teardown runs while someone is waiting for a list to redraw.
const TEARDOWN_TIMEOUT: Duration = Duration::from_secs(60);
/// How long a killed script is given to let go of its output.
const REAP_GRACE: Duration = Duration::from_secs(2);
/// How long after a script exits its last line is waited for. The write reached
/// the pipe before the exit did; this is only the reader catching up.
const SETTLE: Duration = Duration::from_millis(50);
/// Kept from the end of a script's output: the tail is where the error is.
const MAX_OUTPUT: usize = 64 * 1024;
/// What one pipe may hold while a script is still running. Larger than
/// [`MAX_OUTPUT`] because the two pipes are joined before the join is trimmed,
/// so a script that says everything on stderr still arrives with a full budget.
const LIMIT: usize = MAX_OUTPUT + 8 * 1024;

/// Everything a script is told about the worktree it is standing in.
#[derive(Debug, Clone, Copy)]
pub struct Context<'a> {
    /// The repository the worktree was cut from.
    pub repo: &'a Path,
    /// Its directory name, as the workspace shows it.
    pub repo_name: &'a str,
    /// The worktree itself; the script's working directory.
    pub worktree: &'a Path,
    pub branch: &'a str,
    pub base: &'a str,
    pub task_id: i64,
    /// The task's directory, holding this worktree and its siblings.
    pub workspace: &'a Path,
}

/// What running one of the scripts amounted to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Script {
    /// There is no such file. Overwhelmingly the common case, and not worth a
    /// word in the log.
    Absent,
    Ran {
        ok: bool,
        output: String,
        took: Duration,
    },
    /// Killed at the timeout, with whatever it had said by then.
    TimedOut { after: Duration, output: String },
    /// Could not be started at all.
    Failed(String),
}

impl Script {
    /// Whether this is worth telling anyone about.
    pub fn is_quiet(&self) -> bool {
        matches!(self, Script::Absent | Script::Ran { ok: true, .. })
    }
}

/// What carrying the `include` list across amounted to.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Carried {
    pub copied: Vec<PathBuf>,
    /// Listed but not in the repo. Ordinary: an `include` covering every
    /// machine names files that only some of them have.
    pub missing: Vec<PathBuf>,
    pub failed: Vec<(PathBuf, String)>,
    /// Lines refused for pointing outside the repo.
    pub refused: Vec<String>,
}

impl Carried {
    pub fn is_quiet(&self) -> bool {
        self.failed.is_empty() && self.refused.is_empty()
    }
}

/// What preparing one worktree amounted to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Prepared {
    pub repo_name: String,
    pub carried: Carried,
    pub setup: Script,
}

impl Prepared {
    /// Whether everything went as asked. A quiet preparation says nothing.
    pub fn is_quiet(&self) -> bool {
        self.carried.is_quiet() && self.setup.is_quiet()
    }

    /// One line, for the daemon log. `None` when there is nothing to say.
    pub fn summary(&self) -> Option<String> {
        match &self.setup {
            _ if !self.carried.is_quiet() => {
                let mut parts = Vec::new();
                for (path, why) in &self.carried.failed {
                    parts.push(format!("{} ({why})", path.display()));
                }
                for line in &self.carried.refused {
                    parts.push(format!("{line} (outside the repo)"));
                }
                Some(format!(
                    "{}: could not carry {}",
                    self.repo_name,
                    parts.join(", ")
                ))
            }
            Script::Ran { ok: false, .. } => {
                Some(format!("{}: {DIR}/{SETUP} failed", self.repo_name))
            }
            Script::TimedOut { after, .. } => Some(format!(
                "{}: {DIR}/{SETUP} was killed after {}s",
                self.repo_name,
                after.as_secs()
            )),
            Script::Failed(why) => Some(format!(
                "{}: could not run {DIR}/{SETUP}: {why}",
                self.repo_name
            )),
            _ => None,
        }
    }

    /// The section this worktree contributes to `setup.log`.
    fn section(&self) -> Option<String> {
        if self.is_quiet() && matches!(self.setup, Script::Absent) && self.carried.copied.is_empty()
        {
            return None;
        }
        let mut out = format!("# {}\n", self.repo_name);
        if !self.carried.copied.is_empty() {
            out.push_str(&format!(
                "carried  {}\n",
                self.carried
                    .copied
                    .iter()
                    .map(|p| p.display().to_string())
                    .collect::<Vec<_>>()
                    .join(", ")
            ));
        }
        for (path, why) in &self.carried.failed {
            out.push_str(&format!("failed   {}: {why}\n", path.display()));
        }
        for line in &self.carried.refused {
            out.push_str(&format!("refused  {line}: outside the repo\n"));
        }
        match &self.setup {
            Script::Absent => {}
            Script::Ran { ok, output, took } => {
                let verdict = if *ok { "ok" } else { "failed" };
                out.push_str(&format!("setup    {verdict} in {}s\n", took.as_secs()));
                push_output(&mut out, output);
            }
            Script::TimedOut { after, output } => {
                out.push_str(&format!("setup    killed after {}s\n", after.as_secs()));
                push_output(&mut out, output);
            }
            Script::Failed(why) => out.push_str(&format!("setup    could not run: {why}\n")),
        }
        Some(out)
    }
}

fn push_output(out: &mut String, output: &str) {
    if output.trim().is_empty() {
        return;
    }
    out.push('\n');
    for line in output.lines() {
        out.push_str("    ");
        out.push_str(line);
        out.push('\n');
    }
    out.push('\n');
}

/// Carry the include list across, then run `setup`. Never fails as a whole.
pub fn prepare(ctx: &Context) -> Prepared {
    // Before the script, not after: `setup` is the thing most likely to need
    // the `.env` that `include` brings.
    let carried = carry(ctx);
    let setup = match script(ctx.repo, SETUP) {
        Some(path) => run(&path, ctx, SETUP_TIMEOUT),
        None => Script::Absent,
    };
    Prepared {
        repo_name: ctx.repo_name.to_string(),
        carried,
        setup,
    }
}

/// Run `teardown`, if there is one. Never fails.
pub fn teardown(ctx: &Context) -> Script {
    match script(ctx.repo, TEARDOWN) {
        Some(path) => run(&path, ctx, TEARDOWN_TIMEOUT),
        None => Script::Absent,
    }
}

/// Write what preparing a task's worktrees amounted to, beside them.
///
/// `Ok(None)` when every worktree was quiet and there was nothing to record —
/// the file is not created just to say so, because an empty one would still
/// have to be explained to whoever finds it.
pub fn write_log(workspace: &Path, prepared: &[Prepared]) -> std::io::Result<Option<PathBuf>> {
    let sections: Vec<String> = prepared.iter().filter_map(|p| p.section()).collect();
    if sections.is_empty() {
        return Ok(None);
    }
    let path = workspace.join(LOG_FILE);
    std::fs::write(&path, sections.join("\n"))?;
    Ok(Some(path))
}

/// The `include` list, as paths relative to the repo root.
///
/// Blank lines and `#` comments are skipped. A line that would reach outside
/// the repo is refused rather than followed: this file sits in a repository an
/// agent has write access to, and "copy anything on the machine into somewhere
/// I can read it" is not a power a list of filenames should carry.
fn include_list(repo: &Path) -> (Vec<PathBuf>, Vec<String>) {
    let Ok(text) = std::fs::read_to_string(repo.join(DIR).join(INCLUDE)) else {
        return (Vec::new(), Vec::new());
    };
    let mut paths = Vec::new();
    let mut refused = Vec::new();
    for line in text.lines() {
        let line = line.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        let path = Path::new(line);
        if path.is_absolute() || path.components().any(|c| c.as_os_str() == "..") {
            refused.push(line.to_string());
            continue;
        }
        paths.push(path.to_path_buf());
    }
    (paths, refused)
}

fn carry(ctx: &Context) -> Carried {
    let (paths, refused) = include_list(ctx.repo);
    let mut carried = Carried {
        refused,
        ..Default::default()
    };
    for rel in paths {
        let src = ctx.repo.join(&rel);
        if !src.symlink_metadata().is_ok() {
            carried.missing.push(rel);
            continue;
        }
        let dst = ctx.worktree.join(&rel);
        // Whatever git put there wins. A tracked file that happens to be named
        // in `include` is already the right one, and overwriting it would be a
        // silent local edit to a clean worktree.
        if dst.symlink_metadata().is_ok() {
            continue;
        }
        // Where the line *ends up*, which `include_list` cannot answer: it
        // reads the line, and a line with no `..` and no leading slash still
        // leaves the worktree if something on the way out is a symlink.
        if !lands_inside(ctx.worktree, &dst) {
            carried.refused.push(rel.display().to_string());
            continue;
        }
        match copy_across(&src, &dst) {
            Ok(()) => carried.copied.push(rel),
            Err(err) => carried.failed.push((rel, err.to_string())),
        }
    }
    carried
}

/// Whether writing `dst` really writes inside `worktree`.
///
/// [`include_list`] refuses a line that *reads* like it points outside — a
/// leading `/`, a `..` component. This is the other half, and a different
/// question once a symlink is in the way: a repo that commits `conf -> /etc`
/// and lists `conf/marver` reaches `/etc/marver` through a line containing
/// neither of the things that check looks for.
///
/// Decided by the deepest part of `dst` that already exists. Anything below
/// that is created by [`copy_across`] as real directories, which cannot lead
/// anywhere but where they were made.
fn lands_inside(worktree: &Path, dst: &Path) -> bool {
    let Ok(root) = std::fs::canonicalize(worktree) else {
        return false;
    };
    let mut probe = dst;
    while let Some(parent) = probe.parent() {
        match std::fs::canonicalize(parent) {
            Ok(resolved) => return resolved.starts_with(&root),
            // Not there yet; the question belongs to whatever is above it.
            Err(_) => probe = parent,
        }
    }
    false
}

fn copy_across(src: &Path, dst: &Path) -> std::io::Result<()> {
    if let Some(parent) = dst.parent() {
        std::fs::create_dir_all(parent)?;
    }
    // Settled here rather than by passing `CLONE_NOFOLLOW`, so every platform
    // answers the same way: `clonefile` follows a symlink and clones what it
    // points at, and a `.env` that is a link into a shared directory has to
    // stay a link or it stops tracking the file it was pointed at.
    if std::fs::symlink_metadata(src)?.file_type().is_symlink() {
        return std::os::unix::fs::symlink(std::fs::read_link(src)?, dst);
    }
    // A `node_modules` copied byte for byte is the reason this feature would
    // not be worth having. Where the filesystem can share the blocks it costs
    // nothing and takes no time.
    if clone(src, dst) {
        return Ok(());
    }
    copy_recursive(src, dst)
}

/// Copy-on-write clone, where the platform and filesystem allow one.
///
/// APFS does this for whole directory trees in one call. Linux reflinks are
/// deliberately not attempted: the ioctl is per-file and untested here, and a
/// wrong answer would be a silent, expensive copy rather than a visible error.
#[cfg(target_os = "macos")]
fn clone(src: &Path, dst: &Path) -> bool {
    use std::ffi::CString;
    use std::os::unix::ffi::OsStrExt;

    let (Ok(src), Ok(dst)) = (
        CString::new(src.as_os_str().as_bytes()),
        CString::new(dst.as_os_str().as_bytes()),
    ) else {
        return false;
    };
    // SAFETY: both pointers are NUL-terminated and outlive the call, and
    // `clonefile` neither retains nor frees them.
    unsafe { libc::clonefile(src.as_ptr(), dst.as_ptr(), 0) == 0 }
}

#[cfg(not(target_os = "macos"))]
fn clone(_src: &Path, _dst: &Path) -> bool {
    false
}

fn copy_recursive(src: &Path, dst: &Path) -> std::io::Result<()> {
    let meta = std::fs::symlink_metadata(src)?;
    if meta.file_type().is_symlink() {
        // Recreated, not followed: a link into the repo should keep pointing
        // the same way relative to where it now lives.
        return std::os::unix::fs::symlink(std::fs::read_link(src)?, dst);
    }
    if meta.is_dir() {
        std::fs::create_dir_all(dst)?;
        for entry in std::fs::read_dir(src)? {
            let entry = entry?;
            copy_recursive(&entry.path(), &dst.join(entry.file_name()))?;
        }
        return Ok(());
    }
    std::fs::copy(src, dst).map(|_| ())
}

/// The script at `<repo>/.marver/<name>`, if there is one.
fn script(repo: &Path, name: &str) -> Option<PathBuf> {
    let path = repo.join(DIR).join(name);
    path.is_file().then_some(path)
}

/// How to invoke a script: itself if it is executable, `sh` if it is not.
///
/// Forgetting `chmod +x` is the most likely way to write one of these and have
/// nothing happen, and "nothing happened" is the hardest outcome to debug. A
/// shebang still decides the interpreter in the executable case, so nothing is
/// taken away by being forgiving in the other.
fn command_for(path: &Path) -> Command {
    use std::os::unix::fs::PermissionsExt;

    let executable = std::fs::metadata(path)
        .map(|meta| meta.permissions().mode() & 0o111 != 0)
        .unwrap_or(false);
    if executable {
        Command::new(path)
    } else {
        let mut command = Command::new("sh");
        command.arg(path);
        command
    }
}

fn run(path: &Path, ctx: &Context, timeout: Duration) -> Script {
    use std::os::unix::process::CommandExt;

    let started = Instant::now();
    let mut command = command_for(path);
    command
        .current_dir(ctx.worktree)
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .env("MARVER_WORKTREE", ctx.worktree)
        .env("MARVER_REPO", ctx.repo)
        .env("MARVER_REPO_NAME", ctx.repo_name)
        .env("MARVER_BRANCH", ctx.branch)
        .env("MARVER_BASE", ctx.base)
        .env("MARVER_TASK", ctx.task_id.to_string())
        .env("MARVER_WORKSPACE", ctx.workspace);

    // Its own process group, so the timeout can take the whole tree with it.
    // Killing by pid leaves the `npm install` the script started still running,
    // still writing into a worktree marver is about to decide is clean.
    //
    // SAFETY: `setpgid` is async-signal-safe and touches nothing the forked
    // child shares with us.
    unsafe {
        command.pre_exec(|| {
            if libc::setpgid(0, 0) == -1 {
                return Err(std::io::Error::last_os_error());
            }
            Ok(())
        });
    }

    let mut child = match command.spawn() {
        Ok(child) => child,
        Err(err) => return Script::Failed(err.to_string()),
    };
    let pid = child.id() as libc::pid_t;

    // Three threads, not `wait_with_output`. That waits for the pipes to reach
    // end of file, which is not the same event as the script exiting: a setup
    // that starts a dev server in the background hands the server the same
    // stdout, so the pipe stays open long after `.marver/setup` returned. On
    // `wait_with_output` that held the daemon for the whole 300 seconds and
    // then filed the script as timed out, for a script that succeeded in three.
    //
    // So the pipes get a drainer each — both must be read while the script runs
    // or one filling up deadlocks the other — and the exit is waited for
    // separately.
    let out = drain(child.stdout.take());
    let err = drain(child.stderr.take());
    let (tx, rx) = channel();
    std::thread::spawn(move || {
        let _ = tx.send(child.wait());
    });

    // Whatever the drainers have by now. They are not joined: a survivor
    // holding the write end keeps its reader blocked, and that is exactly the
    // wait this function exists to avoid. The thread ends when the last writer
    // does.
    let collected = |grace: Duration| {
        std::thread::sleep(grace);
        let (out, out_lost) = out.take();
        let (err, err_lost) = err.take();
        merge(&out, &err, out_lost + err_lost)
    };

    match rx.recv_timeout(timeout) {
        Ok(Ok(status)) => Script::Ran {
            ok: status.success(),
            output: collected(SETTLE),
            took: started.elapsed(),
        },
        Ok(Err(err)) => Script::Failed(err.to_string()),
        Err(RecvTimeoutError::Disconnected) => {
            Script::Failed("the script could not be waited for".to_string())
        }
        Err(RecvTimeoutError::Timeout) => {
            // SAFETY: a negative pid signals the process group, and this is one
            // we made ourselves in `pre_exec`.
            unsafe { libc::kill(-pid, libc::SIGKILL) };
            Script::TimedOut {
                after: timeout,
                output: collected(REAP_GRACE),
            }
        }
    }
}

/// A pipe read to its end on its own thread, readable at any moment.
struct Drained(std::sync::Arc<std::sync::Mutex<Tail>>);

impl Drained {
    /// What the pipe has said, and how many bytes were thrown away before it.
    fn take(&self) -> (Vec<u8>, usize) {
        self.0
            .lock()
            .map(|held| (held.kept.clone(), held.dropped))
            .unwrap_or_default()
    }
}

/// A bounded tail of a pipe.
#[derive(Default)]
struct Tail {
    kept: Vec<u8>,
    dropped: usize,
}

fn drain<R: std::io::Read + Send + 'static>(source: Option<R>) -> Drained {
    let held = std::sync::Arc::new(std::sync::Mutex::new(Tail::default()));
    let Some(mut source) = source else {
        return Drained(held);
    };
    let into = std::sync::Arc::clone(&held);
    std::thread::spawn(move || {
        let mut buffer = [0u8; 8192];
        loop {
            match source.read(&mut buffer) {
                Ok(0) | Err(_) => break,
                // Appended as it arrives rather than at the end, so a script
                // that is killed still leaves behind what it had said.
                Ok(read) => {
                    let Ok(mut into) = into.lock() else { break };
                    into.kept.extend_from_slice(&buffer[..read]);
                    // Bounded here rather than in `merge`, which is the last
                    // thing to run and so the last thing that can help. The
                    // daemon is the process holding this, and a `.marver/setup`
                    // that prints a build log has no upper bound on how much it
                    // prints — cutting only at the end meant holding all of it
                    // first, and being killed for it takes every running agent's
                    // supervisor with it.
                    //
                    // `LIMIT` rather than `MAX_OUTPUT`: two pipes are merged
                    // afterwards and the join then trimmed, so each needs to
                    // arrive with a whole budget of its own.
                    if into.kept.len() > LIMIT {
                        let over = into.kept.len() - LIMIT;
                        into.kept.drain(..over);
                        into.dropped += over;
                    }
                }
            }
        }
    });
    Drained(held)
}

/// Both streams as one, in the order a terminal would have shown them well
/// enough. Truncated from the front: a build that fails prints its reason last.
///
/// `lost` is what the drainers already threw away, so the count in the prefix
/// is the whole of what is missing rather than only this function's share.
fn merge(out: &[u8], err: &[u8], lost: usize) -> String {
    let mut text = String::from_utf8_lossy(out).into_owned();
    let stderr = String::from_utf8_lossy(err);
    if !stderr.trim().is_empty() {
        if !text.is_empty() && !text.ends_with('\n') {
            text.push('\n');
        }
        text.push_str(&stderr);
    }
    let text = text.trim_end().to_string();
    if text.len() <= MAX_OUTPUT && lost == 0 {
        return text;
    }
    // On a character boundary, so the result is still a string anyone can read.
    let mut cut = text.len().saturating_sub(MAX_OUTPUT);
    while cut < text.len() && !text.is_char_boundary(cut) {
        cut += 1;
    }
    format!("[…{} bytes earlier]\n{}", lost + cut, &text[cut..])
}

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

    struct Fixture {
        _tmp: TempDir,
        repo: PathBuf,
        worktree: PathBuf,
        workspace: PathBuf,
    }

    impl Fixture {
        fn new() -> Self {
            let tmp = TempDir::new().unwrap();
            let repo = tmp.path().join("repo");
            let workspace = tmp.path().join("workspace");
            let worktree = workspace.join("repo");
            std::fs::create_dir_all(&repo).unwrap();
            std::fs::create_dir_all(&worktree).unwrap();
            Self {
                _tmp: tmp,
                repo,
                worktree,
                workspace,
            }
        }

        fn ctx(&self) -> Context<'_> {
            Context {
                repo: &self.repo,
                repo_name: "repo",
                worktree: &self.worktree,
                branch: "marver/1-thing",
                base: "main",
                task_id: 1,
                workspace: &self.workspace,
            }
        }

        fn marver_file(&self, name: &str, body: &str) -> PathBuf {
            let dir = self.repo.join(DIR);
            std::fs::create_dir_all(&dir).unwrap();
            let path = dir.join(name);
            std::fs::write(&path, body).unwrap();
            path
        }

        fn executable(&self, name: &str, body: &str) -> PathBuf {
            use std::os::unix::fs::PermissionsExt;
            let path = self.marver_file(name, body);
            let mut perms = std::fs::metadata(&path).unwrap().permissions();
            perms.set_mode(0o755);
            std::fs::set_permissions(&path, perms).unwrap();
            path
        }
    }

    #[test]
    fn a_repo_with_nothing_configured_is_silent() {
        let fx = Fixture::new();
        let prepared = prepare(&fx.ctx());
        assert!(prepared.is_quiet());
        assert_eq!(prepared.setup, Script::Absent);
        assert!(prepared.summary().is_none());
        assert_eq!(
            write_log(&fx.workspace, &[prepared]).unwrap(),
            None,
            "an empty log would still have to be explained"
        );
    }

    #[test]
    fn listed_files_are_carried_across() {
        let fx = Fixture::new();
        std::fs::write(fx.repo.join(".env"), "SECRET=1\n").unwrap();
        std::fs::create_dir_all(fx.repo.join("node_modules/pkg")).unwrap();
        std::fs::write(fx.repo.join("node_modules/pkg/index.js"), "//\n").unwrap();
        fx.marver_file(INCLUDE, "# what the tests need\n.env\nnode_modules\n\n");

        let carried = carry(&fx.ctx());

        assert_eq!(carried.failed, vec![]);
        assert_eq!(carried.copied.len(), 2);
        assert_eq!(
            std::fs::read_to_string(fx.worktree.join(".env")).unwrap(),
            "SECRET=1\n"
        );
        assert!(
            fx.worktree.join("node_modules/pkg/index.js").exists(),
            "a directory is carried whole"
        );
    }

    #[test]
    fn a_listed_path_that_is_not_there_is_not_a_failure() {
        // One `include` covers every machine, and not every machine has every
        // file on it.
        let fx = Fixture::new();
        fx.marver_file(INCLUDE, ".env.local\n");

        let carried = carry(&fx.ctx());

        assert!(carried.is_quiet());
        assert_eq!(carried.missing, vec![PathBuf::from(".env.local")]);
        assert!(carried.copied.is_empty());
    }

    #[test]
    fn a_path_reaching_outside_the_repo_is_refused() {
        // `.marver/include` lives in a repository an agent can write to.
        let fx = Fixture::new();
        fx.marver_file(INCLUDE, "../../../etc/passwd\n/etc/hosts\n.env\n");
        std::fs::write(fx.repo.join(".env"), "ok\n").unwrap();

        let carried = carry(&fx.ctx());

        assert_eq!(carried.refused.len(), 2);
        assert!(!carried.is_quiet(), "it must be said out loud");
        assert_eq!(
            carried.copied,
            vec![PathBuf::from(".env")],
            "the honest lines still work"
        );
        assert!(!fx.worktree.join("passwd").exists());
    }

    #[test]
    fn a_line_that_reaches_outside_through_a_symlink_is_refused_too() {
        // The check in `include_list` reads the line, and this line is a
        // perfectly ordinary relative path: no leading slash, no `..`. What
        // takes it out of the worktree is a symlink the repo committed, which
        // git checks out like any other tracked file.
        let fx = Fixture::new();
        let outside = fx._tmp.path().join("outside");
        std::fs::create_dir_all(&outside).unwrap();
        std::os::unix::fs::symlink(&outside, fx.worktree.join("conf")).unwrap();
        std::fs::create_dir_all(fx.repo.join("conf")).unwrap();
        std::fs::write(fx.repo.join("conf/marver"), "carried\n").unwrap();
        fx.marver_file(INCLUDE, "conf/marver\n");

        let carried = carry(&fx.ctx());

        assert_eq!(carried.refused, ["conf/marver"], "{carried:?}");
        assert!(carried.copied.is_empty());
        assert!(
            !outside.join("marver").exists(),
            "nothing may be written outside the worktree"
        );
    }

    #[test]
    fn an_ordinary_nested_path_is_still_carried() {
        // The other side of the check: a directory that does not exist yet is
        // created under the worktree, and creating it is not reaching out of
        // it. Refusing these would take the feature away to close the hole.
        let fx = Fixture::new();
        std::fs::create_dir_all(fx.repo.join("deep/nested")).unwrap();
        std::fs::write(fx.repo.join("deep/nested/.env"), "SECRET=1\n").unwrap();
        fx.marver_file(INCLUDE, "deep/nested/.env\n");

        let carried = carry(&fx.ctx());

        assert!(carried.is_quiet(), "{carried:?}");
        assert_eq!(carried.copied, [PathBuf::from("deep/nested/.env")]);
        assert_eq!(
            std::fs::read_to_string(fx.worktree.join("deep/nested/.env")).unwrap(),
            "SECRET=1\n"
        );
    }

    #[test]
    fn what_git_already_put_there_is_not_overwritten() {
        let fx = Fixture::new();
        std::fs::write(fx.repo.join("config.toml"), "from the repo\n").unwrap();
        std::fs::write(
            fx.worktree.join("config.toml"),
            "tracked, and checked out\n",
        )
        .unwrap();
        fx.marver_file(INCLUDE, "config.toml\n");

        let carried = carry(&fx.ctx());

        assert!(carried.copied.is_empty());
        assert_eq!(
            std::fs::read_to_string(fx.worktree.join("config.toml")).unwrap(),
            "tracked, and checked out\n",
            "a clean worktree must stay clean"
        );
    }

    #[test]
    fn a_symlink_is_recreated_rather_than_followed() {
        let fx = Fixture::new();
        std::fs::write(fx.repo.join("real.env"), "x\n").unwrap();
        std::os::unix::fs::symlink("real.env", fx.repo.join(".env")).unwrap();
        fx.marver_file(INCLUDE, ".env\n");

        carry(&fx.ctx());

        let meta = std::fs::symlink_metadata(fx.worktree.join(".env")).unwrap();
        assert!(meta.file_type().is_symlink());
    }

    #[test]
    fn setup_runs_in_the_worktree_and_is_told_where_it_is() {
        let fx = Fixture::new();
        fx.executable(
            SETUP,
            "#!/bin/sh\npwd > where\necho \"$MARVER_BRANCH\" > branch\necho \"$MARVER_TASK\" > task\n",
        );

        let prepared = prepare(&fx.ctx());

        assert!(prepared.is_quiet(), "{:?}", prepared.setup);
        assert_eq!(
            std::fs::read_to_string(fx.worktree.join("branch"))
                .unwrap()
                .trim(),
            "marver/1-thing"
        );
        assert_eq!(
            std::fs::read_to_string(fx.worktree.join("task"))
                .unwrap()
                .trim(),
            "1"
        );
        let where_it_ran = std::fs::read_to_string(fx.worktree.join("where")).unwrap();
        assert!(
            where_it_ran.trim().ends_with("repo"),
            "it ran in {where_it_ran}"
        );
    }

    #[test]
    fn a_script_without_the_executable_bit_still_runs() {
        // Forgetting chmod +x is the likeliest way to write one of these and
        // have nothing at all happen.
        let fx = Fixture::new();
        fx.marver_file(SETUP, "echo hello\n");

        let prepared = prepare(&fx.ctx());

        match prepared.setup {
            Script::Ran { ok, output, .. } => {
                assert!(ok);
                assert_eq!(output, "hello");
            }
            other => panic!("expected it to run: {other:?}"),
        }
    }

    #[test]
    fn a_failing_setup_is_reported_and_does_not_panic() {
        let fx = Fixture::new();
        fx.executable(SETUP, "#!/bin/sh\necho 'no lockfile' >&2\nexit 1\n");

        let prepared = prepare(&fx.ctx());

        assert!(!prepared.is_quiet());
        assert_eq!(
            prepared.summary().as_deref(),
            Some("repo: .marver/setup failed")
        );
        match &prepared.setup {
            Script::Ran { ok, output, .. } => {
                assert!(!ok);
                assert!(output.contains("no lockfile"), "stderr must survive");
            }
            other => panic!("expected a run: {other:?}"),
        }
    }

    #[test]
    fn output_from_both_streams_reaches_the_log() {
        let fx = Fixture::new();
        fx.executable(SETUP, "#!/bin/sh\necho out\necho err >&2\n");

        let prepared = prepare(&fx.ctx());
        let path = write_log(&fx.workspace, std::slice::from_ref(&prepared))
            .unwrap()
            .expect("something was said");
        let log = std::fs::read_to_string(path).unwrap();

        assert!(log.contains("# repo"));
        assert!(log.contains("out"), "{log}");
        assert!(log.contains("err"), "{log}");
    }

    #[test]
    fn a_script_that_never_ends_is_killed_with_its_children() {
        let fx = Fixture::new();
        // The child outlives the script itself, which is the case killing by
        // pid gets wrong: `sleep` keeps the worktree busy after `sh` is gone.
        fx.executable(SETUP, "#!/bin/sh\nsleep 120 &\nsleep 120\n");
        let ctx = fx.ctx();

        let outcome = run(
            &fx.repo.join(DIR).join(SETUP),
            &ctx,
            Duration::from_millis(300),
        );

        match outcome {
            Script::TimedOut { after, .. } => assert_eq!(after, Duration::from_millis(300)),
            other => panic!("expected a timeout: {other:?}"),
        }
    }

    #[test]
    fn a_script_that_leaves_something_running_is_still_over_when_it_exits() {
        let fx = Fixture::new();
        // The dev server case. It inherits the script's stdout, so the pipe
        // stays open after the script is gone — and waiting on end of file
        // instead of on the exit held the daemon for the whole timeout and
        // then filed a successful script as one that hung.
        fx.executable(SETUP, "#!/bin/sh\necho ready\nsleep 30 &\n");
        let ctx = fx.ctx();

        let started = Instant::now();
        let outcome = run(
            &fx.repo.join(DIR).join(SETUP),
            &ctx,
            Duration::from_secs(10),
        );

        assert!(
            started.elapsed() < Duration::from_secs(5),
            "waited {:?} for a script that exited at once",
            started.elapsed()
        );
        match outcome {
            Script::Ran { ok, output, .. } => {
                assert!(ok);
                assert_eq!(output, "ready", "and what it said arrives with it");
            }
            other => panic!("expected a run: {other:?}"),
        }
    }

    #[test]
    fn teardown_runs_when_there_is_one() {
        let fx = Fixture::new();
        fx.executable(
            TEARDOWN,
            "#!/bin/sh\necho gone > $MARVER_WORKSPACE/left-behind\n",
        );
        std::fs::create_dir_all(&fx.workspace).unwrap();

        let outcome = teardown(&fx.ctx());

        assert!(outcome.is_quiet(), "{outcome:?}");
        assert!(fx.workspace.join("left-behind").exists());
    }

    #[test]
    fn teardown_is_absent_when_only_setup_exists() {
        let fx = Fixture::new();
        fx.executable(SETUP, "#!/bin/sh\ntrue\n");
        assert_eq!(teardown(&fx.ctx()), Script::Absent);
    }

    #[test]
    fn a_torrent_of_output_is_bounded_while_it_arrives() {
        // The cap used to be applied only in `merge`, which runs last — so
        // every byte was held first. The daemon is the process holding it, and
        // a `.marver/setup` printing a build log has no upper bound; being
        // OOM-killed for it takes every running agent's supervisor with it.
        let fx = Fixture::new();
        fx.executable(
            SETUP,
            "#!/bin/sh\nawk 'BEGIN{for(i=0;i<400000;i++) print \"padding line\" i}'\necho THE_REASON\n",
        );
        let ctx = fx.ctx();

        let outcome = run(
            &fx.repo.join(DIR).join(SETUP),
            &ctx,
            Duration::from_secs(30),
        );

        match outcome {
            Script::Ran { ok, output, .. } => {
                assert!(ok);
                assert!(
                    output.ends_with("THE_REASON"),
                    "the tail is still the point"
                );
                assert!(
                    output.len() <= MAX_OUTPUT + 64,
                    "kept {} bytes of a multi-megabyte script",
                    output.len()
                );
                assert!(
                    output.starts_with("[…"),
                    "and the cut is admitted: {}",
                    &output[..40]
                );
            }
            other => panic!("expected a run: {other:?}"),
        }
    }

    #[test]
    fn a_long_output_keeps_its_end() {
        let fx = Fixture::new();
        fx.executable(
            SETUP,
            "#!/bin/sh\nawk 'BEGIN{for(i=0;i<20000;i++) print \"line\" i}'\necho THE_REASON\n",
        );

        let prepared = prepare(&fx.ctx());

        match &prepared.setup {
            Script::Ran { output, .. } => {
                assert!(output.len() <= MAX_OUTPUT + 64, "{}", output.len());
                assert!(output.ends_with("THE_REASON"), "the tail is the point");
                assert!(output.starts_with("[…"), "and the cut is admitted");
            }
            other => panic!("expected a run: {other:?}"),
        }
    }

    #[test]
    fn the_log_gathers_every_repo() {
        let fx = Fixture::new();
        let quiet = Prepared {
            repo_name: "web".to_string(),
            carried: Carried::default(),
            setup: Script::Absent,
        };
        let noisy = Prepared {
            repo_name: "api".to_string(),
            carried: Carried::default(),
            setup: Script::Ran {
                ok: false,
                output: "boom".to_string(),
                took: Duration::from_secs(2),
            },
        };

        let path = write_log(&fx.workspace, &[quiet, noisy]).unwrap().unwrap();
        let log = std::fs::read_to_string(path).unwrap();

        assert!(log.contains("# api"));
        assert!(
            !log.contains("# web"),
            "a repo with nothing to say says nothing"
        );
    }
}