fix(cli): invalidate the local data-plane room on doc unload [risk:high]

[zxch3n]

Risk: 🔴 high | Confidence: medium — forced 🔴 by CRDT/sync. Every mechanism here is now covered by a test verified by mutation, but the end-to-end symptom has not been reproduced in a running app, and residual holes found by review are documented below rather than fixed.

What was broken

repo.unloadDoc(docId) evicts the doc from loro-repo's instance cache, so the next
openPersistedDoc returns a different LoroDoc. LocalLoroDataPlaneServer resolves a
room's doc once (buildDocRoom) and holds that object while the room has subscribers.
A renderer with the session open keeps the room alive, so after an unload the room keeps
importing/exporting an orphan: renderer uploads never reach the CLI, CLI writes are never
pushed, the room still reports joined, and the 60s idle watchdog cannot notice because relay
pings are answered in parseLine before the room message chain. Re-joining does not repair
it either — ensureRoom returns the cached entry.

Session GC evicts a session idle for 20 min (cleanSessionForGC -> cleanSessionDoc ->
SessionDocument.destroy() -> repo.unloadDoc). On 2026-08-07 a session was GC'd at 06:19:55
and the user's next two turns (06:22:58, 06:25:03) never synced to the CLI. TurnHistoryGate
held the whole reply for its full 20s bound and then flushed 61 and 198 ACP updates in a single
batch each — nothing on screen for 20s, then the entire reply at once. The cloud transport
normally masks this; it was failing in the same window.

The change

• LocalLoroDataPlaneServer.invalidateDocRoom(docId) — publishes a terminal room status,
  unsubscribes the stale doc, drops the room so the next join rebuilds it against the fresh
  instance, and bumps a per-room-key generation so a build already inside ensureRoom discards
  itself instead of installing the evicted instance.
• LoroDocumentManager.unloadDocRoom(docId) — the single entry point. SessionDocument
  receives it by injection and no longer reaches for repo.unloadDoc, so the unload and the
  invalidation cannot be separated.

Update 2 — recovery is now room-scoped (09562db)

LocalLoroTransportAdapter did not act on a server-pushed terminal room status, so recovery ran
entirely through the workspace reconnect loop. That made one dead room cost a workspace-wide
reconcile — release every idle document store, rejoin every local room, and charge a backoff step
forgiven only after 30s of health. A session being GC'd is routine, so repeated invalidations
would ratchet local reconnect latency workspace-wide (the post-sleep reconnect-storm shape). The
adapter now re-joins that one room itself; the status stays terminal so the loop remains a
backstop.

The F9 tests no longer call adapter.reconnect() by hand — they assert recovery happens with
nobody driving it. Removing the self-repair fails 2 of 3 component tests and 2 F9 cases.

Two test-quality findings from the same review are also fixed: the single-entry-point guard had a
tautological line-number assertion, and a load-bearing comment in the CLI integration test
described a wait that does not actually cover what it claimed.

Update 1 — the post-install window (d3b13a0)

The re-review found the generation guard closed only half the race, and that the residual
half fails worse than the original bug: an invalidation landing between rooms.set and the
awaiting caller resuming hands back a dead entry, handleJoin registers the peer on it,
buildJoinReplyFrames finds no room and emits nothing — the client parks on connecting
forever, which is not terminal, so the reconnect loop never fires. handleUpdate had the same
window (import into the evicted doc on an unsubscribed entry). Fixed by re-reading this.rooms
in one synchronous block with the use, in both handlers — a helper does not work, because
returning from it is itself an await that reopens the window.

Also reversed the teardown order in SessionDocument.destroy: release the repo room before
evicting the doc, since loro-repo binds the instance into a room's transport attachment at attach
time and unloadDoc does not detach rooms. Free — the preceding setStatus writes the meta room,
not this doc's room — and it matches what the renderer already does in store-ref-tracker.ts.

The regression test sweeps the invalidation across fixed microtask depths instead of guessing the
distance, and asserts the invariant that actually matters: a joining peer is never left silent
(it gets either its joined reply or a terminal room-status). Five of eight depths fail without
the fix. Two earlier versions of this test passed with the fix removed and were discarded — one
re-read the doc map after its gate so the race could not manifest, the other fired before the
install and only re-covered the generation path.

Three things the first review corrected, each worth reading

1. The status value is load-bearing. The first version published reconnecting. Only
disconnected/error are terminal in createRoomSyncTracker.needsReconnect(), and that
predicate is what roomSyncRegistry.anyNeedsReconnect() — hence
createLocalReconnectLoop({ hasProblem }) — gates on. reconnecting reads as "already
recovering", so the loop never fired. Inbound sync was unaffected (the next join/update rebuilds
the room), which is exactly why the 20s freeze looked fixed while a renderer that was only
reading a session would have gone permanently stale.

2. ensureRoom had to become generation-aware. invalidateDocRoom only inspected
this.rooms, so a build still resolving its doc was invisible to it: the lookup missed, nothing
was published, and the build then installed a room bound to the just-evicted instance — the
original bug with no recovery signal. Reachable because unloadDocRoom awaits
repo.unloadDoc before invalidating.

3. Invalidation runs after the unload on purpose. Before it, a racing join re-opens the doc
into the repo cache just in time to be stranded again, silently. After it, updates can be lost in
a millisecond-wide window — and those are re-uploaded by the peer's next join reconciliation
(handleJoined -> flushLocal({ force: true })), which is now pinned by a test.

Verification

Every test below was verified by mutation — fix neutered, test observed failing, fix restored:

• packages/components/tests/local-data-plane-room-invalidation-reconnect.test.ts drives the
  real chain: engine -> room-status frame -> LocalLoroTransportAdapter -> real
  createRoomSyncTracker -> real createRoomSyncRegistry -> the exact predicate the reconnect
  loop gates on. Plus a negative control pinning that reconnecting does not wake it. The
  existing data-plane suite passed with defect 1 present precisely because it calls
  adapter.reconnect() by hand instead of exercising the trigger; that line now says so.
• apps/cli/tests/loro-doc-unload-data-plane-integration.test.ts exercises the real seam against
  a real LoroRepo with SQLite storage: session GC -> unloadDocRoom -> a renderer-authored
  upload must reach getSessionHistorySnapshot, and the peer must receive a terminal room status.
• packages/shared/tests/local-loro-transport-bug-repro.test.ts F9: orphaned-room reproduction,
  both-directions recovery, recovery of an upload lost in the eviction window, and the in-flight
  build race.
• apps/cli/tests/loro-doc-unload-invalidates-data-plane.test.ts — guardrail keeping
  repo.unloadDoc to one call site with invalidateDocRoom on the next line.
• typecheck clean for @lody/shared, @lody/components, apps/cli; oxlint 0 errors;
  prettier clean. Pre-existing failures on this base, confirmed by re-running with the change
  stashed: local-ipc (1), loro-streams (2), sqlite-repo-store (1), and 26 in
  packages/components (27 without this change — the difference is this PR's own new test).

Known holes NOT fixed here

• The tracker's transport binding is pinned at join time (create-workspace-runtime.ts,
  acknowledged in a comment there). A room that joined while ownership was unknown (cloud-only
  route) and gained its local member later keeps watching the cloud binding, so it never sees the
  local disconnected. Pre-existing.
• RoomTransportBinding.onStatusChange does not replay the current status and emit dedupes,
  so a tracker attaching after the emit reads null and markFirstSynced() can then paint it
  synced. The new component test attaches to the adapter subscription, which does replay, so
  it cannot catch this. Raising fidelity means driving
  repo.joinDocRoom(...).subscription('local').
• Flock rooms have no invalidateFlockRoom. buildFlockRoom caches entry.flock the same
  way. No CLI caller evicts a flock today, but loro-repo's FlockHydrator can dropFlockDoc on a
  remote purge without any app call.
• repo.unloadDoc does not detach loro-repo's own rooms. doAttachRoomTransport binds the
  doc instance at attach time, so any still-joined room — including the cloud transport — keeps
  syncing the orphan. Same bug one layer lower; not addressed here.

Reported separately (same bug class, out of scope)

• getSessionHistorySnapshot builds a temporary SessionDocument for a session that may already
  have a live one; its destroy() unloads the shared doc and strands the live one. Currently
  unreachable — the only caller (session-export) runs one-shot with no live session docs.
• operation-coordinator.ts (targetSubscriptions) and session-dispatch-watcher.ts
  (watchedSessions) hold mirror.subscribe behind sticky has(sessionId) guards that
  cleanSessionDoc never clears, so after any foreign clean they never re-subscribe to the new
  Mirror. Operation delivery and dispatch reconciliation go silently deaf for that session until
  daemon restart.

Not done

• The risk:high adversarial pipeline is run. Four independent review passes (correctness/
  races, repo-wide bug-class sweep, an adversarial re-review of the fixes, and a fourth round on
  the result) produced every correction above. Three of those rounds each found a real defect,
  two of them in fixes written to address an earlier finding.
• Three attempts at the race regression test passed with the fix removed and were discarded
  before landing one that does not. Every test in this PR is mutation-verified. Independent review agents covered
  correctness/races and a repo-wide sweep for this bug class, and their findings produced the
  three corrections above. A re-review of the fixes themselves was still in flight when this body
  was written; anything it surfaces will be pushed as a follow-up commit.
• No real-app verification. The originating symptom has not been reproduced end to end in a
  running Lody. That is why Confidence is medium, not high.

Note: this repository has no risk:* labels defined, so the tier is carried by the title tag and
this line only.

🤖 Generated with Claude Code