[NewMe505]

Summary

scio dashboard [--root DIR ...] [--port 8765] is a live web view of SCIO's own state machine across workspaces, on 127.0.0.1 only. It shows:

• every thread's current step, lit on its graph;
• the stop waiting for you, and crashed threads;
• feature runs (tier, status, iterations, escalations, cost, links), including the attempt running now;
• the timeline, and cost by role and by feature.

It never writes. It reads the checkpoint DB through mode=ro connections, plus the cost ledgers and progress.json, and reuses scio report's builders, so its costs equal scio report's. The page is plain HTML/JS with no build step, refreshed over a WebSocket. It ships as the optional dashboard extra (FastAPI, uvicorn). docs/OBSERVABILITY.md puts it beside the other two views: GitHub (--gh) and an OpenTelemetry trace viewer.

Closes #68

The real build-graphcalc-m1 while it runs: feature is lit, P1 to P3 passed, P4's first attempt failed at advisor_cap, and the second attempt is running at $1.93 (+ $1.9269 running), with the human's retry in the timeline.

Plan vs. done

Plan step	Status	Notes
Wave 0: the contract, fixtures, stub, extra	done	scio/dashboard/contract.py. Two probes came first (a mode=ro connection under SqliteSaver on a WAL DB; a Fake build's channels and pending writes). Reviewing the contract against them caught I-120 before fan-out.
Wave 1, A: data layer	done	CheckpointDataSource: mode=ro, setup() skipped, a connection per call; channel classification; stops, crashes, Send packets; feature links; tolerant ledger reads. 19 tests on Fake-build checkpoints, including a byte-identical DB after every read.
Wave 1, B: API and WebSocket	done	create_app: GET routes only (a test asserts it), /ws polling versions, Host check, same-origin WebSocket, no framing. 54 tests.
Wave 1, C: page	done	Threads list plus build, feature and bootstrap views; Mermaid 11.15.0 with SRI and a text fallback; CSP; DOM built with textContent only. 13 Playwright tests, offline.
Wave 1, D: ADR 0017, OBSERVABILITY.md	done	The OTel recipe for Phoenix (6006) and Jaeger (4318); the docs' gaps are I-122 and I-123.
Wave 2: scio dashboard, live check, shared docs	done	The CLI (loopback only, bounded shutdown); the real app serving the real page under uvicorn as a test; README, CHANGELOG, PRODUCT_MODE, ARCHITECTURE's tree.
Wave 3: review agent, full check	done	A fresh-context review found six issues (I-133 to I-138), each confirmed by a probe, and all fixed or documented. It found no breach of the read-only guarantee.

Live check (graphcalc-run, while its build runs)

• Costs equal scio report on a backup-API snapshot of the live DB: $9.0983 total, features $8.9244, orchestrator $0.1739, and every feature row and role identical.
• Live update from the real run: P4's second attempt wrote a checkpoint during the watch. /ws pushed changed: [build-graphcalc-m1-p4-a2], and the page fetched the list and the open build again, with no reload and no page errors.
• The run is unaffected: its checkpoint count kept rising while the dashboard read it.
• Read-only: test_the_data_layer_never_writes hashes the main DB before and after every public method, and a write through the dashboard's connection raises. The ADR notes that a mode=ro reader on a DB with no open writer leaves empty -wal/-shm sidecars, which SQLite's next writer cleans up.
• The dashboard caught a real stop: while graphcalc waited at "Feature P4 (advisor_cap, attempt 1) needs a decision", the build and P4 both read waiting, though the build's last checkpoint was 26 minutes older than the stop (I-120 in practice).

Test evidence

set -o pipefail; SCIO_PROVIDER_OVERRIDE=fake uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run python -m pytest -n 8 && uv run python scripts/check_docs.py && uv run python -m evals.runner --suite regression --provider fake --trials 5 --min-pass-pow-k 1.0
ruff: all checks passed · format: 266 files formatted · mypy: no issues in 130 source files
482 passed, 18 skipped in 789 s · docs-check: 0 problem(s) · regression pass@1 1.00, pass^5 1.00 (10 tasks)   # on 79dacc2

CI on 79dacc2: checks 495 passed, 5 skipped (12m53s; the dashboard and Playwright tests ran); docker-live pass (1m1s). 273246d adds only the CHANGELOG ### Fixed line for I-127.
The new tests:

• tests/unit/test_dashboard_data.py: 19 tests on Fake-build checkpoints plus tiny graphs for a stop, its answer, a crash, Send and unreadable rows.
• tests/unit/test_dashboard_app.py: 54 tests.
• tests/unit/test_dashboard_contract.py: the fixtures, and the one-interrupt-per-node scan.
• tests/unit/test_dashboard_cli.py: loopback only, bounded stop, the install hint.
• tests/live/test_dashboard_page.py: 13 Playwright tests.
• tests/live/test_dashboard_server.py: the real app and page under uvicorn, with a clean stop.
• tests/unit/test_lf_writes.py.
• The torn-line test in test_m5_observability.py.

Docs updated

• README (status line, usage with the screenshot, docs list, ADR list, roadmap)
• docs/ARCHITECTURE.md (the package in the tree)
• ADR 0017 (read-only and local only; extra; plain JS; reuse; polling; statuses; the attempt in progress; live files; out of scope: answering stops, Postgres)
• CHANGELOG [Unreleased]
• Docstrings for changed public APIs
• docs/OBSERVABILITY.md (new), docs/PRODUCT_MODE.md

Continuous improvement

• Issue ledger updated for every problem hit (ids: I-120 to I-139; I-121 wontfix, a refuted prediction; I-122 and I-123 open, pre-existing telemetry gaps; I-133 wontfix, documented)
• Each bug fix was swept across the codebase. Patterns searched:
  • checkpoint_id\|get_state( (I-120)
  • uv sync --extra (I-124)
  • write_text(\|open( (I-126)
  • load_entries(\|read_text(encoding="utf-8") (I-127)
  • websocket_connect( (I-128)
  • wait_for_function (I-129)
  • uvicorn\.\|serve_forever\|HTTPServer( (I-132)
  • __interrupt__ (I-134)
  • branch:to: (I-136)
  • the toolchain boundary scan (I-139)
• Retrospective and bottleneck audit: docs/LESSONS_LEARNED.md, "The dashboard". Guardrails 20 to 34 each name a guard; new scans: test_lf_writes.py, test_every_node_interrupts_at_most_once.

Shared code fixed along the way:

• CostLedger.load_entries keeps only complete lines, so scio report no longer dies on a live run's half-written ledger line (I-127; the test fails on the old code).
• _read_artifact replaces a broken character instead of raising.

Risk notes

• New optional dependencies: FastAPI 0.162 and uvicorn 0.54, in the dashboard extra only; uv.lock updated. The core install is unchanged, and scio dashboard without the extra says how to install it (--all-extras, never a bare --extra, I-124).
• The diagram needs cdnjs (pinned, SRI); without it the diagram falls back to text.
• Statuses read from the DB have two documented limits:
  • a resumed crashed thread reads crashed until the resumed node returns (I-133);
  • a process killed without an exception reads in_progress, and only "last update" shows it.
• Rollback: the feature is additive. Revert the PR, or simply don't run scio dashboard.

Bottleneck audit

• Slowest steps:
  • the page agent: 35 minutes, mostly Playwright waits;
  • diagnosing I-132: about 15 minutes, a shutdown hang that appeared only in the full parallel run;
  • the review: about 20 minutes, and worth it.
• Could have run in parallel: the snapshot live check could have started as soon as the API and page were committed.
• Improvement: the wave gate is now the full parallel suite, because I-132 and I-139 each showed only there. Reusable: tests/live/test_dashboard_server.py::_Server runs uvicorn as the CLI does.

Agent run log

Not a SCIO agent PR: built by Claude Code sessions (an orchestrator, four wave agents and a review agent).

🤖 Generated with Claude Code