writeonce/docs/superpowers/plans/2026-09-01-bounded-subprocess.md

# Bounded Subprocess (iteration 42) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use
> superpowers:subagent-driven-development (recommended) or
> 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 implementation or test code
> blocks. Each step names the exact functions, fields, ids and expected
> outcomes; the implementer writes the code at the keyboard, matching the
> anchors cited here.

**Goal:** `proc.run` becomes bounded (deadline, output caps, per-shard
ceiling, owner-bound reaping) and parked (fiber waits, shard never stalls),
plus an extended `proc.run_dl` stating bounds per call.

**Architecture:** rework `WO_B_PROC_RUN` in `runtime/src/sysio.c` from
blocking drain + `waitpid` into the iteration 35 `_dl` parking mould: after
the fork, the two pipe read ends and a pidfd for the child are bundled
behind one epoll fd; the fiber parks on that bundle fd with the existing
`fb->dl_active`/`fb->dl_at` deadline sweep armed; re-entry after each wake
drains whatever is ready into growable capped buffers, and the pidfd firing
means reap-and-return. A per-shard child registry in `wo_vm` carries the
cross-park state and serves the ceiling, engine-stop kill, and unwind
cleanup.

**Tech Stack:** C (runtime), OCaml (compiler stdlib table), `.wo` (example
app), bash (gate script), just (recipes).

**Spec:** `docs/superpowers/specs/2026-09-01-bounded-subprocess-design.md`
— the plan argues from it; read both.

## Global Constraints

- Linux only; pidfd needs runtime kernel ≥ 5.3 (Ubuntu 22.04 ships 5.15).
- glibc 2.35 (the release build floor) has NO `pidfd_open` /
  `pidfd_send_signal` wrappers (they arrived in 2.36) — call both via raw
  `syscall(SYS_pidfd_open, …)` / `syscall(SYS_pidfd_send_signal, …)`.
- Defaults, verbatim from the spec: deadline 30 000 ms, stdout cap
  1 048 576 bytes, stderr cap 65 536 bytes, ceiling 32 children per shard.
- Bound violations kill the child and trap as `WO_T_IO` with a message
  naming the bound and its value; silent truncation is removed.
- New builtin id: `WO_B_PROC_RUN_DL = 96` (89/90 stay iteration 31's
  reserved holes). No `.wob` version bump — `WOB_VERSION` does not move.
- No new dependencies, no new threads, no signal handlers.
- All work on `dev`; every commit title prefixed `feat(lang42):` /
  `fix(lang42):` / `docs(lang42):`; bullet-point commit bodies, ≤25 lines.
- Builds and tests only through just recipes: `just wovm-build`,
  `just wovm-test`, `just woc-build`, `just woc-test`.
- Runtime test binaries build with ASan+UBSan (runtime/Makefile does this
  for every `test/test_*.c` automatically) — a leak or race is a failure.

---

### Task 1: claim the prefix, commit the standing docs

**Files:**
- Modify: `docs/00-git-commit-history.md` (prefix registry table)
- Already-edited, to commit: story 42, spec, `docs/stories/00-status.md`
  row, `docs/00-dependency-graph.md` node, the three exploration studies
  under `docs/plan/exploration/{alacritty,tmux,zen-browser}/`, this plan.

**Interfaces:** none — bookkeeping.

- [ ] **Step 1:** Add a `lang42` row to the prefix registry table in
  `docs/00-git-commit-history.md`: feature "iteration 42 — bounded
  subprocess (proc.run bounded + parked, proc.run_dl)", status "on `dev`".
- [ ] **Step 2:** Commit all listed docs as one
  `docs(lang42): story, spec and plan for bounded subprocess` commit
  (bullets: story+spec+plan added; board row; graph node; the three
  parity studies that motivated it).

### Task 2: baseline suite — pin what `proc.run` already does

**Files:**
- Create: `runtime/test/test_proc.c` (auto-picked by the Makefile's
  `$(wildcard test/test_*.c)` — no build wiring needed)

**Interfaces:**
- Consumes: the test harness macros in `runtime/test/t.h` (`T_EQ`,
  `T_CHECK`), `wo_db_init`-style setup patterns from `test_builtin.c`, and
  direct builtin dispatch the way `test_builtin.c` invokes cases — operands
  in registers, `WO_B_PROC_RUN` (id 56) takes cmd Text, `multi Text` args,
  and the Proc class id, returns the record {code, out, err}.
- Produces: `test_proc.c` as the home for every later runtime leg.

- [ ] **Step 1:** Write three green legs against CURRENT behavior, copying
  `test_builtin.c`'s VM/fiber setup: (a) a child that exits 0 with known
  stdout — assert code 0 and the exact bytes; (b) a child that exits with a
  known nonzero code — assert the code; (c) a nonexistent command — assert
  code 127 (the execvp-failed convention already in the code).
- [ ] **Step 2:** `just wovm-test` — all three legs pass, whole suite
  stays green, ASan clean.
- [ ] **Step 3:** Commit `feat(lang42): pin proc.run's current contract in
  test_proc`.

### Task 3: the parked rework — pidfd + epoll bundle + registry

The core task. The suspected sequential-drain deadlock is proven first,
then dissolved by the rework.

**Files:**
- Modify: `runtime/src/sysio.c` (the `WO_B_PROC_RUN` case, currently
  ~lines 723–815)
- Modify: `runtime/src/vm.h` (the per-shard registry in `wo_vm`, one
  pointer field on `wo_fiber` for the in-flight entry)
- Modify: `runtime/src/vm.c` (engine-stop sweep over the registry)
- Test: `runtime/test/test_proc.c`

**Interfaces:**
- Consumes: `WO_SYS_PARKED` re-entry convention (`sysio.c:510` READ_DL is
  the model: fill `fb->park_fd`, arm `fb->dl_active`/`fb->dl_at` once —
  guarded so re-entry does not re-arm — return `WO_SYS_PARKED`; the plane
  re-runs the builtin on wake); `stop_pending()`; `wo_str_new`.
- Produces: a registry entry type (name it `wo_child`) holding pid, pidfd,
  the bundle epoll fd, both pipe fds, two growable buffers with their caps,
  the deadline, and the owning fiber pointer; `wo_vm` gains a fixed array
  of 32 `wo_child` slots plus a live count; `wo_fiber` gains a pointer to
  its in-flight entry (NULL when none). Task 4–8 legs and Task 9's
  `WO_B_PROC_RUN_DL` all reuse exactly this machinery.

- [ ] **Step 1 (the red test):** In `test_proc.c`, add the deadlock leg: a
  child (use `sh -c` in the test only) that writes ~200 KiB to stdout and
  one line to stderr, stderr kept open until stdout completes. Guard the
  leg with a wall-clock check: it must complete within 5 s. Under the
  current sequential drain the parent stops reading stdout at 8,192 bytes,
  the child blocks on a full pipe, and stderr never reaches EOF.
- [ ] **Step 2:** `just wovm-test` — the new leg FAILS (hangs into the
  guard) while everything else stays green. This is the bug proven.
- [ ] **Step 3 (the rework):** Rewrite the `WO_B_PROC_RUN` case: pipes
  opened `O_NONBLOCK` on the parent side; after the fork,
  `syscall(SYS_pidfd_open, pid, 0)`; create one epoll fd and register both
  pipe read ends and the pidfd; claim a registry slot (fail closed with
  `WO_T_IO` naming the 32-per-shard ceiling if none — the message text the
  Task 6 leg asserts); stash caps and buffers in the slot, point the fiber
  at it. First entry and every re-entry then run the same drain: read each
  ready pipe into its growable buffer; a buffer passing its cap means kill
  (`syscall(SYS_pidfd_send_signal, pidfd, SIGKILL, 0, 0)`), reap, release
  the slot, trap `WO_T_IO` naming the cap and value. Pidfd readable means
  exited: reap via `waitpid` (now non-blocking — the pidfd said so), do a
  final drain of both pipes to EOF (bounded by the caps), release, build
  the Proc record exactly as today. Nothing ready and child alive: park on
  the bundle fd with the deadline armed (30 000 ms default), return
  `WO_SYS_PARKED`. Deadline re-entry with `dl_at` passed: kill, reap,
  release, trap `WO_T_IO` naming the deadline. `stop_pending()` on any
  entry: kill, reap, release, return `WO_SYS_STOPPED`.
- [ ] **Step 4:** Engine-stop sweep: where `vm.c`'s worker loop observes
  the stop flag, kill + reap every live registry entry on that shard —
  covers fibers that never get rescheduled.
- [ ] **Step 5:** `just wovm-test` — deadlock leg green, Task 2 baseline
  legs still green (same results from the parked path), suite ASan clean.
- [ ] **Step 6:** Commit `feat(lang42): proc.run parks — pidfd + epoll
  bundle + child registry` (bullets: the deadlock repro and its dissolve;
  raw syscalls because glibc 2.35).

### Task 4: the deadline leg

**Files:** Test: `runtime/test/test_proc.c`; fix (if red exposes drift):
`runtime/src/sysio.c`.

**Interfaces:** consumes Task 3's machinery unchanged; the leg drives the
default arming path.

- [ ] **Step 1 (red first if Task 3 left a gap):** a child sleeping 10 s,
  run with the deadline forced low for the test (drive the builtin with a
  small `dl` the way the harness passes operands — until Task 9 the
  extended operands are reachable only from C, which is fine here). Assert:
  the trap message names the deadline and its value; then assert the pid is
  GONE — `kill(pid, 0)` returns ESRCH — measured, not assumed.
- [ ] **Step 2:** `just wovm-test` green (implement/adjust the kill path if
  Step 1 caught drift). Also add the fiber-progress assertion: while the
  sleeping child runs, a second fiber on the same VM increments a counter —
  assert it advanced before the deadline fired (the shard was never
  blocked).
- [ ] **Step 3:** Commit `feat(lang42): deadline kills, parked shard keeps
  scheduling`.

### Task 5: the output-cap leg

**Files:** Test: `runtime/test/test_proc.c`; fix: `runtime/src/sysio.c`.

- [ ] **Step 1:** a child writing unbounded output against a small stdout
  cap passed from the harness. Assert: `WO_T_IO` whose message names the
  cap and its value; pid gone (ESRCH); and — fd hygiene — the shard's open
  fd count returns to its pre-call value (count `/proc/self/fd` entries
  before and after).
- [ ] **Step 2:** Same for the stderr cap.
- [ ] **Step 3:** `just wovm-test` green. Commit `feat(lang42): output caps
  refuse by name, no truncation`.

### Task 6: the ceiling leg

**Files:** Test: `runtime/test/test_proc.c`.

- [ ] **Step 1:** 32 fibers each spawn a child sleeping 2 s; a 33rd spawn
  must trap `WO_T_IO` naming the ceiling while the 32 keep running to
  completion unharmed. Then all 32 complete with code 0.
- [ ] **Step 2:** `just wovm-test` green (the slot-claim refusal exists
  since Task 3; this pins it). Commit `feat(lang42): per-shard ceiling
  fails closed at 32`.

### Task 7: the churn leg — fds flat over a thousand runs

**Files:** Test: `runtime/test/test_proc.c`.

- [ ] **Step 1:** loop one thousand sequential short-lived children
  (the iteration 24 measurement style): record the `/proc/self/fd` entry
  count before, assert the count after equals it, and assert no registry
  slot remains claimed.
- [ ] **Step 2:** `just wovm-test` green. Commit `feat(lang42): a thousand
  spawns leave the fd table flat`.

### Task 8: stop and unwind reap their children

**Files:** Test: `runtime/test/test_proc.c`; fix: `runtime/src/sysio.c`,
`runtime/src/vm.c`.

- [ ] **Step 1:** park a fiber on a child sleeping 10 s, set the stop flag
  the way `test_fiber.c` does, drive the loop; assert `WO_SYS_STOPPED`
  surfaced AND the child pid is gone. Second leg: a child owned by a fiber
  that is unwound (the `test_unwind.c` pattern) is also gone.
- [ ] **Step 2:** `just wovm-test` green. Commit `feat(lang42): stop and
  unwind kill the children they own`.

### Task 9: `proc.run_dl` — the per-call bounds surface

**Files:**
- Modify: `runtime/src/wob.h` (enum entry `WO_B_PROC_RUN_DL = 96`, comment
  stating the operand order and the nil-never contract: bounds violations
  trap, they do not nil)
- Modify: `runtime/src/sysio.c` (a thin case: parse deadline_ms, out_cap,
  err_cap operands, then fall into Task 3's core with those instead of the
  defaults)
- Modify: `compiler/src/types.ml:315` region (one row beside `proc.run`:
  module `proc`, member `run_dl`, arity 5, id 96, same nullable-Proc
  return and Proc record class as the existing row)
- Test: `runtime/test/test_proc.c` (drive id 96 with explicit bounds);
  compiler: `just woc-test` must stay green — the generic builtin path
  needs no `emit.ml` change (the net `_dl` family at ids 91–93 landed with
  table rows alone; verify by reading their absence from `emit.ml` before
  assuming).

**Interfaces:**
- Produces: `proc.run_dl(cmd, args, deadline_ms, out_cap, err_cap)` in the
  language, the name the example app and every future consumer calls.

- [ ] **Step 1 (red):** runtime leg driving id 96 with a tight explicit
  deadline — fails while the case is absent.
- [ ] **Step 2:** add the wob.h entry and the sysio.c case; green.
- [ ] **Step 3:** add the types.ml row; `just woc-build && just woc-test`
  green.
- [ ] **Step 4:** Commit `feat(lang42): proc.run_dl — deadline and caps at
  the call site`.

### Task 10: the example app and its gate

**Files:**
- Create: `docs/examples/subprocess/` (wo.toml + one `.wo` source: an
  actor that serves `proc.run`/`proc.run_dl` results — a fast command, a
  deliberate deadline hit caught with try/catch, a deliberate cap hit
  caught, and a long-running child for the drain leg; logs to
  `/tmp/subprocess.log` per the examples convention, announced and
  banner-separated)
- Create: `scripts/subprocess-accept.sh` (the gate)
- Modify: `justfile` (recipe `subprocess` running the gate, in the
  `residency`/`site` recipe mould)

**Interfaces:**
- Consumes: `proc.run` and `proc.run_dl` exactly as Task 9 shipped them.

- [ ] **Step 1:** write the app and gate with these legs: fast command
  returns its output through the actor; deadline violation is caught in
  `.wo` and reported (proves catchability from the language, not just from
  C); cap violation likewise; concurrency — a slow child runs while a
  second request is answered (wall-clock assertion that the second answer
  did not wait for the child); SIGTERM while a `sleep 30` child lives —
  the gate records the child pid, stops the app, asserts the app exited
  cleanly AND the child pid is gone (iteration 40's battery gains its
  subprocess leg here).
- [ ] **Step 2:** `just subprocess` — all legs green, printed as
  `subprocess-accept: N checks, 0 failures`.
- [ ] **Step 3:** Commit `feat(lang42): subprocess example + gate` (app,
  script, recipe).

### Task 11: close-out

**Files:**
- Modify: `runtime/src/CODE-LOGIC.md` (the proc.run section: parked
  lifecycle, the registry, the raw-syscall note, the deadlock that was)
- Modify: `docs/stories/language-runtime-database/42-bounded-subprocess.md`
  (frontmatter `status: done`; Progress note of what landed vs the spec)
- Modify: `docs/stories/00-status.md` (NEXT PLAN entry answering the six
  standup questions — implemented, key findings measured, learned,
  unblocked (the streaming form, tmux/alacritty/zen stages), next steps,
  `.dev/reference` used: alacritty/tmux/zen-browser; flip the pending row)
- Modify: `docs/00-dependency-graph.md` (node 42 class → done, same change
  as the board row per the maintenance rule)

- [ ] **Step 1:** run the full belt: `just wovm-test`, `just woc-test`,
  `just subprocess`, plus `just site` untouched-but-verified. All green,
  outputs quoted in the board entry, not asserted.
- [ ] **Step 2:** write CODE-LOGIC.md beside the code (project rule) and
  the three doc updates.
- [ ] **Step 3:** Commit `docs(lang42): close out iteration 42`.

---

## Self-review (done at write time)

- Spec coverage: every acceptance criterion has a task — normal exit (2),
  deadlock repro-then-fix (3), deadline + progress (4), caps (5), ceiling
  (6), fd-flat thousand (7), stop/unwind (8), per-call bounds (9), drain
  leg + example gate (10). Out-of-scope items appear in no task.
- Placeholders: none; every step names its files, ids, messages and
  expected outcomes.
- Consistency: registry type `wo_child`, bundle-epoll park, id 96, caps
  30 000 ms / 1 MiB / 64 KiB / 32 used identically in tasks 3–10.
- One verify-before-assuming flag left deliberately in Task 9: confirm the
  net `_dl` rows needed no `emit.ml` change before mirroring them.