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 TUI panel track, 2026-10-31
Written because the session was paused mid-step. Read this first, then
docs/TUI-RENDERER-PLAN.md section 8 and 8.1 for the full reasoning.
Where the work stands
The retained renderer is complete and merged. Every milestone M0 to M8a is on main:
| PR | What |
|---|---|
| #185 | docs/TUI-RENDERER-PLAN.md, the plan |
| #186 | scripts/tui/cells.mjs, shared cell primitives (M1) |
| #187 | scripts/mso-agent-transcript.mjs, transcript model (M2) |
| #189 | scripts/mso-agent-screen.mjs, frame writer (M3) |
| #191 | scripts/mso-agent-chrome.mjs, tab row plus footer (M4) |
| #192 | scripts/mso-agent-altscreen.mjs, alternate screen behind --altscreen (M5) |
| #193 | scripts/mso-agent-viewport.mjs plus -render.mjs, viewport and scrollbar (M6) |
| #197 | scripts/mso-agent-mouse.mjs, wheel plus tab click (M7) |
| #198 | scripts/mso-agent-pane.mjs, right-hand side pane (M8a) |
| #199 | plan section 8.1, the blocker list |
| #195, #196 | Semgrep required check fixed (it was red on main with 0 findings) |
| #201 | the real-pty test, and the two bugs it found |
| #202 | scripts/mso-agent-print.mjs, print router for 12 command modules |
| #203 | composer reports its row count, panel reserves that |
| #204 | scripts/mso-agent-turn-print.mjs, mid-turn writes plus withPanelSuspended |
| #205 | scripts/mso-agent-panel-suspend.mjs, suspension really leaves the alternate screen |
| #206 | installs session.printSink (it was never installed before), migrates 3 more modules |
main is at 9e0a82a4 unless someone pushed after this was written.
The one open item, in progress
Branch feat/tui-default-panel in ~/.cache/mso-worktrees/mso-flip, one stash deep.
Goal: flip the alternate screen default on, so the panel is what a user gets, with inline mode kept
for --oneshot, non-TTY and CI.
State: I was routing AgentActivity through turnPrinter so its live spinner row does not draw at
the cursor inside the panel. The change is correct but 4 lines too big: scripts/mso-agent-turn.mjs
went 219 to 223 and the filesOver220 ratchet (43) fails.
cd ~/.cache/mso-worktrees/mso-flip
git stash list # stash@{0}: WIP: route AgentActivity through turnPrinter
git stash pop
The change, for reference, is inside agentRound in scripts/mso-agent-turn.mjs:
const panelActive = Boolean(session?.streamSink);
const activity = options.quiet ? null : (options.activity || new AgentActivity({
output: options.output || process.stdout,
colors: C, now: options.now,
animate: panelActive ? false : options.animate,
print: turnPrinter(session),
})).begin();
To land it, free four lines in that file first. The obvious candidates, in order of safety:
renderInteractionFailurestill defaultsprint = console.log; every real caller passes one. Dropping the default and the parameter saves a line and removes a way to reintroduce the bug.agentRoundLimit()is a three line function that can be one expression.- The
workSectionPrinteddance near the top of the loop can lose a blank line.
What must be true before the default flips
The pty test scripts/mso-agent-pty.e2e.test.ts is the gate that matters. It passed against main at
9e0a82a4 (7 tests). Run it after any change to the entrypoint:
cd ~/.cache/mso-worktrees/mso-flip
npx vitest run scripts/mso-agent-pty.e2e.test.ts
It asserts the painted frame at 100x30 (tab row once, footer once, banner present, enter sequence emitted), a slash command that needs no model, a SIGWINCH resize to 120x35 without duplicated rows, Ctrl+C exiting 0 and emitting the leave sequence, and SIGTERM exiting at all.
Then walk these, because each one is a place a line can land outside the frame:
scripts/mso-agent-ui.mjsstill has 10console.logcalls (banner, panels). It runs once at startup, before the panel is mounted, so it is fine today. Decide explicitly whether that stays true after a flip; if the banner is printed after the panel opens it will be overwritten.scripts/mso-agent-local-commands.mjshas 3 andscripts/mso-agent-approval-ui.mjshas 2, both reached mid-turn. Approval is already suspended, so its prints are safe; local commands are not wrapped yet.scripts/mso-agent-activity.mjsdefaultsprinttoconsole.logand sits at exactly 219 lines. It takes an injectable print, which is the route to take rather than editing it.renderInteractionFailurestill defaults toconsole.log. See item 1 above.
Two defects worth remembering
Both were invisible to unit tests and both came from the pty test:
const screenLoopwas declared insidetryand read infinally, so every exit threw a ReferenceError and exit code became 1.- Attaching a SIGTERM listener replaces node's default termination, so the handler released the screen and then left the process alive forever. Re-raising does not work either, because the screen loop's own SIGTERM handler catches the re-raise. The fix exits explicitly on the next tick with 128 + signal.
And two wiring holes, same class: session.printSink was never installed (#206), and onRows was
never connected (#203). Both made a correct-looking change inert. When adding a callback or a sink,
assert that something installs it, not only that it works once installed.
Housekeeping
- Three required checks are red on
mainfor reasons unrelated to this track:Gitleaks history(a commit no longer in any ref),OSV dependency scan(minimatch3.1.5 / 10.2.6 inbun.lock, needs a major bump to 11.0.1), and until #195/#196Semgrep OWASP/SAST. Merges were done with the admin bypass after printing exactly which checks were red, never silently. ~/.cache/mso-worktrees/mso-{flip,lastprint,suspend,rows,printsink,turnwrites,pane,plan,mouse,viewport,altscreen,screen,chrome}are this track's worktrees. All butmso-flipare merged and can be removed.msodeploy is not needed for TUI changes; only web and app changes need it.- Regenerate the changelog after any doc edit:
node scripts/gen-changelog.mjs, thengit commit --amend --no-edit, because thechangeloggate compares against HEAD.