feat(worldline): follow atomic write-then-rename to the final filename

Tools (editors, build systems, Claude Code) write files atomically: write a
`<name>.tmp.<rand>` then `rename()` it over the target. worldline observed only
the temp file's write, so its timeline showed `report.txt.tmp.4f3a…` instead of
`report.txt`.

fspy now surfaces a `Renamed` file event — a new `CallbackKind`/`FileEventKind`
carrying source + destination — by interposing the rename family in the preload
backend (`rename`/`renameat`/`renameat2` on Linux; `rename`/`renameat`/
`renamex_np`/`renameatx_np` on macOS). Rename carries no descriptor, so a
placeholder fd keeps the supervisor's receive path unchanged. worldline relabels
any captured write of the rename source to display its destination (content
stays stored under the original key, so reconstruction is unchanged).

The seccomp (musl) and Windows backends don't surface renames yet, so atomic
writes still show the temp name there.

Verified end-to-end (a re-signed hardened claude under worldline now shows
`report.txt`, not the temp). Adds Unix regression tests at the fspy callback
layer and the worldline layer.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: wan9chi

crates/fspy/src/callback/mod.rs

@@ -20,13 +20,17 @@ use std::{fs::File, mem::ManuallyDrop, path::Path, sync::Arc};
 
 use fspy_shared::ipc::AccessMode;
 
-/// Whether a [`FileEvent`] fires right after an open or right before a close.
+/// What a [`FileEvent`] reports: an open, a close, or a rename.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FileEventKind {
     /// The file has just been opened; the fd/handle is valid.
     Opened,
     /// The file is about to be closed; the fd/handle is still valid.
     Closing,
+    /// A file was just renamed. [`FileEvent::path`] is the source and
+    /// [`FileEvent::to_path`] the destination. No usable descriptor is provided
+    /// ([`FileEvent::fd`] is a placeholder).
+    Renamed,
 }
 
 /// The path carried by a [`FileEvent`].
@@ -132,9 +136,13 @@ pub struct FileEvent<'a> {
     /// seccomp backend, where the target's descriptor is assigned by the kernel
     /// after the open callback runs).
     pub raw_fd: i64,
-    /// Path of the file. Always present for [`FileEventKind::Opened`].
+    /// Path of the file. Always present for [`FileEventKind::Opened`]; for
+    /// [`FileEventKind::Renamed`] it is the rename source.
     pub path: FileEventPath<'a>,
-    /// A file descriptor / handle usable inside the supervisor process.
+    /// Rename destination. `Some` only for [`FileEventKind::Renamed`].
+    pub to_path: Option<&'a Path>,
+    /// A file descriptor / handle usable inside the supervisor process. Not
+    /// meaningful for [`FileEventKind::Renamed`] (rename carries no descriptor).
     pub fd: BorrowedFile<'a>,
 }
 

crates/fspy/src/callback/unix.rs

@@ -108,19 +108,21 @@ struct ParsedRequest {
     mode: fspy_shared::ipc::AccessMode,
     raw_fd: i64,
     path: Option<PathBuf>,
+    to_path: Option<PathBuf>,
 }
 
 impl ParsedRequest {
     fn decode(body: &[u8]) -> io::Result<Self> {
         let request: CallbackRequest<'_> = wincode::deserialize_exact(body)
             .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err.to_string()))?;
-        let kind = if request.kind == CallbackKind::CLOSING {
-            FileEventKind::Closing
-        } else {
-            FileEventKind::Opened
+        let kind = match request.kind {
+            CallbackKind::CLOSING => FileEventKind::Closing,
+            CallbackKind::RENAMED => FileEventKind::Renamed,
+            _ => FileEventKind::Opened,
         };
         let path = request.path.map(|native| PathBuf::from(native.as_os_str()));
-        Ok(Self { kind, pid: request.pid, mode: request.mode, raw_fd: request.fd, path })
+        let to_path = request.to_path.map(|native| PathBuf::from(native.as_os_str()));
+        Ok(Self { kind, pid: request.pid, mode: request.mode, raw_fd: request.fd, path, to_path })
     }
 }
 
@@ -129,7 +131,7 @@ impl ParsedRequest {
 async fn run_callback(callback: Arc<FileCallbackFn>, request: ParsedRequest, owned_fd: OwnedFd) {
     let result = tokio::task::spawn_blocking(move || {
         let path = match request.kind {
-            FileEventKind::Opened => {
+            FileEventKind::Opened | FileEventKind::Renamed => {
                 FileEventPath::Open(request.path.as_deref().unwrap_or_else(|| Path::new("")))
             }
             FileEventKind::Closing => FileEventPath::Close(request.path.as_deref()),
@@ -140,6 +142,7 @@ async fn run_callback(callback: Arc<FileCallbackFn>, request: ParsedRequest, own
             mode: request.mode,
             raw_fd: request.raw_fd,
             path,
+            to_path: request.to_path.as_deref(),
             fd: BorrowedFile::new(owned_fd.as_fd()),
         };
         (*callback)(event);

crates/fspy/src/callback/windows.rs

@@ -178,19 +178,22 @@ struct ParsedRequest {
     mode: fspy_shared::ipc::AccessMode,
     raw_fd: i64,
     path: Option<PathBuf>,
+    to_path: Option<PathBuf>,
 }
 
 impl ParsedRequest {
     fn decode(body: &[u8]) -> io::Result<Self> {
         let request: CallbackRequest<'_> = wincode::deserialize_exact(body)
             .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err.to_string()))?;
-        let kind = if request.kind == CallbackKind::CLOSING {
-            FileEventKind::Closing
-        } else {
-            FileEventKind::Opened
+        let kind = match request.kind {
+            CallbackKind::CLOSING => FileEventKind::Closing,
+            CallbackKind::RENAMED => FileEventKind::Renamed,
+            _ => FileEventKind::Opened,
         };
         let path = request.path.map(|native| PathBuf::from(native.to_cow_os_str().into_owned()));
-        Ok(Self { kind, pid: request.pid, mode: request.mode, raw_fd: request.fd, path })
+        let to_path =
+            request.to_path.map(|native| PathBuf::from(native.to_cow_os_str().into_owned()));
+        Ok(Self { kind, pid: request.pid, mode: request.mode, raw_fd: request.fd, path, to_path })
     }
 }
 
@@ -199,7 +202,7 @@ impl ParsedRequest {
 async fn run_callback(callback: Arc<FileCallbackFn>, request: ParsedRequest, handle: OwnedHandle) {
     let result = tokio::task::spawn_blocking(move || {
         let path = match request.kind {
-            FileEventKind::Opened => {
+            FileEventKind::Opened | FileEventKind::Renamed => {
                 FileEventPath::Open(request.path.as_deref().unwrap_or_else(|| Path::new("")))
             }
             FileEventKind::Closing => FileEventPath::Close(request.path.as_deref()),
@@ -210,6 +213,7 @@ async fn run_callback(callback: Arc<FileCallbackFn>, request: ParsedRequest, han
             mode: request.mode,
             raw_fd: request.raw_fd,
             path,
+            to_path: request.to_path.as_deref(),
             fd: BorrowedFile::new(handle.as_handle()),
         };
         (*callback)(event);

crates/fspy/src/unix/syscall_handler/mod.rs

@@ -170,6 +170,8 @@ pub(super) fn invoke_callback(
         // callback runs, so open/close cannot be paired by fd here.
         raw_fd: -1,
         path,
+        // The seccomp backend reports opens and closes, not renames.
+        to_path: None,
         fd: BorrowedFile::new(fd.as_fd()),
     };
     let invoke: &FileCallbackFn = &*callback.callback;

crates/fspy/tests/file_callback.rs

@@ -292,6 +292,45 @@ async fn close_callback_fires_for_node_write() -> anyhow::Result<()> {
     Ok(())
 }
 
+/// A successful `rename` fires a `Renamed` event carrying both the source and
+/// the destination path. (Unix preload backend; the `rename` interception lives
+/// there — the seccomp and Windows backends don't surface renames.)
+#[cfg(all(unix, not(target_env = "musl")))]
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn rename_event_reports_source_and_destination() -> anyhow::Result<()> {
+    let dir = tempfile::tempdir()?;
+    let dir_path = std::fs::canonicalize(dir.path())?;
+    std::fs::write(dir_path.join("from.txt"), b"x")?;
+
+    let renames: Arc<Mutex<Vec<(PathBuf, PathBuf)>>> = Arc::new(Mutex::new(Vec::new()));
+    let callback = {
+        let (dir_path, renames) = (dir_path.clone(), Arc::clone(&renames));
+        move |event: FileEvent<'_>| {
+            if event.kind == FileEventKind::Renamed
+                && let (Some(from), Some(to)) = (event.path.get(), event.to_path)
+                && from.starts_with(&dir_path)
+            {
+                renames.lock().unwrap().push((from.to_path_buf(), to.to_path_buf()));
+            }
+        }
+    };
+
+    let cmd = command_for_fn!(dir_path.to_str().unwrap().to_owned(), |dir: String| {
+        let dir = std::path::Path::new(&dir);
+        std::fs::rename(dir.join("from.txt"), dir.join("to.txt")).unwrap();
+    });
+    let child = spawn_with_callback(cmd, AccessMode::WRITE, callback).await?;
+    let termination = child.wait_handle.await?;
+    assert!(termination.status.success());
+
+    let renames = renames.lock().unwrap().clone();
+    assert!(
+        renames.iter().any(|(from, to)| from.ends_with("from.txt") && to.ends_with("to.txt")),
+        "expected a rename from.txt -> to.txt, got {renames:?}"
+    );
+    Ok(())
+}
+
 /// The access-mode mask filters which events reach the callback.
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn mask_filters_events() -> anyhow::Result<()> {

crates/fspy_preload_unix/src/client/callback.rs

@@ -9,7 +9,10 @@ use std::{
     cell::Cell,
     ffi::OsStr,
     io::{self, Read as _, Write as _},
-    os::unix::{ffi::OsStrExt as _, net::UnixStream},
+    os::{
+        fd::AsRawFd as _,
+        unix::{ffi::OsStrExt as _, net::UnixStream},
+    },
     path::PathBuf,
 };
 
@@ -109,23 +112,59 @@ impl CallbackChannel {
         let Some(_guard) = ReentryGuard::enter() else {
             return;
         };
-        if let Err(err) = self.round_trip_inner(kind, fd, mode, path) {
+        if let Err(err) = self.send(kind, fd, mode, path, None) {
             eprintln!("fspy: open/close callback round-trip failed: {err}");
         }
     }
 
-    fn round_trip_inner(
+    /// Run a blocking callback round-trip for a successful `rename` (`from` ->
+    /// `to`). Fires under the `WRITE` mask; carries no descriptor.
+    #[expect(
+        clippy::print_stderr,
+        reason = "preload library intentionally uses stderr for error reporting"
+    )]
+    pub fn round_trip_rename(&self, from: &BStr, to: &BStr) {
+        if !AccessMode::WRITE.intersects(self.mask) {
+            return;
+        }
+        if is_ignored_path(from) || is_ignored_path(to) {
+            return;
+        }
+        let Some(_guard) = ReentryGuard::enter() else {
+            return;
+        };
+        if let Err(err) =
+            self.send(CallbackKind::RENAMED, -1, AccessMode::WRITE, Some(from), Some(to))
+        {
+            eprintln!("fspy: rename callback round-trip failed: {err}");
+        }
+    }
+
+    /// Connect, pass a descriptor, send the request, and await the ack. For
+    /// events with no descriptor (`fd < 0`, e.g. rename) the socket's own fd is
+    /// passed as a placeholder so the supervisor's receive path is unchanged.
+    fn send(
         &self,
         kind: CallbackKind,
         fd: c_int,
         mode: AccessMode,
         path: Option<&BStr>,
+        to_path: Option<&BStr>,
     ) -> io::Result<()> {
         let native_path: Option<&NativePath> =
             path.map(|path| <&NativePath>::from(OsStr::from_bytes(path)));
+        let native_to: Option<&NativePath> =
+            to_path.map(|path| <&NativePath>::from(OsStr::from_bytes(path)));
         // SAFETY: `getpid` is always safe to call.
         let pid = u32::try_from(unsafe { libc::getpid() }).unwrap_or(0);
-        let request = CallbackRequest { kind, mode, pid, fd: i64::from(fd), path: native_path };
+        let request = CallbackRequest {
+            kind,
+            mode,
+            pid,
+            fd: i64::from(fd),
+            path: native_path,
+            to_path: native_to,
+        };
 
         let serialized_size = CallbackRequest::serialized_size(&request)
             .map_err(|err| io::Error::other(err.to_string()))?;
@@ -138,7 +177,8 @@ impl CallbackChannel {
         // A fresh connection per event: it is dropped (and closed) while the
         // reentrancy guard is still held, so its own `close` does not recurse.
         let mut socket = UnixStream::connect(&self.socket_path)?;
-        socket.send_fd(fd)?;
+        let passed_fd = if fd >= 0 { fd } else { socket.as_raw_fd() };
+        socket.send_fd(passed_fd)?;
         socket.write_all(&len.to_le_bytes())?;
         socket.write_all(&body)?;
         let mut ack = [0u8; 1];

crates/fspy_preload_unix/src/client/mod.rs

@@ -162,6 +162,28 @@ impl Client {
         };
     }
 
+    /// Run the blocking rename callback round-trip, resolving both endpoints to
+    /// absolute paths first.
+    unsafe fn run_rename_callback(&self, from: impl ToAbsolutePath, to: impl ToAbsolutePath) {
+        let Some(channel) = &self.callback else {
+            return;
+        };
+        // SAFETY: `from`/`to` only read the caller's path arguments / dir fds.
+        let _ = unsafe {
+            from.to_absolute_path(|from_abs| {
+                let Some(from_abs) = from_abs else {
+                    return Ok(());
+                };
+                to.to_absolute_path(|to_abs| {
+                    if let Some(to_abs) = to_abs {
+                        channel.round_trip_rename(from_abs, to_abs);
+                    }
+                    Ok(())
+                })
+            })
+        };
+    }
+
     /// Run the blocking pre-close callback round-trip for a still-valid fd.
     fn run_close_callback(&self, fd: c_int) {
         let Some(channel) = &self.callback else {
@@ -235,6 +257,19 @@ pub unsafe fn handle_open_callback(fd: c_int, path: impl ToAbsolutePath, mode: i
     unsafe { client.run_open_callback(fd, path, mode) };
 }
 
+/// Run the rename callback, if one is registered. Called after a successful
+/// `rename`/`renameat`/… so the destination already holds the file.
+pub unsafe fn handle_rename(from: impl ToAbsolutePath, to: impl ToAbsolutePath) {
+    let Some(client) = global_client() else {
+        return;
+    };
+    if client.callback.is_none() || callback::is_reentrant() {
+        return;
+    }
+    // SAFETY: `from`/`to` carry valid path pointers / dir fds from the caller.
+    unsafe { client.run_rename_callback(from, to) };
+}
+
 /// Run the pre-close blocking callback, if one is registered. Called before
 /// the real `close`/`fclose`, so `fd` is still valid.
 pub fn handle_close(fd: c_int) {

crates/fspy_preload_unix/src/interceptions/mod.rs

@@ -2,6 +2,7 @@ mod access;
 mod close;
 mod dirent;
 mod open;
+mod rename;
 mod spawn;
 mod stat;