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.
TUI retained-renderer plan
Research only. No product code was changed to produce this document. Worktree
research/tui-renderer, branch of the same name.
Scope: can mso agent (launched from scripts/mso-cli-agent.sh, implemented in
scripts/mso-agent-*.mjs) become a retained-mode renderer with panels, session
tabs, mouse support, a scrollbar and split panes, without breaking the repository
gates? The reference UI is opencode (OpenTUI + Solid). A dependency is not
automatically allowed, so the dependency question is answered against the gates
rather than against taste.
Related documents already in the tree: TUI-PARITY-PLAN.md (per-command parity status, Phase 2 items P2-1..P2-3), ARCHITECTURE.md, DEVELOPMENT.md (dependency update policy), PLATFORMS.md (macOS/Windows/Android run inside a Linux guest), WORKSPACE-GUIDE.md (the documented key map).
0. Method and evidence rules
Measured from source, not from screenshots:
- read every
scripts/mso-agent-*.mjsthat writes to the terminal, plusscripts/mso-agent.mjs,scripts/mso-cli-agent.sh,scripts/mso-tui-select.mjsand the other in-repo TUI (scripts/integrations-tui/*,scripts/mso-cli-integrations-tui.sh); - ran
node scripts/check-architecture.mjs(read only); - ran
eslintwith a probemax-linesrule on the largest agent modules to get the exact code-line counts the lint gate uses; - read the gate definitions (
scripts/gates-12.sh,scripts/gates.sh,.github/workflows/ci.yml,.github/workflows/dependency-review.yml); - did not run the full gate suite, did not deploy, did not touch the live service on :4005.
Package facts (licence, engines, size, dependency lists) come from npm registry metadata fetched while writing this. Anything about how a candidate library behaves inside this repository is marked unverified.
1. What the TUI is today
1.1 Shape of the program
mso agent is a line-oriented, append-only program with no retained frame.
| Property | Today | Evidence |
|---|---|---|
| Render model | append-only writes; no frame buffer, no cell grid, no previous-frame diff | 100 console.log sites and 7 process.stdout.write sites across 15 modules (section 1.2); no module holds rendered lines |
| Alternate screen | never entered by the agent | grep for [?1049 finds only the Integrations wrapper, scripts/mso-cli-integrations-tui.sh:12-13 |
| Mouse | never enabled | no [?100x sequence anywhere under scripts/ |
| Bracketed paste | never enabled | no [?2004 sequence anywhere under scripts/ |
| Scrollbar | none | no viewport model over a transcript; the only scrolling primitive is windowFor in scripts/integrations-tui/layout.mjs:60-66, used by the Integrations column browser |
| Split panes | none in the agent | paneWidths/border/paneRow exist only in scripts/integrations-tui/layout.mjs:35-51 |
| Resize handling | composer only | output.on("resize", onResize) at scripts/mso-agent-composer.mjs:204, handler at :127; banner and already-printed sections never reflow |
| TTY requirement | hard requirement for interactive mode | scripts/mso-agent.mjs:60-62 exits 2 when stdin or stdout is not a TTY |
| Process handoff | launcher execs node, so node owns the terminal |
scripts/mso-cli-agent.sh:397-399 |
The last row matters for every option: because the shell replaces itself with
exec, a bash trap cannot restore the terminal after node exits. The Integrations
TUI can use trap 'integration_alt_off' EXIT INT TERM
(scripts/mso-cli-integrations-tui.sh:39) only because its wrapper stays alive and
re-runs a node child per keystroke (:42, :50). The agent TUI cannot copy that
without dropping exec, or without doing teardown inside node.
1.2 Where it writes, and how
Seven distinct mechanisms, in order of how much they constrain a rewrite:
console.log(implicit\n, stdout): 100 call sites.console.error: 8 call sites (stderr:scripts/mso-agent-cmd-parity.mjs:49,58,scripts/mso-agent-cmd-session.mjs:74,90,scripts/mso-agent-commands.mjs:27,scripts/mso-agent-mentions.mjs:112,scripts/mso-agent.mjs:61,203).- Bare
process.stdout.write: 7 call sites. Streamed model text goes straight to stdout (scripts/mso-agent-turn.mjs:30, called from:138), including the trailing newline (scripts/mso-agent-runtime.mjs:165) and each SSE delta (:150). One-shot output usesprocess.stdout.writetoo (scripts/mso-agent.mjs:50-51,57). - Raw ANSI constants: erase-to-end-of-line
\x1b[2K(scripts/mso-agent-activity.mjs:17), and the composer's cursor kit\x1b[2K,\x1b[nA,\x1b[nB,\x1b[nC,\x1b[2J\x1b[H(scripts/mso-agent-composer-ui.mjs:3-7). - The
\rplus clear live-row trick: one row repainted in place for the whole turn (scripts/mso-agent-activity.mjs:196,:164), driven by a 120 ms ticker (:16,:203-211). - Reserved-row allocation and erase:
reserveComposerRowswrites"\r\n"to physically claim rows, then moves the cursor back up (scripts/mso-agent-composer-ui.mjs:13-19);eraseComposerRowsclears them (:21-25). - Full-screen clear on Ctrl+L:
CLEAR_SCREENatscripts/mso-agent-composer.mjs:135. - Terminal geometry reads: 20 call sites in 11 modules.
scripts/mso-agent-layout.mjs:17,scripts/mso-agent-ui.mjs:88,scripts/mso-agent-diff.mjs:7,146-147,scripts/mso-agent-files.mjs:148-149,scripts/mso-agent-todos.mjs:106,scripts/mso-agent-composer.mjs:44,47,49,171,scripts/mso-agent-local-commands.mjs:58,75,scripts/mso-agent-mentions.mjs:108,113,scripts/mso-agent-local.mjs:219,scripts/mso-agent.mjs:147-148.
Sections are printed, never stored: one Assistant divider per streamed answer
(scripts/mso-agent-turn.mjs:20-33, :138), one Agent work divider per turn
(:160-163), Local agent blocks through sectionBlock
(scripts/mso-agent-local.mjs:218-220), Error sections in
renderInteractionFailure (scripts/mso-agent-turn.mjs:189-194).
1.3 Files that write, ranked by size
"Physical" is split("\n").length, the ruler check-architecture uses
(scripts/check-architecture.mjs:20-22). "Code" is the count the max-lines lint
rule sees with skipBlankLines and skipComments (measured with a probe run).
| Module | Physical | Code | Write sites | Direct writes |
|---|---|---|---|---|
mso-agent-activity.mjs |
220 | 156 | 1 | output.write only, :164,196 |
mso-agent-turn.mjs |
217 | 203 | 8 | stdout stream + sections |
mso-agent.mjs |
204 | 183 | 8 | one-shot, exit line, unknown command |
mso-agent-ui.mjs |
194 | 180 | 10 | the banner, :145-192 |
mso-agent-cmd-parity.mjs |
167 | 161 | 27 | command chatter |
mso-agent-skills.mjs |
154 | 131 | 7 | skill list |
mso-agent-status.mjs |
152 | 136 | 16 | /status |
mso-agent-commands.mjs |
123 | 104 | 3 | skill queued, runCli error |
mso-agent-session-ui.mjs |
119 | 105 | 3 | new/resumed lines |
mso-agent-mentions.mjs |
118 | 110 | 2 | local-agent section |
mso-agent-cmd-session.mjs |
113 | 110 | 12 | /todo, /rename, /compact |
mso-agent-local-commands.mjs |
111 | 105 | 11 | /agents, /inbox |
mso-agent-cmd-inspect.mjs |
98 | 96 | 5 | /permission, /tools |
mso-agent-help.mjs |
59 | 56 | 1 | /help |
mso-agent-subagent.mjs |
40 | 36 | 1 | /spawn |
Two more modules write indirectly and are easy to miss:
scripts/mso-agent-diff.mjs:84-100 returns a string that callers print, and
scripts/mso-agent-edit-diff.mjs:116-127 / scripts/mso-agent-todos.mjs:179-190
print through an injectable print sink. scripts/mso-agent-local.mjs never calls
console.log; it pushes text through composer.notify (:218), which is the one
existing "write above the draft" seam (scripts/mso-agent-composer.mjs:93-106).
Total: 15 modules write directly, 115 direct call sites (100 console.log,
8 console.error, 7 process.stdout.write).
1.4 Input handling
One keypress machinery is reused everywhere:
readline.emitKeypressEvents(input)inscripts/mso-agent-composer.mjs:20andscripts/mso-tui-select.mjs:114. The agent never usesreadline.createInterface, and never usesreadline.question;AgentComposer.questionis a hand-written promise (scripts/mso-agent-composer.mjs:23-211) that installs its own listener (:203) and resolves on submit, cancel or EOF.rl.questioncall sites that go through that hand-written prompt:scripts/mso-agent-session-ui.mjs:87(session picker),scripts/mso-agent-approval-ui.mjs:60,68(approval),scripts/mso-agent-cmd-inspect.mjs:30(picker).- Raw mode is entered in three places:
scripts/mso-agent-composer.mjs:206,scripts/mso-tui-select.mjs:176,scripts/integrations-tui/app.mjs(the finder'srun,input.setRawMode(true)).
Every hardcoded key, so the remaining work is countable. Line numbers in this table
are scripts/mso-agent-composer.mjs unless a module is named:
| Key | Action | Line |
|---|---|---|
| Ctrl+C | clear non-empty draft, else cancel prompt | mso-agent-composer.mjs:130-133 |
| Ctrl+L | clear screen and repaint | :134-136 |
| Esc | dismiss completion, or cancel when escapeCancels |
:137-140 |
| Up / Down (completion open) | move selection | :141-144 |
| Tab (completion open) | apply completion, or submit when selectOnEnter |
:145-151 |
| Tab (empty draft) | onTab, permission cycle |
:152-156 |
| Enter / Return | submit, or apply exact match | :157-168 |
| Up / Down (wrapped draft) | move cursor across visual rows | :169-174 |
| Up / Ctrl+P | history back | :175 |
| Down / Ctrl+N | history forward | :176 |
| Ctrl+D | delete right, or EOF on empty | :178-182 |
| Ctrl+Left, Alt+Left, Alt+B | word left | :183 |
| Ctrl+Right, Alt+Right, Alt+F | word right | :184 |
| Left / Ctrl+B | char left | :185 |
| Right / Ctrl+F | char right | :186 |
| Home / Ctrl+A | line start | :187 |
| End / Ctrl+E | line end | :188 |
| Backspace | delete left | :189 |
| Delete | delete right | :190 |
| Ctrl+W | delete previous word | :191-194 |
| Ctrl+U | delete to start | :195 |
| Ctrl+K | delete to end | :196 |
| printable | insert | :197-200 |
| SIGINT | interrupt turn, second press exits within 2000 ms | scripts/mso-agent.mjs:123-131, scripts/mso-agent-interrupt.mjs:45-64 |
That is 23 semantic bindings (35 key combinations once alternates are counted separately). The permission selector is not
key-driven: approval is typed text, allow or deny
(scripts/mso-agent-approval-ui.mjs:68). The pickers add 10 more bindings
(scripts/mso-tui-select.mjs:159-172): Ctrl+C, Esc, Up, Down, Home, End,
Enter/Return, Backspace, Ctrl+U, printable filter.
Raw-mode restoration:
- Normal paths restore the previous state, not a hardcoded false:
wasRawis captured atscripts/mso-agent-composer.mjs:32and restored incleanup()at:68;finish/cancelcallcleanup(:71-92).AgentComposer.close()forces false (:230-234) and the main loop calls it infinally(scripts/mso-agent.mjs:188-195). - Error paths before raw mode is entered are safe (session bootstrap at
scripts/mso-agent.mjs:70-71precedes the firstquestion). - Error paths after raw mode is entered: the top-level catch (
:203) runs after thefinallyhas closed the composer, so raw is restored. - Gap: no
SIGHUP,SIGTERMorSIGQUIThandler exists. OnlySIGINTis registered (scripts/mso-agent.mjs:131). A terminated terminal or a killed process leaves raw mode on. - Gap:
scripts/mso-tui-select.mjsrestores raw mode incleanup(:142-147) but its top-level catch exits without calling it (:181-184), so a throw leaves the invoking shell in raw mode.
1.5 Scrollback: what an alternate screen would destroy
Nothing in the code reads the terminal scroll buffer (that is impossible from a program), so no code depends on it. The user experience does: the transcript exists only there.
Printed once and never re-rendered:
- the 12-row ASCII banner plus the panel body, up to about 20 more rows
(
scripts/mso-agent-ui.mjs:139-193; 10console.logcalls at:145-192); - every streamed assistant token (
scripts/mso-agent-turn.mjs:28-30); - section dividers and tool receipts (
scripts/mso-agent-turn.mjs:160-163,scripts/mso-agent-activity.mjs:119-150when not animating); - edit diffs and todo blocks (
scripts/mso-agent-edit-diff.mjs:116-127,scripts/mso-agent-todos.mjs:179-190); - error sections (
scripts/mso-agent-turn.mjs:189-194); - every slash-command result (section 1.3);
- the exit line with the resume hint (
scripts/mso-agent.mjs:191-192).
Critically, history is never replayed. --continue and /resume replace the
session object (scripts/mso-agent-session-ui.mjs:39-52,65-82) and print one
resumed ... N history rows line (:80), but no module iterates session.history
to re-render rows (grep for for (const ... of session.history and for a history
printer returns nothing). printAgentBanner receives agentSession but reads only
title and name (scripts/mso-agent-ui.mjs:155-157). So today the transcript is
literally the scrollback; after /resume the user sees the banner and a blank
screen.
Tests and docs treat "no scrollback growth on repaint" as a contract, which is the closest thing to a code dependency:
scripts/mso-agent-composer.test.ts:54,60,scripts/mso-agent-composer-session.test.ts:76assert redraw chunks contain no\n;scripts/mso-agent-activity.test.ts:48asserts the live frame contains no\n;- WORKSPACE-GUIDE.md:235 documents "Tab ... cycles that footer in place without adding scrollback";
docs/PROGRESS.md:2649,2713,2744record three separate ships whose acceptance criterion was zero added scrollback rows. The live PTY regression those entries mention is not present in the tree now (onlyscripts/mso-integrations-finder-pty.test.tsuses a real PTY), so that claim is unverified here.
1.6 Retained state that already exists
The program does hold state; it just never renders from it.
| State | Where | Rendered? |
|---|---|---|
session object (history, usage, permission, queue) |
scripts/mso-agent.mjs:73-83 |
no, only derived strings |
| composer draft, cursor, history (max 100) | scripts/mso-agent-composer.mjs:16-18,77-80 |
yes, one row block |
| live activity row | scripts/mso-agent-activity.mjs:22,87-94 |
yes, one row |
| cached todos | scripts/mso-agent-todos.mjs:6,82-94 |
only as a status chip |
| local-agent bridge state | scripts/mso-agent-local.mjs:84-97 |
no |
2. Dependency policy: is a TUI library allowed?
Plain answer: no gate forbids adding a dependency, and no gate would catch a broken
one. The nearest thing to a policy is
DEVELOPMENT.md:169-180 (dependency updates must pass Verify,
security scans alone are not enough) and docs/DEVELOPMENT.md:234 (a dependency
with an install script must be added to trustedDependencies, precedent:
package.json:107-109).
Gate by gate, for a TUI dependency:
Gate (scripts/gates-12.sh) |
Definition | Effect on a TUI dependency |
|---|---|---|
typecheck |
tsc --noEmit, scripts/gates-12.sh:33; tsconfig.json includes only **/*.ts and **/*.tsx |
none: .mjs is never typechecked |
lint |
eslint . --max-warnings=0, :34; max-lines warn at 220 code lines, eslint.config.mjs:32-35 |
applies to every new module; a warning is fatal |
installer syntax |
bash -n scripts/install.sh && bash -n scripts/install-core.sh, :35 |
none unless the installer is edited |
native dependency |
node -e "require('node-pty')", :36 |
none: hardcoded to node-pty, it does not test a new addon. A broken new native addon installs and fails at runtime |
cycles |
scripts/check-cycles.mjs, :37, scans frontend and lib only, .ts/.tsx |
none: scripts/ is not in the cycle graph |
architecture |
:38, see section 3 |
applies to new files and their physical length |
docs |
:39, scripts/check-docs.mjs |
applies to this document (section 8, M0): every top-level docs/*.md must be classified in docs/README.md (scripts/check-docs.mjs:56-63) |
changelog |
node scripts/gen-changelog.mjs --check, :40 |
every commit must regenerate docs/CHANGELOG.md |
contrast |
:41, scripts/check-contrast.mjs |
none: it reads app/globals.css and the preset registry only (scripts/check-contrast.mjs:2-18); the terminal palette in scripts/mso-agent-theme.mjs:12-28 is not contrast-checked |
bundle budget |
:42, scripts/check-bundle.mjs -> scripts/lib/bundle-report.mjs:17-24 |
none: it measures only .next client chunks for /[[...slug]]/page; nothing under scripts/ is measured |
instance guard, audit strict, ci contract |
:43-45 |
audit applies: audit.mjs --strict fails closed on high/critical |
tests / tests + coverage |
:51 / :53 |
applies; coverage thresholds are only in full |
Outside the local runner:
.github/workflows/ci.yml:38installs withbun install --frozen-lockfile, sobun.lockandpackage.jsonmust move together..github/workflows/ci.yml:65-71runsaudit:strict,bun audit --audit-level=highandnpm audit --prefix scripts/install/node-gyp..github/workflows/dependency-review.ymlfails a PR onhighseverity only.scripts/gates.sh:48runsbun run verifyon pre-push, which includes coverage, the full test suite, parity checks and an out-of-tree build.
So the honest statement is: a pure-JS TUI dependency would not fail a named gate by
itself. It would add install and supply-chain surface that no gate in this repo
tests, and it would still have to be split into <= 220-line modules to satisfy
architecture.
Candidate check (registry metadata, fetched while writing):
| Candidate | Licence | Engines | Size | Dependencies | Fit |
|---|---|---|---|---|---|
@opentui/core 0.8.0 |
MIT | node >= 26.4.0, bun >= 1.3.14 |
18,054,741 B unpacked | 4 runtime deps plus 8 platform native packages (@opentui/core-linux-x64 5,238,581 B, and 7 siblings) |
blocked: package.json:6-9 supports Node `^22.12.0 |
ink 8.0.0 |
MIT | node >= 22 |
619,872 B unpacked | 23 runtime deps, including yoga-layout ~3.2.1 (WASM), patch-console, react-reconciler; peer react >= 19.3.0 (repo has 19.3.1, package.json:97) |
installable; the real cost is architectural, not licence (section 6, Option B) |
blessed 0.1.81 |
MIT | node >= 0.8.0 |
small | none declared | not viable: last published with an npm 2 era toolchain, no maintenance signal, no TypeScript or modern terminal story |
Licence itself is not an obstacle for either MIT candidate: the repository is
PolyForm Noncommercial (LICENSE:1) and no licence policy exists in scripts/audit.mjs
(a grep for license returns nothing). That is a repository observation, not legal
advice.
3. Ratchet and gate exposure
node scripts/check-architecture.mjs on this worktree:
filesOver220 43 / max 43 PASS
filesOver500 0 / max 0 PASS
cliEntrypointLines 212 / max 220 PASS
installerCoreLines 450 / max 450 PASS
Consequences, in order of how much they constrain the design:
filesOver220is full.architecture.boundaries.json:6sets the ceiling and the policy note says ratchets may only stay equal or decrease. Adding one module with more than 220 physical lines fails thearchitecturegate immediately.- The scan includes
scripts/**with.mjs,.js,.sh,.ts,.tsx(scripts/check-architecture.mjs:18). It counts physical lines (:20-22), so comments and blank lines count.eslintcounts differently (skipBlankLines: true, skipComments: true,eslint.config.mjs:35). Two rulers, both fatal. bin/msois at 212 against a 220 ceiling (check-architecture.mjs:47,architecture.boundaries.json:16), andscripts/install-core.shis at 450 of- Neither can grow.
Per-module headroom for the files a renderer change would touch:
| Module | Physical | Physical headroom to 220 | Code (lint) | Code headroom |
|---|---|---|---|---|
mso-agent-activity.mjs |
220 | 0 | 156 | 64 |
mso-agent-composer.mjs |
236 | already over (counted) | 219 | 1 |
mso-agent-local.mjs |
243 | already over (counted) | 220 | 0 |
mso-agent-turn.mjs |
217 | 3 | 203 | 17 |
mso-agent.mjs |
204 | 16 | 183 | 37 |
mso-agent-ui.mjs |
194 | 26 | 180 | 40 |
mso-agent-todos.mjs |
191 | 29 | 135 | 85 |
mso-agent-diff.mjs |
156 | 64 | 142 | 78 |
mso-agent-status.mjs |
152 | 68 | 136 | 84 |
mso-agent-composer-ui.mjs |
114 | 106 | 105 | 115 |
mso-agent-layout.mjs |
65 | 155 | 55 | 165 |
Read that table as a hard plan input:
mso-agent-activity.mjscannot gain a single line, not even a comment, without failingarchitecture. Any new activity behaviour must first remove lines from it.mso-agent-composer.mjshas exactly one code line of lint headroom; a rewrite that adds code there must also move code out of it.mso-agent-local.mjshas zero lint headroom and is already counted, so it may neither gain code nor needs to lose physical lines.- New modules are fine as long as each stays at or under 220 physical lines, and the natural renderer is bigger than that. Splitting is mandatory, not stylistic.
Gate runner modes:
scripts/gates-12.sh fastruns 14 checks: 13 deterministic (:33-45) plusvitest run(:53), with coverage explicitly skipped (:55).scripts/gates-12.sh fullruns 17: the same 14 withbun run coverage(:51), plus forge sandbox (:60), out-of-tree production build (:62), perf gate (:63)..github/workflows/ci.ymlverify job has 22 steps, adding a second Bun-native audit, an npm audit of the native build tool, and 5 browser/perf steps (ci.yml:84-96).scripts/gates.sh(pre-push) is separate and heavier:bun run verify(:48), then cycles, docs, changelog, contrast (:53-59), strict audit (:64), and an out-of-tree build with release journeys (:70).
4. Existing seams that help
| Seam | File:line | Survives a renderer change? |
|---|---|---|
fit, pad, width (ANSI-stripping) |
scripts/mso-agent-ui.mjs:73-85 |
partly: fit strips SGR (:73), so it cannot measure styled cells; usable for plain text only |
cellWidth, fitCells, stripAnsi, clean (wide-char aware) |
scripts/integrations-tui/layout.mjs:1-33 |
yes, and it is the correct primitive for a frame writer; currently private to the Integrations TUI |
paneWidths, border, paneRow, compose, windowFor |
scripts/integrations-tui/layout.mjs:35-66 |
yes: vertical splits, borders and scroll windows for free |
sectionDivider, sectionBlock, printSection |
scripts/mso-agent-layout.mjs:20-42 |
yes as pure string producers; their role shrinks to inline mode and to the transcript view |
composerPrompt, composerFooter, composerSeparator |
scripts/mso-agent-layout.mjs:44-64 |
yes, pure; feed the chrome/footer rows |
statusParts (one array of short status strings) |
scripts/mso-agent-status.mjs:62-88 |
yes, ideal for a fixed footer or tab metadata |
todoStatusChip |
scripts/mso-agent-todos.mjs:154-174 |
yes, plain string |
formatDiffBody, colorizeDiffLine, renderDiff |
scripts/mso-agent-diff.mjs:12-100 |
yes, all return strings; renderDiff returns a block, not a print |
formatEditDiff |
scripts/mso-agent-edit-diff.mjs:61-99 |
yes, pure string |
formatTodoBlock |
scripts/mso-agent-todos.mjs:101-149 |
yes, pure string, already column-aware (:106) |
inputLayout, inputViewport, verticalCursor, completionWindow, menuLines |
scripts/mso-agent-composer-ui.mjs:27-113 |
yes, pure; the only surviving part of the composer |
streamTurn(..., output) injectable sink |
scripts/mso-agent-runtime.mjs:73-80,150,165 |
yes, the single most valuable seam: streamed text can be redirected into a view with no API change |
print / printErr injection |
scripts/mso-agent-edit-diff.mjs:116, scripts/mso-agent-todos.mjs:179, scripts/mso-agent-diff.mjs:107-108, scripts/mso-agent-files.mjs:127-128 |
yes, these already accept a sink |
AgentActivity live row |
scripts/mso-agent-activity.mjs:66-219 |
no: inseparable from \r + \x1b[2K and a single row (:164,196). Its formatters (:34-52) survive |
AgentComposer write loop |
scripts/mso-agent-composer.mjs:39-62 |
no: cursor-relative writes and reserveComposerRows are replaced by a frame writer |
activity.clear() before a block print |
scripts/mso-agent-edit-diff.mjs:119-124, scripts/mso-agent-todos.mjs:182-187 |
no: in a frame model, blocks append to a buffer instead of being logged after clearing a row |
| banner | scripts/mso-agent-ui.mjs:139-193 |
pinned by scripts/mso-agent-contract.test.ts:8-30, which asserts the exact art, the six RGB triples, and identifiers such as AgentComposer, composerPrompt, sectionDivider, Agent work, Local agent |
5. The precedent already in the repo
scripts/integrations-tui/ is a dependency-free retained renderer that already
ships:
- a pure frame function
buildFrame(config, {cols, rows})returning an array of styled lines (scripts/integrations-tui/renderer.mjs:5), including a 3-column pane grid with borders (:6), an inspector pane (:8), section tabs (:3), and height-dependent inspector rows (:9); - a painter
paint(output, lines)that homes, clears, hides the cursor, and writes each line at an absolute row (renderer.mjs:14); - cell-accurate layout including CJK and emoji widths (
layout.mjs:6-33); - an alternate-screen wrapper with
trap ... EXIT INT TERM(scripts/mso-cli-integrations-tui.sh:12-13,39,50); - a real PTY test across 6 terminal sizes (
scripts/mso-integrations-finder-pty.test.ts:48).
What it is not, and what the agent needs: paint repaints the whole screen every
frame (renderer.mjs:14, \x1b[H\x1b[2J then every line), it never restores
content on exit, it hides the cursor without a matching show, and it has no dirty
region, no mouse, no scrollbar and no in-flight async work (the wrapper re-runs node
per keystroke, mso-cli-integrations-tui.sh:42). The agent has a 120 ms spinner
(scripts/mso-agent-activity.mjs:16) and a token stream
(scripts/mso-agent-runtime.mjs:150), so a full clear per frame is not acceptable.
This precedent is the strongest argument for Option A: the primitives, the PTY test pattern and the alt-screen teardown pattern already exist and are already green.
6. Three options
Option A: alternate screen plus a custom retained renderer inside the repo
What it changes:
- new modules under
scripts/tui/(orscripts/mso-agent-view-*.mjs), each at or under 220 physical lines: cell/width math promoted fromscripts/integrations-tui/layout.mjs, a line-diff frame writer (CUP plus erase-to-end-of-line per changed row), a transcript view that owns a buffer of styled lines, a chrome view (tab row, footer), and an input map; AgentComposerkeepsinputLayout/inputViewport/verticalCursor/menuLines(scripts/mso-agent-composer-ui.mjs:27-113) and loses its write loop (scripts/mso-agent-composer.mjs:39-62);streamTurn's injectable sink (scripts/mso-agent-runtime.mjs:73-80) is pointed at the transcript view instead of stdout;lazyAssistantOutput(scripts/mso-agent-turn.mjs:20-33) becomes a buffer append;AgentActivitybecomes one row of the frame, and its formatters (scripts/mso-agent-activity.mjs:34-52) move to a new module so the 220-line file can shrink;- alt screen entered and left inside node, with
process.on("exit"), SIGINT, SIGTERM and SIGHUP teardown.
Why a dirty-region writer and not a cell grid: every rendered row is already a fully
styled string (scripts/mso-agent-composer-ui.mjs:90-113,
scripts/integrations-tui/layout.mjs:47-51). A row-level diff (CUP plus \x1b[2K
plus text, only for rows that changed) is enough to stop flicker, and it avoids
per-cell state on top of the existing wide-char handling (layout.mjs:6-33).
Cost: six to eight new modules, roughly 900 to 1200 new lines by the repository's own ruler, plus PTY tests for resize, alt-screen teardown, and streaming under load. No install, audit or supply-chain cost.
What it breaks:
- scrollback, the moment the alt screen is entered (section 1.5). Mitigation: ship inline mode first (M2 to M4), keep the alt screen behind a flag (M5), and add a transcript view before the flag defaults on;
- the composer unit tests that assert "no
\n" if the writer ever emits line feeds (scripts/mso-agent-composer.test.ts:54,60,scripts/mso-agent-composer-session.test.ts:76,scripts/mso-agent-activity.test.ts:48); scripts/mso-agent-contract.test.ts:8-30if the banner, the section labels or the module identifiers change;scripts/capture-cli.mjs:91-99, which drives the real TUI in a PTY, waits forWelcome to MSO Agent!and assertsAvailable Tools, then writesdocs/media/mso-cli.webp; the capture must be re-run and reviewed;- WORKSPACE-GUIDE.md:229-248 (documented key map) and the parity status rows in TUI-PARITY-PLAN.md:56-62.
Gates touched: architecture (every new file at or under 220 physical lines, and
activity must shrink before it grows), lint (code-line ceiling, note the one line
left in the composer), docs (this file's classification plus the key-map update),
changelog, tests / tests + coverage.
Option B: adopt one TUI library
Named candidate that could actually install here: ink 8.0.0 (MIT, node >= 22,
619,872 B unpacked, 23 runtime deps including WASM yoga-layout ~3.2.1 and
patch-console, peer React >= 19.3.0). @opentui/core 0.8.0 is excluded by its own
engine range (node >= 26.4.0) against package.json:6-9. blessed 0.1.81 is
unmaintained.
What it changes: the CLI becomes a React renderer. Every one of the 115 direct write
sites must be routed: either converted to elements or pushed through ink's static
output. AgentComposer's key loop is replaced by the library's input hook. The
120 ms spinner (scripts/mso-agent-activity.mjs:16) and the token stream
(scripts/mso-agent-runtime.mjs:150) must be throttled into frames. spawnSync with
stdio: "inherit" (scripts/mso-agent-commands.mjs:23-24) must release the
terminal, and /restart's execve (scripts/mso-agent-lifecycle.mjs:36) must tear
the renderer down first.
Cost: one runtime dependency, 23 transitive packages, a React reconciler in the CLI path, and an adapter layer that is itself subject to the 220-line rule. Panels and list scrolling exist in the library; session tabs, a scrollbar styled like the rest of MSO, and split panes are still application code.
What it breaks: the global console contract (ink depends on patch-console; the
exact interaction with 100 existing console.log sites is unverified), the formatter
tests, and any expectation that mso agent runs on a host where only bun install
has happened, because the install now pulls a reconciler and WASM layout engine.
Gates touched: bundle budget does not apply (scripts/lib/bundle-report.mjs:17-24
measures .next only). Applicable: frozen lockfile install (ci.yml:38), audit strict
(gates-12.sh:44), dependency review on high severity, lint, architecture, docs,
changelog, tests. The native dependency gate would not validate this dependency
either way, because it is hardcoded to node-pty (gates-12.sh:36).
Verdict: permitted by policy, and still the wrong first move. It replaces a rendering problem with a dependency, a reconciler and an unverified console interaction, and it does not deliver tabs, scrollbar or splits by itself.
Option C: keep the renderer, add only cheap wins
What it changes:
- a fixed bottom chrome block of two or three rows (session tab row, then the
existing
Inputdivider and footer), painted through the row-reservation machinery that already exists (scripts/mso-agent-composer-ui.mjs:13-25), so the chrome is repainted in place and adds no scrollback; - a static panel layout: transcript stays append-only, the bottom block is the only retained region;
- mouse-free navigation: new keybindings only, no new input decoder.
Cost: one new module of about 80 to 140 lines, one or two lines of change in the composer render, one new test. No dependency, no alt screen, scrollback intact.
What it breaks: nothing structural. Gains are bounded: tabs are a labelled row, not switchable views with independent state; there is no scrollbar because there is no transcript viewport; there are no split panes.
The obvious variant, a header pinned at the top of the screen, needs a DECSTBM scroll
region (\x1b[1;Nr) because the transcript is still an append-only stream. On
xterm-compatible terminals lines that scroll out of the top of a region whose first
row is not row 1 are discarded rather than pushed to scrollback, so a pinned top
header trades away scrollback without an alternate screen. That behaviour is
unverified on Termux, Windows Terminal and macOS Terminal (section 11), which is why
the recommendation puts the chrome at the bottom, where the existing reserved-row
machinery already repaints in place.
Gates touched: architecture (new module under 220), lint, tests, docs if the
key map changes, changelog.
7. Recommendation
Take Option A, sequenced so that the risky half is last: adopt the retained frame model first in inline mode (scrollback preserved, no alt screen, no flag), then put the alternate screen, tabs, scrollbar and mouse behind an explicit opt-in once a transcript view exists. Do not take Option B now. Keep Option C as the fallback if the owner rejects scrollback loss entirely, because C is a strict subset of A's first three milestones.
Reasons, in order of weight:
- Option A needs no dependency, so it cannot fail
audit strict, dependency review,bun install --frozen-lockfile, or the install matrix on Termux/PRoot (docs/PLATFORMS.md:12-14,79-85). Option B's only viable candidate adds 23 packages and a reconciler to a CLI that currently runs onnodeplus the repo. - The primitives already exist and are already tested: cell widths and panes
(
scripts/integrations-tui/layout.mjs:1-66), a pure frame builder and painter (scripts/integrations-tui/renderer.mjs:5,14), an alt-screen wrapper with a trap (scripts/mso-cli-integrations-tui.sh:12-13,39,50), and a PTY test across six terminal sizes (scripts/mso-integrations-finder-pty.test.ts:48). - The agent already has the two hardest seams a rewrite normally lacks: an
injectable stream sink (
scripts/mso-agent-runtime.mjs:73-80) and a set of pure block formatters (scripts/mso-agent-diff.mjs:84-100,scripts/mso-agent-edit-diff.mjs:61-99,scripts/mso-agent-todos.mjs:101-149). The work is layout and state, not protocol. - The ratchet forces the right shape anyway: 43/43 files over 220 physical lines
(
scripts/check-architecture.mjs:21) means the renderer must be split into small pure modules, which is exactly what makes it testable without a PTY.
Cost in milestones (file level, not a time estimate): see section 8. The critical path is M2 (transcript model) then M3 (frame writer); everything visual depends on those two, and mouse/scrollbar/splits are additive after M5.
8. Migration order, gates green after every step
Status, updated as milestones land
| Milestone | Work | State | Evidence |
|---|---|---|---|
| M0 | This plan, classified in docs/README.md | DONE | PR #185, 2dfcda8 |
| M1 | Shared cell primitives, scripts/tui/cells.mjs |
DONE | PR #186, 5b45314; layout.mjs 67 to 20 lines |
| M2 | Transcript model, scripts/mso-agent-transcript.mjs |
DONE | PR #187; reuses formatEditDiff, formatTodoBlock, formatDiffBody |
| M3 | Frame writer, scripts/mso-agent-screen.mjs, inline mode |
DONE | PR #189; composer 221 to 217 lines, ratchet 43 to 42 |
| M4 | Chrome and tabs as a bottom block | DONE | PR #191; chromeLines and tabs switch; composer 216 lines |
| M5 | Alternate screen behind a flag, with teardown | DONE | PR #192; default off; teardown on exit, signals, execve, spawnSync |
| M6 | Transcript viewport and scrollbar | DONE | PR #193; 2000-line cap, follow mode, PgUp/PgDn/Ctrl+G/End, entrypoint 218 to 196 lines |
| M7 | Mouse | DONE | SGR 1000/1006 extended mode, wheel scrolls viewport, tab clicks switch session |
| M8 | Split panes, then flip the alt screen default | DONE | PR #198 the pane; default flipped here, inline is now the opt out (--no-altscreen) |
8.1 The default is now the panel
The four blockers are closed and the alternate screen is the default:
- Print sink,
scripts/mso-agent-print.mjs, installed by the screen loop assession.printSinkand consumed by every command module. One whole release was lost here: #202 added the router and migrated twelve modules, but nothing installed the sink, so it fell through toconsole.logevery time and looked correct in the diff. #206 installed it. - Composer height, reported through
onRowsand reserved exactly, capped at terminal rows minus four rather than a quarter of the terminal, which on a 12 row terminal was 3 and made the fix inert in the case it existed for. - Approval prompts suspend the panel, and suspension leaves the alternate screen. Detaching the sink alone was not enough: the prompt was painted into the buffer and the next repaint erased it, so the user answered a question that had vanished.
- Mid-turn writes go through
turnPrinter, including the activity row, which is forced to discrete lines in panel mode because a live spinner row draws at the cursor inside the frame.
The startup banner moved into the transcript for the same reason: it was printed before the first frame and that frame erased it. The entrypoint captures it through an injectable print and the loop prepends it to every render, trimmed to its last four lines in panel mode because the full banner is 31 lines and would occupy most of a 30 row viewport.
Inline mode is now the opt out, not the default: --no-altscreen or MSO_ALT_SCREEN=0. Non-TTY, CI
and --oneshot are still refused regardless, and an explicit opt out is silent rather than merely
inactive.
Adjacent work that landed while this plan was being executed, and belongs to the same goal:
feat/agent-jobs-view (#183, /jobs for background subagents) and feat/tui-keybinds (#182,
~/.mso/keybinds.json), which closed P2-3.
M0. Documentation. This file, one classification row in docs/README.md (required by
scripts/check-docs.mjs:56-63), a pointer from
TUI-PARITY-PLAN.md:56-62, and
node scripts/gen-changelog.mjs. Gates: docs, changelog, architecture (no code
change), lint, typecheck.
M1. Extract shared cell primitives. New scripts/tui/cells.mjs (about 90 lines:
stripAnsi, clean, cellWidth, fitCells, compose, windowFor, paneWidths,
border, paneRow), moved out of scripts/integrations-tui/layout.mjs:1-66;
layout.mjs re-exports them so scripts/mso-integrations-finder-pty.test.ts and
scripts/mso-integrations-finder.test.ts stay untouched. New
scripts/tui/cells.test.ts. Gates: architecture (two files, both under 220),
lint, tests, changelog.
M2. Transcript model. New scripts/mso-agent-transcript.mjs (about 180 lines) that
turns history rows and live blocks into an array of styled lines, reusing
formatEditDiff, formatTodoBlock, formatDiffBody, sectionDivider. It must
handle the row shapes actually persisted: assistant rows with toolUses, tool rows
with compacted results (scripts/mso-agent-context.mjs:100,148), and agent rows
(scripts/mso-agent-local.mjs:67-82). No rendering change yet: add /transcript
style output first, or a single renderTranscript(history) used by /export
parity. Gates: architecture, lint, tests, docs if a command is added
(docs/CLI.md is generated and checked by scripts/check-docs.mjs:100-102).
M3. Frame writer, inline mode. New scripts/mso-agent-screen.mjs (about 180 lines):
writeFrame(output, previousLines, nextLines) diffing row by row with CUP plus
\x1b[2K, a resize subscription that reuses output.on("resize")
(scripts/mso-agent-composer.mjs:204), and cursor hide/show paired. Move the
composer write loop (scripts/mso-agent-composer.mjs:39-62) into it. Constraint:
composer.mjs has one code line of lint headroom, so the moved code must leave more
lines behind than it adds, or move reserveComposerRows/eraseComposerRows
(scripts/mso-agent-composer-ui.mjs:13-25) wholesale. The existing composer tests must
pass unchanged, including the no-\n assertions.
M4. Chrome and tabs as a bottom block. New scripts/mso-agent-chrome.mjs (about 130
lines) rendering a tab row (@name per session) and the footer from statusParts
(scripts/mso-agent-status.mjs:62-88) and composerFooter
(scripts/mso-agent-layout.mjs:49-60), painted by M3 above the composer. Tabs switch
by reusing the existing session switch path (scripts/mso-agent-session-ui.mjs:65-82)
rather than by introducing parallel session objects. No alt screen yet, so scrollback
survives.
M5. Alternate screen behind a flag. Add enterScreen/leaveScreen with teardown on
exit, SIGINT, SIGTERM, SIGHUP, and explicit release before spawnSync(... stdio: "inherit") (scripts/mso-agent-commands.mjs:23-24) and before execve
(scripts/mso-agent-lifecycle.mjs:36). Shrink scripts/mso-agent-activity.mjs below
220 physical lines first (move the frame table and formatters to
scripts/mso-agent-activity-format.mjs) or the gate fails on the first added line.
M6. Transcript viewport and scrollbar. Keys PgUp/PgDn, Ctrl+G and Ctrl+Shift+G where the terminal reports it, plus a
scrollbar column rendered from windowFor (scripts/integrations-tui/layout.mjs:60-66).
Wire streamTurn's sink (scripts/mso-agent-runtime.mjs:73-80) and
lazyAssistantOutput (scripts/mso-agent-turn.mjs:20-33) to append to the buffer
instead of stdout.
M7. Mouse. SGR reporting (\x1b[?1002h / \x1b[?1006h) plus decoding, wheel to
scroll, click to focus a pane. Only after the owner decides the selection policy
(open question 6).
M8. Split panes. Reuse paneWidths, border, paneRow
(scripts/integrations-tui/layout.mjs:35-51) for a right-hand panel (todos, diff,
files). Then flip the alt screen default on, and keep inline mode for --oneshot
(scripts/mso-agent-oneshot.mjs) and non-TTY callers.
First three commits, concretely:
docs(tui): add retained renderer plan and classify itfiles:docs/TUI-RENDERER-PLAN.md(new),docs/README.md(one row next toTUI-PARITY-PLAN.mdat:64),docs/TUI-PARITY-PLAN.md(Phase 2 pointer),docs/CHANGELOG.md(regenerated). Runnode scripts/check-docs.mjs,node scripts/check-architecture.mjs,node scripts/gen-changelog.mjs --check.refactor(tui): share cell-width and pane primitivesfiles:scripts/tui/cells.mjs(new),scripts/tui/cells.test.ts(new),scripts/integrations-tui/layout.mjs(re-export only, smaller than today's 67 lines),docs/CHANGELOG.md. Runarchitecture,lint,vitest run scripts/tui/cells.test.ts scripts/mso-integrations-finder.test.ts scripts/mso-agent-layout.test.ts.refactor(agent): paint the composer through a frame writerfiles:scripts/mso-agent-screen.mjs(new),scripts/mso-agent-composer.mjs(replace the write loop; the file is at 219 of the 220 lint code lines, so the move must not add code lines to it),scripts/mso-agent-composer-ui.mjs(receivereserveComposerRowsanderaseComposerRows, 105 code lines now, headroom 115),scripts/mso-agent-screen.test.ts(new). Runarchitecture,lint,vitest run scripts/mso-agent-composer.test.ts scripts/mso-agent-composer-wrap.test.ts scripts/mso-agent-composer-session.test.ts scripts/mso-agent-activity.test.ts.
9. What must not be attempted
- A renderer file larger than 220 physical lines.
filesOver220is exactly at its ceiling (43/43,node scripts/check-architecture.mjs), andarchitecture.boundaries.json:20forbids raising a ratchet without an explicit architecture decision. The gate fails on the first such file. - Adding any line to
scripts/mso-agent-activity.mjsbefore removing one. It is exactly 220 physical lines; one more line makes the count 44. Its lint headroom is irrelevant becausearchitecturefails first. - Growing
scripts/mso-agent-local.mjsorscripts/mso-agent-composer.mjsin code lines. Local is at 220 of 220 code lines; the composer at 219 of 220. With--max-warnings=0(scripts/gates-12.sh:34) a single warning failslint. - Entering the alternate screen before a transcript view exists. Nothing replays
history (section 1.5), so
/resumewould render an empty screen and quitting would destroy the only record of the conversation./export(scripts/mso-agent-cmd-parity.mjs:45) is the only current recovery path. - Relying on a bash trap in the launcher to restore the screen. The launcher
execs node (scripts/mso-cli-agent.sh:397-399), so no shell code survives to run a trap. Teardown must be in-process, or theexecmust be removed and the installer and CLI contract re-verified. - Shipping
@opentui/coreas a drop-in. Registry metadata for 0.8.0 declaresnode >= 26.4.0againstpackage.json:6-9(^22.12.0 || ^24.0.0 || >=26.0.0), ships an 18 MB package plus 8 platform-native packages, and no gate would catch the mismatch:native dependencyonly checks node-pty (scripts/gates-12.sh:36). - A full-screen clear per frame (the Integrations approach,
scripts/integrations-tui/renderer.mjs:14). With a 120 ms spinner (scripts/mso-agent-activity.mjs:16) and SSE deltas (scripts/mso-agent-runtime.mjs:150) this flickers and loses the cursor position that the composer currently guarantees (scripts/mso-agent-composer.mjs:55-61). - Renaming or deleting the contract strings.
scripts/mso-agent-contract.test.ts:8-30asserts the exact banner art, six RGB triples, and identifiers includingAgentComposer,composerPrompt,composerFooter,composerSeparator,sectionDivider,Agent work,Local agent. Change them only together with that test. - Editing
bin/msoorscripts/install-core.shfor this feature. They sit at 212 of 220 and 450 of 450 respectively (scripts/check-architecture.mjs:47-48). - Turning on mouse tracking before deciding selection policy. SGR mouse
reporting disables native text selection; the TUI's exported transcript is the
replacement, and
/exportis a round trip.
10. Open questions for the owner, ranked
- Is losing terminal scrollback acceptable? If no, the alternate screen is off the table forever and the plan collapses to Option C plus A's inline milestones (M0 to M4). This single answer changes more than any other.
- Is a new runtime dependency acceptable at all, and if OpenTUI is the target is
the Node floor movable to 26.4? The first half decides ink, the second decides
@opentui/core; todaypackage.json:6-9excludes the latter. - Must the TUI keep working on Node 22 and 24 hosts? This alone decides whether
OpenTUI can ever be considered; it also decides whether WASM dependencies are
acceptable on Termux/PRoot (
docs/PLATFORMS.md:12-14). - Is a reconstructed transcript allowed to show compacted tool results? The
runtime deliberately replaces read-tool payloads with bounded envelopes
(
scripts/mso-agent-turn.mjs:140-143,scripts/mso-agent-context.mjs:100), so a replay view will not match what scrolled by live. Accepting that difference is a product decision. - Do tabs mean multiple live sessions or one session with a switcher? Multiple
live sessions need one
LocalAgentBridgeper session (scripts/mso-agent-local.mjs:84-97,105-124,158-201), each with its own feed and heartbeat. A switcher reusesscripts/mso-agent-session-ui.mjs:65-82and costs almost nothing. - Is losing native text selection for click and wheel acceptable? If not, mouse is wheel-only at reduced value, or skipped.
- Is the scrollbar required for the first ship? It is pure cost until the transcript viewport (M6) exists.
- Should
/restartpreserve screen state? It currentlyexecves a new process (scripts/mso-agent-lifecycle.mjs:36); an alt screen must be left before that, and re-entered after, or the new process inherits the old screen.
11. Explicitly unverified
- Runtime behaviour of
ink8.0.0 and@opentui/core0.8.0 inside this repository. Only registry metadata was read; neither was installed. - Whether
ink'spatch-consoledependency interferes with the 100 existingconsole.logcall sites. The dependency is listed in registry metadata; the interaction was not tested. - The "live PTY regression" for zero-scrollback Tab cycling claimed in
docs/PROGRESS.md:2649. No such test exists in the current tree; onlyscripts/mso-integrations-finder-pty.test.tsuses a real PTY. - Terminal-specific behaviour of a pinned header via a DECSTBM scroll region on Termux, Windows Terminal and macOS Terminal. Not tested here, and it is why the recommendation keeps chrome at the bottom of the screen.
- Exact coverage impact of replacing the composer write loop. Coverage thresholds
(statements 42 / branches 40 / functions 32 / lines 43.5,
scripts/gates-12.sh:47-49) were not measured for a candidate change.
12. One-line summary
The agent TUI is 15 modules and 115 direct write sites of append-only output with no frame, no alt screen, no mouse and no transcript buffer; the repository already owns a dependency-free frame renderer for Integrations and a hard 43/43 line ratchet, so the correct path is a split, dependency-free frame writer in inline mode first, with session tabs and a bottom chrome as the cheapest visible change and the alternate screen, scrollbar, mouse and splits deferred behind a flag until a transcript view exists.