Workspace Isolation on APFS, Btrfs, and Reflinks: Oh-My-Pi's Copy-on-Write Architecture

Oh-My-Pi's workspace isolation leverages APFS clonefile and Linux FICLONE reflinks to create instant, space-efficient task environments through copy-on-write semantics, automatically falling back to compatible backends when filesystem-specific features are unavailable.

Oh-My-Pi implements workspace isolation through its π‑iso Portable Abstraction Layer (PAL), enabling fast, copy-on-write task environments across macOS and Linux. The system selects appropriate filesystem mechanisms—APFS clonefile on macOS and reflink-capable backends like Btrfs on Linux—based on the task.isolation.mode configuration. Understanding the implications of workspace isolation on APFS, Btrfs, and reflinks reveals how the tool achieves O(1) snapshot performance while maintaining strict read-only source protection.

How the π‑iso PAL Implements Workspace Isolation

The π‑iso PAL creates a read-only lower view of the repository while materializing a writable merged directory for each task execution. This architecture ensures the original repository remains untouched while providing isolated mutation spaces.

In packages/coding-agent/src/task/worktree.ts, the parseIsolationMode function maps user-specified configuration strings to backend variants. When a task initializes, ensureIsolation iterates through a candidate list of backends, probing each for filesystem compatibility via ProbeResult::unavailable checks until it finds a functional mechanism.

APFS Clonefile Backend on macOS

On macOS volumes, the PAL utilizes the clonefile(2) system call through the implementation in crates/pi-iso/src/apfs.rs. This backend recursively copies the directory tree while sharing underlying blocks between source and destination.

Key implications:

• O(1) snapshot creation: Only metadata changes are written during the initial clone operation, making it extremely cheap on APFS volumes.
• No mount requirements: The destination becomes an independent tree that requires no kernel-level mounting; cleanup involves simple remove_dir_all operations.
• Platform exclusivity: When running on non-APFS volumes or non-macOS systems, the backend reports ProbeResult::unavailable, triggering automatic fallback to the next candidate.

Btrfs and Linux Reflink Backends

For Linux systems, the PAL implements reflink support in crates/pi-iso/src/linux_reflink.rs using the FICLONE ioctl. This mechanism clones regular files by sharing extents until modification occurs, while directories and symlinks are recreated normally.

Filesystem compatibility:

• Btrfs: Native reflink support enables full copy-on-write semantics.
• XFS and bcachefs: Supported when configured with reflink capabilities.
• OCFS2: Additional enterprise filesystem compatibility.

The backend recreates the directory structure and reflinks individual files, ensuring space-efficient isolation without kernel module dependencies or mount operations. Like the APFS backend, it reports unavailability when FICLONE is unsupported, allowing seamless degradation to overlayfs or rcopy implementations.

Backend Resolution and Fallback Strategy

The resolution logic in crates/pi-iso/src/lib.rs handles backend selection through the IsoBackendKind enum. When ensureIsolation executes, it probes the preferred backend first; if unavailable, it systematically attempts alternatives while exposing the fellBack boolean and fallbackReason string in the returned IsolationHandle.

Users explicitly configure backends via task.isolation.mode in the settings schema (defined in packages/coding-agent/src/config/settings-schema.ts), selecting from "apfs", "btrfs", "reflink", "overlayfs", or "auto" for automatic resolution.

Performance Characteristics and Safety Guarantees

Copy-on-write semantics: Both APFS clonefile and Linux reflink provide metadata-only operations until file modification occurs, delivering O(1) initialization complexity regardless of repository size. This dramatically reduces copy time and disk consumption compared to full recursive copies.

Isolation safety: The lower view remains strictly read-only, preventing task contamination of the source repository. The merged directory receives exclusive write permissions, and the PAL guarantees cleanup through iso_stop or equivalent removal functions, leaving the original workspace pristine.

Practical Implementation Examples

Configuring isolation mode in TypeScript:

// packages/coding-agent/src/task/example.ts
import { ensureIsolation } from "./worktree";
import { IsoBackendKind } from "@oh-my-pi/pi-iso";

async function runTask() {
  const isolation = await ensureIsolation(
    process.cwd(),
    "example-task",
    IsoBackendKind.Apfs,
  );

  console.log("Merged dir:", isolation.mergedDir);
  console.log("Backend used:", isolation.backend);
  console.log("Fallback occurred:", isolation.fellBack);
}

Direct Rust PAL invocation:

use pi_iso::{IsoBackendKind, iso_start, iso_stop};

fn main() -> Result<(), pi_iso::IsoError> {
    let backend = IsoBackendKind::LinuxReflink;
    let lower = "/path/to/repo";
    let merged = "/tmp/omp-task-merged";

    iso_start(backend, lower, merged)?;
    // Task execution occurs in merged directory...
    iso_stop(backend, merged)?;
    Ok(())
}

JSON configuration schema:

{
  "task": {
    "isolation": {
      "mode": "reflink"
    }
  }
}

Summary

• APFS clonefile provides instant snapshots on macOS through block-level sharing via clonefile(2), with automatic unavailability detection on non-APFS volumes.
• Linux reflink leverages FICLONE ioctl for extent sharing on Btrfs, XFS, and compatible filesystems, offering equivalent performance characteristics without mount requirements.
• Automatic fallback in ensureIsolation guarantees functional isolation by probing backend candidates sequentially and reporting fallback status through IsolationHandle.
• O(1) initialization occurs for both mechanisms until write operations trigger copy-on-write page duplication, optimizing both time and space complexity.
• Safety is enforced through read-only lower views and simple recursive cleanup of merged directories, ensuring repository integrity across task executions.

Frequently Asked Questions

What happens when workspace isolation is requested on a filesystem that doesn't support reflinks?

The π‑iso PAL probes the requested backend and receives ProbeResult::unavailable when the filesystem lacks support for clonefile (APFS) or FICLONE (btrfs/XFS). The resolver automatically falls back to the next available backend in the candidate list, such as overlayfs or a recursive copy implementation, while setting fellBack: true and providing a fallbackReason in the isolation handle.

How does Oh-My-Pi ensure the original repository remains unmodified during task execution?

The PAL creates a read-only "lower" view of the repository and materializes a separate writable "merged" directory for task mutations. All write operations occur exclusively within the merged directory, and the original repository is never mounted or opened in write mode. Cleanup simply removes the merged directory without touching the source files.

What is the performance difference between APFS clonefile and standard file copying?

APFS clonefile performs O(1) metadata operations regardless of file size, sharing underlying storage blocks between source and destination until either copy is modified. Standard copying requires O(n) data duplication, consuming both time and disk space proportional to the repository size. This difference becomes significant with multi-gigabyte repositories where clonefile completes in milliseconds while full copies may take minutes.

Can I force a specific isolation backend regardless of platform?

Yes, the task.isolation.mode configuration accepts explicit values including "apfs", "reflink", "btrfs", or "overlayfs". However, if the specified backend is unavailable on the current platform or filesystem, the system will either fail with a clear error or fall back automatically depending on the strictness of the configuration. Use "auto" to allow the PAL to select the optimal available backend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}