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

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

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

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

@@ -125,6 +125,13 @@ class Settings(BaseSettings):
         default=86400, alias="BRAIN_WAREHOUSE_CONSOLIDATION_INTERVAL_SECONDS"
     )
 
+    # KG temporal recency pass (Fase D producer): proposes re-verifying aging,
+    # never-verified live nodes. Gated by temporal_memory_enabled (no separate
+    # enable flag — the flag IS the gate). Daily cadence guard.
+    brain_temporal_recency_interval_seconds: int = Field(
+        default=86400, alias="BRAIN_TEMPORAL_RECENCY_INTERVAL_SECONDS"
+    )
+
     # GitHub Webhook
     github_webhook_secret: str = ""
 
@@ -475,6 +482,16 @@ class Settings(BaseSettings):
         default=False, alias="MARVIS_TEMPORAL_MEMORY"
     )
 
+    # answer-ready claims (DEFAULT OFF). When False every reasoning-tool read is
+    # byte-identical to today (no `claims` key). When True, project_impact/
+    # graph_impact append a `claims[]` block: server-computed, relation-typed
+    # counts with provenance — the agent reports the value instead of re-counting
+    # raw edges (faithfulness). Separate from temporal_memory so grounding can be
+    # enabled without the freshness surface. See plan 2026-06-08-feat-answer-ready-claims.
+    kg_claims_enabled: bool = Field(
+        default=False, alias="MARVIS_KG_CLAIMS"
+    )
+
     # Track 2 #3c — community summaries in the brief (GraphRAG global-search,
     # DEFAULT OFF). When False the brief is byte-identical to today: the
     # communities/community_summary modules are a flag-gated library + seam,

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

@@ -739,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.8b2 → marvisx_cli-0.3.8b4}/core/api/mcp/server.py

@@ -43,6 +43,13 @@ _INSTRUCTIONS = (
     "- '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"
+    "When you state a number from the knowledge graph (a count, in-degree, how many dependents), "
+    "quote it from the tool result's `summary` block and cite it inline — e.g. \"148 edges from 11 "
+    "sources [graph_neighbors summary]\". Do NOT re-count a returned list by hand, and do NOT state a "
+    "count that no tool result supports.\n"
 )
 
 mcp = FastMCP("marvis", instructions=_INSTRUCTIONS)

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

@@ -124,9 +124,10 @@ def register(mcp) -> None:
         as_of: Annotated[str, Field(pattern=_AS_OF_PATTERN, max_length=32)] | None = None,
     ) -> dict[str, Any]:
         """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."""
+        CHI DIPENDE DA X (in UNA call): graph_neighbors(node_id, direction='incoming', rank='degree') → i dipendenti diretti ordinati per grado + un blocco `summary` GIA' aggregato. E' il tool ovvio per 'chi cita / dipende da X' — NON fare N micro-query (project_impact e' il primo passo, non N).
+        ORCHESTRAZIONE: per i vicini diretti di un PROGETTO passa node_id='project:artifact:<slug>' con edge_types=['depends_on']. Codice: caller/callee 1-hop di una function.
+        QUANDO USARLO: vicinato diretto; 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: {neighbors:[{node_id, relation, direction, rank_score?}], summary:{total, distinct_nodes, by_relation, by_direction} (CITA questi numeri, non ricontare la lista), freshness} cap 200."""
         try:
             async with acquire_db() as db:
                 # Node proxy hardcodes limit=200 (the surface exposes no limit param).
@@ -205,7 +206,7 @@ def register(mcp) -> None:
         """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}."""
+        RESTITUISCE: {direct_dependents[], transitive_list[], rank_score, freshness}. Col flag MARVIS_KG_CLAIMS anche claims[]: quanti progetti dipendono DAVVERO da questo (kind=dependents_depends_on) vs quanti lo nominano soltanto (kind=mentioned_by), gia' contati server-side con provenienza e freschezza — riporta quei numeri, non ri-contare le liste."""
         try:
             async with acquire_db() as db:
                 result = await graph_uc.graph_impact(

{marvisx_cli-0.3.8b2 → marvisx_cli-0.3.8b4}/core/api/models/graph_ux.py

@@ -13,7 +13,38 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# ---------------------------------------------------------------------------
+# answer-ready claims (behind MARVIS_KG_CLAIMS) — server-computed, relation-typed
+# ---------------------------------------------------------------------------
+
+class KGClaim(BaseModel):
+    """A server-computed claim about a KG node: the value is counted by the DB,
+    not by the agent. The agent reports it (and the relation) instead of
+    re-counting raw edges — this is the faithfulness fix.
+
+    `kind` names the relation explicitly (e.g. `dependents_depends_on` = real
+    dependency, `mentioned_by` = associative, NOT a dependency). `sources` is a
+    capped sample of the provenance; `sources_total` is the full count.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str = Field(..., description="dependents_depends_on | dependents_imports | dependents_calls | mentioned_by")
+    subject: str = Field(..., description="node_id the claim is about")
+    value: int = Field(..., ge=0, description="server-computed count (the number to report)")
+    sources: list[str] = Field(default_factory=list, description="capped sample of source node ids (provenance)")
+    sources_total: int = Field(..., ge=0, description="full provenance count before capping")
+    as_of: str | None = Field(None, description="last observation (last_seen_at) of the subject")
+    verified: str | None = Field(None, description="last Brain re-confirmation (last_verified_at), or null")
+    needs_review: bool = Field(False, description="subject is stale per the read-time freshness budget")
+
+    @model_validator(mode="after")
+    def _sources_within_total(self) -> "KGClaim":
+        if self.sources_total < len(self.sources):
+            raise ValueError("sources_total must be >= len(sources)")
+        return self
+
 
 # ---------------------------------------------------------------------------
 # Shared type alias (validated at model-field level via annotation)
@@ -47,6 +78,36 @@ class PinOut(BaseModel):
     is_stale: bool = False  # True if node was soft-deleted after pinning (belt-and-braces)
 
 
+# ---------------------------------------------------------------------------
+# Fase D — KG trust write-path request bodies (behind MARVIS_TEMPORAL_MEMORY).
+# The apply actions an agent performs after Triage approves a Brain proposal.
+# ---------------------------------------------------------------------------
+
+class VerifyNodeIn(BaseModel):
+    """Request body for POST /graph/nodes/verify — stamp last_verified_at = now."""
+    node_id: str = Field(
+        ...,
+        min_length=6,
+        max_length=256,
+        pattern=r"^[a-z]+:[a-z]+:.+$",
+        description="Node ID to mark re-verified (REINFORCE apply)",
+    )
+
+
+class SupersedeEdgeIn(BaseModel):
+    """Request body for POST /graph/edges/supersede — soft-invalidate an edge."""
+    source_id: str = Field(..., min_length=6, max_length=256, pattern=r"^[a-z]+:[a-z]+:.+$")
+    target_id: str = Field(..., min_length=6, max_length=256, pattern=r"^[a-z]+:[a-z]+:.+$")
+    relation: str = Field(
+        ..., min_length=2, max_length=32,
+        description="Edge relation of the triple to supersede (e.g. depends_on)",
+    )
+    superseded_by: str | None = Field(
+        None, max_length=256,
+        description="Optional audit pointer to the replacing edge",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Landing bundle
 # ---------------------------------------------------------------------------

{marvisx_cli-0.3.8b2 → marvisx_cli-0.3.8b4}/core/api/routers/graph.py

@@ -79,6 +79,8 @@ from core.api.models.graph_ux import (
     PinIn,
     PinOut,
     ResolveOut,
+    SupersedeEdgeIn,
+    VerifyNodeIn,
 )
 from core.api.models.graph_cosmo import GraphCosmoOut
 from core.api.rate_limit import limiter
@@ -701,6 +703,54 @@ async def delete_graph_pin(
     return result
 
 
+# --- KG trust write-path (Fase D, behind MARVIS_TEMPORAL_MEMORY) ---
+
+@router.post("/nodes/verify", response_model=dict, summary="Mark a KG node re-verified")
+@limiter.limit("60/minute")
+async def mark_node_verified(
+    body: VerifyNodeIn,
+    request: Request,
+    user: UserInfo = Depends(get_current_user_or_agent),
+    db: aiosqlite.Connection = Depends(get_write_db),
+) -> dict:
+    """Stamp graph_nodes.last_verified_at = now (REINFORCE apply).
+
+    The action an agent performs after Triage approves a Brain recency proposal.
+    Inert (422) when MARVIS_TEMPORAL_MEMORY is off. 404 if the node is missing.
+    """
+    ctx = CallerContext.from_user_info(user, is_human_session=False)
+    try:
+        return await uc.mark_node_verified(ctx, db, node_id=body.node_id)
+    except ServiceError as e:
+        raise to_http_legacy(e)
+
+
+@router.post("/edges/supersede", response_model=dict, summary="Soft-invalidate a KG edge")
+@limiter.limit("60/minute")
+async def mark_edge_superseded(
+    body: SupersedeEdgeIn,
+    request: Request,
+    user: UserInfo = Depends(get_current_user_or_agent),
+    db: aiosqlite.Connection = Depends(get_write_db),
+) -> dict:
+    """Set graph_edges.valid_until = now (+ optional superseded_by) on a triple.
+
+    SUPERSEDE / CONTRADICTION apply. Soft, never deletes. Inert (422) when the
+    flag is off. 404 if the triple is absent.
+    """
+    ctx = CallerContext.from_user_info(user, is_human_session=False)
+    try:
+        return await uc.mark_edge_superseded(
+            ctx, db,
+            source_id=body.source_id,
+            target_id=body.target_id,
+            relation=body.relation,
+            superseded_by=body.superseded_by,
+        )
+    except ServiceError as e:
+        raise to_http_legacy(e)
+
+
 # --- Resolve file path → node_id ---
 
 @router.get("/resolve", response_model=ResolveOut, summary="Resolve file path to KG node")

{marvisx_cli-0.3.8b2 → marvisx_cli-0.3.8b4}/core/api/services/brain/jobs.py

@@ -237,6 +237,40 @@ async def _warehouse_consolidation_due(
     return elapsed >= interval_seconds
 
 
+async def _temporal_recency_due(
+    *, workspace_id: str, now: datetime, interval_seconds: int
+) -> bool:
+    """Daily cadence guard for the KG temporal recency pass (Fase D).
+
+    Derives "last run" from the newest persisted recency proposal — these are
+    `operation_type='reinforce'` ops whose proposed_write target_type is 'none'
+    (M1 reinforce uses 'kg_edge_metric', so this filter isolates the recency
+    pass). Idempotent regardless (operation_id collision dedups within a cycle),
+    so a missing/unparseable timestamp falls back to "due".
+    """
+    if interval_seconds <= 0:
+        return True
+    async with acquire_db() as db:
+        row = await (
+            await db.execute(
+                "SELECT MAX(detected_at) FROM brain_memory_operations"
+                " WHERE operation_type = 'reinforce'"
+                "  AND proposed_write_target_type = 'none'",
+            )
+        ).fetchone()
+    last_raw = row[0] if row else None
+    if not last_raw:
+        return True
+    try:
+        last_dt = datetime.fromisoformat(str(last_raw).replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    if last_dt.tzinfo is None:
+        last_dt = last_dt.replace(tzinfo=timezone.utc)
+    elapsed = (now.astimezone(timezone.utc) - last_dt.astimezone(timezone.utc)).total_seconds()
+    return elapsed >= interval_seconds
+
+
 def _cycle_window_from_key(
     cycle_key: str, *, cutoff_hour_utc: int
 ) -> tuple[datetime, datetime]:
@@ -563,6 +597,44 @@ async def _execute_cycle(
                     SourceFailure(source_system="warehouse_consolidation", error=str(exc))
                 )
 
+        # Phase 4c — KG temporal recency (Fase D producer). Ships DORMANT: gated
+        # on temporal_memory_enabled (the MARVIS_TEMPORAL_MEMORY flag IS the gate;
+        # default off → skipped). When on, a daily cadence guard bounds re-emission.
+        # PROPOSALS only — never auto-applied. Isolated try/except so it can NEVER
+        # crash the cycle.
+        if app_settings.temporal_memory_enabled:
+            try:
+                from core.api.services.brain.temporal_recency import (
+                    run_temporal_recency,
+                )
+
+                if await _temporal_recency_due(
+                    workspace_id=workspace_id,
+                    now=now,
+                    interval_seconds=app_settings.brain_temporal_recency_interval_seconds,
+                ):
+                    tr_summary = await run_temporal_recency(
+                        run_id=run_id,
+                        cycle_key=cycle_key,
+                        workspace_id=workspace_id,
+                        now=now,
+                    )
+                    logger.info(
+                        "brain.jobs: temporal recency run_id=%s summary=%s",
+                        run_id,
+                        tr_summary,
+                    )
+                else:
+                    logger.info(
+                        "brain.jobs: temporal recency skipped (cadence guard) run_id=%s",
+                        run_id,
+                    )
+            except Exception as exc:  # noqa: BLE001 — phase-level isolation
+                logger.exception("brain.jobs: temporal recency failed")
+                failures.append(
+                    SourceFailure(source_system="temporal_recency", error=str(exc))
+                )
+
         # Phase 5 — Learn Findings (sub-04). Final L5 phase of the cycle.
         # Consumes digest events + journal entries + drift signals + memory
         # operations of the current run_id (NEVER re-reads substrate).

{marvisx_cli-0.3.8b2 → marvisx_cli-0.3.8b4}/core/api/services/brain/memory_ops.py

@@ -1519,10 +1519,21 @@ def _next_action_for(op: MemoryOperation) -> ApplyNextAction:
     target_type = pw.target_type  # type: ignore[union-attr]
 
     if op.operation_type == "reinforce":
-        tool = None
-        rationale = "reinforce produces edge metric evidence only; v2 may write to graph_edge_metrics."
-        if hasattr(pw, "edge_id"):
-            args = {"edge_id": pw.edge_id, "metric_kind": pw.metric_kind, "delta": pw.delta}
+        if target_type == "none":
+            # Fase D temporal recency: bump the node's last_verified_at via the
+            # write-path tool (proposed_write is `none`; the node id rides in
+            # source_ref). Guidance-only: the operator/agent runs the tool.
+            tool = "mcp__marvis__mark_kg_verified"
+            args = {"node_id": op.source_ref}
+            rationale = (
+                "Temporal recency: this live node is aging and never verified. "
+                "Approve → mark_kg_verified stamps last_verified_at so it reads fresh."
+            )
+        else:
+            tool = None
+            rationale = "reinforce produces edge metric evidence only; v2 may write to graph_edge_metrics."
+            if hasattr(pw, "edge_id"):
+                args = {"edge_id": pw.edge_id, "metric_kind": pw.metric_kind, "delta": pw.delta}
     elif op.operation_type == "cascade_rollup":
         tool = None
         rationale = "Cascade rollup is apply-guidance-only. Operator appends body to parent context.md."

marvisx_cli-0.3.8b4/core/api/services/brain/temporal_recency.py

@@ -0,0 +1,195 @@
+# Brain v1 — Temporal recency pass (Fase D producer, KG freshness/trust).
+#
+# WHY this exists:
+#   The graph now carries graph_nodes.last_verified_at (mig 149) and the
+#   read-time needs_review (Fase A + D read-wiring) treats a re-verified node as
+#   fresh. This pass is the "suggester": it scans the graph for live nodes that
+#   are AGING (last seen a while ago) and NEVER explicitly verified, and PROPOSES
+#   a `reinforce` (bump last_verified_at) in the Triage queue. Approving one then
+#   calls mark_kg_verified (D write-path) → the node reads as fresh again.
+#
+# Mechanical, NO LLM (recency is mechanical per the plan). The LLM judgment for
+# supersede/contradiction on derived edges is deferred to a follow-up.
+#
+# Layering invariants (mirror warehouse_consolidate):
+#   * NO LLM imports. NO substrate mutation (read-only scan; proposals only).
+#   * READ pool (acquire_db) for the scan — never hold the writer across it.
+#   * Reuses the memory_ops persist path (finalize_operation + _persist_operations)
+#     → proposals land as approval_state='pending', NEVER auto-applied.
+#   * Gated by MARVIS_TEMPORAL_MEMORY in jobs.py → dormant when off.
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+import aiosqlite
+
+from core.api.db import acquire_db
+from core.api.services.brain.compound_bridge import proposed_write_none
+from core.api.services.brain.memory_ops import (
+    OperationDraft,
+    _persist_operations,
+    _project_scope,
+    finalize_operation,
+)
+
+logger = logging.getLogger(__name__)
+
+# Node kinds worth re-verifying (skip noisy/derived kinds like commit/inbox).
+RECHECK_TYPES: tuple[str, ...] = (
+    "function", "file", "module", "task", "project", "handoff", "learning",
+    "doc", "pr", "plan", "solution",
+)
+# A node is a candidate once it has not been observed for at least this long
+# (aging — at risk of false-positive staleness) yet is still live + unverified.
+MIN_AGE_DAYS: int = 14
+# Hard cap per cycle — proposals are a Triage signal, never a flood.
+MAX_CANDIDATES: int = 25
+# Re-nag suppression window: a node dismissed/rejected within this many days is
+# not re-proposed (respects the operator's "no"). A still-pending proposal is
+# always suppressed regardless of age (no duplicate while one is open).
+SUPPRESS_DISMISSED_DAYS: int = 30
+
+
+@dataclass(slots=True, frozen=True)
+class _NodeRow:
+    node_id: str
+    node_type: str
+    project_id: str | None
+    last_seen_at: str | None
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    try:
+        dt = datetime.fromisoformat(str(value).replace(" ", "T").replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _scan_query(*, now: datetime) -> tuple[str, list]:
+    """(sql, params) for the candidate scan — pure, so it's unit-testable.
+
+    Robust to mixed 'YYYY-MM-DD HH:MM:SS' / ISO-'T' last_seen_at (datetime() both
+    sides). The NOT EXISTS guard is the re-nag brake: skip a node that already
+    has a recency proposal (reinforce + target_type='none') still PENDING (no
+    duplicate while one is open), or DISMISSED/REJECTED within
+    SUPPRESS_DISMISSED_DAYS (respect the operator's "no"). Without it the
+    cycle-key-scoped operation_id would mint a fresh proposal every night.
+    """
+    aging_cutoff = (now.astimezone(timezone.utc) - timedelta(days=MIN_AGE_DAYS)).strftime(
+        "%Y-%m-%d %H:%M:%S"
+    )
+    suppress_cutoff = (
+        now.astimezone(timezone.utc) - timedelta(days=SUPPRESS_DISMISSED_DAYS)
+    ).strftime("%Y-%m-%d %H:%M:%S")
+    placeholders = ",".join("?" * len(RECHECK_TYPES))
+    sql = (
+        "SELECT n.id, n.type, n.project_id, n.last_seen_at FROM graph_nodes n "
+        "WHERE n.deprecated_at IS NULL AND n.last_verified_at IS NULL "
+        "AND n.last_seen_at IS NOT NULL "
+        f"AND n.type IN ({placeholders}) "
+        "AND datetime(n.last_seen_at) <= datetime(?) "
+        "AND NOT EXISTS ("
+        "  SELECT 1 FROM brain_memory_operations o "
+        "  WHERE o.source_ref = n.id "
+        "    AND o.operation_type = 'reinforce' "
+        "    AND o.proposed_write_target_type = 'none' "
+        "    AND (o.approval_state = 'pending' "
+        "         OR (o.approval_state IN ('dismissed','rejected') "
+        "             AND datetime(o.detected_at) >= datetime(?)))"
+        ") "
+        "ORDER BY datetime(n.last_seen_at) ASC LIMIT ?"
+    )
+    params = [*RECHECK_TYPES, aging_cutoff, suppress_cutoff, MAX_CANDIDATES]
+    return sql, params
+
+
+async def _scan_aging_unverified_nodes(*, now: datetime) -> list[_NodeRow]:
+    """Live, significant, never-verified, aging nodes — minus those already
+    proposed/recently-dismissed (see _scan_query). Read pool; capped, oldest-first.
+    """
+    sql, params = _scan_query(now=now)
+    async with acquire_db() as db:
+        db.row_factory = aiosqlite.Row
+        rows = await (await db.execute(sql, params)).fetchall()
+    return [
+        _NodeRow(
+            node_id=str(r["id"]),
+            node_type=str(r["type"]),
+            project_id=r["project_id"],
+            last_seen_at=r["last_seen_at"],
+        )
+        for r in rows
+    ]
+
+
+def build_recency_drafts(nodes: list[_NodeRow], *, now: datetime) -> list[OperationDraft]:
+    """One `reinforce` proposal per aging-unverified node. Deterministic.
+
+    proposed_write = none (no CHECK-migration needed); the node id rides in
+    source_ref, which the apply-guidance hands to mark_kg_verified. Evidence is
+    a single stable ref (`kg_node:<id>`) → stable evidence_hash → idempotent:
+    re-detecting the same node bumps recurrence rather than duplicating.
+    """
+    drafts: list[OperationDraft] = []
+    for n in sorted(nodes, key=lambda x: x.node_id):
+        scope_type, scope_key = _project_scope(n.project_id)
+        seen = _parse_iso(n.last_seen_at)
+        age_days = int((now - seen).total_seconds() // 86400) if seen else None
+        age_txt = f"{age_days}d ago" if age_days is not None else "long ago"
+        # Older → higher priority; clamped to [0, 1].
+        score = min(1.0, 0.4 + (age_days or 0) / 180.0)
+        drafts.append(
+            OperationDraft(
+                operation_type="reinforce",
+                scope_type=scope_type,
+                scope_key=scope_key,
+                program_key=None,
+                source_ref=n.node_id,
+                target_ref="",
+                evidence=[f"kg_node:{n.node_id}"],
+                summary=(
+                    f"Re-verify {n.node_type} {n.node_id}: live but last seen "
+                    f"{age_txt}, never verified. Approve → mark_kg_verified bumps "
+                    "last_verified_at so it reads fresh again."
+                ),
+                proposed_write=proposed_write_none(),
+                involved_projects=[n.project_id] if n.project_id else [],
+                score=score,
+            )
+        )
+    return drafts
+
+
+async def run_temporal_recency(
+    *,
+    run_id: str,
+    cycle_key: str,
+    workspace_id: str = "ws_default",
+    now: datetime,
+) -> dict[str, int]:
+    """Aging-node re-verification pass. PROPOSALS ONLY (approval_state=pending).
+
+    Reuses the memory_ops persist path so re-runs are idempotent (stable
+    operation_id collides on the natural key). Returns a small summary dict.
+    """
+    now = now.astimezone(timezone.utc)
+    nodes = await _scan_aging_unverified_nodes(now=now)
+    drafts = build_recency_drafts(nodes, now=now)
+    operations = [
+        finalize_operation(draft=d, run_id=run_id, cycle_key=cycle_key, now=now)
+        for d in drafts
+    ]
+    persisted, _recurrence_keys = await _persist_operations(
+        run_id=run_id, operations=operations
+    )
+    return {"candidates": len(nodes), "operations_persisted": persisted}
+
+
+__all__ = ["build_recency_drafts", "run_temporal_recency"]