fix(so_follower): make the kinematics joints guard reachable - #4915

Summary / Motivation

The four kinematics steps in robot_kinematic_processor.py build q_raw from the observation's <motor>.pos keys and then guard it with a condition that can never hold:

q_raw = np.array(
    [float(v) for k, v in observation.items() if isinstance(k, str) and k.endswith(".pos")],
    dtype=float,
)
if q_raw is None:          # np.array(...) is never None
    raise ValueError("Joints observation is require for computing robot kinematics")

So an observation carrying no joint keys reaches the body. Reproduced on main (no hardware):

GripperVelocityToJoint       -> IndexError: index -1 is out of bounds for axis 0 with size 0
InverseKinematicsEEToJoints  -> empty array handed to the solver
InverseKinematicsRLStep      -> empty array handed to the solver
EEReferenceAndDelta          -> empty array handed to FK

GripperVelocityToJoint is the clearest: q_raw[-1] + delta inside np.clip raises an IndexError that mentions neither joints, nor observations, nor which key was missing — while the class documents a ValueError for exactly this case.

That input is reachable rather than hypothetical. compute_forward_kinematics_joints_to_ee pops every <motor>.pos key, so a pipeline that maps the observation to EE space before one of these steps leaves q_raw empty; so does a policy observation keyed observation.state.

There is also a quieter failure: with 5 of 6 joint keys present, GripperVelocityToJoint integrates the wrong joint — q_raw[-1] is now wrist_roll, not gripper — and commands a bogus gripper position with no error at all. This PR does not change that (it depends on the ordering TODO at the same line, which is #4442's territory); it only makes the empty case loud.

Related issues

• Follows fix(so_follower): check the observation for None before copying it #4255, which made the adjacent observation is None guard reachable for precisely the same reason — its test docstring reads "the guard below them was unreachable and an AttributeError escaped instead." This is the same fix shape for the neighbouring condition.
• Related: Support an explicit motor-to-URDF joint mapping in the kinematics pipeline #4442 / feat(kinematics): support per-joint motor-to-URDF sign and offset mapping (#4442) #4788 cover the .pos ordering assumption, deliberately untouched here.

What changed

• A new _assert_joints_present(q_raw, observation) helper raises the documented ValueError when the observation carried no joint positions, and names the keys that were present so the caller can see what it passed.
• All four steps call it in place of the dead if q_raw is None check, rather than repeating the guard inline.
• The helper keeps the is None case too, which EEReferenceAndDelta still needs: there q_raw can legitimately come from complementary_data["IK_solution"].
• The message keeps the "Joints observation" prefix, so the existing fix(so_follower): check the observation for None before copying it #4255 test still matches, and fixes its "is require" typo.

How was this tested (or how to run locally)

New test_observation_without_joint_keys_raises_value_error, parametrised over all four steps, mirroring the existing test_missing_observation_raises_value_error block directly above it. No placo, no robot, no mocks — kinematics=None is enough, because the guard must fire before the solver is touched.

# before
FAILED test_observation_without_joint_keys_raises_value_error[ee_reference_and_delta]
FAILED test_observation_without_joint_keys_raises_value_error[inverse_kinematics_ee_to_joints]
FAILED test_observation_without_joint_keys_raises_value_error[gripper_velocity_to_joint]
FAILED test_observation_without_joint_keys_raises_value_error[inverse_kinematics_rl_step]
4 failed

# after
$ uv run pytest tests/robots/test_robot_kinematic_processor.py -q
10 passed            # 6 pre-existing + 4 new

$ uv run pytest tests/robots tests/teleoperators -q
147 passed, 4 skipped

Quality hooks on the changed files (ruff format, ruff, typos, pyupgrade, bandit, mypy, gitleaks) all pass.

Checklist (required before merge)

• Linting/formatting run (pre-commit run on the changed files — all hooks pass)
• Relevant tests pass locally (tests/robots, tests/teleoperators). Full pytest not run: CPU-only sandbox.
• Documentation updated — not applicable, the exception was already documented
• CI is green — will watch after opening
• Community Review: reviewed fix(motors): disable torque for every serial motor on disconnect #4695 — fix(motors): disable torque for every serial motor on disconnect #4695 (review)

Reviewer notes

• Worth checking: whether any caller today relies on an empty q_raw reaching the solver. I believe not — it produces an IndexError inside RobotKinematics.inverse_kinematics's joint loop anyway — but you would know of any in-flight work that depends on it.
• The error message includes the observation's keys. If you would rather keep exception messages terse, I am happy to drop that.
• The EEReferenceAndDelta case is the one asymmetry in the diff; I kept its is None branch deliberately rather than unifying all four, because IK_solution can genuinely be None there.
• There is a stale open PR (Fix TypeError in Eagle2 text validation and AttributeError in kinematic processor #3037) touching these same functions; it only moves a .copy() and fixes the typo, and does not add an emptiness guard. Flagging it for conflict awareness.

AI assistance disclosure

Per AI_POLICY.md: found and written with AI assistance. I verified it myself: confirmed all four dead q_raw is None checks on main, executed each step with an EE-space observation to capture the actual IndexError/solver failures quoted above, confirmed compute_forward_kinematics_joints_to_ee pops the joint keys, and confirmed EEReferenceAndDelta can receive None from complementary data. Tests were run locally and verified to fail before the fix and pass after.