@duckmind/dm-linux-x64 0.63.9 → 0.64.6

package/extensions/dm-lens/clients/dead-code-client.js

@@ -0,0 +1,347 @@
+import { createSubsystemLogger } from "./extension-log.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findLocalBinsAt, VENV_BIN_DIRS } from "./package-manager.js";
+import { findNearestMarkerRoot } from "./path-utils.js";
+import { getScratchTreeFnmatchPatterns } from "./scratch-tree-policy.js";
+import { safeSpawnAsync } from "./safe-spawn.js";
+import {
+  classifyProbeFailure,
+  createAvailabilityLatch,
+  logAvailabilityDecision,
+  startHostStallSampler
+} from "./dispatch/runners/utils/availability-policy.js";
+import {
+  firstOutputLine,
+  spawnFailedWithNoOutput
+} from "./dispatch/runners/utils/spawn-outcome.js";
+import { formatToolFailure } from "./dispatch/runners/utils/tool-failure.js";
+function emptyResult(language) {
+  return {
+    success: false,
+    language,
+    unusedExports: [],
+    unusedFiles: [],
+    unusedDeps: [],
+    unlistedDeps: []
+  };
+}
+const ANALYSIS_TIMEOUT_MS = 30000;
+const VULTURE_PYTHON_ONLY_EXCLUDES = ["*/site-packages/*", "*/.eggs/*"];
+const VULTURE_EXCLUDES = [
+  ...getScratchTreeFnmatchPatterns(),
+  ...VULTURE_PYTHON_ONLY_EXCLUDES
+];
+const VULTURE_IGNORE_DECORATORS = [
+  "@pytest.fixture",
+  "@pytest.fixture(*",
+  "@fixture",
+  "@fixture(*",
+  "@app.*",
+  "@router.*",
+  "@celery.task*",
+  "@task",
+  "@shared_task*"
+];
+const VULTURE_LINE = /^(.*?):(\d+): unused (\w[\w ]*?) '([^']+)' \((\d+)% confidence\)\s*$/;
+export function parseVultureOutput(output, root) {
+  const issues = [];
+  for (const raw of output.split(/\r?\n/)) {
+    const m = raw.match(VULTURE_LINE);
+    if (!m)
+      continue;
+    const [, file, line, kind, name, confidence] = m;
+    let rel = file;
+    try {
+      rel = path.relative(root, file) || file;
+    } catch {
+      rel = file;
+    }
+    issues.push({
+      category: "export",
+      kind: kind.trim(),
+      name,
+      file: rel,
+      line: Number.parseInt(line, 10),
+      confidence: Number.parseInt(confidence, 10)
+    });
+  }
+  return issues;
+}
+
+export class PythonDeadCodeClient {
+  id = "python";
+  language = "Python";
+  availabilityLatch = createAvailabilityLatch();
+  resolved = null;
+  ensureInFlight = null;
+  inFlight = new Map;
+  log;
+  constructor(verbose = false) {
+    this.log = verbose ? createSubsystemLogger("dead-code:python") : () => {};
+  }
+  get minConfidence() {
+    const raw = Number.parseInt(process.env.DM_LENS_VULTURE_MIN_CONFIDENCE ?? "60", 10);
+    return Number.isFinite(raw) ? Math.min(100, Math.max(0, raw)) : 60;
+  }
+  detect(cwd) {
+    return this.resolveProjectRoot(cwd) !== null;
+  }
+  owns(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === ".py" || ext === ".pyi";
+  }
+  resolveProjectRoot(startDir, homeDirOverride) {
+    return findNearestMarkerRoot(startDir, [
+      "pyproject.toml",
+      "setup.py",
+      "setup.cfg",
+      "requirements.txt",
+      "Pipfile",
+      "tox.ini"
+    ], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
+  }
+  async ensureAvailable(root) {
+    const memo = this.availabilityLatch.read();
+    if (memo !== null)
+      return memo;
+    if (this.ensureInFlight)
+      return this.ensureInFlight;
+    this.ensureInFlight = this.doEnsureAvailable(root);
+    try {
+      return await this.ensureInFlight;
+    } finally {
+      this.ensureInFlight = null;
+    }
+  }
+  venvCandidates(root) {
+    return findLocalBinsAt(["vulture"], root, {
+      windowsExt: ".exe",
+      binDirs: VENV_BIN_DIRS
+    }).map((full) => ({ cmd: full, prefix: [] }));
+  }
+  async doEnsureAvailable(root) {
+    const candidates = [
+      ...root ? this.venvCandidates(root) : [],
+      { cmd: "vulture", prefix: [] },
+      { cmd: "python", prefix: ["-m", "vulture"] },
+      { cmd: "python3", prefix: ["-m", "vulture"] }
+    ];
+    let sawTransient = false;
+    let transientCause = "probe-timeout";
+    const sweepStartedAt = Date.now();
+    let sweepHostStallMs = 0;
+    let sweepEvidence;
+    for (const c of candidates) {
+      const sampler = startHostStallSampler();
+      const startedAt = Date.now();
+      let probe;
+      let hostStallMs;
+      try {
+        probe = await safeSpawnAsync(c.cmd, [...c.prefix, "--version"], {
+          timeout: 5000
+        });
+      } finally {
+        hostStallMs = sampler.stop();
+        sweepHostStallMs += hostStallMs;
+      }
+      if (!probe.error && probe.status === 0) {
+        this.resolved = c;
+        this.availabilityLatch.noteAvailable();
+        this.log(`vulture found: ${[c.cmd, ...c.prefix].join(" ")}`);
+        logAvailabilityDecision({
+          tool: "vulture",
+          verdict: "available",
+          outcome: "success",
+          cause: "ok",
+          elapsedMs: Date.now() - startedAt,
+          latched: true,
+          hostStallMs,
+          budgetMs: 5000,
+          classifiedBy: "probe"
+        });
+        return true;
+      }
+      const classified = classifyProbeFailure(probe, {
+        hostStallMs,
+        command: c.cmd
+      });
+      sweepEvidence = classified.evidence;
+      if (classified.outcome === "transient") {
+        sawTransient = true;
+        transientCause = classified.cause;
+      }
+    }
+    if (sawTransient) {
+      const retryAfterMs = this.availabilityLatch.noteUnavailable("transient", transientCause);
+      this.log("vulture probe timed out; will retry (not treated as missing)");
+      logAvailabilityDecision({
+        tool: "vulture",
+        verdict: "unavailable",
+        outcome: "transient",
+        cause: transientCause,
+        elapsedMs: Date.now() - sweepStartedAt,
+        hostStallMs: sweepHostStallMs,
+        latched: false,
+        retryAfterMs,
+        budgetMs: 5000,
+        classifiedBy: "probe",
+        ...sweepEvidence !== undefined && { evidence: sweepEvidence }
+      });
+      return false;
+    }
+    this.availabilityLatch.noteUnavailable("missing", "not-found");
+    this.log("vulture not installed; skipping (no auto-install)");
+    logAvailabilityDecision({
+      tool: "vulture",
+      verdict: "unavailable",
+      outcome: "missing",
+      cause: "not-found",
+      elapsedMs: Date.now() - sweepStartedAt,
+      hostStallMs: sweepHostStallMs,
+      latched: true,
+      budgetMs: 5000,
+      classifiedBy: "probe",
+      ...sweepEvidence !== undefined && { evidence: sweepEvidence }
+    });
+    return false;
+  }
+  async analyze(cwd) {
+    const root = this.resolveProjectRoot(cwd || process.cwd());
+    if (!root) {
+      return {
+        ...emptyResult(this.language),
+        success: true,
+        summary: "No Python project root found; vulture skipped"
+      };
+    }
+    if (!await this.ensureAvailable(root)) {
+      return {
+        ...emptyResult(this.language),
+        success: true,
+        summary: "vulture not installed; skipped. Install vulture (pip/uv/pipx) to enable Python dead-code detection."
+      };
+    }
+    const key = path.resolve(root);
+    const existing = this.inFlight.get(key);
+    if (existing)
+      return existing;
+    const promise = this.runAnalyze(key);
+    const wrapped = promise.finally(() => {
+      if (this.inFlight.get(key) === wrapped)
+        this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, wrapped);
+    return wrapped;
+  }
+  hasProjectVultureConfig(root) {
+    try {
+      const content = fs.readFileSync(path.join(root, "pyproject.toml"), "utf-8");
+      return content.includes("[tool.vulture]");
+    } catch {
+      return false;
+    }
+  }
+  async runAnalyze(root) {
+    const startMs = Date.now();
+    const invocation = this.resolved ?? { cmd: "vulture", prefix: [] };
+    const hasConfig = this.hasProjectVultureConfig(root);
+    const args = [
+      ...invocation.prefix,
+      ".",
+      ...hasConfig ? [] : [`--min-confidence=${this.minConfidence}`],
+      ...hasConfig ? [] : [`--exclude=${VULTURE_EXCLUDES.join(",")}`],
+      `--ignore-decorators=${VULTURE_IGNORE_DECORATORS.join(",")}`
+    ];
+    const result = await safeSpawnAsync(invocation.cmd, args, {
+      timeout: ANALYSIS_TIMEOUT_MS,
+      cwd: root
+    });
+    const durationMs = Date.now() - startMs;
+    if (result.error) {
+      this.log(`scan error: ${result.error.message}`);
+      return {
+        ...emptyResult(this.language),
+        summary: `Error: ${result.error.message}`,
+        durationMs
+      };
+    }
+    const output = result.stdout || "";
+    if (!output.trim()) {
+      const stderr = (result.stderr || "").trim();
+      if (spawnFailedWithNoOutput(result, output)) {
+        const reason = formatToolFailure({
+          tool: "vulture",
+          status: result.status,
+          signal: result.signal,
+          stderr: result.stderr
+        });
+        this.log(reason);
+        incrementDegradationCount({
+          kind: "runner-empty-result",
+          subject: "vulture",
+          reason
+        });
+        return {
+          ...emptyResult(this.language),
+          summary: stderr ? `vulture error: ${firstOutputLine(stderr)}` : reason,
+          durationMs
+        };
+      }
+      return {
+        ...emptyResult(this.language),
+        success: true,
+        summary: "No dead code found",
+        durationMs
+      };
+    }
+    return { ...this.parseOutput(output, root), durationMs };
+  }
+  parseOutput(output, root) {
+    const unusedExports = parseVultureOutput(output, root);
+    const total = unusedExports.length;
+    return {
+      ...emptyResult(this.language),
+      success: true,
+      unusedExports,
+      summary: total === 0 ? "No dead code found" : `Found ${total} unused Python symbol(s)`
+    };
+  }
+}
+export function getDeadCodeClients(verbose = false) {
+  return [new PythonDeadCodeClient(verbose)];
+}
+export function deadCodeIssueCount(result) {
+  return result.unusedExports.length + result.unusedFiles.length + result.unusedDeps.length + result.unlistedDeps.length;
+}
+export function deadCodeIssues(result) {
+  return [
+    ...result.unusedExports,
+    ...result.unusedFiles,
+    ...result.unusedDeps,
+    ...result.unlistedDeps
+  ];
+}
+export function stableFindingKey(...parts) {
+  return parts.map((part) => part ?? "").join(":");
+}
+export function deadCodeIssueKey(issue) {
+  return stableFindingKey(issue.category, issue.file, issue.name);
+}
+export function formatDeadCodeDelta(issues, language, max = 5) {
+  if (issues.length === 0)
+    return "";
+  let report = `\uD83D\uDC80 Newly unused ${language} symbols in files you edited — check if callers need updating (dead-code):
+`;
+  for (const issue of issues.slice(0, max)) {
+    const loc = issue.file ? `${issue.file}${issue.line ? `:${issue.line}` : ""}` : "(unknown)";
+    report += `  ${loc} — unused ${issue.kind} ${issue.name}
+`;
+  }
+  if (issues.length > max) {
+    report += `  … and ${issues.length - max} more
+`;
+  }
+  return report;
+}

package/extensions/dm-lens/clients/dead-code-logger.js

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+import { isTestMode } from "./env-utils.js";
+import { getGlobalDmLensLogDir } from "./probe-home-state.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
+const LOG_DIR = getGlobalDmLensLogDir();
+const LOG_FILE = path.join(LOG_DIR, "dead-code.log");
+const LOG_BACKUP_FILE = path.join(LOG_DIR, "dead-code.log.1");
+const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.DM_LENS_DEAD_CODE_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
+const writer = createNdjsonLogger({
+  filePath: LOG_FILE,
+  maxBytes: MAX_LOG_BYTES,
+  backupPath: LOG_BACKUP_FILE
+});
+export function logDeadCodeScan(event) {
+  if (isTestMode())
+    return;
+  writer.log({ ts: new Date().toISOString(), ...event });
+}
+export function flushDeadCodeLog() {
+  return writer.flush();
+}

package/extensions/dm-lens/clients/deadline-utils.js

@@ -0,0 +1,117 @@
+import { recordDegradationOnce } from "./degradation-ledger.js";
+export function combineAbortSignals(...signals) {
+  const live = signals.filter((s) => s !== undefined);
+  if (live.length <= 1)
+    return live[0];
+  if (typeof AbortSignal.any === "function")
+    return AbortSignal.any(live);
+  const controller = new AbortController;
+  for (const s of live) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), {
+      once: true
+    });
+  }
+  return controller.signal;
+}
+export function withDeadline(promise, options) {
+  const onTimeout = options.onTimeout ?? "reject";
+  const onReject = options.onReject ?? "propagate";
+  const ms = options.ms ?? (options.deadlineAt !== undefined ? options.deadlineAt - Date.now() : 0);
+  if (ms <= 0) {
+    promise.catch(() => {});
+    return onTimeout === "undefined" ? Promise.resolve(undefined) : Promise.reject(new Error(`Timeout after ${Math.max(0, ms)}ms`));
+  }
+  const base = onReject === "undefined" ? promise.catch(() => {
+    return;
+  }) : promise;
+  if (onReject === "propagate")
+    promise.catch(() => {});
+  let timer;
+  const timeoutPromise = new Promise((resolve, reject) => {
+    timer = setTimeout(() => {
+      if (onTimeout === "undefined")
+        resolve(undefined);
+      else
+        reject(new Error(`Timeout after ${ms}ms`));
+    }, ms);
+  });
+  return Promise.race([base, timeoutPromise]).finally(() => {
+    if (timer)
+      clearTimeout(timer);
+  });
+}
+export function withTimeout(promise, timeoutMs) {
+  return withDeadline(promise, { ms: timeoutMs });
+}
+export function withBudget(promise, budgetMs) {
+  return withDeadline(promise, { ms: budgetMs, onTimeout: "undefined" });
+}
+export function withinRemaining(promise, deadlineAt) {
+  return withDeadline(promise, {
+    deadlineAt,
+    onTimeout: "undefined",
+    onReject: "undefined"
+  });
+}
+const BOUND_ABORTED = Symbol("dm-lens/bounded/aborted");
+export async function bounded(promise, options) {
+  const { signal, shutdownSignal, hook, label } = options;
+  const ms = Number.isFinite(options.ms) ? Math.max(0, options.ms) : 0;
+  const startedAt = Date.now();
+  const boxed = promise.then((value) => ({ value }));
+  boxed.catch(() => {});
+  let cause;
+  let timer;
+  let onCallerAbort;
+  let onShutdownAbort;
+  const abandoned = new Promise((resolve) => {
+    const fire = (reason) => {
+      cause ??= reason;
+      resolve(BOUND_ABORTED);
+    };
+    if (signal?.aborted)
+      return fire("caller-abort");
+    if (shutdownSignal?.aborted)
+      return fire("shutdown");
+    if (ms <= 0)
+      return fire("deadline");
+    timer = setTimeout(() => fire("deadline"), ms);
+    timer.unref?.();
+    onCallerAbort = () => fire("caller-abort");
+    signal?.addEventListener("abort", onCallerAbort, { once: true });
+    if (shutdownSignal) {
+      onShutdownAbort = () => fire("shutdown");
+      shutdownSignal.addEventListener("abort", onShutdownAbort, {
+        once: true
+      });
+    }
+  });
+  try {
+    const settled = await Promise.race([boxed, abandoned]);
+    if (settled !== BOUND_ABORTED)
+      return settled.value;
+    const elapsedMs = Date.now() - startedAt;
+    const fired = cause ?? "deadline";
+    if (fired === "deadline" || fired === "shutdown") {
+      recordDegradationOnce({
+        kind: fired === "deadline" ? "hook-await-exceeded" : "hook-await-abandoned",
+        subject: `${hook}:${label}`,
+        reason: fired === "deadline" ? `exceeded ${ms}ms budget after ${elapsedMs}ms` : `abandoned after ${elapsedMs}ms: session is shutting down (budget ${ms}ms)`,
+        metadata: { hook, label, budgetMs: ms, elapsedMs, cause: fired }
+      });
+    }
+    return;
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+    if (onCallerAbort)
+      signal?.removeEventListener("abort", onCallerAbort);
+    if (onShutdownAbort) {
+      shutdownSignal?.removeEventListener("abort", onShutdownAbort);
+    }
+  }
+}

package/extensions/dm-lens/clients/debug-handles.js

@@ -0,0 +1,121 @@
+import * as asyncHooks from "node:async_hooks";
+import * as path from "node:path";
+import { getGlobalDmLensLogDir } from "./probe-home-state.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
+const DEBUG_HANDLES_ENABLED = process.env.DM_LENS_DEBUG_HANDLES === "1";
+const DEBUG_HANDLES_LOG_FILE = path.join(getGlobalDmLensLogDir(), "debug-handles.log");
+export const TRACKER_MAX_ENTRIES = 500;
+export const TRACKER_PROTECTED_COUNT = 100;
+const TRACKED_TYPE_RE = /^(Timeout|Immediate|TCPWRAP|TCPSOCKETWRAP|TCPCONNECTWRAP|PIPEWRAP|PIPECONNECTWRAP|UDPWRAP|UDPSENDWRAP|TTYWRAP|ProcessWrap|Signal)/;
+function trimStack(raw) {
+  if (!raw)
+    return "";
+  const lines = raw.split(`
+`).slice(1);
+  const callerLines = lines.filter((line) => !line.includes("debug-handles.js") && !line.includes("debug-handles.js"));
+  return callerLines.slice(0, 8).join(`
+`).slice(0, 2000);
+}
+let trackedEvictedCount = 0;
+export function _evictedCountForTest() {
+  return trackedEvictedCount;
+}
+function recordTrackedInit(map, asyncId, type) {
+  if (!TRACKED_TYPE_RE.test(type))
+    return;
+  if (map.size >= TRACKER_MAX_ENTRIES) {
+    let index = 0;
+    let evictKey;
+    for (const key of map.keys()) {
+      if (index >= TRACKER_PROTECTED_COUNT) {
+        evictKey = key;
+        break;
+      }
+      index++;
+    }
+    if (evictKey !== undefined) {
+      map.delete(evictKey);
+      trackedEvictedCount++;
+    }
+  }
+  map.set(asyncId, { type, stack: trimStack(new Error().stack) });
+}
+function installHandleTracker() {
+  const map = new Map;
+  const hook = asyncHooks.createHook({
+    init(asyncId, type) {
+      recordTrackedInit(map, asyncId, type);
+    },
+    destroy(asyncId) {
+      map.delete(asyncId);
+    }
+  });
+  hook.enable();
+  return map;
+}
+const trackedResources = DEBUG_HANDLES_ENABLED ? installHandleTracker() : null;
+const writer = DEBUG_HANDLES_ENABLED ? createNdjsonLogger({
+  filePath: DEBUG_HANDLES_LOG_FILE,
+  maxBytes: getMaxLogSizeMB() * 1024 * 1024
+}) : null;
+export function isDebugHandlesEnabled() {
+  return DEBUG_HANDLES_ENABLED;
+}
+export function getDebugHandlesLogPath() {
+  return DEBUG_HANDLES_LOG_FILE;
+}
+export function flushDebugHandlesLog() {
+  return writer ? writer.flush() : Promise.resolve();
+}
+function safeGetActiveResourcesInfo() {
+  try {
+    const fn = process.getActiveResourcesInfo;
+    return typeof fn === "function" ? fn.call(process) : [];
+  } catch {
+    return [];
+  }
+}
+function summarizeCreationSites(map) {
+  const byType = new Map;
+  for (const { type, stack } of map.values()) {
+    const existing = byType.get(type);
+    if (existing) {
+      existing.count++;
+    } else {
+      byType.set(type, { type, count: 1, sampleStack: stack });
+    }
+  }
+  return [...byType.values()];
+}
+export function dumpActiveHandles(label) {
+  if (!DEBUG_HANDLES_ENABLED || !writer)
+    return;
+  const resources = safeGetActiveResourcesInfo();
+  const counts = {};
+  for (const type of resources) {
+    counts[type] = (counts[type] ?? 0) + 1;
+  }
+  const entry = {
+    ts: new Date().toISOString(),
+    label,
+    total: resources.length,
+    counts
+  };
+  if (trackedResources) {
+    entry.creationSites = summarizeCreationSites(trackedResources);
+    entry.evictedCount = trackedEvictedCount;
+  }
+  writer.log(entry);
+}
+export function _trackedResourceCountForTest() {
+  return trackedResources?.size ?? 0;
+}
+export function _isTrackedForTest(asyncId) {
+  return trackedResources?.has(asyncId) ?? false;
+}
+export function _simulateTrackedInitForTest(asyncId, type) {
+  if (!trackedResources)
+    return;
+  recordTrackedInit(trackedResources, asyncId, type);
+}

package/extensions/dm-lens/clients/debug-heap.js

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as v8 from "node:v8";
+import { getGlobalDmLensLogDir } from "./probe-home-state.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
+const DEBUG_HEAP_ENABLED = process.env.DM_LENS_DEBUG_HEAP === "1";
+export const SNAPSHOT_RETENTION = 3;
+const SNAPSHOT_PREFIX = "heap-";
+const SNAPSHOT_SUFFIX = ".heapsnapshot";
+const HEAP_SNAPSHOT_LOG_FILE = path.join(getGlobalDmLensLogDir(), "heap-snapshots.log");
+const writer = DEBUG_HEAP_ENABLED ? createNdjsonLogger({
+  filePath: HEAP_SNAPSHOT_LOG_FILE,
+  maxBytes: getMaxLogSizeMB() * 1024 * 1024
+}) : null;
+export function isDebugHeapEnabled() {
+  return DEBUG_HEAP_ENABLED;
+}
+export function getHeapSnapshotLogPath() {
+  return HEAP_SNAPSHOT_LOG_FILE;
+}
+export function flushHeapSnapshotLog() {
+  return writer ? writer.flush() : Promise.resolve();
+}
+export function snapshotFileName(pid, isoTs) {
+  return `${SNAPSHOT_PREFIX}${pid}-${isoTs.replace(/[:.]/g, "-")}${SNAPSHOT_SUFFIX}`;
+}
+export function pruneOldSnapshots(dir, keep = SNAPSHOT_RETENTION) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const snapshots = names.filter((name) => name.startsWith(SNAPSHOT_PREFIX) && name.endsWith(SNAPSHOT_SUFFIX)).map((name) => {
+    const full = path.join(dir, name);
+    let mtimeMs = 0;
+    try {
+      mtimeMs = fs.statSync(full).mtimeMs;
+    } catch {}
+    return { full, mtimeMs };
+  }).sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const removed = [];
+  for (const stale of snapshots.slice(Math.max(0, keep))) {
+    try {
+      fs.rmSync(stale.full, { force: true });
+      removed.push(stale.full);
+    } catch {}
+  }
+  return removed;
+}
+export function writeHeapSnapshotNow(label) {
+  if (!DEBUG_HEAP_ENABLED)
+    return null;
+  const dir = getGlobalDmLensLogDir();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {}
+  const ts = new Date().toISOString();
+  const target = path.join(dir, snapshotFileName(process.pid, ts));
+  const rssBytes = process.memoryUsage().rss;
+  const start = Date.now();
+  let written;
+  try {
+    written = v8.writeHeapSnapshot(target);
+  } catch {
+    return null;
+  }
+  const durationMs = Date.now() - start;
+  pruneOldSnapshots(dir);
+  writer?.log({
+    ts,
+    label,
+    path: written,
+    pid: process.pid,
+    rssBytes,
+    durationMs
+  });
+  return { path: written, rssBytes, durationMs };
+}