sync(feat): Apply checkout policy and recovery

why: Configured targets and dirty policies must reach the native backend,
and retained recovery details must survive CLI reporting.

what:
- Forward immutable target and policy values without changing input
- Require --yes before any configured discard accesses a repository
- Preserve recovery tokens, states, conflicts, and ordered failures
- Keep target-drift warnings visible in interactive output
- Verify native target selection, dirty policy, and machine output

Author: tony

CHANGES

@@ -80,6 +80,14 @@ legacy options stop migration before it writes the configuration file.
 they rewrite and preserve entries pinned for that command.
 See {ref}`migration` for an upgrade example.
 
+#### Apply main checkout policy and retain recovery details
+
+Sync forwards the configured selector kind, remote, and drift/dirty policy
+to libvcs. Git preservation retains a recovery token after restoration or
+conflict. Human output shows retained material; JSON and NDJSON preserve its
+exact identity and operation outcomes. Configured discard requires `--yes`
+before repository access. See {ref}`cli-sync` and {ref}`migration`.
+
 #### Validate shared checkout targets
 
 `working_copy` and `worktrees` accept the same `branch`, `tag`, `commit`, or

MIGRATION

@@ -23,6 +23,19 @@ well.
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### Explicit checkout policy and sync results
+
+The main checkout passes its selector kind, remote, and `sync` policy to
+libvcs. Git defaults to aborting on local changes; choose `dirty: preserve`
+to retain and restore them. Configuring `dirty: discard` also requires
+`vcspull sync --yes` on each invocation.
+
+Python callers of `vcspull.cli.sync.update_repo` receive `SyncExecution`:
+use `.project` for the backend instance and `.result` for its complete
+`SyncResult`. Failures still raise `SyncFailedError`, whose `.result` now
+retains recovery tokens, conflicts, and operation outcomes. Programmatic
+discard requires `yes=True`.
+
 ### Exact numeric values
 
 Integer configuration fields accept values up to `9007199254740991`

docs/cli/sync.md

@@ -151,6 +151,39 @@ Use `--dry-run` or `-n` to:
 - Test pattern filters
 - Preview operations in CI/CD
 
+## Checkout policy
+
+Configure the main checkout independently of clone options:
+
+```yaml
+~/code/:
+  project:
+    repo: git+https://example.com/project.git
+    working_copy:
+      branch: main
+      sync:
+        drift: follow
+        dirty: preserve
+```
+
+`follow` resolves the configured target; `keep` and `warn` leave an existing
+checkout in place. The default dirty policy is `abort`. Git preservation
+retains staged, unstaged, and untracked changes in an owned stash and restores
+them after updating. Conflicts retain a recovery token instead of discarding
+local state. Keep other editors and VCS writers out of the checkout during sync.
+
+A configured `dirty: discard` requires explicit authorization on each call:
+
+```console
+$ vcspull sync project --yes
+```
+
+`--yes` authorizes an existing discard policy; it does not enable discard for
+other entries. Successful preservation and failures print the retained recovery
+location. JSON and NDJSON events include `update_state`, `preservation_state`,
+`recovery`, `conflicts`, and ordered `errors`. A recovery token stays available
+until explicitly released through libvcs; a failed operation never deletes it.
+
 ## JSON output
 
 Export sync operations as JSON for automation:

src/vcspull/_internal/sync.py

@@ -0,0 +1,61 @@
+"""Shared checkout settings and sync outcomes for CLI commands."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+from collections.abc import Mapping
+
+from libvcs import BaseSync, SyncPolicy, SyncResult, SyncTarget
+
+from vcspull.validator import validate_working_copy
+
+
+@dataclasses.dataclass(frozen=True)
+class SyncExecution:
+    """Keep the backend instance and its complete synchronization result."""
+
+    project: BaseSync
+    result: SyncResult
+
+
+def checkout_settings(
+    config: Mapping[str, t.Any] | None, *, worktree: bool = False
+) -> tuple[SyncTarget | None, SyncPolicy]:
+    """Translate a validated checkout without collapsing its selector kind.
+
+    >>> target, policy = checkout_settings({"tag": "v1", "sync": {"drift": "keep"}})
+    >>> target.tag, policy.drift
+    ('v1', 'keep')
+    >>> checkout_settings(None)
+    (None, SyncPolicy(drift='follow', dirty='abort'))
+    """
+    if config is None:
+        return None, SyncPolicy()
+    values = dict(config)
+    validate_working_copy(values, worktree=worktree)
+    target = SyncTarget(
+        **{
+            key: values[key]
+            for key in ("branch", "tag", "commit", "rev", "remote")
+            if key in values
+        }
+    )
+    return target, SyncPolicy(**values.get("sync", {}))
+
+
+def sync_result_data(result: SyncResult) -> dict[str, t.Any]:
+    """Serialize recovery identity and outcomes without exception objects.
+
+    >>> sync_result_data(SyncResult())["preservation_state"]
+    'not-needed'
+    """
+    return {
+        "update_state": result.update_state,
+        "preservation_state": result.preservation_state,
+        "recovery": dataclasses.asdict(result.recovery) if result.recovery else None,
+        "conflicts": [dataclasses.asdict(conflict) for conflict in result.conflicts],
+        "errors": [
+            {"step": error.step, "message": error.message} for error in result.errors
+        ],
+    }

src/vcspull/cli/__init__.py

@@ -532,6 +532,7 @@ def cli(_args: list[str] | None = None) -> None:
             log_file=getattr(args, "log_file", None),
             no_log_file=getattr(args, "no_log_file", False),
             panel_lines=getattr(args, "panel_lines", None),
+            yes=getattr(args, "yes", False),
         )
     elif args.subparser_name == "list":
         list_repos(