mixdog 1.2.3 → 1.2.4

package/src/tui/session/cross-surface-share.mjs

@@ -1,406 +0,0 @@
-/**
- * src/tui/session/cross-surface-share.mjs - owner/viewer wiring for one session
- * opened on several surfaces (terminal + desktop pane).
- *
- * Presence + the durable pending spool remain the ownership/base layer; a
- * local pipe layer (live-share) streams frame deltas so co-open surfaces
- * mirror each other in real time.
- *  - presence: mark OUR current session as held open (idle included) so a
- *    cross-open elsewhere attaches as a viewer instead of splitting
- *    ownership; cleared on session switch here and on dispose
- *    (session-api-ext), with sidecar staleness covering crashes.
- *  - owner leg: host the live pipe, push transcript/tail/spinner deltas,
- *    and run foreign submits through the normal queue — full user bubble +
- *    streaming on every surface. The spool drain stays as the fallback
- *    intake (instant via fs.watch, 3s tick as safety net).
- *  - viewer leg: connect to the owner's pipe and mirror its live state.
- *    While the pipe is up the disk-mtime re-resume is skipped (no turn-end
- *    flicker); when the owner disappears the quiet re-resume promotes this
- *    surface to real ownership.
- */
-import { statSync } from 'node:fs';
-import { basename, dirname } from 'node:path';
-import { sessionPath } from '../../runtime/agent/orchestrator/session/store/paths-heartbeat.mjs';
-import { createLiveShare, forwardViewerSubmit, liveSharePipePath } from './live-share.mjs';
-import { promptDisplayText } from './queue-helpers.mjs';
-import { sharedDirWatch } from './shared-dir-watch.mjs';
-
-const SPOOL_WATCH_DEBOUNCE_MS = 120;
-const OWNER_CLOSED_PROMOTE_DELAY_MS = 1500;
-const REMOTE_ATTACH_TICK_MS = 3000;
-// A healthy local owner serves its full frame on connect within tens of ms; a
-// dead presence sidecar or an owner blocked mid-turn never will. The old
-// 1500ms default made exactly those sessions stall entry for the full budget
-// (measured 1571/1519ms resumes — user: 세션 로드가 가끔 매우 느림). Cap the
-// boundary wait low: late owner frames still land through viewerApply and
-// simply replace the disk restore when they arrive.
-const VIEWER_SYNC_WAIT_MS = 400;
-
-// The spool drain waits for its cross-process lock OFF the event loop now, so
-// a watch event and the 3s tick can overlap: one drain at a time.
-function createRemoteInjectionDrain({ runtime, bag }) {
-  let inFlight = null;
-  return () => {
-    if (inFlight) return inFlight;
-    const run = (async () => {
-      const injected = (await runtime.takeRemoteInjections?.()) || [];
-      if (injected.length === 0) return;
-      for (const item of injected) {
-        if (!item || typeof item !== 'object' || (item.text == null && item.content == null)) continue;
-        const content = item.content ?? item.text;
-        const id = typeof item.id === 'string' && item.id.trim() ? item.id.trim() : undefined;
-        bag.enqueue(content, {
-          ...(item.options && typeof item.options === 'object' ? item.options : {}),
-          ...(item.text ? { displayText: item.text } : {}),
-          ...(id ? { id } : {}),
-        });
-      }
-      void bag.drain();
-    })().catch(() => {
-      /* the watch/tick pair retries */
-    });
-    const tracked = run.finally(() => {
-      if (inFlight === tracked) inFlight = null;
-    });
-    inFlight = tracked;
-    return tracked;
-  };
-}
-
-const quietResume = (api, id) =>
-  void Promise.resolve(api.resume(id, { quiet: true })).catch(() => {
-    /* next tick retries */
-  });
-
-function createSessionLiveShare({ api, bag, flags, getState, getPublishedState, listeners, set, createShare }) {
-  const liveShare = createShare({
-    ownerSessionId: () => {
-      const state = getState();
-      return flags.disposed || flags.pendingSessionReset || state.sessionRemoteAttached
-        ? ''
-        : String(state.sessionId || '');
-    },
-    viewerSessionId: () => {
-      const state = getState();
-      return flags.disposed || !state.sessionRemoteAttached ? '' : String(state.sessionId || '');
-    },
-    socketPathFor: (id) => liveSharePipePath(id, sessionPath(id)),
-    getPublishedState,
-    listeners,
-    onRemoteSubmit: (prompt, meta) => {
-      // A refusal must be REPORTED, never silent. This session runtime can be unable to
-      // take a foreign prompt (disposed, or it became an attached viewer
-      // itself); swallowing it here is what made a submitted message vanish
-      // with no transcript row and no error (user: 입력이 씹힘). The ack sent
-      // by live-share carries this verdict back so the sender can re-deliver.
-      if (flags.disposed || getState().sessionRemoteAttached) return false;
-      // Preserve the viewer's submission id end-to-end: the queue entry and
-      // the settled user item then carry the id the submitting surface used
-      // for its optimistic row, so that row releases instead of duplicating.
-      const queued = bag.enqueue(prompt, meta && typeof meta === 'object' ? meta : {}) !== false;
-      void bag.drain();
-      return queued;
-    },
-    onRemoteAbort: () => {
-      // Forwarded viewer stop: interrupt OUR active turn (we are the owner).
-      if (flags.disposed || getState().sessionRemoteAttached) return;
-      try {
-        api.abort?.();
-      } catch {
-        /* abort is best-effort */
-      }
-    },
-    onOwnerClosed: (id) => {
-      // Owner left (clean close or crash): promote via the normal quiet
-      // re-resume once its final save/presence-clear has landed.
-      const timer = setTimeout(() => {
-        const state = getState();
-        if (flags.disposed || !state.sessionRemoteAttached) return;
-        if (String(state.sessionId || '') !== id) return;
-        if (liveShare.viewerConnected()) return;
-        quietResume(api, id);
-      }, OWNER_CLOSED_PROMOTE_DELAY_MS);
-      timer.unref?.();
-    },
-    viewerApply: {
-      getState,
-      set,
-      replaceItems: (...args) => bag.replaceItems(...args),
-      patchItem: (...args) => bag.patchItem(...args),
-      appendItems: (...args) => bag.appendItems(...args),
-      updateStreamingTail: (...args) => bag.updateStreamingTail(...args),
-      clearStreamingTail: (...args) => bag.clearStreamingTail(...args),
-    },
-  });
-  return liveShare;
-}
-
-// Viewer legs ride the owner's pipe (instant user bubble + shared streaming);
-// the durable spool remains the fallback. Every intake boundary the daemon or
-// UI can reach (submit, submitAsync, abort) is wrapped, otherwise a hosted
-// viewer queues the prompt locally and its own user row stands beside the
-// owner's mirrored twin.
-function wrapViewerApi({ api, bag, runtime, liveShare, getState, ensureLiveShare }) {
-  // Returns null when this surface is NOT an attached viewer, so the local
-  // session runtime keeps the prompt.
-  const viewerSubmitIntake = (prompt, options = {}) => {
-    if (!getState().sessionRemoteAttached) return null;
-    const text = String(promptDisplayText(prompt, options) || '').trim();
-    if (!text) return { accepted: false };
-    return {
-      accepted: forwardViewerSubmit({
-        prompt,
-        text,
-        options,
-        share: liveShare,
-        // Writing to the owner's spool instead of starting a fake local turn
-        // that would render an error/synthetic assistant message here.
-        spool: (submissionId) =>
-          runtime.enqueueRemoteAttachedPrompt?.({
-            content: prompt,
-            text,
-            id: submissionId,
-            options,
-          }) === true,
-      }),
-    };
-  };
-  if (typeof api.submit === 'function') {
-    const baseSubmit = api.submit;
-    api.submit = (prompt, options = {}) => {
-      const forwarded = viewerSubmitIntake(prompt, options);
-      return forwarded ? forwarded.accepted : baseSubmit(prompt, options);
-    };
-  }
-  if (typeof api.submitAsync === 'function') {
-    const baseSubmitAsync = api.submitAsync;
-    api.submitAsync = async (prompt, options = {}) => {
-      const forwarded = viewerSubmitIntake(prompt, options);
-      return forwarded ? forwarded.accepted : baseSubmitAsync(prompt, options);
-    };
-  }
-  // Viewer stop button: the local session runtime has no in-flight turn to
-  // cancel — forward the interrupt to the owner over the pipe. Falls back to
-  // the local abort (no-op safe) when the pipe is down.
-  if (typeof api.abort === 'function') {
-    const baseAbort = api.abort;
-    api.abort = (...args) => {
-      if (getState().sessionRemoteAttached && liveShare.viewerConnected() && liveShare.sendAbort()) {
-        return true;
-      }
-      return baseAbort(...args);
-    };
-  }
-  // Attach-time pipe fast-path: session entry (resume) reconciles the live
-  // pipe IMMEDIATELY instead of waiting for the 3s share tick. The attach
-  // render comes from the last disk save WITHOUT the in-flight turn, so that
-  // tick-wide window is exactly when a running tool call / mid-turn
-  // conversation looks missing and then pops in late (user report). The
-  // owner leg benefits equally: its pipe server starts the moment the
-  // session opens, so cross-surface viewers can connect at once.
-  for (const method of ['resume', 'newSession', 'switchContext']) {
-    if (typeof api[method] !== 'function') continue;
-    const base = api[method].bind(api);
-    api[method] = async (...args) => {
-      const result = await base(...args);
-      bag.cancelQueuedGoalContinuations?.();
-      bag.refreshGoalState?.();
-      bag.scheduleGoalContinuation?.();
-      ensureLiveShare();
-      if (method === 'resume' && result === true && getState().sessionRemoteAttached) {
-        const id = String(getState().sessionId || '');
-        // The session projection holds renderer publications across resume.
-        // Keep that hold until the owner's first FULL frame replaces the
-        // persisted transcript, then synchronously publish the complete draft
-        // before getState().
-        if (id && (await liveShare.waitForViewerSync(id, VIEWER_SYNC_WAIT_MS))) bag.flushEmit();
-      }
-      return result;
-    };
-  }
-}
-
-// Instant input pickup: watch the shared pending spool so an attached
-// surface's fallback submit reaches this owner immediately instead of on the
-// 3s tick. Best-effort — the tick remains the safety net. The spool sits
-// directly in the data dir, so that is the narrowest directory to watch; the
-// handle is shared by every session in the process (shared-dir-watch.mjs)
-// and each session keeps its own filter/debounce below.
-function startSpoolWatcher({ runtime, flags, getState, drainRemoteInjections, watchDir }) {
-  let release = null;
-  let debounce = null;
-  try {
-    const spoolPath = String(runtime.pendingSpoolPath?.() || '');
-    if (spoolPath) {
-      const spoolFile = basename(spoolPath);
-      release = watchDir(dirname(spoolPath), (_event, filename) => {
-        if (filename && String(filename) !== spoolFile) return;
-        if (flags.disposed || debounce) return;
-        debounce = setTimeout(() => {
-          debounce = null;
-          if (flags.disposed || flags.pendingSessionReset) return;
-          const state = getState();
-          if (state.busy || state.commandBusy || state.sessionRemoteAttached) return;
-          try {
-            void drainRemoteInjections();
-          } catch {
-            /* tick fallback */
-          }
-        }, SPOOL_WATCH_DEBOUNCE_MS);
-        debounce.unref?.();
-      });
-    }
-  } catch {
-    /* spool watch is an optimization; the 3s tick remains */
-  }
-  return {
-    close: () => {
-      release?.();
-      release = null;
-      if (debounce) {
-        clearTimeout(debounce);
-        debounce = null;
-      }
-    },
-  };
-}
-
-// Viewer leg of the tick: follow the owner live over the pipe, otherwise
-// re-resume from disk when the owner saved or disappeared.
-function createViewerTick({ runtime, api, liveShare, getState }) {
-  let storeMtime = 0;
-  return {
-    reset: () => {
-      storeMtime = 0;
-    },
-    run: () => {
-      const id = String(getState().sessionId || '');
-      if (!id) return;
-      // Pipe-connected viewers follow the owner live; the disk-mtime
-      // re-resume would only reload mid-stream state and flicker.
-      if (liveShare.viewerConnected()) {
-        storeMtime = 0;
-        return;
-      }
-      // Self-heal: a force-killed owner never announces onOwnerClosed and
-      // its final save never bumps the store mtime, so without this probe
-      // the surface stays a viewer forever, spooling messages to nobody.
-      // When the resume guard says the owner is gone, promote via the same
-      // quiet re-resume (it drains the pending spool on the next tick).
-      if (runtime.sessionOwnerGone?.(id) === true) {
-        storeMtime = 0;
-        quietResume(api, id);
-        return;
-      }
-      let mtime = 0;
-      try {
-        mtime = statSync(sessionPath(id)).mtimeMs || 0;
-      } catch {
-        return;
-      }
-      // First attached tick only baselines: the resume that attached this
-      // surface already loaded the current on-disk transcript.
-      if (!storeMtime) {
-        storeMtime = mtime;
-        return;
-      }
-      if (mtime > storeMtime) {
-        storeMtime = mtime;
-        quietResume(api, id);
-      }
-    },
-  };
-}
-
-function startRemoteAttachTicker({ runtime, api, flags, getState, liveShare, spoolWatcher, drainRemoteInjections }) {
-  let heldPresenceId = '';
-  const viewerTick = createViewerTick({ runtime, api, liveShare, getState });
-  const timer = setInterval(() => {
-    if (flags.disposed) {
-      clearInterval(timer);
-      try {
-        liveShare.dispose();
-      } catch {
-        /* best-effort */
-      }
-      spoolWatcher.close();
-      return;
-    }
-    if (flags.pendingSessionReset) return;
-    try {
-      const heldId = runtime.publishSessionPresence?.() || '';
-      if (heldPresenceId && heldPresenceId !== heldId) runtime.clearSessionPresence?.(heldPresenceId);
-      heldPresenceId = heldId;
-    } catch {
-      /* best-effort */
-    }
-    try {
-      liveShare.ensure();
-    } catch {
-      /* next tick retries */
-    }
-    try {
-      const state = getState();
-      if (state.busy || state.commandBusy) return;
-      if (state.sessionRemoteAttached) {
-        viewerTick.run();
-        return;
-      }
-      viewerTick.reset();
-      void drainRemoteInjections();
-    } catch {
-      /* best-effort */
-    }
-  }, REMOTE_ATTACH_TICK_MS);
-  timer.unref?.();
-}
-
-export function attachCrossSurfaceShare({
-  runtime,
-  api,
-  bag,
-  flags,
-  getState,
-  getPublishedState,
-  listeners,
-  set,
-  // Test seams: the pipe layer is replaced by a fake share in unit tests, and
-  // the process-wide directory watch by an isolated registry.
-  createShare = createLiveShare,
-  watchDir = sharedDirWatch.subscribe,
-}) {
-  const drainRemoteInjections = createRemoteInjectionDrain({ runtime, bag });
-  const liveShare = createSessionLiveShare({
-    api,
-    bag,
-    flags,
-    getState,
-    getPublishedState,
-    listeners,
-    set,
-    createShare,
-  });
-  // Immediate live-share reconcile for session entry/promotion. Waiting for
-  // the 3s share tick left a just-resumed live-owned session showing the
-  // stale disk snapshot, then full-swapped the transcript mid-view once the
-  // pipe finally connected (visible up/down lurch until heights resettled).
-  // resume() calls this right after installing the restored items so the
-  // owner's full frame lands at the entry boundary instead of seconds later.
-  const ensureLiveShare = () => {
-    try {
-      liveShare.ensure();
-    } catch {
-      /* share tick retries */
-    }
-  };
-  bag.ensureLiveShare = ensureLiveShare;
-  // Pulse guard: while this surface is an attached viewer with a live pipe,
-  // owner frames own stats/agent/tool state (see the runtime pulse timer).
-  bag.liveShareMirroring = () => getState().sessionRemoteAttached && liveShare.viewerConnected();
-  wrapViewerApi({ api, bag, runtime, liveShare, getState, ensureLiveShare });
-  // Cover session runtimes whose runtime already has a session at construction
-  // time; do not wait for a lifecycle method or the 3s safety pulse to open the pipe.
-  ensureLiveShare();
-  const spoolWatcher = startSpoolWatcher({ runtime, flags, getState, drainRemoteInjections, watchDir });
-  startRemoteAttachTicker({ runtime, api, flags, getState, liveShare, spoolWatcher, drainRemoteInjections });
-}

package/src/tui/session/live-share/delta.mjs

@@ -1,153 +0,0 @@
-/**
- * src/tui/session/live-share/delta.mjs - owner-side frame shaping: the live
- * state subset mirrored to viewers, the full snapshot frame, and the
- * frame-to-frame delta against the last published baseline.
- */
-// Above this many patched rows per frame the delta degenerates to a full
-// items push (bulk rewrites: compaction, clear, history restore).
-const MAX_FRAME_PATCHES = 48;
-
-// Live-state mirror (attach parity): the transcript alone left an attached
-// viewer blind to the owner's activity — busy/stop state, the queued
-// follow-up list, the web-search summary, agent workers/jobs, and the
-// context gauge stats all live in owner process state. Mirror a compact
-// subset so viewer surfaces render them natively. queued entries are
-// projected to display fields only (content parts may carry images).
-const LIVE_STATS_KEYS = [
-  'currentContextSource',
-  'currentContextTokens',
-  'currentEstimatedContextTokens',
-  'currentContextUpdatedAt',
-  'costUsd',
-  'turns',
-  'inputTokens',
-  'outputTokens',
-  'latestInputTokens',
-  'latestPromptTokens',
-  'contextTokens',
-];
-
-function liveStateOf(st) {
-  const stats = st.stats && typeof st.stats === 'object' ? st.stats : {};
-  const statsSubset = {};
-  for (const key of LIVE_STATS_KEYS) {
-    if (stats[key] !== undefined) statsSubset[key] = stats[key];
-  }
-  return {
-    busy: st.busy === true,
-    commandBusy: st.commandBusy === true,
-    queued: (Array.isArray(st.queued) ? st.queued : []).map((entry) => ({
-      id: entry?.id,
-      text: String(entry?.displayText ?? entry?.text ?? entry?.message ?? '').slice(0, 2000),
-      ...(entry?.enqueuedAt ? { enqueuedAt: entry.enqueuedAt } : {}),
-    })),
-    activeToolSummary: st.activeToolSummary || null,
-    activeTools: st.activeTools || null,
-    agentWorkers: Array.isArray(st.agentWorkers) ? st.agentWorkers : [],
-    agentJobs: Array.isArray(st.agentJobs) ? st.agentJobs : [],
-    ownerClientHostPid: Number(st.clientHostPid) || process.pid,
-    displayContextWindow: Number(st.displayContextWindow) || 0,
-    compactBoundaryTokens: Number(st.compactBoundaryTokens) || 0,
-    autoCompactTokenLimit: Number(st.autoCompactTokenLimit) || 0,
-    stats: statsSubset,
-  };
-}
-
-export function fullFrame(sessionId, st) {
-  return {
-    t: 'full',
-    sessionId,
-    items: Array.isArray(st.items) ? st.items : [],
-    tail: st.streamingTail || null,
-    spinner: st.spinner || null,
-    live: liveStateOf(st),
-  };
-}
-
-// References the next delta is computed against. Pure pointer assignments,
-// so re-baselining on every publish with no viewers is effectively free.
-export function baselineOf(st, liveSig = JSON.stringify(liveStateOf(st))) {
-  return { items: st.items, tail: st.streamingTail, spinner: st.spinner, liveSig };
-}
-
-export const EMPTY_BASELINE = Object.freeze({ items: null, tail: null, spinner: null, liveSig: '' });
-
-function itemsDelta(prevItems, nextItems) {
-  const prev = Array.isArray(prevItems) ? prevItems : [];
-  const next = Array.isArray(nextItems) ? nextItems : [];
-  let structural = next.length < prev.length;
-  const changed = [];
-  if (!structural) {
-    for (let i = 0; i < prev.length; i++) {
-      if (next[i] === prev[i]) continue;
-      if (!next[i]?.id || next[i].id !== prev[i]?.id) {
-        structural = true;
-        break;
-      }
-      changed.push(next[i]);
-      if (changed.length > MAX_FRAME_PATCHES) {
-        structural = true;
-        break;
-      }
-    }
-  }
-  if (structural) return { items: next };
-  const delta = {};
-  if (changed.length) delta.changed = changed;
-  if (next.length > prev.length) delta.appended = next.slice(prev.length);
-  return delta;
-}
-
-// Streaming text grows append-only frame to frame: ship just the new suffix
-// so long responses stay a few bytes per frame, not O(text).
-function tailDelta(prevTail, nextTail) {
-  const next = nextTail || null;
-  const prev = prevTail || null;
-  const appendOnly =
-    next &&
-    prev &&
-    next.id === prev.id &&
-    typeof next.text === 'string' &&
-    typeof prev.text === 'string' &&
-    next.text.length >= prev.text.length &&
-    next.text.startsWith(prev.text);
-  if (!appendOnly) return { tail: next };
-  const meta = {};
-  for (const [key, value] of Object.entries(next)) {
-    if (key === 'text') continue;
-    if (!Object.is(prev[key], value)) meta[key] = value;
-  }
-  return {
-    tailAppend: {
-      id: next.id,
-      base: prev.text.length,
-      text: next.text.slice(prev.text.length),
-      ...(Object.keys(meta).length ? { meta } : {}),
-    },
-  };
-}
-
-/** Delta of `st` against `baseline`; `frame` is null when nothing changed. */
-export function deltaFrame(baseline, st) {
-  const frame = { t: 'delta' };
-  let dirty = false;
-  if (st.items !== baseline.items) {
-    Object.assign(frame, itemsDelta(baseline.items, st.items));
-    dirty = true;
-  }
-  if (st.streamingTail !== baseline.tail) {
-    Object.assign(frame, tailDelta(baseline.tail, st.streamingTail));
-    dirty = true;
-  }
-  if (st.spinner !== baseline.spinner) {
-    frame.spinner = st.spinner || null;
-    dirty = true;
-  }
-  const live = liveStateOf(st);
-  const liveSig = JSON.stringify(live);
-  if (liveSig !== baseline.liveSig) {
-    frame.live = live;
-    dirty = true;
-  }
-  return { frame: dirty ? frame : null, baseline: baselineOf(st, liveSig) };
-}

package/src/tui/session/live-share/mirror.mjs

@@ -1,106 +0,0 @@
-/**
- * src/tui/session/live-share/mirror.mjs - viewer-side application of owner
- * frames into the local session store.
- */
-const LIVE_LIMIT_KEYS = ['displayContextWindow', 'compactBoundaryTokens', 'autoCompactTokenLimit'];
-
-export function createMirror(viewerApply) {
-  const upsertItem = (item) => {
-    if (!item || item.id == null) return;
-    const items = viewerApply.getState().items;
-    const exists = Array.isArray(items) && items.some((it) => it?.id === item.id);
-    if (exists) viewerApply.patchItem(item.id, item);
-    else viewerApply.appendItems([item]);
-  };
-
-  // Mirror the owner's live-state subset into the viewer store. Context stats
-  // merge over the local stats object so unmirrored accumulator fields keep
-  // their last local values instead of vanishing.
-  const applyLiveState = (live) => {
-    if (!live || typeof live !== 'object') return;
-    const patch = {
-      busy: live.busy === true,
-      commandBusy: live.commandBusy === true,
-      queued: Array.isArray(live.queued) ? live.queued : [],
-      activeToolSummary: live.activeToolSummary || null,
-      activeTools: live.activeTools || null,
-      agentWorkers: Array.isArray(live.agentWorkers) ? live.agentWorkers : [],
-      agentJobs: Array.isArray(live.agentJobs) ? live.agentJobs : [],
-      ownerClientHostPid: Number(live.ownerClientHostPid) || 0,
-    };
-    for (const key of LIVE_LIMIT_KEYS) {
-      if (Number(live[key]) > 0) patch[key] = Number(live[key]);
-    }
-    if (live.stats && typeof live.stats === 'object' && Object.keys(live.stats).length > 0) {
-      const current = viewerApply.getState().stats;
-      patch.stats = { ...(current && typeof current === 'object' ? current : {}), ...live.stats };
-    }
-    viewerApply.set(patch);
-  };
-
-  // Owner gone (clean close, crash, or pipe drop): the mirrored activity is
-  // no longer authoritative — clear it so the viewer never shows a frozen
-  // spinner/queue while the promotion path takes over.
-  const clearLiveState = () => {
-    try {
-      viewerApply?.set?.({
-        busy: false,
-        commandBusy: false,
-        spinner: null,
-        queued: [],
-        activeToolSummary: null,
-        activeTools: null,
-        agentWorkers: [],
-        agentJobs: [],
-        ownerClientHostPid: 0,
-      });
-    } catch {
-      /* viewer store already disposed */
-    }
-  };
-
-  // Returns false when a tail suffix did not match the local base — this
-  // mirror lost a frame and the caller must request a full resync.
-  const applyTailAppend = (tailAppend) => {
-    const current = viewerApply.getState().streamingTail;
-    const base = Number(tailAppend.base) || 0;
-    const matches =
-      current && current.id === tailAppend.id && typeof current.text === 'string' && current.text.length === base;
-    if (!matches) return false;
-    viewerApply.updateStreamingTail(tailAppend.id, {
-      ...(tailAppend.meta || {}),
-      text: current.text + String(tailAppend.text || ''),
-    });
-    return true;
-  };
-
-  /** Apply one owner frame; false means the mirror is desynced. */
-  const applyFrame = (frame) => {
-    if (frame.t === 'full') {
-      viewerApply.replaceItems(Array.isArray(frame.items) ? frame.items : []);
-      if (frame.tail) viewerApply.updateStreamingTail(frame.tail.id, frame.tail, {}, { resetText: true });
-      viewerApply.set({ spinner: frame.spinner || null });
-      applyLiveState(frame.live);
-      return true;
-    }
-    if (frame.t !== 'delta') return true;
-    if (Array.isArray(frame.items)) {
-      viewerApply.replaceItems(frame.items, { preserveStreamingTail: true });
-    } else {
-      for (const item of frame.changed || []) upsertItem(item);
-      for (const item of frame.appended || []) upsertItem(item);
-    }
-    let synced = true;
-    if (frame.tailAppend) {
-      synced = applyTailAppend(frame.tailAppend);
-    } else if ('tail' in frame) {
-      if (frame.tail) viewerApply.updateStreamingTail(frame.tail.id, frame.tail, {}, { resetText: true });
-      else viewerApply.clearStreamingTail();
-    }
-    if ('spinner' in frame) viewerApply.set({ spinner: frame.spinner || null });
-    if ('live' in frame) applyLiveState(frame.live);
-    return synced;
-  };
-
-  return { applyFrame, clearLiveState };
-}