gitpane 1.0.0__py3-none-any.whl

gitpane/ui/history_rewrite/preview_model.py

@@ -0,0 +1,291 @@
+"""Project prepared history changes into read-only table rows."""
+
+from __future__ import annotations
+
+import unicodedata
+from datetime import UTC, datetime, timedelta, timezone
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QAbstractTableModel, QModelIndex, Qt
+from PySide6.QtGui import QColor, QFont, QPalette
+from PySide6.QtWidgets import QStyle, QStyledItemDelegate
+
+from gitpane.config import ERROR_DARK_COLOR, ERROR_LIGHT_COLOR, LOCAL_PREFIX, SHORT_OID_LENGTH, SPACING_XS, UNKNOWN_DARK_COLOR, UNKNOWN_LIGHT_COLOR
+from gitpane.history_rewrite.value import RewriteStatus
+from gitpane.ui.look.color_contrast import contrast_ratio
+from gitpane.ui.look.theme_color import is_dark_palette
+from gitpane.ui.widget.plain_tooltip import plain_text_tooltip
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QPainter
+    from PySide6.QtWidgets import QStyleOptionViewItem, QWidget
+
+    from gitpane.history_rewrite.value import BranchRewrite, RewriteRow
+
+STATUS_MINIMUM_CONTRAST = 4.5
+STATUS_CONTRAST_STEP_PERCENT = 110
+STATUS_CONTRAST_MAXIMUM_STEPS = 20
+
+
+class BranchColumn(Enum):
+    """Name the branch comparison columns in their presentation order."""
+
+    BRANCH = "Branch"
+    CURRENT_TIP = "Current tip"
+    NEW_TIP = "New tip"
+    PUBLICATION = "Known publication"
+
+    @property
+    def index(self) -> int:
+        """Locate this column without separate integer mappings."""
+        return tuple(type(self)).index(self)
+
+
+class CommitColumn(Enum):
+    """Name the contribution columns in their presentation order."""
+
+    STATUS = "Status"
+    COMMIT = "Commit"
+    MESSAGE = "Message"
+    AUTHOR = "Author"
+    DATE = "Date"
+
+    @property
+    def index(self) -> int:
+        """Locate this column without separate integer mappings."""
+        return tuple(type(self)).index(self)
+
+
+class ModelText(Enum):
+    """Keep presentation labels shared by tables and their details."""
+
+    CURRENT = " (current)"
+    TIP_DELETED = "Previous tip deleted"
+    KNOWN = "Affected commits found in {remote_refs} — last fetch"
+    UNKNOWN = "Unknown — no matching remote reference known"
+    NO_UPSTREAM = "No upstream is configured. This does not mean the branch has never been published."
+    UPSTREAM = "Upstream: {upstream}"
+    NO_MESSAGE = "(No commit message)"
+    NO_SUBJECT = "(No commit subject)"
+    MODIFIED = "Modified commit"
+    DELETED = "Deleted commit"
+    DATE_UNREADABLE = "Unreadable author date: {date}"
+
+
+def safe_text(value: str | bytes, *, multiline: bool = False) -> str:
+    """Expose controls and undecodable bytes without letting them disguise displayed identities."""
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", "surrogateescape")
+    parts = []
+    for character in value:
+        code = ord(character)
+        if character == "\\":
+            parts.append("\\\\")
+        elif character == "\n" and multiline:
+            parts.append(character)
+        elif character == "\n":
+            parts.append(r"\n")
+        elif character == "\t":
+            parts.append(r"\t")
+        elif character == "\r":
+            parts.append(r"\r")
+        elif 0xDC80 <= code <= 0xDCFF:
+            parts.append(f"\\x{code - 0xDC00:02x}")
+        elif unicodedata.category(character).startswith("C") or not character.isprintable():
+            parts.append(f"\\x{code:02x}" if code <= 0xFF else f"\\u{code:04x}")
+        else:
+            parts.append(character)
+    return "".join(parts)
+
+
+def author_date(value: str) -> str:
+    """Render the original author offset instead of silently using the computer's timezone."""
+    timestamp, offset = value.split()
+    sign_index, hour_start, hour_end, minute_end = 0, 1, 3, 5
+    if len(offset) != minute_end or offset[sign_index] not in "+-" or not offset[hour_start:].isdigit():
+        raise ValueError(ModelText.DATE_UNREADABLE.value.format(date=safe_text(value)))
+    hour, minute = int(offset[hour_start:hour_end]), int(offset[hour_end:minute_end])
+    minutes_per_hour = 60
+    if minute >= minutes_per_hour:
+        raise ValueError(ModelText.DATE_UNREADABLE.value.format(date=safe_text(value)))
+    delta = timedelta(minutes=(hour * minutes_per_hour + minute) * (-1 if offset.startswith("-") else 1))
+    date = datetime.fromtimestamp(int(timestamp), UTC).astimezone(timezone(delta))
+    return date.strftime("%Y-%m-%d %H:%M %z")
+
+
+def publication_text(branch: BranchRewrite) -> str:
+    """Describe only publication observed in locally known remote references."""
+    if not branch.remote_refs:
+        return ModelText.UNKNOWN.value
+    refs = []
+    for ref in sorted(branch.remote_refs):
+        refs.append(safe_text(ref))
+    return ModelText.KNOWN.value.format(remote_refs=", ".join(refs))
+
+
+class BranchPreviewModel(QAbstractTableModel):
+    """Present every moved local branch with its full identity available in details."""
+
+    def __init__(self, branches: tuple[BranchRewrite, ...] = (), active_branch: str | None = None) -> None:
+        """Sort the current branch first, then use the complete reference names."""
+        super().__init__()
+        self.active_branch = active_branch
+        self.branches = tuple(sorted(branches, key=lambda branch: (branch.name != active_branch, branch.name)))
+
+    def rowCount(self, parent: QModelIndex | None = None) -> int:
+        """Expose all branches without creating child rows."""
+        return 0 if parent is not None and parent.isValid() else len(self.branches)
+
+    def columnCount(self, parent: QModelIndex | None = None) -> int:
+        """Keep the comparison columns even when no branch is present."""
+        return 0 if parent is not None and parent.isValid() else len(BranchColumn)
+
+    def headerData(self, section: int, orientation: Qt.Orientation, role: int = Qt.ItemDataRole.DisplayRole) -> object:
+        """Name horizontal columns using the shared enum."""
+        if orientation == Qt.Orientation.Horizontal and role == Qt.ItemDataRole.DisplayRole and 0 <= section < len(BranchColumn):
+            return tuple(BranchColumn)[section].value
+        return None
+
+    def data(self, index: QModelIndex, role: int = Qt.ItemDataRole.DisplayRole) -> object:
+        """Return plain text and complete details for the requested branch."""
+        if not index.isValid() or not 0 <= index.row() < len(self.branches):
+            return None
+        if role == Qt.ItemDataRole.ToolTipRole:
+            return plain_text_tooltip(self.details(index.row()).splitlines())
+        if role not in (Qt.ItemDataRole.DisplayRole, Qt.ItemDataRole.AccessibleTextRole):
+            return None
+        branch = self.branches[index.row()]
+        column = tuple(BranchColumn)[index.column()]
+        if column == BranchColumn.BRANCH:
+            return safe_text(branch.name.removeprefix(LOCAL_PREFIX)) + (ModelText.CURRENT.value if branch.name == self.active_branch else "")
+        if column == BranchColumn.CURRENT_TIP:
+            return branch.old_oid[:SHORT_OID_LENGTH]
+        if column == BranchColumn.NEW_TIP:
+            return branch.new_oid[:SHORT_OID_LENGTH] + (f" — {ModelText.TIP_DELETED.value}" if branch.tip_deleted else "")
+        return publication_text(branch)
+
+    def details(self, row: int) -> str:
+        """Expose complete branch names and tips for keyboard access and copying."""
+        branch = self.branches[row]
+        lines = [f"{BranchColumn.BRANCH.value}: {safe_text(branch.name)}", f"{BranchColumn.CURRENT_TIP.value}: {branch.old_oid}",
+                 f"{BranchColumn.NEW_TIP.value}: {branch.new_oid}", publication_text(branch)]
+        if branch.tip_deleted:
+            lines.append(ModelText.TIP_DELETED.value)
+        lines.append(ModelText.UPSTREAM.value.format(upstream=safe_text(branch.upstream)) if branch.upstream else ModelText.NO_UPSTREAM.value)
+        return "\n".join(lines)
+
+
+class CommitPreviewModel(QAbstractTableModel):
+    """Present only the contribution rows supplied by the domain in its stable order."""
+
+    def __init__(self, rows: tuple[RewriteRow, ...] = ()) -> None:
+        """Keep the immutable rows without instantiating per-cell widgets."""
+        super().__init__()
+        self.rows = rows
+        self.deleted_font = QFont()
+        self.deleted_font.setBold(True)
+
+    def rowCount(self, parent: QModelIndex | None = None) -> int:
+        """Expose every contribution, including rows beyond the viewport."""
+        return 0 if parent is not None and parent.isValid() else len(self.rows)
+
+    def columnCount(self, parent: QModelIndex | None = None) -> int:
+        """Keep the same five columns in every state."""
+        return 0 if parent is not None and parent.isValid() else len(CommitColumn)
+
+    def headerData(self, section: int, orientation: Qt.Orientation, role: int = Qt.ItemDataRole.DisplayRole) -> object:
+        """Return the English column labels."""
+        if orientation == Qt.Orientation.Horizontal and role == Qt.ItemDataRole.DisplayRole and 0 <= section < len(CommitColumn):
+            return tuple(CommitColumn)[section].value
+        return None
+
+    def data(self, index: QModelIndex, role: int = Qt.ItemDataRole.DisplayRole) -> object:
+        """Project text without inventing contributions from rewritten descendants."""
+        if not index.isValid() or not 0 <= index.row() < len(self.rows):
+            return None
+        row = self.rows[index.row()]
+        column = tuple(CommitColumn)[index.column()]
+        if role == Qt.ItemDataRole.ToolTipRole:
+            text = row.oid if column == CommitColumn.COMMIT else self.data(index)
+            return plain_text_tooltip([str(text)])
+        if role == Qt.ItemDataRole.UserRole:
+            return row
+        if column == CommitColumn.STATUS:
+            if role == Qt.ItemDataRole.FontRole and row.status == RewriteStatus.DELETED:
+                return self.deleted_font
+            if role == Qt.ItemDataRole.AccessibleTextRole:
+                return (ModelText.DELETED if row.status == RewriteStatus.DELETED else ModelText.MODIFIED).value
+        if role not in (Qt.ItemDataRole.DisplayRole, Qt.ItemDataRole.AccessibleTextRole):
+            return None
+        if column == CommitColumn.STATUS:
+            return row.status.value
+        if column == CommitColumn.COMMIT:
+            return row.oid[:SHORT_OID_LENGTH]
+        if column == CommitColumn.MESSAGE:
+            if row.message:
+                return safe_text(row.message)
+            return (ModelText.NO_SUBJECT if row.message_length else ModelText.NO_MESSAGE).value
+        if column == CommitColumn.AUTHOR:
+            return safe_text(row.author)
+        try:
+            return author_date(row.date)
+        except (ValueError, OverflowError, OSError):
+            return ModelText.DATE_UNREADABLE.value.format(date=safe_text(row.date))
+
+
+def status_color(status: RewriteStatus, palette: QPalette, *, high_contrast: bool = False) -> QColor:
+    """Use semantic colors on Base, or the explicit contrast palette when requested."""
+    if high_contrast:
+        return palette.color(QPalette.ColorRole.Text)
+    dark = is_dark_palette(palette)
+    if status == RewriteStatus.DELETED:
+        color = QColor(ERROR_DARK_COLOR if dark else ERROR_LIGHT_COLOR)
+    else:
+        color = QColor(UNKNOWN_DARK_COLOR if dark else UNKNOWN_LIGHT_COLOR)
+    for _step in range(STATUS_CONTRAST_MAXIMUM_STEPS):
+        if contrast_ratio(color, palette.color(QPalette.ColorRole.Base)) >= STATUS_MINIMUM_CONTRAST:
+            return color
+        color = color.lighter(STATUS_CONTRAST_STEP_PERCENT) if dark else color.darker(STATUS_CONTRAST_STEP_PERCENT)
+    return palette.color(QPalette.ColorRole.Text)
+
+
+class StatusDelegate(QStyledItemDelegate):
+    """Keep the status letter readable against its own Base patch during selection."""
+
+    def __init__(self, parent: QWidget) -> None:
+        """Retain the contrast preference without caching theme-dependent colors."""
+        super().__init__(parent)
+        self.high_contrast = False
+        self.refresh_theme()
+
+    def refresh_theme(self) -> None:
+        """Cache colors and fonts outside painting so theme changes cannot allocate per cell."""
+        self.normal_font = self.parent().font()
+        self.deleted_font = QFont(self.normal_font)
+        self.deleted_font.setBold(True)
+        palette = self.parent().palette()
+        self.base_by_group = {}
+        self.color_by_key = {}
+        for group in (QPalette.ColorGroup.Active, QPalette.ColorGroup.Inactive):
+            palette.setCurrentColorGroup(group)
+            self.base_by_group[group] = palette.brush(QPalette.ColorRole.Base)
+            for status in RewriteStatus:
+                self.color_by_key[status, group] = status_color(status, palette, high_contrast=self.high_contrast)
+
+    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex) -> None:
+        """Leave native selection and focus intact behind a small semantic status patch."""
+        super().paint(painter, option, index)
+        row = index.data(Qt.ItemDataRole.UserRole)
+        if row is None:
+            return
+        painter.save()
+        painter.setFont(self.deleted_font if row.status == RewriteStatus.DELETED else self.normal_font)
+        patch = option.rect.adjusted(0, 0, 0, 0)
+        patch.setWidth(painter.fontMetrics().horizontalAdvance(row.status.value) + SPACING_XS * 2)
+        rect = patch.adjusted(SPACING_XS, 0, 0, 0)
+        group = QPalette.ColorGroup.Active if option.state & QStyle.StateFlag.State_Active else QPalette.ColorGroup.Inactive
+        painter.fillRect(patch, self.base_by_group[group])
+        painter.setPen(self.color_by_key[row.status, group])
+        painter.drawText(rect, Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter, row.status.value)
+        painter.restore()

gitpane/ui/history_rewrite/question.py

@@ -0,0 +1,87 @@
+"""Request explicit consent to prepare a history removal preview."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import QMessageBox
+
+from gitpane.config import LOCAL_PREFIX
+from gitpane.history_rewrite.value import RewriteTargetKind
+from gitpane.ui.history_rewrite.preview_model import safe_text
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QAbstractButton, QWidget
+
+    from gitpane.history_rewrite.value import RewriteTarget
+
+
+class QuestionText(Enum):
+    """Keep the initial question independent of the operation's final confirmation."""
+
+    TITLE = "Remove from history"
+    BUILD = "Build preview"
+    ABORT = "Abort"
+    BODY = ("GitPane will scan all ancestors of {branch} and every affected local branch, including all merge parents, to remove {path} from their history. "
+            "Current files on disk will be kept exactly as they are. Build the preview?")
+    FOLDER = "Folder and all files below it: {path}"
+    FILE = "File: {path}"
+    NO_TARGET = "No valid file or folder is selected. Choose Abort, select one path, and open Remove from history again."
+    NO_BRANCH = "HEAD is detached. Check out a local branch, then build a new preview."
+
+
+class HistoryRewriteQuestion(QMessageBox):
+    """Show the captured path without performing preparation or any Git access."""
+
+    build_requested = Signal(object)
+    abort_requested = Signal()
+
+    def __init__(self, target: RewriteTarget | None, branch: str | None, parent: QWidget | None = None) -> None:
+        """Default to Abort and retain the exact typed target for the explicit choice."""
+        super().__init__(parent)
+        self.target = target
+        self.answered = False
+        self.setIcon(QMessageBox.Icon.Question)
+        prepare_message_box(self, QuestionText.TITLE.value)
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        self.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+        self.build_button = self.addButton(QuestionText.BUILD.value, QMessageBox.ButtonRole.AcceptRole)
+        self.abort_button = self.addButton(QuestionText.ABORT.value, QMessageBox.ButtonRole.RejectRole)
+        self.build_button.setAutoDefault(False)
+        self.setDefaultButton(self.abort_button)
+        self.setEscapeButton(self.abort_button)
+        if target is None:
+            self.setText(QuestionText.NO_TARGET.value)
+        elif not branch:
+            self.setText(QuestionText.NO_BRANCH.value)
+        else:
+            path = safe_text(target.path)
+            self.setText(QuestionText.BODY.value.format(branch=safe_text(branch.removeprefix(LOCAL_PREFIX)), path=path))
+            self.setInformativeText((QuestionText.FOLDER if target.kind == RewriteTargetKind.FOLDER else QuestionText.FILE).value.format(path=path))
+        self.build_button.setEnabled(target is not None and bool(branch))
+        self.buttonClicked.connect(self._choose)
+        self.finished.connect(self._dismiss)
+
+    def _choose(self, button: QAbstractButton) -> None:
+        """Emit the original target only for the first explicit Build preview choice."""
+        if self.answered:
+            return
+        self.answered = True
+        if button == self.build_button and self.target is not None:
+            self.build_button.setEnabled(False)
+            self.build_requested.emit(self.target)
+        else:
+            self.abort_requested.emit()
+
+    def _dismiss(self, _result: int) -> None:
+        """Treat window closure as Abort when no button supplied a choice."""
+        if not self.answered:
+            self.answered = True
+            self.abort_requested.emit()
+
+    def show_modal(self) -> None:
+        """Use the common native-window policy without starting preparation."""
+        open_window_modal(self)

gitpane/ui/history_rewrite/recovery_dialog.py

@@ -0,0 +1,262 @@
+"""Explain an interrupted history publication using observed repository facts."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import QKeySequence, QShortcut
+from PySide6.QtWidgets import QApplication, QDialog, QPlainTextEdit, QPushButton, QTableWidget, QTableWidgetItem, QVBoxLayout
+
+from gitpane.config import fit_window
+from gitpane.history_rewrite.recovery import RewritePublicationState
+from gitpane.ui.history_rewrite.preview_model import safe_text
+from gitpane.ui.widget.dialog_layout import install_banded_layout
+from gitpane.ui.window_control.dialog_modality import open_window_modal
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QWidget
+
+    from gitpane.history_rewrite.recovery import RecoveryDiscovery, RecoveryObservation, RewriteRecoveryRecord
+
+RECOVERY_WIDTH_CHARACTERS = 100
+RECOVERY_HEIGHT_LINES = 28
+
+
+class RestoreText(Enum):
+    """Describe the exact collective restoration being separately confirmed."""
+
+    TITLE = "Restore previous branches?"
+    BODY = ("Restore every local branch listed below from its current tip to its previous tip? The original index is still in place. "
+            "Current files on disk will not be changed. GitPane will check the repository again before restoring these branches.")
+    BRANCH = "Branch"
+    CURRENT = "Current tip"
+    PREVIOUS = "Previous tip to restore"
+    INDEX = "Index: original index still in place."
+    RESTORE = "Restore previous branches"
+    KEEP = "Keep current state"
+
+
+class RecoveryText(Enum):
+    """Name diagnostics without presenting journal entries as observed facts."""
+
+    TITLE = "History rewrite needs recovery"
+    BODY = ("The local branch updates and the index update did not finish together. Review the verified state below before making further changes. "
+            "Current files on disk were not rewritten by this operation.")
+    UNAVAILABLE = ("The repository changed after the interrupted operation. Automatic recovery is unavailable to avoid overwriting those changes. "
+                   "Copy the details and inspect the repository before continuing.")
+    COPY = "Copy details"
+    REFRESH = "Refresh status"
+    CLOSE = "Close diagnostic"
+    LOADING = "Reading current repository state…"
+    UNKNOWN = "Not observed"
+    ABSENT = "Absent"
+    NOT_RECORDED = "Not recorded"
+    REPOSITORY = "Repository"
+    DIRECTORY = "Recovery folder"
+    PREVIOUS = "Previous tip"
+    NEW = "Proposed tip"
+    OBSERVED = "Observed tip"
+    HEAD = "Observed HEAD"
+    INDEX = "Observed index digest"
+    ORIGINAL_INDEX = "Recorded original index digest"
+    CANDIDATE_INDEX = "Recorded candidate index digest"
+    LOCK = "Observed index lock"
+    STATE = "Last recorded state"
+    MISSING = "Recovery data is incomplete. Copy the details and inspect the recovery folder before continuing."
+    RESTORED = "The previous branches and original index are in place. Recovery is complete; working files were retained."
+    COMPLETE = "The recorded operation is complete. Recovery does not undo completed operations."
+    EXECUTABLE_CHANGED = "The Git executable differs from the interrupted operation. Reopen this repository with the original executable before restoring branches."
+    OBSERVED_PUBLISHED = "Observed branches and index match the completed update. No branch restoration is needed."
+    OBSERVED_PREVIOUS = "Observed branches and index match the previous state. No branch restoration is needed."
+
+
+def can_restore(record: RewriteRecoveryRecord | None, observation: RecoveryObservation | None) -> bool:
+    """Require complete matching facts before presenting any restoration choice."""
+    return bool(record is not None and observation is not None and record.old_oid_by_ref and observation.restorable and not observation.detail
+                and record.state not in (RewritePublicationState.COMPLETE, RewritePublicationState.RESTORED)
+                and record.candidate_index_identity is not None and set(record.old_oid_by_ref) == set(record.new_oid_by_ref)
+                and observation.ref_oid_by_name == record.new_oid_by_ref and observation.head_ref == record.head_ref
+                and observation.index_identity == record.original_index_identity and observation.index_identity != record.candidate_index_identity)
+
+
+def branch_table(headers: list[str], rows: list[list[str]], parent: QWidget) -> QTableWidget:
+    """Make full identities selectable with native scrolling and a copy shortcut."""
+    table = QTableWidget(len(rows), len(headers), parent)
+    table.setHorizontalHeaderLabels(headers)
+    table.setAccessibleName(RestoreText.BRANCH.value)
+    table.setWordWrap(False)
+    table.setTextElideMode(Qt.TextElideMode.ElideNone)
+    table.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+    table.verticalHeader().hide()
+    for row_index, values in enumerate(rows):
+        for column_index, value in enumerate(values):
+            table.setItem(row_index, column_index, QTableWidgetItem(value))
+    table.resizeColumnsToContents()
+    shortcut = QShortcut(QKeySequence.StandardKey.Copy, table)
+    shortcut.setContext(Qt.ShortcutContext.WidgetWithChildrenShortcut)
+
+    def copy_selection() -> None:
+        """Copy selected cells in display order without truncating any identity."""
+        lines = []
+        for selection in table.selectedRanges():
+            for row_index in range(selection.topRow(), selection.bottomRow() + 1):
+                values = []
+                for column_index in range(selection.leftColumn(), selection.rightColumn() + 1):
+                    item = table.item(row_index, column_index)
+                    values.append(item.text() if item is not None else "")
+                lines.append("\t".join(values))
+        QApplication.clipboard().setText("\n".join(lines))
+
+    shortcut.activated.connect(copy_selection)
+    return table
+
+
+def fit_recovery_dialog(dialog: QDialog) -> None:
+    """Size the scrollable content from the current font while keeping actions on screen."""
+    metrics = dialog.fontMetrics()
+    dialog.resize(metrics.horizontalAdvance("M") * RECOVERY_WIDTH_CHARACTERS, metrics.lineSpacing() * RECOVERY_HEIGHT_LINES)
+    fit_window(dialog, 0, 0)
+
+
+class HistoryRewriteRecoveryDialog(QDialog):
+    """Keep incomplete publication evidence visible without performing repository writes."""
+
+    refresh_requested = Signal()
+    restore_requested = Signal()
+
+    def __init__(self, repository_dir: str, discovery: RecoveryDiscovery, parent: QWidget | None = None) -> None:
+        """Present durable evidence with restoration disabled until an observation arrives."""
+        super().__init__(parent)
+        self.repository_dir = repository_dir
+        self.operation_dir = discovery.operation_dir
+        self.record = discovery.record
+        self.observation: RecoveryObservation | None = None
+        self.setWindowTitle(RecoveryText.TITLE.value)
+        self.details = QPlainTextEdit()
+        self.details.setReadOnly(True)
+        self.details.setAccessibleName(RecoveryText.TITLE.value)
+        self.branch_table = branch_table([RestoreText.BRANCH.value, RecoveryText.PREVIOUS.value, RecoveryText.NEW.value, RecoveryText.OBSERVED.value], [], self)
+        self.copy_button = QPushButton(RecoveryText.COPY.value)
+        self.refresh_button = QPushButton(RecoveryText.REFRESH.value)
+        self.restore_button = QPushButton(RestoreText.RESTORE.value)
+        self.close_button = QPushButton(RecoveryText.CLOSE.value)
+        buttons = [self.copy_button, self.refresh_button, self.restore_button, self.close_button]
+        for button in buttons:
+            button.setAutoDefault(False)
+        self.close_button.setDefault(True)
+        self.copy_button.clicked.connect(self.copy_details)
+        self.refresh_button.clicked.connect(self.refresh_requested)
+        self.restore_button.clicked.connect(self.restore_requested)
+        self.close_button.clicked.connect(self.reject)
+        body = QVBoxLayout()
+        body.addWidget(self.details)
+        body.addWidget(self.branch_table)
+        self.button_band = install_banded_layout(self, body, buttons)
+        self.set_observation(discovery.record, None, discovery.detail)
+        fit_recovery_dialog(self)
+
+    def set_observation(self, record: RewriteRecoveryRecord | None, observation: RecoveryObservation | None, detail: str = "") -> None:
+        """Replace displayed facts atomically, keeping absent data explicitly unknown."""
+        self.record = record
+        self.observation = observation
+        self.restore_button.setEnabled(can_restore(record, observation))
+        lines = [(RecoveryText.BODY if record is not None else RecoveryText.MISSING).value, f"{RecoveryText.REPOSITORY.value}: {safe_text(self.repository_dir)}",
+                 f"{RecoveryText.DIRECTORY.value}: {safe_text(self.operation_dir)}"]
+        if record is not None:
+            lines.extend([f"{RecoveryText.STATE.value}: {record.state.value}",
+                          f"{RecoveryText.ORIGINAL_INDEX.value}: {record.original_index_identity or RecoveryText.ABSENT.value}",
+                          f"{RecoveryText.CANDIDATE_INDEX.value}: {record.candidate_index_identity or RecoveryText.NOT_RECORDED.value}", safe_text(record.detail, multiline=True)])
+        if observation is None:
+            lines.append(RecoveryText.UNKNOWN.value)
+        else:
+            lines.extend([f"{RecoveryText.HEAD.value}: {safe_text(observation.head_ref) if observation.head_ref else RecoveryText.ABSENT.value}",
+                          f"{RecoveryText.INDEX.value}: {observation.index_identity or RecoveryText.ABSENT.value}",
+                          f"{RecoveryText.LOCK.value}: {observation.lock_identity or RecoveryText.ABSENT.value}", safe_text(observation.detail, multiline=True)])
+            if not can_restore(record, observation):
+                state = record.state if record is not None else None
+                restored = (state == RewritePublicationState.RESTORED and observation.ref_oid_by_name == record.old_oid_by_ref
+                            and observation.index_identity == record.original_index_identity and not observation.detail)
+                published = (record is not None and not observation.detail and observation.ref_oid_by_name == record.new_oid_by_ref
+                             and observation.index_identity == record.candidate_index_identity and record.candidate_index_identity is not None)
+                previous = (record is not None and not observation.detail and observation.ref_oid_by_name == record.old_oid_by_ref
+                            and observation.index_identity == record.original_index_identity)
+                lines.append((RecoveryText.RESTORED if restored else
+                              RecoveryText.COMPLETE if state == RewritePublicationState.COMPLETE else RecoveryText.OBSERVED_PUBLISHED if published else
+                              RecoveryText.OBSERVED_PREVIOUS if previous else RecoveryText.UNAVAILABLE).value)
+        lines.append(safe_text(detail, multiline=True))
+        name_set = set(record.old_oid_by_ref) | set(record.new_oid_by_ref) if record is not None else set()
+        if observation is not None:
+            name_set.update(observation.ref_oid_by_name)
+        self.branch_table.setRowCount(len(name_set))
+        for row_index, name in enumerate(sorted(name_set)):
+            values = [safe_text(name), record.old_oid_by_ref.get(name, RecoveryText.NOT_RECORDED.value) if record else RecoveryText.NOT_RECORDED.value,
+                      record.new_oid_by_ref.get(name, RecoveryText.NOT_RECORDED.value) if record else RecoveryText.NOT_RECORDED.value,
+                      observation.ref_oid_by_name.get(name, RecoveryText.ABSENT.value) if observation else RecoveryText.UNKNOWN.value]
+            lines.append("\t".join(values))
+            for column_index, value in enumerate(values):
+                self.branch_table.setItem(row_index, column_index, QTableWidgetItem(value))
+        self.branch_table.resizeColumnsToContents()
+        self.details.setPlainText("\n".join(lines))
+
+    def set_loading(self) -> None:
+        """Revoke restoration while current facts are being reread."""
+        self.set_observation(self.record, None, RecoveryText.LOADING.value)
+
+    def set_error(self, detail: str) -> None:
+        """Keep the recorded facts but revoke an observation that could not be refreshed."""
+        self.set_observation(self.record, None, detail)
+
+    def copy_details(self) -> None:
+        """Copy all displayed evidence, including every full branch identity."""
+        QApplication.clipboard().setText(self.details.toPlainText())
+
+    def show_modal(self) -> None:
+        """Open the diagnostic through the shared native modality policy."""
+        open_window_modal(self)
+
+
+class RestoreBranchesQuestion(QDialog):
+    """Request one explicit consent to restore the exact observed branch set."""
+
+    restore_requested = Signal()
+
+    def __init__(self, repository_dir: str, record: RewriteRecoveryRecord, observation: RecoveryObservation, parent: QWidget | None = None) -> None:
+        """Show complete current/previous tips with Keep current state as the default."""
+        super().__init__(parent)
+        self.setWindowTitle(RestoreText.TITLE.value)
+        self.details = QPlainTextEdit()
+        self.details.setReadOnly(True)
+        valid = can_restore(record, observation)
+        self.details.setPlainText("\n".join((RestoreText.BODY.value if valid else RecoveryText.MISSING.value,
+                                            f"{RecoveryText.REPOSITORY.value}: {safe_text(repository_dir)}", RestoreText.INDEX.value if valid else RecoveryText.UNKNOWN.value)))
+        rows = []
+        for name in sorted(record.old_oid_by_ref):
+            rows.append([safe_text(name), observation.ref_oid_by_name.get(name, RecoveryText.UNKNOWN.value), record.old_oid_by_ref[name]])
+        self.branch_table = branch_table([RestoreText.BRANCH.value, RestoreText.CURRENT.value, RestoreText.PREVIOUS.value], rows, self)
+        self.restore_button = QPushButton(RestoreText.RESTORE.value)
+        self.restore_button.setAutoDefault(False)
+        self.restore_button.setEnabled(can_restore(record, observation))
+        self.keep_button = QPushButton(RestoreText.KEEP.value)
+        self.keep_button.setAutoDefault(False)
+        self.keep_button.setDefault(True)
+        self.keep_button.clicked.connect(self.reject)
+        self.restore_button.clicked.connect(self._confirm)
+        body = QVBoxLayout()
+        body.addWidget(self.details)
+        body.addWidget(self.branch_table)
+        self.button_band = install_banded_layout(self, body, [self.restore_button, self.keep_button])
+        fit_recovery_dialog(self)
+
+    def _confirm(self) -> None:
+        """Consume the explicit choice before any connected operation can start."""
+        if not self.restore_button.isEnabled():
+            return
+        self.restore_button.setEnabled(False)
+        self.accept()
+        self.restore_requested.emit()
+
+    def show_modal(self) -> None:
+        """Open the confirmation through the shared native modality policy."""
+        open_window_modal(self)