guardedWrite: cross-process conditional publication (residual check-to-rename window)

[easonLiangWorldedtech]

Residual window: check-to-rename across processes

Filed from the file-write safety series (epic #1375, trial #1413) after the CodeRabbit review of the guardedWrite TOCTOU finding.

What the guard covers today

guardedWrite (src/core/tools/guardedWrite.ts) makes the agent's own writes fail stale when the file changed since the agent's read:

• a per-path FIFO serializes in-process publication, and
• the version token (dev:ino:size:mtimeNs:ctimeNs) is recomputed at publish time and compared before the rename.

The residual window

Between the recomputed token check and the rename, a different process (another extension host, an external editor with a plugin, a shell command) can still create or modify the file; the rename then overwrites it. No in-process serialization can close this window.

Why it is out of scope for the series

Atomic conditional publication (rename-if-version-matches, O_EXCL create, or a lock held through the rename) has no portable Node primitive:

• Windows has no POSIX conditional rename, and
• MS_SHARE_DENY_WRITE / proper-lockfile style locks are advisory and do not survive a crash of the locking process.

Implementing a cross-process protocol (lockfile coordination across every writer, including user editors) is a platform-level change beyond this series' write-safety goal. Crash-atomicity of publication is already covered by the staged temp + atomic rename (S3).

Options for the follow-up

1. Document the residual window in the epic's risk section (wording proposed in the feat(fws): file-write safety series — trial build (all 15 component PRs) #1413 review thread).
2. Optional hardening: detect the post-check modification on best-effort platforms (e.g. re-stat after the rename and surface a warning when the token moved) — loud, not preventing.
3. Optional: adopt a per-workspace lockfile protocol for guarded publications (requires coordination with non-agent writers to be effective).

Linked: epic #1375, trial PR #1413.