@agent-native/core 0.119.5 → 0.120.0

package/corpus/core/src/templates/workspace-core/.agents/skills/integration-webhooks/SKILL.md

@@ -16,10 +16,10 @@ metadata:
 
 Integration webhooks (Slack, Telegram, WhatsApp, email, Google Docs, etc.) must
 **enqueue work to SQL and return 200 immediately**, then process the work in a
-**separate fresh function execution** kicked off by a self-fired HTTP POST. A
-recurring retry job sweeps anything that gets stuck. This pattern works on every
-serverless host (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) without
-relying on platform-specific background-execution features.
+**separate fresh function execution** kicked off by a self-fired HTTP POST. SQL
+is always the source of truth. Long-lived hosts use an in-process retry loop as
+a best-effort safety net; serverless deployments must use an external durable
+sweep when recovery cannot depend on a process staying alive.
 
 Do not run agent loops inside the webhook handler itself. Do not rely on
 fire-and-forget `Promise`s after `return`ing from a serverless handler — they get
@@ -38,8 +38,9 @@ Past attempts that don't work cross-host:
   freeze the execution context the moment the response goes out. The promise
   is silently killed, the user gets no reply, and there's no error in the
   logs.
-- **Netlify Background Functions** — Netlify-only, requires a `-background`
-  filename suffix, breaks on every other host.
+- **A platform background function as the queue** — host-specific execution is
+  useful as a delivery mechanism, but it cannot replace the SQL row or atomic
+  claim shared by every host.
 - **Cloudflare `event.waitUntil()`** — CF Workers only, not portable.
 - **Vercel Fluid / `after()`** — Vercel-only, gated behind specific runtimes.
 - **A long-lived in-process queue** — fine on a single Node box, but on
@@ -62,8 +63,9 @@ and a recurring job is the safety net.
                             2. INSERT INTO integration_pending_tasks
                                  (status='pending', payload=...)
                                                                   │
-                            3. fetch(POST /integrations/_process-task)
-                                 — fire-and-forget, NO await on body
+                            3. dispatch POST /integrations/process-task
+                                 — portable self-fire by default
+                                 — acknowledged background handoff when enabled
                                                                   │
                             4. return 200 to platform ◄───────────┘
 
@@ -79,7 +81,7 @@ and a recurring job is the safety net.
 
 
                           ┌──────────────────────────────────────────────┐
-                          │  Recurring job (every 60s) — safety net      │
+                          │  Recovery sweep (every 60s) — safety net    │
                           │  Re-fires processor for tasks stuck in       │
                           │  'pending' or 'processing' beyond timeout.   │
                           │  Caps retries at 3 then marks 'failed'.      │
@@ -98,6 +100,7 @@ loop.
 | `packages/core/src/integrations/webhook-handler.ts`                     | Verifies signature, parses, enqueues task, fires processor             |
 | `packages/core/src/integrations/pending-tasks-store.ts`                 | SQL queue: `insertPendingTask`, `claimPendingTask`, `markTaskCompleted`, `markTaskFailed` |
 | `packages/core/src/integrations/pending-tasks-retry-job.ts`             | Recurring retry sweep (`startPendingTasksRetryJob`, `retryStuckPendingTasks`) |
+| `packages/core/src/integrations/integration-durable-dispatch.ts`        | Default-off acknowledged dispatch, scoped rollout, and outcome recording |
 | `packages/core/src/integrations/types.ts`                               | `PlatformAdapter`, `IncomingMessage`, `OutgoingMessage`                |
 | `packages/core/src/integrations/adapters/{slack,telegram,whatsapp,email,google-docs}.ts` | One adapter per platform                                               |
 
@@ -108,7 +111,8 @@ All under `/_agent-native/integrations/`:
 | Method | Path                       | Purpose                                                       |
 | ------ | -------------------------- | ------------------------------------------------------------- |
 | POST   | `/:platform/webhook`       | Platform pings this. Verifies, enqueues, returns 200 quickly. |
-| POST   | `/_process-task`           | Self-webhook target. Claims a task and runs the agent loop.   |
+| POST   | `/process-task`            | Processor target. Claims a task and runs the agent loop.      |
+| POST   | `/retry-stuck-tasks`       | Signed, bounded recovery sweep for durable schedulers.        |
 | GET    | `/status`                  | All integrations status (settings UI).                        |
 | GET    | `/:platform/status`        | One platform's status.                                        |
 | POST   | `/:platform/enable`        | Enable an integration.                                        |
@@ -129,6 +133,10 @@ CREATE TABLE IF NOT EXISTS integration_pending_tasks (
   org_id             TEXT,
   status             TEXT    NOT NULL,   -- pending | processing | completed | failed
   attempts           INTEGER NOT NULL DEFAULT 0,
+  dispatch_attempts  INTEGER NOT NULL DEFAULT 0,
+  last_dispatch_at   INTEGER,
+  last_dispatch_outcome TEXT,
+  dispatch_scope     TEXT,             -- persisted channel scope for recovery
   error_message      TEXT,
   created_at         INTEGER NOT NULL,
   updated_at         INTEGER NOT NULL,
@@ -136,6 +144,8 @@ CREATE TABLE IF NOT EXISTS integration_pending_tasks (
 );
 CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created
   ON integration_pending_tasks(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_pending_tasks_dispatch_scope
+  ON integration_pending_tasks(platform, dispatch_scope);
 ```
 
 The store layer creates this lazily on first use via `ensureTable()` and uses
@@ -143,10 +153,38 @@ The store layer creates this lazily on first use via `ensureTable()` and uses
 
 `claimPendingTask` is the critical concurrency primitive: it atomically flips
 `pending` → `processing` and increments `attempts`, returning `null` if another
-worker beat us to it. Both the initial fire-and-forget call and the retry job
+worker beat us to it. Both the initial dispatch and every recovery sweep
 funnel through the same processor endpoint, and `claimPendingTask` is what
 prevents the same task from being processed twice.
 
+### Netlify durable recovery
+
+The portable self-dispatch remains the default. To emit and use Netlify's
+acknowledged background worker plus a one-minute scheduled recovery function,
+set `AGENT_INTEGRATION_DURABLE_DISPATCH=true` at build and runtime. A production
+rollout can be narrowed with the comma-separated
+`AGENT_INTEGRATION_DURABLE_DISPATCH_SCOPES` allowlist. Supported values are
+`<platform>:*`, `<platform>:<external-thread-id>`, and, for adapters that expose
+one, `<platform>:<channel-id>` (for example `slack:C123`).
+Channel-scoped handoffs persist that scope separately from the provider thread
+identity so a later bounded recovery sweep applies the same allowlist decision.
+
+Workspace deploys emit this pair only for the Dispatch control-plane app, which
+owns workspace messaging integrations. Standalone templates emit their own
+pair when the same flag is enabled.
+
+The background handoff waits only for Netlify's enqueue acknowledgement, not
+for the agent loop. A failed or non-2xx acknowledgement falls back to the
+portable processor. The scheduled function calls the HMAC-authenticated,
+bounded `/retry-stuck-tasks` route; its atomic compare-and-set update prevents
+overlapping sweeps from dispatching the same stale row twice.
+Rows acknowledged by the 15-minute background worker use a 16-minute stale
+cutoff, while portable synchronous dispatches retain the shorter serverless
+cutoff. Apply that lease predicate before `LIMIT` so healthy long runs cannot
+hide recoverable work. The background processor writes its lease marker in the
+same atomic update that claims the row; best-effort dispatch telemetry is not
+trusted for replay safety.
+
 ## Adding a New Platform Adapter
 
 1. **Implement `PlatformAdapter`** in `packages/core/src/integrations/adapters/<platform>.ts`:
@@ -245,9 +283,10 @@ so a normal long-running reply is safe.
 
 ## Cross-Platform Considerations
 
-- **No platform-specific background APIs.** No `waitUntil`, no
-  `-background.ts` filenames, no Vercel `after()`. The pattern works
-  identically on every host because it only uses `fetch()` and SQL.
+- **Portable correctness, optional host acceleration.** Every host uses SQL,
+  HMAC-authenticated processor routes, and atomic claims. A host-specific
+  background function or scheduler may provide a more reliable wake-up, but
+  disabling it must preserve the portable path.
 - **No assumed runtime.** The processor endpoint is a normal H3 handler under
   `/_agent-native/`. It runs wherever the rest of the framework runs.
 - **No persistent in-memory state.** The dedup map in the webhook handler is
@@ -262,11 +301,12 @@ so a normal long-running reply is safe.
 
 ## Why Fire-and-Forget on Serverless Is Unreliable
 
-Even though the webhook handler does `fetch(processorUrl, ...)` without
-awaiting the response body, that initial dispatch is **not** guaranteed to
-complete before the function freezes. In practice it usually does — the TCP
-connect + write happens quickly — but the recurring retry job is the safety
-net for the cases where:
+The portable webhook path gives the outbound processor request a short head
+start but does not wait for the response body, so that initial dispatch is
+**not** guaranteed to complete before the function freezes. On a long-lived
+host, the in-process retry loop is a best-effort safety net. On Netlify with
+durable dispatch enabled, the initial handoff is acknowledged and the external
+scheduled function supplies the recovery wake-up for cases where:
 
 - The serverless platform froze the handler before the outbound `fetch`
   flushed its bytes.
@@ -278,8 +318,9 @@ Tasks stuck in `pending` for >90s or `processing` for >5min get re-fired up to
 3 times. After 3 attempts they're marked `failed` permanently so we stop
 spamming the processor.
 
-**Never assume the initial fire-and-forget succeeded.** Always rely on the
-queue + retry job for at-least-once delivery.
+**Never assume the initial dispatch succeeded.** Rely on the SQL queue, atomic
+claim, and a recovery mechanism whose lifetime is independent of the original
+request. An in-process timer alone is not that mechanism on serverless.
 
 ## Debugging Checklist
 
@@ -292,7 +333,7 @@ queue + retry job for at-least-once delivery.
 4. **Status?** `pending` means the processor never picked it up — check that
    `_process-task` is reachable from the box itself (the self-fetch must work
    over the public URL). `processing` for over 5 minutes means the processor
-   died mid-run — the retry job will pick it up.
+   died mid-run — a live recovery sweep will pick it up.
 5. **Failed?** Check `error_message` and `attempts`. After 3 attempts the row
    is parked at `failed` and won't be retried.
 6. **Reply not delivered?** The processor likely succeeded but

package/corpus/templates/assets/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run",

package/corpus/templates/brain/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run --config vitest.config.ts",

package/corpus/templates/calendar/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run",

package/corpus/templates/clips/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "typecheck": "agent-native typecheck",

package/corpus/templates/content/actions/add-database-item.ts

@@ -217,6 +217,7 @@ export default defineAction({
       ...(await getContentDatabaseResponse(databaseId)),
       createdItemId: itemId,
       createdDocumentId: documentId,
+      createdDocumentUpdatedAt: now,
     };
   },
 });

package/corpus/templates/content/actions/set-document-property.ts

@@ -1,5 +1,4 @@
 import { defineAction } from "@agent-native/core";
-import { writeAppState } from "@agent-native/core/application-state";
 import { assertAccess } from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
@@ -87,7 +86,6 @@ export default defineAction({
           now,
         });
       }
-      await writeAppState("refresh-signal", { ts: Date.now() });
       return {
         documentId,
         databaseId: database.id,
@@ -133,8 +131,6 @@ export default defineAction({
       });
     }
 
-    await writeAppState("refresh-signal", { ts: Date.now() });
-
     return {
       documentId,
       databaseId: database.id,

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

@@ -38,6 +38,7 @@ const BLOCK_FIELD_DRAG_THRESHOLD = 6;
 
 interface DocumentBlockFieldsProps {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   /**
    * The fully-wired collaborative body editor for the primary "Content" field.
@@ -238,6 +239,7 @@ export function blockFieldsRenderState(args: {
  */
 export function DocumentBlockFields({
   documentId,
+  databaseDocumentId,
   canEdit,
   primaryEditor,
 }: DocumentBlockFieldsProps) {
@@ -303,6 +305,7 @@ export function DocumentBlockFields({
               // field while SAVING to another across an identity change.
               key={`${documentId}:${state.field.definition.id}`}
               documentId={documentId}
+              databaseDocumentId={databaseDocumentId}
               property={state.field}
               canEdit={canEdit}
             />
@@ -318,6 +321,7 @@ export function DocumentBlockFields({
       return (
         <MultiBlockFields
           documentId={documentId}
+          databaseDocumentId={databaseDocumentId}
           canEdit={canEdit}
           blockFields={state.fields}
           primaryEditor={primaryEditor}
@@ -329,12 +333,14 @@ export function DocumentBlockFields({
 
 function MultiBlockFields({
   documentId,
+  databaseDocumentId,
   canEdit,
   blockFields,
   primaryEditor,
   t,
 }: {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   blockFields: DocumentProperty[];
   primaryEditor: ReactNode;
@@ -504,6 +510,7 @@ function MultiBlockFields({
                   // doc's edits to the old field's closure.
                   key={`${documentId}:${property.definition.id}`}
                   documentId={documentId}
+                  databaseDocumentId={databaseDocumentId}
                   property={property}
                   canEdit={canEdit}
                 />
@@ -789,14 +796,16 @@ export function useBlockFieldEditor({
  */
 function AdditionalBlockEditor({
   documentId,
+  databaseDocumentId,
   property,
   canEdit,
 }: {
   documentId: string;
+  databaseDocumentId: string;
   property: DocumentProperty;
   canEdit: boolean;
 }) {
-  const setProperty = useSetDocumentProperty(documentId);
+  const setProperty = useSetDocumentProperty(documentId, databaseDocumentId);
   const propertyId = property.definition.id;
   const initialContent =
     typeof property.value === "string" ? property.value : "";

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

@@ -80,6 +80,7 @@ import {
   canWriteLinkedLocalSource,
   writeDocumentToLinkedLocalSource,
 } from "@/lib/local-content-source-files";
+import { isDatabaseChoicePending } from "@/lib/optimistic-document";
 import { cn } from "@/lib/utils";
 
 import {
@@ -1519,6 +1520,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   );
   const defaultIconKind = documentEditorDefaultIconKind(document);
   const isDatabasePage = Boolean(document.database);
+  const databaseChoicePending = isDatabaseChoicePending(
+    document,
+    createDatabase.isPending,
+  );
   const showNewDocumentTypeChooser =
     canEdit &&
     !isLocalFileDocument &&
@@ -1791,12 +1796,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                               type="button"
                               variant="outline"
                               className="justify-start gap-2"
-                              disabled={
-                                !editorCanEdit || createDatabase.isPending
-                              }
+                              disabled={!editorCanEdit || databaseChoicePending}
                               onClick={() => void handleChooseDatabase()}
                             >
-                              {createDatabase.isPending ? (
+                              {databaseChoicePending ? (
                                 <IconLoader2 className="animate-spin" />
                               ) : (
                                 <IconDatabase />
@@ -1867,6 +1870,9 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                         return (
                           <DocumentBlockFields
                             documentId={documentId}
+                            databaseDocumentId={
+                              document.databaseMembership.databaseDocumentId
+                            }
                             canEdit={editorCanEdit}
                             primaryEditor={primaryEditor}
                           />

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

@@ -32,7 +32,11 @@ export function DocumentInfoPanel({
         onSave={onSaveDescription}
       />
       {document.databaseMembership && !isLocalFileDocument ? (
-        <DocumentProperties documentId={document.id} canEdit={canEdit} />
+        <DocumentProperties
+          documentId={document.id}
+          databaseDocumentId={document.databaseMembership.databaseDocumentId}
+          canEdit={canEdit}
+        />
       ) : null}
     </div>
   );

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

@@ -165,6 +165,7 @@ function tWithFallback(
 
 interface DocumentPropertiesProps {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   popoversPortalled?: boolean;
 }
@@ -796,6 +797,7 @@ function scalarPlaceholder(type: DocumentPropertyType, t: TFunction) {
 
 export function DocumentProperties({
   documentId,
+  databaseDocumentId,
   canEdit,
   popoversPortalled = true,
 }: DocumentPropertiesProps) {
@@ -826,6 +828,7 @@ export function DocumentProperties({
               key={property.definition.id}
               property={property}
               documentId={documentId}
+              databaseDocumentId={databaseDocumentId}
               canEdit={canEdit}
               popoversPortalled={popoversPortalled}
               t={t}
@@ -927,12 +930,14 @@ function HiddenPropertiesMenu({
 function PropertyRow({
   property,
   documentId,
+  databaseDocumentId,
   canEdit,
   popoversPortalled,
   t,
 }: {
   property: DocumentProperty;
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   popoversPortalled: boolean;
   t: TFunction;
@@ -978,6 +983,7 @@ function PropertyRow({
         <PropertyValuePopover
           property={property}
           documentId={documentId}
+          databaseDocumentId={databaseDocumentId}
           portalled={popoversPortalled}
         >
           {value}

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

@@ -197,6 +197,7 @@ import {
 } from "@/hooks/use-document-properties";
 import {
   isDocumentUpdateConflict,
+  type DocumentUpdateResult,
   useDeleteDocument,
   useDocument,
   seedDatabaseItemDocumentCaches,
@@ -254,7 +255,10 @@ import { EmojiPicker } from "../EmojiPicker";
 import {
   createPreviewDocumentSaveController,
   deferredPreviewDocumentSave,
+  type PreviewDocumentPayload,
   type PreviewDocumentSaveAdapter,
+  type PreviewDocumentSaveDeferred,
+  type PreviewDocumentSaveSuccess,
 } from "../previewDocumentSaveController";
 import {
   acquirePreviewDocumentSaveController,
@@ -436,7 +440,8 @@ export function databaseCreatedItemForImmediatePreview(
   if (returnedItem) return returnedItem;
   if (!response.createdItemId || !response.createdDocumentId) return null;
 
-  const now = args.now ?? new Date().toISOString();
+  const now =
+    response.createdDocumentUpdatedAt ?? args.now ?? new Date().toISOString();
   const position = Math.max(
     0,
     (response.pagination?.totalItems ?? response.items.length + 1) - 1,
@@ -473,6 +478,42 @@ export function databaseCreatedItemForImmediatePreview(
   };
 }
 
+export function previewDocumentSaveResult(args: {
+  result: DocumentUpdateResult;
+  payload: PreviewDocumentPayload;
+  baseline?: PreviewDocumentPayload;
+  contentChanged: boolean;
+}): PreviewDocumentSaveDeferred | PreviewDocumentSaveSuccess {
+  const serverDocument = isDocumentUpdateConflict(args.result)
+    ? args.result.document
+    : args.result;
+  const titleSaveObservedExternalBody =
+    !args.contentChanged && serverDocument.content !== args.payload.content;
+
+  if (isDocumentUpdateConflict(args.result) || titleSaveObservedExternalBody) {
+    return deferredPreviewDocumentSave("conflict", {
+      lastSaved: args.baseline ?? args.payload,
+      pending: {
+        title: serverDocument.title,
+        content: serverDocument.content,
+        loadedUpdatedAt: serverDocument.updatedAt,
+        loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
+          serverDocument.content,
+        ),
+      },
+      deferredReason: "conflict",
+    });
+  }
+
+  return {
+    outcome: "saved",
+    loadedUpdatedAt: args.result.updatedAt,
+    loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
+      args.result.content,
+    ),
+  };
+}
+
 export function databaseBuilderHydrationSourceForItem(
   item: ContentDatabaseItem,
   sources: ContentDatabaseSource[],
@@ -4098,8 +4139,6 @@ function DatabaseItemPreview({
   // ever touch its own row's state. See previewDocumentSaveRegistry.
   const updateDocumentRef = useRef(updateDocument);
   updateDocumentRef.current = updateDocument;
-  const queryClientRef = useRef(queryClient);
-  queryClientRef.current = queryClient;
   const bodyHydrationPendingRef = useRef(bodyHydrationPending);
   bodyHydrationPendingRef.current = bodyHydrationPending;
   const draftVersionsRef = useRef<Map<string, number | null>>(new Map());
@@ -4244,30 +4283,14 @@ function DatabaseItemPreview({
           },
           {
             onSuccess: (result) => {
-              if (isDocumentUpdateConflict(result)) {
-                resolve(
-                  deferredPreviewDocumentSave("conflict", {
-                    lastSaved: baseline ?? payload,
-                    pending: {
-                      title: result.document.title,
-                      content: result.document.content,
-                      loadedUpdatedAt: result.document.updatedAt,
-                      loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
-                        result.document.content,
-                      ),
-                    },
-                    deferredReason: "conflict",
-                  }),
-                );
-                return;
-              }
-              resolve({
-                outcome: "saved" as const,
-                loadedUpdatedAt: result.updatedAt,
-                loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
-                  result.content,
-                ),
-              });
+              resolve(
+                previewDocumentSaveResult({
+                  result,
+                  payload,
+                  baseline,
+                  contentChanged,
+                }),
+              );
             },
             onError: reject,
           },
@@ -4276,12 +4299,6 @@ function DatabaseItemPreview({
     onSaved: (persistedPayload) => {
       const controller = peekPreviewDocumentSaveController(documentId);
       if (controller) enqueueDraftWrite(controller, "delete", persistedPayload);
-      void queryClientRef.current.invalidateQueries({
-        queryKey: contentDatabaseQueryKey(databaseDocumentId),
-      });
-      void queryClientRef.current.invalidateQueries({
-        queryKey: ["action", "list-documents"],
-      });
     },
     onError: (err) => {
       toast.error(dbText("failedToSavePagePreview"), {
@@ -4876,6 +4893,7 @@ function DatabaseItemPreview({
             {previewDocument.databaseMembership ? (
               <DocumentProperties
                 documentId={previewDocument.id}
+                databaseDocumentId={databaseDocumentId}
                 canEdit={previewCanEdit}
                 popoversPortalled={false}
               />
@@ -4913,6 +4931,7 @@ function DatabaseItemPreview({
                 const editor = previewDocument.databaseMembership ? (
                   <DocumentBlockFields
                     documentId={previewDocument.id}
+                    databaseDocumentId={databaseDocumentId}
                     canEdit={previewCanEdit}
                     primaryEditor={primaryEditor}
                   />

package/corpus/templates/content/app/components/editor/previewDocumentSaveController.ts

@@ -130,8 +130,8 @@ export interface PreviewDocumentSaveController {
   /** Adopt `payload` as the confirmed-saved baseline (no save scheduled). */
   mark(payload: PreviewDocumentPayload): void;
   /**
-   * Adopt a fresher server baseline while retaining the user's pending title
-   * and content. Used only after an explicit "keep local draft" choice.
+   * Adopt a fresher server baseline while retaining only fields the user
+   * changed locally. Used only after an explicit "keep local draft" choice.
    */
   rebasePending(payload: PreviewDocumentPayload): void;
   /** Replace callbacks captured by an older preview mount. */
@@ -261,8 +261,7 @@ export function createPreviewDocumentSaveController(
         // the controller was created/last marked — e.g. "empty" for a
         // brand-new page — forever, even after real content has been saved.
         const success = asSaveSuccess(result);
-        lastSaved = {
-          ...attempted,
+        const savedMetadata = {
           ...(success?.loadedUpdatedAt !== undefined
             ? { loadedUpdatedAt: success.loadedUpdatedAt }
             : {}),
@@ -270,6 +269,15 @@ export function createPreviewDocumentSaveController(
             ? { loadedContentWasEmpty: success.loadedContentWasEmpty }
             : {}),
         };
+        lastSaved = {
+          ...attempted,
+          ...savedMetadata,
+        };
+        // A later keystroke starts from `pending`, including while this save is
+        // in flight. Rebase that trailing payload onto our own successful write
+        // so its next CAS does not mistake the preceding save for an external
+        // change.
+        pending = { ...pending, ...savedMetadata };
         hasSavedLocally = true;
         deferredReason = null;
         inFlight = null;
@@ -336,9 +344,13 @@ export function createPreviewDocumentSaveController(
     },
     rebasePending(payload: PreviewDocumentPayload) {
       clearTimer();
+      const titleChangedLocally = pending.title !== lastSaved.title;
+      const contentChangedLocally = pending.content !== lastSaved.content;
       lastSaved = { ...payload };
       pending = {
         ...pending,
+        title: titleChangedLocally ? pending.title : payload.title,
+        content: contentChangedLocally ? pending.content : payload.content,
         loadedUpdatedAt: payload.loadedUpdatedAt,
         loadedContentWasEmpty: payload.loadedContentWasEmpty,
       };