---
id: PLN-0150
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Cartridge Loading Through VM Sessions
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current `LoadCartridgeStep` initializes `ctx.os.vm().initialize(ctx.vm, &cartridge)` before task/session ownership is selected.

This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.

## Objective

Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.

## Dependencies

- Source decision: DEC-0038.
- Requires PLN-0148.
- Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
- Must precede the end-to-end coexistence validation in PLN-0152.

## Scope

- Replace direct global VM initialization in `LoadCartridgeStep`.
- Add a session/facade operation that:
  - selects an existing resident Game session when the same `app_id` is relaunched;
  - rejects or reports different resident Game launches under V1;
  - creates a new VM Shell session for a Shell cartridge;
  - initializes the cartridge inside the selected session VM.
- Keep asset manager initialization aligned with the foreground cartridge being launched.
- Ensure `AppCrashesStep` receives initialization failures from the target session.
- Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.

## Non-Goals

- Do not implement multiple resident Games.
- Do not implement background execution.
- Do not redesign cartridge format or asset packaging.
- Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.

## Execution Method

1. Add a `load_vm_cartridge` or equivalent method to `SessionsFacade` or `VmFacade`.
2. Make the method return an execution target:
   - existing Game task for same resident `app_id`;
   - new Game task for first Game launch;
   - new VM Shell task for Shell launch;
   - structured error/crash report for invalid VM initialization;
   - explicit lifecycle error for blocked second Game.
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` to call the facade method instead of initializing `ctx.vm`.
4. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` so same-Game relaunch checks session/lifecycle state rather than `ctx.os.vm().current_app_id()`.
5. Preserve AppMode-based transition:
   - Game target transitions to `GameRunning`;
   - Shell target creates/focuses a window and transitions to `ShellRunning`.
6. Adapt crash tests and resident-game relaunch tests in firmware.

## Acceptance Criteria

- `LoadCartridgeStep` no longer initializes a global firmware VM.
- Loading a Shell cartridge creates/initializes a Shell VM session.
- Loading the first Game cartridge creates/initializes the resident Game VM session.
- Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
- Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
- VM initialization failure still transitions to `AppCrashesStep`.

## Tests

- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- Add or update firmware tests for:
  - first Game load creates one session and enters `GameRunning`;
  - same Game relaunch resumes existing task/session;
  - VM Shell load creates a distinct session;
  - Shell load does not change resident Game session app identity;
  - invalid cartridge reports `CrashReport::VmInit`.

## Affected Artifacts

- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- VM session module introduced by PLN-0148