24 KiB
Permanent terminal (bottom panel / floating window)
A full terminal available from every destination, independent of chats.
Each terminal starts at the machine's login prompt (su -l <user> for the
server's own account), so the operator types that account's password before
getting a shell. It keeps running, logged in, when the panel is hidden or the
app navigates or reloads; it ends when the Pipelines server restarts (run
tmux inside it for work that must survive that).
Behaviour
- Modes (Settings → Appearance → Terminal, or the terminal's own ⋮ menu): Bottom panel docks under the app (the app shrinks above it, never hidden under it); Floating window is a window over the app. Both are toggled by the bar's Terminal button (every destination's bar ends with it) and the shortcuts below.
- First open: the first time the terminal is shown in an app run (once
every machine's list has arrived) it starts one terminal, as New terminal
does, unless one is already running; it shows the login prompt and the
operator types the password into the terminal (the PTY hides it). From
then on the button, shortcuts and the narrow page only hide and show it:
no toggle opens another terminal, even after every tab is closed (New
terminal does). Opening one by hand first counts as the first
(
TerminalHub.firstOpenDone,openTerminalIfNone). Each new tab is its own login and asks for the password again. - Shortcuts (
terminal_shortcuts.dart, handled by the surface as aFocusManagerearly key handler, so they work wherever focus is, including inside the terminal and in the chat composer, and neither receives the key):- Alt+T (Option+T), Ctrl+T, Cmd+T (Meta+T) and **Ctrl+
** show or hide the terminal in the selected mode; on a narrow window they open and close the full-screen page. Only the one modifier counts (Ctrl+Shift+T, Ctrl+Alt+T pass through); Option+T, which types † on a Mac, is also matched by key position. Cmd+stays the macOS window switcher. The shell's own Ctrl+T (transpose-chars) no longer reaches it while this binding is on. - Ctrl+Tab / Ctrl+Shift+Tab, while the terminal is shown (panel,
window or narrow page), select the next / previous terminal tab, wrapping,
and focus it. This deliberately overrides the chat's Ctrl+Tab pane
cycling while the terminal is open (
TerminalActions.claimsTabKeys, checked bychat_screen_workspace.dart); hidden, Ctrl+Tab cycles chat panes as before. - Browsers keep some of these: a normal Chrome/Safari/Firefox tab
never receives Cmd+T (new tab) or Ctrl+Tab / Ctrl+Shift+Tab (switch
tabs), and outside macOS Ctrl+T is new tab too. The web build therefore
lists only Ctrl+T (macOS), Alt/Option+T and Ctrl+
in the button tooltip and the ⋮ menu (TerminalShortcutLabels`), and no tab keys; the handlers stay on, so an installed app window that does deliver a key still works. Native macOS/Linux/Android-with-keyboard builds get all of them and list them.
- Alt+T (Option+T), Ctrl+T, Cmd+T (Meta+T) and **Ctrl+
- Focus: whenever the terminal shows (shortcut, button, a reload that
restores it, a mode change, un-minimising, a tab change by pointer, key or
New terminal) the selected tab's emulator gets the keyboard: the body is a
FocusScopethe surface focuses after the frame, and the emulator autofocuses inside it (terminal_focus.dart). Hiding gives the keyboard back at once to what had it before opening (the composer, a field), if the terminal still has it; the narrow page's route restores focus itself. - Motion:
Motion.standard(200 ms,Motion.curvein, ease-in-cubic out), played on the app clock the animation-speed setting dilates, and zero under reduced motion (Motion.of). The bottom panel keeps its full height and slides up from the bottom edge with a slight fade (opacity 0.4 to 1) while the app above shrinks with it frame by frame (no jump, and the emulator is not resized during the motion); the floating window scales from 92 % and fades in its own place. During the hide motion the terminal stays mounted but takes no pointer or focus (terminal_stage.dart). - Bottom panel: resized by dragging its top edge (the app's
AdaptiveResizeGrip; arrow keys too, slider semantics); its height is remembered. The panel always leaves the app at least 160 px. - Floating window: dragged by its title bar, resized from its lower right corner, double-click or Maximise fills the app (8 px margin), Minimise collapses it to its title bar, × hides it. Frame and state are remembered.
- Narrow windows (< 600 px): the terminal opens as a full-screen page (Material/Cupertino route) with the chat terminal's key toolbar (Paste, Enter, Ctrl-C, Tab, Esc, arrows, and the typing field on Android/iOS).
- Tabs: one per terminal; the title is the shell's OSC 0/2 title
(followed by the emulator, also recorded by the server for the list),
else the start folder (
~for home). Ended terminals are italic and show why they ended with a Close tab button. With more than one machine connected (or tabs from several) each tab names its machine, and New terminal (+) asks which machine. ⨯ on a tab closes it, which kills the login or shell. - Open in terminal: the chat header's More menu (the chat's folder, on the chat's machine) and a folder's ⋮ menu in the Files panel open a new terminal there and show the surface.
- Permanence: the app's
TerminalHublives as long as the app; hiding or minimising never closes a shell. Reopening redraws the same emulator. The layout (mode, shown, height, frame) is saved per device, so a reload reopens the terminal, lists the machine's terminals and resumes each from its retained output. A dropped connection resumes after the last byte held. A restarted server lists the terminals as ended, with why. - Keyboard: a focused terminal gets every key (Ctrl-C, Esc, Tab, arrows, Ctrl-letters) except the shortcuts above (Ctrl+T, Alt+T, Cmd+T, Ctrl+`, and Ctrl+Tab while shown); paste is Cmd-V (Apple) or Ctrl-V/Ctrl-Shift-V. Clicking elsewhere moves focus away normally.
- No terminal request is sent until the terminal is first shown (or a
terminal is opened): each connection sends one request at a time, so the
first screen's read is never queued behind
terminal_list.
Protocol (server)
internal/protocol/terminal.go; documented in docs/cli.md ("Machine
terminals"). Body terminal_request {terminal_id?, cwd?, cols?, rows?, data?, after?}.
terminal_open {cwd, cols, rows}→terminalonce su's password prompt shows (subscribes the connection to its output first); refused when the login cannot ask for a password (below).terminal_list→terminals(running and ended, oldest first; live records carry their current title, size andstream).terminal_input {terminal_id, data}(UTF-8, ≤ 16 KiB, 64-request queue),terminal_resize {terminal_id, cols, rows}(clamped 20–500 × 4–200).terminal_output {terminal_id, after}→terminalwithoutput,output_start,output_end,stream; subscribes the connection.terminal_close {terminal_id}→ the closed record (runs off the read loop: it waits up to 3 s for the shell).- Pushed
terminal_event: output{terminal_id, output, offset, end}to subscribed connections, lifecycle{terminal_id, terminal}(opened, title, exited, closed) to every connection. A slow connection's queue (256 frames) drops output; the client sees the offset gap and re-reads.
Login and lifetime (server)
internal/server/terminal_login.go. A terminal runs, in its PTY,su -l <user> -c '<script>'for the server's own account (user.Current): su from PATH, else/usr/bin/su(macOS) or/bin/su,/usr/bin/su(Linux), withLC_ALL=Cso the prompt is English. macOS su passes the arguments after the login name to the shell; util-linux su takes-c. PAM asks for the account's password even though the server already runs as that user (checked on this Mac:/etc/pam.d/suispam_rootoksufficient, thenpam_opendirectory). After the login the account's shell runs the script: it prints the marker OSCESC ] 6973;pipelines-login BEL(emulators ignore it), cds to the start folder (home when that fails) andexec "$SHELL" -l(su -l's own login shell has read the profile once already, so the login profile runs twice).terminal_openreplies only once the output shows "password" (within 5 s). It is refused with a reason, and never listed, when su is missing, the server runs as root (pam_rootokwould skip the password), the marker arrives before any prompt (an account without a password), su exits first (its last line is quoted, e.g. no terminal), or nothing asks in time. There is no fallback to an unauthenticated shell.- A wrong password: su prints
su: Authentication failed(macOS) and exits 1; the tab is ended with "The login did not complete (wrong password, or the prompt was cancelled)..." and the exit code. Close it and open a new terminal to try again. - No tmux: a terminal is a direct child of the server and ends with it. A
stop records "The Pipelines server stopped..."; on start, records still
running(a crash, or a stop whose save lost the race with the store closing) become ended with "The Pipelines server restarted and this terminal ended with it... run tmux inside a terminal...". The tmux backing, reattach and the record'stmuxfield are gone; the DB'stmuxcolumn stays (additive schema) but is no longer written. - Leftovers:
cmd/pipelines-servercallsserver.EndLegacyTerminalTmux()at start: ontmux -L pipelines -f /dev/nullonly, it kills sessions namedpipelines-term_*(what earlier servers created); any other session there and the operator's own tmux servers are untouched. - DB table
terminals: id, title, cwd, shell (<su> -l <user>), created_at, status, ended_at, exit_code, reason, cols, rows. Ended records beyond 16 are pruned. Output stays in memory (1 MiB tail per terminal).
Security
- Only reachable through the authenticated
/connectwebsocket, like chat shell commands, and each terminal then needs the machine account's password (su), a second barrier. Any connection of that server may list, type into or close its terminals, including a logged-in one. - The start folder must exist inside the operator's home after resolving
symlinks (the Files panel's containment);
~,~/suband absolute paths are accepted,~userand relative paths refused. - Input is never logged or stored: the server skips its request log line
for
terminal_input/terminal_resize, nothing is written to the DB, and the client's input pipe (ChatShellInputPipe, shared with chat shells) keeps nothing once sent. The password is typed into the PTY with echo off, so it is in neither the output nor the retained tail.
Limits and known gaps
- 8 running terminals per machine; 1 MiB retained output per terminal.
- Terminals end when the server restarts; persistence is tmux inside the logged-in shell, by hand.
- Linux su was not run: the arguments follow util-linux su; only this Mac's
/usr/bin/suwas checked for real. - The client transport sends one request at a time per connection, so a keystroke waits behind any slower request on the same machine (as chat shell input already does).
- Opening a terminal elsewhere (another device) adds its tab here too: the tabs are the machine's terminals.
- Mobile (narrow page, soft-keyboard field) is verified by widget tests and a narrow Chrome capture only; no device test ran. Android/Linux builds were not run.
test/applicationandtest/features/settingshave 51 failures that are identical on the base commit8f06f12d(pendingLaunchUpdateCheckertimers etc.); none is new.
Files
- Server:
internal/protocol/terminal.go,message.go;internal/pipeline/terminals.go,store.go;internal/server/terminal_{manager,supervise,process,login,legacy_tmux,clients,title,cwd,handlers}.go,websocket.go,cmd/pipelines-server/main.go; teststerminal_ws_test.go,terminal_login_test.go,terminal_lifetime_test.go,terminal_legacy_tmux_test.go,internal/pipeline/terminals_test.go;docs/cli.md. - App:
lib/features/terminal/(terminal_{info,stream,tab,hub,listing,machines,layout,scope,surface,stage,focus,shortcuts,panel,float,float_frame,page,body,tab_strip,menu,toggle_button,open_action}.dart),lib/application/app_terminals.dart,pipelines_app.dart,bootstrap.dart,lib/shell/adaptive_shell.dart(barActions),lib/features/settings/settings_terminal_section.dart(+ screen/topic pages),lib/features/chat/conversation/chat_thread_view.dart(Open in terminal),lib/features/chat/files/files_panel.dart(folder action),lib/features/chat/shell/chat_shell_terminals.dart(ChatShellInputPipemade public),lib/features/chat/chat_screen_workspace.dart(Ctrl+Tab yields to a shown terminal). Teststest/features/terminal/. Probe fixturetool/perf/terminal_fixture.dart(?terminals=1,?terminal=panel|float).
Verification
Go 1.x / Flutter 3.44.6, macOS host, tmux 3.7c (/opt/homebrew/bin/tmux).
-
go test ./internal/protocol ./internal/pipeline ./internal/server -count=1:ok …/protocol 0.188s,ok …/pipeline 8.193s,ok …/server 69.120s. Terminal tests: open/list/input/resize/output-resume/close over the websocket with two clients; shell exit status; cwd containment, input bounds, unknown ids, the 8-terminal limit; tmux survives a manager restart (list running, screen redrawn, shell variable kept, close kills the session); a killed tmux client is replaced; without tmux the stop and a crashed record are listed as ended with their reasons; OSC titles.-race -count=4on the terminal tests: ok. Each tmux test uses its own socket and removes it.go vet,gofmt -l: clean.GOOS=freebsd go build ./internal/server,GOOS=linux go test -c: ok. -
tool/memwatch/full.sh test/features/terminal:PASS: 15 passed(hub: lazy activation, ordered output + gap re-read, reconnect resume and new-stream re-read, open/select/close, foreign open/close frames, titles and ended reason, input, multi-machine, refusals; surface: Ctrl+` and button toggle while the terminal has focus, hiding keeps shells, panel drag-resize remembered and app shrinks, float drag/resize/ minimise/maximise, tabs select/close/new, mode switch from the menu, Settings mode choice, narrow full-screen page with key toolbar). -
tool/memwatch/full.sh test/features/chat:PASS: 1137 passed, 0 failed. -
test/application test/shell test/features/settings: 129 passed, 51 failed — the same 51 failing tests as the base commit (compared by name). -
tool/analyze.sh: clean.flutter build web: built.FLUTTER_XCODE_ARCHS=arm64 flutter build macos: built (35.0MB). -
Real Chrome (
tool/capture, probe?terminals=1, 1280x820), inspected:/tmp/terminal-panel/panel-{light,dark}/01-panel.png,03-panel-three-tabs.png,04-panel-taller.png(dragged up 200 px);/tmp/terminal-panel/typed-{light,dark}/01-panel-tab2-typed.png(second tab,pwd+Enter typed as key events, focused cursor);/tmp/terminal-panel/float-{light,dark}/01-float.png,02-float-moved-resized.png,03-float-minimised.png,04-float-maximised.png;/tmp/terminal-panel/settings-light/0{1,2,3}-*.png(Appearance → Terminal, choosing Floating window, then the bar button);/tmp/terminal-panel/narrow-light/01-narrow-page.png(560 px page with key toolbar);/tmp/terminal-panel/cupertino-dark/0{1,2}-*.png(Cupertino, two machines: tabs name their machine, New terminal asks which);/tmp/terminal-panel/chat-open/02-chat-opened-terminal.png(chat More → Open in terminal opened/workspace/demo). -
Scratch server end to end (
go build ./cmd/pipelines-server;env -iwith HOME, XDG_DATA_HOME, DB andTMUX_TMPDIRunder/tmp/term-e2e, OS-chosen loopback port,SHELL=/bin/bash; Node websocket driver/tmp/term-e2e/drive.mjs, script/tmp/term-e2e/run.sh; server stopped and tmux server gone afterwards):opened term_c76697ebb5a10ce7 cwd=/tmp/term-e2e/home shell=/bin/bash tmux=pipelines-term_c76697ebb5a10ce7 size=100x30 typed command ran: before-restart-42 seen server 94915 stopped tmux sessions while the server is down: pipelines-term_c76697ebb5a10ce7 pane_pid=94934 tmux scrollback while the server is down: line-1 / line-2 / line-3 / before-restart-42 server pid 94951 port 62223 list after restart: term_c76697ebb5a10ce7 running tmux=pipelines-term_c76697ebb5a10ce7 stream=e5cca0de2a86 reattached output (1463 bytes) has earlier lines: line-1=true line-3=true before-restart-42=true shell state survived: KEEP=kept-across-restart close: terminal_close status=closed list after close: 0 terminals tmux sessions after close: no server running on /private/tmp/term-e2e/tmux/tmux-501/pipelines input lines logged: 0 KEEP in log: 0
Toggle shortcuts, focus and motion (2026-11-09)
- Fixed on the way: the previous Ctrl+
handler was aHardwareKeyboardhandler, which does not stop the focus tree, so a focused terminal also received the backquote. The shortcuts are nowFocusManagerearly key handlers; a widget test asserts noterminal_input` for each chord and no input from a held chord's repeats. tool/memwatch/full.sh test/features/terminal:PASS: 38 passed(each of Alt+T, Ctrl+T, Cmd+T, Ctrl+toggling the panel and the window from a text field and from inside the terminal; Option+T (†) by key position; Shift / second modifier ignored; held chord toggles once; focus on show, on reload restore and on pointer tab change; focus back to the field on hide; Ctrl+Tab / Ctrl+Shift+Tab cycling and wrapping only while shown; auto-start of a terminal when none; narrow page open/close/focus/ Ctrl+Tab; panel slide with the app shrinking mid-way, window scale+fade, hide keeps it mounted, animation-speed dilation, reduced motion instant; labels per platform; withChatScreen`: Ctrl+Tab cycles panes when hidden, terminal tabs when shown, and the composer gets the keyboard back).tool/memwatch/full.sh test/shell:PASS: 128 passed.tool/memwatch/full.sh test/features/chat:PASS: 1144 passed, 0 failed.tool/analyze.sh: clean.flutter build web: built.FLUTTER_XCODE_ARCHS=arm64 flutter build macos: built (35.1MB).- Real Chrome (
tool/capture, probe?terminals=1, 1280x820; the kit's film step gainedfilm=press:<chord>to film a key press), inspected:/tmp/terminal-toggle/panel/02-panel-show-sheet.png,/tmp/terminal-toggle/panel-warm/01-panel-show-warm-sheet.png(269 ms frame: panel half way up, app above shrunk),panel/07-panel-hide-sheet.png(183 ms frame mid-slide),panel/03-focused-after-alt-t.png,panel/04-typed.png(pwdtyped straight after Alt+T),panel/05-ctrl-tab.png,panel/06-ctrl-shift-tab.png;/tmp/terminal-toggle/float/02-float-hide-sheet.png(178 ms, scaled and faded),float/04-float-show-sheet.png(164 ms),float/05-float-focused.png,float/06-menu-shortcuts.png(web on macOS lists "Show or hide: Ctrl+T, Option+T, Ctrl+", no tab keys);/tmp/terminal-toggle/chat/0{1..4}-*.png(composer "draft ", Alt+T,lstyped in the terminal, Ctrl+Tab to~, Alt+T,oklands in the composer: "draft ok", no strayt/†`). - Not verified: CDP key events are delivered to the page directly, past the
browser's own shortcuts, so the captures cannot show which chords a real
browser keeps; the list above follows the browsers' documented reserved
shortcuts (Cmd+T, Ctrl+T outside macOS, Ctrl+Tab, Ctrl+Shift+Tab). OS-level
keys via
osascript/System Events were not permitted (it waited on the automation permission), so neither real Chrome nor the native macOS build's Cmd+T was driven by real keystrokes; native behaviour is verified by widget tests only.
Login prompt instead of tmux (2026-11-10)
The tmux results above (restart survival, client replacement, the
/tmp/term-e2e run) describe the removed tmux backing.
-
go test ./internal/protocol ./internal/pipeline ./internal/server ./cmd/pipelines-server -count=1:ok …/protocol 0.190s,ok …/pipeline 8.169s,ok …/server 70.840s,ok …/cmd/pipelines-server 0.217s.go test -race -run Terminal -count=3 ./internal/server: ok.go vet,gofmt -l: clean;GOOS=linux GOARCH=amd64 go vet+go test -c,GOOS=freebsd go build ./internal/server: ok. Terminal tests use a fakesuon PATH (printsPassword:, reads a line with echo off, accepts onlytest-password; modes for no prompt, silence and no terminal), so no real password is ever needed: login args per OS and refusals (root, no su, no user, other systems), refusal without su on PATH or in the usual directories, the prompt in a real PTY, wrong password ended with its reason and exit 1, right password gives a shell in the start folder with the password absent from the output, unprompted/silent/failing logins refused and never listed, ended on stop and on restart with their reasons, no tmux in the record, leftover-session cleanup on a test socket (onlypipelines-term_*killed), and the websocket open/input/resize/resume/ close, exit status and limits tests logged in through the fake. -
tool/memwatch/full.sh test/features/terminal:PASS: 48 passed, 0 failed(newterminal_first_open_test.dart: first show opens exactly one terminal in the panel and in the window, and six toggles open no more and close none; closing every tab then toggling opens none; a running terminal from before is shown, not added to; only ended ones (server restarted) → one new login; a hand-opened one counts as first and New terminal still opens another; three quick taps open one; the narrow page opened three times opens one).tool/analyze.sh: clean. -
Real
/usr/bin/suon this Mac, as the same non-root user, in a PTY (/tmp/su-probe/probe.py):Password:; a wrong password →su: Authentication failed, exit 1. The operator's password was never typed. -
Scratch server live check (
/tmp/term-login-e2e/run.sh, driverdrive.mjs):env -i, HOME, XDG_DATA_HOME, DB andTMUX_TMPDIRunder/tmp/term-login-e2e, OS-chosen loopback port,PIPELINES_MDNS=off; two sessions planted on the scratchtmux -L pipelinesfirst:leftover sessions planted on the scratch tmux -L pipelines: mine pipelines-term_leftover server pid 43971 port 50492 scratch tmux sessions after start: mine opened term_f04cd8ac8c198a09 status=running shell="/usr/bin/su -l alan" cwd=/tmp/term-login-e2e/home tmux=(none) output of term_f04cd8ac8c198a09: "Password:" su processes under the server: 43987 su server 43971 stopped su processes left: 0 list after restart: term_f04cd8ac8c198a09 exited reason="The Pipelines server restarted and this terminal ended with it. Terminals end with the server; run tmux inside a terminal to keep work across restarts." opened term_add0f7930d880b69 status=running shell="/usr/bin/su -l alan" cwd=/tmp/term-login-e2e/home tmux=(none) output of term_add0f7930d880b69: "Password:" close: terminal_close status=closed terminals table: (empty after closing both) input requests logged: 0 terminal: ended 1 tmux session(s) an earlier Pipelines server left on tmux -L pipelinesThe stop's own save lost the race with the store closing (
terminal save …: sql: database is closed, as before this change), so the restart recorded the end instead. The scratch server's opencode stage service outlived it and was killed by hand. -
Not verified: logging in for real (needs the operator's password), Linux su, and the app against a live server in a browser (widget tests only).