@agent-native/core 0.92.12 → 0.94.0

package/corpus/core/src/client/transcription/use-live-transcription.ts

@@ -13,6 +13,9 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 
+const NETWORK_RESTART_BASE_MS = 1_000;
+const NETWORK_RESTART_MAX_MS = 30_000;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getSpeechRecognitionCtor(): any {
   if (typeof window === "undefined") return null;
@@ -57,6 +60,9 @@ export function useLiveTranscription(
   const transcriptRef = useRef("");
   const stoppedManuallyRef = useRef(false);
   const stopWaiterRef = useRef<((text: string) => void) | null>(null);
+  const restartTimerRef = useRef<number | null>(null);
+  const networkErrorCountRef = useRef(0);
+  const restartDelayRef = useRef(0);
 
   const supported = !!getSpeechRecognitionCtor();
 
@@ -65,6 +71,10 @@ export function useLiveTranscription(
     if (!Ctor) return;
 
     // Clean up any prior session.
+    if (restartTimerRef.current !== null) {
+      window.clearTimeout(restartTimerRef.current);
+      restartTimerRef.current = null;
+    }
     if (recognitionRef.current) {
       try {
         recognitionRef.current.abort();
@@ -80,6 +90,8 @@ export function useLiveTranscription(
     recognitionRef.current = recognition;
     transcriptRef.current = "";
     stoppedManuallyRef.current = false;
+    networkErrorCountRef.current = 0;
+    restartDelayRef.current = 0;
     setTranscript("");
     setInterimText("");
 
@@ -96,21 +108,60 @@ export function useLiveTranscription(
         }
       }
       setInterimText(interim);
+      if (event.results.length > 0) {
+        networkErrorCountRef.current = 0;
+        restartDelayRef.current = 0;
+      }
     };
 
     recognition.onerror = (event: any) => {
       if (event.error === "no-speech" || event.error === "aborted") return;
+      if (
+        event.error === "not-allowed" ||
+        event.error === "service-not-allowed" ||
+        event.error === "audio-capture"
+      ) {
+        stoppedManuallyRef.current = true;
+        setIsActive(false);
+        return;
+      }
+      if (event.error === "network") {
+        const retryIndex = networkErrorCountRef.current++;
+        restartDelayRef.current = Math.min(
+          NETWORK_RESTART_BASE_MS * 2 ** retryIndex,
+          NETWORK_RESTART_MAX_MS,
+        );
+      }
       console.warn("[live-transcription] error:", event.error);
     };
 
     recognition.onend = () => {
       // Web Speech sometimes stops on its own (silence timeout, network
       // hiccup). Restart automatically unless we stopped intentionally.
-      if (!stoppedManuallyRef.current && recognitionRef.current) {
-        try {
-          recognition.start();
-        } catch {
-          setIsActive(false);
+      if (
+        !stoppedManuallyRef.current &&
+        recognitionRef.current === recognition
+      ) {
+        const restart = () => {
+          restartTimerRef.current = null;
+          if (
+            stoppedManuallyRef.current ||
+            recognitionRef.current !== recognition
+          ) {
+            return;
+          }
+          try {
+            recognition.start();
+          } catch {
+            setIsActive(false);
+          }
+        };
+        const delayMs = restartDelayRef.current;
+        restartDelayRef.current = 0;
+        if (delayMs > 0) {
+          restartTimerRef.current = window.setTimeout(restart, delayMs);
+        } else {
+          restart();
         }
         return;
       }
@@ -130,6 +181,10 @@ export function useLiveTranscription(
 
   const stop = useCallback((): string => {
     stoppedManuallyRef.current = true;
+    if (restartTimerRef.current !== null) {
+      window.clearTimeout(restartTimerRef.current);
+      restartTimerRef.current = null;
+    }
     setInterimText("");
     if (recognitionRef.current) {
       try {
@@ -145,6 +200,10 @@ export function useLiveTranscription(
 
   const stopAndWait = useCallback((timeoutMs = 1200): Promise<string> => {
     stoppedManuallyRef.current = true;
+    if (restartTimerRef.current !== null) {
+      window.clearTimeout(restartTimerRef.current);
+      restartTimerRef.current = null;
+    }
     setInterimText("");
 
     const recognition = recognitionRef.current;
@@ -185,6 +244,10 @@ export function useLiveTranscription(
   const pause = useCallback(() => {
     if (!recognitionRef.current) return;
     stoppedManuallyRef.current = true;
+    if (restartTimerRef.current !== null) {
+      window.clearTimeout(restartTimerRef.current);
+      restartTimerRef.current = null;
+    }
     try {
       recognitionRef.current.stop();
     } catch {

package/corpus/core/src/client/use-chat-models.ts

@@ -2,7 +2,9 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { DEFAULT_MODEL } from "../agent/default-model.js";
 import {
+  DEFAULT_REASONING_EFFORT,
   getReasoningEffortOptionsForModel,
+  resolveReasoningEffortSelection,
   type ReasoningEffort,
 } from "../shared/reasoning-effort.js";
 import { agentNativePath } from "./api-path.js";
@@ -87,7 +89,10 @@ export function useChatModels({
     initialPersisted.engine ?? "",
   );
   const [selectedEffort, setSelectedEffort] = useState<ReasoningEffort>(
-    initialPersisted.effort ?? "auto",
+    resolveReasoningEffortSelection(
+      initialPersisted.model ?? DEFAULT_MODEL,
+      initialPersisted.effort,
+    ),
   );
   const selectionRef = useRef({
     selectedModel,
@@ -110,10 +115,9 @@ export function useChatModels({
       setSelectedModel(model);
       setSelectedEngine(engine);
       setSelectedEffort((prevEffort) => {
-        const next =
-          prevEffort === "auto" || effortOptions.includes(prevEffort)
-            ? prevEffort
-            : "auto";
+        const next = effortOptions.includes(prevEffort)
+          ? prevEffort
+          : DEFAULT_REASONING_EFFORT;
         writePersisted(storageKey, { model, engine, effort: next });
         return next;
       });
@@ -180,12 +184,10 @@ export function useChatModels({
             defaultGroup?.models[0] ??
             nextDefaultModel;
           const nextEngine = defaultGroup?.engine ?? "";
-          const effortOptions = getReasoningEffortOptionsForModel(nextModel);
-          const nextEffort =
-            selection.selectedEffort === "auto" ||
-            effortOptions.includes(selection.selectedEffort)
-              ? selection.selectedEffort
-              : "auto";
+          const nextEffort = resolveReasoningEffortSelection(
+            nextModel,
+            selection.selectedEffort,
+          );
           setSelectedModel(nextModel);
           setSelectedEngine(nextEngine);
           setSelectedEffort(nextEffort);
@@ -207,12 +209,10 @@ export function useChatModels({
             defaultGroup?.models[0] ??
             nextDefaultModel;
           const nextEngine = defaultGroup?.engine ?? "";
-          const effortOptions = getReasoningEffortOptionsForModel(nextModel);
-          const nextEffort =
-            selection.selectedEffort === "auto" ||
-            effortOptions.includes(selection.selectedEffort)
-              ? selection.selectedEffort
-              : "auto";
+          const nextEffort = resolveReasoningEffortSelection(
+            nextModel,
+            selection.selectedEffort,
+          );
           setSelectedModel(nextModel);
           setSelectedEngine(nextEngine);
           setSelectedEffort(nextEffort);

package/corpus/core/src/client/use-db-sync.ts

@@ -1,6 +1,9 @@
 import { useEffect, useRef, useState } from "react";
 
-import { ensureDemoModeFetchInterceptor } from "../demo/fetch-interceptor.js";
+import {
+  ensureDemoModeFetchInterceptor,
+  refreshDemoModeFetchInterceptor,
+} from "../demo/fetch-interceptor.js";
 import { agentNativePath } from "./api-path.js";
 import {
   ensureEmbedAuthFetchInterceptor,
@@ -21,6 +24,7 @@ interface QueryClient {
 
 const POLL_ABORT_MIN_MS = 10_000;
 const SSE_FALLBACK_INTERVAL_MS = 15_000;
+const IDLE_POLL_INTERVAL_MS = 15_000;
 const POLL_AUTH_FAILURE_COOLDOWN_MS = 60_000;
 /**
  * Max cadence for SSE/poll-driven query invalidation in `useDbSync`. Events
@@ -192,6 +196,8 @@ interface TransportSubscription {
    * subscribers so the most-frequent caller is satisfied.
    */
   interval: number;
+  /** Requested poll interval while the tab has no active agent work. */
+  idleInterval: number;
   /** Requested fallback interval while SSE is connected. */
   fallbackInterval: number;
   /**
@@ -213,6 +219,7 @@ class SyncTransport {
   private sseConnected = false;
   private authFailureUntil = 0;
   private consecutiveFailures = 0;
+  private activeChatIds = new Set<string>();
 
   constructor(
     private readonly pollUrl: string,
@@ -225,10 +232,17 @@ class SyncTransport {
 
   add(id: symbol, sub: TransportSubscription): void {
     const wasEmpty = this.subscribers.size === 0;
+    const wasActive = this.isActive;
     this.subscribers.set(id, sub);
     if (wasEmpty) {
       this.stopped = false;
       this.start();
+    } else if (!wasActive && this.isActive) {
+      // A collab surface (or other active subscriber) just joined. Catch up
+      // immediately rather than waiting out an idle-cadence timer.
+      this.pollNow();
+    } else {
+      this.reschedule();
     }
     sub.onSseStateChange?.(this.sseConnected);
   }
@@ -264,6 +278,18 @@ class SyncTransport {
     return isFinite(min) ? min : 2000;
   }
 
+  private get effectiveIdleInterval(): number {
+    let min = Infinity;
+    for (const sub of this.subscribers.values()) {
+      if (sub.idleInterval < min) min = sub.idleInterval;
+    }
+    return isFinite(min) ? min : IDLE_POLL_INTERVAL_MS;
+  }
+
+  private get isActive(): boolean {
+    return this.activeChatIds.size > 0;
+  }
+
   private get effectiveFallbackInterval(): number {
     let min = Infinity;
     for (const sub of this.subscribers.values()) {
@@ -277,6 +303,15 @@ class SyncTransport {
   // -------------------------------------------------------------------------
 
   private fan(events: SyncEvent[], version: number | undefined): void {
+    if (
+      events.some(
+        (event) =>
+          event.source === "app-state" &&
+          (event.key === "demo-mode" || event.key === "*"),
+      )
+    ) {
+      void refreshDemoModeFetchInterceptor();
+    }
     for (const sub of this.subscribers.values()) {
       sub.onEvents(events, version);
     }
@@ -310,9 +345,11 @@ class SyncTransport {
       }, authDelay);
       return;
     }
-    const base = this.sseConnected
-      ? this.effectiveFallbackInterval
-      : this.effectiveInterval;
+    const base = this.isActive
+      ? this.effectiveInterval
+      : this.sseConnected
+        ? this.effectiveFallbackInterval
+        : this.effectiveIdleInterval;
     // Exponential backoff while polls keep failing (500s during a deploy,
     // DNS blips, a struggling DB). Auth failures have their own cooldown
     // above; this covers everything else so a down server isn't hammered at
@@ -461,6 +498,40 @@ class SyncTransport {
     this.pollNow();
   };
 
+  private handleChatRunning = (event: Event): void => {
+    const detail = (
+      event as CustomEvent<{
+        isRunning?: unknown;
+        running?: unknown;
+        tabId?: unknown;
+      }>
+    ).detail;
+    const running =
+      typeof detail?.isRunning === "boolean"
+        ? detail.isRunning
+        : typeof detail?.running === "boolean"
+          ? detail.running
+          : null;
+    if (running === null) return;
+
+    const id =
+      typeof detail?.tabId === "string" && detail.tabId
+        ? detail.tabId
+        : "__default__";
+    const wasActive = this.isActive;
+    if (running) this.activeChatIds.add(id);
+    else this.activeChatIds.delete(id);
+    if (wasActive === this.isActive) return;
+
+    if (this.isActive) {
+      // Run start is a high-signal indication that cross-process writes are
+      // imminent. Catch up now, then stay on the active cadence.
+      this.pollNow();
+    } else {
+      this.reschedule();
+    }
+  };
+
   private start(): void {
     // Universal demo-mode redaction for the UI. Idempotent + browser-only +
     // a no-op until demo mode is on. Lives here because every template root
@@ -473,6 +544,7 @@ class SyncTransport {
       void this.poll();
     }
     window.addEventListener("focus", this.handleFocus);
+    window.addEventListener("agentNative.chatRunning", this.handleChatRunning);
     document.addEventListener("visibilitychange", this.handleVisibilityChange);
   }
 
@@ -484,6 +556,10 @@ class SyncTransport {
       this.timer = null;
     }
     window.removeEventListener("focus", this.handleFocus);
+    window.removeEventListener(
+      "agentNative.chatRunning",
+      this.handleChatRunning,
+    );
     document.removeEventListener(
       "visibilitychange",
       this.handleVisibilityChange,
@@ -568,6 +644,7 @@ export function subscribeSyncEvents(
     onSseStateChange: options.onSseStateChange,
     pauseWhenHidden: options.pauseWhenHidden ?? true,
     interval: options.interval ?? 60_000,
+    idleInterval: options.interval ?? 60_000,
     fallbackInterval: options.fallbackInterval ?? 60_000,
   });
   return () => {
@@ -640,6 +717,8 @@ export function useDbSync(
     ),
     pauseWhenHidden = true,
   } = options;
+  const idleInterval =
+    options.interval === undefined ? IDLE_POLL_INTERVAL_MS : interval;
 
   const onEventRef = useRef(options.onEvent);
   onEventRef.current = options.onEvent;
@@ -742,7 +821,12 @@ export function useDbSync(
       for (const evt of relevant) {
         const src = typeof evt.source === "string" ? evt.source : "";
         const ver = typeof evt.version === "number" ? evt.version : 0;
-        if (src && ver > 0) bumpChangeVersion(src, ver);
+        if (src && ver > 0) {
+          bumpChangeVersion(src, ver);
+          if (typeof evt.key === "string" && evt.key) {
+            bumpChangeVersion(`${src}:${evt.key}`, ver);
+          }
+        }
       }
 
       // Awareness (cursor/presence) events never change action/extension/
@@ -796,7 +880,12 @@ export function useDbSync(
           const hasDataChangingEvent = invalidating.some(
             (evt) => evt.source !== "app-state",
           );
-          if (hasDataChangingEvent) {
+          // The broad action invalidate above already covers every fixed
+          // framework prefix. Re-invalidating ["action"] immediately after it
+          // cancels/restarts the same active reads and creates a duplicate
+          // request wave. Keep the fixed-prefix pass for non-action sources;
+          // action batches get exactly one compatibility invalidation.
+          if (hasDataChangingEvent && !hasActionEvent) {
             queryClient.invalidateQueries({ queryKey: ["action"] });
             queryClient.invalidateQueries({ queryKey: ["extension"] });
             queryClient.invalidateQueries({ queryKey: ["extensions"] });
@@ -856,6 +945,7 @@ export function useDbSync(
       onEvents,
       pauseWhenHidden,
       interval,
+      idleInterval,
       fallbackInterval,
     });
 
@@ -880,6 +970,7 @@ export function useDbSync(
     sseUrl,
     queryClient,
     interval,
+    idleInterval,
     fallbackInterval,
     pauseWhenHidden,
   ]);
@@ -926,6 +1017,8 @@ export function useScreenRefreshKey(
     ),
     pauseWhenHidden = true,
   } = options;
+  const idleInterval =
+    options.interval === undefined ? IDLE_POLL_INTERVAL_MS : interval;
   const [key, setKey] = useState(0);
 
   useEffect(() => {
@@ -958,6 +1051,7 @@ export function useScreenRefreshKey(
       onEvents,
       pauseWhenHidden,
       interval,
+      idleInterval,
       fallbackInterval,
     });
 
@@ -967,7 +1061,14 @@ export function useScreenRefreshKey(
         releaseTransport(pollUrl, sseUrl);
       }
     };
-  }, [pollUrl, sseUrl, interval, fallbackInterval, pauseWhenHidden]);
+  }, [
+    pollUrl,
+    sseUrl,
+    interval,
+    idleInterval,
+    fallbackInterval,
+    pauseWhenHidden,
+  ]);
 
   return key;
 }

package/corpus/core/src/client/use-run-stuck-detection.ts

@@ -28,6 +28,13 @@ export interface RunStuckState {
   heartbeatSinceMs: number | null;
   /** How the run was dispatched/continued, e.g. foreground-self-chain or background-processing. */
   dispatchMode: string | null;
+  /**
+   * Server-authoritative: true when the run holds an open tool call or A2A
+   * `agent_call` delegation (`in_flight_since` marker set). Preferred over the
+   * client-side proxy for deciding whether Retry (which aborts the run) is
+   * safe to offer. Null when the server bundle predates this field.
+   */
+  hasInFlightWork: boolean | null;
 }
 
 export interface UseRunStuckDetectionOptions {
@@ -55,6 +62,13 @@ export interface UseRunStuckDetectionOptions {
    * from the same poll response that computes the elapsed time.
    */
   backgroundStuckThresholdMs?: number;
+  /**
+   * Threshold for a claimed durable background worker that is still sending
+   * fresh process heartbeats. These workers can legitimately spend up to the
+   * 12-minute tool/no-progress window on large Design, Plan, or Assets work.
+   * Default 13 minutes, matching the durable chunk handoff boundary.
+   */
+  liveBackgroundStuckThresholdMs?: number;
   /** Poll interval. Default 5_000ms. */
   pollIntervalMs?: number;
   /** API base path. Default `/_agent-native/agent-chat`. */
@@ -63,8 +77,10 @@ export interface UseRunStuckDetectionOptions {
 
 const DEFAULT_STUCK_THRESHOLD_MS = 90_000;
 export const DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS = 180_000;
+export const DEFAULT_LIVE_BACKGROUND_STUCK_THRESHOLD_MS = 13 * 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const IDLE_BACKOFF_INTERVAL_MS = 15_000;
+const FRESH_BACKGROUND_HEARTBEAT_MS = 30_000;
 
 interface ActiveRunResponse {
   active: boolean;
@@ -75,6 +91,8 @@ interface ActiveRunResponse {
   dispatchMode?: string | null;
   /** Server clock at response time, used to compute elapsed server-relative. */
   serverNow?: number;
+  /** True when the run holds an open tool/A2A call (in_flight_since marker). */
+  hasInFlightWork?: boolean;
 }
 
 const EMPTY_STATE: RunStuckState = {
@@ -86,6 +104,7 @@ const EMPTY_STATE: RunStuckState = {
   heartbeatAt: null,
   heartbeatSinceMs: null,
   dispatchMode: null,
+  hasInFlightWork: null,
 };
 
 export function useRunStuckDetection({
@@ -93,6 +112,7 @@ export function useRunStuckDetection({
   enabled = true,
   stuckThresholdMs = DEFAULT_STUCK_THRESHOLD_MS,
   backgroundStuckThresholdMs = DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS,
+  liveBackgroundStuckThresholdMs = DEFAULT_LIVE_BACKGROUND_STUCK_THRESHOLD_MS,
   pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
   apiUrl,
 }: UseRunStuckDetectionOptions): RunStuckState {
@@ -139,9 +159,22 @@ export function useRunStuckDetection({
           const serverContinued =
             dispatchMode === "foreground-self-chain" ||
             dispatchMode?.startsWith("background") === true;
-          const effectiveThresholdMs = serverContinued
-            ? backgroundStuckThresholdMs
-            : stuckThresholdMs;
+          // A claimed durable worker with a fresh heartbeat can legitimately
+          // be waiting on a bounded long-running tool/sub-agent call. Showing
+          // Retry at the generic 3-minute continuation threshold aborts healthy
+          // work and starts the same call again. Let the worker's own 12-minute
+          // watchdog act first; a dead/stale heartbeat still gets the earlier
+          // background fallback below.
+          const liveBackgroundWorker =
+            dispatchMode === "background-processing" &&
+            heartbeatSinceMs != null &&
+            heartbeatSinceMs >= 0 &&
+            heartbeatSinceMs < FRESH_BACKGROUND_HEARTBEAT_MS;
+          const effectiveThresholdMs = liveBackgroundWorker
+            ? liveBackgroundStuckThresholdMs
+            : serverContinued
+              ? backgroundStuckThresholdMs
+              : stuckThresholdMs;
           const isStuck = Boolean(
             data.active &&
             data.status === "running" &&
@@ -157,6 +190,10 @@ export function useRunStuckDetection({
             heartbeatAt,
             heartbeatSinceMs,
             dispatchMode,
+            hasInFlightWork:
+              typeof data.hasInFlightWork === "boolean"
+                ? data.hasInFlightWork
+                : null,
           });
           // Back off polling when nothing is in flight — there's no point
           // hammering the endpoint while the chat is idle. We still poll
@@ -187,6 +224,7 @@ export function useRunStuckDetection({
     enabled,
     stuckThresholdMs,
     backgroundStuckThresholdMs,
+    liveBackgroundStuckThresholdMs,
     pollIntervalMs,
     apiUrl,
   ]);

package/corpus/core/src/code-agents/background-controller.ts

@@ -1,4 +1,5 @@
 import {
+  executeDenyCodeAgentApproval,
   executeExistingCodeAgentRun,
   executePendingCodeAgentApproval,
 } from "../cli/code-agent-executor.js";
@@ -25,6 +26,7 @@ import type { AgentPromptAttachment } from "./prompt-attachments.js";
 
 export type BackgroundAgentControlCommand =
   | "approve"
+  | "deny"
   | "resume"
   | "retry"
   | "stop";
@@ -246,6 +248,22 @@ async function controlLocalCodeBackgroundAgentRun(
         error: approved ? undefined : `Run not found: ${run.id}`,
       };
     }
+    case "deny": {
+      const denied = await executeDenyCodeAgentApproval(run.id, {
+        stdout: input.stdout,
+      });
+      return {
+        ok: Boolean(denied),
+        runId: run.id,
+        run: denied
+          ? toBackgroundAgentRun(denied)
+          : currentBackgroundRun(run.id),
+        message: denied
+          ? "Pending approval denied for the Agent-Native Code run."
+          : undefined,
+        error: denied ? undefined : `Run not found: ${run.id}`,
+      };
+    }
     case "resume":
     case "retry": {
       // A control action must return immediately — awaiting

package/corpus/core/src/collab/ydoc-manager.ts

@@ -181,6 +181,7 @@ async function persistMergedState(
   docId: string,
   doc: Y.Doc,
   getTextSnapshot: () => string,
+  validateTextSnapshot?: (snapshot: string) => void,
 ): Promise<void> {
   for (let attempt = 0; attempt < 5; attempt++) {
     // One DB read per persist attempt. On first attempt this is the only read
@@ -193,17 +194,21 @@ async function persistMergedState(
     }
 
     const stateToStore = buildStateToStore(doc, latest?.state?.length ?? 0);
+    const textSnapshot = getTextSnapshot();
+    validateTextSnapshot?.(textSnapshot);
     const saved = await trySaveYDocState(
       docId,
       stateToStore,
-      getTextSnapshot(),
+      textSnapshot,
       latest?.version ?? null,
     );
     if (saved) return;
   }
 
   // All CAS attempts failed — fall back to unconditional save.
-  await saveYDocState(docId, Y.encodeStateAsUpdate(doc), getTextSnapshot());
+  const textSnapshot = getTextSnapshot();
+  validateTextSnapshot?.(textSnapshot);
+  await saveYDocState(docId, Y.encodeStateAsUpdate(doc), textSnapshot);
 }
 
 /**
@@ -282,6 +287,15 @@ export async function applyText(
   newText: string,
   fieldName: string = DEFAULT_FIELD,
   requestSource?: string,
+  options: {
+    /**
+     * Validate the fully converged text after cross-process Yjs updates have
+     * merged, but before the state is persisted or broadcast. A rejected
+     * candidate is discarded from this process's cache so the next read
+     * reloads the last durable state instead of leaking an uncommitted merge.
+     */
+    validateSnapshot?: (snapshot: string) => void;
+  } = {},
 ): Promise<string> {
   return withDocWriteLock(docId, async () => {
     const doc = await getDoc(docId);
@@ -289,12 +303,33 @@ export async function applyText(
     const update = applyTextToYDoc(doc, fieldName, newText, "server");
 
     if (update.length === 0) {
-      return doc.getText(fieldName).toString();
+      const snapshot = doc.getText(fieldName).toString();
+      try {
+        options.validateSnapshot?.(snapshot);
+      } catch (error) {
+        releaseDoc(docId);
+        throw error;
+      }
+      return snapshot;
     }
 
-    await persistMergedState(docId, doc, () =>
-      doc.getText(fieldName).toString(),
-    );
+    try {
+      await persistMergedState(
+        docId,
+        doc,
+        () => doc.getText(fieldName).toString(),
+        options.validateSnapshot,
+      );
+    } catch (error) {
+      if (options.validateSnapshot) {
+        // The target diff and any cross-process state merged during the CAS
+        // read now live only in this cached Y.Doc. Destroy it before throwing:
+        // neither the rejected update nor a compensating rollback should ever
+        // be persisted/emitted to connected clients.
+        releaseDoc(docId);
+      }
+      throw error;
+    }
 
     emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
     touchAgentPresence(docId, requestSource, {