gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/replay_state.py

@@ -0,0 +1,747 @@
+"""Read the native evidence of a cherry-pick or revert without resuming Git."""
+
+from __future__ import annotations
+
+import configparser
+import os
+import re
+import time
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from gitpane.config import DETACHED_HEAD_NAME, GIT_REFTABLE_DIR_BASENAME, LOCAL_PREFIX, MERGE_HEAD_BASENAME, REFERENCE_ROOT_PREFIX, REPLAY_CAPTURE_TIMEOUT_MS, REPLAY_FILE_LIMIT_BYTES, REPLAY_INSTRUCTION_LIMIT, REPLAY_TOTAL_LIMIT_BYTES
+from gitpane.config import REPLAY_REFRESH_INTERVAL_MS as REPLAY_REFRESH_INTERVAL_MS  # noqa: PLC0414
+from gitpane.history.repository_value import COMMIT_PEEL_SUFFIX, validate_oid
+from gitpane.process.process_runner import READ_PROFILE, ProcessStatus
+from gitpane.sequencer.rebase_state import checked_metadata, metadata_signature
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError, ReadBatch
+from gitpane.worktree.worktree_snapshot import WorktreeKey, read_validated_size
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.worktree.worktree_snapshot import PassiveObservationSource
+
+MERGE_MESSAGE_BASENAME = "MERGE_MSG"
+CHERRY_PICK_HEAD_BASENAME = "CHERRY_PICK_HEAD"
+REVERT_HEAD_BASENAME = "REVERT_HEAD"
+REPLAY_BASENAMES = (CHERRY_PICK_HEAD_BASENAME, REVERT_HEAD_BASENAME, MERGE_MESSAGE_BASENAME, "HEAD", MERGE_HEAD_BASENAME)
+HEAD_BASENAME = "HEAD"
+# The index Git keeps for this worktree, in its own Git directory.
+LIVE_INDEX_BASENAME = "index"
+SEQUENCER_BASENAME = "sequencer"
+# Every native file and folder a replay capture reads, whose place Git decides.
+REPLAY_NATIVE_PATH_BASENAMES = (*REPLAY_BASENAMES, SEQUENCER_BASENAME)
+# Names of the answers a read of the replay facts gives besides the native paths; none of them is a native file name.
+GIT_DIR_ANSWER_NAME = "git-dir"
+SOURCE_ANSWER_NAME = "source"
+HEAD_ANSWER_NAME = "head-oid"
+BRANCH_ANSWER_NAME = "branch"
+# Asked for the full name of a detached HEAD, rev-parse answers with the word HEAD itself.
+DETACHED_HEAD_ANSWER = DETACHED_HEAD_NAME.encode("ascii")
+# Reasons of greyed Continue and Abort buttons, shared by the Cherry-pick/Revert banner and the merge banner.
+BUSY_ACTION_REASON = "Wait for the current operation or merge tool to finish."
+RESOLVE_CONFLICTS_FIRST_REASON = "Resolve and stage all conflicts before continuing."
+PRIVATE_INDEX_VARIABLE = "GIT_INDEX_FILE"
+# rev-parse ends with this status when it cannot resolve a revision it was given, a HEAD without commit included.
+# Whatever it printed before stopping is partial and is never used.
+UNRESOLVED_REVISION_RETURN_CODE = 128
+# Where the grouped answer and the unmerged listing sit in the batch that reads them together.
+GROUPED_ANSWER_POSITION = 0
+UNMERGED_ANSWER_POSITION = 1
+# Splitting an answer whose every line ends with a newline leaves one empty piece after the last line.
+TRAILING_EMPTY_PIECE_COUNT = 1
+REPLAY_SEQUENCER_BASENAMES = ("head", "todo", "opts", "abort-safety")
+# The option Git writes in its sequencer options file when a series was started without a commit.
+SEQUENCER_NO_COMMIT_OPTION = "no-commit"
+# Name of a commit operation whose kind is unknown or gone, also the title of the messages a Cherry-pick or Revert leaves.
+COMMIT_OPERATION_LABEL = "Commit operation"
+
+
+class ReplayKind(Enum):
+    """What a commit operation of a worktree is: a Cherry-pick, a Revert, an operation whose kind cannot be told, or none.
+
+    The value of Cherry-pick and Revert is the Git subcommand that runs them, given to Git by ``.value``. Each kind
+    carries the name the banner shows and, for Cherry-pick and Revert, what Git does with a terminal ``--no-commit``
+    series paused after a conflict: Git refuses ``git cherry-pick --continue`` there, since the resolved changes stay
+    staged and the next pick would overwrite them, so only quitting or aborting ends it; ``git revert --continue`` does go
+    on, but it commits the resolved revert, which the ``--no-commit`` choice did not ask for.
+    """
+
+    CHERRY_PICK = ("cherry-pick", "Cherry-pick",
+                   "Git cannot continue a --no-commit series after a conflict. Run git cherry-pick --quit to keep the result or git cherry-pick --abort to undo.")
+    REVERT = ("revert", "Revert",
+              "Git continues a --no-commit revert series by committing the resolved revert. Run git revert --continue to accept that, git revert --quit to keep the result uncommitted or git revert --abort to undo.")
+    UNKNOWN = ("unknown", COMMIT_OPERATION_LABEL, "")
+    ABSENT = ("absent", COMMIT_OPERATION_LABEL, "")
+
+    def __new__(cls, value: str, label: str, no_commit_series_message: str) -> Self:
+        """Keep the Git subcommand (or the state's name) as the value, the banner name and the series message beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        member.no_commit_series_message = no_commit_series_message
+        return member
+
+    @property
+    def is_replay(self) -> bool:
+        """Tell whether this kind is one of the two operations, Cherry-pick or Revert, rather than an unknown or absent one."""
+        return self in (ReplayKind.CHERRY_PICK, ReplayKind.REVERT)
+
+
+# The kind of each instruction Git writes in its sequencer todo file, keyed by the action word read there.
+REPLAY_KIND_BY_ACTION = {"pick": ReplayKind.CHERRY_PICK, "revert": ReplayKind.REVERT}
+
+
+class ReplayOwnership(Enum):
+    """Who started a pause: GitPane in this run of the program, or anything else, a terminal or an earlier run included."""
+
+    OWNED = "owned"
+    EXTERNAL = "external"
+
+
+class ReplayCommitMode(Enum):
+    """Whether a pause ends with a commit, without one, or in a mode Git's files leave open."""
+
+    COMMIT = "commit"
+    NO_COMMIT = "no-commit"
+    UNKNOWN = "unknown"
+
+
+class ReplayAction(Enum):
+    """One of the three buttons of the Cherry-pick/Revert banner, whose availability replay_action_diagnostic decides."""
+
+    RESOLVE = "resolve"
+    CONTINUE = "continue"
+    ABORT = "abort"
+
+
+class ReplayEffect(Enum):
+    """Why a Cherry-pick or Revert ended without a commit, as its operation step reports it, and the sentence the user reads for it.
+
+    The value is what the step writes in its free-text effect, a field other operations fill with their own words.
+    """
+
+    ALREADY_PRESENT = ("already_present", "No commit was created because the cherry-picked changes are already present in the current checkout.")
+    INITIALLY_EMPTY = ("initially_empty", "No commit was created because the selected commit is empty.")
+    REVERT_NO_EFFECT = ("revert_no_effect", "No commit was created because reverting the selected commit makes no changes.")
+    RESOLVED_NO_CHANGE = ("resolved_no_change", "No commit was created because the resolution leaves no changes.")
+
+    def __new__(cls, value: str, message: str) -> Self:
+        """Keep the word the step writes as the value, and the sentence shown for it beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.message = message
+        return member
+
+
+def replay_effect_message(effect: str) -> str:
+    """Answer the sentence shown for the effect a step wrote, or "" for an effect that is not a replay's end without a commit.
+
+    The effect field of a step is free text shared with other operations, so an effect another operation wrote is no error.
+    """
+    try:
+        return ReplayEffect(effect).message
+    except ValueError:
+        return ""
+
+
+# A pause started in a terminal whose files do not tell whether it commits: Git's Continue could commit the whole index, and
+# its Abort could drop changes staged for a commit mode GitPane cannot see.
+REPLAY_EXTERNAL_UNKNOWN_MODE_MESSAGE = "The commit mode of this operation is unknown, so Continue or Abort could commit or drop staged work. Finish it in the terminal."
+# Unmerged entries (or a lone prepared message) that no replay marker or sequencer explains.
+REPLAY_STEP_UNATTRIBUTED_CONFLICT = "unattributed-conflict"
+
+
+@dataclass(frozen=True)
+class ReplayIdentity:
+    """Bind native instructions to their exact files and original checkout."""
+
+    kind: ReplayKind
+    original_oid: str
+    symbolic_ref: str | None
+    signatures: tuple[tuple[int, ...] | None, ...]
+
+
+@dataclass(frozen=True)
+class ReplayLaunch:
+    """What GitPane launched in one worktree during this run of the program: the source, the choices of the form and the checkout it started from.
+
+    It is kept in memory only, never written anywhere. After a restart the same pause is read from Git's own files
+    alone, as a pause started outside GitPane.
+    """
+
+    kind: ReplayKind
+    source_oid: str
+    create_commit: bool
+    add_reference: bool
+    original_head_oid: str
+    original_symbolic_ref: str | None
+
+
+@dataclass(frozen=True)
+class ReplaySnapshot:
+    """Expose only proven native facts; ambiguous commit modes stay unknown."""
+
+    key: WorktreeKey
+    generation: int
+    kind: ReplayKind = ReplayKind.ABSENT
+    ownership: ReplayOwnership = ReplayOwnership.EXTERNAL
+    identity: ReplayIdentity | None = None
+    head_oid: str | None = None
+    symbolic_ref: str | None = None
+    mode: ReplayCommitMode = ReplayCommitMode.UNKNOWN
+    instruction_oids: tuple[str, ...] = ()
+    unmerged_paths: tuple[bytes, ...] = ()
+    fresh: bool = True
+    diagnostic: str = ""
+    pending_step: str = ""
+    # What GitPane itself launched in this worktree when this pause is one of its own; see ReplayLaunch.
+    launch: ReplayLaunch | None = None
+    # True only for unmerged entries that come with no replay marker, sequencer or prepared message (a conflicting stash pop leaves exactly that).
+    # The default stays False and every state rebuilt after a failed read goes through unreadable_replay_state, which drops it:
+    # only the successful read that proved the absence carries it, and replay_may_be_present also checks the state's shape.
+    replay_evidence_absent: bool = False
+
+
+def replay_may_be_present(state: ReplaySnapshot | None) -> bool:
+    """Tell whether the rules reserved for Cherry-pick and Revert apply to this worktree.
+
+    A real or merely possible replay keeps its session open until its merge tool or command has published, and locks conflict writes from every window while one runs.
+    A pause GitPane launched in this run or a native identity counts whatever Git shows now, even nothing. Without either, a worktree where Git shows no operation is
+    released, and so is a conflict proven to carry no replay trace at all: it keeps the behavior it had before replays existed.
+    """
+    if state is None:
+        return False
+    if state.identity is not None or state.launch is not None:
+        return True
+    if state.kind == ReplayKind.ABSENT:
+        return False
+    # Released only on the exact positive proof: the unattributed conflict itself, read successfully, with no trace and nothing saved.
+    # The flag alone is not enough, because it can be copied into a state of another shape that no read ever proved.
+    ordinary_conflict = state.replay_evidence_absent and state.kind == ReplayKind.UNKNOWN and state.pending_step == REPLAY_STEP_UNATTRIBUTED_CONFLICT and bool(state.unmerged_paths)
+    return not ordinary_conflict
+
+
+def unreadable_replay_state(state: ReplaySnapshot, diagnostic: str, **changes: object) -> ReplaySnapshot:
+    """Build the state published after a failed, partial or contradictory read, from the last state that was known.
+
+    The proof that a conflict carries no replay trace belongs to the successful read that produced it. It is dropped here, so a state
+    built from an error or a doubt always counts as a possible replay instead of inheriting an older answer.
+    """
+    return replace(state, kind=ReplayKind.UNKNOWN, fresh=False, replay_evidence_absent=False, diagnostic=diagnostic, **changes)
+
+
+def replay_action_diagnostic(state: ReplaySnapshot, action: ReplayAction, *, busy: bool = False, abort_available: bool = False) -> str:
+    """Tell why Resolve, Continue or Abort is unavailable for this pause, or answer "" when Git's own command may run.
+
+    A pause GitPane launched in this run and a pause started in a terminal in commit mode end with Git's own Continue
+    and Abort, the way a terminal ends them. Continue waits until no conflict is left. A terminal `--no-commit` series
+    and a terminal pause whose commit mode Git's files leave open keep both disabled, with the reason: there Git's
+    Continue could commit the whole index and its Abort could drop staged work.
+    """
+    if busy:
+        return BUSY_ACTION_REASON
+    if action == ReplayAction.RESOLVE and state.unmerged_paths and (state.fresh or state.pending_step == REPLAY_STEP_UNATTRIBUTED_CONFLICT):
+        return ""
+    if not state.fresh or not state.kind.is_replay:
+        return state.diagnostic or "Refresh the current commit operation before continuing."
+    if action == ReplayAction.RESOLVE:
+        return "There are no unresolved merge conflicts."
+    if state.ownership == ReplayOwnership.OWNED and state.launch is not None and state.identity is not None:
+        if action == ReplayAction.ABORT:
+            return "" if abort_available else "Git's own Abort is not available for this operation."
+        return RESOLVE_CONFLICTS_FIRST_REASON if state.unmerged_paths else ""
+    if state.ownership == ReplayOwnership.EXTERNAL and state.identity is not None:
+        series_message = no_commit_series_message(state)
+        if series_message:
+            return series_message
+        if state.mode != ReplayCommitMode.COMMIT:
+            return REPLAY_EXTERNAL_UNKNOWN_MODE_MESSAGE
+        if action == ReplayAction.ABORT:
+            return ""
+        return RESOLVE_CONFLICTS_FIRST_REASON if state.unmerged_paths else ""
+    return "The identity of this operation is unavailable. Refresh to inspect the native operation."
+
+
+def no_commit_series_message(state: ReplaySnapshot) -> str:
+    """Explain what Git does with a terminal `--no-commit` series paused after a conflict and how to end it, or return "" for any other pause.
+
+    The no-commit mode of an external operation is only ever read from Git's sequencer options, so an external pause in that
+    mode is always such a series with instructions left.
+    """
+    if state.ownership != ReplayOwnership.EXTERNAL or state.identity is None or state.mode != ReplayCommitMode.NO_COMMIT:
+        return ""
+    return state.kind.no_commit_series_message
+
+
+def replay_auto_continue_ready(state: ReplaySnapshot) -> bool:
+    """Tell whether a pause may be continued without a click once its last conflict was solved in GitPane.
+
+    Exactly the pauses the banner Continue accepts qualify: a fresh read of a Cherry-pick or Revert with its native
+    identity, no conflict left and a known commit mode. That is a pause GitPane started in this run, which keeps the
+    choice made in the form, or a pause started in a terminal whose commit mode Git's own files establish. An unknown
+    mode, owner or state keeps waiting for the user's own Continue.
+    """
+    if not state.fresh or not state.kind.is_replay or state.identity is None or state.unmerged_paths:
+        return False
+    if state.ownership == ReplayOwnership.OWNED and (state.launch is None or state.mode not in (ReplayCommitMode.COMMIT, ReplayCommitMode.NO_COMMIT)):
+        return False
+    return not replay_action_diagnostic(state, ReplayAction.CONTINUE, abort_available=True)
+
+
+def join_replay_launch(snapshot: ReplaySnapshot, launch: ReplayLaunch | None) -> ReplaySnapshot:
+    """Mark a native pause as GitPane's own when it is exactly the one GitPane launched in this worktree during this run.
+
+    The pause must be a fresh read of the same kind, holding one instruction whose object ID is a prefix of the
+    launched source, on the same HEAD and branch the launch started from. Its commit mode is then the one chosen in
+    the form. Any other state is answered as it was read.
+    """
+    if launch is None or not snapshot.fresh or snapshot.identity is None or snapshot.ownership != ReplayOwnership.EXTERNAL:
+        return snapshot
+    if (snapshot.kind != launch.kind or len(snapshot.instruction_oids) != 1 or not launch.source_oid.startswith(next(iter(snapshot.instruction_oids)))
+            or snapshot.head_oid != launch.original_head_oid or snapshot.symbolic_ref != launch.original_symbolic_ref):
+        return snapshot
+    return replace(snapshot, ownership=ReplayOwnership.OWNED, mode=ReplayCommitMode.COMMIT if launch.create_commit else ReplayCommitMode.NO_COMMIT, launch=launch)
+
+
+@dataclass(frozen=True)
+class ReplayMetadata:
+    """Keep bounded bytes and file signatures for capture and write revalidation."""
+
+    content_by_basename: dict[str, str]
+    signatures: tuple[tuple[int, ...] | None, ...]
+    sequencer: bool
+    head_reference_signatures: tuple[tuple[int, ...] | None, ...] = ()
+
+    def present(self) -> bool:
+        """Detect native replay evidence even when a marker is empty or corrupt."""
+        cherry_index = REPLAY_BASENAMES.index("CHERRY_PICK_HEAD")
+        revert_index = REPLAY_BASENAMES.index("REVERT_HEAD")
+        return self.sequencer or self.signatures[cherry_index] is not None or self.signatures[revert_index] is not None
+
+
+def read_replay_metadata(git_dir: str) -> ReplayMetadata:
+    """Reject linked or changing metadata and bound every filesystem read."""
+    started = time.monotonic()
+    content_by_basename = {}
+    signatures = []
+    total_bytes = 0
+    sequencer_dir = os.path.join(git_dir, SEQUENCER_BASENAME)
+    try:
+        sequencer_metadata = checked_metadata(sequencer_dir, directory=True)
+    except FileNotFoundError:
+        sequencer_metadata = None
+    filenames = []
+    for basename in REPLAY_BASENAMES:
+        filenames.append((basename, os.path.join(git_dir, basename)))
+    if sequencer_metadata is not None:
+        for basename in REPLAY_SEQUENCER_BASENAMES:
+            filenames.append((basename, os.path.join(sequencer_dir, basename)))
+    for basename, filename in filenames:
+        try:
+            before = checked_metadata(filename)
+        except FileNotFoundError:
+            content_by_basename[basename] = ""
+            signatures.append(None)
+            continue
+        if before.st_size > REPLAY_FILE_LIMIT_BYTES:
+            raise ValueError("Native replay metadata exceeds the file limit. Refresh after correcting it externally.")
+        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        with os.fdopen(os.open(filename, flags), "rb") as stream:
+            opened = os.fstat(stream.fileno())
+            # Windows descriptor and path stat disagree about ctime; compare it only within the same API.
+            if metadata_signature(opened, include_change_time=False) != metadata_signature(before, include_change_time=False):
+                raise ValueError("Native replay metadata changed before reading.")
+            if metadata_signature(checked_metadata(filename)) != metadata_signature(before):
+                raise ValueError("Native replay metadata was replaced before reading.")
+            if sequencer_metadata is not None and metadata_signature(checked_metadata(sequencer_dir, directory=True)) != metadata_signature(sequencer_metadata):
+                raise ValueError("Native replay directory changed before reading.")
+            # The size is the one of the descriptor whose identity was just proven, and it is within the limit.
+            content = read_validated_size(stream, opened.st_size)
+            if metadata_signature(os.fstat(stream.fileno())) != metadata_signature(opened):
+                raise ValueError("Native replay metadata changed during reading.")
+        if len(content) != opened.st_size:
+            raise ValueError("Native replay metadata changed during reading.")
+        if metadata_signature(checked_metadata(filename)) != metadata_signature(before):
+            raise ValueError("Native replay metadata was replaced during reading.")
+        total_bytes += len(content)
+        if len(content) > REPLAY_FILE_LIMIT_BYTES or total_bytes > REPLAY_TOTAL_LIMIT_BYTES or (time.monotonic() - started) * 1000 > REPLAY_CAPTURE_TIMEOUT_MS:
+            raise ValueError("Native replay metadata exceeds the read budget.")
+        try:
+            content_by_basename[basename] = content.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise ValueError("Native replay metadata has invalid text encoding.") from error
+        signatures.append(metadata_signature(before))
+    if sequencer_metadata is not None:
+        if metadata_signature(checked_metadata(sequencer_dir, directory=True)) != metadata_signature(sequencer_metadata):
+            raise ValueError("Native replay directory changed during reading.")
+        signatures.append(metadata_signature(sequencer_metadata))
+    elif os.path.lexists(sequencer_dir):
+        raise ValueError("Native replay directory appeared during reading.")
+    return ReplayMetadata(content_by_basename, tuple(signatures), sequencer_metadata is not None)
+
+
+def replay_snapshot_from_metadata(key: WorktreeKey, generation: int, metadata: ReplayMetadata, *, head_oid: str | None = None,
+                                  symbolic_ref: str | None = None, unmerged_paths: tuple[bytes, ...] = ()) -> ReplaySnapshot:
+    """Classify marker and sequencer evidence without guessing a lost user intention."""
+    content_by_basename = metadata.content_by_basename
+    head_text = content_by_basename.get("HEAD", "").strip()
+    if symbolic_ref is None and head_text.startswith("ref: "):
+        symbolic_ref = head_text.removeprefix("ref: ")
+    if not metadata.present():
+        return ReplaySnapshot(key, generation, head_oid=head_oid, symbolic_ref=symbolic_ref, unmerged_paths=unmerged_paths)
+    kind = ReplayKind.UNKNOWN
+    mode = ReplayCommitMode.UNKNOWN
+    instruction_oids = []
+    original_oid = content_by_basename.get("head", "").strip()
+    try:
+        if symbolic_ref is not None and (not symbolic_ref.startswith(LOCAL_PREFIX) or any(part in ("", ".", "..") for part in symbolic_ref.split("/")) or "\\" in symbolic_ref):
+            raise ValueError("Native replay HEAD reference is malformed.")
+        kind_set = set()
+        for basename, marker_kind in (("CHERRY_PICK_HEAD", ReplayKind.CHERRY_PICK), ("REVERT_HEAD", ReplayKind.REVERT)):
+            marker_index = REPLAY_BASENAMES.index(basename)
+            if metadata.signatures[marker_index] is None:
+                continue
+            marker_oid = content_by_basename[basename].strip()
+            if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", marker_oid) is None:
+                raise ValueError("Native replay marker is malformed.")
+            kind_set.add(marker_kind)
+            instruction_oids.append(marker_oid)
+        if metadata.sequencer:
+            if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", original_oid) is None:
+                raise ValueError("Native replay origin is missing or malformed.")
+            instruction_oids = []
+            for line in content_by_basename.get("todo", "").splitlines():
+                if not line.strip() or line.lstrip().startswith("#"):
+                    continue
+                action_index, oid_index, maximum_split = 0, 1, 2
+                parts = line.split(maxsplit=maximum_split)
+                if len(parts) <= oid_index or parts[action_index] not in REPLAY_KIND_BY_ACTION or re.fullmatch(r"[0-9a-f]{4,64}", parts[oid_index]) is None:
+                    raise ValueError("Native replay instructions are malformed or unsupported.")
+                kind_set.add(REPLAY_KIND_BY_ACTION[parts[action_index]])
+                instruction_oids.append(parts[oid_index])
+                if len(instruction_oids) > REPLAY_INSTRUCTION_LIMIT:
+                    raise ValueError("Native replay instructions exceed the supported limit.")
+            if not instruction_oids:
+                raise ValueError("Native replay instructions are missing.")
+            mode = ReplayCommitMode.COMMIT
+            option_text = content_by_basename.get("opts", "")
+            if option_text:
+                parser = configparser.ConfigParser(interpolation=None)
+                parser.read_string(option_text)
+                if parser.sections() != ["options"]:
+                    raise ValueError("Native replay options are malformed.")
+                if parser.has_option("options", SEQUENCER_NO_COMMIT_OPTION):
+                    mode = ReplayCommitMode.NO_COMMIT if parser.getboolean("options", SEQUENCER_NO_COMMIT_OPTION) else ReplayCommitMode.COMMIT
+            safety_oid = content_by_basename.get("abort-safety", "").strip()
+            if safety_oid and re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", safety_oid) is None:
+                raise ValueError("Native replay abort safety is malformed.")
+        if len(kind_set) != 1:
+            raise ValueError("Native replay contains incompatible operation types.")
+        kind = next(iter(kind_set))
+        if not metadata.sequencer and kind == ReplayKind.CHERRY_PICK:
+            mode = ReplayCommitMode.COMMIT
+        identity = ReplayIdentity(kind, original_oid, symbolic_ref, metadata.signatures)
+        diagnostic = "Commit mode is unknown. Refresh or resolve conflicts; do not assume the original commit choice." if mode == ReplayCommitMode.UNKNOWN else ""
+        return ReplaySnapshot(key, generation, kind, ReplayOwnership.EXTERNAL, identity, head_oid, symbolic_ref, mode, tuple(instruction_oids), unmerged_paths, True, diagnostic,
+                              "conflict" if unmerged_paths else "paused")
+    except (ValueError, configparser.Error) as error:
+        diagnostic = str(error) if str(error).startswith("Native replay") else "Native replay options are malformed."
+        return ReplaySnapshot(key, generation, ReplayKind.UNKNOWN, head_oid=head_oid, symbolic_ref=symbolic_ref, unmerged_paths=unmerged_paths, fresh=False, diagnostic=diagnostic)
+
+
+def replay_head_reference_signatures(context: RepositoryContext, metadata: ReplayMetadata) -> tuple[tuple[int, ...] | None, ...]:
+    """Detect a branch moving under an unchanged symbolic HEAD during queued preparation."""
+    head_text = metadata.content_by_basename.get("HEAD", "").strip()
+    if not head_text.startswith("ref: "):
+        return ()
+    full_ref = head_text.removeprefix("ref: ")
+    parts = full_ref.split("/")
+    if not full_ref.startswith(LOCAL_PREFIX) or any(part in ("", ".", "..") for part in parts) or "\\" in full_ref:
+        raise ValueError("Native replay HEAD reference is malformed.")
+    directory = context.common_git_dir
+    for part in parts[:-1]:
+        directory = os.path.join(directory, part)
+        try:
+            checked_metadata(directory, directory=True)
+        except FileNotFoundError:
+            break
+    signatures = []
+    for filename in (os.path.join(context.common_git_dir, *parts), os.path.join(context.common_git_dir, "packed-refs")):
+        try:
+            signatures.append(metadata_signature(checked_metadata(filename)))
+        except FileNotFoundError:
+            signatures.append(None)
+    return tuple(signatures)
+
+
+def _check_native_path(key: WorktreeKey, basename: str, filename: str) -> None:
+    """Refuse a native file that is not the asked one in this worktree's own Git directory."""
+    if canonical_path(os.path.dirname(filename)) != key.git_dir or os.path.basename(filename) != basename:
+        raise ValueError("Native replay path does not belong to this worktree.")
+
+
+@dataclass(frozen=True)
+class ReplayFacts:
+    """HEAD, the branch it names and, when asked, the unmerged entries of an index, read together in one round of Git processes.
+
+    A HEAD without any commit is None, and so is the branch of a detached HEAD; `unmerged_output` is None when the
+    unmerged entries were not asked for.
+    """
+
+    head_oid: str | None
+    symbolic_ref: str | None
+    unmerged_output: bytes | None = None
+
+
+class ReplayCheckoutMismatch(ValueError):
+    """The Git directory or the source commit a launch was prepared for is not the one Git resolves now.
+
+    A capture never turns this into an unreadable state: the launch it checks is refused with this cause.
+    """
+
+
+def _unmerged_command(index_filename: str | None) -> GitCommand:
+    """List the unmerged entries of the live index, or of a private one: only this listing is ever pointed at a private index."""
+    environment_by_name = {} if index_filename is None else {PRIVATE_INDEX_VARIABLE: index_filename}
+    return GitCommand(["ls-files", "--unmerged", "-z"], environment_by_name=environment_by_name)
+
+
+def _decode_oid(answer: bytes) -> str:
+    """Accept one full object ID answered by Git, refusing anything else."""
+    try:
+        return validate_oid(answer.decode("ascii"))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise ValueError("Native replay HEAD or source is malformed.") from error
+
+
+def _decode_branch(answer: bytes) -> str | None:
+    """Accept the full name of the branch HEAD points to, or nothing for a detached HEAD, refusing any other answer."""
+    if not answer:
+        return None
+    try:
+        branch = answer.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ValueError("Native replay HEAD reference is malformed.") from error
+    if not branch.startswith(REFERENCE_ROOT_PREFIX):
+        raise ValueError("Native replay HEAD reference is malformed.")
+    return branch
+
+
+def _checked_facts(key: WorktreeKey, answer_by_name: dict[str, bytes], source_oid: str | None, unmerged_output: bytes | None) -> ReplayFacts:
+    """Check every answer of one read of the replay facts against what was asked, whichever way it was read.
+
+    The Git directory and each native path must be this worktree's own, the source must resolve to exactly the commit
+    that was selected, HEAD must be a full object ID when present and the branch a full reference name.
+    """
+    git_dir_answer = answer_by_name.get(GIT_DIR_ANSWER_NAME)
+    if git_dir_answer is not None and canonical_path(os.fsdecode(git_dir_answer)) != key.git_dir:
+        raise ReplayCheckoutMismatch("The destination worktree changed. Refresh before applying a commit.")
+    for basename in REPLAY_NATIVE_PATH_BASENAMES:
+        path_answer = answer_by_name.get(basename)
+        if path_answer is not None:
+            _check_native_path(key, basename, os.fsdecode(path_answer))
+    if source_oid is not None and _decode_oid(answer_by_name[SOURCE_ANSWER_NAME]) != source_oid:
+        raise ReplayCheckoutMismatch("The selected commit is not the one Git resolves. Refresh before applying a commit.")
+    head_answer = answer_by_name[HEAD_ANSWER_NAME]
+    head_oid = _decode_oid(head_answer) if head_answer else None
+    return ReplayFacts(head_oid, _decode_branch(answer_by_name[BRANCH_ANSWER_NAME]), unmerged_output)
+
+
+def read_replay_facts(context: RepositoryContext, *, include_paths: bool = False, source_oid: str | None = None, verify_git_dir: bool = False,
+                      read_unmerged: bool = False, index_filename: str | None = None) -> Generator[GitCommand | ReadBatch, object, ReplayFacts]:
+    """Read HEAD and its branch in one rev-parse, with the native paths, the source and the Git directory when asked.
+
+    Every Git process costs about 0.1 s on Windows, and this read runs twice in every capture an operation relies on,
+    so one process answers every question and the unmerged listing, when asked, runs beside it. Only a complete
+    answer, one line per question after a successful exit, is used. A HEAD without commit makes rev-parse fail with
+    partial text, and a folder whose name holds a newline gives more lines than questions: both are asked again one
+    question per process. A timeout, a cancellation or any other failure stays a failure and is never asked again.
+    Nothing read here is kept for a later capture.
+    """
+    key = WorktreeKey.from_context(context)
+    if source_oid is not None:
+        validate_oid(source_oid)
+    arguments = ["rev-parse", "--path-format=absolute"]
+    answer_names = []
+    if verify_git_dir:
+        arguments.append("--absolute-git-dir")
+        answer_names.append(GIT_DIR_ANSWER_NAME)
+    if include_paths:
+        for basename in REPLAY_NATIVE_PATH_BASENAMES:
+            arguments.extend(["--git-path", basename])
+            answer_names.append(basename)
+    if source_oid is not None:
+        # No --end-of-options here: without --verify, rev-parse copies it into its answer. The object ID was validated above.
+        arguments.append(source_oid + COMMIT_PEEL_SUFFIX)
+        answer_names.append(SOURCE_ANSWER_NAME)
+    # rev-parse answers --symbolic-full-name HEAD with the branch HEAD points to, or with the word HEAD when it is detached.
+    arguments.extend(["HEAD", "--symbolic-full-name", "HEAD"])
+    answer_names.extend([HEAD_ANSWER_NAME, BRANCH_ANSWER_NAME])
+    commands = [GitCommand(arguments, profile=READ_PROFILE)]
+    if read_unmerged:
+        commands.append(_unmerged_command(index_filename))
+    try:
+        outputs = yield ReadBatch(tuple(commands))
+    except GitCommandError as error:
+        if error.process_status != ProcessStatus.FAILED or error.return_code != UNRESOLVED_REVISION_RETURN_CODE:
+            raise
+        return (yield from _read_replay_facts_separately(key, answer_names, source_oid, read_unmerged, index_filename))
+    grouped_output = outputs[GROUPED_ANSWER_POSITION]
+    lines = grouped_output.split(b"\n")
+    # A complete answer is one line per question, each ended by a newline, so the last piece of the split is empty.
+    if len(lines) != len(answer_names) + TRAILING_EMPTY_PIECE_COUNT or lines[-1]:
+        return (yield from _read_replay_facts_separately(key, answer_names, source_oid, read_unmerged, index_filename))
+    answer_by_name = dict(zip(answer_names, lines, strict=False))
+    if answer_by_name[BRANCH_ANSWER_NAME] == DETACHED_HEAD_ANSWER:
+        answer_by_name[BRANCH_ANSWER_NAME] = b""
+    unmerged_output = outputs[UNMERGED_ANSWER_POSITION] if read_unmerged else None
+    return _checked_facts(key, answer_by_name, source_oid, unmerged_output)
+
+
+def _read_replay_facts_separately(key: WorktreeKey, answer_names: list[str], source_oid: str | None, read_unmerged: bool,
+                                  index_filename: str | None) -> Generator[GitCommand | ReadBatch, object, ReplayFacts]:
+    """Ask each question of a grouped read in its own process, when the grouped answer failed or cannot be split safely.
+
+    HEAD is read with --verify --quiet, so a HEAD without commit answers nothing, and the branch with symbolic-ref;
+    only the line ending Git adds is removed from each answer, never a space or a newline that belongs to a folder name.
+    """
+    commands = []
+    for answer_name in answer_names:
+        if answer_name == GIT_DIR_ANSWER_NAME:
+            commands.append(GitCommand(["rev-parse", "--absolute-git-dir"]))
+        elif answer_name == SOURCE_ANSWER_NAME:
+            commands.append(GitCommand(["rev-parse", "--verify", "--end-of-options", source_oid + COMMIT_PEEL_SUFFIX], profile=READ_PROFILE))
+        elif answer_name == HEAD_ANSWER_NAME:
+            commands.append(GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1)))
+        elif answer_name == BRANCH_ANSWER_NAME:
+            commands.append(GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1)))
+        else:
+            commands.append(GitCommand(["rev-parse", "--path-format=absolute", "--git-path", answer_name], profile=READ_PROFILE))
+    if read_unmerged:
+        commands.append(_unmerged_command(index_filename))
+    outputs = yield ReadBatch(tuple(commands))
+    answer_by_name = {}
+    for answer_name, output in zip(answer_names, outputs, strict=False):
+        answer_by_name[answer_name] = output.removesuffix(b"\n")
+    unmerged_output = outputs[len(answer_names)] if read_unmerged else None
+    return _checked_facts(key, answer_by_name, source_oid, unmerged_output)
+
+
+def _unreadable_capture(key: WorktreeKey, generation: int, error: Exception) -> ReplaySnapshot:
+    """Describe a capture that could not safely read the native state, keeping the native cause when there is one."""
+    diagnostic = str(error) if isinstance(error, ValueError) and str(error).startswith("Native replay") else "Cannot safely read the native replay state. Refresh to try again."
+    return ReplaySnapshot(key, generation, ReplayKind.UNKNOWN, fresh=False, diagnostic=diagnostic)
+
+
+def _finish_replay_capture(context: RepositoryContext, key: WorktreeKey, generation: int, metadata: ReplayMetadata, head_oid: str | None,
+                           symbolic_ref: str | None, unmerged_paths: tuple[bytes, ...], *,
+                           lone_message_is_trace: bool = False) -> Generator[GitCommand | FileTask, object, ReplaySnapshot]:
+    """Classify a replay state whose facts are known, the same way wherever those facts come from.
+
+    Git's prepared message left alone, without any conflict, is no operation for Git when its references are files:
+    `git status` shows a clean checkout, and Git Extensions leaves exactly that after a Revert that brings nothing. It
+    is then read as the trace of a replay without a commit only right after GitPane's own launch
+    (``lone_message_is_trace``), which ends it with Git's own Quit; anywhere else it is ignored, as Git ignores it,
+    rather than locking every write of the repository. A reference table keeps CHERRY_PICK_HEAD and REVERT_HEAD out
+    of the files read here, so there the message alone may still be a pause in progress and keeps counting as one.
+    """
+    snapshot = replay_snapshot_from_metadata(key, generation, metadata, head_oid=head_oid, symbolic_ref=symbolic_ref, unmerged_paths=unmerged_paths)
+    message_trace = False
+    if metadata.content_by_basename.get(MERGE_MESSAGE_BASENAME) and not unmerged_paths:
+        message_trace = lone_message_is_trace or (yield FileTask(lambda: os.path.isdir(os.path.join(context.common_git_dir, GIT_REFTABLE_DIR_BASENAME))))
+    if snapshot.kind == ReplayKind.ABSENT and (unmerged_paths or message_trace) and not metadata.content_by_basename.get(MERGE_HEAD_BASENAME):
+        other_operation = yield FileTask(lambda: any(os.path.lexists(os.path.join(context.git_dir, name)) for name in ("rebase-merge", "rebase-apply")))
+        if not other_operation:
+            # Existence rather than content: an empty prepared message is still a trace of a no-commit replay.
+            message_absent = metadata.signatures[REPLAY_BASENAMES.index(MERGE_MESSAGE_BASENAME)] is None
+            return ReplaySnapshot(key, generation, ReplayKind.UNKNOWN, head_oid=snapshot.head_oid, symbolic_ref=snapshot.symbolic_ref,
+                                  unmerged_paths=snapshot.unmerged_paths, fresh=False, pending_step=REPLAY_STEP_UNATTRIBUTED_CONFLICT, replay_evidence_absent=message_absent,
+                                  diagnostic="Native conflict evidence has no replay identity. The original operation and commit mode are unknown.")
+    if snapshot.kind != ReplayKind.ABSENT:
+        incompatible = yield FileTask(lambda: any(os.path.lexists(os.path.join(context.git_dir, name)) for name in ("rebase-merge", "rebase-apply", MERGE_HEAD_BASENAME)))
+        if incompatible:
+            return unreadable_replay_state(snapshot, "Incompatible native operations are present. Inspect them in the terminal.")
+    return snapshot
+
+
+def native_file_look(git_dir: str) -> tuple[tuple[int, ...] | None, ...]:
+    """Take the metadata, never the content, of HEAD and of every file and folder Git keeps for a paused cherry-pick or revert.
+
+    Nothing is opened, so the look is safe before Git has confirmed where these files live. A missing path is None; a
+    link or a special file is refused the way the full read refuses it.
+    """
+    signatures = []
+    for basename in REPLAY_NATIVE_PATH_BASENAMES:
+        filename = os.path.join(git_dir, basename)
+        try:
+            signatures.append(metadata_signature(checked_metadata(filename, directory=basename == SEQUENCER_BASENAME)))
+        except FileNotFoundError:
+            signatures.append(None)
+    return tuple(signatures)
+
+
+def capture_replay(context: RepositoryContext, generation: int, *, source_oid: str | None = None, verify_git_dir: bool = False,
+                   lone_message_is_trace: bool = False) -> Generator[GitCommand | FileTask | ReadBatch, object, ReplaySnapshot]:
+    """Read HEAD, its branch, the conflicts and the native files once, the way Git itself shows them.
+
+    Everything is read through Git: this is the capture operations and the observations a user asks for rely on. One
+    grouped read locates the native files before any of them is opened, checks the source commit and the Git directory
+    a launch was prepared for, when given, and lists the conflicts beside it; the native files are read once after it.
+    Git is trusted to keep its own files consistent, as it is for a rebase, so no Git process runs a second time. Only
+    the metadata of the native files, never their content, is looked at before and after the whole read: a pause that
+    appears or ends while Git answers would otherwise mix HEAD from before with markers from after.
+
+    ``lone_message_is_trace`` is set only by the read that follows GitPane's own launch; see _finish_replay_capture.
+    """
+    key = WorktreeKey.from_context(context)
+    if context.is_bare:
+        return ReplaySnapshot(key, generation)
+    try:
+        started = time.monotonic()
+        look_before = yield FileTask(lambda: native_file_look(context.git_dir))
+        facts = yield from read_replay_facts(context, include_paths=True, source_oid=source_oid, verify_git_dir=verify_git_dir, read_unmerged=True)
+        metadata, look_after = yield FileTask(lambda: (read_replay_metadata(context.git_dir), native_file_look(context.git_dir)))
+        if look_before != look_after:
+            raise ValueError("Native replay changed during observation. Refresh to inspect its current state.")
+        if (time.monotonic() - started) * 1000 > REPLAY_CAPTURE_TIMEOUT_MS:
+            raise ValueError("Native replay took too long to read. Refresh to inspect its current state.")
+        path_set = set()
+        for record in facts.unmerged_output.split(b"\0"):
+            if record:
+                _stage, separator, path = record.partition(b"\t")
+                if not separator:
+                    raise ValueError("Native replay conflict data is malformed.")
+                path_set.add(path)
+        return (yield from _finish_replay_capture(context, key, generation, metadata, facts.head_oid, facts.symbolic_ref, tuple(sorted(path_set)),
+                                                  lone_message_is_trace=lone_message_is_trace))
+    except ReplayCheckoutMismatch:
+        raise
+    except (OSError, ValueError) as error:
+        return _unreadable_capture(key, generation, error)
+
+
+def capture_replay_passive(context: RepositoryContext, generation: int,
+                           source: PassiveObservationSource) -> Generator[GitCommand | FileTask, object, ReplaySnapshot]:
+    """Follow a cherry-pick or revert state for the banner with what the automatic refresh has just read; never called by an operation."""
+    key = WorktreeKey.from_context(context)
+    if context.is_bare:
+        return ReplaySnapshot(key, generation)
+    try:
+        for basename in REPLAY_NATIVE_PATH_BASENAMES:
+            # The pause probe has no path for HEAD: Git always keeps it in the worktree's own Git directory, and its content
+            # only stands in for the branch name.
+            if basename == HEAD_BASENAME:
+                continue
+            filename = source.filename_by_git_path.get(basename)
+            if filename is None:
+                raise ValueError("Native replay path does not belong to this worktree.")
+            _check_native_path(key, basename, filename)
+        metadata = yield FileTask(lambda: read_replay_metadata(context.git_dir))
+        return (yield from _finish_replay_capture(context, key, generation, metadata, source.head_oid, source.branch_head, source.unmerged_paths))
+    except (OSError, ValueError) as error:
+        return _unreadable_capture(key, generation, error)