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

> Explore Oh-My-Pi's workspace isolation using APFS clonefile and btrfs reflinks. Learn how copy-on-write creates efficient task environments and falls back automatically.

- Repository: [Can Bölük/oh-my-pi](https://github.com/can1357/oh-my-pi)
- Tags: architecture
- Published: 2026-05-21

---

**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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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:**

```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:**

```rust
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:**

```json
{
  "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.