@1agents/session-reader 0.1.1 → 0.2.1

package/README.md

@@ -36,7 +36,7 @@ npm run build && node dist/bin/1session.js <command>
 
 | 命令 | 说明 |
 | --- | --- |
-| `1session list [--limit n] [--workspace path] [--provider name] [--since 24h] [--json]` | 按最近更新列出各智能体的会话 |
+| `1session list [--limit n] [--scope <path>\|cwd\|global] [--provider name] [--since 24h] [--json]` | 按最近更新列出各智能体的会话（默认当前 pwd 子树，见 `--scope`） |
 | `1session overview <session-id> [--json]` | **第 1 层**：统计卡片（轮次/文件/命令/提交/产物/上传/后台任务/token）+ 目标、口径修正、状态锚点、全量落盘 |
 | `1session turns <session-id> [--json]` | **第 2 层**：逐轮概要——时间、耗时、事件区间、文件/命令/失败数、用户说了什么、agent 回了什么 |
 | `1session turn <session-id> <n> [--event k] [--json]` | **第 3 层**：展开某一轮的全部事件；`--event` 定位单次工具调用，输出完整参数与**未截断**结果 |
@@ -46,12 +46,57 @@ npm run build && node dist/bin/1session.js <command>
 | `1session commands <id> [--failed] [--host h] [--turn n] [--json]` | 命令账本：exit_code / 耗时 / cwd |
 | `1session files <id> [--group project\|runtime\|log\|all] [--json]` | 文件账本，按项目 / 运行态 / 日志分组 |
 | `1session errors <id> [--json]` | 失败命令，带 stderr 与"同前缀命令后续是否成功" |
-| `1session search <query> [--workspace p] [--since 24h] [--limit n] [--kind k1,k2] [--regex] [--case] [--context n] [--max-hits n] [--json]` | 跨会话全文检索：命中轮次 + 上下文片段 |
-| `1session index [<id>] [--all] [--force] [--since 30d]` | 建立 / 刷新索引；`--all` 全库回填 |
+| `1session search <query> [--scope <path>\|cwd\|global] [--since 24h] [--limit n] [--kind k1,k2] [--regex] [--case] [--context n] [--max-hits n] [--json]` | 跨会话全文检索：命中轮次 + 上下文片段（默认当前 pwd 子树，见 `--scope`） |
+| `1session index [<id>] [--all] [--scope <path>\|cwd\|global] [--force] [--since 30d]` | 建立 / 刷新索引；`--all` 全库回填 |
 | `1session graph <id> [--json]`（别名 `related`） | 会话之间的引用关系 + 每条边的证据 |
 
 全局开关 `--no-index` 绕过索引直读源文件。
 
+### `--scope`：会话按路径子树取
+
+`list` / `search` / `index --all` **默认只看当前 pwd 这棵子树下的会话**；跨项目要显式说出来。`--scope` 取三种值：
+
+| 值 | 含义 |
+| --- | --- |
+| 省略 / `cwd` | 当前 pwd **及其所有子目录**下的会话 |
+| 相对路径（`..`、`../web`、`~/proj`）或绝对路径（`/Users/me/proj`） | 该目录**及其所有子目录**下的会话 |
+| `global`（或 `--global`，或 `--scope /`） | 全部会话 |
+
+按子树取而不是按目录相等取：`--scope ~/Documents` 会列出 `~/Documents` 下每一个项目的会话，而不只是恰好在 `~/Documents` 里启动的那几个。目录写错会直接报错，不会静悄悄地返回"0 个会话"。
+
+```bash
+1session list                        # 当前项目（含子模块）
+1session list --scope ..             # 连同同级的兄弟项目
+1session list --scope ~/Documents    # 这棵树下的全部项目
+1session list --global               # 全部
+1session search "超时" --scope ../..  # 在祖父目录这棵树里检索
+1session index --all --global        # 全库回填索引
+```
+
+（`--workspace <path>` 是路径形式的旧拼法，仍然可用，优先于 `--scope`。）
+
+**路径从哪来**（三家各写各的，读之前先归一）：
+
+| Provider | 项目路径 | 时间 |
+| --- | --- | --- |
+| claude | 目录名 = cwd 的 slug（`~/.claude/projects/-Users-me-proj/`），每行 JSONL 另带 `cwd` | `updatedAt` = 文件 mtime；`createdAt` = 首行 `timestamp` |
+| codex | 目录只按日期分（`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`），路径只在 `session_meta` / `turn_context` 的 `payload.cwd` 里 | `updatedAt` = mtime；`createdAt` = `session_meta.timestamp`，兜底解析文件名里的时间戳 |
+| antigravity | transcript 里没有 cwd，但 IDE 自己维护着项目↔会话的关系：`~/.gemini/antigravity/conversations/<id>.db` 的 `trajectory_metadata_blob` 里存着打开的目录（protobuf 字段 1.1，`file://` URI；1.2 是外层 workspace 根，1.4 是 git 分支）。读它，读不到才退回从工具参数里猜 | `updatedAt` = mtime；`createdAt` = 首个 step 的 `created_at` |
+
+排序和 `--since` 都只用 mtime，`listCandidates()` 一次 `stat` 就够，不必打开文件 —— 打开文件（拿标题、cwd、创建时间）才是贵的那一步，所以它走索引缓存。
+
+Antigravity 的 626 个会话里，本机有 14 个至今没有路径 —— 不是没读到，是 IDE 自己把它们标成了 `outside-of-project`（开着聊天窗口、没开文件夹时起的会话）。这类会话只在 `--global` 下出现。
+
+### 列表为什么是全的
+
+`list` / `workspace` / `search` 都走索引：先对每个会话文件做一次指纹检查（size + mtime + 头部哈希），**只有字节动过的才重新解析**，然后用一条 SQL 出结果。所以：
+
+- 没有扫描预算，`--scope` 再大也不会悄悄丢掉更早的会话；
+- 第一次全量解析本机 625 个会话约 **10s**，之后每次 `list` 约 **0.5s**；
+- `--no-index` 仍然可以绕开索引直读源文件，两条路的结果应当逐条一致（可以 `diff` 验证）。
+
+升级到这一版后，索引会因为 `PARSER_VERSION` 提升而自动重建一次（antigravity 的 workspace 口径变了），无需手动清库；想主动做可以跑 `1session index --all --global`。
+
 `<session-id>` 支持完整 id、id 前缀（≥6 位）或原始文件路径。
 
 ```bash

package/dist/bin/1session.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { aggregateWorkspaceSessions } from '../src/aggregator.js';
 import { distillSession } from '../src/distiller.js';
@@ -11,7 +12,7 @@ import { canonicalizePath } from '../src/util/paths.js';
 import { oneLine } from '../src/util/text.js';
 const USAGE = `1session — cross-agent session Read Plane
 
-  1session list [--limit <n>] [--workspace <path>] [--provider <name>] [--since 24h] [--json]
+  1session list [--limit <n>] [--scope <path>|cwd|global] [--provider <name>] [--since 24h] [--json]
   1session overview <session-id> [--json]              第 1 层：会话概要
   1session turns <session-id> [--json]                 第 2 层：逐轮概要
   1session turn <session-id> <n> [--event <k>] [--json] 第 3 层：单轮 / 单次工具调用明细
@@ -21,19 +22,22 @@ const USAGE = `1session — cross-agent session Read Plane
   1session errors <session-id> [--json]
   1session digest <session-id> [--focus marketing|review|full] [--json]
   1session workspace [path] [--since 24h] [--limit <n>] [--digest] [--focus <f>] [--json]
-  1session index [<session-id>] [--all] [--force] [--since 30d]  建立/刷新索引
+  1session index [<session-id>] [--all] [--scope <path>|cwd|global] [--force] [--since 30d]  建立/刷新索引
   1session graph <session-id> [--json]                 会话之间的引用关系
-  1session search <query> [--workspace path] [--since 24h] [--limit n] [--provider name]
+  1session search <query> [--scope <path>|cwd|global] [--since 24h] [--limit n] [--provider name]
                           [--kind user,assistant,thinking,tool_call,tool_result]
                           [--regex] [--case] [--context n] [--max-hits n] [--json]
 
 全局：--no-index 绕过索引直读源文件。索引位于 ~/.1agents/session-reader/index.db
+     list / search / index --all 默认只看当前 pwd 目录（含子目录）下的会话。
+     --scope 取当前目录的相对路径或绝对路径，按子树匹配：--scope .. 含同级项目，
+     --scope ~ 含 home 下全部；--global（= --scope global，= --scope /）跨全部项目。
 
 Providers: antigravity (~/.gemini/antigravity/brain), claude (~/.claude/projects), codex (~/.codex/sessions).
 `;
 /** Flags that never take a value, so they cannot swallow a positional. */
 const BOOLEAN_FLAGS = new Set([
-    'json', 'failed', 'digest', 'regex', 'case', 'all', 'force', 'no-index',
+    'json', 'failed', 'digest', 'regex', 'case', 'all', 'force', 'no-index', 'global',
 ]);
 function parseArgs(argv) {
     const [command = 'help', ...rest] = argv;
@@ -85,6 +89,23 @@ const focusOf = (value) => {
     const focus = str(value);
     return focus === 'marketing' || focus === 'full' ? focus : 'review';
 };
+/**
+ * Which folder a listing covers. `cwd` (the default) is the current working
+ * directory, `global` is everything, and anything else is read as a path —
+ * relative to the cwd or absolute — whose whole subtree is included, so
+ * `--scope ..` covers the sibling projects too and `--scope /` is `global`.
+ * `--workspace <path>` is the older spelling of the path form and wins.
+ */
+function scopeWorkspace(flags) {
+    const scope = str(flags.workspace) ?? str(flags.scope) ?? (flags.global === true ? 'global' : 'cwd');
+    if (scope === 'global')
+        return undefined;
+    const target = canonicalizePath(scope === 'cwd' ? process.cwd() : scope);
+    // A mistyped path would otherwise read as an honest "no sessions found".
+    if (!existsSync(target))
+        throw new Error(`--scope 目录不存在：${scope}`);
+    return target;
+}
 function print(json, data, text) {
     console.log(json ? JSON.stringify(data, null, 2) : text);
 }
@@ -114,9 +135,10 @@ async function main() {
         case 'list': {
             const refs = await listRecentSessions({
                 limit: num(flags.limit) ?? 20,
-                workspace: str(flags.workspace),
+                workspace: scopeWorkspace(flags),
                 since: str(flags.since),
                 provider: str(flags.provider),
+                useIndex,
             });
             print(json, refs, refs
                 .map((ref) => `${ref.provider.padEnd(11)} ${ref.id.slice(0, 8)}  ${ref.updatedAt ?? '?'}  ` +
@@ -210,6 +232,7 @@ async function main() {
                 workspace: target,
                 since: str(flags.since),
                 limit: num(flags.limit) ?? 50,
+                useIndex,
             });
             print(json, { workspace: target, sessions: refs }, [
                 `workspace ${target}`,
@@ -273,7 +296,7 @@ async function main() {
         case 'search': {
             const query = positional.join(' ');
             const hits = await searchSessions(query, {
-                workspace: str(flags.workspace),
+                workspace: scopeWorkspace(flags),
                 since: str(flags.since),
                 limit: num(flags.limit),
                 provider: str(flags.provider),
@@ -328,6 +351,7 @@ async function main() {
             const handles = await listResolvedSessions({
                 limit: num(flags.limit) ?? Number.POSITIVE_INFINITY,
                 scan: num(flags.scan) ?? Number.POSITIVE_INFINITY,
+                workspace: scopeWorkspace(flags),
                 ...(str(flags.since) ? { since: str(flags.since) } : {}),
                 ...(str(flags.provider) ? { provider: str(flags.provider) } : {}),
             });

package/dist/src/parsers/antigravity.d.ts

@@ -1,4 +1,13 @@
 import type { ProviderAdapter } from './provider.js';
+/**
+ * The folder a trajectory was opened in, out of the IDE's own metadata blob.
+ *
+ * Field 1.1 is that folder as a `file://` URI (1.2 holds the enclosing
+ * workspace root when the two differ, 1.4 the git branch). Sessions started
+ * with no folder open — the IDE labels them `outside-of-project` — carry no
+ * field 1 at all, and an unknown workspace is the honest answer for them.
+ */
+export declare function workspaceFromTrajectoryBlob(data: Uint8Array): string | undefined;
 export declare const antigravityAdapter: ProviderAdapter;
 /** Antigravity shortens long step output in the transcript; this is the full copy. */
 export declare function readFullStepOutput(transcriptPath: string, stepIndex: number): Promise<string | undefined>;

package/dist/src/parsers/antigravity.js

@@ -3,9 +3,12 @@ import os from 'node:os';
 import path from 'node:path';
 import { readJsonl } from '../util/jsonl.js';
 import { canonicalizePath, findRepoRoot } from '../util/paths.js';
+import { importSqlite } from '../util/sqlite.js';
 import { clip, oneLine, stripPromptEnvelope } from '../util/text.js';
 import { emptyProviderStats, } from '../types.js';
 const BRAIN_DIR = path.join(os.homedir(), '.gemini', 'antigravity', 'brain');
+/** The IDE's own project↔session mapping: one SQLite file per conversation. */
+const CONVERSATIONS_DIR = path.join(os.homedir(), '.gemini', 'antigravity', 'conversations');
 const TRANSCRIPTS = ['transcript.jsonl', 'transcript_full.jsonl'];
 /** Args whose value is an absolute path we can use to locate the repository. */
 const PATH_ARGS = ['AbsolutePath', 'DirectoryPath', 'SearchPath', 'TargetFile', 'FilePath'];
@@ -76,6 +79,85 @@ function unwrapArgs(args) {
     }
     return out;
 }
+/** One protobuf varint: its value and the offset just past it. */
+function varint(buf, at) {
+    let value = 0;
+    let shift = 0;
+    let i = at;
+    while (i < buf.length) {
+        const byte = buf[i++];
+        value += (byte & 0x7f) * 2 ** shift;
+        shift += 7;
+        if (!(byte & 0x80))
+            break;
+    }
+    return [value, i];
+}
+/** The bytes of the first length-delimited field `no`, or nothing. */
+function protoField(buf, no) {
+    let i = 0;
+    while (i < buf.length) {
+        const [key, afterKey] = varint(buf, i);
+        const wire = key & 7;
+        if (wire === 2) {
+            const [length, afterLength] = varint(buf, afterKey);
+            if (key >>> 3 === no)
+                return buf.subarray(afterLength, afterLength + length);
+            i = afterLength + length;
+            continue;
+        }
+        // Skip the fixed and varint shapes; anything else is not a message we know.
+        if (wire === 0)
+            i = varint(buf, afterKey)[1];
+        else if (wire === 5)
+            i = afterKey + 4;
+        else if (wire === 1)
+            i = afterKey + 8;
+        else
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * The folder a trajectory was opened in, out of the IDE's own metadata blob.
+ *
+ * Field 1.1 is that folder as a `file://` URI (1.2 holds the enclosing
+ * workspace root when the two differ, 1.4 the git branch). Sessions started
+ * with no folder open — the IDE labels them `outside-of-project` — carry no
+ * field 1 at all, and an unknown workspace is the honest answer for them.
+ */
+export function workspaceFromTrajectoryBlob(data) {
+    const opened = protoField(Buffer.from(data), 1);
+    const uri = opened && protoField(opened, 1);
+    return uri?.length ? canonicalizePath(uri.toString('utf8')) : undefined;
+}
+/**
+ * The workspace as the IDE itself records it.
+ *
+ * Antigravity keeps a SQLite file per conversation whose `trajectory_metadata_blob`
+ * holds the blob above. That is the same relation the IDE draws its project
+ * list from, so it beats guessing from tool arguments — which returns the git
+ * root, or a path from some other tree the session happened to touch first.
+ */
+async function workspaceFromConversation(id) {
+    const file = path.join(CONVERSATIONS_DIR, `${id}.db`);
+    if (!(await fs.access(file).then(() => true, () => false)))
+        return undefined;
+    const { DatabaseSync } = await importSqlite();
+    let db;
+    try {
+        db = new DatabaseSync(file, { readOnly: true });
+        const row = db.prepare('SELECT data FROM trajectory_metadata_blob LIMIT 1').get();
+        return row?.data ? workspaceFromTrajectoryBlob(row.data) : undefined;
+    }
+    catch {
+        // A half-written or future-shaped database is not worth failing a listing over.
+        return undefined;
+    }
+    finally {
+        db?.close();
+    }
+}
 function workspaceFromCall(name, args) {
     if (name === 'run_command' && typeof args.Cwd === 'string' && args.Cwd) {
         return canonicalizePath(args.Cwd);
@@ -165,7 +247,7 @@ export const antigravityAdapter = {
     },
     async scanRef(candidate) {
         let title;
-        let workspace;
+        let workspace = await workspaceFromConversation(candidate.id);
         let createdAt;
         for await (const raw of readJsonl(candidate.path, { maxLines: 400 })) {
             const step = raw;
@@ -215,7 +297,7 @@ export const antigravityAdapter = {
     async parse(candidate) {
         const turns = [];
         let title;
-        let workspace;
+        let workspace = await workspaceFromConversation(candidate.id);
         let createdAt;
         const stats = emptyProviderStats();
         const push = (turn) => {

package/dist/src/parsers/claude.js

@@ -53,11 +53,14 @@ export const claudeAdapter = {
         return found.sort((a, b) => b.mtimeMs - a.mtimeMs);
     },
     /**
-     * Only the head of the file is read, so the title is the opening request —
-     * a session's own `custom-title`/`ai-title` is picked up by {@link parse}.
+     * Only the head of the file is read. Claude writes its own titles a few
+     * lines after the opening request, so the scan does not stop at the first
+     * prompt — it keeps reading the head for a `custom-title`/`ai-title`.
      */
     async scanRef(candidate) {
-        let title;
+        let customTitle;
+        let aiTitle;
+        let firstPrompt;
         let workspace;
         let createdAt;
         for await (const raw of readJsonl(candidate.path, { maxLines: 60 })) {
@@ -66,18 +69,21 @@ export const claudeAdapter = {
                 workspace ??= canonicalizePath(entry.cwd);
             createdAt ??= entry.timestamp;
             if (entry.type === 'custom-title' && entry.customTitle)
-                title = entry.customTitle;
-            if (!title && entry.type === 'user' && !entry.isMeta && typeof entry.message?.content === 'string') {
-                title = oneLine(stripPromptEnvelope(entry.message.content), 120);
+                customTitle = entry.customTitle;
+            if (entry.type === 'ai-title' && entry.aiTitle)
+                aiTitle = entry.aiTitle;
+            if (!firstPrompt && entry.type === 'user' && !entry.isMeta && typeof entry.message?.content === 'string') {
+                firstPrompt = oneLine(stripPromptEnvelope(entry.message.content), 120);
             }
-            if (title && workspace)
+            // A user-set title outranks everything, so nothing later can beat it.
+            if (customTitle && workspace)
                 break;
         }
         return {
             id: candidate.id,
             provider: 'claude',
             path: candidate.path,
-            title,
+            title: customTitle ?? aiTitle ?? firstPrompt,
             workspace,
             createdAt,
             updatedAt: new Date(candidate.mtimeMs).toISOString(),
@@ -91,7 +97,8 @@ export const claudeAdapter = {
         let cacheRead = 0;
         // One assistant message can appear on several entries; count its usage once.
         const countedUsage = new Set();
-        let title;
+        let customTitle;
+        let aiTitle;
         let firstPrompt;
         let workspace;
         let createdAt;
@@ -108,9 +115,9 @@ export const claudeAdapter = {
                 updatedAt = entry.timestamp;
             }
             if (entry.type === 'custom-title' && entry.customTitle)
-                title = entry.customTitle;
-            if (entry.type === 'ai-title' && typeof entry.title === 'string')
-                title ??= entry.title;
+                customTitle = entry.customTitle;
+            if (entry.type === 'ai-title' && entry.aiTitle)
+                aiTitle = entry.aiTitle;
             if (entry.gitBranch && !stats.branches.includes(entry.gitBranch))
                 stats.branches.push(entry.gitBranch);
             const model = entry.message?.model;
@@ -189,7 +196,7 @@ export const claudeAdapter = {
                 id: candidate.id,
                 provider: 'claude',
                 path: candidate.path,
-                title: title ?? firstPrompt,
+                title: customTitle ?? aiTitle ?? firstPrompt,
                 workspace,
                 createdAt,
                 updatedAt: updatedAt ?? new Date(candidate.mtimeMs).toISOString(),

package/dist/src/resolver.d.ts

@@ -3,6 +3,13 @@ import type { AgentProvider, NormalizedSession, SessionRef } from './types.js';
 export declare const adapters: ProviderAdapter[];
 export interface ListOptions {
     limit?: number;
+    /**
+     * Serve the listing from the index (the default). The sweep still checks
+     * every session file's fingerprint, but only the ones whose bytes moved are
+     * parsed again — so a listing is complete regardless of `scan`, and cheap
+     * after the first run. Set false to read the source files directly.
+     */
+    useIndex?: boolean;
     /**
      * How many session files may be opened. Defaults to a small budget so an
      * unfiltered `list` stays cheap; pass `Infinity` when completeness matters

package/dist/src/resolver.js

@@ -44,7 +44,10 @@ function couldBelong(candidate, provider, workspace) {
 /** Discovery that keeps the adapter handle, so callers can parse without a second scan. */
 export async function listResolvedSessions(options = {}) {
     const limit = options.limit ?? 20;
-    const workspace = options.workspace ? canonicalizePath(options.workspace) : undefined;
+    // `/` contains every session by definition, so filtering on it would only
+    // cost a scan and drop the sessions whose cwd we could not recover.
+    const scoped = options.workspace ? canonicalizePath(options.workspace) : undefined;
+    const workspace = scoped && scoped !== '/' ? scoped : undefined;
     const sinceMs = parseSince(options.since);
     const found = [];
     for (const adapter of adapters) {
@@ -74,7 +77,43 @@ export async function listResolvedSessions(options = {}) {
         .slice(0, limit);
 }
 export async function listRecentSessions(options = {}) {
-    return (await listResolvedSessions(options)).map((session) => session.ref);
+    if (options.useIndex === false || process.env.SESSION_READER_NO_INDEX === '1') {
+        return (await listResolvedSessions(options)).map((session) => session.ref);
+    }
+    return listIndexedSessions(options);
+}
+/**
+ * The listing as the index sees it: a fingerprint sweep over every candidate
+ * (cheap once indexed), then one SQL query. Unlike the scanning path this one
+ * has no candidate budget, so a workspace never quietly loses its older
+ * sessions once a provider grows past `WORKSPACE_SCAN` files.
+ */
+async function listIndexedSessions(options) {
+    const { openStore } = await import('./store/db.js');
+    const { refreshSession } = await import('./store/indexer.js');
+    const { listSessionRows, refOf } = await import('./store/read.js');
+    const db = await openStore();
+    const sinceMs = parseSince(options.since);
+    const ids = [];
+    for (const adapter of adapters) {
+        if (options.provider && adapter.provider !== options.provider)
+            continue;
+        for (const candidate of await adapter.listCandidates()) {
+            if (sinceMs && candidate.mtimeMs < sinceMs)
+                break; // candidates are newest first
+            const result = await refreshSession(db, { adapter, candidate }, { edges: false }).catch(() => undefined);
+            if (result)
+                ids.push(result.id);
+        }
+    }
+    const scoped = options.workspace ? canonicalizePath(options.workspace) : undefined;
+    return listSessionRows(db, {
+        ids,
+        ...(scoped && scoped !== '/' ? { workspace: scoped } : {}),
+        ...(options.provider ? { provider: options.provider } : {}),
+        ...(sinceMs ? { sinceMs } : {}),
+        limit: options.limit ?? 20,
+    }).map(refOf);
 }
 export async function findSessionsByWorkspace(workspacePath, options = {}) {
     return listRecentSessions({ ...options, limit: options.limit ?? 50, workspace: workspacePath });

package/dist/src/store/db.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { importSqlite } from '../util/sqlite.js';
 import { DDL, SCHEMA_VERSION } from './schema.js';
 /** Where the index lives. `SESSION_READER_DB` overrides it (tests, CI). */
 export function defaultDbPath() {
@@ -9,26 +10,6 @@ export function defaultDbPath() {
         return override;
     return path.join(os.homedir(), '.1agents', 'session-reader', 'index.db');
 }
-/**
- * `node:sqlite` is still flagged experimental and prints a warning on load.
- * Filtering just that one message keeps every other warning intact — far less
- * rude than `removeAllListeners('warning')`.
- */
-async function importSqlite() {
-    const original = process.emitWarning;
-    process.emitWarning = ((warning, ...rest) => {
-        const text = typeof warning === 'string' ? warning : (warning?.message ?? '');
-        if (text.includes('SQLite is an experimental feature'))
-            return;
-        return original.call(process, warning, ...rest);
-    });
-    try {
-        return await import('node:sqlite');
-    }
-    finally {
-        process.emitWarning = original;
-    }
-}
 let cached;
 let cachedPath;
 /**

package/dist/src/store/read.d.ts

@@ -25,5 +25,19 @@ export interface SessionRow {
 export declare function sessionRow(db: DatabaseSync, id: string): SessionRow | undefined;
 /** Resolves a full id, an id prefix, or a native id against the index. */
 export declare function findSessionRow(db: DatabaseSync, needle: string): SessionRow | undefined;
+export interface ListQuery {
+    /** Ids seen on disk during this sweep; rows outside it are stale and skipped. */
+    ids: string[];
+    /** Canonical root; matches the directory itself and everything under it. */
+    workspace?: string;
+    provider?: string;
+    sinceMs?: number;
+    limit?: number;
+}
+/**
+ * The listing served from the index: newest first, no scan budget, so a
+ * workspace never silently loses its older sessions to a candidate cap.
+ */
+export declare function listSessionRows(db: DatabaseSync, query: ListQuery): SessionRow[];
 export declare function refOf(row: SessionRow): SessionRef;
 export declare function readSession(db: DatabaseSync, row: SessionRow): NormalizedSession;

package/dist/src/store/read.js

@@ -15,6 +15,40 @@ export function findSessionRow(db, needle) {
         .prepare('SELECT * FROM sessions WHERE native_id LIKE ? ORDER BY ended_at DESC LIMIT 1')
         .get(`${needle}%`);
 }
+/**
+ * The listing served from the index: newest first, no scan budget, so a
+ * workspace never silently loses its older sessions to a candidate cap.
+ */
+export function listSessionRows(db, query) {
+    if (!query.ids.length)
+        return [];
+    db.exec('DROP TABLE IF EXISTS temp.list_scope');
+    db.exec('CREATE TEMP TABLE list_scope (id TEXT PRIMARY KEY)');
+    const insert = db.prepare('INSERT OR IGNORE INTO temp.list_scope (id) VALUES (?)');
+    for (const id of query.ids)
+        insert.run(id);
+    const where = ['id IN (SELECT id FROM temp.list_scope)'];
+    const params = [];
+    if (query.workspace) {
+        // Prefix comparison rather than LIKE: real paths contain `_`, a LIKE wildcard.
+        where.push('(workspace = ? OR substr(workspace, 1, ?) = ?)');
+        params.push(query.workspace, query.workspace.length + 1, `${query.workspace}/`);
+    }
+    if (query.provider) {
+        where.push('provider = ?');
+        params.push(query.provider);
+    }
+    if (query.sinceMs) {
+        where.push('source_mtime_ms >= ?');
+        params.push(query.sinceMs);
+    }
+    params.push(query.limit ?? 20);
+    return db
+        .prepare(`SELECT * FROM sessions WHERE ${where.join(' AND ')} ` +
+        // Undated rows sort last instead of first, which is where DESC puts NULL.
+        'ORDER BY (ended_at IS NULL), ended_at DESC LIMIT ?')
+        .all(...params);
+}
 export function refOf(row) {
     return {
         id: row.native_id,

package/dist/src/store/schema.d.ts

@@ -9,7 +9,7 @@
 /** DDL layout. A bump drops and rebuilds the whole database. */
 export declare const SCHEMA_VERSION = 1;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
-export declare const PARSER_VERSION = 1;
+export declare const PARSER_VERSION = 2;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
 export declare const EXTRACTOR_VERSION = 1;
 /** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */

package/dist/src/store/schema.js

@@ -9,7 +9,7 @@
 /** DDL layout. A bump drops and rebuilds the whole database. */
 export const SCHEMA_VERSION = 1;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
-export const PARSER_VERSION = 1;
+export const PARSER_VERSION = 2;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
 export const EXTRACTOR_VERSION = 1;
 /** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */

package/dist/src/util/sqlite.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `node:sqlite` is still flagged experimental and prints a warning on load.
+ * Filtering just that one message keeps every other warning intact — far less
+ * rude than `removeAllListeners('warning')`.
+ */
+export declare function importSqlite(): Promise<typeof import('node:sqlite')>;

package/dist/src/util/sqlite.js

@@ -0,0 +1,20 @@
+/**
+ * `node:sqlite` is still flagged experimental and prints a warning on load.
+ * Filtering just that one message keeps every other warning intact — far less
+ * rude than `removeAllListeners('warning')`.
+ */
+export async function importSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const text = typeof warning === 'string' ? warning : (warning?.message ?? '');
+        if (text.includes('SQLite is an experimental feature'))
+            return;
+        return original.call(process, warning, ...rest);
+    });
+    try {
+        return await import('node:sqlite');
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/session-reader",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
   "keywords": [
     "claude-code",
@@ -30,7 +30,7 @@
     }
   },
   "bin": {
-    "1session": "./dist/bin/1session.js"
+    "1session": "dist/bin/1session.js"
   },
   "files": [
     "dist",