Skip to content

Commit 58d5fa1

Browse files
fix(checkpoints): decline to publish a baseline a write overtook rather than record the write as the pre-task state
saveCheckpoint stages when it executes: stageAll captures whatever the workspace holds at that instant. The per-task queue orders a task-start baseline against the first per-write save, but ordering is not content, so a baseline still running when the first write lands committed the write bytes as the pre-task state, and the per-write save queued behind it then found nothing to commit. The baseline mislabelled the bytes and the write cost no record of its own; the pre-write content survived only in the initialization commit, which is not a checkpoint anything can restore to. Measured on 092a2e9 before this change: AssertionError: expected { Object (author, branch, ...) } to be undefined + Received: { "commit": "8a1766aad44abf7d6c7c8d34ab65fcb3f262b903", "summary": { "changes": 1, "deletions": 1, "insertions": 1 } } at src/core/checkpoints/__tests__/checkpointSaveContentPremise.spec.ts:180:20 expect(baseline).toBeUndefined() Of the two branches review thread 607pkQ names - preserve pre-write content, or avoid publishing a baseline - this takes the second: a baseline whose content premise is gone at staging time resolves with no commit and costs the shadow git nothing, and the write keeps its own record whose diff base is the content the task started with. The other branch is worse. Freezing what the baseline stages means capturing the workspace at request time, which is either a copy of it or a stage-and-write-tree at request time. Both do their expensive git work outside the very lock whose comment claims it makes late work safe, and they double the git work a baseline exists to bound. A copy can also catch a file mid-write, so it records a state that is neither pre-write nor post-write - it does not deliver pre-write content either - and it leaves the shadow git meaning two different things by what the workspace looked like. Declining costs the caller nothing it does not already handle: a resolve with no commit is how a dropped save is reported today, which is how the task-start baseline already treats it - by retrying on a later loop entry. A task-start baseline now carries a content premise - no agent write had happened when it was requested - and saveCheckpoint evaluates it immediately before stageAll, with no await between the check and the capture, so nothing this task does can slip in after the answer is taken. Per-write saves carry no premise: recording the workspace as it stands when the save runs is exactly what a per-write save is for. The existing assertion in checkpoint.test.ts that pins the baseline call shape now names the premise it gained, rather than being relaxed to an objectContaining.
1 parent 092a2e9 commit 58d5fa1

4 files changed

Lines changed: 243 additions & 3 deletions

File tree

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,9 +302,11 @@ describe("Checkpoint functionality", () => {
302302
const result = await savePromise
303303

304304
// saveCheckpoint should have been called
305+
// The baseline carries a content premise now: it describes the workspace before any agent
306+
// write, and saveCheckpoint declines to publish if a write landed before it staged.
305307
expect(mockCheckpointService.saveCheckpoint).toHaveBeenCalledWith(
306308
expect.stringContaining("Task: test-task-id"),
307-
{ allowEmpty: true, suppressMessage: false },
309+
{ allowEmpty: true, suppressMessage: false, contentPremise: expect.any(Function) },
308310
)
309311

310312
// Result should contain the commit hash
Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
// The in-flight half of review thread 607pkQ, against a real shadow git.
2+
//
3+
// 607pkQ asks that the in-flight baseline and any retry `preserve pre-write content or avoid
4+
// publishing a baseline`. The per-task queue in ./index.ts guarantees ordering; it cannot guarantee
5+
// content, because saveCheckpoint stages the workspace at the moment it executes. So a task-start
6+
// baseline that is still running when the first write lands commits that write as the pre-task state,
7+
// and the per-write save queued behind it then finds nothing to record. The baseline mislabels the
8+
// bytes and the write costs no record of its own.
9+
//
10+
// This file asserts the branch the fix takes: once a write has landed, the in-flight baseline declines
11+
// to publish at all - it resolves with no commit and costs the shadow git nothing - and the write
12+
// keeps its own record whose diff base is the content the task started with.
13+
import fs from "fs/promises"
14+
import os from "os"
15+
import path from "path"
16+
17+
import { simpleGit } from "simple-git"
18+
19+
import { RepoPerTaskCheckpointService } from "../../../services/checkpoints"
20+
import { BLOCKED_ENV_KEYS } from "../../../services/checkpoints/ShadowCheckpointService"
21+
22+
import { checkpointSave, getCheckpointService } from "../index"
23+
import type { Task } from "../../task/Task"
24+
25+
vi.mock("@roo-code/telemetry", () => ({
26+
TelemetryService: {
27+
instance: {
28+
captureCheckpointCreated: vi.fn(),
29+
captureCheckpointRestored: vi.fn(),
30+
captureCheckpointDiffed: vi.fn(),
31+
},
32+
},
33+
}))
34+
35+
const tmpDir = path.join(os.tmpdir(), "checkpointSaveContentPremise")
36+
const CHECKPOINTED_FILE = "checkpointed.txt"
37+
const PRE_WRITE = "content the task started with"
38+
const MID_FLIGHT_WRITE = "the write that landed mid-flight"
39+
40+
const savedEnv: Partial<Record<string, string>> = {}
41+
42+
beforeAll(() => {
43+
for (const key of BLOCKED_ENV_KEYS) {
44+
savedEnv[key] = process.env[key]
45+
delete process.env[key]
46+
}
47+
})
48+
49+
afterAll(async () => {
50+
for (const key of BLOCKED_ENV_KEYS) {
51+
if (savedEnv[key] !== undefined) {
52+
process.env[key] = savedEnv[key]
53+
} else {
54+
delete process.env[key]
55+
}
56+
}
57+
58+
await fs.rm(tmpDir, { recursive: true, force: true })
59+
}, 60_000)
60+
61+
type SaveArgs = Parameters<RepoPerTaskCheckpointService["saveCheckpoint"]>
62+
type SaveReturn = Awaited<ReturnType<RepoPerTaskCheckpointService["saveCheckpoint"]>>
63+
64+
/**
65+
* Hold the first execution of saveCheckpoint before it stages anything, and hand back the release.
66+
* The held call is real shadow-git work once released, so what it stages is whatever the workspace
67+
* holds when it is released - which is the property this case turns on. The hold stands for the git
68+
* work a task-start baseline takes while the request loop moves on to the first write.
69+
*/
70+
function holdFirstSave(service: RepoPerTaskCheckpointService, tag: string) {
71+
const real = service.saveCheckpoint.bind(service)
72+
const calls: Array<{ stage: "requested" | "running"; tag: string }> = []
73+
let release: () => void = () => {}
74+
const held = new Promise<void>((resolve) => {
75+
release = resolve
76+
})
77+
let ordinal = 0
78+
79+
service.saveCheckpoint = async (...args: SaveArgs): Promise<SaveReturn> => {
80+
const call = ordinal++
81+
// The held call is the baseline; anything after it is a save the baseline left behind, and the
82+
// list has to say which is which or the record below would be read against the wrong save.
83+
const label = call === 0 ? tag : "per-write"
84+
calls.push({ stage: "requested", tag: label })
85+
if (call === 0) {
86+
await held
87+
}
88+
calls.push({ stage: "running", tag: label })
89+
return real(...args)
90+
}
91+
92+
return { calls, release }
93+
}
94+
95+
async function commitCount(shadowDir: string, taskId: string): Promise<number> {
96+
const git = simpleGit(path.join(shadowDir, "tasks", taskId, "checkpoints"))
97+
const log = await git.log()
98+
return log.total
99+
}
100+
101+
async function recorded(service: RepoPerTaskCheckpointService, from: string, to: string) {
102+
const diffs = await service.getDiff({ from, to })
103+
const file = diffs.find((d) => d.paths.relative === CHECKPOINTED_FILE)
104+
return { count: diffs.length, before: file?.content.before, after: file?.content.after }
105+
}
106+
107+
type Setup = Awaited<ReturnType<typeof setupCheckpointTask>>
108+
109+
async function setupCheckpointTask(taskId: string): Promise<Setup> {
110+
const workspaceDir = path.join(tmpDir, `workspace-${taskId}`)
111+
const shadowDir = path.join(tmpDir, `storage-${taskId}`)
112+
await fs.mkdir(workspaceDir, { recursive: true })
113+
await fs.mkdir(shadowDir, { recursive: true })
114+
115+
const workspaceGit = simpleGit(workspaceDir)
116+
await workspaceGit.init()
117+
await workspaceGit.addConfig("user.name", "Roo Code")
118+
await workspaceGit.addConfig("user.email", "[email protected]")
119+
await workspaceGit.addConfig("commit.gpgSign", "false")
120+
await fs.writeFile(path.join(workspaceDir, CHECKPOINTED_FILE), PRE_WRITE)
121+
await workspaceGit.add(".")
122+
await workspaceGit.commit("record the workspace the task started with")
123+
124+
const task = {
125+
taskId,
126+
cwd: workspaceDir,
127+
enableCheckpoints: true,
128+
didEditFile: false,
129+
checkpointService: undefined as RepoPerTaskCheckpointService | undefined,
130+
checkpointServiceInitializing: false,
131+
checkpointTimeout: 30,
132+
abort: false,
133+
clineMessages: [] as never[],
134+
apiConversationHistory: [] as never[],
135+
say: vi.fn(async () => {}),
136+
providerRef: {
137+
deref: () => ({
138+
context: { globalStorageUri: { fsPath: shadowDir } },
139+
log: () => {},
140+
postMessageToWebview: vi.fn(),
141+
}),
142+
},
143+
} as unknown as Task
144+
145+
const service = await getCheckpointService(task)
146+
147+
if (!service) {
148+
throw new Error("no checkpoint service after initialization, so no shadow git exists to read")
149+
}
150+
151+
return { task, service, workspaceGit, shadowDir, baseHash: service.baseHash }
152+
}
153+
154+
describe("checkpointSave against a write that lands while the task-start baseline is in flight", () => {
155+
it("the baseline declines rather than publishing the write, and the write keeps its own record", async () => {
156+
const { task, service, shadowDir, baseHash } = await setupCheckpointTask("baseline-declines-after-a-write")
157+
const checkpointedFile = path.join(service.workspaceDir, CHECKPOINTED_FILE)
158+
159+
// The shadow git was initialized from the workspace while it still held the pre-write content, so
160+
// that content is already recorded and the pair below can be read against it.
161+
const beforeBaseline = await commitCount(shadowDir, task.taskId)
162+
163+
const { calls, release } = holdFirstSave(service, "baseline")
164+
// Requested while no agent write has happened: this save describes the workspace before the write.
165+
const baselinePromise = checkpointSave(task, true, true)
166+
await new Promise((resolve) => setTimeout(resolve, 25))
167+
expect(calls).toEqual([{ stage: "requested", tag: "baseline" }])
168+
169+
// The write the thread names, landing while the baseline is still running: the bytes on disk, and
170+
// the flag every agent write path sets on the task.
171+
await fs.writeFile(checkpointedFile, MID_FLIGHT_WRITE)
172+
task.didEditFile = true
173+
release()
174+
175+
const baseline = await baselinePromise
176+
const afterBaseline = await commitCount(shadowDir, task.taskId)
177+
178+
// The baseline must not publish. It cannot record the state it was asked about, so it records
179+
// nothing, which is what the caller already treats as "no baseline yet" and retries against.
180+
expect(baseline).toBeUndefined()
181+
expect(afterBaseline).toBe(beforeBaseline)
182+
183+
// The write then gets the record the drifted baseline would have swallowed: its own save, whose
184+
// diff base is the content the task started with.
185+
const writeSave = await checkpointSave(task, false, true)
186+
if (!writeSave || typeof writeSave !== "object" || !("commit" in writeSave) || typeof writeSave.commit !== "string") {
187+
throw new Error("the per-write save resolved with no commit, so the write has no record")
188+
}
189+
const writeCommit = writeSave.commit
190+
const record = await recorded(service, baseHash!, writeCommit)
191+
const afterWrite = await commitCount(shadowDir, task.taskId)
192+
193+
// Both saves reached the shadow git and only one of them committed: the baseline was declined
194+
// at staging time and the write ran as its own save, in that order, because the queue held it there.
195+
expect(calls).toEqual([
196+
{ stage: "requested", tag: "baseline" },
197+
{ stage: "running", tag: "baseline" },
198+
{ stage: "requested", tag: "per-write" },
199+
{ stage: "running", tag: "per-write" },
200+
])
201+
expect(record.count).toBe(1)
202+
expect(record.before).toBe(PRE_WRITE)
203+
expect(record.after).toBe(MID_FLIGHT_WRITE)
204+
expect(afterWrite).toBe(beforeBaseline + 1)
205+
}, 60_000)
206+
})

‎src/core/checkpoints/index.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -344,10 +344,31 @@ export async function checkpointSave(task: Task, force = false, suppressMessage
344344
// reported to the caller the same way a missing service is (a resolve with no commit), which is
345345
// how the task-start baseline already treats it - by retrying on a later loop entry.
346346
const timeoutSeconds = task.checkpointTimeout > 0 ? task.checkpointTimeout : DEFAULT_CHECKPOINT_TIMEOUT_SECONDS
347+
// A task-start baseline describes the workspace before any agent write: it is the rollback point for
348+
// the first write of the request loop. The queue orders this save behind whatever is already running,
349+
// but ordering is not content - saveCheckpoint stages when it executes - so a baseline that is still
350+
// running when the first write lands would commit the write bytes as the pre-task state, and the
351+
// per-write save queued behind it would then find nothing to commit. The branch taken here is to
352+
// decline to publish. The other branch the ask names - freezing what the baseline stages, by copying
353+
// the workspace at request time or by staging and writing a tree then - is worse: either does its
354+
// expensive git work outside the very lock whose comment claims it makes late work safe, a copy can
355+
// catch a file half-written and so records a state that is neither pre-write nor post-write, and it
356+
// would leave the shadow git meaning two different things by what the workspace looked like. A
357+
// declined baseline costs the caller nothing it does not already handle: a resolve with no commit is
358+
// how a dropped save is reported today, which is how the task-start baseline already treats it - by
359+
// retrying on a later loop entry. The content the task started with stays recorded in the
360+
// initialization commit, and the write keeps a record of its own whose diff base is that content.
361+
// Per-write saves carry no premise, because recording the workspace as it stands when the save runs
362+
// is exactly what a per-write save is for.
363+
const requestedBeforeAnyWrite = force && !task.didEditFile
347364
return enqueueCheckpointWork(
348365
task.taskId,
349366
() =>
350-
service.saveCheckpoint(`Task: ${task.taskId}, Time: ${Date.now()}`, { allowEmpty: force, suppressMessage }),
367+
service.saveCheckpoint(`Task: ${task.taskId}, Time: ${Date.now()}`, {
368+
allowEmpty: force,
369+
suppressMessage,
370+
contentPremise: requestedBeforeAnyWrite ? () => !task.didEditFile : undefined,
371+
}),
351372
{
352373
label: force ? "queued task-start checkpoint baseline" : "queued per-write checkpoint save",
353374
expiresAt: Date.now() + Math.max(1, timeoutSeconds * 1000),

‎src/services/checkpoints/ShadowCheckpointService.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -330,7 +330,7 @@ export abstract class ShadowCheckpointService extends EventEmitter {
330330

331331
public async saveCheckpoint(
332332
message: string,
333-
options?: { allowEmpty?: boolean; suppressMessage?: boolean },
333+
options?: { allowEmpty?: boolean; suppressMessage?: boolean; contentPremise?: () => boolean }
334334
): Promise<CheckpointResult | undefined> {
335335
try {
336336
this.log(
@@ -341,6 +341,17 @@ export abstract class ShadowCheckpointService extends EventEmitter {
341341
throw new Error("Shadow git repo not initialized")
342342
}
343343

344+
// Content, not only ordering: stageAll captures whatever the workspace holds at this instant,
345+
// so a premise that no longer holds means this save would record a state its caller never asked
346+
// about. The answer is taken here, immediately before the capture, with no await between the two,
347+
// so nothing else this task does can slip in after the premise is checked.
348+
if (options?.contentPremise && !options.contentPremise()) {
349+
this.log(
350+
`[${this.constructor.name}#saveCheckpoint] dropping the save: its content premise no longer holds at staging time, so nothing was committed`,
351+
)
352+
return undefined
353+
}
354+
344355
const startTime = Date.now()
345356
await this.stageAll(this.git)
346357
const commitArgs = options?.allowEmpty ? { "--allow-empty": null } : undefined

0 commit comments

Comments
 (0)