Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Run gate steps in their own session, tied to a lifeline (#6300)

Nick Gomez4b9b457709e1
diff --git a/AGENTS.md b/AGENTS.md
index 02d07cec6..07cd3aa6e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,7 +51,7 @@ pnpm run dev
## Process safety
-Never signal a pid you did not spawn. Signal a held `ChildProcess` before it exits (its group only then); never a pid from a file, `ps` or stdout, a `?? <n>` fallback or literal `0`/`1`/`-1`. Gate: `ok/no-sentinel-signal-target`.
+Never signal a pid you did not spawn. Signal a held `ChildProcess` before it exits (its group only then); never a pid from a file, `ps` or stdout, a `?? <n>` fallback or literal `0`/`1`/`-1`. Two acts in the maintainers' gate tooling, which this repository does not carry, go further, and nothing else does: the lifeline watcher the guard of each gate step forks into the step's process group may run `kill -s KILL 0`, which ends the group it belongs to; and after the step's first process exits, its supervisor may still signal the step's group while that lifeline, a live member, holds the group. Gate: `ok/no-sentinel-signal-target`.
## Comment policy
diff --git a/lint-plugins/ok-rules/README.md b/lint-plugins/ok-rules/README.md
index beb551051..18c249b75 100644
--- a/lint-plugins/ok-rules/README.md
+++ b/lint-plugins/ok-rules/README.md
@@ -669,7 +669,7 @@ Rule: [`lint-plugins/ok-rules/rules/no-unconverted-git-pathspec.mjs`](rules/no-u
### `no-sentinel-signal-target`
-Owned-process signalling. `process.kill(target, signal)` — and the desktop test-support reaper seam `signalOwnedGroup` / `signalOwnedPids` / `reapOwnedTree` when no sender is injected (that seam is not on `main` yet — it lives on the unmerged `feat/ok-update-relaunch-substrate` branch, and the rule covers it ahead of time so the gate is in place the day it lands) — never receive a target that is (a) a literal `0`, `1` or `-1`, (b) a `?? <n>` / `|| <n>` fallback to a number, or (c) a parse of text — `Number(...)`, `parseInt(...)`, `parseFloat(...)`, or the `Number.` spellings of the latter two. A signal-`0` liveness probe (`process.kill(pid, 0)`) sends nothing and is exempt, whatever the target.
+Owned-process signalling. `process.kill(target, signal)` — and the desktop test-support reaper seam `signalOwnedGroup` / `signalOwnedPids` / `reapOwnedTree` when no sender is injected (that seam is not in this tree yet; the rule covers it ahead of time so the gate is in place the day it lands) — never receive a target that is (a) a literal `0`, `1` or `-1`, (b) a `?? <n>` / `|| <n>` fallback to a number, or (c) a parse of text — `Number(...)`, `parseInt(...)`, `parseFloat(...)`, or the `Number.` spellings of the latter two. A signal-`0` liveness probe (`process.kill(pid, 0)`) sends nothing and is exempt, whatever the target.
**Why.** On POSIX, `kill(0, sig)` signals the caller's whole process group, `kill(-1, sig)` every process the user owns, and `kill(-pid, sig)` a group. On 2026-09-20 and 21 a desktop unit test killed every process on a developer's Mac three times, Terminal included: it called `signalOwnedGroup(1, 'SIGKILL')` to prove a guard refused it, a mutation loop had weakened the guard to `pid > 0`, and `process.kill(-1, …)` went through. The mutation loop was killed before its own revert step, so the mutant stayed on disk and every later run of the suite repeated the kill. The same sentinel shape was already live on `main`: `process.kill(pid ?? 0, 'SIGKILL')` in a test reaper, and `process.kill(Number(readFileSync(pidFile)), 'SIGKILL')` in a `finally` — an empty pidfile parses to `0`. Both shipped green: nothing in `pnpm lint` or `pnpm check` looked at what a kill was fed. Canonical prose: the "Never signal a pid you did not spawn" STOP rule in the workspace `AGENTS.md`; this rule encodes its decidable subset.
@@ -677,6 +677,8 @@ Owned-process signalling. `process.kill(target, signal)` — and the desktop tes
- **Signal the handle you spawned** — `child.kill(signal)`.
- **Or a pid you took from that handle** — `child.pid`, wrapped or negated for its group, only while the handle has not reported exit, checked in the same turn as the signal. Negation reaches a group only if you spawned it detached, since `-pid` addresses the group whose pgid is that pid and an ordinary child leads none; on a non-detached child it raises `ESRCH`, which a `catch {}` around the kill turns into a surviving process.
+- **Or that group after the handle reports exit, only while its lifeline holds it.** The maintainers' gate tooling, which the public mirror does not carry, starts each gate step under a guard that forks a lifeline watcher into the step's process group before it runs the step. While that watcher, a live member, holds the group, no other group can take its pgid, so the step's supervisor may still signal `-child.pid` after the step's first process exits. Once the lifeline has closed or been released, the group is no longer a target.
+- **The lifeline's own `kill -s KILL 0`.** That watcher ends the group it belongs to with `kill -s KILL 0` when its supervisor's end of the lifeline closes. It is the only signal to a literal `0` the STOP rule allows, and these two are its only acts beyond signalling a handle before it exits.
- **Negation is not laundering.** `-<expr>` is judged by exactly the same tests as `<expr>`, so a negated `?? <n>` fallback fires just as the bare fallback does, and only a pid already taken from a handle survives the minus sign.
- **Filter a nullable pid out of a list** instead of substituting a sentinel.
- **A pid parsed from a file or a `ps` row is not a signal target**, because `isValidLockPid()` checks its range, not its owner. Stop that process through its owner, or report it.
diff --git a/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs b/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
index a48561083..aa8d29438 100644
--- a/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
+++ b/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
@@ -2,7 +2,7 @@ import { docsUrl } from '../docs.mjs';
const URL = docsUrl('no-sentinel-signal-target');
-const LITERAL_MESSAGE = `Signal target is a literal 0, 1 or -1 — on POSIX that addresses the caller's whole process group, init, or every process the user owns, never a child. Signal only a pid you spawned, and only while it has not exited — the ChildProcess handle, or its pid taken from that handle, negated for the group only if you spawned it detached. See ${URL}`;
+const LITERAL_MESSAGE = `Signal target is a literal 0, 1 or -1 — on POSIX that addresses the caller's whole process group, init, or every process the user owns, never a child. Signal only a pid you spawned, and only while it has not exited — the ChildProcess handle, or its pid taken from that handle, negated for the group only if you spawned it detached. Only two acts in the maintainers' gate tooling, which the public mirror does not carry, go further: after a gate step exits, its supervisor may signal the step's group while a lifeline watcher forked into it, a live member, still holds it; and that watcher's own shell may run \`kill -s KILL 0\`, the one literal-0 signal allowed, to end the group it belongs to. See ${URL}`;
const FALLBACK_MESSAGE = `A \`?? <n>\` / \`|| <n>\` fallback fabricates a signal target when the pid is missing, and \`kill(0, …)\` reaches the caller's own process group. Filter the nullable pid out instead of substituting a sentinel. See ${URL}`;
const PARSED_MESSAGE = `A pid parsed from text reaches \`process.kill\` — an empty pidfile yields \`0\` or \`NaN\` depending on the parser, and a stale pid names whatever process holds the number now. \`isValidLockPid()\` checks only its range, not who owns it. Signal the \`ChildProcess\` you spawned instead; if you hold no handle for the process it names, stop that process through its owner, or report it. See ${URL}`;
diff --git a/lint-plugins/ok-rules/tests/no-sentinel-signal-target.uncached.test.mjs b/lint-plugins/ok-rules/tests/no-sentinel-signal-target.uncached.test.mjs
index d864b39ed..d1c6248c5 100644
--- a/lint-plugins/ok-rules/tests/no-sentinel-signal-target.uncached.test.mjs
+++ b/lint-plugins/ok-rules/tests/no-sentinel-signal-target.uncached.test.mjs
@@ -66,6 +66,7 @@ describe(`${RULE} oxlint rule`, () => {
for (const fire of literal) {
expect(fire.message).toContain('its pid taken from that handle');
expect(fire.message).toContain('negated for the group only if you spawned it detached');
+ expect(fire.message).toContain("two acts in the maintainers' gate tooling, which the public mirror does not carry");
}
});