第三部已经把 runAgentLoop() 内的两层循环、消息队列、工具批次与停止条件讲完。只读这层会留下一个实际问题：循环返回的消息由谁保存，运行中切换模型何时生效，回到旧分支后模型又从哪条路径继续？

Pi 在 packages/agent 中保留了两个答案。稳定的 Agent 是带实时状态的 loop wrapper，pi-coding-agent 再用 AgentSession 给它接上产品级持久化、扩展、自动压缩与 I/O。与此同时，package 里新增了独立的 AgentHarness：它不包 Agent，而是直接驱动同一个 loop，并尝试把 Session、资源、Hook、保存点和结构操作收进一套更适合嵌入的 API。

本部不把这两条路径揉成一套“Pi 最终架构”。它们共享底层 loop 与消息类型，但高层 state owner 不同。第 19 章先把并列调用关系钉住，后五章才集中阅读 Harness，因为这里的 Session 接口更小，状态边界也更容易逐项验证。

六章按哪条线读

第 19 章从两个直接 call site 开始。Agent 自己还原 AgentState；AgentHarness 自己处理 Session append、Hook、phase 与 pending write。随后回到 pi-coding-agent 的 SDK factory，确认稳定 CLI 用的是前者加 AgentSession。这一步用来防止后面每一个 Harness 结论被误写成当前 CLI 已迁移行为。

第 20 章处理运行中配置。Harness 不让一个长 run 从头到尾只用一份配置，也不让 setter 修改正在飞行的 provider request。它在 prompt 开始构造 turn state；assistant response 与完整工具批次结束后，先到保存点，再构造下一份 state。一个 run 因此可以依次使用多份快照。

第 21 章把“修改已经生效”拆成 runtime getter、当前 request、下一 request 和 Session entry 四个观察面。model、thinking level、active tools 在 active phase 会先进入 pending queue，同时更新 Harness 最新字段；保存点按接收顺序写入 Session。resources 与 stream options 则只存在进程内。Hook 抛错也不会回滚已成功提交的 entry。

第 22 章进入 Session 数据模型。backend 保存 append log，parentId 形成树，leaf entry 持久记录 pointer 移动。全量 entries、active branch、context entries 和最终 AgentMessage projection 是四种不同读取。普通 custom entry 默认不会进入模型上下文，必须由 projector 显式转换。

第 23 章比较两个结构操作。compaction 在当前 branch 尾部追加摘要屏障，旧 entries 仍然保留；navigation 移动 active leaf，可把离开的分支压成一条 branch summary 接到新路径。两者都要求 Harness idle，但 navigation 的 leaf move 与 summary append 是两次写入，不能宣称全有或全无。

第 24 章最后做 crash audit。JSONL 与 SQLite 都能重开 Session tree；SQLite 还能让单次 entry 及其 materialized index 在事务内一致。当前 AgentHarness 的 phase、queue、pending write、provider attempt 和 tool-start intent 没有进入 storage。重开会话不会自动续跑未完成 operation，harness-v2.md 提出的 lane 与 operation log 仍是设计目标。

flowchart TB
  accTitle: 第四部状态与所有权地图
  accDescr: Agent 和 AgentHarness 并列调用低层循环；Harness 使用快照与保存点，把完成内容写入 Session tree；context projection、compaction 和 navigation 决定模型看到的路径；storage 不保存未完成运行。
  LOOP["runAgentLoop"]
  AGENT["Agent\nAgentState owner"] --> LOOP
  HARNESS["AgentHarness\noperation owner"] --> LOOP
  HARNESS --> SNAP["turn snapshot\ncurrent request"]
  HARNESS --> SAVE["save point\npending write order"]
  SAVE --> TREE["Session tree\nentries + parentId + leaf"]
  TREE --> VIEW["buildContext\nactive path projection"]
  TREE --> STRUCT["compaction / navigation"]
  TREE --> STORE["memory / JSONL / SQLite"]
  STORE -.-> GAP["no durable run intent\nno tool recovery record"]
  PRODUCT["pi-coding-agent\nAgentSession"] --> AGENT

图中的 STORE -.-> GAP 是本版的明确缺口，不是说 Session 没有持久价值。对话 entry、分支、leaf、摘要和部分配置都可以跨进程恢复。缺的是“这条 prompt 是否已经被接受为一个 operation、provider 请求走到哪一步、工具副作用能否安全重放”这一层 orchestration receipt。

读源码时坚持三个词

这一部会反复使用 run、turn 和 entry，三者不能互换。

run 从一次 prompt() 开始，可能经过多次 provider request、工具调用、steering 和 follow-up，直到 Harness 回到 idle。turn 是低层 loop 的一段 assistant response 加完整工具批次，结束时触发 turn_end 和保存点刷新。entry 是 Session tree 中一次成功追加的事实；它可能是消息，也可能是配置、摘要或 leaf 移动。

同样要区分 snapshot 与 durable state。turn state 是为了让一条 provider request 使用稳定输入；它不是 UI snapshot，也不自动落盘。Session entry 才经过 storage。save_point 事件说明 pending writes 已在当前流程里 flush，并不承诺 fsync、跨工具事务或 crash resume。

本部实验的边界

实验都锁定 v0.83.0 / 845d6ff1f6643aba440341cce877ce1c43ebbc39。Harness 的核心测试使用 faux provider，不需要真实 API key，适合验证模型切换时序、pending write 排序、compaction projection 与 JSONL reopen。它们不能证明真实 provider 的网络恢复，也不能证明 bash、HTTP 或文件工具具有幂等副作用。

固定证据 checkout 只读，只用于 git show、路径和行号核验，不在其中安装依赖、生成 model data 或运行会写入构建产物的命令。这个 tag 还有一个不显眼的发布前提：provider catalog JSON 所在的 packages/ai/src/providers/data/ 被 .gitignore 排除，普通 git checkout 与普通 git archive <commit> 都没有这些文件。直接从这种副本导入 AgentHarness 测试，会在 suite 加载阶段报缺少 amazon-bedrock.json，实际执行数是 0。

本部所有可执行实验统一使用 v0.83.0 官方 release source archive。发布脚本会把被忽略的 provider data 加入临时 git tree，release workflow 又从该 archive 离线构建 binaries，因此不需要在复现当天重新访问可变模型目录。固定制品为 https://github.com/earendil-works/pi/releases/download/v0.83.0/pi-0.83.0-source.tar.gz，SHA256 为 f225b87ec3b4825dd5b94e922a8629558addca31a1b4d2c206ae598a8e2692c0。

进入本部前至少先核对源码身份：

repo="${PI_SOURCE_DIR:-/tmp/pi-handbook-qbQTcA}"

test "$(git -C "$repo" rev-parse HEAD)" = \
  845d6ff1f6643aba440341cce877ce1c43ebbc39
test "$(git -C "$repo" describe --tags --exact-match HEAD)" = v0.83.0
test -z "$(git -C "$repo" status --porcelain)"

随后为可执行实验准备一次性 release tree。哈希不匹配就立即停止；安装和测试都发生在解压目录，不会改动上面的证据 checkout：

work="$(mktemp -d)"
archive="${PI_RELEASE_ARCHIVE:-$work/pi-0.83.0-source.tar.gz}"
url="https://github.com/earendil-works/pi/releases/download/v0.83.0/pi-0.83.0-source.tar.gz"
expected="f225b87ec3b4825dd5b94e922a8629558addca31a1b4d2c206ae598a8e2692c0"

test -f "$archive" || curl -fL "$url" -o "$archive"
if command -v sha256sum >/dev/null 2>&1; then
  actual="$(sha256sum "$archive" | awk '{print $1}')"
else
  actual="$(shasum -a 256 "$archive" | awk '{print $1}')"
fi
test "$actual" = "$expected"

tar -xzf "$archive" -C "$work"
export PI_RELEASE_WORKDIR="$work"
export PI_RELEASE_SOURCE_DIR="$work/pi-0.83.0"
test -f "$PI_RELEASE_SOURCE_DIR/packages/ai/src/providers/data/.manifest.json"
(cd "$PI_RELEASE_SOURCE_DIR" && npm ci --ignore-scripts --no-audit --no-fund)

第 20、21、23 章的命令都只读取 PI_RELEASE_SOURCE_DIR。实验结束后删除 PI_RELEASE_WORKDIR 即可；不要把其中生成的 node_modules、coverage 或缓存当作源码证据。

最后一章会把当前实现与 Harness v2 design 放在同一张差异表里，但只把 src、schema 和可执行测试当作 shipped evidence。设计文档负责说明方向，不负责替实现背书。完成这层校准后，第五部再回到稳定 Coding Agent 的 AgentSession，看产品控制面如何补上 Harness 之外的自动压缩、重试、扩展与会话切换。