---
id: PLN-0154
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Debugger Operations Through VM Sessions
status: open
created: 2026-07-05
ref_decisions: [DEC-0038]
tags: [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