@1agents/session-reader 0.3.0 → 0.5.0

package/README.md

@@ -22,7 +22,9 @@ npm install -g @1agents/session-reader  # 作为 1session 命令
 npx @1agents/session-reader list      # 不安装直接用
 ```
 
-要求 Node.js >= 22.5（依赖内置的 `node:sqlite`），零运行时依赖。
+要求 Node.js >= 22.5（依赖内置的 `node:sqlite`）。
+唯一的运行时依赖是自家的 [`@1agents/dreammate-network`](https://github.com/scottzx/dreammate-network)
+——L0 协议定义，12 kB，本身零依赖——`npm install` 会自动带上，不需要单独装。
 
 ## 内置 skill：一条命令装到三家智能体
 
@@ -67,14 +69,14 @@ npm run build && node dist/bin/1session.js <command>
 | `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` 定位单次工具调用，输出完整参数与**未截断**结果 |
+| `1session turn <session-id> <n> [--event k\|a-b\|a,b,c] [--json]` | **第 3 层**：展开某一轮的全部事件；`--event` 定位工具调用，输出完整参数与**未截断**结果，支持 `491`、`491-493`、`491,495,502` |
 | `1session digest <session-id> [--focus marketing\|review\|full] [--json]` | 单会话蒸馏：目标、改动文件、命令、关键节点 |
 | `1session workspace [path] [--since 24h] [--limit n] [--digest] [--focus f] [--json]` | **按 pwd 跨智能体聚合**（默认 `.`）；带 `--digest` 输出统一故事线 |
 | `1session jobs <id> [--json]` | 异步作业账本：状态 + **证据** + pid / host / log |
 | `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> [--scope <path>\|cwd\|global] [--since 24h] [--limit n] [--kind k1,k2] [--regex] [--case] [--context n] [--max-hits n] [--json]` | 跨会话全文检索：命中轮次 + 上下文片段（默认当前 pwd 子树，见 `--scope`） |
+| `1session search <query> [--scope <path>\|cwd\|global] [--since 24h] [--limit n] [--kind k1,k2] [--regex] [--case] [--context n] [--max-hits n] [--include-self] [--json]` | 跨会话全文检索：命中带 `T<轮次> · E<事件号>` 句柄 + 上下文片段（默认当前 pwd 子树，见 `--scope`） |
 | `1session index [<id>] [--all] [--scope <path>\|cwd\|global] [--force] [--since 30d]` | 建立 / 刷新索引；`--all` 全库回填 |
 | `1session graph <id> [--json]`（别名 `related`） | 会话之间的引用关系 + 每条边的证据 |
 | `1session skill install\|status\|uninstall [--agent a,b] [--copy] [--force] [--dry-run]` | 把内置 skill 装进三家智能体的 skills 目录（见上） |
@@ -156,9 +158,14 @@ T 3 2026-09-11T13:03:29 (283s)  事件 29–45  文件 1 · 命令 7 · 失败 0
 ```
 
 ```bash
-1session turn 5575981e 1 --event 11   # 第 3 层：单次工具调用的完整输出
+1session turn 5575981e 1 --event 11      # 第 3 层：单次工具调用的完整输出
+1session turn 5575981e 1 --event 11-13   # 连着看：调用 + 结果 + 助理的判断
 ```
 
+`--event` 收 `11`、`11-13`、`11,15,22` 及其混合，一次最多 50 条；区间会按会话长度裁剪，
+所以 `560-999` 就是「看到结尾」。读一次工具调用通常要连读它的结果和后面那条助理判断——
+一个进程读完，而不是起三次。
+
 第三层会自动补全被截断的内容：antigravity 的 `transcript.jsonl` 会把长输出截短（事件 #11 只存了 4092 字符），命令会回读 `.system_generated/steps/8/output.txt` 拿到完整的 6937 字节并标注 `[已从 steps/ 补全]`；补不回来时如实提示 `⚠️ steps/N/output.txt 不存在`。
 
 跨会话检索（`--kind` 可过滤轮次类型，只看用户说了什么 / 只看工具调用）：
@@ -169,12 +176,22 @@ T 3 2026-09-11T13:03:29 (283s)  事件 29–45  文件 1 · 命令 7 · 失败 0
 
 ```text
 4 处命中，分布在 2 个会话
+（已折叠 1 处本次检索自身留下的回声；--include-self 展开）
 
 ### antigravity 5575981e  2026-09-13T00:21:05Z → 2026-09-13T03:31:58Z  (2 命中)
-  #318 user  /xhs-tech-card 结合 docs/xhs_sol_h3_spark_output/index.html，第一次实战经验贴。
-  #441 user  /mobile-xhs-publisher
+  T7 · E318 user  /xhs-tech-card 结合 docs/xhs_sol_h3_spark_output/index.html，第一次实战经验贴。
+  T9 · E441 user  /mobile-xhs-publisher
+    ↳ 1session turn 5575981e 7 --event 318
 ```
 
+每条命中前缀就是**下钻句柄** `T<轮次> · E<事件号>`——顺序照着 `turn <id> <T> --event <E>` 排，
+每个会话再附一条拼好的命令，从第 1 层到第 3 层不用再跑一趟 `turns` 人工比对事件区间。
+
+**默认折叠本次检索自己留下的脚印**：调用方的会话是边跑边索引的，`1session search "X"` 这条
+命令本身（以及它打印出来的东西）会立刻成为 `X` 的第一条命中。判据只有一条——五分钟内写下的
+`1session` 调用及其结果；只有活着的那个 transcript 才可能有「此刻」的时间戳，所以历史会话一条
+都不会被碰到。折叠了多少永远会打印出来，`--include-self` 可以全部展开。
+
 输出示例（上午 Antigravity 定方案 → 下午 Claude Code 落地实现，自动交织成一条时间线）：
 
 ```markdown
@@ -204,6 +221,7 @@ import {
   summarizeTurns,
   turnDetail,
   eventDetail,
+  eventDetails,
 } from '@1agents/session-reader';
 
 const sessions = await findSessionsByWorkspace(process.cwd(), { since: '7d' });
@@ -215,8 +233,13 @@ const overview = buildOverview(session);      // 第 1 层：overview.stats / ov
 const turns = summarizeTurns(session);        // 第 2 层
 const detail = turnDetail(session, 3);        // 第 3 层
 const full = await eventDetail(session, 11);  // 第 3 层：未截断的单次工具输出
+const around = await eventDetails(session, '11-13'); // 相邻几条一起读
+hits[0]?.matches[0]?.turn;                    // 命中所在轮次，与 match.index 凑成 T·E 句柄
 ```
 
+`searchSessions` 另接 `selfSessionId` 显式指明调用方（默认取 `SESSION_READER_CALLER_SESSION`）；
+被判定为「调用方自己」的命中不会被删掉，而是带上 `self` / `suppressed` 标记返回，展不展示由调用方定。
+
 `aggregateWorkspaceSessions` 返回 `WorkspaceDigest`：`sessions` / `collaboratingAgents` /
 `unifiedTimeline`（按时间排序的跨智能体节点）/ `fileAttribution`（文件 → 谁在什么时候改的）/ `markdown`。
 适合直接喂给下游做小红书笔记、PRD、周报与 changelog，也可零成本包成 DeepSeek Harness（Cordis）插件或 MCP server。
@@ -265,6 +288,20 @@ const full = await eventDetail(session, 11);  // 第 3 层：未截断的单次
 
 同样的原则贯穿每一处：**没有证据就不断言**。异步作业只在有完成回执时标 `completed`，否则一律 `unknown` 并写明依据；没有打印 exit code 的命令结果，`exitCode` 就是空，绝不补成 0。
 
+### 三级溯源回答不了的那一问：现在还成不成立
+
+`observed / derived / candidate` 回答的是**这个事实怎么来的**，不是**它现在还对不对**。
+overview 的「末态」恰恰是最易腐的一段：
+
+> 凡是关于**当前状态**的问题（凭据、环境变量、装了哪个版本、文件还在不在），会话只能告诉你
+> 它**最后一次为真是什么时候**——去核实。转录记下的是说过什么和退出码，不是效果。
+
+三种真实撞上过的情况：一条命令退出码为 0、无报错，但它读到的是空输入，写进配置的是个空值；
+某一轮的结论说「现在存了三份」，其中一份是只活在当时那个 shell 里的临时函数，从没落盘；
+「某某已配好」在当时是对的，三周后需要另外验证。会话忠实记录了意图和退出码，记不下效果——
+这是转录这种载体的边界，不是提取规则的疏漏，所以本模块不打算用更聪明的规则去补它，
+只把话说清楚。
+
 ## 轮次完成状态
 
 第二层每一轮带一个**有证据的状态**——只说这一轮有没有收尾，不说做成了什么：
@@ -402,6 +439,87 @@ $ 1session graph ca8325e1
 
 运行时捕获：若环境注入了 `SESSION_READER_CALLER_SESSION`，调用当下就直接落边（`observed / runtime:caller-env`），无需事后从历史里恢复。
 
+## `1session serve`：接入 DreamMate Network
+
+把本地 Read Plane 原样暴露成网络能力——`1session overview <id>` 成为 `sessions.read`。
+**不重新实现索引与事实层**，只是换一个调用入口。不引第三方 HTTP 框架，只用 `node:http`。
+
+```bash
+1session serve                                  # 默认 127.0.0.1:7777
+1session serve --host 100.x.x.x --token <t>     # 暴露到 tailnet
+```
+
+启动时默认向本机 [node agent](https://github.com/scottzx/dreammate-node)（36908）报备，
+`--no-report` 可关。**agent 没起时是静默 no-op**，不影响本服务——只是外部得靠约定端口
+碰运气找它，而不是探一个 36908 就看见。报备会如实声明可达性：`--host` 是回环就报
+`localhost`（外部发现得了但连不上），否则报 `network`。
+
+端口 7777 是 [L0 协议](https://github.com/scottzx/dreammate-network) 的**约定端口**
+（`DEFAULT_PORTS['session-registry']`），不是随手挑的：发现是 pull 的——
+Control Plane 从 tailnet 拿到节点后，照着这张表探测 `/manifest` 与 `/health`。
+换成别的端口就探测不到了，得由服务自己 `POST /nodes/register` 告知。
+
+```
+GET /manifest              Node Manifest（dreammate-network node.schema.json）
+GET /health
+GET /v1/node               同 /manifest，本 Service 前缀下的同一份文档
+GET /v1/sessions           ?limit&scope&since&provider
+GET /v1/sessions/:id       会话概要
+GET /v1/sessions/:id/turns 逐轮概要
+GET /v1/search             ?q=&scope=&since=&limit=&provider=&kind=&regex=&case=
+GET /v1/graph/:id          会话之间的引用关系
+```
+
+声明的能力：`sessions.list` `sessions.read` `sessions.turns` `sessions.search` `sessions.graph`。
+
+每个会话都带上网络内的地址：
+
+```
+session://<node>/<runtime>/<session_id>
+session://Scott-Mac.local/claude/87f7a60a-a86e-49c5-b711-e463156a5420
+```
+
+**跨机实测**（Windows 节点读 Mac 的会话，全程没有 Control Plane 参与）：
+
+```
+scott-pc$ curl http://scott-mac.tailfb4720.ts.net:7777/v1/sessions?limit=3
+{ "node": "scott-mac",
+  "sessions": [ { "uri": "session://scott-mac/claude/87f7a60a-…", … } ] }
+```
+
+**读取即落边。** 请求带 `X-Caller-Session: <调用方会话>` 时，读取当下就写入
+`调用方 --references--> 目标`，与 CLI 的 `SESSION_READER_CALLER_SESSION` 是同一条路径。
+两端都必须是本地已索引的会话，否则静默跳过——悬空边比没有边更糟。
+
+**节点身份由 [`@1agents/dreammate-node`](https://github.com/scottzx/dreammate-node) 统一提供**
+（优先 `tailscale status --json` 的 `Self`，缓存 60s）：它是每台机器的公共事实，
+本机所有服务读到同一份，不会各自生成 id 把一台机器裂成几个 Node。
+
+```
+node_id   nigVtDS1s521CNTRL                            ← tailscale ID，重启不变
+name      scott-mac                                    ← DNSName 前缀
+type      macos                                        ← 由 tailscale 的 OS 映射
+base_url  http://scott-mac.tailfb4720.ts.net:7777/v1   ← MagicDNS，跨机可直接用
+```
+
+> ⚠️ 名字取 **DNSName** 而不是 HostName 是有原因的：iOS 设备的 HostName
+> 全是 `localhost`（实测 11 个节点里只有 9 个唯一），几台手机接进来会产出
+> 一模一样的 `session://localhost/yima/...`。DNSName 实测 11/11 唯一且可读。
+
+没装 / 没登录 tailscale 时**静默回退**到本地身份（hostname + 首次生成的 uuid，
+存在 `~/.1agents/node.json`）。回退身份的 name 不保证跨设备唯一，只适合单机自用。
+`manifest.metadata.identity_source` 会如实报告身份来自 `tailscale` 还是 `local`。
+`DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` 覆盖一切（容器或同机第二个实例用）。
+
+**只读、且默认只监听 loopback。** 会话原文含源码、shell 历史和恰好滚过屏幕的密钥，
+所以走出本机必须是一个刻意动作：显式 `--host`，并且最好配 `--token`（`Authorization: Bearer`）。
+非 loopback 且无 token 时启动会告警。非 GET 一律 405。
+
+> 协议定义来自 [`@1agents/dreammate-network`](https://github.com/scottzx/dreammate-network)（L0）。
+> `src/serve/node.ts` 直接 import 它的类型，不再本地抄一份——单向依赖 L2 → L0 是允许的，
+> 而共用同一份定义才谈得上「公共语言」。**schema 是唯一事实源，改类型先去改那个包。**
+> `/manifest` 的 `metadata.protocol_version` 报告本服务遵循的协议版本。
+
 ## 测试
 
 ```bash

package/dist/bin/1session.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { aggregateWorkspaceSessions } from '../src/aggregator.js';
 import { distillSession } from '../src/distiller.js';
 import { buildOverview } from '../src/overview.js';
-import { eventDetail, summarizeTurns, turnDetail } from '../src/turns.js';
+import { eventDetails, summarizeTurns, turnDetail } from '../src/turns.js';
 import { commandLedger, displayPath, errorLedger, fileLedger, jobLedger } from '../src/ledger.js';
 import { listRecentSessions, loadSession } from '../src/resolver.js';
 import { searchSessions } from '../src/search.js';
@@ -15,7 +15,8 @@ const USAGE = `1session — cross-agent session Read Plane
   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 层：单轮 / 单次工具调用明细
+  1session turn <session-id> <n> [--event <k|a-b|a,b,c>] [--json]
+                          第 3 层：单轮 / 单次或多次工具调用明细
   1session jobs <session-id> [--json]                  异步作业账本
   1session commands <session-id> [--failed] [--host h] [--turn n] [--json]
   1session files <session-id> [--group project|runtime|log|all] [--json]
@@ -24,11 +25,17 @@ const USAGE = `1session — cross-agent session Read Plane
   1session workspace [path] [--since 24h] [--limit <n>] [--digest] [--focus <f>] [--json]
   1session index [<session-id>] [--all] [--scope <path>|cwd|global] [--force] [--since 30d]  建立/刷新索引
   1session graph <session-id> [--json]                 会话之间的引用关系
+  1session serve [--port 7777] [--host 127.0.0.1] [--token <t>] [--no-report]
+                          起 HTTP Service，把本机会话接入 DreamMate Network
   1session skill install|status|uninstall [--agent claude,codex,antigravity]
                           [--copy] [--force] [--dry-run] [--json]  装到三家智能体的 skills 目录
   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]
+                          [--regex] [--case] [--context n] [--max-hits n]
+                          [--include-self] [--json]
+
+search 的每条命中带 T<轮次> · E<事件号>，可直接拼成 1session turn <id> <T> --event <E>。
+默认折叠本次检索自身在活跃会话里留下的回声，--include-self 展开。
 
 全局：--no-index 绕过索引直读源文件。索引位于 ~/.1agents/session-reader/index.db
      list / search / index --all 默认只看当前 pwd 目录（含子目录）下的会话。
@@ -40,7 +47,7 @@ Providers: antigravity (~/.gemini/antigravity/brain), claude (~/.claude/projects
 /** 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', 'global',
-    'copy', 'dry-run',
+    'copy', 'dry-run', 'no-report', 'include-self',
 ]);
 function parseArgs(argv) {
     const [command = 'help', ...rest] = argv;
@@ -88,6 +95,12 @@ const kindsOf = (value) => str(value)
     ?.split(',')
     .map((kind) => kind.trim())
     .filter(Boolean);
+/**
+ * The drill-down handle a hit carries: `T9 · E221` reads straight into
+ * `1session turn <id> 9 --event 221`. Turn first, because that is the order
+ * the command wants it in.
+ */
+const handle = (turn, event) => `T${turn || '?'} · E${event}`;
 const focusOf = (value) => {
     const focus = str(value);
     return focus === 'marketing' || focus === 'full' ? focus : 'review';
@@ -266,17 +279,24 @@ async function main() {
         }
         case 'turn': {
             const session = await load(positional[0]);
-            const eventIndex = num(flags.event);
-            if (eventIndex !== undefined) {
-                const detail = await eventDetail(session, eventIndex);
-                const body = detail.fullText ?? detail.text ?? detail.toolResult ?? '';
-                print(json, detail, [
-                    `#${detail.index} ${detail.kind}${detail.toolName ? `(${detail.toolName})` : ''} ${detail.timestamp ?? ''}` +
-                        `${detail.truncated ? (detail.fullText ? '  [已从 steps/ 补全]' : '  [已截断]') : ''}`,
-                    ...(detail.toolArgs ? ['', '参数：', JSON.stringify(detail.toolArgs, null, 2)] : []),
-                    ...(body ? ['', '内容：', body] : []),
-                    ...(detail.truncationNote ? ['', `⚠️ ${detail.truncationNote}`] : []),
-                ].join('\n'));
+            const spec = str(flags.event);
+            if (spec !== undefined) {
+                const details = await eventDetails(session, spec);
+                // A bare index keeps returning one object; a range or a list — which
+                // the caller had to ask for explicitly — returns the array.
+                const single = /^\s*\d+\s*$/.test(spec);
+                print(json, single ? details[0] : details, details
+                    .map((detail) => {
+                    const body = detail.fullText ?? detail.text ?? detail.toolResult ?? '';
+                    return [
+                        `#${detail.index} ${detail.kind}${detail.toolName ? `(${detail.toolName})` : ''} ${detail.timestamp ?? ''}` +
+                            `${detail.truncated ? (detail.fullText ? '  [已从 steps/ 补全]' : '  [已截断]') : ''}`,
+                        ...(detail.toolArgs ? ['', '参数：', JSON.stringify(detail.toolArgs, null, 2)] : []),
+                        ...(body ? ['', '内容：', body] : []),
+                        ...(detail.truncationNote ? ['', `⚠️ ${detail.truncationNote}`] : []),
+                    ].join('\n');
+                })
+                    .join('\n\n────────\n\n'));
                 break;
             }
             const detail = turnDetail(session, num(positional[1]) ?? 1);
@@ -292,13 +312,15 @@ async function main() {
                     return `${head}  ${oneLine(event.text ?? event.toolResult ?? JSON.stringify(event.toolArgs), 160)}`;
                 }),
                 '',
-                `（用 --event <k> 展开单个事件的完整内容）`,
+                `（--event <k> 展开单个事件的完整内容；--event ${detail.summary.events[0]}-` +
+                    `${Math.min(detail.summary.events[0] + 2, detail.summary.events[1])} 或 --event a,b,c 一次读相邻几条）`,
             ].join('\n'));
             break;
         }
         case 'search': {
             const query = positional.join(' ');
-            const hits = await searchSessions(query, {
+            const includeSelf = flags['include-self'] === true;
+            const found = await searchSessions(query, {
                 workspace: scopeWorkspace(flags),
                 since: str(flags.since),
                 limit: num(flags.limit),
@@ -310,22 +332,42 @@ async function main() {
                 maxPerSession: num(flags['max-hits']),
                 useIndex,
             });
+            // The searcher's own live transcript is noise by default: the query is
+            // in it because this very command put it there.
+            const hits = includeSelf ? found : found.filter((hit) => !hit.self);
             const total = hits.reduce((sum, hit) => sum + hit.totalMatches, 0);
+            const foldedSessions = found.length - hits.length;
+            const foldedMatches = found.reduce((sum, hit) => sum + (hit.suppressed ?? 0) + (hits.includes(hit) ? 0 : hit.totalMatches), 0);
+            const foldNote = !includeSelf && foldedMatches
+                ? `（已折叠 ${foldedMatches} 处本次检索自身留下的回声` +
+                    `${foldedSessions ? `，涉及 ${foldedSessions} 个会话` : ''}；--include-self 展开）`
+                : undefined;
             print(json, hits, hits.length
                 ? [
                     `${total} 处命中，分布在 ${hits.length} 个会话`,
+                    ...(foldNote ? [foldNote] : []),
                     ...hits.flatMap((hit) => [
                         '',
                         `### ${hit.session.provider} ${hit.session.id.slice(0, 8)}  ` +
                             `${hit.session.createdAt ?? '?'} → ${hit.session.updatedAt ?? '?'}  (${hit.totalMatches} 命中)`,
                         `    ${oneLine(hit.session.title, 80)}`,
-                        ...hit.matches.map((match) => `  #${match.index} ${match.kind}${match.toolName ? `(${match.toolName})` : ''}  ${match.excerpt}`),
+                        ...hit.matches.map((match) => `  ${handle(match.turn, match.index)} ` +
+                            `${match.kind}${match.toolName ? `(${match.toolName})` : ''}  ${match.excerpt}`),
+                        ...(hit.matches[0]
+                            ? [
+                                `    ↳ 1session turn ${hit.session.id.slice(0, 8)} ` +
+                                    `${hit.matches[0].turn || '<轮次>'} --event ${hit.matches[0].index}`,
+                            ]
+                            : []),
                         ...(hit.totalMatches > hit.matches.length
                             ? [`  …另有 ${hit.totalMatches - hit.matches.length} 处（--max-hits 调大或 --json 查看全部）`]
                             : []),
+                        ...(!includeSelf && hit.suppressed
+                            ? [`  …另折叠 ${hit.suppressed} 处本次检索自身的回声（--include-self 展开）`]
+                            : []),
                     ]),
                 ].join('\n')
-                : `无命中：${query}`);
+                : [`无命中：${query}`, ...(foldNote ? [foldNote] : [])].join('\n'));
             break;
         }
         case 'index': {
@@ -423,6 +465,19 @@ async function main() {
                 : `${row.id} 尚无关系边（没有任何会话通过 1session 查过它，它也没查过别人）`);
             break;
         }
+        case 'serve': {
+            const { serve, DEFAULT_PORT } = await import('../src/serve/http.js');
+            await serve({
+                port: num(flags.port) ?? DEFAULT_PORT,
+                ...(str(flags.host) ? { host: str(flags.host) } : {}),
+                ...(str(flags.token) ? { token: str(flags.token) } : {}),
+                ...(str(flags['base-url']) ? { baseUrl: str(flags['base-url']) } : {}),
+                ...(flags['no-report'] === true ? { report: false } : {}),
+            });
+            // The server owns the process from here; nothing after this resolves.
+            await new Promise(() => { });
+            break;
+        }
         case 'skill': {
             const { describeState, installSkill, skillStatus, uninstallSkill, bundledSkillDir, } = await import('../src/skill.js');
             const agents = str(flags.agent)

package/dist/src/index.d.ts

@@ -4,9 +4,9 @@ export { distillSession, editedFiles, shellCommand } from './distiller.js';
 export { buildOverview } from './overview.js';
 export { classifyUserTurn } from './classify.js';
 export { commandLedger, displayPath, errorLedger, fileLedger, jobCounts, jobLedger, } from './ledger.js';
-export { eventDetail, summarizeTurns, turnDetail, type EventDetail } from './turns.js';
+export { eventDetail, eventDetails, parseEventSpec, summarizeTurns, turnDetail, turnNoAt, turnStarts, turnStartsFrom, type EventDetail, } from './turns.js';
 export { analyzableCommand, fileWrites, rawCommand, stripHeredocs, resolveWritePath, type FileWrite, } from './writes.js';
-export { mandatoryLiteral, planQuery, searchSessions, type QueryPlan, type SearchHit, type SearchMatch, type SearchOptions, } from './search.js';
+export { echoFolder, isCallerSession, mandatoryLiteral, planQuery, searchSessions, type Candidate, type QueryPlan, type SearchHit, type SearchMatch, type SearchOptions, } from './search.js';
 export { aggregateWorkspaceSessions, type AggregateOptions } from './aggregator.js';
 export type { ProviderAdapter, SessionCandidate } from './parsers/provider.js';
 export { canonicalizePath, isInside, slugifyWorkspace } from './util/paths.js';
@@ -18,3 +18,5 @@ export { captureRuntimeEdge, deriveEdges, edgeEvidence, edgesOf, invocationsOf,
 export { deriveFacts } from './store/facts.js';
 export { EDGE_VERSION, EXTRACTOR_VERSION, PARSER_VERSION, SCHEMA_VERSION, } from './store/schema.js';
 export { SKILL_NAME, agentTargets, bundledSkillDir, describeState, installSkill, skillStatus, uninstallSkill, type AgentStatus, type AgentTarget, type EntryState, type InstallMode, type InstallOptions, type InstallResult, type SkillAgent, type UninstallResult, } from './skill.js';
+export { buildManifest, nodeIdentity, sessionUri, SESSION_CAPABILITIES, type AccessDescriptor, type NetworkService, type NodeManifest, } from './serve/node.js';
+export { createServer, serve, type ServeOptions } from './serve/http.js';

package/dist/src/index.js

@@ -3,9 +3,9 @@ export { distillSession, editedFiles, shellCommand } from './distiller.js';
 export { buildOverview } from './overview.js';
 export { classifyUserTurn } from './classify.js';
 export { commandLedger, displayPath, errorLedger, fileLedger, jobCounts, jobLedger, } from './ledger.js';
-export { eventDetail, summarizeTurns, turnDetail } from './turns.js';
+export { eventDetail, eventDetails, parseEventSpec, summarizeTurns, turnDetail, turnNoAt, turnStarts, turnStartsFrom, } from './turns.js';
 export { analyzableCommand, fileWrites, rawCommand, stripHeredocs, resolveWritePath, } from './writes.js';
-export { mandatoryLiteral, planQuery, searchSessions, } from './search.js';
+export { echoFolder, isCallerSession, mandatoryLiteral, planQuery, searchSessions, } from './search.js';
 export { aggregateWorkspaceSessions } from './aggregator.js';
 export { canonicalizePath, isInside, slugifyWorkspace } from './util/paths.js';
 export { defaultDbPath, openStore, resetStoreCache } from './store/db.js';
@@ -16,3 +16,5 @@ export { captureRuntimeEdge, deriveEdges, edgeEvidence, edgesOf, invocationsOf,
 export { deriveFacts } from './store/facts.js';
 export { EDGE_VERSION, EXTRACTOR_VERSION, PARSER_VERSION, SCHEMA_VERSION, } from './store/schema.js';
 export { SKILL_NAME, agentTargets, bundledSkillDir, describeState, installSkill, skillStatus, uninstallSkill, } from './skill.js';
+export { buildManifest, nodeIdentity, sessionUri, SESSION_CAPABILITIES, } from './serve/node.js';
+export { createServer, serve } from './serve/http.js';

package/dist/src/ledger.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { isInside } from './util/paths.js';
 import { oneLine } from './util/text.js';
 import { analyzableCommand, fileWrites, rawCommand, resolveWritePath } from './writes.js';
-import { summarizeTurns } from './turns.js';
+import { turnNoAt, turnStarts } from './turns.js';
 const SSH_HOST = /\b[\w.-]+@((?:\d{1,3}(?:\.\d{1,3}){3})|(?:[\w-]+(?:\.[\w-]+)+))/;
 const BACKGROUND = /\b(?:nohup|setsid|start_new_session\s*=\s*True|subprocess\.Popen|Popen\(|queue-[\w-]+\.py)\b/;
 const LOG_PATH = /([\w./-]+\.log)\b/;
@@ -11,11 +11,8 @@ const LOG_FILE = /(?:\.log|\.download\.log)$|progress\.jsonl?$/i;
 const TEMP_DIR = /^\/(?:private\/)?(?:tmp|var\/folders)\//;
 /** Maps each event index to the turn it belongs to. */
 function turnOf(session) {
-    const ranges = summarizeTurns(session).map((turn) => turn.events);
-    return (index) => {
-        const found = ranges.findIndex(([start, end]) => index >= start && index <= end);
-        return found === -1 ? 0 : found + 1;
-    };
+    const starts = turnStarts(session);
+    return (index) => (index < 0 ? 0 : turnNoAt(starts, index));
 }
 /**
  * Every shell command with whatever is known about how it went. Codex records

package/dist/src/search.d.ts

@@ -12,9 +12,20 @@ export interface SearchOptions extends ListOptions {
     context?: number;
     /** Matches recorded per session before scanning moves on. */
     maxPerSession?: number;
+    /**
+     * The session doing the searching, so its own live transcript can be marked.
+     * Defaults to `SESSION_READER_CALLER_SESSION`; pass `''` to disable.
+     */
+    selfSessionId?: string;
 }
 export interface SearchMatch {
     index: number;
+    /**
+     * The turn this event belongs to — the other half of the drill-down handle,
+     * so `T<turn> · E<index>` maps straight onto `turn <id> <turn> --event <index>`.
+     * 0 when the session records no turn that contains the event.
+     */
+    turn: number;
     kind: TurnKind;
     toolName?: string;
     timestamp?: string;
@@ -24,6 +35,14 @@ export interface SearchHit {
     session: SessionRef;
     matches: SearchMatch[];
     totalMatches: number;
+    /** Matches dropped because they were this very search echoing back. */
+    suppressed?: number;
+    /**
+     * The searcher's own session: either the injected caller id, or a session
+     * whose every match was the running invocation. Never removed from the
+     * result — callers hide it, so the count stays reportable.
+     */
+    self?: boolean;
 }
 /**
  * A substring that every string matching `source` must contain, or `undefined`
@@ -49,6 +68,35 @@ export interface QueryPlan {
  * either way.
  */
 export declare function planQuery(query: string, options?: SearchOptions): QueryPlan;
+export interface Candidate {
+    index: number;
+    kind: TurnKind;
+    toolName?: string;
+    timestamp?: string;
+    body: string;
+}
+/**
+ * Folds the Read Plane's own footprint out of one session: an invocation
+ * running right now, and the result carrying what it printed.
+ *
+ * It deliberately does not require the invocation to carry *this* query. A
+ * `1session` call from a minute ago prints other sessions' content verbatim,
+ * so it matches queries it never mentioned — and whatever it echoed is still
+ * in the session it was quoting from, where the search finds it properly, with
+ * a handle that drills down to the real thing instead of to a screenful of
+ * this tool's output.
+ *
+ * Stateful because the second half is only knowable from the first, so it is
+ * built fresh per session and fed events in index order — which both search
+ * paths already produce.
+ */
+export declare function echoFolder(now: number): (candidate: Candidate) => boolean;
+/**
+ * Whether a session is the one running the search. Accepts the canonical
+ * `provider:native_id`, the bare native id, or a 6+ character prefix of it —
+ * the same spellings `resolveSession` takes.
+ */
+export declare function isCallerSession(ref: SessionRef, callerId: string | undefined): boolean;
 /**
  * Full-text search across sessions.
  *