feat(server): support symlink worktree includes

[michaelmwu]

Closes #2420.

Problem

Git worktrees contain tracked files, but local ignored files and directories such as environment files, credentials, and caches are absent. Paseo setup scripts can copy them manually, but that duplicates boilerplate and cannot express intentionally shared state without hand-written platform-specific links.

What changed

• add root-level .worktreeinclude support before worktree.setup
• keep bare entries as copies and accept explicit copy <path> / symlink <path> modes
• support literal files and directories plus the existing *, **, and directory/** pattern semantics explored in feat(server): support worktree include files #1772
• make include configuration best-effort: missing paths, unmatched patterns, malformed entries, unsafe sources, incompatible include overlaps, destination conflicts, unavailable platform links, and normal filesystem failures skip only that entry; the daemon logs a structured summary and continues with safe entries
• skip ordinary source filesystem errors during glob matching and safety scans per entry, retaining other viable entries
• resolve source symlinks to canonical in-checkout targets: copy makes a snapshot of that target, while symlink creates one direct live link to it rather than a link-to-link; hard links remain ordinary files
• preserve includes when the active source is already a Paseo-managed worktree, while keeping all paths outside that source checkout protected
• revalidate sources immediately before materialization, including directory links and protected Paseo worktree storage; an entry that becomes unsafe is skipped
• stage each materialization before committing it to the worktree; for an existing copy destination, restore its backup if the overlay fails
• remove a fetched checkout branch when preflight fails before worktree creation, and include it in later rollback when necessary
• treat only an inability to safely clean partial materialization state as fatal to creation; Git worktree creation and later setup failures retain their existing rollback behavior
• use relative links on POSIX; on Windows, use junctions for local directories and native symlinks for files or network directories
• document copy snapshots, shared-link lifecycle, Git ignore behavior, cleanup, and the reduced isolation boundary

Example:

.env.local
copy .tool-state/**
symlink node_modules

The verb-prefix form follows an existing public .worktreeinclude implementation in nubjs/nub. Bare entries remain copy-compatible.

Policy

An include may read only from the active source checkout. If that checkout is itself Paseo-managed, its own paths remain eligible; sibling and external managed-worktree paths remain protected. External or dangling symlinks, traversal, .git, special files, and destination-link escapes are not materialized. A safe entry is never blocked by an unrelated include failure. Paseo removes staged output for a failed entry and continues; it aborts only when it cannot safely restore or clean up partial state.

Prior discussion

Inspired by and intended to supersede the abandoned copy-only implementation in #1772.

QA

Focused local macOS verification:

• npx vitest run packages/server/src/utils/worktree-include.test.ts --bail=1 --reporter=verbose — 17 passed, 1 Windows-only test skipped
• npx vitest run packages/server/src/utils/worktree.posix.test.ts --bail=1 --reporter=verbose — 49 passed, 1 macOS-only test skipped
• npm run typecheck
• targeted npm run lint -- ...
• npm run format:check
• the commit hook reran lint, formatting, and typecheck successfully

Windows link behavior retains host-gated real-filesystem coverage but was not exercised locally; CI should run that case on Windows.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 961b8e07b4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7cc6cdb118

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 07ef5cee67

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 45cb4bb57a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dce2ae5ffe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".