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 6e997759e5 docs(rt2): close out runtime-v2 1-5 
- five stories status: done; 00-story records the one-run landing
- spec History: three implementation amendments (Signal record not
  scalar, caller-owned stdio fds, handler-latch instead of signalfd)
- board NEXT PLAN entry with measured findings (zero transport code
  added; the tty-across-the-socket handover proven; the double-raw
  refusal restoring the terminal — the "bug" that was the design
  working); section rows flipped; graph nodes green
- CODE-LOGIC.md: the runtime-v2 section
- full belt quoted on the board: suites 0 fail both flavors (test_proc
  193/0, test_term 60/0), woc 557/0, subprocess 12/0, site 23/0

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

1.8 KiB
Raw Blame History

track iteration status readiness
runtime-v2 4 done ready

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, settled (brainstorm 2026-09-01; spec:

2026-09-01-runtime-v2-design.md)

  1. Exactly two verbs: term.raw(fd) and term.restore(fd). Saved termios live in a per-shard table keyed by fd (one thread — no locks); double-raw on one fd refuses by name; no flag knobs.
  2. Restore is a RUNTIME OBLIGATION. Fiber unwind, engine stop and wo_vm_destroy restore every saved tty, newest first — "no orphan" has its terminal-state sibling: no wrecked tty, ever, trap paths included.
  3. fd-taking from day one — a tty received via 5 works without the verb growing an argument 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.