sync-worktrees 3.2.0 → 3.3.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as path11 from "path";
+import * as path12 from "path";
 import { confirm as confirm2 } from "@inquirer/prompts";
 import * as cron3 from "node-cron";
 import pLimit3 from "p-limit";
@@ -77,6 +77,7 @@ var ERROR_MESSAGES = {
 };
 var ENV_CONSTANTS = {
   GIT_LFS_SKIP_SMUDGE: "GIT_LFS_SKIP_SMUDGE",
+  GIT_ATTR_SOURCE: "GIT_ATTR_SOURCE",
   NODE_ENV_TEST: "test"
 };
 var PATH_CONSTANTS = {
@@ -123,7 +124,7 @@ var HOOK_CONSTANTS = {
 
 // src/services/config-loader.service.ts
 import * as fs from "fs/promises";
-import * as path from "path";
+import * as path2 from "path";
 import { pathToFileURL } from "url";
 import * as cron from "node-cron";
 
@@ -147,14 +148,121 @@ function filterBranchesByName(branches, include, exclude) {
   return result;
 }
 
+// src/utils/git-url.ts
+function extractRepoNameFromUrl(gitUrl) {
+  const url = gitUrl.trim();
+  const sshMatch = url.match(/^git@[^:]+:(?:.+\/)?([^/]+?)(?:\.git)?$/);
+  if (sshMatch) {
+    return sshMatch[1];
+  }
+  const sshUrlMatch = url.match(/^ssh:\/\/[^/]+\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
+  if (sshUrlMatch) {
+    return sshUrlMatch[1];
+  }
+  const httpsMatch = url.match(/^https?:\/\/[^/]+\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
+  if (httpsMatch) {
+    return httpsMatch[1];
+  }
+  const fileMatch = url.match(/^file:\/\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
+  if (fileMatch) {
+    return fileMatch[1];
+  }
+  throw new Error(`Invalid Git URL format: ${gitUrl}`);
+}
+function getDefaultBareRepoDir(repoUrl, baseDir = ".bare") {
+  const repoName = extractRepoNameFromUrl(repoUrl);
+  return `${baseDir}/${repoName}`;
+}
+
+// src/utils/path-compare.ts
+import * as path from "path";
+var CASE_INSENSITIVE_PLATFORMS = /* @__PURE__ */ new Set(["darwin"]);
+function isCaseInsensitiveFs(platform = process.platform) {
+  return CASE_INSENSITIVE_PLATFORMS.has(platform);
+}
+function normalizePathForCompare(p, platform = process.platform) {
+  const resolved = path.resolve(p);
+  return isCaseInsensitiveFs(platform) ? resolved.toLowerCase() : resolved;
+}
+
+// src/errors/index.ts
+var SyncWorktreesError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (cause && cause.stack) {
+      this.stack = `${this.stack}
+Caused by: ${cause.stack}`;
+    }
+  }
+};
+var GitError = class extends SyncWorktreesError {
+  constructor(message, code, cause) {
+    super(message, `GIT_${code}`, cause);
+  }
+};
+var GitOperationError = class extends GitError {
+  constructor(operation, details, cause) {
+    super(`Git operation '${operation}' failed: ${details}`, "OPERATION_FAILED", cause);
+  }
+};
+var WorktreeError = class extends SyncWorktreesError {
+  constructor(message, code, cause) {
+    super(message, `WORKTREE_${code}`, cause);
+  }
+};
+var WorktreeNotCleanError = class extends WorktreeError {
+  constructor(path13, reasons) {
+    super(`Worktree at '${path13}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
+    this.path = path13;
+    this.reasons = reasons;
+  }
+};
+var ConfigError = class extends SyncWorktreesError {
+  constructor(message, code, cause) {
+    super(message, `CONFIG_${code}`, cause);
+  }
+};
+var ConfigValidationError = class extends ConfigError {
+  constructor(field, reason) {
+    super(`Invalid configuration for '${field}': ${reason}`, "VALIDATION_FAILED");
+    this.field = field;
+    this.reason = reason;
+  }
+};
+
+// src/utils/sanitize-name.ts
+var WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+var ILLEGAL_CHARS = /[<>:"|?*\x00-\x1f]/g;
+function sanitizeNameForPath(name, fieldContext = "name") {
+  if (!name || typeof name !== "string") {
+    throw new ConfigValidationError(fieldContext, "must be a non-empty string");
+  }
+  let cleaned = name.trim();
+  cleaned = cleaned.replace(/[/\\]/g, "-");
+  cleaned = cleaned.replace(/^\.+/, "");
+  cleaned = cleaned.replace(ILLEGAL_CHARS, "_");
+  cleaned = cleaned.replace(/[. ]+$/, "");
+  if (cleaned.length === 0) {
+    throw new ConfigValidationError(fieldContext, `'${name}' produces an empty path segment after sanitization`);
+  }
+  if (WINDOWS_RESERVED.test(cleaned)) {
+    throw new ConfigValidationError(fieldContext, `'${cleaned}' is a reserved name on Windows`);
+  }
+  return cleaned;
+}
+
 // src/services/config-loader.service.ts
 var ConfigLoaderService = class {
   async findConfigUpward(startDir) {
-    let current = path.resolve(startDir);
-    const root = path.parse(current).root;
+    let current = path2.resolve(startDir);
+    const root = path2.parse(current).root;
     while (true) {
       for (const name of CONFIG_FILE_NAMES) {
-        const candidate = path.join(current, name);
+        const candidate = path2.join(current, name);
         try {
           await fs.access(candidate);
           return candidate;
@@ -162,13 +270,13 @@ var ConfigLoaderService = class {
         }
       }
       if (current === root) return null;
-      const parent = path.dirname(current);
+      const parent = path2.dirname(current);
       if (parent === current) return null;
       current = parent;
     }
   }
   async loadConfigFile(configPath) {
-    const absolutePath = path.resolve(configPath);
+    const absolutePath = path2.resolve(configPath);
     try {
       await fs.access(absolutePath);
     } catch {
@@ -244,7 +352,11 @@ var ConfigLoaderService = class {
       if (repoObj.hooks !== void 0) {
         this.validateHooksConfig(repoObj.hooks, `Repository '${repoObj.name}'`);
       }
+      if (repoObj.sparseCheckout !== void 0) {
+        this.validateSparseCheckoutConfig(repoObj.sparseCheckout, `Repository '${repoObj.name}'`);
+      }
     });
+    this.warnOnDuplicateRepoUrls(configObj.repositories);
     if (configObj.defaults) {
       if (typeof configObj.defaults !== "object") {
         throw new Error("'defaults' must be an object");
@@ -268,6 +380,9 @@ var ConfigLoaderService = class {
       if (defaults.hooks !== void 0) {
         this.validateHooksConfig(defaults.hooks, "defaults");
       }
+      if (defaults.sparseCheckout !== void 0) {
+        this.validateSparseCheckoutConfig(defaults.sparseCheckout, "defaults");
+      }
     }
     if (configObj.retry !== void 0) {
       if (typeof configObj.retry !== "object") {
@@ -357,6 +472,60 @@ var ConfigLoaderService = class {
       }
     }
   }
+  validateSparseCheckoutConfig(value, context) {
+    if (typeof value !== "object" || value === null) {
+      throw new Error(`'sparseCheckout' in ${context} must be an object`);
+    }
+    const cfg = value;
+    if (!Array.isArray(cfg.include)) {
+      throw new Error(`'sparseCheckout.include' in ${context} must be an array`);
+    }
+    if (cfg.include.length === 0) {
+      throw new Error(`'sparseCheckout.include' in ${context} must contain at least one pattern`);
+    }
+    for (let i = 0; i < cfg.include.length; i++) {
+      const p = cfg.include[i];
+      if (typeof p !== "string" || p.trim() === "") {
+        throw new Error(
+          `'sparseCheckout.include' in ${context} must contain only non-empty strings (invalid at index ${i})`
+        );
+      }
+    }
+    if (cfg.exclude !== void 0) {
+      if (!Array.isArray(cfg.exclude)) {
+        throw new Error(`'sparseCheckout.exclude' in ${context} must be an array`);
+      }
+      for (let i = 0; i < cfg.exclude.length; i++) {
+        const p = cfg.exclude[i];
+        if (typeof p !== "string" || p.trim() === "") {
+          throw new Error(
+            `'sparseCheckout.exclude' in ${context} must contain only non-empty strings (invalid at index ${i})`
+          );
+        }
+      }
+    }
+    if (cfg.mode !== void 0 && cfg.mode !== "cone" && cfg.mode !== "no-cone") {
+      throw new Error(`'sparseCheckout.mode' in ${context} must be 'cone' or 'no-cone'`);
+    }
+  }
+  warnOnDuplicateRepoUrls(repositories) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const repo of repositories) {
+      const url = typeof repo.repoUrl === "string" ? repo.repoUrl : null;
+      const name = typeof repo.name === "string" ? repo.name : null;
+      if (!url || !name) continue;
+      const list = seen.get(url) ?? [];
+      list.push(name);
+      seen.set(url, list);
+    }
+    for (const [url, names] of seen) {
+      if (names.length > 1) {
+        console.warn(
+          `[sync-worktrees] repoUrl '${url}' appears in multiple entries (${names.join(", ")}). Pin 'bareRepoDir' on duplicate entries to make config reorder-proof.`
+        );
+      }
+    }
+  }
   validateHooksConfig(hooks, context) {
     if (typeof hooks !== "object" || hooks === null) {
       throw new Error(`'hooks' in ${context} must be an object`);
@@ -376,7 +545,7 @@ var ConfigLoaderService = class {
       }
     }
   }
-  resolveRepositoryConfig(repo, defaults, configDir, globalRetry) {
+  resolveRepositoryConfig(repo, defaults, configDir, globalRetry, allRepositories) {
     const resolved = {
       name: repo.name,
       repoUrl: repo.repoUrl,
@@ -386,6 +555,11 @@ var ConfigLoaderService = class {
     };
     if (repo.bareRepoDir) {
       resolved.bareRepoDir = this.resolvePath(repo.bareRepoDir, configDir);
+    } else if (allRepositories && this.isDuplicateRepoUrl(repo, allRepositories)) {
+      const sanitized = sanitizeNameForPath(repo.name, `Repository '${repo.name}' name`);
+      resolved.bareRepoDir = this.resolvePath(`.bare/${sanitized}`, configDir);
+    } else {
+      resolved.bareRepoDir = this.resolvePath(getDefaultBareRepoDir(repo.repoUrl), configDir);
     }
     if (repo.branchMaxAge || defaults?.branchMaxAge) {
       resolved.branchMaxAge = repo.branchMaxAge ?? defaults?.branchMaxAge;
@@ -425,8 +599,32 @@ var ConfigLoaderService = class {
         ...repo.hooks || {}
       };
     }
+    const sparse = repo.sparseCheckout ?? defaults?.sparseCheckout;
+    if (sparse) {
+      resolved.sparseCheckout = sparse;
+    }
     return resolved;
   }
+  isDuplicateRepoUrl(repo, all) {
+    const firstIndex = all.findIndex((r) => r.repoUrl === repo.repoUrl);
+    const myIndex = all.indexOf(repo);
+    return firstIndex !== -1 && myIndex !== -1 && myIndex !== firstIndex;
+  }
+  detectBareRepoDirCollisions(repositories) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const repo of repositories) {
+      if (!repo.bareRepoDir) continue;
+      const key = normalizePathForCompare(repo.bareRepoDir);
+      const displayPath = path2.resolve(repo.bareRepoDir);
+      const existing = seen.get(key);
+      if (existing && existing.name !== repo.name) {
+        throw new Error(
+          `Repositories '${existing.name}' and '${repo.name}' resolve to the same bareRepoDir '${displayPath}'. Set distinct 'bareRepoDir' values for duplicate repoUrl entries.`
+        );
+      }
+      seen.set(key, { name: repo.name, displayPath });
+    }
+  }
   isValidGitUrl(url) {
     if (/^https?:\/\/.+/.test(url)) return true;
     if (/^(ssh:\/\/|git@).+/.test(url)) return true;
@@ -435,10 +633,10 @@ var ConfigLoaderService = class {
     return false;
   }
   resolvePath(inputPath, baseDir) {
-    if (path.isAbsolute(inputPath)) {
+    if (path2.isAbsolute(inputPath)) {
       return inputPath;
     }
-    return path.resolve(baseDir || process.cwd(), inputPath);
+    return path2.resolve(baseDir || process.cwd(), inputPath);
   }
   filterRepositories(repositories, filter) {
     if (!filter) {
@@ -451,10 +649,11 @@ var ConfigLoaderService = class {
   }
   async buildRepositories(configPath, overrides) {
     const configFile = await this.loadConfigFile(configPath);
-    const configDir = path.dirname(path.resolve(configPath));
+    const configDir = path2.dirname(path2.resolve(configPath));
     let repositories = configFile.repositories.map(
-      (repo) => this.resolveRepositoryConfig(repo, configFile.defaults, configDir, configFile.retry)
+      (repo) => this.resolveRepositoryConfig(repo, configFile.defaults, configDir, configFile.retry, configFile.repositories)
     );
+    this.detectBareRepoDirCollisions(repositories);
     if (overrides?.filter) {
       repositories = this.filterRepositories(repositories, overrides.filter);
     }
@@ -470,7 +669,7 @@ var ConfigLoaderService = class {
 
 // src/services/InteractiveUIService.tsx
 import React8 from "react";
-import * as path8 from "path";
+import * as path9 from "path";
 import { render } from "ink";
 import * as cron2 from "node-cron";
 import pLimit2 from "p-limit";
@@ -1746,7 +1945,7 @@ var App_default = App;
 
 // src/services/worktree-sync.service.ts
 import * as fs6 from "fs/promises";
-import * as path6 from "path";
+import * as path7 from "path";
 import pLimit from "p-limit";
 
 // src/utils/date-filter.ts
@@ -1867,7 +2066,7 @@ async function retry(fn, options = {}) {
       const jitter = opts.jitterMs > 0 ? Math.random() * opts.jitterMs : 0;
       const delay = baseDelay + jitter;
       opts.onRetry(error, attempt, lfsContext);
-      await new Promise((resolve8) => setTimeout(resolve8, delay));
+      await new Promise((resolve9) => setTimeout(resolve9, delay));
       attempt++;
     }
   }
@@ -1975,71 +2174,8 @@ function formatTimingTable(totalDuration, phaseResults, repoName) {
 
 // src/services/git.service.ts
 import * as fs4 from "fs/promises";
-import * as path4 from "path";
-import simpleGit3 from "simple-git";
-
-// src/errors/index.ts
-var SyncWorktreesError = class extends Error {
-  constructor(message, code, cause) {
-    super(message);
-    this.code = code;
-    this.cause = cause;
-    this.name = this.constructor.name;
-    Object.setPrototypeOf(this, new.target.prototype);
-    if (cause && cause.stack) {
-      this.stack = `${this.stack}
-Caused by: ${cause.stack}`;
-    }
-  }
-};
-var GitError = class extends SyncWorktreesError {
-  constructor(message, code, cause) {
-    super(message, `GIT_${code}`, cause);
-  }
-};
-var GitOperationError = class extends GitError {
-  constructor(operation, details, cause) {
-    super(`Git operation '${operation}' failed: ${details}`, "OPERATION_FAILED", cause);
-  }
-};
-var WorktreeError = class extends SyncWorktreesError {
-  constructor(message, code, cause) {
-    super(message, `WORKTREE_${code}`, cause);
-  }
-};
-var WorktreeNotCleanError = class extends WorktreeError {
-  constructor(path12, reasons) {
-    super(`Worktree at '${path12}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
-    this.path = path12;
-    this.reasons = reasons;
-  }
-};
-
-// src/utils/git-url.ts
-function extractRepoNameFromUrl(gitUrl) {
-  const url = gitUrl.trim();
-  const sshMatch = url.match(/^git@[^:]+:(?:.+\/)?([^/]+?)(?:\.git)?$/);
-  if (sshMatch) {
-    return sshMatch[1];
-  }
-  const sshUrlMatch = url.match(/^ssh:\/\/[^/]+\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
-  if (sshUrlMatch) {
-    return sshUrlMatch[1];
-  }
-  const httpsMatch = url.match(/^https?:\/\/[^/]+\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
-  if (httpsMatch) {
-    return httpsMatch[1];
-  }
-  const fileMatch = url.match(/^file:\/\/(?:.+\/)?([^/]+?)(?:\.git)?$/);
-  if (fileMatch) {
-    return fileMatch[1];
-  }
-  throw new Error(`Invalid Git URL format: ${gitUrl}`);
-}
-function getDefaultBareRepoDir(repoUrl, baseDir = ".bare") {
-  const repoName = extractRepoNameFromUrl(repoUrl);
-  return `${baseDir}/${repoName}`;
-}
+import * as path5 from "path";
+import simpleGit4 from "simple-git";
 
 // src/utils/worktree-list-parser.ts
 function parseWorktreeListPorcelain(output) {
@@ -2181,10 +2317,101 @@ function defaultConsoleOutput(msg, level) {
   else console.log(msg);
 }
 
+// src/services/sparse-checkout.service.ts
+import simpleGit from "simple-git";
+var SparseCheckoutService = class {
+  logger;
+  gitFactory;
+  warnedConfigs = /* @__PURE__ */ new WeakSet();
+  constructor(logger, gitFactory) {
+    this.logger = logger ?? Logger.createDefault();
+    this.gitFactory = gitFactory ?? ((p) => simpleGit(p));
+  }
+  updateLogger(logger) {
+    this.logger = logger;
+  }
+  resolveMode(cfg) {
+    const hasExclude = !!cfg.exclude && cfg.exclude.length > 0;
+    const hasNegation = cfg.include.some((p) => p.trim().startsWith("!"));
+    if (cfg.mode === "no-cone") return "no-cone";
+    if (hasExclude || hasNegation) {
+      if (cfg.mode === "cone" && !this.warnedConfigs.has(cfg)) {
+        this.logger.warn(
+          "sparseCheckout: mode 'cone' is incompatible with excludes or negation patterns; auto-promoting to 'no-cone'"
+        );
+        this.warnedConfigs.add(cfg);
+      }
+      return "no-cone";
+    }
+    return cfg.mode ?? "cone";
+  }
+  buildPatterns(cfg) {
+    return this.buildPatternsForMode(cfg, this.resolveMode(cfg));
+  }
+  buildPatternsForMode(cfg, mode) {
+    const includes = cfg.include.map((p) => p.trim()).filter((p) => p.length > 0);
+    if (mode === "cone") {
+      return includes;
+    }
+    const excludes = (cfg.exclude ?? []).map((p) => p.trim()).filter((p) => p.length > 0).map((p) => p.startsWith("!") ? p : `!${p}`);
+    return [...includes, ...excludes];
+  }
+  async applyToWorktree(worktreePath, cfg) {
+    const mode = this.resolveMode(cfg);
+    const patterns = this.buildPatternsForMode(cfg, mode);
+    if (patterns.length === 0) {
+      throw new Error("sparseCheckout produced no patterns; refusing to apply empty config");
+    }
+    const git = this.gitFactory(worktreePath);
+    await git.raw(["sparse-checkout", "init", mode === "cone" ? "--cone" : "--no-cone"]);
+    await git.raw(["sparse-checkout", "set", mode === "cone" ? "--cone" : "--no-cone", ...patterns]);
+  }
+  async readCurrent(worktreePath) {
+    const git = this.gitFactory(worktreePath);
+    try {
+      const out = await git.raw(["sparse-checkout", "list"]);
+      const lines = out.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
+      return lines.length === 0 ? null : lines;
+    } catch {
+      return null;
+    }
+  }
+  async needsUpdate(worktreePath, cfg) {
+    const current = await this.readCurrent(worktreePath);
+    const desired = this.buildPatterns(cfg);
+    if (current === null) return true;
+    return !this.patternsEqual(current, desired);
+  }
+  isNarrowing(currentPatterns, nextPatterns) {
+    if (!currentPatterns || currentPatterns.length === 0) return false;
+    const isNeg = (p) => p.startsWith("!");
+    const trim = (xs) => xs.map((p) => p.trim()).filter((p) => p.length > 0);
+    const cur = trim(currentPatterns);
+    const next = trim(nextPatterns);
+    const positiveCurrent = new Set(cur.filter((p) => !isNeg(p)));
+    const negativeCurrent = new Set(cur.filter(isNeg));
+    const positiveNext = new Set(next.filter((p) => !isNeg(p)));
+    const negativeNext = new Set(next.filter(isNeg));
+    for (const p of positiveCurrent) {
+      if (!positiveNext.has(p)) return true;
+    }
+    for (const p of negativeNext) {
+      if (!negativeCurrent.has(p)) return true;
+    }
+    return false;
+  }
+  patternsEqual(a, b) {
+    if (a.length !== b.length) return false;
+    const at = a.map((x) => x.trim());
+    const bt = b.map((x) => x.trim());
+    return at.every((v, i) => v === bt[i]);
+  }
+};
+
 // src/services/worktree-metadata.service.ts
 import * as fs2 from "fs/promises";
-import * as path2 from "path";
-import simpleGit from "simple-git";
+import * as path3 from "path";
+import simpleGit2 from "simple-git";
 var WorktreeMetadataService = class {
   logger;
   constructor(logger) {
@@ -2196,7 +2423,7 @@ var WorktreeMetadataService = class {
    * For example: /worktrees/fix/test-branch -> test-branch (not fix/test-branch)
    */
   getWorktreeDirectoryName(worktreePath) {
-    return path2.basename(worktreePath);
+    return path3.basename(worktreePath);
   }
   async getMetadataPath(bareRepoPath, worktreeName) {
     if (worktreeName.includes("/") || worktreeName.includes("\\")) {
@@ -2204,7 +2431,7 @@ var WorktreeMetadataService = class {
         `getMetadataPath requires a filesystem-safe worktree directory name, got '${worktreeName}'. Use getMetadataPathFromWorktreePath when starting from a raw branch name.`
       );
     }
-    return path2.join(
+    return path3.join(
       bareRepoPath,
       METADATA_CONSTANTS.WORKTREE_METADATA_PATH,
       worktreeName,
@@ -2217,7 +2444,7 @@ var WorktreeMetadataService = class {
   }
   async saveMetadata(bareRepoPath, worktreeName, metadata) {
     const metadataPath = await this.getMetadataPath(bareRepoPath, worktreeName);
-    await fs2.mkdir(path2.dirname(metadataPath), { recursive: true });
+    await fs2.mkdir(path3.dirname(metadataPath), { recursive: true });
     const tmpPath = `${metadataPath}.${process.pid}.${Date.now()}.tmp`;
     let renamed = false;
     try {
@@ -2308,7 +2535,7 @@ var WorktreeMetadataService = class {
       this.logger.warn(`No metadata found for worktree ${worktreeDirName}`);
       this.logger.info(`  Attempting to create initial metadata...`);
       try {
-        const worktreeGit = simpleGit(worktreePath);
+        const worktreeGit = simpleGit2(worktreePath);
         const currentCommit = await worktreeGit.revparse(["HEAD"]);
         const branchSummary = await worktreeGit.branch();
         const actualBranchName = branchSummary.current;
@@ -2410,8 +2637,8 @@ var WorktreeMetadataService = class {
 
 // src/services/worktree-status.service.ts
 import * as fs3 from "fs/promises";
-import * as path3 from "path";
-import simpleGit2 from "simple-git";
+import * as path4 from "path";
+import simpleGit3 from "simple-git";
 var OPERATION_FILES = [
   { file: GIT_OPERATIONS.MERGE_HEAD, type: "merge" },
   { file: GIT_OPERATIONS.CHERRY_PICK_HEAD, type: "cherry-pick" },
@@ -2613,7 +2840,7 @@ var WorktreeStatusService = class {
   async detectOperationFile(gitDir) {
     const results = await Promise.all(
       OPERATION_FILES.map(
-        ({ file }) => fs3.access(path3.join(gitDir, file)).then(
+        ({ file }) => fs3.access(path4.join(gitDir, file)).then(
           () => true,
           () => false
         )
@@ -2734,14 +2961,14 @@ var WorktreeStatusService = class {
     }
   }
   async resolveGitDir(worktreePath) {
-    const gitPath = path3.join(worktreePath, PATH_CONSTANTS.GIT_DIR);
+    const gitPath = path4.join(worktreePath, PATH_CONSTANTS.GIT_DIR);
     try {
       const stat3 = await fs3.stat(gitPath);
       if (stat3.isFile()) {
         const content = await fs3.readFile(gitPath, "utf-8");
         const gitdirMatch = content.match(new RegExp(`^${GIT_CONSTANTS.GITDIR_PREFIX}\\s*(.+)$`, "m"));
         if (gitdirMatch) {
-          return path3.resolve(worktreePath, gitdirMatch[1].trim());
+          return path4.resolve(worktreePath, gitdirMatch[1].trim());
         }
         throw new GitOperationError("resolve-git-dir", `Failed to parse gitdir from .git file at ${gitPath}`);
       }
@@ -2755,10 +2982,10 @@ var WorktreeStatusService = class {
     }
   }
   createGitInstance(worktreePath) {
-    const key = `${path3.resolve(worktreePath)}::${this.config.skipLfs ? "1" : "0"}`;
+    const key = `${path4.resolve(worktreePath)}::${this.config.skipLfs ? "1" : "0"}`;
     let git = this.gitInstances.get(key);
     if (!git) {
-      git = this.config.skipLfs ? simpleGit2(worktreePath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit2(worktreePath);
+      git = this.config.skipLfs ? simpleGit3(worktreePath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit3(worktreePath);
       this.gitInstances.set(key, git);
     }
     return git;
@@ -2766,14 +2993,22 @@ var WorktreeStatusService = class {
 };
 
 // src/services/git.service.ts
+function sanitizeGitEnv(env) {
+  const sanitized = { ...env };
+  delete sanitized.EDITOR;
+  delete sanitized.GIT_EDITOR;
+  delete sanitized.GIT_SEQUENCE_EDITOR;
+  return sanitized;
+}
 var GitService = class {
   constructor(config, logger) {
     this.config = config;
     this.logger = logger ?? Logger.createDefault(void 0, config.debug);
     this.bareRepoPath = this.config.bareRepoDir || getDefaultBareRepoDir(this.config.repoUrl);
-    this.mainWorktreePath = path4.join(this.config.worktreeDir, GIT_CONSTANTS.DEFAULT_BRANCH);
+    this.mainWorktreePath = path5.join(this.config.worktreeDir, GIT_CONSTANTS.DEFAULT_BRANCH);
     this.metadataService = new WorktreeMetadataService(this.logger);
     this.statusService = new WorktreeStatusService({ skipLfs: this.config.skipLfs }, this.logger);
+    this.sparseCheckoutService = new SparseCheckoutService(this.logger);
   }
   git = null;
   bareRepoPath;
@@ -2782,29 +3017,34 @@ var GitService = class {
   // Will be updated after detection
   metadataService;
   statusService;
+  sparseCheckoutService;
   logger;
   lfsSkipOverride = false;
   gitInstances = /* @__PURE__ */ new Map();
+  getSparseCheckoutService() {
+    return this.sparseCheckoutService;
+  }
   getCachedGit(dirPath, useLfsSkip = false) {
-    const key = `${path4.resolve(dirPath)}::${useLfsSkip ? "1" : "0"}`;
+    const key = `${path5.resolve(dirPath)}::${useLfsSkip ? "1" : "0"}`;
     let git = this.gitInstances.get(key);
     if (!git) {
-      git = useLfsSkip ? simpleGit3(dirPath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit3(dirPath);
+      git = useLfsSkip ? simpleGit4(dirPath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit4(dirPath);
       this.gitInstances.set(key, git);
     }
     return git;
   }
   updateLogger(logger) {
     this.logger = logger;
+    this.sparseCheckoutService.updateLogger(logger);
   }
   async initialize() {
     const { repoUrl } = this.config;
     try {
-      await fs4.access(path4.join(this.bareRepoPath, "HEAD"));
+      await fs4.access(path5.join(this.bareRepoPath, "HEAD"));
     } catch {
       this.logger.info(`Cloning from "${repoUrl}" as bare repository into "${this.bareRepoPath}"...`);
-      await fs4.mkdir(path4.dirname(this.bareRepoPath), { recursive: true });
-      const cloneGit = this.isLfsSkipEnabled() ? simpleGit3().env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit3();
+      await fs4.mkdir(path5.dirname(this.bareRepoPath), { recursive: true });
+      const cloneGit = this.isLfsSkipEnabled() ? simpleGit4().env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit4();
       await cloneGit.clone(repoUrl, this.bareRepoPath, ["--bare"]);
       this.logger.info("\u2705 Clone successful.");
     }
@@ -2821,34 +3061,39 @@ var GitService = class {
     this.logger.info("Fetching remote branches...");
     await bareGit.fetch(["--all"]);
     this.defaultBranch = await this.detectDefaultBranch(bareGit);
-    this.mainWorktreePath = path4.join(this.config.worktreeDir, this.defaultBranch);
+    this.mainWorktreePath = path5.join(this.config.worktreeDir, this.defaultBranch);
     let needsMainWorktree = true;
     try {
       const worktrees = await this.getWorktreesFromBare(bareGit);
-      needsMainWorktree = !worktrees.some((w) => path4.resolve(w.path) === path4.resolve(this.mainWorktreePath));
+      needsMainWorktree = !worktrees.some((w) => path5.resolve(w.path) === path5.resolve(this.mainWorktreePath));
     } catch {
     }
     if (needsMainWorktree) {
       this.logger.info(`Creating ${this.defaultBranch} worktree at "${this.mainWorktreePath}"...`);
       await fs4.mkdir(this.config.worktreeDir, { recursive: true });
-      const absoluteWorktreePath = path4.resolve(this.mainWorktreePath);
+      const absoluteWorktreePath = path5.resolve(this.mainWorktreePath);
       const branches = await bareGit.branch();
       const defaultBranchExists = branches.all.includes(this.defaultBranch);
+      const useNoCheckoutMain = !!this.config.sparseCheckout;
+      const noCheckoutFlagMain = useNoCheckoutMain ? ["--no-checkout"] : [];
       try {
         if (defaultBranchExists) {
-          await bareGit.raw(["worktree", "add", absoluteWorktreePath, this.defaultBranch]);
+          await bareGit.raw(["worktree", "add", ...noCheckoutFlagMain, absoluteWorktreePath, this.defaultBranch]);
           const worktreeGit = this.getCachedGit(absoluteWorktreePath, this.isLfsSkipEnabled());
           await worktreeGit.branch(["--set-upstream-to", `origin/${this.defaultBranch}`, this.defaultBranch]);
+          await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, this.defaultBranch, false);
         } else {
           await bareGit.raw([
             "worktree",
             "add",
+            ...noCheckoutFlagMain,
             "--track",
             "-b",
             this.defaultBranch,
             absoluteWorktreePath,
             `origin/${this.defaultBranch}`
           ]);
+          await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, this.defaultBranch, true);
         }
       } catch (error) {
         const errorMessage = getErrorMessage(error);
@@ -2862,7 +3107,7 @@ var GitService = class {
       }
       const updatedWorktrees = await this.getWorktreesFromBare(bareGit);
       const mainWorktreeRegistered = updatedWorktrees.some(
-        (w) => path4.resolve(w.path) === path4.resolve(this.mainWorktreePath)
+        (w) => path5.resolve(w.path) === path5.resolve(this.mainWorktreePath)
       );
       if (!mainWorktreeRegistered) {
         if (process.env.NODE_ENV !== ENV_CONSTANTS.NODE_ENV_TEST) {
@@ -2931,13 +3176,29 @@ var GitService = class {
     return branches;
   }
   async verifyLfsFilesDownloaded(worktreePath, branchName) {
-    const worktreeGit = this.getCachedGit(worktreePath);
+    const worktreeGit = this.config.sparseCheckout ? simpleGit4(worktreePath).env({ ...sanitizeGitEnv(process.env), [ENV_CONSTANTS.GIT_ATTR_SOURCE]: "HEAD" }) : this.getCachedGit(worktreePath);
     try {
       const lfsFiles = await worktreeGit.raw(["lfs", "ls-files", "--name-only"]);
-      const lfsFileList = lfsFiles.trim().split("\n").filter((f) => f.length > 0);
+      let lfsFileList = lfsFiles.trim().split("\n").filter((f) => f.length > 0);
       if (lfsFileList.length === 0) {
         return;
       }
+      if (this.config.sparseCheckout) {
+        const existence = await Promise.all(
+          lfsFileList.map(async (f) => {
+            try {
+              await fs4.access(path5.join(worktreePath, f));
+              return f;
+            } catch {
+              return null;
+            }
+          })
+        );
+        lfsFileList = existence.filter((f) => f !== null);
+        if (lfsFileList.length === 0) {
+          return;
+        }
+      }
       if (this.config.debug) {
         this.logger.info(`  - Verifying ${lfsFileList.length} LFS files are downloaded...`);
       }
@@ -2954,7 +3215,7 @@ var GitService = class {
         let allDownloaded = true;
         const notDownloaded = [];
         for (const file of samplesToCheck) {
-          const filePath = path4.join(worktreePath, file);
+          const filePath = path5.join(worktreePath, file);
           try {
             const handle = await fs4.open(filePath, "r");
             try {
@@ -2981,7 +3242,7 @@ var GitService = class {
         }
         retries++;
         if (retries < maxRetries) {
-          await new Promise((resolve8) => setTimeout(resolve8, retryDelay));
+          await new Promise((resolve9) => setTimeout(resolve9, retryDelay));
         }
       }
       this.logger.warn(
@@ -2991,6 +3252,38 @@ var GitService = class {
       this.logger.warn(`  - \u26A0\uFE0F Warning: Could not verify LFS files for '${branchName}': ${error}`);
     }
   }
+  async checkoutHead(worktreePath) {
+    const git = this.getCachedGit(worktreePath, this.isLfsSkipEnabled());
+    await git.raw(["checkout", "HEAD"]);
+  }
+  async applySparseAndCheckout(absoluteWorktreePath) {
+    if (!this.config.sparseCheckout) return;
+    await this.sparseCheckoutService.applyToWorktree(absoluteWorktreePath, this.config.sparseCheckout);
+    const worktreeGit = this.getCachedGit(absoluteWorktreePath, this.isLfsSkipEnabled());
+    await worktreeGit.raw(["checkout", "HEAD"]);
+  }
+  async rollbackPartialWorktree(bareGit, absoluteWorktreePath, branchName, createdNewBranch, failureContext) {
+    let worktreeRemoved = true;
+    try {
+      await bareGit.raw(["worktree", "remove", "--force", absoluteWorktreePath]);
+    } catch (rollbackError) {
+      worktreeRemoved = false;
+      const ctx = failureContext ? ` after ${failureContext}` : "";
+      this.logger.warn(
+        `  - Rollback failed for '${branchName}' at '${absoluteWorktreePath}'${ctx}: ${getErrorMessage(rollbackError)}`
+      );
+    }
+    if (createdNewBranch) {
+      try {
+        await bareGit.raw(["branch", "-D", branchName]);
+      } catch (branchRollbackError) {
+        this.logger.warn(
+          `  - Rollback (branch delete) failed for '${branchName}': ${getErrorMessage(branchRollbackError)}`
+        );
+      }
+    }
+    return { worktreeRemoved };
+  }
   async createWorktreeMetadata(bareGit, worktreePath, branchName) {
     try {
       const worktreeGit = this.getCachedGit(worktreePath, this.isLfsSkipEnabled());
@@ -3011,12 +3304,12 @@ var GitService = class {
   }
   async addWorktree(branchName, worktreePath) {
     const bareGit = this.getCachedGit(this.bareRepoPath, this.isLfsSkipEnabled());
-    const absoluteWorktreePath = path4.resolve(worktreePath);
-    await fs4.mkdir(path4.dirname(absoluteWorktreePath), { recursive: true });
+    const absoluteWorktreePath = path5.resolve(worktreePath);
+    await fs4.mkdir(path5.dirname(absoluteWorktreePath), { recursive: true });
     try {
       await fs4.access(absoluteWorktreePath);
       const worktrees = await this.getWorktreesFromBare(bareGit);
-      const isValidWorktree = worktrees.some((w) => path4.resolve(w.path) === absoluteWorktreePath);
+      const isValidWorktree = worktrees.some((w) => path5.resolve(w.path) === absoluteWorktreePath);
       if (isValidWorktree) {
         this.logger.info(`  - Worktree for '${branchName}' already exists at '${absoluteWorktreePath}'`);
         return;
@@ -3026,9 +3319,10 @@ var GitService = class {
       }
     } catch {
     }
+    let createdNewBranch = false;
     try {
       const { local: localBranchExists, remote: remoteBranchExists } = await this.branchExists(branchName);
-      await this.runWorktreeAddByMatrix(
+      createdNewBranch = await this.runWorktreeAddByMatrix(
         bareGit,
         branchName,
         absoluteWorktreePath,
@@ -3047,10 +3341,7 @@ var GitService = class {
         await this.createWorktreeMetadata(bareGit, absoluteWorktreePath, branchName);
       } catch (metadataError) {
         this.logger.warn(`  - Metadata creation failed for '${branchName}', removing worktree to prevent orphan`);
-        try {
-          await bareGit.raw(["worktree", "remove", "--force", absoluteWorktreePath]);
-        } catch {
-        }
+        await this.rollbackPartialWorktree(bareGit, absoluteWorktreePath, branchName, createdNewBranch);
         throw new Error(`Metadata creation failed for '${branchName}': ${getErrorMessage(metadataError)}`);
       }
     } catch (error) {
@@ -3063,7 +3354,7 @@ var GitService = class {
       }
       if (errorMessage.includes("already registered worktree")) {
         const worktrees = await this.getWorktreesFromBare(bareGit);
-        const existingWorktree = worktrees.find((w) => path4.resolve(w.path) === absoluteWorktreePath);
+        const existingWorktree = worktrees.find((w) => path5.resolve(w.path) === absoluteWorktreePath);
         if (existingWorktree && !existingWorktree.isPrunable) {
           this.logger.info(`  - Worktree for '${branchName}' was created by concurrent operation`);
           return;
@@ -3074,9 +3365,10 @@ var GitService = class {
           await fs4.rm(absoluteWorktreePath, { recursive: true, force: true });
         } catch {
         }
+        let retryCreatedNewBranch = false;
         try {
           const { local: localBranchExists, remote: remoteBranchExists } = await this.branchExists(branchName);
-          await this.runWorktreeAddByMatrix(
+          retryCreatedNewBranch = await this.runWorktreeAddByMatrix(
             bareGit,
             branchName,
             absoluteWorktreePath,
@@ -3091,10 +3383,7 @@ var GitService = class {
             await this.createWorktreeMetadata(bareGit, absoluteWorktreePath, branchName);
           } catch (metadataError) {
             this.logger.warn(`  - Metadata creation failed for '${branchName}', removing worktree to prevent orphan`);
-            try {
-              await bareGit.raw(["worktree", "remove", "--force", absoluteWorktreePath]);
-            } catch {
-            }
+            await this.rollbackPartialWorktree(bareGit, absoluteWorktreePath, branchName, retryCreatedNewBranch);
             throw new Error(`Metadata creation failed for '${branchName}': ${getErrorMessage(metadataError)}`);
           }
           return;
@@ -3111,7 +3400,7 @@ var GitService = class {
       try {
         await fs4.access(absoluteWorktreePath);
         const worktrees = await this.getWorktreesFromBare(bareGit);
-        const isValidWorktree = worktrees.some((w) => path4.resolve(w.path) === absoluteWorktreePath);
+        const isValidWorktree = worktrees.some((w) => path5.resolve(w.path) === absoluteWorktreePath);
         if (isValidWorktree) {
           this.logger.info(`  - Worktree for '${branchName}' already exists at '${absoluteWorktreePath}'`);
           return;
@@ -3122,7 +3411,10 @@ var GitService = class {
       } catch {
       }
       try {
-        await bareGit.raw(["worktree", "add", absoluteWorktreePath, branchName]);
+        const useNoCheckout = !!this.config.sparseCheckout;
+        const fallbackArgs = useNoCheckout ? ["worktree", "add", "--no-checkout", absoluteWorktreePath, branchName] : ["worktree", "add", absoluteWorktreePath, branchName];
+        await bareGit.raw(fallbackArgs);
+        await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, false);
         this.logger.info(`  - Created worktree for '${branchName}' (without tracking)`);
         if (!this.isLfsSkipEnabled()) {
           await this.verifyLfsFilesDownloaded(absoluteWorktreePath, branchName);
@@ -3131,17 +3423,14 @@ var GitService = class {
           await this.createWorktreeMetadata(bareGit, absoluteWorktreePath, branchName);
         } catch (metadataError) {
           this.logger.warn(`  - Metadata creation failed for '${branchName}', removing worktree to prevent orphan`);
-          try {
-            await bareGit.raw(["worktree", "remove", "--force", absoluteWorktreePath]);
-          } catch {
-          }
+          await this.rollbackPartialWorktree(bareGit, absoluteWorktreePath, branchName, false);
           throw new Error(`Metadata creation failed for '${branchName}': ${getErrorMessage(metadataError)}`);
         }
       } catch (fallbackError) {
         const fallbackErrorMessage = getErrorMessage(fallbackError);
         if (fallbackErrorMessage.includes("already registered worktree")) {
           const worktrees = await this.getWorktreesFromBare(bareGit);
-          const existingWorktree = worktrees.find((w) => path4.resolve(w.path) === absoluteWorktreePath);
+          const existingWorktree = worktrees.find((w) => path5.resolve(w.path) === absoluteWorktreePath);
           if (existingWorktree && !existingWorktree.isPrunable) {
             this.logger.info(`  - Worktree for '${branchName}' was created by concurrent operation during fallback`);
             return;
@@ -3152,42 +3441,64 @@ var GitService = class {
     }
   }
   async runWorktreeAddByMatrix(bareGit, branchName, absoluteWorktreePath, localExists, remoteExists) {
+    const useNoCheckout = !!this.config.sparseCheckout;
+    const noCheckoutFlag = useNoCheckout ? ["--no-checkout"] : [];
     if (localExists && remoteExists) {
-      await bareGit.raw(["worktree", "add", absoluteWorktreePath, branchName]);
+      await bareGit.raw(["worktree", "add", ...noCheckoutFlag, absoluteWorktreePath, branchName]);
       try {
         const worktreeGit = this.getCachedGit(absoluteWorktreePath, this.isLfsSkipEnabled());
         await worktreeGit.branch(["--set-upstream-to", `origin/${branchName}`, branchName]);
       } catch (error) {
-        let rollbackFailed = false;
-        try {
-          await bareGit.raw(["worktree", "remove", "--force", absoluteWorktreePath]);
-        } catch (rollbackError) {
-          rollbackFailed = true;
-          this.logger.warn(
-            `  - Rollback failed for '${branchName}' at '${absoluteWorktreePath}' after upstream setup error: ${getErrorMessage(rollbackError)}`
-          );
-        }
-        const detail = getErrorMessage(error);
-        const suffix = rollbackFailed ? " (rollback failed; partial worktree may remain)" : "";
-        const wrapped = new Error(`Failed to set upstream for '${branchName}': ${detail}${suffix}`);
-        wrapped.isUpstreamSetupFailure = true;
-        throw wrapped;
+        throw await this.wrapUpstreamFailure(bareGit, absoluteWorktreePath, branchName, false, error);
       }
-      return;
+      await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, false);
+      return false;
     }
     if (localExists) {
-      await bareGit.raw(["worktree", "add", absoluteWorktreePath, branchName]);
-      return;
+      await bareGit.raw(["worktree", "add", ...noCheckoutFlag, absoluteWorktreePath, branchName]);
+      await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, false);
+      return false;
     }
     if (remoteExists) {
-      await bareGit.raw(["worktree", "add", "--track", "-b", branchName, absoluteWorktreePath, `origin/${branchName}`]);
-      return;
+      await bareGit.raw([
+        "worktree",
+        "add",
+        ...noCheckoutFlag,
+        "--track",
+        "-b",
+        branchName,
+        absoluteWorktreePath,
+        `origin/${branchName}`
+      ]);
+      await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, true);
+      return true;
     }
     throw new WorktreeError(
       `Branch '${branchName}' does not exist locally or on origin; create it first`,
       "BRANCH_NOT_FOUND"
     );
   }
+  async runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, createdNewBranch) {
+    try {
+      await this.applySparseAndCheckout(absoluteWorktreePath);
+    } catch (sparseError) {
+      await this.rollbackPartialWorktree(bareGit, absoluteWorktreePath, branchName, createdNewBranch);
+      throw new Error(`Sparse-checkout setup failed for '${branchName}': ${getErrorMessage(sparseError)}`);
+    }
+  }
+  async wrapUpstreamFailure(bareGit, absoluteWorktreePath, branchName, createdNewBranch, error) {
+    const { worktreeRemoved } = await this.rollbackPartialWorktree(
+      bareGit,
+      absoluteWorktreePath,
+      branchName,
+      createdNewBranch,
+      "upstream setup error"
+    );
+    const suffix = worktreeRemoved ? "" : " (rollback failed; partial worktree may remain)";
+    const wrapped = new Error(`Failed to set upstream for '${branchName}': ${getErrorMessage(error)}${suffix}`);
+    wrapped.isUpstreamSetupFailure = true;
+    return wrapped;
+  }
   async removeWorktree(worktreePath) {
     const bareGit = this.getCachedGit(this.bareRepoPath);
     await bareGit.raw(["worktree", "remove", worktreePath, "--force"]);
@@ -3426,15 +3737,7 @@ var GitService = class {
 // src/services/path-resolution.service.ts
 import { createHash } from "crypto";
 import * as fs5 from "fs";
-import * as path5 from "path";
-
-// src/utils/path-compare.ts
-var CASE_INSENSITIVE_PLATFORMS = /* @__PURE__ */ new Set(["darwin"]);
-function isCaseInsensitiveFs(platform = process.platform) {
-  return CASE_INSENSITIVE_PLATFORMS.has(platform);
-}
-
-// src/services/path-resolution.service.ts
+import * as path6 from "path";
 var BRANCH_STEM_MAX = 80;
 var BRANCH_HASH_LEN = 8;
 var PathResolutionService = class {
@@ -3444,22 +3747,22 @@ var PathResolutionService = class {
     return `${stem}-${hash}`;
   }
   getBranchWorktreePath(worktreeDir, branchName) {
-    return path5.join(worktreeDir, this.sanitizeBranchName(branchName));
+    return path6.join(worktreeDir, this.sanitizeBranchName(branchName));
   }
   resolveRealPath(inputPath) {
-    const absolute = path5.resolve(inputPath);
+    const absolute = path6.resolve(inputPath);
     const missing = [];
     let current = absolute;
     while (!fs5.existsSync(current)) {
-      const parent = path5.dirname(current);
+      const parent = path6.dirname(current);
       if (parent === current) {
         return absolute;
       }
-      missing.unshift(path5.basename(current));
+      missing.unshift(path6.basename(current));
       current = parent;
     }
     try {
-      return path5.join(fs5.realpathSync(current), ...missing);
+      return path6.join(fs5.realpathSync(current), ...missing);
     } catch {
       return absolute;
     }
@@ -3469,7 +3772,7 @@ var PathResolutionService = class {
     const a = fold(resolved);
     const b = fold(resolvedBase);
     if (a === b) return true;
-    return a.length > b.length && a.charAt(b.length) === path5.sep && a.startsWith(b);
+    return a.length > b.length && a.charAt(b.length) === path6.sep && a.startsWith(b);
   }
   normalizeWorktreePath(worktreePath, worktreeBaseDir) {
     const resolved = this.resolveRealPath(worktreePath);
@@ -3477,7 +3780,7 @@ var PathResolutionService = class {
     if (!this.isResolvedPathInsideBase(resolved, resolvedBase)) {
       throw new Error(`Worktree path '${worktreePath}' is outside base directory '${worktreeBaseDir}'`);
     }
-    return path5.relative(resolvedBase, resolved);
+    return path6.relative(resolvedBase, resolved);
   }
   isPathInsideBaseDir(targetPath, baseDir) {
     const resolved = this.resolveRealPath(targetPath);
@@ -3603,8 +3906,50 @@ var WorktreeSyncService = class {
     if (this.config.updateExistingWorktrees !== false) {
       await this.updateExistingWorktreesWithTiming(worktrees, remoteBranches, phaseTimer);
     }
+    if (this.config.sparseCheckout) {
+      await this.reapplySparseCheckout(worktrees);
+    }
     await this.finalizeSyncAttempt(phaseTimer);
   }
+  async reapplySparseCheckout(worktrees) {
+    const sparseConfig = this.config.sparseCheckout;
+    if (!sparseConfig) return;
+    this.logger.info("Step 5: Reconciling sparse-checkout patterns on existing worktrees...");
+    const sparseService = this.gitService.getSparseCheckoutService();
+    const desired = sparseService.buildPatterns(sparseConfig);
+    const limit = pLimit(this.config.parallelism?.maxStatusChecks ?? DEFAULT_CONFIG.PARALLELISM.MAX_STATUS_CHECKS);
+    await Promise.all(
+      worktrees.map(
+        (worktree) => limit(async () => {
+          try {
+            try {
+              await fs6.access(worktree.path);
+            } catch {
+              return;
+            }
+            const current = await sparseService.readCurrent(worktree.path);
+            if (current !== null && sparseService.patternsEqual(current, desired)) return;
+            if (sparseService.isNarrowing(current, desired)) {
+              const status = await this.gitService.getFullWorktreeStatus(worktree.path, false);
+              if (!status.canRemove) {
+                this.logger.warn(
+                  `  - Skipping sparse-checkout narrowing for '${worktree.branch}': ${status.reasons.join(", ")}.`
+                );
+                return;
+              }
+            }
+            await sparseService.applyToWorktree(worktree.path, sparseConfig);
+            await this.gitService.checkoutHead(worktree.path);
+            this.logger.info(`  - \u2705 Sparse-checkout updated for '${worktree.branch}'`);
+          } catch (error) {
+            this.logger.warn(
+              `  - \u26A0\uFE0F Failed to update sparse-checkout for '${worktree.branch}': ${getErrorMessage(error)}`
+            );
+          }
+        })
+      )
+    );
+  }
   async fetchLatestRemoteData(phaseTimer, syncContext) {
     this.logger.info("Step 1: Fetching latest data from remote...");
     phaseTimer.startPhase("Phase 1: Fetch");
@@ -3696,12 +4041,12 @@ var WorktreeSyncService = class {
     }
     const reservedPaths = /* @__PURE__ */ new Map();
     for (const w of worktrees) {
-      reservedPaths.set(path6.resolve(w.path), w.branch);
+      reservedPaths.set(path7.resolve(w.path), w.branch);
     }
     const plan = [];
     for (const branchName of newBranches) {
       const worktreePath = this.pathResolution.getBranchWorktreePath(this.config.worktreeDir, branchName);
-      const resolved = path6.resolve(worktreePath);
+      const resolved = path7.resolve(worktreePath);
       const conflict = reservedPaths.get(resolved);
       if (conflict && conflict !== branchName) {
         this.logger.error(
@@ -3906,12 +4251,12 @@ var WorktreeSyncService = class {
   }
   async updateExistingWorktrees(worktrees, remoteBranches) {
     this.logger.info("Step 4: Checking for worktrees that need updates...");
-    const divergedDir = path6.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedDir = path7.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
     try {
       const diverged = await fs6.readdir(divergedDir);
       if (diverged.length > 0) {
         this.logger.info(
-          `\u{1F4E6} Note: ${diverged.length} diverged worktree(s) in ${path6.relative(process.cwd(), divergedDir)}`
+          `\u{1F4E6} Note: ${diverged.length} diverged worktree(s) in ${path7.relative(process.cwd(), divergedDir)}`
         );
       }
     } catch {
@@ -4019,13 +4364,13 @@ var WorktreeSyncService = class {
   }
   async cleanupOrphanedDirectories(worktrees) {
     try {
-      const worktreeRelativePaths = worktrees.map((w) => path6.relative(this.config.worktreeDir, w.path));
+      const worktreeRelativePaths = worktrees.map((w) => path7.relative(this.config.worktreeDir, w.path));
       const allDirs = await fs6.readdir(this.config.worktreeDir);
       const regularDirs = allDirs.filter((dir) => !dir.startsWith("."));
       const orphanedDirs = [];
       for (const dir of regularDirs) {
         const isPartOfWorktree = worktreeRelativePaths.some((worktreePath) => {
-          return worktreePath === dir || worktreePath.startsWith(dir + path6.sep);
+          return worktreePath === dir || worktreePath.startsWith(dir + path7.sep);
         });
         if (!isPartOfWorktree) {
           orphanedDirs.push(dir);
@@ -4034,7 +4379,7 @@ var WorktreeSyncService = class {
       if (orphanedDirs.length > 0) {
         this.logger.info(`Found ${orphanedDirs.length} orphaned directories: ${orphanedDirs.join(", ")}`);
         for (const dir of orphanedDirs) {
-          const dirPath = path6.join(this.config.worktreeDir, dir);
+          const dirPath = path7.join(this.config.worktreeDir, dir);
           try {
             const stat3 = await fs6.stat(dirPath);
             if (stat3.isDirectory()) {
@@ -4068,7 +4413,7 @@ var WorktreeSyncService = class {
       } else {
         this.logger.info(`\u{1F512} Branch '${worktree.branch}' has diverged with local changes. Moving to diverged...`);
         const divergedPath = await this.divergeWorktree(worktree.path, worktree.branch);
-        const relativePath = path6.relative(process.cwd(), divergedPath);
+        const relativePath = path7.relative(process.cwd(), divergedPath);
         this.logger.info(`   Moved to: ${relativePath}`);
         this.logger.info(`   Your local changes are preserved. To review:`);
         this.logger.info(`     cd ${relativePath}`);
@@ -4092,12 +4437,12 @@ var WorktreeSyncService = class {
     }
   }
   async divergeWorktree(worktreePath, branchName) {
-    const divergedBaseDir = path6.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedBaseDir = path7.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const uniqueSuffix = Date.now().toString(36) + Math.random().toString(36).substring(2, 7);
     const safeBranchName = this.pathResolution.sanitizeBranchName(branchName);
     const divergedName = `${timestamp}-${safeBranchName}-${uniqueSuffix}`;
-    const divergedPath = path6.join(divergedBaseDir, divergedName);
+    const divergedPath = path7.join(divergedBaseDir, divergedName);
     await fs6.mkdir(divergedBaseDir, { recursive: true });
     try {
       await fs6.rename(worktreePath, divergedPath);
@@ -4124,7 +4469,7 @@ var WorktreeSyncService = class {
   Original worktree location: ${worktreePath}`
     };
     await fs6.writeFile(
-      path6.join(divergedPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE),
+      path7.join(divergedPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE),
       JSON.stringify(metadata, null, 2)
     );
     return divergedPath;
@@ -4133,7 +4478,7 @@ var WorktreeSyncService = class {
 
 // src/services/file-copy.service.ts
 import * as fs7 from "fs/promises";
-import * as path7 from "path";
+import * as path8 from "path";
 import { glob } from "glob";
 var DEFAULT_IGNORE_PATTERNS = [
   "**/node_modules/**",
@@ -4160,8 +4505,8 @@ var FileCopyService = class {
     }
     const filesToCopy = await this.expandPatterns(sourceDir, patterns);
     for (const relativePath of filesToCopy) {
-      const sourcePath = path7.join(sourceDir, relativePath);
-      const destPath = path7.join(destDir, relativePath);
+      const sourcePath = path8.join(sourceDir, relativePath);
+      const destPath = path8.join(destDir, relativePath);
       try {
         const copied = await this.copyFile(sourcePath, destPath);
         if (copied) {
@@ -4202,7 +4547,7 @@ var FileCopyService = class {
       return false;
     } catch {
     }
-    const destDir = path7.dirname(destPath);
+    const destDir = path8.dirname(destPath);
     await fs7.mkdir(destDir, { recursive: true });
     await fs7.copyFile(sourcePath, destPath);
     return true;
@@ -4338,7 +4683,7 @@ var HookExecutionService = class {
 // src/utils/disk-space.ts
 import fastFolderSize from "fast-folder-size";
 async function calculateDirectorySize(dirPath) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     fastFolderSize(dirPath, (err, bytes) => {
       if (err) {
         reject(err);
@@ -4348,7 +4693,7 @@ async function calculateDirectorySize(dirPath) {
         reject(new Error(`fast-folder-size returned no bytes for ${dirPath}`));
         return;
       }
-      resolve8(bytes);
+      resolve9(bytes);
     });
   });
 }
@@ -4550,8 +4895,8 @@ var InteractiveUIService = class {
           getWorktreeStatusForRepo: (index) => this.getWorktreeStatusForRepo(index),
           getDivergedDirectoriesForRepo: (index) => this.getDivergedDirectoriesForRepo(index),
           deleteDivergedDirectory: (repoIndex, name) => this.deleteDivergedDirectory(repoIndex, name),
-          openEditorInWorktree: (path12) => this.openEditorInWorktree(path12),
-          openTerminalInWorktree: (repoIndex, path12, branchName) => this.openTerminalInWorktree(repoIndex, path12, branchName),
+          openEditorInWorktree: (path13) => this.openEditorInWorktree(path13),
+          openTerminalInWorktree: (repoIndex, path13, branchName) => this.openTerminalInWorktree(repoIndex, path13, branchName),
           copyBranchFiles: (repoIndex, baseBranch, targetBranch) => this.copyBranchFiles(repoIndex, baseBranch, targetBranch),
           createWorktreeForBranch: (repoIndex, branchName) => this.createWorktreeForBranch(repoIndex, branchName),
           executeOnBranchCreatedHooks: (repoIndex, context) => this.executeOnBranchCreatedHooks(repoIndex, context)
@@ -4655,7 +5000,7 @@ var InteractiveUIService = class {
         if (Date.now() - startTime > timeout) {
           throw new Error("Timeout waiting for sync operations to complete");
         }
-        await new Promise((resolve8) => setTimeout(resolve8, checkInterval));
+        await new Promise((resolve9) => setTimeout(resolve9, checkInterval));
       }
     });
     try {
@@ -4788,7 +5133,7 @@ var InteractiveUIService = class {
     }
     const service = this.syncServices[repoIndex];
     const worktreeDir = service.config.worktreeDir;
-    const divergedDir = path8.join(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedDir = path9.join(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
     let dirEntries;
     try {
       dirEntries = await fs8.readdir(divergedDir, { withFileTypes: true, encoding: "utf-8" });
@@ -4798,8 +5143,8 @@ var InteractiveUIService = class {
     const subdirs = dirEntries.filter((e) => e.isDirectory());
     const results = await Promise.allSettled(
       subdirs.map(async (entry) => {
-        const fullPath = path8.join(divergedDir, entry.name);
-        const infoFilePath = path8.join(fullPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE);
+        const fullPath = path9.join(divergedDir, entry.name);
+        const infoFilePath = path9.join(fullPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE);
         let originalBranch = entry.name;
         let divergedAt = "";
         try {
@@ -4834,11 +5179,11 @@ var InteractiveUIService = class {
     }
     const service = this.syncServices[repoIndex];
     const worktreeDir = service.config.worktreeDir;
-    const divergedBase = path8.resolve(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedBase = path9.resolve(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
     if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
       throw new Error(`Invalid diverged directory name: "${name}"`);
     }
-    const targetPath = path8.join(divergedBase, name);
+    const targetPath = path9.join(divergedBase, name);
     if (!this.pathResolution.isPathInsideBaseDir(targetPath, divergedBase)) {
       throw new Error(`Path traversal rejected: "${name}" resolves outside the diverged directory`);
     }
@@ -5227,7 +5572,7 @@ function reconstructCliCommand(config) {
 
 // src/utils/config-generator.ts
 import * as fs9 from "fs/promises";
-import * as path9 from "path";
+import * as path10 from "path";
 function serializeToESM(obj, indent = 0) {
   const spaces = " ".repeat(indent);
   const innerSpaces = " ".repeat(indent + 2);
@@ -5257,9 +5602,9 @@ ${spaces}}`;
   return String(obj);
 }
 async function generateConfigFile(config, configPath) {
-  const configDir = path9.dirname(configPath);
+  const configDir = path10.dirname(configPath);
   await fs9.mkdir(configDir, { recursive: true });
-  const worktreeDirRelative = path9.relative(configDir, config.worktreeDir);
+  const worktreeDirRelative = path10.relative(configDir, config.worktreeDir);
   const useRelativeWorktree = !worktreeDirRelative.startsWith("../../../");
   const repoName = extractRepoNameFromUrl(config.repoUrl);
   const repository = {
@@ -5268,7 +5613,7 @@ async function generateConfigFile(config, configPath) {
     worktreeDir: useRelativeWorktree ? `./${worktreeDirRelative}` : config.worktreeDir
   };
   if (config.bareRepoDir) {
-    const bareRepoDirRelative = path9.relative(configDir, config.bareRepoDir);
+    const bareRepoDirRelative = path10.relative(configDir, config.bareRepoDir);
     const useRelativeBare = !bareRepoDirRelative.startsWith("../../../");
     repository.bareRepoDir = useRelativeBare ? `./${bareRepoDirRelative}` : config.bareRepoDir;
   }
@@ -5289,11 +5634,11 @@ export default ${serializeToESM(configObject)};
   await fs9.writeFile(configPath, configContent, "utf-8");
 }
 function getDefaultConfigPath() {
-  return path9.join(process.cwd(), "sync-worktrees.config.js");
+  return path10.join(process.cwd(), "sync-worktrees.config.js");
 }
 async function findConfigInCwd(cwd = process.cwd()) {
   for (const name of CONFIG_FILE_NAMES) {
-    const full = path9.join(cwd, name);
+    const full = path10.join(cwd, name);
     try {
       await fs9.access(full);
       return full;
@@ -5304,7 +5649,7 @@ async function findConfigInCwd(cwd = process.cwd()) {
 }
 
 // src/utils/interactive.ts
-import * as path10 from "path";
+import * as path11 from "path";
 import { confirm, input, select } from "@inquirer/prompts";
 async function promptForConfig(partialConfig) {
   console.log("\u{1F527} Welcome to sync-worktrees interactive setup!\n");
@@ -5344,8 +5689,8 @@ async function promptForConfig(partialConfig) {
     if (!worktreeDir.trim() && defaultWorktreeDir) {
       worktreeDir = defaultWorktreeDir;
     }
-    if (!path10.isAbsolute(worktreeDir)) {
-      worktreeDir = path10.resolve(worktreeDir);
+    if (!path11.isAbsolute(worktreeDir)) {
+      worktreeDir = path11.resolve(worktreeDir);
     }
   }
   let bareRepoDir = partialConfig.bareRepoDir;
@@ -5364,8 +5709,8 @@ async function promptForConfig(partialConfig) {
         return true;
       }
     });
-    if (!path10.isAbsolute(bareRepoDir)) {
-      bareRepoDir = path10.resolve(bareRepoDir);
+    if (!path11.isAbsolute(bareRepoDir)) {
+      bareRepoDir = path11.resolve(bareRepoDir);
     }
   }
   let runOnce = partialConfig.runOnce;
@@ -5437,8 +5782,8 @@ async function promptForConfig(partialConfig) {
         return true;
       }
     });
-    if (!path10.isAbsolute(configPath)) {
-      configPath = path10.resolve(configPath);
+    if (!path11.isAbsolute(configPath)) {
+      configPath = path11.resolve(configPath);
     }
     try {
       await generateConfigFile(finalConfig, configPath);
@@ -5674,7 +6019,7 @@ async function main() {
     const discovered = await findConfigInCwd();
     if (discovered) {
       options.config = discovered;
-      console.log(`\u{1F4C4} Using config: ${path11.relative(process.cwd(), discovered)}`);
+      console.log(`\u{1F4C4} Using config: ${path12.relative(process.cwd(), discovered)}`);
     }
   }
   if (options.config) {