Module file_mutation_queue 

Mirrors packages/agent/src/harness/tools/file-mutation-queue.ts — serializes file-mutating operations per canonical path so concurrent edits to the same path (or a symlink + its target) don’t interleave.

The TS uses a WeakMap<ExecutionEnv, MutationQueueState> keyed by env instance. Rust has no per-instance map keyed by trait object, so each env impl carries an Arc<MutationQueueRegistry> field and exposes it via the MutatingEnv accessor trait. The mutation-dependent tools (write, edit) hold Arc<dyn MutatingEnv>; read and bash don’t need it.

Critical invariant (plan §5.4): abort does NOT unblock the queue. An aborted caller still waits for its turn, then runs fn (which may observe the abort and return Err(Aborted)), then releases. The lock guard is held across fn().await; a CancellationToken only causes fn to error out — it does NOT preempt mutex acquisition.

Structs

MutationQueueRegistry

Per-env registry of canonical-path → mutex. Stored as a field on each env impl (behind Arc so clones share the same map).

Traits

MutatingEnv

Accessor used by with_file_mutation_queue to reach the env’s registry AND its ExecutionEnv methods. Concrete env impls (OsExecutionEnv, InMemoryExecutionEnv) implement this; the write/edit tools hold Arc<dyn MutatingEnv>.

Functions

get_mutation_queue_key

Compute the canonical-path queue key for path. Mirrors getMutationQueueKey:

with_file_mutation_queue

Serialize fn per canonical-path key for env. The closure f runs while holding the per-key tokio::Mutex guard; abort/cancel during the wait does NOT skip the queue — f itself must observe the token and return Err(FileError::aborted()).