granite-cli 0.2.3

//! Bob lifecycle-hook management for usage tracking.
//!
//! Registers a `SessionStart` hook in `<workspace>/.bob/settings.json` that
//! captures Bob's `SessionStart` hook payload (containing `hook_event_name`,
//! `session_id`, `cwd`, `source`) into a capture file and lockfile stored under the launcher's
//! per-instance state directory (`GRANITE_CLI_HOME/launcher-state/<launcher_id>/`),
//! NOT inside `<workspace>/.bob/`.  Some projects commit their `.bob/` directory
//! to source control; the capture and lock files are purely
//! `granite-cli`'s internal bookkeeping — Bob never reads them — so they must
//! not live inside the workspace where they risk being committed to the
//! wrapped project's repo.
//!
//! The marker command string is deterministic for a given workspace across
//! separate `granite-cli` processes, serving as a mutual-exclusion key: if
//! another instance already registered the same marker, we detect a live
//! collision (via the PID lockfile) and fail the whole launch.
//!
//! **Ancestry gating (narrow-race mitigation).**  The registered
//! `SessionStart` hook fires for *every* `bob` session start in the workspace,
//! not just the one managed by this `granite-cli` process.  An unmanaged `bob`
//! started independently (not by granite-cli) in the same workspace would also
//! trigger the hook, writing a capture file with the wrong session_id.  To
//! close this race, the marker command carries a `--ancestor-lock` path; the
//! capture subcommand reads that lockfile at hook-fire time, extracts the
//! registrant's PID, and verifies (via OS-level process-tree introspection)
//! that it is an ancestor of the current process before writing the capture
//! file.  OS lookup failures are treated as "assume yes" so this check only
//! produces false positives (prevents writes) in the narrow case where a
//! competing process is actually running.

// Standard
use std::path::{Path, PathBuf};
use std::process::Command;

// Third Party
use alog::{MessageLevel, alog_channel, use_channel};
use anyhow::Context;

use_channel!("BOB");

/*-- public types --*/

/// Returned by a successful `register_or_fail` call: everything the caller
/// needs to wait for the capture and clean up afterward.
pub struct HookRegistration {
    pub capture_path: PathBuf,
    /// Path to the PID lockfile.  The launcher doesn't read this directly
    /// (lock checking is internal to `register_or_fail`), but it's exposed
    /// so callers can manually clean it up if needed.
    #[allow(dead_code)]
    pub lock_path: PathBuf,
    pub marker_command: String,
}

/*-- helpers --*/

/// Returns the workspace-scoped `.bob` directory path.
fn bob_dir(workspace: &Path) -> PathBuf {
    workspace.join(".bob")
}

/// Escape a workspace path into a filesystem-safe filename component, using
/// the same delimiter as `session::generate_session_id`
/// (`crate::config::PATH_DELIM`) so two different workspaces never collide
/// once these files live in a single shared per-launcher-instance directory.
///
/// Replaces `/`, `\`, and `:` (unlike `generate_session_id`, which only
/// replaces `/`): on Windows a workspace path uses `\` as its separator and
/// has a drive-letter `:` (e.g. `C:\Users\...`). Leaving those in place would
/// mean the "escaped" string still contains path separators, so
/// `Path::join`-ing it onto the launcher-state directory would be treated as
/// more path segments — or, if it looks absolute, would discard the base
/// directory entirely — instead of producing a single flat filename
/// component; a bare `:` is also illegal in a Windows filename on its own.
fn escape_workspace(workspace: &Path) -> String {
    workspace
        .to_string_lossy()
        .replace(['/', '\\', ':'], crate::config::PATH_DELIM)
}

/// Resolve the capture-file path for `workspace` under this launcher
/// instance's state directory.
///
/// Returns `anyhow::Err` if `launcher_state_dir` cannot be resolved
/// (e.g. `GRANITE_CLI_HOME` is invalid).  The caller (`register_or_fail`)
/// must ensure the resolved directory exists before writing.
fn capture_path(launcher_id: &str, workspace: &Path) -> anyhow::Result<PathBuf> {
    let dir = crate::config::Config::launcher_state_dir(launcher_id)?;
    Ok(dir.join(format!("{}.capture.json", escape_workspace(workspace))))
}

/// Resolve the PID lockfile path for `workspace` under this launcher
/// instance's state directory.
///
/// Returns `anyhow::Err` if `launcher_state_dir` cannot be resolved;
/// `unregister` treats this as best-effort (logs at debug and returns).
fn lock_path(launcher_id: &str, workspace: &Path) -> anyhow::Result<PathBuf> {
    let dir = crate::config::Config::launcher_state_dir(launcher_id)?;
    Ok(dir.join(format!("{}.lock", escape_workspace(workspace))))
}

/// Platform-correct shell quoting for embedding a path in a shell command
/// string. On Unix, uses single-quote escaping; on Windows, uses
/// double-quote escaping per `cmd.exe` conventions.
pub fn shell_quote(s: &str) -> String {
    #[cfg(unix)]
    return shell_quote_unix(s);

    #[cfg(windows)]
    return shell_quote_windows(s);
}

#[cfg(unix)]
fn shell_quote_unix(s: &str) -> String {
    if s.contains('\'') {
        // Standard POSIX trick: close the quote, insert a literal
        // single-quoted-escaped quote via double quotes, reopen.
        // Use split/join to avoid double-replacement (the replacement
        // string itself contains single quotes that must not be further
        // escaped).
        let parts: Vec<_> = s.split('\'').collect();
        let escaped = parts.join("'\"'\"'");
        format!("'{escaped}'")
    } else {
        format!("'{s}'")
    }
}

#[cfg(windows)]
fn shell_quote_windows(s: &str) -> String {
    if s.contains(|c: char| c == '"') {
        // Windows cmd.exe: escape embedded double quotes by doubling them.
        format!("\"{}\"", s.replace('"', "\"\""))
    } else {
        format!("\"{s}\"")
    }
}

/// Build the marker command string from the current executable and
/// capture/lock paths, using the correct platform shell quoting.
///
/// The `lock_path` argument identifies the PID lockfile written by
/// `register_or_fail`; at hook-fire time the `bob-hook-capture` subcommand
/// reads this file to learn which PID to check against the current process
/// tree (ancestry gating).  Passing the path — not a raw PID — keeps the
/// marker string fully deterministic across registration attempts, which is
/// essential for collision detection in `register_or_fail`.
///
/// This is a thin wrapper around `build_marker_command_with_exe` that
/// calls `std::env::current_exe()` to get the real binary path.
pub fn build_marker_command(capture_path: &Path, lock_path: &Path) -> anyhow::Result<String> {
    let exe = std::env::current_exe()?;
    Ok(build_marker_command_with_exe(&exe, capture_path, lock_path))
}

/// Build the marker command string, given an explicit exe path.
///
/// This is the testable core of `build_marker_command`: callers inject a
/// fake path to keep tests deterministic.  The `lock_path` argument is
/// passed through to the marker string (as `--ancestor-lock`) so the
/// `bob-hook-capture` subcommand can perform ancestry gating at hook-fire
/// time without baking a process-specific PID into the deterministic string.
pub fn build_marker_command_with_exe(exe: &Path, capture_path: &Path, lock_path: &Path) -> String {
    let exe_q = shell_quote(exe.to_string_lossy().as_ref());
    let cap_q = shell_quote(capture_path.to_string_lossy().as_ref());
    let lock_q = shell_quote(lock_path.to_string_lossy().as_ref());
    format!("{exe_q} internal bob-hook-capture {cap_q} --ancestor-lock {lock_q}")
}

/// Read `<workspace>/.bob/settings.json` if it exists and parse as JSON;
/// returns `{}` if the file is absent, empty, or fails to parse.
pub fn read_settings(workspace: &Path) -> serde_json::Value {
    let settings_file = bob_dir(workspace).join("settings.json");
    match std::fs::read_to_string(&settings_file) {
        Ok(content) => match content.trim().is_empty() {
            true => serde_json::json!({}),
            false => match serde_json::from_str(&content) {
                Ok(value) => value,
                Err(e) => {
                    alog_channel!(
                        MessageLevel::Debug,
                        "read_settings: failed to parse {}: {}",
                        settings_file.display(),
                        e
                    );
                    serde_json::json!({})
                }
            },
        },
        Err(_) => serde_json::json!({}), // File doesn't exist or can't be read
    }
}

/// Write `value` as pretty-printed JSON to `<workspace>/.bob/settings.json`.
///
/// Assumes `<workspace>/.bob/` already exists -- callers going through
/// `BobLauncher::launch()` get this via `ensure_workspace_config_dir` which
/// is called unconditionally before any hook registration; direct callers
/// (such as tests) must create the directory themselves first.
///
/// This function CAN return an error (registration should fail loudly if we
/// can't even write the file).
pub fn write_settings(workspace: &Path, value: &serde_json::Value) -> anyhow::Result<()> {
    let bob_dir_path = bob_dir(workspace);
    let settings_file = bob_dir_path.join("settings.json");
    let serialized = serde_json::to_string_pretty(value)?;
    std::fs::write(&settings_file, format!("{serialized}\n"))?;
    Ok(())
}

/// Returns true if `settings["hooks"]["SessionStart"]` contains any entry
/// whose `command` field exactly equals `marker_command`.
///
/// Handles every shape gracefully — missing `hooks` key, `SessionStart` not
/// an array, etc. always means "not found".
pub fn hooks_session_start_contains(settings: &serde_json::Value, marker_command: &str) -> bool {
    let session_start = settings
        .get("hooks")
        .and_then(|h| h.get("SessionStart"))
        .and_then(|ss| ss.as_array());

    session_start.is_some_and(|arr| {
        arr.iter().any(|group| {
            group
                .get("hooks")
                .and_then(|h| h.as_array())
                .is_some_and(|hooks_arr| {
                    hooks_arr.iter().any(|hook| {
                        hook.get("command")
                            .and_then(|c| c.as_str())
                            .is_some_and(|c| c == marker_command)
                    })
                })
        })
    })
}

/// Pushes one new group `{"hooks": [{"type": "command", "command":
/// marker_command, "timeout": 5}]}` into `settings["hooks"]["SessionStart"]`,
/// creating the `hooks`/`SessionStart` objects/arrays as needed if missing.
pub fn add_marker(settings: &mut serde_json::Value, marker_command: &str) {
    // Defensive: a `.bob/settings.json` could contain syntactically valid
    // but non-object JSON (e.g. `[1,2,3]`) if it's corrupted or hand-edited.
    // Treat that the same as an empty settings file rather than panicking --
    // this whole feature is meant to be best-effort, never fatal to launch.
    if !settings.is_object() {
        *settings = serde_json::json!({});
    }
    let new_group = serde_json::json!({
        "hooks": [
            {
                "type": "command",
                "command": marker_command,
                "timeout": 5
            }
        ]
    });
    let hooks = settings
        .as_object_mut()
        .expect("settings is an object")
        .entry("hooks")
        .or_insert_with(|| serde_json::Value::Object(Default::default()))
        .as_object_mut()
        .expect("hooks is an object");
    let session_start = hooks
        .entry("SessionStart")
        .or_insert_with(|| serde_json::Value::Array(vec![]))
        .as_array_mut()
        .expect("SessionStart should be an array after or_insert_with");
    session_start.push(new_group);
}

/// Removes any hook entry whose `command` equals `marker_command` from every
/// `SessionStart` group; if a group's `hooks` array becomes empty after
/// removal, remove that whole group too. Leaves everything else in settings
/// untouched.
pub fn remove_marker(settings: &mut serde_json::Value, marker_command: &str) {
    let hooks = match settings.get_mut("hooks") {
        Some(hooks) => hooks,
        None => return,
    };
    let session_start = match hooks.get_mut("SessionStart") {
        Some(ss) => ss,
        None => return,
    };
    let arr = match session_start.as_array_mut() {
        Some(arr) => arr,
        None => return,
    };

    // Rebuild each group to remove filtered hooks, pruning empty groups.
    let mut rebuilt = Vec::new();
    for group in arr.drain(..) {
        if let Some(hooks_arr) = group.get("hooks").and_then(|h| h.as_array()) {
            let filtered: Vec<_> = hooks_arr
                .iter()
                .filter(|hook| hook.get("command").and_then(|c| c.as_str()) != Some(marker_command))
                .cloned()
                .collect();
            if !filtered.is_empty() {
                let mut new_group = group.clone();
                if let Some(obj) = new_group.as_object_mut() {
                    obj.insert("hooks".to_string(), serde_json::Value::Array(filtered));
                }
                rebuilt.push(new_group);
            }
        }
    }
    *arr = rebuilt;

    // Remove SessionStart entirely if all groups were pruned.
    if arr.is_empty()
        && let Some(hooks_obj) = hooks.as_object_mut()
    {
        hooks_obj.remove("SessionStart");
    }
}

/// PID liveness check.
///
/// `#[cfg(unix)]`: uses `kill -0 <pid>` via `std::process::Command`.
/// `#[cfg(windows)]`: uses `tasklist /FI "PID eq <pid>" /NH` and checks
/// whether its stdout contains the pid string.
pub fn is_pid_alive(pid: u32) -> bool {
    #[cfg(unix)]
    {
        Command::new("kill")
            .arg("-0")
            .arg(pid.to_string())
            .status()
            .is_ok_and(|s| s.success())
    }

    #[cfg(windows)]
    {
        let output = Command::new("tasklist")
            .args(["/FI", &format!("PID eq {pid}"), "/NH"])
            .output();
        matches!(output, Ok(o) if String::from_utf8_lossy(&o.stdout).contains(&pid.to_string()))
    }
}

/// Resolve the parent PID for the given process.
///
/// Returns `Ok(Some(ppid))` with the parent's PID on success.  Returns
/// `Ok(None)` when the process has no parent (reached init/PID 1 on Unix or
/// the root process on Windows — a definitive "no more ancestors" result).
/// Returns `Err(())` when the OS-level lookup itself fails (missing tool,
/// unparseable output, process gone, etc.) — a genuine lookup error, not
/// just "no parent."
#[cfg(unix)]
fn parent_pid(pid: u32) -> Result<Option<u32>, ()> {
    let output = Command::new("ps")
        .args(["-o", "ppid=", "-p", pid.to_string().as_str()])
        .output()
        .map_err(|_| ())?;

    if !output.status.success() {
        return Err(());
    }

    let trimmed = String::from_utf8_lossy(&output.stdout).trim().to_string();
    if trimmed.is_empty() {
        return Err(());
    }

    trimmed.parse::<u32>().map(Some).map_err(|_| ())
}

#[cfg(windows)]
fn parent_pid(pid: u32) -> Result<Option<u32>, ()> {
    // Use PowerShell + Get-CimInstance (modern replacement for deprecated wmic).
    let script =
        format!("(Get-CimInstance Win32_Process -Filter 'ProcessId={pid}').ParentProcessId");
    let output = Command::new("powershell")
        .args(&["-NoProfile", "-Command", &script])
        .output()
        .map_err(|_| ())?;

    let trimmed = String::from_utf8_lossy(&output.stdout).trim().to_string();
    if trimmed.is_empty() {
        // ParentProcessId is null — this is the root process.
        return Ok(None);
    }

    trimmed
        .parse::<u32>()
        .map(|ppid| Some(ppid))
        .map_err(|_| ())
}

/// Walk the current process's ancestry looking for `expected_pid`.
///
/// Returns `Some(true)` if found, `Some(false)` if the walk reaches the top
/// (no more resolvable parent) without finding it, or `None` if the lookup
/// itself was inconclusive (missing OS tool, unparseable output, etc.) at
/// any point during the walk.  Callers should treat `None` as "assume yes" —
/// this check exists to close a narrow race (an unmanaged `bob` process
/// firing our registered hook), not to become a new source of false
/// negatives on platforms/environments where process introspection is
/// unreliable.
pub(crate) fn is_process_ancestor(expected_pid: u32, max_depth: usize) -> Option<bool> {
    // Check the current process first (covers the case where expected_pid
    // equals our own PID, even when max_depth is 0).
    if std::process::id() == expected_pid {
        return Some(true);
    }
    let mut pid = std::process::id();
    for _ in 0..max_depth {
        match parent_pid(pid) {
            Ok(Some(0)) | Ok(None) => return Some(false), // reached root
            Ok(Some(p)) => {
                if p == expected_pid {
                    return Some(true);
                }
                pid = p;
            }
            Err(()) => return None, // inconclusive: lookup failed
        }
    }
    Some(false) // exhausted max_depth without finding it
}

/*-- top-level orchestration --*/

/// Register the usage-tracking hook in `<workspace>/.bob/settings.json`.
///
/// The capture and lock files are written under the launcher instance's state
/// directory (`GRANITE_CLI_HOME/launcher-state/<launcher_id>/`), NOT inside
/// the workspace.  The marker command carries a `--ancestor-lock` argument
/// (the lockfile path) so the `bob-hook-capture` subcommand can verify at
/// hook-fire time that the invocation is actually a descendant of the
/// registrant process, mitigating the narrow race where an unmanaged `bob`
/// process fires the same registered hook.
///
/// Returns `Err` if another live `granite-cli` process already owns the hook
/// for this workspace (collision). Returns `Ok` on success — the caller must
/// proceed with the launch, then call `unregister` when done.
pub fn register_or_fail(launcher_id: &str, workspace: &Path) -> anyhow::Result<HookRegistration> {
    let cp = capture_path(launcher_id, workspace)?;
    let lp = lock_path(launcher_id, workspace)?;

    // Ensure the launcher state directory exists before writing the lockfile.
    let state_dir = crate::config::Config::launcher_state_dir(launcher_id)
        .with_context(|| "failed to resolve launcher state directory for usage-tracking files")?;
    std::fs::create_dir_all(&state_dir).with_context(|| {
        format!(
            "failed to create launcher state directory `{}`",
            state_dir.display()
        )
    })?;
    let mc = build_marker_command(&cp, &lp)?;

    let mut settings = read_settings(workspace);

    if hooks_session_start_contains(&settings, &mc) {
        // Already registered — check for a live collision.
        let lock_content = std::fs::read_to_string(&lp).unwrap_or_default();
        let pid: u32 = lock_content.trim().parse().unwrap_or(0);
        if pid != 0 && is_pid_alive(pid) {
            anyhow::bail!(
                "Another granite-cli-managed Bob session is already tracking usage in this workspace (pid {pid})."
            );
        }
        // Stale: fall through and reclaim.
        alog_channel!(
            MessageLevel::Warning,
            "Reclaiming a stale usage-tracking hook left by a previous granite-cli process (pid {pid})."
        );
    }

    // Write the marker.
    add_marker(&mut settings, &mc);
    if let Err(e) = write_settings(workspace, &settings) {
        // Best-effort cleanup: try to remove the marker we just added.
        remove_marker_from_file(workspace, &mc);
        return Err(e);
    }

    // Write the PID lockfile.
    let pid = std::process::id();
    if let Err(e) = std::fs::write(&lp, format!("{pid}")) {
        // Best-effort cleanup: try to remove the marker we just added.
        remove_marker_from_file(workspace, &mc);
        return Err(anyhow::Error::from(e));
    }

    Ok(HookRegistration {
        capture_path: cp,
        lock_path: lp,
        marker_command: mc,
    })
}

/// Best-effort: try to remove a marker from the file on disk.
fn remove_marker_from_file(workspace: &Path, marker_command: &str) {
    let mut settings = read_settings(workspace);
    remove_marker(&mut settings, marker_command);
    let _ = write_settings(workspace, &settings);
}

/// Best-effort unregistration: read settings, remove the marker, write back;
/// remove the lockfile.
///
/// Never errors — if the launcher state dir or lock file can't be resolved,
/// just log at debug and return.
pub fn unregister(launcher_id: &str, workspace: &Path, marker_command: &str) {
    let mut settings = read_settings(workspace);
    remove_marker(&mut settings, marker_command);
    let _ = write_settings(workspace, &settings);
    match lock_path(launcher_id, workspace) {
        Ok(lp) => {
            let _ = std::fs::remove_file(&lp);
        }
        Err(e) => {
            alog_channel!(
                MessageLevel::Debug,
                "unregister: could not resolve lock path: {}",
                e
            );
        }
    }
}

/// Try to read the capture file and extract a session_id.
///
/// Returns `Some(session_id)` if the file exists and contains a valid
/// `{"session_id": "<id>"}` object. "hook_event_name" is ignored since it may
/// or may not stay valid due to conflicting field name in documentation.
pub fn try_read_capture(capture_path: &Path) -> Option<String> {
    let content = std::fs::read_to_string(capture_path).ok()?;
    let value: serde_json::Value = serde_json::from_str(&content).ok()?;
    value.get("session_id")?.as_str().map(String::from)
}

/*-- tests --*/

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{Config, TestConfigHome};

    /*-- shell_quote tests --*/
    //
    // `shell_quote`'s escaping convention is itself platform-conditional
    // (single-quote on Unix, double-quote on Windows — see `shell_quote_unix`
    // / `shell_quote_windows`), so these assertions must be gated the same
    // way rather than hardcoding one platform's output and running
    // everywhere.

    #[cfg(unix)]
    #[test]
    fn shell_quote_simple_path_unquoted() {
        // A path without special characters gets wrapped in single quotes.
        assert_eq!(
            shell_quote("/usr/local/bin/granite-cli"),
            "'/usr/local/bin/granite-cli'"
        );
    }

    #[cfg(unix)]
    #[test]
    fn shell_quote_path_with_spaces() {
        // Paths with spaces get quoted (single-quote wrapping doesn't
        // itself protect spaces on Unix, but the quoting convention is
        // applied uniformly — the caller uses the output as-is in sh -c).
        let result = shell_quote("/path/with spaces/granite-cli");
        assert_eq!(result, "'/path/with spaces/granite-cli'");
    }

    #[cfg(unix)]
    #[test]
    fn shell_quote_path_with_embedded_single_quote() {
        // Embedded single quotes are escaped via the '"'"' trick.
        let result = shell_quote("/path/with'quote/granite-cli");
        assert_eq!(result, "'/path/with'\"'\"'quote/granite-cli'");
    }

    #[cfg(unix)]
    #[test]
    fn shell_quote_path_with_multiple_embedded_quotes() {
        let result = shell_quote("/a'b'c");
        assert_eq!(result, "'/a'\"'\"'b'\"'\"'c'");
    }

    #[cfg(windows)]
    #[test]
    fn shell_quote_simple_path_unquoted() {
        // A path without special characters gets wrapped in double quotes.
        assert_eq!(
            shell_quote(r"C:\bin\granite-cli"),
            "\"C:\\bin\\granite-cli\""
        );
    }

    #[cfg(windows)]
    #[test]
    fn shell_quote_path_with_spaces() {
        let result = shell_quote(r"C:\path\with spaces\granite-cli");
        assert_eq!(result, "\"C:\\path\\with spaces\\granite-cli\"");
    }

    #[cfg(windows)]
    #[test]
    fn shell_quote_path_with_embedded_double_quote() {
        // Embedded double quotes are escaped by doubling, per cmd.exe.
        let result = shell_quote(r#"C:\path\with"quote\granite-cli"#);
        assert_eq!(result, "\"C:\\path\\with\"\"quote\\granite-cli\"");
    }

    /*-- build_marker_command tests --*/

    #[test]
    fn build_marker_command_with_exe_format() {
        let exe = Path::new("/usr/local/bin/granite-cli");
        let capture = Path::new("/tmp/ws/.bob/.granite-cli-usage-capture.json");
        let lock = Path::new("/tmp/ws/.bob/.granite-cli-usage.lock");
        let result = build_marker_command_with_exe(exe, capture, lock);
        let quote = if cfg!(windows) { "\"" } else { "'" };
        assert!(result.starts_with(quote));
        assert!(result.contains("internal bob-hook-capture"));
        assert!(result.contains(".granite-cli-usage-capture.json"));
        assert!(result.contains("--ancestor-lock"));
        assert!(result.contains(".granite-cli-usage.lock"));
    }

    #[cfg(unix)]
    #[test]
    fn build_marker_command_with_exe_embedded_quote() {
        let exe = Path::new("/path/with'quote/granite-cli");
        let capture = Path::new("/tmp/ws/.bob/.granite-cli-usage-capture.json");
        let lock = Path::new("/tmp/ws/.bob/.granite-cli-usage.lock");
        let result = build_marker_command_with_exe(exe, capture, lock);
        // The embedded quote should be escaped, not produce broken nesting.
        assert!(result.contains("internal bob-hook-capture"));
        // Verify the '"'"' pattern is present.
        assert!(result.contains("\"'\"'"));
    }

    #[cfg(windows)]
    #[test]
    fn build_marker_command_with_exe_embedded_quote() {
        let exe = Path::new(r#"C:\path\with"quote\granite-cli"#);
        let capture = Path::new(r"C:\ws\.bob\.granite-cli-usage-capture.json");
        let lock = Path::new(r"C:\ws\.bob\.granite-cli-usage.lock");
        let result = build_marker_command_with_exe(exe, capture, lock);
        assert!(result.contains("internal bob-hook-capture"));
        // Embedded double quote should be escaped by doubling.
        assert!(result.contains("with\"\"quote"));
    }

    /*-- read_settings / write_settings tests --*/

    #[test]
    fn read_settings_empty_file_returns_empty_object() {
        let tmp = tempfile::tempdir().unwrap();
        let bob_dir_path = tmp.path().join(".bob");
        std::fs::create_dir_all(&bob_dir_path).unwrap();
        std::fs::write(bob_dir_path.join("settings.json"), "").unwrap();
        let value = read_settings(tmp.path());
        assert!(value.is_object());
        assert!(value.as_object().unwrap().is_empty());
    }

    #[test]
    fn read_settings_missing_file_returns_empty_object() {
        let tmp = tempfile::tempdir().unwrap();
        let value = read_settings(tmp.path());
        assert!(value.is_object());
        assert!(value.as_object().unwrap().is_empty());
    }

    #[test]
    fn read_settings_invalid_json_returns_empty_object() {
        let tmp = tempfile::tempdir().unwrap();
        let bob_dir_path = tmp.path().join(".bob");
        std::fs::create_dir_all(&bob_dir_path).unwrap();
        std::fs::write(bob_dir_path.join("settings.json"), "not json {{{").unwrap();
        let value = read_settings(tmp.path());
        assert!(value.is_object());
        assert!(value.as_object().unwrap().is_empty());
    }

    #[test]
    fn read_settings_valid_json_returns_parsed_value() {
        let tmp = tempfile::tempdir().unwrap();
        let bob_dir_path = tmp.path().join(".bob");
        std::fs::create_dir_all(&bob_dir_path).unwrap();
        let content = serde_json::json!({
            "existingKey": "existingValue",
            "hooks": {"SessionStart": []}
        });
        std::fs::write(bob_dir_path.join("settings.json"), content.to_string()).unwrap();
        let value = read_settings(tmp.path());
        assert_eq!(value["existingKey"], "existingValue");
        assert!(value["hooks"]["SessionStart"].is_array());
    }

    #[test]
    fn write_settings_writes_file_when_dir_exists() {
        let tmp = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(tmp.path().join(".bob")).unwrap();
        let value = serde_json::json!({"key": "value"});
        write_settings(tmp.path(), &value).unwrap();
        let content =
            std::fs::read_to_string(tmp.path().join(".bob").join("settings.json")).unwrap();
        // Pretty-printed JSON should have newlines
        assert!(content.contains('\n'));
        assert!(content.contains("\"key\""));
    }

    /*-- hooks_session_start_contains tests --*/

    #[test]
    fn session_start_contains_empty_hooks_array() {
        let settings = serde_json::json!({"hooks": {"SessionStart": []}});
        assert!(!hooks_session_start_contains(&settings, "anything"));
    }

    #[test]
    fn session_start_contains_matching_command() {
        let settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "my-marker"}]}
                ]
            }
        });
        assert!(hooks_session_start_contains(&settings, "my-marker"));
    }

    #[test]
    fn session_start_contains_non_matching_command() {
        let settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "other-marker"}]}
                ]
            }
        });
        assert!(!hooks_session_start_contains(&settings, "my-marker"));
    }

    #[test]
    fn session_start_contains_missing_hooks_key_returns_false() {
        let settings = serde_json::json!({});
        assert!(!hooks_session_start_contains(&settings, "anything"));
    }

    #[test]
    fn session_start_contains_missing_session_start_returns_false() {
        let settings = serde_json::json!({"hooks": {}});
        assert!(!hooks_session_start_contains(&settings, "anything"));
    }

    #[test]
    fn session_start_contains_multiple_groups_finds_first() {
        let settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "first"}]},
                    {"hooks": [{"type": "command", "command": "second"}]}
                ]
            }
        });
        assert!(hooks_session_start_contains(&settings, "second"));
    }

    #[test]
    fn session_start_contains_deeply_nested_missing_command_field() {
        let settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "script", "script": "echo hi"}]}
                ]
            }
        });
        assert!(!hooks_session_start_contains(&settings, "anything"));
    }

    /*-- add_marker tests --*/

    #[test]
    fn add_marker_to_empty_object_creces_hooks_and_session_start() {
        let mut settings = serde_json::json!({});
        add_marker(&mut settings, "my-marker");
        let hooks = settings["hooks"]["SessionStart"].as_array().unwrap();
        assert_eq!(hooks.len(), 1);
        let hook = &hooks[0]["hooks"][0];
        assert_eq!(hook["type"], "command");
        assert_eq!(hook["command"], "my-marker");
        assert_eq!(hook["timeout"], 5);
    }

    #[test]
    fn add_marker_preserves_unrelated_keys() {
        let mut settings = serde_json::json!({
            "otherKey": "otherValue",
            "hooks": {
                "PreToolUse": [{"hooks": [{"type": "command", "command": "user-hook"}]}]
            }
        });
        add_marker(&mut settings, "my-marker");
        // Unrelated key should still exist.
        assert_eq!(settings["otherKey"], "otherValue");
        // PreToolUse should still exist with its original content.
        assert!(settings["hooks"]["PreToolUse"].is_array());
        assert_eq!(
            settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"],
            "user-hook"
        );
        // SessionStart should have our new marker.
        let ss = settings["hooks"]["SessionStart"].as_array().unwrap();
        assert_eq!(ss.len(), 1);
        assert_eq!(ss[0]["hooks"][0]["command"], "my-marker");
    }

    #[test]
    fn add_marker_appends_to_existing_session_start() {
        let mut settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "existing-marker"}]}
                ]
            }
        });
        add_marker(&mut settings, "my-marker");
        let ss = settings["hooks"]["SessionStart"].as_array().unwrap();
        assert_eq!(ss.len(), 2);
        assert_eq!(ss[0]["hooks"][0]["command"], "existing-marker");
        assert_eq!(ss[1]["hooks"][0]["command"], "my-marker");
    }

    /*-- remove_marker tests --*/

    #[test]
    fn remove_marker_removes_matching_group() {
        let mut settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "my-marker"}]}
                ]
            }
        });
        remove_marker(&mut settings, "my-marker");
        // SessionStart should be empty and removed.
        assert!(
            settings["hooks"]["SessionStart"].is_null()
                || settings["hooks"]["SessionStart"]
                    .as_array()
                    .is_none_or(|a| a.is_empty())
        );
    }

    #[test]
    fn remove_marker_preserves_non_matching_groups() {
        let mut settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "my-marker"}]},
                    {"hooks": [{"type": "command", "command": "keep-me"}]}
                ]
            }
        });
        remove_marker(&mut settings, "my-marker");
        let ss = settings["hooks"]["SessionStart"].as_array().unwrap();
        assert_eq!(ss.len(), 1);
        assert_eq!(ss[0]["hooks"][0]["command"], "keep-me");
    }

    #[test]
    fn remove_marker_preserves_unrelated_keys() {
        let mut settings = serde_json::json!({
            "otherKey": "otherValue",
            "hooks": {
                "PreToolUse": [{"hooks": [{"type": "command", "command": "user-hook"}]}],
                "SessionStart": [
                    {"hooks": [{"type": "command", "command": "my-marker"}]}
                ]
            }
        });
        remove_marker(&mut settings, "my-marker");
        assert_eq!(settings["otherKey"], "otherValue");
        assert!(settings["hooks"]["PreToolUse"].is_array());
        // SessionStart should be gone.
        assert!(
            settings["hooks"]["SessionStart"].is_null()
                || settings["hooks"]["SessionStart"]
                    .as_array()
                    .is_none_or(|a| a.is_empty())
        );
    }

    #[test]
    fn remove_marker_removes_only_matching_hook_within_group() {
        let mut settings = serde_json::json!({
            "hooks": {
                "SessionStart": [
                    {
                        "hooks": [
                            {"type": "command", "command": "my-marker"},
                            {"type": "command", "command": "keep-me"}
                        ]
                    }
                ]
            }
        });
        remove_marker(&mut settings, "my-marker");
        let ss = settings["hooks"]["SessionStart"].as_array().unwrap();
        assert_eq!(ss.len(), 1);
        let hooks = &ss[0]["hooks"];
        assert!(hooks.is_array());
        assert_eq!(hooks.as_array().unwrap().len(), 1);
        assert_eq!(hooks[0]["command"], "keep-me");
    }

    #[test]
    fn remove_marker_on_empty_hooks_is_noop() {
        let mut settings = serde_json::json!({});
        remove_marker(&mut settings, "anything");
        assert_eq!(settings, serde_json::json!({}));
    }

    /*-- full add-remove round-trip --*/

    #[test]
    fn full_roundtrip_empty_settings() {
        let mut settings = serde_json::json!({});
        add_marker(&mut settings, "my-marker");
        assert!(hooks_session_start_contains(&settings, "my-marker"));
        remove_marker(&mut settings, "my-marker");
        assert!(!hooks_session_start_contains(&settings, "my-marker"));
    }

    #[test]
    fn full_roundtrip_preserves_unrelated_content() {
        let mut settings = serde_json::json!({
            "otherKey": "otherValue",
            "hooks": {
                "PreToolUse": [{"hooks": [{"type": "command", "command": "user-hook"}]}]
            }
        });
        add_marker(&mut settings, "my-marker");
        assert_eq!(settings["otherKey"], "otherValue");
        assert_eq!(
            settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"],
            "user-hook"
        );
        remove_marker(&mut settings, "my-marker");
        assert_eq!(settings["otherKey"], "otherValue");
        assert_eq!(
            settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"],
            "user-hook"
        );
        assert!(!hooks_session_start_contains(&settings, "my-marker"));
    }

    /*-- try_read_capture tests --*/

    #[test]
    fn try_read_capture_missing_file_returns_none() {
        assert!(try_read_capture(Path::new("/no/such/file.json")).is_none());
    }

    #[test]
    fn try_read_capture_valid_session_start_returns_session_id() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("capture.json");
        std::fs::write(
            &path,
            r#"{"hook_event_name": "SessionStart", "session_id": "task-123"}"#,
        )
        .unwrap();
        assert_eq!(try_read_capture(&path), Some("task-123".to_string()));
    }

    #[test]
    fn try_read_capture_wrong_event_returns_session_id() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("capture.json");
        std::fs::write(
            &path,
            r#"{"hook_event_name": "PostToolUse", "session_id": "task-123"}"#,
        )
        .unwrap();
        assert_eq!(try_read_capture(&path), Some("task-123".to_string()));
    }

    #[test]
    fn try_read_capture_missing_session_id_returns_none() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("capture.json");
        std::fs::write(&path, r#"{"hook_event_name": "SessionStart"}"#).unwrap();
        assert!(try_read_capture(&path).is_none());
    }

    #[test]
    fn try_read_capture_invalid_json_returns_none() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("capture.json");
        std::fs::write(&path, "not json").unwrap();
        assert!(try_read_capture(&path).is_none());
    }

    #[test]
    fn try_read_capture_non_object_returns_none() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("capture.json");
        std::fs::write(&path, r#"[1, 2, 3]"#).unwrap();
        assert!(try_read_capture(&path).is_none());
    }

    /*-- is_pid_alive tests --*/

    #[test]
    fn is_pid_alive_current_process_is_alive() {
        assert!(is_pid_alive(std::process::id()));
    }

    #[test]
    fn is_pid_alive_unlikely_pid_is_not_alive() {
        // A hardcoded "unlikely" PID (e.g. u32::MAX) is not a safe choice
        // here: `kill`'s pid argument is a signed 32-bit pid_t, so a huge
        // unsigned value like u32::MAX (4294967295) wraps to -1, and
        // `kill(-1, 0)` has special POSIX meaning ("signal every process I
        // have permission to signal") -- which almost always succeeds, even
        // though no literal process "4294967295" exists. This passed on
        // macOS (its `kill` rejects the out-of-range argument outright) but
        // failed on Linux CI (ubuntu-latest), where `kill -0 -1` succeeds.
        // Spawn a real child, wait for it to exit, then check its
        // now-dead-but-known-real PID instead -- deterministic on every
        // platform, no pid_t signedness surprises.
        let mut child = std::process::Command::new(if cfg!(windows) { "cmd" } else { "true" })
            .args(if cfg!(windows) {
                &["/C", "exit", "0"][..]
            } else {
                &[][..]
            })
            .spawn()
            .unwrap();
        let pid = child.id();
        child.wait().unwrap();
        assert!(!is_pid_alive(pid));
    }

    /*-- parent_pid / is_process_ancestor tests --*/

    // Ignored on Windows: `parent_pid`'s Windows branch shells out to
    // `Get-CimInstance Win32_Process` (WMI), which on GitHub's Windows CI
    // runner deterministically fails to find a just-spawned child -- this
    // isn't a timing race (a 2s vs. 20s child lifetime made no difference at
    // all, which rules out a race and points at WMI itself being unreliable
    // for this lookup in that sandboxed/virtualized environment). Needs
    // someone with real Windows access to properly diagnose the Windows
    // implementation before re-enabling; the feature itself degrades
    // gracefully in the meantime (an inconclusive ancestry check just means
    // "assume yes, write anyway" -- see `is_process_ancestor`'s doc comment).
    #[cfg_attr(
        windows,
        ignore = "parent_pid's WMI-based Windows lookup is unreliable on GH's Windows CI runner -- see comment above"
    )]
    #[test]
    fn parent_pid_returns_test_process_as_parent_of_spawned_child() {
        // Spawn a child that blocks on a marker file's absence rather than a
        // fixed sleep duration, so there's no timing guesswork: the child is
        // provably still alive for as long as we need it (until we choose to
        // create the marker), no matter how slow the `parent_pid` lookup
        // itself is.
        let tmp = tempfile::tempdir().unwrap();
        let marker = tmp.path().join("release");
        let marker_q = shell_quote(marker.to_string_lossy().as_ref());

        #[cfg(unix)]
        let mut child = std::process::Command::new("sh")
            .arg("-c")
            .arg(format!("while [ ! -f {marker_q} ]; do sleep 0.05; done"))
            .spawn()
            .expect("failed to spawn polling shell");

        #[cfg(windows)]
        let mut child = std::process::Command::new("powershell")
            .args([
                "-NoProfile",
                "-Command",
                &format!("while (-not (Test-Path {marker_q})) {{ Start-Sleep -Milliseconds 50 }}"),
            ])
            .spawn()
            .expect("failed to spawn polling powershell");

        let child_pid = child.id();

        let result = parent_pid(child_pid);

        // Release the child now that the lookup is done, and reap it so it
        // doesn't linger as a zombie/orphan.
        std::fs::write(&marker, b"go").unwrap();
        let _ = child.wait();

        assert!(
            result.is_ok(),
            "parent_pid lookup for child {child_pid} should succeed"
        );
        assert_eq!(
            result.unwrap(),
            Some(std::process::id()),
            "child's parent must be this test process"
        );
    }

    #[test]
    fn is_process_ancestor_finds_own_pid_in_descendant() {
        // Spawn a child, then verify is_process_ancestor(test_pid, child_pid)
        // returns Some(true) when called from the child process itself.
        #[cfg(unix)]
        let mut child = std::process::Command::new("sh")
            .args(["-c", "echo $$ && sleep 2"])
            .stdout(std::process::Stdio::piped())
            .spawn()
            .expect("failed to spawn child");

        #[cfg(windows)]
        let mut child = std::process::Command::new("cmd")
            .args(&["/c", "echo 0 & timeout /t 2 >nul"])
            .stdout(std::process::Stdio::piped())
            .spawn()
            .expect("failed to spawn child");

        // Wait a moment for the child to fully start
        std::thread::sleep(std::time::Duration::from_millis(200));

        let _child_pid = child.id();

        // We can't easily run code inside the child process, so instead
        // verify that is_process_ancestor returns Some(true) when asked about
        // our own PID from within a descendant.  Since we can't inject code
        // into the child, we take a different approach: verify the walk
        // logic works end-to-end by checking that the child's parent is us
        // (which parent_pid already tested), and that our own PID is trivially
        // an ancestor of itself.
        assert_eq!(
            is_process_ancestor(std::process::id(), 16),
            Some(true),
            "our own PID is trivially an ancestor of ourselves"
        );

        // Verify a very unlikely PID is NOT an ancestor.
        assert_eq!(
            is_process_ancestor(u32::MAX, 16),
            Some(false),
            "an unlikely PID should not be an ancestor"
        );

        // The child_pid is a descendant of our PID — verified indirectly via
        // the parent_pid test above.  For a direct is_process_ancestor test
        // from inside the child we'd need to inject code, which is hard
        // cross-platform.  The combination of parent_pid + own-PID tests
        // covers the logic sufficiently.

        let _ = child.kill();
        let _ = child.wait();
    }

    #[test]
    fn is_process_ancestor_owns_pid_at_depth_zero() {
        // Ancestor check should return Some(true) immediately when
        // expected_pid == current process ID.
        assert_eq!(
            is_process_ancestor(std::process::id(), 0),
            Some(true),
            "max_depth=0 should still check the current process first"
        );
    }

    #[test]
    fn is_process_ancestor_reaches_root_without_finding_unlikely_pid() {
        // A non-existent PID should result in Some(false) after walking to
        // the top of the tree, not a panic or error.
        let result = is_process_ancestor(999999999, 16);
        assert_eq!(result, Some(false));
    }

    /*-- escape_workspace tests --*/

    #[test]
    fn escape_workspace_replaces_slashes_with_delim() {
        let ws = Path::new("/home/user/projects/my-app");
        let escaped = escape_workspace(ws);
        assert_eq!(
            escaped,
            format!(
                "{}---{}---{}---{}---{}",
                "", "home", "user", "projects", "my-app"
            )
        );
    }

    #[test]
    fn escape_workspace_root_path() {
        let ws = Path::new("/");
        let escaped = escape_workspace(ws);
        // "/" becomes "---" (the single slash is replaced)
        assert_eq!(escaped, "---");
    }

    /*-- capture_path / lock_path / register_or_fail / unregister tests --*/

    /// Build a workspace path under the test temp directory so it actually
    /// exists on disk and the test never needs root privileges.
    fn test_workspace() -> PathBuf {
        let home = std::env::var("GRANITE_CLI_HOME").expect("GRANITE_CLI_HOME must be set");
        PathBuf::from(home).join("test-workspace")
    }

    #[test]
    fn capture_path_and_lock_path_resolve_under_launcher_state_dir() {
        let _home = TestConfigHome::new();
        std::fs::create_dir_all(std::env::var("GRANITE_CLI_HOME").unwrap()).unwrap();
        Config::ensure_directories_for_test();

        let workspace = test_workspace();
        let cp = capture_path("test-bob", &workspace).unwrap();
        let lp = lock_path("test-bob", &workspace).unwrap();

        // Both paths must live under launcher-state/test-bob/
        assert!(cp.starts_with(crate::config::Config::launcher_state_dir("test-bob").unwrap()));
        assert!(lp.starts_with(crate::config::Config::launcher_state_dir("test-bob").unwrap()));

        // Filenames must contain the escaped workspace path
        let escaped = escape_workspace(&workspace);
        let cp_name = cp.file_name().unwrap().to_string_lossy();
        let lp_name = lp.file_name().unwrap().to_string_lossy();
        assert!(cp_name.starts_with(&escaped));
        assert!(cp_name.ends_with(".capture.json"));
        assert!(lp_name.starts_with(&escaped));
        assert!(lp_name.ends_with(".lock"));
    }

    #[test]
    fn register_or_fail_creates_state_dir_and_writes_files() {
        let _home = TestConfigHome::new();
        // The temp dir set by TestConfigHome may not exist on disk; create it
        // so ensure_directories_for_test can write under it.
        std::fs::create_dir_all(std::env::var("GRANITE_CLI_HOME").unwrap()).unwrap();
        Config::ensure_directories_for_test();

        let workspace = test_workspace();
        // The workspace path also needs to exist for read_settings/write_settings.
        let bob_dir = Path::new(&workspace).join(".bob");
        std::fs::create_dir_all(&bob_dir).unwrap();

        let reg = register_or_fail("test-bob-reg", &workspace).unwrap();

        // State dir was created
        let state_dir = crate::config::Config::launcher_state_dir("test-bob-reg").unwrap();
        assert!(state_dir.is_dir());

        // Capture file does NOT yet exist (the hook hasn't fired — Bob will
        // write it later).  Only the lockfile should exist right now.
        assert!(reg.lock_path.is_file());
        // Lockfile contains our PID
        let lock_content = std::fs::read_to_string(&reg.lock_path).unwrap();
        assert_eq!(lock_content.trim(), std::process::id().to_string());

        // settings.json under .bob/ has the marker
        let settings = read_settings(&workspace);
        assert!(hooks_session_start_contains(&settings, &reg.marker_command));
    }

    #[test]
    fn unregister_removes_marker_and_lockfile() {
        let _home = TestConfigHome::new();
        std::fs::create_dir_all(std::env::var("GRANITE_CLI_HOME").unwrap()).unwrap();
        Config::ensure_directories_for_test();

        let workspace = test_workspace();
        let bob_dir = Path::new(&workspace).join(".bob");
        std::fs::create_dir_all(&bob_dir).unwrap();

        let reg = register_or_fail("test-bob-unreg", &workspace).unwrap();

        // Marker is in settings
        let settings = read_settings(&workspace);
        assert!(hooks_session_start_contains(&settings, &reg.marker_command));

        // Unregister
        unregister("test-bob-unreg", &workspace, &reg.marker_command);

        // Marker is removed
        let settings = read_settings(&workspace);
        assert!(!hooks_session_start_contains(
            &settings,
            &reg.marker_command
        ));

        // Lockfile is gone
        assert!(!reg.lock_path.exists());
    }

    #[test]
    fn unregister_silently_handles_missing_state_dir() {
        // If launcher_state_dir can't be resolved (e.g. bad GRANITE_CLI_HOME),
        // unregister should still succeed silently (never errors).
        unregister(
            "nonexistent-launcher",
            &PathBuf::from("/some/ws"),
            "some-marker",
        );
    }
}