Skip to content

armgit / mso

Public Imported from GitHub
0

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.

6.1 KB
Raw Blame

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:

  1. renderInteractionFailure still defaults print = console.log; every real caller passes one. Dropping the default and the parameter saves a line and removes a way to reintroduce the bug.
  2. agentRoundLimit() is a three line function that can be one expression.
  3. The workSectionPrinted dance 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.mjs still has 10 console.log calls (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.mjs has 3 and scripts/mso-agent-approval-ui.mjs has 2, both reached mid-turn. Approval is already suspended, so its prints are safe; local commands are not wrapped yet.
  • scripts/mso-agent-activity.mjs defaults print to console.log and sits at exactly 219 lines. It takes an injectable print, which is the route to take rather than editing it.
  • renderInteractionFailure still defaults to console.log. See item 1 above.

Two defects worth remembering

Both were invisible to unit tests and both came from the pty test:

  • const screenLoop was declared inside try and read in finally, 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 main for reasons unrelated to this track: Gitleaks history (a commit no longer in any ref), OSV dependency scan (minimatch 3.1.5 / 10.2.6 in bun.lock, needs a major bump to 11.0.1), and until #195/#196 Semgrep 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 but mso-flip are merged and can be removed.
  • mso deploy 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, then git commit --amend --no-edit, because the changelog gate compares against HEAD.