[KM-667] feat(help): wire help dispatch in chat_handler

Replace the help placeholder with the real handler. _load_analysis_state
fail-closes to a not-validated stub (legacy room / read error); help_agent
injectable; streams chunk/done with masked callbacks. Remove dead _stub_message
(help was the last unwired intent).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/chat_handler.py

@@ -10,7 +10,7 @@ End-to-end flow per user message:
                                list[DocumentChunk].
        - `check`             → check_data / check_knowledge tool → rendered table.
        - `problem_statement` → PS skill: draft + validate → write analysis state.
-       - `help`              → placeholder (handler pending).
+       - `help`              → Help skill: analysis state + history → streamed guidance.
   3. `ChatbotAgent.astream` → yield text tokens.
   4. Wrap each step into an SSE-style event dict so the API endpoint can
      stream them as Server-Sent Events.
@@ -38,6 +38,7 @@ from src.retrieval.base import RetrievalResult
 
 from .chatbot import ChatbotAgent, DocumentChunk
 from .handlers.check import run_check
+from .handlers.help import HelpAgent
 from .handlers.problem_statement import ProblemStatementAgent, run_problem_statement
 from .orchestration import OrchestratorAgent
 
@@ -45,6 +46,7 @@ if TYPE_CHECKING:
     from ..catalog.reader import CatalogReader
     from ..query.service import QueryService
     from ..retrieval.router import RetrievalRouter
+    from .gate import AnalysisState
     from .slow_path.coordinator import SlowPathCoordinator
     from .slow_path.store import AnalysisStore
 
@@ -79,6 +81,7 @@ class ChatHandler:
         analysis_store: AnalysisStore | None = None,
         check_invoker_factory: Callable[[str], Any] | None = None,
         ps_agent: ProblemStatementAgent | None = None,
+        help_agent: HelpAgent | None = None,
         state_store: Any | None = None,
         enable_gate: bool = False,
         enable_tracing: bool = False,
@@ -104,6 +107,8 @@ class ChatHandler:
         # `problem_statement` skill: LLM drafter + the Analysis State store it writes
         # `problem_validated` to. Both injectable for tests.
         self._ps_agent = ps_agent
+        # `help` skill: LLM guide that reads the Analysis State + chat history.
+        self._help_agent = help_agent
         self._state_store = state_store
         # Deterministic gate: redirect structured_flow -> problem_statement until the
         # analysis is validated. OFF by default (legacy rooms have no state row).
@@ -158,6 +163,11 @@ class ChatHandler:
             self._ps_agent = ProblemStatementAgent()
         return self._ps_agent
 
+    def _get_help_agent(self) -> HelpAgent:
+        if self._help_agent is None:
+            self._help_agent = HelpAgent()
+        return self._help_agent
+
     def _get_state_store(self) -> Any:
         if self._state_store is None:
             from .state_store import AnalysisStateStore
@@ -165,6 +175,23 @@ class ChatHandler:
             self._state_store = AnalysisStateStore()
         return self._state_store
 
+    async def _load_analysis_state(self, analysis_id: str | None) -> AnalysisState:
+        """Load Analysis State for the Help skill; fail closed to a not-validated stub.
+
+        Mirrors the gate's never-throw fallback so Help degrades gracefully on a
+        missing row, a read error, or a legacy room with no `analysis_id`.
+        """
+        from .gate import stub_analysis_state
+
+        if not analysis_id:
+            return stub_analysis_state(problem_validated=False)
+        try:
+            state = await self._get_state_store().get(analysis_id)
+        except Exception as e:
+            logger.warning("help state read failed — not-validated", error=str(e))
+            state = None
+        return state if state is not None else stub_analysis_state(problem_validated=False)
+
     # ------------------------------------------------------------------
     # Public entry
     # ------------------------------------------------------------------
@@ -285,10 +312,27 @@ class ChatHandler:
             yield {"event": "done", "data": ""}
             return
         elif intent == "help":
-            # help skill not wired yet (LLM skill, deferred). Placeholder keeps
-            # dispatch exhaustive; real handler lands in a follow-up step.
-            logger.info("unwired intent stub", intent=intent)
-            yield {"event": "chunk", "data": _stub_message(intent)}
+            try:
+                state = await self._load_analysis_state(analysis_id)
+            except Exception as e:
+                logger.error("help route failed", user_id=user_id, error=str(e))
+                yield {"event": "error", "data": f"Help failed: {e}"}
+                return
+            # report_ready is the deterministic readiness signal (seam #5). Until
+            # `is_report_ready` lands, the default (not ready) degrades safely — Help
+            # won't suggest generating a report. The prompt sees chat history -> masked.
+            hc = tracer.callbacks(masked=True)
+            hkw = {"callbacks": hc} if hc else {}
+            try:
+                async for token in self._get_help_agent().astream(
+                    state, history=history, message=message, **hkw
+                ):
+                    yield {"event": "chunk", "data": token}
+            except Exception as e:
+                logger.error("help streaming failed", user_id=user_id, error=str(e))
+                yield {"event": "error", "data": f"Help generation failed: {e}"}
+                return
+            tracer.end()
             yield {"event": "done", "data": ""}
             return
         # else: chat path — no context
@@ -480,11 +524,6 @@ def _intent_to_source_hint(intent: str) -> str:
     return "chat"
 
 
-def _stub_message(intent: str) -> str:
-    """Placeholder reply for intents whose handlers are not wired yet."""
-    return f"The '{intent}' route is recognized but not wired up yet."
-
-
 def _build_sources(
     intent: str,
     user_id: str,