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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.8b1
+Version: 0.3.8b3
 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.8b3}/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.8b3}/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)
@@ -732,54 +739,62 @@ def _backfill_session_uuids(conn: sqlite3.Connection) -> None:
 
 
 def _seed_users_and_migrate_owner(conn: sqlite3.Connection) -> None:
-    """Migration 016 post-hook: seed the admin user + data-migrate tasks.owner_id.
+    """Migration 016 post-hook: seed the admin user (when configured) + data-migrate
+    tasks.owner_id.
 
     Runs synchronously inside run_migrations() — do NOT use await here.
-    Accepts either PIR_ADMIN_PASSWORD_HASH (pre-hashed, preferred in production)
-    or PIR_PASSWORD (plaintext, will be bcrypt-hashed here).
-    At least one must be set or the migration aborts.
-
-    The admin identity is config-driven via the same MARVIS_ADMIN_* vars used by
-    the deploy bootstrap (scripts/init.sh), with generic defaults, so a fresh
-    install seeds no hardcoded name. On an existing deployment this seed is
-    skipped (users already exist), so the defaults never affect a running install.
-    """
-    # Prefer pre-hashed password. Canonical var is MARVIS_ADMIN_PASSWORD_HASH;
-    # PIR_ADMIN_PASSWORD_HASH stays accepted as a deprecated alias.
-    hashed = (
-        os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
-        or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
-    ).strip()
-    if not hashed:
-        import bcrypt
-
-        seed_password = (
-            os.environ.get("MARVIS_PASSWORD")
-            or os.environ.get("PIR_PASSWORD", "")
-        ).strip()
-        if not seed_password:
-            raise RuntimeError(
-                "Migration 016 requires MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD "
-                "env var (PIR_* aliases still accepted) to seed the admin user. "
-                "Set at least one in .env."
-            )
-        hashed = bcrypt.hashpw(seed_password.encode("utf-8"), bcrypt.gensalt()).decode()
-
-    admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
-    admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"
-    admin_name = os.environ.get("MARVIS_ADMIN_DISPLAY_NAME", "").strip() or "Admin"
 
+    Admin seeding is OPTIONAL and config-driven: the admin user is created only when
+    a real credential is present (MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD; PIR_*
+    aliases accepted). With NO credential — the OSS single-user case, where the CLI
+    uses the local single-user context and never logs in with a password — the seed
+    is SKIPPED (not aborted), so a fresh-DB boot via init_pool (MCP server / brain,
+    which now run migrations) does not crash on a clean install. `marvis init` sets
+    MARVIS_PASSWORD before migrating, so it still seeds the admin. The owner_id
+    slug→id data migration always runs (idempotent), regardless of seeding.
+
+    b3 note: the real cleanup is to decouple admin seeding from run_migrations
+    entirely — it belongs in `marvis init` / `marvis account`, not in a schema hook.
+    """
     cursor = conn.execute("SELECT COUNT(*) FROM users")
     user_count = cursor.fetchone()[0]
     if user_count == 0:
-        conn.execute(
-            "INSERT OR IGNORE INTO users "
-            "(id, slug, display_name, type, password_hash, system_role) "
-            "VALUES (?, ?, ?, ?, ?, ?)",
-            (admin_id, admin_slug, admin_name, "human", hashed, "super_admin"),
-        )
-        conn.commit()
-        logger.info("Migration 016: seeded admin user '%s' (super_admin)", admin_slug)
+        # Prefer a pre-hashed password (canonical MARVIS_ADMIN_PASSWORD_HASH;
+        # PIR_ADMIN_PASSWORD_HASH stays a deprecated alias).
+        hashed = (
+            os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
+            or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
+        ).strip()
+        if not hashed:
+            seed_password = (
+                os.environ.get("MARVIS_PASSWORD")
+                or os.environ.get("PIR_PASSWORD", "")
+            ).strip()
+            if seed_password:
+                import bcrypt
+
+                hashed = bcrypt.hashpw(
+                    seed_password.encode("utf-8"), bcrypt.gensalt()
+                ).decode()
+            else:
+                logger.warning(
+                    "Migration 016: no MARVIS_ADMIN_PASSWORD_HASH / MARVIS_PASSWORD in "
+                    "env — admin user NOT seeded (schema applied). Single-user CLI uses "
+                    "the local context (no login); create an admin later with `marvis "
+                    "init` if you want HTTP login."
+                )
+        if hashed:  # seed ONLY when we actually have a credential
+            admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
+            admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"
+            admin_name = os.environ.get("MARVIS_ADMIN_DISPLAY_NAME", "").strip() or "Admin"
+            conn.execute(
+                "INSERT OR IGNORE INTO users "
+                "(id, slug, display_name, type, password_hash, system_role) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (admin_id, admin_slug, admin_name, "human", hashed, "super_admin"),
+            )
+            conn.commit()
+            logger.info("Migration 016: seeded admin user '%s' (super_admin)", admin_slug)
 
     # Data migration: owner_id may contain slug strings (e.g. "emilio") from before
     # the users table existed. Resolve each slug to the corresponding users.id.

{marvisx_cli-0.3.8b1 → marvisx_cli-0.3.8b3}/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.8b3}/core/api/mcp/server.py

@@ -34,10 +34,54 @@ 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"
+    "Before answering an orchestration or planning task, confirm you actually called the relevant "
+    "tool (session_brief / project_impact / graph_impact) AND that your answer addresses the task "
+    "as asked — do not reply from raw files or pivot to an unrelated skill.\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.8b3}/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.8b3}/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.8b3}/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.8b3/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