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.

Session search: find any harness by what was said in it, on every machine (#368)

Deeaeb501514b2c
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 3cf098ac5..e4faecbf3 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -489,6 +489,39 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('answers session_search from the index, sealed to the requester', async () => {
+ const socket = new BackendSocket('token')
+ const asked: Array<[string, number | undefined]> = []
+ socket.sessionSearchProvider = (query, options) => {
+ asked.push([query, options.limit])
+ return { hits: [], indexed: 3, pending: 0, tookMs: 1 }
+ }
+ socket.connect()
+ const ws = wsMock.instances[0]
+ ws.open()
+ const unwrap = vi.spyOn(socket.e2ee, 'unwrapDown')
+ vi.spyOn(socket.e2ee, 'hasSession').mockReturnValue(true)
+ const wrapReply = vi.spyOn(socket.e2ee, 'wrapRpcReply').mockReturnValue({
+ type: 'session_search_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
+ })
+ const envelope = { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } }
+ unwrap.mockReturnValueOnce({ type: 'session_search', payload: { requestId: 's-1', query: 'dial scroll', limit: 12 } })
+ ws.message({ t: 'down', connId: 'web-1', frame: { type: 'session_search', payload: envelope } })
+ await vi.waitFor(() => {
+ expect(wrapReply).toHaveBeenCalledWith('web-1', 'session_search_result', 's-1', { hits: [], indexed: 3, pending: 0, tookMs: 1 })
+ })
+ expect(asked).toEqual([['dial scroll', 12]])
+
+ // A machine whose Node has no node:sqlite says so rather than going silent.
+ socket.sessionSearchProvider = null
+ unwrap.mockReturnValueOnce({ type: 'session_search', payload: { requestId: 's-2', query: 'dial' } })
+ ws.message({ t: 'down', connId: 'web-1', frame: { type: 'session_search', payload: envelope } })
+ await vi.waitFor(() => {
+ expect(wrapReply).toHaveBeenCalledWith('web-1', 'session_search_result', 's-2', { error: 'SEARCH_UNAVAILABLE' })
+ })
+ await socket.stop()
+ })
+
it('hands theme_set to the host-theme sink and acknowledges it to the requester', async () => {
const socket = new BackendSocket('token')
const received: unknown[] = []
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index faf9869ca..78534b11b 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -113,6 +113,7 @@ import { shouldReplayCommander } from './lib/commanderReplay.js'
import { RuntimeProfileControlError, type RuntimeProfileErrorCode } from './lib/runtimeProfileController.js'
import { parseRuntimeProfile, type RuntimeModelOption } from './lib/runtimeProfile.js'
import { sid, preview, logFrame } from './lib/log.js'
+import type { SessionSearchResult } from './lib/sessionSearch/indexer.js'
import {
TerminalP2pResponderPool,
TERMINAL_P2P_DOWN_TYPES,
@@ -618,6 +619,9 @@ export class BackendSocket {
recentProvider: RecentProvider | null = null
/** The person's own last questions for an agent, newest first. See the `agent_recent` case. */
recentAsksProvider: ((agentId: string, n: number) => string[]) | null = null
+ /** Answers `session_search` from this machine's transcript index (lib/sessionSearch/). Null when
+ * this Node has no `node:sqlite`. */
+ sessionSearchProvider: ((query: string, options: { limit?: number; from?: number; to?: number }) => SessionSearchResult) | null = null
/** Runtime Model/Effort integration, wired by cli.ts for registered tmux sessions. */
runtimeModelsProvider: ((sessionId?: string) => Promise<RuntimeModelOption[]>) | null = null
/** Answers `usage_read` — this machine's own agent-account usage (lib/accountUsage.ts). A field
@@ -2732,6 +2736,19 @@ export class BackendSocket {
return
}
+ // Every conversation on this machine, searched by what was said in it (lib/sessionSearch/).
+ // Synchronous and a few milliseconds: the index is local SQLite FTS5. The words searched for
+ // arrive sealed and the hits leave sealed — the relay reads neither.
+ case 'session_search': {
+ if (!this.sessionSearchProvider) { reply(type, requestId, { error: 'SEARCH_UNAVAILABLE' }); return }
+ const query = typeof payload.query === 'string' ? payload.query.slice(0, 500) : ''
+ const number = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : undefined
+ // `from`/`to`: only sessions worked on in that window (epoch ms) — "the dial one from last
+ // week". The client reads the time words, so every machine searches the same window.
+ reply(type, requestId, { ...this.sessionSearchProvider(query, { limit: number(payload.limit), from: number(payload.from), to: number(payload.to) }) })
+ return
+ }
+
// The colours the desktop paints its panes with, so tmux answers a TUI's OSC 10/11 with
// them instead of with whatever terminal happened to attach first (lib/hostTheme.ts).
case 'theme_set': {
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 9997fe46c..bacc4adb4 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -93,6 +93,9 @@ import { restoreAgents } from './lib/restoreAgents.js'
import { createRetainExitedSession } from './lib/retainExitedSession.js'
import { repairClaudeCwd } from './lib/cwdRepair.js'
import { stoppedAgents } from './lib/stoppedAgents.js'
+import { SessionSearchIndex, folderWords, type SearchSource } from './lib/sessionSearch/indexer.js'
+import { SessionSearchStore } from './lib/sessionSearch/store.js'
+import { SESSION_SEARCH_FILE, searchCommand } from './lib/sessionSearch/command.js'
import { sweepWorktrees } from './lib/worktreeSweep.js'
import { nameBranchAfterSession } from './lib/branchNaming.js'
import { forgetAgentProject } from './lib/agentProject.js'
@@ -199,9 +202,9 @@ import { CursorTaskHookQueue } from './engines/cursor/taskHookQueue.js'
import { loadCursorPendingTasks, removeCursorPendingTasks } from './engines/cursor/pendingTasks.js'
import { OpencodeReader, readOpencodeMessages } from './engines/opencode/reader.js'
import { opencodeModelFromArgv, setOpencodeSessionModel } from './engines/opencode/sessionModel.js'
-import { lastOpencodeTurnText } from './engines/opencode/normalizer.js'
+import { lastOpencodeTurnText, opencodeMessagesToEvents } from './engines/opencode/normalizer.js'
import { KiloReader, readKiloMessages } from './engines/kilo/reader.js'
-import { lastKiloTurnText } from './engines/kilo/normalizer.js'
+import { kiloMessagesToEvents, lastKiloTurnText } from './engines/kilo/normalizer.js'
import { MuseNormalizer, lastMuseTurnText, museMessagesToEvents } from './engines/muse/normalizer.js'
import { AmpNormalizer, lastAmpTurnText, ampMessagesToEvents } from './engines/amp/normalizer.js'
import { GrokNormalizer, lastGrokTurnText } from './engines/grok/normalizer.js'
@@ -215,8 +218,8 @@ import { PiNormalizer, lastPiTurnText } from './engines/pi/normalizer.js'
import { HermesReader, readHermesMessages } from './engines/hermes/reader.js'
import { hermesDbForSession } from './lib/hermesHome.js'
import { DevinReader, readDevinMessages } from './engines/devin/reader.js'
-import { lastHermesTurnText } from './engines/hermes/normalizer.js'
-import { lastDevinTurnText } from './engines/devin/normalizer.js'
+import { hermesMessagesToEvents, lastHermesTurnText } from './engines/hermes/normalizer.js'
+import { devinMessagesToEvents, lastDevinTurnText } from './engines/devin/normalizer.js'
import {
CommandCodeNormalizer,
commandCodeRunError,
@@ -377,6 +380,8 @@ Machine:
harness new [agent] [@machine] [folder|name] [-- task]
make a harness from a shell: \`harness new\` is claude here; see \`harness new -h\`
harness machines list the machines on this account (this computer's is marked)
+ harness search <words> find the conversation on this computer that said them: every turn of
+ every session, live or stopped (--limit=N, --json)
harness machines delete <id> remove ANOTHER machine (refuses this one; use \`harness logout\`)
harness remote from a Harness terminal tile: open a terminal on another of your machines and move this tile to it
harness version print the installed version (v${VERSION})
@@ -2783,6 +2788,57 @@ async function runForeground(session: AuthSession | null): Promise<void> {
backend.recentProvider = (id, n) => mirror.recent(registry.resolve(id)?.sessionId || stoppedAgents.get(id)?.sessionId || id, n)
backend.recentAsksProvider = (id, n) => mirror.recentAsks(registry.resolve(id)?.sessionId || stoppedAgents.get(id)?.sessionId || id, n)
+ // The engines that keep a conversation in a database instead of a transcript file, read through
+ // the same readers and replay normalizers as `session_get`.
+ const databaseHistory = (s: RegisteredSession): (() => Promise<readonly LiveEvent[]>) | undefined => {
+ switch (s.engine) {
+ case 'opencode': return async () => opencodeMessagesToEvents(await readOpencodeMessages(join(env.OPENCODE_DATA_DIR, 'opencode.db'), s.sessionId))
+ case 'kilo': return async () => kiloMessagesToEvents(await readKiloMessages(join(env.KILO_DATA_DIR, 'kilo.db'), s.sessionId))
+ case 'devin': return async () => devinMessagesToEvents(await readDevinMessages(join(env.DEVIN_HOME, 'sessions.db'), s.sessionId))
+ case 'hermes': return async () => hermesMessagesToEvents(await readHermesMessages(await hermesDbForSession(s), s.sessionId))
+ default: return undefined
+ }
+ }
+
+ // Session search: every turn of every conversation on this machine, live and stopped, indexed from
+ // its transcript and searched by `session_search` (lib/sessionSearch/). Nothing leaves the machine
+ // but the hits for a query. A Node without `node:sqlite` has no index; the RPC then says so.
+ const sessionSearch = (() => {
+ try {
+ const store = SessionSearchStore.open(join(env.ADAPTER_DATA_DIR, SESSION_SEARCH_FILE))
+ if (!store) {
+ console.warn('[search] node:sqlite is not available on this Node — session search is off')
+ return null
+ }
+ const index = new SessionSearchIndex({
+ store,
+ sources: () => [...registry.list(), ...stoppedAgents.list()].flatMap((s): SearchSource[] => {
+ const readHistory = s.transcriptPath ? undefined : databaseHistory(s)
+ if (!s.sessionId || (!s.transcriptPath && !readHistory)) return []
+ return [{
+ agentId: s.agentId,
+ sessionId: s.sessionId,
+ engine: s.engine,
+ transcriptPath: s.transcriptPath || null,
+ header: [projectDisplayName(s), s.title, folderWords(s.cwd)].filter(Boolean).join(' · '),
+ // Conversation stamps only (lib/agentFrame.ts lastActivityAt): the registry's own
+ // updatedAt moves on every discovery pass.
+ updatedAt: Math.max(s.lastTranscriptAt || 0, s.lastHookAt || 0) || s.boundAt || s.registeredAt || 0,
+ readHistory,
+ }]
+ }),
+ agents: () => [...registry.list(), ...stoppedAgents.list()].map((s) => s.agentId),
+ log: (line) => console.log(line),
+ })
+ index.start()
+ return index
+ } catch (error) {
+ console.error('[search] could not open the session index:', error instanceof Error ? error.message : error)
+ return null
+ }
+ })()
+ backend.sessionSearchProvider = sessionSearch ? (query, options) => sessionSearch.search(query, options) : null
+
const runtimeController = new RuntimeProfileController({
manager: runtimeProfiles,
getSession: (id) => registry.resolve(id),
@@ -2898,6 +2954,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
if (isSubagentSession(sessionId)) frame.subagent = true
}
backend.send(frame)
+ if (event.type === 'turn_started' || event.type === 'turn_ended') sessionSearch?.touch(sessionId)
if (event.type === 'turn_started') {
turnStartedAt.set(sessionId, Date.now())
console.log(`[turn] ${sid(sessionId)} started · engine=${registry.bySession(sessionId)?.engine ?? 'claude'} · bytes=${Buffer.byteLength(event.payload.userMessage, 'utf8')}`)
@@ -6321,6 +6378,10 @@ function clearAdapterState(): void {
'summaries.json',
'summary-scratch',
'e2e',
+ // The session search index (lib/sessionSearch/): rebuilt from the transcripts on the next start.
+ SESSION_SEARCH_FILE,
+ `${SESSION_SEARCH_FILE}-wal`,
+ `${SESSION_SEARCH_FILE}-shm`,
]) {
rmSync(join(dir, name), { recursive: true, force: true })
}
@@ -7181,6 +7242,15 @@ switch (cmd) {
error: (line) => console.error(line),
}).then((code) => { process.exitCode = code }).catch(onError)
break
+ case 'search':
+ process.exitCode = searchCommand({
+ argv: rest,
+ dataDir: env.ADAPTER_DATA_DIR,
+ output: (line) => console.log(line),
+ error: (line) => console.error(line),
+ color: process.stdout.isTTY === true,
+ })
+ break
case 'machines':
if (!args[0]) machinesListCommand(flags.includes('--json')).catch(onError)
else if (args[0] === 'list') machinesListCommand(flags.includes('--json')).catch(onError)
diff --git a/cli/src/lib/e2ee/core.test.ts b/cli/src/lib/e2ee/core.test.ts
index 461646b91..b6df06299 100644
--- a/cli/src/lib/e2ee/core.test.ts
+++ b/cli/src/lib/e2ee/core.test.ts
@@ -146,6 +146,9 @@ describe('e2ee core — codes + fingerprint + classification', () => {
// The desktop's pane colours ride the same path; a miss here is the same silent timeout.
expect(C.isEncryptedDownType('theme_set')).toBe(true)
expect(C.isEncryptedRpcResultType('theme_set_result')).toBe(true)
+ // What somebody searches their conversations for, and what the search finds in them.
+ expect(C.isEncryptedDownType('session_search')).toBe(true)
+ expect(C.isEncryptedRpcResultType('session_search_result')).toBe(true)
expect(C.ENCRYPTED_RPC_RESULT_TYPES.has('session_get_result')).toBe(true)
expect(C.ENCRYPTED_RPC_RESULT_TYPES.has('agents_list_result')).toBe(true)
expect(C.ENCRYPTED_RPC_RESULT_TYPES.has('agent_update_result')).toBe(true)
@@ -221,6 +224,6 @@ describe('e2ee core — interop keystone', () => {
it('core.ts still hashes to the pinned value shared with the other implementations', () => {
const here = dirname(fileURLToPath(import.meta.url))
const actual = createHash('sha256').update(readFileSync(join(here, 'core.ts'))).digest('hex')
- expect(actual).toBe('3b5b79f18c6f6346b7d87da26d424402f81b9d1608a2c26dee62eb3287c9ca36')
+ expect(actual).toBe('39beea58aeb717dce493f91096a501a9f1a9637361a3accbabe6335faaaecdc4')
})
})
diff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.ts
index 46e8c9fa3..14043eb09 100644
--- a/cli/src/lib/e2ee/core.ts
+++ b/cli/src/lib/e2ee/core.ts
@@ -363,6 +363,8 @@ export const ENCRYPTED_RPC_RESULT_TYPES = new Set<string>([
// targeted at the requester rather than broadcast — and so a daemon that predates the type is
// told apart by silence, exactly like `usage_read`.
'theme_set_result',
+ // Session search hits: what was said in this machine's conversations, around the searched words.
+ 'session_search_result',
])
/** Client→adapter frames that carry or can trigger adapter-local user data. */
export const ENCRYPTED_DOWN_TYPES = new Set<string>([
@@ -385,6 +387,9 @@ export const ENCRYPTED_DOWN_TYPES = new Set<string>([
// The desktop's pane colours for this machine's tmux sessions (lib/hostTheme.ts). Same trap as
// above if missing: the envelope would never be opened and the app would wait out its timeout.
'theme_set',
+ // What somebody is searching their conversations for (lib/sessionSearch/). Same trap as above if
+ // missing: the envelope would never be opened and the app would wait out its timeout.
+ 'session_search',
'device_e2ee_pair', 'e2ee_pairings_list', 'e2ee_pairing_unpair',
'e2ee_pairings_unpair_all', 'e2ee_browser_link_create',
// Remote terminal control is always pairwise E2EE. The relay may route by outer type/connId but must
diff --git a/cli/src/lib/sessionSearch/command.spec.ts b/cli/src/lib/sessionSearch/command.spec.ts
new file mode 100644
index 000000000..aba0ebd29
--- /dev/null
+++ b/cli/src/lib/sessionSearch/command.spec.ts
@@ -0,0 +1,76 @@
+import { mkdtempSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { SESSION_SEARCH_FILE, searchCommand } from './command.js'
+import { SessionSearchStore } from './store.js'
+
+const NOW = Date.parse('2026-09-26T12:00:00Z')
+const dirs: string[] = []
+afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+function run(argv: string[], dataDir: string, color = false) {
+ const out: string[] = []
+ const err: string[] = []
+ const code = searchCommand({ argv, dataDir, output: (line) => out.push(line), error: (line) => err.push(line), color, now: NOW })
+ return { code, out, err }
+}
+
+function indexed(): string {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const store = SessionSearchStore.open(join(dir, SESSION_SEARCH_FILE))!
+ store.writeSession({
+ sessionId: 's1', agentId: 'agent-12345678', engine: 'claude', path: '/t', header: 'Mobile app · Mobile app build · app code',
+ size: 1, mtime: 1, resumeOffset: 0, resumeTurn: 0, lastAt: NOW - 2 * 3_600_000, turns: 0,
+ }, 0, [{ turn: 0, offset: 0, at: NOW - 3 * 86_400_000, ask: 'swipe right should open Find', answer: '', tools: '' }])
+ store.close()
+ return dir
+}
+
+describe('harness search', () => {
+ it('prints each session with where it said the words', () => {
+ const dir = indexed()
+ expect(run(['swipe'], dir)).toEqual({ code: 0, err: [], out: ['Mobile app 3d ago · agent-12', ' > swipe right should open Find'] })
+ expect(run(['swipe'], dir, true).out[1]).toBe(' > \x1b[1mswipe\x1b[22m right should open Find')
+ expect(run(['nothing-here'], dir).out).toEqual(['Nothing on this computer mentions "nothing-here".'])
+ const json = JSON.parse(run(['swipe', '--json'], dir).out[0])
+ expect(json.hits[0]).toMatchObject({
+ name: 'Mobile app', sessionId: 's1', field: 'ask',
+ snippet: 'swipe right should open Find', matches: [[0, 5]],
+ })
+ // `--limit N` is a flag and its value, not a search word.
+ expect(run(['swipe', '--limit', '1'], dir).out[0]).toBe('Mobile app 3d ago · agent-12')
+ })
+
+ it('reads a time in the words as when the session was worked on', () => {
+ const dir = indexed()
+ // The turn was three days before NOW; the session was last worked on two hours before.
+ expect(run(['swipe', '3', 'days', 'ago'], dir).out[0]).toBe('Mobile app 3d ago · agent-12')
+ expect(run(['swipe', 'yesterday'], dir).out).toEqual(['Nothing on this computer mentions "swipe" yesterday.'])
+ expect(run(['3', 'days', 'ago'], dir).out[1]).toBe(' > swipe right should open Find')
+ expect(run(['yesterday'], dir).out).toEqual(['Nothing on this computer was worked on yesterday.'])
+ })
+
+ it('never rewrites an index another version of the daemon owns', () => {
+ const dir = indexed()
+ const path = join(dir, SESSION_SEARCH_FILE)
+ const raw = SessionSearchStore.open(path)!
+ ;(raw as unknown as { db: { exec(sql: string): void } }).db.exec("UPDATE meta SET value = 'future' WHERE key = 'schema'")
+ raw.close()
+ expect(run(['swipe'], dir)).toMatchObject({ code: 1, err: [expect.stringContaining('another version')] })
+ expect(statSync(path).size).toBeGreaterThan(0)
+ const after = SessionSearchStore.openReader(path)
+ expect(after).toBe('outdated')
+ })
+
+ it('explains a missing index and a bad invocation', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ expect(run(['swipe'], dir)).toMatchObject({ code: 1, err: [expect.stringContaining('No session index yet')] })
+ expect(run([], dir)).toMatchObject({ code: 2, err: [expect.stringContaining('usage')] })
+ expect(run(['x', '--limit=0'], dir).code).toBe(2)
+ })
+})
diff --git a/cli/src/lib/sessionSearch/command.ts b/cli/src/lib/sessionSearch/command.ts
new file mode 100644
index 000000000..c5980231a
--- /dev/null
+++ b/cli/src/lib/sessionSearch/command.ts
@@ -0,0 +1,117 @@
+/**
+ * `harness search <words>` — the session index from a shell: which conversation on this computer
+ * said these words, and where. Reads the index the daemon keeps; never contacts it or a machine.
+ */
+
+import { join } from 'node:path'
+
+import { MARK_CLOSE, MARK_OPEN, SessionSearchStore } from './store.js'
+import { parseSearchWhen } from './when.js'
+
+export const SESSION_SEARCH_FILE = 'session-search.db'
+
+export interface SearchCommandOptions {
+ argv: string[]
+ dataDir: string
+ output: (line: string) => void
+ error: (line: string) => void
+ /** Bold the matched words (a terminal) or leave them plain (a pipe). */
+ color?: boolean
+ now?: number
+}
+
+const USAGE = 'usage: harness search <words> [last week | yesterday | 3 days ago | on monday …] [--limit N] [--json]'
+
+function age(at: number | null, now: number): string {
+ if (at === null) return ''
+ const minutes = Math.max(0, Math.round((now - at) / 60_000))
+ if (minutes < 60) return `${minutes}m ago`
+ if (minutes < 48 * 60) return `${Math.round(minutes / 60)}h ago`
+ return `${Math.round(minutes / 1440)}d ago`
+}
+
+function plainSnippet(marked: string): { snippet: string; matches: Array<[number, number]> } {
+ let snippet = ''
+ const matches: Array<[number, number]> = []
+ let open = -1
+ for (const char of marked) {
+ if (char === MARK_OPEN) open = snippet.length
+ else if (char === MARK_CLOSE) {
+ if (open >= 0) matches.push([open, snippet.length])
+ open = -1
+ } else snippet += char
+ }
+ return { snippet, matches }
+}
+
+export function searchCommand(opts: SearchCommandOptions): number {
+ const words: string[] = []
+ let json = false
+ let limit = 10
+ for (let index = 0; index < opts.argv.length; index++) {
+ const arg = opts.argv[index]
+ if (arg === '--json') json = true
+ else if (arg.startsWith('--limit=')) limit = Number(arg.slice('--limit='.length))
+ else if (arg === '--limit') limit = Number(opts.argv[++index])
+ else if (arg.startsWith('--')) limit = Number.NaN
+ else words.push(arg)
+ }
+ if (!words.length || !Number.isInteger(limit) || limit < 1) {
+ opts.error(USAGE)
+ return 2
+ }
+ // Read-only beside the daemon, which owns the index: this never migrates or deletes it.
+ const store = SessionSearchStore.openReader(join(opts.dataDir, SESSION_SEARCH_FILE))
+ if (store === 'missing') {
+ opts.error('No session index yet. The daemon builds it in the background after `harness start`.')
+ return 1
+ }
+ if (store === 'outdated') {
+ opts.error('The session index is from another version of Harness. Restart the daemon (`harness stop`, then `harness start`) to rebuild it.')
+ return 1
+ }
+ if (store === 'busy') {
+ opts.error('The session index is busy being written. Try again in a moment.')
+ return 1
+ }
+ if (store === 'unreadable') {
+ opts.error('The session index could not be read. The daemon rebuilds it on its next start (`harness stop`, then `harness start`).')
+ return 1
+ }
+ if (!store) {
+ opts.error('Session search needs node:sqlite (Node 22.13 or later).')
+ return 1
+ }
+ try {
+ const now = opts.now ?? Date.now()
+ // "dial last week": the same time phrases Cmd-P reads, as a window.
+ const { words: query, when } = parseSearchWhen(words.join(' '), new Date(now))
+ const hits = store.search(query, { limit, now, from: when?.from, to: when?.to }).map((hit) => ({
+ ...hit,
+ name: store.session(hit.sessionId)?.header.split(' · ')[0] ?? hit.sessionId,
+ }))
+ if (json) {
+ // Plain text for scripts, with the matched words as [start, end) ranges rather than the
+ // control characters the RPC marks them with.
+ opts.output(JSON.stringify({ hits: hits.map(({ snippet, ...hit }) => ({ ...hit, ...plainSnippet(snippet) })) }, null, 2))
+ return 0
+ }
+ if (!hits.length) {
+ opts.output(query
+ ? `Nothing on this computer mentions ${JSON.stringify(query)}${when ? ` ${when.phrase}` : ''}.`
+ : `Nothing on this computer was worked on ${when?.phrase ?? 'then'}.`)
+ return 0
+ }
+ const bold = (text: string) => opts.color
+ ? text.replaceAll(MARK_OPEN, '\x1b[1m').replaceAll(MARK_CLOSE, '\x1b[22m')
+ : text.replaceAll(MARK_OPEN, '').replaceAll(MARK_CLOSE, '')
+ const lead: Record<string, string> = { ask: '> ', tools: '$ ', answer: ' ', name: ' ' }
+ for (const hit of hits) {
+ opts.output(`${hit.name} ${[age(hit.at ?? hit.lastAt, now), hit.agentId.slice(0, 8)].filter(Boolean).join(' · ')}`)
+ if (hit.field !== 'name') opts.output(` ${lead[hit.field]}${bold(hit.snippet)}`)
+ }
+ return 0
+ } finally {
+ store.close()
+ }
+}
diff --git a/cli/src/lib/sessionSearch/indexer.spec.ts b/cli/src/lib/sessionSearch/indexer.spec.ts
new file mode 100644
index 000000000..5a588381a
--- /dev/null
+++ b/cli/src/lib/sessionSearch/indexer.spec.ts
@@ -0,0 +1,175 @@
+import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { LiveEvent } from '../normalize.js'
+import { SessionSearchIndex, folderWords, type SearchSource } from './indexer.js'
+import { SessionSearchStore } from './store.js'
+
+const dirs: string[] = []
+const cleanups: Array<() => void> = []
+afterEach(() => {
+ for (const cleanup of cleanups.splice(0)) cleanup()
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+ vi.useRealTimers()
+})
+
+const at = (minute: number) => `2026-09-20T10:${String(minute).padStart(2, '0')}:00.000Z`
+const prompt = (text: string, minute: number) => JSON.stringify({ type: 'user', timestamp: at(minute), message: { role: 'user', content: text } }) + '\n'
+const answer = (text: string, minute: number) => JSON.stringify({ type: 'assistant', timestamp: at(minute), message: { role: 'assistant', content: [{ type: 'text', text }], stop_reason: 'end_turn' } }) + '\n'
+
+function setup(initial: string, agents?: () => string[]) {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const path = join(dir, 's1.jsonl')
+ writeFileSync(path, initial)
+ const store = SessionSearchStore.open(':memory:')!
+ let sources: SearchSource[] = [{ agentId: 'agent-1', sessionId: 's1', engine: 'claude', transcriptPath: path, header: 'Dial firmware · harness', updatedAt: 1 }]
+ const index = new SessionSearchIndex({ store, sources: () => sources, agents, touchDelayMs: 5 })
+ cleanups.push(() => { index.stop(); store.close() })
+ const found = (query: string) => index.search(query).hits.map((hit) => hit.sessionId)
+ const settle = async () => {
+ index.sweep()
+ await vi.waitFor(() => { expect((index as unknown as { running: boolean }).running).toBe(false) })
+ await index.drain()
+ }
+ return { path, store, index, found, settle, setSources: (next: SearchSource[]) => { sources = next } }
+}
+
+describe('SessionSearchIndex', () => {
+ it('indexes a transcript on the first sweep and picks up only what was added since', async () => {
+ const { path, store, found, settle } = setup(prompt('why does the dial scroll jump', 0) + answer('The delta is doubled.', 1))
+ await settle()
+ expect(found('doubled')).toEqual(['s1'])
+ const first = store.session('s1')!
+ expect(first).toMatchObject({ resumeOffset: 0, resumeTurn: 0, turns: 1, lastAt: Date.parse(at(1)) })
+
+ // The open turn grows, then a new one starts: the pass resumes at the open turn, not the start.
+ appendFileSync(path, answer('Halved it in ui.c.', 2) + prompt('now flash the keyboard firmware', 3))
+ await settle()
+ expect(found('halved')).toEqual(['s1'])
+ expect(found('keyboard')).toEqual(['s1'])
+ const second = store.session('s1')!
+ expect(second.resumeTurn).toBe(1)
+ expect(second.resumeOffset).toBeGreaterThan(0)
+ expect(store.counts()).toEqual({ sessions: 1, turns: 2 })
+ // Nothing indexed twice.
+ expect(found('doubled')).toEqual(['s1'])
+ expect(store.search('delta')[0].snippet).toContain('doubled')
+ })
+
+ it('starts over when the transcript was rewritten shorter', async () => {
+ const { path, found, settle } = setup(prompt('first long conversation about cohorts and retention', 0) + answer('Done with the cohort table.', 1))
+ await settle()
+ writeFileSync(path, prompt('tiny', 0))
+ await settle()
+ expect(found('cohort')).toEqual([])
+ expect(found('tiny')).toEqual(['s1'])
+ })
+
+ it('updates the name without rereading the transcript, and forgets sessions of deleted agents', async () => {
+ const { store, found, settle, setSources, path } = setup(prompt('flash it', 0))
+ await settle()
+ setSources([{ agentId: 'agent-1', sessionId: 's1', engine: 'claude', transcriptPath: path, header: 'Keyboard firmware', updatedAt: 2 }])
+ await settle()
+ expect(found('keyboard')).toEqual(['s1'])
+ expect(found('dial')).toEqual([])
+ expect(store.session('s1')!.turns).toBe(1)
+
+ // An agent's earlier session (before a /clear) stays while the agent does…
+ setSources([{ agentId: 'agent-1', sessionId: 's2', engine: 'terminal', transcriptPath: null, header: 'Keyboard firmware', updatedAt: 3 }])
+ await settle()
+ expect(found('flash')).toEqual(['s1'])
+ // …and goes with it.
+ setSources([])
+ await settle()
+ expect(found('flash')).toEqual([])
+ expect(store.counts().sessions).toBe(0)
+ })
+
+ it('indexes a touched session shortly after its turn event', async () => {
+ const { path, index, found } = setup(prompt('first ask', 0))
+ index.touch('s1')
+ await vi.waitFor(() => { expect(found('first')).toEqual(['s1']) })
+ appendFileSync(path, prompt('second ask about tmux', 1))
+ index.touch('s1')
+ index.touch('s1')
+ await vi.waitFor(() => { expect(found('tmux')).toEqual(['s1']) })
+ })
+
+ it('reads a database-backed history whole, again only when the session changed', async () => {
+ const store = SessionSearchStore.open(':memory:')!
+ let reads = 0
+ let history: LiveEvent[] = [
+ { type: 'user_message', payload: { content: 'draft the release notes' } },
+ { type: 'text_delta', payload: { content: 'Drafted them in RELEASE.md.' } },
+ ]
+ let source: SearchSource = {
+ agentId: 'agent-oc', sessionId: 'ses_1', engine: 'opencode', transcriptPath: null, header: 'OpenCode harness',
+ updatedAt: 100, readHistory: async () => { reads++; return history },
+ }
+ const index = new SessionSearchIndex({ store, sources: () => [source], touchDelayMs: 5 })
+ cleanups.push(() => { index.stop(); store.close() })
+ const found = (query: string) => index.search(query).hits.map((hit) => hit.sessionId)
+ index.sweep()
+ await vi.waitFor(() => { expect(found('release')).toEqual(['ses_1']) })
+ expect(store.session('ses_1')).toMatchObject({ turns: 1, lastAt: 100 })
+
+ index.sweep()
+ await index.drain()
+ expect(reads).toBe(1)
+
+ // A turn event marks it changed even before its update time moves.
+ history = [...history, { type: 'user_message', payload: { content: 'now tag v2' } }]
+ index.touch('ses_1')
+ await vi.waitFor(() => { expect(found('tag')).toEqual(['ses_1']) })
+ expect(reads).toBe(2)
+
+ // A turn event that changed nothing leaves it as it was worked on.
+ const before = store.session('ses_1')!.lastAt
+ index.touch('ses_1')
+ await vi.waitFor(() => { expect(reads).toBe(3) })
+ await index.drain()
+ expect(store.session('ses_1')!.lastAt).toBe(before)
+
+ const now = Date.now()
+ history = [...history, { type: 'user_message', payload: { content: 'publish the changelog' } }]
+ index.touch('ses_1')
+ await vi.waitFor(() => { expect(found('changelog')).toEqual(['ses_1']) })
+ expect(store.session('ses_1')!.turns).toBe(3)
+ expect(store.session('ses_1')!.lastAt).toBeGreaterThanOrEqual(now)
+
+ // A turn whose event was lost (the daemon restarted first): its activity stamp moved, so the
+ // next sweep reads it, and dates it by that stamp.
+ history = [...history, { type: 'user_message', payload: { content: 'archive the old builds' } }]
+ source = { ...source, updatedAt: 5_000 }
+ const restarted = new SessionSearchIndex({ store, sources: () => [source] })
+ cleanups.push(() => restarted.stop())
+ restarted.sweep()
+ await vi.waitFor(() => { expect(restarted.search('archive').hits.map((hit) => hit.sessionId)).toEqual(['ses_1']) })
+ expect(store.session('ses_1')).toMatchObject({ turns: 4, lastAt: 5_000 })
+ restarted.sweep()
+ await restarted.drain()
+ expect(reads).toBe(5)
+ })
+
+ it('keeps an agent\'s sessions while the agent exists, even with nothing to read right now', async () => {
+ let agents = ['agent-1']
+ const { store, found, settle, setSources } = setup(prompt('the first conversation about tmux', 0), () => agents)
+ await settle()
+ setSources([])
+ await settle()
+ expect(found('tmux')).toEqual(['s1'])
+ agents = []
+ await settle()
+ expect(store.counts().sessions).toBe(0)
+ })
+
+ it('names folders the way a person would: the last two segments', () => {
+ expect(folderWords('/home/me/code/worktrees/autonomous-harness/dapper-otter')).toBe('dapper-otter autonomous-harness')
+ expect(folderWords('C:\\work\\app')).toBe('app work')
+ expect(folderWords(null)).toBe('')
+ })
+})
diff --git a/cli/src/lib/sessionSearch/indexer.ts b/cli/src/lib/sessionSearch/indexer.ts
new file mode 100644
index 000000000..8eb883911
--- /dev/null
+++ b/cli/src/lib/sessionSearch/indexer.ts
@@ -0,0 +1,292 @@
+/**
+ * Keeps the session search index in step with the transcripts on this machine.
+ *
+ * One path for everything: a pass reads a transcript from where the last pass stopped — the opening
+ * of its last turn, which may have grown since — through the engine's normalizer into the index. The
+ * first pass over a session is the backfill; every later one is an increment of a turn or two. A sweep
+ * shortly after boot and every few minutes after catches up anything missed; a turn starting or ending
+ * in a live session asks for its pass right away, so what was just said is searchable a second later.
+ *
+ * The daemon's thread is shared with every terminal it streams, so passes run one at a time, read in
+ * 1 MB chunks, skip tool output unparsed, and yield to the event loop every few milliseconds.
+ */
+
+import { stat } from 'node:fs/promises'
+import { performance } from 'node:perf_hooks'
+
+import type { LiveEvent } from '../normalize.js'
+import { forEachLine, lineNormalizer, lineTime, skipPredicate } from './transcript.js'
+import { TurnCollector } from './turns.js'
+import type { IndexedSession, SearchHit, SessionSearchStore } from './store.js'
+
+export interface SearchSource {
+ agentId: string
+ sessionId: string
+ engine: string
+ transcriptPath: string | null
+ /** What the session is called — name, title, folder — searchable beside what was said in it. */
+ header: string
+ /**
+ * When the conversation last moved (epoch ms), from stamps that move only with it — never the
+ * registry's bookkeeping time. Newest sessions are indexed first, and a database-backed history
+ * is read again when this moves.
+ */
+ updatedAt: number
+ /**
+ * The whole history, for an engine that keeps it in a database rather than a transcript file
+ * (OpenCode, Kilo, Hermes, Devin). Read in full when the session changed: there is no offset to
+ * resume from.
+ */
+ readHistory?: () => Promise<readonly LiveEvent[]>
+}
+
+export interface SessionSearchResult {
+ hits: SearchHit[]
+ /** Sessions in the index, and sessions still waiting for their first pass. */
+ indexed: number
+ pending: number
+ tookMs: number
+}
+
+export interface SessionSearchIndexOptions {
+ store: SessionSearchStore
+ /** Every session this machine can index: live agents and stopped ones. */
+ sources: () => SearchSource[]
+ /**
+ * Every agent this machine knows, indexable right now or not. An agent's sessions leave the index
+ * only when the agent does — never because its current session has no transcript for a moment
+ * (a `/clear` between sessions), since its earlier ones cannot be read back once dropped.
+ * Defaults to the agents of `sources`.
+ */
+ agents?: () => Iterable<string>
+ log?: (line: string) => void
+ /** Between full sweeps. */
+ sweepEveryMs?: number
+ /** How long a pass may hold the thread before yielding. */
+ sliceMs?: number
+ /** How long after a turn event its session's pass runs: a burst of events is one pass. */
+ touchDelayMs?: number
+}
+
+const NO_TURN_DELETE = Number.MAX_SAFE_INTEGER
+
+/** The folders a session ran in, as a person would name them: the last two path segments. */
+export function folderWords(cwd: string | null | undefined): string {
+ if (!cwd) return ''
+ return cwd.split(/[\\/]+/).filter(Boolean).slice(-2).reverse().join(' ')
+}
+
+export class SessionSearchIndex {
+ private readonly queue = new Set<string>()
+ /** Sessions with a turn event since their last pass: a database history has no size to compare. */
+ private readonly dirty = new Set<string>()
+ private readonly touches = new Map<string, NodeJS.Timeout>()
+ private sources = new Map<string, SearchSource>()
+ private sourcesReadAt = 0
+ private running = false
+ private stopped = false
+ private sweepTimer: NodeJS.Timeout | null = null
+ private sliceStart = 0
+
+ constructor(private readonly opts: SessionSearchIndexOptions) {}
+
+ /** The first sweep after `delayMs` (boot has other work), then one every `sweepEveryMs`. */
+ start(delayMs = 15_000): void {
+ const every = this.opts.sweepEveryMs ?? 10 * 60_000
+ const first = setTimeout(() => {
+ this.sweep()
+ this.sweepTimer = setInterval(() => this.sweep(), every)
+ this.sweepTimer.unref?.()
+ }, delayMs)
+ first.unref?.()
+ this.sweepTimer = first
+ }
+
+ stop(): void {
+ this.stopped = true
+ if (this.sweepTimer) clearTimeout(this.sweepTimer)
+ for (const timer of this.touches.values()) clearTimeout(timer)
+ this.touches.clear()
+ this.queue.clear()
+ }
+
+ /** A turn started or ended in this session: index it shortly. */
+ touch(sessionId: string): void {
+ if (this.stopped) return
+ this.dirty.add(sessionId)
+ const pending = this.touches.get(sessionId)
+ if (pending) clearTimeout(pending)
+ const timer = setTimeout(() => {
+ this.touches.delete(sessionId)
+ this.refreshSources()
+ if (!this.sources.has(sessionId)) this.refreshSources(true)
+ // Ahead of a sweep's backlog: what somebody just said is what they are likeliest to look for.
+ const rest = [...this.queue].filter((id) => id !== sessionId)
+ this.queue.clear()
+ this.queue.add(sessionId)
+ for (const id of rest) this.queue.add(id)
+ void this.drain()
+ }, this.opts.touchDelayMs ?? 1_500)
+ timer.unref?.()
+ this.touches.set(sessionId, timer)
+ }
+
+ /** Queue every known session, newest first; drop sessions whose agent no longer exists. */
+ sweep(): void {
+ if (this.stopped) return
+ this.refreshSources(true)
+ const agents = new Set(this.opts.agents?.() ?? [...this.sources.values()].map((source) => source.agentId))
+ for (const sessionId of this.opts.store.sessionIds()) {
+ // An agent's earlier sessions (before a /clear) stay findable while the agent exists.
+ const indexed = this.opts.store.session(sessionId)
+ if (indexed && !agents.has(indexed.agentId)) this.opts.store.removeSession(sessionId)
+ }
+ const newest = [...this.sources.values()].sort((a, b) => b.updatedAt - a.updatedAt)
+ for (const source of newest) this.queue.add(source.sessionId)
+ void this.drain()
+ }
+
+ search(query: string, options: { limit?: number; from?: number; to?: number } = {}): SessionSearchResult {
+ const started = performance.now()
+ const hits = this.opts.store.search(query, options)
+ const indexed = this.opts.store.counts().sessions
+ return { hits, indexed, pending: this.queue.size, tookMs: Math.round((performance.now() - started) * 10) / 10 }
+ }
+
+ /** Runs queued passes one at a time until the queue is empty. */
+ async drain(): Promise<void> {
+ if (this.running) return
+ this.running = true
+ try {
+ while (!this.stopped && this.queue.size) {
+ const sessionId = this.queue.values().next().value as string
+ this.queue.delete(sessionId)
+ const source = this.sources.get(sessionId)
+ if (!source) continue
+ try {
+ await this.pass(source)
+ } catch (error) {
+ this.opts.log?.(`[search] ${sessionId.slice(0, 8)} index pass failed: ${error instanceof Error ? error.message : String(error)}`)
+ }
+ }
+ } finally {
+ this.running = false
+ }
+ }
+
+ private refreshSources(force = false): void {
+ if (!force && Date.now() - this.sourcesReadAt < 5_000) return
+ const next = new Map<string, SearchSource>()
+ for (const source of this.opts.sources()) {
+ if (!source.sessionId) continue
+ const known = next.get(source.sessionId)
+ // One session can be listed live and stopped at once: the fresher record wins.
+ if (!known || source.updatedAt > known.updatedAt) next.set(source.sessionId, source)
+ }
+ this.sources = next
+ this.sourcesReadAt = Date.now()
+ }
+
+ /** One pass over one session: from where the last one stopped, or from the start. */
+ async pass(source: SearchSource): Promise<void> {
+ const store = this.opts.store
+ const existing = store.session(source.sessionId)
+ const dirty = this.dirty.delete(source.sessionId)
+ if (!source.transcriptPath && source.readHistory) return this.historyPass(source, existing, dirty)
+ const normalize = source.transcriptPath ? lineNormalizer(source.engine, source.sessionId) : null
+ const file = source.transcriptPath && normalize ? await stat(source.transcriptPath).catch(() => null) : null
+ const header = source.header
+ if (!file || !source.transcriptPath || !normalize) {
+ // Nothing to read (a terminal, a database-backed engine, a missing file): its name is still findable.
+ if (existing?.header === header && existing.agentId === source.agentId) return
+ store.writeSession({
+ sessionId: source.sessionId, agentId: source.agentId, engine: source.engine,
+ path: existing?.path ?? source.transcriptPath ?? '', header,
+ size: existing?.size ?? 0, mtime: existing?.mtime ?? 0,
+ resumeOffset: existing?.resumeOffset ?? 0, resumeTurn: existing?.resumeTurn ?? 0,
+ lastAt: existing?.lastAt ?? (source.updatedAt || null), turns: 0,
+ }, NO_TURN_DELETE, [])
+ return
+ }
+ const path = source.transcriptPath
+ const mtime = Math.floor(file.mtimeMs)
+ const samePath = existing?.path === path
+ if (samePath && existing.size === file.size && existing.mtime === mtime) {
+ if (existing.header !== header || existing.agentId !== source.agentId) {
+ store.writeSession({ ...existing, header, agentId: source.agentId }, NO_TURN_DELETE, [])
+ }
+ return
+ }
+ // A file that shrank was rewritten: start over. One that grew picks up at its last turn.
+ const resume = samePath && file.size >= existing.size && existing.resumeOffset <= file.size
+ const from = resume ? existing.resumeOffset : 0
+ const fromTurn = resume ? existing.resumeTurn : 0
+ const collector = new TurnCollector(fromTurn)
+ let lastAt: number | null = null
+ this.sliceStart = performance.now()
+ const { end } = await forEachLine(path, from, async ({ text, offset }) => {
+ const at = lineTime(text) ?? lastAt
+ if (at !== null && (lastAt === null || at > lastAt)) lastAt = at
+ collector.feed(normalize(text), offset, at)
+ await this.pace()
+ }, { skip: skipPredicate(source.engine), shouldStop: () => this.stopped })
+ if (this.stopped) return
+ const { closed, open } = collector.finish()
+ const session: IndexedSession = {
+ sessionId: source.sessionId, agentId: source.agentId, engine: source.engine, path, header,
+ size: file.size, mtime,
+ resumeOffset: open ? open.offset : end,
+ resumeTurn: open ? open.turn : collector.next,
+ lastAt: lastAt ?? (resume ? existing.lastAt : null) ?? mtime,
+ turns: 0,
+ }
+ store.writeSession(session, fromTurn, open ? [...closed, open] : closed)
+ if (!resume) {
+ this.opts.log?.(`[search] indexed ${source.sessionId.slice(0, 8)} · ${source.engine} · ${closed.length + (open ? 1 : 0)} turns · ${Math.round(file.size / 1024)} KB`)
+ }
+ }
+
+ /**
+ * A database-backed session, read whole the first time, after each turn event (`touch`), and when
+ * its activity stamp moved — which catches a turn whose event was lost to a restart. What it read
+ * is fingerprinted, so the session counts as worked on only when its conversation changed.
+ */
+ private async historyPass(source: SearchSource, existing: IndexedSession | undefined, dirty: boolean): Promise<void> {
+ const store = this.opts.store
+ const stamp = source.updatedAt
+ if (existing && !dirty && existing.mtime === stamp) {
+ if (existing.header !== source.header || existing.agentId !== source.agentId) {
+ store.writeSession({ ...existing, header: source.header, agentId: source.agentId }, NO_TURN_DELETE, [])
+ }
+ return
+ }
+ const events = await source.readHistory!()
+ if (this.stopped) return
+ const collector = new TurnCollector(0)
+ for (let at = 0; at < events.length; at += 200) {
+ collector.feed(events.slice(at, at + 200), 0, null)
+ await this.pace()
+ }
+ const { closed, open } = collector.finish()
+ const turns = open ? [...closed, open] : closed
+ // The size field holds the fingerprint: how much conversation there was when last read.
+ const fingerprint = turns.reduce((sum, turn) => sum + turn.ask.length + turn.answer.length + turn.tools.length + 1, 0)
+ if (existing && existing.size === fingerprint && existing.mtime === stamp
+ && existing.header === source.header && existing.agentId === source.agentId) return
+ const changed = !existing || existing.size !== fingerprint
+ store.writeSession({
+ sessionId: source.sessionId, agentId: source.agentId, engine: source.engine, path: '',
+ header: source.header, size: fingerprint, mtime: stamp, resumeOffset: 0, resumeTurn: 0,
+ // Its turns carry no time: the session's is its activity stamp, or now for a turn just seen.
+ lastAt: !changed ? existing!.lastAt : dirty ? Math.max(Date.now(), stamp) : stamp || null,
+ turns: 0,
+ }, 0, turns)
+ if (!existing) this.opts.log?.(`[search] indexed ${source.sessionId.slice(0, 8)} · ${source.engine} · ${turns.length} turns`)
+ }
+
+ private async pace(): Promise<void> {
+ if (performance.now() - this.sliceStart < (this.opts.sliceMs ?? 12)) return
+ await new Promise<void>((resolve) => setImmediate(resolve))
+ this.sliceStart = performance.now()
+ }
+}
diff --git a/cli/src/lib/sessionSearch/store.spec.ts b/cli/src/lib/sessionSearch/store.spec.ts
new file mode 100644
index 000000000..ae4cfbd92
--- /dev/null
+++ b/cli/src/lib/sessionSearch/store.spec.ts
@@ -0,0 +1,264 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { MARK_CLOSE, MARK_OPEN, SessionSearchStore, makeSnippet, queryTerms, type IndexedSession } from './store.js'
+import type { IndexedTurn } from './turns.js'
+
+const DAY = 86_400_000
+const NOW = Date.parse('2026-09-26T12:00:00Z')
+const stores: SessionSearchStore[] = []
+const dirs: string[] = []
+afterEach(() => {
+ for (const store of stores.splice(0)) store.close()
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function open(path = ':memory:'): SessionSearchStore {
+ const store = SessionSearchStore.open(path)
+ if (!store) throw new Error('node:sqlite is required for these tests')
+ stores.push(store)
+ return store
+}
+
+function session(sessionId: string, header: string, lastAt: number, agentId = `agent-${sessionId}`): IndexedSession {
+ return { sessionId, agentId, engine: 'claude', path: `/t/${sessionId}.jsonl`, header, size: 1, mtime: 1, resumeOffset: 0, resumeTurn: 0, lastAt, turns: 0 }
+}
+
+function turn(index: number, ask: string, answer = '', tools = '', at: number | null = null): IndexedTurn {
+ return { turn: index, offset: index * 100, at, ask, answer, tools }
+}
+
+const plain = (snippet: string) => snippet.replaceAll(MARK_OPEN, '[').replaceAll(MARK_CLOSE, ']')
+
+describe('queryTerms', () => {
+ it('makes each word a prefix phrase of its parts and drops what cannot mean anything alone', () => {
+ expect(queryTerms('swarm_search.dart OH-14')).toEqual(['"swarm search dart"*', '"oh 14"*'])
+ expect(queryTerms('a fix FIX x')).toEqual(['"fix"*'])
+ expect(queryTerms(' ')).toEqual([])
+ })
+
+ it('never passes FTS5 syntax through', () => {
+ const store = open()
+ store.writeSession(session('s1', 'Dial', NOW), 0, [turn(0, 'fix the dial')])
+ for (const query of ['"dial', 'dial" OR "x', 'NEAR(dial', 'dial*', '-dial', 'dial:', '^dial', '(', '"']) {
+ expect(() => store.search(query, { now: NOW })).not.toThrow()
+ }
+ expect(store.search('NEAR(dial', { now: NOW })).toEqual([])
+ expect(store.search('dial"', { now: NOW }).map((hit) => hit.sessionId)).toEqual(['s1'])
+ })
+})
+
+describe('makeSnippet', () => {
+ const words = (...parts: string[][]) => parts.map((part) => new RegExp(`(?<![\\p{L}\\p{N}])${part.join('[^\\p{L}\\p{N}]+')}[\\p{L}\\p{N}]*`, 'giu'))
+
+ it('quotes the words around the first match and marks every match there', () => {
+ const text = `${'lorem '.repeat(40)}we halved the Scroll delta so scrolling feels right ${'ipsum '.repeat(40)}`
+ expect(plain(makeSnippet(text, words(['scroll']))!)).toBe('…lorem we halved the [Scroll] delta so [scrolling] feels right ipsum ipsum…')
+ expect(makeSnippet('nothing here', words(['scroll']))).toBeNull()
+ })
+
+ it('survives a match inside one long unbroken run', () => {
+ const run = '東'.repeat(700)
+ expect(() => makeSnippet(run, words(['東東']))).not.toThrow()
+ const token = `eyJ${'a'.repeat(900)} and more`
+ expect(makeSnippet(token, words(['eyj']))).toContain(MARK_OPEN)
+ })
+
+ it('matches a word of parts as the index does, and keeps short text whole', () => {
+ expect(plain(makeSnippet('edit desktop/lib/swarm_search.dart now', words(['swarm', 'search', 'dart']))!))
+ .toBe('edit desktop/lib/[swarm_search.dart] now')
+ expect(plain(makeSnippet('research is not search', words(['search']))!)).toBe('research is not [search]')
+ })
+})
+
+describe('SessionSearchStore', () => {
+ it('finds a session by a word from any turn, as a prefix, with its own snippet', () => {
+ const store = open()
+ store.writeSession(session('dial', 'Deploy firmware', NOW - DAY), 0, [
+ turn(0, 'flash the latest firmware'),
+ turn(1, 'the dial scroll jumps two rows', 'Halved the scroll delta in ui.c.', 'Edit devices/dial/src/ui.c'),
+ ])
+ store.writeSession(session('web', 'Landing page', NOW - DAY), 0, [turn(0, 'make the hero scroll smoothly')])
+ const hits = store.search('scrol', { now: NOW })
+ expect(hits.map((hit) => hit.sessionId).sort()).toEqual(['dial', 'web'])
+ // Each hit's snippet comes from its own turn — see the CAST in search().
+ expect(hits.map((hit) => plain(hit.snippet)).sort()).toEqual([
+ 'make the hero [scroll] smoothly',
+ 'the dial [scroll] jumps two rows',
+ ])
+ expect(hits.find((hit) => hit.sessionId === 'dial')).toMatchObject({ turn: 1, field: 'ask', agentId: 'agent-dial', engine: 'claude' })
+ })
+
+ it('ranks a turn holding every word above a session that has them only in different turns', () => {
+ const store = open()
+ store.writeSession(session('together', 'A', NOW - 20 * DAY), 0, [turn(0, 'port the daemon to windows')])
+ store.writeSession(session('spread', 'B', NOW), 0, [turn(0, 'port scan'), turn(1, 'resize the windows')])
+ store.writeSession(session('half', 'C', NOW), 0, [turn(0, 'port only')])
+ const hits = store.search('windows port', { now: NOW })
+ expect(hits.map((hit) => [hit.sessionId, hit.together])).toEqual([['together', true], ['spread', false]])
+ })
+
+ it('keeps a session with every word even when common words fill the ranked window', () => {
+ const store = open()
+ const filler = Array.from({ length: 3_100 }, (_, index) => turn(index, 'alpha beta'))
+ store.writeSession(session('filler', 'F', NOW), 0, filler)
+ store.writeSession(session('spread', 'S', NOW), 0, [
+ turn(0, `alpha ${'padding '.repeat(80)}`),
+ turn(1, `beta ${'padding '.repeat(80)}`),
+ ])
+ const hits = store.search('alpha beta', { now: NOW })
+ expect(hits.map((hit) => [hit.sessionId, hit.together])).toEqual([['filler', true], ['spread', false]])
+ expect(plain(hits[1].snippet)).toMatch(/\[(alpha|beta)\]/)
+ })
+
+ it('ranks a word in nearly every turn by recency: the newest sessions that say it', () => {
+ const store = open()
+ store.commonMatches = 3
+ for (let index = 0; index < 6; index++) {
+ store.writeSession(session(`s${index}`, 'x', NOW - index * DAY), 0, [turn(0, `harness ${'word '.repeat(index * 5)}`, '', '', NOW - index * DAY)])
+ }
+ expect(store.search('harness', { now: NOW, limit: 3 }).map((hit) => hit.sessionId)).toEqual(['s0', 's1', 's2'])
+ expect(store.search('harness', { now: NOW, from: NOW - 4.5 * DAY, to: NOW - 2.5 * DAY }).map((hit) => hit.sessionId)).toEqual(['s3', 's4'])
+ })
+
+ it('matches words split between the session name and what was said in it', () => {
+ const store = open()
+ store.writeSession(session('mobile', 'Mobile app build', NOW), 0, [turn(0, 'swipe right opens Find')])
+ const [hit] = store.search('mobile swipe', { now: NOW })
+ expect(hit).toMatchObject({ sessionId: 'mobile', together: false, field: 'ask' })
+ expect(plain(hit.snippet)).toBe('[swipe] right opens Find')
+ expect(store.search('mobile', { now: NOW })[0]).toMatchObject({ field: 'name', turn: -1 })
+ })
+
+ it('reports the field that matched: the ask first, then the name, the answer, the tools', () => {
+ const store = open()
+ store.writeSession(session('s', 'Session', NOW), 0, [turn(0, 'why', 'because of keystone hashing', 'Bash rg keystone')])
+ expect(store.search('keystone', { now: NOW })[0].field).toBe('answer')
+ store.writeSession(session('t', 'Tools', NOW), 0, [turn(0, 'look', '', 'Read cli/src/lib/e2ee/core.ts')])
+ expect(store.search('core.ts', { now: NOW }).map((hit) => [hit.sessionId, hit.field])).toEqual([['t', 'tools']])
+ })
+
+ it('prefers the recent of two equally good matches, but not over a much better old one', () => {
+ const store = open()
+ store.writeSession(session('old', 'x', NOW - 60 * DAY), 0, [turn(0, 'cohort retention')])
+ store.writeSession(session('new', 'y', NOW - DAY), 0, [turn(0, 'cohort retention')])
+ expect(store.search('retention', { now: NOW }).map((hit) => hit.sessionId)).toEqual(['new', 'old'])
+ // One passing mention in a long tool log, yesterday, does not outrank a session about it.
+ store.writeSession(session('mention', 'z', NOW - DAY), 0, [turn(0, 'check the logs', '', `Bash ${'grep -n x file.txt '.repeat(60)} retention`)])
+ expect(store.search('retention', { now: NOW }).map((hit) => hit.sessionId)).toEqual(['new', 'old', 'mention'])
+ })
+
+ it('ranks the session started for something above one that mentions it on the way', () => {
+ const store = open()
+ store.writeSession(session('started', 'Claude harness 9-25 7:25', NOW - 2 * DAY), 0, [
+ turn(0, 'build a phone stand at 60 degrees with a cable slot'),
+ turn(1, 'make the base heavier'),
+ turn(2, 'export the STL'),
+ ])
+ store.writeSession(session('hub', 'Harness list', NOW - 2 * DAY), 0, [
+ turn(0, 'what harnesses are running'),
+ turn(1, 'tidy the list'),
+ turn(2, 'the phone stand harness and the cup engraving harness'),
+ ])
+ expect(store.search('phone stand', { now: NOW }).map((hit) => hit.sessionId)).toEqual(['started', 'hub'])
+ })
+
+ it('narrows to sessions worked on in a window: any turn then, not only the matching one', () => {
+ const store = open()
+ const lastWeek = { from: NOW - 10 * DAY, to: NOW - 4 * DAY }
+ store.writeSession(session('then', 'A', NOW - 5 * DAY), 0, [turn(0, 'fix the dial scroll', '', '', NOW - 6 * DAY)])
+ store.writeSession(session('now', 'B', NOW - 1 * DAY), 0, [turn(0, 'dial firmware', '', '', NOW - 1 * DAY)])
+ // Mentioned the dial three weeks ago, and worked on again last week: still the dial one then.
+ store.writeSession(session('long', 'C', NOW - 5 * DAY), 0, [
+ turn(0, 'the dial keeps rebooting', '', '', NOW - 21 * DAY),
+ turn(1, 'ship it', '', '', NOW - 5 * DAY),
+ ])
+ // A database-backed session: no turn times, only when it was last worked on.
+ store.writeSession(session('untimed', 'D', NOW - 7 * DAY), 0, [turn(0, 'dial menu')])
+ expect(store.search('dial', { now: NOW, ...lastWeek }).map((hit) => hit.sessionId).sort()).toEqual(['long', 'then', 'untimed'])
+ expect(store.search('dial', { now: NOW }).map((hit) => hit.sessionId)).toContain('now')
+ expect(store.search('dial', { now: NOW, from: NOW - 2 * DAY, to: NOW })).toMatchObject([{ sessionId: 'now' }])
+ expect(store.search('keyboard', { now: NOW, ...lastWeek })).toEqual([])
+ })
+
+ it('lists what was worked on in a window when there are no words, latest first', () => {
+ const store = open()
+ store.writeSession(session('a', 'A', NOW - 2 * DAY), 0, [
+ turn(0, 'first thing', '', '', NOW - 3 * DAY),
+ turn(1, 'what I asked last in the window', '', '', NOW - 2 * DAY),
+ ])
+ store.writeSession(session('b', 'B', NOW - 1 * DAY), 0, [turn(0, 'yesterday work', '', '', NOW - 1 * DAY)])
+ store.writeSession(session('c', 'C', NOW - 9 * DAY), 0, [turn(0, 'long ago', '', '', NOW - 9 * DAY)])
+ // A later turn opened by an agent's report does not hide what the person asked.
+ store.writeSession(session('a', 'A', NOW - 2 * DAY), 2, [turn(2, '', 'Another session reported back', '', NOW - 2 * DAY + 60_000)])
+ const hits = store.search('', { now: NOW, from: NOW - 4 * DAY, to: NOW })
+ expect(hits.map((hit) => [hit.sessionId, hit.snippet, hit.field])).toEqual([
+ ['b', 'yesterday work', 'ask'],
+ ['a', 'what I asked last in the window', 'ask'],
+ ])
+ expect(store.search('', { now: NOW })).toEqual([])
+
+ // A database-backed session (turns without times) worked on in the window is listed too, and
+ // a session whose last turns share a time is listed once.
+ store.writeSession(session('untimed', 'D', NOW - 2.5 * DAY), 0, [turn(0, 'from a database')])
+ store.writeSession(session('twice', 'E', NOW - 3 * DAY), 0, [
+ turn(0, 'first', '', '', NOW - 3 * DAY),
+ turn(1, 'second, same minute', '', '', NOW - 3 * DAY),
+ ])
+ expect(store.search('', { now: NOW, from: NOW - 4 * DAY, to: NOW }).map((hit) => [hit.sessionId, hit.snippet])).toEqual([
+ ['b', 'yesterday work'],
+ ['a', 'what I asked last in the window'],
+ ['untimed', 'from a database'],
+ ['twice', 'second, same minute'],
+ ])
+ })
+
+ it('tells a reader a file it cannot read from one written by another version', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const path = join(dir, 'index.db')
+ writeFileSync(path, 'this is not a database, it is a sentence long enough to be read as a header')
+ expect(SessionSearchStore.openReader(path)).toBe('unreadable')
+ expect(SessionSearchStore.openReader(join(dir, 'none.db'))).toBe('missing')
+ })
+
+ it('replaces turns from a point on, keeps earlier ones, and counts them', () => {
+ const store = open()
+ store.writeSession(session('s', 'S', NOW), 0, [turn(0, 'alpha'), turn(1, 'beta draft')])
+ store.writeSession({ ...session('s', 'S renamed', NOW), resumeOffset: 100, resumeTurn: 1 }, 1, [turn(1, 'beta final'), turn(2, 'gamma')])
+ expect(store.session('s')).toMatchObject({ header: 'S renamed', resumeOffset: 100, resumeTurn: 1, turns: 3 })
+ expect(store.search('draft', { now: NOW })).toEqual([])
+ expect(store.search('alpha', { now: NOW })).toHaveLength(1)
+ expect(store.search('renamed', { now: NOW })).toHaveLength(1)
+ expect(store.counts()).toEqual({ sessions: 1, turns: 3 })
+ store.removeSession('s')
+ expect(store.counts()).toEqual({ sessions: 0, turns: 0 })
+ expect(store.search('alpha', { now: NOW })).toEqual([])
+ })
+
+ it('starts over from a file that is not a database', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const path = join(dir, 'index.db')
+ writeFileSync(path, 'this is not a database, it is a sentence long enough to be read as a header')
+ const store = open(path)
+ store.writeSession(session('s', 'S', NOW), 0, [turn(0, 'alpha')])
+ expect(store.search('alpha', { now: NOW })).toHaveLength(1)
+ })
+
+ it('rebuilds an index written by another schema version', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const path = join(dir, 'index.db')
+ const first = open(path)
+ first.writeSession(session('s', 'S', NOW), 0, [turn(0, 'alpha')])
+ ;(first as unknown as { db: { exec(sql: string): void } }).db.exec("UPDATE meta SET value = '0' WHERE key = 'schema'")
+ first.close()
+ stores.splice(stores.indexOf(first), 1)
+ const second = open(path)
+ expect(second.counts()).toEqual({ sessions: 0, turns: 0 })
+ })
+})
diff --git a/cli/src/lib/sessionSearch/store.ts b/cli/src/lib/sessionSearch/store.ts
new file mode 100644
index 000000000..a3000ef69
--- /dev/null
+++ b/cli/src/lib/sessionSearch/store.ts
@@ -0,0 +1,646 @@
+/**
+ * The session search index: one SQLite database per machine, one row per turn, searched with FTS5.
+ *
+ * Keyword search (BM25) rather than embeddings, on purpose. What people type into a quick-open box is
+ * one to three words and very often an exact token — a codename, a file, an issue number, a branch —
+ * which BM25 matches exactly and an embedding blurs. It needs no model, answers in milliseconds, and
+ * updates a turn at a time. See docs/research/2026-09-26-session-search.md.
+ *
+ * Every query word must appear in the SESSION, not necessarily in one turn: "mobile swipe" finds the
+ * session titled Mobile whose swipe discussion came an hour later. A turn holding every word is still
+ * the better match and ranks first.
+ */
+
+import { chmodSync, existsSync, rmSync } from 'node:fs'
+
+import { builtinSqlite } from '../sqliteRead.js'
+import type { IndexedTurn } from './turns.js'
+
+const SCHEMA_VERSION = '5'
+
+/** The row that holds a session's name, title and folder: searchable beside its turns. */
+export const HEADER_TURN = -1
+
+interface Statement {
+ all(...params: unknown[]): Record<string, unknown>[]
+ get(...params: unknown[]): Record<string, unknown> | undefined
+ run(...params: unknown[]): unknown
+}
+interface Database {
+ prepare(sql: string): Statement
+ exec(sql: string): void
+ close(): void
+}
+type DatabaseConstructor = new (path: string, options?: Record<string, unknown>) => Database
+
+export interface IndexedSession {
+ sessionId: string
+ agentId: string
+ engine: string
+ path: string
+ /** The session's name, title and folders, as the header row holds them. */
+ header: string
+ /** File size and mtime when last read, to tell whether it changed since. */
+ size: number
+ mtime: number
+ /** Where the next pass starts: the opening of the last turn, which may still be growing. */
+ resumeOffset: number
+ resumeTurn: number
+ lastAt: number | null
+ turns: number
+}
+
+export interface SearchHit {
+ sessionId: string
+ agentId: string
+ engine: string
+ /** The turn the snippet comes from, or -1 for the session's name and folder. */
+ turn: number
+ /** When that turn happened (epoch ms), when known. */
+ at: number | null
+ /** The session's latest turn (epoch ms), when known. */
+ lastAt: number | null
+ /** Which part of the turn matched best. */
+ field: 'name' | 'ask' | 'answer' | 'tools'
+ /** Text around the match, with each matched word between `\u0002` and `\u0003`. */
+ snippet: string
+ /** Every word in one turn, or spread across the session. */
+ together: boolean
+ /** 0–1, higher is better: relevance blended with recency; comparable across machines. */
+ score: number
+}
+
+// BM25 column weights: header (name/title/folder), what was asked, the answer, tool calls.
+const WEIGHTS = [6, 4, 1.5, 1] as const
+const FIELDS = ['name', 'ask', 'answer', 'tools'] as const
+export const MARK_OPEN = '\u0002'
+export const MARK_CLOSE = '\u0003'
+/** How much recency counts against relevance, and how fast it fades. */
+const RECENCY_WEIGHT = 0.2
+const RECENCY_HALF_LIFE_DAYS = 10
+/**
+ * The turns that say what a session was started for, and how much more they count. A session named
+ * "Claude harness 9-25 7:25" is found by its opening ask or not at all, and a session that merely
+ * lists other sessions by name must not outrank the one that set out to do the thing. Tuned on real
+ * sessions (see the research note): +10 points top-1 for one-word queries, +15 for topic queries,
+ * −2 for four-letter prefixes.
+ */
+const OPENING_TURNS = 2
+const OPENING_BOOST = 1.2
+/** The start of what was asked, for a hit found by time alone. */
+function clipAsk(ask: string): string {
+ return ask.length > 160 ? ask.slice(0, 160).trimEnd() + '…' : ask
+}
+
+export interface SearchOptions {
+ limit?: number
+ /** Only sessions worked on in this window (epoch ms, inclusive). */
+ from?: number
+ to?: number
+ now?: number
+}
+
+/** Rows considered per query before grouping by session: bounds the work of a very common word. */
+const CANDIDATE_ROWS = 3_000
+/** Past this many matching turns a query is ranked by recency first (see search()). */
+export const COMMON_MATCHES = 30_000
+
+/**
+ * Query words as the index sees them: each split into its letter-and-digit parts, since the index
+ * splits on everything else — "swarm_search.dart" and "OH-14" become phrases of their parts.
+ */
+function queryWords(query: string): string[][] {
+ const seen = new Set<string>()
+ const words: string[][] = []
+ for (const word of query.toLowerCase().normalize('NFKC').split(/\s+/).filter(Boolean)) {
+ const parts = word.split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+ if (!parts.length) continue
+ // One letter matches too much of everything to mean anything on its own.
+ if (parts.length === 1 && [...parts[0]].length < 2) continue
+ const key = parts.join(' ')
+ if (seen.has(key)) continue
+ seen.add(key)
+ words.push(parts)
+ }
+ return words
+}
+
+/** Query words as FTS5 phrases. Each word matches as a prefix, so the list updates while typing. */
+export function queryTerms(query: string): string[] {
+ return queryWords(query).map((parts) => `"${parts.join(' ')}"*`)
+}
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** Where a query word occurs in text the way the index matches it: at a word start, as a prefix. */
+function wordPattern(parts: string[]): RegExp {
+ const body = parts.map(escapeRegExp).join('[^\\p{L}\\p{N}]+')
+ return new RegExp(`(?<![\\p{L}\\p{N}])${body}[\\p{L}\\p{N}]*`, 'giu')
+}
+
+const SNIPPET_BEFORE = 4
+const SNIPPET_WORDS = 12
+
+/**
+ * The words around the first match in `text`, every match marked, or null when nothing matches.
+ * Built here rather than by FTS5's snippet(), which reads the whole posting list of a common word
+ * again for each hit: 30 hits of "harness" took a quarter of a second.
+ */
+export function makeSnippet(text: string, patterns: RegExp[]): string | null {
+ let first = -1
+ for (const pattern of patterns) {
+ pattern.lastIndex = 0
+ const match = pattern.exec(text)
+ if (match && (first < 0 || match.index < first)) first = match.index
+ }
+ if (first < 0) return null
+ // Only the neighbourhood of the match is tokenized: an answer runs to 12 KB.
+ const regionStart = Math.max(0, first - 200)
+ const regionEnd = Math.min(text.length, first + 600)
+ const words = [...text.slice(regionStart, regionEnd).matchAll(/[\p{L}\p{N}]+/gu)]
+ .map((word) => Object.assign(word, { index: word.index! + regionStart }))
+ // A word cut by the region's edge is not a word: drop it, unless the edge is the text's own —
+ // or it is the only word there, as in a long run of CJK text or an encoded token.
+ if (regionStart > 0 && words.length > 1 && words[0].index === regionStart) words.shift()
+ if (regionEnd < text.length && words.length > 1 && words.at(-1)!.index! + words.at(-1)![0].length === regionEnd) words.pop()
+ if (!words.length) return null
+ let at = words.findIndex((word) => word.index! + word[0].length > first)
+ if (at < 0) at = words.length - 1
+ const from = Math.max(0, at - SNIPPET_BEFORE)
+ const to = Math.min(words.length - 1, from + SNIPPET_WORDS - 1)
+ const start = from === 0 && regionStart === 0 ? 0 : words[from].index!
+ const end = to === words.length - 1 && regionEnd === text.length ? text.length : words[to].index! + words[to][0].length
+ const window = text.slice(start, end)
+ const marks: Array<[number, number]> = []
+ for (const pattern of patterns) {
+ pattern.lastIndex = 0
+ for (const match of window.matchAll(pattern)) marks.push([match.index!, match.index! + match[0].length])
+ }
+ marks.sort((a, b) => a[0] - b[0])
+ let out = ''
+ let cursor = 0
+ for (const [markStart, markEnd] of marks) {
+ if (markStart < cursor) continue
+ out += `${window.slice(cursor, markStart)}${MARK_OPEN}${window.slice(markStart, markEnd)}${MARK_CLOSE}`
+ cursor = markEnd
+ }
+ out += window.slice(cursor)
+ return `${start > 0 ? '…' : ''}${out.trim()}${end < text.length ? '…' : ''}`
+}
+
+export class SessionSearchStore {
+ private readonly db: Database
+ private readonly statements = new Map<string, Statement>()
+
+ private constructor(db: Database) {
+ this.db = db
+ }
+
+ /**
+ * The index at `path`, created if missing, for its one writer: the daemon. Null on a Node without
+ * `node:sqlite`. The index is derived data — every row can be rebuilt from the transcripts — so a
+ * file SQLite says is not a database, or is corrupt, is deleted and started again rather than
+ * leaving search broken until somebody notices. Anything else (a lock held by another process)
+ * is thrown: deleting a file somebody has open loses their writes.
+ */
+ static open(path: string): SessionSearchStore | null {
+ try {
+ return SessionSearchStore.openOnce(path)
+ } catch (error) {
+ if (path === ':memory:' || !isCorrupt(error)) throw error
+ for (const suffix of ['', '-wal', '-shm']) rmSync(`${path}${suffix}`, { force: true })
+ return SessionSearchStore.openOnce(path)
+ }
+ }
+
+ /**
+ * The index for a reader beside the daemon (`harness search`): read-only, never migrated, never
+ * deleted. `outdated` when it was written by another schema version — the daemon of that version
+ * owns it and rebuilds it on its next start.
+ */
+ static openReader(path: string): SessionSearchStore | 'missing' | 'outdated' | 'busy' | 'unreadable' | null {
+ const Constructor = builtinSqlite() as unknown as DatabaseConstructor | null
+ if (!Constructor) return null
+ if (!existsSync(path)) return 'missing'
+ let db: Database | null = null
+ try {
+ db = new Constructor(path, { readOnly: true })
+ db.exec('PRAGMA busy_timeout = 3000')
+ const version = db.prepare("SELECT value FROM meta WHERE key = 'schema'").get()?.value
+ if (version === SCHEMA_VERSION) return new SessionSearchStore(db)
+ db.close()
+ return 'outdated'
+ } catch (error) {
+ try { db?.close() } catch { /* already closed */ }
+ // SQLITE_BUSY (5) and SQLITE_LOCKED (6): the daemon is writing; a moment later will do.
+ const code = (error as { errcode?: number } | null)?.errcode
+ if (code === 5 || code === 6) return 'busy'
+ // A table missing is an index from before `meta` existed: another version's.
+ if (/no such table/i.test(error instanceof Error ? error.message : String(error))) return 'outdated'
+ return 'unreadable'
+ }
+ }
+
+ private static openOnce(path: string): SessionSearchStore | null {
+ const Constructor = builtinSqlite() as unknown as DatabaseConstructor | null
+ if (!Constructor) return null
+ const fresh = path !== ':memory:' && !existsSync(path)
+ const db = new Constructor(path)
+ if (path !== ':memory:') {
+ db.exec('PRAGMA journal_mode = WAL')
+ db.exec('PRAGMA synchronous = NORMAL')
+ }
+ db.exec('PRAGMA busy_timeout = 1000')
+ const store = new SessionSearchStore(db)
+ store.migrate()
+ if (fresh) {
+ // What people said to their agents: this user's eyes only, like the transcripts themselves.
+ for (const suffix of ['', '-wal', '-shm']) {
+ try { chmodSync(`${path}${suffix}`, 0o600) } catch { /* not created yet */ }
+ }
+ }
+ return store
+ }
+
+ private migrate(): void {
+ this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)')
+ const version = this.db.prepare("SELECT value FROM meta WHERE key = 'schema'").get()?.value
+ if (version === SCHEMA_VERSION) return
+ this.db.exec(`
+ DROP TABLE IF EXISTS turns_fts;
+ DROP TABLE IF EXISTS turns;
+ DROP TABLE IF EXISTS sessions;
+ CREATE TABLE sessions (
+ session_id TEXT PRIMARY KEY,
+ agent_id TEXT NOT NULL,
+ engine TEXT NOT NULL,
+ path TEXT NOT NULL,
+ header TEXT NOT NULL,
+ size INTEGER NOT NULL,
+ mtime INTEGER NOT NULL,
+ resume_offset INTEGER NOT NULL,
+ resume_turn INTEGER NOT NULL,
+ last_at INTEGER,
+ turns INTEGER NOT NULL
+ );
+ CREATE TABLE turns (
+ id INTEGER PRIMARY KEY,
+ session_id TEXT NOT NULL,
+ turn INTEGER NOT NULL,
+ at INTEGER,
+ name TEXT NOT NULL DEFAULT '',
+ ask TEXT NOT NULL DEFAULT '',
+ answer TEXT NOT NULL DEFAULT '',
+ tools TEXT NOT NULL DEFAULT ''
+ );
+ CREATE UNIQUE INDEX turns_by_session ON turns (session_id, turn);
+ CREATE INDEX turns_by_time ON turns (at);
+ CREATE VIRTUAL TABLE turns_fts USING fts5 (
+ name, ask, answer, tools,
+ content = 'turns', content_rowid = 'id',
+ tokenize = 'unicode61 remove_diacritics 2',
+ prefix = '2 3 4'
+ );
+ CREATE TRIGGER turns_insert AFTER INSERT ON turns BEGIN
+ INSERT INTO turns_fts (rowid, name, ask, answer, tools)
+ VALUES (new.id, new.name, new.ask, new.answer, new.tools);
+ END;
+ CREATE TRIGGER turns_delete AFTER DELETE ON turns BEGIN
+ INSERT INTO turns_fts (turns_fts, rowid, name, ask, answer, tools)
+ VALUES ('delete', old.id, old.name, old.ask, old.answer, old.tools);
+ END;
+ `)
+ this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema', ?)").run(SCHEMA_VERSION)
+ }
+
+ private statement(sql: string): Statement {
+ let statement = this.statements.get(sql)
+ if (!statement) {
+ statement = this.db.prepare(sql)
+ this.statements.set(sql, statement)
+ }
+ return statement
+ }
+
+ private transaction<T>(work: () => T): T {
+ this.db.exec('BEGIN IMMEDIATE')
+ try {
+ const result = work()
+ this.db.exec('COMMIT')
+ return result
+ } catch (error) {
+ this.db.exec('ROLLBACK')
+ throw error
+ }
+ }
+
+ /** Who each session belongs to and when it was last worked on, read once per change. */
+ private meta: Map<string, { agentId: string; engine: string; lastAt: number | null }> | null = null
+
+ private sessionMeta(): Map<string, { agentId: string; engine: string; lastAt: number | null }> {
+ if (!this.meta) {
+ this.meta = new Map(this.statement('SELECT session_id, agent_id, engine, last_at FROM sessions').all().map((row) => [
+ row.session_id as string,
+ { agentId: row.agent_id as string, engine: row.engine as string, lastAt: (row.last_at as number | null) ?? null },
+ ]))
+ }
+ return this.meta
+ }
+
+ session(sessionId: string): IndexedSession | undefined {
+ const row = this.statement('SELECT * FROM sessions WHERE session_id = ?').get(sessionId)
+ return row ? toSession(row) : undefined
+ }
+
+ sessionIds(): string[] {
+ return this.statement('SELECT session_id FROM sessions').all().map((row) => row.session_id as string)
+ }
+
+ /**
+ * Replaces the session's turns from `fromTurn` on with `turns` and records where the next pass
+ * starts, in one transaction: a reader never sees a half-written session.
+ */
+ writeSession(session: IndexedSession, fromTurn: number, turns: readonly IndexedTurn[]): void {
+ this.meta = null
+ this.windowSessions = null
+ this.transaction(() => {
+ this.statement('DELETE FROM turns WHERE session_id = ? AND (turn >= ? OR turn = ?)').run(session.sessionId, fromTurn, HEADER_TURN)
+ const insert = this.statement('INSERT INTO turns (session_id, turn, at, name, ask, answer, tools) VALUES (?, ?, ?, ?, ?, ?, ?)')
+ insert.run(session.sessionId, HEADER_TURN, session.lastAt, session.header, '', '', '')
+ for (const turn of turns) insert.run(session.sessionId, turn.turn, turn.at, '', turn.ask, turn.answer, turn.tools)
+ const count = this.statement('SELECT count(*) AS n FROM turns WHERE session_id = ? AND turn >= 0').get(session.sessionId)?.n as number
+ this.statement(`INSERT OR REPLACE INTO sessions
+ (session_id, agent_id, engine, path, header, size, mtime, resume_offset, resume_turn, last_at, turns)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+ session.sessionId, session.agentId, session.engine, session.path, session.header, session.size,
+ session.mtime, session.resumeOffset, session.resumeTurn, session.lastAt, count,
+ )
+ })
+ }
+
+ removeSession(sessionId: string): void {
+ this.meta = null
+ this.windowSessions = null
+ this.transaction(() => {
+ this.statement('DELETE FROM turns WHERE session_id = ?').run(sessionId)
+ this.statement('DELETE FROM sessions WHERE session_id = ?').run(sessionId)
+ })
+ }
+
+ counts(): { sessions: number; turns: number } {
+ const sessions = this.statement('SELECT count(*) AS n FROM sessions').get()?.n as number
+ const turns = this.statement('SELECT count(*) AS n FROM turns WHERE turn >= 0').get()?.n as number
+ return { sessions, turns }
+ }
+
+ /**
+ * The best sessions for `query`, best first. With `from`/`to` (epoch ms), only sessions worked on
+ * in that window — any turn then, not necessarily the matching one: "the dial one from last week"
+ * is a session about the dial that was open last week. With a window and no words, those
+ * sessions by their latest turn in it. `now` is for tests.
+ */
+ /** Where a query counts as matching too much to rank (tests lower it). */
+ commonMatches = COMMON_MATCHES
+
+ search(query: string, options: SearchOptions = {}): SearchHit[] {
+ const terms = queryTerms(query)
+ const limit = Math.max(1, Math.min(options.limit ?? 30, 100))
+ const now = options.now ?? Date.now()
+ const window = options.from !== undefined && options.to !== undefined && options.from <= options.to
+ ? { from: options.from, to: options.to }
+ : null
+ if (!terms.length) return window ? this.workedOn(window, limit, now) : []
+ const inWindow = window ? this.sessionsWorkedOn(window) : null
+ if (inWindow && !inWindow.size) return []
+
+ // 1. Sessions with one turn holding every word.
+ const best = new Map<string, { id: number; turn: number; at: number | null; rank: number; together: boolean }>()
+ // Ranked inside FTS5 first and joined after, so a word in every turn costs one sort rather than
+ // a join per match; the opening-turn boost is applied to those candidates. Words in a large share
+ // of all turns barely tell one turn from another, and sorting every match by BM25 is the slowest
+ // thing a search can do — those take the most recent matches and let recency decide.
+ const allWords = terms.join(' AND ')
+ const common = this.statement('SELECT count(*) AS n FROM turns_fts WHERE turns_fts MATCH ?').get(allWords)!.n as number > this.commonMatches
+ // A word in a large share of all turns barely tells one from another, and sorting every match
+ // by BM25 is the slowest thing a search can do: those take the newest matching turns, unranked,
+ // and let recency decide. (By turn time, not the highest rowids: a backfill writes the newest
+ // sessions first.) Bounded like the ranked path, so the daemon never holds every match.
+ let rows = common
+ ? this.statement(`
+ SELECT t.id AS id, t.session_id AS sid, t.turn AS turn, t.at AS at, -1 AS rank
+ FROM turns_fts JOIN turns t ON t.id = turns_fts.rowid WHERE turns_fts MATCH ?
+ ORDER BY t.at DESC LIMIT ${CANDIDATE_ROWS}`).all(allWords)
+ : this.statement(`
+ SELECT f.id AS id, t.session_id AS sid, t.turn AS turn, t.at AS at, f.rank AS rank
+ FROM (SELECT rowid AS id, bm25(turns_fts, ${WEIGHTS.join(', ')}) AS rank FROM turns_fts
+ WHERE turns_fts MATCH ? ORDER BY rank LIMIT ${CANDIDATE_ROWS}) f
+ JOIN turns t ON t.id = f.id`).all(allWords)
+ if (inWindow) {
+ // The ranked candidates, narrowed to the window — enough unless the list was cut short and
+ // the window holds few of them; then rank within the window's sessions themselves.
+ const within = rows.filter((row) => inWindow.has(row.sid as string))
+ rows = rows.length < CANDIDATE_ROWS || new Set(within.map((row) => row.sid)).size >= limit
+ ? within
+ : this.statement(`
+ SELECT t.id AS id, t.session_id AS sid, t.turn AS turn, t.at AS at, bm25(turns_fts, ${WEIGHTS.join(', ')}) AS rank
+ FROM turns_fts JOIN turns t ON t.id = turns_fts.rowid
+ WHERE turns_fts MATCH ? AND t.session_id IN (SELECT value FROM json_each(?))
+ ORDER BY rank LIMIT ${CANDIDATE_ROWS}`).all(allWords, JSON.stringify([...inWindow]))
+ }
+ for (const row of rows) {
+ const sid = row.sid as string
+ const turn = row.turn as number
+ const rank = (row.rank as number) * (turn >= 0 && turn < OPENING_TURNS ? OPENING_BOOST : 1)
+ const known = best.get(sid)
+ if (!known || rank < known.rank) best.set(sid, { id: row.id as number, turn, at: row.at as number | null, rank, together: true })
+ }
+
+ // 2. Sessions holding every word, but in different turns. Each word's sessions, intersected.
+ if (terms.length > 1 && best.size < limit) {
+ const perTerm = terms.map((term) => new Set(this.statement(`
+ SELECT DISTINCT t.session_id AS sid FROM turns_fts JOIN turns t ON t.id = turns_fts.rowid
+ WHERE turns_fts MATCH ?`).all(term).map((row) => row.sid as string)))
+ let rarestIndex = 0
+ for (let index = 1; index < perTerm.length; index++) {
+ if (perTerm[index].size < perTerm[rarestIndex].size) rarestIndex = index
+ }
+ const spread = new Set([...perTerm[rarestIndex]].filter((sid) => !best.has(sid) && perTerm.every((set) => set.has(sid)) && (!inWindow || inWindow.has(sid))))
+ // Each such session's best turn for any of the words, in one ranked pass: its rank, discounted
+ // for being spread, and its snippet — from what was said rather than the name, which the row
+ // already shows, unless the name is the only place.
+ if (spread.size) {
+ const header = new Map<string, { id: number; turn: number; at: number | null; rank: number; together: boolean }>()
+ for (const row of this.statement(`
+ SELECT f.id AS id, t.session_id AS sid, t.turn AS turn, t.at AS at, f.rank AS rank
+ FROM (SELECT rowid AS id, bm25(turns_fts, ${WEIGHTS.join(', ')}) AS rank FROM turns_fts
+ WHERE turns_fts MATCH ? ORDER BY rank LIMIT ${CANDIDATE_ROWS}) f
+ JOIN turns t ON t.id = f.id`).all(terms.join(' OR '))) {
+ const sid = row.sid as string
+ if (!spread.has(sid)) continue
+ const turn = row.turn as number
+ const rank = (row.rank as number) * (turn >= 0 && turn < OPENING_TURNS ? OPENING_BOOST : 1) / 2
+ const into = turn === HEADER_TURN ? header : best
+ const known = into.get(sid)
+ if (!known || rank < known.rank) into.set(sid, { id: row.id as number, turn, at: row.at as number | null, rank, together: false })
+ }
+ for (const [sid, match] of header) if (!best.has(sid)) best.set(sid, match)
+ // Common words can fill that ranked window with other sessions' rows. A session that has
+ // every word must not vanish for it: look its best turn up directly, a bounded few at a time,
+ // and rank it last among its kind.
+ const missing = [...spread].filter((sid) => !best.has(sid)).slice(0, limit)
+ if (missing.length) {
+ // bm25 is negative and lower is better, so the weakest rank so far is the largest.
+ let weakest = Number.NEGATIVE_INFINITY
+ for (const match of best.values()) weakest = Math.max(weakest, match.rank)
+ const worst = Number.isFinite(weakest) ? weakest : -1
+ const bestTurn = this.statement(`
+ SELECT t.id AS id, t.turn AS turn, t.at AS at FROM turns_fts JOIN turns t ON t.id = turns_fts.rowid
+ WHERE turns_fts MATCH ? AND t.session_id = ? ORDER BY (t.turn < 0), bm25(turns_fts, ${WEIGHTS.join(', ')}) LIMIT 1`)
+ for (const sid of missing) {
+ const row = bestTurn.get(terms[rarestIndex], sid)
+ if (row) best.set(sid, { id: row.id as number, turn: row.turn as number, at: row.at as number | null, rank: worst * 0.9, together: false })
+ }
+ }
+ }
+ }
+ if (!best.size) return []
+
+ // 3. Relevance (bm25 is negative; lower is better) relative to the best match, blended with how
+ // recently the session was worked on — "the one from last week" usually means the recent one.
+ const sessions = this.sessionMeta()
+ let top = 0
+ for (const match of best.values()) top = Math.min(top, match.rank)
+ const ranked = [...best.entries()]
+ .filter(([sid]) => sessions.has(sid))
+ .map(([sid, match]) => {
+ const session = sessions.get(sid)!
+ const relevance = top < 0 ? match.rank / top : 1
+ const lastAt = session.lastAt ?? match.at
+ const ageDays = lastAt ? Math.max(0, now - lastAt) / 86_400_000 : 365
+ const recency = Math.pow(0.5, ageDays / RECENCY_HALF_LIFE_DAYS)
+ const score = (1 - RECENCY_WEIGHT) * relevance + RECENCY_WEIGHT * recency
+ return { sid, match, session, score }
+ })
+ .sort((a, b) => Number(b.match.together) - Number(a.match.together) || b.score - a.score)
+ .slice(0, limit)
+
+ // 4. For the hits only: which field matched, and the words around it — what the person asked
+ // says the most about a session, then its name, then the answer, then the tools.
+ const patterns = queryWords(query).map(wordPattern)
+ const text = this.statement('SELECT name, ask, answer, tools FROM turns WHERE id = CAST(? AS INTEGER)')
+ return ranked.map(({ sid, match, session, score }) => {
+ const row = text.get(match.id)
+ let field: (typeof FIELDS)[number] = 'ask'
+ let snippet = ''
+ for (const candidate of ['ask', 'name', 'answer', 'tools'] as const) {
+ const found = makeSnippet(String(row?.[candidate] ?? ''), patterns)
+ if (found) {
+ field = candidate
+ snippet = found
+ break
+ }
+ }
+ return {
+ sessionId: sid,
+ agentId: session.agentId,
+ engine: session.engine,
+ turn: match.turn,
+ at: match.at,
+ lastAt: session.lastAt,
+ field,
+ snippet,
+ together: match.together,
+ score: Math.round(score * 1000) / 1000,
+ }
+ })
+ }
+
+ /** The last window asked about, and its sessions: typing on, the window stays the same. */
+ private windowSessions: { from: number; to: number; sessions: Set<string> } | null = null
+
+ /** Sessions with a turn in the window; a session whose turns carry no time, by its last activity. */
+ private sessionsWorkedOn(window: { from: number; to: number }): Set<string> {
+ const cached = this.windowSessions
+ if (cached && cached.from === window.from && cached.to === window.to) return cached.sessions
+ const sessions = this.readSessionsWorkedOn(window)
+ this.windowSessions = { ...window, sessions }
+ return sessions
+ }
+
+ private readSessionsWorkedOn(window: { from: number; to: number }): Set<string> {
+ return new Set(this.statement(`
+ SELECT DISTINCT session_id AS sid FROM turns WHERE turn >= 0 AND at BETWEEN ? AND ?
+ UNION SELECT session_id AS sid FROM sessions WHERE last_at BETWEEN ? AND ?
+ AND NOT EXISTS (SELECT 1 FROM turns u WHERE u.session_id = sessions.session_id AND u.turn >= 0 AND u.at IS NOT NULL)`)
+ .all(window.from, window.to, window.from, window.to).map((row) => row.sid as string))
+ }
+
+ /**
+ * No words, only a window: the sessions worked on then, by their latest turn in it — or, for a
+ * session whose turns carry no time (a database-backed engine), by its last activity. One row
+ * per session.
+ */
+ private workedOn(window: { from: number; to: number }, limit: number, now: number): SearchHit[] {
+ const sessions = this.sessionMeta()
+ const latest = new Map<string, number>()
+ for (const row of this.statement(`
+ SELECT session_id AS sid, max(at) AS at FROM turns
+ WHERE turn >= 0 AND at BETWEEN ? AND ? GROUP BY session_id`).all(window.from, window.to)) {
+ latest.set(row.sid as string, row.at as number)
+ }
+ for (const sid of this.sessionsWorkedOn(window)) {
+ if (!latest.has(sid)) latest.set(sid, sessions.get(sid)?.lastAt ?? window.to)
+ }
+ // The latest thing the person asked in the window, else the latest turn there: a turn an
+ // agent's report opened says less about the session than what was asked.
+ const timedTurn = this.statement(`
+ SELECT id, turn, at, ask, answer FROM turns WHERE session_id = ? AND turn >= 0 AND at BETWEEN ? AND ?
+ ORDER BY (ask = '') ASC, at DESC, turn DESC LIMIT 1`)
+ const lastTurn = this.statement(`
+ SELECT id, turn, at, ask, answer FROM turns WHERE session_id = ? AND turn >= 0 ORDER BY (ask = '') ASC, turn DESC LIMIT 1`)
+ const hits: SearchHit[] = []
+ for (const [sid, at] of [...latest].sort((a, b) => b[1] - a[1]).slice(0, limit)) {
+ const session = sessions.get(sid)
+ const row = timedTurn.get(sid, window.from, window.to) ?? lastTurn.get(sid)
+ if (!session || !row) continue
+ // What was asked; a turn opened by an agent's report has only the agent's side.
+ const asked = String(row.ask ?? '')
+ hits.push({
+ sessionId: sid, agentId: session.agentId, engine: session.engine,
+ turn: row.turn as number, at, lastAt: session.lastAt, field: asked ? 'ask' : 'answer',
+ snippet: clipAsk(asked || String(row.answer ?? '')),
+ together: true,
+ score: Math.round(Math.pow(0.5, Math.max(0, now - at) / 86_400_000 / RECENCY_HALF_LIFE_DAYS) * 1000) / 1000,
+ })
+ }
+ return hits
+ }
+
+ close(): void {
+ this.statements.clear()
+ this.db.close()
+ }
+}
+
+/** SQLite's SQLITE_CORRUPT (11) and SQLITE_NOTADB (26), as node:sqlite reports them. */
+function isCorrupt(error: unknown): boolean {
+ const code = (error as { errcode?: number } | null)?.errcode
+ if (code === 11 || code === 26) return true
+ return /not a database|malformed/i.test(error instanceof Error ? error.message : String(error))
+}
+
+function toSession(row: Record<string, unknown>): IndexedSession {
+ return {
+ sessionId: row.session_id as string,
+ agentId: row.agent_id as string,
+ engine: row.engine as string,
+ path: row.path as string,
+ header: row.header as string,
+ size: row.size as number,
+ mtime: row.mtime as number,
+ resumeOffset: row.resume_offset as number,
+ resumeTurn: row.resume_turn as number,
+ lastAt: (row.last_at as number | null) ?? null,
+ turns: row.turns as number,
+ }
+}
diff --git a/cli/src/lib/sessionSearch/transcript.spec.ts b/cli/src/lib/sessionSearch/transcript.spec.ts
new file mode 100644
index 000000000..a7b48c467
--- /dev/null
+++ b/cli/src/lib/sessionSearch/transcript.spec.ts
@@ -0,0 +1,121 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { forEachLine, lineNormalizer, lineTime, skipPredicate } from './transcript.js'
+import { TurnCollector, type IndexedTurn } from './turns.js'
+
+const dirs: string[] = []
+function file(content: string | Buffer): string {
+ const dir = mkdtempSync(join(tmpdir(), 'session-search-'))
+ dirs.push(dir)
+ const path = join(dir, 'transcript.jsonl')
+ writeFileSync(path, content)
+ return path
+}
+afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+async function lines(path: string, start = 0, skip?: (head: string) => boolean) {
+ const seen: Array<[number, string]> = []
+ const { end } = await forEachLine(path, start, ({ text, offset }) => { seen.push([offset, text]) }, { skip })
+ return { seen, end }
+}
+
+/** Turns from a transcript, through the engine's own normalizer — with or without the output skip. */
+async function turnsOf(engine: string, path: string, skip: boolean): Promise<IndexedTurn[]> {
+ const normalize = lineNormalizer(engine, 'session-1')!
+ const collector = new TurnCollector(0)
+ await forEachLine(path, 0, ({ text, offset }) => collector.feed(normalize(text), offset, lineTime(text)), {
+ skip: skip ? skipPredicate(engine) : null,
+ })
+ const { closed, open } = collector.finish()
+ return open ? [...closed, open] : closed
+}
+
+const at = (minute: number) => `2026-09-20T10:${String(minute).padStart(2, '0')}:00.000Z`
+const claude = {
+ prompt: (text: string, minute: number) => JSON.stringify({ type: 'user', uuid: `u${minute}`, timestamp: at(minute), message: { role: 'user', content: text } }),
+ toolUse: (id: string, command: string, minute: number) => JSON.stringify({ type: 'assistant', uuid: `a${minute}`, timestamp: at(minute), message: { role: 'assistant', content: [{ type: 'tool_use', id, name: 'Bash', input: { command } }], stop_reason: 'tool_use' } }),
+ toolResult: (id: string, output: string, minute: number) => JSON.stringify({ type: 'user', uuid: `r${minute}`, timestamp: at(minute), message: { role: 'user', content: [{ tool_use_id: id, type: 'tool_result', content: output }] } }),
+ answer: (text: string, minute: number) => JSON.stringify({ type: 'assistant', uuid: `b${minute}`, timestamp: at(minute), message: { role: 'assistant', content: [{ type: 'text', text }], stop_reason: 'end_turn' } }),
+}
+const codex = {
+ line: (minute: number, type: string, payload: Record<string, unknown>) => JSON.stringify({ timestamp: at(minute), type, payload }),
+}
+
+describe('forEachLine', () => {
+ it('reports each complete line with its byte offset and leaves a partial last line for later', async () => {
+ const path = file('first\nsécond\nthird-without-newline')
+ const { seen, end } = await lines(path)
+ expect(seen).toEqual([[0, 'first'], [6, 'sécond']])
+ expect(end).toBe(Buffer.byteLength('first\nsécond\n'))
+ expect((await lines(path, end)).seen).toEqual([])
+ })
+
+ it('resumes from an offset and reads lines longer than one read chunk', async () => {
+ const long = 'x'.repeat(3 * 1024 * 1024)
+ const path = file(`a\n${long}\nb\n`)
+ const { seen, end } = await lines(path)
+ expect(seen.map(([offset, text]) => [offset, text.length])).toEqual([[0, 1], [2, long.length], [long.length + 3, 1]])
+ expect((await lines(path, 2)).seen.map(([, text]) => text.length)).toEqual([long.length, 1])
+ expect(end).toBe(long.length + 5)
+ })
+
+ it('drops a skipped line unread and keeps counting offsets through it', async () => {
+ const path = file(`keep 1\nDROP ${'y'.repeat(2 * 1024 * 1024)}\nkeep 2\n`)
+ const { seen } = await lines(path, 0, (head) => head.startsWith('DROP'))
+ expect(seen.map(([, text]) => text)).toEqual(['keep 1', 'keep 2'])
+ expect(seen[1][0]).toBe(7 + 5 + 2 * 1024 * 1024 + 1)
+ })
+})
+
+describe('lineTime', () => {
+ it('reads the record time wherever the field sits', () => {
+ expect(lineTime(claude.answer('hi', 3))).toBe(Date.parse(at(3)))
+ expect(lineTime('{"type":"x"}')).toBeNull()
+ })
+})
+
+describe('skipping tool output', () => {
+ it('leaves Claude turns exactly as the normalizer reads them in full', async () => {
+ const path = file([
+ claude.prompt('Why does the dial scroll jump?', 0),
+ claude.toolUse('t1', 'rg scroll devices/dial', 1),
+ claude.toolResult('t1', 'devices/dial/src/ui.c:120 scroll_by(...)\n'.repeat(2000), 2),
+ claude.answer('The scroll delta is doubled in ui.c.', 3),
+ claude.prompt('fix it', 4),
+ claude.answer('Fixed and flashed.', 5),
+ ].join('\n') + '\n')
+ const full = await turnsOf('claude', path, false)
+ expect(await turnsOf('claude', path, true)).toEqual(full)
+ expect(full.map((turn) => [turn.ask, turn.answer, turn.tools, turn.at])).toEqual([
+ ['Why does the dial scroll jump?', 'The scroll delta is doubled in ui.c.', 'Bash rg scroll devices/dial', Date.parse(at(0))],
+ ['fix it', 'Fixed and flashed.', '', Date.parse(at(4))],
+ ])
+ })
+
+ it('leaves Codex turns exactly as the normalizer reads them in full', async () => {
+ const path = file([
+ codex.line(0, 'session_meta', { id: 'session-1', cwd: '/work/app' }),
+ codex.line(1, 'event_msg', { type: 'task_started' }),
+ codex.line(1, 'event_msg', { type: 'user_message', message: 'summarize the retention cohorts' }),
+ codex.line(2, 'response_item', { type: 'reasoning', summary: [{ type: 'summary_text', text: 'thinking' }] }),
+ codex.line(3, 'response_item', { type: 'function_call', call_id: 'c1', name: 'shell', arguments: JSON.stringify({ command: ['bash', '-lc', 'python3 cohorts.py'] }) }),
+ codex.line(4, 'response_item', { type: 'function_call_output', call_id: 'c1', output: 'row\n'.repeat(5000) }),
+ codex.line(5, 'event_msg', { type: 'agent_message', message: 'Day-7 retention is 35%.' }),
+ codex.line(5, 'event_msg', { type: 'token_count', info: {} }),
+ codex.line(6, 'event_msg', { type: 'task_complete' }),
+ ].join('\n') + '\n')
+ const full = await turnsOf('codex', path, false)
+ expect(await turnsOf('codex', path, true)).toEqual(full)
+ expect(full).toHaveLength(1)
+ expect(full[0]).toMatchObject({ ask: 'summarize the retention cohorts', answer: 'Day-7 retention is 35%.' })
+ expect(full[0].tools).toContain('python3 cohorts.py')
+ })
+
+ it('has no normalizer for engines whose history is not a JSONL file', () => {
+ for (const engine of ['opencode', 'kilo', 'hermes', 'devin', 'terminal']) expect(lineNormalizer(engine, 's')).toBeNull()
+ })
+})
diff --git a/cli/src/lib/sessionSearch/transcript.ts b/cli/src/lib/sessionSearch/transcript.ts
new file mode 100644
index 000000000..fefb9c8f1
--- /dev/null
+++ b/cli/src/lib/sessionSearch/transcript.ts
@@ -0,0 +1,166 @@
+/**
+ * Reading a transcript for session search: line by line from a byte offset, through the same
+ * incremental normalizer each engine uses for its live view.
+ *
+ * Transcripts are large (a long Codex rollout runs to gigabytes) and nearly all of it is tool output.
+ * The reader looks at the first bytes of each line and drops the output records before they are
+ * decoded or parsed, and never holds more than one line in memory — a 200 MB command dump costs a
+ * seek, not a parse.
+ */
+
+import { open } from 'node:fs/promises'
+
+import type { LiveEvent } from '../normalize.js'
+import { lineToEvents, newTurnState } from '../normalize.js'
+import { AgyNormalizer } from '../../engines/agy/normalizer.js'
+import { AmpNormalizer } from '../../engines/amp/normalizer.js'
+import { CodexNormalizer } from '../../engines/codex/normalizer.js'
+import { CommandCodeNormalizer } from '../../engines/commandcode/normalizer.js'
+import { CopilotNormalizer } from '../../engines/copilot/normalizer.js'
+import { CursorNormalizer } from '../../engines/cursor/normalizer.js'
+import { GrokNormalizer } from '../../engines/grok/normalizer.js'
+import { MuseNormalizer } from '../../engines/muse/normalizer.js'
+import { PiNormalizer } from '../../engines/pi/normalizer.js'
+
+export type LineNormalizer = (line: string) => LiveEvent[]
+
+/**
+ * A fresh normalizer for one pass over one transcript, or null for an engine whose history is not a
+ * JSONL file (OpenCode, Kilo, Hermes and Devin keep theirs in a database; a terminal has none).
+ * Fresh on every pass: a pass starts at a turn boundary, where no earlier state is needed.
+ */
+export function lineNormalizer(engine: string, sessionId: string): LineNormalizer | null {
+ switch (engine) {
+ case 'claude': {
+ const state = newTurnState()
+ return (line) => lineToEvents(line, state)
+ }
+ case 'codex': {
+ // Sub-agent threads are resolved for the live view's cards; search only needs the text.
+ const normalizer = new CodexNormalizer('live', () => null)
+ return (line) => normalizer.ingest(line)
+ }
+ case 'cursor': {
+ const normalizer = new CursorNormalizer('live', sessionId)
+ return (line) => normalizer.ingest(line)
+ }
+ case 'muse': return ingestWith(new MuseNormalizer())
+ case 'amp': return ingestWith(new AmpNormalizer())
+ case 'grok': return ingestWith(new GrokNormalizer())
+ case 'agy': return ingestWith(new AgyNormalizer())
+ case 'copilot': return ingestWith(new CopilotNormalizer())
+ case 'pi': return ingestWith(new PiNormalizer('live'))
+ case 'commandcode': return ingestWith(new CommandCodeNormalizer('live'))
+ default: return null
+ }
+}
+
+function ingestWith(normalizer: { ingest(line: string): LiveEvent[] }): LineNormalizer {
+ return (line) => normalizer.ingest(line)
+}
+
+/**
+ * Records that carry only tool output, reasoning or accounting, told apart by their opening bytes.
+ * Skipping them is safe because the turn collector reads prompts, answer text and tool calls only;
+ * `transcript.spec.ts` checks the turns come out the same with and without the skip.
+ */
+const SKIP_HEAD: Record<string, RegExp> = {
+ codex: /"type":"(?:function_call_output|custom_tool_call_output|reasoning|token_count|local_shell_call_output|web_search_call_output)"|^\{"timestamp":"[^"]*","type":"token_usage_record"/,
+ // A user record whose content is a tool result. A prompt can never open with one.
+ claude: /^\{[^]*?"type":"user"[^]*?"content":\[\{"tool_use_id"|^\{[^]*?"type":"user"[^]*?"content":\[\{"type":"tool_result"/,
+}
+
+/** How much of a line is read before deciding whether to skip it. */
+const HEAD_BYTES = 1024
+/** A longer line is not a prompt or an answer anyone wrote; it is dropped unread. */
+const MAX_LINE_BYTES = 16 * 1024 * 1024
+const CHUNK_BYTES = 1024 * 1024
+
+export function skipPredicate(engine: string): ((head: string) => boolean) | null {
+ const pattern = SKIP_HEAD[engine]
+ return pattern ? (head) => pattern.test(head) : null
+}
+
+const TIMESTAMP = /"timestamp"\s*:\s*"([^"]{10,40})"/
+
+/** When a transcript line was written, from its own `timestamp` field; null when it has none. */
+export function lineTime(line: string): number | null {
+ const match = TIMESTAMP.exec(line)
+ if (!match) return null
+ const at = Date.parse(match[1])
+ return Number.isFinite(at) ? at : null
+}
+
+export interface LineVisit {
+ text: string
+ /** Byte offset of the line's first byte. */
+ offset: number
+}
+
+/**
+ * Calls `visit` for every complete line from `start`, and resolves with the offset just past the last
+ * complete line. A final line without its newline is left for the next pass: the engine may still be
+ * writing it. `visit` may return a promise to pace the reader.
+ */
+export async function forEachLine(
+ path: string,
+ start: number,
+ visit: (line: LineVisit) => void | Promise<void>,
+ options: { skip?: ((head: string) => boolean) | null; shouldStop?: () => boolean } = {},
+): Promise<{ end: number }> {
+ const handle = await open(path, 'r')
+ try {
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES)
+ let position = start
+ let lineStart = start
+ let parts: Buffer[] = []
+ let length = 0
+ let decided = false
+ let dropping = false
+ for (;;) {
+ if (options.shouldStop?.()) return { end: lineStart }
+ const { bytesRead } = await handle.read(buffer, 0, CHUNK_BYTES, position)
+ if (bytesRead === 0) return { end: lineStart }
+ let cursor = 0
+ while (cursor < bytesRead) {
+ const newline = buffer.indexOf(10, cursor)
+ const stop = newline === -1 || newline >= bytesRead ? bytesRead : newline
+ if (!dropping) {
+ const piece = buffer.subarray(cursor, stop)
+ if (length + piece.length > MAX_LINE_BYTES) {
+ dropping = true
+ parts = []
+ length = 0
+ } else {
+ parts.push(Buffer.from(piece))
+ length += piece.length
+ if (!decided && options.skip && (length >= HEAD_BYTES || stop < bytesRead)) {
+ decided = true
+ const head = Buffer.concat(parts, length).subarray(0, HEAD_BYTES).toString('utf8')
+ if (options.skip(head)) {
+ dropping = true
+ parts = []
+ length = 0
+ }
+ }
+ }
+ }
+ if (stop === bytesRead) break
+ // A complete line.
+ if (!dropping && length > 0) {
+ const text = Buffer.concat(parts, length).toString('utf8')
+ await visit({ text, offset: lineStart })
+ }
+ lineStart = position + stop + 1
+ parts = []
+ length = 0
+ decided = false
+ dropping = false
+ cursor = stop + 1
+ }
+ position += bytesRead
+ }
+ } finally {
+ await handle.close()
+ }
+}
diff --git a/cli/src/lib/sessionSearch/turns.spec.ts b/cli/src/lib/sessionSearch/turns.spec.ts
new file mode 100644
index 000000000..1d934879e
--- /dev/null
+++ b/cli/src/lib/sessionSearch/turns.spec.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+
+import type { LiveEvent } from '../normalize.js'
+import { ANSWER_MAX, ASK_MAX, TOOLS_MAX, TurnCollector, searchableText, toolText } from './turns.js'
+
+const ask = (text: string): LiveEvent => ({ type: 'turn_started', payload: { userMessage: text } })
+const say = (text: string): LiveEvent => ({ type: 'text_delta', payload: { content: text } })
+const tool = (name: string, input: unknown): LiveEvent => ({ type: 'tool_start', payload: { id: name, tool: name, input } })
+
+describe('TurnCollector', () => {
+ it('folds prompts, answers and tool calls into turns, the last one left open', () => {
+ const turns = new TurnCollector(0)
+ turns.feed([ask('Port the daemon to Windows')], 0, 1_000)
+ turns.feed([say('Reading the tmux backend first.'), tool('Read', { file_path: 'cli/src/lib/tmux.ts' })], 40, 1_100)
+ turns.feed([say('It needs a named-pipe transport.'), { type: 'turn_ended', payload: {} }], 90, 1_200)
+ turns.feed([ask('ok do it')], 130, 2_000)
+ const { closed, open } = turns.finish()
+ expect(closed).toEqual([{
+ turn: 0, offset: 0, at: 1_000, ask: 'Port the daemon to Windows',
+ answer: 'Reading the tmux backend first. It needs a named-pipe transport.',
+ tools: 'Read cli/src/lib/tmux.ts',
+ }])
+ expect(open).toMatchObject({ turn: 1, offset: 130, at: 2_000, ask: 'ok do it', answer: '' })
+ expect(turns.next).toBe(2)
+ })
+
+ it('counts a prompt announced twice as one turn, and a replayed user_message as a new one', () => {
+ const turns = new TurnCollector(5)
+ turns.feed([ask('fix the dial scroll'), { type: 'user_message', payload: { content: 'fix the dial scroll' } }], 0, null)
+ turns.feed([say('done')], 10, null)
+ turns.feed([{ type: 'user_message', payload: { content: 'now the pane title' } }], 20, null)
+ const { closed, open } = turns.finish()
+ expect(closed.map((turn) => [turn.turn, turn.ask])).toEqual([[5, 'fix the dial scroll']])
+ expect(open).toMatchObject({ turn: 6, ask: 'now the pane title' })
+ })
+
+ it('keeps text that arrives before any prompt as a turn of its own, and drops empty ones', () => {
+ const turns = new TurnCollector(0)
+ turns.feed([say('…and the tests pass.')], 0, null)
+ turns.feed([ask('')], 10, null)
+ turns.feed([ask('next')], 20, null)
+ const { closed, open } = turns.finish()
+ expect(closed.map((turn) => [turn.ask, turn.answer])).toEqual([['', '…and the tests pass.']])
+ expect(open?.ask).toBe('next')
+ })
+
+ it('bounds every field, keeping the end of a long answer where the outcome is', () => {
+ const turns = new TurnCollector(0)
+ turns.feed([ask('x'.repeat(ASK_MAX * 2))], 0, null)
+ for (let i = 0; i < 400; i++) turns.feed([say(`step ${i} ${'y'.repeat(200)}`)], i, null)
+ turns.feed([say('FINAL OUTCOME')], 500, null)
+ for (let i = 0; i < 200; i++) turns.feed([tool('Bash', { command: `echo ${i} ${'z'.repeat(100)}` })], 600 + i, null)
+ const { open } = turns.finish()
+ expect(open!.ask.length).toBe(ASK_MAX)
+ expect(open!.answer.length).toBeLessThanOrEqual(ANSWER_MAX + 3)
+ expect(open!.answer.startsWith('step 0 ')).toBe(true)
+ expect(open!.answer.endsWith('FINAL OUTCOME')).toBe(true)
+ expect(open!.tools.length).toBeLessThanOrEqual(TOOLS_MAX)
+ })
+})
+
+describe('what the person asked, and what they did not', () => {
+ it('files a sub-agent hand-back under the agent, and drops notices', () => {
+ const turns = new TurnCollector(0)
+ turns.feed([ask('Another Claude session sent a message: <agent-message from="a1">[Subagent hand-back] the dial audit found 3 bugs</agent-message>')], 0, null)
+ turns.feed([say('Fixing them now.')], 10, null)
+ turns.feed([ask('Your claude.ai usage limit has reset. Continue the task you were working on.')], 20, null)
+ turns.feed([ask('now flash it')], 30, null)
+ const { closed, open } = turns.finish()
+ // The notice leaves nothing behind; the hand-back is the agent's text, not an ask.
+ expect(closed).toHaveLength(1)
+ expect(closed[0].ask).toBe('')
+ expect(closed[0].answer).toContain('the dial audit found 3 bugs')
+ expect(closed[0].answer).toContain('Fixing them now.')
+ expect(open?.ask).toBe('now flash it')
+ })
+
+ it('counts a hand-back announced twice as one turn', () => {
+ const turns = new TurnCollector(0)
+ const report = 'Another Claude session sent a message: the audit is done'
+ turns.feed([ask(report), { type: 'user_message', payload: { content: report } }], 0, null)
+ turns.feed([ask('thanks, ship it')], 10, null)
+ const { closed } = turns.finish()
+ expect(closed).toHaveLength(1)
+ })
+})
+
+describe('searchableText', () => {
+ it('drops harness wrappers, folds whitespace and blanks secrets', () => {
+ expect(searchableText('<system-reminder>ignore\nthis</system-reminder>deploy with\nsk-abcdefghijklmnop', 100))
+ .toBe('deploy with sk-<redacted>')
+ expect(searchableText('<command-name>/clear</command-name> hello', 100)).toBe('hello')
+ expect(searchableText('see <pasted_content id="c200"> https://github.com/x/y/issues/167 </pasted_content id="c200">', 100))
+ .toBe('see https://github.com/x/y/issues/167')
+ })
+})
+
+describe('toolText', () => {
+ it('keeps the paths, commands and queries a person would search by', () => {
+ expect(toolText('Edit', { file_path: 'desktop/lib/state/swarm_search.dart', old_string: 'a'.repeat(5000) }))
+ .toBe('Edit desktop/lib/state/swarm_search.dart')
+ expect(toolText('Bash', { command: "python3 - <<'EOF'\nprint(1)\nEOF", description: 'Run the probe' }))
+ .toBe("Bash python3 - <<'EOF' Run the probe")
+ expect(toolText('WebSearch', '{"query":"fts5 prefix index"}')).toBe('WebSearch fts5 prefix index')
+ })
+
+ it('drops encoded blobs, which are never words anybody searches for', () => {
+ expect(toolText('Task', { description: `gAAAAB${'q'.repeat(120)} audit onboarding` })).toBe('Task audit onboarding')
+ })
+
+ it('names a patch by its files, never its contents', () => {
+ const patch = '*** Begin Patch\n*** Update File: cli/src/cli.ts\n@@\n-secret\n+other\n*** Add File: docs/a.md\n*** End Patch'
+ expect(toolText('apply_patch', patch)).toBe('apply_patch cli/src/cli.ts docs/a.md')
+ expect(toolText('apply_patch', { input: patch })).toBe('apply_patch cli/src/cli.ts docs/a.md')
+ })
+})
diff --git a/cli/src/lib/sessionSearch/turns.ts b/cli/src/lib/sessionSearch/turns.ts
new file mode 100644
index 000000000..cef0b8b02
--- /dev/null
+++ b/cli/src/lib/sessionSearch/turns.ts
@@ -0,0 +1,230 @@
+/**
+ * What one turn of a conversation contributes to session search: what the person asked, what the
+ * agent answered, and which files and commands it touched on the way.
+ *
+ * Built from the engines' normalized `LiveEvent` stream, so every engine's transcript format is
+ * already parsed and cleaned by the normalizer that serves the live view. Tool OUTPUT, reasoning and
+ * images are left out on purpose: they are nearly all of a transcript's bytes and almost none of what a
+ * person remembers about it. Tool INPUT is kept, but only the parts a person would search by — a file
+ * path, a command, a URL — never a heredoc body or a patch's contents.
+ */
+
+import type { LiveEvent } from '../normalize.js'
+import { redactSecretsInText } from '../logBundle.js'
+
+export interface IndexedTurn {
+ /** Position in the session, counting from 0. */
+ turn: number
+ /** Byte offset of the transcript line that opened this turn — where a later pass resumes. */
+ offset: number
+ /** When the turn opened (epoch ms), or null when the transcript does not say. */
+ at: number | null
+ ask: string
+ answer: string
+ tools: string
+}
+
+export const ASK_MAX = 8_000
+export const ANSWER_MAX = 12_000
+/** The start of an answer usually says what it will do and the end what was done: keep both. */
+const ANSWER_HEAD = 3_000
+export const TOOLS_MAX = 4_000
+const TOOL_VALUE_MAX = 300
+
+// Harness and engine wrappers that ride inside a prompt but are not what the person typed.
+const WRAPPER_TAGS = [
+ 'system-reminder', 'command-name', 'command-message', 'command-args', 'local-command-stdout',
+ 'local-command-stderr', 'local-command-caveat', 'user-prompt-submit-hook', 'environment_context',
+ 'user_instructions', 'turn_aborted',
+]
+const WRAPPERS = new RegExp(`<(${WRAPPER_TAGS.join('|')})>[\\s\\S]*?</\\1>`, 'g')
+
+/**
+ * Messages that arrive as the person's turn but were written by the harness or another agent: a
+ * sub-agent handing back its report, a notice that a limit reset. Searchable — a report says what
+ * was done — but as the agent's side, never as what the person asked.
+ */
+const AGENT_WRITTEN = /^(?:Another \w+ session sent a message|<agent-message\b|\[Subagent hand-back\])/
+/** Notices with nothing to find: dropped. */
+const NOTICE = /^(?:Your claude\.ai usage limit has reset|\[Request interrupted by user|\[SYSTEM NOTIFICATION)/
+
+export type AskKind = 'person' | 'agent' | 'notice'
+
+export function askKind(text: string): AskKind {
+ const start = text.trimStart()
+ if (NOTICE.test(start)) return 'notice'
+ if (AGENT_WRITTEN.test(start)) return 'agent'
+ return 'person'
+}
+
+// A paste's markers: what was pasted is the person's, and searchable; the tags around it are not.
+const PASTE_TAGS = /<\/?pasted_content\b[^>]*>/g
+
+/** Text as it is stored and searched: wrappers out, whitespace folded, secrets blanked, bounded. */
+export function searchableText(text: string, max: number): string {
+ const folded = redactSecretsInText(text.replace(WRAPPERS, ' ').replace(PASTE_TAGS, ' ')).replace(/\s+/g, ' ').trim()
+ return folded.length > max ? folded.slice(0, max) : folded
+}
+
+function boundedAnswer(text: string): string {
+ const folded = searchableText(text, Number.MAX_SAFE_INTEGER)
+ if (folded.length <= ANSWER_MAX) return folded
+ return `${folded.slice(0, ANSWER_HEAD)} … ${folded.slice(folded.length - (ANSWER_MAX - ANSWER_HEAD))}`
+}
+
+const TOOL_KEYS = [
+ 'file_path', 'filePath', 'notebook_path', 'path', 'paths', 'command', 'cmd', 'pattern', 'url',
+ 'query', 'description', 'subject', 'skill', 'subagent_type',
+]
+const PATCH_FILE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm
+
+function patchFiles(text: string): string[] {
+ return [...text.matchAll(PATCH_FILE)].map((match) => match[1].trim())
+}
+
+// An unbroken run this long is an encoded blob (Codex seals sub-agent context this way), never a word.
+const BLOB = /[A-Za-z0-9+/=_-]{81,}/g
+
+function clip(value: string): string {
+ const firstLine = value.split('\n', 1)[0].replace(BLOB, ' ').replace(/\s+/g, ' ').trim()
+ return firstLine.length > TOOL_VALUE_MAX ? firstLine.slice(0, TOOL_VALUE_MAX) : firstLine
+}
+
+/** The searchable part of one tool call: its name and the paths, commands and queries it was given. */
+export function toolText(tool: string, input: unknown): string {
+ const parts: string[] = []
+ const take = (value: unknown): void => {
+ if (typeof value === 'string') {
+ const files = patchFiles(value)
+ if (files.length) parts.push(...files)
+ else if (value.trim()) parts.push(clip(value.trim()))
+ } else if (Array.isArray(value)) {
+ for (const item of value.slice(0, 20)) if (typeof item === 'string') take(item)
+ }
+ }
+ let value = input
+ if (typeof value === 'string') {
+ const text = value.trim()
+ if (text.startsWith('{')) {
+ try { value = JSON.parse(text) } catch { /* a plain string input */ }
+ }
+ }
+ if (typeof value === 'string') take(value)
+ else if (value && typeof value === 'object') {
+ const record = value as Record<string, unknown>
+ for (const key of TOOL_KEYS) if (key in record) take(record[key])
+ // apply_patch and friends carry the patch as `input`/`patch`: only its file names are kept.
+ for (const key of ['input', 'patch']) {
+ if (typeof record[key] === 'string') parts.push(...patchFiles(record[key] as string))
+ }
+ }
+ return [tool, ...parts.filter(Boolean)].join(' ')
+}
+
+interface Draft {
+ /** The message that opened the turn, as it arrived: a second announcement of it is the same turn. */
+ opener: string
+ turn: number
+ offset: number
+ at: number | null
+ ask: string
+ answer: string[]
+ answerLength: number
+ tools: string[]
+ toolsLength: number
+}
+
+/**
+ * Folds a stream of normalized events into turns. A turn opens on a prompt (`turn_started`, or a
+ * `user_message` from an engine that replays without the turn lifecycle) and closes when the next one
+ * opens; the last turn stays open because more of it may still be written.
+ */
+export class TurnCollector {
+ private draft: Draft | null = null
+ private readonly closed: IndexedTurn[] = []
+
+ constructor(private nextTurn: number) {}
+
+ /** The number the next turn will take. */
+ get next(): number { return this.nextTurn }
+
+ /** Events normalized from one transcript line, with that line's offset and time. */
+ feed(events: readonly LiveEvent[], offset: number, at: number | null): void {
+ for (const event of events) {
+ switch (event.type) {
+ case 'turn_started':
+ this.open(event.payload.userMessage, offset, at)
+ break
+ case 'user_message': {
+ const content = event.payload.content
+ // The live normalizers announce a prompt twice (the turn, then the message): one turn.
+ if (this.draft && this.draft.opener === content && this.draft.answerLength === (askKind(content) === 'agent' ? content.length : 0)) break
+ this.open(content, offset, at)
+ break
+ }
+ case 'text_delta':
+ this.current(offset, at).answer.push(event.payload.content)
+ this.draft!.answerLength += event.payload.content.length
+ // Bounded while reading: a runaway turn must not hold megabytes until it closes.
+ if (this.draft!.answerLength > ANSWER_MAX * 4) this.compactAnswer()
+ break
+ case 'tool_start': {
+ const draft = this.current(offset, at)
+ if (draft.toolsLength >= TOOLS_MAX) break
+ const text = toolText(event.payload.tool, event.payload.input)
+ draft.tools.push(text)
+ draft.toolsLength += text.length + 1
+ break
+ }
+ default:
+ break
+ }
+ }
+ }
+
+ /** Every turn closed so far, then the one still open (if any). Call once, after the last line. */
+ finish(): { closed: IndexedTurn[]; open: IndexedTurn | null } {
+ const open = this.draft ? this.seal(this.draft) : null
+ this.draft = null
+ return { closed: this.closed, open }
+ }
+
+ private open(ask: string, offset: number, at: number | null): void {
+ if (this.draft) this.close()
+ const kind = askKind(ask)
+ this.draft = {
+ opener: ask,
+ turn: this.nextTurn++, offset, at,
+ ask: kind === 'person' ? searchableText(ask, ASK_MAX) : '',
+ answer: kind === 'agent' ? [ask] : [],
+ answerLength: kind === 'agent' ? ask.length : 0,
+ tools: [], toolsLength: 0,
+ }
+ }
+
+ /** Text or a tool call before any prompt: a turn the transcript picked up in the middle. */
+ private current(offset: number, at: number | null): Draft {
+ if (!this.draft) this.draft = { opener: '', turn: this.nextTurn++, offset, at, ask: '', answer: [], answerLength: 0, tools: [], toolsLength: 0 }
+ return this.draft
+ }
+
+ private compactAnswer(): void {
+ const draft = this.draft!
+ const text = boundedAnswer(draft.answer.join('\n'))
+ draft.answer = [text]
+ draft.answerLength = text.length
+ }
+
+ private close(): void {
+ const sealed = this.seal(this.draft!)
+ if (sealed) this.closed.push(sealed)
+ this.draft = null
+ }
+
+ private seal(draft: Draft): IndexedTurn | null {
+ const answer = boundedAnswer(draft.answer.join('\n'))
+ const tools = draft.tools.join('\n').slice(0, TOOLS_MAX)
+ if (!draft.ask && !answer && !tools) return null
+ return { turn: draft.turn, offset: draft.offset, at: draft.at, ask: draft.ask, answer, tools }
+ }
+}
diff --git a/cli/src/lib/sessionSearch/when.spec.ts b/cli/src/lib/sessionSearch/when.spec.ts
new file mode 100644
index 000000000..9a9b2dc63
--- /dev/null
+++ b/cli/src/lib/sessionSearch/when.spec.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseSearchWhen } from './when.js'
+
+// Saturday 26 September 2026, 14:30 local — the same cases as desktop/test/search_when_test.dart.
+const now = new Date(2026, 8, 26, 14, 30)
+const day = (d: number) => new Date(2026, 8, d).getTime()
+const read = (query: string) => {
+ const { words, when } = parseSearchWhen(query, now)
+ return { words, from: when?.from, to: when?.to }
+}
+
+describe('parseSearchWhen', () => {
+ it('reads the common ways of saying when, and takes them out of the words', () => {
+ expect(read('dial today')).toEqual({ words: 'dial', from: day(26), to: now.getTime() })
+ expect(read('yesterday dial')).toEqual({ words: 'dial', from: day(25), to: day(26) })
+ expect(read('dial this week')).toEqual({ words: 'dial', from: day(21), to: now.getTime() })
+ expect(read('dial LAST WEEK scroll')).toEqual({ words: 'dial scroll', from: day(14), to: day(21) })
+ expect(read('cohorts last month')).toEqual({ words: 'cohorts', from: new Date(2026, 7).getTime(), to: new Date(2026, 8).getTime() })
+ })
+
+ it('keeps "ago" loose, the way memory is', () => {
+ expect(read('dial 3 days ago')).toEqual({ words: 'dial', from: day(22), to: day(25) })
+ expect(read('a few days ago mobile')).toEqual({ words: 'mobile', from: day(20), to: day(25) })
+ expect(read('two weeks ago')).toEqual({ words: '', from: day(8), to: day(17) })
+ expect(read('a week ago dial')).toEqual({ words: 'dial', from: day(15), to: day(24) })
+ })
+
+ it('a weekday is its most recent one; "last" skips today', () => {
+ expect(read('dial on monday')).toEqual({ words: 'dial', from: day(21), to: day(22) })
+ expect(read('on friday')).toEqual({ words: '', from: day(25), to: day(26) })
+ expect(read('dial on saturday')).toEqual({ words: 'dial', from: day(26), to: now.getTime() })
+ expect(read('dial last saturday')).toEqual({ words: 'dial', from: day(19), to: day(20) })
+ })
+
+ it('leaves words alone that only look like time', () => {
+ expect(read('dial 0 days ago')).toEqual({ words: 'dial', from: day(25), to: now.getTime() })
+ for (const query of ['dial', 'todays menu', 'sundays', 'weekday parser', 'lastweek', 'sun mon', 'days ago', 'friday deploy']) {
+ expect(parseSearchWhen(query, now)).toEqual({ words: query, when: null })
+ }
+ })
+})
diff --git a/cli/src/lib/sessionSearch/when.ts b/cli/src/lib/sessionSearch/when.ts
new file mode 100644
index 000000000..a8c2d1b5f
--- /dev/null
+++ b/cli/src/lib/sessionSearch/when.ts
@@ -0,0 +1,70 @@
+/**
+ * When a search is about, read from its words: "dial last week", "yesterday", "3 days ago",
+ * "on monday". The same phrases the desktop's Cmd-P reads (`desktop/lib/state/search_when.dart`);
+ * keep the two in step. The phrase becomes a window and is taken out of the words.
+ */
+
+export interface SearchWhen {
+ from: number
+ to: number
+ phrase: string
+}
+
+const NUMBERS: Record<string, number> = {
+ a: 1, an: 1, one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+}
+
+const WEEKDAYS: Record<string, number> = {
+ sunday: 0, monday: 1, tuesday: 2, wednesday: 3, thursday: 4, friday: 5, saturday: 6,
+}
+
+const PHRASES = new RegExp(
+ '(?<![\\p{L}\\p{N}])(?:'
+ + '(?<today>today)'
+ + '|(?<yesterday>yesterday)'
+ + '|(?<thisweek>this week)'
+ + '|(?<lastweek>last week)'
+ + '|(?<thismonth>this month)'
+ + '|(?<lastmonth>last month)'
+ + '|(?<few>(?:a )?few days ago|(?:a )?couple(?: of)? days ago)'
+ + '|(?<count>\\d{1,2}|a|an|one|two|three|four|five|six|seven|eight|nine|ten) (?<unit>days?|weeks?) ago'
+ // A weekday only with "on" or "last": "friday deploy" is a harness's name, "on friday" is a time.
+ + '|(?<last>last|on) (?<weekday>monday|tuesday|wednesday|thursday|friday|saturday|sunday)'
+ + ')(?![\\p{L}\\p{N}])',
+ 'iu',
+)
+
+/** The words with any time phrase taken out, and the window it names (local time). */
+export function parseSearchWhen(query: string, now: Date): { words: string; when: SearchWhen | null } {
+ const match = PHRASES.exec(query)
+ if (!match || match.index === undefined) return { words: query, when: null }
+ const groups = match.groups ?? {}
+ const day = (offset: number) => new Date(now.getFullYear(), now.getMonth(), now.getDate() + offset).getTime()
+ // Monday-first weeks, as the desktop reads them.
+ const weekday = (now.getDay() + 6) % 7 + 1
+ let from: number
+ let to: number
+ if (groups.today) [from, to] = [day(0), now.getTime()]
+ else if (groups.yesterday) [from, to] = [day(-1), day(0)]
+ else if (groups.thisweek) [from, to] = [day(1 - weekday), now.getTime()]
+ else if (groups.lastweek) [from, to] = [day(1 - weekday - 7), day(1 - weekday)]
+ else if (groups.thismonth) [from, to] = [new Date(now.getFullYear(), now.getMonth()).getTime(), now.getTime()]
+ else if (groups.lastmonth) [from, to] = [new Date(now.getFullYear(), now.getMonth() - 1).getTime(), new Date(now.getFullYear(), now.getMonth()).getTime()]
+ else if (groups.few) [from, to] = [day(-6), day(-1)]
+ else if (groups.count) {
+ const parsed = Number.parseInt(groups.count, 10)
+ const n = Number.isNaN(parsed) ? NUMBERS[groups.count.toLowerCase()] ?? 1 : parsed
+ const weeks = groups.unit.toLowerCase().startsWith('week')
+ const back = weeks ? n * 7 : n
+ const slack = weeks ? 4 : 1
+ ;[from, to] = [day(-back - slack), day(-back + slack + 1)]
+ } else {
+ const target = WEEKDAYS[groups.weekday.toLowerCase()]
+ let back = (now.getDay() - target + 7) % 7
+ if (back === 0 && groups.last.toLowerCase() === 'last') back = 7
+ ;[from, to] = [day(-back), day(-back + 1)]
+ }
+ to = Math.min(to, now.getTime())
+ const words = `${query.slice(0, match.index)} ${query.slice(match.index + match[0].length)}`.replace(/\s+/g, ' ').trim()
+ return { words, when: { from, to, phrase: match[0] } }
+}
diff --git a/desktop/lib/core/fuzzy_match.dart b/desktop/lib/core/fuzzy_match.dart
index 3a88db441..c74bf1d18 100644
--- a/desktop/lib/core/fuzzy_match.dart
+++ b/desktop/lib/core/fuzzy_match.dart
@@ -1,12 +1,14 @@
/// The spread of a subsequence match, or null when the query does not match.
-/// Both arguments should already be normalized for case.
+/// Both arguments should already be normalized for case. [from] is where in
+/// [text] the match may begin.
int? subsequenceSpread(
String text,
String query, {
+ int from = 0,
void Function(int start, int end)? onMatch,
}) {
if (query.isEmpty) return 0;
- var at = -1;
+ var at = from - 1;
var first = -1;
for (final rune in query.runes) {
final character = String.fromCharCode(rune);
@@ -18,3 +20,134 @@ int? subsequenceSpread(
}
return at - first;
}
+
+final _wordCharacter = RegExp(r'[\p{L}\p{N}]', unicode: true);
+
+/// Whether [index] begins a word: the start of [text], or just after a
+/// character that is neither a letter nor a digit, as in "fix-auth".
+bool startsWord(String text, int index) {
+ if (index <= 0) return true;
+ final unit = text.codeUnitAt(index - 1);
+ if (unit < 0x80) {
+ return !(unit >= 0x30 && unit <= 0x39 ||
+ unit >= 0x41 && unit <= 0x5a ||
+ unit >= 0x61 && unit <= 0x7a);
+ }
+ // Separators every row carries ("·", "…", "—", no-break space) and emoji
+ // halves, without a regex per character.
+ if (unit == 0xa0 ||
+ unit == 0xb7 ||
+ unit >= 0x2000 && unit <= 0x206f ||
+ unit >= 0xd800 && unit <= 0xdfff) {
+ return true;
+ }
+ return !_wordCharacter.hasMatch(text[index - 1]);
+}
+
+/// The first occurrence of [term] at or after [start] that begins a word, or
+/// -1: "port" is a word in "windows port" and only a fragment of "support".
+int wordStartIndexOf(String text, String term, [int start = 0]) {
+ if (term.isEmpty) return start.clamp(0, text.length);
+ for (
+ var at = text.indexOf(term, start);
+ at >= 0;
+ at = text.indexOf(term, at + 1)
+ ) {
+ if (startsWord(text, at)) return at;
+ }
+ return -1;
+}
+
+/// A scattered-letter match that starts on a word and stays close together:
+/// "ath" finds "fix authentication" and "cmd" finds "command", but "auth" no
+/// longer finds every folder under ".../autonomous-harness/...". Returns the
+/// tightest such spread, or null; [onMatch] receives the letters it used.
+int? wordSubsequenceSpread(
+ String text,
+ String query, {
+ void Function(int start, int end)? onMatch,
+}) {
+ if (query.isEmpty) return 0;
+ final letters = _lettersOf(query);
+ // Two scattered letters match nearly everything ("hn" in every "harness"):
+ // they count only as initials, each starting a word ("ns" for New Split).
+ if (letters.length < 3) return _initials(text, letters, onMatch: onMatch);
+ final first = letters.first;
+ final limit = query.length * 2;
+ int? bestStart, bestSpread;
+ for (
+ var at = text.indexOf(first);
+ at >= 0;
+ at = text.indexOf(first, at + first.length)
+ ) {
+ if (!startsWord(text, at)) continue;
+ final spread = _spreadWithin(text, letters, at, limit);
+ // A later start sees less of the text, so it cannot match either.
+ if (spread == _absent) break;
+ if (spread != null && (bestSpread == null || spread < bestSpread)) {
+ bestStart = at;
+ bestSpread = spread;
+ if (spread == query.length - 1) break;
+ }
+ }
+ if (bestStart != null && onMatch != null) {
+ subsequenceSpread(text, query, from: bestStart, onMatch: onMatch);
+ }
+ return bestSpread;
+}
+
+/// No subsequence at all from here on.
+const _absent = -1;
+
+/// The spread of [query] as a subsequence of [text] starting at [start],
+/// giving up as soon as it passes [limit] (null) rather than scanning on to the
+/// end of a long field; [_absent] when a letter never occurs again.
+int? _spreadWithin(String text, List<String> letters, int start, int limit) {
+ var at = start;
+ for (var index = 1; index < letters.length; index++) {
+ final found = text.indexOf(letters[index], at + 1);
+ if (found < 0) return _absent;
+ if (found - start > limit) return null;
+ at = found;
+ }
+ return at - start;
+}
+
+/// A query's letters, as strings: worked out once per query, not once per
+/// field of every row it is matched against.
+List<String> _lettersOf(String query) {
+ if (identical(query, _lettersQuery) || query == _lettersQuery) {
+ return _letters;
+ }
+ _lettersQuery = query;
+ return _letters = [for (final rune in query.runes) String.fromCharCode(rune)];
+}
+
+String? _lettersQuery;
+List<String> _letters = const [];
+
+int? _initials(
+ String text,
+ List<String> letters, {
+ void Function(int start, int end)? onMatch,
+}) {
+ var at = -1;
+ var first = -1;
+ final found = <(int, int)>[];
+ for (final character in letters) {
+ var next = text.indexOf(character, at + 1);
+ while (next >= 0 && !startsWord(text, next)) {
+ next = text.indexOf(character, next + 1);
+ }
+ if (next < 0) return null;
+ if (first < 0) first = next;
+ at = next;
+ found.add((next, next + character.length));
+ }
+ if (onMatch != null) {
+ for (final (start, end) in found) {
+ onMatch(start, end);
+ }
+ }
+ return at - first;
+}
diff --git a/desktop/lib/e2ee/envelope.dart b/desktop/lib/e2ee/envelope.dart
index 9bccf36ca..b2f003c21 100644
--- a/desktop/lib/e2ee/envelope.dart
+++ b/desktop/lib/e2ee/envelope.dart
@@ -47,6 +47,8 @@ const Set<String> encryptedDownTypes = {
'usage_read',
// The pane colours this client paints with, for the machine's tmux sessions (cli/src/lib/hostTheme.ts).
'theme_set',
+ // What somebody searches their conversations for (cli/src/lib/sessionSearch/).
+ 'session_search',
'device_e2ee_pair',
'e2ee_pairings_list',
'e2ee_pairing_unpair',
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index b4b2024f9..ebeb2bafe 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -69,6 +69,8 @@ import '../ws/ws_pool.dart';
import 'pane_preset.dart';
import 'pane_arrangement.dart';
import 'pending_question.dart';
+import 'search_when.dart';
+import 'session_content_search.dart';
import 'session_preview.dart';
import '../usage/models_menu_controller.dart';
import '../usage/remote_usage.dart';
@@ -6976,6 +6978,46 @@ class AppNotifier extends ChangeNotifier {
return localHostnameOrNull();
}
+ /// Machines whose daemon can be asked what was said in their sessions now.
+ Iterable<String> get searchableMachineIds => [
+ for (final machine in machineStates.values)
+ if (machine.connectionStatus == ConnectionStatus.connected &&
+ !machine.needsLink &&
+ machine.nodeOnline != false)
+ machine.machine.machineId,
+ ];
+
+ /// Every turn of every session on [machineId], searched by its daemon
+ /// (`session_search`, cli/src/lib/sessionSearch/). Null when the machine
+ /// cannot answer: offline, or a CLI that predates the request, which goes
+ /// silent rather than refusing it — hence the short timeout.
+ Future<List<SessionContentHit>?> searchSessions(
+ String machineId,
+ String query, {
+ SearchWhen? when,
+ int limit = 30,
+ }) async {
+ if (!searchableMachineIds.contains(machineId)) return null;
+ try {
+ final reply = await _conn(machineId).request(
+ 'session_search',
+ payload: {
+ 'query': query,
+ 'limit': limit,
+ if (when != null) ...{
+ 'from': when.from.millisecondsSinceEpoch,
+ 'to': when.to.millisecondsSinceEpoch,
+ },
+ },
+ timeout: const Duration(seconds: 4),
+ );
+ if (reply['error'] != null) return null;
+ return SessionContentHit.listFromReply(machineId, reply);
+ } catch (_) {
+ return null;
+ }
+ }
+
Future<MachineUsage?> _readMachineUsage(MachineState machine) async {
try {
final reply = await _conn(machine.machine.machineId)
diff --git a/desktop/lib/state/search_when.dart b/desktop/lib/state/search_when.dart
new file mode 100644
index 000000000..70b06f68b
--- /dev/null
+++ b/desktop/lib/state/search_when.dart
@@ -0,0 +1,99 @@
+/// When a search is about, read from its words: "dial last week", "yesterday",
+/// "3 days ago", "on monday". People remember a session by roughly when as
+/// often as by what; the phrase narrows the search to sessions worked on then
+/// and is taken out of the words matched against names and conversations.
+///
+/// Parsed here rather than by each machine so every machine searches the same
+/// window, in this computer's time zone.
+typedef SearchWhen = ({DateTime from, DateTime to, String phrase});
+
+const _numbers = {
+ 'a': 1,
+ 'an': 1,
+ 'one': 1,
+ 'two': 2,
+ 'three': 3,
+ 'four': 4,
+ 'five': 5,
+ 'six': 6,
+ 'seven': 7,
+ 'eight': 8,
+ 'nine': 9,
+ 'ten': 10,
+};
+
+const _weekdays = {
+ 'monday': DateTime.monday,
+ 'tuesday': DateTime.tuesday,
+ 'wednesday': DateTime.wednesday,
+ 'thursday': DateTime.thursday,
+ 'friday': DateTime.friday,
+ 'saturday': DateTime.saturday,
+ 'sunday': DateTime.sunday,
+};
+
+final _phrases = RegExp(
+ r'(?<![\p{L}\p{N}])(?:'
+ r'(?<today>today)'
+ r'|(?<yesterday>yesterday)'
+ r'|(?<thisweek>this week)'
+ r'|(?<lastweek>last week)'
+ r'|(?<thismonth>this month)'
+ r'|(?<lastmonth>last month)'
+ r'|(?<few>(?:a )?few days ago|(?:a )?couple(?: of)? days ago)'
+ r'|(?<count>\d{1,2}|a|an|one|two|three|four|five|six|seven|eight|nine|ten) (?<unit>days?|weeks?) ago'
+ // A weekday only with "on" or "last": "friday deploy" is a harness's name,
+ // "on friday" is a time.
+ r'|(?<last>last|on) (?<weekday>monday|tuesday|wednesday|thursday|friday|saturday|sunday)'
+ r')(?![\p{L}\p{N}])',
+ caseSensitive: false,
+ unicode: true,
+);
+
+/// The words with any time phrase taken out, and the window it names.
+({String words, SearchWhen? when}) parseSearchWhen(String query, DateTime now) {
+ final match = _phrases.firstMatch(query);
+ if (match == null) return (words: query, when: null);
+ final midnight = DateTime(now.year, now.month, now.day);
+ DateTime day(int offset) =>
+ DateTime(midnight.year, midnight.month, midnight.day + offset);
+ late DateTime from, to;
+ if (match.namedGroup('today') != null) {
+ (from, to) = (midnight, now);
+ } else if (match.namedGroup('yesterday') != null) {
+ (from, to) = (day(-1), midnight);
+ } else if (match.namedGroup('thisweek') != null) {
+ (from, to) = (day(1 - now.weekday), now);
+ } else if (match.namedGroup('lastweek') != null) {
+ (from, to) = (day(1 - now.weekday - 7), day(1 - now.weekday));
+ } else if (match.namedGroup('thismonth') != null) {
+ (from, to) = (DateTime(now.year, now.month), now);
+ } else if (match.namedGroup('lastmonth') != null) {
+ (from, to) = (
+ DateTime(now.year, now.month - 1),
+ DateTime(now.year, now.month),
+ );
+ } else if (match.namedGroup('few') != null) {
+ // Two to five days back, loosely.
+ (from, to) = (day(-6), day(-1));
+ } else if (match.namedGroup('count') case final count?) {
+ final n = int.tryParse(count) ?? _numbers[count.toLowerCase()] ?? 1;
+ final weeks = match.namedGroup('unit')!.toLowerCase().startsWith('week');
+ // Memory is loose: a day either side, or half a week either side.
+ final back = weeks ? n * 7 : n;
+ final slack = weeks ? 4 : 1;
+ (from, to) = (day(-back - slack), day(-back + slack + 1));
+ } else {
+ final weekday = _weekdays[match.namedGroup('weekday')!.toLowerCase()]!;
+ final strictlyBefore = match.namedGroup('last')!.toLowerCase() == 'last';
+ var back = (now.weekday - weekday) % 7;
+ if (back == 0 && strictlyBefore) back = 7;
+ (from, to) = (day(-back), day(-back + 1));
+ }
+ if (to.isAfter(now)) to = now;
+ final words = query
+ .replaceRange(match.start, match.end, ' ')
+ .replaceAll(RegExp(r'\s+'), ' ')
+ .trim();
+ return (words: words, when: (from: from, to: to, phrase: match[0]!));
+}
diff --git a/desktop/lib/state/session_content_search.dart b/desktop/lib/state/session_content_search.dart
new file mode 100644
index 000000000..6682f5a34
--- /dev/null
+++ b/desktop/lib/state/session_content_search.dart
@@ -0,0 +1,283 @@
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+
+import 'search_when.dart';
+import 'swarm_navigation.dart' show agentDestinationId;
+
+/// Where a machine's daemon marks each matched word in a snippet.
+const kSnippetMarkOpen = '\u0002';
+const kSnippetMarkClose = '\u0003';
+
+/// One conversation that matched a search, as its machine's daemon found it
+/// (`session_search`, cli/src/lib/sessionSearch/). The daemon has read every
+/// turn of every session on that machine; the app only ever sees the hits.
+@immutable
+class SessionContentHit {
+ const SessionContentHit({
+ required this.machineId,
+ required this.agentId,
+ required this.sessionId,
+ required this.field,
+ required this.snippet,
+ required this.together,
+ required this.score,
+ this.position = 0,
+ this.turn = 0,
+ this.at,
+ });
+
+ final String machineId, agentId, sessionId;
+
+ /// `ask`, `answer`, `tools` or `name`: which part of the turn matched.
+ final String field;
+
+ /// The words around the match, each matched word between
+ /// [kSnippetMarkOpen] and [kSnippetMarkClose].
+ final String snippet;
+
+ /// Every searched word in one turn, rather than spread across the session.
+ final bool together;
+
+ /// 0–1, higher is better: relevance blended with recency by the daemon.
+ /// Relative to that machine's best hit, so not comparable across machines.
+ final double score;
+
+ /// Where the machine ranked it, from 0. Hits from several machines merge
+ /// by this: each machine's first is as good as another's first.
+ final int position;
+ final int turn;
+
+ /// When the matching turn happened, when the transcript says.
+ final DateTime? at;
+
+ String get destinationId => agentDestinationId(machineId, agentId);
+
+ /// The snippet as plain text, marks removed.
+ String get plainSnippet => snippet
+ .replaceAll(kSnippetMarkOpen, '')
+ .replaceAll(kSnippetMarkClose, '');
+
+ static SessionContentHit? fromJson(
+ String machineId,
+ Object? raw, {
+ int position = 0,
+ }) {
+ if (raw is! Map) return null;
+ final agentId = raw['agentId'];
+ final sessionId = raw['sessionId'];
+ final snippet = raw['snippet'];
+ if (agentId is! String || agentId.isEmpty || sessionId is! String) {
+ return null;
+ }
+ final score = raw['score'];
+ final at = raw['at'];
+ final turn = raw['turn'];
+ return SessionContentHit(
+ machineId: machineId,
+ agentId: agentId,
+ sessionId: sessionId,
+ field: raw['field'] is String ? raw['field'] as String : 'ask',
+ snippet: snippet is String
+ ? snippet.length > 600
+ ? snippet.substring(0, 600)
+ : snippet
+ : '',
+ together: raw['together'] == true,
+ score: score is num ? score.toDouble().clamp(0, 1) : 0,
+ position: position,
+ turn: turn is int ? turn : 0,
+ at: at is int ? DateTime.fromMillisecondsSinceEpoch(at) : null,
+ );
+ }
+
+ /// A `session_search_result` payload, or an empty list for an error.
+ static List<SessionContentHit> listFromReply(
+ String machineId,
+ Map<String, dynamic> reply,
+ ) {
+ final hits = reply['hits'];
+ if (reply['error'] != null || hits is! List) return const [];
+ return [
+ for (final (position, raw) in hits.take(100).indexed)
+ ?SessionContentHit.fromJson(machineId, raw, position: position),
+ ];
+ }
+}
+
+/// Asks one machine for [words], only in sessions worked on in [when] when
+/// there is one.
+typedef SessionSearchAsk = Future<List<SessionContentHit>?> Function(
+ String machineId,
+ String words,
+ SearchWhen? when,
+);
+
+/// Asks every reachable machine what was said in its sessions, as the person
+/// types in Cmd-P. Debounced so a burst of keys is one question; an answer to
+/// an older question is dropped. Hits are keyed by the harness row they belong
+/// to, and a machine that cannot answer (offline, or a CLI that predates
+/// `session_search`) simply adds none.
+class SessionContentSearch extends ChangeNotifier {
+ SessionContentSearch({
+ required this.machines,
+ required this.ask,
+ this.debounce = const Duration(milliseconds: 110),
+ DateTime Function()? now,
+ }) : _now = now ?? DateTime.now;
+
+ /// The machines to ask right now.
+ final Iterable<String> Function() machines;
+ final SessionSearchAsk ask;
+ final Duration debounce;
+ final DateTime Function() _now;
+
+ /// What [query] asks for: its words, and when, if it says.
+ ({String words, SearchWhen? when}) read(String query) =>
+ parseSearchWhen(query.trim(), _now());
+
+ Map<String, SessionContentHit> _hits = const {};
+ Map<String, SessionContentHit> get hits => _hits;
+
+ /// The hits that vouch for [query]. While its own answer is on the way, an
+ /// earlier answer's hit counts only if its snippet shows every word of it:
+ /// a hit found for "mob" says nothing about "mob swipe".
+ Map<String, SessionContentHit> hitsFor(String query) {
+ final wanted = query.trim();
+ if (_answered == null || _hits.isEmpty) return const {};
+ if (_answered == wanted) return _hits;
+ // Read on every row's build: worked out once per query and answer.
+ final cached = _vouched;
+ if (cached != null &&
+ cached.query == wanted &&
+ identical(cached.hits, _hits)) {
+ return cached.vouched;
+ }
+ final vouched = _vouch(wanted);
+ _vouched = (query: wanted, hits: _hits, vouched: vouched);
+ return vouched;
+ }
+
+ ({
+ String query,
+ Map<String, SessionContentHit> hits,
+ Map<String, SessionContentHit> vouched,
+ })?
+ _vouched;
+
+ Map<String, SessionContentHit> _vouch(String wanted) {
+ // A hit found for another time says nothing about this one. Compared by
+ // the phrase: "today" ends now, and now moves on every read.
+ final now = read(wanted), then = read(_answered!);
+ if (now.when?.phrase.toLowerCase() != then.when?.phrase.toLowerCase()) {
+ return const {};
+ }
+ final words = now.words
+ .toLowerCase()
+ .split(RegExp(r'\s+'))
+ .where((word) => word.isNotEmpty)
+ .toList();
+ return {
+ for (final entry in _hits.entries)
+ if (_shows(entry.value.plainSnippet.toLowerCase(), words))
+ entry.key: entry.value,
+ };
+ }
+
+ static final _wordStart = RegExp(r'[^\p{L}\p{N}]', unicode: true);
+
+ static bool _shows(String text, List<String> words) => words.every((word) {
+ for (
+ var at = text.indexOf(word);
+ at >= 0;
+ at = text.indexOf(word, at + 1)
+ ) {
+ if (at == 0 || _wordStart.hasMatch(text[at - 1])) return true;
+ }
+ return false;
+ });
+
+ /// The query the current [hits] answer, or null while none have arrived.
+ String? get answered => _answered;
+ String? _answered;
+
+ String _query = '';
+ int _generation = 0;
+ Timer? _timer;
+ bool _disposed = false;
+
+ /// Two letters at least: one matches too much of everything to mean anything.
+ /// A time on its own ("yesterday") is a search too: what was worked on then.
+ bool searchable(String query) {
+ final read = this.read(query);
+ return read.when != null || read.words.runes.length >= 2;
+ }
+
+ void search(String query) {
+ final next = query.trim();
+ if (next == _query) return;
+ final previous = _query;
+ _query = next;
+ _timer?.cancel();
+ final generation = ++_generation;
+ // Typing more of the same words keeps the last answer on screen until the
+ // new one lands; anything else would show rows for words no longer typed.
+ if (!next.toLowerCase().startsWith(previous.toLowerCase()) ||
+ !searchable(next)) {
+ if (_hits.isNotEmpty || _answered != null) {
+ _hits = const {};
+ _answered = null;
+ notifyListeners();
+ }
+ }
+ // Nothing to ask while every machine is offline: no timer, no work.
+ if (!searchable(next) || machines().isEmpty) return;
+ final read = this.read(next);
+ _timer = Timer(
+ debounce,
+ () => _run(next, read.words, read.when, generation),
+ );
+ }
+
+ Future<void> _run(
+ String query,
+ String words,
+ SearchWhen? when,
+ int generation,
+ ) async {
+ final found = <String, SessionContentHit>{};
+ var first = true;
+ await Future.wait([
+ for (final machineId in machines())
+ ask(machineId, words, when).then((hits) {
+ if (_disposed || generation != _generation) return;
+ if (first) {
+ // The first answer replaces what an earlier question found.
+ first = false;
+ _hits = const {};
+ }
+ for (final hit in hits ?? const <SessionContentHit>[]) {
+ final id = hit.destinationId;
+ final known = found[id];
+ // One row per harness: its best conversation, earlier ones included.
+ if (known == null ||
+ (hit.together && !known.together) ||
+ (hit.together == known.together &&
+ hit.position < known.position)) {
+ found[id] = hit;
+ }
+ }
+ _hits = Map.unmodifiable(found);
+ _answered = query;
+ notifyListeners();
+ }, onError: (_) {}),
+ ]);
+ }
+
+ @override
+ void dispose() {
+ _disposed = true;
+ _timer?.cancel();
+ super.dispose();
+ }
+}
diff --git a/desktop/lib/state/swarm_navigation.dart b/desktop/lib/state/swarm_navigation.dart
index 7252d4b4c..4145875c3 100644
--- a/desktop/lib/state/swarm_navigation.dart
+++ b/desktop/lib/state/swarm_navigation.dart
@@ -13,6 +13,7 @@ import '../widgets/engine_identity.dart';
import 'app_state.dart';
import 'harness_placement.dart';
import 'pane_arrangement.dart';
+import 'session_content_search.dart';
import 'session_preview.dart';
import 'swarm.dart';
import 'swarm_catalog.dart';
@@ -704,32 +705,52 @@ class SwarmLocationCatalog {
}
}
-/// Open Harness uses the same activity timestamp it shows beside each session.
+/// Open Harness uses the same activity timestamp it shows beside each session,
+/// within each [SwarmMatchStrength]: typing "hn" puts the harness named hn
+/// first, however many newer ones live in a folder whose path spells h…n.
/// Undated rows come last; ties retain visit recency and search relevance.
List<SwarmDestination> rankSwarmDestinationsByActivity(
List<SwarmDestination> all,
String query, {
List<String> recent = const [],
SessionPreviewStore? previews,
+ Map<String, SessionContentHit>? contentHits,
}) {
- final matches = rankSwarmDestinations(all, query, previews: previews);
- final rank = {for (var i = 0; i < matches.length; i++) matches[i].id: i};
+ final matches = _matchSwarmDestinations(
+ all,
+ query,
+ previews,
+ contentHits: contentHits,
+ );
final visits = {for (var i = 0; i < recent.length; i++) recent[i]: i};
matches.sort((a, b) {
- final aTime = a.lastActivityAt;
- final bTime = b.lastActivityAt;
+ final strength = a.strength.index.compareTo(b.strength.index);
+ if (strength != 0) return strength;
+ // What was said is ranked by the index, which weighs how well it matched
+ // against how long ago; activity decides between equal answers.
+ if (a.strength == SwarmMatchStrength.said ||
+ a.strength == SwarmMatchStrength.content) {
+ final said = b.said.compareTo(a.said);
+ if (said != 0) return said;
+ }
+ final aTime = a.entry.lastActivityAt;
+ final bTime = b.entry.lastActivityAt;
final activity = aTime == null
? (bTime == null ? 0 : 1)
: bTime == null
? -1
: bTime.compareTo(aTime);
if (activity != 0) return activity;
- final visit = (visits[a.id] ?? recent.length).compareTo(
- visits[b.id] ?? recent.length,
+ final visit = (visits[a.entry.id] ?? recent.length).compareTo(
+ visits[b.entry.id] ?? recent.length,
);
- return visit != 0 ? visit : rank[a.id]!.compareTo(rank[b.id]!);
+ if (visit != 0) return visit;
+ final score = a.score.compareTo(b.score);
+ if (score != 0) return score;
+ final name = compareNatural(a.entry.fields.first, b.entry.fields.first);
+ return name != 0 ? name : a.entry.id.compareTo(b.entry.id);
});
- return matches;
+ return [for (final match in matches) match.entry];
}
/// Each swarm is one selectable parent, followed by its matching agent views.
@@ -1288,42 +1309,122 @@ List<String> swarmQueryTerms(String query) {
/// The same field preference drives ranking and the visible match emphasis.
/// A good metadata match should not paint unrelated fuzzy title characters.
-int? swarmFieldMatchScore(String field, String term, {required bool title}) {
+/// Whole words beat fragments: "port" is exact in "port", a prefix of
+/// "port audit", a word of "windows port" and only a fragment of "support".
+/// Scattered letters must start a word and stay close together; loose, they
+/// matched nearly any folder ("auth" in ".../autonomous-harness/...").
+///
+/// [strict] is for harness rows: hundreds of names and long folder paths, where
+/// loose letters match nearly anything, so scattered letters must start a word
+/// and stay close, and two letters count only as initials. Commands, machines,
+/// projects and models are short curated lists that keep any scattered
+/// letters, so abbreviations like "kb" and "mbp" still work.
+int? swarmFieldMatchScore(
+ String field,
+ String term, {
+ required bool title,
+ bool strict = false,
+}) {
final offset = field.indexOf(term);
- final spread = offset >= 0 ? 0 : subsequenceSpread(field, term);
- if (spread == null) return null;
- return (title ? 0 : 64) +
- (field == term
- ? 0
- : offset == 0
- ? 8
- : offset > 0
- ? 16
- : 128 + spread);
+ final int score;
+ if (offset == 0) {
+ score = field.length == term.length ? 0 : 8;
+ } else if (offset > 0) {
+ score = wordStartIndexOf(field, term, offset) >= 0 ? 12 : 16;
+ } else {
+ final spread = strict
+ ? wordSubsequenceSpread(field, term)
+ : subsequenceSpread(field, term);
+ if (spread == null) return null;
+ score = 128 + spread;
+ }
+ return (title ? 0 : 64) + score;
+}
+
+/// How well a row matched, coarsest first. Harnesses order by activity only
+/// among equally good matches, so the one named for a word is never buried
+/// under newer ones that mention it in a folder or a recap.
+enum SwarmMatchStrength {
+ /// The whole query is the name.
+ exact,
+
+ /// Every word starts a word of the name or title.
+ name,
+
+ /// A fragment of the name, or a whole word of the project, branch or machine.
+ context,
+
+ /// A fragment of the project, branch, folder or machine.
+ fragment,
+
+ /// Every word in one turn of the conversation — asked, answered, or a file
+ /// or command it touched — as the machine's session index found it.
+ said,
+
+ /// The words appear in the conversation, but not together.
+ content,
+
+ /// Scattered letters of the name or its context: real words anywhere in
+ /// the conversation are better evidence than letters strewn across a name.
+ scattered;
+
+ static SwarmMatchStrength ofScore(int score) => score <= 12
+ ? name
+ : score <= 76
+ ? context
+ : score < 128
+ ? fragment
+ : scattered;
}
+typedef _SwarmMatch = ({
+ SwarmDestination entry,
+ int score,
+ SwarmMatchStrength strength,
+
+ /// How the session index ranked this row among its machine's hits, as a
+ /// reciprocal rank (higher is better), when it found it.
+ double said,
+});
+
/// Each word may match a different field, in either order: "mini auth" and
-/// "auth mini" both find Auth on Mac mini. Names outrank incidental metadata.
-/// Existing preview text is a fallback, with literal word fragments rather
-/// than scattered-letter matches across long paragraphs. Reading it never
-/// warms the cache or contacts a machine.
-List<SwarmDestination> rankSwarmDestinations(
+/// "auth mini" both find Auth on Mac mini. Existing preview text is the last
+/// resort, matched at word starts so "port" does not find every "support".
+/// Reading it never warms the cache or contacts a machine.
+///
+/// [contentHits] are what the machines' session indexes found for this query,
+/// by row id: everything ever said in each session, not only the recent
+/// excerpt the preview holds. A hit vouches for every word, so it admits a
+/// row the fields alone cannot, and lifts one that only scattered letters
+/// matched.
+List<_SwarmMatch> _matchSwarmDestinations(
List<SwarmDestination> all,
- String query, {
- List<String> recent = const [],
- SessionPreviewStore? previews,
+ String query,
+ SessionPreviewStore? previews, {
+ Map<String, SessionContentHit>? contentHits,
}) {
final needle = query.trim().toLowerCase();
final terms = swarmQueryTerms(query);
- final recency = {for (var i = 0; i < recent.length; i++) recent[i]: i};
- final ranked = <({SwarmDestination entry, int score, bool content})>[];
+ final matches = <_SwarmMatch>[];
for (final entry in all) {
- if (entry.fields.take(entry.titleFieldCount).contains(needle)) {
- ranked.add((entry: entry, score: -1, content: false));
+ if (needle.isNotEmpty &&
+ entry.fields.take(entry.titleFieldCount).contains(needle)) {
+ matches.add((
+ entry: entry,
+ score: -1,
+ strength: SwarmMatchStrength.exact,
+ said: 0,
+ ));
continue;
}
+ final hit = terms.isEmpty ? null : contentHits?[entry.id];
+ final hitStrength = hit == null
+ ? null
+ : hit.together
+ ? SwarmMatchStrength.said
+ : SwarmMatchStrength.content;
var total = 0;
- var content = false;
+ var strength = SwarmMatchStrength.name;
String? excerpt;
for (final term in terms) {
int? best;
@@ -1333,31 +1434,61 @@ List<SwarmDestination> rankSwarmDestinations(
field,
term,
title: i < entry.titleFieldCount,
+ strict: entry.agentId != null,
);
if (score == null) continue;
if (best == null || score < best) best = score;
// Every remaining field is metadata, whose best possible score is 64.
- // An exact/prefix/substring title match already beats that; an exact
+ // A whole-word or fragment title match already beats that; an exact
// metadata match ties it. Neither needs further field scans.
if (best <= 64) break;
}
+ final SwarmMatchStrength termStrength;
if (best == null) {
excerpt ??= entry.previewKey == null
? ''
: previews?.read(entry.previewKey!)?.searchText ?? '';
- if (!excerpt.contains(term)) {
+ if (wordStartIndexOf(excerpt, term) < 0) {
total = -1;
break;
}
- content = true;
+ termStrength = SwarmMatchStrength.content;
best = 256;
+ } else {
+ termStrength = SwarmMatchStrength.ofScore(best);
}
+ if (termStrength.index > strength.index) strength = termStrength;
total += best;
}
+ if (hitStrength != null &&
+ (total < 0 || hitStrength.index < strength.index)) {
+ strength = hitStrength;
+ if (total < 0) total = 256 * terms.length;
+ }
if (total >= 0) {
- ranked.add((entry: entry, score: total, content: content));
+ matches.add((
+ entry: entry,
+ score: total,
+ strength: strength,
+ // Reciprocal rank: each machine's session index ranks its own hits, and
+ // a machine's first is as good as another's first.
+ said: hit == null ? 0 : 1 / (1 + hit.position),
+ ));
}
}
+ return matches;
+}
+
+/// Names outrank incidental metadata, and metadata outranks preview text.
+List<SwarmDestination> rankSwarmDestinations(
+ List<SwarmDestination> all,
+ String query, {
+ List<String> recent = const [],
+ SessionPreviewStore? previews,
+}) {
+ final needle = query.trim().toLowerCase();
+ final recency = {for (var i = 0; i < recent.length; i++) recent[i]: i};
+ final ranked = _matchSwarmDestinations(all, query, previews);
int tier(SwarmDestination e) => !e.hasView
? 3
: e.current
@@ -1365,8 +1496,11 @@ List<SwarmDestination> rankSwarmDestinations(
: recency.containsKey(e.id)
? 0
: 1;
+ bool content(_SwarmMatch match) =>
+ match.strength == SwarmMatchStrength.content ||
+ match.strength == SwarmMatchStrength.said;
ranked.sort((a, b) {
- var order = (a.content ? 1 : 0).compareTo(b.content ? 1 : 0);
+ var order = (content(a) ? 1 : 0).compareTo(content(b) ? 1 : 0);
if (order == 0) order = a.score.compareTo(b.score);
if (order == 0 && needle.isEmpty) {
order = tier(a.entry).compareTo(tier(b.entry));
diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
index 26c44c4c2..56c7275c1 100644
--- a/desktop/lib/state/swarm_search.dart
+++ b/desktop/lib/state/swarm_search.dart
@@ -14,6 +14,8 @@ import 'pane_arrangement.dart';
import 'swarm_catalog.dart';
import 'swarm_navigation.dart';
import 'harness_sessions.dart';
+import 'search_when.dart';
+import 'session_content_search.dart';
const kSwarmSearchHint = 'Search harnesses';
const kHarnessPickerHint = kSwarmSearchHint;
@@ -71,6 +73,13 @@ class SwarmSearchController extends ChangeNotifier {
_locations = locations ?? SwarmLocationCatalog(),
targetId = app.activeSwarmId,
targetName = app.activeSwarm.name {
+ if (activityFirst && history == null && !navigating) {
+ _content = SessionContentSearch(
+ machines: () => app.searchableMachineIds,
+ ask: (machineId, words, when) =>
+ app.searchSessions(machineId, words, when: when),
+ )..addListener(_contentChanged);
+ }
_refresh();
app.addListener(_refresh);
projects?.addListener(_refresh);
@@ -395,6 +404,53 @@ class SwarmSearchController extends ChangeNotifier {
}
final bool commandsOnly;
+
+ /// Open Harness also asks every machine's session index what was said in
+ /// each conversation; its hits join the ranking as they arrive.
+ SessionContentSearch? _content;
+
+ /// Whether somebody moved through the results since the query changed:
+ /// until then, rows arriving from a machine keep the best one selected.
+ bool _chosen = false;
+
+ /// The query the machines' session indexes last answered, or null before
+ /// any answer: whether what was said has been searched yet.
+ String? get contentAnswered => _content?.answered;
+
+ /// What a machine's session index found in this row's conversation for the
+ /// current query, when that is how the row matched.
+ SessionContentHit? contentHitFor(String rowId) =>
+ _contentQuery.isEmpty ? null : _content?.hitsFor(_contentQuery)[rowId];
+
+ /// When the query says to look ("dial last week"), and its words without
+ /// that: Open Harness only, where a time narrows to what was worked on then.
+ ({String words, SearchWhen? when}) get _read {
+ final content = _content;
+ final query = _contentQuery;
+ return content == null || query.isEmpty
+ ? (words: matchQuery, when: null)
+ : content.read(query);
+ }
+
+ /// The words matched against names and highlighted: the query less any time.
+ String get wordsQuery => _read.words;
+
+ /// The words sent to the session indexes: plain harness search only.
+ String get _contentQuery =>
+ isCommandMode || isHelpMode || isGroupMode || isModelMode || isStoreMode
+ ? ''
+ : matchQuery;
+
+ void _contentChanged() {
+ if (_disposed) return;
+ if (!_chosen) {
+ cursor = 0;
+ _selectedId = null;
+ }
+ _filter();
+ notifyListeners();
+ }
+
SessionFilter sessionFilter = SessionFilter.all;
SessionSort sessionSort = SessionSort.recent;
final machineResources = <String, MachineResources>{};
@@ -536,6 +592,7 @@ class SwarmSearchController extends ChangeNotifier {
cursor = 0;
_selectedId = null;
_filter();
+ _content?.search(_contentQuery);
notifyListeners();
return true;
}
@@ -659,6 +716,7 @@ class SwarmSearchController extends ChangeNotifier {
_selectedId = draft.selectedId;
cursor = 0;
_filter();
+ _content?.search(_contentQuery);
notifyListeners();
}
@@ -899,6 +957,20 @@ class SwarmSearchController extends ChangeNotifier {
notifyListeners();
}
+ /// With a time in the query, the rows worked on then: last active in it, or
+ /// vouched for by a machine that saw a turn in it.
+ List<SwarmDestination> _within(List<SwarmDestination> rows) {
+ final when = _read.when;
+ if (when == null) return rows;
+ final hits = _content?.hitsFor(_contentQuery) ?? const {};
+ bool then(DateTime? at) =>
+ at != null && !at.isBefore(when.from) && !at.isAfter(when.to);
+ return [
+ for (final row in rows)
+ if (hits.containsKey(row.id) || then(row.lastActivityAt)) row,
+ ];
+ }
+
void refreshCommands() {
if (!isCommandMode) return;
_filter();
@@ -1107,10 +1179,13 @@ class SwarmSearchController extends ChangeNotifier {
)
: byActivity
? rankSwarmDestinationsByActivity(
- candidates,
- matchQuery,
+ _within(candidates),
+ wordsQuery,
recent: recent,
previews: app.sessionPreviews,
+ contentHits: _contentQuery.isEmpty
+ ? null
+ : _content?.hitsFor(_contentQuery),
)
: rankSwarmDestinations(
candidates,
@@ -1321,7 +1396,9 @@ class SwarmSearchController extends ChangeNotifier {
if (isStoreMode) _refreshStore();
cursor = 0;
_selectedId = null;
+ _chosen = false;
_filter();
+ _content?.search(_contentQuery);
notifyListeners();
}
@@ -1338,6 +1415,7 @@ class SwarmSearchController extends ChangeNotifier {
if (rows.isEmpty) return;
cursor = ((cursor < 0 && delta < 0 ? 0 : cursor) + delta) % rows.length;
_selectedId = selected!.id;
+ _chosen = true;
notifyListeners();
}
@@ -1511,6 +1589,8 @@ class SwarmSearchController extends ChangeNotifier {
@override
void dispose() {
_disposed = true;
+ _content?.removeListener(_contentChanged);
+ _content?.dispose();
_modelUseTimer?.cancel();
if (_modelUseWait?.isCompleted == false) _modelUseWait!.complete();
app.removeListener(_refresh);
diff --git a/desktop/lib/widgets/agent_picker.dart b/desktop/lib/widgets/agent_picker.dart
index 998fd6fe0..9bd1c7f7e 100644
--- a/desktop/lib/widgets/agent_picker.dart
+++ b/desktop/lib/widgets/agent_picker.dart
@@ -761,7 +761,7 @@ class _AgentPickerState extends State<AgentPicker> {
if (needle.isEmpty || text == null) return const [];
final field = text.toLowerCase();
return field.contains(needle)
- ? [(field: field, term: needle, title: title)]
+ ? [(field: field, term: needle, title: title, strict: false)]
: const [];
}
diff --git a/desktop/lib/widgets/search_result_text.dart b/desktop/lib/widgets/search_result_text.dart
index 09f370da0..159dfca8c 100644
--- a/desktop/lib/widgets/search_result_text.dart
+++ b/desktop/lib/widgets/search_result_text.dart
@@ -1,9 +1,17 @@
import 'package:flutter/widgets.dart';
import '../core/fuzzy_match.dart';
+import '../state/session_content_search.dart';
import '../state/swarm_navigation.dart';
-typedef SearchFieldMatch = ({String field, String term, bool title});
+/// [strict]: the field was matched by [swarmFieldMatchScore]'s rules for
+/// harness rows, so scattered letters are emphasised the way they matched.
+typedef SearchFieldMatch = ({
+ String field,
+ String term,
+ bool title,
+ bool strict,
+});
/// Match only the field that earns each query term's ranking score. Work is
/// bounded to visible rows; discovery and ranking retain their existing path.
@@ -19,7 +27,12 @@ List<SearchFieldMatch> searchResultMatches(
for (var i = 0; i < row.fields.length; i++) {
final field = row.fields[i];
if (field.length > 4096) continue;
- final score = swarmFieldMatchScore(field, term, title: i == 0);
+ final score = swarmFieldMatchScore(
+ field,
+ term,
+ title: i < row.titleFieldCount,
+ strict: row.agentId != null,
+ );
if (score != null && (best == null || score < best)) {
best = score;
fieldIndex = i;
@@ -31,6 +44,7 @@ List<SearchFieldMatch> searchResultMatches(
field: row.fields[fieldIndex],
term: term,
title: fieldIndex == 0,
+ strict: row.agentId != null,
));
}
}
@@ -79,12 +93,11 @@ List<SearchTextRun> searchTextRuns(
));
} else {
final fuzzy = <({int start, int end})>[];
- if (subsequenceSpread(
- match.field,
- match.term,
- onMatch: (start, end) =>
- fuzzy.add((start: fieldAt + start, end: fieldAt + end)),
- ) !=
+ void onMatch(int start, int end) =>
+ fuzzy.add((start: fieldAt + start, end: fieldAt + end));
+ if ((match.strict
+ ? wordSubsequenceSpread(match.field, match.term, onMatch: onMatch)
+ : subsequenceSpread(match.field, match.term, onMatch: onMatch)) !=
null) {
positions.addAll(fuzzy);
}
@@ -185,3 +198,67 @@ class SearchResultText extends StatelessWidget {
);
}
}
+
+/// Where a session index found the words: what was asked reads like a
+/// prompt, a command like a shell line, and the agent's answer plainly.
+String snippetLead(String field) => switch (field) {
+ 'ask' => '> ',
+ 'tools' => r'$ ',
+ _ => '',
+};
+
+/// A session index snippet with its matched words in bold, one line.
+List<SearchTextRun> snippetRuns(String snippet) {
+ final runs = <SearchTextRun>[];
+ var rest = snippet;
+ while (rest.isNotEmpty) {
+ final open = rest.indexOf(kSnippetMarkOpen);
+ if (open < 0) {
+ runs.add((text: rest, matched: false));
+ break;
+ }
+ if (open > 0) runs.add((text: rest.substring(0, open), matched: false));
+ final close = rest.indexOf(kSnippetMarkClose, open + 1);
+ final end = close < 0 ? rest.length : close;
+ if (end > open + 1) {
+ runs.add((text: rest.substring(open + 1, end), matched: true));
+ }
+ rest = close < 0 ? '' : rest.substring(close + 1);
+ }
+ return runs;
+}
+
+class SessionSnippetText extends StatelessWidget {
+ const SessionSnippetText(
+ this.hit, {
+ super.key,
+ required this.style,
+ this.maxLines = 1,
+ });
+
+ final SessionContentHit hit;
+ final TextStyle style;
+
+ /// One line in a result row; null lets the preview show all of it.
+ final int? maxLines;
+
+ @override
+ Widget build(BuildContext context) => Text.rich(
+ TextSpan(
+ children: [
+ TextSpan(text: snippetLead(hit.field)),
+ for (final run in snippetRuns(hit.snippet))
+ TextSpan(
+ text: run.text,
+ style: run.matched
+ ? const TextStyle(fontWeight: FontWeight.w700)
+ : null,
+ ),
+ ],
+ ),
+ key: key == null ? ValueKey('session-snippet:${hit.destinationId}') : null,
+ maxLines: maxLines,
+ overflow: maxLines == null ? null : TextOverflow.ellipsis,
+ style: style,
+ );
+}
diff --git a/desktop/lib/widgets/swarm_search_preview.dart b/desktop/lib/widgets/swarm_search_preview.dart
index aeed3024b..7e82c06be 100644
--- a/desktop/lib/widgets/swarm_search_preview.dart
+++ b/desktop/lib/widgets/swarm_search_preview.dart
@@ -11,12 +11,14 @@ import '../shared/theme/app_type.dart';
import '../shared/theme/status_line_style.dart';
import '../state/app_state.dart';
import '../state/harness_sessions.dart';
+import '../state/session_content_search.dart';
import '../state/swarm_navigation.dart';
import '../state/swarm_search.dart';
import '../terminal/terminal_theme.dart';
import '../terminal/terminal_theme_store.dart';
import 'box_chrome.dart';
import 'engine_identity.dart';
+import 'search_result_text.dart' show SessionSnippetText;
import 'swarm_preview_scroll.dart';
typedef _PreviewAgent = ({MachineState machine, Agent agent});
@@ -68,6 +70,7 @@ class SwarmSearchPreview extends StatefulWidget {
class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
Timer? _warm;
String? _selectedId;
+ SessionContentHit? _found;
late SwarmPreviewScrollController _scroll;
AppNotifier get app => widget.search.app;
@@ -100,6 +103,9 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
void _changed() {
final row = widget.search.selected;
+ // A machine's answer can land after the selection: show where it found it.
+ final found = row == null ? null : widget.search.contentHitFor(row.id);
+ if (!identical(found, _found)) setState(() => _found = found);
if (_selectedId == row?.id) return;
_selectedId = row?.id;
setState(() {});
@@ -278,6 +284,7 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
item: agents.single,
dense: widget.compactHeader,
terminal: widget.terminal,
+ found: widget.search.contentHitFor(row.id),
),
),
),
@@ -301,6 +308,7 @@ class _AgentPreview extends StatelessWidget {
this.compact = false,
this.dense = false,
this.terminal = false,
+ this.found,
});
final AppNotifier app;
final _PreviewAgent item;
@@ -308,6 +316,10 @@ class _AgentPreview extends StatelessWidget {
final bool dense;
final bool terminal;
+ /// Where the machine's session index found the searched words in this
+ /// conversation, when that is how it matched.
+ final SessionContentHit? found;
+
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
@@ -488,6 +500,30 @@ class _AgentPreview extends StatelessWidget {
? 16
: 26,
),
+ if (found case final found? when found.field != 'name') ...[
+ Text(
+ [
+ switch (found.field) {
+ 'answer' => 'Found in an answer',
+ 'tools' => 'Found in a command or file',
+ _ => 'Found in what you asked',
+ },
+ if (found.at case final at?)
+ '${harnessActivityAge(at, DateTime.now())} ago',
+ ].join(' · '),
+ style: terminal
+ ? muted
+ : muted.copyWith(fontWeight: FontWeight.w500),
+ ),
+ if (!terminal) const SizedBox(height: 7),
+ SessionSnippetText(
+ found,
+ key: ValueKey('preview-found:${found.destinationId}'),
+ style: body,
+ maxLines: null,
+ ),
+ SizedBox(height: terminal ? cell.height : 24),
+ ],
if (waiting != null) ...[
Container(
width: double.infinity,
diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
index 3d255b273..2b13a785c 100644
--- a/desktop/lib/widgets/swarm_switcher.dart
+++ b/desktop/lib/widgets/swarm_switcher.dart
@@ -23,6 +23,7 @@ import '../shared/theme/app_theme.dart' as grid;
import '../shared/widgets/app_dialog.dart';
import '../state/app_state.dart';
import '../state/swarm_navigation.dart';
+import '../state/session_content_search.dart';
import '../state/swarm_search.dart';
import '../models/model_search_catalog.dart';
import '../state/harness_sessions.dart' show SessionFilter, harnessActivityAge;
@@ -1258,10 +1259,15 @@ class _SearchRowContent extends StatefulWidget {
}
class _SearchRowContentState extends State<_SearchRowContent> {
- late (String, bool) _query;
+ late (String, bool, SessionContentHit?) _query;
- (String, bool) get _currentQuery =>
- (widget.search.matchQuery, widget.search.isHelpMode);
+ /// What this row draws from the search: its words, and what a machine's
+ /// session index found in its conversation, which can land after the words.
+ (String, bool, SessionContentHit?) get _currentQuery => (
+ widget.search.wordsQuery,
+ widget.search.isHelpMode,
+ widget.search.contentHitFor(widget.row.id),
+ );
@override
void initState() {
@@ -1295,7 +1301,18 @@ class _SearchRowContentState extends State<_SearchRowContent> {
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
final row = widget.row;
- final matches = searchResultMatches(row, swarmQueryTerms(_query.$1));
+ final terms = swarmQueryTerms(_query.$1);
+ final matches = searchResultMatches(row, terms);
+ // Found in what was said rather than in the row's own name and context:
+ // the second line shows where, instead of the context that did not match.
+ final hit = widget.search.contentHitFor(row.id);
+ final snippet =
+ hit != null &&
+ hit.snippet.isNotEmpty &&
+ hit.field != 'name' &&
+ (terms.isEmpty || matches.length < terms.take(12).toSet().length)
+ ? hit
+ : null;
if (widget.bios) {
final theme = terminalThemeFor(
grid.AppTheme.palette.value,
@@ -1334,6 +1351,7 @@ class _SearchRowContentState extends State<_SearchRowContent> {
label: row.isCreate
? '${row.title}\n$detail'
: '${row.title}\n${row.terminalDetail ?? row.detail}'
+ '${snippet == null ? '' : ', Found in conversation: ${snippet.plainSnippet}'}'
'${modelAction == null ? '' : ', $modelAction'}'
'${widget.unavailableReason == null ? '' : ', ${widget.unavailableReason}'}'
'${row.shortcut == null ? '' : ', Shortcut ${row.shortcut}'}'
@@ -1352,15 +1370,36 @@ class _SearchRowContentState extends State<_SearchRowContent> {
children: [
// Match Cmd-N's empty two-cell gutter.
SizedBox(width: cell.width * 2),
- Expanded(
- child: row.isCreate
- ? Text(row.title, style: style, maxLines: 1)
- : SearchResultText(
- row.title,
- matches: matches.where((match) => match.title),
- style: style,
- ),
- ),
+ if (widget.singleLine && snippet != null) ...[
+ // One line per result: the name, then where the words
+ // were said, the way fzf shows the matching line.
+ ConstrainedBox(
+ constraints: BoxConstraints(
+ maxWidth: constraints.maxWidth * .4,
+ ),
+ child: SearchResultText(
+ row.title,
+ matches: matches.where((match) => match.title),
+ style: style,
+ ),
+ ),
+ SizedBox(width: cell.width * 2),
+ Expanded(
+ child: SessionSnippetText(
+ snippet,
+ style: terminalContentStyle(color: muted),
+ ),
+ ),
+ ] else
+ Expanded(
+ child: row.isCreate
+ ? Text(row.title, style: style, maxLines: 1)
+ : SearchResultText(
+ row.title,
+ matches: matches.where((match) => match.title),
+ style: style,
+ ),
+ ),
if (modelAction != null) ...[
SizedBox(width: cell.width * 2),
Text(
@@ -1411,7 +1450,9 @@ class _SearchRowContentState extends State<_SearchRowContent> {
),
),
),
- if (!widget.singleLine && !row.isCommand && detail.isNotEmpty)
+ if (!widget.singleLine &&
+ !row.isCommand &&
+ (detail.isNotEmpty || snippet != null))
Padding(
padding: EdgeInsets.only(
left: cell.width * 3,
@@ -1421,11 +1462,16 @@ class _SearchRowContentState extends State<_SearchRowContent> {
height: cell.height,
child: Align(
alignment: Alignment.centerLeft,
- child: SearchResultText(
- detail,
- matches: matches.where((match) => !match.title),
- style: terminalContentStyle(color: muted),
- ),
+ child: snippet != null
+ ? SessionSnippetText(
+ snippet,
+ style: terminalContentStyle(color: muted),
+ )
+ : SearchResultText(
+ detail,
+ matches: matches.where((match) => !match.title),
+ style: terminalContentStyle(color: muted),
+ ),
),
),
),
@@ -1441,7 +1487,14 @@ class _SearchRowContentState extends State<_SearchRowContent> {
final detailText = widget.terminal
? row.terminalDetail ?? row.detail
: row.detail;
- final detail = widget.terminal && row.promptContext != null
+ final detail = snippet != null
+ ? SessionSnippetText(
+ snippet,
+ style: widget.terminal
+ ? boxMonoStyle(color: kBoxFaint)
+ : boxMonoStyle(color: Colors.white54),
+ )
+ : widget.terminal && row.promptContext != null
? PromptContextView(
contextData: row.promptContext!,
matches: matches.where((match) => !match.title),
diff --git a/desktop/test/bios_navigation_test.dart b/desktop/test/bios_navigation_test.dart
index 04de241a7..4904de489 100644
--- a/desktop/test/bios_navigation_test.dart
+++ b/desktop/test/bios_navigation_test.dart
@@ -51,9 +51,10 @@ void main() {
'a12',
]);
search.setQuery('Agent 1');
+ // The harness named exactly that leads; the rest keep activity order.
expect(
search.rows.where((row) => !row.isCreate).map((row) => row.agentId),
- ['a10', 'a11', 'a1', 'a12'],
+ ['a1', 'a10', 'a11', 'a12'],
);
final ordinary = SwarmSearchController(app, recent, adding: true);
diff --git a/desktop/test/prompt_context_test.dart b/desktop/test/prompt_context_test.dart
index 27161a42c..1877c6968 100644
--- a/desktop/test/prompt_context_test.dart
+++ b/desktop/test/prompt_context_test.dart
@@ -153,7 +153,9 @@ void main() {
);
await show();
expect(find.text('main'), findsOneWidget);
- await show(matches: [(field: 'main', term: 'mai', title: false)]);
+ await show(
+ matches: [(field: 'main', term: 'mai', title: false, strict: false)],
+ );
final highlighted = tester.widget<Text>(find.text('main'));
expect(highlighted.textSpan, isNotNull);
await show(
diff --git a/desktop/test/resource_preview_actions_test.dart b/desktop/test/resource_preview_actions_test.dart
index 05110c203..944f12717 100644
--- a/desktop/test/resource_preview_actions_test.dart
+++ b/desktop/test/resource_preview_actions_test.dart
@@ -585,6 +585,9 @@ void main() {
expect(choices.single.action, SwarmSearchAction.addHere);
expect(choices.single.destination.agentId, 'task');
expect(app.panes, isEmpty);
+ // The machines are connected, so the typed words also went to their
+ // session indexes after a pause; let that pause run out.
+ await tester.pump(const Duration(milliseconds: 200));
},
);
diff --git a/desktop/test/search_when_test.dart b/desktop/test/search_when_test.dart
new file mode 100644
index 000000000..f45e53bf1
--- /dev/null
+++ b/desktop/test/search_when_test.dart
@@ -0,0 +1,87 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/state/search_when.dart';
+
+void main() {
+ // Saturday 26 September 2026, 14:30 local.
+ final now = DateTime(2026, 9, 26, 14, 30);
+ DateTime day(int d) => DateTime(2026, 9, d);
+
+ ({String words, DateTime? from, DateTime? to}) read(String query) {
+ final parsed = parseSearchWhen(query, now);
+ return (words: parsed.words, from: parsed.when?.from, to: parsed.when?.to);
+ }
+
+ test(
+ 'reads the common ways of saying when, and takes them out of the words',
+ () {
+ expect(read('dial today'), (words: 'dial', from: day(26), to: now));
+ expect(read('yesterday dial'), (
+ words: 'dial',
+ from: day(25),
+ to: day(26),
+ ));
+ expect(read('dial this week'), (words: 'dial', from: day(21), to: now));
+ expect(read('dial LAST WEEK scroll'), (
+ words: 'dial scroll',
+ from: day(14),
+ to: day(21),
+ ));
+ expect(read('cohorts last month'), (
+ words: 'cohorts',
+ from: DateTime(2026, 8),
+ to: DateTime(2026, 9),
+ ));
+ },
+ );
+
+ test('keeps "ago" loose, the way memory is', () {
+ expect(read('dial 3 days ago'), (
+ words: 'dial',
+ from: day(22),
+ to: day(25),
+ ));
+ expect(read('a few days ago mobile'), (
+ words: 'mobile',
+ from: day(20),
+ to: day(25),
+ ));
+ expect(read('two weeks ago'), (words: '', from: day(8), to: day(17)));
+ expect(read('a week ago dial'), (
+ words: 'dial',
+ from: day(15),
+ to: day(24),
+ ));
+ });
+
+ test('a weekday is its most recent one; "last" skips today', () {
+ // 26 September 2026 is a Saturday.
+ expect(read('dial on monday'), (words: 'dial', from: day(21), to: day(22)));
+ expect(read('on friday'), (words: '', from: day(25), to: day(26)));
+ expect(read('dial on saturday'), (words: 'dial', from: day(26), to: now));
+ expect(read('dial last saturday'), (
+ words: 'dial',
+ from: day(19),
+ to: day(20),
+ ));
+ });
+
+ test('"0 days ago" is today, as the CLI reads it', () {
+ expect(read('dial 0 days ago'), (words: 'dial', from: day(25), to: now));
+ });
+
+ test('leaves words alone that only look like time', () {
+ for (final query in [
+ 'dial',
+ 'todays menu',
+ 'sundays',
+ 'weekday parser',
+ 'lastweek',
+ 'sun mon',
+ 'days ago',
+ 'friday deploy',
+ ]) {
+ expect(parseSearchWhen(query, now).when, isNull, reason: query);
+ expect(parseSearchWhen(query, now).words, query);
+ }
+ });
+}
diff --git a/desktop/test/session_content_search_test.dart b/desktop/test/session_content_search_test.dart
new file mode 100644
index 000000000..b62cc51e7
--- /dev/null
+++ b/desktop/test/session_content_search_test.dart
@@ -0,0 +1,571 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/state/harness_placement.dart';
+import 'package:harness/state/session_content_search.dart';
+import 'package:harness/state/swarm_navigation.dart';
+import 'package:harness/state/swarm_search.dart';
+import 'package:harness/widgets/search_result_text.dart';
+import 'package:harness/ws/ws_conn.dart';
+
+import 'swarm_state_test.dart' show createApp;
+
+const _o = kSnippetMarkOpen;
+const _c = kSnippetMarkClose;
+
+SessionContentHit hit(
+ String agentId, {
+ String machineId = 'm',
+ bool together = true,
+ double score = .5,
+ int position = 0,
+ String snippet = 'the ${_o}dial$_c scroll',
+ String field = 'ask',
+}) => SessionContentHit(
+ machineId: machineId,
+ agentId: agentId,
+ sessionId: 'session-$agentId',
+ field: field,
+ snippet: snippet,
+ together: together,
+ score: score,
+ position: position,
+);
+
+/// A daemon that answers only `session_search`, from [answers] by query.
+class SearchConnection extends WsConn {
+ SearchConnection(this.answers)
+ : super(
+ wsBaseUrl: 'ws://fixture.invalid',
+ autonomousEnv: 'test',
+ machineId: 'm',
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: (_) {},
+ onEvent: (_) {},
+ onStatus: (_) {},
+ );
+
+ final Map<String, List<Map<String, dynamic>>> answers;
+ final asked = <String>[];
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String type, {
+ Map<String, dynamic> payload = const {},
+ Duration timeout = const Duration(seconds: 20),
+ }) async {
+ if (type != 'session_search') return {'error': 'UNSUPPORTED'};
+ final query = payload['query'] as String;
+ asked.add(query);
+ return {'hits': answers[query] ?? const [], 'indexed': 3, 'pending': 0};
+ }
+}
+
+Future<void> settle() => Future<void>.delayed(const Duration(milliseconds: 30));
+
+/// Past Open Harness's pause-in-typing debounce and the reply.
+Future<void> answered() =>
+ Future<void>.delayed(const Duration(milliseconds: 250));
+
+void main() {
+ group('SessionContentHit', () {
+ test('reads a daemon reply and refuses what it cannot use', () {
+ final hits = SessionContentHit.listFromReply('m', {
+ 'hits': [
+ {
+ 'agentId': 'a1',
+ 'sessionId': 's1',
+ 'field': 'answer',
+ 'snippet': 'halved the ${_o}scroll$_c delta',
+ 'together': true,
+ 'score': 1.7,
+ 'turn': 4,
+ 'at': 1790000000000,
+ },
+ {'sessionId': 's2'},
+ 'junk',
+ ],
+ });
+ expect(hits, hasLength(1));
+ expect(hits.single.destinationId, agentDestinationId('m', 'a1'));
+ expect(hits.single.score, 1);
+ expect(hits.single.plainSnippet, 'halved the scroll delta');
+ expect(
+ hits.single.at,
+ DateTime.fromMillisecondsSinceEpoch(1790000000000),
+ );
+ expect(SessionContentHit.listFromReply('m', {'error': 'X'}), isEmpty);
+ });
+
+ test('snippet runs bold exactly the marked words', () {
+ expect(snippetRuns('a ${_o}dial$_c and ${_o}scroll$_c.'), [
+ (text: 'a ', matched: false),
+ (text: 'dial', matched: true),
+ (text: ' and ', matched: false),
+ (text: 'scroll', matched: true),
+ (text: '.', matched: false),
+ ]);
+ expect(snippetRuns('unclosed ${_o}mark'), [
+ (text: 'unclosed ', matched: false),
+ (text: 'mark', matched: true),
+ ]);
+ expect(snippetLead('ask'), '> ');
+ expect(snippetLead('tools'), r'$ ');
+ expect(snippetLead('answer'), '');
+ });
+
+ testWidgets('a snippet reads as one line with its words in bold', (
+ tester,
+ ) async {
+ await tester.pumpWidget(
+ MaterialApp(
+ home: SessionSnippetText(hit('a1'), style: const TextStyle()),
+ ),
+ );
+ final text = tester.widget<Text>(find.byType(Text));
+ expect(text.textSpan!.toPlainText(), '> the dial scroll');
+ expect(text.maxLines, 1);
+ });
+ });
+
+ group('SessionContentSearch', () {
+ test('asks every machine once per pause in typing and keeps the best hit per harness', () async {
+ final asked = <(String, String)>[];
+ final gate = Completer<void>();
+ final search = SessionContentSearch(
+ machines: () => ['m', 'n'],
+ debounce: const Duration(milliseconds: 5),
+ ask: (machine, query, _) async {
+ asked.add((machine, query));
+ if (machine == 'n') await gate.future;
+ return machine == 'm'
+ ? [
+ hit('a1', together: false, score: .9),
+ hit('a1', together: true, score: .2),
+ ]
+ : [hit('b1', machineId: 'n')];
+ },
+ );
+ addTearDown(search.dispose);
+ search.search('d');
+ search.search('di');
+ search.search('dia');
+ search.search('dial');
+ await settle();
+ expect(asked, [('m', 'dial'), ('n', 'dial')]);
+ // One harness, its best conversation: all words together beats spread.
+ expect(search.hits.keys, [agentDestinationId('m', 'a1')]);
+ expect(search.hits.values.single.together, isTrue);
+ expect(search.answered, 'dial');
+ gate.complete();
+ await settle();
+ expect(search.hits.keys, hasLength(2));
+ });
+
+ test(
+ 'drops a late answer to an older question and clears for new words',
+ () async {
+ final answers = <String, Completer<List<SessionContentHit>?>>{};
+ final search = SessionContentSearch(
+ machines: () => ['m'],
+ debounce: Duration.zero,
+ ask: (_, query, _) => (answers[query] = Completer()).future,
+ );
+ addTearDown(search.dispose);
+ search.search('dial');
+ await settle();
+ search.search('dial scroll');
+ await settle();
+ answers['dial']!.complete([hit('old')]);
+ await settle();
+ expect(search.hits, isEmpty);
+ answers['dial scroll']!.complete([hit('new')]);
+ await settle();
+ expect(search.hits.keys, [agentDestinationId('m', 'new')]);
+ // Typing on keeps the answer on screen; different words clear it.
+ search.search('dial scroll f');
+ expect(search.hits, isNotEmpty);
+ search.search('keyboard');
+ expect(search.hits, isEmpty);
+ search.search('k');
+ await settle();
+ expect(answers.keys, isNot(contains('k')));
+ },
+ );
+ });
+
+ test('an earlier answer vouches only for words its snippet shows', () async {
+ final search = SessionContentSearch(
+ machines: () => ['m'],
+ debounce: Duration.zero,
+ ask: (_, query, _) async => query == 'mob'
+ ? [
+ hit('a1', snippet: 'the ${_o}mobile$_c swipe feels slow'),
+ hit('a2', snippet: 'the ${_o}mobile$_c build broke'),
+ ]
+ : Completer<List<SessionContentHit>?>().future,
+ );
+ addTearDown(search.dispose);
+ search.search('mob');
+ await settle();
+ expect(search.hitsFor('mob').keys, hasLength(2));
+ search.search('mob swipe');
+ expect(search.hitsFor('mob swipe').keys, [agentDestinationId('m', 'a1')]);
+ expect(search.hitsFor('mob swi').keys, [agentDestinationId('m', 'a1')]);
+ expect(search.hitsFor('mob build keyboard'), isEmpty);
+ });
+
+ test(
+ 'a time in the words goes to the machines as a window, not as words',
+ () async {
+ final asked = <(String, DateTime?, DateTime?)>[];
+ final search = SessionContentSearch(
+ machines: () => ['m'],
+ debounce: Duration.zero,
+ now: () => DateTime(2026, 9, 26, 14, 30),
+ ask: (_, words, when) async {
+ asked.add((words, when?.from, when?.to));
+ return [hit('a1', snippet: 'fix the ${_o}dial$_c')];
+ },
+ );
+ addTearDown(search.dispose);
+ search.search('dial last week');
+ await settle();
+ expect(asked, [('dial', DateTime(2026, 9, 14), DateTime(2026, 9, 21))]);
+ expect(search.hitsFor('dial last week'), hasLength(1));
+ // Another time: that answer says nothing about it.
+ expect(search.hitsFor('dial yesterday'), isEmpty);
+ // A time alone is a search: what was worked on then.
+ search.search('yesterday');
+ await settle();
+ expect(asked.last, ('', DateTime(2026, 9, 25), DateTime(2026, 9, 26)));
+ },
+ );
+
+ test(
+ '"today" is the same window keystroke to keystroke, though now moves',
+ () async {
+ var clock = DateTime(2026, 9, 26, 14, 30);
+ final search = SessionContentSearch(
+ machines: () => ['m'],
+ debounce: Duration.zero,
+ now: () => clock = clock.add(const Duration(milliseconds: 7)),
+ ask: (_, words, when) async => words == 'dia'
+ ? [hit('a1', snippet: 'the ${_o}dial$_c scroll')]
+ : Completer<List<SessionContentHit>?>().future,
+ );
+ addTearDown(search.dispose);
+ search.search('today dia');
+ await settle();
+ search.search('today dial');
+ expect(search.hitsFor('today dial').keys, [
+ agentDestinationId('m', 'a1'),
+ ]);
+ // Read once per query and answer, however many rows ask.
+ expect(
+ identical(search.hitsFor('today dial'), search.hitsFor('today dial')),
+ isTrue,
+ );
+ expect(search.hitsFor('yesterday dial'), isEmpty);
+ },
+ );
+
+ group('ranking with what was said', () {
+ SwarmDestination row(String id, String title, int hour) => SwarmDestination(
+ id: agentDestinationId('m', id),
+ title: title,
+ detail: '',
+ swarmId: null,
+ current: false,
+ agentId: id,
+ machineId: 'm',
+ lastActivityAt: DateTime.utc(2026, 9, 26, hour),
+ );
+
+ test(
+ 'what was said ranks under names, real words above scattered letters',
+ () {
+ final rows = [
+ row('named', 'Dial scroll fix', 1),
+ row('scattered', 'Dig all logs', 12),
+ row('said', 'Claude harness 9-25 7:25', 3),
+ row('said better', 'Codex harness 9-24 1:20', 2),
+ row('spread', 'Keyboard', 11),
+ row('nothing', 'Mobile', 10),
+ ];
+ final hits = {
+ for (final found in [
+ hit('said better', position: 0),
+ hit('said', position: 1),
+ hit('spread', together: false, position: 2),
+ ])
+ found.destinationId: found,
+ };
+ expect(
+ rankSwarmDestinationsByActivity(
+ rows,
+ 'dial',
+ contentHits: hits,
+ ).map((r) => r.agentId),
+ ['named', 'said better', 'said', 'spread', 'scattered'],
+ );
+ // Without the index the conversations are invisible.
+ expect(
+ rankSwarmDestinationsByActivity(rows, 'dial').map((r) => r.agentId),
+ ['named', 'scattered'],
+ );
+ },
+ );
+
+ test("each machine's first hit is as good as another's first", () {
+ SwarmDestination on(String machine, String id, int hour) =>
+ SwarmDestination(
+ id: agentDestinationId(machine, id),
+ title: 'Claude harness $id',
+ detail: '',
+ swarmId: null,
+ current: false,
+ agentId: id,
+ machineId: machine,
+ lastActivityAt: DateTime.utc(2026, 9, 26, hour),
+ );
+ final rows = [on('m', 'm1', 1), on('m', 'm2', 9), on('n', 'n1', 5)];
+ final hits = {
+ for (final found in [
+ // A remote machine's lone weak hit scores 1.0 against its own best,
+ // yet ranks with the other machine's first, not above everything.
+ hit('m1', score: .7),
+ hit('m2', score: .6, position: 1),
+ hit('n1', machineId: 'n', score: 1),
+ ])
+ found.destinationId: found,
+ };
+ expect(
+ rankSwarmDestinationsByActivity(
+ rows,
+ 'retention',
+ contentHits: hits,
+ ).map((r) => r.agentId),
+ ['n1', 'm1', 'm2'],
+ );
+ });
+ });
+
+ group('Open Harness', () {
+ test(
+ 'finds a harness by what was said in it, with the best match selected',
+ () async {
+ final connection = SearchConnection({
+ 'retention cohorts': [
+ {
+ 'agentId': 'a7',
+ 'sessionId': 's7',
+ 'field': 'answer',
+ 'snippet': 'Day-7 ${_o}retention$_c by ${_o}cohort$_c is 35%',
+ 'together': true,
+ 'score': .9,
+ },
+ {
+ 'agentId': 'a3',
+ 'sessionId': 's3',
+ 'field': 'ask',
+ 'snippet': 'the ${_o}retention$_c chart',
+ 'together': false,
+ 'score': .5,
+ },
+ // A harness this app does not list is ignored.
+ {'agentId': 'gone', 'sessionId': 'sx', 'snippet': '', 'score': 1},
+ ],
+ });
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ addTearDown(app.dispose);
+ final search = SwarmSearchController(
+ app,
+ const [],
+ adding: true,
+ offersCreate: true,
+ activityFirst: true,
+ placement: HarnessPlacement.newTab,
+ );
+ addTearDown(search.dispose);
+
+ search.setQuery('retention cohorts');
+ final found = search.rows.where((row) => !row.isCreate).toList();
+ expect(found, isEmpty);
+ await answered();
+ expect(connection.asked, ['retention cohorts']);
+ expect(
+ search.rows.where((row) => !row.isCreate).map((row) => row.agentId),
+ ['a7', 'a3'],
+ );
+ expect(search.selected!.agentId, 'a7');
+ expect(
+ search.contentHitFor(agentDestinationId('m', 'a7'))!.field,
+ 'answer',
+ );
+
+ // Commands and scoped modes never go to the session index.
+ search.setQuery('>retention');
+ await answered();
+ expect(connection.asked, ['retention cohorts']);
+ expect(search.contentHitFor(agentDestinationId('m', 'a7')), isNull);
+ },
+ );
+
+ test('a time narrows Open Harness to what was worked on then', () async {
+ final now = DateTime.now();
+ final connection = SearchConnection({
+ '': [
+ {
+ 'agentId': 'vouched',
+ 'sessionId': 's',
+ 'field': 'ask',
+ 'snippet': 'what I asked then',
+ 'together': true,
+ 'score': 1,
+ },
+ ],
+ });
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ app.machineStates['m']!.agents = [
+ Agent(
+ id: 'then',
+ name: 'Then',
+ engine: 'codex',
+ terminalAvailable: true,
+ lastActivityAt: DateTime(now.year, now.month, now.day - 1, 12),
+ ),
+ Agent(
+ id: 'old',
+ name: 'Old',
+ engine: 'codex',
+ terminalAvailable: true,
+ lastActivityAt: now.subtract(const Duration(days: 20)),
+ ),
+ // Last active just now, but a machine saw it worked on in the window.
+ Agent(
+ id: 'vouched',
+ name: 'Vouched',
+ engine: 'codex',
+ terminalAvailable: true,
+ lastActivityAt: now,
+ ),
+ ];
+ addTearDown(app.dispose);
+ final search = SwarmSearchController(
+ app,
+ const [],
+ adding: true,
+ offersCreate: true,
+ activityFirst: true,
+ placement: HarnessPlacement.newTab,
+ );
+ addTearDown(search.dispose);
+ search.setQuery('yesterday');
+ expect(search.wordsQuery, '');
+ await answered();
+ expect(connection.asked, ['']);
+ expect(
+ search.rows.where((row) => !row.isCreate).map((row) => row.agentId),
+ ['vouched', 'then'],
+ );
+ expect(
+ search.contentHitFor(agentDestinationId('m', 'vouched'))!.snippet,
+ 'what I asked then',
+ );
+ });
+
+ test('a restored draft searches what was said too', () async {
+ final connection = SearchConnection({
+ 'retention': [
+ {
+ 'agentId': 'a7',
+ 'sessionId': 's7',
+ 'snippet': 'x',
+ 'together': true,
+ 'score': 1,
+ },
+ ],
+ });
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ addTearDown(app.dispose);
+ SwarmSearchController open() => SwarmSearchController(
+ app,
+ const [],
+ adding: true,
+ offersCreate: true,
+ activityFirst: true,
+ placement: HarnessPlacement.newTab,
+ );
+ final first = open()..setQuery('retention');
+ final draft = first.draft;
+ first.dispose();
+ await answered();
+ connection.asked.clear();
+ final again = open();
+ addTearDown(again.dispose);
+ again.restoreDraft(draft, newTab: true);
+ await answered();
+ expect(connection.asked, ['retention']);
+ expect(again.rows.map((row) => row.agentId), contains('a7'));
+ });
+
+ test(
+ 'a hit arriving later does not take the row somebody moved to',
+ () async {
+ final connection = SearchConnection({
+ 'agent 1': [
+ {
+ 'agentId': 'a55',
+ 'sessionId': 's',
+ 'snippet': 'x',
+ 'together': true,
+ 'score': 1,
+ },
+ ],
+ });
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ app.machineStates['m']!.agents = [
+ for (final (id, name) in [
+ ('a1', 'Agent 1'),
+ ('a10', 'Agent 10'),
+ ('a55', 'Other'),
+ ])
+ Agent(id: id, name: name, engine: 'codex', terminalAvailable: true),
+ ];
+ addTearDown(app.dispose);
+ final search = SwarmSearchController(
+ app,
+ const [],
+ adding: true,
+ offersCreate: true,
+ activityFirst: true,
+ placement: HarnessPlacement.newTab,
+ );
+ addTearDown(search.dispose);
+ search.setQuery('agent 1');
+ final first = search.selected!.agentId;
+ search.move(1);
+ final moved = search.selected!.id;
+ expect(search.selected!.agentId, isNot(first));
+ await answered();
+ expect(search.rows.map((row) => row.agentId), contains('a55'));
+ expect(search.selected!.id, moved);
+ },
+ );
+ });
+}
diff --git a/desktop/test/session_search_daemon_e2e_test.dart b/desktop/test/session_search_daemon_e2e_test.dart
new file mode 100644
index 000000000..88b476795
--- /dev/null
+++ b/desktop/test/session_search_daemon_e2e_test.dart
@@ -0,0 +1,156 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/state/harness_placement.dart';
+import 'package:harness/state/session_content_search.dart';
+import 'package:harness/state/swarm_search.dart';
+import 'package:harness/ws/ws_conn.dart';
+
+import 'swarm_state_test.dart' show createApp;
+
+/// Cmd-P against a real daemon: the app's own transport, catalog and search
+/// controller, the daemon's real index of real transcripts. Point it at a
+/// running daemon (never the one serving your harnesses — see
+/// docs/research/2026-09-26-session-search.md for the isolated setup):
+///
+/// HARNESS_SEARCH_E2E_PORT=28473 HARNESS_SEARCH_E2E_HOME=`its HOME` \
+/// flutter test test/session_search_daemon_e2e_test.dart
+///
+/// Queries and expectations come from HARNESS_SEARCH_E2E_CASES, one per line:
+/// `query => expected words in the top row's title or snippet`, `=> *` for
+/// any content hit on the top row, or `=> -` for no content hits.
+void main() {
+ final port = Platform.environment['HARNESS_SEARCH_E2E_PORT'];
+ final home = Platform.environment['HARNESS_SEARCH_E2E_HOME'];
+ if (port == null || home == null) {
+ test(
+ 'Cmd-P against a real daemon',
+ () {},
+ skip: 'Set HARNESS_SEARCH_E2E_PORT and _HOME.',
+ );
+ return;
+ }
+ final machineId = File('$home/.harness/computer-id')
+ .readAsStringSync()
+ .trim();
+ late WsConn connection;
+
+ Future<void> until(
+ String label,
+ bool Function() check, {
+ int seconds = 10,
+ }) async {
+ final deadline = DateTime.now().add(Duration(seconds: seconds));
+ while (DateTime.now().isBefore(deadline)) {
+ if (check()) return;
+ await Future<void>.delayed(const Duration(milliseconds: 20));
+ }
+ fail('Timed out: $label');
+ }
+
+ setUpAll(() async {
+ var connected = false;
+ connection = WsConn(
+ wsBaseUrl: '',
+ autonomousEnv: 'prod',
+ machineId: machineId,
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: fail,
+ onStatus: (status) => connected = status == ConnectionStatus.connected,
+ onEvent: (_) async {},
+ transportKind: WsTransportKind.localPlaintext,
+ localWsUri: Uri.parse('ws://127.0.0.1:$port/api/local-ws'),
+ );
+ await connection.connect();
+ await until('connected', () => connected);
+ });
+ tearDownAll(() => connection.close());
+
+ test('finds harnesses by what was said, fast, on the real index', () async {
+ final listed = await connection.request(
+ 'agents_list',
+ payload: const {'includeStopped': true},
+ );
+ final agents = [
+ for (final raw in listed['agents'] as List)
+ Agent.fromJson(raw as Map<String, dynamic>),
+ ];
+ expect(agents, isNotEmpty);
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ addTearDown(app.dispose);
+ // The fixture machine stands for the daemon's own; the connection is real.
+ app.machineStates['m']!.agents = agents;
+ final search = SwarmSearchController(
+ app,
+ const [],
+ adding: true,
+ offersCreate: true,
+ activityFirst: true,
+ placement: HarnessPlacement.newTab,
+ );
+ addTearDown(search.dispose);
+
+ final cases = (Platform.environment['HARNESS_SEARCH_E2E_CASES'] ?? '')
+ .split('\n')
+ .where((line) => line.contains('=>'))
+ .map((line) => line.split('=>').map((part) => part.trim()).toList());
+ final report = StringBuffer();
+ var failures = 0;
+ for (final [query, expected] in cases) {
+ final started = DateTime.now();
+ search.setQuery(query);
+ final byName = search.rows.where((row) => !row.isCreate).length;
+ // Answered: the controller holds this query's hits, or the daemon had none.
+ await until(
+ 'answer for $query',
+ () =>
+ search.contentAnswered == query.trim() ||
+ // A prefix (> @ # : * ?) opens another kind of search.
+ search.isCommandMode ||
+ search.isHelpMode ||
+ search.isGroupMode ||
+ search.isModelMode ||
+ search.isStoreMode ||
+ !SessionContentSearch(
+ machines: () => const [],
+ ask: (_, _, _) async => null,
+ ).searchable(query),
+ );
+ final took = DateTime.now().difference(started).inMilliseconds;
+ final rows = search.rows.where((row) => !row.isCreate).toList();
+ final top = rows.isEmpty ? null : rows.first;
+ final hit = top == null ? null : search.contentHitFor(top.id);
+ final line = '${top?.title ?? '(none)'} ${hit?.plainSnippet ?? ''}'
+ .toLowerCase();
+ final ok = switch (expected) {
+ '-' => rows.every((row) => search.contentHitFor(row.id) == null),
+ '*' => hit != null,
+ _ => expected.toLowerCase().split(' ').every(line.contains),
+ };
+ if (!ok) failures++;
+ report.writeln(
+ '${ok ? '✓' : '✗'} "$query" · ${rows.length} rows ($byName by name before the answer) · ${took}ms\n'
+ ' 1. ${top?.title} ${hit == null ? '' : '· ${hit.field}: ${hit.plainSnippet}'}\n'
+ '${rows.skip(1).take(2).map((row) => ' · ${row.title} ${search.contentHitFor(row.id)?.plainSnippet ?? ''}').join('\n')}',
+ );
+ // The best row is selected; with none, the New Harness row.
+ final selected = search.selected;
+ if (top == null
+ ? selected != null && !selected.isCreate
+ : selected?.id != top.id) {
+ failures++;
+ report.writeln(
+ ' ✗ selected ${selected?.title} instead of ${top?.title}',
+ );
+ }
+ }
+ // ignore: avoid_print
+ print(report);
+ expect(failures, 0, reason: report.toString());
+ }, timeout: const Timeout(Duration(minutes: 5)));
+}
diff --git a/desktop/test/session_search_rendering_test.dart b/desktop/test/session_search_rendering_test.dart
new file mode 100644
index 000000000..bc87185cb
--- /dev/null
+++ b/desktop/test/session_search_rendering_test.dart
@@ -0,0 +1,96 @@
+import 'support/open_harness.dart';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shortcuts/app_keymap.dart';
+import 'package:harness/state/session_content_search.dart';
+import 'package:harness/state/swarm_catalog.dart';
+import 'package:harness/state/swarm_navigation.dart';
+import 'package:harness/widgets/swarm_switcher.dart';
+
+import 'keymap_host_test.dart' show MemoryKeymap;
+import 'session_content_search_test.dart' show SearchConnection;
+import 'swarm_state_test.dart' show createApp;
+
+void main() {
+ testWidgets(
+ 'a harness found by what was said in it shows where, in place of its context',
+ (tester) async {
+ final connection = SearchConnection({
+ 'retention cohorts': [
+ {
+ 'agentId': 'a7',
+ 'sessionId': 's7',
+ 'field': 'ask',
+ 'snippet':
+ 'compare ${kSnippetMarkOpen}retention$kSnippetMarkClose by '
+ '$kSnippetMarkOpen${'cohort'}$kSnippetMarkClose',
+ 'together': true,
+ 'score': .9,
+ },
+ ],
+ });
+ final app = createApp(
+ connected: true,
+ connectionForTest: (_) => connection,
+ );
+ final map = MemoryKeymap();
+ final projects = SwarmProjectStore();
+ addTearDown(map.dispose);
+ addTearDown(projects.dispose);
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(1280, 800);
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ builder: (_, child) => grid.BrightnessScope(
+ child: KeymapProvider(keymap: map, child: child!),
+ ),
+ home: SwarmScreen(
+ notifier: app,
+ nativeTabs: false,
+ projectStore: projects,
+ ),
+ ),
+ );
+ await tester.pump(const Duration(milliseconds: 100));
+ await openHarnessPicker(tester);
+ await tester.enterText(
+ find.byKey(const ValueKey('swarm-search-input')),
+ 'retention cohorts',
+ );
+ // Past the pause-in-typing debounce, then the reply.
+ await tester.pump(const Duration(milliseconds: 200));
+ await tester.pump(const Duration(milliseconds: 50));
+ final search = tester
+ .widget<SwarmSearchResults>(find.byType(SwarmSearchResults))
+ .search;
+ expect(search.selected!.agentId, 'a7');
+ final snippet = find.byKey(
+ ValueKey('session-snippet:${agentDestinationId('m', 'a7')}'),
+ );
+ expect(snippet, findsOneWidget);
+ expect(
+ tester.widget<Text>(snippet).textSpan!.toPlainText(),
+ '> compare retention by cohort',
+ );
+ final found = find.byKey(
+ ValueKey('preview-found:${agentDestinationId('m', 'a7')}'),
+ );
+ expect(found, findsOneWidget);
+ final foundText = find.descendant(of: found, matching: find.byType(Text));
+ expect(
+ tester.widget<Text>(foundText).textSpan!.toPlainText(),
+ '> compare retention by cohort',
+ );
+ expect(tester.widget<Text>(foundText).maxLines, isNull);
+ expect(find.text('Found in what you asked'), findsOneWidget);
+ app.dispose();
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+}
diff --git a/desktop/test/swarm_navigation_test.dart b/desktop/test/swarm_navigation_test.dart
index c7dc121d8..2e26b45e9 100644
--- a/desktop/test/swarm_navigation_test.dart
+++ b/desktop/test/swarm_navigation_test.dart
@@ -1,5 +1,6 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/models.dart';
+import 'package:harness/state/session_preview.dart';
import 'package:harness/state/swarm_navigation.dart';
import 'package:harness/terminal/terminal_session.dart';
@@ -79,6 +80,122 @@ void main() {
]);
});
+ test('the finder ranks how well a harness matched before how recently', () {
+ SwarmDestination row(
+ String id,
+ String title, {
+ String? cwd,
+ required int hour,
+ }) => SwarmDestination(
+ id: id,
+ title: title,
+ detail: '',
+ swarmId: null,
+ current: false,
+ agentId: id,
+ machineId: 'm',
+ lastActivityAt: DateTime.utc(2026, 9, 26, hour),
+ searchFields: [cwd],
+ );
+ final catalog = [
+ row('named', 'hn', hour: 1),
+ row('scattered', 'Harness monitor', hour: 9),
+ row(
+ 'folder',
+ 'Mobile build',
+ cwd: '/users/me/harnesses/worktrees/autonomous-harness/rustic-birch',
+ hour: 12,
+ ),
+ row('word', 'Build the hn tui', hour: 3),
+ row('newer word', 'Fix hn keys', hour: 4),
+ ];
+ expect(
+ rankSwarmDestinationsByActivity(catalog, 'hn').map((row) => row.id),
+ // Two letters scattered through "harness…" names and folders are noise.
+ ['named', 'newer word', 'word'],
+ );
+ // Two letters still work as initials. (A command keeps abbreviations like
+ // "kb": the strict rule is for the hundreds of harness names.)
+ expect(
+ rankSwarmDestinationsByActivity([
+ row('split', 'New Split', hour: 2),
+ row('other', 'Networks', hour: 3),
+ ], 'ns').map((row) => row.id),
+ ['split'],
+ );
+ // Scattered letters that wander across a folder path are no match at all.
+ expect(rankSwarmDestinationsByActivity(catalog, 'auth'), isEmpty);
+ expect(
+ rankSwarmDestinationsByActivity(catalog, 'rustic').single.id,
+ 'folder',
+ );
+
+ final words = [
+ row('fragment', 'Support tickets', hour: 12),
+ row('word', 'Windows port', hour: 1),
+ ];
+ expect(
+ rankSwarmDestinationsByActivity(words, 'port').map((row) => row.id),
+ ['word', 'fragment'],
+ );
+ expect(rankSwarmDestinationsByActivity(words, '').map((row) => row.id), [
+ 'fragment',
+ 'word',
+ ]);
+ });
+
+ test('what was asked finds a session only at the start of a word', () async {
+ const SessionPreviewKey asked = (
+ machineId: 'm',
+ agentId: 'asked',
+ sessionId: null,
+ );
+ const SessionPreviewKey other = (
+ machineId: 'm',
+ agentId: 'other',
+ sessionId: null,
+ );
+ final previews = SessionPreviewStore(
+ canFetch: (_) => true,
+ fetchRecent: (key) async => {
+ 'agentId': key.agentId,
+ 'asks': [
+ key == asked ? 'Port the daemon to Windows' : 'Add support for tabs',
+ ],
+ },
+ );
+ addTearDown(previews.dispose);
+ previews.warm([asked, other]);
+ await Future<void>.delayed(Duration.zero);
+ SwarmDestination row(SessionPreviewKey key) => SwarmDestination(
+ id: key.agentId,
+ title: 'Claude harness 9-26 13:41',
+ detail: '',
+ swarmId: null,
+ current: false,
+ agentId: key.agentId,
+ machineId: key.machineId,
+ previewKey: key,
+ );
+ final catalog = [row(asked), row(other)];
+ expect(
+ rankSwarmDestinationsByActivity(
+ catalog,
+ 'port windows',
+ previews: previews,
+ ).map((row) => row.id),
+ ['asked'],
+ );
+ expect(
+ rankSwarmDestinationsByActivity(
+ catalog,
+ 'support',
+ previews: previews,
+ ).map((row) => row.id),
+ ['other'],
+ );
+ });
+
test('search keeps Unicode subsequences and separate field boundaries', () {
final catalog = [
SwarmDestination(
diff --git a/docs/research/2026-09-26-session-search.md b/docs/research/2026-09-26-session-search.md
new file mode 100644
index 000000000..f46c23144
--- /dev/null
+++ b/docs/research/2026-09-26-session-search.md
@@ -0,0 +1,258 @@
+# Session search: finding a harness by what happened in it
+
+2026-09-26. Why ⌘P could not find the session you wanted, what was built instead, and how it
+measures on one machine's real sessions (184 harnesses, 77 transcripts, 4.4 GB of JSONL).
+
+## The problem
+
+⌘P searched two things, both in the app:
+
+- the catalog: name, agent title, project, branch, folder, machine, engine;
+- the preview cache: the last three asks and the latest recap, fetched for the first 32 sessions
+ per machine only.
+
+The daemon kept nothing older than three turns, and nothing searched the transcripts. Known-item
+test: take something you asked mid-session and search for its two rarest words. The app found the
+session **0%** of the time. A full-transcript keyword index found it **100%** top-1.
+
+The ranking made it worse:
+
+- **Recency beat relevance.** Every match was sorted by last activity, so a weak match on a newer
+ session buried the session named for the word: the harness named `hn` came 6th of 166 matches.
+- **Scattered letters matched through folder paths.** `auth` matched every
+ `.../autonomous-harness/...` folder: 81 matches, none about auth.
+- **Preview text matched fragments.** `port` matched "support", "report", "important".
+
+## What was built
+
+```
+ transcripts on each machine daemon, per machine (cli/src/lib/sessionSearch/) desktop app
+ ───────────────────────── ───────────────────────────────────────────── ───────────
+ ~/.claude/projects/*.jsonl ──► engine's own normalizer ─► turns ─► SQLite FTS5 ◄── session_search
+ ~/.codex/sessions/*.jsonl (from a saved offset; │ session-search.db (E2EE, every
+ cursor, pi, amp, grok, … tool output skipped) │ 0600 connected
+ ▼ machine)
+ `harness search` reads it too merge with name
+ matches, snippet
+```
+
+### Where: each machine's daemon
+
+Transcripts stay on the machine that ran the agent; the app talks only to the CLI. Each daemon
+indexes its own sessions and answers `session_search`. The app asks every connected machine in
+parallel and merges. Only the hits for a query leave a machine, sealed like every other RPC.
+
+### What is indexed
+
+One row per turn: what was asked, the answer, and the tool calls' paths, commands and queries.
+A header row per session holds its name, title and last two folder names, so "mobile swipe" finds
+the session named Mobile whose swipe discussion came later.
+
+- **Reuse, not a parser per format.** A pass runs the engine's own incremental normalizer, the one
+ the live view uses, over the transcript. Every JSONL engine (Claude, Codex, Cursor, Pi, Amp,
+ Grok, Muse, Agy, Copilot, Command Code) comes for free, cleaning included. The engines that keep
+ history in a database (OpenCode, Kilo, Hermes, Devin) go through the readers and replay
+ normalizers `session_get` uses, read whole when the session changed.
+- **Left out:** tool output, reasoning, images. Tool-output records are recognised by their first
+ kilobyte and skipped unparsed. Across all 76 real transcripts, asks, answers, turn times and
+ offsets come out identical with and without the skip.
+- **Cleaned:** harness wrappers removed, whitespace folded, secrets blanked with the CLI's
+ redactor, encoded blobs dropped. Asks are capped at 8 KB, answers at 12 KB (head and tail kept),
+ tool text at 4 KB.
+
+### Keeping it fresh
+
+One code path for backfill and live updates. A pass reads from the session's saved resume point,
+the opening byte of its last turn, which may still be growing. A turn starting or ending in a live
+session queues its pass 1.5 s later. A sweep runs 15 s after boot and every 10 minutes. A file that
+shrank is re-read from the start; an agent that no longer exists is dropped with its sessions.
+Passes run one at a time, read 1 MB chunks and yield every 12 ms.
+
+Measured: the first backfill of 4.4 GB took **4.7 s**, with a longest event-loop stall of 48 ms. A
+sweep with nothing new takes 0.1 s. The index is 11 MB. Resuming from the last turn's offset
+reproduces that turn exactly for all 76 transcripts.
+
+### Keyword, not vectors
+
+SQLite FTS5 with BM25 (`node:sqlite`, already in the managed Node 22.23; no new dependency).
+
+- ⌘P queries are one to three words typed live, and often exact tokens: codenames, files
+ (`swarm_search.dart`), ids (`OH-14`, `#189`). BM25 is exact on those; embeddings blur them.
+- Every word matches as a prefix, so results update while typing. Words are split the way the
+ index splits them, so `swarm_search.dart` is a phrase of its parts.
+- Embeddings would need a local model on every machine, a slower backfill and more storage, and
+ cloud embeddings are out because transcripts hold code and secrets. They stay a later option,
+ as a second retriever fused by rank, if logged misses show vocabulary mismatch.
+
+### Ranking
+
+In the daemon:
+
+1. Sessions with one turn holding every word, ranked by that turn's BM25. Column weights:
+ name 6, ask 4, answer 1.5, tools 1. Each session's first two turns count 1.2×.
+2. Then sessions holding every word, but spread across turns, at half weight.
+3. Relevance relative to the best hit, blended 80/20 with recency (half-life 10 days).
+4. For each hit, a snippet built from the stored turn: the ask first, then the name, the answer,
+ the tools.
+
+In the app, a hit is one more kind of match:
+
+- Name matches rank first, as before.
+- A turn holding every word ranks under name and context matches.
+- Words spread across a conversation come next, and letters scattered across a name come last:
+ real words anywhere are better evidence.
+- Hits from several machines merge by reciprocal rank. Each daemon scores against its own best
+ hit, so a machine's first is treated as another's first, and activity breaks the tie.
+
+The row shows the matched words on its line, fzf-style (`> …`, `$ …`), and the preview says where
+they were found and when. Requests are
+debounced 110 ms and stale answers dropped. The best row stays selected as hits arrive, unless you
+have moved. A machine that cannot answer, because it is offline or runs an older CLI, adds nothing.
+
+### When: "dial last week"
+
+People remember a session by roughly when as often as by what. The app reads a time phrase out of
+the query and sends every machine the same window in this computer's time zone:
+
+- today, yesterday, this or last week or month;
+- N days or weeks ago, a few days ago (loosely: a day, or half a week, either side);
+- a weekday with "on" or "last": "on monday", "last friday". A bare weekday stays a word, so a
+ harness named "Friday deploy" is still found by name.
+
+Only sessions worked on in that window are searched: any turn then, not only the matching one. So
+"the dial one from last week" is a session about the dial that was open last week. The remaining
+words are matched as usual. A time alone ("yesterday") lists what was worked on then, each row
+showing what was asked.
+
+## Measured
+
+### Accuracy on real sessions
+
+Known-item queries sample a turn and take words from it; top-1 means a session where that was
+actually said comes first. Topic queries take two words from each session's auto-title and search
+an index with every name removed, so only what was said can find it.
+
+| Query | n | Top 1 | Top 3 | Top 10 |
+|---|---|---|---|---|
+| Two rare words you typed | 102 | 85% | 92% | 100% |
+| Two words from the answer | 99 | 99% | 100% | 100% |
+| One word you typed | 71 | 52% | 89% | 100% |
+| Typing: 4-letter prefixes of two words | 102 | 73% | 88% | 99% |
+| Topic, from the title, names removed | 69 | 59% | 74% | 84% |
+
+These numbers come from one frozen snapshot. The queries are sampled from the data, so a snapshot
+taken an hour earlier, with the same ranking, read 5 points higher on some rows: treat ±5 as
+noise.
+
+A single word is ambiguous by nature: it usually appears in several sessions, and top-3 is the
+fairer number. Tuning is recorded in the code:
+
+- Counting a session's opening ask for more took topic queries from 46% to 61% top-1.
+- Weighting sessions by how many turns match helped single words but hurt everything else, so it
+ was dropped.
+- Scoring whole sessions as one document was worse on every row, so it was dropped.
+
+### Ranking fix in ⌘P (app only)
+
+On 184 real harnesses:
+
+| Query | Before | After |
+|---|---|---|
+| `hn` | the harness named hn 6th of 166 | 1st |
+| `x post` | an unrelated firmware session first | the X posts session first, 4 matches |
+| `cmd o` | the Cmd O session 3rd | 1st |
+| `store` | 84 matches | 10, all Store sessions |
+| `auth` | 81 matches | 3 |
+
+### Speed
+
+| Index | p50 | p95 | Max | Size |
+|---|---|---|---|---|
+| Real, 1.7k turns | 1.7 ms | 3.4 ms | 6 ms | 11 MB |
+| Synthetic, 102k turns (60× real) | 18 ms | — | 72 ms | 667 MB |
+| Same, with a time window | 15–70 ms | — | 200 ms | |
+
+Getting there:
+
+- Rank inside FTS5 before joining.
+- For a word in more than 30k turns, skip the BM25 sort, which barely discriminates there. Take the
+ 3,000 newest matching turns by turn time and let recency decide. Not the highest rowids: a
+ backfill writes the newest sessions first.
+- The slowest queries left are a time with no words over a wide window, and a very common word
+ inside a window: up to 200 ms at 100k turns.
+- A window's sessions are read once and kept while the window stays the same, keystroke to
+ keystroke.
+- Build snippets from the stored turn: FTS5's `snippet()` re-read a common word's whole posting
+ list for every hit, 250 ms for 30 hits.
+- Prefix indexes for 2–4 letters: dropping to 2 letters saves 25% of the size but makes `the*`
+ 926 ms at 100k turns.
+
+Two gotchas:
+
+- `node:sqlite` binds a JS number as REAL, and FTS5 silently ignores a REAL `rowid =` constraint
+ beside `MATCH`. Every row came back, so every hit had the same snippet. The fix is
+ `CAST(? AS INTEGER)`.
+- FTS5 refuses `bm25()` inside an aggregate, even in a subquery that gets flattened.
+- `rowid IN (…)` beside `MATCH` runs a posting-list lookup per value: 3,000 ids took 72 seconds.
+
+## Tested end to end
+
+The branch's daemon ran on the development Mac in isolation, beside the real one: its own HOME,
+port 28473 and tmux socket, fed a copy of the stopped sessions. Their transcripts were read in
+place, read-only, and nothing was resumed or spawned. Two harnesses drove it:
+
+- **A protocol client that speaks what the app speaks:** local WebSocket, `machine_select`, then
+ `session_search`. Real queries answered in 1–18 ms. Typing "retention cohorts" a key at a time
+ peaked at 7 ms. 60 concurrent requests were all answered, each with its own answer. Hostile input
+ (FTS5 syntax, SQL, quotes, a 5,000-character query, wrong payload types, bad windows) never
+ errored or took the daemon down.
+- **Cmd-P's own code against it** (`desktop/test/session_search_daemon_e2e_test.dart`, opt-in):
+ the app's `WsConn`, catalog and search controller over the real index. 23 cases cover names,
+ conversations, time phrases, prefixes, codenames, file names and "nothing". Each keystroke
+ reaches results in about 130 ms, most of it the 110 ms pause-in-typing debounce, with the best
+ row selected.
+
+What it found, all fixed:
+
+- **Injected messages counted as yours.** Sub-agent hand-backs and harness notices were 6% of what
+ the index held as the person's asks.
+- **A time alone showed agent text.** It showed an agent's report instead of the last thing the
+ person asked then.
+- **Paste markers leaked** into snippets.
+- **Two scattered letters matched everything:** "hn" hit 182 rows. They are now initials only, for
+ harness rows.
+- **Keystrokes got slower** from the stricter letter check. Fixed; 2,000 harnesses are at parity
+ with main.
+- **Command search lost "kb".** Short curated lists (commands, machines, projects, models, Store)
+ keep main's letter matching; command search is identical to main on 30 short queries.
+
+Also by design: a leading `#` in Cmd-P opens projects, so type issue numbers without it ("issue
+189", "pr #368").
+
+## Protocol
+
+`session_search { query, limit, from?, to? }` → `{ hits: [{ agentId, sessionId, engine, turn, at,
+lastAt, field, snippet, together, score }], indexed, pending, tookMs }`. `from` and `to` are epoch
+ms.
+
+- Matched words in the snippet are wrapped in `\u0002 … \u0003`.
+- `session_search` and `session_search_result` are in the E2EE type sets (`cli/src/lib/e2ee/core.ts`,
+ `desktop/lib/e2ee/envelope.dart`). That **re-pins the interop keystone**, so the browser client
+ and the device must re-derive from the new `core.ts`.
+- A Node without `node:sqlite` answers `SEARCH_UNAVAILABLE`.
+
+`harness search <words> [--limit N] [--json]` reads the same index from a shell, and reads the same
+time phrases (`harness search dial last week`). It is read-only: it never migrates or deletes the
+index the daemon owns.
+
+## Not yet
+
+- **Sessions started outside Harness** (plain `claude`, `codex`) could be indexed too, so any past
+ conversation on the machine can be found and resumed.
+- **Untitled sessions** ("Claude harness 9-26 13:41") are now found by their content, but a
+ generated title from the first ask would help the name match as well.
+- **A natural-language "ask" mode** for fuzzy memory ("the one last week where we fixed dial
+ scrolling"): let the daemon's existing LLM router pick from the top keyword and recency
+ candidates. Explicit and slower, never in the type-ahead path.
+- **Local measurement:** log `(query, chosen row, its rank)` on this computer only, never sent
+ anywhere. Its mean reciprocal rank decides whether embeddings are worth adding.
diff --git a/mobile/lib/e2ee/envelope.dart b/mobile/lib/e2ee/envelope.dart
index 48a0765fb..d189527f9 100644
--- a/mobile/lib/e2ee/envelope.dart
+++ b/mobile/lib/e2ee/envelope.dart
@@ -52,6 +52,8 @@ const Set<String> encryptedDownTypes = {
'usage_read',
// The pane colours this client paints with, for the machine's tmux sessions (cli/src/lib/hostTheme.ts).
'theme_set',
+ // What somebody searches their conversations for (cli/src/lib/sessionSearch/).
+ 'session_search',
'device_e2ee_pair',
'e2ee_pairings_list',
'e2ee_pairing_unpair',