sync-worktrees 3.3.1 → 3.5.0

package/dist/mcp-server.js

@@ -5,7 +5,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 * as path9 from "path";
 import simpleGit5 from "simple-git";
 
 // src/constants.ts
@@ -57,7 +57,11 @@ var DEFAULT_CONFIG = {
     MAX_SAFE_TOTAL_CONCURRENT_OPS: 100
   },
   UPDATE_EXISTING_WORKTREES: true,
-  HOOK_TIMEOUT_MS: 6e4
+  HOOK_TIMEOUT_MS: 6e4,
+  FETCH_TIMEOUT_MS: 3e5,
+  CLONE_TIMEOUT_MS: 9e5,
+  LOCK_STALE_MS: 6e5,
+  LOCK_UPDATE_MS: 3e4
 };
 var ERROR_MESSAGES = {
   GIT_NOT_INITIALIZED: "Git service not initialized. Call initialize() first.",
@@ -198,9 +202,9 @@ var WorktreeError = class extends SyncWorktreesError {
   }
 };
 var WorktreeNotCleanError = class extends WorktreeError {
-  constructor(path10, reasons) {
-    super(`Worktree at '${path10}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
-    this.path = path10;
+  constructor(path11, reasons) {
+    super(`Worktree at '${path11}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
+    this.path = path11;
     this.reasons = reasons;
   }
 };
@@ -751,8 +755,9 @@ function defaultConsoleOutput(msg, level) {
 
 // src/services/worktree-sync.service.ts
 import * as fs6 from "fs/promises";
-import * as path7 from "path";
+import * as path8 from "path";
 import pLimit from "p-limit";
+import * as lockfile from "proper-lockfile";
 
 // src/utils/date-filter.ts
 function parseDuration(durationStr) {
@@ -1002,7 +1007,7 @@ function formatTimingTable(totalDuration, phaseResults, repoName) {
 
 // src/services/git.service.ts
 import * as fs4 from "fs/promises";
-import * as path5 from "path";
+import * as path6 from "path";
 import simpleGit4 from "simple-git";
 
 // src/utils/worktree-list-parser.ts
@@ -1047,11 +1052,13 @@ function parseWorktreeListPorcelain(output) {
 }
 
 // src/services/sparse-checkout.service.ts
+import * as path3 from "path";
 import simpleGit from "simple-git";
 var SparseCheckoutService = class {
   logger;
   gitFactory;
   warnedConfigs = /* @__PURE__ */ new WeakSet();
+  matcherCache = /* @__PURE__ */ new WeakMap();
   constructor(logger, gitFactory) {
     this.logger = logger ?? Logger.createDefault();
     this.gitFactory = gitFactory ?? ((p) => simpleGit(p));
@@ -1135,11 +1142,66 @@ var SparseCheckoutService = class {
     const bt = b.map((x) => x.trim());
     return at.every((v, i) => v === bt[i]);
   }
+  /**
+   * Decide whether a list of changed file paths intersects the sparse-checkout
+   * set defined by `cfg`. Used to skip fast-forward updates when upstream
+   * commits only touch files outside the materialized worktree.
+   *
+   * Cone mode materializes:
+   *   - all files at the repository root,
+   *   - all files directly inside every ancestor of an included directory
+   *     (e.g. include `tools/build` keeps `tools/foo.txt` checked out too),
+   *   - everything inside an included directory.
+   * We mirror those rules here. Missing the ancestor-files case would let
+   * stale files linger when only those parent files change upstream.
+   *
+   * No-cone mode: gitignore-style matching with negation is non-trivial and
+   * not implemented here yet. We return `true` so the caller falls back to
+   * the safe behavior of always running the update.
+   *
+   * The matcher derived from `cfg` is cached on the cfg object identity
+   * (WeakMap), so callers should reuse the same `cfg` reference across
+   * invocations to benefit from the cache.
+   */
+  pathsTouchSparse(changedPaths, cfg) {
+    if (changedPaths.length === 0) return false;
+    const matcher = this.getMatcher(cfg);
+    if (matcher.mode === "no-cone") return true;
+    if (matcher.patterns.length === 0) return true;
+    return changedPaths.some((p) => {
+      if (!p.includes("/")) return true;
+      for (const pat of matcher.patterns) {
+        if (p === pat || p.startsWith(pat + "/")) return true;
+      }
+      return matcher.ancestorDirs.has(path3.posix.dirname(p));
+    });
+  }
+  getMatcher(cfg) {
+    const cached = this.matcherCache.get(cfg);
+    if (cached) return cached;
+    const mode = this.resolveMode(cfg);
+    if (mode === "no-cone") {
+      const matcher2 = { mode, patterns: [], ancestorDirs: /* @__PURE__ */ new Set() };
+      this.matcherCache.set(cfg, matcher2);
+      return matcher2;
+    }
+    const patterns = cfg.include.map((p) => p.trim()).filter((p) => p.length > 0).map((p) => p.endsWith("/") ? p.slice(0, -1) : p);
+    const ancestorDirs = /* @__PURE__ */ new Set();
+    for (const pat of patterns) {
+      const parts = pat.split("/");
+      for (let i = 1; i < parts.length; i++) {
+        ancestorDirs.add(parts.slice(0, i).join("/"));
+      }
+    }
+    const matcher = { mode, patterns, ancestorDirs };
+    this.matcherCache.set(cfg, matcher);
+    return matcher;
+  }
 };
 
 // src/services/worktree-metadata.service.ts
 import * as fs2 from "fs/promises";
-import * as path3 from "path";
+import * as path4 from "path";
 import simpleGit2 from "simple-git";
 var WorktreeMetadataService = class {
   logger;
@@ -1152,7 +1214,7 @@ var WorktreeMetadataService = class {
    * For example: /worktrees/fix/test-branch -> test-branch (not fix/test-branch)
    */
   getWorktreeDirectoryName(worktreePath) {
-    return path3.basename(worktreePath);
+    return path4.basename(worktreePath);
   }
   async getMetadataPath(bareRepoPath, worktreeName) {
     if (worktreeName.includes("/") || worktreeName.includes("\\")) {
@@ -1160,7 +1222,7 @@ var WorktreeMetadataService = class {
         `getMetadataPath requires a filesystem-safe worktree directory name, got '${worktreeName}'. Use getMetadataPathFromWorktreePath when starting from a raw branch name.`
       );
     }
-    return path3.join(
+    return path4.join(
       bareRepoPath,
       METADATA_CONSTANTS.WORKTREE_METADATA_PATH,
       worktreeName,
@@ -1173,7 +1235,7 @@ var WorktreeMetadataService = class {
   }
   async saveMetadata(bareRepoPath, worktreeName, metadata) {
     const metadataPath = await this.getMetadataPath(bareRepoPath, worktreeName);
-    await fs2.mkdir(path3.dirname(metadataPath), { recursive: true });
+    await fs2.mkdir(path4.dirname(metadataPath), { recursive: true });
     const tmpPath = `${metadataPath}.${process.pid}.${Date.now()}.tmp`;
     let renamed = false;
     try {
@@ -1366,7 +1428,7 @@ var WorktreeMetadataService = class {
 
 // src/services/worktree-status.service.ts
 import * as fs3 from "fs/promises";
-import * as path4 from "path";
+import * as path5 from "path";
 import simpleGit3 from "simple-git";
 var OPERATION_FILES = [
   { file: GIT_OPERATIONS.MERGE_HEAD, type: "merge" },
@@ -1569,7 +1631,7 @@ var WorktreeStatusService = class {
   async detectOperationFile(gitDir) {
     const results = await Promise.all(
       OPERATION_FILES.map(
-        ({ file }) => fs3.access(path4.join(gitDir, file)).then(
+        ({ file }) => fs3.access(path5.join(gitDir, file)).then(
           () => true,
           () => false
         )
@@ -1690,14 +1752,14 @@ var WorktreeStatusService = class {
     }
   }
   async resolveGitDir(worktreePath) {
-    const gitPath = path4.join(worktreePath, PATH_CONSTANTS.GIT_DIR);
+    const gitPath = path5.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 path4.resolve(worktreePath, gitdirMatch[1].trim());
+          return path5.resolve(worktreePath, gitdirMatch[1].trim());
         }
         throw new GitOperationError("resolve-git-dir", `Failed to parse gitdir from .git file at ${gitPath}`);
       }
@@ -1711,7 +1773,7 @@ var WorktreeStatusService = class {
     }
   }
   createGitInstance(worktreePath) {
-    const key = `${path4.resolve(worktreePath)}::${this.config.skipLfs ? "1" : "0"}`;
+    const key = `${path5.resolve(worktreePath)}::${this.config.skipLfs ? "1" : "0"}`;
     let git = this.gitInstances.get(key);
     if (!git) {
       git = this.config.skipLfs ? simpleGit3(worktreePath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit3(worktreePath);
@@ -1734,7 +1796,7 @@ 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 = path5.join(this.config.worktreeDir, GIT_CONSTANTS.DEFAULT_BRANCH);
+    this.mainWorktreePath = path6.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);
@@ -1753,11 +1815,21 @@ var GitService = class {
   getSparseCheckoutService() {
     return this.sparseCheckoutService;
   }
+  getFetchTimeoutMs() {
+    if (process.env.NODE_ENV === ENV_CONSTANTS.NODE_ENV_TEST) return 0;
+    return this.config.fetchTimeoutMs ?? DEFAULT_CONFIG.FETCH_TIMEOUT_MS;
+  }
+  getCloneTimeoutMs() {
+    if (process.env.NODE_ENV === ENV_CONSTANTS.NODE_ENV_TEST) return 0;
+    return this.config.cloneTimeoutMs ?? DEFAULT_CONFIG.CLONE_TIMEOUT_MS;
+  }
   getCachedGit(dirPath, useLfsSkip = false) {
-    const key = `${path5.resolve(dirPath)}::${useLfsSkip ? "1" : "0"}`;
+    const key = `${path6.resolve(dirPath)}::${useLfsSkip ? "1" : "0"}`;
     let git = this.gitInstances.get(key);
     if (!git) {
-      git = useLfsSkip ? simpleGit4(dirPath).env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit4(dirPath);
+      const block = this.getFetchTimeoutMs();
+      const base = block > 0 ? simpleGit4(dirPath, { timeout: { block } }) : simpleGit4(dirPath);
+      git = useLfsSkip ? base.env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : base;
       this.gitInstances.set(key, git);
     }
     return git;
@@ -1769,11 +1841,13 @@ var GitService = class {
   async initialize() {
     const { repoUrl } = this.config;
     try {
-      await fs4.access(path5.join(this.bareRepoPath, "HEAD"));
+      await fs4.access(path6.join(this.bareRepoPath, "HEAD"));
     } catch {
       this.logger.info(`Cloning from "${repoUrl}" as bare repository into "${this.bareRepoPath}"...`);
-      await fs4.mkdir(path5.dirname(this.bareRepoPath), { recursive: true });
-      const cloneGit = this.isLfsSkipEnabled() ? simpleGit4().env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : simpleGit4();
+      await fs4.mkdir(path6.dirname(this.bareRepoPath), { recursive: true });
+      const cloneBlock = this.getCloneTimeoutMs();
+      const cloneBase = cloneBlock > 0 ? simpleGit4({ timeout: { block: cloneBlock } }) : simpleGit4();
+      const cloneGit = this.isLfsSkipEnabled() ? cloneBase.env({ [ENV_CONSTANTS.GIT_LFS_SKIP_SMUDGE]: "1" }) : cloneBase;
       await cloneGit.clone(repoUrl, this.bareRepoPath, ["--bare"]);
       this.logger.info("\u2705 Clone successful.");
     }
@@ -1790,17 +1864,17 @@ var GitService = class {
     this.logger.info("Fetching remote branches...");
     await bareGit.fetch(["--all"]);
     this.defaultBranch = await this.detectDefaultBranch(bareGit);
-    this.mainWorktreePath = path5.join(this.config.worktreeDir, this.defaultBranch);
+    this.mainWorktreePath = path6.join(this.config.worktreeDir, this.defaultBranch);
     let needsMainWorktree = true;
     try {
       const worktrees = await this.getWorktreesFromBare(bareGit);
-      needsMainWorktree = !worktrees.some((w) => path5.resolve(w.path) === path5.resolve(this.mainWorktreePath));
+      needsMainWorktree = !worktrees.some((w) => path6.resolve(w.path) === path6.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 = path5.resolve(this.mainWorktreePath);
+      const absoluteWorktreePath = path6.resolve(this.mainWorktreePath);
       const branches = await bareGit.branch();
       const defaultBranchExists = branches.all.includes(this.defaultBranch);
       const useNoCheckoutMain = !!this.config.sparseCheckout;
@@ -1836,7 +1910,7 @@ var GitService = class {
       }
       const updatedWorktrees = await this.getWorktreesFromBare(bareGit);
       const mainWorktreeRegistered = updatedWorktrees.some(
-        (w) => path5.resolve(w.path) === path5.resolve(this.mainWorktreePath)
+        (w) => path6.resolve(w.path) === path6.resolve(this.mainWorktreePath)
       );
       if (!mainWorktreeRegistered) {
         if (process.env.NODE_ENV !== ENV_CONSTANTS.NODE_ENV_TEST) {
@@ -1859,6 +1933,9 @@ var GitService = class {
   getDefaultBranch() {
     return this.defaultBranch;
   }
+  getBareRepoPath() {
+    return this.bareRepoPath;
+  }
   async fetchAll() {
     this.assertInitialized();
     this.logger.info("Fetching latest data from remote...");
@@ -1916,7 +1993,7 @@ var GitService = class {
         const existence = await Promise.all(
           lfsFileList.map(async (f) => {
             try {
-              await fs4.access(path5.join(worktreePath, f));
+              await fs4.access(path6.join(worktreePath, f));
               return f;
             } catch {
               return null;
@@ -1944,7 +2021,7 @@ var GitService = class {
         let allDownloaded = true;
         const notDownloaded = [];
         for (const file of samplesToCheck) {
-          const filePath = path5.join(worktreePath, file);
+          const filePath = path6.join(worktreePath, file);
           try {
             const handle = await fs4.open(filePath, "r");
             try {
@@ -2033,12 +2110,12 @@ var GitService = class {
   }
   async addWorktree(branchName, worktreePath) {
     const bareGit = this.getCachedGit(this.bareRepoPath, this.isLfsSkipEnabled());
-    const absoluteWorktreePath = path5.resolve(worktreePath);
-    await fs4.mkdir(path5.dirname(absoluteWorktreePath), { recursive: true });
+    const absoluteWorktreePath = path6.resolve(worktreePath);
+    await fs4.mkdir(path6.dirname(absoluteWorktreePath), { recursive: true });
     try {
       await fs4.access(absoluteWorktreePath);
       const worktrees = await this.getWorktreesFromBare(bareGit);
-      const isValidWorktree = worktrees.some((w) => path5.resolve(w.path) === absoluteWorktreePath);
+      const isValidWorktree = worktrees.some((w) => path6.resolve(w.path) === absoluteWorktreePath);
       if (isValidWorktree) {
         this.logger.info(`  - Worktree for '${branchName}' already exists at '${absoluteWorktreePath}'`);
         return;
@@ -2083,7 +2160,7 @@ var GitService = class {
       }
       if (errorMessage.includes("already registered worktree")) {
         const worktrees = await this.getWorktreesFromBare(bareGit);
-        const existingWorktree = worktrees.find((w) => path5.resolve(w.path) === absoluteWorktreePath);
+        const existingWorktree = worktrees.find((w) => path6.resolve(w.path) === absoluteWorktreePath);
         if (existingWorktree && !existingWorktree.isPrunable) {
           this.logger.info(`  - Worktree for '${branchName}' was created by concurrent operation`);
           return;
@@ -2129,7 +2206,7 @@ var GitService = class {
       try {
         await fs4.access(absoluteWorktreePath);
         const worktrees = await this.getWorktreesFromBare(bareGit);
-        const isValidWorktree = worktrees.some((w) => path5.resolve(w.path) === absoluteWorktreePath);
+        const isValidWorktree = worktrees.some((w) => path6.resolve(w.path) === absoluteWorktreePath);
         if (isValidWorktree) {
           this.logger.info(`  - Worktree for '${branchName}' already exists at '${absoluteWorktreePath}'`);
           return;
@@ -2159,7 +2236,7 @@ var GitService = class {
         const fallbackErrorMessage = getErrorMessage(fallbackError);
         if (fallbackErrorMessage.includes("already registered worktree")) {
           const worktrees = await this.getWorktreesFromBare(bareGit);
-          const existingWorktree = worktrees.find((w) => path5.resolve(w.path) === absoluteWorktreePath);
+          const existingWorktree = worktrees.find((w) => path6.resolve(w.path) === absoluteWorktreePath);
           if (existingWorktree && !existingWorktree.isPrunable) {
             this.logger.info(`  - Worktree for '${branchName}' was created by concurrent operation during fallback`);
             return;
@@ -2382,6 +2459,23 @@ var GitService = class {
       return false;
     }
   }
+  async getChangedPathsInRange(worktreePath, fromRef, toRef) {
+    const worktreeGit = this.getCachedGit(worktreePath);
+    try {
+      const out = await worktreeGit.raw([
+        "-c",
+        "core.quotePath=false",
+        "diff",
+        "--name-only",
+        "--no-renames",
+        `${fromRef}..${toRef}`
+      ]);
+      return out.split("\n").map((l) => l.replace(/\r$/, "")).filter((l) => l.length > 0);
+    } catch (error) {
+      this.logger.warn(`Failed to compute diff ${fromRef}..${toRef} in ${worktreePath}: ${getErrorMessage(error)}`);
+      return null;
+    }
+  }
   async compareTreeContent(worktreePath, branch) {
     const worktreeGit = this.getCachedGit(worktreePath);
     try {
@@ -2466,7 +2560,7 @@ var GitService = class {
 // src/services/path-resolution.service.ts
 import { createHash } from "crypto";
 import * as fs5 from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 var BRANCH_STEM_MAX = 80;
 var BRANCH_HASH_LEN = 8;
 var PathResolutionService = class {
@@ -2476,22 +2570,22 @@ var PathResolutionService = class {
     return `${stem}-${hash}`;
   }
   getBranchWorktreePath(worktreeDir, branchName) {
-    return path6.join(worktreeDir, this.sanitizeBranchName(branchName));
+    return path7.join(worktreeDir, this.sanitizeBranchName(branchName));
   }
   resolveRealPath(inputPath) {
-    const absolute = path6.resolve(inputPath);
+    const absolute = path7.resolve(inputPath);
     const missing = [];
     let current = absolute;
     while (!fs5.existsSync(current)) {
-      const parent = path6.dirname(current);
+      const parent = path7.dirname(current);
       if (parent === current) {
         return absolute;
       }
-      missing.unshift(path6.basename(current));
+      missing.unshift(path7.basename(current));
       current = parent;
     }
     try {
-      return path6.join(fs5.realpathSync(current), ...missing);
+      return path7.join(fs5.realpathSync(current), ...missing);
     } catch {
       return absolute;
     }
@@ -2501,7 +2595,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) === path6.sep && a.startsWith(b);
+    return a.length > b.length && a.charAt(b.length) === path7.sep && a.startsWith(b);
   }
   normalizeWorktreePath(worktreePath, worktreeBaseDir) {
     const resolved = this.resolveRealPath(worktreePath);
@@ -2509,7 +2603,7 @@ var PathResolutionService = class {
     if (!this.isResolvedPathInsideBase(resolved, resolvedBase)) {
       throw new Error(`Worktree path '${worktreePath}' is outside base directory '${worktreeBaseDir}'`);
     }
-    return path6.relative(resolvedBase, resolved);
+    return path7.relative(resolvedBase, resolved);
   }
   isPathInsideBaseDir(targetPath, baseDir) {
     const resolved = this.resolveRealPath(targetPath);
@@ -2568,6 +2662,11 @@ var WorktreeSyncService = class {
       this.logger.warn("\u26A0\uFE0F  Sync already in progress, skipping...");
       return { started: false, reason: "in_progress" };
     }
+    const release = await this.acquireBareLock();
+    if (release === null) {
+      this.logger.warn("\u26A0\uFE0F  Another process holds the sync lock for this repo, skipping...");
+      return { started: false, reason: "locked" };
+    }
     this.syncInProgress = true;
     this.logger.info(`[${(/* @__PURE__ */ new Date()).toISOString()}] Starting worktree synchronization...`);
     const totalTimer = new Timer();
@@ -2584,6 +2683,11 @@ var WorktreeSyncService = class {
         this.gitService.setLfsSkipEnabled(false);
       }
       this.syncInProgress = false;
+      try {
+        await release();
+      } catch (releaseError) {
+        this.logger.warn(`Failed to release sync lock: ${getErrorMessage(releaseError)}`);
+      }
       this.logger.info(`[${(/* @__PURE__ */ new Date()).toISOString()}] Synchronization finished.
 `);
       if (this.config.debug) {
@@ -2595,6 +2699,39 @@ var WorktreeSyncService = class {
     }
     return { started: true };
   }
+  async acquireBareLock() {
+    if (process.env.NODE_ENV === ENV_CONSTANTS.NODE_ENV_TEST) {
+      return async () => {
+      };
+    }
+    if (typeof this.gitService.getBareRepoPath !== "function") {
+      return async () => {
+      };
+    }
+    const barePath = this.gitService.getBareRepoPath();
+    const lockTarget = path8.join(barePath, "HEAD");
+    try {
+      await fs6.access(lockTarget);
+    } catch {
+      return async () => {
+      };
+    }
+    try {
+      const release = await lockfile.lock(lockTarget, {
+        stale: DEFAULT_CONFIG.LOCK_STALE_MS,
+        update: DEFAULT_CONFIG.LOCK_UPDATE_MS,
+        retries: 0,
+        realpath: false
+      });
+      return release;
+    } catch (error) {
+      const code = error.code;
+      if (code === "ELOCKED") {
+        return null;
+      }
+      throw error;
+    }
+  }
   createRetryOptions(syncContext) {
     return {
       maxAttempts: this.config.retry?.maxAttempts ?? 3,
@@ -2770,12 +2907,12 @@ var WorktreeSyncService = class {
     }
     const reservedPaths = /* @__PURE__ */ new Map();
     for (const w of worktrees) {
-      reservedPaths.set(path7.resolve(w.path), w.branch);
+      reservedPaths.set(path8.resolve(w.path), w.branch);
     }
     const plan = [];
     for (const branchName of newBranches) {
       const worktreePath = this.pathResolution.getBranchWorktreePath(this.config.worktreeDir, branchName);
-      const resolved = path7.resolve(worktreePath);
+      const resolved = path8.resolve(worktreePath);
       const conflict = reservedPaths.get(resolved);
       if (conflict && conflict !== branchName) {
         this.logger.error(
@@ -2980,12 +3117,12 @@ var WorktreeSyncService = class {
   }
   async updateExistingWorktrees(worktrees, remoteBranches) {
     this.logger.info("Step 4: Checking for worktrees that need updates...");
-    const divergedDir = path7.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedDir = path8.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 ${path7.relative(process.cwd(), divergedDir)}`
+          `\u{1F4E6} Note: ${diverged.length} diverged worktree(s) in ${path8.relative(process.cwd(), divergedDir)}`
         );
       }
     } catch {
@@ -3015,7 +3152,23 @@ var WorktreeSyncService = class {
             return { action: "diverged", worktree };
           }
           const isBehind = await this.gitService.isWorktreeBehind(worktree.path);
-          return isBehind ? { action: "update", worktree } : null;
+          if (!isBehind) return null;
+          const sparseCfg = this.config.sparseCheckout;
+          if (sparseCfg && sparseCfg.skipUpdateWhenOutsideSparse !== false) {
+            const sparseService = this.gitService.getSparseCheckoutService();
+            if (sparseService.resolveMode(sparseCfg) === "cone") {
+              const diff = await this.gitService.getChangedPathsInRange(
+                worktree.path,
+                "HEAD",
+                `origin/${worktree.branch}`
+              );
+              if (diff !== null && !sparseService.pathsTouchSparse(diff, sparseCfg)) {
+                this.logger.info(`\u23ED\uFE0F  Skipping '${worktree.branch}' - upstream changes outside sparse paths`);
+                return null;
+              }
+            }
+          }
+          return { action: "update", worktree };
         })
       )
     );
@@ -3093,13 +3246,13 @@ var WorktreeSyncService = class {
   }
   async cleanupOrphanedDirectories(worktrees) {
     try {
-      const worktreeRelativePaths = worktrees.map((w) => path7.relative(this.config.worktreeDir, w.path));
+      const worktreeRelativePaths = worktrees.map((w) => path8.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 + path7.sep);
+          return worktreePath === dir || worktreePath.startsWith(dir + path8.sep);
         });
         if (!isPartOfWorktree) {
           orphanedDirs.push(dir);
@@ -3108,7 +3261,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 = path7.join(this.config.worktreeDir, dir);
+          const dirPath = path8.join(this.config.worktreeDir, dir);
           try {
             const stat4 = await fs6.stat(dirPath);
             if (stat4.isDirectory()) {
@@ -3142,7 +3295,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 = path7.relative(process.cwd(), divergedPath);
+        const relativePath = path8.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}`);
@@ -3166,12 +3319,12 @@ var WorktreeSyncService = class {
     }
   }
   async divergeWorktree(worktreePath, branchName) {
-    const divergedBaseDir = path7.join(this.config.worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedBaseDir = path8.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 = path7.join(divergedBaseDir, divergedName);
+    const divergedPath = path8.join(divergedBaseDir, divergedName);
     await fs6.mkdir(divergedBaseDir, { recursive: true });
     try {
       await fs6.rename(worktreePath, divergedPath);
@@ -3198,7 +3351,7 @@ var WorktreeSyncService = class {
   Original worktree location: ${worktreePath}`
     };
     await fs6.writeFile(
-      path7.join(divergedPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE),
+      path8.join(divergedPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE),
       JSON.stringify(metadata, null, 2)
     );
     return divergedPath;
@@ -3253,9 +3406,9 @@ var RepositoryContext = class {
   discoveryCache = /* @__PURE__ */ new Map();
   async loadConfig(configPath, options = {}) {
     const setDefaultCurrent = options.setDefaultCurrent ?? true;
-    const absolutePath = path8.resolve(configPath);
+    const absolutePath = path9.resolve(configPath);
     const configFile = await this.configLoader.loadConfigFile(absolutePath);
-    const configDir = path8.dirname(absolutePath);
+    const configDir = path9.dirname(absolutePath);
     const globalDefaults = configFile.defaults;
     const resolvedAll = [];
     for (const repo of configFile.repositories) {
@@ -3292,7 +3445,7 @@ var RepositoryContext = class {
     return configFile.repositories;
   }
   async detectFromPath(dirPath) {
-    const absolutePath = path8.resolve(dirPath);
+    const absolutePath = path9.resolve(dirPath);
     const cached = this.discoveryCache.get(absolutePath);
     if (cached && await this.isCacheFresh(cached)) {
       return cached.result;
@@ -3311,8 +3464,8 @@ var RepositoryContext = class {
     const { result, adminDir } = await this.detectFromPathUncached(absolutePath);
     if (result.isWorktree && result.bareRepoPath && adminDir) {
       const [worktreeHeadMtimeMs, worktreesDirMtimeMs] = await Promise.all([
-        safeMtimeMs(path8.join(adminDir, "HEAD")),
-        safeMtimeMs(path8.join(result.bareRepoPath, "worktrees"))
+        safeMtimeMs(path9.join(adminDir, "HEAD")),
+        safeMtimeMs(path9.join(result.bareRepoPath, "worktrees"))
       ]);
       this.discoveryCache.set(absolutePath, {
         result,
@@ -3344,8 +3497,8 @@ var RepositoryContext = class {
     return this.discoveryCache.size;
   }
   async discoverSiblingRepositories(currentBareRepoPath) {
-    const repoDir = path8.dirname(currentBareRepoPath);
-    const workspaceRoot = path8.dirname(repoDir);
+    const repoDir = path9.dirname(currentBareRepoPath);
+    const workspaceRoot = path9.dirname(repoDir);
     if (workspaceRoot === repoDir) return [];
     let entries;
     try {
@@ -3362,15 +3515,15 @@ var RepositoryContext = class {
     const results = [];
     await Promise.all(
       entries.map(async (entry) => {
-        const candidate = path8.join(workspaceRoot, entry);
-        const bareCandidate = path8.join(candidate, GIT_CONSTANTS.BARE_DIR_NAME);
+        const candidate = path9.join(workspaceRoot, entry);
+        const bareCandidate = path9.join(candidate, GIT_CONSTANTS.BARE_DIR_NAME);
         try {
           const stat4 = await fs7.stat(bareCandidate);
           if (!stat4.isDirectory()) return;
         } catch {
           return;
         }
-        const resolvedBare = path8.resolve(bareCandidate);
+        const resolvedBare = path9.resolve(bareCandidate);
         const matchedName = configBares.get(normalizePathForCompare(resolvedBare));
         results.push({
           name: matchedName ?? entry,
@@ -3392,8 +3545,8 @@ var RepositoryContext = class {
     if (Date.now() - cached.cachedAt >= DISCOVERY_CACHE_TTL_MS) return false;
     if (!cached.worktreeAdminDir || !cached.result.bareRepoPath) return true;
     const [currentHeadMtime, currentWorktreesDirMtime] = await Promise.all([
-      safeMtimeMs(path8.join(cached.worktreeAdminDir, "HEAD")),
-      safeMtimeMs(path8.join(cached.result.bareRepoPath, "worktrees"))
+      safeMtimeMs(path9.join(cached.worktreeAdminDir, "HEAD")),
+      safeMtimeMs(path9.join(cached.result.bareRepoPath, "worktrees"))
     ]);
     return currentHeadMtime === cached.worktreeHeadMtimeMs && currentWorktreesDirMtime === cached.worktreesDirMtimeMs;
   }
@@ -3434,13 +3587,13 @@ var RepositoryContext = class {
       return unsupported("Invalid .git file format (missing gitdir line)");
     }
     const gitdir = gitdirMatch[1].trim();
-    const resolvedGitdir = path8.isAbsolute(gitdir) ? gitdir : path8.resolve(worktreeRoot, gitdir);
+    const resolvedGitdir = path9.isAbsolute(gitdir) ? gitdir : path9.resolve(worktreeRoot, gitdir);
     const worktreesMatch = resolvedGitdir.match(/^(.+?)[/\\]worktrees[/\\][^/\\]+$/);
     if (!worktreesMatch) {
       return unsupported("gitdir does not follow worktree structure (missing /worktrees/<name>)");
     }
-    const bareRepoPath = path8.resolve(worktreesMatch[1]);
-    const adminDir = path8.resolve(resolvedGitdir);
+    const bareRepoPath = path9.resolve(worktreesMatch[1]);
+    const adminDir = path9.resolve(resolvedGitdir);
     let repoUrl = null;
     let worktrees = [];
     let currentBranch = null;
@@ -3481,7 +3634,7 @@ var RepositoryContext = class {
         adminDir
       };
     }
-    const worktreeDir = path8.dirname(worktreeRoot);
+    const worktreeDir = path9.dirname(worktreeRoot);
     const noUrlReason = "no remote origin URL detected";
     const capabilities = {
       listWorktrees: { available: true },
@@ -3517,7 +3670,7 @@ var RepositoryContext = class {
         cronSchedule: DEFAULT_CONFIG.CRON_SCHEDULE,
         runOnce: true
       };
-      const detectedKey = `${AUTO_DETECT_PREFIX}${path8.basename(bareRepoPath)}@${bareRepoPath}`;
+      const detectedKey = `${AUTO_DETECT_PREFIX}${path9.basename(bareRepoPath)}@${bareRepoPath}`;
       if (!this.repos.has(detectedKey)) {
         this.repos.set(detectedKey, {
           name: detectedKey,
@@ -3609,7 +3762,7 @@ function parseWorktreeList(output, currentPath) {
   const foldedCurrent = normalizePathForCompare(currentPath);
   const results = [];
   for (const wt of parseWorktreeListPorcelain(output)) {
-    const resolved = path8.resolve(wt.path);
+    const resolved = path9.resolve(wt.path);
     const branch = wt.branch ?? (wt.detached ? `(detached ${(wt.head ?? "").slice(0, 7)})` : null);
     if (!branch) continue;
     results.push({
@@ -3629,10 +3782,10 @@ async function safeMtimeMs(filePath) {
   }
 }
 async function findWorktreeRoot(startPath) {
-  let current = path8.resolve(startPath);
-  const root = path8.parse(current).root;
+  let current = path9.resolve(startPath);
+  const root = path9.parse(current).root;
   while (true) {
-    const gitPath = path8.join(current, ".git");
+    const gitPath = path9.join(current, ".git");
     try {
       const content = await fs7.readFile(gitPath, "utf-8");
       return { kind: "worktree-file", worktreeRoot: current, gitFileContent: content };
@@ -3646,7 +3799,7 @@ async function findWorktreeRoot(startPath) {
       }
     }
     if (current === root) return null;
-    const parent = path8.dirname(current);
+    const parent = path9.dirname(current);
     if (parent === current) return null;
     current = parent;
   }
@@ -3657,7 +3810,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
 // src/mcp/handlers.ts
-import * as path9 from "path";
+import * as path10 from "path";
 import pLimit2 from "p-limit";
 
 // src/utils/disk-space.ts
@@ -3854,7 +4007,7 @@ async function getReadyService(ctx, repoName, options = {}) {
 }
 async function ensureRepoWorktreePath(ctx, params, git) {
   await ensurePathBelongsToRepo(ctx, params.path, params.repoName, git);
-  return path9.resolve(params.path);
+  return path10.resolve(params.path);
 }
 async function ensurePathBelongsToRepo(ctx, targetPath, repoName, git) {
   const discovered = ctx.getDiscoveredContext(repoName);
@@ -3915,7 +4068,7 @@ async function handleListWorktrees(ctx, params, _extra) {
   const results = await Promise.all(
     worktrees.map(
       (wt) => limit(async () => {
-        const resolvedPath = path9.resolve(wt.path);
+        const resolvedPath = path10.resolve(wt.path);
         const isCurrent = currentPath !== null && pathsEqual(wt.path, currentPath);
         const [status, divergence, metadata, sizeBytes] = await Promise.all([
           git.getFullWorktreeStatus(wt.path, false).catch(() => null),
@@ -3995,7 +4148,7 @@ async function handleCreateWorktree(ctx, params, _extra) {
   return formatToolResponse({
     success: true,
     branchName,
-    worktreePath: path9.resolve(worktreePath),
+    worktreePath: path10.resolve(worktreePath),
     created,
     pushed
   });
@@ -4083,7 +4236,7 @@ async function handleLoadConfig(ctx, params, _extra) {
   }
   await ctx.loadConfig(configPath);
   return formatToolResponse({
-    configPath: path9.resolve(configPath),
+    configPath: path10.resolve(configPath),
     currentRepository: ctx.getCurrentRepo(),
     repositories: ctx.getRepositoryList()
   });