gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/rebase_state.py

@@ -0,0 +1,523 @@
+"""Read native rebase metadata without owning or advancing the Git operation."""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import time
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+from gitpane.config import LOCAL_PREFIX, REBASE_CAPTURE_ATTEMPTS, REBASE_CAPTURE_TIMEOUT_MS, REBASE_FILE_LIMIT_BYTES, REBASE_STEP_LIMIT, REBASE_TOTAL_LIMIT_BYTES, SHORT_OID_LENGTH
+from gitpane.process.process_runner import READ_PROFILE
+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 Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.worktree.worktree_snapshot import PassiveObservationSource
+
+# The two folders Git keeps a stopped rebase in, one per backend.
+MERGE_STATE_DIR_BASENAME = "rebase-merge"
+REBASE_STATE_DIR_BASENAMES = (MERGE_STATE_DIR_BASENAME, "rebase-apply")
+DONE_BASENAME = "done"
+REBASE_BASENAMES = ("orig-head", "onto", "head-name", DONE_BASENAME, "git-rebase-todo", "stopped-sha", "amend", "msgnum", "end", "next", "last")
+REBASE_ACTION_BY_ALIAS = {"p": "pick", "r": "reword", "e": "edit", "s": "squash", "f": "fixup", "d": "drop"}
+REBASE_COMMIT_ACTION_SET = frozenset((*REBASE_ACTION_BY_ALIAS.values(),))
+
+
+@dataclass(frozen=True)
+class RebaseStep:
+    """Retain the native instruction, including opaque actions we cannot classify."""
+
+    action: str
+    oid: str
+    message: str
+    raw: str
+    opaque: bool = False
+
+
+@dataclass(frozen=True)
+class RebaseIdentity:
+    """Identify a native operation independently of its moving replay HEAD."""
+
+    backend: str
+    state_dir: str
+    original_oid: str
+    onto_oid: str
+    head_name: str
+    creation_fingerprint: tuple[int, int, int]
+
+
+@dataclass(frozen=True)
+class RebaseCommit:
+    """Describe an original commit for display without changing its native instruction."""
+
+    oid: str
+    author_name: str
+    author_timestamp: int
+
+
+# States of a rebase stopped and waiting for the user. Its instructions can be edited then, and only the writes that help
+# finish the rebase are allowed: staging, conflict tools, Continue, Abort, and Amend on an edit stop.
+REBASE_STOPPED_STATE_SET = frozenset(("edit", "conflict", "paused", "intervention_required"))
+# Stopped states Continue can resume. A conflict is left out: it must be resolved and staged first, which turns it into
+# "paused".
+REBASE_CONTINUABLE_STATE_SET = frozenset(("edit", "paused", "intervention_required"))
+
+
+@dataclass(frozen=True)
+class RebaseSnapshot:
+    """Publish immutable native facts bound to a worktree and observation generation.
+
+    `state` is one of: absent, starting, edit, conflict, paused (conflicts resolved and staged, Continue expected), intervention_required,
+    unknown or external-change.
+    """
+
+    key: WorktreeKey
+    generation: int
+    identity: RebaseIdentity | None = None
+    head_oid: str | None = None
+    original_branch: str = ""
+    state: str = "absent"
+    fresh: bool = True
+    diagnostic: str = ""
+    done_steps: tuple[RebaseStep, ...] = ()
+    current_step: RebaseStep | None = None
+    remaining_steps: tuple[RebaseStep, ...] = ()
+    opaque_steps: tuple[RebaseStep, ...] = ()
+    # Whether the index still held a conflict when this state was captured.
+    unmerged: bool = False
+    # The native files of each rebase state folder (None for an absent folder) that this capture proved stable. It only
+    # lets a display tell later whether those files are still the same; it never authorizes a command. None means no
+    # such proof is available: a failed, stale or rebuilt state never carries one.
+    native_observations: tuple[NativeMetadata | None, ...] | None = field(default=None, hash=False)
+    # True only on the first absent state read after a rebase GitPane knew ended without a command of GitPane (a quit,
+    # an abort or a continue made in a terminal): the views follow the new state once, without a banner.
+    ended_outside: bool = False
+    # The paths still in conflict when this state was captured, sorted and without repeats, so a stop can name them.
+    conflict_paths: tuple[bytes, ...] = ()
+
+
+# The one line the views show when a rebase ended without a command of GitPane.
+REBASE_ENDED_OUTSIDE_MESSAGE = "Rebase ended outside GitPane."
+
+
+def ended_outside_state(state: RebaseSnapshot) -> RebaseSnapshot:
+    """Mark an absent state that follows a rebase GitPane knew as ended elsewhere, for its one publication."""
+    return replace(state, diagnostic=REBASE_ENDED_OUTSIDE_MESSAGE, ended_outside=True)
+
+
+def read_rebase_commits(steps: tuple[RebaseStep, ...]) -> Generator[GitCommand, bytes, tuple[RebaseCommit, ...]]:
+    """Read original authors and dates independently of native state and recovery commands."""
+    oid_set = set()
+    for step in steps:
+        if step.oid:
+            oid_set.add(step.oid)
+    if not oid_set:
+        return ()
+    try:
+        # Stdin avoids Windows command-length limits for large instruction lists.
+        output = yield GitCommand(["log", "--no-walk", "--ignore-missing", "--no-decorate", "--no-notes", "--no-show-signature", "--encoding=UTF-8",
+                                   "-z", "--format=%H%x00%an%x00%at", "--stdin"], stdin=("\n".join(sorted(oid_set)) + "\n").encode("ascii"))
+        fields = output.decode("utf-8", errors="replace").rstrip("\0").split("\0")
+        field_count = 3
+        oid_offset, author_offset, timestamp_offset = 0, 1, 2
+        commits = []
+        for index in range(0, len(fields) - field_count + 1, field_count):
+            commits.append(RebaseCommit(fields[index + oid_offset], fields[index + author_offset], int(fields[index + timestamp_offset])))
+        return tuple(commits)
+    except (GitCommandError, ValueError):
+        return ()
+
+
+def can_abort_rebase(snapshot: RebaseSnapshot) -> bool:
+    """Permit native abandonment only when the backend and original checkout are readable."""
+    identity = snapshot.identity
+    return (snapshot.fresh and identity is not None and identity.backend in REBASE_STATE_DIR_BASENAMES
+            and snapshot.state not in ("absent", "external-change")
+            and re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", identity.original_oid) is not None
+            and (identity.head_name.startswith(LOCAL_PREFIX) or identity.head_name == "detached HEAD"))
+
+
+# Recent Git (2.53 on Ubuntu 26) writes "pick <oid> # <subject>" where Git for Windows 2.47 writes "pick <oid> <subject>".
+# Everything after the hash is a comment for Git either way; only the marker is removed from the displayed subject.
+REBASE_SUBJECT_COMMENT_MARKER = "# "
+
+
+def parse_steps(content: str) -> tuple[RebaseStep, ...]:
+    """Preserve native ordering and expose unsupported instructions as plain text.
+
+    The subject shown for a step is read in both instruction formats Git writes, with or without a comment marker
+    between the hash and the subject.
+    """
+    steps = []
+    for raw in content.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        first_index, oid_index, message_index = 0, 1, 2
+        parts = raw.split(maxsplit=message_index)
+        action = parts[first_index]
+        action = REBASE_ACTION_BY_ALIAS.get(action, action)
+        if action == "fixup" and len(parts) > oid_index and parts[oid_index] in ("-C", "-c"):
+            # Git's fixup message flags precede the hash but do not change its identity.
+            parts = (parts[first_index] + " " + (parts[message_index] if len(parts) > message_index else "")).split(maxsplit=message_index)
+        oid = parts[oid_index] if len(parts) > oid_index else ""
+        message = parts[message_index] if len(parts) > message_index else ""
+        message = message.removeprefix(REBASE_SUBJECT_COMMENT_MARKER)
+        opaque = action not in REBASE_COMMIT_ACTION_SET or re.fullmatch(r"[0-9a-f]{4,64}", oid) is None
+        steps.append(RebaseStep(action, "" if opaque else oid, raw if opaque else message, raw, opaque))
+        if len(steps) > REBASE_STEP_LIMIT:
+            raise ValueError("Native rebase exceeds the supported instruction limit")
+    return tuple(steps)
+
+
+# Git lists in this file the commits a squash or fixup chain has folded so far, one instruction per line without its
+# subject, and removes it once the chain is committed. It is read only to show which commits a message is about, so it
+# stays out of REBASE_BASENAMES: that list is the signature of the observation, and this file comes and goes during
+# every squash.
+CURRENT_FIXUPS_BASENAME = "current-fixups"
+
+
+@dataclass(frozen=True)
+class RebaseMessageCommit:
+    """One commit a message Git asks for during a rebase is about, as the header of the message window shows it."""
+
+    short_oid: str
+    subject: str
+
+
+def _read_display_text(filename: str) -> str:
+    """Read one of Git's rebase files for display: empty when absent, refused when it is a link, a special file or too large.
+
+    The bytes are decoded with replacement characters, since nothing is decided on this text.
+    """
+    try:
+        metadata = checked_metadata(filename)
+    except FileNotFoundError:
+        return ""
+    if metadata.st_size > REBASE_FILE_LIMIT_BYTES:
+        raise ValueError("Native rebase metadata exceeds the supported file limit")
+    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:
+        data = stream.read(REBASE_FILE_LIMIT_BYTES + 1)
+    if len(data) > REBASE_FILE_LIMIT_BYTES:
+        raise ValueError("Native rebase metadata exceeds the supported file limit")
+    return data.decode("utf-8", errors="replace")
+
+
+def read_message_context(git_dir: str) -> tuple[RebaseMessageCommit, ...]:
+    """Name the commits a commit message Git asks for right now is about, from Git's own rebase files.
+
+    rebase-merge/done ends with the instruction being applied. Without current-fixups the message is a reword's: its
+    commit is the last instruction. With current-fixups, its N lines are the commits a squash or fixup chain folded,
+    the last N instructions, and the instruction before them is the commit they fold into. The comments Git writes in
+    the message are never read: their count does not follow the chain. Nothing is named when done is absent, unreadable
+    or holds no commit, so the header falls back to the repository alone.
+    """
+    state_dir = os.path.join(git_dir, MERGE_STATE_DIR_BASENAME)
+    try:
+        steps = parse_steps(_read_display_text(os.path.join(state_dir, DONE_BASENAME)))
+        fixup_count = 0
+        for line in _read_display_text(os.path.join(state_dir, CURRENT_FIXUPS_BASENAME)).splitlines():
+            if line.strip():
+                fixup_count += 1
+    except (OSError, ValueError):
+        return ()
+    base_count = 1
+    commits = []
+    for step in steps[-(fixup_count + base_count):]:
+        if step.oid:
+            commits.append(RebaseMessageCommit(step.oid[:SHORT_OID_LENGTH], step.message))
+    return tuple(commits)
+
+
+@dataclass(frozen=True)
+class NativeMetadata:
+    """Retain file identity as well as bytes so replacements invalidate a capture."""
+
+    creation_fingerprint: tuple[int, int, int]
+    content_by_basename: dict[str, str]
+    signatures: tuple[tuple[int, ...] | None, ...]
+
+
+def metadata_signature(metadata: os.stat_result, *, include_change_time: bool = True) -> tuple[int, ...]:
+    """Compare file identity, size and timestamps across the whole observation."""
+    return (metadata.st_dev, metadata.st_ino, metadata.st_mode, metadata.st_size, metadata.st_mtime_ns,
+            metadata.st_ctime_ns if include_change_time else 0, metadata.st_nlink)
+
+
+def checked_metadata(filename: str, *, directory: bool = False) -> os.stat_result:
+    """Reject links, special files and Windows reparse points before reading bytes."""
+    metadata = os.lstat(filename)
+    expected_type = stat.S_ISDIR if directory else stat.S_ISREG
+    if not expected_type(metadata.st_mode) or getattr(metadata, "st_reparse_tag", 0) or not directory and metadata.st_nlink != 1:
+        raise ValueError("Native rebase metadata has an unsupported file type or link")
+    return metadata
+
+
+def read_metadata(state_dir: str) -> NativeMetadata | None:
+    """Bound native file reads and verify their opened identity before consuming bytes."""
+    try:
+        metadata = checked_metadata(state_dir, directory=True)
+    except FileNotFoundError:
+        return None
+    content_by_basename = {}
+    signatures = [metadata_signature(metadata)]
+    total_bytes = 0
+    started = time.monotonic()
+    for basename in REBASE_BASENAMES:
+        filename = os.path.join(state_dir, basename)
+        try:
+            before = checked_metadata(filename)
+        except FileNotFoundError:
+            content_by_basename[basename] = ""
+            signatures.append(None)
+            continue
+        if before.st_size > REBASE_FILE_LIMIT_BYTES:
+            raise ValueError("Native rebase metadata exceeds the supported file limit")
+        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        descriptor = os.open(filename, flags)
+        with os.fdopen(descriptor, "rb") as stream:
+            opened = os.fstat(stream.fileno())
+            # Windows path stat and descriptor stat can expose different ctime
+            # meanings; compare that timestamp only within the same API.
+            if (metadata_signature(opened, include_change_time=False) != metadata_signature(before, include_change_time=False)
+                    or metadata_signature(checked_metadata(filename)) != metadata_signature(before)
+                    or metadata_signature(checked_metadata(state_dir, directory=True)) != metadata_signature(metadata)):
+                raise ValueError("Native rebase metadata 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 rebase metadata changed while reading")
+        if len(content) != opened.st_size:
+            raise ValueError("Native rebase metadata changed while reading")
+        total_bytes += len(content)
+        if len(content) > REBASE_FILE_LIMIT_BYTES or total_bytes > REBASE_TOTAL_LIMIT_BYTES or (time.monotonic() - started) * 1000 > REBASE_CAPTURE_TIMEOUT_MS:
+            raise ValueError("Native rebase metadata exceeds the supported read budget")
+        signatures.append(metadata_signature(before))
+        try:
+            content_by_basename[basename] = content.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise ValueError("Native rebase metadata uses unsupported UTF-8 encoding. Correct it externally, then Refresh.") from error
+    if metadata_signature(checked_metadata(state_dir, directory=True)) != metadata_signature(metadata):
+        raise ValueError("Native rebase directory changed while reading")
+    # Unix ctime changes as Git edits directory entries; only birth time, when
+    # supplied by the OS, can supplement the stable device/inode identity.
+    creation = (metadata.st_dev, metadata.st_ino, getattr(metadata, "st_birthtime_ns", 0))
+    return NativeMetadata(creation, content_by_basename, tuple(signatures))
+
+
+def _checked_state_dir(key: WorktreeKey, backend: str, state_dir: str) -> str:
+    """Refuse a rebase state folder that is not the asked one in this worktree's own Git directory."""
+    if canonical_path(os.path.dirname(state_dir)) != key.git_dir or os.path.basename(state_dir) != backend:
+        raise ValueError("Native rebase path does not belong to this worktree")
+    return state_dir
+
+
+def _read_state_dirs(key: WorktreeKey) -> Generator[GitCommand | ReadBatch, object, list[str]]:
+    """Ask Git where this worktree keeps both rebase state folders, and check each answer."""
+    arguments = ["rev-parse", "--path-format=absolute"]
+    for backend in REBASE_STATE_DIR_BASENAMES:
+        arguments.extend(["--git-path", backend])
+    # One process answers for both folders; a newline is valid inside a folder name, so a count that does not match
+    # asks each folder alone to keep every path whole.
+    output = yield GitCommand(arguments, profile=READ_PROFILE)
+    outputs = output.removesuffix(b"\n").split(b"\n")
+    if len(outputs) != len(REBASE_STATE_DIR_BASENAMES):
+        commands = []
+        for backend in REBASE_STATE_DIR_BASENAMES:
+            commands.append(GitCommand(["rev-parse", "--path-format=absolute", "--git-path", backend], profile=READ_PROFILE))
+        outputs = yield ReadBatch(tuple(commands))
+    state_dirs = []
+    for backend, path_output in zip(REBASE_STATE_DIR_BASENAMES, outputs, strict=True):
+        state_dirs.append(_checked_state_dir(key, backend, os.fsdecode(path_output).strip()))
+    return state_dirs
+
+
+def state_dirs_from_pause_paths(key: WorktreeKey, filename_by_git_path: dict[str, str]) -> list[str]:
+    """Take both rebase state folders from the paths Git gave the session's pause probe, checking that each is this worktree's own."""
+    state_dirs = []
+    for backend in REBASE_STATE_DIR_BASENAMES:
+        state_dir = filename_by_git_path.get(backend)
+        if state_dir is None:
+            raise ValueError("Native rebase path does not belong to this worktree")
+        state_dirs.append(_checked_state_dir(key, backend, state_dir))
+    return state_dirs
+
+
+def native_observations_unchanged(state_dirs: list[str], observations: tuple[NativeMetadata | None, ...]) -> bool:
+    """Tell whether the native rebase files are still exactly the ones a stable capture proved, absences included.
+
+    Runs on a worker. A read that fails is propagated, never taken for a match.
+    """
+    current = []
+    for state_dir in state_dirs:
+        current.append(read_metadata(state_dir))
+    return tuple(current) == observations
+
+
+def staged_change_command() -> GitCommand:
+    """Ask whether the index differs from HEAD, which tells a stop whose conflicts were resolved and staged from one that needs a correction."""
+    return GitCommand(["diff-index", "--cached", "--name-only", "-z", "HEAD"], accepted_codes=(0, 128))
+
+
+def _capture_rebase_attempts(key: WorktreeKey, generation: int, state_dirs: list[str],
+                             read_facts: Callable[[], Generator[GitCommand | ReadBatch, object, tuple[bytes, bytes, bytes]]], *,
+                             confirm_facts: bool) -> Generator[GitCommand | FileTask | ReadBatch, object, RebaseSnapshot]:
+    """Read the native files around the HEAD, conflict and index facts until two looks agree, within bounded attempts and time.
+
+    With `confirm_facts` the facts are read a second time after the files and must not have moved either.
+    """
+    started = time.monotonic()
+    for _attempt in range(REBASE_CAPTURE_ATTEMPTS):
+        try:
+            before = yield FileTask(lambda: tuple(read_metadata(directory) for directory in state_dirs))
+            if not any(before):
+                after = yield FileTask(lambda: tuple(read_metadata(directory) for directory in state_dirs))
+                if before == after:
+                    return RebaseSnapshot(key, generation, native_observations=before)
+                continue
+            first_facts = yield from read_facts()
+            after = yield FileTask(lambda: tuple(read_metadata(directory) for directory in state_dirs))
+            last_facts = first_facts
+            if confirm_facts:
+                last_facts = yield from read_facts()
+            if before == after and first_facts == last_facts and (time.monotonic() - started) * 1000 <= REBASE_CAPTURE_TIMEOUT_MS:
+                head_output, unmerged, staged = first_facts
+                path_set = set(unmerged.split(b"\0"))
+                path_set.discard(b"")
+                snapshot = snapshot_from_metadata(key, generation, state_dirs, before, head_output.decode().strip() or None, bool(unmerged), staged_change=bool(staged))
+                return replace(snapshot, conflict_paths=tuple(sorted(path_set)))
+        except (OSError, ValueError):
+            if _attempt == REBASE_CAPTURE_ATTEMPTS - 1:
+                raise
+        if (time.monotonic() - started) * 1000 > REBASE_CAPTURE_TIMEOUT_MS:
+            break
+    raise ValueError("Native rebase changed during observation. Refresh to try again.")
+
+
+def unmerged_paths_output(listing: bytes) -> bytes:
+    """Keep only the paths of an `ls-files --unmerged -z` listing, separated by NUL, in the form the automatic refresh hands over.
+
+    Each record is the mode, object ID and stage, a tab, then the path; a record without its tab is refused.
+    """
+    paths = []
+    for record in listing.split(b"\0"):
+        if not record:
+            continue
+        _stage, separator, path = record.partition(b"\t")
+        if not separator:
+            raise ValueError("Native rebase conflict data is malformed.")
+        paths.append(path)
+    return b"\0".join(paths)
+
+
+def capture_rebase(context: RepositoryContext, generation: int) -> Generator[GitCommand | FileTask | ReadBatch, object, RebaseSnapshot]:
+    """Retry changing native captures within bounded attempts and total elapsed time.
+
+    Everything is read again through Git: this is the capture operations and the observations a user asks for rely on.
+    """
+    key = WorktreeKey.from_context(context)
+    if context.is_bare:
+        return RebaseSnapshot(key, generation)
+    state_dirs = yield from _read_state_dirs(key)
+
+    def read_facts() -> Generator[ReadBatch, object, tuple[bytes, bytes, bytes]]:
+        """Read HEAD, the unmerged paths and whether the index differs from HEAD, in one batch."""
+        head_output, unmerged_listing, staged = yield ReadBatch((GitCommand(["rev-parse", "--verify", "HEAD"], accepted_codes=(0, 128)),
+                                                                 GitCommand(["ls-files", "--unmerged", "-z"]), staged_change_command()))
+        return head_output, unmerged_paths_output(unmerged_listing), staged
+
+    return (yield from _capture_rebase_attempts(key, generation, state_dirs, read_facts, confirm_facts=True))
+
+
+def capture_rebase_passive(context: RepositoryContext, generation: int,
+                           source: PassiveObservationSource) -> Generator[GitCommand | FileTask | ReadBatch, object, RebaseSnapshot]:
+    """Follow the rebase 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 RebaseSnapshot(key, generation)
+    state_dirs = state_dirs_from_pause_paths(key, source.filename_by_git_path)
+
+    def read_facts() -> Generator[GitCommand, object, tuple[bytes, bytes, bytes]]:
+        """Answer HEAD and the conflicts from the status, and ask Git only whether the index differs from HEAD."""
+        staged = b""
+        # This fact follows the submodule settings while the status of the display reads every submodule, so it is
+        # asked of Git as the other capture does, and only without a conflict: the only case the classification reads it.
+        if not source.unmerged_paths:
+            staged = yield staged_change_command()
+        return (source.head_oid or "").encode("ascii"), b"\0".join(source.unmerged_paths), staged
+
+    return (yield from _capture_rebase_attempts(key, generation, state_dirs, read_facts, confirm_facts=False))
+
+
+def snapshot_from_metadata(key: WorktreeKey, generation: int, state_dirs: list[str], observations: tuple[NativeMetadata | None, ...],
+                           head_oid: str | None, unmerged: bool, *, staged_change: bool = False) -> RebaseSnapshot:
+    """Classify a coherent native capture without inventing progress for opaque lines.
+
+    `staged_change` tells whether the index differs from HEAD; without it a stop whose conflicts were resolved and staged
+    cannot be told apart from one that still needs a manual correction.
+    """
+    present_count = sum(observed is not None for observed in observations)
+    for state_dir, observed in zip(state_dirs, observations, strict=True):
+        if observed is None:
+            continue
+        content_by_basename = observed.content_by_basename
+        backend = os.path.basename(state_dir)
+        identity = RebaseIdentity(backend, os.path.normcase(state_dir), content_by_basename["orig-head"].strip(),
+                                  content_by_basename["onto"].strip(), content_by_basename["head-name"].strip(), observed.creation_fingerprint)
+        done_steps = parse_steps(content_by_basename["done"])
+        remaining_steps = parse_steps(content_by_basename["git-rebase-todo"])
+        opaque_steps = []
+        for step in (*done_steps, *remaining_steps):
+            if step.opaque:
+                opaque_steps.append(step)
+        current_step = None
+        state = "unknown"
+        diagnostic = "Native rebase is present; refresh to inspect its current state."
+        complete_identity = (re.fullmatch(r"[0-9a-f]{40,64}", identity.original_oid) is not None
+                             and re.fullmatch(r"[0-9a-f]{40,64}", identity.onto_oid) is not None and bool(identity.head_name))
+        todo_signature_index = REBASE_BASENAMES.index("git-rebase-todo") + 1
+        missing_todo = backend == "rebase-merge" and observed.signatures[todo_signature_index] is None
+        if backend == "rebase-merge" and present_count == 1 and complete_identity:
+            state = "intervention_required"
+            diagnostic = "Git needs intervention. Review the Git output; edit the instructions or correct the repository externally, then Refresh. You can also abort the rebase."
+        if backend == "rebase-merge" and done_steps and present_count == 1:
+            last_step_index = len(done_steps) - 1
+            candidate = done_steps[last_step_index]
+            stopped_oid = content_by_basename["stopped-sha"].strip()
+            amend_oid = content_by_basename["amend"].strip()
+            if candidate.oid and (stopped_oid.startswith(candidate.oid) or (amend_oid and head_oid == amend_oid) or unmerged):
+                current_step = candidate
+                done_steps = done_steps[:last_step_index]
+                if unmerged:
+                    state, diagnostic = "conflict", ""
+                elif candidate.action == "edit" and amend_oid:
+                    state, diagnostic = "edit", ""
+                elif stopped_oid.startswith(candidate.oid) and staged_change:
+                    # The stopped pick's conflicts were resolved and staged: Git only waits for Continue, so an intervention message would contradict the expected action.
+                    state, diagnostic = "paused", "Conflicts are resolved and staged. Continue the rebase, or abort it."
+                else:
+                    state = "intervention_required"
+        if backend == "rebase-apply":
+            diagnostic = "The apply backend is present. This view cannot classify its native steps."
+        if present_count != 1:
+            state = "unknown"
+            diagnostic = "Multiple native rebase directories are present. The current operation is unknown."
+        if not complete_identity:
+            state = "unknown"
+            diagnostic = "Native rebase metadata is incomplete. Restore it externally, then Refresh."
+        elif missing_todo:
+            state = "unknown"
+            diagnostic = "Native rebase instructions are missing. Refresh after correcting them externally, or abort the rebase."
+        known_done_steps = tuple(step for step in done_steps if not step.opaque)
+        known_remaining_steps = tuple(step for step in remaining_steps if not step.opaque)
+        fresh = complete_identity and present_count == 1
+        return RebaseSnapshot(key, generation, identity, head_oid, identity.head_name, state, fresh, diagnostic,
+                              known_done_steps, current_step, known_remaining_steps, tuple(opaque_steps), unmerged, tuple(observations) if fresh else None)
+    return RebaseSnapshot(key, generation, unmerged=unmerged, native_observations=tuple(observations))