fix(core): serialize file tool operations and make writes atomic (#29078) - #29499

Summary

Fixes concurrent file operations race conditions across tool executions (notably parallel sub-agents) in packages/core. When multiple tool invocations execute simultaneously against the same file path, uncoordinated read-modify-write sequences cause silent lost updates, inaccurate diff calculations, and shadow Git snapshot collisions (.git/index.lock).

This PR:

1. Introduces an in-process, per-path async mutex (withPathLock) supporting immediate cancellation while queued.
2. Normalizes lock keys to canonical real paths with parent directory resolution fallback when target files do not exist yet.
3. Serializes read-modify-write critical sections in EditTool and WriteFileTool by resolved path.
4. Implements atomic file writes in StandardFileSystemService.writeTextFile using sibling temporary files with permission preservation and Windows EBUSY/EPERM/EACCES rename retries.
5. Serializes shadow Git repository snapshot creations per resolved project root to prevent .git/index.lock collisions.

Details

• In-process Path Mutex (withPathLock): Coordinates file tool actions inside the Node.js process using normalized absolute path keys with resolveToRealPath and parent directory resolution fallback. Waiters in the lock queue observe AbortSignal and reject immediately if aborted, while handing off the lock chain safely to downstream waiters.
• EditTool & WriteFileTool Serialization: Wraps calculateEdit $\to$ writeTextFile and file existence verification in withPathLock. Prevents two parallel operations from reading an identical base version and clobbering each other's edits.
• Atomic Writes in StandardFileSystemService: Writes content to a unique sibling .tmp file (${realPath}.${randomUUID()}.tmp) and atomically renames (fs.rename) it to the target path. Preserves existing file permissions (0600), handles symlink target resolution, cleans up temp files on error, and retries on Windows transient lock/sharing violation errors (EBUSY, EPERM, EACCES).
• Git Service Snapshot Serialization: Wraps createFileSnapshot in withPathLock('git-snapshot:' + realProjectRoot) to prevent concurrent staging (git add .) and commit operations from conflicting or locking .git/index.lock.
• Zero New Linter Suppressions: Adheres strictly to project coding standards with zero new eslint-disable rules.

Related Issues

Closes #29078

How to Validate

1. Automated Vitest Tests

Run the dedicated concurrency and core test suites:

npx vitest run \
  packages/core/src/utils/pathMutex.test.ts \
  packages/core/src/services/fileSystemService.test.ts \
  packages/core/src/services/fileSystemService.atomic.test.ts \
  packages/core/src/services/gitService.test.ts \
  packages/core/src/tools/edit.test.ts \
  packages/core/src/tools/write-file.test.ts

Expected: All 6 test files pass (162 tests passed).

2. Manual Verification

• Scenario 1 (Non-atomic writes): A concurrent reader in a tight loop reading a file during a 10MB write observed 0 partial or truncated reads. The file transitioned atomically between the old and new states.
• Scenario 2 (Lost updates): Two parallel operations performing read-modify-write appending to the same file were serialized by withPathLock. Both operations persisted cleanly with zero lost updates.
• Scenario 3 (Checkpoint race): Five concurrent calls to GitService.createFileSnapshot in the same shadow repository executed concurrently without .git/index.lock collisions or corrupted snapshot history.
• Sub-Agent Concurrency: Two sub-agents appending unique lines to test.txt preserved both lines on disk with no lost updates.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker