---
id: PLN-0148
ticket: foreground-stack-game-pause-shell-vm-backed
title: Introduce VM Session Registry and Identity
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.

The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.

## Objective

Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.

## Dependencies

- Source decision: DEC-0038.
- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.

## Scope

- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
- Add a `VmSession` data structure containing at least:
  - owning `TaskId`;
  - owning process id or process lookup path;
  - `app_id`, title, version, and `AppMode`;
  - initial placeholder for the session-owned `VirtualMachine`;
  - initial placeholder for session-owned runtime state to be populated by PLN-0149.
- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
- Enforce V1 uniqueness:
  - at most one resident Game session;
  - one foreground Shell task at a time;
  - same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.

## Non-Goals

- Do not move all VM runtime fields yet; that is PLN-0149.
- Do not route cartridge loading through sessions yet; that is PLN-0150.
- Do not remove `Firmware.vm` yet.
- Do not implement general background execution.
- Do not allow Game-to-Game switching.

## Execution Method

1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
2. Add the VM session module with a small API:
   - create session for an existing VM-backed task/process;
   - get immutable/mutable session by task id;
   - get resident Game session by `app_id`;
   - reject incompatible duplicate Game sessions.
3. Wire the registry into `SystemOS`.
4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
5. Keep native Shell task creation out of the VM session registry.
6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.

## Acceptance Criteria

- `SystemOS` owns a VM session registry.
- Creating a VM Game task creates exactly one VM session associated with that task.
- Creating a VM Shell task creates exactly one VM session associated with that task.
- Creating a native Shell task creates no VM session.
- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
- No firmware state transition depends on the new registry yet except through task/session creation.

## Tests

- `cargo test -p prometeu-system`
- Add unit tests for:
  - VM Game task creates a VM session;
  - VM Shell task creates a VM session;
  - native Shell task does not create a VM session;
  - lookup by `TaskId`;
  - same resident Game `app_id` resolves to the existing session;
  - different resident Game `app_id` remains blocked under V1.

## Affected Artifacts

- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/services/mod.rs`
- New or extended module under `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-system/src/lib.rs` if exports are required