## ARENA BATTLE — ROOM REVIEWS AND STAFF / v15 R27

## Player flow
A room participant can report a frozen display, stalled game or audio/video issue through Room review. Spectators cannot submit reports. Only one open review exists per room; another participant receives the same review ID instead of creating a duplicate. After resolution, a room-wide 5-minute server-clock cooldown applies. Finished/cancelled battles cannot receive new reports.

Reporting does not stop play or move money. Participants receive in-app notifications; authorized provider/operator staff see the open count under Room reviews. Panel counters poll every 15 seconds; player review status polls every 3 seconds.

## Staff decisions
Claim the review first. Another reviewer cannot decide for 10 minutes; provider staff can immediately take over a claim held by operator staff. Resolution needs a note of at least 10 characters and is audited:
- No fault found: notifies players without changing the game or balances.
- Close and refund: staff-confirmed fault only; stop the room and return every original entry to its original site wallet. Partial bonus winnings are not distributed separately. Finalized battles cannot be refunded again.

Only provider staff may resolve cross-site room reviews. Operator staff can view/claim them, but cannot see another site's member identity, report details or private operator-staff notes. Operators can resolve their own single-site rooms.

## Refund recovery
Approval is durable before cancellation. Existing ledgers/outboxes own refunds and immutable transaction IDs. Repeating a decision never adds a second refund. Lost acknowledgements, pending joins, departed-seat refunds and restarts remain tracked until reconciliation completes. A worker-close acknowledgement is also required before staff cancellations show as complete. If normal cancellation already occurred, its original refund is inspected rather than recreated. Reports are not automatic fault diagnoses: staff must inspect evidence and room state.

## Staff access
Operator panel > Team supports named staff, email, initial password and individual grants. Site identity comes from the authenticated panel session. Managers cannot grant privileges they lack, edit stronger accounts or remove the last active team manager. Permission/password/deactivation updates revoke old sessions. Every staff member enrolls their own 2FA.

Provider panel > Team and roles supports named accounts and custom roles. The final active provider owner is protected. Review access uses `reviews.read`/`reviews.manage`; operator team access uses `team.read`/`team.manage`. Write grants require the matching read grant. Queued decisions revalidate the actual session and grants immediately before execution; already-approved durable refunds continue recovery after staff revocation.

## Endpoints
Player bearer session (used automatically by iframe/module clients):
```text Endpoint contract · notation, not JSON
GET  /play/:slug/api/room-review?room=:roomId
POST /play/:slug/api/room-review?room=:roomId {reason: frozen|stuck|audio_video|other, details?: string(0..500)}
```

First report: 201. Existing report: 200 with `alreadyReported`:true. Cooldown: 429.

Panel session; same Origin and `X-CSRF-Token` on POST/PATCH:
```text Endpoint contract · notation, not JSON
GET  /control/api/reviews or /operator-api/reviews (?summary=1 for count only)
POST /control/api/reviews/:id or /operator-api/reviews/:id {action: claim|no_issue|refund, note?: string}
GET/POST /operator-api/team
PATCH /operator-api/team/:id
```

Create staff: `{name,email,password,permissions:[...]}`; edit: `{name?,password?,active?,permissions?}`.

These are session-protected panel routes, not server-key money-transfer APIs. The server integration contract remains unchanged; wallet callbacks send refunds to the operator. Never expose secrets in the client. See ACCESS-SECURITY.en.txt and SEAMLESS-WALLET.en.txt for session, 2FA, source-IP and wallet integration details.

## Upgrade
Redeploy the current client ZIP for a file/module installation; iframe clients load from the provider. Provider and file client must both be R27-compatible. Reviews and staff grants persist in SQLite. Do not roll back to R26 with restricted staff or unresolved reviews: that version does not understand these restrictions.
