Skip to content

Commit 075adc7

Browse files
committed
fix(checkpoints): review follow-ups T1-T3 (journal tail, baseline guard, ignored-path rollback)
T1: appendChanges now rejects a malformed final record even when it kept its newline (same hazard as the unterminated tail: accepting it demotes it to a skipped middle line and reports an incomplete history as valid). T2: the task-start baseline block is wrapped in try/catch - a rejected state lookup or checkpoint error is logged and no longer aborts task startup. T3: shadow-repo-excluded paths never enter the change journal (skip-when- journaling) and restoreFile's delete branch refuses an excluded target with an explicit error instead of fs.rm (covers journals written before the fix). New ShadowCheckpointService#isPathIgnored uses check-ignore --no-index -v and judges by output, not by promise settlement (simple-git raw() resolves on a silent non-zero exit).
1 parent 70afcfa commit 075adc7

9 files changed

Lines changed: 221 additions & 33 deletions

File tree

‎src/core/checkpoints/__tests__/changeJournal.spec.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,26 @@ describe("changeJournal", () => {
7070
expect(after).toBe(raw + '{"path":"src/half.ts","operation":"upd')
7171
})
7272

73+
it("rejects an append when a malformed final record kept its newline", async () => {
74+
await appendChange(tmpRoot, taskId, entry({ checkpointId: "good" }))
75+
// A final line of valid JSON that is not an entry (a bare null) is the
76+
// same hazard with or without its newline: accepting it here would
77+
// demote it to a skipped middle line after the append, so loadChanges
78+
// would report an incomplete rollback history as valid and
79+
// restore-latest could pick an older entry for the same file.
80+
const filePath = journalPath(tmpRoot, taskId)
81+
const raw = await fs.readFile(filePath, "utf8")
82+
await fs.writeFile(filePath, raw + "null\n")
83+
84+
await expect(appendChange(tmpRoot, taskId, entry({ checkpointId: "after" }))).rejects.toThrow(
85+
/final record is not a complete entry/,
86+
)
87+
88+
// The journal is left untouched for an explicit recovery.
89+
const after = await fs.readFile(filePath, "utf8")
90+
expect(after).toBe(raw + "null\n")
91+
})
92+
7393
it("does not insert a blank line when the journal ends cleanly", async () => {
7494
await appendChange(tmpRoot, taskId, entry({ checkpointId: "a" }))
7595
await appendChange(tmpRoot, taskId, entry({ checkpointId: "b" }))

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

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ const COMMIT = "test-commit-hash"
6060
interface ServiceLike {
6161
isInitialized: boolean
6262
saveCheckpoint: (...args: unknown[]) => Promise<unknown>
63+
isPathIgnored: (filePath: string) => Promise<boolean>
6364
}
6465

6566
interface ProviderLike {
@@ -105,7 +106,13 @@ describe("checkpointSave change-journal wiring (B2)", () => {
105106
mockTask = {
106107
taskId: TASK_ID,
107108
enableCheckpoints: true,
108-
checkpointService: { isInitialized: true, saveCheckpoint: saveCheckpointSpy },
109+
checkpointService: {
110+
isInitialized: true,
111+
saveCheckpoint: saveCheckpointSpy,
112+
// Default: nothing is excluded from the shadow repo, so journaling
113+
// behavior is unchanged unless a test overrides this.
114+
isPathIgnored: vi.fn().mockResolvedValue(false),
115+
},
109116
checkpointServiceInitializing: false,
110117
providerRef: { deref: () => mockProvider },
111118
// B3a: the card emission calls task.say; a resolved double keeps the
@@ -138,6 +145,38 @@ describe("checkpointSave change-journal wiring (B2)", () => {
138145
expect(raw.split("\n").filter((line) => line !== "")).toHaveLength(1)
139146
})
140147

148+
it("keeps shadow-repo-excluded paths out of the journal and the card", async () => {
149+
// Excluded paths are absent from the shadow commit by design; journaling
150+
// them would route a later rollback into restoreFile's delete branch and
151+
// remove the user's live file. They must not appear in the journal, must
152+
// not be advertised by the card, and a step whose writes are ALL excluded
153+
// must produce neither a journal update nor a card.
154+
mockTask.checkpointService.isPathIgnored = vi
155+
.fn()
156+
.mockImplementation(async (p: string) => p.startsWith("node_modules/"))
157+
158+
await checkpointSave(mockTask as Task, false, true, [
159+
{ path: "src/kept.ts", operation: "create", diffStats: { additions: 1, deletions: 0 } },
160+
{ path: "node_modules/pkg/index.js", operation: "create", diffStats: { additions: 1, deletions: 0 } },
161+
])
162+
163+
let entries = await loadChanges(tmpStorageDir, TASK_ID)
164+
expect(entries.map((e) => e.path)).toEqual(["src/kept.ts"])
165+
const sayMock = mockTask.say as Mock
166+
expect(sayMock).toHaveBeenCalledTimes(1)
167+
expect(String(sayMock.mock.calls[0][1])).not.toContain("node_modules")
168+
169+
// A step whose every write is excluded journals nothing and emits no card.
170+
await checkpointSave(mockTask as Task, false, true, {
171+
path: "node_modules/pkg/other.js",
172+
operation: "create",
173+
diffStats: { additions: 1, deletions: 0 },
174+
})
175+
entries = await loadChanges(tmpStorageDir, TASK_ID)
176+
expect(entries.map((e) => e.path)).toEqual(["src/kept.ts"])
177+
expect(sayMock).toHaveBeenCalledTimes(1)
178+
})
179+
141180
it("omits diffStats in the journal entry when not provided", async () => {
142181
await checkpointSave(mockTask as Task, false, true, { path: "src/bar.ts", operation: "update" })
143182

‎src/core/checkpoints/__tests__/checkpointSave.spec.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,10 @@ function makeTask(options: {
5353
enableCheckpoints: options.enableCheckpoints ?? true,
5454
// With `storageDir: null` there is no preset service either, so the
5555
// lookup runs for real and fails on the missing storage dir.
56-
checkpointService: options.storageDir === null ? undefined : { saveCheckpoint, isInitialized: true },
56+
checkpointService:
57+
options.storageDir === null
58+
? undefined
59+
: { saveCheckpoint, isInitialized: true, isPathIgnored: vi.fn().mockResolvedValue(false) },
5760
providerRef: { deref: vi.fn().mockReturnValue(providerDeref) },
5861
say,
5962
} as unknown as Task

‎src/core/checkpoints/changeJournal.ts‎

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -122,31 +122,43 @@ export async function appendChanges(
122122
throw error
123123
}
124124
}
125-
// Torn-tail handling: a crash can leave the final line unterminated.
126-
// If that final line is a complete, entry-shaped JSON record it was
127-
// fully written and only its newline was lost - verified recovery:
128-
// keep it and re-terminate. An unparseable or non-entry-shaped tail
129-
// is NOT verified recovery material: it may be the truncated journal
130-
// record of a committed write, and silently truncating it would let
131-
// this append succeed while the rollback history is already
132-
// incomplete (a later rollback could then resolve the file to the
133-
// wrong checkpoint or lose the lost write's metadata). Reject the
134-
// append instead; torn-tail repair is a separately verified recovery
135-
// operation, not a side effect of the next write.
136-
if (content && !content.endsWith("\n")) {
137-
const cut = content.lastIndexOf("\n") + 1
138-
let tail: unknown
139-
try {
140-
tail = JSON.parse(content.slice(cut))
141-
} catch {
142-
tail = undefined
125+
// Torn-tail handling: the FINAL record must be complete and
126+
// entry-shaped whether or not it ends with a newline. A crash can
127+
// leave the final line unterminated; if that line is a complete,
128+
// entry-shaped JSON record it was fully written and only its newline
129+
// was lost - verified recovery: keep it and re-terminate. An
130+
// unparseable or non-entry-shaped final record is NOT verified
131+
// recovery material: it may be the truncated journal record of a
132+
// committed write, and silently truncating it would let this append
133+
// succeed while the rollback history is already incomplete (a later
134+
// rollback could then resolve the file to the wrong checkpoint or
135+
// lose the lost write's metadata). A malformed final record that
136+
// still ends with its newline (e.g. "null\n") is the same hazard:
137+
// accepting it here would demote it to a skipped middle line after
138+
// the append, reporting an incomplete history as valid. Reject the
139+
// append in both cases; torn-tail repair is a separately verified
140+
// recovery operation, not a side effect of the next write.
141+
if (content) {
142+
const unterminated = !content.endsWith("\n")
143+
const body = unterminated ? content : content.slice(0, -1)
144+
const cut = body.lastIndexOf("\n") + 1
145+
const tailText = body.slice(cut)
146+
if (tailText !== "") {
147+
let tail: unknown
148+
try {
149+
tail = JSON.parse(tailText)
150+
} catch {
151+
tail = undefined
152+
}
153+
if (!isEntryShaped(tail)) {
154+
throw new Error(
155+
`Cannot append to change journal ${filePath}: ${unterminated ? "unterminated " : ""}final record is not a complete entry (torn-tail recovery requires explicit repair)`,
156+
)
157+
}
143158
}
144-
if (!isEntryShaped(tail)) {
145-
throw new Error(
146-
`Cannot append to change journal ${filePath}: unterminated final record is not a complete entry (torn-tail recovery requires explicit repair)`,
147-
)
159+
if (unterminated) {
160+
content = content + "\n"
148161
}
149-
content = content + "\n"
150162
}
151163
const payload = entries.map((entry) => JSON.stringify(entry) + "\n").join("")
152164
const tmpPath = path.join(dir, `${JOURNAL_FILENAME}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`)

‎src/core/checkpoints/index.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,25 @@ export async function checkpointSave(
352352
// changes can still produce a commit, and emitting a card for it would
353353
// show a change card with zero files. The checkpoint itself still runs.
354354
if (result?.commit && hasWriteMetadata) {
355-
const writes = journalWrites ?? []
355+
// Paths excluded from the shadow repository (node_modules, build
356+
// output, .gitignore'd files) never enter the journal: the shadow
357+
// commit cannot contain them, so a journal entry would route a later
358+
// rollback into restoreFile's delete branch, where absence from the
359+
// commit would delete the user's live file. Skipping excluded paths
360+
// at journaling time keeps rollback metadata honest and removes
361+
// excluded-path noise from the journal and the change card.
362+
const writes: CheckpointWriteInfo[] = []
363+
for (const w of journalWrites ?? []) {
364+
if (await service.isPathIgnored(w.path)) {
365+
continue
366+
}
367+
writes.push(w)
368+
}
369+
if (writes.length === 0) {
370+
// Every write landed on an excluded path: nothing to journal and
371+
// nothing to show; the checkpoint commit itself still ran.
372+
return result
373+
}
356374
if (!journalDir) {
357375
// Defensive: the pre-commit guard above normally makes this
358376
// unreachable. If the location is nonetheless gone while the commit

‎src/core/task/Task.ts‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3863,13 +3863,21 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
38633863
// save would only add latency to a task that is being disposed.
38643864
if (!this.taskStartBaselineDone && !this._isHistoryTask && !this.abort) {
38653865
this.taskStartBaselineDone = true
3866-
const baselineEnabled = (await this.providerRef.deref()?.getState())?.perWriteCheckpoints
3867-
// Cancellation can arrive while the state lookup is pending; recheck
3868-
// before the save so a canceled task performs no checkpoint work.
3869-
if (baselineEnabled !== false && !this.abort) {
3870-
// allowEmpty=true so a clean workspace still produces the baseline
3871-
// commit; awaited so the first per-write checkpoint cannot interleave.
3872-
await this.checkpointSave(true, true)
3866+
try {
3867+
const baselineEnabled = (await this.providerRef.deref()?.getState())?.perWriteCheckpoints
3868+
// Cancellation can arrive while the state lookup is pending; recheck
3869+
// before the save so a canceled task performs no checkpoint work.
3870+
if (baselineEnabled !== false && !this.abort) {
3871+
// allowEmpty=true so a clean workspace still produces the baseline
3872+
// commit; awaited so the first per-write checkpoint cannot interleave.
3873+
await this.checkpointSave(true, true)
3874+
}
3875+
} catch (error) {
3876+
// The baseline is best-effort and runs before TaskStarted: a rejected
3877+
// state lookup or a checkpoint error must not abort task startup
3878+
// (startTask rethrows non-abort errors from initiateTaskLoop). Log
3879+
// and continue; per-write saves still report their own failures.
3880+
console.error("[Task] task-start checkpoint baseline failed:", error)
38733881
}
38743882
}
38753883

‎src/core/task/__tests__/Task.spec.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6991,6 +6991,31 @@ describe("Cline", () => {
69916991
await loopPromise
69926992
expect(requestSpy).toHaveBeenCalled()
69936993
})
6994+
6995+
it("continues task startup when the baseline checkpoint fails", async () => {
6996+
const task = new Task({
6997+
provider: mockProvider,
6998+
apiConfiguration: mockApiConfig,
6999+
task: "baseline failure task",
7000+
startTask: false,
7001+
})
7002+
const taskAccess = getTaskTestAccess(task)
7003+
const boom = new Error("baseline boom")
7004+
vi.spyOn(task, "checkpointSave").mockRejectedValue(boom)
7005+
const state = await mockProvider.getState()
7006+
vi.spyOn(mockProvider, "getState").mockResolvedValue(state)
7007+
const requestSpy = vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
7008+
const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
7009+
7010+
// The baseline runs before TaskStarted: a checkpoint error must not
7011+
// abort task startup (startTask rethrows non-abort errors from
7012+
// initiateTaskLoop). The loop must still be entered.
7013+
await taskAccess.initiateTaskLoop([])
7014+
7015+
expect(requestSpy).toHaveBeenCalled()
7016+
expect(consoleErrorSpy).toHaveBeenCalledWith("[Task] task-start checkpoint baseline failed:", boom)
7017+
consoleErrorSpy.mockRestore()
7018+
})
69947019
})
69957020

69967021
describe("start()", () => {

‎src/services/checkpoints/ShadowCheckpointService.ts‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -535,6 +535,16 @@ export abstract class ShadowCheckpointService extends EventEmitter {
535535
// single requested path.
536536
await this.git.checkout([commitHash, "--", `:(literal)${gitPath}`])
537537
} else {
538+
// Belt-and-suspenders: a path the shadow repository excludes was
539+
// never tracked, so its absence from the commit is not evidence of
540+
// a deletion - removing it here could rm a live user file (e.g. a
541+
// log under an excluded directory) that no checkpoint ever
542+
// contained. Journaling now skips excluded paths, but journals
543+
// written before that fix can still route an excluded path here;
544+
// fail loudly instead of deleting.
545+
if (await this.isPathIgnored(filePath)) {
546+
throw new Error(`restoreFile target is excluded from the shadow repository: ${filePath}`)
547+
}
538548
// TOCTOU guard: same race as above - without this re-check the
539549
// delete could remove a file the swapped link now points at
540550
// outside the workspace.
@@ -555,6 +565,39 @@ export abstract class ShadowCheckpointService extends EventEmitter {
555565
}
556566
}
557567

568+
/**
569+
* Whether `filePath` (workspace-relative or absolute) is excluded from the
570+
* shadow repository by its local exclude rules (.git/info/exclude, which
571+
* mirrors the workspace ignore configuration). Excluded paths are never
572+
* tracked by the shadow repo, so they must not enter the change journal
573+
* and must not be deleted by restoreFile's delete branch.
574+
*/
575+
public async isPathIgnored(filePath: string): Promise<boolean> {
576+
if (!this.git) {
577+
return false
578+
}
579+
const resolved = path.resolve(this.workspaceDir, filePath)
580+
const gitPath = path.relative(this.workspaceDir, resolved).split(path.sep).join("/")
581+
if (!gitPath || gitPath.startsWith("..")) {
582+
return false
583+
}
584+
try {
585+
// --no-index evaluates the exclude rules alone: index or commit
586+
// membership is irrelevant to "the shadow repo never tracks this".
587+
// The verdict comes from the -v output, not from the promise
588+
// settling: simple-git's raw() resolves (rather than rejects) on a
589+
// silent non-zero exit, so "not ignored" (exit 1, no output) arrives
590+
// as an empty success here - the same defect documented in
591+
// fileExistsInCommit. An ignored path prints its matching rule line.
592+
const match = await this.git.raw(["check-ignore", "--no-index", "-v", "--", gitPath])
593+
return match.trim().length > 0
594+
} catch {
595+
// A git fatal (corrupt repo) leaves the path unproven-ignored;
596+
// callers keep their historical behavior for that case.
597+
return false
598+
}
599+
}
600+
558601
/** Whether `filePath` exists in the tree of `commitHash`. */
559602
private async fileExistsInCommit(commitHash: string, filePath: string): Promise<boolean> {
560603
// A failed lookup is not evidence the file is absent. If the commit object

‎src/services/checkpoints/__tests__/ShadowCheckpointService.spec.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,26 @@ describe.each([[RepoPerTaskCheckpointService, "RepoPerTaskCheckpointService"]])(
202202
expect(await fs.readFile(testFile, "utf-8")).toBe("Ahoy, world!")
203203
})
204204

205+
it("rejects deleting an ignored live file that the checkpoint never tracked", async () => {
206+
await fs.writeFile(testFile, "Ahoy, world!")
207+
const commit1 = await service.saveCheckpoint("First checkpoint")
208+
expect(commit1?.commit).toBeTruthy()
209+
210+
// An ignored path (.log is excluded by the default shadow-repo
211+
// rules) reaches restoreFile only from a journal written before the
212+
// skip-when-journaling fix. Its absence from the commit is not
213+
// evidence of a deletion: the delete branch must fail loudly
214+
// instead of removing a live file the shadow repo never tracked.
215+
const ignoredFile = path.join(service.workspaceDir, "live.log")
216+
await fs.writeFile(ignoredFile, "live log content")
217+
218+
await expect(service.restoreFile(commit1!.commit, "live.log")).rejects.toThrow(
219+
/excluded from the shadow repository/,
220+
)
221+
222+
expect(await fileExistsAtPath(ignoredFile)).toBe(true)
223+
})
224+
205225
it("accepts a native backslashed path on Windows (git pathspecs are POSIX)", async () => {
206226
if (process.platform !== "win32") {
207227
// Off-Windows the journal paths are already POSIX, so there is

0 commit comments

Comments
 (0)