Carry local files and shared state into new worktrees (#2419)

* feat(server): support symlink worktree includes

* refactor(server): simplify worktree include handling

* fix(server): constrain worktree include traversal

* fix(server): clean up failed worktree branches

* fix(server): skip missing worktree include entries

* fix(server): make worktree includes best effort

* fix(server): skip failed worktree includes

* fix(server): harden worktree include planning

* fix(server): preserve reused worktree result shape

Materialization reports describe one creation attempt, not durable worktree identity. Carry them beside the worktree so newly created and reused results keep the same stable shape.

* fix(server): harden worktree include boundaries

Replace directory snapshots exactly, keep canonical Git metadata protected, report recovery skips, and only roll back branches owned before worktree creation.

* fix(server): follow safe include aliases

Traverse canonical in-checkout directory links during glob planning and treat coded revalidation failures as per-entry skips.

* fix(server): make include preflight race safe

Create fetched checkout refs atomically, retain overlapping copy entries for independent fallback, and protect the full managed-worktree base.

* fix(server): preserve staged recovery state

Validate completed directory snapshots, retain backups after failed restoration, and derive atomic ref guards from the repository object ID width.

* fix(server): preserve partial include progress

Keep safe glob matches, enforce recursive-directory types, validate staged roots, and retain OID guards through rollback.

---------

Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>

public-docs/worktrees.md

@@ -110,6 +110,46 @@ Both fields accept a multiline shell script or an array of commands; commands ru
 
 Commands run with the worktree as `cwd`. Use `$PASEO_SOURCE_CHECKOUT_PATH` to reach files in the original checkout (untracked config, local caches, etc).
 
+## .worktreeinclude
+
+Use a root-level .worktreeinclude to materialize local source-checkout files before
+worktree.setup runs. Each path is relative to the source checkout.
+
+    # Copy is the default.
+    .env.local
+    .cache/**
+
+    # Modes can also be explicit.
+    symlink node_modules
+    copy .tool-state/**
+
+Each line is `[copy|symlink] <path>`; the mode is optional and defaults to `copy`. Blank lines
+and whole-line comments are ignored. A single star matches within a path segment and a double
+star matches recursively; a directory ending in /\*\* materializes that directory as one
+recursive entry. Absolute paths, parent-directory paths, and .git paths are rejected.
+
+Copy entries are independent snapshots: a copied file or directory replaces an existing path on
+a later materialization. Symlink entries point directly at
+the live source file or directory, so changes through either path affect the same data. Paseo
+does not replace an existing file, directory, or different link with a symlink.
+
+Entries must resolve to regular files or directories. A top-level source symbolic link is
+dereferenced only when its canonical target remains inside the source checkout: `copy` snapshots
+that target and `symlink` links directly to it. Directory snapshots reject nested symbolic links
+so Paseo never writes through an unexpected path. A symlinked directory intentionally exposes its
+live source contents.
+
+Prefer paths ignored by the target branch. For a symlinked directory, use an ignore rule without
+a trailing slash (for example, node_modules, not node_modules/), because Git treats the link
+itself as a file. Unignored materialized paths appear in git status.
+
+On Windows, Paseo uses junctions for local directories. File links and network-directory links
+require Windows symbolic-link support. It never silently copies an explicit `symlink <path>`
+entry; enable Developer Mode or switch that entry to `copy <path>` if link creation fails.
+
+Archiving removes only the worktree's links, not their source targets. If the source path is
+later moved or deleted, a symlink becomes broken; Paseo does not repair it automatically.
+
 ## Scripts and services
 
 `scripts` are named commands you can run inside a worktree on demand. Mark one as a _service_ and Paseo supervises it as a long-running process, assigns it a port, and routes HTTP traffic to it through the daemon's reverse proxy.