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.

docs(tui): a handover for the panel track, so a pause costs nothing (#208)

Abdurrahman Fakhrulcf8459a8e769
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 251f24fb..b1c14e89 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,7 +8,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Added**
-- `tui` install the print sink the last change forgot, and migrate the modules that still print
+- `tui` install the print sink the last change forgot, and migrate the modules that still print (#206)
- `tui` a suspended panel really leaves the alternate screen, so an approval is readable (#205)
- `tui` mid-turn writes go into the panel, and prompts suspend it instead of fighting it (#204)
- `tui` the composer reports its height, so the panel stops guessing how much to reserve (#203)
@@ -37,6 +37,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Docs**
+- `tui` a handover for the panel track, so a pause costs nothing
- handover for the next session, plus the entry this session was missing
- `tui` name the four things between here and an alternate screen default (#199)
diff --git a/docs/README.md b/docs/README.md
index 09509f13..2a7c5b4f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -63,6 +63,7 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`N8N-PARITY.md`](./N8N-PARITY.md) | Core n8n capability map across native Workflows, Organization, Integrations and the dedicated external n8n workspace |
| [`TUI-PARITY-PLAN.md`](./TUI-PARITY-PLAN.md) | MSO Agent TUI parity program: per-item status, the server seam each item uses, and the items deliberately refused |
| [`TUI-RENDERER-PLAN.md`](./TUI-RENDERER-PLAN.md) | What the TUI is today, why a retained renderer is the only path to panels and tabs, and the M0 to M8 order that keeps every gate green |
+| [`TUI-HANDOVER.md`](./TUI-HANDOVER.md) | Where the TUI panel track stands, the state of the one in-progress branch, and what must be true before the alternate screen becomes the default |
| [`ORGANIZATION.md`](./ORGANIZATION.md) | Owner-private organization units, seats, reporting lines, live agent bindings, and workflow routing references |
| [`MCP-HOW-TO.md`](./MCP-HOW-TO.md) | Bahasa Indonesia onboarding: client connection, prompts, workflow, project MCP and troubleshooting |
| [`MCP.md`](./MCP.md) | MCP/OAuth internals and full external-tool security model |
diff --git a/docs/TUI-HANDOVER.md b/docs/TUI-HANDOVER.md
new file mode 100644
index 00000000..a15f6308
--- /dev/null
+++ b/docs/TUI-HANDOVER.md
@@ -0,0 +1,117 @@
+# 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`:
+
+```js
+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.