unreal: distill headless UBT/UHT compile learnings

[ryanlitalien]

Distillation pass per DISTILLING.md, triggered by a new dated entry in the private repo's unreal/LEARNINGS.md. The source was standing up a container-based UE 5.7 headless compile path on a Windows + WSL2 host.

Section A (agent/skill learnings)

Four findings, all of which describe themselves as something they are not:

• An installed (binary) engine refuses a target that changes shared build settings, and UBT's own suggested fix is the trap. A .Target.cs whose DefaultBuildSettings/IncludeOrderVersion differ from the installed engine fails in seconds before compiling anything. UBT suggests BuildEnvironment = TargetBuildEnvironment.Unique, which means "compile the engine too" and is impossible on an installed or container engine.
• UHT cannot parse a nested enum used in a UFUNCTION signature, and reports it as Unable to find ... with name 'X' for a type sitting a few lines above the error.
• One missing #include masquerades as missing types and as broken inheritance, including a TIsDerivedFrom static_assert against a class that does derive from that base. Two includes collapsed roughly 30 of 57 error lines.
• Error_UnknownCookFailure (25) is not always missing content - it can be Blueprint nodes outliving a plugin that is no longer enabled by default. Plus the related preflight: a project with no .umap/.uasset has nothing to cook at all.

Section B (operational/rig)

WSL2's df overreporting free space from a sparse vhdx (895 GB claimed vs 19 GB real on the host volume), Windows OpenSSH killing detached child processes when the session closes, a dead registry credential being indistinguishable from a missing tag, and bounded preflight checks with honest exit-code handling.

Skills

• unreal-observe §8: three new failure-signature rows
• unreal-build §0: two new preflight checks

Distillation compliance

• Sanitization (a): no internal hostnames, machine names, personal names, project codenames, or absolute paths in the added lines. Two grep hits in the touched files are pre-existing and legitimate - "tracer bullet" there is the FAST_COOK technique, and /Users/Shared/Epic Games is the standard macOS engine path.
• Compression (b): 32% shorter than the private source, inside the 30-50% target. A first pass came in at 21% and was recompressed by merging the docker-credential and preflight-bounds items and dropping two automation-authoring traps that are not Unreal findings; those stay private.
• Truthfulness (c): no usage or customer claims. Every finding describes what was actually run.

Note: no Godot content here. Godot remains a 🚧 Planned placeholder in both repos and this pass produced no Godot findings.

🤖 Generated with Claude Code