rungate 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +81 -16
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-id-cross-tree.ts +19 -7
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +241 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reap test-suite processes that have no owner left (#690, #712).
|
|
3
|
+
*
|
|
4
|
+
* The thing this replaces never tested for orphanhood.
|
|
5
|
+
* `~/.pai/hooks/OrphanProcessCleanup.hook.ts` is, in its entirety:
|
|
6
|
+
*
|
|
7
|
+
* ```
|
|
8
|
+
* pgrep -f "bun test" # find every bun test process on the machine
|
|
9
|
+
* pkill -f "bun test" # SIGTERM all of them
|
|
10
|
+
* sleep 1
|
|
11
|
+
* pkill -9 -f "bun test" # SIGKILL the survivors
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* No parent check, no age check, no session check, and it was registered on
|
|
15
|
+
* `SessionStart` **and** `SessionEnd`, so every session start — including a
|
|
16
|
+
* compaction resume — killed every suite on the machine. Measured on
|
|
17
|
+
* 2026-10-19: a consumer project's suite baseline and a peer session's suite
|
|
18
|
+
* died at the same instant, both mid-run, both with no summary line and no
|
|
19
|
+
* failure count, which is why it was diagnosed as a hang first. Its banner
|
|
20
|
+
* said `Cleaned up 4 orphaned bun test processes` while reaping four
|
|
21
|
+
* processes that all had live parents.
|
|
22
|
+
*
|
|
23
|
+
* ## What it was named for, and never did
|
|
24
|
+
*
|
|
25
|
+
* A genuinely parentless `bun test` burns CPU until reboot. `TestSuiteRelease`
|
|
26
|
+
* returns the lock slot and the TTL backstops it, so slot correctness never
|
|
27
|
+
* depended on the reaper — but nothing reaps the PROCESS. That job is real,
|
|
28
|
+
* and a fix that merely stops killing things does not do it. The negative
|
|
29
|
+
* control for this module is therefore not "nothing died": it is
|
|
30
|
+
* **a genuine orphan still dies**, asserted by name in
|
|
31
|
+
* `test/orphan-reaper.test.ts`.
|
|
32
|
+
*
|
|
33
|
+
* ## Three conditions, all of them, and a pid rather than a pattern
|
|
34
|
+
*
|
|
35
|
+
* `orphanDecision` is the one decider and it reaps only when every one of
|
|
36
|
+
* these holds:
|
|
37
|
+
*
|
|
38
|
+
* 1. **The row is positively a suite.** `classifyPsLine` in
|
|
39
|
+
* `lib/test-suite-lock.ts` is asked — the same binding the concurrency
|
|
40
|
+
* guard uses to decide what keeps a slot, so the two cannot drift. Its
|
|
41
|
+
* third reading, `unknown`, is never reaped: a slot is kept on `unknown`
|
|
42
|
+
* because over-detection is safe there, and a process is spared on
|
|
43
|
+
* `unknown` because over-detection is not safe here. One classifier, read
|
|
44
|
+
* in opposite directions, each named.
|
|
45
|
+
* 2. **The parent is gone.** `ppid === 1` means the launching session exited
|
|
46
|
+
* and the kernel reparented the process to init. A suite with a live
|
|
47
|
+
* parent belongs to somebody who is still there, and `LIVE_PARENT` is the
|
|
48
|
+
* reason that keeps a peer's run alive. **This condition has a known
|
|
49
|
+
* false-positive path — read `INIT_PID` below before arming anything.**
|
|
50
|
+
* 3. **It is older than the floor.** A suite started seconds ago is never an
|
|
51
|
+
* orphan (#690 AC-3), and the floor is set well past any plausible run
|
|
52
|
+
* rather than at the edge of one.
|
|
53
|
+
*
|
|
54
|
+
* Every row is judged against all three, independently, and carries all three
|
|
55
|
+
* readings into the report. `reason` is the FIRST condition that failed, which
|
|
56
|
+
* is what an operator wants at a glance and is not enough to diagnose a false
|
|
57
|
+
* positive: a row reading `LIVE_PARENT` says nothing about whether it was even
|
|
58
|
+
* a suite or whether it had cleared the floor. `conditions` says, so a
|
|
59
|
+
* dry-run log can be read without reproducing the machine state that produced
|
|
60
|
+
* it (#690 AC-4).
|
|
61
|
+
*
|
|
62
|
+
* Signals go to one pid at a time, read off the row that was judged. There is
|
|
63
|
+
* no pattern anywhere: `pkill -f` acts on whatever matches at signal time,
|
|
64
|
+
* including processes that started after the decision, and it matches the
|
|
65
|
+
* measuring shell as readily as the suite — which is the half of #690 that
|
|
66
|
+
* destroyed the evidence.
|
|
67
|
+
*
|
|
68
|
+
* ## Arming is a deployment decision, and it is not this module's to take
|
|
69
|
+
*
|
|
70
|
+
* `reapOrphans` is inert unless `armed` is passed. The report is identical
|
|
71
|
+
* either way except for `armed` and `signalled`, so a dry run says exactly
|
|
72
|
+
* which pids it would have signalled and why. #690's own scope note says to
|
|
73
|
+
* confirm with Jason before changing kill behaviour on this machine, and the
|
|
74
|
+
* hook that would call this runs from the shared checkout at every
|
|
75
|
+
* `SessionStart` — so a merge that armed it would arm it for every live peer
|
|
76
|
+
* at once. See `hooks/StaleTTLCleanup.hook.ts` for the one-line flip.
|
|
77
|
+
*
|
|
78
|
+
* **It shipped disarmed and it should stay that way until the dry-run log has
|
|
79
|
+
* been read.** `armedFromEnv` is the only thing that arms it: there is no
|
|
80
|
+
* config key, nothing in the scaffold writes it, and `hooks/` is not in
|
|
81
|
+
* `package.json` `files[]`, so no consumer inherits the caller. The two
|
|
82
|
+
* reasons to leave it disarmed are measurements, not caution — see `INIT_PID`
|
|
83
|
+
* and `MIN_ORPHAN_AGE_SECONDS` below. Arm it by reading a few days of
|
|
84
|
+
* `conditions` lines and checking that every row it would have signalled was
|
|
85
|
+
* in fact dead.
|
|
86
|
+
*
|
|
87
|
+
* **"Disarmed" was an assumption until #690's last wave.** The claim rested
|
|
88
|
+
* on a `===` spelled inline in a hook — nothing executed it with the values
|
|
89
|
+
* that must NOT arm it, and nothing in the tree would have noticed a commit
|
|
90
|
+
* adding the variable to a workflow `env:` block or a settings file. Both
|
|
91
|
+
* halves are now cases: `armedFromEnv` is driven over the values, and
|
|
92
|
+
* `test/orphan-reaper.test.ts` holds the population of committed ARMING
|
|
93
|
+
* positions at zero over the file types that can set an environment
|
|
94
|
+
* variable.
|
|
95
|
+
*/
|
|
96
|
+
|
|
97
|
+
import {
|
|
98
|
+
classifyPsLine,
|
|
99
|
+
type ExecutableResolver,
|
|
100
|
+
type PsLineReading,
|
|
101
|
+
} from "./test-suite-lock";
|
|
102
|
+
import { readProcessTable, type ProcessRow } from "./process-table";
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* How old a parentless suite must be before it is residue (#690 AC-3).
|
|
106
|
+
*
|
|
107
|
+
* ONE declaration, so there is one thing for a battery to mutate. Thirty
|
|
108
|
+
* minutes is deliberately far past a real run rather than next to one: the
|
|
109
|
+
* cost of waiting is some CPU, and the cost of being wrong is somebody's
|
|
110
|
+
* measurement. A suite reparented to init and still going after half an hour
|
|
111
|
+
* has no shell left to read its exit code.
|
|
112
|
+
*
|
|
113
|
+
* **Thirty minutes was chosen against a healthy machine, and this machine is
|
|
114
|
+
* not reliably one.** The Linux CI runners live in a Lima VM with 9912 MB of
|
|
115
|
+
* RAM running nine runner units, each peaking at 3.5–4.0 GB, and a suite
|
|
116
|
+
* runs 474 files as separate processes under `--isolate`. A legitimate run
|
|
117
|
+
* under that much memory pressure takes far longer than a run on an idle
|
|
118
|
+
* host, so the floor that is "well past any plausible run" on a quiet machine
|
|
119
|
+
* is not obviously past one here. **The dry-run log decides this number**, not
|
|
120
|
+
* an estimate: read what a few days of it would have signalled, and raise the
|
|
121
|
+
* floor past the oldest row that turns out to have been alive.
|
|
122
|
+
*/
|
|
123
|
+
export const MIN_ORPHAN_AGE_SECONDS = 1800;
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* The pid a process is reparented to when its parent exits.
|
|
127
|
+
*
|
|
128
|
+
* ## `ppid === 1` is not proof the owner is gone (measured 2026-10-21)
|
|
129
|
+
*
|
|
130
|
+
* The design reads "reparented to init" as "the launching session exited",
|
|
131
|
+
* and on a healthy machine that is what it means. There is a second way to
|
|
132
|
+
* reach it, and this hardware produces it: **when the kernel OOM-killer kills
|
|
133
|
+
* a parent, its children are reparented to init exactly like an orphan.**
|
|
134
|
+
* Three self-hosted CI runners on the Mac Mini's Lima VM were OOM-killed
|
|
135
|
+
* mid-job on 2026-10-21. Any suite one of them had spawned survived the kill,
|
|
136
|
+
* kept running, kept doing useful work — and from `ps` it is byte-identical
|
|
137
|
+
* to residue: `ppid 1`, a `bun test` argv, and an age that climbs.
|
|
138
|
+
*
|
|
139
|
+
* So the condition is **necessary and not sufficient**, and the gap is on the
|
|
140
|
+
* dangerous side: it over-reports orphans rather than under-reporting them.
|
|
141
|
+
* Whoever arms this is signalling that class too. Nothing here tries to tell
|
|
142
|
+
* the two apart, because the distinguishing evidence is not in the process
|
|
143
|
+
* table — it is in whether anything is still reading the suite's output — and
|
|
144
|
+
* guessing at it would be a second decider that agrees with the first.
|
|
145
|
+
*
|
|
146
|
+
* What to do instead of widening this check from first principles: read the
|
|
147
|
+
* dry-run log. Every candidate line carries the full argv and all three
|
|
148
|
+
* conditions, so an OOM-reparented survivor is identifiable after the fact.
|
|
149
|
+
* If the log names a suite that was alive, the OOM case needs handling
|
|
150
|
+
* BEFORE this goes anywhere near a signal.
|
|
151
|
+
*/
|
|
152
|
+
export const INIT_PID = 1;
|
|
153
|
+
|
|
154
|
+
/** Why a row was or was not signalled. Every row carries one. */
|
|
155
|
+
export type ReapReason =
|
|
156
|
+
| "ORPHANED"
|
|
157
|
+
| "NOT_A_SUITE"
|
|
158
|
+
| "UNCLASSIFIED"
|
|
159
|
+
| "SELF_OR_ANCESTOR"
|
|
160
|
+
| "LIVE_PARENT"
|
|
161
|
+
| "TOO_YOUNG";
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Every condition, read for every row, whether or not an earlier one settled
|
|
165
|
+
* the answer.
|
|
166
|
+
*
|
|
167
|
+
* `reason` is a short-circuit and so cannot carry this: `LIVE_PARENT` is the
|
|
168
|
+
* first failing condition and says nothing about the other two. Reading a
|
|
169
|
+
* dry-run log for false positives means asking "what else was true of this
|
|
170
|
+
* row", and a log that answers only "the first thing that was false" sends
|
|
171
|
+
* the reader back to a machine state that no longer exists.
|
|
172
|
+
*
|
|
173
|
+
* `suite` keeps the classifier's three-state reading rather than a boolean,
|
|
174
|
+
* because `not-suite` and `unknown` are different facts and collapsing them
|
|
175
|
+
* is what #707 was about.
|
|
176
|
+
*/
|
|
177
|
+
export interface ReapConditions {
|
|
178
|
+
/** Condition 1, as `classifyPsLine` read it. Only `suite` can be reaped. */
|
|
179
|
+
suite: PsLineReading;
|
|
180
|
+
/** Condition 2 — see `INIT_PID` for the OOM-reparenting false positive. */
|
|
181
|
+
parentGone: boolean;
|
|
182
|
+
/** Condition 3, against `floorSeconds`. */
|
|
183
|
+
olderThanFloor: boolean;
|
|
184
|
+
/** Not one of the three: this process or one of its ancestors. */
|
|
185
|
+
protectedPid: boolean;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export interface ReapDecision {
|
|
189
|
+
pid: number;
|
|
190
|
+
ppid: number;
|
|
191
|
+
ageSeconds: number;
|
|
192
|
+
command: string;
|
|
193
|
+
reap: boolean;
|
|
194
|
+
reason: ReapReason;
|
|
195
|
+
conditions: ReapConditions;
|
|
196
|
+
/** The floor `olderThanFloor` was read against, so the log is self-contained. */
|
|
197
|
+
floorSeconds: number;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* The one decider. `reap` is `reason === "ORPHANED"` and nothing else
|
|
202
|
+
* computes it, so there is no second binding that could disagree.
|
|
203
|
+
*/
|
|
204
|
+
function reasonFrom(c: ReapConditions): ReapReason {
|
|
205
|
+
if (c.suite === "not-suite") return "NOT_A_SUITE";
|
|
206
|
+
if (c.suite === "unknown") return "UNCLASSIFIED";
|
|
207
|
+
if (c.protectedPid) return "SELF_OR_ANCESTOR";
|
|
208
|
+
if (!c.parentGone) return "LIVE_PARENT";
|
|
209
|
+
if (!c.olderThanFloor) return "TOO_YOUNG";
|
|
210
|
+
return "ORPHANED";
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
export interface OrphanDecisionOptions {
|
|
214
|
+
minAgeSeconds?: number;
|
|
215
|
+
/** Pids that must never be signalled: this process and its ancestors. */
|
|
216
|
+
protectedPids?: ReadonlySet<number>;
|
|
217
|
+
resolveExecutable?: ExecutableResolver;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* The one place a process is judged to be an orphan.
|
|
222
|
+
*
|
|
223
|
+
* Exported so there is exactly one binding to mutate, and so a case can drive
|
|
224
|
+
* it over a table of rows without a process existing anywhere.
|
|
225
|
+
*/
|
|
226
|
+
export function orphanDecision(
|
|
227
|
+
row: ProcessRow,
|
|
228
|
+
options: OrphanDecisionOptions = {},
|
|
229
|
+
): ReapDecision {
|
|
230
|
+
const floorSeconds = options.minAgeSeconds ?? MIN_ORPHAN_AGE_SECONDS;
|
|
231
|
+
// Every condition is read for every row. A short-circuit here would leave
|
|
232
|
+
// the later conditions unmeasured, and an unmeasured condition rendered in
|
|
233
|
+
// a log is indistinguishable from one that was false.
|
|
234
|
+
const conditions: ReapConditions = {
|
|
235
|
+
suite: classifyPsLine(row.command, options),
|
|
236
|
+
parentGone: row.ppid === INIT_PID,
|
|
237
|
+
olderThanFloor: row.elapsedSeconds >= floorSeconds,
|
|
238
|
+
protectedPid: options.protectedPids?.has(row.pid) === true,
|
|
239
|
+
};
|
|
240
|
+
const reason = reasonFrom(conditions);
|
|
241
|
+
return {
|
|
242
|
+
pid: row.pid,
|
|
243
|
+
ppid: row.ppid,
|
|
244
|
+
ageSeconds: row.elapsedSeconds,
|
|
245
|
+
command: row.command,
|
|
246
|
+
reap: reason === "ORPHANED",
|
|
247
|
+
reason,
|
|
248
|
+
conditions,
|
|
249
|
+
floorSeconds,
|
|
250
|
+
};
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Every pid between `pid` and the root of the table, inclusive. */
|
|
254
|
+
export function ancestryOf(rows: readonly ProcessRow[], pid: number): Set<number> {
|
|
255
|
+
const byPid = new Map(rows.map((r) => [r.pid, r]));
|
|
256
|
+
const seen = new Set<number>([pid]);
|
|
257
|
+
let cursor = byPid.get(pid);
|
|
258
|
+
while (cursor && !seen.has(cursor.ppid)) {
|
|
259
|
+
seen.add(cursor.ppid);
|
|
260
|
+
cursor = byPid.get(cursor.ppid);
|
|
261
|
+
}
|
|
262
|
+
return seen;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export interface SignalRecord {
|
|
266
|
+
pid: number;
|
|
267
|
+
signal: "SIGTERM" | "SIGKILL";
|
|
268
|
+
ageSeconds: number;
|
|
269
|
+
command: string;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
export interface ReapReport {
|
|
273
|
+
/** `UNMEASURED` means nothing was judged and nothing was signalled. */
|
|
274
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
275
|
+
unmeasuredReason?: string;
|
|
276
|
+
/** How many rows the reading contained, so a verdict reports its coverage. */
|
|
277
|
+
examined: number;
|
|
278
|
+
/**
|
|
279
|
+
* One entry per CANDIDATE row — anything the classifier did not rule out as
|
|
280
|
+
* `not-suite` — carrying the pid, the parent, the age and the reason.
|
|
281
|
+
* "Cleaned up N" and "No orphaned processes found" were the only two things
|
|
282
|
+
* the old hook could say, and neither distinguishes a real orphan from a
|
|
283
|
+
* live run (#690 AC-4).
|
|
284
|
+
*/
|
|
285
|
+
decisions: ReapDecision[];
|
|
286
|
+
/** Whether signals were allowed at all. A dry run still reports decisions. */
|
|
287
|
+
armed: boolean;
|
|
288
|
+
signalled: SignalRecord[];
|
|
289
|
+
/** Pids signalled with SIGTERM that were still present on the re-read. */
|
|
290
|
+
survivors: number[];
|
|
291
|
+
/** Set when the post-SIGTERM re-read could not be taken. */
|
|
292
|
+
escalationUnmeasuredReason?: string;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
export interface ReapOptions extends OrphanDecisionOptions {
|
|
296
|
+
rows?: ProcessRow[];
|
|
297
|
+
readRows?: () => ProcessRow[];
|
|
298
|
+
kill?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
|
|
299
|
+
/** Called between SIGTERM and the re-read. Injected so no case sleeps. */
|
|
300
|
+
settle?: () => void;
|
|
301
|
+
selfPid?: number;
|
|
302
|
+
armed?: boolean;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
const defaultKill = (pid: number, signal: "SIGTERM" | "SIGKILL") => {
|
|
306
|
+
process.kill(pid, signal);
|
|
307
|
+
};
|
|
308
|
+
|
|
309
|
+
/** The one variable that can arm the reaper, and the one value that does it. */
|
|
310
|
+
export const ARM_ENV_VAR = "RUNGATE_REAP_ORPHANS";
|
|
311
|
+
export const ARM_ENV_VALUE = "1";
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* Whether the environment arms the reaper. The ONE arming decider.
|
|
315
|
+
*
|
|
316
|
+
* It was `process.env.RUNGATE_REAP_ORPHANS === '1'`, spelled inline at the
|
|
317
|
+
* hook's call site. That is the same comparison and it could not be driven:
|
|
318
|
+
* a hook module runs its work at import, so the only way to ask "does an
|
|
319
|
+
* empty environment arm this" was to read the source and agree with it. The
|
|
320
|
+
* repository's claim about its own kill switch was the one claim with no
|
|
321
|
+
* instrument behind it, on the one switch where being wrong costs somebody
|
|
322
|
+
* else's three-hour run.
|
|
323
|
+
*
|
|
324
|
+
* Read EXACTLY, for the reason `.claude/rules/config-access.md` gives about
|
|
325
|
+
* `RUNGATE_REQUIRE_AI_REVIEW`: a loose reading of a variable that turns a
|
|
326
|
+
* gate on is a gate that turns itself on by accident. `true`, `TRUE`, `yes`,
|
|
327
|
+
* `01` and a leading space are all disarmed, and each is a case.
|
|
328
|
+
*
|
|
329
|
+
* `env` is a parameter so a case can pass a table instead of mutating the
|
|
330
|
+
* live `process.env` — a suite that armed its own environment and then threw
|
|
331
|
+
* would leave the variable set for every later file in the same process.
|
|
332
|
+
*/
|
|
333
|
+
export function armedFromEnv(
|
|
334
|
+
env: Record<string, string | undefined> = process.env,
|
|
335
|
+
): boolean {
|
|
336
|
+
return env[ARM_ENV_VAR] === ARM_ENV_VALUE;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* Judge every process, and — only when `armed` — signal the orphans by pid.
|
|
341
|
+
*
|
|
342
|
+
* An unreadable process table is `UNMEASURED` and kills nothing. An empty
|
|
343
|
+
* list from a failed read must not read as "checked, nothing orphaned":
|
|
344
|
+
* `readProcessTable` refuses a reading that cannot see its own reader, and
|
|
345
|
+
* that refusal arrives here as an exception rather than as zero rows.
|
|
346
|
+
*/
|
|
347
|
+
export function reapOrphans(options: ReapOptions = {}): ReapReport {
|
|
348
|
+
const readRows = options.readRows ?? (() => readProcessTable({ selfPid: options.selfPid }));
|
|
349
|
+
let rows: ProcessRow[];
|
|
350
|
+
try {
|
|
351
|
+
rows = options.rows ?? readRows();
|
|
352
|
+
} catch (e) {
|
|
353
|
+
return {
|
|
354
|
+
reading: "UNMEASURED",
|
|
355
|
+
unmeasuredReason: (e as Error).message,
|
|
356
|
+
examined: 0,
|
|
357
|
+
decisions: [],
|
|
358
|
+
armed: options.armed === true,
|
|
359
|
+
signalled: [],
|
|
360
|
+
survivors: [],
|
|
361
|
+
};
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
const protectedPids =
|
|
365
|
+
options.protectedPids ?? ancestryOf(rows, options.selfPid ?? process.pid);
|
|
366
|
+
const decisions = rows
|
|
367
|
+
.map((row) => orphanDecision(row, { ...options, protectedPids }))
|
|
368
|
+
.filter((d) => d.reason !== "NOT_A_SUITE");
|
|
369
|
+
|
|
370
|
+
const report: ReapReport = {
|
|
371
|
+
reading: "MEASURED",
|
|
372
|
+
examined: rows.length,
|
|
373
|
+
decisions,
|
|
374
|
+
armed: options.armed === true,
|
|
375
|
+
signalled: [],
|
|
376
|
+
survivors: [],
|
|
377
|
+
};
|
|
378
|
+
if (!report.armed) return report;
|
|
379
|
+
|
|
380
|
+
const kill = options.kill ?? defaultKill;
|
|
381
|
+
const doomed = decisions.filter((d) => d.reap);
|
|
382
|
+
for (const d of doomed) {
|
|
383
|
+
try {
|
|
384
|
+
kill(d.pid, "SIGTERM");
|
|
385
|
+
report.signalled.push({
|
|
386
|
+
pid: d.pid,
|
|
387
|
+
signal: "SIGTERM",
|
|
388
|
+
ageSeconds: d.ageSeconds,
|
|
389
|
+
command: d.command,
|
|
390
|
+
});
|
|
391
|
+
} catch {
|
|
392
|
+
// Gone between the reading and the signal. Nothing to escalate.
|
|
393
|
+
}
|
|
394
|
+
}
|
|
395
|
+
if (doomed.length === 0) return report;
|
|
396
|
+
|
|
397
|
+
options.settle?.();
|
|
398
|
+
let after: ProcessRow[];
|
|
399
|
+
try {
|
|
400
|
+
after = readRows();
|
|
401
|
+
} catch (e) {
|
|
402
|
+
report.escalationUnmeasuredReason = (e as Error).message;
|
|
403
|
+
return report;
|
|
404
|
+
}
|
|
405
|
+
const stillThere = new Set(after.map((r) => r.pid));
|
|
406
|
+
for (const d of doomed) {
|
|
407
|
+
if (!stillThere.has(d.pid)) continue;
|
|
408
|
+
report.survivors.push(d.pid);
|
|
409
|
+
try {
|
|
410
|
+
kill(d.pid, "SIGKILL");
|
|
411
|
+
report.signalled.push({
|
|
412
|
+
pid: d.pid,
|
|
413
|
+
signal: "SIGKILL",
|
|
414
|
+
ageSeconds: d.ageSeconds,
|
|
415
|
+
command: d.command,
|
|
416
|
+
});
|
|
417
|
+
} catch {
|
|
418
|
+
// Exited between the re-read and the escalation.
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
return report;
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/** `yes`/`no`, or the classifier's own word when the reading is three-state. */
|
|
425
|
+
const conditionLine = (d: ReapDecision): string =>
|
|
426
|
+
[
|
|
427
|
+
`suite=${d.conditions.suite}`,
|
|
428
|
+
`parent-gone=${d.conditions.parentGone ? "yes" : "no"}`,
|
|
429
|
+
`past-floor=${d.conditions.olderThanFloor ? "yes" : "no"}` +
|
|
430
|
+
`(${d.ageSeconds}s/${d.floorSeconds}s)`,
|
|
431
|
+
`self=${d.conditions.protectedPid ? "yes" : "no"}`,
|
|
432
|
+
].join(" ");
|
|
433
|
+
|
|
434
|
+
/**
|
|
435
|
+
* The report as lines an operator can act on.
|
|
436
|
+
*
|
|
437
|
+
* Every line names a pid, a parent, an age, **all three conditions** and the
|
|
438
|
+
* full argv, because the thing that made #690 expensive was a banner that
|
|
439
|
+
* counted without saying what it counted — and the thing that would make a
|
|
440
|
+
* false positive expensive is a line that names only the first condition
|
|
441
|
+
* that failed. This is the log a decision to arm has to be read off, so it
|
|
442
|
+
* has to be diagnosable on its own: by the time anyone reads it, the process
|
|
443
|
+
* table it describes is gone and no repro is available.
|
|
444
|
+
*/
|
|
445
|
+
export function reapReportLines(report: ReapReport): string[] {
|
|
446
|
+
if (report.reading === "UNMEASURED") {
|
|
447
|
+
return [`ORPHAN-REAP UNMEASURED: ${report.unmeasuredReason ?? "no reason recorded"}`];
|
|
448
|
+
}
|
|
449
|
+
const lines = [
|
|
450
|
+
`ORPHAN-REAP ${report.armed ? "armed" : "dry-run"}: ` +
|
|
451
|
+
`${report.examined} processes examined, ${report.decisions.length} candidates, ` +
|
|
452
|
+
`${report.decisions.filter((d) => d.reap).length} orphaned`,
|
|
453
|
+
];
|
|
454
|
+
for (const d of report.decisions) {
|
|
455
|
+
lines.push(
|
|
456
|
+
` pid=${d.pid} ppid=${d.ppid} age=${d.ageSeconds}s ` +
|
|
457
|
+
`${conditionLine(d)} ${d.reason} ` +
|
|
458
|
+
`${d.reap && !report.armed ? "(would signal) " : ""}${d.command}`,
|
|
459
|
+
);
|
|
460
|
+
}
|
|
461
|
+
for (const s of report.signalled) {
|
|
462
|
+
lines.push(` SIGNAL ${s.signal} pid=${s.pid} age=${s.ageSeconds}s ${s.command}`);
|
|
463
|
+
}
|
|
464
|
+
if (report.escalationUnmeasuredReason) {
|
|
465
|
+
lines.push(` ESCALATION UNMEASURED: ${report.escalationUnmeasuredReason}`);
|
|
466
|
+
}
|
|
467
|
+
return lines;
|
|
468
|
+
}
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ONE binding decides whether the contract-parity check has one name and one
|
|
3
|
+
* home (#637 AC-8).
|
|
4
|
+
*
|
|
5
|
+
* ## Why this is a check and not a comment
|
|
6
|
+
*
|
|
7
|
+
* #626 asked for a `contract-parity` command and said, in the issue body, why
|
|
8
|
+
* it must not be called a preflight: `preflightResults` in `workflows/ship.js`
|
|
9
|
+
* is SSH host reachability and `lib/release-preflight.ts` is npm release
|
|
10
|
+
* verification, so a third meaning of the word would be its own parity defect
|
|
11
|
+
* — the fix for the class committing an instance of the class.
|
|
12
|
+
*
|
|
13
|
+
* A sentence in an issue is a sentence. The thing that stops a second copy of
|
|
14
|
+
* `commandParity` appearing in `workflows/ship.js` eight weeks from now, or a
|
|
15
|
+
* `preflightParity` growing beside `contractParity`, is a scan somebody has to
|
|
16
|
+
* get past.
|
|
17
|
+
*
|
|
18
|
+
* ## Why ONE exported binding and not three
|
|
19
|
+
*
|
|
20
|
+
* There are three properties below and it is tempting to export three
|
|
21
|
+
* predicates. Two deciders that agree are behaviourally one guard — no
|
|
22
|
+
* behavioural test can tell them apart, and a mutation of either leaves the
|
|
23
|
+
* other holding every case up (`.claude/rules/checks-must-be-able-to-fail.md`,
|
|
24
|
+
* fourth shape). Three would be worse. So the three properties are three
|
|
25
|
+
* VIOLATION CLASSES out of one function, and each has an input only it can
|
|
26
|
+
* reach, written down as a separate case in
|
|
27
|
+
* `test/contract-parity-derivation.test.ts`:
|
|
28
|
+
*
|
|
29
|
+
* | Class | The input only it reaches |
|
|
30
|
+
* |---|---|
|
|
31
|
+
* | `DUPLICATE_PARITY_BINDING` | a tree declaring `contractParity` twice |
|
|
32
|
+
* | `PREFLIGHT_NAMED_PARITY` | a tree declaring `preflightParity` beside one correct `contractParity` |
|
|
33
|
+
* | `UNMEASURED_PARITY_SCAN` | a tree declaring no `contractParity` at all |
|
|
34
|
+
*
|
|
35
|
+
* Varying exactly one thing per input is #585's pair discipline: a fixture
|
|
36
|
+
* that moved two of those at once would be red under any of the three and
|
|
37
|
+
* would measure none of them.
|
|
38
|
+
*
|
|
39
|
+
* ## Why the scan refuses when it finds nothing
|
|
40
|
+
*
|
|
41
|
+
* A scan over a directory tree that matched no declarations reports the same
|
|
42
|
+
* empty violation list as a tree that is perfectly in order. That is the
|
|
43
|
+
* third shape, and it is how a regex that stops matching after a reformat
|
|
44
|
+
* becomes a green check nobody can see through. So an empty reading is a
|
|
45
|
+
* REFUSAL naming the scan — `UNMEASURED_PARITY_SCAN` — and the control is the
|
|
46
|
+
* `preflight` family itself: seven declarations in this tree that cannot all
|
|
47
|
+
* vanish, named here because a string that must be present if the store holds
|
|
48
|
+
* anything is the only thing that distinguishes an absent problem from an
|
|
49
|
+
* absent instrument (`.claude/rules/checks-must-be-able-to-fail.md`, #646/#657).
|
|
50
|
+
*/
|
|
51
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
|
|
52
|
+
import { join } from "path";
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The directories AC-8 names. `workflows/` is in the list because it is where
|
|
56
|
+
* the second copy would go: `workflows/ship.js` cannot import (#69), so every
|
|
57
|
+
* comparison it needs is inlined, and an inlined parity check is a second
|
|
58
|
+
* decider by construction.
|
|
59
|
+
*/
|
|
60
|
+
export const PARITY_SCAN_DIRS = ["lib", "scripts", "gates", "workflows"] as const;
|
|
61
|
+
|
|
62
|
+
/** The one name the contract-parity entry point is allowed to have. */
|
|
63
|
+
export const PARITY_BINDING = "contractParity";
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* The word a parity binding must never wear, and the word that proves the
|
|
67
|
+
* scan is reading something.
|
|
68
|
+
*/
|
|
69
|
+
export const FOREIGN_PARITY_WORD = "preflight";
|
|
70
|
+
|
|
71
|
+
export const PARITY_VIOLATION_CLASSES = [
|
|
72
|
+
"DUPLICATE_PARITY_BINDING",
|
|
73
|
+
"PREFLIGHT_NAMED_PARITY",
|
|
74
|
+
"UNMEASURED_PARITY_SCAN",
|
|
75
|
+
] as const;
|
|
76
|
+
export type ParityViolationClass = (typeof PARITY_VIOLATION_CLASSES)[number];
|
|
77
|
+
|
|
78
|
+
/** A value declaration — the things that can decide something. */
|
|
79
|
+
const DECLARATION =
|
|
80
|
+
/(?:^|\n)\s*(export\s+)?(?:default\s+)?(?:async\s+)?(?:function\s+|class\s+|const\s+|let\s+|var\s+)([A-Za-z_$][A-Za-z0-9_$]*)/g;
|
|
81
|
+
|
|
82
|
+
export interface ParityDeclaration {
|
|
83
|
+
name: string;
|
|
84
|
+
/** Repo-relative path. */
|
|
85
|
+
file: string;
|
|
86
|
+
line: number;
|
|
87
|
+
/**
|
|
88
|
+
* AC-8 is about the EXPORTED symbol, and the distinction is load-bearing in
|
|
89
|
+
* both directions: a module-local `const parity` is nobody's second decider,
|
|
90
|
+
* and `preflightResults` — a local in `workflows/ship.js` — is one of the
|
|
91
|
+
* seven declarations that prove this scan is reading the tree at all.
|
|
92
|
+
*/
|
|
93
|
+
exported: boolean;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function walk(dir: string, out: string[] = []): string[] {
|
|
97
|
+
if (!existsSync(dir)) return out;
|
|
98
|
+
for (const entry of readdirSync(dir)) {
|
|
99
|
+
if (entry === "node_modules" || entry.startsWith(".")) continue;
|
|
100
|
+
const p = join(dir, entry);
|
|
101
|
+
if (statSync(p).isDirectory()) walk(p, out);
|
|
102
|
+
else if (/\.(ts|js)$/.test(p) && !/\.test\.(ts|js)$/.test(p)) out.push(p);
|
|
103
|
+
}
|
|
104
|
+
return out;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Every value declaration in the four directories whose name contains `word`,
|
|
109
|
+
* case-insensitively.
|
|
110
|
+
*
|
|
111
|
+
* Exported for the cases to read, NOT as a second decider: nothing in this
|
|
112
|
+
* module's verdict is computed anywhere but `parityBindingViolations`, so
|
|
113
|
+
* there is one thing to mutate. A case that asserted on this reading instead
|
|
114
|
+
* of on the violations would be asserting the input it just supplied.
|
|
115
|
+
*/
|
|
116
|
+
export function declarationsNaming(root: string, word: string): ParityDeclaration[] {
|
|
117
|
+
const needle = word.toLowerCase();
|
|
118
|
+
const out: ParityDeclaration[] = [];
|
|
119
|
+
for (const dir of PARITY_SCAN_DIRS) {
|
|
120
|
+
for (const abs of walk(join(root, dir))) {
|
|
121
|
+
const text = readFileSync(abs, "utf-8");
|
|
122
|
+
const relative = abs.slice(root.endsWith("/") ? root.length : root.length + 1);
|
|
123
|
+
for (const m of text.matchAll(DECLARATION)) {
|
|
124
|
+
if (!m[2].toLowerCase().includes(needle)) continue;
|
|
125
|
+
out.push({
|
|
126
|
+
name: m[2],
|
|
127
|
+
file: relative,
|
|
128
|
+
line: text.slice(0, m.index!).split("\n").length,
|
|
129
|
+
exported: m[1] !== undefined,
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
return out;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The whole verdict. Empty means the contract-parity binding has one name and
|
|
139
|
+
* one home; every string names its class first so a reader can tell the three
|
|
140
|
+
* apart without parsing prose.
|
|
141
|
+
*/
|
|
142
|
+
export function parityBindingViolations(root: string): string[] {
|
|
143
|
+
const violations: string[] = [];
|
|
144
|
+
const parity = declarationsNaming(root, "parity");
|
|
145
|
+
const foreign = declarationsNaming(root, FOREIGN_PARITY_WORD);
|
|
146
|
+
|
|
147
|
+
// The instrument, before any finding. An empty reading over four
|
|
148
|
+
// directories is not a clean tree, and a reading that found no `preflight`
|
|
149
|
+
// in a tree that has seven of them is a scan that has stopped working.
|
|
150
|
+
const exported = parity.filter(d => d.exported);
|
|
151
|
+
const entry = exported.filter(d => d.name === PARITY_BINDING);
|
|
152
|
+
if (entry.length === 0) {
|
|
153
|
+
violations.push(
|
|
154
|
+
`UNMEASURED_PARITY_SCAN: the scan over ${PARITY_SCAN_DIRS.join(", ")} found no declaration of ` +
|
|
155
|
+
`\`${PARITY_BINDING}\` at all. A comparison that could not be performed is not a comparison that ` +
|
|
156
|
+
`passed — either the binding was renamed, or this scan has stopped reading the tree ` +
|
|
157
|
+
`(it saw ${parity.length} parity declaration(s) and ${foreign.length} ${FOREIGN_PARITY_WORD} declaration(s))`,
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
// One name, one home. Counted per name rather than only for the entry
|
|
162
|
+
// point: a second `commandParity` is the same defect one level down, and
|
|
163
|
+
// the category runners are what `contractParity` dispatches to.
|
|
164
|
+
//
|
|
165
|
+
// **The entry point is counted whether or not it is exported, and that is
|
|
166
|
+
// the fifth shape applied in advance.** AC-8's words are "the exported
|
|
167
|
+
// symbol is declared exactly once", so the cheapest repair when this goes
|
|
168
|
+
// red is to delete the `export` keyword from the duplicate — one word, the
|
|
169
|
+
// symptom disappears, and the tree still holds two deciders answering one
|
|
170
|
+
// question, each called from inside its own module. A check that counted
|
|
171
|
+
// only exported declarations would CERTIFY that repair. A module-local
|
|
172
|
+
// `const parity` is a different matter and stays out of this: it is nobody's
|
|
173
|
+
// second decider, which is why the widening is to the entry-point NAME and
|
|
174
|
+
// not to every name containing the word.
|
|
175
|
+
const entryAnywhere = parity.filter(d => d.name === PARITY_BINDING);
|
|
176
|
+
const counted = [...exported, ...entryAnywhere.filter(d => !d.exported)];
|
|
177
|
+
const byName = new Map<string, ParityDeclaration[]>();
|
|
178
|
+
for (const d of counted) {
|
|
179
|
+
if (!byName.has(d.name)) byName.set(d.name, []);
|
|
180
|
+
byName.get(d.name)!.push(d);
|
|
181
|
+
}
|
|
182
|
+
for (const [name, found] of [...byName].sort(([a], [b]) => a.localeCompare(b))) {
|
|
183
|
+
if (found.length <= 1) continue;
|
|
184
|
+
violations.push(
|
|
185
|
+
`DUPLICATE_PARITY_BINDING: \`${name}\` is declared ${found.length} times — ` +
|
|
186
|
+
`${found.map(d => `${d.file}:${d.line}`).join(", ")}. Two deciders answering one question about one ` +
|
|
187
|
+
`input are behaviourally one guard, and a mutation of either leaves the other holding the case up (#637 AC-8)`,
|
|
188
|
+
);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
// Not a third preflight. The repository already has two unrelated meanings
|
|
192
|
+
// of that word; a parity binding wearing it would be #626's own subject,
|
|
193
|
+
// committed by the fix for it.
|
|
194
|
+
for (const d of exported) {
|
|
195
|
+
if (!d.name.toLowerCase().includes(FOREIGN_PARITY_WORD)) continue;
|
|
196
|
+
violations.push(
|
|
197
|
+
`PREFLIGHT_NAMED_PARITY: \`${d.name}\` at ${d.file}:${d.line} decides parity under the name ` +
|
|
198
|
+
`\`${FOREIGN_PARITY_WORD}\`. This repository already has two unrelated things wearing that name — ` +
|
|
199
|
+
`SSH host reachability in workflows/ship.js and npm release verification in lib/release-preflight.ts — ` +
|
|
200
|
+
`and a third meaning is its own parity defect (#626, #637 AC-8)`,
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
return violations;
|
|
205
|
+
}
|