agent-wiki-ui/docs/adr/0005-windows-senza-console.md

ADR-0005 — Windows: eseguibile senza finestra di console

• Stato: Proposta
• Data: 2026-10-15
• Collegato a: ADR-0001 (GUI e piattaforme)

Contesto

Su Windows l'eseguibile è di tipo "console" (OutputType Exe): con il doppio clic, oltre alla finestra della GUI si apre anche un terminale vuoto che resta aperto finché l'app gira. Il tipo console serve alla CLI (agent-wiki-ui.exe "prompt"), perché da terminale cmd e PowerShell aspettano la fine del programma, mostrano l'output e danno l'exit code. Un eseguibile "GUI" non ha console, ma allora la CLI perde queste proprietà. Su Linux il problema non esiste: nessuna finestra extra.

Criteri di decisione

1. Doppio clic: solo la finestra della GUI.
2. La CLI deve continuare a mostrare l'output nel terminale da cui parte, anche con reindirizzamenti (> file, | altro).
3. Un solo file da distribuire, come per Linux.
4. Nessun cambiamento per Linux.

Opzioni considerate

Opzione	Esito	Motivo
Lasciare il tipo console e nascondere la finestra all'avvio (FreeConsole)	Scartata	La finestra compare comunque per un istante; con Windows Terminal come terminale predefinito può restare una scheda.
Due file: agent-wiki-ui.exe (senza console) e agent-wiki-ui-cli.exe (con console)	Alternativa valida	Nessuna perdita nella CLI (exit code corretto ovunque), ma due file da distribuire e da spiegare. Da riprendere se l'exit code della CLI diventa importante in Windows.
Un solo .exe senza console; la CLI riaggancia il terminale padre	Scelta	Un file, doppio clic pulito, output visibile nel terminale.

Decisione

• Il progetto usa OutputType WinExe (sottosistema Windows). Su Linux non cambia nulla.
• Con argomenti (modalità CLI) su Windows, Core/ConsoleHost.cs chiama AttachConsole(ATTACH_PARENT_PROCESS): se parte da cmd, PowerShell o Windows Terminal l'app usa quel terminale. Se l'output standard non è già valido (non è reindirizzato) lo collega alla console (CONOUT$); se è un file o una pipe ereditati li lascia stare, così > file e | funzionano. Il motore avviato dopo eredita gli stessi handle.
• Senza terminale padre (doppio clic, avvio da un altro programma) l'attacco fallisce in silenzio e l'app prosegue.
• Senza argomenti (GUI) non si tocca la console.

Conseguenze

Positive: il doppio clic mostra solo la finestra; un unico file; output e reindirizzamenti della CLI funzionano. Negative / costi — comportamento della CLI su Windows:

• cmd e PowerShell non aspettano la fine di un programma a sottosistema Windows: il prompt torna subito e l'output compare dopo, mescolato al prompt.
• L'exit code non arriva a %ERRORLEVEL% né a $LASTEXITCODE in uso interattivo. Arriva se il chiamante aspetta il processo: start /wait agent-wiki-ui.exe "prompt" in cmd, Start-Process -Wait -NoNewWindow o & .\agent-wiki-ui.exe "prompt" | Out-Host in PowerShell, script e programmi che attendono il processo figlio. In pipeline (| Out-Host, | more) PowerShell attende.
• Su Linux e macOS il comportamento della CLI resta quello di sempre (exit code propagato, streaming).
• Il criterio di accettazione dell'MVP sull'exit code vale quindi, su Windows, solo se il chiamante attende il processo.

Da verificare

• Doppio clic su Windows nativo: nessuna finestra di console.
• Da cmd, PowerShell e Windows Terminal: output visibile, reindirizzamento su file e pipe, exit code con start /wait e con Start-Process -Wait.
• Output corretto quando il processo è avviato da un altro programma senza terminale.
• Il sottosistema dell'eseguibile pubblicato risulta "Windows GUI" (controllato sull'intestazione PE).

Riferimenti

• Passi: ROADMAP.md, Fase 5.
• Righe di test: TESTING.md, righe WIN.