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

package/dist/core.js

@@ -42,8 +42,11 @@
 //  - The plugin strips this key from everything it syncs — the write
 //    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 } from "./config.js";
+import { cursorFor, isV2NativeMessage, messageTombstone, normalizeV1Diff, normalizeV1Message } from "./contract.js";
+import { queueBindingWrite } from "./binding-queue.js";
 const DEFAULT_POLICY = {
     mode: "persistent",
     turnGraceMs: 120000,
@@ -93,11 +96,12 @@ function itemFor(type, data, sessionID) {
     if (type === "prefs")
         return { key: "prefs", item: { type, data } };
     if (type === "session")
-        return { key: `session/${data?.id ?? ""}`, item: { type, data } };
+        return { key: `session/${data?.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?.id ?? ""}`, item: { type, data } };
-    if (type === "part")
-        return { key: `part/${data?.messageID ?? ""}/${data?.id ?? ""}`, item: { type, data } };
+        return { key: `message/${data?.id ?? ""}`, item: { type, sessionID, data } };
     if (type === "session_diff")
         return { key: `session_diff/${sessionID}`, item: { type, sessionID, data } };
     return undefined;
@@ -269,6 +273,8 @@ export function createEngine(deps) {
                 initTimer: null,
                 initWasAttach: false,
                 backoff: 1000,
+                backoffResetTimer: null,
+                spoolSaveTimer: null,
                 reconnectTimer: null,
                 intentionalClose: false,
                 connectQueued: false,
@@ -334,12 +340,19 @@ export function createEngine(deps) {
             if (b && typeof b === "object" && b.policy) {
                 applyPolicy(b.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.frameAuth) {
+                frameAuthUrls.add(url);
+            }
         })
             .catch(() => {
             // unreachable worker: defaults stay; the init ack will correct us
             policyAsked.delete(url);
         });
     };
+    const frameAuthUrls = new Set();
     const wsUrl = (url) => url.replace(/^http/, "ws");
     // ---- spool root ---------------------------------------------------------
     let spoolRoot = spoolDirFor(cfg);
@@ -380,6 +393,8 @@ export function createEngine(deps) {
         activated: false,
         wroteBinding: false,
         everConnected: false,
+        merged: new Map(),
+        sentHash: new Map(),
     });
     const refreshConfig = () => {
         // settings may change between activations (the TUI writes the config
@@ -419,6 +434,9 @@ export function createEngine(deps) {
         }
         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
@@ -493,25 +511,30 @@ export function createEngine(deps) {
     async function writeMetadata(st, value) {
         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?.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?.message || e);
+            }
+        });
     }
     /** Parse the metadata binding: v2 map ({v:2, servers:{url:{id,secret,
      * rev,url,enabled?}}}) or legacy flat ({id,secret,rev,url}) which maps
@@ -632,13 +655,55 @@ export function createEngine(deps) {
     const spoolSave = (st, r) => {
         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?.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, r, f) => {
+        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?.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, r) => {
+        if (r.spoolSaveTimer)
+            return;
+        r.spoolSaveTimer = setTimeout(() => {
+            r.spoolSaveTimer = null;
+            if (!st.closed)
+                spoolSave(st, r);
+        }, 300);
+    };
     const spoolLoad = (st, r) => {
+        // 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
@@ -647,16 +712,48 @@ export function createEngine(deps) {
                 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 = [];
+                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 {
@@ -679,12 +776,26 @@ export function createEngine(deps) {
     };
     const spoolClear = (st, r) => {
         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, obj) => {
         if (debugEvents)
             log(`ws ${r.url.slice(0, 24)} #${r.socketSeq} send ${obj?.op} (ready=${r.wsReady})`);
@@ -696,16 +807,70 @@ export function createEngine(deps) {
         }
         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;
+    /** 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, maxItems, maxBytes) => {
+        const chunks = [];
+        let cur = [];
+        let curJson = [];
+        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, maxItems, maxBytes) => 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, status, seq) => `{"op":"sync","items":${itemsJson},"status":${JSON.stringify(status)}${seq !== undefined ? `,"seq":${seq}` : ""}}`;
+    const wsSendRaw = (r, s) => {
+        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, f) => {
         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 });
-        }
+            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;
     };
     const announceUrl = (st, r) => {
@@ -899,7 +1064,12 @@ export function createEngine(deps) {
                 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);
@@ -940,6 +1110,32 @@ export function createEngine(deps) {
                 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((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) } });
             }
@@ -973,7 +1169,9 @@ export function createEngine(deps) {
     const scheduleReconnect = (st, r) => {
         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;
@@ -1065,6 +1263,15 @@ export function createEngine(deps) {
         }
     };
     const handleFrame = async (st, r, frame) => {
+        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 ?? "");
@@ -1123,6 +1330,21 @@ export function createEngine(deps) {
                 // 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;
@@ -1154,11 +1376,26 @@ export function createEngine(deps) {
             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);
@@ -1184,19 +1421,70 @@ export function createEngine(deps) {
             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?.message || e));
             }
             return;
         }
         if (frame.op === "ack") {
             r.ackedRev = frame.rev ?? 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
@@ -1227,6 +1515,10 @@ export function createEngine(deps) {
     };
     // ---- flush -------------------------------------------------------------
     const frameFrom = (st) => {
+        // 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;
@@ -1251,18 +1543,41 @@ export function createEngine(deps) {
             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 = f.items.length ? chunkedFrames(f.items, 200, 512 * 1024) : [];
         let httpWork;
         for (const r of st.remotes.values()) {
+            if (r.frozenRemote)
+                continue; // refused server-side; stop spooling
+            const fresh = [];
+            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: [], 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);
@@ -1271,36 +1586,84 @@ export function createEngine(deps) {
         }
         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?.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) => {
+        if (!it || typeof it !== "object")
+            return null;
+        const o = it;
+        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, r) => {
         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 = [];
+        // 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();
+        const unkeyed = [];
         let status;
+        const sentSeqs = new Set();
         for (const f of r.pending) {
-            for (const it of f.items)
-                items.push(it);
+            for (const it of f.items) {
+                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(() => ({})));
             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));
+        scheduleSpoolSave(st, r);
     };
     const scheduleFlush = (st) => {
         if (st.timer)
@@ -1316,19 +1679,358 @@ export function createEngine(deps) {
             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?.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?.message || e));
         }, wait);
     };
     const enqueue = (st, entry) => {
         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;
+        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);
     };
+    const msgIndex = new Map(); // `${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();
+    const indexMessage = (entry) => {
+        if (entry.item.type !== "message")
+            return;
+        const d = entry.item.data;
+        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,
+            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,
+        });
+    };
+    const sessionStateOf = (sid) => sessions.get(childToParent.get(sid) ?? sid);
+    const reEnqueueMessage = (m) => {
+        // 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, at) => {
+        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) => {
+        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;
+            for (let k = 0; k < users.length; k++) {
+                const agent = segmentAgent(list, users[k]);
+                const d = list[users[k]].data;
+                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) {
+                    if (want) {
+                        const meta = (d.metadata ??= {});
+                        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) => {
+        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.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;
+                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 = {
+        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.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) => {
+        // 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.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();
+        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, messageID) => {
+        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, sid, messageID) => {
+        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;
+                    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, sid, info) => {
+        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, sid, part) => {
+        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, messageID, evSid) => {
+        // 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, sid, messageID, partID) => {
+        const e = st.merged.get(messageID);
+        if (!e)
+            return;
+        e.parts.delete(partID);
+        if (e.info)
+            emitMerged(st, sid, messageID);
+    };
     const remove = (st) => {
         st.closed = true;
         st.activated = false;
@@ -1347,6 +2049,10 @@ export function createEngine(deps) {
                 clearTimeout(r.initTimer);
                 r.initTimer = null;
             }
+            if (r.backoffResetTimer) {
+                clearTimeout(r.backoffResetTimer);
+                r.backoffResetTimer = null;
+            }
             if (r.reconnectTimer) {
                 clearTimeout(r.reconnectTimer);
                 r.reconnectTimer = null;
@@ -1356,8 +2062,28 @@ export function createEngine(deps) {
                 clearTimeout(r.idleDropTimer);
                 r.idleDropTimer = null;
             }
-            if (r.wsReady)
+            // 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
@@ -1379,6 +2105,21 @@ export function createEngine(deps) {
         }, 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 () => {
@@ -1413,7 +2154,7 @@ export function createEngine(deps) {
     const PAGE_SIZE = 100;
     const MAX_PAGES = 50;
     const query = () => (deps.directory ? { directory: deps.directory } : {});
-    async function fetchMessages(client, sid) {
+    async function fetchMessages(client, sid, onPage) {
         if (typeof client.session.messages !== "function")
             return [];
         const out = [];
@@ -1429,41 +2170,69 @@ export function createEngine(deps) {
             if (!Array.isArray(result) || result.length === 0)
                 break;
             out.push(...result);
+            // 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);
+                }
+                catch { }
+            }
             if (result.length < PAGE_SIZE)
                 break;
             const last = result[result.length - 1];
-            const nextBefore = typeof last?.info?.id === "string" ? last.info.id : typeof last?.id === "string" ? last.id : undefined;
-            if (!nextBefore || nextBefore === before)
+            const lastInfo = (last?.info ?? last);
+            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?.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;
     }
     const backfillSession = async (st, client, sid, info) => {
         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);
-            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;
-                if (!p || typeof p.id !== "string" || typeof p.messageID !== "string")
+        const consume = (messages) => {
+            for (const message of messages) {
+                const m = (message.info ?? message);
+                if (!m || typeof m.id !== "string")
                     continue;
-                if (p.state?.status === "error")
-                    st.badSignal = true;
-                enqueue(st, itemFor("part", p, sid));
+                // 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 ?? [])) {
+                    const p = rawPart;
+                    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);
+                }
+                emitMerged(st, sid, m.id);
+                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));
+                }
             }
-        }
+        };
+        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
@@ -1725,8 +2494,13 @@ export function createEngine(deps) {
                         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?.message || e));
                         const epoch = st.statusEpoch;
                         const settle = () => {
@@ -1736,7 +2510,9 @@ export function createEngine(deps) {
                                 clearTimeout(st.timer);
                             st.timer = null;
                             chain = chain
-                                .then(() => flush(st))
+                                .then(() => {
+                                flush(st);
+                            })
                                 .then(() => {
                                 armSettleDrop(st);
                             })
@@ -1773,9 +2549,9 @@ export function createEngine(deps) {
                     // 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;
@@ -1783,13 +2559,18 @@ export function createEngine(deps) {
                     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;
                         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") {
@@ -1844,7 +2625,7 @@ export function createEngine(deps) {
                     }
                     if (!st || !st.activated || st.closed)
                         return;
-                    enqueue(st, itemFor("message", p.info, sid));
+                    ingestMessageInfo(st, sid, p.info);
                     const info = p.info;
                     if (info?.role === "user" && info?.model) {
                         const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, info.model);
@@ -1853,8 +2634,9 @@ export function createEngine(deps) {
                     // 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.finish === "error") {
+                    // share must still say error. Works for v2-native messages too
+                    // (finish lives on the message itself).
+                    if (info?.finish === "error") {
                         st.badSignal = true;
                     }
                 }
@@ -1865,13 +2647,13 @@ export function createEngine(deps) {
                     const part = p.part;
                     if (part?.state?.status === "error")
                         st.badSignal = true;
-                    enqueue(st, itemFor("part", part, sid));
+                    ingestPart(st, sid, part);
                 }
                 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
@@ -1925,6 +2707,16 @@ export function createEngine(deps) {
                             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;