129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
---
|
|
id: PLN-0061
|
|
ticket: task-owned-shell-windows
|
|
title: Plan - Shell Running Lifecycle Integration
|
|
status: open
|
|
created: 2026-05-15
|
|
completed:
|
|
ref_decisions: [DEC-0027]
|
|
tags: [runtime, os, task, window-manager, shell, lifecycle, firmware, tests]
|
|
---
|
|
|
|
# Plan - Shell Running Lifecycle Integration
|
|
|
|
## Briefing
|
|
|
|
Integrate the accepted task-owned window contract into `ShellRunningStep`.
|
|
`ShellRunningStep` must stop using generic focused-window presence as the
|
|
liveness contract and must close the shell task through lifecycle when the
|
|
focused window no longer belongs to that task.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0027` - Task-Owned Shell Windows
|
|
|
|
## Alvo
|
|
|
|
`ShellRunningStep` continues only when:
|
|
|
|
```text
|
|
TaskState::Foreground
|
|
+
|
|
os.windows().focused_window_belongs_to_task(task_id)
|
|
```
|
|
|
|
When that predicate is false, the step must call
|
|
`os.lifecycle().close_task(task_id)` and return `FirmwareState::HubHome`.
|
|
|
|
## Escopo
|
|
|
|
Included:
|
|
|
|
- Update
|
|
[firmware_step_shell_running.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs).
|
|
- Adjust the shell-running path in
|
|
[prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs) only if `focused_window_active` becomes unused or misleading.
|
|
- Add firmware/system tests proving lifecycle closure and Hub return behavior.
|
|
- Preserve `GameRunningStep` behavior.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Spec edits; covered by `PLN-0059`.
|
|
- Adding the window ownership API; covered by `PLN-0060`.
|
|
- Overlay/modal policy.
|
|
- Background, minimization, app switcher, dock, or multiple-window behavior.
|
|
- Treating games as windows.
|
|
|
|
## Plano de Execucao
|
|
|
|
1. Depend on `PLN-0060`.
|
|
Do not update `ShellRunningStep` until
|
|
`os.windows().focused_window_belongs_to_task(task_id)` exists.
|
|
|
|
2. Replace the liveness predicate in `ShellRunningStep`.
|
|
In `firmware_step_shell_running.rs`, keep the existing `TaskState`
|
|
validation. After `ctx.hub.update_shell_profile(...)`, replace the
|
|
`outcome.focused_window_active` check with:
|
|
|
|
```text
|
|
!ctx.os.windows().focused_window_belongs_to_task(self.task_id)
|
|
```
|
|
|
|
3. Preserve crash handling order.
|
|
Keep VM crash handling before window-liveness closure so a crash reported by
|
|
the shell update remains a crash, not a normal close.
|
|
|
|
4. Close through lifecycle before returning Hub.
|
|
When the focused-window ownership predicate is false:
|
|
- log the closure with task id;
|
|
- call `ctx.os.lifecycle().close_task(self.task_id)`;
|
|
- log lifecycle close errors;
|
|
- return `Some(FirmwareState::HubHome(HubHomeStep))`.
|
|
|
|
5. De-emphasize or remove `focused_window_active`.
|
|
If `SystemProfileUpdate.focused_window_active` has no remaining call sites,
|
|
remove it from `SystemProfileUpdate` and its construction. If another
|
|
legitimate caller remains, keep it but do not use it for shell task
|
|
liveness.
|
|
|
|
6. Add or update tests.
|
|
Use existing firmware tests in
|
|
[firmware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/firmware.rs)
|
|
or a nearby test module. Cover:
|
|
- focused task-owned window keeps the shell path running;
|
|
- no focused window closes task and returns `HubHome`;
|
|
- focused `Hub` window closes task and returns `HubHome`;
|
|
- focused `Overlay` window closes task and returns `HubHome` in v1;
|
|
- focused window for another task closes task and returns `HubHome`;
|
|
- lifecycle close changes task to `Closed` and process to `Stopped`;
|
|
- `GameRunningStep` remains independent from `WindowManager`.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] `ShellRunningStep` no longer uses `focused_window_active` as its
|
|
continuation contract.
|
|
- [ ] `ShellRunningStep` uses
|
|
`os.windows().focused_window_belongs_to_task(self.task_id)`.
|
|
- [ ] A false predicate closes the task through lifecycle before returning
|
|
`HubHome`.
|
|
- [ ] `Hub`, `Overlay`, absent focus, and another task's focused window all
|
|
fail the predicate for the current shell task.
|
|
- [ ] Game-running behavior is unchanged and remains outside `WindowManager`.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Run `cargo test -p prometeu-system`.
|
|
- Run `cargo test -p prometeu-firmware`.
|
|
- Run a workspace or targeted build command used by this repository if the two
|
|
crate tests are not sufficient.
|
|
- Run `discussion validate`.
|
|
|
|
## Riscos
|
|
|
|
- Current Hub update behavior may close or replace windows during the same tick;
|
|
tests need to account for the final focused window after `update_shell_profile`.
|
|
- Removing `focused_window_active` may require small cleanup in system tests or
|
|
callers.
|
|
- The v1 overlay behavior is intentionally strict. Do not add overlay
|
|
preservation logic in this plan.
|