# HyperTwist Alpha Test Takeover, Black-Screen Repair, and Validation

Date: `2026-07-19`

Last updated: `2026-07-23`

Status: fixed Shipping Alpha delivered and archive-verified; first-run and
Classic interactive visuals green; coach-dashboard route green under
first-party headless diagnostics, with a fresh dashboard screenshot retained
as operator-connected visual QA rather than misreported from a disconnected
desktop

## Purpose

This document is the durable handoff and evidence authority for the first
operator-reported HyperTwist desktop Alpha failures:

- an earlier extracted executable opened to a black or functionally empty scene
- an earlier ZIP could not be opened reliably
- another loose executable failed because `tbbmalloc.dll` was absent
- prior package smoke reports proved process survival but did not prove that a
  rendered launch surface, gameplay map, camera, HUD, or cube was present

The repair goal is stricter than "the process starts." A distributable is ready
only when the exact packaged binary:

1. creates a real Unreal window in the interactive Windows desktop session
2. renders the first-run launch surface
3. opens the coach dashboard from that surface
4. opens the Classic Cube route from that surface
5. renders all 26 visible cubies, the authored environment, the orbit camera,
   and the gameplay HUD
6. writes current runtime and startup diagnostics
7. survives fresh packaged launches for all four shipped training maps
8. is delivered as a complete folder and a ZIP whose entries and hash are
   independently verified

## Authority and source review

The takeover review used the live HyperTwist repository as implementation
authority and cross-referenced the following context families:

- `docs/`, including the comprehensive reconstruction roadmap, deep manual
  pack, feature registry, development guide, packaging doctrine, hygiene
  doctrine, reverse-SSH runbook, and previous Windows package evidence
- `/home/dev/src/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse`
  as historical product, donor, clean-room, and handoff lineage
- `/home/dev/src/Workspaces/HyperTwist` as repository-evaluation and clean-room
  workspace lineage
- `/home/dev/src/Workspaces/HyperTwist-worktrees` as worktree-placement context
- the maintained Windows validation root
  `C:\HyperTwist_worktrees\phase10validate`

Historical parse documents remain useful lineage, but their May 2026 maturity
descriptions do not outrank the current source, current roadmap, or current
packaged-runtime evidence.

## Failure analysis

### 1. Native widget trees were built too late

The first-run menu, Classic HUD, and coach dashboard are native `UUserWidget`
implementations. Their old lifecycle could let `Super::RebuildWidget()` cache
an empty fallback Slate widget before the code-created `WidgetTree` had a root.
Later construction changed UObject state, but not necessarily the already
cached rendered Slate tree. This explains a package that was alive and logging
without showing its intended UI.

Repair:

- build native widget roots before the superclass Slate rebuild completes
- keep initialization and construction idempotent
- expose explicit readiness predicates for all three surfaces
- reject and log a widget that has no renderable root
- place launch/dashboard surfaces above ordinary gameplay HUD layers
- validate first-run cached geometry after real layout ticks rather than
  treating `AddToViewport()` as visual proof

### 2. Cooked runtime geometry ownership was incomplete

The Classic cube's 26 procedural cubie components could exist during editor
construction while not remaining authoritative in the cooked runtime. The old
`BeginPlay()` path skipped regeneration when construction generation was
enabled. A prior packaged log therefore truthfully reported `0 renderable
pieces` even though the map contained a placed cube actor.

Repair:

- define the physical invariant as 26 visible cubies; the enclosed core is not
  rendered
- count registered procedural meshes with actual sections at runtime
- call `EnsureRenderablePresentation()` from both actor and game-mode startup
- regenerate when the count is incomplete
- own dynamic meshes and turn pivots as actor instance components
- mark runtime-generated presentation components transient so cooked map
  serialization is not mistaken for runtime ownership
- log the exact final cubie count and whether recovery was required

### 3. The authored maps were presentation-incomplete

The earlier Classic and Follow-Along maps were too sparse to be trusted as
shipping launch surfaces. A later visual run also exposed a real-time SkyLight
without the required SkyAtmosphere context.

Repair:

- transactionally author both maps with a floor, directional light, SkyLight,
  SkyAtmosphere, reflection capture, PlayerStart, and cube actor
- preserve the correct game-mode override per map
- validate the seven required actor labels before writing a durable completion
  marker
- restore the pre-authoring map automatically if authoring does not complete
- use D3D11 offscreen authoring by default because the zero-extent headless
  Plane path was unsafe on this UE 5.7 host
- use a thin Cube floor to retain volumetric bounds
- keep game-mode fallbacks for a missing orbit pawn or key light

Current source map SHA-256 values after transactional authoring:

- Classic: `b47d58cc2db66589cb0110548a002cf8446ce610c8448c50c9fbab329f3742ff`
- Follow-Along: `69a986cf36d53a6a22845dc89ecbe95119a1c2f383f344ecf020d6ee58ba0e47`

### 4. Unquoted INI URLs were parsed incorrectly

The configured local HTTP sidecar values used `http://...` without quotes.
Unreal INI parsing could collapse these values to `http:/...`, producing
malformed requests and noisy startup failures.

Repair:

- quote all three local HTTP service base URLs in `DefaultGame.ini`
- trim and validate complete `http://` or `https://` schemes in each HTTP
  client before joining paths
- reject an absent authority rather than emitting a malformed request
- add a loaded-default configuration regression test for vision, speech, and
  voice clients

Connection-refused warnings remain acceptable when an optional local sidecar
is not running. A malformed URL is not acceptable.

### 5. Package validation could report false success

Several harness behaviors allowed stale or incomplete evidence:

- old runtime/startup logs could be rediscovered
- a bootstrap process could exit while a child process survived untracked
- cleanup could leave packaged children running
- a raw path prefix could classify a sibling archive as an owned process
- a 10-second map smoke ended during plugin startup before any world loaded
- process survival and image brightness did not prove a specific UI route

Repair:

- remove the target runtime log before each launch and require the new file
- require fresh startup diagnostics by timestamp
- discover package descendants by executable path and protect pre-existing PIDs
- match owned paths at a directory boundary, not a raw string prefix
- stop the complete owned process family after validation
- classify Unreal low-level fatal, assertion, critical-error, swap-chain, and
  unhandled-exception signatures as blocking
- require the expected `UnrealWindow` class for visual proof
- capture only the verified client rectangle with per-monitor DPI awareness
- inject interaction into the verified client and require a route-specific
  startup-diagnostics result
- wait 30 seconds for packaged map smoke, require an actual target-map load
  line, and require the exact 26-cubie marker for Classic and Follow-Along
- serialize plain strings into reports so PowerShell object formatting cannot
  create a false result
- terminate timed-out interactive-task descendants before deleting the task

### 6. Generic map arguments did not own packaged startup

The project-level first-run game-mode authority can override a generic map
argument. Earlier package helpers therefore appeared to request a training map
while the product still resolved its normal first-launch owner. This was a
validation-route defect, not proof that the family map had opened.

Repair:

- add the bounded first-party
  `-HyperTwistStartupRoute=<registered-route>` argument
- resolve the argument only through
  `UHyperTwistFirstRunLaunchLibrary::BuildFirstRunLaunchRoutes()`
- reject empty, duplicate, unknown, overlong, case-drifted, or character-
  injected route identifiers
- invoke the same `OpenFirstRunRoute()` authority used by visible UI buttons
- make package launchers use the public outer bootstrap and registered route
  ids instead of treating raw map arguments as product authority
- cover absent, valid, and invalid parser states in focused automation

### 7. Stock Shipping did not guarantee an Unreal log

The final package uses an ordinary Unreal Shipping target. It does not enable
the incompatible `bUseLoggingInShipping` target posture, and an engine
`-log`/`-abslog` file is therefore optional rather than release authority.

Repair:

- add `HyperTwistRuntimeDiagnostics`, a first-party, Shipping-compatible,
  append-only diagnostics surface independent of `UE_LOG`
- accept an explicit `-HyperTwistDiagnosticsLog=<path>` for immutable
  validation runs
- otherwise write `HyperTwistRuntime-latest.log` beneath the user Saved/Logs
  directory
- require runtime initialization, semantic map/presentation markers, fatal
  scans across every available log, package-owned process command lines, and
  no unexpected listener/trace-control endpoint
- retain `HyperTwistFirstRunLaunch-latest.log` as the separate bounded
  first-run/menu/route result authority

### 8. Desktop pixels alone were not semantic proof

`CopyFromScreen()` can capture the surrounding desktop when a window is hidden,
occluded, moved by DPI scaling, or unavailable in a disconnected session. A
bright screenshot is not sufficient evidence that HyperTwist rendered the
expected product surface.

Repair:

- have first-run, Classic, and higher-dimensional runtime owners request a
  named ready-frame capture only after their semantic readiness invariant is
  true
- require a fresh named PNG created after the launch timestamp for release
  visual gates
- record both the copied evidence SHA-256 and the original semantic-frame
  SHA-256
- keep client-window screenshots without a semantic capture as operator
  corroboration only
- do not convert a disconnected/locked Windows desktop failure into a green
  visual result

## Validation state

### Source and editor gates green

- UE 5.7 editor and game targets: `Result: Succeeded`
- final Shipping editor rebuild after the route and direct-diagnostics repair:
  `Result: Succeeded`, 10 actions, UnrealBuildTool total `90.11 s`
- focused Classic automation: `16/16` green
- final focused first-run automation: `5/5` green, including
  `PackagedStartupRouteArgumentContract`
- focused HTTP configuration automation: `1/1` green
- Sentrux source-only architecture check: all `7` rules pass
- GitNexus bounded source-only index: current and up to date
- Python map-authoring compile: green
- all current PowerShell package/launch/visual helpers parse successfully

### Historical superseded package archive

Build/archive root:

`C:\HyperTwist_worktrees\phase10validate_packaged_alpha_final_20260719`

Automated package facts:

- configuration: `Development`
- cooked map count: `4`
- packaged executable SHA-256:
  `ccbc74bb6bcc8b7340d74ca15109c8159a83250f1413ea01f7f61a0c091f2c45`
- package file count before final delivery metadata: `127`
- package bytes before final delivery metadata: `1577648281`
- all four initial process-survival map launches completed without fatal log
  signatures
- desktop bootstrap launch completed with a current runtime log and bounded
  NullRHI startup recovery

The initial four-map report was not final semantic authority because its old
10-second interval ended before world load. It is retained only as failure
lineage and is superseded by the Release 17 Shipping evidence below.

### Release 17 Shipping rollback package

Build/archive root:

`C:\HyperTwist_worktrees\phase10validate_packaged_alpha_release17_20260723`

Durable pulled evidence:

`docs/generated/alpha_test_20260723`

Final package facts:

- configuration: `Shipping`
- outer executable SHA-256:
  `886f69c6a823770b3ed68db4fe3790a488124c99c98dbd41944a6bed5d634dc6`
- bootstrap resource:
  `UnrealHyperTwist -notraceserver -traceautostart=0`
- exact solver table: `676207080` bytes, SHA-256
  `dc6de3d909a37afe2ba7f1f978543a13eae215bd20d954d66813524a8ca20034`
- Classic semantic smoke: exact map, `26` renderable pieces, settled valid,
  no queued turns
- Follow-Along semantic smoke: accepted registered startup route, exact map,
  `26` renderable pieces, settled valid, no queued turns
- Magic120Cell semantic smoke: accepted registered startup route, exact map,
  `120` canonical renderable elements, `6` distinct layer materials
- MagicCube5D semantic smoke: accepted registered startup route, exact map,
  `242` canonical renderable elements, `6` distinct layer materials
- all four smokes recorded runtime initialization and semantic `MapReady`
  evidence with no fatal signature, trace listener, or package-owned listening
  endpoint

The first Release 17 aggregate status retained a historical false failure
because the old desktop validator still required an absent Shipping Unreal log.
The corrected v2 launch report is the current authority: direct runtime
diagnostics initialized, first-run diagnostics were fresh, package-owned
processes were live, and no fatal or trace-control evidence was present.

Interactive proof:

- the exact final Downloads executable rendered an `UnrealWindow` and produced
  a fresh semantic first-run frame with result `launch-menu-renderable`,
  screenshot SHA-256
  `6f5e3443d7b9188d6d3642c0a41f703e5a3beed7cee348982f7915621e786919`
- a real `WindowMessage` click on the visible Classic button produced
  `map-route-opened`, the exact Classic map, `26` renderable pieces, `29`
  completed quarter turns, `0` queued turns, and a fresh semantic frame with
  screenshot SHA-256
  `6e6b8f2c06f6ff8a68c2f4d9e0a576305056cd6f4d7353e9894a05e63d853ab5`
- a later dashboard visual retry correctly failed when no live interactive
  desktop was available; no screenshot from that attempt is release evidence
- the same final executable then passed a first-party NullRHI dashboard-route
  probe: runtime initialized, `coach-dashboard` was accepted, and the route
  opened through first-run product authority

### Required final evidence

The following remain the acceptance ledger:

- [x] corrected v2 map-smoke reports prove all four target maps actually loaded
- [x] Classic and Follow-Along diagnostics confirm 26 renderable cubies
- [x] final first-run automation proves route delegates and strict packaged
  startup-route parsing
- [x] interactive first-run screenshot and `launch-menu-renderable`
- [ ] fresh interactive coach-dashboard screenshot after an operator connects
  or unlocks the Windows desktop; the route itself is green under direct
  Shipping diagnostics and this visual-only item must not block use of the
  delivered Alpha
- [x] interactive Classic route screenshot and `map-route-opened`
- [x] interactive Classic diagnostics have 26 cubies and no old presentation
  warnings
- [x] complete folder copied to the Windows Downloads directory
- [x] ZIP created with `System.IO.Compression.ZipFile`
- [x] ZIP reopened, entries enumerated, and seven critical payloads stream-
  hashed from the archive
- [x] final folder/ZIP SHA-256, sizes, and counts recorded

### Current Release 19 Shipping package

Release 19 supersedes Release 17 as the current Alpha authority while retaining
Release 17 as rollback provenance.

Build/archive root:

`C:\HyperTwist_worktrees\phase10validate_packaged_alpha_release19_shipping_20260723`

Current operator delivery:

- `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19`
- `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19.zip`
- `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19-Setup.exe`

Durable pulled evidence:

`docs/generated/alpha_test_20260723_release19`

Release 19 adds the combined player-experience repair above the startup fix:

- exact dedicated 4D orders `2x2x2x2` through `6x6x6x6`
- exact 5D and 120-cell runtime state with deliberately bounded projected
  scenes
- player-facing Learn, Settings, Account, Advanced, About/Credits, pause,
  back, and exit ownership
- fixed native coach with offline guidance plus optional AI, global STT, and
  asynchronous TTS
- separately configurable provider-neutral AI/STT/TTS settings with protected
  credentials and cloud-consent gates
- exact original-29 live capability catalog plus independently verified
  historical Phase 1 browser-support queue

Final acceptance facts:

- UE 5.7 post-repair editor build succeeded in `60.93` seconds
- `HyperTwist.PlayerExperience`: `5` succeeded, `0` failed, `0` warnings
- fresh Shipping build/cook/archive: passed
- all `9` native route smokes: passed
- staged browser runtime and exact solver table: passed
- ZIP: `167` entries, `1093537260` bytes, SHA-256
  `630963f96c681fc49130cbc56c6c850008d4cddda7e83f2ee9c077c52d7709a9`
- all `173` delivered folder files hash-match the validation archive
- both the validation-archive executable and exact Downloads executable
  produced semantic `launch-menu-renderable` visual proof in an `UnrealWindow`
- both visible reports copied screenshot SHA-256
  `caa45f3d3104a8e5406f493a60c8a136d852bd35e0bd1c8dfbf79738c1343892`
- no fatal signature, package-owned listener, trace-control listener, or
  lingering owned packaged process remained
- the later `2026-07-26` installer authority passed with size `851049086`
  bytes, SHA-256
  `c31ed6b0b2ae1feb449c27e484d72dc2e07ba220e3cdafa4c3605429d638e0ea`,
  `143` manifest-owned payload files, and green install, readiness, Shipping
  launch, in-place upgrade, second parity, uninstall, user-data preservation,
  and cleanup proof

The global-assistant regression fix is part of this exact package. A standalone
speech session no longer requires an active Classic training run, so the fixed
coach can use global dictation on 4D, 5D, and 120-cell routes. A real
provider-reachability, microphone, and audible-TTS test still requires
intentionally configured services and hardware and is not inferred from
structural automation.

### Release 19 Windows installer authority

Durable evidence:

`docs/generated/alpha_test_20260726_installer`

The installer is now the preferred first-time Alpha delivery while the
validated folder and ZIP remain portable and rollback-friendly alternatives.
It owns:

- x64 Windows 10 22H2 / Windows 11 preflight
- a valid Microsoft-signed Visual C++ 2015-2022 x64 prerequisite
- a complete `143`-file payload manifest with SHA-256 parity
- safe install-directory leaf and non-empty ownership refusal
- Add/Remove Programs plus resolved app/readiness/uninstall shortcuts
- marker-and-registry-gated upgrade and uninstall
- preservation of settings, saves, replays, and diagnostics

The lifecycle harness deliberately used an install path containing spaces. It
proved an unowned non-empty target was refused before prerequisite or payload
mutation, then passed first install, full parity, installed readiness,
stock-Shipping initialization, in-place upgrade, second parity, and uninstall.
No install root, registration, shortcut, listener, or owned process remained.

This is `isolated-current-host` evidence because no clean VM or Windows Sandbox
was available. The executable is `NotSigned`; trusted Authenticode remains a
production gate rather than an inferred Alpha capability.

### 2026-07-26 final staging retirement

The earlier installer hygiene pass conservatively retained
`C:\HyperTwist_worktrees\phase10validate` plus historical and current package
production roots while four relative source-tree symlinks blocked complete
duplicate proof. That uncertainty is now closed by:

`docs/generated/alpha_test_20260726_installer/post-task-hygiene-reconciliation-report.json`

The reconciliation:

- isolated all `4` relative symlinks without traversing their targets
- compared `19,789` regular snapshot files against the VPS source and Git
  history
- found no unique unlanded source
- proved all `145` current package files and `1,920,300,068` bytes match the
  retained Downloads Release 19 folder
- proved the staging and Downloads ZIPs share SHA-256
  `630963f96c681fc49130cbc56c6c850008d4cddda7e83f2ee9c077c52d7709a9`
- proved the staging and Downloads installers share SHA-256
  `c31ed6b0b2ae1feb449c27e484d72dc2e07ba220e3cdafa4c3605429d638e0ea`

All `8` artifacts under `C:\HyperTwist_worktrees` were therefore removed and
the now-empty staging root was deleted. The current Release 19
folder/ZIP/installer, explicit Release 17 rollback folder/ZIP, and operator
saved data remain protected.

## Operator diagnostics

The delivered Alpha uses stock Shipping configuration and first-party direct
diagnostics. After launch, inspect:

- `%LOCALAPPDATA%\UnrealHyperTwist\Saved\Logs\HyperTwistRuntime-latest.log` -
  Shipping-compatible runtime initialization, map, presentation, and route
  events
- `%LOCALAPPDATA%\UnrealHyperTwist\Saved\Logs\HyperTwistFirstRunLaunch-latest.log`
  - bounded first-run menu, fallback, and route result

An `UnrealHyperTwist.log` may be absent in stock Shipping and is not required
when direct diagnostics are present.

The package-validation helpers also write immutable-per-run evidence beneath
the archive's `validation` directory.

Do not diagnose a black screen by checking only that `UnrealHyperTwist.exe` is
running. Check the window class, current screenshots, startup result, target
map-load line, game-mode presentation marker, and fatal-signature scan.

## Distribution rule

Never distribute a loose `UnrealHyperTwist.exe`. The executable depends on the
complete staged `Windows` directory, including engine binaries, project
content containers, and runtime DLLs such as `tbbmalloc.dll`.

The approved Alpha distribution shapes are:

- the validated installer for normal first-time operator testing
- an extracted folder for direct operator testing
- a separately verified ZIP of that complete folder
- matching release metadata with SHA-256, byte count, file/entry count, and
  validation references

Historical Release 17 rollback delivery:

- folder:
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723`
- folder facts: `103` files, `1887943160` bytes
- ZIP:
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723.zip`
- ZIP facts: `103` entries, `1082134734` bytes, SHA-256
  `1ad8e1c0fc967b227ca09fb68c515ed644eca3e4bda07fdf8c378b438000fc42`

Approved current Release 19 delivery:

- folder:
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19`
- ZIP:
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19.zip`
- ZIP facts: `167` entries, `1093537260` bytes, SHA-256
  `630963f96c681fc49130cbc56c6c850008d4cddda7e83f2ee9c077c52d7709a9`
- installer:
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19-Setup.exe`
- installer facts: `851049086` bytes, SHA-256
  `c31ed6b0b2ae1feb449c27e484d72dc2e07ba220e3cdafa4c3605429d638e0ea`

The superseded July 9 folder and matching ZIP were deleted only after the
replacement folder, archive, critical-entry hashes, and final Downloads launch
were verified. The retirement report is retained at
`docs/generated/alpha_test_20260723/superseded_july9_retirement_report.json`.
