gitpane 1.0.0__py3-none-any.whl

gitpane/reference/stash.py

@@ -0,0 +1,730 @@
+"""Run native stash commands, keeping their observed effects with the authority they started from."""
+
+from __future__ import annotations
+
+import os
+import stat
+import uuid
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_MUTATION_TIMEOUT_MS, GIT_PATH_SEPARATOR, SUBMODULE_RECURSION_OFF_ARGUMENTS
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, READ_PROFILE, ProcessStatus
+from gitpane.system.path_identity import canonical_path
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.operation.launch_signature import LaunchSignature
+    from gitpane.operation.repository_operation import OperationIntent, OperationOutcome, RepositoryOperationService
+    from gitpane.reference.stash_list import StashEntry, StashList
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry, WorktreeSnapshot
+
+STASH_INCLUDE_UNTRACKED_KEY = "stash_include_untracked"
+STASH_KEEP_INDEX_KEY = "stash_keep_index"
+STASH_DEFAULT_BY_KEY = {STASH_INCLUDE_UNTRACKED_KEY: True, STASH_KEEP_INDEX_KEY: False}
+STASH_REFERENCE = "refs/stash"
+# Where the files backend keeps the stash reflog, relative to the shared Git directory Git already resolved.
+STASH_REFLOG_DIR_PARTS = ("logs", "refs")
+STASH_REFLOG_BASENAME = "stash"
+STASH_CHANGED_CAUSE = "Stash changed during reading; refresh the repository"
+NEW_CHANGE_CAUSE = "Working files, index or HEAD changed; reopen the form after refreshing"
+CREATE_CHANGED_CAUSE = "Working files, index, HEAD or stash authority changed before launch; reopen the form"
+POP_CHANGED_CAUSE = "Stash, working files, index or authority changed before launch; refresh the repository"
+DROP_CHANGED_CAUSE = "The stash list changed since it was read; refresh the repository and try again"
+DROP_AMBIGUOUS_CAUSE = "Several stashes hold this same stash commit; drop the right one from the left panel"
+DROP_CONFLICT_CAUSE = "Merge conflicts remain in the working tree; the stash is kept"
+DROP_OPERATION_LABEL = "Drop stash"
+
+
+def stash_reflog_filename(context: RepositoryContext) -> str:
+    """Name the shared stash reflog of the files backend; a reftable store keeps it in its tables instead."""
+    return os.path.join(context.common_git_dir, *STASH_REFLOG_DIR_PARTS, STASH_REFLOG_BASENAME)
+
+
+def capture_stash_signature(context: RepositoryContext, filenames: tuple[str, ...] = (), watched_dirs: tuple[str, ...] = (),
+                            parent_dirs: tuple[str, ...] = ()) -> LaunchSignature:
+    """Take the metadata, without any content, of the shared stash storage plus the given paths.
+
+    The stash storage is every file and folder the reference signature covers (loose, packed and table references,
+    configuration, linked worktrees) and the stash reflog with each of its folders, present or absent, so a reflog
+    that appears, grows or is replaced changes the signature. Runs on a worker: it walks the reference folders.
+    """
+    from gitpane.operation.launch_signature import sign_launch_paths
+    from gitpane.reference.reference_edit import reference_signature_paths
+
+    reference_filenames, reference_dirs = reference_signature_paths(context)
+    reflog_filename = stash_reflog_filename(context)
+    log_refs_dir = os.path.dirname(reflog_filename)
+    all_filenames = [*reference_filenames, reflog_filename, *filenames]
+    all_watched_dirs = [*reference_dirs, os.path.dirname(log_refs_dir), log_refs_dir, *watched_dirs]
+    all_parent_dirs = [context.common_git_dir, context.git_dir, *parent_dirs]
+    return sign_launch_paths(all_filenames, all_watched_dirs, all_parent_dirs)
+
+
+def refuse_new_changes(snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...]) -> None:
+    """Refuse a fresh status that shows a path the form's read did not: a new change or a new untracked file."""
+    for entry in entries:
+        for path in entry.paths:
+            if path not in snapshot.fingerprint_by_path:
+                raise ValueError(NEW_CHANGE_CAUSE)
+
+
+@dataclass(frozen=True)
+class StashLaunchBaseline:
+    """The first look one stash write relies on, taken on a worker before its policy and content checks.
+
+    ``signature`` holds only metadata of the checked files and folders. The other fields are the exact contents a
+    worker compares again once every check has passed, just before the command is handed to the launcher. Nothing
+    here authorizes a write by itself.
+    """
+
+    signature: LaunchSignature
+    reference_state: tuple
+    working_state: tuple
+    reflog_content: bytes | None
+
+
+def stash_launch_paths(context: RepositoryContext, paths: tuple[bytes, ...], untracked_dirs: tuple[str, ...], native_git_dirs: tuple[str, ...],
+                       index_filename: str) -> tuple[tuple[str, ...], tuple[str, ...], tuple[str, ...]]:
+    """List the files, watched folders and containing folders one stash write is checked against, besides the stash storage.
+
+    Files: the index, every path the native stash reads, the linked worktree pointers and the pause markers of every
+    related Git directory, so a rebase, cherry-pick, revert or merge started elsewhere is noticed. Watched folders:
+    the worktree root, each folder holding a checked path and the untracked folders a creation found, where a new
+    entry would change what Git stashes. Containing folders are compared by identity only. Runs on a worker.
+    """
+    from gitpane.operation.launch_signature import LINKED_COMMON_DIR_BASENAME, WORKTREE_GIT_ENTRY_BASENAME
+    from gitpane.operation.repository_operation import PAUSE_PROBE_GIT_PATHS
+    from gitpane.reference.reference_edit import reference_git_dirs
+    from gitpane.tool.system_tool import worktree_filename
+
+    worktree_dir = context.worktree_dir
+    if worktree_dir is None:
+        raise ValueError("A stash requires a working tree")
+    filenames = [index_filename, os.path.join(context.git_dir, LINKED_COMMON_DIR_BASENAME)]
+    watched_dirs = [worktree_dir, *untracked_dirs]
+    git_entry = os.path.join(worktree_dir, WORKTREE_GIT_ENTRY_BASENAME)
+    parent_dirs = [os.path.dirname(index_filename), git_entry]
+    if os.path.isfile(git_entry):
+        filenames.append(git_entry)
+    root_dir = os.path.normcase(os.path.abspath(worktree_dir))
+    for path in paths:
+        filename = worktree_filename(context, path)
+        filenames.append(filename)
+        directory = os.path.dirname(filename)
+        while os.path.normcase(directory) != root_dir:
+            watched_dirs.append(directory)
+            parent_dir = os.path.dirname(directory)
+            if parent_dir == directory:
+                raise ValueError("A stashed path is outside the working tree")
+            directory = parent_dir
+    for git_dir in sorted({*native_git_dirs, *reference_git_dirs(context)}):
+        parent_dirs.append(git_dir)
+        for git_path in PAUSE_PROBE_GIT_PATHS:
+            filenames.append(os.path.join(git_dir, *git_path.split(GIT_PATH_SEPARATOR)))
+    return tuple(filenames), tuple(watched_dirs), tuple(parent_dirs)
+
+
+def capture_stash_launch_baseline(context: RepositoryContext, index_filename: str, index_content: bytes | None, paths: tuple[bytes, ...],
+                                  untracked_dirs: tuple[str, ...], native_git_dirs: tuple[str, ...], changed_cause: str) -> StashLaunchBaseline:
+    """Take the first look of a stash write: the contents it will compare again, between two identical metadata looks.
+
+    The index must still be the one the write was asked with. Runs on a worker: it walks folders and reads contents.
+    """
+    from gitpane.operation.launch_signature import verify_launch_signature
+    from gitpane.reference.reference_edit import reference_signature, working_signature
+    from gitpane.worktree.worktree_snapshot import read_index
+
+    filenames, watched_dirs, parent_dirs = stash_launch_paths(context, paths, untracked_dirs, native_git_dirs, index_filename)
+    signature = capture_stash_signature(context, filenames, watched_dirs, parent_dirs)
+    if read_index(index_filename) != index_content:
+        raise ValueError(changed_cause)
+    reference_state = reference_signature(context)
+    working_state = working_signature(context, paths)
+    reflog_content = read_index(stash_reflog_filename(context))
+    verify_launch_signature(signature, changed_cause)
+    return StashLaunchBaseline(signature, reference_state, working_state, reflog_content)
+
+
+def prepare_stash_launch(context: RepositoryContext, baseline: StashLaunchBaseline, index_filename: str, index_content: bytes | None, paths: tuple[bytes, ...],
+                         untracked_signature: tuple[tuple[str, tuple[int, ...]], ...], changed_cause: str) -> LaunchSignature:
+    """Check, once every other check has passed, that nothing moved since the first look, and answer the signature the launch compares.
+
+    The contents are compared with the first look, between two metadata looks that must both match it: a change made
+    by another program meanwhile is refused, never adopted. Runs on a worker.
+    """
+    from gitpane.operation.launch_signature import verify_launch_signature
+    from gitpane.reference.reference_edit import reference_signature, working_signature
+    from gitpane.worktree.worktree_snapshot import read_index
+
+    verify_launch_signature(baseline.signature, changed_cause)
+    if (read_index(index_filename) != index_content or reference_signature(context) != baseline.reference_state
+            or working_signature(context, paths) != baseline.working_state or read_index(stash_reflog_filename(context)) != baseline.reflog_content):
+        raise ValueError(changed_cause)
+    untracked_dirs = []
+    for directory, _identity in untracked_signature:
+        untracked_dirs.append(directory)
+    if _directory_signature(tuple(untracked_dirs)) != untracked_signature:
+        raise ValueError(changed_cause)
+    verify_launch_signature(baseline.signature, changed_cause)
+    return baseline.signature
+
+
+def _write_paths(snapshot: WorktreeSnapshot) -> tuple[bytes, ...]:
+    """Include clean tracked files because native stash also reads changes made while queued."""
+    path_set = set(snapshot.fingerprint_by_path)
+    for record in (snapshot.index_entries or b"").split(b"\0"):
+        if record:
+            _metadata, _separator, path = record.partition(b"\t")
+            path_set.add(path)
+    return tuple(sorted(path_set))
+
+
+def _directory_signature(dirs: tuple[str, ...]) -> tuple[tuple[str, tuple[int, ...]], ...]:
+    """Detect new nested files through parent metadata without rereading ignored content."""
+    from gitpane.worktree.worktree_file import stat_identity
+
+    records = []
+    for directory in dirs:
+        metadata = os.lstat(directory)
+        if not stat.S_ISDIR(metadata.st_mode) or getattr(metadata, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0):
+            raise ValueError("An untracked directory changed type; reopen the stash form")
+        records.append((directory, stat_identity(metadata)))
+    return tuple(records)
+
+
+def _capture_untracked_directory_signature(context: RepositoryContext) -> Generator:
+    """Include initially empty directories while leaving Git-ignored trees unvisited."""
+    from gitpane.worktree.command_sequence import FileTask, GitCommand
+    from gitpane.worktree.worktree_file import validate_destination
+
+    worktree_dir = context.worktree_dir
+    if worktree_dir is None:
+        raise ValueError("Creating a stash requires a working tree")
+    root_signature = yield FileTask(lambda: _directory_signature((worktree_dir,)))
+    untracked = yield GitCommand(["ls-files", "--others", "--directory", "--exclude-standard", "-z"])
+    ignored = yield GitCommand(["ls-files", "--others", "--ignored", "--directory", "--exclude-standard", "-z"])
+
+    def capture() -> tuple[tuple[str, tuple[int, ...]], ...]:
+        """Enumerate directory metadata in the filesystem worker before capturing file content."""
+        ignored_dir_set = set()
+        for path in ignored.split(b"\0"):
+            if path.endswith(b"/"):
+                filename, _parents = validate_destination(context, path.rstrip(b"/"))
+                ignored_dir_set.add(os.path.normcase(filename))
+        pending_dirs = []
+        for path in untracked.split(b"\0"):
+            if path.endswith(b"/"):
+                filename, _parents = validate_destination(context, path.rstrip(b"/"))
+                pending_dirs.append(filename)
+        directory_set = set()
+        while pending_dirs:
+            directory = pending_dirs.pop()
+            if directory in directory_set or os.path.normcase(directory) in ignored_dir_set:
+                continue
+            _directory_signature((directory,))
+            directory_set.add(directory)
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    if entry.name.casefold() != ".git" and entry.is_dir(follow_symlinks=False):
+                        pending_dirs.append(entry.path)
+        return root_signature + _directory_signature(tuple(sorted(directory_set)))
+
+    return (yield FileTask(capture))
+
+
+@dataclass(frozen=True)
+class StashOption:
+    """Keep creation options separate from the literal user message."""
+
+    include_untracked: bool = STASH_DEFAULT_BY_KEY[STASH_INCLUDE_UNTRACKED_KEY]
+    keep_index: bool = STASH_DEFAULT_BY_KEY[STASH_KEEP_INDEX_KEY]
+
+
+@dataclass(frozen=True)
+class StashIntent:
+    """Bind one submission to the exact worktree read presented by its form."""
+
+    operation: OperationIntent
+    snapshot: WorktreeSnapshot
+    message: str = ""
+    option: StashOption = StashOption()
+
+    @classmethod
+    def capture(cls, snapshot: WorktreeSnapshot, message: str = "", option: StashOption | None = None, *, session_id: str | None = None) -> StashIntent:
+        """Assign a fresh submission identity without changing its captured repository."""
+        from gitpane.operation.repository_operation import OperationAction, OperationIntent, WriteScope
+
+        operation = OperationIntent.capture(uuid.uuid4().hex, snapshot.context, snapshot.git_filename, generation=snapshot.generation,
+                                            session_id=session_id, operation="Create stash", action=OperationAction.STASH,
+                                            scope=WriteScope.capture(snapshot.context, (STASH_REFERENCE,)))
+        return cls(operation, snapshot, message, option if option is not None else StashOption())
+
+
+@dataclass(frozen=True)
+class StashObservation:
+    """Preserve reflog entries even when two consecutive stashes share an object ID."""
+
+    oid: str | None
+    entries: tuple[bytes, ...]
+    unmerged_paths: tuple[bytes, ...] | None = field(default=None, compare=False)
+    retained_oid: str | None = field(default=None, compare=False)
+    retained: bool | None = field(default=None, compare=False)
+    observed_at: datetime | None = field(default=None, compare=False)
+
+    def retention_of(self, previous: StashObservation) -> StashObservation:
+        """Attach a dated observation of the original stash object without claiming future retention."""
+        retained = previous.oid is not None and previous.oid.encode("ascii") in self.entries
+        return replace(self, retained_oid=previous.oid, retained=retained, observed_at=datetime.now(UTC))
+
+    def added_after(self, previous: StashObservation) -> bool:
+        """Recognize a single prepended entry while retaining the older reflog exactly."""
+        first_entry_index, preceding_entries_index = 0, 1
+        return (self.oid is not None and len(self.entries) == len(previous.entries) + 1
+                and self.entries[preceding_entries_index:] == previous.entries and self.entries[first_entry_index].decode("ascii") == self.oid)
+
+
+@dataclass(frozen=True)
+class StashDropIntent:
+    """One request to drop one exact stash, named by the stash commit GitPane read for it.
+
+    Git drops a stash by its position only (``stash@{N}``), and every position moves when another stash is created
+    or dropped. The stash commit is what names the stash: the drop reads the list again and refuses when that commit
+    is no longer where it was read. ``index`` None means the position is unknown and the commit is looked for in the
+    whole list, as for the stash a Stash pop kept; it must then appear exactly once. ``require_resolved`` refuses the
+    drop while the index still holds an unresolved conflict.
+    """
+
+    operation: OperationIntent
+    oid: str
+    index: int | None = None
+    require_resolved: bool = False
+
+    @classmethod
+    def of_entry(cls, operation: OperationIntent, entry: StashEntry) -> StashDropIntent:
+        """Drop the stash the user chose in the left panel: it must still be at the position the list showed."""
+        return cls(_stash_write_operation(operation, DROP_OPERATION_LABEL), entry.oid, entry.index)
+
+    @classmethod
+    def of_retained(cls, operation: OperationIntent, oid: str) -> StashDropIntent:
+        """Drop the stash a Stash pop kept, wherever it now stands in the list, and only once no conflict remains."""
+        return cls(_stash_write_operation(operation, DROP_OPERATION_LABEL), oid, None, require_resolved=True)
+
+
+def _stash_write_operation(operation: OperationIntent, label: str) -> OperationIntent:
+    """Give a captured write the stash authority and the stash reference as its only written reference."""
+    from gitpane.operation.repository_operation import OperationAction, WriteScope
+
+    return replace(operation, operation=label, action=OperationAction.STASH, scope=WriteScope.capture(operation.context, (STASH_REFERENCE,)))
+
+
+def locate_stash(stash_list: StashList, intent: StashDropIntent) -> int:
+    """Answer the position of the stash a drop names, or refuse when it moved, vanished or cannot be told apart."""
+    if stash_list.cause:
+        raise ValueError(stash_list.cause)
+    positions = []
+    for entry in stash_list.entries:
+        if entry.oid == intent.oid:
+            positions.append(entry.index)
+    if intent.index is not None:
+        if intent.index not in positions:
+            raise ValueError(DROP_CHANGED_CAUSE)
+        return intent.index
+    if not positions:
+        raise ValueError(DROP_CHANGED_CAUSE)
+    if len(positions) > 1:
+        raise ValueError(DROP_AMBIGUOUS_CAUSE)
+    only_position_index = 0
+    return positions[only_position_index]
+
+
+def stash_oids(stash_list: StashList | None) -> tuple[str, ...]:
+    """List the stash commits of a read list, newest first, to compare two reads without their dates or messages."""
+    if stash_list is None:
+        return ()
+    oids = []
+    for entry in stash_list.entries:
+        oids.append(entry.oid)
+    return tuple(oids)
+
+
+def pop_stopped_on_conflict(outcome: OperationOutcome) -> bool:
+    """Tell whether a Stash pop stopped on merge conflicts, an expected pause that waits for the user rather than a failure.
+
+    Git applied what it could, left the conflicting files unmerged, kept the stash and ended with its conflict exit
+    status. Any other ending (a refusal, an error, a result that could not be read) stays a failure.
+    """
+    from gitpane.history.repository_value import GIT_CONFLICT_RETURN_CODE
+
+    if outcome.status != OperationStatus.PARTIAL:
+        return False
+    for step in outcome.steps:
+        if isinstance(step.after, StashObservation) and step.after.unmerged_paths and step.return_code == GIT_CONFLICT_RETURN_CODE:
+            return True
+    return False
+
+
+class StashService:
+    """Run native stash writes under the shared repository owner and always reread."""
+
+    def __init__(self, worktree_service: WorktreeService, repository_operation: RepositoryOperationService) -> None:
+        """Inject existing process execution and common repository reservations."""
+        self.worktree_service = worktree_service
+        self.repository_operation = repository_operation
+        self.outcome_by_id: dict[str, OperationOutcome] = {}
+        self.cancelled_id_set: set[str] = set()
+
+    def pop(self, operation: OperationIntent, *, is_current: Callable[[], bool] | None = None) -> str:
+        """Apply the latest stash once after acquiring the common repository reservation."""
+        from gitpane.operation.repository_operation import OperationAction, WriteScope
+
+        operation = replace(operation, action=OperationAction.STASH, scope=WriteScope.capture(operation.context, (STASH_REFERENCE,)))
+        return self.repository_operation.submit(operation, self._pop(operation, is_current))
+
+    def cancel_pop(self, operation_id: str) -> None:
+        """Stop current native work while allowing final observation to complete.
+
+        The Stash pop console no longer offers Abort (a pop is a local write that must finish), so the application
+        does not call this any more. It stays as the service-level way to stop a queued or running pop: the stash tests
+        use it to check that a stopped pop still rereads and reports the retained stash instead of losing it.
+        """
+        if operation_id in self.outcome_by_id:
+            return
+        self.cancelled_id_set.add(operation_id)
+        runner = self.worktree_service.runner
+        for active in tuple(runner.active_by_id.values()):
+            if active.request.operation_id == operation_id:
+                runner.cancel(active.request.request_id)
+        for request in tuple(runner.pending_requests):
+            if request.operation_id == operation_id:
+                runner.cancel(request.request_id)
+
+    def _require_authority(self, operation: OperationIntent, is_current: Callable[[], bool] | None, changed_cause: str) -> None:
+        """Refuse a write whose live authority is gone, reading nothing from disk beyond what the application policy checks.
+
+        The service must be open and still hold this very intention, with management capability; the application must
+        still allow it and consider it current, and a pop must not have been cancelled.
+        """
+        from gitpane.history.file_history import WindowCapability
+
+        owner = self.repository_operation
+        allows = owner.allows
+        if (owner.closed or owner.active_by_id.get(operation.operation_id) is not operation or operation.capability != WindowCapability.MANAGE
+                or operation.operation_id in self.cancelled_id_set or allows is not None and not allows(operation)
+                or is_current is not None and not is_current()):
+            raise ValueError(changed_cause)
+
+    def _related_git_dirs(self, operation: OperationIntent) -> tuple[str, ...]:
+        """Freeze, on the Qt thread, the Git directories whose pause state the write policy examines for this shared storage."""
+        git_dirs = [operation.context.git_dir]
+        for context in operation.reserved_contexts:
+            git_dirs.append(context.git_dir)
+        for context in tuple(self.repository_operation.context_by_key.values()):
+            if canonical_path(context.common_git_dir) == operation.common_git_dir:
+                git_dirs.append(context.git_dir)
+        return tuple(dict.fromkeys(git_dirs))
+
+    def _pop(self, operation: OperationIntent, is_current: Callable[[], bool] | None) -> Generator:
+        """Recheck the captured stash at native launch and reread even on a rejected command."""
+        from gitpane.operation.launch_signature import verify_launch_signature
+        from gitpane.operation.repository_operation import OperationOutcome, OperationStepResult
+        from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+
+        def read_failure_diagnostic(error: Exception) -> PreparedDiagnostic:
+            """Describe a failed read of the pop's result, naming the Git process it comes from when there is one.
+
+            A console that already ended that process with its own line then does not repeat the failure. The block
+            written to the log is the same as without the process, which is not part of its text.
+            """
+            return Diagnostic("Read stash result", operation.context.repository_dir, operation.git_filename, [], str(error),
+                              process_id=error.diagnostic.process_id if isinstance(error, GitCommandError) else "").prepare()
+
+        before = after = snapshot = refreshed = diagnostic = process_status = return_code = None
+        native_started = False
+        status, effect = OperationStatus.REFUSED, "not observed"
+        try:
+            if operation.context.is_bare:
+                raise ValueError("This bare repository has no working tree for Stash pop")
+            before = yield from self.observe(operation.context)
+            # A pop is asked without a worktree read, so this complete capture is what its result is compared with.
+            snapshot = yield from self.worktree_service.capture(operation.context, operation.git_filename, operation.generation)
+            if before.oid is None:
+                raise ValueError("No stash to apply. Create a stash before using Stash pop.")
+            paths = _write_paths(snapshot)
+            git_dirs = self._related_git_dirs(operation)
+            baseline = yield FileTask(lambda: capture_stash_launch_baseline(operation.context, snapshot.index_filename, snapshot.index_content, paths, (), git_dirs,
+                                                                            POP_CHANGED_CAUSE))
+            self._require_authority(operation, is_current, POP_CHANGED_CAUSE)
+            self.repository_operation.validate(operation)
+            if (yield from self.observe(operation.context)) != before:
+                raise ValueError("Stash changed before launch; refresh the repository")
+            signature = yield FileTask(lambda: prepare_stash_launch(operation.context, baseline, snapshot.index_filename, snapshot.index_content, paths, (),
+                                                                    POP_CHANGED_CAUSE))
+            self._require_authority(operation, is_current, POP_CHANGED_CAUSE)
+
+            def validate_launch() -> None:
+                """Refuse a changed authority or any metadata change after queue waiting; no content is read here."""
+                nonlocal native_started
+                self._require_authority(operation, is_current, POP_CHANGED_CAUSE)
+                verify_launch_signature(signature, POP_CHANGED_CAUSE)
+                native_started = True
+
+            # Stash invokes Git subcommands internally; no user pathspec is passed to this native command. Submodule
+            # recursion is turned off so the files of every submodule stay as they are, even with submodule.recurse set.
+            yield GitCommand([*SUBMODULE_RECURSION_OFF_ARGUMENTS, "--no-literal-pathspecs", "stash", "pop"], timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                             idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+            process_status, return_code = ProcessStatus.SUCCESS, 0
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Stash pop", operation.context.repository_dir, operation.git_filename, [], str(error)).prepare()
+            process_status = error.process_status if isinstance(error, GitCommandError) else None
+            return_code = error.return_code if isinstance(error, GitCommandError) else None
+            status = OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+        try:
+            after = yield from self.observe(operation.context)
+            if before is not None:
+                after = after.retention_of(before)
+            if process_status == ProcessStatus.SUCCESS:
+                preceding_entries_index = 1
+                removed = before is not None and after.entries == before.entries[preceding_entries_index:]
+                status, effect = (OperationStatus.SUCCESS, "applied") if removed else (OperationStatus.UNKNOWN, "unknown")
+                if not removed:
+                    diagnostic = Diagnostic("Stash pop", operation.context.repository_dir, operation.git_filename, [],
+                                            "Stash history changed unexpectedly; inspect the repository before trying again").prepare()
+        except (ValueError, OSError, GitCommandError) as error:
+            status, effect = OperationStatus.UNKNOWN, "unknown"
+            diagnostic = read_failure_diagnostic(error)
+        try:
+            if not operation.context.is_bare:
+                refreshed = yield from self.worktree_service.capture(operation.context, operation.git_filename, operation.generation)
+                if after is not None:
+                    unmerged_paths = []
+                    for entry in refreshed.entries:
+                        if entry.conflict_stages:
+                            unmerged_paths.append(entry.path)
+                    after = replace(after, unmerged_paths=tuple(sorted(set(unmerged_paths))))
+                if status != OperationStatus.UNKNOWN and native_started:
+                    changed = before != after or (snapshot is not None and (snapshot.head_oid != refreshed.head_oid or snapshot.index_entries != refreshed.index_entries
+                               or snapshot.fingerprint_by_path != refreshed.fingerprint_by_path))
+                    if after is not None and after.unmerged_paths or process_status != ProcessStatus.SUCCESS and changed:
+                        status, effect = OperationStatus.PARTIAL, "partially applied"
+                    elif process_status != ProcessStatus.SUCCESS:
+                        effect = "unchanged"
+                if after is not None and after.unmerged_paths:
+                    names = []
+                    for path in after.unmerged_paths:
+                        names.append(path.decode("utf-8", "replace"))
+                    cause = "Unresolved files:\n" + "\n".join(names)
+                    diagnostic = Diagnostic("Stash pop", operation.context.repository_dir, operation.git_filename, [], cause).prepare()
+                if after is not None and after.retained:
+                    cause = diagnostic.cause + "\n" if diagnostic is not None else ""
+                    cause += "Stash retained: " + after.retained_oid + " (observed " + after.observed_at.isoformat() + ")"
+                    diagnostic = Diagnostic("Stash pop", operation.context.repository_dir, operation.git_filename, [], cause).prepare()
+        except (ValueError, OSError, GitCommandError) as error:
+            status = OperationStatus.UNKNOWN
+            diagnostic = read_failure_diagnostic(error)
+        step = OperationStepResult("Stash pop", status, before, after, process_status, effect, diagnostic, return_code)
+        refresh = OperationStepResult("Read working tree", OperationStatus.SUCCESS if refreshed is not None else OperationStatus.UNKNOWN, before=snapshot, after=refreshed)
+        outcome = OperationOutcome(operation.operation_id, status, (step, refresh), diagnostic)
+        self.outcome_by_id[operation.operation_id] = outcome
+        self.cancelled_id_set.discard(operation.operation_id)
+        return outcome
+
+    def drop(self, intent: StashDropIntent, *, is_current: Callable[[], bool] | None = None) -> str:
+        """Drop one exact stash once, under the common repository reservation, and report what the list shows afterwards."""
+        return self.repository_operation.submit(intent.operation, self._drop(intent, is_current))
+
+    def _drop(self, intent: StashDropIntent, is_current: Callable[[], bool] | None) -> Generator:
+        """Find the stash again by its commit, check nothing moved, run `git stash drop stash@{N}`, then read the list again.
+
+        The stash reflog is read as a file between two identical metadata looks at the stash storage, and the same
+        look is compared again just before Git starts: a stash created or dropped by another program meanwhile makes
+        the drop refuse instead of removing whatever now stands at that position. Only the stash reference and its
+        reflog are written; working files, the index and submodules are never read for writing nor touched.
+        """
+        from gitpane.operation.launch_signature import verify_launch_signature
+        from gitpane.operation.repository_operation import OperationOutcome, OperationStepResult
+        from gitpane.reference.stash_list import read_stash_list, stash_selector
+        from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+
+        operation = intent.operation
+        context = operation.context
+        before = after = diagnostic = process_status = return_code = None
+        native_started = False
+        status, effect = OperationStatus.REFUSED, "not observed"
+        position = None
+        try:
+            if context.is_bare:
+                raise ValueError("This bare repository has no stash to drop")
+            signature = yield FileTask(lambda: capture_stash_signature(context))
+            before = yield FileTask(lambda: read_stash_list(context))
+            position = locate_stash(before, intent)
+            if intent.require_resolved:
+                unmerged = yield GitCommand(["ls-files", "--unmerged", "-z"])
+                if unmerged:
+                    raise ValueError(DROP_CONFLICT_CAUSE)
+            yield FileTask(lambda: verify_launch_signature(signature, DROP_CHANGED_CAUSE))
+            self._require_authority(operation, is_current, DROP_CHANGED_CAUSE)
+            self.repository_operation.validate(operation)
+
+            def validate_launch() -> None:
+                """Refuse a changed authority or any change of the stash storage after queue waiting; no content is read here."""
+                nonlocal native_started
+                self._require_authority(operation, is_current, DROP_CHANGED_CAUSE)
+                verify_launch_signature(signature, DROP_CHANGED_CAUSE)
+                native_started = True
+
+            yield GitCommand(["stash", "drop", stash_selector(position)], timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                             before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+            process_status, return_code = ProcessStatus.SUCCESS, 0
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(DROP_OPERATION_LABEL, context.repository_dir, operation.git_filename, [], str(error)).prepare()
+            process_status = error.process_status if isinstance(error, GitCommandError) else None
+            return_code = error.return_code if isinstance(error, GitCommandError) else None
+            status = OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+        if native_started:
+            try:
+                after = yield FileTask(lambda: read_stash_list(context))
+                expected = list(stash_oids(before))
+                del expected[position]
+                if not after.cause and stash_oids(after) == tuple(expected):
+                    status, effect = OperationStatus.SUCCESS, "dropped"
+                elif process_status == ProcessStatus.SUCCESS or stash_oids(after) != stash_oids(before):
+                    status, effect = OperationStatus.UNKNOWN, "unknown"
+                    diagnostic = Diagnostic(DROP_OPERATION_LABEL, context.repository_dir, operation.git_filename, [],
+                                            "Stash list changed unexpectedly; inspect the repository before trying again").prepare()
+                else:
+                    effect = "unchanged"
+            except (ValueError, OSError) as error:
+                status, effect = OperationStatus.UNKNOWN, "unknown"
+                diagnostic = Diagnostic("Read stash result", context.repository_dir, operation.git_filename, [], str(error)).prepare()
+        step = OperationStepResult(DROP_OPERATION_LABEL, status, before, after, process_status, effect, diagnostic, return_code)
+        outcome = OperationOutcome(operation.operation_id, status, (step,), diagnostic)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def observe(self, context: RepositoryContext) -> Generator:
+        """Read the stash reference and reflog of the context's shared storage, without copying messages or file contents to diagnostics."""
+        from gitpane.operation.launch_signature import verify_launch_signature
+        from gitpane.worktree.command_sequence import FileTask, GitCommand
+
+        # Two identical metadata looks at the stash storage, before and after the Git reads, prove those reads saw one
+        # state; a second rev-parse could not see a reflog entry added with the same object ID, a packing or a new table.
+        signature = yield FileTask(lambda: capture_stash_signature(context))
+        # Exit code 1 with no output means the reference is absent; a timeout or a cancellation stays an error.
+        output = yield GitCommand(["rev-parse", "--verify", "--quiet", STASH_REFERENCE], accepted_codes=(0, 1))
+        oid_output = output.strip()
+        entries: tuple[bytes, ...] = ()
+        if oid_output:
+            # The reference and its reflog are separate facts: a reference can exist without a log, or point elsewhere
+            # than its latest entry, and both are kept as Git reports them.
+            reflog_output = yield GitCommand(["reflog", "show", "--format=%H", STASH_REFERENCE])
+            entries = tuple(reflog_output.splitlines())
+        yield FileTask(lambda: verify_launch_signature(signature, STASH_CHANGED_CAUSE))
+        return StashObservation(oid_output.decode("ascii") or None, entries)
+
+    def create(self, intent: StashIntent, *, is_current: Callable[[], bool] | None = None) -> str:
+        """Submit one native creation once without replaying an uncertain result."""
+        return self.repository_operation.submit(intent.operation, self._create(intent, is_current))
+
+    def _create(self, intent: StashIntent, is_current: Callable[[], bool] | None) -> Generator:
+        """Validate captured state, execute Git, then separate its status from observed effects."""
+        # Preferences import the option definitions; load execution dependencies only when running a stash.
+        from gitpane.operation.launch_signature import verify_launch_signature
+        from gitpane.operation.repository_operation import OperationOutcome, OperationStepResult
+        from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+        from gitpane.worktree.worktree_service import STATUS_ARGUMENTS
+        from gitpane.worktree.worktree_snapshot import parse_status
+
+        operation, snapshot = intent.operation, intent.snapshot
+        before = after = refreshed = diagnostic = process_status = return_code = None
+        native_started = False
+        status, effect = OperationStatus.REFUSED, "not observed"
+        try:
+            if (snapshot.context.is_bare or not snapshot.fresh or snapshot.key != operation.key or snapshot.context != operation.context
+                    or snapshot.generation != operation.generation or snapshot.git_filename != operation.git_filename):
+                raise ValueError("The stash request does not match its captured working tree")
+            if "\0" in intent.message:
+                raise ValueError("The stash message cannot contain a NUL character")
+            if is_current is not None and not is_current():
+                raise ValueError("The stash request is no longer current; reopen the form")
+            before = yield from self.observe(snapshot.context)
+            untracked_directory_signature = ()
+            if intent.option.include_untracked:
+                untracked_directory_signature = yield from _capture_untracked_directory_signature(snapshot.context)
+            untracked_dirs = []
+            for directory, _identity in untracked_directory_signature:
+                untracked_dirs.append(directory)
+            paths = _write_paths(snapshot)
+            git_dirs = self._related_git_dirs(operation)
+            # The exact bytes of every path the native stash reads, clean tracked files included, are taken here and
+            # compared again after the checks below, between metadata looks that must not move: the checks then
+            # describe the state that will be stashed.
+            baseline = yield FileTask(lambda: capture_stash_launch_baseline(snapshot.context, snapshot.index_filename, snapshot.index_content, paths, tuple(untracked_dirs),
+                                                                            git_dirs, CREATE_CHANGED_CAUSE))
+            self._require_authority(operation, is_current, CREATE_CHANGED_CAUSE)
+            self.repository_operation.validate(operation)
+            # verify compares the paths the form read (bytes, index, HEAD, identity, configuration and attributes); only
+            # the paths with a fingerprint are passed, a clean path listed by the index has none to compare with.
+            yield from self.worktree_service.verify(snapshot, tuple(snapshot.fingerprint_by_path))
+            # A fresh status shows what verify cannot: a change to a file that was clean, or a new untracked file.
+            status_output = yield GitCommand(list(STATUS_ARGUMENTS), profile=READ_PROFILE)
+            refuse_new_changes(snapshot, parse_status(status_output))
+            signature = yield FileTask(lambda: prepare_stash_launch(snapshot.context, baseline, snapshot.index_filename, snapshot.index_content, paths,
+                                                                    untracked_directory_signature, CREATE_CHANGED_CAUSE))
+            self._require_authority(operation, is_current, CREATE_CHANGED_CAUSE)
+
+            def validate_launch() -> None:
+                """Refuse a changed authority or any metadata change after queue waiting; no content is read here."""
+                nonlocal native_started
+                self._require_authority(operation, is_current, CREATE_CHANGED_CAUSE)
+                verify_launch_signature(signature, CREATE_CHANGED_CAUSE)
+                native_started = True
+
+            # The shared reader enables literal pathspecs, but stash internally checks out :/ for Keep index.
+            # No user path is supplied here; restore Git's native pathspec handling for its own subcommands.
+            # Submodule recursion is turned off so the files of every submodule stay as they are, even with submodule.recurse set.
+            arguments = [*SUBMODULE_RECURSION_OFF_ARGUMENTS, "--no-literal-pathspecs", "stash", "push"]
+            if intent.option.include_untracked:
+                arguments.append("--include-untracked")
+            if intent.option.keep_index:
+                arguments.append("--keep-index")
+            if intent.message:
+                arguments.extend(["--message", intent.message])
+            yield GitCommand(arguments, timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+            process_status, return_code = ProcessStatus.SUCCESS, 0
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Create stash", operation.context.repository_dir, operation.git_filename, [], str(error)).prepare()
+            process_status = error.process_status if isinstance(error, GitCommandError) else None
+            return_code = error.return_code if isinstance(error, GitCommandError) else None
+            status = OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+        try:
+            after = yield from self.observe(snapshot.context)
+            if native_started and before is not None and after.added_after(before):
+                effect = "created"
+                status = OperationStatus.SUCCESS if process_status == ProcessStatus.SUCCESS else OperationStatus.PARTIAL
+            elif process_status == ProcessStatus.SUCCESS:
+                status = OperationStatus.NO_CHANGE if after == before else OperationStatus.UNKNOWN
+                effect = "unchanged" if after == before else "unknown"
+                cause = "No changes to stash. Change a file, then try again." if status == OperationStatus.NO_CHANGE else "Stash changed unexpectedly; inspect the repository before trying again"
+                diagnostic = Diagnostic("Create stash", operation.context.repository_dir, operation.git_filename, [], cause).prepare()
+        except (ValueError, OSError, GitCommandError) as error:
+            status, effect = OperationStatus.UNKNOWN, "unknown"
+            diagnostic = Diagnostic("Read stash result", operation.context.repository_dir, operation.git_filename, [], str(error)).prepare()
+        try:
+            if not snapshot.context.is_bare:
+                refreshed = yield from self.worktree_service.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+        except (ValueError, OSError, GitCommandError) as error:
+            status = OperationStatus.UNKNOWN
+            diagnostic = Diagnostic("Read stash result", operation.context.repository_dir, operation.git_filename, [], str(error)).prepare()
+        step = OperationStepResult("Create stash", status, before, after, process_status, effect, diagnostic, return_code)
+        refresh = OperationStepResult("Read working tree", OperationStatus.SUCCESS if refreshed is not None else OperationStatus.UNKNOWN, after=refreshed)
+        outcome = OperationOutcome(operation.operation_id, status, (step, refresh), diagnostic)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome