Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Discovery: read past Claude's checkpoint snapshots to a transcript's cwd (#1479)

0xdiego2567b11108a0c4
diff --git a/cli/src/cable/serialWindows.spec.ts b/cli/src/cable/serialWindows.spec.ts
index 9eff09fcf..6ccaff4c6 100644
--- a/cli/src/cable/serialWindows.spec.ts
+++ b/cli/src/cable/serialWindows.spec.ts
@@ -86,7 +86,8 @@ describe('SerialLink over harness-serial (any OS, the stand-in)', () => {
} finally {
await fleet.stop()
watch.stop()
- rmSync(logs, { recursive: true, force: true })
+ // DialLog's last write can land after stop(): retry the ENOTEMPTY that race leaves, as CI hit once.
+ rmSync(logs, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 })
}
})
})
diff --git a/cli/src/engines/kit/identityScan.ts b/cli/src/engines/kit/identityScan.ts
index 0bd45529d..861460291 100644
--- a/cli/src/engines/kit/identityScan.ts
+++ b/cli/src/engines/kit/identityScan.ts
@@ -79,6 +79,80 @@ export async function identityBytes(path: string, maxBytes: number, expected?: I
} finally { await handle.close() }
}
+/**
+ * A regular file's opening lines, read in bounded chunks with the same change checks as `identityBytes`.
+ * `skip` sees the first bytes of each line (up to SKIP_PROBE); a skipped line is passed over without being kept or
+ * counted, so a run of large bookkeeping records cannot hide the lines that follow it. `visit` gets each kept line in
+ * order and returns true to stop. The result says why reading ended: `stopped` by `visit`, the file's `end`, or a
+ * `limit` (kept lines, kept characters, or `maxBytes` read). A final line without a newline is visited only at `end`.
+ */
+const SKIP_PROBE = 64
+export async function identityLines(path: string, limits: { maxBytes: number; maxLines: number; maxChars: number },
+ skip: (start: string) => boolean, visit: (line: string) => boolean | Promise<boolean>,
+): Promise<'stopped' | 'end' | 'limit'> {
+ const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
+ try {
+ const before = await handle.stat()
+ if (!before.isFile()) throw new IdentityReadUnavailable('the native record is not a regular file')
+ const length = Math.min(before.size, limits.maxBytes), chunk = Buffer.alloc(64 * 1024)
+ let position = 0, lines = 0, chars = 0
+ let parts: Buffer[] = [], size = 0, decided = false, skipping = false
+ const keep = async (): Promise<'stopped' | 'limit' | null> => {
+ const text = Buffer.concat(parts).toString('utf8')
+ parts = []; size = 0
+ // A line's own newline counts only once a later line is read, as in a character slice of the head.
+ if (++lines > limits.maxLines || (chars += text.length) > limits.maxChars) return 'limit'
+ const stop = await visit(text)
+ chars += 1
+ return stop ? 'stopped' : null
+ }
+ const outcome = await (async (): Promise<'stopped' | 'end' | 'limit'> => {
+ while (position < length) {
+ const read = (await handle.read(chunk, 0, Math.min(chunk.length, length - position), position)).bytesRead
+ if (!read) throw new IdentityReadUnavailable('the native record ended during the read')
+ position += read
+ for (let from = 0; from < read;) {
+ const found = chunk.indexOf(10, from), newline = found !== -1 && found < read
+ const to = newline ? found : read
+ if (!skipping) {
+ parts.push(Buffer.from(chunk.subarray(from, to))); size += to - from
+ if (!decided && (size >= SKIP_PROBE || newline)) {
+ decided = true
+ skipping = skip(Buffer.concat(parts).subarray(0, SKIP_PROBE).toString('utf8'))
+ if (skipping) { parts = []; size = 0 }
+ }
+ if (!skipping && size > limits.maxChars * 4) return 'limit'
+ }
+ if (!newline) break
+ if (!skipping) { const done = await keep(); if (done) return done }
+ decided = false; skipping = false
+ from = to + 1
+ }
+ }
+ if (length < before.size) return 'limit'
+ if (!skipping && size && !skip(Buffer.concat(parts).subarray(0, SKIP_PROBE).toString('utf8'))) {
+ const done = await keep(); if (done) return done
+ }
+ return 'end'
+ })()
+ const after = await handle.stat()
+ if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+ throw new IdentityReadUnavailable('the native record changed during the read')
+ }
+ const current = await open(path, constants.O_RDONLY | constants.O_NONBLOCK).catch(() => {
+ throw new IdentityReadUnavailable('the native record disappeared during the read')
+ })
+ try {
+ const now = await current.stat()
+ if (now.dev !== before.dev || now.ino !== before.ino || now.size !== before.size
+ || now.mtimeMs !== before.mtimeMs || now.ctimeMs !== before.ctimeMs) {
+ throw new IdentityReadUnavailable('the native record was replaced during the read')
+ }
+ } finally { await current.close() }
+ return outcome
+ } finally { await handle.close() }
+}
+
/** opendir bounds the directory buffer too; readdir followed by slice would still read the whole tree. */
export async function* identityEntries(path: string, budget: { remaining: number }, missingOkay = true): AsyncGenerator<Dirent> {
// An empty or missing directory still costs a filesystem operation.
diff --git a/cli/src/lib/sessionRepair.bounds.spec.ts b/cli/src/lib/sessionRepair.bounds.spec.ts
index 017870044..3d2ef9ffe 100644
--- a/cli/src/lib/sessionRepair.bounds.spec.ts
+++ b/cli/src/lib/sessionRepair.bounds.spec.ts
@@ -179,6 +179,24 @@ describe('complete bounded evidence before choosing a conversation', () => {
await expect(scan()).rejects.toThrow('Conversation identity is held')
})
+ it.each([
+ ['a long session opening with checkpoint snapshots', 60, 88 * 1024, 'resolves'],
+ ['snapshots past the byte bound', 400, 88 * 1024, 'held'],
+ ] as const)('reads past %s to its cwd', async (_name, count, bytes, outcome) => {
+ const path = transcript()
+ const snapshot = JSON.stringify({ type: 'file-history-snapshot', messageId: 'm', snapshot: { trackedFileBackups: 'x'.repeat(bytes) } }) + '\n'
+ const head = ['ai-title', 'agent-name', 'mode', 'permission-mode'].map(type => JSON.stringify({ type, sessionId: 'resumed' }) + '\n').join('')
+ file(join(root, 'claude', 'projects', 'work', 'resumed.jsonl'), head + snapshot.repeat(count) + body('/elsewhere') + 'later\n')
+ if (outcome === 'resolves') await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
+ else await expect(scan()).rejects.toThrow('header exceeds the read limit')
+ })
+
+ it('still holds on a large record that is not a skipped snapshot', async () => {
+ transcript()
+ file(join(root, 'claude', 'projects', 'work', 'big.jsonl'), JSON.stringify({ type: 'user', text: 'x'.repeat(300 * 1024) }) + '\n' + body('/elsewhere'))
+ await expect(scan()).rejects.toThrow('header exceeds the read limit')
+ })
+
it('can exclude a confirmed different cwd without reading its remaining history', async () => {
const path = transcript()
file(join(root, 'claude', 'projects', 'other.jsonl'), JSON.stringify({ cwd: '/elsewhere' }) + '\n' + 'x'.repeat(2 * 1024 * 1024))
diff --git a/cli/src/lib/sessionRepair.metadata.spec.ts b/cli/src/lib/sessionRepair.metadata.spec.ts
index 6ecc1cc19..0aab0ec5c 100644
--- a/cli/src/lib/sessionRepair.metadata.spec.ts
+++ b/cli/src/lib/sessionRepair.metadata.spec.ts
@@ -84,8 +84,8 @@ describe('bounded session metadata discovery', () => {
vi.mocked(fs.open).mockResolvedValueOnce(handle)
try {
await expect(read()).resolves.toMatchObject({ sessionId: 'session-id' })
- expect(reads).toHaveBeenCalledTimes(1)
- expect(reads.mock.calls[0].slice(1)).toEqual([0, LIMIT * 4 + 1, 0])
+ expect(reads).toHaveBeenCalledTimes(1) // The cwd is in the first bounded chunk; the rest is never read.
+ expect(reads.mock.calls[0].slice(1)).toEqual([0, 64 * 1024, 0])
expect(handle.fd).toBe(-1)
} finally { if (handle.fd !== -1) await handle.close() }
})
diff --git a/cli/src/lib/sessionRepair.ts b/cli/src/lib/sessionRepair.ts
index 4c1228479..95cf0b05c 100644
--- a/cli/src/lib/sessionRepair.ts
+++ b/cli/src/lib/sessionRepair.ts
@@ -18,7 +18,7 @@ import { realpath, stat } from 'fs/promises'
import { basename, dirname, isAbsolute, join, sep } from 'path'
import { env } from '../config/env.js'
import type { SessionStoreContract } from '../engines/facets/sessionStore.js'
-import { identityBytes, identityEntries, identityFile, identityHead, identityScanBudget, IdentityReadUnavailable } from '../engines/kit/identityScan.js'
+import { identityBytes, identityEntries, identityFile, identityHead, identityLines, identityScanBudget, IdentityReadUnavailable } from '../engines/kit/identityScan.js'
import { sessionIdentityMetaOf } from '../engines/sessionFiles.js'
import { exactTranscript, exactWorkspaces } from '../engines/kit/exactTranscript.js'
import { readSessionHeader } from '../engines/kit/sessionIdentity.js'
@@ -110,37 +110,41 @@ async function transcripts(root: string, budget: { remaining: number }, out: Tra
*/
const CWD_SCAN_LINES = 20
const CWD_SCAN_CHARS = 256 * 1024
+/**
+ * Claude writes a `file-history-snapshot` record (tens of KB each) per checkpoint, and a long or resumed session can
+ * open with dozens of them before the first record that carries its cwd: 4–5 MB in, at line 50–60. They are passed
+ * over unread and uncounted, inside this byte bound, so such a session no longer holds every agent in its folder.
+ */
+const CWD_SCAN_BYTES = 32 * 1024 * 1024
+const UNCOUNTED_RECORD = /^\{\s*"type"\s*:\s*"file-history-snapshot"/
/**
* The first `cwd` in a transcript's head and, when asked, its opening flag named `sidechain` (an engine's session
- * store declares it: `scan.sidechain`). One bounded read (256 KB — transcripts run to hundreds of MB) shared by
- * every file engine that declares its cwd in-file. Without a flag it stops at the first cwd, exactly as it always did.
+ * store declares it: `scan.sidechain`). One bounded streaming read (the first 20 counted lines, 256 K characters,
+ * within 32 MB; transcripts run to hundreds of MB) shared by every file engine that declares its cwd in-file. Without
+ * a flag it stops at the first cwd, exactly as it always did.
*/
async function readTranscriptHead(path: string, sidechain: string | null, requestedCwd?: string): Promise<{ cwd: string; side: boolean | undefined } | null> {
try {
- // Preserve the existing UTF-16 character budget, including non-ASCII paths. Four
- // UTF-8 bytes per code unit is sufficient even when the cutoff splits a surrogate
- // pair; a byte budget equal to the character budget would silently shrink the scan.
- const bytes = await identityBytes(path, CWD_SCAN_CHARS * 4 + 1)
- const text = bytes.subarray(0, CWD_SCAN_CHARS * 4).toString('utf-8')
- const head = text.slice(0, CWD_SCAN_CHARS)
- const complete = bytes.length <= CWD_SCAN_CHARS * 4 && text.length <= CWD_SCAN_CHARS
- && head.split('\n').length <= CWD_SCAN_LINES
let cwd = ''
let side: boolean | undefined
let malformed = false
- for (const line of head.split('\n', CWD_SCAN_LINES)) {
- if (!line.trim()) continue
- let obj: Record<string, unknown>
- try { obj = JSON.parse(line) as Record<string, unknown> } catch { malformed = true; continue }
- if (!obj || typeof obj !== 'object' || Array.isArray(obj)) { malformed = true; continue }
- if (!cwd && typeof obj.cwd === 'string' && obj.cwd) cwd = obj.cwd
- if (cwd && !isAbsolute(cwd)) throw new IdentityReadUnavailable('the transcript working directory is invalid')
- if (sidechain && side === undefined && typeof obj[sidechain] === 'boolean') side = obj[sidechain] as boolean
- if (cwd && requestedCwd && !await sameDir(cwd, requestedCwd)) return { cwd, side }
- if (side === true || (cwd && (!sidechain || side !== undefined))) return { cwd, side }
- }
- if (!complete) throw new IdentityReadUnavailable('the transcript header exceeds the read limit')
+ let found: { cwd: string; side: boolean | undefined } | null = null
+ const ended = await identityLines(path, { maxBytes: CWD_SCAN_BYTES, maxLines: CWD_SCAN_LINES, maxChars: CWD_SCAN_CHARS },
+ start => UNCOUNTED_RECORD.test(start), async line => {
+ if (!line.trim()) return false
+ let obj: Record<string, unknown>
+ try { obj = JSON.parse(line) as Record<string, unknown> } catch { malformed = true; return false }
+ if (!obj || typeof obj !== 'object' || Array.isArray(obj)) { malformed = true; return false }
+ if (!cwd && typeof obj.cwd === 'string' && obj.cwd) cwd = obj.cwd
+ if (cwd && !isAbsolute(cwd)) throw new IdentityReadUnavailable('the transcript working directory is invalid')
+ if (sidechain && side === undefined && typeof obj[sidechain] === 'boolean') side = obj[sidechain] as boolean
+ if (cwd && requestedCwd && !await sameDir(cwd, requestedCwd)) { found = { cwd, side }; return true }
+ if (side === true || (cwd && (!sidechain || side !== undefined))) { found = { cwd, side }; return true }
+ return false
+ })
+ if (found) return found
+ if (ended === 'limit') throw new IdentityReadUnavailable('the transcript header exceeds the read limit')
if (!cwd || (sidechain && side === undefined && malformed)) {
throw new IdentityReadUnavailable('the transcript header is incomplete or invalid')
}