gitpane 1.0.0__py3-none-any.whl

gitpane/submodule/submodule_discovery.py

@@ -0,0 +1,1180 @@
+"""Discover declared gitlinks without treating an empty child as its parent."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+import uuid
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+from gitpane.account.credential_manager import CredentialManagerRefusal
+from gitpane.config import (
+    GIT_CLONE_TIMEOUT_MS,
+    GIT_TRANSPORT_TIMEOUT_MS,
+    SUBMODULE_SUMMARY_COMMIT_LIMIT,
+    SUBMODULE_SUMMARY_DIFFERENCE_LIMIT,
+    SUBMODULE_SUMMARY_OUTPUT_LIMIT_BYTES,
+    SharedText,
+)
+from gitpane.history.history_parse import parse_tree_entries
+from gitpane.history.repository_value import FileStatus, RepositoryContext, validate_oid
+from gitpane.operation.console_line import REPOSITORY_HEADER_LABEL, RETRY_SUBMODULES_LABEL, ConsoleHeader
+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 NETWORK_PROFILE, ProcessRequest, ProcessStatus
+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.cloned_without_checkout import is_cloned_without_checkout
+from gitpane.system.path_identity import canonical_path
+from gitpane.transport.git_refusal import CREDENTIALS_MISSING_PATTERN, file_transport_refused, git_output_lines, repository_not_found
+from gitpane.transport.refusal_notice import FILE_TRANSPORT_REFUSED_TEXT
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+from gitpane.worktree.worktree_snapshot import StagingSide, SubmoduleState, parse_status
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.account.authentication import AuthenticationService
+    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.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry
+
+
+SUBMODULE_INIT_ARGUMENTS = ("submodule", "update", "--init", "--recursive", "--checkout", "--")
+# The same update for a submodule Git cloned but never checked out. Git skips the checkout of a submodule whose HEAD
+# already names the recorded commit, which is what a clone leaves whenever that commit is the tip of the default
+# branch; --force makes it check the files out anyway. It only ever runs on a folder that holds nothing but its .git
+# file and a Git folder without an index, checked again right before Git starts, so there is nothing it could overwrite.
+SUBMODULE_CLONED_CHECKOUT_ARGUMENTS = ("submodule", "update", "--init", "--recursive", "--checkout", "--force", "--")
+# The line that ends an initialization console, with the word of its status (``done``); the result record of the --log
+# file keeps the same line with the bare status (``success``).
+INITIALIZE_END_TEMPLATE = "Initialize submodule: {status} — {repository_dir}"
+SUBMODULE_OCCUPIED_MESSAGE = ("Cannot initialize the submodule: its folder already contains files. "
+                              "Please remove these files or initialize the submodule manually.")
+# Causes of a failed, stopped or incomplete initialization. Each ends on the action that tries again, which depends on
+# where it started: the repository window opens the submodule again, the clone form offers its Retry submodules button.
+# The ending is chosen once per initialization, so every cause it can give names the same action.
+INITIALIZE_INTERRUPTED_START = "Submodule initialization was interrupted. Review the details before "
+INITIALIZE_FAILED_START = "Could not initialize the submodule. Existing files were preserved. Review the details, fix the reported problem, then "
+INITIALIZE_INTERRUPTED_KEPT_START = "Submodule initialization was interrupted. Existing files were preserved. "
+INITIALIZE_INCOMPLETE_START = "Some submodules could not be initialized. Existing files were preserved. "
+OPEN_AGAIN_INTERRUPTED_ENDING = "opening it again."
+OPEN_AGAIN_FAILED_ENDING = "open the submodule again."
+OPEN_AGAIN_RETRY_SENTENCE = "Open the submodule again to retry."
+RETRY_INTERRUPTED_ENDING = "clicking " + RETRY_SUBMODULES_LABEL + " again."
+RETRY_FAILED_ENDING = "click " + RETRY_SUBMODULES_LABEL + " again."
+RETRY_AGAIN_SENTENCE = "Click " + RETRY_SUBMODULES_LABEL + " again."
+
+
+def initialization_command(git_filename: str, parent_dir: str, path: str, *, powershell: bool) -> str:
+    """Quote a manual initialization command for one child and its parent without running it.
+
+    The command is shown so the user can run it after clearing an occupied submodule folder. It is the same
+    initialization as opening the submodule: like it, it adds no protocol.file.allow, so Git's own setting decides
+    whether a submodule whose URL is a local folder may be cloned.
+    """
+    arguments = [git_filename, "--literal-pathspecs", "-C", parent_dir, *SUBMODULE_INIT_ARGUMENTS, path]
+    if not powershell:
+        return shlex.join(arguments)
+    quoted_paths = []
+    for argument in (git_filename, parent_dir, path):
+        # PowerShell treats typographic apostrophes as quotes too; double each accepted delimiter.
+        for quote in ("'", "\u2018", "\u2019"):
+            argument = argument.replace(quote, quote + quote)
+        quoted_paths.append("'" + argument + "'")
+    quoted_git_filename, quoted_parent_dir, quoted_path = quoted_paths
+    return " ".join(["&", quoted_git_filename, "--literal-pathspecs", "-C", quoted_parent_dir, *SUBMODULE_INIT_ARGUMENTS, quoted_path])
+
+
+@dataclass(frozen=True)
+class SubmoduleReferenceState:
+    """Keep parent HEAD, parent index and child checkout as independent observed sources."""
+
+    parent_dir: str
+    path: bytes
+    repository_dir: str
+    parent_head_oid: str | None
+    committed_oid: str | None
+    indexed_oid: str | None
+    checkout_oid: str | None
+    committed_availability: str
+    indexed_availability: str
+    checkout_availability: str
+    submodule: SubmoduleState
+    cause: str = ""
+    internal_changes: tuple[SubmoduleDifference, ...] | None = None
+
+
+@dataclass(frozen=True)
+class SubmoduleCommit:
+    """Preserve a known hash even when its metadata cannot be read locally."""
+
+    oid: str | None
+    timestamp: int | None = None
+    subject: str | None = None
+
+
+@dataclass(frozen=True)
+class SubmoduleDifference:
+    """Retain literal path bytes, including both sides of a rename."""
+
+    status: str
+    path: bytes
+    old_path: bytes | None = None
+
+
+def parse_internal_status(output: bytes) -> tuple[SubmoduleDifference, ...]:
+    """Preserve both native status columns and literal rename paths from porcelain v1 NUL records."""
+    if output and not output.endswith(b"\0"):
+        raise ValueError("Incomplete submodule status output")
+    changes = []
+    records = iter(output.split(b"\0"))
+    status_width = len("XY")
+    for record in records:
+        if not record:
+            continue
+        status = record[:status_width].decode("ascii")
+        separator = record[status_width:status_width + len(b" ")]
+        path = record[status_width + len(b" "):]
+        if separator != b" " or not path or any(character not in " MTADRCU?!" for character in status):
+            raise ValueError("Malformed submodule status record")
+        old_path = None
+        if "R" in status or "C" in status:
+            old_path = next(records, None)
+            if not old_path:
+                raise ValueError("Missing submodule rename source")
+        changes.append(SubmoduleDifference(status, path, old_path))
+    return tuple(sorted(changes, key=lambda change: (change.path, change.old_path or b"", change.status)))
+
+
+@dataclass(frozen=True)
+class SubmoduleSummary:
+    """Publish one validated comparison with unknown facts distinct from empty lists."""
+
+    reference: SubmoduleReferenceState
+    side: StagingSide
+    source: SubmoduleCommit
+    target: SubmoduleCommit
+    relation: str = "Unavailable"
+    added_count: int | None = None
+    removed_count: int | None = None
+    added_commits: tuple[SubmoduleCommit, ...] = ()
+    removed_commits: tuple[SubmoduleCommit, ...] = ()
+    differences: tuple[SubmoduleDifference, ...] | None = None
+    differences_truncated: bool = False
+    cause: str = ""
+
+
+def summary_command(directory: str, arguments: list[str], *, accepted_codes: tuple[int, ...] = (0,)) -> GitCommand:
+    """Apply the same output bound to every local comparison read."""
+    return GitCommand(["-C", directory, *arguments], accepted_codes=accepted_codes, stdout_limit_bytes=SUBMODULE_SUMMARY_OUTPUT_LIMIT_BYTES)
+
+
+@dataclass(frozen=True)
+class SubmoduleEntry:
+    """Describe a repository or declared child independently of its tree label."""
+
+    repository_dir: str
+    parent_dir: str | None
+    path: str
+    section: str
+    branch: str | None
+    head_oid: str | None
+    availability: str
+    cause: str = ""
+    submodule: SubmoduleState = field(default_factory=SubmoduleState)
+
+
+@dataclass(frozen=True)
+class SubmoduleSnapshot:
+    """Publish one complete repository family with explicit child availability."""
+
+    root_dir: str
+    entries: tuple[SubmoduleEntry, ...]
+    cause: str = ""
+
+
+@dataclass(frozen=True)
+class SubmoduleInitIntent:
+    """Capture the parent index reference and the declared target before native writes."""
+
+    operation: OperationIntent
+    path: bytes
+    expected_oid: str
+    repository_dir: str
+    signature: tuple
+    configuration_filenames: tuple[str, ...] = ()
+    inspected_dirs: tuple[str, ...] = ()
+    # True for a submodule Git cloned but never checked out: its HEAD may differ from the recorded commit while there is
+    # no file to keep, and Git is asked to check it out anyway.
+    cloned_without_checkout: bool = False
+
+
+@dataclass
+class SubmoduleInitRun:
+    """Retain native, validation and opening results independently across a retry."""
+
+    operation_id: str
+    entry: SubmoduleEntry
+    trace: OperationTrace
+    session_id: str = ""
+    intent: SubmoduleInitIntent | None = None
+    status: str = "preparing"
+    validation_status: str = "not_started"
+    open_status: str = "not_started"
+    cancelled: bool = False
+    diagnostic: PreparedDiagnostic | None = None
+    snapshot: SubmoduleSnapshot | None = None
+    # None until Git was launched for this initialization.
+    native_status: ProcessStatus | None = None
+    return_code: int | None = None
+    # Why the credential manager was refused when that refusal stopped this initialization, so the window explaining
+    # how to install it can open; None otherwise.
+    credential_manager_refusal: CredentialManagerDetection | None = None
+    # True once the sentence of each submodule whose checkout Git refused was written, before the submodules Git left
+    # cloned after it were checked out, so the end of the initialization does not write it again.
+    refusal_explained: bool = False
+    # The error output of the initialization's submodule update process, or of the nested one that failed, decoded once
+    # for every refusal check.
+    git_error_text: str = ""
+
+
+@dataclass(frozen=True)
+class SubmoduleAuthenticationTarget:
+    """Bind a requested account to a missing child and the configuration that named it."""
+
+    entry: SubmoduleEntry
+    endpoint: str
+    parent: RepositoryContext
+    signature: tuple
+
+
+def initialization_signature(context: RepositoryContext, child_dir: str, configuration_filenames: tuple[str, ...] = (), inspected_dirs: tuple[str, ...] = ()) -> tuple:
+    """Detect replaced path components and changed parent configuration while queued."""
+    states = []
+    for inspected_dir in inspected_dirs:
+        declared_directory(context.repository_dir, os.path.relpath(inspected_dir, context.repository_dir))
+        directory = inspected_dir
+        while canonical_path(directory) != canonical_path(context.repository_dir):
+            state = os.stat(directory) if os.path.exists(directory) else None
+            states.append((directory, None if state is None else (state.st_dev, state.st_ino)))
+            directory = os.path.dirname(directory)
+    directory = child_dir
+    root_dir = canonical_path(context.repository_dir)
+    while True:
+        if os.path.islink(directory) or os.path.isjunction(directory):
+            raise ValueError("Linked submodule paths are not supported")
+        state = os.stat(directory) if os.path.exists(directory) else None
+        states.append((directory, None if state is None else (state.st_dev, state.st_ino)))
+        if canonical_path(directory) == root_dir:
+            break
+        parent_dir = os.path.dirname(directory)
+        if parent_dir == directory:
+            raise ValueError("Submodule path leaves its parent repository")
+        directory = parent_dir
+    for filename in (context.git_dir, context.common_git_dir, os.path.join(context.repository_dir, ".git"), os.path.join(context.repository_dir, ".gitmodules"),
+                     os.path.join(context.git_dir, "index"), os.path.join(context.common_git_dir, "config"), *configuration_filenames):
+        if os.path.islink(filename) or os.path.isjunction(filename):
+            raise ValueError("Linked repository metadata is not supported")
+        if os.path.isfile(filename):
+            with open(filename, "rb") as stream:
+                states.append((filename, stream.read()))
+        elif os.path.isdir(filename):
+            state = os.stat(filename)
+            states.append((filename, state.st_dev, state.st_ino))
+        else:
+            states.append((filename, None))
+    if os.path.isdir(child_dir) and not os.path.lexists(os.path.join(child_dir, ".git")):
+        with os.scandir(child_dir) as children:
+            if next(children, None) is not None:
+                raise ValueError(SUBMODULE_OCCUPIED_MESSAGE)
+    return tuple(states)
+
+
+def declared_directory(parent_dir: str, path: str) -> str:
+    """Reject escaped or linked child paths before reading another repository."""
+    parts = path.replace("\\", "/").split("/")
+    if not path or os.path.isabs(path) or ":" in path or any(part in ("", ".", "..") for part in parts):
+        raise ValueError("Invalid submodule path")
+    root_dir = canonical_path(parent_dir)
+    directory = parent_dir
+    for part in parts:
+        directory = os.path.join(directory, part)
+        if os.path.islink(directory) or os.path.isjunction(directory):
+            raise ValueError("Linked submodule paths are not supported")
+    if os.path.commonpath((root_dir, canonical_path(directory))) != root_dir:
+        raise ValueError("Submodule path leaves its parent repository")
+    return directory
+
+
+@dataclass
+class OperationCredentialHelper:
+    """Keep the credential helper one submodule operation found, so every child it initializes uses it without searching again.
+
+    ``commands`` stays None until the first child that composes an account searches; after a refusal that lets the
+    operation go on, it holds the preview, so no later child searches either.
+    """
+
+    commands: tuple[str, ...] | None = None
+
+
+class SubmoduleInitializationError(ValueError):
+    """A submodule initialization that failed after GitPane already prepared its diagnostic.
+
+    The diagnostic travels with the error so the console shows at most one line of it and the ``--log`` file keeps its
+    full block; the message is the short cause. The error output of the Git process that failed travels with it too,
+    decoded once, so a refusal read from it names the same folders as everywhere else. It stays a ValueError, so every
+    handler of a failed initialization still catches it.
+    """
+
+    def __init__(self, diagnostic: PreparedDiagnostic, git_error_text: str) -> None:
+        """Keep the prepared diagnostic and Git's decoded error output, and give the short cause as the error message."""
+        self.diagnostic = diagnostic
+        self.git_error_text = git_error_text
+        super().__init__(diagnostic.cause)
+
+
+class SubmoduleService:
+    """Read native Git declarations through the shared bounded process service."""
+
+    def __init__(self, worktree: WorktreeService, repository_operation: RepositoryOperationService | None = None,
+                 authentication: AuthenticationService | None = None, ssh: SshService | None = None, log: DiagnosticLog | None = None) -> None:
+        """Inject the existing process scheduler for responsive discovery."""
+        self.worktree = worktree
+        self.repository_operation = repository_operation
+        self.authentication = authentication
+        self.ssh = ssh
+        self.log = log
+        self.run_by_id: dict[str, SubmoduleInitRun] = {}
+
+    def has_incomplete_initialization(self, repository_dir: str) -> bool:
+        """Use the latest actual attempt for a child while retaining its historical diagnostics."""
+        directory = canonical_path(repository_dir)
+        for run in reversed(self.run_by_id.values()):
+            if canonical_path(run.entry.repository_dir) != directory:
+                continue
+            # A refused preparation did not change the checkout and cannot replace
+            # the last native attempt's result, including a successful recovery.
+            if run.native_status is None and run.status not in ("preparing", "running"):
+                continue
+            return run.validation_status != OperationStatus.SUCCESS.value
+        return False
+
+    def initialize(self, context: RepositoryContext, git_filename: str, entry: SubmoduleEntry, callback: Callable[[SubmoduleInitRun], None],
+                   *, session_id: str, generation: int, is_current: Callable[[], bool]) -> SubmoduleInitRun:
+        """Initialize only a freshly verified declared child and retain ownership through reconciliation."""
+        operation_id = uuid.uuid4().hex
+        # The header names the parent that declares the submodule, the window's repository for a root entry. The
+        # initialization itself runs there and reaches the submodule through -C. The preparation reads run in the
+        # window's repository, so for a nested submodule their lines carry the "(in …)" suffix of another folder.
+        trace = OperationTrace(operation_id, self.worktree.runner, self.log, header=ConsoleHeader(REPOSITORY_HEADER_LABEL, entry.parent_dir or context.repository_dir))
+        run = SubmoduleInitRun(operation_id, entry, trace, session_id)
+        self.run_by_id[operation_id] = run
+
+        def complete(value: object, error: Exception | None) -> None:
+            """Publish a filtered terminal result after all reads and native descendants finish."""
+            if error is not None:
+                run.status = OperationStatus.CANCELLED.value if run.cancelled else OperationStatus.FAILED.value
+                if run.validation_status == "running":
+                    run.validation_status = OperationStatus.FAILED.value
+                # A Git process that failed, the initialization's own or a nested checkout's, keeps its prepared
+                # diagnostic, so the --log block names its command and its process; any other error keeps its cause.
+                if isinstance(error, (GitCommandError, SubmoduleInitializationError)):
+                    run.diagnostic = error.diagnostic
+                else:
+                    run.diagnostic = Diagnostic("Initialize submodule", entry.repository_dir, git_filename, [], str(error)).prepare()
+                if isinstance(error, SubmoduleInitializationError):
+                    run.git_error_text = error.git_error_text
+                if isinstance(error, CredentialManagerRefusal) and not run.cancelled:
+                    run.credential_manager_refusal = error.detection
+            publish_after_trace(publish)
+
+        def publish() -> None:
+            """Write the result in the console and the --log file, release the repositories, then hand the run back.
+
+            When Git refused a local submodule through its protocol.file.allow setting, or refused to check out a path of
+            a submodule, the cause is written once in plain words, after Git's own lines and before the end line.
+            """
+            # The run's state holds a finished operation's word by now; it is read as that end once, here.
+            end_status = OperationStatus(run.status)
+            if run.diagnostic is not None and file_transport_refused(run.git_error_text):
+                run.trace.append_failure_cause(operation_id, FILE_TRANSPORT_REFUSED_TEXT)
+            if run.diagnostic is not None and not run.refusal_explained:
+                # A cause is one console line, so each submodule whose checkout Git refused gets its own.
+                for refusal in checkout_refusals(run.git_error_text):
+                    run.trace.append_failure_cause(operation_id, checkout_refusal_text((refusal,), sys.platform))
+            run.trace.append_end_line(operation_id, "result", INITIALIZE_END_TEMPLATE.format(status=run.status, repository_dir=entry.repository_dir),
+                                      INITIALIZE_END_TEMPLATE.format(status=end_status.end_word, repository_dir=entry.repository_dir), end_status,
+                                      failure_reported=run.diagnostic is not None)
+            if run.diagnostic is not None:
+                # The credential manager was refused before Git started, so the line says the initialization did not
+                # start, as every other refused operation does; the run's own status stays failed.
+                run.trace.append_diagnostic(operation_id, "error", run.diagnostic, OperationStatus.REFUSED if run.credential_manager_refusal is not None else end_status)
+            if operation_id in self.repository_operation.active_by_id:
+                self.repository_operation.reconcile(OperationOutcome(operation_id, end_status, (OperationStepResult("Initialize submodule", end_status, after=run.snapshot,
+                                                                                                                   diagnostic=run.diagnostic, process_status=run.native_status,
+                                                                                                                   return_code=run.return_code),), run.diagnostic))
+            callback(run)
+
+        def prepared(value: object, error: Exception | None) -> None:
+            """Reserve before transport preparation and verify again immediately before launch.
+
+            A refused reservation takes the repository owner's reason, which names another operation only when a write
+            holds the parent or a submodule folder, and otherwise says why the application no longer allows the write.
+            """
+            if error is not None:
+                complete(None, error)
+                return
+            parent, expected_oid, known_contexts, configuration_filenames, inspected_dirs = value
+            owner = OperationIntent.capture(operation_id, parent, git_filename, session_id=session_id, generation=generation, operation="Initialize submodule",
+                                            reserved_repository_dirs=(canonical_path(entry.repository_dir),), reserved_contexts=known_contexts, action=OperationAction.SUBMODULE_INIT)
+            if not self.repository_operation.reserve(owner):
+                complete(None, ValueError(self.repository_operation.refusal_cause(owner)))
+                return
+            try:
+                signature = initialization_signature(parent, entry.repository_dir, configuration_filenames, inspected_dirs)
+                run.intent = SubmoduleInitIntent(owner, os.fsencode(entry.path), expected_oid, entry.repository_dir, signature, configuration_filenames, inspected_dirs)
+            except (OSError, ValueError) as failure:
+                complete(None, failure)
+                return
+            self.worktree.run(parent, git_filename, self._initialize_then_cloned_children(run, is_current), complete, operation_id=operation_id)
+
+        self.worktree.run(context, git_filename, self._prepare_initialization(entry), prepared)
+        return run
+
+    def _initialize_then_cloned_children(self, run: SubmoduleInitRun, is_current: Callable[[], bool]) -> Generator:
+        """Initialize the submodule, then check out the nested submodules Git cloned but left without files after a refused checkout.
+
+        Git clones every nested submodule before checking them out, and stops at the first checkout it refuses on a file
+        name: the nested submodules after that one are cloned but never checked out. They are checked out here, one at a
+        time, inside the initialized submodule only; those whose checkout Git refused on a file name, even one cut by a
+        line break, are left exactly as Git left them. The sentence of each refusal whose path Git could cite is written
+        first, right after Git's own lines. A checkout that failed for another reason starts nothing here: the
+        initialization stays failed and opening the submodule again takes it up.
+        """
+        credential_helper = OperationCredentialHelper()
+        yield from self._initialize(run, is_current, credential_helper=credential_helper)
+        if run.cancelled or run.diagnostic is None or not is_current():
+            return
+        refused_paths = refused_checkout_submodule_paths(run.git_error_text)
+        if not refused_paths:
+            return
+        for refusal in checkout_refusals(run.git_error_text):
+            run.trace.append_failure_cause(run.operation_id, checkout_refusal_text((refusal,), sys.platform))
+        run.refusal_explained = True
+        owner = run.intent.operation
+        refused_dir_set = set(refused_submodule_dirs(refused_paths, owner.context.repository_dir))
+        run.snapshot = yield from self.resume_missing(owner, run.trace, is_current, credential_helper=credential_helper, refused_dir_set=refused_dir_set,
+                                                      initialize_missing=False, scope_dir=run.entry.repository_dir, retry_wording=False)
+
+    def cancel(self, operation_id: str) -> None:
+        """Stop supervised native work without releasing ownership before reconciliation."""
+        run = self.run_by_id.get(operation_id)
+        if run is None or run.validation_status in (OperationStatus.SUCCESS.value, OperationStatus.PARTIAL.value) or run.status not in ("preparing", "running", OperationStatus.SUCCESS.value):
+            return
+        run.cancelled = True
+        self.worktree.runner.cancel(operation_id)
+
+    def _context(self, directory: str) -> Generator:
+        """Read actual Git identities instead of inferring them from directory proximity.
+
+        One process answers the three locations of an ordinary repository. Output that does not split into three
+        absolute locations starting with this exact root is read again one location at a time, so a line break
+        inside a path can never move a boundary between two answers.
+        """
+        location_arguments = ("--show-toplevel", "--absolute-git-dir", "--git-common-dir")
+        root_position = 0
+        output = yield GitCommand(["-C", directory, "rev-parse", "--path-format=absolute", "--show-toplevel", "--absolute-git-dir", "--git-common-dir"])
+        values = os.fsdecode(output.removesuffix(b"\n")).split("\n")
+        grouped = (len(values) == len(location_arguments) and all(os.path.isabs(value) for value in values)
+                   and canonical_path(values[root_position]) == canonical_path(directory))
+        if not grouped:
+            values = []
+            for argument in location_arguments:
+                output = yield GitCommand(["-C", directory, "rev-parse", "--path-format=absolute", argument])
+                values.append(os.fsdecode(output).rstrip("\r\n"))
+        root_dir, git_dir, common_dir = values
+        if canonical_path(root_dir) != canonical_path(directory):
+            raise ValueError("Repository does not resolve to its declared worktree")
+        return RepositoryContext(directory, git_dir, common_dir, False)
+
+    def _prepare_initialization(self, entry: SubmoduleEntry, *, cloned_without_checkout: bool = False) -> Generator:
+        """Reject occupied paths, conflicting gitlinks and existing divergent checkouts before update.
+
+        With ``cloned_without_checkout``, the submodule itself is one Git cloned but never checked out: its HEAD is still
+        the clone's default branch, which may differ from the recorded commit, and that is not a checkout to keep, since
+        its folder holds no file. Its nested submodules, if any, are still checked like any other.
+        """
+        if entry.parent_dir is None:
+            raise ValueError("No parent declares this submodule")
+        child_dir = declared_directory(entry.parent_dir, entry.path)
+        parent = yield from self._context(entry.parent_dir)
+        section_by_path, stage_by_path = yield from self._read_declarations(entry.parent_dir)
+        stages = stage_by_path.get(entry.path, [])
+        if section_by_path.get(entry.path) != entry.section or len(stages) != 1:
+            raise ValueError("The submodule declaration or index changed. Refresh the repository and retry.")
+        mode, expected_oid, stage = next(iter(stages))
+        if mode != "160000" or stage != "0":
+            raise ValueError("The submodule index has unresolved stages or no gitlink.")
+        initialization_signature(parent, child_dir)
+        known_contexts = []
+        inspected_dirs = []
+        if os.path.lexists(os.path.join(child_dir, ".git")):
+            family = yield from self._read(child_dir)
+            if family.cause:
+                raise ValueError(family.cause)
+            for child in family.entries:
+                if not child.repository_dir or not self._inside(child_dir, child.repository_dir):
+                    continue
+                inspected_dirs.append(child.repository_dir)
+                if child.availability == "not initialized":
+                    continue
+                if child.availability != "initialized":
+                    raise ValueError(child.cause or "The submodule path cannot be initialized safely.")
+                child_context = yield from self._context(child.repository_dir)
+                known_contexts.append(child_context)
+                if cloned_without_checkout and canonical_path(child.repository_dir) == canonical_path(child_dir):
+                    continue
+                reference = yield from self._read_reference_state(child.parent_dir, os.fsencode(child.path))
+                if reference.checkout_oid != reference.indexed_oid:
+                    raise ValueError("An existing submodule checkout differs from its parent index. Existing work was preserved.")
+        configuration_filename_set: set[str] = set()
+        for context in (parent, *known_contexts):
+            output = yield GitCommand(["-C", context.repository_dir, "config", "--includes", "--show-origin", "--name-only", "--null", "--list"])
+            fields = iter(output.split(b"\0"))
+            for origin in fields:
+                if not origin:
+                    continue
+                next(fields, None)
+                if origin.startswith(b"file:"):
+                    filename = os.fsdecode(origin.removeprefix(b"file:"))
+                    if not os.path.isabs(filename):
+                        filename = os.path.join(context.repository_dir, filename)
+                    configuration_filename_set.add(os.path.abspath(filename))
+            configuration_filename_set.add(os.path.join(context.repository_dir, ".gitmodules"))
+            configuration_filename_set.add(os.path.join(context.git_dir, "index"))
+            configuration_filename_set.add(os.path.join(context.repository_dir, ".git"))
+            configuration_filename_set.add(os.path.join(context.git_dir, "HEAD"))
+            configuration_filename_set.add(os.path.join(context.common_git_dir, "packed-refs"))
+            head_reference = yield GitCommand(["-C", context.repository_dir, "symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            if head_reference.strip():
+                configuration_filename_set.add(declared_directory(context.common_git_dir, os.fsdecode(head_reference).strip()))
+            output = yield GitCommand(["-C", context.repository_dir, "config", "--includes", "--show-origin", "--null", "--get-regexp", r"^include(if\..*)?\.path$"], accepted_codes=(0, 1))
+            fields = iter(output.split(b"\0"))
+            for origin in fields:
+                if not origin:
+                    continue
+                record = next(fields)
+                _key, value = record.split(b"\n", 1)
+                filename = os.path.expanduser(os.fsdecode(value))
+                if not os.path.isabs(filename) and origin.startswith(b"file:"):
+                    source_filename = os.fsdecode(origin.removeprefix(b"file:"))
+                    filename = os.path.join(context.repository_dir, os.path.dirname(source_filename), filename)
+                if os.path.isabs(filename):
+                    configuration_filename_set.add(os.path.abspath(filename))
+        return parent, validate_oid(expected_oid), tuple(known_contexts), tuple(sorted(configuration_filename_set)), tuple(inspected_dirs)
+
+    def _inside(self, root_dir: str, directory: str) -> bool:
+        """Compare path boundaries without accepting similarly prefixed sibling folders."""
+        return os.path.commonpath((canonical_path(root_dir), canonical_path(directory))) == canonical_path(root_dir)
+
+    def authentication_target(self, context: RepositoryContext, diagnostic: str) -> Generator:
+        """Identify an HTTPS child from native declarations and the reported authentication refusal.
+
+        Besides plain refusals, Git's words for credentials nobody gave count, and so does a repository the server says
+        does not exist: GitHub answers that way for a private repository the account used cannot see, so another
+        account is offered. A submodule URL that is really wrong is offered an account too; its retry fails the same way.
+        """
+        lowered = diagnostic.lower()
+        refused = any(word in lowered for word in ("authentication", "credential", "401", "403"))
+        if not refused and CREDENTIALS_MISSING_PATTERN.search(diagnostic) is None and not repository_not_found(git_output_lines(diagnostic)):
+            return None
+        snapshot = yield from self._read(context.repository_dir)
+        targets = []
+        for entry in snapshot.entries:
+            if entry.availability != "not initialized" or entry.parent_dir is None:
+                continue
+            parent = yield from self._context(entry.parent_dir)
+            endpoint_raw = yield GitCommand(["-C", entry.parent_dir, "config", "--get", "submodule." + entry.section + ".url"], accepted_codes=(0, 1))
+            endpoint = endpoint_raw.decode("utf-8", "replace").strip()
+            if not endpoint.startswith("https://"):
+                continue
+            resolved_raw = yield GitCommand(["-C", entry.parent_dir, "ls-remote", "--get-url", "--", endpoint])
+            endpoint = resolved_raw.decode("utf-8", "replace").strip()
+            target = SubmoduleAuthenticationTarget(entry, endpoint, parent, initialization_signature(parent, entry.repository_dir))
+            if endpoint in diagnostic:
+                return target
+            targets.append(target)
+        return next(iter(targets)) if len(targets) == 1 else None
+
+    def resume_missing(self, owner: OperationIntent, trace: OperationTrace, is_current: Callable[[], bool], destinations: tuple = (), *,
+                       credential_helper: OperationCredentialHelper | None = None, refused_dir_set: set[str] | None = None, initialize_missing: bool = True,
+                       scope_dir: str | None = None, retry_wording: bool = True) -> Generator:
+        """Reread the family, then initialize its missing children one at a time under an already reserved owner; return the last read.
+
+        Every child shares ``credential_helper``: the credential manager is searched at most once for the whole operation.
+
+        With ``refused_dir_set``, the children Git cloned but never checked out, because it stopped on a refused checkout
+        before them, are checked out too, except the folders in that set: Git refused their checkout on a file name, and
+        would refuse it again. A child of that kind whose checkout Git refuses in turn on a file name, even one cut by a
+        line break, gets its sentence when Git could cite the refused path, one console line per refused submodule, its
+        folder joins the set and the next child follows. Any other failure, such as a locked index or a name too long for
+        the file system, stops here with the diagnostic of its Git process, and the folder stays out of the set so that a
+        later retry checks it out again. A child that only looks like one (a file in its folder, an index) is never written.
+        ``initialize_missing`` set to False leaves the children never cloned alone, and ``scope_dir`` limits the work to
+        the children inside that folder.
+        ``retry_wording`` picks which action the causes of a failure name: Retry submodules, or opening the submodule again.
+        """
+        if credential_helper is None:
+            credential_helper = OperationCredentialHelper()
+        attempted_dir_set: set[str] = set()
+        while True:
+            if not is_current():
+                raise ValueError("Submodule retry was cancelled. Existing files were preserved.")
+            snapshot = yield from self._read(owner.context.repository_dir)
+            if snapshot.cause:
+                raise ValueError(snapshot.cause)
+            missing = None
+            cloned_without_checkout = False
+            for entry in snapshot.entries:
+                if scope_dir is not None and (not entry.repository_dir or not self._inside(scope_dir, entry.repository_dir)):
+                    continue
+                if entry.availability == "not initialized":
+                    if not initialize_missing:
+                        continue
+                    missing = entry
+                    break
+                if entry.availability != "initialized":
+                    raise ValueError(entry.cause or "Submodule state could not be read.")
+                if refused_dir_set is None or entry.parent_dir is None:
+                    continue
+                directory = canonical_path(entry.repository_dir)
+                if directory in refused_dir_set or directory in attempted_dir_set or not is_cloned_without_checkout(entry.repository_dir):
+                    continue
+                attempted_dir_set.add(directory)
+                missing = entry
+                cloned_without_checkout = True
+                break
+            if missing is None:
+                return snapshot
+            parent, expected_oid, _known_contexts, configuration_filenames, inspected_dirs = yield from self._prepare_initialization(
+                missing, cloned_without_checkout=cloned_without_checkout)
+            operation = OperationIntent.capture(owner.operation_id, parent, owner.git_filename, session_id=owner.session_id, generation=owner.generation,
+                                                  capability=owner.capability, operation=owner.operation, action=OperationAction.SUBMODULE_INIT)
+            signature = initialization_signature(parent, missing.repository_dir, configuration_filenames, inspected_dirs)
+            run = SubmoduleInitRun(owner.operation_id, missing, trace, owner.session_id)
+            run.intent = SubmoduleInitIntent(operation, os.fsencode(missing.path), expected_oid, missing.repository_dir, signature, configuration_filenames, inspected_dirs,
+                                             cloned_without_checkout)
+            yield from self._initialize(run, is_current, owner, destinations, credential_helper=credential_helper, retry_wording=retry_wording)
+            if run.status == OperationStatus.SUCCESS.value and run.validation_status == OperationStatus.SUCCESS.value:
+                continue
+            error_text = run.git_error_text if run.diagnostic is not None and not run.cancelled else ""
+            refused_paths = refused_checkout_submodule_paths(error_text)
+            if refused_dir_set is not None:
+                refused_dir_set.update(refused_submodule_dirs(refused_paths, parent.repository_dir))
+            if cloned_without_checkout and refused_paths:
+                # Git's lines are already in the console: the reads that ended the initialization ran after its process.
+                for refusal in checkout_refusals(error_text):
+                    trace.append_failure_cause(owner.operation_id, checkout_refusal_text((refusal,), sys.platform))
+                continue
+            if run.diagnostic is not None:
+                raise SubmoduleInitializationError(run.diagnostic, run.git_error_text)
+            raise ValueError(INITIALIZE_INCOMPLETE_START + (RETRY_AGAIN_SENTENCE if retry_wording else OPEN_AGAIN_RETRY_SENTENCE))
+
+    def _initialize(self, run: SubmoduleInitRun, is_current: Callable[[], bool], external_owner: OperationIntent | None = None, selected_destinations: tuple = (), *,
+                    credential_helper: OperationCredentialHelper | None = None, retry_wording: bool | None = None) -> Generator:
+        """Use Git's recursive checkout and reconcile even failed or interrupted partial results.
+
+        The reservation is first extended to the parent and the submodules already there; a refused extension says why,
+        naming another operation only when a write really holds one of them. When a destination has an account and the
+        operation's ``credential_helper`` is still empty, the credential manager is searched here, in the background,
+        and kept there for the following children. ``retry_wording`` says whether the causes name Retry submodules; by
+        default they do when another owner holds the work, as a retry from the clone form does.
+
+        A submodule Git cloned but never checked out is checked out with ``--force``, since Git would skip one whose HEAD
+        already names the recorded commit; right before Git starts, its folder must still hold nothing but its ``.git``
+        file, and its Git folder no index.
+        """
+        if credential_helper is None:
+            credential_helper = OperationCredentialHelper()
+        if retry_wording is None:
+            retry_wording = external_owner is not None
+        # A retry started from the clone form names its own button: the submodule cannot be opened from there.
+        if retry_wording:
+            interrupted_ending, failed_ending, retry_sentence = RETRY_INTERRUPTED_ENDING, RETRY_FAILED_ENDING, RETRY_AGAIN_SENTENCE
+        else:
+            interrupted_ending, failed_ending, retry_sentence = OPEN_AGAIN_INTERRUPTED_ENDING, OPEN_AGAIN_FAILED_ENDING, OPEN_AGAIN_RETRY_SENTENCE
+        intent = run.intent
+        parent = intent.operation.context
+        parent_again, expected_oid, known_contexts, configuration_filenames, inspected_dirs = yield from self._prepare_initialization(
+            run.entry, cloned_without_checkout=intent.cloned_without_checkout)
+        if parent_again != parent or expected_oid != intent.expected_oid or configuration_filenames != intent.configuration_filenames or inspected_dirs != intent.inspected_dirs:
+            raise ValueError("The parent repository or indexed submodule changed. Refresh and retry.")
+        owner = external_owner or intent.operation
+        active_owner = self.repository_operation.active_by_id[owner.operation_id]
+        extended_owner = replace(owner, reserved_contexts=(*active_owner.reserved_contexts, parent, *known_contexts))
+        if not self.repository_operation.extend(extended_owner):
+            # The submodules reached now can be refused by their own state, a paused rebase for example, as well as by a write holding them.
+            raise ValueError(self.repository_operation.refusal_cause(extended_owner))
+        repository_dirs = (parent.repository_dir, *(context.repository_dir for context in known_contexts))
+        inherited_keys = yield from self.authentication.recursive_inherited_keys(repository_dirs)
+        destinations = list(self.authentication.recursive_context())
+        from gitpane.account.authentication import PREVIEW_HELPER_COMMANDS, RecursiveTransportContext, endpoint_origin, helper_after_refusal
+
+        parent_uses_account = False
+        for context in (parent, *known_contexts):
+            endpoint_raw = yield GitCommand(["-C", context.repository_dir, "remote", "get-url", "origin"], accepted_codes=(0, 2))
+            endpoint = endpoint_raw.decode("utf-8", "replace").strip()
+            if endpoint.startswith("https://"):
+                selection = self.authentication.account_for_endpoint(endpoint, context)
+                destinations.append(RecursiveTransportContext(endpoint, endpoint_origin(endpoint), selection, context))
+                if context is parent and selection is not None:
+                    parent_uses_account = True
+        destinations.extend(selected_destinations)
+        # An account chosen for this operation itself, such as the account the user picked for a refused submodule
+        # before Retry submodules, commits it as much as the parent's own account, so a refused credential manager
+        # stops it on its sentence instead of letting Git run without any helper. Only the operation's own choices
+        # count: the service defaults in ``destinations`` are kept for other submodules and never block it.
+        operation_uses_account = parent_uses_account
+        for selected_destination in selected_destinations:
+            if selected_destination.selection is not None:
+                operation_uses_account = True
+        if credential_helper.commands is None and any(destination.selection is not None for destination in destinations):
+            git_filename = intent.operation.git_filename
+            try:
+                helper = yield FileTask(lambda: self.authentication.credential_helper(git_filename))
+                credential_helper.commands = helper.commands
+            except ValueError as refusal:
+                credential_helper.commands = helper_after_refusal(refusal, operation_uses_account=operation_uses_account, log=self.log)
+        helper_commands = credential_helper.commands if credential_helper.commands is not None else PREVIEW_HELPER_COMMANDS
+        arguments = self.authentication.recursive_configuration(tuple(destinations), inherited_keys, helper_commands=helper_commands)
+        environment_by_name = {}
+        if self.ssh.configuration().ssh_filename:
+            ssh_arguments, environment_by_name = self.ssh.command_configuration()
+            arguments.extend(ssh_arguments)
+
+        def before_start() -> None:
+            """Recheck queued filesystem identity and authority immediately before native writes."""
+            current_owner = self.repository_operation.active_by_id.get(owner.operation_id)
+            if current_owner is None:
+                raise ValueError("Submodule initialization no longer owns its repositories")
+            self.repository_operation.validate(current_owner)
+            if run.cancelled or not is_current():
+                raise ValueError(INITIALIZE_INTERRUPTED_KEPT_START + retry_sentence)
+            if initialization_signature(parent, intent.repository_dir, configuration_filenames, inspected_dirs) != intent.signature:
+                raise ValueError("The parent configuration, index or submodule path changed. Refresh and retry.")
+            # The forced checkout may only ever write into a folder that still holds no file of anyone.
+            if intent.cloned_without_checkout and not is_cloned_without_checkout(intent.repository_dir):
+                raise ValueError(SharedText.CLONED_SUBMODULE_CHANGED.value.format(submodule=run.entry.path))
+            self.authentication.recursive_configuration(tuple(destinations), inherited_keys, helper_commands=helper_commands)
+
+        # The launcher runs before_start when the process really starts, after any wait in its queue; checking here
+        # as well would only compute the same signature once more, before the moment that matters.
+        # No protocol.file.allow is added: 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 when the initialization ends.
+        update_arguments = SUBMODULE_CLONED_CHECKOUT_ARGUMENTS if intent.cloned_without_checkout else SUBMODULE_INIT_ARGUMENTS
+        request = ProcessRequest(run.operation_id, intent.operation.git_filename,
+                                 ["--literal-pathspecs", "-C", parent.repository_dir, *arguments, *update_arguments,
+                                  os.fsdecode(intent.path)],
+                                 parent.repository_dir, GIT_CLONE_TIMEOUT_MS, session_id=intent.operation.session_id, idle_timeout_ms=GIT_TRANSPORT_TIMEOUT_MS,
+                                 environment_by_name=environment_by_name, operation="Initialize submodule", profile=NETWORK_PROFILE, operation_id=run.operation_id, before_start=before_start)
+        request = self.ssh.prompt(request, context=owner.context, generation=owner.generation, is_current=lambda: not run.cancelled and is_current())
+        run.status = "running"
+        # The existing scheduler resumes this sequence only after native descendants drain.
+        result = yield request
+        run.native_status = result.status
+        run.return_code = result.return_code
+        run.git_error_text = git_error_text(result.stderr)
+        run.status = OperationStatus.CANCELLED.value if run.cancelled else operation_status(result.status).value
+        if result.status != ProcessStatus.SUCCESS:
+            # A refusal of the launch check carries its own reason (a changed index, configuration or owner); it is the
+            # useful explanation, since Git never ran and wrote nothing to its error output.
+            refusal = result.cause if result.status == ProcessStatus.START_FAILED else ""
+            cause = INITIALIZE_INTERRUPTED_START + interrupted_ending if run.cancelled else refusal or INITIALIZE_FAILED_START + failed_ending
+            run.diagnostic = Diagnostic("Initialize submodule", intent.repository_dir, request.program_filename, request.arguments, cause,
+                                        result.stderr, result.return_code, process_id=request.request_id).prepare()
+        run.validation_status = "running"
+        declared_directory(parent.repository_dir, os.fsdecode(intent.path))
+        if (yield from self._context(parent.repository_dir)) != parent:
+            raise ValueError("The parent repository identity changed during initialization.")
+        run.snapshot = yield from self._read(parent.repository_dir)
+        if result.status != ProcessStatus.SUCCESS or run.cancelled:
+            run.validation_status = OperationStatus.PARTIAL.value
+            return
+        section_by_path, stage_by_path = yield from self._read_declarations(parent.repository_dir)
+        if section_by_path.get(os.fsdecode(intent.path)) != run.entry.section or stage_by_path.get(os.fsdecode(intent.path)) != [("160000", intent.expected_oid, "0")]:
+            raise ValueError("The parent declaration or indexed submodule changed during initialization.")
+        child_context = yield from self._context(intent.repository_dir)
+        output = yield GitCommand(["-C", child_context.repository_dir, "rev-parse", "HEAD"])
+        if output.decode().strip() != intent.expected_oid:
+            raise ValueError("The initialized submodule does not match the captured parent index.")
+        output = yield GitCommand(["-C", parent.repository_dir, "submodule", "status", "--recursive", "--", os.fsdecode(intent.path)])
+        if not output or any(not line.startswith(b" ") for line in output.splitlines()):
+            raise ValueError(INITIALIZE_INCOMPLETE_START + retry_sentence)
+        if run.snapshot.cause or any(child.availability != "initialized" for child in run.snapshot.entries if child.repository_dir and self._inside(intent.repository_dir, child.repository_dir)):
+            raise ValueError("Submodule validation is incomplete. Existing files were preserved.")
+        run.validation_status = OperationStatus.SUCCESS.value
+        if run.cancelled or not is_current():
+            run.status = OperationStatus.CANCELLED.value
+
+    def read(self, context: RepositoryContext, git_filename: str, callback: Callable[[SubmoduleSnapshot | None, Exception | None], None], root_dir: str | None = None) -> None:
+        """Discover an entire initialized family without changing any checkout."""
+        self.worktree.run(context, git_filename, self._read(root_dir or context.repository_dir), callback)
+
+    def read_reference_state(self, context: RepositoryContext, git_filename: str, path: bytes, callback: Callable[[SubmoduleReferenceState | None, Exception | None], None],
+                             *, parent_dir: str | None = None) -> None:
+        """Read the three sources from either the parent view or a child with a verified parent."""
+        self.worktree.run(context, git_filename, self._validated_reference(parent_dir or context.repository_dir, path), callback)
+
+    def _validated_reference(self, parent_dir: str, path: bytes) -> Generator:
+        """Reject a reference capture when its sources change during observation."""
+        reference = yield from self._read_reference_state(parent_dir, path)
+        if reference != (yield from self._read_reference_state(parent_dir, path)):
+            raise ValueError("The submodule changed since it was read. Refresh the repository and review it before staging again.")
+        return reference
+
+    def _read_reference_state(self, parent_dir: str, path: bytes) -> Generator:
+        """Read exact gitlinks and child identity independently, preserving unavailable facts."""
+        child_dir = declared_directory(parent_dir, os.fsdecode(path))
+        causes: list[str] = []
+        parent_head_oid = committed_oid = indexed_oid = checkout_oid = None
+        committed_availability = indexed_availability = checkout_availability = "Unavailable"
+        state = SubmoduleState()
+        internal_changes = None
+        try:
+            raw_head = yield summary_command(parent_dir, ["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            parent_head_oid = validate_oid(raw_head.decode().strip()) if raw_head.strip() else None
+            committed_availability = "Parent has no commit" if parent_head_oid is None else "No committed gitlink"
+            if parent_head_oid is not None:
+                output = yield summary_command(parent_dir, ["ls-tree", "-z", parent_head_oid, "--", os.fsdecode(path)])
+                for entry in parse_tree_entries(output):
+                    if entry.path == path and entry.mode == "160000":
+                        committed_oid, committed_availability = entry.oid, "Available"
+        except (ValueError, RuntimeError, OSError) as error:
+            committed_availability = "Unavailable"
+            causes.append(str(error))
+        try:
+            output = yield summary_command(parent_dir, ["ls-files", "--stage", "-z", "--", os.fsdecode(path)])
+            indexed_availability = "No indexed gitlink"
+            for record in output.split(b"\0"):
+                if not record:
+                    continue
+                metadata, raw_path = record.split(b"\t", 1)
+                mode, oid, stage = metadata.decode().split()
+                if raw_path != path:
+                    continue
+                if stage != "0":
+                    raise ValueError("The submodule index has unresolved stages")
+                if mode == "160000":
+                    indexed_oid, indexed_availability = validate_oid(oid), "Available"
+        except (ValueError, RuntimeError, OSError) as error:
+            indexed_oid, indexed_availability = None, "Unavailable"
+            causes.append(str(error))
+        try:
+            output = yield summary_command(child_dir, ["rev-parse", "--show-toplevel"])
+            if canonical_path(os.fsdecode(output).rstrip("\r\n")) != canonical_path(child_dir):
+                raise ValueError("Submodule does not resolve to its declared worktree")
+            output = yield summary_command(child_dir, ["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            checkout_oid = validate_oid(output.decode().strip()) if output.strip() else None
+            checkout_availability = "Available" if checkout_oid else "Child has no commit"
+            output = yield summary_command(child_dir, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignore-submodules=none"])
+            internal_changes = parse_internal_status(output)
+            tracked_changed = untracked_changed = False
+            for change in internal_changes:
+                if change.status == "??":
+                    untracked_changed = True
+                else:
+                    tracked_changed = True
+            state = SubmoduleState(None if checkout_oid is None or indexed_oid is None else checkout_oid != indexed_oid, tracked_changed, untracked_changed)
+        except (ValueError, RuntimeError, OSError) as error:
+            causes.append(str(error))
+        return SubmoduleReferenceState(parent_dir, path, child_dir, parent_head_oid, committed_oid, indexed_oid, checkout_oid,
+                                       committed_availability, indexed_availability, checkout_availability, state, "\n".join(causes), internal_changes)
+
+    def compare(self, context: RepositoryContext, git_filename: str, entry: LocalEntry, callback: Callable[[SubmoduleSummary | None, Exception | None], None]) -> None:
+        """Compare the selected side in the verified child and reject changed sources."""
+        self.worktree.run(context, git_filename, self._compare(context.repository_dir, entry.path, entry.side), callback)
+
+    def _commit(self, directory: str, oid: str | None) -> Generator:
+        """Read the real subject and author date without losing an unavailable hash."""
+        if oid is None:
+            return SubmoduleCommit(None)
+        output = yield summary_command(directory, ["show", "--no-patch", "--no-notes", "--format=%at%x00%s", oid, "--"])
+        timestamp, subject = output.removesuffix(b"\n").split(b"\0", 1)
+        return SubmoduleCommit(oid, int(timestamp), subject.decode("utf-8", "replace"))
+
+    def _ancestor(self, directory: str, source_oid: str, target_oid: str) -> Generator:
+        """Distinguish a negative ancestry answer from a failed Git read."""
+        try:
+            yield summary_command(directory, ["merge-base", "--is-ancestor", source_oid, target_oid])
+        except GitCommandError as error:
+            if error.return_code == 1 and error.process_status == ProcessStatus.FAILED:
+                return False
+            raise
+        return True
+
+    def _commit_count(self, directory: str, source_oid: str, target_oid: str) -> Generator:
+        """Keep the established total independent of bounded metadata retrieval."""
+        output = yield summary_command(directory, ["rev-list", "--count", source_oid + ".." + target_oid, "--"])
+        return int(output.strip())
+
+    def _commits(self, directory: str, source_oid: str, target_oid: str) -> Generator:
+        """List a bounded prefix without treating its length as the total history."""
+        revision = source_oid + ".." + target_oid
+        output = yield summary_command(directory, ["log", "--no-notes", "--format=%H%x00%at%x00%s%x00", "--max-count=" + str(SUBMODULE_SUMMARY_COMMIT_LIMIT), revision, "--"])
+        commits: list[SubmoduleCommit] = []
+        fields = output.split(b"\0")
+        field_count = 3
+        for offset in range(0, len(fields) - 1, field_count):
+            oid, timestamp, subject = fields[offset:offset + field_count]
+            commits.append(SubmoduleCommit(validate_oid(oid.strip().decode()), int(timestamp), subject.decode("utf-8", "replace")))
+        return tuple(commits)
+
+    def _relation(self, directory: str, source_oid: str, target_oid: str) -> Generator:
+        """Only negative ancestry in a complete repository can establish unrelated history."""
+        if source_oid == target_oid:
+            return "Unchanged", False
+        output = yield summary_command(directory, ["rev-parse", "--is-shallow-repository"])
+        shallow = output.strip() == b"true"
+        if (yield from self._ancestor(directory, source_oid, target_oid)):
+            return "Fast Forward", shallow
+        if (yield from self._ancestor(directory, target_oid, source_oid)):
+            return "Rewind", shallow
+        common = yield summary_command(directory, ["merge-base", source_oid, target_oid], accepted_codes=(0, 1))
+        if shallow:
+            return "Unavailable", True
+        return ("Diverged" if common.strip() else "Unrelated histories"), False
+
+    def _differences(self, directory: str, source_oid: str, target_oid: str) -> Generator:
+        """Preserve NUL-delimited filenames and explicit rename pairs."""
+        output = yield summary_command(directory, ["diff", "--name-status", "-z", "--find-renames", "--no-ext-diff", "--no-textconv", "--no-color", source_oid, target_oid, "--"])
+        fields = iter(output.split(b"\0"))
+        differences: list[SubmoduleDifference] = []
+        truncated = False
+        for raw_status in fields:
+            if not raw_status:
+                break
+            status = raw_status.decode("ascii")
+            path = next(fields)
+            old_path = None
+            if status.startswith(("R", "C")):
+                old_path, path = path, next(fields)
+            if len(differences) < SUBMODULE_SUMMARY_DIFFERENCE_LIMIT:
+                differences.append(SubmoduleDifference(status, path, old_path))
+            else:
+                truncated = True
+        return tuple(differences), truncated
+
+    def _compare(self, parent_dir: str, path: bytes, side: StagingSide) -> Generator:
+        """Build facts between immutable commits and recheck all mutable sources at the end."""
+        if side not in (StagingSide.STAGED, StagingSide.UNSTAGED):
+            raise ValueError("Unknown comparison side")
+        reference = yield from self._read_reference_state(parent_dir, path)
+        source_oid, target_oid = (reference.committed_oid, reference.indexed_oid) if side == StagingSide.STAGED else (reference.indexed_oid, reference.checkout_oid)
+        directory = reference.repository_dir
+        causes = [reference.cause] if reference.cause else []
+        relation = "Unavailable"
+        counts: list[int | None] = [None, None]
+        commit_lists: list[tuple[SubmoduleCommit, ...]] = [(), ()]
+        endpoint_commits: list[SubmoduleCommit] = []
+        differences, truncated = None, False
+        child_available = reference.checkout_availability != "Unavailable"
+        for oid in (source_oid, target_oid):
+            commit = SubmoduleCommit(oid)
+            if child_available:
+                try:
+                    commit = yield from self._commit(directory, oid)
+                except (ValueError, RuntimeError, OSError) as error:
+                    causes.append(str(error))
+            endpoint_commits.append(commit)
+        if child_available and source_oid and target_oid:
+            shallow = True
+            try:
+                relation, shallow = yield from self._relation(directory, source_oid, target_oid)
+                if shallow:
+                    causes.append("History is shallow; complete added and removed commit counts are unavailable.")
+            except (ValueError, RuntimeError, OSError) as error:
+                causes.append(str(error))
+            if not shallow:
+                for position, (old_oid, new_oid) in enumerate(((source_oid, target_oid), (target_oid, source_oid))):
+                    try:
+                        counts[position] = yield from self._commit_count(directory, old_oid, new_oid)
+                        commit_lists[position] = yield from self._commits(directory, old_oid, new_oid)
+                    except (ValueError, RuntimeError, OSError) as error:
+                        causes.append(str(error))
+            try:
+                differences, truncated = yield from self._differences(directory, source_oid, target_oid)
+            except (ValueError, RuntimeError, OSError) as error:
+                causes.append(str(error))
+        if reference != (yield from self._read_reference_state(parent_dir, path)):
+            raise ValueError("The submodule changed since it was read. Refresh the repository and review it before staging again.")
+        source, target = endpoint_commits
+        added_count, removed_count = counts
+        added_commits, removed_commits = commit_lists
+        return SubmoduleSummary(reference, side, source, target, relation, added_count, removed_count, added_commits, removed_commits, differences, truncated, "\n".join(causes))
+
+    def _read_declarations(self, directory: str) -> Generator:
+        """Join declarations with all index stages while rejecting ambiguous paths."""
+        modules_filename = os.path.join(directory, ".gitmodules")
+        if not os.path.lexists(modules_filename):
+            return {}, {}
+        if os.path.islink(modules_filename) or not os.path.isfile(modules_filename):
+            raise ValueError("Invalid .gitmodules file")
+        declarations = yield GitCommand(["-C", directory, "config", "--null", "--file", modules_filename, "--get-regexp", r"^submodule\..*\.path$"], accepted_codes=(0, 1))
+        index = yield GitCommand(["-C", directory, "ls-files", "--stage", "-z"])
+        stage_by_path: dict[str, list[tuple[str, str, str]]] = {}
+        section_by_path: dict[str, str] = {}
+        for record in index.split(b"\0"):
+            if record:
+                metadata, raw_path = record.split(b"\t", 1)
+                mode, oid, stage = metadata.decode().split()
+                stage_by_path.setdefault(os.fsdecode(raw_path), []).append((mode, oid, stage))
+        for declaration in declarations.split(b"\0"):
+            if declaration:
+                key, raw_path = declaration.split(b"\n", 1)
+                path = os.fsdecode(raw_path)
+                if path in section_by_path:
+                    raise ValueError("Duplicate submodule path declaration")
+                section_by_path[path] = key.decode("utf-8", "replace").removeprefix("submodule.").removesuffix(".path")
+        return section_by_path, stage_by_path
+
+    def _root_and_parent(self, directory: str, verified_directory_set: set[str]) -> Generator:
+        """Prove a repository's own root and name its native parent, in one process when the output is unambiguous.
+
+        A directory whose root Git confirms is added to the caller's set of proven roots. Output that does not split
+        into one or two absolute paths starting with this exact root is read again one question at a time, so a line
+        break inside a path can never turn part of a path into a parent.
+        """
+        root_position, parent_position = 0, 1
+        lone_field_count, parent_field_count = 1, 2
+        output = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel", "--show-superproject-working-tree"])
+        fields = os.fsdecode(output.removesuffix(b"\n")).split("\n")
+        if (len(fields) in (lone_field_count, parent_field_count) and all(os.path.isabs(field) for field in fields)
+                and canonical_path(fields[root_position]) == canonical_path(directory)):
+            verified_directory_set.add(canonical_path(directory))
+            return fields[parent_position] if len(fields) == parent_field_count else ""
+        root_raw = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel"])
+        if canonical_path(os.fsdecode(root_raw).rstrip("\r\n")) == canonical_path(directory):
+            verified_directory_set.add(canonical_path(directory))
+        parent_raw = yield GitCommand(["-C", directory, "rev-parse", "--show-superproject-working-tree"])
+        return os.fsdecode(parent_raw).rstrip("\r\n")
+
+    def _find_root(self, directory: str, verified_directory_set: set[str]) -> Generator:
+        """Ascend only through native parents that declare this exact gitlink.
+
+        Every repository crossed on the way proves its own root in the same process that names its parent; those
+        proven roots are recorded in the set the caller owns for the duration of one read.
+        """
+        visited_dir_set: set[str] = set()
+        while canonical_path(directory) not in visited_dir_set:
+            visited_dir_set.add(canonical_path(directory))
+            parent_dir = yield from self._root_and_parent(directory, verified_directory_set)
+            if not parent_dir or canonical_path(parent_dir) in visited_dir_set:
+                break
+            try:
+                section_by_path, stage_by_path = yield from self._read_declarations(parent_dir)
+                matched = False
+                for path in section_by_path:
+                    if canonical_path(declared_directory(parent_dir, path)) != canonical_path(directory):
+                        continue
+                    if any(mode == "160000" for mode, _oid, _stage in stage_by_path.get(path, [])):
+                        matched = True
+                        break
+                if not matched:
+                    break
+            except (ValueError, RuntimeError, OSError):
+                break
+            directory = parent_dir
+        return directory
+
+    def _read(self, root_dir: str) -> Generator:
+        """Keep recursive reads inside verified declared worktrees.
+
+        Each repository proves its exact root once per read: while ascending to the family root, or when it is taken
+        from the queue after its declared path was validated again. The set of proven roots is local to this read, so
+        no later read and no check made before a write can ever rely on it.
+        """
+        verified_directory_set: set[str] = set()
+        root_dir = yield from self._find_root(root_dir, verified_directory_set)
+        entries: list[SubmoduleEntry] = []
+        causes: list[str] = []
+        pending_dirs = [(root_dir, None, "", "")]
+        visited_dir_set: set[str] = set()
+        while pending_dirs:
+            directory, parent_dir, path, section = pending_dirs.pop(0)
+            canonical_dir = canonical_path(directory)
+            if canonical_dir in visited_dir_set:
+                continue
+            visited_dir_set.add(canonical_dir)
+            try:
+                if parent_dir is not None:
+                    declared_directory(parent_dir, path)
+                if canonical_dir not in verified_directory_set:
+                    root_raw = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel"])
+                    if canonical_path(os.fsdecode(root_raw).rstrip("\r\n")) != canonical_dir:
+                        raise ValueError("Submodule does not resolve to its declared worktree")
+                    verified_directory_set.add(canonical_dir)
+                branch_raw = yield GitCommand(["-C", directory, "symbolic-ref", "--quiet", "--short", "HEAD"], accepted_codes=(0, 1))
+                head_raw = yield GitCommand(["-C", directory, "rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            except (ValueError, RuntimeError, OSError) as error:
+                entries.append(SubmoduleEntry(directory, parent_dir, path, section, None, None, "unknown", str(error)))
+                continue
+            cause = ""
+            internal_state = SubmoduleState()
+            try:
+                output = yield GitCommand(["-C", directory, "status", "--porcelain=v2", "-z", "--untracked-files=all", "--ignore-submodules=none"])
+                local_entries = parse_status(output)
+                tracked_changed = False
+                untracked_changed = False
+                for entry in local_entries:
+                    if entry.old_mode == "000000" and entry.new_mode == "000000" and entry.status == FileStatus.ADDED:
+                        untracked_changed = True
+                    else:
+                        tracked_changed = True
+                internal_state = SubmoduleState(None, tracked_changed, untracked_changed)
+            except (ValueError, RuntimeError, OSError) as error:
+                cause = str(error)
+            entries.append(SubmoduleEntry(directory, parent_dir, path, section, branch_raw.decode("utf-8", "replace").strip() or None,
+                                          head_raw.decode().strip() or None, "initialized", cause, internal_state))
+            try:
+                section_by_path, stage_by_path = yield from self._read_declarations(directory)
+            except (ValueError, RuntimeError, OSError) as error:
+                causes.append(str(error))
+                continue
+            for child_path, child_section in sorted(section_by_path.items()):
+                try:
+                    child_dir = declared_directory(directory, child_path)
+                except ValueError as error:
+                    entries.append(SubmoduleEntry("", directory, child_path, child_section, None, None, "invalid", str(error)))
+                    continue
+                stages = stage_by_path.get(child_path, [])
+                if any(stage != "0" for _mode, _oid, stage in stages):
+                    entries.append(SubmoduleEntry(child_dir, directory, child_path, child_section, None, None, "conflict", "The submodule index has unresolved stages"))
+                    continue
+                if not stages or not any(mode == "160000" and stage == "0" for mode, _oid, stage in stages):
+                    entries.append(SubmoduleEntry(child_dir, directory, child_path, child_section, None, None, "unknown", "No stage-zero gitlink"))
+                    continue
+                if not os.path.exists(child_dir):
+                    entries.append(SubmoduleEntry(child_dir, directory, child_path, child_section, None, None, "not initialized"))
+                    continue
+                if not os.path.isdir(child_dir):
+                    entries.append(SubmoduleEntry(child_dir, directory, child_path, child_section, None, None, "occupied", "A file occupies the declared path"))
+                    continue
+                if not os.path.lexists(os.path.join(child_dir, ".git")):
+                    with os.scandir(child_dir) as children:
+                        occupied = next(children, None) is not None
+                    availability = "occupied" if occupied else "not initialized"
+                    entries.append(SubmoduleEntry(child_dir, directory, child_path, child_section, None, None, availability,
+                                                  SUBMODULE_OCCUPIED_MESSAGE if occupied else ""))
+                    continue
+                # The child proves its exact root when it is taken from the queue, which reports a failure as the same unknown entry.
+                pending_dirs.append((child_dir, directory, child_path, child_section))
+        return SubmoduleSnapshot(root_dir, tuple(entries), "\n".join(causes))