wup 0.2.69__tar.gz → 0.2.70__tar.gz

{wup-0.2.69/wup.egg-info → wup-0.2.70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wup
-Version: 0.2.69
+Version: 0.2.70
 Summary: WUP (What's Up) - Intelligent file watcher for regression testing in large projects
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -42,17 +42,17 @@ Dynamic: license-file
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.69-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$5.86-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-51.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.70-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$6.52-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-51.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $5.8610 (97 commits)
+- 🤖 **LLM usage:** $6.5152 (98 commits)
 - 👤 **Human dev:** ~$5115 (51.1h @ $100/h, 30min dedup)
 
-Generated on 2026-07-16 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-07-17 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.69-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.70-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **WUP (What's Up)** - Intelligent file watcher for regression testing in large projects.
 
@@ -147,6 +147,30 @@ wup watch ./my-project --config custom-config.yaml
 wup testql-endpoints /path/to/scenarios --output testql-deps.json
 ```
 
+### Watch Multiple Projects Simultaneously
+
+Pass several project roots to watch them all at once in a single process. Each
+project keeps its own `wup.yaml`, dependency map, file observer and test queue.
+
+```bash
+# Watch several projects at the same time
+wup watch ./service-a ./service-b ./service-c
+
+# Discover: expand a monorepo root into every sub-project that has a wup.yaml
+wup watch --discover ./my-monorepo
+
+# Discover from the current directory
+wup watch -D .
+```
+
+`--discover` walks the immediate sub-directories of each given path and watches
+those that already contain a `wup.yaml` (hidden and vendor folders such as
+`node_modules`, `.venv`, `dist` and `build` are skipped). A relative `--deps`
+path is resolved per project, so each project uses its own `deps.json`.
+
+> The live `--dashboard` and single `--config` options apply to single-project
+> runs only; when watching multiple projects each uses its own `wup.yaml`.
+
 ### Initialize Configuration
 
 ```bash

{wup-0.2.69 → wup-0.2.70}/README.md

@@ -3,17 +3,17 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.69-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$5.86-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-51.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.70-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$6.52-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-51.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $5.8610 (97 commits)
+- 🤖 **LLM usage:** $6.5152 (98 commits)
 - 👤 **Human dev:** ~$5115 (51.1h @ $100/h, 30min dedup)
 
-Generated on 2026-07-16 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-07-17 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.69-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.70-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **WUP (What's Up)** - Intelligent file watcher for regression testing in large projects.
 
@@ -108,6 +108,30 @@ wup watch ./my-project --config custom-config.yaml
 wup testql-endpoints /path/to/scenarios --output testql-deps.json
 ```
 
+### Watch Multiple Projects Simultaneously
+
+Pass several project roots to watch them all at once in a single process. Each
+project keeps its own `wup.yaml`, dependency map, file observer and test queue.
+
+```bash
+# Watch several projects at the same time
+wup watch ./service-a ./service-b ./service-c
+
+# Discover: expand a monorepo root into every sub-project that has a wup.yaml
+wup watch --discover ./my-monorepo
+
+# Discover from the current directory
+wup watch -D .
+```
+
+`--discover` walks the immediate sub-directories of each given path and watches
+those that already contain a `wup.yaml` (hidden and vendor folders such as
+`node_modules`, `.venv`, `dist` and `build` are skipped). A relative `--deps`
+path is resolved per project, so each project uses its own `deps.json`.
+
+> The live `--dashboard` and single `--config` options apply to single-project
+> runs only; when watching multiple projects each uses its own `wup.yaml`.
+
 ### Initialize Configuration
 
 ```bash

{wup-0.2.69 → wup-0.2.70}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wup"
-version = "0.2.69"
+version = "0.2.70"
 description = "WUP (What's Up) - Intelligent file watcher for regression testing in large projects"
 readme = "README.md"
 requires-python = ">=3.10"

wup-0.2.70/tests/test_multi_project.py

@@ -0,0 +1,117 @@
+"""Tests for simultaneous multi-project watching."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from wup.cli import _discover_projects, _resolve_project_paths
+from wup.config import detect_watch_paths, get_default_config
+from wup.core import WupWatcher
+from wup.models.config import ProjectConfig, WatchConfig, WupConfig
+from wup.multi import MultiProjectWatcher
+
+
+def _make_project(root: Path, name: str, src: str = "src") -> Path:
+    """Create a project dir with a wup.yaml and one watchable source folder."""
+    proj = root / name
+    (proj / src).mkdir(parents=True)
+    (proj / src / "main.py").write_text("print('hi')\n")
+    (proj / "wup.yaml").write_text(
+        f"project:\n  name: {name}\nwatch:\n  paths:\n  - {src}/**\n"
+    )
+    return proj
+
+
+def _watcher(project_root: Path, paths: list[str]) -> WupWatcher:
+    cfg = WupConfig(
+        project=ProjectConfig(name=project_root.name),
+        watch=WatchConfig(paths=paths),
+    )
+    return WupWatcher(
+        project_root=str(project_root),
+        deps_file=str(project_root / "deps.json"),
+        config=cfg,
+    )
+
+
+def test_detect_watch_paths_uses_existing_dirs(tmp_path: Path) -> None:
+    (tmp_path / "services").mkdir()
+    (tmp_path / "lib").mkdir()
+    paths = detect_watch_paths(tmp_path)
+    assert "services/**" in paths
+    assert "lib/**" in paths
+    # A non-existent common dir is not emitted.
+    assert "app/**" not in paths
+
+
+def test_detect_watch_paths_falls_back_when_nothing_matches(tmp_path: Path) -> None:
+    assert detect_watch_paths(tmp_path) == ["app/**", "src/**", "routes/**"]
+
+
+def test_default_config_watches_only_real_dirs(tmp_path: Path) -> None:
+    (tmp_path / "services").mkdir()
+    cfg = get_default_config(tmp_path)
+    assert cfg.watch.paths == ["services/**"]
+
+
+def test_discover_finds_subprojects(tmp_path: Path) -> None:
+    _make_project(tmp_path, "alpha")
+    _make_project(tmp_path, "beta")
+    (tmp_path / "not_a_project").mkdir()  # no wup.yaml -> skipped
+
+    discovered = {p.name for p in _discover_projects(tmp_path)}
+    assert discovered == {"alpha", "beta"}
+
+
+def test_discover_skips_vendor_and_hidden(tmp_path: Path) -> None:
+    _make_project(tmp_path, "alpha")
+    _make_project(tmp_path, "node_modules")  # vendored -> skipped
+    _make_project(tmp_path, ".hidden")  # hidden -> skipped
+
+    discovered = {p.name for p in _discover_projects(tmp_path)}
+    assert discovered == {"alpha"}
+
+
+def test_resolve_paths_dedupes(tmp_path: Path) -> None:
+    _make_project(tmp_path, "alpha")
+    resolved = _resolve_project_paths(
+        [str(tmp_path / "alpha"), str(tmp_path / "alpha")], discover=False
+    )
+    assert len(resolved) == 1
+
+
+def test_prepare_observer_none_when_no_valid_paths(tmp_path: Path) -> None:
+    watcher = _watcher(tmp_path, paths=["does-not-exist/**"])
+    assert watcher.prepare_observer() is None
+
+
+def test_multi_watcher_returns_false_when_all_invalid(tmp_path: Path) -> None:
+    w1 = _watcher(tmp_path, paths=["missing-a/**"])
+    w2 = _watcher(tmp_path, paths=["missing-b/**"])
+    assert MultiProjectWatcher([w1, w2]).start_watching() is False
+
+
+def test_multi_watcher_starts_observers_for_valid_projects(tmp_path: Path) -> None:
+    alpha = _make_project(tmp_path, "alpha")
+    beta = _make_project(tmp_path, "beta")
+    w1 = _watcher(alpha, paths=["src/**"])
+    w2 = _watcher(beta, paths=["src/**"])
+
+    multi = MultiProjectWatcher([w1, w2])
+    observers = []
+    active = []
+    for watcher in multi.watchers:
+        watcher.start_background_tasks()
+        obs = watcher.prepare_observer()
+        if obs is not None:
+            observers.append(obs)
+            active.append(watcher)
+
+    try:
+        assert len(active) == 2
+        assert all(obs.is_alive() for obs in observers)
+    finally:
+        for obs in observers:
+            obs.stop()
+        for obs in observers:
+            obs.join()

{wup-0.2.69 → wup-0.2.70}/wup/__init__.py

@@ -7,7 +7,7 @@ WUP monitors file changes and runs intelligent regression tests using a 3-layer
 3. Detail Layer: Full tests with blame reports (only on failure)
 """
 
-__version__ = "0.2.69"
+__version__ = "0.2.70"
 __author__ = "Tom Sapletta"
 
 from .config import load_config, save_config, get_default_config

{wup-0.2.69 → wup-0.2.70}/wup/cli.py

@@ -4,7 +4,7 @@ CLI interface for WUP (What's Up) - Intelligent file watcher for regression test
 
 import asyncio
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
 
 import typer
 from rich.console import Console
@@ -13,6 +13,7 @@ from .config import find_config_file, load_config
 from .core import WupWatcher
 from .dependency_mapper import DependencyMapper
 from .models.config import WupConfig
+from .multi import MultiProjectWatcher
 from .testql_watcher import TestQLWatcher
 
 app = typer.Typer(
@@ -117,9 +118,119 @@ def _create_watcher(
     )
 
 
+def _is_project_dir(path: Path) -> bool:
+    """A directory is a WUP project if it already carries a wup.yaml/.wup.yaml."""
+    return path.is_dir() and find_config_file(path) is not None
+
+
+def _discover_projects(root: Path) -> List[Path]:
+    """
+    Expand a monorepo root into its immediate sub-projects.
+
+    Returns child directories that already have a wup.yaml, sorted by name. The
+    root itself is included when it, too, has a config. Hidden directories and
+    common vendor/build folders are skipped.
+    """
+    skip = {"node_modules", "__pycache__", ".git", ".venv", "venv", "dist", "build"}
+    found: List[Path] = []
+    if _is_project_dir(root):
+        found.append(root)
+    for child in sorted(root.iterdir(), key=lambda p: p.name):
+        if child.name in skip or child.name.startswith("."):
+            continue
+        if _is_project_dir(child):
+            found.append(child)
+    return found
+
+
+def _resolve_project_paths(projects: List[str], discover: bool) -> List[Path]:
+    """
+    Turn raw CLI project arguments into a de-duplicated list of project roots.
+
+    With ``discover`` each argument is expanded into its sub-projects (see
+    :func:`_discover_projects`); without it each argument is taken as-is.
+    """
+    resolved: List[Path] = []
+    seen = set()
+    for raw in projects:
+        base = Path(raw).resolve()
+        if not base.exists():
+            console.print(f"[red]Error: Project path '{raw}' does not exist[/red]")
+            raise typer.Exit(1)
+        candidates = _discover_projects(base) if discover else [base]
+        if discover and not candidates:
+            console.print(
+                f"[yellow]No wup.yaml projects discovered under '{raw}'[/yellow]"
+            )
+        for path in candidates:
+            if path not in seen:
+                seen.add(path)
+                resolved.append(path)
+    return resolved
+
+
+def _build_project_watcher(
+    project_path: Path,
+    config_path: Optional[Path],
+    *,
+    mode: str,
+    deps_file: str,
+    cpu_throttle: float,
+    debounce: int,
+    cooldown: int,
+    scenarios_dir: Optional[str],
+    testql_bin: str,
+    browser_service_url: Optional[str],
+    track_dir: str,
+    quick_limit: int,
+    probe_interval: Optional[int],
+    print_header: bool = True,
+) -> WupWatcher:
+    """Prepare a single project: auto-config, load, refresh manifest, build watcher."""
+    # Auto-generate config if it doesn't exist
+    if not find_config_file(project_path) and not (config_path and config_path.exists()):
+        console.print(
+            f"[cyan]🔍 No wup.yaml in {project_path.name} - auto-detecting project type...[/cyan]"
+        )
+        _auto_generate_config(project_path, mode)
+        console.print(f"[green]✓ Auto-generated wup.yaml for {project_path.name}[/green]")
+        console.print()
+
+    wup_config = _load_watch_config(project_path, config_path, probe_interval, mode)
+    effective_scenarios_dir = scenarios_dir or wup_config.testql.scenario_dir
+
+    if print_header:
+        _print_watch_header(wup_config, cpu_throttle, debounce, cooldown, config_path)
+
+    cfg_path = config_path if config_path and config_path.exists() else find_config_file(project_path)
+    _refresh_monitoring_manifest(project_path, wup_config, cfg_path)
+
+    # Resolve a relative deps file against the project root so each project keeps
+    # its own dependency map (for `wup watch .` this equals the CWD, unchanged).
+    deps_path = deps_file if Path(deps_file).is_absolute() else str(project_path / deps_file)
+
+    return _create_watcher(
+        mode=mode,
+        project_path=project_path,
+        deps_file=deps_path,
+        cpu_throttle=cpu_throttle,
+        debounce=debounce,
+        cooldown=cooldown,
+        scenarios_dir=effective_scenarios_dir,
+        testql_bin=testql_bin,
+        browser_service_url=browser_service_url,
+        track_dir=track_dir,
+        quick_limit=quick_limit,
+        config=wup_config,
+    )
+
+
 @app.command()
 def watch(
-    project: str = typer.Argument(".", help="Path to the project root directory"),
+    projects: Optional[List[str]] = typer.Argument(
+        None,
+        help="One or more project root directories (default: current directory)",
+    ),
     deps_file: str = typer.Option("deps.json", "--deps", "-d", help="Path to dependency map file"),
     cpu_throttle: float = typer.Option(0.8, "--cpu-throttle", "-c", help="CPU usage threshold (0.0-1.0)"),
     debounce: int = typer.Option(2, "--debounce", "-b", help="Debounce time in seconds"),
@@ -144,10 +255,21 @@ def watch(
         "--probe-interval",
         help="Periodic live HTTP probes in seconds (default: 60 in testql mode, or testql.probe_interval_s from wup.yaml; use 0 to disable)",
     ),
+    discover: bool = typer.Option(
+        False,
+        "--discover",
+        "-D",
+        help="Treat each given path as a monorepo root and watch every sub-directory that has a wup.yaml",
+    ),
     config: Optional[str] = typer.Option(None, "--config", "-C", help="Path to wup.yaml config file"),
 ):
     """
-    Watch project for file changes and run regression tests.
+    Watch one or more projects for file changes and run regression tests.
+
+    Pass several project directories to test them **simultaneously**
+    (``wup watch proj-a proj-b``), or use ``--discover`` to expand a monorepo
+    root into every sub-directory that already has a wup.yaml. With no argument
+    the current directory is watched.
 
     Defaults (no extra flags): ``--mode testql`` and live probes every **60s**
     (unless ``testql.probe_interval_s`` is set in wup.yaml). Use
@@ -155,51 +277,62 @@ def watch(
 
     If wup.yaml doesn't exist, it will be auto-generated based on project detection.
     """
-    project_path = Path(project).resolve()
+    raw_projects = list(projects) if projects else ["."]
+    project_paths = _resolve_project_paths(raw_projects, discover)
 
-    if not project_path.exists():
-        console.print(f"[red]Error: Project path '{project}' does not exist[/red]")
+    if not project_paths:
+        console.print("[red]No projects to watch[/red]")
         raise typer.Exit(1)
 
-    config_path = Path(config) if config else None
-
-    # Auto-generate config if it doesn't exist
-    if not find_config_file(project_path):
-        console.print("[cyan]🔍 No wup.yaml found - auto-detecting project type...[/cyan]")
-        _auto_generate_config(project_path, mode)
-        console.print("[green]✓ Auto-generated wup.yaml configuration[/green]")
-        console.print()
-
-    wup_config = _load_watch_config(project_path, config_path, probe_interval, mode)
-    effective_scenarios_dir = scenarios_dir or wup_config.testql.scenario_dir
-
-    _print_watch_header(wup_config, cpu_throttle, debounce, cooldown, config_path)
-
-    cfg_path = config_path if config_path and config_path.exists() else find_config_file(project_path)
-    _refresh_monitoring_manifest(project_path, wup_config, cfg_path)
+    # --config only applies to a single explicit project.
+    single = len(project_paths) == 1
+    config_path = Path(config) if (config and single) else None
+    if config and not single:
+        console.print(
+            "[yellow]--config is ignored when watching multiple projects; "
+            "each project uses its own wup.yaml[/yellow]"
+        )
 
-    watcher = _create_watcher(
-        mode=mode,
-        project_path=project_path,
-        deps_file=deps_file,
-        cpu_throttle=cpu_throttle,
-        debounce=debounce,
-        cooldown=cooldown,
-        scenarios_dir=effective_scenarios_dir,
-        testql_bin=testql_bin,
-        browser_service_url=browser_service_url,
-        track_dir=track_dir,
-        quick_limit=quick_limit,
-        config=wup_config,
-    )
+    watchers = [
+        _build_project_watcher(
+            project_path,
+            config_path,
+            mode=mode,
+            deps_file=deps_file,
+            cpu_throttle=cpu_throttle,
+            debounce=debounce,
+            cooldown=cooldown,
+            scenarios_dir=scenarios_dir,
+            testql_bin=testql_bin,
+            browser_service_url=browser_service_url,
+            track_dir=track_dir,
+            quick_limit=quick_limit,
+            probe_interval=probe_interval,
+        )
+        for project_path in project_paths
+    ]
+
+    if single:
+        watcher = watchers[0]
+        if dashboard:
+            console.print("[green]Starting watcher with live dashboard...[/green]")
+            asyncio.run(watcher.run_with_dashboard())
+        else:
+            console.print("[green]Starting watcher...[/green]")
+            if watcher.start_watching() is False:
+                raise typer.Exit(1)
+        return
 
     if dashboard:
-        console.print("[green]Starting watcher with live dashboard...[/green]")
-        asyncio.run(watcher.run_with_dashboard())
-    else:
-        console.print("[green]Starting watcher...[/green]")
-        if watcher.start_watching() is False:
-            raise typer.Exit(1)
+        console.print(
+            "[yellow]--dashboard is not supported with multiple projects; "
+            "running without dashboard[/yellow]"
+        )
+    console.print(
+        f"[green]Starting {len(watchers)} watchers simultaneously...[/green]"
+    )
+    if MultiProjectWatcher(watchers, console=console).start_watching() is False:
+        raise typer.Exit(1)
 
 
 def _auto_generate_config(project_path: Path, mode: str):

{wup-0.2.69 → wup-0.2.70}/wup/config.py

@@ -389,25 +389,45 @@ def validate_config(raw: dict) -> WupConfig:
     )
 
 
+# Common source-directory names, in priority order, used to seed watch paths
+# for an auto-generated config. Only directories that actually exist are kept,
+# so the generated wup.yaml doesn't point at paths that were never there.
+_DEFAULT_SOURCE_DIRS = [
+    "app", "src", "routes", "services", "lib", "packages", "pkg", "internal", "cmd",
+]
+
+
+def detect_watch_paths(project_root: Path) -> list:
+    """
+    Pick watch-path globs for a project by probing for common source directories.
+
+    Returns ``["<dir>/**", ...]`` for every well-known source directory that
+    exists under ``project_root``. Falls back to the classic app/src/routes
+    guess only when none are found, so a brand-new project still gets a config.
+    """
+    found = [f"{name}/**" for name in _DEFAULT_SOURCE_DIRS if (project_root / name).is_dir()]
+    return found or ["app/**", "src/**", "routes/**"]
+
+
 def get_default_config(project_root: Path) -> WupConfig:
     """
     Get default configuration when no config file exists.
-    
+
     Args:
         project_root: Path to project root directory
-        
+
     Returns:
         Default WupConfig object
     """
     project_name = project_root.name
-    
+
     return WupConfig(
         project=ProjectConfig(
             name=project_name,
             description=f"Auto-generated config for {project_name}"
         ),
         watch=WatchConfig(
-            paths=["app/**", "src/**", "routes/**"],
+            paths=detect_watch_paths(project_root),
             exclude_patterns=["*.md", "*.txt", "tests/**", "node_modules/**"]
         ),
         services=[],

{wup-0.2.69 → wup-0.2.70}/wup/core.py

@@ -566,18 +566,31 @@ class WupWatcher:
                 return observer
             raise
 
-    def start_watching(self, watch_paths: Optional[List[str]] = None) -> bool:
+    def start_background_tasks(self) -> None:
         """
-        Start watching for file changes.
+        Hook for subclasses to start background threads before watching begins.
+
+        The base watcher has nothing to start; TestQLWatcher overrides this to
+        launch its periodic live-probe thread. Coordinators that run several
+        watchers at once (see :class:`~wup.multi.MultiProjectWatcher`) call this
+        on each watcher so background probes fire regardless of who owns the
+        main loop.
+        """
+
+    def prepare_observer(self, watch_paths: Optional[List[str]] = None):
+        """
+        Set up and start the filesystem observer without entering a blocking loop.
+
+        Splitting this out of :meth:`start_watching` lets a coordinator drive
+        several watchers from a single loop (multi-project mode).
 
         Args:
-            watch_paths: List of paths to watch (default: from config or common source directories)
+            watch_paths: List of paths to watch (default: from config or common
+                source directories)
 
         Returns:
-            False when no valid paths could be watched (configuration error —
-            CLI turns this into a non-zero exit so supervisors notice instead
-            of treating a watcher that never watched as a clean run),
-            True after a graceful interrupt.
+            The started observer, or ``None`` when no valid paths could be
+            watched (configuration error).
         """
         if watch_paths is None:
             watch_paths = self.build_watched_paths()
@@ -586,12 +599,38 @@ class WupWatcher:
         watch_paths = [p for p in watch_paths if Path(p).exists()]
 
         if not watch_paths:
-            self.console.print("[red]No valid paths to watch[/red]")
-            return False
+            self.console.print(
+                f"[red]No valid paths to watch[/red] "
+                f"[dim](project: {self.config.project.name})[/dim]"
+            )
+            return None
 
         event_handler = WupEventHandler(self)
         observer = self._create_and_start_observer(event_handler, watch_paths)
-        self.console.print(f"[green]🕵️  Watching: {', '.join(watch_paths)}[/green]")
+        self.console.print(
+            f"[green]🕵️  Watching ({self.config.project.name}): "
+            f"{', '.join(watch_paths)}[/green]"
+        )
+        return observer
+
+    def start_watching(self, watch_paths: Optional[List[str]] = None) -> bool:
+        """
+        Start watching for file changes.
+
+        Args:
+            watch_paths: List of paths to watch (default: from config or common source directories)
+
+        Returns:
+            False when no valid paths could be watched (configuration error —
+            CLI turns this into a non-zero exit so supervisors notice instead
+            of treating a watcher that never watched as a clean run),
+            True after a graceful interrupt.
+        """
+        self.start_background_tasks()
+
+        observer = self.prepare_observer(watch_paths)
+        if observer is None:
+            return False
 
         try:
             while True:
@@ -636,9 +675,11 @@ class WupWatcher:
     
     async def run_with_dashboard(self):
         """Run watcher with live dashboard."""
+        self.start_background_tasks()
+
         watch_paths = self.build_watched_paths()
         watch_paths = [p for p in watch_paths if Path(p).exists()]
-        
+
         event_handler = WupEventHandler(self)
         observer = self._create_and_start_observer(event_handler, watch_paths)