Sharpa Avatar plugin — agent notes

CRITICAL: Before editing this tree, read this file and the repo root AGENTS.md.

• Keep the Avatar SDK external. install_avatar_sdk.sh installs the official package under /opt/avatar-sdk; the build consumes the selected SDK root in place (-DAVATAR_SDK_ROOT > $AVATAR_SDK_ROOT > /opt/avatar-sdk). Do not copy, patch, or package SDK files.
• Install the pinned production avatar-sdk package from the signed production channel, and never substitute -dev or -beta. Do not parse or duplicate production_version: CMake calls install_avatar_sdk.sh --check, which holds the default root to the full pin (layout, BUILD_TYPE=Production, dpkg package version) and layout-checks a custom root, where a non-production build only warns. Do not pin VERSION= from share/Version; the dpkg package version is authoritative.
• Linux only. BUILD_PLUGIN_SHARPA_AVATAR=ON with no usable SDK under the selected root skips this plugin; it must not FATAL_ERROR the rest of the tree. The SDK check runs only after that layout is present.
• After rebasing, verify the root option is still gated through src/plugins/CMakeLists.txt; defining the option alone does not create the avatar_hand_plugin target.
• APT signing keys: require the pinned fingerprints to be present. Do not demand exact set equality (extra fingerprints from key rotation are allowed).
• Keep installer responsibilities separate: SDK/APT in install_avatar_sdk.sh, host device permissions in install_udev_rules.sh, and plugin build/install through the repository's top-level CMake workflow.
• Installers must not delete files derived from a configured install prefix.
• Do not mutate loader environment variables or SDK configuration at runtime. Runtime paths come from the selected SDK root and its sdk_config.json.
• Carry Avatar SDK enums such as DeviceSide and DeviceDataCategory through plugin internals; convert only at an existing external API boundary.
• Adapt this plugin to shared APIs; do not refactor other plugins or shared modules solely to change this plugin's internal representation.
• Keep shared enum iteration tables in one scope; a public kDeviceSides or category table must not have a same-named private duplicate.
• Use plugin_utils::WristPoseSource for world-space wrist placement. Do not copy the Manus/XDev/controller fallback implementation into this plugin. When that query is invalid (no headset optical pose and no controller), still inject HUMAN at identity with VALID-only flags; do not skip HandInjector::push. HandsSource/live_view otherwise stay empty.
• OpenXR setup is required for publication; initialization errors must abort construction instead of leaving an Avatar-only idle plugin.
• Keep initialization non-blocking; update() owns retries for absent gloves.
• In manual haptic freshness tests that suspend the Python producer, record its process group, resume it before cleanup, and terminate the producer/plugin group together; do not rely on repeated terminal interrupts for cleanup.
• In pinned SDK 1.7.3, get_device() returns an initialized handle; do not call init() again. Use its lightweight ingress callback for liveness and keep SDK work off the callback thread. Scope callback signals to one device generation; callbacks must not retain a GloveState address across reset or destruction.
• USB transport health combines physical enumeration with AvatarSDK::get_usb_connection_state(): the production SDK can retain CONNECTED while its serial listener is reconnecting, so neither signal is sufficient alone. Before stopping a glove handle, best-effort clear manual haptics. Isolate dynamic output setup failures to that side and retry without terminating the plugin.
• Bound pending haptic commands by source observation freshness and discard them while a glove is unready. Delivery retries may retain only commands the source keeps refreshing; a cached command must never replay after reconnection.
• Treat a successful list_device_info() result as the handle-lifecycle authority: retain handles while their row exists (including online=false), and release them only when a successful snapshot drops the row. A failed refresh makes inventory health unknown and must not reconcile cached rows.
• Keep transport presence, physical-glove ingress/faults, and HUMAN/RAW/ROBOT output freshness/errors as separate health layers. One advancing dataset must not keep another dataset healthy.
• Validate every emitted health state/reason pair through the Python status reducer; producer-only tests do not protect the cross-language monitoring contract.
• Keep the static HUMAN-to-OpenXR index table synchronized with the pinned production SDK's landmark order. Do not read joint names from sdk_config.json at runtime or fill unsupported OpenXR slots with neighbouring poses. Refresh that table and the example's RAW/ROBOT name snapshots together with the package pin.
• When reconciling the maintained feature branch, use it as the baseline and retain local divergence only for an explicit API or correctness requirement.
• Keep this plugin tree C++-only (core/ + app/). The TeleopSession sample lives at examples/sharpa_avatar/ (live_view.py) and runs as python -m isaaccapture_examples.sharpa_avatar. Do not put Python samples under src/plugins/sharpa_avatar/, and do not add SDK-only diagnostic printers that bypass Isaac Capture.