prometeu-runtime/discussion/workflow/plans/PLN-0156-harden-vm-session-lifecycle-error-boundaries.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0156	foreground-stack-game-pause-shell-vm-backed	Harden VM Session Lifecycle Error Boundaries	done	2026-07-05	DEC-0038	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