Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(wiki): absorb transient Windows sharing violations in atomic persists (#568)

Fabio Akitab6448ec75d5e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f810742..55e4769d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -331,6 +331,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
Re-run `install-hooks --apply` to move an existing install onto the stored
form. Only `--apply` persists; printing a snippet writes no credential.
+- Atomic wiki writes now absorb transient Windows sharing violations (#567).
+ On Windows the tmp-then-rename persist can fail with
+ `ERROR_SHARING_VIOLATION` when an antivirus or indexer briefly holds the
+ just-created tempfile — endemic on CI runners, and the cause of a
+ `per_session_isolates_concurrent_writes` failure on the nightly Windows run.
+ Both persist sites retry up to five times with linear backoff (at most
+ 150 ms) before propagating; `ACCESS_DENIED` and every other error still
+ propagate immediately, and nothing is classified transient off Windows, so
+ Unix behaviour is byte-for-byte unchanged. The retry mechanics are tested on
+ every platform by injecting the failure rather than hoping to reproduce a
+ scanner's timing.
+
### Docs
- `docs/windows.md` gains **Scenario E**, a persistent-server story for native
diff --git a/crates/ai-memory-wiki/src/atomic.rs b/crates/ai-memory-wiki/src/atomic.rs
index f9e22022..fb9e2a90 100644
--- a/crates/ai-memory-wiki/src/atomic.rs
+++ b/crates/ai-memory-wiki/src/atomic.rs
@@ -7,9 +7,85 @@
use std::fs::File;
use std::io::Write;
use std::path::Path;
+use std::time::Duration;
use crate::error::{WikiError, WikiResult};
+/// How many times a persist is retried when the failure is a transient
+/// sharing violation, and the base of the linear backoff between attempts.
+/// Worst case adds 10+20+30+40+50 = 150ms before the real error propagates.
+const PERSIST_RETRY_ATTEMPTS: u32 = 5;
+const PERSIST_RETRY_BASE_DELAY: Duration = Duration::from_millis(10);
+
+/// Persist `tmp` over `path`, absorbing transient Windows sharing violations.
+///
+/// On Windows the rename can fail with `ERROR_SHARING_VIOLATION` (32) or
+/// `ERROR_LOCK_VIOLATION` (33) when another process briefly holds the
+/// just-created tempfile or the destination — most commonly an antivirus or
+/// indexer scanning the new file, which is endemic on CI runners. The hold is
+/// transient by nature, so a short bounded retry absorbs it; anything that
+/// outlasts the budget is a real error and propagates unchanged. On
+/// non-Windows platforms nothing is classified transient, so behaviour is
+/// byte-for-byte what it was.
+pub(crate) fn persist_with_retry(
+ tmp: tempfile::NamedTempFile,
+ path: &Path,
+) -> Result<File, tempfile::PersistError> {
+ persist_with_retry_impl(
+ tmp,
+ PERSIST_RETRY_ATTEMPTS,
+ PERSIST_RETRY_BASE_DELAY,
+ is_transient_sharing_violation,
+ |tmp, path| tmp.persist(path),
+ path,
+ )
+}
+
+/// The retry loop with its collaborators injected, so the mechanics are
+/// testable on every platform: tests fabricate `PersistError`s (its fields
+/// are public) and supply their own transience predicate and zero delay,
+/// while production supplies the Windows classifier and the real `persist`.
+fn persist_with_retry_impl<F, P>(
+ mut tmp: tempfile::NamedTempFile,
+ attempts: u32,
+ base_delay: Duration,
+ transient: P,
+ mut attempt_fn: F,
+ path: &Path,
+) -> Result<File, tempfile::PersistError>
+where
+ F: FnMut(tempfile::NamedTempFile, &Path) -> Result<File, tempfile::PersistError>,
+ P: Fn(&std::io::Error) -> bool,
+{
+ let mut attempt = 0u32;
+ loop {
+ match attempt_fn(tmp, path) {
+ Ok(file) => return Ok(file),
+ Err(err) if attempt < attempts && transient(&err.error) => {
+ attempt += 1;
+ std::thread::sleep(base_delay * attempt);
+ // `PersistError` hands the tempfile back, which is what makes
+ // retrying possible at all: the staged bytes are still intact.
+ tmp = err.file;
+ }
+ Err(err) => return Err(err),
+ }
+ }
+}
+
+/// Windows: sharing (32) and lock (33) violations are transient third-party
+/// holds. Everything else — including `ACCESS_DENIED`, which is usually a
+/// real permissions problem — propagates immediately. Elsewhere: nothing is
+/// transient; raw code 32 on Unix is `EPIPE` and retrying a rename on it
+/// would be noise on top of a real failure.
+fn is_transient_sharing_violation(err: &std::io::Error) -> bool {
+ if cfg!(windows) {
+ matches!(err.raw_os_error(), Some(32) | Some(33))
+ } else {
+ false
+ }
+}
+
/// Atomically replace the file at `path` with `bytes`.
///
/// Steps: write to a `tempfile` in the same directory, `sync_data` the
@@ -33,7 +109,7 @@ pub fn write_atomic(path: &Path, bytes: &[u8]) -> WikiResult<u64> {
tmp.write_all(bytes)?;
tmp.as_file().sync_data()?;
- let persisted: File = tmp.persist(path)?;
+ let persisted: File = persist_with_retry(tmp, path)?;
persisted.sync_data()?;
// Best-effort: fsync the parent so the rename is durable too.
@@ -72,6 +148,115 @@ mod tests {
use super::*;
use tempfile::TempDir;
+ fn staged(dir: &TempDir) -> tempfile::NamedTempFile {
+ let mut tmp = tempfile::Builder::new().tempfile_in(dir.path()).unwrap();
+ tmp.write_all(b"staged bytes").unwrap();
+ tmp
+ }
+
+ fn sharing_violation(tmp: tempfile::NamedTempFile) -> tempfile::PersistError {
+ tempfile::PersistError {
+ error: std::io::Error::from_raw_os_error(32),
+ file: tmp,
+ }
+ }
+
+ /// A transient hold that clears must not surface: the retry absorbs the
+ /// first failures and the bytes still land. This is the Windows-CI
+ /// antivirus scenario, exercised on every platform by injecting the
+ /// failure instead of hoping to reproduce a scanner's timing.
+ #[test]
+ fn a_transient_hold_is_absorbed_and_the_write_lands() {
+ let dir = TempDir::new().unwrap();
+ let target = dir.path().join("page.md");
+ let mut failures_left = 3;
+ let result = persist_with_retry_impl(
+ staged(&dir),
+ 5,
+ Duration::ZERO,
+ |_| true,
+ |tmp, path| {
+ if failures_left > 0 {
+ failures_left -= 1;
+ Err(sharing_violation(tmp))
+ } else {
+ tmp.persist(path)
+ }
+ },
+ &target,
+ );
+ assert!(result.is_ok(), "three transient failures must be absorbed");
+ assert_eq!(std::fs::read(&target).unwrap(), b"staged bytes");
+ }
+
+ /// A hold that never clears is a real error: the budget bounds the wait
+ /// and the final error propagates rather than looping forever.
+ #[test]
+ fn a_persistent_hold_exhausts_the_budget_and_propagates() {
+ let dir = TempDir::new().unwrap();
+ let target = dir.path().join("page.md");
+ let mut calls = 0u32;
+ let result = persist_with_retry_impl(
+ staged(&dir),
+ 5,
+ Duration::ZERO,
+ |_| true,
+ |tmp, _| {
+ calls += 1;
+ Err(sharing_violation(tmp))
+ },
+ &target,
+ );
+ assert!(result.is_err());
+ assert_eq!(calls, 6, "initial attempt plus five retries, then stop");
+ }
+
+ /// A non-transient error must NOT be retried: retrying a real failure
+ /// only delays it and can mask its cause. The control for the whole
+ /// mechanism — if the loop treated everything as transient, this fails.
+ #[test]
+ fn a_non_transient_error_propagates_immediately() {
+ let dir = TempDir::new().unwrap();
+ let target = dir.path().join("page.md");
+ let mut calls = 0u32;
+ let result = persist_with_retry_impl(
+ staged(&dir),
+ 5,
+ Duration::ZERO,
+ |_| false,
+ |tmp, _| {
+ calls += 1;
+ Err(sharing_violation(tmp))
+ },
+ &target,
+ );
+ assert!(result.is_err());
+ assert_eq!(calls, 1, "no retry when the predicate says non-transient");
+ }
+
+ /// Pins the production classifier per platform: on Unix nothing is
+ /// transient (raw 32 is EPIPE there), so Unix persist behaviour is
+ /// byte-for-byte unchanged by this fix. On Windows, 32 and 33 retry.
+ #[test]
+ fn the_classifier_matches_only_windows_sharing_codes() {
+ let sharing = std::io::Error::from_raw_os_error(32);
+ let lock = std::io::Error::from_raw_os_error(33);
+ let denied = std::io::Error::from_raw_os_error(5);
+ if cfg!(windows) {
+ assert!(is_transient_sharing_violation(&sharing));
+ assert!(is_transient_sharing_violation(&lock));
+ assert!(
+ !is_transient_sharing_violation(&denied),
+ "ACCESS_DENIED is a real permissions problem, not a transient hold"
+ );
+ } else {
+ assert!(
+ !is_transient_sharing_violation(&sharing),
+ "nothing is transient off Windows; unix behaviour is unchanged"
+ );
+ }
+ }
+
#[test]
fn writes_atomically_and_creates_parents() {
let tmp = TempDir::new().unwrap();
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 52256886..6042746f 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -2099,7 +2099,7 @@ fn persist_tmp_with_rollback_snapshot(
path: &Path,
) -> WikiResult<InstalledFile> {
let previous = snapshot_existing_file(path)?;
- let persisted = tmp.persist(path)?;
+ let persisted = crate::atomic::persist_with_retry(tmp, path)?;
persisted.sync_data()?;
sync_parent_best_effort(path);
Ok(InstalledFile {