gitpane 1.0.0__py3-none-any.whl

gitpane/transport/clone.py

@@ -0,0 +1,1273 @@
+"""Run native clones whose result survives whatever happens to the opening of the repository."""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import posixpath
+import re
+import stat
+import sys
+import tempfile
+import unicodedata
+import uuid
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+from urllib.parse import unquote, urlsplit
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.account.authentication import PREVIEW_HELPER_COMMANDS, RecursiveTransportContext, endpoint_origin, helper_after_refusal, isolated_http_arguments
+from gitpane.account.credential_manager import CredentialManagerRefusal
+from gitpane.config import (
+    CONTROL_CHARACTER_CATEGORY,
+    CREDENTIAL_READ_RETRY_DELAY_MS,
+    GIT_BRANCH_LIST_TIMEOUT_MS,
+    GIT_CLONE_TIMEOUT_MS,
+    GIT_TRANSPORT_TIMEOUT_MS,
+    LOCAL_PREFIX,
+    WINDOWS_PLATFORM,
+    ProcessPriority,
+    SharedText,
+)
+from gitpane.history.repository_value import RepositoryContext
+from gitpane.operation.console_line import (
+    CLONE_LABEL,
+    DESTINATION_HEADER_LABEL,
+    RETRY_SUBMODULES_LABEL,
+    ConsoleHeader,
+    ConsoleLine,
+    operation_end_text,
+)
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus, operation_status
+from gitpane.operation.operation_trace import OperationTrace, publish_after_trace
+from gitpane.operation.repository_operation import OperationAction, OperationIntent, OperationOutcome, OperationStepResult
+from gitpane.process.git_output_text import git_error_text
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, NETWORK_PROFILE, ProcessRequest, ProcessStatus
+from gitpane.sequencer.replay_state import HEAD_BASENAME
+from gitpane.submodule.checkout_refusal import checkout_refusals, refused_checkout_submodule_paths, refused_submodule_dirs
+from gitpane.submodule.checkout_refusal_notice import checkout_refusal_text
+from gitpane.submodule.submodule_discovery import OperationCredentialHelper, SubmoduleAuthenticationTarget, SubmoduleInitializationError, SubmoduleService, initialization_signature
+from gitpane.submodule.submodule_loss import GIT_ENTRY_BASENAME
+from gitpane.system.path_identity import canonical_path, link_resolved_path
+from gitpane.transport.credential_read_retry import credential_read_retry_due, credential_read_retry_text
+from gitpane.transport.git_refusal import file_transport_refused
+from gitpane.transport.refusal_notice import FILE_TRANSPORT_REFUSED_TEXT
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.account.authentication import AccountSelection, AuthenticationService, CredentialHelper
+    from gitpane.account.credential_manager import CredentialManagerDetection
+    from gitpane.account.ssh import SshService
+    from gitpane.operation.diagnostic import DiagnosticLog, PreparedDiagnostic
+    from gitpane.operation.repository_operation import RepositoryOperationService
+    from gitpane.process.process_runner import ProcessResult, ProcessRunner
+
+
+# Put in front of why the inherited authentication settings of a clone's parent folder could not be read.
+INHERITED_INSPECTION_FAILED_TEXT = "Could not inspect inherited transport configuration. "
+# Said when the parent repository was cloned but some of its submodules were not; the clone form shows it only once,
+# whether it comes from the clone result or from the form itself.
+SUBMODULE_PARTIAL_TEXT = "The repository was cloned, but some submodules could not be initialized. Review the details before continuing."
+# Ending a bare host:path text must have, with no scheme and no user, before the clipboard text is taken as a repository URL.
+GIT_URL_SUFFIX = ".git"
+# What endpoint_kind answers for an address. A URL's kind is its scheme: HTTPS, SSH and file:// are the accepted ones.
+HTTPS_ENDPOINT_KIND = "https"
+SSH_ENDPOINT_KIND = "ssh"
+LOCAL_ENDPOINT_KIND = "local"
+# A file:// URL names a repository on this computer or on a network share. Only its shape is checked: Git says at run
+# time whether the folder exists, and it never takes an account.
+FILE_URL_ENDPOINT_KIND = "file"
+FILE_URL_PREFIX = FILE_URL_ENDPOINT_KIND + "://"
+# Start of the refusal endpoint_kind gives, without and with plain local folders accepted; the reason is added after it.
+ENDPOINT_EXPECTED_TEXT = "Enter an HTTPS, SSH or file:// repository URL"
+LOCAL_ENDPOINT_EXPECTED_TEXT = "Enter an HTTPS, SSH or file:// repository URL or an absolute local folder path"
+URL_ENDPOINT_KIND_SET = frozenset({HTTPS_ENDPOINT_KIND, SSH_ENDPOINT_KIND})
+# Kinds of URL the clone form takes from the clipboard at once, without the disk: every accepted URL. A plain folder path
+# is never taken on its text alone: it is only taken once a background check finds a Git repository there.
+CLIPBOARD_ENDPOINT_KIND_SET = frozenset({HTTPS_ENDPOINT_KIND, SSH_ENDPOINT_KIND, FILE_URL_ENDPOINT_KIND})
+# Folders a bare repository, or a copied .git folder itself, holds beside its HEAD file.
+BARE_OBJECTS_BASENAME = "objects"
+BARE_REFS_BASENAME = "refs"
+# Windows reads a path that starts with two separators, in either direction, as a network share (\\server\share) or a
+# device path (\\?\, \\.\): only a drive path such as C:\repo names a disk of this PC.
+WINDOWS_SEPARATOR_CHARACTERS = "\\/"
+WINDOWS_NETWORK_PREFIX_LENGTH = 2
+# The automounter of macOS (and many Linux setups) mounts /net/<host> from any host named in the path the moment it is
+# looked up, so a path under /net reaches a server that the path itself chooses.
+AUTOMOUNT_HOST_ROOT_BASENAME = "net"
+# Said when a clone, or its submodule retry, is refused because the clone form that asked for it was closed or changed since.
+CLONE_REQUEST_NOT_CURRENT_TEXT = "The clone request is no longer current."
+DESTINATION_REMOVED_TEXT = "Removed the empty destination folder GitPane created: "
+DESTINATION_KEPT_TEXT = "Kept the destination folder: "
+# Written to the clone's console after a bare clone, which is never opened in a repository window.
+BARE_CLONE_DONE_TEXT = "Bare repository cloned to: "
+# Commits fetched per branch when the full history is not asked for: only the tip of each branch.
+SHALLOW_CLONE_DEPTH = 1
+BRANCH_NAME_REFUSED_TEXT = 'Enter a branch name that does not start with "-" and has no control characters.'
+# The branch list of the clone form runs Git in an empty temporary folder named with this prefix, removed afterwards.
+BRANCH_LIST_DIR_PREFIX = "gitpane-branches-"
+BRANCH_LIST_OPERATION = "List remote branches"
+# Branch lists queue apart from the clone itself, so typing a URL never fills the clone's own queue.
+BRANCH_LIST_SESSION_ID = "clone-branch-list"
+BRANCH_LIST_CLOSED_TEXT = "The clone service is closed."
+LS_REMOTE_FIELD_SEPARATOR = "\t"
+
+
+def parse_remote_branches(output: bytes) -> tuple[str, ...]:
+    """Read the branch names of a ``git ls-remote --heads`` answer, sorted by name regardless of case.
+
+    A remote lists its branches under the same namespace as local branches, so the local branch prefix selects them.
+    Tags and any other reference are skipped, a name given twice is kept once, and the order Git printed them in is
+    never relied upon.
+    """
+    branch_name_set: set[str] = set()
+    for line in output.decode("utf-8", "replace").splitlines():
+        _object_name, separator, reference = line.partition(LS_REMOTE_FIELD_SEPARATOR)
+        if not separator or not reference.startswith(LOCAL_PREFIX):
+            continue
+        branch_name = reference.removeprefix(LOCAL_PREFIX)
+        if branch_name:
+            branch_name_set.add(branch_name)
+    return tuple(sorted(branch_name_set, key=lambda branch_name: (branch_name.casefold(), branch_name)))
+
+
+def remove_branch_list_dir(neutral_dir: str) -> None:
+    """Remove the empty folder a branch list ran in; Git writes nothing there, so a folder that is not empty is kept."""
+    if not neutral_dir:
+        return
+    try:
+        os.rmdir(neutral_dir)
+    except OSError:
+        pass
+
+
+@dataclass(frozen=True)
+class BranchList:
+    """Answer one branch list request: the remote branches, or the reason they could not be read (for the --log file only)."""
+
+    request_id: str
+    endpoint: str
+    branches: tuple[str, ...] = ()
+    cause: str = ""
+
+
+@dataclass
+class PendingBranchList:
+    """Keep what one started branch list needs until its Git process has exited."""
+
+    request_id: str
+    endpoint: str
+    neutral_dir: str
+    output: bytearray = field(default_factory=bytearray)
+    # The started request, kept so a list whose secret read failed can be started again unchanged in the same folder.
+    request: ProcessRequest | None = None
+    # How many times this list was started again after a failed secret read, and whether it waits to be started again.
+    credential_read_retry_count: int = 0
+    retry_waiting: bool = False
+
+
+def suggested_name(endpoint: str) -> str:
+    """Suggest the final URL component without altering an explicitly edited name."""
+    path = urlsplit(endpoint).path if "://" in endpoint else endpoint.replace("\\", "/").rsplit(":", 1)[-1]
+    return unquote(path.rstrip("/").rsplit("/", 1)[-1]).removesuffix(".git")
+
+
+def file_url_shape_refusal(endpoint: str) -> str:
+    """Answer why a ``file://`` URL is malformed, or an empty string when its shape is accepted.
+
+    Only the shape is checked, never the folder: Git says at run time whether it exists. The URL must start with exactly
+    ``file://`` (Git reads any other spelling as another transport), carry no user, password or port since a local
+    repository never takes an account, no query or fragment Git would read as part of the path, no backslash, and an
+    absolute path. The host is left to Git, so a Windows network share ``file://server/share`` is accepted.
+    """
+    parsed = urlsplit(endpoint)
+    if not endpoint.startswith(FILE_URL_PREFIX) or "\\" in endpoint:
+        return " starting with file:// and written with forward slashes."
+    if "@" in parsed.netloc or ":" in parsed.netloc or "?" in endpoint or "#" in endpoint:
+        return " without a user, password, port, query or fragment."
+    if not parsed.path.startswith("/") or parsed.path == "/":
+        return ". The file:// URL needs an absolute path."
+    return ""
+
+
+def endpoint_kind(endpoint: str, allow_local: bool = False) -> str:
+    """Accept explicit supported transports without allowing arbitrary Git helper syntax.
+
+    HTTPS, SSH and ``file://`` URLs are accepted; a ``file://`` URL is checked on its shape only, whether or not local folders
+    are accepted, so every screen that reads a URL accepts it the same way. With allow_local an absolute folder path is
+    accepted as a plain local repository; option-looking values, control characters, relative paths and other URL schemes
+    stay refused either way.
+    """
+    expected = LOCAL_ENDPOINT_EXPECTED_TEXT if allow_local else ENDPOINT_EXPECTED_TEXT
+    if not endpoint or endpoint.startswith("-") or any(ord(character) < 32 or ord(character) == 127 for character in endpoint):
+        raise ValueError(expected + " without control characters.")
+    if urlsplit(endpoint).scheme == FILE_URL_ENDPOINT_KIND:
+        refusal = file_url_shape_refusal(endpoint)
+        if refusal:
+            raise ValueError(expected + refusal)
+        return FILE_URL_ENDPOINT_KIND
+    if "\\" in endpoint and not allow_local:
+        raise ValueError(expected + " without control characters.")
+    if allow_local and os.path.isabs(endpoint):
+        return LOCAL_ENDPOINT_KIND
+    if "://" in endpoint:
+        parsed = urlsplit(endpoint)
+        if parsed.scheme not in URL_ENDPOINT_KIND_SET or not parsed.hostname or parsed.password is not None or parsed.query or parsed.fragment:
+            raise ValueError(expected + " without a password, query or fragment.")
+        if not parsed.path or parsed.port == 0:
+            raise ValueError("The repository URL needs a path and a valid port.")
+        return parsed.scheme
+    if re.fullmatch(r"(?:[^\s/@:]+@)?(?:\[[0-9a-fA-F:]+\]|[^\s/:]+):[^:].*", endpoint) and not re.match(r"^[A-Za-z]:", endpoint):
+        return SSH_ENDPOINT_KIND
+    raise ValueError(expected + ".")
+
+
+def clipboard_repository_url(text: str) -> str:
+    """Return the clipboard text when it is clearly the URL of a repository, otherwise an empty string.
+
+    Clipboard text comes from any application, so it is only taken when it is one word with no blank once the blanks
+    around it are dropped, and that word is an HTTPS, SSH or well-formed ``file://`` address without a password, with or
+    without a final ``.git``. Another transport or a URL with a password is never taken. A folder path is not taken
+    here either: ``clipboard_local_repository_candidate`` and ``looks_like_git_repository`` decide it, the second on a
+    background thread. The URL is only written into the form; nothing is started from it.
+    """
+    candidate = text.strip()
+    # A copied repository address never holds a blank, so a text that still has one (space, tab or line break) is
+    # ordinary text, such as "bob@example.com: thanks for the review".
+    if re.search(r"\s", candidate):
+        return ""
+    try:
+        kind = endpoint_kind(candidate)
+    except ValueError:
+        return ""
+    if kind not in CLIPBOARD_ENDPOINT_KIND_SET:
+        return ""
+    # A bare host:path with no scheme and no user also has the shape of short everyday text with no blank, such as a
+    # time ("12:30"), that nobody copied to clone, so on top of having no blank it needs a final .git to be taken.
+    host, _separator, _path = candidate.partition(":")
+    if "://" not in candidate and "@" not in host and not candidate.endswith(GIT_URL_SUFFIX):
+        return ""
+    return candidate
+
+
+def is_network_path(path: str, platform: str) -> bool:
+    """Tell, from the text alone, whether looking up this absolute path would make the system contact another computer.
+
+    On Windows that is any path starting with two separators: a network share, where the system connects and signs in
+    with the user's Windows account to the server the path names, or a device path, which no copied repository path needs.
+    Elsewhere it is a path under /net, which the automounter mounts from the host named right after it. The letter case
+    of /net is ignored, since the macOS disk ignores it too. ``platform`` is a ``sys.platform`` value, so each system's
+    rule can be tested from any other.
+    """
+    if platform == WINDOWS_PLATFORM:
+        prefix = path[:WINDOWS_NETWORK_PREFIX_LENGTH]
+        return len(prefix) == WINDOWS_NETWORK_PREFIX_LENGTH and all(character in WINDOWS_SEPARATOR_CHARACTERS for character in prefix)
+    root_basename = posixpath.normpath(path).lstrip("/").split("/")[0]
+    return root_basename.casefold() == AUTOMOUNT_HOST_ROOT_BASENAME
+
+
+def clipboard_local_repository_candidate(text: str, platform: str = sys.platform) -> str:
+    """Return the clipboard text when it may be the path of a local repository, otherwise an empty string; never reads the disk.
+
+    Clipboard text comes from any application, so only an absolute path on a single line is kept, once the blanks around
+    it are dropped, and only when it holds no control character; blanks inside are allowed, since folder names have
+    them. An absolute path never starts with "-", so it can never be read as an option. A network path is never kept:
+    the form checks the candidate on its own, without the user asking, and looking up such a path would contact (and on
+    Windows sign in to) a server chosen by whoever wrote the copied text. Whether a repository is really there is for
+    ``looks_like_git_repository`` to say, on a background thread. ``platform`` is a ``sys.platform`` value, so each
+    system's rule of absolute and network paths can be tested from any other.
+    """
+    candidate = text.strip()
+    if not candidate or len(candidate.splitlines()) != 1:
+        return ""
+    for character in candidate:
+        if unicodedata.category(character) == CONTROL_CHARACTER_CATEGORY:
+            return ""
+    is_absolute = ntpath.isabs if platform == WINDOWS_PLATFORM else posixpath.isabs
+    if not is_absolute(candidate) or is_network_path(candidate, platform):
+        return ""
+    return candidate
+
+
+def looks_like_git_repository(directory: str) -> bool:
+    """Tell, from the disk alone and without starting Git, whether the folder is a Git repository. May block on a slow disk.
+
+    A folder with a .git entry is a working tree, a submodule or a linked worktree; a folder with a HEAD file and objects
+    and refs folders is a bare repository, or a copied .git folder. A folder inside a repository is none of these, nor is
+    a path that is absent or cannot be read: those all answer False, never an error, so the text is simply not taken.
+    """
+    try:
+        if os.path.lexists(os.path.join(directory, GIT_ENTRY_BASENAME)):
+            return True
+        return (os.path.isfile(os.path.join(directory, HEAD_BASENAME)) and os.path.isdir(os.path.join(directory, BARE_OBJECTS_BASENAME))
+                and os.path.isdir(os.path.join(directory, BARE_REFS_BASENAME)))
+    except (OSError, ValueError):
+        return False
+
+
+def directory_identity(directory: str) -> tuple[int, int]:
+    """Identify a real directory while rejecting links and Windows junctions."""
+    metadata = os.lstat(directory)
+    if not stat.S_ISDIR(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode) or getattr(metadata, "st_reparse_tag", 0):
+        raise ValueError("Choose a real directory, not a link or junction: " + directory)
+    return metadata.st_dev, metadata.st_ino
+
+
+def validate_destination(parent_dir: str, name: str) -> None:
+    """Reject ambiguous portable filenames before creating any destination on disk."""
+    if not parent_dir or not os.path.isabs(parent_dir):
+        raise ValueError("Choose an existing absolute parent directory.")
+    if (not name or name in {".", ".."} or name.endswith((" ", ".")) or any(character in '<>:"/\\|?*' or ord(character) < 32 for character in name)
+            or re.fullmatch(r"(?:CON|PRN|AUX|NUL|COM[1-9¹²³]|LPT[1-9¹²³])(?:\..*)?", name, re.IGNORECASE)):
+        raise ValueError("Enter a repository name without separators, traversal or reserved filename characters.")
+    directory_identity(parent_dir)
+    # Links are found by resolving them without the disk spelling: on macOS a parent typed with another letter case
+    # is the same folder, not a link.
+    if link_resolved_path(parent_dir) != os.path.normcase(os.path.abspath(parent_dir)):
+        raise ValueError("Choose a parent directory without links or junctions.")
+    if os.path.lexists(os.path.join(parent_dir, name)):
+        raise ValueError("Destination already exists. Choose another repository name or parent directory.")
+
+
+def validate_branch_name(branch: str) -> None:
+    """Refuse a branch name Git could read as an option or that hides a control character.
+
+    An empty name means the remote HEAD. A name that does not exist on the server is left to Git, which refuses it
+    with its own message.
+    """
+    if branch.startswith("-") or any(ord(character) < 32 or ord(character) == 127 for character in branch):
+        raise ValueError(BRANCH_NAME_REFUSED_TEXT)
+
+
+@dataclass(frozen=True)
+class CloneOptions:
+    """What the clone form asks Git to do besides copying the repository."""
+
+    # An empty branch clones the branch the server's HEAD points to.
+    branch: str = ""
+    initialize_submodules: bool = True
+    full_history: bool = True
+    bare: bool = False
+
+
+def clone_arguments(options: CloneOptions, endpoint: str, destination_dir: str, *, local: bool = False) -> list[str]:
+    """Build the clone command for the chosen options, in the order Git Extensions uses.
+
+    A short history keeps every remote branch visible (``--no-single-branch``) so the user can still switch to another
+    branch afterwards. Git ignores ``--depth`` when it copies a local folder directly, so a short history of a ``local``
+    folder also asks for ``--no-local``, which makes Git fetch through its normal transport and honour the depth. A bare
+    repository has no working tree, so its submodules are never initialized. The URL and the destination always come
+    after ``--`` and the branch travels as one ``--branch=<name>`` argument, so no option is ever read from user text.
+    """
+    arguments = ["clone"]
+    if options.bare:
+        arguments.append("--bare")
+    if options.initialize_submodules and not options.bare:
+        arguments.append("--recurse-submodules")
+    if not options.full_history:
+        arguments.extend(["--depth", str(SHALLOW_CLONE_DEPTH), "--no-single-branch"])
+        if local:
+            arguments.append("--no-local")
+    arguments.append("--progress")
+    if options.branch:
+        arguments.append("--branch=" + options.branch)
+    arguments.extend(["--", endpoint, destination_dir])
+    return arguments
+
+
+def clone_context(destination_dir: str, bare: bool) -> RepositoryContext:
+    """Describe the repository a clone writes: a bare clone is its own Git folder, any other clone keeps it in ``.git``."""
+    if bare:
+        return RepositoryContext(None, destination_dir, destination_dir, True)
+    git_dir = os.path.join(destination_dir, ".git")
+    return RepositoryContext(destination_dir, git_dir, git_dir, False)
+
+
+def repository_written(destination_dir: str, bare: bool) -> bool:
+    """Tell whether Git already wrote a repository into the clone folder, so a failure keeps it instead of reading it as missing."""
+    if bare:
+        return os.path.isfile(os.path.join(destination_dir, "HEAD"))
+    return os.path.isdir(os.path.join(destination_dir, ".git"))
+
+
+@dataclass(frozen=True)
+class CloneIntent:
+    """Capture a welcome request and the exact destination the user approved."""
+
+    endpoint: str
+    parent_dir: str
+    name: str
+    session_id: str
+    generation: int
+    selection: AccountSelection | None = None
+    options: CloneOptions = field(default_factory=CloneOptions)
+
+
+@dataclass(frozen=True)
+class OwnedDestination:
+    """Remember the exclusively created directory and its original resolved parent."""
+
+    destination_dir: str
+    parent_dir: str
+    resolved_parent_dir: str
+    identity: tuple[int, int]
+    parent_identity: tuple[int, int]
+
+    @classmethod
+    def create(cls, parent_dir: str, name: str) -> OwnedDestination:
+        """Claim an absent destination without adopting any pre-existing directory."""
+        validate_destination(parent_dir, name)
+        parent_dir = os.path.abspath(parent_dir)
+        parent_identity = directory_identity(parent_dir)
+        resolved_parent_dir = canonical_path(parent_dir)
+        destination_dir = os.path.join(parent_dir, name)
+        os.mkdir(destination_dir)
+        return cls(destination_dir, parent_dir, resolved_parent_dir, directory_identity(destination_dir), parent_identity)
+
+    def verify(self) -> None:
+        """Refuse another path identity before any later command or opening."""
+        if (directory_identity(self.parent_dir) != self.parent_identity or canonical_path(self.parent_dir) != self.resolved_parent_dir
+                or directory_identity(self.destination_dir) != self.identity):
+            raise ValueError("The clone destination or its parent changed. Inspect the directory: " + self.destination_dir)
+
+    def remove_if_empty(self) -> bool:
+        """Remove the folder this clone created when it is still that same folder and holds nothing; return whether it was removed.
+
+        A clone that failed or was cancelled before Git wrote anything would otherwise leave an empty folder behind, and
+        the same name would then be refused as an existing destination. The folder and its parent must still be the
+        ones recorded at creation, so a replaced folder, a link or a junction is never removed. Only ``os.rmdir`` is
+        used: it refuses a folder that is not empty by itself, so a file that appears between the emptiness check and
+        the removal is kept. Nothing is ever removed recursively, and any doubt keeps the folder.
+        """
+        try:
+            self.verify()
+            with os.scandir(self.destination_dir) as entries:
+                if next(entries, None) is not None:
+                    return False
+            os.rmdir(self.destination_dir)
+        except (OSError, ValueError):
+            return False
+        return True
+
+
+def kept_destination_reason(destination: OwnedDestination) -> str:
+    """Say in plain words why a clone's own folder was kept after a failure, for the clone console."""
+    try:
+        destination.verify()
+        with os.scandir(destination.destination_dir) as entries:
+            if next(entries, None) is not None:
+                return "it is not empty"
+    except ValueError:
+        return "it changed since GitPane created it"
+    except OSError as error:
+        return "it could not be read: " + (error.strerror or str(error))
+    return "it could not be removed"
+
+
+@dataclass
+class CloneRun:
+    """Keep the process result separate from the subsequent window publication."""
+
+    operation_id: str
+    intent: CloneIntent
+    trace: OperationTrace
+    destination: OwnedDestination | None = None
+    clone_status: str = "not_started"
+    open_status: str = "not_started"
+    diagnostic: PreparedDiagnostic | None = None
+    cancelled: bool = False
+    validation_status: str = "not_started"
+    selection_saved: bool = False
+    origin_restored: bool = False
+    incomplete_repository: bool = False
+    recursive_status: str = "not_started"
+    retry_operation_id: str = ""
+    authentication_target: SubmoduleAuthenticationTarget | None = None
+    child_selection: AccountSelection | None = None
+    # The account resolved for an HTTPS clone (None without one), kept so a failure can name it; never a secret.
+    selection: AccountSelection | None = None
+    # True once the empty folder this clone created was removed after a failure or a cancellation.
+    destination_removed: bool = False
+    # Why the credential manager was refused when that refusal stopped this clone or its last Retry submodules, so the
+    # window explaining how to install it can open; None otherwise.
+    credential_manager_refusal: CredentialManagerDetection | None = None
+    # The sentence that explains a submodule whose checkout Git refused, set when the clone ends and emptied when a failed
+    # Retry submodules brings its own cause; empty otherwise. The clone form then shows it first instead of the generic
+    # partial-clone sentence.
+    checkout_refusal_text: str = ""
+    # The folders of the submodules whose checkout Git refused, during the clone or a later Retry submodules: the
+    # submodules Git cloned after them without checking them out are checked out, these are left as Git left them.
+    refused_submodule_dir_set: set[str] = field(default_factory=set)
+    # The step that checks out those submodules right after a clone Git stopped on a refused checkout: NOT_STARTED until
+    # it begins, PENDING while it runs, then the status it ended with.
+    cloned_checkout_status: OperationStatus = OperationStatus.NOT_STARTED
+    # The clone's own request with its launch checks, before the SSH prompt owner is attached, so the clone can be started
+    # again unchanged after a failed secret read; None until it is first started.
+    native_request: ProcessRequest | None = None
+    # How many times the clone was started again after a failed secret read, and the failed result it waits on meanwhile.
+    credential_read_retry_count: int = 0
+    retry_result: ProcessResult | None = None
+
+    def has_running_step(self) -> bool:
+        """Tell whether a step of the clone still runs: the clone, its submodules, its validation or the checkout of the submodules cloned without files."""
+        return self.cloned_checkout_status == OperationStatus.PENDING or "running" in (self.clone_status, self.recursive_status, self.validation_status)
+
+
+class CloneService(QObject):
+    """Reserve native clone work until actual exit and preserve completed directories."""
+
+    finished = Signal(object)
+
+    def __init__(self, runner: ProcessRunner, repository_operation: RepositoryOperationService, authentication: AuthenticationService,
+                 ssh: SshService, parent: QObject | None = None, *, is_current: Callable[[CloneIntent], bool], log: DiagnosticLog | None = None) -> None:
+        """Inject process, authentication and authority owners without tying them to a dialog."""
+        super().__init__(parent)
+        self.runner = runner
+        self.repository_operation = repository_operation
+        self.authentication = authentication
+        self.ssh = ssh
+        self.is_current = is_current
+        self.log = log
+        # The clone form accepts a local folder, typed or chosen with Browse; a test can still turn this off to check the refusal.
+        self.allow_local_endpoint = True
+        self.closed = False
+        self.run_by_id: dict[str, CloneRun] = {}
+        # Branch lists whose Git process has not exited yet, and the callbacks still waiting for a branch list result.
+        self.branch_list_by_id: dict[str, PendingBranchList] = {}
+        self.branch_complete_by_id: dict[str, Callable[[BranchList], None]] = {}
+        self.submodule = SubmoduleService(repository_operation.worktree_service, repository_operation, authentication, ssh, log)
+        runner.stdout_chunk.connect(self._branch_list_output)
+        runner.finished.connect(self._finished)
+
+    def submit(self, intent: CloneIntent, git_filename: str) -> CloneRun:
+        """Start one captured clone or retain a safe explicit refusal for its form.
+
+        A refused reservation of the destination takes the repository owner's reason, which names another operation only
+        when a write really holds the destination folder.
+        """
+        for previous in self.run_by_id.values():
+            if previous.intent.session_id == intent.session_id and previous.clone_status == "running":
+                return previous
+        operation_id = uuid.uuid4().hex
+        # The destination does not exist yet, so the console names it rather than a repository; it is known before any check.
+        header = ConsoleHeader(DESTINATION_HEADER_LABEL, os.path.join(intent.parent_dir, intent.name))
+        run = CloneRun(operation_id, intent, OperationTrace(operation_id, self.runner, self.log, header=header))
+        self.run_by_id[operation_id] = run
+        try:
+            if self.closed or not self.is_current(intent):
+                raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+            kind = endpoint_kind(intent.endpoint, self.allow_local_endpoint)
+            validate_destination(intent.parent_dir, intent.name)
+            validate_branch_name(intent.options.branch)
+            endpoint, arguments, environment_by_name = intent.endpoint, [], {}
+            destinations = self.authentication.recursive_context()
+            if kind == HTTPS_ENDPOINT_KIND:
+                selection = intent.selection or self.authentication.account_for_endpoint(endpoint)
+                run.selection = selection
+                destinations = self.authentication.recursive_context(endpoint, selection)
+                if selection is not None:
+                    endpoint, _selected_arguments = self.authentication.command_configuration(endpoint, selection=selection, helper_commands=PREVIEW_HELPER_COMMANDS)
+            if kind == SSH_ENDPOINT_KIND or self.ssh.configuration().ssh_filename:
+                arguments, environment_by_name = self.ssh.command_configuration()
+            destination_dir = os.path.join(intent.parent_dir, intent.name)
+            context = clone_context(destination_dir, intent.options.bare)
+            owner = OperationIntent.capture(operation_id, context, git_filename, operation="Clone repository", generation=intent.generation,
+                                            reserved_repository_dirs=(canonical_path(destination_dir),), action=OperationAction.SUBMODULE_INIT)
+            if not self.repository_operation.reserve(owner):
+                raise ValueError(self.repository_operation.refusal_cause(owner))
+            run.destination = OwnedDestination.create(intent.parent_dir, intent.name)
+            destination = run.destination
+            destination.verify()
+            def before_start() -> None:
+                """Recheck the final destination after any queue delay and before native launch."""
+                self.repository_operation.validate(owner)
+                destination.verify()
+                if run.cancelled or not self.is_current(intent):
+                    raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+                self.authentication.recursive_configuration(destinations, helper_commands=PREVIEW_HELPER_COMMANDS)
+
+            # No protocol.file.allow is added: whatever URL the parent came from, Git's own setting decides whether a
+            # submodule whose URL is a local folder or a file:// URL may be cloned, and a refusal is explained at the end.
+            request = ProcessRequest(operation_id, git_filename, [*arguments,
+                                                                  *clone_arguments(intent.options, endpoint, destination.destination_dir, local=kind == LOCAL_ENDPOINT_KIND)],
+                                     destination.parent_dir,
+                                     GIT_CLONE_TIMEOUT_MS, session_id="clone:" + intent.session_id, idle_timeout_ms=GIT_TRANSPORT_TIMEOUT_MS,
+                                     environment_by_name=environment_by_name, operation="Clone repository", profile=NETWORK_PROFILE, operation_id=operation_id, before_start=before_start)
+            run.clone_status = "running"
+            run.recursive_status = "running"
+
+            def prepare_transport() -> Generator:
+                """Find the credential manager once for the whole recursive clone, then inspect inherited authentication.
+
+                Runs in the background: the search may start short processes. Every submodule's Git then starts the same
+                helper, by the same absolute path. Without any account to compose, nothing is searched; a refusal stops
+                only a clone whose own URL uses an account (see helper_after_refusal).
+                """
+                helper_commands = PREVIEW_HELPER_COMMANDS
+                if any(recursive_destination.selection is not None for recursive_destination in destinations):
+                    try:
+                        helper = yield FileTask(lambda: self.authentication.credential_helper(git_filename))
+                        helper_commands = helper.commands
+                    except ValueError as refusal:
+                        helper_commands = helper_after_refusal(refusal, operation_uses_account=run.selection is not None, log=self.log)
+                try:
+                    configuration = yield from self.authentication.recursive_inherited_keys((destination.parent_dir,))
+                except (OSError, ValueError, RuntimeError) as failure:
+                    raise ValueError(INHERITED_INSPECTION_FAILED_TEXT + str(failure)) from failure
+                return helper_commands, configuration
+
+            def prepared(value: object, error: Exception | None) -> None:
+                """Launch only after the credential manager was found and inherited authentication names were read safely.
+
+                A refused credential manager reaches here as its own sentence, which becomes the cause of the clone's red line.
+                """
+                try:
+                    if error is not None:
+                        if isinstance(error, CredentialManagerRefusal) and not run.cancelled:
+                            run.credential_manager_refusal = error.detection
+                        raise ValueError(str(error))
+                    helper_commands, configuration = value
+                    before_start()
+                    recursive_arguments = self.authentication.recursive_configuration(destinations, configuration, helper_commands=helper_commands)
+
+                    def verified_start() -> None:
+                        """Bind queued launch to the inspected conditional authentication files and to the helper found for this clone."""
+                        before_start()
+                        self.authentication.recursive_configuration(destinations, configuration, helper_commands=helper_commands)
+
+                    native_request = replace(request, arguments=[*recursive_arguments, *request.arguments], before_start=verified_start)
+                    run.native_request = native_request
+                    native_request = self.ssh.prompt(native_request, is_current=lambda: not run.cancelled and self.is_current(intent))
+                    self.runner.start(native_request)
+                except (OSError, ValueError, RuntimeError) as failure:
+                    run.clone_status = run.recursive_status = OperationStatus.CANCELLED.value if run.cancelled else OperationStatus.FAILED.value
+                    run.diagnostic = Diagnostic("Clone repository", destination.destination_dir, git_filename, [], str(failure)).prepare()
+                    # Git's clone never ran: the console says it did not start, or that the user cancelled it.
+                    run.trace.append_diagnostic(operation_id, "error", run.diagnostic, OperationStatus.CANCELLED if run.cancelled else OperationStatus.REFUSED)
+                    self._release_empty_destination(run)
+                    self._complete(run, (OperationStepResult("Prepare recursive transport", OperationStatus(run.recursive_status), diagnostic=run.diagnostic),))
+
+            self.repository_operation.worktree_service.run(context, git_filename, prepare_transport(), prepared, operation_id=operation_id)
+        except (OSError, ValueError, RuntimeError) as error:
+            run.diagnostic = Diagnostic("Clone repository", intent.parent_dir, git_filename, [], str(error)).prepare()
+            run.clone_status = run.recursive_status = OperationStatus.CANCELLED.value if run.cancelled else OperationStatus.FAILED.value
+            # A refusal before launch is its single red line: no end line repeats it, since nothing was attempted.
+            run.trace.append_diagnostic(operation_id, "error", run.diagnostic, OperationStatus.CANCELLED if run.cancelled else OperationStatus.REFUSED)
+            self._release_empty_destination(run)
+            self.repository_operation.release(operation_id)
+            QTimer.singleShot(0, self, lambda: self.finished.emit(run))
+        return run
+
+    def accepts_endpoint(self, endpoint: str) -> bool:
+        """Tell whether a clone would accept this repository address, so an unfinished URL starts no branch list."""
+        try:
+            endpoint_kind(endpoint, self.allow_local_endpoint)
+        except ValueError:
+            return False
+        return True
+
+    def list_remote_branches(self, endpoint: str, git_filename: str, selection: AccountSelection | None, complete: Callable[[BranchList], None]) -> str:
+        """Read a remote repository's branches in the background with the account a clone would use, and return the request's id.
+
+        The list is read while the user types, so it must never ask anything: inherited credential helpers are cleared,
+        the credential helper may not prompt, no askpass program is given and Git runs from an empty temporary folder
+        where it may not look for a repository above, so no repository's settings apply. With an account, the
+        credential manager is first found away from the window's thread; its refusal is the list's failure. Without
+        one, nothing is searched. ``complete`` is called once, later, unless ``cancel_branch_list`` forgot the request first.
+        """
+        request_id = uuid.uuid4().hex
+        self.branch_complete_by_id[request_id] = complete
+        try:
+            if self.closed:
+                raise ValueError(BRANCH_LIST_CLOSED_TEXT)
+            selection = self._branch_list_selection(endpoint, selection)
+        except (OSError, ValueError, RuntimeError) as error:
+            self._publish_branch_list_later(BranchList(request_id, endpoint, cause=self._branch_list_cause(git_filename, [], str(error))))
+            return request_id
+        if selection is None:
+            self._start_branch_list(request_id, endpoint, git_filename, None, PREVIEW_HELPER_COMMANDS)
+            return request_id
+
+        def helper_found(helper: CredentialHelper | None, error: Exception | None) -> None:
+            """Read the branches with the credential manager found, unless the request was cancelled or the service closed meanwhile."""
+            if self.closed or request_id not in self.branch_complete_by_id:
+                return
+            if error is not None:
+                self._publish_branch_list_later(BranchList(request_id, endpoint, cause=self._branch_list_cause(git_filename, [], str(error))))
+                return
+            self._start_branch_list(request_id, endpoint, git_filename, selection, helper.commands)
+
+        self.authentication.resolve_credential_helper(git_filename, helper_found)
+        return request_id
+
+    def _branch_list_selection(self, endpoint: str, selection: AccountSelection | None) -> AccountSelection | None:
+        """Return the account a branch list of this address reads with: the chosen one, else the address's default, never one for a non-HTTPS address."""
+        if endpoint_kind(endpoint, self.allow_local_endpoint) != HTTPS_ENDPOINT_KIND:
+            return None
+        return selection or self.authentication.account_for_endpoint(endpoint)
+
+    def _start_branch_list(self, request_id: str, endpoint: str, git_filename: str, selection: AccountSelection | None, helper_commands: tuple[str, ...]) -> None:
+        """Start ``git ls-remote`` in an empty temporary folder, or publish why it could not start."""
+        neutral_dir = ""
+        arguments: list[str] = []
+        try:
+            arguments, environment_by_name = self._branch_list_command(endpoint, selection, helper_commands)
+            neutral_dir = tempfile.mkdtemp(prefix=BRANCH_LIST_DIR_PREFIX)
+            environment_by_name["GIT_CEILING_DIRECTORIES"] = os.path.dirname(neutral_dir)
+            request = ProcessRequest(request_id, git_filename, arguments, neutral_dir, GIT_BRANCH_LIST_TIMEOUT_MS, session_id=BRANCH_LIST_SESSION_ID,
+                                     idle_timeout_ms=GIT_BRANCH_LIST_TIMEOUT_MS, environment_by_name=environment_by_name, operation=BRANCH_LIST_OPERATION,
+                                     profile=NETWORK_PROFILE, operation_id=request_id, priority=ProcessPriority.BACKGROUND)
+            self.branch_list_by_id[request_id] = PendingBranchList(request_id, endpoint, neutral_dir, request=request)
+            self.runner.start(request)
+        except (OSError, ValueError, RuntimeError) as error:
+            self.branch_list_by_id.pop(request_id, None)
+            remove_branch_list_dir(neutral_dir)
+            cause = self._branch_list_cause(git_filename, arguments, str(error))
+            self._publish_branch_list_later(BranchList(request_id, endpoint, cause=cause))
+
+    def cancel_branch_list(self, request_id: str) -> None:
+        """Forget a branch list's callback and stop its Git process, whether it still waits in the queue, already runs or waits to be started again."""
+        self.branch_complete_by_id.pop(request_id, None)
+        pending = self.branch_list_by_id.get(request_id)
+        if pending is not None and pending.retry_waiting:
+            del self.branch_list_by_id[request_id]
+            remove_branch_list_dir(pending.neutral_dir)
+            return
+        if pending is not None:
+            self.runner.cancel(request_id)
+
+    def _branch_list_command(self, endpoint: str, selection: AccountSelection | None, helper_commands: tuple[str, ...]) -> tuple[list[str], dict[str, str]]:
+        """Build the ``git ls-remote --heads`` command and its environment with the same account and SSH client a clone of this address would use.
+
+        ``selection`` is the account already chosen for this address, if any, and ``helper_commands`` the credential
+        manager already found for it; nothing is searched here.
+        """
+        kind = endpoint_kind(endpoint, self.allow_local_endpoint)
+        arguments = self.authentication.recursive_configuration((), helper_commands=PREVIEW_HELPER_COMMANDS)
+        arguments.extend(["-c", "core.askPass="])
+        environment_by_name: dict[str, str] = {}
+        command_url = endpoint
+        if kind == HTTPS_ENDPOINT_KIND and selection is not None:
+            command_url, account_arguments = self.authentication.command_configuration(endpoint, selection=selection, helper_commands=helper_commands)
+            arguments.extend(account_arguments)
+            arguments.extend(isolated_http_arguments(command_url))
+        # Batch mode and no question helper: an unknown host key or a passphrase makes the list fail instead of asking.
+        # Without any SSH client the configuration is refused here and Git is never started.
+        if kind == SSH_ENDPOINT_KIND or self.ssh.configuration().ssh_filename:
+            ssh_arguments, ssh_environment_by_name = self.ssh.command_configuration(batch_mode=True)
+            arguments.extend(ssh_arguments)
+            environment_by_name.update(ssh_environment_by_name)
+        # "--heads" rather than "--branches": older Git versions only know the first. Never its one-letter form, which asks Git for help.
+        arguments.extend(["ls-remote", "--heads", "--", command_url])
+        return arguments, environment_by_name
+
+    def _branch_list_cause(self, git_filename: str, arguments: list[str], cause: str, stderr: bytes = b"", return_code: int | None = None) -> str:
+        """Prepare why a branch list failed without any secret, and write it to the --log file; the form only says the branches could not be read."""
+        diagnostic = Diagnostic(BRANCH_LIST_OPERATION, "", git_filename, arguments, cause, stderr, return_code).prepare()
+        if self.log is not None:
+            self.log.write(diagnostic)
+        return diagnostic.cause
+
+    def _branch_list_output(self, request: ProcessRequest, data: bytes) -> None:
+        """Collect the standard output of branch lists only; every other command's output is left to its own owner."""
+        pending = self.branch_list_by_id.get(request.request_id)
+        if pending is not None:
+            pending.output.extend(data)
+
+    def _branch_list_finished(self, pending: PendingBranchList, result: ProcessResult) -> None:
+        """Remove the branch list's empty folder once Git has exited, then publish the branches or the failure.
+
+        A list whose secret read failed is started again a moment later in the same folder instead, while it is still
+        wanted; the failed attempt is written to the --log file with the retry line as its cause.
+        """
+        if (not self.closed and pending.request is not None and pending.request_id in self.branch_complete_by_id
+                and credential_read_retry_due(result, pending.credential_read_retry_count)):
+            pending.credential_read_retry_count += 1
+            pending.retry_waiting = True
+            pending.output.clear()
+            self.branch_list_by_id[pending.request_id] = pending
+            request = result.request
+            self._branch_list_cause(request.program_filename, request.arguments, credential_read_retry_text(pending.credential_read_retry_count), result.stderr, result.return_code)
+            QTimer.singleShot(CREDENTIAL_READ_RETRY_DELAY_MS, self, lambda: self._list_branches_again(pending))
+            return
+        remove_branch_list_dir(pending.neutral_dir)
+        if result.status == ProcessStatus.SUCCESS:
+            branch_list = BranchList(pending.request_id, pending.endpoint, parse_remote_branches(bytes(pending.output)))
+        else:
+            request = result.request
+            cause = self._branch_list_cause(request.program_filename, request.arguments, result.cause or result.status.value, result.stderr, result.return_code)
+            branch_list = BranchList(pending.request_id, pending.endpoint, cause=cause or result.status.value)
+        self._publish_branch_list_later(branch_list)
+
+    def _list_branches_again(self, pending: PendingBranchList) -> None:
+        """Start a branch list again once its pause is over, unless it was cancelled or the service closed meanwhile."""
+        if self.branch_list_by_id.get(pending.request_id) is not pending or not pending.retry_waiting:
+            return
+        pending.retry_waiting = False
+        if self.closed or pending.request_id not in self.branch_complete_by_id:
+            del self.branch_list_by_id[pending.request_id]
+            remove_branch_list_dir(pending.neutral_dir)
+            return
+        try:
+            self.runner.start(pending.request)
+        except (OSError, ValueError, RuntimeError) as error:
+            self.branch_list_by_id.pop(pending.request_id, None)
+            remove_branch_list_dir(pending.neutral_dir)
+            request = pending.request
+            self._publish_branch_list_later(BranchList(pending.request_id, pending.endpoint, cause=self._branch_list_cause(request.program_filename, request.arguments, str(error))))
+
+    def _publish_branch_list_later(self, branch_list: BranchList) -> None:
+        """Hand a branch list to its callback on a later turn, so the caller always knows the request's id before the answer arrives."""
+        QTimer.singleShot(0, self, lambda: self._publish_branch_list(branch_list))
+
+    def _publish_branch_list(self, branch_list: BranchList) -> None:
+        """Call the branch list's callback unless the request was cancelled meanwhile."""
+        complete = self.branch_complete_by_id.pop(branch_list.request_id, None)
+        if complete is not None:
+            complete(branch_list)
+
+    def close(self) -> None:
+        """Cancel all clone work and every branch list while retaining traces until the native owner drains."""
+        self.closed = True
+        for request_id in (*self.branch_complete_by_id, *self.branch_list_by_id):
+            self.cancel_branch_list(request_id)
+        for run in tuple(self.run_by_id.values()):
+            self.cancel(run.operation_id)
+            if not run.has_running_step():
+                run.trace.close()
+
+    def cancel(self, operation_id: str) -> None:
+        """Invalidate later publication while supervised Git drains its descendants."""
+        run = self.run_by_id.get(operation_id)
+        if run is None:
+            return
+        run.cancelled = True
+        if not run.has_running_step():
+            return
+        if run.retry_result is not None:
+            QTimer.singleShot(0, self, lambda: self._clone_again(run))
+            return
+        owner_id = run.retry_operation_id or operation_id
+        requests = list(self.runner.pending_requests)
+        for active in self.runner.active_by_id.values():
+            requests.append(active.request)
+        for request in requests:
+            if request.request_id == owner_id or request.operation_id == owner_id:
+                self.runner.cancel(request.request_id)
+
+    def open_result(self, operation_id: str, success: bool, diagnostic: PreparedDiagnostic | None = None) -> None:
+        """Record the opening result without replaying a successful clone."""
+        run = self.run_by_id[operation_id]
+        run.open_status = OperationStatus.SUCCESS.value if success else OperationStatus.FAILED.value
+        if diagnostic is not None:
+            run.diagnostic = diagnostic
+
+    def _finished(self, result: ProcessResult) -> None:
+        """Finish a branch list, or recheck a clone's destination ownership after native exit before allowing a new session."""
+        pending = self.branch_list_by_id.pop(result.request.request_id, None)
+        if pending is not None:
+            self._branch_list_finished(pending, result)
+            return
+        run = self.run_by_id.get(result.request.request_id)
+        if run is None or run.clone_status != "running":
+            return
+        publish_after_trace(lambda: self._clone_exited(run, result), self)
+
+    def _clone_exited(self, run: CloneRun, result: ProcessResult) -> None:
+        """Recheck a clone's destination ownership after native exit, then validate what Git wrote or end the clone.
+
+        A clone whose secret read failed before Git wrote any repository is started again a moment later instead.
+        """
+        if self._retry_after_credential_read_failure(run, result):
+            return
+        run.clone_status = operation_status(result.status).value
+        run.recursive_status = operation_status(result.status).value
+        try:
+            run.destination.verify()
+        except (OSError, ValueError) as error:
+            run.clone_status = OperationStatus.UNKNOWN.value
+            run.diagnostic = Diagnostic("Clone repository", run.intent.parent_dir, result.request.program_filename, [], str(error)).prepare()
+        if run.clone_status != OperationStatus.SUCCESS.value and run.diagnostic is None:
+            bare = run.intent.options.bare
+            written = repository_written(run.destination.destination_dir, bare)
+            # A bare clone has no submodules and is never opened, so what an interrupted one leaves is only a kept folder,
+            # never a partial clone to open or to retry submodules in. Git writes a bare HEAD before any transfer.
+            run.incomplete_repository = written and not bare
+            cause = result.cause
+            if written:
+                error_text = git_error_text(result.stderr)
+                refusals = checkout_refusals(error_text) if not bare else ()
+                refusal_text = checkout_refusal_text(refusals, sys.platform)
+                run.checkout_refusal_text = refusal_text
+                refused_paths = refused_checkout_submodule_paths(error_text) if not bare else ()
+                run.refused_submodule_dir_set.update(refused_submodule_dirs(refused_paths, run.destination.destination_dir))
+                if refusal_text:
+                    cause = refusal_text + "\n" + cause
+                elif not bare and (b"submodule" in result.stderr.lower() or b"failed to clone" in result.stderr.lower()):
+                    cause = SUBMODULE_PARTIAL_TEXT + "\n" + cause
+                else:
+                    cause = "The partial repository was preserved. Review the details before continuing.\n" + cause
+                # Git refuses local submodules with its default protocol.file.allow, whatever URL the parent came from.
+                # GitPane gives no permission for that and only says why, after Git's own lines.
+                if file_transport_refused(error_text):
+                    run.trace.append_failure_cause(run.operation_id, FILE_TRANSPORT_REFUSED_TEXT)
+                # Git cites the first name it refuses in a submodule, then stops its checkout. GitPane only explains those
+                # lines, after them, without another process and without file name rules of its own.
+                # A cause is one console line, so each refused submodule gets its own.
+                for refusal in refusals:
+                    run.trace.append_failure_cause(run.operation_id, checkout_refusal_text((refusal,), sys.platform))
+            run.diagnostic = Diagnostic("Clone repository", run.destination.destination_dir, result.request.program_filename, result.request.arguments,
+                                        cause, result.stderr, result.return_code).prepare()
+        step = OperationStepResult("Clone repository", OperationStatus(run.clone_status), process_status=result.status, effect=run.clone_status, diagnostic=run.diagnostic, return_code=result.return_code)
+        if run.clone_status == OperationStatus.UNKNOWN.value or not repository_written(run.destination.destination_dir, run.intent.options.bare):
+            if run.clone_status != OperationStatus.SUCCESS.value:
+                self._release_empty_destination(run)
+            self._complete(run, (step,))
+            return
+        git_filename = result.request.program_filename
+
+        def validated() -> None:
+            """End the clone, after checking out the submodules Git cloned but left without files when it refused another's checkout."""
+            steps = (step, OperationStepResult("Validate cloned repository", OperationStatus(run.validation_status), diagnostic=run.diagnostic))
+            if not run.refused_submodule_dir_set or run.validation_status != OperationStatus.SUCCESS.value or run.cancelled or not self.is_current(run.intent):
+                self._complete(run, steps)
+                return
+            self._check_out_cloned_submodules(run, git_filename, lambda checkout_step: self._complete(run, (*steps, checkout_step)))
+
+        self.validate_repository(run, git_filename, validated, reconcile_only=True)
+
+    def _retry_after_credential_read_failure(self, run: CloneRun, result: ProcessResult) -> bool:
+        """Start the clone again after a pause when its secret read failed and Git left nothing; tell whether it will.
+
+        Only a clone that left its folder as GitPane created it, empty and without any repository, is started again:
+        Git removes what it wrote when a clone fails, so the next attempt starts from the same state. A clone that already
+        wrote its repository, such as one whose submodule failed, keeps the partial clone path and Retry submodules.
+        """
+        if run.cancelled or self.closed or run.native_request is None or run.destination is None:
+            return False
+        if not credential_read_retry_due(result, run.credential_read_retry_count):
+            return False
+        try:
+            run.destination.verify()
+            if repository_written(run.destination.destination_dir, run.intent.options.bare):
+                return False
+            with os.scandir(run.destination.destination_dir) as entries:
+                if next(entries, None) is not None:
+                    return False
+        except (OSError, ValueError):
+            return False
+        run.credential_read_retry_count += 1
+        run.retry_result = result
+        run.trace.append_event(run.operation_id, "status", credential_read_retry_text(run.credential_read_retry_count))
+        QTimer.singleShot(CREDENTIAL_READ_RETRY_DELAY_MS, self, lambda: self._clone_again(run))
+        return True
+
+    def _clone_again(self, run: CloneRun) -> None:
+        """Start the clone again once its pause is over, or end it as cancelled when the user cancelled or GitPane is closing.
+
+        A request that stopped being current during the pause ends with the refusal its first start gives, not as cancelled.
+
+        Whichever comes first, the end of the pause or the cancel, decides; the other does nothing. The launch checks of
+        the first start run again: the destination, the request's authority and the composed credential settings.
+        """
+        failed_result = run.retry_result
+        if failed_result is None:
+            return
+        run.retry_result = None
+        if run.cancelled or self.closed:
+            self._clone_exited(run, replace(failed_result, status=ProcessStatus.CANCELLED, cause=SharedText.CREDENTIAL_READ_RETRY_CANCELLED.value))
+            return
+        if not self.is_current(run.intent):
+            # Nobody cancelled: the request lost its authority during the pause, which the first start refuses with its own words.
+            self._clone_exited(run, replace(failed_result, status=ProcessStatus.FAILED, cause=CLONE_REQUEST_NOT_CURRENT_TEXT, stderr=b""))
+            return
+        try:
+            self.runner.start(self.ssh.prompt(run.native_request, is_current=lambda: not run.cancelled and self.is_current(run.intent)))
+        except (OSError, ValueError, RuntimeError) as failure:
+            # Git did not start again: its earlier output is already in the console, and keeping it here would start
+            # another retry on the same words.
+            self._clone_exited(run, replace(failed_result, status=ProcessStatus.FAILED, cause=str(failure), stderr=b""))
+
+    def _check_out_cloned_submodules(self, run: CloneRun, git_filename: str, complete: Callable[[OperationStepResult], None]) -> None:
+        """Check out, one at a time, the submodules Git cloned but never checked out because it stopped on a refused checkout.
+
+        Git clones every submodule first, then checks them out in order, and stops at the first checkout it refuses: the
+        submodules after that one are cloned, with their history, but their folder holds only the ``.git`` file. They
+        are checked out here under the clone's own reservation, with the account the clone used for its own address,
+        the way Retry submodules does; the submodules whose checkout Git refused are left exactly as Git left them. The
+        clone's own result is kept: Git did refuse a checkout. A failure of this step is written in the console only, and
+        so is the reason the step did not run when the clone no longer holds its repository.
+        """
+        destination = run.destination
+        owner = self.repository_operation.active_by_id.get(run.operation_id)
+        if owner is None:
+            run.trace.append_failure_cause(run.operation_id, SharedText.CLONED_SUBMODULE_CHECKOUT_NOT_STARTED.value)
+            complete(OperationStepResult(SharedText.CLONED_SUBMODULE_CHECKOUT_STEP.value, OperationStatus.REFUSED))
+            return
+        context = clone_context(destination.destination_dir, False)
+        destinations = ()
+        if run.selection is not None and endpoint_kind(run.intent.endpoint, self.allow_local_endpoint) == HTTPS_ENDPOINT_KIND:
+            destinations = (RecursiveTransportContext(run.intent.endpoint, endpoint_origin(run.intent.endpoint), run.selection),)
+
+        def current() -> bool:
+            """Check destination identity and publication authority before every checkout."""
+            destination.verify()
+            return not run.cancelled and self.is_current(run.intent)
+
+        def checked_out(error: Exception | None) -> None:
+            """Write why the step failed, if it did, once the trace has heard the last process, then end the clone."""
+            status = OperationStatus.CANCELLED if run.cancelled else OperationStatus.FAILED if error is not None else OperationStatus.SUCCESS
+            run.cloned_checkout_status = status
+            diagnostic = None
+            if error is not None:
+                if isinstance(error, (GitCommandError, SubmoduleInitializationError)):
+                    diagnostic = error.diagnostic
+                else:
+                    diagnostic = Diagnostic(SharedText.CLONED_SUBMODULE_CHECKOUT_STEP.value, destination.destination_dir, git_filename, [], str(error)).prepare()
+                run.trace.append_diagnostic(run.operation_id, "error", diagnostic, status)
+            complete(OperationStepResult(SharedText.CLONED_SUBMODULE_CHECKOUT_STEP.value, status, diagnostic=diagnostic))
+
+        def ended(value: object, error: Exception | None) -> None:
+            """Finish the step one turn later, after the trace has heard the last process."""
+            publish_after_trace(lambda: checked_out(error), self)
+
+        run.cloned_checkout_status = OperationStatus.PENDING
+        sequence = self.submodule.resume_missing(owner, run.trace, current, destinations, credential_helper=OperationCredentialHelper(),
+                                                 refused_dir_set=run.refused_submodule_dir_set, initialize_missing=False)
+        self.repository_operation.worktree_service.run(context, git_filename, sequence, ended, operation_id=run.operation_id)
+
+    def retry_submodules(self, run: CloneRun, git_filename: str) -> None:
+        """Resume only missing declared children while preserving the original native clone result.
+
+        A retry refused at its launch says why: a clone request that is no longer current says so, and a refused
+        reservation takes the repository owner's reason, which names another operation only when a write really holds
+        the cloned repository.
+        """
+        if (run.retry_operation_id or run.operation_id) in self.repository_operation.active_by_id or run.destination is None:
+            return
+        # The same run serves every Retry submodules: a refusal from an earlier retry must not reopen the install window
+        # after a later one.
+        run.credential_manager_refusal = None
+        destination = run.destination
+        context = clone_context(destination.destination_dir, run.intent.options.bare)
+        run.retry_operation_id = uuid.uuid4().hex
+        run.trace.operation_id = run.retry_operation_id
+        owner = OperationIntent.capture(run.retry_operation_id, context, git_filename, operation="Retry submodules", generation=run.intent.generation,
+                                        reserved_repository_dirs=(canonical_path(destination.destination_dir),), action=OperationAction.SUBMODULE_INIT)
+
+        def current() -> bool:
+            """Check destination identity and publication authority before every resumed write."""
+            destination.verify()
+            return not run.cancelled and self.is_current(run.intent)
+
+        def sequence() -> Generator:
+            """Use the same initialization reader and native supervision as declared child activation."""
+            if not current():
+                raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+            target = run.authentication_target
+            destinations = ()
+            if target is not None and run.child_selection is not None:
+                if initialization_signature(target.parent, target.entry.repository_dir) != target.signature:
+                    raise ValueError("The child destination or configuration changed. Review the details before retrying.")
+                current_target = yield from self.submodule.authentication_target(context, "Authentication failed for " + target.endpoint)
+                if current_target != target:
+                    raise ValueError("The child endpoint changed. Review the details before retrying.")
+                destinations = (RecursiveTransportContext(target.endpoint, endpoint_origin(target.endpoint), run.child_selection),)
+            try:
+                # The submodules Git cloned but left without files are checked out too, except those whose checkout it refused.
+                yield from self.submodule.resume_missing(owner, run.trace, current, destinations, credential_helper=OperationCredentialHelper(),
+                                                         refused_dir_set=run.refused_submodule_dir_set)
+            except (OSError, ValueError, RuntimeError) as error:
+                if current():
+                    # Only Git's own error output may say a submodule was refused: the full block also lists the command
+                    # line, whose empty credential helper would make every failure look like an authentication refusal.
+                    refusal_text = error.diagnostic.stderr if isinstance(error, SubmoduleInitializationError) else str(error)
+                    run.authentication_target = yield from self.submodule.authentication_target(context, refusal_text)
+                raise
+            if not current():
+                raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+            if target is not None and run.child_selection is not None:
+                child_context = yield from self.submodule._context(target.entry.repository_dir)
+                if not current():
+                    raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+                self.authentication.save_selection(run.child_selection.origin, run.child_selection, child_context)
+
+        def finish_retry(error: Exception | None) -> None:
+            """End the retry once the trace has heard the last process end, keeping earlier diagnostics.
+
+            Called one turn after that end, so a failed retry writes its diagnostic and its end line at once; a
+            successful one first validates the repository.
+            """
+            run.recursive_status = OperationStatus.CANCELLED.value if run.cancelled else OperationStatus.FAILED.value if error else OperationStatus.SUCCESS.value
+            if error:
+                if isinstance(error, (GitCommandError, SubmoduleInitializationError)):
+                    run.diagnostic = error.diagnostic
+                else:
+                    run.diagnostic = Diagnostic("Retry submodules", destination.destination_dir, git_filename, [], str(error)).prepare()
+                # Only the error output of the Git process that failed may say why, decoded once when it ended.
+                error_text = error.git_error_text if isinstance(error, SubmoduleInitializationError) else ""
+                # The retry's own cause replaces the clone's, so the clone's checkout refusal no longer heads what the form shows.
+                run.checkout_refusal_text = ""
+                # Retrying does not change Git's protocol.file.allow setting, so a refused local submodule says why again.
+                if file_transport_refused(error_text):
+                    run.trace.append_failure_cause(run.operation_id, FILE_TRANSPORT_REFUSED_TEXT)
+                # Retrying does not change the names the repository records either, so a submodule whose checkout Git
+                # refused says why again, after Git's lines, one console line per refused submodule.
+                for refusal in checkout_refusals(error_text):
+                    run.trace.append_failure_cause(run.operation_id, checkout_refusal_text((refusal,), sys.platform))
+                line_status = OperationStatus(run.recursive_status)
+                # The credential manager was refused before Git started, so the line says the retry did not start, as
+                # every other refused operation does; the retry's own status stays failed.
+                if isinstance(error, CredentialManagerRefusal) and not run.cancelled:
+                    line_status = OperationStatus.REFUSED
+                    run.credential_manager_refusal = error.detection
+                run.trace.append_diagnostic(run.operation_id, "error", run.diagnostic, line_status)
+            steps = (OperationStepResult("Retry submodules", OperationStatus(run.recursive_status), diagnostic=run.diagnostic),)
+            if error is None and not run.cancelled:
+                self.validate_repository(run, git_filename, lambda: self._complete(run, steps))
+            else:
+                self._end(run, self._reconcile_reservation(run, steps))
+
+        def complete(value: object, error: Exception | None) -> None:
+            """Finish the retry one turn later, after all initialization reads have finished."""
+            publish_after_trace(lambda: finish_retry(error), self)
+
+        try:
+            if not current():
+                raise ValueError(CLONE_REQUEST_NOT_CURRENT_TEXT)
+            if not self.repository_operation.reserve(owner):
+                raise ValueError(self.repository_operation.refusal_cause(owner))
+            run.recursive_status = "running"
+            self.repository_operation.worktree_service.run(context, git_filename, sequence(), complete, operation_id=run.retry_operation_id)
+        except (OSError, ValueError) as error:
+            complete(None, error)
+
+    def validate_repository(self, run: CloneRun, git_filename: str, complete: Callable[[], None], *, reconcile_only: bool = False) -> None:
+        """Inspect real HEAD and references so an invalid server HEAD cannot look empty.
+
+        A check that cannot reserve the cloned repository fails with the repository owner's reason, which names another
+        operation only when a write really holds it.
+        """
+        run.validation_status = "running"
+        destination = run.destination
+        context = clone_context(destination.destination_dir, run.intent.options.bare)
+        verification_id = ""
+        operation_id = run.retry_operation_id or run.operation_id
+        if operation_id not in self.repository_operation.active_by_id:
+            verification_id = uuid.uuid4().hex
+            owner = OperationIntent.capture(verification_id, context, git_filename, operation="Validate cloned repository",
+                                            reserved_repository_dirs=(canonical_path(destination.destination_dir),), action=OperationAction.CONFIG_WRITE)
+            if not self.repository_operation.reserve(owner):
+                run.validation_status = OperationStatus.FAILED.value
+                run.diagnostic = Diagnostic("Validate cloned repository", destination.destination_dir, git_filename, [], self.repository_operation.refusal_cause(owner)).prepare()
+                QTimer.singleShot(0, self, complete)
+                return
+
+        def before_start() -> None:
+            """Refuse queued validation commands after directory replacement or cancellation."""
+            current_owner = self.repository_operation.active_by_id.get(verification_id or operation_id)
+            if current_owner is None:
+                raise ValueError("Clone validation no longer owns its destination")
+            self.repository_operation.validate(current_owner)
+            destination.verify()
+            if not reconcile_only and (run.cancelled or not self.is_current(run.intent)):
+                raise ValueError("Clone validation was cancelled.")
+
+        def sequence() -> Generator[GitCommand, bytes]:
+            """Recheck ownership before each native validation and exact origin restoration."""
+            destination.verify()
+            if not reconcile_only and (run.cancelled or not self.is_current(run.intent)):
+                raise ValueError("Clone validation was cancelled.")
+            if not run.origin_restored and endpoint_kind(run.intent.endpoint, self.allow_local_endpoint) == HTTPS_ENDPOINT_KIND:
+                yield GitCommand(["config", "--local", "remote.origin.url", run.intent.endpoint], profile=LOCAL_WRITE_PROFILE, before_start=before_start)
+                run.origin_restored = True
+            destination.verify()
+            if not reconcile_only and (run.cancelled or not self.is_current(run.intent)):
+                raise ValueError("Clone validation was cancelled.")
+            head = yield GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1), before_start=before_start)
+            destination.verify()
+            if not reconcile_only and (run.cancelled or not self.is_current(run.intent)):
+                raise ValueError("Clone validation was cancelled.")
+            refs = yield GitCommand(["for-each-ref", "--format=%(objectname)"], before_start=before_start)
+            destination.verify()
+            if refs.strip() and not head.strip():
+                raise ValueError("Repository cloned, but the server HEAD does not identify a checked-out branch. Repair HEAD before opening this directory.")
+            # A bare repository has no working tree and therefore no submodule to authenticate.
+            if (not run.intent.options.bare and run.incomplete_repository and run.recursive_status != OperationStatus.SUCCESS.value and run.diagnostic is not None
+                    and not run.cancelled and self.is_current(run.intent)):
+                run.authentication_target = yield from self.submodule.authentication_target(context, run.diagnostic.stderr)
+
+        def validated(value: object, error: Exception | None) -> None:
+            """Retain the native clone success even when readiness cannot be established."""
+            run.validation_status = OperationStatus.SUCCESS.value if error is None else OperationStatus.FAILED.value
+            if error is not None:
+                run.diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Validate cloned repository", destination.destination_dir, git_filename, [], str(error)).prepare()
+            if verification_id:
+                self.repository_operation.release(verification_id)
+            complete()
+
+        self.repository_operation.worktree_service.run(context, git_filename, sequence(), validated, operation_id=operation_id)
+
+    def _release_empty_destination(self, run: CloneRun) -> None:
+        """Remove the empty folder a failed or cancelled clone created, so the same name can be cloned again.
+
+        Called only when this clone's Git has exited, or never started, and left no repository in the folder. The
+        folder is kept while another queued or running Git command still uses it, when it changed, or when it holds
+        anything at all; the clone console says which happened.
+        """
+        destination = run.destination
+        if destination is None or run.destination_removed:
+            return
+        if self._destination_in_use(run, destination.destination_dir):
+            reason = "another Git command still uses it"
+        elif destination.remove_if_empty():
+            run.destination_removed = True
+            run.trace.append_event(run.operation_id, "status", DESTINATION_REMOVED_TEXT + destination.destination_dir)
+            return
+        else:
+            reason = kept_destination_reason(destination)
+        run.trace.append_event(run.operation_id, "status", DESTINATION_KEPT_TEXT + destination.destination_dir + " (" + reason + ")")
+
+    def _destination_in_use(self, run: CloneRun, destination_dir: str) -> bool:
+        """Tell whether a queued or running command of this clone, or any command working inside its folder, is still there."""
+        requests = list(self.runner.pending_requests)
+        for active in self.runner.active_by_id.values():
+            requests.append(active.request)
+        owned_dir = os.path.normcase(os.path.abspath(destination_dir))
+        for request in requests:
+            if run.operation_id in (request.request_id, request.operation_id):
+                return True
+            working_dir = os.path.normcase(os.path.abspath(request.working_dir))
+            if working_dir == owned_dir or working_dir.startswith(owned_dir + os.sep):
+                return True
+        return False
+
+    def _complete(self, run: CloneRun, steps: tuple[OperationStepResult, ...]) -> None:
+        """Release the reservation only after clone and readiness reads have terminated, then end the clone once its trace has caught up."""
+        status = self._reconcile_reservation(run, steps)
+        publish_after_trace(lambda: self._end(run, status), self)
+
+    def _reconcile_reservation(self, run: CloneRun, steps: tuple[OperationStepResult, ...]) -> OperationStatus:
+        """Release the clone's or retry's repository reservation with its outcome, and return the status its end line shows."""
+        status = OperationStatus(run.recursive_status) if run.validation_status in {"not_started", OperationStatus.SUCCESS.value} else OperationStatus.PARTIAL
+        operation_id = run.retry_operation_id or run.operation_id
+        if operation_id in self.repository_operation.active_by_id:
+            self.repository_operation.reconcile(OperationOutcome(operation_id, status, steps, run.diagnostic))
+        return status
+
+    def _end(self, run: CloneRun, status: OperationStatus) -> None:
+        """Write the clone's end line in its console, then publish the finished clone.
+
+        The end line is console text only: the ``--log`` file and the records already hold every step's own status. A
+        clone the user cancelled says so, whatever the checks of what Git had already written found.
+        """
+        end_status = OperationStatus.CANCELLED if run.cancelled else status
+        label = RETRY_SUBMODULES_LABEL if run.retry_operation_id else CLONE_LABEL
+        run.trace.append_console_line(ConsoleLine(operation_end_text(label, end_status), run.trace.end_tone(end_status, failure_reported=run.diagnostic is not None)))
+        self.finished.emit(run)
+        if self.closed:
+            run.trace.close()