gitpane 1.0.0__py3-none-any.whl

gitpane/history/repository.py

@@ -0,0 +1,1600 @@
+"""Read a repository through asynchronous Git commands, never writing to it."""
+
+from __future__ import annotations
+
+import os
+import sys
+import uuid
+from collections import OrderedDict, deque
+from dataclasses import dataclass, field, replace
+from functools import wraps
+from time import monotonic
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import (
+    COMMIT_BATCH_SIZE,
+    COMMIT_HEADER_LIMIT_BYTES,
+    COMMIT_LIMIT_BYTES,
+    DIFF_CACHE_ENTRY_LIMIT,
+    DIFF_CACHE_LIMIT_BYTES,
+    FILE_CACHE_LIMIT_BYTES,
+    FILE_HISTORY_BATCH_SIZE,
+    FILE_PARSE_BUDGET_MS,
+    FILE_PREVIEW_LIMIT_BYTES,
+    GIT_OPEN_TIMEOUT_MS,
+    GIT_READ_TIMEOUT_MS,
+    HISTORY_PUBLISH_INTERVAL_MS,
+    HISTORY_STREAM_TIMEOUT_MS,
+    MESSAGE_CACHE_LIMIT_BYTES,
+    MILLISECONDS_PER_SECOND,
+    PARSING_BACKLOG_LIMIT_BYTES,
+    PARSING_BUDGET_MS,
+    SNAPSHOT_RETRY_LIMIT,
+)
+from gitpane.history.history_filter import HistoryFilterMode
+from gitpane.history.history_parse import (
+    CHANGED_PATH_ARGUMENTS,
+    HISTORY_LOG_ARGUMENTS,
+    CatFileParser,
+    ChangedPathParser,
+    HistoryLogParser,
+    commit_matches_query,
+    commit_subject,
+    oversized_commit_cause,
+    parse_abbreviation_answer,
+    parse_commit,
+    parse_history_comparisons,
+    parse_presence_answer,
+    parse_revision_entries,
+    parse_tree_entries,
+    relation_link,
+    summarize_commit,
+    unavailable_commit,
+)
+from gitpane.history.repository_value import (
+    COMMIT_PEEL_SUFFIX,
+    SUCCESS_EXIT_CODE,
+    CommitLink,
+    CommitRelation,
+    ComparisonGroup,
+    FileStatus,
+    HistorySnapshot,
+    OpeningHeadRead,
+    Reference,
+    ReferenceKind,
+    RepositoryContext,
+    RepositoryFailure,
+    validate_oid,
+)
+from gitpane.history.revision_file import comparison_metadata, decode_blob_display, unchanged_context
+from gitpane.process.process_runner import ProcessRequest, ProcessResult, ProcessRunner, ProcessStatus
+from gitpane.reference.reference_snapshot import REFERENCE_FORMAT, parse_reference_read
+from gitpane.system.path_identity import canonical_path
+from gitpane.text.text_query import TextQuery
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.history.repository_value import BlobContent, Commit, FilePanel, FileReadIdentity, RequestIdentity, RevisionEntry, TreeEntry
+    from gitpane.reference.reference_snapshot import ReferenceRead, ReferenceSnapshot
+
+
+MISSING_HEAD_EXIT_CODE = 1
+BARE_ROOT_EXIT_CODE = 128
+GIT_TRUE = "true"
+GIT_FALSE = "false"
+GIT_LINE_FEED = "\n"
+# The root question comes last on purpose: a bare repository prints the three answers before it, then fails on it
+# with BARE_ROOT_EXIT_CODE. Any other failure stops before printing, or prints something else in last position.
+REPOSITORY_LOCATION_OPTIONS = ("--git-dir", "--git-common-dir", "--is-bare-repository", "--show-toplevel")
+GIT_DIR_LOCATION_INDEX, COMMON_GIT_DIR_LOCATION_INDEX, BARE_FLAG_LOCATION_INDEX, ROOT_LOCATION_INDEX = range(len(REPOSITORY_LOCATION_OPTIONS))
+ABSOLUTE_PATH_FORMAT_ARGUMENT = "--path-format=absolute"
+REPOSITORY_LOCATION_ARGUMENTS = ["rev-parse", ABSOLUTE_PATH_FORMAT_ARGUMENT, *REPOSITORY_LOCATION_OPTIONS]
+# HEAD without a commit answers the shallow flag alone with MISSING_HEAD_EXIT_CODE, and nothing on the error output.
+HEAD_READ_ARGUMENTS = ["rev-parse", "--is-shallow-repository", "--verify", "--quiet", "HEAD"]
+HEAD_READ_EXPECTED_CODES = (SUCCESS_EXIT_CODE, MISSING_HEAD_EXIT_CODE)
+SHALLOW_FLAG_INDEX = 0
+HEAD_OID_INDEX = 1
+SYMBOLIC_HEAD_ARGUMENTS = ["symbolic-ref", "--quiet", "HEAD"]
+SYMBOLIC_HEAD_EXPECTED_CODES = (SUCCESS_EXIT_CODE, MISSING_HEAD_EXIT_CODE)
+# Namespaces the history lists and shows, in the order of the kinds: local branches, remote branches, tags.
+SHOWN_REFERENCE_PREFIXES = tuple(kind.prefix for kind in ReferenceKind if kind.prefix)
+
+
+def git_answer_lines(output: bytes) -> list[str]:
+    """Split one answer into its lines, removing only the line feed Git writes after the last one."""
+    if not output:
+        return []
+    return os.fsdecode(output.removesuffix(b"\n")).split(GIT_LINE_FEED)
+
+
+def location_context(values: list[str]) -> RepositoryContext:
+    """Build a repository context from Git's location answers, refusing anything but absolute paths and a real flag.
+
+    A bare repository has three answers and no working tree; any other repository has four, its root last.
+    """
+    bare_text = values[BARE_FLAG_LOCATION_INDEX]
+    if bare_text not in (GIT_TRUE, GIT_FALSE):
+        raise ValueError("Git returned an invalid repository location")
+    is_bare = bare_text == GIT_TRUE
+    expected_count = ROOT_LOCATION_INDEX if is_bare else len(REPOSITORY_LOCATION_OPTIONS)
+    if len(values) != expected_count:
+        raise ValueError("Git returned an incomplete repository location")
+    for path in values[:BARE_FLAG_LOCATION_INDEX] + values[ROOT_LOCATION_INDEX:]:
+        if not os.path.isabs(path):
+            raise ValueError("Git returned an invalid repository location")
+    worktree_dir = None if is_bare else values[ROOT_LOCATION_INDEX]
+    return RepositoryContext(worktree_dir, values[GIT_DIR_LOCATION_INDEX], values[COMMON_GIT_DIR_LOCATION_INDEX], is_bare)
+
+
+def parse_repository_location(output: bytes, return_code: int) -> RepositoryContext | None:
+    """Read the grouped location answer, or answer nothing when a line feed inside a path makes it ambiguous.
+
+    With a success every question is answered. With the bare code only the three answers before the root question
+    exist, the last one saying the repository is bare. More lines than expected can only come from a path holding a
+    line feed, so the caller asks each question again on its own instead of guessing where a path ends.
+    """
+    values = git_answer_lines(output)
+    expected_count = len(REPOSITORY_LOCATION_OPTIONS) if return_code == SUCCESS_EXIT_CODE else ROOT_LOCATION_INDEX
+    if len(values) > expected_count:
+        return None
+    if len(values) < expected_count:
+        raise ValueError("Git returned an incomplete repository location")
+    if return_code != SUCCESS_EXIT_CODE and values[BARE_FLAG_LOCATION_INDEX] != GIT_TRUE:
+        raise ValueError("Git could not locate a working tree for this repository")
+    return location_context(values)
+
+
+def is_bare_location_answer(output: bytes) -> bool:
+    """Tell whether a failed location read printed what only a bare repository prints before the root question."""
+    values = git_answer_lines(output)
+    return len(values) >= ROOT_LOCATION_INDEX and values[-1] == GIT_TRUE
+
+
+def parse_head_read(output: bytes, return_code: int) -> tuple[bool, str | None]:
+    """Read the shallow flag and HEAD's commit from one grouped answer.
+
+    A success holds the flag then a full object ID. HEAD without a commit holds the flag alone and exits with the
+    missing code. Any other shape is refused rather than read as an empty or partial HEAD.
+    """
+    if output and not output.endswith(b"\n"):
+        raise ValueError("Git returned an incomplete HEAD read")
+    values = output.decode("ascii").removesuffix(GIT_LINE_FEED).split(GIT_LINE_FEED) if output else []
+    expected_count = HEAD_OID_INDEX + 1 if return_code == SUCCESS_EXIT_CODE else SHALLOW_FLAG_INDEX + 1
+    if len(values) != expected_count or values[SHALLOW_FLAG_INDEX] not in (GIT_TRUE, GIT_FALSE):
+        raise ValueError("Git returned an invalid shallow or HEAD answer")
+    head_oid = validate_oid(values[HEAD_OID_INDEX]) if return_code == SUCCESS_EXIT_CODE else None
+    return values[SHALLOW_FLAG_INDEX] == GIT_TRUE, head_oid
+
+
+def reference_snapshot_fits(snapshot: ReferenceSnapshot, identity: RequestIdentity, context: RepositoryContext, git_filename: str) -> bool:
+    """Tell whether a reference capture was taken for this very read: same generation, same Git, same repository, listing kept.
+
+    The session itself is checked by the caller's request identity; a capture carries no session of its own.
+    """
+    captured = snapshot.context
+    return (snapshot.reference_read is not None and snapshot.generation == identity.generation and snapshot.git_filename == git_filename
+            and captured.is_bare == context.is_bare and canonical_path(captured.git_dir) == canonical_path(context.git_dir)
+            and canonical_path(captured.repository_dir) == canonical_path(context.repository_dir))
+
+
+def parse_symbolic_head(output: bytes, return_code: int) -> str | None:
+    """Read the branch HEAD names, or nothing when Git says HEAD is not symbolic."""
+    if return_code != SUCCESS_EXIT_CODE:
+        return None
+    head_ref = output.decode("utf-8", "surrogateescape").removesuffix(GIT_LINE_FEED)
+    if not head_ref or GIT_LINE_FEED in head_ref:
+        raise ValueError("Git returned an invalid HEAD branch")
+    return head_ref
+
+
+class CommitCache:
+    """Keep repository-specific commit metadata under one shared LRU byte budget."""
+
+    def __init__(self, limit_bytes: int = MESSAGE_CACHE_LIMIT_BYTES) -> None:
+        """Allow small limits for boundary tests without changing production settings."""
+        self.limit_bytes = limit_bytes
+        self.size_bytes = 0
+        self.entry_by_key: OrderedDict[tuple[str, str], tuple[Commit, int]] = OrderedDict()
+
+    def get(self, repository_dir: str, oid: str) -> Commit | None:
+        """Reuse metadata only in the repository where Git calculated its abbreviation."""
+        key = (repository_dir, oid)
+        entry = self.entry_by_key.get(key)
+        if entry is None:
+            return None
+        self.entry_by_key.move_to_end(key)
+        commit, _size = entry
+        return commit
+
+    def put(self, repository_dir: str, commit: Commit) -> None:
+        """Charge repository keys and message storage to the same global eviction budget."""
+        key = (repository_dir, commit.oid)
+        # Reading the history again gives back the same commits: an unchanged entry only needs to become the most recent.
+        entry = self.entry_by_key.get(key)
+        if entry is not None:
+            cached_commit, _size = entry
+            if cached_commit == commit:
+                self.entry_by_key.move_to_end(key)
+                return
+        size = (sys.getsizeof(commit.message) + sys.getsizeof(commit.body_preview) + sys.getsizeof(commit.author_name) + sys.getsizeof(commit.author_email) + sys.getsizeof(commit)
+                + sys.getsizeof(key) + sys.getsizeof(repository_dir) + sys.getsizeof(commit.oid) + sys.getsizeof(commit.short_oid))
+        previous = self.entry_by_key.pop(key, None)
+        if previous is not None:
+            _, previous_size = previous
+            self.size_bytes -= previous_size
+        if size > self.limit_bytes:
+            return
+        while self.entry_by_key and self.size_bytes + size > self.limit_bytes:
+            _, (_, oldest_size) = self.entry_by_key.popitem(last=False)
+            self.size_bytes -= oldest_size
+        self.entry_by_key[key] = (commit, size)
+        self.size_bytes += size
+
+
+@dataclass
+class _StreamRead:
+    """Retain bounded chunks while Qt schedules the next parsing turn.
+
+    ``ready`` tells whether the chunks can be parsed yet; while it answers no, the chunk already received is kept,
+    Git's output stays paused and ``held_request`` remembers the request whose parsing resumes once it can.
+    """
+
+    consume: Callable[[bytes], None]
+    chunks: deque[bytes] = field(default_factory=deque)
+    size_bytes: int = 0
+    scheduled: bool = False
+    ready: Callable[[], bool] | None = None
+    held_request: ProcessRequest | None = None
+
+
+@dataclass
+class _CommitBatchRead:
+    """The two reads of one commit batch, started together: Git's abbreviations and the raw objects.
+
+    It only lets the two be stopped and forgotten together when one of them fails, is cancelled or no longer belongs
+    to the current request; it schedules nothing and caches nothing.
+    """
+
+    identity: RequestIdentity
+    request_id_set: set[str] = field(default_factory=set)
+    short_oid_by_oid: dict[str, str] | None = None
+    object_request_id: str = ""
+
+
+class GitRepository(QObject):
+    """Translate repository reads into asynchronous Git commands without a shell."""
+
+    opened = Signal(object, object, object)
+    commit_read = Signal(object, object)
+    failed = Signal(object, object)
+    snapshot_read = Signal(object, object)
+    commit_batch_read = Signal(object, object)
+    matching_read = Signal(object, object, int, bool)
+    relation_read = Signal(object, object)
+    changes_read = Signal(object, object)
+    diff_read = Signal(object, object, bytes)
+    tree_read = Signal(object, object)
+    blob_read = Signal(object, object)
+    file_failed = Signal(object, object)
+    # Emitted when the last callback queued for the next turn of the event loop has run.
+    next_turn_work_done = Signal()
+
+    def __init__(self, git_filename: str, parent: QObject | None = None, runner: ProcessRunner | None = None,
+                 backlog_limit_bytes: int = PARSING_BACKLOG_LIMIT_BYTES, object_limit_bytes: int = COMMIT_LIMIT_BYTES, cache_limit_bytes: int = MESSAGE_CACHE_LIMIT_BYTES) -> None:
+        """Keep executable selection and request ownership separate from widgets.
+
+        ``git_version`` is the ``git --version`` line of the chosen Git, empty until a check has read it; it says which
+        options that Git knows.
+        """
+        super().__init__(parent)
+        self.git_filename = git_filename
+        self.git_version = ""
+        self.runner = runner if runner is not None else ProcessRunner(self)
+        self.identity_by_session: dict[str, RequestIdentity] = {}
+        self.context_by_session: dict[str, RepositoryContext] = {}
+        self.callback_by_id: dict[str, Callable[[bytes], None]] = {}
+        self.identity_by_id: dict[str, RequestIdentity] = {}
+        self.output_by_id: dict[str, bytearray] = {}
+        self.result_callback_by_id: dict[str, tuple[Callable[[bytes, ProcessResult], None], tuple[int, ...]]] = {}
+        self.opening_head_read_by_session: dict[str, OpeningHeadRead] = {}
+        self.executable_by_session: dict[str, str] = {}
+        self.snapshot_by_session: dict[str, HistorySnapshot] = {}
+        self.selection_identity_by_session: dict[str, RequestIdentity] = {}
+        self.search_identity_by_session: dict[str, RequestIdentity] = {}
+        self.stream_by_id: dict[str, _StreamRead] = {}
+        # Both reads of a commit batch point at the same record, so either one can stop the other.
+        self.batch_read_by_request_id: dict[str, _CommitBatchRead] = {}
+        # The window session each callback queued for the next turn of the event loop and not run yet was queued for, by
+        # one token per callback: a cached answer about to be published, or the next page or slice of a read. No request
+        # map holds them, so this is what tells they are pending, and for which window; ``None`` when no window is known.
+        self.next_turn_session_id_by_token: dict[object, str | None] = {}
+        self.backlog_limit_bytes = backlog_limit_bytes
+        self.object_limit_bytes = object_limit_bytes
+        self.commit_cache = CommitCache(cache_limit_bytes)
+        self.relation_identity_by_session: dict[str, RequestIdentity] = {}
+        self.file_identity_by_key: dict[tuple[str, FilePanel], FileReadIdentity] = {}
+        self.file_identity_by_id: dict[str, FileReadIdentity] = {}
+        self.patch_by_key: OrderedDict[tuple[str, RevisionEntry, bool], bytes] = OrderedDict()
+        self.patch_cache_size_bytes = 0
+        self.blob_by_key: OrderedDict[tuple[str, str], tuple[BlobContent, int]] = OrderedDict()
+        self.blob_cache_size_bytes = 0
+        self.runner.stdout_chunk.connect(self._receive_chunk)
+        self.runner.finished.connect(self._receive_result)
+
+    def open_repository(self, repository_dir: str, request_identity: RequestIdentity) -> None:
+        """Resolve repository locations and load HEAD before reporting a successful opening.
+
+        The executable is not asked for its version here: the application checks it at startup and whenever the
+        setting changes, and a file that is not Git fails the location read below with its own diagnostic. One
+        command locates the repository and one reads the shallow flag with HEAD; only a location that cannot be
+        split with certainty, or HEAD without a commit, costs more.
+        """
+        self.cancel(request_identity.session_id)
+        self.identity_by_session[request_identity.session_id] = request_identity
+        git_filename = self.git_filename
+        self.executable_by_session[request_identity.session_id] = git_filename
+        repository_dir = os.path.abspath(repository_dir)
+
+        def located(output: bytes, result: ProcessResult) -> None:
+            """Accept a complete answer, or the bare repository's documented failure on its root, and nothing else."""
+            if result.return_code != SUCCESS_EXIT_CODE and not is_bare_location_answer(output):
+                self._emit_result_failure(request_identity, result)
+                return
+            context = parse_repository_location(output, result.return_code)
+            if context is None:
+                read_location_separately([])
+                return
+            read_head(context)
+
+        def read_location_separately(values: list[str]) -> None:
+            """Ask each location question on its own, removing only the line feed Git ends each answer with."""
+            answered_count = len(values)
+            if answered_count > BARE_FLAG_LOCATION_INDEX and (values[BARE_FLAG_LOCATION_INDEX] == GIT_TRUE or answered_count == len(REPOSITORY_LOCATION_OPTIONS)):
+                read_head(location_context(values))
+                return
+
+            def answered(output: bytes) -> None:
+                read_location_separately([*values, os.fsdecode(output.removesuffix(b"\n"))])
+
+            self._execute(repository_dir, ["rev-parse", ABSOLUTE_PATH_FORMAT_ARGUMENT, REPOSITORY_LOCATION_OPTIONS[answered_count]], request_identity, answered)
+
+        def read_head(context: RepositoryContext) -> None:
+            """Read the shallow flag and HEAD together; only HEAD without a commit asks Git for its branch name."""
+            self.context_by_session[request_identity.session_id] = context
+
+            def head_read(output: bytes, result: ProcessResult) -> None:
+                shallow, head_oid = parse_head_read(output, result.return_code)
+                if head_oid is not None:
+                    self._read_commit(head_oid, request_identity, lambda commit: publish(OpeningHeadRead(request_identity, context, git_filename, shallow, head_oid), commit))
+                    return
+
+                def symbolic_read(symbolic_output: bytes, symbolic_result: ProcessResult) -> None:
+                    head_ref = parse_symbolic_head(symbolic_output, symbolic_result.return_code)
+                    publish(OpeningHeadRead(request_identity, context, git_filename, shallow, None, head_ref), None)
+
+                self._execute_expecting(context.repository_dir, SYMBOLIC_HEAD_ARGUMENTS, request_identity, symbolic_read, SYMBOLIC_HEAD_EXPECTED_CODES)
+
+            self._execute_expecting(context.repository_dir, HEAD_READ_ARGUMENTS, request_identity, head_read, HEAD_READ_EXPECTED_CODES)
+
+        def publish(head_read: OpeningHeadRead, commit: Commit | None) -> None:
+            """Keep what this opening read for its own first history capture, then report the opening."""
+            self.opening_head_read_by_session[request_identity.session_id] = head_read
+            self.opened.emit(request_identity, head_read.context, commit)
+
+        self._execute_expecting(repository_dir, REPOSITORY_LOCATION_ARGUMENTS, request_identity, located, (SUCCESS_EXIT_CODE, BARE_ROOT_EXIT_CODE))
+
+    def read_commit(self, oid: str, request_identity: RequestIdentity, verify_exists: bool = False) -> None:
+        """Read a commit into the same shared value used by the initial view."""
+        validate_oid(oid)
+        current = self.identity_by_session.get(request_identity.session_id)
+        if current is None or current.generation != request_identity.generation:
+            self.cancel(request_identity.session_id)
+            self.identity_by_session[request_identity.session_id] = request_identity
+            self.executable_by_session[request_identity.session_id] = self.git_filename
+        self.selection_identity_by_session[request_identity.session_id] = request_identity
+        for request_id, pending_identity in tuple(self.identity_by_id.items()):
+            if pending_identity.session_id == request_identity.session_id and pending_identity.oid is not None and pending_identity != request_identity:
+                self.runner.cancel(request_id)
+        def read_verified(_output: bytes = b"") -> None:
+            """Use cached metadata only after any requested object-presence check."""
+            cached = self.commit_cache.get(self.context_by_session[request_identity.session_id].git_dir, oid)
+            if cached is not None and not cached.detail_error:
+                self._call_on_next_turn(lambda: self.commit_read.emit(request_identity, cached) if self._is_current(request_identity) else None, request_identity.session_id)
+                return
+            self._read_commit(oid, request_identity, lambda commit: self.commit_read.emit(request_identity, commit))
+
+        if verify_exists:
+            context = self.context_by_session[request_identity.session_id]
+            self._execute(context.repository_dir, ["rev-parse", "--verify", oid + COMMIT_PEEL_SUFFIX], request_identity, read_verified)
+        else:
+            read_verified()
+
+    def read_relation(self, commit: Commit, snapshot: HistorySnapshot | None, identity: RequestIdentity) -> None:
+        """Read direct relatives independently of displayed pages, preserving captured order."""
+        self.relation_identity_by_session[identity.session_id] = identity
+        complete = snapshot is not None and snapshot.complete and not snapshot.error
+        child_oids = []
+        if snapshot is not None:
+            child_oid_set = set(snapshot.child_oids_by_oid.get(commit.oid, []))
+            for oid in snapshot.ordered_oids:
+                if oid in child_oid_set:
+                    child_oids.append(oid)
+            for explicit_commit in snapshot.explicit_commits:
+                if commit.oid in explicit_commit.parent_oids and explicit_commit.oid not in child_oid_set:
+                    child_oids.append(explicit_commit.oid)
+        relation_oids = list(dict.fromkeys([*commit.parent_oids, *child_oids]))
+        link_by_oid: dict[str, CommitLink] = {}
+        context = self.context_by_session[identity.session_id]
+        # The history already read the full commits it shows: only the relatives it never read are asked of Git. The
+        # cache is display data here, never a proof that an object still exists.
+        missing_oids = []
+        for oid in relation_oids:
+            cached = self.commit_cache.get(context.git_dir, oid)
+            if cached is None:
+                missing_oids.append(oid)
+            else:
+                link_by_oid[oid] = relation_link(cached)
+        offset = 0
+
+        def publish() -> None:
+            """Show the relatives in their captured order, once, for a still current request."""
+            if not self._is_current(identity):
+                return
+            parents = []
+            child_links = []
+            for oid in commit.parent_oids:
+                parents.append(link_by_oid[oid])
+            for oid in child_oids:
+                child_links.append(link_by_oid[oid])
+            self.relation_read.emit(identity, CommitRelation(commit.oid, parents, child_links, complete))
+
+        def next_page() -> None:
+            """Bound object reads and yield between pages of unusually large ancestry."""
+            nonlocal offset
+            if not self._is_current(identity):
+                return
+            if offset >= len(missing_oids):
+                publish()
+                return
+            page_oids = missing_oids[offset:offset + COMMIT_BATCH_SIZE]
+            offset += len(page_oids)
+
+            def presence_read(output: bytes) -> None:
+                type_by_oid = parse_presence_answer(output, page_oids)
+                existing_oids = []
+                for oid in page_oids:
+                    if type_by_oid[oid] != "commit":
+                        link_by_oid[oid] = CommitLink(oid, "", "Object unavailable", False)
+                        continue
+                    cached = self.commit_cache.get(context.git_dir, oid)
+                    if cached is not None:
+                        link_by_oid[oid] = relation_link(cached)
+                    else:
+                        existing_oids.append(oid)
+                if not existing_oids:
+                    self._call_on_next_turn(next_page, identity.session_id)
+                    return
+
+                def consume(relative: Commit) -> None:
+                    """Retain only the full subject, while the common cache bounds message bodies."""
+                    link_by_oid[relative.oid] = relation_link(relative)
+
+                self.request_commit_batch(existing_oids, identity, lambda _commits: self._call_on_next_turn(next_page, identity.session_id), consume)
+
+            stdin = ("\n".join(page_oids) + "\n").encode("ascii")
+            self._execute(context.repository_dir, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], identity, presence_read, GIT_READ_TIMEOUT_MS, stdin=stdin)
+
+        if not missing_oids:
+            # Published on the next turn, like every other answer, so the caller has finished recording its request.
+            self._call_on_next_turn(publish, identity.session_id)
+            return
+        next_page()
+
+    def read_snapshot(self, identity: RequestIdentity, committed_parent_oid: str | None = None, *, reference_snapshot: ReferenceSnapshot | None = None) -> None:
+        """Capture refs and HEAD, optionally including an available unnamed parent gitlink.
+
+        One listing of the references and one read of the shallow flag with HEAD make a capture. A reference capture
+        taken for this very window, repository, Git and generation replaces the listing, and the first capture after an
+        opening reuses the HEAD that opening read. Neither is ever used as a reason to write anything.
+        """
+        if committed_parent_oid is not None:
+            validate_oid(committed_parent_oid)
+        # Taken before the cancellation below, which forgets what any earlier request of this window read.
+        opening_head_read = self.opening_head_read_by_session.pop(identity.session_id, None)
+        self.cancel(identity.session_id)
+        self.identity_by_session[identity.session_id] = identity
+        git_filename = self.git_filename
+        self.executable_by_session[identity.session_id] = git_filename
+        context = self.context_by_session[identity.session_id]
+        if opening_head_read is not None and (opening_head_read.identity != identity or opening_head_read.context != context or opening_head_read.git_filename != git_filename):
+            opening_head_read = None
+        if reference_snapshot is not None and not reference_snapshot_fits(reference_snapshot, identity, context, git_filename):
+            reference_snapshot = None
+
+        def start() -> None:
+            """Begin on the next turn of the event loop, so even a capture that needs no process never answers inside this call."""
+            if not self._is_current(identity):
+                return
+            try:
+                self._capture(identity, context, 1, reference_snapshot, opening_head_read, committed_parent_oid)
+            except (ValueError, KeyError, UnicodeError, OSError) as error:
+                self.failed.emit(identity, RepositoryFailure("Read Git", context.repository_dir, git_filename, [], str(error)))
+
+        self._call_on_next_turn(start, identity.session_id)
+
+    def _read_tag_targets(self, oids: list[str], identity: RequestIdentity, callback: Callable[[dict[str, str | None]], None]) -> None:
+        """Peel nested tags in bounded batches and identify replies by the original object ID."""
+        target_by_oid: dict[str, str | None] = {}
+        offset = 0
+
+        def next_page() -> None:
+            """Yield between batches so large ref collections remain cancellable."""
+            nonlocal offset
+            if not self._is_current(identity):
+                return
+            page_oids = oids[offset:offset + COMMIT_BATCH_SIZE]
+            if not page_oids:
+                callback(target_by_oid)
+                return
+            offset += len(page_oids)
+            pending_oid_set = set(page_oids)
+            expressions = []
+            for oid in page_oids:
+                expressions.append(f"{validate_oid(oid)}^{{}} {oid}")
+
+            def receive(output: bytes) -> None:
+                """Keep blob/tree tags non-navigable and reject incomplete or unexpected responses."""
+                for line in output.decode("ascii").splitlines():
+                    if line.endswith(" missing"):
+                        expression, _status = line.split(" ", 1)
+                        oid = validate_oid(expression.removesuffix("^{}"))
+                        target = None
+                    else:
+                        oid, target_oid, object_type = line.split("\t")
+                        validate_oid(oid)
+                        validate_oid(target_oid)
+                        target = target_oid if object_type == "commit" else None
+                    if oid not in pending_oid_set:
+                        raise ValueError("Unexpected tag lookup result")
+                    pending_oid_set.remove(oid)
+                    target_by_oid[oid] = target
+                if pending_oid_set:
+                    raise ValueError("Incomplete tag lookup results")
+                self._call_on_next_turn(next_page, identity.session_id)
+
+            context = self.context_by_session[identity.session_id]
+            self._execute(context.repository_dir, ["cat-file", "--batch-check=%(rest)\t%(objectname)\t%(objecttype)"], identity, receive,
+                          GIT_READ_TIMEOUT_MS, stdin=("\n".join(expressions) + "\n").encode("ascii"))
+
+        next_page()
+
+    def _capture(self, identity: RequestIdentity, context: RepositoryContext, attempt_number: int, shared: ReferenceSnapshot | None,
+                 opening_head_read: OpeningHeadRead | None, committed_parent_oid: str | None) -> None:
+        """Gather one reference listing and one HEAD read that agree, then publish the history's references.
+
+        The listing is the shared capture when one was given, otherwise one for-each-ref in the common format. HEAD
+        comes from the opening's read when there is one, otherwise from one grouped rev-parse. When HEAD disagrees with
+        the listing, HEAD kept from the opening is dropped and read again first; answers that still disagree are all read
+        again, a bounded number of times, and then reported instead of being assembled into a history.
+        """
+
+        def read_again() -> None:
+            if attempt_number >= SNAPSHOT_RETRY_LIMIT:
+                raise ValueError("The repository changed while reading; references not refreshed")
+            self._capture(identity, context, attempt_number + 1, None, None, committed_parent_oid)
+
+        def read_head(receive: Callable[[bool, str | None, bool], None]) -> None:
+            self._execute_expecting(context.repository_dir, HEAD_READ_ARGUMENTS, identity,
+                                    lambda output, result: receive(*parse_head_read(output, result.return_code), False), HEAD_READ_EXPECTED_CODES)
+
+        def begin(receive: Callable[[bool, str | None, bool], None]) -> None:
+            if opening_head_read is None:
+                read_head(receive)
+                return
+            receive(opening_head_read.shallow, opening_head_read.head_oid, True)
+
+        if shared is not None:
+            shared_read = shared.reference_read
+
+            def shared_head(shallow: bool, head_oid: str | None, from_opening: bool) -> None:
+                """Use the shared capture only if HEAD has not moved since it was taken; otherwise list the references afresh."""
+                opening_disagrees = from_opening and opening_head_read.head_ref is not None and opening_head_read.head_ref != shared.head_ref
+                if head_oid == shared.head_oid and not opening_disagrees:
+                    self._complete_capture(identity, shared_read, shared.references, shallow, head_oid, shared.head_ref, shared, committed_parent_oid)
+                    return
+                if from_opening:
+                    read_head(shared_head)
+                    return
+                read_again()
+
+            begin(shared_head)
+            return
+
+        def listed(output: bytes) -> None:
+            listing = parse_reference_read(output)
+
+            def listed_head(shallow: bool, head_oid: str | None, from_opening: bool) -> None:
+                """A branch marked current must hold the very commit HEAD resolves to; a listing without a mark means a detached or unborn HEAD."""
+                if listing.head_ref is None or head_oid == listing.head_oid:
+                    self._complete_capture(identity, listing, listing.references, shallow, head_oid, listing.head_ref, None, committed_parent_oid)
+                    return
+                if from_opening:
+                    read_head(listed_head)
+                    return
+                read_again()
+
+            begin(listed_head)
+
+        self._execute(context.repository_dir, ["for-each-ref", "--format=" + REFERENCE_FORMAT, *SHOWN_REFERENCE_PREFIXES], identity, listed)
+
+    def _complete_capture(self, identity: RequestIdentity, read: ReferenceRead, references: tuple[Reference, ...], shallow: bool, head_oid: str | None,
+                          head_ref: str | None, shared: ReferenceSnapshot | None, committed_parent_oid: str | None) -> None:
+        """Follow only the tags the listing left as tags, then publish the references the graph shows and start its walk.
+
+        Branches, remote branches and tags are shown; any other reference a shared capture lists is not. A committed
+        parent that no listed reference proves to be a commit is checked in the same bounded lookup.
+        """
+        shown_references: list[Reference] = []
+        commit_oid_set: set[str] = set()
+        for reference in references:
+            if reference.full_name.startswith(SHOWN_REFERENCE_PREFIXES):
+                shown_references.append(reference)
+                if reference.target_oid is not None:
+                    commit_oid_set.add(reference.target_oid)
+        unresolved_tag_oid_by_name: dict[str, str] = {}
+        for full_name, tag_oid in read.unresolved_tag_oid_by_name.items():
+            if full_name.startswith(SHOWN_REFERENCE_PREFIXES):
+                unresolved_tag_oid_by_name[full_name] = tag_oid
+        parent_proven = committed_parent_oid is not None and committed_parent_oid in commit_oid_set
+        lookup_oid_set = set(unresolved_tag_oid_by_name.values())
+        if committed_parent_oid is not None and not parent_proven:
+            lookup_oid_set.add(committed_parent_oid)
+
+        def resolved(target_by_oid: dict[str, str | None]) -> None:
+            """Attach each peeled commit to its tag, then publish one history from this single observation."""
+            history_references: list[Reference] = []
+            for reference in shown_references:
+                tag_oid = unresolved_tag_oid_by_name.get(reference.full_name)
+                history_references.append(reference if tag_oid is None else replace(reference, target_oid=target_by_oid[tag_oid]))
+            if head_oid is not None:
+                history_references.append(Reference("HEAD", ReferenceKind.HEAD, head_oid, head_ref, True))
+            history_references.sort(key=lambda reference: (reference.kind, reference.full_name))
+            tip_oid_set: set[str] = set()
+            if parent_proven or committed_parent_oid is not None and target_by_oid.get(committed_parent_oid) == committed_parent_oid:
+                tip_oid_set.add(committed_parent_oid)
+            for reference in history_references:
+                if reference.target_oid is not None:
+                    tip_oid_set.add(reference.target_oid)
+            snapshot = HistorySnapshot(identity.generation, history_references, sorted(tip_oid_set), head_oid, shallow=shallow, reference_snapshot=shared)
+            self.snapshot_by_session[identity.session_id] = snapshot
+            self.snapshot_read.emit(identity, snapshot)
+            self._walk_snapshot(identity, snapshot)
+
+        self._read_tag_targets(sorted(lookup_oid_set), identity, resolved)
+
+    def _walk_snapshot(self, identity: RequestIdentity, snapshot: HistorySnapshot) -> None:
+        """Read the whole history with one streamed git log: ancestry in Git's topological order and every row with it.
+
+        The rows of the first parsed chunk are published at once; later rows are gathered and published at most once
+        per short interval, each time followed by the grown history, so the window redraws a few times rather than once
+        per chunk. The complete history is published last, after the last rows, so the graph is finished once every
+        row is there. A shallow history holds its rows until the end of the read, when the boundary commits get their
+        real parents.
+        """
+        parser = HistoryLogParser(snapshot, self.object_limit_bytes, COMMIT_HEADER_LIMIT_BYTES)
+        git_dir = self.context_by_session[identity.session_id].git_dir
+        held_commits: list[Commit] = []
+        published_at: float | None = None
+
+        def publish() -> None:
+            """Cache the held full commits and hand their rows to the window."""
+            nonlocal published_at
+            summaries: list[Commit] = []
+            for commit in held_commits:
+                self.commit_cache.put(git_dir, commit)
+                summaries.append(summarize_commit(commit))
+            held_commits.clear()
+            published_at = monotonic()
+            if summaries:
+                self.commit_batch_read.emit(identity, summaries)
+
+        def consume(chunk: bytes) -> None:
+            held_commits.extend(parser.feed(chunk))
+            if snapshot.shallow or published_at is not None and monotonic() - published_at < HISTORY_PUBLISH_INTERVAL_MS / MILLISECONDS_PER_SECOND:
+                return
+            publish()
+            self.snapshot_read.emit(identity, snapshot)
+
+        def complete() -> None:
+            publish()
+            parser.finish()
+            self.snapshot_read.emit(identity, snapshot)
+
+        def finish(_output: bytes) -> None:
+            parser.check_ended()
+            if snapshot.shallow:
+                self._read_boundary_parents(identity, snapshot, held_commits, complete)
+                return
+            complete()
+
+        if not snapshot.tip_oids:
+            finish(b"")
+            return
+        self._execute(self.context_by_session[identity.session_id].repository_dir, HISTORY_LOG_ARGUMENTS, identity, finish, HISTORY_STREAM_TIMEOUT_MS,
+                      stdin=("\n".join(snapshot.tip_oids) + "\n").encode("ascii"), stdout_limit_bytes=None, stream_callback=consume)
+
+    def _read_boundary_parents(self, identity: RequestIdentity, snapshot: HistorySnapshot, commits: list[Commit], callback: Callable[[], None]) -> None:
+        """Give the commits at the edge of a shallow history the parents their objects really name, then call back.
+
+        Git leaves out a parent it does not have, so at the boundary of a shallow clone the log shows a commit
+        without parents although its object names one. The history keeps that parent as an explicit boundary, as a
+        raw object read does, so the commits the log showed without parents are read raw, in one read, and only in a
+        shallow history.
+        """
+        rootless_oids: list[str] = []
+        for commit in commits:
+            if not commit.parent_oids:
+                rootless_oids.append(commit.oid)
+        if not rootless_oids:
+            callback()
+            return
+        object_parser = CatFileParser(rootless_oids, self.object_limit_bytes + COMMIT_HEADER_LIMIT_BYTES, self.backlog_limit_bytes)
+        parent_oids_by_oid: dict[str, list[str]] = {}
+
+        def consume(chunk: bytes) -> None:
+            for oid, raw in object_parser.feed(chunk):
+                if raw is not None:
+                    parent_oids_by_oid[oid] = parse_commit(oid, raw, oid).parent_oids
+
+        def objects_read(_output: bytes) -> None:
+            object_parser.finish()
+            for commit_index, commit in enumerate(commits):
+                parent_oids = parent_oids_by_oid.get(commit.oid)
+                if not parent_oids:
+                    continue
+                commits[commit_index] = replace(commit, parent_oids=parent_oids)
+                snapshot.parent_oids_by_oid[commit.oid] = parent_oids
+                for parent_oid in parent_oids:
+                    snapshot.child_oids_by_oid.setdefault(parent_oid, []).append(commit.oid)
+            callback()
+
+        self._execute(self.context_by_session[identity.session_id].repository_dir, ["cat-file", "--batch"], identity, objects_read, GIT_READ_TIMEOUT_MS,
+                      stdin=("\n".join(rootless_oids) + "\n").encode("ascii"), stdout_limit_bytes=None, stream_callback=consume)
+
+    def request_commit_batch(self, oids: list[str], identity: RequestIdentity, callback: Callable[[list[Commit]], None] | None = None,
+                             consume_commit: Callable[[Commit], None] | None = None) -> None:
+        """Associate raw objects and Git abbreviations by OID, preserving requested order.
+
+        Both reads start together, the abbreviations first so that a window's process slots never hold an object read
+        waiting for an abbreviation read that cannot start. Objects arriving before the abbreviations wait in their
+        first chunk with Git's output paused, and are parsed once the abbreviations are known. The batch publishes once,
+        after both reads ended; a failure of either stops the other.
+        """
+        for oid in oids:
+            validate_oid(oid)
+        if len(oids) > COMMIT_BATCH_SIZE:
+            raise ValueError("Commit batch is too large")
+        if not oids or not self._is_current(identity):
+            return
+        context = self.context_by_session[identity.session_id]
+        stdin = ("\n".join(oids) + "\n").encode("ascii")
+        batch = _CommitBatchRead(identity)
+        parser = CatFileParser(oids, self.object_limit_bytes + COMMIT_HEADER_LIMIT_BYTES, self.backlog_limit_bytes)
+        commit_by_oid: dict[str, Commit] = {}
+
+        def abbreviations_read(output: bytes) -> None:
+            """Keep the abbreviations, then let the objects already received be parsed."""
+            batch.short_oid_by_oid = parse_abbreviation_answer(output, oids)
+            self._resume_held_stream(batch.object_request_id)
+
+        def consume(chunk: bytes) -> None:
+            """Turn every complete object into a commit; the stream only reaches here once the abbreviations are known."""
+            short_oid_by_oid = batch.short_oid_by_oid
+            if short_oid_by_oid is None:
+                raise ValueError("Commit abbreviations missing")
+            for oid, raw in parser.feed(chunk):
+                header, _separator, body = raw.partition(b"\n\n") if raw is not None else (b"", b"", b"")
+                if raw is None or len(body) > self.object_limit_bytes or len(header) > COMMIT_HEADER_LIMIT_BYTES:
+                    snapshot = self.snapshot_by_session.get(identity.session_id)
+                    parent_oids = snapshot.parent_oids_by_oid.get(oid, []) if snapshot else []
+                    commit = unavailable_commit(oid, short_oid_by_oid[oid], parent_oids, oversized_commit_cause(self.object_limit_bytes))
+                else:
+                    commit = parse_commit(oid, raw, short_oid_by_oid[oid])
+                    snapshot = self.snapshot_by_session.get(identity.session_id)
+                    if snapshot is not None and oid in snapshot.parent_oids_by_oid:
+                        snapshot.parent_oids_by_oid[oid] = commit.parent_oids
+                        for parent_oid in commit.parent_oids:
+                            child_oids = snapshot.child_oids_by_oid.setdefault(parent_oid, [])
+                            if oid not in child_oids:
+                                child_oids.append(oid)
+                self.commit_cache.put(context.git_dir, commit)
+                if consume_commit is not None:
+                    consume_commit(commit)
+                    continue
+                if callback is not None:
+                    commit_by_oid[oid] = commit
+                else:
+                    commit_by_oid[oid] = summarize_commit(commit)
+
+        def objects_read(output: bytes) -> None:
+            """Publish the whole batch in the requested order, once both reads have answered."""
+            if batch.short_oid_by_oid is None:
+                raise ValueError("Commit abbreviations missing")
+            parser.finish()
+            commits = []
+            if consume_commit is None:
+                for oid in oids:
+                    commits.append(commit_by_oid[oid])
+            if callback is not None:
+                callback(commits)
+            else:
+                self.commit_batch_read.emit(identity, commits)
+
+        self._execute(context.repository_dir, ["log", "--no-walk=unsorted", "--no-show-signature", "--format=%H%x00%h", "--stdin"], identity,
+                      abbreviations_read, GIT_READ_TIMEOUT_MS, stdin=stdin, batch=batch)
+        batch.object_request_id = self._execute(context.repository_dir, ["cat-file", "--batch"], identity, objects_read, GIT_READ_TIMEOUT_MS, stdin=stdin,
+                                                stdout_limit_bytes=None, stream_callback=consume, batch=batch, ready=lambda: batch.short_oid_by_oid is not None)
+
+    def cancel_search(self, session_id: str) -> None:
+        """Abandon history searches without stopping history or selection reads."""
+        self.search_identity_by_session.pop(session_id, None)
+        for request_id, identity in tuple(self.identity_by_id.items()):
+            if identity.session_id == session_id and identity.search_generation:
+                self.runner.cancel(request_id)
+
+    def read_filter_matches(self, snapshot: HistorySnapshot, text: str, mode: HistoryFilterMode, identity: RequestIdentity) -> None:
+        """Run the search the window's filter mode asks for: on the changed file names, or on the messages.
+
+        An empty text shows every commit in both modes, which the message search answers without a Git read when the
+        commits are cached.
+        """
+        if mode == HistoryFilterMode.FILES and text:
+            self.read_changed_path_matching_oids(snapshot, text, identity)
+            return
+        self.read_matching_oids(snapshot, text, identity)
+
+    def read_matching_oids(self, snapshot: HistorySnapshot, text: str, identity: RequestIdentity) -> None:
+        """Check every commit of the shown history against the query, then emit the matches once, in the history's order.
+
+        When the cache still holds every commit of the history, the messages are checked from there with no Git read.
+        Otherwise the whole history is read once more by the same streamed git log as the history itself. Progress is
+        emitted while checking; a new query cancels this one through its search generation.
+        """
+        self.cancel_search(identity.session_id)
+        self.search_identity_by_session[identity.session_id] = identity
+        query = TextQuery(text)
+
+        def begin() -> None:
+            """Read the matching commits if this search is still the window's latest."""
+            if not self._is_current(identity):
+                return
+            self._read_matching_commits(snapshot, lambda commit: commit_matches_query(commit, query, text), identity)
+
+        self._call_on_next_turn(begin, identity.session_id)
+
+    def read_changed_path_matching_oids(self, snapshot: HistorySnapshot, text: str, identity: RequestIdentity) -> None:
+        """Keep the commits of the shown history that change a file whose path matches the query, then emit them once, in the history's order.
+
+        One git diff-tree reads the changed paths of every commit, fed with the shown history's OIDs: a merge counts
+        with its changes against each parent, a rename with both names. The rows of the matches then come from the
+        cache, or from one more streamed history read when any is missing. A new query cancels this one through its
+        search generation.
+        """
+        self.cancel_search(identity.session_id)
+        self.search_identity_by_session[identity.session_id] = identity
+        query = TextQuery(text)
+
+        def begin() -> None:
+            """Read the changed paths if this search is still the window's latest."""
+            if not self._is_current(identity):
+                return
+            self._stream_changed_path_matches(snapshot, query, identity)
+
+        self._call_on_next_turn(begin, identity.session_id)
+
+    def _stream_changed_path_matches(self, snapshot: HistorySnapshot, query: TextQuery, identity: RequestIdentity) -> None:
+        """Read the changed paths of every commit of the shown history in one streamed process, then read the rows of the matching ones.
+
+        A path is matched on the text the diff panel shows for it. A commit Git answers that the history does not hold,
+        or a requested commit Git leaves unanswered, fails the search instead of publishing a wrong list.
+        """
+        if not snapshot.ordered_oids:
+            self.matching_read.emit(identity, [], 0, True)
+            return
+        context = self.context_by_session[identity.session_id]
+        requested_oid_set = set(snapshot.ordered_oids)
+        answered_oid_set: set[str] = set()
+        matched_oid_set: set[str] = set()
+        parser = ChangedPathParser()
+        reported_at: float | None = None
+
+        def check(records: list[tuple[str, list[bytes]]]) -> None:
+            """Note every answered commit and keep it when one of its paths matches."""
+            for oid, paths in records:
+                if oid not in requested_oid_set:
+                    raise ValueError("Unexpected changed-file answer")
+                answered_oid_set.add(oid)
+                if oid in matched_oid_set:
+                    continue
+                for path in paths:
+                    if query.matches(path.decode("utf-8", "replace")):
+                        matched_oid_set.add(oid)
+                        break
+
+        def consume(chunk: bytes) -> None:
+            """Check the records this chunk completes, then report progress at most once per publishing interval."""
+            nonlocal reported_at
+            check(parser.feed(chunk))
+            if reported_at is None or monotonic() - reported_at >= HISTORY_PUBLISH_INTERVAL_MS / MILLISECONDS_PER_SECOND:
+                reported_at = monotonic()
+                self.matching_read.emit(identity, [], len(answered_oid_set), False)
+
+        def finish(_output: bytes) -> None:
+            """Refuse an answer that left a commit out, then read the rows of the matching commits."""
+            check(parser.finish())
+            if answered_oid_set != requested_oid_set:
+                raise ValueError("Incomplete changed-file answer")
+            if not self._is_current(identity):
+                return
+            self._read_matching_commits(snapshot, lambda commit: commit.oid in matched_oid_set, identity)
+
+        self._execute(context.repository_dir, CHANGED_PATH_ARGUMENTS, identity, finish, HISTORY_STREAM_TIMEOUT_MS,
+                      stdin=("\n".join(snapshot.ordered_oids) + "\n").encode("ascii"), stdout_limit_bytes=None, stream_callback=consume)
+
+    def _read_matching_commits(self, snapshot: HistorySnapshot, matches: Callable[[Commit], bool], identity: RequestIdentity) -> None:
+        """Keep the commits of the shown history that ``matches`` accepts, from the cache when it holds them all, or by reading the history once more."""
+        git_dir = self.context_by_session[identity.session_id].git_dir
+        cached_commits: list[Commit] = []
+        for oid in snapshot.ordered_oids:
+            commit = self.commit_cache.get(git_dir, oid)
+            if commit is None:
+                self._stream_matching_commits(snapshot, matches, identity)
+                return
+            cached_commits.append(commit)
+        self._scan_cached_matching_commits(cached_commits, matches, identity)
+
+    def _scan_cached_matching_commits(self, commits: list[Commit], matches: Callable[[Commit], bool], identity: RequestIdentity) -> None:
+        """Check cached commits, already in the history's order, a short time slice at a time so the window stays responsive.
+
+        Only the message check can refuse a commit, when its message could not be read; the failure is reported as such.
+        """
+        matching_commits: list[Commit] = []
+        scanned_count = 0
+
+        def scan_slice() -> None:
+            """Check commits until the time slice ends, then report progress and yield, or publish every match at the end."""
+            nonlocal scanned_count
+            if not self._is_current(identity):
+                return
+            deadline = monotonic() + PARSING_BUDGET_MS / MILLISECONDS_PER_SECOND
+            try:
+                while scanned_count < len(commits) and monotonic() < deadline:
+                    commit = commits[scanned_count]
+                    scanned_count += 1
+                    if matches(commit):
+                        matching_commits.append(summarize_commit(commit))
+            except ValueError as error:
+                self.failed.emit(identity, RepositoryFailure("Search messages", self.context_by_session[identity.session_id].repository_dir,
+                                                            self.executable_by_session[identity.session_id], [], str(error)))
+                return
+            if scanned_count < len(commits):
+                self.matching_read.emit(identity, [], scanned_count, False)
+                self._call_on_next_turn(scan_slice, identity.session_id)
+                return
+            self.matching_read.emit(identity, matching_commits, scanned_count, True)
+
+        scan_slice()
+
+    def _stream_matching_commits(self, snapshot: HistorySnapshot, matches: Callable[[Commit], bool], identity: RequestIdentity) -> None:
+        """Read the whole history with the history's own streamed git log and keep the commits that ``matches`` accepts.
+
+        The read fills a private history, never the one the window shows. Only commits of the shown history count, and
+        they are checked against its size at the end, so a history that moved meanwhile fails the search instead of
+        publishing a wrong list. The matches are put in the shown history's order, whatever order Git wrote them in.
+        """
+        parser = HistoryLogParser(HistorySnapshot(snapshot.generation, [], list(snapshot.tip_oids), snapshot.head_oid), self.object_limit_bytes,
+                                  COMMIT_HEADER_LIMIT_BYTES)
+        context = self.context_by_session[identity.session_id]
+        matching_commits: list[Commit] = []
+        scanned_count = 0
+        reported_at: float | None = None
+
+        def consume(chunk: bytes) -> None:
+            """Check the commits this chunk completes, then report progress at most once per publishing interval."""
+            nonlocal scanned_count, reported_at
+            for commit in parser.feed(chunk):
+                parent_oids = snapshot.parent_oids_by_oid.get(commit.oid)
+                if parent_oids is None:
+                    continue
+                # The shown history is the reference for the parents: at the edge of a shallow clone it keeps the
+                # parent Git leaves out of its log.
+                if commit.parent_oids != parent_oids:
+                    commit = replace(commit, parent_oids=parent_oids)
+                scanned_count += 1
+                self.commit_cache.put(context.git_dir, commit)
+                if matches(commit):
+                    matching_commits.append(summarize_commit(commit))
+            if reported_at is None or monotonic() - reported_at >= HISTORY_PUBLISH_INTERVAL_MS / MILLISECONDS_PER_SECOND:
+                reported_at = monotonic()
+                self.matching_read.emit(identity, [], scanned_count, False)
+
+        def finish(_output: bytes) -> None:
+            """Refuse a history that moved while searching, then publish the matches in the shown history's order."""
+            parser.finish()
+            if scanned_count != len(snapshot.ordered_oids):
+                raise ValueError("The history changed while searching. Refresh to search again.")
+            position_by_oid: dict[str, int] = {}
+            for position, oid in enumerate(snapshot.ordered_oids):
+                position_by_oid[oid] = position
+            matching_commits.sort(key=lambda commit: position_by_oid[commit.oid])
+            self.matching_read.emit(identity, matching_commits, scanned_count, True)
+
+        if not snapshot.tip_oids:
+            finish(b"")
+            return
+        self._execute(context.repository_dir, HISTORY_LOG_ARGUMENTS, identity, finish, HISTORY_STREAM_TIMEOUT_MS,
+                      stdin=("\n".join(snapshot.tip_oids) + "\n").encode("ascii"), stdout_limit_bytes=None, stream_callback=consume)
+
+    def read_history_comparisons(self, comparisons: list[tuple[str | None, str]], path: bytes, identity: FileReadIdentity,
+                                callback: Callable[[dict[tuple[str | None, str], list[RevisionEntry]]], None]) -> None:
+        """Batch captured parent edges, expanding only path boundaries for complete rename detection."""
+        if not comparisons or len(comparisons) > FILE_HISTORY_BATCH_SIZE or len(set(comparisons)) != len(comparisons):
+            raise ValueError("Invalid file-history comparison batch")
+        if not path or b"\0" in path:
+            raise ValueError("Invalid historical Git path")
+        session_id = identity.request_identity.session_id
+        self.cancel_file(session_id, identity.panel_kind)
+        self.file_identity_by_key[(session_id, identity.panel_kind)] = identity
+        repository_dir = self.context_by_session[session_id].repository_dir
+        options = ["diff-tree", "--stdin", "-r", "--raw", "-z", "--no-abbrev", "--format=%H%x00%P%x00", "--always", "--root", "--no-ext-diff", "--no-textconv"]
+
+        def read(batch: list[tuple[str | None, str]], scoped: bool, receive: Callable[[bytes], None]) -> None:
+            """Use explicit immutable child/parent pairs, including root comparisons."""
+            lines = []
+            for parent_oid, child_oid in batch:
+                line = validate_oid(child_oid)
+                if parent_oid is not None:
+                    line += " " + validate_oid(parent_oid)
+                lines.append(line)
+            arguments = ["--literal-pathspecs", *options, "--no-renames" if scoped else "-M"]
+            if scoped:
+                arguments.extend(["--", os.fsdecode(path)])
+            self._execute(repository_dir, arguments, identity.request_identity, receive, timeout_ms=GIT_READ_TIMEOUT_MS,
+                          stdin=("\n".join(lines) + "\n").encode("ascii"), file_identity=identity)
+
+        def receive_scoped(output: bytes) -> None:
+            """Unchanged paths need no whole-tree read; additions and deletions can conceal renames."""
+            entry_by_comparison = parse_history_comparisons(output, comparisons)
+            boundary_comparisons = []
+            for comparison, entries in entry_by_comparison.items():
+                if any(entry.status in (FileStatus.ADDED, FileStatus.DELETED) for entry in entries):
+                    boundary_comparisons.append(comparison)
+            if not boundary_comparisons:
+                callback(entry_by_comparison)
+                return
+
+            def receive_boundaries(boundary_output: bytes) -> None:
+                """Retain only the tracked side after Git detects renames against every changed path."""
+                boundary_entry_by_comparison = parse_history_comparisons(boundary_output, boundary_comparisons)
+                for comparison, entries in boundary_entry_by_comparison.items():
+                    retained_entries = []
+                    for entry in entries:
+                        if path in (entry.old_path, entry.new_path):
+                            retained_entries.append(entry)
+                    entry_by_comparison[comparison] = retained_entries
+                callback(entry_by_comparison)
+
+            read(boundary_comparisons, False, receive_boundaries)
+
+        read(comparisons, True, receive_scoped)
+
+    def read_changes(self, commit: Commit, identity: FileReadIdentity, callback: Callable[[list[ComparisonGroup]], None] | None = None) -> None:
+        """Read each true-parent comparison, including the empty side of a root commit."""
+        validate_oid(commit.oid)
+        self.cancel_file(identity.request_identity.session_id, identity.panel_kind)
+        self.file_identity_by_key[(identity.request_identity.session_id, identity.panel_kind)] = identity
+        groups: list[ComparisonGroup] = []
+        parents = iter(commit.parent_oids or [None])
+        context = self.context_by_session[identity.request_identity.session_id]
+        repository_dir = context.repository_dir
+
+        def next_parent() -> None:
+            """Serialize parent reads to preserve their commit-object order."""
+            try:
+                parent_oid = next(parents)
+            except StopIteration:
+                self.changes_read.emit(identity, groups)
+                if callback is not None:
+                    callback(groups)
+                return
+            arguments = ["diff-tree", "-r", "--raw", "-z", "--no-abbrev", "--no-commit-id", "-M", "--no-ext-diff", "--no-textconv"]
+            if parent_oid is None:
+                arguments.extend(["--root", commit.oid])
+            else:
+                arguments.extend([validate_oid(parent_oid), commit.oid])
+
+            def receive(output: bytes) -> None:
+                """Resolve the parent's display identity without changing comparison order."""
+                entries = parse_revision_entries(output, commit.oid, parent_oid)
+                if parent_oid is None:
+                    groups.append(ComparisonGroup(None, "", "Initial commit", entries))
+                    next_parent()
+                    return
+                # A parent the history already read in full is described from that read; Git is asked only for the others.
+                parent = self.commit_cache.get(context.git_dir, parent_oid)
+                if parent is not None and not parent.detail_error:
+                    groups.append(ComparisonGroup(parent_oid, parent.short_oid, commit_subject(parent.message), entries))
+                    next_parent()
+                    return
+
+                def receive_description(description: bytes) -> None:
+                    """Attach Git's abbreviation and subject to the already read changes."""
+                    short_oid, subject = description.rstrip(b"\n").split(b"\0", maxsplit=1)
+                    groups.append(ComparisonGroup(parent_oid, short_oid.decode("ascii"), subject.decode("utf-8", "replace"), entries))
+                    next_parent()
+
+                self._execute(repository_dir, ["show", "-s", "--format=%h%x00%s", "--no-show-signature", parent_oid], identity.request_identity,
+                              receive_description, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity)
+
+            self._execute(repository_dir, arguments, identity.request_identity, receive, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity)
+
+        next_parent()
+
+    def read_diff(self, entry: RevisionEntry, identity: FileReadIdentity) -> None:
+        """Compare immutable objects with external diff drivers explicitly disabled."""
+        validate_oid(entry.commit_oid)
+        session_id = identity.request_identity.session_id
+        self.cancel_file(session_id, identity.panel_kind)
+        self.file_identity_by_key[(session_id, identity.panel_kind)] = identity
+        repository_dir = self.context_by_session[session_id].repository_dir
+        cache_key = (self.context_by_session[session_id].git_dir, entry, identity.full_context)
+        cached = self.patch_by_key.get(cache_key)
+        if cached is not None:
+            self.patch_by_key.move_to_end(cache_key)
+
+            def publish_cached() -> None:
+                """Check ownership again after the event loop before publishing a cache hit."""
+                if self.file_identity_by_key.get((session_id, identity.panel_kind)) == identity:
+                    self.diff_read.emit(identity, entry, cached)
+
+            self._call_on_next_turn(publish_cached, session_id)
+            return
+        if "160000" in (entry.old_mode, entry.new_mode):
+            lines = ["Submodule commit", f"Old: {entry.old_blob_oid or 'absent'}", f"New: {entry.new_blob_oid or 'absent'}"]
+            self.diff_read.emit(identity, entry, "\n".join(lines).encode())
+            return
+        options = ["--no-ext-diff", "--no-textconv", "--no-color", "--full-index"]
+        format_options = ["-c", "diff.suppressBlankEmpty=false"]
+        if entry.old_blob_oid and entry.new_blob_oid:
+            arguments = [*format_options, "diff", *options, validate_oid(entry.old_blob_oid), validate_oid(entry.new_blob_oid)]
+        else:
+            arguments = [*format_options, "--literal-pathspecs", "diff-tree", "-r", "-p", "--no-commit-id", *options]
+            if entry.parent_oid:
+                arguments.extend([validate_oid(entry.parent_oid), entry.commit_oid])
+            else:
+                arguments.extend(["--root", entry.commit_oid])
+            arguments.append("--")
+            for path in (entry.old_path, entry.new_path):
+                if path is not None:
+                    arguments.append(os.fsdecode(path))
+        def receive(output: bytes) -> None:
+            """Restore path and mode metadata lost when comparing blobs directly."""
+            patch = comparison_metadata(entry) + output
+            if len(patch) > COMMIT_LIMIT_BYTES:
+                raise ValueError("Diff exceeds the display size limit")
+            previous = self.patch_by_key.pop(cache_key, b"")
+            self.patch_cache_size_bytes -= len(previous)
+            self.patch_by_key[cache_key] = patch
+            self.patch_cache_size_bytes += len(patch)
+            while self.patch_cache_size_bytes > DIFF_CACHE_LIMIT_BYTES or len(self.patch_by_key) > DIFF_CACHE_ENTRY_LIMIT:
+                _key, evicted = self.patch_by_key.popitem(last=False)
+                self.patch_cache_size_bytes -= len(evicted)
+            self.diff_read.emit(identity, entry, patch)
+
+        if not identity.full_context:
+            self._execute(repository_dir, arguments, identity.request_identity, receive, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity)
+            return
+        blob_oids = []
+        for blob_oid in (entry.old_blob_oid, entry.new_blob_oid):
+            if blob_oid is not None and blob_oid not in blob_oids:
+                blob_oids.append(blob_oid)
+        pending_oids = iter(blob_oids)
+        context_line_count = 0
+
+        def read_next_blob() -> None:
+            """Measure both bounded blobs so full context never assumes a universal length."""
+            try:
+                blob_oid = next(pending_oids)
+            except StopIteration:
+                command_index = arguments.index("diff") if "diff" in arguments else arguments.index("diff-tree")
+                arguments.insert(command_index + 1, f"--unified={context_line_count}")
+                self._execute(repository_dir, arguments, identity.request_identity, receive, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity)
+                return
+
+            def receive_blob(content: bytes) -> None:
+                """Count lines exactly, including a final line without a linefeed."""
+                nonlocal context_line_count
+                line_count = content.count(b"\n") + int(bool(content) and not content.endswith(b"\n"))
+                context_line_count = max(context_line_count, line_count)
+                if entry.old_blob_oid == entry.new_blob_oid:
+                    receive(unchanged_context(content))
+                    return
+                read_next_blob()
+
+            self._execute(repository_dir, ["cat-file", "blob", validate_oid(blob_oid)], identity.request_identity,
+                          receive_blob, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity)
+
+        read_next_blob()
+
+    def read_tree(self, commit_oid: str, identity: FileReadIdentity) -> None:
+        """Read all historical paths from Git, independent of the current working tree."""
+        session_id = identity.request_identity.session_id
+        self.cancel_file(session_id, identity.panel_kind)
+        self.file_identity_by_key[(session_id, identity.panel_kind)] = identity
+        repository_dir = self.context_by_session[session_id].repository_dir
+        buffer = bytearray()
+        entries: list[TreeEntry] = []
+
+        def consume(chunk: bytes) -> None:
+            """Parse complete records per streamed chunk while retaining one partial path."""
+            buffer.extend(chunk)
+            end = buffer.rfind(b"\0")
+            if end >= 0:
+                entries.extend(parse_tree_entries(bytes(buffer[:end + 1])))
+                del buffer[:end + 1]
+            if len(buffer) > self.backlog_limit_bytes:
+                raise ValueError("Tree path exceeds the parsing limit")
+
+        def receive(output: bytes) -> None:
+            """Publish entries only after complete NUL records have been validated."""
+            if buffer:
+                raise ValueError("Incomplete tree record")
+            entries.sort(key=lambda entry: entry.path)
+            self.tree_read.emit(identity, entries)
+
+        self._execute(repository_dir, ["ls-tree", "-r", "--full-tree", "-z", validate_oid(commit_oid)], identity.request_identity,
+                      receive, timeout_ms=GIT_READ_TIMEOUT_MS, file_identity=identity, stream_callback=consume, stdout_limit_bytes=None)
+
+    def read_blob(self, blob_oid: str, identity: FileReadIdentity) -> None:
+        """Retain only a bounded historical preview while checking the complete byte stream."""
+        validate_oid(blob_oid)
+        session_id = identity.request_identity.session_id
+        self.cancel_file(session_id, identity.panel_kind)
+        self.file_identity_by_key[(session_id, identity.panel_kind)] = identity
+        key = (self.context_by_session[session_id].git_dir, blob_oid)
+        cached = self.blob_by_key.get(key)
+        if cached is not None:
+            self.blob_by_key.move_to_end(key)
+            cached_content, _cached_size = cached
+
+            def publish_cached() -> None:
+                """Recheck a queued cache response after any intervening selection change."""
+                if self.file_identity_by_key.get((session_id, identity.panel_kind)) == identity:
+                    self.blob_read.emit(identity, cached_content)
+
+            self._call_on_next_turn(publish_cached, session_id)
+            return
+        preview = bytearray()
+
+        def consume(chunk: bytes) -> None:
+            """Keep the first display bytes and discard the remaining preview stream."""
+            remaining = FILE_PREVIEW_LIMIT_BYTES - len(preview)
+            if remaining > 0:
+                preview.extend(chunk[:remaining])
+
+        def finish(size_bytes: int) -> None:
+            """Charge the raw and decoded preview to a shared byte-bounded cache."""
+            content = decode_blob_display(blob_oid, bytes(preview), size_bytes)
+            git_dir, _oid = key
+            size = sum(sys.getsizeof(value) for value in (key, git_dir, blob_oid, content, content.raw_bytes, content.display_text, content.diagnostic))
+            previous = self.blob_by_key.pop(key, None)
+            if previous is not None:
+                _previous_content, previous_size = previous
+                self.blob_cache_size_bytes -= previous_size
+            while self.blob_by_key and self.blob_cache_size_bytes + size > FILE_CACHE_LIMIT_BYTES:
+                _key, (_content, evicted_size) = self.blob_by_key.popitem(last=False)
+                self.blob_cache_size_bytes -= evicted_size
+            if size <= FILE_CACHE_LIMIT_BYTES:
+                self.blob_by_key[key] = (content, size)
+                self.blob_cache_size_bytes += size
+            self.blob_read.emit(identity, content)
+
+        self.stream_blob(blob_oid, identity, consume, finish)
+
+    def stream_blob(self, blob_oid: str, identity: FileReadIdentity, consume: Callable[[bytes], None], completed: Callable[[int], None]) -> None:
+        """Deliver exact blob chunks; consumers finalize only on completion and cancel via cancel_file."""
+        validate_oid(blob_oid)
+        session_id = identity.request_identity.session_id
+        self.cancel_file(session_id, identity.panel_kind)
+        self.file_identity_by_key[(session_id, identity.panel_kind)] = identity
+        parser = CatFileParser([blob_oid], object_limit_bytes=0, expected_object_type="blob", body_callback=consume)
+
+        def receive(output: bytes) -> None:
+            """Confirm identity, type, exact body size and terminal framing before success."""
+            parser.finish()
+            completed(parser.size_by_oid[blob_oid])
+
+        self._execute(self.context_by_session[session_id].repository_dir, ["cat-file", "--batch"], identity.request_identity,
+                      receive, timeout_ms=GIT_READ_TIMEOUT_MS, stdin=(blob_oid + "\n").encode(), file_identity=identity,
+                      stream_callback=parser.feed, stdout_limit_bytes=None)
+
+    def cancel_file(self, session_id: str, panel_kind: FilePanel) -> None:
+        """Cancel one panel without stopping history, detail, or another panel."""
+        self.file_identity_by_key.pop((session_id, panel_kind), None)
+        for request_id, identity in tuple(self.file_identity_by_id.items()):
+            if identity.request_identity.session_id == session_id and identity.panel_kind == panel_kind:
+                self.runner.cancel(request_id)
+
+    def cancel(self, session_id: str) -> None:
+        """Invalidate outstanding callbacks belonging to just one repository window, stopping only the reads this repository started.
+
+        The runner is shared: a Fetch, a Push or a submodule initialization of the same window runs there under the
+        window's session too, and each is stopped by its own service. A new history read cancels the window's older
+        reads through here, so stopping the whole session would end such an operation in the middle.
+        """
+        for file_session_id, panel_kind in tuple(self.file_identity_by_key):
+            if file_session_id == session_id:
+                self.cancel_file(session_id, panel_kind)
+        self.identity_by_session.pop(session_id, None)
+        self.executable_by_session.pop(session_id, None)
+        self.selection_identity_by_session.pop(session_id, None)
+        self.relation_identity_by_session.pop(session_id, None)
+        self.search_identity_by_session.pop(session_id, None)
+        self.snapshot_by_session.pop(session_id, None)
+        self.opening_head_read_by_session.pop(session_id, None)
+        for request_id, identity in tuple(self.identity_by_id.items()):
+            if identity.session_id == session_id:
+                self.runner.cancel(request_id)
+        for request_id, identity in tuple(self.identity_by_id.items()):
+            if identity.session_id == session_id:
+                self.identity_by_id.pop(request_id, None)
+                self.callback_by_id.pop(request_id, None)
+                self.output_by_id.pop(request_id, None)
+                self.result_callback_by_id.pop(request_id, None)
+                self.stream_by_id.pop(request_id, None)
+                self.file_identity_by_id.pop(request_id, None)
+                self.batch_read_by_request_id.pop(request_id, None)
+
+    def close(self) -> None:
+        """Cancel every owned request when application shutdown begins."""
+        for session_id in list(self.identity_by_session):
+            self.cancel(session_id)
+        self.opening_head_read_by_session.clear()
+        self.runner.close()
+        self.patch_by_key.clear()
+        self.patch_cache_size_bytes = 0
+        self.blob_by_key.clear()
+        self.blob_cache_size_bytes = 0
+
+    def _read_commit(self, oid: str, identity: RequestIdentity, callback: Callable[[Commit], None]) -> None:
+        """Reuse byte-framed object reading for opening and individual selection."""
+        def deliver(commits: list[Commit]) -> None:
+            first_commit_index = 0
+            callback(commits[first_commit_index])
+        self.request_commit_batch([oid], identity, deliver)
+
+    def _call_on_next_turn(self, callback: Callable[[], None], session_id: str | None) -> None:
+        """Run a callback on the next turn of the event loop, kept in ``next_turn_session_id_by_token`` until it has run.
+
+        A cached answer, a capture that needs no process and the next page of a long read are all queued this way, so
+        whoever waits for a repository to be idle, like the commit timing of the --log file, sees them as pending work
+        instead of calling it idle one turn before they publish. ``session_id`` is the window the callback serves, so that
+        work queued for a window of another repository is told apart; ``None`` when no window is known. ``next_turn_work_done``
+        is emitted once the last of them has run, even when it raised. The queued function keeps the callback's qualified
+        name: the tests of the commit measurement hold a cached commit answer back by that name, to check that the
+        measurement waits for it.
+        """
+        token = object()
+        self.next_turn_session_id_by_token[token] = session_id
+
+        @wraps(callback)
+        def run() -> None:
+            """Run the callback, then forget its token and tell when no queued callback is left."""
+            try:
+                callback()
+            finally:
+                self.next_turn_session_id_by_token.pop(token, None)
+                if not self.next_turn_session_id_by_token:
+                    self.next_turn_work_done.emit()
+
+        QTimer.singleShot(0, run)
+
+    def _is_current(self, identity: RequestIdentity) -> bool:
+        """Accept the active traversal or its latest independent selection only."""
+        current = self.identity_by_session.get(identity.session_id)
+        if current is None or current.generation != identity.generation:
+            return False
+        if identity.relation_generation:
+            return (self.relation_identity_by_session.get(identity.session_id) == identity
+                    and self.selection_identity_by_session.get(identity.session_id) == replace(identity, relation_generation=0))
+        if identity.oid is not None:
+            return self.selection_identity_by_session.get(identity.session_id) == identity
+        if identity.search_generation:
+            return self.search_identity_by_session.get(identity.session_id) == identity
+        return current == identity
+
+    def _execute(self, working_dir: str, arguments: list[str], identity: RequestIdentity, callback: Callable[[bytes], None], timeout_ms: int = GIT_OPEN_TIMEOUT_MS,
+                 stdin: bytes = b"", stdout_limit_bytes: int | None = COMMIT_LIMIT_BYTES,
+                 stream_callback: Callable[[bytes], None] | None = None, file_identity: FileReadIdentity | None = None,
+                 batch: _CommitBatchRead | None = None, ready: Callable[[], bool] | None = None) -> str:
+        """Accumulate only a bounded single-object reply while the runner streams chunks, and answer the request's ID.
+
+        ``batch`` ties the read to the other read of the same commit batch before it is launched, so even a launch that
+        fails at once stops both. ``ready`` holds a streamed read's chunks until it answers yes.
+        """
+        request_id = uuid.uuid4().hex
+        self.callback_by_id[request_id] = callback
+        self.identity_by_id[request_id] = identity
+        if file_identity is not None:
+            self.file_identity_by_id[request_id] = file_identity
+        self.output_by_id[request_id] = bytearray()
+        if stream_callback is not None:
+            self.stream_by_id[request_id] = _StreamRead(stream_callback, ready=ready)
+        if batch is not None:
+            batch.request_id_set.add(request_id)
+            self.batch_read_by_request_id[request_id] = batch
+        self._launch(request_id, working_dir, arguments, identity, timeout_ms, stdin, stdout_limit_bytes)
+        return request_id
+
+    def _execute_expecting(self, working_dir: str, arguments: list[str], identity: RequestIdentity, callback: Callable[[bytes, ProcessResult], None],
+                           accepted_return_codes: tuple[int, ...], timeout_ms: int = GIT_OPEN_TIMEOUT_MS) -> None:
+        """Run one read whose exit code is part of its answer, such as a missing HEAD or a bare repository's root.
+
+        Only a process that ran to its end and exited with one of the listed codes reaches the callback, with its
+        whole output and outcome. A stop, a limit, a launch failure or any other code keeps the ordinary error path.
+        """
+        request_id = uuid.uuid4().hex
+        self.result_callback_by_id[request_id] = (callback, accepted_return_codes)
+        self.identity_by_id[request_id] = identity
+        self.output_by_id[request_id] = bytearray()
+        self._launch(request_id, working_dir, arguments, identity, timeout_ms, b"", COMMIT_LIMIT_BYTES)
+
+    def _launch(self, request_id: str, working_dir: str, arguments: list[str], identity: RequestIdentity, timeout_ms: int, stdin: bytes, stdout_limit_bytes: int | None) -> None:
+        """Start one read with the executable captured for the requesting window."""
+        self.runner.start(ProcessRequest(request_id, self.executable_by_session[identity.session_id], arguments, working_dir, timeout_ms, identity.session_id,
+                                         stdout_limit_bytes=stdout_limit_bytes, stdin=stdin))
+
+    def _emit_result_failure(self, identity: RequestIdentity, result: ProcessResult) -> None:
+        """Report a command's own failure, with Git's diagnostic, exactly as an unexpected exit is reported."""
+        request = result.request
+        self.failed.emit(identity, RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, result.cause, result.stderr, result.return_code))
+
+    def _receive_chunk(self, request: ProcessRequest, data: bytes) -> None:
+        """Retain output only for a still-current detail or file request."""
+        identity = self.identity_by_id.get(request.request_id)
+        if identity is None or not self._request_is_current(request.request_id, identity):
+            return
+        stream = self.stream_by_id.get(request.request_id)
+        if stream is not None:
+            if stream.size_bytes + len(data) > self.backlog_limit_bytes:
+                self._stream_failed(request, identity, "Parsing backlog exceeded; history incomplete")
+                return
+            stream.chunks.append(data)
+            stream.size_bytes += len(data)
+            self.runner.pause_stdout(request.request_id)
+            if not stream.scheduled:
+                stream.scheduled = True
+                self._call_on_next_turn(lambda: self._parse_stream(request, identity, stream), identity.session_id)
+            return
+        self.output_by_id[request.request_id].extend(data)
+
+    def _parse_stream(self, request: ProcessRequest, identity: RequestIdentity, stream: _StreamRead) -> None:
+        """Yield between chunks and reject cancelled generations before parsing work."""
+        if self.stream_by_id.get(request.request_id) is not stream or not self._request_is_current(request.request_id, identity):
+            self.runner.resume_stdout(request.request_id)
+            return
+        if stream.ready is not None and not stream.ready():
+            # Nothing can be parsed yet: the chunk stays, Git's output stays paused, and no turn is scheduled again
+            # until the read this stream waits for answers.
+            stream.scheduled = False
+            stream.held_request = request
+            return
+        budget_ms = FILE_PARSE_BUDGET_MS if request.request_id in self.file_identity_by_id else PARSING_BUDGET_MS
+        deadline = monotonic() + budget_ms / 1000
+        try:
+            while stream.chunks and monotonic() < deadline:
+                chunk = stream.chunks.popleft()
+                stream.size_bytes -= len(chunk)
+                stream.consume(chunk)
+        except (ValueError, KeyError, UnicodeError, OSError) as error:
+            self._stream_failed(request, identity, str(error))
+            return
+        if stream.chunks:
+            self._call_on_next_turn(lambda: self._parse_stream(request, identity, stream), identity.session_id)
+            return
+        stream.scheduled = False
+        self.runner.resume_stdout(request.request_id)
+
+    def _resume_held_stream(self, request_id: str) -> None:
+        """Schedule the parsing a stream put off until the read it waited for answered."""
+        stream = self.stream_by_id.get(request_id)
+        identity = self.identity_by_id.get(request_id)
+        if stream is None or identity is None or stream.held_request is None or stream.scheduled:
+            return
+        request = stream.held_request
+        stream.held_request = None
+        stream.scheduled = True
+        self._call_on_next_turn(lambda: self._parse_stream(request, identity, stream), identity.session_id)
+
+    def _abandon_batch_read(self, batch: _CommitBatchRead) -> None:
+        """Stop and forget the reads of a commit batch still running, without any diagnostic of their own.
+
+        Called once one read of the batch failed, was cancelled or no longer belongs to the current request: the other
+        read could publish nothing useful, and its chunks and paused output are released now.
+        """
+        for request_id in tuple(batch.request_id_set):
+            self.batch_read_by_request_id.pop(request_id, None)
+            self.identity_by_id.pop(request_id, None)
+            self.callback_by_id.pop(request_id, None)
+            self.output_by_id.pop(request_id, None)
+            self.stream_by_id.pop(request_id, None)
+            self.runner.cancel(request_id)
+        batch.request_id_set.clear()
+
+    def _stream_failed(self, request: ProcessRequest, identity: RequestIdentity, cause: str) -> None:
+        """Publish a concrete parsing failure once and terminate only its child process, and the other read of its batch."""
+        self.stream_by_id.pop(request.request_id, None)
+        batch = self.batch_read_by_request_id.pop(request.request_id, None)
+        if batch is not None:
+            batch.request_id_set.discard(request.request_id)
+            self._abandon_batch_read(batch)
+        file_identity = self.file_identity_by_id.get(request.request_id)
+        self.runner.cancel(request.request_id)
+        failure = RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, cause)
+        if file_identity is not None:
+            self.file_failed.emit(file_identity, failure)
+        else:
+            self.failed.emit(identity, failure)
+
+    def _request_is_current(self, request_id: str, identity: RequestIdentity) -> bool:
+        """Validate the complete file envelope instead of replacing detail ownership."""
+        file_identity = self.file_identity_by_id.get(request_id)
+        if file_identity is None:
+            return self._is_current(identity)
+        current = self.identity_by_session.get(identity.session_id)
+        return (current is not None and current.generation == identity.generation
+                and self.file_identity_by_key.get((identity.session_id, file_identity.panel_kind)) == file_identity)
+
+    def _receive_result(self, result: ProcessResult) -> None:
+        """Drop abandoned generations before parsing or raising an application diagnostic."""
+        request = result.request
+        pending_identity = self.identity_by_id.get(request.request_id)
+        current = pending_identity is not None and self._request_is_current(request.request_id, pending_identity)
+        file_identity = self.file_identity_by_id.pop(request.request_id, None)
+        identity = self.identity_by_id.pop(request.request_id, None)
+        callback = self.callback_by_id.pop(request.request_id, None)
+        output = self.output_by_id.pop(request.request_id, bytearray())
+        result_entry = self.result_callback_by_id.pop(request.request_id, None)
+        self.stream_by_id.pop(request.request_id, None)
+        batch = self.batch_read_by_request_id.pop(request.request_id, None)
+        if batch is not None:
+            batch.request_id_set.discard(request.request_id)
+            if result.status != ProcessStatus.SUCCESS or not current:
+                self._abandon_batch_read(batch)
+        if identity is None or (callback is None and result_entry is None) or not current or result.status == ProcessStatus.CANCELLED:
+            return
+        failure_signal = self.file_failed if file_identity is not None else self.failed
+        failure_identity = file_identity if file_identity is not None else identity
+        if result_entry is not None:
+            result_callback, accepted_return_codes = result_entry
+            ran_to_its_end = result.status == ProcessStatus.SUCCESS or result.status == ProcessStatus.FAILED and result.return_code != SUCCESS_EXIT_CODE
+            if ran_to_its_end and result.return_code in accepted_return_codes:
+                try:
+                    result_callback(bytes(output), result)
+                except (ValueError, KeyError, UnicodeError, OSError) as error:
+                    failure_signal.emit(failure_identity, RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, str(error), result.stderr, result.return_code))
+                return
+            failure_signal.emit(failure_identity, RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, result.cause, result.stderr, result.return_code))
+            return
+        if result.status != ProcessStatus.SUCCESS:
+            failure_signal.emit(failure_identity, RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, result.cause, result.stderr, result.return_code))
+            return
+        try:
+            callback(bytes(output))
+        except (ValueError, KeyError, UnicodeError, OSError) as error:
+            if batch is not None:
+                self._abandon_batch_read(batch)
+            failure_signal.emit(failure_identity, RepositoryFailure("Read Git", request.working_dir, request.program_filename, request.arguments, str(error), result.stderr, result.return_code))