@wrongstack/core 0.296.4 → 0.298.0

package/dist/utils/heap-watchdog.js

@@ -1,7 +1,148 @@
 // src/utils/heap-watchdog.ts
+import * as fs from "node:fs";
+import * as fsp2 from "node:fs/promises";
+import * as path3 from "node:path";
+import { PerformanceObserver, constants as performanceConstants } from "node:perf_hooks";
+import * as v8 from "node:v8";
+
+// src/utils/memory-flight-recorder.ts
 import * as fsp from "node:fs/promises";
 import * as path2 from "node:path";
-import * as v8 from "node:v8";
+
+// src/utils/continuous-memory-profiler.ts
+import { Session } from "node:inspector/promises";
+var DEFAULT_SAMPLE_INTERVAL_BYTES = 512 * 1024;
+var DEFAULT_STACK_DEPTH = 64;
+var MAX_SUMMARY_STACKS = 20;
+var MAX_FRAMES_PER_STACK = 12;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function numeric(value) {
+  if (typeof value === "bigint") return Number(value);
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function summarizePprof(profile) {
+  const strings = profile.stringTable.strings;
+  const functions = new Map(profile.function.map((entry) => [numeric(entry.id), entry]));
+  const locations = new Map(profile.location.map((entry) => [numeric(entry.id), entry]));
+  const stacks = /* @__PURE__ */ new Map();
+  let sampledBytes = 0;
+  let sampledObjects = 0;
+  for (const sample of profile.sample) {
+    const objects = numeric(sample.value[0]);
+    const bytes = numeric(sample.value[1]);
+    sampledObjects += objects;
+    sampledBytes += bytes;
+    const frames = sample.locationId.slice(0, MAX_FRAMES_PER_STACK).flatMap((locationId) => {
+      const location = locations.get(numeric(locationId));
+      const line = location?.line[0];
+      const fn = line ? functions.get(numeric(line.functionId)) : void 0;
+      if (!fn) return [];
+      const name = strings[numeric(fn.name)] || "(anonymous)";
+      const filename = strings[numeric(fn.filename)] || "";
+      const lineNumber = numeric(line?.line);
+      return [filename ? `${name} (${filename}${lineNumber > 0 ? `:${lineNumber}` : ""})` : name];
+    });
+    if (frames.length === 0) frames.push("(unknown)");
+    const key = frames.join("\n");
+    const existing = stacks.get(key);
+    if (existing) {
+      existing.bytes += bytes;
+      existing.objects += objects;
+    } else {
+      stacks.set(key, { bytes, objects, frames });
+    }
+  }
+  return {
+    sampledBytes,
+    sampledObjects,
+    sampleCount: profile.sample.length,
+    topStacks: [...stacks.values()].sort((left, right) => right.bytes - left.bytes).slice(0, MAX_SUMMARY_STACKS)
+  };
+}
+async function startDatadogProfiler() {
+  const pprof = await import("@datadog/pprof");
+  pprof.heap.start(DEFAULT_SAMPLE_INTERVAL_BYTES, DEFAULT_STACK_DEPTH);
+  let stopped = false;
+  return {
+    backend: "datadog-pprof",
+    capture: async () => {
+      if (stopped) throw new Error("Continuous memory profiler is stopped");
+      const profile = pprof.heap.profile();
+      return {
+        backend: "datadog-pprof",
+        data: await pprof.encode(profile),
+        extension: ".pb.gz",
+        summary: summarizePprof(profile)
+      };
+    },
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      pprof.heap.stop();
+    }
+  };
+}
+async function startInspectorProfiler() {
+  const session = new Session();
+  session.connect();
+  try {
+    await session.post("HeapProfiler.enable");
+    await session.post("HeapProfiler.startSampling", {
+      samplingInterval: DEFAULT_SAMPLE_INTERVAL_BYTES,
+      includeObjectsCollectedByMajorGC: false,
+      includeObjectsCollectedByMinorGC: false
+    });
+  } catch (error) {
+    try {
+      session.disconnect();
+    } catch {
+    }
+    throw error;
+  }
+  let stopped = false;
+  return {
+    backend: "node-inspector",
+    capture: async () => {
+      if (stopped) throw new Error("Continuous memory profiler is stopped");
+      const result = await session.post("HeapProfiler.stopSampling");
+      await session.post("HeapProfiler.startSampling", {
+        samplingInterval: DEFAULT_SAMPLE_INTERVAL_BYTES,
+        includeObjectsCollectedByMajorGC: false,
+        includeObjectsCollectedByMinorGC: false
+      });
+      return {
+        backend: "node-inspector",
+        data: JSON.stringify(result.profile),
+        extension: ".heapprofile"
+      };
+    },
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      try {
+        await session.post("HeapProfiler.disable");
+      } catch {
+      }
+      try {
+        session.disconnect();
+      } catch {
+      }
+    }
+  };
+}
+async function startContinuousMemoryProfiler() {
+  try {
+    return { profiler: await startDatadogProfiler() };
+  } catch (error) {
+    const fallbackReason = errorMessage(error);
+    return {
+      profiler: await startInspectorProfiler(),
+      fallbackReason
+    };
+  }
+}
 
 // src/utils/wstack-paths.ts
 import * as os from "node:os";
@@ -12,27 +153,310 @@ function wstackGlobalRoot() {
   return path.join(os.homedir(), ".wrongstack");
 }
 
-// src/utils/heap-watchdog.ts
+// src/utils/memory-flight-recorder.ts
 var MB = 1024 * 1024;
+var HOUR_MS = 60 * 60 * 1e3;
+var DEFAULT_WINDOW_MS = 5 * 60 * 1e3;
+var DEFAULT_MINIMUM_WINDOW_MS = 2 * 60 * 1e3;
+var DEFAULT_COOLDOWN_MS = 15 * 60 * 1e3;
+var DEFAULT_CONTINUOUS_CAPTURE_MS = 5 * 60 * 1e3;
+var MAX_OBSERVATIONS = 24;
+var MAX_CAPTURE_SESSIONS = 12;
+var MAX_CAPTURES_PER_SESSION = 6;
+var SESSION_MAX_AGE_MS = 7 * 24 * HOUR_MS;
+function timestampSlug(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replaceAll(":", "").replaceAll(".", "-");
+}
+async function pruneCaptureFiles(artifactDir) {
+  const entries = await fsp.readdir(artifactDir, { withFileTypes: true });
+  const captures = entries.filter(
+    (entry) => entry.isFile() && entry.name.startsWith("event-") && entry.name.endsWith(".json")
+  ).map((entry) => entry.name).sort();
+  const remove = captures.slice(0, Math.max(0, captures.length - MAX_CAPTURES_PER_SESSION));
+  await Promise.all(
+    remove.flatMap((eventName) => {
+      const stem = eventName.slice("event-".length, -".json".length);
+      return [
+        fsp.rm(path2.join(artifactDir, eventName), { force: true }),
+        fsp.rm(path2.join(artifactDir, `allocations-${stem}.heapprofile`), { force: true }),
+        fsp.rm(path2.join(artifactDir, `allocations-${stem}.pb.gz`), { force: true })
+      ];
+    })
+  );
+}
+async function pruneOldSessions(root, currentDir) {
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  const sessions = await Promise.all(
+    entries.filter((entry) => entry.isDirectory() && entry.name !== path2.basename(currentDir)).map(async (entry) => {
+      const fullPath = path2.join(root, entry.name);
+      const stat2 = await fsp.stat(fullPath);
+      return { fullPath, mtimeMs: stat2.mtimeMs };
+    })
+  );
+  sessions.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const now = Date.now();
+  await Promise.all(
+    sessions.filter(
+      (session, index) => now - session.mtimeMs > SESSION_MAX_AGE_MS || index >= MAX_CAPTURE_SESSIONS && now - session.mtimeMs > 24 * HOUR_MS
+    ).map((session) => fsp.rm(session.fullPath, { recursive: true, force: true }))
+  );
+}
+var ContinuousMemoryCaptureWriter = class {
+  artifactDir;
+  root;
+  ready;
+  profiler;
+  profilerBackend = "initializing";
+  fallbackReason;
+  startError;
+  lastSummary;
+  stopped = false;
+  constructor(root) {
+    this.root = root;
+    this.artifactDir = path2.join(root, `${timestampSlug()}-pid-${process.pid}`);
+    this.ready = this.start().catch((error) => {
+      this.startError = error instanceof Error ? error.message : String(error);
+      this.profilerBackend = "unavailable";
+    });
+  }
+  async start() {
+    const started = await startContinuousMemoryProfiler();
+    this.profiler = started.profiler;
+    this.profilerBackend = started.profiler.backend;
+    this.fallbackReason = started.fallbackReason;
+  }
+  diagnostics() {
+    return {
+      memoryProfilerBackend: this.profilerBackend,
+      ...this.fallbackReason ? { memoryProfilerFallbackReason: this.fallbackReason } : {},
+      ...this.startError ? { memoryProfilerStartError: this.startError } : {},
+      ...this.lastSummary ? {
+        memoryProfileSampledBytes: this.lastSummary.sampledBytes,
+        memoryProfileSampledObjects: this.lastSummary.sampledObjects,
+        memoryProfileSampleCount: this.lastSummary.sampleCount,
+        memoryProfileTopStack: this.lastSummary.topStack,
+        memoryProfileTopStackBytes: this.lastSummary.topStackBytes
+      } : {}
+    };
+  }
+  async capture(event) {
+    await this.ready;
+    if (this.stopped) return;
+    let profile;
+    let captureError = this.startError;
+    if (!captureError && this.profiler) {
+      try {
+        profile = await this.profiler.capture();
+        const top = profile.summary?.topStacks[0];
+        if (profile.summary) {
+          this.lastSummary = {
+            sampledBytes: profile.summary.sampledBytes,
+            sampledObjects: profile.summary.sampledObjects,
+            sampleCount: profile.summary.sampleCount,
+            topStack: top?.frames.join(" <- "),
+            topStackBytes: top?.bytes
+          };
+        }
+      } catch (error) {
+        captureError = error instanceof Error ? error.message : String(error);
+      }
+    }
+    await fsp.mkdir(this.artifactDir, { recursive: true });
+    const stem = `${timestampSlug(new Date(event.capturedAt))}-${event.reason}`;
+    await fsp.writeFile(
+      path2.join(this.artifactDir, `event-${stem}.json`),
+      `${JSON.stringify(
+        {
+          ...event,
+          profilerBackend: profile?.backend ?? this.profilerBackend,
+          ...profile?.summary ? { allocationSummary: profile.summary } : {},
+          ...this.fallbackReason ? { profilerFallbackReason: this.fallbackReason } : {},
+          ...captureError ? { captureError } : {}
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+    if (profile) {
+      await fsp.writeFile(
+        path2.join(this.artifactDir, `allocations-${stem}${profile.extension}`),
+        profile.data
+      );
+    }
+    await Promise.all([
+      pruneCaptureFiles(this.artifactDir),
+      fsp.mkdir(this.root, { recursive: true }).then(() => pruneOldSessions(this.root, this.artifactDir))
+    ]);
+  }
+  async stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    await this.ready;
+    await this.profiler?.stop();
+  }
+};
+function disabledWriter(artifactDir) {
+  return {
+    artifactDir,
+    capture: async () => void 0,
+    stop: async () => void 0
+  };
+}
+function createMemoryFlightRecorder(options = {}) {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const root = options.diagnosticsRoot ?? path2.join(wstackGlobalRoot(), "diagnostics", "memory");
+  const enabled = options.enabled ?? (process.env["WRONGSTACK_MEMORY_FLIGHT_RECORDER"] !== "0" && process.env["NODE_ENV"] !== "test");
+  const writer = options.captureWriter ?? (enabled ? new ContinuousMemoryCaptureWriter(root) : disabledWriter(path2.join(root, `${timestampSlug()}-pid-${process.pid}`)));
+  const observations = [];
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  const minimumWindowMs = options.minimumWindowMs ?? DEFAULT_MINIMUM_WINDOW_MS;
+  const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  const continuousCaptureMs = options.continuousCaptureMs ?? DEFAULT_CONTINUOUS_CAPTURE_MS;
+  const warmupMs = options.warmupMs ?? 6e4;
+  let lastSignalCaptureAt = Number.NEGATIVE_INFINITY;
+  let lastContinuousCaptureAt = startedAt;
+  let captureInFlight = false;
+  let capturePromise;
+  const observe = (sample, stats) => {
+    const at = now();
+    const postGcHeapUsed = typeof stats["postGcHeapUsed"] === "number" ? stats["postGcHeapUsed"] : 0;
+    const postMajorGcHeapUsed = typeof stats["postMajorGcHeapUsed"] === "number" ? stats["postMajorGcHeapUsed"] : 0;
+    const lastGcAgoMs = typeof stats["lastGcAgoMs"] === "number" ? stats["lastGcAgoMs"] : -1;
+    const lastMajorGcAgoMs = typeof stats["lastMajorGcAgoMs"] === "number" ? stats["lastMajorGcAgoMs"] : -1;
+    const retainedHeapUsed = postMajorGcHeapUsed > 0 && lastMajorGcAgoMs >= 0 && lastMajorGcAgoMs <= windowMs ? postMajorGcHeapUsed : postGcHeapUsed > 0 && lastGcAgoMs >= 0 && lastGcAgoMs <= minimumWindowMs ? postGcHeapUsed : sample.heapUsed;
+    observations.push({
+      at,
+      heapUsed: retainedHeapUsed,
+      rss: sample.rss,
+      nativeResidual: sample.nativeResidual ?? 0
+    });
+    while (observations.length > MAX_OBSERVATIONS || observations.length > 1 && at - (observations[0]?.at ?? at) > windowMs) {
+      observations.shift();
+    }
+    const first = observations[0] ?? observations.at(-1);
+    const elapsedMs = first ? Math.max(0, at - first.at) : 0;
+    const heapGrowthBytes = first ? retainedHeapUsed - first.heapUsed : 0;
+    const rssGrowthBytes = first ? sample.rss - first.rss : 0;
+    const nativeGrowthBytes = first ? (sample.nativeResidual ?? 0) - first.nativeResidual : 0;
+    const heapGrowthBytesPerHour = elapsedMs > 0 ? Math.round(heapGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    const rssGrowthBytesPerHour = elapsedMs > 0 ? Math.round(rssGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    const nativeGrowthBytesPerHour = elapsedMs > 0 ? Math.round(nativeGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    let signal = "stable";
+    if ((sample.detachedContexts ?? 0) > 0) signal = "detached-contexts";
+    else if (heapGrowthBytes >= 32 * MB && heapGrowthBytesPerHour > 0) signal = "js-retention";
+    else if (nativeGrowthBytes >= 64 * MB && nativeGrowthBytesPerHour > 0) signal = "native-rss";
+    const diagnosis = {
+      memorySignal: signal,
+      memoryWindowMs: elapsedMs,
+      retainedHeapUsed,
+      transientHeapBytes: Math.max(0, sample.heapUsed - retainedHeapUsed),
+      heapGrowthBytes,
+      rssGrowthBytes,
+      nativeGrowthBytes,
+      heapGrowthBytesPerHour,
+      rssGrowthBytesPerHour,
+      nativeGrowthBytesPerHour,
+      memoryArtifactDir: writer.artifactDir,
+      ...writer.diagnostics?.() ?? {}
+    };
+    let reason;
+    if (at - startedAt >= warmupMs) {
+      if ((sample.detachedContexts ?? 0) > 0) reason = "detached-contexts";
+      else if (sample.load >= 0.45) reason = "heap-load";
+      else if (sample.heapUsed >= (options.absoluteHeapBytes ?? 768 * MB)) {
+        reason = "absolute-heap";
+      } else if (elapsedMs >= minimumWindowMs && heapGrowthBytes >= (options.heapGrowthBytes ?? 32 * MB) && heapGrowthBytesPerHour >= (options.heapGrowthBytesPerHour ?? 192 * MB)) {
+        reason = "heap-growth";
+      } else if (elapsedMs >= minimumWindowMs && nativeGrowthBytes >= (options.nativeGrowthBytes ?? 128 * MB) && nativeGrowthBytesPerHour >= (options.nativeGrowthBytesPerHour ?? 256 * MB)) {
+        reason = "native-rss-growth";
+      }
+    }
+    const signalCaptureDue = reason !== void 0 && at - lastSignalCaptureAt >= cooldownMs;
+    const intervalCaptureDue = at - lastContinuousCaptureAt >= continuousCaptureMs;
+    const captureReason = signalCaptureDue ? reason : intervalCaptureDue ? "interval" : void 0;
+    if (enabled && captureReason && !captureInFlight) {
+      if (captureReason !== "interval") lastSignalCaptureAt = at;
+      lastContinuousCaptureAt = at;
+      captureInFlight = true;
+      diagnosis["memoryCaptureReason"] = captureReason;
+      capturePromise = writer.capture({
+        reason: captureReason,
+        capturedAt: new Date(at).toISOString(),
+        pid: process.pid,
+        sample,
+        stats,
+        diagnosis: { ...diagnosis },
+        observations: observations.map((observation) => ({ ...observation }))
+      }).catch(() => {
+      }).finally(() => {
+        captureInFlight = false;
+        capturePromise = void 0;
+      });
+    }
+    return diagnosis;
+  };
+  return {
+    artifactDir: writer.artifactDir,
+    observe,
+    stop: async () => {
+      await capturePromise;
+      await writer.stop();
+    }
+  };
+}
+
+// src/utils/heap-watchdog.ts
+var MB2 = 1024 * 1024;
 function defaultHeapLogPath() {
-  return path2.join(wstackGlobalRoot(), "logs", "heap.jsonl");
+  const override = process.env["WRONGSTACK_HEAP_LOG_PATH"]?.trim();
+  if (override) return path3.resolve(override);
+  return path3.join(wstackGlobalRoot(), "logs", "heap.jsonl");
 }
 function takeHeapSample() {
   const m = process.memoryUsage();
-  const limit = v8.getHeapStatistics().heap_size_limit || 0;
+  const heap = v8.getHeapStatistics();
+  const spaces = v8.getHeapSpaceStatistics();
+  const spaceUsed = (name) => spaces.find((space) => space.space_name === name)?.space_used_size ?? 0;
+  const limit = heap.heap_size_limit || 0;
+  let activeResources = 0;
+  let activeResourceTypes = "";
+  try {
+    const resources = process.getActiveResourcesInfo?.() ?? [];
+    activeResources = resources.length;
+    const counts = /* @__PURE__ */ new Map();
+    for (const resource of resources) counts.set(resource, (counts.get(resource) ?? 0) + 1);
+    activeResourceTypes = [...counts].sort(([left], [right]) => left.localeCompare(right)).map(([resource, count]) => `${resource}=${count}`).join(",");
+  } catch {
+  }
   return {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     rss: m.rss,
     heapUsed: m.heapUsed,
     heapTotal: m.heapTotal,
     external: m.external,
+    arrayBuffers: m.arrayBuffers,
+    nativeResidual: Math.max(0, m.rss - m.heapTotal - m.external),
+    oldSpaceUsed: spaceUsed("old_space"),
+    newSpaceUsed: spaceUsed("new_space"),
+    largeObjectSpaceUsed: spaceUsed("large_object_space"),
+    codeSpaceUsed: spaceUsed("code_space"),
+    mallocedMemory: heap.malloced_memory,
+    peakMallocedMemory: heap.peak_malloced_memory,
+    nativeContexts: heap.number_of_native_contexts,
+    detachedContexts: heap.number_of_detached_contexts,
+    activeResources,
+    activeResourceTypes,
     heapLimit: limit,
     load: limit > 0 ? m.heapUsed / limit : 0
   };
 }
 function startHeapWatchdog(opts = {}) {
-  const sampleEveryMs = opts.sampleEveryMs ?? 6e4;
-  const logEveryMs = opts.logEveryMs ?? 3e5;
+  const profileMode = process.env["WRONGSTACK_MEMORY_PROFILE"] === "1";
+  const sampleEveryMs = opts.sampleEveryMs ?? (profileMode ? 5e3 : 3e4);
+  const logEveryMs = opts.logEveryMs ?? (profileMode ? 5e3 : 6e4);
   const logPath = opts.logPath ?? defaultHeapLogPath();
   const warnAt = opts.warnAt ?? 0.6;
   const criticalAt = opts.criticalAt ?? 0.85;
@@ -45,13 +469,56 @@ function startHeapWatchdog(opts = {}) {
   let drainPromise;
   let stopped = false;
   let dirReady = false;
+  const flightRecorder = createMemoryFlightRecorder();
+  let gcMajorCount = 0;
+  let gcMinorCount = 0;
+  let gcIncrementalCount = 0;
+  let gcWeakCallbackCount = 0;
+  let gcDurationMs = 0;
+  let postGcHeapUsed = 0;
+  let postMajorGcHeapUsed = 0;
+  let lastGcAt = 0;
+  let lastMajorGcAt = 0;
+  const gcObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      const kind = entry.detail?.kind ?? 0;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MAJOR) !== 0) gcMajorCount++;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MINOR) !== 0) gcMinorCount++;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_INCREMENTAL) !== 0) {
+        gcIncrementalCount++;
+      }
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_WEAKCB) !== 0) gcWeakCallbackCount++;
+      gcDurationMs += entry.duration;
+      postGcHeapUsed = process.memoryUsage().heapUsed;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MAJOR) !== 0) {
+        postMajorGcHeapUsed = postGcHeapUsed;
+        lastMajorGcAt = Date.now();
+      }
+      lastGcAt = Date.now();
+    }
+  });
+  try {
+    gcObserver.observe({ entryTypes: ["gc"] });
+  } catch {
+  }
+  const collectRuntimeStats = () => ({
+    gcMajorCount,
+    gcMinorCount,
+    gcIncrementalCount,
+    gcWeakCallbackCount,
+    gcDurationMs: Math.round(gcDurationMs),
+    postGcHeapUsed,
+    postMajorGcHeapUsed,
+    lastGcAgoMs: lastGcAt > 0 ? Date.now() - lastGcAt : -1,
+    lastMajorGcAgoMs: lastMajorGcAt > 0 ? Date.now() - lastMajorGcAt : -1
+  });
   const writeDiagnosticLine = opts.writeDiagnosticLine ?? (async (targetPath, line) => {
     if (!dirReady) {
-      await fsp.mkdir(path2.dirname(targetPath), { recursive: true });
+      await fsp2.mkdir(path3.dirname(targetPath), { recursive: true });
       dirReady = true;
     }
-    await fsp.appendFile(targetPath, `${line}
-`, "utf8");
+    await fsp2.appendFile(targetPath, `${line}
+`, { encoding: "utf8", mode: 384 });
   });
   const drainWrites = async (firstLine) => {
     let line = firstLine;
@@ -74,6 +541,43 @@ function startHeapWatchdog(opts = {}) {
     writeInFlight = true;
     drainPromise = drainWrites(line);
   };
+  const appendTerminalSample = (event, error, origin) => {
+    if (stopped) return;
+    let extras = {};
+    try {
+      extras = opts.collectStats?.() ?? {};
+    } catch {
+    }
+    try {
+      const sample = takeHeapSample();
+      const runtimeStats = collectRuntimeStats();
+      fs.mkdirSync(path3.dirname(logPath), { recursive: true });
+      fs.appendFileSync(
+        logPath,
+        `${JSON.stringify({
+          ...extras,
+          ...runtimeStats,
+          event,
+          ...origin ? { crashOrigin: origin } : {},
+          ...error instanceof Error ? { errorName: error.name, errorMessage: error.message.slice(0, 1e3) } : {},
+          pid: process.pid,
+          ...sample,
+          exitCode: process.exitCode
+        })}
+`,
+        "utf8"
+      );
+    } catch {
+    }
+  };
+  const onUncaughtException = (error, origin) => {
+    appendTerminalSample("memory.flight_recorder.crash", error, origin);
+  };
+  const onProcessExit = () => {
+    appendTerminalSample("memory.flight_recorder.exit");
+  };
+  process.on("uncaughtExceptionMonitor", onUncaughtException);
+  process.on("exit", onProcessExit);
   const tick = () => {
     let userTimings = 0;
     try {
@@ -85,19 +589,27 @@ function startHeapWatchdog(opts = {}) {
     } catch {
     }
     const s = takeHeapSample();
+    let extras = {};
+    try {
+      extras = opts.collectStats?.() ?? {};
+    } catch {
+    }
+    const runtimeStats = collectRuntimeStats();
+    const diagnosticStats = { ...extras, ...runtimeStats };
+    const memoryDiagnosis = flightRecorder.observe(s, diagnosticStats);
     if (s.load >= criticalAt && criticalArmed) {
       criticalArmed = false;
       warnArmed = false;
       opts.onWarn?.(
         "critical",
-        `Heap critical: ${Math.round(s.heapUsed / MB)} MB of ~${Math.round(s.heapLimit / MB)} MB V8 limit (${Math.round(s.load * 100)}%). An out-of-memory crash is likely soon \u2014 finish/checkpoint work and restart the session. Diagnostics: ${logPath}`,
+        `Heap critical: ${Math.round(s.heapUsed / MB2)} MB of ~${Math.round(s.heapLimit / MB2)} MB V8 limit (${Math.round(s.load * 100)}%). An out-of-memory crash is likely soon \u2014 finish/checkpoint work and restart the session. Diagnostics: ${logPath}`,
         s
       );
     } else if (s.load >= warnAt && warnArmed) {
       warnArmed = false;
       opts.onWarn?.(
         "warn",
-        `Heap high: ${Math.round(s.heapUsed / MB)} MB of ~${Math.round(s.heapLimit / MB)} MB V8 limit (${Math.round(s.load * 100)}%). Memory diagnostics are being recorded to ${logPath}`,
+        `Heap high: ${Math.round(s.heapUsed / MB2)} MB of ~${Math.round(s.heapLimit / MB2)} MB V8 limit (${Math.round(s.load * 100)}%). Memory diagnostics are being recorded to ${logPath}`,
         s
       );
     }
@@ -105,14 +617,19 @@ function startHeapWatchdog(opts = {}) {
     if (!criticalArmed && s.load < criticalAt - REARM_MARGIN) criticalArmed = true;
     const due = Date.now() - lastLogAt >= logEveryMs;
     const crossed = s.load >= warnAt;
-    if (due || crossed) {
+    const captured = typeof memoryDiagnosis["memoryCaptureReason"] === "string";
+    if (due || crossed || captured) {
       lastLogAt = Date.now();
-      let extras = {};
-      try {
-        extras = opts.collectStats?.() ?? {};
-      } catch {
-      }
-      append(JSON.stringify({ pid: process.pid, ...s, userTimings, ...extras }));
+      append(
+        JSON.stringify({
+          ...extras,
+          ...runtimeStats,
+          ...memoryDiagnosis,
+          pid: process.pid,
+          ...s,
+          userTimings
+        })
+      );
     }
   };
   const timer = setInterval(tick, sampleEveryMs);
@@ -121,12 +638,69 @@ function startHeapWatchdog(opts = {}) {
   return async () => {
     stopped = true;
     clearInterval(timer);
+    gcObserver.disconnect();
+    process.removeListener("uncaughtExceptionMonitor", onUncaughtException);
+    process.removeListener("exit", onProcessExit);
     await drainPromise;
+    await flightRecorder.stop();
+  };
+}
+var sharedContributors = /* @__PURE__ */ new Map();
+var nextSharedContributorId = 1;
+var sharedSamplerActive = false;
+var stopSharedSampler;
+function collectSharedStats() {
+  const merged = {};
+  for (const contributor of sharedContributors.values()) {
+    try {
+      Object.assign(merged, contributor.collectStats?.() ?? {});
+    } catch {
+    }
+  }
+  return merged;
+}
+function warnSharedContributors(level, message, sample) {
+  for (const contributor of sharedContributors.values()) {
+    try {
+      contributor.onWarn?.(level, message, sample);
+    } catch {
+    }
+  }
+}
+function startSharedHeapWatchdog(opts = {}) {
+  if (process.env["NODE_ENV"] === "test" && !sharedSamplerActive && opts.logPath === void 0 && opts.writeDiagnosticLine === void 0) {
+    return async () => void 0;
+  }
+  const id = nextSharedContributorId++;
+  sharedContributors.set(id, {
+    collectStats: opts.collectStats,
+    onWarn: opts.onWarn
+  });
+  if (!sharedSamplerActive) {
+    sharedSamplerActive = true;
+    stopSharedSampler = startHeapWatchdog({
+      ...opts,
+      collectStats: collectSharedStats,
+      onWarn: warnSharedContributors
+    });
+  }
+  let stopped = false;
+  return async () => {
+    if (stopped) return;
+    stopped = true;
+    sharedContributors.delete(id);
+    if (sharedContributors.size > 0 || !sharedSamplerActive) return;
+    const stop = stopSharedSampler;
+    if (!stop) return;
+    sharedSamplerActive = false;
+    stopSharedSampler = void 0;
+    await stop();
   };
 }
 export {
   defaultHeapLogPath,
   startHeapWatchdog,
+  startSharedHeapWatchdog,
   takeHeapSample
 };
 //# sourceMappingURL=heap-watchdog.js.map