TheWitness fcfd944a4a docs: enshrine script/process lifecycle design principles (#630) ...

## What
Adds a *Script and process execution design principles (do not regress)*
section to `.github/instructions/instructions.md` codifying three
invariants for script and PHP Script Server execution:

1. One read attempt per command, no looping to EOF.
2. Never block the polling thread in `waitpid()` — single non-blocking
WNOHANG attempt, then hand off to the async abandoned-pid sweep.
3. Script timeouts must go through `nft_popen()`/`nft_pchild()`
(pid-tracked), not a native `popen()`/`pclose()` fallback.

## Why
While investigating a reported poller slowdown, these three invariants
were each found violated: #614 turned `nft_pclose()` into a
bounded-but-blocking spin/sleep/SIGTERM/SIGKILL sequence on the polling
hot path, and 1.2.x's `nft_pclose()` has an unbounded blocking
`waitpid()` there. Writing this down so future AI-assisted changes don't
reintroduce either. Tracked in #632.

## What was tested
Docs-only change; no build/test impact.

Signed-off-by: TheWitness <thewitness@cacti.net>

2026-09-24 09:40:52 -05:00

..

instructions.md

docs: enshrine script/process lifecycle design principles (#630)

2026-09-24 09:40:52 -05:00