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.

Restore compressed Codex histories when reopening retained harnesses (#1600)

Dee14f2cf12aac7
diff --git a/cli/e2e/ends.e2e.ts b/cli/e2e/ends.e2e.ts
index 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.ts
index 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. Read
diff --git a/cli/src/engines/facets/sessionStore.ts b/cli/src/engines/facets/sessionStore.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 './resumeA
import { 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: string
let 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.ts
index 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 = null
let allocationAttempted = false
try {
+ // 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 resumeUnconfirmed
const built = await relaunchOverrides(saved, saved, sourceCurrent)
if (sourceError) throw sourceError
transcript?.verify()