---
id: PLN-0152
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game and VM Shell Session Coexistence
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

DEC-0038 was motivated by the concrete failure mode where a resident Game is suspended, a Shell is opened, and Game logs or state unexpectedly continue under the wrong foreground owner. After VM sessions and scheduling are implemented, the system needs explicit regression coverage for this workflow.

## Objective

Add end-to-end and integration validation proving a resident Game VM session and a VM-backed Shell session can coexist without overwriting or ticking each other incorrectly.

## Dependencies

- Source decision: DEC-0038.
- Requires PLN-0148, PLN-0149, PLN-0150, and PLN-0151.
- Should be executed before closing the broader DEC-0038 implementation thread.

## Scope

- Add firmware-level regression tests for:
  - Game launch;
  - Home/SystemOS request;
  - Game pause/suspend;
  - VM Shell launch;
  - Shell foreground ticking;
  - Shell exit;
  - Hub return;
  - resident Game resume.
- Add system-level tests for independent session state.
- Add host-level tests only where active VM/debugger/stat routing cannot be covered at firmware/system level.
- Verify logs from the stress cartridge or equivalent test cartridge do not appear while Game is suspended and Shell is foreground.
- Verify Shell logs, frames, or tick counters belong to the Shell session.

## Non-Goals

- Do not introduce new architecture in this plan.
- Do not broaden background execution.
- Do not rewrite Hub UI behavior except where required to exercise the flow.
- Do not depend on manual desktop testing as the only evidence.

## Execution Method

1. Identify or add deterministic test cartridges/helpers that can emit per-session tick/log evidence.
2. Add a firmware integration test for `Game -> Home -> VM Shell -> Hub -> same Game`.
3. Capture Game session counters before Shell launch and after Shell foreground ticks.
4. Assert the Game session counters and lifecycle delivery state remain stable while Shell is foreground.
5. Assert the Shell session counters advance while Shell is foreground.
6. Assert returning to the same Game resumes the same task/session and then advances the Game counter.
7. Add a regression specifically covering the prior symptom: Game `stress` logs must not appear during Shell foreground execution.
8. Run the relevant crate tests and record evidence in the plan completion notes when implemented.

## Acceptance Criteria

- The failing manual scenario is covered by automated tests.
- The Game session is suspended and non-ticking while VM Shell is foreground.
- The VM Shell session ticks independently.
- Returning to Hub and selecting the same Game resumes the resident Game session instead of creating a duplicate process/session.
- No test relies on a single global `current_app_id` to infer correctness.

## Tests

- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-host-desktop-winit` if host active-session plumbing changed.
- Optional manual smoke:
  - run `cargo run --bin prometeu-host-desktop-winit --profile release --manifest-path crates/host/prometeu-host-desktop-winit/Cargo.toml -- --games-root test-cartridges`;
  - open Stress Console;
  - press ESC/Home;
  - open VM-backed Shell;
  - verify no Stress logs appear while Shell is foreground;
  - return and resume Stress Console.

## Affected Artifacts

- `crates/console/prometeu-firmware/src/firmware/firmware.rs` tests
- `crates/console/prometeu-system/src/os/system_os.rs` tests
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs` tests if needed
- `test-cartridges/` only if a deterministic VM Shell fixture is missing