Torn-tail repair fsyncs the destroy before the rebuild: a crash between the two steps loses the recovered records, and the only trace says "recovered"

[yamingmou]

EN / English

TL;DR. Torn-tail repair in @deepseek-ai/dsh-session-persistence-jsonl runs as two steps: persistContiguous first calls truncateTornTail (lib/index.js:229), which truncates the log to the last complete frame and fsyncs it; only then does it call persistBatch with the recovered records (:233). Both steps are durable writes, and both can fail or be interrupted — but by the time the second one starts, the first has already destroyed the only on-disk copy of the torn frame those records were decoded from. A process crash between the two fsyncs loses every complete record the recovery had salvaged, permanently and silently: the next open sees a clean prefix, sets no truncation point, triggers no repair, and leaves no trace that anything was discarded.

The rule this report stands on, stated once: the rebuild must be able to survive the destroy — never the other way round. The same package already follows this rule in its migration publish path (§4). I am not proposing a fix, a field, or a schedule; I am asking whether the durability this package promises for recovered records should also hold across a crash inside the repair itself.

1. The repair is two durable steps, destroy first

Reads of @deepseek-ai/dsh-session-persistence-jsonl@0.2.1-rc.5 (the next tag as of 2026-10-31; latest is 0.0.1-rc.1, alpha is 0.2.2-alpha.2). All line numbers below are from the published tarball's lib/index.js unless marked as master.

persistContiguous — the shared durable-append body — runs the repair in this order (:228-235):

if (this.state.tornTruncateTo !== void 0) {
    await this.storage.truncateTornTail(this.header, this.state.tornTruncateTo);   // :229  destroy
    this.state.tornTruncateTo = void 0;
}
if (this.state.recoveredTail !== void 0) {
    if (this.state.recoveredTail.length > 0) await this.storage.persistBatch(this.header, this.state.recoveredTail, ...);  // :233  rebuild
    this.state.recoveredTail = void 0;
}
await this.storage.persistBatch(this.header, batch, ...);                          // :236  the new append

Step one, truncateTornTail (:2938-2942), calls repair (:3337-3346), which is truncate(path, offset) followed by an r+ open, sync(), close(). The destroy is fsync'd — after :229 resolves, the torn bytes are gone from disk durably.

Step two, persistBatch with recoveredTail (:233), appends and fsyncs the salvaged records — after the bytes they were decoded from no longer exist.

Both tornTruncateTo and recoveredTail live only in the handle's in-memory state (:228, :232). Nothing about step two is journaled, staged, or recoverable across a process death. Master ce7073d51 carries the same order in packages/session/session-persistence-jsonl/src/storage.ts:328-337 — the window @PerryLink named in #6493.

2. What dies between the two steps

Before the repair runs, the torn final frame is still on disk, and every open re-decodes it: decodeStoredLog calls decompressZstdPrefix(buffer.subarray(tornStart)) (:3024) and returns the salvaged records in recoveredTail (:3036-3037). The recovery is repeatable — crash before :229, reopen, and the same records come back.

After :229 resolves, that is no longer true. The frame is gone; the records exist only in this handle's memory, awaiting a step that has not started. If the process dies before :233 fsyncs:

• the log on disk is a clean prefix — complete frames, no torn tail;
• the next open computes tornTruncateTo: undefined and recoveredTail: [] (:3017-3018), so no repair is triggered and nothing logs;
• the complete records the recovery had salvaged are not in the file and not recoverable from it — the only source bytes were the ones :229 truncated away.

These are not speculative bytes. The recovery path's own comment on master (src/index.ts:1047-1049) calls them what they are:

// A torn final frame's append never resolved, but complete JSONL records
// already flushed into it are real emitted events: recover them, and let
// the write path truncate the torn bytes and rewrite them durably.

And the package promises the rewrite in three places. README (README.md:77): "a write handle truncates the torn bytes and durably rewrites those recovered records before its first new batch." The state field's doc comment (master src/index.ts:128): "Complete events recovered from the torn final frame; the write path rewrites them durably." The comment above. What is lost in the crash window is exactly what these three texts promise to keep.

One boundary I want to be precise about, because it is the strongest counter-reading: the base package's invariant list (@deepseek-ai/dsh-session-persistence@0.2.1-rc.5, README.md:86) says "A torn physical tail never reaches a reader. It belongs to an append that never resolved; the write path truncates it durably before its first new append." That invariant governs the torn fragment — and the fragment is indeed discarded. It does not cover the complete records decoded out of the frame: those are promised a durable rewrite (:77), and the crash window is where that promise can break. The two are separate claims in the package's own texts, and only the first one is unconditional.

3. The one log line fires before the rebuild starts

The whole file has four runtime log statements (:423, :438, :2731, :2941). The torn-tail one (:2941) is inside truncateTornTail, after repair resolves:

this.ctx.logger.warn(`${this.name}: session "${header.id}" recovered from a torn tail; incomplete tail bytes were discarded`);

By control flow, this warn runs after the destroy (:229) and before the rebuild (:233) — truncateTornTail is called from :229. So in the crash window the situation on the ground is: the only trace the runtime ever emits about this recovery says "recovered", the fsync'd destroy has landed, the fsync'd rebuild has not, and the salvaged records are about to stop existing. A later reader of that log is told the recovery happened; the file tells a different story by being a shorter prefix with nothing marked.

4. The same package already orders a durable rewrite correctly — destroy last

This is not a general property of the codebase's durability layer. The migration publish path does the opposite, and does it deliberately, with comments. Master src/index.ts:1298-1323 (npm artifact :3223-2335, comments stripped):

const tmp = await this.writeSyncedTempFile(finalPath, content)   // write + fsync the NEW content first
// Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the
// final path already exists, so two processes materializing the same id
// concurrently cannot clobber each other. rename() would silently overwrite.
let linked = false
try {
  await link(tmp, finalPath)                                      // publish
  linked = true
} finally {
  if (!linked) await rm(tmp, { force: true })                     // destroy the temp only on failure
}
// link() succeeded — the log is published. fsync the directory so the new
// entry survives a power loss: the new link is not crash-durable until the
// parent directory's metadata is synced.
await this.syncDirPosix(dir)
try {
  await rm(tmp, { force: true })                                  // destroy the redundant temp AFTER publish
} catch { /* Swallow only the rm failure … */ }

New content is written and fsync'd (writeSyncedTempFile, :1361/:3257: open(tmp, "wx"), writeFile, sync), then published, then — only then — is the old redundant copy removed. A crash at any point leaves either the temp (unpublished, ignored by canonical-name scanning) or the published file; never neither. The comments spell out the crash-durability reasoning step by step. Torn-tail repair is the one durable rewrite in this package that runs the same two operations in the other order.

5. Relation to adjacent reports

@PerryLink 的 #6493 already named this exact window in the thread dismissing the migration-truncation claim: "The only truncate-before-rewrite window is torn-tail repair on the current generation (storage.ts:328-337), bounded to one torn zstd frame." That comment used the window as a scale bound — it cannot explain a day-long outage. This report is the other half of that sentence: what the bound bounds is a real interval between two fsync'd steps, and what can die inside it is the set of complete records the recovery salvaged. Same window, contents instead of size.

#8010 (@Kizaemon) covers whole trailing frames lost where no repair runs at all — the reader accepts a shorter prefix, and the gap is detection. Here the repair does run; the gap is that its two halves are not crash-atomic against each other.

6. Scope, stated so it can be checked

The window needs three conditions, all checkable in the published artifact:

• zstd compression — the default (:2290 DEFAULT_COMPRESSION = "zstd", :2302 schema default, :2435 config.compression ?? DEFAULT_COMPRESSION). The uncompressed path never salvages anything (recoveredTail: [] at :2852), so it has no window.
• the torn frame must contain at least one complete record (recoveredTail.length > 0, :233) — an empty salvage skips the rebuild and loses nothing.
• a process death after :229 fsyncs and before :233 fsyncs. The interval spans one persistBatch call; it is narrow. It is also the only path where the destroyed source bytes are the sole copy of records the package has already decided to keep.

Opinion, flagged as such — this paragraph is the only one carrying a position: for a production runtime's recovery path I would hold one rule: the rebuild must be able to survive the destroy. A repair that permanently loses salvageable records in its own crash window turns a recoverable state (re-decodable on every open) into an unrecoverable one (a clean prefix, no markers, nothing to retry), and its only log line has already claimed success. I am not proposing a fix design, not asking for a new field, and not claiming an intent — the question is only whether "durably rewrites those recovered records" should also hold when the crash lands inside the repair itself, and whether the migration path's order (write, publish, then destroy) is the order the repair path should meet as well.

Environment

@deepseek-ai/dsh-session-persistence-jsonl@0.2.1-rc.5 — next tag as of 2026-10-31 (latest=0.0.1-rc.1, alpha=0.2.2-alpha.2); repository coordinates from master ce7073d51 (2026-10-29T16:13:15Z). Readings taken by reading the published npm tarball and the master sources; no code was executed and no other version was inspected. Host OS not involved — the analysis is of the write-path ordering, not of a platform-specific failure.

Authorship note: I ran into this in my own daily use and wrote it up. Root-cause analysis and drafting were assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out and I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/. Contact: contact@offerkuai.com

---

中文版

一句话。 @deepseek-ai/dsh-session-persistence-jsonl 的撕尾修复是两步：persistContiguous 先调 truncateTornTail（lib/index.js:229），把日志截断到最后一个完整帧并 fsync；之后才调 persistBatch 把抢救出的记录写回（:233）。两步都是持久写，都可能被中断——但第二步开始时，第一步已经把抢救记录所源自的那份磁盘上唯一的副本销毁了。两段 fsync 之间进程崩溃，恢复捞出的每一条完整记录都会永久、静默地丢失：下次打开看到的是干净前缀，不设截断点，不触发修复，也不留任何丢弃痕迹。

本报告立在一条规矩上，只说一次：重建必须能在销毁之后活下来——顺序不能反。 同一个包在它的迁移发布路径里已经遵守这条规矩（§4）。我不提修法、不提新字段、不提排期；我问的是：这个包对抢救记录承诺的持久性，是否也应该覆盖修复动作自身内部的那次崩溃。

1. 修复是两步持久写，先销毁

读 @deepseek-ai/dsh-session-persistence-jsonl@0.2.1-rc.5（2026-10-31 写作时的 next；latest 是 0.0.1-rc.1，alpha 是 0.2.2-alpha.2）。以下行号除标注 master 外，均取自发布产物 lib/index.js。

共享的持久追加主体 persistContiguous 按此顺序执行修复（:228-235）；master ce7073d51 在 packages/session/session-persistence-jsonl/src/storage.ts:328-337 保持同样顺序——正是 @PerryLink 在 #6493 里点名的那扇窗：

if (this.state.tornTruncateTo !== void 0) {
    await this.storage.truncateTornTail(this.header, this.state.tornTruncateTo);   // :229  销毁
    this.state.tornTruncateTo = void 0;
}
if (this.state.recoveredTail !== void 0) {
    if (this.state.recoveredTail.length > 0) await this.storage.persistBatch(this.header, this.state.recoveredTail, ...);  // :233  重建
    this.state.recoveredTail = void 0;
}
await this.storage.persistBatch(this.header, batch, ...);                          // :236  新追加

第一步 truncateTornTail（:2938-2942）调用 repair（:3337-3346）：truncate(path, offset) 之后 r+ 打开、sync()、close()。销毁是 fsync 的——:229 resolve 之后，撕裂字节就已从磁盘上持久消失。

第二步 persistBatch 写回 recoveredTail（:233），追加并 fsync 那些抢救出的记录——在它们所源自的字节已经不存在之后。

tornTruncateTo 与 recoveredTail 都只活在这个句柄的内存状态里（:228、:232）。第二步没有任何 journal、暂存或跨进程死亡的可恢复性。

2. 两步之间死掉的是什么

修复运行之前，撕裂的末帧还在磁盘上，每次打开都会重新解码它：decodeStoredLog 调 decompressZstdPrefix(buffer.subarray(tornStart))（:3024），把抢救出的记录放进 recoveredTail 返回（:3036-3037）。恢复是可重复的——在 :229 之前崩溃，重新打开，同样的记录会再回来。

:229 resolve 之后，这就不再成立。帧没了；记录只存在于这个句柄的内存里，等着一个还没开始的步骤。进程在 :233 fsync 之前死掉的话：

• 磁盘上的日志是干净前缀——完整帧，无撕裂尾；
• 下次打开算出 tornTruncateTo: undefined、recoveredTail: []（:3017-3018），不触发修复，也不打日志；
• 恢复已经捞出的完整记录既不在文件里，也无法再从文件里恢复——唯一的源字节就是 :229 截掉的那些。

这些不是假想的字节。恢复路径自己的注释（master src/index.ts:1047-1049）说得很清楚：

// A torn final frame's append never resolved, but complete JSONL records
// already flushed into it are real emitted events: recover them, and let
// the write path truncate the torn bytes and rewrite them durably.

包也在三处承诺了这次重写。README（README.md:77）："a write handle truncates the torn bytes and durably rewrites those recovered records before its first new batch." 状态字段的文档注释（master src/index.ts:128）："Complete events recovered from the torn final frame; the write path rewrites them durably." 还有上面那条注释。崩溃窗口里丢掉的，正是这三处文本承诺要保住的东西。

有一条边界我要说精确，因为它是最强的反读法：基础包的不变量清单（@deepseek-ai/dsh-session-persistence@0.2.1-rc.5，README.md:86）写着"A torn physical tail never reaches a reader. It belongs to an append that never resolved; the write path truncates it durably before its first new append." 这条不变量管的是撕裂碎片——碎片确实被丢弃了。它不管从帧里解码出来的完整记录：那些记录被承诺了一次持久重写（:77），而崩溃窗口正是这个承诺可能落空的地方。在包自己的文本里这是两个分开的主张，只有第一个是无条件的。

3. 唯一那行日志在重建开始之前就发了

整个文件只有四条运行时日志（:423、:438、:2731、:2941）。撕尾那条（:2941）在 truncateTornTail 内部、repair resolve 之后：

this.ctx.logger.warn(`${this.name}: session "${header.id}" recovered from a torn tail; incomplete tail bytes were discarded`);

按控制流，这条 warn 在销毁（:229）之后、重建（:233）之前——truncateTornTail 就是从 :229 调进来的。所以在崩溃窗口里，地面上的情况是：运行时关于这次恢复发出的唯一痕迹写着"已恢复"，fsync 过的销毁已经落地，fsync 过的重建还没有，而抢救出的记录即将不复存在。后来的读者从日志里被告知恢复已经发生；文件却讲了另一个故事——它是一个更短的前缀，且什么都没标记。

4. 同一个包已经把一次持久重写排对了——销毁在后

这不是该代码库持久层的一般性质。迁移发布路径做的是相反的顺序，而且是带注释地 deliberate。master src/index.ts:1298-1323（npm 产物 :3223-2335，注释被剥掉）：

const tmp = await this.writeSyncedTempFile(finalPath, content)   // 先把新内容写入并 fsync
// Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the
// final path already exists, so two processes materializing the same id
// concurrently cannot clobber each other. rename() would silently overwrite.
let linked = false
try {
  await link(tmp, finalPath)                                      // 发布
  linked = true
} finally {
  if (!linked) await rm(tmp, { force: true })                     // 只在失败时销毁 temp
}
// link() succeeded — the log is published. fsync the directory so the new
// entry survives a power loss: the new link is not crash-durable until the
// parent directory's metadata is synced.
await this.syncDirPosix(dir)
try {
  await rm(tmp, { force: true })                                  // 发布之后才销毁冗余 temp
} catch { /* Swallow only the rm failure … */ }

新内容先写入、先 fsync（writeSyncedTempFile，:1361/:3257：open(tmp, "wx")、writeFile、sync），然后发布，然后才移除旧的冗余副本。任何一点崩溃，留下的要么是 temp（未发布，被规范名扫描忽略），要么是已发布的文件；不会两者皆无。注释逐步写明了 crash-durability 的推理。撕尾修复是这个包里唯一一次把同样两个操作反着排的持久重写。

5. 与相邻报告的关系

@PerryLink 的 #6493 已经在驳斥迁移截断主张的那条线程里点名了这扇窗："The only truncate-before-rewrite window is torn-tail repair on the current generation (storage.ts:328-337), bounded to one torn zstd frame." 那条评论把这扇窗当规模下界用——它解释不了一整天的中断。本报告是那句话的另一半：这个下界所限定的，是一段真实的、位于两次 fsync 之间的区间；而能死在里面的，是恢复所捞出的那批完整记录。同一扇窗，看的是内容，不是尺寸。

#8010（@Kizaemon）覆盖的是整段尾帧丢失且完全没有修复发生——读者接受一个更短的前缀，缺口在检测。这里修复确实跑了；缺口在于它的两半彼此之间不是崩溃原子的。

6. 危害面，写出来以便核验

这扇窗需要三个条件，全部可在发布产物里核对：

• zstd 压缩——默认路径（:2290 DEFAULT_COMPRESSION = "zstd"、:2302 schema default、:2435 config.compression ?? DEFAULT_COMPRESSION）。无压缩路径不抢救任何东西（:2852 恒为 recoveredTail: []），没有这扇窗。
• 撕裂帧内至少含一条完整记录（recoveredTail.length > 0，:233）——空抢救会跳过重建，什么都不丢。
• 进程死在 :229 fsync 之后、:233 fsync 之前。 这段区间横跨一次 persistBatch 调用，很窄。它同时也是唯一一处：被销毁的源字节，是包已经决定要保留的那些记录的唯一副本。

以下是意见，已标明——本段是全稿唯一带立场的部分：对一个生产级运行时的恢复路径，我会守一条规矩：重建必须能在销毁之后活下来。 一次修复如果在自己的崩溃窗口里永久丢失可抢救的记录，就是把一个可恢复状态（每次打开都能重新解码）变成不可恢复状态（干净前缀、无标记、无可重试），而它唯一的日志行已经宣称成功。我不提修法设计、不要求新字段、不断言意图——问题只有一个："durably rewrites those recovered records" 这句承诺，是否也应该在崩溃落进修复动作自身内部时成立；迁移路径的顺序（先写、先发布、后销毁）是否就是修复路径该达标的那个顺序。

环境

@deepseek-ai/dsh-session-persistence-jsonl@0.2.1-rc.5——2026-10-31 写作时的 next 标签（latest=0.0.1-rc.1、alpha=0.2.2-alpha.2）；仓库坐标取自 master ce7073d51（2026-10-29T16:13:15Z）。读数都取自 npm 发布 tarball 与 master 源码的阅读；没有执行任何代码，也没有检视别的版本。不涉及宿主系统——本分析针对的是写路径的顺序，不是某个平台特有的故障。

声明：本文由我在日常使用中撞到并记录成文；根因与成文由 AI 协助完成，我负责校验与发布。我非工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。

本报告由 OfferKuai（Offer快）团队 提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/。联系：contact@offerkuai.com

[LyleLiu666]

I reproduced the 8 → 6 event loss by killing the writer immediately after it truncates the torn frame. I have a local fix that saves the recovered events in a small sidecar journal before repairing the original file. New readers use that journal if repair is interrupted.

On macOS and Linux, fresh processes still read all 8 events after kills during truncation and rewriting. A stale journal after later appends does not roll the log back, and repeated interrupted recovery preserves the later events too. The recorded SDK resume test also produces the same complete transcript. On a full Linux tmpfs, recovery fails without changing the main file; freeing space and retrying succeeds.

The main file keeps its inode and permissions. This requires upgrading all readers of a shared store, and the implementation refuses automatic tail repair when the file has multiple hard links, because an alias could miss the journal. Native Windows testing is still outstanding.

Is anyone already working on this? Would a PR with journal-aware reads and those two constraints fit the project?

[yamingmou]

@LyleLiu666 — your reproduction lands on the window this post is about: killed after the truncate, before the rebuild lands.

Your question has three parts in it, and keeping them apart matters — the answer to each is different.

Is anyone working on it. Speaking only for ourselves: we are outside developers, the same as you. We file reports and we build tooling around this project; we have no fix in flight for this window and none planned on our side. Does a PR fit. That call belongs to the maintainers. We cannot answer for the project, and we would rather say so than guess.

What we can say about the design — two points, plus an offer.

The first point is that your crash window sits on a contract that is already published. We maintain dsh-log-contract, an offline session-log contract guard; one of its rules is Z6 — tail completeness must be declared: tailStatus: complete | interrupted | truncated | unknown, with the boundary written down honestly (a clean ok certifies only the events that were actually read, not that the tail survived). Your window makes a case that rule did not have: after the destroy step the main file decodes cleanly and is simply short. Nothing is torn, nothing is malformed — two records are absent, and absence leaves no gap for a checker to find. A file-only check, ours included, will call that file fine. The journal is the only witness — which is the interesting part: once a journal exists, "what does tail status mean — the file, or the store?" stops being an implementation detail and becomes a contract question that readers and checkers both need one stated answer to. If that is useful to you: an independent verdict on your interrupted-repair states is exactly what such a checker is for. It is public, and PRs on the rule catalog are welcome.

The second point is about two constraints your design already implies but does not state.

• The journal is a second authority, and its criterion is unstated. You handle the stale-journal case (an append after repair must not roll the log back), which is the right case to handle — but why it does not roll back is what a future reader needs written down: an offset inside the journal, a completion marker, an mtime comparison? Whichever it is, the recovery path should say which store is authoritative and which range it failed to recover. A second source of truth that does not declare its own precedence is how "recovered" ends up meaning two different things.
• nlink > 1 is one instance of a wider class: writers that cannot see the journal. Refusing automatic repair for multiple hard links is defensible for exactly the reason you give. That reason covers more than aliases — an older host version, a restore from backup, an external tool that trims or rewrites the log at startup. For hard links you refuse; for the rest, the behaviour is not stated. And what matters for the failure in the report is what happens after the refusal: a typed error, a skip, or a normal open of a damaged log. If it lands on "open as usual", the damage is silent again — the same shape as @AnnidLin's #12008, through a different entrance.

One more, since you named it yourself: "upgrade all readers of a shared store" is a compatibility promise with no enforcement point. Anything a reader is allowed to skip, a reader will skip.

That is all we have — no claim on the project's roadmap from us.

Authorship note: root-cause reading and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out and I will re-verify and correct.

Reported by the OfferKuai Team (Offer快) — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/. Contact: contact@offerkuai.com

---

中文版

@LyleLiu666 —— 你这次复现正好落在本篇所说的窗口上：truncate 之后、重建落地之前被杀掉。

你那一问里面其实有三件事，分开答很重要 —— 三件事的答案各不相同。

有没有人在做。 只代表我们自己说：我们和你一样是外部开发者。我们会提报告、会在项目周边做工具；这个窗口我方没有在修的补丁，也没有提交计划。这个 PR 合不合。 那是维护者的判断。我们不能替项目回答，与其猜，不如直说不能答。

关于你的设计，我们能说的两点 —— 外加一个邀请。

第一点：你这个崩溃窗口，正好落在一份已经公开的契约上。我们维护 dsh-log-contract（离线会话日志契约守护），它其中一条规则是 Z6 —— 尾部完整性必须显式声明：tailStatus: complete | interrupted | truncated | unknown，并且把边界如实写下来（ok 干净只认证真正被读到的事件，不保证尾部还在）。你这个窗口给了这条规则一个它原先没有的案例：销毁那一步之后，主文件解码是干净的，只是变短了。 没有撕裂、没有畸形 —— 两条记录不存在，而不存在不会留下任何空隙供检查器发现。只看文件的检查（包括我们这个）会判定那个文件没问题。journal 是唯一的证人 —— 而这正是有意思的地方：journal 一旦存在，「tail 状态说的是文件，还是整个存储」 就不再是实现细节，而变成读者与检查者都需要同一句声明的契约问题。如果对你有用：你那几个"中断恢复"状态，正好可以拿这种检查器做一次独立裁决 —— 它是公开的，规则目录欢迎 PR。

第二点：你的设计里有两处约束，是已经被隐含、但还没写出来的。

• journal 造了第二权威，而判据没写。 你处理了 stale journal（修复之后的追加不得把日志回滚），这是该处理的那一格 —— 但为什么它不会回滚，才是后来读代码的人需要看到的：journal 里记 offset？一个完成标记？还是比 mtime？无论选哪个，恢复路径都该说清哪一份存储是权威、以及哪一段范围没能恢复。一个不声明自己优先级的事实来源，正是「recovered」这个词开始出现两种含义的方式。
• nlink > 1 是一大类里的一例：看不见 journal 的写者。 多硬链接时拒绝自动修复，理由正当，就是你给的那条。但那条理由覆盖的不止别名 —— 旧版本宿主、从备份恢复、启动时裁剪或改写日志的外部工具。硬链接你拒绝了；其余这些，行为没写。而对原报告里那个失败真正要紧的是拒绝之后发生什么：typed error、跳过、还是照旧打开一个已受损的日志？若落到「照旧打开」，损伤就又回到静默 —— 与 @AnnidLin 的 #12008 同一形状，只是换了入口。

还有一句，因为是你自己点出的：「所有读者都要升级」是一条没有执行点的兼容承诺。凡是允许读者跳过的，读者就会跳过。

我们就这些 —— 不对项目路线图做任何主张。

声明：根因阅读与文稿撰写由 AI 协助完成；核验与发布由我本人负责。我非工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。

本报告由 OfferKuai（Offer快）团队 提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/。联系：contact@offerkuai.com

[LyleLiu666]

Thanks — the prototype uses the main file plus a matching journal for recovery. The journal records the file identity, a hash of the intact prefix, and the exact recovered events. Overlapping events must match. If the main file already contains those events and later appends, it wins; otherwise the reader supplies only the missing suffix. This does not depend on mtime ordering.

An identity, prefix or event mismatch raises SessionPersistenceCorruptionError. Reads and write opens reject; they do not fall back to the shorter main file. Hard-link refusal happens before repair changes any bytes. I added an agent-resume test: the failure propagates, no Session is published, ownership is released, and retry succeeds after the extra link is removed.

The compatibility concern remains real. On the same interrupted store, the upgraded reader returns 8 events and the old reader returns 6. Deleting the journal also leaves the upgraded reader with only 6. The write protocol assumes writers use the existing lease; it cannot protect against tools rewriting files outside that protocol.

Whether coordinated reader upgrades are acceptable is a decision for the maintainers. Native Windows validation is still outstanding.

[yamingmou]

@XJPeng12's #11258 got a patch from its own author, and that patch looks like the right fix for what was reported. What it implies reaches past that one package — so the general form is written down here rather than only in that thread.

We reproduced the structure on the published tarball: the deadline is armed on exec.signal, but the TOOL_TIMEOUT result is substituted only after next() settles. So when the transport swallows the abort on an in-flight body read, no line of code runs at the moment the budget is reached — the step simply waits, and the caller cannot tell "slow" apart from "unbounded".

What I would generalise is not "a timeout was too soft", but this: the constraint was declared as data, and nothing executes when it is reached.

Same shape, different producer — @wutyi4330's #11298 (2026-10-28): when a single response hits max-tokens, agent-loop returns that as the result and the turn loop breaks out through the normal completion path, so the UI reports the turn as completed while the output is cut mid-sentence. That reporter makes the same point themselves — dsh-compaction exists, but it is a pre-emptive context-budget compaction and does not cover the single-response-truncated case. A declared limit, again with nothing that runs where it is hit.

⇒ That gives a check that generalises past either report: enumerate the constraints the runtime declares (budgets, caps, windows) and, for each, ask whether any code path executes at the moment that constraint is reached. A declared constraint with no execution point is data, not a rule — and from the caller's side the two are indistinguishable.

The post above is the same shape seen from the log side: it declares recovered at the moment the destroy step runs, and the rebuild that would justify the word happens afterwards — if it happens at all.

Opinion, flagged as such: I would enumerate before racing. A race closes the budget you already found; an enumeration surfaces the ones nobody has reported yet.

Authorship note: the structure above was confirmed by me against the published npm tarball of @deepseek-ai/dsh-tool-call-timeout-policy (0.2.1-rc.4, next tag as of 2026-10-29); no other version was run. Drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team (Offer快) — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/. Contact: contact@offerkuai.com

---

中文版

@XJPeng12 的 #11258 已经由作者本人给了补丁，这个补丁看起来正是针对所报问题的那一刀。而它暗示的东西不止那一个包 —— 所以一般化形式写在这里，而不是只留在那个帖子里。

我在已发布的 tarball 上复现了这个结构：deadline 挂在 exec.signal 上，但 TOOL_TIMEOUT 结果只在 next() 落定之后才被替换。于是当传输层把中断吞掉（中断落在一次正在进行的 body 读取上）时，在预算被触及的那一刻没有任何一行代码在跑 —— step 只是干等，调用方分不出"慢"和"没有上界"。

我想给出的那层概括不是"超时设得太软"，而是：约束被声明成了数据，而在它被触及时没有任何东西执行。

同一个形状，另一个产生侧 —— @wutyi4330 的 #11298（2026-10-28）：单次响应触到 max-tokens 时，agent-loop 把这个结果当正常出口 break 出去，界面于是报"成功完成"，而输出被截在句子中间。那位报告人自己也点了这一句：dsh-compaction 在，但它是预防性的上下文预算压缩，不覆盖"单次响应被截断"这一格。又是：声明了上限，触顶处无执行点。

⇒ 由此得到一条可枚举的自查：把运行时声明出来的约束（预算／上限／窗口）列一遍，逐个问一句 —— 约束被触及时，有没有代码在那里执行？ 声明了却没有执行点的约束，是数据不是规矩；而在调用方看来，这两者不可分辨。

上面那篇帖子，是同一形状在日志侧的样子：它在销毁那一步跑起来时就已经声明了 recovered，而那个能让这个词成立的"重建"发生在之后 —— 如果它真的发生。

以下是意见，已标明：我会先枚举再修。一次 race 补上的，是你已经发现的那个预算；枚举照出的，是还没有人报的那些。

声明：上述结构由我对照 @deepseek-ai/dsh-tool-call-timeout-policy 的已发布 npm 产物（0.2.1-rc.4，写作时 next）核实，未跑过别的版本；文稿撰写由 AI 协助；核验与发布由我本人负责。我非工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。

本报告由 OfferKuai（Offer快）团队 提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/。联系：contact@offerkuai.com

[yamingmou]

@LyleLiu666 — that answers the two things I asked, and it answers them with criteria rather than assurances: identity + prefix hash + exact events, refusal before any byte changes, no fallback to the shorter file. That is a second authority that states its own precedence, which is what was missing.

One path it does not cover, and I would rather ask than assume.

Your stale-journal handling covers the order new reader, old journal: the main file has moved on, the journal is behind, the file wins. The reverse order is a supported way to run: an older reader opens that same interrupted store, sees the six events, and the user keeps working. Whatever the writer assigns to the next event, it is the seq the recovered record would have occupied — the truncation freed exactly that position.

Now the main file holds a record at that seq, and the journal holds a different record at the same seq. Under "overlapping events must match", that is a mismatch, so it raises SessionPersistenceCorruptionError — and a session that was merely mixed-version becomes a session that will not open. The bytes were never corrupt; an older writer used the position legitimately.

Is that the intended verdict? Both answers are defensible, but they are different judgements and one criterion cannot stand for both: either mixed-version use counts as corruption (and the error is right), or the newer write wins and the journal drops to read-only evidence that needs a human decision. Whichever you choose, say it out loud, because this is the one path where your two constraints — refusal rather than fallback, and overlap must match — point in opposite directions.

On your last paragraph: agreed, and that is the reason it matters less whether the protocol can defend against out-of-protocol writers than what the refusal leaves behind. A refusal that is only reachable through a raised error the caller then swallows is still silent from where the user sits.

Authorship note: drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out and I will re-verify and correct.

Reported by the OfferKuai Team (Offer快) — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/. Contact: contact@offerkuai.com

---

中文版

@LyleLiu666 —— 这答了我问的两件事，而且是用判据答的，不是用保证答的：文件身份 + 前缀哈希 + 精确事件、任何字节改动之前就拒绝、不回退到更短的文件。这就是一个声明了自己优先级的第二权威 —— 原本缺的正是这个。

有一条路径它没覆盖，我宁愿问一句也不假设。

你的 stale-journal 处理覆盖的是 新读者、旧 journal 这个顺序：主文件已经往前走，journal 落后，主文件赢。反过来那个顺序同样是受支持的使用方式：旧读者打开同一个中断过的存储，看到 6 条，用户接着干活。写入者为下一条事件分配的任何一个 seq，都正是那条恢复记录本该占的位置 —— 截断恰好把这个位置空了出来。

于是现在：主文件在那个 seq 上有一条记录，journal 在同一个 seq 上是另一条记录。按「overlapping events must match」，这就是不匹配，于是抛 SessionPersistenceCorruptionError —— 一个本来只是混版本使用的会话，变成一个打不开的会话。字节从来没坏过；是一个更旧的写入者合法地用了那个位置。

这是预期的判定吗？两个答案都站得住，但它们是两个不同的判断，一条判据代表不了两者：要么混版本使用算损坏（那么抛错是对的），要么更新的那次写入赢、journal 降为只读证据、交给人工裁。无论选哪个，都该明确写出来 —— 因为这是你的两条约束（拒绝而非回退、重叠必须匹配）唯一指向相反方向的那条路径。

关于你最后一段：同意。也正因如此，协议能不能防住协议外的写者，不如拒绝之后留下了什么重要。一个只能通过抛出异常来拒绝、而调用方又把异常吞掉的拒绝，从用户的位置看仍然是静默的。

声明：文稿撰写由 AI 协助完成；核验与发布由我本人负责。我非工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。

本报告由 OfferKuai（Offer快）团队 提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/。联系：contact@offerkuai.com

[LyleLiu666]

I tested that exact sequence with an older writer from the clean upstream build. It reads the six-event log and successfully appends different events at seq 6 and 7, leaving the journal in place.

The upgraded read open, write open and agent resume all reject with SessionPersistenceCorruptionError: event content mismatch. Both files remain byte-for-byte unchanged. Resume publishes no Session, and repeating it reports the same conflict rather than an ownership error.

That refusal is intentional. Here the error describes conflicting persisted histories, not undecodable bytes. Automatically choosing the newer write would discard the events the journal was created to preserve. The files are retained for explicit reconciliation; this patch does not choose between them.

Continuing to write with an older version is outside the coordinated-upgrade requirement. Whether that requirement fits the project remains for the maintainers to decide.