@oscaner-skills/cdd-engine 3.0.0 → 3.0.1
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/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -1,573 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/face/termination.ts
|
|
2
|
-
// The process seam of one dispatch — spawn → (sample → judge → kill, T2/T3) →
|
|
3
|
-
// collect. The seam's interface is `ChildRunner`; `Terminator` is its production
|
|
4
|
-
// implementation (execa's asynchronous face, which owns process-group creation,
|
|
5
|
-
// group kill, the SIGTERM → SIGKILL escalation, the parent-exit cleanup and the
|
|
6
|
-
// wall-clock ceiling — the engine holds no signal logic of its own).
|
|
7
|
-
//
|
|
8
|
-
// The seam's two ends are value objects, so the whole child lifecycle speaks one
|
|
9
|
-
// shape:
|
|
10
|
-
// · `ChildRun` — one dispatch's full context (command/args/cwd + the heartbeat
|
|
11
|
-
// path the sampler writes + the termination policy of the phase);
|
|
12
|
-
// · `ChildOutcome` — the child's result (its own exit code, verbatim streams)
|
|
13
|
-
// plus the `termination` fact: non-null ⟺ the round was cut short. The
|
|
14
|
-
// terminated round's downstream judgments all read that one fact, never the
|
|
15
|
-
// exit code (a never-spawned child has neither an exit code nor a termination).
|
|
16
|
-
//
|
|
17
|
-
// Module-level exports are types / the value object / the class — zero
|
|
18
|
-
// behavior-carrying bare functions.
|
|
19
|
-
|
|
20
|
-
import { execFileSync } from "node:child_process";
|
|
21
|
-
import { readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
22
|
-
import path from "node:path";
|
|
23
|
-
import { execa } from "execa";
|
|
24
|
-
import type {
|
|
25
|
-
RoundPhase,
|
|
26
|
-
Sample,
|
|
27
|
-
SampleRecord,
|
|
28
|
-
StallVerdict,
|
|
29
|
-
TerminationCause,
|
|
30
|
-
} from "../session/ledger.ts";
|
|
31
|
-
|
|
32
|
-
// ---------------------------------------------------------------------------
|
|
33
|
-
// the seam — one dispatch's input, result and runner
|
|
34
|
-
// ---------------------------------------------------------------------------
|
|
35
|
-
|
|
36
|
-
/** How a round ended when it did not end by itself — the derived cause plus the
|
|
37
|
-
* last observed sample (the postmortem pair the crash record carries; the sample
|
|
38
|
-
* rides the outcome in memory, never re-read from the heartbeat file). `unknown`
|
|
39
|
-
* is the unattributable fallback of the derivation. */
|
|
40
|
-
export interface Termination {
|
|
41
|
-
cause: TerminationCause | "unknown";
|
|
42
|
-
lastSample: SampleRecord | null;
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
/** The facts the termination derivation rules on — the execa result face plus the
|
|
46
|
-
* engine's own stall-kill flag and the sampling loop's last observation. Named
|
|
47
|
-
* fields, because the three adjacent booleans/strings would swap silently as
|
|
48
|
-
* positional parameters. */
|
|
49
|
-
export interface TerminationFacts {
|
|
50
|
-
timedOut: boolean;
|
|
51
|
-
killedByStall: boolean;
|
|
52
|
-
signal: string | undefined;
|
|
53
|
-
isTerminated: boolean;
|
|
54
|
-
lastSample: SampleRecord | null;
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/** One dispatch's result over the child-runner seam — the child's own exit code
|
|
58
|
-
* (null when it never spawned or was signalled) and its verbatim streams, plus the
|
|
59
|
-
* termination fact. `termination !== null` ⟺ the round was cut short (the wall-clock
|
|
60
|
-
* ceiling, the engine's own kill, or a signal on the child) — a spawn failure has
|
|
61
|
-
* neither an exit code nor a termination, so it rides the ordinary child-exit face. */
|
|
62
|
-
export interface ChildOutcome {
|
|
63
|
-
code: number | null;
|
|
64
|
-
stdout: string;
|
|
65
|
-
stderr: string;
|
|
66
|
-
termination: Termination | null;
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
/** One dispatch's full context — everything the runner needs, and nothing that
|
|
70
|
-
* reaches back into the session: the spawned command, the heartbeat path the
|
|
71
|
-
* sampler writes for this dispatch, and the phase's termination policy. The
|
|
72
|
-
* caller derives `cwd` and `heartbeatPath` from the one workspace it holds, so
|
|
73
|
-
* both paths share one source; the same `cwd` is the spawn directory AND the
|
|
74
|
-
* scanned tree root (the "scan root ≡ the child's cwd" structural guarantee). */
|
|
75
|
-
export interface ChildRun {
|
|
76
|
-
command: string;
|
|
77
|
-
args: readonly string[];
|
|
78
|
-
cwd: string;
|
|
79
|
-
heartbeatPath: string;
|
|
80
|
-
policy: TerminationPolicy;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
/** The child-runner seam — the production terminator and the test stub implement
|
|
84
|
-
* this one shape; the lifecycle sees only the interface. A failed child rides the
|
|
85
|
-
* result, never a throw (fail-open). */
|
|
86
|
-
export interface ChildRunner {
|
|
87
|
-
run(run: ChildRun): Promise<ChildOutcome>;
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
// ---------------------------------------------------------------------------
|
|
91
|
-
// the constant single source — budget and timing, per dispatch phase
|
|
92
|
-
// ---------------------------------------------------------------------------
|
|
93
|
-
|
|
94
|
-
/** TerminationPolicy — the budget/timing constant single source (code constants
|
|
95
|
-
* only: zero environment variables, zero config plane). The budget key set IS the
|
|
96
|
-
* dispatch-phase set, so no phase falls through to another phase's ceiling. The
|
|
97
|
-
* timing pair is injectable (the production values are the constants below; tests
|
|
98
|
-
* inject tiny ones, so an end-to-end stall case need not wait out the real window). */
|
|
99
|
-
export class TerminationPolicy {
|
|
100
|
-
/** The per-phase wall-clock ceiling (ms) — the implement round is the long one. */
|
|
101
|
-
static readonly BUDGET_MS: Readonly<Record<RoundPhase, number>> = {
|
|
102
|
-
implement: 6 * 60 * 60 * 1000,
|
|
103
|
-
review: 3 * 60 * 60 * 1000,
|
|
104
|
-
fix: 3 * 60 * 60 * 1000,
|
|
105
|
-
"branch-review": 3 * 60 * 60 * 1000,
|
|
106
|
-
};
|
|
107
|
-
/** The stall window (ms) — how long a round may make no progress before the
|
|
108
|
-
* judge rules it stalled (not per phase: "no progress" means the same thing on
|
|
109
|
-
* every phase). */
|
|
110
|
-
static readonly IDLE_WINDOW_MS = 30 * 60 * 1000;
|
|
111
|
-
/** The sampling cadence (ms) — one sample tick per interval. */
|
|
112
|
-
static readonly SAMPLE_INTERVAL_MS = 60 * 1000;
|
|
113
|
-
|
|
114
|
-
/** The round's wall-clock ceiling (ms) — the execa `timeout` value. */
|
|
115
|
-
readonly budgetMs: number;
|
|
116
|
-
/** The stall window the judge rules on (ms). */
|
|
117
|
-
readonly idleWindowMs: number;
|
|
118
|
-
/** The sampler's tick interval (ms). */
|
|
119
|
-
readonly sampleIntervalMs: number;
|
|
120
|
-
|
|
121
|
-
constructor(
|
|
122
|
-
budgetMs: number,
|
|
123
|
-
idleWindowMs: number = TerminationPolicy.IDLE_WINDOW_MS,
|
|
124
|
-
sampleIntervalMs: number = TerminationPolicy.SAMPLE_INTERVAL_MS,
|
|
125
|
-
) {
|
|
126
|
-
this.budgetMs = budgetMs;
|
|
127
|
-
this.idleWindowMs = idleWindowMs;
|
|
128
|
-
this.sampleIntervalMs = sampleIntervalMs;
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
/** The production policy of one dispatch phase — its own budget key plus the
|
|
132
|
-
* shared timing constants. */
|
|
133
|
-
static of(phase: RoundPhase): TerminationPolicy {
|
|
134
|
-
return new TerminationPolicy(TerminationPolicy.BUDGET_MS[phase]);
|
|
135
|
-
}
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
// ---------------------------------------------------------------------------
|
|
139
|
-
// the stall judge — the running judgment over one dispatch, pure logic
|
|
140
|
-
// ---------------------------------------------------------------------------
|
|
141
|
-
|
|
142
|
-
/** StallJudge — is this dispatch still moving? Not a comparison of two samples but a
|
|
143
|
-
* judgment over the round: the judge holds its own accumulating state and is fed one
|
|
144
|
-
* tick at a time through `observe`, which returns the tick's verdict. Zero I/O: it
|
|
145
|
-
* reads the two legs of a `Sample` and nothing else (the OS reads live in `Sampler`),
|
|
146
|
-
* so its truth table is testable without a process or a tree. Both the idle window
|
|
147
|
-
* and the spawn instant are injected — the window never comes from a module constant
|
|
148
|
-
* and the clock never comes from the wall (a stall case must not wait out the real
|
|
149
|
-
* half hour), and the spawn instant seeds the idle clock.
|
|
150
|
-
*
|
|
151
|
-
* The rules, in the order they are applied:
|
|
152
|
-
* · an unreadable leg (`null`) → `unknown`, and unknown never kills (fail-open: no
|
|
153
|
-
* reading of a leg means no evidence of a stall, and an unreadable tick carries no
|
|
154
|
-
* observation either way);
|
|
155
|
-
* · CPU above the PREVIOUS observation, or mtime above the HISTORICAL MAXIMUM →
|
|
156
|
-
* `progress`, and the idle clock restarts at this tick;
|
|
157
|
-
* · no progress and the window is still open → `idled`;
|
|
158
|
-
* · no progress and the window is spent → `stalled` (the kill).
|
|
159
|
-
* Neither leg authorizes a kill alone (`unknown` covers the unreadable case) and
|
|
160
|
-
* output activity is deliberately NOT a signal: a thinking child is silent, and using
|
|
161
|
-
* silence against it would kill a child that is working. */
|
|
162
|
-
export class StallJudge {
|
|
163
|
-
readonly #idleWindowMs: number;
|
|
164
|
-
/** The instant of the last progress — the spawn instant until the first one. */
|
|
165
|
-
#idleSince: number;
|
|
166
|
-
/** The previous tick's process-group CPU (ms) — `null` until the first readable one. */
|
|
167
|
-
#lastCpuMs: number | null = null;
|
|
168
|
-
/** The largest mtime (ms) the tree leg has ever reported. */
|
|
169
|
-
#maxMtimeMs: number | null = null;
|
|
170
|
-
|
|
171
|
-
constructor(idleWindowMs: number, spawnedAt: number) {
|
|
172
|
-
this.#idleWindowMs = idleWindowMs;
|
|
173
|
-
this.#idleSince = spawnedAt;
|
|
174
|
-
}
|
|
175
|
-
|
|
176
|
-
/** Judge one tick: feed the tick's sample and the instant it was taken. */
|
|
177
|
-
observe(sample: Sample, now: number): StallVerdict {
|
|
178
|
-
const cpuMs = sample.groupCpuMs;
|
|
179
|
-
const mtimeMs = sample.newestMtimeMs;
|
|
180
|
-
// Both legs must be readable to judge at all.
|
|
181
|
-
if (cpuMs === null || mtimeMs === null) return "unknown";
|
|
182
|
-
// Progress is an advance over what has already been seen — this CPU over the
|
|
183
|
-
// previous observation, this mtime over the historical maximum. The first readable
|
|
184
|
-
// tick has neither, so it can never be a progress tick: the idle clock has been
|
|
185
|
-
// running since the spawn instant, exactly as if that tick had been flat.
|
|
186
|
-
const advanced =
|
|
187
|
-
(this.#lastCpuMs !== null && cpuMs > this.#lastCpuMs) ||
|
|
188
|
-
(this.#maxMtimeMs !== null && mtimeMs > this.#maxMtimeMs);
|
|
189
|
-
this.#lastCpuMs = cpuMs;
|
|
190
|
-
if (this.#maxMtimeMs === null || mtimeMs > this.#maxMtimeMs) this.#maxMtimeMs = mtimeMs;
|
|
191
|
-
if (advanced) {
|
|
192
|
-
this.#idleSince = now;
|
|
193
|
-
return "progress";
|
|
194
|
-
}
|
|
195
|
-
return now - this.#idleSince < this.#idleWindowMs ? "idled" : "stalled";
|
|
196
|
-
}
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
// ---------------------------------------------------------------------------
|
|
200
|
-
// the sampler — the two legs' heavy lifting (the only OS I/O of the stall face)
|
|
201
|
-
// ---------------------------------------------------------------------------
|
|
202
|
-
|
|
203
|
-
/** Sampler — one dispatch's two legs, read once per tick: the process group's
|
|
204
|
-
* cumulative CPU and the newest content mtime of the scanned tree. The I/O lives
|
|
205
|
-
* here and the judgment lives in `StallJudge`, so each face is testable on its own
|
|
206
|
-
* (the truth table without a process, the fail-open `null` without a judge).
|
|
207
|
-
*
|
|
208
|
-
* · The group id is the child's own pid, never recomputed: `killDescendants` forces
|
|
209
|
-
* the spawn-layer detachment, so the child IS its process group leader — the same
|
|
210
|
-
* fact execa's own `process.kill(-pid)` kill rides.
|
|
211
|
-
* · The scan root is the child's cwd (the repo root), so the "scan root ≡ child cwd"
|
|
212
|
-
* correspondence is structural.
|
|
213
|
-
* · `exclude` is the engine's own writes — `Sampler.excludesFor` is its single
|
|
214
|
-
* source: the repo's `.git/` and the dispatch's heartbeat file. The rest of
|
|
215
|
-
* `.kairos/` is NOT excluded: a child's handoff draft there is real progress. */
|
|
216
|
-
export class Sampler {
|
|
217
|
-
/** The deepest tree level the walk descends to. */
|
|
218
|
-
static readonly MAX_DEPTH = 32;
|
|
219
|
-
/** The VCS internal every scan skips — its mtime is never a round's progress. */
|
|
220
|
-
static readonly VCS_DIR = ".git";
|
|
221
|
-
/** A `ps -o time=` reading: `[DD-][HH:]MM:SS[.ff]` (BSD gives centiseconds, Linux
|
|
222
|
-
* whole seconds — both ride the same pattern). */
|
|
223
|
-
static readonly TIME_PATTERN =
|
|
224
|
-
/^(?:(\d+)-)?(?:(\d+):(\d+):(\d+(?:\.\d+)?)|(\d+):(\d+(?:\.\d+)?))$/;
|
|
225
|
-
|
|
226
|
-
readonly #pgid: number;
|
|
227
|
-
readonly #scanRoot: string;
|
|
228
|
-
readonly #exclude: ReadonlySet<string>;
|
|
229
|
-
|
|
230
|
-
constructor(options: { pgid: number; scanRoot: string; exclude: readonly string[] }) {
|
|
231
|
-
this.#pgid = options.pgid;
|
|
232
|
-
// Absolute, normalized forms on both sides of the comparison below, so an
|
|
233
|
-
// exclusion matches the walked path it names.
|
|
234
|
-
this.#scanRoot = path.resolve(options.scanRoot);
|
|
235
|
-
this.#exclude = new Set(options.exclude.map((entry) => path.resolve(entry)));
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
/** The exclusion single source for one dispatch: the repo's VCS internal plus the
|
|
239
|
-
* heartbeat path the engine itself writes (a tick must never self-certify). */
|
|
240
|
-
static excludesFor(scanRoot: string, heartbeatPath: string): readonly string[] {
|
|
241
|
-
return [path.join(scanRoot, Sampler.VCS_DIR), heartbeatPath];
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
/** Read both legs of this tick — each independently fail-open: a leg the platform
|
|
245
|
-
* cannot read is `null`, never a fabricated reading. */
|
|
246
|
-
probe(): Sample {
|
|
247
|
-
return { groupCpuMs: this.#groupCpuMs(), newestMtimeMs: this.#newestMtimeMs() };
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
/** The process group's cumulative CPU (ms), summed over the group's processes. A
|
|
251
|
-
* non-zero `ps` exit (no such group, or no `ps` at all) or any unparseable line
|
|
252
|
-
* makes the leg unreadable — `null`. An empty reading is unreadable too: a group
|
|
253
|
-
* with no observable member is not evidence of zero CPU. */
|
|
254
|
-
#groupCpuMs(): number | null {
|
|
255
|
-
let output: string;
|
|
256
|
-
try {
|
|
257
|
-
output = execFileSync("ps", ["-o", "time=", "-g", String(this.#pgid)], {
|
|
258
|
-
encoding: "utf8",
|
|
259
|
-
// stdout only: `ps`'s own complaint about an unknown group is not a reading,
|
|
260
|
-
// and it must never reach the engine's stderr channel.
|
|
261
|
-
stdio: ["ignore", "pipe", "ignore"],
|
|
262
|
-
});
|
|
263
|
-
} catch {
|
|
264
|
-
return null;
|
|
265
|
-
}
|
|
266
|
-
const lines = output
|
|
267
|
-
.split("\n")
|
|
268
|
-
.map((line) => line.trim())
|
|
269
|
-
.filter((line) => line.length > 0);
|
|
270
|
-
if (lines.length === 0) return null;
|
|
271
|
-
let total = 0;
|
|
272
|
-
for (const line of lines) {
|
|
273
|
-
const ms = Sampler.#parseCpuTime(line);
|
|
274
|
-
if (ms === null) return null;
|
|
275
|
-
total += ms;
|
|
276
|
-
}
|
|
277
|
-
return total;
|
|
278
|
-
}
|
|
279
|
-
|
|
280
|
-
/** One `time=` reading as milliseconds — `null` when the text is not that format. */
|
|
281
|
-
static #parseCpuTime(text: string): number | null {
|
|
282
|
-
const match = Sampler.TIME_PATTERN.exec(text);
|
|
283
|
-
if (match === null) return null;
|
|
284
|
-
const days = Number(match[1] ?? 0);
|
|
285
|
-
const hours = Number(match[2] ?? 0);
|
|
286
|
-
const minutes = Number(match[3] ?? match[5] ?? 0);
|
|
287
|
-
const seconds = Number(match[4] ?? match[6] ?? 0);
|
|
288
|
-
return (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
|
|
289
|
-
}
|
|
290
|
-
|
|
291
|
-
/** The newest content mtime (ms) in the scanned tree — `null` when the walk cannot
|
|
292
|
-
* complete (an unreadable directory anywhere makes the whole leg unreadable rather
|
|
293
|
-
* than under-reporting). */
|
|
294
|
-
#newestMtimeMs(): number | null {
|
|
295
|
-
try {
|
|
296
|
-
return this.#newestIn(this.#scanRoot, 0);
|
|
297
|
-
} catch {
|
|
298
|
-
return null;
|
|
299
|
-
}
|
|
300
|
-
}
|
|
301
|
-
|
|
302
|
-
/** The recursive descent — symlinks and the engine's own paths skipped, `MAX_DEPTH`
|
|
303
|
-
* as the floor of the walk. */
|
|
304
|
-
#newestIn(dir: string, depth: number): number | null {
|
|
305
|
-
if (depth > Sampler.MAX_DEPTH) return null;
|
|
306
|
-
let newest: number | null = null;
|
|
307
|
-
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
308
|
-
const child = path.join(dir, entry.name);
|
|
309
|
-
// A symlink is never followed (it can leave the tree outright); an excluded path
|
|
310
|
-
// is the engine's own write.
|
|
311
|
-
if (entry.isSymbolicLink() || this.#exclude.has(child)) continue;
|
|
312
|
-
if (entry.isDirectory()) {
|
|
313
|
-
const nested = this.#newestIn(child, depth + 1);
|
|
314
|
-
if (nested !== null && (newest === null || nested > newest)) newest = nested;
|
|
315
|
-
continue;
|
|
316
|
-
}
|
|
317
|
-
// Content mtimes only: a directory's own mtime moves on entry churn, which the
|
|
318
|
-
// CPU leg already reflects as work — and the heartbeat's first creation would
|
|
319
|
-
// otherwise bump its directory and self-certify a progress tick.
|
|
320
|
-
const mtimeMs = statSync(child).mtimeMs;
|
|
321
|
-
if (newest === null || mtimeMs > newest) newest = mtimeMs;
|
|
322
|
-
}
|
|
323
|
-
return newest;
|
|
324
|
-
}
|
|
325
|
-
}
|
|
326
|
-
|
|
327
|
-
// ---------------------------------------------------------------------------
|
|
328
|
-
// the sampling loop — the dispatch's heartbeat trail (§3.4)
|
|
329
|
-
// ---------------------------------------------------------------------------
|
|
330
|
-
|
|
331
|
-
/** The sampling loop of one dispatch — the cadence that wraps the running child: one
|
|
332
|
-
* sample the moment the child is spawned, then one per `intervalMs`. Each tick reads
|
|
333
|
-
* the two legs through the `Sampler`, has the `StallJudge` rule on them, and
|
|
334
|
-
* overwrites the dispatch's heartbeat file with the resulting `SampleRecord` — the
|
|
335
|
-
* trail a human reads after a round was cut short. A `stalled` verdict fires the
|
|
336
|
-
* loop's `onStall` callback once — the Terminator's kill trigger (the engine's own
|
|
337
|
-
* group kill; the SIGTERM → SIGKILL escalation is execa's).
|
|
338
|
-
*
|
|
339
|
-
* The interval is unref'd: the engine's own sampling must never be the reason the
|
|
340
|
-
* parent process stays alive (the dispatch awaits the child, not the cadence). The
|
|
341
|
-
* heartbeat write is a plain overwrite, deliberately NOT a write-then-rename: a
|
|
342
|
-
* temporary file would sit inside the scanned tree and its own creation would certify
|
|
343
|
-
* "progress" — the very self-report the exclusion exists to prevent. Both the write
|
|
344
|
-
* and the removal are fail-open: the trail is a diagnostic, never a dispatch's fate.
|
|
345
|
-
*
|
|
346
|
-
* The last observation is held in memory (`lastSample`): a terminated round's crash
|
|
347
|
-
* record takes it from there, never by re-reading the file the engine itself wrote. */
|
|
348
|
-
class SamplingLoop {
|
|
349
|
-
readonly #sampler: Sampler;
|
|
350
|
-
readonly #judge: StallJudge;
|
|
351
|
-
readonly #heartbeatPath: string;
|
|
352
|
-
readonly #intervalMs: number;
|
|
353
|
-
/** The stall trigger — called once on the first `stalled` verdict (the kill). */
|
|
354
|
-
readonly #onStall?: () => void;
|
|
355
|
-
/** Whether the stall verdict has already fired — one kill per dispatch. */
|
|
356
|
-
#stallFired = false;
|
|
357
|
-
/** The most recent observation — the postmortem sample of a terminated round. */
|
|
358
|
-
#last: SampleRecord | null = null;
|
|
359
|
-
#timer: ReturnType<typeof setInterval> | null = null;
|
|
360
|
-
|
|
361
|
-
constructor(options: {
|
|
362
|
-
sampler: Sampler;
|
|
363
|
-
judge: StallJudge;
|
|
364
|
-
heartbeatPath: string;
|
|
365
|
-
intervalMs: number;
|
|
366
|
-
onStall?: () => void;
|
|
367
|
-
}) {
|
|
368
|
-
this.#sampler = options.sampler;
|
|
369
|
-
this.#judge = options.judge;
|
|
370
|
-
this.#heartbeatPath = options.heartbeatPath;
|
|
371
|
-
this.#intervalMs = options.intervalMs;
|
|
372
|
-
this.#onStall = options.onStall;
|
|
373
|
-
}
|
|
374
|
-
|
|
375
|
-
/** Sample at once (the spawn instant has just passed — a round is never observed
|
|
376
|
-
* only from the first interval on) and start the cadence. */
|
|
377
|
-
start(): void {
|
|
378
|
-
this.#tick(Date.now());
|
|
379
|
-
this.#timer = setInterval(() => this.#tick(Date.now()), this.#intervalMs);
|
|
380
|
-
// Never hold the parent process open for the engine's own sampling.
|
|
381
|
-
this.#timer.unref();
|
|
382
|
-
}
|
|
383
|
-
|
|
384
|
-
/** The loop's last observation (null when no tick was ever taken) — the sample a
|
|
385
|
-
* terminated round's crash record carries, from memory. */
|
|
386
|
-
lastSample(): SampleRecord | null {
|
|
387
|
-
return this.#last;
|
|
388
|
-
}
|
|
389
|
-
|
|
390
|
-
/** End the loop at the dispatch's terminal state: the cadence stops, and the
|
|
391
|
-
* heartbeat is removed iff the round ended by itself — a terminated round's file
|
|
392
|
-
* stays for a human's postmortem. */
|
|
393
|
-
stop(endedByItself: boolean): void {
|
|
394
|
-
if (this.#timer !== null) {
|
|
395
|
-
clearInterval(this.#timer);
|
|
396
|
-
this.#timer = null;
|
|
397
|
-
}
|
|
398
|
-
if (!endedByItself) return;
|
|
399
|
-
try {
|
|
400
|
-
rmSync(this.#heartbeatPath, { force: true });
|
|
401
|
-
} catch {
|
|
402
|
-
// Fail-open (see the class doc).
|
|
403
|
-
}
|
|
404
|
-
}
|
|
405
|
-
|
|
406
|
-
/** One tick: read both legs, judge them, and overwrite the heartbeat record. A
|
|
407
|
-
* `stalled` verdict fires the kill trigger once (the first stall owns the kill;
|
|
408
|
-
* later ticks of a dying child never re-fire). */
|
|
409
|
-
#tick(now: number): void {
|
|
410
|
-
const sample = this.#sampler.probe();
|
|
411
|
-
const verdict = this.#judge.observe(sample, now);
|
|
412
|
-
const record: SampleRecord = {
|
|
413
|
-
sampledAt: now,
|
|
414
|
-
groupCpuMs: sample.groupCpuMs,
|
|
415
|
-
newestMtimeMs: sample.newestMtimeMs,
|
|
416
|
-
verdict,
|
|
417
|
-
};
|
|
418
|
-
this.#last = record;
|
|
419
|
-
try {
|
|
420
|
-
writeFileSync(this.#heartbeatPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
|
|
421
|
-
} catch {
|
|
422
|
-
// Fail-open (see the class doc): an unwritable heartbeat slows nothing down.
|
|
423
|
-
}
|
|
424
|
-
if (verdict === "stalled" && !this.#stallFired) {
|
|
425
|
-
this.#stallFired = true;
|
|
426
|
-
this.#onStall?.();
|
|
427
|
-
}
|
|
428
|
-
}
|
|
429
|
-
}
|
|
430
|
-
|
|
431
|
-
// ---------------------------------------------------------------------------
|
|
432
|
-
// the production runner — execa's asynchronous face
|
|
433
|
-
// ---------------------------------------------------------------------------
|
|
434
|
-
|
|
435
|
-
/** Terminator — the production `ChildRunner`: one child, its whole process
|
|
436
|
-
* lifecycle. Every process capability the seam needs is execa's, never the
|
|
437
|
-
* engine's:
|
|
438
|
-
* · `killDescendants: true` — the child is spawned as its own process group and
|
|
439
|
-
* the group is killed as a unit (execa forces the spawn-layer detachment
|
|
440
|
-
* internally; the user-facing `detached` option is never set, because it would
|
|
441
|
-
* short-circuit execa's parent-exit `cleanup`);
|
|
442
|
-
* · `forceKillAfterDelay` — SIGTERM, then SIGKILL after the grace (execa's own
|
|
443
|
-
* default written out, so the escalation is pinned at the call site);
|
|
444
|
-
* · `timeout` — the phase's wall-clock ceiling on the same kill path;
|
|
445
|
-
* · `reject: false` + `stripFinalNewline: false` — the fail-open result face, the
|
|
446
|
-
* child's stdout kept byte-verbatim;
|
|
447
|
-
* · `maxBuffer` is never set or lowered — execa's own 100 MB default is the
|
|
448
|
-
* unbounded-face successor of the retired fixed 1 MiB cap;
|
|
449
|
-
* · the sampling loop — the child is sampled from the spawn instant and every
|
|
450
|
-
* `policy.sampleIntervalMs` after (the heartbeat file is that loop's trail, and
|
|
451
|
-
* the judge's verdict rides every record).
|
|
452
|
-
* The class holds zero session state: everything a dispatch needs rides the
|
|
453
|
-
* `ChildRun` argument, so the composition root wires it without a scene. */
|
|
454
|
-
export class Terminator implements ChildRunner {
|
|
455
|
-
/** The force-kill grace (ms) — SIGTERM, then SIGKILL after this delay (execa's
|
|
456
|
-
* default, pinned explicitly). */
|
|
457
|
-
static readonly FORCE_KILL_AFTER_DELAY_MS = 5000;
|
|
458
|
-
|
|
459
|
-
async run(run: ChildRun): Promise<ChildOutcome> {
|
|
460
|
-
// The spawn instant seeds the judge's idle clock (§3.3).
|
|
461
|
-
const spawnedAt = Date.now();
|
|
462
|
-
// The engine's own stall kill — set by the sampling loop's trigger when the
|
|
463
|
-
// judge rules `stalled` AND the kill is delivered; the derivation reads it to
|
|
464
|
-
// attribute the kill (the signal execa reports for OUR kill would otherwise
|
|
465
|
-
// read as an external one).
|
|
466
|
-
let killedByStall = false;
|
|
467
|
-
const subprocess = execa(run.command, [...run.args], {
|
|
468
|
-
cwd: run.cwd,
|
|
469
|
-
reject: false,
|
|
470
|
-
stripFinalNewline: false,
|
|
471
|
-
killDescendants: true,
|
|
472
|
-
forceKillAfterDelay: Terminator.FORCE_KILL_AFTER_DELAY_MS,
|
|
473
|
-
timeout: run.policy.budgetMs,
|
|
474
|
-
});
|
|
475
|
-
const sampling = this.#startSampling(run, subprocess.pid, spawnedAt, () => {
|
|
476
|
-
// The engine's own group kill — execa kills the process group and escalates
|
|
477
|
-
// SIGTERM → SIGKILL after the grace. No signal logic of the engine's own.
|
|
478
|
-
// The flag records DELIVERY, not intent: `kill()` returns false when the signal
|
|
479
|
-
// could not be sent (the child already exited), so a round that ended by itself
|
|
480
|
-
// in the same tick is not misattributed as `stalled`.
|
|
481
|
-
if (subprocess.kill()) killedByStall = true;
|
|
482
|
-
});
|
|
483
|
-
// The round's heartbeat fate — terminated by default, so an unexpected throw keeps
|
|
484
|
-
// the trail as well; a round that ends by itself leaves no file behind.
|
|
485
|
-
let endedByItself = false;
|
|
486
|
-
try {
|
|
487
|
-
const result = await subprocess;
|
|
488
|
-
const termination = Terminator.terminationOf({
|
|
489
|
-
timedOut: result.timedOut,
|
|
490
|
-
killedByStall,
|
|
491
|
-
signal: result.signal,
|
|
492
|
-
isTerminated: result.isTerminated,
|
|
493
|
-
lastSample: sampling?.lastSample() ?? null,
|
|
494
|
-
});
|
|
495
|
-
endedByItself = termination === null;
|
|
496
|
-
return {
|
|
497
|
-
// The child's OWN exit code, unfolded: null means "never spawned / signalled",
|
|
498
|
-
// never a fabricated 1 (which would misreport both as an ordinary failed run).
|
|
499
|
-
code: result.exitCode ?? null,
|
|
500
|
-
stdout: result.stdout,
|
|
501
|
-
// The child's own stderr when it wrote one, else execa's diagnostic (a spawn
|
|
502
|
-
// failure like ENOENT writes nothing, so its reason rides the `shortMessage` —
|
|
503
|
-
// the fail-open face keeps a reason text, never an empty block).
|
|
504
|
-
stderr: result.stderr || (result.failed ? (result.shortMessage ?? "") : ""),
|
|
505
|
-
termination,
|
|
506
|
-
};
|
|
507
|
-
} finally {
|
|
508
|
-
// The cadence never outlives the dispatch.
|
|
509
|
-
sampling?.stop(endedByItself);
|
|
510
|
-
}
|
|
511
|
-
}
|
|
512
|
-
|
|
513
|
-
/** Start the dispatch's sampling loop, or null when the child never spawned (a
|
|
514
|
-
* broken command has no pid: nothing to sample and nothing to postmortem). The
|
|
515
|
-
* group id is the child's OWN pid, never recomputed — `killDescendants` forces the
|
|
516
|
-
* spawn-layer detachment, so the child IS its process group leader (the same fact
|
|
517
|
-
* execa's own group kill rides); the scan root is the same `cwd` the child was
|
|
518
|
-
* spawned in. The stall trigger rides through: the loop's first `stalled` verdict
|
|
519
|
-
* is the kill's authorization. */
|
|
520
|
-
#startSampling(
|
|
521
|
-
run: ChildRun,
|
|
522
|
-
pid: number | undefined,
|
|
523
|
-
spawnedAt: number,
|
|
524
|
-
onStall?: () => void,
|
|
525
|
-
): SamplingLoop | null {
|
|
526
|
-
if (pid === undefined) return null;
|
|
527
|
-
const sampling = new SamplingLoop({
|
|
528
|
-
sampler: new Sampler({
|
|
529
|
-
pgid: pid,
|
|
530
|
-
scanRoot: run.cwd,
|
|
531
|
-
exclude: Sampler.excludesFor(run.cwd, run.heartbeatPath),
|
|
532
|
-
}),
|
|
533
|
-
judge: new StallJudge(run.policy.idleWindowMs, spawnedAt),
|
|
534
|
-
heartbeatPath: run.heartbeatPath,
|
|
535
|
-
intervalMs: run.policy.sampleIntervalMs,
|
|
536
|
-
onStall,
|
|
537
|
-
});
|
|
538
|
-
sampling.start();
|
|
539
|
-
return sampling;
|
|
540
|
-
}
|
|
541
|
-
|
|
542
|
-
/** Derive the termination fact from the child's own result face — the four-way
|
|
543
|
-
* derivation (§4.1), in the order the causes claim a kill (package-visible, so the
|
|
544
|
-
* table-driven pin can rule on every branch without a real child):
|
|
545
|
-
* · the wall-clock ceiling (execa's `timedOut`) → `over-budget`;
|
|
546
|
-
* · the engine's own stall kill → `stalled` (ahead of the signal leg: OUR kill
|
|
547
|
-
* also arrives as a signal, and misreading it as external would falsify the
|
|
548
|
-
* postmortem);
|
|
549
|
-
* · any other signal → `signal` (the external-kill semantic, never the SIGTERM
|
|
550
|
-
* literal — SIGTERM / SIGKILL / SIGINT / SIGHUP read the same);
|
|
551
|
-
* · none of the three but the child was terminated anyway → `unknown` (the
|
|
552
|
-
* unattributable fallback);
|
|
553
|
-
* · nothing of the above → the round ended by itself (successfully or not), no
|
|
554
|
-
* termination.
|
|
555
|
-
* The last sample rides whichever cause won: it is the sampling loop's own last
|
|
556
|
-
* observation, held in memory — never a re-read of the heartbeat file the engine
|
|
557
|
-
* itself wrote.
|
|
558
|
-
*
|
|
559
|
-
* `killedByStall` records that OUR kill was delivered (execa's `kill()` returns
|
|
560
|
-
* false when the signal could not be sent — a child that already exited is not
|
|
561
|
-
* attributed here). Residual boundary: a child that exits within the same tick
|
|
562
|
-
* while its process group still exists (a zombie not yet reaped) can still be
|
|
563
|
-
* signalled and read `stalled` — the idle verdict, not the kill landing, is the
|
|
564
|
-
* criterion. */
|
|
565
|
-
static terminationOf(facts: TerminationFacts): Termination | null {
|
|
566
|
-
const { timedOut, killedByStall, signal, isTerminated, lastSample } = facts;
|
|
567
|
-
if (timedOut) return { cause: "over-budget", lastSample };
|
|
568
|
-
if (killedByStall) return { cause: "stalled", lastSample };
|
|
569
|
-
if (signal !== undefined) return { cause: "signal", lastSample };
|
|
570
|
-
if (isTerminated) return { cause: "unknown", lastSample };
|
|
571
|
-
return null;
|
|
572
|
-
}
|
|
573
|
-
}
|