---
id: PLN-0155
ticket: foreground-stack-game-pause-shell-vm-backed
title: Retire Legacy Firmware VM Runtime Bridge
status: open
created: 2026-07-05
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

DEC-0038 states that `Firmware.vm` must not remain the canonical owner of VM-backed app context. PLN-0148 through PLN-0152 moved normal cartridge loading and ticking toward VM sessions, but a transitional legacy bridge still initializes and exposes the old global VM/runtime path for compatibility.

## Objective

Remove the legacy firmware VM/runtime bridge from normal runtime architecture. After this plan, VM-backed app execution, initialization, active runtime queries, and host-facing inspection must resolve through VM sessions or explicitly global render/runtime services.

## Dependencies

- Source decision: DEC-0038.
- Requires PLN-0154 so debugger operations no longer depend on `firmware.vm`.
- Builds on PLN-0148 through PLN-0153.

## Scope

- Remove `Firmware.vm` from `crates/console/prometeu-firmware/src/firmware/firmware.rs` if all callsites have migrated.
- Remove `PrometeuContext.vm` from `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`.
- Remove `legacy_vm` from `SessionsFacade::load_vm_cartridge`.
- Remove `initialize_legacy_active_vm`.
- Remove or narrow global `VmFacade::initialize`, `tick`, `reset`, and `debug_step_instruction` methods that operate on caller-supplied `VirtualMachine`.
- Keep global render ownership, render worker lifecycle, telemetry publication, and log service where they are global SystemOS responsibilities.
- Preserve Hub/Home rendering behavior while avoiding any guest VM state stored in firmware.
- Update direct boot, debug boot, reset, and load-cartridge tests to prove session ownership is the only app VM path.

## Non-Goals

- Do not remove `VirtualMachineRuntime` itself.
- Do not redesign render worker ownership.
- Do not add background execution.
- Do not change debugger protocol shape beyond the PLN-0154 migration.

## Execution Method

1. Use `rg` to list every remaining `firmware.vm`, `ctx.vm`, `legacy_vm`, and `os.vm().initialize/tick/reset/debug_step_instruction` callsite.
2. Replace firmware context construction so state steps receive `SystemOS`, Hub, signals, platform, and boot target only.
3. Replace reset behavior with session registry/runtime reset semantics:
   - clear VM sessions on firmware reset when booting fresh;
   - preserve only explicitly resident sessions during lifecycle flows, not reset.
4. Update cartridge loading to initialize only the selected VM session.
5. Split `VmFacade` into:
   - session-targeted VM execution/inspection methods;
   - global render/runtime authority methods.
6. Delete compatibility methods that accept `&mut VirtualMachine` when no remaining production callsite exists.
7. Add tests or assertions proving no production code path initializes or ticks a global firmware VM.
8. Run full affected test suites and clippy.

## Acceptance Criteria

- `Firmware` no longer owns `pub vm: VirtualMachine`.
- `PrometeuContext` no longer carries a VM reference.
- `LoadCartridgeStep` initializes only session-owned VM context.
- `GameRunningStep` and VM-backed `ShellRunningStep` tick only sessions.
- Debugger, stats, and host runner access active session state or global render services explicitly.
- `rg "firmware\\.vm|ctx\\.vm|legacy_vm|os\\.vm\\(\\)\\.initialize\\(|os\\.vm\\(\\)\\.tick\\("` finds no production runtime dependency on the legacy global VM path.
- Tests continue to prove Game resident + VM Shell coexistence.

## Tests

- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-host-desktop-winit`
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
- Add or update tests for:
  - reset clears session-owned VM contexts appropriately;
  - direct boot creates session-owned VM context;
  - debug boot uses session-owned VM context;
  - no global VM tick path remains.

## Affected Artifacts

- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_*.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`