From f7e79048b9aa27f0545239b7eddf9f46ebc7a031 Mon Sep 17 00:00:00 2001
From: kerzhaev <57300165+kerzhaev@users.noreply.github.com>
Date: Sat, 29 Aug 2026 19:34:17 +0100
Subject: [PATCH] docs(hooks): explain why the detached launcher uses
 CREATE_NO_WINDOW (Win11 focus-steal)

Add a comment warning against reverting the Windows detached spawn to DETACHED_PROCESS:
DETACHED_PROCESS lets the child allocate its own console, which Windows 11 + Windows
Terminal render as a visible focus-stealing window, so CREATE_NO_WINDOW is required.
---
 graphify/hooks.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/graphify/hooks.py b/graphify/hooks.py
index ab4289079..e535e1913 100644
--- a/graphify/hooks.py
+++ b/graphify/hooks.py
@@ -246,7 +246,14 @@ except Exception as exc:
 # the real rebuild fully detached and returns immediately, so the hook never
 # blocks. POSIX uses start_new_session (the setsid equivalent); Windows uses
 # CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP, breaking away from any job object
-# when allowed. This payload is carried inside a shell double-quoted -c argument,
+# when allowed. Do NOT 'simplify' CREATE_NO_WINDOW back into DETACHED_PROCESS:
+# on Windows 11 with Windows Terminal as the default console host, a
+# console-less python still gets a VISIBLE console allocated when its runtime
+# touches the console API during startup (ctrl-handler installation), popping
+# an empty Terminal window over whatever the user is doing - once per commit,
+# for the whole rebuild. Reproduced via GetConsoleWindow(): DETACHED_PROCESS
+# child reports a visible hwnd, CREATE_NO_WINDOW child reports none (3bac3df).
+# This payload is carried inside a shell double-quoted -c argument,
 # so it deliberately uses only single-quoted Python strings (no ", $, ` or \\).
 _LAUNCHER_TEMPLATE = """\
 import os, subprocess, sys