Add read-only experiment viewer with Harbor inspection

[zimuwang-real]

Summary

• add a read-only evolve view command for generated experiment workspaces
• show experiment health, generation stages, modifications, canonical performance, and paginated trials
• provide bounded built-in previews for diffs, JSON, source files, and plain text
• link retained trial evidence into Harbor trajectory, logs, verifier, artifact, and configuration inspection
• document local and DevBox usage, SSH tunneling, page semantics, safety, and troubleshooting

Why

Experiment progress and evidence currently live across archive rows, stage artifacts, evaluation records, and Harbor job folders. This viewer provides one simple local surface for inspecting that evidence without changing experiment state.

Notable fixes

• use a fixed 0–1 canonical-score axis with explicit generation labels
• scope application table CSS so Diff2Html line numbers remain aligned
• disable shell/asset caching to prevent stale deployments
• replace Harbor job-directory symlinks with a disposable hard-link index so Harbor's path-containment checks accept trajectory and file endpoints
• block mutating and action-shaped Harbor routes in the composed server

Validation

• uv run pytest -q: 557 passed
• node --test tests/frontend/viewer-ui.test.mjs: 5 passed
• node --check src/evolve/viewer/static/app.js
• uv run ruff check .
• production wheel build completed and includes viewer assets and third-party notices
• live tau3-bench banking run verified through an SSH tunnel: overview, G0–G10 graph, formatted diff, 50 generation-10 trial links, Harbor trajectory, Agent, and Config views

Safety

The viewer binds to loopback by default, exposes registered/bounded artifact reads, and permits only GET/HEAD/OPTIONS. It is an inspection surface, not an authorization boundary.

Summary by CodeRabbit

• New Features

  • Added a read-only experiment viewer accessible through the evolve view command.
  • Added overview, generation, trial, Harbor inspection, artifact preview, filtering, pagination, and refresh capabilities.
  • Added responsive navigation and status displays for experiment health, stages, changes, performance, and trials.
  • Added safeguards including read-only access, bounded previews, path validation, and stale-snapshot preservation.

• Documentation

  • Added startup, access, usage, limitations, security, and troubleshooting guidance for the experiment viewer.

• Tests

  • Added comprehensive coverage for viewer navigation, snapshots, artifacts, Harbor integration, filtering, refresh behavior, and access restrictions.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 5f70a66c-dfd0-49bc-88b8-447e6731ce08

📥 Commits

Reviewing files that changed from the base of the PR and between ebb00de and c511224.

⛔ Files ignored due to path filters (5)

• src/evolve/viewer/static/vendor/diff2html.min.css is excluded by !**/*.min.css
• src/evolve/viewer/static/vendor/diff2html.min.js is excluded by !**/*.min.js
• src/evolve/viewer/static/vendor/highlight-github.min.css is excluded by !**/*.min.css
• src/evolve/viewer/static/vendor/highlight.min.js is excluded by !**/*.min.js
• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (27)

• ARCHITECTURE.md
• README.md
• docs/README.md
• docs/experiment-viewer.md
• pyproject.toml
• src/evolve/archive.py
• src/evolve/cli.py
• src/evolve/viewer/__init__.py
• src/evolve/viewer/app.py
• src/evolve/viewer/harbor_bridge.py
• src/evolve/viewer/models.py
• src/evolve/viewer/reader.py
• src/evolve/viewer/snapshot.py
• src/evolve/viewer/static/app.js
• src/evolve/viewer/static/index.html
• src/evolve/viewer/static/styles.css
• src/evolve/viewer/static/vendor/LICENSE.diff2html
• src/evolve/viewer/static/vendor/LICENSE.highlight.js
• src/evolve/viewer/static/vendor/THIRD_PARTY_NOTICES.md
• src/evolve/viewer/static/viewer-ui.js
• tests/frontend/viewer-ui.test.mjs
• tests/test_viewer_app.py
• tests/test_viewer_archive.py
• tests/test_viewer_cli.py
• tests/test_viewer_harbor_bridge.py
• tests/test_viewer_reader.py
• tests/test_viewer_snapshot.py

---

📝 Walkthrough

Walkthrough

Added a read-only evolve view experiment viewer. It reads workspace data, derives snapshots, federates Harbor evidence, serves FastAPI endpoints, renders a responsive frontend, and includes CLI wiring, tests, dependencies, and documentation.

Changes

Experiment viewer

Layer / File(s)	Summary
Workspace data and snapshot pipeline src/evolve/viewer/models.py, src/evolve/viewer/reader.py, src/evolve/viewer/snapshot.py, src/evolve/archive.py, tests/test_viewer_reader.py, tests/test_viewer_snapshot.py, tests/test_viewer_archive.py	Added typed viewer models, workspace parsing, archive merging, snapshot construction, stage and trial summaries, artifact registration, health classification, and validation tests.
Harbor evidence federation src/evolve/viewer/harbor_bridge.py, tests/test_viewer_harbor_bridge.py	Added temporary Harbor job federation, stable naming, canonical task matching, trial links, legacy evidence parsing, cleanup, and integration tests.
Viewer API and CLI integration src/evolve/viewer/app.py, src/evolve/viewer/__init__.py, src/evolve/cli.py, pyproject.toml, ARCHITECTURE.md, README.md, docs/README.md, docs/experiment-viewer.md, tests/test_viewer_app.py, tests/test_viewer_cli.py	Added FastAPI routes, refresh handling, bounded artifact reads, read-only request controls, static serving, port selection, CLI startup, runtime dependencies, documentation, and API tests.
Browser interface and artifact presentation src/evolve/viewer/static/*, tests/frontend/viewer-ui.test.mjs	Added the HTML shell, responsive styling, client-side routing, polling, overview and detail pages, artifact rendering, trial filters, score charts, vendored assets, notices, and frontend tests.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant FastAPI
  participant SnapshotStore
  participant WorkspaceReader
  participant HarborBridge
  participant Browser

  CLI->>FastAPI: run_viewer(workspace, host, port_spec)
  Browser->>FastAPI: GET snapshot or generation data
  FastAPI->>SnapshotStore: refresh workspace state
  SnapshotStore->>WorkspaceReader: read workspace sources
  SnapshotStore->>HarborBridge: refresh Harbor job federation
  SnapshotStore-->>FastAPI: return viewer snapshot
  FastAPI-->>Browser: return JSON snapshot and artifact metadata
  Browser->>FastAPI: poll snapshot every three seconds

Loading

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands.}