Persistent agent session UI with orchestration graph visualization

[gx-ai-architect]

Summary

Implements #642 — a persistent agent session management UI with graphical orchestration visualization for the factory dashboard.

• SQLite session persistence (factory/sessions.py) — captures every agent invocation in a local sessions.db with hierarchical parent→child linking, alongside existing Langfuse telemetry (additive, not replacing)
• Session API endpoints — 6 new routes in the dashboard: cycles list, cycle detail, session detail, graph data, interactive resume, and sessions page
• Session browser UI (sessions.html) — two-column layout with cycle list + chat-style conversation viewer, using marked.js for markdown and Prism.js for syntax highlighting
• Agent orchestration graph — interactive DAG visualization using Cytoscape.js + dagre layout, showing agent spawning relationships, sequential ordering, role-colored nodes, click-to-navigate, and hover tooltips

Key design decisions

• Data-driven, not hardcoded: role colors are hash-based, graph structure is derived from session hierarchy + event timeline — no mode-specific templates. Adding/removing agent roles (e.g., QA Agent: consolidate all post-Builder verification into one agent #630 QA agent) requires zero UI code changes.
• SQLite, not Langfuse-dependent: the UI works standalone with zero external dependencies. Session capture runs alongside Langfuse telemetry via the same try/except pattern.
• Vanilla HTML/JS: matches the existing dashboard pattern — no React/Vue build step.

Verified

• 52+ tests across 3 test files (session CRUD, API endpoints, graph API)
• E2E verified with a real snake-game build cycle (CEO → researcher → strategist → builder)
• Interactive session resume preserves agent identity and context
• All conversation item types captured (messages, tool calls, tool outputs, thinking blocks)
• Graph correctly shows 4 nodes, 3 spawned edges, 2 sequential edges

Test plan

uv run pytest tests/test_sessions.py tests/test_dashboard_sessions.py tests/test_graph_api.py -v

Manual E2E:

# Start dashboard
uv run factory dashboard --port 8420 --projects-dir /path/to/projects

# Open http://localhost:8420/sessions/<project-name>
# - Left panel: cycle list with role badges and cost stats
# - Right panel: click a cycle → conversation viewer with collapsible tool calls
# - Toggle to Graph view → interactive DAG with click-to-navigate

Closes #642, closes #643, closes #645, closes #646

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 81.47513% with 108 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.48%. Comparing base (13a3e43) to head (5cb0b5a).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
factory/dashboard/app.py	77.38%	38 Missing ⚠️
factory/sessions.py	89.11%	37 Missing ⚠️
factory/cli.py	26.31%	28 Missing ⚠️
factory/agents/runner.py	86.48%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #644      +/-   ##
==========================================
- Coverage   88.23%   87.48%   -0.75%     
==========================================
  Files          70       71       +1     
  Lines       10570    11229     +659     
==========================================
+ Hits         9326     9824     +498     
- Misses       1244     1405     +161     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gx-ai-architect]

Phase 3: Agent orchestration graph visualization (#646)

Added interactive DAG visualization of agent orchestration to sessions.html:

Changes

• factory/dashboard/app.py: Added GET /api/projects/{name}/cycles/{cycle_id}/graph endpoint and _build_cycle_graph() helper that derives graph from session hierarchy + events.jsonl
• factory/dashboard/static/sessions.html: Added Cytoscape.js + dagre CDN scripts, Conversation/Graph toggle, full graph rendering with dagre layout, click-to-navigate, hover tooltips
• tests/test_graph_api.py: 9 tests covering node count, spawned/sequential edges, timeline, unknown roles, empty cycles, failed status

Key design decisions

• Node colors via hash function (same roleColor() as conversation view) — roster-agnostic
• No hardcoded flow templates — graph is purely data-driven from session hierarchy
• Dagre top-to-bottom layout for the DAG
• Click node → switch to conversation view, scroll to agent section
• Node size proportional to duration, border style indicates status (solid=completed, dashed=running, dotted=failed)

All 23 tests pass, lint clean.