Concurrent writes

This page is about what happens when more than one writer works in the same workspace at the same time: agents on different machines, a fleet of workers, or an agent writing while you edit. If your workspace has one writer at a time, skip this page; everything behaves like a local directory, and other machines see finished writes within tens of milliseconds.

Two machines, one directory tree

File and directory operations (create, mkdir, rename, delete, chmod) take effect for every mount the moment they succeed. Two machines never see different directory listings:

# On machine A:
mkdir /mnt/work/outputs

# On machine B, immediately after:
ls /mnt/work
# outputs

Two writers, one file: don't

If two machines write the same file at the same time, the file ends up interleaved: blocks of up to 4 MB from one writer mixed with blocks from the other. No bytes are lost or corrupted, but the file as a whole is neither writer's version.

This is the one behavior to design around, and the fix is cheap:

• One file per writer. outputs/agent-7/result.json instead of every agent appending to outputs/all.log. Collisions become impossible.
• Merge at read time. The reader concatenates logs/*.log when it needs the combined view.

One writer per file is always safe, regardless of how many machines write to the workspace.

When other machines see your write

A finished write is readable everywhere within tens of milliseconds. Each mount caches data it has read, and a read after a remote change returns the new bytes. You don't manage this; it's the default.

Publishing results readers can trust

Two situations let a reader catch work in progress:

• A file is read mid-write, showing only the part written so far.
• A result spans several files (a report plus its attachments, a directory of shards), and a reader lists the directory after the first file landed but before the last. Files land one by one; there is no way to make several files appear simultaneously.

One pattern fixes both: write into a hidden path, then rename into place as the last step. Rename is atomic across machines, so every reader sees the old state or the new state, never something in between.

# Single file:
echo "result" > /mnt/work/outputs/.tmp.result.json
mv /mnt/work/outputs/.tmp.result.json /mnt/work/outputs/result.json

# A result made of several files: stage the directory, rename it last.
mkdir -p /mnt/work/outputs/.staging
# ... write report.md, chart.png, data.csv into .staging/ ...
mv /mnt/work/outputs/.staging /mnt/work/outputs/run-001

A reader polling outputs/ sees run-001 appear complete, with everything inside it, or not at all.

If you need exactly one writer

When two machines must not do the same work at the same time (claiming a queue item, rebuilding an index), use a lock or a claim-by-rename: both work across machines. See File locks and coordination.