ltcai 9.9.1 → 9.9.3

package/lattice_brain/graph/fusion.py

@@ -0,0 +1,179 @@
+"""Query-class aware retrieval fusion weights (backlog #5, review §7.2 E).
+
+Hybrid retrieval fuses keyword/lexical, vector, and graph channels. A single
+static weight set treats "이 함수 왜 죽어?" and "어제 회의에서 뭐 결정했지?"
+identically, which is measurably wrong: code questions live on exact
+identifiers (lexical), person questions lean on relationship edges (graph),
+recency questions need fresher lexical hits over semantic neighbors.
+
+This module is deliberately tiny and deterministic:
+
+* :func:`classify_query` — pure ko/en heuristics → ``fact | code | person |
+  recency`` (``fact`` is the fallback class and its weights are identical to
+  the historical defaults, so fact-class behavior is byte-compatible).
+* :data:`DEFAULT_FUSION_WEIGHTS` — the per-class weight table. ``keyword`` /
+  ``vector`` / ``graph`` feed the three-channel service fusion
+  (``SearchService.hybrid_search``); ``alpha`` is the vector share for the
+  two-channel graph-layer fusion (``KnowledgeGraphStore.hybrid_search``).
+* :func:`fusion_profile` — classify + resolve weights, honoring the
+  ``LATTICEAI_FUSION_WEIGHTS`` env override (JSON, partial per-class merges,
+  e.g. ``{"code": {"alpha": 0.2}}``).
+
+Never uses ``or`` on scores (score 0 is falsy but valid) and never raises:
+a malformed override is ignored, an unknown class falls back to ``fact``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, Mapping, Optional
+
+QUERY_CLASSES = ("fact", "code", "person", "recency")
+
+FUSION_WEIGHTS_ENV = "LATTICEAI_FUSION_WEIGHTS"
+
+# Per-class fusion weights. "fact" mirrors the pre-fusion-gate defaults
+# (SearchService DEFAULT_HYBRID_WEIGHTS + graph-layer alpha=0.6) so the
+# fallback class introduces zero behavioral drift.
+DEFAULT_FUSION_WEIGHTS: Dict[str, Dict[str, float]] = {
+    "fact": {"keyword": 0.35, "vector": 0.40, "graph": 0.25, "alpha": 0.60},
+    # Code recall lives on exact identifiers/tokens → lexical dominates.
+    "code": {"keyword": 0.55, "vector": 0.25, "graph": 0.20, "alpha": 0.35},
+    # Person questions are relationship questions → graph channel leads.
+    "person": {"keyword": 0.30, "vector": 0.30, "graph": 0.40, "alpha": 0.45},
+    # Recency questions want fresh literal hits over semantic neighbors.
+    "recency": {"keyword": 0.45, "vector": 0.35, "graph": 0.20, "alpha": 0.50},
+}
+
+# ── query-class heuristics (pure, ko/en) ─────────────────────────────────────
+
+_CODE_FENCE_RE = re.compile(r"```|`[^`\n]+`")
+_CODE_IDENT_RE = re.compile(
+    # ``\b`` fails between an identifier and an attached Korean particle
+    # ("ingest_folder가"), so use explicit ASCII-boundary lookbehinds instead.
+    r"[A-Za-z_][A-Za-z0-9_]*\(\)"                      # call syntax foo()
+    r"|(?<![A-Za-z0-9_])[a-z0-9]+_[a-z0-9_]+"          # snake_case
+    r"|(?<![A-Za-z0-9_])[a-z]+[A-Z][A-Za-z0-9]*"       # camelCase
+    r"|(?<![A-Za-z0-9_])[\w-]+\.(?:py|js|jsx|ts|tsx|json|yaml|yml|css|html|sql|sh|go|rs|java|rb)(?![A-Za-z0-9])"
+)
+_CODE_WORD_RE = re.compile(
+    r"\b(?:def|class|import|function|traceback|exception|stack\s*trace|"
+    r"bug|error|null|undefined|api|sql|regex)\b"
+    r"|코드|함수|버그|에러|오류|스택|컴파일|빌드\s*실패|구현",
+    re.IGNORECASE,
+)
+_PERSON_RE = re.compile(
+    r"\b(?:who|whom|whose)\b|누구|어떤\s*사람|담당자|팀원|동료|만난\s*사람"
+    r"|[\w.+-]+@[\w-]+\.[\w.]+"        # an email address names a person
+    r"|[가-힣]{2,4}\s*(?:님|씨)(?:\s|$|[을를이가은는의??.!,])",
+    re.IGNORECASE,
+)
+_RECENCY_RE = re.compile(
+    r"최근|어제|오늘|그저께|방금|아까|지난\s*주|지난주|지난\s*달|지난달"
+    r"|이번\s*주|이번주|이번\s*달|이번달"
+    r"|\b(?:recent|recently|yesterday|today|latest|last\s+(?:week|month|night|meeting))\b",
+    re.IGNORECASE,
+)
+
+
+def classify_query(query: Any) -> str:
+    """Classify a retrieval query into fact / code / person / recency.
+
+    Precedence: code (strongest structural signal) → recency (explicit time
+    words) → person → fact. Deterministic, never raises, empty → fact.
+    """
+    text = str(query or "").strip()
+    if not text:
+        return "fact"
+    if _CODE_FENCE_RE.search(text) or _CODE_IDENT_RE.search(text) or _CODE_WORD_RE.search(text):
+        return "code"
+    if _RECENCY_RE.search(text):
+        return "recency"
+    if _PERSON_RE.search(text):
+        return "person"
+    return "fact"
+
+
+def _env_overrides() -> Dict[str, Dict[str, float]]:
+    """Parse LATTICEAI_FUSION_WEIGHTS (JSON) → per-class partial overrides."""
+    raw = os.getenv(FUSION_WEIGHTS_ENV, "").strip()
+    if not raw:
+        return {}
+    try:
+        payload = json.loads(raw)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    overrides: Dict[str, Dict[str, float]] = {}
+    for cls, table in payload.items():
+        if cls not in DEFAULT_FUSION_WEIGHTS or not isinstance(table, dict):
+            continue
+        cleaned: Dict[str, float] = {}
+        for key, value in table.items():
+            if key not in ("keyword", "vector", "graph", "alpha"):
+                continue
+            try:
+                cleaned[key] = max(0.0, min(1.0, float(value)))
+            except (TypeError, ValueError):
+                continue
+        if cleaned:
+            overrides[str(cls)] = cleaned
+    return overrides
+
+
+def fusion_weight_table(
+    overrides: Optional[Mapping[str, Mapping[str, float]]] = None,
+) -> Dict[str, Dict[str, float]]:
+    """Full per-class table: defaults ← env override ← caller override."""
+    table = {cls: dict(weights) for cls, weights in DEFAULT_FUSION_WEIGHTS.items()}
+    for source in (_env_overrides(), overrides or {}):
+        for cls, partial in source.items():
+            if cls in table and isinstance(partial, Mapping):
+                for key, value in partial.items():
+                    if key in table[cls]:
+                        try:
+                            table[cls][key] = max(0.0, min(1.0, float(value)))
+                        except (TypeError, ValueError):
+                            continue
+    return table
+
+
+def fusion_profile(
+    query: Any,
+    *,
+    overrides: Optional[Mapping[str, Mapping[str, float]]] = None,
+) -> Dict[str, Any]:
+    """Classify ``query`` and return its resolved fusion weights.
+
+    Returns ``{"query_class": str, "weights": {keyword, vector, graph},
+    "alpha": float}``. ``weights`` feeds the three-channel service fusion;
+    ``alpha`` feeds the two-channel graph-layer fusion.
+    """
+    query_class = classify_query(query)
+    table = fusion_weight_table(overrides)
+    resolved = table.get(query_class)
+    if resolved is None:  # defensive — classify_query only emits known classes
+        query_class = "fact"
+        resolved = table["fact"]
+    return {
+        "query_class": query_class,
+        "weights": {
+            "keyword": resolved["keyword"],
+            "vector": resolved["vector"],
+            "graph": resolved["graph"],
+        },
+        "alpha": resolved["alpha"],
+    }
+
+
+__all__ = [
+    "DEFAULT_FUSION_WEIGHTS",
+    "FUSION_WEIGHTS_ENV",
+    "QUERY_CLASSES",
+    "classify_query",
+    "fusion_profile",
+    "fusion_weight_table",
+]

package/lattice_brain/graph/projection.py

@@ -514,6 +514,167 @@ class KnowledgeGraphProjectionMixin:
             "skipped_total": len(overlay["skipped"]),
         }
 
+    _NOISE_CONTENT_TYPES = (
+        "Document",
+        "File",
+        "CodeFile",
+        "Message",
+        "AIResponse",
+        "Chat",
+        "Page",
+        "Slide",
+        "Spreadsheet",
+    )
+    _NOISE_CONCEPT_TYPES = ("Concept", "Feature", "Topic", "Code", "Error")
+
+    def curate_noise(
+        self,
+        *,
+        dry_run: bool = True,
+        max_df_ratio: float = 0.8,
+        min_doc_frequency: int = 1,
+        min_corpus_docs: int = 5,
+        normalize_verbs: bool = True,
+        max_removals: int = 200,
+    ) -> Dict[str, Any]:
+        """Noise-reduction curation job (backlog #10, review §7.2 D).
+
+        (a) Removes heuristic concept nodes (``auto_extracted`` /
+        ``graph_curator``-promoted) whose document frequency marks them as
+        noise: ubiquitous (low IDF — linked from more than ``max_df_ratio`` of
+        content docs once the corpus has ``min_corpus_docs``) or below the
+        ``min_doc_frequency`` floor. Explicitly user-created nodes are never
+        touched, whatever their stats.
+
+        (b) Normalizes free-string relation verbs on the legacy edge table via
+        the ko/en dictionary in :mod:`lattice_brain.graph.curator`
+        ('만들다/만든/creates' → 'created', …), merging rows that collide
+        after the rename.
+
+        ``dry_run=True`` (the default) only *reports* what would change.
+        """
+        from .curator import (
+            build_relation_verb_index,
+            plan_concept_noise_reduction,
+            plan_relation_normalization,
+        )
+
+        max_removals = max(0, int(max_removals))
+        # Operate on the legacy write tables directly: they are the mutation
+        # target, and raw free-string verbs only exist there (the v4 write
+        # door normalizes new edges; the kgv2_* read views collapse
+        # legacy_type and would hide exactly the rows this job cleans up).
+        nt, et = "nodes", "edges"
+        with self._connect() as conn:
+            content_ph = ",".join("?" for _ in self._NOISE_CONTENT_TYPES)
+            total_docs = conn.execute(
+                f"SELECT COUNT(*) AS c FROM {nt} WHERE type IN ({content_ph})",
+                self._NOISE_CONTENT_TYPES,
+            ).fetchone()["c"]
+
+            concept_ph = ",".join("?" for _ in self._NOISE_CONCEPT_TYPES)
+            concept_rows = conn.execute(
+                f"SELECT id, type, title, metadata_json FROM {nt} WHERE type IN ({concept_ph})",
+                self._NOISE_CONCEPT_TYPES,
+            ).fetchall()
+            concepts = []
+            for row in concept_rows:
+                meta = _safe_loads(row["metadata_json"]) or {}
+                heuristic = bool(meta.get("auto_extracted")) or (
+                    meta.get("source") == "graph_curator" or meta.get("curated") is True
+                )
+                # Document frequency: distinct *content* nodes linked to this
+                # concept in either direction.
+                df = conn.execute(
+                    f"""
+                    SELECT COUNT(DISTINCT n.id) AS c
+                    FROM {et} e
+                    JOIN {nt} n
+                      ON n.id = CASE WHEN e.to_node = ? THEN e.from_node ELSE e.to_node END
+                    WHERE (e.to_node = ? OR e.from_node = ?)
+                      AND n.type IN ({content_ph})
+                    """,
+                    (row["id"], row["id"], row["id"], *self._NOISE_CONTENT_TYPES),
+                ).fetchone()["c"]
+                concepts.append({
+                    "id": row["id"],
+                    "label": row["title"],
+                    "type": row["type"],
+                    "df": int(df or 0),
+                    "heuristic": heuristic,
+                })
+
+            plan = plan_concept_noise_reduction(
+                concepts,
+                total_docs,
+                max_df_ratio=max_df_ratio,
+                min_doc_frequency=min_doc_frequency,
+                min_corpus_docs=min_corpus_docs,
+            )
+            removals = plan["remove"][:max_removals]
+
+            verb_index = build_relation_verb_index()
+            edge_type_rows = conn.execute(
+                f"SELECT DISTINCT type FROM {et}"
+            ).fetchall()
+            verb_plan = (
+                plan_relation_normalization(
+                    (row["type"] for row in edge_type_rows), index=verb_index,
+                )
+                if normalize_verbs
+                else {}
+            )
+
+            removed_count = 0
+            renamed_edges = 0
+            if not dry_run:
+                for decision in removals:
+                    node_id = decision["id"]
+                    conn.execute(
+                        "DELETE FROM edges WHERE from_node=? OR to_node=?",
+                        (node_id, node_id),
+                    )
+                    conn.execute(
+                        "DELETE FROM vector_embeddings WHERE item_id=?", (node_id,)
+                    )
+                    conn.execute("DELETE FROM nodes WHERE id=?", (node_id,))
+                    self._v2_delete_nodes(conn, [node_id])
+                    removed_count += 1
+                for original, canonical in verb_plan.items():
+                    renamed_edges += conn.execute(
+                        "SELECT COUNT(*) AS c FROM edges WHERE type=?", (original,)
+                    ).fetchone()["c"]
+                    # UNIQUE(from_node, to_node, type): merge rows that collide
+                    # after the rename instead of failing the UPDATE.
+                    conn.execute(
+                        "UPDATE OR IGNORE edges SET type=? WHERE type=?",
+                        (canonical, original),
+                    )
+                    conn.execute("DELETE FROM edges WHERE type=?", (original,))
+
+        return {
+            "status": "ok",
+            "dry_run": bool(dry_run),
+            "total_content_docs": int(total_docs or 0),
+            "concepts_examined": len(concepts),
+            "remove": removals,
+            "remove_total": len(plan["remove"]),
+            "kept": len(plan["keep"]),
+            "protected_user_nodes": sum(
+                1 for item in plan["keep"] if item.get("reason") == "user_created_protected"
+            ),
+            "verb_normalizations": verb_plan,
+            "applied": {
+                "removed_nodes": removed_count,
+                "renamed_edges": renamed_edges,
+            },
+            "thresholds": {
+                "max_df_ratio": float(max_df_ratio),
+                "min_doc_frequency": int(min_doc_frequency),
+                "min_corpus_docs": int(min_corpus_docs),
+            },
+        }
+
     def mark_superseded(self, old_node_id: str, new_node_id: str) -> Dict[str, Any]:
         """Record that ``old_node_id`` was replaced by ``new_node_id``.
 

package/lattice_brain/graph/retrieval.py

@@ -450,7 +450,7 @@ class KnowledgeGraphRetrievalMixin:
         query: str,
         *,
         top_k: int = 20,
-        alpha: float = 0.6,
+        alpha: Optional[float] = None,
         workspace_id: Optional[str] = None,
         allowed_workspaces=None,
         include_legacy_global: bool = False,
@@ -476,6 +476,12 @@ class KnowledgeGraphRetrievalMixin:
 
         ``workspace_id`` is a convenience for single-workspace callers; the
         richer ``allowed_workspaces`` set wins when both are provided.
+
+        ``alpha=None`` (the default) resolves the vector share from the
+        query-class fusion table (:mod:`lattice_brain.graph.fusion`):
+        fact 0.6 (the historical default) / code 0.35 / person 0.45 /
+        recency 0.5, config-overridable via ``LATTICEAI_FUSION_WEIGHTS``.
+        Passing an explicit ``alpha`` pins it exactly as before.
         """
         query = str(query or "").strip()
         try:
@@ -483,6 +489,16 @@ class KnowledgeGraphRetrievalMixin:
         except (TypeError, ValueError):
             top_k = 20
         top_k = max(1, min(top_k, 100))
+        query_class: Optional[str] = None
+        if alpha is None:
+            try:
+                from .fusion import fusion_profile
+
+                profile = fusion_profile(query)
+                query_class = profile["query_class"]
+                alpha = float(profile["alpha"])
+            except Exception:  # noqa: BLE001 — fusion table must never break search
+                alpha = 0.6
         try:
             alpha = float(alpha)
         except (TypeError, ValueError):
@@ -496,6 +512,7 @@ class KnowledgeGraphRetrievalMixin:
                 "query": query,
                 "mode": "hybrid",
                 "alpha": alpha,
+                "query_class": query_class,
                 "top_k": top_k,
                 "sources": {"lexical": 0, "vector": 0},
                 "matches": [],
@@ -624,6 +641,7 @@ class KnowledgeGraphRetrievalMixin:
             "query": query,
             "mode": mode,
             "alpha": alpha,
+            "query_class": query_class,
             "top_k": top_k,
             "sources": {"lexical": len(lexical_matches), "vector": len(vector_matches)},
             "matches": matches,

package/lattice_brain/ingestion.py

@@ -245,6 +245,72 @@ def assess_extraction_quality(
     return {"score": round(score, 4), "level": _quality_level(score), "reasons": reasons}
 
 
+# ── capture quality CTA (backlog #9, review §7.2 C) ──────────────────────────
+# Structured verdict over the same extraction-quality schema the rest of the
+# pipeline uses, so capture surfaces (browser extension, read-url) can render
+# an honest "this capture is thin" CTA instead of silently storing junk.
+CAPTURE_SUGGESTIONS_THIN = ["recapture", "paste_manually", "highlight_source"]
+_CAPTURE_REASON_LABELS = {
+    "empty_text": "추출된 본문이 비어 있습니다",
+    "very_short_text": "추출된 본문이 매우 짧습니다",
+    "short_text": "추출된 본문이 짧습니다",
+    "no_sentence_structure": "문장 구조가 거의 없습니다",
+    "low_character_diversity": "반복 문자가 대부분입니다",
+    "repetitive_lines": "같은 줄이 반복됩니다",
+    "repetitive_words": "같은 단어가 반복됩니다",
+    "high_whitespace_ratio": "공백이 지나치게 많습니다",
+    "fragmented_lines": "줄이 잘게 조각나 있습니다",
+    "nav_menu_remnants": "메뉴/내비게이션 잔여물이 많습니다",
+    "boilerplate_markers": "상용구 텍스트가 많습니다",
+    "no_extracted_text": "추출된 텍스트가 없습니다",
+}
+
+
+def capture_quality_verdict(
+    extraction_quality: Optional[Dict[str, Any]],
+    *,
+    source_type: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Structured CTA verdict from a pipeline ``extraction_quality`` dict.
+
+    ``{"status": "thin"|"ok", "reason": str|None, "suggestions": [...],
+    "score": float|None, "level": str|None}``. ``thin`` (level == "low", the
+    same threshold as the ingest warning) carries actionable suggestions —
+    ``recapture`` / ``paste_manually`` / ``highlight_source`` — so the UI can
+    offer the user a way to fix the capture instead of hiding the problem.
+    Deterministic and never raises; ``None`` input yields an honest ``thin``.
+    """
+    if not isinstance(extraction_quality, dict):
+        return {
+            "status": "thin",
+            "reason": _CAPTURE_REASON_LABELS["no_extracted_text"],
+            "reason_codes": ["no_extracted_text"],
+            "suggestions": list(CAPTURE_SUGGESTIONS_THIN),
+            "score": None,
+            "level": None,
+        }
+    level = str(extraction_quality.get("level") or "")
+    score = extraction_quality.get("score")
+    reasons = [str(item) for item in (extraction_quality.get("reasons") or [])]
+    thin = level == "low"
+    reason = None
+    if thin:
+        labeled = [
+            _CAPTURE_REASON_LABELS[code]
+            for code in reasons
+            if code in _CAPTURE_REASON_LABELS
+        ]
+        reason = "; ".join(labeled) if labeled else QUALITY_LOW_WARNING
+    return {
+        "status": "thin" if thin else "ok",
+        "reason": reason,
+        "reason_codes": reasons if thin else [],
+        "suggestions": list(CAPTURE_SUGGESTIONS_THIN) if thin else [],
+        "score": score,
+        "level": level or None,
+    }
+
+
 def _load_latticeignore(root: Path) -> List[str]:
     """Parse ``root/.latticeignore`` → glob patterns (gitignore-like subset)."""
     ignore_file = root / LATTICEIGNORE_FILENAME

package/lattice_brain/runtime/multi_agent.py

@@ -48,7 +48,7 @@ from .contracts import multi_agent_contract
 from ..utils import now_iso as _now
 
 
-MULTI_AGENT_VERSION = "9.9.1"
+MULTI_AGENT_VERSION = "9.9.3"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "9.9.1"
+__version__ = "9.9.3"

package/latticeai/api/automation_intelligence.py

@@ -12,11 +12,21 @@ enable), review-queue gated, local-only, and idempotent per suggestion.
 
 from __future__ import annotations
 
+import asyncio
+import os
+import time
 from typing import Any, Callable, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.services.automation_execution import (
+    build_last_execution,
+    dry_run_report,
+    enqueue_failed_execution,
+    is_automation_workflow,
+    summarize_workflow_run,
+)
 from latticeai.services.automation_intelligence import AutomationIntelligenceService
 from latticeai.services.brain_automation import find_installed_recipe_workflow
 
@@ -26,6 +36,21 @@ class SuggestionInstallRequest(BaseModel):
     enabled: bool = False
 
 
+class AutomationRunNowRequest(BaseModel):
+    workflow_id: str
+    # Dry-run first: the default reports what WOULD happen without side
+    # effects; an explicit dry_run=false runs the automation once for real.
+    dry_run: bool = True
+
+
+def _run_now_wait_seconds() -> float:
+    raw = os.environ.get("LATTICEAI_AUTOMATION_RUN_NOW_WAIT", "30")
+    try:
+        return max(0.0, min(float(raw), 300.0))
+    except (TypeError, ValueError):
+        return 30.0
+
+
 def create_automation_intelligence_router(
     *,
     service: AutomationIntelligenceService,
@@ -35,7 +60,10 @@ def create_automation_intelligence_router(
     gate_write: Callable[[Request], Optional[str]],
     append_audit_event: Callable[..., None],
     workspace_graph: Callable[[], Any],
+    run_executor: Any = None,
+    review_queue: Any = None,
 ) -> APIRouter:
+    from lattice_brain.runtime.statuses import RUN_TERMINAL_STATUSES
     from lattice_brain.workflow import legacy_steps_from_nodes, validate_definition
 
     router = APIRouter()
@@ -123,6 +151,137 @@ def create_automation_intelligence_router(
             "already_installed": False,
         }
 
+    def _stamp_last_execution(
+        workflow_id: str, last_execution: dict, scope: Optional[str]
+    ) -> None:
+        """Persist the execution record on the workflow's metadata (merge)."""
+        try:
+            store.update_workflow_definition(
+                workflow_id,
+                metadata={"last_execution": last_execution},
+                workspace_id=scope,
+            )
+        except Exception:  # noqa: BLE001 — surfacing must never undo the run
+            pass
+
+    @router.post("/api/automation/run-now")
+    async def automation_run_now(req: AutomationRunNowRequest, request: Request):
+        """Run an installed automation once — dry-run by default.
+
+        * ``dry_run=true``: deterministic report of what WOULD happen; no
+          runner executes and nothing but the ``last_execution`` stamp moves.
+        * ``dry_run=false``: one real execution through the async run
+          executor; the request waits briefly for completion, stamps the
+          result, and enqueues failed executions into the review inbox.
+        """
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            workflow = store.get_workflow(req.workflow_id, workspace_id=scope)
+        except FileNotFoundError as exc:
+            raise HTTPException(
+                status_code=404, detail=f"Automation not found: {req.workflow_id}"
+            ) from exc
+        if not is_automation_workflow(workflow):
+            raise HTTPException(
+                status_code=404,
+                detail=f"Workflow is not an installed automation: {req.workflow_id}",
+            )
+
+        if req.dry_run:
+            report = dry_run_report(workflow)
+            last_execution = build_last_execution(
+                mode="dry_run",
+                status=report["status"],
+                summary=report["summary"],
+            )
+            _stamp_last_execution(req.workflow_id, last_execution, scope)
+            append_audit_event(
+                "automation_run_now",
+                user_email=user,
+                workflow_id=req.workflow_id,
+                dry_run=True,
+                status=report["status"],
+            )
+            return {
+                "workflow_id": req.workflow_id,
+                "dry_run": True,
+                "status": report["status"],
+                "report": report,
+                "last_execution": last_execution,
+            }
+
+        if run_executor is None:
+            raise HTTPException(
+                status_code=503,
+                detail="Automation execution runtime is not available.",
+            )
+        started = await run_executor.start_workflow(
+            workflow,
+            workflow_id=req.workflow_id,
+            user_email=user or None,
+            scope=scope,
+            inputs={"trigger": "run_now"},
+        )
+        run_id = str(((started or {}).get("run") or {}).get("id") or "")
+
+        # Bounded, non-cancelling wait: poll the durable run row so a slow
+        # execution keeps running in the background instead of being aborted.
+        run = (started or {}).get("run") or {}
+        deadline = time.monotonic() + _run_now_wait_seconds()
+        while time.monotonic() < deadline:
+            try:
+                run = store.get_workflow_run(run_id, workspace_id=scope)
+            except FileNotFoundError:
+                break
+            if str(run.get("status") or "") in RUN_TERMINAL_STATUSES:
+                break
+            await asyncio.sleep(0.05)
+
+        status = str(run.get("status") or "running")
+        completed = status in RUN_TERMINAL_STATUSES
+        summary = (
+            summarize_workflow_run(run)
+            if completed
+            else "started — still running in the background"
+        )
+        last_execution = build_last_execution(
+            mode="live",
+            status=status if completed else "running",
+            summary=summary,
+            run_id=run_id or None,
+        )
+        _stamp_last_execution(req.workflow_id, last_execution, scope)
+
+        review_item = None
+        if status == "failed":
+            review_item = enqueue_failed_execution(
+                review_queue,
+                workflow=workflow,
+                run_id=run_id or None,
+                error=summary,
+                user_email=user or None,
+                workspace_id=scope,
+            )
+        append_audit_event(
+            "automation_run_now",
+            user_email=user,
+            workflow_id=req.workflow_id,
+            dry_run=False,
+            run_id=run_id or None,
+            status=last_execution["status"],
+        )
+        payload = {
+            "workflow_id": req.workflow_id,
+            "dry_run": False,
+            "status": last_execution["status"],
+            "run_id": run_id or None,
+            "last_execution": last_execution,
+        }
+        if review_item is not None:
+            payload["review_item_id"] = review_item.get("id")
+        return payload
+
     return router