v2 client shell: apps/v2 renders the live hierarchy

[pseudoseed]

Second buildable unit of the Codev v2 UI program (#37), after spec 52 shipped the server events.

What this is

apps/v2 exists and renders the live hierarchy. Nothing else.

One page, at /v2/, that opens the /v2/events stream and draws the site view from the approved design: machine lot, workspace plot, architect header, builder row, with live status and the activity sparkline. It reads. It does not act.

Why this scope

Spec 52's stream has never been consumed by anything. It was tested against fake clients in its own suite and no browser has opened it. The first client is therefore also the first real test of the contract: scoped snapshot, streamId-bound resume, four statuses, tick buckets, counts rollups, gone semantics.

Anything larger buries that. If tiling, terminals and gates all land in the same unit and the tree renders wrong, the cause could be any of them.

In scope

• New apps/v2 pnpm workspace, fork-owned (FRD Part 0). Zero edits to apps/web, tower.html, apps/vscode, apps/streamdeck.
• Served from the existing /v2/ mount. No second insertion point in tower-routes.ts — the mount is already there and the next route reuses it.
• Consumes GET /v2/events via fetch + ReadableStream, not EventSource, which cannot set the codev-tower-key header.
• Renders FR-1 (containment, not an outline), FR-3 (builder under its spawning architect), FR-4 (live status, pushed), FR-41 (activity sparkline), FR-42 (stalled distinct from idle and gate-waiting).
• Uses tokens.css and tokens-dark.css as shipped. Colour discipline is binding: rust means a human is needed and is used for gates and nothing else.
• FR-15: one machine unreachable degrades that subtree only. A dark frame renders as a dark machine, never as an empty tree.

Out of scope

Tiling, terminals, gates UI, multi-machine pairing, the command palette, mobile layouts, theme switching. Each is its own unit. Reading the tree is this one.

The design of record

UX Pilot page SXl8jE8uNyYLwBsG6vsL, 27 designs on main at codev/research/v2-mockups/uxpilot/.

The site view is 01-site.html in codev/research/v2-mockups/, which is real markup with the pattern classes: .plot, .corner, .stake, .spark, .stamp, .grid-bg, .dim-sub, .needs-attn.

Measure a design before scoring it against a breakpoint requirement. Group names are not viewports; that mistake already produced one false finding (FRD rev. 9).

Constraints

• Additive only. New files under apps/v2/; the /v2/ mount already exists.
• Do not modify v2-sampler.ts, v2-events.ts, v2-routes.ts or the wire contract. If the contract is wrong, that is a finding to report, not an edit to make.
• FR-49 applies from the first line: a pane is a viewer. Nothing in the client may destroy a session. This unit has no panes yet, and the ownership rule is established before anything can violate it.
• Known divergence to carry: dockview's sashWidth stays 4 in JS while its CSS hit region is 44 ([Spike] v2 UI: can a finger drag a dockview split on a real iPad? #62). Not used in this unit; it lands with tiling.

What "done" looks like

Open /v2/ in a browser, see the real hierarchy of this machine, watch a builder spawn and appear without a reload, watch it go stalled after IDLE_WAITING_THRESHOLD_MS, and watch it disappear on afx cleanup. No polling anywhere in the client.

Reference

• FRD rev. 9: codev/research/codev-v2-ui-frd.md
• Wire contract: codev/specs/52-v2-server-events.md
• Server: packages/codev/src/agent-farm/servers/v2-*.ts
• Auth precedent: apps/web/src/hooks/useSSE.ts (why fetch+stream, not EventSource)

[pseudoseed]

PR #104 merged. Issue left open for verify.

Follow-ups filed:

• Bare GET /v2 (no trailing slash) 401s #105 Bare GET /v2 (no trailing slash) 401s
• A thrown /v2/events fetch discards the drawn tree #106 A thrown /v2/events fetch discards the drawn tree
• apps/v2 Playwright is not in the root CI matrix #107 apps/v2 Playwright is not in the root CI matrix

Already filed: #98 (open), #100 (open). #97 is closed.

Review links: codev/reviews/83-v2-client-shell.md lines 32 and 209 cite #97, #98, and #100.

[pseudoseed]

Closed by #104, merged 2026-08-24.

apps/v2 exists and /v2/ renders the live hierarchy from GET /v2/events. Verified live against Tower on :4100 after merge — 22 workspaces, 60 builders, real statuses. Keyless GET /v2/ returns 200 and the assets load.

Verified by the architect, not relayed

• 127 client tests, 3,394 server tests (0 failures), 15/15 Playwright
• Frozen files: zero diff vs origin/main on all 12 C1/C2 paths, tower-routes.ts included
• Cold load 42ms against a 2,000ms budget; idle 0 B/s against 1 KB/s — that zero is the no-polling requirement v2 exists to satisfy
• Rendered at 1440 and screenshotted twice, fixture and live: containment holds, --rust appears only on the GATE stamp, counts read as machine totals, heldMail marks render

Change surface outside apps/v2: v2-static.ts (new), v2-routes.ts +4/−4 prologue, server-utils.ts +2 for the two public-route clauses, four test files, one CI step.

What the stream taught us

The contract had never been consumed. Opening it by hand produced seven facts no code reading had, and each changed the spec:

Observed	Result
No machine node is ever emitted	D10 — the local machine is the page's frame
counts is machine-wide, off by 45 against a one-workspace scope	D11 — footer, labelled machine totals
encodeURIComponent(paths.join(',')) → HTTP 200, empty tree, no error	D12 — encode each path, literal comma
A dark workspace has no node to mark	D5 — darkPaths is a separate store
Two connections both start at seq: 0	D1 — the cursor is per-streamId; a global rule kills the page on every Tower restart
buckets is an array on a node, an object on a tick	D1 — one name, two shapes
Dark is decided once per connection and can never clear	#98

Two of my own findings were wrong and were retracted after re-measuring — FR-3 at rev. 12, filed as #97 and closed as already-working.

Deferred, honestly

FR-15 is not satisfied. It requires one environment to degrade its subtree only; an environment is a connected Tower and this unit has exactly one, so when it is unreachable the whole page is the subtree. It lands with pairing.

Follow-ups

#111 — short plots stretched to the tallest in their row, wasting most of the page at real volume. Only visible live; the one-workspace fixture could never show it.
#98 — dark evaluated once per connection.
#100 — orphaned worktrees can be seen by every surface and removed by none. 40 of the 60 builders on this page are orphans.