@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/utils.js

@@ -7,7 +7,7 @@
  * @format
  * @oncall memory_lab
  */
-import { getSnapshotMetadata, getSessionConfig, shouldEmitHeader, } from './heap-state.js';
+import { getSnapshotMetadata, getSessionConfig, isLightSnapshot, shouldEmitHeader, } from './heap-state.js';
 // ScanTimeoutError / makeScanBudget moved to analysis-budget.ts (shared, no
 // import cycle). Re-exported here so existing `from '../utils.js'` imports in
 // the tools keep working unchanged.
@@ -59,6 +59,36 @@ export function truncateDomToTag(name) {
     }
     return `${detached}<${tag}>`;
 }
+// Marker left in place of elided C++ template arguments. Distinctive enough to
+// detect when rendering a legend, and short enough to be worth the swap.
+export const BLINK_TEMPLATE_ELISION = '<…>';
+// A Blink/cppgc type name carries its whole template instantiation, and one hop
+// of a retainer trace can be 400+ tokens of
+// `blink::HeapHashTableBacking<blink::HashTable<cppgc::internal::BasicMember<…>>>`.
+// The information a reader acts on is the OUTER type; the arguments are noise
+// that crowds out the rest of the trace. Collapse everything from the first `<`
+// to the matching final `>` into one marker, keeping any suffix after it.
+//
+// Deliberately conservative: only applied to `::`-qualified C++ names (so a JS
+// class that happens to contain `<` is untouched), and only when the name is
+// long enough for the elision to be worth it — abbreviating
+// `blink::Foo<Bar>` into something barely shorter just costs information.
+const CPP_TEMPLATE_MIN_LEN = 48;
+export function abbreviateBlinkTypeName(name) {
+    if (name.length < CPP_TEMPLATE_MIN_LEN)
+        return name;
+    if (!name.includes('::') || !name.includes('<'))
+        return name;
+    const open = name.indexOf('<');
+    const close = name.lastIndexOf('>');
+    if (close <= open)
+        return name;
+    const head = name.slice(0, open);
+    const tail = name.slice(close + 1);
+    const abbreviated = `${head}${BLINK_TEMPLATE_ELISION}${tail}`;
+    // Never let the "abbreviation" be longer than what it replaced.
+    return abbreviated.length < name.length ? abbreviated : name;
+}
 export function truncateNodeName(name, type, selfSize, maxLen = 150, aggressiveDom = false) {
     if (type === 'string' ||
         type === 'concatenated string' ||
@@ -83,9 +113,10 @@ export function truncateNodeName(name, type, selfSize, maxLen = 150, aggressiveD
         }
         return name;
     }
-    if (name.length <= maxLen)
-        return name;
-    return `${name.slice(0, maxLen)}…`;
+    const abbreviated = abbreviateBlinkTypeName(name);
+    if (abbreviated.length <= maxLen)
+        return abbreviated;
+    return `${abbreviated.slice(0, maxLen)}…`;
 }
 export function serializeNodeSummary(node) {
     return {
@@ -153,11 +184,21 @@ const NODE_NAME_BLOCK_LIST = new Set([
     '(External strings)',
     '(Builtins)',
 ]);
-export function isNodeWorthInspecting(node) {
+/**
+ * Whether a node is worth showing in a default "interesting objects" listing.
+ *
+ * `NODE_TYPE_BLOCK_LIST` exists to keep noise out of the DEFAULT view — it is not
+ * meant to make those types unreachable. When a caller explicitly asks for one
+ * of them (e.g. `largest_objects({node_type: 'array'})`), honour the request:
+ * otherwise the filter silently returns zero rows for `array`, `native`, `code`,
+ * `synthetic` and `hidden`, which reads as "there are none" on a heap that
+ * plainly contains 100k+ of them.
+ */
+export function isNodeWorthInspecting(node, opts) {
     if (node.id <= 3) {
         return false;
     }
-    if (NODE_TYPE_BLOCK_LIST.has(node.type)) {
+    if (!opts?.allowBlockedTypes && NODE_TYPE_BLOCK_LIST.has(node.type)) {
         return false;
     }
     if (NODE_NAME_BLOCK_LIST.has(node.name)) {
@@ -228,11 +269,27 @@ export function looksLikeFailurePayload(value) {
         /"error"\s*:\s*"(?!null)[^"]+/i.test(head));
 }
 export function filterLargestObjects(snapshot, filter, limit) {
+    return filterLargestObjectsCounted(snapshot, filter, limit).nodes;
+}
+/**
+ * As `filterLargestObjects`, but also reports how many nodes MATCHED.
+ *
+ * The population size is not a nicety. A conclusion drawn from the top 5 of a
+ * matching population reads identically whether that population was 5 or 23,918,
+ * and the difference decides whether the conclusion is sound: one report stated
+ * "all 5 sampled instances share the same retainer pattern — likely a single
+ * root cause" where a full-population trace found 1,468 distinct paths, the
+ * largest covering 2.2%. The sample fraction has to reach the caller, so the
+ * walk that already visits every node returns it.
+ */
+export function filterLargestObjectsCounted(snapshot, filter, limit) {
     let result = [];
+    let matched = 0;
     snapshot.nodes.forEach(node => {
         if (!filter(node)) {
             return;
         }
+        matched++;
         const size = node.retainedSize;
         let i;
         for (i = result.length - 1; i >= 0; --i) {
@@ -246,7 +303,7 @@ export function filterLargestObjects(snapshot, filter, limit) {
         }
         result = result.slice(0, limit);
     });
-    return result;
+    return { nodes: result, matched };
 }
 /**
  * Collapse heap nodes that are merely different VIEWS of the same dominator
@@ -413,6 +470,159 @@ export function boundedDominatorRetainedSize(ids, snapshot, maxWalk = 500) {
     }
     return { retained, exact };
 }
+/**
+ * Collect the object-valued slots of a Map/Set/WeakMap backing store, sorted by
+ * their true FixedArray slot index.
+ *
+ * V8 stores entries in an OrderedHashMap/OrderedHashSet reachable via the
+ * `table` (or `backing_store`) edge. Browser (Chromium) snapshots type the
+ * key/value slot edges as `internal` with a numeric name (the array index);
+ * Node snapshots type them `element`. The header counts and hash-chain links are
+ * inline SMIs, which emit NO edge at all — so the slot indices are NOT
+ * contiguous, and the GAPS are meaningful (they mark SMI-valued or deleted
+ * slots). Returning the slots WITH their indices lets callers pair by index
+ * instead of by position, which is what makes the pairing correct when some
+ * values are SMIs (see `enumerateMapEntries`).
+ */
+export function collectBackingSlots(node) {
+    const out = [];
+    for (const edge of node.references) {
+        const eName = String(edge.name_or_index);
+        if (eName !== 'table' && eName !== 'backing_store')
+            continue;
+        const backing = edge.toNode;
+        for (const te of backing.references) {
+            // Skip the backing store's hidden-class pointer and any hidden edges; the
+            // remaining element/internal edges are the real key/value slots.
+            if (te.type === 'hidden' || String(te.name_or_index) === 'map')
+                continue;
+            const idx = Number(te.name_or_index);
+            if (!Number.isFinite(idx))
+                continue;
+            const target = te.toNode;
+            // `the_hole` marks a deleted/empty backing-store slot; oddball roots
+            // (id<=3) are not real entries. Do NOT skip `undefined`: an explicit
+            // `undefined` value/element is a real entry, and dropping it would make it
+            // indistinguishable from an inline-primitive gap (mis-reported as absent).
+            if (target.id <= 3 || target.name === 'the_hole') {
+                continue;
+            }
+            out.push({ idx, node: target });
+        }
+        break;
+    }
+    out.sort((a, b) => a.idx - b.idx);
+    return out;
+}
+/**
+ * Enumerate a Map/WeakMap's (key, value) entries.
+ *
+ * V8 lays each entry out as consecutive slots `[key, value, chain]` (the chain
+ * link is an inline SMI, so it emits no edge). We therefore pair a key with the
+ * value in the immediately-following slot INDEX (`key.idx + 1`). When no slot
+ * exists at `key.idx + 1`, the value was an inline SMI/primitive and we emit
+ * `value: null` — instead of mispairing the key with the NEXT entry's key, which
+ * is what naive "consecutive object edges = key,value" pairing does whenever a
+ * Map has SMI values (a real correctness bug on browser heaps).
+ */
+export function enumerateMapEntries(node) {
+    const slots = collectBackingSlots(node);
+    const entries = [];
+    let i = 0;
+    while (i < slots.length) {
+        const key = slots[i];
+        const next = slots[i + 1];
+        if (next && next.idx === key.idx + 1) {
+            entries.push({ key: key.node, value: next.node });
+            i += 2;
+        }
+        else {
+            // Value slot absent at key.idx+1 → the value was an inline SMI/primitive.
+            entries.push({ key: key.node, value: null });
+            i += 1;
+        }
+    }
+    return entries;
+}
+/** Enumerate a Set's elements (every occupied backing-store slot). */
+export function enumerateSetElements(node) {
+    return collectBackingSlots(node).map(s => s.node);
+}
+/**
+ * Property names that identify an individual record rather than describe its
+ * content — always unique per instance, so INCLUDING them in a content
+ * signature defeats duplicate detection (every record looks distinct). Excluded
+ * by default from `objectContentSignature`. `id`/`__id`/`__ref` are Relay/GraphQL
+ * data-id fields; `key`/`clientMutationId` are common per-instance keys.
+ */
+export const IDENTITY_PROPS = new Set([
+    'id',
+    '__id',
+    '__ref',
+    'key',
+    'clientMutationId',
+]);
+/**
+ * A stable, shallow content signature for an object: the sorted set of property
+ * names, each annotated with its scalar value (strings capped) or a marker for
+ * object/array-valued properties. Two objects with the same signature are
+ * structurally identical at one level — the basis for duplicate-record
+ * detection (`memlab_duplicate_objects`) and ad-hoc dedup checks in eval.
+ *
+ * By default per-instance identity fields (`IDENTITY_PROPS`: id/__id/__ref/…) are
+ * EXCLUDED so records that differ only by their data-id still collapse together
+ * — pass `ignoreProps` to override the set (e.g. `new Set()` to include them).
+ *
+ * String, boolean, null and object-valued properties are captured (objects
+ * generically as `o`, so nested content is not compared).
+ *
+ * Caveat — numeric values are NOT captured: the V8 heap-snapshot format does not
+ * store the actual value of a number field (SMI nodes are `smi number`,
+ * heap-numbers are `heap number` — the IEEE-754/int value is not accessible; see
+ * `tools/get-value.ts`). A numeric property therefore contributes only a generic
+ * `<name>=n` marker, so two objects differing ONLY in a numeric field hash to the
+ * same signature and are reported as duplicates. Treat numeric-heavy records
+ * accordingly (or compare their values via another tool).
+ */
+export function objectContentSignature(node, opts = {}) {
+    const maxLen = opts.maxStringLen ?? 40;
+    const ignore = opts.ignoreProps ?? IDENTITY_PROPS;
+    const parts = [];
+    for (const edge of node.references) {
+        // Hidden-class ("map") and other internal edges are already excluded by the
+        // `edge.type !== 'property'` guard above, so no explicit `map` name skip is
+        // needed (it would only hide a legitimate user property literally named "map").
+        if (edge.type !== 'property')
+            continue;
+        const name = String(edge.name_or_index);
+        if (name === '__proto__')
+            continue;
+        if (ignore.has(name))
+            continue;
+        const t = edge.toNode;
+        if (t.isString) {
+            const v = t.toStringNode()?.stringValue ?? '';
+            parts.push(`${name}=s:${v.length > maxLen ? v.slice(0, maxLen) : v}`);
+        }
+        else if (t.type === 'number' || t.name === 'heap number') {
+            // Numeric values are NOT recoverable from the snapshot format (SMI /
+            // heap-number nodes carry no value — see get-value.ts), so we can only
+            // record that the property is a number, not distinguish by value.
+            parts.push(`${name}=n`);
+        }
+        else if (t.name === 'true' ||
+            t.name === 'false' ||
+            t.name === 'null' ||
+            t.name === 'undefined') {
+            parts.push(`${name}=${t.name}`);
+        }
+        else {
+            parts.push(`${name}=o`);
+        }
+    }
+    parts.sort();
+    return parts.join('|');
+}
 /**
  * Best-effort detection of which app a Node snapshot came from, by tallying the
  * `/app(s)/<name>/` segment in bundle paths embedded throughout the heap (string
@@ -489,6 +699,97 @@ export function instrumentationRetainerNote(steps) {
     }
     return null;
 }
+/** Describe a non-property edge in the terms a reader can act on. */
+function describeOwnerRelation(edge) {
+    const name = String(edge.name_or_index);
+    if (edge.type === 'property' && !/^\d+$/.test(name))
+        return null;
+    // A captured variable keeps its source name even after minification, which
+    // makes it more useful than the anchor it hangs under.
+    if (edge.type === 'context')
+        return `closure var ${name}`;
+    if (/^\d+$/.test(name))
+        return 'entry';
+    return name;
+}
+export function nearestNamedOwner(node, opts) {
+    const maxHops = opts?.maxHops ?? 6;
+    let relation = null;
+    let current = node;
+    for (let hop = 0; hop < maxHops; hop++) {
+        // A named property wins over any other referrer at the same hop: it is the
+        // only edge that names the object rather than merely containing it.
+        let chosen = null;
+        for (const edge of current.referrers) {
+            const name = String(edge.name_or_index);
+            if (edge.type === 'property' && !/^\d+$/.test(name)) {
+                chosen = edge;
+                break;
+            }
+            if (!chosen)
+                chosen = edge;
+        }
+        if (!chosen)
+            return null;
+        // Only the FIRST hop describes how the target itself is held; hops above it
+        // are the anchor's own retention and not the caller's concern.
+        if (hop === 0)
+            relation = describeOwnerRelation(chosen);
+        const name = String(chosen.name_or_index);
+        if (chosen.type === 'property' && !/^\d+$/.test(name)) {
+            const anchor = `${chosen.fromNode.name}.${name}`;
+            return {
+                anchor,
+                relation,
+                label: relation == null ? anchor : `${anchor} ▸ ${relation}`,
+                ownerNode: chosen.fromNode,
+                hops: hop + 1,
+            };
+        }
+        current = chosen.fromNode;
+    }
+    return null;
+}
+/**
+ * V8 emits a WeakMap entry as one synthetic edge on the backing table:
+ *
+ *   `26 / part of key (Foo @644221) -> value (Bar @644219) pair in WeakMap (table @3212981)`
+ *
+ * A retainer path that ENDS on such an edge proves nothing. The WeakMap holds
+ * the value only for as long as something else holds the KEY, and V8 collects
+ * value→key cycles, so "retained by a WeakMap" is not a reason an object is
+ * alive — the reason is whatever retains the key. Acting on the path as printed
+ * produces a fix for a leak that is not there.
+ */
+const EPHEMERON_EDGE_RE = /part of key \(([^@()]*)@(\d+)\)\s*->\s*value \(([^@()]*)@(\d+)\) pair in WeakMap/;
+/** Parse a WeakMap ephemeron edge name, or `null` if it is an ordinary edge. */
+export function parseEphemeronEdge(edgeName) {
+    if (edgeName == null)
+        return null;
+    const m = EPHEMERON_EDGE_RE.exec(edgeName);
+    if (!m)
+        return null;
+    return {
+        keyName: m[1].trim(),
+        keyId: Number(m[2]),
+        valueName: m[3].trim(),
+        valueId: Number(m[4]),
+    };
+}
+/**
+ * The caveat to print when a path traverses an ephemeron edge. `atTarget` marks
+ * the case where it is the LAST hop, which is the one that invalidates the
+ * conclusion outright rather than merely complicating it.
+ */
+export function ephemeronCaveat(eph, atTarget) {
+    return (`⚠ **This path crosses a WeakMap key→value pair${atTarget ? ' as its FINAL hop' : ''}, so it does not explain retention.** ` +
+        `A WeakMap holds \`${eph.valueName || 'the value'}\` only while something else holds the KEY ` +
+        `\`${eph.keyName || 'key'}\` @${eph.keyId}, and V8 collects value→key cycles — so "retained by a WeakMap" is never the reason an object is alive. ` +
+        `Re-trace from the key to find the real retainer: \`memlab_retainer_trace({node_id: ${eph.keyId}})\`.` +
+        (atTarget
+            ? ' Until you do, treat this object as UNEXPLAINED, not as a confirmed leak.'
+            : ''));
+}
 export function formatBytes(bytes) {
     if (!Number.isFinite(bytes) || bytes < 0)
         return 'N/A';
@@ -527,6 +828,89 @@ export function formatNodeInline(id, name, type, selfSize) {
     const displayName = selfSize != null ? truncateNodeName(name, type, selfSize, 80) : name;
     return `@${id} ${displayName} (${type})`;
 }
+/**
+ * Collapse runs of consecutive same-class hops in a retainer path into a single
+ * step tagged with `repeatCount`.
+ *
+ * Linked structures (a React hook update queue's `pending → .next → .next → …`,
+ * intrusive lists, promise chains) produce paths that are hundreds of identical
+ * `Object → Object → Object` hops long. Rendering every hop costs thousands of
+ * tokens and tells the reader nothing the count doesn't: the interesting part is
+ * the chain's head, its length, and where it attaches. This keeps the first hop
+ * of each run (so the edge into the run is preserved) and folds the rest.
+ *
+ * Only runs of at least `minRun` are collapsed, so ordinary short paths render
+ * exactly as before.
+ */
+export function collapseRepeatedRuns(steps, minRun = 3) {
+    if (steps.length < minRun)
+        return steps;
+    const key = (s) => `${s.type}::${s.name}`;
+    const out = [];
+    // The final step is the node the caller asked about. Never fold it into a
+    // run, or the trace stops showing the object under investigation and the
+    // "← retained object" marker lands on a summarised run instead.
+    const foldLimit = steps.length - 1;
+    let i = 0;
+    while (i < foldLimit) {
+        let j = i + 1;
+        while (j < foldLimit && key(steps[j]) === key(steps[i]))
+            j++;
+        const run = j - i;
+        if (run >= minRun) {
+            // Keep the first hop (carries the edge into the run) and the last hop's
+            // identity is the same class, so one step with a count is lossless enough.
+            out.push({ ...steps[i], repeatCount: run });
+        }
+        else {
+            for (let k = i; k < j; k++)
+                out.push(steps[k]);
+        }
+        i = j;
+    }
+    out.push(steps[foldLimit]);
+    return out;
+}
+/**
+ * Collapse runs of an identical rendered label, for formatters that have already
+ * reduced each hop to a string. Mirrors `collapseRepeatedRuns` for chain-style
+ * (`A → B → C`) renderers.
+ */
+export function collapseRepeatedLabels(labels, minRun = 3) {
+    if (labels.length < minRun)
+        return labels;
+    const out = [];
+    // Mirror collapseRepeatedRuns: the last label is the target, keep it intact.
+    const foldLimit = labels.length - 1;
+    let i = 0;
+    while (i < foldLimit) {
+        let j = i + 1;
+        while (j < foldLimit && labels[j] === labels[i])
+            j++;
+        const run = j - i;
+        out.push(run >= minRun ? `${labels[i]} ×${run}` : labels[i]);
+        for (let k = i + 1; k < j && run < minRun; k++)
+            out.push(labels[k]);
+        i = j;
+    }
+    out.push(labels[foldLimit]);
+    return out;
+}
+/**
+ * One-line note describing what a tool's thresholds excluded from its own
+ * output. Printing this everywhere a default threshold exists prevents the
+ * failure mode where a tool reports "0" or "none found" and the reader takes it
+ * as "there is nothing there", when in fact everything interesting was below the
+ * cutoff. (A `dev_artifacts` run reporting `0 B` dev-only — because every
+ * console-retained string was under the 512 KB default — nearly landed a
+ * measurement artifact in a diff as a production leak.)
+ */
+export function describeSkipped(examined, skipped, thresholdLabel) {
+    if (skipped <= 0) {
+        return `_Examined all ${formatNumber(examined)} candidates; no ${thresholdLabel} filter excluded anything._`;
+    }
+    return `_Examined ${formatNumber(examined)} candidates; **${formatNumber(skipped)} were skipped by ${thresholdLabel}** and are NOT reflected in the rows above. Lower it if you expect something smaller._`;
+}
 function formatEdgeLabel(name) {
     const trimmed = name.length > 40 ? `${name.slice(0, 39)}…` : name;
     if (/^\d+$/.test(trimmed))
@@ -569,7 +953,10 @@ function formatRetainerLadder(steps, showSizes) {
             ? `  — ${formatBytes(s.retainedSize)}`
             : '';
         const nodeStr = formatNodeInline(s.id, s.name, s.type, s.selfSize);
-        lines.push(`${nodeStr}${size}${retainerMarker(i, steps.length)}`);
+        const repeat = s.repeatCount && s.repeatCount > 1
+            ? `  ×${s.repeatCount} (chain of identical hops)`
+            : '';
+        lines.push(`${nodeStr}${repeat}${size}${retainerMarker(i, steps.length)}`);
     }
     return lines.join('\n');
 }
@@ -618,11 +1005,18 @@ export function formatRetainerTree(steps, opts = {}) {
             ? `  — ${formatBytes(s.retainedSize)}`
             : '';
         const nodeStr = formatNodeInline(s.id, s.name, s.type, s.selfSize);
-        lines.push(`${pad}${connector}${nodeStr}${size}${retainerMarker(i, steps.length)}`);
+        const repeat = s.repeatCount && s.repeatCount > 1
+            ? `  ×${s.repeatCount} (chain of identical hops)`
+            : '';
+        lines.push(`${pad}${connector}${nodeStr}${repeat}${size}${retainerMarker(i, steps.length)}`);
     }
     return lines.join('\n');
 }
 export function formatNodeSummaryTable(nodes) {
+    // On a light load there is no dominator pass, so every `retainedSize` reads
+    // 0. Printing "0 B" in a Retained Size column is a wrong answer wearing the
+    // costume of a right one; say the number does not exist instead.
+    const light = isLightSnapshot();
     const headers = ['ID', 'Name', 'Type', 'Self Size', 'Retained Size'];
     const rightCols = new Set([3, 4]);
     const rows = nodes.map(n => [
@@ -630,9 +1024,22 @@ export function formatNodeSummaryTable(nodes) {
         n.name,
         n.type,
         formatBytes(n.self_size),
-        formatBytes(n.retained_size),
+        light ? 'n/a (light)' : formatBytes(n.retained_size),
     ]);
-    return markdownTable(headers, rows, rightCols);
+    return markdownTable(headers, rows, rightCols) + blinkLegend(rows.flat());
+}
+/**
+ * Legend for elided C++ template arguments, emitted only when something in the
+ * rendered output actually carries the marker — an unconditional legend is the
+ * same token tax the abbreviation exists to remove.
+ */
+export function blinkLegend(rendered) {
+    for (const cell of rendered) {
+        if (typeof cell === 'string' && cell.includes(BLINK_TEMPLATE_ELISION)) {
+            return `\n\n_\`${BLINK_TEMPLATE_ELISION}\` = C++ template arguments elided; the outer type is what identifies the object. Use \`memlab_get_node\` for the full instantiated name._`;
+        }
+    }
+    return '';
 }
 export function formatQueryNodesResult(result, offset) {
     const partial = result.timed_out
@@ -655,6 +1062,31 @@ export function formatQueryNodesResult(result, offset) {
     }
     return `Total matching nodes: ${formatNumber(result.total_count)}${partial}`;
 }
+/**
+ * Build a name filter from a caller-supplied pattern.
+ *
+ * Interpreted as a case-insensitive regular expression, falling back to a plain
+ * case-insensitive substring test when the pattern is not valid regex — so a
+ * literal like `blink::UndoStep` works without escaping and a real pattern
+ * still works. An empty/absent pattern matches everything.
+ *
+ * Why this exists: answering "is `blink::UndoStep` present?" previously meant
+ * `class_histogram({node_type: "native", limit: 200})` and reading ~4 KB of
+ * table for one row. Filtering at the source is the difference between a
+ * yes/no answer and a page of output.
+ */
+export function makeNamePatternTest(pattern) {
+    if (pattern == null || pattern.length === 0)
+        return () => true;
+    try {
+        const re = new RegExp(pattern, 'i');
+        return (name) => re.test(name);
+    }
+    catch {
+        const needle = pattern.toLowerCase();
+        return (name) => name.toLowerCase().includes(needle);
+    }
+}
 export function snapshotHeader() {
     const meta = getSnapshotMetadata();
     if (!meta)
@@ -666,21 +1098,81 @@ export function snapshotHeader() {
             : 'Unknown';
     return `> Snapshot: ${meta.fileName} (${formatBytes(meta.totalSize)}, ${formatNumber(meta.nodeCount)} nodes, ${envLabel})`;
 }
+/**
+ * The header for a tool that read snapshots given as PATHS.
+ *
+ * `snapshotHeader()` can only ever describe the RESIDENT snapshot, because that
+ * is the only one the session knows about. For a path-taking tool that is the
+ * wrong file by construction whenever the caller has something else loaded —
+ * and these tools restore the caller's active snapshot before they build their
+ * result (see `withSnapshotAt`), so by the time the header is rendered the
+ * snapshot it names is never the one that was measured.
+ *
+ * Measured across a 12-round investigation: every path-based call printed a
+ * header naming a capture from an earlier round. A ladder result labelled with
+ * another round's rung is a cross-round misattribution hazard in exactly the
+ * workflow these tools exist for, so name what was actually read.
+ */
+export function pathsHeader(labels) {
+    const seen = labels.filter(l => l.length > 0);
+    if (seen.length === 0)
+        return '';
+    if (seen.length === 1)
+        return `> Snapshot: ${seen[0]}`;
+    if (seen.length === 2)
+        return `> Snapshots: ${seen[0]} → ${seen[1]}`;
+    return `> Snapshots: ${seen.length} rungs, ${seen[0]} … ${seen[seen.length - 1]}`;
+}
 export function textResult(text) {
     return { content: [{ type: 'text', text }] };
 }
-export function toolResult(text) {
-    const header = shouldEmitHeader() ? snapshotHeader() : '';
+/**
+ * @param headerOverride Pass `pathsHeader([...])` when the tool read snapshots
+ * by PATH rather than operating on the resident one. Passing `null` suppresses
+ * the header entirely. Omitting it keeps the session-header behaviour, which is
+ * correct only for tools that genuinely act on the active snapshot.
+ */
+export function toolResult(text, headerOverride) {
+    const header = headerOverride !== undefined
+        ? (headerOverride ?? '')
+        : shouldEmitHeader()
+            ? snapshotHeader()
+            : '';
     const body = header ? `${header}\n\n${text}` : text;
     return { content: [{ type: 'text', text: body }] };
 }
+/**
+ * After this many suggestion trailers in one server process, the rest are
+ * suppressed automatically.
+ *
+ * The trailer is genuinely useful the first time and pure cost thereafter: it
+ * is the same text on every call, and a long investigation makes dozens of
+ * calls. `suppressSuggestions` already existed but has to be set deliberately,
+ * which means it is set — if at all — only after the tokens have been spent.
+ * Auto-suppressing keeps the onboarding value and drops the repetition without
+ * anyone having to notice.
+ */
+const SUGGESTION_TRAILER_BUDGET = 5;
+let suggestionTrailersEmitted = 0;
 /**
  * Whether tools should omit "Suggested next steps" / "How to fix" trailers.
  * Honors the session-level `suppressSuggestions` config so callers can trim
- * repeated boilerplate tokens across a long investigation.
+ * repeated boilerplate tokens across a long investigation, and self-suppresses
+ * after `SUGGESTION_TRAILER_BUDGET` trailers.
+ *
+ * NOTE: this both reads and ADVANCES the budget, so call it once per decision.
  */
 export function suggestionsSuppressed() {
-    return getSessionConfig().suppressSuggestions;
+    if (getSessionConfig().suppressSuggestions)
+        return true;
+    if (suggestionTrailersEmitted >= SUGGESTION_TRAILER_BUDGET)
+        return true;
+    suggestionTrailersEmitted++;
+    return false;
+}
+/** Test seam; also reset when the session config is changed explicitly. */
+export function resetSuggestionBudget() {
+    suggestionTrailersEmitted = 0;
 }
 export function jsonResult(data) {
     return textResult(JSON.stringify(data, null, 2));