Files
pipelines/app/notes/terminal-panel.md
T

24 KiB
Raw Blame History

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 a FocusManager early 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 by chat_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.
  • 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 FocusScope the 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.curve in, 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 TerminalHub lives 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} → terminal once 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 and stream).
  • 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} → terminal with output, 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), with LC_ALL=C so 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/su is pam_rootok sufficient, then pam_opendirectory). After the login the account's shell runs the script: it prints the marker OSC ESC ] 6973;pipelines-login BEL (emulators ignore it), cds to the start folder (home when that fails) and exec "$SHELL" -l (su -l's own login shell has read the profile once already, so the login profile runs twice).
  • terminal_open replies 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_rootok would 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's tmux field are gone; the DB's tmux column stays (additive schema) but is no longer written.
  • Leftovers: cmd/pipelines-server calls server.EndLegacyTerminalTmux() at start: on tmux -L pipelines -f /dev/null only, it kills sessions named pipelines-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 /connect websocket, 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); ~, ~/sub and absolute paths are accepted, ~user and 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/su was 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/application and test/features/settings have 51 failures that are identical on the base commit 8f06f12d (pending LaunchUpdateChecker timers 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; tests terminal_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 (ChatShellInputPipe made public), lib/features/chat/chat_screen_workspace.dart (Ctrl+Tab yields to a shown terminal). Tests test/features/terminal/. Probe fixture tool/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=4 on 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 -i with HOME, XDG_DATA_HOME, DB and TMUX_TMPDIR under /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 gained film=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 (pwd typed 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 fake su on PATH (prints Password:, reads a line with echo off, accepts only test-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 (only pipelines-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 (new terminal_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/su on 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, driver drive.mjs): env -i, HOME, XDG_DATA_HOME, DB and TMUX_TMPDIR under /tmp/term-login-e2e, OS-chosen loopback port, PIPELINES_MDNS=off; two sessions planted on the scratch tmux -L pipelines first:

    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 pipelines
    

    The 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).