shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/runtime-v2/02-pty.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 2 pending refine

runtime-v2 2 — PTY: a child that believes it owns a terminal

Part of Story — runtime-v2: the runtime beyond sockets. After 1: a streaming child whose stdio is a pseudo-terminal instead of pipes. A shell run over pipes disables its prompt, its line editing and its job control; a multiplexer is pointless without them.

The problem. Nothing can allocate a PTY pair, place the child on the slave side as its controlling terminal, or resize it. The reference reading is .dev/reference/tmux spawn.c + compat/fdforkpty.c (~450 lines of C covering five platforms; Linux alone is far smaller).

Info — the forks (open)

  1. Surface. A pty: true option on iteration 1's spawn verb (the lean — one spawn shape, two transports) versus a separate proc.spawn_pty.
  2. Resize. A verb on the handle (resize(cols, rows) → TIOCSWINSZ) — needed the moment 3 delivers SIGWINCH. The fork is only whether it ships here or with 3.
  3. The master fd's transport is settled by iteration 1's fork 2 — whatever won there carries the PTY master identically.
  4. Encoding edge. A PTY master delivers the child's output with tty post-processing (ONLCR and friends): raw the master by default versus expose termios knobs. Lean: raw, no knobs, until a consumer asks.

Acceptance sketch

  • A real shell spawned on a PTY prints a PROMPT (it never does over pipes) — asserted on the bytes.
  • Resize: the child (a script reading TIOCGWINSZ) observes the new size.
  • isatty inside the child answers yes on all three fds.
  • Kill/reap/stop legs identical to 1's, PTY edition; fd count flat.

Consumers

wmux 1 (every pane), the alacritty study's stage A (the headless expect-clone is exactly "spawn on a PTY, script it, assert").