Skip to content

The agent that grows with you

43.7 KB
Raw Blame
//! The "update in progress" marker: the Desktop launch gate and the
//! cross-process update lock shared with `hermes_cli/update_lock.py` and the
//! Electron gate (`apps/desktop/electron/update-marker.ts`).
//!
//! Parse, liveness, claim and litter rules are the LP-LOCK round-2 contract
//! that `hermes_cli/update_lock.py` implements identically; keep them in step.

use std::io::Write;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use crate::update::UPDATE_EXIT_CONCURRENT;

/// RAII guard that owns the "update in progress" marker (see
/// `paths::update_in_progress_marker`). Created at the top of `run_update`;
/// its `Drop` releases the claim on EVERY exit path — success, early
/// `return Err`, or a panic that unwinds through `run_update` — so a crashed
/// or aborted updater can never permanently strand the marker and block
/// future desktop launches.
///
/// Marker contract (C1, shared byte-for-byte with `hermes_cli/update_lock.py`
/// and the Electron gate), UTF-8, `\n` line ends, trailing newline:
///
/// ```text
/// <pid>
/// <started_at unix seconds>
/// ct:<owner process creation time, unix seconds, 3 decimals>
/// delegate:<pid> ct:<ct>          (optional; written by `hermes update` / the hand-off scripts)
/// run:<id>                        (optional; the Desktop update run, A7 rule 6)
/// ```
///
/// Every decision-and-mutation (reclaim, adopt, release, rewrite) runs while holding the
/// kernel lock on the never-deleted sidecar `<marker>.lock` (A7 rule 1); only the exclusive
/// first publish is lock-free. `tests/fixtures/update_marker_corpus.json` pins parse, liveness
/// and release byte-for-byte across every implementation.
///
/// Line 3 is absent in legacy (v1) markers. The creation time makes the pid
/// a process IDENTITY, so liveness never has to fall back to an age ceiling
/// (a live v2 owner is live however long it runs) and a recycled pid is not
/// mistaken for the original owner.
///
/// The marker is also the cross-process update lock: `hermes update` claims
/// the same file so a dashboard-spawned update and this updater can't mutate
/// one checkout at the same time. `acquire` therefore publishes its claim
/// exclusively (a fully written tmp file hard-linked onto the path) and
/// REFUSES when a live foreign owner holds it — the pre-fix clobber is what
/// let a dashboard `hermes update` keep running while install-mode bootstrap
/// rewrote the tree underneath it.
pub(crate) struct UpdateMarkerGuard {
    path: PathBuf,
    /// We published or adopted a claim (released per A7 rule 5 on `complete`/`Drop`).
    claimed: bool,
}

/// Why `UpdateMarkerGuard::acquire` did not produce a claim.
pub(crate) enum AcquireError {
    /// A live update (or a claim being published right now: pid 0) holds it.
    Busy(MarkerOwner),
    /// The marker cannot be written at all; the user-facing message.
    Unwritable(String),
}

/// Age ceiling for markers whose owner identity cannot be confirmed: legacy
/// (v1, no `ct:` line) markers, and v2 markers whose live pid's creation
/// time cannot be read. Without a creation time a live pid may be a
/// recycled one, so age is the only bound. Matches the v1 rule in
/// apps/desktop/electron/update-marker.ts and hermes_cli/update_lock.py.
const UPDATE_MARKER_MAX_AGE_SECS: u64 = 20 * 60;

/// Creation-time tolerance when matching a recorded `ct:` against the live
/// process (Linux derives it from whole-second btime plus clock ticks).
const MARKER_CT_TOLERANCE_SECS: f64 = 2.0;

/// A 0-byte marker this young is a claim between its exclusive create and
/// its first write (the non-hard-link fallback): live, never deleted.
const EMPTY_MARKER_GRACE: Duration = Duration::from_secs(5);

/// The pid + age of a confirmed-live update holding the marker. pid 0 is a
/// claim still being written (a fresh 0-byte marker).
pub(crate) struct MarkerOwner {
    pub(crate) pid: u32,
    pub(crate) age_secs: u64,
    /// R6: the marker's owner is dead but the install's checkout lock is still held (a process
    /// that update started is still mutating the checkout), so the marker is kept. pid is 0.
    pub(crate) held: bool,
}

/// Parsed marker body.
struct MarkerRecord {
    pid: u32,
    started_at: u64,
    ct: Option<f64>,
    /// The `ct:` value exactly as written (a rewrite keeps it byte-identical).
    ct_text: Option<String>,
    /// The first well-formed `delegate:<pid> ct:<ct>` line at line 4 or later.
    delegate: Option<(u32, f64)>,
    delegate_ct_text: Option<String>,
    /// Every well-formed `run:<id>` line at line 4 or later (the first is THE run id).
    runs: Vec<String>,
    /// Lines 1-2 plus the `ct:` line when present.
    #[cfg_attr(not(test), allow(dead_code))]
    identity: Vec<String>,
}

impl MarkerRecord {
    /// A7 rule 5 rewrite: `pid` owns the claim from the original `started_at`; run lines kept.
    fn canonical(&self, pid: u32, ct_text: Option<&str>) -> Vec<u8> {
        let mut body = format!("{pid}\n{}\n", self.started_at);
        if let Some(ct) = ct_text {
            body.push_str(&format!("ct:{ct}\n"));
        }
        for run in &self.runs {
            body.push_str(&format!("run:{run}\n"));
        }
        body.into_bytes()
    }
}

fn is_ascii_digits(text: &str) -> bool {
    !text.is_empty() && text.bytes().all(|b| b.is_ascii_digit())
}

/// `[0-9]+(\.[0-9]+)?` as a float; anything else is `None`.
fn parse_ct_value(text: &str) -> Option<f64> {
    let (whole, frac) = match text.split_once('.') {
        Some((whole, frac)) => (whole, Some(frac)),
        None => (text, None),
    };
    if !is_ascii_digits(whole) || frac.is_some_and(|frac| !is_ascii_digits(frac)) {
        return None;
    }
    text.parse().ok()
}

/// `delegate:<pid> ct:<ct>` with exactly one space.
fn parse_delegate(line: &str) -> Option<(u32, f64, &str)> {
    let (pid, ct) = line.strip_prefix("delegate:")?.split_once(' ')?;
    if !is_ascii_digits(pid) {
        return None;
    }
    let ct = ct.strip_prefix("ct:")?;
    Some((pid.parse().ok()?, parse_ct_value(ct)?, ct))
}

/// `run:<[A-Za-z0-9._-]{1,128}>` (A7 rule 6).
fn parse_run(line: &str) -> Option<&str> {
    let id = line.strip_prefix("run:")?;
    let ok = (1..=128).contains(&id.len())
        && id
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'));
    ok.then_some(id)
}

/// Parse a marker body (A2 + A7 rule 7; `tests/fixtures/update_marker_corpus.json`). `None` =
/// malformed (dead): line 1 (a u32 pid) and line 2 must be ASCII digits only after dropping one
/// BOM, one trailing `\r` per line and surrounding spaces/tabs. A line 3 that is not a
/// well-formed `ct:` makes a v1 marker. Lines 4+ are tagged: the first well-formed delegate line
/// and every well-formed run line count; anything else is ignored.
fn parse_marker(raw: &[u8]) -> Option<MarkerRecord> {
    let text = String::from_utf8_lossy(raw);
    let text = text.strip_prefix('\u{feff}').unwrap_or(&text);
    let lines: Vec<&str> = text
        .split('\n')
        .map(|line| {
            line.strip_suffix('\r')
                .unwrap_or(line)
                .trim_matches(|c| c == ' ' || c == '\t')
        })
        .collect();
    let (pid_line, started_line) = (*lines.first()?, *lines.get(1)?);
    if !is_ascii_digits(pid_line) || !is_ascii_digits(started_line) {
        return None;
    }
    let pid = pid_line.parse().ok()?;
    let started_at = started_line.parse().ok()?;
    let ct_line = lines.get(2).copied().unwrap_or("");
    let ct_text = ct_line
        .strip_prefix("ct:")
        .filter(|ct| parse_ct_value(ct).is_some());
    let mut identity = vec![pid_line.to_string(), started_line.to_string()];
    if ct_text.is_some() {
        identity.push(ct_line.to_string());
    }
    let tagged = lines.get(3..).unwrap_or(&[]);
    let delegate = tagged.iter().find_map(|line| parse_delegate(line));
    Some(MarkerRecord {
        pid,
        started_at,
        ct: ct_text.and_then(parse_ct_value),
        ct_text: ct_text.map(str::to_string),
        delegate: delegate.map(|(pid, ct, _)| (pid, ct)),
        delegate_ct_text: delegate.map(|(_, _, text)| text.to_string()),
        runs: tagged
            .iter()
            .filter_map(|line| parse_run(line))
            .map(str::to_string)
            .collect(),
        identity,
    })
}

fn unix_now_secs() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}

/// The process facts a marker verdict depends on: who we are, the clock, and how to probe a pid.
/// Production uses `World::real`; the shared corpus injects its own process table.
struct World<'a> {
    pid: u32,
    /// Our own creation time; `None` only when it cannot be probed.
    ct: Option<f64>,
    now: u64,
    alive: &'a dyn Fn(u32) -> bool,
    ct_of: &'a dyn Fn(u32) -> Option<f64>,
}

impl World<'static> {
    fn real() -> Self {
        let pid = std::process::id();
        World {
            pid,
            ct: process_creation_time(pid),
            now: unix_now_secs(),
            alive: &pid_is_alive,
            ct_of: &process_creation_time,
        }
    }
}

/// Our own pid is our incarnation only within this epsilon (A7 rule 4, R12): the `ct:` we
/// wrote is our exact creation time to 3 decimals, so anything further is a previous process
/// that had our pid — never "close enough".
const OWN_CT_EPSILON_SECS: f64 = 0.005;

/// The process `pid` is alive AND is the process that recorded `recorded_ct` (A1, A7 rule 4).
/// Our own pid must match our creation time exactly; a no-`ct` claim naming our pid is a
/// previous incarnation (dead). Any other pid: only a confirmed creation-time match is
/// unbounded; a v1 record, or a live pid whose creation time cannot be read, is live only while
/// the marker is within the v1 age ceiling.
fn identity_live(pid: u32, recorded_ct: Option<f64>, age_secs: u64, world: &World) -> bool {
    if pid == 0 {
        return false;
    }
    // We are alive by definition: only our incarnation is in question.
    if pid == world.pid {
        return match (recorded_ct, world.ct) {
            (Some(recorded), Some(own)) => (recorded - own).abs() <= OWN_CT_EPSILON_SECS,
            // Degraded: we cannot read our own creation time, so we write v1 claims ourselves.
            (None, None) => true,
            _ => false,
        };
    }
    if !(world.alive)(pid) {
        return false;
    }
    let within_ceiling = age_secs <= UPDATE_MARKER_MAX_AGE_SECS;
    let Some(recorded) = recorded_ct else {
        return within_ceiling;
    };
    match (world.ct_of)(pid) {
        Some(actual) => (recorded - actual).abs() <= MARKER_CT_TOLERANCE_SECS,
        None => within_ceiling,
    }
}

/// The live holder of a parsed marker, if any: the owner (lines 1-3) or, failing that, the
/// delegate, both aged by the marker's `started_at`.
fn marker_live_holder(record: &MarkerRecord, world: &World) -> Option<MarkerOwner> {
    let age_secs = world.now.saturating_sub(record.started_at);
    if identity_live(record.pid, record.ct, age_secs, world) {
        return Some(MarkerOwner {
            pid: record.pid,
            age_secs,
            held: false,
        });
    }
    match record.delegate {
        Some((pid, ct)) if identity_live(pid, Some(ct), age_secs, world) => Some(MarkerOwner {
            pid,
            age_secs,
            held: false,
        }),
        _ => None,
    }
}

/// What releasing our claim does to the marker bytes (A7 rule 5).
#[derive(Debug, PartialEq)]
enum Release {
    Keep,
    Delete,
    Rewrite(Vec<u8>),
}

/// A7 rule 5. The owner (lines 1-3 are our exact incarnation) deletes the marker regardless of
/// delegate lines, unless a LIVE delegate other than us exists: that delegate then inherits the
/// claim (rewritten with it as owner). A delegate (us) drops its line while the owner lives,
/// else deletes. A marker not naming us is kept.
fn release_decision(raw: &[u8], world: &World) -> Release {
    let Some(record) = parse_marker(raw) else {
        return Release::Keep;
    };
    let age_secs = world.now.saturating_sub(record.started_at);
    let owner_live = identity_live(record.pid, record.ct, age_secs, world);
    let delegate_live = record
        .delegate
        .is_some_and(|(pid, ct)| identity_live(pid, Some(ct), age_secs, world));
    let delegate_pid = record.delegate.map(|(pid, _)| pid);
    if record.pid == world.pid && owner_live {
        return match delegate_pid {
            Some(pid) if pid != world.pid && delegate_live => {
                Release::Rewrite(record.canonical(pid, record.delegate_ct_text.as_deref()))
            }
            _ => Release::Delete,
        };
    }
    if delegate_pid == Some(world.pid) && delegate_live {
        return if owner_live {
            Release::Rewrite(record.canonical(record.pid, record.ct_text.as_deref()))
        } else {
            Release::Delete
        };
    }
    Release::Keep
}

/// How long a marker mutation waits for another process's hold on the marker mutex.
const MUTEX_WAIT: Duration = Duration::from_secs(10);

/// `<marker>.lock`: the A7 rule 1 sidecar. Never deleted; holding its kernel lock serializes
/// every marker decision-and-mutation across Python, this updater and the hand-off scripts.
fn marker_mutex_path(path: &Path) -> PathBuf {
    let name = path.file_name().unwrap_or_default().to_string_lossy();
    path.with_file_name(format!("{name}.lock"))
}

/// A held marker mutex; the kernel lock is released when the file closes (also on a crash).
struct MarkerMutex {
    _file: std::fs::File,
}

/// A7 rule 1: hold the sidecar's kernel lock (POSIX `flock`; Windows an exclusive, share-none
/// open — the same lock the PowerShell hand-off takes) for at most `MUTEX_WAIT`.
/// `ErrorKind::WouldBlock` = another process held it the whole time.
fn lock_marker(path: &Path) -> std::io::Result<MarkerMutex> {
    let sidecar = marker_mutex_path(path);
    let deadline = std::time::Instant::now() + MUTEX_WAIT;
    loop {
        if let Some(file) = try_lock_sidecar(&sidecar)? {
            return Ok(MarkerMutex { _file: file });
        }
        if std::time::Instant::now() >= deadline {
            return Err(std::io::Error::new(
                std::io::ErrorKind::WouldBlock,
                "another process holds the update marker mutex",
            ));
        }
        std::thread::sleep(Duration::from_millis(20));
    }
}

#[cfg(unix)]
fn try_lock_sidecar(sidecar: &Path) -> std::io::Result<Option<std::fs::File>> {
    use std::os::unix::io::AsRawFd;

    let file = match std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .open(sidecar)
    {
        Ok(file) => file,
        // flock needs no write access: a sidecar another user created still serializes us.
        Err(err) if err.kind() == std::io::ErrorKind::PermissionDenied => {
            std::fs::OpenOptions::new().read(true).open(sidecar)?
        }
        Err(err) => return Err(err),
    };
    if unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) } == 0 {
        return Ok(Some(file));
    }
    let err = std::io::Error::last_os_error();
    match err.raw_os_error() {
        Some(code) if code == libc::EWOULDBLOCK || code == libc::EINTR => Ok(None),
        _ => Err(err),
    }
}

#[cfg(windows)]
fn try_lock_sidecar(sidecar: &Path) -> std::io::Result<Option<std::fs::File>> {
    use std::os::windows::fs::OpenOptionsExt;
    const ERROR_ACCESS_DENIED: i32 = 5;
    const ERROR_SHARING_VIOLATION: i32 = 32;

    let opened = std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .share_mode(0)
        .open(sidecar);
    let opened = match opened {
        Err(err) if err.raw_os_error() == Some(ERROR_ACCESS_DENIED) => std::fs::OpenOptions::new()
            .read(true)
            .share_mode(0)
            .open(sidecar),
        other => other,
    };
    match opened {
        Ok(file) => Ok(Some(file)),
        Err(err) if err.raw_os_error() == Some(ERROR_SHARING_VIOLATION) => Ok(None),
        Err(err) => Err(err),
    }
}

/// Delete the marker only if its bytes still equal `expected` (the bytes a verdict was reached
/// on). Callers hold the marker mutex; the compare additionally spares a claim a non-locking
/// legacy writer published meanwhile. `Ok(true)` when the file is gone because of us.
fn remove_if_unchanged(path: &Path, expected: &[u8]) -> std::io::Result<bool> {
    match std::fs::read(path) {
        Ok(current) if current == expected => match std::fs::remove_file(path) {
            Ok(()) => Ok(true),
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(false),
            Err(err) => {
                tracing::warn!(?path, %err, "could not remove update marker");
                Err(err)
            }
        },
        _ => Ok(false),
    }
}

fn compare_and_delete(path: &Path, expected: &[u8]) -> bool {
    remove_if_unchanged(path, expected).unwrap_or(false)
}

/// Replace the marker with `body` (tmp + rename) while its bytes are still `expected`.
fn replace_if_unchanged(path: &Path, expected: &[u8], body: &[u8]) -> std::io::Result<bool> {
    let tmp = tmp_sibling(path);
    let swapped = write_new_file(&tmp, body).and_then(|()| {
        if std::fs::read(path)? != expected {
            return Ok(false);
        }
        std::fs::rename(&tmp, path).map(|()| true)
    });
    let _ = std::fs::remove_file(&tmp);
    swapped
}

/// What is on disk at the marker path.
enum MarkerState {
    Absent,
    /// A live holder, or a dead marker kept because its checkout lock is held (`held`, R6).
    Live(MarkerOwner),
    /// Dead / malformed / recycled / past the ceiling, compare-and-deleted.
    /// Carries the error when the marker could not be read or removed (it
    /// is then still on disk).
    Dead(Option<std::io::Error>),
}

/// Read and judge the marker; a dead verdict REMOVES it. The CALLER HOLDS the marker mutex
/// (A7 rule 1), so the verdict and the delete are one critical section: a claim published by a
/// lock-respecting process after our read can no longer be deleted on a stale verdict (R3).
/// A 0-byte marker younger than `EMPTY_MARKER_GRACE` is a claim being written: live as pid 0.
/// R6: a dead marker is never deleted while `install_root`'s checkout lock is held; it is then
/// reported `held` (pid 0) — the update it names exited, but a process it started still runs.
fn inspect_marker_locked(path: &Path, install_root: &Path, world: &World) -> MarkerState {
    let raw = match std::fs::read(path) {
        Ok(raw) => raw,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return MarkerState::Absent,
        // Present but unreadable: no verdict, and nothing we may delete.
        Err(err) => return MarkerState::Dead(Some(err)),
    };
    let live = if raw.is_empty() {
        empty_marker_age(path)
            .filter(|age| *age < EMPTY_MARKER_GRACE)
            .map(|age| MarkerOwner {
                pid: 0,
                age_secs: age.as_secs(),
                held: false,
            })
    } else {
        parse_marker(&raw).and_then(|record| marker_live_holder(&record, world))
    };
    match live {
        Some(owner) => MarkerState::Live(owner),
        None if checkout_lock_held(install_root) => MarkerState::Live(MarkerOwner {
            pid: 0,
            age_secs: parse_marker(&raw)
                .map_or(0, |record| world.now.saturating_sub(record.started_at)),
            held: true,
        }),
        None => MarkerState::Dead(remove_if_unchanged(path, &raw).err()),
    }
}

/// Age of the marker by mtime; a future mtime counts as brand new.
fn empty_marker_age(path: &Path) -> Option<Duration> {
    let modified = std::fs::metadata(path)
        .and_then(|meta| meta.modified())
        .ok()?;
    Some(
        SystemTime::now()
            .duration_since(modified)
            .unwrap_or_default(),
    )
}

/// Read the marker (under its mutex) and report a live holder, if any; a dead marker is
/// removed. Test-only view of `inspect_marker_locked`; the install root is the marker's
/// `hermes-agent` sibling, as in production (`<HERMES_HOME>/hermes-agent`).
#[cfg(test)]
fn live_marker_owner(path: &Path) -> Option<MarkerOwner> {
    let _mutex = lock_marker(path).ok()?;
    let install_root = path.with_file_name("hermes-agent");
    match inspect_marker_locked(path, &install_root, &World::real()) {
        MarkerState::Live(owner) => Some(owner),
        _ => None,
    }
}

/// True when the on-disk marker's owner identity is THIS incarnation (A7 rule 4): our pid AND
/// our creation time, never just a pid a previous process also had.
///
/// Liveness of anything else is deliberately NOT consulted: the exit-2 self-heal below needs
/// exactly one fact — is this our claim — because a `hermes update` child that refuses over
/// OUR claim is a handoff-recognition failure in a stale checkout, not a concurrent update.
fn marker_owned_by_self(path: &Path) -> bool {
    let Some(record) = std::fs::read(path).ok().and_then(|raw| parse_marker(&raw)) else {
        return false;
    };
    let world = World::real();
    record.pid == world.pid && identity_live(record.pid, record.ct, 0, &world)
}

/// The exit-2 heal decision (#75788), extracted so the contract is testable.
///
/// True only when ALL hold: the child exited with the concurrent-update
/// refusal code, the on-disk marker names THIS process, and nothing holds
/// `install_root`'s checkout lock. That combination means the child refused
/// over its own parent's claim — a stale checkout without handoff
/// recognition — so dropping the claim and retrying once is safe. Any other
/// owner (live foreign updater, garbage, missing marker), any other exit
/// code, or a held checkout lock (R6: another update's process is still
/// mutating the install, so the refusal is legitimate) must leave the
/// refusal untouched.
pub(crate) fn should_heal_self_marker_refusal(
    exit_code: Option<i32>,
    marker_path: &Path,
    install_root: &Path,
) -> bool {
    exit_code == Some(UPDATE_EXIT_CONCURRENT)
        && marker_owned_by_self(marker_path)
        && !checkout_lock_held(install_root)
}

/// `hermes_cli/update_lock.py::CHECKOUT_LOCK_NAME` (no checkout) / `GIT_CHECKOUT_LOCK_NAME`.
const CHECKOUT_LOCK_NAME: &str = ".hermes-update.lock";
const GIT_CHECKOUT_LOCK_NAME: &str = "hermes-update.lock";

/// `update_lock.py::_WINDOWS_LOCK_OFFSET`: the byte msvcrt locks, far past the holder record.
#[cfg(windows)]
const WINDOWS_LOCK_OFFSET: u32 = 1 << 20;
/// `update_lock.py::_LEASE_SLOTS`: the lease bytes right after it. A child that joined the lock
/// holds one (R5b) and may outlive its owner, so any held lease reads as a held lock.
#[cfg(windows)]
const LEASE_SLOTS: u32 = 16;

/// `update_lock.py::_git_common_dir`: the repository's common git dir, read from disk. `.git`
/// is the dir itself, or a `gitdir: <path>` file (linked worktree, submodule) whose target may
/// name the shared dir in `commondir`. `None` when `root` is no checkout.
fn git_common_dir(root: &Path) -> Option<PathBuf> {
    let read = |path: &Path| -> Option<String> {
        let text = std::fs::read_to_string(path).ok()?;
        Some(
            text.strip_prefix('\u{feff}')
                .unwrap_or(&text)
                .trim()
                .to_string(),
        )
    };
    let dot = root.join(".git");
    let mut gitdir = if dot.is_dir() {
        dot
    } else if dot.is_file() {
        // An absolute target replaces `root`.
        root.join(read(&dot)?.strip_prefix("gitdir:")?.trim())
    } else {
        return None;
    };
    let common = gitdir.join("commondir");
    if common.is_file() {
        gitdir = gitdir.join(read(&common)?);
    }
    Some(normalize_lexically(&gitdir))
}

/// `os.path.normpath`: drop `.` and fold `..` without touching the filesystem.
fn normalize_lexically(path: &Path) -> PathBuf {
    use std::path::Component;
    let mut out = PathBuf::new();
    for component in path.components() {
        match component {
            Component::CurDir => {}
            Component::ParentDir => match out.components().next_back() {
                Some(Component::Normal(_)) => {
                    out.pop();
                }
                Some(Component::RootDir | Component::Prefix(_)) => {}
                _ => out.push(".."),
            },
            other => out.push(other.as_os_str()),
        }
    }
    out
}

/// `update_lock.py::checkout_lock_path`: the install's checkout kernel lock file.
fn checkout_lock_path(install_root: &Path) -> PathBuf {
    match git_common_dir(install_root) {
        Some(common) => common.join(GIT_CHECKOUT_LOCK_NAME),
        None => install_root.join(CHECKOUT_LOCK_NAME),
    }
}

/// `update_lock.py::checkout_lock_held`: true while some process holds the checkout kernel
/// lock. The probe takes the lock for one try on a fresh open and drops it; a missing file is
/// not held. This updater never takes the checkout lock itself, so it is never the holder.
#[cfg(unix)]
fn checkout_lock_held(install_root: &Path) -> bool {
    use std::os::unix::io::AsRawFd;

    let Ok(file) = std::fs::File::open(checkout_lock_path(install_root)) else {
        return false;
    };
    let fd = file.as_raw_fd();
    if unsafe { libc::flock(fd, libc::LOCK_EX | libc::LOCK_NB) } == 0 {
        unsafe { libc::flock(fd, libc::LOCK_UN) };
        return false;
    }
    std::io::Error::last_os_error().raw_os_error() == Some(libc::EWOULDBLOCK)
}

/// Windows: msvcrt's `LK_NBLCK` is a `LockFile` byte-range lock on one byte at
/// `WINDOWS_LOCK_OFFSET`; `LockFileEx` on the same byte conflicts with it. As in `_try_lock`,
/// a lock that cannot be taken is held, the lease bytes after it included.
#[cfg(windows)]
fn checkout_lock_held(install_root: &Path) -> bool {
    use std::os::windows::fs::OpenOptionsExt;
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Storage::FileSystem::{
        LockFileEx, UnlockFileEx, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE,
        LOCKFILE_EXCLUSIVE_LOCK, LOCKFILE_FAIL_IMMEDIATELY,
    };
    use windows_sys::Win32::System::IO::OVERLAPPED;

    let Ok(file) = std::fs::OpenOptions::new()
        .read(true)
        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
        .open(checkout_lock_path(install_root))
    else {
        return false;
    };
    let handle = file.as_raw_handle();
    let at_offset = || unsafe {
        let mut overlapped: OVERLAPPED = std::mem::zeroed();
        overlapped.Anonymous.Anonymous.Offset = WINDOWS_LOCK_OFFSET;
        overlapped
    };
    unsafe {
        let mut overlapped = at_offset();
        let flags = LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY;
        if LockFileEx(handle, flags, 0, 1 + LEASE_SLOTS, 0, &mut overlapped) == 0 {
            return true;
        }
        let mut overlapped = at_offset();
        UnlockFileEx(handle, 0, 1 + LEASE_SLOTS, 0, &mut overlapped);
    }
    false
}

#[cfg(not(any(unix, windows)))]
fn checkout_lock_held(_install_root: &Path) -> bool {
    false
}

/// Process creation time as unix seconds, comparable with the `ct:` values
/// `hermes_cli/update_lock.py` records. `None` when it cannot be probed.
#[cfg(target_os = "linux")]
fn process_creation_time(pid: u32) -> Option<f64> {
    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
    // Field 22 (starttime, clock ticks since boot). The comm field may hold
    // spaces, so count from the closing paren: the field after it is #3.
    let after_comm = &stat[stat.rfind(')')? + 1..];
    let ticks: f64 = after_comm.split_whitespace().nth(22 - 3)?.parse().ok()?;
    let btime: f64 = std::fs::read_to_string("/proc/stat")
        .ok()?
        .lines()
        .find_map(|line| line.strip_prefix("btime "))?
        .trim()
        .parse()
        .ok()?;
    let clk_tck = unsafe { libc::sysconf(libc::_SC_CLK_TCK) };
    if clk_tck <= 0 {
        return None;
    }
    Some(btime + ticks / clk_tck as f64)
}

#[cfg(target_os = "macos")]
fn process_creation_time(pid: u32) -> Option<f64> {
    // proc_pidinfo(PROC_PIDTBSDINFO) reads the same kernel start time as
    // sysctl kern.proc.pid's kp_proc.p_starttime.
    let mut info: libc::proc_bsdinfo = unsafe { std::mem::zeroed() };
    let size = std::mem::size_of::<libc::proc_bsdinfo>() as libc::c_int;
    let written = unsafe {
        libc::proc_pidinfo(
            pid as libc::c_int,
            libc::PROC_PIDTBSDINFO,
            0,
            &mut info as *mut _ as *mut libc::c_void,
            size,
        )
    };
    if written != size {
        return None;
    }
    Some(info.pbi_start_tvsec as f64 + info.pbi_start_tvusec as f64 / 1_000_000.0)
}

#[cfg(windows)]
fn process_creation_time(pid: u32) -> Option<f64> {
    use windows_sys::Win32::Foundation::{CloseHandle, FILETIME};
    use windows_sys::Win32::System::Threading::{
        GetProcessTimes, OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION,
    };

    const UNIX_EPOCH_AS_FILETIME: u64 = 116_444_736_000_000_000;
    let empty = || FILETIME {
        dwLowDateTime: 0,
        dwHighDateTime: 0,
    };
    let (mut creation, mut exit, mut kernel, mut user) = (empty(), empty(), empty(), empty());
    let ok = unsafe {
        let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
        if handle.is_null() {
            // Access denied included: `pid_is_alive` calls such a pid alive, and an unreadable
            // creation time leaves it only the v1 age ceiling (`identity_live`).
            return None;
        }
        let ok = GetProcessTimes(handle, &mut creation, &mut exit, &mut kernel, &mut user);
        CloseHandle(handle);
        ok
    };
    if ok == 0 {
        return None;
    }
    let ticks = (u64::from(creation.dwHighDateTime) << 32) | u64::from(creation.dwLowDateTime);
    Some(ticks.checked_sub(UNIX_EPOCH_AS_FILETIME)? as f64 / 10_000_000.0)
}

#[cfg(not(any(target_os = "linux", target_os = "macos", windows)))]
fn process_creation_time(_pid: u32) -> Option<f64> {
    None
}

/// `ERROR_ACCESS_DENIED` (winerror.h); spelled out so the decision below is testable off Windows.
#[cfg(any(windows, test))]
const WIN32_ERROR_ACCESS_DENIED: u32 = 5;

/// Liveness verdict when `OpenProcess` on a pid fails with `GetLastError() == err`.
///
/// Access denied means the process EXISTS but belongs to another user or runs elevated: alive,
/// as `hermes_cli/_early_recovery._pid_is_running` decides — racing an elevated updater is worse
/// than postponing. Its creation time is then unreadable too (`process_creation_time` is
/// `None`), so `identity_live` bounds it by the v1 age ceiling, never forever. Any other failure
/// (`ERROR_INVALID_PARAMETER` for a pid that does not exist, ...) is dead.
#[cfg(any(windows, test))]
fn liveness_from_open_error(err: u32) -> bool {
    err == WIN32_ERROR_ACCESS_DENIED
}

/// True when a process with `pid` currently exists.
#[cfg(windows)]
fn pid_is_alive(pid: u32) -> bool {
    use windows_sys::Win32::Foundation::{CloseHandle, GetLastError, WAIT_TIMEOUT};
    use windows_sys::Win32::System::Threading::{
        OpenProcess, WaitForSingleObject, PROCESS_SYNCHRONIZE,
    };

    // pid 0 is the System Idle Process, never an updater (Python: `pid <= 0` is dead).
    if pid == 0 {
        return false;
    }
    unsafe {
        // A process object is signalled once it exits. Never `GetExitCodeProcess ==
        // STILL_ACTIVE`: a process that exited with code 259 reads "running" for as long as
        // any handle keeps its object, and its creation time still matches the v2 marker.
        // Same probe as `hermes_cli/_early_recovery._pid_is_running`.
        let handle = OpenProcess(PROCESS_SYNCHRONIZE, 0, pid);
        if handle.is_null() {
            return liveness_from_open_error(GetLastError());
        }
        let alive = WaitForSingleObject(handle, 0) == WAIT_TIMEOUT;
        CloseHandle(handle);
        alive
    }
}

#[cfg(not(windows))]
fn pid_is_alive(pid: u32) -> bool {
    // Unsigned marker PIDs must remain positive pid_t values: zero/negative
    // kill operands probe process groups (and -1 probes all processes).
    let Ok(pid) = libc::pid_t::try_from(pid) else {
        return false;
    };
    if pid <= 0 {
        return false;
    }
    // signal 0 delivers nothing; it only probes existence/permission.
    // ESRCH => dead. EPERM => alive but owned by another user.
    //
    // kill(pid, 0) alone is not a reliable liveness probe: it also succeeds
    // for a ZOMBIE — a process that has exited but whose parent has not yet
    // reaped it. A crashed updater lingering as a zombie would read as alive
    // and hold a stale marker "live" for the whole age ceiling (#77259). On
    // Linux the process state is directly observable via /proc; fall back to
    // signal 0 when /proc is unavailable (e.g. a container without procfs).
    #[cfg(target_os = "linux")]
    {
        if let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) {
            // Field 3 is the state; the comm field in parens may contain
            // spaces, so anchor on the closing paren instead of splitting.
            if let Some(comm_end) = stat.rfind(')') {
                let state = stat[comm_end + 1..].split_whitespace().next().unwrap_or("");
                if state == "Z" {
                    return false;
                }
            }
        }
    }
    // macOS has no /proc; `ps -o stat=` reports the same state field ('Z' for
    // a zombie). Only consulted after the marker's pid answered signal 0, so
    // the spawn cost is paid exactly when a stale-marker zombie is the
    // question. A failed or empty probe falls through to the signal-0
    // verdict (fail-open, matching the EPERM rule below).
    #[cfg(target_os = "macos")]
    {
        if let Ok(output) = std::process::Command::new("ps")
            .arg("-o")
            .arg("stat=")
            .arg("-p")
            .arg(pid.to_string())
            .output()
        {
            let state = String::from_utf8_lossy(&output.stdout);
            if state.trim_start().starts_with('Z') {
                return false;
            }
        }
    }
    let rc = unsafe { libc::kill(pid, 0) };
    if rc == 0 {
        return true;
    }
    std::io::Error::last_os_error().raw_os_error() == Some(libc::EPERM)
}

/// A unique tmp sibling `<marker name>.<own pid>.<nanos>-<seq>.tmp`. The pid
/// is the first dot component after the marker name so `sweep_tmp_litter`
/// can tell a dead claimant's leftovers from a live one's in-flight file.
fn tmp_sibling(path: &Path) -> PathBuf {
    static SEQ: AtomicU64 = AtomicU64::new(0);
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
    let name = path.file_name().unwrap_or_default().to_string_lossy();
    path.with_file_name(format!("{name}.{}.{nanos}-{seq}.tmp", std::process::id()))
}

/// Exclusively create `path` and write + fsync `body` into it.
fn write_new_file(path: &Path, body: &[u8]) -> std::io::Result<()> {
    let mut file = std::fs::OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(path)?;
    file.write_all(body)?;
    file.sync_all()
}

/// m10: delete `<marker name>.<pid>.tmp` / `<marker name>.<pid>.<any>.tmp`
/// siblings whose `<pid>` is no longer alive — the leftovers of a claimant
/// that died between writing its tmp file and removing it.
fn sweep_tmp_litter(path: &Path) {
    let (Some(dir), Some(name)) = (path.parent(), path.file_name()) else {
        return;
    };
    let prefix = format!("{}.", name.to_string_lossy());
    let Ok(entries) = std::fs::read_dir(dir) else {
        return;
    };
    for entry in entries.flatten() {
        let entry_name = entry.file_name();
        let entry_name = entry_name.to_string_lossy();
        let Some(rest) = entry_name
            .strip_prefix(prefix.as_str())
            .and_then(|rest| rest.strip_suffix(".tmp"))
        else {
            continue;
        };
        let pid = rest.split('.').next().unwrap_or("");
        if !is_ascii_digits(pid) {
            continue;
        }
        let gone = match pid.parse::<u32>() {
            Ok(pid) if pid == std::process::id() => own_pid_tmp_is_stale(&entry),
            Ok(pid) => !pid_is_alive(pid),
            Err(_) => true, // past u32: no process has that pid
        };
        if gone {
            let _ = std::fs::remove_file(entry.path());
        }
    }
}

/// Every tmp write of ours publishes or is removed well inside this: an older
/// tmp under our own pid number is a previous holder's (containers reuse pids
/// every boot), never ours in flight. Mirrors `OWN_PID_TMP_STALE_SECONDS`.
const OWN_PID_TMP_STALE: Duration = Duration::from_secs(60);

fn own_pid_tmp_is_stale(entry: &std::fs::DirEntry) -> bool {
    entry
        .metadata()
        .and_then(|meta| meta.modified())
        .ok()
        .and_then(|modified| modified.elapsed().ok())
        .is_some_and(|age| age > OWN_PID_TMP_STALE)
}

/// Outcome of one claim attempt.
enum Publish {
    Claimed,
    Exists,
}

/// A3: publish `body` at `path` only if nothing is there. The body is fully
/// written and fsynced in a tmp sibling first, then hard-linked onto the
/// path, so a reader never sees a torn claim. A filesystem without hard
/// links falls back to exclusive create + write + fsync (whose brief 0-byte
/// window readers treat as live). `Err` = the marker cannot be written.
fn publish_claim(path: &Path, body: &[u8]) -> std::io::Result<Publish> {
    let tmp = tmp_sibling(path);
    let linked = write_new_file(&tmp, body).and_then(|()| std::fs::hard_link(&tmp, path));
    let _ = std::fs::remove_file(&tmp);
    match linked {
        Ok(()) => return Ok(Publish::Claimed),
        Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => return Ok(Publish::Exists),
        Err(err) => tracing::debug!(?path, %err, "hard-link claim unavailable; using create_new"),
    }
    match write_new_file(path, body) {
        Ok(()) => Ok(Publish::Claimed),
        Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => Ok(Publish::Exists),
        Err(err) => {
            // Remove our torn file only while it still holds a prefix of
            // what we were writing (a reader may already have reaped it and
            // someone else re-claimed the path).
            if let Ok(current) = std::fs::read(path) {
                if body.starts_with(&current) {
                    compare_and_delete(path, &current);
                }
            }
            Err(err)
        }
    }
}

fn unwritable(path: &Path, err: &std::io::Error) -> AcquireError {
    AcquireError::Unwritable(format!(
        "Cannot lock this install for the update: {} is not writable ({err}). \
         Run the update as the user that owns the install.",
        path.display()
    ))
}

impl UpdateMarkerGuard {
    /// Claim the marker, or report why not.
    ///
    /// A7 rule 2: the claim is an exclusive publish (`publish_claim`) with no lock; an existing
    /// marker is never truncated and overwritten. If one exists, the verdict and any mutation
    /// happen under the marker mutex (rule 1): a dead holder (or unparseable bytes — including a
    /// no-`ct` claim naming our own pid, a previous incarnation, rule 4) is removed and the
    /// claim re-published inside the same hold; a live foreign holder is `Busy`; a claim that is
    /// our exact incarnation is adopted.
    ///
    /// R6: a dead marker is NOT removed while `install_root`'s checkout lock is held — a process
    /// the dead update started is still mutating the install — and the refusal is `Busy` with a
    /// `held` owner.
    ///
    /// A marker that cannot be written at all is `Unwritable`: the update
    /// refuses rather than run unserialized against other updaters (m8).
    pub(crate) fn acquire(path: PathBuf, install_root: &Path) -> Result<Self, AcquireError> {
        let world = World::real();
        let mut body = format!("{}\n{}\n", world.pid, world.now);
        if let Some(ct) = world.ct {
            body.push_str(&format!("ct:{ct:.3}\n"));
        }
        if let Some(parent) = path.parent() {
            if let Err(err) = std::fs::create_dir_all(parent) {
                return Err(unwritable(&path, &err));
            }
        }
        sweep_tmp_litter(&path);
        let claimed = |path: PathBuf| Self {
            path,
            claimed: true,
        };
        for _ in 0..3 {
            match publish_claim(&path, body.as_bytes()) {
                Ok(Publish::Claimed) => return Ok(claimed(path)),
                Ok(Publish::Exists) => {}
                Err(err) => {
                    tracing::warn!(?path, %err, "could not create update-in-progress marker");
                    return Err(unwritable(&path, &err));
                }
            }
            let _mutex = match lock_marker(&path) {
                Ok(mutex) => mutex,
                Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {
                    return Err(AcquireError::Busy(MarkerOwner {
                        pid: 0,
                        age_secs: 0,
                        held: false,
                    }))
                }
                Err(err) => return Err(unwritable(&marker_mutex_path(&path), &err)),
            };
            let world = World::real();
            match inspect_marker_locked(&path, install_root, &world) {
                MarkerState::Live(owner) if owner.pid == world.pid => return Ok(claimed(path)),
                MarkerState::Live(owner) => return Err(AcquireError::Busy(owner)),
                MarkerState::Dead(Some(err)) => return Err(unwritable(&path, &err)),
                MarkerState::Absent | MarkerState::Dead(None) => {
                    match publish_claim(&path, body.as_bytes()) {
                        Ok(Publish::Claimed) => return Ok(claimed(path)),
                        // A non-locking exclusive creator won the path: judge it.
                        Ok(Publish::Exists) => {}
                        Err(err) => return Err(unwritable(&path, &err)),
                    }
                }
            }
        }
        // The path kept changing under three attempts: refuse rather than run unserialized.
        tracing::warn!(?path, "update marker changed under three claim attempts");
        Err(AcquireError::Busy(MarkerOwner {
            pid: 0,
            age_secs: 0,
            held: false,
        }))
    }

    /// Release the marker as soon as every mutating stage has completed.
    ///
    /// The updater still owns a Tauri/Cocoa event loop while it relaunches the
    /// desktop, and that loop can outlive `app.exit(0)`. Relying on `Drop`
    /// alone therefore leaves a *successful* update looking active — a live
    /// pid holding a fresh marker — which blocks desktop startup and every
    /// other updater. Idempotent: `Drop` still runs and tolerates an
    /// already-removed (or handed-over) marker.
    ///
    /// A7 rule 5 under the marker mutex (`release_decision`): our claim is removed regardless of
    /// delegate lines, except that a LIVE `hermes update` delegate inherits it (the marker is
    /// rewritten with that delegate as owner) instead of losing it.
    pub(crate) fn complete(&self) {
        if !self.claimed {
            return;
        }
        let _mutex = match lock_marker(&self.path) {
            Ok(mutex) => mutex,
            Err(err) => {
                tracing::warn!(path = ?self.path, %err, "could not lock the update marker to release it");
                return;
            }
        };
        let Ok(raw) = std::fs::read(&self.path) else {
            return;
        };
        match release_decision(&raw, &World::real()) {
            Release::Keep => {}
            Release::Delete => {
                compare_and_delete(&self.path, &raw);
            }
            Release::Rewrite(body) => {
                if let Err(err) = replace_if_unchanged(&self.path, &raw, &body) {
                    tracing::warn!(path = ?self.path, %err, "could not hand the update marker to its delegate");
                }
            }
        }
    }
}

impl Drop for UpdateMarkerGuard {
    fn drop(&mut self) {
        self.complete();
    }
}

#[cfg(test)]
#[path = "marker_tests.rs"]
mod tests;