feat(cyt_mcp): enhance workspace tool hydration and background processing

- Introduced a new function `_workspace_scope_disk_tools` to load workspace-scoped disk catalogs, improving tool retrieval logic.
- Updated `_hydrate_missing_servers_from_disk` to merge tools from both merged disk and workspace disk sources for better server hydration.
- Refactored `_hydrate_server_runtime_caches` to return a boolean indicating hydration success, allowing for conditional cache pushes.
- Added a new threaded function `_schedule_hydrate_hook_caches_from_registration` to run hook cache hydration asynchronously, improving performance during catalog registration.
- Increased `PUSH_TIMEOUT_SECONDS` to 30 to accommodate larger workspace catalogs during hook daemon operations.
- Enhanced unit tests to validate new functionality and ensure resilience against stale tool registrations.

Author: qdrddr

src/cyt/cyt_mcp/catalog.py

@@ -380,6 +380,42 @@ def _disk_catalog_tools(cache_key: _CytMcpCacheKey) -> list[dict[str, Any]]:
     return _normalize_tools_list(tools)
 
 
+def _workspace_scope_disk_tools(cache_key: _CytMcpCacheKey) -> list[dict[str, Any]]:
+    """Load ws-scoped disk catalog (separate slug from merged hook injection cache)."""
+    if not cache_key.workspace:
+        return []
+    ws = Path(cache_key.workspace).expanduser()
+    agg_path = ws / ".agents/cyt/config/mcp-config.yaml"
+    if not agg_path.is_file():
+        from cyt_mcp.workspace_catalog import workspace_aggregator_path
+
+        alt = workspace_aggregator_path(ws, cache_key.agent)
+        if alt is None or not alt.is_file():
+            return []
+        agg_path = alt
+    try:
+        from cyt_mcp.catalog_build import disk_catalog_slug_for_config
+        from cyt_mcp.config import load_aggregator_config
+
+        config = load_aggregator_config(
+            agent=cache_key.agent,
+            aggregator_path=agg_path,
+            workspace_folder=ws,
+        )
+        if config.catalog_scope != "workspace":
+            return []
+        slug = disk_catalog_slug_for_config(config)
+    except (ValueError, OSError):
+        return []
+    envelope = read_disk_catalog(slug)
+    if envelope is None:
+        return []
+    tools = envelope.get("tools")
+    if not isinstance(tools, list):
+        return []
+    return _normalize_tools_list(tools)
+
+
 def _server_keys_for_tools(tools: Sequence[dict[str, Any]]) -> set[str]:
     return {key for key in (_tool_server_key(tool) for tool in tools) if key}
 
@@ -516,16 +552,23 @@ def _hydrate_missing_servers_from_disk(
     cache_key: _CytMcpCacheKey,
     tools: list[dict[str, Any]],
 ) -> list[dict[str, Any]]:
-    disk_tools = _disk_catalog_tools(cache_key)
-    if not disk_tools:
+    merged_disk_tools = _disk_catalog_tools(cache_key)
+    ws_disk_tools = _workspace_scope_disk_tools(cache_key)
+    disk_sources: list[list[dict[str, Any]]] = []
+    if merged_disk_tools:
+        disk_sources.append(merged_disk_tools)
+    if ws_disk_tools:
+        disk_sources.append(ws_disk_tools)
+    if not disk_sources:
         return tools
-    missing_servers = _server_keys_for_tools(disk_tools) - _server_keys_for_tools(tools)
+    all_disk_tools = [tool for source in disk_sources for tool in source]
+    missing_servers = _server_keys_for_tools(all_disk_tools) - _server_keys_for_tools(tools)
     configured_servers = _configured_server_keys_for_hydration(cache_key)
     if configured_servers:
         missing_servers = missing_servers & configured_servers
     if not missing_servers:
         return tools
-    merged = _preserve_tools_for_servers(tools, [disk_tools], missing_servers)
+    merged = _preserve_tools_for_servers(tools, disk_sources, missing_servers)
     if len(merged) > len(tools):
         logger.info(
             "cyt-mcp catalog hydrated %d tools from disk for backends: %s",

src/cyt/hook/catalog_registry.py

@@ -480,6 +480,24 @@ def _hydrate_hook_caches_from_registration(
         logger.warning("hook cache hydration after catalog register failed: %s", exc)
 
 
+def _schedule_hydrate_hook_caches_from_registration(
+    tools: list[dict[str, Any]],
+    *,
+    agent: str,
+    workspace_root: str,
+) -> None:
+    """Run hook cache hydration off the catalog register HTTP request thread."""
+    if not tools:
+        return
+    thread = threading.Thread(
+        target=_hydrate_hook_caches_from_registration,
+        kwargs={"tools": tools, "agent": agent, "workspace_root": workspace_root},
+        name="cyt-catalog-register-hydrate",
+        daemon=True,
+    )
+    thread.start()
+
+
 def _register_full_tools(
     existing: _CatalogRegistration | None,
     *,
@@ -577,7 +595,7 @@ def register_catalog(payload: dict[str, Any]) -> RegisterResult:
         from cyt.hook.active_workspace import touch_active_workspace
 
         touch_active_workspace(agent, workspace_root)
-        _hydrate_hook_caches_from_registration(
+        _schedule_hydrate_hook_caches_from_registration(
             tools,
             agent=agent,
             workspace_root=workspace_root,

src/cyt_mcp/cli.py

@@ -246,10 +246,10 @@ def _start_pairing_repair_thread(config: AggregatorConfig) -> None:
 def _hydrate_server_runtime_caches(
     cache: RuntimeToolCache,
     config: AggregatorConfig,
-) -> None:
+) -> bool:
     from cyt_mcp.catalog_build import hydrate_runtime_cache
 
-    hydrate_runtime_cache(cache, config)
+    return hydrate_runtime_cache(cache, config)
 
 
 def _make_background_catalog_refresh(
@@ -329,7 +329,13 @@ async def _run_server(config: AggregatorConfig, *, aggregator_path: Path | None
         from cyt.hook.active_workspace import touch_active_workspace
 
         touch_active_workspace(config.agent, config.workspace_root)
-    _hydrate_server_runtime_caches(cache, config)
+    hydrated = _hydrate_server_runtime_caches(cache, config)
+    if bool(cache.snapshot()):
+        # Disk/registry hydrate can warm the cache before stdio starts; still push so
+        # hook inject/tiers see ws tools without waiting for a full backend refresh.
+        from cyt_mcp.hook_daemon_push import schedule_catalog_push
+
+        schedule_catalog_push(cache, config)
     background_catalog_refresh = _make_background_catalog_refresh(
         cache=cache,
         config=config,

src/cyt_mcp/hook_daemon_push.py

@@ -27,7 +27,9 @@
 
 REGISTER_PATH = "/hook/catalog/register"
 DEREGISTER_PATH = "/hook/catalog/deregister"
-PUSH_TIMEOUT_SECONDS = 2.0
+# Full ws catalogs (100+ tools) can exceed 2s because the hook daemon rebuilds
+# master caches synchronously during /hook/catalog/register.
+PUSH_TIMEOUT_SECONDS = 30.0
 
 _RETRY_DELAYS_SECONDS = (1.0, 2.0, 5.0, 10.0)
 

src/tests/unit/test_cyt_mcp_catalog_resilience.py

@@ -345,3 +345,73 @@ def test_disk_snapshot_hydrate_restores_ws_tools_after_registry_clear(
     assert loaded == 1
     merged = catalog_for_hook("cursor", workspace, allow_stale=True)
     assert {tool["name"] for tool in merged} == {tool["name"] for tool in tools}
+
+
+def test_hook_catalog_hydrates_ws_disk_when_merged_disk_is_usr_only(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Regression: stale merged hook disk must not hide ws-layer disk tools."""
+    from cyt.cyt_mcp.catalog import (
+        _cache_key_for_config,
+        _write_catalog_disk,
+        get_cyt_mcp_catalog,
+    )
+    from cyt.cyt_mcp.catalog_disk import raw_catalog_content_hash, write_disk_catalog
+    from cyt_mcp.catalog_build import disk_catalog_slug_for_config
+    from cyt_mcp.config import load_aggregator_config
+    from tests.support.cyt_mcp_catalog_resilience_fixtures import (
+        RESILIENCE_MCP_SERVER_KEYS,
+        clear_cyt_mcp_memory_catalog_state,
+    )
+
+    workspace = materialize_workspace(tmp_path)
+    cyt_config_dir = workspace / ".agents" / "cyt" / "config"
+    (cyt_config_dir / "mcp-config.yaml").write_text(
+        "\n".join(
+            [
+                "default_agent: cursor",
+                "agents:",
+                "  cursor: mcp/cursor.json",
+                "catalog_scope: workspace",
+                "transport: stdio",
+            ],
+        ),
+        encoding="utf-8",
+    )
+    (cyt_config_dir / "mcp" / "cursor.json").write_text(
+        json.dumps({"mcpServers": {key: {"command": key} for key in RESILIENCE_MCP_SERVER_KEYS}}),
+        encoding="utf-8",
+    )
+    cache_dir = tmp_path / "cyt-mcp-catalog"
+    monkeypatch.setattr("cyt.cyt_mcp.catalog_disk.cyt_mcp_catalog_cache_dir", lambda: cache_dir)
+
+    ws_tools = load_ws_tools_catalog()
+    usr_tools = load_usr_tools_catalog()
+    config = load_aggregator_config(
+        agent="cursor",
+        aggregator_path=cyt_config_dir / "mcp-config.yaml",
+        workspace_folder=workspace,
+    )
+    ws_slug = disk_catalog_slug_for_config(config)
+    assert ws_slug is not None
+    write_disk_catalog(
+        ws_slug,
+        agent="cursor",
+        tools=ws_tools,
+        content_hash=raw_catalog_content_hash(ws_tools),
+    )
+
+    hook_config = cyt_mcp_hook_config(workspace, db_path=tmp_path / "tiers.db")
+    merged_key = _cache_key_for_config(hook_config)
+    _write_catalog_disk(merged_key, usr_tools)
+
+    clear_catalog_registry(purge_disk_snapshot=False)
+    clear_cyt_mcp_memory_catalog_state()
+    patch_daemon_catalog_status(monkeypatch, [])
+
+    catalog = get_cyt_mcp_catalog(hook_config, blocking=True, force=True)
+    assert catalog is not None
+    names = {tool["name"] for tool in catalog}
+    assert {tool["name"] for tool in ws_tools if tool.get("server_key")}.issubset(names)
+    assert {tool["name"] for tool in usr_tools}.issubset(names)

src/tests/unit/test_cyt_mcp_cli.py

@@ -56,8 +56,9 @@ def test_run_server_stdio_skips_background_refresh_when_cache_warmed() -> None:
     config = _stdio_config()
     refresh_calls: list[str] = []
 
-    def _hydrate_warm(cache: RuntimeToolCache, _config: object) -> None:
+    def _hydrate_warm(cache: RuntimeToolCache, _config: object) -> bool:
         cache.replace([{"name": "tool-a"}])
+        return True
 
     async def _refresh(*_args: object, **_kwargs: object) -> None:
         refresh_calls.append("refresh")
@@ -72,13 +73,15 @@ async def _run_async(*_args: object, **_kwargs: object) -> None:
         patch("cyt_mcp.catalog_build.refresh_catalog_cache", side_effect=_refresh),
         patch("cyt_mcp.hook_daemon_push.register_push_context"),
         patch("cyt_mcp.hook_daemon_push.deregister_catalog_push"),
+        patch("cyt_mcp.hook_daemon_push.schedule_catalog_push") as schedule_push,
     ):
         server = AsyncMock()
         build.return_value = (server, None, _mock_coordinator())
         server.run_async = AsyncMock(side_effect=_run_async)
         result = asyncio.run(_run_server(config))
     assert result == 0
     assert refresh_calls == []
+    schedule_push.assert_called_once()
 
 
 def test_run_search_wires_refresh_and_lookup(

src/tests/unit/test_empty_home_cache_bootstrap.py

@@ -147,7 +147,15 @@ def test_register_catalog_eager_hydrates_master_without_warm(
 
     register_ws_catalog(pack.workspace, pack.tools)
 
-    catalog = get_master_tool_catalog(config, blocking=False) or []
+    import time
+
+    deadline = time.monotonic() + 5.0
+    catalog: list[dict[str, object]] = []
+    while time.monotonic() < deadline:
+        catalog = get_master_tool_catalog(config, blocking=False) or []
+        if len(catalog) >= pack.minimum_master_catalog_tools:
+            break
+        time.sleep(0.05)
     names = {tool["name"] for tool in catalog}
     assert len(catalog) >= pack.minimum_master_catalog_tools
     assert set(pack.expected_tool_names).issubset(names)