@memlab/mcp-server 2.52.0 → 2.86.0

package/dist/react-shapes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+/**
+ * Recognising React structures in a heap snapshot.
+ *
+ * Fibers, hooks, update queues and update records are ALL plain `Object` in a
+ * production bundle, so every class-name-based heuristic walks straight past
+ * them. On one population `helpers.owner()` returned `(none)` for 100% of
+ * 1,645 records for exactly this reason, and the useful answer —
+ * `BaseTooltipSimple` — needed a hand-written walk to the fiber plus a read of
+ * `elementType`.
+ *
+ * That walk has now been hand-written for four findings of the same family
+ * across this workstream. The `elementType` / `stateNode` / `memoizedProps`
+ * layout is stable across every React version Meta ships, so it belongs here
+ * rather than in each investigation.
+ */
+import type { IHeapNode } from '@memlab/core';
+/** Property set of a React update record — the eager-bailout leak family. */
+export declare const UPDATE_RECORD_FIELDS: string[];
+/** Does this node look like a React fiber? */
+export declare function isFiberNode(node: IHeapNode): boolean;
+/** Does this node look like a React update record (`queue.pending` member)? */
+export declare function isUpdateRecord(node: IHeapNode): boolean;
+/**
+ * The component name behind a fiber.
+ *
+ * Three shapes, in the order they occur: `elementType` is a closure (function
+ * component — the closure's own name is the component name), or a string (host
+ * element), or an object carrying `render` / `type` (memo, forwardRef, lazy),
+ * in which case the name is one level deeper.
+ */
+export declare function fiberComponentName(fiber: IHeapNode): string | null;
+export declare function nearestFiber(node: IHeapNode, maxHops: number): IHeapNode | null;
+//# sourceMappingURL=react-shapes.d.ts.map

package/dist/react-shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-shapes.d.ts","sourceRoot":"","sources":["../src/react-shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAe5C,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,UAMhC,CAAC;AAYF,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAOpD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAWvD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAOlE;AAyCD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAsBlB"}

package/dist/react-shapes.js

@@ -0,0 +1,149 @@
+/**
+ * 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
+ */
+/**
+ * Fields that only a fiber carries. `stateNode` alone is too weak (a class
+ * instance has one), so a match needs `elementType` or `memoizedProps`, which
+ * together with `return`/`child` are fiber-specific.
+ */
+const FIBER_STRONG_FIELDS = ['elementType', 'memoizedProps', 'pendingProps'];
+const FIBER_SUPPORTING_FIELDS = [
+    'return',
+    'child',
+    'stateNode',
+    'memoizedState',
+];
+/** Property set of a React update record — the eager-bailout leak family. */
+export const UPDATE_RECORD_FIELDS = [
+    'action',
+    'eagerState',
+    'hasEagerState',
+    'lane',
+    'next',
+];
+/** Own property names of a node, as a Set. Cheap; used by every check here. */
+function propertyNames(node) {
+    const names = new Set();
+    for (const edge of node.references) {
+        if (edge.type !== 'property')
+            continue;
+        names.add(String(edge.name_or_index));
+    }
+    return names;
+}
+/** Does this node look like a React fiber? */
+export function isFiberNode(node) {
+    if (node.type !== 'object')
+        return false;
+    const names = propertyNames(node);
+    const strong = FIBER_STRONG_FIELDS.filter(f => names.has(f)).length;
+    if (strong === 0)
+        return false;
+    const supporting = FIBER_SUPPORTING_FIELDS.filter(f => names.has(f)).length;
+    return strong + supporting >= 3;
+}
+/** Does this node look like a React update record (`queue.pending` member)? */
+export function isUpdateRecord(node) {
+    if (node.type !== 'object')
+        return false;
+    const names = propertyNames(node);
+    // `eagerState` may be absent when the update never took the eager path, so
+    // require the rest and treat it as optional.
+    return (names.has('action') &&
+        names.has('lane') &&
+        names.has('next') &&
+        (names.has('hasEagerState') || names.has('eagerState')));
+}
+/**
+ * The component name behind a fiber.
+ *
+ * Three shapes, in the order they occur: `elementType` is a closure (function
+ * component — the closure's own name is the component name), or a string (host
+ * element), or an object carrying `render` / `type` (memo, forwardRef, lazy),
+ * in which case the name is one level deeper.
+ */
+export function fiberComponentName(fiber) {
+    for (const edge of fiber.references) {
+        if (edge.type !== 'property')
+            continue;
+        if (String(edge.name_or_index) !== 'elementType')
+            continue;
+        return elementTypeName(edge.toNode, 0);
+    }
+    return null;
+}
+function elementTypeName(node, depth) {
+    if (depth > 2)
+        return null;
+    if (node.type === 'string' || node.type === 'concatenated string') {
+        const value = node.toStringNode()?.stringValue ?? node.name;
+        return value ? `<${value}>` : null;
+    }
+    if (node.type === 'closure') {
+        // A minified bundle still names the closure after the component in the
+        // overwhelming majority of cases; an empty name is worth reporting as
+        // unknown rather than as "".
+        return node.name && node.name !== 'function' ? node.name : null;
+    }
+    // memo / forwardRef / lazy wrappers.
+    for (const edge of node.references) {
+        if (edge.type !== 'property')
+            continue;
+        const name = String(edge.name_or_index);
+        if (name !== 'render' && name !== 'type')
+            continue;
+        const inner = elementTypeName(edge.toNode, depth + 1);
+        if (inner != null)
+            return inner;
+    }
+    return null;
+}
+/**
+ * Walk up from a hook/queue/record to the fiber that owns it.
+ *
+ * Prefers the edges that actually lead there — a hook's owner is reached via
+ * `memoizedState` / `next` / `queue` / `baseQueue`, not by whatever referrer
+ * happens to come first — and falls back to any referrer so a slightly
+ * different shape still resolves.
+ */
+const OWNER_EDGE_PREFERENCE = [
+    'memoizedState',
+    'queue',
+    'baseQueue',
+    'next',
+    'return',
+];
+export function nearestFiber(node, maxHops) {
+    let current = node;
+    const seen = new Set([node.id]);
+    for (let hop = 0; hop < maxHops; hop++) {
+        if (isFiberNode(current))
+            return current;
+        let chosen = null;
+        let fallback = null;
+        for (const edge of current.referrers) {
+            const from = edge.fromNode;
+            if (from.id <= 3 || seen.has(from.id))
+                continue;
+            if (OWNER_EDGE_PREFERENCE.includes(String(edge.name_or_index))) {
+                chosen = from;
+                break;
+            }
+            if (fallback == null)
+                fallback = from;
+        }
+        const next = chosen ?? fallback;
+        if (next == null)
+            return null;
+        seen.add(next.id);
+        current = next;
+    }
+    return null;
+}
+//# sourceMappingURL=react-shapes.js.map

package/dist/react-shapes.js.map

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

package/dist/server-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+/**
+ * The version this server reports about itself.
+ *
+ * Kept in its own module so `memlab_server_status` can report it without
+ * importing `index.ts` (which would be an import cycle — index imports every
+ * tool). Keep in sync with `package.json`; `scripts/check-version-sync.mjs`
+ * enforces that.
+ */
+export declare const SERVER_VERSION = "2.86.0";
+//# sourceMappingURL=server-version.d.ts.map

package/dist/server-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-version.d.ts","sourceRoot":"","sources":["../src/server-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC"}

package/dist/server-version.js

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+/**
+ * The version this server reports about itself.
+ *
+ * Kept in its own module so `memlab_server_status` can report it without
+ * importing `index.ts` (which would be an import cycle — index imports every
+ * tool). Keep in sync with `package.json`; `scripts/check-version-sync.mjs`
+ * enforces that.
+ */
+export const SERVER_VERSION = '2.86.0';
+//# sourceMappingURL=server-version.js.map

package/dist/server-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-version.js","sourceRoot":"","sources":["../src/server-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC"}

package/dist/snapshot-borrow.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { IHeapSnapshot } from '@memlab/core';
+/**
+ * Run `fn` against the snapshot at `localPath`, loading it only if it is not
+ * already resident, and leaving the session exactly as it was found.
+ *
+ * Every tool that walks an ORDERED ladder needs this, and each one getting it
+ * subtly wrong is the failure mode worth designing out. Three invariants:
+ *
+ *  - **Reuse a resident graph.** Re-parsing a 250 MB capture that is already in
+ *    memory is the single most expensive avoidable thing these tools do.
+ *  - **Hold one graph at a time.** `memlab_eval_across` needs every rung
+ *    resident simultaneously, which is precisely why it cannot serve a ladder of
+ *    large captures. Loading and dropping keeps peak RSS at one rung.
+ *  - **Restore the caller's active snapshot.** A ladder walk is a measurement,
+ *    not a navigation; silently leaving the session pointed at rung 6 makes the
+ *    caller's next `memlab_eval` answer a question about the wrong capture, and
+ *    nothing in that output says so.
+ */
+export declare function withSnapshotAt<T>(localPath: string, fn: (snapshot: IHeapSnapshot) => Promise<T> | T): Promise<T>;
+export interface ResolvedRung {
+    /** The path as the caller wrote it, used in report rows. */
+    label: string;
+    localPath: string;
+    sizeMB: number;
+}
+/**
+ * Resolve every path and check its size BEFORE anything is loaded.
+ *
+ * Ordering matters here: an unreadable or oversized rung five should fail in a
+ * second, not after four multi-minute loads have already been paid for.
+ */
+export declare function resolveRungs(paths: string[], maxFileSizeMB?: number): {
+    rungs: ResolvedRung[];
+    largestMB: number;
+};
+/**
+ * A full-heap walk on a multi-million-node graph does not finish inside the
+ * 60 s eval default, and every caller discovering that by timing out first is
+ * pure friction. Scale from the largest rung.
+ */
+export declare function scaledTimeoutMs(largestMB: number, explicit?: number): number;
+/**
+ * Re-arm the whole-heap scan guardrail for the work about to be done.
+ *
+ * Scaling a tool's own `timeout_ms` is NOT enough on its own, which is only
+ * obvious once you run against a big graph. The guardrail in `guardrail.ts`
+ * arms a 90s scan budget from the tool's incoming params before the handler
+ * runs; a tool that then computes a larger per-snapshot timeout is still inside
+ * that 90s budget, so a full-heap walk dies at 90s no matter what it asked for.
+ * Measured on a real 690 MB / 5.1M-node Ads Manager capture: a detached-node
+ * probe raised its eval timeout to 414s and still lost the rung to
+ * `Scan exceeded its 90000ms budget`.
+ *
+ * Re-arming per snapshot is what `memlab_analyze_run` already does for its
+ * steps. The guardrail's own `finally` disarms afterwards, so nothing leaks.
+ */
+export declare function armScanBudgetFor(timeoutMs: number): void;
+//# sourceMappingURL=snapshot-borrow.d.ts.map

package/dist/snapshot-borrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-borrow.d.ts","sourceRoot":"","sources":["../src/snapshot-borrow.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAkBhD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CA+BZ;AAED,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,GACrB;IAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAoB5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAExD"}

package/dist/snapshot-borrow.js

@@ -0,0 +1,113 @@
+/**
+ * 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 fs from 'fs';
+import memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { findResidentByPath, getCurrentHandle, getSnapshotByHandle, removeSnapshot, setCurrentSnapshot, setSnapshot, } from './heap-state.js';
+import { beginAnalysisBudget } from './analysis-budget.js';
+import { resolveMaxFileSizeMB, resolveSnapshotPath, } from './tools/load-snapshot.js';
+/**
+ * Run `fn` against the snapshot at `localPath`, loading it only if it is not
+ * already resident, and leaving the session exactly as it was found.
+ *
+ * Every tool that walks an ORDERED ladder needs this, and each one getting it
+ * subtly wrong is the failure mode worth designing out. Three invariants:
+ *
+ *  - **Reuse a resident graph.** Re-parsing a 250 MB capture that is already in
+ *    memory is the single most expensive avoidable thing these tools do.
+ *  - **Hold one graph at a time.** `memlab_eval_across` needs every rung
+ *    resident simultaneously, which is precisely why it cannot serve a ladder of
+ *    large captures. Loading and dropping keeps peak RSS at one rung.
+ *  - **Restore the caller's active snapshot.** A ladder walk is a measurement,
+ *    not a navigation; silently leaving the session pointed at rung 6 makes the
+ *    caller's next `memlab_eval` answer a question about the wrong capture, and
+ *    nothing in that output says so.
+ */
+export async function withSnapshotAt(localPath, fn) {
+    const resident = findResidentByPath(localPath);
+    let snapshot = resident != null ? getSnapshotByHandle(resident.handle) : null;
+    const previousHandle = getCurrentHandle();
+    let temporaryHandle = null;
+    try {
+        if (snapshot == null) {
+            snapshot = await getFullHeapFromFile(localPath);
+            const meta = setSnapshot(snapshot, localPath, {
+                fileName: localPath.replace(/^.*\//, ''),
+                nodeCount: snapshot.nodes?.length ?? 0,
+                edgeCount: snapshot.edges?.length ?? 0,
+                totalSize: 0,
+                env: 'unknown',
+            }, { replace: false });
+            temporaryHandle = meta.handle;
+        }
+        else if (resident != null) {
+            setCurrentSnapshot(resident.handle);
+        }
+        return await fn(snapshot);
+    }
+    finally {
+        if (temporaryHandle != null)
+            removeSnapshot(temporaryHandle);
+        if (previousHandle != null)
+            setCurrentSnapshot(previousHandle);
+    }
+}
+/**
+ * Resolve every path and check its size BEFORE anything is loaded.
+ *
+ * Ordering matters here: an unreadable or oversized rung five should fail in a
+ * second, not after four multi-minute loads have already been paid for.
+ */
+export function resolveRungs(paths, maxFileSizeMB) {
+    const rungs = [];
+    let largestMB = 0;
+    for (const p of paths) {
+        const { localPath, fetchedFrom } = resolveSnapshotPath(p);
+        if (!fs.existsSync(localPath)) {
+            throw new Error(`File not found: ${localPath}`);
+        }
+        const sizeMB = fs.statSync(localPath).size / (1024 * 1024);
+        largestMB = Math.max(largestMB, sizeMB);
+        const limit = resolveMaxFileSizeMB(maxFileSizeMB, fetchedFrom != null);
+        if (sizeMB > limit) {
+            throw new Error(`${p} is ${sizeMB.toFixed(0)} MB — exceeds the ${limit} MB per-file ` +
+                'limit. Raise it with max_file_size_mb.');
+        }
+        rungs.push({ label: p.replace(/^.*\//, ''), localPath, sizeMB });
+    }
+    return { rungs, largestMB };
+}
+/**
+ * A full-heap walk on a multi-million-node graph does not finish inside the
+ * 60 s eval default, and every caller discovering that by timing out first is
+ * pure friction. Scale from the largest rung.
+ */
+export function scaledTimeoutMs(largestMB, explicit) {
+    return explicit ?? Math.max(60000, Math.ceil(largestMB * 600));
+}
+/**
+ * Re-arm the whole-heap scan guardrail for the work about to be done.
+ *
+ * Scaling a tool's own `timeout_ms` is NOT enough on its own, which is only
+ * obvious once you run against a big graph. The guardrail in `guardrail.ts`
+ * arms a 90s scan budget from the tool's incoming params before the handler
+ * runs; a tool that then computes a larger per-snapshot timeout is still inside
+ * that 90s budget, so a full-heap walk dies at 90s no matter what it asked for.
+ * Measured on a real 690 MB / 5.1M-node Ads Manager capture: a detached-node
+ * probe raised its eval timeout to 414s and still lost the rung to
+ * `Scan exceeded its 90000ms budget`.
+ *
+ * Re-arming per snapshot is what `memlab_analyze_run` already does for its
+ * steps. The guardrail's own `finally` disarms afterwards, so nothing leaks.
+ */
+export function armScanBudgetFor(timeoutMs) {
+    beginAnalysisBudget(timeoutMs);
+}
+//# sourceMappingURL=snapshot-borrow.js.map

package/dist/snapshot-borrow.js.map

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

package/dist/string-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string-index.d.ts","sourceRoot":"","sources":["../src/string-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAG3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;CACzC,GACL,WAAW,CAoDb;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}
+{"version":3,"file":"string-index.d.ts","sourceRoot":"","sources":["../src/string-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAG3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;CACzC,GACL,WAAW,CA8Db;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}

package/dist/string-index.js

@@ -33,6 +33,14 @@ export function buildStringIndex(snapshot, opts = {}) {
     const scratch = getEvalScratch();
     const cached = scratch[CACHE_KEY];
     const wantDevOnly = opts.withDevOnly === true;
+    // `withDevOnly` without an `isDevOnlyNode` is a programmer error, not a
+    // degraded mode: without the predicate the pass cannot run, so the index
+    // would be built with `hasDevOnly: false`, fail the cache-reuse guard below,
+    // and be rebuilt in full on every call. Refuse instead of silently
+    // re-scanning the whole graph forever.
+    if (wantDevOnly && opts.isDevOnlyNode == null) {
+        throw new Error('buildStringIndex: withDevOnly requires isDevOnlyNode; without it the dev-root pass cannot run.');
+    }
     if (cached && (!wantDevOnly || cached.hasDevOnly)) {
         return cached;
     }

package/dist/string-index.js.map

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

package/dist/tools/analyze-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-run.d.ts","sourceRoot":"","sources":["../../src/tools/analyze-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA6KvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8U1D"}
+{"version":3,"file":"analyze-run.d.ts","sourceRoot":"","sources":["../../src/tools/analyze-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAoMvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2Y1D"}

package/dist/tools/analyze-run.js

@@ -15,7 +15,7 @@ import { getRegisteredTool } from '../tool-registry.js';
 import { activeElapsedMs, activeTimeoutMs_, beginAnalysisBudget, endAnalysisBudget, ScanTimeoutError, } from '../analysis-budget.js';
 import { clearAllSnapshots, listSnapshots, setCurrentSnapshot, setSnapshot, } from '../heap-state.js';
 import { artifactLabel } from '../artifact-classes.js';
-import { errorResult, formatBytes, formatNumber, markdownTable, toolResult, } from '../utils.js';
+import { errorResult, formatBytes, formatNumber, markdownTable, pathsHeader, toolResult, } from '../utils.js';
 import { computeSequenceTrends } from './sequence-analysis.js';
 const { getFullHeapFromFile } = memlabHeapAnalysis;
 /**
@@ -44,10 +44,17 @@ const { getFullHeapFromFile } = memlabHeapAnalysis;
  */
 async function runTool(name, args, budgetMs, unanalyzed) {
     const entry = getRegisteredTool(name);
-    if (entry == null)
+    if (entry == null) {
+        // A step that did not run belongs under UNANALYZED whatever the reason.
+        // Returning only the inline note let a misspelled step name — or a tool
+        // missing from this server build — print "every step of the protocol ran"
+        // underneath a section that never executed.
+        unanalyzed.push(`${name} is not registered on this server`);
         return `_(${name} is not registered on this server)_`;
+    }
     const outerRemaining = Math.max(0, activeTimeoutMs_() - activeElapsedMs());
     const outerTimeout = activeTimeoutMs_();
+    const stepStart = Date.now();
     beginAnalysisBudget(budgetMs);
     try {
         const res = await entry.handler(args, {});
@@ -85,9 +92,15 @@ async function runTool(name, args, budgetMs, unanalyzed) {
     finally {
         // Restore the caller's budget, minus what this step consumed, so the
         // remaining steps still run under the overall timeout rather than getting
-        // a fresh one each.
+        // a fresh one each. The subtraction is the whole point:
+        // `beginAnalysisBudget` resets the clock unconditionally, so restoring the
+        // pre-step remaining would pause the outer guardrail for the duration of
+        // every step and let a chain of N steps overrun `timeout_ms` by the sum of
+        // their wall clocks. The floor of 1ms keeps the budget ARMED once it is
+        // exhausted (0 would disable it), so the next step trips immediately.
         if (outerTimeout > 0) {
-            beginAnalysisBudget(Math.max(1, outerRemaining));
+            const stepElapsed = Date.now() - stepStart;
+            beginAnalysisBudget(Math.max(1, outerRemaining - stepElapsed));
         }
         else {
             endAnalysisBudget();
@@ -186,29 +199,77 @@ export function registerAnalyzeRun(server) {
             if (missing > 0) {
                 unanalyzed.push(`${missing} rung file(s) from the manifest are missing on disk and were excluded.`);
             }
-            const paths = rungs.map(r => r.path);
-            const first = rungs[0];
-            const last = rungs[rungs.length - 1];
+            // A mid-run page reload starts a NEW V8 isolate, so deltas ACROSS the
+            // split compare two unrelated heaps. hunt_runner already detects this
+            // and records it; nothing downstream was reading it, so the trend was
+            // fitted straight through the discontinuity. On one measured round that
+            // turned a real +2.1 MB into a reported -3.6 MB — the sign flipped.
+            // Analyse the longest unbroken SEGMENT instead, and say so.
+            const allRungs = rungs;
+            const segments = [];
+            for (const rung of allRungs) {
+                if (segments.length === 0 || rung.isolate_restarted) {
+                    segments.push([rung]);
+                }
+                else {
+                    segments[segments.length - 1].push(rung);
+                }
+            }
+            const longest = segments.reduce((best, seg) => (seg.length > best.length ? seg : best), segments[0] ?? []);
+            const ladderSplit = segments.length > 1;
+            if (ladderSplit && longest.length < 2) {
+                return errorResult(`The page reloaded ${segments.length - 1} time(s) during this run, and no unbroken segment has 2 or more rungs. ` +
+                    'Every delta would compare two different V8 isolates, so there is nothing here to fit a trend to. ' +
+                    'Re-drive the round without the reload — a positive control that COLLAPSES across a split is a corrupted ladder, not a failed control.');
+            }
+            const analysed = ladderSplit ? longest : allRungs;
+            const paths = analysed.map(r => r.path);
+            const first = analysed[0];
+            const last = analysed[analysed.length - 1];
             const perRungCycles = cycles_between_rungs ??
-                (rungs.length > 1
-                    ? Math.round((last.cycles - first.cycles) / (rungs.length - 1))
+                (analysed.length > 1
+                    ? Math.round((last.cycles - first.cycles) / (analysed.length - 1))
                     : 0);
             const out = [
                 `# Leak-hunt analysis — ${manifest.run_id ?? path.basename(path.dirname(manifestPath))}`,
                 '',
-                `Combos: ${(manifest.config?.combos ?? []).join(', ') || '(unrecorded)'} · cycles driven: ${formatNumber(manifest.totals?.cycles ?? last.cycles)} (ok ${formatNumber(manifest.totals?.ok ?? 0)} / fail ${formatNumber(manifest.totals?.fail ?? 0)}) · ${rungs.length} rungs · ~${formatNumber(perRungCycles)} cycles between rungs`,
+                `Combos: ${(manifest.config?.combos ?? []).join(', ') || '(unrecorded)'} · cycles driven: ${formatNumber(manifest.totals?.cycles ?? last.cycles)} (ok ${formatNumber(manifest.totals?.ok ?? 0)} / fail ${formatNumber(manifest.totals?.fail ?? 0)}) · ${analysed.length} rungs analysed${ladderSplit ? ` of ${allRungs.length} captured` : ''} · ~${formatNumber(perRungCycles)} cycles between rungs`,
                 manifest.stop_reason ? `Stop reason: ${manifest.stop_reason}` : '',
                 '',
                 '## Ladder',
                 '',
-                markdownTable(['Rung', 'Cycles', 'Post-GC heap', 'Reason'], rungs.map(r => [
-                    String(r.index),
-                    formatNumber(r.cycles),
-                    `${r.post_gc_heap_mb.toFixed(1)} MB`,
-                    r.reason ?? '',
-                ]), new Set([0, 1, 2])),
+                markdownTable(
+                // The exclusion column only exists when something was excluded.
+                // Emitting it unconditionally left an unnamed, empty fifth column
+                // on every unsplit ladder — which is most of them.
+                ladderSplit
+                    ? ['Rung', 'Cycles', 'Post-GC heap', 'Reason', 'Analysed?']
+                    : ['Rung', 'Cycles', 'Post-GC heap', 'Reason'], allRungs.map(r => {
+                    const row = [
+                        String(r.index),
+                        formatNumber(r.cycles),
+                        `${r.post_gc_heap_mb.toFixed(1)} MB`,
+                        r.reason ?? '',
+                    ];
+                    if (ladderSplit) {
+                        row.push(analysed.includes(r)
+                            ? 'yes'
+                            : r.isolate_restarted
+                                ? 'no — reload, new isolate'
+                                : 'no — other segment');
+                    }
+                    return row;
+                }), new Set([0, 1, 2])),
                 '',
             ].filter(Boolean);
+            if (ladderSplit) {
+                out.push(`> ⚠️ **LADDER SPLIT — the page reloaded ${segments.length - 1} time(s) mid-run.** A reload starts a new V8 ` +
+                    `isolate, so any delta spanning the split compares two unrelated heaps. This analysis uses only the ` +
+                    `longest unbroken segment (rungs ${longest[0].index}–${longest[longest.length - 1].index}, ` +
+                    `${longest.length} of ${allRungs.length}); the other rungs are excluded above. ` +
+                    `Segment lengths: ${segments.map(seg => seg.length).join(', ')}. ` +
+                    `If a positive control COLLAPSED in this round, read that as a corrupted ladder rather than a failed control.`, '');
+            }
             const heapDelta = last.post_gc_heap_mb - first.post_gc_heap_mb;
             out.push(`Aggregate post-GC heap moved **${heapDelta >= 0 ? '+' : ''}${heapDelta.toFixed(1)} MB** across the run. Aggregate heap is the weakest signal here and is reported for completeness only: a measured round found a real leak (+6.25 undo entries/cycle, linear across five rungs) while aggregate heap FELL 8.9 MB. The per-class trend below is what decides.`, '');
             // ---- Step 1: ladder trend (transient loads, one graph at a time) ----
@@ -245,7 +306,7 @@ export function registerAnalyzeRun(server) {
                         `+${formatNumber(g.netCount)}`,
                         perRungCycles > 0
                             ? (g.netCount /
-                                (perRungCycles * (rungs.length - 1))).toFixed(2)
+                                (perRungCycles * (analysed.length - 1))).toFixed(2)
                             : '—',
                         `${g.netSize >= 0 ? '+' : ''}${formatBytes(g.netSize)}`,
                         g.artifact != null
@@ -333,7 +394,7 @@ export function registerAnalyzeRun(server) {
             if (resident) {
                 out.push(`_Resident snapshots: ${resident}. Follow up on a specific object with \`memlab_dominator_chain\` / \`memlab_retainer_trace\`, or unload them with \`memlab_snapshots\`._`);
             }
-            return toolResult(out.join('\n'));
+            return toolResult(out.join('\n'), pathsHeader(paths.map(p => p.replace(/^.*\//, ''))));
         }
         catch (err) {
             return errorResult(err);