|
| 1 | +# JSON persistence audit for PR #2136 |
| 2 | + |
| 3 | +This is a source audit of the working tree, not a claim of power-loss durability or exhaustive filesystem fault testing. There are 19 executable `safeWriteJson` calls in 10 consumer files; the earlier review's count of 11 sibling callers did not identify its counting unit. Tests, the writer declaration, and the built-in command's textual example are excluded. |
| 4 | + |
| 5 | +## Shared contract |
| 6 | + |
| 7 | +Every call acquires the canonical file's advisory lock before recovery, merge, streaming, or replacement. Recovery only interprets ENOENT as absence. A failed restore or rollback retains committed backups. No fsync or durability option remains; replacement protects against process interruption, not arbitrary power loss. Read recovery checks for a matching backup before acquiring the same lock and rechecks the filesystem under it. |
| 8 | + |
| 9 | +All rejected recovery attempts, including read-side lock acquisition and directory inspection failures, emit `json-recovery-failed` with the canonical path, process ID, timestamp, and error code through the shared persistence trace sink. UI-message writes additionally retain their task-specific stage callbacks. Sink exceptions cannot replace the filesystem error. This trace does not log file contents. Best-effort leftover-unlink failures still use the existing console error logging and do not reject an otherwise successful recovery. |
| 10 | + |
| 11 | +A fresh-looking lock left by SIGKILL still rejects a writer or a reader attempting backup recovery with ELOCKED after the configured retries. This is intentional: lock freshness cannot distinguish a dead process from a paused owner. The subprocess test verifies rejection, backup preservation, and recovery after aging the lock past `LOCK_STALE_MS` (31 seconds). It does not wait 31 real seconds or establish Windows filesystem semantics. |
| 12 | + |
| 13 | +## Consumer inventory |
| 14 | + |
| 15 | +Paths in this table are relative to `src/`. |
| 16 | + |
| 17 | +| Consumer | Calls | Data and semantics | Error/read behavior | |
| 18 | +| ---------------------------------------------- | ----: | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 19 | +| `api/providers/fetchers/modelEndpointCache.ts` | 1 | Replace fetched endpoint cache | Disk reader checks existence; cache can be refetched. Writer rejection propagates to cache refresh handling. | |
| 20 | +| `api/providers/fetchers/modelCache.ts` | 1 | Replace fetched model cache | Includes a synchronous disk reader; missing cache can be refetched. Refresh paths catch/log write failures. | |
| 21 | +| `services/mcp/McpHub.ts` | 4 | Create global settings with a preserving merge; replace settings for updates, removal, and tool configuration | Creation preserves recovered settings. Other operations read before entering the writer's lock; their entire read-modify-write is not made atomic by this PR. | |
| 22 | +| `services/code-index/cache-manager.ts` | 2 | Save or clear file hashes | Initialization uses VS Code filesystem reads and resets a missing cache; writes catch/log and emit telemetry. Hashes are rebuildable. | |
| 23 | +| `core/config/importExport.ts` | 1 | Replace a user-selected settings export | Export catches/logs failures. Import reads the selected canonical file directly. | |
| 24 | +| `core/webview/webviewMessageHandler.ts` | 1 | Initialize project MCP settings when the canonical file appears absent | Uses an existence check and blind default write. An orphaned backup can be restored and then replaced by defaults. This is a remaining initialization gap, not covered by task-message recovery tests. | |
| 25 | +| `core/task-persistence/taskMessages.ts` | 1 | Save UI messages; optional snapshot merge | Reads use missing-file retry and backup recovery. Save failures propagate to Task, whose existing save helper catches them. Adds task-specific write traces. | |
| 26 | +| `core/task-persistence/apiMessages.ts` | 2 | Migrate legacy history with merge; save API messages with optional merge | Current and legacy readers use recovery. Genuine absence maps to no history; other I/O failures throw. Migration removes the legacy source only after the write succeeds. | |
| 27 | +| `core/task-persistence/TaskHistoryStore.ts` | 5 | Repair intent; legacy migration; history delta merge; authoritative replacement; conditional pending-action settlement | Deletion removes backups under the same file lock. Settlement rejects missing disk state. Store history reads and repair-intent reads still read canonical paths directly: orphaned history/intent backups are healed on writes, not on these readers. | |
| 28 | +| `core/context-tracking/FileContextTracker.ts` | 1 | Replace task file-context metadata | Reads check canonical existence and otherwise return an empty context. Saves catch/log failures. Read-side backup healing is not provided here. | |
| 29 | + |
| 30 | +`ClineProvider.getTaskWithId` is an additional API-history reader, not a writer. It now uses the recovery reader. SyntaxError and ENOENT retain their previous empty-history behavior; other filesystem/recovery failures propagate. Task loading and parent reopening also use the message readers. The advisory-file-lock owners are the JSON writer/recovery and history deletion; the inspected call paths do not invoke message recovery while already holding the same file lock. Provider delegation locks and store host mutexes are distinct from that file lock. |
| 31 | + |
| 32 | +## Writes outside the shared protocol |
| 33 | + |
| 34 | +The production source scan covered `src/`, `packages/`, and `apps/cli`, excluding tests, generated output, dependencies, and fixtures. These paths do not acquire protection merely because other writes use `safeWriteJson`: |
| 35 | + |
| 36 | +- Task-history import copies files into a unique staging directory, validates `history_item.json`, and promotes the directory by rename. It does not rewrite existing canonical message files through the JSON writer. Its directory-level publication protocol is separate. |
| 37 | +- TaskHistoryStore also renames repair intents into quarantine and unlinks completed intents. These are removal/quarantine operations, not JSON replacements. |
| 38 | +- `services/marketplace/SimpleInstaller.ts` writes and removes MCP entries with direct JSON file writes to project/global MCP settings. It can share files with McpHub and is outside its advisory-lock protocol. Concurrent marketplace/McpHub updates and interruption safety need separate work. |
| 39 | +- Qwen credential refresh writes its credentials JSON directly. The CLI's VS Code shim writes Memento and SecretStorage JSON synchronously. None of these writes gains crash recovery from this PR. |
| 40 | +- Other direct writes found are workspace edits, generated images, YAML modes and settings migration, rule/skill installation, exported markdown, logs, shell scripts, terminal artifacts, managed-binary staging, build output, and test/coverage tooling. The scan found no additional direct production replacement of `ui_messages.json`, `api_conversation_history.json`, or `history_item.json` outside task-history import's staging protocol. |
| 41 | + |
| 42 | +## Validation and limits |
| 43 | + |
| 44 | +Focused tests cover failed recovery/rollback, filesystem errors, backup ordering, neighboring files, missing-file reads, fresh-lock rejection, stale-lock takeover, trace delivery, and history deletion. The existing real-window restart E2E additionally moves UI/API histories to orphaned backups in a fresh extension host before resume and requires public reads to restore their exact bytes. |
| 45 | + |
| 46 | +The E2E runner and CI workflow inspected run VS Code on Linux. That is real extension-host/window coverage, not evidence for Windows open-handle rename behavior. The Windows EPERM branch is fault-injected in unit/subprocess tests. The remaining reader and MCP-writer gaps above are explicitly outside the verified UI/API history contract. |
0 commit comments