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.

Reduce repeated saved-session catalog work (#538)

Dee7f5100622fd1
diff --git a/cli/scripts/benchmark-stopped-catalog.ts b/cli/scripts/benchmark-stopped-catalog.ts
new file mode 100644
index 000000000..4d61eecf4
--- /dev/null
+++ b/cli/scripts/benchmark-stopped-catalog.ts
@@ -0,0 +1,52 @@
+/** Synthetic saved-session catalog reads. Never reads or starts the user's sessions.
+ * Run: node --import tsx scripts/benchmark-stopped-catalog.ts [output.json]
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { performance } from 'node:perf_hooks'
+
+const root = mkdtempSync(join(tmpdir(), 'harness-catalog-bench-'))
+process.env.ADAPTER_DATA_DIR = root
+const { StoppedAgentStore } = await import('../src/lib/stoppedAgents.js')
+const summaries: Record<string, unknown>[] = []
+try {
+ for (const count of [32, 272, 1000]) {
+ const directory = join(root, String(count))
+ mkdirSync(directory, { mode: 0o700 })
+ for (let i = 0; i < count; i++) {
+ const row = { schemaVersion: 2, agentId: `saved-${i}`, sessionId: `conversation-${i}`,
+ engine: i % 2 ? 'claude' : 'codex', active: false, projectDir: '/synthetic/project',
+ cwd: '/synthetic/project', runtimes: [{ backend: 'tmux', paneId: `%${i}` }],
+ primaryRuntimeKey: `tmux\0%${i}`, tmuxPane: `%${i}`, processIdentity: null,
+ launch: { state: 'ready' }, title: `Saved task ${i}`, defaultName: `Project ${i}`,
+ registeredAt: 1, touchedAt: 2, lastHookAt: 1, lastTranscriptAt: 2, lastOpenedAt: 2,
+ transcriptPath: `/synthetic/history/${i}.jsonl`, permissionMode: 'ask',
+ source: 'hook', boundAt: 1, model: 'synthetic-model', cliVersion: 'fixture',
+ }
+ writeFileSync(join(directory, `${row.agentId}.json`), JSON.stringify({ version: 1, session: row }), { mode: 0o600 })
+ }
+ const store = new StoppedAgentStore(directory)
+ const started = performance.now()
+ if (store.list().length !== count) throw new Error('Cold catalog mismatch')
+ const coldMs = performance.now() - started
+ for (let i = 0; i < 5; i++) store.available([])
+ const cpu = process.cpuUsage()
+ const samples: number[] = []
+ for (let i = 0; i < 60; i++) {
+ const start = performance.now()
+ const rows = store.available([])
+ if (rows.length !== count || rows.some(row => row.active || !row.sessionId)) throw new Error('Warm catalog mismatch')
+ samples.push(performance.now() - start)
+ }
+ const used = process.cpuUsage(cpu)
+ samples.sort((a, b) => a - b)
+ summaries.push({ count, coldMs, reads: samples.length, warmMedianMs: samples[29], warmP95Ms: samples[56],
+ warmMaxMs: samples[59], cpuMs: (used.user + used.system) / 1000 })
+ }
+ const result = { kind: 'synthetic-saved-session-catalog', node: process.version,
+ platform: process.platform, arch: process.arch, summaries,
+ limitations: ['Synthetic metadata with a warm OS file cache.', 'Measures catalog reads, not whole-app CPU, display latency, or model processes.'] }
+ if (process.argv[2]) writeFileSync(process.argv[2], JSON.stringify(result, null, 2) + '\n')
+ console.log(JSON.stringify(result, null, 2))
+} finally { rmSync(root, { recursive: true, force: true }) }
diff --git a/cli/scripts/resume-native-e2e.ts b/cli/scripts/resume-native-e2e.ts
index 1629b620a..6c8112ad6 100644
--- a/cli/scripts/resume-native-e2e.ts
+++ b/cli/scripts/resume-native-e2e.ts
@@ -183,6 +183,17 @@ try {
const inventory = await rpc('agents_list', { includeStopped: true })
assert(inventory.agents.some((a: any) => a.id === old.agentId && a.status === 'stopped'))
const openSaved = async (creationId: string) => {
+ // Warm the same catalog used by status updates before each real resume.
+ // The action must revalidate disk state, and the resumed row must stop
+ // appearing among saved sessions without waiting for a cache timeout.
+ for (let i = 0; i < 2; i++) {
+ const savedInventory = await rpc('agents_list', { includeStopped: true })
+ const rows = savedInventory.agents.filter((a: any) => a.id === old.agentId)
+ assert.equal(rows.length, 1, 'the catalog must not duplicate or lose the conversation')
+ // After an external engine exit, this fixture intentionally leaves the
+ // old registry route until resume repairs it and preserves its shell.
+ if (!registry.advertised().some(row => row.agentId === old.agentId)) assert.equal(rows[0].status, 'stopped')
+ }
let settled = false, submitted = false, historyVisible = false
const hookCount = hooks.length
const nativeHookSeen = () => hooks.some(h => h.engine === engine && h.sessionId === sessionId)
@@ -217,6 +228,8 @@ try {
assert(settled, `${engine} did not confirm: ${readFileSync(join(root, `${engine}-screen.txt`), 'utf8')}`)
assert(historyVisible, `${engine} did not render the saved conversation`)
assert(!needHook || nativeHookSeen(), `${engine} did not send its native SessionStart`)
+ assert(!stoppedAgents.available(registry.advertised()).some(row => row.agentId === old.agentId),
+ 'a resumed conversation must immediately leave the saved catalog')
return opening
}
const creationId = randomUUID()
diff --git a/cli/src/authCommand.spec.ts b/cli/src/authCommand.spec.ts
index cbbcb4c67..151b30ad1 100644
--- a/cli/src/authCommand.spec.ts
+++ b/cli/src/authCommand.spec.ts
@@ -268,13 +268,19 @@ describe('harness auth status --json', () => {
expect(fp).toMatch(FP)
})
- it('leaves fingerprint out without a key, and never makes one by asking', () => {
+ // Each source-CLI startup gets its own test deadline. Combining two launches
+ // under one five-second limit repeatedly timed out on the shared CI runner.
+ it.each([
+ { state: 'signed out', signedIn: false },
+ { state: 'signed in', signedIn: true },
+ ])('leaves fingerprint out and never creates a key while $state', ({ signedIn }) => {
const root = tempRoot()
- const signedOut = runSync(root, ['auth', 'status', '--json'], 'http://127.0.0.1:1')
- expect(JSON.parse(signedOut.stdout.trim())).not.toHaveProperty('fingerprint')
- seedSession(root)
- const signedIn = runSync(root, ['auth', 'status', '--json'], 'http://127.0.0.1:1')
- expect(JSON.parse(signedIn.stdout.trim())).not.toHaveProperty('fingerprint')
+ if (signedIn) seedSession(root)
+ const result = runSync(root, ['auth', 'status', '--json'], 'http://127.0.0.1:1')
+ expect(result.status).toBe(0)
+ const body = JSON.parse(result.stdout.trim())
+ expect(body.loggedIn).toBe(signedIn)
+ expect(body).not.toHaveProperty('fingerprint')
expect(existsSync(identityFile(root))).toBe(false)
})
})
diff --git a/cli/src/lib/stoppedAgents.spec.ts b/cli/src/lib/stoppedAgents.spec.ts
index 6ce7870db..a6ab72df2 100644
--- a/cli/src/lib/stoppedAgents.spec.ts
+++ b/cli/src/lib/stoppedAgents.spec.ts
@@ -1,10 +1,10 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { chmodSync, constants, openSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
+import { chmodSync, constants, openSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import type { RegisteredSession } from './registry.js'
-vi.mock('node:fs', async original => { const fs = await original<typeof import('node:fs')>(); return { ...fs, openSync: vi.fn(fs.openSync) } })
+vi.mock('node:fs', async original => { const fs = await original<typeof import('node:fs')>(); return { ...fs, openSync: vi.fn(fs.openSync), readFileSync: vi.fn(fs.readFileSync) } })
let directory = ''
beforeEach(() => {
@@ -14,10 +14,166 @@ beforeEach(() => {
})
afterEach(() => {
vi.mocked(openSync).mockRestore()
+ vi.mocked(readFileSync).mockRestore()
vi.unstubAllEnvs()
rmSync(directory, { recursive: true, force: true })
})
+describe('saved catalog reads', () => {
+ it('does not reread unchanged records for status snapshots, but resume still reads the file', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const first = store.list()
+ vi.mocked(readFileSync).mockClear()
+ for (let i = 0; i < 20; i++) expect(store.available([])).toEqual(first)
+ expect(readFileSync).not.toHaveBeenCalled()
+ expect(store.get(saved.agentId)).toEqual(first[0])
+ expect(readFileSync).toHaveBeenCalledTimes(1)
+ })
+
+ it('keeps cached records private and filters the current live inventory on every call', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const [first] = store.list()
+ first.title = 'A caller changed this'
+ first.runtimes[0].paneId = '%999'
+ first.processIdentity!.pid = 1
+ expect(store.list()[0]).toMatchObject({ title: saved.title, runtimes: saved.runtimes, processIdentity: saved.processIdentity })
+ expect(store.available([saved])).toEqual([])
+ expect(store.available([])).toHaveLength(1)
+ })
+
+ it('periodically revalidates file contents and refreshes after a backwards clock change', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const now = Date.now()
+ const clock = vi.spyOn(Date, 'now').mockReturnValue(now)
+ try {
+ store.list()
+ vi.mocked(readFileSync).mockClear()
+ clock.mockReturnValue(now + 30_000)
+ expect(store.list()).toHaveLength(1)
+ expect(readFileSync).toHaveBeenCalledTimes(1)
+ vi.mocked(readFileSync).mockClear()
+ clock.mockReturnValue(now - 1)
+ expect(store.list()).toHaveLength(1)
+ expect(readFileSync).toHaveBeenCalledTimes(1)
+ } finally { clock.mockRestore() }
+ })
+
+ it('sees saves, patches, external replacements, in-place edits and deletion immediately', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ store.list()
+ store.patch(saved.agentId, { cwd: '/changed' })
+ expect(store.list()[0].cwd).toBe('/changed')
+ store.save({ ...saved, title: 'Updated title' })
+ expect(store.list()[0].title).toBe('Updated title')
+ const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
+ const replacement = `${file}.tmp`
+ const raw = JSON.parse(readFileSync(file, 'utf8'))
+ raw.session.title = 'External edit'
+ writeFileSync(replacement, JSON.stringify(raw), { mode: 0o600 })
+ renameSync(replacement, file)
+ expect(store.list()[0].title).toBe('External edit')
+ const before = statSync(file)
+ raw.session.title = 'External next' // Same length; restoring mtime must not conceal the edit.
+ writeFileSync(file, JSON.stringify(raw))
+ utimesSync(file, before.atime, before.mtime)
+ expect(store.list()[0].title).toBe('External next')
+ rmSync(file)
+ expect(store.list()).toEqual([])
+ store.save(saved)
+ expect(store.list()[0].sessionId).toBe(saved.sessionId)
+ })
+
+ it('drops a warmed record when corrupted, unsafe, or replaced by a symlink', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
+ const raw = readFileSync(file, 'utf8')
+ store.list()
+ writeFileSync(file, '{')
+ expect(store.list()).toEqual([])
+ writeFileSync(file, raw)
+ expect(store.list()).toHaveLength(1)
+ chmodSync(file, 0o666)
+ expect(store.list()).toEqual([])
+ expect(() => store.get(saved.agentId)).toThrow()
+ chmodSync(file, 0o600)
+ expect(store.list()).toHaveLength(1)
+ rmSync(file)
+ const target = join(directory, 'other.json')
+ writeFileSync(target, raw, { mode: 0o600 })
+ symlinkSync(target, file)
+ expect(store.list()).toEqual([])
+ expect(() => store.get(saved.agentId)).toThrow()
+ expect(readFileSync(target, 'utf8')).toBe(raw)
+ chmodSync(join(directory, 'stopped-agents'), 0o777)
+ expect(() => store.list()).toThrow()
+ })
+
+ it('does not cache a read under the identity of a replacement made during that read', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
+ const raw = JSON.parse(readFileSync(file, 'utf8'))
+ raw.session.title = 'Replacement'
+ const replacement = `${file}.tmp`
+ writeFileSync(replacement, JSON.stringify(raw), { mode: 0o600 })
+ const real = await vi.importActual<typeof import('node:fs')>('node:fs')
+ vi.mocked(readFileSync).mockImplementationOnce((...args: any[]) => {
+ const value = (real.readFileSync as (...args: any[]) => any)(...args)
+ renameSync(replacement, file)
+ return value
+ })
+ expect(store.list()[0].title).toBe(saved.title)
+ expect(store.list()[0].title).toBe('Replacement')
+ })
+
+ it('bounds retained bytes while keeping every large record visible and fresh', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const base = join(directory, 'stopped-agents')
+ rmSync(join(base, `${saved.agentId}.json`))
+ for (let i = 0; i < 10; i++) {
+ writeFileSync(join(base, `large-${i}.json`), JSON.stringify({ version: 1,
+ session: { ...saved, agentId: `large-${i}`, title: 'x'.repeat(512 * 1024) } }), { mode: 0o600 })
+ }
+ expect(store.list()).toHaveLength(10)
+ vi.mocked(readFileSync).mockClear()
+ expect(store.list()).toHaveLength(10)
+ // Ten half-megabyte files exceed the cache's byte budget; some must stay on disk.
+ expect(vi.mocked(readFileSync).mock.calls.length).toBeGreaterThan(0)
+ expect(vi.mocked(readFileSync).mock.calls.length).toBeLessThan(10)
+ for (let i = 0; i < 10; i++) rmSync(join(base, `large-${i}.json`))
+ expect(store.list()).toEqual([])
+ store.save(saved)
+ store.list()
+ vi.mocked(readFileSync).mockClear()
+ expect(store.list()).toHaveLength(1)
+ expect(readFileSync).not.toHaveBeenCalled()
+ })
+
+ it('bounds cached record count without thrashing or hiding a larger catalog', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const base = join(directory, 'stopped-agents')
+ rmSync(join(base, `${saved.agentId}.json`))
+ for (let i = 0; i < 2050; i++) {
+ const agentId = `bounded-${String(i).padStart(4, '0')}`
+ writeFileSync(join(base, `${agentId}.json`), JSON.stringify({ version: 1,
+ session: { ...saved, agentId } }), { mode: 0o600 })
+ }
+ expect(store.list()).toHaveLength(2050)
+ for (let pass = 0; pass < 2; pass++) {
+ vi.mocked(readFileSync).mockClear()
+ expect(store.list()).toHaveLength(2050)
+ expect(readFileSync).toHaveBeenCalledTimes(2)
+ }
+ })
+})
+
async function fixture() {
const { registry } = await import('./registry.js')
const { StoppedAgentStore } = await import('./stoppedAgents.js')
diff --git a/cli/src/lib/stoppedAgents.ts b/cli/src/lib/stoppedAgents.ts
index a1b13972a..e1e7bf192 100644
--- a/cli/src/lib/stoppedAgents.ts
+++ b/cli/src/lib/stoppedAgents.ts
@@ -1,5 +1,5 @@
/** Stopped work is durable history, separate from the registry of live terminal routes. */
-import { closeSync, constants, fsyncSync, openSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { closeSync, constants, fsyncSync, lstatSync, openSync, readdirSync, statSync, unlinkSync, writeFileSync, type BigIntStats } from 'node:fs'
import { randomUUID } from 'node:crypto'
import { dirname, join } from 'node:path'
import { env } from '../config/env.js'
@@ -8,7 +8,21 @@ import { atomicWriteJson, projectDisplayName, strictPersistedRow, type Registere
import { readPrivateStateFile, secureStateDirectory } from './secureState.js'
const SAFE_ID = /^[a-zA-Z0-9_-]{1,128}$/
+const CATALOG_CACHE_RECORDS = 2048
+const CATALOG_CACHE_BYTES = 4 * 1024 * 1024
+const CATALOG_CACHE_MS = 30_000
+
+function catalogFingerprint(stat: BigIntStats): string {
+ // ctime catches in-place edits even if a writer restores mtime. Inode/device
+ // distinguish atomic replacements; mode/owner/type changes must miss too.
+ return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.birthtimeNs,
+ stat.mode, stat.uid, stat.gid, stat.nlink].join(':')
+}
+
export class StoppedAgentStore {
+ private readonly catalogCache = new Map<string, { fingerprint: string; bytes: number; at: number; session: RegisteredSession }>()
+ private catalogCacheBytes = 0
+
constructor(private readonly directory = join(env.ADAPTER_DATA_DIR, 'stopped-agents')) {}
get(agentId: string): RegisteredSession | null {
@@ -28,21 +42,61 @@ export class StoppedAgentStore {
list(): RegisteredSession[] {
try {
secureStateDirectory(this.directory, false)
- return readdirSync(this.directory).filter(name => name.endsWith('.json')).flatMap(name => {
+ const ids = readdirSync(this.directory).filter(name => name.endsWith('.json')).map(name => name.slice(0, -5))
+ const present = new Set(ids)
+ for (const id of this.catalogCache.keys()) if (!present.has(id)) this.forgetCatalogRecord(id)
+ return ids.flatMap(id => {
try {
- const saved = this.get(name.slice(0, -5))
+ const saved = this.catalogRecord(id)
return saved ? [saved] : []
} catch {
+ this.forgetCatalogRecord(id)
// One unreadable record must not hide the other saved harnesses.
return []
}
})
} catch (error) {
+ this.catalogCache.clear()
+ this.catalogCacheBytes = 0
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
throw error
}
}
+ /** Status snapshots repeatedly enumerate the same saved metadata. Recheck
+ * every file's identity on every read, but only reopen/parse changed files.
+ * Actions still use get(), which always performs a fresh guarded read. */
+ private catalogRecord(agentId: string): RegisteredSession | null {
+ if (!SAFE_ID.test(agentId)) return null
+ const file = join(this.directory, `${agentId}.json`)
+ const before = lstatSync(file, { bigint: true })
+ const fingerprint = catalogFingerprint(before)
+ const cached = this.catalogCache.get(agentId)
+ const now = Date.now()
+ // Some mounted filesystems have coarse timestamps. Bound reuse even when
+ // their metadata cannot distinguish two writes; no background timer is needed.
+ if (cached?.fingerprint === fingerprint && now >= cached.at && now - cached.at < CATALOG_CACHE_MS) {
+ return structuredClone(cached.session)
+ }
+ this.forgetCatalogRecord(agentId)
+ const session = this.get(agentId)
+ const bytes = Number(before.size)
+ if (session && this.catalogCache.size < CATALOG_CACHE_RECORDS
+ && this.catalogCacheBytes + bytes <= CATALOG_CACHE_BYTES
+ && catalogFingerprint(lstatSync(file, { bigint: true })) === fingerprint) {
+ this.catalogCache.set(agentId, { fingerprint, bytes, at: now, session: structuredClone(session) })
+ this.catalogCacheBytes += bytes
+ }
+ return session
+ }
+
+ private forgetCatalogRecord(agentId: string): void {
+ const cached = this.catalogCache.get(agentId)
+ if (!cached) return
+ this.catalogCacheBytes -= cached.bytes
+ this.catalogCache.delete(agentId)
+ }
+
save(session: RegisteredSession): void {
if (!SAFE_ID.test(session.agentId)) throw new Error('Invalid stopped harness identity.')
// An exited engine leaves its pane as a shell. Stopping that shell must keep
@@ -73,6 +127,7 @@ export class StoppedAgentStore {
// A snapshot without a tmux pane omits the legacy alias just like registry persistence.
if (!snapshot.tmuxPane) delete (snapshot as Partial<RegisteredSession>).tmuxPane
atomicWriteJson(join(this.directory, `${session.agentId}.json`), { version: 1, session: snapshot })
+ this.forgetCatalogRecord(session.agentId)
}
/** Correct one field of an archive in place — the folder a Claude row drifted out of (cwdRepair.ts).
@@ -84,6 +139,7 @@ export class StoppedAgentStore {
secureStateDirectory(dirname(this.directory))
secureStateDirectory(this.directory)
atomicWriteJson(join(this.directory, `${agentId}.json`), { version: 1, session: { ...saved, ...patch } })
+ this.forgetCatalogRecord(agentId)
return true
}
diff --git a/docs/performance/2026-10-01-catalog-data/after.json b/docs/performance/2026-10-01-catalog-data/after.json
new file mode 100644
index 000000000..d1c695146
--- /dev/null
+++ b/docs/performance/2026-10-01-catalog-data/after.json
@@ -0,0 +1,39 @@
+{
+ "kind": "synthetic-saved-session-catalog",
+ "node": "v22.23.2",
+ "platform": "darwin",
+ "arch": "arm64",
+ "summaries": [
+ {
+ "count": 32,
+ "coldMs": 2.7702500000000043,
+ "reads": 60,
+ "warmMedianMs": 0.3396250000000123,
+ "warmP95Ms": 0.3986250000000098,
+ "warmMaxMs": 0.7107079999999826,
+ "cpuMs": 25.473
+ },
+ {
+ "count": 272,
+ "coldMs": 16.258791000000002,
+ "reads": 60,
+ "warmMedianMs": 2.3111670000000117,
+ "warmP95Ms": 2.6963329999999814,
+ "warmMaxMs": 3.0092500000000086,
+ "cpuMs": 153.82
+ },
+ {
+ "count": 1000,
+ "coldMs": 50.882124999999974,
+ "reads": 60,
+ "warmMedianMs": 8.314875000000029,
+ "warmP95Ms": 9.55766600000004,
+ "warmMaxMs": 9.943250000000035,
+ "cpuMs": 522.768
+ }
+ ],
+ "limitations": [
+ "Synthetic metadata with a warm OS file cache.",
+ "Measures catalog reads, not whole-app CPU, display latency, or model processes."
+ ]
+}
diff --git a/docs/performance/2026-10-01-catalog-data/before.json b/docs/performance/2026-10-01-catalog-data/before.json
new file mode 100644
index 000000000..2e00dcfcb
--- /dev/null
+++ b/docs/performance/2026-10-01-catalog-data/before.json
@@ -0,0 +1,39 @@
+{
+ "kind": "synthetic-saved-session-catalog",
+ "node": "v22.23.2",
+ "platform": "darwin",
+ "arch": "arm64",
+ "summaries": [
+ {
+ "count": 32,
+ "coldMs": 2.1812499999999773,
+ "reads": 60,
+ "warmMedianMs": 1.1652919999999654,
+ "warmP95Ms": 1.2583329999999933,
+ "warmMaxMs": 1.651625000000024,
+ "cpuMs": 85.175
+ },
+ {
+ "count": 272,
+ "coldMs": 11.692666999999972,
+ "reads": 60,
+ "warmMedianMs": 8.055000000000064,
+ "warmP95Ms": 9.360125000000039,
+ "warmMaxMs": 9.903082999999981,
+ "cpuMs": 504.729
+ },
+ {
+ "count": 1000,
+ "coldMs": 32.435249999999996,
+ "reads": 60,
+ "warmMedianMs": 30.811749999999847,
+ "warmP95Ms": 34.27866700000004,
+ "warmMaxMs": 37.59762500000011,
+ "cpuMs": 1892.008
+ }
+ ],
+ "limitations": [
+ "Synthetic metadata with a warm OS file cache.",
+ "Measures catalog reads, not whole-app CPU, display latency, or model processes."
+ ]
+}
diff --git a/docs/performance/2026-10-01-saved-session-catalog.md b/docs/performance/2026-10-01-saved-session-catalog.md
new file mode 100644
index 000000000..0bdf2fa12
--- /dev/null
+++ b/docs/performance/2026-10-01-saved-session-catalog.md
@@ -0,0 +1,73 @@
+# Saved-session catalog performance
+
+A 20-second CPU profile of the connected local development daemon identified
+repeated `StoppedAgentStore.list` / `get` calls during status updates. The host
+had 272 saved metadata files, totaling 324,006 bytes. That profile was taken
+against `0.3.41-dev.f7dd8bb4d` with desktop 1.2.38; it is evidence for selecting
+a code path, not a measurement of the released 0.3.42 / 1.2.39 pair.
+The temporary profiler was stopped and its loopback inspector was closed.
+
+## Change
+
+Catalog reads retain parsed metadata for unchanged files. Every enumeration
+still checks the private directory, enumerates its current filenames, and checks
+each file's identity, timestamps, permissions, ownership, and size. Changed files
+use the existing guarded reader and schema validation. Deletion and failed reads
+discard the cached entry; save and patch invalidate it immediately. The cache is
+limited to 2,048 records and 4 MiB of source JSON, and entries expire after 30 seconds
+when next requested. There is no new timer or watcher. The byte limit bounds source
+data retained, not exact JavaScript heap allocation.
+
+Actions such as Resume still call `get`, which always opens and validates the
+file afresh. Catalog callers receive independent copies and filter against the
+current live inventory, so resuming a conversation immediately hides its archive.
+Nanosecond ctime also catches in-place edits with a restored mtime; expiration
+bounds staleness on filesystems whose timestamps cannot distinguish such edits.
+
+## Local comparison
+
+The benchmark uses only synthetic metadata in a disposable private directory.
+Baseline: main `e2b867772`, before the cache. macOS arm64, Node 22.23.2, 60 warm
+reads after five warmups. This is one local before/after comparison with other
+applications running. All observed samples are retained.
+
+| Saved records | Warm median before → after | CPU for 60 reads before → after | First read before → after |
+| --- | --- | --- | --- |
+| 32 | 1.17 → 0.34 ms | 85.2 → 25.5 ms | 2.18 → 2.77 ms |
+| 272 | 8.06 → 2.31 ms | 504.7 → 153.8 ms | 11.69 → 16.26 ms |
+| 1,000 | 30.81 → 8.31 ms | 1,892.0 → 522.8 ms | 32.44 → 50.88 ms |
+
+Repeated-read CPU fell by about 70–72% for the larger two catalogs. First reads
+cost more because they populate and validate the cache; cold means an empty
+application cache, not an emptied OS file cache. These measurements do not establish
+a whole-app CPU or energy reduction, native display latency, a smaller model
+process, or the requested 100-fold reduction in total resources.
+
+Raw observations: [before](2026-10-01-catalog-data/before.json),
+[after](2026-10-01-catalog-data/after.json).
+
+Reproduce from `cli/`:
+
+```sh
+node --import tsx scripts/benchmark-stopped-catalog.ts /tmp/catalog-results.json
+```
+
+## Verification
+
+- Storage and lifecycle regression tests cover uncached Resume reads, caller
+ mutation, immediate save/patch/replacement/in-place-edit/delete visibility,
+ corrupt records, unsafe permissions, symlinks, replacement during a read,
+ expiry/backwards clocks, bounded retained bytes, and catalogs beyond the
+ record limit. Existing close, resume, checkpoint, secure-state, and cwd-repair
+ tests remain in the validation set.
+- The isolated native fixture warms the catalog before each resume and checks
+ that the row appears once and leaves the saved catalog immediately after resume.
+ Claude Code 2.1.286 and Codex 0.159.3 passed three close/checkpoint/resume cycles
+ each, same-conversation history restoration, live reattach, neighboring-pane
+ preservation, surviving-shell preservation, deferred-close persistence/cancel,
+ and automatic idle close for Claude. Only disposable profiles and a private
+ tmux server were used; the fixture cleaned them up.
+- The native fixture observed 232–235 MiB of Claude process-tree RSS and 171–173 MiB
+ of Codex process-tree RSS released per close. This verifies existing close
+ behavior survives the cache; it is not an additional memory saving from caching.
+- Native desktop rendering was unchanged and was not re-benchmarked in this pass.