@webex/contact-center 3.12.0-llmrefactor.12 → 3.12.0-llmrefactor.14

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

@@ -11,8 +11,8 @@
 | Doc kind | Module spec |
 | Coverage score | Partial (manifest-authoritative); 15/15 required document fields present |
 | Generated from | `module-spec` @ SDLC template library `0.2.1` |
-| generated_by / approved_by / updated_at | Codex generator / developer-approved follow-up review remediation / 2026-07-21 |
-| Validation status | Follow-up validation passed (independent Claude fallback, 2026-07-21); coverage remains Partial |
+| generated_by / approved_by / updated_at | Codex generator / developer-approved Agent Wellness Break delta / 2026-09-02 |
+| Validation status | Agent Wellness Break v0.4 delta independently validated by claude-code on 2026-09-07; coverage remains Partial until the remaining baseline promotion criteria are satisfied |
 
 ## Evidence Rules
 Every requirement cites stable source and test file paths. Code/tests are the behavioral referee; routed source text supplies explicit intent and rationale. Missing or contradictory evidence blocks promotion.
@@ -100,6 +100,8 @@ services/config/
 | Organization masking | `OrgSettings.maskSensitiveData` | `src/services/config/types.ts`, `src/services/config/Util.ts` |
 | Auxiliary-code list URL | includes `desktopProfileFilter=true` | `src/services/config/constants.ts` |
 | Outdial ANI entries | public wrapper through ContactCenter | `src/services/config/index.ts`, `src/cc.ts` |
+| `Profile.isWellnessBreakEnabled` | required effective flag derived from backend AI feature configuration and organization license quantity | `src/services/config/Util.ts`, `src/services/config/types.ts` |
+| `getWellbeingBreakIdleCode(orgId)` | paginated exact lookup for the active system idle code named `WellbeingBreak`, exposed and registration-cached by ContactCenter | `src/services/config/index.ts`, `src/services/config/constants.ts`, `src/cc.ts` |
 
 The service has no `TeamList.channelMap` contract. Exact package exports are indexed in root `CONTRACTS.md`.
 
@@ -116,6 +118,8 @@ The service has no `TeamList.channelMap` contract. Exact package exports are ind
 | CONFIG-R-003 | Paginate teams and auxiliary codes until completion and include `desktopProfileFilter=true` for auxiliary-code requests. | A partial or unfiltered set yields invalid profile/team/auxiliary choices. | `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | CONFIG-R-004 | Expose current response/field names: `MultimediaProfileResponse`, `OrgSettings.maskSensitiveData`, and real TeamList fields only. | Type-name drift causes invalid consumer code and incorrect privacy behavior. | `src/services/config/types.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
 | CONFIG-R-005 | Reject the entire profile aggregation when any required dependent request fails. | Consumers must never receive an internally inconsistent partial Profile. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
+| CONFIG-R-006 | Always populate `Profile.isWellnessBreakEnabled`; set it true only when `agentWellbeing.enable` is true, `wellnessBreakReminders` is `ENABLED`, and `OrgSettings.aiAssistantQuantity` is greater than zero. Missing or null inputs fail closed. | Hosts need one license-and-server-rollout-aware signal rather than reconstructing partial configuration. | `src/services/config/Util.ts`, `src/services/config/types.ts` | `test/unit/spec/services/config/Util.ts` | The supported SDK contracts expose no separate rollout response field; backend delivery of enabled `agentWellbeing` configuration is the rollout decision. | PRESENT |
+| CONFIG-R-007 | Retrieve the wellness idle code from `/v2/auxiliary-code` using `workType=IDLE_CODE`, `customFilter=isSystemCode==true`, and `desktopProfileFilter=false`; follow pagination and accept only the exact active system code name `WellbeingBreak`. | The dedicated state must be independent of desktop-profile filtering and must never fall back to a similarly named or non-system code. | `src/services/config/index.ts`, `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
 
 ## Design Overview
 Config separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Profile creation is all-or-nothing across dependent API calls so consumers never receive internally inconsistent partial configuration.
@@ -162,6 +166,7 @@ The AgentProfile is defined as the [`Profile`](../types.ts) type. This is not an
 | `accessQueue` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab queue access scope from Desktop Profile |
 | `accessEntryPoint` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab entry-point access scope from Desktop Profile |
 | `accessBuddyTeam` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab buddy-team access scope from Desktop Profile |
+| `isWellnessBreakEnabled` | boolean | Effective wellness gate derived from backend enablement/reminder configuration and positive AI Assistant license quantity |
 
 `parseAgentConfigs()` maps the three `access*` fields from `DesktopProfileResponse` onto the public `Profile` returned by `cc.register()`.
 
@@ -264,7 +269,7 @@ The service fetches data from multiple APIs with these response structures:
 | `getTenantData` | `TenantData` | `outdialEnabled`, `forceDefaultDn`, `privacyShieldVisible`, `timeoutDesktopInactivityEnabled` | Tenant-level feature flags |
 | `getOrgInfo` | `OrgInfo` | `tenantId`, `timezone` | Organization metadata |
 | `getAllAuxCodes` | `AuxCode[]` | `id`, `name`, `workTypeCode`, `active`, `isSystemCode`, `defaultCode` | Auxiliary codes for idle/wrap-up states |
-| `getOrganizationSetting` | `OrgSettings` | `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled` | Organization-level feature flags |
+| `getOrganizationSetting` | `OrgSettings` | `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled`, `aiAssistantQuantity` | Organization-level feature flags and AI Assistant license quantity |
 | `getDialPlanData` | `DialPlanEntity[]` | `id`, `name`, `regularExpression`, `prefix`, `strippedChars` | Dial plan rules for outbound calling |
 | `getURLMapping` | `URLMapping[]` | `name`, `url` | External service URL mappings |
 | `getSiteInfo` | `SiteInfo` | Site-specific configuration | Site details |
@@ -449,11 +454,14 @@ classDiagram
 - **UC-2 Paginated teams/aux codes:** follow backend page metadata to completion; auxiliary-code requests include `desktopProfileFilter=true`. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
 - **UC-3 Dial plan and URL mapping:** request dial-plan data only when the desktop profile enables it while always including URL mapping in profile aggregation. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
 - **UC-4 Outdial ANI retrieval:** return the organization-scoped ANI list through authenticated WebexRequest and propagate failures without a partial substitute. Evidence: `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts`.
+- **UC-5 Wellness configuration:** produce one fail-closed effective profile flag and retrieve the exact system wellness idle code across pages. Evidence: `src/services/config/Util.ts`, `src/services/config/index.ts`, `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts`.
 
 ## Business Rules & Invariants
 - `getAgentConfig` rejects when any required dependent request rejects; it never returns a partial Profile.
 - `Profile.aiFeature` is derived from the AI-feature response, and sensitive-data masking uses the real `maskSensitiveData` field.
 - Team data has no `channelMap` contract; multimedia profile responses use `MultimediaProfileResponse`.
+- `isWellnessBreakEnabled` is always boolean and defaults false when any gate is absent, disabled, or unlicensed.
+- The system wellness code lookup is separate from profile auxiliary-code aggregation and uses `desktopProfileFilter=false`.
 
 ## Concurrency & Reactive Flow
 - The initial user lookup supplies identifiers for a ten-promise `Promise.all`; pagination loops await pages in order and stop from returned metadata.
@@ -465,6 +473,7 @@ All Config operations are authenticated REST calls through WebexRequest. Importa
 |---|---|
 | AI feature flags | `organization/{orgId}/v2/ai-feature?page=0&pageSize=100` |
 | Auxiliary codes | pagination/filter/attributes plus `desktopProfileFilter=true` |
+| Wellness system idle code | `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false` |
 | Multimedia profile | organization-scoped multimedia-profile resource |
 | Dial plan | organization-scoped dial-plan resource when desktop profile enables it |
 
@@ -653,6 +662,8 @@ public async getUserUsingCI(orgId: string, agentId: string): Promise<AgentRespon
 | `CONFIG-R-003` | `test/unit/spec/services/config/index.ts` | None. |
 | `CONFIG-R-004` | `test/unit/spec/services/config/index.ts` | None. |
 | `CONFIG-R-005` | `test/unit/spec/services/config/index.ts` | Keep an explicit rejection assertion for each required dependency category. |
+| `CONFIG-R-006` | `test/unit/spec/services/config/Util.ts` | None. |
+| `CONFIG-R-007` | `test/unit/spec/services/config/index.ts` | None. |
 
 ## Traceability
 - Repo architecture: `../../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../../ai-docs/SPEC_INDEX.md`

package/src/services/config/constants.ts

@@ -34,6 +34,12 @@ export const AGENT_STATE_AVAILABLE_ID = '0';
  */
 export const AGENT_STATE_AVAILABLE = 'Available';
 
+/** System idle-code name reserved for Agent Wellness Break. */
+export const WELLBEING_BREAK_IDLE_CODE = 'WellbeingBreak';
+
+/** Backend sentinel indicating wellness-break reminders are enabled. @internal */
+export const WELLNESS_BREAK_REMINDERS_ENABLED = 'ENABLED';
+
 /**
  * Description for the 'Available' agent state.
  * @type {string}
@@ -75,6 +81,7 @@ export const METHODS = {
   GET_URL_MAPPING: 'getURLMapping',
   GET_DIAL_PLAN_DATA: 'getDialPlanData',
   GET_AI_FEATURE_FLAGS: 'getAIFeatureFlags',
+  GET_WELLBEING_BREAK_IDLE_CODE: 'getWellbeingBreakIdleCode',
   GET_QUEUES: 'getQueues',
 
   // Util methods
@@ -175,6 +182,11 @@ export const endPointMap = {
       filter && filter.length > 0 ? `&filter=id=in=(${filter})` : ''
     }&attributes=${attributes}&desktopProfileFilter=true`,
 
+  /** Lists system idle codes without applying the agent Desktop Profile filter. */
+  systemIdleCodes: (orgId: string, page: number, pageSize: number) =>
+    `organization/${orgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}` +
+    '&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false',
+
   /**
    * Gets the endpoint for organization info.
    * @param orgId - Organization ID.

package/src/services/config/index.ts

@@ -23,6 +23,7 @@ import {
   OutdialAniEntriesResponse,
   OutdialAniParams,
   AIFeatureFlagsResponse,
+  Entity,
 } from './types';
 import WebexRequest from '../core/WebexRequest';
 import {WCC_API_GATEWAY} from '../constants';
@@ -34,6 +35,7 @@ import {
   DEFAULT_PAGE_SIZE,
   endPointMap,
   METHODS,
+  WELLBEING_BREAK_IDLE_CODE,
 } from './constants';
 
 /**
@@ -470,6 +472,69 @@ export default class AgentConfigService {
     }
   }
 
+  /**
+   * Retrieves the exact system-managed WellbeingBreak idle code.
+   * This query intentionally bypasses Desktop Profile filtering so the system code does not
+   * need to appear in the normal agent-selectable idle-code list.
+   * @param orgId - Organization identifier
+   * @returns The normalized WellbeingBreak entity
+   * @throws When the request fails or the exact system code is unavailable
+   * @internal
+   */
+  public async getWellbeingBreakIdleCode(orgId: string): Promise<Entity> {
+    LoggerProxy.info('Fetching WellbeingBreak system idle code', {
+      module: CONFIG_FILE_NAME,
+      method: METHODS.GET_WELLBEING_BREAK_IDLE_CODE,
+    });
+
+    try {
+      let page = DEFAULT_PAGE;
+      let totalPages = 1;
+
+      do {
+        // Pagination is intentionally sequential so the lookup can stop as soon as the code is found.
+        // eslint-disable-next-line no-await-in-loop
+        const response = await this.webexReq.request({
+          service: WCC_API_GATEWAY,
+          resource: endPointMap.systemIdleCodes(orgId, page, DEFAULT_PAGE_SIZE),
+          method: HTTP_METHODS.GET,
+        });
+
+        if (response.statusCode !== 200) {
+          throw new Error(`API call failed with ${response.statusCode}`);
+        }
+
+        const result = response.body as ListAuxCodesResponse;
+        const wellbeingCode = result.data?.find(
+          (code) =>
+            code.active === true &&
+            code.isSystemCode === true &&
+            code.name === WELLBEING_BREAK_IDLE_CODE
+        );
+
+        if (wellbeingCode) {
+          return {
+            id: wellbeingCode.id,
+            name: wellbeingCode.name,
+            isSystem: true,
+            isDefault: wellbeingCode.defaultCode,
+          };
+        }
+
+        totalPages = result.meta?.totalPages ?? 1;
+        page += 1;
+      } while (page < totalPages);
+
+      throw new Error('WELLBEING_BREAK_IDLE_CODE_NOT_FOUND');
+    } catch (error) {
+      LoggerProxy.error(`getWellbeingBreakIdleCode API call failed with ${error}`, {
+        module: CONFIG_FILE_NAME,
+        method: METHODS.GET_WELLBEING_BREAK_IDLE_CODE,
+      });
+      throw error;
+    }
+  }
+
   /**
    * Fetches the site data for the given orgId and siteId.
    * @ignore

package/src/services/config/types.ts

@@ -150,8 +150,7 @@ export const CC_TASK_EVENTS = {
 /**
  * Events emitted on Contact Center agent operations
  * @enum {string}
- * @private
- * @ignore
+ * @public
  */
 export const CC_AGENT_EVENTS = {
   /** Welcome event when agent connects to websocket/backend */
@@ -190,6 +189,8 @@ export const CC_AGENT_EVENTS = {
   AGENT_BUDDY_AGENTS_RETRIEVE_FAILED: 'BuddyAgentsRetrieveFailed',
   /** Event emitted when contact is reserved for agent */
   AGENT_CONTACT_RESERVED: 'AgentContactReserved',
+  /** Agent-level Agent Wellness Break notification */
+  WELLNESS_BREAK: 'WellnessBreak',
 } as const;
 
 /**
@@ -729,6 +730,8 @@ export type OrgSettings = {
   maskSensitiveData: boolean;
   /** Whether campaign manager features are enabled */
   campaignManagerEnabled: boolean;
+  /** Number of AI Assistant licenses assigned to the organization */
+  aiAssistantQuantity?: number | null;
 };
 
 /**
@@ -1237,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 */
@@ -1245,6 +1250,12 @@ export type Profile = {
   lastIdleCodeChangeTimestamp?: number;
   /** AI feature flags resolved from organization config */
   aiFeature?: AIFeatureFlags;
+  /**
+   * Whether Agent Wellness Break is effectively enabled for this profile.
+   * This combines the organization wellbeing configuration with AI Assistant licensing;
+   * Server-side rollout remains enforced by the backend configuration and notification delivery.
+   */
+  isWellnessBreakEnabled?: boolean;
 };
 
 /**

package/src/services/core/Utils.ts

@@ -16,6 +16,10 @@ import {
 import {PARTICIPANT_TYPES, STATE_CONSULT} from './constants';
 import {DialPlan} from '../config/types';
 
+/** Returns whether a value is a non-null object with string keys. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
 /**
  * Extracts common error details from a Webex request payload.
  *

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;
 };
 
 /**