Skip to content

Commit 29765dc

Browse files
committed
fix: serialize history deletion with settlement and validate the locked record
Address PR #1726 review findings with minimal changes scoped to the new settlement writer. Deletion versus settlement (#1726 finding 1) - src/utils/fileLock.ts exports acquireFileLock and withFileLock. They use the exact advisory lock protocol that safeWriteJson uses, so one implementation owns the per-file lock. safeWriteJson acquires through acquireFileLock and keeps its write, backup, and release behavior. - TaskHistoryStore.delete and deleteMany unlink each history_item.json inside withFileLock. Cache eviction and write-through semantics stay identical to base. Lock ordering stays store lock first, then one per-file lock, matching the write path, so no path nests the file lock. - The real-filesystem race test pauses settlement inside its locked disk read, starts deletion from a second store, verifies the deletion stays blocked, releases settlement, and verifies the file stays deleted without resurrection. Locked-record validation (#1726 finding 3) - The settlement merge callback now validates the disk record with the canonical historyItemSchema and requires parsed.data.id === taskId. - Malformed or mismatched records evict the stale cache entry and fail settlement closed without rewriting the record. Missing-record eviction and error behavior stay unchanged. Gemini partial assertions (#1726 finding 2) - The request-unique tool-call ID test now asserts exactly one partial with name new_task and no arguments and exactly one partial with serialized empty arguments and no name, then keeps the shared-ID and cross-request uniqueness assertions. The pre-commit hook was skipped because the full-workspace eslint in this environment was killed for memory (exit 137). Targeted eslint --prune-suppressions --max-warnings=0 passed on every edited file with no suppression count increase, and CI runs the full lint. Validation: focused Vitest suites pass, tsc --noEmit passes, all seven bounded lifecycle model checkers pass, and full pnpm test passes (13 tasks, 488 files, 9021 tests).
1 parent 69f761b commit 29765dc

7 files changed

Lines changed: 297 additions & 44 deletions

File tree

‎docs/architecture/task-lifecycle-model.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ CI fails if either exact causal witness or violation class changes, a witness di
8383

8484
The known-unsafe witnesses currently compare exact shortest action sequences. This is intentionally simple and reviewable, but brittle to harmless action renames or serialization refactors. A causal partial-order comparator would reduce that brittleness but would add a second trace-equivalence protocol to maintain. Until that complexity is justified, update an exact witness only after confirming the terminal violation class and required causal ordering are unchanged.
8585

86-
`TaskHistoryStore.realConcurrency.spec.ts` complements the abstract interleavings with real-filesystem checks through the real `proper-lockfile` and filesystem rename path, including stale-settlement compare-and-clear. Restart recovery is covered by `Task.persistence.spec.ts`: it treats an interrupted task's pending `create_subtask` action as rejected, settles that exact action before replay, and a failed recovery write stops replay rather than creating another child. Broader VS Code E2E remains reserved for other restart and extension-host behavior.
86+
`TaskHistoryStore.realConcurrency.spec.ts` complements the abstract interleavings with real-filesystem checks through the real `proper-lockfile` and filesystem rename path, including stale-settlement compare-and-clear. History-file deletion serializes on the same per-file advisory lock as `safeWriteJson`, and the real-filesystem suite covers a deletion that targets the settlement read-to-commit window plus schema and task-ID validation of the locked disk record before settlement (#1726). Restart recovery is covered by `Task.persistence.spec.ts`: it treats an interrupted task's pending `create_subtask` action as rejected, settles that exact action before replay, and a failed recovery write stops replay rather than creating another child. Broader VS Code E2E remains reserved for other restart and extension-host behavior.
8787

8888
## Task cleanup protocol model
8989

‎src/api/providers/__tests__/gemini.spec.ts‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -352,12 +352,21 @@ describe("GeminiHandler", () => {
352352
]),
353353
)
354354
const chunks = await collectStream(handler.createMessage(systemPrompt, messages, metadata))
355-
const partialIds = chunks
355+
const partials = chunks
356356
.filter((chunk) => chunk.type === "tool_call_partial")
357-
.map((chunk) => (chunk as { id: string }).id)
357+
.map((chunk) => chunk as { id: string; name?: string; arguments?: string })
358358
// The handler emits one name partial and one arguments partial
359-
// for the synthesized call.
360-
expect(partialIds).toHaveLength(2)
359+
// for the synthesized call. Assert both semantic halves so a
360+
// duplicate name partial cannot satisfy the ID comparison.
361+
expect(partials).toHaveLength(2)
362+
expect(
363+
partials.filter(({ name, arguments: args }) => name === "new_task" && args === undefined),
364+
).toHaveLength(1)
365+
expect(
366+
partials.filter(({ name, arguments: args }) => name === undefined && args === "{}"),
367+
).toHaveLength(1)
368+
369+
const partialIds = partials.map(({ id }) => id)
361370
expect(new Set(partialIds).size).toBe(1)
362371
firstCallIds.push(partialIds[0])
363372
}

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

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,11 @@ import * as path from "path"
44
import crypto from "crypto"
55

66
import deepEqual from "fast-deep-equal"
7-
import type { HistoryItem } from "@roo-code/types"
7+
import { historyItemSchema, type HistoryItem } from "@roo-code/types"
88

99
import { GlobalFileNames } from "../../shared/globalFileNames"
10-
import { LOCK_STALE_MS, safeWriteJson } from "../../utils/safeWriteJson"
10+
import { LOCK_STALE_MS, withFileLock } from "../../utils/fileLock"
11+
import { safeWriteJson } from "../../utils/safeWriteJson"
1112
import { getStorageBasePath } from "../../utils/storage"
1213
import { assertValidTransition, settleRejectedCreateSubtaskAction, type HistoryItemStatus } from "./taskLifecycle"
1314
import { computeHistoryDelta, DeltaRejectedError, mergeHistoryDelta } from "./taskStoreConcurrency"
@@ -269,12 +270,25 @@ export class TaskHistoryStore {
269270
this.cache.delete(taskId)
270271
this.taskFileMtimes.delete(taskId)
271272

272-
// Remove per-task file (best-effort)
273+
// Remove per-task file (best-effort). The unlink runs under the
274+
// same per-file advisory lock that `safeWriteJson` holds, so a
275+
// deletion cannot interleave with another host's locked
276+
// read-modify-write (for example the settlement in
277+
// `clearPendingActionIfMatching`). Lock ordering stays store
278+
// lock first, then one per-file lock, matching the write path.
273279
try {
274280
const filePath = await this.getTaskFilePath(taskId)
275-
await fs.unlink(filePath)
281+
await withFileLock(filePath, async (absoluteFilePath) => {
282+
try {
283+
await fs.unlink(absoluteFilePath)
284+
} catch {
285+
// File may already be deleted
286+
}
287+
})
276288
} catch {
277-
// File may already be deleted
289+
// A missing task directory also proves the history file is
290+
// absent, so remaining failures keep the base best-effort
291+
// deletion semantics.
278292
}
279293

280294
// Call onWrite callback inside the lock for serialized write-through
@@ -293,11 +307,21 @@ export class TaskHistoryStore {
293307
this.cache.delete(taskId)
294308
this.taskFileMtimes.delete(taskId)
295309

310+
// Serialize each unlink with `safeWriteJson` under the same
311+
// per-file advisory lock. See `delete` for the lock order.
296312
try {
297313
const filePath = await this.getTaskFilePath(taskId)
298-
await fs.unlink(filePath)
314+
await withFileLock(filePath, async (absoluteFilePath) => {
315+
try {
316+
await fs.unlink(absoluteFilePath)
317+
} catch {
318+
// File may already be deleted
319+
}
320+
})
299321
} catch {
300-
// File may already be deleted
322+
// A missing task directory also proves the history file
323+
// is absent, so remaining failures keep the base
324+
// best-effort deletion semantics.
301325
}
302326
}
303327

@@ -1073,9 +1097,13 @@ export class TaskHistoryStore {
10731097
*
10741098
* Deletion by another host is authoritative (#1726): when no persisted
10751099
* record exists, the merge callback removes the stale cache entry and
1076-
* throws instead of writing the cached record back to disk.
1100+
* throws instead of writing the cached record back to disk. A persisted
1101+
* record must also match the canonical task-history schema and carry the
1102+
* requested task ID; malformed or mismatched records drop the stale
1103+
* cache entry and fail settlement closed without rewriting the record.
10771104
*
1078-
* @throws If the task ID is not present in the cache or no persisted record remains on disk.
1105+
* @throws If the task ID is not present in the cache, no persisted record remains on disk,
1106+
* or the persisted record is invalid or belongs to a different task ID.
10791107
*/
10801108
public async clearPendingActionIfMatching(taskId: string, expectedActionId: string): Promise<HistoryItem> {
10811109
return this.withLock(async () => {
@@ -1089,7 +1117,7 @@ export class TaskHistoryStore {
10891117
try {
10901118
await safeWriteJson(filePath, cached, {
10911119
merge: (existing) => {
1092-
if (!existing || typeof existing !== "object" || !("id" in existing)) {
1120+
if (existing === null || existing === undefined) {
10931121
// Writing the cached record back would recreate a task
10941122
// another host deleted, so drop the stale entry first.
10951123
// A throwing merge writes nothing, so the deleted
@@ -1101,6 +1129,27 @@ export class TaskHistoryStore {
11011129
`[TaskHistoryStore] clearPendingActionIfMatching: task ${taskId} not found in cache`,
11021130
)
11031131
}
1132+
// Validate the locked disk record with the canonical
1133+
// task-history schema (#1726). Settlement must not
1134+
// rewrite malformed data and must not clear the action
1135+
// on a record persisted under a different task ID, so
1136+
// both cases drop the stale cache entry and fail
1137+
// closed without touching the disk record.
1138+
const parsed = historyItemSchema.safeParse(existing)
1139+
if (!parsed.success) {
1140+
this.cache.delete(taskId)
1141+
this.taskFileMtimes.delete(taskId)
1142+
throw new Error(
1143+
`[TaskHistoryStore] clearPendingActionIfMatching: task ${taskId} has an invalid disk record`,
1144+
)
1145+
}
1146+
if (parsed.data.id !== taskId) {
1147+
this.cache.delete(taskId)
1148+
this.taskFileMtimes.delete(taskId)
1149+
throw new Error(
1150+
`[TaskHistoryStore] clearPendingActionIfMatching: task ${taskId} has a disk record with mismatched id ${parsed.data.id}`,
1151+
)
1152+
}
11041153
const disk = existing as HistoryItem
11051154
authoritative = settleRejectedCreateSubtaskAction(disk, expectedActionId)
11061155
return authoritative

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,69 @@ describe("TaskHistoryStore cross-instance safety", () => {
253253
expect(await fs.readFile(filePath, "utf8")).toBe("{invalid")
254254
})
255255

256+
it("fails settlement closed for a malformed disk record without rewriting it", async () => {
257+
const pendingAction = {
258+
kind: "create_subtask" as const,
259+
actionId: "action-a",
260+
approvalText: "{}",
261+
mode: "code",
262+
message: "action A",
263+
todos: [],
264+
}
265+
const cached = makeHistoryItem({ id: "malformed-settlement-task", pendingAction })
266+
const filePath = path.join(tmpDir, "tasks", cached.id, GlobalFileNames.historyItem)
267+
await fs.mkdir(path.dirname(filePath), { recursive: true })
268+
// Valid JSON that fails the canonical task-history schema: id must
269+
// be a string and the required history fields are absent.
270+
const malformed = JSON.stringify({ id: 123, pendingAction })
271+
await fs.writeFile(filePath, malformed, "utf8")
272+
const storeState = storeA as unknown as {
273+
cache: Map<string, HistoryItem>
274+
taskFileMtimes: Map<string, number>
275+
}
276+
storeState.cache.set(cached.id, cached)
277+
storeState.taskFileMtimes.set(cached.id, Date.now())
278+
279+
await expect(storeA.clearPendingActionIfMatching(cached.id, pendingAction.actionId)).rejects.toThrow(
280+
`task ${cached.id} has an invalid disk record`,
281+
)
282+
expect(storeA.get(cached.id)).toBeUndefined()
283+
expect(storeState.taskFileMtimes.has(cached.id)).toBe(false)
284+
// The malformed record stays on disk untouched.
285+
expect(await fs.readFile(filePath, "utf8")).toBe(malformed)
286+
})
287+
288+
it("fails settlement closed when the disk record carries a different task id", async () => {
289+
const pendingAction = {
290+
kind: "create_subtask" as const,
291+
actionId: "action-a",
292+
approvalText: "{}",
293+
mode: "code",
294+
message: "action A",
295+
todos: [],
296+
}
297+
const cached = makeHistoryItem({ id: "mismatch-settlement-task", pendingAction })
298+
const other = makeHistoryItem({ id: "other-task" })
299+
const filePath = path.join(tmpDir, "tasks", cached.id, GlobalFileNames.historyItem)
300+
await fs.mkdir(path.dirname(filePath), { recursive: true })
301+
const mismatched = JSON.stringify(other, null, "\t")
302+
await fs.writeFile(filePath, mismatched, "utf8")
303+
const storeState = storeA as unknown as {
304+
cache: Map<string, HistoryItem>
305+
taskFileMtimes: Map<string, number>
306+
}
307+
storeState.cache.set(cached.id, cached)
308+
storeState.taskFileMtimes.set(cached.id, Date.now())
309+
310+
await expect(storeA.clearPendingActionIfMatching(cached.id, pendingAction.actionId)).rejects.toThrow(
311+
`task ${cached.id} has a disk record with mismatched id other-task`,
312+
)
313+
expect(storeA.get(cached.id)).toBeUndefined()
314+
expect(storeState.taskFileMtimes.has(cached.id)).toBe(false)
315+
// The other task's record stays on disk untouched.
316+
expect(await fs.readFile(filePath, "utf8")).toBe(mismatched)
317+
})
318+
256319
/**
257320
* Host B completes a task on disk while host A's cache still has it
258321
* active. Host A's next save updates only totalCost (a full-object

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

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ import type { HistoryItem } from "@roo-code/types"
66

77
import { TaskHistoryStore } from "../TaskHistoryStore"
88

9+
// Wrap the real fs/promises so a test can pause inside the per-file lock
10+
// while every call still runs against the real filesystem.
11+
vi.mock("fs/promises", async () => {
12+
const actual = await vi.importActual<typeof import("fs/promises")>("fs/promises")
13+
return { ...actual, readFile: vi.fn(actual.readFile) }
14+
})
15+
916
type WriteTaskFile = (item: HistoryItem, delta?: Partial<HistoryItem>) => Promise<HistoryItem>
1017

1118
interface WriteBarrier {
@@ -312,6 +319,72 @@ describe("TaskHistoryStore real cross-host locking", () => {
312319
}
313320
})
314321

322+
it("serializes deletion after settlement reads disk without recreating the record", async () => {
323+
const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), "task-history-delete-during-settlement-"))
324+
const storeA = new TaskHistoryStore(storagePath)
325+
const storeB = new TaskHistoryStore(storagePath)
326+
const action = createAction("action-a", "action A")
327+
const filePath = path.join(storagePath, "tasks", "shared-task", "history_item.json")
328+
const actualFs = await vi.importActual<typeof import("fs/promises")>("fs/promises")
329+
let signalReadComplete!: () => void
330+
const readComplete = new Promise<void>((resolve) => {
331+
signalReadComplete = resolve
332+
})
333+
let releaseSettlement!: () => void
334+
const settlementCanContinue = new Promise<void>((resolve) => {
335+
releaseSettlement = resolve
336+
})
337+
338+
try {
339+
await storeA.initialize()
340+
await storeA.upsert({ ...item("shared-task"), pendingAction: action })
341+
await storeB.initialize()
342+
343+
// Pause settlement inside its locked disk read, then start a
344+
// deletion from another store so it targets the settlement's
345+
// read-to-commit window.
346+
vi.mocked(fs.readFile).mockImplementation(async (...args: Parameters<typeof fs.readFile>) => {
347+
const result = await actualFs.readFile(...args)
348+
if (args[0] === filePath) {
349+
signalReadComplete()
350+
await settlementCanContinue
351+
}
352+
return result
353+
})
354+
355+
const settlement = storeA.clearPendingActionIfMatching("shared-task", action.actionId)
356+
await readComplete
357+
const deletion = storeB.delete("shared-task")
358+
let deletionSettled = false
359+
void deletion.finally(() => {
360+
deletionSettled = true
361+
})
362+
await new Promise((resolve) => setTimeout(resolve, 25))
363+
// The deletion must stay blocked while settlement holds the
364+
// per-file lock across its read-to-commit window.
365+
expect(deletionSettled).toBe(false)
366+
367+
releaseSettlement()
368+
await expect(settlement).resolves.toMatchObject({ id: "shared-task", pendingAction: undefined })
369+
await deletion
370+
371+
// The settlement committed first and the locked deletion
372+
// removed the file afterwards, so the record stays deleted
373+
// instead of being resurrected.
374+
await expect(fs.access(filePath)).rejects.toMatchObject({ code: "ENOENT" })
375+
await expect(storeA.clearPendingActionIfMatching("shared-task", action.actionId)).rejects.toThrow(
376+
"task shared-task not found",
377+
)
378+
expect(storeA.get("shared-task")).toBeUndefined()
379+
expect(storeB.get("shared-task")).toBeUndefined()
380+
} finally {
381+
vi.mocked(fs.readFile).mockImplementation(actualFs.readFile)
382+
storeA.dispose()
383+
storeB.dispose()
384+
await fs.rm(storagePath, { recursive: true, force: true })
385+
}
386+
})
387+
315388
it("rejects settlement for a task absent from the cache without creating it", async () => {
316389
const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), "task-history-cache-miss-settlement-"))
317390
const store = new TaskHistoryStore(storagePath)

‎src/utils/fileLock.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
import * as path from "path"
2+
import * as lockfile from "proper-lockfile"
3+
4+
/**
5+
* Shared staleness window for per-file advisory locks. This module owns the
6+
* single advisory lock protocol used by `safeWriteJson` and by callers that
7+
* must serialize with it, such as task-history deletion.
8+
*/
9+
export const LOCK_STALE_MS = 31_000
10+
11+
/**
12+
* Acquire the advisory lock for one file path using the exact protocol
13+
* `safeWriteJson` uses, so operations that hold this lock serialize with
14+
* every `safeWriteJson` write to the same path. Callers must release the
15+
* returned function exactly once and must not acquire the same lock again
16+
* while holding it.
17+
*/
18+
export async function acquireFileLock(filePath: string): Promise<() => Promise<void>> {
19+
const absoluteFilePath = path.resolve(filePath)
20+
try {
21+
return await lockfile.lock(absoluteFilePath, {
22+
stale: LOCK_STALE_MS,
23+
update: 10000, // Update mtime every 10 seconds to prevent staleness if operation is long
24+
realpath: false, // the file may not exist yet, which is acceptable
25+
retries: {
26+
// Configuration for retrying lock acquisition
27+
retries: 5, // Number of retries after the initial attempt
28+
factor: 2, // Exponential backoff factor (e.g., 100ms, 200ms, 400ms, ...)
29+
minTimeout: 100, // Minimum time to wait before the first retry (in ms)
30+
maxTimeout: 1000, // Maximum time to wait for any single retry (in ms)
31+
},
32+
onCompromised: (err) => {
33+
console.error(`Lock at ${absoluteFilePath} was compromised:`, err)
34+
throw err
35+
},
36+
})
37+
} catch (lockError) {
38+
console.error(`Failed to acquire lock for ${absoluteFilePath}:`, lockError)
39+
throw lockError
40+
}
41+
}
42+
43+
/**
44+
* Run one operation while holding the advisory lock for a file path.
45+
* Callers must not acquire this lock again from inside `operation`, and
46+
* they must keep the documented lock order when combining this helper
47+
* with other locks to prevent deadlock.
48+
*/
49+
export async function withFileLock<T>(
50+
filePath: string,
51+
operation: (absoluteFilePath: string) => Promise<T>,
52+
): Promise<T> {
53+
const absoluteFilePath = path.resolve(filePath)
54+
const releaseLock = await acquireFileLock(absoluteFilePath)
55+
56+
let result: T
57+
try {
58+
result = await operation(absoluteFilePath)
59+
} catch (operationError) {
60+
// The operation error is the primary failure. Release without
61+
// reporting a secondary release error over it.
62+
try {
63+
await releaseLock()
64+
} catch (releaseError) {
65+
console.error(`Failed to release lock for ${absoluteFilePath}:`, releaseError)
66+
}
67+
throw operationError
68+
}
69+
70+
try {
71+
await releaseLock()
72+
} catch (releaseError) {
73+
// The operation already succeeded, so a release failure is only
74+
// logged, matching how `safeWriteJson` handles release failures.
75+
console.error(`Failed to release lock for ${absoluteFilePath}:`, releaseError)
76+
}
77+
return result
78+
}

0 commit comments

Comments
 (0)