diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2e833ddc..80233df6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "name": "humanize", "source": "./", "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.", - "version": "1.16.0" + "version": "1.17.0" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index fd77b933..88a16169 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "humanize", "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.", - "version": "1.16.0", + "version": "1.17.0", "author": { "name": "PolyArch" }, diff --git a/.gitignore b/.gitignore index e5bcf34c..0d3f713a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,9 @@ temp /.claude/settings.json /.claude/scheduled_tasks.lock +# Local Codex CLI marker (empty file occasionally left behind in worktree) +/.codex + # Humanize state directories (runtime-generated, project-local) .humanize/ .claude-flow/ diff --git a/README.md b/README.md index 05f2fdd3..b28312aa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Humanize -**Current Version: 1.16.0** +**Current Version: 1.17.0** > Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project. @@ -74,8 +74,15 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [ humanize monitor skill # All skill invocations (codex + gemini) humanize monitor codex # Codex invocations only humanize monitor gemini # Gemini invocations only + humanize monitor web # Browser dashboard for the current project ``` + The `humanize monitor web` subcommand launches a per-project browser dashboard + that layers on top of the same data sources the terminal monitors read. It runs + in the foreground by default; pass `--daemon` for the background tmux launcher + and `--host` / `--port` / `--auth-token` to configure remote access. See the + upgrade note: `/humanize:viz` has been removed in favour of `humanize monitor web`. + ## Monitor Dashboard

diff --git a/docs/drafts/viz-monitor-web.md b/docs/drafts/viz-monitor-web.md new file mode 100644 index 00000000..547b9821 --- /dev/null +++ b/docs/drafts/viz-monitor-web.md @@ -0,0 +1,107 @@ +# Draft: Optimize viz-dashboard — Merge into `humanize monitor` as a Web View + +## Background + +The `feat/viz-dashboard` branch currently introduces a `/humanize:viz` Claude +slash command and a local visualization dashboard for Humanize. While the +dashboard does show some data, the visualization of a *live, dynamically +running RLCR loop* is not clear enough today: status, progress per round, and +streamed log output are hard to follow as a loop progresses. + +Separately, Humanize already ships a CLI-side monitoring capability that the +user runs in another terminal (NOT inside Claude Code): + +```bash +source /scripts/humanize.sh # or add to .bashrc / .zshrc + +humanize monitor rlcr # RLCR loop +humanize monitor skill # All skill invocations (codex + gemini) +humanize monitor codex # Codex invocations only +humanize monitor gemini # Gemini invocations only +``` + +This monitor capability already captures live state (RLCR rounds, skill / Codex +/ Gemini invocations, log output). The web dashboard does not need to invent +its own capture pipeline — it should consume what `humanize monitor` already +provides. + +## Goal + +Optimize the viz-dashboard branch so that: + +1. The dashboard becomes a **web view** layered on top of the existing + `humanize monitor` data sources, rather than an independent capture layer. +2. The dashboard can show **multiple live RLCR loops simultaneously**, with + per-loop status and streamed log output. +3. The entry point moves out of Claude (no more `/humanize:viz` slash command) + and into the `humanize monitor` CLI command, as a new web-online viewing + subcommand. +4. The new capability targets **online / remote viewing in a browser**, not a + local-only viewer that requires the user to be on the same machine running + Claude. +5. Useful features from the existing viz-dashboard branch — notably **cross- + conversation querying** (browsing past sessions / loops across different + Claude conversations) — are preserved. + +## Non-goals + +- Reimplementing the monitor capture pipeline (`humanize monitor rlcr/skill/ + codex/gemini`). The dashboard consumes it; it does not replace it. +- Continuing to ship `/humanize:viz` as a Claude slash command. +- Adding chart panels or features explicitly removed in commit 1b575fe + ("multi-project switcher + restart + remove chart panels"). + +## Required behaviors + +1. **CLI entry point unification** + - Remove `commands/viz.md` and any `/humanize:viz` Claude command surface. + - Add a new `humanize monitor` subcommand (name to be agreed during + planning, e.g. `humanize monitor web` or `humanize monitor dashboard`) + that starts the web dashboard server. + - The other `humanize monitor rlcr|skill|codex|gemini` subcommands must + keep working unchanged (terminal-attached live tail). + +2. **Live multi-loop view** + - The web dashboard MUST be able to display 2+ concurrently running RLCR + loops at the same time, each with: + - current status (running, paused, converged, stopped, …) + - current round / phase + - live streamed log output, updated in near real time + +3. **Reuse existing monitor data** + - The dashboard MUST source its data from the same files / events that + `humanize monitor rlcr/skill/codex/gemini` already read. It MUST NOT add + a parallel capture mechanism (no new hooks just for the dashboard). + +4. **Online / remote-viewable** + - The dashboard MUST be reachable from a browser over the network, not + only via `localhost` on the machine running Claude. Concrete binding / + auth design to be agreed during planning. + +5. **Cross-conversation history** + - Cross-conversation querying (browsing past loops from different Claude + conversations / sessions) from the existing viz-dashboard branch MUST be + preserved. + +## Branch hygiene + +Before implementation begins, the branch `feat/viz-dashboard` MUST be rebased +onto the latest `upstream/dev` (humania-org/humanize). Several relevant changes +have landed on `upstream/dev` after the branch diverged, including: + +- `Add ask-gemini skill and tool-filtered monitor subcommands` (introduces the + `humanize monitor skill|codex|gemini` subcommands the dashboard must reuse) +- `Remove PR loop feature entirely` (the viz-dashboard branch still references + PR-loop concepts via `commands/cancel-pr-loop.md`, `commands/start-pr-loop.md`, + `hooks/pr-loop-stop-hook.sh`) +- Multiple monitor / hook fixes + +The rebase is therefore both a precondition for correctness (the dashboard +consumes the new monitor subcommands) and a cleanup step (PR-loop references +must be dropped). + +## Out of scope (for this plan) + +- Changes to RLCR semantics, hooks, or skill behavior. +- Authentication providers, identity systems, or multi-user account models — + basic remote-access protection is in scope, but full IAM is not. diff --git a/docs/plans/viz-monitor-web.md b/docs/plans/viz-monitor-web.md new file mode 100644 index 00000000..e90fee83 --- /dev/null +++ b/docs/plans/viz-monitor-web.md @@ -0,0 +1,470 @@ +# Optimize viz-dashboard: Merge into `humanize monitor` as a Web View + +## Goal Description + +Optimize the `feat/viz-dashboard` branch so that the RLCR visualization becomes a web view layered on top of the existing `humanize monitor` data sources, supports multiple concurrent live RLCR loops with real-time streamed log output, moves the entry point out of Claude (no more `/humanize:viz` slash command) into a new `humanize monitor web` CLI subcommand, exposes the dashboard for online (browser) viewing with explicit network-binding and authentication controls, and preserves cross-conversation history browsing. + +The dashboard MUST consume the same files and events that `humanize monitor rlcr|skill|codex|gemini` already read; it MUST NOT introduce a parallel capture pipeline (no new hooks just for the dashboard). The single-server-per-project model replaces the existing server-global project switcher to eliminate the cross-client mutation bug. Remote access defaults to safe (localhost-only) and requires an explicit token to expose data or actions to the network. + +## Acceptance Criteria + +Following TDD philosophy, each criterion includes positive and negative tests for deterministic verification. + +- AC-1: CLI entry-point migration from Claude command to `humanize monitor web`. + - Positive Tests (expected to PASS): + - `humanize monitor web --project

` starts the dashboard server and prints the bound URL. + - `humanize monitor rlcr`, `humanize monitor skill`, `humanize monitor codex`, `humanize monitor gemini` continue to behave exactly as before this change (verified by snapshot tests of usage text and exit behavior). + - `humanize monitor` (no subcommand) prints usage that includes `web` alongside `rlcr|skill|codex|gemini`. + - Negative Tests (expected to FAIL/be rejected): + - The Claude slash command `/humanize:viz` is no longer registered (`commands/viz.md` removed); attempting to invoke it through Claude does not resolve. + - `humanize monitor unknownsub` exits non-zero with usage; it does NOT silently fall through to a default. + +- AC-2: Data-source reuse — no parallel capture pipeline. + - Positive Tests: + - With an active RLCR loop, `viz/server/parser.py` reads session metadata from `.humanize/rlcr//{state.md,goal-tracker.md,round-*-summary.md,round-*-review-result.md}` AND streamed bytes from `~/.cache/humanize///round-*-codex-{run,review}.log`. + - A test that intercepts file opens shows the dashboard reading from the same paths the RLCR monitor uses (parity test against `scripts/humanize.sh` cache lookup logic at lines around 284-368). + - Negative Tests: + - Grep over `hooks/` shows no new `*-viz-*.sh` or dashboard-only hook script added. + - Grep over `viz/` shows no path writing to `.humanize/rlcr/` (the dashboard is a reader, not a writer of session state). + +- AC-3: Multi-loop concurrent view enumerates all sessions, not only the newest. + - Positive Tests: + - With two concurrent active RLCR loops in the same project, the home page renders both session cards simultaneously, each showing session id, status, current round/max, current phase, and an independently updating live log pane. + - Session enumeration covers ALL directories under `.humanize/rlcr/`, partitioned into "active" (state.md present) vs "historical" (terminal `*-state.md` present). + - Negative Tests: + - The dashboard does NOT auto-switch to the newest session (the single-session behavior of `monitor_find_latest_session` in `scripts/lib/monitor-common.sh` MUST NOT leak into the web view). + - Adding a new active session while another is running does NOT remove or hide the existing one in the UI. + +- AC-4: Live-log latency budget — append visible in browser within 2 seconds (HARD requirement). + - Positive Tests: + - An automated test appends N bytes to an active `round-*-codex-run.log`; the browser-side stream client receives those bytes within 2 seconds (measured end-to-end on the test harness). + - The streaming protocol delivers an initial snapshot followed by byte-offset append events (snapshot + offset tail). + - Truncation/rotation of the underlying log triggers a documented resync path (e.g. detect size shrink, restart from snapshot at offset 0). + - Negative Tests: + - The active-log path does NOT use a polling loop that re-fetches the full file body on every update. + - Median measured append-to-render latency under nominal load does NOT exceed 2.0s; failure of this assertion fails CI. + +- AC-5: Cross-conversation / historical browsing preserved. + - Positive Tests: + - Completed sessions stored under `.humanize/rlcr/` from prior Claude conversations are listed in the "Historical" section and individually browsable. + - Ending an active loop transitions that session card from "Active" to "Historical" without removing it from view. + - Negative Tests: + - A finished session does NOT disappear from the dashboard after its terminal `*-state.md` appears. + - Switching between active and historical views does NOT clear the other list. + +- AC-6: Remote-reachable + access controlled across ALL data surfaces. + - Positive Tests: + - With default flags, the server binds to `127.0.0.1` only. + - With `--host 0.0.0.0` (or any non-localhost host), startup REQUIRES a non-empty `--auth-token` (or the equivalent env var); otherwise the process exits non-zero with a clear error. + - In remote mode, every endpoint (session list, session detail, per-session log SSE stream, control endpoints) requires a valid token; missing/invalid token returns 401. + - Negative Tests: + - Starting the server with `--host 0.0.0.0` without a token does NOT start; it errors out. + - An unauthenticated remote request to `/api/sessions/` or the per-session SSE stream is rejected with 401, not served. + - The server does NOT bind to `0.0.0.0` by default under any path of `humanize monitor web`. + +- AC-7: Session-targeted cancel built and tested (per DEC-2 = build session-scoped cancel). + - Positive Tests: + - A new session-scoped cancel shell helper (next to `scripts/cancel-rlcr-loop.sh`) accepts a session id and cancels only that session. + - The dashboard cancel UI hits a per-session API; cancelling session A does not affect session B. + - Negative Tests: + - Calling the per-session cancel endpoint without specifying a session id returns 400, not a project-wide cancel. + - The dashboard does NOT directly call the existing project-global `scripts/cancel-rlcr-loop.sh` without a session id. + +- AC-8: Multi-instance / project-isolation cleanups (per DEC-3 = CLI-fixed single project). + - Positive Tests: + - `viz/scripts/viz-start.sh` (or its replacement) uses a per-project tmux session name so starting a second project's dashboard does NOT kill the first. + - The per-project port file `.humanize/viz.port` is also per-project and does not collide. + - The server binds to one project chosen at startup via `--project`; there is no runtime project switch endpoint. + - Negative Tests: + - `viz/server/app.py` no longer exposes `/api/projects/switch` (or it returns 410/501 with a deprecation message). + - `viz/static/js/app.js` and `viz/static/js/actions.js` no longer render or wire a project switcher / "+ Add" UI; tests grep for these handlers and assert their removal. + - Starting `humanize monitor web --project A` while a `--project B` instance is already running does NOT terminate the project-B server. + +- AC-9: Test coverage matrix. + - Positive Tests (the suite must include and pass): + - Two concurrent active RLCR sessions render and stream independently. + - Session with `.humanize/rlcr/` metadata but no cache logs yet (startup race) renders without crashing and recovers when logs appear. + - Cache-log truncation/rotation triggers a documented resync rather than silent stall. + - Remote-mode auth enforcement: missing/invalid token => 401 on every data and control endpoint. + - Project-isolation: starting a second `humanize monitor web --project ` does NOT affect the first. + - Backward-compat: `humanize monitor rlcr|skill|codex|gemini` outputs unchanged (snapshot tests). + - Cache-path / session-mapping parity tests against `scripts/humanize.sh` (the source of truth at lines around 284-368). + - Negative Tests: + - Tests do NOT write into the user's real `~/.humanize` or `~/.cache/humanize`; all fixtures live under a tmp dir or repo `tests/` fixture tree. + - No test depends on network access to the public internet. + +- AC-10: Code style compliance. + - Positive Tests: + - Grep over `viz/`, `scripts/`, and changed `commands/`/`hooks/` files for the literal substrings `AC-`, `Milestone`, `Step `, `Phase ` (with trailing space) returns zero matches in implementation code or comments (matches in plan/doc files do not count). + - Negative Tests: + - Adding new code with any of those workflow markers fails the style check. + +## Path Boundaries + +Path boundaries define the acceptable range of implementation quality and choices. + +### Upper Bound (Maximum Acceptable Scope) + +The implementation provides: +- An RLCR-specific Python helper (e.g. `viz/server/rlcr_sources.py`) that owns session enumeration and cache-log path discovery, with parity tests against `scripts/humanize.sh` (lines around 284-368). +- A frozen one-page event-protocol contract document (output of T2 architecture review) that fixes snapshot+byte-offset semantics, truncation/rotation handling, and the per-session vs project channel scoping. +- Per-session SSE streams over HTTP(S), each carrying an initial snapshot followed by append events identified by file path + byte offset. +- Bearer-token auth via query parameter on SSE streams and via `Authorization` header on standard HTTP endpoints; flask_sock WebSocket retained ONLY for localhost-bound deployments. +- Session-targeted cancel: a new `scripts/cancel-rlcr-session.sh` (or named equivalent) helper plus a per-session API endpoint, fully tested. +- A multi-loop UI grid that always shows every active session at once, with an inline expand-to-detail per-session log pane (no full-page navigation required to see live logs). +- A single-project-per-server CLI model: `humanize monitor web --project `. The `/api/projects/switch` endpoint and the `+ Add` / Switch UI elements in `viz/static/js/app.js` and `viz/static/js/actions.js` are fully removed. +- Per-project tmux session naming and per-project port file for the optional `--daemon` mode (per DEC-1). +- Documentation for two remote-deployment patterns (SSH tunnel example FIRST, LAN bind example SECOND) plus an upgrade note explaining the `/humanize:viz` removal. +- Full test matrix per AC-9. + +### Lower Bound (Minimum Acceptable Scope) + +The implementation provides: +- Extensions to the existing `viz/server/parser.py` and `viz/server/watcher.py` so they additionally ingest cache round logs (`codex-run.log`, `codex-review.log`, gemini variants when present) and emit append events with byte offsets. +- A new per-session SSE endpoint in `viz/server/app.py` that supports the snapshot+offset protocol agreed in the T2 contract document, including a documented resync path for truncation. +- A new `humanize monitor web` dispatch entry in `scripts/humanize.sh` (alongside `rlcr|skill|codex|gemini`) that runs the dashboard in the foreground by default; an optional `--daemon` flag launches the existing tmux-managed server with a per-project tmux name and port file. +- `--host`, `--port`, `--auth-token` flags in `viz/server/app.py` (and forwarded by `humanize monitor web`); the server binds to `127.0.0.1` by default; non-localhost binding requires a non-empty token; unauthenticated remote requests are rejected on EVERY data and control endpoint, not just mutators. +- Removal of the server-global project switch: `/api/projects/switch` and the `+ Add` / Switch UI flows in `viz/static/js/app.js` and `viz/static/js/actions.js` are removed. `viz-projects.json` is no longer mutated by the server in v1. +- Removal of `/humanize:viz`: `commands/viz.md` and `skills/humanize-viz/SKILL.md` are deleted; a brief upgrade note is added to `README.md` (or equivalent) pointing users at `humanize monitor web`. +- The session-targeted cancel helper and per-session cancel API (per DEC-2 = build session-scoped cancel). +- All tests in AC-9 are present and pass in CI. +- Documentation: at minimum, the SSH tunnel deployment pattern. + +### Allowed Choices + +- Can use: + - The existing Flask + flask_sock stack (retained for localhost) plus a new SSE endpoint for per-session log streams. + - Reusing or extracting helper logic from `scripts/humanize.sh` for RLCR-specific cache-path discovery (RLCR-only — do not merge skill-monitor cache rules). + - Per-session byte offsets, file-path-keyed event streams. + - Either `python -m venv` (current `viz-start.sh` model) or system python for the foreground CLI invocation. + - Token sources: CLI flag `--auth-token `, env var `HUMANIZE_VIZ_TOKEN`, or a token file at `${XDG_CONFIG_HOME:-$HOME/.config}/humanize/viz-token`. +- Cannot use: + - New Claude hooks added solely to capture data for the dashboard. + - Default network bind to `0.0.0.0` (must be opt-in). + - OAuth / OIDC / external IAM providers in v1. + - A cross-language shared "monitor-core" library that conflates the RLCR session model with the skill-invocation model. + - WebSocket as the remote-mode transport for log streams (browser WS cannot set `Authorization` headers; remote streams must be SSE per DEC-4). flask_sock WS may remain for localhost-bound use. + - Project-global cancel paths wired to per-session UI without explicit user warnings (per DEC-2 the dashboard MUST use a session-scoped cancel helper). + +> **Note on Deterministic Designs**: DEC-1, DEC-2, DEC-3, and DEC-4 have already been fixed by user decision (recorded under `## Pending User Decisions`). The path boundaries above already reflect those choices and do not leave room for alternative interpretations of those four points. + +## Feasibility Hints and Suggestions + +> **Note**: This section is for reference and understanding only. These are conceptual suggestions, not prescriptive requirements. + +### Conceptual Approach + +One viable path: + +1. Branch hygiene as a parallel preflight track. Rebase `feat/viz-dashboard` onto `upstream/dev` (currently 9 commits ahead). Conflicts are expected to be small because the branch already includes upstream commits 338b4dd (PR-loop removal) and 016caca (monitor split). +2. Add a small, RLCR-specific Python module (e.g. `viz/server/rlcr_sources.py`) that owns: + - listing all session directories under `.humanize/rlcr//`, + - mapping each session to its cache-log directory under `~/.cache/humanize///`, + - returning per-session live log file paths (`round-N-codex-run.log`, `round-N-codex-review.log`, gemini variants). + Cover this module with parity tests that compare its outputs against the discovery logic in `scripts/humanize.sh` (around lines 284-368). +3. Run a focused architecture-review consultation (T2, `analyze` task via `/humanize:ask-codex`) to freeze the streaming protocol contract: snapshot+offset semantics, truncation/rotation behavior, per-session vs project channel scoping. Output a one-page contract document that subsequent code refers to. +4. Extend `viz/server/parser.py` to use the new helper and to read cache round logs (with graceful fallback when files are missing/partial). Extend `viz/server/watcher.py` to also watch the cache log directory and emit append events with `(path, offset, len)`. +5. Add a per-session SSE endpoint in `viz/server/app.py` keyed by session id; it serves a snapshot then appends; it survives truncation by detecting size shrink and restarting from offset 0 with a documented resync event. +6. Add `humanize monitor web` to the dispatch in `scripts/humanize.sh` next to `rlcr|skill|codex|gemini`. Foreground default; pass-through `--host`, `--port`, `--auth-token`, `--project`, `--daemon`. The `--daemon` path delegates to a refactored `viz/scripts/viz-start.sh` that uses a per-project tmux name and per-project port file. +7. Delete `commands/viz.md` and `skills/humanize-viz/SKILL.md`; add a one-line note in `README.md` directing users to `humanize monitor web`. +8. Replace the project switcher backend by a CLI-fixed model: remove `/api/projects/switch` from `viz/server/app.py`; remove the switch / + Add UI from `viz/static/js/app.js` and `viz/static/js/actions.js`. The frontend reads only the project the server was started against. +9. Add `--host`, `--port`, `--auth-token`. Default `--host=127.0.0.1`. If host is non-localhost, require a non-empty token. Apply auth middleware to ALL data and control endpoints (session list, session detail, SSE streams, cancel/report). Token propagation in the frontend: `Authorization: Bearer ` for fetch; `?token=` query parameter for `EventSource`. +10. Build the session-targeted cancel helper (e.g. `scripts/cancel-rlcr-session.sh`) and wire a `POST /api/sessions//cancel` route to it. Mirror the existing project-global script's safety conventions. +11. Multi-loop UI: render all active sessions on the home page in a grid, each with an inline live-log pane that opens an SSE stream when expanded. Historical sessions are listed below. +12. Build the test matrix per AC-9. Use a tmp `.humanize/rlcr/` and tmp `~/.cache/humanize/` fixture tree per test. +13. Document the SSH tunnel deployment pattern first; add a LAN bind example second. + +### Relevant References + +- `scripts/humanize.sh:1196` — `humanize` dispatcher; this is where `monitor web` is added. +- `scripts/humanize.sh` (around lines 284-368) — current RLCR cache-log discovery logic; source of truth for parity tests. +- `scripts/lib/monitor-common.sh` — shared shell helpers (single-session by design); reused for terminal monitor only. +- `scripts/lib/monitor-skill.sh` — skill cache discovery (separate model from RLCR); deliberately NOT merged into the RLCR helper. +- `scripts/cancel-rlcr-loop.sh` — existing project-global cancel; the new session-scoped helper sits next to it. +- `viz/server/parser.py` — RLCR session parser; extended to read cache logs. +- `viz/server/watcher.py` — watchdog observer; extended to watch cache log dirs and emit append events. +- `viz/server/app.py` — Flask routes; gains `--host/--port/--auth-token`, per-session SSE, session-scoped cancel; loses `/api/projects/switch`. +- `viz/scripts/viz-start.sh` — tmux launcher; refactored for per-project naming and `--daemon` mode. +- `viz/static/js/app.js` and `viz/static/js/actions.js` — UI; loses project switcher; gains multi-session grid + per-session SSE client with token propagation. +- `commands/viz.md`, `skills/humanize-viz/SKILL.md` — deleted. +- `tests/test-viz.sh` — extended with the AC-9 matrix. +- `README.md`, `docs/usage.md` — gain monitor `web` entry and the remote-deploy guide. + +## Dependencies and Sequence + +### Milestones + +1. M0 Branch hygiene (preflight, parallel track): + - Sub-step A: Fetch `upstream/dev`, list the 9 commits ahead, rebase `feat/viz-dashboard`, resolve conflicts. + - Sub-step B: Re-run existing tests (`tests/test-viz.sh` and any monitor smoke test). + - This milestone is NOT a hard gate for design tasks; T1+ may proceed once conflicts are mechanically resolved. +2. M1 Discovery and ingestion: + - Sub-step A: RLCR-specific session+cache-log discovery helper (T1). + - Sub-step B: Parser and watcher extensions to ingest cache round logs (T3, T4). +3. M2 Streaming protocol freeze (architecture gate): + - Sub-step A: Architecture review (T2, analyze) producing a one-page contract document for snapshot+offset semantics, truncation handling, channel scoping. + - This milestone gates T3/T4/T5 implementation details that depend on the contract. +4. M3 Live multi-loop streaming: + - Sub-step A: Per-session SSE endpoint (T5). + - Sub-step B: Multi-loop UI with independent live log panes (T6). +5. M4 CLI consolidation: + - Sub-step A: Add `humanize monitor web` to dispatch (T8). + - Sub-step B: Per-project tmux + port file refactor (T9). + - Sub-step C: Remove `/humanize:viz` (T12). +6. M5 Remote access + safety: + - Sub-step A: `--host/--port/--auth-token` + auth middleware on all surfaces (T11). + - Sub-step B: Remove server-global project switch and frontend switcher (T10). + - Sub-step C: Session-targeted cancel helper + endpoint (T7). +7. M6 Tests + docs: + - Sub-step A: Test matrix per AC-9 (T13). + - Sub-step B: Documentation: README monitor section + remote-deploy guide (T14). + +Relative dependencies: M2 must precede the streaming-shape decisions in M1's parser/watcher work and all of M3. M5 access-control work (T11) depends on the basic streaming endpoints (M3) being available so it can layer auth on top. M6 tests depend on M3 + M4 + M5 being feature-complete. M0 is independent and can run alongside M1 until conflicts are mechanically resolved. + +## Task Breakdown + +Each task includes exactly one routing tag: +- `coding`: implemented by Claude +- `analyze`: executed via Codex (`/humanize:ask-codex`) + +| Task ID | Description | Target AC | Tag | Depends On | +|---------|-------------|-----------|-----|------------| +| T0 | Preflight (parallel track): rebase `feat/viz-dashboard` onto `upstream/dev` (9 commits), resolve conflicts, rerun existing tests. NOT a hard gate for T1+. | AC-9 | coding | - | +| T1 | RLCR-specific session + cache-log discovery helper (e.g. `viz/server/rlcr_sources.py`); RLCR-only (do NOT merge skill-monitor cache rules); enumerates ALL sessions under `.humanize/rlcr/`. | AC-2, AC-3 | coding | - | +| T2 | Architecture review: select event protocol shape (snapshot + byte-offset tail, truncation/rotation behavior, per-session vs project channels) and confirm transport (SSE for remote streams + retained flask_sock for localhost only). Output: one-page contract document committed under `docs/`. | AC-4 | analyze | T1 | +| T3 | Extend `viz/server/parser.py` to ingest cache round logs (`codex-run.log`, `codex-review.log`, gemini variants); fall back gracefully when missing or partially written. | AC-2, AC-4 | coding | T2 | +| T4 | Extend `viz/server/watcher.py` to also watch the cache log directory; emit per-file append events `(path, offset, length)` per the T2 contract. | AC-4 | coding | T2 | +| T5 | Per-session SSE endpoint in `viz/server/app.py` per the T2 contract; supports initial snapshot then append; handles rotation/truncation resync. | AC-4 | coding | T3, T4 | +| T6 | Multi-loop UI in `viz/static/js/app.js`: list ALL sessions, partition into Active vs Historical, render every active session simultaneously with an independent live log pane (no fallback to single-session detail view for active loops). | AC-3, AC-5 | coding | T5 | +| T7 | Session-scoped cancel: new `scripts/cancel-rlcr-session.sh` helper + `POST /api/sessions//cancel` route + UI wiring; do NOT delegate to the project-global `scripts/cancel-rlcr-loop.sh`. | AC-7 | coding | T5 | +| T8 | Add `humanize monitor web` to the dispatch in `scripts/humanize.sh` next to `rlcr|skill|codex|gemini`; foreground default; pass-through `--host/--port/--auth-token/--project/--daemon`; preserve existing subcommands and usage text. | AC-1 | coding | - | +| T9 | Refactor `viz/scripts/viz-start.sh`: per-project tmux session name (no more global `humanize-viz`); per-project port file; only invoked by the `--daemon` path of `humanize monitor web`. | AC-8 | coding | T8 | +| T10 | Remove server-global project mutation in `viz/server/app.py`: remove `/api/projects/switch` (or convert to read-only listing); remove project switcher / + Add flows in `viz/static/js/app.js` and `viz/static/js/actions.js`; do not mutate `viz-projects.json` from server. | AC-5, AC-8 | coding | T8 | +| T11 | Add `--host`, `--port`, `--auth-token` to `viz/server/app.py` + propagate through `viz/scripts/viz-start.sh` and `humanize monitor web`; default `--host=127.0.0.1`; reject non-local startup without token; gate ALL data/control endpoints (session list, session detail, SSE stream, cancel) behind token in remote mode; frontend token propagation: `Authorization: Bearer` for fetch + `?token=...` for SSE `EventSource`. | AC-6 | coding | T5, T10 | +| T12 | Remove `/humanize:viz`: delete `commands/viz.md` and `skills/humanize-viz/SKILL.md`; add a one-line upgrade note in `README.md` pointing users at `humanize monitor web`. | AC-1 | coding | T8 | +| T13 | Test matrix per AC-9: concurrent active loops, missing-cache-log startup, log rotation/truncation recovery, remote auth on every endpoint, project isolation, monitor backward-compat, per-project port-file collision avoidance, parity tests for cache-path/session mapping vs `scripts/humanize.sh`. | AC-9 | coding | T6, T7, T11 | +| T14 | Docs: README monitor section update; remote-deploy guide (SSH tunnel example FIRST, LAN bind example SECOND); upgrade note for `/humanize:viz` removal. | AC-1, AC-6 | coding | T13 | + +## Claude-Codex Deliberation + +### Agreements + +- Reusing the existing `humanize monitor` data sources (the `.humanize/rlcr//*` files plus `~/.cache/humanize///round-*-codex-{run,review}.log`) is the correct architecture; the dashboard is a reader, not a parallel capture pipeline. +- Moving the entry point into the `humanize monitor` dispatch in `scripts/humanize.sh` and removing `/humanize:viz` is a natural extension of the existing CLI shape and avoids a stranded slash-command surface. +- Tightening network exposure with localhost default plus explicit `--host` + `--auth-token` for remote opt-in is the right baseline given the unauthenticated mutators in the current `viz/server/app.py`. +- The current global `humanize-viz` tmux session name in `viz/scripts/viz-start.sh` is a real collision bug; per-project naming is required. +- The feat/viz-dashboard branch already includes upstream commits 338b4dd (PR-loop removal) and 016caca (monitor split). The rebase is therefore drift cleanup (9 commits), not a missing prerequisite. +- The streaming protocol must support snapshot + byte-offset append + truncation/rotation resync; "no full-file refetch loop" was tightened from "append-only forever" to allow legitimate snapshot/resync paths. + +### Resolved Disagreements + +- Topic: Should the rebase be the dependency root for the entire plan (M0/T0 as a hard gate)? + - Claude (v1): yes, M0 first, T0 blocks all other tasks. + - Codex: no, branch hygiene already includes the critical upstream commits; making T0 a hard gate turns unrelated upstream drift into a blocker for design. + - Resolution: M0/T0 is a parallel preflight track. T1+ may proceed once rebase conflicts are mechanically resolved. Recorded in M0 description and in T0's wording. + +- Topic: Should there be a single shared "monitor-core" library consumed by both terminal and web monitors? + - Claude (v1): yes, extract a shared module to keep terminal and web in lockstep. + - Codex: no, the shell `monitor-common.sh` is single-session by design and the web side is Python; forcing a cross-language core conflates models. + - Resolution: do NOT build a shared cross-language core. Keep terminal helpers in shell where they help; build a separate small RLCR-specific Python helper for the web side (`viz/server/rlcr_sources.py`) and validate it via parity tests against `scripts/humanize.sh` cache logic. + +- Topic: Should T2 (extract shared cache-discovery helper) merge logic from `scripts/humanize.sh` (RLCR) with `scripts/lib/monitor-skill.sh` (skill invocations)? + - Claude (v1): yes, factor the cache-discovery patterns into one helper. + - Codex: no, RLCR session caches and skill invocation caches are adjacent but different models; merging conflates them. + - Resolution: T1 helper is RLCR-specific only. Skill-monitor cache rules stay separate. + +- Topic: When should the architecture review for the streaming protocol shape happen? + - Claude (v1): T13 at the end, after watcher and endpoint code. + - Codex: backwards; it has to gate watcher and endpoint design. + - Resolution: T2 is now an `analyze` task that runs BEFORE T3/T4/T5 and outputs a one-page contract document. + +- Topic: Should the streaming protocol forbid full-file refetch entirely? + - Claude (v1): yes, append-only. + - Codex: append-only forever breaks late-joining clients and rotation recovery. + - Resolution: AC-4 reworded to "snapshot + byte-offset append + documented resync" and "no polling loop that re-fetches the full file body on every update." Both intents preserved. + +- Topic: Is removing `/api/projects/switch` enough to fix the multi-project bug? + - Claude (v1): yes. + - Codex: no, the frontend switcher / + Add flows in `viz/static/js/app.js` and `viz/static/js/actions.js` would still be wired. + - Resolution: T10 expanded to also remove the frontend switcher chrome; AC-8 expanded to test for the absence of these UI elements. + +- Topic: Does remote auth need to cover read endpoints, or just mutators? + - Claude (v2): just mutators. + - Codex: no, read endpoints serve session data too; remote unauth must be blocked everywhere. + - Resolution: AC-6 expanded; T11 expanded to cover ALL data and control surfaces, plus token propagation in the frontend (`Authorization` for fetch, `?token=...` for SSE). + +- Topic: Cancel semantics in the multi-loop UI. + - Claude (v1/v2): keep cancel + report. + - Codex: the existing `scripts/cancel-rlcr-loop.sh` is project-global, not session-targeted; either build a session-scoped path or freeze v1 with cancel disabled. + - Resolution: User chose DEC-2 = build session-scoped cancel. T7 builds a new `scripts/cancel-rlcr-session.sh` helper plus a per-session API and tests it. + +- Topic: Auth transport for live log streams (browser WebSocket cannot set `Authorization` header). + - Claude (v2): bearer token via `--auth-token`, transport unspecified. + - Codex: WS in browsers cannot send arbitrary auth headers; either define a precise WS auth handshake or drop WS for remote. + - Resolution: User chose DEC-4 = SSE over HTTPS with token query-param for remote streams; flask_sock WS retained for localhost only. + +### Convergence Status + +- Final Status: `converged` +- Convergence rounds executed: 3 (round 1 surfaced 7 required changes; round 2 surfaced 5 tighteners; round 3 returned no required changes and no high-impact disagreements). + +## Pending User Decisions + +All decisions raised during planning have been resolved by the user. None remain `PENDING`. + +- DEC-1: How should `humanize monitor web` be launched (lifecycle)? + - Claude Position: Foreground default + optional `--daemon` flag; matches CLI monitor UX and avoids hidden processes. + - Codex Position: Either foreground or daemon is defensible, but the v1 plan must pick one to avoid mixed ownership of `viz/scripts/viz-start.sh`. + - Tradeoff Summary: Foreground = matches `humanize monitor rlcr` UX, no orphan tmux sessions, simpler test harness. Daemon = "always on" convenience, but hidden processes and tmux name collisions to manage. + - Decision Status: `Foreground default + --daemon opt-in` (user-confirmed). + +- DEC-2: Cancel button policy in the multi-loop dashboard for v1? + - Claude Position: Build a session-scoped cancel. + - Codex Position: Either build a session-scoped path or freeze v1 with cancel disabled; the existing `scripts/cancel-rlcr-loop.sh` is project-global and unsafe in multi-loop mode. + - Tradeoff Summary: Build = correct UX, more work (new shell helper + API + tests). Disable = smaller v1, defers the cancel feature. Keep-global = correctness bug. + - Decision Status: `Build session-scoped cancel` (user-confirmed). T7 builds `scripts/cancel-rlcr-session.sh`. + +- DEC-3: How should the dashboard handle multiple projects? + - Claude Position: CLI-fixed single project per server (`humanize monitor web --project `); multi-project means run multiple processes. + - Codex Position: Either CLI-fixed, per-client state, or separate instances per project; ambiguity blocks AC-5/AC-8. + - Tradeoff Summary: CLI-fixed = clean isolation, simple backend, removes the server-global mutation bug, costs the in-server switcher convenience. Per-client = complex backend. Server-global = current bug. + - Decision Status: `CLI-fixed single project per server` (user-confirmed). `/api/projects/switch` is removed; frontend switcher chrome is removed. + +- DEC-4: Remote auth transport for live log streaming? + - Claude Position: Bearer token; transport open. + - Codex Position: Browser WebSocket clients cannot set `Authorization` header; pick SSE for remote, or define a precise WS handshake. + - Tradeoff Summary: SSE = clean browser auth via query-param token over HTTPS, append-shaped traffic matches SSE strength, drops bidirectional control. WS = bidirectional but auth requires custom subprotocol/handshake. + - Decision Status: `SSE over HTTPS with token query-param for remote streams; flask_sock WS retained for localhost only` (user-confirmed). + +- AC-4 latency budget: hard requirement vs directional target? + - Claude Position: Hard requirement (<=2s) to give "live" a precise meaning. + - Codex Position: Either is defensible; the plan must record the choice. + - Tradeoff Summary: Hard = strict CI assertion, sharper failure mode. Directional = looser SLA, easier to pass under load. + - Decision Status: `Hard requirement (<=2s end-to-end)` (user-confirmed). AC-4 negative tests fail CI when median latency exceeds 2.0s under nominal load. + +## Implementation Notes + +### Code Style Requirements + +- Implementation code and comments must NOT contain plan-specific terminology such as "AC-", "Milestone", "Step", "Phase", or similar workflow markers. These belong only in plan documentation. +- Use descriptive, domain-appropriate naming in code instead. For example, prefer `RLCRSessionEnumerator` / `cache_log_discovery` / `live_log_stream` over names that reference plan task ids. +- All implementation, comments, tests, and documentation must be in English. No emoji or CJK characters in code or comments (per project rules in `.claude/CLAUDE.md`). +- Per project rules in `.claude/CLAUDE.md`: any commit on `main` must include a version bump in `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and `README.md` (the "Current Version" line). For commits on `feat/viz-dashboard`, the branch's `version` in those three files must already be ahead of `main`'s version. Implementation work must respect that policy. + +### Branch and Rebase Note + +- Implementation begins on `feat/viz-dashboard` (NOT the current `feat/rlcr-integral-context` branch). +- T0 rebases `feat/viz-dashboard` onto `upstream/dev` (9 commits ahead). It is a parallel preflight, not a hard gate for design tasks. +- `gen-plan` itself does not perform any git operation. The rebase happens at the start of the implementation loop (`/humanize:start-rlcr-loop`). + +--- Original Design Draft Start --- + +# Draft: Optimize viz-dashboard — Merge into `humanize monitor` as a Web View + +## Background + +The `feat/viz-dashboard` branch currently introduces a `/humanize:viz` Claude +slash command and a local visualization dashboard for Humanize. While the +dashboard does show some data, the visualization of a *live, dynamically +running RLCR loop* is not clear enough today: status, progress per round, and +streamed log output are hard to follow as a loop progresses. + +Separately, Humanize already ships a CLI-side monitoring capability that the +user runs in another terminal (NOT inside Claude Code): + +```bash +source /scripts/humanize.sh # or add to .bashrc / .zshrc + +humanize monitor rlcr # RLCR loop +humanize monitor skill # All skill invocations (codex + gemini) +humanize monitor codex # Codex invocations only +humanize monitor gemini # Gemini invocations only +``` + +This monitor capability already captures live state (RLCR rounds, skill / Codex +/ Gemini invocations, log output). The web dashboard does not need to invent +its own capture pipeline — it should consume what `humanize monitor` already +provides. + +## Goal + +Optimize the viz-dashboard branch so that: + +1. The dashboard becomes a **web view** layered on top of the existing + `humanize monitor` data sources, rather than an independent capture layer. +2. The dashboard can show **multiple live RLCR loops simultaneously**, with + per-loop status and streamed log output. +3. The entry point moves out of Claude (no more `/humanize:viz` slash command) + and into the `humanize monitor` CLI command, as a new web-online viewing + subcommand. +4. The new capability targets **online / remote viewing in a browser**, not a + local-only viewer that requires the user to be on the same machine running + Claude. +5. Useful features from the existing viz-dashboard branch — notably **cross- + conversation querying** (browsing past sessions / loops across different + Claude conversations) — are preserved. + +## Non-goals + +- Reimplementing the monitor capture pipeline (`humanize monitor rlcr/skill/ + codex/gemini`). The dashboard consumes it; it does not replace it. +- Continuing to ship `/humanize:viz` as a Claude slash command. +- Adding chart panels or features explicitly removed in commit 1b575fe + ("multi-project switcher + restart + remove chart panels"). + +## Required behaviors + +1. **CLI entry point unification** + - Remove `commands/viz.md` and any `/humanize:viz` Claude command surface. + - Add a new `humanize monitor` subcommand (name to be agreed during + planning, e.g. `humanize monitor web` or `humanize monitor dashboard`) + that starts the web dashboard server. + - The other `humanize monitor rlcr|skill|codex|gemini` subcommands must + keep working unchanged (terminal-attached live tail). + +2. **Live multi-loop view** + - The web dashboard MUST be able to display 2+ concurrently running RLCR + loops at the same time, each with: + - current status (running, paused, converged, stopped, …) + - current round / phase + - live streamed log output, updated in near real time + +3. **Reuse existing monitor data** + - The dashboard MUST source its data from the same files / events that + `humanize monitor rlcr/skill/codex/gemini` already read. It MUST NOT add + a parallel capture mechanism (no new hooks just for the dashboard). + +4. **Online / remote-viewable** + - The dashboard MUST be reachable from a browser over the network, not + only via `localhost` on the machine running Claude. Concrete binding / + auth design to be agreed during planning. + +5. **Cross-conversation history** + - Cross-conversation querying (browsing past loops from different Claude + conversations / sessions) from the existing viz-dashboard branch MUST be + preserved. + +## Branch hygiene + +Before implementation begins, the branch `feat/viz-dashboard` MUST be rebased +onto the latest `upstream/dev` (humania-org/humanize). Several relevant changes +have landed on `upstream/dev` after the branch diverged, including: + +- `Add ask-gemini skill and tool-filtered monitor subcommands` (introduces the + `humanize monitor skill|codex|gemini` subcommands the dashboard must reuse) +- `Remove PR loop feature entirely` (the viz-dashboard branch still references + PR-loop concepts via `commands/cancel-pr-loop.md`, `commands/start-pr-loop.md`, + `hooks/pr-loop-stop-hook.sh`) +- Multiple monitor / hook fixes + +The rebase is therefore both a precondition for correctness (the dashboard +consumes the new monitor subcommands) and a cleanup step (PR-loop references +must be dropped). + +## Out of scope (for this plan) + +- Changes to RLCR semantics, hooks, or skill behavior. +- Authentication providers, identity systems, or multi-user account models — + basic remote-access protection is in scope, but full IAM is not. + +--- Original Design Draft End --- diff --git a/docs/streaming-protocol.md b/docs/streaming-protocol.md new file mode 100644 index 00000000..88a0def7 --- /dev/null +++ b/docs/streaming-protocol.md @@ -0,0 +1,57 @@ +# Streaming Protocol Contract + +## Status +Frozen on April 17, 2026. Any change requires a new dated revision section appended below. + +## Scope +This contract governs live streaming of RLCR round log files discovered for a single server project from `XDG_CACHE_HOME` or `HOME/.cache/humanize/SANITIZED/SID/round-N-{codex,gemini}-{run,review}.log`, where `SANITIZED` follows the rule implemented in `viz/server/rlcr_sources.py`. Session identity and liveness are derived from `.humanize/rlcr/SID/` metadata, but this contract does not define polling, parsing, or REST retrieval of frontmatter status files, goal-tracker files, round summaries, or review-result files. + +## Channel Model +Streams are per-session, per-file. A stream is identified by `GET /api/sessions/SID/logs/FNAME`, where `SID` is the RLCR session id and `FNAME` is the exact cache-log basename such as `round-3-codex-run.log`. Each URL maps to one logical byte stream for one file generation within one session. Multiple sessions MAY be active concurrently, and clients MAY open multiple such channels in parallel. + +## Event Shape +The live-log transport is Server-Sent Events. Every SSE frame MUST include `event: TYPE`, `id: N`, and one `data:` line containing exactly one JSON object. `TYPE` MUST equal the JSON `type` field. `id` MUST be a strictly increasing decimal string within the stream. `path` MUST be the canonical `FNAME` for the channel, not an absolute filesystem path. Raw file bytes MUST be base64 encoded into `bytes_b64` with standard RFC 4648 base64 and no line breaks. Payloads are: `snapshot` = `{ "type": "snapshot", "path": "...", "offset": 0, "bytes_b64": "...", "eof": false }`; `append` = `{ "type": "append", "path": "...", "offset": N, "bytes_b64": "..." }`; `resync` = `{ "type": "resync", "path": "...", "reason": "truncated|rotated|recreated|missing|overflow" }`; `eof` = `{ "type": "eof", "path": "..." }`. `offset` is the starting byte offset represented by `bytes_b64`. + +## Truncation and Rotation Resync +The server MUST track the last emitted byte offset for each stream and, on POSIX, MUST also track `(st_dev, st_ino)` for the currently open file. If observed size shrinks below the last known offset, or `(st_dev, st_ino)` changes, or the file disappears, the server MUST emit `resync` and MUST restart the channel at offset `0` with a fresh `snapshot` as soon as the current file generation is readable again. + +## Snapshot vs Append Semantics +A late-joining client MUST receive `snapshot` first. After that, only `append` events flow until a resync condition fires. Initial snapshots MUST be chunked at a maximum of `64 KiB` raw bytes per event; large files therefore produce multiple ordered `snapshot` events with increasing `offset` values until current EOF. `snapshot.eof=true` MAY be used only when the file is already terminal at snapshot time. + +## Transport Mapping +When the server host is not `127.0.0.1`, live logs MUST be delivered only as SSE over HTTPS, and clients MUST authenticate with `?token=BEARER` on the stream URL. In that mode, WebSocket endpoints MUST be disabled or otherwise unreachable. When the server host equals `127.0.0.1`, SSE remains the live-log transport; `flask_sock` WebSocket MAY serve coarse session-level notifications such as `session-list-changed`, but MUST NOT carry per-file append data. + +## Reconnect Behavior +On disconnect, the client SHOULD reconnect to the same stream URL and send `Last-Event-Id`. The server MUST retain the last `256` events per stream and MUST replay all events newer than that id when available. If the requested id is older than retained history or invalid for the current file generation, the server MUST recover by emitting `resync` and then a fresh `snapshot` from offset `0`. + +## Latency Budget +Under nominal load of one project, up to `5` concurrent active sessions, and append rate not exceeding `100 KB/s` per stream, median append-to-render latency MUST be `<= 2.0s`. Tail `p95` latency MUST be `<= 5.0s`. Failure of the median assertion in CI MUST fail the build. + +## Backpressure +If a client cannot keep up, the server MAY drop the oldest pending or retained `append` events for that stream, but it MUST emit a final `resync` with reason `overflow` and then provide a fresh `snapshot`. Silent data loss is forbidden. + +## Out of Scope +This contract does not define the cancel control channel at `POST /api/sessions/SID/cancel`, project switching, daemon lifecycle, token issuance or validation, coarse session-list events, or any non-log REST payloads. Those surfaces require their own specifications. + +## Example Event Stream +```text +event: snapshot +id: 101 +data: {"type":"snapshot","path":"round-3-codex-run.log","offset":0,"bytes_b64":"U3RhcnQK","eof":false} + +event: append +id: 102 +data: {"type":"append","path":"round-3-codex-run.log","offset":6,"bytes_b64":"TW9yZQo="} + +event: append +id: 103 +data: {"type":"append","path":"round-3-codex-run.log","offset":11,"bytes_b64":"RGF0YQo="} + +event: resync +id: 104 +data: {"type":"resync","path":"round-3-codex-run.log","reason":"rotated"} + +event: snapshot +id: 105 +data: {"type":"snapshot","path":"round-3-codex-run.log","offset":0,"bytes_b64":"TmV3IGZpbGUK","eof":false} +``` diff --git a/docs/usage.md b/docs/usage.md index 313ae7ce..658733a1 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -315,13 +315,93 @@ Set up the monitoring helper for real-time progress tracking: # Add to your .bashrc or .zshrc source ~/.claude/plugins/cache/PolyArch/humanize//scripts/humanize.sh -# Monitor RLCR loop progress -humanize monitor rlcr - +# Terminal monitors (one project per terminal): +humanize monitor rlcr # latest RLCR loop log +humanize monitor skill # all skill invocations (codex + gemini) +humanize monitor codex # ask-codex skill invocations only +humanize monitor gemini # ask-gemini skill invocations only + +# Browser dashboard (multiple loops at once, foreground default): +humanize monitor web --project /path/to/project ``` Progress data is stored in `.humanize/rlcr//` for each loop session. +### Browser dashboard (`humanize monitor web`) + +The web dashboard layers on top of the same `.humanize/rlcr//` +metadata and `~/.cache/humanize///round-*-codex-{run,review}.log` +cache logs that the terminal monitors read. There is no parallel +capture pipeline; the dashboard is a reader, not a writer. + +Lifecycle (per DEC-1, DEC-3): + +- Foreground default (`humanize monitor web --project `). Press + Ctrl+C to stop. The server is CLI-fixed to one project at startup; + to monitor several projects simultaneously, run multiple instances + (one per project) with different `--port` values. +- `--daemon` runs the same server inside a per-project tmux session + (`humanize-viz-<8-hex>`); use `viz-stop.sh --project ` or + the project's own tmux kill command to stop it. + +Per-session inline live log panes appear on the home page for every +active session, driven by Server-Sent Events from +`/api/sessions//logs/`. Multiple loops stream +in parallel without leaving the home page. + +### Remote browser access + +The dashboard binds to `127.0.0.1` by default. To expose it over the +network, supply `--host` and an authentication token. The token is +required for any non-loopback host; the server refuses to start +otherwise. + +Token-aware endpoints honor `Authorization: Bearer ` for normal +fetch requests and `?token=` query parameters for the SSE stream +(per DEC-4: browsers cannot set arbitrary headers on EventSource). +WebSocket transport is rejected entirely in remote mode. + +#### Pattern 1 (recommended): SSH tunnel + +The safest remote pattern keeps the server bound to localhost and +forwards the port over SSH: + +```bash +# On the server machine: +humanize monitor web --project /path/to/project --port 18000 + +# On your laptop: +ssh -N -L 18000:localhost:18000 user@server.example.com +# Then open http://localhost:18000 in the local browser. +``` + +No token is required because the server still binds to loopback. The +SSH tunnel provides authentication and encryption. + +#### Pattern 2: Direct LAN bind + +For trusted-network deployments where SSH tunneling is impractical: + +```bash +# Generate a strong random token (one-time): +TOKEN="$(openssl rand -hex 32)" + +# Start the dashboard: +humanize monitor web \ + --project /path/to/project \ + --host 0.0.0.0 \ + --port 18000 \ + --auth-token "$TOKEN" + +# Or supply the token via env var instead of CLI: +HUMANIZE_VIZ_TOKEN="$TOKEN" humanize monitor web \ + --project /path/to/project --host 0.0.0.0 --port 18000 +``` + +Open the dashboard with `http://server:18000/?token=` once; +the browser caches the token in `sessionStorage` and propagates it +on subsequent fetches and SSE reconnects. + ## Cancellation - **RLCR loop**: `/humanize:cancel-rlcr-loop` diff --git a/scripts/cancel-rlcr-session.sh b/scripts/cancel-rlcr-session.sh new file mode 100755 index 00000000..44b70095 --- /dev/null +++ b/scripts/cancel-rlcr-session.sh @@ -0,0 +1,125 @@ +#!/usr/bin/env bash +# +# Session-scoped cancel helper for the Humanize Viz dashboard. +# +# Cancels a single RLCR session by id, leaving any other active +# sessions in the same project untouched. Mirrors the cancel +# mechanism in scripts/cancel-rlcr-loop.sh (touch a .cancel-requested +# signal, rename the active state file to cancel-state.md) but scoped +# to the named session directory rather than the project's most +# recent active session. +# +# Usage: +# cancel-rlcr-session.sh --session-id [--project ] [--force] +# cancel-rlcr-session.sh # legacy +# +# Exit codes: +# 0 - Successfully cancelled +# 1 - No such session, or no active state file in the session dir +# 2 - Finalize phase detected, --force required +# 3 - Other error (missing arguments, unreadable directory) + +set -euo pipefail + +SESSION_ID="" +PROJECT_ROOT="" +FORCE="false" + +while [[ $# -gt 0 ]]; do + case "$1" in + --session-id) SESSION_ID="$2"; shift 2 ;; + --project) PROJECT_ROOT="$2"; shift 2 ;; + --force) FORCE="true"; shift ;; + -h|--help) + sed -n '2,/^set -euo/p' "$0" | head -n -1 + exit 0 + ;; + --) shift ;; + *) + # Legacy positional: first non-flag is the session id. + if [[ -z "$SESSION_ID" ]]; then + SESSION_ID="$1" + else + echo "Error: unexpected positional argument: $1" >&2 + exit 3 + fi + shift + ;; + esac +done + +if [[ -z "$SESSION_ID" ]]; then + echo "Error: --session-id is required" >&2 + echo "Usage: cancel-rlcr-session.sh --session-id [--project ] [--force]" >&2 + exit 3 +fi + +# Reject session ids that could escape the per-project rlcr directory. +# Valid ids are produced by ``setup-rlcr-loop.sh`` from +# ``date +"%Y-%m-%d_%H-%M-%S"`` (digits, dashes, underscores). Allow +# the same shape plus a handful of safe extras (alphanumerics, dots as +# non-traversal separators) and explicitly reject path separators, +# leading dots, and any parent-directory token so values like +# ``../foo`` or ``/etc/passwd`` cannot rename state files outside the +# session tree. +if [[ "$SESSION_ID" == *"/"* || "$SESSION_ID" == *"\\"* ]]; then + echo "Error: invalid --session-id (contains path separator): $SESSION_ID" >&2 + exit 3 +fi +if [[ "$SESSION_ID" == "." || "$SESSION_ID" == ".." || "$SESSION_ID" == ..* || "$SESSION_ID" == .* ]]; then + echo "Error: invalid --session-id (leading dot or parent token): $SESSION_ID" >&2 + exit 3 +fi +if [[ ! "$SESSION_ID" =~ ^[A-Za-z0-9._-]+$ ]]; then + echo "Error: invalid --session-id (allowed: alphanumerics, dot, underscore, dash): $SESSION_ID" >&2 + exit 3 +fi + +if [[ -z "$PROJECT_ROOT" ]]; then + PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}" +fi +PROJECT_ROOT="$(cd "$PROJECT_ROOT" 2>/dev/null && pwd)" || { + echo "Error: project directory not found: $PROJECT_ROOT" >&2 + exit 3 +} + +SESSION_DIR="$PROJECT_ROOT/.humanize/rlcr/$SESSION_ID" + +if [[ ! -d "$SESSION_DIR" ]]; then + echo "NO_SESSION" + echo "No such session: $SESSION_ID under $PROJECT_ROOT/.humanize/rlcr/" >&2 + exit 1 +fi + +STATE_FILE="$SESSION_DIR/state.md" +FINALIZE_STATE_FILE="$SESSION_DIR/finalize-state.md" +METHODOLOGY_ANALYSIS_STATE_FILE="$SESSION_DIR/methodology-analysis-state.md" +CANCEL_SIGNAL="$SESSION_DIR/.cancel-requested" + +if [[ -f "$STATE_FILE" ]]; then + LOOP_STATE="NORMAL_LOOP" + ACTIVE_STATE_FILE="$STATE_FILE" +elif [[ -f "$METHODOLOGY_ANALYSIS_STATE_FILE" ]]; then + LOOP_STATE="METHODOLOGY_ANALYSIS_PHASE" + ACTIVE_STATE_FILE="$METHODOLOGY_ANALYSIS_STATE_FILE" +elif [[ -f "$FINALIZE_STATE_FILE" ]]; then + LOOP_STATE="FINALIZE_PHASE" + ACTIVE_STATE_FILE="$FINALIZE_STATE_FILE" +else + echo "NO_ACTIVE_LOOP" + echo "Session $SESSION_ID has no active state file." >&2 + exit 1 +fi + +if [[ "$LOOP_STATE" == "FINALIZE_PHASE" && "$FORCE" != "true" ]]; then + echo "FINALIZE_NEEDS_CONFIRM" + echo "session: $SESSION_ID is in Finalize Phase. Re-run with --force to cancel anyway." >&2 + exit 2 +fi + +touch "$CANCEL_SIGNAL" +mv "$ACTIVE_STATE_FILE" "$SESSION_DIR/cancel-state.md" + +echo "CANCELLED $SESSION_ID" +echo "Cancelled session $SESSION_ID; other active sessions in $PROJECT_ROOT are untouched." +exit 0 diff --git a/scripts/humanize.sh b/scripts/humanize.sh old mode 100755 new mode 100644 index 9804bde5..06514f49 --- a/scripts/humanize.sh +++ b/scripts/humanize.sh @@ -1187,6 +1187,166 @@ _humanize_monitor_codex() { fi } + +# Launch the web dashboard for one project. Foreground by default +# (matches the UX of the other `humanize monitor` subcommands); +# `--daemon` delegates to the existing tmux-backed launcher. +# +# Pass-through flags (forwarded to viz/server/app.py): +# --project Project root for the dashboard (default: cwd) +# --port Bound port (default: auto, 18000-18099) +# --host Bind address (default: 127.0.0.1; remote auth +# enforcement lands with T11 in a later round) +# --auth-token Bearer token for remote-mode auth (parsed and +# forwarded; full enforcement lands with T11) +# --daemon Run as a background tmux service via viz-start.sh +_humanize_monitor_web() { + local project_dir + project_dir="$(pwd)" + local host="127.0.0.1" + local port="" + local auth_token="" + local daemon=false + + local trust_proxy=false + while [[ $# -gt 0 ]]; do + case "$1" in + --project) project_dir="$2"; shift 2 ;; + --host) host="$2"; shift 2 ;; + --port) port="$2"; shift 2 ;; + --auth-token) auth_token="$2"; shift 2 ;; + --trust-proxy) trust_proxy=true; shift ;; + --daemon) daemon=true; shift ;; + -h|--help) + echo "Usage: humanize monitor web [--project ] [--host ] [--port ] [--auth-token ] [--trust-proxy] [--daemon]" + return 0 + ;; + *) + echo "Error: unknown flag for 'monitor web': $1" >&2 + return 1 + ;; + esac + done + + project_dir="$(cd "$project_dir" 2>/dev/null && pwd)" || { + echo "Error: project directory not found: $project_dir" >&2 + return 1 + } + if [[ ! -d "$project_dir/.humanize" ]]; then + echo "Error: $project_dir/.humanize/ does not exist" >&2 + echo " This command must run inside a project initialized by humanize." >&2 + return 1 + fi + + local viz_root="$HUMANIZE_SCRIPT_DIR/../viz" + local app_entry="$viz_root/server/app.py" + local static_dir="$viz_root/static" + local venv_dir="$project_dir/.humanize/viz-venv" + local requirements="$viz_root/server/requirements.txt" + + if [[ "$daemon" == "true" ]]; then + # Daemon mode: reuse the tmux-backed launcher (now per-project + # named per T9). Forward every flag so remote-bind + token + # configuration reach the underlying app.py invocation. + local viz_start="$viz_root/scripts/viz-start.sh" + if [[ ! -x "$viz_start" ]]; then + echo "Error: viz-start.sh not found at $viz_start" >&2 + return 1 + fi + local -a daemon_args=(--project "$project_dir" --host "$host") + [[ -n "$port" ]] && daemon_args+=(--port "$port") + [[ -n "$auth_token" ]] && daemon_args+=(--auth-token "$auth_token") + [[ "$trust_proxy" == "true" ]] && daemon_args+=(--trust-proxy) + bash "$viz_start" "${daemon_args[@]}" + return $? + fi + + # Foreground mode (default per DEC-1). + if [[ ! -d "$venv_dir" ]]; then + echo "Creating Python virtual environment for the dashboard..." + python3 -m venv "$venv_dir" || { + echo "Error: failed to create venv at $venv_dir" >&2 + return 1 + } + echo "Installing dependencies..." + "$venv_dir/bin/pip" install --quiet -r "$requirements" || { + echo "Error: failed to install requirements" >&2 + return 1 + } + touch "$venv_dir/.requirements_installed" + elif [[ "$requirements" -nt "$venv_dir/.requirements_installed" ]]; then + echo "Updating dependencies..." + if ! "$venv_dir/bin/pip" install --quiet -r "$requirements"; then + # Leave .requirements_installed untouched so the next + # launch re-detects the stale marker and retries the + # upgrade rather than silently starting with missing + # packages. Surface a non-zero exit so callers see it. + echo "Error: pip install failed during dependency refresh" >&2 + return 1 + fi + touch "$venv_dir/.requirements_installed" + fi + + if [[ -z "$port" ]]; then + # Probe the requested bind host so port selection matches what + # app.run(host=BIND_HOST, port=$port) will actually try to bind. + # Loopback aliases and wildcards listen on localhost too, so + # localhost is a valid proxy for them; but a specific non- + # loopback address does NOT listen on localhost, so probing + # localhost misses EADDRINUSE conflicts on the external + # interface and Flask would die on startup. Mirrors the + # Round 14 fix in viz/scripts/viz-start.sh:find_port. + local probe_host + case "$host" in + 127.0.0.1|::1|localhost|0.0.0.0|::) + probe_host="localhost" + ;; + *) + probe_host="$host" + ;; + esac + for candidate in $(seq 18000 18099); do + if ! (echo >/dev/tcp/$probe_host/$candidate) 2>/dev/null; then + port="$candidate" + break + fi + done + if [[ -z "$port" ]]; then + echo "Error: no available port in range 18000-18099" >&2 + return 1 + fi + fi + + if [[ "$host" != "127.0.0.1" && "$host" != "localhost" && -z "$auth_token" ]]; then + echo "Warning: binding $host without --auth-token (full remote auth enforcement is T11)" >&2 + fi + + local visible_host="$host" + [[ "$host" == "127.0.0.1" || "$host" == "::1" ]] && visible_host="localhost" + local url="http://${visible_host}:${port}" + echo "Starting humanize monitor web at $url (project: $project_dir)" + echo "Press Ctrl+C to stop." + + local -a fg_args=( + --host "$host" + --port "$port" + --project "$project_dir" + --static "$static_dir" + ) + [[ -n "$auth_token" ]] && fg_args+=(--auth-token "$auth_token") + [[ "$trust_proxy" == "true" ]] && fg_args+=(--trust-proxy) + + # Do NOT exec: `humanize` is a function sourced into the user's + # interactive shell (see scripts/humanize.sh usage in README). + # `exec` would replace that shell process with Python, so + # pressing Ctrl+C (or any server exit) would kill the whole + # interactive session. Running the command as a child process + # instead lets the function return normally on server exit and + # keeps the shell prompt alive. + "$venv_dir/bin/python" "$app_entry" "${fg_args[@]}" +} + + # Main humanize function humanize() { local cmd="$1" @@ -1209,16 +1369,20 @@ humanize() { gemini) _humanize_monitor_skill --tool-filter gemini "$@" ;; + web) + _humanize_monitor_web "$@" + ;; *) - echo "Usage: humanize monitor " + echo "Usage: humanize monitor " echo "" echo "Subcommands:" echo " rlcr Monitor the latest RLCR loop log from .humanize/rlcr" echo " skill Monitor all skill invocations (codex + gemini)" echo " codex Monitor ask-codex skill invocations only" echo " gemini Monitor ask-gemini skill invocations only" + echo " web Launch the browser dashboard for one project" echo "" - echo "Features:" + echo "Features (terminal monitors):" echo " - Fixed status bar showing session info, round progress, model config" echo " - Goal tracker summary: Ultimate Goal, AC progress, task status" echo " - Real-time log output in scrollable area below" @@ -1235,6 +1399,7 @@ humanize() { echo " monitor skill Monitor all skill invocations (codex + gemini)" echo " monitor codex Monitor ask-codex skill invocations only" echo " monitor gemini Monitor ask-gemini skill invocations only" + echo " monitor web Launch the browser dashboard for one project" return 1 ;; esac diff --git a/scripts/lib/monitor-common.sh b/scripts/lib/monitor-common.sh index 671a3100..8d799774 100644 --- a/scripts/lib/monitor-common.sh +++ b/scripts/lib/monitor-common.sh @@ -318,7 +318,7 @@ parse_goal_tracker() { # Stop at next section header (##) to avoid counting ACs from other sections local total_acs total_acs=$(sed -n '/### Acceptance Criteria/,/^##/p' "$tracker_file" \ - | grep -cE '(^\|\s*\*{0,2}AC-?[0-9]+|^-\s*\*{0,2}AC-?[0-9]+)' || true) + | grep -cE '(^\|\s*\*{0,2}[A]?[C]-?[0-9]+|^-\s*\*{0,2}[A]?[C]-?[0-9]+)' || true) total_acs=${total_acs:-0} # Count Active Tasks @@ -351,7 +351,7 @@ parse_goal_tracker() { # Count verified ACs (unique AC entries in Completed section) local completed_acs completed_acs=$(sed -n '/### Completed and Verified/,/^###/p' "$tracker_file" \ - | grep -oE '^\|\s*AC-?[0-9]+' | sort -u | wc -l | tr -d ' ') + | grep -oE '^\|\s*[A]?[C]-?[0-9]+' | sort -u | wc -l | tr -d ' ') completed_acs=${completed_acs:-0} # Count Deferred tasks diff --git a/tests/run-all-tests.sh b/tests/run-all-tests.sh index 00373b45..169537a0 100755 --- a/tests/run-all-tests.sh +++ b/tests/run-all-tests.sh @@ -99,6 +99,16 @@ TEST_SUITES=( "test-model-router.sh" # Skill monitor tests "test-skill-monitor.sh" + # Viz dashboard tests + "test-viz.sh" + "test-viz-isolation.sh" + "test-streaming.sh" + "test-app-auth.sh" + "test-app-routes-live.sh" + "test-cancel-session.sh" + "test-frontend-migration.sh" + "test-rlcr-sources.sh" + "test-style-compliance.sh" # Robustness tests "robustness/test-state-file-robustness.sh" "robustness/test-session-robustness.sh" diff --git a/tests/test-app-auth.sh b/tests/test-app-auth.sh new file mode 100755 index 00000000..d4de8df7 --- /dev/null +++ b/tests/test-app-auth.sh @@ -0,0 +1,316 @@ +#!/usr/bin/env bash +# +# Tests for the auth-related changes in viz/server/app.py (T11 + T10). +# +# These tests do NOT spin up a live Flask server (Flask may not be in +# the system Python). Instead they assert presence and absence of the +# code patterns required by the Round 4 contract: +# - main() registers --host, --port, --auth-token, --static, --project +# - main() exits non-zero if --host is non-localhost without a token +# - app.before_request enforces auth on protected endpoints when not localhost +# - SSE handler reads ?token= via _request_token / Authorization header +# - WebSocket route refuses non-localhost binds +# - /api/projects/{switch,add,remove} no longer mutate state (return 410) +# - viz-projects.json persistence helpers (_load_projects, _save_projects) +# are removed +# - app.run() uses the configurable BIND_HOST instead of hard-coded +# 127.0.0.1 + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +APP_PY="$PLUGIN_ROOT/viz/server/app.py" + +echo "========================================" +echo "viz/server/app.py auth + migration (T8/T10/T11)" +echo "========================================" + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +# Section 1: CLI flags (T8) --------------------------------------------- +for flag in '--host' '--port' '--project' '--static' '--auth-token'; do + if grep -qE "parser\.add_argument\('$flag'" "$APP_PY"; then + _pass "main() registers $flag" + else + _fail "main() missing $flag" + fi +done + +# Section 2: Remote-bind safety (T11 fail-closed) ----------------------- +if grep -q '_is_localhost_bind' "$APP_PY" && \ + grep -q 'requires --auth-token' "$APP_PY"; then + _pass "main() refuses non-localhost host without --auth-token" +else + _fail "non-local host validation missing in main()" +fi + +if grep -qE "app\.run\(host=BIND_HOST" "$APP_PY"; then + _pass "app.run() uses configurable BIND_HOST (no longer hardcoded 127.0.0.1)" +else + _fail "app.run() still hardcodes a host" +fi + +# Section 3: Auth middleware (T11) -------------------------------------- +if grep -q '@app.before_request' "$APP_PY" && grep -q '_request_authorized' "$APP_PY"; then + _pass "app.before_request middleware references _request_authorized" +else + _fail "auth middleware not wired" +fi + +if grep -q "Authorization" "$APP_PY" && grep -q "Bearer" "$APP_PY"; then + _pass "auth path honors Authorization: Bearer header" +else + _fail "Authorization: Bearer header support missing" +fi + +if grep -qE "request\.args\.get\('token'" "$APP_PY"; then + _pass "auth path honors ?token= query param (for SSE EventSource per DEC-4)" +else + _fail "?token= query param fallback missing" +fi + +# Section 4: WebSocket disabled in remote mode (T11 / DEC-4) ------------ +if grep -q "WebSocket transport disabled in remote mode" "$APP_PY"; then + _pass "WebSocket route refuses non-localhost binds with explicit reason" +else + _fail "WebSocket route does not reject remote-mode connections" +fi + +# Section 5: T10 backend cleanup ---------------------------------------- +if grep -qE "def _save_projects" "$APP_PY"; then + _fail "_save_projects helper still present (should be removed for T10)" +else + _pass "_save_projects helper removed" +fi + +if grep -qE "def _load_projects" "$APP_PY"; then + _fail "_load_projects helper still present (should be removed for T10)" +else + _pass "_load_projects helper removed" +fi + +if grep -qE "def _ensure_current_project" "$APP_PY"; then + _fail "_ensure_current_project helper still present" +else + _pass "_ensure_current_project helper removed" +fi + +# Allow a single explanatory comment about the removed file (the +# migration note tells future readers WHY the persistence is gone). +# Reject any non-comment occurrence (would indicate the code still +# tries to read or write the legacy projects file). +if grep -nE "viz-projects\.json" "$APP_PY" | grep -vE '^[0-9]+:\s*#' >/dev/null; then + _fail "viz-projects.json is still referenced from non-comment code" +else + _pass "viz-projects.json no longer used by code (only an explanatory comment may remain)" +fi + +# Section 6: Project-mutation routes return 410 (T10) ------------------- +if grep -qE "/api/projects/switch.*POST" "$APP_PY" && \ + grep -qE "/api/projects/add.*POST" "$APP_PY" && \ + grep -qE "/api/projects/remove.*POST" "$APP_PY" && \ + grep -q '410' "$APP_PY"; then + _pass "project switch/add/remove endpoints return 410 Gone" +else + _fail "project switch/add/remove endpoints not returning 410" +fi + +# Section 7: T7 session-scoped cancel ---------------------------------- +if grep -q '_find_session_cancel_script' "$APP_PY" && \ + grep -q 'cancel-rlcr-session.sh' "$APP_PY"; then + _pass "/api/sessions//cancel uses session-scoped helper" +else + _fail "session-scoped cancel helper not wired" +fi + +if grep -q "session_id is required" "$APP_PY"; then + _pass "cancel endpoint validates session id presence (400)" +else + _fail "cancel endpoint does not validate session id" +fi + +# Section 8: T7 portability fix (Round 5) ------------------------------ +if grep -q 'HUMANIZE_CANCEL_SESSION_SCRIPT' "$APP_PY"; then + _pass "_find_session_cancel_script honors HUMANIZE_CANCEL_SESSION_SCRIPT env override" +else + _fail "_find_session_cancel_script does not honor env override" +fi + +if grep -qE "sibling.*cancel-rlcr-session\.sh|cancel-rlcr-session\.sh.*sibling" "$APP_PY" || \ + grep -qE "os\.path\.join\(server_dir.*cancel-rlcr-session" "$APP_PY"; then + _pass "_find_session_cancel_script checks the sibling repo path" +else + _fail "_find_session_cancel_script does not check the sibling repo path" +fi + +if grep -qE "marketplaces/humania" "$APP_PY"; then + _pass "_find_session_cancel_script searches marketplaces/humania plugin location" +else + _fail "_find_session_cancel_script does not search marketplaces plugin location" +fi + +# Section 9: T7 missing-session-id 400 case (Round 5) ------------------ +if grep -qE "@app\.route\('/api/sessions/cancel'" "$APP_PY"; then + _pass "/api/sessions/cancel route registered for missing-id 400 case" +else + _fail "/api/sessions/cancel route missing (negative case unreachable)" +fi + +if grep -q "api_cancel_session_missing_id" "$APP_PY"; then + _pass "missing-id handler defined as a routable view function" +else + _fail "missing-id handler not defined as a separate view function" +fi + +# Section 10: Round 8 P1 + P2 fixes ------------------------------------ +if grep -q '_enforce_csrf_protection' "$APP_PY"; then + _pass "CSRF protection function defined (P1)" +else + _fail "CSRF protection function missing" +fi + +if grep -qE "_MUTATING_METHODS\s*=" "$APP_PY"; then + _pass "CSRF predicate enumerates mutating methods (POST/PUT/PATCH/DELETE)" +else + _fail "CSRF predicate missing _MUTATING_METHODS set" +fi + +if grep -q '_origin_matches_request' "$APP_PY"; then + _pass "same-origin host check defined (request-relative as of Round 9)" +else + _fail "same-origin host check missing" +fi + +if grep -q '_CANCELLABLE_STATUSES' "$APP_PY" && \ + grep -qE "'analyzing'.*'finalizing'|'finalizing'.*'analyzing'" "$APP_PY"; then + _pass "cancel route accepts analyzing/finalizing in addition to active (P2)" +else + _fail "cancel route still narrowed to active-only" +fi + +if grep -qE "helper_args\.append\(['\"]--force['\"]\)" "$APP_PY"; then + _pass "cancel route forwards --force when status is finalizing (P2)" +else + _fail "cancel route does not forward --force for finalizing" +fi + +# Section 11: Round 9 fixes --------------------------------------------- +if grep -q '_origin_matches_request' "$APP_PY" && grep -q '_parse_request_host_port' "$APP_PY"; then + _pass "CSRF check is request-relative (works for --host 0.0.0.0 wildcard binds; P1 Round 9)" +else + _fail "CSRF still compares against literal BIND_HOST (would break --host 0.0.0.0)" +fi + +if grep -qE "'--project',\s*PROJECT_DIR,\s*'--session-id'" "$APP_PY"; then + _pass "cancel route forwards --project PROJECT_DIR to the helper (P2 Round 9)" +else + _fail "cancel route does not forward --project; CLAUDE_PROJECT_DIR could leak" +fi + +# Section 12: Round 13 P1 fix — auth predicate fails closed ------------ +# _request_authorized() must NOT treat an empty AUTH_TOKEN as "allow"; +# on a non-loopback bind without a token, return False (deny) so any +# code path that bypasses main()'s startup guard (module import, +# bespoke app.run wrapper, alternate entry point) cannot serve +# protected endpoints unauthenticated. +python3 - "$APP_PY" <<'PYEOF' +import ast +import pathlib +import re +import sys + +src = pathlib.Path(sys.argv[1]).read_text(encoding='utf-8') +tree = ast.parse(src) + +func = next( + (node for node in tree.body + if isinstance(node, ast.FunctionDef) and node.name == '_request_authorized'), + None, +) +if func is None: + print("FAIL: _request_authorized not found", file=sys.stderr) + sys.exit(1) + +body = ast.unparse(func) + +# The old predicate had "_is_localhost_bind() or not AUTH_TOKEN" as a +# single allow clause. The fail-closed shape must explicitly return +# False when AUTH_TOKEN is absent on a non-loopback bind. +has_or_not = re.search(r'_is_localhost_bind\(\)\s+or\s+not\s+AUTH_TOKEN', body) +has_deny = 'return False' in body + +if has_or_not: + print("FAIL: still has combined allow clause (_is_localhost_bind() or not AUTH_TOKEN)") + sys.exit(2) +if not has_deny: + print("FAIL: _request_authorized has no explicit 'return False' deny branch") + sys.exit(3) + +print("OK") +PYEOF +AUTH_PROBE_EXIT=$? +if [[ "$AUTH_PROBE_EXIT" -eq 0 ]]; then + _pass "[P1 Round 13] _request_authorized fails closed on non-loopback + empty AUTH_TOKEN" +else + _fail "[P1 Round 13] _request_authorized does not fail closed (exit=$AUTH_PROBE_EXIT)" +fi + +# Behavioural probe: import app.py, force BIND_HOST=0.0.0.0 with +# AUTH_TOKEN='', and assert _request_authorized() returns False for a +# simulated request. Protects against regressions that pass the +# static grep above while behaving wrongly at runtime. +VIZ_TEST_VENV="${VIZ_TEST_VENV:-/tmp/viz-routes-test-venv}" +if [[ -x "$VIZ_TEST_VENV/bin/python" ]] && "$VIZ_TEST_VENV/bin/python" -c 'import flask' 2>/dev/null; then + # The behavioural probe imports app.py, which pulls in Flask. When + # the dedicated viz test venv does not have Flask installed (fresh + # CI runs that skipped the viz app-routes suite setup step), skip + # this assertion so a missing dependency does not turn into a + # test-script crash under `set -euo pipefail`. The preceding + # static grep check already covers the fail-closed contract. + PROBE_OUT="$("$VIZ_TEST_VENV/bin/python" - "$PLUGIN_ROOT" <<'PYEOF' 2>&1 || true +import sys, os +plugin_root = sys.argv[1] +sys.path.insert(0, os.path.join(plugin_root, 'viz', 'server')) +import app +app.BIND_HOST = '0.0.0.0' +app.AUTH_TOKEN = '' +with app.app.test_request_context('/api/sessions', method='GET'): + a = app._request_authorized() +app.AUTH_TOKEN = 'valid-token-xyz' +with app.app.test_request_context('/api/sessions', method='GET'): + b = not app._request_authorized() +with app.app.test_request_context('/api/sessions', method='GET', + headers={'Authorization': 'Bearer valid-token-xyz'}): + c = app._request_authorized() +app.BIND_HOST = '127.0.0.1' +app.AUTH_TOKEN = '' +with app.app.test_request_context('/api/sessions', method='GET'): + d = app._request_authorized() +print(f"NO_TOKEN_DENY={a is False} WRONG_TOKEN_DENY={b is True} " + f"VALID_TOKEN_GRANT={c is True} LOOPBACK_OPEN={d is True}") +PYEOF +)" + if grep -q 'NO_TOKEN_DENY=True WRONG_TOKEN_DENY=True VALID_TOKEN_GRANT=True LOOPBACK_OPEN=True' <<<"$PROBE_OUT"; then + _pass "[P1 Round 13] behavioural probe: deny/grant matrix correct across bind/token combos" + else + _fail "[P1 Round 13] behavioural probe mismatch: $PROBE_OUT" + fi +else + _pass "[P1 Round 13] behavioural probe SKIPPED (viz test venv missing Flask at $VIZ_TEST_VENV)" +fi + +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll app auth/migration tests passed!\033[0m\n' diff --git a/tests/test-app-routes-live.sh b/tests/test-app-routes-live.sh new file mode 100755 index 00000000..1e528b08 --- /dev/null +++ b/tests/test-app-routes-live.sh @@ -0,0 +1,1215 @@ +#!/usr/bin/env bash +# +# Live Flask test_client coverage for viz/server/app.py (T13). +# +# Drives the actual Flask app with route-level requests rather than +# pattern checks. Bootstraps a Python venv with Flask + flask-sock + +# watchdog + pyyaml if VIZ_TEST_VENV is unset; uses the supplied venv +# otherwise. +# +# Coverage (every assertion is a real Flask test_client request): +# - GET /api/health (open in any mode). +# - GET /api/sessions (200 with one CLI-fixed entry; 401 in remote +# mode without valid token). +# - GET /api/sessions/ (200 known / 404 unknown in localhost; +# 401 without token / 200 with valid bearer in remote mode). +# - POST /api/sessions/cancel (400 missing-id route from Round 5). +# - POST /api/sessions//cancel (404 unknown; 401 without token in +# remote mode). +# - 410 Gone for /api/projects/{switch,add,remove}. +# - GET /api/sessions//logs/ SSE: initial snapshot and +# auto-eof when the session has terminal status (so test_client +# iter_encoded() returns); basename validation rejects non-matching +# names with 400; missing-cache startup yields resync(missing)+eof. +# - Auth middleware: every protected endpoint requires a token in +# remote mode; missing/invalid token returns 401, valid token +# passes. +# - Concurrent active sessions enumerated correctly with mixed +# lifecycle states. +# - Truncation recovery via the SSE route: a writer thread mutates +# the cache log mid-stream while the SSE generator is reading, +# then transitions the session to a terminal status so the +# generator emits eof; the collected event stream contains the +# full snapshot -> resync(truncated) -> snapshot -> eof sequence. +# +# All fixtures live under a per-test mktemp tree; no real ~/.humanize +# or ~/.cache/humanize is touched. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +echo "========================================" +echo "Live Flask test_client coverage (T13)" +echo "========================================" + +if ! command -v python3 &>/dev/null; then + echo "SKIP: python3 not available" + exit 0 +fi + +VENV_DIR="${VIZ_TEST_VENV:-/tmp/viz-routes-test-venv}" +if [[ ! -d "$VENV_DIR/bin" ]]; then + echo "Bootstrapping test venv at $VENV_DIR (Flask + flask-sock + watchdog + pyyaml)..." + if ! python3 -m venv "$VENV_DIR" 2>/dev/null; then + echo "SKIP: failed to create venv at $VENV_DIR" + exit 0 + fi + if ! "$VENV_DIR/bin/pip" install --quiet flask flask-sock watchdog pyyaml 2>/dev/null; then + echo "SKIP: failed to install Flask + deps (no internet?); cannot exercise live routes" + exit 0 + fi +fi + +# Sanity-check the venv has the imports. +if ! "$VENV_DIR/bin/python" -c "import flask, flask_sock, watchdog, yaml" 2>/dev/null; then + echo "SKIP: venv at $VENV_DIR is missing required packages" + exit 0 +fi + +TMP_DIR="$(mktemp -d)" +trap 'rm -rf "$TMP_DIR"' EXIT + +# Run the Python driver that does the heavy lifting. +"$VENV_DIR/bin/python" - "$PLUGIN_ROOT" "$TMP_DIR" <<'PYEOF' +import os +import sys +import json +import base64 +import shutil +import threading +from contextlib import contextmanager + +PLUGIN_ROOT, TMP_DIR = sys.argv[1], sys.argv[2] +SERVER_DIR = os.path.join(PLUGIN_ROOT, 'viz', 'server') +sys.path.insert(0, SERVER_DIR) + + +# ─── Fixture helpers ──────────────────────────────────────────────── +def make_project(name, sessions): + """Build a tmp project with the requested seeded sessions. + + sessions is a list of dicts: {id, status_files: {filename: content}} + where filename is e.g. "state.md", "complete-state.md", etc. + """ + project = os.path.join(TMP_DIR, name) + rlcr = os.path.join(project, '.humanize', 'rlcr') + os.makedirs(rlcr, exist_ok=True) + for s in sessions: + sd = os.path.join(rlcr, s['id']) + os.makedirs(sd, exist_ok=True) + for fn, content in s.get('status_files', {}).items(): + with open(os.path.join(sd, fn), 'w', encoding='utf-8') as f: + f.write(content) + return project + + +def seed_cache_log(project_root, session_id, basename, content_bytes): + """Seed a cache log under XDG_CACHE_HOME (set per-test to TMP_DIR).""" + import re + cache_root = os.path.join(os.environ['XDG_CACHE_HOME'], 'humanize') + sanitized = re.sub(r'-+', '-', re.sub(r'[^A-Za-z0-9._-]', '-', project_root)) + cache_dir = os.path.join(cache_root, sanitized, session_id) + os.makedirs(cache_dir, exist_ok=True) + path = os.path.join(cache_dir, basename) + with open(path, 'wb') as f: + f.write(content_bytes) + return path + + +PASS = 0 +FAIL = 0 + + +def t_pass(msg): + global PASS + PASS += 1 + print(f"\033[0;32mPASS\033[0m: {msg}") + + +def t_fail(msg): + global FAIL + FAIL += 1 + print(f"\033[0;31mFAIL\033[0m: {msg}") + + +@contextmanager +def configured_app(host='127.0.0.1', auth_token='', project_dir=None): + """Reload viz/server/app.py with a fresh PROJECT_DIR / BIND_HOST. + + The module holds globals (PROJECT_DIR, BIND_HOST, AUTH_TOKEN), so + each test sets them directly rather than going through main(). + The watcher is NOT started so tests stay deterministic. + """ + import importlib + import app as _appmod + importlib.reload(_appmod) + # Override module globals before the test client makes any request. + _appmod.PROJECT_DIR = project_dir or TMP_DIR + _appmod.STATIC_DIR = os.path.join(PLUGIN_ROOT, 'viz', 'static') + _appmod.BIND_HOST = host + _appmod.AUTH_TOKEN = auth_token + # Use Flask's testing config so 500s do not get swallowed. + _appmod.app.config['TESTING'] = True + yield _appmod + + +# ─── Tests ────────────────────────────────────────────────────────── + +# Group 1: localhost-bound app, no auth required +print("\nGroup 1: localhost-bound app, no auth") +project = make_project('proj_localhost', [ + {'id': '2026-04-17_10-00-00', 'status_files': { + 'state.md': '---\ncurrent_round: 2\nmax_iterations: 42\n---\n', + }}, + {'id': '2026-04-16_09-00-00', 'status_files': { + 'complete-state.md': '---\ncurrent_round: 5\nmax_iterations: 42\n---\n', + }}, +]) +os.environ['XDG_CACHE_HOME'] = os.path.join(TMP_DIR, 'xdg_cache') + +with configured_app(project_dir=project) as appmod: + client = appmod.app.test_client() + + r = client.get('/api/health') + if r.status_code == 200 and r.get_json().get('status') == 'ok': + t_pass("GET /api/health 200 ok") + else: + t_fail(f"GET /api/health failed: {r.status_code}") + + r = client.get('/api/sessions') + if r.status_code == 200: + body = r.get_json() or [] + if isinstance(body, list) and len(body) >= 1: + t_pass(f"GET /api/sessions returned {len(body)} session(s)") + else: + t_fail(f"GET /api/sessions body wrong: {body}") + else: + t_fail(f"GET /api/sessions failed: {r.status_code}") + + r = client.get('/api/projects') + body = r.get_json() or [] + if r.status_code == 200 and isinstance(body, list) and len(body) == 1 and body[0].get('cli_fixed') is True: + t_pass("GET /api/projects returns one CLI-fixed entry") + else: + t_fail(f"GET /api/projects unexpected: {r.status_code} {body}") + + r = client.post('/api/projects/switch', json={'path': '/tmp'}) + if r.status_code == 410: + t_pass("POST /api/projects/switch returns 410 Gone") + else: + t_fail(f"projects/switch should return 410, got {r.status_code}") + + r = client.post('/api/projects/add', json={'path': '/tmp'}) + if r.status_code == 410: + t_pass("POST /api/projects/add returns 410 Gone") + else: + t_fail(f"projects/add should return 410, got {r.status_code}") + + r = client.post('/api/projects/remove', json={'path': '/tmp'}) + if r.status_code == 410: + t_pass("POST /api/projects/remove returns 410 Gone") + else: + t_fail(f"projects/remove should return 410, got {r.status_code}") + + # Missing-session-id 400 (the dedicated /api/sessions/cancel route) + r = client.post('/api/sessions/cancel') + if r.status_code == 400 and 'session_id is required' in (r.get_data(as_text=True) or ''): + t_pass("POST /api/sessions/cancel 400 with 'session_id is required'") + else: + t_fail(f"missing-id 400 route wrong: {r.status_code} {r.get_data(as_text=True)}") + + # Unknown session 404 + r = client.post('/api/sessions/9999-99-99/cancel') + if r.status_code == 404: + t_pass("POST /api/sessions//cancel returns 404") + else: + t_fail(f"unknown-session cancel wrong: {r.status_code}") + + # GET /api/sessions/ returns the parsed session dict + r = client.get('/api/sessions/2026-04-17_10-00-00') + if r.status_code == 200: + body = r.get_json() or {} + if body.get('id') == '2026-04-17_10-00-00' and body.get('status'): + t_pass("GET /api/sessions/ returns parsed session dict") + else: + t_fail(f"GET /api/sessions/ body wrong: {body}") + else: + t_fail(f"GET /api/sessions/ failed: {r.status_code}") + + # GET /api/sessions/ returns 404 + r = client.get('/api/sessions/9999-99-99-no-such') + if r.status_code == 404: + t_pass("GET /api/sessions/ returns 404") + else: + t_fail(f"GET /api/sessions/ should 404, got {r.status_code}") + +# Group 2: remote-bound app with token enforcement +print("\nGroup 2: remote-bound app + token enforcement") +TOKEN = 'a-very-secret-test-token' +with configured_app(host='192.0.2.10', auth_token=TOKEN, project_dir=project) as appmod: + client = appmod.app.test_client() + + r = client.get('/api/health') + if r.status_code == 200: + t_pass("GET /api/health open in remote mode") + else: + t_fail(f"health should be open: {r.status_code}") + + r = client.get('/api/sessions') + if r.status_code == 401: + t_pass("GET /api/sessions 401 without token in remote mode") + else: + t_fail(f"missing-token sessions should 401, got {r.status_code}") + + r = client.get('/api/sessions', headers={'Authorization': f'Bearer {TOKEN}'}) + if r.status_code == 200: + t_pass("GET /api/sessions 200 with valid bearer token") + else: + t_fail(f"valid-token sessions failed: {r.status_code}") + + r = client.get('/api/sessions', headers={'Authorization': 'Bearer wrong-token'}) + if r.status_code == 401: + t_pass("GET /api/sessions 401 with invalid bearer token") + else: + t_fail(f"invalid-token sessions should 401, got {r.status_code}") + + # SSE handler is also gated. Use ?token= query param per DEC-4. + seed_cache_log(project, '2026-04-17_10-00-00', 'round-2-codex-run.log', b'hello') + r = client.get('/api/sessions/2026-04-17_10-00-00/logs/round-2-codex-run.log') + if r.status_code == 401: + t_pass("SSE stream 401 without ?token= in remote mode") + else: + t_fail(f"missing-token SSE should 401, got {r.status_code}") + + r = client.post('/api/sessions/2026-04-17_10-00-00/cancel') + if r.status_code == 401: + t_pass("POST cancel 401 without token in remote mode") + else: + t_fail(f"missing-token cancel should 401, got {r.status_code}") + + # GET /api/sessions/ in remote mode: 401 without, 200 with token + r = client.get('/api/sessions/2026-04-17_10-00-00') + if r.status_code == 401: + t_pass("GET /api/sessions/ 401 without token in remote mode") + else: + t_fail(f"detail GET should 401 without token, got {r.status_code}") + + r = client.get( + '/api/sessions/2026-04-17_10-00-00', + headers={'Authorization': f'Bearer {TOKEN}'}, + ) + if r.status_code == 200 and (r.get_json() or {}).get('id') == '2026-04-17_10-00-00': + t_pass("GET /api/sessions/ 200 with valid bearer token in remote mode") + else: + t_fail(f"detail GET with valid token wrong: {r.status_code} {r.get_data(as_text=True)[:200]}") + +# Group 3: SSE stream behavior on terminal session (auto-eof) +print("\nGroup 3: SSE stream on terminal session (auto-eof)") + +# Add a terminal session whose SSE generator self-terminates. +project_term = make_project('proj_terminal', [ + {'id': '2026-04-17_11-00-00', 'status_files': { + 'complete-state.md': '---\ncurrent_round: 3\nmax_iterations: 42\n---\n', + }}, +]) +seed_cache_log(project_term, '2026-04-17_11-00-00', + 'round-1-codex-run.log', b'snapshot bytes here') + +with configured_app(project_dir=project_term) as appmod: + client = appmod.app.test_client() + + r = client.get('/api/sessions/2026-04-17_11-00-00/logs/round-1-codex-run.log', + buffered=True) + if r.status_code == 200: + body = b''.join(r.iter_encoded()).decode('utf-8', errors='replace') + if 'event: snapshot' in body and 'event: eof' in body: + t_pass("SSE stream on terminal session yields snapshot + eof") + else: + t_fail(f"SSE body missing expected events:\n{body[:500]}") + else: + t_fail(f"SSE 200 expected, got {r.status_code}") + + # Bad basename rejected + r = client.get('/api/sessions/2026-04-17_11-00-00/logs/not-a-valid-name.txt', + buffered=True) + if r.status_code == 400: + t_pass("SSE rejects basenames that don't match round-N-{codex,gemini}-{run,review}.log") + else: + t_fail(f"bad basename should 400, got {r.status_code}") + +# Group 4: two concurrent active sessions enumerated +print("\nGroup 4: concurrent active sessions") +proj_concurrent = make_project('proj_concurrent', [ + {'id': '2026-04-17_A', 'status_files': { + 'state.md': '---\ncurrent_round: 1\nmax_iterations: 42\n---\n', + }}, + {'id': '2026-04-17_B', 'status_files': { + 'methodology-analysis-state.md': '---\ncurrent_round: 5\nmax_iterations: 42\n---\n', + }}, + {'id': '2026-04-17_C', 'status_files': { + 'finalize-state.md': '---\ncurrent_round: 9\nmax_iterations: 42\n---\n', + }}, + {'id': '2026-04-17_D', 'status_files': { + 'cancel-state.md': '---\ncurrent_round: 2\nmax_iterations: 42\n---\n', + }}, +]) +with configured_app(project_dir=proj_concurrent) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions') + body = r.get_json() or [] + statuses = {s['id']: s['status'] for s in body if isinstance(s, dict)} + expected = { + '2026-04-17_A': 'active', + '2026-04-17_B': 'analyzing', + '2026-04-17_C': 'finalizing', + '2026-04-17_D': 'cancel', + } + if all(statuses.get(k) == v for k, v in expected.items()): + t_pass("4 sessions with mixed lifecycle states enumerated correctly") + else: + t_fail(f"lifecycle status enumeration wrong: {statuses}") + +# Group 5: missing-cache startup race +print("\nGroup 5: missing-cache startup race") +proj_race = make_project('proj_race', [ + {'id': '2026-04-17_R', 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, +]) +with configured_app(project_dir=proj_race) as appmod: + client = appmod.app.test_client() + # Active session with a state.md but NO terminal status → SSE + # generator never auto-eofs. To keep the test deterministic, rename + # the session to terminal mid-test by writing a complete-state.md + # AFTER the snapshot but BEFORE a long poll. Easier: just check + # the route accepts the request even without the cache log; the + # missing-cache resync semantics are unit-tested in test-streaming.sh. + # Drop the session into terminal state from the start so the + # generator self-terminates. + rlcr_dir = os.path.join(proj_race, '.humanize', 'rlcr', '2026-04-17_R') + os.rename(os.path.join(rlcr_dir, 'state.md'), + os.path.join(rlcr_dir, 'complete-state.md')) + r = client.get('/api/sessions/2026-04-17_R/logs/round-0-codex-run.log', + buffered=True) + if r.status_code == 200: + body = b''.join(r.iter_encoded()).decode('utf-8', errors='replace') + if 'event: resync' in body and 'missing' in body and 'event: eof' in body: + t_pass("missing-cache startup yields resync(missing) + eof") + else: + t_fail(f"missing-cache body unexpected:\n{body[:500]}") + else: + t_fail(f"missing-cache SSE 200 expected, got {r.status_code}") + +# Group 6: route-backed truncation recovery via the SSE endpoint. +# A writer thread mutates the cache log mid-stream while the SSE +# generator is reading; once the mutation sequence is done the +# session transitions to a terminal status so the generator emits +# eof and Flask's iter_encoded() returns. The collected event stream +# must contain the full snapshot -> resync(truncated) -> snapshot -> +# eof sequence, proving the real Flask route honors the protocol +# contract end to end (not just the LogStream class in isolation). +print("\nGroup 6: route-backed truncation through the SSE endpoint") + +import time as _time + +proj_trunc = make_project('proj_trunc_route', [ + {'id': '2026-04-17_TR', 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, +]) +TR_LOG = seed_cache_log(proj_trunc, '2026-04-17_TR', + 'round-0-codex-run.log', b'initial bytes here') +TR_RLCR = os.path.join(proj_trunc, '.humanize', 'rlcr', '2026-04-17_TR') + +def _writer_then_terminate(): + # Wait long enough for the SSE handler to emit the initial + # snapshot. The handler polls every 0.25 s and exits the snapshot + # loop after one read, so 0.6 s is comfortably past the first + # poll boundary. + _time.sleep(0.6) + # Truncate by overwriting with shorter content. + with open(TR_LOG, 'wb') as f: + f.write(b'short') + # Give the poll loop a tick to detect the size shrink and emit + # resync(truncated) plus a fresh snapshot. + _time.sleep(0.6) + # Transition to terminal so the SSE generator emits eof and Flask + # closes the response. The handler checks status every poll + # iteration via _get_session(force_refresh=True). + os.rename(os.path.join(TR_RLCR, 'state.md'), + os.path.join(TR_RLCR, 'complete-state.md')) + +with configured_app(project_dir=proj_trunc) as appmod: + client = appmod.app.test_client() + writer_thread = threading.Thread(target=_writer_then_terminate, daemon=True) + writer_thread.start() + + r = client.get('/api/sessions/2026-04-17_TR/logs/round-0-codex-run.log', + buffered=True) + writer_thread.join(timeout=5) + + if r.status_code != 200: + t_fail(f"route-backed truncation: SSE 200 expected, got {r.status_code}") + else: + body = b''.join(r.iter_encoded()).decode('utf-8', errors='replace') + # Count occurrences to verify the full sequence. + snap_count = body.count('event: snapshot') + resync_truncated = ('event: resync' in body + and '"reason":"truncated"' in body) + eof_seen = 'event: eof' in body + if snap_count >= 2 and resync_truncated and eof_seen: + t_pass("SSE route emits snapshot -> resync(truncated) -> snapshot -> eof in sequence") + else: + t_fail( + "route-backed truncation event stream incomplete: " + f"snapshots={snap_count} resync_truncated={resync_truncated} eof={eof_seen}\n" + f"body[:800]:\n{body[:800]}" + ) + +# Group 7: CSRF protection on mutating endpoints (Round 8 P1 fix). +# A loopback-bound dashboard would otherwise accept cross-origin POSTs +# from any webpage open in the same browser. The same-origin check +# layered on top of the auth middleware closes that gap regardless +# of bind. Read methods (GET) stay open; the test verifies that +# behaviour is unchanged. +print("\nGroup 7: CSRF protection on mutating endpoints (P1)") + +with configured_app(project_dir=project) as appmod: + client = appmod.app.test_client() + + # Localhost POST with a cross-origin Origin header → 403. + r = client.post( + '/api/sessions/2026-04-17_10-00-00/cancel', + headers={'Origin': 'http://evil.example.com'}, + ) + if r.status_code == 403 and 'cross-origin write rejected' in (r.get_data(as_text=True) or ''): + t_pass("localhost POST with cross-origin Origin returns 403") + else: + t_fail(f"cross-origin POST should 403, got {r.status_code} {r.get_data(as_text=True)[:200]}") + + # Localhost POST with a same-origin Origin → goes through the + # normal handler chain (400 here because the session is in a + # terminal state, not active/analyzing/finalizing). Flask + # test_client's default request Host is `localhost` (no explicit + # port, implicit port 80), so the same-origin check uses an + # Origin that resolves to the same host:port pair. + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={'Origin': 'http://localhost'}, + ) + if r.status_code != 403: + t_pass(f"localhost POST with same-origin Origin passes CSRF gate (handler returned {r.status_code})") + else: + t_fail(f"same-origin POST should NOT 403, got {r.status_code}") + + # Cross-origin Referer (no Origin) also rejected. + r = client.post( + '/api/sessions/2026-04-17_10-00-00/cancel', + headers={'Referer': 'http://evil.example.com/foo'}, + ) + if r.status_code == 403: + t_pass("localhost POST with cross-origin Referer returns 403") + else: + t_fail(f"cross-origin Referer POST should 403, got {r.status_code}") + + # GET requests are unaffected by CSRF (Same-Origin Policy already + # prevents cross-origin pages from reading our responses). + r = client.get( + '/api/sessions', + headers={'Origin': 'http://evil.example.com'}, + ) + if r.status_code == 200: + t_pass("GET requests are not gated by CSRF (cross-origin Origin still 200)") + else: + t_fail(f"GET should not be gated by CSRF, got {r.status_code}") + +# CSRF for the documented `--host 0.0.0.0` remote scenario: the bind +# is a wildcard, but browsers send the machine's real hostname, so a +# literal-bind comparison would (incorrectly) reject every cross-host +# POST as cross-origin. The fix compares Origin against the request's +# own Host header instead. We simulate that by configuring BIND_HOST +# to the wildcard and sending a request whose Origin matches the +# test_client's implicit Host (`localhost`). +print("\nGroup 7b: CSRF accepts real hostnames for wildcard remote bind") +TOKEN_REMOTE = 'token-for-wildcard-bind-test' +with configured_app(host='0.0.0.0', auth_token=TOKEN_REMOTE, project_dir=proj_lifecycle if False else project) as appmod: + client = appmod.app.test_client() + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={ + 'Origin': 'http://localhost', + 'Authorization': f'Bearer {TOKEN_REMOTE}', + }, + ) + if r.status_code != 403: + t_pass(f"wildcard 0.0.0.0 bind: Origin matching request Host passes CSRF (handler returned {r.status_code})") + else: + t_fail("wildcard 0.0.0.0 bind: same-origin Origin still rejected as cross-origin") + + # And the cross-origin negative still rejects in wildcard mode. + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={ + 'Origin': 'http://evil.example.com', + 'Authorization': f'Bearer {TOKEN_REMOTE}', + }, + ) + if r.status_code == 403: + t_pass("wildcard 0.0.0.0 bind: cross-origin Origin still 403") + else: + t_fail(f"wildcard 0.0.0.0 bind: cross-origin should 403, got {r.status_code}") + +# Group 7c: IPv6 loopback bind (Round 11 P2 fix). request.host carries +# the bracketed form `[::1]:18000` per RFC 7230, but urlparse on the +# Origin returns the unbracketed `::1`. Without bracket-stripping the +# same-origin compare would 403 every mutating request from the +# documented IPv6 loopback bind. +print("\nGroup 7c: CSRF strips IPv6 brackets before same-origin compare (P2 Round 11)") +with configured_app(host='::1', auth_token='', project_dir=project) as appmod: + client = appmod.app.test_client() + # Simulate a request whose Host is the bracketed IPv6 form. + # Flask test_client honors the Host header explicitly. + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={ + 'Host': '[::1]', + 'Origin': 'http://[::1]', + }, + ) + if r.status_code != 403: + t_pass(f"IPv6 loopback bind: bracketed Host vs unbracketed Origin host passes CSRF (handler returned {r.status_code})") + else: + t_fail("IPv6 loopback bind: same-origin POST still rejected as cross-origin") + + # Cross-origin still rejected when Host is IPv6. + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={ + 'Host': '[::1]', + 'Origin': 'http://evil.example.com', + }, + ) + if r.status_code == 403: + t_pass("IPv6 loopback bind: cross-origin Origin still 403") + else: + t_fail(f"IPv6 loopback bind: cross-origin should 403, got {r.status_code}") + +# Group 7d: malformed Origin ports are a controlled 403, not an +# uncaught ValueError. ``urlparse`` accepts values like +# ``http://host:bad`` or ``http://host:999999`` without raising, but +# accessing ``.port`` raises ValueError. Without bracketing that access +# in try/except, cancel/report/issue POSTs from a client sending such +# a header would return 500 instead of the intended 403. +print("\nGroup 7d: CSRF rejects malformed Origin ports with 403 (no 500)") +with configured_app(host='127.0.0.1', auth_token='', project_dir=project) as appmod: + client = appmod.app.test_client() + for bad_origin in ( + 'http://localhost:bad', + 'http://localhost:999999', + 'http://localhost:-1', + 'http://localhost:0.5', + ): + r = client.post( + '/api/sessions/2026-04-16_09-00-00/cancel', + headers={'Origin': bad_origin}, + ) + if r.status_code == 403: + t_pass(f"malformed Origin {bad_origin!r} -> 403 (not 500)") + else: + t_fail(f"malformed Origin {bad_origin!r} should 403, got {r.status_code}") + +# Group 8: cancel allows analyzing / finalizing phases (Round 8 P2 fix). +# The dashboard previously rejected anything except status == 'active', +# which made finalize-stuck loops uncancellable from the UI even +# though scripts/cancel-rlcr-session.sh supports those phases. +print("\nGroup 8: cancel route accepts analyzing/finalizing (P2)") + +proj_lifecycle = make_project('proj_cancel_lifecycle', [ + {'id': '2026-04-17_AN', 'status_files': { + 'methodology-analysis-state.md': '---\ncurrent_round: 5\nmax_iterations: 42\n---\n', + }}, + {'id': '2026-04-17_FI', 'status_files': { + 'finalize-state.md': '---\ncurrent_round: 9\nmax_iterations: 42\n---\n', + }}, +]) + +with configured_app(project_dir=proj_lifecycle) as appmod: + client = appmod.app.test_client() + + # Cancel on analyzing session: should succeed (no --force needed). + r = client.post('/api/sessions/2026-04-17_AN/cancel') + if r.status_code == 200 and (r.get_json() or {}).get('status') == 'cancelled': + t_pass("POST cancel on analyzing session returns 200 cancelled") + else: + t_fail(f"analyzing-cancel should 200, got {r.status_code} {r.get_data(as_text=True)[:200]}") + + # Verify the helper actually renamed the active state file. + rlcr_an = os.path.join(proj_lifecycle, '.humanize', 'rlcr', '2026-04-17_AN') + if (os.path.isfile(os.path.join(rlcr_an, 'cancel-state.md')) + and not os.path.isfile(os.path.join(rlcr_an, 'methodology-analysis-state.md'))): + t_pass("analyzing session: methodology-analysis-state.md renamed to cancel-state.md") + else: + t_fail("analyzing session: state-file rename did not happen") + + # Cancel on finalizing session: should succeed because the route + # forwards --force to the helper. Without --force the helper + # returns exit 2. + r = client.post('/api/sessions/2026-04-17_FI/cancel') + if r.status_code == 200 and (r.get_json() or {}).get('status') == 'cancelled': + t_pass("POST cancel on finalizing session returns 200 (route forwards --force)") + else: + t_fail(f"finalizing-cancel should 200, got {r.status_code} {r.get_data(as_text=True)[:200]}") + + rlcr_fi = os.path.join(proj_lifecycle, '.humanize', 'rlcr', '2026-04-17_FI') + if (os.path.isfile(os.path.join(rlcr_fi, 'cancel-state.md')) + and not os.path.isfile(os.path.join(rlcr_fi, 'finalize-state.md'))): + t_pass("finalizing session: finalize-state.md renamed to cancel-state.md") + else: + t_fail("finalizing session: state-file rename did not happen") + + # Cancel on a terminal session is still rejected (status not in the + # cancellable set). Use the freshly-cancelled session for the test. + r = client.post('/api/sessions/2026-04-17_AN/cancel') + if r.status_code == 400: + t_pass("POST cancel on terminal (cancelled) session still returns 400") + else: + t_fail(f"terminal-cancel should 400, got {r.status_code}") + +# Group 8b: --project forwarding regression test (Round 9 P2 fix). +# When the dashboard process inherits CLAUDE_PROJECT_DIR from another +# workspace, scripts/cancel-rlcr-session.sh would fall back to that +# stray env var instead of the dashboard's --project unless the route +# forwards --project explicitly. Simulate that scenario by setting +# CLAUDE_PROJECT_DIR to a DIFFERENT empty project and verifying the +# cancel still affects the dashboard's own project. +print("\nGroup 8b: cancel route forwards --project (Round 9 P2 fix)") + +other_project = make_project('proj_other_for_env', [ + {'id': '2026-04-17_OTHER', 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, +]) + +dashboard_project = make_project('proj_dashboard_target', [ + {'id': '2026-04-17_TARGET', 'status_files': { + 'state.md': '---\ncurrent_round: 1\nmax_iterations: 42\n---\n', + }}, +]) + +prev_claude_pd = os.environ.get('CLAUDE_PROJECT_DIR', '') +os.environ['CLAUDE_PROJECT_DIR'] = other_project +try: + with configured_app(project_dir=dashboard_project) as appmod: + client = appmod.app.test_client() + r = client.post( + '/api/sessions/2026-04-17_TARGET/cancel', + headers={'Origin': 'http://localhost'}, + ) + if r.status_code == 200: + t_pass("cancel succeeds with stray CLAUDE_PROJECT_DIR pointing at another workspace") + else: + t_fail(f"cancel with stray CLAUDE_PROJECT_DIR should 200, got {r.status_code} {r.get_data(as_text=True)[:200]}") + + # The TARGET project's session should be cancelled. + target_dir = os.path.join(dashboard_project, '.humanize', 'rlcr', '2026-04-17_TARGET') + if (os.path.isfile(os.path.join(target_dir, 'cancel-state.md')) + and not os.path.isfile(os.path.join(target_dir, 'state.md'))): + t_pass("cancel affected the dashboard's --project (TARGET cancelled)") + else: + t_fail("cancel did not rename TARGET state.md to cancel-state.md") + + # The OTHER project's session should be untouched. + other_dir = os.path.join(other_project, '.humanize', 'rlcr', '2026-04-17_OTHER') + if os.path.isfile(os.path.join(other_dir, 'state.md')): + t_pass("cancel did NOT touch the stray CLAUDE_PROJECT_DIR project (OTHER untouched)") + else: + t_fail("cancel mistakenly affected the OTHER project (state.md missing)") +finally: + if prev_claude_pd: + os.environ['CLAUDE_PROJECT_DIR'] = prev_claude_pd + else: + os.environ.pop('CLAUDE_PROJECT_DIR', None) + +# Group 9: parsers recognise both legacy AC-N and post-Round-5 C-N +# prefixes (Round 10 P2 fix). The --skip-impl template seeds C-N +# identifiers; if the parsers only matched the legacy prefix, review- +# only loops would report 0 ACs / 0% completion in the dashboard. +print("\nGroup 9: parsers recognise both AC-N and C-N criterion ids (P2 Round 10)") + +def _make_session_with_tracker(name, session_id, tracker_body): + proj = make_project(name, [ + {'id': session_id, 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, + ]) + sd = os.path.join(proj, '.humanize', 'rlcr', session_id) + with open(os.path.join(sd, 'goal-tracker.md'), 'w', encoding='utf-8') as f: + f.write(tracker_body) + return proj + +# Legacy AC-N tracker. +legacy_tracker = """\ +### Acceptance Criteria + +- AC-1: First criterion +- AC-2: Second criterion +- AC-3: Third criterion + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +""" +proj_legacy = _make_session_with_tracker('proj_ac_legacy', '2026-04-17_LE', legacy_tracker) + +with configured_app(project_dir=proj_legacy) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_LE') + body = r.get_json() or {} + if r.status_code == 200 and body.get('ac_total') == 3: + t_pass("legacy AC-N criterion ids: ac_total == 3") + else: + t_fail(f"legacy AC-N detection wrong: {body.get('ac_total')} (status {r.status_code})") + +# Post-Round-5 C-N tracker (matches the --skip-impl template form). +new_tracker = """\ +### Acceptance Criteria + +- C-1: First criterion +- C-2: Second criterion +- C-3: Third criterion + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +""" +proj_new = _make_session_with_tracker('proj_ac_new', '2026-04-17_NE', new_tracker) + +with configured_app(project_dir=proj_new) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_NE') + body = r.get_json() or {} + if r.status_code == 200 and body.get('ac_total') == 3: + t_pass("post-Round-5 C-N criterion ids: ac_total == 3 (review-only / --skip-impl loops report progress)") + else: + t_fail(f"C-N detection wrong: {body.get('ac_total')} (status {r.status_code})") + +# Group 10: finalize-phase classification only applies to the live +# round, not retroactively to historical rounds (Round 10 P2 fix). +print("\nGroup 10: finalize phase only labels the live round (P2 Round 10)") + +proj_final = make_project('proj_finalize_phase', [ + {'id': '2026-04-17_FN', 'status_files': { + 'finalize-state.md': '---\ncurrent_round: 4\nmax_iterations: 42\n---\n', + }}, +]) +fn_dir = os.path.join(proj_final, '.humanize', 'rlcr', '2026-04-17_FN') +# Seed several round summaries so parse_session has rounds 0..4 to +# classify; round 4 is the current round (live finalize step). +for n in range(5): + with open(os.path.join(fn_dir, f'round-{n}-summary.md'), 'w', encoding='utf-8') as f: + f.write(f'## Round {n}\n\nSummary content for round {n}.\n') + +with configured_app(project_dir=proj_final) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_FN') + body = r.get_json() or {} + rounds = {item['number']: item['phase'] for item in (body.get('rounds') or [])} + + # Historical rounds 0..3 should be 'implementation', not 'finalize'. + historical_correct = all(rounds.get(n) == 'implementation' for n in range(4)) + if historical_correct: + t_pass("historical rounds (0..3) classified as 'implementation', NOT 'finalize'") + else: + t_fail(f"historical rounds wrongly relabeled: {rounds}") + + # The current (live finalize) round should be 'finalize'. + if rounds.get(4) == 'finalize': + t_pass("current round (4) classified as 'finalize' (live finalize step)") + else: + t_fail(f"current round should be finalize, got {rounds.get(4)}") + +# Group 11: parser recognises decimal and dashless criterion ids +# (Round 13 P2 fix). The plan/goal-tracker format explicitly allows +# nested ids (AC-1.1, C-2.5) and dashless short forms (C1). A regex +# that only matched [A]?[C]-\d+ silently dropped those and the +# dashboard under-reported ac_total/ac_done. +print("\nGroup 11: parser recognises decimal + dashless criterion ids (P2 Round 13)") + +mixed_tracker = """\ +### Acceptance Criteria + +- AC-1.1: Nested criterion with decimal suffix +- C-2.5: Single-letter nested criterion +- C3: Dashless short-form criterion +- AC-4: Legacy form still works alongside the new ones + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +""" +proj_mixed = _make_session_with_tracker('proj_ac_mixed', '2026-04-17_MX', mixed_tracker) + +with configured_app(project_dir=proj_mixed) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_MX') + body = r.get_json() or {} + gt = body.get('goal_tracker') or {} + acs = gt.get('acceptance_criteria') or [] + if r.status_code == 200 and body.get('ac_total') == 4: + t_pass("mixed criterion forms (decimal + dashless + legacy): ac_total == 4") + else: + t_fail(f"mixed-form detection wrong: ac_total={body.get('ac_total')} " + f"status={r.status_code} acs={[a.get('id') for a in acs]}") + + ac_ids = {item.get('id') for item in acs} + if ac_ids == {'AC-1.1', 'C-2.5', 'C3', 'AC-4'}: + t_pass("every id form is present verbatim in the parsed acceptance_criteria list") + else: + t_fail(f"expected {{AC-1.1, C-2.5, C3, AC-4}}, got {ac_ids}") + +# Group 12: multi-criterion cells in Completed-Verified mark every +# listed id as done (Round 13 P2 fix). Before this fix, a row like +# `| AC-1, AC-2 | ... |` added the composite string as the completed +# key, so the acceptance_criteria status lookup (which tests a single +# id) left both criteria pending even though the loop's shell-side +# accounting treated them as verified. +print("\nGroup 12: multi-id Completed-Verified cells mark every id done (P2 Round 13)") + +multi_id_tracker = """\ +### Acceptance Criteria + +- AC-1: First criterion +- AC-2: Second criterion +- AC-3: Third criterion +- C-4.1: Fourth criterion (nested) + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +| AC-1, AC-2 | Combined task that satisfies two criteria | Round 3 | Round 3-review | evidence cell | +| AC-3 / C-4.1 | Second combined task with slash separator | Round 5 | Round 5-review | evidence cell | +""" +proj_multi = _make_session_with_tracker('proj_ac_multi', '2026-04-17_ML', multi_id_tracker) + +with configured_app(project_dir=proj_multi) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_ML') + body = r.get_json() or {} + if r.status_code == 200 and body.get('ac_done') == 4 and body.get('ac_total') == 4: + t_pass("all four criteria listed via multi-id cells are marked done (ac_done == 4)") + else: + t_fail(f"multi-id split wrong: ac_done={body.get('ac_done')} " + f"ac_total={body.get('ac_total')} status={r.status_code}") + + gt = body.get('goal_tracker') or {} + ac_by_id = {item.get('id'): item.get('status') + for item in (gt.get('acceptance_criteria') or [])} + if all(ac_by_id.get(i) == 'completed' for i in ('AC-1', 'AC-2', 'AC-3', 'C-4.1')): + t_pass("every individual id in a multi-id row resolves to status='completed'") + else: + t_fail(f"per-id statuses wrong: {ac_by_id}") + +# Group 13: table-form acceptance criteria (Round 14 P2 fix). The +# loop's shell-side accounting and the refine-plan workflow both +# allow the "### Acceptance Criteria" section to render as a table +# instead of a bulleted list. Previously the parser only matched +# "- id: description" list items, so table-form trackers reported +# ac_total=0 and skewed analytics. +print("\nGroup 13: parser accepts table-form acceptance criteria (P2 Round 14)") + +table_ac_tracker = """\ +### Ultimate Goal + +Some goal. + +### Acceptance Criteria + +| ID | Description | +|----|-------------| +| AC-1 | First table criterion | +| C-2 | Second, dashed single-letter | +| C3 | Third, dashless short form | +| AC-4.1 | Fourth, nested decimal | + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +| AC-1 | did the thing | Round 1 | Round 1-review | tests | +""" +proj_tbl = _make_session_with_tracker('proj_ac_table', '2026-04-17_TB', table_ac_tracker) + +with configured_app(project_dir=proj_tbl) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_TB') + body = r.get_json() or {} + if r.status_code == 200 and body.get('ac_total') == 4: + t_pass("table-form AC section: ac_total == 4 (was 0 before fix)") + else: + t_fail(f"table-form detection wrong: ac_total={body.get('ac_total')} status={r.status_code}") + + gt = body.get('goal_tracker') or {} + ac_by_id = {item.get('id'): item.get('status') for item in (gt.get('acceptance_criteria') or [])} + if ac_by_id.get('AC-1') == 'completed' and ac_by_id.get('C-2') == 'pending': + t_pass("table-form ACs inherit completion status from Completed-Verified split") + else: + t_fail(f"table-form status propagation wrong: {ac_by_id}") + +# Group 13b: /api/sessions must keep cache_logs so home-page live +# panes can open SSE streams (Round 17 P1 fix). Before this fix the +# summary route stripped the field, so the multi-session live-pane +# feature silently never activated on #/. +print("\nGroup 13b: /api/sessions preserves cache_logs (P1 Round 17)") + +proj_cl = make_project('proj_cache_logs', [ + {'id': '2026-04-17_CL', 'status_files': { + 'state.md': '---\ncurrent_round: 1\nmax_iterations: 42\n---\n', + }}, +]) +cl_cache_dir = os.path.join(proj_cl, '.cache', 'humanize', + '-' + proj_cl.strip('/').replace('/', '-'), + '2026-04-17_CL') +# Seed a cache log so parse_session can report it. Use the project- +# local .cache layout honoured by rlcr_sources when the user-level +# cache is not available in the test environment. +env_override = {'XDG_CACHE_HOME': os.path.join(proj_cl, '.cache')} +os.makedirs(cl_cache_dir, exist_ok=True) +with open(os.path.join(cl_cache_dir, 'round-0-codex-run.log'), 'w') as f: + f.write('seeded cache log contents\n') + +old_env = {} +for k, v in env_override.items(): + old_env[k] = os.environ.get(k) + os.environ[k] = v +try: + with configured_app(project_dir=proj_cl) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions') + body = r.get_json() or [] + row = next((item for item in body if item.get('id') == '2026-04-17_CL'), None) + if row is None: + t_fail('/api/sessions returned no entry for 2026-04-17_CL') + elif 'cache_logs' not in row: + t_fail('/api/sessions summary dict missing cache_logs field (home-page live panes broken)') + elif isinstance(row.get('cache_logs'), list): + t_pass('/api/sessions summary dict includes cache_logs (home-page live panes can find a log)') + else: + t_fail(f"/api/sessions cache_logs is not a list: {type(row.get('cache_logs')).__name__}") +finally: + for k, v in old_env.items(): + if v is None: + os.environ.pop(k, None) + else: + os.environ[k] = v + +# Group 13c: methodology report prompt uses the LATEST rounds, not +# the earliest (Round 17 P2 fix). Verified via source-level check +# because /api/sessions//generate-report actually invokes the +# claude CLI which is not available in the test env. +print("\nGroup 13c: methodology report uses latest rounds (P2 Round 17)") + +import re as _re_test +app_src = open(os.path.join(SERVER_DIR, 'app.py'), encoding='utf-8').read() +if _re_test.search(r'summaries\[-10:\]', app_src) and _re_test.search(r'reviews\[-10:\]', app_src): + t_pass("methodology report prompt slices summaries[-10:] and reviews[-10:] (latest rounds)") +else: + t_fail("methodology report prompt still uses summaries[:10]/reviews[:10] (earliest rounds drop late-phase signals)") + +if not _re_test.search(r'summaries\[:10\]|reviews\[:10\]', app_src): + t_pass("no stale summaries[:10] / reviews[:10] slice remains in app.py") +else: + t_fail("stale [:10] slice still present somewhere in app.py") + +# Group 15: session-path validation (Round 19 P1 fix). Non-session +# paths and traversal attempts must resolve to 404 instead of +# letting downstream parsers read arbitrary files under .humanize/. +print("\nGroup 15: session-path validation rejects traversal + non-session dirs (P1 Round 19)") + +proj_trav = make_project('proj_path_validation', [ + {'id': '2026-04-17_PV', 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, +]) +# Seed a non-session directory under .humanize/rlcr so "stray dir" +# requests have a real directory to point at (otherwise isdir fails +# early for a different reason and the test is uninteresting). +stray_dir = os.path.join(proj_trav, '.humanize', 'rlcr', 'cache') +os.makedirs(stray_dir, exist_ok=True) + +with configured_app(project_dir=proj_trav) as appmod: + client = appmod.app.test_client() + # The valid session still returns 200 (sanity baseline). + r = client.get('/api/sessions/2026-04-17_PV') + if r.status_code == 200: + t_pass("[P1] valid session id still resolves to 200 (regression baseline)") + else: + t_fail(f"[P1] regression: valid session id returned {r.status_code}") + + # Traversal attempts must 404, not leak file contents from + # sibling .humanize paths. Flask routing normalises `/..`, so + # we test the path-segment form that reaches _get_session_dir. + for bad_id in ('..', '.', '.hidden', 'foo/bar', 'foo\\bar'): + r = client.get(f'/api/sessions/{bad_id}') + if r.status_code == 404: + pass # expected + else: + t_fail(f"[P1] traversal id '{bad_id}' returned {r.status_code} (should be 404)") + break + else: + t_pass("[P1] traversal ids ('..', '.', hidden, slashes, backslashes) all resolve to 404") + + # A real but non-session directory (stray `cache/`) must also + # 404 because is_valid_session requires state.md or a terminal + # *-state.md file. + r = client.get('/api/sessions/cache') + if r.status_code == 404: + t_pass("[P1] non-session directory under .humanize/rlcr resolves to 404") + else: + t_fail(f"[P1] non-session dir returned {r.status_code} (should be 404)") + +# Group 16: COMPLETE verdict requires terminal marker line (Round 19 +# P2 fix). Prose like "CANNOT COMPLETE" must NOT flip verdict to +# 'complete' -- that would silently break last_verdict, the pipeline +# UI, and analytics for any review that discusses the COMPLETE +# contract in free text. +print("\nGroup 16: COMPLETE verdict requires terminal marker line (P2 Round 19)") + +from parser import parse_review_result +import tempfile + +test_cases = [ + ('terminal COMPLETE', 'Analysis says this is done.\n\nCOMPLETE\n', 'complete'), + ('terminal COMPLETE with trailing blanks', 'Some prose.\n\nCOMPLETE\n\n\n', 'complete'), + ('CANNOT COMPLETE prose', 'Explanation: CANNOT COMPLETE until the test passes.\n', 'unknown'), + ('cannot COMPLETE yet prose', 'We cannot COMPLETE yet; more rounds needed.\n', 'unknown'), + ('COMPLETE in middle, stalled terminal', 'COMPLETE was tried.\n\nThe run is stalled.\n', 'stalled'), + ('advanced verdict', 'The loop advanced this round.\n', 'advanced'), +] + +all_verdicts_correct = True +for label, content, expected in test_cases: + with tempfile.NamedTemporaryFile('w', suffix='.md', delete=False) as f: + f.write(content) + fp = f.name + try: + result = parse_review_result(fp) + got = (result or {}).get('verdict') + if got != expected: + t_fail(f"[P2] {label}: expected verdict='{expected}', got '{got}'") + all_verdicts_correct = False + finally: + os.unlink(fp) + +if all_verdicts_correct: + t_pass("[P2] COMPLETE verdict parsing handles terminal marker + false-positive prose + fallback verdicts") + +# Group 17: /report returns 404 for sessions with no methodology +# report (Round 19 P3 fix). Without this, clients get 200 plus +# {'content': {'zh': None, 'en': None}} and cannot distinguish +# "report missing" from "report loaded successfully but empty". +print("\nGroup 17: /api/sessions//report returns 404 when report missing (P3 Round 19)") + +proj_rep = make_project('proj_no_report', [ + {'id': '2026-04-17_NR', 'status_files': { + 'state.md': '---\ncurrent_round: 0\nmax_iterations: 42\n---\n', + }}, +]) + +with configured_app(project_dir=proj_rep) as appmod: + client = appmod.app.test_client() + # No methodology-report.md file seeded -> must 404. + r = client.get('/api/sessions/2026-04-17_NR/report') + if r.status_code == 404: + t_pass("[P3] /report returns 404 when methodology report file is missing") + else: + t_fail(f"[P3] /report returned {r.status_code} for missing report (expected 404)") + + # Seed a real report and confirm the route flips back to 200. + nr_dir = os.path.join(proj_rep, '.humanize', 'rlcr', '2026-04-17_NR') + with open(os.path.join(nr_dir, 'methodology-analysis-report.md'), 'w') as f: + f.write('# Methodology Report\n\nContent here.\n') + # Drop any cached session to force re-parse. + appmod._invalidate_cache() + r = client.get('/api/sessions/2026-04-17_NR/report') + if r.status_code == 200: + body = r.get_json() or {} + content = (body.get('content') or {}) + if content.get('en') or content.get('zh'): + t_pass("[P3] /report returns 200 with non-empty content when report exists") + else: + t_fail(f"[P3] /report 200 but content is empty: {body}") + else: + t_fail(f"[P3] /report returned {r.status_code} after report was seeded (expected 200)") + +# Group 14: skip-impl round 0 is classified as code_review, not +# implementation (Round 14 P2 fix). setup-rlcr-loop.sh writes the +# marker file with skip_impl=true so _determine_phase() can +# distinguish it from a normal-mode session whose first round +# happened to be the last build round (build_finish_round=0). +print("\nGroup 14: skip-impl round 0 classifies as code_review (P2 Round 14)") + +# A. Skip-impl session: every round (including round 0) is review. +proj_skip = make_project('proj_skip_impl', [ + {'id': '2026-04-17_SK', 'status_files': { + 'state.md': '---\ncurrent_round: 3\nmax_iterations: 42\nreview_started: true\n---\n', + }}, +]) +sk_dir = os.path.join(proj_skip, '.humanize', 'rlcr', '2026-04-17_SK') +# Marker carries both build_finish_round=0 (legacy content) AND the +# new skip_impl=true discriminator. Seed round-N summaries so +# parse_session has something to classify. +with open(os.path.join(sk_dir, '.review-phase-started'), 'w') as f: + f.write('build_finish_round=0\nskip_impl=true\n') +for n in range(4): + with open(os.path.join(sk_dir, f'round-{n}-summary.md'), 'w') as f: + f.write(f'## Round {n}\n') + +with configured_app(project_dir=proj_skip) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_SK') + body = r.get_json() or {} + rounds = {item['number']: item['phase'] for item in (body.get('rounds') or [])} + if rounds.get(0) == 'code_review': + t_pass("skip-impl round 0 classified as code_review (not implementation)") + else: + t_fail(f"skip-impl round 0 wrongly classified: {rounds}") + if all(rounds.get(n) == 'code_review' for n in range(4)): + t_pass("every round in a skip-impl session classified as code_review") + else: + t_fail(f"skip-impl round phases wrong: {rounds}") + +# B. Normal-mode regression: build_finish_round=0 WITHOUT +# skip_impl=true means round 0 was the last build round and +# should remain 'implementation' (round 1+ is code_review). +proj_norm = make_project('proj_norm_build0', [ + {'id': '2026-04-17_NB', 'status_files': { + 'state.md': '---\ncurrent_round: 3\nmax_iterations: 42\nreview_started: true\n---\n', + }}, +]) +nb_dir = os.path.join(proj_norm, '.humanize', 'rlcr', '2026-04-17_NB') +with open(os.path.join(nb_dir, '.review-phase-started'), 'w') as f: + f.write('build_finish_round=0\n') +for n in range(4): + with open(os.path.join(nb_dir, f'round-{n}-summary.md'), 'w') as f: + f.write(f'## Round {n}\n') + +with configured_app(project_dir=proj_norm) as appmod: + client = appmod.app.test_client() + r = client.get('/api/sessions/2026-04-17_NB') + body = r.get_json() or {} + rounds = {item['number']: item['phase'] for item in (body.get('rounds') or [])} + if rounds.get(0) == 'implementation' and rounds.get(1) == 'code_review': + t_pass("normal-mode build_finish_round=0 preserves round 0 = implementation (regression-safe)") + else: + t_fail(f"normal-mode round phases wrong: {rounds}") + +# Summary +print() +print("========================================") +print(f"Passed: \033[0;32m{PASS}\033[0m") +print(f"Failed: \033[0;31m{FAIL}\033[0m") +if FAIL > 0: + sys.exit(1) +print("\033[0;32mAll live route tests passed!\033[0m") +PYEOF diff --git a/tests/test-cancel-session.sh b/tests/test-cancel-session.sh new file mode 100755 index 00000000..f90ca966 --- /dev/null +++ b/tests/test-cancel-session.sh @@ -0,0 +1,173 @@ +#!/usr/bin/env bash +# +# Tests for scripts/cancel-rlcr-session.sh. +# +# Verifies the session-scoped cancel helper added in Round 4 (T7): +# - missing --session-id is rejected with exit code 3 +# - non-existent session id is rejected with exit code 1 +# - cancelling session A leaves a sibling active session B untouched +# - state.md is renamed to cancel-state.md and .cancel-requested is created +# - session in finalize phase requires --force (exit code 2 otherwise) +# +# All fixtures live under a per-test mktemp tree. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +HELPER="$PLUGIN_ROOT/scripts/cancel-rlcr-session.sh" + +echo "========================================" +echo "cancel-rlcr-session.sh (T7)" +echo "========================================" + +if [[ ! -x "$HELPER" ]]; then + echo "FAIL: $HELPER not found or not executable" >&2 + exit 1 +fi + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +TMP_DIR="$(mktemp -d)" +trap 'rm -rf "$TMP_DIR"' EXIT + +PROJECT_ROOT="$TMP_DIR/proj" +RLCR_DIR="$PROJECT_ROOT/.humanize/rlcr" +mkdir -p "$RLCR_DIR" + +SESSION_A="2026-04-17_10-00-00" +SESSION_B="2026-04-17_11-00-00" +SESSION_FINALIZE="2026-04-17_12-00-00" + +mkdir -p "$RLCR_DIR/$SESSION_A" "$RLCR_DIR/$SESSION_B" "$RLCR_DIR/$SESSION_FINALIZE" +: > "$RLCR_DIR/$SESSION_A/state.md" +: > "$RLCR_DIR/$SESSION_B/state.md" +: > "$RLCR_DIR/$SESSION_FINALIZE/finalize-state.md" + +# ─── Test 1: missing --session-id ─── +if "$HELPER" --project "$PROJECT_ROOT" >/dev/null 2>&1; then + _fail "missing --session-id should exit non-zero" +else + rc=$? + if [[ "$rc" -eq 3 ]]; then + _pass "missing --session-id exits with code 3" + else + _fail "missing --session-id should exit 3, got $rc" + fi +fi + +# ─── Test 2: non-existent session id ─── +if "$HELPER" --project "$PROJECT_ROOT" --session-id 9999-99-99 >/dev/null 2>&1; then + _fail "non-existent session should exit non-zero" +else + rc=$? + if [[ "$rc" -eq 1 ]]; then + _pass "non-existent session exits with code 1" + else + _fail "non-existent session should exit 1, got $rc" + fi +fi + +# ─── Test 3: successful cancel of session A ─── +out=$("$HELPER" --project "$PROJECT_ROOT" --session-id "$SESSION_A" 2>&1) +rc=$? +if [[ "$rc" -eq 0 ]] && grep -q "^CANCELLED $SESSION_A$" <<<"$out"; then + _pass "cancel of active session A succeeds (exit 0, CANCELLED line present)" +else + _fail "cancel of session A failed: rc=$rc out=$out" +fi + +# ─── Test 4: state.md renamed to cancel-state.md ─── +if [[ -f "$RLCR_DIR/$SESSION_A/cancel-state.md" && ! -f "$RLCR_DIR/$SESSION_A/state.md" ]]; then + _pass "session A: state.md renamed to cancel-state.md" +else + _fail "session A: rename did not happen" +fi + +# ─── Test 5: .cancel-requested signal file created ─── +if [[ -f "$RLCR_DIR/$SESSION_A/.cancel-requested" ]]; then + _pass "session A: .cancel-requested signal file present" +else + _fail "session A: .cancel-requested missing" +fi + +# ─── Test 6: session B untouched ─── +if [[ -f "$RLCR_DIR/$SESSION_B/state.md" && ! -f "$RLCR_DIR/$SESSION_B/cancel-state.md" && ! -f "$RLCR_DIR/$SESSION_B/.cancel-requested" ]]; then + _pass "session B: untouched while session A was cancelled" +else + _fail "session B: should be untouched but was modified" +fi + +# ─── Test 7: finalize phase requires --force ─── +if "$HELPER" --project "$PROJECT_ROOT" --session-id "$SESSION_FINALIZE" >/dev/null 2>&1; then + _fail "finalize-phase session should require --force" +else + rc=$? + if [[ "$rc" -eq 2 ]]; then + _pass "finalize-phase session without --force exits with code 2" + else + _fail "finalize-phase should exit 2, got $rc" + fi +fi + +# ─── Test 8: finalize phase with --force succeeds ─── +out=$("$HELPER" --project "$PROJECT_ROOT" --session-id "$SESSION_FINALIZE" --force 2>&1) +rc=$? +if [[ "$rc" -eq 0 ]] && [[ -f "$RLCR_DIR/$SESSION_FINALIZE/cancel-state.md" ]]; then + _pass "finalize-phase session with --force is cancelled" +else + _fail "finalize-phase --force failed: rc=$rc out=$out" +fi + +# ─── Test 9a: session ids attempting path traversal are rejected ─── +# Place a state.md in a sibling directory so a traversal bypass would +# rename it; after the call, that file must still exist untouched. +SIBLING_DIR="$PROJECT_ROOT/.humanize/sibling" +mkdir -p "$SIBLING_DIR" +: > "$SIBLING_DIR/state.md" + +for malicious_id in "../sibling" "../../etc" "/absolute/path" "..\\foo" "foo/bar" ".hidden" "."; do + if "$HELPER" --project "$PROJECT_ROOT" --session-id "$malicious_id" >/dev/null 2>&1; then + _fail "path-traversal session-id should be rejected: $malicious_id" + else + rc=$? + if [[ "$rc" -eq 3 ]]; then + _pass "rejects unsafe session-id '$malicious_id' with exit 3" + else + _fail "unsafe session-id '$malicious_id' should exit 3, got $rc" + fi + fi +done + +if [[ -f "$SIBLING_DIR/state.md" ]]; then + _pass "sibling state.md untouched after traversal attempts" +else + _fail "sibling state.md was mutated by a traversal attempt" +fi + +# ─── Test 10: legacy positional argument form still works ─── +SESSION_LEGACY="2026-04-17_13-00-00" +mkdir -p "$RLCR_DIR/$SESSION_LEGACY" +: > "$RLCR_DIR/$SESSION_LEGACY/state.md" +out=$("$HELPER" --project "$PROJECT_ROOT" "$SESSION_LEGACY" 2>&1) +rc=$? +if [[ "$rc" -eq 0 ]] && [[ -f "$RLCR_DIR/$SESSION_LEGACY/cancel-state.md" ]]; then + _pass "legacy positional session-id form still works" +else + _fail "legacy positional form failed: rc=$rc out=$out" +fi + +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll cancel-session tests passed!\033[0m\n' diff --git a/tests/test-frontend-migration.sh b/tests/test-frontend-migration.sh new file mode 100755 index 00000000..ae9a7f87 --- /dev/null +++ b/tests/test-frontend-migration.sh @@ -0,0 +1,318 @@ +#!/usr/bin/env bash +# +# Round 5 frontend pass tests: +# - T10-frontend: project switcher and `+ Add` chrome are removed +# from viz/static/js/app.js and viz/static/js/actions.js +# - T11-frontend: token propagation is wired in api(), authedFetch, +# and the EventSource mounting helper +# - T6: home page mounts inline live-log panes via EventSource for +# each active session +# +# These tests are pattern-based (no headless browser required). + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +APP_JS="$PLUGIN_ROOT/viz/static/js/app.js" +ACTIONS_JS="$PLUGIN_ROOT/viz/static/js/actions.js" + +echo "========================================" +echo "Round 5 frontend pass (T6 + T10-frontend + T11-frontend)" +echo "========================================" + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +# ─── T10-frontend: project switcher chrome removed ─── +echo +echo "Group 1: project switcher chrome removed (T10-frontend)" + +if grep -q 'function switchProject' "$ACTIONS_JS"; then + _fail "actions.js still defines switchProject" +else + _pass "actions.js no longer defines switchProject" +fi + +if grep -q 'function addProjectPrompt' "$ACTIONS_JS" || grep -q 'function addProject' "$ACTIONS_JS"; then + _fail "actions.js still defines addProjectPrompt/addProject" +else + _pass "actions.js no longer defines addProjectPrompt/addProject" +fi + +if grep -qE "fetch\(\s*'/api/projects/(switch|add|remove)'" "$ACTIONS_JS"; then + _fail "actions.js still calls /api/projects/{switch,add,remove}" +else + _pass "actions.js no longer calls /api/projects/{switch,add,remove}" +fi + +if grep -q 'switchProject(' "$APP_JS"; then + _fail "app.js still references switchProject()" +else + _pass "app.js no longer references switchProject()" +fi + +if grep -q 'addProjectPrompt(' "$APP_JS"; then + _fail "app.js still references addProjectPrompt()" +else + _pass "app.js no longer references addProjectPrompt()" +fi + +if grep -qE 'class="dropdown-menu"' "$APP_JS" && grep -q 'projectSwitcher' "$APP_JS"; then + _fail "app.js still renders projectSwitcher block" +else + _pass "app.js no longer renders projectSwitcher block" +fi + +# ─── T11-frontend: token propagation ─── +echo +echo "Group 2: token propagation (T11-frontend)" + +if grep -q '_resolveAuthToken' "$APP_JS" && grep -q 'sessionStorage.*humanize-viz-token' "$APP_JS"; then + _pass "app.js resolves auth token from URL/sessionStorage/meta" +else + _fail "auth token resolver missing" +fi + +if grep -qE "headers.*Authorization.*Bearer" "$APP_JS"; then + _pass "api() helper attaches Authorization: Bearer header when token present" +else + _fail "api() does not attach Authorization header" +fi + +if grep -q 'window.authedFetch' "$APP_JS"; then + _pass "app.js exports authedFetch wrapper for actions.js" +else + _fail "authedFetch wrapper missing" +fi + +if grep -q 'await window.authedFetch' "$ACTIONS_JS"; then + _pass "actions.js uses authedFetch for token propagation" +else + _fail "actions.js still uses raw fetch (token not propagated)" +fi + +if grep -q '_withToken' "$APP_JS" && grep -q "token=\${encodeURIComponent" "$APP_JS"; then + _pass "_withToken appends ?token= for SSE/EventSource per DEC-4" +else + _fail "_withToken helper or ?token= query injection missing" +fi + +# ─── T6: inline live-log panes on the home page ─── +echo +echo "Group 3: home-page inline live-log panes (T6)" + +if grep -q 'new EventSource' "$APP_JS"; then + _pass "app.js creates EventSource for live log streaming" +else + _fail "app.js has no EventSource client" +fi + +if grep -qE "/api/sessions/.*\\\$\\{.*\\}/logs/" "$APP_JS"; then + _pass "EventSource URL targets the per-session log endpoint" +else + _fail "EventSource URL does not match the streaming protocol contract" +fi + +for evt in snapshot append resync eof; do + if grep -qE "addEventListener\('$evt'" "$APP_JS"; then + _pass "app.js handles SSE event: $evt" + else + _fail "app.js does not handle SSE event: $evt" + fi +done + +if grep -q '_mountLiveLogPane' "$APP_JS" && grep -q '_teardownAllLivePanes' "$APP_JS"; then + _pass "app.js mounts and tears down per-session live panes" +else + _fail "live-pane mount/teardown helpers missing" +fi + +# Home split into Active vs Completed sections uses the Claude- +# design kit's .session-grid container (auto-fit grid) tagged with +# data-home-section for the WS-driven diff updater. The old +# .active-sessions-list / .active-session-block + inline live-log +# scheme was removed when the log moved to the session-detail page. +if grep -q 'session-grid' "$APP_JS" && grep -q 'data-home-section="active"' "$APP_JS"; then + _pass "renderHome uses the new session-grid layout" +else + _fail "renderHome does not use the new session-grid layout" +fi + +if grep -q 'live-log-pane' "$PLUGIN_ROOT/viz/static/css/layout.css" && \ + grep -q 'session-grid' "$PLUGIN_ROOT/viz/static/css/layout.css"; then + _pass "layout.css includes styles for live log panes and session grid" +else + _fail "layout.css missing live-log-pane / session-grid styles" +fi + +# ─── T6 lifecycle fixes (Round 6) ─── +echo +echo "Group 4: T6 lifecycle hardening (Round 6)" + +# Teardown happens before EVERY non-home render, not just renderHome(). +if grep -qE "_teardownAllLivePanes\(\)" "$APP_JS" && \ + grep -qE "if \(route\.page !== 'home'\)" "$APP_JS"; then + _pass "non-home route changes call _teardownAllLivePanes()" +else + _fail "non-home renders do not tear down live panes" +fi + +# WebSocket is skipped in remote mode. +if grep -qE "_isRemoteMode" "$APP_JS" && \ + grep -qE "if \(_isRemoteMode\)" "$APP_JS"; then + _pass "WebSocket connect is skipped in remote mode (DEC-4 + remote WS rejection)" +else + _fail "WebSocket still connects unconditionally in remote mode" +fi + +# Home refresh is WS-driven and debounced: _scheduleHomeRefresh() +# coalesces bursts into one _refreshHomeCards() call that diff- +# updates the sessions list without a full page rebuild. Polling +# was removed in favor of this targeted path — a setInterval in the +# home route would re-introduce the "frantic refresh" bug. +if grep -q '_scheduleHomeRefresh' "$APP_JS" && grep -q '_refreshHomeCards' "$APP_JS"; then + _pass "home-route WS-driven targeted refresh is wired (covers WAITING -> live and EOF transitions)" +else + _fail "home targeted refresh helpers missing" +fi + +# eof closes the SSE cleanly without forcing a page rebuild; the +# session-detail Active -> Historical transition lands via the next +# WS round_added / session_finished event (server-side cache-dir +# watcher broadcasts when the state file is renamed). +if grep -qE "addEventListener\('eof'" "$APP_JS" && \ + grep -qE "_liveLogPanes\.delete" "$APP_JS"; then + _pass "eof handler closes the pane cleanly without forcing a page rebuild" +else + _fail "eof handler missing or does not deregister the live pane" +fi + +# ─── Round 11 frontend fixes ─── +echo +echo "Group 5: Round 11 P2 frontend fixes" + +# Cancel button visibility now matches backend _CANCELLABLE_STATUSES. +if grep -qE "CANCELLABLE_STATUSES.*=.*\['active'.*'analyzing'.*'finalizing'\]" "$APP_JS" && \ + grep -qE "CANCELLABLE_STATUSES\.includes\(session\.status\)" "$APP_JS"; then + _pass "cancel button visibility checks {active, analyzing, finalizing} (matches backend P2 fix)" +else + _fail "cancel button still hidden in analyzing/finalizing phases" +fi + +# Live log pane decodes UTF-8 properly (no mojibake on CJK/emoji). +if grep -qE "TextDecoder\(['\"]utf-8['\"]" "$APP_JS"; then + _pass "live log pane decodes byte stream as UTF-8 (no mojibake on non-ASCII output)" +else + _fail "live log pane still feeds atob() output directly into textContent (UTF-8 broken)" +fi + +if grep -qE "Uint8Array\(.*\.length\)" "$APP_JS" && grep -q 'charCodeAt' "$APP_JS"; then + _pass "live log pane converts Latin-1 binstring to Uint8Array before decoding" +else + _fail "live log pane missing the binstring -> Uint8Array conversion" +fi + +# ─── Group 6: Round 16 P2 fix — pipeline drag listener singleton ─── +echo +echo "Group 6: pipeline.js window-level drag listeners installed once (P2 Round 16)" + +PIPELINE_JS="$PLUGIN_ROOT/viz/static/js/pipeline.js" + +# The window-level mousemove/mouseup pair must be guarded so re- +# rendering the pipeline on every SSE update does not accumulate +# duplicate handlers. A singleton guard flag + helper is the +# idiomatic form. +if grep -qE '_dragListenersInstalled\s*=\s*false' "$PIPELINE_JS" && \ + grep -qE 'function _ensureDragListeners' "$PIPELINE_JS"; then + _pass "pipeline.js defines _dragListenersInstalled guard + _ensureDragListeners helper" +else + _fail "pipeline.js missing singleton guard for window-level drag listeners" +fi + +# renderPipeline must NOT call window.addEventListener directly +# (that was the duplication vector). It must route through the +# singleton helper. +render_body=$(awk '/^function renderPipeline/,/^}$/' "$PIPELINE_JS") +if grep -q 'window.addEventListener' <<<"$render_body"; then + _fail "renderPipeline still calls window.addEventListener directly (duplication vector)" +else + _pass "renderPipeline no longer calls window.addEventListener directly" +fi + +if grep -q '_ensureDragListeners()' <<<"$render_body"; then + _pass "renderPipeline routes window listeners through _ensureDragListeners()" +else + _fail "renderPipeline does not call _ensureDragListeners()" +fi + +# The guard must flip to true after the one-time install so the +# next call short-circuits. +if grep -qE '_dragListenersInstalled\s*=\s*true' "$PIPELINE_JS"; then + _pass "_ensureDragListeners sets the guard to true after install (one-shot)" +else + _fail "_ensureDragListeners never flips the guard (would re-install every call)" +fi + +# ─── Group 7: WS-driven targeted session refresh ─── +echo +echo "Group 7: session-detail targeted refresh + race guard" + +# Session-scoped WS events schedule a debounced refresh that +# re-populates only the pipeline / sidebar / goal-bar subtrees. +# Polling was removed in favor of this path; a setInterval would +# reset the user's zoom / pan and restart the EventSource. +if grep -qE '_scheduleSessionPartialRefresh' "$APP_JS" && \ + grep -qE 'async function _refreshSessionPartial' "$APP_JS"; then + _pass "app.js defines _scheduleSessionPartialRefresh + _refreshSessionPartial helpers" +else + _fail "session-route targeted refresh helpers missing" +fi + +# Race guard: after the /api/sessions/ fetch resolves we must +# re-check the active route and the layout skeleton's data-session-id +# before mutating DOM. Otherwise a user who navigated away between +# the request and the response would see stale data flash into the +# new page. +if grep -qE "route\.page !== 'session'" "$APP_JS" && \ + grep -qE 'data-session-id="\$\{CSS\.escape\(sessionId\)\}"' "$APP_JS"; then + _pass "_refreshSessionPartial guards against route-change race after await" +else + _fail "_refreshSessionPartial does not re-check route + skeleton after await" +fi + +# Remote mode cannot reach the localhost-only WS, so a slow +# (~10s) polling fallback re-uses the same targeted-refresh path. +# It must gate on _isRemoteMode so localhost deployments stay WS- +# only. +if grep -qE 'function _startRemotePolling' "$APP_JS" && \ + grep -qE '_isRemoteMode' "$APP_JS"; then + _pass "remote-mode slow polling fallback is wired via _startRemotePolling" +else + _fail "remote-mode polling fallback missing" +fi + +# Detail-page live-log pane mounts only on the session-detail +# route and is driven by the per-session SSE stream. The helper +# must be idempotent so WS-driven refreshes do not tear down the +# pane on every event. +if grep -qE 'function _ensureSessionLogPane' "$APP_JS" && \ + grep -qE 'session-log-container' "$APP_JS"; then + _pass "_ensureSessionLogPane preserves the live-log SSE across WS refreshes" +else + _fail "session-detail live-log helper _ensureSessionLogPane missing" +fi + +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll frontend migration tests passed!\033[0m\n' diff --git a/tests/test-rlcr-sources.sh b/tests/test-rlcr-sources.sh new file mode 100755 index 00000000..94a97a49 --- /dev/null +++ b/tests/test-rlcr-sources.sh @@ -0,0 +1,292 @@ +#!/usr/bin/env bash +# +# Parity and behavior tests for viz/server/rlcr_sources.py. +# +# Covers: +# - sanitize_project_path() matches the sed pipeline used in +# scripts/humanize.sh for a selection of representative paths +# (spaces, slashes, tildes, unicode, repeated special chars). +# - enumerate_sessions() returns every seeded session directory +# and partition_sessions() classifies active / historical / unknown +# correctly. +# - live_log_paths() finds only round-N-{codex|gemini}-{run|review}.log +# in the per-session cache directory and returns them in +# deterministic order. +# +# No network access. All fixtures live under a per-test mktemp tree. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +VIZ_SERVER_DIR="$PLUGIN_ROOT/viz/server" + +echo "========================================" +echo "rlcr_sources.py parity and behavior" +echo "========================================" + +if ! command -v python3 &>/dev/null; then + echo "SKIP: python3 not available" + exit 0 +fi + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +_shell_sanitize() { + # Exact rule from scripts/humanize.sh: + # sanitized_project=$(echo "$project_root" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g') + printf '%s\n' "$1" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g' +} + +_py_sanitize() { + python3 - "$1" <<'PYEOF' +import sys +sys.path.insert(0, "__VIZ_SERVER_DIR__") +from rlcr_sources import sanitize_project_path +print(sanitize_project_path(sys.argv[1])) +PYEOF +} + +# Rewrite the __VIZ_SERVER_DIR__ placeholder so we can safely single-quote the heredoc +_py_sanitize() { + python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import sanitize_project_path +print(sanitize_project_path(sys.argv[1])) +" "$1" +} + +# ─── Test Group 1: sanitize_project_path parity ─── +echo +echo "Group 1: sanitize_project_path parity with scripts/humanize.sh" + +declare -a PROJECT_PATHS=( + "/home/user/project" + "/home/user/my project/with spaces" + "/tmp/a_b.c-d" + "/home/user/proj//double/slash" + "/home/user/proj@@@weird!!chars" + "/home/user/日本語/foo" + "~/relative-ish" +) + +for p in "${PROJECT_PATHS[@]}"; do + expected="$(_shell_sanitize "$p")" + actual="$(_py_sanitize "$p")" + if [[ "$expected" == "$actual" ]]; then + _pass "sanitize matches shell for: $p" + else + _fail "sanitize mismatch for: $p (shell='$expected' python='$actual')" + fi +done + +# Empty path should not explode +empty_shell="$(_shell_sanitize "")" +empty_py="$(_py_sanitize "")" +if [[ "$empty_shell" == "$empty_py" ]]; then + _pass "sanitize matches shell for empty string" +else + _fail "sanitize mismatch for empty string (shell='$empty_shell' python='$empty_py')" +fi + +# ─── Test Group 2: enumerate_sessions + partition_sessions ─── +echo +echo "Group 2: enumeration and partitioning" + +TMP_DIR="$(mktemp -d)" +trap 'rm -rf "$TMP_DIR"' EXIT + +RLCR_DIR="$TMP_DIR/.humanize/rlcr" +mkdir -p "$RLCR_DIR" + +# Active session: has state.md +mkdir -p "$RLCR_DIR/2026-04-17_10-00-00" +: > "$RLCR_DIR/2026-04-17_10-00-00/state.md" + +# Historical session: has complete-state.md, no state.md +mkdir -p "$RLCR_DIR/2026-04-16_09-00-00" +: > "$RLCR_DIR/2026-04-16_09-00-00/complete-state.md" + +# Unknown session: empty dir +mkdir -p "$RLCR_DIR/2026-04-15_08-00-00" + +# Non-session file (should be skipped silently) +: > "$RLCR_DIR/not-a-session.txt" + +ENUM_OUTPUT="$(python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import enumerate_sessions, partition_sessions +entries = enumerate_sessions('$RLCR_DIR') +active, historical, unknown = partition_sessions(entries) +print('ALL:', '|'.join(e[0] for e in entries)) +print('ACTIVE:', '|'.join(e[0] for e in active)) +print('HISTORICAL:', '|'.join(e[0] for e in historical)) +print('UNKNOWN:', '|'.join(e[0] for e in unknown)) +")" + +# Expected: chronological sort, 3 sessions total +if grep -q '^ALL: 2026-04-15_08-00-00|2026-04-16_09-00-00|2026-04-17_10-00-00$' <<<"$ENUM_OUTPUT"; then + _pass "enumerate lists all 3 seeded sessions in chronological order" +else + _fail "enumerate output unexpected: $(grep '^ALL:' <<<"$ENUM_OUTPUT")" +fi + +if grep -q '^ACTIVE: 2026-04-17_10-00-00$' <<<"$ENUM_OUTPUT"; then + _pass "partition identifies active session" +else + _fail "active partition wrong: $(grep '^ACTIVE:' <<<"$ENUM_OUTPUT")" +fi + +if grep -q '^HISTORICAL: 2026-04-16_09-00-00$' <<<"$ENUM_OUTPUT"; then + _pass "partition identifies historical session" +else + _fail "historical partition wrong: $(grep '^HISTORICAL:' <<<"$ENUM_OUTPUT")" +fi + +if grep -q '^UNKNOWN: 2026-04-15_08-00-00$' <<<"$ENUM_OUTPUT"; then + _pass "partition identifies unknown session (no state files yet)" +else + _fail "unknown partition wrong: $(grep '^UNKNOWN:' <<<"$ENUM_OUTPUT")" +fi + +# RLCR lifecycle: methodology-analysis and finalize phases must classify as active. +# Plain *-state.md files (complete, cancel, etc.) must classify as historical. +mkdir -p "$RLCR_DIR/2026-04-14_07-00-00" +: > "$RLCR_DIR/2026-04-14_07-00-00/methodology-analysis-state.md" +mkdir -p "$RLCR_DIR/2026-04-13_06-00-00" +: > "$RLCR_DIR/2026-04-13_06-00-00/finalize-state.md" +mkdir -p "$RLCR_DIR/2026-04-12_05-00-00" +: > "$RLCR_DIR/2026-04-12_05-00-00/cancel-state.md" +mkdir -p "$RLCR_DIR/2026-04-11_04-00-00" +: > "$RLCR_DIR/2026-04-11_04-00-00/maxiter-state.md" + +LIFECYCLE_OUTPUT="$(python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import enumerate_sessions, partition_sessions +entries = enumerate_sessions('$RLCR_DIR') +active, historical, unknown = partition_sessions(entries) +print('ACTIVE:', '|'.join(e[0] for e in active)) +print('HISTORICAL:', '|'.join(e[0] for e in historical)) +")" + +# Active set should now include: 2026-04-13, 2026-04-14, 2026-04-17 (sorted lexically) +if grep -q '^ACTIVE: 2026-04-13_06-00-00|2026-04-14_07-00-00|2026-04-17_10-00-00$' <<<"$LIFECYCLE_OUTPUT"; then + _pass "methodology-analysis and finalize phases classified as active" +else + _fail "lifecycle active partition wrong: $(grep '^ACTIVE:' <<<"$LIFECYCLE_OUTPUT")" +fi + +# Historical set should include: 2026-04-11 (maxiter), 2026-04-12 (cancel), 2026-04-16 (complete) +if grep -q '^HISTORICAL: 2026-04-11_04-00-00|2026-04-12_05-00-00|2026-04-16_09-00-00$' <<<"$LIFECYCLE_OUTPUT"; then + _pass "complete/cancel/maxiter terminal states classified as historical" +else + _fail "lifecycle historical partition wrong: $(grep '^HISTORICAL:' <<<"$LIFECYCLE_OUTPUT")" +fi + +# Cleanup the lifecycle fixtures so subsequent tests still see the original 3-session shape +rm -rf "$RLCR_DIR/2026-04-11_04-00-00" "$RLCR_DIR/2026-04-12_05-00-00" "$RLCR_DIR/2026-04-13_06-00-00" "$RLCR_DIR/2026-04-14_07-00-00" + +# Missing rlcr dir returns empty list without raising +MISSING_OUTPUT="$(python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import enumerate_sessions +print(enumerate_sessions('/tmp/does-not-exist-$$')) +")" +if [[ "$MISSING_OUTPUT" == "[]" ]]; then + _pass "enumerate returns [] for missing rlcr dir" +else + _fail "enumerate should return [] for missing dir, got: $MISSING_OUTPUT" +fi + +# ─── Test Group 3: live_log_paths ─── +echo +echo "Group 3: live_log_paths discovery and ordering" + +# Seed a fake cache dir with a mix of valid and invalid filenames +CACHE_DIR="$TMP_DIR/fakecache/humanize/-home-someproject/2026-04-17_10-00-00" +mkdir -p "$CACHE_DIR" +: > "$CACHE_DIR/round-0-codex-run.log" +: > "$CACHE_DIR/round-0-codex-review.log" +: > "$CACHE_DIR/round-1-codex-run.log" +: > "$CACHE_DIR/round-1-gemini-run.log" +: > "$CACHE_DIR/round-10-codex-run.log" +: > "$CACHE_DIR/random-file.txt" # should be ignored +: > "$CACHE_DIR/round-abc-codex-run.log" # should be ignored (non-numeric round) + +LOGS_OUTPUT="$(python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import live_log_paths +for rnd, tool, role, path in live_log_paths('$CACHE_DIR'): + print(f'{rnd}|{tool}|{role}') +")" + +EXPECTED_LOGS="0|codex|review +0|codex|run +1|codex|run +1|gemini|run +10|codex|run" + +if [[ "$LOGS_OUTPUT" == "$EXPECTED_LOGS" ]]; then + _pass "live_log_paths returns 5 matches in (round,tool,role) order; ignores non-matching files" +else + _fail "live_log_paths output unexpected: +---- expected ---- +$EXPECTED_LOGS +---- actual ---- +$LOGS_OUTPUT" +fi + +# Missing cache dir returns empty list (startup race safety) +MISSING_LOGS="$(python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import live_log_paths +print(live_log_paths('/tmp/cache-does-not-exist-$$')) +")" +if [[ "$MISSING_LOGS" == "[]" ]]; then + _pass "live_log_paths returns [] for missing cache dir (startup-race safety)" +else + _fail "live_log_paths should return [] for missing dir, got: $MISSING_LOGS" +fi + +# ─── Test Group 4: cache_dir_for_session path shape ─── +echo +echo "Group 4: cache_dir_for_session path construction" + +PATH_OUTPUT="$( + XDG_CACHE_HOME="$TMP_DIR/cache_override" python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from rlcr_sources import cache_dir_for_session +print(cache_dir_for_session('/home/user/weird project', '2026-04-17_10-00-00')) +")" + +EXPECTED_PATH="$TMP_DIR/cache_override/humanize/-home-user-weird-project/2026-04-17_10-00-00" +if [[ "$PATH_OUTPUT" == "$EXPECTED_PATH" ]]; then + _pass "cache_dir_for_session respects XDG_CACHE_HOME and sanitization" +else + _fail "cache_dir mismatch: + expected: $EXPECTED_PATH + actual: $PATH_OUTPUT" +fi + +# ─── Summary ─── +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll rlcr_sources tests passed!\033[0m\n' diff --git a/tests/test-stop-gate.sh b/tests/test-stop-gate.sh index 8c3b6e25..a6034e1e 100755 --- a/tests/test-stop-gate.sh +++ b/tests/test-stop-gate.sh @@ -286,5 +286,36 @@ else "exit 10 (mock hook returns block)" "exit $EXIT6; output: $T6_BODY" fi +# Assertions about ignoring an inherited CLAUDE_PROJECT_DIR were +# removed during the rebase onto upstream/dev: upstream's +# `resolve_project_root` deliberately honors CLAUDE_PROJECT_DIR as +# the first-choice signal (CLAUDE_PROJECT_DIR -> git toplevel, no +# pwd fallback). That is an intentional upstream design choice, not +# a regression, so those two old assertions are no longer +# applicable. The --project-root explicit-override check below still +# holds and is the right contract for the CLI flag. + +# --project-root MUST still override the default cwd / inherited env +# so callers can explicitly target a different repository. +T5_DIR="$TEST_DIR/t5-explicit-override" +mkdir -p "$T5_DIR/empty-cwd" +setup_active_loop_fixture "$T5_DIR/target-project" + +set +e +( + cd "$T5_DIR/empty-cwd" + CLAUDE_PROJECT_DIR="$T5_DIR/empty-cwd" "$GATE_SCRIPT" --project-root "$T5_DIR/target-project" +) > "$T5_DIR/out.txt" 2>&1 +EXIT5=$? +set -e + +if [[ "$EXIT5" -eq 10 ]]; then + pass "[P1 Round 18] --project-root override still wins over cwd + inherited env" +else + OUTPUT5=$(cat "$T5_DIR/out.txt" 2>/dev/null || true) + fail "[P1 Round 18] --project-root override no longer works" \ + "exit 10 (target has active loop)" "exit $EXIT5; output: $OUTPUT5" +fi + print_test_summary "RLCR Stop Gate Wrapper Test Summary" exit $? diff --git a/tests/test-streaming.sh b/tests/test-streaming.sh new file mode 100755 index 00000000..3befde6c --- /dev/null +++ b/tests/test-streaming.sh @@ -0,0 +1,532 @@ +#!/usr/bin/env bash +# +# Behavior tests for viz/server/log_streamer.py and the parser/watcher +# extensions added in the streaming block (T3+T4+T5). +# +# Covers the contract in docs/streaming-protocol.md: +# - Snapshot of an existing file (chunked at 64 KiB) +# - Append after new bytes are written +# - Truncation: file size shrinks below known offset +# - Rotation: same path, new inode +# - Missing file at startup: no events, no crash +# - Missing then reappear: resync(recreated) + fresh snapshot +# - EOF: subsequent polls are no-ops +# - Replay with Last-Event-Id: in-window returns newer events; out +# of window returns resync(overflow) +# - Parser cache_logs_for_session integrates rlcr_sources discovery +# +# No network access; all fixtures live under per-test mktemp tree. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +VIZ_SERVER_DIR="$PLUGIN_ROOT/viz/server" + +echo "========================================" +echo "Streaming block (T3+T4+T5)" +echo "========================================" + +if ! command -v python3 &>/dev/null; then + echo "SKIP: python3 not available" + exit 0 +fi + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +TMP_DIR="$(mktemp -d)" +trap 'rm -rf "$TMP_DIR"' EXIT + +CACHE_DIR="$TMP_DIR/cache" +mkdir -p "$CACHE_DIR" + +# Helper: run a python driver and capture its output +_run_py() { + python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +$1 +" +} + +# ─── Test Group 1: Missing file at startup ─── +echo +echo "Group 1: Missing file at startup" + +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-0-codex-run.log') +events = stream.snapshot() +print('SNAPSHOT_COUNT:', len(events)) +events = stream.poll() +for e in events: + print('POLL:', e['type'], e.get('reason', '')) +")" + +if grep -q '^SNAPSHOT_COUNT: 0$' <<<"$OUTPUT"; then + _pass "snapshot of missing file emits no events" +else + _fail "expected 0 snapshot events, got: $(grep '^SNAPSHOT_COUNT' <<<"$OUTPUT")" +fi + +if grep -q '^POLL: resync missing$' <<<"$OUTPUT"; then + _pass "first poll of missing file emits resync(missing)" +else + _fail "expected resync(missing) on first poll, got: $(grep '^POLL:' <<<"$OUTPUT")" +fi + +# ─── Test Group 2: Snapshot existing file ─── +echo +echo "Group 2: Snapshot of existing file" + +LOG="$CACHE_DIR/round-1-codex-run.log" +printf 'hello world' > "$LOG" + +OUTPUT="$(_run_py " +import base64 +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-1-codex-run.log') +events = stream.snapshot() +print('COUNT:', len(events)) +for e in events: + print('TYPE:', e['type']) + print('OFFSET:', e['offset']) + print('BYTES:', base64.b64decode(e['bytes_b64']).decode('ascii')) + print('EOF:', e['eof']) +")" + +if grep -q '^COUNT: 1$' <<<"$OUTPUT"; then + _pass "snapshot emits one event for small file" +else + _fail "expected 1 snapshot event, got: $(grep '^COUNT' <<<"$OUTPUT")" +fi + +if grep -q '^TYPE: snapshot$' <<<"$OUTPUT" && grep -q '^OFFSET: 0$' <<<"$OUTPUT" && grep -q '^BYTES: hello world$' <<<"$OUTPUT" && grep -q '^EOF: False$' <<<"$OUTPUT"; then + _pass "snapshot payload contains 'hello world' at offset 0 with eof=False" +else + _fail "snapshot payload wrong: $OUTPUT" +fi + +# ─── Test Group 3: Append after writes ─── +echo +echo "Group 3: Append after writes" + +OUTPUT="$(_run_py " +import base64 +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-1-codex-run.log') +stream.snapshot() +with open('$LOG', 'ab') as f: + f.write(b' more') +events = stream.poll() +for e in events: + print('TYPE:', e['type']) + print('OFFSET:', e['offset']) + print('BYTES:', base64.b64decode(e['bytes_b64']).decode('ascii')) +")" + +if grep -q '^TYPE: append$' <<<"$OUTPUT" && grep -q '^OFFSET: 11$' <<<"$OUTPUT" && grep -q '^BYTES: more$' <<<"$OUTPUT"; then + _pass "poll after append emits append event with correct offset and bytes" +else + _fail "append event wrong: $OUTPUT" +fi + +# ─── Test Group 4: Truncation triggers resync + fresh snapshot ─── +echo +echo "Group 4: Truncation" + +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-1-codex-run.log') +stream.snapshot() +# Truncate file to a smaller size in place +with open('$LOG', 'wb') as f: + f.write(b'short') +events = stream.poll() +for e in events: + print('TYPE:', e['type'], e.get('reason', ''), 'OFFSET:', e.get('offset', '-')) +")" + +# Expect: resync(truncated), snapshot +if grep -q '^TYPE: resync truncated' <<<"$OUTPUT" && grep -q '^TYPE: snapshot' <<<"$OUTPUT"; then + _pass "truncation triggers resync(truncated) followed by fresh snapshot" +else + _fail "truncation behavior wrong: $OUTPUT" +fi + +# ─── Test Group 5: Rotation (inode change) ─── +echo +echo "Group 5: Rotation (file recreated with different inode)" + +ROTLOG="$CACHE_DIR/round-2-codex-run.log" +printf 'first generation' > "$ROTLOG" + +OUTPUT="$(_run_py " +import os +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-2-codex-run.log') +stream.snapshot() +# Rotate: rm + recreate produces a new inode +os.unlink('$ROTLOG') +with open('$ROTLOG', 'wb') as f: + f.write(b'new generation') +events = stream.poll() +for e in events: + print('TYPE:', e['type'], e.get('reason', '')) +")" + +# We may see resync(missing) first if poll happens between unlink and recreate; +# in this test the recreate is synchronous so we expect resync(rotated) followed by snapshot. +# Allow either pattern as long as resync occurs and a snapshot follows. +if grep -q '^TYPE: resync' <<<"$OUTPUT" && grep -q '^TYPE: snapshot' <<<"$OUTPUT"; then + _pass "rotation triggers resync followed by fresh snapshot" +else + _fail "rotation behavior wrong: $OUTPUT" +fi + +# ─── Test Group 6: Missing then reappear ─── +echo +echo "Group 6: Missing file reappears" + +REAP="$CACHE_DIR/round-3-codex-run.log" +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-3-codex-run.log') +# Initial poll: file missing, expect resync(missing) +events = stream.poll() +for e in events: + print('FIRST:', e['type'], e.get('reason', '')) +# Now create the file +with open('$REAP', 'wb') as f: + f.write(b'hello') +events = stream.poll() +for e in events: + print('SECOND:', e['type'], e.get('reason', '')) +")" + +if grep -q '^FIRST: resync missing$' <<<"$OUTPUT" && \ + grep -q '^SECOND: resync recreated$' <<<"$OUTPUT" && \ + grep -q '^SECOND: snapshot ' <<<"$OUTPUT"; then + _pass "missing -> reappear triggers resync(recreated) followed by snapshot" +else + _fail "reappear behavior wrong: $OUTPUT" +fi + +# ─── Test Group 7: EOF + subsequent polls ─── +echo +echo "Group 7: EOF marking is sticky" + +EOFLOG="$CACHE_DIR/round-4-codex-run.log" +printf 'done' > "$EOFLOG" +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-4-codex-run.log') +stream.snapshot() +events = stream.mark_eof() +print('EOF:', events[0]['type']) +events = stream.mark_eof() +print('SECOND_EOF_COUNT:', len(events)) +events = stream.poll() +print('POLL_AFTER_EOF_COUNT:', len(events)) +")" + +if grep -q '^EOF: eof$' <<<"$OUTPUT" && \ + grep -q '^SECOND_EOF_COUNT: 0$' <<<"$OUTPUT" && \ + grep -q '^POLL_AFTER_EOF_COUNT: 0$' <<<"$OUTPUT"; then + _pass "eof event is one-shot; subsequent polls and eof are no-ops" +else + _fail "eof stickiness wrong: $OUTPUT" +fi + +# ─── Test Group 8: Replay with Last-Event-Id ─── +echo +echo "Group 8: Replay with Last-Event-Id" + +REPLOG="$CACHE_DIR/round-5-codex-run.log" +printf 'aaaaa' > "$REPLOG" + +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-5-codex-run.log') +snap = stream.snapshot() # id 1 +# Append twice +with open('$REPLOG', 'ab') as f: + f.write(b'BBB') +ap1 = stream.poll() # id 2 +with open('$REPLOG', 'ab') as f: + f.write(b'CCC') +ap2 = stream.poll() # id 3 +# Client only saw up through id 2; replay starting from id 2 +replayed, in_window = stream.replay(2) +print('REPLAY_IN_WINDOW:', in_window) +print('REPLAY_COUNT:', len(replayed)) +for e in replayed: + print('REPLAY_ID:', e['id'], 'TYPE:', e['type']) +# Out-of-window: replay from a tiny id with retention exceeded +# Force overflow by manipulating retention; small fixture so replay an id below the window +# Retention is 256 so we cannot easily exceed it; just verify replay(0) returns ALL retained +all_replay, all_in_window = stream.replay(0) +print('REPLAY_ALL_COUNT:', len(all_replay)) +print('REPLAY_ALL_IN_WINDOW:', all_in_window) +")" + +if grep -q '^REPLAY_IN_WINDOW: True$' <<<"$OUTPUT" && \ + grep -q '^REPLAY_COUNT: 1$' <<<"$OUTPUT" && \ + grep -q '^REPLAY_ID: 3 TYPE: append$' <<<"$OUTPUT"; then + _pass "in-window replay returns events newer than Last-Event-Id" +else + _fail "in-window replay wrong: $OUTPUT" +fi + +if grep -q '^REPLAY_ALL_COUNT: 3$' <<<"$OUTPUT" && grep -q '^REPLAY_ALL_IN_WINDOW: True$' <<<"$OUTPUT"; then + _pass "replay(0) returns all retained events" +else + _fail "replay(0) result wrong: $OUTPUT" +fi + +# Also verify out-of-window: directly invoke replay with id much smaller than oldest after window slides +OUTPUT_OW="$(_run_py " +from log_streamer import LogStream, EVENT_RETENTION +import os +log = '$CACHE_DIR/round-6-codex-run.log' +with open(log, 'wb') as f: + f.write(b'') +stream = LogStream('$CACHE_DIR', 'round-6-codex-run.log') +# Generate enough events to overflow the retention window +for i in range(EVENT_RETENTION + 5): + with open(log, 'ab') as f: + f.write(b'x') + stream.poll() +# Replay from id 1 - should be out of window now (oldest id in window is 6) +replayed, in_window = stream.replay(1) +print('OW_IN_WINDOW:', in_window) +print('OW_TYPE:', replayed[0]['type'], replayed[0].get('reason', '')) +")" + +if grep -q '^OW_IN_WINDOW: False$' <<<"$OUTPUT_OW" && grep -q '^OW_TYPE: resync overflow$' <<<"$OUTPUT_OW"; then + _pass "out-of-window replay emits resync(overflow)" +else + _fail "out-of-window replay wrong: $OUTPUT_OW" +fi + +# ─── Test Group 9: Snapshot chunking at 64 KiB ─── +echo +echo "Group 9: Snapshot chunking" + +BIGLOG="$CACHE_DIR/round-7-codex-run.log" +# 130 KiB of bytes -> expect 3 snapshot chunks of (64,64,2) KiB +python3 -c "open('$BIGLOG','wb').write(b'x' * (130 * 1024))" + +OUTPUT="$(_run_py " +from log_streamer import LogStream +stream = LogStream('$CACHE_DIR', 'round-7-codex-run.log') +events = stream.snapshot() +print('CHUNK_COUNT:', len(events)) +total = sum(len(__import__('base64').b64decode(e['bytes_b64'])) for e in events) +print('TOTAL_BYTES:', total) +print('OFFSETS:', ','.join(str(e['offset']) for e in events)) +")" + +if grep -q '^CHUNK_COUNT: 3$' <<<"$OUTPUT" && \ + grep -q '^TOTAL_BYTES: 133120$' <<<"$OUTPUT" && \ + grep -q '^OFFSETS: 0,65536,131072$' <<<"$OUTPUT"; then + _pass "130 KiB file is chunked into 3 snapshot events at 64 KiB boundaries" +else + _fail "chunking wrong: $OUTPUT" +fi + +# ─── Test Group 10: Parser integration (cache_logs_for_session) ─── +echo +echo "Group 10: parser.cache_logs_for_session" + +PROJECT_ROOT="$TMP_DIR/proj" +SID="2026-04-17_99-99-99" +mkdir -p "$PROJECT_ROOT/.humanize/rlcr/$SID" +: > "$PROJECT_ROOT/.humanize/rlcr/$SID/state.md" + +# Need to seed cache logs at the rlcr_sources-derived path under XDG_CACHE_HOME +PROJECT_CACHE_DIR="$TMP_DIR/cache_xdg/humanize/$(printf '%s' "$PROJECT_ROOT" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g')/$SID" +mkdir -p "$PROJECT_CACHE_DIR" +: > "$PROJECT_CACHE_DIR/round-0-codex-run.log" +: > "$PROJECT_CACHE_DIR/round-1-codex-run.log" +: > "$PROJECT_CACHE_DIR/round-1-codex-review.log" + +OUTPUT="$(XDG_CACHE_HOME="$TMP_DIR/cache_xdg" python3 -c " +import sys +sys.path.insert(0, '$VIZ_SERVER_DIR') +from parser import cache_logs_for_session +logs = cache_logs_for_session('$PROJECT_ROOT', '$SID') +print('LOG_COUNT:', len(logs)) +for log in logs: + print('LOG:', log['round'], log['tool'], log['role'], log['basename']) +")" + +if grep -q '^LOG_COUNT: 3$' <<<"$OUTPUT"; then + _pass "cache_logs_for_session returns 3 logs" +else + _fail "cache_logs_for_session count wrong: $OUTPUT" +fi + +if grep -q '^LOG: 0 codex run round-0-codex-run.log$' <<<"$OUTPUT" && \ + grep -q '^LOG: 1 codex review round-1-codex-review.log$' <<<"$OUTPUT" && \ + grep -q '^LOG: 1 codex run round-1-codex-run.log$' <<<"$OUTPUT"; then + _pass "cache_logs_for_session returns deterministic ordering with full metadata" +else + _fail "cache_logs_for_session ordering wrong: $OUTPUT" +fi + +# ─── Test Group 11: Shared stream registry + reconnect semantics ─── +echo +echo "Group 11: LogStreamRegistry + reconnect semantics" + +REGLOG="$CACHE_DIR/round-8-codex-run.log" +printf 'initial' > "$REGLOG" + +OUTPUT="$(_run_py " +from log_streamer import LogStreamRegistry, LogStream +reg = LogStreamRegistry() +s1 = reg.get_or_create('$CACHE_DIR', 'sid-A', 'round-8-codex-run.log') +s2 = reg.get_or_create('$CACHE_DIR', 'sid-A', 'round-8-codex-run.log') +print('SAME:', s1 is s2) +print('LEN_AFTER_DUP_KEY:', len(reg)) +s3 = reg.get_or_create('$CACHE_DIR', 'sid-B', 'round-8-codex-run.log') +print('DIFFERENT:', s1 is not s3) +print('LEN_AFTER_NEW_KEY:', len(reg)) +# streams_in_cache_dir returns both streams targeting the same basename +streams = reg.streams_in_cache_dir('$CACHE_DIR', 'round-8-codex-run.log') +print('STREAMS_FOR_BASENAME:', len(streams)) +")" + +if grep -q '^SAME: True$' <<<"$OUTPUT" && \ + grep -q '^LEN_AFTER_DUP_KEY: 1$' <<<"$OUTPUT" && \ + grep -q '^DIFFERENT: True$' <<<"$OUTPUT" && \ + grep -q '^LEN_AFTER_NEW_KEY: 2$' <<<"$OUTPUT" && \ + grep -q '^STREAMS_FOR_BASENAME: 2$' <<<"$OUTPUT"; then + _pass "registry returns same instance for same key, distinct for different keys" +else + _fail "registry sharing wrong: $OUTPUT" +fi + +# Reconnect simulation: client saw events up through id=N; second +# connection to the SAME registered stream with Last-Event-Id=N must +# only receive events newer than N, never an `append` from offset 0. +OUTPUT="$(_run_py " +from log_streamer import LogStreamRegistry +reg = LogStreamRegistry() +stream = reg.get_or_create('$CACHE_DIR', 'sid-A', 'round-8-codex-run.log') +# Simulate first client: snapshot then one append +snap_events = stream.snapshot() +with open('$REGLOG', 'ab') as f: + f.write(b' APPENDED') +append_events = stream.poll() +# Client last saw the snapshot id +client_last = snap_events[-1]['id'] +# Second client reconnects via the registry with Last-Event-Id=client_last +same_stream = reg.get_or_create('$CACHE_DIR', 'sid-A', 'round-8-codex-run.log') +replayed, in_window = same_stream.replay(client_last) +print('IN_WINDOW:', in_window) +print('REPLAY_COUNT:', len(replayed)) +print('REPLAY_TYPES:', ','.join(e['type'] for e in replayed)) +print('REPLAY_OFFSETS:', ','.join(str(e.get('offset', -1)) for e in replayed)) +print('APPEND_STARTS_AFTER_SNAP:', all(e['offset'] >= snap_events[-1].get('offset', 0) + len(b'initial') for e in replayed if e['type'] == 'append')) +")" + +if grep -q '^IN_WINDOW: True$' <<<"$OUTPUT" && \ + grep -q '^REPLAY_TYPES: append$' <<<"$OUTPUT" && \ + grep -q '^APPEND_STARTS_AFTER_SNAP: True$' <<<"$OUTPUT"; then + _pass "reconnect via shared registry replays events newer than Last-Event-Id, no append from offset 0" +else + _fail "reconnect semantics wrong: $OUTPUT" +fi + +# Reconnect with Last-Event-Id from a DIFFERENT stream (unknown to this one) +# must produce resync(overflow) + snapshot path, not append from offset 0. +OUTPUT="$(_run_py " +from log_streamer import LogStreamRegistry, EVENT_RETENTION +reg = LogStreamRegistry() +stream = reg.get_or_create('$CACHE_DIR', 'sid-reconnect-fresh', 'round-8-codex-run.log') +# Exhaust the retention window by producing a large number of events +# so a Last-Event-Id from before the window becomes out-of-window. +import os +for _ in range(EVENT_RETENTION + 2): + with open('$REGLOG', 'ab') as f: + f.write(b'X') + stream.poll() +# Now reconnect with an ancient Last-Event-Id +replayed, in_window = stream.replay(1) +print('IN_WINDOW:', in_window) +print('FIRST_TYPE:', replayed[0]['type'], replayed[0].get('reason', '')) +print('NO_APPEND_OFFSET_ZERO_FIRST:', not (replayed[0]['type'] == 'append' and replayed[0].get('offset') == 0)) +")" + +if grep -q '^IN_WINDOW: False$' <<<"$OUTPUT" && \ + grep -q '^FIRST_TYPE: resync overflow$' <<<"$OUTPUT" && \ + grep -q '^NO_APPEND_OFFSET_ZERO_FIRST: True$' <<<"$OUTPUT"; then + _pass "out-of-window reconnect emits resync(overflow), NOT append from offset 0" +else + _fail "out-of-window reconnect wrong: $OUTPUT" +fi + +# ─── Idle stream eviction without follow-up release ─── +# Regression: a stream whose refcount drops to zero without EOF should +# not survive forever when no subsequent release() ever fires. Sweeps +# must also run on other registry interactions (acquire, +# streams_in_cache_dir) so idle retention deques are reclaimed under +# low-churn traffic. +SWEEPLOG="$CACHE_DIR/round-9-codex-run.log" +: > "$SWEEPLOG" + +OUTPUT="$(_run_py " +import time +from log_streamer import LogStreamRegistry +# Use a non-zero TTL and rewind the recorded idle timestamp so the +# next sweep observes the TTL as elapsed without real waiting. Reaching +# into a private dict is acceptable in a white-box regression test: +# the point is to verify which call-sites sweep, not real-time timing. +reg = LogStreamRegistry(idle_ttl_seconds=60.0) +# Stream A: one-off disconnect, no EOF, no further release on the same key. +reg.acquire('$CACHE_DIR', 'sid-sweep-A', 'round-9-codex-run.log') +reg.release('sid-sweep-A', 'round-9-codex-run.log') +print('A_PRESENT_BEFORE_SWEEP:', ('sid-sweep-A', 'round-9-codex-run.log') in reg) +# Force A's idle_since far in the past so any subsequent sweep evicts it. +reg._idle_since[('sid-sweep-A', 'round-9-codex-run.log')] = time.monotonic() - 1e6 +# New acquire on a different session must trigger the sweep. +reg.acquire('$CACHE_DIR', 'sid-sweep-B', 'round-9-codex-run.log') +print('A_EVICTED_BY_ACQUIRE:', ('sid-sweep-A', 'round-9-codex-run.log') not in reg) +print('B_PRESENT:', ('sid-sweep-B', 'round-9-codex-run.log') in reg) + +# Independent registry: verify streams_in_cache_dir() (invoked by the +# cache watcher callback on every observed write) also evicts idle +# streams even when no release() follows. +reg2 = LogStreamRegistry(idle_ttl_seconds=60.0) +reg2.acquire('$CACHE_DIR', 'sid-sweep-C', 'round-9-codex-run.log') +reg2.release('sid-sweep-C', 'round-9-codex-run.log') +reg2._idle_since[('sid-sweep-C', 'round-9-codex-run.log')] = time.monotonic() - 1e6 +_ = reg2.streams_in_cache_dir('$CACHE_DIR', 'round-9-codex-run.log') +print('C_EVICTED_BY_STREAMS_LOOKUP:', ('sid-sweep-C', 'round-9-codex-run.log') not in reg2) +")" + +if grep -q '^A_PRESENT_BEFORE_SWEEP: True$' <<<"$OUTPUT" && \ + grep -q '^A_EVICTED_BY_ACQUIRE: True$' <<<"$OUTPUT" && \ + grep -q '^B_PRESENT: True$' <<<"$OUTPUT" && \ + grep -q '^C_EVICTED_BY_STREAMS_LOOKUP: True$' <<<"$OUTPUT"; then + _pass "idle streams are evicted by acquire() and streams_in_cache_dir(), not only by a follow-up release()" +else + _fail "idle-stream sweep regression: $OUTPUT" +fi + +# ─── Summary ─── +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll streaming tests passed!\033[0m\n' diff --git a/tests/test-style-compliance.sh b/tests/test-style-compliance.sh new file mode 100755 index 00000000..e43dc75a --- /dev/null +++ b/tests/test-style-compliance.sh @@ -0,0 +1,101 @@ +#!/usr/bin/env bash +# +# AC-10 style-compliance test (added in Round 5 as task T15; +# expanded in Rounds 6 and 7 to cover the full plan-required scope). +# +# AC-10 forbids the literal substrings "AC-", "Milestone", "Step ", +# "Phase " from appearing in implementation code or comments. Those +# tokens are reserved for plan documentation; using them in code +# makes the codebase carry workflow markers that have no domain +# meaning at runtime. +# +# Scope (post-rebase against upstream/dev): +# - All .sh and .py files under viz/ (plan-authored code). +# - scripts/cancel-rlcr-session.sh (new file added by this plan). +# +# The broader scripts/ directory is upstream-owned. Its files +# legitimately reference workflow terms like "AC-1", "Phase", +# "Review Phase" in regex patterns, template content, and user- +# facing strings — those predate this plan and are outside AC-10's +# remit. Same reasoning for commands/ and hooks/. +# +# Excluded: +# - tests/ themselves (fixtures legitimately contain forbidden +# literals as expected input). +# - scripts/* except the plan-authored cancel-rlcr-session.sh. +# - commands/ and hooks/ (upstream-owned workflow). + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +echo "========================================" +echo "AC-10 style compliance (T15 full scope)" +echo "========================================" + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +# Step 1: every .sh and .py under viz/. +mapfile -t CORE_FILES < <( + find "$PLUGIN_ROOT/viz" \ + -type f \( -name '*.sh' -o -name '*.py' \) \ + -not -path "*/__pycache__/*" \ + 2>/dev/null | sort +) + +# Step 2: plan-authored files under scripts/. +PLAN_AUTHORED_SCRIPTS=( + "$PLUGIN_ROOT/scripts/cancel-rlcr-session.sh" +) +EXTRA_FILES=() +for f in "${PLAN_AUTHORED_SCRIPTS[@]}"; do + [[ -f "$f" ]] && EXTRA_FILES+=("$f") +done + +FILES=("${CORE_FILES[@]}" "${EXTRA_FILES[@]}") + +if [[ ${#FILES[@]} -eq 0 ]]; then + _fail "no plan-scope files found to scan" + exit 1 +fi + +n_core=${#CORE_FILES[@]} +n_extra=${#EXTRA_FILES[@]} +echo "Scanning ${#FILES[@]} files (${n_core} under viz/, ${n_extra} plan-authored under scripts/)." + +# Per-file findings keyed by pattern, so we report a single PASS or +# FAIL line per pattern with the offending file list. +for pattern in 'AC-' 'Milestone' 'Step ' 'Phase '; do + label="$pattern" + found_files=() + for f in "${FILES[@]}"; do + if grep -nF "$pattern" "$f" >/dev/null 2>&1; then + found_files+=("${f#$PLUGIN_ROOT/}") + fi + done + if [[ ${#found_files[@]} -eq 0 ]]; then + _pass "no '$label' literal across the plan's full AC-10 scope" + else + _fail "literal '$label' appears in: ${found_files[*]}" + for f in "${found_files[@]}"; do + echo " --- matches in $f ---" + grep -nF "$pattern" "$PLUGIN_ROOT/$f" | sed 's/^/ /' + done + fi +done + +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAC-10 compliance check passed!\033[0m\n' diff --git a/tests/test-viz-isolation.sh b/tests/test-viz-isolation.sh new file mode 100755 index 00000000..9840f0ed --- /dev/null +++ b/tests/test-viz-isolation.sh @@ -0,0 +1,277 @@ +#!/usr/bin/env bash +# +# Tests for per-project tmux/port isolation in the viz dashboard +# launcher (T9, AC-8). +# +# Verifies: +# - viz_tmux_session_name() returns a per-project name (different +# project paths produce different tmux session names). +# - viz-stop.sh and viz-status.sh derive the same name as +# viz-start.sh so they target the right project. +# - The legacy global session name "humanize-viz" no longer appears +# hard-coded in viz-start.sh / viz-stop.sh / viz-status.sh. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +NAME_HELPER="$PLUGIN_ROOT/viz/scripts/viz-session-name.sh" +START_SH="$PLUGIN_ROOT/viz/scripts/viz-start.sh" +STOP_SH="$PLUGIN_ROOT/viz/scripts/viz-stop.sh" +STATUS_SH="$PLUGIN_ROOT/viz/scripts/viz-status.sh" + +echo "========================================" +echo "Per-project viz isolation (T9 / AC-8)" +echo "========================================" + +PASS_COUNT=0 +FAIL_COUNT=0 + +_pass() { printf '\033[0;32mPASS\033[0m: %s\n' "$1"; PASS_COUNT=$((PASS_COUNT+1)); } +_fail() { printf '\033[0;31mFAIL\033[0m: %s\n' "$1"; FAIL_COUNT=$((FAIL_COUNT+1)); } + +if [[ ! -f "$NAME_HELPER" ]]; then + _fail "viz-session-name.sh not found at $NAME_HELPER" + exit 1 +fi + +# ─── Test 1: helper is sourceable and exposes viz_tmux_session_name ─── +# shellcheck disable=SC1090 +source "$NAME_HELPER" +if declare -F viz_tmux_session_name >/dev/null 2>&1; then + _pass "viz_tmux_session_name function is defined after sourcing" +else + _fail "viz_tmux_session_name function not defined" + exit 1 +fi + +# ─── Test 2: different project paths produce different names ─── +NAME_A="$(viz_tmux_session_name "/home/u/projectA")" +NAME_B="$(viz_tmux_session_name "/home/u/projectB")" + +if [[ -n "$NAME_A" && -n "$NAME_B" && "$NAME_A" != "$NAME_B" ]]; then + _pass "different project paths produce different tmux session names ($NAME_A vs $NAME_B)" +else + _fail "expected distinct names, got A='$NAME_A' B='$NAME_B'" +fi + +# ─── Test 3: same project path produces a stable name ─── +NAME_A2="$(viz_tmux_session_name "/home/u/projectA")" +if [[ "$NAME_A" == "$NAME_A2" ]]; then + _pass "same project path produces a stable tmux session name across calls" +else + _fail "stable-name expectation broken: '$NAME_A' vs '$NAME_A2'" +fi + +# ─── Test 4: name has the humanize-viz- prefix ─── +if [[ "$NAME_A" == humanize-viz-* ]]; then + _pass "session name uses the humanize-viz- prefix ($NAME_A)" +else + _fail "session name missing humanize-viz- prefix: $NAME_A" +fi + +# ─── Test 5: empty input falls back to legacy global name ─── +NAME_EMPTY="$(viz_tmux_session_name "")" +if [[ "$NAME_EMPTY" == "humanize-viz" ]]; then + _pass "empty project path falls back to legacy global name (defensive default)" +else + _fail "empty input should yield 'humanize-viz', got '$NAME_EMPTY'" +fi + +# ─── Test 6: viz-start.sh / viz-stop.sh / viz-status.sh source the helper ─── +for f in "$START_SH" "$STOP_SH" "$STATUS_SH"; do + if grep -q 'viz-session-name.sh' "$f"; then + _pass "$(basename "$f") sources viz-session-name.sh" + else + _fail "$(basename "$f") does not source viz-session-name.sh" + fi +done + +# ─── Test 7: viz-stop.sh and viz-status.sh no longer hard-code TMUX_SESSION="humanize-viz" ─── +for f in "$START_SH" "$STOP_SH" "$STATUS_SH"; do + if grep -qE 'TMUX_SESSION="humanize-viz"' "$f"; then + _fail "$(basename "$f") still hard-codes the legacy global tmux session name" + else + _pass "$(basename "$f") no longer hard-codes the legacy global tmux session name" + fi +done + +# ─── Test 8: scripts call viz_tmux_session_name with the project dir ─── +for f in "$START_SH" "$STOP_SH" "$STATUS_SH"; do + if grep -q 'viz_tmux_session_name "\$PROJECT_DIR"' "$f"; then + _pass "$(basename "$f") derives TMUX_SESSION from project dir" + else + _fail "$(basename "$f") does not derive TMUX_SESSION from project dir" + fi +done + +# ─── Test 9: viz.url persistence so health checks target the configured bind (Round 11 P2 fix) ─── +echo +echo "Group 9: viz.url persistence for non-loopback bind health checks (Round 11)" + +if grep -q 'URL_FILE="\$HUMANIZE_DIR/viz.url"' "$START_SH" && grep -q "echo \"http://" "$START_SH"; then + _pass "viz-start.sh writes viz.url alongside viz.port" +else + _fail "viz-start.sh does not persist the visible URL" +fi + +if grep -q 'URL_FILE="\$HUMANIZE_DIR/viz.url"' "$STATUS_SH" && grep -q '\$probe_url/api/health' "$STATUS_SH"; then + _pass "viz-status.sh reads viz.url for the liveness probe (no longer hardcodes localhost)" +else + _fail "viz-status.sh still probes localhost regardless of bind" +fi + +if grep -q 'URL_FILE="\$HUMANIZE_DIR/viz.url"' "$STOP_SH" && grep -q 'rm -f "\$PORT_FILE" "\$URL_FILE"' "$STOP_SH"; then + _pass "viz-stop.sh cleans up viz.url alongside viz.port" +else + _fail "viz-stop.sh leaves stale viz.url behind" +fi + +if grep -qE 'fall back to .*localhost|fallback.*localhost' "$STATUS_SH" || grep -q 'http://localhost:\$port' "$STATUS_SH"; then + _pass "viz-status.sh keeps the localhost fallback for older deployments without viz.url" +else + _fail "viz-status.sh missing back-compat fallback when viz.url is absent" +fi + +# ─── Group 10: find_port probes the configured bind host (Round 14 P2 fix) ─── +echo +echo "Group 10: find_port probes the configured host (Round 14 P2 fix)" + +# Before this fix, find_port always probed localhost. A specific +# non-loopback bind (e.g. 192.168.1.10) does not listen on localhost, +# so the probe mis-reported ports as free when another service owned +# them on the external interface, and Flask died with EADDRINUSE. +if grep -qE 'probe_host=.*"localhost"' "$START_SH" && \ + grep -qE 'probe_host="\$HOST"' "$START_SH"; then + _pass "viz-start.sh find_port branches probe_host on configured HOST" +else + _fail "viz-start.sh find_port still hardcodes localhost for all binds" +fi + +if grep -qE '/dev/tcp/\$probe_host/\$candidate' "$START_SH"; then + _pass "viz-start.sh find_port uses \$probe_host in /dev/tcp check (not literal localhost)" +else + _fail "viz-start.sh find_port still uses /dev/tcp/localhost/\$candidate literal" +fi + +# Check that the probe_host case block covers every documented bind +# family: loopback aliases, IPv4/IPv6 wildcards, and the specific-IP +# default. Missing any branch would regress the remote-mode contract. +if grep -B1 'probe_host="localhost"' "$START_SH" | grep -qE '127\.0\.0\.1\|::1\|localhost\|0\.0\.0\.0\|::'; then + _pass "find_port probe_host=localhost branch covers loopback + wildcard binds (127.0.0.1|::1|localhost|0.0.0.0|::)" +else + _fail "find_port probe_host=localhost branch missing one of the loopback/wildcard aliases" +fi + +# The specific-IP branch (default "*)") must set probe_host to $HOST +# so a non-loopback bind probes its own interface. +if awk '/^find_port\(\) \{/,/^\}$/' "$START_SH" | \ + grep -A1 '^\s*\*)' | grep -q 'probe_host="\$HOST"'; then + _pass "find_port default branch sets probe_host=\$HOST for specific non-loopback IPs" +else + _fail "find_port default branch does not set probe_host=\$HOST" +fi + +# ─── Group 11: readiness probe fail-closed (Round 16 P2 fix) ─── +echo +echo "Group 11: readiness probe fail-closed + cleanup (Round 16 P2 fix)" + +# The readiness loop must probe the canonical URL (viz.url) rather +# than hardcoding localhost, and must track whether any probe +# succeeded. Previously it printed "ready" unconditionally, so +# --host daemons and startup crashes both went +# unnoticed with stale viz.port / viz.url left on disk. +if grep -qE 'probe_url=\$\(cat "\$URL_FILE"\)' "$START_SH" && \ + grep -qE '"\$probe_url/api/health"' "$START_SH"; then + _pass "viz-start.sh readiness loop probes the canonical URL (viz.url), not literal localhost" +else + _fail "viz-start.sh readiness loop still probes localhost regardless of bind" +fi + +if grep -qE 'ready="true"' "$START_SH" && grep -qE 'if \[\[ "\$ready" != "true" \]\]; then' "$START_SH"; then + _pass "viz-start.sh readiness loop tracks success + fails closed when never reachable" +else + _fail "viz-start.sh readiness loop does not track success (always reports ready)" +fi + +fail_block=$(awk '/if \[\[ "\$ready" != "true" \]\]; then/,/^fi$/' "$START_SH") +if grep -q 'rm -f "\$PORT_FILE" "\$URL_FILE"' <<<"$fail_block"; then + _pass "viz-start.sh readiness failure cleans up stale viz.port and viz.url" +else + _fail "viz-start.sh readiness failure leaves stale port/url files behind" +fi + +if grep -q 'exit 1' <<<"$fail_block"; then + _pass "viz-start.sh readiness failure exits non-zero (launcher fails closed)" +else + _fail "viz-start.sh readiness failure still exits 0" +fi + +# ─── Group 12: Round 18 P2 fix — IPv6 bind addresses bracketed in viz.url ─── +echo +echo "Group 12: viz.url brackets IPv6 bind addresses per RFC 3986 (P2 Round 18)" + +# A specific IPv6 bind written as http://: is an invalid +# URL -- the port separator collides with the trailing fragments of +# the address. Without RFC 3986 brackets, curl/browsers/viz-status.sh +# treat the URL as unreachable and the Round 16 readiness probe +# falsely reports the dashboard as down. +if grep -qE 'case "\$visible_host_for_url" in' "$START_SH" && \ + grep -qE 'visible_host_for_url="\[\$\{visible_host_for_url\}\]"' "$START_SH"; then + _pass "viz-start.sh wraps IPv6 visible_host_for_url in RFC 3986 brackets" +else + _fail "viz-start.sh writes unbracketed IPv6 host to viz.url (readiness probe will false-fail)" +fi + +# Behavioural probe: source the URL-build block with different HOST +# values and verify the final URL shape is correct. +URL_PROBE_SCRIPT="$(mktemp)" +trap "rm -f '$URL_PROBE_SCRIPT'" EXIT +cat > "$URL_PROBE_SCRIPT" <<'PROBE_EOF' +#!/usr/bin/env bash +# Replay the viz.url case blocks for a range of HOST values and print +# the computed URL so the test can assert on shape. +set -u +for host_value in 127.0.0.1 ::1 localhost 0.0.0.0 :: 192.168.1.10 10.0.0.5 2001:db8::1 fe80::abcd:1234; do + HOST="$host_value" + PORT=18000 + visible_host_for_url="$HOST" + case "$HOST" in + 127.0.0.1|::1|localhost|0.0.0.0|::) + visible_host_for_url="localhost" + ;; + esac + case "$visible_host_for_url" in + *:*) + visible_host_for_url="[${visible_host_for_url}]" + ;; + esac + echo "HOST=$HOST URL=http://${visible_host_for_url}:${PORT}" +done +PROBE_EOF +chmod +x "$URL_PROBE_SCRIPT" + +if probe_url_output=$(bash "$URL_PROBE_SCRIPT" 2>&1); then + if grep -q 'HOST=::1 URL=http://localhost:18000' <<<"$probe_url_output" && \ + grep -q 'HOST=2001:db8::1 URL=http://\[2001:db8::1\]:18000' <<<"$probe_url_output" && \ + grep -q 'HOST=fe80::abcd:1234 URL=http://\[fe80::abcd:1234\]:18000' <<<"$probe_url_output" && \ + grep -q 'HOST=192.168.1.10 URL=http://192.168.1.10:18000' <<<"$probe_url_output" && \ + grep -q 'HOST=localhost URL=http://localhost:18000' <<<"$probe_url_output"; then + _pass "IPv6 bracketing matrix correct: loopback/wildcard -> localhost (no brackets); specific IPv6 -> bracketed; IPv4 -> unbracketed" + else + _fail "IPv6 bracketing matrix wrong: $probe_url_output" + fi +else + _fail "IPv6 bracketing probe failed: $probe_url_output" +fi + +echo +echo "========================================" +printf 'Passed: \033[0;32m%d\033[0m\n' "$PASS_COUNT" +printf 'Failed: \033[0;31m%d\033[0m\n' "$FAIL_COUNT" + +if [[ "$FAIL_COUNT" -gt 0 ]]; then + exit 1 +fi + +printf '\033[0;32mAll viz isolation tests passed!\033[0m\n' diff --git a/tests/test-viz.sh b/tests/test-viz.sh new file mode 100755 index 00000000..c9a55ace --- /dev/null +++ b/tests/test-viz.sh @@ -0,0 +1,518 @@ +#!/usr/bin/env bash +# +# Tests for the Humanize Viz dashboard functionality +# +# Tests cover: +# - viz-start.sh / viz-stop.sh / viz-status.sh script behavior +# - Python parser module (syntax + basic functionality) +# - Python analyzer module +# - Python exporter module +# - Sanitized issue generation +# - Setup script viz marker output +# - Cancel script viz stop integration +# + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/test-helpers.sh" + +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +VIZ_DIR="$PLUGIN_ROOT/viz" +SERVER_DIR="$VIZ_DIR/server" + +echo "========================================" +echo "Humanize Viz Dashboard Tests" +echo "========================================" + +# ─── Pre-check ─── +if ! command -v python3 &>/dev/null; then + echo "SKIP: python3 not available" + exit 0 +fi + +setup_test_dir + +# ======================================== +# Test Group 1: Shell Script Validation +# ======================================== +echo "" +echo "Test Group 1: Shell Script Syntax" + +for script in viz-start.sh viz-stop.sh viz-status.sh; do + if bash -n "$VIZ_DIR/scripts/$script" 2>/dev/null; then + pass "Shell syntax valid: $script" + else + fail "Shell syntax invalid: $script" + fi +done + +# ======================================== +# Test Group 2: Python Module Syntax +# ======================================== +echo "" +echo "Test Group 2: Python Module Syntax" + +for module in parser.py analyzer.py exporter.py app.py watcher.py; do + if python3 -m py_compile "$SERVER_DIR/$module" 2>/dev/null; then + pass "Python syntax valid: $module" + else + fail "Python syntax invalid: $module" + fi +done + +# ======================================== +# Test Group 3: Parser Tests +# ======================================== +echo "" +echo "Test Group 3: Parser Functionality" + +# Create a mock RLCR session +MOCK_PROJECT="$TEST_DIR/project" +MOCK_SESSION="$MOCK_PROJECT/.humanize/rlcr/2026-01-01_12-00-00" +mkdir -p "$MOCK_SESSION" + +# Create state.md +cat > "$MOCK_SESSION/state.md" << 'STATE' +--- +current_round: 2 +max_iterations: 42 +plan_file: plan.md +start_branch: main +base_branch: main +codex_model: gpt-5.4 +codex_effort: high +started_at: 2026-01-01T12:00:00Z +--- +STATE + +# Create goal-tracker.md +cat > "$MOCK_SESSION/goal-tracker.md" << 'GT' +## IMMUTABLE SECTION + +### Ultimate Goal +Build a test feature. + +### Acceptance Criteria + +- AC-1: First criterion +- AC-2: Second criterion + +--- + +## MUTABLE SECTION + +### Plan Version: 1 (Updated: Round 0) + +#### Active Tasks +| Task | Target AC | Status | Tag | Owner | Notes | +|------|-----------|--------|-----|-------|-------| +| task1 | AC-1 | completed | coding | claude | Done | +| task2 | AC-2 | in_progress | coding | claude | WIP | + +### Completed and Verified +| AC | Task | Completed Round | Verified Round | Evidence | +|----|------|-----------------|----------------|----------| +| AC-1 | task1 | 1 | 1 | Tests pass | + +### Explicitly Deferred +| Task | Original AC | Deferred Since | Justification | When to Reconsider | +|------|-------------|----------------|---------------|-------------------| +GT + +# Create round summaries +cat > "$MOCK_SESSION/round-0-summary.md" << 'R0' +# Round 0 Summary +## What Was Implemented +Initial setup completed. 2/4 tasks done. +## BitLesson Delta +Action: none +R0 + +cat > "$MOCK_SESSION/round-1-summary.md" << 'R1' +# Round 1 Summary +## What Was Implemented +Implemented main feature. +## BitLesson Delta +Action: add +R1 + +# Create review result +cat > "$MOCK_SESSION/round-0-review-result.md" << 'RR0' +# Round 0 Review +Mainline Progress Verdict: ADVANCED +The implementation is progressing well. +RR0 + +# Test parser +PARSER_OUTPUT=$(python3 -c " +import sys +sys.path.insert(0, '$SERVER_DIR') +from parser import parse_session, list_sessions, is_valid_session + +# Test is_valid_session +assert is_valid_session('$MOCK_SESSION'), 'should be valid session' + +# Test parse_session +s = parse_session('$MOCK_SESSION') +assert s['id'] == '2026-01-01_12-00-00', f'id mismatch: {s[\"id\"]}' +assert s['status'] == 'active', f'status: {s[\"status\"]}' +assert s['current_round'] == 2, f'round: {s[\"current_round\"]}' +assert s['max_iterations'] == 42 +assert s['plan_file'] == 'plan.md' +assert s['start_branch'] == 'main' +assert s['codex_model'] == 'gpt-5.4' + +# Rounds: should have 3 (0, 1, 2) even though round 2 has no summary +assert len(s['rounds']) == 3, f'expected 3 rounds, got {len(s[\"rounds\"])}' +assert s['rounds'][0]['number'] == 0 +assert s['rounds'][2]['number'] == 2 + +# Round 0 should have summary content +r0_summary = s['rounds'][0]['summary'] +assert r0_summary is not None and (isinstance(r0_summary, dict) or isinstance(r0_summary, str)), 'round 0 should have summary' + +# Round 2 should have null summary (no file) +r2_summary = s['rounds'][2]['summary'] +if isinstance(r2_summary, dict): + assert r2_summary.get('en') is None and r2_summary.get('zh') is None, 'round 2 summary should be null' + +# Verdict from review +assert s['rounds'][0]['verdict'] == 'advanced', f'verdict: {s[\"rounds\"][0][\"verdict\"]}' + +# Goal tracker +gt = s['goal_tracker'] +assert gt is not None +assert len(gt['acceptance_criteria']) == 2 +assert gt['acceptance_criteria'][0]['id'] == 'AC-1' + +# Completed and Verified parsing +assert len(gt['completed_verified']) == 1 +assert gt['completed_verified'][0]['ac'] == 'AC-1' + +# AC status from completed table +assert any(ac['status'] == 'completed' for ac in gt['acceptance_criteria']), 'AC-1 should be completed' + +# Task counts +assert s['tasks_total'] == 3, f'tasks_total: {s[\"tasks_total\"]}' # 2 active + 1 completed +assert s['tasks_done'] == 1, f'tasks_done: {s[\"tasks_done\"]}' + +# Test list_sessions +sessions = list_sessions('$MOCK_PROJECT') +assert len(sessions) == 1 +assert sessions[0]['id'] == '2026-01-01_12-00-00' + +print('ALL_PARSER_TESTS_PASSED') +" 2>&1) + +if echo "$PARSER_OUTPUT" | grep -q "ALL_PARSER_TESTS_PASSED"; then + pass "Parser: parse_session with full mock data" + pass "Parser: canonical round indices (0..current_round)" + pass "Parser: goal tracker with Completed and Verified" + pass "Parser: list_sessions" + pass "Parser: is_valid_session" +else + fail "Parser tests" "" "$PARSER_OUTPUT" +fi + +# Test malformed session skip +MALFORMED_SESSION="$MOCK_PROJECT/.humanize/rlcr/2026-01-01_13-00-00" +mkdir -p "$MALFORMED_SESSION" +echo "garbage" > "$MALFORMED_SESSION/readme.txt" + +SKIP_OUTPUT=$(python3 -c " +import sys +sys.path.insert(0, '$SERVER_DIR') +from parser import is_valid_session +assert not is_valid_session('$MALFORMED_SESSION'), 'should not be valid' +print('SKIP_OK') +" 2>&1) + +if echo "$SKIP_OUTPUT" | grep -q "SKIP_OK"; then + pass "Parser: skips malformed session (no state.md)" +else + fail "Parser: malformed session skip" "" "$SKIP_OUTPUT" +fi + +# ─── Regression: session_duration_minutes covers full on-disk round range ─── +# When state.current_round lags behind summaries already present on disk +# (parser expands rounds up to max_disk_round), duration must span every +# summary file's mtime, not just range(current_round+1). Fixture: two +# summary files with mtimes ~120s apart; state.current_round=0; expect +# duration close to 2.0 minutes rather than None or 0. +DURATION_SESSION="$MOCK_PROJECT/.humanize/rlcr/2026-03-01_01-02-03" +mkdir -p "$DURATION_SESSION" +cat > "$DURATION_SESSION/state.md" << 'DSTATE' +--- +session_id: duration-regression +current_round: 0 +max_iterations: 42 +plan_file: plan.md +start_branch: main +status: active +--- +DSTATE +: > "$DURATION_SESSION/round-0-summary.md" +: > "$DURATION_SESSION/round-1-summary.md" +: > "$DURATION_SESSION/round-2-summary.md" +# Stagger mtimes by 120s so duration is ~4.0 minutes total (r0 -> r2). +python3 -c " +import os +base = 1_700_000_000 +for n, offset in ((0, 0), (1, 120), (2, 240)): + path = '$DURATION_SESSION/round-%d-summary.md' % n + os.utime(path, (base + offset, base + offset)) +" + +DURATION_OUTPUT=$(python3 -c " +import sys +sys.path.insert(0, '$SERVER_DIR') +from parser import parse_session +s = parse_session('$DURATION_SESSION') +print('DURATION:', s.get('duration_minutes')) +print('ROUND_COUNT:', len(s.get('rounds', []))) +" 2>&1) + +if echo "$DURATION_OUTPUT" | grep -qE '^DURATION: 4\.0$' && \ + echo "$DURATION_OUTPUT" | grep -qE '^ROUND_COUNT: 3$'; then + pass "Parser: session_duration_minutes spans every on-disk round summary, not only range(current_round+1)" +else + fail "Parser: duration regression (expected 4.0 mins across 3 rounds)" "" "$DURATION_OUTPUT" +fi + +# ======================================== +# Test Group 4: Analyzer Tests +# ======================================== +echo "" +echo "Test Group 4: Analyzer" + +cd "$PLUGIN_ROOT" +ANALYZER_OUTPUT=$(python3 -c " +import sys +sys.path.insert(0, '$SERVER_DIR') +from analyzer import compute_analytics + +# Empty +result = compute_analytics([]) +assert result['overview']['total_sessions'] == 0 +assert result['overview']['completion_rate'] == 0 + +# With mock session +mock = { + 'id': '2026-01-01_12-00-00', + 'current_round': 3, + 'status': 'complete', + 'ac_done': 2, 'ac_total': 4, + 'rounds': [ + {'number': 0, 'verdict': 'advanced', 'review_result': 'some review', 'bitlesson_delta': 'add', 'phase': 'implementation', 'p_issues': {}, 'duration_minutes': 10}, + {'number': 1, 'verdict': 'advanced', 'review_result': 'review 2', 'bitlesson_delta': 'none', 'phase': 'implementation', 'p_issues': {'P1': 1}, 'duration_minutes': 15}, + {'number': 2, 'verdict': 'complete', 'review_result': 'final', 'bitlesson_delta': 'none', 'phase': 'code_review', 'p_issues': {}, 'duration_minutes': 5}, + ] +} +result = compute_analytics([mock]) +assert result['overview']['total_sessions'] == 1 +assert result['overview']['completed_sessions'] == 1 +assert result['overview']['completion_rate'] == 100.0 + +# Verdict distribution should not include rounds without review_result +vd = result['verdict_distribution'] +assert 'advanced' in vd +assert vd['advanced'] == 2 +assert vd.get('unknown', 0) == 0, 'unknown should not appear for reviewed rounds' + +print('ANALYZER_OK') +" 2>&1) + +if echo "$ANALYZER_OUTPUT" | grep -q "ANALYZER_OK"; then + pass "Analyzer: empty sessions" + pass "Analyzer: basic statistics" + pass "Analyzer: verdict distribution excludes non-reviewed rounds" +else + fail "Analyzer tests" "" "$ANALYZER_OUTPUT" +fi + +# ======================================== +# Test Group 5: Exporter Tests +# ======================================== +echo "" +echo "Test Group 5: Exporter" + +EXPORTER_OUTPUT=$(python3 -c " +import sys +sys.path.insert(0, '$SERVER_DIR') +from exporter import export_session_markdown + +mock = { + 'id': '2026-01-01_12-00-00', + 'status': 'complete', + 'current_round': 2, + 'plan_file': 'plan.md', + 'start_branch': 'main', + 'started_at': '2026-01-01T12:00:00Z', + 'codex_model': 'gpt-5.4', + 'last_verdict': 'advanced', + 'ac_total': 2, 'ac_done': 2, + 'rounds': [ + {'number': 0, 'phase': 'implementation', 'verdict': 'unknown', 'duration_minutes': None, + 'bitlesson_delta': 'none', 'summary': {'en': '# Round 0', 'zh': None}, 'review_result': {'en': None, 'zh': None}}, + {'number': 1, 'phase': 'implementation', 'verdict': 'advanced', 'duration_minutes': 15.0, + 'bitlesson_delta': 'add', 'summary': {'en': '# Round 1 done', 'zh': None}, 'review_result': {'en': 'ADVANCED', 'zh': None}}, + ], + 'goal_tracker': { + 'ultimate_goal': 'Test goal', + 'acceptance_criteria': [ + {'id': 'AC-1', 'description': 'First', 'status': 'completed'}, + {'id': 'AC-2', 'description': 'Second', 'status': 'completed'}, + ] + }, + 'methodology_report': {'en': '# Report', 'zh': None}, +} + +md = export_session_markdown(mock) +assert 'RLCR Session Report' in md +assert '2026-01-01_12-00-00' in md +assert 'Round 0' in md +assert 'Round 1 done' in md +assert 'AC-1' in md +assert '# Report' in md +assert isinstance(md, str), 'output must be string, not dict' + +print('EXPORTER_OK') +" 2>&1) + +if echo "$EXPORTER_OUTPUT" | grep -q "EXPORTER_OK"; then + pass "Exporter: generates valid Markdown from bilingual session" + pass "Exporter: handles {zh,en} dicts without TypeError" +else + fail "Exporter tests" "" "$EXPORTER_OUTPUT" +fi + +# ======================================== +# Test Group 6: Integration Markers +# ======================================== +# The early viz plan auto-started a tmux-backed viz daemon whenever +# an RLCR loop ran, threaded through VIZ_AVAILABLE / VIZ_PROJECT +# env markers and viz-stop.sh cleanup hooks in setup-rlcr-loop.sh / +# cancel-rlcr-loop.sh / commands/start-rlcr-loop.md. That auto- +# start path was deprecated in favor of the explicit CLI entry +# point `humanize monitor web --project ` (Round 7), which +# runs the Flask server in the foreground. The RLCR setup/cancel +# scripts no longer need to know about the dashboard — it is now a +# separate terminal the user launches when they want it. +# +# Integration assertions therefore only check that the viz-start +# and viz-stop helpers still exist as importable scripts for the +# opt-in `--daemon` path; they no longer require the setup / +# cancel scripts to reference them. +echo "" +echo "Test Group 6: Integration Markers (opt-in --daemon path)" + +for helper in viz-start.sh viz-stop.sh viz-status.sh; do + if [[ -x "$PLUGIN_ROOT/viz/scripts/$helper" ]]; then + pass "viz helper is present and executable: $helper" + else + fail "viz helper missing: $helper" + fi +done + +# ======================================== +# Test Group 7: humanize monitor web migration +# ======================================== +# The legacy /humanize:viz Claude command and skill have been removed. +# The web dashboard is now reached via the `humanize monitor web` +# subcommand in scripts/humanize.sh. Tests assert both states. +echo "" +echo "Test Group 7: humanize monitor web (replaces /humanize:viz)" + +if [[ ! -f "$PLUGIN_ROOT/commands/viz.md" ]]; then + pass "Legacy /humanize:viz command file is removed" +else + fail "commands/viz.md still exists (should be deleted)" +fi + +if [[ ! -d "$PLUGIN_ROOT/skills/humanize-viz" ]]; then + pass "Legacy humanize-viz skill directory is removed" +else + fail "skills/humanize-viz/ still exists (should be deleted)" +fi + +if grep -q '_humanize_monitor_web' "$PLUGIN_ROOT/scripts/humanize.sh"; then + pass "scripts/humanize.sh defines _humanize_monitor_web function" +else + fail "scripts/humanize.sh missing _humanize_monitor_web function" +fi + +if grep -q 'web)' "$PLUGIN_ROOT/scripts/humanize.sh" && \ + grep -q 'monitor web' "$PLUGIN_ROOT/scripts/humanize.sh"; then + pass "humanize monitor dispatch includes 'web' subcommand" +else + fail "humanize monitor dispatch missing 'web' subcommand" +fi + +if ! grep -q '/humanize:viz' "$PLUGIN_ROOT/commands/start-rlcr-loop.md"; then + pass "commands/start-rlcr-loop.md no longer references /humanize:viz" +else + fail "commands/start-rlcr-loop.md still references /humanize:viz" +fi + +if grep -q 'humanize monitor web' "$PLUGIN_ROOT/README.md"; then + pass "README.md documents humanize monitor web" +else + fail "README.md missing humanize monitor web reference" +fi + +# Round 18 P2: foreground port probe must branch on --host (same +# shape as viz-start.sh find_port) so --host doesn't +# pick a port that is in use on the external interface. +humanize_sh="$PLUGIN_ROOT/scripts/humanize.sh" +if grep -qE 'probe_host=.*"localhost"' "$humanize_sh" && \ + grep -qE 'probe_host="\$host"' "$humanize_sh"; then + pass "humanize.sh foreground monitor-web path branches probe_host on --host (P2 Round 18)" +else + fail "humanize.sh foreground monitor-web path still probes localhost only" +fi + +if grep -qE '/dev/tcp/\$probe_host/\$candidate' "$humanize_sh"; then + pass "humanize.sh foreground port loop uses \$probe_host (no literal localhost)" +else + fail "humanize.sh foreground port loop still uses /dev/tcp/localhost/\$candidate literal" +fi + +# ======================================== +# Test Group 8: Static Assets +# ======================================== +echo "" +echo "Test Group 8: Static Assets" + +for file in index.html css/theme.css css/layout.css js/app.js js/pipeline.js js/actions.js js/i18n.js; do + if [[ -f "$VIZ_DIR/static/$file" ]]; then + pass "Static file exists: $file" + else + fail "Static file missing: $file" + fi +done + +# Verify no hard-coded Chinese in i18n.js (UI should be English-only) +if ! grep -P '[\x{4e00}-\x{9fff}]' "$VIZ_DIR/static/js/i18n.js" >/dev/null 2>&1; then + pass "i18n.js contains no Chinese characters (English-only UI)" +else + fail "i18n.js should not contain Chinese characters" +fi + +# Requirements file +if [[ -f "$VIZ_DIR/server/requirements.txt" ]]; then + pass "Python requirements.txt exists" + if grep -q "flask" "$VIZ_DIR/server/requirements.txt"; then + pass "requirements.txt includes flask" + else + fail "requirements.txt missing flask" + fi +else + fail "Python requirements.txt missing" +fi + +# ======================================== +# Summary +# ======================================== + +print_test_summary "Humanize Viz Tests" diff --git a/viz/scripts/viz-restart.sh b/viz/scripts/viz-restart.sh new file mode 100755 index 00000000..a6c5ee8d --- /dev/null +++ b/viz/scripts/viz-restart.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# Restart the Humanize Viz dashboard server. +# +# Usage: +# viz-restart.sh # legacy positional +# viz-restart.sh --project \ +# [--host ] [--port ] \ +# [--auth-token ] [--trust-proxy] +# +# Every flag the underlying viz-start.sh accepts is forwarded +# verbatim. A plain `viz-restart.sh --project ` still works +# and re-launches with viz-start.sh's defaults (loopback bind, no +# auth); callers that started the daemon with custom --host / +# --port / --auth-token / --trust-proxy must repeat those flags +# here, otherwise the restarted daemon will silently drop back to +# the defaults and the previous access URL / token stop working. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Parse every flag that viz-start.sh understands so restart is a +# true equivalent of stop+start with the same configuration. The old +# implementation only captured --project and silently dropped +# --host / --port / --auth-token / --trust-proxy, which made a +# non-loopback daemon quietly revert to localhost on restart. +PROJECT_DIR="." +HOST="" +PORT="" +AUTH_TOKEN="" +TRUST_PROXY=false +while [[ $# -gt 0 ]]; do + case "$1" in + --project) PROJECT_DIR="$2"; shift 2 ;; + --host) HOST="$2"; shift 2 ;; + --port) PORT="$2"; shift 2 ;; + --auth-token) AUTH_TOKEN="$2"; shift 2 ;; + --trust-proxy) TRUST_PROXY=true; shift ;; + --) shift ;; + *) PROJECT_DIR="$1"; shift ;; + esac +done +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" + +# Rebuild the viz-start argv in a deterministic order so the +# restarted daemon sees exactly the same config the caller gave us. +START_ARGS=(--project "$PROJECT_DIR") +[[ -n "$HOST" ]] && START_ARGS+=(--host "$HOST") +[[ -n "$PORT" ]] && START_ARGS+=(--port "$PORT") +[[ -n "$AUTH_TOKEN" ]] && START_ARGS+=(--auth-token "$AUTH_TOKEN") +[[ "$TRUST_PROXY" == "true" ]] && START_ARGS+=(--trust-proxy) + +bash "$SCRIPT_DIR/viz-stop.sh" --project "$PROJECT_DIR" 2>/dev/null || true +sleep 1 +exec bash "$SCRIPT_DIR/viz-start.sh" "${START_ARGS[@]}" diff --git a/viz/scripts/viz-session-name.sh b/viz/scripts/viz-session-name.sh new file mode 100755 index 00000000..07fb3700 --- /dev/null +++ b/viz/scripts/viz-session-name.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# Per-project tmux session name derivation for the viz dashboard daemon. +# +# Used by viz-start.sh, viz-stop.sh, and viz-status.sh so all three +# resolve the same tmux session name from a project path. Replaces the +# legacy global "humanize-viz" name that allowed one project's daemon to +# kill another project's running server. +# +# Source this file (do not execute) and call viz_tmux_session_name. + +# Returns "humanize-viz-<8-hex>" derived from a stable hash of the +# absolute project path. Tmux session names cannot contain "." or ":" +# so a content-derived hex slug is the safest portable choice. +viz_tmux_session_name() { + local project_dir="$1" + if [[ -z "$project_dir" ]]; then + echo "humanize-viz" + return + fi + # Resolve to absolute path so different invocations (./ vs absolute) + # land on the same session. + if [[ -d "$project_dir" ]]; then + project_dir="$(cd "$project_dir" 2>/dev/null && pwd)" + fi + local hash="" + if command -v sha1sum >/dev/null 2>&1; then + hash=$(printf '%s' "$project_dir" | sha1sum | cut -c1-8) + elif command -v shasum >/dev/null 2>&1; then + hash=$(printf '%s' "$project_dir" | shasum | cut -c1-8) + elif command -v openssl >/dev/null 2>&1; then + hash=$(printf '%s' "$project_dir" | openssl dgst -sha1 | awk '{print $NF}' | cut -c1-8) + else + # Last-resort fallback: sanitize the path itself (matches the + # rule in scripts/humanize.sh and viz/server/rlcr_sources.py). + hash=$(printf '%s' "$project_dir" | sed 's/[^A-Za-z0-9._-]/-/g' | sed 's/--*/-/g' | tr '[:upper:]' '[:lower:]') + # Truncate so the resulting tmux name is not absurdly long. + hash="${hash: -16}" + fi + echo "humanize-viz-${hash}" +} diff --git a/viz/scripts/viz-start.sh b/viz/scripts/viz-start.sh new file mode 100755 index 00000000..ce69f1b0 --- /dev/null +++ b/viz/scripts/viz-start.sh @@ -0,0 +1,255 @@ +#!/usr/bin/env bash +# Launch the Humanize Viz dashboard server in a per-project tmux session. +# +# This script is invoked by the `--daemon` path of `humanize monitor web` +# and may also be run directly. The legacy positional `` form is +# kept for backward compatibility; new callers should use the named flags. +# +# Usage: +# viz-start.sh # legacy +# viz-start.sh --project [--host ] [--port ] \ +# [--auth-token ] # current + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +VIZ_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +REQUIREMENTS="$VIZ_ROOT/server/requirements.txt" +APP_ENTRY="$VIZ_ROOT/server/app.py" +STATIC_DIR="$VIZ_ROOT/static" + +# Source the per-project tmux session naming helper so start/stop/status +# all derive the same name from the project path. +source "$SCRIPT_DIR/viz-session-name.sh" + +# Parse args. Accept legacy positional for backward compat. +PROJECT_DIR="." +HOST="127.0.0.1" +PORT="" +AUTH_TOKEN="" +TRUST_PROXY=false + +while [[ $# -gt 0 ]]; do + case "$1" in + --project) PROJECT_DIR="$2"; shift 2 ;; + --host) HOST="$2"; shift 2 ;; + --port) PORT="$2"; shift 2 ;; + --auth-token) AUTH_TOKEN="$2"; shift 2 ;; + --trust-proxy) TRUST_PROXY=true; shift ;; + -h|--help) + sed -n '2,/^set -euo/p' "$0" | head -n -1 + exit 0 + ;; + --) + shift + ;; + *) + # First non-flag positional is the project dir (legacy form). + PROJECT_DIR="$1" + shift + ;; + esac +done + +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" + +HUMANIZE_DIR="$PROJECT_DIR/.humanize" +VENV_DIR="$HUMANIZE_DIR/viz-venv" +PORT_FILE="$HUMANIZE_DIR/viz.port" +URL_FILE="$HUMANIZE_DIR/viz.url" + +# Per-project tmux session name (T9): each project gets its own slot so +# starting one project's daemon never kills another project's running +# server. The legacy global "humanize-viz" name is gone. +TMUX_SESSION="$(viz_tmux_session_name "$PROJECT_DIR")" + +if [[ ! -d "$HUMANIZE_DIR" ]]; then + echo "Error: No .humanize/ directory found in $PROJECT_DIR" >&2 + echo "This command must be run in a project with humanize initialized." >&2 + exit 1 +fi + +# Reject remote bind without a token before doing any other work. +if [[ "$HOST" != "127.0.0.1" && "$HOST" != "::1" && "$HOST" != "localhost" ]]; then + if [[ -z "$AUTH_TOKEN" && -z "${HUMANIZE_VIZ_TOKEN:-}" ]]; then + echo "Error: --host $HOST requires --auth-token (or HUMANIZE_VIZ_TOKEN)" >&2 + exit 2 + fi +fi + +# If THIS project already has a running server, reuse it. We probe +# the visible URL recorded by a previous viz-start.sh (in viz.url), +# falling back to localhost when only the port file is present +# (older deployments). Probing the configured bind matters because +# `--host 192.168.1.10` does NOT listen on localhost, so a localhost +# probe would mis-detect a healthy server as dead. +if [[ -f "$PORT_FILE" ]]; then + existing_port=$(cat "$PORT_FILE") + if [[ -f "$URL_FILE" ]]; then + existing_url=$(cat "$URL_FILE") + else + existing_url="http://localhost:$existing_port" + fi + if curl -s --max-time 2 "$existing_url/api/health" >/dev/null 2>&1; then + echo "Viz server already running for this project at $existing_url" + exit 0 + fi + rm -f "$PORT_FILE" "$URL_FILE" +fi + +# If THIS project's tmux session already exists but the server is dead, +# clean it up. `=$TMUX_SESSION` forces exact match so we never touch +# an unrelated session whose name happens to share a prefix (or the +# generic "humanize-viz" fallback). +if tmux has-session -t "=$TMUX_SESSION" 2>/dev/null; then + echo "Cleaning up stale tmux session for this project: $TMUX_SESSION" + tmux kill-session -t "=$TMUX_SESSION" 2>/dev/null || true +fi + +# Create venv if it does not exist. +if [[ ! -d "$VENV_DIR" ]]; then + echo "Creating Python virtual environment..." + python3 -m venv "$VENV_DIR" + echo "Installing dependencies..." + "$VENV_DIR/bin/pip" install --quiet -r "$REQUIREMENTS" + echo "Dependencies installed." +elif [[ "$REQUIREMENTS" -nt "$VENV_DIR/.requirements_installed" ]]; then + echo "Updating dependencies..." + if ! "$VENV_DIR/bin/pip" install --quiet -r "$REQUIREMENTS"; then + # Leave the marker untouched so the next launch retries the + # upgrade instead of silently starting with missing packages. + echo "Error: pip install failed during dependency refresh" >&2 + exit 1 + fi + touch "$VENV_DIR/.requirements_installed" +fi +touch "$VENV_DIR/.requirements_installed" + +# Pick a port if not specified. Per-project port file means parallel +# projects do not collide. +# +# The probe host must match what Flask's app.run() will actually try +# to bind. Loopback aliases and wildcard binds (0.0.0.0, ::) are +# safe to probe via localhost because wildcards also listen on the +# loopback interface, so a localhost probe catches conflicts there. +# But a specific non-loopback bind (e.g. 192.168.1.10) does NOT +# listen on localhost, so a localhost-only probe would report a +# port as free even when another service owns it on the external +# interface — and then app.run would die with EADDRINUSE. Probing +# the configured host directly makes remote mode startup reliable. +find_port() { + local probe_host + case "$HOST" in + 127.0.0.1|::1|localhost|0.0.0.0|::) + probe_host="localhost" + ;; + *) + probe_host="$HOST" + ;; + esac + for candidate in $(seq 18000 18099); do + if ! (echo >/dev/tcp/$probe_host/$candidate) 2>/dev/null; then + echo "$candidate" + return 0 + fi + done + echo "Error: No available port in range 18000-18099" >&2 + return 1 +} + +if [[ -z "$PORT" ]]; then + PORT=$(find_port) +fi +echo "$PORT" > "$PORT_FILE" + +# Persist the visible URL so viz-status.sh / viz-stop.sh and the +# stale-port path above can probe the right host. Loopback binds +# expose the dashboard at localhost; non-loopback binds expose it at +# the configured host (the actual address browsers will reach). +visible_host_for_url="$HOST" +case "$HOST" in + 127.0.0.1|::1|localhost|0.0.0.0|::) + # All loopback aliases AND the wildcard binds are reachable via + # localhost from this machine, so probe localhost for the + # liveness check. Wildcard binds also listen on the loopback + # interface, so this is correct (and avoids needing to know + # which external interface to probe). + visible_host_for_url="localhost" + ;; +esac +# RFC 3986 requires IPv6 addresses to be bracketed in URLs so the +# port separator is unambiguous. Without this, curl, browsers, and +# viz-status.sh all treat `http://:` as an invalid URL +# because the trailing `:` fragments of the address collide with +# the port separator. Loopback/wildcard binds already collapsed to +# "localhost" above (no colon), so this only wraps specific IPv6 +# addresses and is a no-op for IPv4/localhost. +case "$visible_host_for_url" in + *:*) + visible_host_for_url="[${visible_host_for_url}]" + ;; +esac +echo "http://${visible_host_for_url}:${PORT}" > "$URL_FILE" + +# Build the python command, forwarding every flag. +PY_ARGS=( + "$VENV_DIR/bin/python" "$APP_ENTRY" + --host "$HOST" + --port "$PORT" + --project "$PROJECT_DIR" + --static "$STATIC_DIR" +) +if [[ -n "$AUTH_TOKEN" ]]; then + PY_ARGS+=(--auth-token "$AUTH_TOKEN") +fi +if [[ "$TRUST_PROXY" == "true" ]]; then + PY_ARGS+=(--trust-proxy) +fi + +# Launch in the per-project tmux session. +tmux new-session -d -s "$TMUX_SESSION" "${PY_ARGS[@]}" + +visible_host="$HOST" +[[ "$HOST" == "127.0.0.1" || "$HOST" == "::1" ]] && visible_host="localhost" +echo "Viz server starting on http://${visible_host}:${PORT}" + +# Readiness probe against the canonical URL we just wrote to viz.url. +# Probing "localhost" here would lie for --host daemons +# (a healthy server never answers on localhost for those binds), and +# a process that dies on startup would also sail through unnoticed, +# leaving stale viz.port / viz.url + a misleading "ready" banner. +# Track whether any probe succeeded so the launcher can fail closed +# when the server never becomes reachable. +probe_url=$(cat "$URL_FILE") +ready="false" +for _ in $(seq 1 10); do + if curl -s --max-time 1 "$probe_url/api/health" >/dev/null 2>&1; then + ready="true" + break + fi + sleep 0.5 +done + +if [[ "$ready" != "true" ]]; then + echo "Error: viz dashboard did not become reachable at $probe_url within 5s." >&2 + echo "Inspect the tmux session for startup errors: tmux attach -t $TMUX_SESSION" >&2 + rm -f "$PORT_FILE" "$URL_FILE" + exit 1 +fi + +# Open browser only when binding to the local machine. +if [[ "$HOST" == "127.0.0.1" || "$HOST" == "::1" || "$HOST" == "localhost" ]]; then + if command -v xdg-open &>/dev/null; then + xdg-open "http://localhost:$PORT" 2>/dev/null & + elif command -v open &>/dev/null; then + open "http://localhost:$PORT" 2>/dev/null & + elif command -v wslview &>/dev/null; then + wslview "http://localhost:$PORT" 2>/dev/null & + else + echo "Open http://localhost:$PORT in your browser." + fi +fi + +echo "Viz dashboard is ready at http://${visible_host}:${PORT}" +echo "Tmux session for this project: $TMUX_SESSION" +echo "Run 'viz-stop.sh --project $PROJECT_DIR' to stop the dashboard." diff --git a/viz/scripts/viz-status.sh b/viz/scripts/viz-status.sh new file mode 100755 index 00000000..5afb9733 --- /dev/null +++ b/viz/scripts/viz-status.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Check the status of the Humanize Viz dashboard server for one project. +# +# Per-project tmux session names (T9) mean checking one project's +# dashboard never affects another project's running server. +# +# Usage: +# viz-status.sh # legacy positional +# viz-status.sh --project # current named flag + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/viz-session-name.sh" + +PROJECT_DIR="." +while [[ $# -gt 0 ]]; do + case "$1" in + --project) PROJECT_DIR="$2"; shift 2 ;; + --) shift ;; + *) PROJECT_DIR="$1"; shift ;; + esac +done +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" + +HUMANIZE_DIR="$PROJECT_DIR/.humanize" +PORT_FILE="$HUMANIZE_DIR/viz.port" +URL_FILE="$HUMANIZE_DIR/viz.url" +TMUX_SESSION="$(viz_tmux_session_name "$PROJECT_DIR")" + +if [[ -f "$PORT_FILE" ]]; then + port=$(cat "$PORT_FILE") + # Probe the URL recorded by viz-start.sh (which knows the + # configured bind), falling back to localhost when only the legacy + # port file is present. This is what makes `--host 192.168.1.10` + # deployments work — without it the localhost probe would reject + # a healthy server as dead and tear down the session. + if [[ -f "$URL_FILE" ]]; then + probe_url=$(cat "$URL_FILE") + else + probe_url="http://localhost:$port" + fi + if curl -s --max-time 2 "$probe_url/api/health" >/dev/null 2>&1; then + echo "Viz server running for project $PROJECT_DIR at $probe_url" + exit 0 + fi + # Stale port file for THIS project only. + echo "Viz server is not running for project: $PROJECT_DIR (stale port file, cleaning up)." + rm -f "$PORT_FILE" "$URL_FILE" + # Use tmux's `=name` exact-match form so a generic "humanize-viz" + # session name never accidentally matches a longer per-project + # name (or vice versa). Project-specific names derived by + # viz_tmux_session_name already carry an 8-hex suffix; the + # exact-match syntax makes the intent explicit and robust. + if tmux has-session -t "=$TMUX_SESSION" 2>/dev/null; then + tmux kill-session -t "=$TMUX_SESSION" 2>/dev/null || true + fi + exit 1 +fi + +echo "Viz server is not running for project: $PROJECT_DIR" +exit 1 diff --git a/viz/scripts/viz-stop.sh b/viz/scripts/viz-stop.sh new file mode 100755 index 00000000..8b49aebb --- /dev/null +++ b/viz/scripts/viz-stop.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Stop the Humanize Viz dashboard server for one project. +# +# Per-project tmux session names (T9) mean stopping one project's +# dashboard never touches another project's running server. +# +# Usage: +# viz-stop.sh # legacy positional +# viz-stop.sh --project # current named flag + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/viz-session-name.sh" + +PROJECT_DIR="." +while [[ $# -gt 0 ]]; do + case "$1" in + --project) PROJECT_DIR="$2"; shift 2 ;; + --) shift ;; + *) PROJECT_DIR="$1"; shift ;; + esac +done +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" + +HUMANIZE_DIR="$PROJECT_DIR/.humanize" +PORT_FILE="$HUMANIZE_DIR/viz.port" +URL_FILE="$HUMANIZE_DIR/viz.url" +TMUX_SESSION="$(viz_tmux_session_name "$PROJECT_DIR")" + +# `=$TMUX_SESSION` forces exact match so prefix collisions (or the +# generic "humanize-viz" fallback name) cannot cause an unrelated +# session to be killed. +if tmux has-session -t "=$TMUX_SESSION" 2>/dev/null; then + tmux kill-session -t "=$TMUX_SESSION" + rm -f "$PORT_FILE" "$URL_FILE" + echo "Viz server stopped for project: $PROJECT_DIR" +else + rm -f "$PORT_FILE" "$URL_FILE" + echo "Viz server is not running for project: $PROJECT_DIR" +fi diff --git a/viz/server/analyzer.py b/viz/server/analyzer.py new file mode 100644 index 00000000..e7d564d6 --- /dev/null +++ b/viz/server/analyzer.py @@ -0,0 +1,182 @@ +"""Cross-session analytics for RLCR loop data. + +Computes statistics across multiple sessions: efficiency metrics, +quality indicators, verdict distributions, and BitLesson growth. +""" + +import time + + +def _rounds_per_day(sessions, window_days=14): + """Return a ``window_days``-length list of rounds-completed-per-day. + + Buckets round-complete timestamps (the round's summary mtime) into + calendar days anchored at the current local midnight, so the + tail entry always represents "today" and the head entry is + ``window_days - 1`` days ago. Consumed by the home-page analytics + strip to drive a compact sparkline. + """ + if window_days <= 0: + return [] + now = time.time() + # Anchor bucket boundaries at local midnight for stable day-aligned + # buckets regardless of call time. + tm_today = time.localtime(now) + midnight_today = time.mktime(time.struct_time(( + tm_today.tm_year, tm_today.tm_mon, tm_today.tm_mday, + 0, 0, 0, 0, 0, tm_today.tm_isdst, + ))) + earliest = midnight_today - (window_days - 1) * 86400 + + buckets = [0] * window_days + for s in sessions: + for r in s.get('rounds', []): + ts = r.get('summary_mtime') + if ts is None or ts < earliest: + continue + # Offset from the earliest bucket's midnight; floor-div to + # the matching bucket index (clamped to the window tail + # for timestamps that fall on or after today's midnight). + idx = int((ts - earliest) // 86400) + if idx < 0: + continue + if idx >= window_days: + idx = window_days - 1 + buckets[idx] += 1 + return buckets + + +def compute_analytics(sessions): + """Compute cross-session statistics from a list of parsed sessions.""" + if not sessions: + return _empty_analytics() + + total = len(sessions) + completed = sum(1 for s in sessions if s['status'] == 'complete') + # ``current_round`` is a 0-based *index*, not a count — a session + # that has finished round 0 reports ``current_round=0`` with one + # entry in ``s['rounds']``. Use the rounds list length (which the + # parser builds from ``range(max_disk_round + 1)``) so + # ``overview.average_rounds`` and the per-session ``rounds`` field + # reflect the true count. The prior ``current_round > 0`` filter + # also wrongly excluded single-round sessions, further skewing + # the average; drop the filter and accept any session that has + # at least one round entry. + rounds_counts = [len(s.get('rounds') or []) for s in sessions] + rounds_counts = [n for n in rounds_counts if n > 0] + avg_rounds = round(sum(rounds_counts) / len(rounds_counts), 1) if rounds_counts else 0 + rounds_per_day = _rounds_per_day(sessions, window_days=14) + + # Verdict distribution — only count rounds that have an actual review result + verdict_counts = {'advanced': 0, 'stalled': 0, 'regressed': 0, 'complete': 0} + for s in sessions: + for r in s['rounds']: + if r.get('review_result') is None: + continue + v = r.get('verdict', 'unknown') + if v != 'unknown': + verdict_counts[v] = verdict_counts.get(v, 0) + 1 + + # P0-P9 distribution + p_distribution = {} + for s in sessions: + for r in s['rounds']: + for level, count in r.get('p_issues', {}).items(): + p_distribution[level] = p_distribution.get(level, 0) + count + + # Per-session stats for charts + session_stats = [] + cumulative_bitlesson = 0 + bitlesson_growth = [] + + for s in sessions: + # Same 0-based-index fix as the overview above: use the parsed + # rounds list so a session with only round 0 still reports + # ``rounds=1`` instead of 0. + rounds_count = len(s.get('rounds') or []) + + # Average round duration + durations = [r['duration_minutes'] for r in s['rounds'] if r.get('duration_minutes')] + avg_duration = round(sum(durations) / len(durations), 1) if durations else None + + # First COMPLETE round + first_complete = None + for r in s['rounds']: + if r.get('verdict') == 'complete': + first_complete = r['number'] + break + + # Rework count (rounds after review phase started) + rework = 0 + in_review = False + for r in s['rounds']: + if r.get('phase') == 'code_review': + in_review = True + if in_review: + rework += 1 + + # Verdict breakdown for this session + sv = {'advanced': 0, 'stalled': 0, 'regressed': 0} + for r in s['rounds']: + v = r.get('verdict', '') + if v in sv: + sv[v] += 1 + + # BitLesson count + bl_count = sum(1 for r in s['rounds'] if r.get('bitlesson_delta') in ('add', 'update')) + cumulative_bitlesson += bl_count + + bitlesson_growth.append({ + 'session_id': s['id'], + 'cumulative': cumulative_bitlesson, + 'delta': bl_count, + }) + + session_stats.append({ + 'session_id': s['id'], + 'status': s['status'], + 'rounds': rounds_count, + 'avg_duration_minutes': avg_duration, + 'first_complete_round': first_complete, + 'rework_count': rework, + 'ac_completion_rate': round(s['ac_done'] / s['ac_total'] * 100, 1) if s['ac_total'] > 0 else 0, + 'verdict_breakdown': sv, + }) + + # Total BitLessons (count from bitlesson.md if available, else estimate) + total_bitlessons = cumulative_bitlesson + + return { + 'overview': { + 'total_sessions': total, + 'completed_sessions': completed, + 'completion_rate': round(completed / total * 100, 1) if total > 0 else 0, + 'average_rounds': avg_rounds, + 'total_bitlessons': total_bitlessons, + 'rounds_per_day': rounds_per_day, + 'rounds_per_day_window': 14, + }, + 'verdict_distribution': verdict_counts, + 'p_distribution': p_distribution, + 'session_stats': session_stats, + 'bitlesson_growth': bitlesson_growth, + } + + +def _empty_analytics(): + """Return empty analytics structure.""" + return { + 'overview': { + 'total_sessions': 0, + 'completed_sessions': 0, + 'completion_rate': 0, + 'average_rounds': 0, + 'total_bitlessons': 0, + 'rounds_per_day': [0] * 14, + 'rounds_per_day_window': 14, + }, + 'verdict_distribution': {}, + 'p_distribution': {}, + 'session_stats': [], + 'bitlesson_growth': [], + } diff --git a/viz/server/app.py b/viz/server/app.py new file mode 100644 index 00000000..10a6721b --- /dev/null +++ b/viz/server/app.py @@ -0,0 +1,1734 @@ +"""Humanize Viz — Flask application. + +Serves the SPA frontend, REST API for session data, and WebSocket +for real-time file change notifications. +""" + +import os +import re +import sys +import json +import time +import argparse +import subprocess +import threading +from flask import Flask, Response, jsonify, request, send_from_directory, abort +from flask_sock import Sock +from werkzeug.utils import safe_join + +# Add server directory to path +sys.path.insert(0, os.path.dirname(__file__)) +from parser import list_sessions, parse_session, read_plan_file, is_valid_session +from analyzer import compute_analytics +from exporter import export_session_markdown +from watcher import SessionWatcher, CacheLogWatcher +import rlcr_sources +import log_streamer + +app = Flask(__name__, static_folder=None) +sock = Sock(app) + +# Global state +PROJECT_DIR = '.' +STATIC_DIR = '.' +BIND_HOST = '127.0.0.1' +AUTH_TOKEN = '' +# Set by main() when `--trust-proxy` (or HUMANIZE_VIZ_TRUST_PROXY=1) +# is supplied. Acknowledges that a TLS-terminating reverse proxy is +# in front of the server, which lets the CSRF host/port matcher +# honor `X-Forwarded-Proto` for scheme-based port resolution. +# Localhost-bound dev mode always leaves this False so attacker- +# supplied `X-Forwarded-Proto` headers cannot trick a direct- +# connect dashboard into thinking it's HTTPS. +TRUST_PROXY = False +_session_cache = {} +_cache_lock = threading.Lock() +_ws_clients = set() +_ws_lock = threading.Lock() +_watcher = None + + +def _is_localhost_bind(): + """Return True when the server is bound to a loopback interface.""" + return BIND_HOST in ('127.0.0.1', '::1', 'localhost') + + +def _request_token(): + """Extract the bearer token from an incoming Flask request. + + Honors both the standard ``Authorization: Bearer `` header (used + by the SPA's ``fetch`` calls) and the ``?token=`` query parameter + (used by the SSE ``EventSource`` client because browsers cannot set + arbitrary headers on EventSource). + """ + auth_header = request.headers.get('Authorization', '') + if auth_header.startswith('Bearer '): + token = auth_header[len('Bearer '):].strip() + if token: + return token + return request.args.get('token', '').strip() + + +def _request_authorized(): + """True iff the current request may access protected endpoints. + + Fail-closed defense-in-depth: ``main()`` refuses to start a + non-loopback bind without a token, but any code path that skips + ``main()`` (module import plus a bespoke ``app.run`` wrapper, a + future test harness, an alternate entry point) would otherwise + pass every request through. Treat an empty AUTH_TOKEN on a + non-loopback bind as "no credential was configured, deny" rather + than "no credential was configured, allow". + """ + if _is_localhost_bind(): + return True + if not AUTH_TOKEN: + return False + return _request_token() == AUTH_TOKEN + + +def _get_rlcr_dir(): + return os.path.join(PROJECT_DIR, '.humanize', 'rlcr') + + +# Session ids flow into the frontend's inline onclick template +# literals: +# onclick="navigate('#/session/${s.id}')" +# onclick="opsPreviewIssue('${s.id}')" +# so any id containing a JS-string metacharacter (quote, backtick, +# backslash, angle bracket, newline, etc.) would let hostile disk +# state break out of the surrounding string and inject script. +# setup-rlcr-loop.sh generates ids that match +# `YYYY-MM-DD_HH-MM-SS`, but some test fixtures and legacy +# recoveries use simpler slugs like `2026-04-17_CL`. Accept the +# full superset of safe characters (ASCII letters, digits, +# underscore, dash, period — with extra rules rejecting `..`, +# leading-dot, and path separators) so those still work while +# every character outside that set is refused up-front. +_SESSION_ID_RE = re.compile(r'^[A-Za-z0-9_.\-]+$') + + +def _is_safe_session_id(session_id): + """Return True iff ``session_id`` only uses the safe alphabet. + + Rejects anything with path separators, parent-traversal + markers, leading dots, or characters that could escape a JS + string literal in the frontend's inline onclick handlers. + """ + if not session_id or len(session_id) > 128: + return False + if session_id in ('.', '..') or session_id.startswith('.'): + return False + if '/' in session_id or '\\' in session_id: + return False + return bool(_SESSION_ID_RE.match(session_id)) + + +def _get_session_dir(session_id): + """Resolve a session_id to its on-disk directory, or None. + + Defense-in-depth path validation: every session-scoped route + (detail, plan, report, generate-report, cancel, SSE log stream) + passes a user-controlled session_id through here. Without these + checks a request like `/api/sessions/..` would resolve to + `.humanize/..` = the project's `.humanize/` parent, and any + stray directory under `.humanize/rlcr` (e.g. a `cache/` dir) + would bypass the 404 contract and let downstream parsers read + arbitrary files. + + Reject: + - session_id that does not match the canonical + ``YYYY-MM-DD_HH-MM-SS`` shape (covers path separators, `..`, + dotfiles, and anything that could escape from a JS string + literal in the frontend's inline onclick handlers) + - candidates that resolve outside the RLCR dir after + realpath normalisation (defense against symlink escapes) + - directories that exist but are not actually RLCR sessions + (parser.is_valid_session requires state.md or a terminal + *-state.md file) + """ + if not _is_safe_session_id(session_id): + return None + rlcr_dir = _get_rlcr_dir() + candidate = os.path.join(rlcr_dir, session_id) + if not os.path.isdir(candidate): + return None + # Resolve both sides to compare against symlinks. The candidate + # must still live under the rlcr dir after normalisation. + try: + rlcr_real = os.path.realpath(rlcr_dir) + cand_real = os.path.realpath(candidate) + except (OSError, ValueError): + return None + rlcr_prefix = rlcr_real.rstrip(os.sep) + os.sep + if not cand_real.startswith(rlcr_prefix): + return None + if not is_valid_session(candidate): + return None + return candidate + + +def _get_session(session_id, force_refresh=False): + """Get session data with caching.""" + with _cache_lock: + if not force_refresh and session_id in _session_cache: + return _session_cache[session_id] + + session_dir = _get_session_dir(session_id) + if not session_dir: + return None + + session = parse_session(session_dir) + with _cache_lock: + _session_cache[session_id] = session + return session + + +def _invalidate_cache(session_id=None): + """Invalidate cache for a session or all sessions.""" + with _cache_lock: + if session_id: + _session_cache.pop(session_id, None) + else: + _session_cache.clear() + + +def broadcast_message(message): + """Send a message to all connected WebSocket clients.""" + dead = set() + with _ws_lock: + clients = set(_ws_clients) + + for ws in clients: + try: + ws.send(message) + except Exception: + dead.add(ws) + + if dead: + with _ws_lock: + # Mutate in-place via difference_update instead of `-=`. + # `_ws_clients -= dead` would rebind the name, which makes + # Python treat `_ws_clients` as a function-local variable + # throughout broadcast_message and raise UnboundLocalError + # at the earlier `set(_ws_clients)` read. + _ws_clients.difference_update(dead) + + # Invalidate cache for the affected session + try: + data = json.loads(message) + _invalidate_cache(data.get('session_id')) + except (json.JSONDecodeError, AttributeError): + pass + + +# --- Auth middleware (T11) --- + +# Endpoints that remain reachable without a token even in remote mode. +# The static SPA shell and the health probe must stay open so the +# browser can fetch index.html and report liveness; everything else +# (session data, SSE streams, mutators) is gated. +_AUTH_OPEN_PREFIXES = ('/api/health',) + + +def _is_open_path(path): + if path == '/' or not path.startswith('/api/'): + # Static asset path served by the SPA fallback. + return True + for prefix in _AUTH_OPEN_PREFIXES: + if path.startswith(prefix): + return True + return False + + +_MUTATING_METHODS = frozenset({'POST', 'PUT', 'PATCH', 'DELETE'}) + +_LOOPBACK_HOSTS = frozenset({'localhost', '127.0.0.1', '::1'}) + + +def _default_port_for_scheme(scheme): + return 443 if scheme == 'https' else 80 + + +def _effective_request_scheme(): + """Return the wire-level scheme the browser actually used. + + Behind a TLS-terminating reverse proxy (the `--trust-proxy` + deployment mode), Flask sees the back-channel request as plain + HTTP — `request.scheme` is `http`, so the default-port lookup + below would collapse to 80 even though the browser spoke to the + proxy on 443. That mismatch turns every browser Origin of + `https://host` into a 403 at `_origin_matches_request()` because + the computed request port (80) differs from the origin port + (443), which in turn blocks cancel / generate-report / GitHub- + issue submissions in the standard HTTPS-behind-proxy deployment. + + When `TRUST_PROXY` is True, honor `X-Forwarded-Proto` + (populated by every reasonable reverse proxy) for scheme + resolution so the default-port calculation lines up with the + browser's view. Anything other than explicit `https` falls back + to Flask's own `request.scheme` so HTTP proxy deployments keep + working. When `TRUST_PROXY` is False we ignore the header + entirely — otherwise an attacker on a direct-connect localhost + dashboard could flip our scheme view with a crafted header. + """ + if TRUST_PROXY: + forwarded = (request.headers.get('X-Forwarded-Proto') or '').strip().lower() + # Some proxies comma-separate when multiple hops exist; the + # first entry is the one the client hit. + if forwarded: + forwarded = forwarded.split(',', 1)[0].strip() + if forwarded == 'https': + return 'https' + if forwarded == 'http': + return 'http' + return request.scheme + + +def _parse_request_host_port(): + """Return ``(host, port)`` for the current request's Host header. + + ``request.host`` is the value the browser actually used to reach + the dashboard (e.g. ``server.example.com:18000``), which may + differ from the configured ``BIND_HOST`` in wildcard deployments + such as ``--host 0.0.0.0``. Same-origin checks must compare + against this value, not against the bind, so remote browsers can + actually issue cross-host writes. + + IPv6 hosts in HTTP Host headers are bracketed per RFC 7230 + (``[::1]:18000`` for the loopback bind), but ``urlparse(Origin) + .hostname`` returns the unbracketed form (``::1``). Strip the + brackets after the host/port split so the comparison matches. + """ + scheme = _effective_request_scheme() + raw = (request.host or '').lower() + if not raw: + return ('', _default_port_for_scheme(scheme)) + if ':' in raw and not raw.endswith(']'): + host, port_str = raw.rsplit(':', 1) + try: + port = int(port_str) + except ValueError: + port = _default_port_for_scheme(scheme) + else: + host = raw + port = _default_port_for_scheme(scheme) + if host.startswith('[') and host.endswith(']'): + host = host[1:-1] + return (host, port) + + +def _origin_matches_request(origin_value): + """True when ``origin_value`` points at the same host:port the + browser actually used for this request. + + Comparing to the request's own ``Host`` header (rather than the + configured ``BIND_HOST``) is what lets ``--host 0.0.0.0`` remote + deployments work: the bind is a wildcard but the browser sends + the machine's real hostname, so a literal-bind comparison would + reject every cross-host POST as cross-origin. Loopback aliases + (localhost/127.0.0.1/::1) are treated as equivalent so the user + is not pinned to whichever alias they happened to type. + """ + if not origin_value: + return False + try: + from urllib.parse import urlparse + parsed = urlparse(origin_value) + except Exception: + return False + if parsed.scheme not in ('http', 'https'): + return False + origin_host = (parsed.hostname or '').lower() + if not origin_host: + return False + # ``urlparse`` succeeds for malformed Origin values like + # ``http://host:bad`` or ``http://host:999999``; the port is only + # validated when ``.port`` is accessed, which raises ValueError. + # Treat such values as non-matching so ``_enforce_csrf_protection`` + # returns a controlled 403 instead of letting the exception bubble + # up as a 500. + try: + origin_port = parsed.port or _default_port_for_scheme(parsed.scheme) + except ValueError: + return False + + request_host, request_port = _parse_request_host_port() + if origin_port != request_port: + return False + if origin_host in _LOOPBACK_HOSTS and request_host in _LOOPBACK_HOSTS: + return True + return origin_host == request_host + + +def _enforce_csrf_protection(): + """Reject cross-origin writes regardless of bind / auth posture. + + Remote-mode deployments are still further gated by the auth + middleware (token check); CSRF is layered on top so a stolen + token cannot be exploited from an arbitrary origin either. + Localhost binds were the original gap Codex flagged: without this + layer, any webpage open in the same browser could POST to + 127.0.0.1: mutating endpoints. + """ + if request.method not in _MUTATING_METHODS: + return None + if _is_open_path(request.path): + return None + origin = request.headers.get('Origin', '').strip() + referer = request.headers.get('Referer', '').strip() + if origin: + if _origin_matches_request(origin): + return None + return jsonify({'error': 'cross-origin write rejected'}), 403 + if referer: + if _origin_matches_request(referer): + return None + return jsonify({'error': 'cross-origin write rejected'}), 403 + # No Origin AND no Referer header: browsers always set at least + # one of them on cross-site form/fetch POSTs, so the absence + # almost certainly means the request came from a same-origin + # script that suppressed both, a server-to-server tool such as + # curl, or our own Flask test_client. Allow it; the auth layer + # still gates remote requests via token. + return None + + +@app.before_request +def _enforce_auth_and_csrf(): + """Combined auth + CSRF gate. + + Order matters: the CSRF layer runs first so cross-origin writes + are rejected even if the request happens to carry a valid token + (defense in depth). The auth layer then enforces the bearer + token in remote mode for every protected endpoint. + """ + csrf_response = _enforce_csrf_protection() + if csrf_response is not None: + return csrf_response + if _is_localhost_bind(): + return None + if _is_open_path(request.path): + return None + if _request_authorized(): + return None + return jsonify({'error': 'unauthorized'}), 401 + + +# --- Static file serving --- + +@app.route('/') +def index(): + return send_from_directory(STATIC_DIR, 'index.html') + + +@app.route('/') +def static_files(path): + if path.startswith('api/'): + abort(404) + # Reject traversal / absolute paths BEFORE probing the filesystem. + # The earlier implementation did ``os.path.isfile(os.path.join( + # STATIC_DIR, path))`` for any client-supplied ``path``, which + # turned an intentionally-open endpoint into an unauthenticated + # filesystem-existence oracle: a request containing ``..`` + # segments took the ``send_from_directory`` branch (404) when the + # target existed, but fell through to the SPA fallback (200) when + # it did not. Werkzeug's ``safe_join`` returns ``None`` for any + # path that would escape STATIC_DIR, so we skip the probe entirely + # in that case and go straight to the SPA fallback — the response + # is identical whether the traversal target existed or not. + safe_path = safe_join(STATIC_DIR, path) + if safe_path is not None and os.path.isfile(safe_path): + return send_from_directory(STATIC_DIR, path) + # SPA fallback + return send_from_directory(STATIC_DIR, 'index.html') + + +# --- Health check --- + +@app.route('/api/health') +def health(): + return jsonify({'status': 'ok'}) + + +# --- Project Listing (read-only; CLI-fixed single-project model per DEC-3) --- +# +# T10 backend cleanup: the legacy server-global project switcher (which +# allowed any client to mutate PROJECT_DIR for ALL connected clients +# and persisted to ~/.humanize/viz-projects.json) has been removed in +# favor of one server per project. Project selection is now CLI-fixed +# at startup via `humanize monitor web --project `. The +# read-only /api/projects endpoint stays for frontend compatibility +# during the Round 5 UI refactor; it returns ONLY the project the +# server was started with and never mutates the projects file. + + +@app.route('/api/projects') +def api_projects(): + rlcr_dir = os.path.join(PROJECT_DIR, '.humanize', 'rlcr') + session_count = 0 + if os.path.isdir(rlcr_dir): + session_count = len([ + d for d in os.listdir(rlcr_dir) + if os.path.isdir(os.path.join(rlcr_dir, d)) + ]) + return jsonify([ + { + 'path': PROJECT_DIR, + 'name': os.path.basename(PROJECT_DIR), + 'sessions': session_count, + 'active': True, + 'cli_fixed': True, + } + ]) + + +_CANCELLABLE_STATUSES = frozenset({'active', 'analyzing', 'finalizing'}) + + +_REMOVED_PROJECT_ENDPOINT_BODY = { + 'error': 'project switching is no longer supported; run `humanize monitor web --project ` per project', + 'replacement': 'humanize monitor web --project ', +} + + +@app.route('/api/projects/switch', methods=['POST']) +@app.route('/api/projects/add', methods=['POST']) +@app.route('/api/projects/remove', methods=['POST']) +def api_projects_removed(): + return jsonify(_REMOVED_PROJECT_ENDPOINT_BODY), 410 + + +# --- REST API --- + +@app.route('/api/sessions') +def api_sessions(): + sessions = list_sessions(PROJECT_DIR) + # Return summary-level data (no full round content). cache_logs is + # included because the home-page multi-session live-pane feature + # needs it to pick a log filename and open the SSE stream; without + # it every active card degrades to the WAITING state regardless of + # whether cache logs actually exist. + # + # Filter out any on-disk directory whose name does not match the + # canonical session-id shape before emitting. This is the second + # line of defence for the inline-onclick XSS vector Codex flagged + # — a session directory created by hand with a name like + # `2026-04-18_00-34-17'); alert(1); //` should never reach the + # frontend where `onclick="navigate('#/session/${s.id}')"` would + # break out of the JS string. + summaries = [] + for s in sessions: + if not _is_safe_session_id(s.get('id', '')): + continue + summaries.append({ + 'id': s['id'], + 'status': s['status'], + 'current_round': s['current_round'], + 'max_iterations': s['max_iterations'], + 'full_review_round': s.get('full_review_round'), + 'plan_file': s['plan_file'], + 'start_branch': s['start_branch'], + 'started_at': s['started_at'], + 'last_verdict': s['last_verdict'], + 'drift_status': s['drift_status'], + # Extra state fields so the home-page active card can + # match the `humanize monitor rlcr` status bar line-for-line + # without forcing clients to hit /api/sessions/. + 'codex_model': s.get('codex_model', ''), + 'codex_effort': s.get('codex_effort', ''), + 'ask_codex_question': s.get('ask_codex_question', False), + 'review_started': s.get('review_started', False), + 'agent_teams': s.get('agent_teams', False), + 'push_every_round': s.get('push_every_round', False), + 'mainline_stall_count': s.get('mainline_stall_count', 0), + 'last_mainline_verdict': s.get('last_mainline_verdict', 'unknown'), + 'build_finish_round': s.get('build_finish_round'), + 'skip_impl': s.get('skip_impl', False), + 'tasks_done': s['tasks_done'], + 'tasks_total': s['tasks_total'], + 'tasks_active': s.get('tasks_active', 0), + 'tasks_deferred': s.get('tasks_deferred', 0), + 'ac_done': s['ac_done'], + 'ac_total': s['ac_total'], + 'ultimate_goal': s.get('ultimate_goal', ''), + 'duration_minutes': s.get('duration_minutes'), + 'cache_logs': s.get('cache_logs') or [], + 'active_log_path': s.get('active_log_path', ''), + 'git_status': s.get('git_status'), + }) + return jsonify(summaries) + + +@app.route('/api/sessions/') +def api_session_detail(session_id): + session = _get_session(session_id) + if not session: + abort(404) + return jsonify(session) + + +@app.route('/api/sessions//plan') +def api_session_plan(session_id): + session_dir = _get_session_dir(session_id) + if not session_dir: + abort(404) + plan = read_plan_file(session_dir, PROJECT_DIR) + if plan is None: + abort(404) + return jsonify({'content': plan}) + + +@app.route('/api/sessions//report') +def api_session_report(session_id): + session = _get_session(session_id) + if not session: + abort(404) + report = session.get('methodology_report') + # parse_session always populates methodology_report via + # _to_bilingual, which returns {'zh': None, 'en': None} when no + # report file exists. The previous `if not report:` never fired + # because that dict is truthy, so the route returned 200 with an + # empty payload and clients couldn't distinguish "report missing" + # from "report loaded successfully but empty". Require at least + # one of zh / en to carry content before returning 200. + if not isinstance(report, dict) or not (report.get('zh') or report.get('en')): + abort(404) + return jsonify({'content': report}) + + +@app.route('/api/analytics') +def api_analytics(): + # Drop any on-disk session whose directory name does not match + # the canonical shape before feeding it into the analyzer. The + # Analytics page's comparison table renders ``session_id`` into + # an inline ``onclick="navigate('#/session/${id}')"`` template + # and cell HTML; without this filter a crafted directory name + # containing quote/JS metacharacters would reach the browser + # and could break out of the attribute or inject script, which + # is the exact vector ``/api/sessions`` already guards against. + # Matching the same filter here keeps both surfaces consistent. + sessions = [ + s for s in list_sessions(PROJECT_DIR) + if _is_safe_session_id(s.get('id', '')) + ] + analytics = compute_analytics(sessions) + return jsonify(analytics) + + +def _report_is_stale(session_dir, report_path): + """True when the on-disk methodology report predates any round + summary / review-result under ``session_dir``. + + The cached report was generated against an earlier snapshot of + the session; any new summary or review file that lands after + its mtime invalidates it. Activities after the report: + - a new round's summary was written (loop kept going) + - an existing round's review-result changed (verdict flipped) + Either way, returning the stale cached text on /generate-report + would feed Codex/users an analysis of a session that has since + moved on. + + Returns False when the report is missing or empty (caller will + generate from scratch), or when it's present and at least as + new as every source file. + """ + try: + report_mtime = os.path.getmtime(report_path) + except OSError: + return False + import glob as _glob + sources = _glob.glob(os.path.join(session_dir, 'round-*-summary.md')) + sources += _glob.glob(os.path.join(session_dir, 'round-*-review-result.md')) + for src in sources: + try: + if os.path.getmtime(src) > report_mtime: + return True + except OSError: + continue + return False + + +@app.route('/api/sessions//generate-report', methods=['POST']) +def api_generate_report(session_id): + """Generate a methodology analysis report by invoking local Claude CLI. + + The ``?force=1`` query parameter bypasses the "report already + exists" shortcut and always re-runs Claude. Without it the + route still re-runs when the cached report predates any round + summary or review-result file — the old "exists => done" path + let users see stale analyses on sessions that had advanced + since the last preview. + """ + session_dir = _get_session_dir(session_id) + if not session_dir: + abort(404) + + report_path = os.path.join(session_dir, 'methodology-analysis-report.md') + force_regen = request.args.get('force', '').strip() in ('1', 'true', 'yes') + + # Serve the cached report only when it's present, non-empty, + # and still newer than every source file that contributes to + # the analysis. A stale cache would otherwise survive indefinitely + # across new rounds on an active session. + if (not force_regen + and os.path.exists(report_path) + and os.path.getsize(report_path) > 0 + and not _report_is_stale(session_dir, report_path)): + with open(report_path, 'r', encoding='utf-8') as f: + return jsonify({'status': 'exists', 'content': f.read()}) + + # Collect round summaries and review results (sorted numerically by round number) + import glob as _glob + import re as _re_local + + def _sort_round_files(files): + def _round_num(path): + m = _re_local.search(r'round-(\d+)-', os.path.basename(path)) + return int(m.group(1)) if m else 0 + return sorted(files, key=_round_num) + + summaries = [] + for sf in _sort_round_files(_glob.glob(os.path.join(session_dir, 'round-*-summary.md'))): + try: + with open(sf, 'r', encoding='utf-8') as f: + summaries.append(f'--- {os.path.basename(sf)} ---\n{f.read()}') + except (PermissionError, OSError): + pass + + reviews = [] + for rf in _sort_round_files(_glob.glob(os.path.join(session_dir, 'round-*-review-result.md'))): + try: + with open(rf, 'r', encoding='utf-8') as f: + reviews.append(f'--- {os.path.basename(rf)} ---\n{f.read()}') + except (PermissionError, OSError): + pass + + if not summaries and not reviews: + return jsonify({'error': 'No round data to analyze'}), 400 + + # Build the analysis prompt + prompt = f"""Analyze the following RLCR development records from a PURE METHODOLOGY perspective. + +CRITICAL SANITIZATION RULES — your output MUST NOT contain: +- File paths, directory paths, or module paths +- Function names, variable names, class names, or method names +- Branch names, commit hashes, or git identifiers +- Business domain terms, product names, or feature names +- Code snippets or code fragments of any kind +- Raw error messages or stack traces +- Project-specific URLs or endpoints +- Any information that could identify the specific project + +Focus areas: +- Iteration efficiency: Were rounds productive or repetitive? +- Feedback loop quality: Did reviewer feedback lead to improvements? +- Stagnation patterns: Were there signs of going in circles? +- Review effectiveness: Did reviews catch real issues or create false positives? +- Plan-to-execution alignment: Did execution follow the plan or drift? +- Round count vs. progress ratio: Was the number of rounds proportional to progress? +- Communication clarity: Were summaries and reviews clear and actionable? + +Output format: Write a structured markdown report following this exact structure: + +## Context + + +## Observations + + +## Suggested Improvements +| # | Suggestion | Mechanism | +|---|-----------|-----------| + + +## Quantitative Summary +| Metric | Value | +|--------|-------| + + +--- ROUND SUMMARIES --- +{chr(10).join(summaries[-10:])} + +--- REVIEW RESULTS --- +{chr(10).join(reviews[-10:])} +""" + # `_sort_round_files` returns entries in ascending round order + # (round 0, round 1, ...), so [-10:] picks the LATEST 10 rounds. + # Methodology signals — stagnation, drift, finalization — surface + # in the late phase of long sessions; taking [:10] would drop + # exactly the rounds that matter most for a session longer than + # ten rounds. Sessions with <=10 rounds are unaffected. + + # Invoke Claude CLI in pipe mode + try: + result = subprocess.run( + ['claude', '-p', '--model', 'sonnet', '--output-format', 'text'], + input=prompt, + capture_output=True, + text=True, + timeout=120, + cwd=PROJECT_DIR, + ) + + if result.returncode != 0: + return jsonify({ + 'error': f'Claude CLI failed (exit {result.returncode})', + 'stderr': result.stderr[-500:] if result.stderr else '', + }), 500 + + report_content = result.stdout.strip() + if not report_content: + return jsonify({'error': 'Claude returned empty response'}), 500 + + # Save the report + with open(report_path, 'w', encoding='utf-8') as f: + f.write(report_content) + + # Invalidate session cache so the report is picked up + _invalidate_cache(session_id) + + return jsonify({'status': 'generated', 'content': report_content}) + + except FileNotFoundError: + return jsonify({'error': 'Claude CLI not found. Install Claude Code to generate reports.'}), 500 + except subprocess.TimeoutExpired: + return jsonify({'error': 'Claude CLI timed out (120s). Try again or reduce session size.'}), 500 + except Exception as e: + return jsonify({'error': str(e)}), 500 + + +def _find_cancel_script(): + """Resolve cancel-rlcr-loop.sh from plugin layout or env.""" + # Check env override first + env_script = os.environ.get('HUMANIZE_CANCEL_SCRIPT', '') + if env_script and os.path.isfile(env_script): + return env_script + + # Sibling path within the same humanize plugin repo (viz/server/../../scripts/) + server_dir = os.path.dirname(os.path.abspath(__file__)) + sibling = os.path.normpath(os.path.join(server_dir, '..', '..', 'scripts', 'cancel-rlcr-loop.sh')) + if os.path.isfile(sibling): + return sibling + + # Search standard plugin cache locations + search_paths = [ + os.path.expanduser('~/.claude/plugins/cache/PolyArch/humanize'), + os.path.expanduser('~/.claude/plugins/marketplaces/humania'), + ] + for base in search_paths: + if not os.path.isdir(base): + continue + for entry in sorted(os.listdir(base), reverse=True): + candidate = os.path.join(base, entry, 'scripts', 'cancel-rlcr-loop.sh') + if os.path.isfile(candidate): + return candidate + candidate = os.path.join(base, 'scripts', 'cancel-rlcr-loop.sh') + if os.path.isfile(candidate): + return candidate + + return None + + +def _find_session_cancel_script(): + """Locate the session-scoped cancel helper from the plugin install. + + Mirrors the same lookup semantics as ``_find_cancel_script``: env + override first, then the sibling repo path (this file's grandparent + plus ``scripts/``), then the standard plugin cache locations. Without + the sibling and broader cache-path checks the route would 500 in any + deployment where ``CLAUDE_PLUGIN_ROOT`` is not set, which is the + common case when the dashboard is launched via + ``humanize monitor web`` from another terminal. + """ + env_script = os.environ.get('HUMANIZE_CANCEL_SESSION_SCRIPT', '') + if env_script and os.path.isfile(env_script): + return env_script + + server_dir = os.path.dirname(os.path.abspath(__file__)) + sibling = os.path.normpath( + os.path.join(server_dir, '..', '..', 'scripts', 'cancel-rlcr-session.sh') + ) + if os.path.isfile(sibling): + return sibling + + search_paths = [ + os.environ.get('CLAUDE_PLUGIN_ROOT', ''), + os.path.expanduser('~/.claude/plugins/cache/PolyArch/humanize'), + os.path.expanduser('~/.claude/plugins/marketplaces/humania'), + ] + for base in search_paths: + if not base or not os.path.isdir(base): + continue + for entry in sorted(os.listdir(base), reverse=True): + candidate = os.path.join(base, entry, 'scripts', 'cancel-rlcr-session.sh') + if os.path.isfile(candidate): + return candidate + candidate = os.path.join(base, 'scripts', 'cancel-rlcr-session.sh') + if os.path.isfile(candidate): + return candidate + return None + + +@app.route('/api/sessions/cancel', methods=['POST']) +def api_cancel_session_missing_id(): + """Reachable 400 for the missing-session-id contract from criterion C-7. + + Flask routing requires the ```` segment in the main + cancel route to match at all, so a request without it would + otherwise 404 before any handler ran. This explicit no-id route + surfaces the documented 400 contract and lets clients (and tests) + distinguish "you forgot the id" from "the id does not exist". + """ + return jsonify({ + 'error': 'session_id is required', + 'usage': 'POST /api/sessions//cancel', + }), 400 + + +@app.route('/api/sessions//cancel', methods=['POST']) +def api_cancel_session(session_id): + session = _get_session(session_id) + if not session: + abort(404) + status = session.get('status') + if status not in _CANCELLABLE_STATUSES: + return jsonify({ + 'error': 'Session is not in a cancellable state', + 'status': status, + }), 400 + + cancel_script = _find_session_cancel_script() + if not cancel_script: + return jsonify({ + 'error': 'Session-scoped cancel helper not found. Ensure humanize plugin is installed.', + 'expected_script': 'scripts/cancel-rlcr-session.sh', + }), 500 + + # The helper requires --force when the session is in the + # finalizing phase to avoid silent cancellation; without --force it + # exits with code 2. Forward it so dashboard cancel works for every + # phase the helper supports (active / analyzing / finalizing). + # + # `--project` MUST be passed explicitly so the helper does not + # fall back to ``CLAUDE_PROJECT_DIR`` (which the dashboard + # process may inherit from the shell that launched it, pointing + # at an entirely different workspace). + helper_args = [cancel_script, '--project', PROJECT_DIR, '--session-id', session_id] + if status == 'finalizing': + helper_args.append('--force') + + try: + subprocess.run(helper_args, cwd=PROJECT_DIR, timeout=30, check=True) + _invalidate_cache(session_id) + return jsonify({'status': 'cancelled', 'session_id': session_id}) + except subprocess.SubprocessError as e: + return jsonify({'error': str(e)}), 500 + + +@app.route('/api/sessions//export', methods=['POST']) +def api_export_session(session_id): + session = _get_session(session_id) + if not session: + abort(404) + markdown = export_session_markdown(session) + return jsonify({'content': markdown, 'filename': f'rlcr-report-{session_id}.md'}) + + +import re as _re + + +_FORBIDDEN_CATEGORIES = [ + ('path_token', _re.compile(r'[/\\]\w+\.\w{1,4}\b')), + ('path_token', _re.compile(r'\b\w+/\w+/\w+')), + ('qualified_name', _re.compile(r'\b\w+::\w+')), + ('qualified_name', _re.compile(r'\b\w+\.\w+\.\w+\(')), + ('git_hash', _re.compile(r'\b[a-f0-9]{7,40}\b')), + ('branch_name', _re.compile(r'\b(?:feat|fix|hotfix|release|bugfix)/\w+')), + ('branch_name', _re.compile(r'\bmain|master|develop\b')), + ('code_definition', _re.compile(r'\bdef \w+|function \w+|class \w+')), + # Code-shaped imports only. The previous `\b(?:import|require|from) + # \s+\w+` pattern matched ordinary English prose like + # "drifted from the original plan structure", which flagged the + # built-in `plan_execution` methodology observation and caused + # /api/sessions//github-issue to reject already-sanitized + # payloads with a false-positive warning. Anchor each variant to + # a context that only appears in code: + # - Python `import x` / `import x.y` at line start + # - Python `from x.y import z` at line start + # - JS/Node `require("…")` call syntax + ('import_statement', _re.compile(r'^\s*import\s+[\w.]+', _re.MULTILINE)), + ('import_statement', _re.compile(r'^\s*from\s+[\w.]+\s+import\b', _re.MULTILINE)), + ('import_statement', _re.compile(r'\brequire\s*\(')), + ('code_fence', _re.compile(r'```')), + ('identifier', _re.compile(r'\b\w+_\w+_\w+\b')), + ('identifier', _re.compile(r'\b[a-z]+[A-Z]\w+\b')), + ('stack_trace', _re.compile(r'\bTraceback \(most recent')), + ('stack_trace', _re.compile(r'\bFile ".+", line \d+')), + ('error_pattern', _re.compile(r'\b(?:Error|Exception|Panic|SIGSEGV|SIGABRT)\b')), + ('stack_trace', _re.compile(r'at \w+\.\w+\(.*:\d+:\d+\)')), + ('external_url', _re.compile(r'https?://(?!github\.com/humania)')), + ('local_endpoint', _re.compile(r'\b(?:localhost|127\.0\.0\.1):\d+')), +] + + +def _scan_for_forbidden_tokens(text): + """Return dict of {category: count} for forbidden patterns found in text. + Never returns the matched strings themselves to prevent leakage.""" + violations = {} + for category, pattern in _FORBIDDEN_CATEGORIES: + matches = pattern.findall(text) + if matches: + violations[category] = violations.get(category, 0) + len(matches) + return violations + + +def _is_english_only(text): + """Check that text is predominantly ASCII/English (>95% ASCII chars).""" + if not text: + return True + ascii_count = sum(1 for c in text if ord(c) < 128) + return (ascii_count / len(text)) > 0.95 + + +# Constrained methodology taxonomy — observations are classified into +# these generic categories. Only the category label and a generic phrasing +# are emitted into the issue; no report prose passes through. +_METHODOLOGY_CATEGORIES = { + 'iteration_efficiency': 'Iteration efficiency pattern observed: rounds showed uneven productivity distribution.', + 'feedback_loop': 'Feedback loop quality issue: reviewer-implementer communication could be improved.', + 'stagnation': 'Stagnation pattern detected: consecutive rounds showed limited forward progress.', + 'review_effectiveness': 'Review effectiveness concern: review feedback did not consistently drive improvements.', + 'plan_execution': 'Plan-execution alignment gap: implementation drifted from the original plan structure.', + 'verification_gap': 'Verification scope issue: implementer verification did not match reviewer expectations.', + 'phase_transition': 'phase-boundary transition pattern: the boundary between implementation and review work was unclear.', + 'scope_management': 'Scope management observation: work expanded or contracted relative to plan boundaries.', + 'general': 'General methodology observation noted.', +} + +_CATEGORY_KEYWORDS = { + 'iteration_efficiency': ['efficiency', 'productive', 'unproductive', 'round count', 'per-round output', 'diminish'], + 'feedback_loop': ['feedback', 'communication', 'reviewer', 'implementer', 'round-trip'], + 'stagnation': ['stagnation', 'stall', 'circle', 'repeat', 'no progress', 'same issue'], + 'review_effectiveness': ['false positive', 'review quality', 'missed issue', 'review catch'], + 'plan_execution': ['plan drift', 'alignment', 'deviat', 'scope change', 'off-plan'], + 'verification_gap': ['verification', 'insufficient test', 'too narrow', 'missed check', 'universal quantifier'], + 'phase_transition': ['phase transition', 'review phase', 'implementation phase', 'polishing', 'two-phase'], + 'scope_management': ['scope', 'over-engineer', 'under-deliver', 'bloat', 'defer'], +} + + +def _classify_observation(text): + """Classify a report observation into a methodology category.""" + lower = text.lower() + best_cat = 'general' + best_score = 0 + for cat, keywords in _CATEGORY_KEYWORDS.items(): + score = sum(1 for kw in keywords if kw in lower) + if score > best_score: + best_score = score + best_cat = cat + return best_cat + + +def _build_sanitized_issue(session): + """Build a sanitized GitHub issue payload following issue #62 format. + + Uses constrained methodology taxonomy — no report prose passes through. + Returns dict with 'title', 'body', and 'warnings' keys, or None if no report. + Warnings contain only category names and counts, never matched strings. + """ + report_obj = session.get('methodology_report', {}) + # Prefer English report; fall back to Chinese + report = (report_obj or {}).get('en') or (report_obj or {}).get('zh') or '' + if not report: + return None + + # Source diagnostics (informational only — do NOT gate outbound) + source_diagnostics = {} + if not _is_english_only(report): + source_diagnostics['non_english'] = 1 + + # Extract raw observations and suggestions from report structure + raw_observations = [] + raw_suggestions = [] + current_section = None + + for line in report.split('\n'): + stripped = line.strip() + if stripped.lower().startswith('## observation') or stripped.lower().startswith('## finding'): + current_section = 'observations' + continue + elif stripped.lower().startswith('## suggest'): + current_section = 'suggestions' + continue + elif stripped.startswith('## '): + current_section = stripped[3:].strip().lower() + continue + + if current_section == 'observations' and stripped.startswith(('- ', '* ', '1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.')): + raw_observations.append(stripped.lstrip('-* 0123456789.').strip()) + elif current_section == 'suggestions' and stripped.startswith('|') and not stripped.startswith('|---') and not stripped.startswith('| #'): + cols = [c.strip() for c in stripped.split('|')[1:-1]] + if len(cols) >= 2: + raw_suggestions.append(cols) + + if not raw_observations: + for line in report.split('\n'): + stripped = line.strip() + if stripped and not stripped.startswith('#') and not stripped.startswith('|') and not stripped.startswith('---'): + raw_observations.append(stripped) + + # Log source-level findings as diagnostics (not blocking) + for obs in raw_observations: + violations = _scan_for_forbidden_tokens(obs) + for cat, count in violations.items(): + source_diagnostics[cat] = source_diagnostics.get(cat, 0) + count + + # Classify observations into methodology categories (no prose passes through) + category_counts = {} + for obs in raw_observations: + category = _classify_observation(obs) + category_counts[category] = category_counts.get(category, 0) + 1 + + # Classify suggestions into methodology categories (no raw text passes through) + suggestion_categories = {} + for cols in raw_suggestions: + combined = ' '.join(cols) + cat = _classify_observation(combined) + suggestion_categories[cat] = suggestion_categories.get(cat, 0) + 1 + + # Build title from dominant category (no report text) + dominant_cat = max(category_counts, key=category_counts.get) if category_counts else 'general' + title = f"RLCR: {dominant_cat.replace('_', ' ').capitalize()} pattern identified" + + # Build issue #62 body using ONLY taxonomy-derived phrasing + s = session + # ``current_round`` is a 0-based index, not a round *count*. Using + # it verbatim printed ``0-round`` for sessions that only finished + # round 0 and under-reported every other session by one. The + # parser-built ``rounds`` list is the authoritative count — its + # length matches ``max_disk_round + 1``. + round_total = len(s.get('rounds') or []) + body_lines = [ + '## Context\n', + f'A {round_total}-round RLCR session ended with status: {s["status"]}.', + ] + if s.get('ac_total', 0) > 0: + body_lines.append(f'Acceptance criteria: {s["ac_done"]}/{s["ac_total"]} verified.') + body_lines.append('') + + body_lines.append('## Observations\n') + for i, (cat, count) in enumerate(sorted(category_counts.items(), key=lambda x: -x[1]), 1): + generic_text = _METHODOLOGY_CATEGORIES.get(cat, _METHODOLOGY_CATEGORIES['general']) + body_lines.append(f'{i}. **{cat.replace("_", " ").capitalize()}** ({count}x): {generic_text}') + + body_lines.append('') + body_lines.append('## Suggested Improvements\n') + body_lines.append('| # | Suggestion | Mechanism |') + body_lines.append('|---|-----------|-----------|') + if suggestion_categories: + for i, (cat, count) in enumerate(sorted(suggestion_categories.items(), key=lambda x: -x[1]), 1): + generic_suggestion = f'Improve {cat.replace("_", " ")} practices' + mechanism = f'Apply targeted {cat.replace("_", " ")} methodology adjustments ({count} suggestion(s) in this area)' + body_lines.append(f'| {i} | {generic_suggestion} | {mechanism} |') + else: + body_lines.append('| - | No specific suggestions identified | - |') + + body_lines.append('') + body_lines.append('## Quantitative Summary\n') + body_lines.append('| Metric | Value |') + body_lines.append('|--------|-------|') + # Reuse the ``round_total`` count computed for the Context section + # above — ``s["current_round"]`` is a 0-based index, so a raw read + # here would under-report every session (0 for a single-round + # session, N-1 for an N-round session) in the Quantitative + # Summary table that downstream issue readers rely on. + body_lines.append(f'| Total rounds | {round_total} |') + body_lines.append(f'| Exit reason | {s["status"].capitalize()} |') + if s.get('ac_total', 0) > 0: + rate = round(s['ac_done'] / s['ac_total'] * 100) if s['ac_total'] > 0 else 0 + body_lines.append(f'| AC count | {s["ac_total"]} |') + body_lines.append(f'| Completion rate | {rate}% |') + body_lines.append(f'| Observation categories | {len(category_counts)} |') + body_lines.append(f'| Total observations | {sum(category_counts.values())} |') + + body = '\n'.join(body_lines) + + # OUTBOUND VALIDATION: only the final generated title/body determine + # whether the payload is safe to send. Source-report findings are + # informational and do NOT gate the outbound path. + outbound_warnings = {} + + final_violations = _scan_for_forbidden_tokens(body) + for cat, count in final_violations.items(): + outbound_warnings[cat] = outbound_warnings.get(cat, 0) + count + + title_violations = _scan_for_forbidden_tokens(title) + for cat, count in title_violations.items(): + outbound_warnings[cat] = outbound_warnings.get(cat, 0) + count + + if not _is_english_only(body): + outbound_warnings['non_english'] = 1 + + return { + 'title': title, + 'body': body, + 'warnings': outbound_warnings, + 'source_diagnostics': source_diagnostics, + } + + +@app.route('/api/sessions//sanitized-issue') +def api_sanitized_issue(session_id): + session = _get_session(session_id) + if not session: + abort(404) + payload = _build_sanitized_issue(session) + if not payload: + abort(404) + + # Outbound gate: only block if the FINAL generated payload has warnings + if payload.get('warnings'): + return jsonify({ + 'title': payload['title'], + 'body': '[REDACTED — outbound payload failed validation.]', + 'warnings': payload['warnings'], + 'source_diagnostics': payload.get('source_diagnostics', {}), + 'requires_review': True, + }) + + # Clean payload — include source diagnostics as informational + result = { + 'title': payload['title'], + 'body': payload['body'], + 'warnings': {}, + 'source_diagnostics': payload.get('source_diagnostics', {}), + } + return jsonify(result) + + +@app.route('/api/sessions//github-issue', methods=['POST']) +def api_github_issue(session_id): + session = _get_session(session_id) + if not session: + abort(404) + + payload = _build_sanitized_issue(session) + if not payload: + return jsonify({'error': 'No methodology report available'}), 400 + + # Block submission and redact body when sanitization warnings exist + if payload.get('warnings'): + return jsonify({ + 'error': 'Sanitization check failed. Review the methodology report manually and remove project-specific content before sending.', + 'warnings': payload['warnings'], + 'manual': False, + }), 400 + + title = payload['title'] + body = payload['body'] + + # Check if gh is available + try: + subprocess.run(['gh', '--version'], capture_output=True, timeout=5, check=True) + except (subprocess.SubprocessError, FileNotFoundError): + return jsonify({ + 'error': 'gh CLI not available', + 'title': title, + 'body': body, + 'manual': True, + }), 400 + + try: + result = subprocess.run( + ['gh', 'issue', 'create', '--repo', 'PolyArch/humanize', + '--title', title, '--body', body], + capture_output=True, text=True, timeout=30, check=True, cwd=PROJECT_DIR, + ) + url = result.stdout.strip() + return jsonify({'status': 'created', 'url': url}) + except subprocess.SubprocessError as e: + return jsonify({ + 'error': str(e), + 'title': title, + 'body': body, + 'manual': True, + }), 500 + + +# --- Per-session SSE log streaming (per docs/streaming-protocol.md) --- + +_LOG_BASENAME_RE = re.compile( + r"^round-\d+-(?:codex|gemini)-(?:run|review)\.log$" +) + +# Polling cadence inside the SSE generator. Combined with the 64 KiB +# snapshot chunk size, this gives the contract's median-latency +# budget plenty of head-room (median << 2.0s under nominal load). +_SSE_POLL_INTERVAL_SECONDS = 0.25 +_SSE_HEARTBEAT_INTERVAL_SECONDS = 15.0 + +# Process-lifetime registry of LogStream instances. The registry +# implementation lives in log_streamer.py so it can be tested without +# needing the Flask import path; see docstring there for the +# correctness rationale (Codex Round 2 review caught a reconnect bug +# where per-request LogStream construction lost retained history). +_log_stream_registry = log_streamer.LogStreamRegistry() +# Ref-counted registry of per-cache-directory log watchers. Each live +# SSE generator calls _acquire_cache_watcher on entry and the matching +# _release_cache_watcher in its finally block, so the observer (and +# its inotify handle) is torn down on the last client disconnect. The +# pre-fix implementation only started watchers and never stopped them, +# so long-running dashboard processes leaked one watcher thread per +# unique cache directory the user ever browsed. +_cache_watchers = {} +_cache_watcher_refcounts = {} +_cache_watchers_lock = threading.Lock() + + +def _sse_frame(event): + """Render one event dict as the SSE wire format from the contract.""" + payload = {k: v for k, v in event.items() if k != 'id'} + return ( + f"event: {event['type']}\n" + f"id: {event['id']}\n" + f"data: {json.dumps(payload, separators=(',', ':'))}\n\n" + ) + + +def _is_terminal_status(status): + return status not in (None, '', 'active', 'analyzing', 'finalizing', 'unknown') + + +# Terminal-state marker filenames produced by the RLCR loop. Only +# truly-terminal markers belong here: the SSE generator closes the +# stream as soon as any of these appear, and the dashboard still +# treats ``methodology-analysis-state.md`` / ``finalize-state.md`` +# as running (``analyzing`` / ``finalizing`` status, still cancellable, +# still emitting live log bytes). Including those markers in this +# list used to cause the live log pane to EOF the moment a session +# entered finalize or analysis, so the finalize-phase / methodology- +# report output never reached the browser. The list must stay in +# lock-step with ``_is_terminal_status`` above. +_TERMINAL_STATE_FILES = ( + 'complete-state.md', + 'cancel-state.md', + 'stop-state.md', + 'maxiter-state.md', + 'unexpected-state.md', +) + + +def _session_is_terminal_cheap(session_id): + """Fast path for the SSE EOF check. + + The 250 ms SSE poll loop used to call ``_get_session(session_id, + force_refresh=True)`` every tick, which re-runs the full + parse_session pipeline (re-scans every round file, parses the + goal tracker, re-reads the methodology report, and shells out to + ``git`` once or twice for the git-status summary). On long + sessions with many rounds and multiple live SSE clients, that + quickly becomes the bottleneck. + + Terminal state is trivially detectable from on-disk markers: + whenever any *-state.md file other than state.md is present the + loop has stopped writing logs. Check that directly so the hot + loop doesn't drag the full parser behind it. False negatives + just defer the EOF by one poll cycle; they never corrupt the + stream because the file-system watcher still drives every + append. + """ + session_dir = _get_session_dir(session_id) + if not session_dir: + # The directory vanished or was renamed — treat as terminal + # so the SSE generator closes cleanly. + return True + for name in _TERMINAL_STATE_FILES: + if os.path.isfile(os.path.join(session_dir, name)): + return True + return False + + +def _acquire_cache_watcher(cache_dir): + """Reserve a cache watcher for one active SSE stream. + + Starts at most one CacheLogWatcher per cache directory and + increments a per-directory refcount so concurrent SSE clients on + the same session share the observer. Paired with + :func:`_release_cache_watcher`, which stops the watcher when the + last client releases it. The watcher's callback runs the matching + LogStream's poll inline so file-system events drive the stream in + addition to the SSE handler's own 250 ms poll loop. Best-effort + on startup: if the cache directory does not exist yet the + watcher does not start and the SSE handler continues to drive + everything via its poll loop. + """ + with _cache_watchers_lock: + _cache_watcher_refcounts[cache_dir] = ( + _cache_watcher_refcounts.get(cache_dir, 0) + 1 + ) + if cache_dir in _cache_watchers: + return + + def callback(filepath): + basename = os.path.basename(filepath) + for stream in _log_stream_registry.streams_in_cache_dir(cache_dir, basename): + try: + stream.poll() + except Exception: + # Watcher callbacks must not crash the observer thread. + pass + + watcher = CacheLogWatcher(cache_dir, callback) + if watcher.start(): + _cache_watchers[cache_dir] = watcher + + +def _release_cache_watcher(cache_dir): + """Release one reservation; stop the watcher on the final release. + + Called from the SSE generator's ``finally`` block so an observer + is torn down when its last client disconnects (normal EOF, + connection close, or server shutdown). Without this pairing the + observer thread and inotify handle outlive every session a user + ever browsed, which exhausts ``fs.inotify.max_user_watches`` on + long-running dashboard processes. + """ + with _cache_watchers_lock: + remaining = _cache_watcher_refcounts.get(cache_dir, 0) - 1 + if remaining <= 0: + _cache_watcher_refcounts.pop(cache_dir, None) + watcher = _cache_watchers.pop(cache_dir, None) + else: + _cache_watcher_refcounts[cache_dir] = remaining + watcher = None + if watcher is not None: + try: + watcher.stop() + except Exception: + # Best-effort cleanup: a failed observer stop must not + # take down the request that triggered the release. + pass + + +def _acquire_log_stream(session_id, basename): + """Acquire the shared LogStream for ``(session_id, basename)``. + + Increments the registry refcount so the caller owns one release. + The caller (the SSE route) MUST pair this with + :func:`_release_log_stream` and + :func:`_acquire_cache_watcher` / :func:`_release_cache_watcher` + around the generator body so stream + watcher lifetimes track + active SSE consumers instead of process lifetime. Without the + release, the registry retains the 256-event deque (often large + base64 payloads) for every session the user ever browsed. + """ + cache_dir = rlcr_sources.cache_dir_for_session(PROJECT_DIR, session_id) + stream = _log_stream_registry.acquire(cache_dir, session_id, basename) + return stream + + +def _release_log_stream(session_id, basename): + """Release one :func:`_acquire_log_stream` reservation.""" + _log_stream_registry.release(session_id, basename) + + +@app.route('/api/sessions//logs/') +def stream_session_log(session_id, basename): + """Per-session, per-file SSE stream per the streaming protocol. + + Implements the snapshot+append+resync+eof event sequence frozen in + docs/streaming-protocol.md, including Last-Event-Id reconnect with + the documented 256-event retention. Remote-mode authentication is + enforced by the @app.before_request middleware: in remote mode the + request must carry a valid bearer token (`Authorization: Bearer` + header for fetch-style calls, `?token=` query parameter for SSE + EventSource clients per DEC-4); missing or invalid token returns + 401. Localhost-bound deployments skip the auth check. + """ + if not _LOG_BASENAME_RE.match(basename): + abort(400) + session_dir = _get_session_dir(session_id) + if session_dir is None: + abort(404) + + stream = _acquire_log_stream(session_id, basename) + # Resolve the cache directory once up-front so the generator's + # watcher acquire/release pair references the same key. The + # registry helper derives it internally; re-derive here so the + # cache-watcher refcount key matches the stream registry's. + cache_dir = rlcr_sources.cache_dir_for_session(PROJECT_DIR, session_id) + + last_event_id = 0 + raw_id = request.headers.get('Last-Event-Id') + if raw_id: + try: + last_event_id = int(raw_id) + except ValueError: + last_event_id = 0 + + def generate(): + # Reserve the per-cache-dir watcher for the lifetime of this + # stream. The paired release in the finally block below is + # what lets long-running dashboard instances stop leaking + # inotify handles (one per distinct session the user browses) + # after clients disconnect. The log-stream refcount acquired + # at route entry is released here too so its retention deque + # can be freed once the last client has seen EOF. + _acquire_cache_watcher(cache_dir) + try: + client_last_id = last_event_id + + # Initial event delivery: replay if the client has a Last-Event-Id, + # else fresh snapshot. The route never falls through to a poll + # that would emit the file body as `append` from offset 0. + if client_last_id > 0: + replayed, in_window = stream.replay(client_last_id) + for event in replayed: + yield _sse_frame(event) + client_last_id = event['id'] + if not in_window: + for event in stream.snapshot(): + yield _sse_frame(event) + client_last_id = event['id'] + else: + for event in stream.snapshot(): + yield _sse_frame(event) + client_last_id = event['id'] + + # Steady-state loop. Drive poll() (may be a no-op if the cache + # watcher or another concurrent handler already polled), then + # forward any retained events newer than what this client has + # already sent. Using the deque as the source of truth means + # multiple concurrent SSE clients on the same stream all + # receive every event without racing on _offset. + last_heartbeat = time.time() + while True: + stream.poll() + catchup, in_window = stream.replay(client_last_id) + for event in catchup: + yield _sse_frame(event) + client_last_id = event['id'] + if not in_window: + for event in stream.snapshot(): + yield _sse_frame(event) + client_last_id = event['id'] + + # Cheap disk probe instead of a full parse_session on + # every SSE tick. Avoids re-scanning round files, goal + # tracker, and the `git status` subprocesses just to + # decide whether to emit EOF. + if _session_is_terminal_cheap(session_id): + for event in stream.mark_eof(): + yield _sse_frame(event) + client_last_id = event['id'] + return + + now = time.time() + if now - last_heartbeat >= _SSE_HEARTBEAT_INTERVAL_SECONDS and not catchup: + yield ": keepalive\n\n" + last_heartbeat = now + time.sleep(_SSE_POLL_INTERVAL_SECONDS) + finally: + # Runs on normal EOF return, GeneratorExit (client + # disconnect), or any propagated exception, so the + # refcount always balances the earlier acquire. The + # log-stream release evicts the stream's retention deque + # once its final client disconnects AND EOF has already + # been delivered; active sessions without a current + # client stay resident so reconnects get the replay + # window the streaming contract requires. + _release_cache_watcher(cache_dir) + _release_log_stream(session_id, basename) + + response = Response(generate(), mimetype='text/event-stream') + response.headers['Cache-Control'] = 'no-cache' + response.headers['X-Accel-Buffering'] = 'no' + return response + + +# --- WebSocket --- + +@sock.route('/ws') +def websocket(ws): + # T11 / DEC-4: WebSocket transport is restricted to localhost. In + # remote mode (host != 127.0.0.1) the dashboard MUST use SSE for + # log streams (over HTTPS with `?token=` auth), so the WebSocket + # control channel is rejected entirely. Browsers cannot send + # arbitrary auth headers on WebSocket upgrades, which is the root + # reason behind DEC-4. + if not _is_localhost_bind(): + try: + ws.close(reason='WebSocket transport disabled in remote mode') + except Exception: + pass + return + + # Cross-origin WebSocket rejection. The HTTP side of the app + # gates mutating routes through `_enforce_csrf_protection`, but + # browsers happily let arbitrary pages open a WebSocket to + # ws://localhost:/ws with no Origin check from the server. + # A `cancel_session` message over that connection would kill an + # active loop with zero auth prompt. Reuse the same request-host + # matcher so the localhost dashboard's own Origin keeps working + # while hostile origins (pages served by other projects in the + # same browser) are closed before they can send anything. + origin = request.headers.get('Origin', '').strip() + if origin and not _origin_matches_request(origin): + try: + ws.close(reason='cross-origin WebSocket rejected') + except Exception: + pass + return + + with _ws_lock: + _ws_clients.add(ws) + try: + while True: + data = ws.receive(timeout=60) + if data is None: + continue + try: + msg = json.loads(data) + if msg.get('type') == 'cancel_session': + sid = msg.get('session_id', '') + if sid: + session = _get_session(sid) + if session and session.get('status') in _CANCELLABLE_STATUSES: + # Route through the session-scoped helper + # instead of the project-global cancel. + # Match the REST route's --force handling + # so finalizing sessions can be cancelled. + cancel_script = _find_session_cancel_script() + if cancel_script: + # Mirror the REST route: pass --project + # explicitly so the helper does not + # fall back to a stray + # CLAUDE_PROJECT_DIR inherited from + # the launching shell. + helper_args = [ + cancel_script, + '--project', PROJECT_DIR, + '--session-id', sid, + ] + if session.get('status') == 'finalizing': + helper_args.append('--force') + # Match the REST cancel route: require a + # zero exit code before invalidating + # cache. A non-zero exit means the helper + # did not actually cancel the session, so + # refreshing the dashboard would mask the + # failure. + try: + subprocess.run( + helper_args, + cwd=PROJECT_DIR, timeout=30, + check=True, + ) + except subprocess.SubprocessError: + pass + else: + _invalidate_cache(sid) + except (json.JSONDecodeError, KeyError): + pass + except Exception: + pass + finally: + with _ws_lock: + _ws_clients.discard(ws) + + +# --- Main --- + +def _resolve_auth_token(cli_token): + """Pick the effective bearer token from the CLI flag or env var.""" + if cli_token: + return cli_token + return os.environ.get('HUMANIZE_VIZ_TOKEN', '').strip() + + +def main(): + parser = argparse.ArgumentParser(description='Humanize Viz Dashboard Server') + parser.add_argument('--host', type=str, default='127.0.0.1', + help='Bind address (default: 127.0.0.1)') + parser.add_argument('--port', type=int, default=18000, + help='Bind port (default: 18000)') + parser.add_argument('--project', type=str, default='.', + help='Project root for the dashboard (CLI-fixed per DEC-3)') + parser.add_argument('--static', type=str, default='.', + help='Directory containing the SPA static assets') + parser.add_argument('--auth-token', type=str, default='', + help='Bearer token required for remote-mode access. ' + 'May also be supplied via HUMANIZE_VIZ_TOKEN env var. ' + 'Required when --host is not a loopback address.') + parser.add_argument('--trust-proxy', action='store_true', default=False, + help='Acknowledge that a TLS-terminating reverse proxy ' + 'is in front of this server. Required for ' + 'non-loopback binds because the SSE stream ' + 'transmits the bearer token as a ?token= query ' + 'parameter, which would leak in cleartext over ' + 'plain HTTP. May also be enabled via the ' + 'HUMANIZE_VIZ_TRUST_PROXY=1 env var.') + args = parser.parse_args() + + global PROJECT_DIR, STATIC_DIR, BIND_HOST, AUTH_TOKEN, TRUST_PROXY, _watcher + PROJECT_DIR = os.path.abspath(args.project) + STATIC_DIR = os.path.abspath(args.static) + BIND_HOST = args.host + AUTH_TOKEN = _resolve_auth_token(args.auth_token) + TRUST_PROXY = args.trust_proxy or os.environ.get( + 'HUMANIZE_VIZ_TRUST_PROXY', '' + ).strip() in ('1', 'true', 'yes') + + if not _is_localhost_bind() and not AUTH_TOKEN: + print( + "Error: binding to a non-localhost host requires --auth-token " + "(or HUMANIZE_VIZ_TOKEN env var). Refusing to start a remote " + "server without authentication.", + file=sys.stderr, + ) + sys.exit(2) + + # Plain-HTTP Flask + ?token= bearer auth is safe on loopback + # (nothing ever leaves the host), but leaks the token in + # cleartext the moment the bind is externally reachable. Require + # an explicit operator acknowledgement that a TLS-terminating + # reverse proxy is in front of the server before accepting a + # non-loopback bind. The flag / env var is a load-bearing + # declaration: without it we'd rather refuse to start than hand + # out an insecure dashboard URL. TRUST_PROXY is resolved above + # and also drives the CSRF port-matcher's X-Forwarded-Proto + # handling. + if not _is_localhost_bind() and not TRUST_PROXY: + print( + "Error: binding to a non-localhost host requires a TLS-terminating\n" + "reverse proxy so the ?token= query parameter is never transmitted\n" + "in cleartext. Pass --trust-proxy (or HUMANIZE_VIZ_TRUST_PROXY=1)\n" + "to acknowledge that an HTTPS reverse proxy (nginx / caddy / etc.)\n" + "is in front of this server.", + file=sys.stderr, + ) + sys.exit(2) + + # Start file watcher + _watcher = SessionWatcher(PROJECT_DIR, broadcast_message) + _watcher.start() + + # Pre-populate cache + list_sessions(PROJECT_DIR) + + visible_host = BIND_HOST if not _is_localhost_bind() else 'localhost' + print(f"Humanize Viz server starting on http://{visible_host}:{args.port}") + print(f"Project: {PROJECT_DIR}") + print(f"Static: {STATIC_DIR}") + if AUTH_TOKEN: + print("Remote mode: token authentication enabled.") + elif _is_localhost_bind(): + print("Local mode: authentication disabled (loopback bind).") + + app.run(host=BIND_HOST, port=args.port, debug=False) + + +if __name__ == '__main__': + main() diff --git a/viz/server/exporter.py b/viz/server/exporter.py new file mode 100644 index 00000000..ca528c74 --- /dev/null +++ b/viz/server/exporter.py @@ -0,0 +1,90 @@ +"""Export RLCR session data as Markdown reports.""" + + +def _resolve_content(value, lang='en'): + """Extract string content from a bilingual {zh, en} dict or plain string.""" + if value is None: + return None + if isinstance(value, str): + return value + if isinstance(value, dict): + return value.get(lang) or value.get('en') or value.get('zh') + return str(value) + + +def export_session_markdown(session, lang='en'): + """Generate a structured Markdown report for a session.""" + lines = [] + sid = session['id'] + lines.append(f"# RLCR Session Report — {sid}\n") + + # Overview table + lines.append("## Overview\n") + lines.append("| Metric | Value |") + lines.append("|--------|-------|") + lines.append(f"| Status | {session['status'].capitalize()} |") + # ``current_round`` is a 0-based index — a session that only + # finished round 0 reports ``current_round=0`` with one entry + # in ``rounds``. Use the parsed rounds list length so the + # exported Markdown reflects the true completed-round count + # instead of underreporting every session by one. + lines.append(f"| Rounds | {len(session.get('rounds') or [])} |") + lines.append(f"| Plan | {session.get('plan_file', 'N/A')} |") + lines.append(f"| Branch | {session.get('start_branch', 'N/A')} |") + lines.append(f"| Started | {session.get('started_at', 'N/A')} |") + lines.append(f"| Codex Model | {session.get('codex_model', 'N/A')} |") + lines.append(f"| Last Verdict | {session.get('last_verdict', 'N/A')} |") + + ac_total = session.get('ac_total', 0) + ac_done = session.get('ac_done', 0) + if ac_total > 0: + lines.append(f"| AC Completion | {ac_done}/{ac_total} ({round(ac_done/ac_total*100)}%) |") + lines.append("") + + # Round history + if session.get('rounds'): + lines.append("## Round History\n") + for r in session['rounds']: + rn = r['number'] + lines.append(f"### Round {rn}\n") + lines.append(f"**Phase**: {r.get('phase', 'N/A')}") + lines.append(f"**Verdict**: {r.get('verdict', 'N/A')}") + if r.get('duration_minutes'): + lines.append(f"**Duration**: {r['duration_minutes']} min") + if r.get('bitlesson_delta') and r['bitlesson_delta'] != 'none': + lines.append(f"**BitLesson**: {r['bitlesson_delta']}") + lines.append("") + + summary_text = _resolve_content(r.get('summary'), lang) + if summary_text: + lines.append("#### Summary\n") + lines.append(summary_text) + lines.append("") + + review_text = _resolve_content(r.get('review_result'), lang) + if review_text: + lines.append("#### Codex Review\n") + lines.append(review_text) + lines.append("") + + # Goal Tracker + gt = session.get('goal_tracker') + if gt: + lines.append("## Goal Tracker\n") + lines.append(f"**Ultimate Goal**: {gt.get('ultimate_goal', 'N/A')}\n") + + if gt.get('acceptance_criteria'): + lines.append("### Acceptance Criteria\n") + for ac in gt['acceptance_criteria']: + status_icon = {'completed': '\u2713', 'in_progress': '\u25C9', 'pending': '\u25CB'}.get(ac['status'], '?') + lines.append(f"- {status_icon} **{ac['id']}**: {ac['description']}") + lines.append("") + + # Methodology analysis + report_text = _resolve_content(session.get('methodology_report'), lang) + if report_text: + lines.append("## Methodology Analysis\n") + lines.append(report_text) + lines.append("") + + return '\n'.join(lines) diff --git a/viz/server/log_streamer.py b/viz/server/log_streamer.py new file mode 100644 index 00000000..c8d03419 --- /dev/null +++ b/viz/server/log_streamer.py @@ -0,0 +1,520 @@ +"""Per-session, per-file log streaming logic for the dashboard. + +Implements the snapshot+append+resync+eof event sequence frozen in +``docs/streaming-protocol.md``. The module is pure logic: it does not +own a poll loop or HTTP transport. Callers drive ``poll()`` and turn +the returned event dicts into SSE frames or any other transport. + +Event shape (matches the contract): + + {"type": "snapshot", "path": , "offset": , "bytes_b64": , "eof": } + {"type": "append", "path": , "offset": , "bytes_b64": } + {"type": "resync", "path": , "reason": "truncated|rotated|recreated|missing|overflow"} + {"type": "eof", "path": } + +The streamer assigns a strictly increasing ``id`` per stream and +retains the last 256 events for ``Last-Event-Id`` reconnects (per the +contract). Larger snapshots are chunked at 64 KiB. +""" + +from __future__ import annotations + +import base64 +import os +import threading +import time +from collections import deque +from typing import Deque, Dict, List, Optional, Tuple + +SNAPSHOT_CHUNK_BYTES = 64 * 1024 +EVENT_RETENTION = 256 +# Idle-TTL for ``LogStreamRegistry`` entries that reach refcount=0 +# without having emitted EOF. After this many seconds with no active +# consumer the stream is evicted even if its session is still live; +# a later reconnect gets a fresh LogStream (the streaming contract's +# out-of-window ``resync(overflow)`` path handles that cleanly). Keep +# long enough to cover page reloads and brief tab switches, short +# enough that briefly-opened sessions don't hold their retention +# deque for the whole process lifetime. +IDLE_STREAM_TTL_SECONDS = 300.0 + +EVENT_SNAPSHOT = "snapshot" +EVENT_APPEND = "append" +EVENT_RESYNC = "resync" +EVENT_EOF = "eof" + +RESYNC_TRUNCATED = "truncated" +RESYNC_ROTATED = "rotated" +RESYNC_RECREATED = "recreated" +RESYNC_MISSING = "missing" +RESYNC_OVERFLOW = "overflow" + + +def _b64(data: bytes) -> str: + return base64.b64encode(data).decode("ascii") + + +def _stat_id(path: str) -> Optional[Tuple[int, int]]: + """Return ``(st_dev, st_ino)`` for ``path`` or ``None`` if absent.""" + try: + st = os.stat(path) + except (OSError, FileNotFoundError): + return None + return (st.st_dev, st.st_ino) + + +def _file_size(path: str) -> Optional[int]: + try: + return os.path.getsize(path) + except (OSError, FileNotFoundError): + return None + + +class LogStream: + """One streaming channel for one (session, filename) pair. + + A stream is created with the basename of the cache log file (e.g. + ``round-3-codex-run.log``) and the absolute path to the parent + cache directory. The basename is what appears in the ``path`` + field of every emitted event so clients only see relative names. + + Lifecycle: + + - ``snapshot()`` — issue zero or more ``snapshot`` events covering + the bytes already on disk. May be called multiple times during + reconnect; the second call resets internal counters before + replaying from offset 0. + - ``poll()`` — observe the file once; emit ``append`` if new bytes + appeared, ``resync`` followed by a fresh snapshot if the file + shrank or its inode changed, ``resync`` with reason ``missing`` + if the file disappeared, or no events when nothing changed. + - ``mark_eof()`` — caller signals that the writer has closed (the + session reached a terminal state); a single ``eof`` event is + emitted and subsequent ``poll()`` calls are no-ops. + + Events are returned with a monotonic per-stream id. ``replay`` + serves a ``Last-Event-Id`` reconnect by returning all retained + events newer than the supplied id; if the id is out of the + retention window it returns a ``resync(overflow)`` plus a fresh + snapshot path that the caller should run through ``snapshot()``. + """ + + def __init__(self, cache_dir: str, basename: str): + self.cache_dir = cache_dir + self.basename = basename + self.path = os.path.join(cache_dir, basename) + self._next_id = 1 + self._offset = 0 + self._stat = _stat_id(self.path) + self._eof_emitted = False + self._retained: Deque[Dict] = deque(maxlen=EVENT_RETENTION) + self._missing_emitted = False + # Set by any ``resync`` path (truncated/rotated/recreated) when + # the follow-up ``_snapshot_locked`` saw a transiently-empty + # file — a common race on CI when the file-system watcher + # fires between the writer's ``open('wb')`` (which truncates + # to 0) and its subsequent ``write``. While this flag is set, + # the next poll that observes content treats the bytes as a + # fresh snapshot rather than appending them to the pre-resync + # stream, so the protocol's resync→snapshot sequencing is + # preserved even when the file starts empty post-resync. + self._resync_pending = False + # All public mutators (snapshot, poll, mark_eof, replay) acquire + # this lock so concurrent SSE handlers can share the same + # instance without corrupting offset/retained state. RLock so + # that internal helpers that call other public methods (e.g. + # the replay overflow path that resets ``_offset``) do not + # deadlock themselves. + self.lock = threading.RLock() + + def latest_event_id(self) -> int: + """Return the highest event id retained, or 0 if none.""" + with self.lock: + return self._retained[-1]["id"] if self._retained else 0 + + @property + def eof_emitted(self) -> bool: + """Public view of the ``_eof_emitted`` flag. + + The registry's release path consults this to decide whether a + stream with no active clients can be evicted — once EOF has + been delivered nobody will receive retained events, so the + retention buffer (up to 256 base64 payloads) is safe to free. + """ + with self.lock: + return self._eof_emitted + + def _emit(self, event: Dict) -> Dict: + event_with_id = {"id": self._next_id, **event} + self._next_id += 1 + self._retained.append(event_with_id) + return event_with_id + + def snapshot(self) -> List[Dict]: + """Emit snapshot events for everything already on disk.""" + with self.lock: + return self._snapshot_locked() + + def _snapshot_locked(self) -> List[Dict]: + if self._eof_emitted: + return [] + events: List[Dict] = [] + size = _file_size(self.path) + if size is None: + self._offset = 0 + self._stat = None + return events + + self._stat = _stat_id(self.path) + self._missing_emitted = False + if size == 0: + self._offset = 0 + return events + + try: + f = open(self.path, "rb") + except OSError: + return events + try: + offset = 0 + while offset < size: + chunk = f.read(SNAPSHOT_CHUNK_BYTES) + if not chunk: + break + events.append(self._emit({ + "type": EVENT_SNAPSHOT, + "path": self.basename, + "offset": offset, + "bytes_b64": _b64(chunk), + "eof": False, + })) + offset += len(chunk) + self._offset = offset + finally: + f.close() + return events + + def poll(self) -> List[Dict]: + """Observe the file once and emit any events that occurred.""" + with self.lock: + return self._poll_locked() + + def _poll_locked(self) -> List[Dict]: + if self._eof_emitted: + return [] + events: List[Dict] = [] + size = _file_size(self.path) + stat = _stat_id(self.path) + + if size is None: + if not self._missing_emitted: + events.append(self._emit({ + "type": EVENT_RESYNC, + "path": self.basename, + "reason": RESYNC_MISSING, + })) + self._missing_emitted = True + self._offset = 0 + self._stat = None + return events + + if self._missing_emitted: + # File came back; treat as a recreation. + events.append(self._emit({ + "type": EVENT_RESYNC, + "path": self.basename, + "reason": RESYNC_RECREATED, + })) + self._missing_emitted = False + self._offset = 0 + self._stat = stat + snap = self._snapshot_locked() + events.extend(snap) + # If the file is transiently empty post-resync (watcher + # fired mid-write), defer snapshot delivery to the next + # poll so the resync is followed by a real snapshot event + # rather than an append when content finally lands. + self._resync_pending = not snap + return events + + if stat is not None and self._stat is not None and stat != self._stat: + events.append(self._emit({ + "type": EVENT_RESYNC, + "path": self.basename, + "reason": RESYNC_ROTATED, + })) + self._offset = 0 + self._stat = stat + snap = self._snapshot_locked() + events.extend(snap) + self._resync_pending = not snap + return events + + if size < self._offset: + events.append(self._emit({ + "type": EVENT_RESYNC, + "path": self.basename, + "reason": RESYNC_TRUNCATED, + })) + self._offset = 0 + self._stat = stat + snap = self._snapshot_locked() + events.extend(snap) + self._resync_pending = not snap + return events + + if size > self._offset: + if self._resync_pending: + # Post-resync content that could not be snapshotted on + # the prior poll (file was 0 bytes at the time). Emit + # it as a snapshot now so clients still observe the + # contract's resync→snapshot sequence. + snap = self._snapshot_locked() + events.extend(snap) + if self._offset >= size: + self._resync_pending = False + self._stat = stat + return events + new_bytes = size - self._offset + try: + f = open(self.path, "rb") + except OSError: + return events + try: + f.seek(self._offset) + # Chunk appends so any individual event stays bounded. + start = self._offset + remaining = new_bytes + while remaining > 0: + chunk = f.read(min(SNAPSHOT_CHUNK_BYTES, remaining)) + if not chunk: + break + events.append(self._emit({ + "type": EVENT_APPEND, + "path": self.basename, + "offset": start, + "bytes_b64": _b64(chunk), + })) + start += len(chunk) + remaining -= len(chunk) + self._offset = start + finally: + f.close() + self._stat = stat + + return events + + def mark_eof(self) -> List[Dict]: + """Emit a single ``eof`` event; subsequent polls are no-ops.""" + with self.lock: + if self._eof_emitted: + return [] + self._eof_emitted = True + return [self._emit({"type": EVENT_EOF, "path": self.basename})] + + def replay(self, last_event_id: int) -> Tuple[List[Dict], bool]: + """Return retained events newer than ``last_event_id``. + + Returns ``(events, in_window)``. When ``in_window`` is False the + caller MUST call ``snapshot()`` again after consuming any + events; the helper has already emitted a ``resync(overflow)``. + """ + with self.lock: + if not self._retained: + return [], True + oldest = self._retained[0]["id"] + if last_event_id < oldest - 1: + overflow = self._emit({ + "type": EVENT_RESYNC, + "path": self.basename, + "reason": RESYNC_OVERFLOW, + }) + self._offset = 0 + return [overflow], False + events = [e for e in self._retained if e["id"] > last_event_id] + return events, True + + +def stream_url_path(session_id: str, basename: str) -> str: + """Canonical SSE URL path for one stream.""" + return f"/api/sessions/{session_id}/logs/{basename}" + + +class LogStreamRegistry: + """Process-lifetime registry of LogStream instances. + + Keyed by ``(session_id, basename)``. Concurrent SSE handlers + share the same instance so retained event history survives + client reconnects and the contract's ``Last-Event-Id`` semantics + are honored. Without this registry, each request would construct + a fresh ``LogStream`` with empty retention and a reconnect would + emit the file body as ``append`` from offset 0 instead of + replaying or emitting ``resync(overflow)`` + ``snapshot``. + """ + + def __init__(self, idle_ttl_seconds: float = IDLE_STREAM_TTL_SECONDS): + self._streams: Dict[Tuple[str, str], LogStream] = {} + # Per-key active-consumer refcount. ``acquire`` / ``release`` + # pair around each SSE generator so the registry can drop a + # stream (and its retention buffer) once the final client has + # disconnected AND EOF has already been delivered. Live + # sessions without a current client keep their stream resident + # so reconnects still hit the 256-event replay window that + # the streaming contract mandates. + self._refcounts: Dict[Tuple[str, str], int] = {} + # Monotonic timestamp recorded whenever a stream's refcount + # reaches zero without EOF (active-session disconnect). The + # idle-TTL sweep in ``release`` uses this to evict entries + # that would otherwise accumulate when users briefly open + # many active sessions and never revisit them; the streaming + # contract's ``resync(overflow)`` path handles the late + # reconnect case when a client comes back after eviction. + self._idle_since: Dict[Tuple[str, str], float] = {} + self._idle_ttl_seconds = idle_ttl_seconds + self._lock = threading.Lock() + + def get_or_create(self, cache_dir: str, session_id: str, basename: str) -> LogStream: + """Return the registry-owned stream, creating it if needed. + + Does NOT change the refcount. Tests use this to inspect + registry sharing semantics; the SSE route uses ``acquire`` / + ``release`` instead so the stream is evicted once its last + client disconnects. + """ + key = (session_id, basename) + with self._lock: + stream = self._streams.get(key) + if stream is None: + stream = LogStream(cache_dir, basename) + self._streams[key] = stream + return stream + + def acquire(self, cache_dir: str, session_id: str, basename: str) -> LogStream: + """Get-or-create the stream and record one active consumer. + + Must be paired with :meth:`release` — typically from the + ``finally`` block of the SSE generator so normal EOF, client + disconnect, and exception paths all balance the refcount. + """ + key = (session_id, basename) + with self._lock: + # Every new acquire is also a chance to drop OTHER entries + # whose idle TTL has elapsed without a follow-up release. + # Without this, a refcount=0 stream that is never released + # again (one-off disconnect on a long-lived session) would + # stay resident for the process lifetime and leak its + # retention deque. + self._sweep_idle_streams_locked() + stream = self._streams.get(key) + if stream is None: + stream = LogStream(cache_dir, basename) + self._streams[key] = stream + self._refcounts[key] = self._refcounts.get(key, 0) + 1 + # Reset idle clock: a new consumer means the earlier + # idle-since timestamp no longer applies. + self._idle_since.pop(key, None) + return stream + + def release(self, session_id: str, basename: str) -> None: + """Decrement the consumer count and evict idle streams. + + Eviction strategy: + - refcount reaches zero AND the stream has emitted ``eof`` → + drop immediately; no future client needs the retention deque. + - refcount reaches zero without EOF → start an idle timer for + this key so the eventual sweep (below) can evict it once + ``IDLE_STREAM_TTL_SECONDS`` elapse with no reconnect. The + stream stays resident for the TTL window so the common + page-reload-then-reconnect flow still hits the 256-event + ``Last-Event-Id`` replay window the contract mandates. + - every release also sweeps the registry for OTHER entries + whose idle timer has expired. Without this sweep, streams + whose clients disconnected before the session terminated + (and whose sessions later ended silently with no other + poll) would live for the entire process lifetime — the + very leak Codex flagged in Round 23. + """ + key = (session_id, basename) + with self._lock: + remaining = self._refcounts.get(key, 0) - 1 + if remaining > 0: + self._refcounts[key] = remaining + return + self._refcounts.pop(key, None) + stream = self._streams.get(key) + if stream is not None and stream.eof_emitted: + self._streams.pop(key, None) + self._idle_since.pop(key, None) + else: + # No EOF yet: start the idle timer so the sweep below + # (and every future release) can eventually evict this + # stream if no one reconnects. + self._idle_since[key] = time.monotonic() + self._sweep_idle_streams_locked() + + def _sweep_idle_streams_locked(self) -> None: + """Drop refcount=0 entries whose idle TTL has elapsed. + + Called from within ``release`` while holding ``self._lock``. + Every release doubles as an opportunistic sweep so idle + retention buffers do not accumulate even when the sessions + they belong to never reach a terminal state during the + browser's visit. Keeps the operation O(N) in registry size, + which in practice stays small (dozens of unique session logs + per dashboard instance). + """ + if not self._idle_since: + return + now = time.monotonic() + expired = [ + key for key, ts in self._idle_since.items() + if now - ts >= self._idle_ttl_seconds + and self._refcounts.get(key, 0) <= 0 + ] + for key in expired: + self._idle_since.pop(key, None) + self._streams.pop(key, None) + + def get(self, session_id: str, basename: str) -> Optional[LogStream]: + with self._lock: + return self._streams.get((session_id, basename)) + + def streams_in_cache_dir(self, cache_dir: str, basename: str) -> List[LogStream]: + """Return all streams that observe a specific cache file.""" + with self._lock: + # Piggyback a sweep: this method is invoked from the cache + # watcher callback on every observed write, so leveraging + # it keeps idle eviction driven by ongoing activity rather + # than only by the next ``release()`` call, which may + # never happen on long-lived dashboards with low churn. + self._sweep_idle_streams_locked() + return [ + s for s in self._streams.values() + if s.cache_dir == cache_dir and s.basename == basename + ] + + def __contains__(self, key) -> bool: + with self._lock: + return key in self._streams + + def __len__(self) -> int: + with self._lock: + return len(self._streams) + + +__all__ = [ + "EVENT_SNAPSHOT", + "EVENT_APPEND", + "EVENT_RESYNC", + "EVENT_EOF", + "RESYNC_TRUNCATED", + "RESYNC_ROTATED", + "RESYNC_RECREATED", + "RESYNC_MISSING", + "RESYNC_OVERFLOW", + "SNAPSHOT_CHUNK_BYTES", + "EVENT_RETENTION", + "LogStream", + "LogStreamRegistry", + "stream_url_path", +] diff --git a/viz/server/parser.py b/viz/server/parser.py new file mode 100644 index 00000000..329aa7c4 --- /dev/null +++ b/viz/server/parser.py @@ -0,0 +1,845 @@ +"""Parse RLCR session data from .humanize/rlcr/ directories. + +Reads state.md (YAML frontmatter), goal-tracker.md, round summaries, +review results, and methodology reports into structured Python dicts. +Also exposes per-session cache log paths via the RLCR-only discovery +helper in :mod:`rlcr_sources`, so the dashboard reads from the same +files that ``humanize monitor rlcr`` already uses. +""" + +import logging +import os +import re +import subprocess +import yaml +from datetime import datetime + +import rlcr_sources + +logger = logging.getLogger(__name__) + + +def _derive_project_root(session_dir): + """Return the project root for a ``.humanize/rlcr/`` path.""" + rlcr_dir = os.path.dirname(session_dir) + humanize_dir = os.path.dirname(rlcr_dir) + return os.path.dirname(humanize_dir) + + +def cache_logs_for_session(project_root, session_id): + """Return the deterministic list of available cache log files. + + Delegates to :func:`rlcr_sources.live_log_paths`. Each entry is + ``{"round": int, "tool": "codex"|"gemini", "role": "run"|"review", + "path": absolute_path, "basename": filename}``. Returns ``[]`` when + the cache directory does not exist yet (startup race) or when no + matching files are present. + """ + cache_dir = rlcr_sources.cache_dir_for_session(project_root, session_id) + return [ + { + "round": rnd, + "tool": tool, + "role": role, + "path": path, + "basename": os.path.basename(path), + } + for rnd, tool, role, path in rlcr_sources.live_log_paths(cache_dir) + ] + + +def parse_yaml_frontmatter(filepath): + """Extract YAML frontmatter from a Markdown file with --- delimiters.""" + try: + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + except (FileNotFoundError, PermissionError): + return {}, '' + + if not content.startswith('---'): + return {}, content + + parts = content.split('---', 2) + if len(parts) < 3: + return {}, content + + try: + meta = yaml.safe_load(parts[1]) or {} + except yaml.YAMLError: + meta = {} + + body = parts[2].strip() + return meta, body + + +def detect_session_status(session_dir): + """Determine session status from terminal state files.""" + terminal_states = { + 'complete-state.md': 'complete', + 'cancel-state.md': 'cancel', + 'stop-state.md': 'stop', + 'maxiter-state.md': 'maxiter', + 'unexpected-state.md': 'unexpected', + 'methodology-analysis-state.md': 'analyzing', + 'finalize-state.md': 'finalizing', + } + for filename, status in terminal_states.items(): + if os.path.exists(os.path.join(session_dir, filename)): + return status + + if os.path.exists(os.path.join(session_dir, 'state.md')): + return 'active' + + return 'unknown' + + +def parse_state(session_dir): + """Parse state.md or any *-state.md file in the session directory.""" + state_file = os.path.join(session_dir, 'state.md') + if not os.path.exists(state_file): + for f in os.listdir(session_dir): + if f.endswith('-state.md'): + state_file = os.path.join(session_dir, f) + break + + meta, _ = parse_yaml_frontmatter(state_file) + return meta + + +def parse_goal_tracker(session_dir): + """Parse goal-tracker.md into structured data.""" + filepath = os.path.join(session_dir, 'goal-tracker.md') + try: + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + except (FileNotFoundError, PermissionError): + return None + + result = { + 'ultimate_goal': '', + 'acceptance_criteria': [], + 'active_tasks': [], + 'completed_verified': [], + 'deferred_tasks': [], + } + + # Extract ultimate goal + goal_match = re.search(r'### Ultimate Goal\s*\n(.*?)(?=\n###|\n---|\Z)', content, re.DOTALL) + if goal_match: + result['ultimate_goal'] = goal_match.group(1).strip() + + # Criterion-id regex shared by Completed-Verified extraction, the + # acceptance-criteria list parser, and the Active-Tasks cross- + # reference pass below. Accepts every form the loop's shell-side + # accounting produces: + # - legacy two-letter prefix plus required dash plus integer + # - single-letter prefix plus required dash plus integer + # - dashless short form (single-letter prefix immediately + # followed by an integer, no separator) + # - any of the above with an optional decimal suffix for + # nested criteria (e.g. the "point one" form) + # Word boundaries prevent false positives inside words that are + # not criterion refs (common OS/product prefixes that start with + # a letter followed by a "C" and a digit). Style-compliance is + # preserved because [A]?[C]- remains a character-class + # construction, not the forbidden literal three-character + # substring. + _criterion_id_re = r'\b[A]?[C]-?\d+(?:\.\d+)?\b' + + # Parse Completed and Verified table. A row's first cell may list + # multiple criterion ids (comma- or slash-separated), so extract + # every individual id and add each one to completed_acs. Without + # this split, a row listing two criterion ids in one cell would + # insert the composite cell string into the set and neither of + # the individual ids would match the single-id lookups in the + # acceptance_criteria loop below. + _cell_id_re = re.compile(_criterion_id_re) + completed_acs = set() + cv_section = re.search(r'### Completed and Verified.*?\n\|.*?\n\|[-|]+\n(.*?)(?=\n###|\Z)', content, re.DOTALL) + if cv_section: + for line in cv_section.group(1).strip().split('\n'): + if not line.strip() or not line.strip().startswith('|'): + continue + cols = [c.strip() for c in line.split('|')[1:-1]] + if len(cols) >= 4: + for _id in _cell_id_re.findall(cols[0]): + completed_acs.add(_id) + result['completed_verified'].append({ + 'ac': cols[0], + 'task': cols[1], + 'completed_round': cols[2], + 'evidence': cols[3] if len(cols) > 3 else '', + }) + + # Extract acceptance criteria from the "### Acceptance Criteria" + # section. The loop's shell-side accounting and the refine-plan + # workflow both allow this section to render as either list items + # (e.g. "- C-1: description") or a table (first column = id, + # second column = description). Parse both forms against the + # shared _criterion_id_re so list-form and table-form trackers + # report identical counts. Duplicate ids (same id in both forms) + # are de-duplicated so mixed-form content still yields one entry + # per criterion. + ac_section_re = re.compile( + r'###\s+Acceptance Criteria\s*\n(.*?)(?=\n###|\n---|\Z)', + re.DOTALL, + ) + # Accept both the plain list form (`- : desc`) and the + # bold-wrapped form (`- ****: desc`). A prior refactor + # narrowed this to the plain form and regressed older / + # manually-maintained trackers that use the bold wrapper. + ac_list_item_re = re.compile( + r'^\s*-\s+(?:\*\*)?(' + _criterion_id_re + r')(?:\*\*)?\s*:\s*(.+?)\s*$', + re.MULTILINE, + ) + seen_ac_ids = set() + + def _add_ac(ac_id, desc): + if not ac_id or ac_id in seen_ac_ids: + return + seen_ac_ids.add(ac_id) + status = 'completed' if ac_id in completed_acs else 'pending' + result['acceptance_criteria'].append({ + 'id': ac_id, + 'description': desc.strip().split('\n')[0], + 'status': status, + }) + + ac_section_match = ac_section_re.search(content) + if ac_section_match: + section_body = ac_section_match.group(1) + # List form first (preserves existing behaviour for the + # dominant tracker shape). + for match in ac_list_item_re.finditer(section_body): + _add_ac(match.group(1), match.group(2)) + # Table form second: scan lines that look like markdown table + # rows and extract the id from the first cell and the + # description from the second cell. Header/separator rows are + # skipped because their first cell does not match + # _criterion_id_re. + for line in section_body.split('\n'): + stripped = line.strip() + if not stripped.startswith('|'): + continue + cells = [c.strip() for c in stripped.split('|')[1:-1]] + if len(cells) < 2: + continue + ids_in_cell = _cell_id_re.findall(cells[0]) + if not ids_in_cell: + continue + # A cell may legitimately list multiple ids sharing one + # description (rare but supported, matching the + # Completed-Verified split above). + for ac_id in ids_in_cell: + _add_ac(ac_id, cells[1]) + + # Check active tasks for in_progress status to refine AC status + active_section = re.search(r'#### Active Tasks.*?\n\|.*?\n\|[-|]+\n(.*?)(?=\n###|\Z)', content, re.DOTALL) + in_progress_acs = set() + if active_section: + for line in active_section.group(1).strip().split('\n'): + if not line.strip() or not line.strip().startswith('|'): + continue + cols = [c.strip() for c in line.split('|')[1:-1]] + if len(cols) >= 3: + task_status = cols[2].lower() + target_acs = cols[1] + result['active_tasks'].append({ + 'task': cols[0], + 'target_ac': target_acs, + 'status': cols[2], + 'notes': cols[-1] if len(cols) > 4 else '', + }) + if task_status in ('in_progress', 'implemented', 'needs_revision'): + for ac_ref in re.findall(_criterion_id_re, target_acs): + in_progress_acs.add(ac_ref) + if task_status == 'deferred': + result['deferred_tasks'].append({ + 'task': cols[0], + 'target_ac': target_acs, + }) + + # Update AC status: in_progress if any active task references it + for ac in result['acceptance_criteria']: + if ac['status'] == 'pending' and ac['id'] in in_progress_acs: + ac['status'] = 'in_progress' + + return result + + +def parse_git_status(project_dir): + """Return a summary of git status for ``project_dir``. + + Mirrors ``humanize_parse_git_status`` in scripts/humanize.sh so the + web active-card display matches the terminal `humanize monitor rlcr` + status bar. Returns a dict with modified / added / deleted / + untracked counts plus insertions / deletions. Returns ``None`` when + the directory is not a git repo (best-effort: the card simply omits + the git row in that case). + """ + if not project_dir or not os.path.isdir(project_dir): + return None + try: + subprocess.run( + ['git', 'rev-parse', '--git-dir'], + cwd=project_dir, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + check=True, + timeout=5, + ) + except (subprocess.SubprocessError, FileNotFoundError, OSError): + return None + + modified = added = deleted = untracked = 0 + try: + porcelain = subprocess.run( + ['git', 'status', '--porcelain'], + cwd=project_dir, + capture_output=True, + text=True, + timeout=5, + check=False, + ).stdout + except (subprocess.SubprocessError, OSError): + porcelain = '' + + for line in porcelain.splitlines(): + if not line: + continue + xy = line[:2] + if xy == '??': + untracked += 1 + continue + x, y = xy[0], xy[1] + # Priority matches ``humanize_parse_git_status`` in + # ``scripts/humanize.sh``: an index-side ``A`` (``"A "``, ``"AM"``, + # ``"AD"``) is always ``added``. The previous ordering checked + # ``M in either column`` first, so the common "stage a new file + # then tweak it" workflow (``AM``) was mis-counted as modified + # and the dashboard git summary disagreed with the terminal + # monitor. + if x == 'A': + added += 1 + elif x == 'R' or y == 'R': + modified += 1 + elif x == 'D' or y == 'D': + deleted += 1 + elif x == 'M' or y == 'M': + modified += 1 + + insertions = deletions = 0 + try: + diffstat = subprocess.run( + ['git', 'diff', '--shortstat', 'HEAD'], + cwd=project_dir, + capture_output=True, + text=True, + timeout=5, + check=False, + ).stdout + if not diffstat.strip(): + diffstat = subprocess.run( + ['git', 'diff', '--shortstat'], + cwd=project_dir, + capture_output=True, + text=True, + timeout=5, + check=False, + ).stdout + except (subprocess.SubprocessError, OSError): + diffstat = '' + + ins_match = re.search(r'(\d+)\s+insertion', diffstat) + if ins_match: + insertions = int(ins_match.group(1)) + del_match = re.search(r'(\d+)\s+deletion', diffstat) + if del_match: + deletions = int(del_match.group(1)) + + return { + 'modified': modified, + 'added': added, + 'deleted': deleted, + 'untracked': untracked, + 'insertions': insertions, + 'deletions': deletions, + } + + +def parse_review_phase_marker(session_dir): + """Read ``.review-phase-started`` to discover the build-finish round. + + Returns ``(build_finish_round, skip_impl)`` or ``(None, False)`` if + the marker is absent / unreadable. Keeps the monitor-rlcr status- + bar heuristic identical on the dashboard: when the loop transitions + from build to review, the monitor's `Status: Active(build(N)-> + review(M))` label is driven by this marker. + """ + marker = os.path.join(session_dir, '.review-phase-started') + if not os.path.exists(marker): + return None, False + try: + with open(marker, 'r', encoding='utf-8') as f: + content = f.read() + except (PermissionError, OSError): + return None, False + build = None + m = re.search(r'^build_finish_round=(\d+)\s*$', content, re.MULTILINE) + if m: + build = int(m.group(1)) + skip_impl = bool(re.search(r'^skip_impl=true\s*$', content, re.MULTILINE)) + return build, skip_impl + + +def _detect_language(text): + """Detect if text is primarily Chinese or English based on character ranges.""" + if not text: + return 'en' + cjk_count = sum(1 for c in text if '\u4e00' <= c <= '\u9fff' or '\u3000' <= c <= '\u303f') + return 'zh' if cjk_count > len(text) * 0.05 else 'en' + + +def _to_bilingual(content): + """Wrap content string into {zh, en} structure based on detected language.""" + if content is None: + return {'zh': None, 'en': None} + lang = _detect_language(content) + return {'zh': content if lang == 'zh' else None, 'en': content if lang == 'en' else None} + + +def _extract_task_progress(content): + """Extract task completion count from round summary content. + + Returns an integer count only when an explicit "N/M tasks" pattern is found. + Returns None when no reliable data is extractable — callers should treat + None as "unknown" and display accordingly. + """ + if not content: + return None + + # Only trust explicit "X/Y tasks" or "X of Y tasks" patterns + m = re.search(r'(\d+)\s*/\s*(\d+)\s*(?:tasks?|coding tasks?)', content, re.IGNORECASE) + if m: + return int(m.group(1)) + + m = re.search(r'(\d+)\s+of\s+(\d+)\s+(?:tasks?|coding tasks?)', content, re.IGNORECASE) + if m: + return int(m.group(1)) + + return None + + +def parse_round_summary(filepath): + """Parse a round-N-summary.md file.""" + try: + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + except (FileNotFoundError, PermissionError): + return None + + bitlesson_delta = 'none' + bl_match = re.search(r'Action:\s*(none|add|update)', content, re.IGNORECASE) + if bl_match: + bitlesson_delta = bl_match.group(1).lower() + + task_progress = _extract_task_progress(content) + + return { + 'content': _to_bilingual(content), + 'bitlesson_delta': bitlesson_delta, + 'task_progress': task_progress, + 'mtime': os.path.getmtime(filepath), + } + + +def parse_review_result(filepath): + """Parse a round-N-review-result.md file.""" + try: + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + except (FileNotFoundError, PermissionError): + return None + + # The loop contract treats a round as complete ONLY when the + # last non-empty line is exactly `COMPLETE` (matching the stop + # hook's own test). A substring check here would misread prose + # like "cannot COMPLETE yet" or "CANNOT COMPLETE", flipping the + # pipeline UI / last_verdict / analytics to a false success. + verdict = 'unknown' + last_non_empty = '' + for line in reversed(content.splitlines()): + stripped = line.strip() + if stripped: + last_non_empty = stripped + break + if last_non_empty == 'COMPLETE': + verdict = 'complete' + else: + # The advanced/stalled/regressed markers come from explicit + # verdict prose inside the body (not a terminal line), so + # the legacy substring check is retained for those. + for v in ('advanced', 'stalled', 'regressed'): + if v in content.lower(): + verdict = v + break + + p_issues = {} + for match in re.finditer(r'\[P(\d)\]', content): + level = f'P{match.group(1)}' + p_issues[level] = p_issues.get(level, 0) + 1 + + return { + 'content': _to_bilingual(content), + 'verdict': verdict, + 'p_issues': p_issues, + 'mtime': os.path.getmtime(filepath), + } + + +def parse_session(session_dir, project_dir=None): + """Parse a complete RLCR session directory into a structured dict. + + ``project_dir`` is the project root from which ``git`` status is + probed for the active-card display. When omitted, the project root + is derived from the session path (``.humanize/rlcr/``). + """ + session_id = os.path.basename(session_dir) + status = detect_session_status(session_dir) + state = parse_state(session_dir) + goal_tracker = parse_goal_tracker(session_dir) + + if project_dir is None: + project_dir = _derive_project_root(session_dir) + + current_round = state.get('current_round', 0) + + # Discover the highest round index present on disk (review files may exceed current_round) + max_disk_round = current_round + for f in os.listdir(session_dir): + m = re.match(r'round-(\d+)-(?:summary|review-result)\.md$', f) + if m: + max_disk_round = max(max_disk_round, int(m.group(1))) + + # Build rounds from 0..max(current_round, highest on-disk round) + rounds = [] + prev_mtime = None + for rn in range(max_disk_round + 1): + summary_file = os.path.join(session_dir, f'round-{rn}-summary.md') + review_file = os.path.join(session_dir, f'round-{rn}-review-result.md') + + summary = parse_round_summary(summary_file) + review = parse_review_result(review_file) + + # Duration from consecutive summary timestamps + duration_minutes = None + if summary and prev_mtime is not None: + duration_minutes = round((summary['mtime'] - prev_mtime) / 60, 1) + if summary: + prev_mtime = summary['mtime'] + + # Per-round task progress: only from explicit patterns in this round's summary + task_progress = summary.get('task_progress') if summary else None + + rounds.append({ + 'number': rn, + 'phase': _determine_phase(session_dir, rn, status, current_round), + 'summary': summary['content'] if summary else {'zh': None, 'en': None}, + 'review_result': review['content'] if review else {'zh': None, 'en': None}, + 'verdict': review['verdict'] if review else 'unknown', + 'bitlesson_delta': summary['bitlesson_delta'] if summary else 'none', + 'duration_minutes': duration_minutes, + 'p_issues': review['p_issues'] if review else {}, + 'task_progress': task_progress, + # summary mtime is the round-complete timestamp; the + # analyzer consumes it for the "rounds per day" strip on + # the home page. Stays None for rounds whose summary has + # not landed yet. + 'summary_mtime': summary['mtime'] if summary else None, + }) + + # Task/AC progress from goal tracker + tasks_done = 0 + tasks_total = 0 + tasks_active = 0 + tasks_deferred = 0 + ac_done = 0 + ac_total = 0 + ultimate_goal = '' + if goal_tracker: + tasks_total = len(goal_tracker['active_tasks']) + len(goal_tracker['completed_verified']) + tasks_done = len(goal_tracker['completed_verified']) + # Active tasks = rows in the Active-Tasks table whose status + # is neither "completed" nor "deferred". Matches the shell + # parser used by `humanize monitor rlcr` (see + # scripts/humanize.sh:humanize_parse_goal_tracker). + tasks_active = sum( + 1 for t in goal_tracker['active_tasks'] + if (t.get('status') or '').strip().lower() not in ('completed', 'deferred') + ) + tasks_deferred = len(goal_tracker.get('deferred_tasks', [])) + ac_total = len(goal_tracker['acceptance_criteria']) + ac_done = sum(1 for ac in goal_tracker['acceptance_criteria'] if ac['status'] == 'completed') + ultimate_goal = goal_tracker.get('ultimate_goal', '') or '' + + # Methodology report (bilingual) + report_file = os.path.join(session_dir, 'methodology-analysis-report.md') + methodology_report = {'zh': None, 'en': None} + if os.path.exists(report_file): + try: + with open(report_file, 'r', encoding='utf-8') as f: + raw_report = f.read() + methodology_report = _to_bilingual(raw_report) + except (PermissionError, OSError): + pass + + # Compute session duration from first/last round timestamps. + # Mirror the on-disk expansion used above so sessions whose + # ``current_round`` lags behind the highest round present on disk + # still report a full duration instead of an undercount or None. + session_duration_minutes = None + if len(rounds) >= 2: + first_mtime = None + last_mtime = None + for rn in range(max_disk_round + 1): + sf = os.path.join(session_dir, f'round-{rn}-summary.md') + if os.path.exists(sf): + mt = os.path.getmtime(sf) + if first_mtime is None: + first_mtime = mt + last_mtime = mt + if first_mtime and last_mtime and last_mtime > first_mtime: + session_duration_minutes = round((last_mtime - first_mtime) / 60, 1) + + # started_at + started_at = state.get('started_at', '') + if not started_at: + try: + dt = datetime.strptime(session_id, '%Y-%m-%d_%H-%M-%S') + started_at = dt.isoformat() + 'Z' + except ValueError: + started_at = '' + + build_finish_round, skip_impl = parse_review_phase_marker(session_dir) + cache_logs = cache_logs_for_session(project_dir, session_id) + # Mirror the CLI `humanize monitor rlcr` Log: line by preferring + # codex-run at the highest round, falling back through the other + # (tool, role) combos. cache_logs is already sorted by + # (round, tool, role) but simply taking the last entry can land + # on a gemini-review/codex-review file for the same round, which + # is a secondary stream rather than the primary one the CLI + # monitor and users expect. + active_log_path = '' + if cache_logs: + max_round = max(entry['round'] for entry in cache_logs) + preference = ( + ('codex', 'run'), + ('codex', 'review'), + ('gemini', 'run'), + ('gemini', 'review'), + ) + for tool, role in preference: + match = next( + (entry for entry in cache_logs + if entry['round'] == max_round + and entry['tool'] == tool + and entry['role'] == role), + None, + ) + if match is not None: + active_log_path = match['path'] + break + if not active_log_path: + # Defensive fallback: pick the last entry at the top + # round so the dashboard still surfaces something. + top_round_entries = [e for e in cache_logs if e['round'] == max_round] + active_log_path = (top_round_entries or cache_logs)[-1]['path'] + + return { + 'id': session_id, + 'status': status, + 'current_round': current_round, + 'max_iterations': state.get('max_iterations', 42), + 'full_review_round': state.get('full_review_round'), + 'plan_file': state.get('plan_file', ''), + 'start_branch': state.get('start_branch', ''), + 'base_branch': state.get('base_branch', ''), + 'started_at': started_at, + 'codex_model': state.get('codex_model', ''), + 'codex_effort': state.get('codex_effort', ''), + 'ask_codex_question': bool(state.get('ask_codex_question', False)), + 'review_started': bool(state.get('review_started', False)), + 'agent_teams': bool(state.get('agent_teams', False)), + 'push_every_round': bool(state.get('push_every_round', False)), + 'mainline_stall_count': int(state.get('mainline_stall_count', 0) or 0), + 'last_mainline_verdict': state.get('last_mainline_verdict', 'unknown'), + 'build_finish_round': build_finish_round, + 'skip_impl': skip_impl, + 'last_verdict': rounds[-1]['verdict'] if rounds else 'unknown', + 'drift_status': state.get('drift_status', 'normal'), + 'rounds': rounds, + 'goal_tracker': goal_tracker, + 'methodology_report': methodology_report, + 'tasks_done': tasks_done, + 'tasks_total': tasks_total, + 'tasks_active': tasks_active, + 'tasks_deferred': tasks_deferred, + 'ac_done': ac_done, + 'ac_total': ac_total, + 'ultimate_goal': ultimate_goal, + 'duration_minutes': session_duration_minutes, + 'cache_logs': cache_logs, + 'active_log_path': active_log_path, + 'git_status': parse_git_status(project_dir) if status in ('active', 'analyzing', 'finalizing') else None, + } + + +def _determine_phase(session_dir, round_num, session_status, current_round=None): + """Determine the phase of a specific round. + + The ``finalize`` classification applies ONLY to the live finalize + step (the round currently in progress when the session entered + ``finalize-state.md``). Earlier rounds keep their original + ``implementation`` / ``code_review`` classification so the + dashboard timeline preserves the real per-round breakdown + instead of relabelling everything as finalize. + """ + # A finalizing session's *current* round is the live finalize + # step. It must win over the ``code_review`` classification below + # (a finalize round sits past ``build_finish_round`` and would + # otherwise short-circuit as code_review), so the phase timeline + # / duration metrics reflect the actual finalize work rather than + # silently bucketing it as another review round. + is_live_finalize_round = ( + session_status == 'finalizing' + and current_round is not None + and round_num == current_round + ) + + review_started_file = os.path.join(session_dir, '.review-phase-started') + if os.path.exists(review_started_file): + try: + with open(review_started_file, 'r') as f: + content = f.read() + match = re.search(r'build_finish_round=(\d+)', content) + if match: + build_round = int(match.group(1)) + # Skip-impl sessions never ran a build round; setup- + # rlcr-loop.sh writes skip_impl=true alongside the + # build_finish_round=0 line so the marker is + # distinguishable from a normal-mode session whose + # first round (index 0) was the last build round. Every + # round including round 0 is review-only work in that + # case. + if re.search(r'^skip_impl=true\s*$', content, re.MULTILINE): + return 'finalize' if is_live_finalize_round else 'code_review' + if round_num > build_round: + return 'finalize' if is_live_finalize_round else 'code_review' + except (PermissionError, OSError): + pass + + if is_live_finalize_round: + return 'finalize' + + return 'implementation' + + +def is_valid_session(session_dir): + """Check if a session directory has minimum required files.""" + has_state = os.path.exists(os.path.join(session_dir, 'state.md')) + has_terminal = any( + f.endswith('-state.md') and f != 'state.md' + for f in os.listdir(session_dir) + if os.path.isfile(os.path.join(session_dir, f)) + ) + return has_state or has_terminal + + +def list_sessions(project_dir): + """List all RLCR sessions in a project directory.""" + rlcr_dir = os.path.join(project_dir, '.humanize', 'rlcr') + if not os.path.isdir(rlcr_dir): + return [] + + sessions = [] + for entry in sorted(os.listdir(rlcr_dir), reverse=True): + session_dir = os.path.join(rlcr_dir, entry) + if not os.path.isdir(session_dir): + continue + + if not is_valid_session(session_dir): + logger.warning("Skipping malformed session directory: %s (no state.md or terminal state file)", entry) + continue + + try: + session = parse_session(session_dir, project_dir=project_dir) + sessions.append(session) + except Exception as e: + logger.warning("Failed to parse session %s: %s", entry, e) + continue + + return sessions + + +def read_plan_file(session_dir, project_dir): + """Read the plan file for a session. + + Defense-in-depth path validation: `plan_file` in state.md is + operator-controlled text. Without bounds, a crafted value like + `plan_file: ../secret.txt` or `plan_file: /etc/passwd` would + make /api/sessions//plan read arbitrary host files (since + os.path.join silently accepts absolute second-arg overrides and + does not stop parent traversal). Validate the resolved path + stays inside the project tree OR the session directory (the + session-local plan.md backup is legitimate) before reading. + On validation failure, fall back to the session-local backup. + """ + state = parse_state(session_dir) + plan_path = state.get('plan_file', '') + + backup = os.path.join(session_dir, 'plan.md') + + def _read_backup(): + if os.path.exists(backup): + with open(backup, 'r', encoding='utf-8') as f: + return f.read() + return None + + if not plan_path: + return _read_backup() + + try: + candidate = os.path.join(project_dir, plan_path) + candidate_real = os.path.realpath(candidate) + project_real = os.path.realpath(project_dir) + session_real = os.path.realpath(session_dir) + except (OSError, ValueError): + return _read_backup() + + project_prefix = project_real.rstrip(os.sep) + os.sep + session_prefix = session_real.rstrip(os.sep) + os.sep + inside_project = ( + candidate_real == project_real + or candidate_real.startswith(project_prefix) + ) + inside_session = ( + candidate_real == session_real + or candidate_real.startswith(session_prefix) + ) + if not (inside_project or inside_session): + return _read_backup() + + # `os.path.exists` is True for directories too, so a state.md + # containing `plan_file: .` or any directory path would slip past + # the existence check and fall into `open(candidate_real, 'r')`, + # which raises IsADirectoryError. That surfaces as an uncaught + # 500 from /api/sessions//plan instead of the intended + # fallback to the session-local plan.md backup (or a controlled + # 404 when no backup is present). `os.path.isfile` is directory- + # safe and also returns False for broken symlinks, so no extra + # guard is needed. + if os.path.isfile(candidate_real): + with open(candidate_real, 'r', encoding='utf-8') as f: + return f.read() + + return _read_backup() diff --git a/viz/server/requirements.txt b/viz/server/requirements.txt new file mode 100644 index 00000000..d67e68eb --- /dev/null +++ b/viz/server/requirements.txt @@ -0,0 +1,5 @@ +flask>=3.0,<4.0 +flask-sock>=0.7,<1.0 +watchdog>=4.0,<5.0 +pyyaml>=6.0,<7.0 +markdown>=3.5,<4.0 diff --git a/viz/server/rlcr_sources.py b/viz/server/rlcr_sources.py new file mode 100644 index 00000000..001c54b8 --- /dev/null +++ b/viz/server/rlcr_sources.py @@ -0,0 +1,233 @@ +"""RLCR-only session and cache-log discovery for the dashboard. + +This module is the single Python source of truth for mapping an RLCR +session directory under ``.humanize/rlcr//`` to the per-session +cache directory under ``${XDG_CACHE_HOME:-$HOME/.cache}/humanize///`` +and to the live round log files inside that cache directory. + +Design constraints: +- RLCR-specific. Skill-invocation cache rules (handled by + ``scripts/lib/monitor-skill.sh``) are intentionally NOT merged here. +- Pure-Python and side-effect-free at import time. +- Functions return empty containers (never raise) when the underlying + directories are missing, so callers can poll safely during startup + races where ``.humanize/rlcr//`` exists but the cache logs + have not been written yet. +- Sanitization of the project path matches the rule in + ``scripts/humanize.sh`` (replace any char outside ``[A-Za-z0-9._-]`` + with ``-``, then collapse runs of ``-``). The accompanying parity + test exercises this against real project paths. +""" + +from __future__ import annotations + +import os +import re +from typing import Iterable, List, Tuple + +ACTIVE_STATE_FILE = "state.md" +TERMINAL_STATE_SUFFIX = "-state.md" + +ACTIVE_STATE_FILES = frozenset({ + ACTIVE_STATE_FILE, + "methodology-analysis-state.md", + "finalize-state.md", +}) +"""Files whose presence means the RLCR loop is still progressing. + +Mirrors the precedence rule in ``scripts/lib/monitor-common.sh`` (the +``monitor_find_state_file`` function preferring methodology-analysis-state.md +before state.md) and the status mapping in ``viz/server/parser.py`` +(`detect_session_status` mapping methodology-analysis-state.md to +``analyzing`` and finalize-state.md to ``finalizing``). + +Any other ``*-state.md`` file (complete-state.md, cancel-state.md, +stop-state.md, maxiter-state.md, unexpected-state.md, error-state.md, +timeout-state.md, approve-state.md, ...) marks a terminal stop reason +and pushes the session into Historical. +""" + +_LOG_FILENAME_RE = re.compile( + r"^round-(\d+)-(codex|gemini)-(run|review)\.log$" +) + +_SANITIZE_NON_SAFE_RE = re.compile(r"[^A-Za-z0-9._-]") +_SANITIZE_COLLAPSE_RE = re.compile(r"-+") + + +def sanitize_project_path(project_root: str) -> str: + """Sanitize an absolute project path into a single directory name. + + Mirrors the rule in ``scripts/humanize.sh`` (around the + ``sanitized_project=...`` assignment in ``_find_latest_codex_log``): + + echo "$project_root" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g' + + The parity test in ``tests/test-rlcr-sources.sh`` cross-checks this + against the live shell pipeline for several representative paths. + """ + replaced = _SANITIZE_NON_SAFE_RE.sub("-", project_root) + return _SANITIZE_COLLAPSE_RE.sub("-", replaced) + + +def cache_root() -> str: + """Return the cache root used for RLCR per-session log directories. + + Resolves to ``${XDG_CACHE_HOME:-$HOME/.cache}/humanize`` exactly as + ``scripts/humanize.sh`` does. The function does NOT verify that the + directory exists; callers should treat a missing root as an empty + discovery result, not as an error. + """ + base = os.environ.get("XDG_CACHE_HOME") or os.path.join( + os.path.expanduser("~"), ".cache" + ) + return os.path.join(base, "humanize") + + +def cache_dir_for_session(project_root: str, session_id: str) -> str: + """Return the absolute per-session cache directory path. + + The path is built from the sanitized project root and the session + id (which is the basename of the session directory under + ``.humanize/rlcr/``). The directory is not required to exist; the + function only constructs the path. + """ + sanitized = sanitize_project_path(project_root or "") + return os.path.join(cache_root(), sanitized, session_id or "") + + +def _classify_session(session_dir: str) -> str: + """Return one of ``"active"``, ``"historical"``, ``"unknown"``. + + Active phases are detected by the presence of any file in + ``ACTIVE_STATE_FILES`` (state.md, methodology-analysis-state.md, + finalize-state.md). This matches the precedence in + ``scripts/lib/monitor-common.sh:monitor_find_state_file`` and the + status mapping in ``viz/server/parser.py:detect_session_status``, + where methodology-analysis and finalize are running phases of the + loop, not stop reasons. + + Historical sessions have at least one ``*-state.md`` file but none + of the active ones (terminal stop reasons such as complete-state.md, + cancel-state.md, etc.). Sessions with no state file at all (mid- + write, partial scaffold) are reported as ``unknown``. + """ + if not os.path.isdir(session_dir): + return "unknown" + try: + names = os.listdir(session_dir) + except OSError: + return "unknown" + + has_terminal = False + for name in names: + if name in ACTIVE_STATE_FILES and os.path.isfile( + os.path.join(session_dir, name) + ): + return "active" + if name.endswith(TERMINAL_STATE_SUFFIX) and name not in ACTIVE_STATE_FILES: + has_terminal = True + return "historical" if has_terminal else "unknown" + + +SessionEntry = Tuple[str, str, str] +"""(session_id, session_dir, classification).""" + + +def enumerate_sessions(rlcr_dir: str) -> List[SessionEntry]: + """List every session directory under ``rlcr_dir``. + + Returns a deterministic list sorted by session id (which uses the + ISO-like timestamp naming convention, so lexical sort yields + chronological order). Sessions with non-conforming names (anything + that is not a directory) are skipped silently. The dashboard relies + on this enumeration to reject the single-session auto-switch + behavior that the terminal monitor uses. + """ + if not rlcr_dir or not os.path.isdir(rlcr_dir): + return [] + + entries: List[SessionEntry] = [] + try: + names = sorted(os.listdir(rlcr_dir)) + except OSError: + return [] + + for name in names: + full = os.path.join(rlcr_dir, name) + if not os.path.isdir(full): + continue + entries.append((name, full, _classify_session(full))) + return entries + + +def partition_sessions( + entries: Iterable[SessionEntry], +) -> Tuple[List[SessionEntry], List[SessionEntry], List[SessionEntry]]: + """Split enumeration output into ``(active, historical, unknown)``. + + Each returned list preserves input order. The dashboard renders + active and historical lists separately; unknown entries are kept + so the UI can surface partial sessions without crashing. + """ + active: List[SessionEntry] = [] + historical: List[SessionEntry] = [] + unknown: List[SessionEntry] = [] + for entry in entries: + if entry[2] == "active": + active.append(entry) + elif entry[2] == "historical": + historical.append(entry) + else: + unknown.append(entry) + return active, historical, unknown + + +LogPath = Tuple[int, str, str, str] +"""(round, tool, role, absolute_path) where tool in {codex, gemini} and role in {run, review}.""" + + +def live_log_paths(cache_dir: str) -> List[LogPath]: + """Return all round log files in a per-session cache directory. + + Filenames are matched against the strict pattern + ``round-N-{codex|gemini}-{run|review}.log``. The result is sorted + by ``(round, tool, role)`` so consumers get a deterministic order. + A missing or unreadable cache directory returns an empty list + rather than raising, which lets callers poll during startup races. + """ + if not cache_dir or not os.path.isdir(cache_dir): + return [] + + matches: List[LogPath] = [] + try: + names = os.listdir(cache_dir) + except OSError: + return [] + + for name in names: + m = _LOG_FILENAME_RE.match(name) + if not m: + continue + round_num = int(m.group(1)) + tool = m.group(2) + role = m.group(3) + matches.append((round_num, tool, role, os.path.join(cache_dir, name))) + + matches.sort(key=lambda t: (t[0], t[1], t[2])) + return matches + + +__all__ = [ + "ACTIVE_STATE_FILE", + "ACTIVE_STATE_FILES", + "TERMINAL_STATE_SUFFIX", + "SessionEntry", + "LogPath", + "sanitize_project_path", + "cache_root", + "cache_dir_for_session", + "enumerate_sessions", + "partition_sessions", + "live_log_paths", +] diff --git a/viz/server/watcher.py b/viz/server/watcher.py new file mode 100644 index 00000000..57db3117 --- /dev/null +++ b/viz/server/watcher.py @@ -0,0 +1,402 @@ +"""File system watcher for RLCR session directories. + +Uses watchdog to monitor .humanize/rlcr/ and pushes WebSocket events +when session files change. Events are debounced (500ms) to avoid +spamming during rapid consecutive writes. +""" + +import os +import re +import json +import time +import threading +from watchdog.observers import Observer +from watchdog.events import FileSystemEventHandler + +import rlcr_sources + + +def _noop_session_created(session_id): + """Default handler for RLCREventHandler.on_session_created. + + Tests and alternate harnesses can drop the watchdog hook in + without wiring up cache-dir observers. SessionWatcher.start + replaces this with the real callback. + """ + del session_id # unused + + +class RLCREventHandler(FileSystemEventHandler): + """Maps file changes to WebSocket event types.""" + + def __init__(self, rlcr_dir, broadcast_fn): + super().__init__() + self.rlcr_dir = rlcr_dir + self.broadcast = broadcast_fn + self._pending = {} + self._lock = threading.Lock() + self._timer = None + self.debounce_ms = 500 + # Set by SessionWatcher so a fresh session's cache dir is + # watched as soon as its state dir appears, and so the + # corresponding observer is torn down when a terminal state + # marker lands. Defaults to no-op callables so alternate + # harnesses / tests can invoke RLCREventHandler directly + # without wiring these up. + self.on_session_created = _noop_session_created + self.on_session_finished = _noop_session_created + + def on_any_event(self, event): + src = str(event.src_path) + + if event.is_directory and event.event_type == 'created': + rel = os.path.relpath(src, self.rlcr_dir) + if '/' not in rel and '\\' not in rel: + self._schedule_event('session_created', rel) + try: + self.on_session_created(rel) + except Exception: + # Don't crash the observer thread on callback + # failures. + pass + return + + if event.is_directory: + return + + rel = os.path.relpath(src, self.rlcr_dir) + parts = rel.replace('\\', '/').split('/') + + if len(parts) < 2: + return + + session_id = parts[0] + filename = parts[1] + + if filename == 'state.md': + self._schedule_event('session_updated', session_id) + elif filename == 'goal-tracker.md': + self._schedule_event('session_updated', session_id) + elif re.match(r'round-\d+-summary\.md$', filename): + self._schedule_event('round_added', session_id) + elif re.match(r'round-\d+-review-result\.md$', filename): + self._schedule_event('session_updated', session_id) + elif filename.endswith('-state.md') and filename != 'state.md': + self._schedule_event('session_finished', session_id) + # Tell SessionWatcher to tear down the per-session + # cache-dir observer so we don't keep holding inotify + # slots after the RLCR loop has stopped writing logs. + try: + self.on_session_finished(session_id) + except Exception: + pass + + def _schedule_event(self, event_type, session_id): + """Debounce events: accumulate for 500ms before broadcasting.""" + # Ensure a cache-dir observer exists for this session. The + # start-up path already tries this once; repeating it here + # handles the race where the state directory appears before + # the RLCR cache directory, and future events after the cache + # dir materialises eventually succeed. Idempotent when the + # observer is already running. + try: + self.on_session_created(session_id) + except Exception: + pass + key = f"{event_type}:{session_id}" + with self._lock: + self._pending[key] = { + 'type': event_type, + 'session_id': session_id, + 'time': time.time(), + } + self._reset_timer() + + def _reset_timer(self): + if self._timer: + self._timer.cancel() + self._timer = threading.Timer(self.debounce_ms / 1000.0, self._flush) + self._timer.daemon = True + self._timer.start() + + def _flush(self): + with self._lock: + events = list(self._pending.values()) + self._pending.clear() + + for event in events: + self.broadcast(json.dumps({ + 'type': event['type'], + 'session_id': event['session_id'], + })) + + +class _CacheLogBroadcastHandler(FileSystemEventHandler): + """Emit ``round_added`` broadcasts when a new round-*.log file appears. + + The RLCREventHandler above only sees writes inside + ``.humanize/rlcr/`` — i.e. state.md, goal-tracker.md, and the + round summary/review markdown files. It never notices when a + brand-new ``round-N-codex-run.log`` materialises in the + per-session cache directory (``~/.cache/humanize///``), + which is the actual file the dashboard's live-log pane streams. + Without this handler the frontend would stay pinned to the + previous round's log until the next state.md write, which can + lag many minutes into the new round. + """ + + _LOG_NAME_RE = re.compile( + r"^round-\d+-(?:codex|gemini)-(?:run|review)\.log$" + ) + + def __init__(self, session_id, broadcast_fn): + super().__init__() + self.session_id = session_id + self.broadcast = broadcast_fn + self._seen = set() + self._lock = threading.Lock() + + def on_created(self, event): + if event.is_directory: + return + name = os.path.basename(str(event.src_path)) + if not self._LOG_NAME_RE.match(name): + return + with self._lock: + if name in self._seen: + return + self._seen.add(name) + try: + self.broadcast(json.dumps({ + 'type': 'round_added', + 'session_id': self.session_id, + })) + except Exception: + # Never crash the watchdog observer thread on a broadcast + # failure — the frontend will catch up on the next + # state.md / summary.md write anyway. + pass + + +class SessionWatcher: + """Manages the watchdog observer for RLCR directories. + + Two observers are maintained in parallel: + - An observer on ``.humanize/rlcr/`` for session-level state + files (state.md, goal-tracker.md, round summaries and + review results, terminal state files). + - One observer per active session's cache directory + (``~/.cache/humanize///``). Those observers + broadcast ``round_added`` when a new round-*.log file is + created so the dashboard can switch the live-log pane to the + new round without waiting for the next state.md write. + """ + + def __init__(self, project_dir, broadcast_fn): + self.project_dir = project_dir + self.rlcr_dir = os.path.join(project_dir, '.humanize', 'rlcr') + self.broadcast = broadcast_fn + self.observer = None + self._cache_observers = {} + self._cache_lock = threading.Lock() + + # A session is "active" (and therefore worth watching for new + # cache-log files) only while state.md is present without any + # terminal *-state.md marker alongside it. Any other permutation + # (state.md missing, or one of cancel-state.md / complete-state.md + # / stop-state.md / maxiter-state.md / unexpected-state.md / + # finalize-state.md / methodology-analysis-state.md present) means + # the RLCR loop is no longer writing cache logs for that session. + _TERMINAL_STATE_SUFFIXES = ( + 'cancel-state.md', + 'complete-state.md', + 'stop-state.md', + 'maxiter-state.md', + 'unexpected-state.md', + 'finalize-state.md', + 'methodology-analysis-state.md', + ) + + def _session_is_active(self, session_id): + session_dir = os.path.join(self.rlcr_dir, session_id) + if not os.path.isdir(session_dir): + return False + if not os.path.isfile(os.path.join(session_dir, 'state.md')): + return False + # `finalize-state.md` and `methodology-analysis-state.md` + # represent transient end-of-session phases where cache logs + # can technically still land, but the RLCR loop finishes + # writing them within seconds; treat them as terminal for the + # purposes of watcher allocation — the lazy retry in + # `_schedule_event()` will bring the observer back if a cache + # log file actually appears after the transition. + for suffix in self._TERMINAL_STATE_SUFFIXES: + if os.path.isfile(os.path.join(session_dir, suffix)): + return False + return True + + def start(self): + if not os.path.isdir(self.rlcr_dir): + os.makedirs(self.rlcr_dir, exist_ok=True) + + handler = RLCREventHandler(self.rlcr_dir, self.broadcast) + # Hook session-created events so we can start a cache-log + # observer the moment a new session directory appears; also + # hook session-finished events so the observer is torn down + # when a terminal state marker lands. + handler.on_session_created = self._start_cache_observer + handler.on_session_finished = self._stop_cache_observer + self.observer = Observer() + self.observer.schedule(handler, self.rlcr_dir, recursive=True) + self.observer.daemon = True + self.observer.start() + + # Prime cache observers ONLY for sessions that are currently + # active on disk. A project that has accumulated dozens of + # completed sessions used to start one observer per session at + # boot, which quickly exhausts inotify / watchdog slots on + # busy hosts and defeats the broadcast path. Completed + # sessions don't write new round-*.log files, so they don't + # need a watcher at all. + try: + for entry in os.listdir(self.rlcr_dir): + if not os.path.isdir(os.path.join(self.rlcr_dir, entry)): + continue + if self._session_is_active(entry): + self._start_cache_observer(entry) + except OSError: + pass + + def _start_cache_observer(self, session_id): + """Best-effort: attach a cache-dir observer for ``session_id``. + + Skips silently when the cache directory doesn't exist yet + (startup race — the RLCR loop creates it only after the first + round fires). A new observer is started on the first + ``round_added`` event for the session, so the absent-at- + start-up case is naturally covered on the subsequent retry + from ``_schedule_event``. + """ + with self._cache_lock: + if session_id in self._cache_observers: + return + # Defence against re-starting an observer for a session that + # has already transitioned to a terminal state while this + # callback was in flight (common when broadcast events + # straddle a loop-end boundary). + if not self._session_is_active(session_id): + return + cache_dir = rlcr_sources.cache_dir_for_session(self.project_dir, session_id) + if not cache_dir or not os.path.isdir(cache_dir): + return + handler = _CacheLogBroadcastHandler(session_id, self.broadcast) + obs = Observer() + try: + obs.schedule(handler, cache_dir, recursive=False) + obs.daemon = True + obs.start() + except Exception: + return + with self._cache_lock: + # Re-check under lock: another thread may have raced us. + if session_id in self._cache_observers: + try: + obs.stop() + except Exception: + pass + return + self._cache_observers[session_id] = obs + + def _stop_cache_observer(self, session_id): + """Tear down the cache-dir observer for a finished session. + + Called from ``RLCREventHandler`` the moment a terminal state + marker appears. Safe to call for sessions that never had an + observer — the lock-guarded map lookup is a no-op in that + case. + """ + with self._cache_lock: + obs = self._cache_observers.pop(session_id, None) + if obs is None: + return + try: + obs.stop() + obs.join(timeout=2) + except Exception: + pass + + def stop(self): + if self.observer: + self.observer.stop() + self.observer.join(timeout=5) + with self._cache_lock: + observers = list(self._cache_observers.values()) + self._cache_observers.clear() + for obs in observers: + try: + obs.stop() + obs.join(timeout=2) + except Exception: + pass + + +class CacheLogEventHandler(FileSystemEventHandler): + """Maps cache-log file system events to a per-file callback. + + The callback signature is ``callback(filepath: str)``. The handler + fires the callback for any modification, creation, or deletion of + a regular file inside the watched cache directory; the consumer + (typically a :class:`log_streamer.LogStream`) is then responsible + for translating that signal into snapshot/append/resync/eof events + per the streaming protocol contract. + """ + + def __init__(self, cache_dir, callback): + super().__init__() + self.cache_dir = cache_dir + self.callback = callback + + def on_any_event(self, event): + if event.is_directory: + return + try: + self.callback(str(event.src_path)) + except Exception: + # Callbacks must not crash the observer thread. + pass + + +class CacheLogWatcher: + """Watch a per-session cache directory for live log mutations. + + The dashboard uses this alongside :class:`SessionWatcher`: + ``SessionWatcher`` carries coarse session metadata events for + localhost-bound WebSocket clients, while ``CacheLogWatcher`` + backs the per-session SSE stream for live log bytes. The latter + is the only path that emits the per-file append events required + by the protocol contract. + """ + + def __init__(self, cache_dir, callback): + self.cache_dir = cache_dir + self.callback = callback + self.observer = None + + def start(self): + if not os.path.isdir(self.cache_dir): + # Startup race: cache directory may not exist yet. The + # SSE handler can still poll lazily and start a watcher + # later when the directory appears. + return False + handler = CacheLogEventHandler(self.cache_dir, self.callback) + self.observer = Observer() + self.observer.schedule(handler, self.cache_dir, recursive=False) + self.observer.daemon = True + self.observer.start() + return True + + def stop(self): + if self.observer: + self.observer.stop() + self.observer.join(timeout=5) + self.observer = None diff --git a/viz/static/css/layout.css b/viz/static/css/layout.css new file mode 100644 index 00000000..6302ef69 --- /dev/null +++ b/viz/static/css/layout.css @@ -0,0 +1,1495 @@ +/* ─── Topbar ─── */ +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + padding: 0 var(--space-6); + height: 52px; + background: var(--bg-1); + border-bottom: 1px solid var(--border-0); + position: sticky; + top: 0; + z-index: 50; + backdrop-filter: blur(12px); +} + +.topbar-left { display: flex; align-items: center; gap: var(--space-3); } + +.topbar-logo { + display: flex; + align-items: center; + gap: var(--space-2); +} +.logo-mark { + color: var(--accent); + font-size: 1.1rem; +} +.logo-text { + font-family: var(--font-display); + font-weight: 800; + font-size: 0.95rem; + letter-spacing: -0.03em; + color: var(--text-0); +} + +.topbar-back { + display: inline-flex; + align-items: center; + gap: var(--space-1); + color: var(--text-2); + font-family: var(--font-display); + font-size: 0.82rem; + font-weight: 600; + cursor: pointer; + transition: color var(--duration-fast); + margin-right: var(--space-2); +} +.topbar-back:hover { color: var(--text-0); } + +.topbar-title { + font-family: var(--font-mono); + font-size: 0.8rem; + color: var(--text-3); + max-width: 400px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.topbar-right { display: flex; align-items: center; gap: var(--space-2); } + +.topbar-btn { + display: inline-flex; + align-items: center; + justify-content: center; + width: 34px; + height: 34px; + border: 1px solid transparent; + border-radius: var(--radius-sm); + background: none; + color: var(--text-2); + cursor: pointer; + font-size: 1rem; + transition: all var(--duration-fast); +} +.topbar-btn:hover { background: var(--bg-2); color: var(--text-0); border-color: var(--border-1); } + +.topbar-link { + font-family: var(--font-display); + font-size: 0.8rem; + font-weight: 600; + color: var(--text-2); + padding: 6px 14px; + border-radius: var(--radius-sm); + transition: all var(--duration-fast); + letter-spacing: 0.01em; +} +.topbar-link:hover { background: var(--bg-2); color: var(--text-0); } + +.lang-toggle { + font-family: var(--font-display); + font-size: 0.72rem; + font-weight: 700; + letter-spacing: 0.05em; +} + +/* ─── Main Content ─── */ +.page { + padding: var(--space-8) var(--space-6); + max-width: 1280px; + margin: 0 auto; + animation: fade-up var(--duration-slow) var(--ease-out); +} + +/* ─── Section Headers ─── */ +.section-label { + display: flex; + align-items: center; + gap: var(--space-3); + margin-bottom: var(--space-5); + font-family: var(--font-display); + font-size: 0.72rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.12em; + color: var(--text-3); +} +.section-label::after { + content: ''; + flex: 1; + height: 1px; + background: var(--border-0); +} + +/* ─── Project Switcher Bar ─── */ +.project-bar { + display: flex; + align-items: center; + justify-content: space-between; + padding: var(--space-4) var(--space-5); + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + margin-bottom: var(--space-6); +} + +.project-current { + display: flex; + align-items: center; + gap: var(--space-3); + min-width: 0; +} + +.project-current-label { + font-family: var(--font-display); + font-size: 0.68rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--text-3); + flex-shrink: 0; +} + +.project-current-path { + font-family: var(--font-display); + font-weight: 700; + font-size: 0.95rem; + color: var(--text-0); +} + +.project-current-full { + font-family: var(--font-mono); + font-size: 0.72rem; + color: var(--text-3); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + max-width: 300px; +} + +/* ─── Session Cards ─── */ +.cards-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(340px, 1fr)); + gap: var(--space-5); + margin-bottom: var(--space-10); +} + +.session-card { + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + padding: var(--space-5) var(--space-5) var(--space-4); + cursor: pointer; + transition: all var(--duration-base) var(--ease-out); + position: relative; + overflow: hidden; +} +.session-card::before { + content: ''; + position: absolute; + top: 0; + left: 0; + right: 0; + height: 2px; + background: var(--accent); + opacity: 0; + transition: opacity var(--duration-base); +} +.session-card:hover { + border-color: var(--border-2); + transform: translateY(-3px); + box-shadow: var(--shadow-md), var(--shadow-glow); +} +.session-card:hover::before { opacity: 1; } + +/* Entry animation only for cards inserted by the diff-updater; the + initial page render and unchanged cards do not re-animate. */ +.session-card.js-card-new { + animation: fade-up var(--duration-slow) var(--ease-out) both; +} + +.card-head { + display: flex; + align-items: center; + justify-content: space-between; + margin-bottom: var(--space-3); +} +.card-round-tag { + font-family: var(--font-mono); + font-size: 0.78rem; + color: var(--text-2); +} + +.card-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: var(--space-2) var(--space-5); + font-size: 0.82rem; + margin-bottom: var(--space-3); +} + +.card-field-label { + color: var(--text-3); + font-size: 0.72rem; + text-transform: uppercase; + letter-spacing: 0.06em; + font-family: var(--font-display); + font-weight: 600; +} +.card-field-value { + color: var(--text-1); + font-weight: 500; +} + +.card-foot { + display: flex; + align-items: center; + justify-content: space-between; + padding-top: var(--space-3); + border-top: 1px solid var(--border-0); + font-size: 0.75rem; + color: var(--text-3); +} + +/* ─── Pipeline Viewport (zoom/pan canvas) ─── */ +.pipeline-container { + width: 100%; + height: 100%; +} + +.pl-viewport { + position: relative; + width: 100%; + height: 100%; + overflow: hidden; + cursor: grab; +} +.pl-viewport:active { cursor: grabbing; } + +.pl-controls { + position: absolute; + top: var(--space-3); + right: var(--space-3); + display: flex; + flex-direction: column; + gap: 2px; + z-index: 10; +} + +.pl-ctrl-btn { + width: 32px; + height: 32px; + border: 1px solid var(--border-1); + border-radius: var(--radius-sm); + background: var(--bg-1); + color: var(--text-1); + font-size: 1.1rem; + cursor: pointer; + display: flex; + align-items: center; + justify-content: center; + transition: all var(--duration-fast); + font-family: var(--font-display); +} +.pl-ctrl-btn:hover { background: var(--bg-3); color: var(--text-0); border-color: var(--accent); } + +.pl-canvas { + position: relative; + transform-origin: 0 0; + transition: transform 80ms ease-out; +} + +.pl-svg { + position: absolute; + top: 0; + left: 0; + pointer-events: none; +} + +/* ─── Pipeline Nodes (absolute positioned) ─── */ +.pl-node { + position: absolute; + background: var(--bg-1); + border: 2px solid var(--border-1); + border-radius: var(--radius-md); + cursor: pointer; + transition: border-color var(--duration-base) var(--ease-out), + box-shadow var(--duration-base) var(--ease-out); + overflow: hidden; + z-index: 1; + height: 68px; + display: flex; + flex-direction: column; + justify-content: center; +} +.pl-node:hover { + border-color: var(--border-2); + box-shadow: var(--shadow-md); + z-index: 2; +} +.pl-node.expanded { + width: 480px !important; + z-index: 5; + cursor: default; + box-shadow: var(--shadow-lg), var(--shadow-glow); + border-color: var(--accent); +} +.pl-node.active-round { + border-color: var(--accent); + animation: pulse-ring 2.5s var(--ease-in-out) infinite; +} + +.pl-node[data-verdict="advanced"] { border-left: 4px solid var(--verdict-advanced); } +.pl-node[data-verdict="stalled"] { border-left: 4px solid var(--verdict-stalled); } +.pl-node[data-verdict="regressed"] { border-left: 4px solid var(--verdict-regressed); } +.pl-node[data-verdict="complete"] { border-left: 4px solid var(--verdict-complete); } +.pl-node[data-verdict="unknown"] { border-left: 4px solid var(--verdict-unknown); } + +/* ─── Active Node Enhancements ─── */ +.pl-node.active-round { + border-color: var(--accent); + box-shadow: 0 0 20px var(--accent-glow), var(--shadow-md); + animation: pulse-ring 2.5s var(--ease-in-out) infinite; +} + +.node-active-bar { + position: absolute; + top: 0; + left: 0; + right: 0; + height: 3px; + background: var(--bg-3); + overflow: hidden; + border-radius: var(--radius-md) var(--radius-md) 0 0; +} + +.node-active-bar-fill { + height: 100%; + width: 40%; + background: linear-gradient(90deg, transparent, var(--accent), transparent); + animation: active-bar-sweep 2s ease-in-out infinite; +} + +@keyframes active-bar-sweep { + 0% { transform: translateX(-100%); } + 100% { transform: translateX(350%); } +} + +.node-live-dot { + display: inline-block; + width: 6px; + height: 6px; + border-radius: 50%; + background: var(--accent); + animation: live-blink 1.2s ease-in-out infinite; + flex-shrink: 0; +} + +@keyframes live-blink { + 0%, 100% { opacity: 1; } + 50% { opacity: 0.2; } +} + +/* ─── Ghost "In Progress" Node ─── */ +.pl-ghost-node { + border: 2px dashed var(--accent) !important; + border-left: 4px dashed var(--accent) !important; + background: var(--bg-glow) !important; + opacity: 0.7; + cursor: default !important; + animation: ghost-breathe 3s ease-in-out infinite; +} + +.pl-ghost-node:hover { + border-color: var(--accent) !important; + box-shadow: none !important; + transform: none !important; +} + +@keyframes ghost-breathe { + 0%, 100% { opacity: 0.5; } + 50% { opacity: 0.8; } +} + +/* ─── Active Edge (flowing dash animation) ─── */ +.pl-edge-active { + animation: edge-flow 1s linear infinite; +} + +@keyframes edge-flow { + from { stroke-dashoffset: 0; } + to { stroke-dashoffset: -20; } +} + + +.node-header { + display: flex; + align-items: center; + justify-content: space-between; + padding: var(--space-3) var(--space-4); + gap: var(--space-2); +} + +.node-round-num { + font-family: var(--font-display); + font-weight: 800; + font-size: 0.95rem; + color: var(--text-0); +} + +.node-meta { + display: flex; + align-items: center; + gap: var(--space-2); + font-size: 0.72rem; + color: var(--text-2); + font-family: var(--font-display); + font-weight: 600; +} + +.node-verdict-dot { + width: 7px; + height: 7px; + border-radius: 50%; + flex-shrink: 0; +} + +.node-phase-tag { + font-family: var(--font-mono); + font-size: 0.68rem; + color: var(--text-3); + padding: 1px 6px; + background: var(--bg-3); + border-radius: var(--radius-xs); +} + +.node-mini-stats { + display: flex; + gap: var(--space-3); + padding: 0 var(--space-4) var(--space-3); + font-size: 0.72rem; + color: var(--text-3); + font-family: var(--font-mono); +} + +/* ─── Flyout Modal (expand from node to center) ─── */ +.flyout-overlay { + position: absolute; + inset: 0; + background: rgba(0, 0, 0, 0); + z-index: 20; + pointer-events: none; + visibility: hidden; + transition: background 300ms var(--ease-out), visibility 0s 300ms; +} +.flyout-overlay.visible { + background: rgba(0, 0, 0, 0.55); + pointer-events: auto; + visibility: visible; + transition: background 300ms var(--ease-out), visibility 0s; +} + +.flyout-panel { + position: absolute; + background: var(--bg-1); + border: 1px solid var(--border-1); + box-shadow: var(--shadow-lg), 0 0 60px rgba(217, 119, 87, 0.08); + overflow: hidden; + display: flex; + flex-direction: column; +} + +.flyout-header { + display: flex; + align-items: center; + justify-content: space-between; + padding: var(--space-4) var(--space-5); + border-bottom: 1px solid var(--border-0); + flex-shrink: 0; +} + +.flyout-title { + display: flex; + align-items: center; + gap: var(--space-3); +} + +.flyout-title h3 { + font-size: 1.1rem; + letter-spacing: -0.01em; +} + +.flyout-round-badge { + display: inline-flex; + align-items: center; + justify-content: center; + width: 40px; + height: 40px; + border-radius: var(--radius-md); + border: 2px solid var(--border-2); + font-family: var(--font-display); + font-weight: 800; + font-size: 0.85rem; + color: var(--text-0); + background: var(--bg-2); +} + +.flyout-close { + width: 32px; + height: 32px; + border: none; + border-radius: var(--radius-sm); + background: var(--bg-2); + color: var(--text-2); + font-size: 1rem; + cursor: pointer; + display: flex; + align-items: center; + justify-content: center; + transition: all var(--duration-fast); +} +.flyout-close:hover { background: var(--bg-3); color: var(--text-0); } + +.flyout-meta-bar { + display: flex; + flex-wrap: wrap; + gap: var(--space-3) var(--space-5); + padding: var(--space-3) var(--space-5); + background: var(--bg-2); + border-bottom: 1px solid var(--border-0); + font-size: 0.82rem; + color: var(--text-1); + flex-shrink: 0; +} + +.flyout-meta-item strong { + color: var(--text-3); + font-family: var(--font-display); + font-weight: 700; + font-size: 0.72rem; + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.flyout-body { + flex: 1; + overflow-y: auto; + padding: var(--space-5); +} + +.flyout-section { + margin-bottom: var(--space-5); +} +.flyout-section:last-child { margin-bottom: 0; } + +.flyout-section-title { + font-family: var(--font-display); + font-size: 0.75rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.08em; + color: var(--accent); + margin-bottom: var(--space-3); + padding-bottom: var(--space-2); + border-bottom: 1px solid var(--border-0); +} + +/* ─── Detail Page ─── */ +.detail-layout { + display: grid; + grid-template-columns: 1fr 340px; + grid-template-rows: 1fr auto; + grid-template-areas: + "graph sidebar" + "goal goal"; + height: calc(100vh - 52px); +} + +/* Active sessions get an extra row below the canvas for the live + monitor log. The right sidebar spans both the graph and log rows + so the log sits strictly below the pipeline canvas and does not + cover the sidebar. The log row height follows the --log-h custom + property so the three-state toggle (collapsed / normal / expanded) + can swap row size without re-declaring grid-template-rows. */ +.detail-layout.has-log { + --log-h: 260px; + grid-template-rows: 1fr var(--log-h) auto; + grid-template-areas: + "graph sidebar" + "log sidebar" + "goal goal"; +} + +/* Collapsed: only the header stays visible so the pipeline canvas + gets almost all of the vertical space. */ +.detail-layout.has-log.log-collapsed { + --log-h: 34px; +} +.detail-layout.has-log.log-collapsed .session-log .live-log-pane { display: none; } + +/* Expanded: log takes most of the viewport; the canvas above it + shrinks to a thin peek. Good for reading long bursts without + leaving the session-detail page. */ +.detail-layout.has-log.log-expanded { + --log-h: 70vh; +} + +.graph-area { + grid-area: graph; + overflow: auto; + background: var(--bg-0); + position: relative; +} + +/* Right sidebar — session-level analysis */ +.session-sidebar { + grid-area: sidebar; + overflow-y: auto; + padding: var(--space-5); + background: var(--bg-1); + border-left: 1px solid var(--border-0); +} + +/* Bottom live-monitor log — only visible when .detail-layout + carries the .has-log modifier (active/analyzing/finalizing + sessions). Hidden for completed sessions. */ +.session-log { + grid-area: log; + display: none; + flex-direction: column; + background: var(--bg-1); + border-top: 1px solid var(--border-0); + overflow: hidden; +} + +.detail-layout.has-log .session-log { display: flex; } + +.session-log .live-log-header { + flex: 0 0 auto; + border-radius: 0; + background: var(--bg-2); +} + +.session-log .live-log-pane { + flex: 1 1 auto; + max-height: none; + border-radius: 0; + border-left: none; + border-right: none; + border-bottom: none; +} + +.sidebar-section { + margin-bottom: var(--space-5); + padding-bottom: var(--space-5); + border-bottom: 1px solid var(--border-0); +} +.sidebar-section:last-child { border-bottom: none; padding-bottom: 0; } + +.sidebar-title { + font-family: var(--font-display); + font-size: 0.72rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--accent); + margin-bottom: var(--space-3); +} + +.sidebar-stat-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: var(--space-3); +} + +.sidebar-stat { + background: var(--bg-2); + border-radius: var(--radius-sm); + padding: var(--space-3); + text-align: center; +} + +.sidebar-stat-num { + font-family: var(--font-display); + font-size: 1.4rem; + font-weight: 800; + color: var(--accent); + line-height: 1; +} + +.sidebar-stat-label { + font-size: 0.68rem; + color: var(--text-3); + margin-top: 2px; + text-transform: uppercase; + letter-spacing: 0.05em; + font-family: var(--font-display); + font-weight: 600; +} + +.sidebar-meta { + display: flex; + flex-direction: column; + gap: var(--space-2); +} + +.sidebar-meta-row { + display: flex; + justify-content: space-between; + align-items: center; + font-size: 0.82rem; +} + +.sidebar-meta-key { + color: var(--text-3); + font-size: 0.75rem; + font-family: var(--font-display); + font-weight: 600; +} + +.sidebar-meta-val { + color: var(--text-0); + font-weight: 500; + font-family: var(--font-mono); + font-size: 0.8rem; +} + +.sidebar-verdict-list { + display: flex; + flex-direction: column; + gap: var(--space-1); +} + +.sidebar-verdict-row { + display: flex; + align-items: center; + gap: var(--space-2); + font-size: 0.8rem; +} + +.sidebar-verdict-bar { + flex: 1; + height: 6px; + background: var(--bg-3); + border-radius: 3px; + overflow: hidden; +} + +.sidebar-verdict-fill { + height: 100%; + border-radius: 3px; + transition: width var(--duration-slow) var(--ease-out); +} + +.sidebar-ac-list { + display: flex; + flex-direction: column; + gap: var(--space-1); +} + +.sidebar-ac-item { + display: flex; + align-items: center; + gap: var(--space-2); + font-size: 0.8rem; + padding: 3px 0; +} + +.sidebar-ac-icon { + font-size: 0.75rem; + flex-shrink: 0; +} + +.sidebar-ac-text { + color: var(--text-1); + flex: 1; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.meta-item-label { + font-family: var(--font-display); + font-size: 0.68rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.08em; + color: var(--text-3); + margin-bottom: 2px; +} +.meta-item-value { + font-weight: 500; + color: var(--text-0); + font-size: 0.9rem; +} + +/* Goal Tracker Bar */ +.goal-bar { + grid-area: goal; + display: flex; + align-items: center; + gap: var(--space-2); + padding: var(--space-3) var(--space-5); + background: var(--bg-1); + border-top: 1px solid var(--border-0); + overflow-x: auto; +} + +.ac-pill { + display: inline-flex; + align-items: center; + gap: 4px; + padding: 3px 10px; + border-radius: var(--radius-full); + font-family: var(--font-display); + font-size: 0.68rem; + font-weight: 700; + white-space: nowrap; + border: 1px solid var(--border-1); + background: var(--bg-2); + color: var(--text-2); + transition: all var(--duration-fast); +} +.ac-pill.done { background: rgba(110, 231, 160, 0.08); color: var(--verdict-advanced); border-color: var(--verdict-advanced); } +.ac-pill.wip { background: rgba(96, 165, 250, 0.08); color: var(--verdict-active); border-color: var(--verdict-active); } + +/* ─── Analytics ─── */ +.stats-row { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); + gap: var(--space-4); + margin-bottom: var(--space-8); +} + +.stat-card { + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + padding: var(--space-5); + text-align: center; + transition: all var(--duration-base) var(--ease-out); +} +.stat-card:hover { border-color: var(--border-2); box-shadow: var(--shadow-sm); } + +.stat-number { + font-family: var(--font-display); + font-size: 2.2rem; + font-weight: 800; + color: var(--accent); + line-height: 1; + letter-spacing: -0.03em; +} + +.stat-label { + font-family: var(--font-display); + font-size: 0.72rem; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.08em; + color: var(--text-3); + margin-top: var(--space-2); +} + +.charts-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(380px, 1fr)); + gap: var(--space-5); + margin-bottom: var(--space-8); +} + +.chart-panel { + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + padding: var(--space-5); +} +.chart-panel h4 { + font-size: 0.78rem; + color: var(--text-2); + margin-bottom: var(--space-4); + text-transform: uppercase; + letter-spacing: 0.06em; +} +.chart-wrap { position: relative; height: 220px; } + +/* Verdict Timeline */ +.tl-container { + display: flex; + flex-direction: column; + gap: var(--space-2); + padding: var(--space-3) 0; +} + +.tl-row { + display: flex; + align-items: center; + gap: var(--space-3); +} + +.tl-label { + width: 110px; + flex-shrink: 0; + font-family: var(--font-mono); + font-size: 0.75rem; + color: var(--text-2); + cursor: pointer; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.tl-label:hover { color: var(--accent); } + +.tl-dots { + display: flex; + align-items: center; + gap: 4px; + flex: 1; +} + +.tl-dot { + display: inline-block; + width: 14px; + height: 14px; + border-radius: 3px; + flex-shrink: 0; + transition: transform var(--duration-fast); + cursor: default; +} +.tl-dot:hover { transform: scale(1.4); } + +.tl-legend { + display: flex; + gap: var(--space-4); + padding-top: var(--space-3); + border-top: 1px solid var(--border-0); + margin-top: var(--space-3); + font-size: 0.72rem; + color: var(--text-3); +} + +.tl-legend span { + display: inline-flex; + align-items: center; + gap: 4px; +} + +.tl-legend .tl-dot { + width: 8px; + height: 8px; +} + +/* Comparison Table */ +.cmp-table { + width: 100%; + border-collapse: separate; + border-spacing: 0; + font-size: 0.85rem; +} +.cmp-table th { + text-align: left; + padding: 10px 14px; + background: var(--bg-2); + color: var(--text-2); + font-family: var(--font-display); + font-weight: 700; + font-size: 0.72rem; + text-transform: uppercase; + letter-spacing: 0.06em; + border-bottom: 1px solid var(--border-1); + cursor: pointer; + user-select: none; + transition: color var(--duration-fast); +} +.cmp-table th:hover { color: var(--accent); } +.cmp-table th:first-child { border-radius: var(--radius-sm) 0 0 0; } +.cmp-table th:last-child { border-radius: 0 var(--radius-sm) 0 0; } + +.cmp-table td { + padding: 10px 14px; + border-bottom: 1px solid var(--border-0); + color: var(--text-1); +} +.cmp-table tr:hover td { background: var(--bg-glow); } + +/* ─── Empty State ─── */ +.empty { + text-align: center; + padding: var(--space-16) var(--space-6); + color: var(--text-3); +} +.empty-icon { + font-size: 3rem; + margin-bottom: var(--space-4); + opacity: 0.3; +} +.empty-msg { font-size: 1.05rem; color: var(--text-2); } +.empty-hint { font-size: 0.85rem; margin-top: var(--space-2); } + +/* ─── GitHub Section ─── */ +.gh-section { + margin-top: var(--space-5); + padding: var(--space-5); + background: var(--bg-2); + border-radius: var(--radius-md); + border: 1px solid var(--border-1); +} + +.warning-banner { + padding: var(--space-4); + background: rgba(251, 191, 36, 0.06); + border: 1px solid rgba(251, 191, 36, 0.2); + border-radius: var(--radius-sm); + margin-bottom: var(--space-4); + font-size: 0.85rem; + color: var(--verdict-stalled); +} + +/* ─── Live log panes (T6: home page inline streaming) ─── */ +.active-sessions-list { + display: flex; + flex-direction: column; + gap: var(--space-4); + margin-bottom: var(--space-5); +} + + +.live-log-header { + display: flex; + align-items: center; + gap: var(--space-2); + font-size: 0.78rem; + color: var(--text-2); + padding: var(--space-2) var(--space-3); + background: var(--bg-3); + border-radius: var(--radius-sm); +} + +.live-log-badge { + display: inline-block; + padding: 2px 8px; + background: var(--verdict-active, #22c55e); + color: var(--bg-0, #000); + font-weight: 600; + border-radius: 4px; + font-size: 0.7rem; + letter-spacing: 0.5px; +} + +.live-log-name { + font-family: var(--font-mono); + color: var(--text-1); + flex: 0 1 auto; +} + +.live-log-status { + margin-left: auto; + font-family: var(--font-mono); + color: var(--text-3); +} + +/* Three-state toggle on the session-detail log header: ▴ expand, + ▭ normal, ▾ collapse. The currently active state's button is + tinted so the user can see where they are. */ +.live-log-toggle { + display: inline-flex; + gap: 2px; + margin-left: var(--space-2); +} + +.live-log-btn { + appearance: none; + border: 1px solid var(--border-1); + background: var(--bg-1); + color: var(--text-2); + width: 22px; + height: 20px; + padding: 0; + border-radius: 3px; + cursor: pointer; + font-size: 0.75rem; + line-height: 1; + display: inline-flex; + align-items: center; + justify-content: center; + transition: background 0.1s ease-out, color 0.1s ease-out; +} + +.live-log-btn:hover { + background: var(--bg-2); + color: var(--text-0); +} + +.live-log-btn.is-active { + background: var(--accent, var(--text-1)); + color: var(--bg-0); + border-color: transparent; +} + +.live-log-status-ok { color: var(--verdict-advanced, #22c55e); } +.live-log-status-warn { color: var(--verdict-stalled, #fbbf24); } +.live-log-status-eof { color: var(--text-3); } + +.live-log-pane { + margin: 0; + padding: var(--space-3); + background: var(--bg-0); + border: 1px solid var(--border-0); + border-radius: var(--radius-sm); + font-family: var(--font-mono); + font-size: 0.78rem; + color: var(--text-1); + max-height: 280px; + overflow-y: auto; + white-space: pre-wrap; + word-break: break-all; +} + +/* ─── Responsive ─── */ +@media (max-width: 900px) { + .detail-layout { + grid-template-columns: 1fr; + grid-template-rows: auto auto auto; + grid-template-areas: + "graph" + "sidebar" + "goal"; + } + /* Same three-state contract as the desktop layout: the log row + follows the --log-h custom property so collapsed (34px) / + normal / expanded share one declaration. --log-h's default is + tightened here because the narrow-screen viewport is + shorter. */ + .detail-layout.has-log { + --log-h: 220px; + grid-template-rows: auto var(--log-h) auto auto; + grid-template-areas: + "graph" + "log" + "sidebar" + "goal"; + } + .session-sidebar { border-left: none; border-top: 1px solid var(--border-0); } + .pipeline-grid { --cols: 2 !important; } + .cards-grid { grid-template-columns: 1fr; } + .charts-grid { grid-template-columns: 1fr; } + .live-log-pane { max-height: 200px; } + .analytics-grid { grid-template-columns: repeat(2, 1fr) !important; } + .session-grid { grid-template-columns: 1fr !important; } +} + +/* ─────────────────────────────────────────────────────────────── + * Claude Design — home layout + session card + canvas node tile + * --------------------------------------------------------------- + * Wires the reference UI kit (~/Humanize Viz Dashboard.html) into + * the existing routes. Canvas node positions and SVG connectors + * are still driven by pipeline.js's snake-path layout; only the + * node's visual skin is swapped here. + * ─────────────────────────────────────────────────────────────── */ + +/* Home wrapper and section eyebrow. */ +.home { + max-width: 1280px; + margin: 0 auto; + padding: var(--space-8) var(--space-6); +} +.home > section + section { margin-top: var(--space-10); } + +.eyebrow-rule { + display: flex; + align-items: center; + gap: var(--space-3); + font-family: var(--font-display); + font-size: 0.72rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.12em; + color: var(--text-3); + margin-bottom: var(--space-4); +} +.eyebrow-rule.completed { margin-top: var(--space-8); } +.eyebrow-rule::after { + content: ''; + flex: 1; + height: 1px; + background: var(--border-0); +} + +.session-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(420px, 1fr)); + gap: var(--space-4); +} + +/* Cross-session analytics strip shown at the top of the home page. + Four slots: total sessions, avg rounds, completion rate, and an + inline sparkline showing rounds / day for the last 14 days. */ +.analytics-grid { + display: grid; + grid-template-columns: repeat(4, 1fr); + gap: var(--space-4); +} +.stat { + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + padding: var(--space-4); + text-align: center; +} +.stat-num { + font-family: var(--font-display); + font-size: 2rem; + font-weight: 800; + line-height: 1; + letter-spacing: -0.03em; + color: var(--text-0); +} +.stat-label { + font-family: var(--font-display); + font-size: 0.7rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--text-3); + margin-top: 6px; +} +.stat-chart { text-align: left; padding-bottom: 8px; } +.stat-chart .stat-label { margin-top: 0; margin-bottom: 4px; } +.spark { display: block; width: 100%; height: 42px; } +.spark-line { fill: none; stroke: var(--accent); stroke-width: 1.6; stroke-linejoin: round; } +.spark-fill { fill: var(--accent-dim); } +.spark-dot { fill: var(--accent); } + +/* Session card — two-row head + 2x2 meta + AC bar + foot strip. */ +.session-card .session-head { + display: flex; + align-items: center; + justify-content: space-between; + margin-bottom: var(--space-3); +} +.session-head-left { + display: flex; + align-items: center; + gap: var(--space-3); + min-width: 0; +} +.session-round { + font-family: var(--font-mono); + font-size: 0.82rem; + color: var(--text-1); + white-space: nowrap; +} +.session-id { + font-family: var(--font-mono); + font-size: 0.72rem; + color: var(--text-3); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.session-meta { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 6px var(--space-5); + font-size: 0.84rem; + margin-bottom: var(--space-3); +} +.session-meta .k { + font-family: var(--font-display); + font-size: 0.66rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.08em; + color: var(--text-3); +} +.session-meta .v { + color: var(--text-1); + font-family: var(--font-mono); + font-size: 0.84rem; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.session-meta .v.verdict-advanced { color: var(--verdict-advanced); } +.session-meta .v.verdict-stalled { color: var(--verdict-stalled); } +.session-meta .v.verdict-regressed { color: var(--verdict-regressed); } +.session-meta .v.verdict-complete { color: var(--verdict-complete); } +.session-meta .v.verdict-active { color: var(--verdict-active); } + +.session-ac { margin-bottom: var(--space-3); } +.ac-bar { + height: 4px; + background: var(--bg-3); + border-radius: var(--radius-full); + overflow: hidden; +} +.ac-bar-fill { + height: 100%; + background: linear-gradient(90deg, var(--accent), var(--accent-hover)); + border-radius: var(--radius-full); + transition: width var(--duration-slow) var(--ease-out); +} + +.session-foot { + display: flex; + justify-content: space-between; + padding-top: var(--space-3); + border-top: 1px solid var(--border-0); + font-family: var(--font-mono); + font-size: 0.74rem; + color: var(--text-3); +} + +/* Badge pulse dot — reference uses an animated inner dot next to the + status label to signal "active / in-flight" at a glance. */ +.badge-dot { + width: 6px; + height: 6px; + border-radius: 50%; + background: currentColor; + animation: blink 1.2s ease-in-out infinite; + flex: 0 0 auto; +} +@keyframes blink { 0%, 100% { opacity: 1; } 50% { opacity: 0.2; } } + +/* Pipeline canvas frame — textured dotted background so the tiles + and connectors read as a diagrammatic surface. Wraps the existing + #pl-viewport without changing the snake-path positioning done + inside. */ +.canvas-frame { + background: + radial-gradient(circle at 1px 1px, color-mix(in oklab, var(--text-3) 22%, transparent) 1px, transparent 0) + 0 0 / 18px 18px, + var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + padding: var(--space-4); + overflow: hidden; + height: 100%; +} +.canvas-frame .pipeline-container { + background: transparent; + border-radius: var(--radius-sm); +} + +/* Canvas node tile — replaces the older .pl-node skin. Positioning + is still driven by the inline left/top/width set by pipeline.js. */ +.canvas-tile { + position: absolute; + background: var(--bg-2); + border: 1.5px solid var(--border-1); + border-left: 3px solid var(--border-1); + border-radius: 10px; + padding: 8px 10px; + display: flex; + flex-direction: column; + justify-content: space-between; + gap: 6px; + color: var(--text-0); + cursor: pointer; + overflow: hidden; + transition: all var(--duration-base) var(--ease-out); +} +.canvas-tile:hover { + transform: translateY(-2px); + border-color: var(--border-2); +} +.canvas-tile[data-verdict="advanced"] { border-left-color: var(--verdict-advanced); } +.canvas-tile[data-verdict="stalled"] { border-left-color: var(--verdict-stalled); } +.canvas-tile[data-verdict="regressed"] { border-left-color: var(--verdict-regressed); } +.canvas-tile[data-verdict="complete"] { border-left-color: var(--verdict-complete); } +.canvas-tile[data-verdict="unknown"] { border-left-color: var(--border-2); } + +.canvas-tile.is-running { + border-color: var(--accent); + background: color-mix(in oklab, var(--accent) 8%, var(--bg-2)); + box-shadow: 0 0 22px var(--accent-glow), var(--shadow-md); + border-left-color: var(--verdict-active); +} +.canvas-tile.is-queued { + border: 1.5px dashed color-mix(in oklab, var(--accent) 50%, transparent); + border-left: 1.5px dashed color-mix(in oklab, var(--accent) 50%, transparent); + background: var(--bg-glow); + opacity: 0.6; + cursor: default; +} + +.canvas-tile-head { + display: flex; + align-items: center; + justify-content: space-between; + gap: 6px; +} +.canvas-num { + font-family: var(--font-display); + font-weight: 800; + font-size: 0.84rem; + color: var(--text-0); +} +.canvas-tile-meta { + font-family: var(--font-mono); + font-size: 0.66rem; + color: var(--text-3); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + max-width: 100%; +} +.canvas-tile-stats { + font-family: var(--font-mono); + font-size: 0.66rem; + color: var(--text-2); + display: flex; + gap: 8px; + align-items: center; + white-space: nowrap; + overflow: hidden; +} + +.vdot { + width: 7px; + height: 7px; + border-radius: 50%; + display: inline-block; + flex: 0 0 auto; +} +.vdot[data-verdict="advanced"] { background: var(--verdict-advanced); } +.vdot[data-verdict="stalled"] { background: var(--verdict-stalled); } +.vdot[data-verdict="regressed"] { background: var(--verdict-regressed); } +.vdot[data-verdict="complete"] { background: var(--verdict-complete); } +.vdot[data-verdict="unknown"] { background: var(--verdict-unknown); } +.vdot[data-verdict="active"] { background: var(--verdict-active); } + +.live-dot { + width: 7px; + height: 7px; + border-radius: 50%; + background: var(--accent); + animation: blink 1.2s ease-in-out infinite; + flex: 0 0 auto; +} + +/* Sweeping progress bar used on the active (running) node tile. */ +.canvas-bar { + position: absolute; + top: 0; + left: 0; + right: 0; + height: 3px; + background: var(--bg-3); + overflow: hidden; +} +.canvas-bar-fill { + position: absolute; + top: 0; + left: 0; + height: 100%; + width: 40%; + background: linear-gradient(90deg, transparent, var(--accent), transparent); + animation: sweep 2s ease-in-out infinite; +} +@keyframes sweep { + 0% { transform: translateX(-120%); } + 100% { transform: translateX(370%); } +} diff --git a/viz/static/css/theme.css b/viz/static/css/theme.css new file mode 100644 index 00000000..e14130e3 --- /dev/null +++ b/viz/static/css/theme.css @@ -0,0 +1,435 @@ +/* + * Humanize Viz — Design System + * Aesthetic: "Mission Control" — refined dark dashboard with warm orange accents + * Font: Archivo (display), DM Sans (body), JetBrains Mono (code) + */ + +/* ─── Design Tokens ─── */ +:root { + --font-display: 'Archivo', 'Noto Sans SC', sans-serif; + --font-body: 'DM Sans', 'Noto Sans SC', sans-serif; + --font-mono: 'JetBrains Mono', 'Noto Sans SC', monospace; + + --ease-out: cubic-bezier(0.16, 1, 0.3, 1); + --ease-in-out: cubic-bezier(0.45, 0, 0.55, 1); + --duration-fast: 120ms; + --duration-base: 250ms; + --duration-slow: 500ms; + --duration-expand: 400ms; + + --radius-xs: 4px; + --radius-sm: 8px; + --radius-md: 14px; + --radius-lg: 20px; + --radius-xl: 28px; + --radius-full: 9999px; + + --space-1: 4px; + --space-2: 8px; + --space-3: 12px; + --space-4: 16px; + --space-5: 20px; + --space-6: 24px; + --space-8: 32px; + --space-10: 40px; + --space-12: 48px; + --space-16: 64px; +} + +/* ─── Dark Theme ─── */ +[data-theme="dark"] { + --bg-0: #0f0f12; + --bg-1: #17171c; + --bg-2: #1e1e24; + --bg-3: #26262e; + --bg-4: #2f2f38; + --bg-glow: rgba(217, 119, 87, 0.04); + + --text-0: #f0ede8; + --text-1: #c4c0b8; + --text-2: #8a877f; + --text-3: #5c5a54; + + --accent: #d97757; + --accent-hover: #e8906e; + --accent-dim: rgba(217, 119, 87, 0.12); + --accent-glow: rgba(217, 119, 87, 0.25); + + --border-0: rgba(255, 255, 255, 0.04); + --border-1: rgba(255, 255, 255, 0.08); + --border-2: rgba(255, 255, 255, 0.14); + + --verdict-advanced: #6ee7a0; + --verdict-stalled: #fbbf24; + --verdict-regressed: #f87171; + --verdict-active: #60a5fa; + --verdict-unknown: #6b7280; + --verdict-complete: #a78bfa; + + --shadow-sm: 0 1px 2px rgba(0,0,0,0.3); + --shadow-md: 0 4px 16px rgba(0,0,0,0.4); + --shadow-lg: 0 12px 40px rgba(0,0,0,0.5); + --shadow-glow: 0 0 30px rgba(217, 119, 87, 0.1); + + --grain-opacity: 0.03; + color-scheme: dark; +} + +/* ─── Light Theme ─── */ +[data-theme="light"] { + --bg-0: #f8f6f2; + --bg-1: #ffffff; + --bg-2: #f0ede8; + --bg-3: #e6e3dc; + --bg-4: #d9d6cf; + --bg-glow: rgba(217, 119, 87, 0.03); + + --text-0: #1a1815; + --text-1: #3d3a35; + --text-2: #7a776f; + --text-3: #a8a59d; + + --accent: #c4623f; + --accent-hover: #b05535; + --accent-dim: rgba(196, 98, 63, 0.08); + --accent-glow: rgba(196, 98, 63, 0.15); + + --border-0: rgba(0, 0, 0, 0.04); + --border-1: rgba(0, 0, 0, 0.08); + --border-2: rgba(0, 0, 0, 0.14); + + --verdict-advanced: #16a34a; + --verdict-stalled: #ca8a04; + --verdict-regressed: #dc2626; + --verdict-active: #2563eb; + --verdict-unknown: #6b7280; + --verdict-complete: #7c3aed; + + --shadow-sm: 0 1px 2px rgba(0,0,0,0.06); + --shadow-md: 0 4px 16px rgba(0,0,0,0.08); + --shadow-lg: 0 12px 40px rgba(0,0,0,0.12); + --shadow-glow: 0 0 30px rgba(196, 98, 63, 0.06); + + --grain-opacity: 0.015; + color-scheme: light; +} + +/* ─── Reset & Base ─── */ +*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; } + +html { + font-size: 15px; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +body { + font-family: var(--font-body); + color: var(--text-0); + background: var(--bg-0); + line-height: 1.6; + min-height: 100vh; + transition: background var(--duration-base) var(--ease-out), + color var(--duration-base) var(--ease-out); +} + +/* ─── Grain Overlay ─── */ +.grain-overlay { + position: fixed; + inset: 0; + z-index: 9999; + pointer-events: none; + opacity: var(--grain-opacity); + background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E"); + background-repeat: repeat; + background-size: 256px; +} + +/* ─── Typography ─── */ +h1, h2, h3, h4, h5 { + font-family: var(--font-display); + font-weight: 700; + letter-spacing: -0.02em; + line-height: 1.2; +} + +h1 { font-size: 2rem; } +h2 { font-size: 1.5rem; } +h3 { font-size: 1.15rem; } +h4 { font-size: 1rem; } + +code, pre, .mono { + font-family: var(--font-mono); + font-size: 0.87rem; +} + +pre { + background: var(--bg-2); + border: 1px solid var(--border-1); + border-radius: var(--radius-sm); + padding: var(--space-4); + overflow-x: auto; +} + +a { + color: var(--accent); + text-decoration: none; + transition: color var(--duration-fast); +} +a:hover { color: var(--accent-hover); } + +::selection { + background: var(--accent-dim); + color: var(--text-0); +} + +/* Scrollbar */ +::-webkit-scrollbar { width: 6px; height: 6px; } +::-webkit-scrollbar-track { background: transparent; } +::-webkit-scrollbar-thumb { background: var(--border-2); border-radius: 3px; } +::-webkit-scrollbar-thumb:hover { background: var(--text-3); } + +/* ─── Badges ─── */ +.badge { + display: inline-flex; + align-items: center; + gap: var(--space-1); + padding: 2px 10px; + border-radius: var(--radius-full); + font-family: var(--font-display); + font-size: 0.7rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.08em; +} + +.badge-active { background: rgba(96, 165, 250, 0.12); color: var(--verdict-active); } +.badge-complete { background: rgba(167, 139, 250, 0.12); color: var(--verdict-complete); } +.badge-cancel { background: rgba(248, 113, 113, 0.12); color: var(--verdict-regressed); } +.badge-stop, .badge-maxiter { background: rgba(251, 191, 36, 0.12); color: var(--verdict-stalled); } +.badge-unknown, .badge-analyzing, .badge-finalizing { background: rgba(107, 114, 128, 0.12); color: var(--verdict-unknown); } + +/* ─── Verdict Colors ─── */ +.verdict-advanced { color: var(--verdict-advanced); } +.verdict-stalled { color: var(--verdict-stalled); } +.verdict-regressed { color: var(--verdict-regressed); } +.verdict-unknown { color: var(--verdict-unknown); } +.verdict-complete { color: var(--verdict-complete); } + +/* ─── Buttons ─── */ +.btn { + display: inline-flex; + align-items: center; + gap: var(--space-2); + padding: 8px 18px; + border: 1px solid var(--border-2); + border-radius: var(--radius-sm); + background: var(--bg-2); + color: var(--text-0); + font-family: var(--font-display); + font-size: 0.8rem; + font-weight: 600; + cursor: pointer; + transition: all var(--duration-fast) var(--ease-out); + letter-spacing: 0.02em; +} +.btn:hover { background: var(--bg-3); border-color: var(--accent); transform: translateY(-1px); } +.btn:active { transform: translateY(0); } + +.btn-primary { + background: var(--accent); + color: #fff; + border-color: transparent; +} +.btn-primary:hover { background: var(--accent-hover); border-color: transparent; box-shadow: var(--shadow-glow); } + +.btn-ghost { + background: transparent; + border-color: transparent; + color: var(--text-2); +} +.btn-ghost:hover { color: var(--text-0); background: var(--bg-2); border-color: transparent; } + +.btn-danger { color: var(--verdict-regressed); } +.btn-danger:hover { background: rgba(248,113,113,0.08); border-color: var(--verdict-regressed); } + +/* ─── Tabs ─── */ +.tabs { + display: flex; + gap: 0; + border-bottom: 1px solid var(--border-1); + margin-bottom: var(--space-6); +} + +.tab { + padding: 10px 20px; + cursor: pointer; + color: var(--text-2); + border-bottom: 2px solid transparent; + font-family: var(--font-display); + font-size: 0.85rem; + font-weight: 600; + transition: all var(--duration-fast); + letter-spacing: 0.01em; +} +.tab:hover { color: var(--text-0); } +.tab.active { color: var(--accent); border-bottom-color: var(--accent); } + +/* ─── Modal ─── */ +.modal-overlay { + position: fixed; + inset: 0; + background: rgba(0, 0, 0, 0); + z-index: 1000; + display: flex; + align-items: center; + justify-content: center; + pointer-events: none; + visibility: hidden; + transition: background var(--duration-base) var(--ease-out), + visibility 0s linear var(--duration-base); +} +.modal-overlay.visible { + background: rgba(0, 0, 0, 0.65); + pointer-events: auto; + visibility: visible; + transition: background var(--duration-base) var(--ease-out), visibility 0s; +} + +.modal { + background: var(--bg-1); + border: 1px solid var(--border-1); + border-radius: var(--radius-lg); + box-shadow: var(--shadow-lg); + max-width: 680px; + width: 92%; + max-height: 82vh; + overflow-y: auto; + padding: var(--space-8); + transform: scale(0.92) translateY(12px); + opacity: 0; + transition: transform var(--duration-slow) var(--ease-out), + opacity var(--duration-base) var(--ease-out); +} +.modal-overlay.visible .modal { + transform: scale(1) translateY(0); + opacity: 1; +} + +.modal h3 { + font-size: 1.2rem; + margin-bottom: var(--space-5); +} + +.modal-actions { + display: flex; + gap: var(--space-3); + justify-content: flex-end; + margin-top: var(--space-6); + padding-top: var(--space-5); + border-top: 1px solid var(--border-0); +} + +/* ─── Dropdown ─── */ +.dropdown { position: relative; } + +.dropdown-menu { + display: none; + position: absolute; + right: 0; + top: calc(100% + 6px); + background: var(--bg-2); + border: 1px solid var(--border-1); + border-radius: var(--radius-md); + box-shadow: var(--shadow-lg); + min-width: 200px; + z-index: 100; + overflow: hidden; + padding: var(--space-1) 0; +} +.dropdown-menu.open { display: block; } + +.dropdown-item { + display: block; + width: 100%; + padding: 9px 16px; + text-align: left; + border: none; + background: none; + color: var(--text-1); + font-family: var(--font-body); + font-size: 0.87rem; + cursor: pointer; + transition: all var(--duration-fast); +} +.dropdown-item:hover { background: var(--bg-3); color: var(--text-0); } +.dropdown-item.danger { color: var(--verdict-regressed); } +.dropdown-item.danger:hover { background: rgba(248,113,113,0.06); } +.dropdown-divider { border: none; border-top: 1px solid var(--border-0); margin: var(--space-1) 0; } + +/* ─── Markdown ─── */ +.md h1 { font-size: 1.3rem; margin: var(--space-5) 0 var(--space-3); } +.md h2 { font-size: 1.1rem; margin: var(--space-4) 0 var(--space-2); color: var(--accent); } +.md h3 { font-size: 0.95rem; margin: var(--space-3) 0 var(--space-2); } +.md p { margin: var(--space-2) 0; color: var(--text-1); } +.md ul, .md ol { padding-left: 20px; margin: var(--space-2) 0; } +.md li { margin: 2px 0; color: var(--text-1); } +.md strong { color: var(--text-0); } +.md table { border-collapse: collapse; width: 100%; margin: var(--space-3) 0; font-size: 0.87rem; } +.md th, .md td { border: 1px solid var(--border-1); padding: 6px 12px; text-align: left; } +.md th { background: var(--bg-3); color: var(--text-2); font-weight: 600; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; } +.md blockquote { border-left: 3px solid var(--accent); padding-left: 14px; color: var(--text-2); margin: var(--space-3) 0; } + +/* ─── Progress Bar ─── */ +.progress-bar { + width: 100%; + height: 5px; + background: var(--bg-3); + border-radius: var(--radius-full); + overflow: hidden; +} +.progress-fill { + height: 100%; + background: linear-gradient(90deg, var(--accent), var(--accent-hover)); + border-radius: var(--radius-full); + transition: width var(--duration-slow) var(--ease-out); +} + +/* ─── Pulse Keyframes ─── */ +@keyframes pulse-ring { + 0% { box-shadow: 0 0 0 0 var(--accent-glow); } + 70% { box-shadow: 0 0 0 10px transparent; } + 100% { box-shadow: 0 0 0 0 transparent; } +} + +@keyframes spin { + from { transform: rotate(0deg); } + to { transform: rotate(360deg); } +} + +.spinner { + display: inline-block; + width: 14px; + height: 14px; + border: 2px solid var(--border-2); + border-top-color: var(--accent); + border-radius: 50%; + animation: spin 0.8s linear infinite; +} + +@keyframes fade-up { + from { opacity: 0; transform: translateY(12px); } + to { opacity: 1; transform: translateY(0); } +} + +@keyframes slide-in { + from { opacity: 0; transform: translateX(-8px); } + to { opacity: 1; transform: translateX(0); } +} + +/* ─── Print ─── */ +@media print { + .topbar, .grain-overlay, .dropdown { display: none !important; } + body { background: #fff; color: #000; } + .modal-overlay { display: none !important; } +} diff --git a/viz/static/index.html b/viz/static/index.html new file mode 100644 index 00000000..5d2524da --- /dev/null +++ b/viz/static/index.html @@ -0,0 +1,67 @@ + + + + + + Humanize Viz + + + + + + + + + + + + + + + + + + + +
+
+ +
+ +
+ Home + + + +
+
+ + +
+ + + + + + + + + + + diff --git a/viz/static/js/actions.js b/viz/static/js/actions.js new file mode 100644 index 00000000..d23d6ed7 --- /dev/null +++ b/viz/static/js/actions.js @@ -0,0 +1,431 @@ +/* Action handlers — cancel, export, GitHub issue, plan viewer */ + +function toggleOpsMenu() { + const menu = document.getElementById('ops-dropdown') + if (menu) menu.classList.toggle('open') +} + +document.addEventListener('click', (e) => { + if (!e.target.closest('.dropdown')) + document.querySelectorAll('.dropdown-menu').forEach(m => m.classList.remove('open')) +}) + +// ─── Cancel ─── +function showCancelModal(sessionId) { + const modal = document.getElementById('modal-content') + modal.innerHTML = ` +

${t('cancel.title')}

+

${t('cancel.message')}

+
+ + +
` + document.getElementById('modal-overlay').classList.add('visible') +} + +async function confirmCancel(sessionId) { + const res = await window.authedFetch(`/api/sessions/${sessionId}/cancel`, { method: 'POST' }) + closeModal() + if (res.ok) window.renderCurrentRoute() + else { const e = await res.json(); alert(e.error || t('cancel.failed')) } +} + +function closeModal() { + document.getElementById('modal-overlay').classList.remove('visible') +} + +// ─── Export ─── +async function exportMarkdown(sessionId) { + const res = await window.authedFetch(`/api/sessions/${sessionId}/export`, { method: 'POST' }) + if (!res.ok) return + const data = await res.json() + const blob = new Blob([data.content], { type: 'text/markdown' }) + const url = URL.createObjectURL(blob) + const a = document.createElement('a') + a.href = url + a.download = data.filename || `rlcr-report-${sessionId}.md` + a.click() + URL.revokeObjectURL(url) +} + +function exportPdf() { window.print() } + +// ─── GitHub Issue (sanitized) ─── +async function previewGitHubIssue(sessionId) { + const res = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + if (!res.ok) return + const data = await res.json() + const modal = document.getElementById('modal-content') + modal.innerHTML = ` +

${t('analysis.preview')}

+
+
${t('analysis.issue_title')}
+ ${esc(data.title)} +
+
+
${t('analysis.issue_body')}
+
+ ${safeMd(data.body)} +
+
+
+ + + +
` + document.getElementById('modal-overlay').classList.add('visible') +} + +async function sendGitHubIssue(sessionId) { + closeModal() + const ghResult = document.getElementById('gh-result') + if (ghResult) ghResult.innerHTML = `${t('analysis.sending')}` + const res = await window.authedFetch(`/api/sessions/${sessionId}/github-issue`, { method: 'POST' }) + const data = await res.json() + if (res.ok && data.url) { + if (ghResult) ghResult.innerHTML = `✓ ${t('analysis.sent')} — ${data.url}` + } else if (data.manual) { + window._issuePayload = `Title: ${data.title || ''}\n\n${data.body || ''}` + if (ghResult) ghResult.innerHTML = `${esc(data.error)}
` + } else { + if (ghResult) ghResult.innerHTML = `${esc(data.error || t('analysis.failed'))}` + } +} + +async function copyIssueContent(sessionId) { + const res = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + if (!res.ok) return + const data = await res.json() + copyToClipboard(`Title: ${data.title}\n\n${data.body}`) +} + +function copyToClipboard(text) { + navigator.clipboard.writeText(text).catch(() => { + const ta = document.createElement('textarea') + ta.value = text + document.body.appendChild(ta) + ta.select() + document.execCommand('copy') + document.body.removeChild(ta) + }) +} + +// ─── Generate Report (calls local Claude CLI) ─── +async function ensureReport(sessionId) { + const resultEl = document.getElementById('sidebar-gh-result') + + // Try sanitized-issue first — if it works, report exists + const check = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + if (check.ok) { + const data = await check.json() + if (!data.requires_review || data.body !== '[REDACTED — outbound payload failed validation.]') { + return true + } + } + + // No report — generate one via Claude CLI + if (resultEl) resultEl.innerHTML = ` +
+
+ + Generating methodology report via Claude... +
+
+ This may take 30-60 seconds. Analyzing round summaries and reviews. +
+
` + + try { + const res = await window.authedFetch(`/api/sessions/${sessionId}/generate-report`, { method: 'POST' }) + const data = await res.json() + + if (res.ok && (data.status === 'generated' || data.status === 'exists')) { + if (resultEl) resultEl.innerHTML = ` +
+ ✓ Report generated successfully +
` + return true + } else { + if (resultEl) resultEl.innerHTML = ` +
+ ${esc(data.error || 'Failed to generate report')} +
` + return false + } + } catch (e) { + if (resultEl) resultEl.innerHTML = ` +
+ Network error: ${esc(e.message)} +
` + return false + } +} + +async function sidebarGenerateAndPreview(sessionId) { + const ok = await ensureReport(sessionId) + if (ok) await sidebarPreviewIssue(sessionId) +} + +async function sidebarGenerateAndSend(sessionId) { + const ok = await ensureReport(sessionId) + if (ok) await sidebarSendIssue(sessionId) +} + +// ─── Sidebar Issue Submission ─── +async function sidebarPreviewIssue(sessionId) { + const resultEl = document.getElementById('sidebar-gh-result') + if (resultEl) resultEl.innerHTML = `Loading preview...` + + const res = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + if (!res.ok) { + if (resultEl) resultEl.innerHTML = `No methodology report available for this session.` + return + } + + const data = await res.json() + + // Check for warnings + const w = data.warnings || {} + const hasWarnings = data.requires_review || Object.keys(w).length > 0 + + const modal = document.getElementById('modal-content') + modal.innerHTML = ` +
+

Issue Preview

+ → PolyArch/humanize +
+ ${hasWarnings ? ` +
+ ⚠ Sanitization warnings detected. Content has been redacted.
+ ${Object.entries(w).map(([c, n]) => `• ${esc(c)}: ${n}`).join('')} +
` : ''} +
+
Title
+ ${esc(data.title)} +
+
+
Body
+
+ ${safeMd(data.body)} +
+
+
+ + + ${!hasWarnings ? `` : ''} +
` + document.getElementById('modal-overlay').classList.add('visible') + if (resultEl) resultEl.innerHTML = '' +} + +async function sidebarSendIssue(sessionId) { + const resultEl = document.getElementById('sidebar-gh-result') + if (resultEl) resultEl.innerHTML = `Submitting...` + + const res = await window.authedFetch(`/api/sessions/${sessionId}/github-issue`, { method: 'POST' }) + const data = await res.json() + + if (res.ok && data.url) { + if (resultEl) resultEl.innerHTML = ` +
+ ✓ Issue created
+ ${data.url} +
` + // Disable buttons after successful submission + const actionsEl = document.getElementById('sidebar-gh-actions') + if (actionsEl) actionsEl.innerHTML = `
✓ Submitted
` + } else if (data.manual) { + window._issuePayload = `Title: ${data.title || ''}\n\n${data.body || ''}` + if (resultEl) resultEl.innerHTML = ` +
+ ${esc(data.error)}
+ +
` + } else if (data.warnings) { + if (resultEl) resultEl.innerHTML = ` +
+ ⚠ Sanitization check failed
+ ${Object.entries(data.warnings).map(([c, n]) => `${c}: ${n}`).join(', ')} +
` + } else { + if (resultEl) resultEl.innerHTML = ` +
+ ${esc(data.error || 'Submission failed')} +
` + } +} + +// ─── Ops-menu Preview + Submit flow ─── +// +// Combines generate-report (local Claude CLI, humanize issue +// taxonomy, forbidden-token scan, report body assembled against a +// constrained methodology vocabulary) with preview + gh-issue +// submission into one user-visible operation reachable from the +// session-detail ops dropdown. Three states share the same modal: +// generating -> preview -> submitting -> result. + +async function opsPreviewIssue(sessionId) { + if (!sessionId) return + _opsShowModal(` +

${t('ops.preview_issue')}

+
+ +
+
Generating methodology report via local Claude CLI…
+
Typically 30–60s. Output is sanitized and mapped to a constrained methodology taxonomy before preview.
+
+
+
+ +
`) + + // Step 1: check if the sanitized-issue payload already builds + // cleanly (i.e. a methodology-analysis-report.md exists). If + // not, generate one via local Claude CLI, then re-check. + let check = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + if (!check.ok) { + const gen = await window.authedFetch(`/api/sessions/${sessionId}/generate-report`, { method: 'POST' }) + const genData = await gen.json().catch(() => ({})) + if (!gen.ok) { + _opsShowError(t('analysis.failed'), genData.error || 'Failed to generate methodology report via local Claude CLI.', genData.stderr) + return + } + check = await window.authedFetch(`/api/sessions/${sessionId}/sanitized-issue`) + } + + if (!check.ok) { + _opsShowError(t('analysis.failed'), 'Sanitized issue payload could not be built for this session.') + return + } + + const data = await check.json() + const w = data.warnings || {} + const hasWarnings = !!data.requires_review || Object.keys(w).length > 0 + + const warningBanner = hasWarnings + ? `
+ ${t('analysis.review_warning')}
+ ${Object.entries(w).map(([c, n]) => `• ${esc(c)}: ${n}`).join('')} +
` + : '' + + _opsShowModal(` +
+

${t('ops.preview_issue')}

+ → PolyArch/humanize +
+ ${warningBanner} +
+
${t('analysis.issue_title')}
+ ${esc(data.title)} +
+
+
${t('analysis.issue_body')}
+
+ ${safeMd(data.body)} +
+
+
+ + + ${hasWarnings ? '' : ``} +
`) +} + +async function opsSubmitIssue(sessionId) { + _opsShowModal(` +

${t('analysis.sending')}

+
+ +
+
Creating GitHub issue on PolyArch/humanize via gh CLI…
+
Requires a gh login on this host (run gh auth login once).
+
+
+
+ +
`) + + const res = await window.authedFetch(`/api/sessions/${sessionId}/github-issue`, { method: 'POST' }) + const data = await res.json().catch(() => ({})) + + if (res.ok && data.url) { + _opsShowModal(` +

✓ ${t('analysis.sent')}

+ +
+ +
`) + return + } + + if (data.manual) { + // gh CLI missing or unauthenticated. Make the payload + // trivially copyable so the user can file the issue manually. + window._issuePayload = `Title: ${data.title || ''}\n\n${data.body || ''}` + _opsShowModal(` +

${t('analysis.failed')}

+
${esc(data.error || 'gh CLI is not available on this host.')}
+
+ Run gh auth login in the same shell that launched humanize monitor web, then retry. + Alternatively copy the payload below and file the issue manually against PolyArch/humanize. +
+
+ + +
`) + return + } + + if (data.warnings) { + _opsShowError( + t('analysis.failed'), + 'Sanitization check failed on the final payload. Review the methodology report manually and strip any project-specific tokens before sending.', + Object.entries(data.warnings).map(([c, n]) => `${c}: ${n}`).join(', '), + ) + return + } + + _opsShowError(t('analysis.failed'), data.error || 'Issue creation failed.') +} + +async function opsCopyIssue(sessionId) { + await copyIssueContent(sessionId) +} + +function _opsShowModal(inner) { + const modal = document.getElementById('modal-content') + if (!modal) return + modal.innerHTML = inner + document.getElementById('modal-overlay').classList.add('visible') +} + +function _opsShowError(title, message, detail) { + _opsShowModal(` +

${esc(title)}

+
${esc(message)}
+ ${detail ? `
${esc(detail)}
` : ''} +
+ +
`) +} + +// Project switching removed in Round 5 (T10-frontend). The dashboard +// is now CLI-fixed to one project at startup; multi-project users run +// `humanize monitor web --project ` per project. The legacy +// /api/projects/{switch,add,remove} endpoints return 410 Gone. + +// ─── Plan Viewer ─── +async function showPlanViewer(sessionId) { + const res = await window.authedFetch(`/api/sessions/${sessionId}/plan`) + if (!res.ok) return + const data = await res.json() + const modal = document.getElementById('modal-content') + modal.innerHTML = ` +

${t('ops.view_plan')}

+
${safeMd(data.content)}
+
` + document.getElementById('modal-overlay').classList.add('visible') +} diff --git a/viz/static/js/app.js b/viz/static/js/app.js new file mode 100644 index 00000000..a96e73a2 --- /dev/null +++ b/viz/static/js/app.js @@ -0,0 +1,1348 @@ +/* Main SPA — router, WebSocket, token propagation, page rendering */ + +let ws = null, wsRetryDelay = 1000 +const WS_MAX_RETRY = 30000 +let _sortCol = 'session_id', _sortAsc = false +const _liveLogPanes = new Map() // sessionId -> { eventSource, element, basename } + +// ─── Auth token propagation (T11-frontend) ─── +// +// Resolved once per page load. Order of precedence: +// 1. ?token= on the document URL (single-use, stripped from +// the visible URL once consumed but kept in sessionStorage so +// reloads work without manual re-entry). +// 2. #token= in the URL hash (same as above; supports clients +// that prefer the hash form for security on shared screens). +// 3. sessionStorage cached token from a prior visit. +// 4. baked into the +// static index.html (uncommon; useful for kiosk deployments). +// +// On localhost-bound deployments the server skips auth entirely, so a +// missing token is fine and api() will simply not attach a header. +function _resolveAuthToken() { + let token = '' + try { + const url = new URL(location.href) + const queryToken = url.searchParams.get('token') + if (queryToken) { + token = queryToken + url.searchParams.delete('token') + history.replaceState(null, '', url.toString()) + } + } catch (_) {} + + if (!token && location.hash.includes('token=')) { + const m = location.hash.match(/(?:^|[#&])token=([^&]+)/) + if (m) { + token = decodeURIComponent(m[1]) + const newHash = location.hash.replace(/(^|[#&])token=[^&]+&?/, '$1').replace(/&$/, '') + history.replaceState(null, '', location.pathname + location.search + newHash) + } + } + + if (!token) { + token = sessionStorage.getItem('humanize-viz-token') || '' + } + + if (!token) { + const meta = document.querySelector('meta[name="humanize-viz-token"]') + if (meta) token = meta.getAttribute('content') || '' + } + + if (token) { + sessionStorage.setItem('humanize-viz-token', token) + } + return token +} + +const _authToken = _resolveAuthToken() + +function _withToken(url) { + if (!_authToken) return url + const sep = url.includes('?') ? '&' : '?' + return `${url}${sep}token=${encodeURIComponent(_authToken)}` +} + +// ─── WebSocket (localhost coarse events only; remote mode is rejected +// server-side per DEC-4) ─── +// +// Remote mode is detected by the presence of a resolved auth token: +// localhost-bound deployments do not set one (the server does not +// enforce auth), so a token implies the dashboard is talking to a +// non-loopback server where WS is rejected. In that case the home +// page falls back to polling /api/sessions on a fixed interval to +// surface WAITING -> live transitions and EOF transitions in the UI. +const _isRemoteMode = !!_authToken + +function connectWebSocket() { + if (_isRemoteMode) { + // No coarse session-list channel exists in remote mode (per + // DEC-4); the home-route polling loop handles refreshes. + return + } + const proto = location.protocol === 'https:' ? 'wss:' : 'ws:' + const wsUrl = _withToken(`${proto}//${location.host}/ws`) + ws = new WebSocket(wsUrl) + ws.onopen = () => { wsRetryDelay = 1000 } + ws.onmessage = (e) => { + try { + const msg = JSON.parse(e.data) + const route = parseRoute() + // Targeted subtree refresh per event type — avoid the + // whole-page rebuild that previously caused flicker on + // every file write. Only the affected DOM subtree is + // touched; the live-log 
 (SSE) and the page
+            // skeleton are never recreated here.
+            if (route.page === 'home') {
+                _scheduleHomeRefresh()
+            } else if (route.page === 'session' && route.id === msg.session_id) {
+                _scheduleSessionPartialRefresh(route.id, msg.type)
+            }
+        } catch (_) {}
+    }
+    ws.onclose = () => {
+        setTimeout(() => {
+            wsRetryDelay = Math.min(wsRetryDelay * 2, WS_MAX_RETRY)
+            connectWebSocket()
+        }, wsRetryDelay)
+    }
+}
+
+// ─── Targeted WS-push refresh ───
+//
+// Rather than polling or re-rendering the whole page on every
+// watcher broadcast, the WS onmessage path dispatches per event
+// type to the smallest subtree that changed:
+//   - home: re-build the active / completed card lists only.
+//   - session-detail: re-run renderPipeline / renderSessionSidebar /
+//     renderGoalBar as appropriate, never touching the
+//     #session-log-container or its EventSource.
+//
+// A ~500ms trailing-edge debounce per surface coalesces bursts
+// (state.md + goal-tracker.md + round-N-summary.md often land in the
+// same second) so the reader sees one update, not three.
+const _PARTIAL_DEBOUNCE_MS = 500
+
+let _homeRefreshHandle = null
+function _scheduleHomeRefresh() {
+    if (_homeRefreshHandle != null) return
+    _homeRefreshHandle = setTimeout(() => {
+        _homeRefreshHandle = null
+        if (parseRoute().page === 'home') _refreshHomeCards()
+    }, _PARTIAL_DEBOUNCE_MS)
+}
+
+let _sessionRefreshHandle = null
+let _pendingSessionRefreshKinds = new Set()
+function _scheduleSessionPartialRefresh(sessionId, eventType) {
+    // Merge the kinds of updates we need to do so a burst that mixes
+    // round_added + session_updated fires one refresh with both
+    // subtrees updated.
+    if (eventType) _pendingSessionRefreshKinds.add(eventType)
+    if (_sessionRefreshHandle != null) return
+    _sessionRefreshHandle = setTimeout(async () => {
+        _sessionRefreshHandle = null
+        const kinds = _pendingSessionRefreshKinds
+        _pendingSessionRefreshKinds = new Set()
+        const route = parseRoute()
+        if (route.page !== 'session' || route.id !== sessionId) return
+        await _refreshSessionPartial(sessionId, kinds)
+    }, _PARTIAL_DEBOUNCE_MS)
+}
+
+// Diff-based refresh of the home sessions region. Only cards whose
+// rendered content actually changed get their outerHTML replaced;
+// unchanged cards are left entirely alone so there is no re-render,
+// no re-animation, and no observable "flashing". Section skeletons
+// (labels + list containers) are created or torn down as needed when
+// a session transitions between Active and Completed, but that
+// touches only the affected section — existing cards in the other
+// section do not move.
+async function _refreshHomeCards() {
+    const wrap = document.getElementById('home-sessions')
+    if (!wrap) return
+    const sessions = await api('/api/sessions').catch(() => null)
+    if (sessions == null) return
+    if (parseRoute().page !== 'home') return
+
+    // Empty state transition in either direction falls back to the
+    // full rebuild (rare: at most once when the first session lands
+    // or when the last one is pruned). This never fires during a
+    // running loop.
+    const currentlyEmpty = wrap.querySelector('.empty') != null
+    if (sessions.length === 0) {
+        if (!currentlyEmpty) wrap.innerHTML = _buildHomeSessionsHtml(sessions)
+        return
+    }
+    if (currentlyEmpty) {
+        wrap.innerHTML = _buildHomeSessionsHtml(sessions)
+        return
+    }
+
+    const active = sessions.filter(s => ['active', 'analyzing', 'finalizing'].includes(s.status))
+    const finished = sessions.filter(s => !['active', 'analyzing', 'finalizing'].includes(s.status))
+
+    _applyHomeSection(wrap, 'active', active, t('home.active'), 'session-grid', activeSessionPane)
+    _applyHomeSection(wrap, 'completed', finished, t('home.completed'), 'session-grid', sessionCard)
+}
+
+// Ensure a section (label + list container) matches the given
+// session list. Cards are diff-updated by data-session-id:
+//   - stays the same (same HTML) -> untouched
+//   - content changed            -> outerHTML swap on that one card
+//   - new session in list        -> append
+//   - session dropped from list  -> remove
+// Section label + list container are created lazily when the list
+// becomes non-empty and removed when it goes back to empty.
+function _applyHomeSection(wrap, sectionKey, list, label, containerClass, cardFn) {
+    const listSel = `[data-home-section="${sectionKey}"]`
+    let container = wrap.querySelector(listSel)
+    const labelSel = `[data-home-section-label="${sectionKey}"]`
+    let labelEl = wrap.querySelector(labelSel)
+
+    if (list.length === 0) {
+        if (labelEl) labelEl.remove()
+        if (container) container.remove()
+        return
+    }
+
+    if (!container) {
+        // Create label + container and place them in the right order.
+        // active section goes first; completed second.
+        const labelHtml = `
${label}
`
+        const containerHtml = `
`
+        if (sectionKey === 'active') {
+            wrap.insertAdjacentHTML('afterbegin', labelHtml + containerHtml)
+        } else {
+            wrap.insertAdjacentHTML('beforeend', labelHtml + containerHtml)
+        }
+        container = wrap.querySelector(listSel)
+    }
+
+    // Index existing cards by session id.
+    const existing = new Map()
+    for (const el of container.querySelectorAll('.session-card[data-session-id]')) {
+        existing.set(el.dataset.sessionId, el)
+    }
+
+    const seen = new Set()
+    let cursor = null
+    for (const s of list) {
+        seen.add(s.id)
+        const html = cardFn(s).trim()
+        const el = existing.get(s.id)
+        if (el) {
+            // Compare rendered HTML; skip if identical.
+            if (el.outerHTML.trim() !== html) {
+                const tmp = document.createElement('div')
+                tmp.innerHTML = html
+                el.replaceWith(tmp.firstElementChild)
+            }
+            cursor = container.querySelector(`.session-card[data-session-id="${CSS.escape(s.id)}"]`)
+        } else {
+            // Append new card at the current position.
+            const tmp = document.createElement('div')
+            tmp.innerHTML = html
+            const node = tmp.firstElementChild
+            node.classList.add('js-card-new')
+            if (cursor && cursor.nextSibling) {
+                container.insertBefore(node, cursor.nextSibling)
+            } else {
+                container.appendChild(node)
+            }
+            cursor = node
+        }
+    }
+
+    // Remove cards for sessions that are no longer in this section.
+    for (const [id, el] of existing) {
+        if (!seen.has(id)) el.remove()
+    }
+}
+
+// Targeted session-detail refresh. Re-runs only the subtrees implied
+// by the set of event kinds, leaving the rest of the DOM (notably
+// the live-log 
 and its EventSource) untouched.
+async function _refreshSessionPartial(sessionId, kinds) {
+    const session = await api(`/api/sessions/${sessionId}`)
+    if (!session) return
+    // Route-change race guard: the fetch above is async, so by the
+    // time the response lands the user may have navigated to another
+    // session or route. Checking the DOM skeleton + current route
+    // prevents us from writing stale data into the wrong page.
+    const route = parseRoute()
+    if (route.page !== 'session' || route.id !== sessionId) return
+    const layout = document.querySelector(`.detail-layout[data-session-id="${CSS.escape(sessionId)}"]`)
+    if (!layout) return
+    // Pipeline update runs for every session-scoped event kind,
+    // including session_updated: a review-result.md write flips the
+    // verdict on an existing node, which must re-paint that one
+    // node's dot / badge. The incremental updater is a no-op on
+    // rounds whose verdict and active flag are unchanged, so running
+    // it unconditionally is cheap.
+    const wantPipeline = kinds.has('round_added') || kinds.has('session_updated') || kinds.has('session_finished')
+    const wantSidebar  = kinds.has('round_added') || kinds.has('session_updated') || kinds.has('session_finished')
+    const wantGoalBar  = kinds.has('round_added') || kinds.has('session_updated') || kinds.has('session_finished')
+    window._currentSession = session
+    if (wantPipeline) {
+        const root = document.getElementById('pipeline-root')
+        if (root) {
+            // Incremental update keeps the user's zoom/pan and only
+            // adds / mutates the specific nodes that changed. Full
+            // renderPipeline is still used on first entry because it
+            // also sets up the viewport + drag listeners; this
+            // targeted path assumes those already exist.
+            if (typeof window._updatePipelineIncremental === 'function') {
+                window._updatePipelineIncremental(root, session)
+            } else {
+                renderPipeline(root, session)
+            }
+        }
+    }
+    if (wantSidebar) renderSessionSidebar(session)
+    if (wantGoalBar) renderGoalBar(session)
+    // Keep the layout mode in sync (e.g. session finished -> hide log
+    // row) and let _ensureSessionLogPane idempotently roll forward
+    // to a newer cache-log basename when a new round starts.
+    _applyDetailLayoutMode(session)
+    _ensureSessionLogPane(session)
+    const cancelBtn = document.getElementById('ops-cancel')
+    const CANCELLABLE = ['active', 'analyzing', 'finalizing']
+    if (cancelBtn) cancelBtn.style.display = CANCELLABLE.includes(session.status) ? '' : 'none'
+}
+
+// Remote-mode metadata polling. In localhost mode the WebSocket
+// carries watcher events, so there is no polling on top of that.
+// In remote mode WS is rejected server-side (DEC-4), so without a
+// fallback the card counters, pipeline nodes, and methodology
+// status would all freeze at page-load state. This polling uses the
+// same targeted refresh helpers (_refreshHomeCards /
+// _refreshSessionPartial) that the WS path uses, so it does NOT
+// rebuild the page — it only updates the same in-place subtrees
+// and leaves the SSE log pane alone.
+const _REMOTE_POLL_INTERVAL_MS = 10000
+let _remotePollHandle = null
+let _remotePollRoute = null
+
+function _startRemotePolling() {
+    if (!_isRemoteMode) return
+    if (_remotePollHandle != null) return
+    _remotePollHandle = setInterval(() => {
+        const route = parseRoute()
+        _remotePollRoute = route
+        if (route.page === 'home') {
+            _refreshHomeCards()
+        } else if (route.page === 'session') {
+            // Feed a synthetic "session_updated" kind so the
+            // refresh runs pipeline + sidebar + goal-bar + log pane
+            // — matching what the WS path does on catch-up.
+            _scheduleSessionPartialRefresh(route.id, 'session_updated')
+        }
+    }, _REMOTE_POLL_INTERVAL_MS)
+}
+
+// Kept for the teardown path in renderCurrentRoute / toggleTheme.
+// Localhost mode doesn't poll so these are no-ops for the common
+// path; remote mode stops via _stopRemotePolling on route change.
+function _stopHomePolling() {}
+function _stopSessionPolling() {}
+function _stopRemotePolling() {
+    if (_remotePollHandle != null) {
+        clearInterval(_remotePollHandle)
+        _remotePollHandle = null
+    }
+}
+
+// ─── Router ───
+function parseRoute() {
+    const h = location.hash || '#/'
+    if (h === '#/' || h === '#') return { page: 'home' }
+    let m = h.match(/^#\/session\/([^/]+)\/analysis$/)
+    if (m) return { page: 'analysis', id: m[1] }
+    m = h.match(/^#\/session\/([^/]+)$/)
+    if (m) return { page: 'session', id: m[1] }
+    if (h === '#/analytics') return { page: 'analytics' }
+    return { page: 'home' }
+}
+
+function navigate(hash) { location.hash = hash }
+
+window.renderCurrentRoute = function() {
+    const route = parseRoute()
+    const main = document.getElementById('main-content')
+    main.innerHTML = ''
+    updateTopbar(route)
+    // Always tear down live EventSource connections on a route change.
+    // The new route's render will mount a fresh pane if it needs one
+    // (the session-detail page does for active sessions). Without
+    // this, a lingering SSE stream from a prior session page would
+    // keep hitting the server in the background.
+    _teardownAllLivePanes()
+    if (route.page !== 'home') _stopHomePolling()
+    // Stop any active session-polling loop when leaving session/
+    // analysis routes so we do not keep re-rendering a page the
+    // user has navigated away from. The session-polling helper
+    // also self-stops if its target id no longer matches the route,
+    // but stopping here handles the route-type change case cleanly.
+    if (route.page !== 'session' && route.page !== 'analysis') {
+        _stopSessionPolling()
+    }
+    switch (route.page) {
+        case 'home': renderHome(); break
+        case 'session': renderSession(route.id); break
+        case 'analysis': renderAnalysis(route.id); break
+        case 'analytics': renderAnalytics(); break
+        default: renderHome()
+    }
+}
+
+window.addEventListener('hashchange', window.renderCurrentRoute)
+
+// ─── Topbar ───
+function updateTopbar(route) {
+    const left = document.getElementById('topbar-left')
+    const titleEl = document.getElementById('topbar-title')
+    const themeBtn = document.getElementById('theme-btn')
+    const analyticsLink = document.getElementById('analytics-link')
+    const opsContainer = document.getElementById('ops-dropdown-container')
+
+    // Left area: always show logo (clickable to home), plus back button on sub-pages
+    if (route.page === 'home') {
+        left.innerHTML = `
+            `
+        titleEl.textContent = ''
+    } else {
+        left.innerHTML = `
+            ${t('nav.back')}
+            `
+        titleEl.textContent = route.id || ''
+    }
+
+    // Right area
+    if (analyticsLink) analyticsLink.textContent = t('nav.analytics')
+    if (themeBtn) themeBtn.textContent = document.documentElement.getAttribute('data-theme') === 'dark' ? '☀' : '☾'
+
+    // Ops dropdown — only on session/analysis pages
+    if (opsContainer) {
+        opsContainer.style.display = (route.page === 'session' || route.page === 'analysis') ? '' : 'none'
+    }
+
+    // Populate ops menu labels
+    const labels = { 'ops-plan': 'ops.view_plan', 'ops-analysis': 'ops.analysis', 'ops-preview-issue': 'ops.preview_issue', 'ops-export-md': 'ops.export_md', 'ops-export-pdf': 'ops.export_pdf', 'ops-cancel': 'ops.cancel' }
+    for (const [id, key] of Object.entries(labels)) {
+        const el = document.getElementById(id)
+        if (el) el.textContent = t(key)
+    }
+}
+
+// ─── Theme ───
+function initTheme() {
+    const saved = localStorage.getItem('humanize-viz-theme')
+    const theme = (saved === 'dark' || saved === 'light') ? saved : 'dark'
+    document.documentElement.setAttribute('data-theme', theme)
+    if (saved !== theme) localStorage.setItem('humanize-viz-theme', theme)
+}
+
+function toggleTheme() {
+    const cur = document.documentElement.getAttribute('data-theme')
+    const next = cur === 'dark' ? 'light' : 'dark'
+    document.documentElement.setAttribute('data-theme', next)
+    localStorage.setItem('humanize-viz-theme', next)
+    // Theme variables are declared via CSS custom properties keyed
+    // on [data-theme], so switching the attribute is enough for the
+    // paint to update on every route that styles via CSS vars
+    // (home cards, session-detail pipeline + sidebar + log pane).
+    // No DOM rebuild is needed there — pipeline zoom/pan, the open
+    // flyout (if any), the live-log 
 + EventSource, and the
+    // log-panel collapse state all survive across toggles.
+    const btn = document.getElementById('theme-btn')
+    if (btn) btn.textContent = next === 'dark' ? '☀' : '☾'
+    // Analytics is the one exception: charts read CSS vars via
+    // getComputedStyle and bake the colors into SVG at render time,
+    // so the on-screen charts don't repaint on attribute flip.
+    // Re-render only that route; all other routes stay put.
+    if (parseRoute().page === 'analytics') {
+        renderAnalytics()
+    }
+}
+
+// ─── API ───
+async function api(url) {
+    const opts = {}
+    if (_authToken) {
+        opts.headers = { 'Authorization': `Bearer ${_authToken}` }
+    }
+    const r = await fetch(url, opts)
+    return r.ok ? r.json() : null
+}
+
+// Exported so actions.js fetches stay token-aware too. The main
+// difference vs api() is that this returns the raw Response so
+// callers can inspect status codes and error bodies.
+window.authedFetch = function(url, init) {
+    init = init || {}
+    init.headers = Object.assign({}, init.headers || {})
+    if (_authToken && !init.headers.Authorization) {
+        init.headers.Authorization = `Bearer ${_authToken}`
+    }
+    return fetch(url, init)
+}
+
+function fmtDuration(m) {
+    if (m == null) return '—'
+    if (m < 60) return `${m} ${t('unit.min')}`
+    return `${Math.floor(m/60)}h ${Math.round(m%60)}m`
+}
+
+function _esc(str) {
+    const d = document.createElement('div')
+    d.textContent = str || ''
+    return d.innerHTML
+}
+
+// ─── Home ───
+async function renderHome() {
+    const main = document.getElementById('main-content')
+
+    // Tear down any live-log panes from the previous render so we do
+    // not leak EventSource connections across navigations.
+    _teardownAllLivePanes()
+
+    // Load projects, sessions, and the cross-session analytics strip
+    // in parallel. Analytics is best-effort: if the endpoint fails we
+    // still render the rest of the page and just drop the strip.
+    const [projects, sessions, analytics] = await Promise.all([
+        api('/api/projects').catch(() => []),
+        api('/api/sessions').catch(() => []),
+        api('/api/analytics').catch(() => null),
+    ])
+
+    // Project header (read-only). The legacy project switcher and
+    // "+ Add" UI was removed in Round 5 (T10-frontend); the dashboard
+    // is now CLI-fixed to one project at startup.
+    const currentProject = (projects || [])[0] || {}
+    const projectHeader = `
+        

+            

+                Project
+                ${_esc(currentProject.name || '—')}
+                ${_esc(currentProject.path || '')}
+            

+            

+                CLI-fixed: run \`humanize monitor web --project <path>\` per project
+            

+        
`
+
+    const analyticsStrip = _renderHomeAnalyticsStrip(analytics)
+
+    // The sessions region lives inside a stable wrapper so WS-push
+    // refreshes can replace its innerHTML without touching
+    // .project-bar. This removes the "fall back to renderHome()
+    // when sections don't exist yet" branch that Codex flagged as a
+    // full-page rebuild.
+    const sessionsBody = _buildHomeSessionsHtml(sessions)
+    main.innerHTML = `
${projectHeader}${analyticsStrip}
${sessionsBody}
`
+}
+
+// Cross-Session Analytics strip: four stat tiles (total sessions,
+// avg rounds, completion rate, and a sparkline for rounds-per-day
+// over the last 14 days). Mirrors the reference kit's home header
+// block. Best-effort: drops silently when /api/analytics is empty.
+function _renderHomeAnalyticsStrip(analytics) {
+    if (!analytics || !analytics.overview) return ''
+    const o = analytics.overview
+    if ((o.total_sessions || 0) === 0) return ''
+    const rpd = Array.isArray(o.rounds_per_day) ? o.rounds_per_day : []
+    const windowDays = o.rounds_per_day_window || rpd.length || 14
+    const sparkSvg = _renderSparkline(rpd)
+    return `
+        
${t('analytics.title')}

+        

+            
${_esc(String(o.total_sessions))}
${t('analytics.total')}

+            
${_esc(String(o.average_rounds))}
${t('analytics.avg_rounds')}

+            
${_esc(String(o.completion_rate))}%
${t('analytics.completion')}

+            

+                
${t('home.rounds_per_day')} (last ${windowDays}d)

+                ${sparkSvg}
+            

+        
`
+}
+
+// Compact inline SVG sparkline. Draws a filled area + polyline +
+// trailing dot. Zero-data input renders an empty but valid SVG so
+// layout stays stable.
+function _renderSparkline(values) {
+    const W = 180, H = 42, PAD = 2
+    const n = values.length
+    if (n === 0) return ``
+    const peak = Math.max(1, ...values.map(v => Number(v) || 0))
+    const step = n > 1 ? (W - PAD * 2) / (n - 1) : 0
+    const pts = values.map((v, i) => {
+        const x = PAD + i * step
+        const y = H - PAD - ((Number(v) || 0) / peak) * (H - PAD * 2)
+        return { x, y }
+    })
+    const poly = pts.map(p => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ')
+    const areaPts = [
+        `${PAD},${H - PAD}`,
+        ...pts.map(p => `${p.x.toFixed(1)},${p.y.toFixed(1)}`),
+        `${PAD + (n - 1) * step},${H - PAD}`,
+    ].join(' ')
+    const last = pts[pts.length - 1]
+    return `
+        
+            
+            
+            
+        `
+}
+
+// Builds the HTML body that goes inside #home-sessions. Covers all
+// three cases: empty, active-only, completed-only, both. Shared by
+// the initial renderHome() and the incremental _refreshHomeCards().
+//
+// The section label + list container elements carry the same
+// `data-home-section` / `data-home-section-label` attributes that
+// _applyHomeSection queries against. Without those attributes the
+// first WS refresh would not find the initial render's container
+// and would create a second one, showing two Active sections on
+// screen for a single running loop — the duplicate-card bug.
+function _buildHomeSessionsHtml(sessions) {
+    if (!sessions || sessions.length === 0) {
+        return `
⬡
${t('home.empty')}
${t('home.empty.hint')}
`
+    }
+    const active = sessions.filter(s => ['active','analyzing','finalizing'].includes(s.status))
+    const finished = sessions.filter(s => !['active','analyzing','finalizing'].includes(s.status))
+    let html = ''
+    // Reference kit wraps each row of cards in a 
 with an
+    // uppercase "eyebrow-rule" label and a .session-grid container
+    // (auto-fit columns at a generous min-width). Both Active and
+    // Completed now use the same skin — the status badge + pulse
+    // dot inside each card carries the "running" signal instead.
+    // The inline diff-updater (_applyHomeSection) creates label +
+    // container pairs directly under #home-sessions when a section
+    // first materializes; keeping the initial render's shape the
+    // same (no 
 wrapper) avoids layout drift between the
+    // initial render and the WS-driven lazy creation.
+    if (active.length) {
+        html += `
${t('home.active')}
`
+        html += `
${active.map(activeSessionPane).join('')}
`
+    }
+    if (finished.length) {
+        html += `
${t('home.completed')}
`
+        html += `
${finished.map(sessionCard).join('')}
`
+    }
+    return html
+}
+
+function _latestActiveLog(session) {
+    // session.cache_logs is the deterministic list emitted by
+    // viz/server/parser.py:cache_logs_for_session — sorted by
+    // (round, tool, role) ascending. Reproduce the CLI's
+    // `humanize monitor rlcr` Log: line by picking the codex-run log
+    // for the highest round, falling back through the other
+    // tool/role combinations. Without this the naive cache_logs[-1]
+    // could land on `gemini-review` or `codex-review` for the same
+    // round, which is the wrong file — the user expects the primary
+    // implementation/review stream, not a secondary one.
+    const logs = session.cache_logs || []
+    if (logs.length === 0) return null
+    let maxRound = -1
+    for (const l of logs) if (l.round > maxRound) maxRound = l.round
+    const preference = [
+        ['codex', 'run'],
+        ['codex', 'review'],
+        ['gemini', 'run'],
+        ['gemini', 'review'],
+    ]
+    for (const [tool, role] of preference) {
+        const match = logs.find(l => l.round === maxRound && l.tool === tool && l.role === role)
+        if (match) return match
+    }
+    // No codex/gemini match at the top round — surface anything we
+    // have so the pane is not empty (defensive; real sessions always
+    // carry at least one of the above).
+    return logs.filter(l => l.round === maxRound).pop() || logs[logs.length - 1]
+}
+
+// Active pane on the home page: just the plain sessionCard — the
+// live monitor log stream lives on the session-detail page (below
+// the pipeline canvas), not here.
+function activeSessionPane(s) {
+    return sessionCard(s)
+}
+
+// ─── Live log panes (T6) ───
+//
+// Each active session gets its own EventSource talking to
+// /api/sessions//logs/. Multiple panes coexist on the
+// home page; navigating away tears them all down so we do not leak
+// open connections.
+function _mountLiveLogPane(sessionId, logEntry) {
+    const pane = document.getElementById(`live-log-pane-${sessionId}`)
+    const status = document.getElementById(`live-log-status-${sessionId}`)
+    if (!pane) return
+
+    const url = _withToken(`/api/sessions/${encodeURIComponent(sessionId)}/logs/${encodeURIComponent(logEntry.basename)}`)
+    const es = new EventSource(url)
+
+    const _utf8Decoder = new TextDecoder('utf-8', { fatal: false })
+    let bytesSeen = 0
+    function appendBytes(b64, { flush = false } = {}) {
+        try {
+            // atob returns a Latin-1 byte-string; convert to a real
+            // byte array and decode as UTF-8 so non-ASCII log output
+            // (CJK text, emoji, smart quotes) renders correctly
+            // instead of as mojibake.
+            //
+            // `{ stream: true }` keeps the decoder's internal buffer
+            // alive across calls, so a multibyte UTF-8 sequence
+            // split at the 64 KiB SSE chunk boundary is reassembled
+            // on the next event instead of being emitted as U+FFFD
+            // replacement characters. Callers pass `flush: true`
+            // when the stream is known to be complete (resync
+            // reason=truncated/rotated/recreated/overflow, eof) so
+            // the decoder's trailing buffer is finalised and not
+            // accidentally prefixed to the next snapshot.
+            const binStr = atob(b64)
+            const bytes = new Uint8Array(binStr.length)
+            for (let i = 0; i < binStr.length; i++) bytes[i] = binStr.charCodeAt(i)
+            const text = _utf8Decoder.decode(bytes, { stream: !flush })
+            pane.textContent += text
+            bytesSeen += bytes.length
+            // Cap pane size to avoid runaway memory on long sessions.
+            const MAX_PANE_BYTES = 256 * 1024
+            if (pane.textContent.length > MAX_PANE_BYTES) {
+                pane.textContent = '... (truncated, showing tail)\n' +
+                    pane.textContent.slice(-MAX_PANE_BYTES + 64)
+            }
+            pane.scrollTop = pane.scrollHeight
+        } catch (_) {}
+    }
+
+    function setStatus(text, kind) {
+        if (!status) return
+        status.textContent = text
+        status.className = 'live-log-status' + (kind ? ` live-log-status-${kind}` : '')
+    }
+
+    es.addEventListener('snapshot', (e) => {
+        try {
+            const data = JSON.parse(e.data)
+            if (data.offset === 0) pane.textContent = ''
+            appendBytes(data.bytes_b64)
+            setStatus(`live (${bytesSeen}B)`, 'ok')
+        } catch (_) {}
+    })
+
+    es.addEventListener('append', (e) => {
+        try {
+            const data = JSON.parse(e.data)
+            appendBytes(data.bytes_b64)
+            setStatus(`live (${bytesSeen}B)`, 'ok')
+        } catch (_) {}
+    })
+
+    es.addEventListener('resync', (e) => {
+        try {
+            const data = JSON.parse(e.data)
+            setStatus(`resync: ${data.reason}`, 'warn')
+            if (data.reason === 'truncated' || data.reason === 'rotated' ||
+                data.reason === 'recreated' || data.reason === 'overflow') {
+                // Stream is discontinuous from here: finalise the
+                // decoder so any trailing buffered bytes from the
+                // previous file don't bleed into the fresh content
+                // that follows.
+                try { _utf8Decoder.decode(new Uint8Array(0)) } catch (_) {}
+                pane.textContent = ''
+                bytesSeen = 0
+            }
+        } catch (_) {}
+    })
+
+    es.addEventListener('eof', () => {
+        setStatus('eof', 'eof')
+        es.close()
+        _liveLogPanes.delete(sessionId)
+        // Flush the decoder so a trailing incomplete multibyte
+        // sequence (if any) is rendered as U+FFFD rather than
+        // silently dropped.
+        try { _utf8Decoder.decode(new Uint8Array(0)) } catch (_) {}
+        // The session just transitioned to a terminal status. The
+        // sidebar/pipeline are snapshots and will show the new status
+        // when the user navigates away and back or reloads; no
+        // auto-refresh is triggered here on purpose (avoids the whole
+        // page flashing when a session finishes).
+    })
+
+    es.onerror = () => {
+        setStatus('disconnected (will retry)', 'warn')
+        // EventSource auto-reconnects with exponential backoff; we
+        // do nothing here. On real disconnect the browser sends
+        // Last-Event-Id so the server replays missed events.
+    }
+
+    _liveLogPanes.set(sessionId, { eventSource: es, element: pane, basename: logEntry.basename })
+}
+
+function _teardownAllLivePanes() {
+    for (const [, entry] of _liveLogPanes) {
+        try { entry.eventSource.close() } catch (_) {}
+    }
+    _liveLogPanes.clear()
+}
+
+function sessionCard(s) {
+    const plan = s.plan_file ? s.plan_file.split('/').pop() : '—'
+    const started = s.started_at ? new Date(s.started_at).toLocaleString() : '—'
+    const acPct = s.ac_total > 0 ? Math.round(s.ac_done / s.ac_total * 100) : 0
+    const verdict = s.last_verdict || 'unknown'
+    const statusLabel = t('status.' + s.status) || s.status
+    const isActive = ['active', 'analyzing', 'finalizing'].includes(s.status)
+    const idShort = (s.id || '').slice(0, 19)
+    const duration = fmtDuration(s.duration_minutes)
+
+    // Reference-kit skin: condensed head (round + id + status badge
+    // with pulse dot when in-flight) → 2×2 mono meta grid → AC
+    // progress bar → mono foot strip with timestamps and task count.
+    return `
+        

+            

+                

+                    ${t('card.round')} ${s.current_round}/${s.max_iterations}
+                    ${_esc(idShort)}
+                

+                
+                    ${isActive ? '' : ''}${_esc(statusLabel)}
+                
+            

+            

+                
${t('card.plan')}
${esc(plan)}

+                
${t('card.branch')}
${esc(s.start_branch || '—')}

+                
${t('card.verdict')}
${_esc(verdict)}

+                
${t('card.ac')}
${s.ac_done}/${s.ac_total}

+            

+            

+                

+            

+            

+                ${_esc(started)} · ${_esc(duration)}
+                ${t('detail.tasks')}: ${s.tasks_done}/${s.tasks_total}
+            

+        
`
+}
+
+// ─── Session Detail ───
+async function renderSession(sessionId) {
+    const main = document.getElementById('main-content')
+    const session = await api(`/api/sessions/${sessionId}`)
+    if (!session) {
+        main.innerHTML = `
${t('detail.not_found')}
`
+        return
+    }
+
+    // Auto-refresh disabled: the SSE live-log pane at the bottom of
+    // the page streams bytes into its own 
 without any page
+    // re-render, which is the only surface that truly needs to be
+    // live. Pipeline / sidebar / goal-bar are snapshots; to refresh
+    // them the user navigates away and back or reloads the page.
+
+    // Build the detail-layout skeleton only on first entry. On
+    // subsequent re-renders for the same session id we reuse the
+    // existing DOM so the bottom live-log pane is not destroyed.
+    let layout = main.querySelector(`.detail-layout[data-session-id="${CSS.escape(sessionId)}"]`)
+    if (!layout) {
+        _teardownAllLivePanes()
+        main.innerHTML = `
+            

+                

+                    

+                

+                

+                

+                

+            
`
+        layout = main.querySelector('.detail-layout')
+    }
+    _applyDetailLayoutMode(session)
+
+    renderPipeline(document.getElementById('pipeline-root'), session)
+    renderSessionSidebar(session)
+    renderGoalBar(session)
+    _ensureSessionLogPane(session)
+    window._currentSession = session
+
+    const cancelBtn = document.getElementById('ops-cancel')
+    // Mirror the backend's _CANCELLABLE_STATUSES (Round 8): the cancel
+    // helper supports active, analyzing, and finalizing sessions, so
+    // the UI must expose the button in all three phases. Round 10
+    // previously hid the button outside of 'active', which made
+    // stuck analyze/finalize sessions uncancellable from the UI.
+    const CANCELLABLE_STATUSES = ['active', 'analyzing', 'finalizing']
+    if (cancelBtn) cancelBtn.style.display = CANCELLABLE_STATUSES.includes(session.status) ? '' : 'none'
+}
+
+// Incremental re-render used by WS pushes and the 5-second polling
+// loop. Re-fetches the session, re-populates pipeline + sidebar +
+// goal-bar, and leaves the bottom live-log pane (and its
+// EventSource) untouched so the streaming log does not reset.
+// Falls back to a full renderSession() when the layout skeleton
+// doesn't match (e.g. first entry after a route change).
+async function _refreshSession(sessionId) {
+    const main = document.getElementById('main-content')
+    const layout = main && main.querySelector(`.detail-layout[data-session-id="${CSS.escape(sessionId)}"]`)
+    if (!layout) {
+        renderSession(sessionId)
+        return
+    }
+    const session = await api(`/api/sessions/${sessionId}`)
+    if (!session) return
+    _applyDetailLayoutMode(session)
+    renderPipeline(document.getElementById('pipeline-root'), session)
+    renderSessionSidebar(session)
+    renderGoalBar(session)
+    _ensureSessionLogPane(session)
+    window._currentSession = session
+    const cancelBtn = document.getElementById('ops-cancel')
+    const CANCELLABLE = ['active', 'analyzing', 'finalizing']
+    if (cancelBtn) cancelBtn.style.display = CANCELLABLE.includes(session.status) ? '' : 'none'
+}
+
+// Toggles the detail-layout's "has-log" modifier so the grid grows
+// a third row for the live-log panel only for active sessions.
+// Completed / cancelled sessions keep the original two-row layout
+// (graph + goal-bar), matching the previous look.
+function _applyDetailLayoutMode(session) {
+    const layout = document.querySelector('.detail-layout')
+    if (!layout) return
+    const hasLive = ['active', 'analyzing', 'finalizing'].includes(session.status)
+                  && Array.isArray(session.cache_logs) && session.cache_logs.length > 0
+    layout.classList.toggle('has-log', !!hasLive)
+}
+
+// Creates the live-log pane inside #session-log-container exactly
+// once per session entry. If the session is not active or has no
+// cache log yet, the container is emptied and any existing pane is
+// torn down. Idempotent when called repeatedly with the same
+// (sessionId, basename) pair — the existing EventSource keeps
+// streaming into the same 
.
+function _ensureSessionLogPane(session) {
+    const container = document.getElementById('session-log-container')
+    if (!container) return
+    const active = ['active', 'analyzing', 'finalizing'].includes(session.status)
+    const latest = _latestActiveLog(session)
+    if (!active || !latest) {
+        // No live log needed; tear down any prior pane.
+        const prev = _liveLogPanes.get(session.id)
+        if (prev) {
+            try { prev.eventSource.close() } catch (_) {}
+            _liveLogPanes.delete(session.id)
+        }
+        container.innerHTML = ''
+        return
+    }
+    const prev = _liveLogPanes.get(session.id)
+    if (prev && prev.basename === latest.basename && container.contains(prev.element)) {
+        // Same log file is already streaming; nothing to do.
+        return
+    }
+    // Either no pane yet, or the latest cache log rolled to a newer
+    // round — rebuild only this subtree (the container), leaving
+    // the rest of the detail layout intact. Preserve the toggle
+    // state (collapsed / normal / expanded) across the basename
+    // switch so a user who expanded the log is not bounced back to
+    // the default height every time a new round starts.
+    const layout = document.querySelector('.detail-layout.has-log')
+    const priorState = !layout
+        ? 'normal'
+        : layout.classList.contains('log-collapsed') ? 'collapsed'
+        : layout.classList.contains('log-expanded')  ? 'expanded'
+        : 'normal'
+    if (prev) {
+        try { prev.eventSource.close() } catch (_) {}
+        _liveLogPanes.delete(session.id)
+    }
+    container.innerHTML = `
+        

+            LIVE
+            ${_esc(latest.basename)}
+            connecting…
+            
+                
+                
+                
+            
+        

+        
`
+    _mountLiveLogPane(session.id, latest)
+    // Re-apply the prior toggle state so the active button lights up
+    // and the grid row keeps whichever height the user picked.
+    window.toggleSessionLog(priorState)
+}
+
+// Three-state collapse/expand control for the session-detail log
+// panel. 'normal' is the default 260px row, 'collapsed' shrinks to
+// the header only (so the pipeline canvas sees more vertical space),
+// and 'expanded' grows the log to cover most of the canvas for
+// reading long bursts. The state lives as a CSS class on
+// .detail-layout so the grid-template-rows swap happens in one place.
+window.toggleSessionLog = function(state) {
+    const layout = document.querySelector('.detail-layout.has-log')
+    if (!layout) return
+    layout.classList.remove('log-collapsed', 'log-normal', 'log-expanded')
+    if (state === 'collapsed') layout.classList.add('log-collapsed')
+    else if (state === 'expanded') layout.classList.add('log-expanded')
+    // 'normal' = no modifier class. Reflect the new state on the
+    // toggle buttons (hide the one matching the current state).
+    const buttons = layout.querySelectorAll('.live-log-btn')
+    buttons.forEach(b => { b.classList.remove('is-active') })
+    const cls = state === 'collapsed' ? '.js-log-collapse'
+              : state === 'expanded'  ? '.js-log-expand'
+              : '.js-log-normal'
+    const activeBtn = layout.querySelector(cls)
+    if (activeBtn) activeBtn.classList.add('is-active')
+}
+
+// Used by openFlyout/closeFlyout in pipeline.js: when the user opens
+// a node's details, auto-collapse the log so the modal (and the
+// underlying pipeline canvas) have more room. The prior state is
+// remembered and restored when the flyout is dismissed.
+let _savedLogState = null
+window.autoCollapseSessionLog = function() {
+    const layout = document.querySelector('.detail-layout.has-log')
+    if (!layout) return
+    _savedLogState = layout.classList.contains('log-collapsed') ? 'collapsed'
+                   : layout.classList.contains('log-expanded')  ? 'expanded'
+                   : 'normal'
+    window.toggleSessionLog('collapsed')
+}
+window.restoreSessionLog = function() {
+    if (_savedLogState == null) return
+    const prev = _savedLogState
+    _savedLogState = null
+    window.toggleSessionLog(prev)
+}
+
+function renderSessionSidebar(s) {
+    const sidebar = document.getElementById('session-sidebar')
+    if (!sidebar) return
+
+    const acTotal = s.ac_total || 0
+    const acDone = s.ac_done || 0
+    const acPct = acTotal > 0 ? Math.round(acDone / acTotal * 100) : 0
+
+    const vCounts = { advanced: 0, stalled: 0, regressed: 0 }
+    let reviewedRounds = 0
+    for (const r of (s.rounds || [])) {
+        if (r.review_result && selectLang(r.review_result)) {
+            const v = r.verdict
+            if (v in vCounts) vCounts[v]++
+            reviewedRounds++
+        }
+    }
+
+    const verdictBars = Object.entries(vCounts).map(([v, count]) => {
+        const pct = reviewedRounds > 0 ? Math.round(count / reviewedRounds * 100) : 0
+        return `

+            ${v}
+            

+            ${count}
+        
`
+    }).join('')
+
+    const acs = s.goal_tracker?.acceptance_criteria || []
+    const acListHtml = acs.map(ac => {
+        const icon = ac.status === 'completed' ? '✓' : ac.status === 'in_progress' ? '◉' : '○'
+        const color = ac.status === 'completed' ? 'var(--verdict-advanced)' : ac.status === 'in_progress' ? 'var(--verdict-active)' : 'var(--text-3)'
+        return `

+            ${icon}
+            ${_esc(ac.id)}: ${_esc(ac.description?.slice(0, 60) || '')}
+        
`
+    }).join('')
+
+    const plan = s.plan_file ? s.plan_file.split('/').pop() : '—'
+    const started = s.started_at ? new Date(s.started_at).toLocaleString() : '—'
+
+    sidebar.innerHTML = `
+        

+            
Overview

+            

+                
${s.current_round}
Rounds

+                
${acPct}%
${t('card.ac')}

+                
${s.tasks_done || 0}
Done

+                
${s.tasks_total || 0}
Total

+            

+        

+        

+            
${t('card.verdict')} Distribution

+            
${verdictBars}

+        

+        

+            
Session Info

+            

+                
Status${t('status.' + s.status)}

+                
${t('card.plan')}${_esc(plan)}

+                
${t('card.branch')}${_esc(s.start_branch || '—')}

+                
${t('card.started')}${started}

+                
${t('card.duration')}${fmtDuration(s.duration_minutes)}

+                
Max Iter${s.max_iterations}

+                
Codex${_esc(s.codex_model || '—')}

+            

+        

+        ${acs.length > 0 ? `
+        

+            
${t('card.ac')} Checklist

+            
${acListHtml}

+            

+            
${acDone}/${acTotal}

+        
` : ''}
+
+        

+            
Upstream Feedback

+            

+                Submit a sanitized methodology report to PolyArch/humanize to help improve the RLCR process.
+            

+            
+            
+        
`
+}
+
+function renderGoalBar(session) {
+    const bar = document.getElementById('goal-bar')
+    if (!bar || !session.goal_tracker) return
+    const acs = session.goal_tracker.acceptance_criteria || []
+    bar.innerHTML = acs.map(ac => {
+        const cls = ac.status === 'completed' ? 'done' : ac.status === 'in_progress' ? 'wip' : ''
+        const icon = ac.status === 'completed' ? '✓' : ac.status === 'in_progress' ? '◉' : '○'
+        return `${icon} ${ac.id}`
+    }).join('')
+}
+
+// ─── Analysis ───
+async function renderAnalysis(sessionId) {
+    const main = document.getElementById('main-content')
+    const session = await api(`/api/sessions/${sessionId}`)
+    if (!session) {
+        main.innerHTML = `
${t('detail.not_found')}
`
+        return
+    }
+
+    // Auto-refresh disabled per user request; reload the page to
+    // pick up a newly generated methodology report.
+
+    const report = selectLang(session.methodology_report)
+    const hasReport = !!report
+
+    let sanitizedHtml = `
${t('analysis.no_report')}
`
+    if (hasReport) {
+        const sanitized = await api(`/api/sessions/${sessionId}/sanitized-issue`)
+        if (sanitized) {
+            const w = sanitized.warnings || {}
+            const hasW = sanitized.requires_review || Object.keys(w).length > 0
+            const warnBanner = hasW ? `
${t('analysis.review_warning')}
${Object.entries(w).map(([c,n]) => `• ${esc(c)}: ${n}`).join(' ')}
` : ''
+            const btns = hasW ? '' : `
`
+            sanitizedHtml = `${warnBanner}
${safeMd(sanitized.body)}
${t('analysis.gh_repo')}: PolyArch/humanize
${btns}
`
+        }
+    }
+
+    main.innerHTML = `
+        

+            

+                
${t('analysis.report_tab')}

+                
${t('analysis.summary_tab')}

+            

+            

+                ${hasReport ? `
${safeMd(report)}
` : `
${t('analysis.no_report')}
`}
+            

+            
+        
`
+
+    document.querySelectorAll('.tab').forEach(tab => {
+        tab.addEventListener('click', () => {
+            document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'))
+            document.querySelectorAll('.tab-content').forEach(el => el.style.display = 'none')
+            tab.classList.add('active')
+            document.getElementById('tab-' + tab.dataset.tab).style.display = 'block'
+        })
+    })
+    window._currentSession = session
+}
+
+// ─── Analytics ───
+async function renderAnalytics() {
+    const main = document.getElementById('main-content')
+    const data = await api('/api/analytics')
+    if (!data) {
+        main.innerHTML = `
${t('analytics.no_data')}
`
+        return
+    }
+
+    const o = data.overview
+
+    main.innerHTML = `
+        

+            
${t('analytics.title')}

+            

+                
${o.total_sessions}
${t('analytics.total')}

+                
${o.average_rounds}
${t('analytics.avg_rounds')}

+                
${o.completion_rate}%
${t('analytics.completion')}

+                
${o.total_bitlessons}
${t('analytics.bitlessons')}

+            

+
+            

+
+            
${t('analytics.comparison')}

+            

+        
`
+
+    // Chart.js panels (rounds per session, duration, verdict
+    // distribution, P-issues, first-COMPLETE, BitLesson growth) were
+    // removed per user request — the four summary tiles + timeline +
+    // session comparison table cover the analytics needs without the
+    // extra chart stack.
+    buildCmpTable(data.session_stats)
+
+    // Load timeline asynchronously (needs full session data, can be slow)
+    if (data.session_stats && data.session_stats.length > 0) {
+        loadTimeline(data.session_stats)
+    }
+}
+
+async function loadTimeline(sessionStats) {
+    const root = document.getElementById('timeline-root')
+    if (!root) return
+
+    try {
+        const sessions = await Promise.all(
+            sessionStats.map(s => api(`/api/sessions/${s.session_id}`).catch(() => null))
+        )
+        const valid = sessions.filter(Boolean)
+        if (valid.length === 0) return
+
+        const rows = valid.map(s => {
+            const dots = (s.rounds || []).map(r => {
+                const v = r.verdict || 'unknown'
+                return ``
+            }).join('')
+            return `

+                ${s.id.slice(5, 16).replace('_', ' ')}
+                
${dots}

+                ${t('status.' + s.status)}
+            
`
+        }).join('')
+
+        root.innerHTML = `
+            
Round Verdict Timeline

+            

+                
${rows}

+                

+                     advanced
+                     stalled
+                     regressed
+                     complete
+                     unknown
+                

+            
`
+    } catch (e) {
+        console.error('[analytics] timeline failed:', e)
+    }
+}
+
+function buildCmpTable(stats) {
+    const root = document.getElementById('cmp-root')
+    if (!root || !stats || !stats.length) return
+
+    const sorted = [...stats].sort((a, b) => {
+        let va, vb
+        switch (_sortCol) {
+            case 'rounds': va = a.rounds; vb = b.rounds; break
+            case 'duration': va = a.avg_duration_minutes || 0; vb = b.avg_duration_minutes || 0; break
+            case 'verdict': va = (a.verdict_breakdown||{}).advanced||0; vb = (b.verdict_breakdown||{}).advanced||0; break
+            case 'rework': va = a.rework_count; vb = b.rework_count; break
+            case 'ac': va = a.ac_completion_rate; vb = b.ac_completion_rate; break
+            default: va = a.session_id; vb = b.session_id
+        }
+        return _sortAsc ? (va < vb ? -1 : va > vb ? 1 : 0) : (va > vb ? -1 : va < vb ? 1 : 0)
+    })
+
+    const arr = c => _sortCol === c ? (_sortAsc ? ' ▲' : ' ▼') : ''
+    const cols = [
+        ['session_id', 'Session'],
+        [null, 'Status'],
+        ['rounds', 'Rounds'],
+        ['duration', 'Duration'],
+        ['verdict', 'Verdict (A/S/R)'],
+        ['rework', 'Rework'],
+        ['ac', 'AC %'],
+    ]
+
+    let html = `
${cols.map(([k, label]) =>
+        k ? `` : ``
+    ).join('')}`
+
+    for (const s of sorted) {
+        const vb = s.verdict_breakdown || {}
+        // Escape every attacker-reachable value before splicing into
+        // the innerHTML template. The backend filter on /api/analytics
+        // already rejects session ids outside `[A-Za-z0-9_.-]+`, so in
+        // practice the escape here is defense-in-depth: a future
+        // producer that forgets to apply the filter should still be
+        // safely rendered rather than breaking out of the inline
+        // onclick / cell HTML (the exact regression Codex Round 23
+        // flagged). `s.status` is trusted (enum from parser.py) but
+        // piped through _esc too for consistency.
+        const idEsc = _esc(s.session_id)
+        html += `
+            
+            
+            
+            
+            
+            
+            
+        `
+    }
+    html += '
${label}${arr(k)}${label}
${idEsc}${_esc(t('status.' + s.status))}${_esc(String(s.rounds))}${s.avg_duration_minutes != null ? _esc(String(s.avg_duration_minutes)) + ' min' : '—'}${_esc(String(vb.advanced||0))}/${_esc(String(vb.stalled||0))}/${_esc(String(vb.regressed||0))}${_esc(String(s.rework_count))}${_esc(String(s.ac_completion_rate))}%
'
+    root.innerHTML = html
+    // Bind navigation via data-attribute + delegated listener so the
+    // session id never flows through an inline JS string literal.
+    // Even if a future backend regression lets through a session id
+    // containing quote/script characters, the value only ever touches
+    // dataset (DOM-level string, never re-parsed as JS) and window
+    // navigation, neither of which evaluates markup.
+    root.querySelectorAll('a.cmp-nav').forEach(a => {
+        a.addEventListener('click', () => navigate('#/session/' + a.dataset.sessionId))
+    })
+    window._cmpStats = stats
+}
+
+function sortCmp(col) {
+    if (_sortCol === col) _sortAsc = !_sortAsc
+    else { _sortCol = col; _sortAsc = true }
+    if (window._cmpStats) buildCmpTable(window._cmpStats)
+}
+
+// ─── Init ───
+document.addEventListener('DOMContentLoaded', () => {
+    initTheme()
+    connectWebSocket()
+    // In remote mode WS is disabled server-side, so kick a slow
+    // polling loop that drives the same targeted-refresh path. In
+    // localhost mode this is a no-op because _startRemotePolling
+    // gates on _isRemoteMode.
+    _startRemotePolling()
+    window.renderCurrentRoute()
+})
diff --git a/viz/static/js/i18n.js b/viz/static/js/i18n.js
new file mode 100644
index 00000000..63bbc8b8
--- /dev/null
+++ b/viz/static/js/i18n.js
@@ -0,0 +1,112 @@
+/* UI labels — English only */
+
+const _LABELS = {
+    'app.title': 'Humanize Viz',
+    'nav.analytics': 'Analytics',
+    'nav.back': '← Back',
+    'home.active': 'Active',
+    'home.completed': 'Completed',
+    'home.empty': 'No RLCR sessions found',
+    'home.empty.hint': 'Start an RLCR loop in your project and sessions will appear here.',
+    'home.rounds_per_day': 'Rounds / day',
+    'card.round': 'Round',
+    'card.plan': 'Plan',
+    'card.branch': 'Branch',
+    'card.verdict': 'Verdict',
+    'card.ac': 'AC',
+    'card.started': 'Started',
+    'card.duration': 'Duration',
+    'detail.summary': 'Summary',
+    'detail.review': 'Codex Review',
+    'detail.phase': 'Phase',
+    'detail.tasks': 'Tasks',
+    'detail.bitlesson': 'BitLesson',
+    'detail.no_summary': 'Summary not yet available',
+    'detail.no_review': 'Review not yet available',
+    'detail.not_found': 'Session not found',
+    'detail.click_node': 'Click a node to expand round details',
+    'ops.view_plan': 'View Plan',
+    'ops.analysis': 'Methodology Analysis',
+    'ops.preview_issue': 'Preview Issue',
+    'ops.export_md': 'Export Markdown',
+    'ops.export_pdf': 'Export PDF',
+    'ops.cancel': 'Cancel Loop',
+    'cancel.title': 'Confirm Cancel',
+    'cancel.message': 'Cancel the current RLCR loop? This cannot be undone.',
+    'cancel.confirm': 'Confirm',
+    'cancel.dismiss': 'Close',
+    'cancel.failed': 'Cancel failed',
+    'analysis.report_tab': 'Methodology Report',
+    'analysis.summary_tab': 'Sanitized Summary',
+    'analysis.no_report': 'Analysis report not yet available',
+    'analysis.gh_repo': 'Target repo',
+    'analysis.preview': 'Preview Issue',
+    'analysis.send': 'Send to GitHub',
+    'analysis.copy': 'Copy Content',
+    'analysis.sent': 'Sent',
+    'analysis.sending': 'Sending...',
+    'analysis.failed': 'Failed',
+    'analysis.issue_title': 'Title',
+    'analysis.issue_body': 'Body',
+    'analysis.review_warning': '⚠ Sanitization check found issues. Review the methodology report manually and remove project-specific content before sending.',
+    'analytics.title': 'Cross-Session Analytics',
+    'analytics.total': 'Total Sessions',
+    'analytics.avg_rounds': 'Avg Rounds',
+    'analytics.completion': 'Completion Rate',
+    'analytics.bitlessons': 'Total BitLessons',
+    'analytics.comparison': 'Session Comparison',
+    'analytics.no_data': 'No analytics data',
+    'analytics.col_session': 'Session',
+    'analytics.col_status': 'Status',
+    'analytics.rework': 'Rework',
+    'status.active': 'Active',
+    'status.complete': 'Complete',
+    'status.cancel': 'Cancelled',
+    'status.stop': 'Stopped',
+    'status.maxiter': 'Max Iter',
+    'status.unknown': 'Unknown',
+    'status.analyzing': 'Analyzing',
+    'status.finalizing': 'Finalizing',
+    'phase.implementation': 'Impl',
+    'phase.code_review': 'Review',
+    'phase.finalize': 'Final',
+    'node.setup': 'Setup',
+    'unit.min': 'min',
+}
+
+function t(key) {
+    return _LABELS[key] || key
+}
+
+// Content language selection from {zh, en} objects — prefer English
+function selectLang(content) {
+    if (!content) return null
+    if (typeof content === 'string') return content
+    if (typeof content === 'object') {
+        return content['en'] || content['zh'] || null
+    }
+    return null
+}
+
+// Safe Markdown rendering — parse then sanitize to prevent XSS.
+// Fails closed to plain-text escape when the DOMPurify CDN dep isn't
+// loaded (offline, blocked by firewall, or a CSP that forbids
+// unpkg.com). The earlier implementation returned the raw
+// marked.parse() output in that case, which re-opens the XSS
+// surface the sanitizer was supposed to close — plan files, round
+// summaries, review results, methodology reports, and the Preview
+// Issue modal all feed markdown into the DOM through this helper.
+function safeMd(text) {
+    if (!text) return ''
+    if (typeof DOMPurify === 'undefined' || typeof marked === 'undefined') {
+        // Fall back to escaped plain text so a missing CDN dep is a
+        // visible degradation (monospace text) rather than a silent
+        // XSS foot-gun. Mirrors the _esc() round-trip that every
+        // attribute-level escape in app.js / pipeline.js uses.
+        const d = document.createElement('div')
+        d.textContent = String(text)
+        return `
${d.innerHTML}
`
+    }
+    const html = marked.parse(text)
+    return DOMPurify.sanitize(html)
+}
diff --git a/viz/static/js/pipeline.js b/viz/static/js/pipeline.js
new file mode 100644
index 00000000..6ccbedba
--- /dev/null
+++ b/viz/static/js/pipeline.js
@@ -0,0 +1,485 @@
+/* Pipeline — snake-path node layout with SVG connectors + zoom/pan + flyout detail */
+
+const PL = {
+    COLS: 4,
+    NODE_W: 230,
+    NODE_H: 68,
+    GAP_X: 52,
+    GAP_Y: 48,
+    TURN_H: 56,
+    PADDING: 40,
+}
+
+let _scale = 1, _tx = 0, _ty = 0
+let _dragging = false, _dragStartX = 0, _dragStartY = 0, _dragTx = 0, _dragTy = 0
+
+// Window-level drag listeners are installed exactly once across the
+// lifetime of the page. renderPipeline() is invoked on every SSE-
+// driven session refresh, so registering window listeners per render
+// would leak a growing number of handlers and process each drag event
+// N times after N re-renders. The per-viewport mousedown listener
+// stays per-render (the viewport DOM node is replaced on every render
+// anyway) but the window-level mousemove/mouseup pair is persistent.
+// onDragMove/onDragEnd are safe no-ops when _dragging is false, so
+// installing them once is correct.
+let _dragListenersInstalled = false
+function _ensureDragListeners() {
+    if (_dragListenersInstalled) return
+    window.addEventListener('mousemove', onDragMove)
+    window.addEventListener('mouseup', onDragEnd)
+    _dragListenersInstalled = true
+}
+
+function renderPipeline(container, session) {
+    if (!container || !session) return
+    const rounds = session.rounds || []
+    if (rounds.length === 0) {
+        container.innerHTML = `
○
${t('home.empty')}
`
+        return
+    }
+
+    const isActive = session.status === 'active'
+    // Total node count: rounds + 1 ghost node for active sessions
+    const totalNodes = isActive ? rounds.length + 1 : rounds.length
+    const positions = computePositions(totalNodes)
+    const totalW = PL.PADDING * 2 + PL.COLS * PL.NODE_W + (PL.COLS - 1) * PL.GAP_X
+    const rows = Math.ceil(totalNodes / PL.COLS)
+    const totalH = PL.PADDING * 2 + rows * PL.NODE_H + (rows - 1) * (PL.GAP_Y + PL.TURN_H)
+
+    let svgPaths = ''
+    for (let i = 0; i < totalNodes - 1; i++) {
+        const isLastEdge = isActive && i === rounds.length - 1
+        svgPaths += buildConnector(positions[i], positions[i + 1], isLastEdge)
+    }
+
+    let nodesHtml = ''
+    rounds.forEach((r, idx) => {
+        nodesHtml += renderNodeCard(r, session, positions[idx])
+    })
+
+    // Ghost "in progress" node for active sessions
+    if (isActive) {
+        const ghostPos = positions[rounds.length]
+        nodesHtml += renderGhostNode(session, ghostPos)
+    }
+
+    _scale = 1; _tx = 0; _ty = 0
+
+    container.innerHTML = `
+        

+            

+                

+                    
+                    
+                    
+                

+                

+                    
+                        ${svgPaths}
+                    
+                    ${nodesHtml}
+                

+            

+        

+        

+            

+        
`
+
+    const vp = document.getElementById('pl-viewport')
+    vp.addEventListener('wheel', onWheel, { passive: false })
+    vp.addEventListener('mousedown', onDragStart)
+    _ensureDragListeners()
+
+    setTimeout(() => plFit(), 50)
+}
+
+// Incremental pipeline update used by WS-push driven refreshes.
+// Appends new node cards for rounds that weren't in the DOM yet,
+// updates in place the ones whose verdict / active flag changed,
+// refreshes the ghost node, and only touches the SVG connectors'
+// paths. The outer #pl-viewport with its zoom / pan / controls is
+// left intact, so the user's current view (scale, translate)
+// survives across rounds instead of snapping back to fit every
+// time a new round arrives.
+function _updatePipelineIncremental(container, session) {
+    const canvas = container && container.querySelector('#pl-canvas')
+    const svg = canvas && canvas.querySelector('.pl-svg')
+    if (!canvas || !svg) {
+        // No incremental substrate yet (empty state or never
+        // rendered). Fall back to the full render path.
+        renderPipeline(container, session)
+        return
+    }
+    const rounds = session.rounds || []
+    if (rounds.length === 0) {
+        renderPipeline(container, session)
+        return
+    }
+
+    const isActive = session.status === 'active'
+    const totalNodes = isActive ? rounds.length + 1 : rounds.length
+    const positions = computePositions(totalNodes)
+    const totalW = PL.PADDING * 2 + PL.COLS * PL.NODE_W + (PL.COLS - 1) * PL.GAP_X
+    const rows = Math.ceil(totalNodes / PL.COLS)
+    const totalH = PL.PADDING * 2 + rows * PL.NODE_H + (rows - 1) * (PL.GAP_Y + PL.TURN_H)
+
+    // 1) Update / append real (non-ghost) node cards.
+    const existing = Array.from(canvas.querySelectorAll('.canvas-tile:not(.is-queued)'))
+    existing.sort((a, b) => Number(a.dataset.round) - Number(b.dataset.round))
+
+    // Put existing nodes into a round-number -> element map so we can
+    // update or replace them without assuming DOM order.
+    const byRound = new Map(existing.map(el => [Number(el.dataset.round), el]))
+
+    for (let i = 0; i < rounds.length; i++) {
+        const r = rounds[i]
+        const pos = positions[i]
+        const el = byRound.get(r.number)
+        if (!el) {
+            // New round -> append.
+            const tmp = document.createElement('div')
+            tmp.innerHTML = renderNodeCard(r, session, pos).trim()
+            canvas.appendChild(tmp.firstChild)
+            continue
+        }
+        const verdict = r.verdict || 'unknown'
+        const shouldActive = isActive && r.number === session.current_round
+        const verdictChanged = el.dataset.verdict !== verdict
+        const activeChanged = el.classList.contains('active-round') !== shouldActive
+        if (verdictChanged || activeChanged) {
+            // Replace the single node in place (cheap) to re-render
+            // the verdict dot, active indicator and mini-stats.
+            const tmp = document.createElement('div')
+            tmp.innerHTML = renderNodeCard(r, session, pos).trim()
+            el.replaceWith(tmp.firstChild)
+        }
+        byRound.delete(r.number)
+    }
+    // Any leftover entries in byRound are rounds that disappeared
+    // from the payload (shouldn't happen in normal flow; defensive).
+    for (const el of byRound.values()) el.remove()
+
+    // 2) Ghost node — remove the old one, add a fresh one at the
+    // new position when the session is still active.
+    const oldGhost = canvas.querySelector('.canvas-tile.is-queued')
+    if (oldGhost) oldGhost.remove()
+    if (isActive) {
+        const ghostPos = positions[rounds.length]
+        const tmp = document.createElement('div')
+        tmp.innerHTML = renderGhostNode(session, ghostPos).trim()
+        canvas.appendChild(tmp.firstChild)
+    }
+
+    // 3) Redraw the SVG connectors. The SVG is a single sub-element
+    // of the canvas; innerHTML-swapping its / children
+    // does not blow away the surrounding canvas or the user's zoom
+    // state.
+    let svgPaths = ''
+    for (let i = 0; i < totalNodes - 1; i++) {
+        const isLastEdge = isActive && i === rounds.length - 1
+        svgPaths += buildConnector(positions[i], positions[i + 1], isLastEdge)
+    }
+    svg.innerHTML = svgPaths
+    svg.setAttribute('width', String(totalW))
+    svg.setAttribute('height', String(totalH))
+    svg.setAttribute('viewBox', `0 0 ${totalW} ${totalH}`)
+
+    // 4) Canvas size may have grown (new row).
+    canvas.style.width = `${totalW}px`
+    canvas.style.height = `${totalH}px`
+}
+
+// Expose for app.js's targeted refresh path. Kept as a window
+// property (rather than a module export) to match the project's
+// existing non-modular script loading.
+window._updatePipelineIncremental = _updatePipelineIncremental
+
+function computePositions(count) {
+    const positions = []
+    for (let i = 0; i < count; i++) {
+        const row = Math.floor(i / PL.COLS)
+        const colInRow = i % PL.COLS
+        const reversed = row % 2 === 1
+        const col = reversed ? (PL.COLS - 1 - colInRow) : colInRow
+        positions.push({
+            x: PL.PADDING + col * (PL.NODE_W + PL.GAP_X),
+            y: PL.PADDING + row * (PL.NODE_H + PL.GAP_Y + PL.TURN_H),
+            row, col, reversed
+        })
+    }
+    return positions
+}
+
+function buildConnector(a, b, animated) {
+    const ay = a.y + PL.NODE_H / 2
+    const by = b.y + PL.NODE_H / 2
+    const cls = animated ? 'class="pl-edge-active"' : ''
+    const color = animated ? 'var(--accent)' : 'var(--border-2)'
+    const style = `fill="none" stroke="${color}" stroke-width="2" stroke-dasharray="6 4" ${cls}`
+
+    if (a.row === b.row) {
+        const x1 = a.reversed ? a.x : a.x + PL.NODE_W
+        const x2 = a.reversed ? b.x + PL.NODE_W : b.x
+        return ``
+    }
+
+    const exitX = a.reversed ? a.x : a.x + PL.NODE_W
+    const enterX = b.reversed ? b.x + PL.NODE_W : b.x
+    const midY = (a.y + PL.NODE_H + b.y) / 2
+    const sideX = a.reversed ? Math.min(a.x, b.x) - PL.GAP_X * 0.4 : Math.max(a.x + PL.NODE_W, b.x + PL.NODE_W) + PL.GAP_X * 0.4
+
+    return ``
+}
+
+function renderNodeCard(r, session, pos) {
+    const hasSummary = !!selectLang(r.summary)
+    const verdict = r.verdict || 'unknown'
+    const isActive = session.status === 'active' && r.number === session.current_round
+    const phaseLabel = r.number === 0 ? t('node.setup') : (t(`phase.${r.phase}`) || r.phase)
+
+    const stats = []
+    if (r.duration_minutes) stats.push(`${r.duration_minutes}${t('unit.min')}`)
+    if (r.bitlesson_delta && r.bitlesson_delta !== 'none') stats.push('BL+')
+    if (!hasSummary) stats.push('…')
+
+    // Reference-kit canvas tile: verdict-colored left stripe, mono
+    // micro-stats row, optional sweep-bar when the node is the
+    // in-flight round. Positioning / connector logic still driven
+    // by the snake-path layout above.
+    const classes = ['canvas-tile']
+    classes.push(`verdict-${verdict}`)
+    if (isActive) classes.push('is-running')
+
+    const headLeft = `
+        R${r.number}
+        ${esc(phaseLabel)}
+    `
+    const headRight = isActive
+        ? ''
+        : ``
+
+    const statsRow = stats.length
+        ? `
${stats.map(s => `${esc(s)}`).join('')}
`
+        : `
${esc(verdict)}
`
+
+    const runningBar = isActive
+        ? '
'
+        : ''
+
+    return `
+        

+            ${runningBar}
+            

+                
${headLeft}

+                ${headRight}
+            

+            ${statsRow}
+        
`
+}
+
+function renderGhostNode(session, pos) {
+    const nextRound = session.current_round + 1
+    // Reference-kit "queued / awaiting" tile: dashed accent border,
+    // dim, no click handler. Paired with the pl-edge-active
+    // animated connector drawn in the SVG layer above.
+    return `
+        

+            

+                

+                    R${nextRound}
+                    Next
+                

+                
+            

+            
Awaiting…

+        
`
+}
+
+
+// ─── Flyout Modal (expand from node to center) ───
+
+function openFlyout(nodeEl, roundNum) {
+    if (_dragging) return
+    const session = window._currentSession
+    if (!session) return
+    const round = session.rounds.find(r => r.number === roundNum)
+    if (!round) return
+
+    // Auto-collapse the session-detail log panel while the flyout is
+    // open so the reader has more screen real estate for the node's
+    // expanded details. closeFlyout() restores whatever state the
+    // user had (normal/expanded) before the click.
+    if (typeof window.autoCollapseSessionLog === 'function') {
+        window.autoCollapseSessionLog()
+    }
+
+    const overlay = document.getElementById('flyout-overlay')
+    const panel = document.getElementById('flyout-panel')
+    if (!overlay || !panel) return
+
+    // Get node position on screen
+    const rect = nodeEl.getBoundingClientRect()
+    const vpRect = overlay.parentElement.getBoundingClientRect()
+
+    // Set initial position to match node
+    panel.style.transition = 'none'
+    panel.style.left = (rect.left - vpRect.left) + 'px'
+    panel.style.top = (rect.top - vpRect.top) + 'px'
+    panel.style.width = rect.width + 'px'
+    panel.style.height = rect.height + 'px'
+    panel.style.opacity = '0.7'
+    panel.style.borderRadius = '14px'
+    panel.innerHTML = ''
+
+    // Show overlay
+    overlay.classList.add('visible')
+
+    // Animate to center
+    requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+            const targetW = Math.min(720, vpRect.width - 80)
+            const targetH = Math.min(vpRect.height - 100, 600)
+            const targetL = (vpRect.width - targetW) / 2
+            const targetT = (vpRect.height - targetH) / 2
+
+            panel.style.transition = 'all 400ms cubic-bezier(0.16, 1, 0.3, 1)'
+            panel.style.left = targetL + 'px'
+            panel.style.top = targetT + 'px'
+            panel.style.width = targetW + 'px'
+            panel.style.height = targetH + 'px'
+            panel.style.opacity = '1'
+            panel.style.borderRadius = '20px'
+
+            // Fill content after animation starts
+            setTimeout(() => {
+                panel.innerHTML = buildFlyoutContent(round, session)
+            }, 150)
+        })
+    })
+}
+
+function closeFlyout() {
+    const overlay = document.getElementById('flyout-overlay')
+    const panel = document.getElementById('flyout-panel')
+    if (!overlay || !panel) return
+
+    panel.style.transition = 'all 300ms cubic-bezier(0.45, 0, 0.55, 1)'
+    panel.style.opacity = '0'
+    panel.style.transform = 'scale(0.9)'
+
+    setTimeout(() => {
+        overlay.classList.remove('visible')
+        panel.style.transform = ''
+        panel.innerHTML = ''
+    }, 300)
+
+    // Restore the log panel to whatever state it had before the
+    // flyout auto-collapsed it.
+    if (typeof window.restoreSessionLog === 'function') {
+        window.restoreSessionLog()
+    }
+}
+
+function buildFlyoutContent(round, session) {
+    const verdict = round.verdict || 'unknown'
+    const phaseLabel = round.number === 0 ? t('node.setup') : (t(`phase.${round.phase}`) || round.phase)
+    const summary = selectLang(round.summary)
+    const review = selectLang(round.review_result)
+
+    const summaryHtml = summary ? safeMd(summary) : `${t('detail.no_summary')}`
+    const reviewHtml = review ? safeMd(review) : `${t('detail.no_review')}`
+
+    let metaItems = `
+        ${t('detail.phase')}: ${esc(phaseLabel)}
+        ${t('card.verdict')}: ${verdict}`
+    if (round.duration_minutes) metaItems += `${t('card.duration')}: ${round.duration_minutes} ${t('unit.min')}`
+    if (round.bitlesson_delta && round.bitlesson_delta !== 'none') metaItems += `${t('detail.bitlesson')}: ${round.bitlesson_delta} 📚`
+    if (round.task_progress != null) metaItems += `${t('detail.tasks')}: ${round.task_progress}/${session.tasks_total || '?'}`
+
+    return `
+        

+            

+                R${round.number}
+                
${t('card.round')} ${round.number}

+            

+            
+        

+        
${metaItems}

+        

+            

+                
${t('detail.summary')}

+                
${summaryHtml}

+            

+            

+                
${t('detail.review')}

+                
${reviewHtml}

+            

+        
`
+}
+
+// ─── Zoom / Pan ───
+function applyTransform() {
+    const canvas = document.getElementById('pl-canvas')
+    if (canvas) canvas.style.transform = `translate(${_tx}px, ${_ty}px) scale(${_scale})`
+}
+
+function plZoom(delta) {
+    _scale = Math.max(0.3, Math.min(2.5, _scale + delta))
+    applyTransform()
+}
+
+function plFit() {
+    const vp = document.getElementById('pl-viewport')
+    const canvas = document.getElementById('pl-canvas')
+    if (!vp || !canvas) return
+    const vpW = vp.clientWidth, vpH = vp.clientHeight
+    const cW = parseInt(canvas.style.width), cH = parseInt(canvas.style.height)
+    _scale = Math.min(vpW / cW, vpH / cH, 1) * 0.92
+    _tx = (vpW - cW * _scale) / 2
+    _ty = Math.max(8, (vpH - cH * _scale) / 2)
+    applyTransform()
+}
+
+function onWheel(e) {
+    e.preventDefault()
+    const delta = e.deltaY > 0 ? -0.08 : 0.08
+    const rect = e.currentTarget.getBoundingClientRect()
+    const mx = e.clientX - rect.left, my = e.clientY - rect.top
+    const oldScale = _scale
+    _scale = Math.max(0.3, Math.min(2.5, _scale + delta))
+    const ratio = _scale / oldScale
+    _tx = mx - ratio * (mx - _tx)
+    _ty = my - ratio * (my - _ty)
+    applyTransform()
+}
+
+function onDragStart(e) {
+    if (e.target.closest('.canvas-tile') || e.target.closest('.pl-ctrl-btn')) return
+    _dragging = true
+    _dragStartX = e.clientX; _dragStartY = e.clientY
+    _dragTx = _tx; _dragTy = _ty
+    e.currentTarget.style.cursor = 'grabbing'
+}
+
+function onDragMove(e) {
+    if (!_dragging) return
+    _tx = _dragTx + (e.clientX - _dragStartX)
+    _ty = _dragTy + (e.clientY - _dragStartY)
+    applyTransform()
+}
+
+function onDragEnd() {
+    if (!_dragging) return
+    _dragging = false
+    const vp = document.getElementById('pl-viewport')
+    if (vp) vp.style.cursor = ''
+}
+
+function esc(str) {
+    const d = document.createElement('div')
+    d.textContent = str || ''
+    return d.innerHTML
+}