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
Reduce repeated saved-session catalog work (#538)
Dee7f5100622fd1
diff --git a/cli/scripts/benchmark-stopped-catalog.ts b/cli/scripts/benchmark-stopped-catalog.tsnew file mode 100644index 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.tsindex 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 = falseconst hookCount = hooks.lengthconst 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.tsindex 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.tsindex 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.tsindex 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 Registereimport { 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 = 0if ((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>).tmuxPaneatomicWriteJson(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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.