rungate 0.5.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.
Files changed (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The project's one day stamp (#600).
3
+ *
4
+ * A LEAF module, in the shape `lib/git-dates.ts` established (#508): one
5
+ * exported binding, no relative imports, so there is exactly one thing to
6
+ * mutate and every call site names the same rule.
7
+ *
8
+ * ## Why this exists
9
+ *
10
+ * `new Date().toISOString().split("T")[0]` is the UTC calendar day. Between
11
+ * 20:00 EDT and midnight that is TOMORROW, so an evening session stamps work
12
+ * on a day it did not happen. Twenty sites in this tree did it, and the one
13
+ * that mattered was `scripts/update-project-state.ts`, whose stamp is read
14
+ * back by the pre-commit hook: the hook only produced a staged diff when the
15
+ * computed stamp differed from the stored one, so the DA-owned-file violation
16
+ * of #599 fired for about four hours a day and the other twenty hours of
17
+ * green runs were not evidence of compliance. A date that is wrong for four
18
+ * hours a day is worse than one that is wrong always, because the twenty
19
+ * green hours look like a passing check.
20
+ *
21
+ * ## What it is NOT for
22
+ *
23
+ * Instants. `new Date().toISOString()` — the whole timestamp — is correct and
24
+ * stays correct: an instant is zone-free and UTC is its canonical spelling.
25
+ * This module is only about collapsing an instant to the calendar day a
26
+ * HUMAN would write next to it, and that question has no answer without a
27
+ * zone.
28
+ *
29
+ * ## Why Intl rather than getFullYear/getMonth/getDate
30
+ *
31
+ * The local-getter form is three calls that must each be padded correctly and
32
+ * cannot be pointed at another zone, so a test for the defect would have to
33
+ * mutate `process.env.TZ` and could never assert the explicit-zone case.
34
+ * `formatToParts` answers both from one binding, and `calendar`/
35
+ * `numberingSystem` are pinned so a host default cannot hand back a
36
+ * non-Gregorian year or non-Latin digits.
37
+ */
38
+
39
+ const PART_FORMAT: Intl.DateTimeFormatOptions = {
40
+ calendar: "gregory",
41
+ numberingSystem: "latn",
42
+ year: "numeric",
43
+ month: "2-digit",
44
+ day: "2-digit",
45
+ };
46
+
47
+ /**
48
+ * The calendar day `at` falls on, in `timeZone`, as `YYYY-MM-DD`.
49
+ *
50
+ * @param at the instant to collapse. Defaults to now.
51
+ * @param timeZone an IANA zone. Defaults to the process zone, which is what
52
+ * every call site in this repo wants — the day the person
53
+ * running the command is living in.
54
+ */
55
+ export function localCalendarDay(at: Date = new Date(), timeZone?: string): string {
56
+ if (Number.isNaN(at.getTime())) {
57
+ // Intl renders an invalid date as literal "Invalid Date" parts rather
58
+ // than throwing, and a frontmatter block reading `updated: Invalid Date`
59
+ // is worse than a crash: it is written, committed, and read as a date.
60
+ throw new Error("localCalendarDay: invalid Date — nothing to stamp");
61
+ }
62
+ const parts = new Intl.DateTimeFormat(
63
+ "en-US",
64
+ timeZone ? { ...PART_FORMAT, timeZone } : PART_FORMAT,
65
+ ).formatToParts(at);
66
+ const of = (type: Intl.DateTimeFormatPartTypes) => parts.find(p => p.type === type)?.value;
67
+ const year = of("year");
68
+ const month = of("month");
69
+ const day = of("day");
70
+ if (!year || !month || !day) {
71
+ // Only reachable if a host's ICU stops emitting a requested part. Loud,
72
+ // because the alternative is `undefined-undefined-undefined` in a doc.
73
+ throw new Error(
74
+ `localCalendarDay: Intl did not return year/month/day for ${timeZone ?? "the process zone"}`,
75
+ );
76
+ }
77
+ return `${year.padStart(4, "0")}-${month}-${day}`;
78
+ }
@@ -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
+ }