【pi-mono 源码解析 3/4】幽灵边：pi-mono forkFrom() 揭示的 Lying Sentinel 与 TypeScript 的表达空白

导读#

一个版本号为 3 的文件，可以合法地包含版本 1 格式的数据体。这不是偶然——是 pi-mono 的分支创建路径在写文件时主动写入了这个矛盾。

本文是 pi-mono 源码解析系列第三篇，也是收尾篇。三篇文章的递进是有意设计的：

• 第一篇：运行时行为——agent loop 里隐藏的控制流与静默截断
• 第二篇：类型系统——类型层表达了哪些，遗漏了哪些
• 第三篇：设计哲学——框架对隐式约定、隐式 LLM 成本，持什么态度

读完本篇，你将理解：

1. forkFrom() 如何在磁盘上制造一个格式矛盾的 session 文件
2. 为什么四个函数都"正确执行"，却依次传递了一条损坏的数据
3. TypeScript 类型系统有能力表达这些层间合同，但 pi-mono 选择了不表达
4. 这个选择在 LLM 框架领域是普遍现象，而且有结构性原因

前置篇目：建议先读第一篇（agent loop 与 compaction）和第二篇（Tool Call Atomicity 与 Parse-Don't-Validate）。

涉及文件清单：

现象：forkFrom() 的精确 bug 形态#

执行链#

forkFrom() 是 pi-mono 的分支创建入口。当用户执行 pi-mono --fork <source> 时，session-manager.ts:1444 开始执行：

// session-manager.ts:1444-1494（简化，保留关键步骤）
async forkFrom(sourcePath: string): Promise<SessionManager> {
    // 步骤 1：读取 source 文件的所有 entries，无迁移
    const sourceEntries = loadEntriesFromFile(sourcePath);   // ~1452

    // 步骤 2：写新文件 header，硬编码 v3
    // ~1477-1484
    const header = {
        version: CURRENT_SESSION_VERSION,   // = 3
        // ...其他元数据
    };
    fs.writeFileSync(newPath, JSON.stringify(header) + "\n");

    // 步骤 3：逐条写入 source entries，原样，无格式转换
    for (const entry of sourceEntries) {
        fs.appendFileSync(newPath, JSON.stringify(entry) + "\n");  // ~1488-1491
    }

    // 步骤 4：用新路径创建 SessionManager
    return new SessionManager(newPath);   // ~1494
    // └─ migrateToCurrentVersion()
    //      └─ header.version === 3 → SKIP
}

结果：磁盘上出现一个文件，header 宣称 version: 3，body 里的每一条 entry 都是 v1 格式（缺失 id/parentId 字段）。

这是主动写入矛盾，不是被动遗忘#

关键区别：

• 被动遗忘：forkFrom() 忘了调用 migrateToCurrentVersion()，导致文件留在 v1
• 主动写入矛盾：forkFrom() 主动写了 version: 3 的 header，然后把 v1 body 贴上去

后者的危害更隐蔽。migrateToCurrentVersion()（session-manager.ts:276）不是没被调用——它被调用了，并且"正确地"判断"这是 v3，不需要迁移"，然后放行。没有任何环节出错，但文件已经损坏。

这就是 Lying Sentinel：一个被系统信任的标记字段，携带了与实际数据格式不符的声明。它的危险不在于"值是错的"，而在于系统信任它的方式——migrateToCurrentVersion() 把 header.version 当作 Oracle，不做结构验证，直接放行。

触发条件与磁盘持久性#

触发条件：forkFrom() 的 sourcePath 指向一个未经 open() 迁移的 v1 session 文件。

main.ts:163-164 里，resolveSessionPath() 有一条直通路径：

if (hasPathChars(arg) || arg.endsWith(".jsonl")) {
    return { type: "path", path: arg };  // 直接返回，完全绕过 open()
}

用户执行 pi-mono --fork /path/to/old-v1-session.jsonl，这个路径原样传给 forkFrom()，没有经过任何迁移。这三条生产调用路径（--fork <file>、--fork <session-id>、cross-project fork）都有可能携带 v1 文件。

更严重的是：这是磁盘持久化的损坏，没有自愈路径。 之后每次 open() 这个腐败文件：

open(腐败文件) → migrateToCurrentVersion()
  └─ header.version (3) >= CURRENT (3) → return false（跳过）
  └─ _rewriteFile()  ← 把 v3 header + v1 body 原样写回磁盘

_rewriteFile() 每次把同样的腐败数据固化一遍。进程重启不修复它，没有任何后台机制会清理它。

根因：版本信息的类型擦除#

SessionTreeEntry 不携带版本信息#

harness/types.ts:409：

type SessionTreeEntry =
    | MessageEntry
    | CompactionEntry
    | ToolCallEntry
    | ToolResultEntry
    | SystemEntry
    | AssistantEntry
    | UserEntry
    | BranchSummaryEntry
    | StartEntry
    | ForkEntry
    | ErrorEntry;
    // 11 个变体，无版本类型参数

类型系统完全不知道"这是 v1 格式的 entry 还是 v3 格式的 entry"。编译器无法阻止你把 v1 的 SessionTreeEntry[] 原样写进声称是 v3 的文件。

如果版本信息在类型层表达：

// 如果这样设计
type SessionTreeEntry<V extends 1 | 3> =
    V extends 1 ? LegacyMessageEntry : MessageEntry | CompactionEntry | ...;

// forkFrom() 的签名就必须变成：
async forkFrom(sourcePath: string): Promise<Session<3>>
// 内部不得不做类型转换，编译器在写盘前就拦截了

这和第二篇的结构完全对称：MessageEntry.message: AgentMessage 不携带 role 信息，导致 findValidCutPoints() 必须运行时过滤；这里 SessionTreeEntry 不携带版本信息，导致 forkFrom() 可以合法制造版本矛盾。类型系统在 parse 边界吞掉了关键分类信息，下游每次使用都要重新推断或静默出错。

parentId 的 null 语义双关#

parentId: string | null 的 null 有两种含义：

1. 根节点：这条 entry 是 session 树的根，没有父节点（正常）
2. orphaned entry：v1 格式 entry 没有 parentId 字段，TypeScript 读到 undefined，与 null 在后续处理中等价（异常）

getPathToRoot()（jsonl-storage.ts:275）看到 null 就 break，无法区分"正常到根"和"遇到了格式不兼容的条目"。

静默传播链#

四步执行，无一报错。

Layer 2: forkFrom()                          session-manager.ts:1444
         └─ 制造 v3 header + v1 body，写入磁盘，"成功返回"

Layer 1: getPathToRoot()                     jsonl-storage.ts:275
         └─ v1 entry → current.parentId === undefined → break
         └─ 路径在第一条 entry 处截断，无异常抛出

Layer 1: collectEntriesForBranchSummary()    branch-summarization.ts:67
         └─ LCA（最近公共祖先）基于截断路径计算
         └─ 返回错误的共同历史区间，无异常

Layer 1: generateBranchSummary()             branch-summarization.ts:199
         └─ models.stream()  ← 真实 LLM API 调用
         └─ 输出格式完整，语义错误，无任何错误返回

这不是 Failure Cascade。Failure Cascade 是"A 出错 → 错误信号传播 → B 出错"，可以在任意节点拦截。这条链是 Silent Corruption Cascade：

• forkFrom()（session-manager.ts:1444）制造了矛盾，但它"成功了"
• getPathToRoot()（jsonl-storage.ts:275）正确地处理了 parentId === undefined 的情况——break 是它的合法行为
• collectEntriesForBranchSummary()（branch-summarization.ts:67）拿到截断路径，正确地计算了 LCA——只是输入错了
• generateBranchSummary()（branch-summarization.ts:199）发出了一次真实的 LLM API 调用，得到了格式完整的摘要

没有一层应该被单独指责。每一层都做了"正确"的事，整条链基于一个在创建时就被污染的不变量：header.version === body entry format version。这个不变量从来没有在任何地方被显式声明，也从来没有在任何地方被验证。

最终代价：用户在 fork session 之后切换分支，generateBranchSummary()（branch-summarization.ts:199）悄悄产生了一次 LLM API 调用，花了时间和 token，生成的摘要基于错误的对话历史。用户看到的摘要格式正确，内容混乱，没有任何错误提示指向 forkFrom() 在创建文件时埋下的问题。

外部参照：为什么行业选择了约定#

pi-mono 对这类问题的处理方式在 LLM 框架领域是普遍现象。

为什么 TypeScript/Python 框架都选择了隐式约定？因为 LLM API 变化太快。Anthropic 从文本补全 → 对话 → tool_use → extended thinking，每次变化都要更新框架。如果 header.version 的合同被表达为 V3SessionHeader 类型，v4 协议出来就要改所有接口签名。在协议不稳定期，隐式约定的迭代成本更低。

这是速度与正确性的 trade-off，不只是疏忽。

LangChain 0.1→0.2 的演化说明了这个选择的终局：在框架趋于稳定后，LangChain 把普遍存在的 Temporal Coupling 升格为系统性重构，用 Runnable 接口把时序约束从"文档里写着"变成"接口链里不可绕过"。这和下文提到的 MigratedSessionHandle 是同构方案。

LangChain 触发重构的原因是开发者体验摩擦——摩擦点是普遍的，所有链式调用都有顺序问题，所以有人问了"还有多少条类似的链"。pi-mono 的 bug 触发条件更苛刻（需要未经 open() 的 v1 文件），所以实际的修复压力倾向于局部：只修 forkFrom()，不引入 MigratedSessionHandle。

幽灵边的结构#

这条 Temporal Coupling 在依赖图上制造了一条幽灵边：

静态依赖图（package.json 可见）：
  pi-coding-agent (Layer 2) ──→ pi-agent-core (Layer 1)

运行时约束（不可见，约定层）：
  JsonlSessionStorage.open() 必须 AFTER SessionManager.open()
  即 Layer 1 的安全调用，隐式依赖 Layer 2 的先行执行

  pi-agent-core (Layer 1)  - - →  pi-coding-agent (Layer 2)
                              ↑ 反向幽灵边，只存在于运行时约定

JsonlSessionStorage（Layer 1）硬拒非 v3 文件（jsonl-storage.ts:68），把所有历史格式的处理责任全部推给 Layer 2 的 SessionManager——这是有意识的关注点分离：Layer 1 保持纯净，Layer 2 承担向后兼容的脏活。这个设计有一个优雅的出口：随着 v1 session 文件在用户机器上自然消亡，Layer 2 的迁移逻辑可以悄悄删掉，Layer 1 始终不需要改动。

问题是：这个"有意识的设计"把分层合同放在了类型之外。任何绕过幽灵边的代码路径，都能让整个假设在不知情的情况下崩溃——forkFrom() 就是那条绕路代码。

有意识的设计，遇上了无意识的绕路。

开放问题#

forkFrom() 修好之后（Option A：写盘前在内存迁移 source entries），这篇文章分析的直接 bug 消失了。

但幽灵边本身还在。SessionManager.open() 必须先于 JsonlSessionStorage.open() 的约定，仍然只存在于 JSDoc 和团队记忆里，没有进入任何类型签名。

下一条绕路代码——下一个 forkFrom()——会是哪个函数？

有两条路：

Option A 局部修复：修 forkFrom()，让它在写盘前迁移 source entries。快，有效，幽灵边留着。下一条绕路代码再次显形之前，这是够用的。

MigratedSessionHandle 系统性封闭：引入 token type，把时序约束从约定层升到类型层。需要改所有调用点，但幽灵边从此变成真实边，静态分析工具接管了人工记忆的职责。

interface MigratedSessionHandle {
    readonly _brand: unique symbol;
    path: string;
}

class SessionManager {
    async open(path: string): Promise<MigratedSessionHandle> { /* ... */ }
}

class JsonlSessionStorage {
    async open(handle: MigratedSessionHandle): Promise<void> { /* ... */ }
}

LangChain 在 0.1→0.2 时选择了系统性重构，触发点是开发者体验摩擦的普遍积累。pi-mono 现在的触发点是一个特定场景的 bug，修复压力倾向于局部。

pi-mono 框架稳定之后，隐式约定的维护成本何时会超过类型重构的成本？这是本系列读完之后，值得继续观察的问题。