---
id: PLN-0164
ticket: hub-suspended-game-kill-affordance
title: Expose Resident Game Termination Contract
status: open
created: 2026-07-05
ref_decisions: [DEC-0040]
tags: [hub, lifecycle, game, ui]
---

## Briefing

DEC-0040 requires the Hub kill affordance to reuse the same resident-game termination path used by cartridge switching. This plan creates the lifecycle/runtime contract that the Hub UI can call without duplicating cleanup logic.

## Objective

Expose a single SystemOS/Firmware operation that terminates the current resident `Game` cartridge from Hub context and performs the complete cleanup required by DEC-0040.

## Dependencies

- Source decision: DEC-0040.
- Related lifecycle behavior: DSC-0043 / DEC-0039 cartridge switch orchestrator.
- Must be completed before PLN-0163 can wire the Hub UI click.

## Scope

- Add or reuse a resident-game termination operation in SystemOS lifecycle/facade code.
- Ensure the operation closes task/process lifecycle state.
- Ensure the operation removes the VM session and resident game state.
- Ensure render ownership returns to Shell/Hub.
- Ensure game audio pause/lifecycle state is cleared.
- Ensure Game2D composer scene binding/cache state is cleared.
- Ensure cartridge asset manager state and physical memory banks are cleared.
- Emit an explicit `INFO` log for manual Hub kill.

## Non-Goals

- Do not change cartridge switching semantics except to reuse the same termination path.
- Do not add Hub UI rendering or hit testing; that belongs to PLN-0163.
- Do not add confirmation semantics; DEC-0040 explicitly rejects confirmation for this version.
- Do not support shell/system app killing through this affordance.

## Execution Method

1. Locate the current game switch termination path in firmware/SystemOS lifecycle code.
   - Files: `crates/console/prometeu-firmware/src/firmware/`, `crates/console/prometeu-system/src/`.
   - Confirm which function currently closes the resident game before switching cartridges.

2. Extract or expose a named resident-game termination operation.
   - The operation must be callable from Hub context without a target cartridge.
   - It must return an explicit status: no resident game, terminated game, or failure if the lifecycle cannot close cleanly.
   - It must preserve existing switch behavior by making switch call the same operation or a shared internal helper.

3. Wire complete cleanup into that operation.
   - Close task/process lifecycle state.
   - Remove the VM session and resident game state.
   - Transition render ownership to Shell/Hub.
   - Clear game lifecycle audio pause state.
   - Unbind `Game2D` scene/composer state.
   - Shutdown cartridge assets and clear physical memory banks.

4. Emit the manual kill log.
   - Source must be `HUB` or `POS`.
   - Level must be `INFO`.
   - Message must include the killed title, equivalent to `Resident game killed from Hub: <title>`.

## Acceptance Criteria

- [ ] There is one canonical resident-game termination path used by both cartridge switching and Hub manual kill.
- [ ] Calling the operation with no resident game is harmless and does not mutate unrelated Hub state.
- [ ] Calling the operation with a suspended `Game` closes the task/process and removes the VM session.
- [ ] The runtime cannot resume the killed game after the operation.
- [ ] Render ownership is Shell/Hub after the operation.
- [ ] Game audio pause/lifecycle state is not left active after the operation.
- [ ] Composer and cartridge asset/bank state are cleared.
- [ ] An explicit INFO log is emitted for Hub manual kill.

## Tests

- Unit or integration test around the lifecycle operation:
  - no resident game is a no-op;
  - resident game is terminated;
  - VM session lookup returns none after kill;
  - resident game state returns none after kill;
  - render owner is Shell/Hub after kill.
- Regression test proving cartridge switch still terminates through the same cleanup behavior.
- Asset/composer cleanup assertions should mirror the recent Stress/Dummy switch tests where applicable.

## Affected Artifacts

- `crates/console/prometeu-system/src/`
- `crates/console/prometeu-firmware/src/`
- Existing switch tests under firmware/SystemOS test modules