# 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 ` 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 -c '