gitpane 1.0.0__py3-none-any.whl

gitpane/transport/remote.py

@@ -0,0 +1,747 @@
+"""Apply explicit native Git edits to the remotes of a repository."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_MUTATION_TIMEOUT_MS, LOCAL_PREFIX, REMOTE_PREFIX
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction, OperationIntent, OperationOutcome, OperationStepResult, WriteScope
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, READ_PROFILE, ProcessStatus
+from gitpane.reference.reference_edit import reference_signature
+from gitpane.reference.reference_snapshot import REFERENCE_FORMAT
+from gitpane.system.path_identity import canonical_path
+from gitpane.transport.remote_config import (
+    INACTIVE_REMOTE_SECTION,
+    MERGE_TRACKING_FIELD,
+    REMOTE_TRACKING_FIELD,
+    BranchTracking,
+    GitConfigScope,
+    RemoteEntry,
+    RemoteSnapshot,
+    active_remote_urls,
+    config_signature,
+    field_values,
+    parse_config,
+    parse_remote_reference_output,
+    remote_section,
+    rewrite_url,
+    tracking_values,
+)
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError, ReadBatch
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.repository_operation import RepositoryOperationService
+    from gitpane.transport.remote_config import RemoteValue
+    from gitpane.worktree.worktree_service import WorktreeService
+
+
+@dataclass(frozen=True)
+class RemoteChange:
+    """Describe one explicitly edited field without replacing neighboring values."""
+
+    field: str
+    value: str
+    selected: RemoteValue | None = None
+    local_override: bool = False
+
+
+@dataclass(frozen=True)
+class RemoteOutcome(OperationOutcome):
+    """Publish the reread target and individual field results after actual process exit."""
+
+    snapshot: RemoteSnapshot | None = None
+    selected_name: str = ""
+
+
+REMOTE_FIELD_LABEL_BY_NAME = {"add": "Add remote", "name": "Name", "url": "Fetch Url", "pushurl": "Push Url"}
+TRACKING_LABEL_BY_FIELD = {REMOTE_TRACKING_FIELD: "Remote repository", MERGE_TRACKING_FIELD: "Default merge with"}
+EFFECTIVE_CONFIG_LIST_ARGUMENTS = ("config", "--null", "--show-origin", "--show-scope", "--includes", "--list")
+CONFIG_FILE_ORIGIN_PREFIX = "file:"
+
+
+def config_origin_filename(context: RepositoryContext, origin: str) -> str | None:
+    """Return the canonical file behind a ``file:`` origin, relative ones resolved from the repository, or None."""
+    if not origin.startswith(CONFIG_FILE_ORIGIN_PREFIX):
+        return None
+    filename = origin.removeprefix(CONFIG_FILE_ORIGIN_PREFIX)
+    if not filename:
+        return None
+    if not os.path.isabs(filename):
+        filename = os.path.join(context.repository_dir, filename)
+    return canonical_path(filename)
+
+
+def direct_config_values(context: RepositoryContext, values: tuple[RemoteValue, ...]) -> tuple[RemoteValue, ...]:
+    """Select, in order and with every repetition, the values written in the repository's own config file.
+
+    These are the only values a local write edits in place: an included file, a worktree file or a global file also
+    reads as local or effective configuration but is never the file ``git config --local`` changes. A value whose
+    origin cannot be resolved to that exact file is not direct, so it never authorizes an edit.
+    """
+    direct_filename = canonical_path(os.path.join(context.common_git_dir, "config"))
+    direct_values: list[RemoteValue] = []
+    for value in values:
+        if value.scope == GitConfigScope.LOCAL and config_origin_filename(context, value.origin) == direct_filename:
+            direct_values.append(value)
+    return tuple(direct_values)
+
+
+def signature_covers(signature: tuple, earlier: tuple) -> bool:
+    """Tell whether every source recorded by an earlier config signature is still identical in a later, wider one."""
+    identity_records, records = signature
+    earlier_identity_records, earlier_records = earlier
+    record_set = set(records)
+    return identity_records == earlier_identity_records and all(record in record_set for record in earlier_records)
+
+
+def url_edit_reason(snapshot: RemoteSnapshot, name: str, field: str, selected: RemoteValue | None) -> str:
+    """Explain when native set-url cannot safely edit precisely one selected value."""
+    values = field_values(snapshot, name, field)
+    if selected is None:
+        return "Choose the exact URL to edit." if values else ""
+    if any(character in selected.value for character in ("\0", "\n", "\r")):
+        return "This URL contains control characters. Review its configuration source before editing."
+    if selected not in field_values(snapshot, name, field, direct=True):
+        return "This URL is inherited. Editing it locally would retain the inherited destination; edit its source explicitly outside this form."
+    expanded = rewrite_url(selected.value, snapshot.values)
+    candidates = 0
+    for value in values:
+        if value.value in (selected.value, expanded):
+            candidates += 1
+    if candidates != 1:
+        return "This URL is repeated or overlaps a rewritten value. Git cannot select only this occurrence safely."
+    return ""
+
+
+def validate_name(name: str) -> None:
+    """Reject empty names and control characters before Git validates ref naming."""
+    if not name or name.startswith("-") or any(character in name for character in ("\0", "\n", "\r")):
+        raise ValueError("Enter a valid remote name without options or control characters")
+
+
+class RemoteService:
+    """Use the existing common repository owner and native asynchronous runner."""
+
+    def __init__(self, worktree_service: WorktreeService, repository_operation: RepositoryOperationService) -> None:
+        """Inject write ownership so remotes cannot race staging or other config changes."""
+        self.worktree_service = worktree_service
+        self.repository_operation = repository_operation
+        self.outcome_by_id: dict[str, RemoteOutcome] = {}
+
+    def capture(self, context: RepositoryContext, git_filename: str, generation: int = 0) -> Generator:
+        """Read every config value, branch, remote-tracking branch and HEAD with two Git processes.
+
+        The reference and configuration sources are fingerprinted before and after the reads; a capture that saw any
+        of them move is refused rather than published. Destinations follow Git's own remote rules from the values read,
+        and only a remote whose destinations Git alone can establish is asked of Git separately.
+        """
+        opening_state = yield FileTask(lambda: (reference_signature(context), config_signature(context, ())))
+        reference_state, base_signature = opening_state
+        reference_output, output = yield ReadBatch((GitCommand(["for-each-ref", "--format=" + REFERENCE_FORMAT, LOCAL_PREFIX, REMOTE_PREFIX], profile=READ_PROFILE),
+                                                    GitCommand(list(EFFECTIVE_CONFIG_LIST_ARGUMENTS), profile=READ_PROFILE)))
+        values = parse_config(output)
+        direct_values = direct_config_values(context, values)
+        signature = yield FileTask(lambda: config_signature(context, values))
+        if not signature_covers(signature, base_signature):
+            raise ValueError("Remote configuration changed while reading; reopen Manage remotes")
+        references, branch_state_by_ref, head_oid, head_ref = parse_remote_reference_output(reference_output)
+        if head_ref is None:
+            # The listing marks HEAD only when it is on an existing branch; a detached or unborn HEAD is asked of Git.
+            head_output, symbolic_output = yield ReadBatch((GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1), profile=READ_PROFILE),
+                                                            GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1), profile=READ_PROFILE)))
+            head_oid = head_output.decode("ascii", "replace").strip() or None
+            head_ref = symbolic_output.decode("utf-8", "surrogateescape").strip()
+        value_by_name: dict[str, list[RemoteValue]] = {}
+        inactive_value_by_name: dict[str, list[RemoteValue]] = {}
+        for value in values:
+            for prefix, target_by_name in (("remote.", value_by_name), (INACTIVE_REMOTE_SECTION, inactive_value_by_name)):
+                if value.key.startswith(prefix) and "." in value.key.removeprefix(prefix):
+                    name, _key = value.key.removeprefix(prefix).rsplit(".", 1)
+                    target_by_name.setdefault(name, []).append(value)
+        entry_by_name: dict[str, RemoteEntry] = {}
+        for name in sorted(value_by_name.keys() | inactive_value_by_name.keys(), key=lambda name: (name.casefold(), name)):
+            active = name in value_by_name
+            entry_values = value_by_name[name] if active else inactive_value_by_name[name]
+            if not active:
+                # Git's remote reader ignores command-scope definitions. Inactive sections retain
+                # their configured destinations with the same longest-prefix rewrite rules.
+                fetch_urls: list[str] = []
+                push_urls: list[str] = []
+                raw_urls: list[str] = []
+                for value in entry_values:
+                    if value.key == INACTIVE_REMOTE_SECTION + name + ".url":
+                        raw_urls.append(value.value)
+                        fetch_urls.append(rewrite_url(value.value, values))
+                    elif value.key == INACTIVE_REMOTE_SECTION + name + ".pushurl":
+                        push_urls.append(rewrite_url(value.value, values))
+                if not push_urls:
+                    for url in raw_urls:
+                        rewritten = rewrite_url(url, values, ".pushinsteadof")
+                        if rewritten != url:
+                            push_urls.append(rewritten)
+                    if not push_urls:
+                        push_urls.extend(fetch_urls)
+            else:
+                native_urls = active_remote_urls(name, tuple(entry_values), values)
+                if native_urls is None:
+                    fetch, push = yield ReadBatch((GitCommand(["remote", "get-url", "--all", "--", name], accepted_codes=(0, 2), profile=READ_PROFILE),
+                                                  GitCommand(["remote", "get-url", "--push", "--all", "--", name], accepted_codes=(0, 2), profile=READ_PROFILE)))
+                    native_urls = (tuple(fetch.decode("utf-8", "surrogateescape").splitlines()), tuple(push.decode("utf-8", "surrogateescape").splitlines()))
+                fetch_urls, push_urls = native_urls
+            entry_by_name[name] = RemoteEntry(name, tuple(entry_values), tuple(fetch_urls), tuple(push_urls), active, active and name in inactive_value_by_name)
+        final_signature = yield FileTask(lambda: config_signature(context, values))
+        final_reference_state = yield FileTask(lambda: reference_signature(context))
+        if final_signature != signature or reference_state != final_reference_state:
+            raise ValueError("Remote configuration changed while reading; reopen Manage remotes")
+        observed_ref_set: set[str] = set(branch_state_by_ref)
+        for record in references.splitlines():
+            full_ref, _separator, _rest = record.partition(b"\0")
+            observed_ref_set.add(full_ref.decode("utf-8", "surrogateescape"))
+        tracking_by_ref: dict[str, BranchTracking] = {}
+        for full_ref, (oid, upstream) in branch_state_by_ref.items():
+            prefix = "branch." + full_ref.removeprefix(LOCAL_PREFIX) + "."
+            branch_values = tuple(value for value in values if value.key in (prefix + REMOTE_TRACKING_FIELD, prefix + MERGE_TRACKING_FIELD))
+            tracking_by_ref[full_ref] = BranchTracking(full_ref, oid, branch_values, upstream, bool(upstream) and upstream in observed_ref_set)
+        return RemoteSnapshot(context, git_filename, generation, entry_by_name, values, direct_values, signature, references, tracking_by_ref, reference_state,
+                              head_oid, head_ref)
+
+    def read(self, context: RepositoryContext, git_filename: str, generation: int, callback: Callable) -> None:
+        """Read without taking a mutation reservation or changing the repository."""
+        self.worktree_service.run(context, git_filename, self.capture(context, git_filename, generation), callback)
+
+    def save(self, snapshot: RemoteSnapshot, name: str, changes: tuple[RemoteChange, ...], *, session_id: str,
+             is_current: Callable[[], bool] | None = None, operation_id: str | None = None) -> str:
+        """Reserve and submit the selected target once, retaining its completed result."""
+        refs = [REMOTE_PREFIX + name + "/*"]
+        for change in changes:
+            if change.field == "name":
+                refs.append(REMOTE_PREFIX + change.value + "/*")
+        operation = OperationIntent.capture(operation_id or uuid.uuid4().hex, snapshot.context, snapshot.git_filename,
+                                            generation=snapshot.generation, targets=(name,), session_id=session_id, operation="Save remote",
+                                            action=OperationAction.CONFIG_WRITE, scope=WriteScope.capture(snapshot.context, tuple(refs)), from_form=True)
+        return self.repository_operation.submit(operation, self._save(operation, snapshot, name, changes, is_current))
+
+    def set_active(self, snapshot: RemoteSnapshot, name: str, active: bool, *, session_id: str,
+                   is_current: Callable[[], bool] | None = None, operation_id: str | None = None) -> str:
+        """Move a local remote section once while retaining every reference and tracking value."""
+        operation = OperationIntent.capture(operation_id or uuid.uuid4().hex, snapshot.context, snapshot.git_filename,
+                                            generation=snapshot.generation, targets=(name,), session_id=session_id,
+                                            operation="Activate remote" if active else "Deactivate remote", action=OperationAction.CONFIG_WRITE, from_form=True)
+        return self.repository_operation.submit(operation, self._set_active(operation, snapshot, name, active, is_current))
+
+    def remove(self, snapshot: RemoteSnapshot, name: str, *, session_id: str,
+               is_current: Callable[[], bool] | None = None, operation_id: str | None = None) -> str:
+        """Remove exactly the confirmed local remote after checking its captured definition."""
+        operation = OperationIntent.capture(operation_id or uuid.uuid4().hex, snapshot.context, snapshot.git_filename,
+                                            generation=snapshot.generation, targets=(name,), session_id=session_id, operation="Remove remote",
+                                            action=OperationAction.CONFIG_WRITE, scope=WriteScope.capture(snapshot.context, (REMOTE_PREFIX + name + "/*",)), from_form=True)
+        return self.repository_operation.submit(operation, self._remove(operation, snapshot, name, is_current))
+
+    def set_tracking(self, snapshot: RemoteSnapshot, full_ref: str, changes: tuple[RemoteChange, ...], *, session_id: str,
+                     is_current: Callable[[], bool] | None = None, operation_id: str | None = None) -> str:
+        """Save only the selected branch's explicit config fields under common ownership."""
+        operation = OperationIntent.capture(operation_id or uuid.uuid4().hex, snapshot.context, snapshot.git_filename,
+                                            generation=snapshot.generation, targets=(full_ref,), session_id=session_id, operation="Save branch tracking", action=OperationAction.CONFIG_WRITE, from_form=True)
+        return self.repository_operation.submit(operation, self._set_tracking(operation, snapshot, full_ref, changes, is_current))
+
+    def _set_tracking(self, operation: OperationIntent, snapshot: RemoteSnapshot, full_ref: str, changes: tuple[RemoteChange, ...],
+                      is_current: Callable[[], bool] | None) -> Generator:
+        """Recheck the captured branch and record each native field write separately."""
+        expected = snapshot
+        refreshed = snapshot
+        steps: list[OperationStepResult] = []
+        diagnostic = None
+        field_set: set[str] = set()
+        for change in changes:
+            native_started = False
+            process_status = None
+            cause = None
+            status = OperationStatus.REFUSED
+            try:
+                if (not operation.session_id or full_ref not in expected.tracking_by_ref or change.field not in TRACKING_LABEL_BY_FIELD
+                        or change.field in field_set or is_current is not None and not is_current()):
+                    raise ValueError("The branch tracking form is invalid or no longer authorized")
+                field_set.add(change.field)
+                current = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                branch = current.tracking_by_ref.get(full_ref)
+                if branch != expected.tracking_by_ref[full_ref] or current.values != expected.values:
+                    raise ValueError("Branch or configuration changed. Reread tracking before saving this branch.")
+                if not change.value or any(character in change.value for character in ("\0", "\n", "\r")):
+                    raise ValueError("Enter a nonempty tracking value without control characters")
+                if change.field == MERGE_TRACKING_FIELD:
+                    if not change.value.startswith(LOCAL_PREFIX):
+                        raise ValueError("Default merge with must be a full refs/heads/ branch name")
+                    yield GitCommand(["check-ref-format", change.value], profile=READ_PROFILE)
+                elif change.value != "." and change.value not in current.entry_by_name:
+                    raise ValueError("Choose a configured remote repository")
+                values = tracking_values(current, full_ref, change.field)
+                selected = change.selected
+                if selected is not None and selected not in values:
+                    raise ValueError("The selected value does not belong to this captured branch field")
+                if values and (selected not in values or sum(value.value == selected.value for value in values) != 1):
+                    raise ValueError("Select one unique configured tracking value; repeated values require review in their source")
+                if selected is not None and selected not in current.direct_values:
+                    raise ValueError("This tracking value is inherited; edit its original configuration source")
+                key = "branch." + full_ref.removeprefix(LOCAL_PREFIX) + "." + change.field
+                arguments = (["config", "--local", "--fixed-value", "--replace-all", "--", key, change.value, selected.value]
+                             if selected else ["config", "--local", "--add", "--", key, change.value])
+                def validate_launch(captured: RemoteSnapshot = current) -> None:
+                    """Keep queued writes tied to the same branch, config sources and authority."""
+                    nonlocal native_started
+                    self.repository_operation.validate(operation)
+                    allows = self.repository_operation.allows
+                    if (is_current is not None and not is_current() or allows is not None and not allows(operation)
+                            or config_signature(snapshot.context, captured.values) != captured.signature
+                            or reference_signature(snapshot.context) != captured.reference_state):
+                        raise ValueError("Branch, configuration or authority changed before launch; reread tracking")
+                    native_started = True
+
+                if selected is None or change.value != selected.value:
+                    # Saving tracking writes local configuration, so it stays supervised even when the caller
+                    # launched the surrounding sequence as a plain read, as an upstream setup after a push does.
+                    yield GitCommand(arguments, timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                                     before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+                process_status = ProcessStatus.SUCCESS
+                refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                expected_texts: list[str] = []
+                for value in values:
+                    expected_texts.append(change.value if value == selected else value.value)
+                if selected is None:
+                    expected_texts.append(change.value)
+                if tuple(value.value for value in tracking_values(refreshed, full_ref, change.field)) != tuple(expected_texts):
+                    raise ValueError("Git completed but the saved tracking field could not be verified")
+                refreshed_branch = refreshed.tracking_by_ref.get(full_ref)
+                if (refreshed_branch is None or refreshed_branch.oid != branch.oid
+                        or tuple(value for value in refreshed.values if value.key != key) != tuple(value for value in current.values if value.key != key)):
+                    raise ValueError("Branch or another configuration field changed during save. Reread tracking before continuing.")
+                expected = refreshed
+                status = OperationStatus.SUCCESS
+            except (ValueError, OSError, GitCommandError) as error:
+                cause = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(operation.operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+                diagnostic = diagnostic or cause
+                if isinstance(error, GitCommandError):
+                    process_status = error.process_status
+                status = OperationStatus.UNKNOWN if process_status == ProcessStatus.SUCCESS else OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+                try:
+                    refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                    if native_started and tracking_values(refreshed, full_ref, change.field) != tracking_values(current, full_ref, change.field):
+                        status = OperationStatus.UNKNOWN
+                except (ValueError, OSError, GitCommandError):
+                    refreshed = None
+                    if native_started:
+                        status = OperationStatus.UNKNOWN
+            steps.append(OperationStepResult(TRACKING_LABEL_BY_FIELD.get(change.field, "Tracking field"), status, change, refreshed, process_status,
+                                             "saved" if status == OperationStatus.SUCCESS else "verify effect" if status == OperationStatus.UNKNOWN else "not saved", cause))
+            if status != OperationStatus.SUCCESS:
+                break
+        status = OperationStatus.SUCCESS if steps and all(step.status == OperationStatus.SUCCESS for step in steps) else OperationStatus.PARTIAL if any(step.status == OperationStatus.SUCCESS for step in steps) else next(reversed(steps)).status if steps else OperationStatus.REFUSED
+        outcome = RemoteOutcome(operation.operation_id, status, tuple(steps), diagnostic, refreshed, full_ref)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def _remove(self, operation: OperationIntent, snapshot: RemoteSnapshot, name: str, is_current: Callable[[], bool] | None) -> Generator:
+        """Observe native removal without transporting or deleting any reference on a server."""
+        refreshed = None
+        current = None
+        diagnostic = None
+        process_status = None
+        return_code = None
+        native_started = False
+        status, effect = OperationStatus.REFUSED, "not removed"
+        try:
+            validate_name(name)
+            if not operation.session_id or is_current is not None and not is_current():
+                raise ValueError("The remote form is no longer authorized")
+            current = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+            entry = current.entry_by_name.get(name)
+            if entry is None or name not in snapshot.entry_by_name:
+                raise ValueError("The selected remote no longer exists; reopen Manage remotes")
+            if entry.collision:
+                raise ValueError("Active and inactive remote definitions collide; review their configuration sources")
+            if current.values != snapshot.values or current.references != snapshot.references:
+                raise ValueError("Remote configuration or references changed; review the selected remote before removal")
+            if any(value not in current.direct_values for value in entry.values):
+                raise ValueError("An inherited remote cannot be removed locally; edit its original configuration source")
+            if entry.active:
+                for value in current.values:
+                    if value.key.startswith("branch.") and value.key.endswith((".remote", ".pushremote")) and value.value == name and value not in current.direct_values:
+                        raise ValueError("Inherited branch tracking cannot be updated by local remote removal; review its original source")
+            yield GitCommand(["check-ref-format", REMOTE_PREFIX + name + "/check"], profile=READ_PROFILE)
+            reference_state = yield FileTask(lambda: reference_signature(snapshot.context))
+
+            def validate_launch() -> None:
+                """Recheck the confirmed target after waiting for a native process slot."""
+                nonlocal native_started
+                self.repository_operation.validate(operation)
+                allows = self.repository_operation.allows
+                if (is_current is not None and not is_current() or allows is not None and not allows(operation)
+                        or config_signature(snapshot.context, current.values) != current.signature
+                        or reference_signature(snapshot.context) != reference_state):
+                    raise ValueError("Remote configuration, references or authority changed before launch")
+                native_started = True
+
+            arguments = ["remote", "remove", "--", name] if entry.active else ["config", "--local", "--remove-section", "--", remote_section(current, name)]
+            yield GitCommand(arguments, timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+            process_status, return_code = ProcessStatus.SUCCESS, 0
+            refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+            if name in refreshed.entry_by_name:
+                raise ValueError("Git completed but the selected remote still has a configuration definition")
+            if not entry.active:
+                expected_values = tuple(value for value in current.values if value not in entry.values)
+                if refreshed.references != current.references or refreshed.values != expected_values:
+                    raise ValueError("The inactive section was removed but other configuration or references also changed")
+            status, effect = OperationStatus.SUCCESS, "removed"
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(operation.operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+            if isinstance(error, GitCommandError):
+                process_status, return_code = error.process_status, error.return_code
+            status = OperationStatus.UNKNOWN if process_status == ProcessStatus.SUCCESS else OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+            try:
+                refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                if native_started and current is not None and (refreshed.values != current.values or refreshed.references != current.references):
+                    status, effect = OperationStatus.UNKNOWN, "configuration or references changed; review before retrying"
+            except (ValueError, OSError, GitCommandError):
+                if native_started:
+                    status, effect = OperationStatus.UNKNOWN, "verify removal"
+        step = OperationStepResult(operation.operation, status, snapshot, refreshed, process_status, effect, diagnostic, return_code)
+        selected_name = name if refreshed is None or name in refreshed.entry_by_name else ""
+        outcome = RemoteOutcome(operation.operation_id, status, (step,), diagnostic, refreshed, selected_name)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def _set_active(self, operation: OperationIntent, snapshot: RemoteSnapshot, name: str, active: bool, is_current: Callable[[], bool] | None) -> Generator:
+        """Compare exact definitions before moving a section and observe its final native state."""
+        refreshed = None
+        diagnostic = None
+        process_status = None
+        native_started = False
+        effect = "not changed"
+        status = OperationStatus.REFUSED
+        try:
+            validate_name(name)
+            if not operation.session_id or type(active) is not bool or is_current is not None and not is_current():
+                raise ValueError("The remote form is no longer authorized")
+            current = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+            entry = current.entry_by_name.get(name)
+            expected = snapshot.entry_by_name.get(name)
+            if entry is None or expected is None:
+                raise ValueError("The selected remote no longer exists; reopen Manage remotes")
+            if entry.collision:
+                raise ValueError("Active and inactive remote definitions collide; review their configuration sources")
+            if current.values != snapshot.values or current.references != snapshot.references:
+                raise ValueError("Remote configuration or references changed; review the selected remote")
+            if entry.active == active:
+                refreshed, status, effect = current, OperationStatus.SUCCESS, "already active" if active else "already inactive"
+            else:
+                if any(value not in current.direct_values for value in entry.values):
+                    raise ValueError("An inherited remote cannot be moved locally; edit its original configuration source")
+                yield GitCommand(["check-ref-format", REMOTE_PREFIX + name + "/check"], profile=READ_PROFILE)
+                reference_state = yield FileTask(lambda: reference_signature(snapshot.context))
+
+                def validate_launch() -> None:
+                    """Keep queued writes bound to the same config, refs and live authority."""
+                    nonlocal native_started
+                    self.repository_operation.validate(operation)
+                    allows = self.repository_operation.allows
+                    if (is_current is not None and not is_current() or allows is not None and not allows(operation)
+                            or config_signature(snapshot.context, current.values) != current.signature
+                            or reference_signature(snapshot.context) != reference_state):
+                        raise ValueError("Remote configuration, references or authority changed before launch")
+                    native_started = True
+
+                source = remote_section(current, name)
+                destination = ("remote." if active else INACTIVE_REMOTE_SECTION) + name
+                yield GitCommand(["config", "--local", "--rename-section", "--", source, destination], timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                                 idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+                process_status = ProcessStatus.SUCCESS
+                refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                expected_values = tuple(replace(value, key=destination + value.key.removeprefix(source)) if value in entry.values else value for value in current.values)
+                if (refreshed.values != expected_values or refreshed.references != current.references
+                        or refreshed.entry_by_name.get(name) is None or refreshed.entry_by_name[name].active != active):
+                    raise ValueError("Git completed but the remote section, references or tracking could not be verified")
+                status, effect = OperationStatus.SUCCESS, "activated" if active else "deactivated"
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(operation.operation, snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+            if isinstance(error, GitCommandError):
+                process_status = error.process_status
+            status = OperationStatus.UNKNOWN if process_status == ProcessStatus.SUCCESS else OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+            try:
+                refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                if native_started and refreshed.entry_by_name.get(name) != snapshot.entry_by_name.get(name):
+                    status, effect = OperationStatus.UNKNOWN, "verify changed remote"
+            except (ValueError, OSError, GitCommandError):
+                if native_started:
+                    status, effect = OperationStatus.UNKNOWN, "verify changed remote"
+        step = OperationStepResult(operation.operation, status, snapshot, refreshed, process_status, effect, diagnostic)
+        outcome = RemoteOutcome(operation.operation_id, status, (step,), diagnostic, refreshed, name)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def _save(self, operation: OperationIntent, snapshot: RemoteSnapshot, name: str, changes: tuple[RemoteChange, ...], is_current: Callable[[], bool] | None) -> Generator:
+        """Route a captured addition or field edits without silently widening the intent."""
+        if any(change.field == "add" for change in changes):
+            additions = tuple(change for change in changes if change.field == "add")
+            edits = tuple(change for change in changes if change.field != "add")
+            if any(change.field != "pushurl" for change in edits):
+                return (yield from self._add(operation, snapshot, name, changes, is_current))
+            outcome = yield from self._add(operation, snapshot, name, additions, is_current)
+            if outcome.status != OperationStatus.SUCCESS or not edits:
+                return outcome
+            result = yield from self._edit(operation, outcome.snapshot, name, edits, is_current)
+            status = result.status if result.status == OperationStatus.SUCCESS else OperationStatus.PARTIAL
+            outcome = replace(result, status=status, steps=outcome.steps + result.steps)
+            self.outcome_by_id[operation.operation_id] = outcome
+            return outcome
+        return (yield from self._edit(operation, snapshot, name, changes, is_current))
+
+    def _add(self, operation: OperationIntent, snapshot: RemoteSnapshot, name: str, changes: tuple[RemoteChange, ...], is_current: Callable[[], bool] | None) -> Generator:
+        """Revalidate the add target at submission and again when Git actually launches."""
+        diagnostic = None
+        refreshed = None
+        status = OperationStatus.REFUSED
+        process_status = None
+        native_started = False
+        try:
+            if not operation.session_id:
+                raise ValueError("A live management session is required")
+            validate_name(name)
+            if is_current is not None and not is_current():
+                raise ValueError("The remote form is no longer current")
+            if len(changes) != 1 or next(iter(changes)).field != "add":
+                raise ValueError("Choose Add remote to create a new remote")
+            change = next(iter(changes))
+            if not change.value or any(character in change.value for character in ("\0", "\n", "\r")):
+                raise ValueError("Enter a URL without control characters")
+            current = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+            if name in snapshot.entry_by_name or name in current.entry_by_name:
+                raise ValueError("A remote with this name already exists")
+            yield GitCommand(["check-ref-format", REMOTE_PREFIX + name + "/check"], profile=READ_PROFILE)
+
+            def validate_launch() -> None:
+                """Reject a queued request after its form or captured configuration changed."""
+                nonlocal native_started
+                self.repository_operation.validate(operation)
+                allows = self.repository_operation.allows
+                if (is_current is not None and not is_current() or allows is not None and not allows(operation)
+                        or config_signature(snapshot.context, current.values) != current.signature):
+                    raise ValueError("Remote configuration or authority changed before launch; review and save again")
+                native_started = True
+
+            yield GitCommand(["remote", "add", "--", name, change.value], timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                             idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+            process_status = ProcessStatus.SUCCESS
+            refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+            entry = refreshed.entry_by_name.get(name)
+            if entry is None or not any(value.key == "remote." + name + ".url" and value.value == change.value for value in entry.values):
+                raise ValueError("Git completed but the saved remote could not be verified")
+            status = OperationStatus.SUCCESS
+        except (ValueError, OSError, GitCommandError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Save remote", snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+            status = OperationStatus.PARTIAL if process_status == ProcessStatus.SUCCESS else OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+            if native_started:
+                try:
+                    refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                    if name not in snapshot.entry_by_name and name in refreshed.entry_by_name:
+                        status = OperationStatus.PARTIAL
+                except (ValueError, OSError, GitCommandError):
+                    status = OperationStatus.UNKNOWN
+        step = OperationStepResult("Add remote", OperationStatus.SUCCESS if process_status == ProcessStatus.SUCCESS else status, snapshot, refreshed, process_status,
+                                   "created" if status == OperationStatus.SUCCESS else "verify saved remote" if process_status == ProcessStatus.SUCCESS else "not observed", diagnostic)
+        outcome = RemoteOutcome(operation.operation_id, status, (step,), diagnostic, refreshed, name)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def _edit(self, operation: OperationIntent, snapshot: RemoteSnapshot, name: str, changes: tuple[RemoteChange, ...], is_current: Callable[[], bool] | None) -> Generator:
+        """Save independent fields with fresh comparisons and observed partial results."""
+        expected = snapshot
+        refreshed = snapshot
+        steps: list[OperationStepResult] = []
+        diagnostic = None
+        field_set: set[str] = set()
+        for change in changes:
+            current = None
+            process_status = None
+            status = OperationStatus.REFUSED
+            cause = None
+            selected_name = name
+            selected = None
+            native_started = False
+            try:
+                if (not operation.session_id or change.field not in ("name", "url", "pushurl") or change.field in field_set
+                        or is_current is not None and not is_current()):
+                    raise ValueError("The remote change is invalid or no longer authorized")
+                field_set.add(change.field)
+                validate_name(name)
+                if not change.value or any(character in change.value for character in ("\0", "\n", "\r")):
+                    raise ValueError("Enter a nonempty value without control characters")
+                current = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                if name not in current.entry_by_name or name not in expected.entry_by_name:
+                    raise ValueError("The selected remote no longer exists; reopen Manage remotes")
+                if current.entry_by_name[name].collision or current.entry_by_name[name].active != expected.entry_by_name[name].active:
+                    raise ValueError("Remote activation changed or definitions collide; reopen Manage remotes")
+                reference_state = None
+                if change.field == "name":
+                    if not current.entry_by_name[name].active:
+                        raise ValueError("Activate this remote before renaming it so Git can update its references and tracking")
+                    validate_name(change.value)
+                    if change.value == name:
+                        continue
+                    if change.value in current.entry_by_name:
+                        raise ValueError("A remote with this name already exists")
+                    if current.entry_by_name[name] != expected.entry_by_name[name] or current.references != expected.references:
+                        raise ValueError("Remote configuration or references changed; review the name change")
+                    for value in current.entry_by_name[name].values:
+                        if value not in current.direct_values:
+                            raise ValueError("An inherited remote cannot be renamed locally without leaving its original definition")
+                    tracking_values = tuple(value for value in current.values if value.key.startswith("branch.") and value.key.endswith((".remote", ".pushremote")) and value.value == name)
+                    expected_tracking_values = tuple(value for value in expected.values if value.key.startswith("branch.") and value.key.endswith((".remote", ".pushremote")) and value.value == name)
+                    if tracking_values != expected_tracking_values or any(value not in current.direct_values for value in tracking_values):
+                        raise ValueError("Branch tracking changed or is inherited; a local rename would not update it safely")
+                    yield GitCommand(["check-ref-format", REMOTE_PREFIX + change.value + "/check"], profile=READ_PROFILE)
+                    reference_state = yield FileTask(lambda: reference_signature(snapshot.context))
+                    arguments = ["remote", "rename", "--", name, change.value]
+                    selected_name = change.value
+                else:
+                    expected_values = field_values(expected, name, change.field)
+                    if field_values(current, name, change.field) != expected_values:
+                        raise ValueError("This field changed outside the form. Review the refreshed value before retrying.")
+                    rewrite_values = tuple(value for value in current.values if value.key.startswith("url."))
+                    expected_rewrite_values = tuple(value for value in expected.values if value.key.startswith("url."))
+                    if rewrite_values != expected_rewrite_values:
+                        raise ValueError("URL rewrite configuration changed. Review the effective destination before retrying.")
+                    selected = replace(change.selected, key=remote_section(current, name) + "." + change.field) if change.selected is not None else None
+                    if selected is not None and selected not in expected_values:
+                        raise ValueError("The selected URL does not belong to this captured field")
+                    reason = url_edit_reason(current, name, change.field, selected)
+                    if reason:
+                        raise ValueError(reason)
+                    inherited = any(value not in current.direct_values for value in current.entry_by_name[name].values)
+                    if selected is None and inherited and not change.local_override:
+                        raise ValueError("Choose Create local Push URL override to replace the inherited fetch destination for pushes")
+                    if selected is None and (change.field != "pushurl" or expected_values):
+                        raise ValueError("Choose the exact configured URL to edit")
+                    arguments = ["remote", "set-url"]
+                    if change.field == "pushurl":
+                        arguments.append("--push")
+                    if selected is None:
+                        arguments.append("--add")
+                    arguments.extend(["--", name, change.value])
+                    if selected is not None:
+                        # Git validates against expanded URLs, then uses the same regex on raw config.
+                        # Match both identities only after proving that no other raw value overlaps.
+                        expanded = rewrite_url(selected.value, current.values)
+                        patterns: list[str] = []
+                        for text in (selected.value, expanded):
+                            escaped = "".join("\\" + character if character in r"\.^$*+?{}[]()|" else character for character in text)
+                            patterns.append("^" + escaped + "$")
+                        arguments.append("(" + "|".join(patterns) + ")")
+                    elif inherited:
+                        # remote set-url refuses a remote defined only in global scope. A new local
+                        # pushurl overrides fetch fallback without rewriting any inherited file.
+                        arguments = ["config", "--local", "--add", "remote." + name + ".pushurl", change.value]
+                    if not current.entry_by_name[name].active:
+                        key = remote_section(current, name) + "." + change.field
+                        if selected is not None:
+                            arguments = ["config", "--local", "--fixed-value", "--replace-all", "--", key, change.value, selected.value]
+                        else:
+                            arguments = ["config", "--local", "--add", "--", key, change.value]
+
+                def validate_launch(current: RemoteSnapshot = current, reference_state: tuple | None = reference_state) -> None:
+                    """Recheck live authority and all read sources immediately before native launch."""
+                    nonlocal native_started
+                    self.repository_operation.validate(operation)
+                    allows = self.repository_operation.allows
+                    if (is_current is not None and not is_current() or allows is not None and not allows(operation)
+                            or config_signature(snapshot.context, current.values) != current.signature
+                            or reference_state is not None and reference_signature(snapshot.context) != reference_state):
+                        raise ValueError("Remote configuration, references or authority changed before launch")
+                    native_started = True
+
+                yield GitCommand(arguments, timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=GIT_MUTATION_TIMEOUT_MS, before_start=validate_launch, profile=LOCAL_WRITE_PROFILE)
+                process_status = ProcessStatus.SUCCESS
+                refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                if change.field == "name":
+                    if name in refreshed.entry_by_name or selected_name not in refreshed.entry_by_name:
+                        raise ValueError("Git completed the rename but its final remote definition is uncertain")
+                    old_prefix, new_prefix = REMOTE_PREFIX + name + "/", REMOTE_PREFIX + selected_name + "/"
+                    # for-each-ref sorts by full name, so compare records after a rename changes sort order.
+                    if sorted(refreshed.references.splitlines()) != sorted(current.references.replace(old_prefix.encode("utf-8"), new_prefix.encode("utf-8")).splitlines()):
+                        raise ValueError("The renamed remote references differ from their captured targets")
+                    expected = self._renamed_snapshot(expected, name, selected_name)
+                    name = selected_name
+                else:
+                    expected_strings: list[str] = []
+                    for value in field_values(current, name, change.field):
+                        expected_strings.append(change.value if value == selected else value.value)
+                    if selected is None:
+                        expected_strings.append(change.value)
+                    actual_strings = tuple(value.value for value in field_values(refreshed, name, change.field))
+                    if actual_strings != tuple(expected_strings):
+                        raise ValueError("Git completed but the exact URL values could not be verified")
+                    expected = self._updated_field(expected, refreshed, name, change.field)
+                status = OperationStatus.SUCCESS
+            except (ValueError, OSError, GitCommandError) as error:
+                cause = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Save remote", snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+                diagnostic = diagnostic or cause
+                if isinstance(error, GitCommandError):
+                    process_status = error.process_status
+                status = OperationStatus.UNKNOWN if process_status == ProcessStatus.SUCCESS else OperationStatus.FAILED if native_started else OperationStatus.REFUSED
+                try:
+                    refreshed = yield from self.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+                    if change.field == "name" and name not in refreshed.entry_by_name and selected_name in refreshed.entry_by_name:
+                        expected = self._renamed_snapshot(expected, name, selected_name)
+                        name = selected_name
+                        status = OperationStatus.UNKNOWN
+                    elif native_started and change.field in ("url", "pushurl") and any(value.value == change.value for value in field_values(refreshed, name, change.field)):
+                        status = OperationStatus.UNKNOWN
+                except (ValueError, OSError, GitCommandError):
+                    refreshed = None
+            steps.append(OperationStepResult(REMOTE_FIELD_LABEL_BY_NAME.get(change.field, "Remote field"), status, change, refreshed, process_status,
+                                              "saved" if status == OperationStatus.SUCCESS else "verify effect" if status == OperationStatus.UNKNOWN else "not saved", cause))
+            if status == OperationStatus.UNKNOWN:
+                break
+        success = any(step.status == OperationStatus.SUCCESS for step in steps)
+        incomplete = any(step.status != OperationStatus.SUCCESS for step in steps)
+        if success:
+            status = OperationStatus.PARTIAL if incomplete else OperationStatus.SUCCESS
+        else:
+            status = OperationStatus.UNKNOWN if any(step.status == OperationStatus.UNKNOWN for step in steps) else OperationStatus.FAILED if any(step.status == OperationStatus.FAILED for step in steps) else OperationStatus.REFUSED
+        outcome = RemoteOutcome(operation.operation_id, status, tuple(steps), diagnostic, refreshed, name)
+        self.outcome_by_id[operation.operation_id] = outcome
+        return outcome
+
+    def _renamed_snapshot(self, snapshot: RemoteSnapshot, old: str, new: str) -> RemoteSnapshot:
+        """Remap only native rename effects while keeping unrelated field expectations stale."""
+        def renamed(value: RemoteValue) -> RemoteValue:
+            """Follow the native section, refspec and tracking association rename."""
+            key = value.key
+            text = value.value
+            if key.startswith("remote." + old + "."):
+                key = "remote." + new + "." + key.removeprefix("remote." + old + ".")
+                if key.endswith(".fetch"):
+                    text = text.replace(REMOTE_PREFIX + old + "/", REMOTE_PREFIX + new + "/")
+            if key.startswith("branch.") and key.endswith((".remote", ".pushremote")) and text == old:
+                text = new
+            return replace(value, key=key, value=text)
+
+        values = tuple(renamed(value) for value in snapshot.values)
+        direct_values = tuple(renamed(value) for value in snapshot.direct_values)
+        entry_by_name = dict(snapshot.entry_by_name)
+        entry = entry_by_name.pop(old)
+        entry_by_name[new] = replace(entry, name=new, values=tuple(renamed(value) for value in entry.values))
+        return replace(snapshot, values=values, direct_values=direct_values, entry_by_name=entry_by_name)
+
+    def _updated_field(self, expected: RemoteSnapshot, current: RemoteSnapshot, name: str, field: str) -> RemoteSnapshot:
+        """Accept one successful field without accepting unrelated concurrent changes."""
+        key = remote_section(current, name) + "." + field
+        values = tuple(value for value in expected.values if value.key != key) + field_values(current, name, field)
+        direct_values = tuple(value for value in expected.direct_values if value.key != key) + field_values(current, name, field, direct=True)
+        return replace(expected, values=values, direct_values=direct_values)