Improve session search indexing and cache freshness

- Preserve the read budget after slow discovery and resume deferred sweeps
  without repeated retention purges.
- Prefer newer compatible session snapshots and expire cached lists promptly.
This commit is contained in:
Jinjing
2026-11-09 12:59:59 -08:00
parent 42201201f5
commit d45017ca75
6 changed files with 201 additions and 31 deletions
@@ -488,6 +488,41 @@ it('stops the opening sweep at its deadline and drains the rest over the passes
expect(indexer?.status().lastSweepCompletedAt).not.toBeNull()
})
it('does not charge slow discovery against the read budget', async () => {
for (const session of [SESSION_ID, OTHER_SESSION_ID]) {
await writeClaudeTranscript(transcriptPath(session), [`changed session ${session}`], session)
}
await newIndexer({
passDeadlineMs: 5_000,
resolveRoots: async () => {
clock.advance(10_000)
return harness.roots
}
}).start()
expect(indexer?.status()).toMatchObject({ filesIndexed: 2, filesDue: 0, phase: 'current' })
})
it('leaves deferred recent reads to the next cycle instead of forcing a full sweep', async () => {
let sweeps = 0
await startAfterASweep({
...readsPerPass(1),
resolveRoots: async () => {
sweeps += 1
return harness.roots
}
})
for (const session of [SESSION_ID, OTHER_SESSION_ID]) {
await writeClaudeTranscript(transcriptPath(session), [`recent session ${session}`], session)
}
await nextCycle()
expect(sessionsMatching('recent')).toHaveLength(1)
await nextCycle()
expect(sessionsMatching('recent')).toHaveLength(2)
expect(sweeps).toBe(1)
})
it.skipIf(!CAN_DENY_READ)('retires a deleted file behind a block of unreadable rows', async () => {
// Keep the root nonempty so empty-root grace cannot mask retirement behavior.
await writeClaudeTranscript(transcriptPath(), ['a live conversation'], SESSION_ID)
@@ -60,6 +60,8 @@ export class SessionSearchIndexer {
private lastCounts: SessionSearchStateCounts | null = null
private cyclesSinceSweep = 0
private sweepNext = false
/** The queued sweep only resumes a deferred backlog, so retention needs no new purge. */
private resumingBacklog = false
private started = false
private closed = false
@@ -91,6 +93,7 @@ export class SessionSearchIndexer {
// Claim ownership before async initialization so another indexer cannot race the writer open.
this.store = new SessionSearchWorkerStore(options.databasePath, onError, () => {
this.sweepNext = true
this.resumingBacklog = false
})
liveIndexerPaths.add(this.ownershipPath)
this.store.setRetentionCutoffMs(this.cutoffMs())
@@ -115,7 +118,10 @@ export class SessionSearchIndexer {
if (!this.started) {
throw new Error('SessionSearchIndexer.reconcile: start() first')
}
this.sweepNext ||= options.full === true
if (options.full === true) {
this.sweepNext = true
this.resumingBacklog = false
}
return this.tick()
}
@@ -215,10 +221,11 @@ export class SessionSearchIndexer {
private async pass(signal: AbortSignal): Promise<void> {
// Refresh the cutoff each pass so purged transcripts cannot immediately be re-indexed.
this.store.setRetentionCutoffMs(this.cutoffMs())
const startedAt = this.clock.now()
const full = this.sweepNext
// Consume the flag before awaiting so requests arriving during this pass survive.
const purge = full && !this.resumingBacklog
// Consume the flags before awaiting so requests arriving during this pass survive.
this.sweepNext = false
this.resumingBacklog = false
try {
if (full && this.options.resolveRoots) {
const roots = await this.options.resolveRoots(signal)
@@ -231,24 +238,31 @@ export class SessionSearchIndexer {
store: this.store,
roots: this.roots,
full,
purge,
recentPerAgent: this.recentPerAgent,
previousRootsWithFiles: this.previousRootsWithFiles ?? undefined,
overdue: () => this.clock.now() - startedAt >= this.passDeadlineMs,
startReadDeadline: () => {
const readsStartedAt = this.clock.now()
return () => this.clock.now() - readsStartedAt >= this.passDeadlineMs
},
listings: new SessionSearchDirectoryListings(),
signal
})
if (!result.completed) {
// Preserve previous health findings and retry the sweep after an incomplete pass.
this.sweepNext ||= full
this.retrySweep(full, purge)
return
}
this.degradedRoots = result.degradedRoots
this.previousRootsWithFiles = result.rootsWithFiles
this.lastReconcileAt = this.clock.now()
this.left = result.left
// Repeat full discovery while backlogged so reads outside the recency window can progress.
this.sweepNext ||= result.outOfTime
if (full) {
// Repeat discovery while a sweep's backlog remains; recent cycles revisit their own deferred reads.
if (result.outOfTime && !this.sweepNext) {
this.sweepNext = true
this.resumingBacklog = true
}
// Deferred reads prevent a sweep from establishing that the index is current.
if (!result.outOfTime) {
this.lastSweepCompletedAt = this.lastReconcileAt
@@ -262,11 +276,19 @@ export class SessionSearchIndexer {
}
} catch (error) {
// Retry a failed sweep rather than waiting for the periodic cadence.
this.sweepNext ||= full
this.retrySweep(full, purge)
throw error
}
}
private retrySweep(full: boolean, purged: boolean): void {
if (!full || this.sweepNext) {
return
}
this.sweepNext = true
this.resumingBacklog = !purged
}
private cutoffMs(): number | null {
return sessionSearchHistoryCutoffMs(this.options.historyDays, this.clock.now())
}
@@ -37,8 +37,10 @@ export type SessionSearchPassArgs = {
recentPerAgent: number
/** Roots with transcripts on the previous pass; undefined before any observation. */
previousRootsWithFiles?: ReadonlySet<string>
/** The deadline stops transcript reads; discovery and retirement still finish. */
overdue?: () => boolean
/** Purge retention before discovery; defaults to `full`. */
purge?: boolean
/** Arms the read deadline once discovery ends, so slow discovery cannot spend the read budget. */
startReadDeadline?: () => () => boolean
/** Cache directory reads across discovery-health and retirement checks for this pass. */
listings: SessionSearchDirectoryReader
signal?: AbortSignal
@@ -61,7 +63,7 @@ export async function runSessionSearchPass(
): Promise<SessionSearchPassResult> {
const { store, signal } = args
await store.prepare?.()
if (args.full) {
if (args.purge ?? args.full) {
// Apply narrowed retention before the new instance’s first discovery.
await store.purgeOlderThan(store.retentionCutoff, signal)
}
@@ -80,7 +82,7 @@ export async function runSessionSearchPass(
const read = await runSessionSearchIndexPass(store, swept.candidates, {
signal,
rows,
overdue: args.overdue
overdue: args.startReadDeadline?.()
})
outOfTime = read.outOfTime
left = read.left
@@ -0,0 +1,78 @@
import { mkdtemp, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it, vi } from 'vitest'
import type { AiVaultScanOptions } from './session-scanner-types'
import { scanAiVaultSessions } from './session-scanner'
import { isolatedScanRoots, writeJsonlFile } from './session-scanner-test-fixtures'
const { scan } = vi.hoisted(() => ({ scan: vi.fn() }))
vi.mock('./scan-service/session-scanner-background', () => ({
scanAiVaultSessionsInBackground: scan,
clearAiVaultBackgroundRestartCircuit: () => {},
resetAiVaultScannerBackgroundForTests: () => {}
}))
vi.mock('../wsl/discovery/distro-catalog', () => ({
hasCachedWslDistros: () => true,
getCachedWslDistros: () => []
}))
import { listAiVaultSessions, resetAiVaultSessionListCacheForTests } from './cached-session-list'
let root: string | undefined
afterEach(async () => {
resetAiVaultSessionListCacheForTests()
scan.mockReset()
vi.useRealTimers()
if (root) {
await rm(root, { recursive: true, force: true })
root = undefined
}
})
it.each([250, 500])(
'uses the newer full-scope snapshot after a Project scan at depth %s',
async (projectDepth) => {
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(new Date('2026-11-09T12:00:00.000Z'))
const tempRoot = await mkdtemp(join(tmpdir(), 'orca-session-list-cache-'))
root = tempRoot
const roots = isolatedScanRoots(tempRoot)
scan.mockImplementation((options: AiVaultScanOptions, signal: AbortSignal) =>
scanAiVaultSessions({
...options,
...roots,
additionalCodexSessionsDirs: [],
wslHomeDirs: [],
claudeProfileProjectsDirs: [],
opencodeAccountDataDirs: [],
antigravityChatBrainDir: join(tempRoot, 'chat-brain'),
signal
})
)
const writeSession = (id: string, title: string) =>
writeJsonlFile(join(roots.claudeProjectsDir, '-repo', `${id}.jsonl`), [
{
type: 'user',
sessionId: id,
cwd: '/repo',
timestamp: '2026-11-09T11:00:00.000Z',
message: { role: 'user', content: title }
}
])
const scopePaths = ['/repo']
await writeSession('initial', 'Initial conversation')
await listAiVaultSessions({ scopePaths, scopeOnly: true, limit: projectDepth })
await writeSession('newer', 'Newer conversation')
await listAiVaultSessions({ scopePaths, limit: 500 })
await writeSession('after-snapshot', 'Later conversation')
const result = await listAiVaultSessions({ scopePaths, scopeOnly: true, limit: 500 })
expect(result.sessions.map((session) => session.title).sort()).toEqual([
'Initial conversation',
'Newer conversation'
])
}
)
+16 -15
View File
@@ -67,8 +67,10 @@ export type AiVaultSessionSources = {
const cachedLists = new SessionListScopeCache()
let scanCoordinator = new AiVaultScanCoordinator()
let sources: AiVaultSessionSources = {}
// Reject cache writes from scans that began before invalidation, or late results can resurrect deleted sessions.
let cacheGeneration = 0
// Fence cache writes from scans started before invalidation or a completed refresh.
let cacheWriteGeneration = 0
// Refresh fences cache writes; only invalidation splits aggregate requests already in flight.
let invalidationGeneration = 0
export function configureAiVaultSessionSources(next: AiVaultSessionSources): void {
sources = next
@@ -140,21 +142,19 @@ export async function listAiVaultSessions(
}
// A full list for the same paths holds every row a scope-only one would, so All -> Project needs no rescan.
const fullKey = args?.scopeOnly ? aiVaultLocalScanScopeKey({ ...args, scopeOnly: false }) : key
const cachedList = cachedLists.get(key, now) ?? cachedLists.get(fullKey, now)
if (
args?.force !== true &&
(cachedList?.key === key || cachedList?.key === fullKey) &&
cachedList.expiresAt > now &&
aiVaultCachedDepthServes(cachedList.depth, depth, args?.scopePaths)
) {
const cachedList = [cachedLists.get(key, now), cachedLists.get(fullKey, now)]
.filter((entry) => entry !== undefined)
.filter((entry) => aiVaultCachedDepthServes(entry.depth, depth, args?.scopePaths))
.sort((a, b) => b.revision - a.revision)[0]
if (args?.force !== true && cachedList) {
return truncateAiVaultListResult(cachedList.result, depth, args?.scopePaths)
}
// Capture before the coordinator's start microtask so intervening invalidation still rejects the result.
const startGeneration = cacheGeneration
const startGeneration = cacheWriteGeneration
let progress: LocalAiVaultScanProgressHandle | null = null
return scanCoordinator.run({
// Isolate invalidated scans without changing the key used by progress readers.
key: JSON.stringify({ scanKey, generation: startGeneration }),
key: JSON.stringify({ scanKey, generation: invalidationGeneration }),
force: args?.force,
signal: options.signal,
onCreate: (scanId) => {
@@ -188,10 +188,10 @@ export async function listAiVaultSessions(
wslConfirmed
)
// Return pre-invalidation results to their caller, but never repopulate the cache with them.
if (!scanSignal.aborted && startGeneration === cacheGeneration) {
if (!scanSignal.aborted && startGeneration === cacheWriteGeneration) {
if (args?.force === true) {
// A fresh host scan invalidates other scopes and fences older in-flight cache writes.
cacheGeneration++
cacheWriteGeneration++
cachedLists.clear()
}
const current = cachedLists.get(key, Date.now())
@@ -245,12 +245,13 @@ export async function getAiVaultWslHomeDirs(): Promise<string[]> {
}
export function aiVaultSessionListCacheGeneration(): number {
return cacheGeneration
return invalidationGeneration
}
// Invalidate cached results and disarm in-flight cache writes after deletion.
export function invalidateAiVaultSessionListCache(): void {
cacheGeneration++
invalidationGeneration++
cacheWriteGeneration++
cachedLists.clear()
// A deleted WSL session must not come back as a carried-over row.
resetAiVaultWslSessionCarryover()
+36 -4
View File
@@ -1,4 +1,5 @@
import { BoundedMap } from '../../shared/bounded-map'
import { MAX_TIMER_DELAY_MS } from '../../shared/timer-delay'
import type { AiVaultListResult } from '../../shared/ai-vault/contracts/ai-vault-types'
import type { AiVaultSessionDepth } from '../../shared/ai-vault/scanning/ai-vault-session-depth'
@@ -10,17 +11,20 @@ type CachedSessionList = {
}
const MAX_SCOPE_CACHE_BYTES = 32 * 1024 * 1024
type StoredSessionList = CachedSessionList & { revision: number }
export class SessionListScopeCache {
// Preserve the existing one-result cache even when an unlimited scan exceeds the archive budget.
private latest: CachedSessionList | null = null
private readonly previous = new BoundedMap<string, CachedSessionList>({
private latest: StoredSessionList | null = null
private revision = 0
private expiryTimer: ReturnType<typeof setTimeout> | null = null
private readonly previous = new BoundedMap<string, StoredSessionList>({
maxEntries: 7,
maxBytes: MAX_SCOPE_CACHE_BYTES,
sizeOf: (entry) => estimateEntryBytes(entry)
})
get(key: string, now: number): CachedSessionList | undefined {
get(key: string, now: number): StoredSessionList | undefined {
this.prune(now)
return this.latest?.key === key ? this.latest : this.previous.get(key)
}
@@ -32,14 +36,42 @@ export class SessionListScopeCache {
if (old && old.key !== entry.key) {
this.previous.set(old.key, old)
}
this.latest = entry
this.latest = { ...entry, revision: ++this.revision }
this.scheduleExpiry()
}
clear(): void {
if (this.expiryTimer !== null) {
clearTimeout(this.expiryTimer)
this.expiryTimer = null
}
this.latest = null
this.previous.clear()
}
private scheduleExpiry(): void {
if (this.expiryTimer !== null) {
clearTimeout(this.expiryTimer)
this.expiryTimer = null
}
let earliest = this.latest?.expiresAt ?? Infinity
for (const entry of this.previous.values()) {
earliest = Math.min(earliest, entry.expiresAt)
}
if (earliest === Infinity) {
return
}
this.expiryTimer = setTimeout(
() => {
this.expiryTimer = null
this.prune(Date.now())
this.scheduleExpiry()
},
Math.min(MAX_TIMER_DELAY_MS, Math.max(0, earliest - Date.now()))
)
this.expiryTimer.unref?.()
}
private prune(now: number): void {
if (this.latest && this.latest.expiresAt <= now) {
this.latest = null