gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/mergetool.py

@@ -0,0 +1,856 @@
+"""Resolve a series of conflicts through owned external tools or explicit keep or delete choices."""
+
+from __future__ import annotations
+
+import os
+import queue
+import stat
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Qt, QTimer, Signal
+
+from gitpane.config import MERGETOOL_START_TIMEOUT_MS, MERGETOOL_TERMINATE_TIMEOUT_MS, TOOL_RESULT_POLL_MS, WINDOWS_EXCEPTION_STATUS_START
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import GITPANE_CLOSING_TEXT, OperationOutcome
+from gitpane.process.process_group import NativeProcessGroup
+from gitpane.sequencer.conflict import NO_CONFLICT_SELECTED_TEXT, ConflictResolutionIntent, conflicts_from_snapshot, has_deleted_side
+from gitpane.sequencer.merge_recovery import RECOVERY_OUTPUT_BASENAME, MergeRecoveryStore
+from gitpane.system.linux_distribution import DistributionFamily, DistributionRelease
+from gitpane.system.startup_activation import NO_STARTUP_ACTIVATION, StartupActivation, no_startup_activation
+from gitpane.tool.mergetool_recipe import MERGETOOL_DEFAULT_COMMAND, parse_mergetool_command
+from gitpane.worktree.command_sequence import FileTask
+from gitpane.worktree.worktree_file import FILE_OBJECT_IDENTITY_FIELDS, FILE_STABLE_IDENTITY_FIELDS, PRIVATE_DIRECTORY_MODE, PRIVATE_FILE_MODE, FileImage, stat_identity
+from gitpane.worktree.worktree_snapshot import CONFLICT_ROLE_BY_STAGE
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.operation.repository_operation import OperationIntent
+    from gitpane.sequencer.conflict import ConflictService
+    from gitpane.tool.mergetool_recipe import MergetoolRecipe
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_snapshot import ConflictSide, WorktreeSnapshot
+
+AWAITING_MERGE_STATES = ("awaiting-base", "awaiting-result", "awaiting-deletion")
+# The only run states _poll has to look at over time: a starting tool has a startup deadline, and a pending confirmation becomes
+# stale when its authority is lost without any repository operation change. No worker event announces either, so only these keep the timer running.
+MERGETOOL_WATCHED_STATE_SET = frozenset(("starting", *AWAITING_MERGE_STATES))
+# Said when a merge series is asked while another series already resolves conflicts in the same shared repository.
+MERGE_SERIES_RUNNING_TEXT = "The merge tool is already resolving conflicts in this repository. Wait for it to finish."
+
+
+@dataclass(frozen=True)
+class MergetoolRequest:
+    """Retain the exact session, index stages, executable recipe and selected path."""
+
+    snapshot: WorktreeSnapshot
+    path: bytes
+    sides: tuple[ConflictSide, ...]
+    operation: OperationIntent
+    recipe: MergetoolRecipe
+    allow_missing_base: bool = False
+
+
+class MergetoolStatus(Enum):
+    """How one merge tool run ended for its conflict, written as its value in the --log line of the result."""
+
+    SAVED = "saved"
+    """The saved file was staged as the resolution of the conflict."""
+    UNRESOLVED = "unresolved"
+    """No saved result was recognized, or the tool could not run: the conflict stays as it was."""
+    STALE = "stale"
+    """The repository or the conflict changed under the tool, so its result was not staged."""
+    UNKNOWN = "unknown"
+    """The final reading of the repository failed, so how the run ended is not known."""
+
+
+@dataclass(frozen=True)
+class MergetoolResult:
+    """Distinguish saved, unresolved and refused results from native process completion."""
+
+    request: MergetoolRequest
+    status: MergetoolStatus
+    diagnostic: str = ""
+    recovery_filename: str = ""
+    return_code: int | None = None
+    snapshot: WorktreeSnapshot | None = None
+    settings_available: bool = False
+
+
+@dataclass
+class MergetoolRun:
+    """Keep child and private data ownership independent of the originating widget.
+
+    ``activation`` is the startup value of the click that launches this tool, which lets its window come to the front;
+    a tool started without a click has none.
+    """
+
+    request: MergetoolRequest
+    is_current: Callable[[], bool]
+    state: str = "preparing"
+    before: FileImage | None = None
+    output: FileImage | None = None
+    resolution: ConflictResolutionIntent | None = None
+    process: subprocess.Popen | None = None
+    group: NativeProcessGroup | None = None
+    worker: threading.Thread | None = None
+    stop_requested: threading.Event = field(default_factory=threading.Event)
+    return_code: int | None = None
+    deadline: float | None = None
+    forced: bool = False
+    uncertain: bool = False
+    invalidated: bool = False
+    activation: StartupActivation = NO_STARTUP_ACTIVATION
+
+
+@dataclass
+class MergetoolSeries:
+    """Retain the original ordered paths while each tool gets a newly verified snapshot.
+
+    ``activation`` holds the startup value of the click that started the series until its first tool takes it: the
+    following tools start when the previous one closes, without a click, so they get none. A keep or delete answer is a
+    click too: it gives the series a new value for the tool of the next file.
+    """
+
+    request: MergetoolRequest
+    paths: tuple[bytes, ...]
+    is_current: Callable[[], bool]
+    position: int = 0
+    stop_requested: bool = False
+    current_id: str = ""
+    results: list[MergetoolResult] = field(default_factory=list)
+    skipped_paths: list[bytes] = field(default_factory=list)
+    snapshot: WorktreeSnapshot | None = None
+    diagnostic: str = ""
+    invalidated: bool = False
+    activation: StartupActivation = NO_STARTUP_ACTIVATION
+
+
+class MergetoolUnavailable(ValueError):
+    """Identify executable errors separately from unsupported conflict content."""
+
+
+class TemporaryMergeStore:
+    """Keep request-owned directories, immutable inputs and initially absent outputs."""
+
+    def __init__(self, recovery_store: MergeRecoveryStore | None = None) -> None:
+        """Record filesystem identities independently from request-supplied paths."""
+        self.recovery_store = recovery_store if recovery_store is not None else MergeRecoveryStore()
+        self.directory_by_request: dict[str, tuple[str, tuple[int, ...]]] = {}
+        self.input_by_request: dict[str, dict[str, FileImage]] = {}
+        self.parent_by_request: dict[str, tuple[tuple[str, tuple[int, ...]], ...]] = {}
+
+    def create(self, request: MergetoolRequest) -> None:
+        """Create private storage outside the worktree without precreating MERGED."""
+        directory = self.recovery_store.create_directory(request.snapshot.context)
+        os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        request_id = request.operation.operation_id
+        self.directory_by_request[request_id] = (directory, stat_identity(os.lstat(directory)))
+        self.input_by_request[request_id] = {}
+        parents = []
+        current_dir = directory
+        while True:
+            parents.append((current_dir, stat_identity(os.lstat(current_dir))[:FILE_OBJECT_IDENTITY_FIELDS]))
+            parent_dir = os.path.dirname(current_dir)
+            if parent_dir == current_dir:
+                break
+            current_dir = parent_dir
+        self.parent_by_request[request_id] = tuple(parents)
+
+    def filename(self, request: MergetoolRequest, role: str) -> str:
+        """Return an inventoried role path with no raw repository path interpolation."""
+        if role not in (*CONFLICT_ROLE_BY_STAGE.values(), RECOVERY_OUTPUT_BASENAME):
+            raise ValueError("Unknown merge file role")
+        directory, _identity = self.directory_by_request[request.operation.operation_id]
+        return os.path.join(directory, role)
+
+    def validate_directory(self, request: MergetoolRequest) -> None:
+        """Refuse replacement or redirection of the owned directory and its ancestors."""
+        directory, expected = self.directory_by_request[request.operation.operation_id]
+        metadata = os.lstat(directory)
+        if stat_identity(metadata)[:FILE_OBJECT_IDENTITY_FIELDS] != expected[:FILE_OBJECT_IDENTITY_FIELDS]:
+            raise ValueError("The private merge directory was replaced.")
+        current_dir = directory
+        for parent_dir, identity in self.parent_by_request[request.operation.operation_id]:
+            if stat_identity(os.lstat(parent_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != identity:
+                raise ValueError("A private merge ancestor was replaced.")
+        while True:
+            if os.path.islink(current_dir) or os.path.isjunction(current_dir) or not stat.S_ISDIR(os.lstat(current_dir).st_mode):
+                raise ValueError("The private merge path was redirected.")
+            parent_dir = os.path.dirname(current_dir)
+            if parent_dir == current_dir:
+                break
+            current_dir = parent_dir
+
+    def read_file(self, request: MergetoolRequest, filename: str) -> FileImage:
+        """Accept a regular single-link file only while its handle and path identities agree."""
+        self.validate_directory(request)
+        metadata = os.lstat(filename)
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1 or os.path.islink(filename) or os.path.isjunction(filename):
+            raise ValueError("The private merge result is not an owned regular file.")
+        with open(filename, "rb") as stream:
+            if stat_identity(os.fstat(stream.fileno()))[:FILE_STABLE_IDENTITY_FIELDS] != stat_identity(metadata)[:FILE_STABLE_IDENTITY_FIELDS]:
+                raise ValueError("The private merge file changed while reading.")
+            content = stream.read()
+        if stat_identity(os.lstat(filename)) != stat_identity(metadata):
+            raise ValueError("The private merge file changed while reading.")
+        return FileImage(True, metadata.st_mode, content, identity=stat_identity(metadata))
+
+    def freeze_input(self, request: MergetoolRequest, filename: str) -> None:
+        """Remove write permission and retain exact input identities for later verification."""
+        os.chmod(filename, stat.S_IRUSR)
+        self.input_by_request[request.operation.operation_id][filename] = self.read_file(request, filename)
+
+    def capture_output(self, request: MergetoolRequest) -> FileImage | None:
+        """Recognize saved empty or identical bytes only after the process has really exited."""
+        self.validate_directory(request)
+        for filename, image in self.input_by_request[request.operation.operation_id].items():
+            if self.read_file(request, filename) != image:
+                raise ValueError("An immutable merge input was changed.")
+        filename = self.filename(request, RECOVERY_OUTPUT_BASENAME)
+        return self.read_file(request, filename) if os.path.lexists(filename) else None
+
+    def validate_output(self, request: MergetoolRequest, expected: FileImage) -> None:
+        """Require the same saved file identity and content after any confirmation wait."""
+        if self.capture_output(request) != expected:
+            raise ValueError("The saved merge result changed; it has not been published.")
+
+    def cleanup(self, request: MergetoolRequest, output: FileImage | None) -> None:
+        """Delete only named files with recorded identities, retaining unexpected content."""
+        request_id = request.operation.operation_id
+        if request_id not in self.directory_by_request:
+            return
+        self.validate_directory(request)
+        image_by_filename = dict(self.input_by_request[request_id])
+        if output is not None:
+            image_by_filename[self.filename(request, RECOVERY_OUTPUT_BASENAME)] = output
+        for filename, image in image_by_filename.items():
+            if self.read_file(request, filename) != image:
+                raise ValueError("A private file changed; cleanup was refused.")
+        for filename in image_by_filename:
+            os.chmod(filename, PRIVATE_FILE_MODE)
+            os.unlink(filename)
+        directory, _identity = self.directory_by_request[request_id]
+        os.rmdir(directory)
+        self.directory_by_request.pop(request_id)
+        self.input_by_request.pop(request_id)
+        self.parent_by_request.pop(request_id)
+
+
+class MergetoolService(QObject):
+    """Reserve each selected conflict through its tool or file choice and final Git reread."""
+
+    started = Signal(object)
+    finished = Signal(object)
+    confirmation_requested = Signal(object, str)
+    confirmation_closed = Signal(str)
+    idle = Signal()
+    series_changed = Signal(object)
+    series_finished = Signal(object)
+    event_ready = Signal()
+
+    def __init__(self, conflict: ConflictService, mutation: MutationService, parent: QObject | None = None,
+                 *, process_factory: Callable[..., subprocess.Popen] = subprocess.Popen, temporary_store: TemporaryMergeStore | None = None,
+                 activation: Callable[[], StartupActivation] = no_startup_activation, platform: str = sys.platform,
+                 distribution_family: DistributionFamily = DistributionFamily.UNKNOWN, distribution_release: DistributionRelease = DistributionRelease.OTHER) -> None:
+        """Inject the real transaction and process creator without hiding their ownership.
+
+        A merge refused for a missing tool says how to install KDiff3 on ``platform``, and under Linux on the distribution
+        ``distribution_family`` and ``distribution_release`` that the wiring read from the session once; all are received,
+        so each system's message can be checked from any of them.
+
+        The activation source tells the desktop that the user asked for a merge tool (an X11 startup identifier or a
+        Wayland activation token), so its window may come to the front. It is read on the window's thread at the click
+        that starts a series and at the agreement on a missing base, never for a tool started without a click. Without
+        a desktop, as in the tests, there is none.
+        """
+        super().__init__(parent)
+        self.conflict = conflict
+        self.mutation = mutation
+        self.activation = activation
+        self.platform = platform
+        self.distribution_family = distribution_family
+        self.distribution_release = distribution_release
+        self.worktree_service = mutation.worktree_service
+        self.repository_operation = mutation.repository_operation
+        self.process_factory = process_factory
+        self.temporary_store = temporary_store if temporary_store is not None else TemporaryMergeStore()
+        self.active_by_id: dict[str, MergetoolRun] = {}
+        self.result_by_id: dict[str, MergetoolResult] = {}
+        self.series_by_id: dict[str, MergetoolSeries] = {}
+        self.series_id_by_request: dict[str, str] = {}
+        self.event_queue: queue.SimpleQueue[tuple[str, str, object]] = queue.SimpleQueue()
+        self.closed = False
+        self.timer = QTimer(self)
+        self.timer.setInterval(TOOL_RESULT_POLL_MS)
+        self.timer.timeout.connect(self._poll)
+        self.event_ready.connect(self._poll, Qt.ConnectionType.QueuedConnection)
+        self.repository_operation.changed.connect(self._revalidate_runs)
+
+    def owns_repository(self, common_git_dir: str) -> bool:
+        """Include between-file reads so a series cannot race a rebase continuation."""
+        return (any(run.request.operation.common_git_dir == common_git_dir for run in self.active_by_id.values())
+                or any(series.request.operation.common_git_dir == common_git_dir for series in self.series_by_id.values()))
+
+    def merge_series(self, request: MergetoolRequest, paths: tuple[bytes, ...], is_current: Callable[[], bool]) -> str:
+        """Capture paths once and refuse another series against the same shared repository.
+
+        A refused series says why, so the user knows whether to wait, reopen the window or select a file: GitPane is
+        closing; no conflicted file is selected; the window is stale, with the reason it lost its authority (never
+        another running operation, since waiting for it would not help); or another series already works on the same
+        shared repository. Between two files a series holds no reservation, so only this service can name it.
+
+        Called by the user's click: an accepted series reads the click's startup value here, on the window's thread,
+        and keeps it for its first tool.
+        """
+        series_id = request.operation.operation_id
+        if self.closed:
+            self._refuse_series(request, GITPANE_CLOSING_TEXT)
+            return series_id
+        if not paths:
+            self._refuse_series(request, NO_CONFLICT_SELECTED_TEXT)
+            return series_id
+        if not is_current():
+            self._refuse_series(request, self.repository_operation.authority_cause(request.operation))
+            return series_id
+        for series in self.series_by_id.values():
+            if series.request.operation.common_git_dir == request.operation.common_git_dir:
+                self._refuse_series(request, MERGE_SERIES_RUNNING_TEXT)
+                return series_id
+        series = MergetoolSeries(request, tuple(sorted(set(paths))), is_current, activation=self.activation())
+        self.series_by_id[series_id] = series
+        self._next_series_path(series)
+        return series_id
+
+    def _refuse_series(self, request: MergetoolRequest, cause: str) -> None:
+        """Return a visible refusal with its real cause, without touching another series's reservation or state.
+
+        The result is published on the next event-loop turn, like any other result, so the caller has returned the
+        series identifier before the conflicts window reads the refusal.
+        """
+        result = MergetoolResult(request, MergetoolStatus.UNRESOLVED, cause)
+        self.result_by_id[request.operation.operation_id] = result
+        QTimer.singleShot(0, self, lambda: self.finished.emit(result))
+
+    def invalidate_session(self, session_id: str | None) -> None:
+        """Permanently revoke old publication rights while preserving children and saved output."""
+        for series in tuple(self.series_by_id.values()):
+            if series.request.operation.session_id == session_id:
+                series.invalidated = True
+                self.stop_series(series.request.operation.operation_id)
+        for run in tuple(self.active_by_id.values()):
+            if run.request.operation.session_id == session_id:
+                run.invalidated = True
+                if run.state in AWAITING_MERGE_STATES:
+                    self._finish(run, MergetoolStatus.STALE, "The original repository session is no longer current.", retain=run.output is not None)
+
+    def stop_series(self, series_id: str) -> None:
+        """Prevent future launches without revoking the current process's publication rights."""
+        series = self.series_by_id.get(series_id)
+        if series is not None:
+            series.stop_requested = True
+            self.series_changed.emit(series)
+
+    def _next_series_path(self, series: MergetoolSeries) -> None:
+        """Choose the next path from a complete read of the repository, including paths already resolved externally.
+
+        The first path reads the repository. Each following path starts from the terminal read the previous file has
+        just finished, when that read still covers exactly the original inventory: its conversion settings are then
+        compared directly with the original ones. When the inventory changed, for instance a result equal to HEAD
+        leaves the list of changed files, the repository is read again and its conversion is checked on the original
+        inventory, because settings read on two different sets of paths cannot be compared. Either way the next tool
+        only starts after its own preparation has asked Git to verify the state it relies on.
+
+        The first tool the series starts takes the startup value of the click that started it; the series then forgets
+        it, so a tool started when the previous one closes cannot take the focus without a click.
+        """
+        request = series.request
+        if series.stop_requested or series.invalidated or self.closed or not series.is_current() or series.position >= len(series.paths):
+            self._finish_series(series)
+            return
+        series.current_id = ""
+        self.series_changed.emit(series)
+
+        def captured(snapshot: object, error: Exception | None) -> None:
+            """Advance only from a fresh read and never reinterpret the original path selection."""
+            if error is not None or snapshot is None or not snapshot.fresh:
+                series.diagnostic = "Could not read current merge conflicts. Rescan before retrying."
+                if error is not None:
+                    series.diagnostic += " " + self._safe_error(error)
+                self._finish_series(series)
+                return
+            series.snapshot = snapshot
+            if series.stop_requested or series.invalidated or self.closed or not series.is_current():
+                self._finish_series(series)
+                return
+            if snapshot.head_oid != request.snapshot.head_oid:
+                series.diagnostic = "Repository configuration or HEAD changed. Rescan before retrying."
+                self._finish_series(series)
+                return
+            path = series.paths[series.position]
+            series.position += 1
+            entry = next((entry for entry in conflicts_from_snapshot(snapshot) if entry.path == path), None)
+            if entry is None:
+                series.skipped_paths.append(path)
+                self._next_series_path(series)
+                return
+            original = next((entry for entry in conflicts_from_snapshot(request.snapshot) if entry.path == path), None)
+            if original is None or entry.sides != original.sides:
+                series.diagnostic = "The selected conflict versions changed. Rescan before retrying."
+                self._finish_series(series)
+                return
+            owner = replace(request.operation, operation_id=uuid.uuid4().hex)
+            current = replace(request, snapshot=snapshot, path=path, sides=entry.sides, operation=owner)
+            series.current_id = owner.operation_id
+            self.series_id_by_request[owner.operation_id] = request.operation.operation_id
+            self.series_changed.emit(series)
+            activation = series.activation
+            series.activation = NO_STARTUP_ACTIVATION
+            self.merge(current, series.is_current, activation=activation)
+
+        def capture() -> Generator:
+            """Check attributes against the original inventory without changing the new snapshot."""
+            snapshot = yield from self.worktree_service.capture(request.snapshot.context, request.snapshot.git_filename, request.snapshot.generation)
+            yield from self.worktree_service.verify_conversion(request.snapshot)
+            return snapshot
+
+        if series.results:
+            terminal = series.snapshot
+            original = request.snapshot
+            if (terminal is None or not terminal.fresh or terminal.key != original.key or terminal.context != original.context
+                    or terminal.git_filename != original.git_filename):
+                series.diagnostic = "Could not read current merge conflicts. Rescan before retrying."
+                self._finish_series(series)
+                return
+            if tuple(terminal.fingerprint_by_path) == tuple(original.fingerprint_by_path):
+                if terminal.conversion != original.conversion:
+                    series.diagnostic = "Repository configuration or attributes changed. Rescan before retrying."
+                    self._finish_series(series)
+                    return
+                captured(terminal, None)
+                return
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, capture(), captured)
+
+    def _finish_series(self, series: MergetoolSeries) -> None:
+        """Publish the series observation without counting external resolutions as our results."""
+        self.series_by_id.pop(series.request.operation.operation_id, None)
+        self.series_finished.emit(series)
+        self._update_poll_timer()
+        if not self.active_by_id and not self.series_by_id:
+            self.idle.emit()
+
+    def _series_result(self, result: MergetoolResult) -> None:
+        """Require saved success and terminal Git proof before considering the next editor."""
+        series_id = self.series_id_by_request.pop(result.request.operation.operation_id, None)
+        series = self.series_by_id.get(series_id)
+        if series is None:
+            return
+        series.results.append(result)
+        series.snapshot = result.snapshot
+        if (result.status != MergetoolStatus.SAVED or result.snapshot is None or not result.snapshot.fresh
+                or any(entry.path == result.request.path for entry in conflicts_from_snapshot(result.snapshot))):
+            series.diagnostic = result.diagnostic
+            if result.recovery_filename:
+                series.diagnostic += " Saved result retained at: " + result.recovery_filename
+            self._finish_series(series)
+            return
+        self._next_series_path(series)
+
+    def merge(self, request: MergetoolRequest, is_current: Callable[[], bool], *, activation: StartupActivation = NO_STARTUP_ACTIVATION) -> str:
+        """Reserve each captured file before choosing a deletion prompt or an external merge.
+
+        ``activation`` is the startup value of the click that asked for this file, handed to its tool; a file started
+        without a click gets none.
+
+        A refused merge says why: GitPane is closing; the window is stale, with the reason it lost its authority (never
+        another running operation, since waiting for it would not help); or the repository could not be reserved, with
+        the reason the repository operation service finds, which names another operation only when one really holds it.
+        """
+        request_id = request.operation.operation_id
+        cause = ""
+        if self.closed:
+            cause = GITPANE_CLOSING_TEXT
+        elif not is_current():
+            cause = self.repository_operation.authority_cause(request.operation)
+        elif not self.repository_operation.reserve(request.operation):
+            cause = self.repository_operation.refusal_cause(request.operation)
+        if cause:
+            result = MergetoolResult(request, MergetoolStatus.UNRESOLVED, cause)
+            def refused() -> None:
+                """Report the refusal before ending its owning series."""
+                self.finished.emit(result)
+                self._series_result(result)
+
+            QTimer.singleShot(0, self, refused)
+            return request_id
+        run = MergetoolRun(request, is_current, activation=activation)
+        self.active_by_id[request_id] = run
+        self._prepare(run)
+        self._update_poll_timer()
+        return request_id
+
+    def _prepare(self, run: MergetoolRun) -> None:
+        """Validate missing-side choices before private extraction and native startup."""
+        request = run.request
+        request_id = request.operation.operation_id
+
+        def prepare() -> str:
+            """Inspect the conflict first so a deleted side does not require an installed text merge tool."""
+            if (request.operation.key != request.snapshot.key or request.operation.context != request.snapshot.context
+                    or request.operation.git_filename != request.snapshot.git_filename):
+                raise ValueError("The merge request does not belong to its repository owner.")
+            entry = next((entry for entry in conflicts_from_snapshot(request.snapshot) if entry.path == request.path), None)
+            if entry is None or entry.sides != request.sides:
+                raise ValueError("The selected conflict versions changed. Rescan before retrying.")
+            if has_deleted_side(entry.sides):
+                return "deleted-side"
+            try:
+                request.recipe.validate(platform=self.platform, family=self.distribution_family, release=self.distribution_release)
+            except ValueError as error:
+                raise MergetoolUnavailable(str(error)) from error
+            if entry.kind not in ("Text conflict", "Add/add (no base)"):
+                raise ValueError("Use manual conflict resolution for this file type or missing side.")
+            missing_base = entry.kind == "Add/add (no base)"
+            if missing_base and request.allow_missing_base:
+                parse_mergetool_command(request.recipe.command, None, "LOCAL", "REMOTE", RECOVERY_OUTPUT_BASENAME, allow_missing_base=True)
+            return "missing-base" if missing_base and not request.allow_missing_base else ""
+
+        def sequence() -> Generator:
+            """Keep both file and Git work out of synchronous widget callbacks."""
+            reason = yield FileTask(prepare)
+            if reason == "deleted-side":
+                yield from self.worktree_service.verify(request.snapshot, (request.path,))
+                resolution = yield FileTask(lambda: ConflictResolutionIntent.capture(request.snapshot, request.path, request.operation, delete=True))
+                return reason, resolution
+            if reason:
+                return reason, None
+            return "", (yield from self.conflict.prepare_merge(request, self.temporary_store, self.mutation))
+
+        def prepared(value: object, error: Exception | None) -> None:
+            """Start the owned child only while the captured session is still valid."""
+            if error is not None:
+                self._finish(run, MergetoolStatus.UNRESOLVED, self._safe_error(error), settings_available=isinstance(error, MergetoolUnavailable))
+                return
+            if not self._current(run):
+                self._finish(run, MergetoolStatus.STALE, "The original repository session is no longer current.")
+                return
+            reason, result = value
+            if reason == "deleted-side":
+                run.resolution = result
+                run.state = "awaiting-deletion"
+                self._update_poll_timer()
+                self.confirmation_requested.emit(request, reason)
+                return
+            if reason == "missing-base":
+                run.state = "awaiting-base"
+                self._update_poll_timer()
+                self.confirmation_requested.emit(request, "missing-base")
+                return
+            run.before = result
+            run.state = "starting"
+            run.deadline = time.monotonic() + MERGETOOL_START_TIMEOUT_MS / 1000
+            run.worker = threading.Thread(target=self._run_process, args=(run,), daemon=True)
+            run.worker.start()
+            self._update_poll_timer()
+
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, sequence(), prepared, operation_id=request_id)
+
+    def confirm(self, request_id: str, accepted: bool) -> None:
+        """Require explicit agreement while rechecking saved output and original authority.
+
+        Called when the user answers the question: an agreement on a missing base starts the tool, so the startup value
+        of that answer is read here, on the window's thread, for it.
+        """
+        run = self.active_by_id.get(request_id)
+        if run is not None and run.state == "awaiting-deletion":
+            if not accepted:
+                self.confirm_deletion(request_id, None)
+            return
+        if run is None or run.state not in ("awaiting-base", "awaiting-result"):
+            return
+        if not accepted or not self._current(run):
+            self._finish(run, MergetoolStatus.UNRESOLVED, "The conflict was kept unresolved.", retain=run.output is not None)
+            return
+        if run.state == "awaiting-base":
+            run.request = replace(run.request, allow_missing_base=True)
+            run.activation = self.activation()
+            run.state = "preparing"
+            self._prepare(run)
+            return
+        self._publish(run)
+
+    def confirm_deletion(self, request_id: str, delete: bool | None) -> None:
+        """Stage the exact keep/delete choice under the existing owner, or stop the series on cancellation.
+
+        Called when the user answers the question: when a series has files left, the tool of the next one starts once the
+        choice is staged, so the startup value of that answer is read here, on the window's thread, for it.
+        """
+        run = self.active_by_id.get(request_id)
+        if run is None or run.state != "awaiting-deletion" or run.resolution is None:
+            return
+        if delete is None or not self._current(run):
+            self._finish(run, MergetoolStatus.UNRESOLVED, "The conflict was kept unresolved. The remaining selected files were not processed.")
+            return
+        if not delete and not run.resolution.image.exists:
+            self._finish(run, MergetoolStatus.UNRESOLVED, "The working file is absent and cannot be kept. Rescan before retrying.")
+            return
+        series = self.series_by_id.get(self.series_id_by_request.get(request_id))
+        if series is not None and series.position < len(series.paths):
+            series.activation = self.activation()
+        run.state = "publishing"
+        resolution = replace(run.resolution, delete=delete)
+
+        def completed(outcome: object, error: Exception | None) -> None:
+            """Continue only after successful publication; retain the transaction's recovery diagnostic on failure."""
+            if error is not None:
+                self._finish(run, MergetoolStatus.STALE, self._safe_error(error))
+                return
+            if outcome.status != "success":
+                self._finish(run, MergetoolStatus.STALE, outcome.diagnostic.cause if outcome.diagnostic is not None else "Git could not stage the chosen conflict resolution.")
+                return
+            self._finish(run, MergetoolStatus.SAVED)
+
+        self.worktree_service.run(resolution.snapshot.context, resolution.snapshot.git_filename, self.mutation.resolve_conflict_sequence(resolution), completed,
+                                 operation_id=request_id)
+
+    def _current(self, run: MergetoolRun) -> bool:
+        """Recheck both application authority and exact repository ownership before publication."""
+        registry = self.repository_operation
+        return (not run.invalidated and not self.closed and not registry.closed and run.is_current() and registry.active_by_id.get(run.request.operation.operation_id) is run.request.operation
+                and (registry.allows is None or registry.allows(run.request.operation)))
+
+    @staticmethod
+    def _safe_error(error: Exception) -> str:
+        """Avoid including arbitrary child output or command arguments in merge diagnostics."""
+        from gitpane.worktree.command_sequence import GitCommandError
+
+        return "Git could not validate or stage the merge result. Rescan before retrying." if isinstance(error, GitCommandError) else str(error)
+
+    def _run_process(self, run: MergetoolRun) -> None:
+        """Wait for the supervisor and every descendant without blocking the Qt event loop.
+
+        The supervisor gets GitPane's environment without any inherited startup value, plus the one of the click that
+        launched this tool, and hands that environment on to the tool.
+        """
+        request = run.request
+        request_id = request.operation.operation_id
+        try:
+            store = self.temporary_store
+            store.validate_directory(request)
+            role_set = set()
+            for side in request.sides:
+                role_set.add(CONFLICT_ROLE_BY_STAGE[side.stage])
+            arguments = parse_mergetool_command(request.recipe.command, store.filename(request, "BASE") if "BASE" in role_set else None,
+                                               store.filename(request, "LOCAL"), store.filename(request, "REMOTE"), store.filename(request, RECOVERY_OUTPUT_BASENAME),
+                                               allow_missing_base=request.allow_missing_base)
+            if os.path.lexists(store.filename(request, RECOVERY_OUTPUT_BASENAME)):
+                raise ValueError("The private merge output was created before launch.")
+            run.group = NativeProcessGroup()
+            program_filename, arguments = run.group.prepare(request.recipe.program_filename, arguments)
+            directory, _identity = store.directory_by_request[request_id]
+            # Tool streams may contain whole file versions; redaction cannot safely classify arbitrary blob text.
+            run.process = self.process_factory([program_filename, *arguments], cwd=directory, shell=False, stdin=subprocess.DEVNULL,
+                                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=run.activation.environment(os.environ),
+                                               creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+            self._queue_event((request_id, "started", None))
+            self._wait_process(run)
+        except (OSError, ValueError) as error:
+            if run.process is not None:
+                run.uncertain = True
+                self._wait_process(run)
+                return
+            if run.group is not None:
+                run.group.close()
+            self._queue_event((request_id, "error", type(error).__name__))
+
+    def _wait_process(self, run: MergetoolRun) -> None:
+        """Keep polling uncertain OS proof instead of abandoning a still-owned native child."""
+        request_id = run.request.operation.operation_id
+        stop_sent = False
+        while True:
+            if run.stop_requested.is_set() and not stop_sent:
+                try:
+                    run.group.stop()
+                    stop_sent = True
+                except OSError:
+                    run.uncertain = True
+            try:
+                return_code = run.process.poll()
+                if return_code is not None and run.group.is_empty():
+                    run.process.wait(timeout=MERGETOOL_TERMINATE_TIMEOUT_MS / 1000)
+                    run.return_code = run.group.result_return_code(return_code)
+                    failed = run.group.launch_failed()
+                    run.group.close()
+                    self._queue_event((request_id, "exited", failed))
+                    return
+            except (OSError, ValueError):
+                if not run.uncertain:
+                    self._queue_event((request_id, "unknown", None))
+                run.uncertain = True
+            time.sleep(TOOL_RESULT_POLL_MS / 1000)
+
+    def _queue_event(self, event: tuple[str, str, object]) -> None:
+        """Let a worker thread drop one event and wake the Qt thread, the only one that touches the runs."""
+        self.event_queue.put(event)
+        self.event_ready.emit()
+
+    def _update_poll_timer(self) -> None:
+        """Run the timer only while a run waits in a state that needs checking over time, never while a tool window is open."""
+        watched = any(run.state in MERGETOOL_WATCHED_STATE_SET for run in self.active_by_id.values())
+        if watched and not self.timer.isActive():
+            self.timer.start()
+        elif not watched and self.timer.isActive():
+            self.timer.stop()
+
+    def _revalidate_runs(self) -> None:
+        """Permanently invalidate every run that lost its authority, and end a pending confirmation that did.
+
+        Nothing is polled while a tool window is open: authority is rechecked each time a repository operation starts or ends,
+        when the tool exits and during publication. A change of the merge tool or Git preference invalidates the run for good
+        through invalidate_session, even if the preference is restored afterwards.
+        """
+        for run in tuple(self.active_by_id.values()):
+            if self._current(run):
+                continue
+            run.invalidated = True
+            if run.state in AWAITING_MERGE_STATES:
+                self._finish(run, MergetoolStatus.STALE, "The original repository session is no longer current.", retain=run.output is not None)
+
+    def _poll(self) -> None:
+        """Deliver worker events on Qt while retaining timed-out or unknown process ownership.
+
+        Worker events wake it through event_ready; the timer only adds the checks over time of the watched states.
+        """
+        while True:
+            try:
+                request_id, kind, value = self.event_queue.get_nowait()
+            except queue.Empty:
+                break
+            run = self.active_by_id.get(request_id)
+            if run is None:
+                continue
+            if kind == "started":
+                run.state = "running"
+                self.started.emit(run.request)
+            elif kind == "exited":
+                self._process_finished(run, bool(value))
+            elif kind == "error":
+                self._finish(run, MergetoolStatus.UNRESOLVED, "The external merge tool could not start (" + str(value) + ").", settings_available=True)
+            elif kind == "unknown":
+                run.state = "unknown"
+        for run in tuple(self.active_by_id.values()):
+            if run.state == "starting" and run.deadline is not None and time.monotonic() >= run.deadline:
+                run.forced = True
+                run.stop_requested.set()
+        self._revalidate_runs()
+        self._update_poll_timer()
+
+    def _process_finished(self, run: MergetoolRun, launch_failed: bool) -> None:
+        """Inspect a request-owned result only after the OS proves actual process completion."""
+        run.state = "inspecting"
+
+        def sequence() -> Generator:
+            """Read regular saved bytes on a file worker."""
+            return (yield FileTask(lambda: self.temporary_store.capture_output(run.request)))
+
+        def inspected(output: object, error: Exception | None) -> None:
+            """Never equate a successful close without a produced file to a resolution."""
+            run.output = output
+            if error is not None:
+                self._finish(run, MergetoolStatus.STALE, self._safe_error(error), retain=True)
+            elif not self._current(run):
+                self._finish(run, MergetoolStatus.STALE, "The original repository session is no longer current.", retain=output is not None)
+            elif output is None or launch_failed or run.forced or self._crashed(run.return_code):
+                self._finish(run, MergetoolStatus.UNRESOLVED, "No successful saved merge result was recognized. Use Mark conflict as solved after checking the working file.", retain=output is not None)
+            elif run.return_code != 0 or run.uncertain or run.request.recipe.command != MERGETOOL_DEFAULT_COMMAND or self._has_markers(output):
+                run.state = "awaiting-result"
+                self._update_poll_timer()
+                self.confirmation_requested.emit(run.request, "saved-result")
+            else:
+                self._publish(run)
+
+        request = run.request
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, sequence(), inspected, operation_id=request.operation.operation_id)
+
+    @staticmethod
+    def _crashed(return_code: int | None) -> bool:
+        """Distinguish signalled exits and Windows exception statuses from normal refusal codes."""
+        return return_code is None or return_code < 0 or os.name == "nt" and return_code >= WINDOWS_EXCEPTION_STATUS_START
+
+    @staticmethod
+    def _has_markers(output: FileImage) -> bool:
+        """Treat merge-like markers as ambiguity while allowing explicit saved-result approval."""
+        content = output.read()
+        return b"<<<<<<<" in content and b"=======" in content and b">>>>>>>" in content
+
+    def _publish(self, run: MergetoolRun) -> None:
+        """Keep metadata reads lightweight while the index transaction supervises its writes."""
+        run.state = "publishing"
+        request = run.request
+
+        def completed(outcome: object, error: Exception | None) -> None:
+            """Preserve saved bytes on any refusal, including Git filter or lock failures."""
+            if error is not None or outcome.status != "success":
+                self._finish(run, MergetoolStatus.STALE, self._safe_error(error) if error else "Git could not stage the saved working result.", retain=True)
+                return
+            self._finish(run, MergetoolStatus.SAVED)
+
+        sequence = self.conflict.publish_merge_result(request, run.before, run.output, self.temporary_store, self.mutation, lambda: self._current(run))
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, sequence, completed, operation_id=request.operation.operation_id)
+
+    def _finish(self, run: MergetoolRun, status: MergetoolStatus, diagnostic: str = "", *, retain: bool = False, settings_available: bool = False) -> None:
+        """Reread terminal Git state and finish file work before releasing the sole owner."""
+        run.state = "finishing"
+        request, store = run.request, self.temporary_store
+        request_id = request.operation.operation_id
+        self.confirmation_closed.emit(request_id)
+        recovery_filename = store.filename(request, RECOVERY_OUTPUT_BASENAME) if retain and request_id in store.directory_by_request else ""
+        recovery_diagnostic = ""
+
+        def sequence() -> Generator:
+            """Keep cleanup and the final observation within the reservation's lifetime."""
+            nonlocal recovery_diagnostic
+            if recovery_filename:
+                try:
+                    yield FileTask(lambda: store.validate_directory(request))
+                    yield FileTask(lambda: store.recovery_store.retain(request.snapshot.context, os.path.dirname(recovery_filename), request.path))
+                except (OSError, ValueError) as error:
+                    recovery_diagnostic = " Recovery information could not be recorded: " + self._safe_error(error)
+            if not retain:
+                yield FileTask(lambda: store.cleanup(request, run.output))
+            return (yield from self.worktree_service.capture(request.snapshot.context, request.snapshot.git_filename, request.snapshot.generation))
+
+        def complete(snapshot: object, error: Exception | None) -> None:
+            """Retain the result before notifying views or allowing another repository operation."""
+            final_status = MergetoolStatus.UNKNOWN if error is not None else status
+            final_diagnostic = diagnostic or (self._safe_error(error) if error else "")
+            final_diagnostic += recovery_diagnostic
+            result = MergetoolResult(request, final_status, final_diagnostic, recovery_filename, run.return_code, snapshot, settings_available)
+            self.result_by_id[request_id] = result
+            self.active_by_id.pop(request_id, None)
+            self.repository_operation.reconcile(OperationOutcome(request_id, OperationStatus.SUCCESS if final_status == MergetoolStatus.SAVED else OperationStatus.REFUSED))
+            self.finished.emit(result)
+            self._series_result(result)
+            self._update_poll_timer()
+            if not self.active_by_id and not self.series_by_id:
+                self.idle.emit()
+
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, sequence(), complete, operation_id=request_id)
+
+    def close(self) -> None:
+        """Reject new launches and stop supervised descendants while retaining their resources."""
+        self.closed = True
+        for series_id in tuple(self.series_by_id):
+            self.stop_series(series_id)
+        for run in tuple(self.active_by_id.values()):
+            run.forced = True
+            run.stop_requested.set()
+            if run.state in AWAITING_MERGE_STATES:
+                self._finish(run, MergetoolStatus.STALE, "The original repository session is no longer current.", retain=run.output is not None)