feat: post_event/attach_control queue for thread-safe session control

[abhichothani42]

Summary

SessionControlCapable sources (VR buttons, keyboard, future foot pedals, …) each run on their own thread and fire callbacks from that thread. But SessionManager's episode methods (start_episode, stop_episode, discard_*, shutdown) are single-threaded. Previously the VR demos called stop_episode() directly from the VR reader thread, racing the main loop that owns the session.

This PR adds a thread-safe event queue so a control source can only post an intent; SessionManager drains it and mutates the session only on the orchestrating thread.

Changes

• Add SessionManager::post_event(SessionControlEvent) — thread-safe enqueue, callable from any thread; never touches session state.
• Add SessionManager::attach_control(SessionControlCapable&) — installs post-event callbacks, starts the source, and remembers it so shutdown() stops (joins) it before teardown.
• Add private drain_control_events(ControlPhase) — applies queued events on the main thread, phase-aware: kStart advances + skips reset while recording / resumes while resetting; kStopEarly stops the episode; kRerecord; kStopSession and disconnect end the session.
• Drain the queue inside monitor_episode() and wait_for_reset(); shutdown() stops attached sources first so no queued event can drive a session being torn down.
• Add test_session_manager_control.cpp (11 tests): queue behavior, attach/shutdown lifecycle, phase-aware mapping, and disconnect-fires-once through attach_control.

Test Plan

• Builds cleanly (make build)
• Tests pass (make test)
• Lint passes (pre-commit run --all-files)
• Tested on hardware (if applicable)

Breaking Changes

None. The new API is additive. With no attached control sources the queue stays empty, so existing keyboard-only demos (monitor_episode/wait_for_reset) behave exactly as before.

Related Issues

[abhichothani42]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• scripts: add Foxglove user scripts for robot and EEF visualization #277
• scripts: add URDF extraction tool for TrossenMCAP recordings #276
• examples: enable robot description recording in solo demo #275
• backend: write robot description to TrossenMCAP files #274
• config: add robot description options to TrossenMCAP backend #273
• utils: add RobotDescriptionCache for URDF download and mesh embedding #272
• examples: update sanity check for end-effector pose #270
• arm: emit end-effector pose from TrossenArmProducer #269
• backend: add end-effector pose write support to TrossenMCAP #268
• arm: add EndEffectorPoseRecord and proto schema #267
• examples: add trossen_vr_mobile demo #266
• examples: add trossen_vr_stationary demo #265
• examples: add trossen_vr_solo demo #264
• vr: add VrSessionControlComponent button-to-session bridge #263
• vr: add VrBaseComponent base-velocity teleop leader #262
• vr: add VrArmComponent cartesian teleop leader #261
• vr: add shared VrSession connection owner #260
• feat: post_event/attach_control queue for thread-safe session control #271 👈 (View in Graphite)
• session-control: add SessionControlCapable interface #259
• hw: make SlateBaseComponent a base-velocity teleop follower #258
• teleop: add base-velocity (Base) space to teleop interface #257
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

This PR introduces a thread-safe “session control” event queue in SessionManager so that push-based control sources (VR buttons, etc.) can post intents from their own threads while the session state continues to be mutated only from the orchestrating loop.

Changes:

• Added SessionManager::post_event() (thread-safe enqueue) and SessionManager::attach_control() (installs callbacks, starts/stops sources via shutdown).
• Implemented phase-aware draining of queued control events from monitor_episode() and wait_for_reset().
• Added a new unit test suite (test_session_manager_control) and wired it into the test build.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/runtime/session_manager.cpp	Implements control-source lifecycle shutdown, event enqueueing, and phase-aware draining in episode/reset loops.
include/trossen_sdk/runtime/session_manager.hpp	Exposes the new public APIs and adds private queue/flags used by control-event draining.
tests/test_session_manager_control.cpp	Adds unit coverage for queueing/draining behavior and attach/shutdown lifecycle.
tests/CMakeLists.txt	Builds and registers the new test binary with CTest.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shantanuparab-tr]

Can we have a shared_ptr here as we already have those for all hardware components. A raw pointer has the exact problems as mentioned in the note. Using shared pointer would gaurantee that the source outlives the session manager.

[abhichothani42]

dead938
Done. attach_control now takes std::shared_ptr and the manager holds it in control_sources_, so the source is guaranteed to outlive the manager's use of it.