@cleocode/worktree 2026.5.99 → 2026.5.101

package/dist/copy-on-write.d.ts

@@ -1,36 +1,66 @@
 /**
  * Copy-on-write file utility for `@cleocode/worktree`.
  *
- * Provides efficient path copying using filesystem-level copy-on-write
- * (reflink / clonefile) when available, falling back to regular recursive copy.
+ * Thin TS wrapper around `@cleocode/worktree-napi`'s parallel reflink-aware
+ * copy primitive ({@link copyPathsParallel}). Replaces the prior 150-LOC
+ * sequential `execFile('cp')` loop — the worktree bootstrap is now a single
+ * Rust call backed by a 4-thread rayon pool with reflink probing.
  *
- * Platform support:
- * - macOS (darwin): APFS clonefile via `cp -cR`
- * - Linux: btrfs / xfs / zfs reflink via `cp -R --reflink=auto`
- * - Windows: `fs.copyFile` with `COPYFILE_FICLONE` (Node 24+) for files,
- *   regular recursive copy for directories
+ * Platform support inherited from `worktrunk-core::copy::copy_leaf`:
+ * - macOS (darwin): APFS clonefile via `cp -c`
+ * - Linux: btrfs / xfs / zfs reflink via `cp --reflink=auto`
+ * - Windows: regular copyFile with FICLONE on supported FS
  *
+ * @task T9982
  * @task T1161
  */
 /**
- * Copy multiple paths from a source directory to a target directory using
- * copy-on-write when available.
+ * Optional knobs for {@link copyPathsWithReflock}.
  *
- * Each path in `paths` is treated as relative to `sourceDir` and copied to
- * the corresponding location under `targetDir`.
+ * Mirrors the napi `CopyOpts` shape with TS-friendly defaults. The `rootGuard`
+ * option keeps every destination resolution inside the supplied root — the
+ * canonical XDG worktree path is the recommended value for production callers.
  *
- * Missing source paths are skipped with a warning written to `stderr`.
- * Existing target paths are skipped without overwriting.
+ * @task T9982
+ */
+export interface CopyPathsOptions {
+    /** Overwrite existing entries at the destination. Default `false`. */
+    force?: boolean;
+    /**
+     * When set, every destination must resolve inside this root. Used as a
+     * safety belt against path traversal in the supplied `paths` list.
+     */
+    rootGuard?: string;
+    /**
+     * Reserved for future use — symlinks are always followed by the underlying
+     * `worktrunk_core::copy::copy_leaf` today. Default `true`.
+     */
+    includeSymlinks?: boolean;
+}
+/**
+ * Copy multiple paths from a source directory to a target directory using
+ * copy-on-write when available, in parallel via the Rust binding.
  *
- * If a copy-on-write attempt fails, a regular recursive copy is attempted
- * as fallback. If that also fails, the path is recorded in `failed`.
+ * Each entry in `paths` is treated as relative to `sourceDir` and copied to
+ * the corresponding location under `targetDir`. Missing source paths or paths
+ * that already exist at the destination are silently skipped by
+ * `worktrunk-core` — see the {@link CopyPathsResult.failed} list for true
+ * failures.
+ *
+ * The synchronous-looking call boundary hides 4-thread parallelism behind the
+ * napi layer; the `Promise` wrapper preserves the legacy async signature for
+ * existing TS callers.
  *
  * @param paths - Array of relative paths to copy.
  * @param sourceDir - Absolute path to the source directory.
  * @param targetDir - Absolute path to the target directory.
+ * @param options - Optional copy-options forwarded to the napi layer.
  * @returns Object with arrays of successfully copied and failed paths.
+ *
+ * @task T9982
+ * @task T1161
  */
-export declare function copyPathsWithReflock(paths: string[], sourceDir: string, targetDir: string): Promise<{
+export declare function copyPathsWithReflock(paths: string[], sourceDir: string, targetDir: string, options?: CopyPathsOptions): Promise<{
     copied: string[];
     failed: string[];
 }>;

package/dist/copy-on-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-on-write.d.ts","sourceRoot":"","sources":["../src/copy-on-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAyCjD"}
+{"version":3,"file":"copy-on-write.d.ts","sourceRoot":"","sources":["../src/copy-on-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwBjD"}

package/dist/copy-on-write.js

@@ -1,133 +1,63 @@
 /**
  * Copy-on-write file utility for `@cleocode/worktree`.
  *
- * Provides efficient path copying using filesystem-level copy-on-write
- * (reflink / clonefile) when available, falling back to regular recursive copy.
+ * Thin TS wrapper around `@cleocode/worktree-napi`'s parallel reflink-aware
+ * copy primitive ({@link copyPathsParallel}). Replaces the prior 150-LOC
+ * sequential `execFile('cp')` loop — the worktree bootstrap is now a single
+ * Rust call backed by a 4-thread rayon pool with reflink probing.
  *
- * Platform support:
- * - macOS (darwin): APFS clonefile via `cp -cR`
- * - Linux: btrfs / xfs / zfs reflink via `cp -R --reflink=auto`
- * - Windows: `fs.copyFile` with `COPYFILE_FICLONE` (Node 24+) for files,
- *   regular recursive copy for directories
+ * Platform support inherited from `worktrunk-core::copy::copy_leaf`:
+ * - macOS (darwin): APFS clonefile via `cp -c`
+ * - Linux: btrfs / xfs / zfs reflink via `cp --reflink=auto`
+ * - Windows: regular copyFile with FICLONE on supported FS
  *
+ * @task T9982
  * @task T1161
  */
-import { execFile } from 'node:child_process';
-import { constants, existsSync, promises as fs, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { promisify } from 'node:util';
-import { DEFAULT_GIT_TIMEOUT_MS } from './git.js';
-const execFileAsync = promisify(execFile);
-/**
- * Default per-copy subprocess timeout in milliseconds (T9545).
- *
- * Reuses {@link DEFAULT_GIT_TIMEOUT_MS} so spawn-pipeline subprocess budgets
- * stay aligned across git and `cp` invocations.
- */
-const DEFAULT_COPY_TIMEOUT_MS = DEFAULT_GIT_TIMEOUT_MS;
+import { copyPathsParallel } from './napi-binding.js';
 /**
  * Copy multiple paths from a source directory to a target directory using
- * copy-on-write when available.
+ * copy-on-write when available, in parallel via the Rust binding.
  *
- * Each path in `paths` is treated as relative to `sourceDir` and copied to
- * the corresponding location under `targetDir`.
+ * Each entry in `paths` is treated as relative to `sourceDir` and copied to
+ * the corresponding location under `targetDir`. Missing source paths or paths
+ * that already exist at the destination are silently skipped by
+ * `worktrunk-core` — see the {@link CopyPathsResult.failed} list for true
+ * failures.
  *
- * Missing source paths are skipped with a warning written to `stderr`.
- * Existing target paths are skipped without overwriting.
- *
- * If a copy-on-write attempt fails, a regular recursive copy is attempted
- * as fallback. If that also fails, the path is recorded in `failed`.
+ * The synchronous-looking call boundary hides 4-thread parallelism behind the
+ * napi layer; the `Promise` wrapper preserves the legacy async signature for
+ * existing TS callers.
  *
  * @param paths - Array of relative paths to copy.
  * @param sourceDir - Absolute path to the source directory.
  * @param targetDir - Absolute path to the target directory.
+ * @param options - Optional copy-options forwarded to the napi layer.
  * @returns Object with arrays of successfully copied and failed paths.
- */
-export async function copyPathsWithReflock(paths, sourceDir, targetDir) {
-    const copied = [];
-    const failed = [];
-    for (const relativePath of paths) {
-        const sourcePath = join(sourceDir, relativePath);
-        const targetPath = join(targetDir, relativePath);
-        if (!existsSync(sourcePath)) {
-            process.stderr.write(`[copy-on-write] skipping missing source: ${sourcePath}\n`);
-            continue;
-        }
-        if (existsSync(targetPath)) {
-            continue;
-        }
-        try {
-            mkdirSync(dirname(targetPath), { recursive: true });
-        }
-        catch {
-            process.stderr.write(`[copy-on-write] failed to create parent directory for: ${targetPath}\n`);
-            failed.push(relativePath);
-            continue;
-        }
-        try {
-            await copyWithReflock(sourcePath, targetPath);
-            copied.push(relativePath);
-        }
-        catch {
-            try {
-                await copyRegular(sourcePath, targetPath);
-                copied.push(relativePath);
-            }
-            catch {
-                failed.push(relativePath);
-            }
-        }
-    }
-    return { copied, failed };
-}
-/**
- * Attempt a copy-on-write copy from source to target.
  *
- * @param sourcePath - Absolute path to the source file or directory.
- * @param targetPath - Absolute path to the target location.
- * @throws Error if the copy operation fails or the platform is unsupported.
+ * @task T9982
+ * @task T1161
  */
-async function copyWithReflock(sourcePath, targetPath) {
-    const platform = process.platform;
-    if (platform === 'darwin') {
-        // T9545 — bound cp -cR with a default timeout to keep the spawn pipeline
-        // safe against runaway / wedged subprocesses.
-        await execFileAsync('cp', ['-cR', sourcePath, targetPath], {
-            timeout: DEFAULT_COPY_TIMEOUT_MS,
+export async function copyPathsWithReflock(paths, sourceDir, targetDir, options = {}) {
+    if (paths.length === 0)
+        return { copied: [], failed: [] };
+    let result;
+    try {
+        result = copyPathsParallel(sourceDir, targetDir, paths, {
+            force: options.force ?? false,
+            ...(options.rootGuard !== undefined ? { rootGuard: options.rootGuard } : {}),
+            includeSymlinks: options.includeSymlinks ?? true,
         });
-        return;
     }
-    if (platform === 'linux') {
-        // T9545 — bound cp --reflink with a default timeout.
-        await execFileAsync('cp', ['-R', '--reflink=auto', sourcePath, targetPath], {
-            timeout: DEFAULT_COPY_TIMEOUT_MS,
-        });
-        return;
-    }
-    if (platform === 'win32') {
-        const stat = await fs.stat(sourcePath);
-        if (stat.isDirectory()) {
-            throw new Error('Windows directories do not support copy-on-write');
-        }
-        await fs.copyFile(sourcePath, targetPath, constants.COPYFILE_FICLONE);
-        return;
-    }
-    throw new Error(`Unsupported platform: ${platform}`);
-}
-/**
- * Perform a regular recursive copy as fallback.
- *
- * @param sourcePath - Absolute path to the source file or directory.
- * @param targetPath - Absolute path to the target location.
- * @throws Error if the copy operation fails.
- */
-async function copyRegular(sourcePath, targetPath) {
-    const stat = await fs.stat(sourcePath);
-    if (stat.isDirectory()) {
-        await fs.cp(sourcePath, targetPath, { recursive: true });
-    }
-    else {
-        await fs.copyFile(sourcePath, targetPath);
+    catch (err) {
+        // A whole-batch failure (matcher / IO error before any leaf was tried)
+        // reports every path as failed so callers can recover or audit.
+        process.stderr.write(`[copy-on-write] napi.copyPathsParallel failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { copied: [], failed: [...paths] };
     }
+    const failedSet = new Set(result.failedPaths);
+    const copied = paths.filter((p) => !failedSet.has(p));
+    const failed = paths.filter((p) => failedSet.has(p));
+    return { copied, failed };
 }
 //# sourceMappingURL=copy-on-write.js.map

package/dist/copy-on-write.js.map

@@ -1 +1 @@
-{"version":3,"file":"copy-on-write.js","sourceRoot":"","sources":["../src/copy-on-write.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"copy-on-write.js","sourceRoot":"","sources":["../src/copy-on-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAuB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA0B3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAe,EACf,SAAiB,EACjB,SAAiB,EACjB,UAA4B,EAAE;IAE9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAE1D,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE;YACtD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;YAC7B,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI;SACjD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uEAAuE;QACvE,gEAAgE;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kDAAkD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACvG,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}

package/dist/git.d.ts

@@ -74,4 +74,61 @@ export declare function getGitRoot(projectRoot: string): string;
  * @returns Current HEAD ref string.
  */
 export declare function resolveHeadRef(gitRoot: string, fallback?: string): string;
+/**
+ * Options for {@link addTransientWorktree}.
+ *
+ * @task T9984
+ */
+export interface AddTransientWorktreeOptions {
+    /** Absolute project root the worktree is added to. */
+    projectRoot: string;
+    /** Absolute path where the worktree directory will be created. */
+    worktreePath: string;
+    /** Branch name (created or reused if already present). */
+    branch: string;
+    /** Ref to branch from (e.g. `origin/main`, `origin/<branch>`). */
+    baseRef: string;
+    /**
+     * When true, pass `-B` (force-reset the branch ref). Otherwise `-b` is used
+     * (fail if the branch already exists locally).
+     *
+     * @default true
+     */
+    resetBranch?: boolean;
+}
+/**
+ * Add a **transient** (non-canonical-location) worktree via `git worktree add`.
+ *
+ * This is the legitimate escape hatch for callers that need a worktree
+ * OUTSIDE the canonical XDG agent-worktree root — for example the
+ * `cleo docs publish-pr` flow which provisions a temporary worktree in the
+ * OS tmpdir to produce a doc-PR commit/push.
+ *
+ * Routing through this helper keeps the raw `git worktree add` shell-out
+ * confined to `@cleocode/worktree` (the legitimate owner) so the lint gate
+ * introduced in T9984 can reject inline `git worktree` calls everywhere
+ * else.
+ *
+ * For AGENT worktrees (under XDG canonical root) use {@link createWorktree}
+ * from `@cleocode/worktree/worktree-create.js` instead — it adds locking,
+ * include-patterns, hook lifecycle, and sentinel-index registration.
+ *
+ * @param options - Provisioning options.
+ * @throws Error if `git worktree add` exits non-zero.
+ *
+ * @task T9984
+ */
+export declare function addTransientWorktree(options: AddTransientWorktreeOptions): Promise<void>;
+/**
+ * Remove a transient worktree previously created via {@link addTransientWorktree}.
+ *
+ * Best-effort — failures throw, but callers SHOULD swallow in `finally`
+ * blocks so cleanup never masks the underlying error.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param worktreePath - Absolute path to the worktree to remove.
+ *
+ * @task T9984
+ */
+export declare function removeTransientWorktree(projectRoot: string, worktreePath: string): Promise<void>;
 //# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAWlF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAS,GAAG,MAAM,CAMzE"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAWlF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAS,GAAG,MAAM,CAMzE;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/git.js

@@ -117,4 +117,45 @@ export function resolveHeadRef(gitRoot, fallback = 'main') {
         return fallback;
     }
 }
+/**
+ * Add a **transient** (non-canonical-location) worktree via `git worktree add`.
+ *
+ * This is the legitimate escape hatch for callers that need a worktree
+ * OUTSIDE the canonical XDG agent-worktree root — for example the
+ * `cleo docs publish-pr` flow which provisions a temporary worktree in the
+ * OS tmpdir to produce a doc-PR commit/push.
+ *
+ * Routing through this helper keeps the raw `git worktree add` shell-out
+ * confined to `@cleocode/worktree` (the legitimate owner) so the lint gate
+ * introduced in T9984 can reject inline `git worktree` calls everywhere
+ * else.
+ *
+ * For AGENT worktrees (under XDG canonical root) use {@link createWorktree}
+ * from `@cleocode/worktree/worktree-create.js` instead — it adds locking,
+ * include-patterns, hook lifecycle, and sentinel-index registration.
+ *
+ * @param options - Provisioning options.
+ * @throws Error if `git worktree add` exits non-zero.
+ *
+ * @task T9984
+ */
+export async function addTransientWorktree(options) {
+    const { projectRoot, worktreePath, branch, baseRef, resetBranch = true } = options;
+    const flag = resetBranch ? '-B' : '-b';
+    await gitAsync(['worktree', 'add', flag, branch, worktreePath, baseRef], projectRoot);
+}
+/**
+ * Remove a transient worktree previously created via {@link addTransientWorktree}.
+ *
+ * Best-effort — failures throw, but callers SHOULD swallow in `finally`
+ * blocks so cleanup never masks the underlying error.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param worktreePath - Absolute path to the worktree to remove.
+ *
+ * @task T9984
+ */
+export async function removeTransientWorktree(projectRoot, worktreePath) {
+    await gitAsync(['worktree', 'remove', '--force', worktreePath], projectRoot);
+}
 //# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,GAAW,EAAE,SAAkB;IACrE,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/B,GAAG;QACH,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC/B,OAAO,EAAE,SAAS,IAAI,sBAAsB;KAC7C,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,GAAW,EAAE,SAAkB;IACvE,IAAI,CAAC;QACH,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;YACxB,GAAG;YACH,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,SAAS,IAAI,sBAAsB;SAC7C,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAc,EAAE,GAAW,EAAE,SAAkB;IAC5E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE;QAClD,GAAG;QACH,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,SAAS,IAAI,sBAAsB;KAC7C,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,QAAQ,GAAG,MAAM;IAC/D,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -21,9 +21,9 @@
  * @adr ADR-055
  */
 export type { CreateWorktreeOptions, CreateWorktreeResult, DestroyWorktreeOptions, DestroyWorktreeResult, ListWorktreesOptions, PruneWorktreesOptions, PruneWorktreesResult, WorktreeHook, WorktreeHookResult, WorktreeIncludePattern, WorktreeListEntry, } from '@cleocode/contracts';
-export type { LegacyMergeResult, LegacyWorktreeConfig, LegacyWorktreeEntry, LegacyWorktreeHandle, LegacyWorktreeRequest, } from './compat.js';
-export { legacyCreateWorktree, legacyListWorktrees, legacyMergeWorktree, legacyResolveWorktreeRoot, } from './compat.js';
+export type { CopyPathsOptions } from './copy-on-write.js';
 export { copyPathsWithReflock } from './copy-on-write.js';
+export { type AddTransientWorktreeOptions, addTransientWorktree, removeTransientWorktree, } from './git.js';
 export type { WorktreeAuditPayload } from './worktree-audit.js';
 export { addWorktreeToSentinelIndex, appendWorktreeAuditLog, removeWorktreeFromSentinelIndex, resolveWorktreeIndexPath, WORKTREE_INDEX_RELATIVE_PATH, WORKTREE_LIFECYCLE_AUDIT_FILE, } from './worktree-audit.js';
 export { createWorktree } from './worktree-create.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -20,8 +20,8 @@
  * @task T1161
  * @adr ADR-055
  */
-export { legacyCreateWorktree, legacyListWorktrees, legacyMergeWorktree, legacyResolveWorktreeRoot, } from './compat.js';
 export { copyPathsWithReflock } from './copy-on-write.js';
+export { addTransientWorktree, removeTransientWorktree, } from './git.js';
 export { addWorktreeToSentinelIndex, appendWorktreeAuditLog, removeWorktreeFromSentinelIndex, resolveWorktreeIndexPath, WORKTREE_INDEX_RELATIVE_PATH, WORKTREE_LIFECYCLE_AUDIT_FILE, } from './worktree-audit.js';
 export { createWorktree } from './worktree-create.js';
 export { destroyWorktree } from './worktree-destroy.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAwBH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAiBH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAEL,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/napi-binding.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ESM-friendly bridge to `@cleocode/worktree-napi` (a CommonJS native addon).
+ *
+ * The napi-rs loader at `crates/worktree-napi/index.cjs` exposes its surface as
+ * `module.exports = nativeBinding` — Node.js's CJS-to-ESM interop cannot
+ * statically detect named exports from a dynamic require(), so direct
+ * `import { copyPathsParallel } from '@cleocode/worktree-napi'` throws
+ * "does not provide an export named ..." at link time.
+ *
+ * This module wraps the native binding via `createRequire` so the import looks
+ * like a regular dynamic require from a CJS context. All consumers in this
+ * package import napi functions from THIS module, never directly from
+ * `@cleocode/worktree-napi`.
+ *
+ * @task T9982
+ */
+interface CopyOptsNapi {
+    /** Overwrite existing entries at the destination. */
+    force: boolean;
+    /** When set, every destination must resolve inside this root. */
+    rootGuard?: string;
+    /** Reserved for future use — symlinks are always followed by copy_leaf. */
+    includeSymlinks: boolean;
+}
+interface CopyResultNapi {
+    copiedCount: number;
+    skippedCount: number;
+    failedPaths: string[];
+    totalBytes: number;
+}
+interface DestroyOptsNapi {
+    repoRoot: string;
+    worktreePath: string;
+    force: boolean;
+}
+interface DestroyResultNapi {
+    removed: boolean;
+    branchDeleted: boolean;
+}
+interface IncludePatternNapi {
+    pattern: string;
+    isNegation: boolean;
+}
+interface ListOptsNapi {
+    repoRoot: string;
+}
+interface WorktreeInfoNapi {
+    path: string;
+    branch?: string;
+    head: string;
+    isLocked: boolean;
+    isPrunable: boolean;
+}
+/**
+ * Shape of the native module exported by `@cleocode/worktree-napi`.
+ *
+ * Mirrors the napi-rs `index.d.ts` but mapped into TS-friendly types that
+ * this package owns (the `.d.ts` from the crate uses `Array<T>` and is
+ * regenerated at every build, so we don't import from it directly).
+ *
+ * @internal
+ */
+interface WorktreeNapiModule {
+    copyPathsParallel(srcDir: string, destDir: string, paths: string[], opts: CopyOptsNapi): CopyResultNapi;
+    destroyWorktree(opts: DestroyOptsNapi): DestroyResultNapi;
+    readWorktreeInclude(repoRoot: string): IncludePatternNapi[];
+    applyInclude(patterns: IncludePatternNapi[], srcDir: string, destDir: string, opts: CopyOptsNapi): CopyResultNapi;
+    listWorktrees(opts: ListOptsNapi): WorktreeInfoNapi[];
+}
+export declare const copyPathsParallel: WorktreeNapiModule['copyPathsParallel'];
+export declare const destroyWorktree: WorktreeNapiModule['destroyWorktree'];
+export declare const readWorktreeInclude: WorktreeNapiModule['readWorktreeInclude'];
+export declare const applyInclude: WorktreeNapiModule['applyInclude'];
+export declare const listWorktrees: WorktreeNapiModule['listWorktrees'];
+export type { CopyOptsNapi, CopyResultNapi, DestroyOptsNapi, DestroyResultNapi, IncludePatternNapi, ListOptsNapi, WorktreeInfoNapi, };
+//# sourceMappingURL=napi-binding.d.ts.map

package/dist/napi-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"napi-binding.d.ts","sourceRoot":"","sources":["../src/napi-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,UAAU,YAAY;IACpB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,eAAe;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,UAAU,kBAAkB;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,UAAU,kBAAkB;IAC1B,iBAAiB,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,YAAY,GACjB,cAAc,CAAC;IAClB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAAC;IAC5D,YAAY,CACV,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,GACjB,cAAc,CAAC;IAClB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAAC;CACvD;AAsBD,eAAO,MAAM,iBAAiB,EAAE,kBAAkB,CAAC,mBAAmB,CAKN,CAAC;AAEjE,eAAO,MAAM,eAAe,EAAE,kBAAkB,CAAC,iBAAiB,CAC/B,CAAC;AAEpC,eAAO,MAAM,mBAAmB,EAAE,kBAAkB,CAAC,qBAAqB,CAC/B,CAAC;AAE5C,eAAO,MAAM,YAAY,EAAE,kBAAkB,CAAC,cAAc,CACD,CAAC;AAE5D,eAAO,MAAM,aAAa,EAAE,kBAAkB,CAAC,eAAe,CAC7B,CAAC;AAElC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,CAAC"}

package/dist/napi-binding.js

@@ -0,0 +1,43 @@
+/**
+ * ESM-friendly bridge to `@cleocode/worktree-napi` (a CommonJS native addon).
+ *
+ * The napi-rs loader at `crates/worktree-napi/index.cjs` exposes its surface as
+ * `module.exports = nativeBinding` — Node.js's CJS-to-ESM interop cannot
+ * statically detect named exports from a dynamic require(), so direct
+ * `import { copyPathsParallel } from '@cleocode/worktree-napi'` throws
+ * "does not provide an export named ..." at link time.
+ *
+ * This module wraps the native binding via `createRequire` so the import looks
+ * like a regular dynamic require from a CJS context. All consumers in this
+ * package import napi functions from THIS module, never directly from
+ * `@cleocode/worktree-napi`.
+ *
+ * @task T9982
+ */
+import { createRequire } from 'node:module';
+const require_ = createRequire(import.meta.url);
+/**
+ * Lazy-loaded handle to the native binding. The first call to any exported
+ * function triggers a `require()` of `@cleocode/worktree-napi`; subsequent
+ * calls reuse the cached module. This keeps the load failure off the
+ * import-time critical path so:
+ *
+ * - Compile-time consumers (tsc, biome) never touch the native module.
+ * - CLI startup never crashes when the .node is missing on a partial
+ *   install (the failure is deferred until an actual worktree op runs).
+ *
+ * @internal
+ */
+let nativeBinding = null;
+function getNative() {
+    if (nativeBinding === null) {
+        nativeBinding = require_('@cleocode/worktree-napi');
+    }
+    return nativeBinding;
+}
+export const copyPathsParallel = (srcDir, destDir, paths, opts) => getNative().copyPathsParallel(srcDir, destDir, paths, opts);
+export const destroyWorktree = (opts) => getNative().destroyWorktree(opts);
+export const readWorktreeInclude = (repoRoot) => getNative().readWorktreeInclude(repoRoot);
+export const applyInclude = (patterns, srcDir, destDir, opts) => getNative().applyInclude(patterns, srcDir, destDir, opts);
+export const listWorktrees = (opts) => getNative().listWorktrees(opts);
+//# sourceMappingURL=napi-binding.js.map

package/dist/napi-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"napi-binding.js","sourceRoot":"","sources":["../src/napi-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAyEhD;;;;;;;;;;;GAWG;AACH,IAAI,aAAa,GAA8B,IAAI,CAAC;AACpD,SAAS,SAAS;IAChB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,aAAa,GAAG,QAAQ,CAAC,yBAAyB,CAAuB,CAAC;IAC5E,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAA4C,CACxE,MAAM,EACN,OAAO,EACP,KAAK,EACL,IAAI,EACJ,EAAE,CAAC,SAAS,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AAEjE,MAAM,CAAC,MAAM,eAAe,GAA0C,CAAC,IAAI,EAAE,EAAE,CAC7E,SAAS,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,mBAAmB,GAA8C,CAAC,QAAQ,EAAE,EAAE,CACzF,SAAS,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAE5C,MAAM,CAAC,MAAM,YAAY,GAAuC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAClG,SAAS,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAE5D,MAAM,CAAC,MAAM,aAAa,GAAwC,CAAC,IAAI,EAAE,EAAE,CACzE,SAAS,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC"}

package/dist/worktree-create.d.ts

@@ -45,9 +45,11 @@ interface CreateWorktreeResultWithBootstrap extends CreateWorktreeResult {
  *    Otherwise create a new branch via `git worktree add -b <branch> <path> <baseRef>`.
  * 4. Optionally apply `git worktree lock` to prevent pruning.
  * 5. Run declarative `post-create` hooks.
- * 6. Apply `.cleo/worktree-include` glob patterns (symlinks).
- * 7. Copy `node_modules` and `packages/ * /dist` via copy-on-write when not already
- *    covered by worktree-include patterns.
+ * 6. Apply `.worktreeinclude` (or legacy `.cleo/worktree-include`) glob patterns —
+ *    real ignore::gitignore matching is delegated to `@cleocode/worktree-napi`.
+ * 7. NO hardcoded bootstrap copy (T9982). Projects that need node_modules /
+ *    packages/* /dist mirrored into the worktree MUST declare them in
+ *    `.worktreeinclude` — the multi-language native include file.
  * 8. Run declarative `post-start` hooks.
  * 9. Build and return the {@link CreateWorktreeResult}.
  *

package/dist/worktree-create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-create.d.ts","sourceRoot":"","sources":["../src/worktree-create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,qBAAqB,CAAC;AAG7B;;;;;;GAMG;AACH,UAAU,iCAAkC,SAAQ,oBAAoB;IACtE,SAAS,EAAE;QACT,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,WAAW,EAAE,kBAAkB,EAAE,CAAC;KACnC,CAAC;IACF,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AA2HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,iCAAiC,CAAC,CAyO5C"}
+{"version":3,"file":"worktree-create.d.ts","sourceRoot":"","sources":["../src/worktree-create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,UAAU,iCAAkC,SAAQ,oBAAoB;IACtE,SAAS,EAAE;QACT,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,WAAW,EAAE,kBAAkB,EAAE,CAAC;KACnC,CAAC;IACF,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAqGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,iCAAiC,CAAC,CA2N5C"}