chunksilo 2.3.2__tar.gz → 2.3.3__tar.gz

{chunksilo-2.3.2/src/chunksilo.egg-info → chunksilo-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chunksilo
-Version: 2.3.2
+Version: 2.3.3
 Summary: Local RAG-based semantic document search with MCP server interface
 Author: Fredrik Reveny
 License-Expression: Apache-2.0

{chunksilo-2.3.2 → chunksilo-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chunksilo"
-version = "2.3.2"
+version = "2.3.3"
 description = "Local RAG-based semantic document search with MCP server interface"
 license = "Apache-2.0"
 requires-python = ">=3.11"

{chunksilo-2.3.2 → chunksilo-2.3.3}/src/chunksilo/__init__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 """ChunkSilo - Local RAG-based semantic document search."""
 
-__version__ = "2.3.2"
+__version__ = "2.3.3"

{chunksilo-2.3.2 → chunksilo-2.3.3}/src/chunksilo/cfgload.py

@@ -75,6 +75,7 @@ _DEFAULTS: dict[str, Any] = {
             "per_file_seconds": 300,  # 5 minutes per file
             "doc_conversion_seconds": 90,  # 90 seconds for .doc conversion
             "heartbeat_interval_seconds": 2,
+            "scan_item_seconds": 30,  # timeout for stat/hash/walk during scanning
         },
         "logging": {
             "log_slow_files": True,

{chunksilo-2.3.2 → chunksilo-2.3.3}/src/chunksilo/index.py

@@ -10,6 +10,7 @@ import itertools
 import json
 import logging
 import os
+import queue
 import signal
 import sqlite3
 import sys
@@ -575,48 +576,28 @@ def _extract_pdf_headings_from_outline(
         return []
 
 
-def _split_docx_with_timeout(
-    docx_path: Path,
-    ctx: "FileProcessingContext | None",
-    timeout_seconds: float,
-) -> List[LlamaIndexDocument]:
-    """Run split_docx_into_heading_documents() in a worker thread with a hard timeout.
+_SCAN_TIMEOUT_SENTINEL = object()
 
-    Returns the loaded documents, or an empty list if the call times out.
-    """
-    with ThreadPoolExecutor(max_workers=1) as pool:
-        future = pool.submit(split_docx_into_heading_documents, docx_path, ctx)
-        try:
-            return future.result(timeout=timeout_seconds)
-        except Exception as e:
-            future.cancel()
-            if "TimeoutError" in type(e).__name__ or isinstance(e, TimeoutError):
-                logger.warning(
-                    f"DOCX processing timed out after {timeout_seconds:.0f}s: {docx_path}"
-                )
-                return []
-            raise
 
+def _run_with_timeout(fn, timeout_seconds: float, default=_SCAN_TIMEOUT_SENTINEL):
+    """Run *fn* in a background thread, returning *default* on timeout.
 
-def _load_data_with_timeout(
-    reader: SimpleDirectoryReader, timeout_seconds: float
-) -> List[LlamaIndexDocument]:
-    """Run reader.load_data() in a worker thread with a hard timeout.
-
-    Returns the loaded documents, or an empty list if the call times out.
+    If *fn* raises an exception it is re-raised in the caller.
+    On timeout the pool is shut down without waiting so the caller is not
+    blocked by a still-running filesystem call.
     """
-    with ThreadPoolExecutor(max_workers=1) as pool:
-        future = pool.submit(reader.load_data)
-        try:
-            return future.result(timeout=timeout_seconds)
-        except Exception as e:
-            future.cancel()
-            if "TimeoutError" in type(e).__name__ or isinstance(e, TimeoutError):
-                logger.warning(
-                    f"load_data() timed out after {timeout_seconds:.0f}s"
-                )
-                return []
-            raise
+    pool = ThreadPoolExecutor(max_workers=1)
+    future = pool.submit(fn)
+    try:
+        result = future.result(timeout=timeout_seconds)
+        pool.shutdown(wait=False)
+        return result
+    except Exception as exc:
+        future.cancel()
+        pool.shutdown(wait=False, cancel_futures=True)
+        if "TimeoutError" in type(exc).__name__ or isinstance(exc, TimeoutError):
+            return default
+        raise
 
 
 class LocalFileSystemSource(DataSource):
@@ -627,17 +608,31 @@ class LocalFileSystemSource(DataSource):
         self.base_dir = config.path
 
     def is_available(self) -> bool:
-        """Check if the directory is available and accessible."""
-        try:
-            if not self.base_dir.exists():
-                return False
-            if not self.base_dir.is_dir():
+        """Check if the directory is available and accessible.
+
+        Runs with a timeout to avoid hanging on unresponsive network mounts.
+        """
+        timeout = cfgload.get("indexing.timeout.scan_item_seconds", 30)
+
+        def _check():
+            try:
+                if not self.base_dir.exists():
+                    return False
+                if not self.base_dir.is_dir():
+                    return False
+                # Try to list directory to verify access (important for network mounts)
+                next(self.base_dir.iterdir(), None)
+                return True
+            except (OSError, PermissionError):
                 return False
-            # Try to list directory to verify access (important for network mounts)
-            next(self.base_dir.iterdir(), None)
-            return True
-        except (OSError, PermissionError):
-            return False
+
+        result = _run_with_timeout(_check, timeout_seconds=timeout, default=False)
+        if result is False and timeout > 0:
+            # Distinguish genuine "not a dir" from timeout — log only for timeout
+            # (the sentinel default=False means we can't distinguish here, but
+            # _run_with_timeout already logged nothing; let callers log.)
+            pass
+        return result
 
     def _matches_patterns(self, file_path: Path) -> bool:
         """Check if file matches include patterns and doesn't match exclude patterns.
@@ -700,6 +695,43 @@ class LocalFileSystemSource(DataSource):
                     return True
         return False
 
+    def _walk_with_timeout(self):
+        """Yield (root, dirs, files) tuples from os.walk with per-iteration timeout.
+
+        Runs os.walk in a daemon thread, feeding results through a queue.
+        If no result arrives within scan_item_seconds, the walk is considered
+        stalled and iteration stops.
+        """
+        timeout = cfgload.get("indexing.timeout.scan_item_seconds", 30)
+        q: queue.Queue = queue.Queue()
+        _sentinel = None  # signals end of iteration
+
+        def _producer():
+            try:
+                for entry in os.walk(self.base_dir):
+                    q.put(entry)
+                q.put(_sentinel)
+            except Exception as exc:
+                q.put(exc)
+
+        t = threading.Thread(target=_producer, daemon=True)
+        t.start()
+
+        while True:
+            try:
+                item = q.get(timeout=timeout)
+            except queue.Empty:
+                logger.warning(
+                    f"os.walk() stalled for {timeout}s on {self.base_dir}, "
+                    "aborting directory scan"
+                )
+                return
+            if item is _sentinel:
+                return
+            if isinstance(item, Exception):
+                raise item
+            yield item
+
     def iter_files(self, tracked_files: Dict[str, dict] | None = None) -> Iterator[FileInfo]:
         """Yield FileInfo for each matching file in the source.
 
@@ -708,8 +740,7 @@ class LocalFileSystemSource(DataSource):
                 keyed by absolute path. Used for mtime-based fast pre-check.
         """
         if self.config.recursive:
-            # topdown=True (default) allows pruning dirs in-place
-            for root, dirs, files in os.walk(self.base_dir):
+            for root, dirs, files in self._walk_with_timeout():
                 # Prune excluded directories in-place to prevent descent
                 dirs[:] = [d for d in dirs if not self._should_skip_directory(d)]
 
@@ -720,7 +751,7 @@ class LocalFileSystemSource(DataSource):
                         continue
                     try:
                         yield self._create_file_info(file_path, tracked_files)
-                    except (OSError, IOError) as e:
+                    except (OSError, IOError, TimeoutError) as e:
                         logger.warning(f"Could not access file {file_path}: {e}")
                         continue
         else:
@@ -738,7 +769,7 @@ class LocalFileSystemSource(DataSource):
                     continue
                 try:
                     yield self._create_file_info(f, tracked_files)
-                except (OSError, IOError) as e:
+                except (OSError, IOError, TimeoutError) as e:
                     logger.warning(f"Could not access file {f}: {e}")
                     continue
 
@@ -746,6 +777,30 @@ class LocalFileSystemSource(DataSource):
         self,
         file_path: Path,
         tracked_files: Dict[str, dict] | None = None,
+    ) -> FileInfo:
+        """Create FileInfo with timeout protection against stalled mounts.
+
+        Delegates to _create_file_info_inner in a background thread so that a
+        blocking stat() or read() cannot hang the scan indefinitely.
+
+        Raises TimeoutError if the operation exceeds scan_item_seconds.
+        """
+        timeout = cfgload.get("indexing.timeout.scan_item_seconds", 30)
+        result = _run_with_timeout(
+            lambda: self._create_file_info_inner(file_path, tracked_files),
+            timeout_seconds=timeout,
+        )
+        if result is _SCAN_TIMEOUT_SENTINEL:
+            logger.warning(
+                f"Timed out after {timeout}s accessing file {file_path}, skipping"
+            )
+            raise TimeoutError(f"stat/hash timed out for {file_path}")
+        return result
+
+    def _create_file_info_inner(
+        self,
+        file_path: Path,
+        tracked_files: Dict[str, dict] | None = None,
     ) -> FileInfo:
         """Create FileInfo with source directory context.
 
@@ -787,15 +842,30 @@ class LocalFileSystemSource(DataSource):
         ctx: "FileProcessingContext | None" = None
     ) -> List[LlamaIndexDocument]:
         file_path = Path(file_info.path)
-        if not file_path.exists():
-            logger.warning(f"Skipping disappeared file: {file_path}")
+        exists_timeout = cfgload.get("indexing.timeout.scan_item_seconds", 30)
+        exists_result = _run_with_timeout(
+            file_path.exists, timeout_seconds=exists_timeout, default=False,
+        )
+        if not exists_result:
+            if exists_result is False:
+                logger.warning(f"Skipping disappeared file: {file_path}")
             return []
         if file_path.suffix.lower() == ".docx":
             if ctx:
                 ctx.set_phase("Parsing DOCX")
             remaining = ctx.remaining_seconds() if ctx else None
             if remaining is not None:
-                return _split_docx_with_timeout(file_path, ctx, remaining)
+                result = _run_with_timeout(
+                    lambda: split_docx_into_heading_documents(file_path, ctx),
+                    timeout_seconds=remaining,
+                    default=None,
+                )
+                if result is None:
+                    logger.warning(
+                        f"DOCX processing timed out after {remaining:.0f}s: {file_path}"
+                    )
+                    return []
+                return result
             return split_docx_into_heading_documents(file_path, ctx)
         elif file_path.suffix.lower() == ".doc":
             # Convert .doc to .docx using LibreOffice, then process
@@ -814,7 +884,16 @@ class LocalFileSystemSource(DataSource):
                     ctx.set_phase("Parsing converted DOCX")
                 remaining = ctx.remaining_seconds() if ctx else None
                 if remaining is not None:
-                    docs = _split_docx_with_timeout(docx_path, ctx, remaining)
+                    result = _run_with_timeout(
+                        lambda: split_docx_into_heading_documents(docx_path, ctx),
+                        timeout_seconds=remaining,
+                        default=None,
+                    )
+                    if result is None:
+                        logger.warning(
+                            f"DOCX processing timed out after {remaining:.0f}s: {docx_path}"
+                        )
+                    docs = result if result is not None else []
                 else:
                     docs = split_docx_into_heading_documents(docx_path, ctx)
                 # Update metadata to point to original .doc file
@@ -834,7 +913,16 @@ class LocalFileSystemSource(DataSource):
             )
             remaining = ctx.remaining_seconds() if ctx else None
             if remaining is not None:
-                docs = _load_data_with_timeout(reader, remaining)
+                result = _run_with_timeout(
+                    reader.load_data,
+                    timeout_seconds=remaining,
+                    default=None,
+                )
+                if result is None:
+                    logger.warning(
+                        f"load_data() timed out after {remaining:.0f}s"
+                    )
+                docs = result if result is not None else []
             else:
                 docs = reader.load_data()
             # Ensure dates are visible to LLM (remove from exclusion list)

{chunksilo-2.3.2 → chunksilo-2.3.3/src/chunksilo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chunksilo
-Version: 2.3.2
+Version: 2.3.3
 Summary: Local RAG-based semantic document search with MCP server interface
 Author: Fredrik Reveny
 License-Expression: Apache-2.0

{chunksilo-2.3.2 → chunksilo-2.3.3}/src/chunksilo.egg-info/SOURCES.txt

@@ -28,5 +28,6 @@ test/test_jira_integration.py
 test/test_quoted_phrases.py
 test/test_rag_metrics.py
 test/test_retrieval_only.py
+test/test_scan_timeouts.py
 test/test_system.py
 test/test_utils.py

{chunksilo-2.3.2 → chunksilo-2.3.3}/test/test_indexing_ui.py

@@ -779,58 +779,57 @@ class TestFileProcessingContextTimeout:
 
 
 # =============================================================================
-# _load_data_with_timeout tests (Issue #39)
+# _run_with_timeout integration tests for load_data / DOCX (Issue #39)
 # =============================================================================
 
 
 class TestLoadDataWithTimeout:
     def test_returns_docs_on_success(self):
-        """_load_data_with_timeout returns docs when load_data succeeds."""
+        """_run_with_timeout returns docs when load_data succeeds."""
         from unittest.mock import MagicMock
-        from chunksilo.index import _load_data_with_timeout
+        from chunksilo.index import _run_with_timeout
 
         mock_reader = MagicMock()
         mock_reader.load_data.return_value = ["doc1", "doc2"]
 
-        result = _load_data_with_timeout(mock_reader, timeout_seconds=5.0)
+        result = _run_with_timeout(mock_reader.load_data, timeout_seconds=5.0, default=None)
         assert result == ["doc1", "doc2"]
 
-    def test_returns_empty_on_timeout(self):
-        """_load_data_with_timeout returns [] when load_data hangs."""
+    def test_returns_default_on_timeout(self):
+        """_run_with_timeout returns default when load_data hangs."""
         from unittest.mock import MagicMock
-        from chunksilo.index import _load_data_with_timeout
+        from chunksilo.index import _run_with_timeout
 
         mock_reader = MagicMock()
         mock_reader.load_data.side_effect = lambda: time.sleep(10)
 
-        result = _load_data_with_timeout(mock_reader, timeout_seconds=0.1)
-        assert result == []
-
-
-# =============================================================================
-# _split_docx_with_timeout tests (Issue #39)
-# =============================================================================
+        result = _run_with_timeout(mock_reader.load_data, timeout_seconds=0.1, default=None)
+        assert result is None
 
 
 class TestSplitDocxWithTimeout:
     def test_returns_docs_on_success(self):
-        """_split_docx_with_timeout returns docs when processing succeeds."""
+        """_run_with_timeout returns docs when DOCX processing succeeds."""
         from unittest.mock import patch, MagicMock
-        from chunksilo.index import _split_docx_with_timeout
+        from chunksilo.index import _run_with_timeout
 
         mock_doc = MagicMock()
         with patch(
             "chunksilo.index.split_docx_into_heading_documents",
             return_value=[mock_doc],
-        ):
-            result = _split_docx_with_timeout(Path("/fake/doc.docx"), None, 5.0)
+        ) as mock_split:
+            result = _run_with_timeout(
+                lambda: mock_split(Path("/fake/doc.docx"), None),
+                timeout_seconds=5.0,
+                default=None,
+            )
 
         assert result == [mock_doc]
 
-    def test_returns_empty_on_timeout(self):
-        """_split_docx_with_timeout returns [] when processing hangs."""
+    def test_returns_default_on_timeout(self):
+        """_run_with_timeout returns default when DOCX processing hangs."""
         from unittest.mock import patch
-        from chunksilo.index import _split_docx_with_timeout
+        from chunksilo.index import _run_with_timeout
 
         def hang(*args, **kwargs):
             time.sleep(10)
@@ -838,7 +837,11 @@ class TestSplitDocxWithTimeout:
         with patch(
             "chunksilo.index.split_docx_into_heading_documents",
             side_effect=hang,
-        ):
-            result = _split_docx_with_timeout(Path("/fake/doc.docx"), None, 0.1)
+        ) as mock_split:
+            result = _run_with_timeout(
+                lambda: mock_split(Path("/fake/doc.docx"), None),
+                timeout_seconds=0.1,
+                default=None,
+            )
 
-        assert result == []
+        assert result is None

chunksilo-2.3.3/test/test_scan_timeouts.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Tests for scan-phase timeout protection.
+
+Verifies that filesystem operations during the scanning phase (directory
+traversal, stat, MD5 hashing, file existence checks) cannot hang indefinitely
+when a network mount becomes unresponsive.
+
+Uses threading.Event + time.sleep to simulate blocking filesystem calls
+without needing a real stalled network mount.
+"""
+import hashlib
+import os
+import threading
+import time
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from chunksilo.index import (
+    _run_with_timeout,
+    _SCAN_TIMEOUT_SENTINEL,
+    DirectoryConfig,
+    FileInfo,
+    IndexConfig,
+    LocalFileSystemSource,
+    MultiDirectoryDataSource,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _block_forever(*_args, **_kwargs):
+    """Simulate a blocking syscall that never returns."""
+    threading.Event().wait(timeout=60)
+
+
+def _make_source(tmp_path, **overrides):
+    """Create a LocalFileSystemSource pointing at tmp_path."""
+    cfg = DirectoryConfig(path=tmp_path, **overrides)
+    return LocalFileSystemSource(cfg)
+
+
+# ===========================================================================
+# TestRunWithTimeout — tests for the _run_with_timeout() helper itself
+# ===========================================================================
+
+
+class TestRunWithTimeout:
+    def test_fast_call_returns_result(self):
+        """Callable that returns immediately yields its value."""
+        assert _run_with_timeout(lambda: 42, timeout_seconds=5) == 42
+
+    def test_slow_call_times_out(self):
+        """Callable that sleeps longer than timeout returns the default."""
+        result = _run_with_timeout(
+            lambda: threading.Event().wait(60) or "never",
+            timeout_seconds=1,
+            default="timed_out",
+        )
+        assert result == "timed_out"
+
+    def test_slow_call_returns_sentinel_by_default(self):
+        """When no default is given, the sentinel object is returned."""
+        result = _run_with_timeout(
+            lambda: threading.Event().wait(60),
+            timeout_seconds=1,
+        )
+        assert result is _SCAN_TIMEOUT_SENTINEL
+
+    def test_exception_propagates(self):
+        """Callable that raises an exception propagates it."""
+        def _raise():
+            raise ValueError("boom")
+
+        with pytest.raises(ValueError, match="boom"):
+            _run_with_timeout(_raise, timeout_seconds=5)
+
+
+# ===========================================================================
+# TestIsAvailableTimeout — is_available() doesn't hang on unresponsive mounts
+# ===========================================================================
+
+
+class TestIsAvailableTimeout:
+    @patch("chunksilo.index.cfgload")
+    def test_is_available_returns_false_on_timeout(self, mock_cfg, tmp_path):
+        """Patch Path.exists() to block; is_available() returns False within
+        a reasonable time rather than hanging for 60s."""
+        mock_cfg.get.return_value = 2  # 2-second timeout for fast test
+
+        source = _make_source(tmp_path)
+
+        # Patch the specific base_dir's exists to block
+        original_exists = Path.exists
+        def _blocking_exists(self_path):
+            if self_path == tmp_path:
+                threading.Event().wait(60)
+            return original_exists(self_path)
+
+        with patch.object(Path, "exists", _blocking_exists):
+            start = time.monotonic()
+            result = source.is_available()
+            elapsed = time.monotonic() - start
+
+        assert result is False
+        assert elapsed < 10, f"is_available() took {elapsed:.1f}s, expected < 10s"
+
+    def test_is_available_returns_true_when_responsive(self, tmp_path):
+        """Normal directory on tmp_path still returns True (no false positives)."""
+        (tmp_path / "file.txt").write_text("hello")
+        source = _make_source(tmp_path)
+        assert source.is_available() is True
+
+
+# ===========================================================================
+# TestCreateFileInfoTimeout — _create_file_info() doesn't hang on stat/read
+# ===========================================================================
+
+
+class TestCreateFileInfoTimeout:
+    @patch("chunksilo.index.cfgload")
+    def test_stat_hang_skips_file(self, mock_cfg, tmp_path):
+        """When Path.stat blocks, iter_files skips the file with a warning."""
+        mock_cfg.get.return_value = 2  # 2s timeout
+
+        f = tmp_path / "test.txt"
+        f.write_text("data")
+        source = _make_source(tmp_path)
+
+        original_stat = Path.stat
+        def _blocking_stat(self_path, *a, **kw):
+            if self_path == f:
+                threading.Event().wait(60)
+            return original_stat(self_path, *a, **kw)
+
+        with patch.object(Path, "stat", _blocking_stat):
+            start = time.monotonic()
+            results = list(source.iter_files())
+            elapsed = time.monotonic() - start
+
+        assert len(results) == 0
+        assert elapsed < 15, f"iter_files() took {elapsed:.1f}s, expected < 15s"
+
+    @patch("chunksilo.index.cfgload")
+    def test_hash_read_hang_skips_file(self, mock_cfg, tmp_path):
+        """When open().read() blocks during MD5 hashing, the file is skipped."""
+        mock_cfg.get.return_value = 2  # 2s timeout
+
+        f = tmp_path / "test.txt"
+        f.write_text("data")
+        source = _make_source(tmp_path)
+
+        original_open = open
+        def _blocking_open(path, *args, **kwargs):
+            fh = original_open(path, *args, **kwargs)
+            if str(path) == str(f) and "b" in (args[0] if args else ""):
+                original_read = fh.read
+                def _blocking_read(*a, **kw):
+                    threading.Event().wait(60)
+                    return original_read(*a, **kw)
+                fh.read = _blocking_read
+            return fh
+
+        with patch("builtins.open", _blocking_open):
+            start = time.monotonic()
+            results = list(source.iter_files())
+            elapsed = time.monotonic() - start
+
+        assert len(results) == 0
+        assert elapsed < 15, f"iter_files() took {elapsed:.1f}s, expected < 15s"
+
+    def test_normal_files_unaffected(self, tmp_path):
+        """Normal local files are returned with correct hashes."""
+        files = {}
+        for name in ("a.txt", "b.txt", "c.txt"):
+            p = tmp_path / name
+            p.write_text(f"content of {name}")
+            h = hashlib.md5(p.read_bytes()).hexdigest()
+            files[str(p.absolute())] = h
+
+        source = _make_source(tmp_path)
+        results = list(source.iter_files())
+
+        assert len(results) == 3
+        for fi in results:
+            assert fi.hash == files[fi.path], f"Hash mismatch for {fi.path}"
+
+
+# ===========================================================================
+# TestIterFilesWithTimeout — os.walk() hangs are recovered from
+# ===========================================================================
+
+
+class TestIterFilesWithTimeout:
+    @patch("chunksilo.index.cfgload")
+    def test_walk_hang_on_subdirectory_recovers(self, mock_cfg, tmp_path):
+        """When os.walk blocks on a subdirectory, iter_files eventually stops
+        rather than hanging forever."""
+        mock_cfg.get.return_value = 2  # 2s timeout
+
+        # Create dir structure: subA/file_a.txt, subB/ (will hang)
+        sub_a = tmp_path / "subA"
+        sub_a.mkdir()
+        (sub_a / "file_a.txt").write_text("aaa")
+        sub_b = tmp_path / "subB"
+        sub_b.mkdir()
+        (sub_b / "file_b.txt").write_text("bbb")
+
+        source = _make_source(tmp_path)
+
+        # Replace os.walk to yield first entry normally, then block
+        original_walk = os.walk
+
+        def _stalling_walk(top, **kw):
+            call_count = 0
+            for entry in original_walk(top, **kw):
+                call_count += 1
+                yield entry
+                if call_count >= 2:  # After yielding top + subA, block
+                    threading.Event().wait(60)
+
+        with patch("os.walk", _stalling_walk):
+            start = time.monotonic()
+            results = list(source.iter_files())
+            elapsed = time.monotonic() - start
+
+        # Should have at least the file from subA (and maybe top-level)
+        # but should NOT hang for 60s
+        assert elapsed < 15, f"iter_files() took {elapsed:.1f}s, expected < 15s"
+
+    def test_all_walk_results_returned_when_fast(self, tmp_path):
+        """Normal tmp_path with nested dirs returns all files."""
+        sub = tmp_path / "nested"
+        sub.mkdir()
+        (tmp_path / "top.txt").write_text("top")
+        (sub / "deep.txt").write_text("deep")
+
+        source = _make_source(tmp_path)
+        results = list(source.iter_files())
+
+        paths = {fi.path for fi in results}
+        assert str((tmp_path / "top.txt").absolute()) in paths
+        assert str((sub / "deep.txt").absolute()) in paths
+
+
+# ===========================================================================
+# TestMultiDirectorySourceTimeout — stalled source doesn't block others
+# ===========================================================================
+
+
+class TestMultiDirectorySourceTimeout:
+    def test_stalled_source_does_not_block_others(self, tmp_path):
+        """One directory is responsive, the other's is_available blocks.
+        Only the working directory's files are indexed."""
+        good_dir = tmp_path / "good"
+        good_dir.mkdir()
+        (good_dir / "file.txt").write_text("hello")
+
+        bad_dir = tmp_path / "bad"
+        bad_dir.mkdir()
+
+        config = IndexConfig(
+            directories=[
+                DirectoryConfig(path=good_dir),
+                DirectoryConfig(path=bad_dir),
+            ]
+        )
+
+        original_is_available = LocalFileSystemSource.is_available
+
+        def _patched_is_available(self):
+            if self.base_dir == bad_dir:
+                # Simulate stalled mount — return False (as timeout would)
+                return False
+            return original_is_available(self)
+
+        with patch.object(LocalFileSystemSource, "is_available", _patched_is_available):
+            mds = MultiDirectoryDataSource(config)
+
+        assert len(mds.sources) == 1
+        assert len(mds.unavailable_dirs) == 1
+
+        results = list(mds.iter_files())
+        assert len(results) == 1
+        assert results[0].path == str((good_dir / "file.txt").absolute())
+
+    @patch("chunksilo.index.cfgload")
+    def test_stalled_source_during_scan_skips_to_next(self, mock_cfg, tmp_path):
+        """Both directories pass is_available(), but one's os.walk hangs.
+        Files from the other source are still returned."""
+        mock_cfg.get.return_value = 2  # 2s timeout
+
+        good_dir = tmp_path / "good"
+        good_dir.mkdir()
+        (good_dir / "file.txt").write_text("hello")
+
+        bad_dir = tmp_path / "bad"
+        bad_dir.mkdir()
+        (bad_dir / "file.txt").write_text("stale")
+
+        config = IndexConfig(
+            directories=[
+                DirectoryConfig(path=good_dir),
+                DirectoryConfig(path=bad_dir),
+            ]
+        )
+
+        mds = MultiDirectoryDataSource(config)
+        assert len(mds.sources) == 2
+
+        # Patch os.walk so walks into bad_dir hang, triggering queue timeout
+        original_walk = os.walk
+
+        def _stalling_walk(top, **kw):
+            if str(top) == str(bad_dir):
+                # Block immediately — queue timeout will abort iteration
+                threading.Event().wait(60)
+                return
+                yield  # make it a generator
+            yield from original_walk(top, **kw)
+
+        with patch("os.walk", _stalling_walk):
+            start = time.monotonic()
+            results = list(mds.iter_files())
+            elapsed = time.monotonic() - start
+
+        good_paths = {fi.path for fi in results}
+        assert str((good_dir / "file.txt").absolute()) in good_paths
+        assert elapsed < 15, f"iter_files() took {elapsed:.1f}s, expected < 15s"
+
+
+# ===========================================================================
+# TestLoadFileExistsTimeout — load_file existence check doesn't hang
+# ===========================================================================
+
+
+class TestLoadFileExistsTimeout:
+    @patch("chunksilo.index.cfgload")
+    def test_exists_hang_skips_file(self, mock_cfg, tmp_path):
+        """When Path.exists blocks on a file, load_file returns [] rather
+        than hanging."""
+        mock_cfg.get.return_value = 2  # 2s timeout
+
+        f = tmp_path / "test.txt"
+        f.write_text("data")
+        source = _make_source(tmp_path)
+        fi = FileInfo(
+            path=str(f.absolute()),
+            hash="abc",
+            last_modified=0,
+            source_dir=str(tmp_path.absolute()),
+        )
+
+        original_exists = Path.exists
+        def _blocking_exists(self_path):
+            if self_path == f:
+                threading.Event().wait(60)
+            return original_exists(self_path)
+
+        with patch.object(Path, "exists", _blocking_exists):
+            start = time.monotonic()
+            result = source.load_file(fi)
+            elapsed = time.monotonic() - start
+
+        assert result == []
+        assert elapsed < 10, f"load_file() took {elapsed:.1f}s, expected < 10s"