marvisx-cli 0.3.8b1__tar.gz → 0.3.8b2__tar.gz

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.8b1
+Version: 0.3.8b2
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/config.py

@@ -453,6 +453,13 @@ class Settings(BaseSettings):
     graph_lane_weight: float = Field(
         default=0.12, alias="MARVIS_GRAPH_LANE_WEIGHT"
     )
+    # #13: when a graph read finds its index stale/behind HEAD, surface the
+    # reindex as an EXPLICIT next action (command + auto_reindex marker). Default
+    # off; even when on, a read NEVER fires the (heavy, repo-re-parsing) KG
+    # reindex itself — re-indexing stays an explicit operation.
+    graph_autoreindex_on_drift: bool = Field(
+        default=False, alias="MARVIS_GRAPH_AUTOREINDEX_ON_DRIFT"
+    )
 
     # Track 2 #1 — bi-temporal memory READ path (DEFAULT OFF). When False every
     # learnings read is byte-identical to today (no invalid_at filter, no as_of):

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/db.py

@@ -118,6 +118,13 @@ async def init_pool(size: int = 2) -> None:
 
     Pool size=8 supports concurrent deep=true requests (4 parallel KG subqueries × 2 concurrent requests).
     """
+    # Apply any pending schema migrations before opening the pool, so EVERY
+    # entry point (CLI, MCP, brain, API) lands on a current schema — not only
+    # `marvis init` and the API lifespan. Idempotent and cheap when already
+    # current (the API path migrates explicitly first, so this finds nothing).
+    # Fail-loud here is a clearer signal than a later "no such column" on the
+    # first write against a half-upgraded DB. (#12)
+    run_migrations()
     global _pool, _pool_size, _writer
     actual_size = 8  # read-only pool: expanded for KG lens 4-subquery parallel pattern (Phase 7.0)
     _pool = asyncio.Queue(maxsize=actual_size)

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/main.py

@@ -931,6 +931,20 @@ async def _periodic_inbox_digest() -> None:
                     result.get("overflow", 0),
                     result.get("expired", 0),
                 )
+            # Invariant guard: every VISIBLE item must be deepened. The 6 UTC
+            # precompute is best-effort/one-shot; this sweep catches its failures
+            # and items promoted into visible later in the day.
+            from core.api.services.inbox_digest_deep_research import (
+                sweep_visible_missing_deep_research,
+            )
+
+            sweep = await sweep_visible_missing_deep_research()
+            if sweep.get("missing"):
+                logger.info(
+                    "Digest deep-research sweep: deepened %d/%d missing visible items",
+                    sweep.get("generated", 0),
+                    sweep.get("missing", 0),
+                )
         except asyncio.CancelledError:
             break
         except Exception:

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/mcp/server.py

@@ -34,10 +34,51 @@ from core.api.mcp.tools import register_all
 # `app.state` equivalent for a server with no FastAPI `app`). Tools register on
 # this at import time so `from core.api.mcp.server import mcp` already carries the
 # full tool set — the smoke test introspects it without launching stdio.
-mcp = FastMCP("marvis")
+_INSTRUCTIONS = (
+    "Marvis is a company-brain MCP for cross-project orchestration and institutional memory.\n"
+    "Route by task type (prefer these structured tools over re-deriving context from raw files):\n"
+    "- Cold-start / 'state of project X': session_brief(slug) — it also suggests the next tool when the project is cross-project.\n"
+    "- 'If I pause / close / de-prioritize project X, what blocks?': project_impact(slug) — the project-level blast radius. "
+    "(graph_impact on a 'project:artifact:<slug>' node with depends_on does the same.)\n"
+    "- 'What breaks if I change function X' (code level): graph_impact / graph_neighbors on a 'py:function:...' node.\n"
+    "- 'What do we already know / what bit us before' (decisions and risky actions): check_learnings(q).\n"
+    "- Cross-project discovery by meaning: search(q). Body of ONE known project: get_project(slug) — do not layer search on top of get_project.\n"
+)
+
+mcp = FastMCP("marvis", instructions=_INSTRUCTIONS)
 
 register_all(mcp)
 
+# mcp-ergonomics (tiering): mark the cold-start core always-loaded so clients with
+# MCP tool-search (e.g. Claude Code — the agent that drives the brain) keep these in
+# context and defer the other ~60 tools on demand. A 70-tool surface is well over the
+# ~20-30 threshold where tool-selection accuracy degrades. Additive: clients without
+# tool-search still see every tool (no regression). Best-effort — a FastMCP registry
+# shape change degrades to a no-op, never a boot failure.
+_CORE_TOOLS = frozenset(
+    {
+        "session_brief",
+        "search",
+        "check_learnings",
+        "list_tasks",
+        "get_task",
+        "create_task",
+        "update_task",
+        "get_project",
+        "graph_impact",
+        "graph_neighbors",
+        "project_impact",
+    }
+)
+try:
+    for _name, _tool in mcp._tool_manager._tools.items():
+        if _name in _CORE_TOOLS:
+            _m = dict(_tool.meta or {})
+            _m["anthropic/alwaysLoad"] = True
+            _tool.meta = _m
+except Exception:  # pragma: no cover - FastMCP internal-shape guard
+    pass
+
 
 def main() -> None:
     """Run the MCP server over stdio (the OSS runtime entrypoint).

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/mcp/tools/graph.py

@@ -123,10 +123,10 @@ def register(mcp) -> None:
         rank: NeighborRank = "none",
         as_of: Annotated[str, Field(pattern=_AS_OF_PATTERN, max_length=32)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Surgical 1-hop neighbour query for a KG node (calls/imports/defines/mentions/...) — per context completo su un nodo usa get_task/get_project/get_handoff/get_learning(deep=true). Usa questo tool solo quando hai bisogno di ispezionare il vicinato topologico diretto senza il bundle completo.
-        QUANDO USARLO: refactor impact assessment su una singola function; verificare se un nodo ha caller inattesi; time-travel as_of su commit specifico; rank=suspect_write per bug write-through-read.
-        QUANDO NON USARLO: NOT per context di un task/handoff/learning -> usa get_*(deep=true). NOT per BFS transitivo -> usa graph_impact.
-        RESTITUISCE: list of {node_id, relation, direction, rank_score?} cap 200."""
+        """1-hop: chi tocca / dipende direttamente da un nodo. Funziona su codice ('py:function:...') E su progetti ('project:artifact:<slug>').
+        ORCHESTRAZIONE: per i vicini diretti di un PROGETTO (chi dipende da X) passa node_id='project:artifact:<slug>' con edge_types=['depends_on']. Codice: caller/callee 1-hop di una function.
+        QUANDO USARLO: vicinato diretto senza il bundle completo; caller inattesi; time-travel as_of; rank=suspect_write per bug write-through-read. Per il blast radius transitivo usa graph_impact / project_impact.
+        RESTITUISCE: list of {node_id, relation, direction, rank_score?, freshness} cap 200."""
         try:
             async with acquire_db() as db:
                 # Node proxy hardcodes limit=200 (the surface exposes no limit param).
@@ -152,7 +152,7 @@ def register(mcp) -> None:
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
         type_filter: HotspotTypeFilter = "file",
     ) -> dict[str, Any]:
-        """[Power-user] DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
+        """DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
         QUANDO USARLO: identificare moduli ad alto rischio prima di una release; trovare ownership gaps (bus_factor=1); pianificare tech debt.
         QUANDO NON USARLO: NOT per context di un progetto specifico -> usa get_project(deep=true). NOT per BFS da un nodo -> usa graph_impact.
         RESTITUISCE: list of {node_id, touch_count_7d, touch_count_30d, authors[], bus_factor} top N."""
@@ -178,10 +178,10 @@ def register(mcp) -> None:
         edge_types: list[EdgeType] | None = None,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] BFS impact analysis: 'cosa si rompe se cambio X?' con ranker su direct callers + transitive list — per context completo usa get_task(deep=true). Usa questo tool per delete/rename risk assessment o pre-refactor sweep.
-        QUANDO USARLO: prima di eliminare/rinominare una function critica; misurare blast radius di una migration; dependency cascade analysis.
-        QUANDO NON USARLO: NOT per context standard -> usa get_*(deep=true). NOT per 1-hop only -> usa graph_neighbors.
-        RESTITUISCE: {direct_callers[], transitive_list[], rank_score} depth configurabile."""
+        """Impact / blast radius: 'cosa si rompe — o quali progetti si bloccano — se cambio / pauso / chiudo X?'. BFS sui rami transitivi + ranker sui diretti.
+        ORCHESTRAZIONE DI PORTAFOGLIO: per sapere quali PROGETTI si bloccano se pausi/chiudi un progetto, passa node_id='project:artifact:<slug>' con edge_types=['depends_on','mentions','refers_to'] — oppure usa il tool dedicato project_impact(slug). Livello-codice: per 'cosa si rompe se cambio questa function' passa un node 'py:function:...'.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto (blast radius cross-project); prima di eliminare/rinominare una function critica; dependency cascade analysis; sequenziare lavoro (cosa sblocca cosa).
+        RESTITUISCE: {direct (callers/dependents)[], transitive_list[], rank_score, freshness (indexed_sha vs HEAD)} depth configurabile."""
         try:
             async with acquire_db() as db:
                 result = await graph_uc.graph_impact(
@@ -197,15 +197,38 @@ def register(mcp) -> None:
         except ServiceError as e:
             raise_mcp_error(e)
 
+    @mcp.tool()
+    async def project_impact(
+        slug: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)],
+        depth: Annotated[int, Field(ge=1, le=5)] = 2,
+    ) -> dict[str, Any]:
+        """Portfolio blast radius: 'se pauso / chiudo / de-prioritizzo questo PROGETTO, quali altri progetti si bloccano?'. Il tool di prima classe per l'orchestrazione cross-progetto — distinto dal grafo-codice.
+        Risolve 'project:artifact:<slug>' e fa l'impact BFS sui soli edge progetto->progetto (depends_on / mentions / refers_to). La response porta il segnale freshness (indexed_sha vs HEAD) per non fidarsi di un indice stantio.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto; sequenziare un portafoglio (cosa sblocca cosa); capire le dipendenze cross-progetto di una decisione.
+        RESTITUISCE: {direct_dependents[], transitive_list[], rank_score, freshness}."""
+        try:
+            async with acquire_db() as db:
+                result = await graph_uc.graph_impact(
+                    LOCAL_CTX,
+                    db,
+                    node_id=f"project:artifact:{slug}",
+                    depth=depth,
+                    limit=100,
+                    edge_types=["depends_on", "mentions", "refers_to"],
+                    project=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
     @mcp.tool()
     async def graph_context(
         node_id: Annotated[str, Field(pattern=_NODE_ID_PATTERN, max_length=256)],
         per_category_limit: Annotated[int, Field(ge=1, le=20)] = 5,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Rationale chain: function→commit→PR→task→handoff→learning in 1 call — per context su un singolo artefatto usa get_task/get_handoff/get_learning(deep=true). Usa questo tool quando hai un node_id e vuoi la storia completa del PERCHE'.
-        QUANDO USARLO: archeologia di codice legacy ('perche esiste questa function?'); audit trail pre-refactor; linkare codice a decision record.
-        QUANDO NON USARLO: NOT per workflow standard su task/handoff -> usa get_*(deep=true). NOT per vicinato topologico -> usa graph_neighbors.
+        """Rationale chain di un nodo: function/progetto → commit → PR → task → handoff → learning in 1 call. Il PERCHE' dietro qualcosa.
+        QUANDO USARLO: perche' esiste / da dove viene una function o una decisione di progetto; audit trail; linkare codice o progetto a un decision record.
         RESTITUISCE: chain {commits[], PR?, task?, handoffs[], learnings[]} per_category_limit configurabile."""
         try:
             async with acquire_db() as db:
@@ -225,7 +248,7 @@ def register(mcp) -> None:
         scope: Annotated[str, Field(max_length=256)],
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
     ) -> dict[str, Any]:
-        """[Power-user] Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
+        """Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
         QUANDO USARLO: 'quali learnings esistono per api.db?' prima di toccare il DB module; scoping pre-deployment di un servizio specifico.
         QUANDO NON USARLO: NOT per ricerca semantica generica pre-azione -> usa check_learnings. NOT per context di un nodo -> usa graph_context.
         RESTITUISCE: list of {learning_id, title, prevention, severity, scope_match_score}."""
@@ -240,7 +263,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def graph_capabilities() -> dict[str, Any]:
-        """[Power-user] KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
+        """KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
         QUANDO USARLO: prima di costruire query graph_* o validare node_id pattern; cold-start agent discovery.
         QUANDO NON USARLO: per query topologiche -> usa graph_neighbors/impact/context.
         RESTITUISCE: {edge_types[], node_kinds[], node_prefixes[], schema_version}.

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/mcp/tools/learnings.py

@@ -47,10 +47,10 @@ def register(mcp) -> None:
         q: Annotated[str, Field(min_length=1, max_length=500)],
         module: str | None = None,
     ) -> dict[str, Any]:
-        """Search learnings DB (past post-mortems + prevention rules) for a risky action.
+        """Cosa sappiamo gia' / cosa ci ha morso: cerca nei learnings (post-mortem + regole di prevenzione) prima di una decisione o di un'azione.
 
-        QUANDO USARLO: PRIMA di qualunque azione production-affecting (deploy, migration, auth change, push to main, dependency upgrade) — Quality Gate 9.4. BOUNDARY: create_learning vs check_learnings = create scrive nuovo; check cerca rilevante PRE-azione rischiosa. BOUNDARY: check_learnings vs list_learnings = check = semantic match su situazione; list = enumerazione filtrata.
-        QUANDO NON USARLO: NOT quando hai gia' un file/module path e vuoi learnings scoped -> usa graph_pattern. NOT per scrivere un nuovo learning -> usa create_learning.
+        QUANDO USARLO: prima di qualunque azione production-affecting (deploy, migration, auth change, push, dependency upgrade); E prima di una DECISIONE o di un piano (per non ripetere errori noti e riusare cio' che ha funzionato). Non e' solo un gate pre-deploy: e' la memoria istituzionale a cui attingere quando ragioni. BOUNDARY: create_learning scrive nuovo; check_learnings = semantic match sulla situazione; list_learnings = enumerazione filtrata.
+        QUANDO NON USARLO: se hai gia' un file/module path e vuoi learnings scoped -> graph_pattern. Per scrivere un nuovo learning -> create_learning.
         RESTITUISCE: list of {id, title, prevention, severity, module} ranked per rilevanza."""
         try:
             async with acquire_db() as db:

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b2}/core/api/routers/inbox.py

@@ -1,6 +1,7 @@
 # v1.1.0 - 2026-04-14 - Single-writer: reclassify_inbox_items uses get_write_db (batch 5/6)
 from __future__ import annotations
 
+import asyncio
 import logging
 import time
 from collections import defaultdict
@@ -62,6 +63,20 @@ from core.api.services.inbox_triage import (
 
 logger = logging.getLogger(__name__)
 
+
+# Strong refs to fire-and-forget on-read deep-research sweeps so the event loop
+# does not garbage-collect them mid-flight; discarded when each completes.
+_background_sweeps: set[asyncio.Task] = set()
+
+
+def _on_sweep_done(task: asyncio.Task) -> None:
+    _background_sweeps.discard(task)
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.warning("on-read digest deep-research sweep failed: %s", exc)
+
 router = APIRouter(prefix="/api/v1/inbox", tags=["inbox"])
 
 # ---------------------------------------------------------------------------
@@ -306,13 +321,26 @@ async def get_current_digest_items(
     db: aiosqlite.Connection = Depends(get_db),
 ) -> list[dict]:
     workspace_id = user.workspace_id or "ws_default"
-    return await list_digest_items(
+    items = await list_digest_items(
         db,
         workspace_id,
         state="visible",
         domain_key=domain_key,
         limit=limit,
     )
+    # On-read safety net (A): kick off deepening of any visible item still
+    # missing deep research, non-blocking, so it is ready by the time the user
+    # opens it. Idempotent + lock-guarded (no overlap with the scheduler sweep).
+    from core.api.services.inbox_digest_deep_research import (
+        sweep_visible_missing_deep_research,
+    )
+
+    sweep_task = asyncio.create_task(
+        sweep_visible_missing_deep_research(workspace_id=workspace_id)
+    )
+    _background_sweeps.add(sweep_task)
+    sweep_task.add_done_callback(_on_sweep_done)
+    return items
 
 
 @router.get("/digest/overflow")

marvisx_cli-0.3.8b2/core/api/services/inbox_digest_deep_research.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from fastapi import HTTPException
+
+from core.api.services.inbox_tldr import get_or_generate_deep_research
+
+logger = logging.getLogger(__name__)
+
+# Serializes the on-read trigger and the periodic scheduler so two sweeps never
+# overlap and hammer the gateway for the same items.
+_sweep_lock = asyncio.Lock()
+
+
+async def precompute_deep_research_for_items(
+    *,
+    inbox_item_ids: list[str],
+    workspace_id: str,
+    cycle_key: str,
+    concurrency: int = 1,
+    allow_cloud_fallback: bool = False,
+) -> dict[str, Any]:
+    """Best-effort Deep Analysis precompute for a prepared digest cycle."""
+    stats: dict[str, Any] = {
+        "cycle_key": cycle_key,
+        "attempted": 0,
+        "generated": 0,
+        "cached": 0,
+        "failed": 0,
+        "skipped": 0,
+        "errors": [],
+    }
+    item_ids = [item_id for item_id in inbox_item_ids if item_id]
+    stats["skipped"] = len(inbox_item_ids) - len(item_ids)
+    if not item_ids:
+        return stats
+
+    semaphore = asyncio.Semaphore(max(1, concurrency))
+
+    async def precompute_one(item_id: str) -> None:
+        async with semaphore:
+            stats["attempted"] += 1
+            try:
+                result = await get_or_generate_deep_research(
+                    item_id,
+                    workspace_id,
+                    force=False,
+                    allow_cloud_fallback=allow_cloud_fallback,
+                )
+            except HTTPException as exc:
+                stats["failed"] += 1
+                stats["errors"].append(
+                    {"item_id": item_id, "status_code": exc.status_code}
+                )
+                logger.warning(
+                    "Digest Deep Analysis precompute failed for %s cycle=%s status=%s",
+                    item_id,
+                    cycle_key,
+                    exc.status_code,
+                )
+                return
+            except Exception as exc:
+                stats["failed"] += 1
+                stats["errors"].append(
+                    {"item_id": item_id, "error": type(exc).__name__}
+                )
+                logger.warning(
+                    "Digest Deep Analysis precompute failed for %s cycle=%s: %s",
+                    item_id,
+                    cycle_key,
+                    exc,
+                )
+                return
+
+            if result.get("cached"):
+                stats["cached"] += 1
+            else:
+                stats["generated"] += 1
+
+    await asyncio.gather(*(precompute_one(item_id) for item_id in item_ids))
+    return stats
+
+
+async def sweep_visible_missing_deep_research(
+    *,
+    workspace_id: str = "ws_default",
+    limit: int = 50,
+) -> dict[str, Any]:
+    """Deepen any current-cycle VISIBLE digest item still missing deep research.
+
+    Enforces the invariant "an item shown in the daily visible digest must be
+    deepened". Catches both 6 UTC precompute failures (gateway slow/down, no
+    retry) and items promoted into the visible set later in the day. Idempotent
+    (only targets rows where deep_research is NULL/empty) and serialized by
+    ``_sweep_lock`` so the periodic scheduler and the on-read trigger never run
+    overlapping sweeps. Honors the same digest settings as the 6 UTC run
+    (mode/deep_research_enabled/concurrency/allow_cloud_fallback).
+    """
+    if _sweep_lock.locked():
+        return {"status": "already_running", "attempted": 0}
+
+    async with _sweep_lock:
+        from core.api.db import acquire_db
+        from core.api.services.inbox_digest import get_current_digest_cycle_key
+        from core.api.services.inbox_digest_jobs import _load_digest_settings
+
+        async with acquire_db() as db:
+            settings = await _load_digest_settings(db)
+            if settings.mode == "false" or not settings.deep_research_enabled:
+                return {"status": "disabled", "attempted": 0}
+            cycle_key = await get_current_digest_cycle_key(db, workspace_id)
+
+            where = ["s.workspace_id = ?", "s.state = 'visible'"]
+            params: list[Any] = [workspace_id]
+            if cycle_key:
+                where.append("s.digest_cycle_key = ?")
+                params.append(cycle_key)
+            params.append(limit)
+            rows = await (
+                await db.execute(
+                    "SELECT s.inbox_item_id FROM inbox_digest_selections s "
+                    "JOIN inbox_items i ON i.id = s.inbox_item_id "
+                    f"WHERE {' AND '.join(where)} "
+                    "AND (i.deep_research IS NULL OR i.deep_research = '') "
+                    "ORDER BY s.rank_in_domain ASC LIMIT ?",
+                    tuple(params),
+                )
+            ).fetchall()
+
+        missing_ids = [row[0] for row in rows]
+        if not missing_ids:
+            return {"status": "ok", "attempted": 0, "missing": 0}
+
+        stats = await precompute_deep_research_for_items(
+            inbox_item_ids=missing_ids,
+            workspace_id=workspace_id,
+            cycle_key=cycle_key or "sweep",
+            concurrency=settings.concurrency,
+            allow_cloud_fallback=settings.allow_cloud_fallback,
+        )
+        stats["status"] = "ok"
+        stats["missing"] = len(missing_ids)
+        logger.info(
+            "Digest deep-research sweep: %d visible missing -> generated=%d cached=%d failed=%d",
+            len(missing_ids),
+            stats.get("generated", 0),
+            stats.get("cached", 0),
+            stats.get("failed", 0),
+        )
+        return stats

marvisx_cli-0.3.8b2/core/api/tests/test_graph_freshness.py

@@ -0,0 +1,126 @@
+"""Unit tests for the KG freshness/staleness signal (#13).
+
+graph_impact / graph_neighbors must not return an authoritative-looking blast
+radius with no hint that the index is stale or partial. compute_index_freshness
+surfaces, per the queried node's project, whether the graph is indexed / has git
+provenance / matches HEAD — and NEVER mutates (no reindex from a read).
+"""
+
+from __future__ import annotations
+
+import aiosqlite
+import pytest
+
+import core.api.use_cases.graph as graph_mod
+from core.api.use_cases.graph import compute_index_freshness
+
+_SCHEMA = """
+CREATE TABLE graph_nodes (
+    id TEXT PRIMARY KEY,
+    project_id TEXT,
+    last_modified_git_sha TEXT,
+    touch_last_at TEXT
+);
+"""
+
+
+async def _db(rows):
+    conn = await aiosqlite.connect(":memory:")
+    conn.row_factory = aiosqlite.Row
+    await conn.executescript(_SCHEMA)
+    for r in rows:
+        await conn.execute(
+            "INSERT INTO graph_nodes (id, project_id, last_modified_git_sha, touch_last_at) "
+            "VALUES (?, ?, ?, ?)",
+            r,
+        )
+    await conn.commit()
+    return conn
+
+
+@pytest.mark.asyncio
+async def test_not_indexed_is_stale():
+    db = await _db([])
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["reason"] == "not_indexed"
+        assert out["stale"] is True
+        assert "index" in out["hint"]
+    finally:
+        await db.close()
+
+
+@pytest.mark.asyncio
+async def test_not_git_linked_is_not_stale(monkeypatch):
+    monkeypatch.setattr("core.api.routers.projects._find_git_path", lambda slug: None)
+    db = await _db([("py:function:x.y", "alpha", "abc1234", "2026-05-01")])
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["reason"] == "not_git_linked"
+        assert out["stale"] is False
+    finally:
+        await db.close()
+
+
+@pytest.mark.asyncio
+async def test_sha_unpopulated_is_stale(monkeypatch):
+    # The real-world case from the issue: nodes exist + repo linked, but commit
+    # provenance was never populated (distinct git_sha = 0).
+    monkeypatch.setattr("core.api.routers.projects._find_git_path", lambda slug: "/tmp/repo")
+    monkeypatch.setattr(graph_mod, "_git_head_sha", lambda repo: "deadbee")
+    db = await _db(
+        [
+            ("py:function:x.y", "alpha", "", "2026-05-01"),
+            ("py:file:x", "alpha", None, "2026-05-02"),
+        ]
+    )
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["reason"] == "sha_unpopulated"
+        assert out["stale"] is True
+        assert out["indexed_node_count"] == 2
+    finally:
+        await db.close()
+
+
+@pytest.mark.asyncio
+async def test_behind_head_is_stale(monkeypatch):
+    monkeypatch.setattr("core.api.routers.projects._find_git_path", lambda slug: "/tmp/repo")
+    monkeypatch.setattr(graph_mod, "_git_head_sha", lambda repo: "newsha9")
+    db = await _db([("py:function:x.y", "alpha", "oldsha1", "2026-05-01")])
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["reason"] == "behind_head"
+        assert out["stale"] is True
+        assert out["indexed_git_sha"] == "oldsha1"
+        assert out["head_git_sha"] == "newsha9"
+    finally:
+        await db.close()
+
+
+@pytest.mark.asyncio
+async def test_fresh_when_indexed_sha_matches_head(monkeypatch):
+    monkeypatch.setattr("core.api.routers.projects._find_git_path", lambda slug: "/tmp/repo")
+    monkeypatch.setattr(graph_mod, "_git_head_sha", lambda repo: "abc1234")
+    db = await _db([("py:function:x.y", "alpha", "abc1234", "2026-05-01")])
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["reason"] == "fresh"
+        assert out["stale"] is False
+    finally:
+        await db.close()
+
+
+@pytest.mark.asyncio
+async def test_autoreindex_flag_marks_command_but_never_executes(monkeypatch):
+    monkeypatch.setattr(
+        "core.api.config.settings.graph_autoreindex_on_drift", True, raising=False
+    )
+    db = await _db([])  # not_indexed → stale
+    try:
+        out = await compute_index_freshness(db, node_id="py:function:x.y", project="alpha")
+        assert out["stale"] is True
+        assert out.get("auto_reindex") == "suggested"
+        assert out["reindex_command"] == "marvis project index alpha"
+    finally:
+        await db.close()