routes: POST /troubleshoot/tree — deterministic tree endpoint (Phase 1.c)

Closes the engine + trees foundation by wiring the tree runner into a
public route. Mirrors POST /troubleshoot exactly for session +
event_buffer + SSE + resume behaviour — only the event source differs
(tree runner vs LLM bridge).

Endpoint contract (POST /troubleshoot/tree):
  - body: {scenario_id: str, session_id?: str}
  - response: text/event-stream
  - 200 = SSE stream of events (same vocabulary as /troubleshoot:
          thought, tool_call, tool_result, verdict,
          recommended_action, error)
  - 404 = scenario_id not in registry
  - 409 = session_already_active (use /troubleshoot/resume to
          reattach)
  - 422 = missing or extra fields
  - 503 = tree_runner_unavailable (trees did not load at container
          start; check logs)

Wiring (src/app.py lifespan):
  - After action_executor loads, attempt to load tree registry from
    BLOX_AI_TREES_DIR (default /etc/fula/blox-ai/trees).
  - Cross-validate against the diag tool set (known_tools) + the
    action whitelist (tier_2_names + tier_3_names from
    LoadedWhitelist) before constructing the TreeRunner.
  - Soft-fail: if the dir is missing or any tree fails validation,
    log + set app.state.tree_runner = None; /troubleshoot/tree
    returns 503 but other endpoints still work.
  - Companion fula-ota commit adds the bind mount + the env var.

Driver function (_drive_tree_into_buffer):
  - Counterpart to _drive_generator_into_buffer used by
    /troubleshoot for the LLM bridge.
  - Walks the tree's async iterator, writes each event into the
    sessions event_buffer via session.append_event.
  - Same try/except/finally shape: CancelledError -> mark_done +
    re-raise; other exceptions -> error event + mark_done.

8 endpoint tests (test_troubleshoot_tree.py):
  - happy path returns SSE + verdict event
  - diag-calling tree emits tool_call + tool_result + verdict
  - caller-supplied session_id is preserved
  - 503 when tree_runner is None
  - 404 on unknown scenario_id
  - 422 on missing scenario_id
  - 422 on extra fields (pydantic extra: forbid)
  - 409 on concurrent POST against an active session

Full suite: 459/459 (was 451; +8 net).

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

Author: ehsan6sha

src/app.py

@@ -21,9 +21,11 @@
 
 from src.runtime.mock_backend import MockBackend
 from src.runtime.runbook_loader import RunbookLoader
+from src.runtime.tree_dsl import TreeValidationError, load_tree_registry
+from src.runtime.tree_runner import TreeRunner
 from src.session.manager import SessionManager
 from src.tools.approval_token import ApprovalTokenSigner
-from src.tools.diag_impls import RealDiagExecutor
+from src.tools.diag_impls import RealDiagExecutor, known_tools
 from src.tools.executor import ActionExecutor, WhitelistError, load_whitelist
 from src.schemas import SchemaRegistry
 from src.routes import cancel, diag, execute, feedback, health, pending, troubleshoot
@@ -100,6 +102,46 @@ async def lifespan(app: FastAPI):
             runbook_loader=None,  # rewired below once runbook_loader exists
         )
 
+    # Phase 1.c: deterministic tree runner. Loads YAML trees from
+    # BLOX_AI_TREES_DIR; cross-validates against the diag tool set +
+    # the action whitelist loaded above. Soft-fail in dev — if the
+    # tree dir is missing or trees fail to load, /troubleshoot/tree
+    # returns 503 but other endpoints still work.
+    trees_dir = os.environ.get(
+        "BLOX_AI_TREES_DIR",
+        "/etc/fula/blox-ai/trees",
+    )
+    app.state.tree_runner = None
+    if os.path.isdir(trees_dir):
+        try:
+            known_action_names = set()
+            if app.state.action_executor is not None:
+                wl = app.state.action_executor.whitelist
+                # LoadedWhitelist exposes tier_2_names / tier_3_names
+                # as frozensets per src/tools/executor.py.
+                known_action_names |= set(wl.tier_2_names)
+                known_action_names |= set(wl.tier_3_names)
+            diag_short = {t.removeprefix("diag/") for t in known_tools()}
+            registry = load_tree_registry(
+                trees_dir,
+                known_diag_tools=diag_short,
+                known_action_names=known_action_names,
+            )
+            app.state.tree_runner = TreeRunner(
+                trees=registry,
+                tool_executor=app.state.tool_executor,
+            )
+            logger.info(
+                "tree_runner wired with %d trees: %s",
+                len(registry), sorted(registry.keys()),
+            )
+        except TreeValidationError as e:
+            logger.error("tree registry load failed: %s; /troubleshoot/tree will 503", e)
+    else:
+        logger.info(
+            "trees_dir %s not present; /troubleshoot/tree will 503", trees_dir,
+        )
+
     # C5: in-memory session registry for /troubleshoot conversations.
     # 30-min sliding TTL, 50-session cap, LRU eviction. Lost on container
     # restart by design (matches HMAC approval-secret rotation).

src/routes/troubleshoot.py

@@ -44,6 +44,23 @@ class TroubleshootRequest(BaseModel):
     session_id: str | None = Field(default=None, min_length=1, max_length=128)
 
 
+class TreeRequest(BaseModel):
+    """POST /troubleshoot/tree body (Phase 1.c).
+
+    The deterministic-tree counterpart to /troubleshoot. Same SSE event
+    vocabulary; same session/event_buffer/resume infrastructure; same
+    /execute-action approval flow for recommended actions. Difference:
+    the events come from a YAML-authored tree walker, not the LLM.
+
+    Used by the app's quick-start buttons (the user picked a scenario
+    explicitly) and by the classifier endpoint (the LLM mapped a
+    free-text prompt to a known scenario_id)."""
+    model_config = {"extra": "forbid"}
+
+    scenario_id: str = Field(min_length=1, max_length=64)
+    session_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+
 class UserReplyRequest(BaseModel):
     """POST /troubleshoot/user-reply body. Mirrors fula-ota's
     user_reply_request.schema.json shape."""
@@ -190,6 +207,118 @@ async def _stream_from_buffer(
             await session.cond.wait()
 
 
+async def _drive_tree_into_buffer(
+    session: SessionState,
+    tree_runner,
+    scenario_id: str,
+) -> None:
+    """Phase 1.c counterpart to _drive_generator_into_buffer. Walks the
+    tree and writes each emitted event into the session's buffer. The
+    SSE consumer (and any resume callers) read the buffer; they don't
+    talk to the tree runner directly. Apps/box's resume protocol
+    works unchanged because the event vocabulary is the same."""
+    try:
+        async for event in tree_runner.run(scenario_id):
+            await session.append_event(event)
+    except asyncio.CancelledError:
+        await session.mark_done()
+        raise
+    except Exception as e:  # noqa: BLE001
+        logger.exception("tree runner failed session=%s scenario=%s",
+                         session.session_id, scenario_id)
+        try:
+            await session.append_event({
+                "type": "error",
+                "code": "tree_runner_crashed",
+                "message": str(e)[:200],
+                "recoverable": False,
+            })
+        except Exception:
+            pass
+    finally:
+        await session.mark_done()
+
+
+@router.post("/troubleshoot/tree")
+async def troubleshoot_tree(req: TreeRequest, request: Request) -> Response:
+    """Phase 1.c — deterministic tree runner endpoint.
+
+    Mirrors POST /troubleshoot's session/buffer/SSE plumbing exactly;
+    the only difference is the generator (tree runner vs LLM bridge).
+    503 when the tree runner failed to load at startup (missing
+    BLOX_AI_TREES_DIR or YAML validation error).
+    """
+    tree_runner = getattr(request.app.state, "tree_runner", None)
+    if tree_runner is None:
+        return JSONResponse(
+            status_code=503,
+            content=_error_body(
+                "tree_runner_unavailable",
+                "trees did not load at startup; check container logs",
+            ),
+        )
+    # 404 on unknown scenario — caller bug, not a transient error.
+    if req.scenario_id not in tree_runner.trees:
+        return JSONResponse(
+            status_code=404,
+            content=_error_body(
+                "unknown_scenario_id",
+                f"available: {sorted(tree_runner.trees.keys())}",
+            ),
+        )
+
+    session_mgr = request.app.state.session_manager
+    if req.session_id:
+        session = session_mgr.get(req.session_id)
+        if session is None:
+            session = session_mgr.create(session_id=req.session_id)
+    else:
+        session = session_mgr.create()
+
+    if (
+        session.generator_task is not None
+        and not getattr(session.generator_task, "done", lambda: True)()
+        and not session.generator_done
+    ):
+        return JSONResponse(
+            status_code=409,
+            content=_error_body(
+                "session_already_active",
+                "use GET /troubleshoot/resume?session_id=...&from=N to reattach",
+            ),
+        )
+
+    # Reset buffer state for the new run (matches /troubleshoot).
+    session.event_buffer = []
+    session.next_seq = 0
+    session.dropped_count = 0
+    session.generator_done = False
+    session.consumer_generation += 1
+    async with session.cond:
+        session.cond.notify_all()
+
+    session.generator_task = asyncio.create_task(
+        _drive_tree_into_buffer(session, tree_runner, req.scenario_id),
+        name=f"blox-ai-tree-{session.session_id}-{req.scenario_id}",
+    )
+
+    async def sse_stream():
+        try:
+            async for chunk in _stream_from_buffer(session, from_seq=0):
+                yield chunk
+        finally:
+            session_mgr.touch(session.session_id)
+
+    return StreamingResponse(
+        sse_stream(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
 @router.post("/troubleshoot")
 async def troubleshoot(req: TroubleshootRequest, request: Request) -> Response:
     backend = request.app.state.backend