marvisx-cli 0.3.5__tar.gz → 0.3.6__tar.gz

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.5
+Version: 0.3.6
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1
@@ -31,6 +31,7 @@ Requires-Dist: click>=8
 Requires-Dist: pydantic>=2.5
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: PyYAML>=6
+Requires-Dist: platformdirs>=4.0
 Requires-Dist: cryptography>=42
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: slowapi>=0.1.9

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/README.md

@@ -1,10 +1,31 @@
-# MarvisX
+# Marvis
 
-Self-hosted, EU-resident **company brain** for agent-native operations: a cross-project Knowledge Graph, audit-immutable provenance, reflective Brain pipeline, and an agent-native Model Context Protocol surface.
+**The Company Brain your agents install.** Use Claude Code, or whatever coding agent you run, to manage projects and coordinate your agents, not just write code. Marvis captures what your agents do as they work, structures it into a cross-project Knowledge Graph, and hands it back to them, so your work stays on track and the system learns from it. Self-hosted, EU-resident, governed by an immutable audit chain.
 
-Released as a defensive-publication architectural pattern. See the Zenodo preprint: [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860).
+**Open-core and free to run.** Marvis is the free core: you self-host it, read the source, fork it, audit it, at no cost. MarvisX is the commercial tier on top of the same brain: multi-department teams, data sovereignty and managed hosting, and autonomous, hands-off-the-keyboard operation. Marvis is what you install today; MarvisX is what you reach for when a single self-hosted instance is no longer enough.
 
-## What MarvisX gives you
+## Install
+
+Marvis runs as a CLI your agent drives. Install it, then let the agent you already use take it from there:
+
+```bash
+uv tool install marvisx-cli
+marvis init
+```
+
+`marvis init` scaffolds the project and installs the governance hooks, then exposes the MCP surface to your agent. Python 3.10–3.13; on 3.14, pin the interpreter: `uv tool install --python 3.13 marvisx-cli`. No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+To run the full Console + API stack yourself, see [Self-hosting the full stack](#self-hosting-the-full-stack).
+
+## What it does, in plain terms
+
+- **Your agents stop forgetting.** Decisions, specs, playbooks, learnings and mistakes are captured as a side effect of the work your agents already do, not retyped by hand.
+- **Your work stays on track.** A reflective Brain layer compares what agents produce against your intent and surfaces drift early, before it compounds across sessions.
+- **One brain, many projects and teams.** A cross-project Knowledge Graph links decisions, code and documents, so an agent working in one project can see what was decided in another.
+- **Governed by default.** Constitution rules enforced at the hook level, plus a foreign-key-immutable audit log: every action traces back to the human who approved it.
+- **It lives in your terminal, not a dashboard.** An agent-native MCP surface keeps your existing Claude Code / Codex / Cursor as the place you work.
+
+## Under the hood
 
 - **Cross-project Knowledge Graph** with 17 deterministic edge types covering code, work-chain artifacts, knowledge-chain documents, cross-project references, and bridge edges. Canonical IDs follow `{prefix}:{kind}:{slug}`.
 - **Foreign-key-immutable audit log** with provenance pinned at the SQLite level. Designed to satisfy the logging surface required by EU Regulation 2024/1689 (AI Act) Article 12.
@@ -14,22 +35,22 @@ Released as a defensive-publication architectural pattern. See the Zenodo prepri
 
 ## Search and embedding quality
 
-MarvisX-OSS Phase 1 defaults to **IBM Granite-Embedding-97m-Multilingual-R2** self-hosted via ONNX, blended with SQLite BM25 keyword search through Reciprocal Rank Fusion. Backend is selectable through `EMBEDDING_MODE`.
+Marvis defaults to **IBM Granite-Embedding-97m-Multilingual-R2** self-hosted via ONNX, blended with SQLite BM25 keyword search through Reciprocal Rank Fusion. Backend is selectable through `EMBEDDING_MODE`.
 
 This is a deliberate tradeoff: EU compliance, self-hosting, and zero external embedding cost come at the cost of retrieval quality that is below commercial managed embedding providers. See [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) for the benchmark numbers, affected workflows, mitigations available today, and the Phase 2 fine-tune roadmap.
 
 ## License posture
 
-- Code: **Business Source License 1.1**, with an automatic change date converting to **Apache License 2.0** four years after release.
+- **Free to self-host.** Code is **source-available** under the **Business Source License 1.1**, with an automatic change date converting to **Apache License 2.0** four years after release.
 - Documentation and architectural patterns: **CC-BY 4.0**.
 
-The combination is intended to make the architecture freely citable while preserving the ability to ship a self-hosted reference deployment.
+This is open-core, not OSI open source: the core is free to run and read, and the BSL holds back only competing commercial-as-a-service use until the change date. The combination keeps the architecture freely citable while preserving the ability to ship a self-hosted reference deployment.
 
 ## Architecture map
 
 The system groups capabilities into eight functional domains (`M1 Capture`, `M2 Index`, `M3 Retrieve`, `M4 Reflect`, `M5 Act`, `M6 Agent-native I/O`, `M7 Compliance`, `M8 Productization`). The Knowledge Graph stitches them together with canonical IDs and an audit chain.
 
-For the full architectural description, see the Zenodo preprint linked above.
+The full architectural description is the MarvisX preprint on Zenodo: [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860).
 
 ## Repository layout
 
@@ -46,9 +67,9 @@ deploy/
                 # (Docker Compose + environment scaffolding)
 ```
 
-## Quick start
+## Self-hosting the full stack
 
-The reference deployment uses Docker Compose. Clone the repository, copy `deploy/_template/.env.example` to `.env`, populate the required secrets, and bring the stack up:
+The CLI above runs Marvis against a local SQLite database. To run the full Console + API stack yourself, use the reference Docker Compose deployment. Clone the repository, copy `deploy/_template/.env.example` to `.env`, populate the required secrets, and bring the stack up:
 
 ```bash
 cp deploy/_template/.env.example deploy/_template/.env
@@ -58,13 +79,9 @@ docker compose up -d
 
 The Console becomes available on the configured `CONSOLE_PORT` and the API on the configured `API_PORT`. Detailed first-run instructions are inside the deployment template.
 
-## Setting up local embeddings
-
-[`docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md`](docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md) covers the step-by-step path to the self-hosted Granite backend, including first-boot setup, re-indexing an existing corpus, and KG threshold recalibration.
-
 ## MCP surface
 
-MarvisX ships an MCP server exposing 91 tools across 11 categories: project and session context, tasks, handoffs, semantic search, learnings, costs, pull requests, knowledge graph queries, ingest triage, brain reflection layer, and audit-and-monitoring controls.
+Marvis ships an MCP server exposing 91 tools across 11 categories: project and session context, tasks, handoffs, semantic search, learnings, costs, pull requests, knowledge graph queries, ingest triage, brain reflection layer, and audit-and-monitoring controls.
 
 The same surface is used by autonomous agents and by humans through the web console. The intent is parity: any action a user can take through the console, an agent can also take through MCP, and the reverse.
 
@@ -78,15 +95,25 @@ Setting `MARVIS_OSS_LOCAL=1` (truthy: `1`/`true`/`yes`/`on`) makes the `block-db
 
 **No-fork guarantee.** The HTTP API and the MCP server are not two implementations: both are thin adapters over the same `core/api/use_cases`, differing only in how they fill the per-call `CallerContext`. The proof is the API test suite staying green after the extraction — the same behaviour, exercised through the HTTP surface, over the identical use_cases the MCP server calls.
 
+## Telemetry
+
+Marvis sends anonymous, opt-out usage telemetry to help improve it: coarse event counts plus version and OS buckets, tied to a random install id (a plain UUID, never derived from your machine, user, or email). It never sends file content, project data, or personal information.
+
+Turn it off at any time:
+
+```bash
+marvis telemetry off
+```
+
+Or per environment: `MARVIS_TELEMETRY=0`, the universal `DO_NOT_TRACK=1`, or `telemetry: false` in `~/.marvis/settings.yaml`. With `MARVIS_TELEMETRY=log`, Marvis prints exactly what it would send to stderr and transmits nothing.
+
 ## Documentation
 
 - [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) — search quality expectations, affected workflows, and mitigations
-- [`docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md`](docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md) — setting up the self-hosted Granite embedding backend
-- [`docs/solutions/architecture-patterns/`](docs/solutions/architecture-patterns/) — architectural decision records
 
 ## Contributing
 
-This is a defensive-publication release. The repository accepts issues for bug reports and clarifications. The architecture itself is documented in the Zenodo preprint; the codebase is intended as the reference implementation of that architecture.
+Issues and bug reports are welcome through the repository tracker.
 
 ## References
 

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/core/api/config.py

@@ -8,6 +8,8 @@ from typing import Literal
 from pydantic import AliasChoices, Field, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from core.platform import current_user, db_default_path
+
 # Prod (Hetzner/Docker) ships the vec0 loadable at this path; it stays the
 # final fallback so prod keeps working unchanged.
 _VEC0_PATH_PROD_DEFAULT = "/data/pir/lib/vec0"
@@ -70,7 +72,12 @@ class Settings(BaseSettings):
         ),
     )
     db_path: str = Field(
-        default="console.db",
+        # Fallback when no MARVIS_DB_PATH/PIR_DB_PATH/DB_PATH env is set: the
+        # platformdirs data root (was a CWD-relative "console.db" that opened a
+        # different DB per launch directory — split-brain, and on Windows a
+        # nonsense root). The env aliases still win via pydantic; this factory
+        # runs ONLY when none are set.
+        default_factory=lambda: str(db_default_path()),
         validation_alias=AliasChoices("MARVIS_DB_PATH", "PIR_DB_PATH", "DB_PATH"),
     )
     cookie_domain: str | None = Field(default=None, alias="COOKIE_DOMAIN")
@@ -544,16 +551,14 @@ class Settings(BaseSettings):
 
         Returns '' when GIT_RUNAS_USER is unset or already matches the current
         OS user (no privilege hop needed)."""
-        import pwd
-
         user = (self.git_runas_user or "").strip()
         if not user:
             return ""
-        try:
-            if pwd.getpwuid(os.getuid()).pw_name == user:
-                return ""
-        except (KeyError, OSError):
-            pass
+        # current_user() is pwd.getpwuid(os.getuid()).pw_name on POSIX (identical
+        # to the previous inline lookup) and getpass-based on Windows; the bare
+        # `import pwd` here crashed `marvis project list` on Windows.
+        if current_user() == user:
+            return ""
         return user
 
 

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/core/api/mcp/tools/learnings.py

@@ -109,6 +109,59 @@ def register(mcp) -> None:
         except ServiceError as e:
             raise_mcp_error(e)
 
+    @mcp.tool()
+    async def update_learning(
+        learning_id: Annotated[str, Field(min_length=1)],
+        title: Annotated[str, Field(min_length=1, max_length=200)] | None = None,
+        category: LearningCategory | None = None,
+        description: Annotated[str, Field(min_length=1)] | None = None,
+        prevention: Annotated[str, Field(min_length=1)] | None = None,
+        severity: LearningSeverity | None = None,
+        module: str | None = None,
+        tags: list[str] | None = None,
+        project: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing learning (operator+), then re-embed it so search/check_learnings see the new content immediately.
+
+        QUANDO USARLO: il contenuto di un learning e' obsoleto/incompleto (prevention piu' precisa, severity ricalibrata, nuovo modulo) ma vuoi PRESERVARE la history. BOUNDARY: update_learning aggiorna in-place + re-embed; delete_learning cancella permanente; create_learning scrive nuovo.
+        QUANDO NON USARLO: NOT per un learning nuovo -> usa create_learning. NOT per azzerare un campo a null: la superficie MCP NON puo' settare null (omettere un campo lo lascia invariato) -> usa l'HTTP PATCH se devi pulire un campo.
+        RESTITUISCE: il learning aggiornato {id, title, category, severity, prevention, tags, module, project, updated_at} — gia' ri-embeddato (retrievable by meaning, non solo keyword)."""
+        fields = {
+            k: v
+            for k, v in {
+                "title": title,
+                "category": category,
+                "description": description,
+                "prevention": prevention,
+                "severity": severity,
+                "module": module,
+                "tags": tags,
+                "project": project,
+            }.items()
+            if v is not None
+        }
+        try:
+            async with acquire_write_db(label="mcp.update_learning") as db:
+                result = await learnings_uc.update_learning(
+                    LOCAL_CTX, db, learning_id=learning_id, fields=fields
+                )
+            # Writer lock released: re-embed-on-write (mirror create_learning) so the
+            # updated content is retrievable by meaning immediately, not stale until
+            # a manual reindex.
+            await mcp_embed_learning(
+                learning_id=result.id,
+                title=result.title,
+                description=result.description,
+                category=result.category,
+                severity=result.severity,
+                prevention=result.prevention,
+                project=result.project,
+                workspace_id=LOCAL_CTX.workspace_id,
+            )
+            return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
     @mcp.tool()
     async def list_learnings(
         project: str | None = None,

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/core/api/models/tasks.py

@@ -18,7 +18,6 @@ VALID_STATUSES = {
 VALID_PRIORITIES = {"high", "medium", "low"}
 VALID_KINDS = {"normal", "idea"}
 VALID_SOURCES = {
-    "reflectx_proposal",
     "telegram",
     "manual",
     "session",
@@ -51,7 +50,7 @@ class TaskCreateRequest(BaseModel):
     priority: str = Field("medium", pattern=r"^(high|medium|low)$")
     source: str = Field(
         ...,
-        pattern=r"^(reflectx_proposal|telegram|manual|session|console|rem_proposal)$",
+        pattern=r"^(telegram|manual|session|console|rem_proposal)$",
     )
     source_ref: str | None = Field(None, max_length=500)
     owner_id: str | None = Field(

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/core/cli/_brain_opportunistic.py

@@ -29,6 +29,7 @@ import shutil
 import sys
 from typing import Any
 
+from core.platform import secure_path
 from core.telemetry import client as _tc  # canonical ~/.marvis + settings.yaml reader
 
 _RUN_INTERVAL_S = 24 * 3600
@@ -71,10 +72,7 @@ def _mark_ran(now: float) -> None:
         path = _last_run_path()
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(f"{now:.0f}\n", encoding="utf-8")
-        try:
-            os.chmod(path, 0o600)
-        except OSError:
-            pass
+        secure_path(path, mode=0o600)
     except Exception:  # noqa: BLE001
         pass
 

{marvisx_cli-0.3.5 → marvisx_cli-0.3.6}/core/cli/_brain_schedule.py

@@ -35,10 +35,13 @@ import sys
 from pathlib import Path
 from typing import Any
 
+from core.platform import current_uid
+
 # launchd Label / systemd unit base / cron marker — one identity across backends.
 _LABEL = "com.marvisx.brain"
 _UNIT = "marvis-brain"
 _CRON_MARKER = "# marvis-brain"
+_SCHTASKS_TN = "MarvisX Brain"  # Windows Task Scheduler task name
 
 # Default daily fire time (local), off-peak.
 _HOUR = 3
@@ -75,11 +78,11 @@ def _run(cmd: list[str], *, input_text: str | None = None) -> tuple[int, str, st
 
 
 def detect_backend() -> str:
-    """Return ``launchd`` | ``systemd`` | ``cron`` | ``unsupported``."""
+    """Return ``launchd`` | ``systemd`` | ``cron`` | ``schtasks`` | ``unsupported``."""
     if sys.platform == "darwin":
         return "launchd"
     if sys.platform.startswith("win"):
-        return "unsupported"
+        return "schtasks"
     if shutil.which("systemctl"):
         return "systemd"
     if shutil.which("crontab"):
@@ -93,7 +96,7 @@ def _marvis_path() -> str | None:
     if exe:
         return exe
     argv0 = sys.argv[0] if sys.argv else ""
-    if argv0.endswith(("marvis", "marvis-init")) and os.path.isfile(argv0):
+    if argv0.endswith(("marvis", "marvis.exe", "marvis-init", "marvis-init.exe")) and os.path.isfile(argv0):
         return os.path.abspath(argv0)
     return None
 
@@ -189,7 +192,7 @@ def _launchd_enable() -> dict[str, Any]:
     plist = _launchd_plist_path()
     plist.parent.mkdir(parents=True, exist_ok=True)
     plist.write_text(plist_text(marvis), encoding="utf-8")
-    domain = f"gui/{os.getuid()}"
+    domain = f"gui/{current_uid()}"
     # Idempotent: bootout an existing instance first (ignore failure), then bootstrap.
     _run(["launchctl", "bootout", f"{domain}/{_LABEL}"])
     rc, _out, err = _run(["launchctl", "bootstrap", domain, str(plist)])
@@ -203,7 +206,7 @@ def _launchd_enable() -> dict[str, Any]:
 
 def _launchd_disable() -> dict[str, Any]:
     plist = _launchd_plist_path()
-    rc, _out, err = _run(["launchctl", "bootout", f"gui/{os.getuid()}/{_LABEL}"])
+    rc, _out, err = _run(["launchctl", "bootout", f"gui/{current_uid()}/{_LABEL}"])
     removed = False
     if plist.is_file():
         plist.unlink()
@@ -214,7 +217,7 @@ def _launchd_disable() -> dict[str, Any]:
 
 def _launchd_status() -> dict[str, Any]:
     plist = _launchd_plist_path()
-    rc, _out, _err = _run(["launchctl", "print", f"gui/{os.getuid()}/{_LABEL}"])
+    rc, _out, _err = _run(["launchctl", "print", f"gui/{current_uid()}/{_LABEL}"])
     return {
         "backend": "launchd",
         "enabled": rc == 0,
@@ -335,13 +338,68 @@ def _cron_status() -> dict[str, Any]:
     return {"backend": "cron", "enabled": present}
 
 
+# ---------------------------------------------------------------------------
+# schtasks backend (Windows Task Scheduler)
+# ---------------------------------------------------------------------------
+
+
+def schtasks_argv_create(
+    marvis_path: str, *, hour: int = _HOUR, minute: int = _MINUTE, tn: str = _SCHTASKS_TN
+) -> list[str]:
+    """Build the ``schtasks /create`` argv (PURE — unit-tested).
+
+    ``/tr`` is ONE argv element; the program path keeps its OWN inner quotes so a
+    space in ``%USERPROFILE%`` (e.g. ``C:\\Users\\Marsida Curaj\\...``) survives Task
+    Scheduler parsing. ``_run`` passes a list (no shell), so subprocess does the
+    OUTER quoting via ``list2cmdline``; this builder owns only the inner ``/tr``.
+    ``/f`` force-overwrites = idempotent; no ``/ru`` = current user, no admin.
+    """
+    tr = f'"{marvis_path}" brain run --mode full'
+    return [
+        "schtasks", "/create", "/tn", tn, "/tr", tr,
+        "/sc", "DAILY", "/st", f"{hour:02d}:{minute:02d}", "/f",
+    ]
+
+
+def _schtasks_enable() -> dict[str, Any]:
+    marvis = _marvis_path()
+    if not marvis:
+        return {"backend": "schtasks", "ok": False, "error": "marvis not found on PATH"}
+    rc, _out, err = _run(schtasks_argv_create(marvis))
+    # schtasks can refuse on a password-protected / Microsoft-account user without
+    # stored creds; never crash — the opportunistic on-invocation upkeep is the net.
+    return {
+        "backend": "schtasks",
+        "ok": rc == 0,
+        "task_name": _SCHTASKS_TN,
+        "error": err.strip() if rc != 0 else None,
+        "warning": (
+            None
+            if rc == 0
+            else "could not register the Windows scheduled task; the opportunistic "
+            "on-invocation upkeep still runs whenever you use marvis"
+        ),
+    }
+
+
+def _schtasks_disable() -> dict[str, Any]:
+    # rc!=0 when the task does not exist — still a successful disable.
+    rc, _out, _err = _run(["schtasks", "/delete", "/tn", _SCHTASKS_TN, "/f"])
+    return {"backend": "schtasks", "ok": True, "deleted_rc": rc}
+
+
+def _schtasks_status() -> dict[str, Any]:
+    rc, _out, _err = _run(["schtasks", "/query", "/tn", _SCHTASKS_TN])
+    return {"backend": "schtasks", "enabled": rc == 0}
+
+
 # ---------------------------------------------------------------------------
 # Public dispatch
 # ---------------------------------------------------------------------------
 
-_ENABLE = {"launchd": _launchd_enable, "systemd": _systemd_enable, "cron": _cron_enable}
-_DISABLE = {"launchd": _launchd_disable, "systemd": _systemd_disable, "cron": _cron_disable}
-_STATUS = {"launchd": _launchd_status, "systemd": _systemd_status, "cron": _cron_status}
+_ENABLE = {"launchd": _launchd_enable, "systemd": _systemd_enable, "cron": _cron_enable, "schtasks": _schtasks_enable}
+_DISABLE = {"launchd": _launchd_disable, "systemd": _systemd_disable, "cron": _cron_disable, "schtasks": _schtasks_disable}
+_STATUS = {"launchd": _launchd_status, "systemd": _systemd_status, "cron": _cron_status, "schtasks": _schtasks_status}
 
 
 def enable(cadence: str = "daily") -> dict[str, Any]:

marvisx_cli-0.3.6/core/cli/_update_check.py

@@ -0,0 +1,164 @@
+# v1.0.0 - 2026-06-03 - 0.3.6: opt-out CLI "update available" notice (notify-only)
+"""Throttled, fail-silent "a new version is available" notice (NOTIFY ONLY).
+
+NEVER self-updates — no ``pip``/``uv`` side effect. It prints one line to stderr
+telling the user how to upgrade. npm-style decoupling so the notice is reliable:
+
+- print INSTANTLY from a cached latest-version file (so it actually shows, even
+  on a fast command that would outrun a background network call), then
+- refresh that cache in a detached daemon thread at most once per 24h.
+
+First run has no cache → no notice, but kicks the refresh → the next run shows it.
+
+Opt out via ``MARVIS_NO_UPDATE_CHECK=1`` or ``settings.yaml`` ``update_check: false``.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+from core.telemetry import client as _tc  # canonical ~/.marvis + settings reader
+
+_PACKAGE = "marvisx-cli"
+_PYPI_JSON = "https://pypi.org/pypi/marvisx-cli/json"
+_CHECK_INTERVAL_S = 24 * 3600
+_TIMEOUT = 2.5
+
+
+def _last_check_path():
+    return _tc._marvis_dir() / "update_last_check"
+
+
+def _cached_latest_path():
+    return _tc._marvis_dir() / "update_latest"
+
+
+def _opted_out() -> bool:
+    if os.environ.get("MARVIS_NO_UPDATE_CHECK"):
+        return True
+    try:
+        return _tc._read_settings().get("update_check") is False
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _installed_version() -> str | None:
+    try:
+        from importlib.metadata import version
+
+        return version(_PACKAGE)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _read_cached_latest() -> str | None:
+    try:
+        path = _cached_latest_path()
+        if path.is_file():
+            return path.read_text(encoding="utf-8").strip() or None
+    except Exception:  # noqa: BLE001
+        return None
+    return None
+
+
+def _write_cached_latest(version: str) -> None:
+    try:
+        path = _cached_latest_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(version.strip() + "\n", encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _should_check(now: float) -> bool:
+    try:
+        path = _last_check_path()
+        if not path.is_file():
+            return True
+        last = float(path.read_text(encoding="utf-8").strip() or 0)
+        return (now - last) >= _CHECK_INTERVAL_S
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _mark_checked(now: float) -> None:
+    try:
+        path = _last_check_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(f"{now:.0f}\n", encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _parse(v: str) -> tuple[int, ...]:
+    """Numeric release tuple; a pre-release/garbage chunk truncates to its int
+    prefix (0 if none) — conservative, never crashes."""
+    out: list[int] = []
+    for chunk in v.split("."):
+        digits = ""
+        for ch in chunk:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        out.append(int(digits) if digits else 0)
+    return tuple(out)
+
+
+def _is_newer(latest: str, installed: str) -> bool:
+    try:
+        return _parse(latest) > _parse(installed)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _fetch_latest() -> str | None:
+    import json
+    import urllib.request
+
+    try:
+        req = urllib.request.Request(
+            _PYPI_JSON, headers={"User-Agent": "marvis-update-check/1"}
+        )
+        with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:  # noqa: S310 — https pinned
+            data = json.loads(resp.read().decode("utf-8", "replace"))
+        v = (data.get("info") or {}).get("version")
+        return v if isinstance(v, str) and v else None
+    except Exception:  # noqa: BLE001 — down/slow PyPI → silent
+        return None
+
+
+def _refresh_cache() -> None:
+    latest = _fetch_latest()
+    if latest:
+        _write_cached_latest(latest)
+
+
+def maybe_notify_update() -> None:
+    """Print a cached "update available" notice (instant), then refresh the cache
+    in the background ≤1×/day. Notify-only, fail-silent, never blocks."""
+    try:
+        if _opted_out():
+            return
+
+        installed = _installed_version()
+        if installed:
+            cached = _read_cached_latest()
+            if cached and _is_newer(cached, installed):
+                sys.stderr.write(
+                    f"\n[marvis] update available: {installed} → {cached}. "
+                    f"Upgrade with: uv tool upgrade {_PACKAGE}\n"
+                )
+
+        from time import time
+
+        now = time()
+        if _should_check(now):
+            _mark_checked(now)  # claim the 24h window before the network call
+            import threading
+
+            threading.Thread(
+                target=_refresh_cache, name="marvis-update-check", daemon=True
+            ).start()
+    except Exception:  # noqa: BLE001 — must never affect the command
+        return