Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
Handover — MSO state as of 2026-10-31
For whoever picks this up next, human or agent. Read this first, then
docs/MSO-MIGRATION.md's header for the phase table.
Where the repo is
main = 3bf32e81 (PR #194 merged)
working tree clean
Everything described here is merged and pushed. Nothing is mid-flight.
What was asked, and what came out of it
The request was "migrate MSO from Next.js to Svelte, Bun and Rust, then keep going". The honest outcome after ~45 hours of work across two sessions is that the migration was measured and mostly argued away, while the parts that did ship are worth more than the migration would have been.
| Phase | State | Why |
|---|---|---|
| 0 Instrumentation | shipped | five perf scripts, gate running in CI |
| 1 Bun tooling | shipped | bun install builds node-pty via a committed patch |
| 2 Portable core | shipped | 117/117 route handlers ≤ 15 LOC, lib/ free of static next/* |
| 3 Svelte island | cancelled | a hello-world island costs 15.75 KiB gzip; React is already resident |
| 4 Slice-by-slice | cancelled | a hybrid adds a ~17.7 KiB second runtime beside React, net +11.7 KiB |
| 5 Shell swap | not started | the only remaining work, and the only place the byte win can arrive |
| 6 Rust sidecar | no-go | proxy costs 15 µs/request; a sidecar adds 200–500 µs of loopback hop |
Numbers that decide things
Measured, on an idle host, reproducible with the commands in docs/BENCH-BEFORE.md.
bundle initial 270.8 KiB gzip, of which framework floor 129.6 KiB (47.9%)
first-load JS 910.2 KiB browser-measured
LCP (Slow 4G, 4x CPU) 3.15 s desktop / 2.96 s mobile
TBT 173 ms desktop / 101 ms mobile (target was 150 ms)
hydration chain last JS 2.80 s -> mount 2.52 s -> icons 3.08 s -> LCP 3.13 s
LCP is hydration-bound, not paint-bound: the shell mounts only after ~910 KiB of JS arrives. That is why Phase 5 is the only lever left.
The SvelteKit floor was measured independently at 33.07 KiB gzip (real build, browser-
verified), so a full swap is 132.7 out, 33.07 in = −99.6 KiB. That number is the entire case
for Phase 5, and it only applies to a full swap, never to a hybrid.
Code facts worth knowing before you touch anything
- 117 route handlers, all ≤ 15 LOC, all tested. Coverage went 59/117 → 117/117 this session.
lib/has zero staticnext/*imports. One documented dynamicimport("next/headers")remains inlib/auth/require-session.ts—cookies()is request-scoped and has no web-standard equivalent in place. Moving it out is 54 mechanical edits, deliberately not done.- Auth is not uniform, and that is deliberate:
verifyAuthreturning 401 vsrequireSession/requireOwnerreturning 403 with a different key.app/api/status-contract.test.tspins the twenty routes where getting this wrong is an RCE, a write, a secret read or a role escalation. app/api/skillsreturns 409ambiguouswhen a bare skill name matches several projects. Do not "fix" it to 404 — returning one project's instructions under another's name is the bug that branch exists to prevent..well-known/*routes are public by design. Their tests assert they stay public. Adding a session gate there breaks every MCP client.
The gate, and how to run it
bash scripts/gates-12.sh # fast, ~2 min, deterministic checks
bash scripts/gates-12.sh full # ~20 min, what CI runs: coverage + build + perf
fast prints why each skipped step was skipped; full reports 17 passed / 0 failed / 0 skipped.
CI runs the same set on GitHub. A Turbopack build warning fails the release gate — if you add
an fs.* call whose path is a variable or env var, it needs /* turbopackIgnore: true */ or the
whole project gets traced.
The perf gate compares TBT only on the same core count and at low load. It has been wrong once: it compared a 16-core workstation baseline against a 4-core GitHub runner and blocked a PR for a property of the runner.
Traps that cost real time this session
scripts/verify-build.sharchives HEAD, not the working tree. A fix must be committed before the gate can see it. Two build cycles were lost to this.docs/CHANGELOG.mdis generated and always conflicts..gitattributesnow marks itmerge=ours, but that is inert untilgit config merge.ours.driver true.mainmoves often (TUI work is active on another track). Three rebases were needed on one PR.ghCLI is not authenticated on this box and SSHid_ed25519_rahmanef63is rejected by GitHub. Pushing works over HTTPS with the PAT stored in~/.mso/private/infra-providers.jsonunderusers/rahman/connections/github/gh-rahmanef63. Do not paste that token into chat./tmpis a 9.8 GB tmpfs shared by parallel agents; it filled mid-build once and failed a verification withNo space left on device, which looks like a code failure and is not.
If you are picking this up
Do not start Phase 5 without deciding it is worth 8–12 months. The measured upside is
−99.6 KiB gzip and LCP 3.15 → ~2.5 s. The measured downside is re-expressing 20,028 LOC of
appshell and 54,181 LOC of slices, with two confirmed hard spots: the window store's
synchronous useSyncExternalStore open path, and the per-surface chunk split that Vite can
silently undo by hoisting shared dependencies into the entry chunk.
Cheaper work that still has real value, in order:
- LCP. It is 3.15 s and set by first paint of the mounted shell. Cheapest untried lever:
take the wallpaper artwork off the critical path — it is already an
IMGLCP element on mobile. - Coverage of
lib/is 42.6 % functions. Route coverage is now complete;lib/hostandlib/managed-appsare where the untested logic lives, and both touch the filesystem and process control. bun testparity.scripts/*run under Bun, the vitest suite does not (it fails onvi.mock, jsdom, localStorage assumptions). Bun's runner has no coverage thresholds, so this would be a second way to run tests, not a replacement — decide whether that is worth it.
Documents, in reading order
docs/MSO-MIGRATION.md— the plan, its phase table, and every retraction this work produced. §4.0 is the corrected Phase 4 reasoning. It is authoritative overBENCH-AFTER.md.docs/BENCH-BEFORE.md/docs/BENCH-AFTER.md— the measured comparison, including the deltas that are zero and the ones inside the noise band.docs/PROGRESS.md— dated entries, newest first, with the evidence for each.docs/DEVELOPMENT.md— the gate commands and what each one enforces.