gitpane 1.0.0__py3-none-any.whl

gitpane/process/process_group.py

@@ -0,0 +1,851 @@
+"""Keep a native process group alive, inherited streams included, beyond the exit of its parent.
+
+This file is also run on its own, as the supervisor started before every supervised command: the base interpreter
+runs it in isolated mode, with neither the application's packages nor any site directory. At that point only the
+standard library can be imported, so what the parent side alone needs is imported where the parent side uses it.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import enum
+import os
+import subprocess
+import sys
+import time
+from ctypes import wintypes
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+JOB_OBJECT_BASIC_ACCOUNTING_INFORMATION = 1
+JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
+JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000
+# A member may start a process outside the job, but only by asking for it explicitly when it starts that process.
+JOB_OBJECT_LIMIT_BREAKAWAY_OK = 0x0800
+# Every process a member starts is outside the job, without asking.
+JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK = 0x1000
+JOB_OBJECT_ASSIGN_PROCESS_AND_QUERY = 0x0005
+CREATE_SUSPENDED = 0x00000004
+CREATE_BREAKAWAY_FROM_JOB = 0x01000000
+# Rights needed to put a process in a job (set quota, terminate) and to let it run afterwards (suspend and resume).
+PROCESS_JOB_ADOPTION_ACCESS = 0x0100 | 0x0001 | 0x0800
+# The least right that lets a caller ask which job holds a process.
+PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+NT_SUCCESS_STATUS = 0
+# Shows a negative status the way Windows documents it, as an unsigned 32-bit value.
+NT_STATUS_MASK = 0xFFFFFFFF
+PROCESS_STOP_EXIT_CODE = 125
+PROCESS_START_FAILED_EXIT_CODE = 127
+LINUX_SET_CHILD_SUBREAPER = 36
+LINUX_SET_PARENT_DEATH_SIGNAL = 1
+SUPERVISOR_ARGUMENT_OFFSET = 1
+# Settings the supervisor reads before its target program: control folder, job name, poll period and GitPane's process ID.
+SUPERVISOR_SETTING_ARGUMENT_COUNT = 4
+SUPERVISOR_PROCESS_COUNT = 1
+IO_COUNTER_FIELD_COUNT = 6
+MINIMUM_TRACKED_PROCESS_ID = 2
+# Workaround: a copy of config.py's value. The supervisor runs this file in isolated mode, where it cannot import the
+# application package, so it keeps its own; a test checks that both stay equal.
+MILLISECONDS_PER_SECOND = 1000
+# Workaround: copies of config.py's platform names, for the same reason as above; a test checks that they stay equal.
+MACOS_PLATFORM = "darwin"
+LINUX_PLATFORM = "linux"
+WINDOWS_PLATFORM = "win32"
+# Systems where the supervisor stops its command itself when GitPane dies, compared as prefixes of sys.platform.
+OWNER_WATCH_PLATFORM_PREFIXES = (MACOS_PLATFORM, LINUX_PLATFORM)
+CONSOLE_INTERPRETER_BASENAME = "python.exe"
+WINDOWLESS_INTERPRETER_BASENAME = "pythonw.exe"
+STOP_BASENAME = "stop"
+GROUP_BASENAME = "group"
+COMPLETE_BASENAME = "complete"
+START_FAILED_BASENAME = "start-failed"
+PROC_DIR = "/proc"
+PROC_STAT_BASENAME = "stat"
+# Fields of a /proc/<pid>/stat line counted from the first one after the command name.
+PROC_STAT_STATE_INDEX = 0
+PROC_STAT_PARENT_INDEX = 1
+PROC_STAT_GROUP_INDEX = 2
+PROC_STAT_SESSION_INDEX = 3
+ZOMBIE_STATE = "Z"
+# Windows signatures of the kernel32 functions this module calls, declared once so ctypes never truncates a handle or a pointer on 64 bits.
+KERNEL_SIGNATURE_BY_NAME = {
+    "CreateJobObjectW": ([ctypes.c_void_p, wintypes.LPCWSTR], wintypes.HANDLE),
+    "OpenJobObjectW": ([wintypes.DWORD, wintypes.BOOL, wintypes.LPCWSTR], wintypes.HANDLE),
+    "SetInformationJobObject": ([wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD], wintypes.BOOL),
+    "QueryInformationJobObject": ([wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD, ctypes.c_void_p], wintypes.BOOL),
+    "AssignProcessToJobObject": ([wintypes.HANDLE, wintypes.HANDLE], wintypes.BOOL),
+    "TerminateJobObject": ([wintypes.HANDLE, wintypes.UINT], wintypes.BOOL),
+    "GetCurrentProcess": ([], wintypes.HANDLE),
+    "OpenProcess": ([wintypes.DWORD, wintypes.BOOL, wintypes.DWORD], wintypes.HANDLE),
+    "IsProcessInJob": ([wintypes.HANDLE, wintypes.HANDLE, ctypes.POINTER(wintypes.BOOL)], wintypes.BOOL),
+    "CloseHandle": ([wintypes.HANDLE], wintypes.BOOL),
+}
+
+
+def _bound_kernel(function_names: tuple[str, ...]) -> ctypes.WinDLL:
+    """Load kernel32 and give each requested function its signature from ``KERNEL_SIGNATURE_BY_NAME``.
+
+    Every caller gets its own instance, so none depends on the declarations another one made. Only the standard library
+    is used, since the supervisor runs this file without the application's packages.
+    """
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    for function_name in function_names:
+        argument_types, result_type = KERNEL_SIGNATURE_BY_NAME[function_name]
+        function = getattr(kernel, function_name)
+        function.argtypes = argument_types
+        function.restype = result_type
+    return kernel
+
+
+class _JobBasicLimit(ctypes.Structure):
+    """Match the native limit structure without assuming pointer or integer widths."""
+
+    _fields_ = [("per_process_time", ctypes.c_longlong), ("per_job_time", ctypes.c_longlong), ("limit_flags", wintypes.DWORD),
+                ("minimum_working_set", ctypes.c_size_t), ("maximum_working_set", ctypes.c_size_t), ("active_process_limit", wintypes.DWORD),
+                ("affinity", ctypes.c_size_t), ("priority_class", wintypes.DWORD), ("scheduling_class", wintypes.DWORD)]
+
+
+class _JobExtendedLimit(ctypes.Structure):
+    """Include native accounting fields to place the kill-on-close flag correctly."""
+
+    _fields_ = [("basic_limit", _JobBasicLimit), ("io_counter", ctypes.c_ulonglong * IO_COUNTER_FIELD_COUNT), ("process_memory_limit", ctypes.c_size_t),
+                ("job_memory_limit", ctypes.c_size_t), ("peak_process_memory", ctypes.c_size_t), ("peak_job_memory", ctypes.c_size_t)]
+
+
+class _JobAccounting(ctypes.Structure):
+    """Read the OS count that includes descendants after the original process exits."""
+
+    _fields_ = [("total_user_time", ctypes.c_longlong), ("total_kernel_time", ctypes.c_longlong), ("period_user_time", ctypes.c_longlong),
+                ("period_kernel_time", ctypes.c_longlong), ("page_fault_count", wintypes.DWORD), ("total_process_count", wintypes.DWORD),
+                ("active_process_count", wintypes.DWORD), ("terminated_process_count", wintypes.DWORD)]
+
+
+class _WindowsJob:
+    """Own a Windows job whose members cannot leave while their helpers are running."""
+
+    def __init__(self, name: str | None, *, existing: bool = False, limit_flags: int = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) -> None:
+        """Bind the pointer-safe APIs before creating or opening the named job; a job without a name is private to its creator.
+
+        A created job always stops its members when its last handle closes; ``limit_flags`` may add what its members are
+        allowed to start outside of it.
+        """
+        self.kernel = _bound_kernel(("CreateJobObjectW", "OpenJobObjectW", "SetInformationJobObject", "QueryInformationJobObject", "AssignProcessToJobObject",
+                                     "TerminateJobObject", "GetCurrentProcess", "OpenProcess", "IsProcessInJob", "CloseHandle"))
+        self.handle = self.kernel.OpenJobObjectW(JOB_OBJECT_ASSIGN_PROCESS_AND_QUERY, False, name) if existing else self.kernel.CreateJobObjectW(None, name)
+        if not self.handle:
+            raise ctypes.WinError(ctypes.get_last_error())
+        if existing:
+            return
+        limit = _JobExtendedLimit()
+        limit.basic_limit.limit_flags = limit_flags | JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        if not self.kernel.SetInformationJobObject(self.handle, JOB_OBJECT_EXTENDED_LIMIT_INFORMATION, ctypes.byref(limit), ctypes.sizeof(limit)):
+            error = ctypes.WinError(ctypes.get_last_error())
+            self.close()
+            raise error
+
+    def adopt_suspended(self, process_id: int) -> None:
+        """Put a process started suspended in this job, then let it run, so it can start nothing before it is a member."""
+        process_handle = self.kernel.OpenProcess(PROCESS_JOB_ADOPTION_ACCESS, False, process_id)
+        if not process_handle:
+            raise ctypes.WinError(ctypes.get_last_error())
+        try:
+            if not self.kernel.AssignProcessToJobObject(self.handle, process_handle):
+                raise ctypes.WinError(ctypes.get_last_error())
+            # Workaround: subprocess does not keep the handle of the main thread of a process it started, so the thread
+            # cannot be resumed with the documented ResumeThread. NtResumeProcess resumes every thread of the process at
+            # once; it is exported by ntdll and has kept the same behaviour since Windows XP.
+            ntdll = ctypes.WinDLL("ntdll")
+            ntdll.NtResumeProcess.argtypes = [wintypes.HANDLE]
+            ntdll.NtResumeProcess.restype = ctypes.c_long
+            status = ntdll.NtResumeProcess(process_handle)
+            if status != NT_SUCCESS_STATUS:
+                raise OSError(f"The process could not be resumed (status {status & NT_STATUS_MASK:#010x})")
+        finally:
+            self.kernel.CloseHandle(process_handle)
+
+    def join_current_process(self) -> None:
+        """Join before launching user commands so even their first child inherits membership."""
+        if not self.kernel.AssignProcessToJobObject(self.handle, self.kernel.GetCurrentProcess()):
+            raise ctypes.WinError(ctypes.get_last_error())
+        # Only the GUI retains a handle: its unexpected exit must also kill this job.
+        # Queries with a null handle inspect the calling process's immediate job.
+        self.close()
+
+    def active_count(self) -> int:
+        """Ask the kernel for live membership, including nested descendant jobs."""
+        accounting = _JobAccounting()
+        if not self.kernel.QueryInformationJobObject(self.handle, JOB_OBJECT_BASIC_ACCOUNTING_INFORMATION, ctypes.byref(accounting), ctypes.sizeof(accounting), None):
+            raise ctypes.WinError(ctypes.get_last_error())
+        return accounting.active_process_count
+
+    def stop(self) -> None:
+        """Terminate every current member rather than only the observed parent."""
+        if not self.kernel.TerminateJobObject(self.handle, PROCESS_STOP_EXIT_CODE):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+    def close(self) -> None:
+        """Release the native handle exactly once after membership is drained."""
+        if self.handle:
+            self.kernel.CloseHandle(self.handle)
+            self.handle = None
+
+
+class ProcessGroup(Protocol):
+    """Provide launch isolation and verifiable drainage for replaceable native controllers."""
+
+    def prepare(self, program_filename: str, arguments: list[str]) -> tuple[str, list[str]]:
+        """Return a supervised command without changing its input and output channels."""
+        ...
+
+    def contains_process(self, process_id: int) -> bool:
+        """Return whether the OS proves this process belongs to the tracked descendants."""
+        ...
+
+    def stop(self) -> None:
+        """Request descendant termination while retaining proof resources."""
+        ...
+
+    def is_empty(self) -> bool:
+        """Return true only when no descendant can continue modifying repository data."""
+        ...
+
+    def launch_failed(self) -> bool:
+        """Distinguish a failed target launch from the supervisor's own exit."""
+        ...
+
+    def result_return_code(self, fallback: int | None) -> int | None:
+        """Preserve the target's signed native status across the supervisor boundary."""
+        ...
+
+    def close(self) -> None:
+        """Release resources after a terminal result becomes safe to publish."""
+        ...
+
+
+def watches_owner_exit(platform: str) -> bool:
+    """Tell whether the supervisor must watch GitPane itself to stop its command when GitPane dies.
+
+    On Windows the supervisor is a member of GitPane's job, which the kernel stops as soon as GitPane exits. macOS has
+    no such job and nothing adopts orphans there: the supervisor's parent simply becomes launchd. Linux gives the
+    supervisor no parent-death signal either. On both, the supervisor reads its parent at start and stops the command's
+    group as soon as that parent changes.
+    """
+    return platform.startswith(OWNER_WATCH_PLATFORM_PREFIXES)
+
+
+class ReleasedChildGuard(enum.Enum):
+    """How a system keeps a released helper from outliving the worker that started it."""
+
+    # A private job, which the kernel stops when its owner exits or when it is closed.
+    JOB = enum.auto()
+    # The kernel's parent-death signal, which the helper asks for before its program runs.
+    PARENT_DEATH_SIGNAL = enum.auto()
+    # A small watcher started as the helper's parent, which the kernel tells when the worker ends.
+    WATCHER = enum.auto()
+
+
+# Compared as prefixes of sys.platform; a system missing here has no known guard and is refused.
+RELEASED_CHILD_GUARD_BY_PLATFORM_PREFIX = {
+    WINDOWS_PLATFORM: ReleasedChildGuard.JOB,
+    LINUX_PLATFORM: ReleasedChildGuard.PARENT_DEATH_SIGNAL,
+    MACOS_PLATFORM: ReleasedChildGuard.WATCHER,
+}
+
+
+def released_child_guard(platform: str) -> ReleasedChildGuard:
+    """Pick the way ``platform`` stops a released helper together with its worker, refusing a system without one.
+
+    Windows holds the helper in a private job. Linux lets the helper ask the kernel for a signal when its parent dies.
+    macOS has neither, and stopping the worker's group does not reach a helper that leads a session of its own, so a
+    watcher becomes the helper's parent and stops it when the kernel reports the worker's end.
+    """
+    for platform_prefix, guard in RELEASED_CHILD_GUARD_BY_PLATFORM_PREFIX.items():
+        if platform.startswith(platform_prefix):
+            return guard
+    raise OSError("No way to stop a released helper with its worker is known on " + platform)
+
+
+def released_child_watch_filename() -> str:
+    """Answer the absolute file of the released helper watcher, as imported from the installation; a module that cannot be found or is not valid Python, or a missing file, is a launch error."""
+    try:
+        import gitpane.process.released_child_watch
+    except (ImportError, SyntaxError) as error:
+        raise OSError("The released helper watcher is not available: " + str(error)) from error
+
+    watch_filename = os.path.abspath(gitpane.process.released_child_watch.__file__)
+    if not os.path.isfile(watch_filename):
+        raise OSError("The released helper watcher is not available: " + watch_filename)
+    return watch_filename
+
+
+def supervisor_script_filename() -> str:
+    """Answer the absolute file of the supervisor script, this module as imported from the installation; a missing file is a launch error."""
+    script_filename = os.path.abspath(__file__)
+    if not os.path.isfile(script_filename):
+        raise OSError("The supervisor script is not available: " + script_filename)
+    return script_filename
+
+
+def console_interpreter_filename(interpreter_filename: str) -> str:
+    """Answer the console form of ``interpreter_filename``: the console interpreter of the same folder for the Windows windowless one, any other name unchanged.
+
+    Windows gives no console to a windowless program, even when asked to start it with a hidden one, and every console
+    program such a process starts then opens a visible console window of its own. A Python helper that starts console
+    programs (Git, the credential manager) therefore runs on the console interpreter, which receives the hidden console
+    and hands it on. Only the exact Windows name is replaced, in any case, so Linux and macOS interpreters never change.
+    The answer is a name only: whether that file exists is for the caller to check.
+    """
+    directory, basename = os.path.split(interpreter_filename)
+    if basename.casefold() != WINDOWLESS_INTERPRETER_BASENAME:
+        return interpreter_filename
+    return os.path.join(directory, CONSOLE_INTERPRETER_BASENAME)
+
+
+def supervisor_interpreter_filename() -> str:
+    """Answer the interpreter that runs the supervisor: the base interpreter of this runtime, in its console form.
+
+    The interpreter of a virtual environment is a small launcher that starts the base interpreter as one more process;
+    starting the base interpreter directly saves that process for every supervised command, and the supervisor needs
+    nothing of the environment. The runtime names its base interpreter; when it names none, the running interpreter is
+    the explicit fallback. An application started without a console runs the windowless interpreter, which cannot hand
+    its standard streams on to Git, so the console interpreter installed beside it is taken instead. A named
+    interpreter that is missing is a launch error: another Python is never searched for.
+    """
+    # The base interpreter is only published as a private attribute of the runtime; nothing public names it.
+    candidate = console_interpreter_filename(getattr(sys, "_base_executable", None) or sys.executable)
+    if not os.path.isabs(candidate) or not os.path.isfile(candidate):
+        raise OSError("The supervisor interpreter is not available: " + candidate)
+    return candidate
+
+
+def supervisor_poll_ms(value: str) -> int:
+    """Read the poll period the parent hands to the supervisor, refusing anything but a positive number of milliseconds."""
+    poll_ms = int(value)
+    if poll_ms <= 0:
+        raise ValueError("The supervisor poll period must be positive")
+    return poll_ms
+
+
+def supervisor_owner_id(value: str) -> int:
+    """Read the process ID of GitPane, which the parent hands to the supervisor, refusing anything but a positive number."""
+    owner_id = int(value)
+    if owner_id <= 0:
+        raise ValueError("The supervisor owner process ID must be positive")
+    return owner_id
+
+
+class NativeProcessGroup:
+    """Coordinate an OS job or session through private, non-secret control markers."""
+
+    def __init__(self, *, breakaway_allowed: bool = False) -> None:
+        """Create private control storage before any process can be launched.
+
+        ``breakaway_allowed`` lets a member start a process outside the group when it explicitly asks for it; nothing
+        leaves the group otherwise. Only a browser sign-in worker needs it, to hold Git Credential Manager in a job of its own.
+        """
+        import tempfile
+        import uuid
+
+        self.control = tempfile.TemporaryDirectory(prefix="gitpane-process-")
+        self.control_dir = self.control.name
+        self.job_name = "Local\\gitpane-" + uuid.uuid4().hex if os.name == "nt" else ""
+        limit_flags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE | (JOB_OBJECT_LIMIT_BREAKAWAY_OK if breakaway_allowed else 0)
+        try:
+            self.job = _WindowsJob(self.job_name, limit_flags=limit_flags) if os.name == "nt" else None
+        except OSError:
+            self.control.cleanup()
+            raise
+
+    def prepare(self, program_filename: str, arguments: list[str]) -> tuple[str, list[str]]:
+        """Start the standard-library bootstrap, which joins the group before it runs the target unchanged.
+
+        A repository can contain a hostile gitpane package, a sitecustomize module or a PYTHONPATH: isolated mode
+        ignores the environment and the current directory, and skipping site loads nothing from any site directory.
+        The script is the absolute file of this module, as imported from the installation. The poll period comes from
+        the shared configuration, which the bootstrap itself cannot import. The process ID of the process preparing the
+        command, GitPane, which starts the supervisor itself, tells the supervisor which parent to watch.
+        """
+        from gitpane.config import ISOLATED_INTERPRETER_OPTIONS, PROCESS_GROUP_POLL_MS
+
+        return supervisor_interpreter_filename(), [*ISOLATED_INTERPRETER_OPTIONS, supervisor_script_filename(), self.control_dir, self.job_name, str(PROCESS_GROUP_POLL_MS),
+                                                   str(os.getpid()), program_filename, *arguments]
+
+    def stop(self) -> None:
+        """Cancel startup as well as existing members without freeing their reservation."""
+        _write_marker(self.control_dir, STOP_BASENAME)
+        if self.job is not None:
+            self.job.stop()
+            return
+        group_id = _read_group_id(self.control_dir)
+        if group_id is not None:
+            _stop_posix_group(group_id)
+
+    def is_empty(self) -> bool:
+        """Keep ownership when missing or inaccessible proof makes the outcome unknown."""
+        if self.job is not None:
+            return self.job.active_count() == 0
+        group_id = _read_group_id(self.control_dir)
+        if group_id is not None and _posix_group_exists(group_id):
+            return False
+        return os.path.isfile(os.path.join(self.control_dir, COMPLETE_BASENAME)) or self.launch_failed()
+
+    def contains_process(self, process_id: int) -> bool:
+        """Verify that an IPC caller belongs to this operation's native descendant group."""
+        if self.job is None:
+            group_id = _read_group_id(self.control_dir)
+            try:
+                return group_id is not None and os.getpgid(process_id) == group_id
+            except ProcessLookupError:
+                return False
+        kernel = self.job.kernel
+        handle = kernel.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, process_id)
+        if not handle:
+            return False
+        try:
+            contained = wintypes.BOOL()
+            return bool(kernel.IsProcessInJob(handle, self.job.handle, ctypes.byref(contained)) and contained.value)
+        finally:
+            kernel.CloseHandle(handle)
+
+    def launch_failed(self) -> bool:
+        """Read only the supervisor's launch status, never a credential-bearing diagnostic."""
+        return os.path.isfile(os.path.join(self.control_dir, START_FAILED_BASENAME))
+
+    def result_return_code(self, fallback: int | None) -> int | None:
+        """Restore negative POSIX signal statuses that a supervisor exit cannot encode."""
+        try:
+            with open(os.path.join(self.control_dir, COMPLETE_BASENAME), encoding="ascii") as stream:
+                value = stream.read()
+            return int(value) if value else fallback
+        except FileNotFoundError:
+            return fallback
+        except ValueError as error:
+            raise OSError("Invalid supervised process status") from error
+
+    def close(self) -> None:
+        """Dispose of the already empty job and its private markers."""
+        if self.job is not None:
+            self.job.close()
+        self.control.cleanup()
+
+
+def caller_job_forbids_breakaway() -> bool:
+    """Tell whether the job holding this process forbids its members to start a process outside it.
+
+    Windows refuses a launch that asks to leave such a job with the same access-denied error it gives for a program the
+    user may not run (file rights, an application control policy, an antivirus), so the job's own limits tell the two
+    apart. A process in no job, in a job that lets its members leave, or whose job cannot be read, is taken as not
+    forbidden: the launch's own error is then the one shown. Elsewhere than on Windows there is no such job.
+    """
+    if os.name != "nt":
+        return False
+    kernel = _bound_kernel(("GetCurrentProcess", "IsProcessInJob", "QueryInformationJobObject"))
+    contained = wintypes.BOOL()
+    if not kernel.IsProcessInJob(kernel.GetCurrentProcess(), None, ctypes.byref(contained)) or not contained.value:
+        return False
+    limit = _JobExtendedLimit()
+    # A null job handle reads the job that holds the calling process.
+    if not kernel.QueryInformationJobObject(None, JOB_OBJECT_EXTENDED_LIMIT_INFORMATION, ctypes.byref(limit), ctypes.sizeof(limit), None):
+        return False
+    return not limit.basic_limit.limit_flags & (JOB_OBJECT_LIMIT_BREAKAWAY_OK | JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK)
+
+
+def process_is_in_a_job(process_id: int) -> bool:
+    """Tell whether any job holds the process, raising when Windows cannot answer.
+
+    Since Windows 8 jobs nest. A process started with the request to leave its job leaves each job of the chain that
+    allows it, one after the other, and silently stays in the first one that forbids it. A helper still in a job right
+    after it was started suspended with that request was therefore kept by a job outside GitPane, since GitPane's own
+    jobs all let it leave. Elsewhere than on Windows there are no jobs.
+    """
+    if os.name != "nt":
+        return False
+    kernel = _bound_kernel(("OpenProcess", "IsProcessInJob", "CloseHandle"))
+    process_handle = kernel.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, process_id)
+    if not process_handle:
+        raise ctypes.WinError(ctypes.get_last_error())
+    try:
+        contained = wintypes.BOOL()
+        # A null job handle asks about any job rather than one given job.
+        if not kernel.IsProcessInJob(process_handle, None, ctypes.byref(contained)):
+            raise ctypes.WinError(ctypes.get_last_error())
+        return bool(contained.value)
+    finally:
+        kernel.CloseHandle(process_handle)
+
+
+class JobBreakawayRefusedError(OSError):
+    """A job holding GitPane, the one GitPane runs in or one further out, keeps the process, so a released launch cannot go on.
+
+    Starting the process inside that job, or inside the supervised group instead, would expose what it opens, such as
+    the user's browser, to the stopping of that job or group.
+    """
+
+
+class ReleasedChildJob:
+    """Run one process that is stopped with this job, while every process it starts is left running on its own.
+
+    Git Credential Manager opens the user's browser as a child process during a browser sign-in. In a supervised group
+    that browser would be a member like any helper: the group would only count as empty once the user closes the
+    browser, and stopping the group would close it. On Windows the process therefore leaves the supervised group when it
+    starts (that group must allow it) and is held in this private job instead. The kernel stops the job's members when
+    ``stop`` is called or when the job's owner exits, so the process can never outlive the worker that started it;
+    the processes it starts leave the job at once, so the browser is never stopped by GitPane. When a job outside GitPane
+    forbids leaving it, the process stays in that job without any error; it is then stopped before it has run anything
+    and the launch is refused, since that job could close the browser too.
+
+    Elsewhere, the process runs in a session of its own, and the browser it opens stays in that session and in its group
+    (``xdg-open`` and ``open`` move it to neither). Only the process itself is ever stopped, never its group, so the
+    browser keeps running. On Linux the kernel also stops the process as soon as the worker that started it exits, as
+    the Windows job would, and the supervisor does not wait for what is left of that session once its leader has ended.
+    macOS has no such signal, so a small watcher leads that session as the process's parent: the kernel tells it when
+    the worker ends, and it then stops the process alone. The watcher hands the process its streams and ends with its
+    exit code, so the worker reads the watcher as it would read the process.
+    """
+
+    def __init__(self, caller_job_forbids_breakaway: Callable[[], bool] = caller_job_forbids_breakaway,
+                 process_is_in_a_job: Callable[[int], bool] = process_is_in_a_job, platform: str = sys.platform) -> None:
+        """Pick the system's guard, and create the private job before anything is started where the guard is a job.
+
+        ``caller_job_forbids_breakaway`` reads the limits of the job holding GitPane, and ``process_is_in_a_job`` tells
+        whether a job still holds the process just started; the tests replace both, since Windows alone has such jobs.
+        ``platform`` is the system whose guard is used.
+        """
+        self.guard = released_child_guard(platform)
+        self.job = _WindowsJob(None, limit_flags=JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK) if self.guard is ReleasedChildGuard.JOB else None
+        self.process: subprocess.Popen | None = None
+        self.caller_job_forbids_breakaway = caller_job_forbids_breakaway
+        self.process_is_in_a_job = process_is_in_a_job
+
+    def start(self, command: list[str], environment_by_name: dict[str, str]) -> subprocess.Popen:
+        """Start the process with piped standard streams, already a member of this job before it runs any code.
+
+        Raises ``JobBreakawayRefusedError`` without starting anything when the caller's own job forbids leaving it, and
+        after stopping the process before it has run anything when a job outside GitPane keeps it. Any other refusal,
+        such as a helper program the user may not run, is raised as it came. A process stopped that way is waited for
+        and its pipes closed before the refusal is raised, so nothing of it is left behind.
+
+        On macOS the process returned is the watcher that runs the helper: it shares the helper's streams and ends with
+        the helper's exit code, and a helper the watcher cannot start shows up as its exit code 127 with the reason on
+        standard error.
+        """
+        from gitpane.config import ISOLATED_INTERPRETER_OPTIONS, PROCESS_TERMINATE_TIMEOUT_MS
+
+        pipe_by_stream = {"stdin": subprocess.PIPE, "stdout": subprocess.PIPE, "stderr": subprocess.PIPE}
+        if self.job is None and self.guard is ReleasedChildGuard.WATCHER:
+            watched_command = [supervisor_interpreter_filename(), *ISOLATED_INTERPRETER_OPTIONS, released_child_watch_filename(), str(os.getpid()), *command]
+            self.process = subprocess.Popen(watched_command, env=environment_by_name, start_new_session=True, **pipe_by_stream)
+            return self.process
+        if self.job is None:
+            # Workaround: the parent-death signal can only be requested by the new process itself, so it goes through
+            # preexec_fn, which runs between fork and exec. That is only unsafe while other threads run, and the
+            # sign-in worker that starts the helper runs none (on POSIX, communicate() waits without threads).
+            stop_with_owner = _stop_with_owner_function(os.getpid())
+            self.process = subprocess.Popen(command, env=environment_by_name, start_new_session=True, preexec_fn=stop_with_owner, **pipe_by_stream)  # noqa: PLW1509 -- see above
+            return self.process
+        try:
+            process = subprocess.Popen(command, env=environment_by_name, creationflags=CREATE_SUSPENDED | CREATE_BREAKAWAY_FROM_JOB, **pipe_by_stream)
+        except PermissionError as error:
+            if not self.caller_job_forbids_breakaway():
+                raise
+            # A job that forbids leaving it holds this worker. Starting the process inside the supervised group instead
+            # would put the browser it opens in that group too, and stopping the group would close the user's browser,
+            # so the launch is refused rather than retried.
+            raise JobBreakawayRefusedError("The calling job does not allow a process to leave it") from error
+        self.process = process
+        try:
+            # The process is still suspended and has run nothing, so it cannot have opened a browser yet. A job outside
+            # GitPane that forbids leaving it keeps the process without any error from Windows; only asking which job
+            # holds it now shows that, and the process is then stopped before it runs.
+            if self.process_is_in_a_job(process.pid):
+                raise JobBreakawayRefusedError("A job outside GitPane keeps the process it starts")
+            self.job.adopt_suspended(process.pid)
+        except OSError:
+            process.kill()
+            # The refused process must hold neither a running process nor open handles until the garbage collector
+            # finds it, nor make Python warn that it is still running. A suspended process that has run nothing ends as
+            # soon as Windows stops it; if it still has not ended in time, the refusal is what the user must see.
+            try:
+                process.wait(timeout=PROCESS_TERMINATE_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+            except subprocess.TimeoutExpired:
+                pass
+            for stream in (process.stdin, process.stdout, process.stderr):
+                if stream is not None:
+                    stream.close()
+            self.process = None
+            raise
+        return process
+
+    def stop(self) -> None:
+        """Stop the process now, leaving alone the processes it started.
+
+        Elsewhere than on Windows only the process is signalled, never its group: the browser it opened is a member of
+        that group. The process is still unreaped while it runs, so its ID cannot name another process yet. On macOS the
+        watcher is asked to stop, and it stops the helper alone, its own unreaped child, before it ends.
+        """
+        if self.job is not None:
+            self.job.stop()
+            return
+        if self.process is None or self.process.poll() is not None:
+            return
+        if self.guard is ReleasedChildGuard.WATCHER:
+            self.process.terminate()
+            return
+        self.process.kill()
+
+    def close(self) -> None:
+        """Release the job; a member still running is stopped by the kernel when its last handle closes.
+
+        Elsewhere there is no job to close, so a process still running is stopped here, the way the job would stop it.
+        """
+        if self.job is not None:
+            self.job.close()
+            return
+        self.stop()
+
+
+def _stop_with_owner_function(owner_id: int) -> Callable[[], None]:
+    """Return what a new Linux process runs before its program: ask the kernel to stop it when ``owner_id``, its parent, exits.
+
+    This is the Linux counterpart of the Windows job that stops its member when its owner exits. The C library is
+    bound here, in the parent, so the new process only makes the call. A process whose parent already exited before
+    the request took effect, or whose request was refused, ends before its program runs rather than run unguarded.
+    """
+    library = ctypes.CDLL(None, use_errno=True)
+    import signal
+
+    def ask_kernel() -> None:
+        """Run in the new process, between its creation and its program."""
+        if library.prctl(LINUX_SET_PARENT_DEATH_SIGNAL, signal.SIGKILL, 0, 0, 0) != 0:
+            os._exit(PROCESS_START_FAILED_EXIT_CODE)
+        if os.getppid() != owner_id:
+            os._exit(PROCESS_STOP_EXIT_CODE)
+
+    return ask_kernel
+
+
+def _write_marker(control_dir: str, basename: str, value: str = "") -> None:
+    """Atomically publish small control records so polling never reads a partial PID."""
+    temporary_filename = os.path.join(control_dir, basename + ".tmp-" + str(os.getpid()))
+    with open(temporary_filename, "w", encoding="ascii") as stream:
+        stream.write(value)
+    os.replace(temporary_filename, os.path.join(control_dir, basename))
+
+
+def _read_group_id(control_dir: str) -> int | None:
+    """Read the isolated session identity once the supervisor has started the target."""
+    try:
+        with open(os.path.join(control_dir, GROUP_BASENAME), encoding="ascii") as stream:
+            group_id = int(stream.read())
+    except FileNotFoundError:
+        return None
+    except ValueError as error:
+        raise OSError("Invalid supervised process group") from error
+    if group_id < MINIMUM_TRACKED_PROCESS_ID:
+        raise OSError("Invalid supervised process group")
+    return group_id
+
+
+def _posix_group_exists(group_id: int) -> bool:
+    """Tell whether any member of the group, a zombie included, still exists, so termination is never invented.
+
+    A group whose remaining members are zombies not yet reaped still exists: it disappears once they are reaped, and
+    the caller checks again. Any other refusal of the system is raised, since the outcome is then unknown.
+    """
+    try:
+        os.killpg(group_id, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Workaround: macOS answers EPERM for a group whose remaining members are all zombies not yet reaped, where
+        # Linux accepts the request; the group still exists until they are reaped.
+        return True
+    return True
+
+
+def _stop_posix_group(group_id: int) -> None:
+    """Stop the entire isolated group while leaving the supervisor alive to reap it.
+
+    A group that no longer exists, or whose remaining members are zombies not yet reaped, has nothing left to stop.
+    Any other refusal of the system is raised.
+    """
+    import signal
+
+    try:
+        os.killpg(group_id, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    except PermissionError:
+        # Workaround: macOS answers EPERM to killpg on a group whose remaining members are all zombies not yet reaped,
+        # where Linux succeeds; nothing alive is left to stop, and reaping them is what ends the group.
+        pass
+
+
+def _reap_exited_children() -> bool:
+    """Reap every child that has exited, adopted ones included, and report whether a child still runs."""
+    while True:
+        try:
+            process_id, _ = os.waitpid(-1, os.WNOHANG)
+        except ChildProcessError:
+            return False
+        if process_id == 0:
+            return True
+
+
+def _running_child_records() -> list[tuple[int, int, int]] | None:
+    """List the supervisor's running children, adopted ones included, as (process ID, group ID, session ID); None when they cannot be read.
+
+    No system call lists the children of a process: Linux only gives each process's parent, group and session in its
+    own /proc entry, so every entry is read. This only runs while a child outlives the target, which is rare.
+    """
+    supervisor_id = os.getpid()
+    child_records = []
+    try:
+        proc_entries = os.scandir(PROC_DIR)
+    except OSError:
+        return None
+    with proc_entries:
+        for proc_entry in proc_entries:
+            if not proc_entry.name.isdigit():
+                continue
+            try:
+                with open(os.path.join(proc_entry.path, PROC_STAT_BASENAME), encoding="ascii", errors="replace") as stream:
+                    stat_text = stream.read()
+            except OSError:
+                # The process ended since the folder was listed; one of the supervisor's own is always readable.
+                continue
+            # The command name comes first, between parentheses, and may itself contain spaces or parentheses.
+            stat_fields = stat_text.rpartition(")")[2].split()
+            if stat_fields[PROC_STAT_STATE_INDEX] == ZOMBIE_STATE or int(stat_fields[PROC_STAT_PARENT_INDEX]) != supervisor_id:
+                continue
+            child_records.append((int(proc_entry.name), int(stat_fields[PROC_STAT_GROUP_INDEX]), int(stat_fields[PROC_STAT_SESSION_INDEX])))
+    return child_records
+
+
+def _session_leader_runs(session_id: int) -> bool:
+    """Tell whether the process that leads a session still exists.
+
+    While any member of the session remains, Linux keeps its ID reserved, so the ID cannot name another process.
+    """
+    try:
+        os.kill(session_id, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _reap_orphan(target_id: int, *, stopping: bool) -> bool:
+    """Reap adopted Linux descendants and report whether one must still be waited for; when ``stopping``, stop what the target's session still runs.
+
+    ``target_id`` is the target's process ID, which is also the ID of the group and of the session it leads. A child in
+    the target's session is waited for: a member of its group, or a program the target started in a group of its own
+    so that it can stop that program with everything it started. When the command is being stopped, each such group is
+    stopped as a whole, as the Windows job stops all of its members. A child that leads a session of its own, as Git's
+    background maintenance does once detached, is waited for too: it may still change repository data. Only a child
+    left behind by another session whose leader has ended is not waited for: that is what a released credential
+    helper opened before it ended, the user's browser, which is never stopped either. When the children cannot be
+    read, every one is waited for.
+
+    Once the command is being stopped, nothing outside the target's session is waited for any more. Such a child is
+    never stopped (it may be the user's browser, an SSH ControlPersist master or a gpg-agent that daemonized), so
+    waiting for it after a stop would keep the supervisor alive until it is killed, even though Git itself has ended.
+    """
+    if not _reap_exited_children():
+        return False
+    child_records = _running_child_records()
+    if child_records is None:
+        return True
+    waiting = False
+    for process_id, group_id, session_id in child_records:
+        if session_id == target_id:
+            if stopping and group_id != target_id:
+                _stop_posix_group(group_id)
+            waiting = True
+            continue
+        if stopping:
+            continue
+        if process_id == session_id or _session_leader_runs(session_id):
+            waiting = True
+    return waiting
+
+
+def supervise(control_dir: str, job_name: str, program_filename: str, arguments: list[str], *, poll_ms: int, owner_id: int) -> int:
+    """Run a target with unchanged streams and stay until all of its helpers exit, checking again every ``poll_ms``.
+
+    On Windows the supervisor blocks on the target itself, and only then checks the job until nobody but the supervisor
+    is left: stopping goes through the job from the application, so nothing needs watching while the target runs.
+    Elsewhere the stop marker must be watched while the target runs, so the target is polled. Once it has exited, the
+    supervisor stays while a member of the target's group runs, and on Linux while a descendant it adopted may still
+    change repository data; what a released credential helper opened, such as the user's browser, is not waited for.
+
+    On macOS and Linux the supervisor also watches the process that started it, GitPane, whose process ID is
+    ``owner_id``: when its parent is no longer GitPane, GitPane has died, and the target's group is stopped exactly as
+    for a stop request. A supervisor whose parent is already not GitPane when it starts runs nothing and records its end
+    as for a stop requested before the launch. The parent is compared with GitPane itself, not with the first process
+    of the system, because a Linux desktop session adopts orphans in a process of its own, and GitPane may itself be
+    that first process in a container.
+    """
+    job = None
+    child = None
+    watching_owner = watches_owner_exit(sys.platform)
+    try:
+        if os.name == "nt":
+            job = _WindowsJob(job_name, existing=True)
+            job.join_current_process()
+        elif sys.platform.startswith(LINUX_PLATFORM):
+            # Adopt orphan grandchildren so their zombies cannot keep an empty group alive, and so what the target
+            # leaves behind can still be waited for or stopped.
+            library = ctypes.CDLL(None, use_errno=True)
+            if library.prctl(LINUX_SET_CHILD_SUBREAPER, 1, 0, 0, 0) != 0:
+                raise OSError(ctypes.get_errno(), "Could not track orphan descendants")
+        if os.path.isfile(os.path.join(control_dir, STOP_BASENAME)) or (watching_owner and os.getppid() != owner_id):
+            _write_marker(control_dir, COMPLETE_BASENAME)
+            return PROCESS_STOP_EXIT_CODE
+        child = subprocess.Popen([program_filename, *arguments], stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr, start_new_session=os.name != "nt",
+                                 creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+        _write_marker(control_dir, GROUP_BASENAME, str(child.pid))
+        if job is not None:
+            return_code = child.wait()
+            while job.active_count() != SUPERVISOR_PROCESS_COUNT:
+                time.sleep(poll_ms / MILLISECONDS_PER_SECOND)
+            _write_marker(control_dir, COMPLETE_BASENAME, str(return_code))
+            return return_code
+        while True:
+            stopping = os.path.isfile(os.path.join(control_dir, STOP_BASENAME)) or (watching_owner and os.getppid() != owner_id)
+            if stopping:
+                _stop_posix_group(child.pid)
+            return_code = child.poll()
+            if return_code is not None:
+                orphan_alive = _reap_orphan(child.pid, stopping=stopping)
+                drained = not _posix_group_exists(child.pid) and not orphan_alive
+                if drained:
+                    _write_marker(control_dir, COMPLETE_BASENAME, str(return_code))
+                    return return_code
+            time.sleep(poll_ms / MILLISECONDS_PER_SECOND)
+    except OSError as error:
+        if child is None:
+            _write_marker(control_dir, START_FAILED_BASENAME)
+        # Keep errors on the existing stderr path, where credential diagnostics are filtered.
+        print(str(error), file=sys.stderr, flush=True)
+        return PROCESS_START_FAILED_EXIT_CODE
+    finally:
+        if job is not None:
+            job.close()
+
+
+if __name__ == "__main__":
+    supervisor_arguments = sys.argv[SUPERVISOR_ARGUMENT_OFFSET:]
+    control_dir, job_name, poll_ms_value, owner_id_value = supervisor_arguments[:SUPERVISOR_SETTING_ARGUMENT_COUNT]
+    program_filename, *arguments = supervisor_arguments[SUPERVISOR_SETTING_ARGUMENT_COUNT:]
+    try:
+        poll_ms = supervisor_poll_ms(poll_ms_value)
+        supervisor_owner = supervisor_owner_id(owner_id_value)
+    except ValueError as error:
+        _write_marker(control_dir, START_FAILED_BASENAME)
+        print(str(error), file=sys.stderr, flush=True)
+        raise SystemExit(PROCESS_START_FAILED_EXIT_CODE) from None
+    raise SystemExit(supervise(control_dir, job_name, program_filename, arguments, poll_ms=poll_ms, owner_id=supervisor_owner))