Codev v2 UI

[pseudoseed]

Tracking issue for the Codev v2 UI. Not a spec, and not implementation authorization.

Where this came from

codev/research/codev-v2-ui-frd.md (rev. 5, decided 2026-08-21). Design language and
mockups in codev/research/v2-mockups/.

What is decided

• Option 2: a new fork-owned apps/v2/ pnpm workspace, mounted through one
  if (url.pathname.startsWith('/v2/')) block in tower-routes.ts. Additive, because
  this repo is a fork of an active upstream and edits to hot upstream files are paid as
  merge conflicts forever.
• Multi-machine ships in v1. This is what selected Option 2.
• Both UIs run indefinitely by design. The old UI stays the surface that merges upstream.
• Design language approved. Rust means a human is needed, and is used for gates and
  nothing else. Ochre means something may be wrong but nobody is blocked. Moss means
  healthy. Ink is everything else.
• 48 numbered requirements (FR-1 to FR-48) in Part 4 of the FRD.

The gate before any spec

The FRD requires all blocking spikes to run before a spec is written. Ranked:

1. Multi-client resize policy, solved in the v2 layer, never in pty-session.ts.
2. HTTPS on a phone via Tailscale Serve, through to one delivered push notification.
   If this fails, the mobile half of the FRD is fiction.
3. iPad keyboard weekend test on the current app. Human, no code.
4. Terminal.tsx reuse strategy. Recommendation stands: import unmodified for v1.
5. dockview on a real iPad, only if FR-7's tablet clause is promoted to MUST.

Still open

• Transport shape (Part 6 Q3). Both reviewers: one typed control socket per environment,
  PTY sockets left alone. The library worth having is the schema, not the transport.
• Tailscale as a hard MUST (Q4). FR-37 already reads MUST; spike 2 decides it in fact.
• Mobile reach (Q7). Both reviewers: PWA now, Capacitor as a door not walked through,
  never SwiftUI.
• Space Grotesk should be swapped. There is no dark mode.

Acceptance scenario

From a locked iPad on the sofa: a notification arrives that builder X is gate-waiting.
Tap it. Read the last 50 lines of that builder's terminal. Approve. Confirm the next
phase started. Under 30 seconds, no page reload.

[pseudoseed]

Spike 1 done (#38, PR #45 merged)

Policy chosen: follow the focused client. FR-38 is met additively; pty-session.ts untouched. Last-writer-wins reproduced against current code, not assumed. Notes at codev/experiments/38-multi-client-resize/.

Two things this adds to the spec's job:

• Mixed v1+v2 attach is a scope decision. A v1 client still calls resize() via tower-websocket.ts:80 and pty-manager.ts:239/369. Forbid mixed attach, or accept the gap while the old UI is still used on a session. Routing v1 through the broker means editing a hot upstream file.
• Focus needs its own tiebreak. Two explicit focus frames are last-writer-wins one layer up. Treat viewer input as implicit focus in the production module.

Appendix spike 1 can be struck. The production broker module is follow-up work under this issue.

Spike 2 in progress (#39)

Blocked at gate 1: Tailscale is not installed on this machine (not on PATH, no /Applications/Tailscale.app). Environment gap, not a finding.

Everything not gated on it already passed, and it settles a Part 0 question:

• Tower's host allowlist rejects a MagicDNS Host with 401, as predicted (server-utils.ts:252).
• A fork-owned ingress on :4110 rewrites Host and gets through without touching or restarting Tower.
• A real Tower terminal WebSocket echoes through that ingress, frames captured.

So the additive ingress seam is demonstrated rather than assumed. Unproven: the Tailscale cert and every phone gate.

[pseudoseed]

Gate 2 is now a design question, not a spike question

Spike 2 (#39) can prove the cert, service worker registration, push permission and one delivered notification using a static page hosted in the infra cluster. It cannot prove the terminal WebSocket, and the reason matters more than the gap.

Tower must never be publicly routed. It spawns agents and executes shell, so a misconfigured edge policy turns it into unauthenticated remote code execution on a personal machine. The infra owner has already seen an admin surface ship where Cloudflare Access existed in intent and the protection did not exist in fact, found by a scanner rather than internally.

That breaks the FRD's acceptance scenario as written. A PWA served over HTTPS cannot open a connection to http://<lan-ip>:4110; the browser blocks it as mixed content. A VPN does not fix this — it is a browser rule, not a network one. So the notification arrives and the terminal it refers to cannot load.

Rejected: give Tower a cert via DNS-01

Proposed and withdrawn. Four reasons, all checked against the estate rather than argued:

1. There is no ACME anywhere in that cluster. All 43 hostnames terminate TLS at Cloudflare's edge. This would introduce a subsystem, not change a config.
2. The cert would land on an unmanaged laptop, unmonitored, on a 90-day clock, in an estate whose signature failure is silent expiry.
3. It makes an unmanaged VPN load-bearing.
4. A public name resolving to an RFC1918 address is the textbook DNS-rebinding shape, and resolvers that block it would make the name fail to resolve on the LAN.

Candidate answer: invert the direction

Tower does not need a cert and does not need to be reachable. It needs to dial out. A thin relay in the cluster sits behind the existing tunnel and Access; Tower holds an outbound WSS connection to it; the PWA talks HTTPS and WSS to the relay. Nothing ever connects inbound to the laptop.

This removes the cert, the inbound path and the VPN dependency, and unlike every other option it actually works off-LAN, which the acceptance scenario requires.

The constraint that makes or breaks it: the relay must not become a generic shell proxy. Tower speaks a narrow protocol — stream terminal output, accept a signed approve or deny against a specific gate id — and forwards nothing arbitrary. Anything looser makes gate approval reachable from the internet, and gate approval is the one action in this system that is defined as requiring a human.

The cheaper option, which may be the right one

Notifications work anywhere; approvals require you on the LAN. Costs nothing, ships now, no relay, no new attack surface. It narrows the acceptance scenario from "from the sofa, anywhere" to "from the sofa, at home."

Open decision for the human. FR-19 and Part 5's acceptance scenario both depend on the answer.

[pseudoseed]

Spike 2 complete (#39). The spike gate is cleared.

All five gates pass on a real iPhone, not on Playwright WebKit.

Gate	Result	Evidence
1. Trusted cert	PASS	Google Trust Services WE1, SAN *.pseudoseed.com, ssl_verify_result=0, no warning on device
1b. Access enforced	PASS	every path including /sw.js 302s to pseudoseed.cloudflareaccess.com unauthenticated
3. PWA install	PASS	standalone: true, secureContext: true, SW registered at the origin
4. Push permission	PASS	granted inside the installed PWA
5. Delivered push	PASS	real web.push.apple.com subscription, accepted 201, notification arrived on a locked device
2. WebSocket	OUT OF SCOPE	LAN-only approvals, human decision

The finding that mattered

Cloudflare Access does not break Add to Home Screen or service worker registration on iOS. The Access session carries into the standalone PWA even though every path, /sw.js included, is challenged when unauthenticated.

This was the outcome that would have forced FR-36 to be rewritten. One device, one iOS version, so it is evidence rather than a guarantee.

A requirement nobody would have predicted

The first push failed 403 BadJwtToken. Cause was ours: the VAPID subject was mailto:exp39@localhost, and Apple rejects a subject on a non-real domain. Changing it to https://ade.pseudoseed.com sent successfully, with unchanged keys and unchanged subscription.

The error names nothing useful and this would have shipped. The VAPID subject must be a real https origin or a real mailto.

Where the mobile half now stands

Rev. 4's warning was that if the HTTPS-on-a-phone path failed, the mobile half of the FRD was fiction. It did not fail. The whole chain is proven end to end: trusted cert, secure context, service worker, installed PWA, push permission, delivered notification on a locked device.

Open questions, resolved

• Q3 transport. Both reviewers converged independently: one typed control socket per environment, PTY sockets left alone, and the library worth having is the schema rather than the transport. Spike 1 confirms the PTY half is right, since the resize fix lives in a v2 wrapper and never in PtySession. Taking it as settled.
• Q7 mobile reach. PWA, now demonstrated rather than argued. Capacitor stays a door not walked through. Closed.
• Appendix spikes 3 and 5. Spike 3 existed to decide PWA versus a Capacitor shell; that decision made itself. Spike 5 stays conditional on FR-7's tablet clause being promoted to MUST.

Nothing now blocks the v2 spec.

[pseudoseed]

Program status

Spikes: done. #38 (multi-client resize) and #39 (HTTPS to a locked-device push) both merged, both answered, both proved the additive seam Part 0 depends on.

Spec 52 (v2 server events): in review, rev. 9. PR #53.

Nine revisions against the opencode/Grok lane. Every round has found a real defect rather than style notes, which is why it is still running:

Rev	What the review caught
1	D2 said the schema is the contract; no schema was written
2	seq was per-connection, so since resume could not work at all
3	Builder ids collided across workspaces (PRIMARY KEY (workspace_path, id))
4	done and offline precedence fixed for two revisions before noticing neither could be computed
5	idle was unreachable; stalled left completed builders matching no status
6	A stale block from rev. 2 still contradicted rev. 6's own table
7	snapshot consuming a cursor would silently skip the first delta after every resume
8	lastDataAt churn would exhaust the resume buffer in seconds; parent gone orphaned children

Each of those would have reached a builder and become wasted implementation.

Decisions locked along the way: four statuses that are all actually computable (gate-waiting, offline, stalled, running); no done and no idle, because nothing on the wire carries them; ids qualified by workspace and keyed on the worktree name so they are stable from creation; liveness never fires gone.

Next: once the verdict is clean, spawn a builder on the opencode/Grok harness. The client shell is a separate spec after this one.