@webex/contact-center 3.12.0-llmrefactor.13 → 3.12.0-llmrefactor.15

package/src/metrics/ai-docs/metrics-spec.md

@@ -246,6 +246,7 @@ All event names are defined in `METRIC_EVENT_NAMES` (`constants.ts`). Events fol
 | `WXAPP_SESSION_SKIPPED` | `'WxApp Session Skipped'` | Webex Together session skipped (`wxcc_sdk.user.webex_together_session_init.ignore`) |
 | `WXAPP_USERSUB_PUBLISH_SUCCESS` / `FAILED` | `'WxApp Usersub Publish ...'` | Cross-client usersub publish (`wxcc_sdk.user.webex_together_usersub_publish.complete\|fail`). Preflight failures (missing `userId` or device URL before HTTP publish) emit `WXAPP_USERSUB_PUBLISH_FAILED` with `skipReason` (`user_id_unavailable` / `device_url_unavailable`) and no `timeEvent` timer. Stale-generation discards (teardown or concurrent disable while HTTP publish is in flight) call `cancelTimedEvent` without emitting success/fail only when the completing publish still owns the active timer (`usersubPublishMetricsId` guard — a newer overlapping publish must not have its timer cleared). |
 | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` / `FAILED` | `'WxApp Mercury Subscribe ...'` | Telephony Mercury mute-sync subscribe (`wxcc_sdk.user.webex_together_mercury_subscribe.complete\|fail`) |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `'WxApp Offer Participant Fields Missing'` | Read-only observability when usersub is active but inbound OFFERED participant **still** lacks valid wxApp fields after a **500 ms grace period** (orchestrated in `voice/wxAppOfferObservability.ts`; avoids false alarms from transient WS ordering). After usersub publish, `TaskManager.refreshWxAppOfferObservabilityForAllTasks()` re-runs the observer so a pre-publish OFFERED task can still schedule grace. Task removal calls `disposeWxAppOfferObservability()` so a pending timer cannot emit after `CONTACT_MERGED` / collection drop. Emitted with matching `[CC wxApp] participant fields mismatch` WARN (`wxcc_sdk.user.webex_together_offer_participant_fields.fail`) |
 | `TASK_CONFERENCE_START_SUCCESS` / `FAILED` | `'Task Conference Start ...'` | Conference start result |
 | `TASK_CONFERENCE_END_SUCCESS` / `FAILED` | `'Task Conference End ...'` | Conference end result |
 | `TASK_CONFERENCE_TRANSFER_SUCCESS` / `FAILED` | `'Task Conference Transfer ...'` | Conference transfer result |
@@ -301,6 +302,7 @@ All event names are defined in `constants.ts` as `METRIC_EVENT_NAMES`. Events fo
 | WxApp Session Init     | `WXAPP_SESSION_INIT_SUCCESS`           | `WXAPP_SESSION_INIT_FAILED`            |
 | WxApp Usersub Publish  | `WXAPP_USERSUB_PUBLISH_SUCCESS`        | `WXAPP_USERSUB_PUBLISH_FAILED`         |
 | WxApp Mercury Subscribe | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS`     | `WXAPP_MERCURY_SUBSCRIBE_FAILED`       |
+| WxApp Offer Participant Fields | —                              | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` |
 | Upload Logs            | `UPLOAD_LOGS_SUCCESS`                  | `UPLOAD_LOGS_FAILED`                   |
 | WebSocket Deregister   | `WEBSOCKET_DEREGISTER_SUCCESS`         | `WEBSOCKET_DEREGISTER_FAIL`            |
 | Device Type Update     | `AGENT_DEVICE_TYPE_UPDATE_SUCCESS`     | `AGENT_DEVICE_TYPE_UPDATE_FAILED`      |
@@ -322,9 +324,48 @@ Webex Together events (`WXAPP_*` constants) use `*_webex_together` compound targ
 | Usersub publish | `webex_together_usersub_publish` | `wxcc_sdk.user.webex_together_usersub_publish.complete` | `wxcc_sdk.user.webex_together_usersub_publish.fail` | — |
 | Mercury subscribe | `webex_together_mercury_subscribe` | `wxcc_sdk.user.webex_together_mercury_subscribe.complete` | `wxcc_sdk.user.webex_together_mercury_subscribe.fail` | — |
 | Session init | `webex_together_session_init` | `wxcc_sdk.user.webex_together_session_init.complete` | `wxcc_sdk.user.webex_together_session_init.fail` | `wxcc_sdk.user.webex_together_session_init.ignore` |
+| Offer participant fields | `webex_together_offer_participant_fields` | — | `wxcc_sdk.user.webex_together_offer_participant_fields.fail` | — |
 
 Operational and business wire names are unchanged (`WXCC_SDK_WXAPP_*`).
 
+### WxApp metric payload fields (operational / behavioral tags)
+
+| Event | Payload fields (booleans/enums; no raw IDs) |
+|---|---|
+| `WXAPP_SESSION_INIT_SUCCESS` | `loginOption`, `enableWxBetterTogether`, `usersubPublished`, `mercurySubscribed`, `telephonyTaskType` |
+| `WXAPP_SESSION_INIT_FAILED` | above + `skipReason` (`usersub_not_published`, `mercury_not_subscribed`, `mercury_subscribe_failed`, `publish_failed`) + optional `error`. `usersubPublished` reflects **retained session state** (`isAnswerCallsStateActive()` / `answerCallsState`), including on catch-path failures — not gated on the current init attempt's `publishedEnable`. |
+| `WXAPP_USERSUB_PUBLISH_SUCCESS` | `enableWxBetterTogether`, `usersubPublished` |
+| `WXAPP_USERSUB_PUBLISH_FAILED` | `enableWxBetterTogether`, `usersubPublished`, optional `skipReason`, `error`. `usersubPublished` reflects **retained session state** (`answerCallsState`), not the requested enable value — a failed disable/refresh while usersub remains active reports `true`. |
+| `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `mercurySubscribed: true` |
+| `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `mercurySubscribed: false`, `error` |
+| `WXAPP_TASK_ACCEPT_*` / `DECLINE_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`, optional `acceptReason`; failures add `trackingId` when available. `acceptReason` is captured **before** the telephony REST call (not hard-coded `wxApp_offer_ready`) so success and failure both retain `wxApp_answer_pending` / `wxApp_accept_in_flight` when those flags were already set. Outdial-cancel AQM failures (`error.details`) include the same participant context fields via `getWxAppTelephonyMetricContext` merged with AQM correlation fields. Outdial cancel during post-accept pending phase may report `acceptReason: wxApp_answer_pending`. |
+| `WXAPP_TASK_MUTE_*` / `DTMF_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`; failures add `trackingId` when available |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `taskId`, `usersubPublished`, `hasDeviceCallId`, `hasDeviceId`, `acceptReason` |
+
+### Customer console log triage (MMT / support)
+
+Customers often embed with `logger.level: 'log'`. wxApp diagnostics use **`LoggerProxy.log`** / **`warn`** / **`error`** with prefix **`[CC wxApp]`** and grep-friendly `key=value` suffixes on the message string (fields also appear in structured `data`).
+
+| Search in browser console | Meaning |
+|---|---|
+| `[CC wxApp]` | All wxApp diagnostic lines (primary search) |
+| `WXCC_SDK_WXAPP` | Operational metric wire names (name only in console; payloads go to backend) |
+| `session readiness` | usersub + Mercury state after station login |
+| `offer decision` | Why Accept is visible/enabled; includes `acceptReason`, `hasDeviceCallId`, `usersubPublished` |
+| `participant fields mismatch` | usersub active but WS participant **still** missing wxApp triple after ~500 ms (transient gaps on first OFFERED tick are normal — look for `wxApp_offer_ready` within 1 s) |
+| `telephony accept failed` | REST answer failure; includes `trackingId` when available |
+
+Do **not** search `WXAPP` alone — it matches metric wire names but misses `[CC wxApp]` diagnostic lines.
+
+Example lines at `logger.level: 'log'`:
+
+```text
+PLUGIN_CC - [LOG]: ... [CC wxApp] session readiness usersubPublished=true mercurySubscribed=true loginOption=EXTENSION ...
+PLUGIN_CC - [LOG]: ... [CC wxApp] offer decision acceptReason=wxApp_offer_ready hasDeviceCallId=true usersubPublished=true interactionId=...
+PLUGIN_CC - [WARN]: ... [CC wxApp] participant fields mismatch usersubPublished=true hasDeviceCallId=false acceptReason=extension_non_wxApp_offer interactionId=...
+PLUGIN_CC - [LOG]: ... operational-events -> @submitEvent. Submit event: WXCC_SDK_WXAPP_TASK_ACCEPT_SUCCESS
+```
+
 Special events (no success/failure pair):
 
 - `AGENT_RONA` — has behavioral taxonomy (`service.agent_rona.set`)
@@ -337,11 +378,11 @@ Special events (no success/failure pair):
 
 - `WXAPP_SESSION_SKIPPED` — has behavioral taxonomy (`wxcc_sdk.user.webex_together_session_init.ignore`)
 
-Of the 116 defined metric names, 96 have behavioral taxonomy and 20 do not. The Agent Wellness Break names are intentionally operational-only and therefore have no `eventTaxonomyMap` entries.
+Of the 113 defined metric names, 97 have behavioral taxonomy and 16 do not. Events **without** an `eventTaxonomyMap` entry are the original eight `AI_ASSISTANT_*` names, the three Agent Wellness Break `AI_ASSISTANT_WELLNESS_*` names, the two `WELLBEING_BREAK_IDLE_CODE_FETCH_*` names, plus `WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, and `WEBSOCKET_EVENT_RECEIVED`. The Agent Wellness Break names are intentionally operational-only and therefore have no `eventTaxonomyMap` entries.
 
 ### Complete METRIC_EVENT_NAMES catalog
 
-This table contains all 116 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 96 mapped and 20 unmapped.
+This table contains all 113 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 97 mapped and 16 unmapped.
 
 | Constant | Emitted name | Behavioral taxonomy? |
 |---|---|---|
@@ -415,6 +456,7 @@ This table contains all 116 names from `src/metrics/constants.ts`; taxonomy pres
 | `WXAPP_USERSUB_PUBLISH_FAILED` | `WxApp Usersub Publish Failed` | yes |
 | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `WxApp Mercury Subscribe Success` | yes |
 | `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `WxApp Mercury Subscribe Failed` | yes |
+| `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `WxApp Offer Participant Fields Missing` | yes |
 | `UPLOAD_LOGS_SUCCESS` | `Upload Logs Success` | yes |
 | `UPLOAD_LOGS_FAILED` | `Upload Logs Failed` | yes |
 | `WEBSOCKET_DEREGISTER_SUCCESS` | `Websocket Deregister Success` | no |

package/src/metrics/behavioral-events.ts

@@ -405,6 +405,12 @@ const eventTaxonomyMap: Record<string, BehavioralEventTaxonomy> = {
     target: 'webex_together_mercury_subscribe',
     verb: 'fail',
   },
+  [METRIC_EVENT_NAMES.WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING]: {
+    product,
+    agent: 'user',
+    target: 'webex_together_offer_participant_fields',
+    verb: 'fail',
+  },
 
   // Conference Tasks
   [METRIC_EVENT_NAMES.TASK_CONFERENCE_START_SUCCESS]: {

package/src/metrics/constants.ts

@@ -156,6 +156,7 @@ export const METRIC_EVENT_NAMES = {
   WXAPP_USERSUB_PUBLISH_FAILED: 'WxApp Usersub Publish Failed',
   WXAPP_MERCURY_SUBSCRIBE_SUCCESS: 'WxApp Mercury Subscribe Success',
   WXAPP_MERCURY_SUBSCRIBE_FAILED: 'WxApp Mercury Subscribe Failed',
+  WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING: 'WxApp Offer Participant Fields Missing',
 
   UPLOAD_LOGS_SUCCESS: 'Upload Logs Success',
   UPLOAD_LOGS_FAILED: 'Upload Logs Failed',

package/src/services/AnswerCallOnWebexService.ts

@@ -97,7 +97,7 @@ export default class AnswerCallOnWebexService {
     try {
       const uri = `${this.getTelephonyBaseUrl()}${resource}`;
 
-      LoggerProxy.info(`AnswerCallOnWebexService.${logMethod} request`, {
+      LoggerProxy.log(`AnswerCallOnWebexService.${logMethod} request`, {
         module: ANSWER_CALL_ON_WEBEX_FILE,
         method: logMethod,
         data: {uri, bodyKeys: Object.keys(body)},
@@ -110,7 +110,7 @@ export default class AnswerCallOnWebexService {
         addAuthHeader: true,
       })) as IHttpResponse;
 
-      LoggerProxy.info(`AnswerCallOnWebexService.${logMethod} success`, {
+      LoggerProxy.log(`AnswerCallOnWebexService.${logMethod} success`, {
         module: ANSWER_CALL_ON_WEBEX_FILE,
         method: logMethod,
         data: {statusCode: response.statusCode},
@@ -197,10 +197,10 @@ export default class AnswerCallOnWebexService {
     const uri = `${this.getTelephonyBaseUrl()}/${callId}${lineOwnerIdQuery}`;
 
     try {
-      LoggerProxy.info('AnswerCallOnWebexService.getCallDetails request', {
+      LoggerProxy.log('AnswerCallOnWebexService.getCallDetails request', {
         module: ANSWER_CALL_ON_WEBEX_FILE,
         method: METHODS.GET_CALL_DETAILS_ON_WEBEX,
-        data: {callId},
+        data: {callIdSuffix: callId.length <= 8 ? callId : callId.slice(-8)},
       });
 
       const response = (await this.webex.request({

package/src/services/WebexCrossClientService.ts

@@ -213,6 +213,7 @@ export default class WebexCrossClientService {
             METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
             {
               enableWxBetterTogether: enable,
+              usersubPublished: this.answerCallsState,
               error: error instanceof Error ? error.toString() : String(error),
             },
             ['operational', 'behavioral']
@@ -243,12 +244,15 @@ export default class WebexCrossClientService {
     if (trackPublishMetrics) {
       metricsManager.trackEvent(
         METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS,
-        {enableWxBetterTogether: enable},
+        {
+          enableWxBetterTogether: enable,
+          usersubPublished: enable,
+        },
         ['operational', 'behavioral']
       );
     }
 
-    LoggerProxy.info(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
+    LoggerProxy.log(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
       module: WEBEX_CROSS_CLIENT_FILE,
       method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
       data: {
@@ -273,6 +277,7 @@ export default class WebexCrossClientService {
       METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
       {
         enableWxBetterTogether: enable,
+        usersubPublished: this.answerCallsState,
         skipReason,
         error,
       },

package/src/services/WxAppTelephonyMercurySync.ts

@@ -88,7 +88,7 @@ export default class WxAppTelephonyMercurySync {
 
       MetricsManager.getInstance().trackEvent(
         METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED,
-        {error: 'Mercury is unavailable for wxApp mute sync'},
+        {error: 'Mercury is unavailable for wxApp mute sync', mercurySubscribed: false},
         ['operational', 'behavioral']
       );
 
@@ -110,11 +110,11 @@ export default class WxAppTelephonyMercurySync {
 
     MetricsManager.getInstance().trackEvent(
       METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_SUCCESS,
-      {},
+      {mercurySubscribed: true},
       ['operational', 'behavioral']
     );
 
-    LoggerProxy.info('Subscribed to wxApp telephony Mercury mute sync', {
+    LoggerProxy.log('Subscribed to wxApp telephony Mercury mute sync', {
       module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
       method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
     });

package/src/services/config/types.ts

@@ -1240,6 +1240,8 @@ export type Profile = {
   maskSensitiveData?: boolean;
   /** Whether agent is currently logged in */
   isAgentLoggedIn?: boolean;
+  /** Active station session after a successful registered relogin. */
+  agentSessionId?: string;
   /** Last auxiliary code ID used for state change */
   lastStateAuxCodeId?: string;
   /** Timestamp of last state change */

package/src/services/task/TaskFactory.ts

@@ -31,6 +31,7 @@ export default class TaskFactory {
       isRecordingEnabled: recordingEnabled,
       enableWxBetterTogether: configFlags.enableWxBetterTogether ?? false,
       answerCallOnWebexService,
+      getUsersubPublished: configFlags.getWxAppUsersubPublished,
       consultTransferConfig: consultTransfer,
     };
     switch (mediaType) {

package/src/services/task/TaskManager.ts

@@ -778,6 +778,7 @@ export default class TaskManager extends EventEmitter {
     const interactionId = message.data.interactionId;
     const reservationInteractionId = message.data.reservationInteractionId;
     let task = this.taskCollection[interactionId];
+    let ownerChangeResolvedByRelatedInteraction = false;
 
     // When a campaign preview contact is accepted, the assigned event may arrive
     // with a new interactionId while the task is stored under the original
@@ -792,7 +793,66 @@ export default class TaskManager extends EventEmitter {
     }
 
     if (!task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
-      task = this.findTaskForContactOwnerChange(message.data);
+      const incomingShowsCurrentAgentPromotion = Boolean(
+        this.agentId &&
+          message.data.interaction?.owner === this.agentId &&
+          TaskManager.isParticipantActiveOnMainInteraction(message.data, this.agentId)
+      );
+
+      task = this.findUniqueTaskByRelatedInteraction(
+        message.data,
+        (candidate) => {
+          const currentAgentId = this.agentId || candidate.data?.agentId;
+
+          return Boolean(
+            currentAgentId &&
+              (TaskManager.isParticipantActiveOnMainInteraction(candidate.data, currentAgentId) ||
+                incomingShowsCurrentAgentPromotion)
+          );
+        },
+        {includeCollectionKeys: true, includeMainCallMediaKeys: true}
+      );
+      ownerChangeResolvedByRelatedInteraction = Boolean(task);
+    }
+
+    let ownerChangeMainInteractionId: string | undefined;
+    if (task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      const taskMainInteractionId = task.data?.interaction?.mainInteractionId;
+      const payloadMainInteractionId = message.data.interaction?.mainInteractionId;
+      const hasConflictingMainInteractionIds = Boolean(
+        taskMainInteractionId &&
+          payloadMainInteractionId &&
+          taskMainInteractionId !== payloadMainInteractionId
+      );
+      // A promoted child task can retain stale embedded IDs. Prefer the
+      // authoritative incoming main-call identity before local snapshot IDs.
+      const stableMainInteractionId =
+        payloadMainInteractionId ||
+        TaskManager.getMainCallMediaId(message.data.interaction) ||
+        TaskManager.getMainCallMediaId(task.data?.interaction) ||
+        taskMainInteractionId ||
+        message.data.interaction?.interactionId ||
+        task.data?.interaction?.interactionId ||
+        task.data?.interactionId;
+      const taskAtStableKey = stableMainInteractionId
+        ? this.taskCollection[stableMainInteractionId]
+        : undefined;
+
+      if (
+        !stableMainInteractionId ||
+        hasConflictingMainInteractionIds ||
+        (taskAtStableKey && taskAtStableKey !== task)
+      ) {
+        LoggerProxy.warn('Unable to safely correlate owner change to the main interaction task', {
+          module: TASK_MANAGER_FILE,
+          method: 'prepareEventContext',
+          interactionId:
+            payloadMainInteractionId || taskMainInteractionId || message.data.interactionId,
+        });
+        task = undefined;
+      } else if (ownerChangeResolvedByRelatedInteraction) {
+        ownerChangeMainInteractionId = stableMainInteractionId;
+      }
     }
 
     if (!task && MAIN_INTERACTION_CORRELATED_EVENTS.has(eventType)) {
@@ -821,8 +881,11 @@ export default class TaskManager extends EventEmitter {
           }
         : message.data;
 
-    if (task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
-      adjustedPayload = TaskManager.preserveMainTaskIdentity(task, adjustedPayload);
+    if (task && ownerChangeMainInteractionId) {
+      adjustedPayload = {
+        ...adjustedPayload,
+        interactionId: ownerChangeMainInteractionId,
+      };
     }
 
     if (task && eventType === CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE) {
@@ -860,53 +923,6 @@ export default class TaskManager extends EventEmitter {
     };
   }
 
-  /**
-   * ContactOwnerChanged can identify the promoted agent's child interaction while
-   * the surviving task is stored under the main interaction. Accept one related
-   * task when its existing snapshot or the authoritative incoming promotion proves
-   * current-agent main-call membership, while excluding non-promoted and ambiguous matches.
-   */
-  private findTaskForContactOwnerChange(payload: WebSocketPayload): ITask | undefined {
-    const relatedCandidates = this.findRelatedTasks(payload, {
-      includeCollectionKeys: true,
-      includeMainCallMediaKeys: true,
-    });
-    const incomingShowsCurrentAgentPromotion =
-      this.isCurrentAgentPromotedOnIncomingMainCall(payload);
-    const eligibleCandidates = relatedCandidates.filter(
-      (candidate) =>
-        this.isCurrentAgentActiveOnMainInteraction(candidate.data) ||
-        incomingShowsCurrentAgentPromotion
-    );
-
-    if (eligibleCandidates.length === 1) {
-      return eligibleCandidates[0];
-    }
-
-    if (eligibleCandidates.length > 1) {
-      LoggerProxy.warn('Unable to correlate task event to a unique main interaction task', {
-        module: TASK_MANAGER_FILE,
-        method: 'findTaskForContactOwnerChange',
-        interactionId:
-          payload.interaction?.mainInteractionId ||
-          payload.interaction?.parentInteractionId ||
-          payload.interaction?.callProcessingDetails?.parentInteractionId ||
-          payload.interactionId,
-      });
-
-      return undefined;
-    }
-
-    return undefined;
-  }
-
-  private isCurrentAgentActiveOnMainInteraction(taskData: TaskData | undefined): boolean {
-    const currentAgentId = this.agentId || taskData?.agentId;
-    if (!currentAgentId) return false;
-
-    return TaskManager.isParticipantActiveOnMainInteraction(taskData, currentAgentId);
-  }
-
   private static isParticipantActiveOnMainInteraction(
     taskData: TaskData | WebSocketPayload | undefined,
     participantId: string
@@ -921,14 +937,6 @@ export default class TaskManager extends EventEmitter {
     );
   }
 
-  private isCurrentAgentPromotedOnIncomingMainCall(payload: WebSocketPayload): boolean {
-    return Boolean(
-      this.agentId &&
-        payload.interaction?.owner === this.agentId &&
-        TaskManager.isParticipantActiveOnMainInteraction(payload, this.agentId)
-    );
-  }
-
   private static getMainCallMediaId(
     interaction: TaskData['interaction'] | undefined
   ): string | undefined {
@@ -960,31 +968,6 @@ export default class TaskManager extends EventEmitter {
     );
   }
 
-  /** Keep a related owner-change event from re-keying the surviving main task to a child ID. */
-  private static preserveMainTaskIdentity(
-    task: ITask,
-    payload: WebSocketPayload
-  ): WebSocketPayload {
-    const currentMainInteractionId = task.data?.interaction?.mainInteractionId;
-    const payloadMainInteractionId = payload.interaction?.mainInteractionId;
-    const currentMainMediaId = TaskManager.getMainCallMediaId(task.data?.interaction);
-    const payloadMainMediaId = TaskManager.getMainCallMediaId(payload.interaction);
-    const stableInteractionId =
-      currentMainInteractionId ||
-      payloadMainInteractionId ||
-      currentMainMediaId ||
-      payloadMainMediaId ||
-      payload.interaction?.interactionId ||
-      task.data?.interaction?.interactionId ||
-      task.data?.interactionId;
-
-    if (!stableInteractionId || stableInteractionId === payload.interactionId) {
-      return payload;
-    }
-
-    return {...payload, interactionId: stableInteractionId};
-  }
-
   /**
    * ParticipantLeftConference may arrive after an owner update while still carrying
    * the departed owner. Keep the confirmed owner only when the new roster proves that
@@ -1024,9 +1007,10 @@ export default class TaskManager extends EventEmitter {
    */
   private findUniqueTaskByRelatedInteraction(
     payload: WebSocketPayload,
-    candidateFilter: (task: ITask) => boolean = () => true
+    candidateFilter: (task: ITask) => boolean = () => true,
+    options: {includeCollectionKeys?: boolean; includeMainCallMediaKeys?: boolean} = {}
   ): ITask | undefined {
-    const candidates = this.findRelatedTasks(payload).filter(candidateFilter);
+    const candidates = this.findRelatedTasks(payload, options).filter(candidateFilter);
 
     if (candidates.length === 1) {
       return candidates[0];
@@ -1060,7 +1044,9 @@ export default class TaskManager extends EventEmitter {
         payload.interaction?.parentInteractionId,
         payload.interaction?.callProcessingDetails?.parentInteractionId,
         ...(includeMainCallMediaKeys ? [TaskManager.getMainCallMediaId(payload.interaction)] : []),
-      ].filter((interactionId): interactionId is string => Boolean(interactionId))
+      ].filter((relatedInteractionId): relatedInteractionId is string =>
+        Boolean(relatedInteractionId)
+      )
     );
     if (payloadInteractionIds.size === 0) return [];
 
@@ -1082,7 +1068,8 @@ export default class TaskManager extends EventEmitter {
             ];
 
             return candidateInteractionIds.some(
-              (interactionId) => Boolean(interactionId) && payloadInteractionIds.has(interactionId)
+              (relatedInteractionId) =>
+                Boolean(relatedInteractionId) && payloadInteractionIds.has(relatedInteractionId)
             );
           })
           .map(([, candidate]) => candidate)
@@ -1457,6 +1444,7 @@ export default class TaskManager extends EventEmitter {
   }
 
   private removeTaskFromCollection(task: ITask) {
+    task.disposeWxAppOfferObservability?.();
     if (typeof task.cancelAutoWrapupTimer === 'function') {
       task.cancelAutoWrapupTimer();
     }
@@ -1655,6 +1643,16 @@ export default class TaskManager extends EventEmitter {
     });
   }
 
+  /**
+   * Re-run OFFERED wxApp offer diagnostics for collected voice tasks.
+   * Used after usersub publish so pre-publish offers can schedule mismatch grace.
+   */
+  public refreshWxAppOfferObservabilityForAllTasks(): void {
+    Object.values(this.taskCollection).forEach((task) => {
+      task.refreshWxAppOfferObservability?.();
+    });
+  }
+
   public static getTaskManager(
     apiAIAssistant: ApiAIAssistant,
     contact: ReturnType<typeof routingContact>,

package/src/services/task/ai-docs/task-spec.md

@@ -618,6 +618,8 @@ This keeps transcript and suggestion delivery aligned on the same per-task event
 
 **wxApp consumer contract (WXCC-6026):** Hosts enable `enableWxBetterTogether` at init (Phase 1 init-only; re-init to change), bind UI to `task.uiControls` (including optional `main.keypad`), and call **`task.accept()`**, **`task.decline()`**, **`task.toggleMute({ muted? })`**, **`task.transmitDtmf({ dtmf })`**. SDK routes wxApp telephony internally on `Voice`. Shared-line `lineOwnerId` defaults from the wxApp agent participant when omitted.
 
+**wxApp OFFERED diagnostics:** `Voice.updateUiControls` delegates offer-decision logging and deferred participant-mismatch WARN/metric to `voice/wxAppOfferObservability.ts` (500 ms grace; observability only). After usersub publish, `TaskManager.refreshWxAppOfferObservabilityForAllTasks()` re-invokes the observer without emitting UI controls. `removeTaskFromCollection` calls `disposeWxAppOfferObservability()` so a pending grace timer cannot emit after the task is dropped (including `CONTACT_MERGED` child removal). Dispose is terminal: the observer sets a disposed guard (timer cancel plus no-op `handleUiControlsUpdate`) so a later `updateUiControls` / refresh cannot schedule a new grace timer.
+
 **wxApp offer UI (`uiControlsComputer`):** `wxAppAcceptInFlight` disables accept/decline during the accept REST call. `wxAppAnswerPending` additionally disables accept and decline for **inbound** offers until ASSIGN; wxApp **outdial** keeps decline enabled during the post-accept "Calling…" phase so `cancelTask` remains available.
 
 **wxApp decline observability:** Inbound wxApp offers decline via telephony `rejectCall` (`runWxAppReject` → `WXAPP_TASK_DECLINE_*`). wxApp outdial cancellations use CC routing `cancelTask` (`runWxAppOutdialDecline` → additive `WXAPP_TASK_DECLINE_*` plus existing `TASK_DECLINE_*`).
@@ -924,15 +926,17 @@ guards. The state-machine transition table lives in
 Primary-Agent promotion remains backend-authoritative and follows the two-event
 desktop contract. `ContactOwnerChanged` updates the promoted Agent; TaskManager
 prefers an exact task, then one unique related task resolved through nested
-main/parent identifiers or the `mainCall` media-map identity. A related
-candidate is eligible when its current
+main/parent identifiers, the task collection key, or the `mainCall` media-map
+identity. A related candidate is eligible when its current
 snapshot contains the current Agent's participant entry with `hasLeft !== true`
 and membership on the `mType: mainCall` leg. The incoming snapshot can provide
 that evidence only when it also names the current Agent as `interaction.owner`;
 this permits an authoritative promotion payload to repair a stale child-keyed
 snapshot while still excluding consult-only tasks. The update keeps the
 surviving main interaction identity even when the notification names a
-promoted-Agent child interaction.
+promoted-Agent child interaction. Conflicting main identifiers, ambiguous
+matches, and a canonical key occupied by a distinct task are ignored rather
+than replacing an existing task.
 
 If no related task exists, TaskManager recovers only the promoted current Agent
 from a non-terminal telephony `ContactOwnerChanged` payload that provides the same

package/src/services/task/types.ts

@@ -1759,6 +1759,20 @@ export interface ITask extends IEventEmitter {
    */
   syncWxAppMuteFromCallDetails?(): Promise<boolean | undefined>;
 
+  /**
+   * Re-run OFFERED wxApp offer diagnostics without emitting UI controls.
+   * Voice tasks implement this; other channel types omit it.
+   * @internal
+   */
+  refreshWxAppOfferObservability?(): void;
+
+  /**
+   * Cancel pending wxApp offer observability timers (participant-mismatch grace).
+   * Voice tasks implement this; other channel types omit it.
+   * @internal
+   */
+  disposeWxAppOfferObservability?(): void;
+
   /**
    * State machine instance for managing task state transitions and derived properties.
    * The state machine handles:
@@ -2070,6 +2084,8 @@ export type VoiceUIControlOptions = {
   enableWxBetterTogether?: boolean;
   consultTransferConfig?: ConsultTransferDestinationConfig;
   answerCallOnWebexService?: import('../AnswerCallOnWebexService').default;
+  /** Read-only observability: whether usersub answer-calls-on-wxcc is active this session. */
+  getUsersubPublished?: () => boolean;
 };
 
 /**