Merge branch 'worktree-agent-a2b0140029ece13b5'
This commit is contained in:
+139
-39
@@ -1,8 +1,11 @@
|
||||
# Permanent terminal (bottom panel / floating window)
|
||||
|
||||
A full terminal available from every destination, independent of chats. It
|
||||
keeps running when the panel is hidden, the app navigates or reloads, and
|
||||
(where tmux is installed) across Pipelines server restarts.
|
||||
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
|
||||
|
||||
@@ -10,8 +13,16 @@ keeps running when the panel is hidden, the app navigates or reloads, and
|
||||
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. Opening it with no terminal yet (once
|
||||
every machine's list has arrived) starts one, as New terminal does.
|
||||
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):
|
||||
@@ -67,7 +78,7 @@ keeps running when the panel is hidden, the app navigates or reloads, and
|
||||
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
|
||||
shell (and its tmux session).
|
||||
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.
|
||||
@@ -76,7 +87,7 @@ keeps running when the panel is hidden, the app navigates or reloads, and
|
||||
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 (new stream) is read again from its start.
|
||||
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
|
||||
@@ -91,8 +102,9 @@ keeps running when the panel is hidden, the app navigates or reloads, and
|
||||
terminals"). Body `terminal_request {terminal_id?, cwd?, cols?, rows?,
|
||||
data?, after?}`.
|
||||
|
||||
- `terminal_open {cwd, cols, rows}` → `terminal` (subscribes the
|
||||
connection to its output first).
|
||||
- `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),
|
||||
@@ -106,54 +118,73 @@ data?, after?}`.
|
||||
title, exited, closed) to every connection. A slow connection's queue
|
||||
(256 frames) drops output; the client sees the offset gap and re-reads.
|
||||
|
||||
## Persistence
|
||||
## Login and lifetime (server)
|
||||
|
||||
- **tmux present** (looked up on PATH, then /opt/homebrew/bin,
|
||||
/usr/local/bin, /usr/bin): each shell is `$SHELL -l` (else `/bin/sh`) as
|
||||
the only pane of session `pipelines-<id>` on a Pipelines-owned tmux
|
||||
server, `tmux -L pipelines -f /dev/null` (never the operator's own server
|
||||
or config; `TMUX`/`TMUX_PANE` are stripped). Options: status off, mouse
|
||||
on (wheel scrolls tmux history), history-limit 10000, escape-time 10,
|
||||
set-titles on with the pane title. The server shows it through an
|
||||
ordinary `attach-session` client in a PTY (creack/pty, the chat shell's
|
||||
`startChatShellTerminal`). On shutdown the client gets SIGHUP and the
|
||||
session stays; on start `recover` lists the DB's running terminals and
|
||||
reattaches each whose session is alive (a fresh output stream: tmux
|
||||
redraws the screen). A client that exits while its session lives is
|
||||
replaced (up to 5 times).
|
||||
- **No tmux:** the shell is a direct child; it ends with the server and is
|
||||
listed as ended with the reason ("tmux is not installed on this
|
||||
machine"); running tabs say "This shell ends if the server on <machine>
|
||||
restarts (tmux is not installed there)".
|
||||
- DB table `terminals` (additive): id, title, cwd, shell, created_at, tmux,
|
||||
status, ended_at, exit_code, reason, cols, rows. Ended records beyond 16
|
||||
are pruned. Output stays in memory (1 MiB tail per terminal).
|
||||
- `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; any connection of that server may list, type into or
|
||||
close its terminals.
|
||||
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.
|
||||
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.
|
||||
- A tmux shell's exit status is not reported (only direct shells have it).
|
||||
- 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.
|
||||
- After a server restart the reattached output starts with tmux's redraw
|
||||
of the screen; older lines are in tmux's history (mouse wheel), not in
|
||||
the emulator's own scrollback.
|
||||
- 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.
|
||||
@@ -165,8 +196,9 @@ data?, after?}`.
|
||||
|
||||
- Server: `internal/protocol/terminal.go`, `message.go`;
|
||||
`internal/pipeline/terminals.go`, `store.go`;
|
||||
`internal/server/terminal_{manager,supervise,process,tmux,clients,title,cwd,handlers}.go`,
|
||||
`websocket.go`; tests `terminal_ws_test.go`, `terminal_restart_test.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`,
|
||||
@@ -291,3 +323,71 @@ Go 1.x / Flutter 3.44.6, macOS host, tmux 3.7c (/opt/homebrew/bin/tmux).
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user