@mirrowel/opencode-openshare 0.1.1 → 0.2.0-dev.2

package/src/core.ts

@@ -43,8 +43,11 @@
 //    secret must never reach viewers.
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { createHash } from "node:crypto"
 import { join } from "node:path"
 import { METADATA_KEY, loadConfig, resolveShareMode, spoolDirFor, URL_FILE_NONE, resolveServer, saveServerToken, type ShareConfig, type ShareMode, type ServerEntry } from "./config.js"
+import { CONTRACT_VERSION, cursorFor, isV2NativeMessage, messageTombstone, normalizeV1Diff, normalizeV1Message } from "./contract.js"
+import { queueBindingWrite } from "./binding-queue.js"
 
 // --- minimal structural types (hand-written: the standalone bundle must
 // not depend on the plugin SDK at runtime; shapes verified against
@@ -106,13 +109,21 @@ type RemoteState = {
   initTimer: ReturnType<typeof setTimeout> | null
   initWasAttach: boolean
   backoff: number
+  /** deferred backoff reset: released after 30s of socket stability or a
+   * second acked sync — never right after init (init-then-drop servers
+   * would cycle at 1/s otherwise) */
+  backoffResetTimer: ReturnType<typeof setTimeout> | null
   reconnectTimer: ReturnType<typeof setTimeout> | null
   intentionalClose: boolean
   connectQueued: boolean
   /** identity dead-end for THIS server (frozen owner, unenrollable
    * private server): stop reconnecting it; other servers unaffected. */
   authBlocked: boolean
-  pending: Array<{ items: unknown[]; status: string }> // frames awaiting ack (spool)
+  pending: Array<{ items: unknown[]; status: string; seq?: number; wire?: string }> // chunk-frames awaiting ack (spool; wire = prebuilt frame string)
+  frozenRemote?: boolean // server froze the owner mid-session: stop writing
+  spoolAppendFailed?: boolean // last append errored: memory-only frame exists
+  spoolSaveTimer: ReturnType<typeof setTimeout> | null // debounced ack-path spool rewrite
+  authWaiter?: (() => void) | undefined // frame-auth handshake resolver
   announced: boolean
   settleTimer: ReturnType<typeof setTimeout> | null
   idleDropTimer: ReturnType<typeof setTimeout> | null
@@ -148,6 +159,16 @@ type SessionState = {
   /** any remote completed a handshake — used to detect LATER creates
    * (fan-out adds, post-mismatch recreates) which need a history backfill */
   everConnected: boolean
+  /** contract v2 merge state: v1 hosts stream parts separately; the v2
+   * item embeds content, so the engine holds the assembled view per
+   * message and re-emits the normalized whole on every update */
+  merged: Map<string, { info?: Record<string, unknown>; parts: Map<string, Record<string, unknown>> }>
+  /** content hash of the LAST item enqueued per key: identical re-feeds
+   * (v2 hosts re-sync the whole transcript on every refresh; unchanged
+   * session info on every session.updated) are skipped instead of being
+   * flushed to every remote, bumping rev and re-folding every viewer.
+   * Cleared on activation — re-activation re-backfills by design. */
+  sentHash: Map<string, string>
 }
 
 type Message = { info?: Record<string, unknown>; parts?: Record<string, unknown>[] }
@@ -239,10 +260,11 @@ type ItemEntry = { key: string; item: Record<string, unknown> }
 function itemFor(type: string, data: unknown, sessionID: string): ItemEntry | undefined {
   if (type === "model") return { key: `model/${sessionID}`, item: { type, sessionID, data } }
   if (type === "prefs") return { key: "prefs", item: { type, data } }
-  if (type === "session") return { key: `session/${(data as SessionInfo)?.id ?? ""}`, item: { type, data } }
-  if (type === "message") return { key: `message/${(data as MessageInfo)?.id ?? ""}`, item: { type, data } }
-  if (type === "part")
-    return { key: `part/${(data as PartInfo)?.messageID ?? ""}/${(data as PartInfo)?.id ?? ""}`, item: { type, data } }
+  if (type === "session") return { key: `session/${(data as SessionInfo)?.id ?? ""}`, item: { type, sessionID, data } }
+  // v2 messages carry no sessionID inside data (v1 infos did); the item
+  // envelope stamps it so multi-session folds (parent + subagents) can
+  // group without guessing
+  if (type === "message") return { key: `message/${(data as MessageInfo)?.id ?? ""}`, item: { type, sessionID, data } }
   if (type === "session_diff") return { key: `session_diff/${sessionID}`, item: { type, sessionID, data } }
   return undefined
 }
@@ -414,6 +436,8 @@ export function createEngine(deps: EngineDeps): Engine {
         initTimer: null,
         initWasAttach: false,
         backoff: 1000,
+        backoffResetTimer: null,
+        spoolSaveTimer: null,
         reconnectTimer: null,
         intentionalClose: false,
         connectQueued: false,
@@ -479,12 +503,19 @@ export function createEngine(deps: EngineDeps): Engine {
         if (b && typeof b === "object" && (b as { policy?: unknown }).policy) {
           applyPolicy((b as { policy: unknown }).policy, url)
         }
+        // frame auth capability: the server accepts the token as the
+        // first WS frame — lets us keep it off the query string (proxy
+        // and access logs otherwise capture the full credential)
+        if (b && typeof b === "object" && (b as { frameAuth?: unknown }).frameAuth) {
+          frameAuthUrls.add(url)
+        }
       })
       .catch(() => {
         // unreachable worker: defaults stay; the init ack will correct us
         policyAsked.delete(url)
       })
   }
+  const frameAuthUrls = new Set<string>()
   const wsUrl = (url: string) => url.replace(/^http/, "ws")
 
   // ---- spool root ---------------------------------------------------------
@@ -527,6 +558,8 @@ export function createEngine(deps: EngineDeps): Engine {
     activated: false,
     wroteBinding: false,
     everConnected: false,
+    merged: new Map(),
+    sentHash: new Map(),
   })
 
   const refreshConfig = () => {
@@ -565,6 +598,9 @@ export function createEngine(deps: EngineDeps): Engine {
     }
     st.activated = true
     st.opts = opts
+    // re-activation re-backfills the whole session (unshare -> share
+    // again): the enqueue dedupe must not skip the returning content
+    st.sentHash.clear()
     const gated = mode === "manual" || opts2?.gated === true
     if (gated) {
       // seed the share status from the session's CURRENT state before
@@ -640,26 +676,31 @@ export function createEngine(deps: EngineDeps): Engine {
 
   async function writeMetadata(st: SessionState, value: Record<string, unknown> | null) {
     if (!st.client) return
-    try {
-      const info = unwrap(
-        await st.client.session.get({
-          path: { id: st.sid },
-          ...(deps.directory ? { query: { directory: deps.directory } } : {}),
-        }),
-      )
-      const metadata = { ...(info?.metadata ?? {}) }
-      if (value === null) delete metadata[METADATA_KEY]
-      else metadata[METADATA_KEY] = value
-      unwrap(
-        await st.client.session.update({
-          path: { id: st.sid },
-          body: { metadata },
-          ...(deps.directory ? { query: { directory: deps.directory } } : {}),
-        }),
-      )
-    } catch (e) {
-      log("metadata write failed (spool still covers reconnects):", (e as Error)?.message || e)
-    }
+    // the read-modify-write runs inside the shared per-session queue: the
+    // TUI patches the same metadata (opt-outs, collisions) and interleaved
+    // RMWs silently lose one side's update (see binding-queue.ts)
+    await queueBindingWrite(st.sid, async () => {
+      try {
+        const info = unwrap(
+          await st.client!.session.get({
+            path: { id: st.sid },
+            ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+          }),
+        )
+        const metadata = { ...(info?.metadata ?? {}) }
+        if (value === null) delete metadata[METADATA_KEY]
+        else metadata[METADATA_KEY] = value
+        unwrap(
+          await st.client!.session.update({
+            path: { id: st.sid },
+            body: { metadata },
+            ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+          }),
+        )
+      } catch (e) {
+        log("metadata write failed (spool still covers reconnects):", (e as Error)?.message || e)
+      }
+    })
   }
 
   /** Parse the metadata binding: v2 map ({v:2, servers:{url:{id,secret,
@@ -770,12 +811,51 @@ export function createEngine(deps: EngineDeps): Engine {
   const spoolSave = (st: SessionState, r: RemoteState) => {
     try {
       writeFileSync(metaPath(st, r.url), JSON.stringify({ shareId: r.shareId, secret: r.secret, ackedRev: r.ackedRev, sid: st.sid, url: r.url }))
-      writeFileSync(queuePath(st, r.url), r.pending.map((f) => JSON.stringify(f)).join("\n") + (r.pending.length ? "\n" : ""))
+      // the queue line IS the wire frame when prebuilt (single
+      // serialization end-to-end); a pending frame without wire (legacy
+      // spool load) serializes here
+      writeFileSync(queuePath(st, r.url), r.pending.map((f) => f.wire ?? JSON.stringify(f)).join("\n") + (r.pending.length ? "\n" : ""))
+      // the migrated content now lives in the new queue (or was acked):
+      // retire the single-server-era files so they don't accumulate forever
+      rmSync(legacyMetaPath(st), { force: true })
+      rmSync(legacyQueuePath(st), { force: true })
     } catch (e) {
       logError("spool save failed", (e as Error)?.message || e)
     }
   }
+  // hot path: appending one pending frame must not re-serialize the whole
+  // queue (O(n^2) during backfill bursts) — append the line instead
+  const spoolAppend = (st: SessionState, r: RemoteState, f: { items: unknown[]; status: string; seq?: number; wire?: string }) => {
+    try {
+      appendFileSync(queuePath(st, r.url), (f.wire ?? JSON.stringify(f)) + "\n")
+    } catch (e) {
+      // the frame lives ONLY in memory now — flag the remote so the next
+      // spoolLoad does NOT replace in-memory pending with the shorter
+      // disk queue (silent loss otherwise; live-caught class in review)
+      r.spoolAppendFailed = true
+      logError("spool append failed", (e as Error)?.message || e)
+    }
+  }
+  /** Debounced ack-path spool rewrite: one ack per chunk during a
+   * multi-chunk replay each rewrote the WHOLE queue file (O(n^2) —
+   * ~160MB of sync disk churn on a 25-chunk outage recovery). A crash
+   * inside the 300ms window only loses "these frames were acked" — the
+   * next connect replays idempotent keyed upserts, which the protocol
+   * already tolerates. init-ok keeps the immediate save (binding/
+   * recovery info). */
+  const scheduleSpoolSave = (st: SessionState, r: RemoteState) => {
+    if (r.spoolSaveTimer) return
+    r.spoolSaveTimer = setTimeout(() => {
+      r.spoolSaveTimer = null
+      if (!st.closed) spoolSave(st, r)
+    }, 300)
+  }
   const spoolLoad = (st: SessionState, r: RemoteState) => {
+    // meta first (share binding recovery), in its OWN try: a missing meta
+    // file is normal (it's only written after the first successful
+    // handshake) and must NOT touch pending (live-caught class: the old
+    // blanket catch wiped in-memory pending AND skipped the queue read,
+    // so everything queued before the first successful connect was lost).
     try {
       const meta = JSON.parse(readFileSync(metaPath(st, r.url), "utf8"))
       // metadata binding (db) is authoritative when both exist and disagree
@@ -784,15 +864,40 @@ export function createEngine(deps: EngineDeps): Engine {
         r.secret = meta.secret
         r.ackedRev = meta.ackedRev ?? 0
       }
+    } catch {}
+    try {
       if (existsSync(queuePath(st, r.url))) {
-        r.pending = readFileSync(queuePath(st, r.url), "utf8")
-          .split("\n")
-          .filter((l) => l.trim())
-          .map((l) => JSON.parse(l))
+        // append-only spool: a crash mid-append can tear the LAST line —
+        // keep the valid prefix instead of dropping the whole queue.
+        // The disk queue is the authority: every in-memory frame was
+        // appended before it was tracked, so replacing pending with the
+        // parsed queue loses nothing. A FAILED read keeps in-memory
+        // pending untouched.
+        const disk: Array<{ items: unknown[]; status: string; seq?: number }> = []
+        for (const line of readFileSync(queuePath(st, r.url), "utf8").split("\n")) {
+          if (!line.trim()) continue
+          try {
+            disk.push(JSON.parse(line))
+          } catch {
+            log(`spool load: dropped torn tail line for ${st.sid.slice(0, 18)}`)
+            break
+          }
+        }
+        // seq hygiene: re-stamp pre-seq spool lines (an ack without seq
+        // would otherwise clear ALL pending — the H2 wipe, once per
+        // upgrade) and seed the counter past every restored seq (a
+        // restart resetting to 0 would collide new frames with old ones)
+        for (const f of disk) {
+          if (typeof f.seq !== "number") f.seq = ++nextSeq
+          else if (f.seq >= nextSeq) nextSeq = f.seq + 1
+        }
+        // a failed append means the disk queue can be SHORTER than
+        // memory — the disk is only authoritative when every append
+        // landed (otherwise the replace would drop the memory-only frame)
+        if (!r.spoolAppendFailed) r.pending = disk
+        else r.spoolAppendFailed = false
       }
-    } catch {
-      r.pending = []
-    }
+    } catch {}
     // single-server-era spool (no url suffix): belongs to the first target
     if (!r.shareId && targets[0]?.url === r.url) {
       try {
@@ -814,12 +919,27 @@ export function createEngine(deps: EngineDeps): Engine {
   }
   const spoolClear = (st: SessionState, r: RemoteState) => {
     try {
+      if (r.spoolSaveTimer) {
+        clearTimeout(r.spoolSaveTimer)
+        r.spoolSaveTimer = null
+      }
       rmSync(metaPath(st, r.url), { force: true })
       rmSync(queuePath(st, r.url), { force: true })
+      // single-server-era files die with the session too
+      rmSync(legacyMetaPath(st), { force: true })
+      rmSync(legacyQueuePath(st), { force: true })
     } catch {}
   }
 
   // ---- websocket transport (per remote) ----------------------------------
+  /** Monotonic client frame sequence: every chunk-frame gets one; the
+   * server echoes it in the ack, and the plugin clears exactly that
+   * chunk from pending. (Live-caught class: one logical frame split into
+   * N chunks — the worker acks EACH chunk, and a blanket "pending = []"
+   * on the first ack erased chunks 2..N; a socket death right there lost
+   * them permanently.) */
+  let nextSeq = 0
+
   const wsSend = (r: RemoteState, obj: unknown) => {
     if (debugEvents) log(`ws ${r.url.slice(0, 24)} #${r.socketSeq} send ${(obj as { op?: string })?.op} (ready=${r.wsReady})`)
     try {
@@ -830,15 +950,66 @@ export function createEngine(deps: EngineDeps): Engine {
     return true
   }
 
-  /** Sync frames are chunked (~1MB WS cap on CF; a 5000-message backfill
-   * must ride several frames — worker apply is keyed-idempotent, chunks
-   * just bump rev). Status rides each chunk; last write wins. */
-  const SYNC_CHUNK = 200
-  const sendSync = (r: RemoteState, f: { items: unknown[]; status: string }) => {
-    if (!f.items.length) return wsSend(r, { op: "sync", items: [], status: f.status })
-    for (let i = 0; i < f.items.length; i += SYNC_CHUNK) {
-      wsSend(r, { op: "sync", items: f.items.slice(i, i + SYNC_CHUNK), status: f.status })
+  /** Sync frames are chunked by BOTH item count and serialized bytes.
+   * Count-only chunking could pack 200 large tool outputs into a frame
+   * that exceeds the server's WS receive cap (CF 32 MiB, Bun 16 MB
+   * default) and die wholesale. Budget keeps every frame cheap to apply
+   * and rebroadcast; worker apply is keyed-idempotent, so chunks just
+   * bump rev. An item larger than the whole budget rides alone in its
+   * own frame (the worker fits oversize items to its storage cap).
+   * Status rides each chunk; last write wins.
+   * Returns each chunk's PREBUILT items JSON: the wire frame and the
+   * spool line are derived from it by concatenation — every item used
+   * to be serialized 3-5x per remote per flush (chunk measure, spool
+   * append, ws send, sendSync re-chunk). */
+  const chunkedFrames = (items: unknown[], maxItems: number, maxBytes: number): Array<{ items: unknown[]; json: string }> => {
+    const chunks: Array<{ items: unknown[]; json: string }> = []
+    let cur: unknown[] = []
+    let curJson: string[] = []
+    let curBytes = 0
+    for (const it of items) {
+      const j = JSON.stringify(it) ?? "null"
+      if (cur.length && (cur.length >= maxItems || curBytes + j.length > maxBytes)) {
+        chunks.push({ items: cur, json: "[" + curJson.join(",") + "]" })
+        cur = []
+        curJson = []
+        curBytes = 0
+      }
+      cur.push(it)
+      curJson.push(j)
+      curBytes += j.length
+    }
+    if (cur.length) chunks.push({ items: cur, json: "[" + curJson.join(",") + "]" })
+    return chunks
+  }
+  /** legacy chunker (count/byte split without prebuilt JSON) — replay
+   * paths that only need the split */
+  const chunkItems = (items: unknown[], maxItems: number, maxBytes: number): unknown[][] =>
+    chunkedFrames(items, maxItems, maxBytes).map((c) => c.items)
+  /** the wire sync frame, built by concatenation over the prebuilt items
+   * JSON — byte-identical to JSON.stringify({op,items,status,seq}) */
+  const syncFrameStr = (itemsJson: string, status: string, seq: number | undefined) =>
+    `{"op":"sync","items":${itemsJson},"status":${JSON.stringify(status)}${seq !== undefined ? `,"seq":${seq}` : ""}}`
+  const wsSendRaw = (r: RemoteState, s: string) => {
+    if (debugEvents) log(`ws ${r.url.slice(0, 24)} #${r.socketSeq} send raw (${Math.round(s.length / 1024)}KB, ready=${r.wsReady})`)
+    try {
+      r.ws?.send(s)
+    } catch {
+      return false
+    }
+    return true
+  }
+  const sendSync = (r: RemoteState, f: { items: unknown[]; status: string; seq?: number; wire?: string }) => {
+    if (!f.items.length) return wsSend(r, { op: "sync", items: [], status: f.status, seq: f.seq })
+    // prebuilt wire (the hot flush path): one serialization total
+    if (f.wire) return wsSendRaw(r, f.wire)
+    // replayed/legacy frames: chunk-shaped by construction — only an
+    // oversize one (a pre-chunking spool line) needs re-splitting
+    const itemsJson = JSON.stringify(f.items)
+    if (f.items.length <= 200 && itemsJson.length <= 512 * 1024) {
+      return wsSendRaw(r, syncFrameStr(itemsJson, f.status, f.seq))
     }
+    for (const c of chunkedFrames(f.items, 200, 512 * 1024)) wsSendRaw(r, syncFrameStr(c.json, f.status, f.seq))
     return true
   }
 
@@ -1017,7 +1188,12 @@ export function createEngine(deps: EngineDeps): Engine {
         logError(`sharing to ${r.url} disabled (no credential): ${cred.error}`)
         return
       }
-      const ws = new WebSocket(`${wsUrl(r.url)}/api/ws?token=${encodeURIComponent(token ?? "")}`)
+      // frame auth: when the server advertises it, keep the token off the
+      // URL (query strings land in proxy/access logs). The auth frame
+      // rides the socket in order — the server sets its identity before
+      // our init arrives. Old servers fall back to ?token=.
+      const useFrameAuth = !!token && frameAuthUrls.has(r.url)
+      const ws = new WebSocket(`${wsUrl(r.url)}/api/ws${useFrameAuth ? "" : `?token=${encodeURIComponent(token ?? "")}`}`)
       r.ws = ws
       await new Promise((resolve, reject) => {
         const t = setTimeout(() => reject(new Error("ws open timeout")), 15000)
@@ -1055,6 +1231,31 @@ export function createEngine(deps: EngineDeps): Engine {
         if (!st.closed) scheduleReconnect(st, r)
       })
 
+      if (useFrameAuth) {
+        wsSend(r, { op: "auth", token })
+        // the auth and init frames can interleave in the worker's
+        // concurrent webSocketMessage invocations — wait for the authed
+        // ack before authenticating anything (timeout -> fall back to a
+        // query-token reconnect)
+        const authed = await new Promise<boolean>((resolve) => {
+          const t = setTimeout(() => resolve(false), 3000)
+          r.authWaiter = () => {
+            clearTimeout(t)
+            resolve(true)
+          }
+        })
+        r.authWaiter = undefined
+        if (!authed) {
+          logError(`ws ${r.url.slice(0, 24)}: frame-auth ack timeout - reconnecting with query token`)
+          frameAuthUrls.delete(r.url)
+          try {
+            ws.close(4000, "auth timeout")
+          } catch {}
+          if (!st.closed) scheduleReconnect(st, r)
+          return
+        }
+      }
+
       if (r.initWasAttach) {
         wsSend(r, { op: "init", attach: { id: r.shareId, secret: r.secret, ...authFrame(st) } })
       } else {
@@ -1084,7 +1285,9 @@ export function createEngine(deps: EngineDeps): Engine {
 
   const scheduleReconnect = (st: SessionState, r: RemoteState) => {
     if (st.closed || r.reconnectTimer) return
-    const wait = r.backoff
+    // jitter (±20%) so fan-out remotes and multiple sessions never sync
+    // their retry storms onto the same second
+    const wait = Math.max(250, Math.round(r.backoff * (0.8 + Math.random() * 0.4)))
     r.backoff = Math.min(r.backoff * 2, 60000)
     r.reconnectTimer = setTimeout(() => {
       r.reconnectTimer = null
@@ -1170,6 +1373,15 @@ export function createEngine(deps: EngineDeps): Engine {
   }
 
   const handleFrame = async (st: SessionState, r: RemoteState, frame: Record<string, unknown>) => {
+    if (frame.op === "authed") {
+      // frame-auth handshake ack: release the init (the auth and init
+      // frames can interleave server-side — webSocketMessage invocations
+      // run concurrently — so the init must WAIT for this, else it
+      // authenticates as anonymous/tokenless)
+      r.authWaiter?.()
+      r.authWaiter = undefined
+      return
+    }
     if (frame.op === "init") {
       if (!frame.ok) {
         const err = String(frame.error ?? "")
@@ -1223,6 +1435,19 @@ export function createEngine(deps: EngineDeps): Engine {
         // bad base (mismatch protocol). Content REPLAYS to the new share —
         // pending is never dropped on a reset (live-caught: the recreate
         // husk had the title but zero messages).
+        if (/limit|too many|rate/i.test(err)) {
+          // quota/429 ("max shares reached", "daily create limit", the
+          // anonymous caps): an immediate re-init on the same socket is a
+          // hot loop against the server — back off through the normal
+          // reconnect cadence instead
+          logError(`${r.url}: create refused:`, frame.error, "- retrying with backoff")
+          r.connecting = false
+          try {
+            r.ws?.close(4000, "rate limited")
+          } catch {}
+          if (!st.closed) scheduleReconnect(st, r)
+          return
+        }
         logError(`${r.url}: init refused:`, frame.error, "- creating fresh share")
         deleteAbandoned(r)
         r.shareId = null
@@ -1253,11 +1478,23 @@ export function createEngine(deps: EngineDeps): Engine {
       r.connecting = false
       r.initWasAttach = false
       r.collided = null
+      // a successful handshake proves write access: an admin unfreeze
+      // revives the remote from here (frozenRemote is otherwise sticky)
+      if (r.frozenRemote && !frame.error) r.frozenRemote = false
       if (r.initTimer) {
         clearTimeout(r.initTimer)
         r.initTimer = null
       }
-      r.backoff = 1000
+      // backoff reset is DEFERRED until the socket proves stable: a
+      // server that accepts init then immediately drops would otherwise
+      // reconnect once per second forever (~1 cycle/s per session-server
+      // pair, live-caught in the optimization audit). 30s alive (socket
+      // still ready, no reconnect pending) or a second acked sync.
+      if (r.backoffResetTimer) clearTimeout(r.backoffResetTimer)
+      r.backoffResetTimer = setTimeout(() => {
+        r.backoffResetTimer = null
+        if (r.wsReady && !r.reconnectTimer) r.backoff = 1000
+      }, 30000)
       st.everConnected = true
       if (frame.policy) applyPolicy(frame.policy, r.url)
       r.intentionalClose = false
@@ -1279,19 +1516,67 @@ export function createEngine(deps: EngineDeps): Engine {
       if (wasFanoutCreate) {
         // a server joined an ALREADY-live session (fan-out add, or a
         // post-mismatch recreate): its fresh share needs the full history —
-        // backfill is keyed-idempotent, other servers just re-upsert
+        // backfill is keyed-idempotent, other servers just re-upsert.
+        // The enqueue dedupe must step aside: those hashes say "already
+        // entered the machinery", but the NEW remote never received any
+        // of it (live-caught by F3: the join's backfill was fully
+        // deduped away and the joined share stayed empty).
+        st.sentHash.clear()
         chain = chain.then(() => backfill(st)).catch((e) => logError("fan-out backfill error", (e as Error)?.message || e))
       }
       return
     }
     if (frame.op === "ack") {
       r.ackedRev = (frame.rev as number) ?? r.ackedRev
-      r.pending = []
-      spoolSave(st, r)
+      // a second acked sync also proves the socket stable — release the
+      // backoff reset timer early (complements the 30s-alive timer)
+      if (r.backoffResetTimer) {
+        clearTimeout(r.backoffResetTimer)
+        r.backoffResetTimer = null
+        r.backoff = 1000
+      }
+      // seq-scoped retirement: an ack identifies the chunk it applied.
+      // An ack WITHOUT seq = old server: legacy clear-all (correct there —
+      // old servers acked the whole pending batch together).
+      if (typeof frame.seq === "number") {
+        r.pending = r.pending.filter((p) => p.seq !== frame.seq)
+      } else {
+        r.pending = []
+      }
+      scheduleSpoolSave(st, r)
       scheduleBindingWrite(st)
       return
     }
     if (frame.op === "nack" || frame.op === "error") {
+      const errText = String(frame.error ?? "")
+      if (frame.op === "nack") {
+        // classify: the share dying server-side under a live socket
+        // (sweeper TTL, admin delete, purge) surfaces as nacks — the
+        // socket is "healthy" so nothing else recovers it. Same reset as
+        // the init-refused path: fresh create + content replay.
+        if (/not found|gone/i.test(errText)) {
+          logError(`${r.url}: share vanished server-side (nack: ${errText}) - recreating`)
+          deleteAbandoned(r)
+          r.shareId = null
+          r.secret = null
+          r.ackedRev = 0
+          try {
+            r.ws?.close(4000, "share gone")
+          } catch {}
+          if (!st.closed) queueConnect(st, r)
+          return
+        }
+        if (/frozen/i.test(errText)) {
+          // owner frozen mid-session: every write is refused. Stop
+          // spooling NEW frames for this remote (unbounded growth) but
+          // KEEP what's already queued — an unfreeze revives the remote
+          // on the next successful handshake (init-ok clears the flag)
+          // and the backlog replays from there.
+          r.frozenRemote = true
+          logError(`${r.url}: share frozen by the hoster - edits refused; contact the server admin`)
+          return
+        }
+      }
       logError(`${r.url}: worker refused frame:`, JSON.stringify(frame).slice(0, 200))
       // the control socket lost its attach state (worker-side eviction of
       // the control DO): force a reconnect — init attach replays pending
@@ -1323,6 +1608,10 @@ export function createEngine(deps: EngineDeps): Engine {
 
   // ---- flush -------------------------------------------------------------
   const frameFrom = (st: SessionState) => {
+    // stamps run at frame time: the whole family's data is indexed by now
+    // (child prompts are created during the task call, well inside the
+    // flush debounce), and any re-enqueued message lands in this frame
+    stampsPass(st)
     const items = Array.from(st.queue.values())
     st.queue.clear()
     const statusChanged = st.status !== st.lastSentStatus
@@ -1344,51 +1633,115 @@ export function createEngine(deps: EngineDeps): Engine {
     if (!f) return
     // fan out to every remote; each carries its own pending copy and acks
     // independently. Remotes mid-handshake or auth-blocked just buffer.
+    // PENDING IS CHUNK-SHAPED (seq-tagged): one logical frame becomes N
+    // chunk-frames so a partial-ack can never erase unsent chunks
+    // (live-caught class: chunk-1 ack + socket death erased chunks 2..N).
+    const chunks: Array<{ items: unknown[]; json: string }> = f.items.length ? chunkedFrames(f.items, 200, 512 * 1024) : []
     let httpWork: Promise<unknown> | undefined
     for (const r of st.remotes.values()) {
+      if (r.frozenRemote) continue // refused server-side; stop spooling
+      const fresh: Array<{ items: unknown[]; status: string; seq: number; wire?: string }> = []
+      if (chunks.length) {
+        for (const c of chunks) {
+          const seq = ++nextSeq
+          const cf = { items: c.items, status: f.status, seq, wire: syncFrameStr(c.json, f.status, seq) }
+          fresh.push(cf)
+          r.pending.push(cf)
+          spoolAppend(st, r, cf)
+        }
+      } else {
+        // status-only frame (empty items): one chunk-less frame
+        const seq = ++nextSeq
+        const cf = { items: [] as unknown[], status: f.status, seq }
+        fresh.push(cf)
+        r.pending.push(cf)
+        spoolAppend(st, r, cf)
+      }
       // never send syncs before the init ack: the worker's per-socket
       // ControlDO has no attach until OUR init completes, and a racing
       // sync dies as "unknown op" (live-caught: post-drop reconnects
       // lost whole turns). The init-ok handler flushes pending itself.
-      r.pending.push(f)
-      spoolSave(st, r)
       if (r.ws && !r.wsReady) continue
       if (r.wsReady) {
-        sendSync(r, f)
+        for (const cf of fresh) sendSync(r, cf)
         continue
       }
       const viaHttp = flushViaHttp(st, r)
       if (viaHttp) httpWork = (httpWork ?? Promise.resolve()).then(() => viaHttp)
     }
     if (st.remotes.size) st.lastFlushAt = Date.now()
+    // the HTTP work runs detached from the flush chain (one dead server
+    // must not stall the fan-out); dispose awaits its own final flush
+    if (httpWork) void httpWork.catch((e) => logError("http flush error", (e as Error)?.message || e))
     return httpWork
   }
 
+  /** Client-side key derivation mirroring the server's itemKey — used only
+   * for deduping the HTTP fallback batch (keyed upserts: the LAST item
+   * for a key wins, matching apply() semantics). */
+  const httpDedupeKey = (it: unknown): string | null => {
+    if (!it || typeof it !== "object") return null
+    const o = it as { type?: string; data?: { id?: string; messageID?: string; sessionID?: string }; sessionID?: string }
+    switch (o.type) {
+      case "session": return "session/" + (o.data?.id ?? "")
+      case "session_diff": return "session_diff/" + (o.sessionID ?? o.data?.sessionID ?? "")
+      case "message": return "message/" + (o.data?.id ?? "")
+      case "part": return "part/" + (o.data?.messageID ?? "") + "/" + (o.data?.id ?? "")
+      case "model": return "model/" + (o.sessionID ?? o.data?.sessionID ?? "")
+      case "prefs": return "prefs"
+      default: return null
+    }
+  }
+
   const flushViaHttp = async (st: SessionState, r: RemoteState) => {
     if (!r.shareId || !r.pending.length) return
     // ALL pending frames, merged (keyed upserts — later wins). Sending
     // only the last frame dropped every earlier batch's items whenever
     // the HTTP fallback carried more than one (live-caught class:
-    // content loss on reconnect paths).
-    const items: unknown[] = []
+    // content loss on reconnect paths). DEDUPE BY KEY before chunking:
+    // a streaming message appearing in k pending frames shipped k
+    // copies (up to 25x on a replay burst) — every duplicate was also a
+    // server row-write + a rebroadcast frame.
+    const byKey = new Map<string, unknown>()
+    const unkeyed: unknown[] = []
     let status: string | undefined
+    const sentSeqs = new Set<number>()
     for (const f of r.pending) {
-      for (const it of f.items as unknown[]) items.push(it)
+      for (const it of f.items as unknown[]) {
+        const k = httpDedupeKey(it)
+        if (k) byKey.set(k, it)
+        else unkeyed.push(it)
+      }
       if (f.status) status = f.status
+      if (typeof f.seq === "number") sentSeqs.add(f.seq)
     }
+    const items = [...byKey.values(), ...unkeyed]
     const cred = credOf(r.url)
-    const res = await fetch(`${r.url}/api/share/${r.shareId}/sync`, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...(cred.credential ? { authorization: `Bearer ${cred.credential}` } : {}) },
-      body: JSON.stringify({ secret: r.secret ?? "", data: items, status }),
-      signal: AbortSignal.timeout(15000),
-    }).catch(() => null)
-    if (res && res.ok) {
+    // chunked like WS frames: one unbounded body is a whole-backlog
+    // bomb after a mid-backfill socket drop (backfill = full history).
+    // Failure stops the loop with pending intact — replaying already-
+    // applied chunks is idempotent.
+    // status-only frames (items empty, e.g. the terminal completed
+    // flush in HTTP-only mode) still need ONE request or the status
+    // never lands (the share stays "live" forever)
+    const chunks = items.length ? chunkItems(items, 500, 4 * 1024 * 1024) : [[]]
+    for (const chunk of chunks) {
+      const res = await fetch(`${r.url}/api/share/${r.shareId}/sync`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(cred.credential ? { authorization: `Bearer ${cred.credential}` } : {}) },
+        body: JSON.stringify({ secret: r.secret ?? "", data: chunk, status }),
+        signal: AbortSignal.timeout(15000),
+      }).catch(() => null)
+      if (!res || !res.ok) return
       const body = (await res.json().catch(() => ({}))) as { rev?: number }
       r.ackedRev = body.rev ?? r.ackedRev
-      r.pending = []
-      spoolSave(st, r)
     }
+    // retire EXACTLY what this run sent: a concurrent flush may have
+    // queued new frames while our fetches were in flight (the HTTP work
+    // is deliberately detached from the flush chain) — a blanket clear
+    // would erase them before anything transmitted them
+    r.pending = r.pending.filter((p) => !sentSeqs.has(p.seq as number))
+    scheduleSpoolSave(st, r)
   }
 
   const scheduleFlush = (st: SessionState) => {
@@ -1403,19 +1756,350 @@ export function createEngine(deps: EngineDeps): Engine {
     st.timer = setTimeout(() => {
       st.timer = null
       if (debugEvents) log(`flush timer fired sid=${st.sid.slice(0, 18)} queue=${st.queue.size} remotes=${st.remotes.size}`)
-      chain = chain.then(() => flush(st)).catch((e) => logError("flush error", (e as Error)?.message || e))
+      // NOTE: the flush's HTTP-fallback promise is deliberately NOT
+      // chained — one black-holing server (15s timeout per chunk) must
+      // not stall every other remote's flushes behind it. Dispose awaits
+      // its own final flush explicitly.
+      chain = chain
+        .then(() => {
+          flush(st)
+        })
+        .catch((e) => logError("flush error", (e as Error)?.message || e))
     }, wait)
   }
 
   const enqueue = (st: SessionState, entry: ItemEntry | undefined) => {
     if (!st || !entry) return
+    // content dedupe at the machinery boundary: an identical re-feed has
+    // either entered the queue already or been flushed into every
+    // remote's pending/spool (the per-remote delivery machinery owns it
+    // from there) — re-sending it bumps rev, rewrites storage and
+    // re-folds every viewer for nothing. This is the engine-side home
+    // the v2-adapter dedupe lacked (an adapter-side cache poisoned while
+    // dormant and skipped the flag-time content — live-caught).
+    let h: string
+    try {
+      h = createHash("sha256").update(JSON.stringify(entry.item)).digest("hex")
+    } catch {
+      h = ""
+    }
+    if (h && st.sentHash.get(entry.key) === h) {
+      if (debugEvents) log(`enqueue dedupe ${entry.item.type} ${entry.key.slice(0, 40)}`)
+      return
+    }
+    if (h) st.sentHash.set(entry.key, h)
     st.queue.set(entry.key, entry.item)
+    indexMessage(entry)
     if (debugEvents) log(`enqueue sid=${st.sid.slice(0, 18)} ${entry.item.type} queue=${st.queue.size}`)
     touch(st)
     ensureConnected(st)
     scheduleFlush(st)
   }
 
+  // ---- authoritative stamps ----------------------------------------------
+  // The viewer renders stamped facts and never re-derives them (owner
+  // directive). Both stamps are computed at frame time across the whole
+  // share family - the engine sees every session of the family regardless
+  // of host generation, so this is the only place with the full picture.
+
+  type IndexedMessage = {
+    sid: string
+    role: string
+    agent?: string
+    created: number
+    data: Record<string, unknown>
+  }
+  const msgIndex = new Map<string, IndexedMessage>() // `${sid}:${messageID}`
+  /** message ids tombstoned this run: stampsPass must never re-upsert an
+   * undone message (live-caught class: dropMergedMessage removed the
+   * merged entry but msgIndex kept the corpse; a neighboring-segment
+   * change recomputed its stamps and reEnqueueMessage resurrected the
+   * deleted turn server-side). */
+  const tombstoned = new Set<string>()
+
+  const indexMessage = (entry: ItemEntry) => {
+    if (entry.item.type !== "message") return
+    const d = entry.item.data as Record<string, any> | undefined
+    if (!d || typeof d.id !== "string") return
+    const role = String(d.type ?? "")
+    if (role !== "user" && role !== "assistant") return
+    const key = `${entry.item.sessionID}:${d.id}`
+    const prev = msgIndex.get(key)
+    msgIndex.set(key, {
+      sid: String(entry.item.sessionID ?? ""),
+      role: role as string,
+      agent:
+        role === "assistant"
+          ? typeof d.agent === "string"
+            ? d.agent
+            : prev?.agent
+          : typeof d.metadata?.agent === "string"
+            ? d.metadata.agent
+            : prev?.agent,
+      created: Number(d.time?.created ?? prev?.created ?? 0),
+      data: d as Record<string, unknown>,
+    })
+  }
+
+  const sessionStateOf = (sid: string): SessionState | undefined =>
+    sessions.get(childToParent.get(sid) ?? sid)
+
+  const reEnqueueMessage = (m: IndexedMessage) => {
+    // tombstone guard: an undone message stays dead even if a stamp pass
+    // recomputes its segment metadata
+    if (tombstoned.has(`${m.sid}:${m.data.id}`)) return
+    const st = sessionStateOf(m.sid)
+    if (st) enqueue(st, itemFor("message", m.data, m.sid))
+  }
+
+  /** segment agent for a user prompt: the prompt's own recorded agent (v1
+   * hosts stamp it on every user message), else the first assistant
+   * response inside the segment (v2 hosts), else carry-forward. */
+  const segmentAgent = (ordered: IndexedMessage[], at: number): string | undefined => {
+    const own = ordered[at]?.agent
+    if (own) return own
+    for (let i = at + 1; i < ordered.length; i++) {
+      if (ordered[i].role === "assistant" && ordered[i].agent) return ordered[i].agent
+      if (ordered[i].role === "user") break // next segment already began
+    }
+    return undefined
+  }
+
+  /** user messages whose segment runs a DIFFERENT agent than the previous
+   * segment carry metadata.agentSwitch = <agent> - the viewer renders the
+   * transition chip from the stamp alone. */
+  const stampAgentSwitches = (bySession: Map<string, IndexedMessage[]>) => {
+    for (const [, list] of bySession) {
+      list.sort((a, b) => a.created - b.created)
+      const users = list.map((m, i) => (m.role === "user" ? i : -1)).filter((i) => i >= 0)
+      let prev: string | undefined
+      for (let k = 0; k < users.length; k++) {
+        const agent = segmentAgent(list, users[k])
+        const d = list[users[k]].data as Record<string, any>
+        const want = k > 0 && agent && prev && agent !== prev ? agent : undefined
+        // only touch metadata when the stamp actually CHANGES — a blanket
+        // `d.metadata ??= {}` polluted every user message (including the
+        // host's live objects on v2 pass-through) with an empty metadata
+        // object, which re-emitted the message once per refresh (rev churn
+        // per feed — live-caught by the enqueue-dedupe rev check)
+        if (want !== (d.metadata?.agentSwitch as string | undefined)) {
+          if (want) {
+            const meta = (d.metadata ??= {}) as Record<string, unknown>
+            meta.agentSwitch = want
+          } else if (d.metadata) {
+            delete d.metadata.agentSwitch
+          }
+          reEnqueueMessage(list[users[k]])
+        }
+        if (agent) prev = agent
+      }
+    }
+  }
+
+  /** task/subagent tool calls get metadata.agent = the agent that actually
+   * ran for THAT call: the child's first prompt created at/after the call
+   * started (v1 prompts carry the agent; v2 resolves via the response).
+   * Rank-free pairing - a resumed child's second call lands on its second
+   * prompt by construction time. */
+  const stampTaskAgents = (bySession: Map<string, IndexedMessage[]>) => {
+    for (const list of bySession.values()) list.sort((a, b) => a.created - b.created)
+    for (const m of msgIndex.values()) {
+      if (m.role !== "assistant") continue
+      const content = (m.data as any).content
+      if (!Array.isArray(content)) continue
+      let mutated = false
+      for (const part of content) {
+        if (!part || part.type !== "tool") continue
+        if (part.name !== "task" && part.name !== "subagent") continue
+        const state = part.state
+        const meta = state?.metadata
+        const childSid = typeof meta?.sessionID === "string" ? meta.sessionID : undefined
+        if (!childSid || typeof meta.agent === "string") continue
+        const partStart = Number(part.time?.created ?? 0)
+        const child = bySession.get(childSid)
+        if (!child) continue
+        let agent: string | undefined
+        for (const c of child) {
+          if (c.created < partStart) continue
+          if (c.role === "user" && c.agent) {
+            agent = c.agent
+            break
+          }
+        }
+        if (!agent) {
+          for (const c of child) {
+            if (c.created < partStart) continue
+            if (c.role === "assistant" && c.agent) {
+              agent = c.agent
+              break
+            }
+          }
+        }
+        if (agent) {
+          meta.agent = agent
+          mutated = true
+        }
+      }
+      if (mutated) reEnqueueMessage(m)
+    }
+  }
+
+  /** file tools get metadata.language (shiki lang id, from the path the
+   * call touched) - the viewer highlights from the stamp and never guesses
+   * (owner directive; the viewer's extension map is an old-share fallback) */
+  const LANG_BY_EXT: Record<string, string> = {
+    ts: "typescript", tsx: "tsx", mts: "typescript", cts: "typescript",
+    js: "javascript", jsx: "jsx", mjs: "javascript", cjs: "javascript",
+    json: "json", jsonc: "json", md: "markdown", mdx: "mdx",
+    py: "python", rs: "rust", go: "go", java: "java", rb: "ruby",
+    css: "css", scss: "scss", html: "html", xml: "xml", yaml: "yaml", yml: "yaml",
+    toml: "toml", sh: "shellscript", bash: "shellscript", ps1: "powershell",
+    sql: "sql", c: "c", h: "c", cpp: "cpp", hpp: "cpp", cs: "csharp",
+    swift: "swift", kt: "kotlin", php: "php", lua: "lua", vue: "vue", svelte: "svelte",
+  }
+  const FILE_TOOLS = new Set(["read", "write", "edit", "patch"])
+  const stampFileLanguages = () => {
+    for (const m of msgIndex.values()) {
+      if (m.role !== "assistant") continue
+      const content = (m.data as any).content
+      if (!Array.isArray(content)) continue
+      let mutated = false
+      for (const part of content) {
+        if (!part || part.type !== "tool") continue
+        if (!FILE_TOOLS.has(part.name)) continue
+        const state = part.state
+        const meta = state?.metadata
+        if (!meta) continue
+        const raw = state.input?.path ?? state.input?.filePath
+        // language stamp (shiki id from the path)
+        if (typeof meta.language !== "string" && typeof raw === "string") {
+          const ext = raw.split(".").pop()?.toLowerCase() ?? ""
+          const lang = LANG_BY_EXT[ext]
+          if (lang) {
+            meta.language = lang
+            mutated = true
+          }
+        }
+        // lineStart stamp: reads sliced from an offset keep REAL file line
+        // numbers in the viewer's unified file card (pierre numbers from 1;
+        // the viewer shifts by this stamp, authoritatively)
+        if (typeof meta.lineStart !== "number" && part.name === "read") {
+          const off = state.input?.offset
+          if (typeof off === "number" && off >= 0 && off > 0) {
+            meta.lineStart = off + 1
+            mutated = true
+          }
+        }
+      }
+      if (mutated) reEnqueueMessage(m)
+    }
+  }
+
+  const stampsPass = (st: SessionState) => {
+    // skip entirely when this flush carries no message items: every
+    // index mutation rides a message item through the queue (inserts via
+    // enqueue, deletes via tombstones — both are type "message"), so no
+    // message in the queue means the stamps' inputs are unchanged. A
+    // status-only/model/prefs/diff flush costs zero stamp work.
+    let any = false
+    for (const it of st.queue.values()) {
+      if ((it as { type?: string }).type === "message") {
+        any = true
+        break
+      }
+    }
+    if (!any) return
+    // one grouping + one sort shared by both passes (each used to build
+    // and sort its own identical bySession map per flush)
+    const bySession = new Map<string, IndexedMessage[]>()
+    for (const m of msgIndex.values()) {
+      const list = bySession.get(m.sid)
+      if (list) list.push(m)
+      else bySession.set(m.sid, [m])
+    }
+    for (const list of bySession.values()) list.sort((a, b) => a.created - b.created)
+    stampAgentSwitches(bySession)
+    stampTaskAgents(bySession)
+    stampFileLanguages()
+  }
+
+  // ---- contract v2 message assembly --------------------------------------
+  // v1 hosts stream parts as separate events; the v2 item embeds content.
+  // The engine keeps the assembled view per message and re-emits the
+  // normalized whole (the keyed queue dedupes across a debounce window,
+  // so intermediate re-emissions collapse).
+
+  const mergeEntry = (st: SessionState, messageID: string) => {
+    let e = st.merged.get(messageID)
+    if (!e) {
+      e = { parts: new Map() }
+      st.merged.set(messageID, e)
+    }
+    return e
+  }
+
+  /** (Re-)emit the v2 message item for a merged v1 message. */
+  const emitMerged = (st: SessionState, sid: string, messageID: string) => {
+    const e = st.merged.get(messageID)
+    if (!e?.info) return // parts arriving before their message: wait
+    const res = normalizeV1Message(e.info, [...e.parts.values()])
+    if (!res) return
+    if ("refill" in res) {
+      // v1 compaction summary assistant → rewrite the parent compaction
+      // message with the summary text; the summary message itself is not
+      // emitted as its own item
+      const parent = st.merged.get(res.refill)
+      if (parent?.info) {
+        const compaction = normalizeV1Message(parent.info, [...parent.parts.values()])
+        if (compaction && "message" in compaction) {
+          const msg = compaction.message as Record<string, unknown>
+          msg.summary = res.summary
+          enqueue(st, itemFor("message", msg, sid))
+        }
+      }
+      return
+    }
+    enqueue(st, itemFor("message", res.message, sid))
+  }
+
+  /** message.updated / part.updated ingestion for v1 hosts; v2 hosts call
+   * with v2-native messages (pass-through, no merge). */
+  const ingestMessageInfo = (st: SessionState, sid: string, info: Record<string, unknown>) => {
+    if (isV2NativeMessage(info)) {
+      enqueue(st, itemFor("message", info, sid))
+      return
+    }
+    if (typeof info?.id !== "string") return
+    const e = mergeEntry(st, info.id)
+    e.info = info
+    emitMerged(st, sid, info.id)
+  }
+
+  const ingestPart = (st: SessionState, sid: string, part: Record<string, unknown>) => {
+    if (typeof part?.id !== "string" || typeof part.messageID !== "string") return
+    const e = mergeEntry(st, part.messageID)
+    e.parts.set(part.id, part)
+    emitMerged(st, sid, part.messageID)
+  }
+
+  const dropMergedMessage = (st: SessionState, messageID: string, evSid?: string) => {
+    // the index corpse must go too: stampsPass iterates msgIndex, and a
+    // re-stamp of a deleted message would re-upsert it (resurrection).
+    // Key by the EVENT's session (children tombstone under their own sid;
+    // the merged map is per main session)
+    const sid = evSid ?? st.sid
+    st.merged.delete(messageID)
+    msgIndex.delete(`${sid}:${messageID}`)
+    tombstoned.add(`${sid}:${messageID}`)
+  }
+
+  const dropMergedPart = (st: SessionState, sid: string, messageID: string, partID: string) => {
+    const e = st.merged.get(messageID)
+    if (!e) return
+    e.parts.delete(partID)
+    if (e.info) emitMerged(st, sid, messageID)
+  }
+
   const remove = (st: SessionState) => {
     st.closed = true
     st.activated = false
@@ -1432,6 +2116,10 @@ export function createEngine(deps: EngineDeps): Engine {
         clearTimeout(r.initTimer)
         r.initTimer = null
       }
+      if (r.backoffResetTimer) {
+        clearTimeout(r.backoffResetTimer)
+        r.backoffResetTimer = null
+      }
       if (r.reconnectTimer) {
         clearTimeout(r.reconnectTimer)
         r.reconnectTimer = null
@@ -1441,8 +2129,28 @@ export function createEngine(deps: EngineDeps): Engine {
         clearTimeout(r.idleDropTimer)
         r.idleDropTimer = null
       }
-      if (r.wsReady) wsSend(r, { op: "delete" })
-      else if (r.shareId && r.secret) {
+      // wsReady delete only when THIS remote still owns a share: a stray
+      // child teardown clears shareId after adopting into the parent —
+      // the ControlDO's server-side attach would otherwise delete the
+      // very share the parent just inherited (live-caught adoption churn)
+      if (r.wsReady && r.shareId) {
+        wsSend(r, { op: "delete" })
+        // backstop: the WS delete is fire-and-forget on the wire — a
+        // socket dying right after leaves the page public until TTL. The
+        // HTTP goodbye is idempotent (404/ok both fine).
+        if (r.shareId && r.secret) {
+          const sid = r.shareId
+          const sec = r.secret
+          setTimeout(() => {
+            void fetch(`${r.url}/api/share/${sid}`, {
+              method: "DELETE",
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify({ secret: sec }),
+              signal: AbortSignal.timeout(8000),
+            }).catch(() => {})
+          }, 2000)
+        }
+      } else if (r.shareId && r.secret) {
         // turn mode may have dropped the socket after the last settle; the
         // goodbye still must land — say it over HTTP
         void fetch(`${r.url}/api/share/${r.shareId}`, {
@@ -1461,6 +2169,15 @@ export function createEngine(deps: EngineDeps): Engine {
       }
     }, 1000)
     for (const r of st.remotes.values()) spoolClear(st, r)
+    // memory hygiene: the session is gone — its index corpses, tombstone
+    // guards and child routing must not linger (msgIndex/tombstoned are
+    // engine-global and otherwise only grow; sentHash rides the session
+    // state and dies with it)
+    const stSid = st.sid
+    const pfx = `${stSid}:`
+    for (const k of msgIndex.keys()) if (k.startsWith(pfx)) msgIndex.delete(k)
+    for (const k of tombstoned) if (k.startsWith(pfx)) tombstoned.delete(k)
+    for (const [child, parent] of childToParent) if (parent === stSid || child === stSid) childToParent.delete(child)
     sessions.delete(st.sid)
     try {
       chain = chain.then(async () => {
@@ -1496,7 +2213,7 @@ export function createEngine(deps: EngineDeps): Engine {
 
   const query = () => (deps.directory ? { directory: deps.directory } : {})
 
-  async function fetchMessages(client: ClientApi, sid: string): Promise<Message[]> {
+  async function fetchMessages(client: ClientApi, sid: string, onPage?: (page: Message[]) => void): Promise<Message[]> {
     if (typeof client.session.messages !== "function") return []
     const out: Message[] = []
     let before: string | undefined
@@ -1511,13 +2228,33 @@ export function createEngine(deps: EngineDeps): Engine {
       )
       if (!Array.isArray(result) || result.length === 0) break
       out.push(...(result as Message[]))
+      // stream pages as they arrive: enqueue (and the rate-limited flush)
+      // starts with page 1 while later pages are still loading — a huge
+      // session backfills progressively instead of after a full collect
+      if (onPage) {
+        try {
+          onPage(result as Message[])
+        } catch {}
+      }
       if (result.length < PAGE_SIZE) break
       const last = result[result.length - 1] as Message
-      const nextBefore =
-        typeof last?.info?.id === "string" ? (last.info.id as string) : typeof (last as unknown as { id?: string })?.id === "string" ? ((last as unknown as { id: string }).id as string) : undefined
-      if (!nextBefore || nextBefore === before) break
+      const lastInfo = (last?.info ?? last) as Record<string, unknown> | undefined
+      const lastID = typeof lastInfo?.id === "string" ? lastInfo.id : undefined
+      // `before` is an OPAQUE cursor: base64url({id, time}) of the page
+      // tail (message-v2.ts codec). A bare message id 400s on hosts with
+      // cursor pagination — every v1 backfill silently truncated to one
+      // 100-message page (live-caught).
+      const lastTime = (lastInfo?.time as Record<string, unknown> | undefined)?.created
+      if (!lastID || typeof lastTime !== "number") break
+      const nextBefore = cursorFor(lastID, lastTime)
+      if (nextBefore === before) break
       before = nextBefore
     }
+    // the page cap is a hard truncation: surface it instead of silently
+    // sharing a partial history (oldest pages dropped)
+    if (out.length >= MAX_PAGES * PAGE_SIZE) {
+      logError(`backfill truncated at ${out.length} messages (page cap) for ${sid.slice(0, 18)} — oldest history not shared`)
+    }
     return out
   }
 
@@ -1525,27 +2262,32 @@ export function createEngine(deps: EngineDeps): Engine {
     const sessionInfoValue = info ?? (await sessionInfo(client, sid))
     if (sessionInfoValue) enqueue(st, itemFor("session", redact(sessionInfoValue), sid))
 
-    const messages = await fetchMessages(client, sid)
     let modelSeen = false
-    for (const message of messages) {
-      const m = (message.info ?? message) as MessageInfo
-      if (!m || typeof m.id !== "string") continue
-      enqueue(st, itemFor("message", m, sid))
-      if (m.role === "user" && m.model) {
-        modelSeen = true
-        const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, m.model)
-        enqueue(
-          st,
-          itemFor("model", [{ id: m.model.modelID, providerID: m.model.providerID, name: label }], sid),
-        )
-      }
-      for (const part of message.parts ?? []) {
-        const p = part as PartInfo
-        if (!p || typeof p.id !== "string" || typeof p.messageID !== "string") continue
-        if (p.state?.status === "error") st.badSignal = true
-        enqueue(st, itemFor("part", p, sid))
+    const consume = (messages: Message[]) => {
+      for (const message of messages) {
+        const m = ((message.info ?? message) as MessageInfo) as Record<string, unknown> | undefined
+        if (!m || typeof m.id !== "string") continue
+        // seed the merge state, then emit the assembled v2 message
+        const e = mergeEntry(st, m.id)
+        e.info = m
+        for (const rawPart of (message.parts ?? []) as Array<Record<string, unknown>>) {
+          const p = rawPart as PartInfo
+          if (!p || typeof p.id !== "string" || typeof p.messageID !== "string") continue
+          if (p.state?.status === "error") st.badSignal = true
+          e.parts.set(p.id, p as Record<string, unknown>)
+        }
+        emitMerged(st, sid, m.id)
+        if (m.role === "user" && m.model) {
+          modelSeen = true
+          const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, m.model as SessionModel)
+          enqueue(
+            st,
+            itemFor("model", [{ id: (m.model as SessionModel).modelID, providerID: (m.model as SessionModel).providerID, name: label }], sid),
+          )
+        }
       }
     }
+    const messages = await fetchMessages(client, sid, (page) => consume(page))
     if (!modelSeen && sessionInfoValue?.model) {
       // hosts whose user messages carry no model (v2): label from the
       // session's own model
@@ -1800,8 +2542,13 @@ export function createEngine(deps: EngineDeps): Engine {
             // runs still land their final status.
             if (st.timer) clearTimeout(st.timer)
             st.timer = null
+            // detached flush (HTTP fallback off the shared chain — one
+            // black-holing server must not stall the fan-out; same rule
+            // as scheduleFlush)
             chain = chain
-              .then(() => flush(st))
+              .then(() => {
+                flush(st)
+              })
               .catch((e) => logError("idle flush error", (e as Error)?.message || e))
             const epoch = st.statusEpoch
             const settle = () => {
@@ -1810,7 +2557,9 @@ export function createEngine(deps: EngineDeps): Engine {
               if (st.timer) clearTimeout(st.timer)
               st.timer = null
               chain = chain
-                .then(() => flush(st))
+                .then(() => {
+                  flush(st)
+                })
                 .then(() => {
                   armSettleDrop(st)
                 })
@@ -1842,19 +2591,24 @@ export function createEngine(deps: EngineDeps): Engine {
           // opencode undo: revert() only marks the session (the viewer
           // hides the range); the NEXT prompt hard-deletes the reverted
           // messages/parts via cleanup() and publishes these events.
-          // The worker's store is upsert-only, so without an explicit
-          // tombstone the deleted items live forever and reappear the
-          // moment the revert marker clears (live-caught in production).
+          // A message tombstone removes the whole v2 message (content is
+          // embedded); a part removal re-emits the merged message minus
+          // the part.
           const st = stFor(sid)
           if (!st || !st.activated || st.closed) return
           const messageID = p.messageID as string | undefined
           if (!messageID) return
           if (t === "message.removed") {
-            enqueue(st, { key: `message/${messageID}`, item: { type: "message", del: true, data: { id: messageID } } })
+            // key/tombstone by the EVENT's session id (a child's message
+            // must not be keyed onto the parent — the worker deletes the
+            // item but the viewer's tombstone key would miss and the
+            // msgIndex corpse could re-upsert it)
+            dropMergedMessage(st, messageID, sid)
+            enqueue(st, { key: `message/${messageID}`, item: messageTombstone(sid, messageID) })
           } else {
             const partID = p.partID as string | undefined
             if (!partID) return
-            enqueue(st, { key: `part/${messageID}/${partID}`, item: { type: "part", del: true, data: { id: partID, messageID } } })
+            dropMergedPart(st, sid, messageID, partID)
           }
         } else if (t === "message.updated") {
           // resumed sessions may emit the user message BEFORE any session.*
@@ -1907,7 +2661,7 @@ export function createEngine(deps: EngineDeps): Engine {
             }
           }
           if (!st || !st.activated || st.closed) return
-          enqueue(st, itemFor("message", p.info, sid))
+          ingestMessageInfo(st, sid, p.info as Record<string, unknown>)
           const info = p.info as MessageInfo
           if (info?.role === "user" && info?.model) {
             const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, info.model)
@@ -1916,8 +2670,9 @@ export function createEngine(deps: EngineDeps): Engine {
           // an assistant message that DIED (finish:"error") — e.g. all
           // retries exhausted — surfaces as a 200 response with an errored
           // message, NOT as session.error (live-caught in the suite); the
-          // share must still say error
-          if (info?.role === "assistant" && (info as { finish?: string }).finish === "error") {
+          // share must still say error. Works for v2-native messages too
+          // (finish lives on the message itself).
+          if ((info as { finish?: string; role?: string })?.finish === "error") {
             st.badSignal = true
           }
         } else if (t === "message.part.updated") {
@@ -1925,11 +2680,11 @@ export function createEngine(deps: EngineDeps): Engine {
           if (!st || !st.activated || st.closed) return
           const part = p.part as PartInfo
           if (part?.state?.status === "error") st.badSignal = true
-          enqueue(st, itemFor("part", part, sid))
+          ingestPart(st, sid, part as Record<string, unknown>)
         } else if (t === "session.diff") {
           const st = stFor(sid)
           if (!st || !st.activated || st.closed) return
-          enqueue(st, itemFor("session_diff", p.diff, sid))
+          enqueue(st, itemFor("session_diff", normalizeV1Diff(p.diff), sid))
         } else if (t === "session.deleted") {
           // a CHILD session ending (task done, gc) must NEVER take the
           // parent's share down with it — the page keeps the subagent's
@@ -1979,6 +2734,16 @@ export function createEngine(deps: EngineDeps): Engine {
               await flushViaHttp(st, r).catch(() => {})
             }
           }
+          // resolve any pending debounced spool rewrite before exit: the
+          // queue lines are already on disk (appends are sync), but the
+          // meta's ackedRev and the compacted queue should be final
+          for (const r of st.remotes.values()) {
+            if (r.spoolSaveTimer) {
+              clearTimeout(r.spoolSaveTimer)
+              r.spoolSaveTimer = null
+              spoolSave(st, r)
+            }
+          }
           if (st.metaTimer) clearTimeout(st.metaTimer)
           st.metaTimer = null
           await writeBinding(st).catch(() => {})