writeonce/docs/superpowers/plans/2026-09-01-runtime-v2.md

# runtime-v2 (iterations 1–5) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use
> superpowers:executing-plans to implement this plan task-by-task. Steps
> use checkbox (`- [ ]`) syntax for tracking.
>
> **Project rule (overrides the plan-skill template):** plan docs carry
> concept, reason and actions in words — no code blocks. Steps name exact
> functions, ids, fields and expected outcomes; the implementer writes
> the code at the keyboard against the cited anchors.

**Goal:** land all five runtime-v2 iterations — streaming subprocess,
PTY, signals-as-events, termios adoption, fd passing — as builtins on the
existing park plane, per the track spec.

**Architecture:** acquisition verbs only, never transport: children and
received fds are ordinary fds the existing `net.read_dl`/`write_dl`/
`close` drive. The `wo_child` registry grows a streaming variant; a
per-shard termios table and shard-0 signalfd are the only new state.

**Tech Stack:** C (runtime), OCaml table rows (compiler), `.wo` +
bash (gate legs).

**Spec:** `docs/superpowers/specs/2026-09-01-runtime-v2-design.md`.

## Global Constraints

- Ids 97–107, in this order: 97 `PROC_SPAWN`, 98 `PROC_WAIT_DL`,
  99 `PROC_SIGNAL`, 100 `PROC_SPAWN_PTY`, 101 `PROC_RESIZE`,
  102 `SIGNAL_ON`, 103 `TERM_RAW`, 104 `TERM_RESTORE`, 105 `NET_SEND_FD`,
  106 `NET_RECV_FD`, 107 `NET_CONNECT_UNIX`. `WO_B_MAX` → 107. No `.wob`
  bump.
- Every id = FOUR registrations: `wob.h` enum, `loader.c` `b_arity`,
  `builtin.c` dispatch range (extend the `<= WO_B_PROC_RUN_DL` bound to
  `<= WO_B_NET_CONNECT_UNIX`), `types.ml` row. The 42 lesson.
- **Spec amendment 1 (verified 2026-09-01):** message payloads are
  unconditionally `wo_drop_obj`'d (`vm.c:887`, `actor_die`,
  `actor_activate`) — a scalar payload is a crash. `signal.on` therefore
  delivers a fresh predeclared `Signal {sig Int}` record per delivery,
  class id appended by the compiler (loader arity 3). Record the
  amendment in the spec's History when closing.
- **Spec amendment 2:** a streaming slot does NOT own the caller-visible
  stdio fds (fd-reuse hazard: the sweep could close a recycled number).
  The caller owns Child.in/out/err and closes them with `net.close`; the
  slot owns pid + pidfd + (PTY only) a private `dup` of the master for
  resize. Sweep = kill, reap, close pidfd (+ master dup).
- PTY via `posix_openpt`/`grantpt`/`unlockpt`/`ptsname_r` — plain libc,
  NO `-lutil`, no Makefile change.
- Raw syscalls where glibc 2.35 lacks wrappers (pidfd already handled);
  `signalfd` has a wrapper since 2.8 — use it.
- SIGTERM/SIGINT registration refused by name; the stop latch stays the
  engine's.
- All work on `dev`, commits prefixed `feat(rt2):`/`docs(rt2):`; builds
  and tests only via just recipes; ASan+UBSan clean is a gate.
- Suite home: `runtime/test/test_proc.c` grows spawn/wait/pty legs; new
  `runtime/test/test_term.c` for termios + signals + fd-passing (auto-
  globbed).

---

### Task 1: streaming spawn — `proc.spawn`, `proc.wait_dl`, `proc.signal` (rt2 iteration 1)

**Files:**
- Modify: `runtime/src/wob.h` (ids 97–99), `runtime/src/loader.c`
  (arities: spawn 3 — cmd, argv, cls; wait_dl 2; signal 2),
  `runtime/src/builtin.c` (dispatch bound), `runtime/src/sysio.c`
  (three cases + slot changes), `runtime/src/vm.h` (`wo_child` gains
  `streaming`, `waiter`, `master_dup` fields), `runtime/src/vm.c`
  (`actor_die` sweeps children owned by the dying actor),
  `compiler/src/types.ml` (`Child` record — id/in/out/err, all Int —
  in `stdlib_records`; rows for the three verbs).
- Test: `runtime/test/test_proc.c`.

**Interfaces:**
- Produces: `proc.spawn(cmd, args) -> ?Child`, `proc.wait_dl(id, ms) ->
  ?Int`, `proc.signal(id, sig) -> 0`; slot ownership field
  `owner_actor` (a `wo_actor*`, NULL = program) that Tasks 2–5 reuse.

- [ ] **Step 1 (red):** legs in `test_proc.c` driving the new ids from
  bytecode: (a) spawn `cat`, `net.write_dl` a line to `Child.in`, read
  it back from `Child.out` via `net.read_dl` — the echo round trip;
  (b) `wait_dl` on a fast child answers its code, on a `sleep 10` with
  ms=100 answers nil and the child is STILL alive (then `proc.signal`
  SIGKILL, wait again, code observed, ECHILD after vm destroy);
  (c) second concurrent `wait_dl` on one id refuses by name (two
  fibers); (d) spawn-loop fd-flat leg with the caller closing all three
  fds each round. Run `just wovm-test` — all four fail (unknown builtin).
- [ ] **Step 2 (green):** implement. Spawn: three pipes (stdin write end
  stays parent-side as Child.in), parent ends `O_NONBLOCK`, fork/execvp
  (argv rules identical to 42's), pidfd, claim slot (`streaming = 1`,
  no epoll bundle, no buffers), owner = `vm->cur->actor` (NULL when
  none), build the Child record via `record_of` (4 fields). `wait_dl`:
  slot lookup by id (id = slot index + a generation counter to refuse a
  stale id by name), waiter-claim refusal, park on the pidfd with
  `dl_active`/`dl_at`, on exit reap + release slot + answer code, nil at
  deadline (child untouched). `signal`: `pidfd_send_signal` through the
  slot. `actor_die` calls a new `wo_proc_abandon_actor(vm, a)` killing
  every slot whose owner is `a`. Sweeps close pidfd only (amendment 2).
- [ ] **Step 3:** `just wovm-test` green both flavors; commit
  `feat(rt2): proc.spawn/wait_dl/signal — the streaming child` with the
  compiler row in the same commit (`just woc-build && just woc-test`
  first).

### Task 2: PTY — `proc.spawn_pty`, `proc.resize` (rt2 iteration 2)

**Files:** same four registration files (ids 100–101; spawn_pty arity 5
— cmd, argv, cols, rows, cls; resize 3), `runtime/src/sysio.c`,
`runtime/test/test_proc.c`.

**Interfaces:**
- Consumes: Task 1's slot, Child record, ownership.
- Produces: `proc.spawn_pty(cmd, args, cols, rows) -> ?Child` (in==out=
  master, err nil), `proc.resize(id, cols, rows) -> 0`.

- [ ] **Step 1 (red):** legs: (a) spawn_pty `sh -c 'test -t 0 && echo
  yes-tty'` — read "yes-tty" back (isatty proof); (b) spawn_pty with
  24x80 then a child running `stty size` — read "24 80"; resize to
  40x120, re-ask via a second child? No — one child that sleeps then
  prints size after a marker write; simpler: child = `sh -c 'read x;
  stty size'` — resize between spawn and the marker write, expect
  "40 120"; (c) resize on a Task-1 pipe child refuses by name. Red run.
- [ ] **Step 2 (green):** `posix_openpt(O_RDWR|O_NOCTTY)`, `grantpt`,
  `unlockpt`, `ptsname_r`; child: `setsid`, open slave (becomes
  controlling tty), dup2 onto 0/1/2, `TIOCSWINSZ` initial size, exec.
  Parent: master `O_NONBLOCK`, slot stores a private `dup` of the master
  (`master_dup`) for resize; Child.in == Child.out == master, err = 0
  (nil). Resize: `ioctl(master_dup, TIOCSWINSZ)` + refusal by name when
  the slot is not a PTY child. Sweep closes `master_dup`.
- [ ] **Step 3:** suites green; commit `feat(rt2): spawn_pty + resize —
  a child that believes it owns a terminal`.

### Task 3: signals as events — `signal.on` (rt2 iteration 3)

**Files:** registrations (id 102, arity 3 — sig, addr, cls),
`runtime/src/sysio.c` or `builtin.c` for the case, `runtime/src/park.c`
(signalfd on shard 0's plane beside the wake eventfd, sentinel
user_data), `runtime/src/vm.h` (per-vm subscription list {sig, actor}),
`compiler/src/types.ml` (`Signal {sig Int}` record + row),
`runtime/test/test_term.c` (new).

**Interfaces:**
- Consumes: `runtime_notify` (`vm.c:1326`, the timer delivery path) for
  handing a fresh payload to an actor.
- Produces: `signal.on(sig, addr) -> 0`; delivery = fresh `Signal{sig}`
  record per arrival (spec amendment 1).

- [ ] **Step 1 (red):** test_term.c: module with an actor whose receive
  pushes `msg.sig` into a shared multi; main registers
  `signal.on(SIGUSR1, addr)`, then `proc.run("sh", ["-c", "kill -USR1
  $PPID"])`, then sleeps briefly; assert the multi holds SIGUSR1's
  number. Second leg: `signal.on(SIGTERM, …)` refuses naming the stop
  latch. Red.
- [ ] **Step 2 (green):** first registration on shard 0 creates the
  signalfd (mask grows per registration; `pthread_sigmask` blocks the
  sig process-wide first — document: registration must happen before
  worker shards spawn or the mask is per-thread incomplete; v1 rule:
  register from shard 0/main, refusal by name elsewhere). park.c: the
  signalfd is registered like the wake eventfd (oneshot POLL_ADD under
  uring, level under epoll) with its own sentinel; on readiness drain
  `signalfd_siginfo` records, for each match allocate `Signal{sig}` via
  `wo_obj_new` and `runtime_notify` the subscribed actor(s).
- [ ] **Step 3:** suites green (both WO_IO backends — the fibers gate
  pattern proves uring AND epoll); commit `feat(rt2): signal.on —
  signalfd delivers Signal records to actors`.

### Task 4: termios — `term.raw`, `term.restore` (rt2 iteration 4)

**Files:** registrations (ids 103–104, arity 1 each),
`runtime/src/sysio.c` (cases + the per-shard saved-termios table in
`wo_vm` — 8 entries {fd, termios, owner fiber}), `runtime/src/vm.c`
(restore sweep in `fib_reap` and `wo_vm_destroy` beside the proc
sweeps), `runtime/test/test_term.c`.

- [ ] **Step 1 (red):** legs using a PTY pair made in the TEST via
  `posix_openpt` (C-side, no builtin): (a) `term.raw(slave_fd)` then
  `tcgetattr` shows ECHO/ICANON cleared; `term.restore(slave_fd)`
  brings the saved flags back bit-identically; (b) double-raw refuses by
  name; (c) raw then DELIBERATE trap in the fiber — after the trap the
  fd's termios are restored (the runtime obligation); (d) restore on an
  fd never raw'd refuses by name. Red.
- [ ] **Step 2 (green):** table claim (full table refuses by name),
  `tcgetattr` save, `cfmakeraw`, `tcsetattr`; restore verb frees the
  entry; `fib_reap` and `wo_vm_destroy` restore entries owned by the
  dying fiber / all, newest first.
- [ ] **Step 3:** suites green; commit `feat(rt2): term.raw/restore —
  no wrecked tty, ever`.

### Task 5: fd passing — `net.send_fd`, `net.recv_fd`, `net.connect_unix` (rt2 iteration 5)

**Files:** registrations (ids 105–107; arities 2/1/1),
`runtime/src/sysio.c`, `runtime/test/test_term.c`.

- [ ] **Step 1 (red):** legs: (a) `net.listen_unix` + `net.connect_unix`
  pair inside one vm (two fibers: acceptor and connector); (b) create a
  pipe in C, `send_fd` its read end across the socket, `recv_fd` it,
  write into the pipe's write end, `net.read_dl` from the RECEIVED fd
  answers the bytes; (c) `send_fd` on a TCP socket refuses by name;
  (d) `recv_fd` when the peer sent plain bytes answers nil; (e) a tty
  fd (test PTY slave) crosses and `term.raw` works on it — the wmux
  handover in miniature. Red.
- [ ] **Step 2 (green):** `connect_unix`: socket AF_UNIX, connect,
  `O_NONBLOCK` after. `send_fd`: `SO_DOMAIN` check (refusal), `sendmsg`
  with one `SCM_RIGHTS` fd in a fixed `CMSG_SPACE(sizeof(int))` buffer
  and one sentinel data byte; EAGAIN parks (POLLOUT, the write mould).
  `recv_fd`: `recvmsg` with the same buffer; EAGAIN parks (POLLIN);
  a message without ancillary fd answers nil; received fd set
  `O_NONBLOCK`.
- [ ] **Step 3:** suites green; commit `feat(rt2): send_fd/recv_fd/
  connect_unix — an fd crosses the socket`.

### Task 6: close-out

**Files:** `runtime/src/CODE-LOGIC.md` (runtime-v2 section),
`docs/superpowers/specs/2026-09-01-runtime-v2-design.md` (History —
the two amendments), the five story files (status: done + Progress),
`docs/stories/00-status.md` (NEXT PLAN entry, section rows ✅),
`docs/00-dependency-graph.md` (nodes → done class).

- [ ] **Step 1:** full belt: `just wovm-test`, `just woc-test`,
  `just subprocess`, `just site` — quote results, never assert.
- [ ] **Step 2:** write the docs; commit `docs(rt2): close out
  runtime-v2 1–5`.

---

## Self-review (at write time)

- Spec coverage: every surface row has a task; both amendments carried
  into Tasks 1 and 3 and recorded for the spec's History in Task 6.
  Out-of-scope items appear in no task.
- Ids consistent 97–107 across tasks; `Child`/`Signal` records named
  identically throughout.
- Deliberate verify-first flags: the shard-0-only registration rule for
  signals (mask is per-thread — confirm where worker threads inherit
  the mask), and `runtime_notify`'s exact signature before reuse.