---
id: PLN-0139
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game Home Shell Game End To End
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, validation, firmware, host, lifecycle]
---

## Briefing

`DEC-0037` is not complete until the product flow is proven end to end:
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
Game can resume only after a valid current-epoch frame exists.

This plan adds final validation after the spec, SystemOS, VM, host input, and
render/audio/input boundary plans are implemented.

## Decisions of Origin

- `DEC-0037` - Foreground Stack and Game Pause Contract.

## Target

Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
regressions around guest input, foreground authority, and stale rendering.

## Scope

- Add integration-style tests for:
  - Game running to Home request;
  - pause notification and forced suspension;
  - Hub foreground while Game is resident;
  - VM-backed Shell foreground while Game is suspended;
  - Shell close returning to Hub;
  - resume request returning to same Game;
  - first-valid-frame visual restore;
  - host `Esc`/`Home` not entering guest input.
- Add manual smoke instructions for desktop host.
- Confirm direct `--run` and games-root Home launch remain separate.

## Out of Scope

- No new implementation beyond tests and developer-facing validation notes.
- No Game A -> Home -> Game B switching.
- No performance tuning.
- No polished UI.

## Execution Plan

1. Add firmware/SystemOS integration tests.
   Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
   and `crates/console/prometeu-system` tests to drive Game foreground, Home
   request, Shell foreground, Shell close, and Game resume.

2. Add host input integration tests.
   Ensure `Esc` and physical `Home` create a host Home event and do not mutate
   guest `InputSignals`.

3. Add render publication validation.
   Assert stale submissions from the pre-pause Game epoch are rejected after
   Home takes foreground and that the Game is not visually restored until a new
   current-epoch submission exists.

4. Add audio/input boundary validation.
   Assert Game input is cleared or barriered across pause/resume. Assert Game
   audio pause follows Game suspension.

5. Add direct boot and games-root regression checks.
   Ensure direct `--run <cart>` remains independent from Home request handling
   and that games-root Home launch still enters the Game path.

6. Document manual smoke commands.
   Add or update developer-facing spec text with release-mode commands:
   - `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
   - `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
   Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
   once implemented.

## Acceptance Criteria

- Automated tests cover `Game -> Home -> same Game`.
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
- Tests prove Home request is host/SystemOS control, not guest pad input.
- Tests prove suspended Game does not tick.
- Tests prove stale render submissions are not presented.
- Tests prove visual return waits for a current-epoch Game frame.
- Direct `--run` and games-root Home launch regressions pass.

## Tests / Validation

- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-host-desktop-winit`.
- Run any targeted render worker tests affected by ownership epoch changes.
- Run `discussion validate`.

## Risks

- The current test seams may not expose enough host-driven lifecycle behavior.
  If needed, add narrow test-only helpers rather than testing through sleeps or
  real-time window loops.
- End-to-end validation can become flaky if it depends on wall-clock timing.
  Use deterministic ticks and explicit state transitions.