@kortix/sdk 0.12.8 → 0.13.0

package/dist/browser/stores/sync-store.js

@@ -1,5 +1,6 @@
 "use client";
 import { create } from "zustand";
+import { commitSessionRewind, isWithinRewindWindow, stageSessionRewind, } from "../../core/session/rewind.js";
 import { ascendingId } from "./sync-store/ascending-id.js";
 import { Binary } from "./sync-store/binary.js";
 import { writeStreamCache } from "./sync-store/stream-cache.js";
@@ -7,6 +8,30 @@ import { writeStreamCache } from "./sync-store/stream-cache.js";
 // `Binary`, `ascendingId`, and the `MessageWithParts` type remain importable
 // from this module exactly as before.
 export { ascendingId, Binary };
+/**
+ * Do two `SessionStatus` values say the same thing?
+ *
+ * NOT a deep equality: it compares `type` plus exactly the fields the retry
+ * readers actually read — `getRetryInfo` / `getRetryMessage` in
+ * `core/turns/state.ts` take `attempt`, `message` and `next`. A blanket
+ * deep-equal would also compare `action`, which nothing reads, and would then
+ * mint a new observation for a change no surface can render.
+ *
+ * The point of the comparison is object identity, not the boolean: a status
+ * frame is an OBSERVATION, and `useSessionWorking` dates it by the identity of
+ * the object in the store. Two equal values are one observation.
+ */
+export function sameSessionStatus(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.type !== b.type)
+        return false;
+    if (a.type !== "retry" || b.type !== "retry")
+        return true;
+    return a.attempt === b.attempt && a.message === b.message && a.next === b.next;
+}
 function isTextLikePart(part) {
     return part.type === "text" || part.type === "reasoning";
 }
@@ -26,6 +51,35 @@ const optimisticIds = new Map();
 // match: the server has not been told it exists, so nothing the server returns
 // can be a copy of it.
 const dispatchedOptimisticIds = new Map();
+// Optimistic ids whose prompt-inbox row LANDED (see `markOptimisticInboxBacked`).
+// The idle sweep skips these: the control plane holds the message durably and
+// will deliver it, so "the session went idle and this was never echoed" is
+// not evidence it was lost.
+const inboxBackedOptimisticIds = new Map();
+// optimistic id → the runtime id that superseded it, and the inverse. Written
+// at supersede time (SSE and hydrate), so a host can keep one identity for a
+// prompt across the swap. Bounded by the number of prompts sent from this tab
+// per session; released with the session.
+const optimisticEchoes = new Map();
+const optimisticOrigins = new Map();
+function recordOptimisticEcho(sessionID, optimisticID, echoID) {
+    if (optimisticID === echoID)
+        return;
+    let fwd = optimisticEchoes.get(sessionID);
+    if (!fwd)
+        optimisticEchoes.set(sessionID, (fwd = new Map()));
+    fwd.set(optimisticID, echoID);
+    let rev = optimisticOrigins.get(sessionID);
+    if (!rev)
+        optimisticOrigins.set(sessionID, (rev = new Map()));
+    rev.set(echoID, optimisticID);
+}
+/** Forget every optimistic mark for one id — confirmed, superseded, or removed. */
+function releaseOptimisticId(sessionID, id) {
+    untrackId(optimisticIds, sessionID, id);
+    untrackId(dispatchedOptimisticIds, sessionID, id);
+    untrackId(inboxBackedOptimisticIds, sessionID, id);
+}
 function trackId(store, sessionID, id) {
     const bucket = store.get(sessionID);
     if (bucket)
@@ -49,6 +103,9 @@ function hasTrackedId(store, sessionID, id) {
 function forgetSessionIds(sessionID) {
     optimisticIds.delete(sessionID);
     dispatchedOptimisticIds.delete(sessionID);
+    inboxBackedOptimisticIds.delete(sessionID);
+    optimisticEchoes.delete(sessionID);
+    optimisticOrigins.delete(sessionID);
     // The joined rows hold the very message and part arrays this session's
     // data is being dropped from. Left behind, they keep the transcript
     // reachable and the drop achieves nothing.
@@ -65,6 +122,9 @@ function forgetSessionIds(sessionID) {
     // bridge-clearing branch fired for it too, wiping every part already
     // stored under it. See bridgedPartIds below.
     bridgedPartIds.delete(sessionID);
+    // Same leak class, on the two T14 + T16 maps above.
+    deltaEventTails.delete(sessionID);
+    stubAssistantIds.delete(sessionID);
 }
 const isOptimistic = (sessionID, messageID) => hasTrackedId(optimisticIds, sessionID, messageID);
 const isDispatched = (sessionID, messageID) => hasTrackedId(dispatchedOptimisticIds, sessionID, messageID);
@@ -97,6 +157,57 @@ const bridgedPartIds = new Map();
 // session's bucket fixes it.
 const deltaActiveParts = new Map();
 // ---------------------------------------------------------------------------
+// Part-delta idempotency (T14).
+//
+// `applyPartDelta` used to be `existing + delta` with nothing consulted for
+// identity — a duplicate delivery of the SAME `message.part.delta` doubled
+// the streamed text. Realistic duplicate sources: the vendor SSE client's
+// retry loop briefly stacking a second live connection before
+// `event-stream.ts`'s own single-live-stream invariant (or the `sseMaxRetryAttempts:
+// 1` pin) catches up, or a second mounted subscriber replaying the same
+// stream.
+//
+// The wire's own `EventMessagePartDelta` (`@opencode-ai/sdk`'s
+// `v2/gen/types.gen.d.ts`) carries a top-level `id: string` on every event —
+// NOT inside `properties`, so `applyEvent`'s `message.part.delta` case now
+// threads `event.id` through as `applyPartDelta`'s new optional trailing
+// `eventID` param. Two independently-broadcast SSE readers of the SAME
+// published event (a stacked connection, a second subscriber) both receive
+// the identical event object and therefore the identical `id` — which makes
+// event identity the correct dedupe key, not delta CONTENT: content-based
+// dedupe (e.g. "reject a delta whose text matches the last one applied at
+// this length") would false-positive on legitimately-repeated content, such
+// as streaming "..." one identical character at a time.
+//
+// Keyed by session (same shape/reason as the maps above), then by
+// `${messageID}:${partID}:${field}` (a part could in principle accumulate
+// more than one delta-bearing field) to the SET of event ids already applied
+// for that key. A stacked duplicate connection can redeliver a whole tail of
+// the stream, not just the single most-recent event — "replay the last N
+// deltas again" is exactly what a reconnect-and-resume does — so every
+// applied id for the key is kept, not just the last one; a Set lookup stays
+// O(1) either way. Bounded by the per-session clears below, so this never
+// grows across an entire session's lifetime, only within one streaming turn.
+// A delta that arrives with no `eventID` (a caller predating this change, or
+// a hand-built synthetic delta) gets NO protection — identical to this
+// function's behavior before this change — rather than risk a content-based
+// false positive (see the module comment above for why content isn't used).
+//
+// Cleared per-session on `session.idle`/`session.error` (a new turn's deltas
+// use brand-new part ids anyway, so nothing realistic is lost) and released
+// wholesale by `forgetSessionIds`/`reset()`, matching `deltaActiveParts`.
+const deltaEventTails = new Map();
+/** Session-scoped tracking for `session.error`'s stub assistant message (see
+ *  the handler below) — same shape/reason as the maps above. A stub only
+ *  ever stands in for a real assistant message that has not arrived yet;
+ *  `hydrate` reconciles (drops) it the moment the server's own transcript
+ *  contains a real one for this session, which is the promise the stub's own
+ *  creation comment made but that nothing previously fulfilled. Released
+ *  wholesale by `forgetSessionIds`/`reset()`; NOT cleared on idle/error — the
+ *  stub message it names still lives in `messages[sessionID]` until hydrate
+ *  reconciles it or the session itself ends. */
+const stubAssistantIds = new Map();
+// ---------------------------------------------------------------------------
 // Session retention — how a transcript ever LEAVES memory again.
 //
 // `messages` and `parts` are keyed by session and nothing removed a key.
@@ -315,6 +426,8 @@ export const useSyncStore = create()((set, get) => ({
     sessionStatus: {},
     diffs: {},
     todos: {},
+    sessionRevert: {},
+    sessionRevertNeedsTailReconcile: {},
     // Compat alias
     get statuses() {
         return get().sessionStatus;
@@ -372,22 +485,18 @@ export const useSyncStore = create()((set, get) => ({
         let list;
         let bridgeCleared = false;
         if (hasTrackedId(bridgedPartIds, partSessionID, messageID)) {
-            // Only retire the optimistic/bridged user text once a REAL text
-            // part with actual content arrives. A stray non-text part — or an
-            // empty text snapshot — must NOT wipe the bridge, otherwise the
-            // user's message renders as an empty bubble.
-            const incoming = part;
-            const incomingIsRealText = incoming?.type === "text" &&
-                typeof incoming.text === "string" &&
-                incoming.text.length > 0;
-            if (incomingIsRealText) {
-                untrackId(bridgedPartIds, partSessionID, messageID);
-                list = [];
-                bridgeCleared = true;
-            }
-            else {
-                list = s.parts[messageID] ?? [];
-            }
+            // T16 — retire the bridge on ANY real part arrival for this
+            // message: text, non-text (tool/file/step/…), or an empty-text
+            // snapshot. This used to retire ONLY on a non-empty text part, so a
+            // message whose first real part was a tool call (or an empty text
+            // snapshot before content streamed in) kept the optimistic bridge
+            // alongside the real parts — duplicating the user's text bubble.
+            // The server has started sending this message's real parts either
+            // way, so the bridge's job — standing in until real data exists —
+            // is done the moment ANY of them arrives.
+            untrackId(bridgedPartIds, partSessionID, messageID);
+            list = [];
+            bridgeCleared = true;
         }
         else {
             list = s.parts[messageID] ?? [];
@@ -467,7 +576,7 @@ export const useSyncStore = create()((set, get) => ({
         }
         return { parts: { ...s.parts, [messageID]: next } };
     }),
-    applyPartDelta: (sessionID, messageID, partID, field, delta) => {
+    applyPartDelta: (sessionID, messageID, partID, field, delta, eventID) => {
         trackId(deltaActiveParts, sessionID, partID);
         set((s) => {
             const list = s.parts[messageID];
@@ -476,6 +585,33 @@ export const useSyncStore = create()((set, get) => ({
             const result = Binary.search(list, partID, (p) => p.id);
             if (!result.found)
                 return s;
+            // Duplicate-delivery no-op — see `deltaEventTails` above. Only acts
+            // when the caller supplied an event id (every real wire delta does);
+            // a delta with no id gets no protection here, same as before this
+            // change. Checked and RECORDED here, inside the actual-apply
+            // branch (after the list/found checks above), not before `set()`
+            // runs at all: recording it earlier marked an event id "applied"
+            // even on the not-found path — a delta whose target part doesn't
+            // exist yet (or was dropped) — which then permanently blocked a
+            // later LEGITIMATE redelivery of that same event once the part
+            // did exist. See "a delta that finds no target part does not
+            // consume the event id" in the test file.
+            if (eventID) {
+                const tailKey = `${messageID}:${partID}:${field}`;
+                let sessionTails = deltaEventTails.get(sessionID);
+                if (!sessionTails) {
+                    sessionTails = new Map();
+                    deltaEventTails.set(sessionID, sessionTails);
+                }
+                let appliedIds = sessionTails.get(tailKey);
+                if (appliedIds?.has(eventID))
+                    return s;
+                if (!appliedIds) {
+                    appliedIds = new Set();
+                    sessionTails.set(tailKey, appliedIds);
+                }
+                appliedIds.add(eventID);
+            }
             const next = [...list];
             const part = { ...next[result.index] };
             const existing = part[field];
@@ -484,15 +620,106 @@ export const useSyncStore = create()((set, get) => ({
             return { parts: { ...s.parts, [messageID]: next } };
         });
     },
-    setStatus: (sessionID, status) => set((s) => ({
-        sessionStatus: { ...s.sessionStatus, [sessionID]: status },
-    })),
+    setStatus: (sessionID, status) => set((s) => {
+        // A value that did not change is not news. `useSessionWorking` stamps
+        // its stream observation from this object's IDENTITY, so an
+        // equal-valued rewrite that minted a new object re-started
+        // `STREAM_OBSERVATION_MAX_MS` from zero on every write — the bound
+        // that stops a dead stream from deciding was never reached. See
+        // `sameSessionStatus`.
+        if (sameSessionStatus(s.sessionStatus[sessionID], status))
+            return s;
+        return { sessionStatus: { ...s.sessionStatus, [sessionID]: status } };
+    }),
     setDiff: (sessionID, diffs) => set((s) => ({
         diffs: { ...s.diffs, [sessionID]: diffs },
     })),
     setTodo: (sessionID, todos) => set((s) => ({
         todos: { ...s.todos, [sessionID]: todos },
     })),
+    stageSessionRevert: (sessionId, messageId) => set((s) => {
+        const current = s.sessionRevert[sessionId];
+        if (current?.staged && current.messageId === messageId)
+            return s;
+        return {
+            sessionRevert: {
+                ...s.sessionRevert,
+                [sessionId]: stageSessionRewind(get().getMessages(sessionId), messageId),
+            },
+        };
+    }),
+    commitSessionRevert: (sessionId) => set((s) => {
+        const current = s.sessionRevert[sessionId] ?? null;
+        const next = commitSessionRewind(current);
+        if (next === current)
+            return s;
+        return { sessionRevert: { ...s.sessionRevert, [sessionId]: next } };
+    }),
+    clearSessionRevert: (sessionId) => set((s) => {
+        if (!s.sessionRevert[sessionId])
+            return s;
+        return { sessionRevert: { ...s.sessionRevert, [sessionId]: null } };
+    }),
+    applyCommittedRevert: (sessionId, boundaryId, watermark) => set((s) => {
+        const list = s.messages[sessionId];
+        if (!list || list.length === 0) {
+            return { sessionRevert: { ...s.sessionRevert, [sessionId]: null } };
+        }
+        const rewind = { messageId: boundaryId, watermark, staged: false };
+        const removedIds = [];
+        const kept = list.filter((m) => {
+            if (isWithinRewindWindow(m.id, rewind)) {
+                removedIds.push(m.id);
+                return false;
+            }
+            return true;
+        });
+        const nextParts = { ...s.parts };
+        for (const id of removedIds)
+            delete nextParts[id];
+        return {
+            messages: { ...s.messages, [sessionId]: kept },
+            parts: nextParts,
+            sessionRevert: { ...s.sessionRevert, [sessionId]: null },
+        };
+    }),
+    markSessionRevertNeedsTailReconcile: (sessionId) => set((s) => {
+        if (s.sessionRevertNeedsTailReconcile[sessionId])
+            return s;
+        return {
+            sessionRevertNeedsTailReconcile: {
+                ...s.sessionRevertNeedsTailReconcile,
+                [sessionId]: true,
+            },
+        };
+    }),
+    clearSessionRevertNeedsTailReconcile: (sessionId) => set((s) => {
+        if (!s.sessionRevertNeedsTailReconcile[sessionId])
+            return s;
+        const { [sessionId]: _, ...rest } = s.sessionRevertNeedsTailReconcile;
+        return { sessionRevertNeedsTailReconcile: rest };
+    }),
+    syncSessionRevertFromInfo: (sessionId, revert) => {
+        if (!revert?.messageID)
+            return;
+        const current = get().sessionRevert[sessionId];
+        // F3 review finding: `null` is a deliberate tombstone — this store's
+        // own record of "committed or cleared, on purpose" (set by
+        // `applyCommittedRevert`/`clearSessionRevert`) — distinct from
+        // `undefined` ("nothing ever tracked here"). A `session.updated` that
+        // raced one of those two events can still carry the OLD `info.revert`
+        // pointer; re-staging off it here would hide every post-rewind
+        // message behind a phantom Restore. The tombstone wins until a
+        // genuinely fresh revert arrives through the real `.staged` wire
+        // event (`stageSessionRevert`, called directly, which overwrites
+        // unconditionally and so clears the tombstone normally) — never
+        // through this best-effort info-snapshot recovery path.
+        if (current === null)
+            return;
+        if (current?.messageId === revert.messageID)
+            return;
+        get().stageSessionRevert(sessionId, revert.messageID);
+    },
     optimisticAdd: (sessionID, message, messageParts) => {
         trackId(optimisticIds, sessionID, message.id);
         // The user has typed into this session, so the disk repaint stands down.
@@ -523,9 +750,20 @@ export const useSyncStore = create()((set, get) => ({
         if (isOptimistic(sessionID, messageID))
             trackId(dispatchedOptimisticIds, sessionID, messageID);
     },
+    markOptimisticInboxBacked: (sessionID, messageID) => {
+        if (isOptimistic(sessionID, messageID))
+            trackId(inboxBackedOptimisticIds, sessionID, messageID);
+    },
+    optimisticEchoOf: (sessionID, optimisticID) => optimisticEchoes.get(sessionID)?.get(optimisticID),
+    optimisticOriginOf: (sessionID, echoID) => optimisticOrigins.get(sessionID)?.get(echoID),
     optimisticRemove: (sessionID, messageID) => {
-        untrackId(optimisticIds, sessionID, messageID);
-        untrackId(dispatchedOptimisticIds, sessionID, messageID);
+        // Only an OPTIMISTIC message can be removed this way. One the runtime has
+        // confirmed (same-id echo, or the store never tracked it) is the
+        // transcript's; a host that removes its inbox row must not take the
+        // persisted message with it.
+        if (!isOptimistic(sessionID, messageID))
+            return;
+        releaseOptimisticId(sessionID, messageID);
         set((s) => {
             const list = s.messages[sessionID];
             if (!list)
@@ -549,15 +787,16 @@ export const useSyncStore = create()((set, get) => ({
             const list = s.messages[sessionID];
             if (!list)
                 return s;
+            // An inbox-backed message is held by the control plane and will be
+            // delivered; a local idle is not evidence it was lost. It stays.
             const optIds = list
-                .filter((m) => isOptimistic(sessionID, m.id))
+                .filter((m) => isOptimistic(sessionID, m.id) &&
+                !hasTrackedId(inboxBackedOptimisticIds, sessionID, m.id))
                 .map((m) => m.id);
             if (optIds.length === 0)
                 return s;
-            for (const id of optIds) {
-                untrackId(optimisticIds, sessionID, id);
-                untrackId(dispatchedOptimisticIds, sessionID, id);
-            }
+            for (const id of optIds)
+                releaseOptimisticId(sessionID, id);
             const filtered = list.filter((m) => !optIds.includes(m.id));
             const newParts = { ...s.parts };
             for (const id of optIds)
@@ -586,6 +825,11 @@ export const useSyncStore = create()((set, get) => ({
             sessionStatus: { ...s.sessionStatus, [sessionID]: { type: "idle" } },
             diffs: { ...s.diffs, [sessionID]: [] },
             todos: { ...s.todos, [sessionID]: [] },
+            sessionRevert: { ...s.sessionRevert, [sessionID]: null },
+            sessionRevertNeedsTailReconcile: (() => {
+                const { [sessionID]: _, ...rest } = s.sessionRevertNeedsTailReconcile;
+                return rest;
+            })(),
         };
     }),
     retainSession: (sessionID) => {
@@ -669,6 +913,22 @@ export const useSyncStore = create()((set, get) => ({
             .filter((m) => !!m?.info?.id)
             .map((m) => m.info)
             .sort((a, b) => cmp(a.id, b.id));
+        // T16 — reconcile a `session.error` stub assistant message
+        // (see `stubAssistantIds` and the `session.error` handler above). The
+        // stub only ever stood in for a real assistant message that had not
+        // arrived yet, sorted BELOW every server id (`ascendingId('msg')`) —
+        // wrong once real data exists. The moment the server's OWN transcript
+        // contains a real assistant message for this session, every
+        // currently-tracked stub for it is stale and is dropped below rather
+        // than kept alongside the real one at the wrong position. If the
+        // incoming snapshot has no assistant message at all yet, nothing has
+        // arrived to reconcile against, so the stub is left untouched.
+        const trackedStubIds = stubAssistantIds.get(sessionID);
+        const reconcileStubs = !!trackedStubIds &&
+            trackedStubIds.size > 0 &&
+            incoming.some((m) => m.role === "assistant");
+        if (reconcileStubs)
+            stubAssistantIds.delete(sessionID);
         // Merge incoming messages with existing ones — never delete messages
         // that exist in the sync store but are missing from the fetch (they may
         // be from a newer turn that the server hasn't persisted yet).
@@ -689,6 +949,21 @@ export const useSyncStore = create()((set, get) => ({
         //
         // The rule is now identity-based, in two passes.
         const existingIds = new Set(existing.map((m) => m.id));
+        // The echo may arrive under the optimistic message's OWN id: the host
+        // minted the wire id and painted the bubble with it. That is a
+        // confirmation, not a duplicate — release the marks so the message is
+        // ordinary from here (the sweep leaves it alone, real parts win), and
+        // bridge its optimistic parts until real ones land.
+        for (const m of incoming) {
+            if (m.role !== "user" || !isOptimistic(sessionID, m.id))
+                continue;
+            releaseOptimisticId(sessionID, m.id);
+            const optimisticParts = s.parts[m.id];
+            const entry = msgs.find((x) => x.info.id === m.id);
+            if ((entry?.parts?.length ?? 0) === 0 && optimisticParts?.length) {
+                trackId(bridgedPartIds, sessionID, m.id);
+            }
+        }
         // Pass 0 — candidate echoes. A real user message we have NEVER seen
         // before may be the server's copy of something still in flight. One we
         // already held is history, and history cannot supersede the present.
@@ -724,6 +999,12 @@ export const useSyncStore = create()((set, get) => ({
         const unmatchedOptimisticUsers = [];
         for (const m of existing) {
             if (!seen.has(m.id)) {
+                if (reconcileStubs && trackedStubIds.has(m.id)) {
+                    // Superseded by a real assistant message this same hydrate
+                    // snapshot introduced — drop it, don't reinsert it below the
+                    // real data at its stale `ascendingId` position.
+                    continue;
+                }
                 if (isOptimistic(sessionID, m.id)) {
                     if (m.role !== "user") {
                         deferredOptimistic.push(m);
@@ -770,10 +1051,13 @@ export const useSyncStore = create()((set, get) => ({
                 deferredOptimistic.push(m);
             }
         }
-        // Clean up superseded optimistic IDs
+        // Clean up superseded optimistic IDs, remembering which runtime id
+        // each one became.
         for (const id of supersededOptimistic) {
-            untrackId(optimisticIds, sessionID, id);
-            untrackId(dispatchedOptimisticIds, sessionID, id);
+            releaseOptimisticId(sessionID, id);
+            const echoId = supersededBy.get(id);
+            if (echoId)
+                recordOptimisticEcho(sessionID, id, echoId);
         }
         // Append surviving optimistic messages at the end
         for (const m of deferredOptimistic) {
@@ -852,7 +1136,38 @@ export const useSyncStore = create()((set, get) => ({
                 }
                 return inP;
             });
-            for (const ep of extras) {
+            // T16 — dedupe extras by content identity. An "extra" is an
+            // existing part whose id the incoming snapshot no longer has — the
+            // server may simply not have persisted it yet (kept, as before), OR
+            // the server RE-ISSUED the same content under a NEW part id (a real
+            // defect: the old SSE-accumulated twin stayed in `exParts` forever,
+            // duplicating the text inside this one message). Distinguish the two
+            // conservatively: drop an extra only when it is text-like AND its own
+            // accumulated text is a PREFIX of (or equal to) some incoming
+            // text-like part of the SAME type — i.e. the incoming copy confidently
+            // re-issues it, not merely resembles it. Non-text-like extras (tool,
+            // permission, file, step, …) are never dropped by content — they carry
+            // distinct identity per id and a coincidental text match doesn't apply
+            // to them at all.
+            //
+            // F1 review finding: an extra still tracked in `deltaActiveParts` (this
+            // session is actively applying deltas to it right now) is EXEMPT from
+            // this filter regardless of what it prefixes. The heuristic above
+            // assumes a text-prefix match means the server re-issued the SAME
+            // content under a new id and the extra is an abandoned twin — but a
+            // live streaming target is never abandoned, and dropping it here also
+            // permanently blocks its later deltas (their event ids would already
+            // be recorded as applied — see `applyPartDelta`'s not-found path).
+            const survivingExtras = extras.filter((extra) => {
+                if (hasTrackedId(deltaActiveParts, sessionID, extra.id))
+                    return true;
+                if (!isTextLikePart(extra) || extra.text.length === 0)
+                    return true;
+                return !inParts.some((inP) => inP.type === extra.type &&
+                    isTextLikePart(inP) &&
+                    inP.text.startsWith(extra.text));
+            });
+            for (const ep of survivingExtras) {
                 const r = Binary.search(reconciled, ep.id, (p) => p.id);
                 if (!r.found)
                     reconciled.splice(r.index, 0, ep);
@@ -867,8 +1182,13 @@ export const useSyncStore = create()((set, get) => ({
     reset: () => {
         optimisticIds.clear();
         dispatchedOptimisticIds.clear();
+        inboxBackedOptimisticIds.clear();
+        optimisticEchoes.clear();
+        optimisticOrigins.clear();
         bridgedPartIds.clear();
         deltaActiveParts.clear();
+        deltaEventTails.clear();
+        stubAssistantIds.clear();
         // The data these holds protected is gone, so the holds are too —
         // otherwise a late unmount could free a session the next page opened.
         sessionConsumers.clear();
@@ -881,6 +1201,8 @@ export const useSyncStore = create()((set, get) => ({
             sessionStatus: {},
             diffs: {},
             todos: {},
+            sessionRevert: {},
+            sessionRevertNeedsTailReconcile: {},
         });
     },
     // ---- Selector: join messages + parts into MessageWithParts[] ----
@@ -912,6 +1234,19 @@ export const useSyncStore = create()((set, get) => ({
                 // optimistic message(s) in a SINGLE atomic set() call.
                 // This prevents the intermediate render where the user bubble
                 // vanishes (optimistic removed) before the real one appears.
+                if (info.role === "user" && isOptimistic(info.sessionID, info.id)) {
+                    // The echo under the optimistic message's OWN id (the host minted
+                    // the wire id and painted with it): confirmed in place. Release the
+                    // marks — it is an ordinary message from here — and bridge the
+                    // optimistic parts until the real ones arrive, so the bubble never
+                    // blinks empty and never shows both.
+                    releaseOptimisticId(info.sessionID, info.id);
+                    if (get().parts[info.id]?.length) {
+                        trackId(bridgedPartIds, info.sessionID, info.id);
+                    }
+                    store.upsertMessage(info.sessionID, info);
+                    return;
+                }
                 if (info.role === "user" && !isOptimistic(info.sessionID, info.id)) {
                     const msgs = get().messages[info.sessionID];
                     if (msgs) {
@@ -960,10 +1295,11 @@ export const useSyncStore = create()((set, get) => ({
                         const matched = byPartId ?? optimisticUsers.find((m) => isDispatched(info.sessionID, m.id));
                         const optIds = matched ? [matched.id] : [];
                         if (optIds.length > 0) {
-                            // Clean up optimistic tracking
+                            // Clean up optimistic tracking, remembering the runtime id
+                            // each superseded message became.
                             for (const id of optIds) {
-                                untrackId(optimisticIds, info.sessionID, id);
-                                untrackId(dispatchedOptimisticIds, info.sessionID, id);
+                                releaseOptimisticId(info.sessionID, id);
+                                recordOptimisticEcho(info.sessionID, id, info.id);
                             }
                             // Atomic: remove optimistic + insert real in one set()
                             set((s) => {
@@ -1102,7 +1438,10 @@ export const useSyncStore = create()((set, get) => ({
                         [props.field]: "",
                     });
                 }
-                store.applyPartDelta(props.sessionID, props.messageID, props.partID, props.field, props.delta);
+                // `event.id` is a top-level field of every wire event (see
+                // `deltaEventTails` above) — never inside `properties`, so it is
+                // read directly off `event`, not `props`.
+                store.applyPartDelta(props.sessionID, props.messageID, props.partID, props.field, props.delta, event.id);
                 if (props.field === "text") {
                     const updated = get().parts[props.messageID]?.find((p) => p.id === props.partID);
                     if (updated && isTextLikePart(updated) && updated.text.length > 0) {
@@ -1128,6 +1467,11 @@ export const useSyncStore = create()((set, get) => ({
                 // still be streaming (see comment above deltaActiveParts).
                 if (sessionID)
                     deltaActiveParts.delete(sessionID);
+                // Same reasoning for the delta event-id tails (T14): a new
+                // turn's deltas use brand-new part ids anyway, so nothing realistic
+                // is lost by dropping this session's tracking here.
+                if (sessionID)
+                    deltaEventTails.delete(sessionID);
                 return;
             }
             case "session.error": {
@@ -1141,6 +1485,7 @@ export const useSyncStore = create()((set, get) => ({
                 // Clear only this session's delta tracking — see the idle handler
                 // above and the comment above deltaActiveParts.
                 deltaActiveParts.delete(sid);
+                deltaEventTails.delete(sid);
                 // Patch the error onto the last assistant message in the sync store.
                 // If no assistant message exists yet, create a temporary one so the
                 // error is visible immediately. The event handler in
@@ -1164,8 +1509,15 @@ export const useSyncStore = create()((set, get) => ({
                         }
                     }
                     // No assistant message yet — create a stub so the error shows.
-                    // Mark it as a client-side stub so hydrate can replace it.
+                    // Tracked in `stubAssistantIds` (T16) so `hydrate` can
+                    // reconcile it away once a real assistant message for this
+                    // session lands — see that map's doc comment and the
+                    // reconciliation in `hydrate` below. `ascendingId('msg')` sorts
+                    // BELOW every server id, which is fine as a placeholder position
+                    // but wrong once real data exists; that is exactly what the
+                    // reconciliation fixes.
                     const stubId = ascendingId("msg");
+                    trackId(stubAssistantIds, sid, stubId);
                     const stubMsg = {
                         id: stubId,
                         sessionID: sid,
@@ -1178,6 +1530,43 @@ export const useSyncStore = create()((set, get) => ({
                 });
                 return;
             }
+            case "session.next.revert.staged": {
+                const props = event.properties;
+                if (props.sessionID && props.revert?.messageID) {
+                    store.stageSessionRevert(props.sessionID, props.revert.messageID);
+                }
+                return;
+            }
+            case "session.next.revert.cleared": {
+                const props = event.properties;
+                if (props.sessionID)
+                    store.clearSessionRevert(props.sessionID);
+                return;
+            }
+            case "session.next.revert.committed": {
+                const props = event.properties;
+                if (props.sessionID && props.messageID) {
+                    const tracked = get().sessionRevert[props.sessionID];
+                    if (tracked) {
+                        store.applyCommittedRevert(props.sessionID, props.messageID, tracked.watermark);
+                    }
+                    else {
+                        // F2 — no tracked local record (fresh mount / second tab that
+                        // never saw `.staged`). The REMOVED fallback guessed a
+                        // watermark from `newestMessageId(local messages)`, which can
+                        // be the user's own REPLACEMENT prompt if its
+                        // `message.updated` arrived before this `.committed` event —
+                        // deleting the replacement and its answer. Do not guess: flag
+                        // this session for a tail reconcile (see
+                        // `markSessionRevertNeedsTailReconcile`'s doc comment) and
+                        // leave messages alone. The server's actual (already-
+                        // truncated) transcript arrives through whatever reads that
+                        // flag.
+                        store.markSessionRevertNeedsTailReconcile(props.sessionID);
+                    }
+                }
+                return;
+            }
             case "session.diff": {
                 const props = event.properties;
                 if (props.sessionID)