[EPIC] File Write Safety Prevent Concurrent Write Races Data Corruption

[easonLiangWorldedtech]

Summary

Multiple confirmed cases of file corruption and lost writes across the ZOO codebase due to lack of atomic file writes, version guards, and cross-process locking. This epic coordinates fixing all known issues and implementing a robust filesystem safety layer.

Impact

• Multi-window Electron: Each window is an independent Node process -- concurrent windows overwrite each other.
• JetBrains plugin: Issue [BUG][regression] Global _index.json full rewrite is unsafe under concurrent tasks (real corruption under JetBrains multi-agent) #1231 confirmed real corruption under multi-agent usage.
• Subtask fan-out: Concurrent subtasks from parallel dispatch compound the problem.

Known Issues

#	Title	Status	Severity
#1371	MCP settings wiped by concurrent windows	Open	High
#920	Concurrent task history updates cause lost entries	Open	Medium
#1221	Truncated tool-call args silently written to disk	Open	Medium
#1021	Race in abandonSubtask for saveClineMessages	Open	Medium
#1231	Global _index.json full rewrite unsafe (corruption confirmed)	Closed	-

Related stories (pending):

• #376 File-level write serialization
• #370 Extension-side task-scoping guard

Current State: Three-Layer Defense Gap

DSH Layer	ZOO Status	Details
Policy CAS (observed version -> replaceIfVersion)	Nonexistent	No read-version record, no write-time check
Per-target FIFO lock	Dead code	safeWriteJson.ts uses proper-lockfile but zero importers
Atomic publish (staging + fsync + rename)	Half	Main paths use raw fs.writeFile()

Unsafe Paths Currently Used

DiffViewProvider.saveDirectly() -> fs.writeFile(absolutePath, content) NO GUARD
McpHub.initializeMcpServers() -> fs.writeFile direct overwrite NO GUARD

Reference: DSH Implementation

DSH handles this with three orthogonal layers:

1. Policy CAS -- FsObservation records presence+version on read; FsWriteIntent.replaceIfVersion(version) gates writes
2. Per-target FIFO lock -- Map tail-promise chain serializes all mutations per target
3. Atomic publish -- staging dir + temp file (0o600) + fsync + rename/hardlink/ReplaceFile

Proposed Plan

Phase 1 (1-2w): Make safeWriteJson sole JSON entry point; fix #1371,#920,#1221,#1021
Phase 2 (2-3w): Implement Observation Gate + guarded intent into Write/Edit tools
Phase 3 (1w): Port DSH tail-promise FIFO chain to DiffViewProvider/safeWriteJson
Phase 4 (1w): Replace all bare fs.writeFile/fs.appendFile with atomic paths

Acceptance Criteria

• No bare fs.writeFile()/fs.appendFile() in production code (only through guarded wrappers)
• Consecutive writes to same file by different processes are serialized with stale-write rejection
• All open issues resolved (MCP settings wiped when multiple windows open — race in McpHub.getMcpSettingsFilePath() direct fs.writeFile #1371,[BUG] Concurrent task history updates from parallel tabs may cause lost entries #920,Truncated tool-call arguments can be silently written to disk (stale partial-parse nativeArgs reused on finalization failure) #1221,fix(task): guard saveClineMessages against abandoned tasks to prevent race in abandonSubtask #1021)
• End-to-end test covering concurrent window + subtask scenarios passes