Skip to content

Commit 8db3cab

Browse files
committed
fix(persistence): preserve committed backups and recover history on reads
1 parent 2d8fe7f commit 8db3cab

21 files changed

Lines changed: 643 additions & 213 deletions

‎.github/workflows/e2e.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,7 @@ jobs:
165165
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
166166
with:
167167
name: restart-persistence-failure
168+
retention-days: 7
168169
path: apps/vscode-e2e/test-failures/
169170
if-no-files-found: ignore
170171

‎apps/vscode-e2e/src/restart/scenarioWorkspace.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ const FAILURE_ARTIFACTS_DIR = "test-failures"
6464
* directory inside the checkout, then removes the temporary scenario root.
6565
* CI uploads that directory as a run artifact, so the failure that used to be
6666
* deleted in the cleanup path stays inspectable: phase results, VS Code logs,
67-
* and the extension's global storage with the task files.
67+
* and the extension's task files. Global state databases are excluded.
6868
*
6969
* The directory is keyed by the unique scenario root name and cleared before
7070
* copying, so retried runs cannot mix artifacts from different failures.
@@ -92,8 +92,14 @@ export async function preserveScenarioWorkspace(scenarioWorkspace: ScenarioWorks
9292
},
9393
{
9494
label: "task files",
95-
source: path.join(scenarioWorkspace.userData, "User", "globalStorage"),
96-
destination: path.join(destinationRoot, "global-storage"),
95+
source: path.join(
96+
scenarioWorkspace.userData,
97+
"User",
98+
"globalStorage",
99+
"zoocodeorganization.zoo-code",
100+
"tasks",
101+
),
102+
destination: path.join(destinationRoot, "tasks"),
97103
},
98104
]
99105

‎apps/vscode-e2e/src/restart/vscodeCoordinator.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@ function phaseEnvironment(options: RestartCoordinatorOptions, phase: RestartPhas
2727
E2E_PHASE: phase,
2828
E2E_SCENARIO: options.scenario,
2929
E2E_RESULTS_DIR: options.workspace.results,
30+
E2E_GLOBAL_STORAGE_PATH: path.join(
31+
options.workspace.userData,
32+
"User",
33+
"globalStorage",
34+
"zoocodeorganization.zoo-code",
35+
),
3036
}
3137
}
3238

‎apps/vscode-e2e/src/suite/restart-persistence.test.ts‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import * as assert from "assert"
2+
import * as fs from "fs/promises"
3+
import * as path from "path"
24
import * as vscode from "vscode"
35

46
import { RooCodeEventName, type RooCodeAPI } from "@roo-code/types"
@@ -60,6 +62,28 @@ async function runCreate(api: RooCodeAPI): Promise<void> {
6062
// never reads a task directory whose final write has not landed yet.
6163
const createdTaskId: string = taskId
6264
await waitFor(() => api.hasTaskUiMessageText(createdTaskId, MARKER))
65+
const globalStoragePath = process.env.E2E_GLOBAL_STORAGE_PATH
66+
if (!globalStoragePath) throw new Error("E2E_GLOBAL_STORAGE_PATH is required")
67+
// The public history API reads the cache; check the committed file
68+
// before quitting so the fresh host has both history and messages.
69+
await waitFor(async () => {
70+
try {
71+
const persisted: unknown = JSON.parse(
72+
await fs.readFile(
73+
path.join(globalStoragePath, "tasks", createdTaskId, "history_item.json"),
74+
"utf8",
75+
),
76+
)
77+
return (
78+
typeof persisted === "object" &&
79+
persisted !== null &&
80+
"id" in persisted &&
81+
persisted.id === createdTaskId
82+
)
83+
} catch {
84+
return false
85+
}
86+
})
6387

6488
const result: PhaseResult = {
6589
version: PHASE_RESULT_VERSION,
@@ -103,7 +127,31 @@ async function runVerify(api: RooCodeAPI): Promise<void> {
103127
const historyItem = await api.getTaskHistoryItem(taskId)
104128
assert.ok(historyItem, "Task history item should be available after restart")
105129
assert.ok(historyItem.task.includes("RESTART_PERSISTENCE_SMOKE"), "History title should persist after restart")
130+
131+
// No task is running in this fresh host yet. Recreate the on-disk
132+
// state left by an interrupted two-step replacement, then require
133+
// public reads to recover it before resume can write anything.
134+
const globalStoragePath = process.env.E2E_GLOBAL_STORAGE_PATH
135+
if (!globalStoragePath) throw new Error("E2E_GLOBAL_STORAGE_PATH is required")
136+
const taskDir = path.join(globalStoragePath, "tasks", taskId)
137+
const interruptedFiles = []
138+
for (const file of ["ui_messages.json", "api_conversation_history.json"]) {
139+
const canonical = path.join(taskDir, file)
140+
const backup = path.join(taskDir, `.${file}.bak_restart_e2e.tmp`)
141+
const committed = await fs.readFile(canonical, "utf8")
142+
await fs.rename(canonical, backup)
143+
interruptedFiles.push({ canonical, backup, committed })
144+
}
145+
assert.strictEqual(await api.hasTaskUiMessageText(taskId, MARKER), true, "Read should recover the UI marker")
106146
await waitForMarkedCompletion(api, taskId)
147+
for (const { canonical, backup, committed } of interruptedFiles) {
148+
assert.strictEqual(
149+
await fs.readFile(canonical, "utf8"),
150+
committed,
151+
"Read recovery must retain committed bytes",
152+
)
153+
await assert.rejects(fs.access(backup), { code: "ENOENT" }, "Recovery should consume the backup")
154+
}
107155

108156
await api.resumeTask(taskId)
109157
await waitFor(() => taskMessages.some(({ type, ask }) => type === "ask" && ask === "resume_completed_task"))
@@ -137,7 +185,7 @@ async function runVerify(api: RooCodeAPI): Promise<void> {
137185
}
138186

139187
suite("Restart persistence", () => {
140-
test("persists completed task across a fresh extension host", async () => {
188+
test("persists and recovers completed task history across a fresh extension host", async () => {
141189
const api = globalThis.api
142190
if (process.env.E2E_PHASE === "create") {
143191
await runCreate(api)
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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.

‎src/core/task-persistence/TaskHistoryStore.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { historyItemSchema, type HistoryItem } from "@roo-code/types"
88

99
import { GlobalFileNames } from "../../shared/globalFileNames"
1010
import { LOCK_STALE_MS, withFileLock } from "../../utils/fileLock"
11-
import { safeWriteJson } from "../../utils/safeWriteJson"
11+
import { safeWriteJson, removeJsonBackups } from "../../utils/safeWriteJson"
1212
import { getStorageBasePath } from "../../utils/storage"
1313
import { assertValidTransition, settleRejectedCreateSubtaskAction, type HistoryItemStatus } from "./taskLifecycle"
1414
import { computeHistoryDelta, DeltaRejectedError, mergeHistoryDelta } from "./taskStoreConcurrency"
@@ -280,7 +280,10 @@ export class TaskHistoryStore {
280280
// Remove per-task file (best-effort)
281281
try {
282282
const filePath = await this.getTaskFilePath(taskId)
283-
await withFileLock(filePath, (absoluteFilePath) => fs.unlink(absoluteFilePath))
283+
await withFileLock(filePath, async (absoluteFilePath) => {
284+
await removeJsonBackups(absoluteFilePath)
285+
await fs.unlink(absoluteFilePath)
286+
})
284287
} catch {
285288
// File may already be deleted
286289
}
@@ -308,7 +311,10 @@ export class TaskHistoryStore {
308311
// Remove per-task file (best-effort)
309312
try {
310313
const filePath = await this.getTaskFilePath(taskId)
311-
await withFileLock(filePath, (absoluteFilePath) => fs.unlink(absoluteFilePath))
314+
await withFileLock(filePath, async (absoluteFilePath) => {
315+
await removeJsonBackups(absoluteFilePath)
316+
await fs.unlink(absoluteFilePath)
317+
})
312318
} catch {
313319
// File may already be deleted
314320
}

‎src/core/task-persistence/__tests__/TaskHistoryStore.crossInstance.spec.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ vi.mock("../../../utils/storage", () => ({
1616
}))
1717

1818
// Mock safeWriteJson to use plain fs writes but honor the merge callback.
19-
vi.mock("../../../utils/safeWriteJson", () => ({
19+
vi.mock("../../../utils/safeWriteJson", async (importOriginal) => ({
20+
...(await importOriginal<typeof import("../../../utils/safeWriteJson")>()),
2021
safeWriteJson: vi
2122
.fn()
2223
.mockImplementation(

‎src/core/task-persistence/__tests__/TaskHistoryStore.realConcurrency.spec.ts‎

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -292,32 +292,40 @@ describe("TaskHistoryStore real cross-host locking", () => {
292292
}
293293
})
294294

295-
it("does not recreate a task deleted by another host before settlement", async () => {
296-
const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), "task-history-deleted-settlement-"))
297-
const storeA = new TaskHistoryStore(storagePath)
298-
const storeB = new TaskHistoryStore(storagePath)
299-
const actionA = createAction("action-a", "action A")
300-
301-
try {
302-
await storeA.initialize()
303-
await storeA.upsert({ ...item("shared-task"), pendingAction: actionA })
304-
await storeB.initialize()
305-
306-
await storeB.delete("shared-task")
307-
expect(storeA.get("shared-task")?.pendingAction).toEqual(actionA)
308-
309-
await expect(storeA.clearPendingActionIfMatching("shared-task", actionA.actionId)).rejects.toThrow(
310-
"task shared-task not found",
311-
)
312-
expect(storeA.get("shared-task")).toBeUndefined()
313-
await storeB.invalidate("shared-task")
314-
expect(storeB.get("shared-task")).toBeUndefined()
315-
} finally {
316-
storeA.dispose()
317-
storeB.dispose()
318-
await fs.rm(storagePath, { recursive: true, force: true })
319-
}
320-
})
295+
it.each(["delete", "deleteMany"] as const)(
296+
"does not resurrect a backup after %s before settlement",
297+
async (method) => {
298+
const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), "task-history-deleted-settlement-"))
299+
const storeA = new TaskHistoryStore(storagePath)
300+
const storeB = new TaskHistoryStore(storagePath)
301+
const actionA = createAction("action-a", "action A")
302+
303+
try {
304+
await storeA.initialize()
305+
await storeA.upsert({ ...item("shared-task"), pendingAction: actionA })
306+
await storeB.initialize()
307+
308+
const canonical = path.join(storagePath, "tasks", "shared-task", "history_item.json")
309+
const backup = path.join(path.dirname(canonical), ".history_item.json.bak_1_test.tmp")
310+
await fs.copyFile(canonical, backup)
311+
if (method === "delete") await storeB.delete("shared-task")
312+
else await storeB.deleteMany(["shared-task"])
313+
await expect(fs.access(backup)).rejects.toMatchObject({ code: "ENOENT" })
314+
expect(storeA.get("shared-task")?.pendingAction).toEqual(actionA)
315+
316+
await expect(storeA.clearPendingActionIfMatching("shared-task", actionA.actionId)).rejects.toThrow(
317+
"task shared-task not found",
318+
)
319+
expect(storeA.get("shared-task")).toBeUndefined()
320+
await storeB.invalidate("shared-task")
321+
expect(storeB.get("shared-task")).toBeUndefined()
322+
} finally {
323+
storeA.dispose()
324+
storeB.dispose()
325+
await fs.rm(storagePath, { recursive: true, force: true })
326+
}
327+
},
328+
)
321329

322330
it("serializes deletion after settlement reads disk without recreating the record", async () => {
323331
const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), "task-history-delete-during-settlement-"))

0 commit comments

Comments
 (0)