# HyperTwist Phase 4 gameplay coach surface orchestration packet

Created on `2026-05-07`

Status:

- first-party HyperTwist packet
- bounded Phase `4` gameplay-facing consumer slice

## Purpose

This packet starts the first thin gameplay-facing consumer widening above the now-stable coach scheduling and recommendation backend by making the panel-widget and session-actor surfaces executable without extra caller-side provenance glue.

The open tasks were:

- stop forcing gameplay / Blueprint callers to invent their own coach start-action source labels before they can launch the currently displayed recommended, follow-up, queue, or primary coach action
- stop dropping coach provenance entirely on the session-actor path when those actions are launched or deferred work is promoted
- expose one thin displayed-action helper layer so callers can act on the retained panel state directly instead of manually wiring active queue-entry ids every time

It is not:

- a new backend continuity packet
- a new analytics-selection packet
- a dashboard rewrite
- a broader gameplay UI integration pass

## Scope

Bounded lane:

- add panel-widget helpers that resolve default coach handoff / primary-action source labels from the cached coach panel state
- add panel-widget helpers that launch the currently displayed recommended, follow-up, primary, next-queued, and active queue-entry actions without extra caller-side routing
- add panel-widget helper coverage for promoting the currently displayed queue entry
- update the session-actor launch and promotion path to stop recording empty source labels
- mirror the same displayed-action helper layer on the session actor for gameplay-facing Blueprint consumers

Out of scope:

- changing coach recommendation policy
- changing queue execution policy
- changing retained dashboard continuity behavior
- widening into a richer gameplay HUD or CTA presentation pass in the same packet

## Why this was the right next packet

Before this slice:

- the recognition-assisted coach-to-review closure lane was already documented as complete
- the repo already exposed rich cached coach state on `HyperTwistTrainingPanelWidget` and `HyperTwistTrainingSessionActor`
- those surfaces already had the raw launch verbs for recommended, follow-up, queue, and queue-entry work

But the first gameplay-facing consumer seam was still obvious:

- the widget surface still required callers to supply coach start-action source labels themselves
- the actor surface launched and promoted coach work with empty source labels, which threw away provenance and downstream analytics context
- callers still had to manually thread the active queue-entry id out of cached panel state for common displayed-action cases

That meant:

- the backend was ready
- but the first gameplay-facing consumer layer still imposed avoidable orchestration work and provenance loss on the caller

So the next bounded move was:

- keep the backend untouched
- and make the existing panel/actor surfaces honest thin consumers of the current coach panel state

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added coach handoff and primary-action source-label resolvers driven by `CachedCoachPanelState`
  - added displayed-action helpers for recommended, follow-up, primary, next-queued, and active queue-entry coach launches
  - added a displayed queue-entry promotion helper
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added the same source-label resolvers and displayed-action helpers for gameplay-facing actor callers
  - updated existing actor launch and queue-promotion methods so they no longer pass empty start-action source labels into the runtime path

## Product effect

The first gameplay-facing coach consumers are now thinner and more truthful:

- gameplay / Blueprint callers can execute the displayed coach action surface without manufacturing source labels first
- session-actor launches and queue promotions now preserve coach provenance instead of silently dropping it
- callers no longer need to manually copy `ActiveQueueEntryId` out of cached panel state for the common displayed queue-entry path

## Acceptance criteria

- panel-widget callers can resolve default coach source labels from the cached coach panel state
- panel-widget callers can launch the displayed recommended, follow-up, primary, next-queued, and active queue-entry actions through dedicated helpers
- session-actor launches and queue promotions no longer record empty source labels
- session-actor callers get the same displayed-action helper layer
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm the panel widget compiles with the new displayed-action and source-label helper surface
3. confirm the session actor compiles with the new displayed-action helper surface
4. confirm actor-side coach launches and queue promotions now route non-empty source labels

## Validation result

- full `Development Editor|Win64` build succeeded on `2026-05-07`
- build completed with the same preexisting `UnrealMCP` / `PythonScriptPlugin` dependency warning and `0` errors

## Next bounded follow-on slice

- stay on the same gameplay-facing consumer lane and expose one thin primary coach CTA descriptor / availability surface on the panel-widget and session-actor layer so gameplay callers can bind a single truthful coach action without reconstructing queue-vs-follow-up-vs-recommended state from raw booleans
