Transcript JSONL corruption; records spliced by unsynchronized writers

Thanks for the detailed audit. Tried to reproduce on the released 2.1.233 build (macOS): scanned a local corpus of ~5,500 transcript .jsonl files (many months of use, including subagent transcripts) and found 0 invalid lines, and a fresh session with two parallel subagents produced fully valid main and subagent transcripts. So we couldn't reproduce the splice locally in the time budget, but your data (17 distinct days, 16 versions, same-session halves on one line) is convincing.

Classification: real bug, not a regression. We confirmed from the current code that several independent writers still append to the same session file without a single shared lock, and that the in-place tombstone-removal path (truncate + positional rewrite of the tail) can overlap with one of the out-of-band metadata appenders. That is a plausible source of spliced/partial lines, and we agree the intended contract is "one atomic write of json + \n per record, all writers serialized per file, in-place rewrites exclude appenders." We're tracking a fix along those lines (and will look at the unbounded batch size you flagged).

If you can, one sanitized example would help pin the mechanism: for a truncated-splice line, the type of the cut-off record and of the record that follows it, plus whether a } fragment line appears anywhere later in the same file. Also OS/filesystem details for any non-ext4 occurrences.

🤖 Generated with Claude Code

Follow-up: mechanism details for the truncated splices

@bcherny

Ran the follow-up on the same corpus, now 13,013 files (~2,064 added since the report). Zero new occurrences in the added files — nothing newer than 2.1.215 (installed is 2.1.234). Answers to your three questions first, then a new structural finding that surfaced while extracting them.

1. Record types at each truncated splice

All 21 instances (letters are anonymized per-file IDs):

| line | cut-off type | following type (role / block) | version |
|---|---|---|---|
| A:948 | message | assistant (text) | 2.1.113 |
| A:1029 | message | assistant (text) | 2.1.113 |
| B:2532 | user | file-history-snapshot | — |
| D:1250 | user | user (tool_result) | 2.1.81 |
| E:258 | message | progress | 2.1.81 |
| F:7138 | user | assistant (thinking) | 2.1.38 |
| G:596 | message | assistant (text) | 2.1.91 |
| I:62 | progress | user (tool_result, isSidechain) | 2.1.50 |
| K:1457 | message | file-history-snapshot | — |
| L:62 | message | assistant (thinking) | 2.1.215 |
| M:315 | user | assistant (tool_use) | 2.1.185 |
| M:319 | message | system | 2.1.185 |
| N:794 | user | assistant (thinking) | 2.1.215 |
| O:663 | user | assistant (text) | 2.1.91 |
| T:980 | message | user (tool_result) | 2.1.74 |
| U:318 † | message | file-history-snapshot | 2.1.50 |
| U:470 † | message | file-history-snapshot | 2.1.50 |
| V:365 | (cut before type) | progress | 2.1.71 |
| V:376 | (cut before type) | file-history-snapshot | — |
| AA:238 | user | user (tool_result) | 2.1.7 |
| AA:345 | (cut before type) | assistant (thinking) | 2.1.7 |

† the only two page-unaligned cut points (see the finding below).

Roll-up:

• Cut-off types: message ×9, user ×7, progress ×1, cut before type ×3
• Following types: assistant ×9, file-history-snapshot ×5, user ×3, progress ×2, system ×1
• 20/21 in main-session transcripts, 1 (file I) in a subagent transcript

2. Later } fragment lines

No, in all 21 cases. The dropped tail bytes never reappear anywhere later in the file.

3. Filesystem

Every occurrence is on a single local ext4 NVMe volume — verified via identical st_dev across all 13,013 files, so there are no non-ext4 occurrences to report.

New finding: cut points sit on 4 KiB page boundaries

19 of the 21 splice cut points are at an exact multiple of 4096 bytes from the start of the file (only U:318 and U:470 are unaligned). Higher alignments do not hold — 8192: 12/19, 16384: 7/19, i.e. chance level — so the boundary is specifically the 4 KiB page.

Two related observations:

• NUL-prefixed lines (6 lines in a disjoint set of 5 files; no file has both a splice and a NUL line): runs of 391–3848 NUL bytes followed by a fully valid record (5× file-history-snapshot, 1× custom-title). 4 of the 6 NUL runs end on an exact 4096 multiple.
• The 3 missing-newline junctions are unaligned, consistent with plain interleaving and no data loss.

Both damage modes match a page-granular partial write whose remainder is never retried: a short write()/flush that isn't looped on, with the file offset advancing anyway. The splice case is the buffer's first N pages landing and the tail being dropped; the NUL case is the mirror image — the offset advancing over a region whose data never reached the page cache, leaving a materialized hole ending on a page boundary. This doesn't require interleaving between writers — a single writer mishandling a short write produces exactly this signature.

Follow-up: we audited the deployed 2.1.234 binary (beautified extract of the transcript-store region) to test the short-write hypothesis, and the page-alignment evidence points at a specific function — not the append path.

The append hot path is safe

All four writer domains funnel into one primitive built on fs/promises.appendFile, which loops on partial writes. Verified empirically (RLIMIT_FSIZE probe, Bun and Node agree): appendFile/appendFileSync throw rather than short-write; bare FileHandle.write silently resolves short (e.g. bytesWritten 3096 of 6000).

But three FileHandle.write call sites on the transcript path discard bytesWritten

• the compaction rewriter (performCompactTranscript): the chunked flushes to the .compact.tmp.<hex> file, the final flush, and the concurrent-tail catch-up write;
• the tombstone remover (performRemoveByUuid): the positional tail rewrite after the truncate.

The compaction rewriter matches the corpus signature point for point

1. A short write leaves a record cut mid-content with the next chunk appended contiguously at the advanced fd position — a splice, no gap, no duplication.
2. The dropped tail is cleared from the accumulator on the same line and never retried — matching our strongest observation: the cut-off bytes never reappear anywhere in the file (writer interleaving would leave them somewhere).
3. The tmp file is written sequentially from offset 0, and a partial completion of an ext4 buffered write stops on a page-aligned file offset — matching 19/21 cuts landing on exact 4096-byte multiples measured from file start. Measured, not just argued: on a loop-mounted ext4 filled to hard ENOSPC and then given back exactly 65536 free bytes, a single 512 KiB FileHandle.write to a file seeded with a deliberately unaligned 1234-byte prefix returned bytesWritten = 64302 with no error, leaving the file at exactly 65536 bytes (size % 4096 === 0): the first partial page was filled from 1234 to 4095, then 15 full pages, then it stopped — the cut lands on a page boundary of the file offset regardless of where the write began. Identical on Bun and Node.
4. The short-written tmp is then rename()d over the live session file. Every pre-rename guard (stat ino/size re-samples, h.sync()) validates the source transcript; nothing validates the bytes just written — h.sync() sits exactly where a bytesWritten check would have caught it.

Triggers, and the fix shape already in the tree

On triggers: ENOSPC is the classic real-world partial-write cause, and 2.1.217's changelog already added disk-full warnings for transcript writes, so this condition is known to occur in the field on this path. Notably, the codebase already contains the correct pattern — one auxiliary transcript-append helper hand-rolls a bytesWritten retry loop ("tryAppend: short write … stalled") — while these three sites rely on unchecked writes. Fix shape: that same loop at the three call sites, plus a written-bytes/final-stat assertion before the rename.

What the original race still explains

The exit-handler race and the un-serialized out-of-band metadata re-append from the original report are still present in 2.1.234, but they can only account for the 3 unaligned missing-newline junctions — they cannot cut a record mid-string, since every append emits whole json + "\n" strings through the looping appendFile.

---

Probe scripts: https://gist.github.com/NubeBuster/1a03409a3e95c322607f01d972048522