gitpane 1.0.0__py3-none-any.whl

gitpane/tool/system_tool.py

@@ -0,0 +1,816 @@
+"""Start independent tools (terminal, text editor, file manager) in explicit directories."""
+
+from __future__ import annotations
+
+import os
+import queue
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol
+
+from PySide6.QtCore import QObject, QTimer, QUrl, Signal
+from PySide6.QtGui import QDesktopServices
+
+from gitpane.config import (
+    EDITOR_HIDDEN_ENVIRONMENT_PREFIXES,
+    FILE_EXPORT_ACTIVE_LIMIT,
+    FILE_EXPORT_BUFFER_CHUNKS,
+    GIT_READ_TIMEOUT_MS,
+    MACOS_OPEN_FILENAME,
+    MACOS_PLATFORM,
+    MILLISECONDS_PER_SECOND,
+    PROCESS_CHUNK_BYTES,
+    TOOL_RESULT_POLL_MS,
+    TOOL_START_ACTIVE_LIMIT,
+    TOOL_START_TIMEOUT_MS,
+    WINDOWS_PLATFORM,
+)
+from gitpane.system.path_identity import canonical_path
+from gitpane.system.startup_activation import NO_STARTUP_ACTIVATION, StartupActivation, no_startup_activation
+from gitpane.tool.editor_recipe import EditorRecipe, build_editor_arguments, file_open_options
+from gitpane.tool.file_reveal import reveal_file, selection_helper_available
+from gitpane.tool.terminal_recipe import (
+    RECIPE_BY_ID,
+    SH_EXECUTABLE_BASENAME,
+    TerminalLaunch,
+    bundle_recipe_program,
+    executable_available,
+    git_bash_candidate_filenames,
+    inside_system_root,
+    terminal_arguments,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.tool.terminal_recipe import TerminalDescriptor, TerminalRecipe
+
+
+@dataclass(frozen=True)
+class OperationResult:
+    """Report a completed file operation without including historical content."""
+
+    request_id: object
+    destination_filename: str
+    cause: str = ""
+
+
+def _contained(filename: str, directory: str) -> bool:
+    try:
+        return os.path.commonpath((filename, directory)) == directory
+    except ValueError:
+        return False
+
+
+def _protect_git_path(filename: str, context: RepositoryContext) -> str:
+    """Reject Git metadata even through a linked worktree or a directory symlink."""
+    resolved_filename = canonical_path(filename)
+    for directory in (context.git_dir, context.common_git_dir):
+        if _contained(resolved_filename, canonical_path(directory)):
+            raise ValueError("Git internal files cannot be used for this operation.")
+    for component in resolved_filename.replace("\\", "/").split("/"):
+        if component.casefold() == ".git":
+            raise ValueError("Git internal files cannot be used for this operation.")
+    return os.path.realpath(filename)
+
+
+def worktree_filename(context: RepositoryContext, path: bytes) -> str:
+    """Build the absolute worktree filename even for a historical file that no longer exists."""
+    if context.is_bare or context.worktree_dir is None:
+        raise ValueError("This bare repository has no working tree folder.")
+    parts = path.split(b"/")
+    for part in parts:
+        if not part or part in (b".", b"..") or b"\0" in part or (os.name == "nt" and (b"\\" in part or b":" in part)):
+            raise ValueError("The selected Git path is not a safe local file path.")
+    return os.path.join(os.path.abspath(context.worktree_dir), *map(os.fsdecode, parts))
+
+
+def file_location(context: RepositoryContext, path: bytes, *, allow_missing: bool = False) -> str:
+    """Resolve a file's folder, optionally finding an existing ancestor for a deleted working path."""
+    filename = worktree_filename(context, path)
+    worktree_dir = os.path.realpath(context.worktree_dir)
+    resolved_filename = _protect_git_path(filename, context)
+    if not _contained(os.path.normcase(resolved_filename), os.path.normcase(worktree_dir)):
+        raise ValueError("The selected file resolves outside this working tree.")
+    if not allow_missing and not os.path.exists(filename):
+        raise FileNotFoundError("This historical file is absent from the working tree. No file was restored.")
+    directory = os.path.dirname(resolved_filename)
+    while not os.path.isdir(directory):
+        if os.path.lexists(directory) or os.path.normcase(directory) == os.path.normcase(worktree_dir):
+            raise FileNotFoundError("The working tree folder is unavailable.")
+        directory = os.path.dirname(directory)
+    return directory
+
+
+@dataclass
+class FileExport:
+    """Share bounded chunks and cancellation with a disk worker that never touches Qt."""
+
+    request_id: object
+    context: RepositoryContext
+    destination_filename: str
+    overwrite_confirmed: bool
+    cancel_read: Callable[[], None]
+    chunks: queue.Queue[bytes | int] = field(default_factory=lambda: queue.Queue(FILE_EXPORT_BUFFER_CHUNKS))
+    cancelled: threading.Event = field(default_factory=threading.Event)
+    publish_lock: threading.Lock = field(default_factory=threading.Lock)
+    cause: str = ""
+    deadline: float = field(default_factory=lambda: time.monotonic() + GIT_READ_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+
+
+def _write_export(operation: FileExport, completion_queue: queue.SimpleQueue[OperationResult]) -> None:
+    """Publish complete bytes atomically and remove only this operation's temporary file."""
+    temporary_filename = ""
+    cause = ""
+    try:
+        destination_filename = os.path.abspath(operation.destination_filename)
+        resolved_filename = _protect_git_path(destination_filename, operation.context)
+        if os.path.islink(destination_filename):
+            raise ValueError("Choose a regular destination file instead of a symbolic link.")
+        original_stat = os.stat(destination_filename) if os.path.exists(destination_filename) else None
+        if original_stat is not None and not operation.overwrite_confirmed:
+            raise FileExistsError("Replacing this file requires explicit overwrite confirmation.")
+        if operation.cancelled.is_set():
+            raise OSError(operation.cause)
+        descriptor, temporary_filename = tempfile.mkstemp(prefix=".gitpane-export-", dir=os.path.dirname(resolved_filename))
+        with os.fdopen(descriptor, "wb") as stream:
+            written_size = 0
+            while True:
+                if operation.cancelled.is_set():
+                    raise OSError(operation.cause)
+                if time.monotonic() >= operation.deadline:
+                    raise TimeoutError("Saving the historical file timed out.")
+                try:
+                    chunk = operation.chunks.get(timeout=TOOL_RESULT_POLL_MS / MILLISECONDS_PER_SECOND)
+                except queue.Empty:
+                    continue
+                if isinstance(chunk, int):
+                    if written_size != chunk:
+                        raise OSError("The historical file stream ended with an incorrect byte count.")
+                    break
+                written_size += stream.write(chunk)
+            stream.flush()
+            os.fsync(stream.fileno())
+        with operation.publish_lock:
+            if operation.cancelled.is_set():
+                raise OSError(operation.cause)
+            if _protect_git_path(destination_filename, operation.context) != resolved_filename or os.path.islink(destination_filename):
+                raise OSError("The destination changed while the file was being saved.")
+            current_stat = os.stat(destination_filename) if os.path.exists(destination_filename) else None
+            if current_stat != original_stat:
+                raise OSError("The destination changed while the file was being saved. Choose it again.")
+            if original_stat is None:
+                # Linking publishes a complete file without overwriting a destination created after confirmation.
+                os.link(temporary_filename, resolved_filename)
+                os.unlink(temporary_filename)
+            else:
+                os.replace(temporary_filename, resolved_filename)
+            temporary_filename = ""
+    except (OSError, ValueError) as error:
+        cause = str(error)
+    finally:
+        if temporary_filename:
+            try:
+                os.unlink(temporary_filename)
+            except OSError as error:
+                cause = f"{cause}; temporary file cleanup failed: {error}"
+        completion_queue.put(OperationResult(operation.request_id, operation.destination_filename, cause))
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """Report startup acceptance separately from the external application's lifetime."""
+
+    request_id: object
+    label: str
+    repository_dir: str
+    program_filename: str
+    arguments: tuple[str, ...]
+    cause: str = ""
+    timed_out: bool = False
+
+
+def _run_until_answer(command_arguments: list[str], working_dir: str, run: Callable[..., subprocess.CompletedProcess[bytes]], **option_by_name: object) -> None:
+    """Run a command that answers as soon as it has handed its work over, and raise its refusal with what it wrote.
+
+    It is waited for, bounded by the tool startup timeout; the service calls this on its worker thread, never on the
+    window's.
+    """
+    completed = run(command_arguments, stdin=subprocess.DEVNULL, capture_output=True,
+                    timeout=TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False, cwd=working_dir, **option_by_name)
+    if completed.returncode != 0:
+        message = completed.stderr.decode("utf-8", errors="replace").strip()
+        raise OSError(message or f"{os.path.basename(command_arguments[0])} exited with code {completed.returncode}")
+
+
+def _run_open_command(arguments: list[str], working_dir: str, run: Callable[..., subprocess.CompletedProcess[bytes]]) -> None:
+    """Ask LaunchServices, through macOS's open command, to open something, and raise its refusal with what open wrote.
+
+    open answers as soon as the application has been asked, so waiting for it never waits for the application.
+    """
+    _run_until_answer([MACOS_OPEN_FILENAME, *arguments], working_dir, run)
+
+
+def _start_detached_terminal(program_filename: str, arguments: list[str], recipe: TerminalRecipe, repository_dir: str, platform: str,
+                             popen: Callable[..., subprocess.Popen], activation: StartupActivation) -> None:
+    """Start a terminal program that outlives GitPane, in the repository folder, without waiting for it.
+
+    Its environment is GitPane's without any inherited startup value, plus the one read when the user clicked: Qt
+    removes its own activation token from the C environment only, and never an inherited X11 startup identifier.
+    """
+    option_by_name: dict[str, object] = {"cwd": repository_dir, "shell": False, "close_fds": True, "env": activation.environment(os.environ)}
+    if platform == WINDOWS_PLATFORM:
+        # Only the shell requested by the user receives a visible console; no PowerShell helper is launched.
+        option_by_name["creationflags"] = subprocess.CREATE_NEW_CONSOLE if recipe.new_console else subprocess.DETACHED_PROCESS
+    else:
+        option_by_name.update(start_new_session=True, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    process = popen([program_filename, *arguments], **option_by_name)
+    # Popen never waits for terminal exit. Its own nonblocking cleanup reaps exited children on later starts.
+    process.poll()
+
+
+def launch_terminal(descriptor: TerminalDescriptor, repository_dir: str, platform: str = sys.platform,
+                    popen: Callable[..., subprocess.Popen] = subprocess.Popen,
+                    run: Callable[..., subprocess.CompletedProcess[bytes]] = subprocess.run, *, activation: StartupActivation = NO_STARTUP_ACTIVATION) -> None:
+    """Start an independent terminal with captured cwd and no constructed shell command.
+
+    The recipe's launch form decides how: its own program, or a program inside a macOS application, started detached;
+    or macOS's open command (run), whose refusal is raised with its message. A terminal whose program or application
+    has gone is refused before anything starts, instead of selecting another one. A terminal started directly receives
+    the startup value read when the user clicked, so its window may come to the front; macOS's open is asked as before.
+    """
+    if not os.path.isdir(repository_dir):
+        raise FileNotFoundError(f"Folder unavailable: {repository_dir}")
+    arguments = terminal_arguments(descriptor, repository_dir)
+    recipe = RECIPE_BY_ID[descriptor.recipe_id]
+    program_filename = available_terminal_program(descriptor)
+    if not program_filename:
+        raise FileNotFoundError(f"Terminal unavailable : {descriptor.label} — {descriptor.program_filename}")
+    if recipe.launch == TerminalLaunch.OPEN:
+        _run_open_command(arguments, repository_dir, run)
+        return
+    _start_detached_terminal(program_filename, arguments, recipe, repository_dir, platform, popen, activation)
+
+
+def available_terminal_program(descriptor: TerminalDescriptor) -> str:
+    """Return what a terminal starts, its program or the macOS application folder open is asked for, or an empty text when it has gone.
+
+    These are the cheap checks that refuse a terminal before anything starts, so the service also runs them on the
+    window's thread before it asks for the click's startup value.
+    """
+    if not descriptor.available:
+        return ""
+    recipe = RECIPE_BY_ID[descriptor.recipe_id]
+    if recipe.launch == TerminalLaunch.OPEN:
+        return descriptor.program_filename if os.path.isdir(descriptor.program_filename) else ""
+    program_filename = descriptor.program_filename
+    if recipe.launch == TerminalLaunch.BUNDLE_PROGRAM:
+        program_filename = bundle_recipe_program(recipe, descriptor.program_filename)
+    return program_filename if executable_available(program_filename) else ""
+
+
+class TextEditorCommand(Protocol):
+    """Build the full start command of the editor that opens a working copy file.
+
+    Two real forms exist: an editor recipe from Settings or detection, started without a shell, and the editor line
+    Git itself would use, started the way Git starts it. Both answer the same question, so the launcher and the
+    unavailable reason never need to tell them apart.
+    """
+
+    def arguments(self, filename: str) -> list[str]:
+        """Return the program followed by its arguments, the file as a single argument; raise ValueError with a readable cause when the editor cannot start."""
+        ...
+
+    def answers_at_once(self) -> bool:
+        """Tell whether the command hands the file over and ends at once with the system's answer, so its refusal can be reported.
+
+        Any other command is the editor itself, or a command that may wait for it, and is started detached without waiting.
+        """
+        ...
+
+
+@dataclass(frozen=True)
+class RecipeTextEditor:
+    """Start an editor recipe from Settings, or a detected one, as a plain argument list without any shell."""
+
+    recipe: EditorRecipe
+
+    def arguments(self, filename: str) -> list[str]:
+        """Check the recipe still names a usable program, then insert the absolute filename as one literal argument."""
+        self.recipe.validate()
+        return [self.recipe.program_filename, *build_editor_arguments(self.recipe.argument_template, filename)]
+
+    def answers_at_once(self) -> bool:
+        """Answer no: a recipe names the editor, which may wait until the file is closed."""
+        return False
+
+
+# The open option that picks the default text editor of macOS, the one LaunchServices chooses (TextEdit unless the user changed it).
+MACOS_DEFAULT_TEXT_EDITOR_OPEN_OPTIONS = ("-t",)
+
+
+@dataclass(frozen=True)
+class MacOpenTextEditor:
+    """Open a file through macOS's open command, in the default text editor or in the application its options name.
+
+    open hands the file to that editor and returns at once, so nothing waits for the editor; no permission is asked.
+    """
+
+    open_options: tuple[str, ...] = MACOS_DEFAULT_TEXT_EDITOR_OPEN_OPTIONS
+
+    def arguments(self, filename: str) -> list[str]:
+        """Return open and its options, followed by the file name as one argument, exactly as given."""
+        return [MACOS_OPEN_FILENAME, *self.open_options, filename]
+
+    def answers_at_once(self) -> bool:
+        """Answer yes: open ends as soon as LaunchServices has handed the file over, or refused it."""
+        return True
+
+
+# The editor a platform opens when neither Settings nor detection gives one; a platform missing here greys the entry.
+DEFAULT_TEXT_EDITOR_BY_PLATFORM: dict[str, TextEditorCommand] = {MACOS_PLATFORM: MacOpenTextEditor()}
+# The shell through which Git itself starts an editor line on POSIX systems.
+POSIX_SHELL_FILENAME = "/bin/sh"
+GIT_EDITOR_ENVIRONMENT_NAME = "GIT_EDITOR"
+VISUAL_ENVIRONMENT_NAME = "VISUAL"
+EDITOR_ENVIRONMENT_NAME = "EDITOR"
+TERM_ENVIRONMENT_NAME = "TERM"
+DUMB_TERMINAL_NAME = "dumb"
+# The editor value Git reads as "no editor at all".
+GIT_NO_EDITOR_VALUE = ":"
+FILE_NOT_IN_WORKTREE_REASON = "The file does not exist in the working tree."
+NOT_A_FILE_REASON = "A folder cannot be opened in a text editor."
+NO_TEXT_EDITOR_REASON = "No text editor set in Settings."
+GIT_SHELL_NOT_FOUND_REASON = "The shell of Git was not found, so the editor set for Git cannot be started."
+GIT_EDITOR_NULL_CHARACTER_REASON = "The editor set for Git or the file name contains a null character."
+TEXT_EDITOR_LABEL = "text editor"
+
+
+@dataclass(frozen=True)
+class GitTextEditor:
+    """Start the editor line set for Git (GIT_EDITOR, core.editor, VISUAL or EDITOR) the way Git starts it.
+
+    That value is a shell line the user wrote for Git, which Git runs through a shell, so it may hold options, quotes
+    or a variable. It is started the same way here: the line goes into the shell script, the file name only arrives
+    as a positional parameter, so a file name coming from a commit is never read as shell code. A Settings recipe is
+    still started without any shell.
+    """
+
+    command_line: str
+    shell_filename: str
+
+    def arguments(self, filename: str) -> list[str]:
+        """Return the shell, the script `<line> "$@"`, the line as the script name, then the absolute file name."""
+        if not self.shell_filename:
+            raise ValueError(GIT_SHELL_NOT_FOUND_REASON)
+        if "\0" in self.command_line or "\0" in filename:
+            raise ValueError(GIT_EDITOR_NULL_CHARACTER_REASON)
+        return [self.shell_filename, "-c", self.command_line + ' "$@"', self.command_line, os.path.abspath(filename)]
+
+    def answers_at_once(self) -> bool:
+        """Answer no: the line set for Git starts the editor itself, which may wait until the file is closed."""
+        return False
+
+
+def git_editor_line(environment_by_name: Mapping[str, str], core_editor: str) -> str:
+    """Return the editor line Git would start, in Git's order, without Git's compiled-in default.
+
+    That default is not a choice of the user and usually names a terminal editor, which shows nothing without a
+    terminal, so nothing set gives an empty line. VISUAL only counts with a terminal that is not dumb, as in Git. The
+    first value that is not blank decides: the colon Git reads as "no editor" ends the search with no editor, as in
+    Git; an empty or blank value is skipped, since Git would fail to start it. No process is started: asking `git var`
+    would answer the compiled-in default too.
+    """
+    terminal_name = environment_by_name.get(TERM_ENVIRONMENT_NAME, "")
+    candidates = [environment_by_name.get(GIT_EDITOR_ENVIRONMENT_NAME, ""), core_editor]
+    if terminal_name and terminal_name != DUMB_TERMINAL_NAME:
+        candidates.append(environment_by_name.get(VISUAL_ENVIRONMENT_NAME, ""))
+    candidates.append(environment_by_name.get(EDITOR_ENVIRONMENT_NAME, ""))
+    for candidate in candidates:
+        line = candidate.strip()
+        if not line:
+            continue
+        if line == GIT_NO_EDITOR_VALUE:
+            return ""
+        return line
+    return ""
+
+
+def uses_git_editor(platform: str = sys.platform) -> bool:
+    """Tell whether Show in text editor may start the editor set for Git on this platform.
+
+    On Windows that editor is a graphical program chosen in the Git for Windows installer, so it opens a window. Elsewhere
+    it is often a terminal editor (vi, nano) which, started without a terminal, shows nothing and reports no error.
+    """
+    return platform == WINDOWS_PLATFORM
+
+
+def git_shell_filename(platform: str = sys.platform, git_filename: str = "", git_utility_dir: str = "", which: Callable[[str], str | None] = shutil.which,
+                       available: Callable[[str], bool] = executable_available, environment_by_name: Mapping[str, str] | None = None) -> str:
+    """Name the shell that starts the editor line set for Git: /bin/sh on POSIX, the sh.exe of Git for Windows otherwise.
+
+    On Windows the sh.exe is searched like Git Bash, starting from the Git GitPane runs; nothing found gives an empty
+    name, which greys the entry with its reason. Only files are looked at.
+    """
+    if platform != WINDOWS_PLATFORM:
+        return POSIX_SHELL_FILENAME
+    environment_by_name = os.environ if environment_by_name is None else environment_by_name
+    for candidate_filename in git_bash_candidate_filenames(SH_EXECUTABLE_BASENAME, git_filename, git_utility_dir, which, environment_by_name):
+        if inside_system_root(candidate_filename, environment_by_name):
+            continue
+        if available(candidate_filename):
+            return os.path.abspath(candidate_filename)
+    return ""
+
+
+def text_editor_command(editor_recipe: EditorRecipe, git_editor: str, shell_filename: Callable[[], str], *, saved: bool, platform: str = sys.platform) -> TextEditorCommand | None:
+    """Choose the editor that opens a working copy file, with one rule per platform.
+
+    The recipe is the one Settings shows: the saved choice (``saved``), even when its program has gone, so its own reason
+    is shown instead of silently opening another editor; otherwise the detected editor, which is not saved.
+
+    On Windows the saved editor comes first, then the editor line set for Git, started by the sh.exe of Git for Windows,
+    then the detected editor (Notepad): the editor the user chose for Git in its installer keeps opening. Without that
+    sh.exe the detected editor opens; with nothing detected either, the Git line is kept so the entry is greyed with the
+    reason that the shell is missing. Searching the shell only looks at files.
+
+    Elsewhere an editor set for Git is often a terminal editor (vi, nano) which, started without a terminal, shows nothing
+    and reports no error. So only the saved or detected editor opens there; the Git line and the shell are never looked
+    at. With neither, macOS opens its default text editor (open -t), so the entry is never greyed for lack of an editor,
+    while Linux greys the entry with its reason. A macOS preset whose command only waits for the rebase, such as
+    TextEdit's separate waiting copy or the new waiting window of VS Code, Sublime Text and Zed, opens the file with
+    its plain open options instead, so it goes to the editor's window already open.
+    """
+    if not uses_git_editor(platform):
+        if editor_recipe.program_filename:
+            open_options = file_open_options(editor_recipe)
+            if open_options:
+                return MacOpenTextEditor(open_options)
+            return RecipeTextEditor(editor_recipe)
+        return DEFAULT_TEXT_EDITOR_BY_PLATFORM.get(platform)
+    if saved and editor_recipe.program_filename:
+        return RecipeTextEditor(editor_recipe)
+    if git_editor:
+        git_shell = shell_filename()
+        if git_shell:
+            return GitTextEditor(git_editor, git_shell)
+        if editor_recipe.program_filename:
+            return RecipeTextEditor(editor_recipe)
+        return GitTextEditor(git_editor, "")
+    if editor_recipe.program_filename:
+        return RecipeTextEditor(editor_recipe)
+    return None
+
+
+def text_editor_unavailable_reason(context: RepositoryContext, path: bytes, command: TextEditorCommand | None) -> str:
+    """Tell why the working copy of a Git path cannot be opened in a text editor, or answer an empty reason.
+
+    The reason greys the menu entry, so it only looks at the disk and the chosen command and never starts a process.
+    """
+    try:
+        file_location(context, path, allow_missing=True)
+        filename = worktree_filename(context, path)
+    except (OSError, ValueError) as error:
+        return str(error)
+    if os.path.isdir(filename):
+        return NOT_A_FILE_REASON
+    if not os.path.isfile(filename):
+        return FILE_NOT_IN_WORKTREE_REASON
+    if command is None:
+        return NO_TEXT_EDITOR_REASON
+    try:
+        command.arguments(filename)
+    except ValueError as error:
+        return str(error)
+    return ""
+
+
+def editor_environment() -> dict[str, str]:
+    """Copy the environment without GitPane's own and trace variables, which an editor started by GitPane must not inherit."""
+    environment_by_name = {}
+    for name, value in os.environ.items():
+        if name.upper().startswith(EDITOR_HIDDEN_ENVIRONMENT_PREFIXES):
+            continue
+        environment_by_name[name] = value
+    return environment_by_name
+
+
+def launch_text_editor(command: TextEditorCommand, filename: str, platform: str = sys.platform,
+                       popen: Callable[..., subprocess.Popen] = subprocess.Popen,
+                       run: Callable[..., subprocess.CompletedProcess[bytes]] = subprocess.run, *, activation: StartupActivation = NO_STARTUP_ACTIVATION) -> None:
+    """Start the chosen editor on a working copy file without ever waiting for it.
+
+    An editor set to wait until its window closes (`--wait`) would otherwise keep GitPane blocked for as long as the
+    file stays open. A command that only hands the file over, such as macOS's open, ends at once with the system's
+    answer: it is run until that answer (run), so a refusal is reported with its message, as for a terminal. The
+    editor receives the startup value read when the user clicked (an X11 startup identifier or a Wayland activation
+    token), so its window may come to the front, and never one GitPane inherited.
+    """
+    arguments = command.arguments(filename)
+    working_dir = os.path.dirname(os.path.abspath(filename))
+    if command.answers_at_once():
+        _run_until_answer(arguments, working_dir, run, env=activation.environment(editor_environment()))
+        return
+    option_by_name: dict[str, object] = {"cwd": working_dir, "shell": False, "close_fds": True, "env": activation.environment(editor_environment())}
+    if platform == WINDOWS_PLATFORM:
+        option_by_name["creationflags"] = subprocess.DETACHED_PROCESS
+    else:
+        option_by_name.update(start_new_session=True, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    process = popen(arguments, **option_by_name)
+    # Popen never waits for the editor to exit. Its own nonblocking cleanup reaps exited children on later starts.
+    process.poll()
+
+
+class TerminalStart(Protocol):
+    """Start a terminal in a folder, handing it the startup value read when the user clicked."""
+
+    def __call__(self, descriptor: TerminalDescriptor, repository_dir: str, *, activation: StartupActivation) -> None:
+        """Start the terminal without waiting for it, or raise why it could not start."""
+
+
+class TextEditorStart(Protocol):
+    """Start an editor on a working copy file, handing it the startup value read when the user clicked."""
+
+    def __call__(self, command: TextEditorCommand, filename: str, *, activation: StartupActivation) -> None:
+        """Start the editor without waiting for it, or raise why it could not start."""
+
+
+def open_explorer(repository_dir: str, open_url: Callable[[QUrl], bool] = QDesktopServices.openUrl) -> None:
+    """Ask the desktop to open the exact local directory and report startup refusal."""
+    if not os.path.isdir(repository_dir):
+        raise FileNotFoundError(f"Folder unavailable: {repository_dir}")
+    if not open_url(QUrl.fromLocalFile(repository_dir)):
+        raise OSError("The system refused to open the folder in the file explorer.")
+
+
+@dataclass
+class PendingLaunch:
+    """Retain capacity after timeout until an uninterruptible OS startup actually returns."""
+
+    result: ToolResult
+    deadline: float
+    reported: bool = False
+
+
+def _launch_worker(start: Callable[[], None], result: ToolResult, completion_queue: queue.SimpleQueue[ToolResult]) -> None:
+    """Send plain data back from a daemon worker without touching any Qt object."""
+    cause = ""
+    try:
+        start()
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
+        cause = str(error)
+    completion_queue.put(ToolResult(result.request_id, result.label, result.repository_dir, result.program_filename, result.arguments, cause))
+
+
+def _reveal_worker(reveal: Callable[[str, str], bool], filename: str, startup_id: str, result: ToolResult, completion_queue: queue.SimpleQueue[tuple[ToolResult, bool]]) -> None:
+    """Request native selection off the GUI thread and leave folder fallback to Qt.
+
+    A selection helper that does not answer in time counts as no selection, so the folder still opens; any other
+    failure is reported with its cause.
+    """
+    cause = ""
+    selected = False
+    try:
+        selected = reveal(filename, startup_id)
+    except subprocess.TimeoutExpired:
+        selected = False
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
+        cause = str(error)
+    completion_queue.put((ToolResult(result.request_id, result.label, result.repository_dir, result.program_filename, result.arguments, cause), selected))
+
+
+class SystemToolService(QObject):
+    """Bound startup work while keeping external terminals independent of application shutdown."""
+
+    started = Signal(object, str)
+    finished = Signal(object)
+    export_finished = Signal(object)
+    export_idle = Signal()
+
+    def __init__(self, launch: TerminalStart = launch_terminal,
+                 explorer: Callable[[str], None] = open_explorer, parent: QObject | None = None,
+                 export_writer: Callable[[FileExport, queue.SimpleQueue[OperationResult]], None] = _write_export,
+                 reveal: Callable[[str, str], bool] = reveal_file,
+                 text_editor_launch: TextEditorStart = launch_text_editor,
+                 activation: Callable[[], StartupActivation] = no_startup_activation,
+                 reveal_available: Callable[[], bool] = selection_helper_available) -> None:
+        """Inject OS calls and return worker results through a GUI-owned polling timer.
+
+        The activation source tells the desktop that the user asked for the program GitPane starts (an X11 startup
+        identifier or a Wayland activation token), so its window may come to the front; it is read on the GUI thread
+        when the user clicks, before the worker starts, and never otherwise. The application injects the desktop's
+        source, which lives in the interface layer; without it, no value is sent and the desktop decides alone. It is
+        not read for a launch the cheap checks already know will not use it (a terminal that has gone, no selection
+        helper for Show in folder): under Wayland a token nobody uses shows a busy pointer for up to 15 s.
+        """
+        super().__init__(parent)
+        self.launch = launch
+        self.text_editor_launch = text_editor_launch
+        self.explorer = explorer
+        self.reveal = reveal
+        self.reveal_available = reveal_available
+        self.activation = activation
+        self.export_writer = export_writer
+        self.export_by_id: dict[object, FileExport] = {}
+        self.export_completion_queue: queue.SimpleQueue[OperationResult] = queue.SimpleQueue()
+        self.pending_by_id: dict[object, PendingLaunch] = {}
+        self.completion_queue: queue.SimpleQueue[ToolResult] = queue.SimpleQueue()
+        self.reveal_completion_queue: queue.SimpleQueue[tuple[ToolResult, bool]] = queue.SimpleQueue()
+        self.closed = False
+        self.timer = QTimer(self)
+        self.timer.setInterval(TOOL_RESULT_POLL_MS)
+        self.timer.timeout.connect(self._poll)
+
+    def show_file_location(self, request_id: object, context: RepositoryContext, path: bytes, *, allow_missing: bool = False) -> None:
+        """Select a contained working file, falling back to its folder when selection is unavailable."""
+        if self.closed or request_id in self.pending_by_id:
+            return
+        try:
+            directory = file_location(context, path, allow_missing=allow_missing)
+            filename = worktree_filename(context, path)
+        except (OSError, ValueError) as error:
+            self.finished.emit(ToolResult(request_id, "file location", context.repository_dir, "", (), str(error)))
+            return
+        if not os.path.lexists(filename):
+            self.open_explorer(request_id, directory)
+            return
+        result = ToolResult(request_id, "file explorer", directory, "", ())
+        if len(self.pending_by_id) >= TOOL_START_ACTIVE_LIMIT:
+            self.finished.emit(ToolResult(request_id, result.label, directory, "", (), "Too many tools are starting. Try again after they finish."))
+            return
+        self.pending_by_id[request_id] = PendingLaunch(result, time.monotonic() + TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        self.started.emit(request_id, result.label)
+        # Read now, on the GUI thread, so the value is the one of this request and Qt windows are only touched here.
+        activation = self.activation() if self.reveal_available() else NO_STARTUP_ACTIVATION
+        threading.Thread(target=_reveal_worker, args=(self.reveal, filename, activation.value, result, self.reveal_completion_queue), daemon=True).start()
+        self.timer.start()
+
+    def save_historical_file(self, request_id: object, context: RepositoryContext, destination_filename: str,
+                             read: Callable[[Callable[[bytes], None], Callable[[int], None]], None], cancel_read: Callable[[], None], overwrite_confirmed: bool = False) -> None:
+        """Stream an immutable Git read into a bounded, cancellable atomic disk writer."""
+        if self.closed or len(self.export_by_id) >= FILE_EXPORT_ACTIVE_LIMIT:
+            self.export_finished.emit(OperationResult(request_id, destination_filename, "Another file export is still running. Try again after it finishes."))
+            return
+        operation = FileExport(request_id, context, destination_filename, overwrite_confirmed, cancel_read)
+        self.export_by_id[request_id] = operation
+        threading.Thread(target=self.export_writer, args=(operation, self.export_completion_queue), daemon=True).start()
+        self.timer.start()
+
+        def consume(chunk: bytes) -> None:
+            """Keep UI delivery nonblocking even when the destination disk stalls."""
+            if operation.cancelled.is_set():
+                return
+            try:
+                for offset in range(0, len(chunk), PROCESS_CHUNK_BYTES):
+                    operation.chunks.put_nowait(chunk[offset:offset + PROCESS_CHUNK_BYTES])
+            except queue.Full:
+                self.fail_export(request_id, "The destination cannot keep up with the file stream. Saving was cancelled.")
+
+        def completed(size: int) -> None:
+            """Allow publication only after Git confirms the complete object framing."""
+            try:
+                operation.chunks.put_nowait(size)
+            except queue.Full:
+                self.fail_export(request_id, "The destination cannot keep up with the file stream. Saving was cancelled.")
+
+        try:
+            read(consume, completed)
+        except (OSError, ValueError, RuntimeError) as error:
+            self.fail_export(request_id, str(error))
+
+    def fail_export(self, request_id: object, cause: str) -> None:
+        """Stop a failed Git read and let the disk worker remove its temporary file."""
+        operation = self.export_by_id.get(request_id)
+        if operation is None:
+            return
+        with operation.publish_lock:
+            operation.cause = cause
+            operation.cancelled.set()
+        operation.cancel_read()
+
+    def cancel_export(self, request_id: object) -> None:
+        """Cancel an unfinished export without touching an existing destination."""
+        self.fail_export(request_id, "Saving was cancelled.")
+
+    def launch_terminal(self, request_id: object, descriptor: TerminalDescriptor, repository_dir: str) -> bool:
+        """Capture a request once and schedule startup without blocking the Qt event loop."""
+        if self.closed or request_id in self.pending_by_id:
+            return False
+        result = ToolResult(request_id, descriptor.label, repository_dir, descriptor.program_filename, tuple(terminal_arguments(descriptor, repository_dir)))
+        if len(self.pending_by_id) >= TOOL_START_ACTIVE_LIMIT:
+            self.finished.emit(ToolResult(request_id, result.label, repository_dir, result.program_filename, result.arguments, "Too many tools are starting. Try again after they finish."))
+            return False
+        self.pending_by_id[request_id] = PendingLaunch(result, time.monotonic() + TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        self.started.emit(request_id, descriptor.label)
+        # Read now, on the GUI thread, so the value is the one of this request and Qt windows are only touched here.
+        activation = self.activation() if os.path.isdir(repository_dir) and available_terminal_program(descriptor) else NO_STARTUP_ACTIVATION
+        threading.Thread(target=_launch_worker, args=(lambda: self.launch(descriptor, repository_dir, activation=activation), result, self.completion_queue), daemon=True).start()
+        self.timer.start()
+        return True
+
+    def launch_text_editor(self, request_id: object, command: TextEditorCommand, filename: str) -> bool:
+        """Start the editor on a working copy file off the Qt thread, with the same startup limit and timeout as a terminal.
+
+        The result names the editor program and its arguments, so a failure tells which editor did not start.
+        """
+        if self.closed or request_id in self.pending_by_id:
+            return False
+        directory = os.path.dirname(filename)
+        try:
+            program_filename, *argument_list = command.arguments(filename)
+        except ValueError as error:
+            self.finished.emit(ToolResult(request_id, TEXT_EDITOR_LABEL, directory, "", (), str(error)))
+            return False
+        result = ToolResult(request_id, TEXT_EDITOR_LABEL, directory, program_filename, tuple(argument_list))
+        if len(self.pending_by_id) >= TOOL_START_ACTIVE_LIMIT:
+            self.finished.emit(ToolResult(request_id, result.label, directory, result.program_filename, result.arguments, "Too many tools are starting. Try again after they finish."))
+            return False
+        self.pending_by_id[request_id] = PendingLaunch(result, time.monotonic() + TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        self.started.emit(request_id, result.label)
+        # Read now, on the GUI thread, so the value is the one of this request and Qt windows are only touched here.
+        activation = self.activation()
+        threading.Thread(target=_launch_worker, args=(lambda: self.text_editor_launch(command, filename, activation=activation), result, self.completion_queue), daemon=True).start()
+        self.timer.start()
+        return True
+
+    def open_explorer(self, request_id: object, repository_dir: str) -> None:
+        """Invoke Qt's desktop integration on the GUI thread after displaying progress."""
+        if self.closed or request_id in self.pending_by_id:
+            return
+        result = ToolResult(request_id, "file explorer", repository_dir, "", ())
+        self.pending_by_id[request_id] = PendingLaunch(result, time.monotonic() + TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        self.started.emit(request_id, result.label)
+        QTimer.singleShot(0, self, lambda: self._open_explorer(result))
+
+    def _open_explorer(self, result: ToolResult) -> None:
+        """Open a validated folder through Qt and report failures to the requesting window."""
+        if self.closed:
+            return
+        cause = ""
+        try:
+            self.explorer(result.repository_dir)
+        except (OSError, ValueError, RuntimeError) as error:
+            cause = str(error)
+        self.pending_by_id.pop(result.request_id, None)
+        self.finished.emit(ToolResult(result.request_id, result.label, result.repository_dir, "", (), cause))
+
+    def _poll(self) -> None:
+        """Report a bounded startup wait without pretending a timed-out OS call was cancelled."""
+        while True:
+            try:
+                result = self.export_completion_queue.get_nowait()
+            except queue.Empty:
+                break
+            operation = self.export_by_id.pop(result.request_id, None)
+            if operation is not None:
+                operation.cancel_read()
+                self.export_finished.emit(result)
+        if not self.export_by_id:
+            self.export_idle.emit()
+        while True:
+            try:
+                result, selected = self.reveal_completion_queue.get_nowait()
+            except queue.Empty:
+                break
+            pending = self.pending_by_id.get(result.request_id)
+            if pending is None:
+                continue
+            if pending.reported:
+                self.pending_by_id.pop(result.request_id)
+                continue
+            if not selected and not result.cause:
+                self._open_explorer(result)
+                continue
+            self.pending_by_id.pop(result.request_id)
+            self.finished.emit(result)
+        while True:
+            try:
+                result = self.completion_queue.get_nowait()
+            except queue.Empty:
+                break
+            pending = self.pending_by_id.pop(result.request_id, None)
+            if pending is not None and not pending.reported:
+                self.finished.emit(result)
+        for pending in tuple(self.pending_by_id.values()):
+            if not pending.reported and time.monotonic() >= pending.deadline:
+                pending.reported = True
+                result = pending.result
+                self.finished.emit(ToolResult(result.request_id, result.label, result.repository_dir, result.program_filename, result.arguments,
+                                              "Startup timed out. The system may still open this tool; another launch will wait for its response.", True))
+        if not self.pending_by_id and not self.export_by_id:
+            self.timer.stop()
+
+    def close(self) -> None:
+        """Stop receiving startup reports without terminating already launched tools."""
+        self.closed = True
+        for request_id in tuple(self.export_by_id):
+            self.cancel_export(request_id)
+        if not self.export_by_id:
+            self.timer.stop()
+        self.pending_by_id.clear()