BT411/phases/phase-12-orphan-processes.md

Phase 12 — orphaned processes, the terminal that never closes, and the MP-hiccup claim

2026-07-27. Triggered by an operator report: "if you X close the game window it leaves the terminal/console open sometimes, and leaves orphaned processes — I think this is a major contributor to multiplayer game hiccups."

All findings below were produced against 4.11.600 on the dev rig, not recalled. Harnesses live in scratchpad/orphan_*.ps1, scratchpad/btwait_probe.ps1, scratchpad/test_loop_logic.ps1.

---

What the process actually owns

A running pod owns four top-level windows (enumerated live, orphan_win.ps1):

class	title	size	X does
MainWndClass	BattleTech 4.11.600 — node 1601	1468x1038	destroy → real exit
BTPlasmaWnd	BattleTech - Plasma	528x167	hide only (L4PLASMAWIN.cpp:21)
MSCTFIME UI / IME	—	0x0	OS input plumbing

Under BT_GLASS_PANELS the per-display panels (L4GLASSWIN.cpp:693) and the pad panel (L4PADPANEL.cpp:468) behave like the plasma window: ShowWindow(SW_HIDE), never quit.

Finding 1 — closing the MAIN window is CLEAN [T2]

Verified in three states: solo mid-model-load ([loadobj] active), the relay join wait, and 16 s after a real console launch. Every run: process exited ~1 s, no relaunch, no orphan, and the relay logged PLAYER 1 LEFT ... (0 seated). The close-means-quit gate (ecb9b33) works.

So the orphans the playtesters saw are consistent with 584 and earlier, where every window close hit BTFE_RelaunchSelfAndExit and resurrected the client. That is already fixed in 600 and still awaiting-verification.

Finding 2 — closing an AUX window hides it irrecoverably [T2]

X on the plasma window (or a glass panel) hides it with no way to bring it back — no menu item, no hotkey — while the game runs on. Verified: vis=True → vis=False, process alive, both relay sockets still Established. Not an orphan (the main window is still there), but it explains the report "eventually all I could find was my plasma display": the small plasma window is what survives when the big one is gone, and a player who closes it has silently lost it for the session.

Finding 3 — the terminal that never closes [T2] — FIXED

join.bat's :btwait loop waited for any btl4.exe on the machine:

for /f "tokens=1" %%P in ('tasklist /FI "IMAGENAME eq btl4.exe" /NH') do (
    if /I "%%P"=="btl4.exe" set "BT_STILL_RUNNING=1"
)

Proved with btwait_probe.ps1: a bat that launched nothing reports would KEEP SPINNING purely because an unrelated instance is alive. So the window never prints its sign-off and looks hung whenever anything else is running — a second client, the operator's own pod, or a genuine orphan. This is the reported symptom, and it is a detector of an orphan, not a cause.

All four launchers carried the identical block. Fixed by snapshotting the PIDs alive before the launch and only waiting on PIDs absent from that snapshot. The if /I "%%P"=="btl4.exe" guard is retained deliberately: tokens=2 alone would parse tasklist's "INFO: No tasks are running" line as a PID and spin forever with nothing running — a worse bug than the one being fixed.

Verified with the text lifted verbatim out of the shipped play_solo.bat:

case	expected	got
nothing running (regression guard)	sign off	sign off
someone else's instance alive	sign off	sign off
our own generation alive	keep waiting	keep waiting
decoy gone, re-check	sign off	sign off

The patched bat still launches the game (pid + launch_report.txt confirmed). Not verified: the full handoff E2E — the bat blocks on the FE menu, which waits for human input, so an automated run never reaches :btwait. Needs one human run.

Note the bat also ends in pause by design, so the window always stays until a keypress. That is intended and is a second, benign reason a terminal is "still open".

Finding 4 — BTLoadPump eats WM_QUIT [T3, latent]

L4VIDEO.cpp:9039 drains the queue during mission load:

while (PeekMessageA(&msg, NULL, 0, 0, PM_REMOVE)) { TranslateMessage(&msg); DispatchMessageA(&msg); }

WM_QUIT dispatched this way is silently discarded — it belongs to no window — so a quit posted during load is destroyed and APPMGR.cpp:102's pump never sees it. This did not produce a hang in testing (the destroyed HWND breaks rendering, which tears the process down another way), so it is not today's orphan mechanism. Flagged as a trap: any future code that relies on WM_QUIT surviving a load will fail here.

The multiplayer-hiccup claim — verdict

The mechanism is real conditional on an orphan existing: an orphan keeps both TCP connections to the relay (:1600 console and :1601 game) Established, so the relay counts a pilot who will never ready — and SEAT_LEFT_GRACE_SECONDS never starts, because nothing ever left. That matches "waiting for mission assignment" forever.

But no orphan could be produced from an X-close in 4.11.600. So on the current build the more likely contributor is Finding 3: a second instance (the operator's own pod is enough) hangs every join window, which reads as "the game didn't exit", which invites people to kill processes and relaunch — and that is what manufactures real ghosts.

Follow-ups

• Aux windows should either refuse to close or be restorable (Finding 2).
• Consider making BTLoadPump re-post WM_QUIT instead of swallowing it (Finding 4).
• The :btwait fix reaches players only when the zip is re-cut; 4.11.600 as shipped still has the machine-wide wait.