---
id: PLN-0056
ticket: system-os-lifecycle-process-task-contract
title: Firmware Lifecycle Delegation
status: done
created: 2026-05-15
ref_decisions: [DEC-0025]
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---

## Briefing

Move firmware lifecycle callsites to the `SystemOS` semantic API introduced by
`PLN-0055`. Firmware remains a boot and execution state machine; it must not
coordinate task/process lifecycle by calling `TaskManager` and `ProcessManager`
separately.

## Source Decisions

- `DEC-0025`: firmware must delegate semantic lifecycle transitions to
  `SystemOS`.

## Target

Replace direct lifecycle manipulation in firmware with `SystemOS` lifecycle
methods while preserving current observable behavior.

## Scope

- Update cartridge launch paths to use `SystemOS` lifecycle authority when
  placing newly created tasks in foreground.
- Update crash paths where a task crash is detected so task/process state moves
  through `SystemOS::crash_task`.
- Preserve the strong `GameRunningStep` invariant: a running game step only
  supports a game task in `TaskState::Foreground`.
- Keep `SystemRunningStep`, Hub, and WindowManager behavior unchanged except for
  lifecycle delegation required by `DEC-0025`.

## Out of Scope

- Full game suspend/resume UX.
- Returning to Hub/Home on suspend or close.
- Shell UI redesign.
- App switcher.
- Background task API.
- WindowManager migration.
- Diagnostics service or crash report persistence.

## Execution Plan

1. Audit direct lifecycle manager usage.
   - Target files:
     `crates/console/prometeu-firmware/src/firmware/*.rs`,
     `crates/console/prometeu-system/src/os/system_os.rs`.
   - Search for direct calls to `task_manager.set_foreground`,
     `task_manager.mark_suspended`, `task_manager.close_task`,
     `task_manager.mark_crashed`, `process_manager.mark_suspended`,
     `process_manager.mark_stopped`, and `process_manager.mark_crashed`.

2. Keep launch construction inside `SystemOS`.
   - Target file:
     `crates/console/prometeu-system/src/os/system_os.rs`.
   - Ensure `create_vm_game_task`, `create_vm_shell_task`, and
     `create_native_shell_task` coordinate foreground/running state through the
     lifecycle core API from `PLN-0055`.

3. Update game crash handling.
   - Target file:
     `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
   - When the task is missing, preserve current crash-screen behavior. If the
     task does not exist, `SystemOS::crash_task` cannot attach state and the
     firmware should continue producing a clear crash report.
   - When a foreground invariant fails for an existing task, call
     `ctx.os.crash_task(task_id, report?)` before transitioning to
     `AppCrashesStep`.
   - When `tick_vm` returns a crash report for the active task, call
     `ctx.os.crash_task(task_id, report?)` before transitioning to
     `AppCrashesStep`.

4. Keep shell launch behavior unchanged.
   - Target file:
     `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
   - Do not move `WindowManager` logic.
   - Do not change shell window creation or focus behavior.
   - Rely on `SystemOS::create_vm_shell_task` to coordinate task/process
     foreground state.

5. Avoid introducing background lifecycle.
   - Do not add `background_task`.
   - Do not treat `TaskState::Background` as a public lifecycle result in
     firmware.

## Acceptance Criteria

- Firmware does not coordinate task/process lifecycle by manually changing both
  managers.
- Game VM crash results in `SystemOS::crash_task` for the active task when the
  task still exists.
- Foreground invariant violation in `GameRunningStep` crashes the task through
  `SystemOS`.
- Launch behavior for `AppMode::Game` and `AppMode::Shell` remains unchanged.
- WindowManager and Hub behavior are not redesigned or moved.

## Tests / Validation

- Run firmware tests that cover cartridge launch for `AppMode::Game` and
  `AppMode::Shell`.
- Add or update tests for `GameRunningStep` crash delegation if the existing
  test harness supports firmware step testing.
- Run the affected Rust test suite for `prometeu-firmware`.

## Risks

- Crash report ownership is not final. This plan should pass the report through
  the lifecycle API only to the extent supported by `PLN-0055`; persistence
  remains out of scope.
- `GameRunningStep` currently reads task state directly. This is acceptable for
  enforcing the foreground invariant, but it must not become a place that
  coordinates lifecycle state across managers.