@epoch-agent/core 0.13.0 → 0.15.0

package/README.md

@@ -373,6 +373,42 @@ artifacts 的 512MB 从此**出自同一张表**。在这之前两个数字各
   （FTS5 自带的 `automerge` 已经在做增量合并那一半），今天唯一的调用方是
   `epoch doctor --reclaim`。它是这个目录里唯一会**写**的诊断函数
 
+## 搬一整段会话进来：`SessionManager.importSession()`（2026-09-20）
+
+给「一个账号多台机器」那类同步 / 迁移用的**写库口**。核心一句：**搬运不是重放**，
+它和 `create()` 是两件事。
+
+- **不跑智能体、不切当前会话、不发任何事件**；导进来的会话也**不算「本进程碰过」**
+  （不进 `touched`），所以进程退出时不会被 `endTouchedSessions()` 盖上一个假的结束标记
+- **id 和每条消息的 `timestamp` 由调用方给**，库不拿挂钟顶替
+- **撞 id 就拒**（`{ ok: false, reason: 'exists' }`），不合并也不覆盖。
+  两边都是用户的数据，这一层没有判断谁该赢的依据
+- 整段会话 + 全部消息**一个事务**；消息 id **一定重发**（`messages.id` 是全库
+  一条序列，跨机必撞），回执里 `idMap` 把来源的号接到本机的号上
+
+四条改之前必须知道的：
+
+- ⚠️ **部件走 `importParts()`，不是 `persistParts()`。** 这两个在图片那一支上是
+  **互逆**的：`restoreParts(parts, { inlineImages: false })` 吐的是**绝对路径**，
+  而 `persistParts()` 见到一个不带 `https?:` 的字符串就当它是 **base64**。
+  两边都是 `string`，接错了编译得过、跑得通，只是把一串路径当乱码解出几十个字节
+  写成一张坏图。`importParts()` 反过来：绝对路径原样收，base64 **当场拒**
+  （`detail: 'image:base64'`）而不是替调用方落盘 —— 事务回滚的话那些文件会成孤儿，
+  而形状错在上游就该在上游红
+- ⚠️ **落库的 `meta` 里计数列一律 0**，不是保守是必须：`insertMessage` 每条都会把
+  `message_count` / `tool_call_count` 推一格，先填好再插就是记两遍
+- **两样有意没搬**：`estimatedCostUsd`（`priced_call_count` 分得出「0 块钱」和
+  「不知道」，抄一个数过来会把后者变成前者）和压缩状态（`insertMessage` 把
+  `active=1, compacted=0, observed=0` 写死）
+- **本机没有那个 `parentId` 时静默丢掉**（回执里 `droppedParentId` 如实报），
+  因为 `parent_id` 是**真外键**，留着悬空引用插不进去 —— 而一段会话不该因为
+  它的来源分支没同步过来就整个进不了库
+
+配套的两样在 `listSessions` 上：**`archived` 从二态变三态**（`undefined`/`false` =
+只列没归档的，`true` = 只列归档的，`'any'` = 两边都列 —— `'any'` 之前「两边都要」
+这句话没有任何写法能表达），以及 `updatedSince`（最后活动**严格晚于**它的；
+比的是 `COALESCE(updated_at, started_at)`，和读侧 `rowToMeta` 那个 `??` 同一个口径）。
+
 ## 强制 JSON：`responseFormat` + 一格能拿去做分支的布尔（2026-08-20，方案 59 PR-1）
 
 `GenerateInput` 上多了两格可选：`responseFormat`