implements PLN-0059 task window specs

discussion/index.ndjson

@@ -1,5 +1,5 @@
 {"type":"meta","next_id":{"DSC":36,"AGD":36,"DEC":28,"PLN":62,"LSN":44,"CLSN":1}}
-{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-agenda-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-decision-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0059","file":"PLN-0059-plan-task-window-contract-specs.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0060","file":"PLN-0060-plan-focused-window-ownership-api.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0061","file":"PLN-0061-plan-shell-running-lifecycle-integration.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-agenda-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-decision-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0059","file":"PLN-0059-plan-task-window-contract-specs.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0060","file":"PLN-0060-plan-focused-window-ownership-api.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0061","file":"PLN-0061-plan-shell-running-lifecycle-integration.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
 {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
 {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"discussion/lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}

discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md

@@ -2,9 +2,9 @@
 id: PLN-0059
 ticket: task-owned-shell-windows
 title: Plan - Task Window Contract Specs
-status: open
+status: done
 created: 2026-05-15
-completed:
+completed: 2026-05-15
 ref_decisions: [DEC-0027]
 tags: [runtime, os, task, window-manager, shell, lifecycle, specs]
 ---
@@ -91,13 +91,13 @@ Included:
 
 ## Criterios de Aceite
 
-- [ ] The spec describes the `Process` / `Task` / `Window` model in English.
-- [ ] The spec states that games are not `WindowManager` windows.
-- [ ] The spec states that shell app windows use `WindowOwner::Task(TaskId)`.
-- [ ] The spec states the v1 `ShellRunningStep` focused-window predicate.
-- [ ] The spec states that loss of the eligible focused window closes the task
+- [x] The spec describes the `Process` / `Task` / `Window` model in English.
+- [x] The spec states that games are not `WindowManager` windows.
+- [x] The spec states that shell app windows use `WindowOwner::Task(TaskId)`.
+- [x] The spec states the v1 `ShellRunningStep` focused-window predicate.
+- [x] The spec states that loss of the eligible focused window closes the task
   through lifecycle before returning to Hub.
-- [ ] The spec does not introduce overlay, background, minimization, app
+- [x] The spec does not introduce overlay, background, minimization, app
   switcher, dock, or multiple-window policy.
 
 ## Tests / Validacao

docs/specs/runtime/12-firmware-pos-and-prometeuhub.md

@@ -31,6 +31,14 @@ The VM does not own the machine lifecycle. Firmware does.
 - **AppMode**: cartridge mode, currently `Game` or `System`.
 - **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
 - **Host tick**: the host-driven outer update tick.
+- **Process**: technical execution owned by POS lifecycle.
+- **Task**: navigable presence associated with an app flow.
+- **Window**: visual presence for a shell/system task when that task is
+  represented by the system window model.
+- **WindowOwner**: ownership marker for a system window. The v1 owners are
+  `Hub`, `Task(TaskId)`, and `Overlay`.
+- **Shell task window**: a `WindowManager` window whose owner is
+  `WindowOwner::Task(TaskId)`.
 
 ## 3 POS Responsibilities
 
@@ -69,6 +77,8 @@ Game-mode cartridges:
 - transition firmware into the game-running state;
 - run as the active app flow;
 - present through the main frame path.
+- run as fullscreen firmware sessions;
+- are not `WindowManager` windows.
 
 ### System
 
@@ -77,8 +87,59 @@ System-mode cartridges:
 - are initialized by POS;
 - are integrated into the Hub/window environment;
 - do not replace the firmware state with the game-running path.
+- are represented as shell task windows when they expose a visual shell
+  presence.
 
-## 6 Cartridge Load Flow
+## 6 Task-Owned Shell Windows
+
+The shell window contract separates execution, navigation, and visual
+presence:
+
+```text
+Process = technical execution
+Task = navigable presence
+Window = visual presence of the task
+```
+
+For shell/system apps managed by the window model, the visible shell presence
+must be a `WindowManager` window owned by `WindowOwner::Task(TaskId)`.
+
+`Hub` windows are not shell task windows. `Overlay` windows are not shell task
+windows in this v1 contract. Overlay/modal policy, minimization, app switching,
+dock behavior, background services, and complex multi-window semantics are
+future contracts and are not defined here.
+
+Game cartridges must not be represented as `WindowManager` windows. They remain
+fullscreen sessions driven by `GameRunningStep`.
+
+For v1, `ShellRunningStep` continues a shell task only while both conditions are
+true:
+
+```text
+TaskState::Foreground
++
+focused window owner == WindowOwner::Task(task_id)
+```
+
+The runtime query for the focused-window ownership predicate is:
+
+```text
+os.windows().focused_window_belongs_to_task(task_id)
+```
+
+If a foreground shell task loses its eligible focused window,
+`ShellRunningStep` must close the task through `SystemOS` lifecycle before
+returning to Hub:
+
+```text
+Shell task loses its eligible focused window
+    -> os.lifecycle().close_task(task_id)
+    -> TaskState::Closed
+    -> ProcessState::Stopped
+    -> FirmwareState::HubHome
+```
+
+## 7 Cartridge Load Flow
 
 Current high-level flow:
 
@@ -93,7 +154,7 @@ If VM initialization fails, firmware transitions to the crash path.
 
 POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
 
-## 7 Firmware States
+## 8 Firmware States
 
 The current firmware state model includes:
 
@@ -107,7 +168,7 @@ The current firmware state model includes:
 
 These states express machine orchestration above the VM. They are not guest-visible bytecode states.
 
-## 8 Execution Contract
+## 9 Execution Contract
 
 For game-mode execution, firmware/runtime coordination preserves:
 
@@ -118,7 +179,7 @@ For game-mode execution, firmware/runtime coordination preserves:
 
 This keeps the machine model deterministic and observable.
 
-## 9 Crash Handling
+## 10 Crash Handling
 
 Firmware owns terminal fault presentation.
 
@@ -130,7 +191,7 @@ When a terminal app fault occurs:
 
 Crash handling is outside the guest VM execution model.
 
-## 10 Relationship to Other Specs
+## 11 Relationship to Other Specs
 
 - [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
 - [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.