--- id: PLN-0145 ticket: foreground-stack-game-pause-shell-vm-backed title: Centralize Resident Game Resume Transition status: done created: 2026-07-04 ref_decisions: [DEC-0037] tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture] --- ## Briefing `DEC-0037` requires returning to the same resident Game to reactivate the Game VM, restore render ownership, send a resume/foreground lifecycle notification, and clear or barrier pending Game input. That transition currently exists in more than one firmware path: `Firmware::resume_resident_game_from_home` and the Hub library click path that resumes the selected resident Game by `app_id`. The behavior is correct, but the duplication is fragile. Any future change to resume ordering, input barriers, render ownership, or lifecycle event delivery could fix one path while leaving the other path stale. ## Objective Create one firmware-owned resident Game resume helper and route every Home/Hub-to-Game resume path through it. ## Dependencies - Source decision: `DEC-0037`. - Depends on the accepted v1 identity rule that `app_id` is unique for all games and may be used to decide whether a Hub game selection refers to the current resident Game. - Should preserve the behavior introduced by `PLN-0142`, `PLN-0143`, and `PLN-0144`. ## Scope Included: - Centralize resident Game resume orchestration in `Firmware`. - Preserve resume lifecycle event queuing through `LifecycleFacade::resume_task`. - Preserve render ownership transition back to `AppMode::Game`. - Preserve input barrier behavior across all Home/Hub-to-Game resume paths. - Preserve the Hub rule that selecting the same resident Game resumes it, while selecting a different Game remains blocked by v1 scope. - Keep tests proving same-task resume, lifecycle event delivery, and input barriering. Excluded: - No Game-to-Game switching. - No multiple resident Games. - No change to `app_id` uniqueness policy. - No direct Shell-to-Game close behavior. ## Non-Goals - Do not move foreground authority from SystemOS into firmware. - Do not change pause budget or suspend behavior. - Do not add UI affordances beyond the existing Hub game row selection. ## Execution Method 1. Introduce a single resident Game resume helper. - What changes: create a private firmware method that performs the complete resident Game resume operation and returns the target `TaskId` or a typed failure. - How it changes: move the shared sequence currently duplicated across `resume_resident_game_from_home` and `HubHomeStep`: read resident task, call `LifecycleFacade::resume_task`, transition VM render ownership to `AppMode::Game`, install `GameRunningStep`, clear state initialization, and arm the input barrier. - File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`. 2. Route explicit resume through the helper. - What changes: `Firmware::resume_resident_game_from_home` becomes a thin wrapper around the centralized helper. - How it changes: preserve its public `bool` return contract for existing tests and call sites. - File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`. 3. Route Hub same-game selection through the helper. - What changes: `HubHomeStep` must no longer hand-roll resume task, render ownership, and input clearing. - How it changes: expose a state transition request that lets the firmware perform the centralized helper, or restructure the Hub action handling so the parent `Firmware` owns this transition. Keep `HubHomeStep` responsible only for recognizing that the selected cartridge matches the resident `app_id`. - File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_state.rs` if a new transition variant is needed. 4. Keep different-game launch blocked under v1. - What changes: selecting a different `app_id` while a resident Game exists continues to log and remain in Hub. - How it changes: keep the existing warning behavior, but ensure it does not duplicate resume side effects. - File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`. 5. Update regression tests. - What changes: tests should prove both explicit resume and Hub same-game selection use the same observable transition. - How it changes: assert same `TaskId`, foreground owner restored to Game, pending resume lifecycle event exists before the next Game tick, delivered resume event after the Game tick, and input barrier suppresses held input. - File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`. ## Acceptance Criteria - [ ] There is exactly one implementation of the resident Game resume sequence. - [ ] `Firmware::resume_resident_game_from_home` preserves its external behavior. - [ ] Hub selection of the same resident Game resumes the existing `TaskId` without creating or loading a new Game task. - [ ] The resume path always queues and delivers the Game lifecycle `ResumeForeground` event. - [ ] The resume path always barriers held Game input. - [ ] Selecting a different Game while one Game is resident remains blocked in v1. ## Tests - Unit/integration tests in `prometeu-firmware` for explicit resume from Home. - Unit/integration tests in `prometeu-firmware` for Hub same-game selection after Home suspension. - Regression assertion that held input does not leak into the Game immediately after resume. - Run `cargo test -p prometeu-firmware resident_game_resume`. - Run `cargo test -p prometeu-firmware hub_home_clicking_resident_game`. - Run `cargo test -p prometeu-system`. - Run `discussion validate`. ## Affected Artifacts - `crates/console/prometeu-firmware/src/firmware/firmware.rs` - `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` - `crates/console/prometeu-firmware/src/firmware/firmware_state.rs` ## Risks - The current step/state architecture gives `HubHomeStep` a `PrometeuContext` but not direct access to private `Firmware` fields. If a new transition variant is introduced, it must stay narrow and must not turn state steps into owners of lifecycle authority. - Duplicating less logic must not accidentally weaken the input barrier that was added for Hub-to-Game transitions.