gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/worktree_service.py

@@ -0,0 +1,584 @@
+"""Run Git command sequences on the shared process runner, the worktree reads among them."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Qt, QTimer, Signal, Slot
+
+from gitpane.config import (
+    FILE_PREVIEW_LIMIT_BYTES,
+    LOCAL_PREFIX,
+    WORKTREE_FILE_WORKER_COUNT,
+    ProcessPriority,
+)
+from gitpane.history.history_parse import CatFileParser
+from gitpane.history.repository_value import validate_oid
+from gitpane.process.process_runner import READ_PROFILE, ProcessRequest, ProcessResult, ProcessRunner, ProcessStatus
+from gitpane.sequencer.merge_state import read_merge_banner_state
+from gitpane.system.path_identity import canonical_path
+from gitpane.tool.system_tool import worktree_filename
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError, ReadBatch, command_profile, resumed_priority
+from gitpane.worktree.worktree_snapshot import (
+    STATUS_BRANCH_HEAD_PREFIX,
+    STATUS_BRANCH_OID_PREFIX,
+    STATUS_DETACHED_HEAD,
+    STATUS_HEADER_PREFIX,
+    STATUS_INITIAL_OID,
+    STATUS_RENAMED_PREFIX,
+    STATUS_UNKNOWN_HEAD,
+    STATUS_UNMERGED_PREFIX,
+    StagingSide,
+    WorktreeKey,
+    WorktreeProbe,
+    WorktreeSnapshot,
+    apply_conflict_attributes,
+    fingerprint,
+    fingerprint_files,
+    parse_index_listing,
+    parse_status,
+    read_index,
+    reusable_index_listing,
+    validate_conflict_index,
+    verify_local_state,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+    from concurrent.futures import Future
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.worktree.worktree_snapshot import LocalEntry
+
+
+# The one status every worktree read and every probe runs, so a probe and the snapshot it is compared with always
+# come from the same command.
+STATUS_ARGUMENTS: tuple[str, ...] = ("-c", "status.renameLimit=0", "status", "--porcelain=v2", "--branch", "--no-ahead-behind", "-z", "--untracked-files=all",
+                                    "--renames", "--ignore-submodules=none")
+
+
+def resolves_to_directory(root_output: bytes, directory: str) -> bool:
+    """Tell whether one Git-reported root, without its line terminator, is exactly the expected directory."""
+    root = os.fsdecode(root_output)
+    return os.path.isabs(root) and canonical_path(root) == canonical_path(directory)
+
+
+def read_gitlink_head(context: RepositoryContext, path: bytes) -> Generator:
+    """Prove the exact child root before trusting its HEAD, since Git otherwise finds the parent repository.
+
+    One process answers both the root and HEAD of an ordinary child. When its output cannot be split with
+    certainty, the two facts are read again separately so a line break inside a path never moves a boundary.
+    """
+    directory = worktree_filename(context, path)
+    if not os.path.isdir(directory) or not os.path.lexists(os.path.join(directory, ".git")):
+        return "uninitialized"
+    if os.path.islink(directory) or os.path.isjunction(directory):
+        raise ValueError("Linked submodule paths are not supported")
+    output = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel", "--verify", "HEAD"])
+    fields = output.removesuffix(b"\n").split(b"\n")
+    grouped_field_count = 2
+    if len(fields) == grouped_field_count:
+        root_output, head_output = fields
+        if resolves_to_directory(root_output, directory):
+            try:
+                return validate_oid(head_output.decode("ascii", "replace"))
+            except ValueError:
+                # An unreadable HEAD field is not a result; the separate reads below decide.
+                pass
+    output = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel"])
+    if not resolves_to_directory(output.removesuffix(b"\n"), directory):
+        raise ValueError("Submodule does not resolve to its declared worktree; refresh the changes")
+    output = yield GitCommand(["-C", directory, "rev-parse", "--verify", "HEAD"])
+    return validate_oid(output.removesuffix(b"\n").decode("ascii", "replace"))
+
+
+def read_worktree_probe(output: bytes) -> Generator[GitCommand, bytes, WorktreeProbe]:
+    """Build the probe from one status output; only a HEAD Git cannot name costs a second process.
+
+    Only the branch identity and head headers are read: upstream and ahead or behind headers change with a fetch
+    and say nothing about the worktree.
+    """
+    branch_oid: bytes | None = None
+    branch_head: bytes | None = None
+    header_length = 0
+    for record in output.split(b"\0"):
+        if not record.startswith(STATUS_HEADER_PREFIX):
+            break
+        header_length += len(record) + len(b"\0")
+        if record.startswith(STATUS_BRANCH_OID_PREFIX):
+            branch_oid = record.removeprefix(STATUS_BRANCH_OID_PREFIX)
+        elif record.startswith(STATUS_BRANCH_HEAD_PREFIX):
+            branch_head = record.removeprefix(STATUS_BRANCH_HEAD_PREFIX)
+    if branch_oid is None or branch_head is None:
+        raise ValueError("Incomplete Git status branch output")
+    entry_output = output[header_length:]
+    head_oid = None if branch_oid == STATUS_INITIAL_OID else branch_oid.decode("ascii")
+    head_reference: str | None
+    if branch_head == STATUS_DETACHED_HEAD:
+        head_reference = None
+    elif branch_head.upper() == STATUS_UNKNOWN_HEAD:
+        # Git writes this value when HEAD points outside the local branches; a branch name built from it would name a
+        # reference that does not exist, so Git is asked for the reference itself. The C library prints the missing
+        # name: "(NULL)" with Git for Windows, "(null)" with glibc. Asking Git is right even for a branch really named
+        # so, since the answer is the reference itself.
+        symbolic_output = yield GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))
+        reference = symbolic_output.removesuffix(b"\n")
+        head_reference = os.fsdecode(reference) if reference else None
+    else:
+        head_reference = LOCAL_PREFIX + os.fsdecode(branch_head)
+    unmerged_records: list[bytes] = []
+    original_path_follows = False
+    for record in entry_output.split(b"\0"):
+        if original_path_follows:
+            # The record after a rename is the original path of that rename, not a record of its own.
+            original_path_follows = False
+            continue
+        if record.startswith(STATUS_RENAMED_PREFIX):
+            original_path_follows = True
+            continue
+        if record.startswith(STATUS_UNMERGED_PREFIX):
+            unmerged_records.append(record)
+    return WorktreeProbe(head_oid, head_reference, tuple(unmerged_records), fingerprint(entry_output))
+
+
+def inspect_conflict_blobs(entries: tuple[LocalEntry, ...]) -> Generator:
+    """Classify immutable side contents in one bounded stream without keeping file bodies."""
+    oid_set: set[str] = set()
+    for entry in entries:
+        for side in entry.conflict_sides:
+            if side.mode in ("100644", "100755"):
+                oid_set.add(side.oid)
+    if not oid_set:
+        return entries
+    binary_oid_set: set[str] = set()
+    oids = sorted(oid_set)
+    retained_body_limit = 0
+    parser = CatFileParser(oids, object_limit_bytes=retained_body_limit, expected_object_type="blob")
+
+    def inspect(body: bytes) -> None:
+        """Remember a binary marker for the currently framed immutable object only."""
+        if b"\0" in body and parser.oid is not None:
+            binary_oid_set.add(parser.oid)
+
+    def consume(chunk: bytes) -> None:
+        """Feed the existing strict object framing while discarding completed bodies."""
+        parser.feed(chunk)
+
+    parser.body_callback = inspect
+    yield GitCommand(["cat-file", "--batch"], stdin="".join(oid + "\n" for oid in oids).encode("ascii"), consume=consume, stdout_limit_bytes=None)
+    parser.finish()
+    inspected_entries = []
+    for entry in entries:
+        if entry.conflict_sides:
+            entry = replace(entry, conflict_binary=any(side.oid in binary_oid_set for side in entry.conflict_sides))
+        inspected_entries.append(entry)
+    return tuple(inspected_entries)
+
+
+class WorktreeService(QObject):
+    """Share the process runner while keeping each read sequence and result isolated."""
+
+    snapshot_read = Signal(object)
+    idle = Signal()
+    file_completed = Signal(str, object)
+
+    def __init__(self, runner: ProcessRunner, parent: QObject | None = None) -> None:
+        """Use the existing runner so all Git work obeys application process limits."""
+        super().__init__(parent)
+        self.runner = runner
+        self.continuation_by_id: dict[str, tuple[Generator, Callable, RepositoryContext, str, GitCommand | ProcessRequest]] = {}
+        self.output_by_id: dict[str, bytearray] = {}
+        self.stream_error_by_id: dict[str, Exception] = {}
+        self.operation_id_by_sequence: dict[Generator, str] = {}
+        # Kept apart from the operation identity: the level orders the waiting queue only, and nothing else reads it.
+        self.priority_by_sequence: dict[Generator, ProcessPriority] = {}
+        self.file_executor = ThreadPoolExecutor(max_workers=WORKTREE_FILE_WORKER_COUNT, thread_name_prefix="gitpane-worktree")
+        self.file_task_by_id: dict[str, tuple[Generator, Callable, RepositoryContext, str]] = {}
+        self.file_completed.connect(self._file_finished, Qt.ConnectionType.QueuedConnection)
+        runner.stdout_chunk.connect(self._collect)
+        runner.finished.connect(self._finished)
+
+    def run(self, context: RepositoryContext, git_filename: str, sequence: Generator, callback: Callable[[object, Exception | None], None], *, operation_id: str = "",
+            priority: ProcessPriority = ProcessPriority.USER) -> None:
+        """Advance a command generator only after each real process has terminated.
+
+        A sequence has no profile: each of its commands chooses its own. Its priority is where it stands in the waiting
+        queue, given by whoever started it: a user action, the rest of an operation, or background work.
+        """
+        self.operation_id_by_sequence[sequence] = operation_id
+        self.priority_by_sequence[sequence] = priority
+        self._advance(context, git_filename, sequence, callback)
+
+    def _advance(self, context: RepositoryContext, git_filename: str, sequence: Generator, callback: Callable, output: object = None, error: Exception | None = None) -> None:
+        """Resume sequential Git work, returning either its value or its actual error.
+
+        An error given to the sequence, whether the sequence handles it or lets it through, leaves without any frame,
+        so whoever keeps it keeps neither the sequence, nor this service's plumbing, nor the frames that delivered the
+        process result.
+        """
+        try:
+            command = sequence.throw(error) if error is not None else sequence.send(output)
+        except StopIteration as stopped:
+            self.operation_id_by_sequence.pop(sequence, None)
+            self.priority_by_sequence.pop(sequence, None)
+            callback(stopped.value, None)
+            if not self.continuation_by_id and not self.file_task_by_id:
+                self.idle.emit()
+            return
+        except (OSError, ValueError, RuntimeError) as failure:
+            # Workaround for a reference cycle, see the ``finally`` below: an escaping error leaves without its traceback.
+            failure.__traceback__ = None
+            self.operation_id_by_sequence.pop(sequence, None)
+            self.priority_by_sequence.pop(sequence, None)
+            callback(None, failure)
+            if not self.continuation_by_id and not self.file_task_by_id:
+                self.idle.emit()
+            return
+        finally:
+            # Workaround for a reference cycle: an error thrown into the sequence keeps, in its traceback, the frame of
+            # the sequence that saw it, whether the sequence handled it or let it through, and a generator frame that
+            # outlives its run keeps the frame that resumed it (``f_back``), this one. This frame holds the error
+            # (``error``) and the callback, which may store it, as a read batch does; so until the cyclic garbage
+            # collector runs, the error keeps every frame that called this one, up to whichever window, dialog or test
+            # ran the event loop. Dropping only this frame from the traceback did not break that cycle, the sequence's
+            # frame still pointing back here. Nothing reads these tracebacks: the cause is the error's text.
+            if error is not None:
+                error.__traceback__ = None
+        priority = self.priority_by_sequence[sequence]
+        if not isinstance(command, ReadBatch):
+            # The step now asked for is this level's work; whatever the sequence asks after it is its follow-up. A file
+            # task counts as a step too: the action is under way even though it started no process.
+            self.priority_by_sequence[sequence] = resumed_priority(priority)
+        if isinstance(command, FileTask):
+            request_id = uuid.uuid4().hex
+            self.file_task_by_id[request_id] = (sequence, callback, context, git_filename)
+            try:
+                future = self.file_executor.submit(command.callback)
+            except RuntimeError as failure:
+                self.file_task_by_id.pop(request_id, None)
+                QTimer.singleShot(0, lambda failure=failure: self._advance(context, git_filename, sequence, callback, error=failure))
+                return
+            # Queued delivery resumes on the Qt thread immediately; polling adds one
+            # full timer interval per file and stalls verification of large repositories.
+            future.add_done_callback(lambda completed: self.file_completed.emit(request_id, completed))
+            return
+        if isinstance(command, ReadBatch):
+            self._run_batch(context, git_filename, sequence, callback, command, priority)
+            return
+        if isinstance(command, ProcessRequest):
+            # Only the place in the queue follows the sequence; everything the generator decided about the launch stays.
+            command = replace(command, priority=priority)
+            self.continuation_by_id[command.request_id] = (sequence, callback, context, git_filename, command)
+            self.output_by_id[command.request_id] = bytearray()
+            try:
+                self.runner.start(command)
+            except (ValueError, RuntimeError) as failure:
+                self.continuation_by_id.pop(command.request_id, None)
+                self.output_by_id.pop(command.request_id, None)
+                QTimer.singleShot(0, lambda failure=failure: self._advance(context, git_filename, sequence, callback, error=failure))
+            return
+        request_id = uuid.uuid4().hex
+        self.continuation_by_id[request_id] = (sequence, callback, context, git_filename, command)
+        self.output_by_id[request_id] = bytearray()
+        operation_id = self.operation_id_by_sequence[sequence]
+        profile = command_profile(command)
+        request = ProcessRequest(request_id, git_filename, ["--literal-pathspecs", *command.arguments], context.repository_dir, command.timeout_ms,
+                                 session_id="worktree:" + WorktreeKey.from_context(context).git_dir, stdin=command.stdin, environment_by_name=command.environment_by_name,
+                                 stdout_limit_bytes=command.stdout_limit_bytes, idle_timeout_ms=command.idle_timeout_ms, profile=profile, operation_id=operation_id,
+                                 before_start=command.before_start, editor_context=command.editor_context, suppress_editor=command.suppress_editor, priority=priority,
+                                 accepted_return_codes=command.accepted_codes, stdin_filename=command.stdin_filename,
+                                 opens_files_deleted_at_end=command.opens_files_deleted_at_end)
+        try:
+            if command.editor_context is not None and os.path.normcase(command.editor_context.git_dir) != WorktreeKey.from_context(context).git_dir:
+                raise ValueError("The editor context belongs to another worktree.")
+            self.runner.start(request)
+        except (ValueError, RuntimeError) as failure:
+            self.continuation_by_id.pop(request_id, None)
+            self.output_by_id.pop(request_id, None)
+            QTimer.singleShot(0, lambda failure=failure: self._advance(context, git_filename, sequence, callback, error=failure))
+
+    def _run_batch(self, context: RepositoryContext, git_filename: str, sequence: Generator, callback: Callable, batch: ReadBatch, priority: ProcessPriority) -> None:
+        """Wait for every bounded read before resuming, even when a command fails or finishes out of order.
+
+        Every member waits in the queue at the level the batch had when it was reached, and the generator takes its
+        follow-up level only once the whole batch has ended.
+        """
+        if not batch.commands:
+            self.priority_by_sequence[sequence] = resumed_priority(priority)
+            self._advance(context, git_filename, sequence, callback, ())
+            return
+        result_by_position: dict[int, tuple[object, Exception | None]] = {}
+
+        def complete(position: int, value: object, error: Exception | None) -> None:
+            """Keep result identity independent of process scheduling and report the first declared error."""
+            result_by_position[position] = (value, error)
+            if len(result_by_position) != len(batch.commands):
+                return
+            outputs = []
+            failure = None
+            for result_position in range(len(batch.commands)):
+                output, result_error = result_by_position[result_position]
+                outputs.append(output)
+                if failure is None:
+                    failure = result_error
+            self.priority_by_sequence[sequence] = resumed_priority(priority)
+            self._advance(context, git_filename, sequence, callback, tuple(outputs), failure)
+
+        def read(command: GitCommand | FileTask) -> Generator:
+            """Collect a single batch member through the normal bounded process path."""
+            return (yield command)
+
+        operation_id = self.operation_id_by_sequence[sequence]
+        for position, command in enumerate(batch.commands):
+            self.run(context, git_filename, read(command), lambda value, error, position=position: complete(position, value, error), operation_id=operation_id,
+                     priority=priority)
+
+    @Slot(str, object)
+    def _file_finished(self, request_id: str, future: Future) -> None:
+        """Resume a completed filesystem task on the owning Qt thread and retain shutdown accounting."""
+        continuation = self.file_task_by_id.pop(request_id, None)
+        if continuation is None:
+            return
+        sequence, callback, context, git_filename = continuation
+        error = future.exception()
+        self._advance(context, git_filename, sequence, callback, None if error else future.result(), error)
+
+    def _collect(self, request: ProcessRequest, chunk: bytes) -> None:
+        """Route owned streams directly to their consumer without accumulating file contents."""
+        continuation = self.continuation_by_id.get(request.request_id)
+        if continuation is None or request.request_id in self.stream_error_by_id:
+            return
+        _sequence, _callback, _context, _git_filename, command = continuation
+        if isinstance(command, ProcessRequest):
+            return
+        if command.consume is None:
+            self.output_by_id[request.request_id].extend(chunk)
+            return
+        try:
+            command.consume(chunk)
+        except (OSError, ValueError) as error:
+            self.stream_error_by_id[request.request_id] = error
+            self.runner.cancel(request.request_id)
+
+    def _finished(self, result: ProcessResult) -> None:
+        """Resume only after process termination, preserving stream-consumer errors."""
+        continuation = self.continuation_by_id.pop(result.request.request_id, None)
+        if continuation is None:
+            return
+        sequence, callback, context, git_filename, command = continuation
+        output = bytes(self.output_by_id.pop(result.request.request_id))
+        if isinstance(command, ProcessRequest):
+            self._advance(context, git_filename, sequence, callback, result)
+            return
+        accepted = result.return_code in command.accepted_codes and result.status in (ProcessStatus.SUCCESS, ProcessStatus.FAILED)
+        error = self.stream_error_by_id.pop(result.request.request_id, None)
+        self._advance(context, git_filename, sequence, callback, output, error or (None if accepted else GitCommandError(result)))
+
+    def capture(self, context: RepositoryContext, git_filename: str, generation: int = 0) -> Generator[GitCommand, bytes, WorktreeSnapshot]:
+        """Read the worktree validated at both ends, as the operations check it before they write.
+
+        Status, configuration and attributes are read again at the end and must be unchanged. Nothing is ever taken
+        over from an earlier read: a check before a write proves the state it relies on by itself.
+        """
+        return (yield from self._capture(context, git_filename, generation, previous=None, closing_reread=True))
+
+    def capture_display(self, context: RepositoryContext, git_filename: str, generation: int = 0,
+                        previous: WorktreeSnapshot | None = None) -> Generator[GitCommand, bytes, WorktreeSnapshot]:
+        """Read what the views show, starting each Git read once.
+
+        The index listing of the previous snapshot is taken over when the index bytes have not moved since it was read.
+        """
+        return (yield from self._capture(context, git_filename, generation, previous=previous, closing_reread=False))
+
+    def _capture(self, context: RepositoryContext, git_filename: str, generation: int, *, previous: WorktreeSnapshot | None,
+                 closing_reread: bool) -> Generator[GitCommand, bytes, WorktreeSnapshot]:
+        """Read one coherent snapshot; the closing Git reads run only when the caller will rely on the result to write."""
+        if context.is_bare or context.worktree_dir is None:
+            raise ValueError("This bare repository has no working tree to prepare")
+        location_output = yield GitCommand(["rev-parse", "--path-format=absolute", "--git-dir", "--git-path", "index", "--git-path", "hooks"])
+        location_fields = location_output.removesuffix(b"\n").split(b"\n")
+        expected_location_count = 3
+        if len(location_fields) != expected_location_count:
+            # Newlines are valid in POSIX directory names; separate results preserve their boundaries.
+            location_outputs = yield ReadBatch((GitCommand(["rev-parse", "--absolute-git-dir"]),
+                                               GitCommand(["rev-parse", "--path-format=absolute", "--git-path", "index"]),
+                                               GitCommand(["rev-parse", "--path-format=absolute", "--git-path", "hooks"])))
+            location_fields = []
+            for value in location_outputs:
+                location_fields.append(value.removesuffix(b"\n"))
+        git_directory, index_output, hooks_output = location_fields
+        resolved_git_dir = canonical_path(os.fsdecode(git_directory.rstrip(b"\r\n")))
+        if resolved_git_dir != WorktreeKey.from_context(context).git_dir:
+            raise ValueError("The repository identity changed; reopen the repository")
+        index_filename = os.fsdecode(index_output.rstrip(b"\r\n"))
+        before_index = yield FileTask(lambda: read_index(index_filename))
+        # The status arguments come from a constant, so the source does not show them as a read: the command says it.
+        read_commands: tuple[GitCommand, ...] = (GitCommand(["config", "--null", "--list", "--show-origin"]), GitCommand(list(STATUS_ARGUMENTS), profile=READ_PROFILE))
+        # The listing is a pure function of the index bytes just read, so equal bytes give the same listing. The index
+        # is read again at the end of this read, which keeps the listing and the bytes it belongs to consistent.
+        listing = reusable_index_listing(previous, context, git_filename, index_filename, before_index)
+        if listing is None:
+            read_commands += (GitCommand(["ls-files", "--stage", "-v", "-z"]),)
+        read_outputs = yield ReadBatch(read_commands)
+        conversion, output, *listing_outputs = read_outputs
+        if listing is None:
+            listing = parse_index_listing(next(iter(listing_outputs)))
+        probe = yield from read_worktree_probe(output)
+        head_oid = probe.head_oid
+        entries = parse_status(output)
+        skip_path_set = set(listing.skip_worktree_paths)
+        index_entries = listing.index_entries
+        validate_conflict_index(entries, index_entries)
+        entries = yield from inspect_conflict_blobs(entries)
+        local_entries: list[LocalEntry] = []
+        for entry in entries:
+            local_entries.append(replace(entry, skip_worktree=any(path in skip_path_set for path in entry.paths)))
+        entries = tuple(local_entries)
+        # Git lists changed entries before unmerged ones, so resolving a conflict moves its path in the status order.
+        # Sorting the paths keeps the fingerprints and the attribute output of two reads of the same paths in the same
+        # order, which lets a later read be compared with an earlier one byte for byte.
+        paths = tuple(sorted(dict.fromkeys(path for entry in entries for path in entry.paths)))
+        fingerprint_by_path = yield FileTask(lambda: fingerprint_files(context, paths))
+        submodule_path_set: set[bytes] = set()
+        for entry in entries:
+            for path in entry.paths:
+                if entry.is_gitlink and path not in submodule_path_set:
+                    submodule_path_set.add(path)
+                    submodule_head = yield from read_gitlink_head(context, path)
+                    fingerprint_by_path[path] += ":" + submodule_head
+        path_input = b"\0".join(fingerprint_by_path) + (b"\0" if fingerprint_by_path else b"")
+        attributes = (yield GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=path_input)) if paths else b""
+        if any(entry.conflict_sides for entry in entries):
+            entries = apply_conflict_attributes(entries, attributes)
+        # A read for the views accepts that a file appearing while it runs only shows at the next read: every write
+        # checks the repository again on its own side. The index and working-file checks below stay in both modes
+        # because they start no process.
+        if closing_reread:
+            final_commands = (
+                GitCommand(list(STATUS_ARGUMENTS), profile=READ_PROFILE),
+                GitCommand(["config", "--null", "--list", "--show-origin"]),
+            )
+            if paths:
+                final_commands += (GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=path_input),)
+            final_outputs = yield ReadBatch(final_commands)
+            after_output, after_conversion, *attribute_outputs = final_outputs
+            after_attributes = next(iter(attribute_outputs), b"")
+            if output != after_output or conversion != after_conversion or attributes != after_attributes:
+                raise ValueError("Repository changed during reading; refresh the changes")
+        after_index = yield FileTask(lambda: read_index(index_filename))
+        if before_index != after_index:
+            raise ValueError("Repository changed during reading; refresh the changes")
+        actual_by_path = yield FileTask(lambda: fingerprint_files(context, paths))
+        for path, expected in fingerprint_by_path.items():
+            actual = actual_by_path[path]
+            if path in submodule_path_set:
+                submodule_head = yield from read_gitlink_head(context, path)
+                actual += ":" + submodule_head
+            if actual != expected:
+                raise ValueError("Working file changed during reading; refresh the changes")
+        return WorktreeSnapshot(WorktreeKey.from_context(context), context, generation, git_filename, head_oid, index_filename, before_index, entries, fingerprint_by_path,
+                                conversion + attributes, index_entries=index_entries, hooks_dir=os.fsdecode(hooks_output), hidden_index_paths=listing.hidden_index_paths,
+                                skip_worktree_paths=listing.skip_worktree_paths, probe=probe)
+
+    def read(self, context: RepositoryContext, git_filename: str, generation: int, callback: Callable, previous: WorktreeSnapshot | None = None, *,
+             priority: ProcessPriority = ProcessPriority.USER) -> None:
+        """Read what the views show through the shared asynchronous runner, handing over the snapshot it replaces.
+
+        The merge state the repository window's banner shows is read from Git's files right after the capture, in the
+        same sequence, so whoever publishes the read knows the merge before anything is shown.
+        """
+        self.run(context, git_filename, self._read_display(context, git_filename, generation, previous), callback, priority=priority)
+
+    def _read_display(self, context: RepositoryContext, git_filename: str, generation: int,
+                      previous: WorktreeSnapshot | None) -> Generator[GitCommand | FileTask, object, WorktreeSnapshot]:
+        """Capture what the views show, then read the merge state in a file task, without a Git process."""
+        snapshot = yield from self.capture_display(context, git_filename, generation, previous)
+        git_dir = context.git_dir
+        merge_banner_state = yield FileTask(lambda: read_merge_banner_state(git_dir))
+        return replace(snapshot, merge_banner_state=merge_banner_state)
+
+    def probe(self, snapshot: WorktreeSnapshot) -> Generator[GitCommand | FileTask, object, WorktreeProbe]:
+        """Read again only what says whether the displayed snapshot still holds: local bytes without a process, then one status.
+
+        Any local difference is an error, so the caller reads everything again. Nothing is kept and the snapshot is not changed.
+        """
+        if not snapshot.fresh or snapshot.context.is_bare or snapshot.context.worktree_dir is None:
+            raise ValueError("A complete current working tree read is required")
+        # A file already modified and modified again keeps the same status line, and another tool can rewrite the index
+        # without changing anything visible. Only the bytes tell, and they are read without starting a process.
+        yield FileTask(lambda: verify_local_state(snapshot, tuple(snapshot.fingerprint_by_path)))
+        output = yield GitCommand(list(STATUS_ARGUMENTS), profile=READ_PROFILE)
+        return (yield from read_worktree_probe(output))
+
+    def verify_conversion(self, snapshot: WorktreeSnapshot) -> Generator:
+        """Compare configuration and attributes on the captured paths even after some become clean."""
+        path_input = b"\0".join(snapshot.fingerprint_by_path) + (b"\0" if snapshot.fingerprint_by_path else b"")
+        conversion, attributes = yield ReadBatch((
+            GitCommand(["config", "--null", "--list", "--show-origin"]),
+            GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=path_input),
+        ))
+        if conversion + attributes != snapshot.conversion:
+            raise ValueError("Repository configuration or attributes changed. Rescan before retrying.")
+
+    def verify(self, snapshot: WorktreeSnapshot, paths: tuple[bytes, ...]) -> Generator:
+        """Recheck write preconditions directly without rebuilding every visible list and rename comparison."""
+        if not snapshot.fresh or snapshot.context.is_bare or snapshot.context.worktree_dir is None:
+            raise ValueError("A complete current working tree read is required")
+        context = snapshot.context
+        before_index = yield FileTask(lambda: read_index(snapshot.index_filename))
+        before_by_path = yield FileTask(lambda: fingerprint_files(context, paths))
+        path_input = b"\0".join(snapshot.fingerprint_by_path) + (b"\0" if snapshot.fingerprint_by_path else b"")
+        location_output, conversion, attributes = yield ReadBatch((
+            GitCommand(["rev-parse", "--path-format=absolute", "--git-dir", "--git-path", "index", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1)),
+            GitCommand(["config", "--null", "--list", "--show-origin"]),
+            GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=path_input),
+        ))
+        location_fields = location_output.removesuffix(b"\n").split(b"\n")
+        unborn_location_count, committed_location_count = 2, 3
+        if len(location_fields) not in (unborn_location_count, committed_location_count):
+            location_outputs = yield ReadBatch((GitCommand(["rev-parse", "--absolute-git-dir"]),
+                                               GitCommand(["rev-parse", "--path-format=absolute", "--git-path", "index"]),
+                                               GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))))
+            location_fields = []
+            for value in location_outputs:
+                location_fields.append(value.removesuffix(b"\n"))
+        git_directory, index_output, *head_outputs = location_fields
+        head_output = next(iter(head_outputs), b"")
+        resolved_git_dir = canonical_path(os.fsdecode(git_directory.rstrip(b"\r\n")))
+        index_filename = os.fsdecode(index_output.rstrip(b"\r\n"))
+        if resolved_git_dir != snapshot.key.git_dir or snapshot.key != WorktreeKey.from_context(context):
+            raise ValueError("The repository identity changed; reopen the repository")
+        if canonical_path(index_filename) != canonical_path(snapshot.index_filename):
+            raise ValueError("The selected index does not belong to this worktree")
+        after_index = yield FileTask(lambda: read_index(index_filename))
+        if before_index != snapshot.index_content or after_index != snapshot.index_content or (head_output.strip().decode("ascii") or None) != snapshot.head_oid or conversion + attributes != snapshot.conversion:
+            raise ValueError("Repository changed since selection; refresh the changes")
+        after_by_path = yield FileTask(lambda: fingerprint_files(context, paths))
+        for path in paths:
+            actual = after_by_path[path]
+            if before_by_path[path] != actual:
+                raise ValueError("Working file changed during verification; refresh the changes")
+            expected = snapshot.fingerprint_by_path.get(path)
+            if expected is not None and expected.startswith(actual + ":"):
+                submodule_head = yield from read_gitlink_head(context, path)
+                actual += ":" + submodule_head
+            if actual != expected:
+                raise ValueError("Working file changed since selection; refresh the changes")
+
+    def diff(self, snapshot: WorktreeSnapshot, entry: LocalEntry) -> Generator[GitCommand, bytes, bytes]:
+        """Read the actual selected comparison, bounding only its presentation."""
+        arguments = ["diff", "--no-ext-diff", "--no-textconv", "--no-color", "--no-renames"]
+        if entry.side == StagingSide.STAGED:
+            arguments.append("--cached")
+        if entry.old_path is None and entry.side == StagingSide.UNSTAGED:
+            arguments.extend(["--no-index", "--", os.devnull, os.fsdecode(entry.path)])
+        else:
+            arguments.append("--")
+            arguments.extend(map(os.fsdecode, entry.paths))
+        # The argument list is built at run time, so the source cannot show it is a read: the command says it.
+        output = yield GitCommand(arguments, accepted_codes=(0, 1), stdout_limit_bytes=FILE_PREVIEW_LIMIT_BYTES, profile=READ_PROFILE)
+        return output