@agent-native/core 0.120.2 → 0.120.4

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -644,16 +644,8 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       }
     : undefined;
 
-  // Live collaboration for everyone who can open the doc — editors and viewers
-  // alike. Viewers join the shared Y.Doc read-only: they see live keystrokes,
-  // cursors, and presence (Google-Docs style) instead of a lagging SQL snapshot.
-  // The server enforces the split — collab READ routes (state / awareness GET /
-  // users) require viewer access, WRITE routes (update) require editor — so a
-  // viewer's client can subscribe but never push. The editor stays non-editable
-  // for viewers (see `editable={canEdit}` below), and VisualEditor additionally
-  // neutralizes every local Y.Doc mutation for viewers (no seed, no reconcile
-  // apply) so a read-only client can never originate a rejected `/update` POST.
-  // Local-file documents are still excluded (they have no SQL-backed collab doc).
+  // All SQL-backed readers subscribe for presence. Only editors bind the body
+  // to Yjs; viewers render canonical SQL so missing collab state cannot hide it.
   const collabEnabled = !isLocalFileDocument;
   const {
     ydoc,
@@ -671,6 +663,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   const bodyHydrationPending = documentBodyHydrationIsPending(document);
   const editorCanEdit =
     canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
+  // Bind an editor's stable Y.Doc on its first mount, even while the initial
+  // state is loading. Editability remains gated by `editorCanEdit`, and the
+  // reconcile hook remains gated by `collabSynced`; keeping the Y.Doc binding
+  // stable avoids a snapshot -> collab remount that can seed the same SQL body
+  // beside freshly projected persisted CRDT content.
+  const collabEditorEnabled = collabEnabled && canEdit && !bodyHydrationPending;
   canEditRef.current = editorCanEdit;
 
   // Viewers intentionally join awareness so they receive live cursors, but
@@ -900,6 +898,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     },
     [document, documentId, queryClient, updateDocument],
   );
+  // The document query can refresh its object identity without changing the
+  // flush request itself. Keep the latest save function behind a ref so those
+  // routine refreshes do not restart the one-shot flush reader and flood the
+  // browser with duplicate application-state requests.
+  const persistDocumentUpdatesRef = useRef(persistDocumentUpdates);
+  persistDocumentUpdatesRef.current = persistDocumentUpdates;
 
   const saveDocumentImmediately = useCallback(
     async (
@@ -1216,7 +1220,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             }
             try {
               if (Object.keys(updates).length > 0) {
-                const saved = await persistDocumentUpdates(updates);
+                const saved = await persistDocumentUpdatesRef.current(updates);
                 if (isDocumentUpdateConflict(saved)) {
                   // Do not acknowledge a CAS loss as a successful flush. The
                   // requester must stop instead of pushing/replacing stale SQL.
@@ -1290,7 +1294,6 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     flushRequestKey,
     flushRequestWake,
     isLocalFileDocument,
-    persistDocumentUpdates,
     t,
   ]);
 
@@ -1372,6 +1375,24 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     setHoveredThreadId(null);
   }, []);
 
+  const activateCommentThread = useCallback((threadId: string) => {
+    setPendingComment(null);
+    setHoveredThreadId(null);
+    setSelectedThreadId(threadId);
+    setUtilityPanel("comments");
+  }, []);
+
+  const handleUtilityPanelChange = useCallback(
+    (nextPanel: DocumentUtilityPanel) => {
+      setUtilityPanel(nextPanel);
+      if (nextPanel !== "comments") {
+        setPendingComment(null);
+        clearCommentFocus();
+      }
+    },
+    [clearCommentFocus],
+  );
+
   useEffect(() => {
     setPendingComment(null);
     setUtilityPanel(null);
@@ -1512,9 +1533,11 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       scrollContainerRef={scrollContainerRef}
       activeThreadId={activeThreadId}
       selectedThreadId={selectedThreadId}
+      onActivateThread={activateCommentThread}
       onSelectedThreadChange={setSelectedThreadId}
       onHoveredThreadChange={setHoveredThreadId}
       currentUserEmail={session?.email}
+      alignToAnchors={hasUtilityRailSpace}
       forceVisible
     />
   );
@@ -1566,7 +1589,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             type="button"
             className="ms-auto flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             aria-label={t("editor.toolbar.closeUtilityPanel")}
-            onClick={() => setUtilityPanel(null)}
+            onClick={() => handleUtilityPanelChange(null)}
           >
             <IconX size={16} />
           </button>
@@ -1594,7 +1617,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       <div
         className="relative flex min-h-0 min-w-0 flex-1"
         data-document-print-root
-        onPointerDownCapture={(event) => {
+        onClickCapture={(event) => {
           const target = event.target as HTMLElement | null;
           if (
             target?.closest("[data-comments-sidebar], [data-comment-thread]")
@@ -1626,7 +1649,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             }
             onDelete={handleDeleteDocument}
             utilityPanel={utilityPanel}
-            onUtilityPanelChange={setUtilityPanel}
+            onUtilityPanelChange={handleUtilityPanelChange}
             showCommentsControl={editorCanEdit && !isLocalFileDocument}
             onOpenBreadcrumbItem={handleOpenToolbarBreadcrumb}
           />
@@ -1817,7 +1840,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       // fields.
                       const primaryEditor = (
                         <VisualEditor
-                          key={`${documentId}:${editorCanEdit && !isLocalFileDocument ? "live" : "snapshot"}`}
+                          key={`${documentId}:${collabEditorEnabled && ydoc ? "live-ready" : canEdit && !isLocalFileDocument ? "live-pending" : `snapshot:${document.updatedAt}`}`}
                           documentId={documentId}
                           content={
                             isLocalFileDocument
@@ -1831,13 +1854,11 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                           }
                           onChange={handleContentChange}
                           onSaveContent={handleContentSaveNow}
-                          // Bind the shared Y.Doc/awareness for viewers too — the
-                          // editor is non-editable for them and VisualEditor blocks
-                          // any local Y.Doc mutation, so they get live edits +
-                          // cursors without ever writing. Excludes local-file docs.
-                          ydoc={collabEnabled ? ydoc : null}
-                          collabSynced={collabEnabled ? collabSynced : true}
-                          awareness={collabEnabled ? awareness : null}
+                          ydoc={collabEditorEnabled ? ydoc : null}
+                          collabSynced={
+                            collabEditorEnabled ? collabSynced : true
+                          }
+                          awareness={collabEditorEnabled ? awareness : null}
                           user={currentUser}
                           editable={editorCanEdit}
                           localFileMode={isLocalFileDocument}
@@ -1854,7 +1875,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                           pendingHighlight={pendingComment?.range ?? null}
                           onActivateThread={
                             editorCanEdit && !isLocalFileDocument
-                              ? setSelectedThreadId
+                              ? activateCommentThread
                               : undefined
                           }
                           onJoinTitle={joinFirstBodyBlockToTitle}
@@ -1883,6 +1904,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                     })()}
                     {!bodyHydrationPending &&
                     !isLocalFileDocument &&
+                    canEdit &&
                     collabLoading ? (
                       <div
                         className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-muted-foreground"
@@ -1910,20 +1932,21 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             open={utilityPanel !== null}
             onOpenChange={(open) => {
               if (!open) {
-                setUtilityPanel(null);
-                setPendingComment(null);
+                handleUtilityPanelChange(null);
               }
             }}
           >
             <SheetContent
               side="right"
-              className="w-[85vw] max-w-sm p-0"
+              className="flex min-h-0 w-[85vw] max-w-sm flex-col overflow-hidden p-0"
               aria-describedby={undefined}
             >
               <SheetHeader className="sr-only">
                 <SheetTitle>{utilityPanelTitle}</SheetTitle>
               </SheetHeader>
-              {utilityPanelContent}
+              <div className="min-h-0 min-w-0 flex-1 overflow-x-hidden overflow-y-auto">
+                {utilityPanelContent}
+              </div>
             </SheetContent>
           </Sheet>
         ) : null}

package/corpus/templates/content/app/components/editor/database/sidebar.tsx

@@ -136,8 +136,14 @@ export function ContentFilesSidebarView({
     | "scroll"
   >;
 }) {
+  const usableData =
+    data?.database &&
+    Array.isArray(data.items) &&
+    Array.isArray(data.properties)
+      ? data
+      : undefined;
   const viewConfig = applyPersonalSidebarViewOverrides(
-    data?.database.viewConfig ?? defaultDatabaseViewConfig(),
+    usableData?.database.viewConfig ?? defaultDatabaseViewConfig(),
     overrides,
   );
   const [selectedViewId, setSelectedViewId] = useState(
@@ -154,10 +160,10 @@ export function ContentFilesSidebarView({
   useEffect(() => {
     setConstraintsCleared(false);
   }, [activeFilterKey, activeView.id]);
-  const items = data
+  const items = usableData
     ? applyDatabaseView(
-        data.items,
-        data.properties,
+        usableData.items,
+        usableData.properties,
         "",
         constraintsCleared ? [] : activeView.filters,
         activeView.sorts,
@@ -167,16 +173,18 @@ export function ContentFilesSidebarView({
   const groups = databaseVisibleGroups(
     databaseViewItemGroups(
       items,
-      data?.properties ?? [],
+      usableData?.properties ?? [],
       activeView.groupByPropertyId,
     ),
     activeView.hideEmptyGroups === true,
   );
-  const hasFilesHierarchy = data?.properties.some(
+  const hasFilesHierarchy = usableData?.properties.some(
     (property) => property.definition.systemRole === "files_parent",
   );
   const hierarchyItems = hasFilesHierarchy ? items : undefined;
-  const hierarchyUniverseItems = hasFilesHierarchy ? data?.items : undefined;
+  const hierarchyUniverseItems = hasFilesHierarchy
+    ? usableData?.items
+    : undefined;
   return (
     <div className="min-w-0">
       {viewConfig.views.length > 1 && (
@@ -204,7 +212,10 @@ export function ContentFilesSidebarView({
         {...labels}
         groups={groups}
         grouped={
-          !!databaseViewGroupingProperty(activeView, data?.properties ?? [])
+          !!databaseViewGroupingProperty(
+            activeView,
+            usableData?.properties ?? [],
+          )
         }
         isLoading={isLoading}
         hasActiveConstraints={

package/corpus/templates/content/app/components/sidebar/DocumentSidebar.tsx

@@ -7,9 +7,10 @@ import {
   useActionMutation,
   useActionQuery,
 } from "@agent-native/core/client/hooks";
-import { useT } from "@agent-native/core/client/i18n";
+import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
 import { OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
+import { SidebarFooterActions } from "@agent-native/toolkit/app-shell";
 import {
   closestCenter,
   DndContext,
@@ -1278,6 +1279,53 @@ export function DocumentSidebar({
     </Link>
   );
 
+  const collapseButton = (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={collapsed ? t("sidebar.expand") : t("sidebar.collapse")}
+          className="flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+          onClick={onToggleCollapsed}
+        >
+          {collapsed ? (
+            <IconLayoutSidebarLeftExpand size={16} />
+          ) : (
+            <IconLayoutSidebarLeftCollapse size={16} />
+          )}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="right">
+        {collapsed ? t("sidebar.expand") : t("sidebar.collapse")}
+      </TooltipContent>
+    </Tooltip>
+  );
+  const searchButton = (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={t("sidebar.search")}
+          className="flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+          onClick={() => setIsSearching((value) => !value)}
+        >
+          <IconSearch size={16} />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="right">{t("sidebar.search")}</TooltipContent>
+    </Tooltip>
+  );
+  const translateButton = (
+    <LanguagePicker variant="ghost-icon" label={t("settings.languageLabel")} />
+  );
+  const feedbackButton = (
+    <FeedbackButton
+      variant={collapsed ? "icon" : "sidebar"}
+      side="right"
+      className={collapsed ? "size-8" : "h-8 min-w-0"}
+    />
+  );
+
   const renderAgentNavButton = () => (
     <Link
       to="/agent"
@@ -1832,17 +1880,6 @@ export function DocumentSidebar({
   if (collapsed) {
     return (
       <div className="agent-layout-left-drawer flex h-full w-12 flex-col items-center gap-1 border-e border-border bg-sidebar py-3 transition-[width] duration-200 ease-out">
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <button
-              className="w-10 h-10 flex items-center justify-center rounded-lg hover:bg-accent text-muted-foreground hover:text-foreground"
-              onClick={onToggleCollapsed}
-            >
-              <IconLayoutSidebarLeftExpand size={18} />
-            </button>
-          </TooltipTrigger>
-          <TooltipContent>{t("sidebar.expand")}</TooltipContent>
-        </Tooltip>
         {renderCollapsedNewButton()}
         <Tooltip>
           <TooltipTrigger asChild>
@@ -1876,6 +1913,13 @@ export function DocumentSidebar({
           </TooltipTrigger>
           <TooltipContent>{t("navigation.settings")}</TooltipContent>
         </Tooltip>
+        <SidebarFooterActions
+          collapsed
+          feedback={feedbackButton}
+          translate={translateButton}
+          search={searchButton}
+          collapse={collapseButton}
+        />
       </div>
     );
   }
@@ -1908,30 +1952,6 @@ export function DocumentSidebar({
             Content
           </span>
         </div>
-        <div className="flex items-center gap-0.5">
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <button
-                className="w-9 h-9 flex items-center justify-center rounded-lg hover:bg-accent text-muted-foreground hover:text-foreground"
-                onClick={() => setIsSearching(!isSearching)}
-              >
-                <IconSearch size={16} />
-              </button>
-            </TooltipTrigger>
-            <TooltipContent>{t("sidebar.search")}</TooltipContent>
-          </Tooltip>
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <button
-                className="w-9 h-9 flex items-center justify-center rounded-lg hover:bg-accent text-muted-foreground hover:text-foreground"
-                onClick={onToggleCollapsed}
-              >
-                <IconLayoutSidebarLeftCollapse size={16} />
-              </button>
-            </TooltipTrigger>
-            <TooltipContent>{t("sidebar.collapse")}</TooltipContent>
-          </Tooltip>
-        </div>
       </div>
 
       {/* Search */}
@@ -2098,13 +2118,17 @@ export function DocumentSidebar({
       {/* Footer */}
       <div className="shrink-0 space-y-2 px-3 py-2">
         {isCodeMode ? <DevDatabaseLink /> : null}
-        <div className="flex items-center justify-end gap-1">
-          <FeedbackButton className="h-8 min-w-0 flex-1 gap-2 rounded-md px-2 py-0" />
-          <div className="flex shrink-0 items-center gap-0.5">
-            <NotionButton />
-            <ThemeToggle />
-          </div>
+        <div className="flex justify-end gap-0.5">
+          <NotionButton />
+          <ThemeToggle />
         </div>
+        <SidebarFooterActions
+          feedback={feedbackButton}
+          translate={translateButton}
+          search={searchButton}
+          collapse={collapseButton}
+          className="px-0 py-0"
+        />
       </div>
 
       {/* Resize handle */}

package/corpus/templates/content/app/global.css

@@ -80,7 +80,7 @@
   --accent: 0 0% 18%;
   --accent-foreground: 0 0% 90%;
 
-  --destructive: 0 84% 60%;
+  --destructive: 0 91% 71%;
   --destructive-foreground: 0 0% 100%;
 
   --border: 0 0% 24%;

package/corpus/templates/content/app/i18n-data.ts

@@ -3085,6 +3085,7 @@ const enUS = {
     askAi: "Ask AI",
     resolve: "Resolve",
     resolved: "Resolved ({{count}})",
+    unanchored: "Highlight unavailable",
     reply: "Reply...",
     reopen: "Reopen",
     agentRegardingText: 'Regarding this text: "{{text}}"',
@@ -8761,6 +8762,19 @@ const contentReferenceMessagesByLocale = {
   },
 } satisfies Partial<Record<LocaleCode, typeof enUS.editor.reference>>;
 
+const commentMessagesByLocale = {
+  "zh-CN": { unanchored: "高亮不可用" },
+  "zh-TW": { unanchored: "無法使用醒目提示" },
+  "es-ES": { unanchored: "Resaltado no disponible" },
+  "fr-FR": { unanchored: "Surlignage indisponible" },
+  "de-DE": { unanchored: "Hervorhebung nicht verfügbar" },
+  "ja-JP": { unanchored: "ハイライトを利用できません" },
+  "ko-KR": { unanchored: "강조 표시를 사용할 수 없음" },
+  "pt-BR": { unanchored: "Destaque indisponível" },
+  "hi-IN": { unanchored: "हाइलाइट उपलब्ध नहीं है" },
+  "ar-SA": { unanchored: "التمييز غير متاح" },
+} satisfies Partial<Record<LocaleCode, Partial<typeof enUS.comments>>>;
+
 function mergeMessages(overrides: PartialMessages): Messages {
   return {
     root: { ...enUS.root, ...overrides.root },
@@ -8862,6 +8876,7 @@ function mergeMessagesForLocale(
   });
   return {
     ...base,
+    comments: { ...base.comments, ...commentMessagesByLocale[locale] },
     root: { ...base.root, ...rawLiteralOverrides.root },
     team: { ...base.team, ...rawLiteralOverrides.team },
     settings: { ...base.settings, ...rawLiteralOverrides.settings },

package/corpus/templates/content/changelog/2026-07-23-shared-pages-now-keep-durable-content-visible-and-comment-th.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Shared pages now keep durable content visible, and comment threads stay stable and connected while you navigate.

package/corpus/templates/content/changelog/2026-07-24-borderless-secondary-surfaces.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-24
+---
+
+Secondary controls and dashboard surfaces now use quieter borderless styling.

package/corpus/templates/content/changelog/2026-07-24-comment-drafts-now-stay-open-when-saving-fails-and-long-live.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-24
+---
+
+Comment drafts now stay open when saving fails, and long-lived document sessions no longer flood the browser with sync requests.

package/corpus/templates/content/changelog/2026-07-24-sidebar-footer-controls-follow-a-consistent-order.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-24
+---
+
+Sidebar utility controls now follow a consistent footer order.

package/corpus/templates/design/actions/update-file.ts

@@ -5,7 +5,7 @@ import {
   applyText,
   seedFromText,
 } from "@agent-native/core/collab";
-import { isPostgres } from "@agent-native/core/db";
+import { getDbExec, isPostgres } from "@agent-native/core/db";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
 import { and, eq, isNull, sql } from "drizzle-orm";
 import { z } from "zod";
@@ -16,6 +16,30 @@ import { assertDesignHtmlEditIntegrity } from "../shared/html-integrity.js";
 import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 import { sourceContentHash } from "../shared/source-workspace.js";
 
+// TEMPORARY diagnostic — remove once we've read a few real conflicts in prod.
+// Conflicts are now benign 409s the framework no longer error-logs; this keeps
+// them visible in Netlify, and `content-conflict`'s cacheIsStale field tells us
+// whether they're the multi-instance stale-cache phantom (→ worth the core
+// reload fix) or a genuine concurrent writer (→ 409-rebase is already correct).
+function logSaveConflictDebug(
+  event: string,
+  detail: Record<string, unknown>,
+): void {
+  console.warn(`[update-file:debug] ${event}`, detail);
+}
+
+// 404 via statusCode (NOT status — the action route only reads statusCode) so
+// the client save-outbox treats a gone file as terminal and drops it, instead
+// of looping a masked 500. Used at every missing-file guard, including the
+// post-lock rereads a concurrent delete can hit.
+function fileNotFound(id: string): Error & { statusCode?: number } {
+  const err = new Error(`File not found: ${id}`) as Error & {
+    statusCode?: number;
+  };
+  err.statusCode = 404;
+  return err;
+}
+
 function rowsAffected(result: unknown): number | undefined {
   const candidate = result as {
     rowsAffected?: unknown;
@@ -169,16 +193,8 @@ export default defineAction({
       .limit(1);
 
     if (!file) {
-      // Terminal (not transient): the row is gone or out of access scope, so a
-      // retry can never succeed. Mark it 404 so the client save-outbox drops the
-      // entry instead of retrying forever (which turns one orphaned/deleted
-      // screen into an update-file 500 storm — see design-save-outbox
-      // isTerminalSaveError).
-      const notFound = new Error(`File not found: ${id}`) as Error & {
-        status?: number;
-      };
-      notFound.status = 404;
-      throw notFound;
+      // The row is gone or out of access scope — retry can't succeed.
+      throw fileNotFound(id);
     }
 
     await assertAccess("design", file.designId, "editor");
@@ -232,7 +248,9 @@ export default defineAction({
           .where(eq(schema.designFiles.id, id))
           .limit(1);
         if (!persistedFile) {
-          throw new Error(`File not found: ${id}`);
+          // Delete-race: the row passed the access check but is gone now.
+          // Same 404 as the outer guard, not a bare 500 the outbox retries.
+          throw fileNotFound(id);
         }
 
         const persistedContentHash = sourceContentHash(persistedFile.content);
@@ -390,9 +408,47 @@ export default defineAction({
                 skippedStaleMirror = true;
               }
             } else {
-              throw new Error(
+              const liveContentHash = sourceContentHash(liveContent);
+              // Diagnostic probe (never affects the outcome): `getText` read this
+              // instance's Y.Doc cache, never re-hydrated from the DB. Compare it
+              // to the freshly persisted text_snapshot so the log distinguishes a
+              // multi-instance stale cache (cacheIsStale) from a genuine writer.
+              let freshDbLiveHash: string | null = null;
+              try {
+                const { rows } = await getDbExec().execute({
+                  sql: "SELECT text_snapshot FROM _collab_docs WHERE doc_id = ?",
+                  args: [id],
+                });
+                if (rows.length > 0) {
+                  freshDbLiveHash = sourceContentHash(
+                    String(rows[0]?.text_snapshot ?? ""),
+                  );
+                }
+              } catch {
+                // diagnostic only
+              }
+              logSaveConflictDebug("content-conflict", {
+                id,
+                caller: context?.caller,
+                syncCollab,
+                operationRevision: operationRevision ?? null,
+                expectedVersionHash,
+                sentContentHash: sourceContentHash(content),
+                liveContentHash,
+                persistedMirrorHash: persistedContentHash,
+                cacheIsStale:
+                  freshDbLiveHash !== null &&
+                  freshDbLiveHash !== liveContentHash,
+                freshDbMatchesExpected: freshDbLiveHash === expectedVersionHash,
+              });
+              // 409 (statusCode), not a bare 500: an expected optimistic-
+              // concurrency outcome the framework returns verbatim and the client
+              // rebases from, instead of a Sentry-captured fault + retry storm.
+              const conflict = new Error(
                 "File changed since it was read. Re-read the file and retry.",
-              );
+              ) as Error & { statusCode?: number };
+              conflict.statusCode = 409;
+              throw conflict;
             }
           }
         }
@@ -461,7 +517,9 @@ export default defineAction({
             // guarded UPDATE alone can still race. Serialize design-file renames in
             // this rare path without using SQLite's fragile async savepoint wrapper.
             await (
-              tx as unknown as { execute: (query: unknown) => Promise<unknown> }
+              tx as unknown as {
+                execute: (query: unknown) => Promise<unknown>;
+              }
             ).execute(sql`LOCK TABLE design_files IN SHARE ROW EXCLUSIVE MODE`);
             const [collision] = await tx
               .select({ id: schema.designFiles.id })
@@ -545,7 +603,7 @@ export default defineAction({
             .from(schema.designFiles)
             .where(eq(schema.designFiles.id, id))
             .limit(1);
-          if (!confirmed) throw new Error(`File not found: ${id}`);
+          if (!confirmed) throw fileNotFound(id);
           const confirmedHash = sourceContentHash(confirmed.content);
           const exactOperationPersisted =
             confirmed.contentOperationSource === operationSource &&
@@ -622,9 +680,18 @@ export default defineAction({
         }
         return;
       }
-      throw new Error(
+      logSaveConflictDebug("retry-exhausted", {
+        id,
+        caller: context?.caller,
+        operationSource: operationSource ?? null,
+        operationRevision: operationRevision ?? null,
+        expectedVersionHash,
+      });
+      const exhausted = new Error(
         "File changed repeatedly while it was being saved. Re-read the file and retry.",
-      );
+      ) as Error & { statusCode?: number };
+      exhausted.statusCode = 409;
+      throw exhausted;
     });
 
     // Update the parent design's updatedAt timestamp. This still runs even