prometeu-runtime/discussion/workflow/plans/PLN-0151-schedule-foreground-vm-session-ticks.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0151	foreground-stack-game-pause-shell-vm-backed	Schedule Foreground VM Session Ticks	done	2026-07-04	DEC-0038	runtime os lifecycle shell game vm foreground architecture

Briefing

DEC-0038 separates session ownership from foreground ownership and states that V1 does not provide general background execution. The runtime therefore needs an explicit scheduler path that ticks the VM session eligible for foreground execution, while leaving suspended resident Game sessions intact.

Objective

Make firmware and SystemOS tick the VM session associated with the current foreground VM-backed task, instead of ticking a global VM/runtime pair.

Dependencies

• Source decision: DEC-0038.
• Requires PLN-0148.
• Requires PLN-0149.
• Requires PLN-0150 for loaded cartridges to map to sessions.

Scope

• Add scheduler/facade operations that tick a specific VM session by TaskId.
• Update GameRunningStep to tick the Game session identified by its task_id.
• Update ShellRunningStep to tick only VM-backed Shell sessions.
• Ensure native Shell foreground state performs native profile updates without ticking any VM session.
• Keep suspended Game sessions non-executing while Hub or Shell is foreground.
• Preserve lifecycle event delivery:
  • pause/resume events go to the resident Game session;
  • Shell lifecycle events, if any, remain scoped to the Shell session.
• Preserve host debugger pause/step behavior against the active VM session view.

Non-Goals

• Do not add background execution classes yet.
• Do not allow multiple simultaneous VM ticks in one host frame.
• Do not implement general service/player processes.
• Do not change the 60 Hz firmware tick contract.

Execution Method

1. Add SystemOS facade methods for:
   • ticking a VM session by task id;
   • querying whether a task is VM-backed;
   • exposing the active VM session to host/debugger tooling.
2. Update crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs to tick through the task/session facade.
3. Update crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs to branch on process kind:
   • VM Shell ticks its VM session;
   • native Shell runs native profile logic only.
4. Remove direct ctx.vm use from Game/Shell execution steps.
5. Ensure resident Game pause budget can deliver one final pause tick and then stop ticking once suspended.
6. Update host/debugger active VM access paths to resolve through the foreground session.
7. Add regression tests for tick counters across Game, Hub, native Shell, and VM Shell transitions.

Acceptance Criteria

• A suspended Game session does not advance while Hub is foreground.
• A suspended Game session does not advance while a Shell is foreground.
• A VM Shell session advances while that VM Shell is foreground.
• A native Shell does not tick any VM session.
• Returning from Hub to resident Game resumes ticking the same Game session.
• Host debugger and stats read the active VM session, not a stale global VM.

Tests

• cargo test -p prometeu-firmware
• cargo test -p prometeu-system
• cargo test -p prometeu-host-desktop-winit
• Add tests for:
  • Game tick count freezes after Home suspension;
  • VM Shell tick count advances independently;
  • native Shell does not advance Game tick count;
  • resume returns to same Game session tick counter;
  • active-session debugger snapshot uses foreground VM session.

Affected Artifacts

• crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs
• crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs
• crates/console/prometeu-firmware/src/firmware/prometeu_context.rs
• crates/console/prometeu-firmware/src/firmware/firmware.rs
• crates/console/prometeu-system/src/os/facades/vm.rs
• crates/console/prometeu-system/src/os/facades/lifecycle.rs
• VM session module introduced by PLN-0148
• crates/host/prometeu-host-desktop-winit/src/debugger.rs
• crates/host/prometeu-host-desktop-winit/src/runner.rs
• crates/host/prometeu-host-desktop-winit/src/stats.rs