@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4544.1.71c003c861

package/src/modules/customers/components/detail/ActivityTimeline.tsx

@@ -18,7 +18,7 @@ const TYPE_ICONS: Record<string, React.ComponentType<{ className?: string }>> =
 interface ActivityTimelineProps {
   activities: InteractionSummary[]
   onEdit?: (activity: InteractionSummary) => void
-  onMarkDone?: (activityId: string) => void | Promise<void>
+  onMarkDone?: (activityId: string, updatedAt?: string | null) => void | Promise<void>
 }
 
 export function ActivityTimeline({ activities, onEdit, onMarkDone }: ActivityTimelineProps) {
@@ -77,7 +77,7 @@ function TimelineEntry({
   t: TranslateFn
   withBorder: boolean
   onEdit?: (activity: InteractionSummary) => void
-  onMarkDone?: (activityId: string) => void | Promise<void>
+  onMarkDone?: (activityId: string, updatedAt?: string | null) => void | Promise<void>
 }) {
   const dateStr = activity.scheduledAt ?? activity.occurredAt ?? activity.createdAt
   const TypeIcon = TYPE_ICONS[activity.interactionType]
@@ -91,7 +91,7 @@ function TimelineEntry({
     if (!onMarkDone || markingDone) return
     setMarkingDone(true)
     try {
-      await onMarkDone(activity.id)
+      await onMarkDone(activity.id, activity.updatedAt)
     } finally {
       setMarkingDone(false)
     }

package/src/modules/customers/components/detail/AddressesSection.tsx

@@ -107,6 +107,7 @@ export function AddressesSection({
       const response = await apiCallOrThrow<Record<string, unknown>>(
         '/api/customers/addresses',
         {
+          // optimistic-lock-exempt: address link add/remove sub-resource
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({
@@ -123,6 +124,7 @@ export function AddressesSection({
       await apiCallOrThrow(
         '/api/customers/addresses',
         {
+          // optimistic-lock-exempt: address link add/remove sub-resource
           method: 'PUT',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({
@@ -138,6 +140,7 @@ export function AddressesSection({
       await apiCallOrThrow(
         '/api/customers/addresses',
         {
+          // optimistic-lock-exempt: address link add/remove sub-resource
           method: 'DELETE',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ id }),
@@ -170,6 +173,7 @@ export function AddressesSection({
       const response = await apiCallOrThrow<Record<string, unknown>>(
         '/api/customers/dictionaries/address-types',
         {
+          // optimistic-lock-exempt: address-type dictionary create-only
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ value }),

package/src/modules/customers/components/detail/CompanyPeopleSection.tsx

@@ -360,6 +360,7 @@ export function CompanyPeopleSection({
         for (const personId of addedIds) {
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: person-company link add/remove
               apiCallOrThrow(
                 `/api/customers/people/${encodeURIComponent(personId)}/companies`,
                 {
@@ -514,6 +515,7 @@ export function CompanyPeopleSection({
       try {
         await runWriteMutation(
           () =>
+            // optimistic-lock-exempt: person-company link add/remove
             apiCallOrThrow(
               `/api/customers/people/${encodeURIComponent(personId)}/companies/${encodeURIComponent(companyId)}`,
               { method: 'DELETE' },

package/src/modules/customers/components/detail/DealsSection.tsx

@@ -651,6 +651,7 @@ export function DealsSection({
               : currentCompanyIds
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: deal association list (link)
               updateCrud(
                 'customers/deals',
                 { id: dealId, personIds: nextPersonIds, companyIds: nextCompanyIds },
@@ -684,6 +685,7 @@ export function DealsSection({
               : currentCompanyIds
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: deal association list (unlink)
               updateCrud(
                 'customers/deals',
                 { id: dealId, personIds: nextPersonIds, companyIds: nextCompanyIds },
@@ -762,6 +764,7 @@ export function DealsSection({
         if (Object.keys(custom).length) payload.customFields = custom
         const { result } = await runWriteMutation(
           () =>
+            // optimistic-lock-exempt: deal create-only, no prior version
             createCrud<{ id?: string }>('customers/deals', payload, {
               errorMessage: translate('customers.people.detail.deals.error', 'Failed to save deal.'),
             }),
@@ -848,6 +851,7 @@ export function DealsSection({
         }
         await runWriteMutation(
           () =>
+            // optimistic-lock-exempt: deal association list (unlink)
             updateCrud('customers/deals', payload, {
               errorMessage: translate('customers.people.detail.deals.unlinkError', 'Failed to unlink deal.'),
             }),

package/src/modules/customers/components/detail/EmailCardActions.tsx

@@ -190,6 +190,11 @@ export function EmailCardActions({ data }: EmailCardActionsProps) {
             const next = data.currentVisibility === 'private' ? 'shared' : 'private'
             try {
               await runMutation({
+                // optimistic-lock-exempt: dedicated single-field visibility
+                // action endpoint (shared/private toggle), not a full-record
+                // edit. The canonical interaction edit/delete is version-locked
+                // at the command layer (customers.interactions.* commands); this
+                // idempotent toggle derives `next` from freshly-loaded state.
                 operation: async () => {
                   const r = await apiCall<{ ok?: boolean }>(
                     `/api/customers/interactions/${interactionId}/visibility`,

package/src/modules/customers/components/detail/EntityTagsDialog.tsx

@@ -854,6 +854,7 @@ export function EntityTagsDialog({
             readApiResultOrThrow<Record<string, unknown>>(
               '/api/customers/tags',
               {
+                // optimistic-lock-exempt: tag dictionary create-only
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
                 body: JSON.stringify({
@@ -892,6 +893,7 @@ export function EntityTagsDialog({
             readApiResultOrThrow<{ id: string; slug: string; label: string }>(
               '/api/customers/labels',
               {
+                // optimistic-lock-exempt: label dictionary create-only
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
                 body: JSON.stringify(payload),
@@ -956,6 +958,7 @@ export function EntityTagsDialog({
         await runGuardedMutation(
           () =>
             apiCallOrThrow(`/api/customers/${entityType === 'person' ? 'people' : 'companies'}`, {
+              // optimistic-lock-exempt: tag/label dictionary + custom-field selection write (assignment add/remove)
               method: 'PUT',
               headers: { 'content-type': 'application/json' },
               body: JSON.stringify({
@@ -984,6 +987,7 @@ export function EntityTagsDialog({
         await runGuardedMutation(
           () =>
             apiCallOrThrow('/api/customers/tags/assign', {
+              // optimistic-lock-exempt: tag assignment add/remove
               method: 'POST',
               headers: { 'content-type': 'application/json' },
               body: JSON.stringify({ tagId, entityId }),
@@ -996,6 +1000,7 @@ export function EntityTagsDialog({
         await runGuardedMutation(
           () =>
             apiCallOrThrow('/api/customers/tags/unassign', {
+              // optimistic-lock-exempt: tag assignment add/remove
               method: 'POST',
               headers: { 'content-type': 'application/json' },
               body: JSON.stringify({ tagId, entityId }),
@@ -1016,6 +1021,7 @@ export function EntityTagsDialog({
         await runGuardedMutation(
           () =>
             apiCallOrThrow('/api/customers/labels/assign', {
+              // optimistic-lock-exempt: label assignment add/remove
               method: 'POST',
               headers: { 'content-type': 'application/json' },
               body: JSON.stringify(payload),
@@ -1031,6 +1037,7 @@ export function EntityTagsDialog({
         await runGuardedMutation(
           () =>
             apiCallOrThrow('/api/customers/labels/unassign', {
+              // optimistic-lock-exempt: label assignment add/remove
               method: 'POST',
               headers: { 'content-type': 'application/json' },
               body: JSON.stringify(payload),

package/src/modules/customers/components/detail/ManageTagsDialog.tsx

@@ -760,6 +760,7 @@ export function ManageTagsDialog({ open, onClose }: ManageTagsDialogProps) {
             if (entry.id) {
               await runGuardedMutation(
                 () =>
+                  // optimistic-lock-exempt: tag dictionary entry assignment add/remove
                   apiCallOrThrow(`/api/customers/dictionaries/${category.kind}/${entry.id}`, {
                     method: 'DELETE',
                   }),
@@ -779,6 +780,7 @@ export function ManageTagsDialog({ open, onClose }: ManageTagsDialogProps) {
           if (!entry.id) {
             await runGuardedMutation(
               () =>
+                // optimistic-lock-exempt: tag dictionary entry create-only
                 apiCallOrThrow(`/api/customers/dictionaries/${category.kind}`, {
                   method: 'POST',
                   headers: { 'content-type': 'application/json' },
@@ -805,6 +807,7 @@ export function ManageTagsDialog({ open, onClose }: ManageTagsDialogProps) {
 
           await runGuardedMutation(
             () =>
+              // optimistic-lock-exempt: tag dictionary entry assignment add/remove
               apiCallOrThrow(`/api/customers/dictionaries/${category.kind}/${entry.id}`, {
                 method: 'PATCH',
                 headers: { 'content-type': 'application/json' },
@@ -891,6 +894,7 @@ export function ManageTagsDialog({ open, onClose }: ManageTagsDialogProps) {
     try {
       await runGuardedMutation(
         () =>
+          // optimistic-lock-exempt: tag dictionary kind-settings assignment add/remove
           apiCallOrThrow('/api/customers/dictionaries/kind-settings', {
             method: 'PATCH',
             headers: { 'content-type': 'application/json' },

package/src/modules/customers/components/detail/PersonCompaniesSection.tsx

@@ -238,6 +238,7 @@ export function PersonCompaniesSection({
         for (const companyId of removedIds) {
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: person-company link add/remove
               apiCallOrThrow(
                 `/api/customers/people/${encodeURIComponent(personId)}/companies/${encodeURIComponent(companyId)}`,
                 { method: 'DELETE' },
@@ -249,6 +250,7 @@ export function PersonCompaniesSection({
         for (const companyId of addedIds) {
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: person-company link add/remove
               apiCallOrThrow(
                 `/api/customers/people/${encodeURIComponent(personId)}/companies`,
                 {
@@ -271,6 +273,7 @@ export function PersonCompaniesSection({
         ) {
           await runWriteMutation(
             () =>
+              // optimistic-lock-exempt: person-company link set-primary (add/remove)
               apiCallOrThrow(
                 `/api/customers/people/${encodeURIComponent(personId)}/companies/${encodeURIComponent(nextPrimaryId)}`,
                 {
@@ -332,6 +335,7 @@ export function PersonCompaniesSection({
       try {
         await runWriteMutation(
           () =>
+            // optimistic-lock-exempt: person-company link add/remove
             apiCallOrThrow(
               `/api/customers/people/${encodeURIComponent(personId)}/companies/${encodeURIComponent(companyId)}`,
               { method: 'DELETE' },

package/src/modules/customers/components/detail/RoleAssignmentRow.tsx

@@ -82,6 +82,7 @@ export function RoleAssignmentRow({
     try {
       await runMutationWithContext(
         () =>
+          // optimistic-lock-exempt: role assignment add/remove
           apiCallOrThrow(`/api/customers/${basePath}/${entityId}/roles?roleId=${role.id}`, {
             method: 'PUT',
             headers: { 'content-type': 'application/json' },
@@ -110,6 +111,7 @@ export function RoleAssignmentRow({
     try {
       await runMutationWithContext(
         () =>
+          // optimistic-lock-exempt: role assignment add/remove
           apiCallOrThrow(`/api/customers/${basePath}/${entityId}/roles?roleId=${role.id}`, {
             method: 'DELETE',
           }),

package/src/modules/customers/components/detail/ScheduleActivityDialog.tsx

@@ -5,7 +5,8 @@ import { Users, Phone, Check, Mail, Calendar, AlertTriangle, X, StickyNote } fro
 import { cn } from '@open-mercato/shared/lib/utils'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { validatePhoneNumber } from '@open-mercato/shared/lib/phone'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { mapCrudServerErrorToFormErrors } from '@open-mercato/ui/backend/utils/serverErrors'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
@@ -411,12 +412,19 @@ export function ScheduleActivityDialog({
         ...(Object.keys(customValues).length > 0 ? { customValues } : {}),
       }
       await runGuardedMutation(
-        () =>
-          apiCallOrThrow('/api/customers/interactions', {
-            method: isSaveEdit ? 'PUT' : 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(payload),
-          }),
+        () => {
+          const call = () =>
+            apiCallOrThrow('/api/customers/interactions', {
+              method: isSaveEdit ? 'PUT' : 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            })
+          // Optimistic lock only applies to edits — a stale modal save against a
+          // concurrently changed/deleted activity surfaces the conflict bar (#2055).
+          return isSaveEdit
+            ? withScopedApiRequestHeaders(buildOptimisticLockHeader(editData?.updatedAt), call)
+            : call()
+        },
         {
           operation: isSaveEdit ? 'updateActivity' : 'createActivity',
           interactionId: editData?.id ?? null,
@@ -428,6 +436,14 @@ export function ScheduleActivityDialog({
       // Delay data reload so the dialog can unmount cleanly and Radix restores body scroll
       requestAnimationFrame(() => { onActivityCreated?.() })
     } catch (err) {
+      // An optimistic-lock 409 was already surfaced as the persistent conflict
+      // bar by `runGuardedMutation` (useGuardedMutation → surfaceRecordConflict).
+      // Do NOT additionally flash the raw `record_modified` code here — that
+      // showed an untranslated toast on top of the localized bar (#2055 QA).
+      if (extractOptimisticLockConflict(err)) {
+        onClose()
+        return
+      }
       const { message, fieldErrors } = mapCrudServerErrorToFormErrors(err)
       const phoneFieldError = fieldErrors?.phoneNumber
       if (state.activityType === 'call' && phoneFieldError) {

package/src/modules/customers/components/detail/hooks/useInteractionMutations.ts

@@ -2,7 +2,9 @@
 
 import * as React from 'react'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 export type GuardedMutationRunner = <T>(
@@ -18,8 +20,8 @@ export type UseInteractionMutationsOptions = {
 }
 
 export type UseInteractionMutationsResult = {
-  completeInteraction: (interactionId: string) => Promise<void>
-  cancelInteraction: (interactionId: string) => Promise<void>
+  completeInteraction: (interactionId: string, updatedAt?: string | null) => Promise<void>
+  cancelInteraction: (interactionId: string, updatedAt?: string | null) => Promise<void>
 }
 
 /**
@@ -44,20 +46,24 @@ export function useInteractionMutations({
   }, [logContext, onAfterChange])
 
   const completeInteraction = React.useCallback(
-    async (interactionId: string) => {
+    async (interactionId: string, updatedAt?: string | null) => {
       try {
         await runMutationWithContext(
           () =>
-            apiCallOrThrow('/api/customers/interactions/complete', {
-              method: 'POST',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify({ id: interactionId, occurredAt: new Date().toISOString() }),
-            }),
+            withScopedApiRequestHeaders(
+              buildOptimisticLockHeader(updatedAt ?? null),
+              () => apiCallOrThrow('/api/customers/interactions/complete', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ id: interactionId, occurredAt: new Date().toISOString() }),
+              }),
+            ),
           { id: interactionId, status: 'done', operation: 'completeActivity' },
         )
         flash(t('customers.timeline.planned.completed', 'Activity completed'), 'success')
         await triggerRefresh()
       } catch (err) {
+        if (surfaceRecordConflict(err, t)) { await triggerRefresh(); return }
         console.warn(`[${logContext}] complete interaction failed`, interactionId, err)
         flash(t('customers.timeline.planned.error', 'Failed to complete activity'), 'error')
       }
@@ -66,20 +72,24 @@ export function useInteractionMutations({
   )
 
   const cancelInteraction = React.useCallback(
-    async (interactionId: string) => {
+    async (interactionId: string, updatedAt?: string | null) => {
       try {
         await runMutationWithContext(
           () =>
-            apiCallOrThrow('/api/customers/interactions', {
-              method: 'PUT',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify({ id: interactionId, status: 'canceled' }),
-            }),
+            withScopedApiRequestHeaders(
+              buildOptimisticLockHeader(updatedAt ?? null),
+              () => apiCallOrThrow('/api/customers/interactions', {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ id: interactionId, status: 'canceled' }),
+              }),
+            ),
           { id: interactionId, status: 'canceled', operation: 'cancelActivity' },
         )
         flash(t('customers.timeline.planned.canceled', 'Activity canceled'), 'success')
         await triggerRefresh()
       } catch (err) {
+        if (surfaceRecordConflict(err, t)) { await triggerRefresh(); return }
         console.warn(`[${logContext}] cancel interaction failed`, interactionId, err)
         flash(t('customers.timeline.planned.cancelError', 'Failed to cancel activity'), 'error')
       }

package/src/modules/customers/components/detail/hooks/useInteractions.ts

@@ -1,7 +1,9 @@
 "use client"
 
 import * as React from 'react'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { InteractionSummary } from '../types'
 
@@ -226,87 +228,126 @@ export function useInteractions({
   const updateInteraction = React.useCallback(
     async (id: string, payload: InteractionUpdatePayload) => {
       setIsMutating(true)
+      // Send the optimistic-lock header (target's loaded `updatedAt`) so a stale
+      // edit — including a task/activity edited from another tab — surfaces the
+      // conflict bar instead of silently overwriting (#2055). A stale edit after
+      // the record was deleted elsewhere maps to the same 409 via the server's
+      // enforceRecordGoneIsConflict, instead of a bare "Interaction not found" 404.
+      const target = interactions.find((entry) => entry.id === id)
       try {
-        await apiCallOrThrow(
-          '/api/customers/interactions',
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ id, ...payload }),
-          },
-          { errorMessage: t('customers.interactions.update.error', 'Failed to update interaction.') },
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(target?.updatedAt ?? null),
+          () => apiCallOrThrow(
+            '/api/customers/interactions',
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ id, ...payload }),
+            },
+            { errorMessage: t('customers.interactions.update.error', 'Failed to update interaction.') },
+          ),
         )
         await refresh()
+      } catch (err) {
+        if (surfaceRecordConflict(err, t)) { await refresh(); return }
+        throw err
       } finally {
         setIsMutating(false)
       }
     },
-    [refresh, t],
+    [interactions, refresh, t],
   )
 
   const completeInteraction = React.useCallback(
     async (id: string) => {
       setIsMutating(true)
       setPendingId(id)
+      const target = interactions.find((entry) => entry.id === id)
       try {
-        await apiCallOrThrow(
-          '/api/customers/interactions/complete',
-          {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ id }),
-          },
-          { errorMessage: t('customers.interactions.complete.error', 'Failed to complete interaction.') },
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(target?.updatedAt ?? null),
+          () => apiCallOrThrow(
+            '/api/customers/interactions/complete',
+            {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ id }),
+            },
+            { errorMessage: t('customers.interactions.complete.error', 'Failed to complete interaction.') },
+          ),
         )
         await refresh()
+      } catch (err) {
+        if (surfaceRecordConflict(err, t)) { await refresh(); return }
+        throw err
       } finally {
         setPendingId(null)
         setIsMutating(false)
       }
     },
-    [refresh, t],
+    [interactions, refresh, t],
   )
 
   const cancelInteraction = React.useCallback(
     async (id: string) => {
       setIsMutating(true)
       setPendingId(id)
+      const target = interactions.find((entry) => entry.id === id)
       try {
-        await apiCallOrThrow(
-          '/api/customers/interactions/cancel',
-          {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ id }),
-          },
-          { errorMessage: t('customers.interactions.cancel.error', 'Failed to cancel interaction.') },
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(target?.updatedAt ?? null),
+          () => apiCallOrThrow(
+            '/api/customers/interactions/cancel',
+            {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ id }),
+            },
+            { errorMessage: t('customers.interactions.cancel.error', 'Failed to cancel interaction.') },
+          ),
         )
         await refresh()
+      } catch (err) {
+        if (surfaceRecordConflict(err, t)) { await refresh(); return }
+        throw err
       } finally {
         setPendingId(null)
         setIsMutating(false)
       }
     },
-    [refresh, t],
+    [interactions, refresh, t],
   )
 
   const deleteInteraction = React.useCallback(
     async (id: string) => {
       setIsMutating(true)
+      const target = interactions.find((entry) => entry.id === id)
       try {
-        await apiCallOrThrow(
-          `/api/customers/interactions?id=${encodeURIComponent(id)}`,
-          {
-            method: 'DELETE',
-          },
-          { errorMessage: t('customers.interactions.delete.error', 'Failed to delete interaction.') },
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(target?.updatedAt ?? null),
+          () =>
+            apiCallOrThrow(
+              `/api/customers/interactions?id=${encodeURIComponent(id)}`,
+              {
+                method: 'DELETE',
+              },
+              { errorMessage: t('customers.interactions.delete.error', 'Failed to delete interaction.') },
+            ),
         )
         await refresh()
+      } catch (err) {
+        // A stale delete (the record was changed/deleted in another tab) surfaces
+        // the unified conflict bar and re-syncs the list instead of a raw error (#2055).
+        if (surfaceRecordConflict(err, t)) {
+          await refresh()
+          return
+        }
+        throw err
       } finally {
         setIsMutating(false)
       }
     },
-    [refresh, t],
+    [interactions, refresh, t],
   )
 
   const hasMore = entityId != null && nextCursor != null

package/src/modules/customers/components/detail/hooks/usePersonTasks.ts

@@ -1,7 +1,8 @@
 "use client"
 
 import * as React from 'react'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { resolveTodoApiPath } from '../utils'
 import type { TodoLinkSummary } from '../types'
 import { generateTempId } from '@open-mercato/core/modules/customers/lib/detailHelpers'
@@ -22,6 +23,7 @@ type CustomerTodoRow = {
   todoDueAt: string | null
   todoCustomValues: Record<string, unknown> | null
   todoOrganizationId: string | null
+  todoUpdatedAt?: string | null
   organizationId: string
   tenantId: string
   createdAt: string
@@ -83,6 +85,7 @@ function mapRowToSummary(row: CustomerTodoRow): TodoLinkSummary {
     description: row.todoDescription ?? null,
     dueAt: row.todoDueAt ?? null,
     todoOrganizationId: row.todoOrganizationId ?? null,
+    updatedAt: row.todoUpdatedAt ?? null,
     customValues: row.todoCustomValues ?? null,
   }
 }
@@ -369,14 +372,21 @@ export function usePersonTasks({
         if (Object.keys(customValues).length) {
           body.customFields = customValues
         }
-        await apiCallOrThrow(
-          apiPath,
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
-          },
-          { errorMessage: 'Failed to update task.' },
+        // Send the optimistic-lock header (task's loaded updatedAt) so a stale
+        // edit — or an edit after the task was deleted in another tab — surfaces
+        // the unified conflict bar (409) instead of silently overwriting or
+        // returning a bare "Interaction not found" 404 (#2055).
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(task.updatedAt ?? null),
+          () => apiCallOrThrow(
+            apiPath,
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(body),
+            },
+            { errorMessage: 'Failed to update task.' },
+          ),
         )
         setTasks((prev) =>
           prev.map((item) => {
@@ -440,14 +450,17 @@ export function usePersonTasks({
       if (!task.id) throw new Error('Task link id missing')
       setIsMutating(true)
     try {
-      await apiCallOrThrow(
-        '/api/customers/todos',
-        {
-          method: 'DELETE',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ id: task.id }),
-        },
-        { errorMessage: 'Failed to remove task.' },
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(task.updatedAt ?? null),
+        () => apiCallOrThrow(
+          '/api/customers/todos',
+          {
+            method: 'DELETE',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ id: task.id }),
+          },
+          { errorMessage: 'Failed to remove task.' },
+        ),
       )
         setTasks((prev) => prev.filter((item) => item.id !== task.id))
         setPageInfo((prev) => ({