pi-oxidized 0.1.1

package/crates/pi/src/core/lockfile.rs

@@ -0,0 +1,913 @@
+//! Cross-process exclusive lock using the `proper-lockfile` mkdir protocol.
+//!
+//! Compatibility target: npm `proper-lockfile@4.1.2` as used by coding-agent
+//! settings, trust, and auth storage.
+//!
+//! Protocol:
+//! - lock artifact is the directory ``${target}.lock`` (or an explicit
+//!   `lockfile_path`), created with atomic `create_dir`
+//! - `realpath: false` — the target path is made absolute without requiring
+//!   the target to exist and without resolving symlinks
+//! - contention (`EEXIST` while the lock is still fresh) is the only
+//!   condition that is retried; other I/O errors propagate immediately
+//! - default sync policy matches the coding-agent wrappers: 10 attempts with
+//!   a 20 ms delay between attempts
+//! - default stale threshold is 10 s; while held, this guard refreshes the
+//!   lock directory mtime on an interval of `stale / 2` so a live holder is
+//!   not stolen
+//! - release removes only the directory this guard created, and only while
+//!   that directory is still the same filesystem identity captured at acquire
+//!
+//! Callers that only need a read of a missing file (for example settings load
+//! when no file exists yet) stay lock-free themselves; this module never
+//! invents that policy.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Condvar, Mutex};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant, SystemTime};
+
+use filetime::{FileTime, set_file_mtime};
+use same_file::Handle;
+use thiserror::Error;
+
+/// Default acquisition attempts used by coding-agent settings/trust/auth.
+pub const DEFAULT_ATTEMPTS: u32 = 10;
+
+/// Delay between contention retries in the default sync policy.
+pub const DEFAULT_RETRY_DELAY: Duration = Duration::from_millis(20);
+
+/// Duration after which an un-refreshed lock directory is treated as stale.
+///
+/// Matches `proper-lockfile`'s default `stale` duration of 10 seconds.
+pub const DEFAULT_STALE: Duration = Duration::from_secs(10);
+
+/// Default mtime refresh interval (`stale / 2`) of 5 seconds.
+pub const DEFAULT_UPDATE: Duration = Duration::from_secs(5);
+
+/// Configurable acquisition and ownership policy.
+///
+/// Production callers use [`LockOptions::default`]. Focused tests shorten
+/// `attempts`, `retry_delay`, `stale`, and `update` so they stay within the
+/// 10 × 20 ms production sleep budget without an injectable clock.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LockOptions {
+    /// Maximum create attempts, including the first try. Must be ≥ 1.
+    pub attempts: u32,
+    /// Sleep between contention retries. Skipped when zero.
+    pub retry_delay: Duration,
+    /// Age at which an existing lock directory may be reclaimed.
+    pub stale: Duration,
+    /// Heartbeat interval for refreshing the held lock directory mtime.
+    ///
+    /// When zero, no background refresh is started (the holder can still be
+    /// stolen after `stale` elapses).
+    pub update: Duration,
+    /// Override for the lock directory path.
+    ///
+    /// When `None`, the lock path is ``${absolute_target}.lock``. Trust storage
+    /// passes an explicit sibling such as `trust.json.lock` while locking the
+    /// parent directory.
+    pub lockfile_path: Option<PathBuf>,
+}
+
+impl Default for LockOptions {
+    fn default() -> Self {
+        Self {
+            attempts: DEFAULT_ATTEMPTS,
+            retry_delay: DEFAULT_RETRY_DELAY,
+            stale: DEFAULT_STALE,
+            update: DEFAULT_UPDATE,
+            lockfile_path: None,
+        }
+    }
+}
+
+impl LockOptions {
+    /// Default production policy.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Set the maximum number of create attempts (including the first).
+    #[must_use]
+    pub fn attempts(mut self, attempts: u32) -> Self {
+        self.attempts = attempts.max(1);
+        self
+    }
+
+    /// Set the delay between contention retries.
+    #[must_use]
+    pub fn retry_delay(mut self, retry_delay: Duration) -> Self {
+        self.retry_delay = retry_delay;
+        self
+    }
+
+    /// Set the stale threshold used when reclaiming an abandoned lock.
+    #[must_use]
+    pub fn stale(mut self, stale: Duration) -> Self {
+        self.stale = stale;
+        self
+    }
+
+    /// Set the mtime refresh interval while the lock is held.
+    #[must_use]
+    pub fn update(mut self, update: Duration) -> Self {
+        self.update = update;
+        self
+    }
+
+    /// Override the lock directory path.
+    #[must_use]
+    pub fn lockfile_path(mut self, lockfile_path: impl Into<PathBuf>) -> Self {
+        self.lockfile_path = Some(lockfile_path.into());
+        self
+    }
+}
+
+/// Failure to acquire or release a path lock.
+#[derive(Debug, Error)]
+pub enum LockError {
+    /// Another live holder owns the lock (proper-lockfile `ELOCKED`).
+    #[error("Lock file is already being held")]
+    Contended {
+        /// Path the caller asked to lock.
+        target: PathBuf,
+        /// Lock directory that could not be created.
+        lock_path: PathBuf,
+    },
+    /// Non-contention filesystem failure.
+    #[error("lock I/O failed for {}: {source}", lock_path.display())]
+    Io {
+        /// Path the caller asked to lock.
+        target: PathBuf,
+        /// Lock directory involved in the failure.
+        lock_path: PathBuf,
+        /// Underlying OS error.
+        #[source]
+        source: io::Error,
+    },
+}
+
+impl LockError {
+    /// Returns true when the failure is pure contention.
+    #[must_use]
+    pub const fn is_contended(&self) -> bool {
+        matches!(self, Self::Contended { .. })
+    }
+
+    /// Stable error code matching proper-lockfile (`ELOCKED` / `EIO`).
+    #[must_use]
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::Contended { .. } => "ELOCKED",
+            Self::Io { .. } => "EIO",
+        }
+    }
+}
+
+/// Shared stop signal for the mtime heartbeat: flag + condvar.
+#[derive(Debug)]
+struct StopSignal {
+    stopped: Mutex<bool>,
+    cvar: Condvar,
+}
+
+impl StopSignal {
+    fn new() -> Self {
+        Self {
+            stopped: Mutex::new(false),
+            cvar: Condvar::new(),
+        }
+    }
+
+    /// Mark stopped and wake any waiter.
+    fn stop(&self) {
+        if let Ok(mut guard) = self.stopped.lock() {
+            *guard = true;
+            self.cvar.notify_all();
+        }
+    }
+
+    /// Wait up to `total`, returning `true` when stop was observed.
+    fn wait_timeout(&self, total: Duration) -> bool {
+        let Ok(mut guard) = self.stopped.lock() else {
+            // Poisoned mutex: treat as stopped so the heartbeat exits.
+            return true;
+        };
+        if *guard {
+            return true;
+        }
+        let deadline = Instant::now() + total;
+        loop {
+            if *guard {
+                return true;
+            }
+            let now = Instant::now();
+            if now >= deadline {
+                return false;
+            }
+            let remaining = deadline.saturating_duration_since(now);
+            let Ok((next, wait_result)) = self.cvar.wait_timeout(guard, remaining) else {
+                return true;
+            };
+            guard = next;
+            if *guard {
+                return true;
+            }
+            if wait_result.timed_out() {
+                return false;
+            }
+        }
+    }
+}
+
+/// RAII exclusive lock over a proper-lockfile-compatible lock directory.
+///
+/// Dropping the guard stops the mtime heartbeat (if any) and removes only the
+/// lock directory this guard created, and only while that directory is still
+/// the same filesystem identity captured at acquire time.
+#[derive(Debug)]
+pub struct LockGuard {
+    target: PathBuf,
+    lock_path: PathBuf,
+    /// Filesystem identity of the lock directory created by this guard.
+    identity: Arc<Handle>,
+    stop: Arc<StopSignal>,
+    refresh_thread: Option<JoinHandle<()>>,
+    released: bool,
+}
+
+impl LockGuard {
+    /// Acquire an exclusive lock with the production default policy.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`LockError::Contended`] when another live holder owns the lock
+    /// after the configured retries, or [`LockError::Io`] for non-contention
+    /// filesystem failures (including failure to capture lock identity).
+    pub fn acquire(target: impl AsRef<Path>) -> Result<Self, LockError> {
+        Self::acquire_with(target, &LockOptions::default())
+    }
+
+    /// Acquire an exclusive lock with a custom policy.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`LockError::Contended`] when another live holder owns the lock
+    /// after the configured retries, or [`LockError::Io`] for non-contention
+    /// filesystem failures (including failure to capture lock identity).
+    pub fn acquire_with(
+        target: impl AsRef<Path>,
+        options: &LockOptions,
+    ) -> Result<Self, LockError> {
+        let target_ref = target.as_ref();
+        let target = absolute_path(target_ref);
+        let lock_path = match &options.lockfile_path {
+            Some(custom) => absolute_path(custom),
+            None => default_lock_path(&target),
+        };
+
+        let attempts = options.attempts.max(1);
+        let mut last_contended = false;
+
+        for attempt in 1..=attempts {
+            match try_create_lock(&lock_path, options.stale, true) {
+                Ok(()) => {
+                    let identity = match Handle::from_path(&lock_path) {
+                        Ok(handle) => Arc::new(handle),
+                        Err(source) => {
+                            // Failed to capture identity: tear down the dir we
+                            // just created so we do not leave an orphan lock.
+                            let _ = fs::remove_dir(&lock_path);
+                            return Err(LockError::Io {
+                                target,
+                                lock_path,
+                                source,
+                            });
+                        }
+                    };
+                    return Ok(Self::from_acquired(
+                        target,
+                        lock_path,
+                        identity,
+                        options.update,
+                    ));
+                }
+                Err(OnceError::Contended) => {
+                    last_contended = true;
+                    if attempt == attempts {
+                        break;
+                    }
+                    if !options.retry_delay.is_zero() {
+                        thread::sleep(options.retry_delay);
+                    }
+                }
+                Err(OnceError::Io(source)) => {
+                    return Err(LockError::Io {
+                        target,
+                        lock_path,
+                        source,
+                    });
+                }
+            }
+        }
+
+        if last_contended {
+            Err(LockError::Contended { target, lock_path })
+        } else {
+            Err(LockError::Io {
+                target,
+                lock_path,
+                source: io::Error::other("lock acquisition produced no result"),
+            })
+        }
+    }
+
+    /// Path the caller asked to lock (absolute, unresolved).
+    #[must_use]
+    pub fn target(&self) -> &Path {
+        &self.target
+    }
+
+    /// Lock directory owned by this guard.
+    #[must_use]
+    pub fn lock_path(&self) -> &Path {
+        &self.lock_path
+    }
+
+    /// Explicitly release the lock. Equivalent to dropping the guard.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`LockError::Io`] only when the lock directory is still owned by
+    /// this guard and `remove_dir` fails for a reason other than not found.
+    /// Ownership loss is treated as a successful no-op.
+    pub fn release(mut self) -> Result<(), LockError> {
+        self.release_inner()
+    }
+
+    fn from_acquired(
+        target: PathBuf,
+        lock_path: PathBuf,
+        identity: Arc<Handle>,
+        update: Duration,
+    ) -> Self {
+        let stop = Arc::new(StopSignal::new());
+        let refresh_thread = start_refresh_thread(
+            lock_path.clone(),
+            Arc::clone(&identity),
+            update,
+            Arc::clone(&stop),
+        );
+        Self {
+            target,
+            lock_path,
+            identity,
+            stop,
+            refresh_thread,
+            released: false,
+        }
+    }
+
+    fn release_inner(&mut self) -> Result<(), LockError> {
+        if self.released {
+            return Ok(());
+        }
+        self.released = true;
+        self.stop.stop();
+        if let Some(handle) = self.refresh_thread.take() {
+            // Join so drop does not race a concurrent utime with remove_dir.
+            let _ = handle.join();
+        }
+
+        // Only remove the directory if it is still the same filesystem object
+        // we created. A stale reclaim by another process replaces the path with
+        // a new directory; deleting that would steal the new owner's lock.
+        match still_our_lock(&self.lock_path, &self.identity) {
+            Ok(true) => match fs::remove_dir(&self.lock_path) {
+                Ok(()) => Ok(()),
+                Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
+                Err(source) => Err(LockError::Io {
+                    target: self.target.clone(),
+                    lock_path: self.lock_path.clone(),
+                    source,
+                }),
+            },
+            // Ownership lost or path gone: release is a no-op for the path.
+            Ok(false) | Err(_) => Ok(()),
+        }
+    }
+}
+
+impl Drop for LockGuard {
+    fn drop(&mut self) {
+        let _ = self.release_inner();
+    }
+}
+
+/// Internal outcome of a single create/reclaim attempt.
+enum OnceError {
+    Contended,
+    Io(io::Error),
+}
+
+fn try_create_lock(
+    lock_path: &Path,
+    stale: Duration,
+    allow_stale_reclaim: bool,
+) -> Result<(), OnceError> {
+    match fs::create_dir(lock_path) {
+        Ok(()) => Ok(()),
+        Err(err) if is_already_exists(&err) => {
+            if !allow_stale_reclaim || stale.is_zero() {
+                return Err(OnceError::Contended);
+            }
+            match fs::metadata(lock_path) {
+                Err(meta_err) if meta_err.kind() == io::ErrorKind::NotFound => {
+                    // Lost the race with a releaser; one non-reclaiming retry.
+                    try_create_lock(lock_path, Duration::ZERO, false)
+                }
+                Err(meta_err) => Err(OnceError::Io(meta_err)),
+                Ok(meta) => {
+                    if !is_lock_stale(&meta, stale) {
+                        return Err(OnceError::Contended);
+                    }
+                    match fs::remove_dir(lock_path) {
+                        Ok(()) => {}
+                        Err(remove_err) if remove_err.kind() == io::ErrorKind::NotFound => {}
+                        Err(remove_err) => return Err(OnceError::Io(remove_err)),
+                    }
+                    // After reclaim, never reclaim again in this attempt chain
+                    // (mirrors proper-lockfile's `stale: 0` follow-up).
+                    try_create_lock(lock_path, Duration::ZERO, false)
+                }
+            }
+        }
+        Err(err) => Err(OnceError::Io(err)),
+    }
+}
+
+fn is_already_exists(err: &io::Error) -> bool {
+    err.kind() == io::ErrorKind::AlreadyExists
+}
+
+fn is_lock_stale(meta: &fs::Metadata, stale: Duration) -> bool {
+    let Ok(mtime) = meta.modified() else {
+        // Unreadable mtime: treat as live so we do not steal blindly.
+        return false;
+    };
+    match SystemTime::now().duration_since(mtime) {
+        // proper-lockfile: `mtime.getTime() < Date.now() - stale`
+        Ok(age) => age > stale,
+        // Future mtime → not stale.
+        Err(_) => false,
+    }
+}
+
+fn default_lock_path(target: &Path) -> PathBuf {
+    let mut os = target.as_os_str().to_os_string();
+    os.push(".lock");
+    PathBuf::from(os)
+}
+
+fn absolute_path(path: &Path) -> PathBuf {
+    // `std::path::absolute` does not touch the filesystem and does not resolve
+    // symlinks — the Rust equivalent of Node `path.resolve` with
+    // `realpath: false`.
+    match std::path::absolute(path) {
+        Ok(abs) => abs,
+        Err(_) => {
+            if path.is_absolute() {
+                path.to_path_buf()
+            } else {
+                std::env::current_dir().map_or_else(|_| path.to_path_buf(), |cwd| cwd.join(path))
+            }
+        }
+    }
+}
+
+/// Returns `Ok(true)` when `lock_path` still names the same directory identity.
+fn still_our_lock(lock_path: &Path, identity: &Handle) -> io::Result<bool> {
+    match Handle::from_path(lock_path) {
+        Ok(current) => Ok(current == *identity),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(err),
+    }
+}
+
+fn start_refresh_thread(
+    lock_path: PathBuf,
+    identity: Arc<Handle>,
+    update: Duration,
+    stop: Arc<StopSignal>,
+) -> Option<JoinHandle<()>> {
+    if update.is_zero() {
+        return None;
+    }
+
+    Some(thread::spawn(move || {
+        loop {
+            if stop.wait_timeout(update) {
+                break;
+            }
+            // Refresh only while the path still names our original directory.
+            // A reclaimed/replaced lock must not receive our mtime pulse, and
+            // we must not invent a child marker file that would break rmdir.
+            match still_our_lock(&lock_path, &identity) {
+                Ok(true) => {
+                    let _ = set_file_mtime(&lock_path, FileTime::now());
+                }
+                Ok(false) | Err(_) => break,
+            }
+        }
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::error::Error;
+    use std::sync::mpsc;
+    use std::time::Duration;
+
+    type TestResult = Result<(), Box<dyn Error + Send + Sync>>;
+
+    #[derive(Debug)]
+    struct TestFailure(String);
+
+    impl std::fmt::Display for TestFailure {
+        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            f.write_str(&self.0)
+        }
+    }
+
+    impl Error for TestFailure {}
+
+    fn fail(message: impl Into<String>) -> Box<dyn Error + Send + Sync> {
+        Box::new(TestFailure(message.into()))
+    }
+
+    fn make_temp_dir() -> Result<PathBuf, Box<dyn Error + Send + Sync>> {
+        let nanos = SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos());
+        let base =
+            std::env::temp_dir().join(format!("pi-lockfile-{}-{}", std::process::id(), nanos));
+        fs::create_dir_all(&base)?;
+        Ok(base)
+    }
+
+    fn short_options() -> LockOptions {
+        LockOptions::new()
+            .attempts(3)
+            .retry_delay(Duration::from_millis(5))
+            .stale(Duration::from_millis(40))
+            .update(Duration::from_millis(10))
+    }
+
+    fn require_contended(
+        result: Result<LockGuard, LockError>,
+    ) -> Result<LockError, Box<dyn Error + Send + Sync>> {
+        match result {
+            Ok(_) => Err(fail("expected contention, acquired lock")),
+            Err(err) if err.is_contended() => Ok(err),
+            Err(err) => Err(fail(format!("expected contention, got {err}"))),
+        }
+    }
+
+    fn require_io(
+        result: Result<LockGuard, LockError>,
+    ) -> Result<LockError, Box<dyn Error + Send + Sync>> {
+        match result {
+            Ok(_) => Err(fail("expected I/O error, acquired lock")),
+            Err(err) if !err.is_contended() => Ok(err),
+            Err(err) => Err(fail(format!("expected I/O error, got {err}"))),
+        }
+    }
+
+    #[test]
+    fn acquires_when_target_does_not_exist() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        if target.exists() {
+            return Err(fail("target should not exist before acquire"));
+        }
+
+        let guard = LockGuard::acquire(&target)?;
+        if !guard.lock_path().exists() {
+            return Err(fail("lock directory missing after acquire"));
+        }
+        if !guard.lock_path().is_dir() {
+            return Err(fail("lock path is not a directory"));
+        }
+        let ends_with_lock = guard
+            .lock_path()
+            .file_name()
+            .and_then(|n| n.to_str())
+            .is_some_and(|n| n.ends_with("settings.json.lock"));
+        if !ends_with_lock {
+            return Err(fail("lock path suffix mismatch"));
+        }
+        drop(guard);
+        if default_lock_path(&absolute_path(&target)).exists() {
+            return Err(fail("lock directory remained after drop"));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn release_on_drop_removes_only_owned_lock_dir() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("trust.json");
+        let foreign = dir.join("other.lock");
+        fs::create_dir(&foreign)?;
+
+        {
+            let guard = LockGuard::acquire(&target)?;
+            if !guard.lock_path().exists() {
+                return Err(fail("owned lock missing"));
+            }
+            if !foreign.exists() {
+                return Err(fail("foreign lock missing during hold"));
+            }
+        }
+
+        if default_lock_path(&absolute_path(&target)).exists() {
+            return Err(fail("owned lock remained after drop"));
+        }
+        if !foreign.exists() {
+            return Err(fail("unrelated lock dir must remain"));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn mutual_exclusion_second_holder_is_contended() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let first = LockGuard::acquire(&target)?;
+
+        let target_for_thread = target.clone();
+        let (tx, rx) = mpsc::channel();
+        let handle = thread::spawn(move || {
+            let result = LockGuard::acquire_with(
+                &target_for_thread,
+                &LockOptions::new()
+                    .attempts(2)
+                    .retry_delay(Duration::from_millis(5)),
+            );
+            let is_err = result.is_err();
+            let _ = tx.send(is_err);
+            result
+        });
+
+        let contended = match rx.recv_timeout(Duration::from_millis(200)) {
+            Ok(value) => value,
+            Err(err) => return Err(fail(format!("join signal: {err}"))),
+        };
+        if !contended {
+            return Err(fail("second acquire must fail while first holds"));
+        }
+
+        let Ok(thread_result) = handle.join() else {
+            return Err(fail("second-holder thread panicked"));
+        };
+        let err = require_contended(thread_result)?;
+        if err.code() != "ELOCKED" {
+            return Err(fail(format!("expected ELOCKED, got {}", err.code())));
+        }
+
+        drop(first);
+        let second = LockGuard::acquire(&target)?;
+        drop(second);
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn stale_lock_is_reclaimed() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let lock_path = default_lock_path(&absolute_path(&target));
+        fs::create_dir(&lock_path)?;
+
+        let past = SystemTime::now()
+            .checked_sub(Duration::from_secs(30))
+            .ok_or_else(|| fail("past time underflow"))?;
+        set_file_mtime(&lock_path, FileTime::from_system_time(past))?;
+
+        let guard = LockGuard::acquire_with(
+            &target,
+            &LockOptions::new()
+                .attempts(2)
+                .retry_delay(Duration::ZERO)
+                .stale(Duration::from_millis(50))
+                .update(Duration::from_millis(20)),
+        )?;
+        if !guard.lock_path().exists() {
+            return Err(fail("reclaimed lock missing"));
+        }
+        drop(guard);
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn fresh_foreign_lock_times_out_as_contended() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let lock_path = default_lock_path(&absolute_path(&target));
+        fs::create_dir(&lock_path)?;
+
+        let started = Instant::now();
+        let err = require_contended(LockGuard::acquire_with(
+            &target,
+            &LockOptions::new()
+                .attempts(3)
+                .retry_delay(Duration::from_millis(5))
+                .stale(Duration::from_secs(30))
+                .update(Duration::from_secs(15)),
+        ))?;
+        let elapsed = started.elapsed();
+
+        if err.code() != "ELOCKED" {
+            return Err(fail(format!("expected ELOCKED, got {}", err.code())));
+        }
+        if elapsed > Duration::from_millis(200) {
+            return Err(fail(format!(
+                "retries must stay within 10*20ms production bound, elapsed={elapsed:?}"
+            )));
+        }
+        if !lock_path.exists() {
+            return Err(fail("foreign lock must remain"));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn held_lock_stays_fresh_past_stale_threshold() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let opts = short_options();
+
+        let guard = LockGuard::acquire_with(&target, &opts)?;
+
+        // Wait longer than the stale threshold. Heartbeat refresh at
+        // `update=10ms` must keep mtime fresh so a second process cannot steal.
+        thread::sleep(Duration::from_millis(100));
+
+        let err = require_contended(LockGuard::acquire_with(
+            &target,
+            &LockOptions::new()
+                .attempts(1)
+                .retry_delay(Duration::ZERO)
+                .stale(opts.stale)
+                .update(opts.update),
+        ))?;
+        if !err.is_contended() {
+            return Err(fail("live holder must not be stolen after stale window"));
+        }
+
+        drop(guard);
+        let reacquired = LockGuard::acquire_with(&target, &opts)?;
+        drop(reacquired);
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn unrelated_io_errors_propagate_without_retry_delay() -> TestResult {
+        let dir = make_temp_dir()?;
+        // Parent of the lock directory does not exist → create_dir fails with
+        // NotFound (or equivalent), which is not contention and must not be
+        // retried for hundreds of milliseconds.
+        let target = dir.join("missing").join("nested").join("settings.json");
+        let started = Instant::now();
+        let err = require_io(LockGuard::acquire_with(
+            &target,
+            &LockOptions::new()
+                .attempts(10)
+                .retry_delay(Duration::from_millis(20)),
+        ))?;
+        let elapsed = started.elapsed();
+
+        if err.is_contended() {
+            return Err(fail("non-contention path returned contended"));
+        }
+        if err.code() != "EIO" {
+            return Err(fail(format!("expected EIO, got {}", err.code())));
+        }
+        if elapsed >= Duration::from_millis(50) {
+            return Err(fail(format!(
+                "non-contention errors must not sleep through the retry budget, elapsed={elapsed:?}"
+            )));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn custom_lockfile_path_is_honored() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("store");
+        fs::create_dir_all(&target)?;
+        let custom = dir.join("trust.json.lock");
+
+        let guard =
+            LockGuard::acquire_with(&target, &LockOptions::new().lockfile_path(custom.clone()))?;
+        if guard.lock_path() != absolute_path(&custom).as_path() {
+            return Err(fail("custom lock path not honored"));
+        }
+        if !(custom.exists() || absolute_path(&custom).exists()) {
+            return Err(fail("custom lock directory missing while held"));
+        }
+        drop(guard);
+        if absolute_path(&custom).exists() {
+            return Err(fail("custom lock directory remained after drop"));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn explicit_release_is_idempotent_with_drop() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let guard = LockGuard::acquire(&target)?;
+        let lock_path = guard.lock_path().to_path_buf();
+        guard.release()?;
+        if lock_path.exists() {
+            return Err(fail("lock remained after explicit release"));
+        }
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+
+    #[test]
+    fn replaced_lock_dir_is_neither_refreshed_nor_deleted_by_old_guard() -> TestResult {
+        let dir = make_temp_dir()?;
+        let target = dir.join("settings.json");
+        let lock_path = default_lock_path(&absolute_path(&target));
+
+        // Slow heartbeat so we can replace the dir between ticks and assert
+        // the old guard does not re-touch or delete the replacement.
+        let guard = LockGuard::acquire_with(
+            &target,
+            &LockOptions::new()
+                .attempts(1)
+                .retry_delay(Duration::ZERO)
+                .stale(Duration::from_millis(30))
+                .update(Duration::from_millis(200)),
+        )?;
+
+        let original_identity = Handle::from_path(&lock_path)?;
+
+        // Simulate a stale reclaim: remove the original dir and create a
+        // replacement at the same path owned by a new process.
+        fs::remove_dir(&lock_path)?;
+        fs::create_dir(&lock_path)?;
+        let replacement_identity = Handle::from_path(&lock_path)?;
+        if original_identity == replacement_identity {
+            return Err(fail("replacement must be a distinct filesystem object"));
+        }
+
+        // Age the replacement mtime into the past. If the old heartbeat still
+        // refreshes the path, mtime will jump forward again.
+        let past = SystemTime::now()
+            .checked_sub(Duration::from_mins(1))
+            .ok_or_else(|| fail("past time underflow"))?;
+        set_file_mtime(&lock_path, FileTime::from_system_time(past))?;
+        let aged_mtime = fs::metadata(&lock_path).and_then(|m| m.modified())?;
+
+        // Wait longer than one update interval so a buggy heartbeat would have
+        // fired against the replacement path.
+        thread::sleep(Duration::from_millis(250));
+
+        let after_wait_mtime = fs::metadata(&lock_path).and_then(|m| m.modified())?;
+        if aged_mtime != after_wait_mtime {
+            return Err(fail("old guard must not refresh a replaced lock directory"));
+        }
+        if Handle::from_path(&lock_path)? != replacement_identity {
+            return Err(fail("replacement identity changed during wait"));
+        }
+
+        // Drop must not delete the replacement either.
+        drop(guard);
+        if !lock_path.exists() {
+            return Err(fail("old guard must not remove a replaced lock directory"));
+        }
+        if Handle::from_path(&lock_path)? != replacement_identity {
+            return Err(fail("replacement identity lost after old guard drop"));
+        }
+
+        let _ = fs::remove_dir_all(&dir);
+        Ok(())
+    }
+}