gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/staging.py

@@ -0,0 +1,1418 @@
+"""Coordinate one shared preparation session, its draft included, per worktree."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QSignalBlocker, QTimer, Signal
+from PySide6.QtWidgets import QApplication
+from shiboken6 import isValid
+
+from gitpane.commit.commit_write import CommitOutcome, CommitRequest, CommitService
+from gitpane.config import WORKTREE_REFRESH_INTERVAL_MS, ProcessPriority
+from gitpane.history.file_history import FileHistoryAnchor
+from gitpane.history.history_parse import parse_tree_entries
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction, OperationIntent, PauseProbe, native_rebase_capture, read_pause_probe_filenames
+from gitpane.sequencer.merge_state import MergeBannerState, merge_message_text, read_merge_banner_state
+from gitpane.submodule.submodule_discovery import SubmoduleService
+from gitpane.tool.system_tool import file_location, worktree_filename
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.file_menu_action import READ_ONLY_FILE_ACTION_SET, FileAction
+from gitpane.worktree.ignore_rule import IgnoreDestination, IgnoreOutcome, IgnoreRuleService
+from gitpane.worktree.mutation import RECOVER_CHANGES_OPERATION
+from gitpane.worktree.partial_patch import RawLineSelection, RawPatch, read_partial
+from gitpane.worktree.trash import TrashOutcome, TrashRequest, TrashService
+from gitpane.worktree.worktree_snapshot import StagingSide, WorktreeKey, local_history_path, passive_observation_source
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from PySide6.QtWidgets import QWidget
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.sequencer.merge_state import MergeInProgress
+    from gitpane.sequencer.rebase import RebaseService
+    from gitpane.sequencer.rebase_state import NativeMetadata, RebaseSnapshot
+    from gitpane.submodule.submodule_discovery import SubmoduleSummary
+    from gitpane.worktree.mutation import MutationOutcome, MutationService, PreparedLineReset
+    from gitpane.worktree.staged_reset import ResetCandidate
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry, PassiveObservationSource, WorktreeProbe, WorktreeSnapshot
+
+# The staging view explains these actions together; the intention it captures for them is never reserved.
+STAGING_AVAILABILITY_OPERATION_ID = "staging-availability"
+STAGING_AVAILABILITY_ACTIONS: tuple[OperationAction, ...] = (OperationAction.COMMIT, OperationAction.AMEND, OperationAction.COMMIT_PUSH,
+                                                             OperationAction.STAGE, OperationAction.UNSTAGE)
+# Diagnostics that describe the present state of the worktree rather than the result of an action: they stay shown until
+# a successful read proves them over, whereas a result is forgotten once the user closes the window that showed it.
+READ_CHANGES_OPERATION = "Read changes"
+STATE_DIAGNOSTIC_OPERATION_SET = frozenset({READ_CHANGES_OPERATION, RECOVER_CHANGES_OPERATION})
+# Said when the changes shown moved while a file's history anchor was read and that anchor no longer matches them.
+HISTORY_STATE_CHANGED_CAUSE = "Changes were updated while resolving file history; use File history again"
+# Side accepted by default for a file action: only Unstaged entries may be staged, stop being tracked or show their history.
+UNSTAGED_SIDE_SET = frozenset((StagingSide.UNSTAGED,))
+# Both lists of Prepare changes.
+LISTED_SIDE_SET = frozenset((StagingSide.UNSTAGED, StagingSide.STAGED))
+
+
+def head_moved_between(previous: WorktreeSnapshot | None, current: WorktreeSnapshot | None) -> bool:
+    """Tell whether two successive worktree reads name another HEAD or another branch; a first read, or one without status facts, tells nothing."""
+    if previous is None or current is None or previous.probe is None or current.probe is None:
+        return False
+    return previous.probe.head_oid != current.probe.head_oid or previous.probe.branch_head != current.probe.branch_head
+
+
+class StagingSession(QObject):
+    """Keep writes alive independently of windows while coalescing background refresh."""
+
+    changed = Signal()
+    # The draft has a signal of its own: the subscribers of changed read the worktree state again and start Git
+    # observations, which a keystroke never justifies. The text itself never travels in the signal.
+    draft_changed = Signal()
+    pause_observation_requested = Signal()
+    # A worktree read found HEAD, or the branch it is on, other than the read before it. Only a read says so: a state an
+    # operation of GitPane publishes after writing never does, since that operation refreshes its windows itself.
+    head_moved = Signal()
+    # A click on Commit or on Commit & push has just captured this CommitRequest, before the commit service saw it:
+    # whoever times the commit starts its clock here. Commit & push may still drop the request while it reads where to
+    # push, before submitting it; then the commit service never sees it.
+    commit_submitted = Signal(object)
+    commit_finished = Signal(object)
+    history_requested = Signal(object)
+    folder_requested = Signal(object)
+    text_editor_requested = Signal(object)
+    window_opened = Signal(object)
+    commit_push_requested = Signal(object, object)
+
+    def __init__(self, context: RepositoryContext, git_filename: str, worktree_service: WorktreeService, mutation: MutationService, parent: QObject | None = None, *,
+                 rebase_service: RebaseService | None = None, window_factory: Callable[[RepositoryContext], QWidget]) -> None:
+        """Associate the shared draft and last result with exactly one real worktree.
+
+        ``rebase_service`` is the application's one rebase observer; an Amend of a paused rebase reads the pause through
+        it, and is refused without it. ``window_factory`` builds the Prepare changes window for this worktree the first
+        time the session opens; the window class belongs to the interface, which the domain does not import.
+        """
+        super().__init__(parent)
+        self.context = context
+        self.rebase_service = rebase_service
+        self.window_factory = window_factory
+        self.key = WorktreeKey.from_context(context)
+        self.git_filename = git_filename
+        self.worktree_service = worktree_service
+        self.submodule_service = SubmoduleService(worktree_service)
+        self.mutation = mutation
+        self.commit_service = CommitService(worktree_service.runner, worktree_service, mutation, self)
+        self.commit_service.finished.connect(self._commit_finished)
+        self.commit_service.waiting.connect(self._commit_waiting)
+        self.last_commit_outcome: CommitOutcome | None = None
+        self.active_commit_request: CommitRequest | None = None
+        self.active_commit_action: OperationAction | None = None
+        self.commit_push_session_id: str | None = None
+        self.pending_commit_push_request: CommitRequest | None = None
+        self.trash_service = TrashService(worktree_service, mutation, parent=self)
+        self.trash_service.finished.connect(self._trash_finished)
+        self.trash_service.waiting.connect(self._trash_waiting)
+        self.last_trash_outcome: TrashOutcome | None = None
+        self.ignore_service = IgnoreRuleService(worktree_service, mutation, self)
+        self.ignore_service.finished.connect(self._ignore_finished)
+        self.last_ignore_outcome: IgnoreOutcome | None = None
+        self.snapshot: WorktreeSnapshot | None = None
+        # Annotated as the QWidget it is: its class, the Prepare changes window, lives in the interface, which the domain
+        # does not import even for a type; the session only uses what that window shows and emits.
+        self.window: QWidget | None = None
+        self.draft = ""
+        self.normal_draft = ""
+        self.amend_draft = ""
+        self.amend_head_oid: str | None = None
+        self.amend = False
+        self.message_generation = 0
+        self.amend_generation = 0
+        self.amend_loading = False
+        self.pending_rebase_amend: RebaseSnapshot | None = None
+        self.pending_amend_generation = 0
+        self.pending_message_generation = 0
+        self.amend_rebase_capture: tuple[NativeMetadata | None, ...] | None = None
+        # The merge waiting for its commit, as the last read after a worktree read found it; None when there is none or
+        # it could not be read, in which case the Commit itself explains why.
+        self.merge_in_progress: MergeInProgress | None = None
+        # The merge state of the repository window's banner, read with every worktree read whether Prepare changes is
+        # open or not, and known before that read is published.
+        self.merge_banner_state = MergeBannerState()
+        # The parents of the merge whose prepared message was already offered, so it is offered once per merge: a user
+        # who empties it keeps an empty message.
+        self.merge_message_parent_oids: tuple[str, ...] = ()
+        # The text offered for the merge in progress, to take it back when the merge goes away without the user having
+        # changed it: a later ordinary Commit must not carry the message of a merge that no longer exists.
+        self.merge_message_offered = ""
+        self.generation = 0
+        self.configuration_generation = 0
+        self.selection_generation = 0
+        self.refresh_active = False
+        self.refresh_queued = False
+        # The queue level of the follow-up read asked while another read or a write was running: the most urgent of the
+        # requests it merges, and nothing when no follow-up is waiting.
+        self.queued_refresh_priority: ProcessPriority | None = None
+        self.explicit_refresh = False
+        # A window that has just started showing this worktree has no count yet. A read that finds the state this
+        # session already had tells nobody, so the next read that publishes must announce its result anyway.
+        self.announce_requested = False
+        self.probe_active = False
+        self.last_outcome: MutationOutcome | None = None
+        self.diagnostic = None
+        # The diagnostic of a Commit whose result needs attention, kept by identity: the status bar draws it as a
+        # warning only while it is the diagnostic shown, so any other diagnostic written later gets the ordinary look
+        # without every place that writes one having to say so.
+        self.warning_diagnostic: PreparedDiagnostic | None = None
+        # The diagnostics of the kept results (last file, commit, trash and ignore outcomes) the user has already read
+        # by closing the window that showed them, kept by identity: a newer result is a new object, so it counts as unread.
+        self.read_result_diagnostics: tuple[PreparedDiagnostic, ...] = ()
+        self.busy = False
+        self.line_model: RawPatch | None = None
+        # The comparison on screen, as the capture it was read from and the row it describes. Both are set only once an
+        # answer was accepted for the still-selected row, so a newer capture can keep showing it without reading it
+        # again for as long as the data it came from is unchanged.
+        self.preview_snapshot: WorktreeSnapshot | None = None
+        self.preview_entry: LocalEntry | None = None
+        # The automatic refresh only serves a window somebody is looking at, and the window activation filter is the
+        # only place that knows which window that is: it starts and stops this timer through set_window_active.
+        self.window_active: bool = False
+        # Says whether the pause state deserves a look through Git; the rebase and replay controllers mark each observation they start.
+        self.pause_probe = PauseProbe()
+        self.timer = QTimer(self)
+        self.timer.setInterval(WORKTREE_REFRESH_INTERVAL_MS)
+        self.timer.timeout.connect(self._tick)
+        mutation.finished.connect(self._finished)
+        mutation.repository_operation.context_by_key[self.key] = context
+        mutation.repository_operation.changed.connect(self._show)
+
+    def action_diagnostic(self, action: OperationAction) -> str:
+        """Ask the shared business policy without giving the window reservation authority."""
+        intent = OperationIntent.capture(STAGING_AVAILABILITY_OPERATION_ID, self.context, self.git_filename, action=action)
+        return self.mutation.repository_operation.availability_diagnostic(intent)
+
+    def open(self) -> QWidget | None:
+        """Reuse the live staging window and reject contexts without a working tree."""
+        if self.context.is_bare or self.context.worktree_dir is None:
+            return None
+        self._window_destroyed()
+        if self.window is None:
+            self.window = self.window_factory(self.context)
+            self.window.stage_requested.connect(self.stage)
+            self.window.commit_requested.connect(self.commit)
+            self.window.commit_push_requested.connect(self.commit_push)
+            self.window.amend_checkbox.setChecked(self.amend)
+            self.window.amend_changed.connect(self.set_amend)
+            self.window.unstage_requested.connect(self.unstage)
+            self.window.refresh_requested.connect(lambda: self.refresh(explicit=True))
+            self.window.entry_selected.connect(self.select)
+            self.window.selection_cleared.connect(self.clear_selection)
+            self.window.line_menu.stage_requested.connect(self.stage_lines)
+            self.window.line_menu.reset_requested.connect(self.reset_lines)
+            self.window.file_menu.requested.connect(self.reset_file)
+            self.window.file_menu.delete_requested.connect(self.delete_file)
+            self.window.file_menu.ignore_requested.connect(self.add_ignore)
+            self.window.file_menu.action_requested.connect(self.consult)
+            self.window.load_message(self.draft)
+            self.window.message_edit.textChanged.connect(self._draft_changed)
+            self.window.closed.connect(self._closed)
+            self.window.destroyed.connect(self._window_destroyed)
+            self.window_opened.emit(self.window)
+        self.window.show()
+        self.window.raise_()
+        self.window.activateWindow()
+        self._show()
+        self.refresh()
+        return self.window
+
+    def _draft_changed(self) -> None:
+        """Retain exact editor text in the worktree's application-lifetime session."""
+        if self.window is not None:
+            self.draft = self.window.message_edit.toPlainText()
+            self.message_generation += 1
+            if self.amend:
+                self.amend_draft = self.draft
+            else:
+                self.normal_draft = self.draft
+            self.draft_changed.emit()
+
+    def request_rebase_amend(self, state: RebaseSnapshot) -> None:
+        """Wait for a new worktree read before selecting the captured edit commit."""
+        if self.busy or state.key != self.key or not state.fresh or state.state != "edit":
+            return
+        self.pending_rebase_amend = state
+        self.pending_amend_generation = self.generation + 1
+        self.pending_message_generation = self.message_generation
+        self.amend_generation += 1
+        self.amend_head_oid = None
+        self.amend_loading = True
+        try:
+            self.amend_rebase_capture = native_rebase_capture(self.context)
+        except (OSError, ValueError) as error:
+            self._refuse_rebase_amend(str(error))
+            return
+        self.refresh(explicit=True)
+
+    def _refuse_rebase_amend(self, reason: str) -> None:
+        """Invalidate only the pending amend authority while preserving the user's text."""
+        self.pending_rebase_amend = None
+        self.amend_loading = False
+        self.amend_head_oid = None
+        self.diagnostic = Diagnostic("Amend", self.context.repository_dir, self.git_filename, [], reason).prepare()
+        self._show()
+
+    def _load_pending_amend(self, generation: int) -> None:
+        """Reject a replaced pause and load only the requested fresh HEAD message.
+
+        The pause is read through the application's rebase service, the same observer every window uses: a read already
+        running can answer only if it started after this request, otherwise a newer read is made.
+        """
+        previous = self.pending_rebase_amend
+        snapshot = self.snapshot
+        if previous is None or generation < self.pending_amend_generation or self.refresh_queued:
+            return
+        self.pending_rebase_amend = None
+        if self.rebase_service is None:
+            self._refuse_rebase_amend("The rebase state cannot be read here. Refresh the repository before amending.")
+            return
+        amend_generation = self.amend_generation
+        message_generation = self.pending_message_generation
+        git_filename = self.git_filename
+
+        def current() -> bool:
+            """Answer only the Amend request still waiting in this open session, for the same Git."""
+            return isValid(self) and amend_generation == self.amend_generation and git_filename == self.git_filename
+
+        def complete(state: RebaseSnapshot) -> None:
+            """Bind the message request to the same native edit instruction and HEAD."""
+            if not current():
+                return
+            if message_generation != self.message_generation:
+                self._refuse_rebase_amend("The message changed while refreshing. Your text is preserved; select Amend commit again to reload.")
+                return
+            if not state.fresh:
+                self._refuse_rebase_amend("The rebase state could not be read. Refresh the rebase before amending.")
+                return
+            if (state.state != "edit" or state.identity != previous.identity or state.current_step != previous.current_step or state.head_oid != previous.head_oid
+                    or snapshot is None or not snapshot.fresh or snapshot.head_oid != previous.head_oid
+                    or self.snapshot is None or not self.snapshot.fresh or self.snapshot.head_oid != previous.head_oid):
+                self._refuse_rebase_amend("The edit commit changed. Refresh the rebase before amending.")
+                return
+            self.set_amend(True, reload=True)
+
+        self.rebase_service.observe(self.context, git_filename, is_current=current, callback=complete)
+
+    def set_amend(self, enabled: bool, *, reload: bool = False) -> None:
+        """Load HEAD on every new Amend selection without overwriting typing during the read."""
+        if self.busy or enabled == self.amend and not reload:
+            return
+        reason = self.action_diagnostic(OperationAction.AMEND) if enabled else ""
+        if reason:
+            if reload:
+                self.amend_loading = False
+            self.diagnostic = Diagnostic("Amend", self.context.repository_dir, self.git_filename, [], reason).prepare()
+            if self.window is not None:
+                with QSignalBlocker(self.window.amend_checkbox):
+                    self.window.amend_checkbox.setChecked(self.amend)
+            self._show()
+            return
+        self.amend = enabled
+        if not reload:
+            self.pending_rebase_amend = None
+            self.amend_rebase_capture = None
+        self.amend_generation += 1
+        generation = self.amend_generation
+        self.amend_head_oid = None
+        self.amend_loading = enabled
+        if not enabled:
+            self._set_message(self.normal_draft)
+            self._show()
+            return
+        snapshot = self.snapshot
+        if snapshot is None or not snapshot.fresh or snapshot.head_oid is None:
+            self.amend_loading = False
+            self.diagnostic = Diagnostic("Amend", self.context.repository_dir, self.git_filename, [], "There is no current HEAD message; Refresh first").prepare()
+            self._show()
+            return
+        message_generation = self.message_generation
+
+        def complete(value: tuple[str, str] | None, error: Exception | None) -> None:
+            """Apply only the message belonging to the still-selected mode, HEAD and editor generation."""
+            if not self.amend or generation != self.amend_generation:
+                return
+            self.amend_loading = False
+            if message_generation != self.message_generation:
+                error = ValueError("The message was edited while loading HEAD. Your text is preserved; uncheck and check Amend to reload")
+            elif self.snapshot is None or not self.snapshot.fresh or self.snapshot.head_oid != snapshot.head_oid:
+                error = ValueError("HEAD changed; Refresh and load Amend again")
+            if self.amend_rebase_capture is not None:
+                try:
+                    if native_rebase_capture(self.context) != self.amend_rebase_capture:
+                        error = ValueError("The native rebase changed while loading Amend. Refresh before amending.")
+                except (OSError, ValueError) as failure:
+                    error = failure
+            if error is not None:
+                self.diagnostic = Diagnostic("Amend", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+                self._show()
+                return
+            self.amend_head_oid, message = value
+            self.amend_draft = message
+            cause_cleared = self.diagnostic is not None
+            self.diagnostic = None
+            self._set_message(message)
+            self._show()
+            if cause_cleared:
+                # The repository window shows the cause of the session's diagnostic on its Commit button and reads it
+                # again only when the worktree state is published.
+                self.changed.emit()
+
+        self._show()
+        self.worktree_service.run(self.context, self.git_filename, self.commit_service.read_amend_message(snapshot), complete)
+
+    def _set_message(self, message: str) -> None:
+        """Replace displayed text without turning a programmatic load into a user edit.
+
+        Publishes the replaced draft, not the worktree state.
+        """
+        self.draft = message
+        if self.window is not None:
+            with QSignalBlocker(self.window.message_edit):
+                self.window.load_message(message)
+        self.draft_changed.emit()
+
+    def _closed(self) -> None:
+        """Detach the closed view while preserving its draft in the shared session, and forget the result it showed.
+
+        The comparison and its line model belonged to the view, so no line action can outlive it. Closing the window
+        counts as having read the result of the last action (Commit, Amend, Move to Trash, ignore rules, staging, Reset,
+        file actions): reopened, the window shows the present state, so an old result is never taken for a new
+        problem; the result stays in the --log file. A diagnostic of the worktree state (a failed read, a recovery)
+        is still true and stays until a successful read, and nothing is forgotten while a write runs. The repository
+        window shows the cause of the session's diagnostic on its Commit button, so the state is published once when
+        a result was forgotten, and not at all otherwise.
+        """
+        self.selection_generation += 1
+        self._forget_preview()
+        if self.amend_loading or self.pending_rebase_amend is not None:
+            self.amend_generation += 1
+            self.pending_rebase_amend = None
+            self.amend_loading = False
+            self.amend_head_oid = None
+        self.window = None
+        if self.busy:
+            return
+        self.read_result_diagnostics = tuple(self._kept_result_diagnostics())
+        if self.diagnostic is None or self.diagnostic.operation in STATE_DIAGNOSTIC_OPERATION_SET:
+            return
+        self.diagnostic = None
+        self.warning_diagnostic = None
+        self.changed.emit()
+
+    def _kept_result_diagnostics(self) -> list[PreparedDiagnostic]:
+        """Answer the diagnostics of the results the session keeps beyond its window: the last file, commit, trash and ignore outcomes."""
+        diagnostics: list[PreparedDiagnostic] = []
+        for outcome in (self.last_outcome, self.last_commit_outcome, self.last_trash_outcome, self.last_ignore_outcome):
+            if outcome is not None and outcome.diagnostic is not None:
+                diagnostics.append(outcome.diagnostic)
+        return diagnostics
+
+    def _unread_result_kept(self) -> bool:
+        """Tell whether a kept result has a diagnostic the user has not read yet by closing the window."""
+        for diagnostic in self._kept_result_diagnostics():
+            if not any(diagnostic is read_diagnostic for read_diagnostic in self.read_result_diagnostics):
+                return True
+        return False
+
+    def _window_destroyed(self, *arguments: object) -> None:
+        """Drop a native-deleted widget without discarding its session-owned draft or result."""
+        if self.window is not None and not isValid(self.window):
+            self._closed()
+
+    def commit(self) -> None:
+        """Capture one explicit commit with the still-current HEAD loaded for Amend.
+
+        commit_submitted tells that this click sent the captured request, just before the commit service receives it,
+        so a refusal the service reports at once still comes after it.
+        """
+        if self.busy or self.amend_loading or self.pending_rebase_amend is not None or self.snapshot is None or not self.snapshot.fresh:
+            return
+        if self.amend and (self.amend_head_oid is None or self.amend_head_oid != self.snapshot.head_oid):
+            self.diagnostic = Diagnostic("Amend", self.context.repository_dir, self.git_filename, [], "HEAD is not the loaded Amend commit; Refresh and load Amend again").prepare()
+            self._show()
+            return
+        request = CommitRequest.capture(self.snapshot, self.draft, self.amend)
+        if self.amend and self.amend_rebase_capture is not None:
+            request = replace(request, rebase_capture=self.amend_rebase_capture)
+        self.active_commit_request = request
+        self.active_commit_action = OperationAction.AMEND if request.amend else OperationAction.COMMIT
+        self.busy = True
+        self.last_commit_outcome = None
+        self.diagnostic = None
+        self.warning_diagnostic = None
+        self._show()
+        self.commit_submitted.emit(request)
+        self.commit_service.submit(request)
+
+    def commit_push(self) -> None:
+        """Reserve the UI immediately and capture one request before asynchronous routing reads.
+
+        commit_submitted tells that this click captured the request, as for Commit, just before the routing reads start.
+        """
+        if self.busy or self.window is None or not self.window.commit_push_button.isEnabled() or self.snapshot is None:
+            return
+        if self.amend and (self.amend_head_oid is None or self.amend_head_oid != self.snapshot.head_oid):
+            return
+        request = CommitRequest.capture(self.snapshot, self.draft, self.amend)
+        self.pending_commit_push_request = request
+        self.active_commit_request = request
+        self.active_commit_action = OperationAction.AMEND if request.amend else OperationAction.COMMIT
+        self.busy = True
+        self.last_commit_outcome = None
+        self.diagnostic = None
+        self.warning_diagnostic = None
+        self._show()
+        self.commit_submitted.emit(request)
+        self.commit_push_requested.emit(self, request)
+
+    def finish_commit_action(self, operation_id: str) -> None:
+        """Clear local progress only when the completed request still owns its presentation."""
+        if self.active_commit_request is None or self.active_commit_request.operation_id != operation_id:
+            return
+        self.active_commit_request = None
+        self.active_commit_action = None
+
+    def _commit_finished(self, outcome: CommitOutcome) -> None:
+        """Empty the draft once a commit exists, keep it otherwise, and close only after Git's actual result is verified.
+
+        The draft, Amend and a waiting merge are cleared as soon as the read after the write proves a new commit, even
+        when the result is a warning: committing the same message again would add a second commit. The window closes
+        on success only; a warning or a failure keeps it open, reopened if needed. When no commit was proven, the
+        status unknown included, the draft stays for another try.
+
+        A successful commit shows the complete read the commit service made after writing and does not read the
+        worktree again for it. A failure, a missing or stale read, or a refresh requested meanwhile still reads again.
+        """
+        if self.active_commit_request is not None and self.active_commit_request.operation_id != outcome.operation_id:
+            return
+        self.finish_commit_action(outcome.operation_id)
+        self.last_commit_outcome = outcome
+        self.busy = False
+        self.diagnostic = outcome.diagnostic
+        self.warning_diagnostic = outcome.diagnostic if outcome.status == OperationStatus.PARTIAL else None
+        if outcome.after is not None:
+            self.snapshot = outcome.after.snapshot
+            if self.snapshot.git_filename != self.git_filename:
+                self.snapshot = replace(self.snapshot, fresh=False)
+        elif self.snapshot is not None:
+            self.snapshot = replace(self.snapshot, fresh=False)
+        if outcome.commit_created or outcome.status == OperationStatus.SUCCESS:
+            self.normal_draft = ""
+            self.amend_draft = ""
+            self.amend = False
+            self.amend_head_oid = None
+            # A new commit concludes any merge that was waiting; the next read says whether another one exists.
+            self.merge_in_progress = None
+            self.merge_banner_state = MergeBannerState()
+            self.merge_message_parent_oids = ()
+            self.merge_message_offered = ""
+            self._set_message("")
+        if outcome.status == OperationStatus.SUCCESS:
+            self._show()
+            if self.window is not None:
+                self.window.close()
+        self._show()
+        if outcome.status != OperationStatus.SUCCESS and self.window is None:
+            self.open()
+        self.changed.emit()
+        self.commit_finished.emit(outcome)
+        if outcome.status != OperationStatus.SUCCESS or self.snapshot is None or not self.snapshot.fresh or self.explicit_refresh or self.refresh_active:
+            self.refresh(priority=ProcessPriority.CONTINUATION)
+        else:
+            # The snapshot shown above is the complete read made after the commit: a timer or window request queued
+            # while the commit ran would read exactly the same state again.
+            self.refresh_queued = False
+            self.queued_refresh_priority = None
+
+    def _commit_waiting(self, diagnostic: object) -> None:
+        """Keep delayed native writes visible while their reservation and draft remain owned."""
+        self.diagnostic = diagnostic
+        self._show()
+
+    def set_git_filename(self, git_filename: str) -> None:
+        """Change future operations while preserving captured active sequences and session drafts."""
+        if self.git_filename == git_filename:
+            return
+        self.git_filename = git_filename
+        self.configuration_generation += 1
+        self.amend_generation += 1
+        self.pending_rebase_amend = None
+        self.amend_rebase_capture = None
+        self.amend_loading = False
+        self.amend_head_oid = None
+        self.invalidate_conversion()
+
+    def invalidate_conversion(self) -> None:
+        """Discard line candidates and reread real Git state after conversion settings change."""
+        self._forget_preview()
+        self.selection_generation += 1
+        if self.snapshot is not None:
+            self.snapshot = replace(self.snapshot, fresh=False)
+        self._show()
+        self.refresh()
+
+    def set_window_active(self, active: bool) -> None:
+        """Start or stop the automatic refresh when a window of this worktree gains or loses activation, and read once on return.
+
+        Coming back to the window is the moment the displayed state may be stale, so it is also the moment worth one read.
+        """
+        if self.window_active == active:
+            return
+        self.window_active = active
+        if not active:
+            self.timer.stop()
+            return
+        if self.worktree_service.runner.closed:
+            return
+        self.timer.start()
+        if self.mutation.repository_operation.owns_worktree(self.key):
+            # The operation checks the repository itself and refreshes when it ends; a read taken in the middle of a
+            # write would only show a passing state.
+            return
+        if self.refresh_active:
+            # The read already in flight will publish the state; a change made while it runs shows at the next period,
+            # and the period has just been restarted.
+            return
+        self.refresh()
+
+    def _tick(self) -> None:
+        """Read the worktree periodically for an active window, through the probe when a complete snapshot can serve as the comparison."""
+        if not self.window_active:
+            # This attribute can be written directly, so the timer must never outlive the activation it serves.
+            self.timer.stop()
+            return
+        if self.mutation.repository_operation.owns_worktree(self.key):
+            # The operation checks the repository itself and refreshes when it ends; a read taken in the middle of a
+            # write would only show a passing state.
+            return
+        if self.refresh_active or self.probe_active:
+            # The read in flight is this period's read; asking for another one would only queue a duplicate.
+            return
+        snapshot = self.snapshot
+        if (snapshot is None or not snapshot.fresh or snapshot.probe is None or snapshot.git_filename != self.git_filename or self.busy
+                or self.refresh_queued or self.explicit_refresh or self.context.is_bare or self.worktree_service.runner.closed):
+            self.refresh(priority=ProcessPriority.BACKGROUND)
+            return
+        self.probe_active = True
+        generation = self.generation
+        self.worktree_service.run(self.context, self.git_filename, self.worktree_service.probe(snapshot),
+                                  lambda probe, error: self._probe_finished(snapshot, generation, probe, error), priority=ProcessPriority.BACKGROUND)
+
+    def _probe_finished(self, snapshot: WorktreeSnapshot, generation: int, probe: WorktreeProbe | None, error: Exception | None) -> None:
+        """Publish nothing while the displayed state still holds, and read everything again in every other case."""
+        if not isValid(self):
+            return
+        if not self.probe_active:
+            return
+        self.probe_active = False
+        if (generation != self.generation or self.snapshot is not snapshot or self.refresh_active or self.busy or not self.window_active
+                or self.mutation.repository_operation.owns_worktree(self.key)):
+            # A complete read has started or will start on its own: the end of an operation, or the return to the window.
+            return
+        # The probe never publishes a state itself; it only says whether one must be read again.
+        if error is not None or probe != snapshot.probe:
+            self.refresh(priority=ProcessPriority.BACKGROUND)
+            return
+        if self._pause_observation_due():
+            self.pause_observation_requested.emit()
+            self._read_merge_banner_state(generation)
+
+    def _pause_observation_due(self) -> bool:
+        """Tell whether Git's pause state deserves a look although the worktree read has not changed.
+
+        It does when a pause file or a fact of the last status differs from what the last observation that really
+        started covered. Nothing is recorded here.
+        """
+        return self.pause_probe.observation_due(self._displayed_worktree_probe())
+
+    def _displayed_worktree_probe(self) -> WorktreeProbe | None:
+        """Answer the status facts of the snapshot on screen, even when an explicit read has just marked it stale."""
+        if self.snapshot is None:
+            return None
+        return self.snapshot.probe
+
+    def passive_observation_source(self) -> PassiveObservationSource | None:
+        """Answer what the automatic refresh has just read, for the observation that makes the banner follow the pause.
+
+        Nothing is answered unless the state on screen is fresh and at rest: the observation then reads everything through
+        Git. An operation never reads this.
+        """
+        snapshot = self.snapshot
+        if snapshot is None or not snapshot.fresh or snapshot.probe is None:
+            return None
+        if snapshot.head_oid != snapshot.probe.head_oid or snapshot.git_filename != self.git_filename:
+            return None
+        if self.refresh_active or self.refresh_queued or self.explicit_refresh or self.busy:
+            return None
+        filename_by_git_path = self.pause_probe.filename_by_git_path()
+        if filename_by_git_path is None:
+            return None
+        try:
+            return passive_observation_source(snapshot.probe, filename_by_git_path)
+        except ValueError:
+            # A status record that cannot be taken apart is not trusted: the observation reads it through Git instead.
+            return None
+
+    def mark_pause_observed(self, observation: str) -> None:
+        """Note that an observation of the pause state starts now.
+
+        The signature is taken before the observation reads anything, so whatever moves afterwards is looked at again.
+        """
+        # An explicit read has just marked the snapshot stale, but its facts are still the ones the screen shows.
+        self.pause_probe.mark_observed(observation, self._displayed_worktree_probe())
+
+    def refresh(self, *, explicit: bool = False, priority: ProcessPriority = ProcessPriority.USER, announce: bool = False) -> None:
+        """Allow one active read and at most one follow-up, without racing an index write.
+
+        The first read of the session starts by asking Git where the pause state files are. The priority is where the
+        read waits in the process queue: the user's own request by default, and always for an explicit Refresh. A
+        follow-up merging several requests waits at the most urgent of their levels, so a later background request
+        never lowers a user's.
+
+        announce is for a window that starts showing this worktree with an unknown count: the next read that publishes
+        tells the subscribers of changed about its result even when it matches the state already held. The session
+        outlives its windows, so a worktree shown again usually reads exactly what it had, and would otherwise stay
+        unknown in that window until something in it changes.
+        """
+        if self.worktree_service.runner.closed:
+            self.timer.stop()
+            self.refresh_queued = False
+            self.queued_refresh_priority = None
+            return
+        if announce:
+            self.announce_requested = True
+        if explicit:
+            priority = ProcessPriority.USER
+            self.explicit_refresh = True
+            if self.snapshot is not None:
+                self.snapshot = replace(self.snapshot, fresh=False)
+            self._show()
+            self.changed.emit()
+        if self.busy or self.refresh_active:
+            self._queue_refresh(priority)
+            return
+        if self.context.is_bare:
+            return
+        if self.queued_refresh_priority is not None:
+            priority = min(priority, self.queued_refresh_priority)
+        # This new read already includes requests received before it started.
+        # Keep the queue only for requests that arrive while this read is active.
+        self.refresh_queued = False
+        self.queued_refresh_priority = None
+        self.generation += 1
+        generation = self.generation
+        configuration_generation = self.configuration_generation
+        self.refresh_active = True
+
+        def complete(snapshot: WorktreeSnapshot | None, error: Exception | None) -> None:
+            """Publish only the latest requested generation and preserve failures explicitly."""
+            if generation != self.generation:
+                return
+            self.refresh_active = False
+            if configuration_generation != self.configuration_generation:
+                self._queue_refresh(priority)
+                self._start_queued_refresh()
+                return
+            if self.busy:
+                self._queue_refresh(priority)
+                return
+            explicit_finished = self.explicit_refresh and not self.refresh_queued
+            if not self.refresh_queued:
+                self.explicit_refresh = False
+            previous = self.snapshot
+            previous_cause = self.diagnostic.cause if self.diagnostic is not None else ""
+            merge_changed = False
+            if error is not None:
+                self.diagnostic = Diagnostic(READ_CHANGES_OPERATION, self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+                if self.snapshot is not None:
+                    self.snapshot = replace(self.snapshot, fresh=False, diagnostic=self.diagnostic)
+            else:
+                if snapshot.merge_banner_state is not None:
+                    merge_changed = snapshot.merge_banner_state != self.merge_banner_state
+                    self._apply_merge_banner_state(snapshot.merge_banner_state)
+                self.snapshot = snapshot
+                # Recovery can publish an outcome synchronously; queue its reread behind this callback.
+                self.refresh_active = True
+                try:
+                    recovery = self.mutation.recover(self.context, snapshot.index_filename)
+                finally:
+                    self.refresh_active = False
+                if recovery:
+                    self.diagnostic = Diagnostic(RECOVER_CHANGES_OPERATION, self.context.repository_dir, self.git_filename, [], recovery).prepare()
+                elif (self.diagnostic is None or self.diagnostic.operation in STATE_DIAGNOSTIC_OPERATION_SET) and not self._unread_result_kept():
+                    self.diagnostic = None
+            if self.explicit_refresh and self.snapshot is not None:
+                self.snapshot = replace(self.snapshot, fresh=False)
+            # Background reads must not invalidate open menus or pending history lookups when only the read number changed.
+            if previous is not None and self.snapshot is not None and replace(self.snapshot, generation=previous.generation) == previous:
+                self.snapshot = previous
+            content_changed = previous is None or self.snapshot is not previous
+            cause_changed = (self.diagnostic.cause if self.diagnostic is not None else "") != previous_cause
+            observation_due = self._pause_observation_due()
+            if content_changed:
+                self.selection_generation += 1
+            self._show()
+            if content_changed:
+                self._reconcile_selection()
+            # Subscribers read the snapshot, the diagnostic cause and the end of a read the user asked for (a Rescan
+            # waits for this signal to finish). An identical background read tells them nothing, and every signal
+            # starts Git observations again; only a window that has just started showing this worktree, with no count
+            # yet, needs to hear it.
+            announced = self.announce_requested
+            self.announce_requested = False
+            if content_changed and head_moved_between(previous, self.snapshot):
+                # Told first: the graph refresh this starts gives the windows a new generation, and a pause observation
+                # started before it by the signals below would then be dropped as out of date.
+                self.head_moved.emit()
+            if content_changed or cause_changed or merge_changed or explicit_finished or announced:
+                self.changed.emit()
+            elif observation_due:
+                self.pause_observation_requested.emit()
+            if self.refresh_queued:
+                self._start_queued_refresh()
+            else:
+                self._load_pending_amend(generation)
+
+        def start_read() -> None:
+            """Start the worktree read of this refresh, compared with the snapshot on screen; it also reads the merge state."""
+            self.worktree_service.read(self.context, self.git_filename, generation, complete, previous=self.snapshot, priority=priority)
+
+        if self.pause_probe.filenames is not None:
+            start_read()
+            return
+
+        # Git locates the pause state files once per session, before the first read, so the first observation marked
+        # as started already has a complete signature to be compared with.
+        def paths_read(filenames: tuple[str, ...] | None, error: Exception | None) -> None:
+            """Keep the located paths and go on with the read; a failure only makes every period ask for an observation."""
+            if not isValid(self):
+                return
+            if self.worktree_service.runner.closed or generation != self.generation:
+                self.refresh_active = False
+                return
+            if error is None:
+                self.pause_probe.filenames = filenames
+            start_read()
+
+        self.worktree_service.run(self.context, self.git_filename, read_pause_probe_filenames(self.context), paths_read, priority=priority)
+
+    def _apply_merge_banner_state(self, state: MergeBannerState) -> None:
+        """Keep the merge state a read found, and for an open Prepare changes allow the merge's Commit and offer Git's message.
+
+        The message is offered once per merge, in an empty normal draft: a message the user wrote, an Amend message and
+        a write or Amend load in progress are never replaced. A merge that could not be read offers nothing: the Commit
+        then refuses it with the cause.
+
+        When the merge is gone (aborted, or concluded elsewhere), the offered message is taken back if the user did not
+        change it, whether Prepare changes is open or not, so a later ordinary Commit does not carry it. The merge already
+        offered is forgotten at the same time, Prepare changes open or not, so the same merge done again later, whose
+        merged commit has not moved, offers Git's message again.
+        """
+        self.merge_banner_state = state
+        if state.merge is None and not state.cause:
+            self.merge_message_parent_oids = ()
+            if self.merge_message_offered and not self.busy:
+                if self.normal_draft == self.merge_message_offered:
+                    self.normal_draft = ""
+                    if not self.amend and not self.amend_loading:
+                        self._set_message("")
+                self.merge_message_offered = ""
+        if self.window is None:
+            return
+        self.merge_in_progress = state.merge
+        if self.merge_in_progress is None:
+            self.merge_message_parent_oids = ()
+            return
+        parent_oids = self.merge_in_progress.parent_oids
+        if parent_oids == self.merge_message_parent_oids or self.amend or self.amend_loading or self.busy or self.draft:
+            return
+        self.merge_message_parent_oids = parent_oids
+        text = merge_message_text(self.merge_in_progress.message)
+        if text:
+            self.normal_draft = text
+            self.merge_message_offered = text
+            self._set_message(text)
+
+    def _read_merge_banner_state(self, generation: int) -> None:
+        """Read the merge state again on the file worker, for a pause file that moved while the worktree read did not change.
+
+        A changed state is published as a change of the session; an unchanged one, or an answer that a newer read has
+        overtaken, publishes nothing.
+        """
+        if self.context.is_bare or self.worktree_service.runner.closed:
+            return
+        git_dir = self.context.git_dir
+
+        def sequence() -> Generator:
+            """Read the merge files in the worker that runs the session's file reads."""
+            return (yield FileTask(lambda: read_merge_banner_state(git_dir)))
+
+        def merge_read(state: MergeBannerState | None, error: Exception | None) -> None:
+            """Publish the merge state when it changed and no newer read has started."""
+            if not isValid(self) or error is not None or generation != self.generation or self.refresh_active or state == self.merge_banner_state:
+                return
+            self._apply_merge_banner_state(state)
+            self._show()
+            self.changed.emit()
+
+        self.worktree_service.run(self.context, self.git_filename, sequence(), merge_read, priority=ProcessPriority.BACKGROUND)
+
+    def _queue_refresh(self, priority: ProcessPriority) -> None:
+        """Keep one follow-up read at the most urgent level of the requests it merges."""
+        self.refresh_queued = True
+        self.queued_refresh_priority = priority if self.queued_refresh_priority is None else min(self.queued_refresh_priority, priority)
+
+    def _start_queued_refresh(self) -> None:
+        """Start the waiting follow-up read on the next turn of the event loop.
+
+        The follow-up stays queued until that read really starts: in the turn between the two reads the session is not at
+        rest, so nothing that waits for a settled state acts on the result about to be replaced.
+        """
+        QTimer.singleShot(0, self, self._run_queued_refresh)
+
+    def _run_queued_refresh(self) -> None:
+        """Start the follow-up read still queued, at the most urgent level of the requests it merges.
+
+        Nothing starts when the queue was emptied meanwhile: a read started since then already covers it, or the result
+        shown made it useless, or the session was closed.
+        """
+        if not self.refresh_queued:
+            return
+        priority = self.queued_refresh_priority if self.queued_refresh_priority is not None else ProcessPriority.USER
+        self.refresh(priority=priority)
+
+    def _forget_preview(self) -> None:
+        """Drop the identity of the comparison on screen and its line model, so nothing can keep or act on them."""
+        self.preview_snapshot = None
+        self.preview_entry = None
+        self.line_model = None
+
+    def _preview_still_valid(self, entry: LocalEntry) -> bool:
+        """Tell whether the finished comparison on screen still describes the selected row of the snapshot now shown.
+
+        The row must be the very one that was read (side, paths, status, modes and object IDs), in a fresh capture of
+        the same worktree and Git, with the same conversion rules. The unstaged side also needs the same working bytes,
+        the staged side the same HEAD. Equal labels prove nothing: a file edited again keeps its status line. A
+        submodule is always read again, because its checkout moves without changing the parent's row.
+        """
+        read_from, current = self.preview_snapshot, self.snapshot
+        if read_from is None or current is None or not current.fresh or self.preview_entry != entry or entry.is_gitlink:
+            return False
+        if self.line_model is not None and (self.line_model.snapshot is not read_from or self.line_model.entry != entry):
+            return False
+        if current.key != read_from.key or current.git_filename != read_from.git_filename or current.git_filename != self.git_filename:
+            return False
+        if current.conversion != read_from.conversion:
+            return False
+        if entry.side == StagingSide.STAGED:
+            return current.head_oid == read_from.head_oid
+        working = current.fingerprint_by_path.get(entry.path)
+        return working is not None and working == read_from.fingerprint_by_path.get(entry.path)
+
+    def _reconcile_selection(self) -> None:
+        """Keep, rebind or read again the comparison of the row still selected once a new state is shown.
+
+        A finished comparison whose data is unchanged stays on screen with its text, cursor and scroll, and its line
+        model is bound to the new snapshot; line intentions captured before keep their old read number and stay
+        refused. Any other selected row is read again once. No selected row clears the comparison and its line model.
+        """
+        if self.window is None:
+            self._forget_preview()
+            return
+        entries = self.window.selected_entries(self.window.unstaged_list) or self.window.selected_entries(self.window.staged_list)
+        if not entries:
+            self._forget_preview()
+            self.window.clear_summary()
+            self.window.diff_view.clear()
+            self.window.line_menu.bind(None)
+            return
+        entry = next(iter(entries))
+        if not self._preview_still_valid(entry):
+            self.select(entry)
+            return
+        self.preview_snapshot = self.snapshot
+        if self.line_model is not None:
+            self.line_model = replace(self.line_model, snapshot=self.snapshot, entry=entry)
+            self.window.line_menu.bind(self.line_model)
+
+    def _publish_operation_snapshot(self, snapshot: WorktreeSnapshot | None) -> tuple[bool, bool]:
+        """Show the complete read an operation made after writing; answer whether it was shown and whether it spares another read.
+
+        A read of another worktree never becomes this session's state. A read made with another Git is shown as not up
+        to date. A missing or stale read, a refresh the user asked for, or a read already running all leave the next
+        state to a new worktree read. A shown read is followed by the selection reconciliation, which keeps, rebinds or
+        drops the comparison on screen and its line model.
+        """
+        if snapshot is None or snapshot.key != self.key:
+            if self.snapshot is not None:
+                self.snapshot = replace(self.snapshot, fresh=False)
+            return False, False
+        shown = snapshot if snapshot.git_filename == self.git_filename else replace(snapshot, fresh=False)
+        changed = shown is not self.snapshot
+        self.snapshot = shown
+        if changed:
+            # Rows and pending previews of the previous state no longer describe the files.
+            self.selection_generation += 1
+        return changed, shown.fresh and not self.explicit_refresh and not self.refresh_active
+
+    def _show(self) -> None:
+        """Publish current preparation and message availability to the live view."""
+        self._window_destroyed()
+        if self.window is not None:
+            with QSignalBlocker(self.window.amend_checkbox):
+                self.window.amend_checkbox.setChecked(self.amend)
+            # The capture reads the native rebase and replay files on the thread of the interface and does not depend on the action.
+            intent = OperationIntent.capture(STAGING_AVAILABILITY_OPERATION_ID, self.context, self.git_filename)
+            for action in STAGING_AVAILABILITY_ACTIONS:
+                availability = self.mutation.repository_operation.availability(replace(intent, action=action))
+                own_commit = self.active_commit_request is not None and availability.owner_operation_id == self.active_commit_request.operation_id
+                self.window.reason_by_action[action] = "" if own_commit else availability.reason
+            self.window.merge_in_progress = self.merge_in_progress is not None
+            self.window.amend_ready = not self.amend_loading and self.amend_head_oid is not None and self.snapshot is not None and self.amend_head_oid == self.snapshot.head_oid
+            self.window.show_snapshot(self.snapshot, self.busy, self.diagnostic, warning=self.diagnostic is not None and self.diagnostic is self.warning_diagnostic,
+                                      commit_action=self.active_commit_action)
+            if self.explicit_refresh and not self.busy:
+                self.window.status_label.setText("Reading changes…")
+
+    def select(self, entry: LocalEntry) -> None:
+        """Read a selected comparison without allowing a late response to replace a newer one.
+
+        The comparison becomes the one on screen, with its capture and row, only when its answer is accepted.
+        """
+        self.selection_generation += 1
+        generation = self.selection_generation
+        snapshot = self.snapshot
+        self._forget_preview()
+        if snapshot is None or entry not in snapshot.entries or self.window is None:
+            return
+        self.window.diff_view.clear()
+        self.window.clear_summary()
+        self.window.line_menu.bind(None)
+
+        if entry.is_gitlink:
+            window, context = self.window, self.context
+            self.window.show_summary_status("Reading submodule changes…")
+
+            def summary_complete(summary: SubmoduleSummary | None, error: Exception | None) -> None:
+                """Publish only to the same live repository, snapshot and selected side."""
+                if (generation != self.selection_generation or self.window is not window or window.close_requested
+                        or self.context is not context or self.snapshot is not snapshot):
+                    return
+                if error is not None or summary is None:
+                    window.show_summary_status("Differences could not be read. Review the details and refresh the repository.\n\n" + str(error))
+                    return
+                if summary.side != entry.side or summary.reference.path != entry.path or summary.reference.parent_dir != context.repository_dir:
+                    return
+                expected_source = entry.old_blob_oid if entry.old_blob_oid and entry.old_blob_oid.strip("0") else None
+                expected_target = entry.new_blob_oid if entry.new_blob_oid and entry.new_blob_oid.strip("0") else None
+                _fingerprint, _separator, expected_checkout = snapshot.fingerprint_by_path.get(entry.path, "").rpartition(":")
+                if (summary.reference.parent_head_oid != snapshot.head_oid or summary.source.oid != expected_source
+                        or (entry.side == StagingSide.STAGED and summary.target.oid != expected_target)
+                        or (expected_checkout and expected_checkout != "uninitialized" and summary.reference.checkout_oid != expected_checkout)):
+                    window.show_summary_status("The submodule changed since it was read. Refresh the repository and review it before staging again.")
+                    return
+                window.show_summary(summary, entry)
+
+            self.submodule_service.compare(context, snapshot.git_filename, entry, summary_complete)
+            return
+
+        def complete(patch: bytes | RawPatch | None, error: Exception | None) -> None:
+            """Route a complete preview only to the selection that requested it."""
+            if generation != self.selection_generation or self.window is None:
+                return
+            if error is not None:
+                self.window.reader_toolbar.status_label.setText("Preview incomplete: " + str(error) + ". Whole-file staging remains available.")
+                if entry.side == StagingSide.UNSTAGED:
+                    self.worktree_service.run(self.context, snapshot.git_filename, self.worktree_service.diff(snapshot, entry), fallback)
+                return
+            self.preview_snapshot = snapshot
+            self.preview_entry = entry
+            if isinstance(patch, RawPatch):
+                self.line_model = patch
+                self.window.show_comparison(patch.patch, entry)
+                self.window.line_menu.bind(patch)
+            else:
+                self.window.show_comparison(patch, entry)
+
+        def fallback(patch: bytes | None, error: Exception | None) -> None:
+            """Keep whole-file previews readable when partial transformations are unavailable."""
+            if generation == self.selection_generation and self.window is not None and error is None:
+                self.window.show_comparison(patch, entry, complete=False)
+
+        sequence = read_partial(snapshot, entry) if entry.side == StagingSide.UNSTAGED and not entry.is_gitlink else self.worktree_service.diff(snapshot, entry)
+        self.worktree_service.run(self.context, snapshot.git_filename, sequence, complete)
+
+    def clear_selection(self) -> None:
+        """Invalidate delayed previews and line actions when no visible file remains selected."""
+        self.selection_generation += 1
+        self._forget_preview()
+
+    def stage_lines(self, selection: RawLineSelection | None) -> None:
+        """Recheck direct calls against the active complete model before reserving a write."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.line_model is None or selection is None:
+            return
+        try:
+            self.line_model.selected(selection)
+            self.mutation._validate(self.line_model.snapshot, self.snapshot, (selection.path,))
+        except ValueError as error:
+            self.diagnostic = Diagnostic("Stage selected lines", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+            self.refresh()
+            return
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+        self.mutation.stage_lines(self.line_model, selection)
+
+    def reset_lines(self, selection: RawLineSelection | None) -> None:
+        """Apply the selected line reset directly while rejecting stale content or a closed source view."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.line_model is None or selection is None or self.window is None:
+            return
+        try:
+            self.line_model.selected(selection)
+            self.mutation._validate(self.line_model.snapshot, self.snapshot, (selection.path,))
+        except ValueError as error:
+            self.diagnostic = Diagnostic("Reset selected lines", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+            self.refresh()
+            return
+        window = self.window
+        generation = self.selection_generation
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+
+        def complete(prepared: PreparedLineReset | None, error: Exception | None) -> None:
+            """Publish the computed candidate only while its original selection remains current."""
+            if error is not None:
+                self.busy = False
+                self.diagnostic = Diagnostic("Reset selected lines", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+                self._show()
+                self.refresh()
+                return
+            if self._confirmation_is_current(window, generation):
+                self.mutation.reset_lines(prepared)
+                return
+            try:
+                self.mutation.cancel_reset_lines(prepared)
+            except (OSError, ValueError) as failure:
+                self.diagnostic = Diagnostic("Cancel reset", self.context.repository_dir, self.git_filename, [], str(failure)).prepare()
+            self._finish_cancelled_confirmation(window)
+
+        self.mutation.prepare_reset_lines(self.line_model, selection, complete)
+
+    def _confirmation_is_current(self, window: QWidget, generation: int) -> bool:
+        """Reject late confirmation answers after selection changes or a requested closure."""
+        return self.window is window and generation == self.selection_generation and not window.close_requested
+
+    def _finish_cancelled_confirmation(self, window: QWidget) -> None:
+        """Release the busy UI after cancellation and honor a closure before any write starts."""
+        self.busy = False
+        self._show()
+        if self.window is window and window.close_requested:
+            window.close()
+        self.changed.emit()
+        self.refresh()
+
+    def stage(self, entries: tuple[LocalEntry, ...]) -> None:
+        """Validate session capability and selection before submitting an irreversible index result."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.context.is_bare:
+            return
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+        self.mutation.stage_file(self.snapshot, entries)
+
+    def reset_file(self, entries: tuple[LocalEntry, ...]) -> None:
+        """Reset captured files in their original live view, confirming only new additions."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.window is None or not entries:
+            return
+        if any(entry not in self.snapshot.entries for entry in entries):
+            self.refresh()
+            return
+        window = self.window
+        generation = self.selection_generation
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+
+        def complete(prepared: ResetCandidate | None, error: Exception | None) -> None:
+            """Recheck the source view before publication and after any new-file confirmation."""
+            if error is not None:
+                self.busy = False
+                self.diagnostic = Diagnostic("Reset", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+                self._show()
+                self.refresh()
+                return
+            needs_confirmation = prepared.snapshot.requires_file_confirmation(tuple(change.path for change in prepared.changes if change.before.exists))
+            accepted = self._confirmation_is_current(window, generation) and (not needs_confirmation or window.file_menu.confirm(prepared))
+            if accepted and self._confirmation_is_current(window, generation):
+                self.mutation.reset_file(prepared)
+                return
+            try:
+                self.mutation.cancel_reset_file(prepared)
+            except (OSError, ValueError) as failure:
+                self.diagnostic = Diagnostic("Cancel Reset", self.context.repository_dir, self.git_filename, [], str(failure)).prepare()
+            self._finish_cancelled_confirmation(window)
+
+        self.mutation.prepare_reset_file(self.snapshot, entries, complete)
+
+    def delete_file(self, entries: tuple[LocalEntry, ...], selected_snapshot: WorktreeSnapshot | None = None) -> None:
+        """Move captured files to Trash directly, confirming batches that include a new addition."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.window is None or not entries:
+            return
+        window = self.window
+        generation = self.selection_generation
+        self.busy = True
+        self.last_trash_outcome = None
+        self._show()
+        self.changed.emit()
+
+        def complete(request: TrashRequest | None, error: Exception | None) -> None:
+            """Require the original live view before moving files or confirming new additions."""
+            if error is not None:
+                self.busy = False
+                self.diagnostic = Diagnostic("Move to Trash", self.context.repository_dir, self.git_filename, [], str(error)).prepare()
+                self._show()
+                self.changed.emit()
+                return
+            needs_confirmation = request.snapshot.requires_file_confirmation(tuple(target.path for target in request.targets))
+            accepted = self._confirmation_is_current(window, generation) and (not needs_confirmation or window.file_menu.confirm_trash(request))
+            if accepted and self._confirmation_is_current(window, generation):
+                self.trash_service.submit(request)
+                return
+            self.trash_service.cancel(request)
+            self._finish_cancelled_confirmation(window)
+
+        self.trash_service.prepare(selected_snapshot or self.snapshot, entries, complete)
+
+    def _trash_finished(self, outcome: TrashOutcome) -> None:
+        """Retain OS results beyond window closure and show the complete read the operation made after moving.
+
+        That read already shows the non-staged Git deletions, after a partial or refused batch too, so the worktree is
+        read again only when the read cannot be used.
+        """
+        self.last_trash_outcome = outcome
+        self.busy = False
+        self.diagnostic = outcome.diagnostic
+        shown, reusable = self._publish_operation_snapshot(outcome.snapshot)
+        if reusable:
+            # A timer or window request queued while the files moved would read exactly the state now shown.
+            self.refresh_queued = False
+            self.queued_refresh_priority = None
+        self._show()
+        if shown:
+            self._reconcile_selection()
+        if outcome.status == OperationStatus.SUCCESS and self.window is not None and self.window.close_requested:
+            self.window.close()
+        reopened = False
+        if outcome.status != OperationStatus.SUCCESS and self.window is None:
+            # Opening the window starts its own worktree read.
+            reopened = self.open() is not None
+        self.changed.emit()
+        if not reusable and not reopened:
+            self.refresh(priority=ProcessPriority.CONTINUATION)
+
+    def add_ignore(self, entries: tuple[LocalEntry, ...], selected_snapshot: WorktreeSnapshot, destination: IgnoreDestination) -> None:
+        """Apply only a captured current Unstaged intention to the named rule destination."""
+        if self.busy or self.window is None or self.window.close_requested or self.snapshot is None or not self.snapshot.fresh:
+            return
+        if selected_snapshot is not self.snapshot or not entries or any(entry not in self.snapshot.entries or entry.side != StagingSide.UNSTAGED for entry in entries):
+            self.refresh()
+            return
+        self.busy = True
+        self.last_ignore_outcome = None
+        self._show()
+        self.ignore_service.submit(selected_snapshot, entries, destination)
+
+    def _local_intention_is_current(self, entries: tuple[LocalEntry, ...], snapshot: WorktreeSnapshot, side_set: frozenset[StagingSide] = UNSTAGED_SIDE_SET) -> bool:
+        """Validate direct handlers as well as menu dispatch against the live worktree read.
+
+        By default only Unstaged entries are accepted; a read-only action passes ``LISTED_SIDE_SET`` so that an entry
+        of either list is accepted.
+        """
+        return (not self.busy and self.window is not None and not self.window.close_requested and self.snapshot is snapshot and snapshot.fresh
+                and not self.context.is_bare and bool(entries) and all(entry in snapshot.entries and entry.side in side_set for entry in entries))
+
+    def stop_tracking(self, entries: tuple[LocalEntry, ...], snapshot: WorktreeSnapshot) -> None:
+        """Confirm cached removal while retaining the exact snapshot and window lifetime."""
+        if not self._local_intention_is_current(entries, snapshot):
+            self.refresh()
+            return
+        if any(entry.old_mode not in ("100644", "100755", "120000") or entry.skip_worktree or entry.conflict_stages for entry in entries):
+            self._consultation_failed("Select tracked ordinary files to stop tracking")
+            return
+        window = self.window
+        generation = self.selection_generation
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+        accepted = window.file_menu.confirm_stop_tracking(entries)
+        if not accepted or not self._confirmation_is_current(window, generation):
+            self._finish_cancelled_confirmation(window)
+            return
+        self.mutation.stop_tracking(snapshot, entries)
+
+    def consult(self, action: FileAction, entries: tuple[LocalEntry, ...], snapshot: WorktreeSnapshot) -> None:
+        """Dispatch captured local-file commands without inventing historical object identities.
+
+        Show in folder and Show in text editor come from both lists, since they only open the working copy or its
+        folder; every other action comes only from the Unstaged list.
+        """
+        side_set = LISTED_SIDE_SET if action in READ_ONLY_FILE_ACTION_SET else UNSTAGED_SIDE_SET
+        if not self._local_intention_is_current(entries, snapshot, side_set=side_set):
+            return
+        if action == FileAction.STAGE:
+            self.stage(entries)
+            return
+        if action == FileAction.STOP_TRACKING:
+            self.stop_tracking(entries, snapshot)
+            return
+        if action in (FileAction.COPY_BASENAME, FileAction.COPY_ABSOLUTE):
+            labels: list[str] = []
+            try:
+                for entry in entries:
+                    filename = worktree_filename(self.context, entry.path)
+                    labels.append(os.path.basename(filename) if action == FileAction.COPY_BASENAME else filename)
+            except ValueError as error:
+                self._consultation_failed(str(error))
+                return
+            QApplication.clipboard().setText("\n".join(labels))
+            if any("\n" in label or "\r" in label for label in labels):
+                self._consultation_failed("Paths copied literally. A filename contains a line break, so displayed lines do not identify separate files.")
+            return
+        if action not in READ_ONLY_FILE_ACTION_SET and action != FileAction.HISTORY:
+            return
+        if len(entries) != 1:
+            self._consultation_failed("Select one file for this action")
+            return
+        entry = next(iter(entries))
+        if action in READ_ONLY_FILE_ACTION_SET:
+            try:
+                file_location(self.context, entry.path, allow_missing=True)
+            except (OSError, ValueError) as error:
+                self._consultation_failed(str(error))
+                return
+            signal = self.folder_requested if action == FileAction.FOLDER else self.text_editor_requested
+            signal.emit(entry.path)
+            return
+        path = local_history_path(snapshot, entry)
+        if path is None:
+            self._consultation_failed("No file history exists at HEAD for this file")
+            return
+        window = self.window
+
+        def read_anchor() -> Generator[GitCommand, bytes, FileHistoryAnchor]:
+            """Resolve the tree entry of the snapshot's HEAD commit, then check once that HEAD still names that commit.
+
+            The tree is asked for by the commit ID, which never changes, so HEAD moving before the read cannot change
+            what is read: the single check at the end refuses the anchor instead.
+            """
+            output = yield GitCommand(["ls-tree", "-z", snapshot.head_oid, "--", os.fsdecode(path)])
+            tree_entries = parse_tree_entries(output)
+            historical = next((candidate for candidate in tree_entries if candidate.path == path and candidate.object_type == "blob"), None)
+            if historical is None:
+                raise ValueError("No file history exists at HEAD for this file")
+            after = yield GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            if after.strip().decode("ascii", "replace") != snapshot.head_oid:
+                raise ValueError("HEAD changed while resolving file history; Refresh first")
+            return FileHistoryAnchor(snapshot.head_oid, path, historical.oid)
+
+        def complete(anchor: FileHistoryAnchor | None, error: Exception | None) -> None:
+            """Open the history for the still-open requesting view when the anchor still matches the changes shown, and say why otherwise.
+
+            A worktree read published meanwhile replaces the snapshot without changing what the anchor names, so the
+            anchor is compared with the changes now shown rather than with the snapshot it was read from. Only a closed
+            view means nobody waits for the answer any more.
+            """
+            if self.window is not window or window.close_requested:
+                return
+            if error is not None:
+                self._consultation_failed(str(error))
+                return
+            if not self._history_anchor_is_current(anchor, entry.path):
+                self._consultation_failed(HISTORY_STATE_CHANGED_CAUSE)
+                return
+            self.history_requested.emit(anchor)
+
+        self.worktree_service.run(self.context, self.git_filename, read_anchor(), complete)
+
+    def _history_anchor_is_current(self, anchor: FileHistoryAnchor, path: bytes) -> bool:
+        """Tell whether the snapshot now shown would give the same history anchor for the unstaged file at ``path``.
+
+        An anchor names a commit and the file's name in it, and Git never changes either object. A newer read that still
+        has HEAD on that commit and still lists the file as unstaged under the same name at HEAD gives exactly the same
+        anchor, whatever else it changed; the window must also still accept a request on that read.
+        """
+        current = self.snapshot
+        if current is None:
+            return False
+        entry = next((candidate for candidate in current.entries if candidate.side == StagingSide.UNSTAGED and candidate.path == path), None)
+        if entry is None or not self._local_intention_is_current((entry,), current):
+            return False
+        return current.head_oid == anchor.commit_oid and local_history_path(current, entry) == anchor.path
+
+    def _consultation_failed(self, cause: str, diagnostic: PreparedDiagnostic | None = None) -> None:
+        """Explain an unavailable action in the existing staging status area.
+
+        A tool started outside Git, such as the text editor, hands over its own diagnostic so the details name that
+        program instead of Git.
+        """
+        if diagnostic is None:
+            diagnostic = Diagnostic("Local file action", self.context.repository_dir, self.git_filename, [], cause).prepare()
+        self.diagnostic = diagnostic
+        self._show()
+
+    def _ignore_finished(self, outcome: IgnoreOutcome) -> None:
+        """Retain rule outcomes and reread without staging either rules or selected files."""
+        self.last_ignore_outcome = outcome
+        self.busy = False
+        self.diagnostic = outcome.diagnostic
+        self._show()
+        if self.window is not None and self.window.close_requested:
+            self.window.close()
+        self.changed.emit()
+        self.refresh(priority=ProcessPriority.CONTINUATION)
+
+    def _trash_waiting(self, outcome: TrashOutcome) -> None:
+        """Keep an outstanding native call visible without ending its mutation reservation."""
+        self.last_trash_outcome = outcome
+        self.diagnostic = outcome.diagnostic
+        self._show()
+        self.changed.emit()
+
+    def _finished(self, outcome: MutationOutcome) -> None:
+        """Publish file-operation outcomes without unlocking an unrelated active native commit."""
+        if outcome.key != self.key:
+            return
+        if self.commit_service.active_by_id or self.trash_service.active_by_id or self.ignore_service.active or self.key in self.mutation.active_key_set:
+            return
+        self.last_outcome = outcome
+        self.busy = False
+        self.diagnostic = outcome.diagnostic
+        if self.snapshot is not None:
+            self.snapshot = replace(self.snapshot, fresh=False)
+        self._show()
+        if outcome.status == "success" and self.window is not None and self.window.close_requested:
+            self.window.close()
+        self.refresh(priority=ProcessPriority.CONTINUATION)
+
+    def unstage(self, entries: tuple[LocalEntry, ...]) -> None:
+        """Remove whole selected staged changes while retaining the session's working content."""
+        if self.busy or self.snapshot is None or not self.snapshot.fresh or self.context.is_bare:
+            return
+        self.busy = True
+        self.last_outcome = None
+        self._show()
+        self.mutation.unstage_file(self.snapshot, entries)