gitpane 1.0.0__py3-none-any.whl

gitpane/process/process_runner.py

@@ -0,0 +1,1033 @@
+"""Bound every child process the application runs: its lifetime, its byte streams, its share of a window's concurrency."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import unicodedata
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QElapsedTimer, QObject, QProcess, QProcessEnvironment, QTimer, Signal
+
+import gitpane.process.exact_arguments
+from gitpane.config import (
+    COMMIT_LIMIT_BYTES,
+    DECOMPOSED_UNICODE_FORM,
+    GCM_ENVIRONMENT_PREFIX,
+    GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME,
+    GIT_FSMONITOR_SETTING,
+    GIT_INERT_EDITOR,
+    GIT_LOCAL_ENVIRONMENT_NAMES,
+    GIT_LOCAL_ENVIRONMENT_PREFIXES,
+    GIT_MUTATION_ENVIRONMENT_NAME_SET,
+    GLOBAL_PROCESS_LIMIT,
+    GLOBAL_QUEUE_LIMIT,
+    ISOLATED_INTERPRETER_OPTIONS,
+    MACOS_PLATFORM,
+    NETWORK_ENVIRONMENT_VALUE_SET_BY_NAME,
+    PARSING_BUDGET_MS,
+    PROCESS_CHUNK_BYTES,
+    PROCESS_GROUP_POLL_MS,
+    PROCESS_IDLE_TIMEOUT_MS,
+    PROCESS_TERMINATE_TIMEOUT_MS,
+    SESSION_PROCESS_LIMIT,
+    SESSION_QUEUE_LIMIT,
+    SSH_ENVIRONMENT_NAMES,
+    STDERR_LIMIT_BYTES,
+    TRACE_ENVIRONMENT_PREFIXES,
+    TRACE_STORAGE_LIMIT_BYTES,
+    WINDOWS_PLATFORM,
+    ProcessPriority,
+)
+from gitpane.operation.diagnostic import MASKED_VALUE, SENSITIVE_NAME_PATTERN, SensitiveTextFilter, SensitiveTextStream, mask_sensitive_arguments
+from gitpane.process.exact_arguments import EXACT_ARGUMENTS_ENVIRONMENT_NAME, EXACT_ARGUMENTS_START_FAILED_EXIT_CODE, EXACT_ARGUMENTS_START_FAILURE_PREFIX
+from gitpane.process.process_group import NativeProcessGroup, ProcessGroup, supervisor_interpreter_filename
+from gitpane.tool.editor_bridge import EDITOR_ENVIRONMENT_NAME_SET
+
+if TYPE_CHECKING:
+    from gitpane.tool.editor import EditorExecutionContext
+
+# The profile of a plain read: a process that changes nothing and needs no supervised launcher.
+READ_PROFILE = "read"
+# The profile of a process that talks to the network: isolated environment, error output kept for the console, supervised launcher.
+NETWORK_PROFILE = "network"
+# The profile of a supervised process that writes locally or may run a hook, a filter or the editor.
+LOCAL_WRITE_PROFILE = "local-write"
+# The profile of a process that exchanges a secret: its output is never published.
+CREDENTIAL_PROFILE = "credential"
+TRACKED_PROCESS_PROFILE_SET = frozenset({LOCAL_WRITE_PROFILE, NETWORK_PROFILE, CREDENTIAL_PROFILE})
+# Built from the supervised profiles instead of listed again: the three names that decide supervision
+# are written once, and the only profile that adds nothing to supervise is the plain read.
+ACCEPTED_PROCESS_PROFILE_SET = TRACKED_PROCESS_PROFILE_SET | frozenset({READ_PROFILE})
+
+
+class ProcessStatus(Enum):
+    """How a process request ended, or that it is still running; the value is the word the ``--log`` file writes."""
+
+    RUNNING = "running"
+    """The request was launched and has not ended yet; no published result carries it."""
+    SUCCESS = "success"
+    """The command ran to its end with exit code 0 and no cause of failure."""
+    FAILED = "failed"
+    """The command ran to its end with another exit code, or with a cause of failure."""
+    TIMEOUT = "timeout"
+    """The command was stopped because it ran past its time limit."""
+    CANCELLED = "cancelled"
+    """The user or the closing runner stopped the request, queued or running."""
+    QUEUE_FULL = "queue_full"
+    """The request was refused because too many were already waiting; it never ran."""
+    START_FAILED = "start_failed"
+    """The program could not be launched, refused by its own check or by the system."""
+    IDLE_TIMEOUT = "idle_timeout"
+    """The command was stopped because it wrote nothing for too long."""
+    VOLUME = "volume"
+    """The command was stopped because it wrote more than its output limit."""
+
+
+# Cause of a failure that wrote no error output; written here and recognised by the console, which does not repeat it.
+EXIT_CODE_CAUSE_TEMPLATE = "Process exited with code {return_code}"
+# The systems whose Qt rewrites every argument QProcess passes into its decomposed Unicode form.
+DECOMPOSED_ARGUMENT_PLATFORM_SET = frozenset({MACOS_PLATFORM})
+# The systems where stopping a read can leave running a program it started, with the files it opened still open. On
+# Windows, Git for Windows' cmd\git.exe is a wrapper that starts the real git.exe: stopping the wrapper leaves git.exe
+# alive until its next write to the closed output fails, and Windows refuses to delete a file it still has open.
+STOPPED_READ_LEAVES_CHILD_PLATFORM_SET = frozenset({WINDOWS_PLATFORM})
+
+
+@dataclass(frozen=True)
+class ProcessRequest:
+    """Capture immutable launch identity and limits before a command enters the queue.
+
+    The priority only decides which waiting request takes the next free slot; it says nothing about what the command
+    may do, so it never takes part in the choice of a launch profile or of supervision.
+
+    ``accepted_return_codes`` are the exit codes the caller does not hold for an error, such as 1 for a reference
+    lookup that may find nothing. Only the operation console reads them; the launch and the result status ignore them.
+    """
+
+    request_id: str
+    program_filename: str
+    arguments: list[str]
+    working_dir: str
+    timeout_ms: int
+    session_id: str = "application"
+    stdout_limit_bytes: int | None = COMMIT_LIMIT_BYTES
+    stderr_limit_bytes: int = STDERR_LIMIT_BYTES
+    idle_timeout_ms: int = PROCESS_IDLE_TIMEOUT_MS
+    stdin: bytes | None = None
+    environment_by_name: dict[str, str] = field(default_factory=dict)
+    operation: str = "Read"
+    wait_for_exit_on_stop: bool = False
+    profile: str = READ_PROFILE
+    operation_id: str = ""
+    before_start: Callable[[], None] | None = None
+    editor_context: EditorExecutionContext | None = field(default=None, repr=False)
+    suppress_editor: bool = False
+    priority: ProcessPriority = ProcessPriority.USER
+    # The group a supervised request runs in, when it needs another one than its runner's default; None keeps the default.
+    process_group_factory: Callable[[], ProcessGroup] | None = field(default=None, repr=False)
+    accepted_return_codes: tuple[int, ...] = (0,)
+    # The caller owns this file until the terminal result; Qt opens it only when the request leaves the queue.
+    stdin_filename: str | None = None
+    # The caller deletes the files this command opens as soon as it ends. Where a stopped read can leave a program it
+    # started running, such a read runs under the supervisor, so its end is only reported once nothing it started is left.
+    opens_files_deleted_at_end: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject competing input sources before a process can enter the queue."""
+        if self.stdin is not None and self.stdin_filename is not None:
+            raise ValueError("stdin and stdin_filename are mutually exclusive")
+
+
+@dataclass(frozen=True)
+class ProcessResult:
+    """Report one terminal outcome with complete bounded stderr and launch context.
+
+    The two timings split the whole life of the request and lose nothing between them: the queue wait runs from the
+    moment the request was received to the moment it left the queue, or to its outcome when it never left; the
+    duration runs from that departure to the outcome, and is zero for a request that never started.
+    """
+
+    request: ProcessRequest
+    status: ProcessStatus
+    return_code: int | None
+    cause: str
+    stderr: bytes
+    queue_wait_ms: int = 0
+    duration_ms: int = 0
+
+
+GIT_GLOBAL_FLAG_SET = frozenset({"--literal-pathspecs", "--no-literal-pathspecs"})
+GIT_GLOBAL_VALUE_OPTION_SET = frozenset({"-c", "-C", "--git-dir", "--work-tree"})
+
+
+def needs_exact_arguments(platform: str, program_filename: str, arguments: list[str]) -> bool:
+    """Tell whether a command must reach its program through the exact-arguments relay on ``platform``.
+
+    Only a system whose Qt decomposes arguments needs it, and there only for a command whose program or one argument
+    changes when decomposed: an all-ASCII command, the usual case, is started directly and costs nothing more.
+    """
+    if platform not in DECOMPOSED_ARGUMENT_PLATFORM_SET:
+        return False
+    if not unicodedata.is_normalized(DECOMPOSED_UNICODE_FORM, program_filename):
+        return True
+    for argument in arguments:
+        if not unicodedata.is_normalized(DECOMPOSED_UNICODE_FORM, argument):
+            return True
+    return False
+
+
+def exact_arguments_relay_filename() -> str:
+    """Answer the absolute file of the exact-arguments relay, as imported from the installation; a missing file is a launch error."""
+    relay_filename = os.path.abspath(gitpane.process.exact_arguments.__file__)
+    if not os.path.isfile(relay_filename):
+        raise OSError("The exact-arguments relay is not available: " + relay_filename)
+    return relay_filename
+
+
+def relay_start_failure_cause(relayed: bool, return_code: int | None, stderr: bytes) -> str | None:
+    """Answer the relay's refusal line when a relayed command never started, or None when the command itself ran.
+
+    QProcess starts the relay without trouble, so a program the relay cannot start shows up as an ordinary exit. Only
+    the relay's exit code together with its refusal line means the program did not start: a command that ran may
+    answer 127 on its own, and its answer must stay a return code.
+    """
+    if not relayed or return_code != EXACT_ARGUMENTS_START_FAILED_EXIT_CODE:
+        return None
+    error_text = stderr.decode("utf-8", "replace").strip()
+    if not error_text.startswith(EXACT_ARGUMENTS_START_FAILURE_PREFIX):
+        return None
+    return error_text
+
+
+def stopped_read_leaves_child(platform: str) -> bool:
+    """Tell whether stopping a read on ``platform`` can leave running a program it started, with its files still open."""
+    return platform in STOPPED_READ_LEAVES_CHILD_PLATFORM_SET
+
+
+def is_supervised_request(request: ProcessRequest, platform: str = sys.platform) -> bool:
+    """Tell whether a request must run under the supervisor that tracks its native descendants on ``platform``.
+
+    Writes and waited-for commands always are. A read is only when its caller deletes the files it opens right after
+    its end, and only on a system where stopping it can leave a program it started holding them: elsewhere the read
+    stays a plain process, which costs no interpreter and no group.
+    """
+    if request.profile in TRACKED_PROCESS_PROFILE_SET or request.wait_for_exit_on_stop:
+        return True
+    return request.opens_files_deleted_at_end and stopped_read_leaves_child(platform)
+
+
+def git_subcommand_index(arguments: list[str]) -> int | None:
+    """Return the position of the Git subcommand behind the global options placed in front of it, or nothing."""
+    skip_value = False
+    for position, argument in enumerate(arguments):
+        if skip_value:
+            skip_value = False
+            continue
+        if argument in GIT_GLOBAL_VALUE_OPTION_SET:
+            skip_value = True
+            continue
+        option_name, separator, _value = argument.partition("=")
+        if separator and option_name in GIT_GLOBAL_VALUE_OPTION_SET:
+            continue
+        if argument in GIT_GLOBAL_FLAG_SET:
+            continue
+        return position
+    return None
+
+
+def git_subcommand(arguments: list[str]) -> str:
+    """Return the Git subcommand hidden behind the global options placed in front of it, or an empty name."""
+    position = git_subcommand_index(arguments)
+    return "" if position is None else arguments[position]
+
+
+OPTION_PREFIX = "-"
+OPTION_VALUE_SEPARATOR = "="
+PATHSPEC_SEPARATOR = "--"
+
+
+@dataclass(frozen=True)
+class ReadForm:
+    """Describe the shape a subcommand must have to write nothing and run no program of the user.
+
+    Each field narrows the accepted shape: options that make the command write or convert are forbidden, one of the
+    required option groups must be complete, a non-empty permitted list closes the form to anything else, the first
+    word may be restricted to a few modes, and the number of words may be capped.
+    """
+
+    forbidden_option_set: frozenset[str] = frozenset()
+    required_option_sets: tuple[frozenset[str], ...] = ()
+    permitted_option_set: frozenset[str] = frozenset()
+    first_word_set: frozenset[str] = frozenset()
+    maximum_word_count: int | None = None
+
+
+# One shape shared by the three comparison subcommands: porcelain and plumbing alike run the user's external diff
+# program and text conversion as soon as they are asked for a patch, so all three demand the same positive proof.
+DIFF_READ_FORM = ReadForm(forbidden_option_set=frozenset({"--ext-diff", "--textconv"}),
+                          required_option_sets=(frozenset({"--no-ext-diff", "--no-textconv"}), frozenset({"--name-only"}), frozenset({"--name-status"})))
+
+# The only list of Git subcommands that read. It is closed on purpose: an unknown subcommand is not a read, because
+# being wrong the other way would let a hook or a filter still run after the repository has been handed back. The
+# quiet form of a comparison is not accepted either: an external diff program whose exit code is declared reliable
+# still runs, and its answer becomes the exit code of the command.
+READ_FORM_BY_SUBCOMMAND: dict[str, ReadForm] = {
+    "--version": ReadForm(),
+    "--exec-path": ReadForm(),
+    "check-attr": ReadForm(),
+    "check-ignore": ReadForm(),
+    "check-ref-format": ReadForm(),
+    "for-each-ref": ReadForm(),
+    "ls-files": ReadForm(),
+    "ls-tree": ReadForm(),
+    "merge-base": ReadForm(),
+    "rev-list": ReadForm(),
+    "rev-parse": ReadForm(),
+    "status": ReadForm(),
+    "var": ReadForm(),
+    "version": ReadForm(),
+    "cat-file": ReadForm(forbidden_option_set=frozenset({"--filters", "--textconv"})),
+    "fast-export": ReadForm(required_option_sets=(frozenset({"--no-data", "--no-renames", "--show-original-ids", "--use-done-feature"}),),
+                            permitted_option_set=frozenset({"--no-data", "--no-renames", "--show-original-ids", "--use-done-feature", "--reencode", "--signed-commits", "--stdin"})),
+    "diff": DIFF_READ_FORM,
+    "diff-index": DIFF_READ_FORM,
+    "diff-tree": DIFF_READ_FORM,
+    # Closed by its permitted options rather than by forbidden ones: the flags that produce a patch are too many to
+    # list without missing the next one, and a patch runs the user's external diff program or text conversion.
+    "log": ReadForm(permitted_option_set=frozenset({"--no-walk", "--ignore-missing", "--no-decorate", "--no-notes", "--no-show-signature",
+                                                    "--encoding", "--format", "--max-count", "--stdin", "-z", "--topo-order"})),
+    "show": ReadForm(forbidden_option_set=frozenset({"--ext-diff", "--textconv"}),
+                     required_option_sets=(frozenset({"-s"}), frozenset({"--no-patch"}), frozenset({"--no-ext-diff", "--no-textconv"}))),
+    "hash-object": ReadForm(forbidden_option_set=frozenset({"-w"}), required_option_sets=(frozenset({"--no-filters"}),)),
+    "merge-file": ReadForm(required_option_sets=(frozenset({"-p"}), frozenset({"--stdout"}))),
+    "config": ReadForm(forbidden_option_set=frozenset({"--add", "--unset", "--unset-all", "--replace-all", "--rename-section", "--remove-section", "--edit", "-e"}),
+                       required_option_sets=(frozenset({"--get"}), frozenset({"--get-all"}), frozenset({"--get-regexp"}), frozenset({"--get-urlmatch"}),
+                                             frozenset({"--list"}), frozenset({"-l"}))),
+    "symbolic-ref": ReadForm(forbidden_option_set=frozenset({"-d", "--delete", "-m"}), maximum_word_count=1),
+    "remote": ReadForm(first_word_set=frozenset({"get-url"})),
+    "worktree": ReadForm(first_word_set=frozenset({"list"})),
+    "reflog": ReadForm(first_word_set=frozenset({"show"})),
+    "submodule": ReadForm(first_word_set=frozenset({"status"})),
+    "ls-remote": ReadForm(required_option_sets=(frozenset({"--get-url"}),)),
+}
+
+READ_SUBCOMMAND_SET = frozenset(READ_FORM_BY_SUBCOMMAND)
+
+
+def is_read_command(arguments: list[str]) -> bool:
+    """Tell whether a Git command only reads: it changes nothing and starts no program belonging to the user.
+
+    Options are read the way this program writes them, one per argument and never grouped into a single letter block.
+    An option is an argument starting with a dash and placed before the pathspec separator, compared by the name in
+    front of its first equals sign; everything else is a word, including every argument after that separator.
+    """
+    position = git_subcommand_index(arguments)
+    if position is None:
+        return False
+    form = READ_FORM_BY_SUBCOMMAND.get(arguments[position])
+    if form is None:
+        return False
+    option_set: set[str] = set()
+    words: list[str] = []
+    after_separator = False
+    for argument in arguments[position + 1:]:
+        if not after_separator and argument == PATHSPEC_SEPARATOR:
+            after_separator = True
+            continue
+        if not after_separator and argument.startswith(OPTION_PREFIX):
+            option_name, _separator, _value = argument.partition(OPTION_VALUE_SEPARATOR)
+            option_set.add(option_name)
+            continue
+        words.append(argument)
+    if option_set & form.forbidden_option_set:
+        return False
+    if form.required_option_sets:
+        satisfied = False
+        for required_option_set in form.required_option_sets:
+            if required_option_set.issubset(option_set):
+                satisfied = True
+                break
+        if not satisfied:
+            return False
+    if form.permitted_option_set and not option_set.issubset(form.permitted_option_set):
+        return False
+    first_word_index = 0
+    if form.first_word_set and words and words[first_word_index] not in form.first_word_set:
+        return False
+    if form.maximum_word_count is None:
+        return True
+    return len(words) <= form.maximum_word_count
+
+
+@dataclass
+class _RunningProcess:
+    """Keep process resources alive until both termination and final draining complete."""
+
+    request: ProcessRequest
+    process: QProcess
+    deadline: QTimer
+    inactivity: QTimer
+    kill_timer: QTimer
+    group_timer: QTimer
+    group: ProcessGroup | None = None
+    stderr: bytearray = field(default_factory=bytearray)
+    stdout_size: int = 0
+    status: ProcessStatus = ProcessStatus.RUNNING
+    cause: str = ""
+    return_code: int | None = None
+    exited: bool = False
+    drain_pending: bool = False
+    stdout_paused: bool = False
+    credential_stream: SensitiveTextStream | None = None
+    ssh_stdout_stream: SensitiveTextStream | None = None
+    stderr_truncated: bool = False
+    drainage_uncertain: bool = False
+    editor_waiting: bool = False
+    editor_deadline_remaining_ms: int = 0
+    editor_idle_remaining_ms: int = 0
+    received_ms: int = 0
+    launched_ms: int = 0
+    relayed: bool = False
+
+
+class ProcessRunner(QObject):
+    """Own queued and running QProcess objects without blocking the Qt event loop."""
+
+    stdout_chunk = Signal(object, bytes)
+    stderr_chunk = Signal(object, bytes)
+    finished = Signal(object)
+    idle = Signal()
+    stop_requested = Signal(object, str)
+    started = Signal(object)
+
+    def __init__(self, parent: QObject | None = None, global_limit: int = GLOBAL_PROCESS_LIMIT, session_limit: int = SESSION_PROCESS_LIMIT,
+                 global_queue_limit: int = GLOBAL_QUEUE_LIMIT, session_queue_limit: int = SESSION_QUEUE_LIMIT, credential_consumer: Callable[[str, bytes], None] | None = None,
+                 process_group_factory: Callable[[], ProcessGroup] = NativeProcessGroup, clock_ms: Callable[[], int] | None = None) -> None:
+        """Allow small injected bounds in tests while keeping production limits centralized.
+
+        The clock is injectable too, so timing tests read exact durations instead of depending on how fast the machine is.
+        """
+        super().__init__(parent)
+        if min(global_limit, session_limit, global_queue_limit, session_queue_limit) < 1:
+            raise ValueError("Process and queue limits must be positive")
+        self.global_limit = global_limit
+        self.session_limit = session_limit
+        self.global_queue_limit = global_queue_limit
+        self.session_queue_limit = session_queue_limit
+        self.active_by_id: dict[str, _RunningProcess] = {}
+        self.pending_requests: list[ProcessRequest] = []
+        self.closed = False
+        # Set while the queue is being emptied: a subscriber reacting to a launch cannot start a second, nested pass.
+        self.pumping = False
+        self.credential_consumer = credential_consumer
+        self.process_group_factory = process_group_factory
+        self.elapsed_timer = QElapsedTimer()
+        self.elapsed_timer.start()
+        self.clock_ms: Callable[[], int] = clock_ms if clock_ms is not None else self.elapsed_timer.elapsed
+        self.received_ms_by_id: dict[str, int] = {}
+        # Qt deletes the QProcess children after the runner itself, and a QProcess deleted while its program runs kills
+        # it, waits for it, and emits its output, error and end signals from inside that deletion. Their callbacks would
+        # then reach a runner and a QProcess whose C++ objects are already gone. Forgetting every running process when the
+        # runner goes makes each callback's ownership check turn them away; the dying QProcess still kills its program.
+        # The callback holds the dictionary, not the runner, so the runner's wrapper stays free to go with it.
+        active_by_id = self.active_by_id
+        self.destroyed.connect(lambda: active_by_id.clear())
+
+    def start(self, request: ProcessRequest) -> None:
+        """Snapshot arguments and working directory before launching or queuing work."""
+        if request.timeout_ms <= 0 or request.idle_timeout_ms <= 0 or request.stderr_limit_bytes < 0 or (request.stdout_limit_bytes is not None and request.stdout_limit_bytes < 0):
+            raise ValueError("Invalid timeouts or output limits")
+        if request.request_id in self.active_by_id or any(pending.request_id == request.request_id for pending in self.pending_requests):
+            raise ValueError("Request ID is already active")
+        if request.profile not in ACCEPTED_PROCESS_PROFILE_SET:
+            raise ValueError("Unsupported process profile")
+        if request.stdin_filename is not None and (not os.path.isabs(request.stdin_filename) or "\0" in request.stdin_filename):
+            raise ValueError("The input file path must be absolute and contain no NUL")
+        # The exact type is required: a boolean or a plain number would otherwise pass for a level by accident.
+        if type(request.priority) is not ProcessPriority:
+            raise ValueError("Unsupported process priority")
+        if type(request.suppress_editor) is not bool or request.suppress_editor and (request.profile != LOCAL_WRITE_PROFILE or request.editor_context is not None):
+            raise ValueError("Editor suppression requires a local write without an interactive editor.")
+        editor_environment_by_name: dict[str, str] = {}
+        if request.editor_context is not None:
+            from gitpane.tool.editor import EditorExecutionContext
+            if (not isinstance(request.editor_context, EditorExecutionContext) or request.profile != LOCAL_WRITE_PROFILE
+                    or not request.editor_context.owns(request.operation_id) or request.editor_context.process_request_id):
+                raise ValueError("The editor context is expired, already bound or belongs to another operation.")
+            editor_environment_by_name = request.editor_context.environment()
+        for name, value in request.environment_by_name.items():
+            editor_allowed = name in editor_environment_by_name and value == editor_environment_by_name[name]
+            # One domain-selected directory, never a caller-supplied Git search list. Git's quoting is applied only at launch.
+            alternate_allowed = (name == GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME and request.profile in {READ_PROFILE, LOCAL_WRITE_PROFILE}
+                                 and os.path.isabs(value) and "\0" not in value and os.path.isdir(value))
+            network_allowed = request.profile in {NETWORK_PROFILE, CREDENTIAL_PROFILE} and value in NETWORK_ENVIRONMENT_VALUE_SET_BY_NAME.get(name, ())
+            if request.profile in {NETWORK_PROFILE, CREDENTIAL_PROFILE} and name == "GIT_CONFIG_GLOBAL" and value == os.devnull:
+                network_allowed = True
+            if request.profile == NETWORK_PROFILE:
+                if name == "GIT_SSH":
+                    network_allowed = os.path.isabs(value) and os.path.isfile(value) and os.access(value, os.X_OK)
+                elif name == "GIT_SSH_VARIANT":
+                    network_allowed = value == "ssh"
+                elif name == "PATH":
+                    network_allowed = os.name == "nt" and all(os.path.isabs(directory) for directory in value.split(os.pathsep) if directory)
+                elif name in {"SSH_ASKPASS", "GIT_ASKPASS"}:
+                    network_allowed = os.path.isabs(value) and os.path.isfile(value) and os.access(value, os.X_OK)
+                elif name == "SSH_ASKPASS_REQUIRE":
+                    network_allowed = value == "force"
+                elif name == "DISPLAY":
+                    network_allowed = value == "gitpane:0"
+                elif name == "GIT_CEILING_DIRECTORIES":
+                    # Only narrows where Git looks for a repository, so a command run from an empty folder reads no repository's settings.
+                    network_allowed = all(os.path.isabs(directory) for directory in value.split(os.pathsep) if directory)
+                elif name in SSH_ENVIRONMENT_NAMES:
+                    network_allowed = bool(request.operation_id) and len(value) <= 512 and not any(character in value for character in "\r\n")
+            if (name not in GIT_MUTATION_ENVIRONMENT_NAME_SET and not network_allowed and not editor_allowed and not alternate_allowed) or not value or "\0" in value:
+                raise ValueError("Unsupported Git process environment override")
+            if name == "GIT_INDEX_FILE" and not os.path.isabs(value):
+                raise ValueError("The candidate index path must be absolute")
+        stderr_limit = TRACE_STORAGE_LIMIT_BYTES if request.profile in {NETWORK_PROFILE, CREDENTIAL_PROFILE} and request.stderr_limit_bytes == STDERR_LIMIT_BYTES else request.stderr_limit_bytes
+        captured = replace(request, arguments=list(request.arguments), working_dir=os.path.abspath(request.working_dir), environment_by_name=dict(request.environment_by_name), stderr_limit_bytes=stderr_limit)
+        if request.editor_context is not None:
+            captured.environment_by_name.update(editor_environment_by_name)
+            request.editor_context.process_request_id = request.request_id
+        received_ms = self.clock_ms()
+        queued_for_session = sum(pending.session_id == request.session_id for pending in self.pending_requests)
+        if self.closed or len(self.pending_requests) >= self.global_queue_limit or queued_for_session >= self.session_queue_limit:
+            status = ProcessStatus.CANCELLED if self.closed else ProcessStatus.QUEUE_FULL
+            cause = "Runner closed" if self.closed else "Process queue is full"
+            cause = self._close_editor(captured, cause)
+            QTimer.singleShot(0, self, lambda: self.finished.emit(self._timed_result(captured, status, None, cause, b"", received_ms, None)))
+            return
+        self.received_ms_by_id[captured.request_id] = received_ms
+        self.pending_requests.append(captured)
+        self._pump()
+
+    def cancel(self, request_id: str) -> None:
+        """Abandon a queued request or stop a running one while retaining write diagnostics."""
+        for request in tuple(self.pending_requests):
+            if request.request_id == request_id:
+                self.pending_requests.remove(request)
+                received_ms = self.received_ms_by_id.pop(request.request_id, self.clock_ms())
+                cause = self._close_editor(request, request.operation + " cancelled")
+                self.finished.emit(self._timed_result(request, ProcessStatus.CANCELLED, None, cause, b"", received_ms, None))
+                self._notify_idle()
+                return
+        active = self.active_by_id.get(request_id)
+        if active is not None:
+            self._stop(active, ProcessStatus.CANCELLED, active.request.operation + " cancelled")
+
+    def protect_secret(self, request_id: str, secret: str) -> None:
+        """Register an SSH answer before its child can echo it on either public stream."""
+        active = self.active_by_id.get(request_id)
+        if active is None or active.credential_stream is None or not secret:
+            return
+        active.credential_stream.filter.sensitive_value_set.add(secret)
+
+    def pause_stdout(self, request_id: str) -> None:
+        """Let a consumer finish its parsing turn before draining additional stdout."""
+        active = self.active_by_id.get(request_id)
+        if active is not None:
+            active.stdout_paused = True
+
+    def resume_stdout(self, request_id: str) -> None:
+        """Resume bounded reads after the consumer has released its parsing backlog."""
+        active = self.active_by_id.get(request_id)
+        if active is not None:
+            active.stdout_paused = False
+            self._schedule_drain(active)
+
+    def cancel_session(self, session_id: str) -> None:
+        """Cancel only one window's work, including requests still waiting for a slot."""
+        request_ids: list[str] = []
+        for request in self.pending_requests:
+            if request.session_id == session_id:
+                request_ids.append(request.request_id)
+        for request_id, active in self.active_by_id.items():
+            if active.request.session_id == session_id:
+                request_ids.append(request_id)
+        for request_id in request_ids:
+            self.cancel(request_id)
+
+    def close(self) -> None:
+        """Begin asynchronous shutdown and emit idle once all children have stopped."""
+        self.closed = True
+        request_ids: list[str] = []
+        for request in self.pending_requests:
+            request_ids.append(request.request_id)
+        request_ids.extend(self.active_by_id)
+        for request_id in request_ids:
+            self.cancel(request_id)
+        self._notify_idle()
+
+    def _pump(self) -> None:
+        """Fill every free slot with the most urgent eligible request, without letting a busy session block other sessions.
+
+        The state is read again before every launch, because a launch can publish synchronously and its subscribers can
+        start, cancel or close. A call made from inside one of those publications returns at once: the pass already
+        under way sees what it changed on its next turn.
+        """
+        if self.closed or self.pumping:
+            return
+        self.pumping = True
+        try:
+            while not self.closed and len(self.active_by_id) < self.global_limit:
+                request = self._next_eligible_request()
+                if request is None:
+                    return
+                self.pending_requests.remove(request)
+                self._launch(request)
+        finally:
+            self.pumping = False
+
+    def _next_eligible_request(self) -> ProcessRequest | None:
+        """Answer the waiting request to launch next: the most urgent level first, and the earliest arrival within a level.
+
+        Only a request whose session still has a free slot is eligible, so a saturated session never holds back another one.
+        """
+        active_count_by_session: dict[str, int] = {}
+        for active in self.active_by_id.values():
+            active_count_by_session[active.request.session_id] = active_count_by_session.get(active.request.session_id, 0) + 1
+        selected: ProcessRequest | None = None
+        for request in self.pending_requests:
+            if active_count_by_session.get(request.session_id, 0) >= self.session_limit:
+                continue
+            if selected is None or request.priority < selected.priority:
+                selected = request
+        return selected
+
+    def _timed_result(self, request: ProcessRequest, status: ProcessStatus, return_code: int | None, cause: str, stderr: bytes, received_ms: int, launched_ms: int | None) -> ProcessResult:
+        """Build every outcome the runner publishes, so none of them reaches a subscriber without its two timings.
+
+        A request that never left the queue has no launch instant: it waited until its own outcome and ran for no time.
+        """
+        now_ms = self.clock_ms()
+        if launched_ms is None:
+            queue_wait_ms, duration_ms = now_ms - received_ms, 0
+        else:
+            queue_wait_ms, duration_ms = launched_ms - received_ms, now_ms - launched_ms
+        return ProcessResult(self._public_request(request), status, return_code, cause, stderr, queue_wait_ms=queue_wait_ms, duration_ms=duration_ms)
+
+    def _launch(self, request: ProcessRequest) -> None:
+        """Start the program the request names, as a bounded child, after clearing inherited repository-specific Git overrides.
+
+        Every command, on every system, gets the command-scope setting ``core.fsmonitor=false`` through
+        ``GIT_CONFIG_COUNT`` in place of the command-scope settings the user's shell passed: Git never starts its
+        fsmonitor daemon for GitPane, so no daemon can keep a supervised command's process group alive.
+        A supervised request hands that same program to its process group, which may wrap it in its own command line.
+        On macOS, a command whose program or an argument Qt would decompose is started through the exact-arguments
+        relay instead: QProcess starts the base interpreter on the relay, the exact command (the supervisor's, for a
+        supervised request) travels in the relay's variable, and the relay replaces itself with it, keeping its process
+        id. The published request and the log keep the logical command in every case.
+        """
+        launched_ms = self.clock_ms()
+        received_ms = self.received_ms_by_id.pop(request.request_id, launched_ms)
+        group = None
+        program_filename, arguments = request.program_filename, request.arguments
+        exact_command: list[str] | None = None
+        try:
+            if request.editor_context is not None and not request.editor_context.owns(request.operation_id):
+                raise ValueError("The editor context expired before command launch.")
+            if request.before_start is not None:
+                request.before_start()
+            if is_supervised_request(request):
+                group = (request.process_group_factory or self.process_group_factory)()
+                program_filename, arguments = group.prepare(program_filename, arguments)
+            if needs_exact_arguments(sys.platform, program_filename, arguments):
+                exact_command = [program_filename, *arguments]
+                program_filename, arguments = supervisor_interpreter_filename(), [*ISOLATED_INTERPRETER_OPTIONS, exact_arguments_relay_filename()]
+        except (OSError, ValueError, RuntimeError) as error:
+            if group is not None:
+                try:
+                    group.close()
+                except OSError:
+                    pass
+            QTimer.singleShot(0, self, lambda cause=str(error): self._launch_failed(request, cause, received_ms, launched_ms))
+            return
+        process = QProcess(self)
+        deadline = QTimer(process)
+        inactivity = QTimer(process)
+        kill_timer = QTimer(process)
+        group_timer = QTimer(process)
+        for timer in (deadline, inactivity, kill_timer, group_timer):
+            timer.setSingleShot(True)
+        active = _RunningProcess(request, process, deadline, inactivity, kill_timer, group_timer, group=group, received_ms=received_ms, launched_ms=launched_ms,
+                                 relayed=exact_command is not None)
+        if request.editor_context is not None:
+            text_filter = SensitiveTextFilter(request.environment_by_name)
+            text_filter.sensitive_value_set.add(request.editor_context.token)
+            active.credential_stream = SensitiveTextStream(text_filter)
+            active.ssh_stdout_stream = SensitiveTextStream(text_filter)
+            request.editor_context.bind_peer(request.operation_id, lambda peer: self.active_by_id.get(request.request_id) is active
+                                            and active.status == ProcessStatus.RUNNING and active.group is not None and active.group.contains_process(peer))
+            request.editor_context.wait_changed.connect(lambda waiting: self._editor_wait_changed(active, waiting))
+            request.editor_context.failed.connect(lambda cause: self._editor_failure(active, cause))
+        elif request.profile == CREDENTIAL_PROFILE:
+            active.credential_stream = SensitiveTextStream(SensitiveTextFilter(self._credential_value_by_name(request)))
+        elif request.profile == NETWORK_PROFILE and "GITPANE_SSH_NONCE" in request.environment_by_name:
+            text_filter = SensitiveTextFilter(request.environment_by_name)
+            active.credential_stream = SensitiveTextStream(text_filter)
+            active.ssh_stdout_stream = SensitiveTextStream(text_filter)
+        self.active_by_id[request.request_id] = active
+        process.setProgram(program_filename)
+        process.setArguments(arguments)
+        process.setWorkingDirectory(request.working_dir)
+        if request.stdin_filename is not None:
+            process.setStandardInputFile(request.stdin_filename)
+        environment = QProcessEnvironment.systemEnvironment()
+        inherited_names = environment.keys()
+        for name in inherited_names:
+            if name.upper() in GIT_LOCAL_ENVIRONMENT_NAMES or name.upper().startswith(GIT_LOCAL_ENVIRONMENT_PREFIXES):
+                environment.remove(name)
+            if name.upper().startswith(TRACE_ENVIRONMENT_PREFIXES):
+                environment.remove(name)
+            if request.profile in {NETWORK_PROFILE, CREDENTIAL_PROFILE} and name.upper().startswith(GCM_ENVIRONMENT_PREFIX):
+                environment.remove(name)
+            if request.profile == NETWORK_PROFILE and name.upper() in {"GIT_SSH", "GIT_SSH_COMMAND", "GIT_SSH_VARIANT", "SSH_ASKPASS", "SSH_ASKPASS_REQUIRE", "GIT_ASKPASS"}:
+                environment.remove(name)
+            if name.upper().startswith(("GITPANE_SSH_", "GITPANE_EDITOR_")) or name.upper() in EDITOR_ENVIRONMENT_NAME_SET:
+                environment.remove(name)
+        environment.insert("GIT_TERMINAL_PROMPT", "0")
+        environment.insert("GIT_OPTIONAL_LOCKS", "0")
+        environment.insert("GIT_NO_LAZY_FETCH", "1")
+        environment.insert("GIT_NO_REPLACE_OBJECTS", "1")
+        environment.insert("LC_ALL", "C")
+        # The inherited count and its keys were removed above, so GitPane's setting takes index 0.
+        fsmonitor_key, fsmonitor_value = GIT_FSMONITOR_SETTING
+        environment.insert("GIT_CONFIG_COUNT", "1")
+        environment.insert("GIT_CONFIG_KEY_0", fsmonitor_key)
+        environment.insert("GIT_CONFIG_VALUE_0", fsmonitor_value)
+        for name, value in request.environment_by_name.items():
+            if name == GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME and os.pathsep in value:
+                # Git splits unquoted alternates on the platform separator. Octal C escapes preserve every filename byte;
+                # JSON's Unicode escapes are not accepted by Git's path parser.
+                quoted_parts = ['"']
+                for byte in os.fsencode(value):
+                    quoted_parts.append(f"\\{byte:03o}")
+                quoted_parts.append('"')
+                value = "".join(quoted_parts)
+            environment.insert(name, value)
+        if request.suppress_editor:
+            environment.insert("GIT_EDITOR", GIT_INERT_EDITOR)
+        # Set last, so neither the inherited environment nor the request can replace the command the relay runs.
+        if exact_command is not None:
+            environment.insert(EXACT_ARGUMENTS_ENVIRONMENT_NAME, json.dumps(exact_command))
+        process.setProcessEnvironment(environment)
+        process.readyReadStandardOutput.connect(lambda: self._schedule_drain(active))
+        process.readyReadStandardError.connect(lambda: self._schedule_drain(active))
+        process.finished.connect(lambda code, status: self._exit(active, code, status))
+        process.errorOccurred.connect(lambda error: self._error(active, error))
+        deadline.timeout.connect(lambda: self._stop(active, ProcessStatus.TIMEOUT, f"Timed out ({request.timeout_ms} ms)"))
+        inactivity.timeout.connect(lambda: self._stop(active, ProcessStatus.IDLE_TIMEOUT, f"No output for {request.idle_timeout_ms} ms"))
+        kill_timer.timeout.connect(process.kill)
+        group_timer.timeout.connect(lambda: self._poll_group(active))
+        deadline.start(request.timeout_ms)
+        inactivity.start(request.idle_timeout_ms)
+        self.started.emit(self._public_request(request))
+        process.start()
+        if request.stdin is not None:
+            process.write(request.stdin)
+            process.closeWriteChannel()
+
+    def _launch_failed(self, request: ProcessRequest, cause: str, received_ms: int, launched_ms: int) -> None:
+        """Publish setup failure without launching an untracked write as a fallback."""
+        if request.profile == CREDENTIAL_PROFILE:
+            cause = SensitiveTextFilter(self._credential_value_by_name(request)).redact(cause)
+        if request.editor_context is not None:
+            cause = SensitiveTextFilter(request.environment_by_name).redact(cause)
+        cause = self._close_editor(request, cause)
+        self.finished.emit(self._timed_result(request, ProcessStatus.START_FAILED, None, cause, b"", received_ms, launched_ms))
+        self._pump()
+        self._notify_idle()
+
+    def _close_editor(self, request: ProcessRequest, cause: str) -> str:
+        """Attach retryable private cleanup diagnostics without changing the command's exit status."""
+        if request.editor_context is None:
+            return cause
+        cleanup_cause = request.editor_context.close()
+        if not cleanup_cause:
+            return cause
+        return cause + "; " + cleanup_cause if cause else cleanup_cause
+
+    def _editor_wait_changed(self, active: _RunningProcess, waiting: bool) -> None:
+        """Account only live authenticated editing time outside this command's remaining budgets."""
+        context = active.request.editor_context
+        if self.active_by_id.get(active.request.request_id) is not active or active.status != ProcessStatus.RUNNING or active.exited or context is None:
+            return
+        if waiting:
+            if active.editor_waiting or not context.owns(active.request.operation_id) or context.pending_socket is None:
+                return
+            active.editor_deadline_remaining_ms = max(1, active.deadline.remainingTime())
+            active.editor_idle_remaining_ms = max(1, active.inactivity.remainingTime())
+            active.deadline.stop()
+            active.inactivity.stop()
+            active.editor_waiting = True
+            return
+        if not active.editor_waiting:
+            return
+        active.editor_waiting = False
+        active.deadline.start(active.editor_deadline_remaining_ms)
+        active.inactivity.start(active.editor_idle_remaining_ms)
+
+    def _editor_failure(self, active: _RunningProcess, cause: str) -> None:
+        """Expose a fixed bridge diagnostic without including credentials or arbitrary editor output."""
+        if self.active_by_id.get(active.request.request_id) is not active:
+            return
+        data = (cause + "\n").encode("utf-8")
+        active.stderr.extend(data)
+        self.stderr_chunk.emit(self._public_request(active.request), data)
+
+    def _schedule_drain(self, active: _RunningProcess) -> None:
+        """Schedule one bounded consumer turn for available process bytes."""
+        if self.active_by_id.get(active.request.request_id) is not active or active.drain_pending:
+            return
+        active.drain_pending = True
+        QTimer.singleShot(0, self, lambda: self._drain(active))
+
+    def _drain(self, active: _RunningProcess) -> None:
+        """Read bounded chunks within a time budget, then yield back to Qt."""
+        if self.active_by_id.get(active.request.request_id) is not active:
+            return
+        active.drain_pending = False
+        if active.exited and not active.process.isOpen():
+            self._complete(active)
+            return
+        budget = QElapsedTimer()
+        budget.start()
+        while budget.elapsed() < PARSING_BUDGET_MS:
+            consumed = False
+            for channel in (QProcess.ProcessChannel.StandardOutput, QProcess.ProcessChannel.StandardError):
+                if channel == QProcess.ProcessChannel.StandardOutput and active.stdout_paused and active.status == ProcessStatus.RUNNING:
+                    continue
+                active.process.setReadChannel(channel)
+                data = bytes(active.process.read(PROCESS_CHUNK_BYTES))
+                if not data:
+                    continue
+                consumed = True
+                if active.status != ProcessStatus.RUNNING and active.group is None:
+                    continue
+                if active.status == ProcessStatus.RUNNING and not active.editor_waiting:
+                    active.inactivity.start(active.request.idle_timeout_ms)
+                if channel == QProcess.ProcessChannel.StandardOutput:
+                    active.stdout_size += len(data)
+                    if active.request.stdout_limit_bytes is not None and active.stdout_size > active.request.stdout_limit_bytes:
+                        self._stop(active, ProcessStatus.VOLUME, f"Standard output exceeds {active.request.stdout_limit_bytes} bytes; {active.request.operation.lower()} result incomplete")
+                        continue
+                    if active.request.profile == CREDENTIAL_PROFILE:
+                        if self.credential_consumer is not None:
+                            self.credential_consumer(active.request.request_id, data)
+                    elif active.ssh_stdout_stream is not None:
+                        for unit in active.ssh_stdout_stream.feed(data):
+                            self.stdout_chunk.emit(self._public_request(active.request), (unit + "\n").encode("utf-8"))
+                    else:
+                        self.stdout_chunk.emit(self._public_request(active.request), data)
+                else:
+                    if active.stderr_truncated:
+                        continue
+                    if len(active.stderr) + len(data) > active.request.stderr_limit_bytes:
+                        if active.request.profile in {NETWORK_PROFILE, CREDENTIAL_PROFILE}:
+                            active.stderr_truncated = True
+                            safe_data = b"Trace incomplete: standard error storage limit exceeded; remaining output withheld.\n"
+                            active.stderr.extend(safe_data)
+                            self.stderr_chunk.emit(self._public_request(active.request), safe_data)
+                            continue
+                        self._stop(active, ProcessStatus.VOLUME, f"Standard error exceeds {active.request.stderr_limit_bytes} bytes; diagnostic incomplete")
+                        continue
+                    if active.credential_stream is not None:
+                        for piece in active.credential_stream.feed_pieces(data):
+                            safe_data = piece.encode("utf-8")
+                            active.stderr.extend(safe_data)
+                            self.stderr_chunk.emit(self._public_request(active.request), safe_data)
+                    else:
+                        active.stderr.extend(data)
+                        self.stderr_chunk.emit(active.request, data)
+            if not consumed:
+                if active.stdout_paused and active.status == ProcessStatus.RUNNING:
+                    return
+                if active.exited:
+                    self._complete(active)
+                return
+        self._schedule_drain(active)
+
+    def _stop(self, active: _RunningProcess, status: ProcessStatus, cause: str) -> None:
+        """Retain tracked writes and their last bytes until native descendant drainage is proven."""
+        if active.status != ProcessStatus.RUNNING:
+            return
+        active.status = status
+        active.cause = cause
+        active.deadline.stop()
+        active.inactivity.stop()
+        if active.request.wait_for_exit_on_stop and active.process.state() != QProcess.ProcessState.NotRunning:
+            # Killing Git alone can orphan hooks that keep writing. Retain the native parent
+            # and reservation until Git reaps its hooks and reports its actual exit.
+            self.stop_requested.emit(self._public_request(active.request), cause)
+            return
+        if active.group is not None:
+            self.stop_requested.emit(self._public_request(active.request), cause)
+            self._poll_group(active)
+            return
+        if active.process.state() != QProcess.ProcessState.NotRunning:
+            active.process.terminate()
+            active.kill_timer.start(PROCESS_TERMINATE_TIMEOUT_MS)
+        else:
+            active.exited = True
+            self._schedule_drain(active)
+
+    def _poll_group(self, active: _RunningProcess) -> None:
+        """Retry inconclusive native checks asynchronously without releasing the owner."""
+        if self.active_by_id.get(active.request.request_id) is not active:
+            return
+        try:
+            if active.status != ProcessStatus.RUNNING and not active.request.wait_for_exit_on_stop:
+                active.group.stop()
+            if active.exited and active.group.is_empty():
+                self._schedule_drain(active)
+                return
+        except OSError:
+            self._unknown_drainage(active)
+        active.group_timer.start(PROCESS_GROUP_POLL_MS)
+
+    def _unknown_drainage(self, active: _RunningProcess) -> None:
+        """Report uncertainty once while preserving the process slot and repository owner."""
+        if active.drainage_uncertain:
+            return
+        active.drainage_uncertain = True
+        cause = "Stopping: outcome unknown; descendant termination could not be confirmed"
+        active.cause = active.cause + "; " + cause if active.cause else cause
+        self.stop_requested.emit(self._public_request(active.request), cause)
+
+    def _error(self, active: _RunningProcess, error: QProcess.ProcessError) -> None:
+        if self.active_by_id.get(active.request.request_id) is not active:
+            return
+        if active.status == ProcessStatus.RUNNING:
+            active.cause = active.process.errorString()
+        if error == QProcess.ProcessError.FailedToStart:
+            active.status = ProcessStatus.START_FAILED
+            active.exited = True
+            self._schedule_drain(active)
+
+    def _exit(self, active: _RunningProcess, return_code: int, exit_status: QProcess.ExitStatus) -> None:
+        """Drain the supervisor's streams without treating its exit as descendant proof."""
+        if self.active_by_id.get(active.request.request_id) is not active:
+            return
+        active.return_code = return_code
+        active.exited = True
+        active.deadline.stop()
+        active.inactivity.stop()
+        active.kill_timer.stop()
+        if exit_status == QProcess.ExitStatus.CrashExit and not active.cause:
+            active.cause = active.process.errorString()
+        self._schedule_drain(active)
+
+    def _complete(self, active: _RunningProcess) -> None:
+        """Publish a final result only after draining and protecting credential output.
+
+        A relay that refused to start its command is recognised first: for a supervised request the command it could not
+        start is the supervisor, so no group was ever created and there is nothing to wait for before freeing the request.
+        """
+        relay_cause = relay_start_failure_cause(active.relayed, active.return_code, bytes(active.stderr)) if active.status == ProcessStatus.RUNNING else None
+        if relay_cause is not None:
+            # The refusal line becomes the cause, as for a program the system could not start; it is not the command's output.
+            active.status = ProcessStatus.START_FAILED
+            active.return_code = None
+            active.cause = relay_cause
+            active.stderr.clear()
+        if active.group is not None and active.status != ProcessStatus.START_FAILED:
+            try:
+                if not active.group.is_empty():
+                    self._unknown_drainage(active)
+                    active.group_timer.start(PROCESS_GROUP_POLL_MS)
+                    return
+                if active.group.launch_failed() and active.status == ProcessStatus.RUNNING:
+                    active.status = ProcessStatus.START_FAILED
+                    active.cause = bytes(active.stderr).decode("utf-8", "replace").strip() or "The supervised command could not be started"
+                active.return_code = active.group.result_return_code(active.return_code)
+            except OSError:
+                self._unknown_drainage(active)
+                active.group_timer.start(PROCESS_GROUP_POLL_MS)
+                return
+        if self.active_by_id.pop(active.request.request_id, None) is not active:
+            return
+        for timer in (active.deadline, active.inactivity, active.kill_timer, active.group_timer):
+            timer.stop()
+            timer.timeout.disconnect()
+        # Release callbacks before deferred destruction: each closure otherwise retains the
+        # process and its timers through a Python/Qt reference cycle.
+        active.process.readyReadStandardOutput.disconnect()
+        active.process.readyReadStandardError.disconnect()
+        active.process.finished.disconnect()
+        active.process.errorOccurred.disconnect()
+        if active.status == ProcessStatus.RUNNING:
+            active.status = ProcessStatus.SUCCESS if active.return_code == 0 and not active.cause else ProcessStatus.FAILED
+            if active.status == ProcessStatus.FAILED and not active.cause:
+                active.cause = bytes(active.stderr).decode("utf-8", "replace").strip() or EXIT_CODE_CAUSE_TEMPLATE.format(return_code=active.return_code)
+        if active.credential_stream is not None and not active.stderr_truncated:
+            for piece in active.credential_stream.feed_pieces(b"", final=True):
+                safe_data = piece.encode("utf-8")
+                active.stderr.extend(safe_data)
+                self.stderr_chunk.emit(self._public_request(active.request), safe_data)
+        stderr = bytes(active.stderr)
+        cause = self._close_editor(active.request, active.cause)
+        if active.credential_stream is not None:
+            cause = active.credential_stream.filter.redact(cause)
+        if active.ssh_stdout_stream is not None:
+            for unit in active.ssh_stdout_stream.feed(b"", final=True):
+                self.stdout_chunk.emit(self._public_request(active.request), (unit + "\n").encode("utf-8"))
+        if active.group is not None:
+            try:
+                active.group.close()
+            except OSError:
+                # Drainage is already proven; an antivirus or file permission race during
+                # private-marker cleanup must not lose the terminal repository result.
+                cleanup_cause = "Process finished, but private supervisor files could not be removed"
+                cause = cause + "; " + cleanup_cause if cause else cleanup_cause
+        self.finished.emit(self._timed_result(active.request, active.status, active.return_code, cause, stderr, active.received_ms, active.launched_ms))
+        active.process.deleteLater()
+        self._pump()
+        self._notify_idle()
+
+    def _public_request(self, request: ProcessRequest) -> ProcessRequest:
+        """Keep the credential protocol input out of publicly emitted request metadata."""
+        if request.before_start is not None:
+            request = replace(request, before_start=None)
+        if request.editor_context is not None:
+            environment_by_name = dict(request.environment_by_name)
+            for name in EDITOR_ENVIRONMENT_NAME_SET:
+                environment_by_name.pop(name, None)
+            request = replace(request, editor_context=None, environment_by_name=environment_by_name)
+        if any(name in request.environment_by_name for name in SSH_ENVIRONMENT_NAMES):
+            environment_by_name = dict(request.environment_by_name)
+            for name in SSH_ENVIRONMENT_NAMES:
+                environment_by_name.pop(name, None)
+            request = replace(request, environment_by_name=environment_by_name)
+        if request.profile == CREDENTIAL_PROFILE:
+            arguments: list[str] = []
+            text_filter = SensitiveTextFilter(self._credential_value_by_name(request))
+            masked_arguments = mask_sensitive_arguments(request.arguments).arguments
+            for argument in masked_arguments:
+                arguments.append(argument if argument == MASKED_VALUE else text_filter.redact(argument))
+            return replace(request, stdin=None, arguments=arguments)
+        return request
+
+    def _credential_value_by_name(self, request: ProcessRequest) -> dict[str, str]:
+        """Hide protocol and argument secrets even if a helper repeats them in its trace."""
+        value_by_name = dict(os.environ)
+        # Only the secrets: a setting login stays readable in the helper's trace, like the URLs it is part of.
+        secret_values = mask_sensitive_arguments(request.arguments).secret_values
+        # The name, not the number, is what matters: the text filter protects every value stored under a secret-looking name.
+        for position, hidden_value in enumerate(secret_values):
+            value_by_name[f"credential_argument_{position}"] = hidden_value
+        if request.stdin:
+            for line in request.stdin.decode("utf-8", "replace").splitlines():
+                name, separator, value = line.partition("=")
+                if separator and SENSITIVE_NAME_PATTERN.search(name):
+                    value_by_name[name] = value
+        return value_by_name
+
+    def _notify_idle(self) -> None:
+        if not self.active_by_id and not self.pending_requests:
+            self.idle.emit()