gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/mutation.py

@@ -0,0 +1,1539 @@
+"""Publish privately prepared Git indexes under an owned lock with recovery records."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import uuid
+from dataclasses import asdict, dataclass, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import GIT_MUTATION_TIMEOUT_MS, MUTATION_IDLE_TIMEOUT_MS, MUTATION_RECORD_LIMIT_BYTES
+from gitpane.history.repository_value import FileStatus
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.repository_operation import GITPANE_CLOSING_TEXT, OWNED_REPOSITORY_TEXT, OperationAction, OperationIntent, RepositoryOperationService, WriteScope, native_rebase_capture
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+from gitpane.worktree.staged_reset import may_carry_split_index
+from gitpane.worktree.worktree_file import (
+    FILE_MODE_IDENTITY_FIELD,
+    FILE_OBJECT_IDENTITY_FIELDS,
+    FILE_STABLE_IDENTITY_FIELDS,
+    MISSING_PARENT_IDENTITY,
+    PRIVATE_DIRECTORY_MODE,
+    PRIVATE_FILE_MODE,
+    FileImage,
+    capture_image,
+    clean_created_parents,
+    clean_owned,
+    create_missing_parents,
+    matches_after_announced_mode,
+    materialize_blob,
+    owned_inventory,
+    prepare_publication_image,
+    private_file_dir,
+    publication_image,
+    publication_permission,
+    publish_image_mode,
+    respell_single_entry,
+    stat_identity,
+    validate_destination,
+    validate_image,
+    write_image,
+)
+from gitpane.worktree.worktree_snapshot import SUBMODULE_NO_COMMIT_CHANGE, StagingSide, WorktreeKey, file_fingerprint, fingerprint, read_index, verify_local_state
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.process.process_runner import ProcessRunner
+    from gitpane.sequencer.conflict import ConflictResolutionIntent
+    from gitpane.worktree.partial_patch import RawLineSelection, RawPatch
+    from gitpane.worktree.staged_reset import ResetCandidate
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry, WorktreeSnapshot
+
+JOURNAL_SCHEMA_VERSION = 1
+
+
+class JournalKind(Enum):
+    """The kinds of change a recovery journal describes; the index journal of a staging change carries no kind at all."""
+
+    RESET = "reset"
+    """A Reset of whole files, with one entry per file it replaces."""
+    FILE = "file"
+    """A change of one working file, such as a Reset of selected lines or a historical restore."""
+
+
+class JournalState(Enum):
+    """The moments of a journaled change, written as their value in record.json and read back at recovery."""
+
+    PREPARING = "preparing"
+    """The private copies are being written; nothing visible has changed."""
+    PREPARED = "prepared"
+    """The candidates and backups are complete; nothing visible has changed yet."""
+    PUBLISHING = "publishing"
+    """The visible replacements are about to start."""
+    FILE_PUBLISHED = "file_published"
+    """At least one working file holds its new content."""
+    INDEX_PUBLISHED = "index_published"
+    """The index holds its new content."""
+    COMPLETE = "complete"
+    """Every replacement finished and was cleaned up."""
+    ABANDONED = "abandoned"
+    """The change stopped before anything visible changed."""
+    RECOVERED_PRE = "recovered_pre"
+    """A recovery found or restored the state from before the change."""
+    RECOVERED_POST = "recovered_post"
+    """A recovery found the change fully applied."""
+    ROLLED_BACK = "rolled_back"
+    """The change put the working file back after a failure."""
+    RESTORED = "restored"
+    """A recovery put this file of a Reset back to its content from before the change."""
+
+
+# The journal states a recovery leaves alone: the change ended, either way.
+FINISHED_JOURNAL_STATE_SET = frozenset((JournalState.COMPLETE, JournalState.ABANDONED, JournalState.RECOVERED_PRE, JournalState.RECOVERED_POST, JournalState.ROLLED_BACK))
+# Causes of a journal this version cannot read, shown after "Cannot inspect interrupted operation: ".
+UNKNOWN_JOURNAL_STATE_CAUSE = "Unknown recovery record state"
+UNKNOWN_JOURNAL_KIND_CAUSE = "Unknown recovery record kind"
+
+
+def read_journal_state(record_by_name: dict[str, object]) -> JournalState:
+    """Read the state a recovery journal records, refusing a word this version does not know, an empty one or none.
+
+    The refusal is a plain sentence the user reads, never Python's own message about the enum.
+    """
+    try:
+        return JournalState(record_by_name.get("state"))
+    except ValueError as error:
+        raise ValueError(UNKNOWN_JOURNAL_STATE_CAUSE) from error
+
+
+def read_journal_kind(record_by_name: dict[str, object]) -> JournalKind | None:
+    """Read the kind of change a recovery journal records, or None when it records none, as the index journal of a staging change does.
+
+    A kind this version does not know is refused with a plain sentence the user reads.
+    """
+    if "kind" not in record_by_name:
+        return None
+    try:
+        return JournalKind(record_by_name["kind"])
+    except ValueError as error:
+        raise ValueError(UNKNOWN_JOURNAL_KIND_CAUSE) from error
+
+# The operation named by a diagnostic about restoring interrupted changes; the staging view keeps it shown as a state.
+RECOVER_CHANGES_OPERATION = "Recover changes"
+# Said when the snapshot's repository folder no longer resolves to the Git directory it was read from, for example after a move.
+REPOSITORY_FOLDER_CHANGED_TEXT = "The repository folder changed since it was read. Refresh before writing."
+# Said when an identifier already prepared is asked again for another repository, Git program, action or scope.
+PREPARED_ACTION_CHANGED_TEXT = "This action no longer matches what was prepared. Refresh and try again."
+# Introduces the folder where an interrupted change keeps its files, so the user can inspect them.
+RECOVERY_FILES_LABEL = "Recovery files: "
+# Ends a sentence of a cause; a cause that already ends with it needs no other one before the next sentence.
+SENTENCE_END = "."
+
+
+def recovery_files_cause(cause: str, operation_dir: str) -> str:
+    """Follow a failure cause with the folder that keeps the recovery files, as the next sentence of the same text.
+
+    Many refusal texts already end their sentence, so the full stop is added only when the cause has none.
+    """
+    separator = " " if cause.endswith(SENTENCE_END) else SENTENCE_END + " "
+    return cause + separator + RECOVERY_FILES_LABEL + operation_dir
+
+
+def reset_recovery_authority(context: RepositoryContext) -> dict[str, str]:
+    """Bind durable recovery to native refs and pause identity without including Reset's own effects."""
+    from gitpane.reference.reference_edit import reference_signature
+
+    observations = []
+    for observation in native_rebase_capture(context):
+        observations.append(asdict(observation) if observation is not None else None)
+    return {
+        "references": fingerprint(json.dumps(reference_signature(context), default=bytes.hex).encode("utf-8")),
+        "rebase": fingerprint(json.dumps(observations, sort_keys=True).encode("utf-8")),
+    }
+
+
+def require_unchanged_authority(context: RepositoryContext, expected: dict[str, str]) -> None:
+    """Refuse when references, configuration files or the native rebase moved since the expected authority was read.
+
+    The authority is read from local files only, so bracketing Git's verification and the live replacements with it
+    costs no Git process, and a reference moved after that verification cannot pass for the verified state.
+    """
+    if reset_recovery_authority(context) != expected:
+        raise ValueError("HEAD, references or the native rebase changed before publication; refresh the changes")
+
+
+@dataclass(frozen=True)
+class MutationOutcome:
+    """Report the proven index result even when its original view has closed."""
+
+    operation_id: str
+    key: WorktreeKey
+    status: str
+    completed_paths: tuple[bytes, ...]
+    failed_paths: tuple[bytes, ...]
+    diagnostic: PreparedDiagnostic | None = None
+    recovery_dir: str | None = None
+
+
+@dataclass(frozen=True)
+class PreparedLineReset:
+    """Own one exact calculated candidate and backup until publication or cancellation."""
+
+    operation_id: str
+    model: RawPatch
+    selection: RawLineSelection
+    before: FileImage
+    after: FileImage
+    operation_dir: str
+    private_dir: str
+    candidate_filename: str
+    backup_filename: str
+    record_by_name: dict[str, object]
+
+
+def announced_candidate_mode(candidate_identity: tuple[int, ...] | None, after: FileImage) -> int | None:
+    """Predict the mode a candidate reports after publish_image_mode, recorded before the change so recovery recognizes it.
+
+    The prediction is the POSIX result: file type kept, permission bits replaced. Where a system reports permissions
+    differently, the prediction simply does not match and the recorded identity stays the only accepted one.
+    """
+    permission = publication_permission(after)
+    if candidate_identity is None or permission is None:
+        return None
+    return stat.S_IFMT(candidate_identity[FILE_MODE_IDENTITY_FIELD]) | permission
+
+
+def write_record(operation_dir: str, record_by_name: dict[str, object]) -> None:
+    """Flush a private recovery record before making its described step visible."""
+    filename = os.path.join(operation_dir, "record.json")
+    temporary_filename = os.path.join(operation_dir, "record.next")
+    with open(temporary_filename, "w", encoding="utf-8") as stream:
+        os.chmod(temporary_filename, PRIVATE_FILE_MODE)
+        json.dump(record_by_name, stream, sort_keys=True)
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.replace(temporary_filename, filename)
+
+
+def fill_owned_lock(descriptor: int, content: bytes) -> None:
+    """Write a candidate into the lock file this operation created, and make it durable before anyone checks it."""
+    with os.fdopen(descriptor, "wb") as stream:
+        stream.write(content)
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+def release_owned_index_lock(lock_filename: str, descriptor: int | None, identity: tuple[int, int] | None) -> None:
+    """Close a publication handle and remove its lock only while its recorded ownership still agrees."""
+    if descriptor is not None:
+        os.close(descriptor)
+    if identity is None:
+        return
+    try:
+        metadata = os.lstat(lock_filename)
+    except FileNotFoundError:
+        return
+    if not stat.S_ISREG(metadata.st_mode) or stat_identity(metadata)[:FILE_OBJECT_IDENTITY_FIELDS] != identity:
+        raise ValueError("The publication lock changed; cleanup refused")
+    os.unlink(lock_filename)
+
+
+class MutationService(QObject):
+    """Serialize index changes by worktree and keep all candidate files outside working trees."""
+
+    finished = Signal(object)
+    reread_requested = Signal(object)
+
+    def __init__(self, runner: ProcessRunner, worktree_service: WorktreeService, parent: QObject | None = None, *, repository_operation: RepositoryOperationService | None = None) -> None:
+        """Inject command execution and reads rather than constructing hidden services."""
+        super().__init__(parent)
+        self.runner = runner
+        self.worktree_service = worktree_service
+        self.repository_operation = repository_operation if repository_operation is not None else RepositoryOperationService(worktree_service, self)
+        self.operation_id_by_key: dict[WorktreeKey, str] = {}
+        self.intent_by_id: dict[str, OperationIntent] = {}
+        self.active_key_set: set[WorktreeKey] = set()
+        self.active_rule_filename_set: set[str] = set()
+        self.configuration_busy = False
+        self.outcome_by_id: dict[str, MutationOutcome] = {}
+        self.prepared_reset_by_id: dict[str, PreparedLineReset] = {}
+        self.prepared_file_reset_by_id: dict[str, ResetCandidate] = {}
+        self.live_reset_id_set: set[str] = set()
+
+    def acquire(self, snapshot: WorktreeSnapshot, operation_id: str, *, action: OperationAction = OperationAction.UNKNOWN, scope: WriteScope | None = None,
+                operation: str | None = None) -> bool:
+        """Reserve the worktree and its shared repository before any candidate or live write."""
+        intent, _reason = self._acquisition_check(snapshot.context, snapshot.git_filename, operation_id, snapshot.generation, action, scope, snapshot.key, operation)
+        return self._reserve_acquisition(intent)
+
+    def acquire_context(self, context: RepositoryContext, git_filename: str, operation_id: str, generation: int = 0, *,
+                        action: OperationAction = OperationAction.UNKNOWN, scope: WriteScope | None = None) -> bool:
+        """Protect preparation that must capture a snapshot after acquiring repository ownership."""
+        intent, _reason = self._acquisition_check(context, git_filename, operation_id, generation, action, scope)
+        return self._reserve_acquisition(intent)
+
+    def acquire_refusal_cause(self, snapshot: WorktreeSnapshot, operation_id: str, *, action: OperationAction = OperationAction.UNKNOWN, scope: WriteScope | None = None,
+                              operation: str | None = None) -> str:
+        """Say why ``acquire`` refused this write, with the same arguments, in the same event-loop turn as the refusal.
+
+        Another operation is named only when a write really holds the repository, so the user waits only when waiting helps.
+        """
+        return self._acquisition_refusal_cause(snapshot.context, snapshot.git_filename, operation_id, snapshot.generation, action, scope, snapshot.key, operation)
+
+    def acquire_context_refusal_cause(self, context: RepositoryContext, git_filename: str, operation_id: str, generation: int = 0, *,
+                                      action: OperationAction = OperationAction.UNKNOWN, scope: WriteScope | None = None) -> str:
+        """Say why ``acquire_context`` refused this write, with the same arguments, in the same event-loop turn as the refusal."""
+        return self._acquisition_refusal_cause(context, git_filename, operation_id, generation, action, scope)
+
+    def _acquisition_check(self, context: RepositoryContext, git_filename: str, operation_id: str, generation: int, action: OperationAction, scope: WriteScope | None,
+                           read_key: WorktreeKey | None = None, operation: str | None = None) -> tuple[OperationIntent | None, str]:
+        """Run the checks of an acquisition that belong to this service, without reserving anything.
+
+        Answers the intent to reserve, or no intent and the reason that prevents it. Both the acquisition and the
+        cause of its refusal use this one list of checks, so the cause cannot drift from what was really refused.
+        """
+        key = WorktreeKey.from_context(context)
+        if read_key is not None and read_key != key:
+            return None, REPOSITORY_FOLDER_CHANGED_TEXT
+        # A global Git setting being saved or another change of the same worktree really holds the repository.
+        if self.configuration_busy or key in self.active_key_set:
+            return None, OWNED_REPOSITORY_TEXT
+        intent = OperationIntent.capture(operation_id, context, git_filename, generation=generation, action=action,
+                                         **({"scope": scope} if scope is not None else {}), **({"operation": operation} if operation is not None else {}))
+        previous = self.intent_by_id.get(operation_id)
+        if previous is None:
+            return intent, ""
+        if previous.context != context or previous.git_filename != git_filename or previous.action != action or previous.scope != intent.scope or previous.operation != intent.operation:
+            return None, PREPARED_ACTION_CHANGED_TEXT
+        return previous, ""
+
+    def _reserve_acquisition(self, intent: OperationIntent | None) -> bool:
+        """Reserve an intent the acquisition checks accepted and record this service's ownership of its worktree."""
+        if intent is None or not self.repository_operation.reserve(intent):
+            return False
+        self.intent_by_id[intent.operation_id] = intent
+        self.operation_id_by_key[intent.key] = intent.operation_id
+        self.active_key_set.add(intent.key)
+        return True
+
+    def _acquisition_refusal_cause(self, context: RepositoryContext, git_filename: str, operation_id: str, generation: int, action: OperationAction,
+                                   scope: WriteScope | None, read_key: WorktreeKey | None = None, operation: str | None = None) -> str:
+        """Give the cause of a refused acquisition: closing first, then this service's checks, then the repository operation service's reason."""
+        if self.repository_operation.closed:
+            return GITPANE_CLOSING_TEXT
+        intent, reason = self._acquisition_check(context, git_filename, operation_id, generation, action, scope, read_key, operation)
+        if reason:
+            return reason
+        return self.repository_operation.refusal_cause(intent)
+
+    def validate_write(self, key: WorktreeKey) -> None:
+        """Recheck the native operation and exact owner before publishing local content."""
+        operation_id = self.operation_id_by_key.get(key)
+        intent = self.repository_operation.active_by_id.get(operation_id)
+        if intent is None:
+            raise ValueError("This action no longer owns the worktree")
+        self.repository_operation.validate(intent)
+
+    def release(self, key: WorktreeKey, operation_id: str) -> None:
+        """Release only matching ownership after its processes and recovery work finish."""
+        if self.operation_id_by_key.get(key) != operation_id:
+            return
+        self.operation_id_by_key.pop(key)
+        self.active_key_set.discard(key)
+        self.repository_operation.release(operation_id)
+
+    def prepare_reset_file(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], callback: Callable[[ResetCandidate | None, Exception | None], None]) -> str:
+        """Compute a whole-file result, releasing the reservation while confirmation is open.
+
+        A refused reservation hands the callback the real cause of the refusal.
+        """
+        operation_id = uuid.uuid4().hex
+        if not self.acquire(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.acquire_refusal_cause(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT)
+            QTimer.singleShot(0, lambda: callback(None, ValueError(cause)))
+            return operation_id
+        self.live_reset_id_set.add(operation_id)
+
+        def complete(prepared: ResetCandidate | None, error: Exception | None) -> None:
+            """Retain only successful candidates and always release calculation ownership."""
+            self.release(snapshot.key, operation_id)
+            self.live_reset_id_set.discard(operation_id)
+            if error is None:
+                self.prepared_file_reset_by_id[operation_id] = prepared
+            else:
+                self.reread_requested.emit(snapshot.key)
+            callback(prepared, error)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._prepare_file_reset(operation_id, snapshot, entries), complete, operation_id=operation_id)
+        return operation_id
+
+    def cancel_reset_file(self, prepared: ResetCandidate) -> None:
+        """Invalidate a declined confirmation and clean only its owned unpublished files."""
+        if self.prepared_file_reset_by_id.pop(prepared.operation_id, None) is not prepared:
+            return
+        prepared.record_by_name["state"] = JournalState.ABANDONED.value
+        write_record(prepared.operation_dir, prepared.record_by_name)
+        self._clean_reset_content(prepared.record_by_name)
+        self.reread_requested.emit(prepared.snapshot.key)
+
+    def reset_file(self, prepared: ResetCandidate) -> str:
+        """Reacquire the worktree and publish only the exact confirmed file/index candidate.
+
+        A refused reservation abandons the candidate and reports the real cause of the refusal.
+        """
+        if self.prepared_file_reset_by_id.pop(prepared.operation_id, None) is not prepared:
+            raise ValueError("This reset confirmation is no longer current")
+        snapshot = prepared.snapshot
+        if not self.acquire(snapshot, prepared.operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.acquire_refusal_cause(snapshot, prepared.operation_id, action=OperationAction.WORKTREE_EDIT)
+            prepared.record_by_name["state"] = JournalState.ABANDONED.value
+            write_record(prepared.operation_dir, prepared.record_by_name)
+            diagnostic = Diagnostic("Reset", snapshot.context.repository_dir, snapshot.git_filename, [], cause).prepare()
+            outcome = MutationOutcome(prepared.operation_id, snapshot.key, "refused", (), tuple(change.path for change in prepared.changes), diagnostic)
+            QTimer.singleShot(0, lambda: self._publish_outcome(outcome))
+            return prepared.operation_id
+        self.live_reset_id_set.add(prepared.operation_id)
+
+        def complete(outcome: MutationOutcome | None, error: Exception | None) -> None:
+            """Keep terminal results after view closure and request a complete reread."""
+            self.release(snapshot.key, prepared.operation_id)
+            self.live_reset_id_set.discard(prepared.operation_id)
+            if error is not None:
+                outcome = self._reset_failure(prepared, error)
+            self._publish_outcome(outcome)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._publish_reset(prepared), complete, operation_id=prepared.operation_id)
+        return prepared.operation_id
+
+    def _prepare_file_reset(self, operation_id: str, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], *, resolution: ConflictResolutionIntent | None = None) -> Generator:
+        """Prepare every file and durable backup before any live path may change."""
+        from gitpane.worktree.staged_reset import ResetCandidate, calculate_reset
+
+        recovery = self.recover(snapshot.context, snapshot.index_filename, operation_id=operation_id)
+        if recovery:
+            raise ValueError(recovery)
+        paths = tuple(dict.fromkeys(path for entry in entries for path in entry.paths))
+        recovery_authority = yield FileTask(lambda: reset_recovery_authority(snapshot.context))
+        yield from self._check_reset_preparation(snapshot, paths, resolution)
+        root_dir = os.path.join(snapshot.context.git_dir, "gitpane-operation")
+        os.makedirs(root_dir, mode=PRIVATE_DIRECTORY_MODE, exist_ok=True)
+        operation_dir = os.path.join(root_dir, operation_id)
+        os.mkdir(operation_dir, PRIVATE_DIRECTORY_MODE)
+        record_by_name: dict[str, object] = {"schema_version": JOURNAL_SCHEMA_VERSION, "kind": JournalKind.RESET.value, "operation_id": operation_id,
+            "index_filename": snapshot.index_filename, "before": snapshot.index_fingerprint, "after": None, "state": JournalState.PREPARING.value, "files": [],
+            "git_filename": snapshot.git_filename, "recovery_authority": recovery_authority,
+            "operation_dir": operation_dir, "operation_identity": stat_identity(os.lstat(operation_dir))[:FILE_OBJECT_IDENTITY_FIELDS]}
+        write_record(operation_dir, record_by_name)
+        try:
+            side = next(iter(entries)).side
+            operation = "Reset"
+            explanation = "Remove staged changes from the index and working files. Independent unstaged changes will be preserved." if side == StagingSide.STAGED else "Replace unstaged changes with the index version. Staged content will be preserved."
+            if resolution is None:
+                changes, before_entries, after_entries, candidate = yield from calculate_reset(snapshot, entries, operation_dir)
+            else:
+                from gitpane.sequencer.conflict import prepare_conflict_deletion
+
+                # Conflict deletion needs the same durable file/index publication and recovery as a staged reset.
+                changes, before_entries, after_entries, candidate = yield from prepare_conflict_deletion(resolution, operation_dir)
+                side = StagingSide.STAGED
+                operation = "Delete conflicted file"
+                explanation = "Delete the working file and stage its deletion as the conflict resolution."
+            owned_files: list[dict[str, object]] = []
+            normalized_changes = []
+            for number, change in enumerate(changes):
+                private_dir = private_file_dir(snapshot.context, change.path, operation_dir, allow_missing_parents=True)
+                backup_filename = os.path.join(private_dir, str(number) + "-before")
+                candidate_filename = os.path.join(private_dir, str(number) + "-after")
+                if change.before.exists:
+                    yield FileTask(lambda change=change, backup_filename=backup_filename: write_image(backup_filename, FileImage(True, stat.S_IFREG | PRIVATE_FILE_MODE, change.before.read())))
+                after = yield FileTask(lambda change=change, candidate_filename=candidate_filename: prepare_publication_image(candidate_filename, change.after, change.before))
+                change = replace(change, after=after)
+                normalized_changes.append(change)
+                candidate_identity = stat_identity(os.lstat(candidate_filename)) if change.after.exists else None
+                candidate_published_mode = announced_candidate_mode(candidate_identity, change.after)
+                owned_files.append({"path_hex": change.path.hex(), "before": change.before.digest(), "after": change.after.digest(),
+                    "before_mode": change.before.mode, "after_mode": change.after.mode, "before_absent": not change.before.exists, "after_absent": not change.after.exists,
+                    "before_identity": change.before.identity, "parents": change.before.parents, "private_dir": private_dir,
+                    "private_identity": stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS], "backup_filename": backup_filename,
+                    "backup_identity": stat_identity(os.lstat(backup_filename)) if change.before.exists else None,
+                    "candidate_filename": candidate_filename, "candidate_identity": candidate_identity, "candidate_published_mode": candidate_published_mode,
+                    "state": JournalState.PREPARED.value, "published_identity": None, "original_path_hex": (change.original_path or change.path).hex()})
+            changes = tuple(normalized_changes)
+            backup_index_filename = os.path.join(operation_dir, "before-index")
+            if snapshot.index_content is not None:
+                yield FileTask(lambda: write_image(backup_index_filename, FileImage(True, stat.S_IFREG | PRIVATE_FILE_MODE, snapshot.index_content)))
+            record_by_name.update({"after": fingerprint(candidate), "state": JournalState.PREPARED.value, "files": owned_files,
+                                  "owned_files": owned_inventory(operation_dir), "side": side.value})
+            yield from self._check_reset_preparation(snapshot, paths, resolution)
+            for change in changes:
+                yield FileTask(lambda change=change: validate_image(snapshot.context, change.path, change.before))
+            write_record(operation_dir, record_by_name)
+            return ResetCandidate(operation_id, snapshot, side, changes, before_entries, after_entries, candidate, operation_dir, record_by_name, explanation, operation)
+        except (OSError, ValueError, RuntimeError):
+            record_by_name["state"] = JournalState.ABANDONED.value
+            write_record(operation_dir, record_by_name)
+            raise
+
+    def _check_reset_preparation(self, snapshot: WorktreeSnapshot, paths: tuple[bytes, ...], resolution: ConflictResolutionIntent | None) -> Generator:
+        """Refuse stale selected bytes at a preparation boundary.
+
+        A normal Reset only builds private files here, so the process-free check of the index bytes and selected paths
+        is enough; Git verifies HEAD, repository identity and conversion once, under the publication lock. A conflict
+        deletion asks Git to verify the index, HEAD, configuration, attributes and chosen path it was written against;
+        its complete capture stays at publication, under the lock, where it protects the file replacement.
+        """
+        if resolution is None:
+            yield FileTask(lambda: verify_local_state(snapshot, paths))
+            return
+        yield from self.worktree_service.verify(snapshot, paths)
+
+    @staticmethod
+    def _reset_verified_paths(prepared: ResetCandidate) -> tuple[bytes, ...]:
+        """Name every selected path the capture fingerprinted, both sides of a rename included.
+
+        A destination the capture never listed has no fingerprint to compare; its before image still proves it.
+        """
+        paths: list[bytes] = []
+        for change in prepared.changes:
+            for path in (change.path, change.original_path):
+                if path is not None and path in prepared.snapshot.fingerprint_by_path and path not in paths:
+                    paths.append(path)
+        return tuple(paths)
+
+    def _clean_reset_content(self, record_by_name: dict[str, object]) -> None:
+        """Remove confirmed owned backup and candidate files without following directory substitutions.
+
+        A candidate may also carry the final permissions its record announced: publication changes them just before
+        recording the new identity, and an interruption between the two must not make GitPane refuse its own file.
+        Any other difference, including another mode, still refuses the cleanup.
+        """
+        operation_dir = record_by_name["operation_dir"]
+        if os.path.islink(operation_dir) or os.path.isjunction(operation_dir) or stat_identity(os.lstat(operation_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(record_by_name["operation_identity"]):
+            raise ValueError("The operation directory changed; cleanup refused")
+        for record in record_by_name["files"]:
+            private_dir = record["private_dir"]
+            if os.path.islink(private_dir) or os.path.isjunction(private_dir) or stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(record["private_identity"]):
+                raise ValueError("Private recovery directory changed; cleanup refused")
+            for name in ("backup", "candidate"):
+                filename = record[name + "_filename"]
+                if os.path.dirname(filename) != private_dir:
+                    raise ValueError("Recovery filename is outside its owned directory")
+                if not os.path.lexists(filename):
+                    continue
+                actual_identity = stat_identity(os.lstat(filename))
+                recorded_identity = tuple(record[name + "_identity"])
+                announced_mode = record.get("candidate_published_mode") if name == "candidate" else None
+                if actual_identity != recorded_identity and not matches_after_announced_mode(actual_identity, recorded_identity, announced_mode):
+                    raise ValueError("Recovery content changed; cleanup refused")
+                os.unlink(filename)
+            if private_dir != operation_dir:
+                os.rmdir(private_dir)
+        clean_owned(operation_dir, record_by_name.get("owned_files", []))
+
+    def _publish_reset(self, prepared: ResetCandidate, *, validate: Callable[[], None] | None = None) -> Generator:
+        """Publish files then index, recording each real transition and retaining partial results.
+
+        Each candidate's final permissions were recorded at preparation, before this changes them: on POSIX the change
+        also gives the candidate a new identity, and a crash before the next record write must still let recovery
+        recognize and clean the candidate.
+
+        A normal Reset fills its owned lock with the candidate index first, asks Git to verify once, then proves with
+        local reads that no reference moved, before the first replacement and again after the last one. A caller that
+        supplies its own validation keeps the complete capture and HEAD read it was written against.
+        """
+        snapshot = prepared.snapshot
+        complete_check = validate is not None
+        validate_owner = validate or (lambda: self.validate_write(snapshot.key))
+        paths = tuple(change.path for change in prepared.changes)
+        lock_filename = snapshot.index_filename + ".lock"
+        lock_descriptor: int | None = None
+        lock_identity: tuple[int, int] | None = None
+        published_path_hexes: list[str] = []
+        created_dirs: list[tuple[str, tuple[int, int]]] = []
+        prepared.record_by_name["created_dirs"] = created_dirs
+        prepared.record_by_name["published_path_hexes"] = published_path_hexes
+        try:
+            lock_descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+            lock_identity = stat_identity(os.fstat(lock_descriptor))[:FILE_OBJECT_IDENTITY_FIELDS]
+            if complete_check:
+                current = yield from self.worktree_service.capture(snapshot.context, snapshot.git_filename)
+                self._validate(snapshot, current, paths)
+            else:
+                if prepared.index_content is not None:
+                    descriptor, lock_descriptor = lock_descriptor, None
+                    fill_owned_lock(descriptor, prepared.index_content)
+                yield from self.worktree_service.verify(snapshot, self._reset_verified_paths(prepared))
+            for change in prepared.changes:
+                yield FileTask(lambda change=change: validate_image(snapshot.context, change.path, change.before))
+            for change, record in zip(prepared.changes, prepared.record_by_name["files"], strict=True):
+                yield FileTask(lambda change=change, record=record: self._validate_reset_storage(change.before, change.after, record))
+            if complete_check and prepared.index_content is not None:
+                descriptor, lock_descriptor = lock_descriptor, None
+                fill_owned_lock(descriptor, prepared.index_content)
+            if not complete_check:
+                yield FileTask(lambda: require_unchanged_authority(snapshot.context, prepared.record_by_name["recovery_authority"]))
+            prepared.record_by_name["state"] = JournalState.PUBLISHING.value
+            prepared.record_by_name["lock_identity"] = lock_identity
+            write_record(prepared.operation_dir, prepared.record_by_name)
+            for change, record in zip(prepared.changes, prepared.record_by_name["files"], strict=True):
+                expected = publication_image(change.before, created_dirs)
+                yield FileTask(lambda change=change, expected=expected: validate_image(snapshot.context, change.path, expected))
+                if change.after.exists:
+                    create_missing_parents(snapshot.context, change.path, change.before, created_dirs, lambda: write_record(prepared.operation_dir, prepared.record_by_name))
+                filename, _parents = validate_destination(snapshot.context, change.path, allow_missing_parents=True)
+                candidate_filename = record["candidate_filename"]
+                validate_owner()
+                self._validate_reset_storage(change.before, change.after, record)
+                if change.after.exists:
+                    publish_image_mode(candidate_filename, change.after)
+                    record["candidate_identity"] = stat_identity(os.lstat(candidate_filename))
+                    write_record(prepared.operation_dir, prepared.record_by_name)
+                    validate_image(snapshot.context, change.path, publication_image(change.before, created_dirs))
+                    os.replace(candidate_filename, filename)
+                    if change.original_path is not None:
+                        respell_single_entry(snapshot.context, change.original_path, change.path)
+                elif change.before.exists:
+                    os.unlink(filename)
+                published_path_hexes.append(change.path.hex())
+                actual = capture_image(snapshot.context, change.path, allow_missing_parents=True)
+                record.update({"state": JournalState.FILE_PUBLISHED.value, "published_identity": actual.identity})
+                prepared.record_by_name["state"] = JournalState.FILE_PUBLISHED.value
+                write_record(prepared.operation_dir, prepared.record_by_name)
+            if complete_check:
+                if read_index(snapshot.index_filename) != snapshot.index_content:
+                    raise ValueError("The index changed before publication")
+                final_head = yield GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+                if (final_head.strip().decode("ascii") or None) != snapshot.head_oid:
+                    raise ValueError("HEAD changed before publication")
+            else:
+                yield FileTask(lambda: require_unchanged_authority(snapshot.context, prepared.record_by_name["recovery_authority"]))
+                if read_index(snapshot.index_filename) != snapshot.index_content:
+                    raise ValueError("The index changed before publication")
+            for change in prepared.changes:
+                if capture_image(snapshot.context, change.path, allow_missing_parents=True).digest() != change.after.digest():
+                    raise ValueError("A working file changed during " + prepared.operation)
+            if stat_identity(os.lstat(lock_filename))[:FILE_OBJECT_IDENTITY_FIELDS] != lock_identity:
+                lock_identity = None
+                raise ValueError("The index publication lock changed")
+            if prepared.side == StagingSide.STAGED:
+                if read_index(lock_filename) != prepared.index_content:
+                    raise ValueError("The candidate index changed")
+                validate_owner()
+                os.replace(lock_filename, snapshot.index_filename)
+                lock_identity = None
+                prepared.record_by_name["index_published"] = True
+            prepared.record_by_name["state"] = JournalState.INDEX_PUBLISHED.value
+            write_record(prepared.operation_dir, prepared.record_by_name)
+            outcome = MutationOutcome(prepared.operation_id, snapshot.key, "success", paths, ())
+        except (OSError, ValueError, RuntimeError) as error:
+            outcome = self._reset_failure(prepared, error)
+        finally:
+            clean_created_parents(created_dirs)
+            try:
+                release_owned_index_lock(lock_filename, lock_descriptor, lock_identity)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._reset_failure(prepared, error)
+        if outcome.diagnostic is None:
+            try:
+                # Backups remain available if releasing the live publication lock fails.
+                prepared.record_by_name["state"] = JournalState.COMPLETE.value
+                write_record(prepared.operation_dir, prepared.record_by_name)
+                self._clean_reset_content(prepared.record_by_name)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._reset_failure(prepared, error)
+        return outcome
+
+    def _reset_failure(self, prepared: ResetCandidate, error: Exception) -> MutationOutcome:
+        """Retain known published paths even if cleanup or a later editor obscures their current bytes."""
+        snapshot = prepared.snapshot
+        published_paths = []
+        for path_hex in prepared.record_by_name.get("published_path_hexes", []):
+            published_paths.append(bytes.fromhex(path_hex))
+        index_published = bool(prepared.record_by_name.get("index_published"))
+        # A filesystem replacement can succeed before raising; keep both recorded facts and observed results.
+        for change in prepared.changes:
+            try:
+                actual = capture_image(snapshot.context, change.path)
+                if actual.digest() == change.after.digest() and actual.digest() != change.before.digest() and change.path not in published_paths:
+                    published_paths.append(change.path)
+            except (OSError, ValueError):
+                pass
+        if prepared.side == StagingSide.STAGED and prepared.index_content != snapshot.index_content:
+            try:
+                index_published = index_published or read_index(snapshot.index_filename) == prepared.index_content
+            except (OSError, ValueError):
+                pass
+        published_path_hexes = []
+        for path in published_paths:
+            published_path_hexes.append(path.hex())
+        prepared.record_by_name["published_path_hexes"] = published_path_hexes
+        prepared.record_by_name["index_published"] = index_published
+        status = "unknown" if index_published else "partial" if published_paths else "refused"
+        journal_state = JournalState.INDEX_PUBLISHED if index_published else JournalState.FILE_PUBLISHED if published_paths else JournalState.ABANDONED
+        prepared.record_by_name["state"] = journal_state.value
+        try:
+            write_record(prepared.operation_dir, prepared.record_by_name)
+        except OSError:
+            pass
+        diagnostic = Diagnostic(prepared.operation, snapshot.context.repository_dir, snapshot.git_filename, [], recovery_files_cause(str(error), prepared.operation_dir)).prepare()
+        failed_paths = tuple(change.path for change in prepared.changes if change.path not in published_paths)
+        return MutationOutcome(prepared.operation_id, snapshot.key, status, tuple(published_paths), failed_paths, diagnostic, prepared.operation_dir)
+
+    def _validate_reset_storage(self, before: FileImage, after: FileImage, record: dict[str, object]) -> None:
+        """Prove both backup and candidate ownership before any member of a batch is replaced."""
+        private_dir = record["private_dir"]
+        if os.path.islink(private_dir) or os.path.isjunction(private_dir) or stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(record["private_identity"]):
+            raise ValueError("The owned Reset directory changed")
+        for name, image in (("backup", before), ("candidate", after)):
+            filename = record[name + "_filename"]
+            if os.path.dirname(filename) != private_dir:
+                raise ValueError("The owned Reset file is outside its private directory")
+            if not image.exists:
+                if os.path.lexists(filename):
+                    raise ValueError("An unexpected file occupies the owned Reset path")
+                continue
+            if stat_identity(os.lstat(filename)) != tuple(record[name + "_identity"]):
+                raise ValueError("The owned Reset " + name + " changed")
+            if name == "candidate" and stat.S_ISLNK(image.mode):
+                content = os.fsencode(os.readlink(filename))
+            else:
+                if os.path.islink(filename):
+                    raise ValueError("The owned Reset backup is a symbolic link")
+                with open(filename, "rb") as stream:
+                    content = stream.read()
+            if content != image.read():
+                raise ValueError("The owned Reset " + name + " changed")
+
+    def _recover_reset(self, context: RepositoryContext, operation_dir: str, record_by_name: dict[str, object], operation_id: str | None) -> str:
+        """Own recovery separately or borrow an explicit caller while retaining original native authority.
+
+        A recovery that cannot reserve the worktree gives the real cause of the refusal, then where its files are kept.
+        """
+        if not record_by_name.get("recovery_authority") or not record_by_name.get("git_filename"):
+            return recovery_files_cause("Interrupted Reset has no native authority proof; inspect its retained files before restoring manually.", operation_dir)
+        key = WorktreeKey.from_context(context)
+        recovery_id = uuid.uuid4().hex
+        borrowed = operation_id is not None
+        if borrowed:
+            owner = self.repository_operation.active_by_id.get(operation_id)
+            if owner is None or owner.key != key or self.operation_id_by_key.get(key) != operation_id:
+                return recovery_files_cause("Reset recovery does not own this worktree.", operation_dir)
+        else:
+            if not self.acquire_context(context, record_by_name["git_filename"], recovery_id, action=OperationAction.WORKTREE_EDIT):
+                cause = self.acquire_context_refusal_cause(context, record_by_name["git_filename"], recovery_id, action=OperationAction.WORKTREE_EDIT)
+                return recovery_files_cause(cause, operation_dir)
+            owner = self.repository_operation.active_by_id[recovery_id]
+        recovery_intent = replace(owner, action=OperationAction.WORKTREE_EDIT, scope=WriteScope.capture(context))
+        lock_filename = record_by_name["index_filename"] + ".lock"
+        lock_identity = None
+        restored_paths: list[bytes] = []
+        diagnostic = ""
+
+        def validate_recovery() -> None:
+            """Recheck the caller, recovery action and durable proof immediately before publication."""
+            if self.operation_id_by_key.get(key) != owner.operation_id:
+                raise ValueError("Reset recovery no longer owns this worktree")
+            self.repository_operation.validate(owner)
+            reason = self.repository_operation.policy_diagnostic(recovery_intent)
+            if reason:
+                raise ValueError(reason)
+            allows = self.repository_operation.allows
+            if allows is not None and not allows(recovery_intent):
+                raise ValueError("Working-file recovery is no longer authorized")
+            if reset_recovery_authority(context) != record_by_name["recovery_authority"]:
+                raise ValueError("HEAD, references or the native rebase changed; inspect retained files before restoring manually")
+            if lock_identity is not None and stat_identity(os.lstat(lock_filename))[:FILE_OBJECT_IDENTITY_FIELDS] != lock_identity:
+                raise ValueError("The recovery index lock changed; remaining backups retained")
+
+        try:
+            validate_recovery()
+            if os.path.lexists(lock_filename):
+                raise ValueError("An interrupted Reset has an index lock; process termination and lock ownership cannot be proven")
+            descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+            lock_identity = stat_identity(os.fstat(descriptor))[:FILE_OBJECT_IDENTITY_FIELDS]
+            os.close(descriptor)
+            diagnostic = self._reconcile_reset(context, operation_dir, record_by_name, validate_recovery, restored_paths)
+        except (OSError, ValueError, TypeError, KeyError) as error:
+            diagnostic = recovery_files_cause(str(error), operation_dir)
+        finally:
+            try:
+                release_owned_index_lock(lock_filename, None, lock_identity)
+            except (OSError, ValueError) as error:
+                diagnostic = (diagnostic + "\n" if diagnostic else "") + recovery_files_cause(str(error), operation_dir)
+            if not borrowed:
+                self.release(key, recovery_id)
+        if restored_paths:
+            failure = Diagnostic(RECOVER_CHANGES_OPERATION, context.repository_dir, owner.git_filename, [], diagnostic).prepare() if diagnostic else None
+            restored_path_set = set(restored_paths)
+            failed_paths = []
+            if diagnostic:
+                for record in record_by_name["files"]:
+                    path = bytes.fromhex(record["path_hex"])
+                    if path not in restored_path_set:
+                        failed_paths.append(path)
+            self._publish_outcome(MutationOutcome(recovery_id, key, "partial" if diagnostic else "rolled_back", tuple(restored_paths), tuple(failed_paths), failure,
+                                                  operation_dir if diagnostic else None))
+        return diagnostic
+
+    def _reconcile_reset(self, context: RepositoryContext, operation_dir: str, record_by_name: dict[str, object],
+                         validate_recovery: Callable[[], None], restored_paths: list[bytes]) -> str:
+        """Check every image under the owned index lock before restoring any interrupted file."""
+        if record_by_name.get("operation_dir") != operation_dir:
+            raise ValueError("Recovery operation directory does not match its record")
+        if stat_identity(os.lstat(operation_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(record_by_name["operation_identity"]):
+            raise ValueError("Recovery operation directory changed")
+        index_filename = record_by_name["index_filename"]
+        current_index = fingerprint(read_index(index_filename))
+        before_index, after_index = record_by_name["before"], record_by_name["after"]
+        if current_index not in (before_index, after_index):
+            return recovery_files_cause("The index changed outside the interrupted Reset.", operation_dir)
+        records = record_by_name["files"]
+        states: list[str] = []
+        images: list[FileImage] = []
+        for record in records:
+            path = bytes.fromhex(record["path_hex"])
+            image = capture_image(context, path, allow_missing_parents=True)
+            parents = tuple((directory, tuple(identity)) for directory, identity in record["parents"])
+            actual_identity_by_directory = dict(image.parents)
+            created_dirs = []
+            for directory, identity in record_by_name.get("created_dirs", []):
+                if actual_identity_by_directory.get(directory) != MISSING_PARENT_IDENTITY:
+                    created_dirs.append((directory, tuple(identity)))
+            parents = publication_image(FileImage(False, 0, parents=parents), created_dirs).parents
+            if image.parents != parents:
+                return recovery_files_cause("A working parent changed outside the interrupted Reset.", operation_dir)
+            before_identity = record.get("restored_identity") or record["before_identity"]
+            published_identity = record["published_identity"] or record["candidate_identity"]
+            is_before = image.digest() == record["before"] and (image.identity is None or before_identity is not None and image.identity == tuple(before_identity))
+            is_after = image.digest() == record["after"] and (image.identity is None or published_identity is not None and image.identity[:FILE_STABLE_IDENTITY_FIELDS] == tuple(published_identity)[:FILE_STABLE_IDENTITY_FIELDS])
+            if not is_before and not is_after:
+                return recovery_files_cause("Working file changed outside the interrupted Reset: " + os.fsdecode(path) + ".", operation_dir)
+            states.append("before" if is_before else "after")
+            images.append(image)
+            private_dir = record["private_dir"]
+            if os.path.islink(private_dir) or os.path.isjunction(private_dir) or stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(record["private_identity"]):
+                raise ValueError("Private recovery directory changed")
+            backup_filename = record["backup_filename"]
+            if os.path.dirname(backup_filename) != private_dir:
+                raise ValueError("Recovery backup is outside its owned directory")
+            if not record["before_absent"]:
+                if stat_identity(os.lstat(backup_filename)) != tuple(record["backup_identity"]) or os.path.islink(backup_filename):
+                    raise ValueError("Recovery backup changed")
+                with open(backup_filename, "rb") as stream:
+                    backup = FileImage(True, record["before_mode"], stream.read())
+                if backup.digest() != record["before"]:
+                    raise ValueError("Recovery backup has different bytes")
+        fully_published = bool(records) and all(state == "after" or record["before"] == record["after"] for state, record in zip(states, records, strict=True))
+        if current_index == after_index and (before_index != after_index or fully_published):
+            if not fully_published:
+                return recovery_files_cause("The index was published but working files no longer match the Reset result.", operation_dir)
+            validate_recovery()
+            record_by_name["state"] = JournalState.RECOVERED_POST.value
+            write_record(operation_dir, record_by_name)
+            self._clean_reset_content(record_by_name)
+            return ""
+        # Check all paths first so an external edit in the last file prevents restoration of the first.
+        for record, state, image in zip(records, states, images, strict=True):
+            if state == "before":
+                continue
+            if fingerprint(read_index(index_filename)) != current_index:
+                raise ValueError("The index changed during recovery; remaining backups retained")
+            path = bytes.fromhex(record["path_hex"])
+            validate_image(context, path, image)
+            filename, _parents = validate_destination(context, bytes.fromhex(record.get("original_path_hex", record["path_hex"])))
+            if record["before_absent"]:
+                validate_recovery()
+                os.unlink(filename)
+            else:
+                with open(record["backup_filename"], "rb") as stream:
+                    before = FileImage(True, record["before_mode"], stream.read())
+                rollback_filename = record["candidate_filename"] + "-rollback"
+                write_image(rollback_filename, before)
+                record["restored_identity"] = stat_identity(os.lstat(rollback_filename))
+                write_record(operation_dir, record_by_name)
+                validate_image(context, path, image)
+                validate_recovery()
+                os.replace(rollback_filename, filename)
+                if "original_path_hex" in record:
+                    respell_single_entry(context, path, bytes.fromhex(record["original_path_hex"]))
+                record["restored_identity"] = capture_image(context, path).identity
+            restored_paths.append(path)
+            record["state"] = JournalState.RESTORED.value
+            write_record(operation_dir, record_by_name)
+        validate_recovery()
+        record_by_name["state"] = JournalState.RECOVERED_PRE.value
+        clean_created_parents(record_by_name.get("created_dirs", []))
+        write_record(operation_dir, record_by_name)
+        self._clean_reset_content(record_by_name)
+        return ""
+
+    def stage_file(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...]) -> str:
+        """Prepare complete selected working files without modifying their bytes."""
+        return self._submit(snapshot, entries, "stage")
+
+    def resolve_conflict(self, intent: ConflictResolutionIntent) -> str:
+        """Reserve one manual resolution until its candidate is published and reported.
+
+        A refused resolution says why: GitPane closing first, then another operation when a write already holds the
+        repository, otherwise the reason the repository operation service finds for refusing the reservation.
+        """
+        owner, snapshot = intent.operation, intent.snapshot
+        operation_id = owner.operation_id
+        # A global Git setting being saved, another change of the same worktree, or this same resolution still running
+        # all hold the repository for real. They are named here because refusal_cause skips an operation with this
+        # resolution's identifier and does not know about a setting save.
+        write_holds_repository = self.configuration_busy or snapshot.key in self.active_key_set or operation_id in self.repository_operation.active_by_id
+        if write_holds_repository or not self.repository_operation.reserve(owner):
+            if self.repository_operation.closed:
+                cause = GITPANE_CLOSING_TEXT
+            elif write_holds_repository:
+                cause = OWNED_REPOSITORY_TEXT
+            else:
+                cause = self.repository_operation.refusal_cause(owner)
+            diagnostic = Diagnostic(owner.operation, snapshot.context.repository_dir, snapshot.git_filename, [], cause).prepare()
+            outcome = MutationOutcome(operation_id, snapshot.key, "refused", (), (intent.path,), diagnostic)
+            QTimer.singleShot(0, lambda: self._publish_outcome(outcome))
+            return operation_id
+        self.operation_id_by_key[snapshot.key] = operation_id
+        self.active_key_set.add(snapshot.key)
+
+        def complete(value: object, error: Exception | None) -> None:
+            """Release only this manual owner after native execution has finished."""
+            if self.repository_operation.active_by_id.get(operation_id) is owner:
+                self.release(snapshot.key, operation_id)
+            else:
+                self.operation_id_by_key.pop(snapshot.key, None)
+                self.active_key_set.discard(snapshot.key)
+            if error is not None:
+                diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(owner.operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+                value = MutationOutcome(operation_id, snapshot.key, "refused", (), (intent.path,), diagnostic)
+            self._publish_outcome(value)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self.resolve_conflict_sequence(intent), complete, operation_id=operation_id)
+        return operation_id
+
+    def resolve_conflict_sequence(self, intent: ConflictResolutionIntent) -> Generator:
+        """Stage a result using the exact existing owner without reserving or releasing it."""
+        from gitpane.sequencer.conflict import has_deleted_side
+
+        self._validate_conflict_owner(intent)
+        snapshot = intent.snapshot
+        entries = tuple(entry for entry in snapshot.entries if entry.path == intent.path and entry.status == FileStatus.UNMERGED)
+        if len(entries) != 1 or next(iter(entries)).conflict_sides != intent.sides:
+            raise ValueError("The selected conflict stages changed; rescan merge conflicts")
+        if (not intent.delete and not intent.image.exists or any(side.mode == "160000" for side in intent.sides)
+                or intent.delete and intent.image.exists and not has_deleted_side(intent.sides)):
+            raise ValueError("Choose an existing file result or explicitly confirm its deletion; resolve submodules externally")
+        yield FileTask(lambda: validate_image(snapshot.context, intent.path, intent.image))
+        if intent.delete and intent.image.exists:
+            operation_id = intent.operation.operation_id
+            self.live_reset_id_set.add(operation_id)
+            try:
+                prepared = yield from self._prepare_file_reset(operation_id, snapshot, entries, resolution=intent)
+                self._validate_conflict_owner(intent)
+                return (yield from self._publish_reset(prepared, validate=lambda: self._validate_conflict_owner(intent)))
+            finally:
+                self.live_reset_id_set.discard(operation_id)
+        return (yield from self._prepare(uuid.uuid4().hex, snapshot, entries, "resolve conflict", resolution=intent))
+
+    def _validate_conflict_owner(self, intent: ConflictResolutionIntent) -> None:
+        """Reject forged ownership and stale session authority before any publication."""
+        owner, snapshot = intent.operation, intent.snapshot
+        service = self.repository_operation
+        service.validate(owner)
+        if (service.active_by_id.get(owner.operation_id) is not owner or service.closed or service.allows is not None and not service.allows(owner)
+                or owner.key != snapshot.key or owner.context != snapshot.context or owner.git_filename != snapshot.git_filename):
+            raise ValueError("The conflict resolution no longer owns this repository or session")
+
+    def unstage_file(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...]) -> str:
+        """Restore selected index entries to HEAD while retaining every working byte."""
+        return self._submit(snapshot, entries, "unstage")
+
+    def stop_tracking(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...]) -> str:
+        """Remove selected index entries with Git's native safety checks and preserve disk content."""
+        return self._submit(snapshot, entries, "stop tracking")
+
+    def stage_lines(self, model: RawPatch, selection: RawLineSelection) -> str:
+        """Publish selected canonical lines using the same index reservation and validation."""
+        return self._submit(model.snapshot, (model.entry,), "stage", model, selection)
+
+    def prepare_reset_lines(self, model: RawPatch, selection: RawLineSelection, callback: Callable[[PreparedLineReset | None, Exception | None], None]) -> str:
+        """Reserve the worktree and compute the exact selected-line result before publication.
+
+        A refused reservation hands the callback the real cause of the refusal.
+        """
+        operation_id = uuid.uuid4().hex
+        if not self.acquire(model.snapshot, operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.acquire_refusal_cause(model.snapshot, operation_id, action=OperationAction.WORKTREE_EDIT)
+            QTimer.singleShot(0, lambda: callback(None, ValueError(cause)))
+            return operation_id
+
+        def complete(prepared: PreparedLineReset | None, error: Exception | None) -> None:
+            """Keep successful candidates reserved while releasing failed computations."""
+            if error is not None:
+                self.release(model.snapshot.key, operation_id)
+            else:
+                self.prepared_reset_by_id[operation_id] = prepared
+            callback(prepared, error)
+
+        self.worktree_service.run(model.snapshot.context, model.snapshot.git_filename, self._prepare_reset(operation_id, model, selection), complete, operation_id=operation_id)
+        return operation_id
+
+    def cancel_reset_lines(self, prepared: PreparedLineReset) -> None:
+        """Discard only an owned unpublished candidate when its source view or selection expires."""
+        if self.prepared_reset_by_id.get(prepared.operation_id) is not prepared:
+            return
+        self.prepared_reset_by_id.pop(prepared.operation_id)
+        self.release(prepared.model.snapshot.key, prepared.operation_id)
+        prepared.record_by_name["state"] = JournalState.ABANDONED.value
+        write_record(prepared.operation_dir, prepared.record_by_name)
+        self._clean_file_content(prepared)
+
+    def reset_lines(self, prepared: PreparedLineReset) -> str:
+        """Publish the exact calculated candidate; a changed target requires a fresh selection."""
+        if self.prepared_reset_by_id.pop(prepared.operation_id, None) is not prepared:
+            raise ValueError("This reset selection is no longer current")
+
+        def complete(outcome: MutationOutcome | None, error: Exception | None) -> None:
+            """Release the worktree after the last process and recovery action have finished."""
+            self.release(prepared.model.snapshot.key, prepared.operation_id)
+            if error is not None:
+                outcome = self._line_reset_failure(prepared, error)
+            self._publish_outcome(outcome)
+
+        self.worktree_service.run(prepared.model.snapshot.context, prepared.model.snapshot.git_filename, self._publish_file(prepared), complete, operation_id=prepared.operation_id)
+        return prepared.operation_id
+
+    def _prepare_reset(self, operation_id: str, model: RawPatch, selection: RawLineSelection) -> Generator:
+        """Materialize outside user content and record the exact before/after file images.
+
+        Nothing live changes here, so both boundaries check the index bytes and the selected file without Git; Git
+        verifies once, under the publication lock.
+        """
+        from gitpane.worktree.partial_patch import reset_content
+
+        snapshot, path = model.snapshot, model.entry.path
+        model.selected(selection)
+        recovery = self.recover(snapshot.context, snapshot.index_filename, operation_id=operation_id)
+        if recovery:
+            raise ValueError(recovery)
+        yield FileTask(lambda: verify_local_state(snapshot, (path,)))
+        before = yield FileTask(lambda: capture_image(snapshot.context, path, allow_missing_parents=True))
+        if before.exists and not stat.S_ISREG(before.mode):
+            raise ValueError("Partial reset requires a regular working file")
+        root_dir = os.path.join(snapshot.context.git_dir, "gitpane-operation")
+        os.makedirs(root_dir, mode=PRIVATE_DIRECTORY_MODE, exist_ok=True)
+        operation_dir = os.path.join(root_dir, operation_id)
+        os.mkdir(operation_dir, PRIVATE_DIRECTORY_MODE)
+        private_dir = private_file_dir(snapshot.context, path, operation_dir, allow_missing_parents=True)
+        candidate_filename = os.path.join(private_dir, "after-file")
+        backup_filename = os.path.join(private_dir, "before-file")
+        record_by_name: dict[str, object] = {"schema_version": JOURNAL_SCHEMA_VERSION, "kind": JournalKind.FILE.value, "operation_id": operation_id,
+            "index_filename": snapshot.index_filename, "path_hex": path.hex(), "before": before.digest(), "before_mode": before.mode, "before_absent": not before.exists,
+            "before_identity": before.identity, "after": None, "state": JournalState.PREPARING.value, "private_dir": private_dir,
+            "private_identity": stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS], "candidate_filename": candidate_filename, "backup_filename": backup_filename}
+        write_record(operation_dir, record_by_name)
+        try:
+            if before.exists:
+                yield FileTask(lambda: write_image(backup_filename, FileImage(True, stat.S_IFREG | PRIVATE_FILE_MODE, before.read())))
+            attributes = yield GitCommand(["check-attr", "-z", "filter", "working-tree-encoding", "--stdin"], stdin=path + b"\0")
+            attribute_by_name: dict[bytes, bytes] = {}
+            fields = iter(attributes.removesuffix(b"\0").split(b"\0"))
+            for _path in fields:
+                name, value = next(fields), next(fields)
+                attribute_by_name[name] = value
+            encoding_value = attribute_by_name.get(b"working-tree-encoding", b"unspecified")
+            encoding = "" if encoding_value in (b"unspecified", b"unset") else encoding_value.decode("ascii")
+            filter_value = attribute_by_name.get(b"filter", b"unspecified")
+            has_filter = filter_value not in (b"unspecified", b"unset")
+            restored = FileImage(False, 0)
+            if model.before_oid:
+                restored = yield from materialize_blob(model.before_oid, path, model.mode, os.path.join(private_dir, "materialized-index"))
+            materialized_working = FileImage(False, 0)
+            if has_filter and model.after_oid:
+                materialized_working = yield from materialize_blob(model.after_oid, path, model.mode, os.path.join(private_dir, "materialized-working"))
+            content = yield from reset_content(model, selection, before, restored, materialized_working, encoding, has_filter)
+            mode = before.mode if before.exists else stat.S_IFREG | (0o755 if model.mode == "100755" else 0o644)
+            after = FileImage(content is not None, mode, content)
+            after = yield FileTask(lambda: prepare_publication_image(candidate_filename, after, before))
+            if after.exists:
+                metadata = os.lstat(candidate_filename)
+                after = replace(after, identity=stat_identity(metadata), parents=before.parents)
+            else:
+                after = FileImage(False, 0, parents=before.parents)
+            yield FileTask(lambda: verify_local_state(snapshot, (path,)))
+            yield FileTask(lambda: validate_image(snapshot.context, path, before))
+            identity_by_basename: dict[str, tuple[int, ...]] = {}
+            for basename in ("after-file", "before-file", "materialized-index", "materialized-working"):
+                filename = os.path.join(private_dir, basename)
+                if os.path.exists(filename):
+                    identity_by_basename[basename] = stat_identity(os.lstat(filename))
+            record_by_name.update({"after": after.digest(), "after_identity": after.identity, "state": JournalState.PREPARED.value, "owned_identity_by_basename": identity_by_basename})
+            write_record(operation_dir, record_by_name)
+            return PreparedLineReset(operation_id, model, selection, before, after, operation_dir, private_dir, candidate_filename, backup_filename, record_by_name)
+        except (OSError, ValueError, RuntimeError):
+            record_by_name["state"] = JournalState.ABANDONED.value
+            write_record(operation_dir, record_by_name)
+            raise
+
+    def _publish_file(self, prepared: PreparedLineReset) -> Generator:
+        """Replace only an unchanged target, preserving recovery bytes after any publication failure.
+
+        The index lock stays empty: it only excludes other index writers while the working file changes. Git verifies
+        once under it, after the private candidate is proven, and local reference reads taken before and after that
+        verification replace a separate HEAD read.
+        """
+        snapshot, path = prepared.model.snapshot, prepared.model.entry.path
+        filename, _parents = validate_destination(snapshot.context, path, allow_missing_parents=True)
+        lock_filename = snapshot.index_filename + ".lock"
+        lock_descriptor: int | None = None
+        lock_identity: tuple[int, int] | None = None
+        published = False
+        created_dirs: list[tuple[str, tuple[int, int]]] = []
+        prepared.record_by_name["created_dirs"] = created_dirs
+        try:
+            lock_descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+            metadata = os.fstat(lock_descriptor)
+            lock_identity = (metadata.st_dev, metadata.st_ino)
+            yield FileTask(lambda: validate_image(snapshot.context, path, prepared.before))
+            private_identity = stat_identity(os.lstat(prepared.private_dir))[:FILE_OBJECT_IDENTITY_FIELDS]
+            if tuple(prepared.record_by_name["private_identity"]) != private_identity or os.path.islink(prepared.private_dir) or os.path.isjunction(prepared.private_dir):
+                raise ValueError("Private preparation directory changed")
+            if prepared.after.exists:
+                metadata = os.lstat(prepared.candidate_filename)
+                if stat_identity(metadata) != prepared.after.identity or not stat.S_ISREG(metadata.st_mode):
+                    raise ValueError("Private reset candidate changed")
+                with open(prepared.candidate_filename, "rb") as stream:
+                    if stream.read() != prepared.after.read():
+                        raise ValueError("Private reset candidate changed")
+            prepared.record_by_name["state"] = JournalState.PREPARED.value
+            write_record(prepared.operation_dir, prepared.record_by_name)
+            authority = yield FileTask(lambda: reset_recovery_authority(snapshot.context))
+            yield from self.worktree_service.verify(snapshot, (path,))
+            yield FileTask(lambda: require_unchanged_authority(snapshot.context, authority))
+            metadata = os.lstat(lock_filename)
+            if not stat.S_ISREG(metadata.st_mode) or (metadata.st_dev, metadata.st_ino) != lock_identity or metadata.st_size:
+                lock_identity = None
+                raise ValueError("The publication lock was replaced externally")
+            # Recheck after the journal flush because an external editor is not blocked by Git's index lock.
+            validate_image(snapshot.context, path, prepared.before)
+            if read_index(snapshot.index_filename) != snapshot.index_content:
+                raise ValueError("The index changed after confirmation")
+            self.validate_write(snapshot.key)
+            if prepared.after.exists:
+                create_missing_parents(snapshot.context, path, prepared.before, created_dirs, lambda: write_record(prepared.operation_dir, prepared.record_by_name))
+                publish_image_mode(prepared.candidate_filename, prepared.after)
+                identity = stat_identity(os.lstat(prepared.candidate_filename))
+                prepared.record_by_name["after_identity"] = identity
+                prepared.record_by_name["owned_identity_by_basename"][os.path.basename(prepared.candidate_filename)] = identity
+                write_record(prepared.operation_dir, prepared.record_by_name)
+                validate_image(snapshot.context, path, publication_image(prepared.before, created_dirs))
+                os.replace(prepared.candidate_filename, filename)
+            elif prepared.before.exists:
+                os.unlink(filename)
+            published = True
+            prepared.record_by_name["working_file_published"] = True
+            prepared.record_by_name["state"] = JournalState.FILE_PUBLISHED.value
+            write_record(prepared.operation_dir, prepared.record_by_name)
+            actual = capture_image(snapshot.context, path)
+            if actual.digest() != prepared.after.digest():
+                raise ValueError("Working file changed immediately after publication")
+            outcome = MutationOutcome(prepared.operation_id, snapshot.key, "success", (path,), ())
+        except (OSError, ValueError, RuntimeError) as error:
+            status = "refused"
+            if not published:
+                try:
+                    actual = capture_image(snapshot.context, path)
+                    published = actual.digest() == prepared.after.digest() and actual.digest() != prepared.before.digest()
+                    prepared.record_by_name["working_file_published"] = published
+                except (OSError, ValueError):
+                    pass
+            if published:
+                status = "unknown"
+                try:
+                    actual = capture_image(snapshot.context, path)
+                    expected_identity = prepared.record_by_name["after_identity"]
+                    # Some filesystems update ctime on rename; content, mode and inode still identify our publication.
+                    same_identity = not actual.exists and not prepared.after.exists
+                    if actual.exists and actual.identity is not None and expected_identity is not None:
+                        same_identity = actual.identity[:FILE_STABLE_IDENTITY_FIELDS] == tuple(expected_identity)[:FILE_STABLE_IDENTITY_FIELDS]
+                    if actual.digest() == prepared.after.digest() and actual.parents == publication_image(prepared.before, created_dirs).parents and same_identity:
+                        if prepared.before.exists:
+                            rollback_filename = os.path.join(prepared.private_dir, "rollback-file")
+                            write_image(rollback_filename, prepared.before)
+                            validate_image(snapshot.context, path, actual)
+                            os.replace(rollback_filename, filename)
+                        elif actual.exists:
+                            validate_image(snapshot.context, path, actual)
+                            os.unlink(filename)
+                        status = "rolled_back"
+                        prepared.record_by_name["working_file_published"] = False
+                except (OSError, ValueError):
+                    pass
+            journal_state = JournalState.ROLLED_BACK if status == "rolled_back" else JournalState.FILE_PUBLISHED if published else JournalState.ABANDONED
+            prepared.record_by_name["state"] = journal_state.value
+            try:
+                write_record(prepared.operation_dir, prepared.record_by_name)
+            except OSError:
+                pass
+            cause = recovery_files_cause(str(error), prepared.operation_dir) if published else str(error)
+            diagnostic = Diagnostic("Reset selected lines", snapshot.context.repository_dir, snapshot.git_filename, [], cause).prepare()
+            outcome = MutationOutcome(prepared.operation_id, snapshot.key, status, (path,) if status == "unknown" else (), (path,), diagnostic, prepared.operation_dir)
+        finally:
+            clean_created_parents(created_dirs)
+            try:
+                release_owned_index_lock(lock_filename, lock_descriptor, lock_identity)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._line_reset_failure(prepared, error)
+        if outcome.diagnostic is None:
+            try:
+                # Lock cleanup is part of publication, so recovery files outlive it.
+                prepared.record_by_name["state"] = JournalState.COMPLETE.value
+                write_record(prepared.operation_dir, prepared.record_by_name)
+                self._clean_file_content(prepared)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._line_reset_failure(prepared, error)
+        return outcome
+
+    def _line_reset_failure(self, prepared: PreparedLineReset, error: Exception) -> MutationOutcome:
+        """Report cleanup faults from recorded publication facts without rolling back later local content."""
+        snapshot, path = prepared.model.snapshot, prepared.model.entry.path
+        published = bool(prepared.record_by_name.get("working_file_published"))
+        # The word this process wrote is compared as text: reading it back as a member could raise inside this failure handler.
+        rolled_back = prepared.record_by_name.get("state") == JournalState.ROLLED_BACK.value
+        status = "unknown" if published else "rolled_back" if rolled_back else "refused"
+        journal_state = JournalState.FILE_PUBLISHED if published else JournalState.ROLLED_BACK if rolled_back else JournalState.ABANDONED
+        prepared.record_by_name["state"] = journal_state.value
+        try:
+            write_record(prepared.operation_dir, prepared.record_by_name)
+        except OSError:
+            pass
+        diagnostic = Diagnostic("Reset selected lines", snapshot.context.repository_dir, snapshot.git_filename, [], recovery_files_cause(str(error), prepared.operation_dir)).prepare()
+        return MutationOutcome(prepared.operation_id, snapshot.key, status, (path,) if published else (), (path,), diagnostic, prepared.operation_dir)
+
+    def _clean_file_content(self, prepared: PreparedLineReset) -> None:
+        """Remove only files owned by a completed or cancelled operation."""
+        actual = os.lstat(prepared.private_dir)
+        if os.path.islink(prepared.private_dir) or os.path.isjunction(prepared.private_dir) or stat_identity(actual)[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(prepared.record_by_name["private_identity"]):
+            raise ValueError("Private cleanup directory changed; recovery files retained")
+        for basename, identity in prepared.record_by_name["owned_identity_by_basename"].items():
+            filename = os.path.join(prepared.private_dir, basename)
+            if not os.path.lexists(filename):
+                continue
+            if os.path.islink(filename) or stat_identity(os.lstat(filename)) != tuple(identity):
+                raise ValueError("Owned recovery file changed; cleanup refused")
+            os.unlink(filename)
+        if prepared.private_dir != prepared.operation_dir:
+            os.rmdir(prepared.private_dir)
+
+    def _submit(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], operation: str, model: RawPatch | None = None, selection: RawLineSelection | None = None) -> str:
+        """Reserve one worktree until computation, publication and terminal reporting finish.
+
+        A refused reservation is reported with the real cause of the refusal.
+        """
+        operation_id = uuid.uuid4().hex
+        paths = tuple(dict.fromkeys(path for entry in entries for path in entry.paths))
+        action = OperationAction.UNSTAGE if operation == "unstage" else OperationAction.STAGE
+        if not self.acquire(snapshot, operation_id, action=action):
+            diagnostic = Diagnostic(operation, snapshot.context.repository_dir, snapshot.git_filename, [], self.acquire_refusal_cause(snapshot, operation_id, action=action)).prepare()
+            outcome = MutationOutcome(operation_id, snapshot.key, "refused", (), paths, diagnostic)
+            QTimer.singleShot(0, lambda: self._publish_outcome(outcome))
+            return operation_id
+
+        def complete(value: object, error: Exception | None) -> None:
+            """Retain failures as terminal results, releasing the reservation only now."""
+            self.release(snapshot.key, operation_id)
+            if error is not None:
+                diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+                value = MutationOutcome(operation_id, snapshot.key, "refused", (), paths, diagnostic)
+            self._publish_outcome(value)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._prepare(operation_id, snapshot, entries, operation, model, selection), complete, operation_id=operation_id)
+        return operation_id
+
+    def _publish_outcome(self, outcome: MutationOutcome) -> None:
+        """Preserve the result for reopening and request authoritative state after every issue."""
+        self.outcome_by_id[outcome.operation_id] = outcome
+        self.reread_requested.emit(outcome.key)
+        self.finished.emit(outcome)
+
+    def recover(self, context: RepositoryContext, index_filename: str, *, operation_id: str | None = None) -> str:
+        """Classify interrupted operations and restore proven Reset effects under explicit authority."""
+        root_dir = os.path.join(context.git_dir, "gitpane-operation")
+        if not os.path.exists(root_dir):
+            return ""
+        if os.path.islink(root_dir) or os.path.isjunction(root_dir) or not os.path.isdir(root_dir):
+            return "The recovery directory is not a private directory"
+        diagnostics: list[str] = []
+        with os.scandir(root_dir) as iterator:
+            operation_dirs = sorted(iterator, key=lambda entry: entry.name)
+        for entry in operation_dirs:
+            if entry.name in self.prepared_file_reset_by_id or entry.name in self.live_reset_id_set:
+                continue
+            if not entry.is_dir(follow_symlinks=False) or os.path.isjunction(entry.path) or len(entry.name) != len(uuid.uuid4().hex) or any(character not in "0123456789abcdef" for character in entry.name):
+                diagnostics.append("Unrecognized recovery data requires inspection")
+                continue
+            record_filename = os.path.join(entry.path, "record.json")
+            try:
+                if os.path.islink(record_filename):
+                    raise ValueError("Linked recovery record")
+                if os.stat(record_filename).st_size > MUTATION_RECORD_LIMIT_BYTES:
+                    raise ValueError("Recovery record exceeds the supported limit")
+                with open(record_filename, encoding="utf-8") as stream:
+                    record_by_name = json.load(stream)
+                if record_by_name.get("schema_version") != JOURNAL_SCHEMA_VERSION or record_by_name.get("index_filename") != index_filename:
+                    raise ValueError("Unrecognized recovery record")
+                # Both words are read once here, so a word this version does not know, or an empty one, stops the
+                # inspection of this journal and leaves it untouched for the user.
+                state = read_journal_state(record_by_name)
+                kind = read_journal_kind(record_by_name)
+                if state in FINISHED_JOURNAL_STATE_SET:
+                    continue
+                if kind == JournalKind.RESET:
+                    diagnostic = self._recover_reset(context, entry.path, record_by_name, operation_id)
+                    if diagnostic:
+                        diagnostics.append(diagnostic)
+                    continue
+                if kind == JournalKind.FILE:
+                    path = bytes.fromhex(record_by_name["path_hex"])
+                    image = capture_image(context, path, allow_missing_parents=True)
+                    if image.digest() == record_by_name.get("before"):
+                        record_by_name["state"] = JournalState.RECOVERED_PRE.value
+                    elif image.digest() == record_by_name.get("after"):
+                        record_by_name["state"] = JournalState.RECOVERED_POST.value
+                    else:
+                        diagnostics.append(recovery_files_cause("Working file changed outside the interrupted operation: " + os.fsdecode(path) + ".", entry.path))
+                        continue
+                    write_record(entry.path, record_by_name)
+                    continue
+                if os.path.lexists(index_filename + ".lock"):
+                    diagnostics.append("An interrupted operation has an index lock; ownership cannot be proven")
+                    continue
+                current = fingerprint(read_index(index_filename))
+                if current == record_by_name.get("before"):
+                    record_by_name["state"] = JournalState.RECOVERED_PRE.value
+                elif current == record_by_name.get("after"):
+                    record_by_name["state"] = JournalState.RECOVERED_POST.value
+                else:
+                    diagnostics.append("The index changed outside the interrupted operation; recovery data retained")
+                    continue
+                write_record(entry.path, record_by_name)
+            except (OSError, ValueError, TypeError, KeyError) as error:
+                diagnostics.append("Cannot inspect interrupted operation: " + str(error))
+        return "\n".join(diagnostics)
+
+    def _prepare(self, operation_id: str, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], operation: str,
+                 model: RawPatch | None = None, selection: RawLineSelection | None = None,
+                 resolution: ConflictResolutionIntent | None = None) -> Generator[GitCommand, bytes, MutationOutcome]:
+        """Compute outside the real index, recheck under exclusive lock, then publish once.
+
+        Every form, a conflict resolution included, writes its candidate into the owned lock and makes it durable
+        before Git's single final verification, which reads HEAD itself. Local reads of references, configuration
+        files and the native rebase are taken before that verification and compared again just before publication,
+        so a change made after Git answered cannot pass for the verified state. A resolution also rechecks the
+        identity of its accepted file and its exact owner at that last point.
+        """
+        if not snapshot.fresh or snapshot.context.is_bare or snapshot.context.worktree_dir is None:
+            raise ValueError("A complete current working tree read is required")
+        side = StagingSide.UNSTAGED if operation in ("stage", "stop tracking", "resolve conflict") else StagingSide.STAGED
+        if not entries or any(entry not in snapshot.entries or entry.side != side for entry in entries):
+            raise ValueError("Choose current " + side.label + " files")
+        if operation == "stage":
+            entries = tuple(entry for entry in entries if entry.stageable)
+            if not entries:
+                raise ValueError(SUBMODULE_NO_COMMIT_CHANGE)
+        if resolution is None and any(entry.conflict_stages for entry in snapshot.entries):
+            intent = self.repository_operation.active_by_id.get(operation_id)
+            # Preparing unrelated files is allowed only under the captured native rebase authority.
+            if any(entry.conflict_stages for entry in entries) or intent is None or not any(intent.rebase_capture or ()):
+                raise ValueError("Resolve all conflicts before preparing changes")
+        if any(entry.skip_worktree for entry in entries):
+            raise ValueError("This file is marked skip-worktree; expand it before preparing changes")
+        if operation == "stop tracking" and any(entry.old_mode not in ("100644", "100755", "120000") for entry in entries):
+            raise ValueError("Stop tracking requires tracked ordinary files")
+        paths = (resolution.path,) if resolution is not None else tuple(dict.fromkeys(path for entry in entries for path in entry.paths))
+        outcome_id = resolution.operation.operation_id if resolution is not None else operation_id
+        recovery = self.recover(snapshot.context, snapshot.index_filename, operation_id=operation_id)
+        if recovery:
+            raise ValueError(recovery)
+        # Only a private candidate is built before locking. Defer the complete Git
+        # metadata check until publication, while rejecting already-stale bytes now.
+        yield FileTask(lambda: verify_local_state(snapshot, paths))
+        root_dir = os.path.join(snapshot.context.git_dir, "gitpane-operation")
+        os.makedirs(root_dir, mode=PRIVATE_DIRECTORY_MODE, exist_ok=True)
+        operation_dir = os.path.join(root_dir, operation_id)
+        os.mkdir(operation_dir, PRIVATE_DIRECTORY_MODE)
+        candidate_filename = os.path.join(operation_dir, "candidate-index")
+        backup_filename = os.path.join(operation_dir, "before-index")
+        record_by_name: dict[str, object] = {"schema_version": JOURNAL_SCHEMA_VERSION, "operation_id": operation_id, "index_filename": snapshot.index_filename,
+                                           "before": snapshot.index_fingerprint, "after": None, "index_absent": snapshot.index_content is None, "state": JournalState.PREPARING.value}
+        write_record(operation_dir, record_by_name)
+        environment_by_name = {"GIT_INDEX_FILE": candidate_filename}
+        lock_filename = snapshot.index_filename + ".lock"
+        lock_descriptor: int | None = None
+        lock_identity: tuple[int, int] | None = None
+        published = False
+        try:
+            if snapshot.index_content is not None:
+                # Preserve the index timestamp: changing it can make Git trust a same-size racy stat entry.
+                shutil.copy2(snapshot.index_filename, candidate_filename)
+                os.chmod(candidate_filename, PRIVATE_FILE_MODE)
+                if read_index(candidate_filename) != snapshot.index_content:
+                    raise ValueError("The index changed while preparing its private copy")
+                with open(backup_filename, "xb") as stream:
+                    os.chmod(backup_filename, PRIVATE_FILE_MODE)
+                    stream.write(snapshot.index_content)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+            else:
+                yield GitCommand(["read-tree", "--empty"], environment_by_name=environment_by_name, profile=LOCAL_WRITE_PROFILE)
+            # Ordinary indexes avoid an unnecessary process; only a possible split index is flattened.
+            if may_carry_split_index(snapshot.index_content):
+                yield GitCommand(["update-index", "--no-split-index"], environment_by_name=environment_by_name, profile=LOCAL_WRITE_PROFILE)
+            before_entries = snapshot.index_entries
+            if before_entries is None:
+                before_entries = yield GitCommand(["ls-files", "--stage", "-z"], environment_by_name=environment_by_name)
+            expected_line_record: bytes | None = None
+            if model is not None:
+                from gitpane.worktree.partial_patch import stage_candidate
+                expected_line_record = yield from stage_candidate(model, selection, environment_by_name)
+                arguments = None
+            elif operation in ("stage", "resolve conflict"):
+                arguments = ["add", "--pathspec-from-file=-", "--pathspec-file-nul"]
+            elif operation == "stop tracking":
+                arguments = ["rm", "--cached", "--pathspec-from-file=-", "--pathspec-file-nul"]
+            elif snapshot.head_oid is not None:
+                arguments = ["restore", "--staged", "--source=" + snapshot.head_oid, "--pathspec-from-file=-", "--pathspec-file-nul"]
+            else:
+                arguments = ["update-index", "--force-remove", "-z", "--stdin"]
+            if arguments is not None:
+                # Every form of this command rewrites the candidate index, and add also runs the user's clean filters, which can outlive it.
+                # It declares its own supervised profile: the merge tool publishes through a sequence started without one, whose metadata reads stay lightweight.
+                yield GitCommand(arguments, stdin=b"\0".join(paths) + b"\0", environment_by_name=environment_by_name,
+                                 timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=MUTATION_IDLE_TIMEOUT_MS, profile=LOCAL_WRITE_PROFILE)
+            after_entries = yield GitCommand(["ls-files", "--stage", "-z"], environment_by_name=environment_by_name)
+            unchanged_records = []
+            path_set = set(paths)
+            for output in (before_entries, after_entries):
+                if output and not output.endswith(b"\0"):
+                    raise ValueError("Incomplete candidate index entries")
+                records = []
+                for record in output.split(b"\0"):
+                    _metadata, separator, path = record.partition(b"\t")
+                    if record and not separator:
+                        raise ValueError("Malformed candidate index entry")
+                    if record and path not in path_set:
+                        records.append(record)
+                unchanged_records.append(sorted(records))
+            before_unchanged, after_unchanged = unchanged_records
+            if before_unchanged != after_unchanged:
+                raise ValueError("The candidate changed files outside the selection")
+            if model is not None:
+                # The listing that proves the neighbors unchanged also proves the staged lines: exactly the expected
+                # record at the selected path, or no record at all after a total removal.
+                line_records = []
+                for record in after_entries.split(b"\0"):
+                    if record and record.partition(b"\t")[2] == model.entry.path:
+                        line_records.append(record + b"\0")
+                if line_records != ([] if expected_line_record is None else [expected_line_record]):
+                    raise ValueError("The candidate index does not hold the selected lines")
+            if resolution is not None:
+                selected_records = []
+                for record in after_entries.split(b"\0"):
+                    metadata, _separator, path = record.partition(b"\t")
+                    if path == resolution.path:
+                        selected_records.append(metadata)
+                if resolution.delete:
+                    valid_result = not selected_records
+                else:
+                    valid_result = len(selected_records) == 1 and next(iter(selected_records)).endswith(b" 0")
+                if not valid_result:
+                    raise ValueError("The candidate did not resolve the selected conflict")
+            candidate = read_index(candidate_filename)
+            if candidate is None:
+                raise ValueError("Git did not produce a candidate index")
+            record_by_name["after"] = fingerprint(candidate)
+            record_by_name["state"] = JournalState.PREPARED.value
+            write_record(operation_dir, record_by_name)
+            lock_descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+            metadata = os.fstat(lock_descriptor)
+            lock_identity = (metadata.st_dev, metadata.st_ino)
+            # The durable prepared record already describes both possible index images.
+            # Recovery classifies those bytes and any remaining lock without intermediate records.
+            descriptor, lock_descriptor = lock_descriptor, None
+            fill_owned_lock(descriptor, candidate)
+            authority = yield FileTask(lambda: reset_recovery_authority(snapshot.context))
+            yield from self.worktree_service.verify(snapshot, paths)
+            # Git's lock protects the index; an editor can still change working bytes independently.
+            for path in paths:
+                actual = yield FileTask(lambda path=path: file_fingerprint(snapshot.context, path))
+                expected = snapshot.fingerprint_by_path[path]
+                if expected.startswith(actual + ":"):
+                    from gitpane.tool.system_tool import worktree_filename
+                    submodule_head = yield GitCommand(["-C", worktree_filename(snapshot.context, path), "rev-parse", "--verify", "HEAD"])
+                    actual += ":" + submodule_head.strip().decode("ascii")
+                if actual != expected:
+                    raise ValueError("Working file changed before publication; refresh the changes")
+            if resolution is not None:
+                # The accepted result is bound to its file identity and parents, which a byte fingerprint alone does not prove.
+                yield FileTask(lambda: validate_image(snapshot.context, resolution.path, resolution.image))
+            yield FileTask(lambda: require_unchanged_authority(snapshot.context, authority))
+            if read_index(snapshot.index_filename) != snapshot.index_content:
+                raise ValueError("The index changed before publication")
+            metadata = os.lstat(lock_filename)
+            if (metadata.st_dev, metadata.st_ino) != lock_identity or read_index(lock_filename) != candidate:
+                lock_identity = None
+                raise ValueError("The publication lock was replaced externally")
+            if resolution is None:
+                self.validate_write(snapshot.key)
+            else:
+                self._validate_conflict_owner(resolution)
+            os.replace(lock_filename, snapshot.index_filename)
+            published = True
+            lock_identity = None
+            record_by_name["state"] = JournalState.COMPLETE.value
+            write_record(operation_dir, record_by_name)
+            return MutationOutcome(outcome_id, snapshot.key, "success", paths, ())
+        except (OSError, ValueError, RuntimeError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+            if operation == "stop tracking":
+                diagnostic = replace(diagnostic, cause=diagnostic.cause + " Review the staged version before retrying; no files were removed from disk.")
+            if not published:
+                record_by_name["state"] = JournalState.ABANDONED.value
+            try:
+                write_record(operation_dir, record_by_name)
+            except OSError:
+                pass
+            return MutationOutcome(outcome_id, snapshot.key, "unknown" if published else "refused", paths if published else (), () if published else paths, diagnostic, operation_dir)
+        finally:
+            if lock_descriptor is not None:
+                os.close(lock_descriptor)
+            if lock_identity is not None:
+                try:
+                    metadata = os.lstat(lock_filename)
+                    if stat.S_ISREG(metadata.st_mode) and (metadata.st_dev, metadata.st_ino) == lock_identity:
+                        os.unlink(lock_filename)
+                except FileNotFoundError:
+                    pass
+
+    def _validate(self, snapshot: WorktreeSnapshot, current: WorktreeSnapshot, paths: tuple[bytes, ...]) -> None:
+        """Refuse stale index, HEAD, conversion settings or selected working bytes."""
+        if snapshot.head_oid != current.head_oid or snapshot.index_content != current.index_content or snapshot.conversion != current.conversion:
+            raise ValueError("Repository changed since selection; refresh the changes")
+        if snapshot.key != current.key or canonical_path(snapshot.index_filename) != canonical_path(current.index_filename):
+            raise ValueError("The selected index does not belong to this worktree")
+        for path in paths:
+            if snapshot.fingerprint_by_path.get(path) != current.fingerprint_by_path.get(path):
+                raise ValueError("Working file changed since selection; refresh the changes")