VM Context Ownership for Resident Game and VM-Backed Shell

discussion/index.ndjson

@@ -1,8 +1,8 @@
-{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":38,"PLN":148,"LSN":52,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":44,"AGD":47,"DEC":39,"PLN":154,"LSN":52,"CLSN":1}}
 {"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
 {"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
-{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-04","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0142","file":"PLN-0142-deliver-game-lifecycle-events-to-vm-runtime.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0143","file":"PLN-0143-guarantee-cooperative-pause-budget-tick-before-suspension.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0144","file":"PLN-0144-suspend-resident-game-when-shell-takes-foreground.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0145","file":"PLN-0145-centralize-resident-game-resume-transition.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0146","file":"PLN-0146-consolidate-lifecycle-process-lookup-helpers.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0147","file":"PLN-0147-move-native-shell-profile-update-into-hub.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-04","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"},{"id":"AGD-0046","file":"AGD-0046-vm-context-ownership-for-resident-game-and-vm-backed-shell.md","status":"accepted","created_at":"2026-07-04","updated_at":"2026-07-04"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"},{"id":"DEC-0038","file":"DEC-0038-vm-session-ownership-for-vm-backed-processes.md","status":"accepted","created_at":"2026-07-04","updated_at":"2026-07-04","ref_agenda":"AGD-0046"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0142","file":"PLN-0142-deliver-game-lifecycle-events-to-vm-runtime.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0143","file":"PLN-0143-guarantee-cooperative-pause-budget-tick-before-suspension.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0144","file":"PLN-0144-suspend-resident-game-when-shell-takes-foreground.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0145","file":"PLN-0145-centralize-resident-game-resume-transition.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0146","file":"PLN-0146-consolidate-lifecycle-process-lookup-helpers.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0147","file":"PLN-0147-move-native-shell-profile-update-into-hub.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0148","file":"PLN-0148-introduce-vm-session-registry-and-identity.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0149","file":"PLN-0149-move-vm-runtime-state-into-vm-sessions.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0150","file":"PLN-0150-route-cartridge-loading-through-vm-sessions.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0151","file":"PLN-0151-schedule-foreground-vm-session-ticks.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0152","file":"PLN-0152-validate-game-and-vm-shell-session-coexistence.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0153","file":"PLN-0153-specify-vm-session-ownership-and-background-ready-scheduling.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
 {"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]}
 {"type":"discussion","id":"DSC-0035","status":"done","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":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}

discussion/workflow/agendas/AGD-0046-vm-context-ownership-for-resident-game-and-vm-backed-shell.md

@@ -0,0 +1,186 @@
+---
+id: AGD-0046
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: VM Context Ownership for Resident Game and VM-Backed Shell
+status: accepted
+created: 2026-07-04
+resolved:
+decision: DEC-0038
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Contexto
+
+`DEC-0037` define que o v1 deve suportar o fluxo `Game -> Home/Shell -> same
+Game`, com o Game residente pausado/suspenso enquanto Hub ou Shell possuem o
+foreground. A implementacao atual ja impede que Shell nativo ticke o Game
+suspenso, porque Shell nativo nao usa a VM.
+
+A lacuna aparece quando o Shell tambem eh VM-backed. Hoje `Firmware` possui um
+unico `VirtualMachine` global (`Firmware.vm`). O Game residente e um Shell
+VM-backed competem por esse mesmo contexto. Se o Shell VM-backed inicializa uma
+nova cartridge nesse objeto, ele sobrescreve o contexto do Game que deveria
+permanecer residente/suspenso.
+
+Isso significa que o modelo de foreground/task/process ja avancou, mas o modelo
+de contexto VM ainda esta acoplado ao firmware global.
+
+## Problema
+
+Precisamos decidir onde vive o contexto de execucao VM quando existem, ao mesmo
+tempo, um Game residente suspenso e um Shell VM-backed foreground.
+
+O problema nao eh apenas pausar ticks. Para coexistencia real, cada VM-backed
+process precisa preservar seu proprio estado: PC, stack, heap, globals,
+cartridge identity, runtime services escopados, render ownership metadata e
+eventos lifecycle pendentes.
+
+Enquanto `Firmware.vm` for unico, "suspender" um Game VM nao preserva o
+contexto se outra cartridge VM-backed for carregada.
+
+## Pontos Criticos
+
+- `DEC-0037` diz que um Game suspenso nao recebe ticks/input/frame pacing, mas
+  continua residente para voltar ao mesmo Game.
+- Shell nativo nao precisa de VM context proprio, mas Shell VM-backed precisa.
+- `SystemOS` ja eh autoridade de lifecycle/process/task, entao eh candidato
+  natural para possuir ou localizar contextos VM por sessao.
+- `Firmware` deve orquestrar macro estados, mas nao deveria ser dono unico do
+  contexto de todos os processos VM-backed.
+- `VirtualMachineRuntime` contem estado atualmente misto: identidade da
+  cartridge atual, render manager, lifecycle delivery, fs/memcard/open handles
+  e telemetria. Precisamos separar o que eh global do OS do que eh por sessao
+  VM-backed.
+- A solucao deve preservar a restricao v1: no maximo um Game residente e no
+  maximo um Shell foreground. Ela nao deve abrir multitasking geral.
+- Game-to-Game switching continua fora desta agenda e pertence a `DSC-0043`.
+
+## Opcoes
+
+### Opcao A - Manter VM global no Firmware e bloquear Shell VM-backed com Game residente
+
+- **Abordagem:** documentar que Shell VM-backed nao pode abrir enquanto um Game
+  VM esta residente; apenas Shell nativo coexiste com Game suspenso.
+- **Pro:** menor implementacao imediata.
+- **Contra:** contradiz a intencao de coexistencia de VM-backed Shell em
+  `DEC-0037` e deixa a arquitetura incompleta.
+- **Manutenibilidade:** baixa, porque o sistema teria regras diferentes para
+  Shell nativo e Shell VM-backed sem uma fronteira clara de sessao.
+
+### Opcao B - Serializar o Game VM ao suspender e restaurar ao resumir
+
+- **Abordagem:** ao suspender Game, extrair snapshot do `VirtualMachine` e do
+  runtime associado; ao resumir, restaurar snapshot depois do Shell VM-backed.
+- **Pro:** preserva a ideia de um unico VM executor ativo.
+- **Contra:** exige serializacao profunda e correta de todo o estado VM/runtime,
+  incluindo handles, assets, render state e side effects. Isso eh muito mais
+  complexo que a necessidade v1.
+- **Manutenibilidade:** baixa a media; snapshots viram contrato dificil e
+  fragil antes de termos necessidade de hibernacao real.
+
+### Opcao C - Tornar o contexto VM propriedade da sessao/processo VM-backed
+
+- **Abordagem:** cada processo VM-backed possui seu proprio `VirtualMachine` e
+  seu contexto runtime VM-scoped. O scheduler/firmware seleciona qual sessao
+  recebe tick conforme foreground/lifecycle. Game suspenso simplesmente deixa
+  de ser tickado, mas seu contexto permanece armazenado na sessao Game.
+- **Pro:** alinha com task/process/lifecycle, suporta Game residente + Shell
+  VM-backed sem sobrescrever contexto, e prepara o terreno para futuras sessoes
+  sem implementar multitasking geral agora.
+- **Contra:** exige separar estado hoje concentrado em `Firmware.vm` e
+  `SystemOS.vm_runtime`, decidindo o que eh global do OS e o que eh por sessao.
+- **Manutenibilidade:** alta, porque a posse do contexto acompanha o processo
+  que executa a VM.
+
+### Opcao D - Criar apenas dois slots VM fixos: Game VM e Shell VM
+
+- **Abordagem:** manter um slot `game_vm` e um slot `shell_vm`, em vez de uma VM
+  por processo/sessao.
+- **Pro:** mais simples que uma tabela geral de sessoes.
+- **Contra:** codifica uma limitacao acidental. Ainda precisariamos decidir
+  ownership, runtime scoped state e lifecycle por slot. Pode virar refactor
+  duplo quando mais de um Shell ou Game switching aparecer.
+- **Manutenibilidade:** media; aceitavel como stepping stone somente se modelado
+  internamente como sessao, nao como campos especiais permanentes.
+
+## Sugestao / Recomendacao
+
+Seguir a Opcao C: contexto VM deve pertencer a uma sessao/processo VM-backed,
+nao ao `Firmware` global.
+
+Para v1, a implementacao pode continuar limitada a uma sessao Game residente e
+uma sessao Shell foreground, mas o modelo deve ser "session-owned VM context".
+Isso permite que Shell VM-backed rode enquanto o Game fica suspenso sem perder
+PC/stack/heap/estado runtime.
+
+O firmware deve deixar de possuir a VM como estado global de todos os apps e
+passar a pedir ao SystemOS/runtime scheduler o contexto VM ativo para o owner
+foreground. `SystemOS` deve continuar sendo a autoridade de lifecycle; o
+runtime deve separar estado VM-scoped de estado global de OS/render/telemetria
+conforme necessario.
+
+## Perguntas em Aberto
+
+- [ ] Qual objeto deve representar a sessao VM-backed: `Process`, novo
+      `VmSession`, ou uma tabela separada ligada a `ProcessId`/`TaskId`?
+- [ ] Quais campos de `VirtualMachineRuntime` sao por sessao VM-backed e quais
+      devem permanecer globais em `SystemOS`?
+- [ ] O render manager fica global por foreground owner ou dentro de cada
+      contexto VM com handoff global?
+- [ ] Handles de FS, memcard, assets e open files devem ser por sessao,
+      por app_id, ou globais com namespace por processo?
+- [ ] Como `LoadCartridgeStep` deve mudar: criar sessao VM nova, ativar sessao
+      existente, ou delegar tudo para uma facade de sessions?
+- [ ] Como preservar os testes e invariantes de `DEC-0037` durante a migracao
+      incremental sem abrir multitasking geral?
+- [ ] Como processos background-capable, como um player de musica, entram no
+      modelo sem confundir foreground visual ownership com elegibilidade de
+      execucao?
+- [ ] Cada Shell VM-backed deve ter uma VM propria, mesmo quando existe mais de
+      um Shell em memoria no futuro?
+
+## Criterio para Encerrar
+
+Esta agenda pode virar decision quando definirmos:
+
+- o proprietario canonico do contexto VM;
+- a fronteira entre estado VM-scoped e estado global do OS;
+- como firmware seleciona/ticka a sessao VM ativa;
+- como Game residente suspenso e Shell VM-backed foreground coexistem;
+- quais restricoes v1 permanecem explicitamente fora de escopo.
+
+## Discussion
+
+- 2026-07-04: Aberta a partir da observacao de que Shell nativo coexiste com
+  Game suspenso, mas Shell VM-backed ainda conflita com o `Firmware.vm` unico.
+- 2026-07-04: Discussao adicional separou foreground ownership de background
+  execution. A recomendacao atual eh que todo processo VM-backed tenha sua
+  propria `VmSession`; processos background-capable devem ser modelados como
+  sessoes com classe/politica de scheduling propria, nao como foreground owners.
+
+## Resolution
+
+Resolvido em 2026-07-04:
+
+- O modelo deve seguir a Opcao C: todo processo VM-backed deve possuir uma
+  `VmSession` propria, ligada ao lifecycle/task/process, em vez de depender de
+  um `Firmware.vm` global.
+- Cada Shell VM-backed deve ter sua propria sessao VM. Ele pode compartilhar a
+  engine/runtime e caches imutaveis, mas nao stack, heap, PC, globals, handles
+  ou identidade mutavel de execucao.
+- O Game residente suspenso preserva seu contexto porque sua `VmSession`
+  continua viva; ele apenas deixa de ser elegivel para ticks normais enquanto
+  Hub/Shell possui foreground.
+- Foreground ownership e background execution sao conceitos separados.
+  Foreground ownership decide input visual, render ownership e frame pacing
+  normal. Execution eligibility decide quais sessoes podem receber ticks sem
+  serem foreground.
+- Background execution, como player de musica ou background services, nao entra
+  na primeira implementacao desta agenda. Mesmo assim, o modelo de `VmSession`
+  deve ser obrigatoriamente compativel com essa evolucao em um futuro proximo.
+- Render ownership permanece autoridade global do SystemOS. Sessoes VM-backed
+  produzem frames, mas nao decidem se podem apresentar.
+- `LoadCartridgeStep` nao deve inicializar uma VM global diretamente. Ele deve
+  delegar criacao/ativacao de sessao para uma facade de sessions/scheduler.
+
+Esta agenda esta pronta para virar decision normativa.

discussion/workflow/decisions/DEC-0038-vm-session-ownership-for-vm-backed-processes.md

@@ -0,0 +1,199 @@
+---
+id: DEC-0038
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: VM Session Ownership for VM-Backed Processes
+status: accepted
+created: 2026-07-04
+ref_agenda: AGD-0046
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Status
+
+Open for review.
+
+## Contexto
+
+`DEC-0037` established the foreground stack and Game pause contract for
+`Game -> Home/Shell -> same Game`. It requires a suspended resident Game to stop
+receiving normal gameplay ticks, input, and frame pacing while remaining
+resident for later resume.
+
+The current implementation works for native Shell apps because native Shell
+apps do not use the VM. It does not fully support VM-backed Shell coexistence:
+`Firmware` owns a single global `VirtualMachine` (`Firmware.vm`), so loading a
+VM-backed Shell can overwrite the suspended Game context that should remain
+resident.
+
+`AGD-0046` closes this gap by separating VM execution context ownership from
+foreground ownership. A foreground owner decides who receives visual/input
+authority. A VM execution context decides where PC, stack, heap, globals,
+handles, cartridge identity, lifecycle delivery state, and VM-scoped runtime
+state live.
+
+## Decisao
+
+PROMETEU MUST make VM execution context session-owned for VM-backed processes.
+
+Every VM-backed process MUST have its own `VmSession` or equivalent
+session-owned context. A VM-backed Game and a VM-backed Shell MUST NOT share the
+same mutable `VirtualMachine` instance, stack, heap, PC, globals, open handles,
+cartridge identity, or VM-scoped lifecycle state.
+
+`Firmware.vm` MUST NOT remain the canonical owner of all VM-backed app context.
+Firmware MAY continue to orchestrate macro states such as loading, Home, Shell,
+and GameRunning, but it MUST delegate VM session creation, activation, lookup,
+and ticking to SystemOS/session services.
+
+For v1, the system MAY still enforce:
+
+- at most one resident Game;
+- at most one foreground Shell;
+- no Game-to-Game switching;
+- no general background execution.
+
+Those restrictions MUST NOT be implemented by relying on a single global VM
+context. They must be expressed as lifecycle/session policy.
+
+Each VM-backed Shell MUST receive its own VM session. If future Shell
+persistence allows more than one Shell app to remain in memory, each retained
+VM-backed Shell MUST still have distinct mutable VM context.
+
+A suspended resident Game MUST preserve its VM session. Suspension means the
+session is not eligible for normal foreground ticks, normal Game input, or
+normal frame pacing. It does not mean serializing, deleting, or overwriting the
+VM context.
+
+Foreground ownership and execution eligibility MUST be separate concepts:
+
+- foreground ownership controls visual owner, primary input, render ownership,
+  and normal foreground frame pacing;
+- execution eligibility controls which sessions may receive ticks or restricted
+  callbacks while not foreground.
+
+Background execution, including music players or background services, is out of
+scope for the first implementation of this decision. However, the session model
+MUST be compatible with adding background-capable scheduling soon. The initial
+model MUST NOT bake in assumptions that only the foreground session can ever be
+eligible to execute.
+
+Render ownership MUST remain a global SystemOS authority. VM sessions may
+produce render submissions, but they MUST NOT decide whether those submissions
+can be presented. SystemOS/render ownership policy remains responsible for
+active owner, epoch/generation validity, stale submission rejection, and final
+publication authority.
+
+`LoadCartridgeStep` MUST stop initializing a global firmware VM directly as the
+long-term model. Cartridge load/activation MUST be delegated to a sessions or
+VM-session facade that can create a new VM session, activate an existing VM
+session, or reject an unsupported transition according to lifecycle policy.
+
+## Rationale
+
+The foreground stack is already task/process-oriented. VM execution context must
+follow the same ownership model. Otherwise the system can mark a Game as
+resident and suspended while the only real VM context has already been reused
+for a Shell.
+
+Session ownership solves the actual coexistence problem without requiring VM
+snapshot/restore. A suspended Game is simply a live session that is not scheduled
+for normal ticks. A VM-backed Shell is another session with its own mutable
+state.
+
+Keeping background execution out of the first implementation avoids expanding
+this work into a general scheduler. At the same time, making execution
+eligibility separate from foreground ownership prevents an immediate future
+background audio/player feature from requiring another foundational refactor.
+
+Keeping render ownership global preserves the contract from `DEC-0037` and the
+render ownership model from `DSC-0040`: sessions can generate frames, but only
+the current foreground/render owner can publish valid current-epoch output.
+
+## Invariantes / Contrato
+
+- VM-backed mutable execution state is owned by a VM session, not by a global
+  firmware VM.
+- A VM-backed Game and VM-backed Shell never share mutable VM context.
+- A suspended resident Game retains its VM session.
+- Suspension prevents normal foreground Game ticks/input/frame pacing; it does
+  not destroy or overwrite VM state.
+- Native Shell apps do not require VM sessions.
+- VM-backed Shell apps always require VM sessions.
+- Each VM-backed Shell gets its own mutable VM session.
+- Foreground ownership and execution eligibility are distinct.
+- General background execution is out of scope for the initial implementation,
+  but the model must support adding it without replacing session ownership.
+- SystemOS remains lifecycle and render ownership authority.
+- Render ownership and stale frame rejection remain global policy, not per-VM
+  session policy.
+- Cartridge load/activation must go through session services rather than
+  initializing one global firmware VM.
+- V1 restrictions on one resident Game and one foreground Shell remain policy,
+  not a consequence of single-VM storage.
+
+## Impactos
+
+- **Runtime / SystemOS:** add a VM session model or equivalent service that
+  stores VM-backed process execution context and maps it to task/process
+  lifecycle.
+- **Firmware:** remove `Firmware.vm` as the canonical VM context owner for all
+  apps. Firmware should request session creation/activation/tick from SystemOS.
+- **VM:** support multiple distinct `VirtualMachine` instances or equivalent
+  isolated VM contexts in one OS lifetime.
+- **Lifecycle:** task/process states must control session scheduling
+  eligibility without conflating foreground ownership with future background
+  execution.
+- **Hub / Shell:** VM-backed Shell load must create or activate a Shell VM
+  session without overwriting a resident Game session.
+- **Game:** Game pause/suspend/resume must preserve the Game VM session and
+  deliver lifecycle events to that session.
+- **Renderer:** render manager stays global and validates ownership/epoch for
+  submissions produced by sessions.
+- **FS / Memcard / Assets:** mutable handles and per-app runtime handles must
+  be evaluated for session scoping. Durable memcard/app data can remain keyed by
+  `app_id`; open handles and staging state should not accidentally leak across
+  sessions.
+- **Tests:** add coverage proving VM-backed Shell creation does not overwrite a
+  suspended Game session, and that only eligible sessions tick.
+
+## Alternativas Descartadas
+
+- **Keep one global firmware VM and block VM-backed Shell when a Game is
+  resident:** rejected because it leaves `DEC-0037` incomplete and creates
+  divergent Shell behavior.
+- **Serialize/snapshot the Game VM on suspension:** rejected because snapshot
+  correctness is harder than needed for v1 and would include VM, handles,
+  render state, assets, and side effects.
+- **Hard-code two VM slots (`game_vm`, `shell_vm`):** rejected as a permanent
+  model because it encodes a short-term limit as architecture. It may only be
+  acceptable as an internal stepping stone if represented through the same
+  session abstraction.
+- **Treat background-capable apps as hidden foreground owners:** rejected
+  because it would violate foreground ownership semantics and make render/input
+  authority ambiguous.
+
+## Referencias
+
+- Source agenda: `AGD-0046`
+- Foreground stack and Game pause contract: `DEC-0037`
+- Runtime mode separation: `DSC-0031`
+- SystemOS lifecycle/process/task authority: `DSC-0032`
+- VM render parallel execution boundary: `DSC-0040`
+- Future Game-to-Game switching: `DSC-0043`
+
+## Propagacao Necessaria
+
+- Add implementation plans for introducing VM sessions and moving VM context
+  out of `Firmware`.
+- Add implementation plans for separating VM-scoped runtime state from global
+  SystemOS/render state.
+- Update runtime/firmware specs to describe session-owned VM context and the
+  distinction between foreground ownership and execution eligibility.
+- Update tests for Game resident suspension, VM-backed Shell creation, and
+  session isolation.
+- Keep future background execution as out of scope for first implementation,
+  but document that the model must support background-capable scheduling.
+
+## Revision Log
+
+- 2026-07-04: Initial decision draft from `AGD-0046`.

discussion/workflow/plans/PLN-0148-introduce-vm-session-registry-and-identity.md

@@ -0,0 +1,92 @@
+---
+id: PLN-0148
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Introduce VM Session Registry and Identity
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.
+
+The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.
+
+## Objective
+
+Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
+- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.
+
+## Scope
+
+- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
+- Add a `VmSession` data structure containing at least:
+  - owning `TaskId`;
+  - owning process id or process lookup path;
+  - `app_id`, title, version, and `AppMode`;
+  - initial placeholder for the session-owned `VirtualMachine`;
+  - initial placeholder for session-owned runtime state to be populated by PLN-0149.
+- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
+- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
+- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
+- Enforce V1 uniqueness:
+  - at most one resident Game session;
+  - one foreground Shell task at a time;
+  - same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.
+
+## Non-Goals
+
+- Do not move all VM runtime fields yet; that is PLN-0149.
+- Do not route cartridge loading through sessions yet; that is PLN-0150.
+- Do not remove `Firmware.vm` yet.
+- Do not implement general background execution.
+- Do not allow Game-to-Game switching.
+
+## Execution Method
+
+1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
+2. Add the VM session module with a small API:
+   - create session for an existing VM-backed task/process;
+   - get immutable/mutable session by task id;
+   - get resident Game session by `app_id`;
+   - reject incompatible duplicate Game sessions.
+3. Wire the registry into `SystemOS`.
+4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
+5. Keep native Shell task creation out of the VM session registry.
+6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.
+
+## Acceptance Criteria
+
+- `SystemOS` owns a VM session registry.
+- Creating a VM Game task creates exactly one VM session associated with that task.
+- Creating a VM Shell task creates exactly one VM session associated with that task.
+- Creating a native Shell task creates no VM session.
+- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
+- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
+- No firmware state transition depends on the new registry yet except through task/session creation.
+
+## Tests
+
+- `cargo test -p prometeu-system`
+- Add unit tests for:
+  - VM Game task creates a VM session;
+  - VM Shell task creates a VM session;
+  - native Shell task does not create a VM session;
+  - lookup by `TaskId`;
+  - same resident Game `app_id` resolves to the existing session;
+  - different resident Game `app_id` remains blocked under V1.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-system/src/os/system_os.rs`
+- `crates/console/prometeu-system/src/os/facades/sessions.rs`
+- `crates/console/prometeu-system/src/services/mod.rs`
+- New or extended module under `crates/console/prometeu-system/src/services/`
+- `crates/console/prometeu-system/src/lib.rs` if exports are required

discussion/workflow/plans/PLN-0149-move-vm-runtime-state-into-vm-sessions.md

@@ -0,0 +1,99 @@
+---
+id: PLN-0149
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Move VM Runtime State Into VM Sessions
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 states that mutable VM context must belong to the VM-backed process session, not to firmware or a single global runtime slot. The current split has `Firmware.vm: VirtualMachine` and `SystemOS.vm_runtime: VirtualMachineRuntime`, which makes a suspended Game vulnerable to VM-backed Shell execution.
+
+This plan migrates mutable per-application VM runtime state into the session model introduced by PLN-0148 while keeping global OS services global.
+
+## Objective
+
+Make each VM session own the state needed to suspend and later resume that VM-backed process without being overwritten by another VM-backed process.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Requires PLN-0148.
+- Must precede full cartridge-loading and scheduler migration in PLN-0150 and PLN-0151.
+
+## Scope
+
+- Classify `VirtualMachineRuntime` fields into session-owned versus global OS-owned state.
+- Move session-owned fields into the `VmSession` context.
+- Keep global services in `SystemOS`, including:
+  - `LogService`;
+  - process/task/window managers;
+  - foreground stack;
+  - durable `MemcardService`;
+  - global render publication authority or worker coordination that must remain host-facing.
+- Treat these as session-owned unless proven otherwise during implementation:
+  - `VirtualMachine`;
+  - current cartridge identity;
+  - frame and tick counters;
+  - lifecycle delivery bookkeeping;
+  - crash report for that session;
+  - pause/debug flags that apply to that session;
+  - per-session open files, handles, and staging state used by VM syscalls.
+- Keep durable memcard contents keyed by `app_id`; do not turn save data into session-private durable storage.
+- Update `VmFacade` and VM runtime helpers so callers can operate on a selected session.
+
+## Non-Goals
+
+- Do not redesign render workers beyond separating session-local render command state from global presentation authority.
+- Do not implement background execution.
+- Do not change syscall semantics except where required to route state through the active session.
+- Do not remove host debugger features; preserve or adapt their access path.
+
+## Execution Method
+
+1. Add an internal field-by-field classification comment or test-only assertion near `VirtualMachineRuntime` before moving fields.
+2. Introduce a session runtime/context type in the VM session module or by splitting `VirtualMachineRuntime` into:
+   - session-local runtime;
+   - global render/log/runtime services.
+3. Move `VirtualMachine` ownership from firmware placeholder/session stub into the session context.
+4. Move per-cartridge and per-frame state from `SystemOS.vm_runtime` into the session context.
+5. Move `open_files`, `next_handle`, and VM syscall staging state out of global `SystemOS` if they are VM-session specific.
+6. Update `VmRuntimeHost` in `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` to receive session-local state plus references to required global services.
+7. Update `VmFacade` in `crates/console/prometeu-system/src/os/facades/vm.rs` with explicit session-targeted methods.
+8. Preserve temporary compatibility methods only where needed for existing host/debugger code, and mark them as active-session views rather than canonical global ownership.
+9. Add tests proving two VM sessions can hold different app identity and counters at the same time.
+
+## Acceptance Criteria
+
+- No canonical VM state lives in `Firmware`.
+- `SystemOS` can hold at least two VM sessions with independent `VirtualMachine` and per-session runtime state.
+- VM session A and VM session B can have different `app_id`, title, frame counters, lifecycle delivery history, crash report, open file handles, and debug pause state.
+- Durable memcard contents remain shared by `app_id` according to the existing memcard contract.
+- Global render ownership remains controlled by SystemOS/host-facing runtime services, not by individual sessions.
+- Existing `prometeu-system` VM runtime tests still pass after adapting their setup.
+
+## Tests
+
+- `cargo test -p prometeu-system`
+- `cargo test -p prometeu-firmware`
+- Add tests for:
+  - independent session app identity;
+  - independent tick/logical-frame counters;
+  - independent lifecycle delivery bookkeeping;
+  - VM Shell session initialization does not mutate resident Game session identity;
+  - session-scoped file handles do not collide across sessions.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-system/src/services/vm_runtime/`
+- VM session module introduced by PLN-0148
+- `crates/console/prometeu-system/src/os/facades/vm.rs`
+- `crates/console/prometeu-system/src/os/system_os.rs`
+- `crates/console/prometeu-system/src/os/facades/fs.rs`
+- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
+- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
+- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
+- `crates/host/prometeu-host-desktop-winit/src/stats.rs`

discussion/workflow/plans/PLN-0150-route-cartridge-loading-through-vm-sessions.md

@@ -0,0 +1,90 @@
+---
+id: PLN-0150
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Route Cartridge Loading Through VM Sessions
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current `LoadCartridgeStep` initializes `ctx.os.vm().initialize(ctx.vm, &cartridge)` before task/session ownership is selected.
+
+This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.
+
+## Objective
+
+Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Requires PLN-0148.
+- Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
+- Must precede the end-to-end coexistence validation in PLN-0152.
+
+## Scope
+
+- Replace direct global VM initialization in `LoadCartridgeStep`.
+- Add a session/facade operation that:
+  - selects an existing resident Game session when the same `app_id` is relaunched;
+  - rejects or reports different resident Game launches under V1;
+  - creates a new VM Shell session for a Shell cartridge;
+  - initializes the cartridge inside the selected session VM.
+- Keep asset manager initialization aligned with the foreground cartridge being launched.
+- Ensure `AppCrashesStep` receives initialization failures from the target session.
+- Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.
+
+## Non-Goals
+
+- Do not implement multiple resident Games.
+- Do not implement background execution.
+- Do not redesign cartridge format or asset packaging.
+- Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.
+
+## Execution Method
+
+1. Add a `load_vm_cartridge` or equivalent method to `SessionsFacade` or `VmFacade`.
+2. Make the method return an execution target:
+   - existing Game task for same resident `app_id`;
+   - new Game task for first Game launch;
+   - new VM Shell task for Shell launch;
+   - structured error/crash report for invalid VM initialization;
+   - explicit lifecycle error for blocked second Game.
+3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` to call the facade method instead of initializing `ctx.vm`.
+4. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` so same-Game relaunch checks session/lifecycle state rather than `ctx.os.vm().current_app_id()`.
+5. Preserve AppMode-based transition:
+   - Game target transitions to `GameRunning`;
+   - Shell target creates/focuses a window and transitions to `ShellRunning`.
+6. Adapt crash tests and resident-game relaunch tests in firmware.
+
+## Acceptance Criteria
+
+- `LoadCartridgeStep` no longer initializes a global firmware VM.
+- Loading a Shell cartridge creates/initializes a Shell VM session.
+- Loading the first Game cartridge creates/initializes the resident Game VM session.
+- Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
+- Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
+- VM initialization failure still transitions to `AppCrashesStep`.
+
+## Tests
+
+- `cargo test -p prometeu-firmware`
+- `cargo test -p prometeu-system`
+- Add or update firmware tests for:
+  - first Game load creates one session and enters `GameRunning`;
+  - same Game relaunch resumes existing task/session;
+  - VM Shell load creates a distinct session;
+  - Shell load does not change resident Game session app identity;
+  - invalid cartridge reports `CrashReport::VmInit`.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
+- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
+- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
+- `crates/console/prometeu-system/src/os/facades/sessions.rs`
+- `crates/console/prometeu-system/src/os/facades/vm.rs`
+- VM session module introduced by PLN-0148

discussion/workflow/plans/PLN-0151-schedule-foreground-vm-session-ticks.md

@@ -0,0 +1,92 @@
+---
+id: PLN-0151
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Schedule Foreground VM Session Ticks
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 separates session ownership from foreground ownership and states that V1 does not provide general background execution. The runtime therefore needs an explicit scheduler path that ticks the VM session eligible for foreground execution, while leaving suspended resident Game sessions intact.
+
+## Objective
+
+Make firmware and SystemOS tick the VM session associated with the current foreground VM-backed task, instead of ticking a global VM/runtime pair.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Requires PLN-0148.
+- Requires PLN-0149.
+- Requires PLN-0150 for loaded cartridges to map to sessions.
+
+## Scope
+
+- Add scheduler/facade operations that tick a specific VM session by `TaskId`.
+- Update `GameRunningStep` to tick the Game session identified by its `task_id`.
+- Update `ShellRunningStep` to tick only VM-backed Shell sessions.
+- Ensure native Shell foreground state performs native profile updates without ticking any VM session.
+- Keep suspended Game sessions non-executing while Hub or Shell is foreground.
+- Preserve lifecycle event delivery:
+  - pause/resume events go to the resident Game session;
+  - Shell lifecycle events, if any, remain scoped to the Shell session.
+- Preserve host debugger pause/step behavior against the active VM session view.
+
+## Non-Goals
+
+- Do not add background execution classes yet.
+- Do not allow multiple simultaneous VM ticks in one host frame.
+- Do not implement general service/player processes.
+- Do not change the 60 Hz firmware tick contract.
+
+## Execution Method
+
+1. Add `SystemOS` facade methods for:
+   - ticking a VM session by task id;
+   - querying whether a task is VM-backed;
+   - exposing the active VM session to host/debugger tooling.
+2. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs` to tick through the task/session facade.
+3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs` to branch on process kind:
+   - VM Shell ticks its VM session;
+   - native Shell runs native profile logic only.
+4. Remove direct `ctx.vm` use from Game/Shell execution steps.
+5. Ensure resident Game pause budget can deliver one final pause tick and then stop ticking once suspended.
+6. Update host/debugger active VM access paths to resolve through the foreground session.
+7. Add regression tests for tick counters across Game, Hub, native Shell, and VM Shell transitions.
+
+## Acceptance Criteria
+
+- A suspended Game session does not advance while Hub is foreground.
+- A suspended Game session does not advance while a Shell is foreground.
+- A VM Shell session advances while that VM Shell is foreground.
+- A native Shell does not tick any VM session.
+- Returning from Hub to resident Game resumes ticking the same Game session.
+- Host debugger and stats read the active VM session, not a stale global VM.
+
+## Tests
+
+- `cargo test -p prometeu-firmware`
+- `cargo test -p prometeu-system`
+- `cargo test -p prometeu-host-desktop-winit`
+- Add tests for:
+  - Game tick count freezes after Home suspension;
+  - VM Shell tick count advances independently;
+  - native Shell does not advance Game tick count;
+  - resume returns to same Game session tick counter;
+  - active-session debugger snapshot uses foreground VM session.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
+- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
+- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
+- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
+- `crates/console/prometeu-system/src/os/facades/vm.rs`
+- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
+- VM session module introduced by PLN-0148
+- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
+- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
+- `crates/host/prometeu-host-desktop-winit/src/stats.rs`

discussion/workflow/plans/PLN-0152-validate-game-and-vm-shell-session-coexistence.md

@@ -0,0 +1,86 @@
+---
+id: PLN-0152
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Validate Game and VM Shell Session Coexistence
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 was motivated by the concrete failure mode where a resident Game is suspended, a Shell is opened, and Game logs or state unexpectedly continue under the wrong foreground owner. After VM sessions and scheduling are implemented, the system needs explicit regression coverage for this workflow.
+
+## Objective
+
+Add end-to-end and integration validation proving a resident Game VM session and a VM-backed Shell session can coexist without overwriting or ticking each other incorrectly.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Requires PLN-0148, PLN-0149, PLN-0150, and PLN-0151.
+- Should be executed before closing the broader DEC-0038 implementation thread.
+
+## Scope
+
+- Add firmware-level regression tests for:
+  - Game launch;
+  - Home/SystemOS request;
+  - Game pause/suspend;
+  - VM Shell launch;
+  - Shell foreground ticking;
+  - Shell exit;
+  - Hub return;
+  - resident Game resume.
+- Add system-level tests for independent session state.
+- Add host-level tests only where active VM/debugger/stat routing cannot be covered at firmware/system level.
+- Verify logs from the stress cartridge or equivalent test cartridge do not appear while Game is suspended and Shell is foreground.
+- Verify Shell logs, frames, or tick counters belong to the Shell session.
+
+## Non-Goals
+
+- Do not introduce new architecture in this plan.
+- Do not broaden background execution.
+- Do not rewrite Hub UI behavior except where required to exercise the flow.
+- Do not depend on manual desktop testing as the only evidence.
+
+## Execution Method
+
+1. Identify or add deterministic test cartridges/helpers that can emit per-session tick/log evidence.
+2. Add a firmware integration test for `Game -> Home -> VM Shell -> Hub -> same Game`.
+3. Capture Game session counters before Shell launch and after Shell foreground ticks.
+4. Assert the Game session counters and lifecycle delivery state remain stable while Shell is foreground.
+5. Assert the Shell session counters advance while Shell is foreground.
+6. Assert returning to the same Game resumes the same task/session and then advances the Game counter.
+7. Add a regression specifically covering the prior symptom: Game `stress` logs must not appear during Shell foreground execution.
+8. Run the relevant crate tests and record evidence in the plan completion notes when implemented.
+
+## Acceptance Criteria
+
+- The failing manual scenario is covered by automated tests.
+- The Game session is suspended and non-ticking while VM Shell is foreground.
+- The VM Shell session ticks independently.
+- Returning to Hub and selecting the same Game resumes the resident Game session instead of creating a duplicate process/session.
+- No test relies on a single global `current_app_id` to infer correctness.
+
+## Tests
+
+- `cargo test -p prometeu-system`
+- `cargo test -p prometeu-firmware`
+- `cargo test -p prometeu-host-desktop-winit` if host active-session plumbing changed.
+- Optional manual smoke:
+  - run `cargo run --bin prometeu-host-desktop-winit --profile release --manifest-path crates/host/prometeu-host-desktop-winit/Cargo.toml -- --games-root test-cartridges`;
+  - open Stress Console;
+  - press ESC/Home;
+  - open VM-backed Shell;
+  - verify no Stress logs appear while Shell is foreground;
+  - return and resume Stress Console.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-firmware/src/firmware/firmware.rs` tests
+- `crates/console/prometeu-system/src/os/system_os.rs` tests
+- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
+- `crates/host/prometeu-host-desktop-winit/src/runner.rs` tests if needed
+- `test-cartridges/` only if a deterministic VM Shell fixture is missing

discussion/workflow/plans/PLN-0153-specify-vm-session-ownership-and-background-ready-scheduling.md

@@ -0,0 +1,82 @@
+---
+id: PLN-0153
+ticket: foreground-stack-game-pause-shell-vm-backed
+title: Specify VM Session Ownership and Background-Ready Scheduling
+status: open
+created: 2026-07-04
+ref_decisions: [DEC-0038]
+tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
+---
+
+## Briefing
+
+DEC-0038 locks the runtime direction: VM context is session-owned, firmware orchestrates macro-state, and background execution is out of V1 but must remain a near-term compatible extension. The canonical specs must describe that contract in English so future implementation and debugging do not drift back to a single global VM model.
+
+## Objective
+
+Update canonical runtime specifications to document VM session ownership, foreground execution eligibility, render publication authority, and the background-ready shape of the scheduler without committing to background execution in this implementation batch.
+
+## Dependencies
+
+- Source decision: DEC-0038.
+- Should be informed by PLN-0148 through PLN-0151 once implementation names settle.
+- May be done before PLN-0152 if the implementation contract is already stable, but final wording must match implemented APIs.
+
+## Scope
+
+- Update the canonical specs under `docs/specs/runtime/` in English.
+- Document:
+  - each VM-backed process owns one VM session;
+  - VM sessions own mutable VM context;
+  - foreground ownership and execution eligibility are separate concepts;
+  - V1 executes only the foreground VM-backed task, except the existing pause handoff budget;
+  - suspended resident Game sessions preserve VM context but do not tick;
+  - VM-backed Shell sessions have their own VM context;
+  - native Shell does not own a VM session;
+  - durable app data remains keyed by `app_id`;
+  - session-scoped handles and staging state are not durable app data;
+  - global render publication remains SystemOS/host authority.
+- Add background-ready wording:
+  - scheduler model can later mark sessions or service processes as eligible without changing ownership;
+  - no current guarantee of background progress is introduced.
+
+## Non-Goals
+
+- Do not write implementation plans into specs.
+- Do not document background execution as available.
+- Do not move normative text into `discussion/lessons/`.
+- Do not create new legacy docs paths.
+
+## Execution Method
+
+1. Locate the most relevant runtime specs, likely:
+   - `docs/specs/runtime/09-events-and-concurrency.md`;
+   - `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`;
+   - `docs/specs/runtime/14-boot-profiles.md`;
+   - `docs/specs/runtime/16-host-abi-and-syscalls.md` if host/debugger active VM views are affected.
+2. Add concise normative sections using `MUST`, `MUST NOT`, and `SHALL` where appropriate.
+3. Keep discussion history out of the spec; cite behavior, not agenda chronology.
+4. Align terminology with implemented type names from PLN-0148 through PLN-0151.
+5. Run discussion validation after edits and any repository tests required by touched docs tooling.
+
+## Acceptance Criteria
+
+- Specs explicitly state that VM context is session-owned for VM-backed processes.
+- Specs explicitly state that native Shell does not own a VM session.
+- Specs distinguish foreground ownership from future execution eligibility.
+- Specs state that V1 does not support general background execution.
+- Specs preserve a future path for background-capable sessions/services without changing VM ownership.
+- No new framework artifacts are written outside `discussion/`.
+
+## Tests
+
+- `discussion validate`
+- Manual review of touched specs for English-only normative text.
+- Run repository doc checks if such a command exists; otherwise no code test is required for this plan.
+
+## Affected Artifacts
+
+- `docs/specs/runtime/09-events-and-concurrency.md`
+- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
+- `docs/specs/runtime/14-boot-profiles.md`
+- `docs/specs/runtime/16-host-abi-and-syscalls.md` if active VM host/debugger wording is needed