Skip to content

Self-improving AI Employees for everyone

fix(supervisor): surface Windows Job Object failures so orphans become detectable

trohitg8a64eb906e82
diff --git a/machina/pyproject.toml b/machina/pyproject.toml
index 30d75235..007a3d7c 100644
--- a/machina/pyproject.toml
+++ b/machina/pyproject.toml
@@ -9,6 +9,10 @@ dependencies = [
"psutil>=6",
"anyio>=4",
"python-dotenv>=1",
+ # Required on Windows for the supervisor's Job Object (machina/tree.py).
+ # Without it, child processes survive abnormal supervisor exit (SIGKILL,
+ # BSOD, console close) and accumulate as orphans across dev restarts.
+ # Floor 308 is the first release shipping prebuilt wheels for Python 3.13.
"pywin32>=308; platform_system == 'Windows'",
]
diff --git a/machina/supervisor.py b/machina/supervisor.py
index 895cfbf4..291cb925 100644
--- a/machina/supervisor.py
+++ b/machina/supervisor.py
@@ -287,9 +287,19 @@ class Manager:
stderr=subprocess.PIPE,
**spawn_kwargs,
) as proc:
- if sys.platform == "win32":
- add_to_job(proc.pid)
color = spec.color or "white"
+ if sys.platform == "win32":
+ # Best-effort enrollment in the supervisor's Job Object so
+ # the OS tree-kills the child if the supervisor itself
+ # dies abnormally. Loud warning (from tree.py) on failure.
+ if not add_to_job(proc.pid):
+ emit(
+ spec.name,
+ "yellow",
+ f"WARN: pid={proc.pid} not enrolled in Job Object -- "
+ f"orphan risk if supervisor crashes",
+ stream="stderr",
+ )
emit(spec.name, color, f"started pid={proc.pid}")
# Register for force-kill access on second Ctrl-C; deregister on
# exit so a restarted-then-died service doesn't leave a stale entry.
diff --git a/machina/tree.py b/machina/tree.py
index 4905ded8..6583bfce 100644
--- a/machina/tree.py
+++ b/machina/tree.py
@@ -48,40 +48,90 @@ def signal_group(pid: int, sig: signal.Signals = signal.SIGTERM) -> None:
# ---------------------------------------------------------------- Windows Job Object
class _JobObject:
- """Lazy-imported wrapper around a Windows Job Object."""
+ """Lazy-imported wrapper around a Windows Job Object.
+ Failure modes are surfaced to stderr instead of swallowed. When this
+ fails the supervisor cannot tree-kill children if it itself dies
+ abnormally (SIGKILL, BSOD, console close), so silent failure leads
+ directly to orphan-process accumulation on Windows.
+ """
+
+ # Win10/11 supports nested jobs, but the parent must allow it. When
+ # the supervisor was launched from another process that already put
+ # us inside a Job Object (npm/pnpm/conhost wrappers occasionally do
+ # this), AssignProcessToJobObject succeeds at the API level but the
+ # child silently lands in the OUTER job, not ours. We detect that
+ # via IsProcessInJob in ``add()`` and warn explicitly.
def __init__(self) -> None:
self._handle = None
self._win32job = None
- if sys.platform == "win32":
- try:
- import win32job # type: ignore[import-not-found]
-
- self._win32job = win32job
- self._handle = win32job.CreateJobObject(None, "")
- info = win32job.QueryInformationJobObject(
- self._handle, win32job.JobObjectExtendedLimitInformation
- )
- info["BasicLimitInformation"]["LimitFlags"] |= (
- win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
- )
- win32job.SetInformationJobObject(
- self._handle, win32job.JobObjectExtendedLimitInformation, info
- )
- except Exception: # pywin32 missing or denied
- self._handle = None
+ if sys.platform != "win32":
+ return
+ try:
+ import win32job # type: ignore[import-not-found]
+ except ImportError as e:
+ sys.stderr.write(
+ f"[supervisor] WARN: pywin32 import failed ({e}). "
+ f"Children will NOT be tree-killed if the supervisor dies "
+ f"abnormally on Windows. Reinstall via: pip install --force-reinstall pywin32\n"
+ )
+ return
+ try:
+ self._win32job = win32job
+ self._handle = win32job.CreateJobObject(None, "")
+ info = win32job.QueryInformationJobObject(
+ self._handle, win32job.JobObjectExtendedLimitInformation
+ )
+ info["BasicLimitInformation"]["LimitFlags"] |= (
+ win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+ )
+ win32job.SetInformationJobObject(
+ self._handle, win32job.JobObjectExtendedLimitInformation, info
+ )
+ except Exception as e:
+ sys.stderr.write(
+ f"[supervisor] WARN: Job Object init failed: {e!r}. "
+ f"Tree-kill on abnormal supervisor exit will not work.\n"
+ )
+ self._handle = None
+ self._win32job = None
def add(self, pid: int) -> bool:
- """Enroll ``pid`` in the job. Returns False when unavailable."""
+ """Enroll ``pid`` in the job. Returns False when enrollment did
+ not actually take effect.
+
+ ``AssignProcessToJobObject`` can return success even when the
+ child remains in a different job (inherited from an outer
+ wrapper that doesn't allow nesting). We verify with
+ ``IsProcessInJob`` so the caller learns the truth.
+ """
if self._handle is None or self._win32job is None:
return False
try:
import win32api # type: ignore[import-not-found]
-
+ except ImportError as e:
+ sys.stderr.write(f"[supervisor] WARN: win32api import failed ({e})\n")
+ return False
+ try:
+ # PROCESS_ALL_ACCESS = 0x1F0FFF
handle = win32api.OpenProcess(0x1F0FFF, False, pid)
self._win32job.AssignProcessToJobObject(self._handle, handle)
+ in_our_job = self._win32job.IsProcessInJob(handle, self._handle)
+ if not in_our_job:
+ in_some_job = self._win32job.IsProcessInJob(handle, None)
+ sys.stderr.write(
+ f"[supervisor] WARN: pid={pid} did not enter our Job Object "
+ f"(already in another job: {in_some_job}). Likely cause: "
+ f"this supervisor was launched from a wrapper (npm/pnpm/conhost) "
+ f"whose own Job Object disallows nesting. Tree-kill on abnormal "
+ f"supervisor exit will not reach this child.\n"
+ )
+ return False
return True
- except Exception:
+ except Exception as e:
+ sys.stderr.write(
+ f"[supervisor] WARN: AssignProcessToJobObject(pid={pid}) failed: {e!r}\n"
+ )
return False