v0.2.0

v0.2.0 — A rewind now moves both halves to the same moment

Fixed

On 0.1.1 the control under a turn's answer restored the files to before that turn
while the fork kept that turn — so a transcript could end at "the file now contains
v3" with v1 on disk. The conversation went on describing work the workspace no longer
held.

sessions.fork({atSeq}) does not cut at its anchor. It takes the first turn/end
at or after it and keeps that whole turn — the convention the harness's own
per-message fork button relies on, where a message seq means "keep the turn this
message belongs to". This plugin passed a seq one event before the turn opened, which
the host rounds forward onto that same turn's end.

A point now anchors on the message that closed the previous turn. Restoring the
point for turn N hands back the workspace as turn N-1 left it, and the fork ends at
turn N-1: both halves describe the same moment.

The command path had a second fork implementation that disagreed with the host by the
same rule. Both paths now apply the host's, located by index rather than by treating a
seq as an offset — chunk events do not survive into the persisted log, so seq is sparse
on a resumed session.

Changed

• The first turn of a session no longer offers a rewind control. There is no
  completed turn for a fork to keep. An omitted atSeq is refused rather than passed
  along, because the host reads it as the last completed turn — the newest state, the
  opposite of a rewind.
• RewindPoint.boundary is now optional and names a seq inside the turn a fork
  keeps. It is reachable through the exported FilesnapProjection, which is why this
  is a minor rather than a patch.
• Projection stateVersion 2 → 3; cached folds are discarded and refolded.

Added

• A Chinese README.
• A section on the filesnap engine,
  with measurements, and on using it from an agent that is not this one.
• Credit to codex-rewind, where
  this design was worked out first.

Upgrading

Forks made by 0.1.1 are not repaired by upgrading. A child session created then
still holds the turn whose writes were reverted; the files in it are correct for the
point that was restored, and the last turn of its transcript is not.

---

修复

0.1.1 上,一轮回答下面的那个控件会把文件还原到这一轮之前,而 fork 却保留了这一
轮 —— 于是 transcript 停在"文件现在是 v3",磁盘上却是 v1。对话继续描述着工作区已经
不再持有的工作。

sessions.fork({atSeq}) 并不在锚点处切断。它取第一个位于锚点或其之后的 turn/end
并保留那一整轮 —— 这正是 harness 自己那个每条消息旁的 fork 按钮所依赖的约定:传一条消息
的 seq,意思是"保留这条消息所属的那一轮"。而本插件传的是这一轮开始前一格的 seq,被
host 向后对齐到了这一轮自己的结尾。

现在点锚在上一轮的收尾消息上。恢复第 N 轮的点 = 把工作区交还成第 N-1 轮结束时的样
子,fork 也停在第 N-1 轮:两半描述同一个时刻。

命令路径上还有第二套 fork 实现,按同一条规则和 host 不一致。现在两条路径都用 host 的规
则,并且用下标查找而不是把 seq 当偏移量 —— chunk 事件不会进入持久化日志,所以在 resume
出来的会话上 seq 是稀疏的。

变更

• 会话的第 1 轮不再提供回退控件。 它前面没有可供 fork 保留的完整轮次。省略 atSeq
  会被拒绝而不是照传,因为 host 会把它读成最后一个完成的轮次 —— 最新状态,和回退恰好
  相反。
• RewindPoint.boundary 改为可选,含义是 fork 所保留的那一轮之内的一个 seq。它经由
  导出的 FilesnapProjection 对外可见,所以这是 minor 而不是 patch。
• Projection stateVersion 2 → 3;缓存的折叠结果会被丢弃并重算。

新增

• 中文 README。
• 关于 filesnap 引擎的章节(带实测数
  据),以及如何在别的 agent 上使用它。
• 致谢 codex-rewind —— 这套设计最
  先是在那里做通的。

升级说明

0.1.1 期间产生的 fork 不会因为升级而被修复。 那时创建的子会话里,仍然保留着那一轮
被回退掉的写入;它里面的文件对于被恢复的那个点是正确的,而 transcript 的最后一轮不是。
Full Changelog: v0.1.1...v0.2.0