Optimal

Appearance

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 (optimal.miami on the Pi) is out of scope here — its cockpit is intentionally minimal. See Deployment modes for the split.

A. Auth + redirect resilience ​

The 2026-05-08 architecture refactor (commit c9b0ccd) replaced the in-memory invite-session Set with a stateless signed JWT, made vault unlock persist a 12h Fabric browser JWT to localStorage.fabric_token, and removed the redirect loops that bounced users into /vault/unlock indefinitely. These tests validate that work.

  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. Vault unlock persists Fabric JWT. Visit /vault/unlock, walk through. Confirm fabric_token appears in localStorage. Visit the Sessions tab — should not bounce.
  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 + MOTHER ​

The starmap home tab + the local-LLM bridge to pop-os RTX 3060.

  1. Click each planet. Currently no-op. Flag if you'd want a drill-down panel.
  2. MOTHER chat round-trip. Click MOTHER bubble. Type "what's the capital of france". Tokens should stream from pop-os via Ollama. ~1s first-token, fast on the 3060.
  3. Model switch. Chat header has a model picker (qwen2.5-coder:7b, gemma2:9b, qwen2.5-coder:14b, etc). Switch mid-session — does the new model load? Switch back?
  4. ESC + Send-while-streaming. Does ESC close the chat cleanly? Hit Send while a stream is in flight — does it queue, block, or break?
  5. Ship animation. While a MOTHER stream runs, look at the starmap. The ship glyph should appear between MOTHER and pop-os. If absent, that's a polish miss to flag.

C. Sessions tab ​

The dispatch UI for one-shot harness sessions across paired devices.

  1. 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.
  2. 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.
  3. Terminal lock-in (T). While a session runs, press T. Modal pops up with live stream replay (Phase 14-3 + 14-3.5).
  4. 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. Vault ​

The age-encrypted credential store. 8 recipients enrolled, 0 entries yet.

  1. Add the first real entry. /vault/dashboard → Add Entry. Drop something like OPENAI_API_KEY. Watch the rewrap progress fan out to all 8 recipients (Pi, Hetzner, pop-os device + 3 browser + 3 recovery).
  2. Revoke flow with last-of-kind guard (Phase 13b-1, commit cbd6bbd). On a recipient row, click Revoke. Confirmation modal should be kind-aware (device vs browser vs recovery). Try revoking the last browser recipient — server-side 409 should fire and the client-side button should be hidden.
  3. Recovery chip-grid paste. /vault/recover (don't walk it; that re-keys the vault). Confirm: tab-paste of a 24-word phrase distributes one word per chip across all cells.

E. OAuth device-grant ​

Phase 13a-1, commit e1ef78d. The RFC 8628 alternative to legacy token-paste pairing. Both paths still work; this validates the new one.

  1. Approve a 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.

F. Mobile ​

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

  • Vault setup ceremony — chip-grid recovery (commit 2b7598c from the mobile/vault-pair branch).
  • /pair mobile — tap-select on the JWT codeblock instead of textarea.
  • TOPO mobile — vertical card stack instead of starmap (mother bubble visible at top).
  • Sessions tab mobile — output pane uses momentum scroll + overflow-wrap.

Built by Carlos Lenis in Miami