---
id: PLN-0146
ticket: foreground-stack-game-pause-shell-vm-backed
title: Consolidate Lifecycle Process Lookup Helpers
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---

## Briefing

`DEC-0037` depends on SystemOS lifecycle authority being internally
consistent. The lifecycle facade now exposes both process state and process kind
for a task so firmware can distinguish VM-backed Shell tasks from native Shell
tasks. Both accessors repeat the same task-to-process lookup pattern.

The duplication is small, but this facade is now part of the foreground
contract surface. Keeping lookup and error mapping in one place reduces the
chance that future lifecycle accessors drift in behavior.

## Objective

Consolidate task-to-process lookup in `LifecycleFacade` behind one private
helper, while preserving the public lifecycle facade behavior and errors.

## Dependencies

- Source decision: `DEC-0037`.
- Depends on the process/task authority from SystemOS lifecycle work.
- Can be implemented independently of `PLN-0145` and `PLN-0147`.

## Scope

Included:

- Add one private helper that resolves a `TaskId` to its backing process.
- Route `process_state_for_task` and `process_kind_for_task` through that
  helper.
- Preserve `LifecycleError::TaskNotFound` and
  `LifecycleError::ProcessNotFound` behavior exactly.
- Keep the current process/task manager ownership boundaries intact.
- Keep the current non-architectural cleanup in `set_foreground_task` if it is
  still present in the working tree.

Excluded:

- No new public process manager API.
- No changes to task or process IDs.
- No changes to Shell/Game lifecycle semantics.
- No broader facade refactor outside lifecycle lookup.

## Non-Goals

- Do not expose raw process manager access through SystemOS.
- Do not change `ProcessKind` or `TaskKind` definitions.
- Do not alter foreground stack behavior.

## Execution Method

1. Add a private lifecycle lookup helper.
   - What changes: add a private function near `process_id_for_task` that
     returns a process reference for a `TaskId`.
   - How it changes: the helper should call `process_id_for_task`, then
     retrieve the process from `process_manager`, returning
     `LifecycleError::ProcessNotFound(process_id)` if the process is missing.
   - File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.

2. Route state and kind accessors through the helper.
   - What changes: `LifecycleFacade::process_state_for_task` and
     `LifecycleFacade::process_kind_for_task` stop duplicating the process
     manager lookup.
   - How it changes: both methods call the helper and map the process reference
     to `ProcessState` or `ProcessKind`.
   - File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.

3. Preserve existing foreground code cleanup.
   - What changes: keep `set_foreground_task` as an expression-returning match
     rather than using redundant `return` statements.
   - How it changes: ensure formatting and clippy stay clean.
   - File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.

4. Tighten tests around lookup behavior.
   - What changes: extend or keep tests proving VM Shell and native Shell
     process kinds are observable through lifecycle.
   - How it changes: add missing-task and missing-process coverage only if the
     helper changes the observable path enough to justify it.
   - File(s): `crates/console/prometeu-system/src/os/system_os.rs`.

## Acceptance Criteria

- [ ] `process_state_for_task` and `process_kind_for_task` share one private
      task-to-process lookup implementation.
- [ ] Missing task and missing process errors remain unchanged.
- [ ] Existing lifecycle tests continue to pass.
- [ ] Firmware can still distinguish `ProcessKind::VmShell` from
      `ProcessKind::NativeShell`.
- [ ] Clippy reports no warnings for the touched crates.

## Tests

- Unit tests in `prometeu-system` for shell process kind lookup.
- Existing lifecycle missing task/process tests must continue to pass.
- Run `cargo test -p prometeu-system lifecycle process_kind`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`.
- Run `discussion validate`.

## Affected Artifacts

- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- `crates/console/prometeu-system/src/os/system_os.rs`

## Risks

- Over-generalizing the helper could leak process manager concepts outside the
  lifecycle facade. Keep it private and narrowly typed.
- This is intentionally small cleanup. It must not become a broad SystemOS
  facade redesign.