shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/runtime-v2/04-termios.md
shoney.arickathil ab8ef64cd9 docs(rt2): runtime-v2 track — the runtime beyond sockets 
- five stories under docs/stories/runtime-v2/: 1 streaming subprocess
  (42's follow-up; five forks incl. the mailbox-cap collision), 2 PTY,
  3 signals-as-events (signalfd lean), 4 termios adoption, 5 SCM_RIGHTS
  fd passing; 00-story states the arc — the plane learned sockets in
  8/11/35, files in 6, this adds processes/terminals/signals
- build order 1 -> 2 -> 3; 4 and 5 startable alone; all readiness:
  refine, brainstormed on demand
- board: Five tracks; "▸ runtime-v2" pending section; wmux section now
  points at it; graph section 6 nodes carry runtime-v2 numbers + links
- wmux stories re-reference the track; prefix `rt2` claimed
- linkcheck: 0 broken

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
(cherry picked from commit e0451cb4889bb3d03429c0276d03c090269a5ced)
2026-09-15 01:15:30 +02:00

1.9 KiB
Raw Blame History

track iteration status readiness
runtime-v2 4 pending refine

runtime-v2 4 — termios adoption: raw mode on a terminal we were given

Part of Story — runtime-v2: the runtime beyond sockets. No incoming edges — startable alone, any time.

The problem. 2 creates terminals for children; this adopts the one the PROCESS was given. A wmux client must put its own stdin into raw mode (no echo, no line buffering, keys arrive as they are typed) and — non-negotiably — restore it on every exit path, including a trap. A terminal left raw is the classic way a program makes a user's shell unusable.

Info — the forks (open)

  1. Surface size. Exactly two verbs — term.raw() returning a restore token and term.restore(token) (the lean: wmux needs nothing else; tmux itself uses little more than cfmakeraw) — versus exposing termios flag knobs. YAGNI says two verbs and a refusal for the rest.
  2. Restore guarantee. Tie restoration to the unwind machinery (the 42 ownership pattern: fiber dies, terminal restored — a runtime obligation) versus caller's-problem-with-a-doc-note. Lean: runtime obligation; "no orphan" has a terminal-state sibling: no wrecked tty.
  3. Scope. stdin only, versus any tty fd (a client adopting a tty it received via 5 — the wmux SERVER's need). This fork decides whether the verb takes an fd argument now or grows one later.

Acceptance sketch

  • Raw on, keystroke arrives unbuffered and unechoed (driven under a 2 PTY in the test — the two iterations prove each other).
  • Restore: tcgetattr before equals after, on the normal path AND after a deliberate trap while raw.
  • The stop path restores too — SIGTERM while raw leaves a sane terminal.

Consumers

wmux 1's client half. The alacritty stage-A harness benefits but does not require it.