worktree(feat): Apply native checkout policy

why: Existing pinned worktrees could stay at the wrong commit, and dirty
policy and retained recovery results did not reach worktree execution.

what:
- Resolve typed targets and use native Git policy for linked checkouts
- Carry parent transport options, remotes, and explicit detach behavior
- Authorize discard before included main-checkout mutations
- Retain successful and failed recovery results in both CLI entrypoints
- Cover native positions, state, creation, and structured output

Author: tony

CHANGES

@@ -52,6 +52,19 @@ worker and native process group before further work. Interrupted results
 retain unknown state and report discovered recovery tokens in human and
 machine output. CLI synchronization requires POSIX process groups.
 
+#### Apply checkout policy to linked worktrees
+
+{ref}`cli-worktree-sync` and {ref}`cli-sync` with `--include-worktrees`
+resolve typed targets, honor drift and dirty policy, and retain native
+recovery results. Existing tag and commit checkouts move when their target
+changes. Parent Git options, selected remotes, and explicit detachment apply
+to worktree updates. Missing worktrees use native linked-worktree creation.
+
+Configured discard requires `--yes`; included worktree policies are checked
+before the main checkout changes. JSON and NDJSON retain exact recovery
+locations after restoration or conflict, and human output shows recovery
+identity. Read-only worktree planning never fetches.
+
 #### Configure partial clones and typed backend options
 
 `git`, `hg`, and `svn` blocks match their libvcs options classes. Loading

docs/cli/worktree/index.md

@@ -40,7 +40,7 @@ prune
 
 Worktrees are configured as a list under a repository entry. Each worktree
 requires a `dir` (relative to workspace root or absolute) and exactly one
-ref type: `tag`, `branch`, or `commit`.
+ref type: `tag`, `branch`, `commit`, or native `rev`.
 
 ```yaml
 ~/code/:
@@ -68,12 +68,17 @@ ref type: `tag`, `branch`, or `commit`.
 |-------|----------|-------------|
 | `dir` | yes | Worktree path (relative to workspace root or absolute) |
 | `tag` | one of | Tag to checkout (creates detached HEAD) |
-| `branch` | one of | Branch to checkout (can be updated/pulled) |
+| `branch` | one of | Branch to follow with fast-forward updates |
 | `commit` | one of | Commit SHA to checkout (creates detached HEAD) |
+| `rev` | one of | Native revision expression; attachment follows its resolved kind |
+| `remote` | no | Fetch source for a branch target |
+| `sync` | no | Drift and dirty policies described in {ref}`cli-worktree-sync` |
+| `detach` | no | Keep the resolved target detached, including a branch |
 | `lock` | no | Lock the worktree to prevent accidental removal |
 | `lock_reason` | no | Reason for locking (implies `lock: true`) |
 
-Exactly one of `tag`, `branch`, or `commit` must be specified per entry.
+Exactly one of `tag`, `branch`, `commit`, or `rev` must be specified per entry.
+Worktrees inherit the parent repository's Git transport options and remotes.
 
 ## Integration with vcspull sync
 
@@ -111,7 +116,7 @@ Each worktree entry emits:
   "action": "unchanged",
   "exists": true,
   "is_dirty": false,
-  "detail": "tag worktree already exists",
+  "detail": "already at configured target",
   "error": null
 }
 ```
@@ -133,13 +138,17 @@ log aggregation.
 
 vcspull refuses to touch work it could destroy:
 
-**Uncommitted changes stop updates.** If a worktree has uncommitted changes,
-vcspull will not update or remove it — commit or stash first. These entries
-show as blocked (`⚠`) in {ref}`vcspull worktree list <cli-worktree-list>`.
+**Dirty policy governs updates.** Updates abort on local changes by default.
+Configure `sync.dirty: preserve` to retain and restore them, or configure
+`discard` and pass `--yes` to authorize their removal. See
+{ref}`cli-worktree-sync` for recovery output and drift policy. Worktree
+pruning still refuses dirty checkouts.
 
 **Unknown refs stop creation.** If a configured tag, branch, or commit
-doesn't exist in the repository, the entry is reported as an error (`✗`)
-rather than guessed at. Fetch from the remote to make the ref available.
+cannot be resolved, the entry is reported as an error (`✗`). Preview and
+list operations only inspect local metadata. Creating a missing worktree
+requires a locally available target; existing worktrees can fetch during
+follow synchronization.
 
 **Locks guard against removal.** Worktrees created with `lock: true` or
 `lock_reason` are locked via `git worktree lock`, preventing accidental

docs/cli/worktree/sync.md

@@ -22,15 +22,43 @@ Sync all configured worktrees:
 $ vcspull worktree sync '*'
 ```
 
-The sync subcommand:
-- Creates missing worktrees at the configured `dir`
-- Pulls latest changes for `branch` worktrees
-- Leaves `tag` and `commit` worktrees unchanged (they're immutable)
-- Skips worktrees with uncommitted changes (BLOCKED)
+Missing worktrees require locally available target metadata and use Git's
+linked-worktree operation. Existing
+worktrees follow their configured `branch`, `tag`, `commit`, or native `rev`;
+changing a tag or commit target moves the checkout to that resolved commit.
+Branch updates are fast-forward only. A matching commit is not drift, even
+when its branch or tag name differs. `detach: true` keeps a branch target
+detached, and `remote` chooses the branch's fetch source.
+
+Each worktree accepts the same `sync` policies as {ref}`cli-sync`:
+`drift: keep` leaves an existing checkout untouched; `drift: warn` also logs
+when its resolved target differs. The default `dirty: abort` blocks updates
+with local changes. `dirty: preserve` retains native recovery material and
+restores changes, including the Git index. Conflicts retain their recovery
+token and make the operation fail.
+
+`dirty: discard` requires explicit invocation consent, including clean or
+missing checkouts:
+
+```console
+$ vcspull worktree sync --yes '*'
+```
+
+For {ref}`cli-sync` with `--include-worktrees`, the same `--yes` authorizes
+configured discard. Worktree consent is checked before the main checkout
+changes. Main and linked checkouts are synchronized serially.
+
+Both commands print retained recovery identity after success or failure.
+JSON and NDJSON include update/preservation states, ordered errors,
+conflicts, and the exact token location required by libvcs recovery. Tokens
+remain retained until explicitly released through libvcs; synchronization
+does not automatically restore interrupted operations into their source.
 
 ## Dry run
 
-Preview what would happen without making changes:
+Preview local target metadata without fetching or changing checkouts. An
+unavailable target produces an error plan; execution may resolve it after
+fetching:
 
 ```console
 $ vcspull worktree sync --dry-run '*'

src/vcspull/_internal/sync.py

@@ -14,6 +14,7 @@
 from libvcs.sync.hg import HgOptions
 from libvcs.sync.svn import SvnOptions
 
+from vcspull import exc
 from vcspull.validator import validate_working_copy
 
 
@@ -91,3 +92,10 @@ def sync_result_data(result: SyncResult) -> dict[str, t.Any]:
             {"step": error.step, "message": error.message} for error in result.errors
         ],
     }
+
+
+def require_discard_authorization(policy: SyncPolicy, *, allow_discard: bool) -> None:
+    """Require explicit invocation consent before constructing a discard backend."""
+    if policy.dirty == "discard" and not allow_discard:
+        message = "dirty: discard requires --yes before synchronization"
+        raise exc.VCSPullException(message)