Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

15.7 KB
Raw Blame
//! Discover and terminate processes whose working directory is under a
//! worktree, for `wt remove --reap` (experimental).
//!
//! # Purpose
//!
//! Removing a worktree leaves behind any long-running process started inside
//! it — a `post-start` dev server, a watcher, a language server — still
//! holding ports and file handles. `--reap` opts into terminating those
//! processes as part of removal.
//!
//! # Discovery
//!
//! Processes are discovered by working directory: any process whose `cwd` is
//! at or under the worktree path. Linux reads `/proc/<pid>/cwd` directly so a
//! system-wide `lsof` scan cannot time out and hide all candidates. Other Unix
//! systems use `lsof -d cwd`; [`parse_lsof_cwd`] parses its output. Both paths
//! skip processes whose cwd cannot be read and filter by the worktree prefix.
//!
//! # Data-safety contract
//!
//! Killing a process the user did not mean to kill — an editor with unsaved
//! buffers, an interactive shell — is exactly the silent loss-of-work the
//! project refuses without explicit consent. Two guards keep `--reap`
//! conservative:
//!
//! - **Controlling-terminal exclusion.** A process holding a controlling
//!   terminal is an interactive shell (including the one `wt remove` was run
//!   from) or a terminal editor (`vim`, `nvim`, `emacs -nw`). These are the
//!   "keep-me" set; `without_controlling_terminal` drops them via `ps -o
//!   tty=`, so only detached processes (dev servers, watchers, daemons) remain
//!   candidates.
//! - **Self-exclusion.** The current `wt` process is never a candidate.
//!
//! cwd-based discovery is also **under-inclusive by design**: a daemon that
//! forked and `chdir`'d away, or reparented to pid 1, no longer reports a cwd
//! under the path and is not found. Those are what [`wt step tether`] is built
//! to reap (it kills the whole process group). `--reap` and `tether` cover
//! different gaps and are not substitutes.
//!
//! # Platform
//!
//! Unix only. Windows has no cheap per-process cwd, so the whole module is
//! `#[cfg(unix)]` and the `wt remove` command rejects `--reap` there.
//!
//! [`wt step tether`]: https://worktrunk.dev/step/#wt-step-tether

#![cfg(unix)]

use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::time::Duration;

use crate::shell_exec::Cmd;

use super::fsmonitor::{NixSignaller, REAP_KILL_DEADLINE, escalate_terminate};

/// One process discovered under a worktree: its PID, short command name, and
/// the working directory reported by the platform's process probe.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CwdProcess {
    pub pid: u32,
    /// Short command name from `/proc` or `lsof`.
    pub command: String,
    pub cwd: PathBuf,
}

/// Timeout for the `lsof` / `ps` probes. Discovery is opt-in and off the hot
/// path, but a hung probe should still not stall removal indefinitely. The
/// PowerShell profile query (`shell::paths`) shares this bound.
///
/// Tests override via `WORKTRUNK_TEST_PROBE_TIMEOUT_MS` (set generously in
/// `STATIC_TEST_ENV_VARS`): under suite load a probe's spawn alone can stall
/// past the production bound, and the timeout's fail-safe empty result then
/// reads as "no processes to reap" — a load-dependent test outcome.
pub(crate) fn probe_timeout() -> Duration {
    let ms = std::env::var("WORKTRUNK_TEST_PROBE_TIMEOUT_MS")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(5_000);
    Duration::from_millis(ms)
}

/// Parse `lsof -d cwd -F pcn` field output into one [`CwdProcess`] per process.
///
/// `lsof` field output emits one record per line, prefixed by a field id:
/// `p<pid>` opens a new process, `c<command>` names it, and `n<path>` gives the
/// cwd (there is exactly one cwd file per process, selected by `-d cwd`). A
/// process contributes a [`CwdProcess`] only once its `n` (cwd path) line is
/// seen; records missing a path are skipped.
pub fn parse_lsof_cwd(stdout: &str) -> Vec<CwdProcess> {
    let mut out = Vec::new();
    let mut pid: Option<u32> = None;
    let mut command = String::new();

    for line in stdout.lines() {
        let Some((tag, rest)) = line.split_at_checked(1) else {
            continue;
        };
        match tag {
            "p" => {
                pid = rest.trim().parse::<u32>().ok();
                command = String::new();
            }
            "c" => command = rest.to_string(),
            "n" => {
                if let Some(pid) = pid {
                    out.push(CwdProcess {
                        pid,
                        command: command.clone(),
                        cwd: PathBuf::from(rest),
                    });
                }
            }
            _ => {}
        }
    }
    out
}

/// Parse `ps -o pid=,tty=` output into `(pid, has_controlling_terminal)` pairs.
///
/// `ps` prints one line per PID: the PID, then the controlling terminal or a
/// "none" marker (`?` / `??` on Linux/macOS, `-` on some platforms). A terminal
/// name that starts with `?` or equals `-` means no controlling terminal.
///
/// This feeds a data-safety gate (a process *with* a terminal is spared), so
/// the unreadable case fails safe: a line missing the tty column is reported as
/// **having** a terminal, so an unparsable reading never turns into a reap.
/// Real `ps -o tty=` always fills the column, so this only guards the anomaly.
pub fn parse_ps_tty(stdout: &str) -> Vec<(u32, bool)> {
    stdout
        .lines()
        .filter_map(|line| {
            let mut fields = line.split_whitespace();
            let pid = fields.next()?.parse::<u32>().ok()?;
            let has_tty = match fields.next() {
                Some(tty) => !(tty.starts_with('?') || tty == "-"),
                None => true,
            };
            Some((pid, has_tty))
        })
        .collect()
}

/// Return the subset of `pids` that hold **no** controlling terminal.
///
/// Runs `ps -o pid=,tty=` over the candidate PIDs and keeps those whose
/// terminal is a "none" marker — the detached processes safe to reap. A PID
/// `ps` does not report (it exited between discovery and this probe, or `ps`
/// exited non-zero because every requested PID was gone) simply doesn't appear
/// in the output, so it's dropped. A `ps` spawn failure yields an empty set:
/// without a terminal reading, nothing is reaped (fail-safe).
fn without_controlling_terminal(pids: &[u32]) -> HashSet<u32> {
    if pids.is_empty() {
        return HashSet::new();
    }
    let pid_list = pids
        .iter()
        .map(u32::to_string)
        .collect::<Vec<_>>()
        .join(",");
    // Parse whatever `ps` printed regardless of exit status: it exits non-zero
    // when some requested PIDs are gone but still lists the live ones (the same
    // partial-output shape `lsof` has in `processes_under`).
    let Ok(output) = Cmd::new("ps")
        .args(["-o", "pid=,tty=", "-p", &pid_list])
        .timeout(probe_timeout())
        .run()
    else {
        return HashSet::new();
    };
    parse_ps_tty(&String::from_utf8_lossy(&output.stdout))
        .into_iter()
        .filter_map(|(pid, has_tty)| (!has_tty).then_some(pid))
        .collect()
}

/// Discover processes whose cwd is at or under `worktree_path`, excluding the
/// current `wt` process. This is the raw discovery step, *before* the
/// controlling-terminal guard — [`collect_reapable`] layers that on top.
///
/// Best-effort: unreadable or disappeared processes are skipped. On non-Linux
/// Unix, an `lsof` spawn failure yields an empty list. Results are sorted by
/// PID for stable output.
pub fn processes_under(worktree_path: &Path) -> Vec<CwdProcess> {
    let canonical =
        dunce::canonicalize(worktree_path).unwrap_or_else(|_| worktree_path.to_path_buf());
    let self_pid = std::process::id();

    #[cfg(target_os = "linux")]
    let processes = processes_from_proc(Path::new("/proc"));
    #[cfg(not(target_os = "linux"))]
    let processes = processes_from_lsof();

    let mut candidates: Vec<CwdProcess> = processes
        .into_iter()
        .filter(|p| p.pid != self_pid)
        .filter(|p| p.cwd.starts_with(&canonical))
        .collect();
    candidates.sort_by_key(|p| p.pid);
    candidates
}

#[cfg(target_os = "linux")]
fn processes_from_proc(proc_root: &Path) -> Vec<CwdProcess> {
    let Ok(entries) = std::fs::read_dir(proc_root) else {
        return Vec::new();
    };
    entries
        .filter_map(Result::ok)
        .filter_map(|entry| {
            let pid = entry.file_name().to_str()?.parse::<u32>().ok()?;
            let cwd = std::fs::read_link(entry.path().join("cwd")).ok()?;
            let command = std::fs::read_to_string(entry.path().join("comm"))
                .unwrap_or_default()
                .trim_end_matches('\n')
                .to_owned();
            Some(CwdProcess { pid, command, cwd })
        })
        .collect()
}

#[cfg(not(target_os = "linux"))]
fn processes_from_lsof() -> Vec<CwdProcess> {
    // `lsof -d cwd` lists every visible process's cwd. It exits non-zero when
    // some processes are inaccessible (other users), but still prints the
    // accessible ones — so parse whatever stdout we got rather than gating on
    // exit status. Only a spawn failure (lsof missing) means "no data".
    let Ok(output) = Cmd::new("lsof")
        .args(["-d", "cwd", "-F", "pcn"])
        .timeout(probe_timeout())
        .run()
    else {
        return Vec::new();
    };

    parse_lsof_cwd(&String::from_utf8_lossy(&output.stdout))
}

/// Discover the processes eligible for reaping under `worktree_path`.
///
/// Applies the full data-safety contract: [`processes_under`] (cwd prefix,
/// self-exclusion) then drops any process holding a controlling terminal.
/// Returns candidates sorted by PID for stable output.
pub fn collect_reapable(worktree_path: &Path) -> Vec<CwdProcess> {
    let mut candidates = processes_under(worktree_path);
    if candidates.is_empty() {
        return candidates;
    }

    let pids: Vec<u32> = candidates.iter().map(|p| p.pid).collect();
    let reapable = without_controlling_terminal(&pids);
    candidates.retain(|p| reapable.contains(&p.pid));
    candidates
}

/// `SIGTERM`→wait→`SIGKILL` each PID, returning the count confirmed gone.
///
/// Thin wrapper over `escalate_terminate` with the production
/// `NixSignaller` and the shared `REAP_KILL_DEADLINE`, so `--reap` uses the
/// same bounded escalation as the fsmonitor sweep.
pub fn reap_pids(pids: &[u32]) -> usize {
    escalate_terminate(&NixSignaller, pids, REAP_KILL_DEADLINE)
}

/// Pluralized noun for a process count (`"process"` / `"processes"`).
pub fn process_noun(count: usize) -> &'static str {
    if count == 1 { "process" } else { "processes" }
}

/// Human summary of a reap outcome. `Ok` when every process was terminated (the
/// caller renders it as success); `Err` when some survived both `SIGTERM` and
/// `SIGKILL` (rendered as a warning).
pub fn reap_summary(count: usize, gone: usize) -> Result<String, String> {
    let noun = process_noun(count);
    if gone >= count {
        Ok(format!("Reaped {count} {noun}"))
    } else {
        let survived = count - gone;
        Err(format!(
            "Reaped {gone} of {count} {noun}; {survived} ignored SIGTERM & SIGKILL"
        ))
    }
}

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

    #[cfg(target_os = "linux")]
    #[test]
    fn missing_procfs_yields_no_processes() {
        let root = crate::testing::tempdir().unwrap();
        assert!(processes_from_proc(&root.path().join("absent")).is_empty());
    }

    #[test]
    fn parse_lsof_cwd_extracts_pid_command_and_path() {
        let stdout = "\
p101
cnode
fcwd
n/home/user/repo.feature
p202
cesbuild
fcwd
n/home/user/repo.feature/node_modules/.bin
";
        let procs = parse_lsof_cwd(stdout);
        assert_eq!(
            procs,
            vec![
                CwdProcess {
                    pid: 101,
                    command: "node".into(),
                    cwd: PathBuf::from("/home/user/repo.feature"),
                },
                CwdProcess {
                    pid: 202,
                    command: "esbuild".into(),
                    cwd: PathBuf::from("/home/user/repo.feature/node_modules/.bin"),
                },
            ]
        );
    }

    #[test]
    fn parse_lsof_cwd_skips_process_without_cwd_line() {
        // A process whose cwd lsof could not read (no `n` line) is dropped; a
        // blank line and unknown field tags (`f`) are ignored.
        let stdout = "\
p101
cbash

p202
czsh
fcwd
n/home/user/repo.feature
";
        let procs = parse_lsof_cwd(stdout);
        assert_eq!(procs.len(), 1);
        assert_eq!(procs[0].pid, 202);
    }

    #[test]
    fn parse_ps_tty_classifies_terminal_presence() {
        // Linux `?`, macOS `??`, and `-` all mean "no controlling terminal";
        // `pts/2` / `s001` are real terminals.
        let stdout = "\
  101 ?
  202 pts/2
  303 ??
  404 s001
  505 -
";
        let ttys = parse_ps_tty(stdout);
        assert_eq!(
            ttys,
            vec![
                (101, false),
                (202, true),
                (303, false),
                (404, true),
                (505, false),
            ]
        );
    }

    #[test]
    fn parse_ps_tty_ignores_unparsable_lines() {
        // A pid-only line (no tty column) fails safe as "has terminal" so an
        // unreadable reading never becomes a reap candidate.
        let stdout = "\
header junk
  101 ?
  707
not-a-pid tty
";
        assert_eq!(parse_ps_tty(stdout), vec![(101, false), (707, true)]);
    }

    #[test]
    fn without_controlling_terminal_empty_input_is_empty() {
        assert!(without_controlling_terminal(&[]).is_empty());
    }

    #[test]
    fn discovery_on_nonexistent_path_is_empty() {
        // A path that can't be canonicalized falls back to itself; no live
        // process has a cwd under it, so both discovery layers return empty.
        let missing = Path::new("/nonexistent/worktrunk-reap-xyz");
        assert!(processes_under(missing).is_empty());
        assert!(collect_reapable(missing).is_empty());
    }

    #[test]
    fn reap_summary_reports_success_and_survivors() {
        assert_eq!(process_noun(1), "process");
        assert_eq!(process_noun(2), "processes");
        assert_eq!(reap_summary(1, 1), Ok("Reaped 1 process".into()));
        assert_eq!(reap_summary(3, 3), Ok("Reaped 3 processes".into()));
        assert_eq!(
            reap_summary(3, 1),
            Err("Reaped 1 of 3 processes; 2 ignored SIGTERM & SIGKILL".into())
        );
    }

    /// `reap_pids` against a real process: `SIGTERM` terminates it and the
    /// count comes back confirmed. Discovery is covered in-process by the
    /// `test_remove_reap_kills_process` integration test (which polls
    /// `processes_under` directly); the controlling-terminal guard's
    /// classification has the `parse_ps_tty` unit tests, and the spawned `wt`
    /// exercises the assembled gate — so this focuses on the signalling half.
    #[test]
    fn reap_pids_terminates_a_process() {
        use std::process::Command;

        let mut child = Command::new("sleep").arg("30").spawn().unwrap();
        let pid = child.id();

        // Reap the zombie concurrently: `sleep` is a direct child here, so
        // after SIGTERM it lingers as a zombie (still "alive" to `kill(pid,0)`)
        // until `wait()`. Real reap targets are detached, not `wt`'s children,
        // so `escalate_terminate` sees them vanish. A thread already blocked in
        // `wait()` reaps the zombie the instant it exits, letting the alive
        // check flip within a poll cycle.
        let reaper = std::thread::spawn(move || child.wait().unwrap());
        let gone = reap_pids(&[pid]);
        let status = reaper.join().unwrap();

        assert_eq!(gone, 1, "child {pid} was not confirmed terminated");
        use std::os::unix::process::ExitStatusExt;
        assert_eq!(
            status.signal(),
            Some(nix::sys::signal::Signal::SIGTERM as i32)
        );
    }
}