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.mdindex 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 filesystemscheduling cannot turn its background writers into an unbounded fsyncworkload 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.lockindex 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.tomlindex 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.mdindex 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 lastwritten 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 thatshared 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.rsindex 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.rsindex 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.rsindex 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())?;