prometeu-runtime/discussion/workflow/plans/PLN-0062-native-shell-launch-and-lifecycle-wiring.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0062	prometeu-hub-ui-direction	Native Shell Launch and Lifecycle Wiring	done	2026-05-15	DEC-0028	hub ui shell system-apps lifecycle design-system

Briefing

Implement the OS/Firmware wiring required by DEC-0028 so the Hub can emit a launch intent for ShellA or ShellB, and SystemOS/Firmware can create a native Shell task, create a task-owned window, run the Shell state, close through lifecycle, and return to Hub/Home.

Source decision: DEC-0028.

Objective

Make the launch/close path architecturally correct before the visual slice depends on it:

• Hub emits launch intent.
• SystemOS/Firmware creates native Shell task/process.
• The Shell app has a WindowOwner::Task(task_id) window.
• Close uses os.lifecycle().close_task(task_id).
• ShellRunningStep returns to Hub/Home after close.

Dependencies

• DEC-0028 must remain accepted.
• This plan should execute before PLN-0064, because the UI buttons need a real launch target.
• This plan may execute before or alongside PLN-0063 if tests can trigger Hub actions without mouse input.

Scope

• Update the Hub update result shape so it can report launch/close actions, not only crashes.
• Add native fake Shell app identity for ShellA and ShellB.
• Wire Firmware/SystemOS launch handling from Hub intent to sessions().create_native_shell_task(...).
• Create and focus a task-owned window for the launched native Shell task.
• Ensure app close routes to lifecycle close, not only window removal.
• Preserve the existing task-owned window liveness rule in ShellRunningStep.

Non-Goals

• No generic app catalog.
• No reusable UI toolkit.
• No game cartridge window model.
• No background/minimize/overlay preservation semantics.
• No controller focus navigation.
• No public spec change unless implementation introduces a new public API.

Execution Method

1. Inspect current launch state.

   • What changes: identify the exact update path from HubHomeStep to PrometeuHub::update_shell_profile and ShellRunningStep.
   • How: read the current firmware state transitions and Hub update result.
   • Files: crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs, crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs, crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs.

2. Replace crash-only Hub output with an action-bearing result.

   • What changes: extend or replace SystemProfileUpdate so it can carry LaunchNativeShell(ShellA|ShellB) and close intent while preserving crash reporting.
   • How: add a small enum local to the Hub/system profile boundary; keep visual components free of lifecycle mutation.
   • Files: crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs and firmware call sites.

3. Handle launch in Firmware/SystemOS.

   • What changes: when Hub emits launch intent, create the native Shell task through os.sessions().create_native_shell_task(app_id, title).
   • How: map ShellA and ShellB to stable local app ids/titles for this fake-app slice.
   • Files: crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs; add helper code in prometeu-system only if needed to avoid duplication.

4. Create the task-owned Shell window.

   • What changes: after task creation, create and focus a window with WindowOwner::Task(task_id).
   • How: use the existing window facade first; introduce a narrow helper only if the launch sequence becomes duplicated or leaks into visual components.
   • Files: crates/console/prometeu-system/src/os/facades/sessions.rs, crates/console/prometeu-system/src/os/facades/window.rs, or firmware step depending on the smallest clean integration point.

5. Route close through lifecycle.

   • What changes: app/window close must call os.lifecycle().close_task(task_id) or emit an equivalent action handled by Firmware/SystemOS.
   • How: keep window removal separate from lifecycle semantics; do not treat close_window as app close.
   • Files: crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs, crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs.

6. Add behavior tests.

   • What changes: add tests proving launch creates native Shell task/window and close returns to Hub.
   • How: test at SystemOS/Firmware boundary rather than only manager internals.
   • Files: existing firmware/system test modules, preferably near current lifecycle/window tests.

Acceptance Criteria

• Launching ShellA creates a native Shell task/process.
• Launching ShellB creates a native Shell task/process.
• Each launched Shell app receives a focused WindowOwner::Task(task_id) window.
• Closing the Shell app closes lifecycle state through os.lifecycle().close_task(task_id).
• Closing the Shell app returns firmware to HubHome.
• Hub visual code does not directly mutate task/process managers.
• Existing shell liveness behavior remains intact.

Tests

• Unit tests for any new Hub action enum or mapping logic.
• SystemOS tests for any new helper/facade that creates native Shell task plus task-owned window.
• Firmware tests for HubHome launch to ShellRunning and ShellRunning close to HubHome.
• Regression tests for focused_window_belongs_to_task(task_id) behavior if touched.

Affected Artifacts

• crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs
• crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs
• crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs
• crates/console/prometeu-system/src/os/facades/sessions.rs
• crates/console/prometeu-system/src/os/facades/window.rs
• Existing SystemOS/Firmware tests