opencode2-cow-worktree 0.1.0

package/src/device.ts

@@ -0,0 +1,98 @@
+/**
+ * The shared filesystem primitives both layers of the plugin sit on: the tool
+ * (`spawn_workspace`'s pre-create device guard) and the strategy (the `cow`
+ * create pre-flight). Both need the same device-identity questions answered,
+ * so the primitives live here — a module neither layer owns — instead of the
+ * strategy importing them from the tool layer, which would invert the
+ * layering: the tool composes the strategy; the strategy must not import from
+ * it.
+ *
+ * Policy lives above these primitives: `verifySameDevice` and
+ * `verifyCowSameDevice` — which mechanisms the device rule applies to — are
+ * tool-layer decisions and stay in `tool.ts`.
+ */
+import { stat } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * The device a path's filesystem belongs to, or `undefined` when it cannot be
+ * read (a path that does not exist yet, or a permission failure).
+ */
+export async function deviceOf(path: string): Promise<number | undefined> {
+  try {
+    const stats = await stat(path);
+    return stats.dev;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The actionable `cow` failure for a clone whose target sits on a different
+ * filesystem than its source. A reflink cannot cross a device boundary, so the
+ * remedy is always to move the target — never to fall back silently.
+ *
+ * Shared by the tool's pre-create guard and the strategy's own pre-flight so
+ * the two name the same cause and the same fix.
+ */
+export function crossDeviceError(source: string, target: string): Error {
+  return new Error(
+    `cow cannot clone ${source} into ${target}: the target is on a different ` +
+      "filesystem and a reflink cannot cross devices. Point opencode2's " +
+      "`worktree.directory` config or the `targetRoot` plugin option (opencode.json) " +
+      "at a directory on the source's filesystem.",
+  );
+}
+
+/**
+ * The one cross-device rule: a `cow` clone may cross no device boundary.
+ * `undefined` on either side is unknown, not a mismatch.
+ */
+export function assertSameDevice(
+  source: string,
+  sourceDevice: number | undefined,
+  target: string,
+  targetDevice: number | undefined,
+): void {
+  if (
+    sourceDevice === undefined ||
+    targetDevice === undefined ||
+    sourceDevice === targetDevice
+  ) {
+    return;
+  }
+  throw crossDeviceError(source, target);
+}
+
+/**
+ * Resolves a target that may not exist yet to the first ancestor whose device
+ * can be read, so the strategy's pre-flight checks the filesystem the target
+ * will actually land on. The root's parent is itself, so the walk terminates;
+ * a fully unreadable chain returns `undefined` and the pre-flight proceeds.
+ */
+export async function nearestExistingDevice(
+  path: string,
+  probeDevice: (path: string) => Promise<number | undefined>,
+): Promise<number | undefined> {
+  let current = path;
+  for (;;) {
+    const device = await probeDevice(current);
+    if (device !== undefined) return device;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+/**
+ * Whether a path exists and is a directory. The live binding for the tool's
+ * `isDirectory` seam, alongside `deviceOf`: a path occupied by a file and a
+ * path that is not there at all are the same answer — no existing Worktree.
+ */
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/dirty.ts

@@ -0,0 +1,54 @@
+/**
+ * The decision half of `cow`'s `remove`, kept pure — in the style of
+ * `entry-kind.ts` — so the refusal table can be tested without a filesystem or
+ * a git repository.
+ *
+ * opencode2's `force` means "proceed despite uncommitted changes", which is not
+ * `node:fs` `rm`'s `force` ("ignore a nonexistent path"). The built-in `git`
+ * strategy maps it to `git worktree remove --force` and refuses when the
+ * worktree is dirty; `cow` must refuse at `force: false` for the same reason,
+ * or it silently deletes uncommitted work.
+ *
+ * A probe that cannot answer (no git metadata, a failing or timed-out `git`, a
+ * machine without git) yields `undefined`, which is deliberately treated as
+ * dirty: deleting on an unknown is the data loss this guards against.
+ */
+
+/** The changed paths the probe found, or `undefined` when it could not tell. */
+export type UncommittedChanges = readonly string[] | undefined;
+
+/** Whether `remove` may proceed, and why not when it may not. */
+export type RemoveDecision =
+  | { readonly remove: true }
+  | { readonly remove: false; readonly reason: string };
+
+/** How many changed paths the refusal names as examples. */
+const EXAMPLE_PATHS = 3;
+
+/**
+ * Decides whether `remove` may delete a directory.
+ *
+ * `force: true` is the user's confirmation and always allows removal.
+ * Otherwise a non-empty change list refuses, and so does `undefined` — an
+ * unknown dirty state is never safe to delete. Only a probe that positively
+ * reported no changes allows removal.
+ */
+export function mayRemove(input: {
+  readonly force: boolean;
+  readonly uncommitted: UncommittedChanges;
+}): RemoveDecision {
+  if (input.force) return { remove: true };
+  if (input.uncommitted === undefined) {
+    return {
+      remove: false,
+      reason:
+        "its uncommitted changes could not be determined (no git metadata, or the git probe failed)",
+    };
+  }
+  if (input.uncommitted.length === 0) return { remove: true };
+  const examples = input.uncommitted.slice(0, EXAMPLE_PATHS).join(", ");
+  return {
+    remove: false,
+    reason: `${input.uncommitted.length} uncommitted change(s) (e.g. ${examples})`,
+  };
+}

package/src/entry-kind.ts

@@ -0,0 +1,36 @@
+/**
+ * How a directory entry is materialised by the clone walker, kept a pure
+ * decision so it can be tested without a real filesystem.
+ *
+ * `readdir` reports an entry's type on the filesystems this tool targets, but
+ * the POSIX contract allows it to report UNKNOWN (all of `isSymbolicLink`,
+ * `isDirectory` and `isFile` false). When that happens `stat` is the
+ * authoritative fallback; it must be `lstat`, which never follows a symlink,
+ * or a link would be classified by its target.
+ */
+
+/** How a directory entry is materialised by the clone walker. */
+export type EntryKind = "file" | "directory" | "symlink";
+
+/** The slice of a `readdir` Dirent this decision reads. */
+export interface EntryLike {
+  isSymbolicLink(): boolean;
+  isDirectory(): boolean;
+  isFile(): boolean;
+}
+
+/** The slice of `lstat` this decision reads; `lstat` never follows a symlink. */
+export interface StatLike {
+  isSymbolicLink(): boolean;
+  isDirectory(): boolean;
+}
+
+export async function entryKind(entry: EntryLike, stat: () => Promise<StatLike>): Promise<EntryKind> {
+  if (entry.isSymbolicLink()) return "symlink";
+  if (entry.isDirectory()) return "directory";
+  if (entry.isFile()) return "file";
+  const stats = await stat();
+  if (stats.isSymbolicLink()) return "symlink";
+  if (stats.isDirectory()) return "directory";
+  return "file";
+}

package/src/hooks.ts

@@ -0,0 +1,216 @@
+/**
+ * The post-create hook runner — the impure tail of the `cow` create flow.
+ *
+ * Commands the plugin option `hooks.postCreate` configures, run against every
+ * Worktree the strategy materializes — the tail of the create flow, so every
+ * entry path (the HTTP API, the TUI, and the `spawn_workspace` tool, which
+ * registers the same strategy object) gets them. Attach never reaches this
+ * code: it binds a session to an existing directory and clones nothing.
+ *
+ * Split out of `strategy.ts` so the strategy is the thin
+ * composition layer: it closes over the validated hook list and calls
+ * `runPostCreateHooks` after a successful clone; this module owns the
+ * mechanics of running the commands and turning a failure into the
+ * leave-nothing-behind error.
+ */
+import { execFile } from "node:child_process";
+import type { ExecFileOptionsWithStringEncoding } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+/**
+ * Runs the configured hooks sequentially against a freshly cloned worktree.
+ *
+ * Each command runs via `sh -c`, with the worktree as its cwd and
+ * `COW_WORKTREE_PATH` / `COW_SOURCE_DIRECTORY` (both absolute) in its
+ * environment, so a command that needs a per-project value can read one. The
+ * first failure aborts creation: the just-created clone is removed — the same
+ * leave-nothing-behind contract as the clone's own failure path — and the
+ * error names the failed command and its 1-based step.
+ */
+export async function runPostCreateHooks(
+  postCreate: readonly string[],
+  worktree: string,
+  sourceDirectory: string,
+): Promise<void> {
+  for (const [index, command] of postCreate.entries()) {
+    try {
+      await runHookCommand(command, worktree, sourceDirectory);
+    } catch (cause) {
+      throw await failedCreate(worktree, command, index + 1, postCreate.length, cause);
+    }
+  }
+}
+
+/**
+ * Turns a hook failure into the create flow's error, after the same
+ * leave-nothing-behind cleanup as the clone's own failure path. The in-place
+ * `rm` — not the quarantine of src/removal.ts — is acceptable here:
+ * the directory is a seconds-old clone the strategy itself just created, so
+ * the provenance is known and there is no audit gap to protect. When the
+ * cleanup itself fails, the hook error still wins: the message keeps the
+ * command, step, and output, notes the failed cleanup, and names where the
+ * remains are.
+ */
+async function failedCreate(
+  worktree: string,
+  command: string,
+  step: number,
+  total: number,
+  cause: unknown,
+): Promise<Error> {
+  const failure = hookFailure(command, step, total, cause);
+  try {
+    await rm(worktree, { recursive: true, force: true });
+  } catch (cleanup) {
+    const detail = cleanup instanceof Error ? cleanup.message : String(cleanup);
+    return new Error(
+      `${failure.message} Removing the worktree also failed (${detail}), so ` +
+        `the remains are left at ${worktree}.`,
+      { cause },
+    );
+  }
+  return failure;
+}
+
+/**
+ * How long one post-create command may run before it is killed and counts as a
+ * failure, with the same cleanup as any other failure. The primary use case is
+ * dependency installation — a cold `corepack use pnpm@latest` or
+ * `bun install` can legitimately run for minutes — so the budget is generous;
+ * a command that still hangs after five minutes is stuck, not slow.
+ */
+const HOOK_TIMEOUT_MS = 300_000;
+
+/**
+ * How much of a hook's combined output `execFile` may buffer before the
+ * command is rejected as an output-limit failure. Node's default, made
+ * explicit so the failure message can name the number.
+ */
+const HOOK_MAX_BUFFER = 1024 * 1024;
+
+/**
+ * Runs one hook command. Exported as the seam the timeout test drives with a
+ * short explicit timeout — the production path always uses `HOOK_TIMEOUT_MS`
+ * through the default parameter, like `probeUncommitted`'s injected seam.
+ *
+ * The command gets no stdin: the script opens with `exec 0</dev/null`, and
+ * `stdio[0] = "ignore"` backs it up on runtimes that honor it (Bun 1.4.2 does
+ * not — without the redirect, a hook that reads stdin hangs to the timeout).
+ * `worktree` and `sourceDirectory` are resolved to absolute before they reach
+ * the cwd or the environment, so the absolute-path contract holds by
+ * construction whatever the caller handed over.
+ */
+export async function runHookCommand(
+  command: string,
+  worktree: string,
+  sourceDirectory: string,
+  timeoutMs: number = HOOK_TIMEOUT_MS,
+): Promise<void> {
+  const worktreePath = resolve(worktree);
+  const sourcePath = resolve(sourceDirectory);
+  // `execFile`'s types omit `stdio` (its promise overloads assume piped
+  // streams), but the runtime accepts it; stdin "ignore" backs up the
+  // in-script redirect on runtimes that honor it — Bun 1.4.2 does not.
+  const options = {
+    cwd: worktreePath,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    maxBuffer: HOOK_MAX_BUFFER,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      COW_WORKTREE_PATH: worktreePath,
+      COW_SOURCE_DIRECTORY: sourcePath,
+    },
+  } as unknown as ExecFileOptionsWithStringEncoding;
+  await run("sh", ["-c", `exec 0</dev/null; ${command}`], options);
+}
+
+/**
+ * What `execFile`'s rejection carries about a failed, signalled, or killed
+ * command — the shapes Bun 1.4.2 actually produces (probed at runtime):
+ *
+ * - exit failure: `code` is the numeric exit status, `signal` absent or null.
+ * - signal death: `signal` is the signal name, `code` null, `killed` false.
+ * - timeout kill: `killed` true, `signal` "SIGTERM", `code` null.
+ * - output past `maxBuffer`: `code` names the limit (Bun:
+ *   "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"; Node: "ENOBUFS").
+ */
+interface CommandFailure {
+  readonly killed?: boolean;
+  readonly signal?: unknown;
+  readonly code?: unknown;
+  readonly stdout?: unknown;
+  readonly stderr?: unknown;
+}
+
+/**
+ * The codes `execFile` rejects with when a stream exceeds `maxBuffer`, across
+ * the runtimes this plugin runs on.
+ */
+const MAXBUFFER_CODES = new Set(["ERR_CHILD_PROCESS_STDIO_MAXBUFFER", "ENOBUFS"]);
+
+/**
+ * Why a hook command failed, ordered by what the real rejection shapes decide
+ * it: an output-limit rejection names itself in `code` before anything else;
+ * `killed` separates the timeout kill (which also carries a signal) from a
+ * signal death; a numeric `code` is an exit status. The "300s" wording is
+ * truthful everywhere this can be produced: `hookFailure` is only reached
+ * through `runPostCreateHooks`, which always runs hooks with the
+ * `HOOK_TIMEOUT_MS` default — the injected-timeout seam bypasses it.
+ */
+function failureReason(failure: CommandFailure): string {
+  const code = failure.code;
+  if (typeof code === "string" && MAXBUFFER_CODES.has(code)) {
+    return "output limit exceeded (1 MiB)";
+  }
+  if (failure.killed) return "timed out after 300s";
+  if (failure.signal != null) return `terminated by ${String(failure.signal)}`;
+  if (typeof code === "number") return `exit code ${code}`;
+  return `terminated by ${String(code)}`;
+}
+
+/**
+ * The hook failure: which command, which 1-based step, how it failed, and —
+ * because a hook's output is the only record of what a failed setup tried to
+ * say — its captured stdout and stderr.
+ */
+function hookFailure(
+  command: string,
+  step: number,
+  total: number,
+  cause: unknown,
+): Error {
+  const failure = cause as CommandFailure;
+  return new Error(
+    `post-create hook failed (step ${step} of ${total}): ${command} ` +
+      `(${failureReason(failure)})` +
+      capturedOutput(failure),
+    { cause },
+  );
+}
+
+/** How much of a failed hook's combined output an error message carries. */
+const CAPTURE_LIMIT = 2048;
+
+/**
+ * The captured stdout and stderr of a failed hook; absent when both are empty.
+ * A hook's output is the only record of what a failed setup tried to say, but
+ * a megabyte of it does not belong inside an error message, so past
+ * `CAPTURE_LIMIT` only the last chunk is kept, behind a truncation marker.
+ */
+function capturedOutput(failure: CommandFailure): string {
+  const streams = [failure.stdout, failure.stderr]
+    .map((stream) => (typeof stream === "string" ? stream.trim() : ""))
+    .filter((stream) => stream !== "");
+  if (streams.length === 0) return "";
+  const capture = streams.join("\n");
+  if (capture.length > CAPTURE_LIMIT) {
+    return `\n--- output ---\n…output truncated…\n${capture.slice(-CAPTURE_LIMIT)}`;
+  }
+  return `\n--- output ---\n${capture}`;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./plugin";

package/src/mechanism.ts

@@ -0,0 +1,9 @@
+/**
+ * Which mechanism produced a Worktree directory.
+ *
+ * `cow` is a Deep clone (extents shared with the source, ignored files
+ * carried); `git` is a Shallow worktree produced by opencode2's built-in
+ * strategy. The value is reported to the caller so an agent that relies on
+ * ignored state knows whether it actually has it.
+ */
+export type Mechanism = "cow" | "git";

package/src/platform-darwin-ffi.ts

@@ -0,0 +1,142 @@
+/**
+ * The real macOS `copyfile(3)` binding, isolated from the decision logic in
+ * `platform-darwin.ts`.
+ *
+ * This module is inert on import: importing `bun:ffi` is fine on Linux, and
+ * nothing here calls `dlopen`. The library is loaded only when
+ * `loadCopyfileLibrary()` is called, which happens only when a Darwin process
+ * actually selects this backend. On Linux that call fails, because
+ * `/usr/lib/libSystem.B.dylib` does not exist.
+ *
+ * LIMITATIONS, stated plainly because the real `copyfile(3)` cannot be executed
+ * here (only the loader seam can be exercised):
+ *
+ * - `bun:ffi` does not throw on a failing C call and does not populate
+ *   `.code`; it returns the raw result and leaves `errno` for the caller. The
+ *   errno must therefore be read explicitly through `__error()` and mapped to a
+ *   name. (This behavior was confirmed locally against `libc.so.6`: a failing
+ *   `open(2)` returned `-1` with no thrown error and no `.code`.)
+ * - `COPYFILE_STATE_WAS_CLONED` is a *state* query, not a return bit. With
+ *   `COPYFILE_CLONE_FORCE`, a 0 return already means the clone happened (the
+ *   flag fails rather than falls back), so no state handle is needed.
+ * - None of this is verified against a real `copyfile(3)`; that requires a
+ *   human on real APFS hardware.
+ */
+import { dlopen, FFIType, read } from "bun:ffi";
+import { DARWIN_CLONE_FLAGS } from "./platform-darwin";
+import type { DarwinCloneSyscall } from "./platform-darwin";
+
+/** The `copyfile(3)` / `__error(3)` entry points this binding needs. */
+export interface CopyfileLibrary {
+  readonly copyfile: (
+    source: string,
+    destination: string,
+    state: null,
+    flags: number,
+  ) => number;
+  readonly __error: () => number;
+}
+
+/**
+ * The loader seam, modelled on `dlopen` itself so the real call is exercised by
+ * a test with a recording stand-in.
+ */
+export type LibraryLoad = (
+  path: string,
+  definitions: unknown,
+) => { readonly symbols: unknown };
+
+/**
+ * The `bun:ffi` definition for libSystem's `copyfile` and its errno accessor
+ * (XNU bsd/sys/errno.h: `#define errno (*__error())`).
+ */
+const COPYFILE_DEFINITION = {
+  copyfile: { args: ["cstring", "cstring", "ptr", "u32"], returns: "i32" },
+  __error: { args: [], returns: FFIType.ptr },
+} as const;
+
+/**
+ * The resolved binding, held for the process lifetime. `cloneFileOnDarwin`
+ * resolves the syscall per file, so without this cache `dlopen` would run on
+ * every cloned file. libSystem is a loaded image rather than a library that is
+ * opened, so this is not a correctness issue — but the handle is also never
+ * `dlclose`d on purpose, because `copyfile` is called through a small libc
+ * trampoline and unloading libSystem while it is still mapped would be a
+ * use-after-free. Caching states that intent instead of leaving it to the
+ * refcount.
+ */
+let loaded: CopyfileLibrary | undefined;
+
+/**
+ * Loads the macOS `copyfile(3)` binding out of libSystem, once per process.
+ *
+ * The `load` seam defaults to the real `dlopen`, so production code loads the
+ * library while a test can inject a recording stand-in and inspect the exact
+ * call.
+ */
+export function loadCopyfileLibrary(
+  load: LibraryLoad = dlopen as unknown as LibraryLoad,
+): CopyfileLibrary {
+  loaded ??= load("/usr/lib/libSystem.B.dylib", COPYFILE_DEFINITION).symbols as CopyfileLibrary;
+  return loaded;
+}
+
+/**
+ * Drops the cached binding so the next resolution calls `load` again. The
+ * cache itself is process-lifetime by design (see above); the reset exists so
+ * a test that injected a stand-in cannot leak it into later tests and make
+ * the suite order-dependent.
+ */
+export function resetCopyfileLibrary(): void {
+  loaded = undefined;
+}
+
+/**
+ * Darwin errno numbers relevant to a clone. The header is XNU
+ * `bsd/sys/errno.h`; unmapped numbers become `ERRNO_<n>` so a code is always
+ * present and a real failure never looks like a missing one.
+ */
+const ERRNO_NAMES: Readonly<Record<number, string>> = {
+  1: "EPERM",
+  2: "ENOENT",
+  5: "EIO",
+  13: "EACCES",
+  17: "EEXIST",
+  18: "EXDEV",
+  20: "ENOTDIR",
+  22: "EINVAL",
+  25: "ENOTTY",
+  28: "ENOSPC",
+  30: "EROFS",
+  45: "ENOTSUP",
+  62: "ELOOP",
+  63: "ENAMETOOLONG",
+  78: "ENOSYS",
+};
+
+function errnoCode(symbols: CopyfileLibrary): string {
+  const errno = read.i32(symbols.__error());
+  return ERRNO_NAMES[errno] ?? `ERRNO_${errno}`;
+}
+
+/**
+ * Builds the syscall over an already-loaded library. Clones one regular file
+ * with `copyfile(3)`, or throws an `Error` carrying the Darwin errno name in
+ * `.code`. The capability predicate matches on those names, so `ENOTSUP` (an
+ * unsupported filesystem) is classified without the probe ever seeing the raw
+ * syscall.
+ */
+export function createDarwinSyscall(
+  symbols: CopyfileLibrary,
+): DarwinCloneSyscall {
+  return async (source, destination) => {
+    if (symbols.copyfile(source, destination, null, DARWIN_CLONE_FLAGS) === 0) {
+      return { cloned: true };
+    }
+    const error = new Error(
+      `copyfile(3) failed on ${source} -> ${destination}`,
+    ) as Error & { code: string };
+    error.code = errnoCode(symbols);
+    throw error;
+  };
+}

package/src/platform-darwin.ts

@@ -0,0 +1,104 @@
+/**
+ * The macOS CoW backend: one regular file cloned with `copyfile(3)`.
+ *
+ * `clonefile(2)` is not used here on purpose. Apple discourages it for
+ * directories — it blocks the whole tree for the duration of the call — so a
+ * Deep clone must be driven entry by entry, and `copyfile(3)` is the supported
+ * recursive primitive.
+ *
+ * The syscall is a seam (`DarwinCloneSyscall`) so the decision logic in
+ * `cloneFileOnDarwin` runs and is unit-tested on any platform. The real binding
+ * lives in `platform-darwin-ffi.ts` and is imported only when a Darwin process
+ * actually selects this backend.
+ */
+
+/**
+ * Flags passed to `copyfile(3)`, from Apple's `copyfile.h`:
+ *
+ * - `COPYFILE_CLONE_FORCE` (1<<25) is the fail-loud flag: cloning is required,
+ *   and an unsupported filesystem returns an error instead of silently
+ *   producing a byte copy. Apple documents it as equivalent to `(COPYFILE_EXCL
+ *   | COPYFILE_STAT | COPYFILE_XATTR | COPYFILE_DATA | COPYFILE_NOFOLLOW_SRC)`.
+ * - `COPYFILE_ALL` (COPYFILE_ACL|COPYFILE_STAT|COPYFILE_XATTR|COPYFILE_DATA) is
+ *   added because the clone flag's implied set covers STAT/XATTR/DATA but
+ *   **not ACL**. Apple's header: "ACLs will not be cloned unless COPYFILE_ACL
+ *   is also passed"; `COPYFILE_ALL` carries that bit. (STAT is already implied,
+ *   so the POSIX mode — including the executable bit git reads — is preserved
+ *   either way.)
+ * - `COPYFILE_EXCL`, implied by the clone flag, means the destination must not
+ *   exist — the same precondition the caller's walker already satisfies.
+ *
+ * Exported so the flag choice is asserted on any platform, without loading the
+ * Darwin library.
+ */
+export const COPYFILE_ALL = (1 << 0) | (1 << 1) | (1 << 2) | (1 << 3);
+export const COPYFILE_CLONE_FORCE = 1 << 25;
+/** Implied by COPYFILE_CLONE_FORCE; named so the destination precondition is explicit. */
+export const COPYFILE_EXCL = 1 << 17;
+export const DARWIN_CLONE_FLAGS = COPYFILE_ALL | COPYFILE_CLONE_FORCE;
+
+/**
+ * True when the clone genuinely shared extents with the source.
+ */
+export type CloneOutcome = { readonly cloned: boolean };
+
+/** A `copyfile(3)` clone of one regular file. Throws the raw failure. */
+export type DarwinCloneSyscall = (
+  source: string,
+  destination: string,
+) => Promise<CloneOutcome>;
+
+/**
+ * The lazily-loaded binding: `loadCopyfileLibrary` and `createDarwinSyscall`
+ * from `platform-darwin-ffi.ts`, whose imports are inert so that merely
+ * referencing them costs nothing on Linux.
+ */
+export type DarwinFfi = {
+  readonly loadCopyfileLibrary: (typeof import("./platform-darwin-ffi"))["loadCopyfileLibrary"];
+  readonly createDarwinSyscall: (typeof import("./platform-darwin-ffi"))["createDarwinSyscall"];
+};
+
+/**
+ * Composes the binding into a syscall: load libSystem, then build the call over
+ * it. Exported and injectable for the same reason the syscall itself is — it is
+ * the wiring `cloneFileOnDarwin` falls back to, and it must be provable without
+ * a Mac. The default performs the lazy import, so the macOS-only module is
+ * pulled in only when a Darwin process actually selects this backend.
+ */
+export async function darwinSyscall(
+  loadFfi: () => Promise<DarwinFfi> = () => import("./platform-darwin-ffi"),
+): Promise<DarwinCloneSyscall> {
+  const ffi = await loadFfi();
+  return ffi.createDarwinSyscall(ffi.loadCopyfileLibrary());
+}
+
+/**
+ * Clones one regular file, or throws.
+ *
+ * Fail closed: when the syscall reports success without a real clone, the
+ * target is discarded and an error is thrown. A Deep clone that quietly became
+ * a full copy is the exact failure this backend exists to prevent, so it is
+ * never returned as success.
+ *
+ * The binding is resolved only inside this default, so importing this module is
+ * inert on Linux; both tests and the platform seam injection point supply their
+ * own syscall instead.
+ */
+export async function cloneFileOnDarwin(
+  source: string,
+  destination: string,
+  attempt: DarwinCloneSyscall | undefined = undefined,
+): Promise<void> {
+  const syscall = attempt ?? (await darwinSyscall());
+  const outcome = await syscall(source, destination);
+  if (outcome.cloned) return;
+  await rm(destination);
+  throw new Error(
+    `copyfile(3) did not clone ${source} onto ${destination}; refusing a full copy`,
+  );
+}
+
+async function rm(path: string): Promise<void> {
+  const { rm: remove } = await import("node:fs/promises");
+  await remove(path, { force: true });
+}