Use filesystem clones for .worktreeinclude copies in local managed worktrees (APFS/reflinks)

What variant of Codex are you using?

Codex desktop app on macOS/APFS. Observed in version 26.908.70816, build 9275.

What feature would you like to see?

Please use filesystem copy-on-write clones when copying ignored files selected by .worktreeinclude into local managed worktrees, where the source and destination filesystem support them.

On macOS/APFS, this would let each worktree have independently writable files while initially sharing the source file's physical storage. Large local databases, response caches and build artefacts could be available immediately without allocating another full physical copy for every task.

The existing .worktreeinclude patterns and exclusions should continue to work unchanged. Prefer native cloning on supported filesystems, retain the existing destination-exists behaviour, and fall back to ordinary copying when cloning is unavailable. Clones must remain independent files: edits in one worktree must not change the source checkout or another worktree.

Why this matters

Our repository includes several multi-gigabyte local caches in .worktreeinclude so new worktrees can reuse expensive cached results. Codex copies these files before its environment setup script or agent starts. Consequently, even a setup script that subsequently replaces the copies with APFS clones cannot prevent the initial full-copy disk allocation.

Inspection of the installed app's local copy path showed fs.promises.copyFile(source, destination, COPYFILE_EXCL), without a clone request. Physical-address measurements confirmed that the resulting files did not share sampled storage with the source.

Claude Code comparison

Claude Code already supports the .worktreeinclude feature for bringing ignored local files into new worktrees, and supports custom worktree creation/setup through hooks. We use a clone-based worktree provisioning workflow with Claude Code on the same APFS machine. Please support this disk-efficient workflow directly in Codex's built-in .worktreeinclude copy step, without requiring users to replace already-allocated copies afterwards.

References: Claude Code worktrees and .worktreeinclude and worktree hooks.

For precision, these documentation links establish Claude Code's inclusion and hook support; they do not document a guarantee that every built-in Claude Code copy uses a filesystem clone.

Additional information

Measured evidence

In one disposable Codex-managed worktree, we measured three production cache files before and after replacing Codex's initial copies with macOS cp -c clones:

The read-only probe used F_LOG2PHYS_EXT at corresponding offsets every 16 MiB. All 486 sampled addresses shared after cloning. This is sampled physical-storage evidence, not exhaustive extent accounting or a disk-usage estimate based solely on logical file sizes.

Our initial setup replaced 14 registered cache databases with clones; a rerun preserved them and replaced zero. That workaround removes persistent duplication, but it cannot avoid Codex's initial allocation. The validation worktree was removed immediately afterwards.

Suggested acceptance criteria

• A fresh local managed worktree on APFS receives clone-backed files matching .worktreeinclude, without first allocating full ordinary copies.
• Changing a destination file leaves the source and sibling worktrees unchanged.
• Existing pattern filtering, exclusions and destination-exists handling remain intact.
• Unsupported filesystems or cross-filesystem destinations retain a working ordinary-copy fallback.
• Validate storage sharing with a physical-extent/address probe; matching bytes or logical du sizes alone do not establish cloning.

Related reports: #42339 concerns .worktreeinclude enumeration of large ignored trees; #35383 concerns accumulating worktree/temp copies. This request specifically concerns clone-backed copying during initial managed-worktree provisioning.

Start at the local managed-worktree copy path described in the issue, where fs.promises.copyFile uses COPYFILE_EXCL, and trace how .worktreeinclude patterns, exclusions, and destination-exists handling are applied. Verify native filesystem cloning on APFS, preserve ordinary-copy fallback for unsupported or cross-filesystem cases, and test that destination edits remain independent while the existing filtering behavior is unchanged.