prometeu-runtime/discussion/workflow/plans/PLN-0159-recover-failed-game-switches-back-to-home.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0159	system-os-cartridge-switch-orchestrator	Recover Failed Game Switches Back To Home	open	2026-07-05	DEC-0039	runtime os lifecycle game cartridge architecture

Briefing

DEC-0039 rejects preserving Game A after a switch begins. If Game B fails to load, the system must discard partial Game B state and return to Home/Hub with a diagnostic, not attempt rollback to Game A.

Objective

Implement controlled failed-switch recovery to Home/Hub after destructive Game replacement begins.

Dependencies

• Source decision: DEC-0039.
• Requires PLN-0157 target contract.
• Requires PLN-0158 resident Game termination/session removal.

Scope

• Detect load/init failure while switching to a different Game.
• Discard any partial new Game task/session/window/render/input/audio state.
• Return firmware/SystemOS to Home/Hub.
• Log or expose a diagnostic that Home can surface or tests can assert.
• Ensure previous Game is not restored after switch failure.

Non-Goals

• Do not implement transactional rollback.
• Do not preserve the previous Game after switch begins.
• Do not design final user-facing error UI.
• Do not change direct boot failure behavior unless needed to keep paths separate.

Execution Method

1. Inspect existing load failure flow in crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs.
2. Add a switch-specific failure outcome or context flag that distinguishes SystemOS Game switching from direct boot load.
3. On switch load failure:
   • remove partial new VM session/task/process if created;
   • clear partial cartridge-scoped state;
   • transition to HubHome instead of app crash when appropriate for switch recovery;
   • log a diagnostic containing target identity/path and failure summary.
4. Preserve existing direct boot and explicit load failure tests unless a direct boot path intentionally still goes to crash.
5. Add tests for bad Game B after Game A was already terminated.

Acceptance Criteria

• Failed Game A -> Home -> Broken Game B returns to Home/Hub.
• Previous Game A is not resident, resumable, or restored.
• Partial Game B VM session/task/process state is removed or closed.
• A diagnostic is logged or otherwise observable.
• Existing direct boot/debug boot failure semantics remain separate.

Tests

• cargo test -p prometeu-firmware
• cargo test -p prometeu-system
• 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 tests for:
  • switch failure returns Home;
  • old Game not restored;
  • partial new session cleanup;
  • direct boot failure path remains unchanged.

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/lifecycle.rs