ADR 0017: pseudo-terminals and signal delivery
- Status: accepted (2026-10-22); amended 2026-10-23 with job control (below)
- Context: An interactive terminal (docs/terminal-plan.md, T2) needs what Linux gives a
program on a terminal:
isatty()true with a size, echo and line editing, raw mode for full-screen programs, Ctrl+C reaching the foreground job, and resize notifications. ClientVM’s stdio was pipes only, andkillterminated a worker without running handlers. So npm, which shows progress only on a terminal, printed nothing until it finished, and Ctrl+C could not reach a dev server’s cleanup code. - Decision:
- Signals are delivered. The kernel posts a signal to the process. Handlers
(
process.on('SIGINT'), a shelltrap) take it and acknowledge it; without one, the default action applies: ignore SIGCHLD and SIGWINCH, terminate on the rest (exit status 128 + n,signalset). A process that neither acknowledges nor exits within 1 s (stuck in JavaScript) is terminated by the kernel. SIGKILL, SIGPIPE and SIGXCPU stay immediate. A process ended by a signal still takes its descendants with it (ADR 0011). The known signals are now HUP INT QUIT KILL USR1 USR2 PIPE ALRM TERM CHLD XCPU WINCH. - A pseudo-terminal in the kernel.
spawn(cmd, args, { pty: { cols, rows } })starts a session on a new terminal: the process’s stdio is the terminal, all its output arrives onstdout, andstdinwrites are keystrokes. Its line discipline (kernel/src/pty.ts) does what Linux’s n_tty does by default: in cooked mode echo, erase, kill line, word erase, Ctrl+C → SIGINT and Ctrl+\ → SIGQUIT to the foreground, Ctrl+D → end of file (an empty chunk, so the terminal stays open for later reads), Enter →\n; in raw mode (setRawMode(true)) bytes pass through. Output gets ONLCR (\n→\r\n).Process.resize(cols, rows)updates every process on the terminal, then sends SIGWINCH to the foreground. - Process groups, simplified. A child joins its parent’s group and inherits the
controlling terminal; a stdio stream is the terminal when inherited from one. A shell’s
background job and
child_process.spawn({ detached: true })start a new group, which terminal signals and input skip. The foreground group is the session leader’s: there is notcsetpgrp, no stopping (Ctrl+Z, SIGTSTP) and no SIGTTIN. Input goes to the newest process in the foreground whose stdin is the terminal, sonodestarted from the shell reads keys while it runs and the shell reads them again afterwards. A process that set raw mode and exits leaves the terminal cooked. - node-compat:
isTTY,columns/rows,getWindowSize,getColorDepth/hasColors(Node’s FORCE_COLOR/NO_COLOR/TERM rules), the cursor methods,'resize'events,setRawMode/isRaw,tty.isatty, signal events onprocess,process.kill(process.pid),readline.emitKeypressEvents, and terminal-modereadline.Interface(raw mode, line editing, history, completer,SIGINTevent), diffed against Node intest/conformance/readline-differential.test.ts. Terminal sessions getTERM=xterm-256color. - Interactive shell:
bash -i, orsh/bashwithout a script when stdin and stderr are the terminal. PS1/PS2 with bash’s escapes (Ubuntu’s coloured default), line editing in raw mode with history in~/.bash_history, Tab completion of commands and paths, continuation lines, background jobs announced with[n] pidand[n]+ Done. Ctrl+C stops work running in the shell at once; for a foreground program the shell waits, and abandons the rest of the line only if the program died of the signal, as bash does.trapactions run on delivered signals in any shell. @clientvm/terminal’sattachShell(term, instance)connects an xterm.js-compatible terminal tobash -ion a pty.
- Signals are delivered. The kernel posts a signal to the process. Handlers
(
- Measured (headless Chromium, M-series Mac, production build): keystroke to echo at the
prompt, 5.3 ms median, 5.5 ms p95 (under one 16 ms frame). Ctrl+C to the next prompt for
sleep 30and fornode -e "setInterval(...)", about 12 ms. A process in its event loop acts on a signal on its next turn, so the 1 s grace period only matters for code that does not yield. - Consequences:
npm installon a terminal shows npm’s own progress spinner; tools that colour only on a TTY now do.execand the agent tools still use pipes, so tool results carry no colour codes.kill('SIGTERM')no longer ends a process synchronously: a handler can clean up (or ignore it, as on Linux).Instance.exectimeouts are unaffected unless the command traps SIGTERM.- The shell’s spawned children read the terminal directly (
stdin: 'inherit') instead of having input copied through the shell, but only on a terminal. Pipes behave as before. - Not yet: SIGTTIN (a background job that reads the terminal simply gets no input),
stty, akillcommand, and wide-character widths in line editing. Interactive sessions are diffed against real bash in a real PTY (pty-differential.spec.ts: both outputs are drawn by@xterm/headlessand the screens compared).
Amendment (2026-10-23): job control
Asked for in the roadmap, so the “no job control” simplification above is lifted:
- Stopping. SIGTSTP (Ctrl+Z in cooked mode, like
^C) and SIGSTOP stop a process, and SIGCONT continues it. A browser cannot pause a worker from outside, so a stopped process stops itself: its default action marks a slot in its syscall channel’s header, reportsstoppedto the kernel and blocks inAtomics.waiton that slot until the kernel’s SIGCONT clears it. SIGSTOP cannot be caught; SIGTSTP can. Other signals to a stopped process wait until it continues (no grace timer), except SIGKILL. A stopped process counts as waiting for the CPU watchdog, and terminal input skips it. - Process groups move.
child-setpgidputs a child and everything it started into the parent’s group (the terminal’s foreground) or a group of its own;child-killwithtreesignals a whole job. Parents hearchild-stoppedandchild-continued. - The interactive shell ignores SIGTSTP. A line whose programs stop becomes a Stopped job
(
[1]+ Stopped cmd,$?148); its programs leave the shell’s group, so the prompt’s input and Ctrl+C no longer reach them.fg [%n]moves a job back and waits for it (it can be stopped again);bg [%n]continues it in its own group;jobsshows Running/Stopped/Done. Exiting the shell hangs up stopped jobs and continues them so they can act on it. - Limits. A process that never returns to its event loop (a busy loop) cannot act on
SIGTSTP, as it cannot act on SIGINT; it is not stopped. Commands the shell runs in its own
worker (
sleep,cat,grep, …; ADR 0011) are not separate processes, so Ctrl+Z does not stop them; bash would stop its externalsleep. A job started with&and brought to the foreground withfgdoes not read the terminal (it was started without it).
Signals to a process blocked in a syscall
A process blocked in a synchronous syscall (execSync, spawnSync) cannot run a handler, and
the 1 s grace period used to end it even when it had one. The process now publishes the signal
numbers it catches in another slot of its channel header (node’s process listeners, the
shell’s traps, the interactive shell’s own). For a blocked process the kernel reads it: an
uncaught signal takes its default action at once, as on Linux; a caught one is delivered and
its grace period starts only once the call returns, so the handler runs then, as in Node.