@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/terminal.js

@@ -0,0 +1,409 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import * as pty from "node-pty";
+import { depCacheEnv } from "./harness/dep-cache.js";
+/**
+ * Coalescing window (ms) for PTY output. node-pty delivers a chatty program's
+ * output (build logs, `cat` of a large file, an agent streaming tokens) as a
+ * flurry of small chunks across many event-loop ticks. Emitting one transport
+ * frame per chunk floods the WebSocket and — over the relay — pays a per-frame
+ * encrypt/chunk cost each time, which is a large part of why the terminal feels
+ * laggy under load. Batching a few ms of output into a single frame collapses
+ * that by an order of magnitude while adding latency well below the threshold of
+ * perception for interactive echo.
+ */
+const OUTPUT_FLUSH_MS = 8;
+/**
+ * How much recent output to retain per terminal for scrollback replay on
+ * reconnect. A phone that backgrounds the PWA (or drops its network) reattaches
+ * to the still-live shell and gets this tail rewritten so it doesn't come back
+ * to a blank screen. Kept modest so a chatty build log can't grow memory without
+ * bound.
+ */
+const SCROLLBACK_LIMIT = 256 * 1024;
+function defaultShell() {
+    if (process.platform === "win32")
+        return process.env.COMSPEC || "powershell.exe";
+    return process.env.SHELL || "/bin/bash";
+}
+/**
+ * Resolve `command` to a runnable executable path, mirroring how the PTY's exec
+ * would search `env`'s PATH. Returns the absolute path, or null when the command
+ * can't be found / isn't executable.
+ *
+ * This exists because node-pty does NOT throw when the target can't be exec'd:
+ * its spawn helper prints the cryptic "posix_spawnp failed." into the terminal
+ * and exits, so a mistyped or uninstalled agent (e.g. `bivy run claude` with no
+ * `claude` on the daemon's PATH) surfaces that message instead of a real error.
+ * Resolving up front lets open() throw a clear, catchable error — and hands the
+ * PTY an unambiguous absolute path.
+ */
+export function resolveExecutable(command, env, cwd) {
+    const win = process.platform === "win32";
+    const isExecutable = (file) => {
+        try {
+            if (!fs.statSync(file).isFile())
+                return false;
+            if (win)
+                return true;
+            fs.accessSync(file, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    // On Windows a bare name may need a PATHEXT suffix (claude → claude.cmd).
+    const exts = win ? (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+    const withExts = (file) => exts.map((ext) => (ext && !file.toLowerCase().endsWith(ext.toLowerCase()) ? file + ext : file));
+    // A command with an explicit path is resolved directly (against the workspace
+    // for a relative one), never via PATH — same as exec.
+    if (command.includes("/") || (win && command.includes("\\"))) {
+        for (const candidate of withExts(path.resolve(cwd, command))) {
+            if (isExecutable(candidate))
+                return candidate;
+        }
+        return null;
+    }
+    for (const dir of (env.PATH || "").split(path.delimiter).filter(Boolean)) {
+        for (const candidate of withExts(path.join(dir, command))) {
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Restore the execute bit on node-pty's bundled `spawn-helper` binary.
+ *
+ * On macOS/Linux, node-pty launches every PTY by exec'ing this helper. Its
+ * prebuilds ship without the execute bit (mode 0664), and a fresh `npm install`
+ * — exactly what `bivy update` runs — resets the bit. node-pty does not surface
+ * this: its spawn prints the cryptic "posix_spawnp failed." into the terminal and
+ * exits, so `bivy run <agent>` dies before the agent starts and keeps breaking
+ * after every update until someone runs `chmod +x` by hand.
+ *
+ * Fix it once, up front, so runs survive updates and reinstalls automatically.
+ * Best-effort and idempotent: if node-pty can't be resolved or the helper is
+ * already executable, this is a no-op and node-pty reports its own errors.
+ */
+let spawnHelperEnsured = false;
+function ensureSpawnHelperExecutable() {
+    if (spawnHelperEnsured)
+        return;
+    spawnHelperEnsured = true;
+    if (process.platform === "win32")
+        return; // Windows has no spawn-helper.
+    const makeExecutable = (file) => {
+        try {
+            const st = fs.statSync(file);
+            if (!st.isFile() || (st.mode & 0o111) !== 0)
+                return; // missing or already +x
+            fs.chmodSync(file, st.mode | 0o755);
+        }
+        catch {
+            // Missing candidate or read-only install — best-effort.
+        }
+    };
+    try {
+        const require = createRequire(import.meta.url);
+        const root = path.dirname(require.resolve("node-pty/package.json"));
+        // Cover both a from-source build and the prebuilt binaries node-pty ships.
+        makeExecutable(path.join(root, "build", "Release", "spawn-helper"));
+        const prebuilds = path.join(root, "prebuilds");
+        try {
+            for (const dir of fs.readdirSync(prebuilds)) {
+                makeExecutable(path.join(prebuilds, dir, "spawn-helper"));
+            }
+        }
+        catch {
+            // No prebuilds directory — fine.
+        }
+    }
+    catch {
+        // Couldn't resolve node-pty; leave it to node-pty to report.
+    }
+}
+export class TerminalManager {
+    terminals = new Map();
+    /** The number of live terminals (for tests / capacity reporting). */
+    get size() {
+        return this.terminals.size;
+    }
+    open(options) {
+        const id = `term-${randomUUID()}`;
+        const shell = options.command || defaultShell();
+        const shellArgs = options.command ? (options.args ?? []) : [];
+        // Ensure a UTF-8 locale so TUIs (e.g. Claude Code) render box-drawing and
+        // emoji instead of "?". The daemon may be started by launchd/systemd with no
+        // LANG/LC_* in its environment; without a UTF-8 locale the child runs under
+        // the C/POSIX locale and downgrades all non-ASCII output. Only fill the gap
+        // when no locale is configured — a real locale in the environment still wins.
+        const hasLocale = Boolean(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG);
+        const localeDefaults = hasLocale ? {} : { LANG: "en_US.UTF-8", LC_CTYPE: "en_US.UTF-8" };
+        const env = {
+            ...localeDefaults,
+            ...process.env,
+            ...depCacheEnv(),
+            ...options.env,
+            TERM: "xterm-256color",
+            // Make it obvious in the shell that this is a Bivy terminal.
+            BIVY_TERMINAL: "1",
+        };
+        // node-pty won't throw for an unresolvable command — it prints
+        // "posix_spawnp failed." into the PTY and exits. Resolve up front so we can
+        // raise a real error (which callers turn into a `terminal.error`) instead.
+        const resolved = resolveExecutable(shell, env, options.workspace);
+        if (!resolved) {
+            throw new Error(options.command
+                ? `Cannot run "${shell}": command not found or not executable on the node's PATH. Install it, or check the command.`
+                : `Cannot start a terminal: no usable shell found (tried "${shell}"). Set the SHELL environment variable.`);
+        }
+        // node-pty exec's a bundled `spawn-helper` whose execute bit a fresh install
+        // (e.g. `bivy update`) strips — restore it before spawning or this fails with
+        // "posix_spawnp failed." See ensureSpawnHelperExecutable().
+        ensureSpawnHelperExecutable();
+        const proc = pty.spawn(resolved, shellArgs, {
+            name: "xterm-256color",
+            cols: clampDim(options.cols, 80),
+            rows: clampDim(options.rows, 24),
+            cwd: options.workspace,
+            env,
+        });
+        const now = Date.now();
+        const entry = {
+            proc,
+            workspace: options.workspace,
+            createdAt: now,
+            lastActivityAt: now,
+            lastInputAt: now,
+            meta: options.meta ?? {},
+            clientSizes: new Map(),
+            buffer: "",
+            pending: "",
+            flushTimer: null,
+            closed: false,
+            onData: options.onData,
+        };
+        // Register the opener as a sized client so a later, smaller client shrinks
+        // the PTY to the min of the two rather than clobbering the opener's size.
+        if (options.clientId) {
+            entry.clientSizes.set(options.clientId, {
+                cols: clampDim(options.cols, 80),
+                rows: clampDim(options.rows, 24),
+            });
+        }
+        this.terminals.set(id, entry);
+        const flush = () => {
+            entry.flushTimer = null;
+            if (entry.closed || !entry.pending)
+                return;
+            const batch = entry.pending;
+            entry.pending = "";
+            entry.onData(batch);
+        };
+        proc.onData((data) => {
+            // A killed PTY can still emit a final chunk after close() tore the
+            // terminal down; ignore it so we never deliver output for a closed one.
+            if (entry.closed)
+                return;
+            // Scrollback tail is kept raw and up to date immediately so a reattach
+            // replay never lags the coalesced client stream.
+            entry.buffer += data;
+            if (entry.buffer.length > SCROLLBACK_LIMIT) {
+                entry.buffer = entry.buffer.slice(entry.buffer.length - SCROLLBACK_LIMIT);
+            }
+            entry.lastActivityAt = Date.now();
+            // A BEL in the raw stream means a program rang the terminal bell. Notify the
+            // caller once per chunk (a bell-storm within one node-pty chunk collapses to
+            // one signal); finer gating is the caller's responsibility.
+            if (options.onBell && data.includes("\x07")) {
+                try {
+                    options.onBell();
+                }
+                catch {
+                    /* a bell handler must never break output delivery */
+                }
+            }
+            // Coalesce delivery: accumulate and flush on a short timer instead of
+            // emitting a frame per chunk.
+            entry.pending += data;
+            if (!entry.flushTimer)
+                entry.flushTimer = setTimeout(flush, OUTPUT_FLUSH_MS);
+        });
+        proc.onExit(({ exitCode, signal }) => {
+            // Deliver whatever was buffered before signalling exit, so a program's
+            // final output isn't dropped by the coalescing window.
+            if (entry.flushTimer) {
+                clearTimeout(entry.flushTimer);
+                entry.flushTimer = null;
+            }
+            // On a natural exit `closed` is still false, so this delivers the final
+            // output. If close() already ran, `closed` is true and flush() is a no-op
+            // — we don't re-emit output for a terminal the client tore down.
+            flush();
+            entry.closed = true;
+            this.terminals.delete(id);
+            options.onExit(exitCode, signal);
+        });
+        return id;
+    }
+    write(id, data) {
+        const entry = this.terminals.get(id);
+        if (!entry)
+            return false;
+        entry.lastInputAt = Date.now();
+        entry.proc.write(data);
+        return true;
+    }
+    /**
+     * Record `clientId`'s desired size for terminal `id` and re-size the shared
+     * PTY to the minimum over all currently-attached clients. Called on both
+     * attach and resize. Using the min (rather than "last writer wins") means a
+     * second client attaching at a different window size can never reflow another
+     * client's TUI wider than its viewport — it only ever adds unused margin on
+     * the larger client, tmux-style.
+     */
+    setClientSize(id, clientId, cols, rows) {
+        const entry = this.terminals.get(id);
+        if (!entry)
+            return false;
+        entry.clientSizes.set(clientId, { cols: clampDim(cols, 80), rows: clampDim(rows, 24) });
+        this.applyMinSize(entry);
+        return true;
+    }
+    /**
+     * Forget `clientId`'s size for terminal `id` (it detached from this terminal)
+     * and re-size the PTY to the min of whoever remains, so the surviving clients
+     * grow back to their real dimensions. No-op if the client had no size here.
+     */
+    dropClientSize(id, clientId) {
+        const entry = this.terminals.get(id);
+        if (!entry)
+            return false;
+        if (entry.clientSizes.delete(clientId))
+            this.applyMinSize(entry);
+        return true;
+    }
+    /**
+     * Forget `clientId` across every terminal — called when a client's transport
+     * (socket/relay) drops, so terminals it viewed grow back for the clients that
+     * remain. A disconnecting client may have sized terminals it never `owned`
+     * (e.g. shared run-terminals), so this sweeps all of them.
+     */
+    dropClient(clientId) {
+        for (const entry of this.terminals.values()) {
+            if (entry.clientSizes.delete(clientId))
+                this.applyMinSize(entry);
+        }
+    }
+    /** Size the PTY to the min cols/rows over all attached clients. */
+    applyMinSize(entry) {
+        // No sized clients (nobody attached, or an unsized opener): leave the PTY at
+        // its current size rather than snapping to the 80x24 clamp floor.
+        if (entry.clientSizes.size === 0)
+            return;
+        let cols = Infinity;
+        let rows = Infinity;
+        for (const size of entry.clientSizes.values()) {
+            if (size.cols < cols)
+                cols = size.cols;
+            if (size.rows < rows)
+                rows = size.rows;
+        }
+        try {
+            entry.proc.resize(clampDim(cols, 80), clampDim(rows, 24));
+        }
+        catch {
+            // resizing a dying pty can throw — harmless
+        }
+    }
+    close(id) {
+        const entry = this.terminals.get(id);
+        if (!entry)
+            return false;
+        this.terminals.delete(id);
+        // Drop any queued output — the client asked to close, so don't emit a
+        // trailing batch (which would fire onData for a terminal it has torn down).
+        // `closed` also neutralises the final PTY chunk a kill can emit afterwards.
+        entry.closed = true;
+        if (entry.flushTimer) {
+            clearTimeout(entry.flushTimer);
+            entry.flushTimer = null;
+        }
+        entry.pending = "";
+        try {
+            entry.proc.kill();
+        }
+        catch {
+            // already gone
+        }
+        return true;
+    }
+    has(id) {
+        return this.terminals.has(id);
+    }
+    /** Metadata for a live terminal, or null if the id is unknown. */
+    meta(id) {
+        const entry = this.terminals.get(id);
+        return entry ? entry.meta : null;
+    }
+    /** Epoch ms of the last PTY output for a live terminal, or null if unknown. */
+    lastActivity(id) {
+        const entry = this.terminals.get(id);
+        return entry ? entry.lastActivityAt : null;
+    }
+    /** Epoch ms of the last client input to a live terminal, or null if unknown. */
+    lastInput(id) {
+        const entry = this.terminals.get(id);
+        return entry ? entry.lastInputAt : null;
+    }
+    /**
+     * Listable summaries of live terminals, newest first. `filter` narrows to a
+     * kind (e.g. only `bivy run` terminals) so a plain shell a client opened for
+     * itself doesn't show up as an attachable agent session.
+     */
+    list(filter) {
+        const out = [];
+        for (const [id, entry] of this.terminals) {
+            if (filter && !filter(entry.meta))
+                continue;
+            out.push({ id, workspace: entry.workspace, createdAt: entry.createdAt, lastActivityAt: entry.lastActivityAt, meta: entry.meta });
+        }
+        return out.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /**
+     * The retained scrollback tail for a live terminal, or null if the id is
+     * unknown (never opened, or already exited). Callers replay this to a client
+     * that is reattaching to an existing shell.
+     */
+    snapshot(id) {
+        const entry = this.terminals.get(id);
+        return entry ? entry.buffer : null;
+    }
+    /**
+     * The OS process id of a terminal's PTY child, or undefined if the id is
+     * unknown. Used to register a reliable kill target for a pinned agent run, so a
+     * later "continue as chat" takeover can stop the exact process it launched
+     * instead of searching for it.
+     */
+    pid(id) {
+        const entry = this.terminals.get(id);
+        return entry ? entry.proc.pid : undefined;
+    }
+    /** Kill every terminal (process shutdown). */
+    disposeAll() {
+        for (const id of [...this.terminals.keys()])
+            this.close(id);
+    }
+}
+function clampDim(value, fallback) {
+    const n = Math.floor(Number(value));
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(Math.max(n, 1), 1000);
+}

package/dist/wire-format.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Node-side mirror of the shared E2E wire-format constants. The spec's home is
+// packages/core/src/wire-format.ts; this is a byte-for-byte copy so the node
+// (node:crypto) and browser (WebCrypto) stacks derive identical values.
+//
+// Why a copy and not a re-export: the node ships as a STANDALONE bundle. The
+// release build compiles only `src/` with `tsc --rootDir src` and the tarball
+// drops `packages/` (see scripts/build-release.mjs), so a re-export of
+// `../packages/core/src/wire-format.js` both fails the compile (TS6059: file
+// outside rootDir) and would be missing at runtime. Reaching across the package
+// boundary is the browser bundler's job (Vite), not the node's tsc-with-rootDir.
+//
+// The single-source guarantee is kept the way slice 4 always intended — by the
+// CONFORMANCE TEST: test/crypto-conformance.test.ts deep-equals every export here
+// against packages/core/src/wire-format.ts, so any drift fails CI. Do NOT edit a
+// value here without changing the spec (and the wire format) in lockstep.
+/**
+ * HKDF `info` strings that domain-separate the per-device ECDH wrap keys. Both
+ * ends must derive with the identical string or the room key fails to unwrap.
+ */
+export const HKDF_INFO = {
+    /** Initial pairing (pair.hello → pair.welcome). */
+    pair: "bivy-pair-v1",
+    /** Room-key rotation after a device revoke. */
+    rotate: "bivy-rotate-v1",
+    /** Model-auth vault delivery (node-only today). */
+    modelAuthVault: "bivy-model-auth-vault-v1",
+    /** GitHub App private-key vault delivery (node-only, opt-in — issue #88). */
+    githubAppVault: "bivy-github-app-vault-v1",
+};
+/** Version byte stamped into every sealed frame's authenticated plaintext. */
+export const FRAME_VERSION = 1;
+/** AES-256-GCM room key length, in bytes. */
+export const ROOM_KEY_BYTES = 32;
+/** Length of the derived ECDH wrap key (HKDF output), in bytes. */
+export const WRAP_KEY_BYTES = 32;
+/** Length of the out-of-band pairing secret carried in the QR, in bytes. */
+export const PAIR_SECRET_BYTES = 32;
+/**
+ * Packed sealed-envelope layout: [ IV | GCM tag | ciphertext ], base64.
+ * The receiver slices by these fixed offsets, so they are wire-observable.
+ */
+export const IV_BYTES = 12;
+export const GCM_TAG_BYTES = 16;
+/** Offset where ciphertext begins (= IV_BYTES + GCM_TAG_BYTES). */
+export const SEALED_HEADER_BYTES = IV_BYTES + GCM_TAG_BYTES; // 28
+/** Random freshness nonce embedded in each frame's authenticated plaintext. */
+export const FRAME_NONCE_BYTES = 12;
+/**
+ * ReplayGuard freshness window and bounded seen-nonce cache size. Frames older
+ * than the window (either direction) or with an already-seen nonce are dropped.
+ */
+export const REPLAY_WINDOW_MS = 5 * 60_000;
+export const MAX_SEEN_NONCES = 5000;
+/**
+ * Relay frame chunking. The relay caps each WebSocket message at
+ * RELAY_MAX_FRAME_BYTES (256 KiB default); larger sealed payloads are split into
+ * ordered slices of at most FRAME_CHUNK_BYTES and reassembled before decrypting.
+ * Kept comfortably below the relay cap so the JSON envelope still fits.
+ */
+export const FRAME_CHUNK_BYTES = 192 * 1024;
+/** Reassembly safety caps — defend against a buggy/hostile peer. */
+export const MAX_REASSEMBLY_BYTES = 32 * 1024 * 1024;
+export const MAX_FRAME_CHUNKS = 4096;
+export const MAX_REASSEMBLY_GROUPS = 16;

package/dist/worktree-provision.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Opportunistic installed-tree dedup for session worktrees (Approach A).
+//
+// Bivy creates a git worktree per session and is not in the install path, so N
+// worktrees of a repo each grow their own node_modules / target / .venv. When
+// the filesystem supports copy-on-write, we can instead clone an already-
+// populated installed dir from a SIBLING worktree of the same repo into a fresh
+// one, so its marginal disk cost is ~its diff, not a full duplicate.
+//
+// Safety rules baked in here:
+//   - Opt-in via BIVY_WORKTREE_COW_CLONE.
+//   - CoW-only: on a non-CoW filesystem we do NOTHING (a plain copy of
+//     node_modules costs the same disk as a fresh install, plus time — a net
+//     loss), and let the agent install normally.
+//   - Only clone a dir when a sibling's lockfile fingerprint MATCHES the new
+//     worktree's, so a reused install is never stale.
+//   - Only these git-IGNORED installed/derived dirs — never tracked files (the
+//     worktree checkout already has those).
+//   - Best-effort: never throws; failure just falls back to a normal install.
+//
+// This is structured so a future "base-provisioning" source (Approach B) can be
+// added as another candidate source without changing callers.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { detectCloneStrategy, cloneDir } from "./harness/cow-clone.js";
+// Order within `lockfiles` is the fingerprint precedence (first present wins).
+const ECOSYSTEMS = [
+    { dir: "node_modules", lockfiles: ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "npm-shrinkwrap.json"] },
+    { dir: "target", lockfiles: ["Cargo.lock"] },
+    { dir: ".venv", lockfiles: ["uv.lock", "poetry.lock", "Pipfile.lock", "requirements.txt"] },
+];
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Fingerprint the first present lockfile for an ecosystem, or undefined. */
+function lockfileFingerprint(dir, lockfiles) {
+    for (const name of lockfiles) {
+        try {
+            const buf = fs.readFileSync(path.join(dir, name));
+            return `${name}:${crypto.createHash("sha256").update(buf).digest("hex")}`;
+        }
+        catch {
+            // not present — try the next
+        }
+    }
+    return undefined;
+}
+function listSiblings(worktreesRoot, exclude) {
+    let entries;
+    try {
+        entries = fs.readdirSync(worktreesRoot);
+    }
+    catch {
+        return [];
+    }
+    const excl = path.resolve(exclude);
+    return entries
+        .map((e) => path.join(worktreesRoot, e))
+        .filter((p) => path.resolve(p) !== excl && isDir(p));
+}
+/**
+ * Decide which installed dirs the new worktree can safely reuse from a sibling.
+ * Pure filesystem logic (no CoW required), so it is unit-testable everywhere.
+ * For each ecosystem: skip if the new worktree already has the dir; otherwise
+ * pick the first sibling that HAS the dir and whose lockfile fingerprint matches
+ * the new worktree's (guaranteeing the deps are current).
+ */
+export function planCowProvision(opts) {
+    const siblings = listSiblings(opts.worktreesRoot, opts.worktreePath);
+    const plan = [];
+    for (const eco of ECOSYSTEMS) {
+        if (isDir(path.join(opts.worktreePath, eco.dir)))
+            continue; // never overwrite an existing install
+        const destFp = lockfileFingerprint(opts.worktreePath, eco.lockfiles);
+        if (!destFp)
+            continue; // no lockfile → cannot verify freshness → skip
+        for (const sib of siblings) {
+            if (!isDir(path.join(sib, eco.dir)))
+                continue;
+            if (lockfileFingerprint(sib, eco.lockfiles) !== destFp)
+                continue; // stale — different deps
+            plan.push({ dir: eco.dir, source: path.join(sib, eco.dir) });
+            break; // first matching sibling wins
+        }
+    }
+    return plan;
+}
+/**
+ * Opportunistically CoW-clone installed dirs into a freshly-created worktree from
+ * a sibling of the same repo. Gated on BIVY_WORKTREE_COW_CLONE and on the
+ * filesystem supporting copy-on-write. Best-effort; never throws.
+ */
+export function cowProvisionDeps(opts) {
+    if (!process.env.BIVY_WORKTREE_COW_CLONE)
+        return { strategy: "disabled", cloned: [] };
+    const strategy = detectCloneStrategy(opts.worktreesRoot);
+    if (strategy === "copy")
+        return { strategy: "no-cow", cloned: [] }; // copying installed dirs is a net loss
+    const cloned = [];
+    for (const item of planCowProvision(opts)) {
+        try {
+            cloneDir(item.source, path.join(opts.worktreePath, item.dir));
+            cloned.push(item.dir);
+            opts.log?.(`[worktree] cow-cloned ${item.dir} from ${item.source} (${strategy})`);
+        }
+        catch (error) {
+            opts.log?.(`[worktree] cow-clone of ${item.dir} skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { strategy, cloned };
+}