Repository navigation
Supervisor spawn opens a visible console window on Windows despite DETACHED_PROCESS #9
Description
Summary
On Windows 11 (rtfm-ai 0.37.1, Python 3.12), every time the supervisor is spawned — via rtfm worker start, rtfm sync, or any hook/MCP call that triggers ensure_worker_running() — a visible console window briefly pops up. Over a session with repeated spawns (retrying after kills, testing, etc.) I accumulated 32 orphaned conhost.exe processes that never got cleaned up.
Root cause
rtfm/core/portable.py:
def detached_popen_kwargs() -> dict:
if sys.platform == "win32": # pragma: no cover - Windows only
return {"creationflags": (subprocess.DETACHED_PROCESS
| subprocess.CREATE_NEW_PROCESS_GROUP)}
return {"start_new_session": True}DETACHED_PROCESS prevents the child from inheriting the parent's console, but depending on how the parent itself was launched (e.g. from within a Node.js child_process.spawn, or a shell that's itself conhost-backed), Windows can still allocate a new console for the child rather than truly running it headless — which is what produces the visible popup and the orphaned conhost.exe.
Suggested fix
Add subprocess.CREATE_NO_WINDOW to the creation flags:
return {"creationflags": (subprocess.DETACHED_PROCESS
| subprocess.CREATE_NEW_PROCESS_GROUP
| subprocess.CREATE_NO_WINDOW)}This is the standard combination for a fully headless background process on Windows — CREATE_NO_WINDOW specifically suppresses console allocation regardless of the parent's own console state, which DETACHED_PROCESS alone doesn't guarantee.
Repro
- Windows 11, rtfm-ai 0.37.1.
- From a terminal (in my case, invoked indirectly via a Node-based process — Claude Code's Bash tool), run
rtfm worker startor trigger any hook that callsensure_worker_running(). - Observe a console window flash/open briefly.
- Repeat several times (e.g. testing, restarting after a kill) — check
tasklist /FI "IMAGENAME eq conhost.exe"afterward; orphaned entries accumulate with no owning visible window left.
Impact
Cosmetic/annoying rather than functionally broken — the supervisor itself works correctly — but it's a visible, repeated distraction for anyone driving rtfm from an agent/automation context (Claude Code, CI, etc.) where a popping-up console window is unexpected and alarming, and the orphaned conhost.exe processes are a minor resource leak over a long session.
Happy to test a fix if useful — reporting this alongside separate testing of the Windows worker/lock fixes in #8.
Activity
fix(windows): nothing RTFM starts opens a window any more
roomi-fields commentedon Sep 3, 2026
Fixed in 0.37.2, on PyPI now — but not the way you proposed, and the difference matters, so here is the reasoning.
CreateProcessdocumentsCREATE_NO_WINDOWas ignored when it is used withDETACHED_PROCESS. Adding it todetached_popen_kwargs()would have compiled, shipped, and changed nothing. Your symptom was real, so I went looking for what else could produce it.It is one level down, and worse than the report assumed.
DETACHED_PROCESSmeans the supervisor has no console at all — and a console program started by a parent that has none is handed a brand new console by Windows, window andconhost.exeand all. The supervisor spawns a child interpreter for every PDF it reads, to keep pdfium's segfaults out of its thread pool (that isolation is why 0.29.0 exists). Marker anddjvutxtare spawned the same way.So the flashes were never one per
worker start. They were one per document. Your 32 orphans came from threeworker startcalls doing nothing wrong and a handful of files being indexed behind them; on a PDF corpus it would have been thousands.Two rules now:
pythonw.exe— the windowed build of the same interpreter, shipped besidepython.exe, which never gets a console in the first place. Falls back topython.exewhere it is absent, because a console flash is a nuisance and no indexing at all is not. The supervisor writes to~/.rtfm/supervisor.log, never to a terminal, so nothing is lost.djvutxt— carriesCREATE_NO_WINDOW. There your flag is exactly right and is not ignored, because nothing detaches those children: they are waited on and their streams are pipes.A test now walks every
subprocesscall in the package and fails on any that carries neither policy, since this package spawns children as a matter of course. I verified it catches a bare spawn by removing one flag and watching it name the file and line.Still unverified on Windows, as ever — I'd be glad to know whether the flashes are actually gone, and whether
tasklist /FI "IMAGENAME eq conhost.exe"stays flat while a PDF-heavy repo indexes. That second one is the real test;worker startalone would only have exercised the easy path.And: you are in the README now. Every command of this thing was broken on Windows and RTFM is developed on Linux, so without your reporting and the testing you did on real hardware it would simply have stayed broken. Thank you.
roomi-fields commentedon Oct 30, 2026
Closing: the fix shipped in 0.37.2 (pythonw.exe for the detached supervisor, CREATE_NO_WINDOW for short-lived helpers) and nothing has come back since. If the console windows or the conhost.exe orphans reappear on a current version, please reopen with the version and I'll dig in. Thanks again for the Windows testing.