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

## Briefing

Implement the first-wave `SystemOS` lifecycle API required by `DEC-0025`.
`SystemOS` becomes the semantic coordinator for `TaskState` and `ProcessState`;
`TaskManager` and `ProcessManager` remain storage and simple transition
mechanisms.

## Source Decisions

- `DEC-0025`: `SystemOS` is the lifecycle authority for tasks and processes.

## Target

Add typed lifecycle operations to `prometeu-system` without changing firmware
behavior, WindowManager ownership, Hub UI, background services, docking, app
switching, or VM ownership.

## Scope

- Add `LifecycleError` and `LifecycleOperation` in `prometeu-system`.
- Add lifecycle methods on `SystemOS`:
  - `set_foreground_task(task_id)`
  - `suspend_task(task_id)`
  - `resume_task(task_id)`
  - `close_task(task_id)`
  - `crash_task(task_id, report?)`
- Coordinate task and process state changes inside `SystemOS`.
- Preserve `TaskManager` and `ProcessManager` as internal state managers.
- Keep `Background` reserved and out of public lifecycle semantics.

## Out of Scope

- Background semantics.
- Docking.
- Background services.
- App switcher.
- WindowManager migration.
- PrometeuHub redesign.
- Game suspend/resume UX.
- ProcessManager owning VM execution.
- Collection/removal of closed or stopped entities.

## Execution Plan

1. Add lifecycle types.
   - Create a lifecycle module or colocate the types under
     `crates/console/prometeu-system/src/os/`.
   - Define `LifecycleOperation` with `SetForeground`, `Suspend`, `Resume`,
     `Close`, and `Crash`.
   - Define `LifecycleError` with `TaskNotFound(TaskId)`,
     `ProcessNotFound(ProcessId)`, and `InvalidTransition { task_id, from,
     operation }`.
   - Re-export the types through `prometeu-system` only if the existing public
     module style requires it.

2. Add the `SystemOS` coordination helpers.
   - Target file: `crates/console/prometeu-system/src/os/system_os.rs`.
   - Resolve the task first through `task_manager`.
   - Extract the task's associated `ProcessId`.
   - Validate that the process exists before mutating state.
   - Return typed errors instead of `bool`.

3. Implement first-wave operations.
   - `set_foreground_task`: call `task_manager.set_foreground(task_id)` and
     `process_manager.mark_running(process_id)`.
   - `suspend_task`: set `TaskState::Suspended` and
     `ProcessState::Suspended`.
   - `resume_task`: require a suspended task, then set
     `TaskState::Foreground` and `ProcessState::Running`.
   - `close_task`: set `TaskState::Closed` and `ProcessState::Stopped`.
   - `crash_task`: set `TaskState::Crashed` and `ProcessState::Crashed`.

4. Keep manager APIs mechanical.
   - Target files:
     `crates/console/prometeu-system/src/services/task/task_manager.rs` and
     `crates/console/prometeu-system/src/services/process/process_manager.rs`.
   - Do not remove existing manager methods in this plan.
   - Add only narrow helpers if needed to support the `SystemOS` API cleanly.

5. Update task creation to use the lifecycle API internally.
   - In `SystemOS::create_vm_game_task`, `create_vm_shell_task`, and
     `create_native_shell_task`, replace direct foreground manager calls with
     `set_foreground_task`.
   - Keep the constructors returning `TaskId`; handle impossible internal
     errors with explicit debug/assert behavior or an internal helper that
     cannot fail after creation.

## Acceptance Criteria

- `SystemOS` exposes all five first-wave lifecycle methods from `DEC-0025`.
- All five methods coordinate both task and process state.
- Missing task returns `LifecycleError::TaskNotFound`.
- Missing associated process returns `LifecycleError::ProcessNotFound`.
- Invalid resume from a non-suspended task returns `InvalidTransition`.
- `Background` is not exposed through a new lifecycle API.
- Closed and stopped entities are not removed by `close_task`.

## Tests / Validation

- Add or update unit tests in `prometeu-system` for each lifecycle mapping.
- Add tests for missing task, missing process, and invalid resume transition.
- Run the affected Rust test suite for `prometeu-system`.

## Risks

- Existing direct manager access is public enough that callsites may keep using
  it. This plan does not remove those methods; enforcement continues in
  `PLN-0056`.
- `TaskManager::set_foreground` currently moves the previous foreground task to
  `Background`. Since `Background` is out of first-wave semantics, tests must
  avoid treating that transition as normative lifecycle policy.