Harden governed reasoning and add the StateOps Control Room

[brunovicco]

Problem

The live reasoning path needed safer handling for provider-portable structured output and terminal Gateway failures. The API-only demonstration also made LangGraph state transitions, parallel investigation, durable interrupts, and resume behavior difficult to present visually.

Solution

Harden the governed reasoning boundary and add a same-origin StateOps Control Room served directly by FastAPI. The graph now converts reasoning failures into metadata-safe terminal state, while the browser UI follows the existing state stream through investigation, human approval, execution, and verification.

Main changes

• use provider-portable structured-output schemas and enforce collection limits in the application boundary;
• translate Gateway HTTP, transport, client, and terminal execution failures into stable reasoning errors;
• persist reasoning failures as serializable workflow state and stop affected graph branches safely;
• make the value stream end with the final persisted checkpoint state;
• add a dependency-free operator console at /ui with state-machine visualization, fan-out progress, approval and rejection controls, timeline, persisted-thread loading, and capture mode;
• serve local HTML, CSS, and JavaScript with a restrictive Content Security Policy;
• include the resolved-state screenshot and update the English and Brazilian Portuguese documentation;
• add regression coverage for Gateway failures, structured-output bounds, graph failure states, final stream state, and packaged UI assets.

Test evidence

• uv run python scripts/quality_gate.py: passed;
• 58 tests passed and 1 opt-in Redis integration test skipped by the default gate;
• total branch coverage: 89.65%;
• Ruff, formatting, strict Mypy, architecture, governance, MCP validation, Bandit, and dependency audit passed;
• browser flow exercised with Redis from waiting_approval through approval to resolved;
• manual live-inference flow exercised through the Governed LLM Gateway and resumed from the human interrupt;
• built wheel verified to contain index.html, app.css, and app.js.

Security and data impact

• the UI has no CDN or third-party browser dependency;
• LLM-derived values are inserted as text rather than interpreted as HTML;
• the UI response denies framing and applies a same-origin-only Content Security Policy;
• provider credentials remain outside StateOps and are never sent to the browser;
• persisted failures contain stable metadata rather than raw provider or transport exceptions;
• incident signals and remediation effects remain synthetic.

Operational and rollout impact

• no database migration or Redis key migration is required;
• rebuilding and restarting the StateOps service exposes the console at /ui;
• existing API consumers remain compatible;
• the final persisted snapshot adds one terminal event to the existing SSE projection.

Risks and follow-ups

• LangGraph v3 event streaming remains experimental and emits the existing framework warning;
• browser behavior is covered through route, security-header, asset, and manual end-to-end validation, but a dedicated browser automation suite is not added;
• production remediation integrations remain intentionally out of scope.