feat(ar): ship the Ember Fox companion — package, placement and animation

[prabu-openclaw]

Lands the Ember Fox as the packaged AR companion, on top of current main, and fixes the reasons a device never actually showed it.

Carries forward the work in #242 / #243 — same asset, and the simpler load-scale-ground approach from #243 — without the 124-commit rollback those branches carry (they branch from #45 and drop ~249 tests). Credit for the asset and the loading approach is @scrimshawlife-ctrl's.

Why the device never showed the fox

Two independent bugs, both of which made diagnostics look healthy while the wrong thing was on screen.

The placeholder was never swapped out. The companion is spawned as soon as the game asks, routinely before a ~19MB rig finishes decoding — so the first companion is the procedural placeholder. Continuity then reported ok_present and never re-planted. The real asset loaded successfully and sat unused for the entire session, which is why the HUD honestly read animated_usdz … anim=PLAYING while the screen showed cone ears and a gold core sphere. The loader now versions its template; the renderer upgrades a companion built from an older generation.

Stale companions never left the scene. Companions sit on AnchorEntitys added with scene.addAnchor, which the scene's anchor collection owns — removeFromParent() does not detach them. Every replacement therefore rendered behind its predecessor. Covered by a test asserting scene.anchors goes 2 → 1 on replace.

Asset

41MB source → 19.4MB packaged. Texture 4096 PNG → 2048 JPEG. The baked DomeLight is stripped so ARKit environment lighting applies — also required for validation, since .hdr is not a permitted USDZ extension. Repacked with usdzip for 64-byte alignment.

• usdchecker --arkit: PASS
• SkelRoot / Skeleton / SkelAnimation intact; 24-joint humanoid rig
• evidence class MESHY_EMBER_FOX_WALK_V1 (not reusing the artist-blend label), EXPORT_OK rewritten to describe what ships
• triple copy in sync; integrity script PASS

Animation

Clip selection. RealityKit surfaces one authored SkelAnimation as six entries, and availableAnimations.first is the scene animation on the root — it replays the export's baked root transform every loop and never touches the skeleton. Measured, it was picking LiraRoot / global scene animation; it now picks Armature / Anim[0].

Movement gating. With a single walk cycle, looping unconditionally left her treading on the spot at rest. It now runs only while she is covering ground, and the restart watchdog distinguishes a paused clip from a stalled one.

Per-state path. Fox_<State>.usdz sidecars authored against the packaged rig bind per state, with the embedded walk as fallback, so a partial set is safe to ship. The fox is a standard humanoid — 19 of 24 joints use Mixamo names — so clips for that skeleton drop straight in.

Retired clips. The six Lira_* sidecars target the old 25-joint artist armature and share zero joints with the fox. They cannot bind and are covered by a test so it is not rediscovered the hard way. Worth deleting in a follow-up (~4.4MB of bundle).

Validation

• 415 unit tests, 0 failures
• check_lira_usdz_integrity.sh: PASS
• device: installed and confirmed by the operator — the fox renders

New tests measure rather than assert intent: packaged height (0.72m) and ground contact, animation inventory, clip selection, material preservation, bounds stability during playback, stale-anchor removal, and the rig-incompatibility record.

Not addressed

Per-state fox clips do not exist yet, so every state currently shows the walk cycle. Physical-device tracking, battery and thermal behaviour remain NOT_COMPUTABLE pending the device protocol.

🤖 Generated with Claude Code

[prabu-openclaw]

Blocks the TestFlight cut — filed as #247.

TESTFLIGHT_RC_CHECKLIST.md currently lists 0.9.0 (2) on main as Ready to archive, but that build renders the procedural placeholder for the whole session rather than the packaged companion. Both bugs this PR fixes are present there, and the diagnostics on that tip read healthy (animated_usdz … anim=PLAYING … ok_present) while the wrong thing is on screen — which is why it went unnoticed across several device sessions.

Suggested order: land this, re-run make validate (code has moved past the Phase A receipt SHA), then re-cut from the new tip or bump to build 3.

On AR_MVP_FREEZE.md (FROZEN_FOR_ENGINEERING): this stays inside the frozen envelope — still packaged Lira_AR_Base.usdz through LiraARAssetLoader with procedural fallback, no new AR surfaces or commands. It reads as maintenance rather than feature creep, but flagging so you can confirm rather than have me assume.