@memlab/mcp-server 2.18.1 → 2.52.0

package/dist/tools/leak-report.js

@@ -0,0 +1,256 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { z } from 'zod';
+import memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+import { artifactLabel } from '../artifact-classes.js';
+import { computeSequenceTrends, normalizeClassName, } from './sequence-analysis.js';
+import { collectDevRoots, computeReachableWithoutDevRoots, } from './dev-artifacts.js';
+import { getFirstNonFrameworkRetainer } from './detached-dom.js';
+// Nodes kept per candidate class for the retainer sample. Small on purpose: the
+// question is "what shape of thing holds these", and a handful of instances
+// answers it — walking thousands would cost more than the trend pass itself.
+const MAX_SAMPLES_PER_CLASS = 8;
+const RETAINER_SAMPLES = 3;
+// A class whose instances are overwhelmingly dev-root-retained is a measurement
+// artifact in production terms, whatever its growth curve looks like. Matches
+// the majority-not-any threshold intern_opportunities uses, for the same reason:
+// a class can legitimately mix a few console-held instances with real data.
+const DEV_ONLY_SHARE = 0.8;
+// Deliberately NOT a sum of retainedSize across the class: retained sizes
+// overlap wherever instances nest, so summing them reports figures larger than
+// the heap (measured: 5.9 GB of `Object` in a 200 MB heap). Net self-size delta
+// across the ladder is additive and is the growth the report is about anyway.
+function displayName(row) {
+    return row.name.length > 0 ? row.name : `(unnamed ${row.type})`;
+}
+function topRetainerLabel(ev) {
+    const counts = new Map();
+    for (const node of ev.samples.slice(0, RETAINER_SAMPLES)) {
+        const label = getFirstNonFrameworkRetainer(node);
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    let best = '(unknown)';
+    let bestCount = 0;
+    for (const [label, c] of counts) {
+        if (c > bestCount) {
+            best = label;
+            bestCount = c;
+        }
+    }
+    return best;
+}
+export function registerLeakReport(server) {
+    server.tool('memlab_leak_report', 'One-call leak triage across an ORDERED ladder of >=2 heap snapshots: runs the growth-trend pass, then gathers per-class EVIDENCE from the final snapshot and returns a single table — class, per-rung counts, Δ and Δ/cycle, how much of it is dev/automation-retained, the dominant retainer, and a verdict hint. ' +
+        'Exists because the trend pass alone cannot tell a leak from an artifact: every hunt then ran memlab_dev_artifacts and a retainer trace by hand on each grower and joined the three outputs mentally, which is the step that gets skipped right before something is reported as a production leak. Composes memlab_sequence_analysis with memlab_dev_artifacts and a retainer sample; costs one extra snapshot load (the last rung) on top of the ladder pass. ' +
+        'The verdict column is a HINT, not a conclusion — confirm a candidate with memlab_retainer_trace on the example node before calling it a leak. Paths may be local, manifold:// URLs, or bare filenames.', {
+        paths: z
+            .array(z.string())
+            .min(1)
+            .describe('Ordered list of >=2 snapshot paths (oldest first): local absolute paths, manifold:// URLs, or bare snapshot filenames. A single ["ladder:<name>"] entry expands to a ladder saved with memlab_ladder.'),
+        cycles: z
+            .number()
+            .optional()
+            .describe('Number of interaction cycles driven between the FIRST and LAST snapshot. When provided, a "Δ/cycle" column is reported — a per-cycle rate is what says whether growth scales with interaction, which a total cannot.'),
+        limit: z
+            .number()
+            .optional()
+            .default(10)
+            .describe('Maximum number of growing classes to gather evidence for (default 10).'),
+        min_growth_count: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Only consider classes whose net instance-count growth is at least this (default 50).'),
+        monotonic_only: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Only consider classes that grew at EVERY step (default false: grew-net classes are included and flagged as noisy).'),
+        include_artifacts: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include classes that are known measurement artifacts (CDP inspector retention, V8 JIT warmup, Blink a11y caches, captured Error stacks). Default false: they are counted in a one-line summary instead of consuming evidence slots, since none of them is an app leak.'),
+        max_file_size_mb: z
+            .number()
+            .optional()
+            .describe('Per-file size ceiling in MB, matching memlab_load_snapshot / memlab_sequence_analysis defaults. Snapshots are loaded one at a time and dropped before the next.'),
+    }, async ({ paths, cycles, limit, min_growth_count, monotonic_only, include_artifacts, max_file_size_mb, }) => {
+        try {
+            const { steps, rows } = await computeSequenceTrends(paths, {
+                minGrowthCount: min_growth_count,
+                monotonicOnly: monotonic_only,
+                maxFileSizeMB: max_file_size_mb,
+                toolName: 'memlab_leak_report',
+            });
+            const n = steps.length;
+            const artifactRows = rows.filter(r => r.artifact != null);
+            const candidates = (include_artifacts ? rows : rows.filter(r => r.artifact == null)).slice(0, limit);
+            const heapNet = steps[n - 1].totalSize - steps[0].totalSize;
+            const lines = [
+                `## Leak report (${n} snapshots)`,
+                '',
+                `Heap self-size ${heapNet >= 0 ? 'grew' : 'shrank'} by ${formatBytes(Math.abs(heapNet))} across the ladder (${formatNumber(steps[0].nodeCount)} → ${formatNumber(steps[n - 1].nodeCount)} nodes).`,
+                '',
+            ];
+            if (n === 2) {
+                lines.push('> ⚠️ **Only 2 snapshots: "↑ every step" is monotonic by construction** and cannot separate a real trend from a single GC-band sample. Capture at least a third rung before treating anything here as a leak.', '');
+            }
+            if (candidates.length === 0) {
+                lines.push(`No non-artifact class grew by >= ${formatNumber(min_growth_count)} instances across the ladder — no unbounded-growth signal to report.`);
+                if (artifactRows.length > 0) {
+                    lines.push('', `> 🧹 ${formatNumber(artifactRows.length)} growing class(es) were known measurement artifacts (pass \`include_artifacts: true\` to see them).`);
+                }
+                return toolResult(lines.join('\n'));
+            }
+            // Evidence pass. The trend loop drops each graph before loading the
+            // next, so the final rung is re-opened here — one extra load, and the
+            // only way to ask retention questions about the classes the trend pass
+            // just identified.
+            const snapshot = await getFullHeapFromFile(steps[n - 1].localPath);
+            const devRoots = collectDevRoots(snapshot);
+            const reached = devRoots.byId.size > 0
+                ? computeReachableWithoutDevRoots(snapshot, devRoots)
+                : null;
+            const evidence = new Map();
+            for (const c of candidates) {
+                evidence.set(c.key, {
+                    total: 0,
+                    devOnly: 0,
+                    samples: [],
+                    example: null,
+                    exampleRetained: -1,
+                    anyExample: null,
+                });
+            }
+            snapshot.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                // Must key exactly as buildHistogram does, normalization included, or
+                // per-instance Context/scope classes never match their trend row.
+                const ev = evidence.get(`${node.type}::${normalizeClassName(node.name)}`);
+                if (!ev)
+                    return;
+                ev.total++;
+                if (reached != null && reached[node.nodeIndex] === 0)
+                    ev.devOnly++;
+                if (ev.anyExample == null)
+                    ev.anyExample = node;
+                if (!node.hasPathEdge)
+                    return;
+                if (ev.samples.length < MAX_SAMPLES_PER_CLASS)
+                    ev.samples.push(node);
+                if (node.retainedSize > ev.exampleRetained) {
+                    ev.exampleRetained = node.retainedSize;
+                    ev.example = node;
+                }
+            });
+            // The biggest traceable instance is the most informative one to walk, so
+            // put it at the head of every retainer sample.
+            for (const ev of evidence.values()) {
+                if (ev.example != null) {
+                    ev.samples = [
+                        ev.example,
+                        ...ev.samples.filter(s => s.id !== ev.example.id),
+                    ];
+                }
+            }
+            const perCycle = cycles != null && cycles > 0;
+            const showDevOnly = reached != null;
+            const headers = [
+                'Class',
+                'Type',
+                ...steps.map((_, i) => `#${i + 1}`),
+                'Δ count',
+                ...(perCycle ? ['Δ/cycle'] : []),
+                'Δ size',
+                ...(showDevOnly ? ['Dev-only'] : []),
+                'Top retainer',
+                'Verdict hint',
+            ];
+            const rightCols = new Set();
+            for (let i = 2; i < headers.length - 2; i++)
+                rightCols.add(i);
+            let leakCandidates = 0;
+            let devOnlyClasses = 0;
+            const tableRows = candidates.map(r => {
+                const ev = evidence.get(r.key);
+                const devShare = ev.total > 0 ? ev.devOnly / ev.total : 0;
+                const isDevOnly = showDevOnly && devShare >= DEV_ONLY_SHARE;
+                if (isDevOnly)
+                    devOnlyClasses++;
+                let verdict;
+                if (r.artifact != null) {
+                    verdict = artifactLabel(r.artifact);
+                }
+                else if (isDevOnly) {
+                    verdict = '🛠 dev/automation-retained (not production)';
+                }
+                else if (r.trend === 'monotonic-up') {
+                    verdict = '↑ every step — LEAK candidate';
+                    leakCandidates++;
+                }
+                else {
+                    verdict = 'grew net (noisy)';
+                }
+                const label = displayName(r);
+                return [
+                    label.length > 34 ? label.slice(0, 31) + '…' : label,
+                    r.type,
+                    ...r.counts.map(c => formatNumber(c)),
+                    `+${formatNumber(r.netCount)}`,
+                    ...(perCycle ? [(r.netCount / cycles).toFixed(2)] : []),
+                    `${r.netSize >= 0 ? '+' : ''}${formatBytes(r.netSize)}`,
+                    ...(showDevOnly
+                        ? [
+                            ev.total === 0
+                                ? '—'
+                                : ev.devOnly === 0
+                                    ? '—'
+                                    : `${(devShare * 100).toFixed(0)}%`,
+                        ]
+                        : []),
+                    (label => (label.length > 44 ? label.slice(0, 41) + '…' : label))(topRetainerLabel(ev)),
+                    verdict,
+                ];
+            });
+            lines.push(markdownTable(headers, tableRows, rightCols));
+            lines.push('', `**${formatNumber(leakCandidates)} leak candidate(s)** of ${formatNumber(candidates.length)} growing class(es) examined` +
+                (devOnlyClasses > 0
+                    ? `; ${formatNumber(devOnlyClasses)} ruled out as dev/automation-retained`
+                    : '') +
+                (artifactRows.length > 0 && !include_artifacts
+                    ? `; ${formatNumber(artifactRows.length)} known measurement artifact(s) not shown (\`include_artifacts: true\`)`
+                    : '') +
+                '.');
+            if (!showDevOnly) {
+                lines.push('', '_No dev/automation roots were found in the final snapshot, so the dev-only column is omitted — nothing here is being attributed to the inspector._');
+            }
+            // Point at the single next call for the strongest candidate rather than
+            // a menu: the failure mode this tool exists to fix is a plausible
+            // grower being reported without anyone tracing it.
+            const strongest = candidates.find(r => r.artifact == null &&
+                r.trend === 'monotonic-up' &&
+                evidence.get(r.key)?.example != null);
+            if (strongest) {
+                const ev = evidence.get(strongest.key);
+                const example = ev.example;
+                lines.push('', `**Next:** confirm the top candidate before reporting it — \`memlab_retainer_trace({node_id: ${example.id}})\` on the largest traceable \`${displayName(strongest)}\` instance in the final rung, then \`memlab_dominator_chain\` on whatever owns it. Counts alone cannot distinguish a leak from a cache that grew and will be evicted.`);
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=leak-report.js.map

package/dist/tools/leak-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leak-report.js","sourceRoot":"","sources":["../../src/tools/leak-report.ts"],"names":[],"mappings":"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"}

package/dist/tools/load-snapshot.d.ts

@@ -16,6 +16,24 @@ export declare const DEFAULT_MAX_EDGES = 24000000;
 export declare const WARN_NODE_COUNT = 2000000;
 export declare const NODES_PER_HEAP_MB = 1700;
 export declare const EDGES_PER_HEAP_MB = 6800;
+export declare const LOAD_BYTES_PER_NODE = 200;
+export declare const LOAD_BYTES_PER_EDGE = 40;
+export declare const HEADROOM_SAFETY_FRACTION = 0.8;
+/**
+ * Projected additional heap (MB) a full load of this graph will occupy.
+ * Light loads skip the dominator/retained-size arrays; the parsed graph still
+ * dominates, so the discount is modest and intentionally conservative.
+ */
+export declare function estimateLoadHeapMB(counts: {
+    nodeCount: number;
+    edgeCount: number;
+}, light: boolean): number;
+/**
+ * Old-space headroom (MB) left for a new load: the configured limit minus what
+ * is already committed. Returns null when the limit can't be read, in which case
+ * the caller skips the guard rather than guessing.
+ */
+export declare function getHeapHeadroomMB(): number | null;
 /**
  * Configured V8 old-space limit in MB (reflects --max-old-space-size). Returns 0
  * when it can't be read, so callers fall back to the fixed floors.

package/dist/tools/load-snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA4BvE,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAU3E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAmBjD,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,eAAe,UAAY,CAAC;AAazC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAoBA;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAgB/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GAC7C,MAAM,GAAG,IAAI,CASf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,mBAAmB,EAAE,OAAO,GAC3B,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAsEA;AAmCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAWhE;AAsGD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuV5D"}
+{"version":3,"file":"load-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAuCvE,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAU3E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAmBjD,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,eAAe,UAAY,CAAC;AAazC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAStC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAMtC,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,EAC9C,KAAK,EAAE,OAAO,GACb,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAUjD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAoBA;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAgB/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GAC7C,MAAM,GAAG,IAAI,CASf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,mBAAmB,EAAE,OAAO,GAC3B,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAsEA;AAmCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAWhE;AA4HD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmgB5D"}

package/dist/tools/load-snapshot.js

@@ -13,10 +13,16 @@ import path from 'path';
 import v8 from 'v8';
 import { execFileSync } from 'child_process';
 import { z } from 'zod';
+import memlabCore from '@memlab/core';
 import memlabHeapAnalysis from '@memlab/heap-analysis';
 const { getFullHeapFromFile } = memlabHeapAnalysis;
-import { setSnapshot, getSnapshotMetadata, setSessionConfig, listSnapshots, clearAllSnapshots, } from '../heap-state.js';
-import { formatBytes, formatNumber, truncateNodeName, errorResult, textResult, } from '../utils.js';
+// `getFullHeapFromFile` = parse + `analysis.preparePathFinder`. Light mode calls
+// only the parse half, so the two pieces are reached directly here. Measured on
+// a 380 MB / 4.19M-node browser snapshot: parse 7.9s, preparePathFinder 9.9s.
+const { utils: memlabUtils } = memlabCore;
+import { setSnapshot, getSnapshotMetadata, setSessionConfig, listSnapshots, clearAllSnapshots, evictLeastRecentlyUsed, findResidentByPath, retainOnlySnapshot, setCurrentSnapshot, } from '../heap-state.js';
+import { makeProgressReporter } from '../progress.js';
+import { formatBytes, formatNumber, truncateNodeName, errorResult, textResult, suggestionsSuppressed, } from '../utils.js';
 // The bucket the Nest auto-capture + the Manifold links in diffs use, so a
 // bare snapshot filename resolves predictably (Feedback §7).
 export const DEFAULT_MANIFOLD_BUCKET = 'nest_server_nodejs_heap_snapshots';
@@ -63,6 +69,48 @@ export const WARN_NODE_COUNT = 2_000_000;
 // 45–49M-edge band, still rejects the 89M-edge / 2 GB band).
 export const NODES_PER_HEAP_MB = 1700;
 export const EDGES_PER_HEAP_MB = 6800;
+// Per-node / per-edge working-set estimate for a full load, fitted to a
+// measured browser capture: 4,185,734 nodes + 18,755,739 edges peaked at
+// ~1,500 MB RSS (200 B/node + 40 B/edge predicts ~1,588 MB). Deliberately a
+// slight OVER-estimate — the failure this guards against is an OOM that kills
+// every resident snapshot, so erring toward "not enough headroom" is the cheap
+// direction to be wrong in. File size is not used: it correlates poorly with
+// graph cost, which is why the node/edge ceilings exist at all.
+export const LOAD_BYTES_PER_NODE = 200;
+export const LOAD_BYTES_PER_EDGE = 40;
+// Fraction of remaining old-space a single load may be projected to consume
+// before the guard fires. Well below 1.0 because the estimate is approximate,
+// the parse allocates in bursts the GC cannot always keep up with, and analysis
+// after the load needs room of its own.
+export const HEADROOM_SAFETY_FRACTION = 0.8;
+/**
+ * Projected additional heap (MB) a full load of this graph will occupy.
+ * Light loads skip the dominator/retained-size arrays; the parsed graph still
+ * dominates, so the discount is modest and intentionally conservative.
+ */
+export function estimateLoadHeapMB(counts, light) {
+    const bytes = counts.nodeCount * LOAD_BYTES_PER_NODE +
+        counts.edgeCount * LOAD_BYTES_PER_EDGE;
+    return Math.round((bytes / (1024 * 1024)) * (light ? 0.85 : 1));
+}
+/**
+ * Old-space headroom (MB) left for a new load: the configured limit minus what
+ * is already committed. Returns null when the limit can't be read, in which case
+ * the caller skips the guard rather than guessing.
+ */
+export function getHeapHeadroomMB() {
+    try {
+        const s = v8.getHeapStatistics();
+        const limit = s.heap_size_limit / (1024 * 1024);
+        const used = s.used_heap_size / (1024 * 1024);
+        if (!Number.isFinite(limit) || limit <= 0)
+            return null;
+        return Math.max(0, Math.round(limit - used));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Configured V8 old-space limit in MB (reflects --max-old-space-size). Returns 0
  * when it can't be read, so callers fall back to the fixed floors.
@@ -285,7 +333,7 @@ function detectEnv(snapshot) {
         return 'node';
     return 'unknown';
 }
-function quickDiagnosis(snapshot, totalSelfSize) {
+function quickDiagnosis(snapshot, totalSelfSize, light = false) {
     const warnings = [];
     const largeStrings = [];
     const stringCounts = new Map();
@@ -322,7 +370,10 @@ function quickDiagnosis(snapshot, totalSelfSize) {
         const display = val.length > 40 ? val.slice(0, 40) + '…' : val;
         warnings.push(`⚠ "${display}" duplicated ${formatNumber(count)} times`);
     }
-    const largest = findLargestObject(snapshot);
+    // Skipped on a light load: `findLargestObject` ranks by retainedSize, which
+    // is uncomputed there — every candidate would read 0 and the "retains N% of
+    // heap" line would be fiction.
+    const largest = light ? null : findLargestObject(snapshot);
     if (largest && totalSelfSize > 0) {
         const pct = ((largest.size / totalSelfSize) * 100).toFixed(0);
         if (largest.size >= totalSelfSize * 0.3) {
@@ -336,11 +387,32 @@ function quickDiagnosis(snapshot, totalSelfSize) {
     for (const [name, count] of anomalous) {
         warnings.push(`⚠ ${formatNumber(count)}× \`${name}\` instances`);
     }
-    if (warnings.length > 0) {
-        warnings.push('', 'Run `memlab_quick_diagnosis` for actionable triage or `memlab_auto_investigate` for deep analysis.');
-    }
     return warnings;
 }
+/**
+ * What to call next, indexed by the QUESTION rather than by tool.
+ *
+ * The old trailer always pointed at `quick_diagnosis` / `auto_investigate`
+ * regardless of why the snapshot was loaded, which is right for "I don't know
+ * what I'm looking at" and wrong for every other case. Measured effect of the
+ * generic version: over one long investigation 28 of the server's tools were
+ * used and the rest never were, including several that answer a stated question
+ * in a single call. Naming the question is what makes the right tool findable
+ * at the only moment the caller is guaranteed to be reading.
+ */
+function nextStepMenu() {
+    return [
+        '**What do you want to know?**',
+        '- _What is this heap made of?_ → `memlab_app_heap` (application data vs bundle source vs V8 machinery — run it before trusting any percentage)',
+        '- _Anything obviously wrong?_ → `memlab_quick_diagnosis`, then `memlab_auto_investigate` for the deep dive',
+        '- _Is X a leak?_ → `memlab_hypothesis`',
+        '- _Who owns the growth?_ → `memlab_explain_delta` (needs a baseline loaded with `keep_previous:true`)',
+        '- _What grew across the ladder?_ → `memlab_leak_report` / `memlab_sequence_analysis`',
+        '- _What does this object pin?_ → `memlab_dominator_chain`, then `memlab_dominator_attribution`',
+        '- _Is it real or an artifact?_ → `memlab_dev_artifacts` (and `memlab_explain_delta` for JIT warmup, which it does not count)',
+        '- _Something else_ → `memlab_tools` lists every tool grouped by the question it answers',
+    ];
+}
 export function registerLoadSnapshot(server) {
     server.tool('memlab_load_snapshot', 'Load and parse a .heapsnapshot file. This builds indexes, computes the dominator tree, and calculates retained sizes. Returns a quick diagnosis highlighting potential issues. Accepts a local absolute path, a manifold:// URL, or a bare snapshot filename (resolved against the nest_server_nodejs_heap_snapshots bucket and fetched automatically). Multiple snapshots can be kept resident — pass keep_previous:true to load several for diffing/comparison; switch between them with memlab_snapshots. Cost note: the load working set is several× the file size and the dominator pass runs uninterruptibly, so large/deep snapshots are memory- and time-heavy — run the server with NODE_OPTIONS="--max-old-space-size=8192", load one snapshot at a time (omit keep_previous) on large heaps, and prefer memlab_sequence_analysis (transient per-snapshot loads) when you only need trend/growth across a ladder. A node/edge-count ceiling (max_nodes/max_edges) refuses pathologically large loads before they wedge the server; the ceiling auto-scales from the server\'s configured --max-old-space-size (an 8 GB server admits the ~1.1 GB / ~14M-node / ~55M-edge Nest tier by default), and force:true self-sizes from the header counts so a one-off oversized load needs no manual max_nodes/max_edges.', {
         file_path: z
@@ -378,8 +450,24 @@ export function registerLoadSnapshot(server) {
         force: z
             .boolean()
             .optional()
-            .describe('Bypass the node/edge-count ceiling and attempt the load anyway (default false). force:true is self-sizing — it uses the header-peeked counts, so you do NOT also need to pass max_nodes/max_edges. The load cannot be interrupted once started, so only use this when you accept a potentially very long load or possible OOM.'),
-    }, async ({ file_path, alias, keep_previous, quiet, suppress_suggestions, max_file_size_mb, max_nodes, max_edges, force, }) => {
+            .describe('Bypass the node/edge-count ceiling AND the memory-headroom guard, and attempt the load anyway (default false). force:true is self-sizing — it uses the header-peeked counts, so you do NOT also need to pass max_nodes/max_edges. The load cannot be interrupted once started, so only use this when you accept a potentially very long load or possible OOM.'),
+        force_reload: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Re-parse even if this exact file is already resident in this server process (default false: an already-loaded file is switched to instead, reported as `cache: hit`). Only needed if the file changed on disk since it was loaded.'),
+        light: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Count-only load: parse the graph but SKIP the dominator / retained-size / shortest-path pass (default false). Roughly halves load time (measured on a 380 MB / 4.19M-node capture: 18s → 8s) for questions that only need counts, names, types, self sizes or string values. The saving is time, not memory — the parsed graph is the bulk of the working set. A light snapshot REFUSES any tool that needs retained sizes, dominators or retainer paths (memlab_retainer_trace, memlab_detached_dom, memlab_largest_objects, memlab_dominator_*, …) instead of silently reporting zeros; reload without light to run those. Light-safe: memlab_class_histogram (include_retained_size:false), memlab_search_nodes, memlab_search_strings, memlab_string_patterns, memlab_snapshot_summary, memlab_snapshot_header, memlab_snapshots.'),
+    }, async ({ file_path, alias, keep_previous, quiet, suppress_suggestions, max_file_size_mb, max_nodes, max_edges, force, force_reload, light, }, extra) => {
+        // 6 phases: resolve → guards → parse → (dominators | skipped) → index →
+        // diagnose. Reported at boundaries only; see progress.ts for why there is
+        // nothing finer-grained available.
+        const progress = makeProgressReporter(extra, 'load_snapshot');
+        const PHASES = 6;
+        const startedAt = Date.now();
         try {
             if (quiet != null || suppress_suggestions != null) {
                 setSessionConfig({
@@ -390,6 +478,7 @@ export function registerLoadSnapshot(server) {
                 });
             }
             const previousMeta = getSnapshotMetadata();
+            progress.phase(1, PHASES, `resolving ${file_path} (a manifold:// or bare filename is fetched here)`);
             let resolved;
             let fetchedFrom = null;
             try {
@@ -403,6 +492,43 @@ export function registerLoadSnapshot(server) {
                     `Ensure the 'manifold' CLI is installed and you have access to the bucket, ` +
                     `or pass a local absolute path instead.`));
             }
+            // In-process snapshot cache. Re-parsing a file this process already
+            // holds is the single most expensive avoidable thing the server does —
+            // a measured 18.8s for a 380 MB capture — and a long investigation
+            // re-loads the same file repeatedly. A hit switches to the resident
+            // graph instead. It must be indistinguishable from a real load apart
+            // from speed, so replace-mode (`keep_previous:false`) still unloads the
+            // others, exactly as a re-parse would have.
+            //
+            // A resident LIGHT snapshot does NOT satisfy a full request: it has no
+            // dominator tree, so serving it would silently answer a retention
+            // question with zeros. The reverse is fine — a full graph satisfies a
+            // light request.
+            if (!force_reload) {
+                const resident = findResidentByPath(resolved);
+                if (resident != null && (!resident.light || light)) {
+                    if (keep_previous) {
+                        setCurrentSnapshot(resident.handle);
+                    }
+                    else {
+                        retainOnlySnapshot(resident.handle);
+                    }
+                    const headroomHitMB = getHeapHeadroomMB();
+                    return textResult([
+                        `cache: **hit** — ${resident.fileName} was already parsed in this server process; switched to it in ${Date.now() - startedAt} ms instead of re-parsing [handle: ${resident.handle}]`,
+                        `${formatNumber(resident.nodeCount)} nodes, ${formatNumber(resident.edgeCount)} edges, ${formatBytes(resident.totalSize)} heap size` +
+                            (resident.light
+                                ? ' (LIGHT — no dominator tree / retained sizes)'
+                                : ''),
+                        headroomHitMB != null
+                            ? `Memory: ~${formatNumber(headroomHitMB)} MB of the ~${formatNumber(getOldSpaceLimitMB())} MB old-space limit free (unchanged — nothing was parsed).`
+                            : '',
+                        '_Pass `force_reload: true` if the file changed on disk since it was loaded._',
+                    ]
+                        .filter(Boolean)
+                        .join('\n'));
+                }
+            }
             if (!fs.existsSync(resolved)) {
                 return errorResult(new Error(`File not found: ${resolved}` +
                     (file_path.includes('/')
@@ -491,8 +617,8 @@ export function registerLoadSnapshot(server) {
                 const countStr = counts
                     ? `${formatNumber(counts.nodeCount)} nodes / ${formatNumber(counts.edgeCount)} edges, `
                     : '';
-                process.stderr.write(`Loading ${formatBytes(fileStat.size)} snapshot (${countStr}parsing → dominators → retained sizes). ` +
-                    `This runs uninterruptibly and can take minutes on a large/deep heap; if it appears to hang it is the dominator pass, not a crash.\n`);
+                process.stderr.write(`Loading ${formatBytes(fileStat.size)} snapshot (${countStr}parsing${light ? '' : ' → dominators → retained sizes'}). ` +
+                    `This runs uninterruptibly and can take minutes on a large/deep heap; if it appears to hang it is the ${light ? 'parse' : 'dominator pass'}, not a crash.\n`);
             }
             // Free any resident snapshot BEFORE parsing the next so peak memory is
             // one heap, not two — the double-residency that tips a large load into
@@ -501,9 +627,61 @@ export function registerLoadSnapshot(server) {
             if (!keep_previous) {
                 clearAllSnapshots();
             }
+            // Memory-headroom guard. The count ceiling above bounds the graph in the
+            // ABSTRACT; this bounds it against what this process actually has left,
+            // which is a different question once other snapshots are resident. When
+            // the projection does not fit, evict cold snapshots (never the current
+            // one) before refusing — an OOM here kills every resident snapshot and
+            // the whole session's state, so shedding the coldest is strictly better.
+            const evicted = [];
+            let headroomMB = getHeapHeadroomMB();
+            let estimateMB = null;
+            if (counts != null && headroomMB != null) {
+                estimateMB = estimateLoadHeapMB(counts, light);
+                while (estimateMB > (headroomMB ?? 0) * HEADROOM_SAFETY_FRACTION &&
+                    !force) {
+                    const victim = evictLeastRecentlyUsed();
+                    if (victim == null)
+                        break;
+                    evicted.push(victim.handle);
+                    headroomMB = getHeapHeadroomMB();
+                }
+                if (!force &&
+                    estimateMB > (headroomMB ?? 0) * HEADROOM_SAFETY_FRACTION) {
+                    const heapMB = getOldSpaceLimitMB();
+                    return errorResult(new Error(`Not enough memory headroom to load this snapshot: it projects to ~${formatNumber(estimateMB)} MB ` +
+                        `(${formatNumber(counts.nodeCount)} nodes × ${LOAD_BYTES_PER_NODE} B + ${formatNumber(counts.edgeCount)} edges × ${LOAD_BYTES_PER_EDGE} B), ` +
+                        `over the ~${formatNumber(Math.round((headroomMB ?? 0) * HEADROOM_SAFETY_FRACTION))} MB budget for one load ` +
+                        `(${Math.round(HEADROOM_SAFETY_FRACTION * 100)}% of the ~${formatNumber(headroomMB ?? 0)} MB free of this server's ~${formatNumber(heapMB)} MB old-space limit; the rest is reserved because the estimate is approximate and the parse allocates in bursts)` +
+                        (evicted.length > 0
+                            ? ` (after unloading ${evicted.length} cold snapshot(s): ${evicted.join(', ')})`
+                            : '') +
+                        `.\n\nAn out-of-memory crash here would take every resident snapshot and all session state with it, so the load is refused instead.\n\nOptions:\n` +
+                        `1. Unload snapshots you no longer need: memlab_snapshots({action: "unload", handle: "…"}).\n` +
+                        `2. Load light — skips the dominator/retained-size pass: memlab_load_snapshot({file_path: "${file_path}", light: true}).\n` +
+                        `3. Use a smaller/earlier snapshot, or memlab_sequence_analysis for trend questions (it holds one graph at a time).\n` +
+                        `4. Restart the server with more memory: NODE_OPTIONS="--max-old-space-size=8192".\n` +
+                        `5. Override this projection with force:true (accepts the OOM risk).`));
+                }
+            }
+            progress.phase(2, PHASES, `guards passed${estimateMB != null ? ` (projected ~${formatNumber(estimateMB)} MB, ~${formatNumber(headroomMB ?? 0)} MB free)` : ''}${evicted.length > 0 ? `, evicted ${evicted.join(', ')}` : ''}`);
+            progress.phase(3, PHASES, `parsing ${formatBytes(fileStat.size)} — this phase is synchronous and emits no further updates until it completes`);
             let snapshot;
             try {
-                snapshot = await getFullHeapFromFile(resolved);
+                if (light) {
+                    // Parse only. `preparePathFinder` (shortest paths + dominators +
+                    // retained sizes + Fiber marking) is the half being skipped, and it
+                    // is the expensive half.
+                    snapshot = await memlabUtils.getSnapshotFromFile(resolved, {
+                        buildNodeIdIndex: true,
+                        verbose: false,
+                    });
+                    progress.phase(4, PHASES, 'parsed; dominator/retained-size pass SKIPPED (light mode)');
+                }
+                else {
+                    snapshot = await getFullHeapFromFile(resolved);
+                    progress.phase(4, PHASES, 'parsed; dominator tree and retained sizes computed');
+                }
             }
             catch (loadErr) {
                 const msg = loadErr instanceof Error ? loadErr.message : String(loadErr);
@@ -525,6 +703,7 @@ export function registerLoadSnapshot(server) {
                 }
                 throw loadErr;
             }
+            progress.phase(5, PHASES, 'indexing nodes and edges');
             let nodeCount = 0;
             let edgeCount = 0;
             let totalSize = 0;
@@ -543,6 +722,7 @@ export function registerLoadSnapshot(server) {
                 edgeCount,
                 totalSize,
                 env,
+                light,
             }, { alias, replace: !keep_previous });
             const envLabel = env === 'browser'
                 ? 'Browser'
@@ -556,7 +736,21 @@ export function registerLoadSnapshot(server) {
             if (fetchedFrom) {
                 lines.push(`Fetched from Manifold: ${fetchedFrom}`);
             }
+            if (evicted.length > 0) {
+                lines.push(`⚠ Unloaded ${evicted.length} cold snapshot(s) to make room: ${evicted.join(', ')}`);
+            }
             lines.push(`Loaded ${fileName} (${formatBytes(fileStat.size)} on disk): ${formatNumber(nodeCount)} nodes, ${formatNumber(edgeCount)} edges, ${formatBytes(totalSize)} heap size (${envLabel} snapshot) [handle: ${meta.handle}]`);
+            if (light) {
+                lines.push('⚡ **LIGHT mode** — dominator tree, retained sizes and retainer paths were NOT computed. Counts, names, types, self sizes and string values are available; tools needing retention data will refuse rather than report zeros. Reload without `light` for those.');
+            }
+            // Report headroom on every load, not just when the guard fires: the
+            // number a caller needs in order to decide whether to keep_previous the
+            // NEXT one is what is left after this load, and nothing else surfaces it.
+            const headroomAfterMB = getHeapHeadroomMB();
+            if (headroomAfterMB != null) {
+                const limitMB = getOldSpaceLimitMB();
+                lines.push(`Memory: ~${formatNumber(headroomAfterMB)} MB of the ~${formatNumber(limitMB)} MB old-space limit still free after this load.`);
+            }
             const captured = extractCaptureTime(fileName);
             if (captured) {
                 const iso = captured.toISOString().slice(0, 10);
@@ -574,10 +768,14 @@ export function registerLoadSnapshot(server) {
                         .join(', ')}. Switch with memlab_snapshots.`);
                 }
             }
-            const warnings = quickDiagnosis(snapshot, totalSize);
+            progress.phase(6, PHASES, 'running quick diagnosis');
+            const warnings = quickDiagnosis(snapshot, totalSize, light);
             if (warnings.length > 0) {
                 lines.push('', ...warnings);
             }
+            if (!suggestionsSuppressed()) {
+                lines.push('', ...nextStepMenu());
+            }
             return textResult(lines.join('\n'));
         }
         catch (err) {