@kortix/sdk 0.12.8 → 0.13.1

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,71 @@ 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();
+// Message ids the CONTROL PLANE still owns after the runtime confirmed them:
+// the echo (same id or re-minted) of an inbox-backed optimistic send. The
+// server can take such a message back out of the runtime and place it again
+// under a new id — a stranded mid-turn prompt being re-placed, a Stop taking
+// an unread prompt back into the queue. A `message.removed` for one of these
+// is not "the message is gone", it is "the message is between two ids": the
+// bubble is re-marked optimistic (dispatched, inbox-backed) and the next echo
+// supersedes it, instead of the bubble blinking out and a new one appearing.
+// Released with the session.
+const controlPlaneOwnedIds = new Map();
+// Message ids the user explicitly CANCELLED (`DELETE .../prompts`). The
+// runtime may keep a part-less husk of the message (a busy loop refuses the
+// whole-message delete; the parts are emptied instead), and every later
+// transcript read would resurrect it as an empty bubble. A tombstoned id is
+// dropped from incoming reads and events. Released with the session.
+const cancelledMessageIds = new Map();
+// Message ids that came from the DISK CACHE and have not yet been seen in a
+// runtime read. The cache is a first-paint accelerator; a message it holds
+// that the runtime's own tail — covering that message's position — does not,
+// never existed there (an optimistic stub mirrored to disk before its echo)
+// and must not outlive the first authoritative read.
+const cacheSourcedIds = new Map();
+function recordOptimisticEcho(sessionID, optimisticID, echoID) {
+    if (optimisticID === echoID)
+        return;
+    // Chain through an earlier swap: a message that itself superseded an
+    // optimistic id keeps pointing the host at that ORIGINAL id, so a second
+    // re-placement does not change the identity the host keyed its bubble on.
+    const origin = optimisticOrigins.get(sessionID)?.get(optimisticID) ?? optimisticID;
+    let fwd = optimisticEchoes.get(sessionID);
+    if (!fwd)
+        optimisticEchoes.set(sessionID, (fwd = new Map()));
+    fwd.set(origin, echoID);
+    if (origin !== optimisticID)
+        fwd.set(optimisticID, echoID);
+    let rev = optimisticOrigins.get(sessionID);
+    if (!rev)
+        optimisticOrigins.set(sessionID, (rev = new Map()));
+    rev.set(echoID, origin);
+}
+/** 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);
+}
+/** The runtime confirmed an inbox-backed optimistic send under `echoID`
+ *  (same id, or re-minted): the control plane still owns that message. */
+function releaseConfirmedOptimisticId(sessionID, optimisticID, echoID) {
+    if (hasTrackedId(inboxBackedOptimisticIds, sessionID, optimisticID)) {
+        trackId(controlPlaneOwnedIds, sessionID, echoID);
+    }
+    releaseOptimisticId(sessionID, optimisticID);
+}
 function trackId(store, sessionID, id) {
     const bucket = store.get(sessionID);
     if (bucket)
@@ -49,6 +139,12 @@ function hasTrackedId(store, sessionID, id) {
 function forgetSessionIds(sessionID) {
     optimisticIds.delete(sessionID);
     dispatchedOptimisticIds.delete(sessionID);
+    inboxBackedOptimisticIds.delete(sessionID);
+    optimisticEchoes.delete(sessionID);
+    optimisticOrigins.delete(sessionID);
+    controlPlaneOwnedIds.delete(sessionID);
+    cacheSourcedIds.delete(sessionID);
+    cancelledMessageIds.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 +161,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 +196,137 @@ 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, except the value
+ *  is a MAP: stub message id → the id of the user message whose turn failed
+ *  (`null` only when the session held no user message at all).
+ *
+ *  The parent is tracked, not merely implied, because every question asked
+ *  about a stub afterwards is a question about its TURN. A stub stands in for
+ *  the assistant message that turn never produced, so `hydrate` may drop it
+ *  only once the server's transcript answers THAT turn — a session-wide "any
+ *  assistant message exists" test deleted the only record of a failure the
+ *  moment an EARLIER turn's reply arrived (the 2026-08-19 report: the first
+ *  `ModelNotFound` rendered nothing at all).
+ *
+ *  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();
+/** Remember `stubId` as this session's stand-in for the turn `parentId` opened. */
+function trackStub(sessionID, stubId, parentId) {
+    const bucket = stubAssistantIds.get(sessionID);
+    if (bucket)
+        bucket.set(stubId, parentId);
+    else
+        stubAssistantIds.set(sessionID, new Map([[stubId, parentId]]));
+}
+function untrackStub(sessionID, stubId) {
+    const bucket = stubAssistantIds.get(sessionID);
+    if (!bucket)
+        return;
+    bucket.delete(stubId);
+    if (bucket.size === 0)
+        stubAssistantIds.delete(sessionID);
+}
+/** The stub id for the turn `userId` opened.
+ *
+ *  Derived from the user message's own id, for two reasons. It is IDEMPOTENT —
+ *  a second `session.error` for the same turn finds the stub it already made
+ *  instead of appending another. And it SORTS immediately after that user
+ *  message: every id the store handles has the same length, so an id that
+ *  extends `userId` byte for byte precedes every id greater than `userId` and
+ *  follows `userId` itself. Position and `parentID` therefore agree, whichever
+ *  of the two a reader uses. */
+const stubIdFor = (userId) => `${userId}_error`;
+/** A stub id as seen from a list that has no tracking map to hand (`hydrate`'s
+ *  incoming server snapshot, which can never legitimately contain one). */
+const isStubShaped = (id) => id.endsWith("_error");
+/** Does `messages` hold an assistant message answering the turn `parentId`
+ *  opened? `parentID` is the linkage `groupMessagesIntoTurns` reads; the id
+ *  comparison covers a wire assistant message that carries none (ids ascend,
+ *  so a greater id is a later message). With no parent turn to speak of, any
+ *  assistant message answers. */
+function hasAssistantForTurn(messages, parentId) {
+    return messages.some((m) => m.role === "assistant" &&
+        !isStubShaped(m.id) &&
+        (!parentId || m.parentID === parentId || (!m.parentID && m.id > parentId)));
+}
+/** Move this session's `session.error` stubs from the optimistic user message
+ *  `fromId` onto the server's own copy of that prompt, `toId`.
+ *
+ *  Both paths that retire an optimistic user message call this — `hydrate`'s
+ *  correlation and the `message.updated` echo — because a stub whose parent id
+ *  no longer names a message in the list has lost the only link that says which
+ *  turn failed, and `groupMessagesIntoTurns` would fall back to "the last turn
+ *  seen", i.e. the bottom of the thread. Returns the list unchanged when this
+ *  session has no stub on `fromId`. */
+function rekeyStubParent(sessionID, list, fromId, toId) {
+    const bucket = stubAssistantIds.get(sessionID);
+    if (!bucket)
+        return list;
+    const moved = [...bucket.entries()].filter(([, parentId]) => parentId === fromId);
+    if (moved.length === 0)
+        return list;
+    let next = [...list];
+    for (const [stubId] of moved) {
+        untrackStub(sessionID, stubId);
+        const idx = next.findIndex((m) => m.id === stubId);
+        if (idx === -1)
+            continue;
+        const nextId = stubIdFor(toId);
+        trackStub(sessionID, nextId, toId);
+        const rekeyed = { ...next[idx], id: nextId, parentID: toId };
+        next.splice(idx, 1);
+        const parentIdx = next.findIndex((m) => m.id === toId);
+        if (parentIdx === -1)
+            next = [...next, rekeyed];
+        else
+            next.splice(parentIdx + 1, 0, rekeyed);
+    }
+    return next;
+}
+// ---------------------------------------------------------------------------
 // Session retention — how a transcript ever LEAVES memory again.
 //
 // `messages` and `parts` are keyed by session and nothing removed a key.
@@ -315,6 +545,8 @@ export const useSyncStore = create()((set, get) => ({
     sessionStatus: {},
     diffs: {},
     todos: {},
+    sessionRevert: {},
+    sessionRevertNeedsTailReconcile: {},
     // Compat alias
     get statuses() {
         return get().sessionStatus;
@@ -372,22 +604,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 +695,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 +704,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 +739,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 +869,52 @@ 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),
+    isOptimisticMessage: (sessionID, messageID) => isOptimistic(sessionID, messageID),
+    forgetControlPlaneMessage: (sessionID, messageID) => {
+        untrackId(controlPlaneOwnedIds, sessionID, messageID);
+        releaseOptimisticId(sessionID, messageID);
+        trackId(cancelledMessageIds, sessionID, messageID);
+        get().removeMessage(sessionID, messageID);
+    },
+    registerOptimisticEcho: (sessionID, optimisticID, echoID) => {
+        if (!isOptimistic(sessionID, optimisticID))
+            return;
+        if (optimisticID === echoID)
+            return;
+        recordOptimisticEcho(sessionID, optimisticID, echoID);
+    },
+    reclaimRemovedMessage: (sessionID, messageID) => {
+        // See `controlPlaneOwnedIds`: a removal of a message the control plane
+        // still owns is a re-placement in progress, not a deletion. Keep the
+        // message and its parts; put the optimistic marks back (dispatched, so
+        // the ordinal echo match may claim it; inbox-backed, so the idle sweep
+        // leaves it) and let the next echo supersede it.
+        if (!hasTrackedId(controlPlaneOwnedIds, sessionID, messageID))
+            return false;
+        const list = get().messages[sessionID];
+        const message = list?.find((m) => m.id === messageID);
+        if (!message || message.role !== "user")
+            return false;
+        untrackId(controlPlaneOwnedIds, sessionID, messageID);
+        trackId(optimisticIds, sessionID, messageID);
+        trackId(dispatchedOptimisticIds, sessionID, messageID);
+        trackId(inboxBackedOptimisticIds, sessionID, messageID);
+        return true;
+    },
     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 +938,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 +976,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) => {
@@ -660,19 +1055,76 @@ export const useSyncStore = create()((set, get) => ({
         touchSessionMessageRows(sessionID, { msgs, partRefs, result });
         return result;
     },
-    hydrate: (sessionID, msgs) => set((s) => {
+    hydrate: (sessionID, msgs, opts) => set((s) => {
         // An authoritative load — the disk repaint itself, or a reconcile —
         // re-establishes the session, so its entry is no longer a fragment.
         evictedSessions.delete(sessionID);
         const cmp = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+        const tombstones = cancelledMessageIds.get(sessionID);
         const incoming = msgs
-            .filter((m) => !!m?.info?.id)
+            .filter((m) => !!m?.info?.id && !tombstones?.has(m.info.id))
             .map((m) => m.info)
             .sort((a, b) => cmp(a.id, b.id));
+        const fromCache = opts?.source === "cache";
+        if (fromCache) {
+            for (const m of incoming)
+                trackId(cacheSourcedIds, sessionID, m.id);
+        }
+        // A RUNTIME read settles the cache's provisional messages: the ones
+        // it contains are real; the ones it lacks but whose position it
+        // COVERS (at or above the oldest message it returned) never existed
+        // there and are dropped. Older ones are history the bounded tail did
+        // not reach — kept, still provisional.
+        let droppedPhantoms = null;
+        const provisional = fromCache ? undefined : cacheSourcedIds.get(sessionID);
+        if (provisional && provisional.size > 0 && incoming.length > 0) {
+            const oldestIncoming = incoming[0].id;
+            const incomingIds = new Set(incoming.map((m) => m.id));
+            for (const id of [...provisional]) {
+                if (incomingIds.has(id)) {
+                    untrackId(cacheSourcedIds, sessionID, id);
+                    continue;
+                }
+                if (cmp(id, oldestIncoming) >= 0 && !isOptimistic(sessionID, id)) {
+                    untrackId(cacheSourcedIds, sessionID, id);
+                    (droppedPhantoms ??= new Set()).add(id);
+                }
+            }
+        }
+        // T16 — a `session.error` stub assistant message is reconciled
+        // PER TURN, after the optimistic correlation below has run (see
+        // `pendingStubs`). It only ever stood in for the assistant message
+        // its own turn never produced, so the question is not "does this
+        // session have an assistant message" — an earlier turn's answer is
+        // no answer at all — but "does the server now answer THAT turn".
+        // Re-adopt a stub that arrives IN the snapshot. The transcript cache
+        // mirrors `messages[sessionID]` to IndexedDB, stubs included, so the
+        // first paint after a reload brings one back — while
+        // `stubAssistantIds` (module state) did not survive the reload. An
+        // unadopted stub is unreconcilable: it would sit beside the server's
+        // own reply forever. Only the runtime ever produces these ids, so
+        // nothing else can be mistaken for one.
+        for (const info of incoming) {
+            if (info.role !== "assistant" || !isStubShaped(info.id))
+                continue;
+            if (!info.error)
+                continue;
+            if (stubAssistantIds.get(sessionID)?.has(info.id))
+                continue;
+            trackStub(sessionID, info.id, info.parentID ?? null);
+        }
+        const trackedStubIds = stubAssistantIds.get(sessionID);
+        /** Stubs held back from the merge below until their parent turn is
+         *  known (an optimistic parent may be superseded by the server's own
+         *  copy in this very snapshot). */
+        const pendingStubs = [];
         // 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).
-        const existing = s.messages[sessionID] ?? [];
+        const existingAll = s.messages[sessionID] ?? [];
+        const existing = droppedPhantoms
+            ? existingAll.filter((m) => !droppedPhantoms.has(m.id))
+            : existingAll;
         const merged = [];
         const seen = new Set();
         // Which optimistic user messages has the server actually echoed?
@@ -689,6 +1141,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;
+            releaseConfirmedOptimisticId(sessionID, m.id, 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 +1191,13 @@ export const useSyncStore = create()((set, get) => ({
         const unmatchedOptimisticUsers = [];
         for (const m of existing) {
             if (!seen.has(m.id)) {
+                if (trackedStubIds?.has(m.id)) {
+                    // Placed (or dropped) after the correlation passes below,
+                    // because where it belongs depends on what happened to the
+                    // user message it is parented to.
+                    pendingStubs.push(m);
+                    continue;
+                }
                 if (isOptimistic(sessionID, m.id)) {
                     if (m.role !== "user") {
                         deferredOptimistic.push(m);
@@ -755,10 +1229,24 @@ export const useSyncStore = create()((set, get) => ({
         // duplicate of anything the server holds, so it is never eligible.
         // That restriction is what keeps a message sent from another tab from
         // consuming this tab's in-flight bubble.
-        const claimable = candidateEchoes.filter((m) => unclaimedEchoes.has(m.id));
+        const claimed = new Set();
+        for (const m of unmatchedOptimisticUsers) {
+            // Alias first: the inbox row announced this message's echo id.
+            const alias = optimisticEchoes.get(sessionID)?.get(m.id);
+            if (alias && unclaimedEchoes.has(alias) && !claimed.has(alias)) {
+                claimed.add(alias);
+                supersededOptimistic.push(m.id);
+                supersededBy.set(m.id, alias);
+            }
+        }
+        const claimable = candidateEchoes.filter((m) => unclaimedEchoes.has(m.id) && !claimed.has(m.id));
         let next = 0;
         for (const m of unmatchedOptimisticUsers) {
-            const echo = isDispatched(sessionID, m.id)
+            if (supersededBy.has(m.id))
+                continue;
+            const echo = isDispatched(sessionID, m.id) &&
+                // Known-different echo → never consume someone else's.
+                !optimisticEchoes.get(sessionID)?.get(m.id)
                 ? claimable[next]
                 : undefined;
             if (echo) {
@@ -770,21 +1258,81 @@ 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);
+            const echoId = supersededBy.get(id);
+            if (echoId) {
+                releaseConfirmedOptimisticId(sessionID, id, echoId);
+                recordOptimisticEcho(sessionID, id, echoId);
+            }
+            else {
+                releaseOptimisticId(sessionID, id);
+            }
         }
         // Append surviving optimistic messages at the end
         for (const m of deferredOptimistic) {
             merged.push(m);
         }
+        // Now place (or retire) each `session.error` stub, with its turn
+        // finally settled. Three outcomes, in order:
+        //
+        //  - its user message was superseded by the server's own copy in this
+        //    snapshot → the stub follows it, re-keyed onto the real id;
+        //  - the server now holds a real assistant message for that turn →
+        //    the stub was a stand-in for exactly that message, so it goes;
+        //  - otherwise → it stays, directly after its user message. This is
+        //    the case the reported bug turned on: the `reconcileTail` that
+        //    every `session.error` triggers returns a transcript with NO
+        //    reply for the failed turn, and dropping the stub there left the
+        //    user staring at their own prompt and nothing else.
+        for (const stub of pendingStubs) {
+            const trackedParent = trackedStubIds?.get(stub.id) ?? null;
+            const parentId = (trackedParent && supersededBy.get(trackedParent)) || trackedParent;
+            untrackStub(sessionID, stub.id);
+            // The server DOES hold a reply for this turn — the stub stood in
+            // for exactly that message, so it goes. Its error moves onto the
+            // real message first, unless the server's copy carries one of its
+            // own: `session.error` is the runtime's report of THIS turn
+            // failing, and the transcript read that follows it does not always
+            // carry the failure back (the same race
+            // `use-opencode-events`'s cache patch exists for). Dropping the
+            // stub against an error-free server copy would erase the only
+            // evidence the turn failed.
+            if (hasAssistantForTurn(incoming, parentId)) {
+                const replyIdx = merged.findIndex((m) => m.role === "assistant" &&
+                    !isStubShaped(m.id) &&
+                    (!parentId || m.parentID === parentId || (!m.parentID && m.id > parentId)));
+                const reply = replyIdx === -1 ? undefined : merged[replyIdx];
+                const stubError = stub.error;
+                if (reply && !reply.error && stubError) {
+                    merged[replyIdx] = { ...reply, error: stubError };
+                }
+                continue;
+            }
+            const stubId = parentId ? stubIdFor(parentId) : stub.id;
+            const placed = stubId === stub.id && stub.parentID === (parentId ?? undefined)
+                ? stub
+                : { ...stub, id: stubId, ...(parentId ? { parentID: parentId } : {}) };
+            trackStub(sessionID, stubId, parentId);
+            const parentIdx = parentId ? merged.findIndex((m) => m.id === parentId) : -1;
+            if (parentIdx !== -1) {
+                merged.splice(parentIdx + 1, 0, placed);
+                continue;
+            }
+            const r = Binary.search(merged, placed.id, (x) => x.id);
+            if (!r.found)
+                merged.splice(r.index, 0, placed);
+        }
         // Merge parts: for each message, reconcile by part ID.
         // If a message is optimistic (still in optimisticIds), keep existing
         // parts entirely — they're from the client and shouldn't be overwritten.
         // Otherwise, incoming parts win (server is authoritative), but keep
         // any extra parts from SSE that aren't in the fetch response.
         const newParts = { ...s.parts };
+        if (droppedPhantoms)
+            for (const id of droppedPhantoms)
+                delete newParts[id];
         // When superseding an optimistic user message, bridge its parts to
         // the real user message ID if the server hasn't sent parts yet.
         // Mirrors the message.updated SSE handler (see above) — without
@@ -852,7 +1400,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 +1446,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 +1465,8 @@ export const useSyncStore = create()((set, get) => ({
             sessionStatus: {},
             diffs: {},
             todos: {},
+            sessionRevert: {},
+            sessionRevertNeedsTailReconcile: {},
         });
     },
     // ---- Selector: join messages + parts into MessageWithParts[] ----
@@ -908,10 +1494,26 @@ export const useSyncStore = create()((set, get) => ({
                 const info = event.properties.info;
                 if (!info?.sessionID)
                     return;
+                // The user cancelled this message; the runtime's husk stays dead.
+                if (cancelledMessageIds.get(info.sessionID)?.has(info.id))
+                    return;
                 // When a real user message arrives from the server, swap out the
                 // 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) {
@@ -957,13 +1559,30 @@ export const useSyncStore = create()((set, get) => ({
                         // matching: at `message.updated` time the confirmed message
                         // usually has no parts in the store yet (they arrive separately
                         // via `message.part.updated`).
-                        const matched = byPartId ?? optimisticUsers.find((m) => isDispatched(info.sessionID, m.id));
+                        // A pre-registered alias (`registerOptimisticEcho`) is an identity
+                        // match: the row named this echo id before it arrived.
+                        const byAlias = optimisticUsers.find((m) => optimisticEchoes.get(info.sessionID)?.get(m.id) === info.id);
+                        // The ordinal guess is only safe when there is exactly ONE
+                        // in-flight send it could be. With a burst in flight, a
+                        // part-less echo that matches neither a part id nor a
+                        // registered alias WAITS: the hydrate that follows carries
+                        // the parts (identity match), and consuming the oldest
+                        // bubble here handed one message's echo another message's
+                        // text (measured: the first bubble of a burst vanished).
+                        const eligible = optimisticUsers.filter((m) => isDispatched(info.sessionID, m.id) &&
+                            // An optimistic message whose OWN echo is known to be a
+                            // DIFFERENT id must not be consumed by someone else's.
+                            !optimisticEchoes.get(info.sessionID)?.get(m.id));
+                        const matched = byPartId ?? byAlias ?? (eligible.length === 1 ? eligible[0] : undefined);
+                        if (!matched && eligible.length > 1)
+                            return;
                         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);
+                                releaseConfirmedOptimisticId(info.sessionID, id, info.id);
+                                recordOptimisticEcho(info.sessionID, id, info.id);
                             }
                             // Atomic: remove optimistic + insert real in one set()
                             set((s) => {
@@ -972,13 +1591,20 @@ export const useSyncStore = create()((set, get) => ({
                                 const without = list.filter((m) => !optIds.includes(m.id));
                                 // Insert the real message at sorted position
                                 const r = Binary.search(without, info.id, (m) => m.id);
-                                const next = [...without];
+                                let next = [...without];
                                 if (r.found) {
                                     next[r.index] = info;
                                 }
                                 else {
                                     next.splice(r.index, 0, info);
                                 }
+                                // A turn that failed before this confirmation arrived
+                                // has a `session.error` stub keyed to the optimistic id
+                                // being retired here. Re-key it, or its error detaches
+                                // from the turn and drifts to the bottom of the thread.
+                                for (const id of optIds) {
+                                    next = rekeyStubParent(info.sessionID, next, id, info.id);
+                                }
                                 // Bridge optimistic parts to the real message ID so
                                 // the user bubble never flickers empty while waiting
                                 // for real parts to arrive via message.part.updated.
@@ -1010,6 +1636,8 @@ export const useSyncStore = create()((set, get) => ({
                 const props = event.properties;
                 if (!props.sessionID || !props.messageID)
                     return;
+                if (store.reclaimRemovedMessage(props.sessionID, props.messageID))
+                    return;
                 store.removeMessage(props.sessionID, props.messageID);
                 return;
             }
@@ -1102,7 +1730,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 +1759,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,43 +1777,119 @@ 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);
-                // 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
-                // use-opencode-events.ts will also fetch real messages from the
-                // server which will bring in the authoritative data via hydrate().
+                deltaEventTails.delete(sid);
+                // Attach the error to the TURN THAT FAILED, which is the turn the
+                // last user message opened: `session.error` terminates the turn the
+                // runtime was running, and the runtime runs one at a time.
+                //
+                // When that turn already produced an assistant message the error is
+                // patched onto it, as before. When it produced none — the whole
+                // class of failures that die before generation starts, e.g.
+                // `ModelNotFound`, which arrives ~2ms after the prompt — a stub
+                // assistant message stands in for it, parented to that user message
+                // and positioned directly after it.
+                //
+                // It used to be "the last assistant message ANYWHERE, else append a
+                // stub at the end", and both halves put the error in the wrong turn:
+                // the patch landed on the previous turn's answer (where the
+                // `reconcileTail` hydrate that follows every `session.error` then
+                // overwrote it with the server's error-free copy, so the failure
+                // rendered NOTHING), and the appended stub rode the bottom of the
+                // thread, reappearing under whichever prompt came next.
+                //
+                // The event handler in use-opencode-events.ts also fetches real
+                // messages from the server, which brings in the authoritative data
+                // via hydrate().
                 set((s) => {
                     const msgs = s.messages[sid] ?? [];
-                    // Find last assistant message and patch .error onto it
+                    // The prompt this error answers.
+                    let userIdx = -1;
                     for (let i = msgs.length - 1; i >= 0; i--) {
-                        const msg = msgs[i];
-                        if (msg.role === "assistant") {
-                            if (msg.error)
-                                return s; // already has error
-                            const next = [...msgs];
-                            // `error` may be the client-synthesized `SyntheticAbortError`
-                            // (see `MessageError`), which the SDK's own `AssistantMessage.error`
-                            // union doesn't declare — the assertion is the documented, narrow
-                            // exception for that one extra shape.
-                            next[i] = { ...msg, error };
-                            return { messages: { ...s.messages, [sid]: next } };
+                        if (msgs[i].role === "user") {
+                            userIdx = i;
+                            break;
                         }
                     }
-                    // No assistant message yet — create a stub so the error shows.
-                    // Mark it as a client-side stub so hydrate can replace it.
-                    const stubId = ascendingId("msg");
+                    const userId = userIdx === -1 ? null : msgs[userIdx].id;
+                    // An assistant message that already belongs to THAT turn takes
+                    // the error. Scanning back only as far as the user message is
+                    // what keeps an earlier turn's answer out of it.
+                    for (let i = msgs.length - 1; i > userIdx; i--) {
+                        const msg = msgs[i];
+                        if (msg.role !== "assistant")
+                            continue;
+                        if (userId && msg.parentID && msg.parentID !== userId)
+                            continue;
+                        if (msg.error)
+                            return s; // already has error
+                        const next = [...msgs];
+                        // `error` may be the client-synthesized `SyntheticAbortError`
+                        // (see `MessageError`), which the SDK's own `AssistantMessage.error`
+                        // union doesn't declare — the assertion is the documented, narrow
+                        // exception for that one extra shape.
+                        next[i] = { ...msg, error };
+                        return { messages: { ...s.messages, [sid]: next } };
+                    }
+                    // No assistant message for this turn yet — stand one in so the
+                    // error renders under the prompt it answers. Tracked in
+                    // `stubAssistantIds` (T16) with its parent so `hydrate` can
+                    // reconcile it away once the server's own transcript answers
+                    // THAT turn — see that map's doc comment and the reconciliation
+                    // in `hydrate` below.
+                    const stubId = userId ? stubIdFor(userId) : ascendingId("msg");
+                    if (msgs.some((m) => m.id === stubId))
+                        return s;
+                    trackStub(sid, stubId, userId);
                     const stubMsg = {
                         id: stubId,
                         sessionID: sid,
                         role: "assistant",
+                        ...(userId ? { parentID: userId } : {}),
                         error,
                     };
-                    return {
-                        messages: { ...s.messages, [sid]: [...msgs, stubMsg] },
-                    };
+                    const next = [...msgs];
+                    next.splice(userIdx === -1 ? next.length : userIdx + 1, 0, stubMsg);
+                    return { messages: { ...s.messages, [sid]: next } };
                 });
                 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)