---
id: PLN-0147
ticket: foreground-stack-game-pause-shell-vm-backed
title: Move Native Shell Profile Update Into Hub
status: open
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

`DEC-0037` says a suspended Game must not receive normal gameplay ticks while
Hub or Shell owns foreground. A recent fix made `ShellRunningStep` branch on
`ProcessKind`: VM-backed Shell tasks use the VM-backed shell profile path, while
native Shell tasks call `PrometeuHub::gui_update` and `PrometeuHub::render`
without ticking the VM.

That behavior is correct, but the native Shell update sequence now lives in
firmware rather than in the Hub profile API. This duplicates part of
`PrometeuHub::update_shell_profile` and creates a drift risk if Shell close,
render, or input rules change later.

## Objective

Move native Shell profile updating into `PrometeuHub` so `ShellRunningStep`
chooses the correct profile API without reimplementing Hub behavior.

## Dependencies

- Source decision: `DEC-0037`.
- Depends on the `ProcessKind::VmShell` vs `ProcessKind::NativeShell`
  distinction available through `LifecycleFacade::process_kind_for_task`.
- May be implemented before or after `PLN-0146`, but should use the consolidated
  lookup helper if `PLN-0146` has already landed.

## Scope

Included:

- Add a Hub-owned native Shell update API that does not tick the VM.
- Keep VM-backed Shell update behavior in the existing VM-backed profile path.
- Keep Shell close handling consistent between native and VM-backed Shells.
- Keep native Shell rendering in the Hub/Shell UI path.
- Keep firmware responsible for choosing which profile applies to the current
  Shell task.
- Preserve regression coverage that a suspended resident Game does not advance
  while native Shell is foreground.

Excluded:

- No change to VM-backed Shell execution semantics.
- No change to native Shell UI content.
- No direct Shell close to Game.
- No multiple foreground Shells.
- No background Game ticking.

## Non-Goals

- Do not move foreground lifecycle authority into `PrometeuHub`.
- Do not make native Shells VM tasks.
- Do not introduce a general scheduler abstraction.

## Execution Method

1. Add a native Shell profile update method on `PrometeuHub`.
   - What changes: create `update_native_shell_profile` or an equivalent
     clearly named method that returns `SystemProfileUpdate`.
   - How it changes: the method calls `gui_update`, maps Start input to
     `SystemProfileAction::CloseShell` when a shell window is focused, calls
     `render`, and always returns `crash: None`.
   - File(s):
     `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.

2. Keep the VM-backed Shell profile method explicitly VM-backed.
   - What changes: either keep `update_shell_profile` and document/name its VM
     tick behavior, or rename/split it if the codebase convention supports that
     without churn.
   - How it changes: ensure the VM-backed path is the only Hub profile update
     method that calls `os.vm().tick(...)`.
   - File(s):
     `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.

3. Simplify `ShellRunningStep`.
   - What changes: remove manual native Shell `gui_update`, Start handling, and
     render calls from firmware.
   - How it changes: branch on `ProcessKind` and call the appropriate Hub
     profile method; keep crash handling only for the VM-backed method.
   - File(s):
     `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`.

4. Add Hub-level native profile tests.
   - What changes: prove native Shell profile update emits close on the close
     button and on Start, renders Shell UI, and does not tick the VM.
   - How it changes: use existing Hub/system test helpers where possible; assert
     VM tick index remains unchanged for native profile update.
   - File(s):
     `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
     and/or `crates/console/prometeu-firmware/src/firmware/firmware.rs`.

5. Preserve end-to-end regression coverage.
   - What changes: keep the Game -> Home -> native Shell test asserting that
     repeated Shell frames do not advance the resident Game VM tick index.
   - How it changes: rerun the firmware regression added for native Shell
     foreground.
   - File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.

## Acceptance Criteria

- [ ] Native Shell update behavior is owned by `PrometeuHub`, not hand-coded in
      `ShellRunningStep`.
- [ ] The native Shell profile update never calls `os.vm().tick(...)`.
- [ ] VM-backed Shell update remains the only Shell profile path that ticks the
      VM runtime.
- [ ] Start and close-button Shell close behavior remains unchanged for native
      Shells.
- [ ] A suspended resident Game receives no normal gameplay ticks while native
      Shell is foreground.

## Tests

- Hub-level tests for native Shell profile close behavior.
- Hub-level or firmware-level tests proving native Shell profile update does not
  tick the VM.
- Existing firmware regression for Game -> Home -> native Shell repeated frames.
- Run `cargo test -p prometeu-system native_shell shell_profile`.
- Run `cargo test -p prometeu-firmware game_home_shell_hub_same_game_flow`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-system`.
- Run `discussion validate`.

## Affected Artifacts

- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`

## Risks

- Renaming the existing VM-backed shell profile method may create unnecessary
  churn. Prefer adding the native method and keeping call sites explicit unless
  the rename is small and clearly improves readability.
- Hub APIs must remain UI/profile orchestration only; lifecycle close and task
  state changes still belong to firmware/SystemOS lifecycle.