sync-worktrees 3.3.1 → 3.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as path12 from "path";
+import * as path13 from "path";
 import { confirm as confirm2 } from "@inquirer/prompts";
 import * as cron3 from "node-cron";
 import pLimit3 from "p-limit";
@@ -55,7 +55,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.",
@@ -215,9 +219,9 @@ var WorktreeError = class extends SyncWorktreesError {
   }
 };
 var WorktreeNotCleanError = class extends WorktreeError {
-  constructor(path13, reasons) {
-    super(`Worktree at '${path13}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
-    this.path = path13;
+  constructor(path14, reasons) {
+    super(`Worktree at '${path14}' is not clean: ${reasons.join(", ")}`, "NOT_CLEAN");
+    this.path = path14;
     this.reasons = reasons;
   }
 };
@@ -669,7 +673,7 @@ var ConfigLoaderService = class {
 
 // src/services/InteractiveUIService.tsx
 import React8 from "react";
-import * as path9 from "path";
+import * as path10 from "path";
 import { render } from "ink";
 import * as cron2 from "node-cron";
 import pLimit2 from "p-limit";
@@ -1945,8 +1949,9 @@ var App_default = App;
 
 // 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) {
@@ -2174,7 +2179,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
@@ -2318,11 +2323,13 @@ function defaultConsoleOutput(msg, level) {
 }
 
 // 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));
@@ -2406,11 +2413,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;
@@ -2423,7 +2485,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("\\")) {
@@ -2431,7 +2493,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,
@@ -2444,7 +2506,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 {
@@ -2637,7 +2699,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" },
@@ -2840,7 +2902,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
         )
@@ -2961,14 +3023,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 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 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}`);
       }
@@ -2982,7 +3044,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);
@@ -3005,7 +3067,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);
@@ -3024,11 +3086,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;
@@ -3040,11 +3112,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.");
     }
@@ -3061,17 +3135,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;
@@ -3107,7 +3181,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) {
@@ -3130,6 +3204,9 @@ var GitService = class {
   getDefaultBranch() {
     return this.defaultBranch;
   }
+  getBareRepoPath() {
+    return this.bareRepoPath;
+  }
   async fetchAll() {
     this.assertInitialized();
     this.logger.info("Fetching latest data from remote...");
@@ -3187,7 +3264,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;
@@ -3215,7 +3292,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 {
@@ -3304,12 +3381,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;
@@ -3354,7 +3431,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;
@@ -3400,7 +3477,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;
@@ -3430,7 +3507,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;
@@ -3653,6 +3730,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 {
@@ -3737,7 +3831,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 {
@@ -3747,22 +3841,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;
     }
@@ -3772,7 +3866,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);
@@ -3780,7 +3874,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);
@@ -3839,6 +3933,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();
@@ -3855,6 +3954,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) {
@@ -3866,6 +3970,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,
@@ -4041,12 +4178,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(
@@ -4251,12 +4388,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 {
@@ -4286,7 +4423,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 };
         })
       )
     );
@@ -4364,13 +4517,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);
@@ -4379,7 +4532,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 stat3 = await fs6.stat(dirPath);
             if (stat3.isDirectory()) {
@@ -4413,7 +4566,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}`);
@@ -4437,12 +4590,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);
@@ -4469,7 +4622,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;
@@ -4478,7 +4631,7 @@ var WorktreeSyncService = class {
 
 // src/services/file-copy.service.ts
 import * as fs7 from "fs/promises";
-import * as path8 from "path";
+import * as path9 from "path";
 import { glob } from "glob";
 var DEFAULT_IGNORE_PATTERNS = [
   "**/node_modules/**",
@@ -4505,8 +4658,8 @@ var FileCopyService = class {
     }
     const filesToCopy = await this.expandPatterns(sourceDir, patterns);
     for (const relativePath of filesToCopy) {
-      const sourcePath = path8.join(sourceDir, relativePath);
-      const destPath = path8.join(destDir, relativePath);
+      const sourcePath = path9.join(sourceDir, relativePath);
+      const destPath = path9.join(destDir, relativePath);
       try {
         const copied = await this.copyFile(sourcePath, destPath);
         if (copied) {
@@ -4547,7 +4700,7 @@ var FileCopyService = class {
       return false;
     } catch {
     }
-    const destDir = path8.dirname(destPath);
+    const destDir = path9.dirname(destPath);
     await fs7.mkdir(destDir, { recursive: true });
     await fs7.copyFile(sourcePath, destPath);
     return true;
@@ -4765,6 +4918,8 @@ var AppEventEmitter = class {
 
 // src/services/InteractiveUIService.tsx
 import * as fs8 from "fs/promises";
+var WAIT_SYNC_FAST_TIMEOUT_MS = 2e3;
+var WAIT_SYNC_DEFAULT_TIMEOUT_MS = 3e4;
 var InteractiveUIService = class {
   app = null;
   syncServices;
@@ -4872,6 +5027,9 @@ var InteractiveUIService = class {
     }
     this.cronJobs = [];
   }
+  registerCronJob(job) {
+    this.cronJobs.push(job);
+  }
   renderUI() {
     if (this.app) {
       this.app.unmount();
@@ -4895,8 +5053,8 @@ var InteractiveUIService = class {
           getWorktreeStatusForRepo: (index) => this.getWorktreeStatusForRepo(index),
           getDivergedDirectoriesForRepo: (index) => this.getDivergedDirectoriesForRepo(index),
           deleteDivergedDirectory: (repoIndex, name) => this.deleteDivergedDirectory(repoIndex, name),
-          openEditorInWorktree: (path13) => this.openEditorInWorktree(path13),
-          openTerminalInWorktree: (repoIndex, path13, branchName) => this.openTerminalInWorktree(repoIndex, path13, branchName),
+          openEditorInWorktree: (path14) => this.openEditorInWorktree(path14),
+          openTerminalInWorktree: (repoIndex, path14, branchName) => this.openTerminalInWorktree(repoIndex, path14, branchName),
           copyBranchFiles: (repoIndex, baseBranch, targetBranch) => this.copyBranchFiles(repoIndex, baseBranch, targetBranch),
           createWorktreeForBranch: (repoIndex, branchName) => this.createWorktreeForBranch(repoIndex, branchName),
           executeOnBranchCreatedHooks: (repoIndex, context) => this.executeOnBranchCreatedHooks(repoIndex, context)
@@ -4986,18 +5144,17 @@ var InteractiveUIService = class {
     await this.destroy();
     process.exit(0);
   }
-  async waitForInProgressSyncs() {
+  async waitForInProgressSyncs(timeoutMs = WAIT_SYNC_DEFAULT_TIMEOUT_MS) {
     const inProgressServices = this.syncServices.filter((s) => s.isSyncInProgress());
     if (inProgressServices.length === 0) {
       return;
     }
     this.addLog(`Waiting for ${inProgressServices.length} in-progress sync(s) to finish...`, "info");
     const syncChecks = inProgressServices.map(async (service) => {
-      const timeout = 3e4;
       const checkInterval = 500;
       const startTime = Date.now();
       while (service.isSyncInProgress()) {
-        if (Date.now() - startTime > timeout) {
+        if (Date.now() - startTime > timeoutMs) {
           throw new Error("Timeout waiting for sync operations to complete");
         }
         await new Promise((resolve9) => setTimeout(resolve9, checkInterval));
@@ -5007,7 +5164,7 @@ var InteractiveUIService = class {
       await Promise.all(syncChecks);
     } catch {
       this.addLog(
-        "Warning: Timeout waiting for sync operations to complete after 30s. Proceeding with potential data loss risk.",
+        `Warning: Timeout waiting for sync operations to complete after ${formatDuration2(timeoutMs)}. Proceeding with potential data loss risk.`,
         "warn"
       );
     }
@@ -5133,7 +5290,7 @@ var InteractiveUIService = class {
     }
     const service = this.syncServices[repoIndex];
     const worktreeDir = service.config.worktreeDir;
-    const divergedDir = path9.join(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedDir = path10.join(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
     let dirEntries;
     try {
       dirEntries = await fs8.readdir(divergedDir, { withFileTypes: true, encoding: "utf-8" });
@@ -5143,8 +5300,8 @@ var InteractiveUIService = class {
     const subdirs = dirEntries.filter((e) => e.isDirectory());
     const results = await Promise.allSettled(
       subdirs.map(async (entry) => {
-        const fullPath = path9.join(divergedDir, entry.name);
-        const infoFilePath = path9.join(fullPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE);
+        const fullPath = path10.join(divergedDir, entry.name);
+        const infoFilePath = path10.join(fullPath, METADATA_CONSTANTS.DIVERGED_INFO_FILE);
         let originalBranch = entry.name;
         let divergedAt = "";
         try {
@@ -5179,11 +5336,11 @@ var InteractiveUIService = class {
     }
     const service = this.syncServices[repoIndex];
     const worktreeDir = service.config.worktreeDir;
-    const divergedBase = path9.resolve(worktreeDir, GIT_CONSTANTS.DIVERGED_DIR_NAME);
+    const divergedBase = path10.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 = path9.join(divergedBase, name);
+    const targetPath = path10.join(divergedBase, name);
     if (!this.pathResolution.isPathInsideBaseDir(targetPath, divergedBase)) {
       throw new Error(`Path traversal rejected: "${name}" resolves outside the diverged directory`);
     }
@@ -5422,11 +5579,11 @@ var InteractiveUIService = class {
       this.addLog(`Failed to copy files to new branch: ${error}`, "error");
     }
   }
-  async destroy() {
+  async destroy(fast = false) {
     this.isDestroyed = true;
     this.cancelCronJobs();
     try {
-      await this.waitForInProgressSyncs();
+      await this.waitForInProgressSyncs(fast ? WAIT_SYNC_FAST_TIMEOUT_MS : WAIT_SYNC_DEFAULT_TIMEOUT_MS);
     } catch {
     }
     this.hookExecutionService.cleanup();
@@ -5572,7 +5729,7 @@ function reconstructCliCommand(config) {
 
 // src/utils/config-generator.ts
 import * as fs9 from "fs/promises";
-import * as path10 from "path";
+import * as path11 from "path";
 function serializeToESM(obj, indent = 0) {
   const spaces = " ".repeat(indent);
   const innerSpaces = " ".repeat(indent + 2);
@@ -5602,9 +5759,9 @@ ${spaces}}`;
   return String(obj);
 }
 async function generateConfigFile(config, configPath) {
-  const configDir = path10.dirname(configPath);
+  const configDir = path11.dirname(configPath);
   await fs9.mkdir(configDir, { recursive: true });
-  const worktreeDirRelative = path10.relative(configDir, config.worktreeDir);
+  const worktreeDirRelative = path11.relative(configDir, config.worktreeDir);
   const useRelativeWorktree = !worktreeDirRelative.startsWith("../../../");
   const repoName = extractRepoNameFromUrl(config.repoUrl);
   const repository = {
@@ -5613,7 +5770,7 @@ async function generateConfigFile(config, configPath) {
     worktreeDir: useRelativeWorktree ? `./${worktreeDirRelative}` : config.worktreeDir
   };
   if (config.bareRepoDir) {
-    const bareRepoDirRelative = path10.relative(configDir, config.bareRepoDir);
+    const bareRepoDirRelative = path11.relative(configDir, config.bareRepoDir);
     const useRelativeBare = !bareRepoDirRelative.startsWith("../../../");
     repository.bareRepoDir = useRelativeBare ? `./${bareRepoDirRelative}` : config.bareRepoDir;
   }
@@ -5634,11 +5791,11 @@ export default ${serializeToESM(configObject)};
   await fs9.writeFile(configPath, configContent, "utf-8");
 }
 function getDefaultConfigPath() {
-  return path10.join(process.cwd(), "sync-worktrees.config.js");
+  return path11.join(process.cwd(), "sync-worktrees.config.js");
 }
 async function findConfigInCwd(cwd = process.cwd()) {
   for (const name of CONFIG_FILE_NAMES) {
-    const full = path10.join(cwd, name);
+    const full = path11.join(cwd, name);
     try {
       await fs9.access(full);
       return full;
@@ -5649,7 +5806,7 @@ async function findConfigInCwd(cwd = process.cwd()) {
 }
 
 // src/utils/interactive.ts
-import * as path11 from "path";
+import * as path12 from "path";
 import { confirm, input, select } from "@inquirer/prompts";
 async function promptForConfig(partialConfig) {
   console.log("\u{1F527} Welcome to sync-worktrees interactive setup!\n");
@@ -5689,8 +5846,8 @@ async function promptForConfig(partialConfig) {
     if (!worktreeDir.trim() && defaultWorktreeDir) {
       worktreeDir = defaultWorktreeDir;
     }
-    if (!path11.isAbsolute(worktreeDir)) {
-      worktreeDir = path11.resolve(worktreeDir);
+    if (!path12.isAbsolute(worktreeDir)) {
+      worktreeDir = path12.resolve(worktreeDir);
     }
   }
   let bareRepoDir = partialConfig.bareRepoDir;
@@ -5709,8 +5866,8 @@ async function promptForConfig(partialConfig) {
         return true;
       }
     });
-    if (!path11.isAbsolute(bareRepoDir)) {
-      bareRepoDir = path11.resolve(bareRepoDir);
+    if (!path12.isAbsolute(bareRepoDir)) {
+      bareRepoDir = path12.resolve(bareRepoDir);
     }
   }
   let runOnce = partialConfig.runOnce;
@@ -5782,8 +5939,8 @@ async function promptForConfig(partialConfig) {
         return true;
       }
     });
-    if (!path11.isAbsolute(configPath)) {
-      configPath = path11.resolve(configPath);
+    if (!path12.isAbsolute(configPath)) {
+      configPath = path12.resolve(configPath);
     }
     try {
       await generateConfigFile(finalConfig, configPath);
@@ -5801,26 +5958,55 @@ async function promptForConfig(partialConfig) {
   return { config: finalConfig, savedConfigPath };
 }
 
-// src/index.ts
-var cleanupFns = [];
-function setupSignalHandlers() {
-  let shuttingDown = false;
-  const handler = async (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    console.log(`
-Received ${signal}, shutting down gracefully...`);
-    for (const fn of cleanupFns) {
-      try {
-        await fn();
-      } catch {
-      }
+// src/utils/signal-handlers.ts
+var DEFAULT_FORCE_EXIT_MS = 3e3;
+function setupSignalHandlers(options = {}) {
+  const forceExitMs = options.forceExitMs ?? DEFAULT_FORCE_EXIT_MS;
+  const log = options.log ?? ((msg) => console.log(msg));
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const target = options.process ?? process;
+  const cleanupFns = [];
+  let signalCount = 0;
+  const handler = (signal) => {
+    signalCount += 1;
+    if (signalCount >= 2) {
+      log(`
+Received second ${signal}, forcing exit.`);
+      exit(130);
+      return;
+    }
+    log(`
+Received ${signal}, shutting down (Ctrl+C again to force exit)...`);
+    const watchdog = setTimeout(() => {
+      log(`
+Shutdown took longer than ${forceExitMs}ms, forcing exit.`);
+      exit(130);
+    }, forceExitMs);
+    if (typeof watchdog.unref === "function") {
+      watchdog.unref();
+    }
+    void Promise.allSettled(cleanupFns.map((fn) => Promise.resolve().then(() => fn(true)))).then(() => {
+      clearTimeout(watchdog);
+      exit(0);
+    });
+  };
+  const sigintListener = () => handler("SIGINT");
+  const sigtermListener = () => handler("SIGTERM");
+  target.on("SIGINT", sigintListener);
+  target.on("SIGTERM", sigtermListener);
+  return {
+    register: (fn) => {
+      cleanupFns.push(fn);
+    },
+    dispose: () => {
+      target.removeListener("SIGINT", sigintListener);
+      target.removeListener("SIGTERM", sigtermListener);
     }
-    process.exit(0);
   };
-  process.on("SIGINT", () => void handler("SIGINT"));
-  process.on("SIGTERM", () => void handler("SIGTERM"));
 }
+
+// src/index.ts
+var signalHandle = setupSignalHandlers();
 async function runSingleRepository(config) {
   const logger = Logger.createDefault(void 0, config.debug);
   logger.info("\n\u{1F4CB} CLI Command (for future reference):");
@@ -5837,11 +6023,11 @@ async function runSingleRepository(config) {
       await syncService.sync();
     } else {
       const uiService = new InteractiveUIService([syncService], void 0, config.cronSchedule);
-      cleanupFns.push(() => uiService.destroy());
+      signalHandle.register((fast) => uiService.destroy(fast));
       await syncService.sync();
       uiService.updateLastSyncTime();
       void uiService.calculateAndUpdateDiskSpace();
-      cron3.schedule(config.cronSchedule, async () => {
+      const job = cron3.schedule(config.cronSchedule, async () => {
         try {
           uiService.setStatus("syncing");
           await syncService.sync();
@@ -5852,6 +6038,7 @@ async function runSingleRepository(config) {
           uiService.setStatus("idle");
         }
       });
+      uiService.registerCronJob(job);
     }
   } catch (error) {
     logger.error("\u274C Fatal Error during initialization:", error);
@@ -5918,7 +6105,7 @@ async function runMultipleRepositories(repositories, runOnce, configPath, maxPar
     const displaySchedule = uniqueSchedules.length === 1 ? uniqueSchedules[0] : void 0;
     const allServices = Array.from(services.values());
     const uiService = new InteractiveUIService(allServices, configPath, displaySchedule, maxParallel, reloadOptions);
-    cleanupFns.push(() => uiService.destroy());
+    signalHandle.register((fast) => uiService.destroy(fast));
     void uiService.calculateAndUpdateDiskSpace();
     uiService.setupCronJobs();
     uiService.addLog(`\u{1F4CB} ${repositories.length} repositories configured`);
@@ -6013,13 +6200,12 @@ async function runInteractive(partial, options) {
   await runSingleRepository(config);
 }
 async function main() {
-  setupSignalHandlers();
   const options = parseArguments();
   if (!options.config && !options.repoUrl && !options.worktreeDir) {
     const discovered = await findConfigInCwd();
     if (discovered) {
       options.config = discovered;
-      console.log(`\u{1F4C4} Using config: ${path12.relative(process.cwd(), discovered)}`);
+      console.log(`\u{1F4C4} Using config: ${path13.relative(process.cwd(), discovered)}`);
     }
   }
   if (options.config) {