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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = 20const 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_LINESlet cwd = ''let side: boolean | undefinedlet 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')}