prometeu-runtime/discussion/workflow/plans/PLN-0158-terminate-resident-game-before-switching-cartridges.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0158	system-os-cartridge-switch-orchestrator	Terminate Resident Game Before Switching Cartridges	done	2026-07-05	DEC-0039	runtime os lifecycle game cartridge architecture

Briefing

DEC-0039 defines Game A -> Home -> Game B as destructive replacement. The current same-Game resume flow keeps the resident Game session alive; switching to a different Game must instead close/remove that resident session and create a fresh session for the new Game.

Objective

Implement the SystemOS lifecycle/session operation that terminates the current resident Game before loading a different Game cartridge.

Dependencies

• Source decision: DEC-0039.
• Requires PLN-0157 target contract.
• Should be implemented before PLN-0159 and PLN-0161.

Scope

• Add a controlled resident Game termination/replacement operation to SystemOS lifecycle/session services.
• Optionally emit a cooperative terminate/close/save lifecycle event when the current event model can carry it, but do not block replacement on it.
• Remove the previous Game from resident/resumable state.
• Remove the previous Game VM session before activating the new Game.
• Clear or reassign app-scoped state that cannot leak into the new Game: session VM, open handles, pending lifecycle state, input barrier/pending input, audio active app state, render ownership, telemetry/debug/crash state.

Non-Goals

• Do not preserve Game A for rollback.
• Do not implement failed-load recovery beyond surfacing errors; that is PLN-0159.
• Do not add background execution or multiple resident Games.
• Do not build final launcher UX.

Execution Method

1. Inspect lifecycle/session state in:
   • crates/console/prometeu-system/src/os/lifecycle.rs;
   • crates/console/prometeu-system/src/os/facades/sessions.rs;
   • crates/console/prometeu-system/src/services/foreground;
   • crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs;
   • crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs.
2. Add a replace_resident_game or equivalent operation that:
   • finds the current resident Game;
   • marks its task/process closed or stopped according to existing lifecycle semantics;
   • removes the resident Game entry from foreground stack/lifecycle state;
   • removes its VM session.
3. Ensure same-Game resume still bypasses replacement and remains governed by DEC-0037.
4. Update game launch from Home so launching a different app_id triggers replacement before load.
5. Ensure render ownership transitions away from the old Game before the new Game becomes foreground.
6. Add focused tests for resident Game termination and session removal.

Acceptance Criteria

• Launching a different Game from Home closes/removes the resident Game rather than resuming it.
• The previous Game VM session is absent before the new Game is made active.
• Same-Game selection still resumes the existing resident Game.
• A cooperative close/terminate event, if added, is non-blocking.
• No previous Game VM, handle, lifecycle, render, or debug state is reused by the new Game.

Tests

• cargo test -p prometeu-system
• cargo test -p prometeu-firmware
• cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings
• Add tests for:
  • different Game launch removes previous resident session;
  • same Game launch resumes existing resident session;
  • old Game task/process state is closed/stopped;
  • old Game session cannot be resolved after replacement starts.

Affected Artifacts

• crates/console/prometeu-system/src/os/lifecycle.rs
• crates/console/prometeu-system/src/os/facades/sessions.rs
• crates/console/prometeu-system/src/services/foreground
• crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs
• crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs