fix(fspy): replace quiescence locking with crash-tolerant shared-memory publication

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+- **Fixed** `vp run` no longer hangs or fails when a task leaves a process running behind it, such as a dev server or a background helper, or when one of a task's processes is killed. The run finishes as soon as the task itself does, and the files the task used are still recorded ([#544](https://github.com/voidzero-dev/vite-task/issues/544), [#675](https://github.com/voidzero-dev/vite-task/pull/675)).
+- **Fixed** A task that reads or writes an unusually large number of files now runs to the end instead of being killed partway through. Vite+ reports the run as not cached, because it could not record every file the task used ([#533](https://github.com/voidzero-dev/vite-task/issues/533), [#675](https://github.com/voidzero-dev/vite-task/pull/675)).
 - **Fixed** Vite+ diagnostics now display individual paths and working directories without Rust debug formatting such as quoted paths or escaped Windows backslashes ([#534](https://github.com/voidzero-dev/vite-task/pull/534)).
 - **Fixed** Automatic file-access tracking now works inside the default Codex CLI and Claude Code sandboxes ([#562](https://github.com/voidzero-dev/vite-task/issues/562), [#563](https://github.com/voidzero-dev/vite-task/issues/563), [#576](https://github.com/voidzero-dev/vite-task/pull/576), [#569](https://github.com/voidzero-dev/vite-task/pull/569)).
 - **Fixed** Broad workspace globs no longer discover and run package scripts inside `node_modules` ([#539](https://github.com/voidzero-dev/vite-task/pull/539)).

crates/fspy/examples/cli.rs

@@ -27,7 +27,11 @@ async fn main() -> anyhow::Result<()> {
 
     let mut csv_writer = csv_async::AsyncWriter::from_writer(out_file);
 
-    for acc in termination.path_accesses.iter() {
+    for acc in termination
+        .path_accesses
+        .expect("the tracking region holds every record this run makes")
+        .iter()
+    {
         path_count += 1;
         let path_str = format!("{:?}", acc.path);
         let mode_str = format!("{:?}", acc.mode);

crates/fspy/src/error.rs

@@ -30,3 +30,15 @@ pub enum SpawnError {
     #[error("underlying os error: {0}")]
     OsSpawn(std::io::Error),
 }
+
+/// A tracked process could not record a file access it went on to perform,
+/// so the accesses collected for the run are a subset of what it really
+/// touched.
+///
+/// The run itself is unaffected: recording must never stop the program
+/// doing the work. What cannot be done is anything that needs every
+/// access, caching above all, which has to treat the run as untracked
+/// rather than as having touched only the paths that fit.
+#[derive(thiserror::Error, Clone, Copy, PartialEq, Eq, Debug)]
+#[error("the file-access records did not fit in the tracking channel")]
+pub struct TrackingIncomplete;

crates/fspy/src/ipc.rs

@@ -1,10 +1,9 @@
-use std::io;
-
 use fspy_shared::ipc::{
-    PathAccess,
-    channel::{Receiver, ReceiverLockGuard},
+    ChannelSize, PathAccess,
+    channel::{FrameReader, Receiver},
 };
-use tokio::task::spawn_blocking;
+
+use crate::error::TrackingIncomplete;
 
 /// Shared memory for one tracked run's file-access records.
 ///
@@ -18,43 +17,55 @@ const DEFAULT_SHM_CAPACITY: usize = 4 * 1024 * 1024 * 1024;
 /// nothing outside this repository should set it.
 const SHM_CAPACITY_ENV: &str = "VP_RUN_INTERNAL_FSPY_SHM_CAPACITY";
 
-/// How much shared memory to give the next tracked run.
+/// How much shared memory to give the next tracked run, split at one
+/// record per 64 bytes: 8 for its descriptor and 56 for its payload.
+/// Records run a few hundred bytes each, so payload space runs out well
+/// before slots do.
 ///
 /// # Panics
 ///
 /// When the override is set to something that is not a byte count. It is
 /// ours to set, so a value we cannot read is a mistake worth stopping for
 /// rather than quietly ignoring.
-pub fn shm_capacity() -> usize {
-    std::env::var_os(SHM_CAPACITY_ENV).map_or(DEFAULT_SHM_CAPACITY, |value| {
+pub fn shm_size() -> ChannelSize {
+    let capacity = std::env::var_os(SHM_CAPACITY_ENV).map_or(DEFAULT_SHM_CAPACITY, |value| {
         value.to_str().and_then(|value| value.parse().ok()).unwrap_or_else(|| {
             panic!("{SHM_CAPACITY_ENV} is not a byte count: {}", value.display())
         })
-    })
+    });
+    ChannelSize { capacity, slots: capacity / 64 }
 }
 
-#[ouroboros::self_referencing]
-pub struct OwnedReceiverLockGuard {
-    /// Owns the shared memory
-    receiver: Receiver,
-    /// Borrows the shared memory and owns the file lock
-    #[borrows(receiver)]
-    #[covariant]
-    lock_guard: ReceiverLockGuard<'this>,
+/// The path accesses a run reported through the IPC channel.
+pub struct ChannelAccesses {
+    frames: FrameReader,
 }
 
-impl OwnedReceiverLockGuard {
-    pub fn lock(receiver: Receiver) -> io::Result<Self> {
-        Self::try_new(receiver, fspy_shared::ipc::channel::Receiver::lock)
-    }
+impl TryFrom<Receiver> for ChannelAccesses {
+    type Error = TrackingIncomplete;
 
-    pub async fn lock_async(receiver: Receiver) -> io::Result<Self> {
-        spawn_blocking(move || Self::lock(receiver)).await.expect("lock task panicked")
+    /// Closes the channel and takes every record it collected.
+    ///
+    /// Never waits for tracked processes: closing reads one counter and
+    /// shuts the channel's gate (see
+    /// [`fspy_shared::ipc::channel::Receiver::close`]), so it runs inline
+    /// however many records were reported.
+    ///
+    /// # Errors
+    ///
+    /// [`TrackingIncomplete`] when a tracked process could not record
+    /// something it went on to do. What did arrive is then a subset of
+    /// what the run really touched, so none of it is handed back.
+    fn try_from(receiver: Receiver) -> Result<Self, TrackingIncomplete> {
+        Ok(Self { frames: receiver.close().map_err(|_| TrackingIncomplete)? })
     }
+}
 
+impl ChannelAccesses {
     pub fn iter_path_accesses(&self) -> impl Iterator<Item = PathAccess<'_>> {
-        self.borrow_lock_guard()
-            .iter_frames()
-            .map(|frame| wincode::deserialize_exact(frame).unwrap())
+        self.frames.iter().map(|frame| {
+            wincode::deserialize_exact(frame)
+                .expect("committed frames are complete under the channel protocol")
+        })
     }
 }

crates/fspy/src/lib.rs

@@ -20,6 +20,7 @@ mod command;
 use std::{env::temp_dir, fs::create_dir, io, process::ExitStatus, sync::LazyLock};
 
 pub use command::Command;
+pub use error::TrackingIncomplete;
 pub use fspy_shared::ipc::{AccessMode, PathAccess};
 use futures_util::future::BoxFuture;
 pub use os_impl::PathAccessIterable;
@@ -30,8 +31,9 @@ use tokio::process::{ChildStderr, ChildStdin, ChildStdout};
 pub struct ChildTermination {
     /// The exit status of the child process.
     pub status: ExitStatus,
-    /// The path accesses captured from the child process.
-    pub path_accesses: PathAccessIterable,
+    /// The path accesses captured from the child process, or the reason
+    /// they cannot be trusted to be all of them.
+    pub path_accesses: Result<PathAccessIterable, TrackingIncomplete>,
 }
 
 pub struct TrackedChild {

crates/fspy/src/unix/mod.rs

@@ -25,7 +25,7 @@ use tokio::task::spawn_blocking;
 use tokio_util::sync::CancellationToken;
 
 #[cfg(not(target_env = "musl"))]
-use crate::ipc::OwnedReceiverLockGuard;
+use crate::ipc::ChannelAccesses;
 use crate::{ChildTermination, Command, TrackedChild, arena::PathAccessArena, error::SpawnError};
 
 #[derive(Debug)]
@@ -80,7 +80,7 @@ impl SpyImpl {
 
         #[cfg(not(target_env = "musl"))]
         let (ipc_channel_conf, ipc_receiver) =
-            channel(crate::ipc::shm_capacity()).map_err(SpawnError::ChannelCreation)?;
+            channel(crate::ipc::shm_size()).map_err(SpawnError::ChannelCreation)?;
 
         let payload = Payload {
             #[cfg(not(target_env = "musl"))]
@@ -137,7 +137,7 @@ impl SpyImpl {
             stdout: child.stdout.take(),
             stderr: child.stderr.take(),
             // Keep polling for the child to exit in the background even if `wait_handle` is not awaited,
-            // because we need to stop the supervisor and lock the channel as soon as the child exits.
+            // because we need to stop the supervisor and close the channel as soon as the child exits.
             wait_handle: tokio::spawn(async move {
                 let status = tokio::select! {
                     status = child.wait() => status?,
@@ -159,16 +159,14 @@ impl SpyImpl {
                 );
                 let arenas = arenas.collect::<Vec<_>>();
 
-                // Lock the ipc channel after the child has exited.
+                // Close the ipc channel after the child has exited.
                 // We are not interested in path accesses from descendants after the main child has exited.
                 #[cfg(not(target_env = "musl"))]
-                let ipc_receiver_lock_guard =
-                    OwnedReceiverLockGuard::lock_async(ipc_receiver).await?;
-                let path_accesses = PathAccessIterable {
-                    arenas,
-                    #[cfg(not(target_env = "musl"))]
-                    ipc_receiver_lock_guard,
-                };
+                #[cfg(not(target_env = "musl"))]
+                let path_accesses = ChannelAccesses::try_from(ipc_receiver)
+                    .map(|ipc_accesses| PathAccessIterable { arenas, ipc_accesses });
+                #[cfg(target_env = "musl")]
+                let path_accesses = Ok(PathAccessIterable { arenas });
 
                 io::Result::Ok(ChildTermination { status, path_accesses })
             })
@@ -181,7 +179,7 @@ impl SpyImpl {
 pub struct PathAccessIterable {
     arenas: Vec<PathAccessArena>,
     #[cfg(not(target_env = "musl"))]
-    ipc_receiver_lock_guard: OwnedReceiverLockGuard,
+    ipc_accesses: ChannelAccesses,
 }
 
 impl PathAccessIterable {
@@ -191,7 +189,7 @@ impl PathAccessIterable {
 
         #[cfg(not(target_env = "musl"))]
         {
-            let accesses_in_shm = self.ipc_receiver_lock_guard.iter_path_accesses();
+            let accesses_in_shm = self.ipc_accesses.iter_path_accesses();
             accesses_in_shm.chain(accesses_in_arena)
         }
         #[cfg(target_env = "musl")]

crates/fspy/src/windows/mod.rs

@@ -21,20 +21,19 @@ use winapi::{
 use winsafe::co::{CP, WC};
 
 use crate::{
-    ChildTermination, TrackedChild, command::Command, error::SpawnError,
-    ipc::OwnedReceiverLockGuard,
+    ChildTermination, TrackedChild, command::Command, error::SpawnError, ipc::ChannelAccesses,
 };
 
 const INTERPOSE_CDYLIB: Artifact =
     artifact!("fspy_preload", "CARGO_CDYLIB_FILE_FSPY_PRELOAD_WINDOWS");
 
 pub struct PathAccessIterable {
-    ipc_receiver_lock_guard: OwnedReceiverLockGuard,
+    ipc_accesses: ChannelAccesses,
 }
 
 impl PathAccessIterable {
     pub fn iter(&self) -> impl Iterator<Item = PathAccess<'_>> {
-        self.ipc_receiver_lock_guard.iter_path_accesses()
+        self.ipc_accesses.iter_path_accesses()
     }
 }
 
@@ -85,7 +84,7 @@ impl SpyImpl {
         command.creation_flags(CREATE_SUSPENDED);
 
         let (channel_conf, receiver) =
-            channel(crate::ipc::shm_capacity()).map_err(SpawnError::ChannelCreation)?;
+            channel(crate::ipc::shm_size()).map_err(SpawnError::ChannelCreation)?;
 
         let mut spawn_success = false;
         let spawn_success = &mut spawn_success;
@@ -156,7 +155,7 @@ impl SpyImpl {
             stderr: child.stderr.take(),
             process_handle,
             // Keep polling for the child to exit in the background even if `wait_handle` is not awaited,
-            // because we need to stop the supervisor and lock the channel as soon as the child exits.
+            // because we need to stop the supervisor and close the channel as soon as the child exits.
             wait_handle: tokio::spawn(async move {
                 let status = tokio::select! {
                     status = child.wait() => status?,
@@ -165,10 +164,10 @@ impl SpyImpl {
                         child.wait().await?
                     }
                 };
-                // Lock the ipc channel after the child has exited.
+                // Close the ipc channel after the child has exited.
                 // We are not interested in path accesses from descendants after the main child has exited.
-                let ipc_receiver_lock_guard = OwnedReceiverLockGuard::lock_async(receiver).await?;
-                let path_accesses = PathAccessIterable { ipc_receiver_lock_guard };
+                let path_accesses = ChannelAccesses::try_from(receiver)
+                    .map(|ipc_accesses| PathAccessIterable { ipc_accesses });
 
                 io::Result::Ok(ChildTermination { status, path_accesses })
             })

crates/fspy/tests/node_fs.rs

@@ -49,7 +49,9 @@ fn track_script(
         let child = command.spawn(tokio_util::sync::CancellationToken::new()).await?;
         let termination = child.wait_handle.await?;
         assert!(termination.status.success());
-        Ok(termination.path_accesses)
+        Ok(termination
+            .path_accesses
+            .expect("the tracking region holds every record this run makes"))
     })
 }
 

crates/fspy/tests/oxlint.rs

@@ -51,7 +51,7 @@ async fn track_oxlint(dir: &std::path::Path, args: &[&str]) -> anyhow::Result<Pa
     let child = command.spawn(tokio_util::sync::CancellationToken::new()).await?;
     let termination = child.wait_handle.await?;
     // oxlint may return non-zero if it finds lint errors, that's OK
-    Ok(termination.path_accesses)
+    Ok(termination.path_accesses.expect("the test region holds every record"))
 }
 
 #[test(tokio::test)]

crates/fspy/tests/static_executable.rs

@@ -50,7 +50,7 @@ async fn track_test_bin(args: &[&str], cwd: Option<&str>) -> PathAccessIterable
     let termination = tracked_child.wait_handle.await.unwrap();
     assert!(termination.status.success());
 
-    termination.path_accesses
+    termination.path_accesses.expect("the tracking region holds every record this run makes")
 }
 
 #[test(tokio::test)]

crates/fspy/tests/test_utils/mod.rs

@@ -84,5 +84,5 @@ pub async fn spawn_command(cmd: subprocess_test::Command) -> anyhow::Result<Path
         .wait_handle
         .await?;
     assert!(termination.status.success());
-    Ok(termination.path_accesses)
+    Ok(termination.path_accesses.expect("the test region holds every record"))
 }

crates/fspy_benchmark_launcher/src/main.rs

@@ -10,7 +10,7 @@
 
 use std::{env, ffi::OsString, process::Stdio, time::Instant};
 
-use fspy::Command;
+use fspy::{Command, PathAccessIterable};
 use tokio::{io::AsyncReadExt as _, process::ChildStdout, runtime::Builder};
 use tokio_util::sync::CancellationToken;
 
@@ -140,6 +140,30 @@ async fn report(mut launch: Launch) {
 /// In relative mode the captured path must come out identical — the tracker
 /// resolves the root working directory and joins the bare name back into
 /// [`MISSING_PATH`] — so the assertion below covers both modes.
+/// Takes the accesses out of a [`fspy::ChildTermination`], whichever shape
+/// that field has.
+///
+/// The benchmark compiles this one source file against two revisions of
+/// `fspy` — the pull request's and its merge base's — so that identical
+/// launcher code times both arms. A revision that changes the field's type
+/// would otherwise stop the other arm from building. Exactly one of these
+/// impls applies per build; the other is inert.
+trait TrackedAccesses {
+    fn tracked(self) -> PathAccessIterable;
+}
+
+impl TrackedAccesses for PathAccessIterable {
+    fn tracked(self) -> PathAccessIterable {
+        self
+    }
+}
+
+impl<E: std::fmt::Debug> TrackedAccesses for Result<PathAccessIterable, E> {
+    fn tracked(self) -> PathAccessIterable {
+        self.expect("the tracking region holds every record this run makes")
+    }
+}
+
 async fn validate(target: &OsString, target_args: &[OsString], relative: bool) {
     let mut command = Command::new(target);
     command
@@ -159,7 +183,7 @@ async fn validate(target: &OsString, target_args: &[OsString], relative: bool) {
         .await
         .expect("failed to wait for tracked target");
     assert!(termination.status.success(), "benchmark target failed: {}", termination.status);
-    let captured_missing_access = termination.path_accesses.iter().any(|access| {
+    let captured_missing_access = termination.path_accesses.tracked().iter().any(|access| {
         access.path.strip_path_prefix(MISSING_PATH, |result| {
             result.is_ok_and(|path| path.as_os_str().is_empty())
         })

crates/fspy_client_unix/Cargo.toml

@@ -14,7 +14,6 @@ libc = { workspace = true }
 nix = { workspace = true, features = ["fs"] }
 fspy_nostd = { workspace = true }
 fspy_nostd_alloc = { workspace = true }
-wincode = { workspace = true }
 
 [target.'cfg(all(target_os = "linux", not(target_env = "musl")))'.dependencies]
 itoa = { workspace = true }