ltcai 9.9.3 → 9.9.4

package/lattice_brain/graph/retrieval_vector.py

@@ -13,6 +13,78 @@ class KnowledgeGraphVectorMixin:
     retrieval/write helpers (e.g. self._vector_text_for_node) through the MRO.
     """
 
+    # ── embedder fingerprint (review Wave 2.2 — stale_embedder) ──────────────
+    # vector_search filters on the CURRENT model/dim, so swapping the embedder
+    # silently yields zero vector rows. The fingerprint persisted in graph_meta
+    # records which embedder actually built the index; a mismatch is surfaced
+    # as the honest ``stale_embedder`` signal instead of a silent degradation.
+
+    _EMBEDDER_FINGERPRINT_KEY = "embedder_fingerprint"
+
+    def _embedder_fingerprint_record(
+        self, conn: sqlite3.Connection
+    ) -> Optional[Dict[str, Any]]:
+        """Read the recorded embedder fingerprint from graph_meta (or None)."""
+        row = conn.execute(
+            "SELECT value FROM graph_meta WHERE key=?",
+            (self._EMBEDDER_FINGERPRINT_KEY,),
+        ).fetchone()
+        if not row:
+            return None
+        payload = _safe_loads(row["value"])
+        if not isinstance(payload, dict) or not payload.get("model_id"):
+            return None
+        try:
+            dim = int(payload.get("dim") or 0)
+        except (TypeError, ValueError):
+            dim = 0
+        return {"model_id": str(payload["model_id"]), "dim": dim}
+
+    def _write_embedder_fingerprint(self, conn: sqlite3.Connection) -> Dict[str, Any]:
+        """Persist the CURRENT embedder identity (same transaction as caller)."""
+        fingerprint = {
+            "model_id": self._embedding_model.model_id,
+            "dim": int(self._embedding_model.dim),
+        }
+        conn.execute(
+            "INSERT OR REPLACE INTO graph_meta(key, value) VALUES (?, ?)",
+            (self._EMBEDDER_FINGERPRINT_KEY, _json(fingerprint)),
+        )
+        return fingerprint
+
+    def record_embedder_fingerprint(self) -> Dict[str, Any]:
+        """Record the current embedder (model_id + dim) as the index builder."""
+        with self._connect() as conn:
+            return self._write_embedder_fingerprint(conn)
+
+    def embedder_fingerprint_status(self) -> Dict[str, Any]:
+        """Compare the current embedder against the recorded index fingerprint.
+
+        Returns ``{"current": {model_id, dim}, "recorded": {...} | None,
+        "stale_embedder": bool}``. ``stale_embedder`` is True only when a
+        fingerprint was recorded AND it differs from the current embedder —
+        an unrecorded index (legacy DBs, nothing indexed yet) is honestly
+        "unknown", never reported stale. Never raises.
+        """
+        current = {
+            "model_id": self._embedding_model.model_id,
+            "dim": int(self._embedding_model.dim),
+        }
+        recorded: Optional[Dict[str, Any]] = None
+        try:
+            with self._connect() as conn:
+                recorded = self._embedder_fingerprint_record(conn)
+        except Exception:  # noqa: BLE001 — status must degrade, never raise
+            recorded = None
+        stale = bool(
+            recorded is not None
+            and (
+                recorded.get("model_id") != current["model_id"]
+                or recorded.get("dim") != current["dim"]
+            )
+        )
+        return {"current": current, "recorded": recorded, "stale_embedder": stale}
+
     def _iter_vector_source_items(
         self,
         conn: sqlite3.Connection,
@@ -153,6 +225,11 @@ class KnowledgeGraphVectorMixin:
                         indexed += 1
                     else:
                         skipped += 1
+                if indexed and self._embedder_fingerprint_record(conn) is None:
+                    # First successful vector write establishes the fingerprint;
+                    # later incremental writes never overwrite it (only a full
+                    # rebuild may flip it after an embedder swap).
+                    self._write_embedder_fingerprint(conn)
             summary.update(
                 {
                     "items_total": len(items),
@@ -254,6 +331,10 @@ class KnowledgeGraphVectorMixin:
                         op_id,
                     ),
                 )
+                # A successful rebuild (re)establishes which embedder built
+                # the index — this is the only path that may flip a recorded
+                # fingerprint after an embedder swap.
+                self._write_embedder_fingerprint(conn)
             return {
                 "status": "completed",
                 "operation_id": op_id,
@@ -401,8 +482,10 @@ class KnowledgeGraphVectorMixin:
                         "within_target": float(duration_ms) <= 10_000,
                     }
                 )
+        embedder_status = self.embedder_fingerprint_status()
         return {
             "status": "ready" if pending == 0 else "needs_reindex",
+            "embedder": embedder_status,
             "storage": {
                 "db_path": str(self.db_path),
                 "backend": "sqlite",
@@ -449,7 +532,11 @@ class KnowledgeGraphVectorMixin:
                 "backlog_reasons": backlog_reasons,
                 "backlog_samples": backlog_samples,
                 "incremental_reindex_recommended": pending > 0,
-                "full_rebuild_recommended": orphaned_items > 0,
+                # A stale embedder means every old-model row must be re-embedded;
+                # only a full rebuild (which re-records the fingerprint) heals it.
+                "full_rebuild_recommended": bool(
+                    orphaned_items > 0 or embedder_status["stale_embedder"]
+                ),
                 "latency_budget": latency_budget,
             },
             "operations": [
@@ -475,7 +562,11 @@ class KnowledgeGraphVectorMixin:
 
         Reduces :meth:`index_status` (``pending = missing + stale``) to the
         fixed contract ``{"status", "pending_items", "total_items", "detail"}``
-        with ``status`` in ``ready`` / ``pending`` / ``unavailable``.
+        with ``status`` in ``ready`` / ``pending`` / ``stale_embedder`` /
+        ``unavailable``. ``stale_embedder`` (review Wave 2.2) is reported only
+        when the recorded embedder fingerprint differs from the current
+        embedder AND rows indexed under the old model still exist — the index
+        needs a full rebuild, not an incremental sync.
 
         Never raises: environments where the embedding provider or index
         storage cannot be used report ``"unavailable"`` with the cause in
@@ -492,6 +583,35 @@ class KnowledgeGraphVectorMixin:
             }
         pending = int(status.get("pending_items") or 0)
         total = int(status.get("source_items") or 0)
+        embedder = status.get("embedder") or {}
+        if embedder.get("stale_embedder"):
+            old_model_rows = 0
+            try:
+                with self._connect() as conn:
+                    old_model_rows = int(
+                        conn.execute(
+                            "SELECT COUNT(*) AS c FROM vector_embeddings "
+                            "WHERE embedding_model<>? OR embedding_dim<>?",
+                            (
+                                self._embedding_model.model_id,
+                                int(self._embedding_model.dim),
+                            ),
+                        ).fetchone()["c"]
+                    )
+            except Exception:  # noqa: BLE001 — keep the existing statuses on failure
+                old_model_rows = 0
+            if old_model_rows > 0:
+                recorded = embedder.get("recorded") or {}
+                return {
+                    "status": "stale_embedder",
+                    "pending_items": pending,
+                    "total_items": total,
+                    "detail": (
+                        f"embedding model changed ({recorded.get('model_id')} → "
+                        f"{self._embedding_model.model_id}); {old_model_rows} indexed "
+                        "rows still use the previous model — run a full vector index rebuild"
+                    ),
+                }
         if pending > 0:
             return {
                 "status": "pending",

package/lattice_brain/portability.py

@@ -14,6 +14,7 @@ any cloud service. Two complementary mechanisms, both fully local:
 from __future__ import annotations
 
 import json
+import logging
 import os
 import shutil
 import sqlite3
@@ -74,9 +75,12 @@ def _checkpoint_sqlite(db_path: Path) -> None:
 
 
 def _restore_sibling(path: Path, backup: Path) -> None:
-    if backup.exists():
+    try:
         shutil.copy2(backup, path)
-    else:
+    except FileNotFoundError:
+        # The backup vanished (or never existed — transient -wal/-shm): the
+        # honest reconstruction is "no such sibling", never a crash that
+        # masks the error that triggered the rollback.
         path.unlink(missing_ok=True)
 
 
@@ -101,10 +105,22 @@ def _replace_sqlite_atomically(src: Path, dest: Path, backup_dir: Path) -> None:
             sibling.unlink(missing_ok=True)
         os.replace(tmp, dest)
     except Exception:
-        if tmp.exists():
-            tmp.unlink()
+        # Recovery I/O must never replace the swap error being reported —
+        # an exception raised here would mask it (the CI-observed
+        # "[Errno 2]" over the real failure). Best-effort restore, then
+        # always re-raise the original.
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError as cleanup_exc:
+            logging.warning("restore tmp cleanup failed: %s", cleanup_exc)
         for sibling in _sqlite_siblings(dest):
-            _restore_sibling(sibling, backups.get(sibling, backup_dir / sibling.name))
+            try:
+                _restore_sibling(sibling, backups.get(sibling, backup_dir / sibling.name))
+            except OSError as rollback_exc:
+                logging.warning(
+                    "restore sibling rollback incomplete for %s: %s",
+                    sibling, rollback_exc,
+                )
         raise
 
 
@@ -127,12 +143,17 @@ def _replace_tree_with_backup(src: Optional[Path], dest: Path, backup_dir: Path)
             shutil.rmtree(dest)
         os.replace(staged, dest)
     except Exception:
-        if staged.exists():
-            shutil.rmtree(staged)
-        if dest.exists():
-            shutil.rmtree(dest)
-        if backup.exists():
-            shutil.copytree(backup, dest)
+        # Same masking guard as the sqlite swap: rollback I/O is
+        # best-effort and the original failure always propagates.
+        try:
+            if staged.exists():
+                shutil.rmtree(staged)
+            if dest.exists():
+                shutil.rmtree(dest)
+            if backup.exists():
+                shutil.copytree(backup, dest)
+        except OSError as rollback_exc:
+            logging.warning("blob tree rollback incomplete: %s", rollback_exc)
         raise
 
 
@@ -307,7 +328,15 @@ class KGPortabilityService:
                     blob_src = tmp / "blobs"
                     _replace_tree_with_backup(blob_src if blob_src.exists() else None, blob_dest, backup_dir)
                 except Exception:
-                    _rollback_sqlite_from_backup(db_dest, backup_dir)
+                    # The rollback is best-effort recovery; an I/O slip inside
+                    # it must never mask the restore failure being reported.
+                    try:
+                        _rollback_sqlite_from_backup(db_dest, backup_dir)
+                    except OSError as rollback_exc:
+                        logging.warning(
+                            "pre-restore rollback incomplete (backup kept at %s): %s",
+                            backup_dir, rollback_exc,
+                        )
                     raise
         stats = self._kg.stats()
         return {

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.3"
+MULTI_AGENT_VERSION = "9.9.4"
 
 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.3"
+__version__ = "9.9.4"

package/latticeai/api/chat.py

@@ -45,6 +45,7 @@ from latticeai.api.chat_helpers import (
     workspace_scope_from_request,
 )
 from latticeai.api.chat_history import HistoryRouteDependencies, register_history_routes
+from latticeai.core.run_store import AgentRunStore
 from latticeai.api.chat_intents import ChatIntentController
 from latticeai.api.chat_stream import stream_chat
 from latticeai.services.app_context import AppContext
@@ -191,6 +192,11 @@ def create_chat_router(context: AppContext) -> APIRouter:
         agent_root=AGENT_ROOT,
         ensure_agent_root=ensure_agent_root,
         funnel_metrics=context.funnel_metrics,
+        run_store=(
+            AgentRunStore(Path(context.data_dir) / "agent_runs")
+            if context.data_dir
+            else None
+        ),
     )
     intent_controller = ChatIntentController(
         model_router=model_router,

package/latticeai/api/chat_agent_http.py

@@ -11,7 +11,7 @@ import threading
 import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 
@@ -19,6 +19,11 @@ from lattice_brain.runtime.hooks import dispatch_tool
 from latticeai.api.chat_contracts import AgentEvalRequest, AgentRequest, AgentResumeRequest
 from latticeai.api.chat_helpers import _LANG_HINT, detect_language, workspace_scope_from_request
 from latticeai.core.agent import AgentRunContext, AgentState, normalize_plan
+from latticeai.core.run_store import (
+    AgentRunStore,
+    hash_approval_token,
+    restore_run_context,
+)
 from latticeai.services.tool_dispatch import collect_artifacts, collect_created_files
 
 
@@ -42,6 +47,7 @@ class AgentHTTPController:
         agent_root: Path,
         ensure_agent_root: Any,
         funnel_metrics: Any = None,
+        run_store: Any = None,
     ) -> None:
         self.runtime = runtime
         self.model_router = model_router
@@ -68,6 +74,16 @@ class AgentHTTPController:
         # explicit human-in-loop context flow above).
         self._approvals: Dict[str, Dict[str, Any]] = {}
         self._approval_ttl_seconds = 10 * 60
+        # Durable side of the approval loop (review Wave 0.1): paused runs are
+        # mirrored to disk so a valid token still resumes after a restart or
+        # from another worker process. In-memory stays the fast path.
+        self.run_store = run_store if run_store is not None else AgentRunStore(
+            Path(base_dir) / "data" / "agent_runs"
+        )
+        try:
+            self.run_store.sweep_expired()
+        except Exception as exc:  # noqa: BLE001 — hygiene must not break startup
+            logging.warning("agent run store sweep failed: %s", exc)
         self._background_tasks: set[asyncio.Task] = set()
 
     def register_routes(self, router: APIRouter) -> None:
@@ -83,6 +99,10 @@ class AgentHTTPController:
         async def agent_resume(req: AgentResumeRequest, request: Request):
             return await self.resume(req, request)
 
+        @router.get("/agent/approvals")
+        async def agent_approvals(request: Request):
+            return self.pending_approvals(request)
+
     def _schedule_background_task(self, coro: Any) -> None:
         task = asyncio.create_task(coro)
         self._background_tasks.add(task)
@@ -180,8 +200,17 @@ class AgentHTTPController:
             "results": results,
         }
 
-    async def agent(self, req: AgentRequest, request: Request) -> Dict[str, Any]:
-        """Plan and execute a natural-language local agent run."""
+    async def agent(
+        self,
+        req: AgentRequest,
+        request: Request,
+        on_step: Any = None,
+    ) -> Dict[str, Any]:
+        """Plan and execute a natural-language local agent run.
+
+        ``on_step`` (optional) is a per-run step observer — the live SSE
+        route attaches one so the client sees progress while EXECUTING.
+        """
         current_user = self.require_user(request)
         self.enforce_rate_limit(current_user, "agent")
         effective_email = self.authenticated_identity(current_user, req.user_email)
@@ -207,6 +236,8 @@ class AgentHTTPController:
         max_steps = max(1, min(req.max_steps, 50))
         max_retry = 3
         ctx = AgentRunContext()
+        if on_step is not None:
+            ctx.on_step = on_step
         ctx.executing_model = req.executing_model
         ctx.reviewing_model = req.reviewing_model
         ctx.state = AgentState.PLANNING
@@ -289,6 +320,26 @@ class AgentHTTPController:
                 "expires_monotonic": now_monotonic + self._approval_ttl_seconds,
                 "expires_at": expires_at,
             }
+        # Durable mirror: a restart between pause and resume must not orphan
+        # the run. Best-effort — the in-memory pause still answers on failure.
+        try:
+            self.run_store.save(
+                run_id,
+                ctx=ctx,
+                req_payload=req.model_dump(),
+                language_hint=language_hint,
+                user=current_user,
+                token=approval_token,
+                expires_epoch=time.time() + self._approval_ttl_seconds,
+                expires_at=expires_at,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logging.warning("agent run store persist failed: %s", exc)
+        if self.funnel_metrics is not None:
+            try:
+                self.funnel_metrics.increment("approval_pauses")
+            except Exception as exc:  # noqa: BLE001 — advisory only
+                logging.warning("funnel metrics increment failed: %s", exc)
         ctx.state_history.append(AgentState.WAITING_APPROVAL.value)
         message = (
             "이 작업에는 승인이 필요한 단계가 있어 실행을 잠시 멈췄습니다. "
@@ -318,6 +369,101 @@ class AgentHTTPController:
         for run_id, entry in list(self._approvals.items()):
             if now_monotonic >= entry["expires_monotonic"]:
                 self._approvals.pop(run_id, None)
+                try:
+                    self.run_store.delete(run_id)
+                except Exception:  # noqa: BLE001 — hygiene only
+                    pass
+
+    def pending_approvals(self, request: Request) -> Dict[str, Any]:
+        """Unexpired paused runs for the current user (memory ∪ disk).
+
+        Lets the UI re-surface an approval card after a reload/restart instead
+        of the run silently vanishing.
+        """
+        current_user = self.require_user(request)
+        now_monotonic = time.monotonic()
+        pending: Dict[str, Dict[str, Any]] = {}
+        with self._pending_lock:
+            for run_id, entry in self._approvals.items():
+                if entry["user"] != current_user:
+                    continue
+                if now_monotonic >= entry["expires_monotonic"]:
+                    continue
+                plan = getattr(entry["ctx"], "plan", {}) or {}
+                pending[run_id] = {
+                    "run_id": run_id,
+                    "goal": str(plan.get("goal") or "")[:200],
+                    "expires_at": entry["expires_at"],
+                }
+        try:
+            for summary in self.run_store.pending_summaries(current_user):
+                run_id = summary.get("run_id")
+                if run_id and run_id not in pending:
+                    pending[run_id] = {
+                        "run_id": run_id,
+                        "goal": summary.get("goal") or "",
+                        "expires_at": summary.get("expires_at"),
+                    }
+        except Exception as exc:  # noqa: BLE001 — disk listing is best-effort
+            logging.warning("agent run store listing failed: %s", exc)
+        return {"pending": sorted(pending.values(), key=lambda p: p["run_id"])}
+
+    def _restore_persisted_approval(self, run_id: str) -> Optional[Dict[str, Any]]:
+        """Rebuild an approval entry from disk after a restart.
+
+        Returns an entry shaped like the in-memory ones but carrying
+        ``token_hash`` instead of the plaintext token. Expired records are
+        deleted and reported via the same 410 contract as the memory path.
+        """
+        try:
+            record = self.run_store.load(run_id)
+        except Exception as exc:  # noqa: BLE001 — load error == not found
+            logging.warning("agent run store load failed: %s", exc)
+            return None
+        if record is None:
+            return None
+        req_payload = record.get("req") or {}
+        if time.time() >= float(record.get("expires_epoch") or 0):
+            try:
+                self.run_store.delete(run_id)
+            except Exception:  # noqa: BLE001
+                pass
+            raise HTTPException(
+                status_code=410,
+                detail={
+                    "error": "approval_expired",
+                    "message": "Approval token expired. Start a new request.",
+                    "replan": {"message": str(req_payload.get("message") or "")},
+                },
+            )
+        try:
+            restored_req = AgentRequest(**req_payload)
+        except Exception as exc:  # noqa: BLE001 — unreconstructable == not found
+            logging.warning("agent run store request restore failed: %s", exc)
+            return None
+        remaining = max(1.0, float(record["expires_epoch"]) - time.time())
+        return {
+            "ctx": restore_run_context(record.get("ctx") or {}),
+            "req": restored_req,
+            "language_hint": str(record.get("language_hint") or "English"),
+            "user": record.get("user"),
+            "token_hash": str(record.get("token_hash") or ""),
+            "expires_monotonic": time.monotonic() + remaining,
+            "expires_at": record.get("expires_at"),
+        }
+
+    @staticmethod
+    def _token_matches(entry: Dict[str, Any], supplied: str) -> bool:
+        """Constant-time token check for both plaintext and hashed entries."""
+        if not supplied:
+            return False
+        stored = entry.get("token")
+        if stored is not None:
+            return secrets.compare_digest(str(stored), supplied)
+        stored_hash = str(entry.get("token_hash") or "")
+        return bool(stored_hash) and secrets.compare_digest(
+            stored_hash, hash_approval_token(supplied)
+        )
 
     async def _finish(
         self,
@@ -468,6 +614,10 @@ class AgentHTTPController:
         now_monotonic = time.monotonic()
         with self._pending_lock:
             entry = self._approvals.get(req.run_id or "")
+            if entry is None:
+                # Restart survival (review Wave 0.1): the in-memory dict is
+                # gone but the durable record may still be valid.
+                entry = self._restore_persisted_approval(req.run_id or "")
             if entry is None:
                 raise HTTPException(
                     status_code=404,
@@ -480,24 +630,43 @@ class AgentHTTPController:
                 )
             if now_monotonic >= entry["expires_monotonic"]:
                 self._approvals.pop(req.run_id, None)
+                try:
+                    self.run_store.delete(req.run_id or "")
+                except Exception:  # noqa: BLE001
+                    pass
                 raise HTTPException(
                     status_code=410,
-                    detail="Approval token expired. Start a new request.",
+                    detail={
+                        "error": "approval_expired",
+                        "message": "Approval token expired. Start a new request.",
+                        "replan": {"message": getattr(entry.get("req"), "message", "")},
+                    },
                 )
-            supplied = req.approval_token or ""
-            if not supplied or not secrets.compare_digest(entry["token"], supplied):
+            if not self._token_matches(entry, req.approval_token or ""):
                 raise HTTPException(
                     status_code=403,
                     detail="Invalid approval token for this run.",
                 )
             # Token validated — the pending run is consumed either way.
             self._approvals.pop(req.run_id, None)
+            try:
+                self.run_store.delete(req.run_id or "")
+            except Exception as exc:  # noqa: BLE001 — consumption must proceed
+                logging.warning("agent run store delete failed: %s", exc)
             self._purge_expired_approvals_locked(now_monotonic)
 
         ctx: AgentRunContext = entry["ctx"]
         original_request: AgentRequest = entry["req"]
         language_hint: str = entry["language_hint"]
 
+        if self.funnel_metrics is not None:
+            # approval_resume_rate = resumes / pauses (review §4.3): counted on
+            # every token-valid resume decision, approve and deny alike.
+            try:
+                self.funnel_metrics.increment("approval_resumes")
+            except Exception as exc:  # noqa: BLE001 — advisory only
+                logging.warning("funnel metrics increment failed: %s", exc)
+
         approved = req.approve if req.approve is not None else req.approved
         if not approved:
             message = "사용자가 계획을 취소했습니다."

package/latticeai/api/chat_intents.py

@@ -17,7 +17,11 @@ from latticeai.api.chat_helpers import (
     format_network_status,
     inline_file_action_content,
 )
-from latticeai.api.chat_stream import agent_payload_stream, single_answer_response
+from latticeai.api.chat_stream import (
+    agent_live_stream,
+    agent_payload_stream,
+    single_answer_response,
+)
 from latticeai.core.agent import AgentState
 from latticeai.core.file_generation import (
     PREVIEWABLE_EXTENSIONS,
@@ -596,31 +600,46 @@ class ChatIntentController:
             user_nickname=req.user_nickname,
             workspace_id=workspace_id,
         )
-        result = await self.agent_controller.agent(agent_request, request)
-        answer = str(result.get("response") or "파일 작업을 처리했습니다.")
-        # UX funnel (backlog #16): a file-intent request that the agent loop
-        # finished without producing a single artifact is the "code-only"
-        # failure mode the >95% real-file goal watches. Paused/failed runs
-        # count neither way — they did not answer with code instead of files.
-        delivered = bool(result.get("created_files") or result.get("artifacts"))
-        if delivered:
-            self._funnel_increment("real_file_delivered")
-        elif str(result.get("status") or "") == "ok":
-            self._funnel_increment("code_only_responses")
-        self.notify("user", req.message, req.source)
-        self.notify("assistant", answer, req.source)
-        result["routed_to_agent"] = True
+
+        def finalize(result: Dict) -> str:
+            """History/funnel side effects once the run has a terminal payload."""
+            answer = str(result.get("response") or "파일 작업을 처리했습니다.")
+            # UX funnel (backlog #16): a file-intent request that the agent loop
+            # finished without producing a single artifact is the "code-only"
+            # failure mode the >95% real-file goal watches. Paused/failed runs
+            # count neither way — they did not answer with code instead of files.
+            delivered = bool(result.get("created_files") or result.get("artifacts"))
+            if delivered:
+                self._funnel_increment("real_file_delivered")
+            elif str(result.get("status") or "") == "ok":
+                self._funnel_increment("code_only_responses")
+            self.notify("user", req.message, req.source)
+            self.notify("assistant", answer, req.source)
+            result["routed_to_agent"] = True
+            return answer
+
         if req.stream:
+            # Live loop visibility (review Wave 1.1): run the agent inside the
+            # SSE generator so step events stream while EXECUTING; the final
+            # frames keep the exact historical payload shape.
+            async def start(observer):
+                return await self.agent_controller.agent(
+                    agent_request, request, on_step=observer
+                )
+
             return StreamingResponse(
-                agent_payload_stream(
-                    answer,
-                    result,
+                agent_live_stream(
+                    start,
                     router=self.router,
                     model_id=model_id,
+                    finalize=finalize,
                 ),
                 media_type="text/event-stream",
                 headers={"X-Model": model_id or "agent", "X-Routed-To": "agent"},
             )
+
+        result = await self.agent_controller.agent(agent_request, request)
+        finalize(result)
         return JSONResponse(content=result)