fix: claim/start must park head at home before orient stream begins

[SlyWombat]

Summary

When /api/mover-control/start transitions a claim to state=streaming, the head should be parked at home (Home anchor) before any subsequent orient updates can land. Currently /start only sets dimmer + colour and starts the engine pump; the head stays at whatever wire DMX was previously on.

Why this matters

/api/mover-control/calibrate-end captures _mover_current_aim_stage(mover) — the head's current stage-frame aim — and uses that as the reference direction the phone's current pose is anchored to. If the head was at a stale pose at calibrate-time (because /start didn't park it), the operator's phone-pose-now is locked to that stale stage direction. Subsequent orient packets are anchored against the wrong reference, and the head appears to "jump" on calibrate-release because the new lock doesn't match where the operator expected the reference to be.

Symptom in the wild: today's Android live-test on fid 17 (2026-05-03) — claim+start brought the head to pan16=53376, tilt16=6272 (a stale aim from a previous test, ≈ stage az=-74°), then calibrate-end-with-phone-steady locked the phone to that stale pose, then the very next orient update moved the head to a "different" pose because the operator was holding the phone where they thought "stage forward" was — but the lock was anchored to az=-74° instead of home. That's the visible "jumped to stage -90X after calibrate" symptom.

Fix

In /api/mover-control/start (or MoverControlEngine.start_streaming), after the claim transitions to state=streaming:

1. Compute the head's home aim DMX via AimSphere.aim_direction(home_az, home_el) for the fixture (uses the new sphere; honours rotation + Home + Secondary).
2. Write that pose to the universe buffer for the fixture's pan/tilt channels.
3. Wait for the engine to settle (or skip the wait — engine pump will catch up within a frame or two).
4. Only then accept incoming orient packets.

Equivalently: the engine's tick loop, when it sees a claim that's state=streaming but calibrated=false, drives the head to home as the streaming reference. Calibrate-end then locks the phone to that home pose. First orient update post-release uses home as the stable reference.

Acceptance

1. fid 17 cold-claim + /start from Android (no calibrate yet): head physically moves to home position (panDmx16=44364, tiltDmx16=0). Wire confirms the writes.
2. Hold phone steady through calibrate-hold + release. After calibrate-end, aim_stage reported by the orchestrator is approximately (0, 1, 0) (stage forward) — i.e., maps to the head's current stage aim, which is now home.
3. Subsequent steady-phone orient packets keep aim_stage ≈ (0, 1, 0) — head stays at home.
4. Tilt phone +20° forward (gesture) → head physically tilts toward floor by ~20° (assuming rotation=[0,0,0] and operator's expected stage convention). No "jump."
5. Same test on fid 14 (rotation [-75, 0, 0]): claim+start parks head at fid 14's home pose (32269, 28298), which is at stage (az=0, el=+75). Calibrate locks phone to that pose. Steady phone keeps head there.

Related

• SPA/Android: orientation indicator drifts independently of physical mover after calibrate #757 (orientation indicator drifts after calibrate) — direct symptom of this; closes when this lands plus Issues A + B from the SPA/Android: orientation indicator drifts independently of physical mover after calibrate #757 diagnostic comment.
• Android mover-control: calibrate-release pan jumps on angular_only fixture (regression of #510 for no-SMART path; spec violation per #738) #748 (calibrate-release pan jumps on angular_only) — same root cause; closes with this fix.
• Android mover-control: 'level' indicator dot never centres at calibrated reference pose (likely #748 side-effect) #750 (level indicator dot never centres) — likely transitively closes since the level indicator presumably tracks aim_stage magnitude.
• feat: rewrite moving-head aim/cal from scratch — new aim/ package, no legacy imports (supersedes #780, #783) #784 PR-5 (mover_control rewire) — already landed; this issue builds on it. The new sphere has the right math, but the claim/start lifecycle wasn't updated to park-on-start.
• CLAUDE.md ## Angular-aim convention (#783) — the stage convention the parked aim must respect.

Out of scope

• The hardcoded REMOTE_FORWARD_LOCAL = (1, 0, 0) (Issue A from SPA/Android: orientation indicator drifts independently of physical mover after calibrate #757 diagnostic) — separate work.
• _mover_current_aim_stage legacy IK paths (Issue B from SPA/Android: orientation indicator drifts independently of physical mover after calibrate #757 diagnostic) — separate work; should land alongside this for cleanest test, but isn't strictly required for this fix's acceptance.

[SlyWombat]

Scope extension — park at home applies to ALL idle / no-active-claim states

Live observation 2026-05-03: with no active claim on any fixture, the engine pump freezes at the last-aim DMX rather than idling at home. Confirmed on fid 17 + fid 14 just now:

no active claims
fid 17 wire: pan16=53376 tilt16=6272   (home 44364/0)    — off ~74° pan
fid 14 wire: pan16=35264 tilt16=2026   (home 32269/28298) — off ~25° pan, ~85° tilt

Operator expectation: when no one is actively driving the fixture (claim released, orchestrator idle, fixture hardware power-cycle), the head returns to home. Currently it sticks at whatever was last written.

Extended scope

This issue's fix should cover all four moments:

1. ** (claim transition to streaming)** — original scope. Park at home before orient stream begins.
2. Claim released ( or claim TTL expires) — park at home.
3. Orchestrator cold start (server reboot) — write home DMX to all calibrated movers as the initial universe state, instead of letting the universe default to zero or whatever the saved snapshot was.
4. Fixture hardware power-cycle — handled implicitly by (3) if the engine is already running and writing home; the fixture firmware will settle to whatever DMX is on the wire.

Same canonical helper covers all four — the existing go_home(fid) in aim/park.py (already used by blackout/abort paths per #782 PR-β). For (1), the engine's claim-state-transition logic calls it before allowing orient. For (2), it fires on release. For (3), fixture loader walks calibrated movers and calls go_home(fid) once per fixture as part of orchestrator startup.

Acceptance — append to existing acceptance

6. Claim release: POST /api/mover-control/release for fid 17 → wire moves to (44364, 0) within 500 ms. fid 14 → (32269, 28298).
7. Cold-start parking: orchestrator restart with no active claims → all calibrated mover fixtures (fid 14, fid 17, fid 19, etc.) end up at their respective Home DMX within ~2 s of engine ready. Wire trace shows the home writes, not zero/stale values.
8. Fixture power-cycle on warm orchestrator: fixture hardware reboot while orchestrator is running → fixture settles to its home pose (because orchestrator is continuously writing home DMX as the idle state).

Operator confirmed this behaviour applies to ALL remotes / fixtures consistently — phone, gyro puck, future remotes — not just one device type. Same coordinate system + same idle behaviour across the board.

[SlyWombat]

Idle definition refinement (operator, 2026-05-03)

Spec for what triggers "head returns to home" — event-driven, NOT timeout-driven.

Trigger events (head snaps to home + lamp policy):

1. Cold start — orchestrator boots → engine pump writes home DMX to every calibrated mover as initial state. Plus a blink: briefly turn each mover's lamp on, then off, to signal "this fixture is ready and parked at home." Visual feedback for the operator at session start. Implementation: home write → wait for settle (~500 ms) → lamp_on → ~300 ms → lamp_off. Once per cold start, never repeated.
2. Claim explicitly released — POST /api/mover-control/release or claim TTL expires. Head snaps to home; lamp turns off (per existing lamp_off on release).
3. Timeline / show ends — last cue of the running show completes with no loop and no follow-up cue. Head snaps to home; lamp follows the cue's last intensity transition (timeline owns lamp behaviour at its boundaries).
4. Track action terminates — track explicitly stops (operator stopped it, or persistent-loss timer fires per the existing track loss-UX). Head snaps to home; lamp follows track's loss policy.

NOT idle triggers (head stays at last writer's pose):

• One-shot POST /api/mover/<fid>/aim followed by silence. Operator scripted "aim at marker 3" and walked away. Head stays at marker 3 indefinitely — last expressed intent was "be there," no release event ever fires.
• DMX test surfaces (/api/fixtures/<fid>/dmx-test, group control sliders, the SPA's raw-DMX UIs). Operator may have intentionally parked the head somewhere via raw DMX manipulation. Don't snap to home just because the operator stopped touching the sliders.
• Brief gaps within an active timeline / track / claim — held by the active writer, not idle.
• Transient orient-packet drop or network blip during an active claim — claim still owns the fixture; held at last claim pose.

Net acceptance (replaces / extends existing acceptance bullets):

1-4 unchanged from issue body.
5. Wire trace at orchestrator cold start shows: write home DMX → settle → lamp on → ~300 ms → lamp off, per calibrated mover, in parallel.
6. After /release for fid 17, wire snaps to (44364, 0). For fid 14, snaps to (32269, 28298).
7. After timeline ends, wire snaps to home for every mover that timeline was driving.
8. No timeout-based idle: leave a fixture at a non-home pose via /aim and walk away — wire stays at that pose for hours. Hard test: 30-minute idle after a one-shot /aim with the orchestrator running but no other activity. Wire pose unchanged.
9. No timeout-based idle from DMX test page: operator drives head via dmx-test sliders, closes the page. Wire stays at that pose.

[SlyWombat]

Cold-start blink correction

Operator confirms there's an existing cold-start blink routine that does a rainbow colour cycle as the "fixture ready" signal. Do not override it. The cold-start additions in #800 are park-at-home only; the existing rainbow blink stays in place and runs after / alongside the home write.

Revised cold-start sequence:

1. Orchestrator boots, engine pump comes up.
2. Engine writes home DMX to every calibrated mover (the new behaviour from fix: claim/start must park head at home before orient stream begins #800).
3. Existing cold-start blink routine runs as it does today (rainbow colour cycle on each mover's lamp). No changes to that routine.
4. After the existing blink completes, fixtures sit at home with lamp off (or whatever the existing blink's terminating state is).

Implementation: the home-write step in this issue lives in the engine's startup sequence, BEFORE the existing blink routine fires. The blink routine continues to operate on whatever fixtures are present without caring whether they were just parked. No changes to the blink code; only adds a home-write step that runs before it.

Acceptance bullet 5 from the previous comment is updated:

Wire trace at orchestrator cold start shows: home DMX written to every calibrated mover ~immediately after engine ready → existing rainbow-blink routine runs as today → fixtures end at home + (existing blink's terminal state).

The earlier suggestion of "home write → settle → lamp_on → lamp_off" as a fresh blink is dropped. The codebase already has its blink behaviour.

[SlyWombat]

Cold-start park-at-home VERIFIED 2026-05-04

Live-test on basement rig: orchestrator booted, no active claims. Wire trace shows both fid 17 and fid 14 at home immediately:

fid 17: pan16=44364 tilt16=0      (= home exactly)
fid 14: pan16=32269 tilt16=28298  (= home exactly)

Lamps off, claims=[]. Cold-start handler from this issue is working as specified for these two fixtures.

Other lifecycle moments (claim release, timeline end, track terminate) not yet verified live; can verify when the next cycle naturally exercises them. Recommend keeping this issue OPEN until claim-release park is observed end-to-end on a fresh build.

[SlyWombat]

Status — code-complete; awaiting live-test verification.

Per the operator's #800-comment-1 idle-trigger spec, all four lifecycle moments are wired in code as of v1.7.41 (commits aff8691 + aa73a28 + 64c30bf):

Trigger	Code	Status
Cold-start parking	_cold_start_park_when_engine_ready daemon thread + _park_fixture_pan_tilt_only (no lamp_off — preserves the existing rainbow-blink terminal state per #800-comment-2)	✓ verified live 2026-05-04
Claim release / TTL expiry	MoverControlEngine.release calls park_fn (full park + lamp_off) so idle = home + dark	code-shipped, needs live verify
Timeline / show ends	_dmx_playback_loop end-of-loop snaps movers (with Home + Secondary captured) to home + lamp off via _park_fixture_at_home; non-mover DMX fixtures keep the legacy zero-channel blackout	code-shipped, needs live verify
Track action terminates	Transitively covered when the timeline that contains the track stops (track-end via timeline-stop). Per-frame dim-only behaviour for unassigned heads is preserved per the "event-driven, not timeout-driven" principle.	code-shipped, needs live verify
Fixture power-cycle	Implicit — engine pump continuously holds Home DMX in the universe buffer for any fixture without an active claim; firmware settles to whatever is on the wire when it boots.	code-shipped, needs live verify on a power-cycled gyro/mover

NOT triggers (preserved per the spec — head stays at last writer's pose):

• One-shot POST /api/mover/<fid>/aim then silence — no auto-park.
• DMX-test sliders / raw-DMX surfaces — no auto-park.
• Brief gaps within an active timeline / track / claim — held by the active writer.
• Transient orient-packet drops during an active claim — claim still owns the fixture.

Verify-and-close checklist (operator-side, on a fresh v1.7.41 dist):

1. Claim a mover, drive it off-home via orient packets, press Release. Wire snaps to home + lamp off within ~500 ms.
2. Start a timeline that drives a mover; let it complete. Wire snaps to home + lamp off.
3. Power-cycle a calibrated mover with the orchestrator running; it returns to home post-boot.

Once those three are confirmed in a live session, this issue closes. Code itself is not expected to need further changes.