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

[easonLiangWorldedtech]

Problem

The agent's file-write path has no version guard, no atomic publish, and no per-step
visibility:

• Concurrent writers silently overwrite each other's work: parallel subtasks share one
  workspace, multiple VS Code windows are separate extension-host processes, and the
  JetBrains plugin has confirmed real corruption under two IDE instances ([BUG][regression] Global _index.json full rewrite is unsafe under concurrent tasks (real corruption under JetBrains multi-agent) #1231).
• Model writes land directly in the shared workspace with no checkpoint to roll back to;
  task start creates no baseline at all.
• No staleness detection: a file that changed after the model read it is silently
  overwritten on the next write.
• The write path carries artificial latency (1 s delay per write) on top of the missing
  safety.

Known issues

#	Title	Status	Fix in this epic
#1371	MCP settings wiped by concurrent windows	Open	A5 — root cause is the check-then-create TOCTOU in McpHub.getMcpSettingsFilePath() (L496-517), not initializeMcpServers()
#1021	Race in abandonSubtask for saveClineMessages	Open	A5 — fire-and-forget saveClineMessages() re-attaches abandoned subtasks
#920	Concurrent task history updates cause lost entries	Open	A5 — cross-instance (parallel tabs) regression test on the locked-merge write
#1231	Global _index.json full rewrite unsafe (corruption confirmed)	Closed	Already fixed — per-task history_item.json + merge-under-lock; that is now the reference storage pattern
#1221	Truncated tool-call args silently written to disk	Open	A6 (separate story) — parser/finalization defect, not a filesystem-safety problem
#376	File-level write serialization	Open	Superseded by A3
#370	Extension-side task-scoping guard	Open	Related; stays open

Current state (verified in code)

Agent write path

• WriteToFileTool.execute() (src/core/tools/WriteToFileTool.ts:29) →
  DiffViewProvider.saveDirectly() (src/integrations/editor/DiffViewProvider.ts:1141) =
  raw fs.writeFile(absolutePath, content): no lock, no version check, no atomic
  publish, no fsync. This is the main agent write path.
• EditFileTool (src/core/tools/EditFileTool.ts:139) validates old_string against a fresh
  read at write time — a natural staleness detector for edits, but write_to_file (full
  overwrite) has no staleness check at all.
• ReadFileTool records no mtime/stat/checksum of the files it hands to the model, so no
  compare-and-swap is possible anywhere in the codebase.
• Auto-approval (src/core/auto-approval/) can skip user review entirely.
• ExecuteCommandTool runs shell commands in the workspace; shell writes bypass any
  filesystem guard (out of scope, below).

Internal state

• safeWriteJson (src/utils/safeWriteJson.ts) is the JSON-state entry point (imported by
  TaskHistoryStore, taskMessages, apiMessages, McpHub, webviewMessageHandler,
  modelCache): proper-lockfile advisory lock, temp + rename, backup/rollback, merge
  callback. Missing: fsync, Windows DACL preservation, and it does not cover the
  workspace write path.
• MCP settings wiped when multiple windows open — race in McpHub.getMcpSettingsFilePath() direct fs.writeFile #1371 root cause: getMcpSettingsFilePath() (McpHub.ts:496-517) does
  fileExistsAtPath() then a raw fs.writeFile of an empty stub — two windows both see
  "absent" and the second blind write truncates the file to a 122-byte stub (TOCTOU).
• fix(task): guard saveClineMessages against abandoned tasks to prevent race in abandonSubtask #1021: fire-and-forget saveClineMessages() calls can resolve after abandonSubtask()
  and re-attach a severed subtask.

Concurrency

• Parallel subtasks / new_task children: same process, shared workspacePath
  (Task.ts L515-517), no file-level isolation.
• Per-task isolation today = checkpoints shadow git at
  /tasks//checkpoints (ShadowCheckpointService), triggered on
  user message send — not on writes.
• Cross-process (VS Code windows / JetBrains) coordination for workspace files: none.
• Worktrees (packages/core/src/worktree/) are user-UI-only: prompts, tools, and
  Task.startTask contain no worktree references, and git worktree add is a full checkout
  of the base commit. The agent flow does not use it; it cannot serve as the isolation
  mechanism for this work.

Solution

A — Safety core: version guard + per-path serialization + atomic publish

• A1 Version token — dev:ino:size:mtimeNs:ctimeNs from one fs.stat (BigInt). Cost of
  one stat; the token is a disk fact, so all processes observe the same value.
• A2 Observation registry — per-task Map<absolutePath, version>, populated by
  ReadFileTool (one extra stat per read). Owner = task, so parent and subtask
  observations are independent.
• A3 Guarded write and edit — compare-and-swap semantics on the write path:
  • unobserved target → createIfAbsent: succeeds for new files; if the file exists the
    write fails, forcing a read first — the model re-reads and retries with the observed
    version;
  • observed-absent → createIfAbsent;
  • observed-present → replaceIfVersion(version): a mismatch fails the tool call with
    "stale version — re-read the file, then retry";
  • edit keeps the literal-match check plus the version guard; an unobserved edit
    fails with "file not read yet — read the file, then retry".
  • Failures carry a remediation suffix the model can act on, so the standard loop
    self-heals (re-read → retry); the user sees the failure as a step event in chat.
  • A per-absolute-path tail-promise chain (in-process FIFO) wraps read → guard →
    publish, so concurrent subtask mutations to the same file are deterministically
    ordered: one wins, the rest fail as stale.
  • Cross-process stance (explicit): no workspace lockfile. Two processes editing
    the same file are detected via the version token; the loser fails as stale and
    re-reads. A lockfile would block the user's own editor.
• A4 Atomic publish — replace saveDirectly's raw fs.writeFile with: temp file in a
  private per-write staging dir → fsync → rename; on Windows ReplaceFile (with DACL
  copy), rename fallback. Generalize safeWriteJson's staging/backup/rollback into a
  safeWriteText used by both file writes and JSON state.
• A5 Internal-state firebreak
  • MCP settings wiped when multiple windows open — race in McpHub.getMcpSettingsFilePath() direct fs.writeFile #1371: replace the raw stub write in getMcpSettingsFilePath() with
    safeWriteJson(..., { merge: keep existing if non-empty }) — atomic read-modify-write
    under the advisory lock closes the TOCTOU.
  • fix(task): guard saveClineMessages against abandoned tasks to prevent race in abandonSubtask #1021: guard in-flight saveClineMessages() with this.abandoned (extract from
    feature/local-usage-stats, commit 1d1eb91).
  • [BUG] Concurrent task history updates from parallel tabs may cause lost entries #920: cross-instance (parallel tabs) regression test for updateTaskHistory on the
    locked-merge write.
• A6 Truncated tool-call args (Truncated tool-call arguments can be silently written to disk (stale partial-parse nativeArgs reused on finalization failure) #1221, separate story) — a NativeToolCallParser
  finalization failure must not reuse the streaming-phase nativeArgs (partial-json
  output); fail the tool call with an explicit "arguments were truncated" error instead
  of writing the truncated content to disk.

Latency — net write-path cost added by A: one stat + one fsync + one rename. On top
of that, remove the artificial delays:

Current slow point	Location	Action
1000 ms delay per write	DEFAULT_WRITE_DELAY_MS (packages/types/src/global-settings.ts:23)	default 0; keep the setting for users who want pacing
delay(300) before approval	WriteToFileTool.ts	remove
Blocking LSP diagnostics after save	saveDirectly tail	report asynchronously as a follow-up event
DiffView open/update/scroll choreography	default approval path	make the chat-diff (PREVENT_FOCUS_DISRUPTION) path the default

B — Per-step visibility + rollback

• B1 Automatic checkpoint per file write — extend the existing checkpoints shadow
  git so every successful write_to_file / edit_file / apply-patch records a checkpoint
  (today only user message sends do). Task start becomes a real, O(1) baseline — not a
  no-op, and not a worktree.
• B2 Per-task change journal — append-only JSONL under the task dir (one entry per
  file write: path, operation, checkpoint id, diff stats); torn-tail repair on load.
• B3 Per-step change cards + rollback — per-step change cards in the existing chat
  flow (reusing the unified diff + computeDiffStats already produced for approval) with
  "N files changed this step", and rollback to any checkpoint per file or per step.
  Auto-approval paths get the same cards after the fact — the user can always see and
  undo what the agent did.

Acceptance criteria

• No raw fs.writeFile / fs.appendFile in the workspace file-write path (all writes
  through the A4 atomic-publish helper; JSON state through safeWriteJson).
• Stale writes (file changed since this task's last read) fail loudly with the
  re-read-then-retry remediation, and the agent recovers automatically in the standard
  loop.
• A write to an existing file the task never read fails (createIfAbsent conflict) and
  the model recovers by reading first.
• Every successful file write produces a rollback-able checkpoint and a journal entry;
  the user can view each step's diff and roll back per step or per file.
• Concurrent subtasks writing the same file: exactly one wins, the others receive stale
  errors — deterministic, no corruption, no lost writes.
• Two-window regression: concurrent MCP settings initialization never truncates
  mcp_settings.json (MCP settings wiped when multiple windows open — race in McpHub.getMcpSettingsFilePath() direct fs.writeFile #1371).
• Abandoned-subtask regression: in-flight saves cannot re-attach an abandoned subtask
  (fix(task): guard saveClineMessages against abandoned tasks to prevent race in abandonSubtask #1021).
• Truncated tool-call regression: a cut-off write_to_file content argument is not
  written to disk; the tool call errors instead (Truncated tool-call arguments can be silently written to disk (stale partial-parse nativeArgs reused on finalization failure) #1221).
• Added guard latency < 50 ms p95 on a local volume (stat + rename only; no artificial
  delays on the default path).
• ESLint suppression counts do not increase; narrow Vitest suites for A and B pass.

Related PRs

Open (head: easonLiangWorldedtech's fork, base main):

PR	Scope
#1380	A5 — #1371: atomic mcp_settings.json stub creation via safeWriteJson + merge under the advisory lock
#1381	Speed: DEFAULT_WRITE_DELAY_MS 1000 → 0, and the delay(300) before scrollToFirstDiff removed
#1382	A5 — #1021: guard saveClineMessages against abandoned tasks (minimal main form of commit 1d1eb91)

Adjacent PRs to track (open on main):

• feat(task-scheduler): enable concurrent delegated task fan-out #1046 — concurrent delegated task fan-out: increases concurrent writers, so the A3 guards become mandatory once it lands.
• [Fix] Task history disappears when user reopens a task #1319 — task-history safe-write rename-window retry + snapshot merge under the advisory lock: overlaps A5's internal-state scope; do not double-fix.
• feat(dashboard): add local usage statistics dashboard with session detail #1225 — usage stats dashboard: original home of the fix(task): guard saveClineMessages against abandoned tasks to prevent race in abandonSubtask #1021 fix commit (1d1eb91).
• fix(write-to-file): address partial filesystem error review #1066 — write_to_file partial filesystem error handling: the A6/Truncated tool-call arguments can be silently written to disk (stale partial-parse nativeArgs reused on finalization failure) #1221 parser fix should be stacked after it (same author, same code area).

Out of scope

• Shell-tool writes (ExecuteCommandTool).
• Cross-process workspace locking — the version token is the cross-process mechanism.
• Replacing the existing diff-editor approval UX: it is preserved; B adds after-the-fact
  visibility.
• Truncated tool-call arguments can be silently written to disk (stale partial-parse nativeArgs reused on finalization failure) #1221 is tracked here but implemented as its own story (parser layer).
• Worktrees remain a user-initiated feature; the agent flow uses checkpoints, not
  worktrees.