opencode2-cow-worktree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Belem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# opencode2-cow-worktree
+
+A copy-on-write worktree strategy for [opencode2](https://opencode.ai). Each
+agent gets a complete, independent copy of the project: tracked files,
+`node_modules`, build caches, local env files, all of it, cloned in
+milliseconds at almost no disk cost. Where a `git worktree` carries tracked
+files only, a **Deep clone** here carries everything, so the agent can run the
+test suite immediately.
+
+In daily use, and published to npm. Install from a local checkout (form A
+below) or from the npm registry.
+
+## Requirements
+
+- opencode2's server runs on **Bun**. The macOS backend needs Bun (`bun:ffi`);
+  it does not work under Node.
+- Linux: **btrfs**, or XFS with reflink enabled. macOS: **APFS**.
+- The worktree directory must be on the **same filesystem** as the project. A
+  reflink cannot cross a device boundary, and the plugin fails loudly rather
+  than degrading to a full copy. Configure it as shown below; the default
+  location opencode2 picks is usually on a different filesystem.
+
+## Install
+
+**What installing changes.** Registering the plugin makes `cow` opencode2's
+default worktree strategy everywhere — TUI, API, and tool calls. There is no
+capability gate on that default: on a filesystem that cannot reflink (ext4,
+tmpfs), worktree creation fails loudly until you remove the plugin. Install
+it only on machines whose projects meet the Requirements above. opencode2
+Desktop cannot select plugin strategies today, so it ignores the plugin
+entirely (`docs/research/desktop-strategy-hardcode.md`).
+
+Two forms. Pick one. Having both makes opencode2 load the tree twice, and the
+duplicate load fails.
+
+### Form A: directory discovery
+
+1. Clone this repository somewhere permanent, e.g. `/path/to/opencode2-cow-worktree`.
+2. Create the plugin directory and its `node_modules`:
+
+   ```sh
+   mkdir -p ~/.config/opencode/plugins/opencode2-cow-worktree/node_modules
+   ```
+
+3. Create two one-line seam files in the plugin directory. The first loads
+   the server plugin; the second loads its TUI half, which shows a small
+   `cow` marker in the sidebar footer while a session runs in a cow
+   worktree:
+
+   ```ts
+   // ~/.config/opencode/plugins/opencode2-cow-worktree/index.ts
+   export { default } from "opencode2-cow-worktree";
+   ```
+
+   ```tsx
+   // ~/.config/opencode/plugins/opencode2-cow-worktree/tui.tsx
+   export { default } from "opencode2-cow-worktree/tui";
+   ```
+
+   The server works without the second file; skip it if you do not want the
+   marker.
+
+4. Symlink the checkout into `node_modules` so the bare specifiers resolve:
+
+   ```sh
+   ln -sfn /path/to/opencode2-cow-worktree \
+     ~/.config/opencode/plugins/opencode2-cow-worktree/node_modules/opencode2-cow-worktree
+   ```
+
+Because opencode2's runtime is Bun and the symlink points at the working tree,
+tracked edits are live with no build step.
+
+This form runs with default options. To set options, use form B.
+
+### Form B: the `plugins` array (required for options)
+
+Point a `plugins` entry at the checkout itself — no symlink, no seam files:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "/path/to/opencode2-cow-worktree",
+      "options": {
+        "hooks": { "postCreate": ["corepack use pnpm@latest"] }
+      }
+    }
+  ]
+}
+```
+
+`hooks`, `fallback`, and `targetRoot` are all optional; anything omitted takes
+its default. Each is described below.
+
+### Verify
+
+```sh
+bun scripts/dogfood-install-check.ts
+```
+
+This boots a throwaway server against the installed plugin and asserts that it
+activates (`GET /api/plugin` reports `state.status: "active"`) and that a
+worktree create with no `strategy` field produces a Deep clone, which proves
+`cow` became the default strategy.
+
+Two gotchas when checking by hand: `GET /api/plugin` does not await
+activation, so a list taken right after boot can look empty — resolve
+`POST /api/plugin/await-activation` first. And if the plugin is present both as
+a discovered directory and in the `plugins` array, one of the two loads fails
+with `Plugin failed to load`; remove one of the declarations.
+
+## Configure
+
+### `worktree.directory` — set this first
+
+opencode2's default worktree parent lives under its data directory, which is
+often on a different filesystem from your projects. Point it inside the
+project's own filesystem:
+
+```json
+{ "worktree": { "directory": ".opencode/worktrees" } }
+```
+
+A relative value resolves against the project checkout, which puts every clone
+on the source's filesystem by construction. An absolute value is used as-is
+and must be on the same filesystem as each project. Without this, `cow`
+creates fail on most setups while the built-in `git` strategy keeps working.
+
+### Plugin `options`
+
+All three options are validated when the plugin loads. A malformed value fails
+the plugin load with a message naming the option; it never degrades silently.
+
+**`fallback`** — what `spawn_workspace` does when the source filesystem cannot
+clone (default `"none"`):
+
+- `"none"`: a request for `cow` produces a Deep clone or fails. Never a
+  shallow worktree.
+- `"git"`: on a non-CoW filesystem the tool may build a regular `git`
+  worktree instead and report `mechanism: "git"`.
+
+**`targetRoot`** — where `spawn_workspace` places the worktree. Unset (the
+default) means a sibling of the source, on the source's filesystem by
+construction. A path is used verbatim and must share the source's filesystem
+for `cow`.
+
+**`hooks.postCreate`** — commands run at the end of every `cow` create,
+whatever started it (HTTP API, TUI, `spawn_workspace`):
+
+```json
+{
+  "plugins": [
+    {
+      "package": "/path/to/opencode2-cow-worktree",
+      "options": {
+        "hooks": {
+          "postCreate": [
+            "corepack use pnpm@latest",
+            "cp $COW_SOURCE_DIRECTORY/.env.local ."
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+Commands run sequentially via `sh -c` in the new worktree, with
+`COW_WORKTREE_PATH` and `COW_SOURCE_DIRECTORY` (absolute) in the environment.
+A five-minute timeout applies per command; stdin is detached, so a command
+that waits on input fails instead of hanging. The first failure removes the
+just-created clone (no orphan directory) and the error names the failed
+command, its 1-based step, and its captured output.
+
+Hooks are your own configuration and run with full shell rights inside the
+new worktree: treat the list like a shell script you wrote.
+
+**Per-project values**: opencode2 merges plugin `options` from a project-level
+`opencode.json` the same way as the global one, so a project can declare its
+own `hooks.postCreate` (or `fallback`/`targetRoot`) and every other project
+keeps the global default.
+
+## Using it
+
+Registering the plugin makes `cow` the **default strategy**: a worktree create
+from the TUI, the API, or a tool call materializes a Deep clone. Passing
+`strategy: "git"` explicitly still selects opencode2's built-in strategy.
+
+**`spawn_workspace`** (for agents): creates a worktree and starts a session in
+it, returning `{ sessionID, directory, mechanism, attached }`. `mechanism`
+tells a `cow` Deep clone from a `git` shallow worktree, so an agent that
+relies on ignored files knows whether it has them.
+
+If the requested name already belongs to a cow worktree, the call attaches: a
+new session binds to the existing directory and `attached: true` comes back —
+nothing is cloned. Attach only happens for worktrees this strategy
+materialized; anything else already at that path (a `git` worktree, an unknown
+directory) is refused before anything changes.
+
+A create whose target path already exists is refused before the first write:
+`cow` never merges into, or deletes, a directory it did not create. Resolve
+the path and re-run.
+
+**`list_worktrees`**: lists the location's cow worktrees — `name` (the
+directory basename), `directory`, `strategy`, and `createdAt`. Derived from
+opencode2's inventory alone; it has no session information.
+
+**Removal**: the strategy refuses to delete a worktree with uncommitted
+changes unless you confirm with force — and if it cannot tell (no git
+metadata, a failed probe), it refuses too. Past that guard the directory is
+renamed to a sibling `.cow-removing-<name>-<random>` and deleted from there,
+so an agent holding a working directory inside does not block the removal.
+`node_modules`-class directories are deleted in the background right after;
+a `.cow-removing-…` sibling that lingers means a deletion failed midway and
+its error was logged — the remains hold nothing else and are safe to delete
+by hand once no process is using them.
+
+The fallback policy is tool-only: `POST /api/worktree {strategy: "cow"}` calls
+the strategy directly, which always fails loudly on a non-CoW source
+regardless of `fallback`. Only `spawn_workspace` consults the policy.
+
+## Troubleshooting
+
+- **"the target is on a different filesystem"** — set `worktree.directory` as
+  shown above, or point `targetRoot` at the source's filesystem.
+- **`cow` fails on an ext4 or tmpfs project** — expected: that filesystem
+  cannot clone. Use the `git` fallback for tool calls, or let the project use
+  the built-in strategy.
+- **Plugin looks absent right after boot** — resolve
+  `POST /api/plugin/await-activation` before reading `GET /api/plugin`.
+- **`Plugin failed to load`** — the plugin is declared twice (discovered
+  directory plus `plugins` array). Keep one.
+- **A `.cow-removing-…` directory that will not go away** — a background
+  deletion failed; the server log names the cause. Delete it by hand once no
+  agent holds a directory inside it.
+
+## Development and verification
+
+The unit suite (`bun test`), typecheck (`bun run typecheck`), coverage gate
+(`bun run test:coverage`), and the e2e harness (`bun scripts/e2e/harness.ts`)
+are described in [`docs/development.md`](docs/development.md), along with the
+recorded live runs and the parallel-lane tooling this repository is developed
+with.
+
+Terms the output uses: a **Workspace** is a logical handle, a **Location** is
+where a session runs, and a **Worktree** is a directory materialized by a
+**Strategy** — more in [CONTEXT.md](CONTEXT.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "opencode2-cow-worktree",
+  "version": "0.1.0",
+  "description": "Copy-on-write worktree strategy for opencode2: a Deep clone of the whole working directory, ignored files included, so parallel agents start ready to run",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./tui.tsx"
+  },
+  "files": [
+    "src",
+    "tui.tsx",
+    "strategy-badge.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov && bun scripts/check-coverage.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode2",
+    "plugin",
+    "worktree",
+    "copy-on-write",
+    "reflink",
+    "ficlone",
+    "agents"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^0.0.0-beta-17639",
+    "@opentui/core": "0.5.11",
+    "@opentui/solid": "0.5.11",
+    "@types/bun": "latest",
+    "solid-js": "1.9.15",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.0.0-beta-17639"
+  }
+}

package/src/capability.ts

@@ -0,0 +1,140 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { reflinkFile } from "./clone";
+
+/**
+ * The outcome of a CoW capability probe.
+ *
+ * - `supported`: a clone attempt succeeded.
+ * - `unsupported`: the clone attempt failed in a way that definitively means
+ *   the filesystem cannot satisfy a CoW clone.
+ * - `error`: any other failure — permissions, a missing path, I/O. Never
+ *   collapsed into `unsupported`.
+ */
+export type CowCapability =
+  | { readonly status: "supported" }
+  | { readonly status: "unsupported" }
+  | { readonly status: "error"; readonly error: Error };
+
+/**
+ * Performs one clone of `source` onto `destination`, throwing on failure.
+ * Injectable so tests can drive the unsupported and error branches without a
+ * filesystem that lacks CoW support.
+ */
+export type CowCloneAttempt = (
+  source: string,
+  destination: string,
+) => Promise<void>;
+
+/**
+ * Default clone operation: `reflinkFile`, which is the platform's forced CoW
+ * clone — `COPYFILE_FICLONE_FORCE` on Linux, `copyfile(3)` with
+ * `COPYFILE_CLONE_FORCE` on macOS. Both fail instead of silently degrading to a
+ * byte copy, which is the semantics this predicate needs; a best-try flag would
+ * report `supported` on a filesystem without CoW support.
+ */
+const cloneWithReflink: CowCloneAttempt = reflinkFile;
+
+const PROBE_PREFIX = ".opencode2-cow-capability-";
+
+/** Failures that definitively mean the clone operation is not supported. */
+const NOT_SUPPORTED_CODES = new Set([
+  "EOPNOTSUPP",
+  "ENOTSUP",
+  "ENOTTY",
+  "EINVAL",
+  "EXDEV",
+  "ENOSYS",
+]);
+
+const cache = new Map<string, Promise<CowCapability>>();
+
+/**
+ * Answers whether `directory`'s filesystem can satisfy a CoW clone, by
+ * attempting one of a small temporary file inside that directory. Never throws:
+ * a failure is reported as `unsupported` or `error`. Terminal verdicts
+ * (`supported`, `unsupported`) are cached per directory; an `error` verdict is
+ * deliberately not — it is the one class defined as transient (permissions, a
+ * missing path, an I/O hiccup), so caching it would disable this directory
+ * until the server restarted over one bad moment. Concurrent first callers
+ * share the one in-flight probe, and only its terminal verdict is kept.
+ */
+export function probeCowCapability(
+  directory: string,
+  attempt: CowCloneAttempt = cloneWithReflink,
+): Promise<CowCapability> {
+  const cached = cache.get(directory);
+  if (cached !== undefined) return cached;
+  const pending = probe(directory, attempt);
+  // Stored before the first await so concurrent callers share this probe
+  // instead of each starting their own. When it settles on `error`, the entry
+  // is dropped: this call and every caller sharing the probe still receive
+  // the verdict, but the next call probes again instead of replaying a
+  // transient failure forever. The identity check means the eviction can only
+  // remove this probe's own entry, never a verdict a newer probe already
+  // replaced it with.
+  cache.set(directory, pending);
+  void pending.then((verdict) => {
+    if (verdict.status === "error" && cache.get(directory) === pending) {
+      cache.delete(directory);
+    }
+  });
+  return pending;
+}
+
+async function probe(
+  directory: string,
+  attempt: CowCloneAttempt,
+): Promise<CowCapability> {
+  try {
+    return await attemptClone(directory, attempt);
+  } catch (error) {
+    return { status: "error", error: toError(error) };
+  }
+}
+
+async function attemptClone(
+  directory: string,
+  attempt: CowCloneAttempt,
+): Promise<CowCapability> {
+  const scratch = await mkdtemp(join(directory, PROBE_PREFIX));
+  try {
+    const source = join(scratch, "source");
+    await writeFile(source, "opencode2-cow-worktree");
+    await attempt(source, join(scratch, "clone"));
+    return { status: "supported" };
+  } catch (error) {
+    return classifyCloneFailure(error);
+  } finally {
+    // The cleanup is best-effort and runs in its own guard: the scratch is
+    // dot-prefixed, tiny, and inside the probed directory, so a failed `rm`
+    // (say, EACCES on a suddenly read-only parent) is not a capability fact
+    // and must never mask the verdict above — least of all by turning a
+    // `supported` answer into an `error`.
+    try {
+      await rm(scratch, { recursive: true, force: true });
+    } catch {
+      // A leftover scratch is harmless; the verdict stands as reported.
+    }
+  }
+}
+
+function classifyCloneFailure(error: unknown): CowCapability {
+  const code = errorCode(error);
+  if (code !== undefined && NOT_SUPPORTED_CODES.has(code)) {
+    return { status: "unsupported" };
+  }
+  return { status: "error", error: toError(error) };
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const { code } = error as { code?: unknown };
+    if (typeof code === "string") return code;
+  }
+  return undefined;
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/clone.ts

@@ -0,0 +1,126 @@
+import {
+  lstat,
+  mkdir,
+  readdir,
+  readlink,
+  symlink,
+} from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { entryKind } from "./entry-kind";
+import { cloneFile } from "./platform";
+
+/**
+ * CoW-clone one regular file, sharing its extents with `source`.
+ *
+ * Dispatches to the platform backend: `COPYFILE_FICLONE_FORCE` on Linux, and
+ * `copyfile(3)` with `COPYFILE_CLONE_FORCE` on macOS. Both fail instead of
+ * falling back to a full byte copy; the error is propagated, never swallowed.
+ * A filesystem that cannot share extents must surface as a failure, not as a
+ * correct-looking clone made by the wrong mechanism.
+ */
+export async function reflinkFile(source: string, target: string): Promise<void> {
+  await cloneFile(source, target);
+}
+
+/**
+ * Deep clone `source` into `target`: recursively reflink every regular file and
+ * recreate every directory and symbolic link, `.git` included.
+ *
+ * Symbolic links are recreated, never followed, so a link in the clone is a
+ * link. Hard links are reflinked like any other file. The target directory is
+ * created if missing. `.git` is walked like any other directory — the clone
+ * gets a genuine standalone metadata directory and no dependency on the
+ * source's object store. Throws when reflinking is unavailable; there is no
+ * copy fallback.
+ *
+ * A target inside the source is legitimate — opencode2 resolves a relative
+ * `worktree.directory` against the project checkout — so the target subtree is
+ * skipped rather than copied into itself. A target that contains the source is
+ * rejected: writing the clone over the tree being walked has no coherent
+ * meaning.
+ *
+ * An occupied target is refused before the first filesystem write: `cow`
+ * never writes into, or deletes, bytes it did not create. `mkdir` would
+ * happily merge into an existing directory and per-file clones would
+ * overwrite its files, and a caller's leave-nothing-behind rollback would
+ * then run its `rm` over content this call never made — so a pre-existing
+ * path (any type, a `lstat` that never follows symlinks) is always the
+ * caller's mistake to resolve, and it surfaces here as a refusal naming the
+ * path. An entry path whose occupancy cannot even be determined fails closed:
+ * it is an error, never an "absent".
+ */
+export async function cloneDirectory(source: string, target: string): Promise<void> {
+  const from = resolve(source);
+  const to = resolve(target);
+
+  if (from === to) {
+    throw new Error(`cannot clone ${from} into itself`);
+  }
+  if (isInside(from, to)) {
+    throw new Error(`cannot clone ${from} into ${to}: the target contains the source`);
+  }
+  if (await entryExists(to)) {
+    throw new OccupiedTargetError(`cannot clone into ${to}: it already exists`);
+  }
+
+  await mkdir(target, { recursive: true });
+  await cloneInto(from, to, to);
+}
+
+/**
+ * True when anything — directory, file, symbolic link — occupies `path`.
+ * `lstat` never follows a symlink, so a link at the path counts as occupied
+ * without consulting what it points to. An error that is not a plain ENOENT
+ * says the occupancy is unknowable, and is rethrown: treating it as absence
+ * would let the clone merge into a path no one could inspect.
+ */
+async function entryExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/**
+ * The target of a `cloneDirectory` call was already occupied. Its own class so
+ * a caller's leave-nothing-behind rollback can tell "refused before the first
+ * write, nothing here is ours" apart from a mid-clone failure, and leave the
+ * foreign content untouched instead of `rm`-ing it.
+ */
+export class OccupiedTargetError extends Error {}
+
+async function cloneInto(source: string, target: string, skip: string): Promise<void> {
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    const from = join(source, entry.name);
+    // The target (when it lives inside the source) must not be copied: it is
+    // being populated by this very walk, so descending into it clones the
+    // clone into itself without bound. Everything else — including the
+    // target's ancestors and their other children — is copied normally.
+    if (from === skip) continue;
+    const to = join(target, entry.name);
+    const kind = await entryKind(entry, () => lstat(from));
+    if (kind === "directory") {
+      await mkdir(to);
+      await cloneInto(from, to, skip);
+    } else if (kind === "symlink") {
+      await symlink(await readlink(from), to);
+    } else {
+      await reflinkFile(from, to);
+    }
+  }
+}
+
+/**
+ * True when `child` lies inside `parent`, compared by path components rather
+ * than by string prefix: `/a/bc` is not inside `/a/b`, and a child literally
+ * named `..foo` is not an escape. `relative` yields exactly that check, and an
+ * absolute result means a different root and therefore not contained.
+ */
+function isInside(child: string, parent: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}

package/src/config.ts

@@ -0,0 +1,92 @@
+import type { FallbackPolicy } from "./tool";
+
+const ACCEPTED: readonly FallbackPolicy[] = ["none", "git"];
+
+/**
+ * Reads the fallback policy from the plugin's free-form `options`.
+ *
+ * Absent means disabled (`"none"`): the fallback is opt-in, so a caller who did
+ * not ask for it never silently gets a Shallow worktree. An unrecognized value
+ * throws rather than degrading to `"none"` — a misconfiguration must not change
+ * the mechanism a caller gets without saying so.
+ */
+export function fallbackPolicy(
+  options: Record<string, unknown> | undefined,
+): FallbackPolicy {
+  const value = options?.fallback;
+  if (value === undefined) return "none";
+  if (isFallbackPolicy(value)) return value;
+  throw new Error(
+    `invalid plugin option "fallback": expected one of ${ACCEPTED.join(", ")}, got ${JSON.stringify(value)}`,
+  );
+}
+
+function isFallbackPolicy(value: unknown): value is FallbackPolicy {
+  return (ACCEPTED as readonly unknown[]).includes(value);
+}
+
+const HOOKS = "hooks";
+
+/**
+ * Reads the post-create hooks from the plugin's free-form `options`, shaped
+ * `hooks: { postCreate: string[] }`.
+ *
+ * Absent — the option, the `hooks` object, or the `postCreate` list — means no
+ * hooks: a caller who did not ask for them gets exactly the create behavior
+ * they had before. A value that is not an array of non-empty command strings
+ * throws rather than being ignored: a misconfiguration must not silently skip
+ * setup the user believes runs on every clone.
+ */
+export function postCreateHooks(
+  options: Record<string, unknown> | undefined,
+): readonly string[] {
+  const hooks = options?.[HOOKS];
+  if (hooks === undefined) return [];
+  if (!isHooksObject(hooks)) {
+    throw new Error(
+      `invalid plugin option "${HOOKS}": expected an object with a "postCreate" command list, got ${JSON.stringify(hooks)}`,
+    );
+  }
+  const commands = (hooks as { postCreate?: unknown }).postCreate;
+  if (commands === undefined) return [];
+  if (!isCommandList(commands)) {
+    throw new Error(
+      `invalid plugin option "${HOOKS}.postCreate": expected an array of non-empty command strings, got ${JSON.stringify(commands)}`,
+    );
+  }
+  return commands;
+}
+
+function isHooksObject(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCommandList(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.every((command) => typeof command === "string" && command.trim() !== "")
+  );
+}
+
+const TARGET_ROOT = "targetRoot";
+
+/**
+ * Reads the Worktree target root from the plugin's free-form `options`.
+ *
+ * Absent means the tool picks a parent on the source's own filesystem (a sibling
+ * of the source) — the same-device default a CoW clone requires. A configured
+ * value is used verbatim, even when it names a different filesystem, because
+ * that is precisely the case the tool must diagnose instead of hiding. A
+ * non-string or empty value throws rather than degrading to the default: a
+ * misconfiguration must not silently relocate every clone.
+ */
+export function targetRoot(
+  options: Record<string, unknown> | undefined,
+): string | undefined {
+  const value = options?.[TARGET_ROOT];
+  if (value === undefined) return undefined;
+  if (typeof value === "string" && value.trim() !== "") return value;
+  throw new Error(
+    `invalid plugin option "${TARGET_ROOT}": expected a non-empty path string, got ${JSON.stringify(value)}`,
+  );
+}