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.
- 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 +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- 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 +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- 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 +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- 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/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- 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 +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -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/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -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-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- 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 +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- 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/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -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 +411 -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-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- 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/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- 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
|
+
}
|