---
id: PLN-0156
ticket: foreground-stack-game-pause-shell-vm-backed
title: Harden VM Session Lifecycle Error Boundaries
status: done
created: 2026-07-05
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

DEC-0038 makes VM session services part of the runtime ownership boundary. Some current session creation paths still use `expect` for lifecycle failures and missing task/process/session invariants. That is acceptable for short-term scaffolding, but session services should expose typed errors at operational boundaries so callers can choose controlled crash, rejection, or recovery behavior.

## Objective

Replace operational `expect`/panic paths in VM session creation/loading with typed errors and controlled firmware outcomes. Keep internal invariant assertions only where impossible states have already been proven by prior checks.

## Dependencies

- Source decision: DEC-0038.
- Builds on PLN-0148 through PLN-0152.
- Can be implemented before or after PLN-0154.
- Should be implemented before broadening VM session scheduling or adding background-capable processes.

## Scope

- Add or extend typed errors for session/lifecycle operations:
  - lifecycle rejection while creating Game/Shell task;
  - missing task for session creation;
  - missing process for session creation;
  - duplicate session;
  - VM-backed session missing during cartridge initialization;
  - foreground Shell already exists.
- Convert `SessionsFacade::create_vm_shell_task` to a fallible equivalent and keep an infallible wrapper only for test/setup code if needed.
- Convert `create_vm_session_for_task` to avoid `expect` for task/process lookup.
- Convert `initialize_session_cartridge` to return typed missing-session errors instead of panicking.
- Map session/lifecycle errors into controlled `CrashReport` or launch rejection behavior in firmware.
- Preserve existing V1 policy:
  - one resident Game;
  - one foreground Shell;
  - no Game-to-Game switching;
  - native Shell creates no VM session.

## Non-Goals

- Do not change DEC-0038 ownership semantics.
- Do not add background execution.
- Do not redesign the foreground stack.
- Do not hide programmer invariants behind overly broad error swallowing.

## Execution Method

1. Introduce a `SessionError` or extend `VmSessionError` with operational cases that cross facade boundaries.
2. Update `SessionsFacade` methods:
   - `try_create_vm_game_task`;
   - new `try_create_vm_shell_task`;
   - `load_vm_cartridge`;
   - `create_vm_session_for_task`;
   - `initialize_session_cartridge`.
3. Update firmware loading paths to map typed session errors into:
   - controlled `CrashReport::VmPanic` for unrecoverable internal failures;
   - logged rejection and no state transition for unsupported lifecycle transitions where appropriate.
4. Update tests that currently rely on panics or infallible creation.
5. Add focused tests for:
   - duplicate foreground Shell rejection during VM Shell load;
   - missing task/process session creation errors;
   - missing VM session during initialization;
   - native Shell still creates no VM session.
6. Run system, firmware, host tests and clippy.

## Acceptance Criteria

- VM session facade operational failures are represented by typed errors.
- `create_vm_shell_task` has a fallible path used by production cartridge loading.
- VM Shell load does not panic when lifecycle rejects the Shell; it returns a controlled error/outcome.
- Missing task/process/session conditions in session services return typed errors.
- Existing tests for resident Game, native Shell, VM Shell, and Game/Shell coexistence still pass.
- No new broad `unwrap`/`expect` appears in production session/lifecycle paths.

## Tests

- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-host-desktop-winit`
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
- Add tests for controlled errors from session creation/loading edge cases.

## Affected Artifacts

- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/services/vm_session.rs`
- `crates/console/prometeu-system/src/os/lifecycle.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
- Related system and firmware tests