prometeu-runtime/discussion/workflow/plans/PLN-0137-implement-systemos-foreground-stack-state.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0137	foreground-stack-game-pause-shell-vm-backed	Implement SystemOS Foreground Stack State	done	2026-07-03	DEC-0037	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.