stablyai / stablyai/orca

[Feature]: Use ReFS block cloning for Windows worktree shared paths

Open
#16,618 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
69.7k
Forks
4.5k
Avg merge
15h 28m
Merged PRs (30d)
471

Description

### Problem or use case

On Windows, Worktree Shared Paths fall back to symlinks or junctions even when the primary checkout and new worktree are on the same ReFS volume. That misses ReFS block cloning, which can materialize large paths quickly without initially duplicating their data blocks, while still giving the new worktree an independent copy-on-write view.

The same limitation affects `.worktreeinclude`: Windows either performs a full byte copy or rejects a large path through the copy budget, even when ReFS can clone it cheaply.

### Proposed solution

When Orca materializes a configured path on Windows, probe the source and destination volumes. If both paths are on the same ReFS volume, clone file extents with `FSCTL_DUPLICATE_EXTENTS_TO_FILE`; otherwise preserve the current symlink, junction, or real-copy fallback.

The Windows-only implementation should remain runtime-guarded, leave the existing macOS APFS behavior unchanged, preserve the always-shared semantics of `orca.yaml` `worktree.sharedDirectories`, and package the native helper with production builds.

### Alternatives or additional context

- Always use symlinks or junctions: fast, but worktree writes affect the shared source.
- Always make a real copy: independent, but slow and disk-intensive for large dependency or build directories.
- Limit this to `.worktreeinclude`: this would not improve user-configured Worktree Shared Paths.

I verified the proposed approach on a healthy ReFS volume with a non-cluster-aligned file. The cloned extents reported reference count `2`, the source and target hashes matched after cloning, and modifying the target left the source unchanged.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the Windows path-materialization code for configured paths, then compare how .worktreeinclude and orca.yaml worktree.sharedDirectories are handled. Read the existing symlink, junction, and real-copy fallbacks before investigating the runtime-guarded FSCTL_DUPLICATE_EXTENTS_TO_FILE helper and production packaging. Done means same-volume ReFS paths use copy-on-write cloning while other platforms and fallbacks retain their current behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
devtools, operating-systems, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.