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
Restore compressed Codex histories when reopening retained harnesses (#1600)
Dee14f2cf12aac7
diff --git a/cli/e2e/ends.e2e.ts b/cli/e2e/ends.e2e.tsindex 44b887971..d6caa4ab7 100644--- a/cli/e2e/ends.e2e.ts+++ b/cli/e2e/ends.e2e.ts@@ -5,7 +5,8 @@* that finds a conversation until it is purged. A close never takes a turn that is still working unless* it was asked to; a purge leaves nothing of the conversation behind.*/-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'+import * as zlib from 'node:zlib'import { join } from 'node:path'import { afterEach, describe, expect, it, onTestFailed } from 'vitest'import { LocalClient, type Frame } from './harness/client.js'@@ -91,6 +92,33 @@ describe('how an agent\'s life ends', () => {client.close()})+ it('Codex: a retained harness reopens the same conversation after cold-rollout compression', async () => {+ const d = await fresh()+ const client = await LocalClient.connect(d)+ const agent = await create(d, client, 'codex', 'compressed-resume')+ await turn(client, agent.id, 'History before compression')+ expect(await close(client, agent, 'now')).toMatchObject({ closed: true })+ await stopped(client, agent.id)+ const [file] = transcriptsOf(d, agent.sessionId)+ const original = readFileSync(file)+ const compressed = (zlib as typeof zlib & { zstdCompressSync: (value: Buffer) => Buffer }).zstdCompressSync(original)+ writeFileSync(file + '.zst', compressed)+ unlinkSync(file)+ // This is the request sent by Open in Desktop search, through the real daemon and resume guards.+ const reopened = await client.request('agent_resume', { agentId: agent.id }, 90_000)+ expect(reopened.error, JSON.stringify(reopened)).toBeUndefined()+ await until('the compressed conversation to reopen', async () => {+ const now = await row(client, agent.id)+ return now?.status === 'active' && now.sessionId === agent.sessionId ? now : null+ }, 60_000, 500)+ expect(readFileSync(file).subarray(0, original.length)).toEqual(original)+ expect(readFileSync(file + '.zst')).toEqual(compressed)+ await turn(client, agent.id, 'History after compression')+ expect(readFileSync(file, 'utf8')).toContain('History before compression')+ expect(readFileSync(file, 'utf8')).toContain('History after compression')+ client.close()+ })+it.each(engines)('%s: unavailable transcript identity holds Close and Resume until the same conversation is restored', async engine => {const d = await fresh()const client = await LocalClient.connect(d)diff --git a/cli/src/engines/codex/sessionStore.ts b/cli/src/engines/codex/sessionStore.tsindex 40e4a0a03..ecd7da618 100644--- a/cli/src/engines/codex/sessionStore.ts+++ b/cli/src/engines/codex/sessionStore.ts@@ -23,6 +23,9 @@ export const sessionStore: SessionStoreContract = {archived: 'archived_sessions',},byId: { layout: 'walk', suffix: rollouts.suffix, id: rollouts.id, walk: rollouts.walk },+ // Codex's cold-rollout worker replaces .jsonl with .jsonl.zst. The saved path stays .jsonl.+ // Upstream: codex-rs/rollout/src/compression.rs (materialize_rollout_for_append).+ compression: { suffix: '.zst', format: 'zstd' },/*** The rollout's first record is the session's metadata: its id (the file name only holds it), the folder it* started in (the one field that says where a rollout belongs), and whether a parent delegated to it. Readdiff --git a/cli/src/engines/facets/sessionStore.ts b/cli/src/engines/facets/sessionStore.tsindex 598cf1706..306b8408d 100644--- a/cli/src/engines/facets/sessionStore.ts+++ b/cli/src/engines/facets/sessionStore.ts@@ -39,6 +39,9 @@ export interface SessionStoreContract {* depth, at most `walk` entries looked at, for an id `id` accepts. `projects`: `<id><suffix>` in any one folder* directly below a sessions folder. */byId: { layout: 'walk'; suffix: string; id: RegExp; walk: number } | { layout: 'projects'; suffix: string }+ /** Cold histories keep their logical path while the engine replaces the file with this archive.+ * Opening a stopped harness materializes only that history before earning control identity. */+ compression?: { suffix: string; format: 'zstd' }/*** What a session file's first record says about it, read within `maxBytes`: its `type`, and where it keeps* the id, the folder, the field whose presence marks a session another one delegated to, and that one's parent.diff --git a/cli/src/engines/kit/zstdFrames.spec.ts b/cli/src/engines/kit/zstdFrames.spec.tsnew file mode 100644index 000000000..ae6998b09--- /dev/null+++ b/cli/src/engines/kit/zstdFrames.spec.ts@@ -0,0 +1,41 @@+import { expect, it } from 'vitest'+import { Readable, Writable } from 'node:stream'+import { pipeline } from 'node:stream/promises'+import * as zlib from 'node:zlib'+import { completeZstdFrames } from './zstdFrames.js'++const zstd = zlib as typeof zlib & { zstdCompressSync: (value: string, options?: { params: Record<number, number> }) => Buffer }+async function check(bytes: Buffer, chunkSize = bytes.length || 1): Promise<Buffer> {+ const chunks: Buffer[] = []+ for (let i = 0; i < bytes.length; i += chunkSize) chunks.push(bytes.subarray(i, i + chunkSize))+ const output: Buffer[] = []+ await pipeline(Readable.from(chunks), completeZstdFrames(), new Writable({ write(chunk, _encoding, done) { output.push(chunk); done() } }))+ return Buffer.concat(output)+}+const text = Array.from({ length: 50_000 }, (_, i) => `line ${i}\n`).join('')+it.each([1, 2, 3, 7, 64 * 1024])('accepts complete native multiblock frames in %i-byte chunks', async size => {+ const compressed = zstd.zstdCompressSync(text)+ expect(await check(compressed, size)).toEqual(compressed)+})+it('rejects every truncated prefix of a valid frame', async () => {+ const compressed = zstd.zstdCompressSync('a complete conversation')+ for (let end = 0; end < compressed.length; end++) await expect(check(compressed.subarray(0, end))).rejects.toThrow()+})+it('accepts concatenated frames, checksums, empty frames and skippable metadata', async () => {+ const skipped = Buffer.alloc(11)+ skipped.writeUInt32LE(0x184d2a50); skipped.writeUInt32LE(3, 4)+ const compressed = Buffer.concat([skipped, zstd.zstdCompressSync(''), zstd.zstdCompressSync(text, { params: { 201: 1 } })])+ expect(await check(compressed, 1)).toEqual(compressed)+ await expect(check(compressed.subarray(0, -1))).rejects.toThrow('Incomplete')+})+it('accepts a streaming frame without a content-size header and an RLE block', async () => {+ // Standard frame, window descriptor 0, last RLE block with 3 decoded bytes, payload "a".+ const bytes = Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 0, 0, 27, 0, 0, 97])+ expect(await check(bytes, 1)).toEqual(bytes)+})+it.each([+ Buffer.from('not zstd'),+ Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 8]),+ Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 0, 0, 7, 0, 0]),+ Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 0, 0, 9, 0, 16]),+])('rejects invalid framing %#', async bytes => { await expect(check(bytes, 1)).rejects.toThrow() })diff --git a/cli/src/engines/kit/zstdFrames.ts b/cli/src/engines/kit/zstdFrames.tsnew file mode 100644index 000000000..d0786f84e--- /dev/null+++ b/cli/src/engines/kit/zstdFrames.ts@@ -0,0 +1,63 @@+/** Check complete zstd frame boundaries while the native decoder checks their contents.+ * Node 22.23's decoder silently accepts a truncated final block, even with finishFlush=end.+ * Publishing its partial output would lose history. This pass retains at most a frame header.+ * Format: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md */+import { Transform } from 'node:stream'++export function completeZstdFrames(): Transform {+ type State = 'magic' | 'descriptor' | 'header' | 'block' | 'payload' | 'checksum' | 'skipSize' | 'skip'+ let state: State = 'magic', need = 4, used = 0, frames = 0, checksum = false, last = false+ const field = Buffer.alloc(14)+ const next = (value: State, bytes: number) => { state = value; need = bytes; used = 0 }+ const boundary = () => { frames++; next('magic', 4) }+ const advance = () => {+ switch (state) {+ case 'magic': {+ const magic = field.readUInt32LE(0)+ if (magic === 0xfd2fb528) next('descriptor', 1)+ else if (magic >= 0x184d2a50 && magic <= 0x184d2a5f) next('skipSize', 4)+ else throw new Error('Invalid zstd frame')+ break+ }+ case 'descriptor': {+ const descriptor = field[0], single = (descriptor & 32) !== 0, size = descriptor >>> 6+ if (descriptor & 8) throw new Error('Reserved zstd frame bit')+ checksum = (descriptor & 4) !== 0+ next('header', (single ? 0 : 1) + [0, 1, 2, 4][descriptor & 3] + [single ? 1 : 0, 2, 4, 8][size])+ break+ }+ case 'header': next('block', 3); break+ case 'block': {+ const block = field.readUIntLE(0, 3), type = (block >>> 1) & 3, size = block >>> 3+ if (type === 3 || size > 128 * 1024) throw new Error('Invalid zstd block')+ last = (block & 1) !== 0+ next('payload', type === 1 ? 1 : size)+ break+ }+ case 'payload':+ if (!last) next('block', 3)+ else if (checksum) next('checksum', 4)+ else boundary()+ break+ case 'checksum': boundary(); break+ case 'skipSize': next('skip', field.readUInt32LE(0)); break+ case 'skip': boundary(); break+ }+ }+ return new Transform({+ transform(chunk: Buffer, _encoding, done) {+ try {+ for (let offset = 0; offset < chunk.length;) {+ const count = Math.min(need - used, chunk.length - offset)+ if (state !== 'payload' && state !== 'skip') chunk.copy(field, used, offset, offset + count)+ used += count; offset += count+ while (used === need) advance()+ }+ done(null, chunk)+ } catch (error) { done(error as Error) }+ },+ flush(done) {+ done(frames > 0 && state === 'magic' && used === 0 ? undefined : new Error('Incomplete zstd frame'))+ },+ })+}diff --git a/cli/src/engines/resumeTranscript.spec.ts b/cli/src/engines/resumeTranscript.spec.tsnew file mode 100644index 000000000..1871a19cc--- /dev/null+++ b/cli/src/engines/resumeTranscript.spec.ts@@ -0,0 +1,170 @@+import { afterEach, beforeEach, expect, it, vi } from 'vitest'+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { dirname, join } from 'node:path'+import * as zlib from 'node:zlib'+import { materializeResumeTranscript } from './resumeTranscript.js'+import { controlTranscriptEvidence } from './transcriptBindings.js'++const zstd = zlib as typeof zlib & { zstdCompressSync: (value: Buffer | string) => Buffer }+const id = 'aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa'+let root: string, home: string, path: string+const history = (sessionId = id, source: unknown = 'cli') => JSON.stringify({ type: 'session_meta',+ payload: { id: sessionId, cwd: root, source } }) + '\n' + JSON.stringify({ type: 'event_msg',+ payload: { type: 'user_message', message: 'Keep this conversation' } }) + '\n'+const archive = (text = history(), at = path) => {+ mkdirSync(dirname(at), { recursive: true })+ writeFileSync(at + '.zst', zstd.zstdCompressSync(text), { mode: 0o600 })+}+const restore = (current = () => true, limits?: { timeoutMs: number; maxBytes: number }) =>+ materializeResumeTranscript('codex', id, path, home, current, limits)+const noTemporary = () => expect(readdirSync(dirname(path)).filter(name => name.startsWith('.harness-restore-'))).toEqual([])+beforeEach(() => {+ root = realpathSync(mkdtempSync(join(tmpdir(), 'resume-compressed-')))+ home = join(root, 'codex')+ path = join(home, 'sessions', '2026', '10', '05', `rollout-${id}.jsonl`)+ archive()+})+afterEach(() => { vi.restoreAllMocks(); rmSync(root, { recursive: true, force: true }) })++it('restores the exact history before control verification, retaining the archive and private permissions', async () => {+ expect(() => controlTranscriptEvidence('codex', id, path, home)).toThrow('unavailable')+ const compressed = readFileSync(path + '.zst')+ expect(await restore()).toBe(path)+ expect(readFileSync(path, 'utf8')).toBe(history())+ expect(readFileSync(path + '.zst')).toEqual(compressed)+ if (process.platform !== 'win32') expect(statSync(path).mode & 0o777).toBe(0o600)+ expect(() => controlTranscriptEvidence('codex', id, path, home).verify()).not.toThrow()+ noTemporary()+})++it('recovers again if Codex compresses the stopped conversation a second time', async () => {+ await restore()+ const later = history() + JSON.stringify({ type: 'event_msg', payload: { type: 'agent_message', message: 'Later reply' } }) + '\n'+ archive(later)+ unlinkSync(path)+ await restore()+ expect(readFileSync(path, 'utf8')).toBe(later)+})++it('accepts an explicitly compressed saved path in a private profile', async () => {+ expect(await materializeResumeTranscript('codex', id, path + '.zst', home, () => true)).toBe(path)+ expect(() => controlTranscriptEvidence('codex', id, path, home).verify()).not.toThrow()+})++it('keeps an existing plain history authoritative even when the archive is stale or corrupt', async () => {+ const current = history() + '{"type":"compacted"}\n'+ writeFileSync(path, current)+ writeFileSync(path + '.zst', 'corrupt old archive')+ expect(await restore()).toBe(path)+ expect(readFileSync(path, 'utf8')).toBe(current)+ noTemporary()+})++it.each(['leading blank lines', 'no final newline'])('uses the existing header rules with %s', async kind => {+ const text = kind === 'leading blank lines' ? '\n \n' + history() : history().split('\n')[0]+ archive(text)+ await restore()+ expect(readFileSync(path, 'utf8')).toBe(text)+ expect(() => controlTranscriptEvidence('codex', id, path, home).verify()).not.toThrow()+})++it('does not decompress histories of an engine that does not declare compression, or invent missing history', async () => {+ expect(await materializeResumeTranscript('claude', id, path, home, () => true)).toBe(path)+ expect(existsSync(path)).toBe(false)+ unlinkSync(path + '.zst')+ expect(await restore()).toBe(path)+ expect(existsSync(path)).toBe(false)+})++it.each([+ ['different', () => history('bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb')],+ ['delegated', () => history(id, { subagent: { thread_spawn: { parent_thread_id: id } } })],+ ['invalid', (): string => '{"type":"not_session_meta"}\n'],+ ['incomplete', (): string => history().split('\n')[0].slice(0, -1)],+ ['oversized', (): string => JSON.stringify({ type: 'session_meta', payload: { id, cwd: root, source: 'cli', padding: 'x'.repeat(128 * 1024) } }) + '\n'],+] as const)('never publishes a %s identity', async (_label, value) => {+ archive(value())+ const compressed = readFileSync(path + '.zst')+ await expect(restore()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })+ expect(existsSync(path)).toBe(false)+ expect(readFileSync(path + '.zst')).toEqual(compressed)+ noTemporary()+})++it.each(['invalid', 'truncated'] as const)('never publishes a %s archive or leaks its content in the error', async kind => {+ const bytes = kind === 'invalid' ? Buffer.from('PRIVATE_ARCHIVE_CONTENT') : readFileSync(path + '.zst').subarray(0, -5)+ writeFileSync(path + '.zst', bytes)+ await expect(restore()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })+ expect(existsSync(path)).toBe(false)+ expect(readFileSync(path + '.zst')).toEqual(bytes)+ noTemporary()+})++it('refuses a destination outside the declared profile', async () => {+ path = join(root, 'outside', `rollout-${id}.jsonl`); archive()+ await expect(restore()).rejects.toThrow('outside')+ expect(existsSync(path)).toBe(false)+})++it('rejects a truncated large archive even when the native decoder emits a complete header and many valid turns', async () => {+ archive(history() + Array.from({ length: 20_000 }, (_,i) => JSON.stringify({ type: 'event_msg', payload: { type: 'user_message', message: `Turn ${i}` } }) + '\n').join(''))+ writeFileSync(path + '.zst', readFileSync(path + '.zst').subarray(0, -1))+ await expect(restore()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })+ expect(existsSync(path)).toBe(false)+ noTemporary()+})++it('refuses a leaf symlink for either the archive or the missing destination', async () => {+ const elsewhere = join(root, 'other.zst')+ renameSync(path + '.zst', elsewhere)+ symlinkSync(elsewhere, path + '.zst')+ await expect(restore()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })+ unlinkSync(path + '.zst'); archive()+ symlinkSync(join(root, 'absent.jsonl'), path)+ expect(await restore()).toBe(path)+ expect(() => controlTranscriptEvidence('codex', id, path, home)).toThrow()+ expect(existsSync(join(root, 'absent.jsonl'))).toBe(false)+})++it('does not overwrite a plain file that appears while decompressing', async () => {+ let calls = 0+ await restore(() => {+ if (++calls === 2) writeFileSync(path, history('bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb'))+ return true+ })+ expect(readFileSync(path, 'utf8')).toContain('bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb')+ expect(() => controlTranscriptEvidence('codex', id, path, home)).toThrow('different')+ noTemporary()+})++it('refuses an archive replaced while decompressing and keeps both versions', async () => {+ let calls = 0+ await expect(restore(() => {+ if (++calls === 2) { renameSync(path + '.zst', path + '.old.zst'); archive() }+ return true+ })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })+ expect(existsSync(path)).toBe(false)+ expect(existsSync(path + '.old.zst')).toBe(true)+ noTemporary()+})++it.each([1, 2, 3])('retains the archive when cancelled at checkpoint %i', async when => {+ let calls = 0+ await expect(restore(() => ++calls !== when)).rejects.toThrow('cancelled')+ expect(existsSync(path)).toBe(false)+ expect(existsSync(path + '.zst')).toBe(true)+ noTemporary()+})++it('bounds decoded bytes without leaving a partial destination', async () => {+ await expect(restore(() => true, { maxBytes: 16, timeoutMs: 30_000 })).rejects.toThrow('size limit')+ expect(existsSync(path)).toBe(false)+ noTemporary()+})++it('bounds the total restore time without leaving a partial destination', async () => {+ await expect(restore(() => true, { maxBytes: 1024 ** 3, timeoutMs: 0 })).rejects.toThrow('retained')+ expect(existsSync(path)).toBe(false)+ noTemporary()+})diff --git a/cli/src/engines/resumeTranscript.ts b/cli/src/engines/resumeTranscript.tsnew file mode 100644index 000000000..7431c2419--- /dev/null+++ b/cli/src/engines/resumeTranscript.ts@@ -0,0 +1,129 @@+/** Materialize one cold history on Open, before the unchanged control-identity check.+ * Codex compresses old rollouts while retaining their logical .jsonl path. Treating that path's+ * absence as a lost conversation blocked a retained harness even though search still showed it.+ * Nothing here runs during discovery, and the archive remains available after any failure. */+import { randomUUID } from 'node:crypto'+import { closeSync, constants, createReadStream, createWriteStream, fstatSync, linkSync, lstatSync, openSync, unlinkSync, type BigIntStats } from 'node:fs'+import { dirname, join, basename } from 'node:path'+import { Transform } from 'node:stream'+import { pipeline } from 'node:stream/promises'+import * as zlib from 'node:zlib'+import { sessionStoreOf } from './sessionStoreContracts.js'+import { transcriptEvidence } from './transcriptBindings.js'+import { NativeFiles } from './kit/nativeFiles.js'+import { nativeFileKey, verifyNativePathFacts } from './kit/nativePaths.js'+import { firstLine, nativeSessionMeta } from './kit/nativeHeader.js'+import { IdentityReadUnavailable } from './kit/identityScan.js'+import { nativeUnavailable } from './kit/nativeEvidence.js'+import { completeZstdFrames } from './kit/zstdFrames.js'+import type { AgentEngine } from './types.js'++// All shipped runtimes have Node's streaming zstd decoder. Feature detection keeps older source+// installations usable for plain histories and gives compressed ones an actionable refusal.+const nativeZstd = zlib as typeof zlib & {+ createZstdDecompress?: (options: { params: Record<number, number> }) => Transform+}+const version = (info: BigIntStats) => `${nativeFileKey(info)}:${info.mode}:${info.uid}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`+const missing = (error: unknown) => (error as NodeJS.ErrnoException).code === 'ENOENT'+const exists = (path: string): boolean => {+ try { lstatSync(path); return true } catch (error) { if (missing(error)) return false; throw error }+}+const defaultLimits = { timeoutMs: 30_000, maxBytes: 4 * 1024 ** 3 }++/** Caller holds the stopped harness's resume reservation, has ruled out its previous writer, and+ * checks this returned path with controlTranscriptEvidence before allocating an engine. */+export async function materializeResumeTranscript(engine: AgentEngine, sessionId: string, path: string,+ profile: string | undefined, current: () => boolean, limits = defaultLimits,+): Promise<string> {+ const store = sessionStoreOf(engine), compression = store?.compression, first = store?.first+ if (!compression || !first) return path+ const plain = path.endsWith(compression.suffix) ? path.slice(0, -compression.suffix.length) : path+ if (!plain.endsWith(store.byId.suffix) || exists(plain) || !exists(plain + compression.suffix)) return plain+ if (!nativeZstd.createZstdDecompress) return nativeUnavailable('opening compressed history requires the current Harness runtime (Node 22.15 or newer)')++ let input: number | undefined, output: number | undefined, temporary: string | undefined+ const controller = new AbortController()+ const timer = setTimeout(() => controller.abort(), limits.timeoutMs)+ timer.unref()+ try {+ // Both paths must belong to the declared home; a dangling leaf alias is never an absent file.+ const destination = transcriptEvidence(engine, plain, profile, true)+ if (!destination.valid) return nativeUnavailable('the compressed conversation destination is outside its session home')+ destination.verify()+ const parent = destination.files.locate(dirname(plain))!+ const target = join(parent.path, basename(plain)), archive = target + compression.suffix+ const source = transcriptEvidence(engine, archive, profile)+ if (!source.valid) return nativeUnavailable('the compressed conversation is outside its session home')+ const location = source.files.file(archive)!+ // Parent aliases are checked above. A leaf alias could borrow a different archive's authority.+ if (location.path !== archive || !lstatSync(archive).isFile()) return nativeUnavailable('the compressed conversation must be a regular file beside its destination')+ source.verify()+ const facts = source.files.paths.snapshot()+ const parentFacts = destination.files.paths.snapshot().filter(fact => fact.path !== target && fact.path !== plain)+ const before = version(location.info)+ input = openSync(archive, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)+ if (version(fstatSync(input, { bigint: true })) !== before) return nativeUnavailable('the compressed conversation changed before reading')+ if (!current()) return nativeUnavailable('the resume was cancelled before restoring its conversation')+ const staging = join(parent.path, `.harness-restore-${randomUUID()}.tmp`)+ output = openSync(staging, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600)+ temporary = staging+ const temporaryKey = nativeFileKey(fstatSync(output, { bigint: true }))+ let total = 0, header = Buffer.alloc(0), verified = false+ const inspect = new Transform({ transform(chunk: Buffer, _encoding, done) {+ try {+ if (!current()) return nativeUnavailable('the resume was cancelled while restoring its conversation')+ total += chunk.length+ if (total > limits.maxBytes) return nativeUnavailable('the compressed conversation exceeds the restore size limit')+ if (!verified) {+ header = Buffer.concat([header, chunk.subarray(0, Math.max(0, first.maxBytes + 1 - header.length))])+ const complete = header.subarray(0, header.lastIndexOf(10) + 1)+ if (complete.toString('utf8').trim() || header.length > first.maxBytes) {+ const meta = nativeSessionMeta(firstLine(header, first.maxBytes), first)+ if (meta.id !== sessionId || meta.isSubagent) return nativeUnavailable('the compressed transcript names a different or delegated conversation')+ verified = true+ header = Buffer.alloc(0)+ }+ }+ done(null, chunk)+ } catch (error) { done(error as Error) }+ } })+ // Bound zstd's window to 64 MiB; the file itself is streamed to disk, never buffered in core.+ const decoder = nativeZstd.createZstdDecompress({ params: { 100: 26 } })+ const reader = createReadStream(archive, { fd: input, autoClose: true })+ input = undefined // The streams own their descriptors on success, abort and decoder failure.+ const writer = createWriteStream(temporary, { fd: output, autoClose: true, flush: true })+ output = undefined+ await pipeline(reader, completeZstdFrames(), decoder, inspect, writer, { signal: controller.signal })+ if (!verified) {+ const meta = nativeSessionMeta(firstLine(header, first.maxBytes), first)+ if (meta.id !== sessionId || meta.isSubagent) return nativeUnavailable('the compressed transcript names a different or delegated conversation')+ }+ if (!current()) return nativeUnavailable('the resume was cancelled before publishing its conversation')+ verifyNativePathFacts(facts)+ verifyNativePathFacts(parentFacts)+ // Re-earn the home's evidence after the asynchronous decode; its old work budget has expired.+ const fresh = transcriptEvidence(engine, archive, profile)+ if (!fresh.valid || version(fresh.files.file(archive)!.info) !== before) return nativeUnavailable('the compressed conversation changed during restoration')+ fresh.verify()+ const staged = new NativeFiles(), metadata = staged.header(temporary, first)+ if (nativeFileKey(staged.file(temporary)!.info) !== temporaryKey || metadata.id !== sessionId || metadata.isSubagent) {+ return nativeUnavailable('the restored conversation changed before publication')+ }+ staged.verify(temporary)+ // link is atomic and cannot overwrite a file another reader or Codex has already restored.+ try { linkSync(temporary, target) } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error+ // The caller earns fresh identity from the winner, which may be foreign or unreadable.+ }+ return plain+ } catch (error) {+ if (error instanceof IdentityReadUnavailable) throw error+ // Decoder and filesystem errors can contain paths or conversation bytes. Keep them private.+ return nativeUnavailable('the compressed conversation could not be restored completely; its archive has been retained')+ } finally {+ clearTimeout(timer)+ if (input !== undefined) closeSync(input)+ if (output !== undefined) closeSync(output)+ if (temporary !== undefined) unlinkSync(temporary)+ }+}diff --git a/cli/src/lib/resumeAgentService.spec.ts b/cli/src/lib/resumeAgentService.spec.tsindex fe7af69b2..2244a5f8a 100644--- a/cli/src/lib/resumeAgentService.spec.ts+++ b/cli/src/lib/resumeAgentService.spec.ts@@ -6,6 +6,7 @@ import { createResumeAgentService, type ResumeAgentServiceDeps } from './resumeAimport { RESUME_READINESS_BUDGET_MS } from './resumeStoppedAgent.js'import { registry, type RegisteredSession } from './registry.js'import { controlTranscriptEvidence } from '../engines/transcriptBindings.js'+import { materializeResumeTranscript } from '../engines/resumeTranscript.js'import { IdentityReadUnavailable } from '../engines/kit/identityScan.js'import { env } from '../config/env.js'import { StoppedAgentStore } from './stoppedAgents.js'@@ -44,6 +45,7 @@ vi.mock('./engineBin.js', () => ({ enginePathOverride: vi.fn(() => undefined) })vi.mock('./engineInstall.js', async original => ({ ...await original<object>(), engineInstallRecipe: () => ({ command: 'fixture-install' }) }))vi.mock('../dsh/installed.js', () => ({ installedDsh: vi.fn() }))vi.mock('../engines/transcriptBindings.js', async original => ({ ...await original<object>(), controlTranscriptEvidence: vi.fn() }))+vi.mock('../engines/resumeTranscript.js', () => ({ materializeResumeTranscript: vi.fn(async (_engine, _id, path) => path) }))let dir: stringlet saved: RegisteredSession@@ -103,6 +105,7 @@ beforeEach(() => {create.mockReset().mockResolvedValue({ state: 'succeeded', runtime: { backend: 'tmux', paneId: pane } })kill.mockReset().mockResolvedValue({ state: 'succeeded' })vi.mocked(controlTranscriptEvidence).mockImplementation((_engine, _id, path) => ({ path, verify: vi.fn() }))+ vi.mocked(materializeResumeTranscript).mockReset().mockImplementation(async (_engine, _id, path) => path)vi.mocked(enginePathOverride).mockReturnValue(undefined)vi.mocked(refusePermissionFlagIfUnsupported).mockReset().mockResolvedValue(null)vi.mocked(installedDsh).mockReturnValue(undefined)@@ -134,6 +137,41 @@ beforeEach(() => {afterEach(() => { vi.useRealTimers(); for (const row of registry.list()) registry.removeAgent(row.agentId); rmSync(dir, { recursive: true, force: true }) })describe('production resume handler', () => {+ it('holds the reservation and restores cold history before checking its control identity', async () => {+ const restored = join(dir, 'restored.jsonl')+ vi.mocked(materializeResumeTranscript).mockImplementation(async (_engine, _id, _path, _profile, current) => {+ expect(deps.stoppedAgents.resumeReservedAt(saved.agentId)).not.toBeNull()+ expect(current()).toBe(true)+ expect(controlTranscriptEvidence).not.toHaveBeenCalled()+ expect(create).not.toHaveBeenCalled()+ return restored+ })+ expect(await start()).toMatchObject({ ok: true })+ expect(controlTranscriptEvidence).toHaveBeenCalledWith('codex', saved.sessionId, restored, undefined, saved.cwd)+ })++ it('does not allocate when Stop cancels an asynchronous history restoration', async () => {+ vi.mocked(materializeResumeTranscript).mockImplementation(async (_engine, _id, path, _profile, current) => {+ deps.restartJobs.cancel(saved.agentId)+ expect(current()).toBe(false)+ return path+ })+ expect(await start()).toMatchObject({ error: 'AGENT_CHANGED' })+ expect(create).not.toHaveBeenCalled()+ expect(deps.stoppedAgents.resumeReservedAt(saved.agentId)).toBeNull()+ })++ it('restoration loses permission if another harness takes the conversation', async () => {+ vi.mocked(materializeResumeTranscript).mockImplementation(async (_engine, _id, _path, _profile, current) => {+ registry.resumePendingAgent({ ...saved, agentId: 'other' }, [{ backend: 'tmux', paneId: '%101' }])+ expect(current()).toBe(false)+ throw new IdentityReadUnavailable('another harness owns the conversation')+ })+ expect(await start()).toMatchObject({ error: 'IDENTITY_UNAVAILABLE' })+ expect(create).not.toHaveBeenCalled()+ expect(deps.stoppedAgents.resumeReservedAt(saved.agentId)).toBeNull()+ })+it('composes stopped resume with real launch preparation before any live row exists', async () => {const apiNotes = vi.fn()const helpers = createLaunchHelpers({diff --git a/cli/src/lib/resumeAgentService.ts b/cli/src/lib/resumeAgentService.tsindex bc87ee8e6..ed9c12b07 100644--- a/cli/src/lib/resumeAgentService.ts+++ b/cli/src/lib/resumeAgentService.ts@@ -5,6 +5,7 @@ import { isTerminalEngine } from '../engines/types.js'import { installedDsh } from '../dsh/installed.js'import { engineKeepsTranscriptFile, registry as liveRegistry, type RegisteredSession } from './registry.js'import { controlTranscriptEvidence } from '../engines/transcriptBindings.js'+import { materializeResumeTranscript } from '../engines/resumeTranscript.js'import { IdentityReadUnavailable } from '../engines/kit/identityScan.js'import type { StoppedAgentStore } from './stoppedAgents.js'import { resumeStoppedAgent, waitForResumedAgent, resumeChanged, resumeUnconfirmed, RESUME_READINESS_BUDGET_MS } from './resumeStoppedAgent.js'@@ -237,6 +238,16 @@ export function createResumeAgentService(deps: ResumeAgentServiceDeps) {let token: string | null = nulllet allocationAttempted = falsetry {+ // Reserve before materializing cold history too: two Open requests must not rewrite a+ // conversation an earlier, unconfirmed allocation might still be using.+ token = stoppedAgents.beginResume(agentId)+ if (!token) token = retakeStaleReservation(agentId)+ if (!token) return resumeUnconfirmed+ if (resumeSessionId && saved.transcriptPath) {+ saved = { ...saved, transcriptPath: await materializeResumeTranscript(saved.engine, resumeSessionId,+ saved.transcriptPath, saved.codexHome ?? undefined, () => current() && !registry.bySession(saved.sessionId)) }+ if (!current()) return resumeChanged+ }let transcript = sourceEvidence()if (transcript) saved = { ...saved, transcriptPath: transcript.path }let sourceError: unknown@@ -249,11 +260,6 @@ export function createResumeAgentService(deps: ResumeAgentServiceDeps) {try { transcript?.verify(); return true }catch (error) { sourceError = error; return false }}- // Reserve before preparing history or rewriting launch configuration: an unknown previous- // allocation may still have a writer using those files.- token = stoppedAgents.beginResume(agentId)- if (!token) token = retakeStaleReservation(agentId)- if (!token) return resumeUnconfirmedconst built = await relaunchOverrides(saved, saved, sourceCurrent)if (sourceError) throw sourceErrortranscript?.verify()