cocoindex-code 0.2.34__tar.gz → 0.2.36__tar.gz

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.34
+Version: 0.2.36
 Summary: MCP server for indexing and querying codebases using CocoIndex
 Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
 Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
@@ -121,6 +121,17 @@ The agent uses semantic search automatically when it would be helpful. You can a
 
 Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and other skill-compatible agents.
 
+#### Claude Code plugin marketplace
+
+For Claude Code users, this repository is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the skill from inside Claude Code with:
+
+```text
+/plugin marketplace add Roxabi/cocoindex-code
+/plugin install cocoindex-code@cocoindex-code
+```
+
+This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates.
+
 ### MCP Server
 
 Alternatively, use `ccc mcp` to run as an MCP server:
@@ -424,6 +435,8 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 
 ## Configuration
 
+For a detailed guide on choosing and configuring embedding models, see [EMBEDDINGS.md](EMBEDDINGS.md).
+
 Configuration lives in two YAML files, both created automatically by `ccc init`.
 
 ### User Settings (`~/.cocoindex_code/global_settings.yml`)
@@ -781,6 +794,33 @@ Using uv (install or upgrade):
 uv tool install --upgrade cocoindex-code
 ```
 
+### `MDB_MAP_FULL: Environment mapsize limit reached`
+
+The index is stored in an LMDB database whose maximum size is fixed when the daemon starts. The default ceiling is **4 GiB**, which is plenty for most projects but can be exhausted by very large codebases (tens of thousands of files), especially with high-dimensional embedding models like `nomic-ai/CodeRankEmbed`.
+
+Raise the ceiling with the `COCOINDEX_LMDB_MAP_SIZE` environment variable (value in **bytes**). LMDB only grows the file as data is written, so a high limit doesn't pre-allocate disk — it's safe to set it generously:
+
+```yaml
+# ~/.cocoindex_code/global_settings.yml
+envs:
+  COCOINDEX_LMDB_MAP_SIZE: "34359738368"   # 32 GiB (= 32 * 1024^3)
+```
+
+Or, if you prefer to set it in your shell environment (the daemon inherits it):
+
+```bash
+export COCOINDEX_LMDB_MAP_SIZE=$((32 * 1024 * 1024 * 1024))   # 32 GiB
+```
+
+The map size is read when the daemon starts, so restart it to pick up the change, then re-index:
+
+```bash
+ccc daemon restart
+ccc index
+```
+
+> This manual step is temporary. Once [cocoindex#2108](https://github.com/cocoindex-io/cocoindex/issues/2108) lands, the map size grows automatically when needed and `COCOINDEX_LMDB_MAP_SIZE` won't be necessary.
+
 ## Legacy: Environment Variables
 
 If you previously configured `cocoindex-code` via environment variables, the `cocoindex-code` MCP command still reads them and auto-migrates to YAML settings on first run. We recommend switching to the YAML settings for new setups.
@@ -808,18 +848,39 @@ export COCOINDEX_DISABLE_USAGE_TRACKING=1
 ## Large codebase / Enterprise
 [CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
 
+> Indexing a very large codebase and hitting `MDB_MAP_FULL`? Raise the LMDB map size — see [`MDB_MAP_FULL: Environment mapsize limit reached`](#mdb_map_full-environment-mapsize-limit-reached) under Troubleshooting.
+
 If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
 
 ## Contributing
 
-We welcome contributions! Before you start, please install the [pre-commit](https://pre-commit.com/) hooks so that linting, formatting, type checking, and tests run automatically before each commit:
+We welcome contributions! This project uses [uv](https://docs.astral.sh/uv/getting-started/installation/) for development, and every PR is gated on the same lint, format, type-check, and test suite in CI. **Please run these checks locally before opening a PR** — failing pre-commit checks are the most common cause of red CI on incoming PRs.
+
+### 1. Install the dev dependencies
+
+After installing [uv](https://docs.astral.sh/uv/getting-started/installation/), sync the project. This installs everything the checks need — including [prek](https://github.com/j178/prek), a fast pre-commit runner, plus Ruff, mypy, and pytest:
 
 ```bash
-pip install pre-commit
-pre-commit install
+uv sync
 ```
 
-This catches common issues — trailing whitespace, lint errors (Ruff), type errors (mypy), and test failures — before they reach CI.
+### 2. Run all checks before every PR
+
+Run the full hook suite across all files — this is exactly what CI runs:
+
+```bash
+uv run prek run --all-files
+```
+
+It runs trailing-whitespace/end-of-file fixes, Ruff lint (`--fix`) and format, `uv.lock` validation, mypy type checking, and the pytest suite. Fix anything it reports (Ruff auto-fixes most lint/format issues for you), re-run until it passes, then push.
+
+### 3. (Optional) Run automatically on each commit
+
+To have the same checks run on every `git commit`, install the git hook once:
+
+```bash
+uv run prek install
+```
 
 For more details, see our [contributing guide](https://cocoindex.io/docs/contributing/guide).
 

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/README.md

@@ -77,6 +77,17 @@ The agent uses semantic search automatically when it would be helpful. You can a
 
 Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and other skill-compatible agents.
 
+#### Claude Code plugin marketplace
+
+For Claude Code users, this repository is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the skill from inside Claude Code with:
+
+```text
+/plugin marketplace add Roxabi/cocoindex-code
+/plugin install cocoindex-code@cocoindex-code
+```
+
+This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates.
+
 ### MCP Server
 
 Alternatively, use `ccc mcp` to run as an MCP server:
@@ -380,6 +391,8 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 
 ## Configuration
 
+For a detailed guide on choosing and configuring embedding models, see [EMBEDDINGS.md](EMBEDDINGS.md).
+
 Configuration lives in two YAML files, both created automatically by `ccc init`.
 
 ### User Settings (`~/.cocoindex_code/global_settings.yml`)
@@ -737,6 +750,33 @@ Using uv (install or upgrade):
 uv tool install --upgrade cocoindex-code
 ```
 
+### `MDB_MAP_FULL: Environment mapsize limit reached`
+
+The index is stored in an LMDB database whose maximum size is fixed when the daemon starts. The default ceiling is **4 GiB**, which is plenty for most projects but can be exhausted by very large codebases (tens of thousands of files), especially with high-dimensional embedding models like `nomic-ai/CodeRankEmbed`.
+
+Raise the ceiling with the `COCOINDEX_LMDB_MAP_SIZE` environment variable (value in **bytes**). LMDB only grows the file as data is written, so a high limit doesn't pre-allocate disk — it's safe to set it generously:
+
+```yaml
+# ~/.cocoindex_code/global_settings.yml
+envs:
+  COCOINDEX_LMDB_MAP_SIZE: "34359738368"   # 32 GiB (= 32 * 1024^3)
+```
+
+Or, if you prefer to set it in your shell environment (the daemon inherits it):
+
+```bash
+export COCOINDEX_LMDB_MAP_SIZE=$((32 * 1024 * 1024 * 1024))   # 32 GiB
+```
+
+The map size is read when the daemon starts, so restart it to pick up the change, then re-index:
+
+```bash
+ccc daemon restart
+ccc index
+```
+
+> This manual step is temporary. Once [cocoindex#2108](https://github.com/cocoindex-io/cocoindex/issues/2108) lands, the map size grows automatically when needed and `COCOINDEX_LMDB_MAP_SIZE` won't be necessary.
+
 ## Legacy: Environment Variables
 
 If you previously configured `cocoindex-code` via environment variables, the `cocoindex-code` MCP command still reads them and auto-migrates to YAML settings on first run. We recommend switching to the YAML settings for new setups.
@@ -764,18 +804,39 @@ export COCOINDEX_DISABLE_USAGE_TRACKING=1
 ## Large codebase / Enterprise
 [CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
 
+> Indexing a very large codebase and hitting `MDB_MAP_FULL`? Raise the LMDB map size — see [`MDB_MAP_FULL: Environment mapsize limit reached`](#mdb_map_full-environment-mapsize-limit-reached) under Troubleshooting.
+
 If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
 
 ## Contributing
 
-We welcome contributions! Before you start, please install the [pre-commit](https://pre-commit.com/) hooks so that linting, formatting, type checking, and tests run automatically before each commit:
+We welcome contributions! This project uses [uv](https://docs.astral.sh/uv/getting-started/installation/) for development, and every PR is gated on the same lint, format, type-check, and test suite in CI. **Please run these checks locally before opening a PR** — failing pre-commit checks are the most common cause of red CI on incoming PRs.
+
+### 1. Install the dev dependencies
+
+After installing [uv](https://docs.astral.sh/uv/getting-started/installation/), sync the project. This installs everything the checks need — including [prek](https://github.com/j178/prek), a fast pre-commit runner, plus Ruff, mypy, and pytest:
 
 ```bash
-pip install pre-commit
-pre-commit install
+uv sync
 ```
 
-This catches common issues — trailing whitespace, lint errors (Ruff), type errors (mypy), and test failures — before they reach CI.
+### 2. Run all checks before every PR
+
+Run the full hook suite across all files — this is exactly what CI runs:
+
+```bash
+uv run prek run --all-files
+```
+
+It runs trailing-whitespace/end-of-file fixes, Ruff lint (`--fix`) and format, `uv.lock` validation, mypy type checking, and the pytest suite. Fix anything it reports (Ruff auto-fixes most lint/format issues for you), re-run until it passes, then push.
+
+### 3. (Optional) Run automatically on each commit
+
+To have the same checks run on every `git commit`, install the git hook once:
+
+```bash
+uv run prek install
+```
 
 For more details, see our [contributing guide](https://cocoindex.io/docs/contributing/guide).
 

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/src/cocoindex_code/__init__.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 import os
 from typing import TYPE_CHECKING, Any
 
@@ -11,8 +10,6 @@ from typing import TYPE_CHECKING, Any
 # init time). See cocoindex-io/cocoindex#1992.
 os.environ.setdefault("COCOINDEX_APPLICATION_FOR_TRACKING", "cocoindex-code")
 
-logging.basicConfig(level=logging.WARNING)
-
 from ._version import __version__  # noqa: E402
 
 if TYPE_CHECKING:

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.34'
-__version_tuple__ = version_tuple = (0, 2, 34)
+__version__ = version = '0.2.36'
+__version_tuple__ = version_tuple = (0, 2, 36)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/src/cocoindex_code/cli.py

@@ -321,12 +321,35 @@ def remove_from_gitignore(project_root: Path) -> None:
 _LITELLM_MODELS_URL = "https://docs.litellm.ai/docs/embedding/supported_embedding"
 
 
+def _st_model_rejection_reason(model: str) -> str | None:
+    """Why ``model`` can't be a sentence-transformers model, or None if it's fine.
+
+    sentence-transformers loads HuggingFace model ids. An ``ollama/`` prefix is a
+    LiteLLM/Ollama route that ST tries (and fails) to resolve as a HuggingFace
+    repo — the user wants the litellm provider instead (issue #181). Real
+    HuggingFace ids that contain an ``org/`` slash (``Snowflake/...``,
+    ``openai/...``) are left alone.
+    """
+    if model.strip().lower().startswith("ollama/"):
+        return (
+            "ollama/… models run via litellm, not sentence-transformers — "
+            "go back and pick the litellm provider instead."
+        )
+    return None
+
+
 def _resolve_embedding_choice(
     litellm_model_flag: str | None,
     st_installed: bool,
     tty: bool,
+    previous: EmbeddingSettings | None = None,
 ) -> EmbeddingSettings:
-    """Resolve the embedding settings per the init control-flow diagram."""
+    """Resolve the embedding settings per the init control-flow diagram.
+
+    On a retry, ``previous`` holds the choice from the last attempt; its
+    provider and model become the prompt defaults so the user only edits
+    what was wrong instead of retyping everything.
+    """
     if litellm_model_flag is not None:
         return EmbeddingSettings(provider="litellm", model=litellm_model_flag)
 
@@ -349,14 +372,15 @@ def _resolve_embedding_choice(
             "Embedding provider",
             choices=[
                 questionary.Choice(
-                    title="sentence-transformers (local, free)",
+                    title="sentence-transformers (local, free — built-in HuggingFace models)",
                     value="sentence-transformers",
                 ),
                 questionary.Choice(
-                    title="litellm (cloud, 100+ providers)",
+                    title="litellm (100+ providers — cloud APIs & local Ollama)",
                     value="litellm",
                 ),
             ],
+            default=previous.provider if previous is not None else None,
         ).ask()
     else:
         _typer.echo(
@@ -369,10 +393,16 @@ def _resolve_embedding_choice(
         raise _typer.Exit(code=1)
 
     if provider == "sentence-transformers":
-        model = questionary.text("Model name", default=DEFAULT_ST_MODEL).ask()
+        default_model = previous.model if previous is not None else DEFAULT_ST_MODEL
+        model = questionary.text(
+            "Model name",
+            default=default_model,
+            validate=lambda m: _st_model_rejection_reason(m) or True,
+        ).ask()
     elif provider == "litellm":
         _typer.echo(f"See supported LiteLLM embedding models: {_LITELLM_MODELS_URL}")
-        model = questionary.text("Model name").ask()
+        default_model = previous.model if previous is not None else ""
+        model = questionary.text("Model name", default=default_model).ask()
     else:
         _typer.echo(f"Error: unknown provider {provider!r}", err=True)
         raise _typer.Exit(code=1)
@@ -392,13 +422,14 @@ def _ok_fail_tag(ok: bool) -> str:
     return _click.style("[FAIL]", fg="red", bold=True)
 
 
-def _run_init_model_check(settings_path: Path) -> None:
-    """Ask the daemon to test the embedding model; print results and a hint on failure.
+def _run_init_model_check() -> bool:
+    """Ask the daemon to test the embedding model; print results. Return True if all pass.
 
     Drives the check via `DoctorRequest(project_root=None)`. The daemon loads
     the model once and stays running, so the user's next `ccc index` starts
     warm. Both DaemonStartError and generic exceptions are rendered as a
-    synthetic failed DoctorCheckResult — uniform failure-output shape.
+    synthetic failed DoctorCheckResult — uniform failure-output shape. The
+    caller decides what to show on failure (retry prompt / next-steps block).
     """
     from rich.console import Console as _Console
     from rich.live import Live as _Live
@@ -426,55 +457,101 @@ def _run_init_model_check(settings_path: Path) -> None:
             )
         ]
 
-    failed = False
+    ok = True
     for r in results:
         if r.name == "done":
             continue
-        _print_doctor_result(r)
+        _print_doctor_result(r, verbose=False)
         if not r.ok:
-            failed = True
+            ok = False
+    return ok
 
-    if failed:
-        display_path = format_path_for_display(settings_path)
-        _typer.echo(
-            f"You can edit {display_path} to change the model or add API keys\n"
-            "under `envs:`. Then run `ccc doctor` to verify.",
-            err=True,
-        )
+
+def _print_init_next_steps(settings_path: Path) -> None:
+    """Prominent recovery block shown after a failed init model check."""
+    import click as _click
+
+    display_path = format_path_for_display(settings_path)
+    _typer.echo(err=True)
+    _typer.echo(_click.style("  Next steps", bold=True), err=True)
+    _typer.echo(_click.style(f"  {'─' * 38}", fg="bright_black"), err=True)
+    _typer.echo(
+        f"  1. Edit  {_click.style(display_path, fg='cyan', bold=True)}\n"
+        "     to change the model or add API keys under `envs:`.",
+        err=True,
+    )
+    _typer.echo("  2. Run  `ccc doctor`  to verify.", err=True)
+    _typer.echo()  # trailing blank before whatever init prints next
 
 
 def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
-    """Interactive global-settings setup — only runs when settings are missing."""
+    """Interactive global-settings setup — only runs when settings are missing.
+
+    Loops until the configured model passes its check or the user chooses to
+    keep the current settings. On failure we offer a retry, but only when we
+    can actually re-prompt for a different model — i.e. interactive and not
+    pinned by ``--litellm-model``; otherwise we just print the next steps.
+    """
     from .embedder_defaults import lookup_defaults
     from .shared import is_sentence_transformers_installed
 
-    embedding = _resolve_embedding_choice(
-        litellm_model_flag=litellm_model_flag,
-        st_installed=is_sentence_transformers_installed(),
-        tty=sys.stdin.isatty(),
-    )
+    st_installed = is_sentence_transformers_installed()
+    interactive = sys.stdin.isatty()
+    previous: EmbeddingSettings | None = None
 
-    # Apply curated defaults if the model is in our table.
-    indexing_defaults, query_defaults = lookup_defaults(embedding.provider, embedding.model)
-    defaults_applied = indexing_defaults is not None or query_defaults is not None
-    if defaults_applied:
-        embedding.indexing_params = indexing_defaults or {}
-        embedding.query_params = query_defaults or {}
+    while True:
+        embedding = _resolve_embedding_choice(
+            litellm_model_flag=litellm_model_flag,
+            st_installed=st_installed,
+            tty=interactive,
+            previous=previous,
+        )
+        previous = embedding  # remembered as the defaults for a potential retry
 
-    path = save_initial_user_settings(embedding, defaults_applied=defaults_applied)
-    _typer.echo()
-    _typer.echo(f"Created user settings: {format_path_for_display(path)}")
+        # Apply curated defaults if the model is in our table.
+        indexing_defaults, query_defaults = lookup_defaults(embedding.provider, embedding.model)
+        defaults_applied = indexing_defaults is not None or query_defaults is not None
+        if defaults_applied:
+            embedding.indexing_params = indexing_defaults or {}
+            embedding.query_params = query_defaults or {}
 
-    if defaults_applied:
+        path = save_initial_user_settings(embedding, defaults_applied=defaults_applied)
         _typer.echo()
-        _typer.echo(f"Applied recommended defaults for {embedding.model}:")
-        _typer.echo(f"  indexing_params: {embedding.indexing_params}")
-        _typer.echo(f"  query_params:    {embedding.query_params}")
+        _typer.echo(f"Created user settings: {format_path_for_display(path)}")
 
-    _typer.echo()
-    _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
-    _run_init_model_check(path)
-    _typer.echo()
+        if defaults_applied:
+            _typer.echo()
+            _typer.echo(f"Applied recommended defaults for {embedding.model}:")
+            _typer.echo(f"  indexing_params: {embedding.indexing_params}")
+            _typer.echo(f"  query_params:    {embedding.query_params}")
+
+        _typer.echo()
+        _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
+        if _run_init_model_check():
+            _typer.echo()
+            return
+
+        # Model check failed. Retry only makes sense if we can re-prompt.
+        if interactive and litellm_model_flag is None:
+            import questionary
+
+            _typer.echo()  # separate the failure output from the prompt below
+            choice = questionary.select(
+                "The embedding model couldn't be loaded. What would you like to do?",
+                choices=[
+                    questionary.Choice(title="Try a different provider/model", value="retry"),
+                    questionary.Choice(
+                        title="Keep these settings and finish — I'll edit the file myself",
+                        value="keep",
+                    ),
+                ],
+            ).ask()
+            if choice == "retry":
+                continue
+            # "keep" or None (cancelled) falls through to the next-steps block.
+
+        _print_init_next_steps(path)
+        return
 
 
 @app.command()
@@ -692,7 +769,7 @@ def _print_error(msg: str) -> None:
     _typer.echo(_click.style(f"  ERROR: {msg}", fg="red"), err=True)
 
 
-def _print_doctor_result(result: DoctorCheckResult) -> None:
+def _print_doctor_result(result: DoctorCheckResult, *, verbose: bool = False) -> None:
     import click as _click
 
     if result.name == "done":
@@ -704,13 +781,26 @@ def _print_doctor_result(result: DoctorCheckResult) -> None:
     for err in result.errors:
         _typer.echo(_click.style(f"    ERROR: {err}", fg="red"), err=True)
     if result.traceback:
-        for line in result.traceback.splitlines():
-            _typer.echo(_click.style(f"    {line}", fg="bright_black"), err=True)
+        if verbose:
+            for line in result.traceback.splitlines():
+                _typer.echo(_click.style(f"    {line}", fg="bright_black"), err=True)
+        else:
+            _typer.echo(
+                _click.style("    Run `ccc doctor -v` for the full traceback.", fg="bright_black"),
+                err=True,
+            )
 
 
 @app.command()
 @_catch_daemon_start_error
-def doctor() -> None:
+def doctor(
+    verbose: bool = _typer.Option(
+        False,
+        "-v",
+        "--verbose",
+        help="Show full exception tracebacks for failed checks.",
+    ),
+) -> None:
     """Check system health and report issues."""
     from . import client as _client
     from .settings import (
@@ -720,6 +810,9 @@ def doctor() -> None:
         load_user_settings as _load_user_settings,
     )
 
+    def _on_result(result: DoctorCheckResult) -> None:
+        _print_doctor_result(result, verbose=verbose)
+
     # --- 1. Global settings (local, no daemon needed) ---
     _print_section("Global Settings")
     settings_path = user_settings_path()
@@ -773,7 +866,7 @@ def doctor() -> None:
         try:
             _client.doctor(
                 project_root=None,
-                on_result=_print_doctor_result,
+                on_result=_on_result,
             )
         except Exception as e:
             _print_error(f"Model check failed: {e}")
@@ -804,7 +897,7 @@ def doctor() -> None:
         try:
             _client.doctor(
                 project_root=str(project_root),
-                on_result=_print_doctor_result,
+                on_result=_on_result,
             )
         except Exception as e:
             _print_error(f"Project checks failed: {e}")

{cocoindex_code-0.2.34 → cocoindex_code-0.2.36}/src/cocoindex_code/client.py

@@ -111,25 +111,33 @@ def _connect_and_handshake() -> Connection:
 
     Returns the open connection for the caller to send exactly one request.
 
-    On the first call, automatically starts or
-    restarts the daemon if needed.  Subsequent calls fail fast with
-    ``DaemonVersionError`` on mismatch (indicating the daemon was replaced
-    mid-session, e.g. after a tool upgrade).
+    Automatically starts or restarts the daemon when it is absent or running
+    with stale global settings (e.g. a ``ccc init`` retry rewrote
+    ``global_settings.yml`` after the daemon loaded it). A genuine *version*
+    mismatch after we have already reached a matching daemon means the binary
+    was replaced under us mid-session — that fails fast instead of looping on
+    restarts.
     """
     global _daemon_ensured  # noqa: PLW0603
 
-    if _daemon_ensured:
-        return _raw_connect_and_handshake()
-
-    # First connection — auto-start/restart as needed.
     try:
         conn = _raw_connect_and_handshake()
         _daemon_ensured = True
         return conn
-    except DaemonVersionError:
+    except DaemonVersionError as e:
+        # `resp.ok` is False only for a real version mismatch. Once we have
+        # ensured a matching daemon, a fresh version mismatch means the binary
+        # was swapped under us — fail fast. A settings-only restart request
+        # (resp.ok True, but the loaded settings mtime moved) is expected;
+        # restart the daemon below so it reloads them.
+        if _daemon_ensured and not e.resp.ok:
+            raise
         stop_daemon()
     except (ConnectionRefusedError, OSError):
-        pass
+        # No daemon answered. Normal on the first call (start one below); if we
+        # had already ensured one it vanished mid-session — surface that.
+        if _daemon_ensured:
+            raise
 
     if _is_daemon_supervised():
         # Supervisor is responsible for (re)starting the daemon — just wait
@@ -192,10 +200,16 @@ class DaemonVersionError(RuntimeError):
 
     def __init__(self, resp: HandshakeResponse) -> None:
         self.resp = resp
-        super().__init__(
-            f"Daemon version mismatch (daemon={resp.daemon_version}, "
-            f"client={__version__}). Please retry — the daemon may need a restart."
-        )
+        if not resp.ok:
+            message = (
+                f"Daemon version mismatch (daemon={resp.daemon_version}, "
+                f"client={__version__}). Please retry — the daemon may need a restart."
+            )
+        else:
+            message = (
+                "Daemon is running with stale global settings and needs a restart. Please retry."
+            )
+        super().__init__(message)
 
 
 class DaemonStartError(RuntimeError):