sync-worktrees 3.1.0 → 3.3.0

package/dist/mcp-server.js

@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/mcp/context.ts
 import * as fs7 from "fs/promises";
 import * as path8 from "path";
-import simpleGit4 from "simple-git";
+import simpleGit5 from "simple-git";
 
 // src/constants.ts
 var GIT_CONSTANTS = {
@@ -79,6 +79,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 = {
@@ -103,7 +104,7 @@ var METADATA_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";
 
@@ -127,14 +128,124 @@ 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;
+}
+function pathsEqual(a, b, platform = process.platform) {
+  return normalizePathForCompare(a, platform) === normalizePathForCompare(b, platform);
+}
+
+// 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(path10, reasons) {
+    super(`Worktree at '${path10}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
+    this.path = path10;
+    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;
@@ -142,13 +253,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 {
@@ -224,7 +335,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");
@@ -248,6 +363,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") {
@@ -337,6 +455,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`);
@@ -356,7 +528,7 @@ var ConfigLoaderService = class {
       }
     }
   }
-  resolveRepositoryConfig(repo, defaults, configDir, globalRetry) {
+  resolveRepositoryConfig(repo, defaults, configDir, globalRetry, allRepositories) {
     const resolved = {
       name: repo.name,
       repoUrl: repo.repoUrl,
@@ -366,6 +538,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;
@@ -405,8 +582,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;
@@ -415,10 +616,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) {
@@ -431,10 +632,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);
     }
@@ -800,34 +1002,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/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) {
@@ -870,10 +1046,101 @@ function parseWorktreeListPorcelain(output) {
   return worktrees;
 }
 
+// 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) {
@@ -885,7 +1152,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("\\")) {
@@ -893,7 +1160,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,
@@ -906,7 +1173,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 {
@@ -997,7 +1264,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;
@@ -1099,47 +1366,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";
-
-// 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(path10, reasons) {
-    super(`Worktree at '${path10}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
-    this.path = path10;
-    this.reasons = reasons;
-  }
-};
-
-// src/services/worktree-status.service.ts
+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" },
@@ -1341,7 +1569,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
         )
@@ -1462,14 +1690,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 stat4 = await fs3.stat(gitPath);
       if (stat4.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}`);
       }
@@ -1483,10 +1711,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;
@@ -1499,9 +1727,10 @@ var GitService = class {
     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;
@@ -1510,29 +1739,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.");
     }
@@ -1549,34 +1783,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);
@@ -1590,7 +1829,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) {
@@ -1659,13 +1898,29 @@ var GitService = class {
     return branches;
   }
   async verifyLfsFilesDownloaded(worktreePath, branchName) {
-    const worktreeGit = this.getCachedGit(worktreePath);
+    const worktreeGit = this.config.sparseCheckout ? simpleGit4(worktreePath).env({ ...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...`);
       }
@@ -1682,7 +1937,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 {
@@ -1719,6 +1974,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());
@@ -1739,12 +2026,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;
@@ -1754,25 +2041,21 @@ var GitService = class {
       }
     } catch {
     }
+    let createdNewBranch = false;
     try {
-      const branches = await bareGit.branch();
-      const localBranchExists = branches.all.includes(branchName);
-      if (localBranchExists || branchName.includes("/")) {
-        await bareGit.raw(["worktree", "add", absoluteWorktreePath, branchName]);
-        const worktreeGit = this.getCachedGit(absoluteWorktreePath, this.isLfsSkipEnabled());
-        await worktreeGit.branch(["--set-upstream-to", `origin/${branchName}`, branchName]);
+      const { local: localBranchExists, remote: remoteBranchExists } = await this.branchExists(branchName);
+      createdNewBranch = await this.runWorktreeAddByMatrix(
+        bareGit,
+        branchName,
+        absoluteWorktreePath,
+        localBranchExists,
+        remoteBranchExists
+      );
+      if (localBranchExists && !remoteBranchExists) {
+        this.logger.info(`  - Created worktree for '${branchName}' (no remote yet \u2014 push to set upstream)`);
       } else {
-        await bareGit.raw([
-          "worktree",
-          "add",
-          "--track",
-          "-b",
-          branchName,
-          absoluteWorktreePath,
-          `origin/${branchName}`
-        ]);
+        this.logger.info(`  - Created worktree for '${branchName}' with tracking to origin/${branchName}`);
       }
-      this.logger.info(`  - Created worktree for '${branchName}' with tracking to origin/${branchName}`);
       if (!this.isLfsSkipEnabled()) {
         await this.verifyLfsFilesDownloaded(absoluteWorktreePath, branchName);
       }
@@ -1780,20 +2063,20 @@ 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) {
       const errorMessage = getErrorMessage(error);
+      if (error?.isUpstreamSetupFailure) {
+        throw error;
+      }
       if (errorMessage.includes("Metadata creation failed")) {
         throw error;
       }
       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;
@@ -1804,16 +2087,16 @@ var GitService = class {
           await fs4.rm(absoluteWorktreePath, { recursive: true, force: true });
         } catch {
         }
+        let retryCreatedNewBranch = false;
         try {
-          await bareGit.raw([
-            "worktree",
-            "add",
-            "--track",
-            "-b",
+          const { local: localBranchExists, remote: remoteBranchExists } = await this.branchExists(branchName);
+          retryCreatedNewBranch = await this.runWorktreeAddByMatrix(
+            bareGit,
             branchName,
             absoluteWorktreePath,
-            `origin/${branchName}`
-          ]);
+            localBranchExists,
+            remoteBranchExists
+          );
           this.logger.info(`  - Created worktree for '${branchName}' after pruning`);
           if (!this.isLfsSkipEnabled()) {
             await this.verifyLfsFilesDownloaded(absoluteWorktreePath, branchName);
@@ -1822,10 +2105,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;
@@ -1842,7 +2122,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;
@@ -1853,7 +2133,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);
@@ -1862,17 +2145,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;
@@ -1882,6 +2162,65 @@ 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", ...noCheckoutFlag, absoluteWorktreePath, branchName]);
+      try {
+        const worktreeGit = this.getCachedGit(absoluteWorktreePath, this.isLfsSkipEnabled());
+        await worktreeGit.branch(["--set-upstream-to", `origin/${branchName}`, branchName]);
+      } catch (error) {
+        throw await this.wrapUpstreamFailure(bareGit, absoluteWorktreePath, branchName, false, error);
+      }
+      await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, false);
+      return false;
+    }
+    if (localExists) {
+      await bareGit.raw(["worktree", "add", ...noCheckoutFlag, absoluteWorktreePath, branchName]);
+      await this.runSparseStepWithRollback(bareGit, absoluteWorktreePath, branchName, false);
+      return false;
+    }
+    if (remoteExists) {
+      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"]);
@@ -2075,10 +2414,18 @@ var GitService = class {
   }
   async branchExists(branchName) {
     const bareGit = this.getCachedGit(this.bareRepoPath);
-    const localBranches = await bareGit.branch();
-    const local = localBranches.all.includes(branchName);
-    const remoteBranches = await bareGit.branch(["-r"]);
-    const remote = remoteBranches.all.includes(`origin/${branchName}`);
+    const checkRef = async (ref) => {
+      try {
+        await bareGit.raw(["show-ref", "--verify", "--quiet", ref]);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const [local, remote] = await Promise.all([
+      checkRef(`${GIT_CONSTANTS.REFS.HEADS}${branchName}`),
+      checkRef(`${GIT_CONSTANTS.REFS.REMOTES}/${branchName}`)
+    ]);
     return { local, remote };
   }
   async getLocalBranches() {
@@ -2113,22 +2460,6 @@ var GitService = class {
 import { createHash } from "crypto";
 import * as fs5 from "fs";
 import * as path6 from "path";
-
-// src/utils/path-compare.ts
-import * as path5 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 = path5.resolve(p);
-  return isCaseInsensitiveFs(platform) ? resolved.toLowerCase() : resolved;
-}
-function pathsEqual(a, b, platform = process.platform) {
-  return normalizePathForCompare(a, platform) === normalizePathForCompare(b, platform);
-}
-
-// src/services/path-resolution.service.ts
 var BRANCH_STEM_MAX = 80;
 var BRANCH_HASH_LEN = 8;
 var PathResolutionService = class {
@@ -2297,8 +2628,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");
@@ -2875,16 +3248,27 @@ var RepositoryContext = class {
     const setDefaultCurrent = options.setDefaultCurrent ?? true;
     const absolutePath = path8.resolve(configPath);
     const configFile = await this.configLoader.loadConfigFile(absolutePath);
+    const configDir = path8.dirname(absolutePath);
+    const globalDefaults = configFile.defaults;
+    const resolvedAll = [];
+    for (const repo of configFile.repositories) {
+      const resolved = this.configLoader.resolveRepositoryConfig(
+        repo,
+        globalDefaults,
+        configDir,
+        configFile.retry,
+        configFile.repositories
+      );
+      resolvedAll.push(resolved);
+    }
+    this.configLoader.detectBareRepoDirCollisions(resolvedAll);
     for (const [name, entry] of this.repos) {
       if (entry.source === "config") {
         this.repos.delete(name);
       }
     }
     this.configPath = absolutePath;
-    const configDir = path8.dirname(absolutePath);
-    const globalDefaults = configFile.defaults;
-    for (const repo of configFile.repositories) {
-      const resolved = this.configLoader.resolveRepositoryConfig(repo, globalDefaults, configDir, configFile.retry);
+    for (const resolved of resolvedAll) {
       this.repos.set(resolved.name, {
         name: resolved.name,
         config: resolved,
@@ -3054,7 +3438,7 @@ var RepositoryContext = class {
     let worktrees = [];
     let currentBranch = null;
     try {
-      const bareGit = simpleGit4(bareRepoPath);
+      const bareGit = simpleGit5(bareRepoPath);
       try {
         const remoteResult = await bareGit.remote(["get-url", "origin"]);
         const urlStr = typeof remoteResult === "string" ? remoteResult.trim() : "";
@@ -3396,7 +3780,7 @@ function wrapHandler(fn) {
 }
 
 // src/mcp/worktree-summary.ts
-import simpleGit5 from "simple-git";
+import simpleGit6 from "simple-git";
 function deriveLabel(status, isCurrent) {
   if (isCurrent) return "current";
   if (!status.isClean || status.hasUnpushedCommits || status.hasStashedChanges) return "dirty";
@@ -3417,7 +3801,7 @@ function deriveSafeToRemove(status) {
 }
 async function getDivergence(worktreePath) {
   try {
-    const git = simpleGit5(worktreePath);
+    const git = simpleGit6(worktreePath);
     const output = await git.raw(["rev-list", "--left-right", "--count", "HEAD...@{upstream}"]);
     const [aheadStr, behindStr] = output.trim().split(/\s+/);
     return { ahead: parseInt(aheadStr, 10), behind: parseInt(behindStr, 10) };
@@ -3730,14 +4114,26 @@ function attachProgressReporter(service, extra) {
 var REPO_NAME_DESCRIBE = "Repository name from loaded config. If omitted, uses the current repository set via set_current_repository or the only loaded repo.";
 var PATH_DESCRIBE_SUFFIX = "Absolute path preferred; relative paths resolve from the server's CWD.";
 var SERVER_INSTRUCTIONS = "Before running git worktree operations, call `detect_context` to learn the current repo, current branch, sibling repositories under the workspace root, and which capabilities are available. It walks up to auto-discover sync-worktrees.config.{js,mjs,cjs,ts}, lists sibling worktrees, and reports per-capability {available, reason} so you can tell which tool is gated and why.";
-function createServer(context) {
+function buildInstructions(snapshot) {
+  const d = snapshot?.discovered;
+  if (!d || !d.isWorktree || d.kind !== "managed") return SERVER_INSTRUCTIONS;
+  const lines = ["Connect-time context (call `detect_context` for live state):"];
+  if (d.kind) lines.push(`- kind: ${d.kind}`);
+  if (d.currentWorktreePath) lines.push(`- currentWorktreePath: ${d.currentWorktreePath}`);
+  if (d.currentBranch) lines.push(`- currentBranch: ${d.currentBranch}`);
+  if (d.configPath) lines.push(`- configPath: ${d.configPath}`);
+  return `${SERVER_INSTRUCTIONS}
+
+${lines.join("\n")}`;
+}
+function createServer(context, snapshot) {
   const server = new McpServer(
     {
       name: "sync-worktrees",
       version: "1.0.0"
     },
     {
-      instructions: SERVER_INSTRUCTIONS
+      instructions: buildInstructions(snapshot)
     }
   );
   server.registerResource(
@@ -3970,8 +4366,9 @@ async function main() {
 `);
     }
   }
+  let discovered = null;
   try {
-    const discovered = await context.detectFromPath(process.cwd());
+    discovered = await context.detectFromPath(process.cwd());
     if (discovered.isWorktree) {
       process.stderr.write(
         `[sync-worktrees-mcp] Auto-detected ${discovered.kind} worktree at ${discovered.currentWorktreePath} (branch: ${discovered.currentBranch})
@@ -3982,7 +4379,7 @@ async function main() {
     process.stderr.write(`[sync-worktrees-mcp] Auto-detect failed: ${err.message}
 `);
   }
-  const server = createServer(context);
+  const server = createServer(context, { discovered });
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }