Make the bridge's on-disk stores safe to publish and safe to watch

[bharathm03]

Four commits hardening how the bridge persists state. Each one started as a defect found by measurement, and the measurement is in the commit message.

1. Every machine-level store publishes by rename, never by truncation

paired-phones.json, mobile-access-policy.json and trusted-peers.json were written with a plain writeFileSync, which truncates before it writes. A reader arriving in that window sees an empty or half-written document — and for the remote-access policy that is the sole machine-level authorization gate reading as unset. All three now go through atomicWriteFile.

The scratch file is scoped to the pid rather than shared. A single <path>.tmp is itself a contended file: the antgrid CLI writes these same stores while the host runs, both truncate into one scratch path, and the rename then publishes the blend through the very step meant to prevent one.

Windows refuses a rename whose target another process holds open — a plain reader is enough — as a MoveFileEx sharing violation surfaced as EPERM/EBUSY/EACCES. Without a retry the fix would have traded silent corruption for a thrown write. It retries with no delay first, short-circuits on a target that will refuse however long we wait (a read-only file and a directory in the way report the same codes), and is empty on POSIX, where those codes only ever mean a permanent fault.

Three consequences of publishing by rename that the old truncating write did not have, all handled here:

• The target is briefly unlinked, so remote-access-policy re-checks before believing the file absent. Absence is the one verdict that writes, routing to a v1 migration that derives false from grants shed on the first upgrade and persists it — permanently revoking a machine the user had enabled, since a v2 file never re-migrates.
• That migration now refuses to persist a derived false unless both v1 stores actually answered.
• setEnabled persists before flipping memory, so a failed write cannot leave the gate reading "off" in memory while disk still says "on".

2. Reap the scratch file a killed writer left in the user's directories

A rename is atomic only within a filesystem, so the scratch file has to sit in the target's own directory — and those directories are the user's. antgrid.yaml is written in their git working tree, where a leaked antgrid.yaml.<pid>.tmp shows up in git status and can be committed (verified: nothing ignores it). host.json leaks a full copy of the control-plane token into <abDir>, which removeHostFile never reaps.

Nor is this a crash path — force-kill is the routine teardown on Windows, since the app assigns the host to a job object with KILL_ON_JOB_CLOSE precisely so the kernel sweeps the tree.

The sweep runs once per target per process, matches on the whole basename so two stores sharing a directory cannot reap each other, and skips any pid still running — so pid reuse can only make us keep a stale file, never delete one being written.

3. Watch the directory: a renamed-over config file goes deaf on Linux

ConfigController.watch armed fsWatch on the file path, while write() publishes by rename. An inotify watch is keyed to the inode it was armed on, so the first save orphans it and every later one is invisible for the life of the process.

Measured under Docker. Cumulative callback counts on one watcher across write → rename-publish → write-again → rename-again:

runtime	counts	verdict
Linux, Node 22	1 / 4 / 4 / 4	dead after the rename
Linux, Bun 1.3.14	1 / 2 / 2 / 2	dead after the rename
Windows, control	2 / 4 / 6 / 8	survives

Bun's fs.watch is its own Zig implementation rather than libuv, so this is two independent implementations landing on the same inode semantics — the bridge runs on Bun, so runtime choice does not save it. Identical on overlayfs and tmpfs, so it is inotify semantics and not a storage-driver artifact. The Windows control run reproducing the earlier measurement is what shows the probe measures the real thing. Scope: measured on a WSL2 kernel, not bare metal.

Why it matters. config:write applies nothing itself — it only replies config:write-result — so the watcher firing is the sole thing that restarts agents and starts or stops services per computeDiff. On Linux, saving config in the app reported success and silently did nothing until the bridge restarted.

The fix is one unconditional directory watch with a basename filter, which is what the same function's own fallback arm and paired-phones.ts already did. The filter over-accepts on purpose, because a spurious hit costs one debounced re-read of a fixed path while a dropped one is the deafness itself:

• Case-insensitively. antgrid.yaml is user-authored, so a repo may carry Antgrid.yaml, and every other access resolves it case-insensitively on Windows and macOS. An exact compare would find the file, seed from it, serve reads off it — then ignore every save to it.
• The .tmp scratch. Windows names only the scratch when the rename target does not yet exist, so dropping it makes a config file's first creation unobservable.
• A nameless event, which carries nothing to filter on.

4. Serialize the two sessions.json writers on one publish primitive

sessions.json had two writers — an async one that awaited between its write and its rename, and a 200ms debounced sync one — sharing a single scratch filename. They interleave with no second process involved. Reverting the fix reproduces three distinct failures: an ENOENT rejection when the sync writer renames the shared scratch out from under the async one, a resurrected row from two overlapping deletes each republishing what it read, and an EPERM from both colliding on that one name. session-manager.ts's own comment states the cost of the corrupt case — a truncated sessions.json is read as empty and silently drops every session.

Both now go through one synchronous publish built on atomicWriteFile, so the publish occupies a single turn with nothing able to interleave. withSessionsFile (createKeyedLock, the mechanism CheckoutStore already uses for its sibling file) covers the writers that suspend: deletePersisted's read-modify-write, and the debounced flush now queued behind it.

flushNow deliberately stays off that lock — teardownServices does not await it, so its write has to land on the tick or the last activity bump is lost on every clean shutdown. The doc comments say exactly that rather than claiming a mutual exclusion the code does not hold: making such a claim true by locking inside the primitive would deadlock every isolated-session create and every cold delete, since createKeyedLock is not reentrant and both awaited callers already hold the key.

A fired debounce whose write is still queued on the lock now sets a flag, because flushNow read a null flushTimer as clean and would have skipped the final write on exactly the shutdown it exists to cover.

Testing

• bun run --filter antgrid-bridge typecheck → exit 0
• bun run --filter antgrid-bridge test → 3002 pass, 6 skip, 0 fail across 244 files (baseline before this branch: 2984)

Every new assertion was regression-checked by reverting the fix under it and confirming the exact failure line. Two are called out as not self-verifying on a dev machine:

• The rename test in config-controller.test.ts cannot fail on Windows — libuv implements a file-path watch there as a parent-directory subscription, so inode deafness is structurally unreproducible. Its real verification is the first CI run on ubuntu-latest. Its comment says so, so it is not later deleted as redundant.
• The delete-persisted suite's leaked-scratch assertion named the old fixed sessions.json.tmp, which is now a filename nothing writes — it passed even with the rename deleted outright. It matches by prefix instead.

Known trade, worth a second opinion

atomicWriteFile's Windows retry ladder can block the event loop up to ~93ms, and deletePersisted runs on the WS control-plane loop where the original code chose async specifically to avoid that. The debounced flush already did an unretried sync write to the same file several times a second, and the alternative on Windows is a silently lost write rather than a delayed one — but it is a trade, not a free win.

Deliberately not included

• The hooks read-modify-write clobber in cursor-agent/hooks.ts — a retrying loser overwrites the merged document it should re-read, then returns true, so the session whose hooks were just dropped suppresses its OSC fallback. The fix is re-read-and-re-merge on contention, which is a design call rather than a cleanup.
• flushSeenProjects (host-server.ts) still writes the project catalog with a plain truncating writeFileSync — the catalog that is the only per-project bound on which projectId a phone may name.
• writeConfigYaml (bootstrap.ts), the interactive CLI first-run path, is a plain truncating write of antgrid.yaml.