Skip to content

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

Rust

fix(wikisync): serialize mutating runs

AkitaOnRails122b100d1cf5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a0cee56..1da27882 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,10 @@ version in [`docs/changelog/`](docs/changelog/):
### Fixed
+- Serialized mutating wikisync runs per destination across their full
+ read/plan/write lifecycle, so overlapping exports no longer race on the
+ shared state temporary file or apply plans from the same baseline (#1847).
+
- Bounded the wiki append-versus-commit concurrency regression so filesystem
scheduling cannot turn its background writers into an unbounded fsync
workload on macOS, while every round still contends with a commit (#1850).
diff --git a/companions/ai-memory-wikisync/Cargo.lock b/companions/ai-memory-wikisync/Cargo.lock
index 5a283622..1a240d80 100644
--- a/companions/ai-memory-wikisync/Cargo.lock
+++ b/companions/ai-memory-wikisync/Cargo.lock
@@ -9,6 +9,7 @@ dependencies = [
"anyhow",
"axum",
"clap",
+ "fs2",
"reqwest",
"serde",
"serde_json",
@@ -346,6 +347,16 @@ dependencies = [
"percent-encoding",
]
+[[package]]
+name = "fs2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
[[package]]
name = "futures-channel"
version = "0.3.34"
@@ -1476,6 +1487,28 @@ dependencies = [
"wasm-bindgen",
]
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
[[package]]
name = "windows-link"
version = "0.2.1"
diff --git a/companions/ai-memory-wikisync/Cargo.toml b/companions/ai-memory-wikisync/Cargo.toml
index a8a30b73..83df94f9 100644
--- a/companions/ai-memory-wikisync/Cargo.toml
+++ b/companions/ai-memory-wikisync/Cargo.toml
@@ -9,6 +9,7 @@ publish = false
[dependencies]
anyhow = "1"
clap = { version = "4", features = ["derive", "env"] }
+fs2 = "0.4"
# Native roots, matching the workspace: the export reads from the same server
# an operator may front with a private CA (#492).
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots"] }
diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.md
index 61667b6e..697eeb0a 100644
--- a/companions/ai-memory-wikisync/README.md
+++ b/companions/ai-memory-wikisync/README.md
@@ -95,6 +95,14 @@ each successful write batch): per page, the SHA-256 of the bytes last
written plus the server `ETag` and version id observed at that write.
Nothing else is stored: no tokens and no server credentials.
+Mutating `export --apply` and `sync --apply` runs take an exclusive OS lock
+for the destination before loading this state and hold it through planning,
+writes, and the final state save. A second mutating run fails promptly with a
+busy-destination error; a crash releases the lock automatically. Read-only
+`plan`, dry-run export/sync, and `sync --check` do not create or take the lock,
+so they remain strictly non-mutating; when run alongside an apply, their report
+may describe the state before that apply finishes.
+
The state is per clone. The state directory carries a `.gitignore` of `*`,
so committing the destination never commits the state: two clones that
shared one would conflict on every merge and trust each other's baselines.
diff --git a/companions/ai-memory-wikisync/src/bidi.rs b/companions/ai-memory-wikisync/src/bidi.rs
index 5cb59c83..d615b8dc 100644
--- a/companions/ai-memory-wikisync/src/bidi.rs
+++ b/companions/ai-memory-wikisync/src/bidi.rs
@@ -324,6 +324,9 @@ pub async fn run(args: &SyncArgs, mode: SyncMode) -> Result<Outcome> {
Mode::DryRun
};
let dest_root = sync::resolve_dest(&run_args.dest, fs_mode)?;
+ let _write_lock = (mode == SyncMode::Apply)
+ .then(|| state::acquire_write_lock(&dest_root))
+ .transpose()?;
let stateless_check = mode == SyncMode::Check && !state::state_path(&dest_root).exists();
let scope = state::SyncScope::of(&run_args.server, &run_args.workspace, &run_args.project);
let old_state = sync::baseline_for(state::load(&dest_root)?, &scope, run_args.adopt_scope)?;
diff --git a/companions/ai-memory-wikisync/src/state.rs b/companions/ai-memory-wikisync/src/state.rs
index 7a93b3ba..0cbfbc2a 100644
--- a/companions/ai-memory-wikisync/src/state.rs
+++ b/companions/ai-memory-wikisync/src/state.rs
@@ -23,6 +23,7 @@ use crate::STATE_DIR;
const STATE_FILE: &str = "state.json";
const IGNORE_FILE: &str = ".gitignore";
+const LOCK_FILE: &str = "write.lock";
/// Ignores the state directory, this file included. Two clones that both
/// commit their state would conflict on every merge and replay each other's
/// baselines.
@@ -142,6 +143,51 @@ pub fn state_path(dest_root: &Path) -> PathBuf {
dest_root.join(STATE_DIR).join(STATE_FILE)
}
+/// Exclusive ownership of one destination's read/plan/write lifecycle.
+/// Keeping the file handle alive keeps the OS lock alive; process exit also
+/// releases it, so a crashed sync never leaves a stale lease to clean up.
+#[derive(Debug)]
+pub struct WriteLock {
+ _file: fs::File,
+}
+
+/// Fail promptly when another mutating run owns this destination.
+///
+/// The lock lives beside clone-local state and covers the whole operation,
+/// not only [`save`]: two plans derived from one baseline must not both apply.
+pub fn acquire_write_lock(dest_root: &Path) -> Result<WriteLock> {
+ let dir = dest_root.join(STATE_DIR);
+ ensure_real_state_dir(&dir)?;
+ fs::create_dir_all(&dir).with_context(|| format!("cannot create {}", dir.display()))?;
+ ensure_real_state_dir(&dir)?;
+ ignore_state_dir(&dir)?;
+
+ let path = dir.join(LOCK_FILE);
+ if fs::symlink_metadata(&path).is_ok_and(|meta| meta.file_type().is_symlink()) {
+ bail!("write lock is a symlink: {}", path.display());
+ }
+ let mut options = fs::OpenOptions::new();
+ options.read(true).write(true).create(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ options.mode(0o600);
+ }
+ let file = options
+ .open(&path)
+ .with_context(|| format!("cannot open write lock {}", path.display()))?;
+ if fs::symlink_metadata(&path).is_ok_and(|meta| meta.file_type().is_symlink()) {
+ bail!("write lock became a symlink: {}", path.display());
+ }
+ fs2::FileExt::try_lock_exclusive(&file).with_context(|| {
+ format!(
+ "destination {} is already being modified by another ai-memory-wikisync run",
+ dest_root.display()
+ )
+ })?;
+ Ok(WriteLock { _file: file })
+}
+
/// The state directory must be a real directory, never a symlink: a symlink
/// planted on `.ai-memory-wikisync` would move state (and lock the writer
/// into trusting it) outside the destination.
@@ -324,6 +370,33 @@ mod tests {
}
}
+ #[test]
+ fn write_lock_is_exclusive_and_released_with_its_guard() {
+ let tmp = tempfile::tempdir().unwrap();
+ let root = tmp.path().canonicalize().unwrap();
+
+ let first = acquire_write_lock(&root).unwrap();
+ let err = acquire_write_lock(&root).unwrap_err().to_string();
+ assert!(err.contains("already being modified"), "{err}");
+
+ drop(first);
+ acquire_write_lock(&root).expect("closing the first handle releases the OS lock");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn write_lock_refuses_a_symlink() {
+ let tmp = tempfile::tempdir().unwrap();
+ let root = tmp.path().canonicalize().unwrap();
+ let dir = root.join(STATE_DIR);
+ fs::create_dir_all(&dir).unwrap();
+ fs::write(root.join("elsewhere"), b"").unwrap();
+ std::os::unix::fs::symlink(root.join("elsewhere"), dir.join(LOCK_FILE)).unwrap();
+
+ let err = acquire_write_lock(&root).unwrap_err().to_string();
+ assert!(err.contains("symlink"), "{err}");
+ }
+
#[test]
fn missing_state_is_empty_and_corrupt_state_fails_closed() {
let tmp = tempfile::tempdir().unwrap();
diff --git a/companions/ai-memory-wikisync/src/sync.rs b/companions/ai-memory-wikisync/src/sync.rs
index 0ac19411..def2d914 100644
--- a/companions/ai-memory-wikisync/src/sync.rs
+++ b/companions/ai-memory-wikisync/src/sync.rs
@@ -687,6 +687,9 @@ pub(crate) fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {
pub async fn run(args: &RunArgs, mode: Mode) -> Result<()> {
let families = validate_allowlist(&args.include)?;
let dest_root = resolve_dest(&args.dest, mode)?;
+ let _write_lock = (mode == Mode::Apply)
+ .then(|| state::acquire_write_lock(&dest_root))
+ .transpose()?;
let scope = state::SyncScope::of(&args.server, &args.workspace, &args.project);
let old_state = baseline_for(state::load(&dest_root)?, &scope, args.adopt_scope)?;
let client = ApiClient::new(&args.server, args.token.clone())?;