salvage: uncommitted work from /home/jwoltje/distrobox-homes/mosaic-dev/src/stack-p3-t5 (disk cleanup #824, 2026-11-06)

This commit is contained in:
mos committed 2026-11-06 09:54:57 -06:00
1 parent 517e1adad3
commit 748eee24ba
2 files changed
+2178 -182

No files matched your search

File diff suppressed because it is too large. Load diff
+443 -60
View File
@@ -442,7 +442,7 @@ its stated reason is the same defect class as the span gap that created this ite
### RED phase result
Focused matrix, gateway package: **83 failing / 17 passing (100 cases, 6 files)**, and the terminal
Focused matrix, gateway package: **83 failing / 40 passing (123 cases, 6 files)**, and the terminal
summary carries **no `Errors` row at all**. Typecheck, lint and Prettier clean. Every failure is an
assertion that names what it wanted — the matrix output was scanned specifically for `TypeError`,
`ReferenceError`, missing-export and module-resolution text, not merely counted. Most of those
@@ -632,10 +632,21 @@ What follows is stated plainly because the temptation to round it off is exactly
this item documents: **exact script equality plus `exec` is not process-tree cleanup.** It prohibits
_injected_ shell content, which is worth having on its own terms. But the launcher the contract
_permits_ is multi-process, so a timed-out route can still leave a live process inside a sandbox
being torn down. The fixture's timeout control asserts what it actually measures — a single-process
`exec node -e` sleeper is killed and writes nothing — and it is named for that property alone. No
assertion in this file establishes descendant containment, and the control is not offered as
evidence of it.
being torn down.
**Historical, and superseded — recorded because the sequence is the point.** At the time this
paragraph was first written, the fixture's timeout control asserted only what it actually measured:
a single-process `exec node -e` sleeper was killed and wrote nothing, and the control was named for
that property alone. No assertion in the file established descendant containment, and the control
was explicitly not offered as evidence of it. **Current disposition:** that gap is closed. The
control now runs the real TSX **CLI/launcher** — `tsx --eval`, which loads the same loader and
esbuild children as the route without executing the absent packaged `dev:local` route — and
containment is asserted rather than assumed. An earlier revision of this sentence, and the control's
own name, said "the real TSX route"; the invocation says `--eval`, so the name claimed a subject the
call does not exercise and both have been corrected. See
_Timeout containment_ below for the mechanism, the ruling that governs it, and the residuals it does
not close. The earlier wording is kept because a document that silently overwrites the state it was
wrong about teaches nothing about how the error was found.
One further measurement decides what any containment design may look like, so it is recorded here
rather than left for whoever writes that design to rediscover: every process in the TSX tree runs in
@@ -644,10 +655,19 @@ the test runner's `pgid` and `sid`, because a spawn inherits both by default. Th
sharp — the obvious repair, signalling the negative process-group id, would signal the test runner
itself. Group containment is therefore not a matter of sending a different signal to the tree as it
exists; it requires the child to be given a group of its own at spawn time before any group-directed
signal is safe to send. Which design does that, and whether the resulting emptiness proof is
reuse-safe to the reviewer's standard, is under adjudication and deliberately not settled by the
author. This section will record the ruling and the residual — including the one no group-based
design can close, a descendant that calls `setsid()` for itself and leaves the group.
signal is safe to send.
Which design does that, and whether the resulting emptiness proof is reuse-safe, **was under
architecture adjudication and is now settled** — the author did not settle it, which was the point
of routing it. The ruling is Design A with the gate set `G1, G2, G3-S (+ subordinate floor), G4, G5,
G6, G7, G8`, behind an independent verification gate. Its two most consequential parts are that a
negative kill is issued **only immediately after an enumeration that just proved at least one fully
identity-verified live member** (G7), and that unproven emptiness **retains** the sandbox rather than
removing it (G8). A subsequent ruling on the same gate settled what counts as proof: **ESRCH from
`kill(-pgid, 0)`**, not a zero-member scan, with enumeration retained for identity rather than for
existence. The mechanism, the accepted residual and its quantitative bound are recorded under
_Timeout containment_ below, including the one no group-based design closes: a descendant that calls
`setsid()` for itself leaves the group and the session.
**There is exactly one place in the file where a child process is created**, and that is the
mechanism, not tidiness. A control that made its own spawn would leave the route's spawn free to be
@@ -712,28 +732,47 @@ the callback happened to throw first. How a proof reads is not a property of the
mechanism this whole item rests on is the last place to accept new surface for it.
A structural assertion guards the shape the argument depends on: the spec asserts against its own
source that `node:child_process` is imported exactly once as the named form `{ spawnSync }`, that
the `spawnSync` identifier occurs exactly twice (its import and its one call), and that
`...process.env` occurs nowhere. That is aimed at the one revert behavioral assertions cannot see,
since a behavioral case only ever observes the spawn it makes itself. It is a source-text
source that `node:child_process` is named exactly twice, once as the value import `{ spawnSync }`
and once as the type import `{ SpawnSyncOptionsWithStringEncoding }`, and matches both import lines
literally rather than counting them; that the `spawnSync` identifier occurs exactly three times —
its import, one occurrence in the comment above the options object, and its single call site; and
that `...process.env` occurs nowhere. That is aimed at the one revert behavioral assertions cannot
see, since a behavioral case only ever observes the spawn it makes itself. It is a source-text
heuristic and is documented as one: a child created through an indirection it does not name would
not redden it. It is stated here as a guard, not as a proof.
`fixture control: the spawn site delivers exactly the allowlist to a real child` is the only case
in the package-route arm that runs a child at RED head, and it measures the environment **from
inside the child** rather than from the object handed to `spawnSync`. It spawns twice through that
one site: directly, where the observed key set must equal the allowlist exactly and the child's
`HOME` must be neither the real home nor an ancestor of it; and through the trusted shell, which is
the route's own shape, where every allowlisted name must be present, must still carry the value the
builder constructed for that spawn's own sandbox, and every added name must be one of the shell's
bookkeeping names. Presence alone was not enough: a shell-mediated child that changed `HOME`,
`PATH` or an XDG root would keep every name and stay green. Beyond the key set, it enumerates the
directories on the child's observed `PATH` and asserts the reachable executable names **equal** the
allowlist, asserts the seven known agent-runtime names are absent, and asserts each symlink resolves
to its exact expected binary. It is green by construction and is a **harness control, not
coverage** — it asserts nothing about the code under test. Its purpose is to redden if the fixture
is widened back toward the ambient environment, including by a new executable appearing on `PATH`
that nobody thought to name.
`fixture control: the spawn site delivers exactly the allowlist to a real child` measures the
environment **from inside the child** rather than from the object handed to `spawnSync`. It spawns
twice through that one site: directly, where the observed key set must equal the allowlist exactly
and the child's `HOME` must be neither the real home nor an ancestor of it; and through the trusted
shell, which is the route's own shape, where every allowlisted name must be present, must still
carry the value the builder constructed for that spawn's own sandbox, and every added name must be
one of the shell's bookkeeping names. Presence alone was not enough: a shell-mediated child that
changed `HOME`, `PATH` or an XDG root would keep every name and stay green. Beyond the key set, it
enumerates the directories on the child's observed `PATH` and asserts the reachable executable names
**equal** the allowlist, asserts the seven known agent-runtime names are absent, and asserts each
symlink resolves to its exact expected binary. It is green by construction and is a **harness
control, not coverage** — it asserts nothing about the code under test. Its purpose is to redden if
the fixture is widened back toward the ambient environment, including by a new executable appearing
on `PATH` that nobody thought to name.
An earlier version of that paragraph opened by calling this the only case in the package-route arm
that runs a child at RED head. It is not, and the uniqueness was doing no work in the argument, so
it has been dropped rather than rescoped: the timeout containment control runs a real child at RED
head too, and a third environment measurement has since been added beside this one.
That third measurement is `fixture control: the TSX launcher delivers exactly the allowlist to its
loader process`, and it exists because the two arms above prove the _fixture's_ hermeticity through
`node` and through the trusted shell, while the route's actual launcher is TSX — a loader that
registers module hooks and therefore has both reason and opportunity to add environment of its own.
Measured through the real TSX CLI, through the same one spawn site and the same two-command `PATH`,
the loader's child receives exactly the ten allowlisted names, each carrying the builder's own value
for that run's sandbox, with no added name and **no `NODE_*` variable of any kind** — no
`NODE_PATH`, no `NODE_OPTIONS`, no loader control. TSX writes one deprecation warning to stderr and
nothing else. That is the result the measurement was built to be able to contradict; it came back
clean, which is a finding and not a reassurance, and the case is retained so that a future TSX which
does inject a loader control reddens rather than passes silently. Like its siblings it is a harness
control and asserts nothing about the code under test.
`does not leak the parent ambient environment into the child` is the route-arm half, and it is
**pending execution until GREEN**. At RED head there is no `dev:local` script, so the manifest
@@ -798,40 +837,115 @@ The second is green today and must stay green; it replaced a case that awaited
`onModuleInit().catch(() => undefined)` and asserted only an absence, which a total failure
satisfied.
The seventeen passing cases are itemized rather than counted as coverage, because a green that
cannot fail for its stated reason is the same defect class as the span gap that created this item:
The forty passing cases are itemized rather than counted as coverage, because a green that cannot
fail for its stated reason is the same defect class as the span gap that created this item. They
divide into two populations that must never be summed as though they measured the same thing:
sixteen that make a claim about the code under test, and twenty-four that make a claim about
this spec's own harness. The sixteen:
| Passing case | Why it is green |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| env: config read on import, no policy | legacy regression guard — expected green |
| env: planted dotenv loads, no policy | legacy regression guard — expected green |
| main: anchored config reaches `detectAndAssertTier` | current-contract regression guard; its import-time-exit premise is superseded and must migrate at GREEN |
| local-dev: production `dev` script untouched | regression guard — expected green |
| local-dev: no static import of `main.js` | structural, three forms (binding, side-effect, `require`); must stay green |
| local-dev: importing starts nothing | structural; green today only because nothing invokes `runLocalDev` |
| policy: refuses to serve when unestablished | scaffolding implements this correctly already |
| policy: no fallback read when unestablished | scaffolding implements this correctly already |
| inventory: retains no raw DSN text | **vacuous today** — the stub returns an empty inventory |
| inventory: retains no planted canary | **vacuous today** — same empty inventory |
| inventory: writes no planted canary to the console | **vacuous today** — the stub reads no source, so it can log none |
| policy: children beneath the state root | **vacuous today** — the stub concatenates the declared root |
| policy: unaffected by post-establish input mutation | **vacuous today** — the stub captured strings, it did not clone |
| policy: frozen policy survives a source file gaining a DSN | **vacuous today** — the stub re-serves the same object it built |
| policy: frozen policy survives the environment gaining a DSN | **vacuous today** — same |
| database: sterile local lifecycle migrates, no Postgres seam | positive anchor — green today, must stay green; the one case that fails if GREEN makes "safe" mean "inert" |
| local-dev: fixture control — spawn site delivers the allowlist | harness control, not coverage — green by construction; the only case that runs a child at RED head, and the guard on the instrument the other three depend on |
| Passing case | Why it is green |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| env: config read on import, no policy | legacy regression guard — expected green |
| env: planted dotenv loads, no policy | legacy regression guard — expected green |
| main: anchored config reaches `detectAndAssertTier` | current-contract regression guard; its import-time-exit premise is superseded and must migrate at GREEN |
| local-dev: production `dev` script untouched | regression guard — expected green |
| local-dev: no static import of `main.js` | structural, three forms (binding, side-effect, `require`); must stay green |
| local-dev: importing starts nothing | structural; green today only because nothing invokes `runLocalDev` |
| policy: refuses to serve when unestablished | scaffolding implements this correctly already |
| policy: no fallback read when unestablished | scaffolding implements this correctly already |
| inventory: retains no raw DSN text | **vacuous today** — the stub returns an empty inventory |
| inventory: retains no planted canary | **vacuous today** — same empty inventory |
| inventory: writes no planted canary to the console | **vacuous today** — the stub reads no source, so it can log none |
| policy: children beneath the state root | **vacuous today** — the stub concatenates the declared root |
| policy: unaffected by post-establish input mutation | **vacuous today** — the stub captured strings, it did not clone |
| policy: frozen policy survives a source file gaining a DSN | **vacuous today** — the stub re-serves the same object it built |
| policy: frozen policy survives the environment gaining a DSN | **vacuous today** — same |
| database: sterile local lifecycle migrates, no Postgres seam | positive anchor — green today, must stay green; the one case that fails if GREEN makes "safe" mean "inert" |
Seven greens are vacuous until the implementation exists, up from three, because an earlier pass
added retention and post-freeze-mutation cases that a stub satisfies trivially. They are evidence
of nothing today and are re-checked at GREEN. The count rising is the honest outcome of asserting
more about a module that does not exist yet — it is recorded here so it cannot later be read as
coverage. Of the ten non-vacuous greens, one is the harness control above — it asserts
nothing about the code under test and is never counted as coverage — seven are guards that must
stay green (two legacy continuity, the untouched `dev` script, the structural no-static-import,
the two unestablished-policy refusals, and the database positive anchor) and two are green for a
weaker reason than they read: `local-dev` "starts nothing on import" is green only because nothing yet invokes
`runLocalDev`, and the `main.ts` anchoring case guards a current contract whose import-time-exit
premise `-02a` inverts, so it must be migrated at GREEN rather than deleted.
The other twenty-four greens are **harness self-verification, not coverage of `-02a` at all**.
They assert that this file's own containment machinery, identity guards and channel accounting
behave as specified — code that lives inside the spec file. Every one of them would still be green
if `local-dev.ts` were never written, because none of them touch it:
| Passing control | What it establishes |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ten identity guards (`refuses undefined` … `refuses the verifier process group`) | a negative kill is refused before it is issued, for every unsafe child-identity shape |
| nine containment negative controls | G7 and G8 hold: enumeration precedes every signal, an empty group is never signaled, ESRCH forces re-enumeration, a non-ESRCH errno becomes a typed failure, identity pairs update across rounds, the bound failure is typed, and an unproven sandbox is retained with its absolute path named |
| two G8 wiring controls | the `'unproven'` flag arrives set from `makeChildSandbox`, and the flip to `'proven-empty'` still follows the proof in source order |
| fixture control: the TSX launcher delivers the allowlist | the launcher passes exactly the allowlist, with both output channels consumed byte-for-byte rather than merely matched |
| fixture control: timeout SIGKILLs TSX and proves its process group empty | the unmocked group-kill route contains a loader child that outlives SIGKILL to its TSX parent |
| fixture control: the spawn site delivers the allowlist | green by construction; the guard on the instrument the environment cases depend on. An earlier revision listed this row in the subject table above, while its own cell there called it "harness control, not coverage" — it was counted on the side it explicitly disclaimed |
Counting those twenty-four as coverage would be precisely the error this section exists to
prevent. The passing total grew from seventeen to forty while the module under test was still
unimplemented, and every added green is a statement about the instrument rather than about the
subject. The failing total did not move — 83 before and after — which is the measurement that says
no case changed sides while the instrument was being hardened.
Two corrections to the paragraph above, both of which were wrong in an earlier revision in the
same direction — toward reading better than the evidence supports.
The first is the split itself. It read seventeen subject to twenty-three harness; it is sixteen to
twenty-four. The `local-dev` spawn-site fixture control was tabled among the subject cases while
its own cell described it as "harness control, not coverage", so the document contradicted itself
within one row and the contradiction inflated the side that flatters the work.
The second is the word "absent". `apps/gateway/src/local-dev.ts` is not absent and has not been
since the RED commit that introduced this spec — it is a tracked forty-three-line stub whose own
header says it "establishes nothing correctly and performs no dynamic import". What is absent is
the implementation, not the module. The distinction is load-bearing rather than pedantic: an
absent module makes a case fail, while a stub can make one pass for a reason that has nothing to
do with the contract, which is exactly the vacuous-green population this section itemizes. The
rest of the section had it right — every vacuous row already explains itself by what "the stub"
does — so the defect was confined to the summary sentence, which is the sentence most likely to be
quoted on its own.
**Every pass/fail total in this section — forty passing, 83 failing — is the measurement taken
before the K1/K2/K3/K6 amendment, and has not been retaken.** The amendment added twenty controls
to `local-dev.spec.ts`, all of them harness self-verification, which moved the file to sixteen
subject claims and forty-four harness controls across sixty runtime cases (fifty-one literal
declarations, one of which is an `it.each` expanding to ten). Those sixty are declared counts,
obtained by reading the file; they are not results. Whether the twenty new controls pass is a
question for the independent gate, and stating a passing total here on the strength of having
written the cases would be the same overclaim the section exists to prevent. The subject count did
not move, which is the property worth checking: an amendment that hardened the instrument added no
claim about the subject.
**The r3 amendment adds three further controls, and the same property holds.** The file is now
**sixteen subject claims and forty-seven harness controls across sixty-three runtime cases**
(fifty-four literal declarations, the same single `it.each` expanding to ten). The three additions
are `classifies a safe zero/zero process identity as present`, `keeps zero/zero nonmembers out of a
complete positive-group enumeration`, and `uses only the validated child pid for every negative
group argument` — a parse class, an enumeration outcome, and a signal-argument boundary, all three
claims about this spec's own instrument rather than about the code under test.
The derivation is stated because the number is the kind of thing that gets carried forward rather
than recomputed. The r2 bytes were reconstructed from the published r2 patch, the reconstruction
was confirmed against that patch's own recorded digest, and the two declaration lists were compared
by name: three present now, none removed. That is why the harness figure is forty-seven rather than
forty-four held over, and why the subject figure is asserted as unmoved rather than assumed to be.
These remain declared counts obtained by reading the file. **No runtime case in this file has been
executed by its author, at r2 or at r3.**
One coincidence is worth disarming explicitly, because it invites a false inference. An independent
run reported sixteen failing and forty-four passing cases, and this document declares sixteen
subject and forty-four harness. The numbers coincide on different axes and neither corroborates the
other; the reported failures were thirteen subject and three harness. Reading agreement into the
pair would be reading a coincidence as a measurement. The r3 counts break the coincidence, which is
convenient rather than meaningful.
Seven of those sixteen greens are vacuous until the implementation exists, up from three,
because an earlier pass added retention and post-freeze-mutation cases that a stub satisfies
trivially. They are evidence of nothing today and are re-checked at GREEN. The count rising is the
honest outcome of asserting more about a module that is not implemented yet — it is recorded here
so it cannot later be read as coverage. Of the nine non-vacuous greens, seven are guards
that must stay green (two legacy continuity, the untouched `dev` script, the structural
no-static-import, the two unestablished-policy refusals, and the database positive anchor) and two
are green for a weaker reason than they read: `local-dev` "starts nothing on import" is green only
because nothing yet invokes `runLocalDev`, and the `main.ts` anchoring case guards a current
contract whose import-time-exit premise `-02a` inverts, so it must be migrated at GREEN rather than
deleted.
**Classification is a type obligation, not only a wording one.** Two inventory cases demanded the
raw source values `'standalone'` and `'postgres'`, which the value-free classification unions
@@ -842,6 +956,275 @@ clean", collapsing the exact distinction the refusal path is built on. The invar
`present === false` if and only if `readability === 'absent'` is asserted directly, per state and
across all seven rows at once.
### Timeout containment: what the fixture kills, and what it does not
Node's `spawnSync` timeout kills exactly one process — the direct child. That is the whole of what
the built-in does, and for a single-process child it is sufficient. The required `dev:local` route
is not a single process. TSX spawns an esbuild service child and a `node --require .../preflight.cjs
--import .../loader.mjs --eval <script>` child, and the second is where the route's own code runs.
Measured six times out of six under the fixture's exact spawn shape, that loader/eval child
**survives** the SIGKILL sent to its TSX parent, is reparented, and completes its work afterward —
writing into a sandbox directory the fixture is concurrently removing. The exact `dev:local` script
contract prevents _injected_ shell content; it does not close this, because the launcher the
contract _permits_ is the one that leaks.
The remediation is a bounded containment step that runs synchronously after `spawnSync` returns:
the child is spawned `detached`, giving it its own process group and its own session; the group is
enumerated from `/proc`, signalled by negative PGID, and re-enumerated until proven empty or a
bound is reached. Two rules govern it, and both are mechanism rather than description.
**Kill eligibility (G7): a negative signal may issue only immediately after an enumeration that
found at least one fully identity-verified live member** — `(pid, starttime)` recorded, and
`pgid === childPid` and `sid === childPid` both satisfied. An enumeration returning zero members
goes straight to emptiness confirmation and signals nothing. The rule it replaces is the ordinary
one — signal, then check — and the difference is that a negative PGID is not a request addressed to
a process the caller has verified exists. Never kill on suspicion.
**Teardown gate (G8): emptiness must be proven before the sandbox is removed, and unproven
emptiness retains it.** Proof is **ESRCH from `kill(-pgid, 0)`**, taken at the initial observation
and again after every signal round, and nothing weaker. A zero-member `/proc` enumeration is not
proof: the scan is a directory snapshot stitched to per-entry reads, and a fork handoff can straddle
it. Measured on this host class — a group whose leader has exited **and been reaped**, with only a
later-created grandchild alive in it, reports EXISTS to the kernel while a scan can list no member
at all. Enumeration is kept and is not the existence oracle: enumeration answers _who_ is present
and whether their identity is anomalous, the kernel call answers _whether anyone is_. Success from
the probe means the group exists; **EPERM means it exists and cannot be signalled**; any other errno
means unknown. Both are typed refusals that retain the sandbox, because a `catch` that reports
emptiness when the answer was unreadable is this item's own defect reintroduced one layer down. An
identity anomaly, a non-ESRCH signal errno, an unreadable member identity, or an exhausted round
bound each leave the sandbox on disk, name its absolute path in the typed failure, and fail the test
loudly. Deleting under a possibly-live survivor would discard both the marker the control depends on
and the forensic evidence, and would remove the working directory out from under a process that is
still running — provoking exactly the less-contained behaviour the step exists to prevent. A typed,
loud failure is the outcome whenever the group will not empty; a silent pass is not reachable.
**An earlier probe of mine reported the opposite result, and it was wrong.** It enumerated
survivors by PPID against the killed parent's pid and found none, which I read as a clean tree.
SIGKILLing a parent _reparents_ its children, so the survivors had moved out of the filter's reach;
the sweep returned empty because it could no longer see them. Re-probed by matching on sandbox path
instead of parentage, the result reversed completely. Parent-scoped observation is not admissible
evidence of tree death, and this is the same defect class as a review bounded by directories it
never listed.
#### The containment argument is session identity, not timing
`detached: true` performs `setsid()`, so the child leads a new session whose id equals its own pid.
Every enumerated group member must therefore satisfy both `pgid === childPid` and `sid === childPid`;
a member matching the group but not the session is a group/session anomaly and is refused with its
own typed failure, **without a kill**. Measured 4/4 on the real TSX route under this exact spawn
shape: every group member carried `sid === childPid`, and the verifier was never in the group.
This bound is structural rather than temporal. Membership in the child's group is reachable only by
being the child, by inheriting across `fork`, or by a `setpgid` that Linux refuses across session
boundaries with `EPERM` — so no process existing before the spawn can join, **regardless of when it
started**. A start-time comparison was the earlier candidate for this job and is strictly weaker: it
reasons about when a process began rather than about what it can be a member of.
A subordinate `SPAWN_BOUNDARY_FLOOR` — the verifier's own start time from `/proc/self/stat` field 22,
read once — is retained as a cheap gross-anomaly backstop beneath that guard, not as the containment
argument. Its gap between the floor and the actual spawn instant is a **detection window, not a
process-age residual**: a process starting inside it is not detectable by the floor, and is not left
uncontained either, because session identity excludes it structurally. A tighter per-spawn floor —
the maximum start time across `/proc` sampled immediately before each spawn — is available in ticks
with no clock conversion and no external executable; it was considered and withdrawn, because it
tightens a guard that is not load-bearing at the cost of a full `/proc` sweep before every one of
the fixture's spawns.
Guarding the guard: the pid about to be signalled is validated as a **positive safe integer** before
any negative kill, not merely as finite. `-0 === 0`, `process.kill` coerces it, and `kill(0, sig)`
signals the caller's own process group — so a finiteness check would have admitted the one value
that turns the self-protection guard into the accident it exists to prevent. The same requirement is
applied to the parsed verifier PGID before it is compared or used in any signal path.
#### What this does not contain — stated, not implied away
- **A descendant that calls `setsid()` for itself leaves the group and the session, and is
unreachable by any group kill.** No design considered here closes that. "Process-group
containment" is not totality, and the point of writing this paragraph is that closing a
containment overclaim by writing a new one would repeat the exact defect this item exists to
record.
- **No start-time test can distinguish a recycled group's new members from legitimate
descendants.** Both postdate the spawn. What bounds that case is the identity-checked enumeration
loop, which matches `(pid, starttime)` pairs across kill rounds so that a pid acquired by a
different process between rounds is not counted as a survivor — and, above it, the session check,
which turns a group recycled into a _different_ session from a mis-kill into a detected refusal.
- **Identity checking does not close pid reuse, and the source must not claim it does — this is an
accepted operational risk, not a solved problem.** A recycled pid equal to `childPid` whose new
owner itself calls `setsid()` presents `pid === pgid === sid === childPid` and is indistinguishable
from the real child by identity fields. The check is not atomic with the signal that follows it, so
such an impostor arising between them would be **mis-killed**, not merely mis-observed. G7 pins
that window to a single enumeration→signal gap by permitting a kill only immediately after an
enumeration that just proved at least one fully identity-verified live member, and by issuing **no
kill at all** when an enumeration finds zero members — never killing on suspicion of members, only
what was just proven present. Post-signal `(pid, starttime)` pair comparison is **detection and
reclassification, not a failure path.** A member whose pair no longer matches is classified as
newly observed rather than as a surviving one; it stays a verified live member, having passed the
same group and session identity checks, and becomes one of the recorded pairs the next eligibility
decision is made against. No typed failure fires on a changed pair. An earlier revision of this
paragraph said one did, which was a claim about a mechanism the source does not contain. What the
comparison actually buys is that a pid acquired by a different process between rounds is never
counted as evidence that the original member survived. It does not buy prevention, and detection
after the fact is not prevention.
The bound on the accepted risk, stated so a reader can judge it rather than take it on trust:
within that sub-millisecond gap the impostor requires **all** of (a) every just-verified member
exiting; (b) the freed number being reallocated, which requires the kernel's cyclic allocator to
traverse the remaining pid space — `pid_max` is 4,194,304 on this host class, so even at an absurd
10⁶ forks per second a wraparound takes seconds against a sub-millisecond window, a margin of at
least 10³; (c) the process landing on exactly `childPid` and calling `setsid()`; and (d) same-uid
signalability, which also bounds any blast radius to the invoking user's own processes.
Requirement (a) additionally rests on the pgid-pins-pid-number mechanism described in the next
bullet, and is kept as stated mechanism rather than host measurement; (b) through (d) carry the
bound on their own. This arithmetic bounds **likelihood, in the mis-signal direction only** — how
improbable it is that an impostor occupies the number a signal round is about to use. It is not
an input to the emptiness proof, which is closed structurally by what ESRCH means and does not
depend on any of these numbers; see the signal-zero-candidate bullet below.
- **An unreaped zombie leader makes the kernel report the group as existing.** `kill(-pgid, 0)`
succeeds while a leader has exited and has not yet been waited on, so the ESRCH answer G8 now
requires as proof is unavailable for as long as the zombie persists. This is bounded and fails in
the safe direction: the sandbox is retained, the round bound is exhausted, and the failure is typed
and loud, so the outcome is a refusal to claim emptiness rather than a false claim of it. It is
stated rather than engineered around, because the only two ways to remove it are to reap on the
containment path — which would mean the verifier taking ownership of a process it did not spawn —
or to read a non-ESRCH answer as emptiness, which is the exact defect the gate exists to remove.
- **The signal-zero candidate is not proven to still name the original child's group.** `spawnSync`
returns after the leader exits, and pid reuse in the enumeration-to-signal gap is already accepted
above; nothing in the source proves the number passed to `kill(-pgid, 0)` still names the group it
named at spawn. What makes this survivable is **structural, and it is not the `pid_max` margin**.
ESRCH is returned only when no process is in the group. Any surviving original member is in that
group by definition. The kernel therefore cannot answer ESRCH while a member exists, so a false
_empty_ is not reachable through reuse at all — a reused group number can only answer EXISTS, and
only when the original group is genuinely gone. A wrong candidate can withhold the proof and
retain the sandbox; it cannot manufacture one. The proof's failure mode is closed; its
availability is not guaranteed, and the design does not claim it is.
**The arithmetic above carries no weight in this argument, and must not be cited as though it
did.** The `pid_max` margin says reuse is unlikely. It says nothing about why reuse is harmless
to the proof, which is a consequence of what ESRCH means rather than of how rarely a number comes
back around. An earlier revision of this bullet rested the case on the margin, which put a number
in the place where the semantics already did the work — the same substitution as counting a
harness control as coverage, and it would have degraded silently on any host with a smaller
`pid_max` rather than failing.
**This closes the emptiness proof and nothing else — and "closed" is the right word only here.**
The same reuse remains live in the other direction, where it is not benign: a group number that
has been reallocated by the time a `SIGKILL` round issues names a stranger's process group, and
that kill lands on a third party rather than failing a test. Withholding a proof retains a sandbox
and fails loudly; a wrong group kill cannot be walked back.
That direction is **narrowed and detected, not closed.** Every signal is issued immediately after
an enumeration whose members passed group, session and anomaly verification — round 0 from the
pre-loop enumeration, each later round from the fresh one taken at the end of its predecessor — so
the exposure is reduced to a single enumeration→signal gap per round instead of spanning the
loop, and a pid acquired by a different process between rounds is never counted as a surviving
member. What that does not do is make the gap atomic. An exact identity impostor arising inside
it — a recycled pid equal to `childPid` whose new owner calls `setsid()`, presenting
`pid === pgid === sid === childPid` — is indistinguishable from the real child by every field the
check reads, and would be mis-killed. That is the accepted operational residual recorded three
bullets above, and per-round re-verification does not remove it.
An earlier revision of this paragraph said the mis-signal risk was "closed by a different
mechanism entirely". That was an overclaim, and it contradicted this document's own bullet
stating that identity checking does not close pid reuse and that the source must not claim it
does. Two adjacent statements in one record, one saying the risk is accepted and one saying it is
closed, is worse than either alone: a reader quoting the closure sentence would carry away the
opposite of the design's actual position. Only false emptiness is closed, and only structurally,
by what ESRCH means. The two mechanisms must be kept apart wherever either is quoted — the
structural ESRCH argument protects the proof, per-round re-verification narrows and detects
mis-signal, and neither substitutes for the other or for the admitted residual.
- **Enumeration is coupled to the readability of the whole `/proc` table, not only to the target
group, and that coupling is deliberate.** A single genuinely unreadable or unparseable record
belonging to an entirely unrelated process makes the whole scan return typed unknown rather than
`complete`. This looks disproportionate and is kept anyway: the scan's question is "is any member
of this group present", and a record that cannot be read cannot be excluded from membership, so
the honest answer is that membership is undetermined. Treating an unreadable stranger as a
nonmember would silently convert an unanswered question into a negative answer, which is the
precise shape of the defect this whole item exists to remove. The cost is availability — an
unrelated permission or grammar surprise anywhere in `/proc` withholds the proof and retains the
sandbox — and the design accepts that cost rather than narrowing the scan to records it already
believes are irrelevant.
Two classes are explicitly **not** instances of this coupling, because both are understood rather
than merely unread. A kernel thread's `pgid=0, sid=0` record is a valid, completely parsed record
that is a nonmember of every strictly positive target group; it is recognized, not tolerated. A
process that disappears mid-scan (`ENOENT` from the open, `ESRCH` from a read after a successful
open) is benign absence, since a task that is gone is not a member either. Neither withholds
`complete`. What withholds it is a record that is present and unreadable, or readable and not
understood — and the distinction between "known to be irrelevant" and "not known" is the entire
content of this bullet. An earlier revision failed exactly here in the opposite direction: it
classified kernel threads as unparseable, which made `complete` unreachable on every Linux host
and meant the containment success path could never run at all.
- **Two mechanisms would close it outright, and both are out of reach here — one on reachability,
one on structure.** Recorded as named escalation paths so that a future reader inherits the
analysis instead of repeating it. `pidfd_send_signal(fd, SIGKILL, PIDFD_SIGNAL_PROCESS_GROUP)` on
kernels ≥ 6.9 signals the group of a pidfd-pinned process and closes the race outright; it is
present in this host's headers and is rejected because Node exposes no pidfd bindings, so reaching
it needs either a native addon or an external helper executable — both refused classes for this
item, and a rejection on **reachability, not absence**. A cgroup v2 kill boundary is rejected on
**structure rather than environment**, which is the sharper reason and not the one first proposed:
delegation is real on this host class and `cgroup.kill` needs no new executable, but under this
design no fixture code runs while `spawnSync` blocks, so the child is already dead when control
returns and there is nothing left to migrate. Migration while the child lives would require the
asynchronous design, and even there writing a pid into `cgroup.procs` moves only that pid, so
anything forked before migration escapes the boundary; the race-free form is
`clone3(CLONE_INTO_CGROUP)`, unreachable from Node builtins. The distinction is worth stating in
its own words, because the author's first framing was the weaker one: the question was never
whether the tool is available, it is whether there is a **moment to use it**. Delegation being real
on this host class is recorded deliberately, so that a future reader who checks the environment,
finds the mechanism present, and concludes the rejection is stale, reads this sentence instead.
"Unavailable in this environment" and "inapplicable to this design" send that reader down
different paths, and this one is the second.
- **One supporting mechanism is unverified.** The soundness of a freshly created group at spawn
time rests on the kernel not allocating a PID number while it persists as a live process's PGID
or SID (struct-pid refcounting). That is stated here as mechanism, not as measurement: forcing
PID-space wraparound to observe it is not a bounded experiment, and it was not run. Nothing in
the design depends on it.
- **The esbuild observation is bounded to the runs performed.** In these runs the esbuild service
child did not survive the parent kill and its count did not accumulate. That is not a claim it
can never survive, and nothing in the design assumes it exits on its own.
- **The installed type declarations do not describe the runtime.** `detached` is declared on
`SpawnOptions` and not on `SpawnSyncOptions`, while Node honours it on `spawnSync` regardless —
measured on this host as `pid == pgid == sid`. The gap is reconciled explicitly and visibly at the
call site, because the earlier reconciliation was an annotated local variable that suppressed
excess-property checking silently: the call read as type-checked when it was not, and the file's
own review measure is a count of type escapes, which such a construct does not appear in. A
construct that defeats the metric is worse than the escape it avoids.
#### The same errno name means different things at different layers
Two syscalls in this design return overlapping errno names while answering different questions. The
names are not interchangeable, and collapsing them is a live failure mode rather than a theoretical
one — it has already happened once, in a ruling.
| Operation | Benign absence | Exists | Unknown / refusal |
| ----------------------- | ----------------- | -------------------------------------------- | -------------------------------------- |
| read `/proc/<pid>/stat` | `ENOENT`, `ESRCH` | n/a — a successful parse is presence | every other errno, every parse failure |
| `kill(-pgid, 0)` | `ESRCH` **only** | success = signalable; `EPERM` = unsignalable | `ENOENT` and every other errno |
The asymmetry is the point. At the stat layer both names mean the task is gone: `ENOENT` is what an
open returns for a task already reaped, and `ESRCH` is what a **read** returns when the task is
reaped after the open succeeded but before the read — `readFileSync` performs both operations in
one call, so a single call can surface either. At the kill layer `ESRCH` carries the entire
emptiness proof and `ENOENT` is not an expected answer at all, so treating it as absence would be
inventing a proof from an unexplained result.
The earlier ruling on this point required `ENOENT` alone as benign stat absence and classified stat
`ESRCH` as unknown. It was **superseded by its own author** after a deterministic measurement of the
open/read race — open an fd on `/proc/<pid>/stat`, kill and reap the task, then read the already-open
fd, which yields `ESRCH` where a fresh open yields `ENOENT`. The candidate was already correct at
that layer and was returned unchanged with the contradiction flagged rather than silently normalized
to match the ruling. That refusal is what surfaced the error. Had the code been aligned to the
ruling instead, the `ENOENT`-only rule would have shipped and left an intermittent version of the
kernel-thread poisoning behind it: in a scan of roughly a thousand pids, a process exiting mid-scan
is the ordinary case rather than the edge, so the bug would have passed most runs and failed
occasionally — the harder kind to find, and the kind that erodes trust in the suite rather than in
the defect.
### Scope discipline
`-02a` neither breaks production-like entrypoints nor authorizes their local use. They resolve