Multi-machine sync correctness: transcript conflicts, history merge, debris, desktop records

[sjalife]

Fixes #69, #70, #71, #72, #76.

This supersedes and includes #78, which I've closed. Everything here came out of running claude-sync across three machines for a few weeks and then investigating what went wrong; each issue has the full evidence, and this is the code.

Seven self-contained commits, one per concern — reviewable and revertable individually. If you'd rather take a subset, say which and I'll split; commits 1–5 are the data-safety fixes and 6–7 are additive.

#	Commit	Issue
1	fix(sync) resolve append-only transcript conflicts by comparing bytes	#69, #70
2	fix(sync) never sync per-machine debris (.lock and .conflict artifacts)	#71
3	feat(storage) typed ErrNotFound	prerequisite for 4
4	fix(sync) union-merge history.jsonl instead of last-writer-wins	#72
5	feat(sync) union-merge genuinely diverged session transcripts	completes #69
6	feat(sync) sync Claude Code Desktop session records	#76
7	fix(cli) report per-file sync errors to stderr in quiet mode	—

1–2: transcripts stop losing data

Pull declares a conflict from metadata alone — remote newer than our last upload, local hash differs from state. For append-only transcripts both are routinely true with nothing diverging, because a live session appends between two syncs. Content is never compared, so a fast-forward is indistinguishable from a fork.

Three machines produced 92 .conflict artifacts in about a week. 91 held no unique data. The 92nd was inverted: local was a truncated 41-line copy and the .conflict file was the complete 251-line transcript, so the rule kept the damaged copy and hid the intact one under a name Claude Code never reads.

Pull now classifies the byte relation first: equal → refresh state; remote ahead → fast-forward by appending the missing tail (never a rewrite, so a concurrent appender can't lose lines); local ahead → keep, no .conflict; diverged → commit 5. Push gets the mirror guard so a truncated local can't clobber a fuller remote, paid only when a file shrank, failing open on any fetch error.

Commit 2 stops the tool replicating its own debris: zero-byte .lock files, and the .conflict artifacts themselves — which self-replicate, since handleConflict writes them inside a synced directory. The .conflict pattern is anchored on the exact timestamp format the tool generates, because excluding an already-tracked path prunes it from the bucket; a loose *.conflict.* would remotely delete a user's notes.conflict.md.

3–4: history.jsonl stops losing prompts

One file appended by every machine, synced as an opaque blob, so pushes are last-writer-wins. #63 recovers the loss after the fact; this prevents it. Push GETs the remote, unions, uploads; pull appends missing lines rather than overwriting or writing .conflict.

Three properties worth keeping in any implementation: merges only ever append (a live session can't lose lines to a stale-read rewrite), they're idempotent by raw-line dedupe, and a fetch error aborts rather than uploading a local-only file over a union that couldn't be read. That last one needs ErrNotFound (commit 3) to tell "no remote yet, first push" from "storage unreachable" — adapters previously returned provider-specific errors and the caller couldn't distinguish them.

5: the diverged case

Before writing this I checked 1,180 real transcripts. Two findings pull in opposite directions:

• Unioning is structurally safe. 782 (66%) already contain a fork — a parentUuid with two children — and Claude Code reads them fine. Records carry their own parent pointers, so a uuid-keyed union yields a valid DAG regardless of append order.
• But transcripts aren't uniformly append-only. Six record types (mode, custom-title, ai-title, permission-mode, last-prompt, worktree-state) are mutable last-wins state with no uuid and — across all 12,679 of them — no timestamp. A naive line-union can therefore place an older state record last and silently resurrect a stale mode or title.

So events union by uuid, and each side's final state record per type is compared as a whole, with file-level times breaking the tie (LastModified is upload time and lags the write, so near-ties resolve in the remote's favour — bounded and self-correcting). Merge failure degrades to the legacy .conflict path.

6: desktop sidebar

The desktop app renders its sidebar from per-machine records at %APPDATA%\Claude\claude-code-sessions\<install-id>\<org-id>\local_*.json, not from ~/.claude/projects. So a machine can receive every transcript, resume any of them from the CLI, and still show an empty sidebar. Records sync under _ccd-sessions/<org-id>/ with the machine-specific install-id deliberately left out of the key, merged last-writer-wins by the record's own lastActivityAt.

Details that cost me time and are easy to miss: MSIX-packaged installs redirect the Roaming path somewhere os.Stat can't traverse, so the Local\Packages glob is also probed; trust state is deliberately not synced because it gates hook execution and a compromised bucket must not be able to pre-trust projects; records are normalised in transit (sorted keys, machine-local permission fields stripped) so they don't ping-pong; writes are atomic because the app may be reading. Machines without the desktop app skip silently.

This is the most separable commit — happy to pull it out if you'd rather land the data-safety fixes alone.

Notes on the diff

Two existing tests were retargeted, not weakened. TestPullDetectsConflicts and TestConflictCreatesConflictFile used history.jsonl as the vehicle for the generic conflict machinery, which by design no longer conflicts after commit 4. Every assertion is byte-for-byte unchanged; only the file under test moved to settings.json, with a comment explaining why.

DetectChanges skips the CCD prefix: those records are tracked in state but live outside claudeDir, so without it the first push would report them as deletions and prune them from the bucket.

Scope: 18 files, +2472/-35. Nothing outside internal/, plus 16 lines in cmd/claude-sync/main.go for commit 7. No changes to config defaults, crypto, or the installer.

Tests: go vet ./... and go test ./... green on Linux/ext4 across all 12 packages, with roughly 40 new cases. I don't think CI has run here — the workflow doesn't appear to trigger on fork PRs without approval — so that's local verification, not GitHub's.

[tawanorg]

Thanks for this — the substance here (append-only transcript conflict resolution, union-merging history.jsonl instead of last-writer-wins, not syncing per-machine debris, typed ErrNotFound) is the right set of problems to be solving, and this is the only one of the three desktop-sync PRs that still merges clean.

Not merging it in this pass, and I want to be straight about why: it isn't a judgement on the code, which I haven't reviewed line by line yet. It's that this PR restructures the most data-sensitive logic in the repo — conflict resolution, history merge, session merge, state tracking — across 18 files, and that deserves a focused review rather than riding along in a backlog sweep. For calibration, #82 landed earlier today: 4 files, 324 lines, and it still took three review rounds and seven confirmed defects, two of which would have corrupted users' transcripts.

One thing you should know, since it affects sequencing: #86 contains this PR's seven commits verbatim, by SHA, plus 16 of its own. So #86 is this work extended rather than a competing approach. The plan is to land #77 first and have #86 rebase onto it — that keeps attribution with you and shrinks #86 to something reviewable.

Tracking the sequencing and the review in #91.

Nothing needed from you right now; this stays open and is next in line for a proper review. If you'd like to make that easier, splitting the storage ErrNotFound commit (f84476ed) out as its own PR would let that land independently, since it's additive and low-risk on its own.