pi-oxidized 0.1.1

package/crates/pi/src/core/tools/mod.rs

@@ -0,0 +1,312 @@
+//! Shared infrastructure and seven concrete coding tools.
+//!
+//! Ports `.references/pi/packages/coding-agent/src/core/tools/`: the ordered
+//! built-in registry, read/bash/edit/write/grep/find/ls implementations,
+//! truncation, rolling-output spill, per-realpath mutation serialization, and
+//! path resolution.
+
+pub mod bash;
+pub mod edit;
+pub mod edit_diff;
+pub mod find;
+pub mod grep;
+pub mod ls;
+pub mod mutation_queue;
+pub mod output_accumulator;
+pub mod path_utils;
+pub mod read;
+pub mod truncate;
+pub mod write;
+
+pub use bash::{
+    BashOperations, BashSpawnContext, BashSpawnHook, BashTool, BashToolDetails, BashToolInput,
+    BashToolOptions, LocalBashOperations, create_bash_tool,
+};
+pub use edit::{
+    EditTool, EditToolDetails, EditToolInput, EditToolOptions, ReplaceEditInput, create_edit_tool,
+};
+pub use find::{FindTool, FindToolDetails, FindToolInput, FindToolOptions, create_find_tool};
+pub use grep::{GrepTool, GrepToolDetails, GrepToolInput, GrepToolOptions, create_grep_tool};
+pub use ls::{LsTool, LsToolDetails, LsToolInput, LsToolOptions, create_ls_tool};
+pub use mutation_queue::{MutationQueueError, with_file_mutation_queue};
+pub use output_accumulator::{
+    DEFAULT_TEMP_FILE_PREFIX, OutputAccumulator, OutputAccumulatorError, OutputAccumulatorOptions,
+    OutputSnapshot,
+};
+pub use path_utils::{
+    PathResolveError, expand_path, path_exists, resolve_read_path, resolve_read_path_async,
+    resolve_to_cwd,
+};
+pub use read::{
+    ReadTool, ReadToolDetails, ReadToolInput, ReadToolOptions, create_read_tool,
+    detect_supported_image_mime_type,
+};
+pub use truncate::{
+    DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, GREP_MAX_LINE_LENGTH, TruncatedBy, TruncatedLine,
+    TruncationOptions, TruncationResult, format_size, truncate_head, truncate_line,
+    truncate_line_with, truncate_tail,
+};
+pub use write::{WriteTool, WriteToolDetails, WriteToolInput, WriteToolOptions, create_write_tool};
+
+use std::path::Path;
+use std::sync::Arc;
+
+use pi_agent::AgentTool;
+use std::error::Error;
+use std::fmt;
+use std::str::FromStr;
+
+use serde::{Deserialize, Serialize};
+
+/// Name of one of the seven built-in coding tools (TypeScript `ToolName`).
+///
+/// Wire form is the lowercase string used in settings and session activation
+/// lists (`"read"`, `"bash"`, …).
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ToolName {
+    /// Read file contents (and images).
+    Read,
+    /// Execute a bash command.
+    Bash,
+    /// Exact multi-edit of a single file.
+    Edit,
+    /// Create or overwrite a file.
+    Write,
+    /// Search file contents (ripgrep).
+    Grep,
+    /// Find files by glob (fd).
+    Find,
+    /// List a directory.
+    Ls,
+}
+
+/// Full registry order (TypeScript `allToolNames` insertion order and
+/// `createAllToolDefinitions` key order): read → bash → edit → write → grep
+/// → find → ls.
+pub const ALL_TOOL_NAMES: [ToolName; 7] = [
+    ToolName::Read,
+    ToolName::Bash,
+    ToolName::Edit,
+    ToolName::Write,
+    ToolName::Grep,
+    ToolName::Find,
+    ToolName::Ls,
+];
+
+/// Default session-active tools (TypeScript `defaultActiveToolNames` /
+/// `createCodingToolDefinitions`): read, bash, edit, write. The full
+/// registry still contains grep/find/ls; they stay inactive until activated.
+pub const DEFAULT_ACTIVE_TOOL_NAMES: [ToolName; 4] = [
+    ToolName::Read,
+    ToolName::Bash,
+    ToolName::Edit,
+    ToolName::Write,
+];
+
+/// Read-only tool set (TypeScript `createReadOnlyToolDefinitions`): read,
+/// grep, find, ls.
+pub const READ_ONLY_TOOL_NAMES: [ToolName; 4] =
+    [ToolName::Read, ToolName::Grep, ToolName::Find, ToolName::Ls];
+
+/// Builds all seven tools in provider-visible registry order.
+#[must_use]
+pub fn create_all_tool_definitions(cwd: impl AsRef<Path>) -> [Arc<dyn AgentTool>; 7] {
+    let cwd = cwd.as_ref();
+    [
+        create_read_tool(cwd),
+        create_bash_tool(cwd),
+        create_edit_tool(cwd),
+        create_write_tool(cwd),
+        create_grep_tool(cwd),
+        create_find_tool(cwd),
+        create_ls_tool(cwd),
+    ]
+}
+
+/// Builds the four tools enabled by default for coding sessions.
+#[must_use]
+pub fn create_coding_tool_definitions(cwd: impl AsRef<Path>) -> [Arc<dyn AgentTool>; 4] {
+    let cwd = cwd.as_ref();
+    [
+        create_read_tool(cwd),
+        create_bash_tool(cwd),
+        create_edit_tool(cwd),
+        create_write_tool(cwd),
+    ]
+}
+
+/// Builds the read-only tool set in registry order.
+#[must_use]
+pub fn create_read_only_tool_definitions(cwd: impl AsRef<Path>) -> [Arc<dyn AgentTool>; 4] {
+    let cwd = cwd.as_ref();
+    [
+        create_read_tool(cwd),
+        create_grep_tool(cwd),
+        create_find_tool(cwd),
+        create_ls_tool(cwd),
+    ]
+}
+
+impl ToolName {
+    /// Lowercase wire name matching the TypeScript discriminant.
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Read => "read",
+            Self::Bash => "bash",
+            Self::Edit => "edit",
+            Self::Write => "write",
+            Self::Grep => "grep",
+            Self::Find => "find",
+            Self::Ls => "ls",
+        }
+    }
+
+    /// Whether this tool is part of the default-active coding set.
+    #[must_use]
+    pub const fn is_default_active(self) -> bool {
+        matches!(self, Self::Read | Self::Bash | Self::Edit | Self::Write)
+    }
+
+    /// Whether this tool is part of the read-only set.
+    #[must_use]
+    pub const fn is_read_only(self) -> bool {
+        matches!(self, Self::Read | Self::Grep | Self::Find | Self::Ls)
+    }
+}
+
+impl fmt::Display for ToolName {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Error returned by [`ToolName`]'s [`FromStr`] implementation. Display text
+/// matches TypeScript `Unknown tool name: ${toolName}` exactly.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UnknownToolName(String);
+
+impl UnknownToolName {
+    /// The unrecognized tool name string.
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for UnknownToolName {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Unknown tool name: {}", self.0)
+    }
+}
+
+impl Error for UnknownToolName {}
+
+impl FromStr for ToolName {
+    type Err = UnknownToolName;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value {
+            "read" => Ok(Self::Read),
+            "bash" => Ok(Self::Bash),
+            "edit" => Ok(Self::Edit),
+            "write" => Ok(Self::Write),
+            "grep" => Ok(Self::Grep),
+            "find" => Ok(Self::Find),
+            "ls" => Ok(Self::Ls),
+            other => Err(UnknownToolName(other.to_owned())),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    type TestResult = Result<(), Box<dyn Error + Send + Sync>>;
+
+    #[test]
+    fn registry_order_is_read_bash_edit_write_grep_find_ls() {
+        assert_eq!(
+            ALL_TOOL_NAMES,
+            [
+                ToolName::Read,
+                ToolName::Bash,
+                ToolName::Edit,
+                ToolName::Write,
+                ToolName::Grep,
+                ToolName::Find,
+                ToolName::Ls,
+            ]
+        );
+        assert_eq!(
+            ALL_TOOL_NAMES.map(ToolName::as_str),
+            ["read", "bash", "edit", "write", "grep", "find", "ls"]
+        );
+    }
+
+    #[test]
+    fn default_active_is_read_bash_edit_write() {
+        assert_eq!(
+            DEFAULT_ACTIVE_TOOL_NAMES,
+            [
+                ToolName::Read,
+                ToolName::Bash,
+                ToolName::Edit,
+                ToolName::Write,
+            ]
+        );
+        for name in ALL_TOOL_NAMES {
+            assert_eq!(
+                name.is_default_active(),
+                DEFAULT_ACTIVE_TOOL_NAMES.contains(&name)
+            );
+        }
+    }
+
+    #[test]
+    fn read_only_is_read_grep_find_ls() {
+        assert_eq!(
+            READ_ONLY_TOOL_NAMES,
+            [ToolName::Read, ToolName::Grep, ToolName::Find, ToolName::Ls,]
+        );
+        for name in ALL_TOOL_NAMES {
+            assert_eq!(name.is_read_only(), READ_ONLY_TOOL_NAMES.contains(&name));
+        }
+    }
+
+    #[test]
+    fn from_str_and_display_roundtrip() -> TestResult {
+        for name in ALL_TOOL_NAMES {
+            let parsed: ToolName = name.as_str().parse()?;
+            assert_eq!(parsed, name);
+            assert_eq!(parsed.to_string(), name.as_str());
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn unknown_tool_name_error_matches_typescript() -> TestResult {
+        let Err(err) = "foo".parse::<ToolName>() else {
+            return Err(std::io::Error::other("foo must not parse as a tool name").into());
+        };
+        assert_eq!(err.to_string(), "Unknown tool name: foo");
+        assert_eq!(err.name(), "foo");
+        Ok(())
+    }
+
+    #[test]
+    fn serde_roundtrip_uses_lowercase_wire_names() -> TestResult {
+        for name in ALL_TOOL_NAMES {
+            let json = serde_json::to_string(&name)?;
+            assert_eq!(json, format!("\"{}\"", name.as_str()));
+            let parsed: ToolName = serde_json::from_str(&json)?;
+            assert_eq!(parsed, name);
+        }
+        // Unknown variants are rejected by serde (settings validation).
+        let bad: Result<ToolName, _> = serde_json::from_str("\"unknown\"");
+        assert!(bad.is_err());
+        Ok(())
+    }
+}

package/crates/pi/src/core/tools/mutation_queue.rs

@@ -0,0 +1,392 @@
+//! Per-realpath serialization for file mutations (edit / write).
+//!
+//! Ports `.references/pi/packages/coding-agent/src/core/tools/file-mutation-queue.ts`.
+//! Operations targeting the same canonical path run FIFO; operations on
+//! distinct paths run concurrently. The queue key is
+//! `realpath(resolve(path))`, falling back to the lexically resolved path
+//! when the target does not yet exist (`ENOENT` / `ENOTDIR`). Map entries
+//! are cleaned up when the last waiter for a key finishes, including on
+//! cancellation via a drop guard.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, LazyLock, Mutex, PoisonError, Weak};
+
+use thiserror::Error;
+use tokio::sync::Semaphore;
+
+use super::path_utils::resolve_lexically_absolute;
+
+/// Errors produced while registering a path into the mutation queue.
+#[derive(Debug, Error)]
+pub enum MutationQueueError {
+    /// Resolving the mutation-queue key for a path failed (working-directory
+    /// lookup, or a `realpath` failure that is not "path missing").
+    #[error("failed to resolve mutation queue key for {path}: {source}")]
+    ResolveKey {
+        /// The path whose key could not be resolved.
+        path: PathBuf,
+        /// Underlying I/O failure.
+        source: std::io::Error,
+    },
+    /// The per-path semaphore was closed. Unreachable in practice: the
+    /// semaphore is never closed by this module.
+    #[error("mutation queue for {path} is unavailable")]
+    QueueUnavailable {
+        /// The path whose queue is unavailable.
+        path: PathBuf,
+    },
+}
+
+/// Global registry of per-key FIFO gates. Entries are held as [`Weak`] so a
+/// finished key can be reclaimed; the live [`Arc`] is owned by each
+/// outstanding waiter.
+static REGISTRY: LazyLock<Mutex<HashMap<PathBuf, Weak<Semaphore>>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+fn lock_registry() -> std::sync::MutexGuard<'static, HashMap<PathBuf, Weak<Semaphore>>> {
+    REGISTRY.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+/// Resolve the queue key for `file_path` (TypeScript `getMutationQueueKey`).
+///
+/// Absolute-ize and lexically normalize first, then `realpath`. Missing
+/// targets (`ENOENT` / `ENOTDIR`) fall back to the resolved path so a
+/// create-on-write and a subsequent edit of the same path share a key.
+async fn mutation_queue_key(file_path: &Path) -> Result<PathBuf, MutationQueueError> {
+    let resolved =
+        resolve_lexically_absolute(file_path).map_err(|source| MutationQueueError::ResolveKey {
+            path: file_path.to_path_buf(),
+            source,
+        })?;
+    match tokio::fs::canonicalize(&resolved).await {
+        Ok(canonical) => Ok(canonical),
+        Err(error)
+            if error.kind() == std::io::ErrorKind::NotFound
+                || error.kind() == std::io::ErrorKind::NotADirectory =>
+        {
+            Ok(resolved)
+        }
+        Err(source) => Err(MutationQueueError::ResolveKey {
+            path: file_path.to_path_buf(),
+            source,
+        }),
+    }
+}
+
+/// Holds one waiter's Arc-cloned gate; on drop, removes the registry entry
+/// when this is the last remaining strong reference.
+struct QueueRegistration {
+    key: PathBuf,
+    gate: Arc<Semaphore>,
+}
+
+impl QueueRegistration {
+    fn register(key: PathBuf) -> Self {
+        let mut map = lock_registry();
+        let gate = if let Some(existing) = map.get(&key).and_then(Weak::upgrade) {
+            existing
+        } else {
+            let gate = Arc::new(Semaphore::new(1));
+            map.insert(key.clone(), Arc::downgrade(&gate));
+            gate
+        };
+        Self { key, gate }
+    }
+}
+
+impl Drop for QueueRegistration {
+    fn drop(&mut self) {
+        let mut map = lock_registry();
+        let own_gate = Arc::downgrade(&self.gate);
+        let maps_to_this_gate = map
+            .get(&self.key)
+            .is_some_and(|mapped| Weak::ptr_eq(mapped, &own_gate));
+
+        // Identity verification, last-reference detection, and removal must
+        // be one registry-locked operation. Otherwise a concurrent registrar
+        // can install a replacement gate between the count check and remove.
+        if maps_to_this_gate && Arc::strong_count(&self.gate) == 1 {
+            map.remove(&self.key);
+        }
+    }
+}
+
+/// Serialize `f` against every other mutation targeting the same realpath.
+/// Distinct keys run in parallel. TypeScript `withFileMutationQueue`.
+///
+/// # Errors
+///
+/// Returns [`MutationQueueError`] when the queue key cannot be resolved or
+/// the (never-closed) semaphore rejects the acquire.
+pub async fn with_file_mutation_queue<T, F, Fut>(
+    file_path: impl AsRef<Path>,
+    f: F,
+) -> Result<T, MutationQueueError>
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = T>,
+{
+    let path = file_path.as_ref();
+    let key = mutation_queue_key(path).await?;
+    // Registration is held for the whole operation so Drop cleans the map
+    // even when the future is cancelled.
+    let registration = QueueRegistration::register(key);
+    let permit = registration
+        .gate
+        .clone()
+        .acquire_owned()
+        .await
+        .map_err(|_| MutationQueueError::QueueUnavailable {
+            path: path.to_path_buf(),
+        })?;
+    // Declaration order: permit drops before registration (reverse of
+    // declaration), releasing the next waiter before the map entry is
+    // considered for cleanup.
+    let result = f().await;
+    drop(permit);
+    Ok(result)
+}
+
+#[cfg(test)]
+fn registry_holds_key(key: &Path) -> bool {
+    lock_registry().get(key).and_then(Weak::upgrade).is_some()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::error::Error;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::time::Duration;
+
+    use tokio::sync::Notify;
+
+    type TestResult = Result<(), Box<dyn Error + Send + Sync>>;
+
+    #[tokio::test]
+    async fn same_key_runs_serially() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let path = dir.path().join("target.txt");
+        std::fs::write(&path, b"seed")?;
+
+        let active = Arc::new(AtomicUsize::new(0));
+        let peak = Arc::new(AtomicUsize::new(0));
+        let completed = Arc::new(Mutex::new(Vec::new()));
+        let mut handles = Vec::new();
+        for index in 0..4 {
+            let path = path.clone();
+            let active = Arc::clone(&active);
+            let peak = Arc::clone(&peak);
+            let completed = Arc::clone(&completed);
+            handles.push(tokio::spawn(async move {
+                with_file_mutation_queue(&path, || async {
+                    let current = active.fetch_add(1, Ordering::SeqCst) + 1;
+                    peak.fetch_max(current, Ordering::SeqCst);
+                    tokio::time::sleep(Duration::from_millis(5)).await;
+                    completed
+                        .lock()
+                        .unwrap_or_else(PoisonError::into_inner)
+                        .push(index);
+                    active.fetch_sub(1, Ordering::SeqCst);
+                })
+                .await
+            }));
+        }
+
+        for handle in handles {
+            handle
+                .await
+                .map_err(|error| std::io::Error::other(error.to_string()))??;
+        }
+        assert_eq!(peak.load(Ordering::SeqCst), 1);
+        let mut recorded = completed
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .clone();
+        recorded.sort_unstable();
+        assert_eq!(recorded, vec![0, 1, 2, 3]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn distinct_keys_run_concurrently() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let path_a = dir.path().join("a.txt");
+        let path_b = dir.path().join("b.txt");
+        std::fs::write(&path_a, b"a")?;
+        std::fs::write(&path_b, b"b")?;
+
+        let a_entered = Arc::new(Notify::new());
+        let b_entered = Arc::new(Notify::new());
+        let a_signal = Arc::clone(&a_entered);
+        let b_wait = Arc::clone(&b_entered);
+        let b_signal = Arc::clone(&b_entered);
+
+        let a = tokio::spawn(async move {
+            with_file_mutation_queue(&path_a, || async {
+                a_signal.notify_one();
+                // Wait for B to enter its critical section. If the two paths
+                // shared a key this would deadlock; the timeout below fails.
+                b_wait.notified().await;
+                "a"
+            })
+            .await
+        });
+        let b = tokio::spawn(async move {
+            // Wait until A holds its permit so the only way B starts is
+            // cross-key parallelism.
+            a_entered.notified().await;
+            with_file_mutation_queue(&path_b, || async {
+                b_signal.notify_one();
+                "b"
+            })
+            .await
+        });
+
+        let a_result = tokio::time::timeout(Duration::from_secs(2), a)
+            .await
+            .map_err(|_| std::io::Error::other("A timed out; keys may be serialized"))?
+            .map_err(|error| std::io::Error::other(error.to_string()))??;
+        let b_result = tokio::time::timeout(Duration::from_secs(2), b)
+            .await
+            .map_err(|_| std::io::Error::other("B timed out; keys may be serialized"))?
+            .map_err(|error| std::io::Error::other(error.to_string()))??;
+        assert_eq!(a_result, "a");
+        assert_eq!(b_result, "b");
+        Ok(())
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn symlink_and_realpath_share_one_key() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let real = dir.path().join("real.txt");
+        let link = dir.path().join("link.txt");
+        std::fs::write(&real, b"seed")?;
+        std::os::unix::fs::symlink(&real, &link)?;
+
+        let order = Arc::new(Mutex::new(Vec::new()));
+        let order_a = Arc::clone(&order);
+        let order_b = Arc::clone(&order);
+
+        // A holds the realpath key via the symlink path; B targets the real
+        // path and must wait for A to finish.
+        let a = tokio::spawn(async move {
+            with_file_mutation_queue(&link, || async {
+                order_a
+                    .lock()
+                    .unwrap_or_else(PoisonError::into_inner)
+                    .push("a-start");
+                tokio::time::sleep(Duration::from_millis(30)).await;
+                order_a
+                    .lock()
+                    .unwrap_or_else(PoisonError::into_inner)
+                    .push("a-end");
+            })
+            .await
+        });
+        // Give A a chance to register and acquire first.
+        tokio::time::sleep(Duration::from_millis(5)).await;
+        let b = tokio::spawn(async move {
+            with_file_mutation_queue(&real, || async {
+                order_b
+                    .lock()
+                    .unwrap_or_else(PoisonError::into_inner)
+                    .push("b-start");
+                order_b
+                    .lock()
+                    .unwrap_or_else(PoisonError::into_inner)
+                    .push("b-end");
+            })
+            .await
+        });
+
+        a.await
+            .map_err(|error| std::io::Error::other(error.to_string()))??;
+        b.await
+            .map_err(|error| std::io::Error::other(error.to_string()))??;
+        let recorded = order.lock().unwrap_or_else(PoisonError::into_inner).clone();
+        assert_eq!(recorded, vec!["a-start", "a-end", "b-start", "b-end"]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn missing_path_uses_resolved_key_and_runs() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let path = dir.path().join("does-not-exist-yet.txt");
+        let result = with_file_mutation_queue(&path, || async { 42 }).await?;
+        assert_eq!(result, 42);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn registry_is_cleaned_after_completion() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let path = dir.path().join("cleanup.txt");
+        std::fs::write(&path, b"seed")?;
+        let key = tokio::fs::canonicalize(&path).await?;
+
+        with_file_mutation_queue(&path, || async {
+            // Entry is live while the operation holds the registration.
+            assert!(registry_holds_key(&key));
+        })
+        .await?;
+        assert!(!registry_holds_key(&key));
+
+        // Two sequential ops leave this key empty each time.
+        with_file_mutation_queue(&path, || async {}).await?;
+        with_file_mutation_queue(&path, || async {}).await?;
+        assert!(!registry_holds_key(&key));
+        Ok(())
+    }
+
+    #[test]
+    fn stale_last_registration_cannot_remove_replacement_gate() -> TestResult {
+        let key = PathBuf::from("replacement-race-key");
+        let stale = QueueRegistration::register(key.clone());
+        let replacement_gate = Arc::new(Semaphore::new(1));
+
+        // Deterministically model the exact race state: a new registrar has
+        // installed a replacement after the stale registration observed
+        // itself as the final strong owner.
+        lock_registry().insert(key.clone(), Arc::downgrade(&replacement_gate));
+        drop(stale);
+
+        let Some(mapped) = lock_registry().get(&key).and_then(Weak::upgrade) else {
+            return Err("stale drop removed the replacement gate".into());
+        };
+        assert!(Arc::ptr_eq(&mapped, &replacement_gate));
+        lock_registry().remove(&key);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn concurrent_ops_on_same_key_leave_registry_empty() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let path = dir.path().join("shared.txt");
+        std::fs::write(&path, b"seed")?;
+        let key = tokio::fs::canonicalize(&path).await?;
+
+        let counter = Arc::new(AtomicUsize::new(0));
+        let mut handles = Vec::new();
+        for _ in 0..8 {
+            let path = path.clone();
+            let counter = Arc::clone(&counter);
+            handles.push(tokio::spawn(async move {
+                with_file_mutation_queue(&path, || async {
+                    counter.fetch_add(1, Ordering::SeqCst);
+                })
+                .await
+            }));
+        }
+        for handle in handles {
+            handle
+                .await
+                .map_err(|error| std::io::Error::other(error.to_string()))??;
+        }
+        assert_eq!(counter.load(Ordering::SeqCst), 8);
+        assert!(!registry_holds_key(&key));
+        Ok(())
+    }
+}