prometeu-runtime/discussion/workflow/plans/PLN-0154-route-debugger-operations-through-vm-sessions.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0154	foreground-stack-game-pause-shell-vm-backed	Route Debugger Operations Through VM Sessions	open	2026-07-05	DEC-0038	runtime os lifecycle shell game vm foreground architecture

Briefing

DEC-0038 requires VM-backed mutable execution state to be owned by VM sessions. Normal execution now ticks session-owned VMs, but desktop debugger commands still inspect and mutate firmware.vm, the transitional legacy VM. This leaves debugger state, breakpoints, single-step execution, PC snapshots, and stack snapshots inconsistent with the active VM session.

Objective

Route host debugger operations through the active VM session rather than the legacy firmware VM. Debugger pause/resume/step/state/breakpoint operations must target the same VM context that foreground execution ticks.

Dependencies

• Source decision: DEC-0038.
• Builds on PLN-0148 through PLN-0152.
• Should be implemented before PLN-0155 removes the legacy firmware VM bridge.

Scope

• Add session-aware debugger accessors to SystemOS/VmFacade.
• Expose active VM session inspection and mutation operations needed by the debugger:
  • PC;
  • operand stack preview;
  • insert breakpoint;
  • remove breakpoint;
  • list breakpoints;
  • single-instruction debug step;
  • active cartridge identity for handshake and state responses.
• Update crates/host/prometeu-host-desktop-winit/src/debugger.rs so it no longer reads or mutates firmware.vm for active VM state.
• Ensure debugger setup for direct debug boot initializes through normal cartridge/session loading or an explicit session-aware metadata path, not os.vm().initialize(&mut firmware.vm, ...).
• Keep pause/resume/step-frame control mapped to active VM session runtime state.
• Add tests that would fail if debugger state came from the legacy VM while the session VM is active.

Non-Goals

• Do not remove Firmware.vm; that is PLN-0155.
• Do not redesign the debugger protocol.
• Do not add multi-client debugging.
• Do not add background-session debugging beyond active/resident session semantics already supported by DEC-0038.

Execution Method

1. Add focused VmFacade methods for active-session VM inspection:
   • active_pc;
   • active_operand_stack_top;
   • insert_active_breakpoint;
   • remove_active_breakpoint;
   • active_breakpoints_list;
   • debug_step_active_session.
2. Define active-session resolution explicitly:
   • foreground VM session first;
   • resident Game session when Hub has foreground but a resident Game is the active debug target;
   • no legacy fallback for debugger mutation once a session exists.
3. Update HostDebugger::setup_boot_target so debug cartridge metadata is loaded without initializing firmware.vm as canonical state.
4. Update HostDebugger::handle_command for Step, GetState, SetBreakpoint, ListBreakpoints, and ClearBreakpoint.
5. Update HostDebugger::stream_events breakpoint-hit PC reporting to read from the active session.
6. Add tests under crates/host/prometeu-host-desktop-winit/src/debugger.rs proving debugger commands observe and mutate the session VM.
7. Run the host, firmware, and system test suites.

Acceptance Criteria

• Debugger handshake reports cartridge identity from session/runtime state or preloaded metadata, not from a global VM initialized only for debugger setup.
• GetState returns PC and stack data from the active VM session.
• Step advances the active VM session, not firmware.vm.
• Breakpoint commands mutate the active VM session.
• Breakpoint-hit events report the active session PC.
• No debugger command path directly reads or mutates firmware.vm for active VM execution state.
• Existing debugger protocol tests pass.

Tests

• cargo test -p prometeu-host-desktop-winit
• cargo test -p prometeu-firmware
• cargo test -p prometeu-system
• cargo clippy -p prometeu-host-desktop-winit -p prometeu-firmware -p prometeu-system --all-targets -- -D warnings
• Add tests for:
  • GetState reads session VM PC;
  • Step affects session VM;
  • breakpoint insert/list/remove uses session VM;
  • debugger setup does not initialize firmware.vm as the canonical app context.

Affected Artifacts

• crates/host/prometeu-host-desktop-winit/src/debugger.rs
• crates/console/prometeu-system/src/os/facades/vm.rs
• crates/console/prometeu-system/src/services/vm_session.rs
• crates/console/prometeu-firmware/src/firmware/firmware.rs
• Debugger-related tests in host and firmware crates