fix: two-player lobby deadlock

docs/API_CONTRACT.md

@@ -66,6 +66,11 @@ The session token is in each POST body. For `GET /api/state`, it is supplied
 in `X-Session-Token`; absence creates a spectator-safe view. It is never a URL
 parameter.
 
+For the primary “Play” action, `requestedRole: "player"` atomically assigns
+the first available player slot (`player1`, then `player2`). This avoids a
+client-side availability race; the response and every authorized state snapshot
+contain the assigned concrete role.
+
 `leave` and `profile-reset` release only the requesting session; profile data is
 cleared by the browser in Milestone 022. A player leaving an active match aborts
 that match and returns remaining valid players to the lobby. `game/reset` is

docs/openapi.yaml

@@ -240,7 +240,8 @@ components:
       description: Opaque, reboot-scoped session token.
     Role:
       type: string
-      enum: [player1, player2, spectator]
+      enum: [player1, player2, spectator, player]
+      description: '`player` atomically assigns the first available player slot; responses always contain player1 or player2.'
     Mode:
       type: string
       enum: [human, bot]