From 8ec78631fd31741987fc0e8fc10f818f1cedc735 Mon Sep 17 00:00:00 2001
From: liuedcson <332840681+liuedcson@users.noreply.github.com>
Date: Sat, 17 Oct 2026 12:16:02 +0800
Subject: [PATCH 1/2] feat(coding-agent): add SQLite session search index

Add a derived, rebuildable SQLite index over session JSONL files for
session lists and full-text search, for Web and Desktop hosts. JSONL stays
the only authoritative data: the index only reads session files and can be
deleted at any time.

Index:
- node:sqlite with FTS5 trigram at <agentDir>/index/session-search.v1.db;
  application_id STCX, schema major in the file name, minor in user_version.
- One worker thread owns the connection. Opening never rejects: a foreign
  file, missing SQLite/FTS5, or a dead worker falls back to a JSONL scan
  with session-level hits and status "degraded".
- Incremental sync verifies header and tail hashes before appending;
  rewritten, shrunk, v1, or older-projector files are rebuilt in one
  BEGIN IMMEDIATE transaction with a snapshot check.
- Queries of 3+ characters use FTS with bm25; shorter ones use LIKE over
  the 200 most recent sessions, at most 50 hits.
- Before each search or list, a 30 ms freshness pass re-syncs the 20 most
  recent files and lists directories whose mtime changed, so sessions
  written by other processes appear without notifications.

Integration:
- SessionManager.setFilePersistedListener() reports create/append/rewrite.
- attachSessionIndex() and withSessionIndex() wire managers and factories.
- createSessionSearchService() exposes search.query, sessions.list, and
  index.status without choosing a transport, validating untrusted params.
- `step session-index status | reindex [--full] | clear`.
- The CLI does not open the index during interactive or print sessions.
- The worker ships beside client.js in dist and the Node bundle, and as an
  extra entry point in compiled Bun binaries.

docs/session-index.md describes storage, upgrades, and the steps for a
host to adopt the index.
---
 apps/cli/src/main.ts                          |  13 +-
 packages/coding-agent/docs/docs.json          |   4 +
 packages/coding-agent/docs/index.md           |   1 +
 packages/coding-agent/docs/session-format.md  |   1 +
 packages/coding-agent/docs/session-index.md   | 137 +++
 packages/coding-agent/package.json            |   2 +-
 .../src/core/session-index/attach.ts          |  30 +
 .../src/core/session-index/client.ts          | 370 ++++++++
 .../src/core/session-index/command.ts         |  92 ++
 .../src/core/session-index/fallback.ts        | 114 +++
 .../src/core/session-index/index.ts           |  24 +
 .../src/core/session-index/projector.ts       | 114 +++
 .../src/core/session-index/reader.ts          | 206 ++++
 .../src/core/session-index/schema.ts          | 331 +++++++
 .../session-index/session-index-worker.ts     | 230 +++++
 .../src/core/session-index/store.ts           | 890 ++++++++++++++++++
 .../src/core/session-index/types.ts           | 102 ++
 .../coding-agent/src/core/session-manager.ts  | 112 +--
 .../coding-agent/src/core/session-summary.ts  | 108 +++
 packages/coding-agent/src/index.ts            |  18 +-
 .../src/server/session-search-service.ts      | 181 ++++
 .../test/session-index/client.test.ts         | 189 ++++
 .../test/session-index/service.test.ts        | 121 +++
 .../test/session-index/store.test.ts          | 395 ++++++++
 scripts/build-binaries.sh                     |   4 +-
 scripts/build-coding-agent-bundle.mjs         |  16 +-
 26 files changed, 3730 insertions(+), 75 deletions(-)
 create mode 100644 packages/coding-agent/docs/session-index.md
 create mode 100644 packages/coding-agent/src/core/session-index/attach.ts
 create mode 100644 packages/coding-agent/src/core/session-index/client.ts
 create mode 100644 packages/coding-agent/src/core/session-index/command.ts
 create mode 100644 packages/coding-agent/src/core/session-index/fallback.ts
 create mode 100644 packages/coding-agent/src/core/session-index/index.ts
 create mode 100644 packages/coding-agent/src/core/session-index/projector.ts
 create mode 100644 packages/coding-agent/src/core/session-index/reader.ts
 create mode 100644 packages/coding-agent/src/core/session-index/schema.ts
 create mode 100644 packages/coding-agent/src/core/session-index/session-index-worker.ts
 create mode 100644 packages/coding-agent/src/core/session-index/store.ts
 create mode 100644 packages/coding-agent/src/core/session-index/types.ts
 create mode 100644 packages/coding-agent/src/core/session-summary.ts
 create mode 100644 packages/coding-agent/src/server/session-search-service.ts
 create mode 100644 packages/coding-agent/test/session-index/client.test.ts
 create mode 100644 packages/coding-agent/test/session-index/service.test.ts
 create mode 100644 packages/coding-agent/test/session-index/store.test.ts

diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts
index afef34e7..d3dc737b 100644
--- a/apps/cli/src/main.ts
+++ b/apps/cli/src/main.ts
@@ -7,7 +7,7 @@
 // very first side effect (before the coding-agent barrel is evaluated) so
 // config.ts resolves the Step storage namespace regardless of launcher name.
 import "#bootstrap/environment";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 import {
 	ambiguousPluginServerNames,
@@ -30,6 +30,7 @@ import {
 	getStepAuthPath,
 	getStepDefaultTheme,
 	getStepLoginStatus,
+	getStepSessionDirOverride,
 	hasConfiguredStepCodeCredential,
 	installProcessStderrDevLogCapture,
 	isStepConfigCommand,
@@ -60,6 +61,7 @@ import {
 	resolveStepStorageRoot,
 	restoreStdout,
 	runFeedbackCommand,
+	runSessionIndexCommand,
 	runStepConfigCommand,
 	runStepLogin,
 	runStepMcpImportPrompt,
@@ -353,6 +355,7 @@ const isTopLevelLogin = topLevelStepCommand === "login";
 const isTopLevelLoginStatus = isTopLevelLogin && process.argv[3] === "status";
 const isTopLevelLogout = topLevelStepCommand === "logout";
 const isTopLevelFeedback = topLevelStepCommand === "feedback";
+const isTopLevelSessionIndex = topLevelStepCommand === "session-index";
 const topLevelAuthHelp = process.argv.slice(3).some((arg) => arg === "--help" || arg === "-h");
 
 let telemetryExitReason: "normal" | "error" = "normal";
@@ -659,6 +662,14 @@ try {
 				}
 			}
 		}
+	} else if (isTopLevelSessionIndex) {
+		const sessionDirOverride = getStepSessionDirOverride(process.env);
+		const exitCode = await runSessionIndexCommand(process.argv.slice(3), {
+			agentDir: resolveStepAgentDir(),
+			...(sessionDirOverride ? { extraRoots: [resolve(sessionDirOverride)] } : {}),
+		});
+		if (exitCode !== 0) process.exitCode = exitCode;
+		forceOneShotExit = true;
 	} else if (isTopLevelFeedback) {
 		const feedbackSettingsManager =
 			currentStepSettingsManager ?? createStepSettingsManager(process.cwd(), resolveStepAgentDir());
diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json
index bbc9e74b..d4bbab02 100644
--- a/packages/coding-agent/docs/docs.json
+++ b/packages/coding-agent/docs/docs.json
@@ -84,6 +84,10 @@
         {
           "title": "Session Format",
           "path": "session-format.md"
+        },
+        {
+          "title": "Session Index",
+          "path": "session-index.md"
         }
       ]
     },
diff --git a/packages/coding-agent/docs/index.md b/packages/coding-agent/docs/index.md
index 1ba79715..8b1c444e 100644
--- a/packages/coding-agent/docs/index.md
+++ b/packages/coding-agent/docs/index.md
@@ -66,6 +66,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 - [Environment variables](environment-variables.md) - Step process configuration and session metadata available to bash tools.
 - [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
+- [Session index](session-index.md) - derived SQLite index for session lists and full-text search.
 
 ## Platform setup
 
diff --git a/packages/coding-agent/docs/session-format.md b/packages/coding-agent/docs/session-format.md
index 8a97a1d9..2622b877 100644
--- a/packages/coding-agent/docs/session-format.md
+++ b/packages/coding-agent/docs/session-format.md
@@ -438,3 +438,4 @@ Key methods for working with sessions programmatically.
 - `getSessionId()` - Session UUID
 - `getSessionFile()` - Session file path (undefined for in-memory)
 - `isPersisted()` - Whether session is saved to disk
+- `setFilePersistedListener(listener)` - Observe `create` / `append` / `rewrite` writes, e.g. for the [session index](session-index.md)
diff --git a/packages/coding-agent/docs/session-index.md b/packages/coding-agent/docs/session-index.md
new file mode 100644
index 00000000..d08c72ca
--- /dev/null
+++ b/packages/coding-agent/docs/session-index.md
@@ -0,0 +1,137 @@
+# Session index
+
+The session index is a derived SQLite database for session lists and full-text search. Session JSONL files stay the only authoritative data: the index only reads them, and deleting it loses nothing but the time to rebuild it.
+
+## Storage and lifecycle
+
+| Item | Value |
+| --- | --- |
+| Location | `<agentDir>/index/session-search.v1.db` (plus `-wal` / `-shm`); the schema major is part of the name |
+| Engine | Built-in `node:sqlite` with FTS5 `trigram`; no extra dependency |
+| Owner | One worker thread per process holds the only connection. The CLI does not open the index during interactive or print sessions; only `step session-index` and hosts that call `openSessionIndex()` do |
+| Roots | `<agentDir>/sessions` and any directory added with `addRoot()` or found holding a persisted file |
+| Ownership check | `PRAGMA application_id` (`STCX`); a file without our id is never modified and the index runs degraded |
+| Damaged file | Unreadable, missing tables, or `schema_major` disagreeing with the name: moved aside as `session-search.v1.db.corrupt-<time>` (one kept) and rebuilt |
+| Schema upgrade | Incompatible layout: new file name, the old file is left alone. Older minor (`user_version`): migrate in place. Newer minor: use known columns, no migration. Tokenizer change: rebuild FTS tables from `entries` without rereading JSONL |
+| Projection change | `projector_version` per source; older sources are reprojected on the next reconcile. Rows from a newer projector are left as is, and an older binary appending to one marks it for reprojection |
+| Metadata | `index_meta` holds `schema_major`, `fts_definition`, `projector_version`, `backfill_state`, `last_reconcile_at` |
+
+## What is indexed
+
+| Source | Indexed text |
+| --- | --- |
+| `message` with role `user` / `assistant` | Text blocks, capped at 64 KiB per entry |
+| `compaction`, `branch_summary` | `summary` |
+| `custom_message` with `display: true` | Text content |
+| `label` | Label text |
+| `session_info` and the first user message | Session title search (`entryId` is `null`) |
+| Tool results, bash output, hidden custom messages, extension entries | Not indexed |
+
+v1 files without entry ids are indexed with ids `L<physical line>`. Files are migrated to v3 in memory only.
+
+## Updates
+
+| Trigger | Behavior |
+| --- | --- |
+| `notifyPersisted({ path, kind })` | Debounced per path (200 ms), then the file is synced |
+| Append | Reads from the stored offset after checking the header and last-line hashes |
+| Header or tail changed, file shrank, v1 file | Session rows are deleted and rebuilt in one transaction |
+| Empty file or incomplete header | Marked `pending`; existing rows stay searchable |
+| Unfinished final line | Left for the next sync |
+| Unparseable complete line | Skipped like `SessionManager` does; the count is kept in `sources.error` and the source stays `ok` |
+| Reconcile (open, `reindex`) | Lists every root, syncs new or changed files newest first, and deletes rows for files that are gone from a root that was listed successfully |
+| Before each search or list | Freshness pass with a 30 ms budget: re-syncs the 20 most recently modified known files, then lists only directories whose mtime moved since the last reconcile to pick up files written by other processes. A pass cut short by the budget schedules a background reconcile. Deletions wait for the next reconcile |
+
+Writes check the source row they started from inside `BEGIN IMMEDIATE`; when another process changed it meanwhile the sync is retried once.
+
+## Search
+
+| Query | Path |
+| --- | --- |
+| Every token has 3+ characters | FTS5 `MATCH` of quoted phrases, ordered by bm25 |
+| Any token is shorter | `LIKE` on `entries.text` within the 200 most recently modified matching sessions, newest first, at most 50 hits. Without `cwd` or `since`, only the last 30 days are searched |
+
+Snippets wrap matches in `SNIPPET_MATCH_START` / `SNIPPET_MATCH_END`. Results carry `coverage` so a caller can tell a partial backfill from a complete answer.
+
+## Degraded mode
+
+When `node:sqlite`, FTS5 trigram, the database, or the worker is unavailable, `openSessionIndex()` still resolves. Searches and lists scan JSONL on each call, hits are session-level only, and `status()` returns `state: "degraded"` with the reason. A worker that fails after opening switches the same object to this mode.
+
+## API
+
+```ts
+import {
+  attachSessionIndex,
+  createStepSessionManagerFactory,
+  openSessionIndex,
+  withSessionIndex,
+} from "@step-harness/coding-agent";
+
+const index = await openSessionIndex({ agentDir });
+attachSessionIndex(sessionManager, index); // one manager
+const factory = withSessionIndex(createStepSessionManagerFactory(agentDir), index); // every manager it builds
+
+for await (const batch of index.search({ text: "migration", cwd, limit: 20 })) {
+  console.log(batch.coverage, batch.hits);
+}
+const page = await index.listSessions({ cwd, limit: 50 });
+await index.close();
+```
+
+`SessionManager.setFilePersistedListener()` reports `create`, `append`, and `rewrite` after each successful write. Listener errors are ignored; the next reconcile repairs any missed update. `attachSessionIndex()` sets that listener; `withSessionIndex()` wraps a `SessionManagerFactory` so created, opened, forked, and resumed managers are attached (in-memory managers have no file and are left alone).
+
+## Host methods
+
+`createSessionSearchService(index)` exposes the index to a Web or Desktop host without choosing a transport. `call(method, params, signal)` takes untrusted JSON params, validates them, and yields JSON-safe results; the host owns framing and the index lifetime.
+
+| Method | Params | Result |
+| --- | --- | --- |
+| `search.query` | `q` (1–500 chars), `cwd?` (absolute), `entryTypes?`, `limit?` (1–100, default 20), `since?` (epoch ms) | One or more `{ hits, coverage }` batches |
+| `sessions.list` | `cwd?`, `limit?` (1–200, default 50), `cursor?` | `{ sessions, nextCursor? }`; `created` / `modified` are epoch ms |
+| `index.status` | none | `SessionIndexStatus` |
+
+Invalid requests throw `SessionSearchRequestError` with `code` `unknown_method` or `invalid_params` before the index is queried.
+
+## Integrating a host
+
+A Web or Desktop host that wants session lists and search follows these steps. Nothing here needs changes to `SessionManager`, the JSONL format, or the CLI.
+
+| Step | What to do | Notes |
+| --- | --- | --- |
+| 1. Open once | At host startup: `openSessionIndex({ agentDir, roots })`. Roots are `defaultSessionIndexRoots(agentDir)` plus any configured session directory (`STEP_CODING_AGENT_SESSION_DIR`, `--session-dir`) as `kind: "custom"` | Never rejects. Backfill runs in the worker; the host stays responsive. Keep one index per host process and reuse it |
+| 2. Wire writes | Pass `withSessionIndex(factory, index)` as the runtime's `sessionManagerFactory`; call `attachSessionIndex(manager, index)` for a manager built outside the factory (the initial session) | Writes from this process are indexed within the 200 ms debounce. Writes from CLI processes are found by the freshness pass before each query |
+| 3. Expose methods | Route the transport's requests to `createSessionSearchService(index).call(method, params, signal)`. Map `SessionSearchRequestError.code` to the transport's error codes; abort the signal when a client cancels or retypes | Results are JSON-safe; stream each `search.query` batch as it arrives |
+| 4. Show progress | Poll `index.status`: `backfilling` with `indexed / total` drives a progress indicator; `degraded` with `degradedReason` means results come from a JSONL scan (session-level hits only). Each search batch also carries `coverage` | `reindex()` yields progress for an explicit rebuild |
+| 5. Shut down | `await index.close()` | Flushes pending notifications and stops the worker |
+
+Constraints for hosts:
+
+- Treat the database as private to the index. Do not open it, write it, or copy rows elsewhere; it may be deleted and rebuilt at any time.
+- Session data changes only through `SessionManager`; the index never writes JSONL.
+- Several processes may open the same index safely (each sync runs in `BEGIN IMMEDIATE` and rechecks its source row), but each costs a worker and a backfill pass. Prefer one long-lived host per agent directory.
+- Packaged builds must ship the worker: `session-index-worker.js` beside `client.js` for `dist/` and the Node bundle, and `src/core/session-index/session-index-worker.ts` as an extra entry point for `bun build --compile`. Without it, the index runs degraded.
+- Requires `node:sqlite` with FTS5 `trigram` (Node.js `>=22.19.0`, or the compiled Bun binary).
+
+Source map:
+
+| Path | Role |
+| --- | --- |
+| `src/core/session-index/client.ts` | `openSessionIndex`, worker RPC, degraded fallback switch |
+| `src/core/session-index/session-index-worker.ts` | Worker that owns the connection; request handling, backfill, freshness pass |
+| `src/core/session-index/store.ts` | Sync, reconcile, freshness pass, search, list |
+| `src/core/session-index/schema.ts` | DDL, open / inspect / upgrade, versions, `getSessionIndexPath` |
+| `src/core/session-index/reader.ts`, `projector.ts` | Read-only JSONL access and entry projection |
+| `src/core/session-index/fallback.ts` | JSONL scan used when the index is degraded |
+| `src/core/session-index/attach.ts` | `attachSessionIndex`, `withSessionIndex` |
+| `src/server/session-search-service.ts` | Transport-neutral host methods and parameter validation |
+| `test/session-index/` | Store, client / worker, and service tests |
+
+## CLI
+
+```bash
+step session-index status [--json]
+step session-index reindex [--full] [--json]
+step session-index clear
+```
+
+`STEP_CODING_AGENT_SESSION_DIR` is included as an extra root when set.
diff --git a/packages/coding-agent/package.json b/packages/coding-agent/package.json
index ff9262e9..c79cb302 100644
--- a/packages/coding-agent/package.json
+++ b/packages/coding-agent/package.json
@@ -28,7 +28,7 @@
 		"clean": "shx rm -rf dist",
 		"build": "npm run build:unbundled && node ../../scripts/build-coding-agent-bundle.mjs",
 		"build:unbundled": "tsgo -p tsconfig.build.json && npm run copy-assets",
-		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../providers run build && npm --prefix ../agent-core run build && npm run build && bun build --compile --no-compile-autoload-bunfig --env=STEPCODE_BUILD_* ../../apps/cli/src/bun/stepcode.ts ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts --outfile dist/step-bin && npm run copy-binary-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../providers run build && npm --prefix ../agent-core run build && npm run build && bun build --compile --no-compile-autoload-bunfig --env=STEPCODE_BUILD_* ../../apps/cli/src/bun/stepcode.ts ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts ./src/core/session-index/session-index-worker.ts --outfile dist/step-bin && npm run copy-binary-assets",
 		"copy-assets": "shx mkdir -p dist/theme && shx cp src/theme/*.json dist/theme/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
 		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx mkdir -p dist/theme && shx cp src/theme/*.json dist/theme/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && node ../../scripts/copy-photon-wasm.mjs dist",
 		"test": "vitest --run",
diff --git a/packages/coding-agent/src/core/session-index/attach.ts b/packages/coding-agent/src/core/session-index/attach.ts
new file mode 100644
index 00000000..ebb878d4
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/attach.ts
@@ -0,0 +1,30 @@
+import type { SessionManager } from "../session-manager.ts";
+import type { SessionManagerFactory } from "../session-manager-factory.ts";
+import type { SessionIndex } from "./types.ts";
+
+type PersistedSink = Pick<SessionIndex, "notifyPersisted">;
+
+/**
+ * Forward a manager's file writes to the index. The listener only enqueues a
+ * debounced sync, so a slow or degraded index never delays persistence.
+ * Replaces any listener already set on the manager.
+ */
+export function attachSessionIndex(manager: SessionManager, index: PersistedSink): SessionManager {
+	manager.setFilePersistedListener((event) => index.notifyPersisted(event));
+	return manager;
+}
+
+/** Wrap a factory so every manager it creates, opens, or forks reports writes to the index. */
+export function withSessionIndex(factory: SessionManagerFactory, index: PersistedSink): SessionManagerFactory {
+	const attach = (manager: SessionManager): SessionManager => attachSessionIndex(manager, index);
+	return {
+		create: (cwd, sessionDir, options) => attach(factory.create(cwd, sessionDir, options)),
+		open: (path, sessionDir, cwdOverride) => attach(factory.open(path, sessionDir, cwdOverride)),
+		inMemory: (cwd, options) => factory.inMemory(cwd, options),
+		forkFrom: (sourcePath, targetCwd, sessionDir, options) =>
+			attach(factory.forkFrom(sourcePath, targetCwd, sessionDir, options)),
+		continueRecent: (cwd, sessionDir) => attach(factory.continueRecent(cwd, sessionDir)),
+		list: factory.list.bind(factory),
+		listAll: factory.listAll.bind(factory),
+	};
+}
diff --git a/packages/coding-agent/src/core/session-index/client.ts b/packages/coding-agent/src/core/session-index/client.ts
new file mode 100644
index 00000000..47ac0f10
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/client.ts
@@ -0,0 +1,370 @@
+import { join } from "node:path";
+import { Worker } from "node:worker_threads";
+import { JsonlScanSessionIndex } from "./fallback.ts";
+import { getSessionIndexPath } from "./schema.ts";
+import type { SessionIndexWorkerData, WorkerMessage, WorkerRequest } from "./session-index-worker.ts";
+import type {
+	ReindexOptions,
+	ReindexProgress,
+	SessionFilePersistedEvent,
+	SessionIndex,
+	SessionIndexHitBatch,
+	SessionIndexQuery,
+	SessionIndexStatus,
+	SessionListPage,
+	SessionListQuery,
+} from "./types.ts";
+
+export interface SessionIndexRoot {
+	path: string;
+	kind: "default" | "custom";
+}
+
+export interface OpenSessionIndexOptions {
+	/** Agent directory; the index lives at `<agentDir>/index/session-search.v1.db`. */
+	agentDir: string;
+	/** Session roots to index. Defaults to `<agentDir>/sessions`. */
+	roots?: readonly SessionIndexRoot[];
+	/** Override the database path, e.g. for tests. */
+	dbPath?: string;
+	/** Reconcile all roots in the background after opening. Defaults to true. */
+	backfill?: boolean;
+	/** Coalesce persisted notifications per path. Defaults to 200ms. */
+	debounceMs?: number;
+	/** Fall back to scanning when the worker is not ready in time. Defaults to 5s. */
+	readyTimeoutMs?: number;
+}
+
+const DEFAULT_DEBOUNCE_MS = 200;
+const DEFAULT_READY_TIMEOUT_MS = 5000;
+const CLOSE_TIMEOUT_MS = 2000;
+
+function resolveWorkerEntry(): string | URL {
+	// Compiled Bun binaries embed the worker under its source path (see scripts/build-binaries.sh).
+	if (typeof process.versions.bun === "string") return "./src/core/session-index/session-index-worker.ts";
+	return new URL(
+		import.meta.url.endsWith(".ts") ? "./session-index-worker.ts" : "./session-index-worker.js",
+		import.meta.url,
+	);
+}
+
+type Pending = {
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	onProgress?: (indexed: number, total: number) => void;
+};
+
+/** Thin RPC over the worker. Rejects every pending call once the worker fails. */
+class WorkerConnection {
+	private readonly worker: Worker;
+	private readonly pending = new Map<number, Pending>();
+	private nextId = 1;
+	private failure: Error | undefined;
+	onFailure: ((reason: string) => void) | undefined;
+
+	private constructor(worker: Worker) {
+		this.worker = worker;
+		worker.on("message", (message: WorkerMessage) => this.receive(message));
+		worker.on("error", (error) => this.fail(error.message));
+		worker.on("exit", () => this.fail("Session index worker exited."));
+	}
+
+	static open(data: SessionIndexWorkerData, timeoutMs: number): Promise<WorkerConnection> {
+		return new Promise((resolve, reject) => {
+			let worker: Worker;
+			try {
+				worker = new Worker(resolveWorkerEntry(), { workerData: data });
+			} catch (error) {
+				reject(error instanceof Error ? error : new Error(String(error)));
+				return;
+			}
+			const timer = setTimeout(() => {
+				cleanup();
+				void worker.terminate();
+				reject(new Error("Session index worker did not start in time."));
+			}, timeoutMs);
+			const onMessage = (message: WorkerMessage): void => {
+				if (message.type === "ready") {
+					cleanup();
+					resolve(new WorkerConnection(worker));
+				} else if (message.type === "degraded") {
+					cleanup();
+					void worker.terminate();
+					reject(new Error(message.reason));
+				}
+			};
+			const onError = (error: Error): void => {
+				cleanup();
+				reject(error);
+			};
+			const onExit = (): void => {
+				cleanup();
+				reject(new Error("Session index worker exited during startup."));
+			};
+			const cleanup = (): void => {
+				clearTimeout(timer);
+				worker.off("message", onMessage);
+				worker.off("error", onError);
+				worker.off("exit", onExit);
+			};
+			worker.on("message", onMessage);
+			worker.once("error", onError);
+			worker.once("exit", onExit);
+		});
+	}
+
+	private receive(message: WorkerMessage): void {
+		if (message.type === "degraded") {
+			this.fail(message.reason);
+			return;
+		}
+		if (message.type === "ready") return;
+		const pending = this.pending.get(message.id);
+		if (!pending) return;
+		if (message.type === "progress") {
+			pending.onProgress?.(message.indexed, message.total);
+			return;
+		}
+		this.pending.delete(message.id);
+		if (message.type === "result") pending.resolve(message.result);
+		else pending.reject(new Error(message.error));
+	}
+
+	private fail(reason: string): void {
+		if (this.failure) return;
+		this.failure = new Error(reason);
+		for (const pending of this.pending.values()) pending.reject(this.failure);
+		this.pending.clear();
+		void this.worker.terminate();
+		this.onFailure?.(reason);
+	}
+
+	get failed(): boolean {
+		return this.failure !== undefined;
+	}
+
+	call(
+		request: DistributiveOmit<WorkerRequest, "id">,
+		onProgress?: Pending["onProgress"],
+	): { id: number; result: Promise<unknown> } {
+		const id = this.nextId++;
+		if (this.failure) return { id, result: Promise.reject(this.failure) };
+		const result = new Promise<unknown>((resolve, reject) => {
+			this.pending.set(id, { resolve, reject, onProgress });
+		});
+		this.worker.postMessage({ ...request, id });
+		return { id, result };
+	}
+
+	async close(): Promise<void> {
+		if (this.failure) return;
+		// Stop the exit listener from reporting the requested shutdown as a failure.
+		this.failure = new Error("Session index closed.");
+		const id = this.nextId++;
+		const closed = new Promise<void>((resolve) => {
+			const timer = setTimeout(resolve, CLOSE_TIMEOUT_MS);
+			this.worker.once("exit", () => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+		this.worker.postMessage({ op: "close", id });
+		await closed;
+		await this.worker.terminate();
+	}
+}
+
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
+/**
+ * Main-thread SessionIndex backed by the worker. Switches permanently to the
+ * JSONL scan when the worker fails; callers keep the same object.
+ */
+class SessionIndexClient implements SessionIndex {
+	private connection: WorkerConnection | undefined;
+	private fallback: JsonlScanSessionIndex | undefined;
+	private readonly roots: string[];
+	private readonly debounceMs: number;
+	private readonly timers = new Map<string, NodeJS.Timeout>();
+	private closed = false;
+
+	constructor(connection: WorkerConnection | undefined, roots: string[], debounceMs: number, reason?: string) {
+		this.roots = roots;
+		this.debounceMs = debounceMs;
+		if (connection) {
+			this.connection = connection;
+			connection.onFailure = (failure) => this.degrade(failure);
+		} else {
+			this.fallback = new JsonlScanSessionIndex(roots, reason ?? "Session index unavailable.");
+		}
+	}
+
+	private degrade(reason: string): void {
+		this.connection = undefined;
+		this.fallback ??= new JsonlScanSessionIndex(this.roots, reason);
+	}
+
+	private async withWorker<T>(
+		run: (connection: WorkerConnection) => Promise<T>,
+		fallback: (index: JsonlScanSessionIndex) => Promise<T>,
+	): Promise<T> {
+		const connection = this.connection;
+		if (connection) {
+			try {
+				return await run(connection);
+			} catch (error) {
+				if (!connection.failed) throw error;
+			}
+		}
+		return fallback(this.fallback ?? new JsonlScanSessionIndex(this.roots, "Session index unavailable."));
+	}
+
+	async *search(query: SessionIndexQuery, signal?: AbortSignal): AsyncIterable<SessionIndexHitBatch> {
+		if (signal?.aborted) return;
+		const connection = this.connection;
+		if (connection) {
+			try {
+				const batch = (await connection.call({ op: "search", query }).result) as SessionIndexHitBatch;
+				if (!signal?.aborted) yield batch;
+				return;
+			} catch (error) {
+				if (!connection.failed) throw error;
+			}
+		}
+		yield* (this.fallback as JsonlScanSessionIndex).search(query, signal);
+	}
+
+	listSessions(query: SessionListQuery, signal?: AbortSignal): Promise<SessionListPage> {
+		return this.withWorker(
+			async (connection) => (await connection.call({ op: "list", query }).result) as SessionListPage,
+			(index) => index.listSessions(query, signal),
+		);
+	}
+
+	status(): Promise<SessionIndexStatus> {
+		return this.withWorker(
+			async (connection) => (await connection.call({ op: "status" }).result) as SessionIndexStatus,
+			(index) => index.status(),
+		);
+	}
+
+	notifyPersisted(event: SessionFilePersistedEvent): void {
+		if (this.closed || !this.connection) return;
+		const previous = this.timers.get(event.path);
+		if (previous) clearTimeout(previous);
+		const timer = setTimeout(() => {
+			this.timers.delete(event.path);
+			// Sync failures are recovered by the next reconcile; the session write already succeeded.
+			this.connection?.call({ op: "sync", paths: [event.path] }).result.catch(() => {});
+		}, this.debounceMs);
+		timer.unref?.();
+		this.timers.set(event.path, timer);
+	}
+
+	async addRoot(dir: string): Promise<void> {
+		if (!this.roots.includes(dir)) this.roots.push(dir);
+		await this.withWorker(
+			async (connection) => {
+				await connection.call({ op: "addRoot", path: dir }).result;
+			},
+			(index) => index.addRoot(dir),
+		);
+	}
+
+	async *reindex(options: ReindexOptions = {}): AsyncIterable<ReindexProgress> {
+		const connection = this.connection;
+		if (!connection) {
+			yield* (this.fallback as JsonlScanSessionIndex).reindex();
+			return;
+		}
+		const queue: ReindexProgress[] = [];
+		let wake: (() => void) | undefined;
+		const { id, result } = connection.call({ op: "reindex", full: options.full === true }, (indexed, total) => {
+			queue.push({ indexed, total, done: false });
+			wake?.();
+		});
+		const abort = (): void => {
+			connection.call({ op: "cancel", target: id }).result.catch(() => {});
+			wake?.();
+		};
+		options.signal?.addEventListener("abort", abort, { once: true });
+		let finished = false;
+		let failure: unknown;
+		let final: SessionIndexStatus | undefined;
+		result.then(
+			(status) => {
+				final = status as SessionIndexStatus;
+				finished = true;
+				wake?.();
+			},
+			(error: unknown) => {
+				failure = error;
+				finished = true;
+				wake?.();
+			},
+		);
+		try {
+			while (true) {
+				while (queue.length > 0) yield queue.shift() as ReindexProgress;
+				if (options.signal?.aborted) return;
+				if (finished) break;
+				await new Promise<void>((resolve) => {
+					wake = resolve;
+				});
+				wake = undefined;
+			}
+			if (failure) throw failure;
+			if (final) yield { indexed: final.indexed, total: final.total, done: true };
+		} finally {
+			options.signal?.removeEventListener("abort", abort);
+		}
+	}
+
+	async close(): Promise<void> {
+		if (this.closed) return;
+		this.closed = true;
+		for (const timer of this.timers.values()) clearTimeout(timer);
+		const pathsToFlush = [...this.timers.keys()];
+		this.timers.clear();
+		const connection = this.connection;
+		this.connection = undefined;
+		if (!connection) return;
+		if (pathsToFlush.length > 0) {
+			await connection.call({ op: "sync", paths: pathsToFlush }).result.catch(() => {
+				// Unflushed paths are picked up by the next reconcile.
+			});
+		}
+		await connection.close();
+	}
+}
+
+export function defaultSessionIndexRoots(agentDir: string): SessionIndexRoot[] {
+	return [{ path: join(agentDir, "sessions"), kind: "default" }];
+}
+
+/**
+ * Open the session index. Never rejects for index problems: when SQLite,
+ * FTS5 trigram, or the worker is unavailable the returned index scans JSONL
+ * and `status()` reports `degraded` with the reason.
+ */
+export async function openSessionIndex(options: OpenSessionIndexOptions): Promise<SessionIndex> {
+	const roots = [...(options.roots ?? defaultSessionIndexRoots(options.agentDir))];
+	const data: SessionIndexWorkerData = {
+		dbPath: options.dbPath ?? getSessionIndexPath(options.agentDir),
+		roots,
+		backfill: options.backfill ?? true,
+	};
+	const rootPaths = roots.map((root) => root.path);
+	const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+	try {
+		const connection = await WorkerConnection.open(data, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+		return new SessionIndexClient(connection, rootPaths, debounceMs);
+	} catch (error) {
+		return new SessionIndexClient(
+			undefined,
+			rootPaths,
+			debounceMs,
+			error instanceof Error ? error.message : String(error),
+		);
+	}
+}
diff --git a/packages/coding-agent/src/core/session-index/command.ts b/packages/coding-agent/src/core/session-index/command.ts
new file mode 100644
index 00000000..0a9af267
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/command.ts
@@ -0,0 +1,92 @@
+import { existsSync } from "node:fs";
+import { defaultSessionIndexRoots, openSessionIndex, type SessionIndexRoot } from "./client.ts";
+import { deleteIndexDatabase, getSessionIndexPath } from "./schema.ts";
+
+export interface SessionIndexCommandOptions {
+	agentDir: string;
+	/** Session roots in addition to `<agentDir>/sessions`, e.g. a configured session directory. */
+	extraRoots?: readonly string[];
+	stdout?: (text: string) => void;
+	stderr?: (text: string) => void;
+}
+
+const USAGE = `Usage: step session-index <command> [options]
+
+Manage the local session search index. Session files are never modified;
+the index can be deleted and rebuilt at any time.
+
+Commands:
+  status            Show index state and coverage
+  reindex [--full]  Index new and changed sessions (--full rebuilds everything)
+  clear             Delete the index database
+
+Options:
+  --json            Print machine-readable output (status, reindex)
+`;
+
+/** `step session-index status | reindex | clear`. Returns the process exit code. */
+export async function runSessionIndexCommand(
+	args: readonly string[],
+	options: SessionIndexCommandOptions,
+): Promise<number> {
+	const stdout = options.stdout ?? ((text: string) => process.stdout.write(text));
+	const stderr = options.stderr ?? ((text: string) => process.stderr.write(text));
+	const [command, ...rest] = args;
+	if (command === undefined || command === "--help" || command === "-h" || rest.includes("--help")) {
+		stdout(USAGE);
+		return command === undefined ? 1 : 0;
+	}
+	const json = rest.includes("--json");
+	const allowed = command === "reindex" ? ["--json", "--full"] : command === "status" ? ["--json"] : [];
+	const unknown = rest.find((arg) => !allowed.includes(arg));
+	if (unknown !== undefined) {
+		stderr(`Unknown option "${unknown}" for "session-index ${command}".\n`);
+		return 1;
+	}
+	const dbPath = getSessionIndexPath(options.agentDir);
+
+	if (command === "clear") {
+		const existed = existsSync(dbPath);
+		deleteIndexDatabase(dbPath);
+		stdout(existed ? `Deleted ${dbPath}\n` : `No session index at ${dbPath}\n`);
+		return 0;
+	}
+	if (command !== "status" && command !== "reindex") {
+		stderr(`Unknown command "${command}".\n\n${USAGE}`);
+		return 1;
+	}
+
+	const roots: SessionIndexRoot[] = [
+		...defaultSessionIndexRoots(options.agentDir),
+		...(options.extraRoots ?? []).map((path) => ({ path, kind: "custom" as const })),
+	];
+	const index = await openSessionIndex({ agentDir: options.agentDir, roots, backfill: false });
+	try {
+		if (command === "reindex") {
+			const status = await index.status();
+			if (status.state === "degraded") {
+				stderr(`Session index unavailable: ${status.degradedReason ?? "unknown reason"}\n`);
+				return 1;
+			}
+			let lastReport = 0;
+			for await (const progress of index.reindex({ full: rest.includes("--full") })) {
+				if (json || (!progress.done && Date.now() - lastReport < 500)) continue;
+				lastReport = Date.now();
+				stderr(`Indexed ${progress.indexed}/${progress.total} sessions${progress.done ? "" : "..."}\n`);
+			}
+		}
+		const status = await index.status();
+		if (json) {
+			stdout(`${JSON.stringify(status)}\n`);
+		} else if (status.state === "degraded") {
+			stdout(`State: degraded (searches scan session files)\nReason: ${status.degradedReason ?? "unknown"}\n`);
+		} else {
+			stdout(
+				`State: ${status.indexed < status.total ? "incomplete" : "ready"}\nIndexed: ${status.indexed}/${status.total} sessions\nPending: ${status.pending}\nErrors: ${status.errors}\nDatabase: ${dbPath}\n`,
+			);
+		}
+		return status.state === "degraded" && command === "reindex" ? 1 : 0;
+	} finally {
+		await index.close();
+	}
+}
diff --git a/packages/coding-agent/src/core/session-index/fallback.ts b/packages/coding-agent/src/core/session-index/fallback.ts
new file mode 100644
index 00000000..170cdf03
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/fallback.ts
@@ -0,0 +1,114 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { type SessionInfo, SessionManager } from "../session-manager.ts";
+import { textSnippet } from "./store.ts";
+import type {
+	ReindexProgress,
+	SessionIndex,
+	SessionIndexHitBatch,
+	SessionIndexQuery,
+	SessionIndexStatus,
+	SessionListPage,
+	SessionListQuery,
+} from "./types.ts";
+
+/**
+ * Used when the index worker is unavailable (no FTS5 trigram, foreign or
+ * unwritable database, worker crash). Scans JSONL on each call and returns
+ * only session-level hits (entryId null); it never writes anything.
+ */
+export class JsonlScanSessionIndex implements SessionIndex {
+	private readonly roots: string[];
+	private readonly reason: string;
+
+	constructor(roots: readonly string[], reason: string) {
+		this.roots = [...roots];
+		this.reason = reason;
+	}
+
+	private async loadSessions(signal?: AbortSignal): Promise<SessionInfo[]> {
+		const directories = new Set<string>();
+		for (const root of this.roots) {
+			directories.add(root);
+			try {
+				for (const entry of await readdir(root, { withFileTypes: true })) {
+					if (entry.isDirectory() || entry.isSymbolicLink()) directories.add(join(root, entry.name));
+				}
+			} catch {
+				// A missing or unreadable root simply contributes no sessions to the scan.
+			}
+		}
+		const sessions: SessionInfo[] = [];
+		for (const directory of directories) {
+			if (signal?.aborted) break;
+			sessions.push(...(await SessionManager.listAll(directory)));
+		}
+		const seen = new Set<string>();
+		return sessions
+			.filter((session) => !seen.has(session.path) && seen.add(session.path))
+			.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+	}
+
+	async *search(query: SessionIndexQuery, signal?: AbortSignal): AsyncIterable<SessionIndexHitBatch> {
+		const tokens = query.text.trim().toLowerCase().split(/\s+/u).filter(Boolean);
+		if (tokens.length === 0 || query.limit <= 0) return;
+		const sessions = await this.loadSessions(signal);
+		if (signal?.aborted) return;
+		const hits: SessionIndexHitBatch["hits"] = [];
+		for (const session of sessions) {
+			if (query.cwd !== undefined && session.cwd !== query.cwd) continue;
+			if (query.since !== undefined && session.modified.getTime() < query.since) continue;
+			const fields = [session.name ?? "", session.firstMessage, session.allMessagesText];
+			const haystack = fields.join("\n").toLowerCase();
+			if (!tokens.every((token) => haystack.includes(token))) continue;
+			const field = fields.find((text) => tokens.some((token) => text.toLowerCase().includes(token))) ?? "";
+			hits.push({
+				sessionPath: session.path,
+				sessionId: session.id,
+				cwd: session.cwd,
+				entryId: null,
+				entryType: "session",
+				ts: session.modified.getTime(),
+				snippet: textSnippet(field, tokens),
+				score: 0,
+			});
+			if (hits.length >= query.limit) break;
+		}
+		yield { hits, coverage: { indexed: sessions.length, total: sessions.length } };
+	}
+
+	async listSessions(query: SessionListQuery, signal?: AbortSignal): Promise<SessionListPage> {
+		const offset = query.cursor === undefined ? 0 : Number.parseInt(query.cursor, 10);
+		if (!Number.isInteger(offset) || offset < 0) throw new Error("Invalid session list cursor.");
+		const sessions = (await this.loadSessions(signal)).filter(
+			(session) => query.cwd === undefined || session.cwd === query.cwd,
+		);
+		const limit = Math.max(1, Math.floor(query.limit));
+		const page = sessions.slice(offset, offset + limit).map(({ allMessagesText: _text, ...item }) => item);
+		return {
+			sessions: page,
+			nextCursor: offset + limit < sessions.length ? String(offset + limit) : undefined,
+		};
+	}
+
+	async status(): Promise<SessionIndexStatus> {
+		return { state: "degraded", indexed: 0, total: 0, pending: 0, errors: 0, degradedReason: this.reason };
+	}
+
+	notifyPersisted(): void {}
+
+	async addRoot(dir: string): Promise<void> {
+		if (!this.roots.includes(dir)) this.roots.push(dir);
+	}
+
+	reindex(): AsyncIterable<ReindexProgress> {
+		const reason = this.reason;
+		return {
+			[Symbol.asyncIterator]: () => ({
+				next: () => Promise.reject(new Error(`Session index unavailable: ${reason}`)),
+			}),
+		};
+	}
+
+	async close(): Promise<void> {}
+}
diff --git a/packages/coding-agent/src/core/session-index/index.ts b/packages/coding-agent/src/core/session-index/index.ts
new file mode 100644
index 00000000..0b77fd56
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/index.ts
@@ -0,0 +1,24 @@
+export { attachSessionIndex, withSessionIndex } from "./attach.ts";
+export {
+	defaultSessionIndexRoots,
+	type OpenSessionIndexOptions,
+	openSessionIndex,
+	type SessionIndexRoot,
+} from "./client.ts";
+export { runSessionIndexCommand, type SessionIndexCommandOptions } from "./command.ts";
+export { deleteIndexDatabase, getSessionIndexPath } from "./schema.ts";
+export {
+	type ReindexOptions,
+	type ReindexProgress,
+	type SessionIndex,
+	type SessionIndexCoverage,
+	type SessionIndexHit,
+	type SessionIndexHitBatch,
+	type SessionIndexQuery,
+	type SessionIndexStatus,
+	type SessionListItem,
+	type SessionListPage,
+	type SessionListQuery,
+	SNIPPET_MATCH_END,
+	SNIPPET_MATCH_START,
+} from "./types.ts";
diff --git a/packages/coding-agent/src/core/session-index/projector.ts b/packages/coding-agent/src/core/session-index/projector.ts
new file mode 100644
index 00000000..3e3ef0f7
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/projector.ts
@@ -0,0 +1,114 @@
+import type { SessionEntry, SessionHeader } from "../session-manager.ts";
+import { extractMessageText } from "../session-summary.ts";
+
+/**
+ * Turns parsed JSONL lines into searchable rows. Pure functions: no I/O and no
+ * runtime imports beyond the summary helpers, so the worker can load it.
+ */
+
+/** Bump when projected text changes; sources with an older version are rebuilt. */
+export const PROJECTOR_VERSION = 1;
+
+/** Per-entry cap; the trigram index grows about 3x with text length. */
+export const MAX_ENTRY_TEXT_CHARS = 64 * 1024;
+
+export interface ProjectedEntry {
+	entryId: string;
+	parentId: string | null;
+	type: string;
+	role: string | null;
+	ts: number;
+	text: string;
+}
+
+/** How entry ids were derived; v1 files have none and use physical line numbers. */
+export type EntryIdScheme = "entry" | "line";
+
+export function isSessionHeader(value: Record<string, unknown>): value is Record<string, unknown> & SessionHeader {
+	return value.type === "session" && typeof value.id === "string";
+}
+
+export function headerVersion(header: SessionHeader): number {
+	return typeof header.version === "number" ? header.version : 1;
+}
+
+export function entryIdSchemeFor(header: SessionHeader): EntryIdScheme {
+	return headerVersion(header) < 2 ? "line" : "entry";
+}
+
+/**
+ * Bring one raw entry to the v3 shape in memory, mirroring SessionManager's
+ * migrations without touching the file. `lineNo` is the 1-based physical line.
+ */
+export function normalizeEntry(
+	raw: Record<string, unknown>,
+	scheme: EntryIdScheme,
+	lineNo: number,
+	previousId: string | null,
+): SessionEntry | null {
+	if (typeof raw.type !== "string" || raw.type === "session") return null;
+	const entry = { ...raw } as Record<string, unknown>;
+	if (scheme === "line") {
+		entry.id = `L${lineNo}`;
+		entry.parentId = previousId;
+	} else if (typeof entry.id !== "string") {
+		return null;
+	}
+	if (entry.type === "message") {
+		const message = entry.message as { role?: unknown } | undefined;
+		if (message && typeof message === "object" && message.role === "hookMessage") {
+			entry.message = { ...message, role: "custom" };
+		}
+	}
+	return entry as unknown as SessionEntry;
+}
+
+function entryTime(entry: SessionEntry, fallback: number): number {
+	if (entry.type === "message") {
+		const messageTime = (entry.message as { timestamp?: unknown } | undefined)?.timestamp;
+		if (typeof messageTime === "number" && Number.isFinite(messageTime)) return messageTime;
+	}
+	const parsed = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
+	return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+function capText(text: string): string {
+	const trimmed = text.trim();
+	return trimmed.length > MAX_ENTRY_TEXT_CHARS ? trimmed.slice(0, MAX_ENTRY_TEXT_CHARS) : trimmed;
+}
+
+/**
+ * Searchable row for an entry, or null when it carries no indexed text.
+ * Indexed: user/assistant message text, compaction and branch summaries,
+ * displayed custom messages, and labels. Tool results, bash output, and
+ * extension-private entries are not indexed.
+ */
+export function projectEntry(entry: SessionEntry, fallbackTs: number): ProjectedEntry | null {
+	let role: string | null = null;
+	let text = "";
+	if (entry.type === "message") {
+		const message = entry.message as { role?: unknown; content?: unknown } | undefined;
+		if (!message || (message.role !== "user" && message.role !== "assistant")) return null;
+		role = message.role;
+		text = extractMessageText(message as Parameters<typeof extractMessageText>[0]);
+	} else if (entry.type === "compaction" || entry.type === "branch_summary") {
+		text = typeof entry.summary === "string" ? entry.summary : "";
+	} else if (entry.type === "custom_message") {
+		if (entry.display !== true) return null;
+		text = extractMessageText({ content: entry.content } as Parameters<typeof extractMessageText>[0]);
+	} else if (entry.type === "label") {
+		text = typeof entry.label === "string" ? entry.label : "";
+	} else {
+		return null;
+	}
+	text = capText(text);
+	if (!text) return null;
+	return {
+		entryId: entry.id,
+		parentId: typeof entry.parentId === "string" ? entry.parentId : null,
+		type: entry.type,
+		role,
+		ts: entryTime(entry, fallbackTs),
+		text,
+	};
+}
diff --git a/packages/coding-agent/src/core/session-index/reader.ts b/packages/coding-agent/src/core/session-index/reader.ts
new file mode 100644
index 00000000..07ab8be4
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/reader.ts
@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Read-only access to session JSONL files. Nothing here writes to a session
+ * file: SessionManager's loadEntriesFromFile() repairs a missing trailing
+ * newline, so the indexer must never reuse it.
+ */
+
+const READ_CHUNK_BYTES = 1024 * 1024;
+
+export interface FileFingerprint {
+	size: number;
+	mtimeMs: number;
+	/** "dev:ino"; a secondary signal only, inode numbers are unreliable on some platforms. */
+	devIno: string;
+}
+
+export function statSessionFile(path: string): FileFingerprint | null {
+	try {
+		const stats = statSync(path, { bigint: true });
+		if (!stats.isFile()) return null;
+		return {
+			size: Number(stats.size),
+			mtimeMs: Number(stats.mtimeMs),
+			devIno: `${stats.dev}:${stats.ino}`,
+		};
+	} catch (error) {
+		if (isMissingFileError(error)) return null;
+		throw error;
+	}
+}
+
+export function isMissingFileError(error: unknown): boolean {
+	const code = (error as { code?: unknown } | null)?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+export interface RawLine {
+	/** Byte offset of the line start. */
+	start: number;
+	/** Byte offset after the line, including its newline when present. */
+	end: number;
+	bytes: Buffer;
+	/** False only for a final line with no trailing newline. */
+	terminated: boolean;
+}
+
+/**
+ * Read physical lines in [from, until). The final unterminated fragment is
+ * returned with terminated=false so the caller can decide whether a writer is
+ * still producing it.
+ */
+export function readLines(path: string, from: number, until: number): RawLine[] {
+	const lines: RawLine[] = [];
+	if (until <= from) return lines;
+	const fd = openSync(path, "r");
+	try {
+		const buffer = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+		let position = from;
+		let pending: Buffer[] = [];
+		let pendingStart = from;
+		while (position < until) {
+			const bytesRead = readSync(fd, buffer, 0, Math.min(buffer.length, until - position), position);
+			if (bytesRead === 0) break;
+			const chunk = buffer.subarray(0, bytesRead);
+			let lineStart = 0;
+			let newline = chunk.indexOf(0x0a, lineStart);
+			while (newline !== -1) {
+				pending.push(chunk.subarray(lineStart, newline));
+				const end = position + newline + 1;
+				lines.push({ start: pendingStart, end, bytes: Buffer.concat(pending), terminated: true });
+				pending = [];
+				pendingStart = end;
+				lineStart = newline + 1;
+				newline = chunk.indexOf(0x0a, lineStart);
+			}
+			if (lineStart < chunk.length) pending.push(Buffer.from(chunk.subarray(lineStart)));
+			position += bytesRead;
+		}
+		if (pending.length > 0) {
+			const bytes = Buffer.concat(pending);
+			lines.push({ start: pendingStart, end: pendingStart + bytes.length, bytes, terminated: false });
+		}
+	} finally {
+		closeSync(fd);
+	}
+	return lines;
+}
+
+export function hashBytes(bytes: Buffer): string {
+	return `sha1:${createHash("sha1").update(bytes).digest("hex")}`;
+}
+
+/** Hash the bytes in [start, end); null when the file is shorter than end. */
+export function hashFileRange(path: string, start: number, end: number): string | null {
+	const length = end - start;
+	if (length < 0) return null;
+	const fd = openSync(path, "r");
+	try {
+		const buffer = Buffer.alloc(length);
+		let offset = 0;
+		while (offset < length) {
+			const bytesRead = readSync(fd, buffer, offset, length - offset, start + offset);
+			if (bytesRead === 0) return null;
+			offset += bytesRead;
+		}
+		return hashBytes(buffer);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** Parse one physical line into a JSON object, or null when it is blank or malformed. */
+export function parseJsonObjectLine(bytes: Buffer): Record<string, unknown> | null {
+	const text = bytes.toString("utf8");
+	if (!text.trim()) return null;
+	try {
+		const value: unknown = JSON.parse(text);
+		return value !== null && typeof value === "object" && !Array.isArray(value)
+			? (value as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+export interface SessionRootScan {
+	files: string[];
+	/** mtime of the root and of each listed subdirectory, taken before listing it. */
+	directories: Map<string, number>;
+}
+
+/**
+ * Session files under one root: *.jsonl directly in the root and in its
+ * immediate subdirectories (the default root keeps one directory per cwd),
+ * plus the directory mtimes a later freshness check compares against.
+ * A missing root yields an empty scan; other directory errors are thrown so
+ * the caller does not mistake an unreadable root for deleted sessions.
+ */
+export function scanSessionRoot(root: string): SessionRootScan {
+	const scan: SessionRootScan = { files: [], directories: new Map() };
+	const rootMtime = statDirectoryMtime(root);
+	if (rootMtime === null) return scan;
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		if (isMissingFileError(error)) return scan;
+		throw error;
+	}
+	scan.directories.set(root, rootMtime);
+	for (const entry of entries) {
+		const path = join(root, entry.name);
+		if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+			scan.files.push(path);
+		} else if (entry.isDirectory() || entry.isSymbolicLink()) {
+			const mtime = statDirectoryMtime(path);
+			// A symlink to a file or a vanished directory is not a session folder.
+			if (mtime === null) continue;
+			const children = listJsonlFiles(path);
+			if (children === null) continue;
+			scan.directories.set(path, mtime);
+			scan.files.push(...children);
+		}
+	}
+	return scan;
+}
+
+/** *.jsonl files directly inside one directory; null when it is missing or not a directory. */
+export function listJsonlFiles(directory: string): string[] | null {
+	let children: string[];
+	try {
+		children = readdirSync(directory);
+	} catch (error) {
+		if (isMissingFileError(error)) return null;
+		throw error;
+	}
+	return children.filter((child) => child.endsWith(".jsonl")).map((child) => join(directory, child));
+}
+
+/** Immediate subdirectories of a root, following symlinks. */
+export function listSubdirectories(root: string): string[] {
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		if (isMissingFileError(error)) return [];
+		throw error;
+	}
+	return entries
+		.filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+		.map((entry) => join(root, entry.name))
+		.filter((path) => statDirectoryMtime(path) !== null);
+}
+
+export function statDirectoryMtime(path: string): number | null {
+	try {
+		const stats = statSync(path);
+		return stats.isDirectory() ? stats.mtimeMs : null;
+	} catch (error) {
+		if (isMissingFileError(error)) return null;
+		throw error;
+	}
+}
diff --git a/packages/coding-agent/src/core/session-index/schema.ts b/packages/coding-agent/src/core/session-index/schema.ts
new file mode 100644
index 00000000..6adcc486
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/schema.ts
@@ -0,0 +1,331 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import { PROJECTOR_VERSION } from "./projector.ts";
+
+/**
+ * Index database schema, validation, and creation. The database is derived
+ * from the session JSONL files: any version or integrity problem is resolved
+ * by rebuilding it, never by touching the session files.
+ */
+
+/** "STCX" — distinguishes our index from an unrelated SQLite file at the same path. */
+export const SESSION_INDEX_APPLICATION_ID = 0x53544358;
+/**
+ * Incompatible layouts get a new file name, so binaries of different majors
+ * never open or delete each other's index.
+ */
+export const SCHEMA_MAJOR = 1;
+/**
+ * Additive migration number within a major, stored in `user_version`. Older
+ * files are migrated in place; newer files are used through known columns only.
+ */
+export const SCHEMA_MINOR = 1;
+/** Changing the tokenizer or FTS columns rebuilds only the FTS tables from `entries`. */
+export const FTS_DEFINITION = "trigram:v1";
+export const SESSION_INDEX_FILE_NAME = `session-search.v${SCHEMA_MAJOR}.db`;
+const MAX_CORRUPT_BACKUPS = 1;
+
+type DatabaseSyncConstructor = typeof DatabaseSync;
+
+export class ForeignDatabaseError extends Error {
+	constructor(path: string) {
+		super(`${path} is not a Step session index; refusing to modify it.`);
+		this.name = "ForeignDatabaseError";
+	}
+}
+
+export class FtsUnavailableError extends Error {
+	constructor(cause: unknown) {
+		super(`SQLite FTS5 trigram tokenizer is unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
+		this.name = "FtsUnavailableError";
+	}
+}
+
+export function getSessionIndexPath(agentDir: string): string {
+	return join(agentDir, "index", SESSION_INDEX_FILE_NAME);
+}
+
+const BASE_TABLES = ["index_meta", "roots", "sources", "sessions", "entries", "entries_fts", "sessions_fts"];
+
+const CORE_DDL = `
+CREATE TABLE index_meta (
+	key TEXT PRIMARY KEY,
+	value TEXT NOT NULL
+) STRICT;
+CREATE TABLE roots (
+	path TEXT PRIMARY KEY,
+	kind TEXT NOT NULL CHECK (kind IN ('default', 'custom')),
+	added_at INTEGER NOT NULL
+) STRICT;
+CREATE TABLE sources (
+	path TEXT PRIMARY KEY,
+	root TEXT NOT NULL REFERENCES roots(path) ON DELETE CASCADE,
+	session_id TEXT,
+	size INTEGER NOT NULL,
+	mtime_ms INTEGER NOT NULL,
+	dev_ino TEXT,
+	indexed_offset INTEGER NOT NULL DEFAULT 0,
+	line_count INTEGER NOT NULL DEFAULT 0,
+	header_end INTEGER,
+	header_hash TEXT,
+	tail_offset INTEGER,
+	tail_hash TEXT,
+	header_version INTEGER,
+	id_scheme TEXT,
+	projector_version INTEGER,
+	status TEXT NOT NULL CHECK (status IN ('ok', 'pending', 'error')),
+	error TEXT,
+	indexed_at INTEGER NOT NULL
+) STRICT;
+CREATE TABLE sessions (
+	sid INTEGER PRIMARY KEY,
+	path TEXT NOT NULL UNIQUE REFERENCES sources(path) ON DELETE CASCADE,
+	session_id TEXT NOT NULL,
+	cwd TEXT NOT NULL,
+	parent_session TEXT,
+	name TEXT,
+	first_message TEXT,
+	created_at INTEGER NOT NULL,
+	modified_at INTEGER NOT NULL,
+	last_activity_at INTEGER,
+	message_count INTEGER NOT NULL
+) STRICT;
+CREATE INDEX sessions_cwd_modified ON sessions(cwd, modified_at DESC);
+CREATE INDEX sessions_modified ON sessions(modified_at DESC);
+CREATE INDEX sessions_session_id ON sessions(session_id);
+CREATE TABLE entries (
+	eid INTEGER PRIMARY KEY,
+	sid INTEGER NOT NULL REFERENCES sessions(sid) ON DELETE CASCADE,
+	entry_id TEXT NOT NULL,
+	parent_id TEXT,
+	entry_type TEXT NOT NULL,
+	role TEXT,
+	ts INTEGER NOT NULL,
+	text TEXT NOT NULL,
+	UNIQUE (sid, entry_id)
+) STRICT;
+CREATE INDEX entries_sid_ts ON entries(sid, ts);
+`;
+
+const FTS_DDL = `
+CREATE VIRTUAL TABLE entries_fts USING fts5(text, content='entries', content_rowid='eid', tokenize='trigram');
+CREATE VIRTUAL TABLE sessions_fts USING fts5(name, first_message, content='sessions', content_rowid='sid', tokenize='trigram');
+CREATE TRIGGER entries_ai AFTER INSERT ON entries BEGIN
+	INSERT INTO entries_fts(rowid, text) VALUES (new.eid, new.text);
+END;
+CREATE TRIGGER entries_ad AFTER DELETE ON entries BEGIN
+	INSERT INTO entries_fts(entries_fts, rowid, text) VALUES ('delete', old.eid, old.text);
+END;
+CREATE TRIGGER entries_au AFTER UPDATE OF text ON entries BEGIN
+	INSERT INTO entries_fts(entries_fts, rowid, text) VALUES ('delete', old.eid, old.text);
+	INSERT INTO entries_fts(rowid, text) VALUES (new.eid, new.text);
+END;
+CREATE TRIGGER sessions_ai AFTER INSERT ON sessions BEGIN
+	INSERT INTO sessions_fts(rowid, name, first_message) VALUES (new.sid, coalesce(new.name, ''), coalesce(new.first_message, ''));
+END;
+CREATE TRIGGER sessions_ad AFTER DELETE ON sessions BEGIN
+	INSERT INTO sessions_fts(sessions_fts, rowid, name, first_message)
+	VALUES ('delete', old.sid, coalesce(old.name, ''), coalesce(old.first_message, ''));
+END;
+CREATE TRIGGER sessions_au AFTER UPDATE OF name, first_message ON sessions BEGIN
+	INSERT INTO sessions_fts(sessions_fts, rowid, name, first_message)
+	VALUES ('delete', old.sid, coalesce(old.name, ''), coalesce(old.first_message, ''));
+	INSERT INTO sessions_fts(rowid, name, first_message) VALUES (new.sid, coalesce(new.name, ''), coalesce(new.first_message, ''));
+END;
+`;
+
+const DROP_FTS = `
+DROP TRIGGER IF EXISTS entries_ai;
+DROP TRIGGER IF EXISTS entries_ad;
+DROP TRIGGER IF EXISTS entries_au;
+DROP TRIGGER IF EXISTS sessions_ai;
+DROP TRIGGER IF EXISTS sessions_ad;
+DROP TRIGGER IF EXISTS sessions_au;
+DROP TABLE IF EXISTS entries_fts;
+DROP TABLE IF EXISTS sessions_fts;
+`;
+
+type ExistingState =
+	| { kind: "missing" }
+	| { kind: "empty" }
+	| { kind: "ours"; userVersion: number }
+	| { kind: "foreign" }
+	| { kind: "corrupt"; error: unknown };
+
+/** Inspect an existing file without writing to it. */
+function inspectExisting(Database: DatabaseSyncConstructor, path: string): ExistingState {
+	if (!existsSync(path)) return { kind: "missing" };
+	let db: DatabaseSync | undefined;
+	try {
+		db = new Database(path, { readOnly: true });
+		const applicationId = Number(db.prepare("PRAGMA application_id").get()?.application_id ?? 0);
+		const userVersion = Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+		const tableCount = Number(
+			db.prepare("SELECT count(*) AS n FROM sqlite_schema WHERE type = 'table'").get()?.n ?? 0,
+		);
+		if (applicationId === SESSION_INDEX_APPLICATION_ID) {
+			const tables = new Set(
+				db
+					.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'")
+					.all()
+					.map((row) => String(row.name)),
+			);
+			// A half-created file from an interrupted first run carries no tables yet.
+			if (!BASE_TABLES.every((name) => tables.has(name))) return { kind: "corrupt", error: "missing tables" };
+			const major = db.prepare("SELECT value FROM index_meta WHERE key = 'schema_major'").get()?.value;
+			// The major is part of the file name; a mismatch means the file was copied or damaged.
+			if (major !== String(SCHEMA_MAJOR)) return { kind: "corrupt", error: `schema_major ${String(major)}` };
+			return { kind: "ours", userVersion };
+		}
+		if (applicationId === 0 && tableCount === 0) return { kind: "empty" };
+		return { kind: "foreign" };
+	} catch (error) {
+		return { kind: "corrupt", error };
+	} finally {
+		db?.close();
+	}
+}
+
+function removeDatabaseFiles(path: string): void {
+	for (const suffix of ["", "-wal", "-shm", "-journal"]) rmSync(`${path}${suffix}`, { force: true });
+}
+
+/** Move a damaged index aside for diagnosis and keep only the newest backups. */
+function quarantine(path: string): void {
+	const backup = `${path}.corrupt-${Date.now()}`;
+	try {
+		renameSync(path, backup);
+	} catch {
+		// Renaming can fail on locked files (Windows); the index is derived, so delete instead.
+	}
+	removeDatabaseFiles(path);
+	const prefix = `${basename(path)}.corrupt-`;
+	const backups = readdirSync(dirname(path))
+		.filter((name) => name.startsWith(prefix))
+		.sort()
+		.reverse();
+	for (const stale of backups.slice(MAX_CORRUPT_BACKUPS)) rmSync(join(dirname(path), stale), { force: true });
+}
+
+function probeTrigram(db: DatabaseSync): void {
+	try {
+		db.exec("CREATE VIRTUAL TABLE temp.session_index_probe USING fts5(x, tokenize='trigram')");
+		db.exec("DROP TABLE temp.session_index_probe");
+	} catch (error) {
+		throw new FtsUnavailableError(error);
+	}
+}
+
+function readMeta(db: DatabaseSync, key: string): string | undefined {
+	const row = db.prepare("SELECT value FROM index_meta WHERE key = ?").get(key);
+	return row ? String(row.value) : undefined;
+}
+
+export function writeMeta(db: DatabaseSync, key: string, value: string): void {
+	db.prepare(
+		"INSERT INTO index_meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+	).run(key, value);
+}
+
+export function getMeta(db: DatabaseSync, key: string): string | undefined {
+	return readMeta(db, key);
+}
+
+function createSchema(db: DatabaseSync): void {
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		db.exec(CORE_DDL);
+		db.exec(FTS_DDL);
+		writeMeta(db, "schema_major", String(SCHEMA_MAJOR));
+		writeMeta(db, "fts_definition", FTS_DEFINITION);
+		writeMeta(db, "projector_version", String(PROJECTOR_VERSION));
+		writeMeta(db, "backfill_state", "running");
+		// Stamp ownership last so an interrupted creation is recognised as ours only once complete.
+		db.exec(`PRAGMA application_id = ${SESSION_INDEX_APPLICATION_ID}`);
+		db.exec(`PRAGMA user_version = ${SCHEMA_MINOR}`);
+		db.exec("COMMIT");
+	} catch (error) {
+		db.exec("ROLLBACK");
+		throw error;
+	}
+}
+
+/**
+ * Bring an existing file to this build's minor and FTS definition. A file
+ * written by a newer binary is left as is: its additive changes are
+ * invisible to the known columns used here, and its FTS definition wins.
+ */
+function upgradeSchema(db: DatabaseSync, userVersion: number): void {
+	if (userVersion > SCHEMA_MINOR) return;
+	const ftsDefinition = readMeta(db, "fts_definition");
+	if (userVersion === SCHEMA_MINOR && ftsDefinition === FTS_DEFINITION) return;
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		// Minor migrations go here in order, each guarded by `userVersion < N`.
+		if (ftsDefinition !== FTS_DEFINITION) {
+			// Rebuild from `entries` without rereading JSONL.
+			db.exec(DROP_FTS);
+			db.exec(FTS_DDL);
+			db.exec("INSERT INTO entries_fts(entries_fts) VALUES ('rebuild')");
+			db.exec("INSERT INTO sessions_fts(sessions_fts) VALUES ('rebuild')");
+			writeMeta(db, "fts_definition", FTS_DEFINITION);
+		}
+		if (userVersion < SCHEMA_MINOR) db.exec(`PRAGMA user_version = ${SCHEMA_MINOR}`);
+		db.exec("COMMIT");
+	} catch (error) {
+		db.exec("ROLLBACK");
+		throw error;
+	}
+}
+
+export interface OpenedIndexDatabase {
+	db: DatabaseSync;
+	/** Set when a damaged file was moved aside and replaced. */
+	recreated?: "corrupt";
+}
+
+/**
+ * Open or create the index. Throws ForeignDatabaseError for a file we do not
+ * own and FtsUnavailableError when the SQLite build lacks trigram FTS5.
+ */
+export function openIndexDatabase(Database: DatabaseSyncConstructor, path: string): OpenedIndexDatabase {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const existing = inspectExisting(Database, path);
+	let recreated: OpenedIndexDatabase["recreated"];
+	if (existing.kind === "foreign") throw new ForeignDatabaseError(path);
+	if (existing.kind === "corrupt") {
+		quarantine(path);
+		recreated = "corrupt";
+	}
+
+	const db = new Database(path, { enableForeignKeyConstraints: true, timeout: 5000 });
+	try {
+		try {
+			chmodSync(path, 0o600);
+		} catch {
+			// Permissions are best effort (e.g. Windows); the index holds only copies of session text.
+		}
+		db.exec("PRAGMA foreign_keys = ON");
+		db.exec("PRAGMA journal_mode = WAL");
+		db.exec("PRAGMA synchronous = NORMAL");
+		probeTrigram(db);
+		if (existing.kind === "ours") {
+			upgradeSchema(db, existing.userVersion);
+		} else {
+			createSchema(db);
+		}
+		if (Number(readMeta(db, "projector_version") ?? 0) < PROJECTOR_VERSION) {
+			// Sources with an older projector_version are re-projected by the next reconcile.
+			writeMeta(db, "projector_version", String(PROJECTOR_VERSION));
+		}
+		return { db, recreated };
+	} catch (error) {
+		db.close();
+		throw error;
+	}
+}
+
+export function deleteIndexDatabase(path: string): void {
+	removeDatabaseFiles(path);
+}
diff --git a/packages/coding-agent/src/core/session-index/session-index-worker.ts b/packages/coding-agent/src/core/session-index/session-index-worker.ts
new file mode 100644
index 00000000..6450e58e
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/session-index-worker.ts
@@ -0,0 +1,230 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { openIndexDatabase } from "./schema.ts";
+import { SessionIndexStore } from "./store.ts";
+import type { SessionIndexQuery, SessionIndexStatus, SessionListQuery } from "./types.ts";
+
+/**
+ * Index worker: the only owner of the SQLite connection. Requests are served
+ * between file syncs, so a long backfill never blocks a search for more than
+ * one file.
+ */
+
+export interface SessionIndexWorkerData {
+	dbPath: string;
+	roots: { path: string; kind: "default" | "custom" }[];
+	/** Reconcile every root in the background after opening. */
+	backfill: boolean;
+}
+
+export type WorkerRequest =
+	| { id: number; op: "sync"; paths: string[] }
+	| { id: number; op: "search"; query: SessionIndexQuery }
+	| { id: number; op: "list"; query: SessionListQuery }
+	| { id: number; op: "status" }
+	| { id: number; op: "reindex"; full: boolean }
+	| { id: number; op: "addRoot"; path: string }
+	| { id: number; op: "cancel"; target: number }
+	| { id: number; op: "close" };
+
+export type WorkerMessage =
+	| { type: "ready" }
+	| { type: "degraded"; reason: string }
+	| { type: "result"; id: number; result: unknown }
+	| { type: "error"; id: number; error: string }
+	| { type: "progress"; id: number; indexed: number; total: number };
+
+const YIELD_EVERY_MS = 20;
+const REFRESH_BUDGET_MS = 30;
+
+const yieldToEvents = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** Corruption makes every later statement unreliable; the client falls back to scanning. */
+function isFatalDatabaseError(error: unknown): boolean {
+	const message = errorMessage(error);
+	return /malformed|not a database|SQLITE_CORRUPT|SQLITE_NOTADB|disk I\/O error/iu.test(message);
+}
+
+async function main(port: NonNullable<typeof parentPort>, data: SessionIndexWorkerData): Promise<void> {
+	const post = (message: WorkerMessage): void => port.postMessage(message);
+
+	// node:sqlite still warns as experimental on Node 22; keep that off the host's stderr.
+	const emitWarning = process.emitWarning.bind(process);
+	process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
+		const text = typeof warning === "string" ? warning : warning.message;
+		if (/SQLite/iu.test(text)) return;
+		(emitWarning as (...args: unknown[]) => void)(warning, ...rest);
+	}) as typeof process.emitWarning;
+
+	let store: SessionIndexStore;
+	try {
+		// Imported after the warning filter is installed; a static import would load first.
+		const { DatabaseSync } = await import("node:sqlite");
+		store = new SessionIndexStore(openIndexDatabase(DatabaseSync, data.dbPath).db);
+		for (const root of data.roots) store.addRoot(root.path, root.kind);
+	} catch (error) {
+		post({ type: "degraded", reason: errorMessage(error) });
+		return;
+	}
+
+	let closed = false;
+	let discoveredTotal = 0;
+	let reconcile: Promise<void> | undefined;
+	const pendingSyncs = new Set<string>();
+	let draining: Promise<void> | undefined;
+	const cancelled = new Set<number>();
+
+	const fail = (error: unknown): void => {
+		if (closed) return;
+		closed = true;
+		try {
+			store.close();
+		} catch {
+			// The connection is already unusable; the client is told to degrade below.
+		}
+		post({ type: "degraded", reason: errorMessage(error) });
+	};
+
+	const syncOne = (path: string): void => {
+		try {
+			store.syncFile(path);
+		} catch (error) {
+			if (isFatalDatabaseError(error)) throw error;
+			// A single unreadable file stays stale; the next reconcile retries it.
+		}
+	};
+
+	const runReconcile = async (full: boolean, onProgress?: (indexed: number, total: number) => void) => {
+		// Persisted so an interrupted backfill is visible after a restart; reconcile resumes from `sources`.
+		store.setMeta("backfill_state", "running");
+		if (full) store.clearSources();
+		const plan = store.planReconcile();
+		discoveredTotal = plan.total;
+		let done = plan.total - plan.toSync.length;
+		let lastYield = Date.now();
+		onProgress?.(done, plan.total);
+		for (const path of plan.toSync) {
+			if (closed) return;
+			syncOne(path);
+			done++;
+			if (Date.now() - lastYield >= YIELD_EVERY_MS) {
+				onProgress?.(done, plan.total);
+				await yieldToEvents();
+				lastYield = Date.now();
+			}
+		}
+		if (closed) return;
+		store.setMeta("backfill_state", "done");
+		store.setMeta("last_reconcile_at", String(Date.now()));
+		onProgress?.(done, plan.total);
+	};
+
+	/** Serialise reconciles; a request made during one runs after it. */
+	const scheduleReconcile = (full: boolean, onProgress?: (indexed: number, total: number) => void) => {
+		const previous = reconcile ?? Promise.resolve();
+		const next = previous.then(() => (closed ? undefined : runReconcile(full, onProgress)));
+		reconcile = next.finally(() => {
+			if (reconcile === tracked) reconcile = undefined;
+		});
+		const tracked = reconcile;
+		return next;
+	};
+
+	const drainSyncs = (): Promise<void> => {
+		draining ??= (async () => {
+			while (pendingSyncs.size > 0 && !closed) {
+				const [path] = pendingSyncs;
+				pendingSyncs.delete(path);
+				syncOne(path);
+				await yieldToEvents();
+			}
+		})().finally(() => {
+			draining = undefined;
+		});
+		return draining;
+	};
+
+	/**
+	 * Writers in other processes do not notify this worker. Check the newest
+	 * files and changed directories within a small budget before answering;
+	 * when the budget runs out, a background reconcile finishes the job.
+	 */
+	const refreshBeforeQuery = (): void => {
+		const complete = store.refreshRecent(Date.now() + REFRESH_BUDGET_MS, syncOne);
+		if (!complete && !reconcile) void scheduleReconcile(false).catch(fail);
+	};
+
+	const status = (): SessionIndexStatus => {
+		const counts = store.counts();
+		return {
+			state: reconcile ? "backfilling" : "ready",
+			indexed: counts.indexed,
+			total: Math.max(counts.total, discoveredTotal),
+			pending: counts.pending,
+			errors: counts.errors,
+			dbPath: data.dbPath,
+		};
+	};
+
+	const handle = async (request: WorkerRequest): Promise<unknown> => {
+		switch (request.op) {
+			case "sync":
+				for (const path of request.paths) pendingSyncs.add(path);
+				await drainSyncs();
+				return undefined;
+			case "search":
+				refreshBeforeQuery();
+				return { hits: store.search(request.query), coverage: store.coverage(discoveredTotal) };
+			case "list":
+				refreshBeforeQuery();
+				return store.listSessions(request.query);
+			case "status":
+				return status();
+			case "addRoot":
+				store.addRoot(request.path, "custom");
+				void scheduleReconcile(false).catch(fail);
+				return undefined;
+			case "reindex":
+				await scheduleReconcile(request.full, (indexed, total) => {
+					if (!cancelled.has(request.id)) post({ type: "progress", id: request.id, indexed, total });
+				});
+				return status();
+			case "cancel":
+				cancelled.add(request.target);
+				return undefined;
+			case "close": {
+				closed = true;
+				await Promise.allSettled([reconcile, draining]);
+				store.close();
+				return undefined;
+			}
+		}
+	};
+
+	port.on("message", (request: WorkerRequest) => {
+		if (closed && request.op !== "close") {
+			post({ type: "error", id: request.id, error: "Session index is closed." });
+			return;
+		}
+		void handle(request).then(
+			(result) => {
+				cancelled.delete(request.id);
+				post({ type: "result", id: request.id, result });
+				if (request.op === "close") port.close();
+			},
+			(error: unknown) => {
+				cancelled.delete(request.id);
+				if (isFatalDatabaseError(error)) fail(error);
+				post({ type: "error", id: request.id, error: errorMessage(error) });
+			},
+		);
+	});
+
+	post({ type: "ready" });
+	if (data.backfill) void scheduleReconcile(false).catch(fail);
+}
+
+if (parentPort) void main(parentPort, workerData as SessionIndexWorkerData);
diff --git a/packages/coding-agent/src/core/session-index/store.ts b/packages/coding-agent/src/core/session-index/store.ts
new file mode 100644
index 00000000..42f533e8
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/store.ts
@@ -0,0 +1,890 @@
+import { dirname } from "node:path";
+import type { DatabaseSync, SQLInputValue } from "node:sqlite";
+import type { SessionHeader } from "../session-manager.ts";
+import {
+	createSessionSummary,
+	foldSessionSummaryEntry,
+	resolveSessionModifiedTime,
+	type SessionSummaryFields,
+} from "../session-summary.ts";
+import {
+	entryIdSchemeFor,
+	headerVersion,
+	isSessionHeader,
+	normalizeEntry,
+	PROJECTOR_VERSION,
+	type ProjectedEntry,
+	projectEntry,
+} from "./projector.ts";
+import {
+	type FileFingerprint,
+	hashFileRange,
+	listJsonlFiles,
+	listSubdirectories,
+	parseJsonObjectLine,
+	type RawLine,
+	readLines,
+	type SessionRootScan,
+	scanSessionRoot,
+	statDirectoryMtime,
+	statSessionFile,
+} from "./reader.ts";
+import { writeMeta } from "./schema.ts";
+import {
+	type SessionIndexCoverage,
+	type SessionIndexHit,
+	type SessionIndexQuery,
+	type SessionListItem,
+	type SessionListPage,
+	type SessionListQuery,
+	SNIPPET_MATCH_END,
+	SNIPPET_MATCH_START,
+} from "./types.ts";
+
+/**
+ * Synchronous index operations over one DatabaseSync connection. Only the
+ * worker owns an instance. Session files are read, never written.
+ */
+
+export const MIN_FTS_QUERY_CHARS = 3;
+export const SHORT_QUERY_DEFAULT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+export const SHORT_QUERY_MAX_SESSIONS = 200;
+export const SHORT_QUERY_MAX_HITS = 50;
+const SNIPPET_CONTEXT_CHARS = 48;
+const FTS_SNIPPET_TOKENS = 32;
+/** Known files re-checked before each search or list. */
+export const REFRESH_RECENT_FILES = 20;
+
+interface TrackedDirectory {
+	mtimeMs: number;
+	/** Roots may gain new per-cwd subdirectories; subdirectories only gain files. */
+	isRoot: boolean;
+}
+
+export type SyncOutcome = "skipped" | "indexed" | "appended" | "pending" | "error" | "removed" | "conflict";
+
+interface SourceRow {
+	path: string;
+	root: string;
+	session_id: string | null;
+	size: number;
+	mtime_ms: number;
+	dev_ino: string | null;
+	indexed_offset: number;
+	line_count: number;
+	header_end: number | null;
+	header_hash: string | null;
+	tail_offset: number | null;
+	tail_hash: string | null;
+	header_version: number | null;
+	id_scheme: string | null;
+	projector_version: number | null;
+	status: "ok" | "pending" | "error";
+	error: string | null;
+}
+
+interface SessionRow {
+	sid: number;
+	session_id: string;
+	cwd: string;
+	name: string | null;
+	created_at: number;
+	last_activity_at: number | null;
+	message_count: number;
+	first_message: string | null;
+}
+
+export interface ReconcilePlan {
+	/** Files that are new or changed, most recently modified first. */
+	toSync: string[];
+	/** Session files found on disk across all readable roots. */
+	total: number;
+	removed: number;
+}
+
+class SnapshotConflictError extends Error {}
+
+function num(value: unknown): number {
+	return typeof value === "bigint" ? Number(value) : (value as number);
+}
+
+function sameSnapshot(a: SourceRow | undefined, b: SourceRow | undefined): boolean {
+	if (!a || !b) return a === b;
+	return (
+		a.indexed_offset === b.indexed_offset &&
+		a.header_hash === b.header_hash &&
+		a.status === b.status &&
+		a.size === b.size &&
+		a.mtime_ms === b.mtime_ms
+	);
+}
+
+function isUnchanged(row: SourceRow, fp: FileFingerprint): boolean {
+	return (
+		row.status === "ok" && row.size === fp.size && row.mtime_ms === Math.trunc(fp.mtimeMs) && isCurrentProjection(row)
+	);
+}
+
+/**
+ * Rows projected by a newer binary count as current, so two installed
+ * versions do not keep rebuilding each other's rows.
+ */
+function isCurrentProjection(row: SourceRow): boolean {
+	return row.projector_version !== null && row.projector_version >= PROJECTOR_VERSION;
+}
+
+function escapeLike(token: string): string {
+	return token.replace(/[\\%_]/gu, (char) => `\\${char}`);
+}
+
+function ftsPhrase(token: string): string {
+	return `"${token.replaceAll('"', '""')}"`;
+}
+
+/** Excerpt around the first match of any token, matching LIKE's ASCII case folding. */
+export function textSnippet(text: string, tokens: readonly string[]): string {
+	const lower = text.replace(/[A-Z]/gu, (char) => char.toLowerCase());
+	let start = -1;
+	let length = 0;
+	for (const token of tokens) {
+		const index = lower.indexOf(token.replace(/[A-Z]/gu, (char) => char.toLowerCase()));
+		if (index !== -1 && (start === -1 || index < start)) {
+			start = index;
+			length = token.length;
+		}
+	}
+	if (start === -1) return text.slice(0, SNIPPET_CONTEXT_CHARS * 2);
+	const from = Math.max(0, start - SNIPPET_CONTEXT_CHARS);
+	const to = Math.min(text.length, start + length + SNIPPET_CONTEXT_CHARS);
+	return `${from > 0 ? "…" : ""}${text.slice(from, start)}${SNIPPET_MATCH_START}${text.slice(start, start + length)}${SNIPPET_MATCH_END}${text.slice(start + length, to)}${to < text.length ? "…" : ""}`;
+}
+
+function encodeCursor(modifiedAt: number, sid: number): string {
+	return Buffer.from(JSON.stringify([modifiedAt, sid])).toString("base64url");
+}
+
+function decodeCursor(cursor: string): [number, number] | null {
+	try {
+		const value: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+		if (Array.isArray(value) && value.length === 2 && value.every((part) => Number.isFinite(part))) {
+			return [value[0] as number, value[1] as number];
+		}
+	} catch {
+		// Fall through: an unreadable cursor is rejected below.
+	}
+	return null;
+}
+
+interface ParsedLines {
+	header?: SessionHeader & Record<string, unknown>;
+	headerEnd?: number;
+	entries: ProjectedEntry[];
+	summary: SessionSummaryFields;
+	/** Offset after the last consumed line. */
+	consumedTo: number;
+	tailOffset: number | null;
+	lineCount: number;
+	malformed: number;
+	/** The first line is not a session header. */
+	invalidHeader?: boolean;
+}
+
+export class SessionIndexStore {
+	private readonly db: DatabaseSync;
+	/** Directory mtimes from the last reconcile; in memory only, empty until the first reconcile. */
+	private directories = new Map<string, TrackedDirectory>();
+
+	constructor(db: DatabaseSync) {
+		this.db = db;
+	}
+
+	close(): void {
+		if (this.db.isTransaction) this.db.exec("ROLLBACK");
+		this.db.close();
+	}
+
+	setMeta(key: string, value: string): void {
+		writeMeta(this.db, key, value);
+	}
+
+	addRoot(path: string, kind: "default" | "custom"): void {
+		this.db
+			.prepare(
+				"INSERT INTO roots(path, kind, added_at) VALUES (?, ?, ?) ON CONFLICT(path) DO UPDATE SET kind = CASE WHEN excluded.kind = 'default' THEN 'default' ELSE roots.kind END",
+			)
+			.run(path, kind, Date.now());
+	}
+
+	listRoots(): { path: string; kind: string }[] {
+		return this.db
+			.prepare("SELECT path, kind FROM roots ORDER BY added_at, path")
+			.all()
+			.map((row) => ({ path: String(row.path), kind: String(row.kind) }));
+	}
+
+	/** The root holding a file: its directory or that directory's parent. Unknown directories become custom roots. */
+	private rootForFile(path: string): string {
+		const directory = dirname(path);
+		const parent = dirname(directory);
+		for (const candidate of [directory, parent]) {
+			if (this.db.prepare("SELECT 1 FROM roots WHERE path = ?").get(candidate)) return candidate;
+		}
+		this.addRoot(directory, "custom");
+		return directory;
+	}
+
+	private getSource(path: string): SourceRow | undefined {
+		const row = this.db.prepare("SELECT * FROM sources WHERE path = ?").get(path);
+		return row as unknown as SourceRow | undefined;
+	}
+
+	/** Bring one file's rows up to date. Retries once when another writer changed the row meanwhile. */
+	syncFile(path: string): SyncOutcome {
+		for (let attempt = 0; attempt < 2; attempt++) {
+			try {
+				return this.syncOnce(path);
+			} catch (error) {
+				if (!(error instanceof SnapshotConflictError)) throw error;
+			}
+		}
+		return "conflict";
+	}
+
+	private syncOnce(path: string): SyncOutcome {
+		const row = this.getSource(path);
+		const fp = statSessionFile(path);
+		if (!fp) {
+			if (!row) return "skipped";
+			this.transaction(row, path, () => this.db.prepare("DELETE FROM sources WHERE path = ?").run(path));
+			return "removed";
+		}
+		if (row && isUnchanged(row, fp)) return "skipped";
+		// SessionManager writes empty files transiently (header rewrite); keep old rows until content returns.
+		if (fp.size === 0) return this.markPending(row, path, fp, "empty file");
+
+		if (row && this.canAppend(row, fp)) return this.append(row, path, fp);
+		return this.rebuild(row, path, fp);
+	}
+
+	private canAppend(row: SourceRow, fp: FileFingerprint): boolean {
+		if (row.status !== "ok" || row.id_scheme !== "entry" || !isCurrentProjection(row)) return false;
+		if (fp.size < row.indexed_offset || row.header_end === null || row.header_hash === null) return false;
+		if (hashFileRange(row.path, 0, row.header_end) !== row.header_hash) return false;
+		if (row.tail_offset !== null && hashFileRange(row.path, row.tail_offset, row.indexed_offset) !== row.tail_hash) {
+			return false;
+		}
+		return true;
+	}
+
+	private transaction(snapshot: SourceRow | undefined, path: string, body: () => void): void {
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			if (!sameSnapshot(snapshot, this.getSource(path))) throw new SnapshotConflictError();
+			body();
+			this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+	}
+
+	private markPending(row: SourceRow | undefined, path: string, fp: FileFingerprint, reason: string): SyncOutcome {
+		this.transaction(row, path, () => {
+			if (row) {
+				this.db
+					.prepare("UPDATE sources SET status = 'pending', error = ?, indexed_at = ? WHERE path = ?")
+					.run(reason, Date.now(), path);
+			} else {
+				this.insertSource(path, fp, { status: "pending", error: reason });
+			}
+		});
+		return "pending";
+	}
+
+	private insertSource(
+		path: string,
+		fp: FileFingerprint,
+		values: Partial<Omit<SourceRow, "path" | "root" | "size" | "mtime_ms" | "dev_ino">> & {
+			status: SourceRow["status"];
+		},
+	): void {
+		this.db
+			.prepare(
+				`INSERT INTO sources(path, root, session_id, size, mtime_ms, dev_ino, indexed_offset, line_count,
+					header_end, header_hash, tail_offset, tail_hash, header_version, id_scheme, projector_version,
+					status, error, indexed_at)
+				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			)
+			.run(
+				path,
+				this.rootForFile(path),
+				values.session_id ?? null,
+				fp.size,
+				Math.trunc(fp.mtimeMs),
+				fp.devIno,
+				values.indexed_offset ?? 0,
+				values.line_count ?? 0,
+				values.header_end ?? null,
+				values.header_hash ?? null,
+				values.tail_offset ?? null,
+				values.tail_hash ?? null,
+				values.header_version ?? null,
+				values.id_scheme ?? null,
+				values.projector_version ?? null,
+				values.status,
+				values.error ?? null,
+				Date.now(),
+			);
+	}
+
+	/**
+	 * Parse lines into projected entries. A final unterminated line is
+	 * consumed only when it is complete JSON; otherwise a writer may still be
+	 * producing it and it is left for the next sync.
+	 */
+	private parseLines(
+		lines: readonly RawLine[],
+		options: {
+			header?: SessionHeader;
+			firstLineNo: number;
+			summary: SessionSummaryFields;
+			fallbackTs: number;
+			startOffset: number;
+		},
+	): ParsedLines {
+		const result: ParsedLines = {
+			header: options.header as ParsedLines["header"],
+			entries: [],
+			summary: options.summary,
+			consumedTo: options.startOffset,
+			tailOffset: null,
+			lineCount: 0,
+			malformed: 0,
+		};
+		let previousId: string | null = null;
+		let lineNo = options.firstLineNo - 1;
+		for (const line of lines) {
+			lineNo++;
+			const value = parseJsonObjectLine(line.bytes);
+			if (!line.terminated && value === null && line.bytes.toString("utf8").trim()) break;
+			result.lineCount++;
+			result.consumedTo = line.end;
+			if (value === null) {
+				if (line.bytes.toString("utf8").trim()) result.malformed++;
+				continue;
+			}
+			result.tailOffset = line.start;
+			if (!result.header) {
+				if (!isSessionHeader(value)) {
+					result.invalidHeader = true;
+					return result;
+				}
+				result.header = value;
+				result.headerEnd = line.end;
+				continue;
+			}
+			const scheme = entryIdSchemeFor(result.header);
+			const entry = normalizeEntry(value, scheme, lineNo, previousId);
+			if (!entry) continue;
+			previousId = entry.id;
+			foldSessionSummaryEntry(result.summary, entry);
+			const projected = projectEntry(entry, options.fallbackTs);
+			if (projected) result.entries.push(projected);
+		}
+		return result;
+	}
+
+	private rebuild(row: SourceRow | undefined, path: string, fp: FileFingerprint): SyncOutcome {
+		const lines = readLines(path, 0, fp.size);
+		const parsed = this.parseLines(lines, {
+			firstLineNo: 1,
+			summary: createSessionSummary(),
+			fallbackTs: Math.trunc(fp.mtimeMs),
+			startOffset: 0,
+		});
+		if (parsed.invalidHeader) {
+			this.transaction(row, path, () => {
+				this.db.prepare("DELETE FROM sources WHERE path = ?").run(path);
+				this.insertSource(path, fp, { status: "error", error: "first entry is not a session header" });
+			});
+			return "error";
+		}
+		const header = parsed.header;
+		// No complete header yet: the file is being created or rewritten.
+		if (!header || parsed.headerEnd === undefined) return this.markPending(row, path, fp, "incomplete header");
+
+		const headerEnd = parsed.headerEnd;
+		const headerHash = hashFileRange(path, 0, headerEnd);
+		const createdAt = Date.parse(header.timestamp);
+		const tailHash = parsed.tailOffset !== null ? hashFileRange(path, parsed.tailOffset, parsed.consumedTo) : null;
+		this.transaction(row, path, () => {
+			this.db.prepare("DELETE FROM sources WHERE path = ?").run(path);
+			this.insertSource(path, fp, {
+				status: "ok",
+				error: parsed.malformed > 0 ? `skipped ${parsed.malformed} malformed line(s)` : null,
+				indexed_offset: parsed.consumedTo,
+				line_count: parsed.lineCount,
+				header_end: headerEnd,
+				header_hash: headerHash,
+				tail_offset: parsed.tailOffset,
+				tail_hash: tailHash,
+				session_id: header.id,
+				header_version: headerVersion(header),
+				id_scheme: entryIdSchemeFor(header),
+				projector_version: PROJECTOR_VERSION,
+			});
+			const sessionRow = this.db
+				.prepare(
+					`INSERT INTO sessions(path, session_id, cwd, name, parent_session, created_at, modified_at,
+						last_activity_at, message_count, first_message)
+					VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING sid`,
+				)
+				.get(
+					path,
+					header.id,
+					typeof header.cwd === "string" ? header.cwd : "",
+					parsed.summary.name ?? null,
+					typeof header.parentSession === "string" ? header.parentSession : null,
+					Number.isNaN(createdAt) ? Math.trunc(fp.mtimeMs) : createdAt,
+					resolveSessionModifiedTime(header, parsed.summary.lastActivityTime, Math.trunc(fp.mtimeMs)),
+					parsed.summary.lastActivityTime ?? null,
+					parsed.summary.messageCount,
+					parsed.summary.firstMessage || null,
+				);
+			this.insertEntries(num(sessionRow?.sid), parsed.entries);
+		});
+		return "indexed";
+	}
+
+	private append(row: SourceRow, path: string, fp: FileFingerprint): SyncOutcome {
+		const session = this.db
+			.prepare(
+				"SELECT sid, session_id, cwd, name, created_at, last_activity_at, message_count, first_message FROM sessions WHERE path = ?",
+			)
+			.get(path) as unknown as SessionRow | undefined;
+		if (!session) return this.rebuild(row, path, fp);
+		const summary: SessionSummaryFields = {
+			name: session.name ?? undefined,
+			firstMessage: session.first_message ?? "",
+			messageCount: session.message_count,
+			lastActivityTime: session.last_activity_at ?? undefined,
+		};
+		const lines = readLines(path, row.indexed_offset, fp.size);
+		const parsed = this.parseLines(lines, {
+			// Only the entry id scheme appends, so the header is needed only to select it.
+			header: { type: "session", id: session.session_id, timestamp: "", cwd: session.cwd, version: 3 },
+			firstLineNo: row.line_count + 1,
+			summary,
+			fallbackTs: Math.trunc(fp.mtimeMs),
+			startOffset: row.indexed_offset,
+		});
+		const tailOffset = parsed.tailOffset ?? row.tail_offset;
+		const tailHash =
+			parsed.tailOffset !== null ? hashFileRange(path, parsed.tailOffset, parsed.consumedTo) : row.tail_hash;
+		const fallbackMtime = Math.trunc(fp.mtimeMs);
+		const modifiedAt =
+			typeof summary.lastActivityTime === "number" && summary.lastActivityTime > 0
+				? summary.lastActivityTime
+				: session.created_at;
+		const malformedNote = parsed.malformed > 0 ? `skipped ${parsed.malformed} malformed line(s)` : row.error;
+		this.transaction(row, path, () => {
+			this.db
+				.prepare(
+					`UPDATE sources SET size = ?, mtime_ms = ?, dev_ino = ?, indexed_offset = ?, line_count = ?,
+						tail_offset = ?, tail_hash = ?, projector_version = min(projector_version, ?), error = ?,
+						indexed_at = ? WHERE path = ?`,
+				)
+				.run(
+					fp.size,
+					fallbackMtime,
+					fp.devIno,
+					parsed.consumedTo,
+					row.line_count + parsed.lineCount,
+					tailOffset,
+					tailHash,
+					// Appending with an older projector marks the file for a newer binary to re-project.
+					PROJECTOR_VERSION,
+					malformedNote,
+					Date.now(),
+					path,
+				);
+			this.db
+				.prepare(
+					`UPDATE sessions SET name = ?, modified_at = ?, last_activity_at = ?, message_count = ?, first_message = ?
+					WHERE sid = ?`,
+				)
+				.run(
+					summary.name ?? null,
+					modifiedAt,
+					summary.lastActivityTime ?? null,
+					summary.messageCount,
+					summary.firstMessage || null,
+					session.sid,
+				);
+			this.insertEntries(session.sid, parsed.entries);
+		});
+		return "appended";
+	}
+
+	private insertEntries(sid: number, entries: readonly ProjectedEntry[]): void {
+		if (entries.length === 0) return;
+		// OR IGNORE: duplicate ids in a damaged file keep the first occurrence, as SessionManager does.
+		const insert = this.db.prepare(
+			"INSERT OR IGNORE INTO entries(sid, entry_id, parent_id, entry_type, role, ts, text) VALUES (?, ?, ?, ?, ?, ?, ?)",
+		);
+		for (const entry of entries) {
+			insert.run(sid, entry.entryId, entry.parentId, entry.type, entry.role, entry.ts, entry.text);
+		}
+	}
+
+	/**
+	 * Compare every root with the sources table. Rows are deleted only when
+	 * their root was listed successfully and the file is gone.
+	 */
+	planReconcile(): ReconcilePlan {
+		const candidates: { path: string; mtimeMs: number }[] = [];
+		let total = 0;
+		let removed = 0;
+		const directories = new Map<string, TrackedDirectory>();
+		for (const root of this.listRoots()) {
+			let scan: SessionRootScan;
+			try {
+				scan = scanSessionRoot(root.path);
+			} catch {
+				// Unreadable root (permissions, network mount): keep its rows rather than treat them as deleted.
+				continue;
+			}
+			for (const [path, mtimeMs] of scan.directories) {
+				directories.set(path, { mtimeMs, isRoot: path === root.path });
+			}
+			const files = scan.files;
+			const known = new Map<string, SourceRow>();
+			for (const row of this.db.prepare("SELECT * FROM sources WHERE root = ?").all(root.path)) {
+				known.set(String(row.path), row as unknown as SourceRow);
+			}
+			for (const file of files) {
+				const fp = statSessionFile(file);
+				if (!fp) continue;
+				total++;
+				const row = known.get(file);
+				known.delete(file);
+				if (!row || !isUnchanged(row, fp)) candidates.push({ path: file, mtimeMs: fp.mtimeMs });
+			}
+			for (const missing of known.keys()) {
+				if (statSessionFile(missing)) continue;
+				this.db.prepare("DELETE FROM sources WHERE path = ?").run(missing);
+				removed++;
+			}
+		}
+		candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+		// Seeded from the listing that produced this plan, so refreshRecent only reports directories changed since.
+		this.directories = directories;
+		return { toSync: candidates.map((candidate) => candidate.path), total, removed };
+	}
+
+	/**
+	 * Cheap pre-query freshness pass: re-sync the most recently modified known
+	 * files, then pick up files created in directories whose mtime moved since
+	 * the last reconcile. Deletions are left to the next reconcile. Returns
+	 * false when the deadline cut the pass short.
+	 */
+	refreshRecent(deadline: number, sync: (path: string) => void, recentLimit = REFRESH_RECENT_FILES): boolean {
+		const recent = this.db.prepare("SELECT path FROM sources ORDER BY mtime_ms DESC LIMIT ?").all(recentLimit);
+		for (const row of recent) {
+			if (Date.now() >= deadline) return false;
+			sync(String(row.path));
+		}
+		// Roots missing or unreadable at the last reconcile still need watching: SessionManager creates them lazily.
+		for (const root of this.listRoots()) {
+			if (!this.directories.has(root.path)) this.directories.set(root.path, { mtimeMs: -1, isRoot: true });
+		}
+		// Live iteration: subdirectories discovered under a root below are visited later in this same pass.
+		for (const [directory, tracked] of this.directories) {
+			if (Date.now() >= deadline) return false;
+			let complete: boolean;
+			try {
+				complete = this.refreshDirectory(directory, tracked, deadline, sync);
+			} catch {
+				// Unreadable directory (permissions, network mount): the search goes ahead and the next pass retries it.
+				continue;
+			}
+			if (!complete) return false;
+		}
+		return true;
+	}
+
+	private refreshDirectory(
+		directory: string,
+		tracked: TrackedDirectory,
+		deadline: number,
+		sync: (path: string) => void,
+	): boolean {
+		const mtimeMs = statDirectoryMtime(directory);
+		if (mtimeMs === null) {
+			if (!tracked.isRoot) this.directories.delete(directory);
+			return true;
+		}
+		if (mtimeMs === tracked.mtimeMs) return true;
+		if (tracked.isRoot) {
+			for (const child of listSubdirectories(directory)) {
+				// -1 never equals a real mtime, so a new directory is always listed.
+				if (!this.directories.has(child)) this.directories.set(child, { mtimeMs: -1, isRoot: false });
+			}
+		}
+		for (const file of listJsonlFiles(directory) ?? []) {
+			if (Date.now() >= deadline) return false;
+			const row = this.getSource(file);
+			const fp = row ? statSessionFile(file) : undefined;
+			if (!row || (fp && !isUnchanged(row, fp))) sync(file);
+		}
+		// Recorded only once the directory was fully processed; a cut-short pass retries it.
+		this.directories.set(directory, { mtimeMs, isRoot: tracked.isRoot });
+		return true;
+	}
+
+	/** Drop every indexed session while keeping registered roots. */
+	clearSources(): void {
+		this.db.exec("DELETE FROM sources");
+	}
+
+	counts(): { total: number; indexed: number; pending: number; errors: number } {
+		const row = this.db
+			.prepare(
+				`SELECT count(*) AS total,
+					coalesce(sum(status = 'ok'), 0) AS indexed,
+					coalesce(sum(status = 'pending'), 0) AS pending,
+					coalesce(sum(status = 'error'), 0) AS errors
+				FROM sources`,
+			)
+			.get();
+		return {
+			total: num(row?.total ?? 0),
+			indexed: num(row?.indexed ?? 0),
+			pending: num(row?.pending ?? 0),
+			errors: num(row?.errors ?? 0),
+		};
+	}
+
+	coverage(discoveredTotal: number): SessionIndexCoverage {
+		const counts = this.counts();
+		return { indexed: counts.indexed, total: Math.max(counts.total, discoveredTotal) };
+	}
+
+	search(query: SessionIndexQuery, now = Date.now()): SessionIndexHit[] {
+		const tokens = query.text.trim().split(/\s+/u).filter(Boolean);
+		const limit = Math.max(0, Math.floor(query.limit));
+		if (tokens.length === 0 || limit === 0) return [];
+		return tokens.every((token) => [...token].length >= MIN_FTS_QUERY_CHARS)
+			? this.searchFts(query, tokens, limit)
+			: this.searchShort(query, tokens, limit, now);
+	}
+
+	private entryTypeFilter(query: SessionIndexQuery, column: string, params: SQLInputValue[]): string {
+		if (!query.entryTypes) return "";
+		if (query.entryTypes.length === 0) return " AND 0";
+		params.push(...query.entryTypes);
+		return ` AND ${column} IN (${query.entryTypes.map(() => "?").join(", ")})`;
+	}
+
+	private searchFts(query: SessionIndexQuery, tokens: readonly string[], limit: number): SessionIndexHit[] {
+		const match = tokens.map(ftsPhrase).join(" AND ");
+		const hits: SessionIndexHit[] = [];
+
+		if (!query.entryTypes) {
+			const params: SQLInputValue[] = [SNIPPET_MATCH_START, SNIPPET_MATCH_END, match];
+			let where = "sessions_fts MATCH ?";
+			if (query.cwd !== undefined) {
+				where += " AND s.cwd = ?";
+				params.push(query.cwd);
+			}
+			if (query.since !== undefined) {
+				where += " AND s.modified_at >= ?";
+				params.push(query.since);
+			}
+			params.push(limit);
+			const rows = this.db
+				.prepare(
+					`SELECT s.path, s.session_id, s.cwd, s.modified_at,
+						snippet(sessions_fts, -1, ?, ?, '…', ${FTS_SNIPPET_TOKENS}) AS snippet, bm25(sessions_fts) AS score
+					FROM sessions_fts JOIN sessions s ON s.sid = sessions_fts.rowid
+					WHERE ${where} ORDER BY score LIMIT ?`,
+				)
+				.all(...params);
+			for (const row of rows) {
+				hits.push({
+					sessionPath: String(row.path),
+					sessionId: String(row.session_id),
+					cwd: String(row.cwd),
+					entryId: null,
+					entryType: "session",
+					ts: num(row.modified_at),
+					snippet: String(row.snippet),
+					score: Number(row.score),
+				});
+			}
+		}
+
+		const params: SQLInputValue[] = [SNIPPET_MATCH_START, SNIPPET_MATCH_END, match];
+		let where = "entries_fts MATCH ?";
+		if (query.cwd !== undefined) {
+			where += " AND s.cwd = ?";
+			params.push(query.cwd);
+		}
+		if (query.since !== undefined) {
+			where += " AND e.ts >= ?";
+			params.push(query.since);
+		}
+		where += this.entryTypeFilter(query, "e.entry_type", params);
+		params.push(limit);
+		const rows = this.db
+			.prepare(
+				`SELECT s.path, s.session_id, s.cwd, e.entry_id, e.entry_type, e.role, e.ts,
+					snippet(entries_fts, 0, ?, ?, '…', ${FTS_SNIPPET_TOKENS}) AS snippet, bm25(entries_fts) AS score
+				FROM entries_fts JOIN entries e ON e.eid = entries_fts.rowid JOIN sessions s ON s.sid = e.sid
+				WHERE ${where} ORDER BY score LIMIT ?`,
+			)
+			.all(...params);
+		for (const row of rows) {
+			hits.push({
+				sessionPath: String(row.path),
+				sessionId: String(row.session_id),
+				cwd: String(row.cwd),
+				entryId: String(row.entry_id),
+				entryType: String(row.entry_type),
+				role: row.role === null ? undefined : String(row.role),
+				ts: num(row.ts),
+				snippet: String(row.snippet),
+				score: Number(row.score),
+			});
+		}
+		return hits.slice(0, limit);
+	}
+
+	/**
+	 * Queries with a token shorter than a trigram scan `entries.text` with LIKE,
+	 * bounded to recent sessions so cost stays independent of history size.
+	 */
+	private searchShort(
+		query: SessionIndexQuery,
+		tokens: readonly string[],
+		requestedLimit: number,
+		now: number,
+	): SessionIndexHit[] {
+		const limit = Math.min(requestedLimit, SHORT_QUERY_MAX_HITS);
+		const since = query.since ?? (query.cwd === undefined ? now - SHORT_QUERY_DEFAULT_WINDOW_MS : undefined);
+		const candidateParams: SQLInputValue[] = [];
+		const candidateWhere: string[] = [];
+		if (query.cwd !== undefined) {
+			candidateWhere.push("cwd = ?");
+			candidateParams.push(query.cwd);
+		}
+		if (since !== undefined) {
+			candidateWhere.push("modified_at >= ?");
+			candidateParams.push(since);
+		}
+		const candidates = `SELECT sid FROM sessions WHERE ${candidateWhere.join(" AND ")}
+			ORDER BY modified_at DESC LIMIT ${SHORT_QUERY_MAX_SESSIONS}`;
+		const patterns = tokens.map((token) => `%${escapeLike(token)}%`);
+		const hits: SessionIndexHit[] = [];
+
+		if (!query.entryTypes) {
+			const titleMatch = patterns
+				.map(() => "(coalesce(s.name, '') LIKE ? ESCAPE '\\' OR coalesce(s.first_message, '') LIKE ? ESCAPE '\\')")
+				.join(" AND ");
+			const rows = this.db
+				.prepare(
+					`SELECT s.path, s.session_id, s.cwd, s.name, s.first_message, s.modified_at
+					FROM sessions s WHERE s.sid IN (${candidates}) AND ${titleMatch}
+					ORDER BY s.modified_at DESC LIMIT ?`,
+				)
+				.all(...candidateParams, ...patterns.flatMap((pattern) => [pattern, pattern]), limit);
+			for (const row of rows) {
+				const title = row.name === null ? "" : String(row.name);
+				const text = tokens.some((token) => title.toLowerCase().includes(token.toLowerCase()))
+					? title
+					: String(row.first_message ?? "");
+				hits.push({
+					sessionPath: String(row.path),
+					sessionId: String(row.session_id),
+					cwd: String(row.cwd),
+					entryId: null,
+					entryType: "session",
+					ts: num(row.modified_at),
+					snippet: textSnippet(text, tokens),
+					score: 0,
+				});
+			}
+		}
+
+		const params: SQLInputValue[] = [...candidateParams, ...patterns];
+		let where = `e.sid IN (${candidates}) AND ${patterns.map(() => "e.text LIKE ? ESCAPE '\\'").join(" AND ")}`;
+		if (since !== undefined) {
+			where += " AND e.ts >= ?";
+			params.push(since);
+		}
+		where += this.entryTypeFilter(query, "e.entry_type", params);
+		params.push(limit);
+		const rows = this.db
+			.prepare(
+				`SELECT s.path, s.session_id, s.cwd, e.entry_id, e.entry_type, e.role, e.ts, e.text
+				FROM entries e JOIN sessions s ON s.sid = e.sid
+				WHERE ${where} ORDER BY e.ts DESC LIMIT ?`,
+			)
+			.all(...params);
+		for (const row of rows) {
+			hits.push({
+				sessionPath: String(row.path),
+				sessionId: String(row.session_id),
+				cwd: String(row.cwd),
+				entryId: String(row.entry_id),
+				entryType: String(row.entry_type),
+				role: row.role === null ? undefined : String(row.role),
+				ts: num(row.ts),
+				snippet: textSnippet(String(row.text), tokens),
+				score: 0,
+			});
+		}
+		return hits.slice(0, limit);
+	}
+
+	listSessions(query: SessionListQuery): SessionListPage {
+		const limit = Math.max(1, Math.floor(query.limit));
+		const params: SQLInputValue[] = [];
+		const where: string[] = [];
+		if (query.cwd !== undefined) {
+			where.push("cwd = ?");
+			params.push(query.cwd);
+		}
+		if (query.cursor !== undefined) {
+			const cursor = decodeCursor(query.cursor);
+			if (!cursor) throw new Error("Invalid session list cursor.");
+			where.push("(modified_at < ? OR (modified_at = ? AND sid < ?))");
+			params.push(cursor[0], cursor[0], cursor[1]);
+		}
+		params.push(limit + 1);
+		const rows = this.db
+			.prepare(
+				`SELECT sid, path, session_id, cwd, name, parent_session, created_at, modified_at, message_count, first_message
+				FROM sessions ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+				ORDER BY modified_at DESC, sid DESC LIMIT ?`,
+			)
+			.all(...params);
+		const page = rows.slice(0, limit);
+		const sessions: SessionListItem[] = page.map((row) => ({
+			path: String(row.path),
+			id: String(row.session_id),
+			cwd: String(row.cwd),
+			name: row.name === null ? undefined : String(row.name),
+			parentSessionPath: row.parent_session === null ? undefined : String(row.parent_session),
+			created: new Date(num(row.created_at)),
+			modified: new Date(num(row.modified_at)),
+			messageCount: num(row.message_count),
+			firstMessage: row.first_message === null ? "(no messages)" : String(row.first_message),
+		}));
+		const last = page.at(-1);
+		return {
+			sessions,
+			nextCursor: rows.length > limit && last ? encodeCursor(num(last.modified_at), num(last.sid)) : undefined,
+		};
+	}
+}
diff --git a/packages/coding-agent/src/core/session-index/types.ts b/packages/coding-agent/src/core/session-index/types.ts
new file mode 100644
index 00000000..ca8c97a5
--- /dev/null
+++ b/packages/coding-agent/src/core/session-index/types.ts
@@ -0,0 +1,102 @@
+import type { SessionEntry, SessionFilePersistedEvent } from "../session-manager.ts";
+
+export type { SessionFilePersistedEvent };
+
+/** Marks the start and end of a matched span inside {@link SessionIndexHit.snippet}. */
+export const SNIPPET_MATCH_START = "\u0002";
+export const SNIPPET_MATCH_END = "\u0003";
+
+export interface SessionIndexQuery {
+	text: string;
+	/** Only sessions whose header cwd equals this resolved path. */
+	cwd?: string;
+	/** Only entries (and, for short queries, sessions) at or after this epoch-ms time. */
+	since?: number;
+	limit: number;
+	/** Product v3 entry types to search. Title hits are included only when omitted. */
+	entryTypes?: readonly SessionEntry["type"][];
+}
+
+export interface SessionIndexHit {
+	sessionPath: string;
+	sessionId: string;
+	cwd: string;
+	/** Null for session-level hits: title matches and every JSONL-scan fallback hit. */
+	entryId: string | null;
+	entryType?: string;
+	role?: string;
+	ts: number;
+	/** Excerpt with matches wrapped in SNIPPET_MATCH_START / SNIPPET_MATCH_END. */
+	snippet: string;
+	/** Lower is better (bm25); 0 when results are ordered by time. */
+	score: number;
+}
+
+export interface SessionIndexCoverage {
+	indexed: number;
+	total: number;
+}
+
+export interface SessionIndexHitBatch {
+	hits: SessionIndexHit[];
+	coverage: SessionIndexCoverage;
+}
+
+export interface SessionListItem {
+	path: string;
+	id: string;
+	cwd: string;
+	name?: string;
+	parentSessionPath?: string;
+	created: Date;
+	modified: Date;
+	messageCount: number;
+	firstMessage: string;
+}
+
+export interface SessionListQuery {
+	cwd?: string;
+	limit: number;
+	cursor?: string;
+}
+
+export interface SessionListPage {
+	sessions: SessionListItem[];
+	nextCursor?: string;
+}
+
+export interface SessionIndexStatus {
+	state: "ready" | "backfilling" | "degraded";
+	indexed: number;
+	total: number;
+	pending: number;
+	errors: number;
+	degradedReason?: string;
+	dbPath?: string;
+}
+
+export interface ReindexProgress {
+	indexed: number;
+	total: number;
+	done: boolean;
+}
+
+export interface ReindexOptions {
+	/** Drop every indexed session and rebuild from the JSONL files. */
+	full?: boolean;
+	signal?: AbortSignal;
+}
+
+/** Search and list sessions through a derived index. JSONL files stay authoritative. */
+export interface SessionIndex {
+	search(query: SessionIndexQuery, signal?: AbortSignal): AsyncIterable<SessionIndexHitBatch>;
+	listSessions(query: SessionListQuery, signal?: AbortSignal): Promise<SessionListPage>;
+	status(): Promise<SessionIndexStatus>;
+	/** Schedule a sync for a written session file. Debounced per path. */
+	notifyPersisted(event: SessionFilePersistedEvent): void;
+	/** Register a session directory, e.g. one passed with --session-dir. */
+	addRoot(dir: string): Promise<void>;
+	reindex(options?: ReindexOptions): AsyncIterable<ReindexProgress>;
+	/** Wait for the in-flight batch, roll back open transactions, and stop the worker. */
+	close(): Promise<void>;
+}
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index a1f05598..260fc0af 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -26,6 +26,7 @@ import {
 	createCompactionSummaryMessage,
 	createCustomMessage,
 } from "./messages.ts";
+import { createSessionSummary, foldSessionSummaryEntry, resolveSessionModifiedTime } from "./session-summary.ts";
 import { createUsageLineage } from "./usage-lineage.ts";
 
 export const CURRENT_SESSION_VERSION = 3;
@@ -188,6 +189,14 @@ export interface SessionInfo {
 	allMessagesText: string;
 }
 
+/** A session file was written: created, appended to, or rewritten in place. */
+export interface SessionFilePersistedEvent {
+	path: string;
+	kind: "create" | "append" | "rewrite";
+}
+
+export type SessionFilePersistedListener = (event: SessionFilePersistedEvent) => void;
+
 export type ReadonlySessionManager = Pick<
 	SessionManager,
 	| "getCwd"
@@ -657,44 +666,15 @@ export function findMostRecentSession(sessionDir: string, cwd?: string): string
 	}
 }
 
-function isMessageWithContent(message: AgentMessage): message is Message {
-	return typeof (message as Message).role === "string" && "content" in message;
-}
-
-function extractTextContent(message: Message): string {
-	const content = message.content;
-	if (typeof content === "string") {
-		return content;
-	}
-	return content
-		.filter((block): block is TextContent => block.type === "text")
-		.map((block) => block.text)
-		.join(" ");
-}
-
-function getMessageActivityTime(entry: SessionMessageEntry): number | undefined {
-	const message = entry.message;
-	if (!isMessageWithContent(message)) return undefined;
-	if (message.role !== "user" && message.role !== "assistant") return undefined;
-
-	const msgTimestamp = (message as { timestamp?: number }).timestamp;
-	if (typeof msgTimestamp === "number") {
-		return msgTimestamp;
-	}
-
-	const t = new Date(entry.timestamp).getTime();
-	return Number.isNaN(t) ? undefined : t;
-}
-
 async function buildSessionInfo(filePath: string): Promise<SessionInfo | null> {
 	try {
 		const stats = await stat(filePath);
 		let header: SessionHeader | null = null;
-		let messageCount = 0;
-		let firstMessage = "";
+		const summary = createSessionSummary();
 		const allMessages: string[] = [];
-		let name: string | undefined;
-		let lastActivityTime: number | undefined;
+		const collectText = (text: string): void => {
+			allMessages.push(text);
+		};
 
 		const rl = createInterface({
 			input: createReadStream(filePath, { encoding: "utf8" }),
@@ -711,54 +691,24 @@ async function buildSessionInfo(filePath: string): Promise<SessionInfo | null> {
 				continue;
 			}
 
-			// Extract session name (use latest, including explicit clears)
-			if (entry.type === "session_info") {
-				name = entry.name?.trim() || undefined;
-			}
-
-			if (entry.type !== "message") continue;
-			messageCount++;
-
-			const activityTime = getMessageActivityTime(entry);
-			if (typeof activityTime === "number") {
-				lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
-			}
-
-			const message = entry.message;
-			if (!isMessageWithContent(message)) continue;
-			if (message.role !== "user" && message.role !== "assistant") continue;
-
-			const textContent = extractTextContent(message);
-			if (!textContent) continue;
-
-			allMessages.push(textContent);
-			if (!firstMessage && message.role === "user") {
-				firstMessage = textContent;
-			}
+			foldSessionSummaryEntry(summary, entry as SessionEntry, collectText);
 		}
 
 		if (!header) return null;
 
 		const cwd = typeof header.cwd === "string" ? header.cwd : "";
 		const parentSessionPath = header.parentSession;
-		const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : NaN;
-		const modified =
-			typeof lastActivityTime === "number" && lastActivityTime > 0
-				? new Date(lastActivityTime)
-				: !Number.isNaN(headerTime)
-					? new Date(headerTime)
-					: stats.mtime;
 
 		return {
 			path: filePath,
 			id: header.id,
 			cwd,
-			name,
+			name: summary.name,
 			parentSessionPath,
 			created: new Date(header.timestamp),
-			modified,
-			messageCount,
-			firstMessage: firstMessage || "(no messages)",
+			modified: new Date(resolveSessionModifiedTime(header, summary.lastActivityTime, stats.mtime.getTime())),
+			messageCount: summary.messageCount,
+			firstMessage: summary.firstMessage || "(no messages)",
 			allMessagesText: allMessages.join(" "),
 		};
 	} catch {
@@ -866,6 +816,7 @@ export class SessionManager {
 	private labelsById: Map<string, string> = new Map();
 	private labelTimestampsById: Map<string, string> = new Map();
 	private leafId: string | null = null;
+	private filePersistedListener: SessionFilePersistedListener | undefined;
 
 	private constructor(
 		cwd: string,
@@ -988,6 +939,28 @@ export class SessionManager {
 		} finally {
 			closeSync(fd);
 		}
+		this._notifyFilePersisted(this.sessionFile, "rewrite");
+	}
+
+	/**
+	 * Observe successful writes to this manager's session files, e.g. to keep a
+	 * derived search index current. The listener runs synchronously after each
+	 * write; pass undefined to remove it.
+	 */
+	setFilePersistedListener(listener: SessionFilePersistedListener | undefined): void {
+		this.filePersistedListener = listener;
+	}
+
+	private _notifyFilePersisted(path: string, kind: SessionFilePersistedEvent["kind"]): void {
+		const listener = this.filePersistedListener;
+		if (!listener) return;
+		try {
+			listener({ path, kind });
+		} catch {
+			// The write already succeeded and the file stays authoritative. An
+			// observer failure must not fail or roll back the session write;
+			// derived indexes reconcile from the file later.
+		}
 	}
 
 	isPersisted(): boolean {
@@ -1021,6 +994,7 @@ export class SessionManager {
 		if (!hasAssistant) {
 			if (this.flushed) {
 				appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
+				this._notifyFilePersisted(this.sessionFile, "append");
 			} else {
 				// Mark as not flushed so when assistant arrives, all entries get written
 				this.flushed = false;
@@ -1038,8 +1012,10 @@ export class SessionManager {
 				closeSync(fd);
 			}
 			this.flushed = true;
+			this._notifyFilePersisted(this.sessionFile, "create");
 		} else {
 			appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
+			this._notifyFilePersisted(this.sessionFile, "append");
 		}
 	}
 
diff --git a/packages/coding-agent/src/core/session-summary.ts b/packages/coding-agent/src/core/session-summary.ts
new file mode 100644
index 00000000..98a61248
--- /dev/null
+++ b/packages/coding-agent/src/core/session-summary.ts
@@ -0,0 +1,108 @@
+import type { AgentMessage } from "@step-harness/agent-core";
+import type { Message, TextContent } from "@step-harness/providers";
+import type { SessionEntry, SessionHeader, SessionMessageEntry } from "./session-manager.ts";
+
+/**
+ * Session list fields derived from entries. SessionManager.list() and the
+ * session index both fold entries through this module so the two lists agree.
+ * Kept free of runtime imports because the index worker loads it directly.
+ */
+export interface SessionSummaryFields {
+	/** Latest session_info name; an empty name clears it. */
+	name: string | undefined;
+	/** First non-empty user text, or "" when there is none. */
+	firstMessage: string;
+	messageCount: number;
+	/** Latest user/assistant activity time in epoch milliseconds. */
+	lastActivityTime: number | undefined;
+}
+
+export function createSessionSummary(): SessionSummaryFields {
+	return { name: undefined, firstMessage: "", messageCount: 0, lastActivityTime: undefined };
+}
+
+function isMessageWithContent(message: AgentMessage): message is Message {
+	return typeof (message as Message).role === "string" && "content" in message;
+}
+
+/** Join the text blocks of a user or assistant message; other blocks are ignored. */
+export function extractMessageText(message: Message): string {
+	const content = message.content;
+	if (typeof content === "string") {
+		return content;
+	}
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((block): block is TextContent => block?.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join(" ");
+}
+
+/** Activity time of a user/assistant message, preferring the message's own timestamp. */
+export function getMessageActivityTime(entry: SessionMessageEntry): number | undefined {
+	const message = entry.message;
+	if (!message || !isMessageWithContent(message)) return undefined;
+	if (message.role !== "user" && message.role !== "assistant") return undefined;
+
+	const msgTimestamp = (message as { timestamp?: number }).timestamp;
+	if (typeof msgTimestamp === "number") {
+		return msgTimestamp;
+	}
+
+	const t = new Date(entry.timestamp).getTime();
+	return Number.isNaN(t) ? undefined : t;
+}
+
+/**
+ * Fold one entry into a summary. `onMessageText` receives each non-empty
+ * user/assistant text in file order.
+ */
+export function foldSessionSummaryEntry(
+	summary: SessionSummaryFields,
+	entry: SessionEntry,
+	onMessageText?: (text: string) => void,
+): void {
+	if (entry.type === "session_info") {
+		summary.name = entry.name?.trim() || undefined;
+	}
+
+	if (entry.type !== "message") return;
+	summary.messageCount++;
+
+	const activityTime = getMessageActivityTime(entry);
+	if (typeof activityTime === "number") {
+		summary.lastActivityTime = Math.max(summary.lastActivityTime ?? 0, activityTime);
+	}
+
+	const message = entry.message;
+	if (!message || !isMessageWithContent(message)) return;
+	if (message.role !== "user" && message.role !== "assistant") return;
+
+	const textContent = extractMessageText(message);
+	if (!textContent) return;
+
+	onMessageText?.(textContent);
+	if (!summary.firstMessage && message.role === "user") {
+		summary.firstMessage = textContent;
+	}
+}
+
+export function summarizeSessionEntries(entries: readonly SessionEntry[]): SessionSummaryFields {
+	const summary = createSessionSummary();
+	for (const entry of entries) foldSessionSummaryEntry(summary, entry);
+	return summary;
+}
+
+/**
+ * The list's "modified" time: last activity, else the header timestamp, else
+ * the file mtime.
+ */
+export function resolveSessionModifiedTime(
+	header: Pick<SessionHeader, "timestamp">,
+	lastActivityTime: number | undefined,
+	fallbackMtimeMs: number,
+): number {
+	if (typeof lastActivityTime === "number" && lastActivityTime > 0) return lastActivityTime;
+	const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : Number.NaN;
+	return Number.isNaN(headerTime) ? fallbackMtimeMs : headerTime;
+}
diff --git a/packages/coding-agent/src/index.ts b/packages/coding-agent/src/index.ts
index 1205780e..859c77e0 100644
--- a/packages/coding-agent/src/index.ts
+++ b/packages/coding-agent/src/index.ts
@@ -311,7 +311,12 @@ export {
 } from "./core/sdk.ts";
 export { formatMissingSessionCwdPrompt, MissingSessionCwdError } from "./core/session-cwd.ts";
 export { exportSessionToJsonl } from "./core/session-export.ts";
-export type { SessionListProgress } from "./core/session-manager.ts";
+export * from "./core/session-index/index.ts";
+export type {
+	SessionFilePersistedEvent,
+	SessionFilePersistedListener,
+	SessionListProgress,
+} from "./core/session-manager.ts";
 export {
 	type BranchSummaryEntry,
 	buildContextEntries,
@@ -542,6 +547,17 @@ export { type RenderDiffOptions, renderDiff } from "./render/diff.ts";
 export { DynamicBorder } from "./render/dynamic-border.ts";
 export { formatKeyText, keyDisplayText, keyHint, keyText, rawKeyHint } from "./render/keybinding-hints.ts";
 export { truncateToVisualLines, type VisualTruncateResult } from "./render/visual-truncate.ts";
+export {
+	createSessionSearchService,
+	parseSearchQueryParams,
+	parseSessionListParams,
+	SESSION_SEARCH_METHODS,
+	type SessionListItemWire,
+	type SessionListPageWire,
+	type SessionSearchMethod,
+	SessionSearchRequestError,
+	type SessionSearchService,
+} from "./server/session-search-service.ts";
 export {
 	getLegacyStepAuthPath,
 	getStepAuthPath,
diff --git a/packages/coding-agent/src/server/session-search-service.ts b/packages/coding-agent/src/server/session-search-service.ts
new file mode 100644
index 00000000..7912bca6
--- /dev/null
+++ b/packages/coding-agent/src/server/session-search-service.ts
@@ -0,0 +1,181 @@
+import { isAbsolute, resolve } from "node:path";
+import type {
+	SessionIndex,
+	SessionIndexHitBatch,
+	SessionIndexQuery,
+	SessionIndexStatus,
+	SessionListItem,
+	SessionListQuery,
+} from "../core/session-index/index.ts";
+import type { SessionEntry } from "../core/session-manager.ts";
+
+/**
+ * Transport-neutral host methods over the session index. A Web or Desktop
+ * host maps its own framing (HTTP, stdio frames) onto {@link SessionSearchService.call};
+ * params arrive as untrusted JSON and are validated here, results are JSON-safe.
+ */
+
+export const SESSION_SEARCH_METHODS = ["search.query", "sessions.list", "index.status"] as const;
+export type SessionSearchMethod = (typeof SESSION_SEARCH_METHODS)[number];
+
+export const SEARCH_QUERY_DEFAULT_LIMIT = 20;
+export const SEARCH_QUERY_MAX_LIMIT = 100;
+export const SEARCH_QUERY_MAX_CHARS = 500;
+export const SESSIONS_LIST_DEFAULT_LIMIT = 50;
+export const SESSIONS_LIST_MAX_LIMIT = 200;
+
+const SEARCHABLE_ENTRY_TYPES: ReadonlySet<string> = new Set<SessionEntry["type"]>([
+	"message",
+	"thinking_level_change",
+	"model_change",
+	"compaction",
+	"branch_summary",
+	"custom",
+	"custom_message",
+	"label",
+	"session_info",
+]);
+
+export class SessionSearchRequestError extends Error {
+	readonly code: "unknown_method" | "invalid_params";
+
+	constructor(code: "unknown_method" | "invalid_params", message: string) {
+		super(message);
+		this.name = "SessionSearchRequestError";
+		this.code = code;
+	}
+}
+
+/** {@link SessionListItem} with epoch-ms times so it survives JSON encoding. */
+export interface SessionListItemWire extends Omit<SessionListItem, "created" | "modified"> {
+	created: number;
+	modified: number;
+}
+
+export interface SessionListPageWire {
+	sessions: SessionListItemWire[];
+	nextCursor?: string;
+}
+
+export interface SessionSearchService {
+	/** search.query: hit batches in arrival order, each with the coverage at that point. */
+	searchQuery(params: unknown, signal?: AbortSignal): AsyncIterable<SessionIndexHitBatch>;
+	/** sessions.list: newest first; pass nextCursor back for the next page. */
+	listSessions(params: unknown, signal?: AbortSignal): Promise<SessionListPageWire>;
+	/** index.status */
+	indexStatus(): Promise<SessionIndexStatus>;
+	/** Dispatch by method name. Non-streaming methods yield exactly one result. */
+	call(method: string, params: unknown, signal?: AbortSignal): AsyncIterable<unknown>;
+}
+
+function invalid(message: string): SessionSearchRequestError {
+	return new SessionSearchRequestError("invalid_params", message);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	if (value === undefined || value === null) return {};
+	if (typeof value !== "object" || Array.isArray(value)) throw invalid("params must be an object.");
+	return value as Record<string, unknown>;
+}
+
+function optionalLimit(value: unknown, fallback: number, max: number): number {
+	if (value === undefined) return fallback;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > max) {
+		throw invalid(`limit must be an integer between 1 and ${max}.`);
+	}
+	return value;
+}
+
+function optionalCwd(value: unknown): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || !isAbsolute(value)) throw invalid("cwd must be an absolute path.");
+	return resolve(value);
+}
+
+export function parseSearchQueryParams(value: unknown): SessionIndexQuery {
+	const params = asRecord(value);
+	const text = params.q;
+	if (typeof text !== "string" || text.trim().length === 0) throw invalid("q must be a non-empty string.");
+	if ([...text].length > SEARCH_QUERY_MAX_CHARS)
+		throw invalid(`q must be at most ${SEARCH_QUERY_MAX_CHARS} characters.`);
+	const query: SessionIndexQuery = {
+		text,
+		limit: optionalLimit(params.limit, SEARCH_QUERY_DEFAULT_LIMIT, SEARCH_QUERY_MAX_LIMIT),
+	};
+	const cwd = optionalCwd(params.cwd);
+	if (cwd !== undefined) query.cwd = cwd;
+	if (params.since !== undefined) {
+		if (typeof params.since !== "number" || !Number.isFinite(params.since) || params.since < 0) {
+			throw invalid("since must be a non-negative epoch-ms number.");
+		}
+		query.since = params.since;
+	}
+	if (params.entryTypes !== undefined) {
+		const types = params.entryTypes;
+		if (
+			!Array.isArray(types) ||
+			!types.every((type) => typeof type === "string" && SEARCHABLE_ENTRY_TYPES.has(type))
+		) {
+			throw invalid(`entryTypes must be an array of: ${[...SEARCHABLE_ENTRY_TYPES].join(", ")}.`);
+		}
+		query.entryTypes = types as SessionEntry["type"][];
+	}
+	return query;
+}
+
+export function parseSessionListParams(value: unknown): SessionListQuery {
+	const params = asRecord(value);
+	const query: SessionListQuery = {
+		limit: optionalLimit(params.limit, SESSIONS_LIST_DEFAULT_LIMIT, SESSIONS_LIST_MAX_LIMIT),
+	};
+	const cwd = optionalCwd(params.cwd);
+	if (cwd !== undefined) query.cwd = cwd;
+	if (params.cursor !== undefined) {
+		if (typeof params.cursor !== "string" || params.cursor.length === 0) {
+			throw invalid("cursor must be a non-empty string.");
+		}
+		query.cursor = params.cursor;
+	}
+	return query;
+}
+
+function toWire(item: SessionListItem): SessionListItemWire {
+	return { ...item, created: item.created.getTime(), modified: item.modified.getTime() };
+}
+
+function isSessionSearchMethod(method: string): method is SessionSearchMethod {
+	return (SESSION_SEARCH_METHODS as readonly string[]).includes(method);
+}
+
+/** The service does not own the index; the host opens and closes it. */
+export function createSessionSearchService(index: SessionIndex): SessionSearchService {
+	const service: SessionSearchService = {
+		searchQuery(params, signal) {
+			// Validated eagerly so a bad request fails before the caller starts iterating.
+			const query = parseSearchQueryParams(params);
+			return index.search(query, signal);
+		},
+		async listSessions(params, signal) {
+			const page = await index.listSessions(parseSessionListParams(params), signal);
+			return { sessions: page.sessions.map(toWire), nextCursor: page.nextCursor };
+		},
+		indexStatus: () => index.status(),
+		async *call(method, params, signal) {
+			if (!isSessionSearchMethod(method)) {
+				throw new SessionSearchRequestError("unknown_method", `Unknown method: ${method}`);
+			}
+			switch (method) {
+				case "search.query":
+					yield* service.searchQuery(params, signal);
+					return;
+				case "sessions.list":
+					yield await service.listSessions(params, signal);
+					return;
+				case "index.status":
+					yield await service.indexStatus();
+					return;
+			}
+		},
+	};
+	return service;
+}
diff --git a/packages/coding-agent/test/session-index/client.test.ts b/packages/coding-agent/test/session-index/client.test.ts
new file mode 100644
index 00000000..bc57eee9
--- /dev/null
+++ b/packages/coding-agent/test/session-index/client.test.ts
@@ -0,0 +1,189 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { withSessionIndex } from "../../src/core/session-index/attach.ts";
+import { openSessionIndex } from "../../src/core/session-index/client.ts";
+import type { SessionIndex, SessionIndexHitBatch, SessionIndexQuery } from "../../src/core/session-index/types.ts";
+import { type SessionFilePersistedEvent, SessionManager } from "../../src/core/session-manager.ts";
+import { nativeSessionManagerFactory } from "../../src/core/session-manager-factory.ts";
+
+const NOW = Date.now();
+
+function writeSession(path: string, id: string, text: string): void {
+	writeFileSync(
+		path,
+		`${JSON.stringify({ type: "session", version: 3, id, timestamp: new Date(NOW).toISOString(), cwd: "/work/app" })}\n${JSON.stringify(
+			{
+				type: "message",
+				id: "m1",
+				parentId: null,
+				timestamp: new Date(NOW).toISOString(),
+				message: { role: "user", content: text, timestamp: NOW },
+			},
+		)}\n`,
+	);
+}
+
+async function collect(index: SessionIndex, query: SessionIndexQuery): Promise<SessionIndexHitBatch[]> {
+	const batches: SessionIndexHitBatch[] = [];
+	for await (const batch of index.search(query)) batches.push(batch);
+	return batches;
+}
+
+async function waitFor(check: () => Promise<boolean>): Promise<void> {
+	const deadline = Date.now() + 10_000;
+	while (!(await check())) {
+		if (Date.now() > deadline) throw new Error("timed out");
+		await new Promise((resolve) => setTimeout(resolve, 20));
+	}
+}
+
+describe("openSessionIndex", () => {
+	let agentDir: string;
+	let sessionDir: string;
+	let index: SessionIndex | undefined;
+
+	beforeEach(() => {
+		agentDir = mkdtempSync(join(tmpdir(), "session-index-client-"));
+		sessionDir = join(agentDir, "sessions", "--work-app--");
+		mkdirSync(sessionDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await index?.close();
+		index = undefined;
+		rmSync(agentDir, { recursive: true, force: true });
+	});
+
+	it("backfills existing sessions in the worker and serves searches", async () => {
+		writeSession(join(sessionDir, "a.jsonl"), "a", "worker backed search");
+		index = await openSessionIndex({ agentDir });
+		await waitFor(async () => (await index!.status()).indexed === 1);
+
+		const [batch] = await collect(index, { text: "backed", limit: 10 });
+		expect(batch?.hits.some((hit) => hit.entryId === "m1")).toBe(true);
+		expect(batch?.coverage).toEqual({ indexed: 1, total: 1 });
+		expect((await index.status()).state).not.toBe("degraded");
+	});
+
+	it("syncs files reported through notifyPersisted", async () => {
+		index = await openSessionIndex({ agentDir, debounceMs: 5 });
+		const path = join(sessionDir, "b.jsonl");
+		writeSession(path, "b", "notified later");
+		index.notifyPersisted({ path, kind: "create" });
+		await waitFor(async () => {
+			const [batch] = await collect(index!, { text: "notified", limit: 10 });
+			return (batch?.hits.length ?? 0) > 0;
+		});
+		const page = await index.listSessions({ limit: 10 });
+		expect(page.sessions.map((session) => session.id)).toEqual(["b"]);
+		expect(page.sessions[0]?.modified).toBeInstanceOf(Date);
+	});
+
+	it("reports reindex progress", async () => {
+		writeSession(join(sessionDir, "a.jsonl"), "a", "first");
+		writeSession(join(sessionDir, "b.jsonl"), "b", "second");
+		index = await openSessionIndex({ agentDir, backfill: false });
+		const progress = [];
+		for await (const step of index.reindex({ full: true })) progress.push(step);
+		expect(progress.at(-1)).toEqual({ indexed: 2, total: 2, done: true });
+	});
+
+	it("falls back to a JSONL scan when the database belongs to something else", async () => {
+		const dbPath = join(agentDir, "index", "session-search.v1.db");
+		mkdirSync(dirname(dbPath), { recursive: true });
+		const foreign = new DatabaseSync(dbPath);
+		foreign.exec("CREATE TABLE other(x)");
+		foreign.close();
+		writeSession(join(sessionDir, "a.jsonl"), "a", "scan fallback text");
+
+		index = await openSessionIndex({ agentDir });
+		const status = await index.status();
+		expect(status.state).toBe("degraded");
+		expect(status.degradedReason).toMatch(/not a Step session index/u);
+		const [batch] = await collect(index, { text: "fallback", limit: 10 });
+		expect(batch?.hits).toHaveLength(1);
+		expect(batch?.hits[0]?.entryId).toBeNull();
+		expect((await index.listSessions({ limit: 10 })).sessions.map((session) => session.id)).toEqual(["a"]);
+	});
+
+	it("finds files written by another process without a notification", async () => {
+		rmSync(join(agentDir, "sessions"), { recursive: true, force: true });
+		index = await openSessionIndex({ agentDir });
+		await waitFor(async () => (await index!.status()).state === "ready");
+
+		// The default root did not exist when the index opened, as on a fresh install.
+		const otherDir = join(agentDir, "sessions", "--work-other--");
+		mkdirSync(otherDir, { recursive: true });
+		writeSession(join(otherDir, "b.jsonl"), "b", "written elsewhere");
+		const [batch] = await collect(index, { text: "elsewhere", limit: 10 });
+		expect(batch?.hits.some((hit) => hit.sessionId === "b" && hit.entryId === "m1")).toBe(true);
+	});
+
+	it("reports writes from managers built by a wrapped factory", async () => {
+		index = await openSessionIndex({ agentDir, debounceMs: 5, backfill: false });
+		const factory = withSessionIndex(nativeSessionManagerFactory, index);
+		const manager = factory.create("/work/app", sessionDir);
+		manager.appendMessage({ role: "user", content: "wrapped factory write", timestamp: NOW });
+		manager.appendMessage({
+			role: "assistant",
+			content: [{ type: "text", text: "ok" }],
+			api: "faux",
+			provider: "faux",
+			model: "faux",
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: NOW,
+		} as never);
+		await waitFor(async () => {
+			const [batch] = await collect(index!, { text: "wrapped", limit: 10 });
+			return (batch?.hits.length ?? 0) > 0;
+		});
+	});
+});
+
+describe("SessionManager file persisted listener", () => {
+	it("reports create and append and ignores listener failures", () => {
+		const dir = mkdtempSync(join(tmpdir(), "session-persist-"));
+		try {
+			const manager = SessionManager.create("/work/app", dir);
+			const events: SessionFilePersistedEvent["kind"][] = [];
+			manager.setFilePersistedListener((event) => {
+				events.push(event.kind);
+				throw new Error("listener failures must not break writes");
+			});
+			manager.appendMessage({ role: "user", content: "hello", timestamp: NOW });
+			expect(events).toEqual([]);
+			manager.appendMessage({
+				role: "assistant",
+				content: [{ type: "text", text: "hi" }],
+				api: "faux",
+				provider: "faux",
+				model: "faux",
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				stopReason: "stop",
+				timestamp: NOW,
+			} as never);
+			manager.appendSessionInfo("named");
+			expect(events).toEqual(["create", "append"]);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});
diff --git a/packages/coding-agent/test/session-index/service.test.ts b/packages/coding-agent/test/session-index/service.test.ts
new file mode 100644
index 00000000..27235ecc
--- /dev/null
+++ b/packages/coding-agent/test/session-index/service.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import type {
+	SessionIndex,
+	SessionIndexHitBatch,
+	SessionIndexQuery,
+	SessionListQuery,
+} from "../../src/core/session-index/types.ts";
+import {
+	createSessionSearchService,
+	parseSearchQueryParams,
+	parseSessionListParams,
+	SessionSearchRequestError,
+} from "../../src/server/session-search-service.ts";
+
+function fakeIndex(calls: { search: SessionIndexQuery[]; list: SessionListQuery[] }): SessionIndex {
+	return {
+		async *search(query) {
+			calls.search.push(query);
+			yield { hits: [], coverage: { indexed: 1, total: 2 } } satisfies SessionIndexHitBatch;
+		},
+		async listSessions(query) {
+			calls.list.push(query);
+			return {
+				sessions: [
+					{
+						path: "/s/a.jsonl",
+						id: "a",
+						cwd: "/work",
+						created: new Date(1000),
+						modified: new Date(2000),
+						messageCount: 1,
+						firstMessage: "hi",
+					},
+				],
+				nextCursor: "next",
+			};
+		},
+		status: async () => ({ state: "ready", indexed: 1, total: 1, pending: 0, errors: 0 }),
+		notifyPersisted() {},
+		addRoot: async () => {},
+		async *reindex() {},
+		close: async () => {},
+	};
+}
+
+async function all(iterable: AsyncIterable<unknown>): Promise<unknown[]> {
+	const items: unknown[] = [];
+	for await (const item of iterable) items.push(item);
+	return items;
+}
+
+describe("session search service params", () => {
+	it("applies defaults and normalises cwd", () => {
+		expect(parseSearchQueryParams({ q: "migration", cwd: "/work/app/../app" })).toEqual({
+			text: "migration",
+			limit: 20,
+			cwd: "/work/app",
+		});
+		expect(parseSessionListParams(undefined)).toEqual({ limit: 50 });
+	});
+
+	it.each([
+		[{}, /q must/u],
+		[{ q: "  " }, /q must/u],
+		[{ q: "x".repeat(501) }, /at most 500/u],
+		[{ q: "x", limit: 0 }, /limit/u],
+		[{ q: "x", limit: 101 }, /limit/u],
+		[{ q: "x", cwd: "relative" }, /absolute/u],
+		[{ q: "x", since: -1 }, /since/u],
+		[{ q: "x", entryTypes: ["session"] }, /entryTypes/u],
+		["text", /object/u],
+	])("rejects invalid search params %#", (params, message) => {
+		expect(() => parseSearchQueryParams(params)).toThrow(message);
+	});
+
+	it("rejects an empty cursor and an oversized list limit", () => {
+		expect(() => parseSessionListParams({ cursor: "" })).toThrow(SessionSearchRequestError);
+		expect(() => parseSessionListParams({ limit: 201 })).toThrow(/limit/u);
+	});
+});
+
+describe("createSessionSearchService", () => {
+	it("dispatches methods and returns JSON-safe results", async () => {
+		const calls = { search: [] as SessionIndexQuery[], list: [] as SessionListQuery[] };
+		const service = createSessionSearchService(fakeIndex(calls));
+
+		const batches = await all(service.call("search.query", { q: "abc", entryTypes: ["message"], limit: 5 }));
+		expect(batches).toEqual([{ hits: [], coverage: { indexed: 1, total: 2 } }]);
+		expect(calls.search).toEqual([{ text: "abc", limit: 5, entryTypes: ["message"] }]);
+
+		const [page] = await all(service.call("sessions.list", { cwd: "/work", cursor: "c1" }));
+		expect(JSON.parse(JSON.stringify(page))).toEqual({
+			sessions: [
+				{
+					path: "/s/a.jsonl",
+					id: "a",
+					cwd: "/work",
+					created: 1000,
+					modified: 2000,
+					messageCount: 1,
+					firstMessage: "hi",
+				},
+			],
+			nextCursor: "next",
+		});
+		expect(calls.list).toEqual([{ limit: 50, cwd: "/work", cursor: "c1" }]);
+
+		expect(await all(service.call("index.status", undefined))).toEqual([
+			{ state: "ready", indexed: 1, total: 1, pending: 0, errors: 0 },
+		]);
+	});
+
+	it("rejects unknown methods and bad params before touching the index", async () => {
+		const calls = { search: [] as SessionIndexQuery[], list: [] as SessionListQuery[] };
+		const service = createSessionSearchService(fakeIndex(calls));
+		await expect(all(service.call("sessions.delete", {}))).rejects.toMatchObject({ code: "unknown_method" });
+		await expect(all(service.call("search.query", { q: "" }))).rejects.toMatchObject({ code: "invalid_params" });
+		expect(() => service.searchQuery({ limit: 1 })).toThrow(SessionSearchRequestError);
+		expect(calls.search).toHaveLength(0);
+	});
+});
diff --git a/packages/coding-agent/test/session-index/store.test.ts b/packages/coding-agent/test/session-index/store.test.ts
new file mode 100644
index 00000000..de7f08bb
--- /dev/null
+++ b/packages/coding-agent/test/session-index/store.test.ts
@@ -0,0 +1,395 @@
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	utimesSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { projectEntry } from "../../src/core/session-index/projector.ts";
+import {
+	ForeignDatabaseError,
+	openIndexDatabase,
+	SCHEMA_MINOR,
+	SESSION_INDEX_APPLICATION_ID,
+	writeMeta,
+} from "../../src/core/session-index/schema.ts";
+import { SessionIndexStore } from "../../src/core/session-index/store.ts";
+import { type SessionIndexHit, SNIPPET_MATCH_END, SNIPPET_MATCH_START } from "../../src/core/session-index/types.ts";
+import { SessionManager } from "../../src/core/session-manager.ts";
+
+const NOW = Date.parse("2026-10-01T00:00:00Z");
+
+function entryHits(hits: SessionIndexHit[]): SessionIndexHit[] {
+	return hits.filter((hit) => hit.entryId !== null);
+}
+
+function header(id: string, cwd = "/work/app", version: number | null = 3): string {
+	return `${JSON.stringify({ type: "session", ...(version === null ? {} : { version }), id, timestamp: "2026-09-30T00:00:00.000Z", cwd })}\n`;
+}
+
+let counter = 0;
+function message(role: "user" | "assistant", text: string, ts = NOW): string {
+	counter++;
+	return `${JSON.stringify({
+		type: "message",
+		id: `e${counter}`,
+		parentId: null,
+		timestamp: new Date(ts).toISOString(),
+		message: { role, content: [{ type: "text", text }], timestamp: ts },
+	})}\n`;
+}
+
+describe("SessionIndexStore", () => {
+	let dir: string;
+	let root: string;
+	let store: SessionIndexStore;
+	let dbPath: string;
+
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), "session-index-"));
+		root = join(dir, "sessions");
+		mkdirSync(join(root, "--work-app--"), { recursive: true });
+		dbPath = join(dir, "index.sqlite");
+		store = new SessionIndexStore(openIndexDatabase(DatabaseSync, dbPath).db);
+		store.addRoot(root, "default");
+	});
+
+	afterEach(() => {
+		store.close();
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	const file = (name: string) => join(root, "--work-app--", `${name}.jsonl`);
+
+	it("indexes a session and finds entries and titles with FTS", () => {
+		const path = file("a");
+		writeFileSync(
+			path,
+			header("s1") + message("user", "Fix the database migration") + message("assistant", "数据库迁移已修复"),
+		);
+		expect(store.syncFile(path)).toBe("indexed");
+
+		const hits = store.search({ text: "migration", limit: 10 });
+		expect(hits.map((hit) => hit.entryId)).toContain(null);
+		const entryHit = hits.find((hit) => hit.entryId !== null);
+		expect(entryHit).toMatchObject({ sessionId: "s1", entryType: "message", role: "user", cwd: "/work/app" });
+		expect(entryHit?.snippet).toContain(`${SNIPPET_MATCH_START}migration${SNIPPET_MATCH_END}`);
+
+		expect(store.search({ text: "数据库", limit: 10 })).toHaveLength(1);
+		expect(store.syncFile(path)).toBe("skipped");
+	});
+
+	it("appends new lines without rebuilding and keeps list fields current", () => {
+		const path = file("a");
+		writeFileSync(path, header("s1") + message("user", "first question"));
+		store.syncFile(path);
+		appendFileSync(path, message("assistant", "an appended answer", NOW + 1000));
+		appendFileSync(
+			path,
+			`${JSON.stringify({ type: "session_info", id: "n1", parentId: null, timestamp: "", name: "Renamed" })}\n`,
+		);
+		expect(store.syncFile(path)).toBe("appended");
+
+		expect(entryHits(store.search({ text: "appended", limit: 5 }))).toHaveLength(1);
+		expect(store.search({ text: "Renamed", limit: 5 })[0]?.entryId).toBeNull();
+		const [item] = store.listSessions({ limit: 10 }).sessions;
+		expect(item).toMatchObject({ name: "Renamed", messageCount: 2, firstMessage: "first question" });
+		expect(item?.modified.getTime()).toBe(NOW + 1000);
+	});
+
+	it("rebuilds when the file is rewritten and keeps rows while it is empty", () => {
+		const path = file("a");
+		writeFileSync(path, header("s1") + message("user", "original wording"));
+		store.syncFile(path);
+
+		writeFileSync(path, "");
+		expect(store.syncFile(path)).toBe("pending");
+		expect(entryHits(store.search({ text: "original", limit: 5 }))).toHaveLength(1);
+
+		writeFileSync(
+			path,
+			header("s1", "/work/app", 3).replace("2026-09-30", "2026-09-29") + message("user", "rewritten wording"),
+		);
+		expect(store.syncFile(path)).toBe("indexed");
+		expect(entryHits(store.search({ text: "original", limit: 5 }))).toHaveLength(0);
+		expect(entryHits(store.search({ text: "rewritten", limit: 5 }))).toHaveLength(1);
+	});
+
+	it("leaves an unfinished final line for the next sync", () => {
+		const path = file("a");
+		const line = message("user", "half written line");
+		writeFileSync(path, header("s1") + line.slice(0, 20));
+		store.syncFile(path);
+		expect(entryHits(store.search({ text: "half written", limit: 5 }))).toHaveLength(0);
+
+		appendFileSync(path, line.slice(20));
+		expect(store.syncFile(path)).toBe("appended");
+		expect(entryHits(store.search({ text: "half written", limit: 5 }))).toHaveLength(1);
+	});
+
+	it("indexes v1 files with line-number ids without modifying them", () => {
+		const path = file("legacy");
+		const legacyMessage = (text: string) =>
+			`${JSON.stringify({ type: "message", timestamp: "2026-09-30T01:00:00.000Z", message: { role: "user", content: text } })}\n`;
+		const content = header("old", "/work/app", null) + legacyMessage("legacy alpha") + legacyMessage("legacy beta");
+		writeFileSync(path, content);
+		store.syncFile(path);
+		const ids = store.search({ text: "legacy", limit: 10 }).flatMap((hit) => (hit.entryId ? [hit.entryId] : []));
+		expect(ids.sort()).toEqual(["L2", "L3"]);
+		expect(readFileSync(path, "utf8")).toBe(content);
+	});
+
+	it("marks files whose first entry is not a header as errors", () => {
+		const path = file("bad");
+		writeFileSync(path, message("user", "no header here"));
+		expect(store.syncFile(path)).toBe("error");
+		expect(store.counts()).toMatchObject({ errors: 1, indexed: 0 });
+	});
+
+	it("uses bounded LIKE for queries shorter than a trigram", () => {
+		const recent = file("recent");
+		const old = file("old");
+		writeFileSync(recent, header("r") + message("user", "fix ui bug", NOW));
+		writeFileSync(old, header("o") + message("user", "old ui work", NOW - 60 * 24 * 3600 * 1000));
+		store.syncFile(recent);
+		store.syncFile(old);
+
+		const hits = store.search({ text: "ui", limit: 500 }, NOW);
+		expect(new Set(hits.map((hit) => hit.sessionId))).toEqual(new Set(["r"]));
+		expect(hits.find((hit) => hit.entryId)?.snippet).toContain(`${SNIPPET_MATCH_START}ui${SNIPPET_MATCH_END}`);
+
+		const scoped = store.search({ text: "ui", cwd: "/work/app", limit: 10 }, NOW);
+		expect(new Set(scoped.map((hit) => hit.sessionId))).toEqual(new Set(["r", "o"]));
+		expect(store.search({ text: "1%", limit: 10 }, NOW)).toHaveLength(0);
+	});
+
+	it("matches SessionManager.listAll for list fields", async () => {
+		const sessionDir = join(root, "--work-app--");
+		const manager = SessionManager.create("/work/app", sessionDir);
+		manager.appendMessage({ role: "user", content: "hello index", timestamp: NOW });
+		manager.appendMessage({
+			role: "assistant",
+			content: [{ type: "text", text: "hi" }],
+			api: "faux",
+			provider: "faux",
+			model: "faux",
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: NOW + 5,
+		} as never);
+		manager.appendSessionInfo("Named session");
+		const plan = store.planReconcile();
+		for (const path of plan.toSync) store.syncFile(path);
+
+		const [expected] = await SessionManager.listAll(sessionDir);
+		const [actual] = store.listSessions({ limit: 10, cwd: "/work/app" }).sessions;
+		const { allMessagesText: _ignored, ...expectedFields } = expected!;
+		expect(actual).toEqual(expectedFields);
+	});
+
+	it("pages the session list with a cursor", () => {
+		for (let i = 0; i < 5; i++) {
+			const path = file(`p${i}`);
+			writeFileSync(path, header(`p${i}`) + message("user", `page ${i}`, NOW + i));
+			store.syncFile(path);
+		}
+		const first = store.listSessions({ limit: 2 });
+		const second = store.listSessions({ limit: 2, cursor: first.nextCursor });
+		const third = store.listSessions({ limit: 2, cursor: second.nextCursor });
+		expect([...first.sessions, ...second.sessions, ...third.sessions].map((s) => s.id)).toEqual([
+			"p4",
+			"p3",
+			"p2",
+			"p1",
+			"p0",
+		]);
+		expect(third.nextCursor).toBeUndefined();
+	});
+
+	it("drops rows for deleted files only after listing their root", () => {
+		const path = file("gone");
+		writeFileSync(path, header("g") + message("user", "soon deleted"));
+		store.syncFile(store.planReconcile().toSync[0]!);
+		rmSync(path);
+		expect(store.planReconcile().removed).toBe(1);
+		expect(store.counts().total).toBe(0);
+	});
+
+	it("re-syncs a file whose mtime changed", () => {
+		const path = file("a");
+		writeFileSync(path, header("s1") + message("user", "stable text"));
+		store.syncFile(path);
+		utimesSync(path, new Date(NOW + 10_000), new Date(NOW + 10_000));
+		expect(store.planReconcile().toSync).toEqual([path]);
+		expect(store.syncFile(path)).toBe("appended");
+		expect(entryHits(store.search({ text: "stable", limit: 5 }))).toHaveLength(1);
+	});
+
+	describe("refreshRecent", () => {
+		const sync = (path: string) => {
+			store.syncFile(path);
+		};
+		const touch = (path: string, ms: number) => utimesSync(path, new Date(ms), new Date(ms));
+
+		it("picks up appends to recent files and files created after the last reconcile", () => {
+			const known = file("known");
+			writeFileSync(known, header("s1") + message("user", "first words"));
+			for (const path of store.planReconcile().toSync) store.syncFile(path);
+
+			appendFileSync(known, message("assistant", "appended paragraph"));
+			const sibling = file("sibling");
+			writeFileSync(sibling, header("s2") + message("user", "sibling session"));
+			touch(join(root, "--work-app--"), NOW + 1_000);
+			const otherDir = join(root, "--work-other--");
+			mkdirSync(otherDir);
+			writeFileSync(join(otherDir, "c.jsonl"), header("s3", "/work/other") + message("user", "another project"));
+			touch(root, NOW + 2_000);
+
+			expect(store.refreshRecent(Date.now() + 10_000, sync)).toBe(true);
+			expect(entryHits(store.search({ text: "appended", limit: 5 }))).toHaveLength(1);
+			expect(entryHits(store.search({ text: "sibling", limit: 5 }))).toHaveLength(1);
+			expect(entryHits(store.search({ text: "another", limit: 5 }))).toHaveLength(1);
+		});
+
+		it("watches a root that did not exist at the last reconcile", () => {
+			rmSync(root, { recursive: true, force: true });
+			expect(store.planReconcile().total).toBe(0);
+			mkdirSync(join(root, "--work-app--"), { recursive: true });
+			writeFileSync(file("new"), header("s1") + message("user", "lazily created root"));
+
+			expect(store.refreshRecent(Date.now() + 10_000, sync)).toBe(true);
+			expect(entryHits(store.search({ text: "lazily", limit: 5 }))).toHaveLength(1);
+		});
+
+		it("stops at the deadline and leaves the rest for a later pass", () => {
+			const path = file("a");
+			writeFileSync(path, header("s1") + message("user", "first words"));
+			for (const candidate of store.planReconcile().toSync) store.syncFile(candidate);
+			const late = file("late");
+			writeFileSync(late, header("s2") + message("user", "late arrival"));
+			touch(join(root, "--work-app--"), NOW + 1_000);
+
+			expect(store.refreshRecent(Date.now() - 1, sync)).toBe(false);
+			expect(store.search({ text: "arrival", limit: 5 })).toHaveLength(0);
+			expect(store.refreshRecent(Date.now() + 10_000, sync)).toBe(true);
+			expect(entryHits(store.search({ text: "arrival", limit: 5 }))).toHaveLength(1);
+		});
+	});
+});
+
+describe("openIndexDatabase", () => {
+	let dir: string;
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), "session-index-db-"));
+	});
+	afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+	it("refuses to touch a database it does not own", () => {
+		const path = join(dir, "foreign.sqlite");
+		const foreign = new DatabaseSync(path);
+		foreign.exec("CREATE TABLE notes(x)");
+		foreign.close();
+		const before = readFileSync(path);
+		expect(() => openIndexDatabase(DatabaseSync, path)).toThrow(ForeignDatabaseError);
+		expect(readFileSync(path).equals(before)).toBe(true);
+	});
+
+	it("quarantines a corrupt file and starts empty", () => {
+		const path = join(dir, "index.sqlite");
+		writeFileSync(path, "this is not sqlite at all".repeat(100));
+		const { db, recreated } = openIndexDatabase(DatabaseSync, path);
+		db.close();
+		expect(recreated).toBe("corrupt");
+		expect(existsSync(path)).toBe(true);
+	});
+
+	it("rebuilds FTS from entries when the FTS definition changes", () => {
+		const path = join(dir, "index.sqlite");
+		const root = join(dir, "sessions");
+		mkdirSync(root);
+		const session = join(root, "a.jsonl");
+		writeFileSync(session, header("s1") + message("user", "kept through rebuild"));
+		let store = new SessionIndexStore(openIndexDatabase(DatabaseSync, path).db);
+		store.addRoot(root, "custom");
+		store.syncFile(session);
+		store.close();
+
+		const raw = new DatabaseSync(path);
+		writeMeta(raw, "fts_definition", "older-tokenizer");
+		raw.close();
+
+		store = new SessionIndexStore(openIndexDatabase(DatabaseSync, path).db);
+		expect(entryHits(store.search({ text: "rebuild", limit: 5 }))).toHaveLength(1);
+		store.close();
+	});
+
+	it("stamps the documented identity and version", () => {
+		const path = join(dir, "index.sqlite");
+		openIndexDatabase(DatabaseSync, path).db.close();
+		const raw = new DatabaseSync(path, { readOnly: true });
+		expect(raw.prepare("PRAGMA application_id").get()?.application_id).toBe(SESSION_INDEX_APPLICATION_ID);
+		expect(raw.prepare("PRAGMA user_version").get()?.user_version).toBe(SCHEMA_MINOR);
+		expect(raw.prepare("SELECT value FROM index_meta WHERE key = 'schema_major'").get()?.value).toBe("1");
+		raw.close();
+	});
+
+	it("uses a file from a newer minor without migrating it", () => {
+		const path = join(dir, "index.sqlite");
+		openIndexDatabase(DatabaseSync, path).db.close();
+		const raw = new DatabaseSync(path);
+		raw.exec(`PRAGMA user_version = ${SCHEMA_MINOR + 1}`);
+		writeMeta(raw, "fts_definition", "newer-tokenizer");
+		raw.close();
+
+		const { db, recreated } = openIndexDatabase(DatabaseSync, path);
+		expect(recreated).toBeUndefined();
+		expect(db.prepare("PRAGMA user_version").get()?.user_version).toBe(SCHEMA_MINOR + 1);
+		expect(db.prepare("SELECT value FROM index_meta WHERE key = 'fts_definition'").get()?.value).toBe(
+			"newer-tokenizer",
+		);
+		db.close();
+	});
+
+	it("quarantines a file whose schema_major disagrees with its name", () => {
+		const path = join(dir, "index.sqlite");
+		openIndexDatabase(DatabaseSync, path).db.close();
+		const raw = new DatabaseSync(path);
+		writeMeta(raw, "schema_major", "2");
+		raw.close();
+		const { db, recreated } = openIndexDatabase(DatabaseSync, path);
+		db.close();
+		expect(recreated).toBe("corrupt");
+	});
+});
+
+describe("projectEntry", () => {
+	it("indexes displayed custom messages and labels", () => {
+		const base = { id: "x", parentId: null, timestamp: "2026-10-01T00:00:00.000Z" };
+		expect(
+			projectEntry({ ...base, type: "custom_message", customType: "note", content: "shown note", display: true }, 0)
+				?.text,
+		).toBe("shown note");
+		expect(
+			projectEntry({ ...base, type: "custom_message", customType: "note", content: "hidden", display: false }, 0),
+		).toBeNull();
+		expect(projectEntry({ ...base, type: "label", targetId: "y", label: "方案定稿" }, 0)).toMatchObject({
+			type: "label",
+			text: "方案定稿",
+		});
+		expect(projectEntry({ ...base, type: "label", targetId: "y", label: undefined }, 0)).toBeNull();
+	});
+});
diff --git a/scripts/build-binaries.sh b/scripts/build-binaries.sh
index 4ba6fc5e..394b54a2 100755
--- a/scripts/build-binaries.sh
+++ b/scripts/build-binaries.sh
@@ -259,9 +259,9 @@ for platform in "${PLATFORMS[@]}"; do
     # Disable cwd bunfig.toml autoload so project preload scripts cannot crash the
     # standalone binary before step starts (see #7684).
     if [[ "$platform" == windows-* ]]; then
-        bun build --compile --no-compile-autoload-bunfig '--env=STEPCODE_BUILD_*' --target="$bun_target" ../../apps/cli/dist/bun/stepcode.js ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts --outfile "$OUTPUT_DIR/$platform/step.exe"
+        bun build --compile --no-compile-autoload-bunfig '--env=STEPCODE_BUILD_*' --target="$bun_target" ../../apps/cli/dist/bun/stepcode.js ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts ./src/core/session-index/session-index-worker.ts --outfile "$OUTPUT_DIR/$platform/step.exe"
     else
-        bun build --compile --no-compile-autoload-bunfig '--env=STEPCODE_BUILD_*' --target="$bun_target" ../../apps/cli/dist/bun/stepcode.js ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts --outfile "$OUTPUT_DIR/$platform/step"
+        bun build --compile --no-compile-autoload-bunfig '--env=STEPCODE_BUILD_*' --target="$bun_target" ../../apps/cli/dist/bun/stepcode.js ./src/utils/image-resize-worker.ts ./src/step/usage/activity-worker.ts ./src/core/session-index/session-index-worker.ts --outfile "$OUTPUT_DIR/$platform/step"
     fi
 done
 
diff --git a/scripts/build-coding-agent-bundle.mjs b/scripts/build-coding-agent-bundle.mjs
index 2a3c71d0..af1d775a 100644
--- a/scripts/build-coding-agent-bundle.mjs
+++ b/scripts/build-coding-agent-bundle.mjs
@@ -205,6 +205,7 @@ const mainResult = await build({
 
 const imageResizeOutput = findContainingOutput(mainResult.metafile, "packages/coding-agent/dist/utils/image-resize.js");
 const activityOutput = findContainingOutput(mainResult.metafile, "packages/coding-agent/dist/step/usage/activity.js");
+const sessionIndexOutput = findContainingOutput(mainResult.metafile, "packages/coding-agent/dist/core/session-index/client.js");
 
 // The image-resize worker is reached through a worker URL, so the main bundle
 // cannot follow it. Emit a self-contained worker file beside the code that
@@ -222,8 +223,19 @@ const lazyResult = await build({
 validateExternalImports([mainResult.metafile, lazyResult.metafile]);
 const activityResult = await build({ ...commonBuildOptions(), entryNames: "[name]", entryPoints: { "activity-worker": join(codingAgentDistDir, "step", "usage", "activity-worker.js") }, outdir: dirname(activityOutput), splitting: false });
 validateExternalImports([activityResult.metafile]);
+// The session index worker owns its SQLite connection; emit it beside the client that resolves its URL.
+const sessionIndexResult = await build({
+	...commonBuildOptions(),
+	entryNames: "[name]",
+	entryPoints: {
+		"session-index-worker": join(codingAgentDistDir, "core", "session-index", "session-index-worker.js"),
+	},
+	outdir: dirname(sessionIndexOutput),
+	splitting: false,
+});
+validateExternalImports([sessionIndexResult.metafile]);
 chmodSync(join(bundleDir, "step.js"), 0o755);
 
-const files = new Set([...Object.keys(mainResult.metafile.outputs), ...Object.keys(lazyResult.metafile.outputs), ...Object.keys(activityResult.metafile.outputs)]).size;
-const mib = outputBytes([mainResult.metafile, lazyResult.metafile, activityResult.metafile]) / (1024 * 1024);
+const files = new Set([...Object.keys(mainResult.metafile.outputs), ...Object.keys(lazyResult.metafile.outputs), ...Object.keys(activityResult.metafile.outputs), ...Object.keys(sessionIndexResult.metafile.outputs)]).size;
+const mib = outputBytes([mainResult.metafile, lazyResult.metafile, activityResult.metafile, sessionIndexResult.metafile]) / (1024 * 1024);
 console.log(`Built ${relative(repoRoot, bundleDir)} (${files} files, ${mib.toFixed(1)} MiB)`);

From 4c882766f06bc3983a613dd3f7a89139aad593a5 Mon Sep 17 00:00:00 2001
From: liuedcson <332840681+liuedcson@users.noreply.github.com>
Date: Sat, 17 Oct 2026 16:11:28 +0800
Subject: [PATCH 2/2] feat(coding-agent): mark child-agent sessions and keep
 them out of search

Child agents (subagent lanes, workflow agents) now stamp origin: "subagent"
and parentSessionId in their session header. isChildAgentSession recognizes
the header marker or the subagent-/workflow- id prefix of older sessions.

The session index (schema minor 2) stores sessions.origin, backfills it from
the id prefix, and excludes child sessions from every search and list path,
including the degraded JSONL scan. The CLI resume picker uses the same rule.
---
 .../src/ui/view/dialogs/session-selector.ts   |  4 +-
 packages/coding-agent/docs/session-format.md  |  8 +++-
 packages/coding-agent/docs/session-index.md   |  2 +
 .../coding-agent/src/core/child-session.ts    | 30 +++++++++++++++
 .../src/core/session-index/fallback.ts        |  4 +-
 .../src/core/session-index/schema.ts          | 17 ++++++++-
 .../src/core/session-index/store.ts           | 23 ++++++++----
 .../coding-agent/src/core/session-manager.ts  | 13 +++++++
 .../src/features/step-subagent.ts             | 15 ++++++++
 .../src/features/subagent/helpers.ts          | 22 +++--------
 packages/coding-agent/src/index.ts            | 12 +++---
 packages/coding-agent/src/main.ts             |  6 ++-
 .../test/session-index/client.test.ts         |  2 +
 .../test/session-index/store.test.ts          | 37 +++++++++++++++++++
 .../test/subagent-child-env.test.ts           | 20 +++++++++-
 15 files changed, 179 insertions(+), 36 deletions(-)
 create mode 100644 packages/coding-agent/src/core/child-session.ts

diff --git a/apps/cli/src/ui/view/dialogs/session-selector.ts b/apps/cli/src/ui/view/dialogs/session-selector.ts
index 33874ba2..a16c301a 100644
--- a/apps/cli/src/ui/view/dialogs/session-selector.ts
+++ b/apps/cli/src/ui/view/dialogs/session-selector.ts
@@ -6,7 +6,7 @@ import type { SessionInfo, SessionListProgress } from "@step-harness/coding-agen
 import {
 	canonicalizePath as _canonicalizePath,
 	DynamicBorder,
-	isChildAgentSessionId,
+	isChildAgentSession,
 	KeybindingsManager,
 	keyHint,
 	keyText,
@@ -954,7 +954,7 @@ export class SessionSelectorComponent extends Container implements Focusable {
 			// a respawned child still reattaches to its own transcript.
 			const sessions = (
 				await (scope === "current" ? this.currentSessionsLoader(onProgress) : this.allSessionsLoader(onProgress))
-			).filter((session) => !isChildAgentSessionId(session.id));
+			).filter((session) => !isChildAgentSession(session));
 
 			if (scope === "current") {
 				this.currentSessions = sessions;
diff --git a/packages/coding-agent/docs/session-format.md b/packages/coding-agent/docs/session-format.md
index 2622b877..818894bb 100644
--- a/packages/coding-agent/docs/session-format.md
+++ b/packages/coding-agent/docs/session-format.md
@@ -202,6 +202,12 @@ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ pare
 {"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
 ```
 
+A session created by a child agent (a subagent lane or workflow agent, spawned with `STEPCODE_SUBAGENT_CHILD=1`) carries `origin: "subagent"` and, when known, the id of the session that spawned it. Session lists, the resume picker, and session search skip these sessions (`isChildAgentSession`, which also recognizes the `subagent-` / `workflow-` id prefixes of older child sessions):
+
+```json
+{"type":"session","version":3,"id":"subagent-uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","origin":"subagent","parentSessionId":"uuid"}
+```
+
 ### SessionMessageEntry
 
 A message in the conversation. The `message` field contains an `AgentMessage`.
@@ -401,7 +407,7 @@ Key methods for working with sessions programmatically.
 - `SessionManager.listAll(onProgress?)` - List all sessions across all projects
 
 ### Instance Methods - Session Management
-- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `newSession(options?)` - Start a new session (options: `{ id?, parentSession?, origin?, parentSessionId? }`)
 - `setSessionFile(path)` - Switch to a different session file
 - `createBranchedSession(leafId)` - Extract branch to new session file
 
diff --git a/packages/coding-agent/docs/session-index.md b/packages/coding-agent/docs/session-index.md
index d08c72ca..cdfc6cad 100644
--- a/packages/coding-agent/docs/session-index.md
+++ b/packages/coding-agent/docs/session-index.md
@@ -29,6 +29,8 @@ The session index is a derived SQLite database for session lists and full-text s
 
 v1 files without entry ids are indexed with ids `L<physical line>`. Files are migrated to v3 in memory only.
 
+Child-agent sessions (subagent lanes, workflow agents) are indexed with `sessions.origin = 'subagent'` but are excluded from every search and list, including the short-query window and degraded mode. A session is a child when its header has `origin: "subagent"` or its id starts with `subagent-` / `workflow-` (`isChildAgentSession`); sessions written before the header marker carry only the prefix. Schema minor 2 added the column and marked existing rows by prefix.
+
 ## Updates
 
 | Trigger | Behavior |
diff --git a/packages/coding-agent/src/core/child-session.ts b/packages/coding-agent/src/core/child-session.ts
new file mode 100644
index 00000000..b8a3f05a
--- /dev/null
+++ b/packages/coding-agent/src/core/child-session.ts
@@ -0,0 +1,30 @@
+/**
+ * Sessions written by child agents (subagent lanes and workflow agents) rather
+ * than by a user. A child runs in the parent's cwd, so its transcript lands in
+ * the same per-cwd session directory as the parent's; session lists and search
+ * use this to keep to sessions a user started.
+ *
+ * Two markers identify a child, and either is enough:
+ * - `origin: "subagent"` in the session header, written by the child process
+ *   when it creates the session (see `childSessionHeader`).
+ * - The session id prefix. Every child is spawned through
+ *   `runStepSubagentProcess` with an id the parent generates
+ *   (`subagent-<uuid>`, `workflow-<runId>-<agentId>`). Sessions written before
+ *   the header marker existed carry only this.
+ */
+
+export const SUBAGENT_SESSION_ID_PREFIX = "subagent-";
+export const WORKFLOW_SESSION_ID_PREFIX = "workflow-";
+
+/** Header `origin` of a session a child agent created. */
+export const CHILD_SESSION_ORIGIN = "subagent";
+
+/** True for an id the parent generated for a spawned child agent. */
+export function isChildAgentSessionId(sessionId: string): boolean {
+	return sessionId.startsWith(SUBAGENT_SESSION_ID_PREFIX) || sessionId.startsWith(WORKFLOW_SESSION_ID_PREFIX);
+}
+
+/** True for a session written by a spawned child agent, not by a user. */
+export function isChildAgentSession(session: { readonly id: string; readonly origin?: unknown }): boolean {
+	return session.origin === CHILD_SESSION_ORIGIN || isChildAgentSessionId(session.id);
+}
diff --git a/packages/coding-agent/src/core/session-index/fallback.ts b/packages/coding-agent/src/core/session-index/fallback.ts
index 170cdf03..cfd2790f 100644
--- a/packages/coding-agent/src/core/session-index/fallback.ts
+++ b/packages/coding-agent/src/core/session-index/fallback.ts
@@ -1,5 +1,6 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
+import { isChildAgentSession } from "../child-session.ts";
 import { type SessionInfo, SessionManager } from "../session-manager.ts";
 import { textSnippet } from "./store.ts";
 import type {
@@ -44,8 +45,9 @@ export class JsonlScanSessionIndex implements SessionIndex {
 			sessions.push(...(await SessionManager.listAll(directory)));
 		}
 		const seen = new Set<string>();
+		// Child-agent sessions are skipped, as in the index's queries.
 		return sessions
-			.filter((session) => !seen.has(session.path) && seen.add(session.path))
+			.filter((session) => !isChildAgentSession(session) && !seen.has(session.path) && seen.add(session.path))
 			.sort((a, b) => b.modified.getTime() - a.modified.getTime());
 	}
 
diff --git a/packages/coding-agent/src/core/session-index/schema.ts b/packages/coding-agent/src/core/session-index/schema.ts
index 6adcc486..dad779d1 100644
--- a/packages/coding-agent/src/core/session-index/schema.ts
+++ b/packages/coding-agent/src/core/session-index/schema.ts
@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import type { DatabaseSync } from "node:sqlite";
+import { CHILD_SESSION_ORIGIN, SUBAGENT_SESSION_ID_PREFIX, WORKFLOW_SESSION_ID_PREFIX } from "../child-session.ts";
 import { PROJECTOR_VERSION } from "./projector.ts";
 
 /**
@@ -20,7 +21,7 @@ export const SCHEMA_MAJOR = 1;
  * Additive migration number within a major, stored in `user_version`. Older
  * files are migrated in place; newer files are used through known columns only.
  */
-export const SCHEMA_MINOR = 1;
+export const SCHEMA_MINOR = 2;
 /** Changing the tokenizer or FTS columns rebuilds only the FTS tables from `entries`. */
 export const FTS_DEFINITION = "trigram:v1";
 export const SESSION_INDEX_FILE_NAME = `session-search.v${SCHEMA_MAJOR}.db`;
@@ -84,6 +85,7 @@ CREATE TABLE sessions (
 	session_id TEXT NOT NULL,
 	cwd TEXT NOT NULL,
 	parent_session TEXT,
+	origin TEXT,
 	name TEXT,
 	first_message TEXT,
 	created_at INTEGER NOT NULL,
@@ -263,6 +265,19 @@ function upgradeSchema(db: DatabaseSync, userVersion: number): void {
 	db.exec("BEGIN IMMEDIATE");
 	try {
 		// Minor migrations go here in order, each guarded by `userVersion < N`.
+		if (userVersion < 2) {
+			// Rows written before the column existed predate the header marker, so the id prefix is all they carry.
+			db.exec("ALTER TABLE sessions ADD COLUMN origin TEXT");
+			db.prepare(
+				"UPDATE sessions SET origin = ? WHERE substr(session_id, 1, ?) = ? OR substr(session_id, 1, ?) = ?",
+			).run(
+				CHILD_SESSION_ORIGIN,
+				SUBAGENT_SESSION_ID_PREFIX.length,
+				SUBAGENT_SESSION_ID_PREFIX,
+				WORKFLOW_SESSION_ID_PREFIX.length,
+				WORKFLOW_SESSION_ID_PREFIX,
+			);
+		}
 		if (ftsDefinition !== FTS_DEFINITION) {
 			// Rebuild from `entries` without rereading JSONL.
 			db.exec(DROP_FTS);
diff --git a/packages/coding-agent/src/core/session-index/store.ts b/packages/coding-agent/src/core/session-index/store.ts
index 42f533e8..49cb1731 100644
--- a/packages/coding-agent/src/core/session-index/store.ts
+++ b/packages/coding-agent/src/core/session-index/store.ts
@@ -1,5 +1,6 @@
 import { dirname } from "node:path";
 import type { DatabaseSync, SQLInputValue } from "node:sqlite";
+import { CHILD_SESSION_ORIGIN, isChildAgentSession } from "../child-session.ts";
 import type { SessionHeader } from "../session-manager.ts";
 import {
 	createSessionSummary,
@@ -52,6 +53,13 @@ export const SHORT_QUERY_MAX_SESSIONS = 200;
 export const SHORT_QUERY_MAX_HITS = 50;
 const SNIPPET_CONTEXT_CHARS = 48;
 const FTS_SNIPPET_TOKENS = 32;
+/**
+ * Child-agent sessions (`origin` set) stay indexed but are never searched or
+ * listed: they belong to a tool call, not to the user, and one fan-out can add
+ * a dozen of them, enough to crowd real sessions out of a page or the
+ * short-query window.
+ */
+const USER_SESSION = "s.origin IS NULL";
 /** Known files re-checked before each search or list. */
 export const REFRESH_RECENT_FILES = 20;
 
@@ -435,9 +443,9 @@ export class SessionIndexStore {
 			});
 			const sessionRow = this.db
 				.prepare(
-					`INSERT INTO sessions(path, session_id, cwd, name, parent_session, created_at, modified_at,
+					`INSERT INTO sessions(path, session_id, cwd, name, parent_session, origin, created_at, modified_at,
 						last_activity_at, message_count, first_message)
-					VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING sid`,
+					VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING sid`,
 				)
 				.get(
 					path,
@@ -445,6 +453,7 @@ export class SessionIndexStore {
 					typeof header.cwd === "string" ? header.cwd : "",
 					parsed.summary.name ?? null,
 					typeof header.parentSession === "string" ? header.parentSession : null,
+					isChildAgentSession(header) ? CHILD_SESSION_ORIGIN : null,
 					Number.isNaN(createdAt) ? Math.trunc(fp.mtimeMs) : createdAt,
 					resolveSessionModifiedTime(header, parsed.summary.lastActivityTime, Math.trunc(fp.mtimeMs)),
 					parsed.summary.lastActivityTime ?? null,
@@ -692,7 +701,7 @@ export class SessionIndexStore {
 
 		if (!query.entryTypes) {
 			const params: SQLInputValue[] = [SNIPPET_MATCH_START, SNIPPET_MATCH_END, match];
-			let where = "sessions_fts MATCH ?";
+			let where = `sessions_fts MATCH ? AND ${USER_SESSION}`;
 			if (query.cwd !== undefined) {
 				where += " AND s.cwd = ?";
 				params.push(query.cwd);
@@ -725,7 +734,7 @@ export class SessionIndexStore {
 		}
 
 		const params: SQLInputValue[] = [SNIPPET_MATCH_START, SNIPPET_MATCH_END, match];
-		let where = "entries_fts MATCH ?";
+		let where = `entries_fts MATCH ? AND ${USER_SESSION}`;
 		if (query.cwd !== undefined) {
 			where += " AND s.cwd = ?";
 			params.push(query.cwd);
@@ -773,7 +782,7 @@ export class SessionIndexStore {
 		const limit = Math.min(requestedLimit, SHORT_QUERY_MAX_HITS);
 		const since = query.since ?? (query.cwd === undefined ? now - SHORT_QUERY_DEFAULT_WINDOW_MS : undefined);
 		const candidateParams: SQLInputValue[] = [];
-		const candidateWhere: string[] = [];
+		const candidateWhere: string[] = ["origin IS NULL"];
 		if (query.cwd !== undefined) {
 			candidateWhere.push("cwd = ?");
 			candidateParams.push(query.cwd);
@@ -850,7 +859,7 @@ export class SessionIndexStore {
 	listSessions(query: SessionListQuery): SessionListPage {
 		const limit = Math.max(1, Math.floor(query.limit));
 		const params: SQLInputValue[] = [];
-		const where: string[] = [];
+		const where: string[] = ["origin IS NULL"];
 		if (query.cwd !== undefined) {
 			where.push("cwd = ?");
 			params.push(query.cwd);
@@ -865,7 +874,7 @@ export class SessionIndexStore {
 		const rows = this.db
 			.prepare(
 				`SELECT sid, path, session_id, cwd, name, parent_session, created_at, modified_at, message_count, first_message
-				FROM sessions ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+				FROM sessions WHERE ${where.join(" AND ")}
 				ORDER BY modified_at DESC, sid DESC LIMIT ?`,
 			)
 			.all(...params);
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index 260fc0af..50a626f0 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -19,6 +19,7 @@ import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
 import { APP_NAME, getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.ts";
 import { normalizePath, resolvePath } from "../utils/paths.ts";
+import { CHILD_SESSION_ORIGIN } from "./child-session.ts";
 import {
 	type BashExecutionMessage,
 	type CustomMessage,
@@ -37,12 +38,19 @@ export interface SessionHeader {
 	id: string;
 	timestamp: string;
 	cwd: string;
+	/** Path of the session this one was forked or continued from. */
 	parentSession?: string;
+	/** Set by a child agent (subagent lane or workflow agent) on the session it creates. */
+	origin?: typeof CHILD_SESSION_ORIGIN;
+	/** Id of the session whose agent spawned this child, when known. */
+	parentSessionId?: string;
 }
 
 export interface NewSessionOptions {
 	id?: string;
 	parentSession?: string;
+	origin?: typeof CHILD_SESSION_ORIGIN;
+	parentSessionId?: string;
 }
 
 export interface SessionEntryBase {
@@ -182,6 +190,8 @@ export interface SessionInfo {
 	name?: string;
 	/** Path to the parent session (if this session was forked). */
 	parentSessionPath?: string;
+	/** Header `origin`; `isChildAgentSession` tells child-agent sessions apart. */
+	origin?: typeof CHILD_SESSION_ORIGIN;
 	created: Date;
 	modified: Date;
 	messageCount: number;
@@ -705,6 +715,7 @@ async function buildSessionInfo(filePath: string): Promise<SessionInfo | null> {
 			cwd,
 			name: summary.name,
 			parentSessionPath,
+			...(header.origin === CHILD_SESSION_ORIGIN ? { origin: header.origin } : {}),
 			created: new Date(header.timestamp),
 			modified: new Date(resolveSessionModifiedTime(header, summary.lastActivityTime, stats.mtime.getTime())),
 			messageCount: summary.messageCount,
@@ -893,6 +904,8 @@ export class SessionManager {
 			timestamp,
 			cwd: this.cwd,
 			parentSession: options?.parentSession,
+			...(options?.origin ? { origin: options.origin } : {}),
+			...(options?.parentSessionId ? { parentSessionId: options.parentSessionId } : {}),
 		};
 		this.fileEntries = [header];
 		this.byId.clear();
diff --git a/packages/coding-agent/src/features/step-subagent.ts b/packages/coding-agent/src/features/step-subagent.ts
index c32bfe86..cfc8c664 100644
--- a/packages/coding-agent/src/features/step-subagent.ts
+++ b/packages/coding-agent/src/features/step-subagent.ts
@@ -14,7 +14,9 @@ import { Text } from "@step-harness/pi-tui";
 import { type Message, type ProviderErrorKind, StringEnum, type Usage } from "@step-harness/providers";
 import { type Static, Type } from "typebox";
 import { CONFIG_DIR_NAME } from "../config.ts";
+import { CHILD_SESSION_ORIGIN } from "../core/child-session.ts";
 import type { ExtensionAPI, ExtensionContext, ExtensionFactory, InlineExtension } from "../core/extensions/types.ts";
+import type { NewSessionOptions } from "../core/session-manager.ts";
 import { resolveStepAgentDir, resolveStepConfigDir } from "../step/environment.ts";
 import type { StepTelemetryReporter } from "../step/telemetry.ts";
 import { formatBuiltinAgentGuidance, type StepAgentConfig, type StepAgentScope } from "./step-subagent-agents.ts";
@@ -75,6 +77,19 @@ export const MAX_JSON_LINE_BYTES = 2 * 1024 * 1024;
 const MAX_MESSAGES = 256;
 export const CHILD_MARKER = "STEPCODE_SUBAGENT_CHILD";
 
+/**
+ * Header fields a child agent process stamps on the session it creates, so the
+ * session is recognisable as a child's without relying on its id. Empty outside
+ * a child process. The env comes from `buildSubagentChildEnv`.
+ */
+export function childSessionHeader(
+	env: NodeJS.ProcessEnv = process.env,
+): Pick<NewSessionOptions, "origin" | "parentSessionId"> {
+	if (env[CHILD_MARKER] !== "1") return {};
+	const parentSessionId = env.STEPCODE_USAGE_PARENT_SESSION_ID?.trim();
+	return { origin: CHILD_SESSION_ORIGIN, ...(parentSessionId ? { parentSessionId } : {}) };
+}
+
 export interface StepSubagentUsage {
 	input: number;
 	output: number;
diff --git a/packages/coding-agent/src/features/subagent/helpers.ts b/packages/coding-agent/src/features/subagent/helpers.ts
index f585186d..e6f9a2a9 100644
--- a/packages/coding-agent/src/features/subagent/helpers.ts
+++ b/packages/coding-agent/src/features/subagent/helpers.ts
@@ -137,19 +137,9 @@ export function isRecordValue(value: unknown): value is Record<string, unknown>
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-/**
- * Session-id prefixes for the child processes Step spawns: `subagent` lanes and
- * `workflow` agents (both run through `runStepSubagentProcess`).
- *
- * A child runs in the parent's cwd, so its transcript lands in the same per-cwd
- * session directory as the parent's, and a single fan-out can add a dozen of
- * them. The prefix is the only marker separating the two, so the resume picker
- * filters on it to keep the list to sessions a user actually started.
- */
-export const SUBAGENT_SESSION_ID_PREFIX = "subagent-";
-export const WORKFLOW_SESSION_ID_PREFIX = "workflow-";
-
-/** True for a session written by a spawned child agent, not by a user. */
-export function isChildAgentSessionId(sessionId: string): boolean {
-	return sessionId.startsWith(SUBAGENT_SESSION_ID_PREFIX) || sessionId.startsWith(WORKFLOW_SESSION_ID_PREFIX);
-}
+export {
+	isChildAgentSession,
+	isChildAgentSessionId,
+	SUBAGENT_SESSION_ID_PREFIX,
+	WORKFLOW_SESSION_ID_PREFIX,
+} from "../../core/child-session.ts";
diff --git a/packages/coding-agent/src/index.ts b/packages/coding-agent/src/index.ts
index 859c77e0..3fe5c742 100644
--- a/packages/coding-agent/src/index.ts
+++ b/packages/coding-agent/src/index.ts
@@ -49,6 +49,13 @@ export {
 	computeCacheWaste,
 	detectCacheMiss,
 } from "./core/cache-stats.ts";
+export {
+	CHILD_SESSION_ORIGIN,
+	isChildAgentSession,
+	isChildAgentSessionId,
+	SUBAGENT_SESSION_ID_PREFIX,
+	WORKFLOW_SESSION_ID_PREFIX,
+} from "./core/child-session.ts";
 // Compaction
 export {
 	type BranchPreparation,
@@ -494,11 +501,6 @@ export {
 	stepScheduleExtensionInline,
 	UpdateGoalParams,
 } from "./features/step-schedule.ts";
-export {
-	isChildAgentSessionId,
-	SUBAGENT_SESSION_ID_PREFIX,
-	WORKFLOW_SESSION_ID_PREFIX,
-} from "./features/step-subagent.ts";
 // Optional Step Workflow capability. The extension remains feature-gated at
 // registration time, while the pure runtime contracts are useful to embedders
 // and tests.
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 20b6eda2..cdcb8319 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -86,6 +86,7 @@ import { SettingsManager, type SettingsManagerCreateOptions } from "./core/setti
 import type { SystemPromptProduct } from "./core/system-prompt.ts";
 import { hasTrustRequiringProjectResources, ProjectTrustStore } from "./core/trust-manager.ts";
 import { builtInExtensions } from "./features/index.ts";
+import { childSessionHeader } from "./features/step-subagent.ts";
 import { runMigrations, showDeprecationWarnings } from "./migrations.ts";
 import { runPrintMode, runRpcMode } from "./modes/index.ts";
 import type { InteractiveModeOptions, StartupTuiPathOptions, StartupUiHooks } from "./modes/interactive-contract.ts";
@@ -593,9 +594,10 @@ export async function createSessionManager(
 		);
 	}
 
+	const newSession = { id: parsed.sessionId, ...childSessionHeader() };
 	return agentDir
-		? createStepSessionManager(cwd, { agentDir, sessionDir, newSession: { id: parsed.sessionId } })
-		: SessionManager.create(cwd, sessionDir, { id: parsed.sessionId });
+		? createStepSessionManager(cwd, { agentDir, sessionDir, newSession })
+		: SessionManager.create(cwd, sessionDir, newSession);
 }
 
 function buildSessionOptions(
diff --git a/packages/coding-agent/test/session-index/client.test.ts b/packages/coding-agent/test/session-index/client.test.ts
index bc57eee9..74348273 100644
--- a/packages/coding-agent/test/session-index/client.test.ts
+++ b/packages/coding-agent/test/session-index/client.test.ts
@@ -98,6 +98,8 @@ describe("openSessionIndex", () => {
 		foreign.exec("CREATE TABLE other(x)");
 		foreign.close();
 		writeSession(join(sessionDir, "a.jsonl"), "a", "scan fallback text");
+		// The scan skips child-agent sessions as the index does.
+		writeSession(join(sessionDir, "child.jsonl"), "subagent-1", "scan fallback text");
 
 		index = await openSessionIndex({ agentDir });
 		const status = await index.status();
diff --git a/packages/coding-agent/test/session-index/store.test.ts b/packages/coding-agent/test/session-index/store.test.ts
index de7f08bb..656aa0cd 100644
--- a/packages/coding-agent/test/session-index/store.test.ts
+++ b/packages/coding-agent/test/session-index/store.test.ts
@@ -86,6 +86,43 @@ describe("SessionIndexStore", () => {
 		expect(store.syncFile(path)).toBe("skipped");
 	});
 
+	it("indexes child-agent sessions but never searches or lists them", () => {
+		const childHeader = (id: string, origin?: string) =>
+			`${JSON.stringify({ type: "session", version: 3, id, timestamp: "2026-09-30T00:00:00.000Z", cwd: "/work/app", ...(origin ? { origin } : {}) })}\n`;
+		writeFileSync(file("user"), header("s1") + message("user", "quokka in the user session"));
+		// Marked by the header, by the subagent id prefix, and by the workflow id prefix.
+		writeFileSync(file("marked"), childHeader("c1", "subagent") + message("user", "quokka you are a subagent"));
+		writeFileSync(file("lane"), childHeader("subagent-1") + message("user", "quokka lane task"));
+		writeFileSync(file("flow"), childHeader("workflow-r-a") + message("user", "quokka workflow task"));
+		for (const name of ["user", "marked", "lane", "flow"]) expect(store.syncFile(file(name))).toBe("indexed");
+
+		const sessionsOf = (hits: SessionIndexHit[]) => [...new Set(hits.map((hit) => hit.sessionId))];
+		expect(sessionsOf(store.search({ text: "quokka", limit: 20 }))).toEqual(["s1"]);
+		expect(sessionsOf(store.search({ text: "you are a subagent", limit: 20 }))).toEqual([]);
+		// Below the trigram minimum: the LIKE path and its recent-session window.
+		expect(sessionsOf(store.search({ text: "qu", cwd: "/work/app", limit: 20 }, NOW))).toEqual(["s1"]);
+		expect(store.listSessions({ limit: 10 }).sessions.map((session) => session.id)).toEqual(["s1"]);
+		expect(store.counts().indexed).toBe(4);
+	});
+
+	it("migrates a minor-1 file by marking child sessions from their id prefix", () => {
+		writeFileSync(file("user"), header("s1") + message("user", "quokka user"));
+		writeFileSync(file("lane"), header("subagent-1") + message("user", "quokka lane"));
+		store.syncFile(file("user"));
+		store.syncFile(file("lane"));
+		store.close();
+		const raw = new DatabaseSync(dbPath);
+		raw.exec("ALTER TABLE sessions DROP COLUMN origin");
+		raw.exec("PRAGMA user_version = 1");
+		raw.close();
+
+		store = new SessionIndexStore(openIndexDatabase(DatabaseSync, dbPath).db);
+		expect([...new Set(store.search({ text: "quokka", limit: 10 }).map((hit) => hit.sessionId))]).toEqual(["s1"]);
+		const check = new DatabaseSync(dbPath, { readOnly: true });
+		expect(check.prepare("PRAGMA user_version").get()?.user_version).toBe(SCHEMA_MINOR);
+		check.close();
+	});
+
 	it("appends new lines without rebuilding and keeps list fields current", () => {
 		const path = file("a");
 		writeFileSync(path, header("s1") + message("user", "first question"));
diff --git a/packages/coding-agent/test/subagent-child-env.test.ts b/packages/coding-agent/test/subagent-child-env.test.ts
index 9d3584e7..268f46ed 100644
--- a/packages/coding-agent/test/subagent-child-env.test.ts
+++ b/packages/coding-agent/test/subagent-child-env.test.ts
@@ -2,10 +2,12 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, expect, test, vi } from "vitest";
+import { isChildAgentSession } from "../src/core/child-session.ts";
 import type { ExtensionAPI, ToolDefinition } from "../src/core/extensions/types.ts";
+import { SessionManager } from "../src/core/session-manager.ts";
 import { createStepCronExtension } from "../src/features/step-cron.ts";
 import { createStepGoalExtension } from "../src/features/step-schedule.ts";
-import { CHILD_MARKER, type StepSubagentRunInput } from "../src/features/step-subagent.ts";
+import { CHILD_MARKER, childSessionHeader, type StepSubagentRunInput } from "../src/features/step-subagent.ts";
 import type { StepAgentConfig } from "../src/features/step-subagent-agents.ts";
 import { liveSubagentSessions } from "../src/features/subagent/lane-lifecycle.ts";
 import {
@@ -97,6 +99,22 @@ test("every rpc child is stripped of scheduling authority", () => {
 	expect(registeredTools(createStepGoalExtension())).toEqual([]);
 });
 
+test("a child stamps its session header from the child env; a user session stays unmarked", async () => {
+	const env = buildSubagentChildEnv(runInput({ parentSessionId: "parent-1" }));
+	expect(childSessionHeader(env)).toEqual({ origin: "subagent", parentSessionId: "parent-1" });
+	expect(childSessionHeader({})).toEqual({});
+
+	const dir = await workspace();
+	const child = SessionManager.create(dir, dir, { id: "any-id", ...childSessionHeader(env) });
+	expect(child.getHeader()).toMatchObject({ origin: "subagent", parentSessionId: "parent-1" });
+	// The header alone marks it, whatever the id.
+	expect(isChildAgentSession({ id: "any-id", origin: child.getHeader()?.origin })).toBe(true);
+	const user = SessionManager.create(dir, dir, { id: "user-id", ...childSessionHeader({}) });
+	expect(user.getHeader()).not.toHaveProperty("origin");
+	expect(isChildAgentSession({ id: "user-id" })).toBe(false);
+	expect(isChildAgentSession({ id: "workflow-run-agent" })).toBe(true);
+});
+
 test("a workflow ACL is forwarded, and a stale inherited one is cleared", () => {
 	vi.stubEnv(WORKFLOW_ACL_ENV, JSON.stringify({ baseCwd: "/inherited" }));