---
id: PLN-0140
ticket: foreground-stack-game-pause-shell-vm-backed
title: Deliver Game Pause Resume and Suspension
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, vm, lifecycle, pause, suspension]
---

## Briefing

`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
is requested during Game execution, SystemOS must notify the Game, give it a
short bounded budget, then suspend the VM even if the Game does not cooperate.
When returning, SystemOS must reactivate the VM and send a resume or
foreground-restore notification before the visual owner returns to Game.

This plan implements the pause/resume and suspension mechanics after the
foreground state model exists.

## Decisions of Origin

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

## Target

Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
same resident Game.

## Scope

- Add a Game lifecycle event model for pause and resume/foreground-restore.
- Add a bounded pause reaction budget owned by SystemOS.
- Suspend the Game VM after the budget even if the Game does not cooperate.
- Ensure a suspended Game receives no normal gameplay ticks.
- Reactivate the VM and deliver resume/foreground-restore before Game visual
  foreground restoration.
- Integrate with `GameRunningStep` and VM runtime tick control.

## Out of Scope

- No render first-valid-frame gating; that is in `PLN-0141`.
- No host keyboard routing; that is in `PLN-0136`.
- No new guest syscall.
- No background execution.
- No Game-to-Game switching.

## Execution Plan

1. Add lifecycle event representation.
   Define pause/resume events in the most local runtime lifecycle module,
   likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
   SystemOS lifecycle submodule. Events must be observable by the VM/runtime
   path without giving the Game authority over suspension.

2. Add pause transition state.
   Extend the foreground state from `PLN-0137` with a `PauseRequested` or
   equivalent transition state that records the target Game task and the
   remaining pause budget.

3. Gate VM ticks.
   Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
   and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
   suspended Game does not receive normal ticks, normal input, or frame pacing.

4. Deliver pause notification.
   Add the mechanism that makes the pause event visible to the running Game
   before suspension. Use an existing VM event channel if present; otherwise add
   a narrow lifecycle-event queue owned by SystemOS/VM runtime.

5. Enforce the budget.
   Advance the pause budget on firmware ticks. When it expires, transition the
   Game task/process to suspended through SystemOS lifecycle regardless of Game
   cooperation.

6. Deliver resume notification.
   On return to the resident Game, transition from suspended to resume-requested,
   reactivate VM execution, deliver resume/foreground-restore, and leave visual
   restoration to the render boundary plan.

7. Add tests.
   Cover cooperative pause, non-cooperative forced suspension, no tick while
   suspended, resume notification delivery, and no Game-owned ability to cancel
   OS suspension.

## Acceptance Criteria

- Game receives pause before suspension.
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
- Suspended Game does not receive normal gameplay ticks.
- Resume/foreground-restore is delivered before visual return to Game.
- Game cannot prevent OS suspension through guest-visible behavior.
- Existing debugger pause behavior remains distinct from lifecycle suspension.

## Tests / Validation

- Add unit tests in `prometeu-system` for lifecycle transition state.
- Add firmware tests around `GameRunningStep` pause request and suspension.
- Add VM runtime tests proving suspended state suppresses normal ticks.
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `discussion validate`.

## Risks

- Debugger pause already exists in VM runtime. Keep debug pause separate from
  lifecycle pause/suspend.
- A lifecycle event queue could become a general app event system. Keep this
  plan limited to pause/resume required by `DEC-0037`.