@webex/contact-center 3.12.0-llmrefactor.3 → 3.12.0-llmrefactor.4

package/src/services/task/TaskManager.ts

@@ -31,6 +31,7 @@ import AnswerCallOnWebexService from '../AnswerCallOnWebexService';
 import {getWebexCallingDeviceDetailsForAgent} from './WebexCallingUtils';
 import WebRTC from './voice/WebRTC';
 import {TaskEvent, type TaskEventPayload} from './state-machine';
+import {MEDIA_TYPE_MAIN_CALL} from './state-machine/constants';
 import {normalizeTaskData} from './taskDataNormalizer';
 import {ApiAIAssistant} from '../ApiAiAssistant';
 
@@ -241,6 +242,15 @@ export default class TaskManager extends EventEmitter {
         return {type: TaskEvent.HYDRATE, taskData: payload, agentId};
 
       case CC_EVENTS.CONTACT_UPDATED:
+        if (
+          task &&
+          typeof payload.interaction?.owner === 'string' &&
+          payload.interaction.owner.trim().length > 0 &&
+          payload.interaction.owner !== task.data?.interaction?.owner
+        ) {
+          return {type: TaskEvent.CONTACT_OWNER_CHANGED, taskData: payload};
+        }
+
         return {type: TaskEvent.CONTACT_UPDATED, taskData: payload};
       case CC_EVENTS.CONTACT_OWNER_CHANGED:
         return {type: TaskEvent.CONTACT_OWNER_CHANGED, taskData: payload};
@@ -597,6 +607,10 @@ export default class TaskManager extends EventEmitter {
       }
     }
 
+    if (!task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      task = this.findTaskForContactOwnerChange(message.data);
+    }
+
     if (!task && MAIN_INTERACTION_CORRELATED_EVENTS.has(eventType)) {
       task = this.findUniqueTaskByRelatedInteraction(message.data);
     }
@@ -613,7 +627,7 @@ export default class TaskManager extends EventEmitter {
       return !wasConsultedTask;
     };
 
-    const adjustedPayload =
+    let adjustedPayload: WebSocketPayload =
       eventType === CC_EVENTS.AGENT_CONSULT_TRANSFERRED ||
       eventType === CC_EVENTS.AGENT_BLIND_TRANSFERRED ||
       eventType === CC_EVENTS.AGENT_VTEAM_TRANSFERRED
@@ -623,6 +637,14 @@ export default class TaskManager extends EventEmitter {
           }
         : message.data;
 
+    if (task && eventType === CC_EVENTS.CONTACT_OWNER_CHANGED) {
+      adjustedPayload = TaskManager.preserveMainTaskIdentity(task, adjustedPayload);
+    }
+
+    if (task && eventType === CC_EVENTS.PARTICIPANT_LEFT_CONFERENCE) {
+      adjustedPayload = TaskManager.preserveConfirmedOwner(task, adjustedPayload);
+    }
+
     const stateMachineEvent = TaskManager.mapEventToTaskStateMachineEvent(
       eventType,
       adjustedPayload,
@@ -645,42 +667,173 @@ 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
+  ): boolean {
+    const interaction = taskData?.interaction;
+    const participant = interaction?.participants?.[participantId];
+    if (!participant || participant.hasLeft === true) return false;
+
+    return Object.values(interaction?.media ?? {}).some(
+      (media) =>
+        media?.mType === MEDIA_TYPE_MAIN_CALL && media.participants?.includes(participantId)
+    );
+  }
+
+  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 {
+    return Object.entries(interaction?.media ?? {}).find(
+      ([, media]) => media?.mType === MEDIA_TYPE_MAIN_CALL
+    )?.[0];
+  }
+
+  private static getStableMainInteractionId(payload: WebSocketPayload): string | undefined {
+    return (
+      payload.interaction?.mainInteractionId ||
+      TaskManager.getMainCallMediaId(payload.interaction) ||
+      payload.interaction?.interactionId ||
+      payload.interactionId
+    );
+  }
+
+  private canRecoverTaskFromContactOwnerChanged(payload: WebSocketPayload): boolean {
+    const interaction = payload.interaction;
+    const stableInteractionId = TaskManager.getStableMainInteractionId(payload);
+
+    return Boolean(
+      this.agentId &&
+        stableInteractionId &&
+        interaction?.mediaType === MEDIA_CHANNEL.TELEPHONY &&
+        interaction.isTerminated !== true &&
+        interaction.owner === this.agentId &&
+        TaskManager.isParticipantActiveOnMainInteraction(payload, this.agentId)
+    );
+  }
+
+  /** 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
+   * owner is active on mainCall and identifies the incoming owner as departed.
+   */
+  private static preserveConfirmedOwner(task: ITask, payload: WebSocketPayload): WebSocketPayload {
+    const confirmedOwner = task.data?.interaction?.owner;
+    const incomingOwner = payload.interaction?.owner;
+    if (!confirmedOwner || !incomingOwner || confirmedOwner === incomingOwner) {
+      return payload;
+    }
+
+    const confirmedOwnerIsActive = TaskManager.isParticipantActiveOnMainInteraction(
+      payload,
+      confirmedOwner
+    );
+    const incomingOwnerIsExplicitlyDeparted =
+      payload.participantId === incomingOwner ||
+      payload.interaction?.participants?.[incomingOwner]?.hasLeft === true;
+
+    if (!confirmedOwnerIsActive || !incomingOwnerIsExplicitlyDeparted) {
+      return payload;
+    }
+
+    return {
+      ...payload,
+      owner: confirmedOwner,
+      interaction: {...payload.interaction, owner: confirmedOwner},
+    };
+  }
+
   /**
    * Resolve lifecycle events that are emitted for the main interaction while the
    * local task can still be indexed by a child consult interaction. Exact task
    * keys are handled before this fallback. Multiple aliases of the same task are
    * treated as one candidate; genuinely ambiguous matches are intentionally ignored.
    */
-  private findUniqueTaskByRelatedInteraction(payload: WebSocketPayload): ITask | undefined {
-    const payloadInteractionIds = new Set(
-      [
-        payload.interactionId,
-        payload.interaction?.interactionId,
-        payload.interaction?.mainInteractionId,
-        payload.interaction?.parentInteractionId,
-        payload.interaction?.callProcessingDetails?.parentInteractionId,
-      ].filter((interactionId): interactionId is string => Boolean(interactionId))
-    );
-    if (payloadInteractionIds.size === 0) return undefined;
-
-    const candidates = [
-      ...new Set(
-        Object.values(this.taskCollection).filter((candidate) => {
-          const taskInteraction = candidate?.data?.interaction;
-          const candidateInteractionIds = [
-            candidate?.data?.interactionId,
-            taskInteraction?.interactionId,
-            taskInteraction?.mainInteractionId,
-            taskInteraction?.parentInteractionId,
-            taskInteraction?.callProcessingDetails?.parentInteractionId,
-          ];
-
-          return candidateInteractionIds.some(
-            (interactionId) => Boolean(interactionId) && payloadInteractionIds.has(interactionId)
-          );
-        })
-      ),
-    ];
+  private findUniqueTaskByRelatedInteraction(
+    payload: WebSocketPayload,
+    candidateFilter: (task: ITask) => boolean = () => true
+  ): ITask | undefined {
+    const candidates = this.findRelatedTasks(payload).filter(candidateFilter);
 
     if (candidates.length === 1) {
       return candidates[0];
@@ -701,6 +854,49 @@ export default class TaskManager extends EventEmitter {
     return undefined;
   }
 
+  private findRelatedTasks(
+    payload: WebSocketPayload,
+    options: {includeCollectionKeys?: boolean; includeMainCallMediaKeys?: boolean} = {}
+  ): ITask[] {
+    const {includeCollectionKeys = false, includeMainCallMediaKeys = false} = options;
+    const payloadInteractionIds = new Set(
+      [
+        payload.interactionId,
+        payload.interaction?.interactionId,
+        payload.interaction?.mainInteractionId,
+        payload.interaction?.parentInteractionId,
+        payload.interaction?.callProcessingDetails?.parentInteractionId,
+        ...(includeMainCallMediaKeys ? [TaskManager.getMainCallMediaId(payload.interaction)] : []),
+      ].filter((interactionId): interactionId is string => Boolean(interactionId))
+    );
+    if (payloadInteractionIds.size === 0) return [];
+
+    return [
+      ...new Set(
+        Object.entries(this.taskCollection)
+          .filter(([taskId, candidate]) => {
+            const taskInteraction = candidate?.data?.interaction;
+            const candidateInteractionIds = [
+              ...(includeCollectionKeys ? [taskId] : []),
+              candidate?.data?.interactionId,
+              taskInteraction?.interactionId,
+              taskInteraction?.mainInteractionId,
+              taskInteraction?.parentInteractionId,
+              taskInteraction?.callProcessingDetails?.parentInteractionId,
+              ...(includeMainCallMediaKeys
+                ? [TaskManager.getMainCallMediaId(taskInteraction)]
+                : []),
+            ];
+
+            return candidateInteractionIds.some(
+              (interactionId) => Boolean(interactionId) && payloadInteractionIds.has(interactionId)
+            );
+          })
+          .map(([, candidate]) => candidate)
+      ),
+    ];
+  }
+
   /**
    * Handle task lifecycle events and determine required actions
    *
@@ -726,6 +922,9 @@ export default class TaskManager extends EventEmitter {
       case CC_EVENTS.CONTACT_MERGED:
         return this.handleContactMergedEvent(context);
 
+      case CC_EVENTS.CONTACT_OWNER_CHANGED:
+        return this.handleContactOwnerChanged(context);
+
       case CC_EVENTS.AGENT_OFFER_CAMPAIGN_RESERVATION:
         return this.handleCampaignPreviewReservation(context);
 
@@ -737,6 +936,74 @@ export default class TaskManager extends EventEmitter {
     }
   }
 
+  /**
+   * Recover the promoted agent's active voice task when local task state was lost.
+   * Existing related tasks are never replaced: an unresolved or ambiguous relation
+   * is safer to ignore than to create a duplicate task.
+   */
+  private handleContactOwnerChanged(context: EventContext): TaskEventActions {
+    if (context.task) {
+      return {task: context.task};
+    }
+
+    const {payload} = context;
+    if (
+      this.findRelatedTasks(payload, {
+        includeCollectionKeys: true,
+        includeMainCallMediaKeys: true,
+      }).length > 0 ||
+      !this.canRecoverTaskFromContactOwnerChanged(payload)
+    ) {
+      return {};
+    }
+
+    const stableInteractionId = TaskManager.getStableMainInteractionId(payload);
+    if (!stableInteractionId || this.taskCollection[stableInteractionId]) {
+      return {};
+    }
+
+    const normalizedPayload: WebSocketPayload =
+      payload.interactionId === stableInteractionId
+        ? payload
+        : {...payload, interactionId: stableInteractionId};
+    const taskData: TaskData = {
+      ...normalizedPayload,
+      owner: normalizedPayload.interaction.owner,
+      wrapUpRequired: normalizedPayload.interaction.participants?.[this.agentId]?.isWrapUp || false,
+      isConferenceInProgress: getIsConferenceInProgress(normalizedPayload),
+      isConsulted: false,
+      isAutoAnswering: false,
+    };
+    const task = TaskFactory.createTask(
+      this.contact,
+      this.webCallingService,
+      taskData,
+      this.configFlags,
+      this.wrapupData,
+      this.agentId,
+      this.answerCallOnWebexService
+    );
+
+    this.taskCollection[stableInteractionId] = task;
+
+    // Restore the actor before installing listeners so the internal hydrate does
+    // not leak as a second public hydrate or as an incoming-task notification.
+    task.sendStateMachineEvent({
+      type: TaskEvent.HYDRATE,
+      taskData,
+      agentId: this.agentId,
+    } as TaskEventPayload);
+
+    this.setupTaskListeners(task);
+    context.payload = taskData;
+    context.stateMachineEvent = {
+      type: TaskEvent.CONTACT_OWNER_CHANGED,
+      taskData,
+    };
+
+    return {task};
+  }
+
   private handleCampaignContactUpdated(context: EventContext) {
     const {payload} = context;
     let {task} = context;

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

@@ -437,6 +437,7 @@ The public `TASK_EVENTS` enum contains 49 members; every member is listed below
 | TASK-R-007 | Route enabled preview-campaign accept, skip, and remove operations through the dialer AQM factory using `PreviewContactPayload`, returning `Promise<TaskResponse>` from the public ContactCenter methods. Before routing skip/remove, reject the operation when the matching task's disable flag is `'true'`. | Preview reservations require typed payloads and correlated backend completion, while campaign controls must block prohibited skip/remove requests before transport begins. | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/task/dialer.ts` | Public delegation and dialer requests are covered; the `campaignPreviewSkipDisabled` and `campaignPreviewRemoveDisabled` early-exit guards lack direct unit coverage. Independent review identified this gap on 2026-07-15. | PRESENT |
 | TASK-R-008 | Voice `dropConferenceParticipant` must validate the public target, resolve the latest main interaction, POST an empty body to the encoded participant-drop route, and settle only from `ParticipantLeftConference`, `ParticipantDropConferenceFailed`, HTTP failure, or the existing AQM timeout. | Participant removal is backend-authoritative and must preserve event-driven roster/state synchronization without exposing participant identifiers through telemetry or logs. | `src/services/task/voice/Voice.ts`, `src/services/task/contact.ts`, `src/services/task/types.ts` | `test/unit/spec/services/task/voice/Voice.ts`, `test/unit/spec/services/task/contact.ts`, `test/unit/spec/services/core/aqm-reqs.ts` | Backend authorization and media removal are remote-service responsibilities. | PRESENT |
 | TASK-R-009 | ContactCenter must inject Desktop Profile collaboration policy into TaskFactory, and every created voice/digital Task must expose ordered Consult and Transfer destination categories through `TaskUIControls.consultTransferDestinations`. | Task consumers need one already-computed policy surface and must not fetch profile flags or duplicate destination decisions. | `src/cc.ts`, `src/services/task/TaskFactory.ts`, `src/services/task/types.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/task/TaskFactory.ts` | Host-specific UI options may only further hide an SDK-allowed category. | PRESENT |
+| TASK-R-010 | TaskManager must propagate backend owner promotion without electing an owner locally. `ContactOwnerChanged` resolves an exact task first, then one unique related task whose existing snapshot proves that the current Agent is active on `mainCall`, or whose incoming snapshot both names that Agent as `interaction.owner` and proves the same active-main-leg membership. Active membership requires a participant entry with `hasLeft !== true`. If no task exists, recovery is limited to that incoming owner=current-Agent proof: create the normal Task under the stable main interaction ID, silently HYDRATE its actor before listener installation, then process the original owner-change event so consumers receive one `task:hydrate` and no `task:incoming`. An owner-changing `ContactUpdated` uses the existing owner-change hydrate path only for an existing task, and a late `ParticipantLeftConference` cannot replace a confirmed active owner with the departed participant. | Every surviving agent must observe the backend-selected primary Agent immediately, including stale child-keyed and narrowly recoverable desynchronization cases, without duplicating tasks or exposing an uninitialized actor. | `src/services/task/TaskManager.ts` | `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/Task.ts` | Backend owner selection and delivery of a complete owner-bearing `ContactOwnerChanged` payload remain remote responsibilities; missing-task `ContactUpdated` remains update-only. | PRESENT |
 
 ## Design Overview
 Task separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. A shared Task base preserves a stable API while media-specific subclasses and a separate state engine enforce capability differences.
@@ -918,6 +919,39 @@ returns to the main-call state selected by the existing guards. Starting a
 consult preserves the prior task snapshot so this membership comparison remains
 available while the consult is initiating.
 
+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
+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.
+
+If no related task exists, TaskManager recovers only the promoted current Agent
+from a non-terminal telephony `ContactOwnerChanged` payload that provides the same
+active-main-leg evidence. It creates the normal Task through TaskFactory under the
+stable main interaction ID, sends an internal HYDRATE before installing external
+listeners, and then processes the original owner-change event. Consumers
+therefore receive one `task:hydrate`, never a synthetic `task:incoming`, and a
+later canonical contact or merge event reuses the same task rather than creating
+an alias. Missing, partial, departed, consult-only, non-promoted, and ambiguous
+payloads are ignored for recovery.
+
+For other surviving Agents, a `ContactUpdated` whose non-empty
+`interaction.owner` differs from the current owner is delivered through the
+existing `CONTACT_OWNER_CHANGED`/`task:hydrate` path; same-owner or owner-less
+updates remain data-only, and a missing task is not created from `ContactUpdated`.
+If a later `ParticipantLeftConference` still names the departed participant as
+owner, an already confirmed owner is retained only when the new roster proves
+that confirmed owner remains active on `mainCall` and explicitly names the
+incoming owner as `participantId` or marks it `hasLeft`. Main-call omission alone
+is not departure evidence. The SDK never chooses the successor locally.
+
 In the Contact Center sample roster, non-owner and Supervisor targets remain
 visible but non-actionable; the UI does not display a separate read-only label.
 The roster is visible whenever the viewing agent remains active on the main leg
@@ -1383,7 +1417,7 @@ await cc.stationLogin({ loginOption: 'BROWSER', ... });
 - A shared Task base preserves a stable API while media-specific subclasses and a separate state engine enforce capability differences.
 
 ## Test-Case Strategy (module)
-Use `test/unit/spec/services/task/Task.ts`, `TaskFactory.ts`, `TaskManager.ts`, media-specific suites, contact/dialer suites, and state-machine suites. Cover concrete-versus-interface method signatures, every TASK_EVENTS group, unsupported media rejection, primary/RTD event ownership, injected state actions, preview-campaign accept/skip/remove payloads and failure paths, the disabled skip/remove pre-guards, Participant Drop validation/correlation/privacy, and success/failure/timeout paths.
+Use `test/unit/spec/services/task/Task.ts`, `TaskFactory.ts`, `TaskManager.ts`, media-specific suites, contact/dialer suites, and state-machine suites. Cover concrete-versus-interface method signatures, every TASK_EVENTS group, unsupported media rejection, primary/RTD event ownership, injected state actions, preview-campaign accept/skip/remove payloads and failure paths, the disabled skip/remove pre-guards, Participant Drop validation/correlation/privacy, primary-owner promotion propagation, and success/failure/timeout paths.
 
 | Behavior / Requirement | Existing test evidence | Gap |
 |---|---|---|
@@ -1396,6 +1430,7 @@ Use `test/unit/spec/services/task/Task.ts`, `TaskFactory.ts`, `TaskManager.ts`,
 | `TASK-R-007` | `test/unit/spec/cc.ts`, `test/unit/spec/services/task/dialer.ts` | Add direct tests proving disabled skip/remove flags throw before dialer invocation; keep public signatures, metrics/error handling, and AQM request contracts synchronized. |
 | `TASK-R-008` | `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/voice/Voice.ts`, `test/unit/spec/services/task/contact.ts`, `test/unit/spec/services/core/aqm-reqs.ts`, `test/unit/spec/services/task/TaskManager.ts` | None. |
 | `TASK-R-009` | `test/unit/spec/cc.ts`, `test/unit/spec/services/task/TaskFactory.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | None. |
+| `TASK-R-010` | `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/Task.ts` | None. |
 
 ## Traceability
 - Repo architecture: `../../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../../ai-docs/SPEC_INDEX.md`

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

@@ -78,7 +78,7 @@ See root `CONTRACTS.md` for the package-level state-control export.
 | TASK_STATE_MACHINE-R-005 | Keep authentication and credentials outside the state-machine layer; it receives typed Task data/events and never invokes authenticated transport. | Pure transition logic remains reusable and cannot leak or mutate host authentication state. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/types.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts` | None; security/auth applicability is explicitly N/A. | PRESENT |
 | TASK_STATE_MACHINE-R-006 | Treat `UIControlConfig` values as Task-supplied capability configuration, not rollout flags evaluated or owned by the state machine. | Rollout and profile policy must be resolved before actor construction so transitions remain deterministic. | `src/services/task/state-machine/types.ts`, `src/services/task/Task.ts` | `test/unit/spec/services/task/Task.ts` | None; rollout ownership is explicit. | PRESENT |
 | TASK_STATE_MACHINE-R-007 | Keep logging and metrics in Task/TaskManager integration; the state-machine implementation has no LoggerProxy or MetricsManager dependency. | Separating observability side effects from guards/actions preserves deterministic transition tests. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/Task.ts` | `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/Task.ts` | None; observability ownership is explicit. | PRESENT |
-| TASK_STATE_MACHINE-R-008 | `CONTACT_OWNER_CHANGED` must synchronize task/context data and emit `task:hydrate` without transitioning state; participant Drop must rely on the existing `ParticipantLeftConference` mapping rather than adding an initiating state event. From every active call-control state, `PARTICIPANT_LEAVE` terminates or wraps the current Agent only when the event names that Agent, marks that Agent `hasLeft`, or removes a previously active Agent from the participant map; an event naming another participant cannot infer self-departure from a partial media roster. `CONSULT_END` evaluates the same explicit evidence before initiator recovery and additionally supports the narrow from-conference nested-consult race where a previously main-leg Agent is absent from the updated `mainCall` but remains active in the participant map and present on the consult leg. Removed accepted Agents emit `task:consultEnd` plus `task:end`, surviving initiators recover to their main call, and an unaccepted OFFERED consultee emits only `task:consultEnd`. Missing, partial, contradictory, or ordinary CONNECTED/HELD media membership is non-terminal, and starting Consult must preserve the prior task snapshot used by the guard. | Owner-sensitive consumers must rerender promptly while participant and consult removal remain backend-authoritative, state-independent, and compatible with existing incoming-task callback behavior. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/actions.ts`, `src/services/task/state-machine/guards.ts`, `src/services/task/TaskManager.ts` | `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/guards.ts` | Backend ownership-successor selection and event delivery are outside this module. | PRESENT |
+| TASK_STATE_MACHINE-R-008 | `CONTACT_OWNER_CHANGED` must synchronize task/context data and emit `task:hydrate` without transitioning state. A TaskManager-recovered promoted-Agent task first receives an internal IDLE `HYDRATE` before listener installation, then the original owner-change event produces exactly one external hydrate and no incoming event. TaskManager maps an owner-changing `ContactUpdated` for an existing task to that owner-change event, while same-owner or owner-less updates remain `CONTACT_UPDATED`; missing-task `ContactUpdated` does not create a task. It also preserves an already confirmed active owner from a late participant-left snapshot that still names the departed owner. Participant Drop must rely on the existing `ParticipantLeftConference` mapping rather than adding an initiating state event. From every active call-control state, `PARTICIPANT_LEAVE` terminates or wraps the current Agent only when the event names that Agent, marks that Agent `hasLeft`, or removes a previously active Agent from the participant map; an event naming another participant cannot infer self-departure from a partial media roster. `CONSULT_END` evaluates the same explicit evidence before initiator recovery and additionally supports the narrow from-conference nested-consult race where a previously main-leg Agent is absent from the updated `mainCall` but remains active in the participant map and present on the consult leg. Removed accepted Agents emit `task:consultEnd` plus `task:end`, surviving initiators recover to their main call, and an unaccepted OFFERED consultee emits only `task:consultEnd`. Missing, partial, contradictory, or ordinary CONNECTED/HELD media membership is non-terminal, and starting Consult must preserve the prior task snapshot used by the guard. | Owner-sensitive consumers must rerender promptly while owner selection, participant removal, consult removal, and narrowly scoped desynchronization recovery remain backend-authoritative and compatible with existing incoming-task callback behavior. | `src/services/task/state-machine/TaskStateMachine.ts`, `src/services/task/state-machine/actions.ts`, `src/services/task/state-machine/guards.ts`, `src/services/task/TaskManager.ts` | `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/TaskManager.ts`, `test/unit/spec/services/task/state-machine/TaskStateMachine.ts`, `test/unit/spec/services/task/state-machine/guards.ts` | Backend ownership-successor selection and delivery of complete recovery payloads are outside this module. | PRESENT |
 
 ## Design Overview
 TaskManager maps Contact Center notifications to `TaskEvent` values. Each Task sends those events to its XState actor built by `createTaskStateMachine()`. The configuration applies guards and named actions, updates `TaskContext`, and computes UI controls. Task supplies the integration-specific `syncTaskDataFromEvent` implementation through machine options; it is not a default action in `actions.ts`.
@@ -216,6 +216,14 @@ sequenceDiagram
 
 ### Hydrate and recovery
 
+When TaskManager narrowly recovers a missing promoted-Agent task from a complete
+`ContactOwnerChanged` payload, it sends `HYDRATE` while the new actor is still
+unobserved so the IDLE guards restore CONNECTED, HELD, CONFERENCING, or another
+backend-represented state. TaskManager then installs listeners and forwards the
+original `CONTACT_OWNER_CHANGED`; only that second event emits the single public
+`task:hydrate`. Recovery never emits `task:incoming`, and missing-task
+`ContactUpdated` does not use this path.
+
 ```mermaid
 sequenceDiagram
   participant TM as TaskManager
@@ -1749,7 +1757,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | `AGENT_CONTACT_RESERVED`           | `TASK_INCOMING`               | `IDLE`                                               | `OFFERED`                                                                     | Incoming task entry               |
 | `AGENT_OFFER_CONTACT`              | `TASK_OFFERED`                | `OFFERED`                                            | `OFFERED`                                                                     | Offer payload refresh             |
 | `AGENT_CONTACT`                    | `HYDRATE`                     | `IDLE`                                               | `WRAPPING_UP` / `CONSULTING` / `HELD` / `CONNECTED` / `CONFERENCING` / `IDLE` | Guard-based restore               |
-| `CONTACT_UPDATED`                  | `CONTACT_UPDATED`             | any                                                  | same                                                                          | Context sync                      |
+| `CONTACT_UPDATED`                  | `CONTACT_UPDATED` or `CONTACT_OWNER_CHANGED` | any                                      | same                                                                          | Owner delta uses existing hydrate path; same/missing owner is context sync only |
 | `CONTACT_OWNER_CHANGED`            | `CONTACT_OWNER_CHANGED`       | any                                                  | same                                                                          | Context/data sync + `task:hydrate` |
 | `AGENT_OFFER_CONSULT`              | `OFFER_CONSULT`               | `OFFERED`                                            | `OFFERED`                                                                     | Receiver-side consult offer       |
 | `AGENT_CONTACT_ASSIGNED`           | `ASSIGN`                      | `OFFERED` / `CONNECTED` / `CONSULTING`               | `CONNECTED`                                                                   | Assign/reassign                   |
@@ -1794,7 +1802,7 @@ Complete mapping from backend CC_EVENTS to internal TaskEvent types.
 | `AgentOfferContact`      | `TASK_OFFERED`          | Stay in OFFERED                                               | Offer confirmation                             |
 | `AgentContact`           | `HYDRATE`               | Various                                                       | State restoration                              |
 | `AgentContactAssigned`   | `ASSIGN`                | OFFERED → CONNECTED (also CONNECTED/CONSULTING refresh paths) | Task accepted/reassigned                       |
-| `ContactUpdated`         | `CONTACT_UPDATED`       | No change                                                     | Data update only                               |
+| `ContactUpdated`         | `CONTACT_UPDATED` or `CONTACT_OWNER_CHANGED` | No change                                      | Changed non-empty owner also emits `task:hydrate`; same/missing owner is data-only |
 | `ContactOwnerChanged`    | `CONTACT_OWNER_CHANGED` | No change                                                     | Owner update plus `task:hydrate` emission      |
 | `ContactEnded`           | `CONTACT_ENDED`         | Guard-based branch                                            | CONFERENCING / WRAPPING_UP / TERMINATED / stay |
 | `AgentContactUnassigned` | None                    | N/A                                                           | Handled by other events                        |