@indigoai-us/hq-cloud 6.16.4 → 6.16.6

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 (34) hide show
  1. package/dist/bin/sync-runner-events.d.ts +10 -0
  2. package/dist/bin/sync-runner-events.d.ts.map +1 -1
  3. package/dist/bin/sync-runner-events.js +34 -0
  4. package/dist/bin/sync-runner-events.js.map +1 -1
  5. package/dist/bin/sync-runner-events.test.js +65 -1
  6. package/dist/bin/sync-runner-events.test.js.map +1 -1
  7. package/dist/bin/sync-runner-heap-telemetry.d.ts +313 -45
  8. package/dist/bin/sync-runner-heap-telemetry.d.ts.map +1 -1
  9. package/dist/bin/sync-runner-heap-telemetry.js +503 -114
  10. package/dist/bin/sync-runner-heap-telemetry.js.map +1 -1
  11. package/dist/bin/sync-runner-heap-telemetry.test.js +436 -11
  12. package/dist/bin/sync-runner-heap-telemetry.test.js.map +1 -1
  13. package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
  14. package/dist/bin/sync-runner-watch-loop.js +69 -9
  15. package/dist/bin/sync-runner-watch-loop.js.map +1 -1
  16. package/dist/bin/sync-runner-watch-loop.test.js +13 -1
  17. package/dist/bin/sync-runner-watch-loop.test.js.map +1 -1
  18. package/dist/bin/sync-runner.d.ts +27 -1
  19. package/dist/bin/sync-runner.d.ts.map +1 -1
  20. package/dist/bin/sync-runner.js +10 -1
  21. package/dist/bin/sync-runner.js.map +1 -1
  22. package/dist/sync/event-sync.js +2 -2
  23. package/dist/sync/event-sync.js.map +1 -1
  24. package/dist/sync/state-store.d.ts +8 -0
  25. package/dist/sync/state-store.d.ts.map +1 -1
  26. package/dist/sync/state-store.js +37 -0
  27. package/dist/sync/state-store.js.map +1 -1
  28. package/dist/watcher.d.ts +49 -9
  29. package/dist/watcher.d.ts.map +1 -1
  30. package/dist/watcher.js +425 -158
  31. package/dist/watcher.js.map +1 -1
  32. package/dist/watcher.test.js +349 -23
  33. package/dist/watcher.test.js.map +1 -1
  34. package/package.json +1 -1
@@ -107,6 +107,15 @@ export function sampleRunnerHeap(deps) {
107
107
  function finiteNumber(value) {
108
108
  return typeof value === "number" && Number.isFinite(value) ? value : 0;
109
109
  }
110
+ /** Fold the four cadence counters into a property bag, ahead of per-site keys. */
111
+ function appendCounters(props, counters) {
112
+ if (!counters)
113
+ return;
114
+ props.heap_observations_count = counters.heapObservationsCount;
115
+ props.heap_interval_observations_count = counters.heapIntervalObservationsCount;
116
+ props.heap_checkpoint_observations_count = counters.heapCheckpointObservationsCount;
117
+ props.ms_since_previous_observation_ms = counters.msSincePreviousObservationMs;
118
+ }
110
119
  /** Parts-per-thousand, the integer spelling every fraction is emitted as. */
111
120
  function toPermille(fraction) {
112
121
  return Math.round(fraction * 1000);
@@ -120,7 +129,7 @@ function toPermille(fraction) {
120
129
  * actually STORED by ingest (unlike the pre-fix `census_<token>` spelling,
121
130
  * which ingest silently dropped, so the attribution never reached the store).
122
131
  */
123
- export function heapSampleCloudProperties(sample) {
132
+ export function heapSampleCloudProperties(sample, counters) {
124
133
  const props = {
125
134
  heap_used_bytes: sample.usedHeapBytes,
126
135
  heap_total_bytes: sample.totalHeapBytes,
@@ -132,22 +141,26 @@ export function heapSampleCloudProperties(sample) {
132
141
  uptime_ms: sample.uptimeMs,
133
142
  census_total_count: sample.censusTotal,
134
143
  };
144
+ appendCounters(props, counters);
135
145
  for (const { site, count } of sample.census) {
136
146
  props[`census_${site}_count`] = count;
137
147
  }
138
148
  return props;
139
149
  }
140
150
  /** Flatten a pressure record into numeric-only telemetry properties. */
141
- export function heapPressureCloudProperties(record) {
151
+ export function heapPressureCloudProperties(record, counters) {
142
152
  const props = {
143
153
  pressure_used_permille_count: toPermille(record.usedFraction),
144
154
  pressure_threshold_permille_count: toPermille(record.thresholdFraction),
145
155
  heap_used_bytes: record.usedHeapBytes,
146
156
  heap_limit_bytes: record.heapLimitBytes,
157
+ heap_effective_limit_bytes: record.effectiveLimitBytes,
158
+ heap_declared_limit_bytes: record.declaredCeilingBytes,
147
159
  rss_bytes: record.rssBytes,
148
160
  external_bytes: record.externalBytes,
149
161
  uptime_ms: record.uptimeMs,
150
162
  };
163
+ appendCounters(props, counters);
151
164
  for (const { site, count, growth } of record.topSites) {
152
165
  props[`${site}_count`] = count;
153
166
  props[`${site}_growth_count`] = growth;
@@ -161,23 +174,32 @@ export function heapPressureStderrLine(record) {
161
174
  .join(",");
162
175
  return ("hq-sync-runner: heap-pressure " +
163
176
  `used=${record.usedHeapBytes} limit=${record.heapLimitBytes} ` +
177
+ `eff=${record.effectiveLimitBytes} ` +
164
178
  `permille=${toPermille(record.usedFraction)} rss=${record.rssBytes} ` +
165
179
  `uptime_ms=${record.uptimeMs} top=${top}`);
166
180
  }
167
181
  /** Flatten a recycle record into numeric-only telemetry properties. */
168
- export function heapRecycleCloudProperties(record) {
182
+ export function heapRecycleCloudProperties(record, counters) {
169
183
  const props = {
170
184
  recycle_used_permille_count: toPermille(record.usedFraction),
171
185
  recycle_live_permille_count: toPermille(record.liveFraction),
172
186
  recycle_live_floor_permille_count: toPermille(record.recycleLiveFraction),
187
+ recycle_pinned_floor_permille_count: toPermille(record.pinnedFraction),
173
188
  recycle_emergency_floor_permille_count: toPermille(record.emergencyFraction),
189
+ recycle_hard_exit_floor_permille_count: toPermille(record.hardExitFraction),
174
190
  recycle_emergency_trigger_count: record.trigger === "emergency" ? 1 : 0,
191
+ recycle_pinned_trigger_count: record.trigger === "pinned" ? 1 : 0,
192
+ recycle_latch_timeout_count: record.reason === "latch_timeout" ? 1 : 0,
193
+ recycle_hard_fraction_count: record.reason === "hard_fraction" ? 1 : 0,
194
+ recycle_post_latch_observations_count: record.postLatchObservations,
175
195
  recycle_sustain_window_ms: record.sustainWindowMs,
176
196
  recycle_observed_sustain_ms: record.observedSustainMs,
177
197
  recycle_min_uptime_ms: record.minUptimeMs,
178
198
  heap_used_bytes: record.usedHeapBytes,
179
199
  heap_live_bytes: record.liveHeapBytes,
180
200
  heap_limit_bytes: record.heapLimitBytes,
201
+ heap_effective_limit_bytes: record.effectiveLimitBytes,
202
+ heap_declared_limit_bytes: record.declaredCeilingBytes,
181
203
  rss_bytes: record.rssBytes,
182
204
  external_bytes: record.externalBytes,
183
205
  array_buffers_bytes: record.arrayBuffersBytes,
@@ -187,6 +209,7 @@ export function heapRecycleCloudProperties(record) {
187
209
  uptime_ms: record.uptimeMs,
188
210
  census_total_count: record.censusTotal,
189
211
  };
212
+ appendCounters(props, counters);
190
213
  for (const { site, count, growth } of record.topSites) {
191
214
  props[`${site}_count`] = count;
192
215
  props[`${site}_growth_count`] = growth;
@@ -207,8 +230,9 @@ export function heapRecycleStderrLine(record) {
207
230
  .map((entry) => `${entry.site}:${entry.growth}`)
208
231
  .join(",");
209
232
  return ("hq-sync-runner: heap-recycle " +
210
- `trigger=${record.trigger} ` +
233
+ `trigger=${record.trigger} reason=${record.reason} ` +
211
234
  `used=${record.usedHeapBytes} live=${record.liveHeapBytes} limit=${record.heapLimitBytes} ` +
235
+ `eff=${record.effectiveLimitBytes} ` +
212
236
  `live_permille=${toPermille(record.liveFraction)} rss=${record.rssBytes} ` +
213
237
  `uptime_ms=${record.uptimeMs} sustain_ms=${record.observedSustainMs} top=${top}`);
214
238
  }
@@ -218,18 +242,12 @@ const DEFAULT_RECYCLE_LIVE_FRACTION = 0.6;
218
242
  const DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS = 120_000;
219
243
  const DEFAULT_RECYCLE_EMERGENCY_FRACTION = 0.9;
220
244
  const DEFAULT_RECYCLE_MIN_UPTIME_MS = 35 * 60_000;
221
- /**
222
- * Owns the sampling state machine. It keeps the baseline and latest sample, the
223
- * pressure escalation, and the two recycle paths:
224
- * - {@link observeMajorGc}, the PRIMARY path, driven by the GC observer: each
225
- * (throttled) call reads the post-GC live heap and tracks the sustain
226
- * window that a live recycle requires.
227
- * - {@link evaluate} and the emergency arm of {@link sample}, the instantaneous
228
- * BACKSTOP: they recycle on a single sample at/above the emergency fraction
229
- * even if the GC signal never arrives or the sampler timer is starved.
230
- * Every fraction is derived from the injected `heap_size_limit`, so the governor
231
- * self-calibrates to whatever `--max-old-space-size` the desktop supplied.
232
- */
245
+ const DEFAULT_RECYCLE_PINNED_FRACTION = 0.84;
246
+ const DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS = 20_000;
247
+ const DEFAULT_HARD_EXIT_FRACTION = 0.955;
248
+ const DEFAULT_LATCH_HARD_EXIT_MS = 60_000;
249
+ const DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS = 240;
250
+ const NO_VERDICT = Object.freeze({ recycle: null, hardExit: null });
233
251
  export class RunnerHeapTelemetry {
234
252
  readers;
235
253
  census;
@@ -237,17 +255,35 @@ export class RunnerHeapTelemetry {
237
255
  threshold;
238
256
  topSiteCount;
239
257
  recycleEnabled;
258
+ declaredCeilingBytes;
240
259
  recycleLiveFraction;
241
260
  recycleSustainWindowMs;
242
261
  recycleEmergencyFraction;
243
262
  recycleMinUptimeMs;
263
+ pinnedFraction;
264
+ pinnedSustainWindowMs;
265
+ hardExitFraction;
266
+ latchHardExitMs;
267
+ latchHardExitObservations;
244
268
  baseline = null;
245
269
  latest = null;
246
270
  pressureSignalled = false;
247
271
  recycleSignalled = false;
272
+ hardExitSignalled = false;
248
273
  /** Uptime (ms) of the first live observation at/above the floor in the
249
274
  * current consecutive run; null when the last live reading dipped below it. */
250
275
  liveAnchorUptimeMs = null;
276
+ /** Uptime (ms) of the first instantaneous observation at/above the pinned
277
+ * floor in the current consecutive run; null when a reading dipped below it. */
278
+ pinnedAnchorUptimeMs = null;
279
+ /** Consecutive instantaneous observations at/above the pinned floor. */
280
+ pinnedObservationCount = 0;
281
+ /** Uptime (ms) at which the FIRST cooperative latch (any tier) armed. */
282
+ latchedAtUptimeMs = null;
283
+ /** The tier that produced the cooperative latch, carried onto a hard exit. */
284
+ latchedTrigger = null;
285
+ /** Observations seen since the cooperative latch armed (drives latch_timeout). */
286
+ postLatchObservations = 0;
251
287
  constructor(options) {
252
288
  this.readers = options.readers;
253
289
  this.census = options.census;
@@ -260,6 +296,11 @@ export class RunnerHeapTelemetry {
260
296
  const count = options.topSiteCount ?? DEFAULT_TOP_SITE_COUNT;
261
297
  this.topSiteCount = Number.isFinite(count) && count > 0 ? Math.trunc(count) : DEFAULT_TOP_SITE_COUNT;
262
298
  this.recycleEnabled = options.recycleEnabled ?? true;
299
+ const declared = options.declaredCeilingBytes;
300
+ this.declaredCeilingBytes =
301
+ typeof declared === "number" && Number.isFinite(declared) && declared > 0
302
+ ? Math.trunc(declared)
303
+ : null;
263
304
  this.recycleLiveFraction = fractionOrDefault(options.recycleLiveFraction, DEFAULT_RECYCLE_LIVE_FRACTION);
264
305
  const window = options.recycleSustainWindowMs ?? DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS;
265
306
  this.recycleSustainWindowMs =
@@ -270,6 +311,34 @@ export class RunnerHeapTelemetry {
270
311
  Number.isFinite(minUptime) && minUptime >= 0
271
312
  ? Math.trunc(minUptime)
272
313
  : DEFAULT_RECYCLE_MIN_UPTIME_MS;
314
+ this.pinnedFraction = fractionOrDefault(options.recyclePinnedFraction, DEFAULT_RECYCLE_PINNED_FRACTION);
315
+ const pinnedWindow = options.recyclePinnedSustainWindowMs ?? DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
316
+ this.pinnedSustainWindowMs =
317
+ Number.isFinite(pinnedWindow) && pinnedWindow >= 0
318
+ ? Math.trunc(pinnedWindow)
319
+ : DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
320
+ this.hardExitFraction = fractionOrDefault(options.hardExitFraction, DEFAULT_HARD_EXIT_FRACTION);
321
+ const latchMs = options.latchHardExitMs ?? DEFAULT_LATCH_HARD_EXIT_MS;
322
+ this.latchHardExitMs =
323
+ Number.isFinite(latchMs) && latchMs >= 0 ? Math.trunc(latchMs) : DEFAULT_LATCH_HARD_EXIT_MS;
324
+ const latchObs = options.latchHardExitObservations ?? DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
325
+ this.latchHardExitObservations =
326
+ Number.isFinite(latchObs) && latchObs >= 1
327
+ ? Math.trunc(latchObs)
328
+ : DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
329
+ }
330
+ /**
331
+ * The one denominator every fraction is computed against: the declared
332
+ * `--max-old-space-size` when known (it is the real V8 ceiling the aborts
333
+ * respect), else V8's reported `heap_size_limit`. Never larger than reported.
334
+ */
335
+ effectiveLimit(heapLimitBytes) {
336
+ if (this.declaredCeilingBytes === null)
337
+ return heapLimitBytes;
338
+ return Math.min(this.declaredCeilingBytes, heapLimitBytes);
339
+ }
340
+ uptimeNow() {
341
+ return Math.max(0, Math.trunc(this.readers.monotonicNowMs() - this.sessionStartedAtMs));
273
342
  }
274
343
  /**
275
344
  * Capture the growth baseline when sampling starts, before the first interval,
@@ -283,16 +352,16 @@ export class RunnerHeapTelemetry {
283
352
  }
284
353
  /**
285
354
  * The interval sampler tick. Emits a sample and (at most once per rising
286
- * crossing) a pressure record. Its recycle output is the EMERGENCY backstop
287
- * only — the instantaneous sawtooth is deliberately NOT the primary verdict.
355
+ * crossing) a pressure record, then runs the instantaneous tiers (pinned,
356
+ * emergency, hard). The primary post-GC live verdict comes from
357
+ * {@link observeMajorGc}; this instantaneous path catches the starved
358
+ * synchronous stretch where no post-GC reading is ever taken.
288
359
  */
289
360
  sample() {
290
361
  const sample = this.buildSample();
291
- return {
292
- sample,
293
- pressure: this.detectPressure(sample),
294
- recycle: this.detectEmergency(sample),
295
- };
362
+ const pressure = this.detectPressure(sample);
363
+ const { recycle, hardExit } = this.observeInstant(sample.usedHeapBytes, sample.heapLimitBytes, sample.uptimeMs, () => sample);
364
+ return { sample, pressure, recycle, hardExit };
296
365
  }
297
366
  /**
298
367
  * The PRIMARY governor path, driven by an observed MAJOR GC. The caller
@@ -307,58 +376,142 @@ export class RunnerHeapTelemetry {
307
376
  * below the floor ALWAYS invalidates the sustain run — a throttle that skipped
308
377
  * such a reading would let a stale anchor fake a continuous run. The fuller
309
378
  * sample (census snapshot + memory deltas) is taken only at the verdict, so a
310
- * GC storm never costs more than the O(1) statistics read here.
379
+ * GC storm never costs more than the O(1) statistics read here. The fraction
380
+ * is denominated in the EFFECTIVE limit (min(declared, reported)) — the only
381
+ * change from the shipped live-tier logic.
311
382
  */
312
383
  observeMajorGc() {
313
- if (!this.recycleEnabled || this.recycleSignalled)
314
- return null;
384
+ if (!this.recycleEnabled)
385
+ return NO_VERDICT;
315
386
  const stats = this.readers.getHeapStatistics();
316
387
  const heapLimitBytes = finiteNumber(stats.heap_size_limit);
317
- if (heapLimitBytes <= 0)
318
- return null;
319
- const liveFraction = finiteNumber(stats.used_heap_size) / heapLimitBytes;
320
- const uptimeMs = Math.max(0, Math.trunc(this.readers.monotonicNowMs() - this.sessionStartedAtMs));
321
- // A genuine post-GC reading already abort-adjacent: recycle now, bypassing
322
- // both the sustain window and the uptime floor.
388
+ const effective = this.effectiveLimit(heapLimitBytes);
389
+ if (effective <= 0)
390
+ return NO_VERDICT;
391
+ const liveFraction = finiteNumber(stats.used_heap_size) / effective;
392
+ const uptimeMs = this.uptimeNow();
393
+ // T4 hard: a post-GC reading is the cleanest instantaneous value, so the
394
+ // hard-fraction and the aged-latch backstops are evaluated here too.
395
+ const hardExit = this.checkHardExit(liveFraction, uptimeMs);
396
+ if (hardExit)
397
+ return { recycle: null, hardExit };
398
+ if (this.recycleSignalled)
399
+ return NO_VERDICT;
400
+ // T3 emergency: a genuine post-GC reading already abort-adjacent — cooperative
401
+ // recycle now, bypassing both the sustain window and the uptime floor.
323
402
  if (liveFraction >= this.recycleEmergencyFraction) {
324
- return this.produceRecycleFromCurrent("emergency", 0);
403
+ return { recycle: this.armCooperativeLatch("emergency", 0), hardExit: null };
325
404
  }
405
+ // T1 live: the post-GC live floor held across the sustain window.
326
406
  if (liveFraction < this.recycleLiveFraction) {
327
407
  // The live floor dipped: reset the anchor so the window only ever measures
328
408
  // a genuinely continuous run at/above the floor.
329
409
  this.liveAnchorUptimeMs = null;
330
- return null;
410
+ return NO_VERDICT;
331
411
  }
332
412
  if (this.liveAnchorUptimeMs === null) {
333
413
  // First qualifying observation. A second, at least a window later, confirms.
334
414
  this.liveAnchorUptimeMs = uptimeMs;
335
- return null;
415
+ return NO_VERDICT;
336
416
  }
337
417
  const observedSustainMs = Math.max(0, uptimeMs - this.liveAnchorUptimeMs);
338
418
  if (observedSustainMs < this.recycleSustainWindowMs)
339
- return null;
419
+ return NO_VERDICT;
340
420
  if (uptimeMs < this.recycleMinUptimeMs)
341
- return null;
342
- return this.produceRecycleFromCurrent("live", observedSustainMs);
421
+ return NO_VERDICT;
422
+ return { recycle: this.armCooperativeLatch("live", observedSustainMs), hardExit: null };
343
423
  }
344
424
  /**
345
- * The loop-top BACKSTOP against timer starvation (the observed 11-minute
346
- * sampler hole). Reads the instantaneous heap and runs the emergency check
347
- * only — an instantaneous reading can never confirm the post-GC live floor,
348
- * so it must not feed the primary path's sustain window. Cheap: an O(1)
349
- * statistics read, sampling the census only if it actually fires.
425
+ * The loop-top / work-driven BACKSTOP against timer starvation (the observed
426
+ * 11-minute sampler hole). Reads the instantaneous heap and runs the
427
+ * instantaneous tiers (hard, emergency, pinned). An instantaneous reading can
428
+ * never confirm the post-GC live floor, so it never feeds the live tier's
429
+ * sustain window. Cheap: an O(1) statistics read, sampling the census only if
430
+ * a verdict actually fires.
350
431
  */
351
432
  evaluate() {
352
- if (!this.recycleEnabled || this.recycleSignalled)
353
- return null;
433
+ if (!this.recycleEnabled)
434
+ return NO_VERDICT;
354
435
  const stats = this.readers.getHeapStatistics();
355
436
  const heapLimitBytes = finiteNumber(stats.heap_size_limit);
356
- if (heapLimitBytes <= 0)
357
- return null;
358
- const usedFraction = finiteNumber(stats.used_heap_size) / heapLimitBytes;
359
- if (usedFraction < this.recycleEmergencyFraction)
437
+ const usedHeapBytes = finiteNumber(stats.used_heap_size);
438
+ const uptimeMs = this.uptimeNow();
439
+ return this.observeInstant(usedHeapBytes, heapLimitBytes, uptimeMs, () => this.buildSample());
440
+ }
441
+ /**
442
+ * The shared instantaneous tier pipeline (interval tick, loop-top, and the
443
+ * work-driven checkpoint all reach it). Order: T4 hard (hard-fraction, then an
444
+ * aged-out latch) → T3 emergency (single observation, bypasses window+floor) →
445
+ * T2 pinned (instantaneous fraction sustained across the pinned window past the
446
+ * uptime floor, with any dip resetting the anchor). The full sample is built
447
+ * only at a verdict, via `buildVerdictSample`.
448
+ */
449
+ observeInstant(usedHeapBytes, heapLimitBytes, uptimeMs, buildVerdictSample) {
450
+ if (!this.recycleEnabled)
451
+ return NO_VERDICT;
452
+ const effective = this.effectiveLimit(heapLimitBytes);
453
+ if (effective <= 0)
454
+ return NO_VERDICT;
455
+ const usedFraction = usedHeapBytes / effective;
456
+ const hardExit = this.checkHardExit(usedFraction, uptimeMs, buildVerdictSample);
457
+ if (hardExit)
458
+ return { recycle: null, hardExit };
459
+ if (this.recycleSignalled)
460
+ return NO_VERDICT;
461
+ // T3 emergency: single instantaneous observation, bypasses window + floor.
462
+ if (usedFraction >= this.recycleEmergencyFraction) {
463
+ return { recycle: this.armCooperativeLatch("emergency", 0, buildVerdictSample), hardExit: null };
464
+ }
465
+ // T2 pinned: instantaneous fraction held across the pinned window.
466
+ if (usedFraction < this.pinnedFraction) {
467
+ this.pinnedAnchorUptimeMs = null;
468
+ this.pinnedObservationCount = 0;
469
+ return NO_VERDICT;
470
+ }
471
+ if (this.pinnedAnchorUptimeMs === null) {
472
+ this.pinnedAnchorUptimeMs = uptimeMs;
473
+ this.pinnedObservationCount = 1;
474
+ return NO_VERDICT;
475
+ }
476
+ this.pinnedObservationCount += 1;
477
+ const observedSustainMs = Math.max(0, uptimeMs - this.pinnedAnchorUptimeMs);
478
+ if (observedSustainMs < this.pinnedSustainWindowMs)
479
+ return NO_VERDICT;
480
+ if (this.pinnedObservationCount < 2)
481
+ return NO_VERDICT;
482
+ if (uptimeMs < this.recycleMinUptimeMs)
483
+ return NO_VERDICT;
484
+ return {
485
+ recycle: this.armCooperativeLatch("pinned", observedSustainMs, buildVerdictSample),
486
+ hardExit: null,
487
+ };
488
+ }
489
+ /**
490
+ * T4 hard-exit evaluation, run at EVERY observation point. Fires at most once
491
+ * per session (independent of the cooperative latch), on either arm:
492
+ * (a) `hard_fraction` — the instantaneous fraction is at/above the hard line;
493
+ * (b) `latch_timeout` — a cooperative latch aged past its time OR observation
494
+ * deadline without the loop honouring it.
495
+ * The `latch_timeout` observation counter advances on every later observation,
496
+ * never on the observation that armed the latch (that call sees a still-false
497
+ * `recycleSignalled` before the cooperative tier runs).
498
+ */
499
+ checkHardExit(fraction, uptimeMs, buildVerdictSample) {
500
+ if (!this.recycleEnabled || this.hardExitSignalled)
360
501
  return null;
361
- return this.produceRecycleFromCurrent("emergency", 0);
502
+ const build = buildVerdictSample ?? (() => this.buildSample());
503
+ if (Number.isFinite(fraction) && fraction >= this.hardExitFraction) {
504
+ return this.armHardExit(build(), "hard_fraction");
505
+ }
506
+ if (this.recycleSignalled && this.latchedAtUptimeMs !== null) {
507
+ this.postLatchObservations += 1;
508
+ const agedMs = uptimeMs - this.latchedAtUptimeMs;
509
+ if (agedMs >= this.latchHardExitMs ||
510
+ this.postLatchObservations >= this.latchHardExitObservations) {
511
+ return this.armHardExit(build(), "latch_timeout");
512
+ }
513
+ }
514
+ return null;
362
515
  }
363
516
  buildSample() {
364
517
  const sample = sampleRunnerHeap({
@@ -372,44 +525,45 @@ export class RunnerHeapTelemetry {
372
525
  this.latest = sample;
373
526
  return sample;
374
527
  }
375
- /** The instantaneous emergency backstop: a single sample at/above the
376
- * emergency fraction, bypassing the sustain window and the uptime floor. */
377
- detectEmergency(sample) {
378
- if (!this.recycleEnabled || this.recycleSignalled)
379
- return null;
380
- if (sample.heapLimitBytes <= 0)
381
- return null;
382
- const usedFraction = sample.usedHeapBytes / sample.heapLimitBytes;
383
- if (usedFraction < this.recycleEmergencyFraction)
384
- return null;
385
- return this.produceRecycle(sample, "emergency", usedFraction, 0);
528
+ /** Arm the one cooperative latch (from any tier) and build its verdict. */
529
+ armCooperativeLatch(trigger, observedSustainMs, buildVerdictSample) {
530
+ this.recycleSignalled = true;
531
+ const sample = (buildVerdictSample ?? (() => this.buildSample()))();
532
+ if (this.latchedAtUptimeMs === null) {
533
+ this.latchedAtUptimeMs = sample.uptimeMs;
534
+ this.latchedTrigger = trigger;
535
+ this.postLatchObservations = 0;
536
+ }
537
+ return this.buildRecord(sample, trigger, "cooperative", observedSustainMs);
386
538
  }
387
- /**
388
- * Produce a verdict from a freshly-taken sample. Called only once the cheap
389
- * per-GC (or loop-top) path has decided a recycle is due, so the census
390
- * snapshot and memory deltas are computed exactly once per session.
391
- */
392
- produceRecycleFromCurrent(trigger, observedSustainMs) {
393
- const sample = this.buildSample();
394
- const liveFraction = sample.heapLimitBytes > 0 ? sample.usedHeapBytes / sample.heapLimitBytes : 0;
395
- return this.produceRecycle(sample, trigger, liveFraction, observedSustainMs);
539
+ /** Arm the one hard exit and build its verdict (`hard_fraction`/`latch_timeout`). */
540
+ armHardExit(sample, reason) {
541
+ this.hardExitSignalled = true;
542
+ const trigger = this.latchedTrigger ?? "emergency";
543
+ return this.buildRecord(sample, trigger, reason, 0);
396
544
  }
397
- produceRecycle(sample, trigger, liveFraction, observedSustainMs) {
398
- this.recycleSignalled = true;
399
- const usedFraction = sample.heapLimitBytes > 0 ? sample.usedHeapBytes / sample.heapLimitBytes : 0;
545
+ buildRecord(sample, trigger, reason, observedSustainMs) {
546
+ const effective = this.effectiveLimit(sample.heapLimitBytes);
547
+ const usedFraction = effective > 0 ? sample.usedHeapBytes / effective : 0;
400
548
  const baseline = this.baseline;
401
549
  return {
402
550
  trigger,
551
+ reason,
403
552
  usedHeapBytes: sample.usedHeapBytes,
404
553
  liveHeapBytes: sample.usedHeapBytes,
405
554
  heapLimitBytes: sample.heapLimitBytes,
555
+ effectiveLimitBytes: effective,
556
+ declaredCeilingBytes: this.declaredCeilingBytes ?? 0,
406
557
  usedFraction,
407
- liveFraction,
558
+ liveFraction: usedFraction,
408
559
  recycleLiveFraction: this.recycleLiveFraction,
560
+ pinnedFraction: this.pinnedFraction,
409
561
  emergencyFraction: this.recycleEmergencyFraction,
562
+ hardExitFraction: this.hardExitFraction,
410
563
  sustainWindowMs: this.recycleSustainWindowMs,
411
564
  observedSustainMs,
412
565
  minUptimeMs: this.recycleMinUptimeMs,
566
+ postLatchObservations: reason === "latch_timeout" ? this.postLatchObservations : 0,
413
567
  uptimeMs: sample.uptimeMs,
414
568
  rssBytes: sample.rssBytes,
415
569
  externalBytes: sample.externalBytes,
@@ -422,9 +576,10 @@ export class RunnerHeapTelemetry {
422
576
  };
423
577
  }
424
578
  detectPressure(sample) {
425
- if (sample.heapLimitBytes <= 0)
579
+ const effective = this.effectiveLimit(sample.heapLimitBytes);
580
+ if (effective <= 0)
426
581
  return null;
427
- const usedFraction = sample.usedHeapBytes / sample.heapLimitBytes;
582
+ const usedFraction = sample.usedHeapBytes / effective;
428
583
  if (usedFraction < this.threshold) {
429
584
  // Re-arm below the threshold so a genuine later crossing escalates again.
430
585
  this.pressureSignalled = false;
@@ -436,6 +591,8 @@ export class RunnerHeapTelemetry {
436
591
  return {
437
592
  usedHeapBytes: sample.usedHeapBytes,
438
593
  heapLimitBytes: sample.heapLimitBytes,
594
+ effectiveLimitBytes: effective,
595
+ declaredCeilingBytes: this.declaredCeilingBytes ?? 0,
439
596
  usedFraction,
440
597
  thresholdFraction: this.threshold,
441
598
  rssBytes: sample.rssBytes,
@@ -549,13 +706,16 @@ export function nodeMajorGcObserver() {
549
706
  };
550
707
  }
551
708
  const DEFAULT_SAMPLE_INTERVAL_MS = 60_000;
709
+ const DEFAULT_CHECKPOINT_MS = 250;
552
710
  /**
553
711
  * Start periodic sampling and, when a GC observer is supplied, the primary
554
712
  * live-heap path. The interval timer is `unref`'d so it can never hold the
555
713
  * process open, and `stop()` clears it and disconnects the GC observer on every
556
- * shutdown path. Each tick, GC callback, and emit — and the loop-top
557
- * `evaluate()` — is wrapped so a fault degrades to silence and never affects the
558
- * watch cycle.
714
+ * shutdown path. The interval tick, the work-driven checkpoint, and the loop-top
715
+ * `evaluate()` share ONE observation pipeline, one last-observation timestamp,
716
+ * and one set of cadence counters. Each observation — and every emit callback it
717
+ * drives — is wrapped so a fault degrades to silence and never affects the watch
718
+ * cycle.
559
719
  */
560
720
  export function startRunnerHeapSampling(options) {
561
721
  const telemetry = new RunnerHeapTelemetry(options);
@@ -572,46 +732,104 @@ export function startRunnerHeapSampling(options) {
572
732
  const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0
573
733
  ? Math.trunc(options.intervalMs)
574
734
  : DEFAULT_SAMPLE_INTERVAL_MS;
735
+ const checkpointMs = options.checkpointMs === undefined
736
+ ? DEFAULT_CHECKPOINT_MS
737
+ : Number.isFinite(options.checkpointMs) && options.checkpointMs >= 0
738
+ ? Math.trunc(options.checkpointMs)
739
+ : DEFAULT_CHECKPOINT_MS;
575
740
  let stopped = false;
576
- // One recycle verdict per session, from whichever path reaches it first. The
577
- // telemetry latches internally, so this callback fires at most once.
578
- const fireRecycle = (record) => {
579
- try {
580
- options.onRecycle?.(record);
741
+ // Shared observation state — interval, checkpoint, and loop-top feed the SAME
742
+ // pipeline, one last-observation timestamp, and one set of cadence counters.
743
+ let lastObservationAtMs = null;
744
+ let observationCount = 0;
745
+ let intervalObservationCount = 0;
746
+ let checkpointObservationCount = 0;
747
+ const snapshotCounters = (msSincePrev) => ({
748
+ heapObservationsCount: observationCount,
749
+ heapIntervalObservationsCount: intervalObservationCount,
750
+ heapCheckpointObservationsCount: checkpointObservationCount,
751
+ msSincePreviousObservationMs: msSincePrev,
752
+ });
753
+ // Deliver at most one verdict: a hard exit preempts the cooperative recycle on
754
+ // the same observation (the process is leaving now); both callbacks are wrapped
755
+ // so a fault degrades to silence and never disturbs a watch cycle.
756
+ const deliver = (recycle, hardExit, counters) => {
757
+ if (hardExit && options.onHardExit) {
758
+ try {
759
+ options.onHardExit(hardExit, counters);
760
+ }
761
+ catch (err) {
762
+ warn(options.log, err);
763
+ }
581
764
  }
582
- catch (err) {
583
- warn(options.log, err);
765
+ else if (recycle) {
766
+ try {
767
+ options.onRecycle?.(recycle, counters);
768
+ }
769
+ catch (err) {
770
+ warn(options.log, err);
771
+ }
584
772
  }
585
773
  };
586
- const tick = () => {
774
+ // The one observation pipeline. `source` distinguishes the 60 s interval tick
775
+ // (which emits a cloud sample) from a checkpoint/loop-top (which never does).
776
+ // `gated` is true only for the work-driven checkpoint: it is throttled to
777
+ // `checkpointMs` and disabled entirely when `checkpointMs <= 0`. The loop-top
778
+ // `evaluate()` passes gated=false so it keeps working with checkpoints off,
779
+ // preserving the shipped behaviour exactly.
780
+ const runObservation = (source, gated) => {
587
781
  if (stopped)
588
782
  return;
589
783
  try {
590
- const { sample, pressure, recycle } = telemetry.sample();
591
- try {
592
- options.onSample(sample);
593
- }
594
- catch (err) {
595
- warn(options.log, err);
784
+ const now = options.readers.monotonicNowMs();
785
+ if (gated) {
786
+ if (checkpointMs <= 0)
787
+ return; // checkpoints disabled
788
+ if (lastObservationAtMs !== null && now - lastObservationAtMs < checkpointMs) {
789
+ return; // below the gate: one clock compare and out
790
+ }
596
791
  }
597
- if (pressure) {
792
+ const msSincePrev = lastObservationAtMs === null ? 0 : Math.max(0, Math.trunc(now - lastObservationAtMs));
793
+ lastObservationAtMs = now;
794
+ observationCount += 1;
795
+ if (source === "interval")
796
+ intervalObservationCount += 1;
797
+ else
798
+ checkpointObservationCount += 1;
799
+ const counters = snapshotCounters(msSincePrev);
800
+ if (source === "interval") {
801
+ const { sample, pressure, recycle, hardExit } = telemetry.sample();
598
802
  try {
599
- options.onPressure(pressure);
803
+ options.onSample(sample, counters);
600
804
  }
601
805
  catch (err) {
602
806
  warn(options.log, err);
603
807
  }
808
+ if (pressure) {
809
+ try {
810
+ options.onPressure(pressure, counters);
811
+ }
812
+ catch (err) {
813
+ warn(options.log, err);
814
+ }
815
+ }
816
+ deliver(recycle, hardExit, counters);
817
+ }
818
+ else {
819
+ const { recycle, hardExit } = telemetry.evaluate();
820
+ deliver(recycle, hardExit, counters);
604
821
  }
605
- if (recycle)
606
- fireRecycle(recycle);
607
822
  }
608
823
  catch (err) {
609
824
  warn(options.log, err);
610
825
  }
611
826
  };
612
- const handle = scheduler.setInterval(tick, intervalMs);
827
+ const handle = scheduler.setInterval(() => runObservation("interval", false), intervalMs);
613
828
  handle.unref?.();
614
- // The primary path: a major GC drives one (throttled) post-GC live evaluation.
829
+ // The primary path: a major GC drives one post-GC live evaluation. It also
830
+ // evaluates the hard tiers (a post-GC reading is the cleanest instantaneous
831
+ // value), so a latch that aged out or a hard-fraction crossing hard-exits here
832
+ // too. It is orthogonal to the cadence gate, so it never touches its counters.
615
833
  const gcObserver = options.gcObserver;
616
834
  if (gcObserver) {
617
835
  try {
@@ -619,9 +837,9 @@ export function startRunnerHeapSampling(options) {
619
837
  if (stopped)
620
838
  return;
621
839
  try {
622
- const recycle = telemetry.observeMajorGc();
623
- if (recycle)
624
- fireRecycle(recycle);
840
+ const { recycle, hardExit } = telemetry.observeMajorGc();
841
+ if (recycle || hardExit)
842
+ deliver(recycle, hardExit, snapshotCounters(0));
625
843
  }
626
844
  catch (err) {
627
845
  warn(options.log, err);
@@ -634,18 +852,8 @@ export function startRunnerHeapSampling(options) {
634
852
  }
635
853
  return {
636
854
  telemetry,
637
- evaluate: () => {
638
- if (stopped)
639
- return;
640
- try {
641
- const recycle = telemetry.evaluate();
642
- if (recycle)
643
- fireRecycle(recycle);
644
- }
645
- catch (err) {
646
- warn(options.log, err);
647
- }
648
- },
855
+ evaluate: () => runObservation("checkpoint", false),
856
+ maybeObserve: () => runObservation("checkpoint", true),
649
857
  stop: () => {
650
858
  if (stopped)
651
859
  return;
@@ -665,6 +873,34 @@ export function startRunnerHeapSampling(options) {
665
873
  },
666
874
  };
667
875
  }
876
+ /**
877
+ * Perform a deliberate hard exit for a `hard_fraction`/`latch_timeout` verdict.
878
+ * Writes the additive `heap-recycle` NDJSON record to stdout and the compact
879
+ * numeric stderr line — through SYNCHRONOUS injected writers, so both records
880
+ * land even when the streams are buffered or blocked — and only THEN exits. The
881
+ * exit code and the writers are injected so the exact write-before-exit ordering
882
+ * is unit-testable and the code stays the runner's single benign-exit constant.
883
+ */
884
+ export function performHeapHardExit(record, io, exitCode) {
885
+ // Both diagnostic writes are BEST-EFFORT: if the supervisor or a pipeline has
886
+ // closed stdout/stderr, a synchronous write can throw — but the exit is the
887
+ // whole point of this path (it replaces the V8 abort), so it must still run.
888
+ // The verdict is already latched one-shot, so a swallowed write with no exit
889
+ // would let the process climb on to the OOM this path exists to prevent.
890
+ try {
891
+ io.writeStdout(`${JSON.stringify({ type: "heap-recycle", ...record })}\n`);
892
+ }
893
+ catch {
894
+ /* stream closed — the fd-1 record is lost, but the exit still happens */
895
+ }
896
+ try {
897
+ io.writeStderr(`${heapRecycleStderrLine(record)}\n`);
898
+ }
899
+ catch {
900
+ /* stream closed — the stderr line is lost, but the exit still happens */
901
+ }
902
+ io.exit(exitCode);
903
+ }
668
904
  const defaultScheduler = {
669
905
  setInterval: (handler, ms) => setInterval(handler, ms),
670
906
  clearInterval: (handle) => clearInterval(handle),
@@ -685,12 +921,23 @@ export const HEAP_RECYCLE_LIVE_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_LIVE_
685
921
  export const HEAP_RECYCLE_SUSTAIN_WINDOW_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_SUSTAIN_WINDOW_MS";
686
922
  export const HEAP_RECYCLE_EMERGENCY_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_EMERGENCY_FRACTION";
687
923
  export const HEAP_RECYCLE_MIN_UPTIME_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_MIN_UPTIME_MS";
924
+ export const HEAP_CHECKPOINT_MS_ENV = "HQ_SYNC_RUNNER_HEAP_CHECKPOINT_MS";
925
+ export const HEAP_PINNED_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_PINNED_FRACTION";
926
+ export const HEAP_PINNED_SUSTAIN_MS_ENV = "HQ_SYNC_RUNNER_HEAP_PINNED_SUSTAIN_MS";
927
+ export const HEAP_HARD_EXIT_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_HARD_EXIT_FRACTION";
928
+ export const HEAP_RECYCLE_LATCH_HARD_EXIT_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_LATCH_HARD_EXIT_MS";
688
929
  export const DEFAULT_HEAP_SAMPLE_INTERVAL_MS = DEFAULT_SAMPLE_INTERVAL_MS;
689
930
  export const DEFAULT_HEAP_PRESSURE_FRACTION = DEFAULT_PRESSURE_THRESHOLD;
690
931
  export const DEFAULT_HEAP_RECYCLE_LIVE_FRACTION = DEFAULT_RECYCLE_LIVE_FRACTION;
691
932
  export const DEFAULT_HEAP_RECYCLE_SUSTAIN_WINDOW_MS = DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS;
692
933
  export const DEFAULT_HEAP_RECYCLE_EMERGENCY_FRACTION = DEFAULT_RECYCLE_EMERGENCY_FRACTION;
693
934
  export const DEFAULT_HEAP_RECYCLE_MIN_UPTIME_MS = DEFAULT_RECYCLE_MIN_UPTIME_MS;
935
+ export const DEFAULT_HEAP_CHECKPOINT_MS = DEFAULT_CHECKPOINT_MS;
936
+ export const DEFAULT_HEAP_PINNED_FRACTION = DEFAULT_RECYCLE_PINNED_FRACTION;
937
+ export const DEFAULT_HEAP_PINNED_SUSTAIN_MS = DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
938
+ export const DEFAULT_HEAP_HARD_EXIT_FRACTION = DEFAULT_HARD_EXIT_FRACTION;
939
+ export const DEFAULT_HEAP_RECYCLE_LATCH_HARD_EXIT_MS = DEFAULT_LATCH_HARD_EXIT_MS;
940
+ export const DEFAULT_HEAP_RECYCLE_LATCH_HARD_EXIT_OBSERVATIONS = DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
694
941
  /**
695
942
  * Parse the sampling-interval env knob (whole milliseconds). Rejects the ENTIRE
696
943
  * string: a value like "60s" must fall back to the default, not silently parse
@@ -790,6 +1037,148 @@ export function resolveHeapRecycleMinUptimeMs(raw) {
790
1037
  const value = Number.parseInt(trimmed, 10);
791
1038
  return Number.isFinite(value) && value >= 0 ? value : DEFAULT_RECYCLE_MIN_UPTIME_MS;
792
1039
  }
1040
+ /**
1041
+ * Parse the checkpoint-gate knob (whole milliseconds, >= 0). 0 is a VALID value
1042
+ * — it disables the work-driven checkpoints, leaving the interval timer and the
1043
+ * loop-top backstop as the only observers (exact base behaviour) — so only a
1044
+ * non-integer or negative value falls back to the 250 ms default.
1045
+ */
1046
+ export function resolveHeapCheckpointMs(raw) {
1047
+ if (raw === undefined)
1048
+ return DEFAULT_CHECKPOINT_MS;
1049
+ const trimmed = raw.trim();
1050
+ if (!/^\d+$/.test(trimmed))
1051
+ return DEFAULT_CHECKPOINT_MS;
1052
+ const value = Number.parseInt(trimmed, 10);
1053
+ return Number.isFinite(value) && value >= 0 ? value : DEFAULT_CHECKPOINT_MS;
1054
+ }
1055
+ /**
1056
+ * Parse the pinned-fraction knob; falls back to the default (0.84) on garbage or
1057
+ * out-of-range input. Rejects the entire string rather than a numeric prefix.
1058
+ */
1059
+ export function resolveHeapPinnedFraction(raw) {
1060
+ if (raw === undefined)
1061
+ return DEFAULT_RECYCLE_PINNED_FRACTION;
1062
+ const trimmed = raw.trim();
1063
+ if (!/^\d*\.?\d+$/.test(trimmed))
1064
+ return DEFAULT_RECYCLE_PINNED_FRACTION;
1065
+ const value = Number.parseFloat(trimmed);
1066
+ return Number.isFinite(value) && value > 0 && value <= 1
1067
+ ? value
1068
+ : DEFAULT_RECYCLE_PINNED_FRACTION;
1069
+ }
1070
+ /**
1071
+ * Parse the pinned-sustain-window knob (whole milliseconds, >= 0). 0 is a VALID
1072
+ * value — it removes the window so two qualifying observations at the same uptime
1073
+ * suffice, which the deterministic tests rely on — so only a non-integer or
1074
+ * negative value falls back to the 20-second default.
1075
+ */
1076
+ export function resolveHeapPinnedSustainMs(raw) {
1077
+ if (raw === undefined)
1078
+ return DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
1079
+ const trimmed = raw.trim();
1080
+ if (!/^\d+$/.test(trimmed))
1081
+ return DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
1082
+ const value = Number.parseInt(trimmed, 10);
1083
+ return Number.isFinite(value) && value >= 0
1084
+ ? value
1085
+ : DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
1086
+ }
1087
+ /**
1088
+ * Parse the hard-exit-fraction knob; falls back to the default (0.955) on garbage
1089
+ * or out-of-range input. Rejects the entire string rather than a numeric prefix.
1090
+ */
1091
+ export function resolveHeapHardExitFraction(raw) {
1092
+ if (raw === undefined)
1093
+ return DEFAULT_HARD_EXIT_FRACTION;
1094
+ const trimmed = raw.trim();
1095
+ if (!/^\d*\.?\d+$/.test(trimmed))
1096
+ return DEFAULT_HARD_EXIT_FRACTION;
1097
+ const value = Number.parseFloat(trimmed);
1098
+ return Number.isFinite(value) && value > 0 && value <= 1 ? value : DEFAULT_HARD_EXIT_FRACTION;
1099
+ }
1100
+ /**
1101
+ * Parse the latch-hard-exit knob (whole milliseconds, >= 0). 0 is a VALID value
1102
+ * — it makes the first post-latch observation hard-exit — so only a non-integer
1103
+ * or negative value falls back to the 60-second default.
1104
+ */
1105
+ export function resolveHeapRecycleLatchHardExitMs(raw) {
1106
+ if (raw === undefined)
1107
+ return DEFAULT_LATCH_HARD_EXIT_MS;
1108
+ const trimmed = raw.trim();
1109
+ if (!/^\d+$/.test(trimmed))
1110
+ return DEFAULT_LATCH_HARD_EXIT_MS;
1111
+ const value = Number.parseInt(trimmed, 10);
1112
+ return Number.isFinite(value) && value >= 0 ? value : DEFAULT_LATCH_HARD_EXIT_MS;
1113
+ }
1114
+ const MAX_OLD_SPACE_FLAG = /^--max[-_]old[-_]space[-_]size$/;
1115
+ /** A whole positive integer of MB → bytes, else null (whole-string only). */
1116
+ function wholeMbToBytes(raw) {
1117
+ const trimmed = raw.trim();
1118
+ if (!/^\d+$/.test(trimmed))
1119
+ return null;
1120
+ const mb = Number.parseInt(trimmed, 10);
1121
+ return Number.isFinite(mb) && mb > 0 ? mb * 1024 * 1024 : null;
1122
+ }
1123
+ /** Strip exactly one pair of surrounding single/double quotes, if present. */
1124
+ function unquoteOptionValue(value) {
1125
+ if (value.length >= 2) {
1126
+ const first = value[0];
1127
+ const last = value[value.length - 1];
1128
+ if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
1129
+ return value.slice(1, -1);
1130
+ }
1131
+ }
1132
+ return value;
1133
+ }
1134
+ /** Last valid `--max-old-space-size` value in a token list, or null. */
1135
+ function declaredCeilingFromTokens(tokens) {
1136
+ let last = null;
1137
+ for (let i = 0; i < tokens.length; i += 1) {
1138
+ const token = tokens[i];
1139
+ const eq = token.indexOf("=");
1140
+ if (eq >= 0) {
1141
+ if (MAX_OLD_SPACE_FLAG.test(token.slice(0, eq))) {
1142
+ const bytes = wholeMbToBytes(unquoteOptionValue(token.slice(eq + 1)));
1143
+ if (bytes !== null)
1144
+ last = bytes;
1145
+ }
1146
+ }
1147
+ else if (MAX_OLD_SPACE_FLAG.test(token)) {
1148
+ const next = tokens[i + 1];
1149
+ if (next !== undefined) {
1150
+ const bytes = wholeMbToBytes(unquoteOptionValue(next));
1151
+ if (bytes !== null)
1152
+ last = bytes;
1153
+ }
1154
+ }
1155
+ }
1156
+ return last;
1157
+ }
1158
+ /**
1159
+ * Resolve the declared V8 old-space ceiling (bytes) the runner is actually
1160
+ * running under, mirroring how hq-desktop-app hands it to the npx-spawned
1161
+ * runner: a `--max-old-space-size` flag on `process.execArgv` wins over one in
1162
+ * `NODE_OPTIONS`, and within each source the LAST occurrence wins (V8's own
1163
+ * precedence). Both the `=value` and adjacent-arg forms are accepted, values may
1164
+ * carry one pair of surrounding quotes, and only a whole positive integer of MB
1165
+ * is honoured — anything else yields null, so the governor falls back to V8's
1166
+ * reported `heap_size_limit`. Never throws.
1167
+ */
1168
+ export function resolveDeclaredHeapCeilingBytes(execArgv, nodeOptions) {
1169
+ try {
1170
+ const fromArgv = declaredCeilingFromTokens(execArgv ?? []);
1171
+ if (fromArgv !== null)
1172
+ return fromArgv;
1173
+ if (nodeOptions === undefined)
1174
+ return null;
1175
+ const tokens = nodeOptions.trim().split(/\s+/).filter(Boolean);
1176
+ return declaredCeilingFromTokens(tokens);
1177
+ }
1178
+ catch {
1179
+ return null;
1180
+ }
1181
+ }
793
1182
  /**
794
1183
  * Production readers over the real runtime. Kept here so the wiring site stays
795
1184
  * a one-liner and the `v8` import lives in exactly one place.