Cockpit QA Checklist

A living punch list of manual test cases for the OptimalOS Fabric cockpit at fabric.optimal.miami, organized by surface area. Use it as a scan-before-you-merge sanity sweep — not as a substitute for unit / integration tests, just the things only a human at the keyboard can verify.

Legacy mode (fabric.optimal.miami on the Pi) is out of scope here — its cockpit is intentionally minimal. See Deployment modes for the split.

A. Auth + OAuth device-grant

The 2026-05-08 architecture refactor (commit c9b0ccd) replaced the in-memory invite-session Set with a stateless signed JWT, and the RFC 8628 optimal pair --device-grant flow (commit e1ef78d) provides token-free pairing. Tests in tests/auth/ cover invite, jwt, oauth-device-grant, pair-flow, unlock-flow, logout-flow, and revocation.

1. Cold sign-in. Clear cookies + localStorage. Sign in with the invite password. Confirm localStorage.optimal_token is ~268 chars (JWT shape, three dot-separated segments) and not a 36-char UUID.
2. Restart survives session. When the Hetzner cloud restarts (e.g. after a deploy), you stay signed in. Pre-fix this kicked everyone to login because the in-memory Set was wiped.
3. Logout clears both keys. DevTools → Application → Local Storage. Click logout. Both optimal_token and fabric_token should be removed.
4. OAuth device-grant pair. Visit /oauth/device in browser. From a terminal: optimal pair --device-grant. Copy the printed user_code into the cockpit, click Approve. CLI should pair within ~5 seconds.
5. Stale fabric_token degrades gracefully. Manually delete fabric_token from localStorage. Reload. Sessions tab should not loop into /vault/unlock; should either show an inline error or work via the legacy fallback.

B. TOPO + Orbital Observatory

The starmap home tab now shows orbital observability, planet gen, ship glyphs, and signal pairing between devices. Test in tests/client/observatory.test.ts and tests/client/*orbital*, *planet*, *ship*, *pairing*.

6. Click each planet. Drill-down panels should render with planet layout/geometry.
7. Orbital observability. Orbiting device markers and net lines should appear. The pairing panel (between paired devices) should show status.
8. Ship animation. While viewing the starmap or running sessions, ship glyphs should render between source and target devices.
9. Signals panel. The signals net/geometry panel should show active connections and link status.

C. Sessions tab

The dispatch UI for one-shot harness sessions across paired devices (tests in tests/client/sessions-merge.test.ts and tests/client/launcher.test.ts).

10. Dispatch claude-code on the Pi. Pick Raspberry Pi 5 (oracle) · claude-code,bun,docker,tmux. Harness: claude-code. Prompt: list files in cwd. Cmd/Ctrl+Enter. Should run via the Pi's OAuth credentials and stream output back. Per-device OAuth (commit 5546502) is the contract.
11. Hetzner claude (expected fail until OAuth). Pick Hetzner CCX13. Same prompt. Should fail with claude not authenticated — operator-side fix is ssh root@178.156.203.234, then claude auth login interactively.
12. Terminal lock-in (T). While a session runs, press T. Modal pops up with live stream replay (Phase 14-3 + 14-3.5).
13. Cancel a running session. Cancel button. The daemon-side process should actually die — verify with journalctl --user -u optimalos-agent -f on the Pi.

D. Feed relay

Live relay for threads with markdown, speech synthesis, voice recording, and avatar rendering (tests in tests/client/feed-*).

14. Thread view rendering. Open any feed thread. Markdown should parse without HTML injection.
15. Speech synthesis. Click the speaker icon on any message. Audio should play in the browser.
16. Voice recording. Click the mic icon. Record a test message. It should send as a voice note and play back.
17. Live updates. Open two browsers. Post from one. The other should show new messages without refresh.
18. Avatar rendering. User avatars should render from avatars.ts without broken images.

E. Office (characters, creatures, demon-rigs)

The office tab hosts character sprites, creatures, and demon-rig scenes (tests in tests/client/office*).

19. Characters/creatures render. Open the office tab. Character and creature sprites should appear without layout breakage.
20. Sheet/table display. The sheet/table UI should show data rows without console errors.

F. Spine and Jev models

Spine and Jev model support for skill usage (tests in tests/client/spine-model.test.ts and tests/client/jev-model.test.ts).

21. Spine model load. From the skill panel, select a Spine-based harness. The model should initialize.
22. Jev model load. From the skill panel, select a Jev-based harness. The model should initialize.

G. Vault

The age-encrypted credential store (tests are limited; check /vault/dashboard and /vault/recover manually).

23. Add entry. /vault/dashboard → Add Entry. Drop a secret. Watch the rewrap progress fan out to all recipients.
24. Recovery chip-grid. /vault/recover. Tab-paste a 24-word phrase. One word should distribute per chip across all cells.

H. Mobile

All of A–G on iPhone Safari (when you have a phone in hand).

• Vault setup ceremony — chip-grid recovery.
• /pair mobile — tap-select on the JWT codeblock instead of textarea.
• TOPO mobile — vertical card stack instead of starmap.
• Sessions tab mobile — output pane uses momentum scroll + overflow-wrap.