---
id: DEC-0040
ticket: hub-suspended-game-kill-affordance
title: Hub Suspended Game Kill Affordance
status: accepted
created: 2026-07-05
ref_agenda: AGD-0047
tags: [hub, lifecycle, game, ui]
---

## Context

O Hub pode ficar ativo enquanto existe um jogo `Game` residente/suspenso apos Home/ESC. Esse estado e intencional para retomada, mas hoje nao fica visivel o suficiente e nao ha uma acao direta no Hub para matar o jogo sem iniciar outro cartridge.

A troca de cartridges ja encerra a VM anterior antes de carregar o proximo jogo. Esta decision define o affordance manual equivalente no Hub.

## Decision

O Hub MUST exibir um indicador de jogo suspenso quando houver exatamente um jogo `Game` residente/suspenso associado ao lifecycle do SystemOS.

O indicador MUST:

- aparecer somente para jogos do perfil `Game`;
- mostrar somente o nome/titulo do jogo suspenso;
- ficar no canto inferior direito do Hub;
- ser apresentado como uma caixa vermelha;
- funcionar como controle destrutivo: um clique MUST matar imediatamente o jogo suspenso;
- desaparecer no mesmo fluxo em que o jogo deixa de ser residente.

O clique no indicador MUST reutilizar o mesmo caminho de encerramento de jogo residente usado pelo cartridge switching. A implementacao MUST NOT criar um segundo caminho parcial de cleanup.

Ao matar o jogo pelo Hub, o runtime MUST limpar o estado pertencente ao jogo residente:

- task/process lifecycle;
- VM session;
- resident game state;
- render ownership retornando ao Shell/Hub;
- game audio pause/lifecycle state;
- Game2D composer binding/cache state;
- cartridge asset manager state and physical memory banks associated with the resident game.

O Hub MUST permanecer no Hub apos a acao. O jogo morto MUST NOT ser retomavel depois do kill. A acao MUST emitir um log `INFO` explicito, com source `HUB` ou `POS`, equivalente a `Resident game killed from Hub: <title>`.

Nao havera confirmacao ou segundo clique nesta versao. A cor vermelha e a posicao dedicada sao o affordance de acao destrutiva.

## Rationale

O fluxo aprovado privilegia simplicidade operacional. A intencao do controle e fechar uma VM suspensa rapidamente, sem iniciar outro jogo apenas para forcar o encerramento do anterior.

Limitar a UI a jogos `Game` evita misturar semantics de shell/system apps com cartridge runtime. Reusar o caminho de termination existente reduz risco de divergencia entre "kill por troca de cartridge" e "kill manual pelo Hub", especialmente apos os bugs recentes envolvendo scene/glyph/assets residuais.

O kill imediato e aceitavel porque o controle e vermelho, posicionado como acao especifica, e opera sobre um jogo que ja esta fora do primeiro plano. Se futuramente houver save-state persistente ou risco maior de perda de progresso, uma nova decision pode revisar este contrato para confirmacao em dois passos.

## Implications

- O Hub precisa consultar estado de jogo residente/suspenso de forma explicita.
- A camada de lifecycle precisa expor uma operacao clara de matar jogo residente sem carregar outro cartridge.
- O cleanup manual precisa ter a mesma abrangencia do cleanup usado por switch.
- O render/presentation state nao pode continuar apontando para ownership/frame do jogo morto.
- Testes devem provar que o indicador aparece, que o clique mata, e que o jogo nao pode ser retomado depois.

## Propagation Targets

- specs: atualizar contrato de Hub/lifecycle se houver spec canonica aplicavel.
- plans: criar plano de execucao para UI do Hub, facade/lifecycle kill e testes.
- code: `prometeu_hub`, firmware/lifecycle facade, runtime cleanup, render/audio/assets cleanup conforme necessario.
- tests: Hub rendering/click hitbox, lifecycle termination, switch-vs-manual cleanup equivalence, no-resume-after-kill.
- docs: registrar lesson apenas apos execucao publicada.

## References

- Agenda: AGD-0047
- Related: DSC-0043 / DEC-0039 cartridge switch orchestrator