---
id: PLN-0137
ticket: foreground-stack-game-pause-shell-vm-backed
title: Implement SystemOS Foreground Stack State
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, foreground, shell, game]
---

## Briefing

`DEC-0037` requires SystemOS to own foreground authority. The system must know
which owner is foreground, keep Hub/Home as root, allow only one resident Game,
allow only one foreground Shell, and return from VM-backed Shell apps to Hub in
v1.

This plan implements the SystemOS state model only. It does not yet deliver
Game pause/resume events, host keyboard routing, or render/audio/input boundary
changes.

## Decisions of Origin

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

## Target

Add an explicit SystemOS foreground stack model that can represent Hub, a
foreground Shell task, and a paused/suspended resident Game.

## Scope

- Add or extend SystemOS-owned foreground state under
  `crates/console/prometeu-system/src/os/` or
  `crates/console/prometeu-system/src/services/`.
- Represent v1 foreground owners:
  - Hub/Home root;
  - Shell task foreground;
  - Game foreground;
  - Game paused/suspended resident.
- Enforce at most one resident Game and at most one foreground Shell.
- Keep Hub as root/back-stack controller.
- Ensure Shell close returns to Hub/Home in v1.
- Expose focused queries through existing or new facades, likely
  `crates/console/prometeu-system/src/os/facades/lifecycle.rs` and
  `crates/console/prometeu-system/src/os/facades/sessions.rs`.

## Out of Scope

- No VM pause/resume event delivery.
- No host `Esc`/`Home` keyboard mapping.
- No render epoch implementation.
- No Game-to-Game switching.
- No background execution.
- No memory eviction for the resident Game.

## Execution Plan

1. Define foreground model types.
   Add enums/structs for foreground owner and resident Game state in the most
   local SystemOS module. The model must distinguish Game foreground, Game
   paused/suspended, Hub foreground, and Shell task foreground.

2. Add SystemOS storage.
   Store the foreground model in `SystemOS` from
   `crates/console/prometeu-system/src/os/system_os.rs` with initialization to
   Hub/Home root.

3. Wire lifecycle facade operations.
   Extend lifecycle/session facades so firmware can request:
   - set Game foreground;
   - request Home from Game;
   - set Shell foreground from Hub;
   - close Shell and return to Hub;
   - query current foreground owner;
   - query resident Game task.

4. Enforce cardinality.
   Add checks that reject a second resident Game and a second foreground Shell
   with typed lifecycle errors. Use existing `LifecycleError` style or add
   precise variants.

5. Integrate existing Shell close behavior.
   Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
   only where needed so closing a Shell task routes through the foreground model
   and ends in `FirmwareState::HubHome`.

6. Add tests.
   Cover initial Hub foreground, Game foreground registration, Home request
   moving Game to resident paused/suspended state, Shell foreground activation,
   Shell close returning to Hub, and cardinality rejection.

## Acceptance Criteria

- SystemOS has an explicit foreground owner model.
- Hub/Home is the initialized root foreground owner.
- Only one resident Game can exist in v1.
- Only one Shell task can be foreground in v1.
- VM-backed Shell close returns to Hub/Home.
- Foreground queries are available to firmware and later plans.
- No implementation path enables background execution.

## Tests / Validation

- Add focused unit tests in `prometeu-system` around the new model and facade.
- Run `cargo test -p prometeu-system lifecycle foreground`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `discussion validate`.

## Risks

- Existing `TaskState::Foreground` and `TaskState::Suspended` may look like the
  complete model. Do not overload them until foreground ownership and Hub root
  authority are explicit.
- Shell windows already have focus semantics. Keep window focus as visual/task
  evidence, not the sole source of SystemOS foreground truth.