Skip to content

Commit f330566

Browse files
fix(checkpoints): make the pending journal a hard prerequisite and keep the commit recoverable
Persistence Integrity (pre-merge check): checkpointSave caught and ignored a failed pre-checkpoint pending-marker write, so the Git checkpoint could commit without the durable marker that is supposed to survive a lost append. - The awaiting-checkpoint marker is now a hard prerequisite: when it cannot be written durably, the save is skipped (no commit) instead of running the checkpoint anyway. - After a commit the ready promotion is retried; when it still fails, the entries are appended directly and the awaiting marker stays as the recovery record. If neither can be written, checkpoints are disabled rather than reporting success with missing journal state. Test updated: a blocked checkpoint dir now asserts the save is skipped (saveCheckpoint not called) and that the failure is logged. checkpoint suite 61/61; eslint/tsc clean.
1 parent 5f503af commit f330566

2 files changed

Lines changed: 76 additions & 39 deletions

File tree

‎src/core/checkpoints/__tests__/checkpointJournal.test.ts‎

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -189,27 +189,22 @@ describe("checkpointSave change-journal wiring (B2)", () => {
189189
expect(await loadChanges(tmpStorageDir, TASK_ID)).toEqual([])
190190
})
191191

192-
it("logs and continues when the journal cannot be written (checkpoints stay enabled)", async () => {
193-
// Block the per-task checkpoint dir so the journal mkdir/append fails.
192+
it("skips the checkpoint when the pending marker cannot be written durably", async () => {
193+
// Block the per-task checkpoint dir so the pending-marker mkdir/write fails.
194194
const taskDir = path.join(tmpStorageDir, "tasks", TASK_ID)
195195
await fs.mkdir(taskDir, { recursive: true })
196196
await fs.writeFile(path.join(taskDir, "checkpoints"), "blocker")
197197

198198
const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
199199

200-
// The journal failure is swallowed (logged, not rethrown), so the
201-
// checkpoint result still resolves exactly as without journaling.
202-
await expect(checkpointSave(mockTask as Task, false, true, write)).resolves.toMatchObject({ commit: COMMIT })
203-
200+
// A committed checkpoint whose pending marker never landed could lose its journal
201+
// state, so the marker is a hard prerequisite: the save is skipped and no commit is
202+
// produced.
203+
await expect(checkpointSave(mockTask as Task, false, true, write)).resolves.toBeUndefined()
204+
expect(saveCheckpointSpy).not.toHaveBeenCalled()
204205
expect(mockTask.enableCheckpoints).toBe(true)
205-
// The pending-marker write (before the commit) and the journal append both fail;
206-
// neither failure propagates to the checkpoint error handler.
207-
expect(consoleErrorSpy).toHaveBeenCalledWith(
208-
expect.stringContaining("failed to record the pending change journal"),
209-
expect.anything(),
210-
)
211206
expect(consoleErrorSpy).toHaveBeenCalledWith(
212-
expect.stringContaining("failed to persist change journal entries"),
207+
expect.stringContaining("not running the checkpoint"),
213208
expect.anything(),
214209
)
215210
})

‎src/core/checkpoints/index.ts‎

Lines changed: 68 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import { DIFF_VIEW_URI_SCHEME } from "../../integrations/editor/DiffViewProvider
1616

1717
import { CheckpointServiceOptions, RepoPerTaskCheckpointService } from "../../services/checkpoints"
1818

19-
import { clearPendingJournal, reconcilePendingJournal, writePendingJournal } from "./changeJournal"
19+
import { appendChange, clearPendingJournal, reconcilePendingJournal, writePendingJournal } from "./changeJournal"
2020

2121
const WARNING_THRESHOLD_MS = 5000
2222

@@ -256,19 +256,25 @@ export async function checkpointSave(
256256

257257
const writes = write ? (Array.isArray(write) ? write : [write]) : []
258258
const globalStorageDir = task.providerRef.deref()?.context.globalStorageUri.fsPath
259+
const journalStorageDir = writes.length > 0 ? globalStorageDir : undefined
259260

260-
// B2: the checkpoint and its change-journal entries are one transaction. The
261-
// pending marker is recorded before the Git commit, promoted to the complete
262-
// entries as soon as the commit id is known, and folded into the journal by
263-
// reconcilePendingJournal. A crash or a failed append therefore leaves a
264-
// durable marker instead of a committed checkpoint with no journal state.
265-
if (writes.length > 0 && globalStorageDir) {
266-
await writePendingJournal(globalStorageDir, task.taskId, {
267-
state: "awaiting-checkpoint",
268-
createdAt: Date.now(),
269-
}).catch((err) => {
270-
console.error("[Task#checkpointSave] failed to record the pending change journal", err)
271-
})
261+
// B2: the checkpoint and its change-journal entries are one transaction. The pending
262+
// marker is recorded before the Git commit and is a hard prerequisite: a committed
263+
// checkpoint whose marker never landed could lose its journal state, so when the
264+
// marker cannot be written durably this save does not run at all.
265+
if (journalStorageDir !== undefined) {
266+
try {
267+
await writePendingJournal(journalStorageDir, task.taskId, {
268+
state: "awaiting-checkpoint",
269+
createdAt: Date.now(),
270+
})
271+
} catch (err) {
272+
console.error(
273+
"[Task#checkpointSave] not running the checkpoint: the pending change journal could not be recorded",
274+
err,
275+
)
276+
return
277+
}
272278
}
273279

274280
// Start the checkpoint process in the background.
@@ -278,29 +284,65 @@ export async function checkpointSave(
278284
// Only a real commit produces entries (an empty or failed save resolves
279285
// to undefined / rejects), and non-write checkpoint calls (e.g. the
280286
// task-start baseline) pass no `write` value at all.
281-
if (globalStorageDir && writes.length > 0) {
287+
if (journalStorageDir !== undefined) {
282288
if (result?.commit) {
283289
const entries = writes.map((w) => ({
284290
path: w.path,
285291
operation: w.operation,
286292
checkpointId: result.commit,
287293
...(w.diffStats ? { diffStats: w.diffStats } : {}),
288294
}))
289-
try {
290-
await writePendingJournal(globalStorageDir, task.taskId, {
291-
state: "ready",
292-
createdAt: Date.now(),
293-
entries,
294-
})
295-
// Appends in order, then clears the marker; idempotent if a
296-
// previous attempt already appended part of the entries.
297-
await reconcilePendingJournal(globalStorageDir, task.taskId)
298-
} catch (err) {
299-
console.error("[Task#checkpointSave] failed to persist change journal entries", err)
295+
// After the commit the entries must become recoverable. Retry the durable
296+
// 'ready' promotion; when it still fails, append the entries directly (the
297+
// earlier 'awaiting' marker stays as the recovery record for the next read).
298+
// Returning success with neither a ready marker nor appended entries would
299+
// recreate the committed-checkpoint-without-journal state.
300+
let promoted = false
301+
for (let attempt = 0; attempt < 2 && !promoted; attempt++) {
302+
try {
303+
await writePendingJournal(journalStorageDir, task.taskId, {
304+
state: "ready",
305+
createdAt: Date.now(),
306+
entries,
307+
})
308+
promoted = true
309+
} catch (promotionError) {
310+
console.error(
311+
"[Task#checkpointSave] failed to promote the pending change journal",
312+
promotionError,
313+
)
314+
}
315+
}
316+
if (promoted) {
317+
try {
318+
// Appends in order, then clears the marker; idempotent if a previous
319+
// attempt already appended part of the entries.
320+
await reconcilePendingJournal(journalStorageDir, task.taskId)
321+
} catch (reconcileError) {
322+
console.error(
323+
"[Task#checkpointSave] failed to reconcile the pending change journal",
324+
reconcileError,
325+
)
326+
}
327+
} else {
328+
try {
329+
for (const entry of entries) {
330+
await appendChange(journalStorageDir, task.taskId, entry)
331+
}
332+
await clearPendingJournal(journalStorageDir, task.taskId)
333+
} catch (appendError) {
334+
// No durable record could be written for a committed checkpoint: stop
335+
// producing checkpoints rather than continue with missing journal state.
336+
console.error(
337+
"[Task#checkpointSave] failed to persist change journal entries; disabling checkpoints",
338+
appendError,
339+
)
340+
task.enableCheckpoints = false
341+
}
300342
}
301343
} else {
302344
// No commit means no journal entry is claimable.
303-
await clearPendingJournal(globalStorageDir, task.taskId).catch(() => {})
345+
await clearPendingJournal(journalStorageDir, task.taskId).catch(() => {})
304346
}
305347
}
306348
return result

0 commit comments

Comments
 (0)