memorydetective 1.8.1 → 1.10.0

package/dist/tools/analyzeAnimationHitches.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { runCommand } from "../runtime/exec.js";
 import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
 export const analyzeAnimationHitchesSchema = z.object({
     tracePath: z
         .string()
@@ -18,11 +19,19 @@ export const analyzeAnimationHitchesSchema = z.object({
         .number()
         .nonnegative()
         .default(0)
-        .describe("Filter out hitches shorter than this duration in milliseconds. Apple categorizes hitches >100ms as user-perceptible — pass 100 to focus on those."),
+        .describe("Filter out hitches shorter than this duration in milliseconds. Apple categorizes hitches >100ms as user-perceptible, pass 100 to focus on those."),
+    timeRangeMs: z
+        .object({
+        startMs: z.number().nonnegative(),
+        endMs: z.number().nonnegative(),
+    })
+        .optional()
+        .describe("Optional time-window filter. Only hitches whose `startNs` falls within `[startMs, endMs]` (milliseconds since recording start) are included. Use this to answer 'what hitches happened during this 5-second user-visible jank window?' without re-recording."),
+    outputFormat: outputFormatField,
 });
 const PERCEPTIBLE_MS = 100;
 /** Pure: turn parsed XML into the analyzed result. */
-export function analyzeAnimationHitchesFromXml(xml, tracePath, topN = 10, minDurationMs = 0) {
+export function analyzeAnimationHitchesFromXml(xml, tracePath, topN = 10, minDurationMs = 0, timeRangeMs) {
     const tables = parseXctraceXml(xml);
     const table = tables.find((t) => t.schema === "animation-hitches");
     if (!table) {
@@ -39,6 +48,7 @@ export function analyzeAnimationHitchesFromXml(xml, tracePath, topN = 10, minDur
             byType: {},
             top: [],
             diagnosis: "No animation-hitches table found in the trace.",
+            status: "not_present",
         };
     }
     const all = [];
@@ -57,7 +67,17 @@ export function analyzeAnimationHitchesFromXml(xml, tracePath, topN = 10, minDur
             source: asFormatted(row.source),
         });
     }
-    const filtered = all.filter((e) => e.durationMs >= minDurationMs);
+    const filtered = all.filter((e) => {
+        if (e.durationMs < minDurationMs)
+            return false;
+        if (timeRangeMs) {
+            const startMs = e.startNs / 1_000_000;
+            if (startMs < timeRangeMs.startMs || startMs > timeRangeMs.endMs) {
+                return false;
+            }
+        }
+        return true;
+    });
     const byType = {};
     for (const e of filtered) {
         byType[e.hitchType] = (byType[e.hitchType] ?? 0) + 1;
@@ -83,6 +103,7 @@ export function analyzeAnimationHitchesFromXml(xml, tracePath, topN = 10, minDur
         byType,
         top,
         diagnosis,
+        status: "available",
     };
 }
 function buildDiagnosis(rows, perceptible, longestMs, averageMs) {
@@ -116,6 +137,6 @@ export async function analyzeAnimationHitches(input) {
     if (result.code !== 0) {
         throw new Error(`xctrace export failed (code ${result.code}): ${result.stderr || result.stdout}`);
     }
-    return analyzeAnimationHitchesFromXml(result.stdout, tracePath, input.topN ?? 10, input.minDurationMs ?? 0);
+    return analyzeAnimationHitchesFromXml(result.stdout, tracePath, input.topN ?? 10, input.minDurationMs ?? 0, input.timeRangeMs);
 }
 //# sourceMappingURL=analyzeAnimationHitches.js.map

package/dist/tools/analyzeAnimationHitches.js.map

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

package/dist/tools/analyzeAppLaunch.d.ts

@@ -1,10 +1,13 @@
 import { z } from "zod";
 export declare const analyzeAppLaunchSchema: z.ZodObject<{
     tracePath: z.ZodString;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
 }, "strip", z.ZodTypeAny, {
     tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
 }, {
     tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
 }>;
 export type AnalyzeAppLaunchInput = z.infer<typeof analyzeAppLaunchSchema>;
 export interface PhaseEntry {

package/dist/tools/analyzeAppLaunch.js

@@ -3,11 +3,13 @@ import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { runCommand } from "../runtime/exec.js";
 import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
 export const analyzeAppLaunchSchema = z.object({
     tracePath: z
         .string()
         .min(1)
         .describe("Absolute path to a `.trace` bundle recorded with the App Launch template (`xcrun xctrace record --template 'App Launch' --launch <bundleId>`)."),
+    outputFormat: outputFormatField,
 });
 /** Phases Apple breaks app launch into, ordered by occurrence. */
 const PHASE_ORDER = [

package/dist/tools/analyzeAppLaunch.js.map

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

package/dist/tools/analyzeHangs.d.ts

@@ -1,18 +1,82 @@
 import { z } from "zod";
+import type { DataStatus } from "../types.js";
 export declare const analyzeHangsSchema: z.ZodObject<{
     tracePath: z.ZodString;
     topN: z.ZodDefault<z.ZodNumber>;
     minDurationMs: z.ZodDefault<z.ZodNumber>;
+    timeRangeMs: z.ZodOptional<z.ZodObject<{
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        startMs: number;
+        endMs: number;
+    }, {
+        startMs: number;
+        endMs: number;
+    }>>;
+    topFramesByHangStartNs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
 }, "strip", z.ZodTypeAny, {
-    topN: number;
     tracePath: string;
+    topN: number;
     minDurationMs: number;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+    timeRangeMs?: {
+        startMs: number;
+        endMs: number;
+    } | undefined;
+    topFramesByHangStartNs?: Record<string, string> | undefined;
 }, {
     tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
     topN?: number | undefined;
     minDurationMs?: number | undefined;
+    timeRangeMs?: {
+        startMs: number;
+        endMs: number;
+    } | undefined;
+    topFramesByHangStartNs?: Record<string, string> | undefined;
 }>;
 export type AnalyzeHangsInput = z.infer<typeof analyzeHangsSchema>;
+/**
+ * Catalog of main-thread-violation signatures. Each entry classifies a
+ * top-frame symbol pattern into one of four kinds that map onto the most
+ * common iOS user-perceived freezes:
+ *
+ *  - `sync-io`: a blocking POSIX read/write or Foundation file API the
+ *    runtime cannot async away from the main queue.
+ *  - `db-lock`: SQLite mutex acquisition (the underlying primitive for
+ *    Core Data, GRDB, and most Swift ORMs).
+ *  - `network`: a blocking Network.framework/NSURLConnection sync call.
+ *  - `lock-contention`: pthread/os_unfair_lock acquisition on the main
+ *    thread, which serializes us against another thread.
+ *
+ * The matchers are case-sensitive substring checks. They deliberately
+ * stay close to the symbol name DebugSwift's Thread Checker flags so the
+ * coverage gap between the on-device tool and the offline catalog stays
+ * small. Adding new symbols later is a one-line append.
+ */
+export type MainThreadViolationKind = "sync-io" | "db-lock" | "network" | "lock-contention";
+export interface MainThreadViolation {
+    kind: MainThreadViolationKind;
+    topFrame: string;
+    samples: number;
+}
+/**
+ * Pure: classify a top-frame symbol into a `MainThreadViolation`. Returns
+ * `null` when nothing in the catalog matches. The `samples` count comes
+ * from the caller; with only a top-frame string available we set it to 1.
+ *
+ * Multiple signatures can match a single frame (e.g. a sync I/O call that
+ * also holds an unfair lock). We return the FIRST match in catalog order,
+ * which puts more user-actionable categories ahead of generic locks.
+ */
+export declare function classifyHangFrame(topFrame: string, samples?: number): MainThreadViolation | null;
+/** Stable key used to correlate the supplemental `topFramesByHangStartNs`
+ *  map. Hang startNs values are nanoseconds (integers when xctrace exports
+ *  them cleanly), so the key is just `String(startNs)`. Centralized so
+ *  callers building the map use the same convention. */
+export declare function hangFrameMapKey(startNs: number): string;
 export interface HangEntry {
     startNs: number;
     startFmt: string;
@@ -20,6 +84,10 @@ export interface HangEntry {
     durationMs: number;
     durationFmt: string;
     hangType: string;
+    /** Main-thread violations detected from the supplemental top-frame map.
+     *  Empty array when the caller provided a frame but no signature matched;
+     *  undefined when no frame was provided for this hang at all. */
+    mainThreadViolations?: MainThreadViolation[];
 }
 export interface AnalyzeHangsResult {
     ok: boolean;
@@ -35,7 +103,15 @@ export interface AnalyzeHangsResult {
     /** Filtered + sorted hangs, capped to topN. */
     top: HangEntry[];
     diagnosis: string;
+    /**
+     * Disambiguates empty arrays into "no data in the trace" vs "trace could
+     * not be exported" vs "data was exported partially". See {@link DataStatus}.
+     */
+    status: DataStatus;
 }
 /** Pure: turn parsed XML rows into our analyzed result. */
-export declare function analyzeHangsFromXml(xml: string, tracePath: string, topN?: number, minDurationMs?: number): AnalyzeHangsResult;
+export declare function analyzeHangsFromXml(xml: string, tracePath: string, topN?: number, minDurationMs?: number, timeRangeMs?: {
+    startMs: number;
+    endMs: number;
+}, topFramesByHangStartNs?: Readonly<Record<string, string>>): AnalyzeHangsResult;
 export declare function analyzeHangs(input: AnalyzeHangsInput): Promise<AnalyzeHangsResult>;

package/dist/tools/analyzeHangs.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { runCommand } from "../runtime/exec.js";
 import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
 export const analyzeHangsSchema = z.object({
     tracePath: z
         .string()
@@ -18,10 +19,97 @@ export const analyzeHangsSchema = z.object({
         .number()
         .nonnegative()
         .default(0)
-        .describe("Filter out hangs shorter than this duration in milliseconds (default 0 — include all). Use 250 to focus on \"real\" hangs only."),
+        .describe("Filter out hangs shorter than this duration in milliseconds (default 0, include all). Use 250 to focus on 'real' hangs only."),
+    timeRangeMs: z
+        .object({
+        startMs: z.number().nonnegative(),
+        endMs: z.number().nonnegative(),
+    })
+        .optional()
+        .describe("Optional time-window filter. Only hangs whose `startNs` falls within `[startMs, endMs]` (milliseconds since recording start) are included. Use this to answer 'what hangs happened between t=2s and t=7s?' without re-recording."),
+    topFramesByHangStartNs: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Optional supplemental map from a hang's `startNs` (as a string) to the top frame seen during that hang. When provided, each matching hang in `top[]` is enriched with `mainThreadViolations[]` that catalog the kind of work happening on the main thread (sync-io, db-lock, network, lock-contention). Typical pipeline: call `analyzeTimeProfile` separately on the same `.trace`, correlate samples to hang windows by timestamp, then re-call `analyzeHangs` with the resulting map. Omit to skip the enrichment."),
+    outputFormat: outputFormatField,
 });
+const MAIN_THREAD_VIOLATION_SIGNATURES = [
+    // sync-io: POSIX read/write and Foundation/NSData blocking APIs.
+    // Foundation often calls through to the libsystem symbols below, but
+    // dSYM symbolication can land on either, so match both.
+    {
+        kind: "sync-io",
+        matches: (f) => /\b(read|pread|readv|write|pwrite|writev|fsync|fdatasync|aio_read|aio_write)\b/.test(f) ||
+            f.includes("Data initWithContentsOfFile") ||
+            f.includes("NSData _initWithContentsOfURL") ||
+            f.includes("FileHandle readDataOfLength") ||
+            f.includes("FileManager createFileAtPath") ||
+            f.includes("FileManager removeItem"),
+    },
+    // db-lock: SQLite mutex acquisition. Triggers under Core Data, GRDB,
+    // SQLite.swift, FMDB - any client that funnels through libsqlite3.
+    {
+        kind: "db-lock",
+        matches: (f) => f.includes("sqlite3_step") ||
+            f.includes("sqlite3_prepare") ||
+            f.includes("sqlite3_mutex_enter") ||
+            f.includes("sqlite3LockAndPrepare") ||
+            f.includes("pagerSharedLock") ||
+            f.includes("NSPersistentStoreCoordinator lock") ||
+            f.includes("NSManagedObjectContext save"),
+    },
+    // network: blocking Network.framework / legacy NSURLConnection sync
+    // call, or +[NSURLConnection sendSynchronousRequest:returningResponse:].
+    {
+        kind: "network",
+        matches: (f) => f.includes("sendSynchronousRequest") ||
+            f.includes("NSURLConnection sendSynchronousRequest") ||
+            f.includes("URLSession dataTaskWithRequest") ||
+            // CFNetwork sync path.
+            f.includes("CFReadStreamRead") ||
+            // Network.framework sync wait.
+            /\bnw_connection_(start|wait)\b/.test(f),
+    },
+    // lock-contention: pthread / os_unfair_lock acquisition on the main
+    // thread that blocks waiting for another thread.
+    {
+        kind: "lock-contention",
+        matches: (f) => f.includes("pthread_mutex_lock") ||
+            f.includes("pthread_rwlock_wrlock") ||
+            f.includes("pthread_rwlock_rdlock") ||
+            f.includes("os_unfair_lock_lock") ||
+            f.includes("dispatch_semaphore_wait") ||
+            f.includes("dispatch_sync") ||
+            f.includes("NSConditionLock lockWhenCondition") ||
+            f.includes("NSLock lock"),
+    },
+];
+/**
+ * Pure: classify a top-frame symbol into a `MainThreadViolation`. Returns
+ * `null` when nothing in the catalog matches. The `samples` count comes
+ * from the caller; with only a top-frame string available we set it to 1.
+ *
+ * Multiple signatures can match a single frame (e.g. a sync I/O call that
+ * also holds an unfair lock). We return the FIRST match in catalog order,
+ * which puts more user-actionable categories ahead of generic locks.
+ */
+export function classifyHangFrame(topFrame, samples = 1) {
+    for (const sig of MAIN_THREAD_VIOLATION_SIGNATURES) {
+        if (sig.matches(topFrame)) {
+            return { kind: sig.kind, topFrame, samples };
+        }
+    }
+    return null;
+}
+/** Stable key used to correlate the supplemental `topFramesByHangStartNs`
+ *  map. Hang startNs values are nanoseconds (integers when xctrace exports
+ *  them cleanly), so the key is just `String(startNs)`. Centralized so
+ *  callers building the map use the same convention. */
+export function hangFrameMapKey(startNs) {
+    return String(startNs);
+}
 /** Pure: turn parsed XML rows into our analyzed result. */
-export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0) {
+export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0, timeRangeMs, topFramesByHangStartNs) {
     const tables = parseXctraceXml(xml);
     const hangsTable = tables.find((t) => t.schema === "potential-hangs");
     if (!hangsTable) {
@@ -38,6 +126,7 @@ export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0
             },
             top: [],
             diagnosis: "No potential-hangs table found in the trace.",
+            status: "not_present",
         };
     }
     const allEntries = [];
@@ -53,7 +142,17 @@ export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0
             hangType: asFormatted(row["hang-type"]) ?? "",
         });
     }
-    const filtered = allEntries.filter((e) => e.durationMs >= minDurationMs);
+    const filtered = allEntries.filter((e) => {
+        if (e.durationMs < minDurationMs)
+            return false;
+        if (timeRangeMs) {
+            const startMs = e.startNs / 1_000_000;
+            if (startMs < timeRangeMs.startMs || startMs > timeRangeMs.endMs) {
+                return false;
+            }
+        }
+        return true;
+    });
     const hangs = filtered.filter((e) => e.hangType === "Hang");
     const microhangs = filtered.filter((e) => e.hangType === "Microhang");
     const totalDurationMs = filtered.reduce((sum, e) => sum + e.durationMs, 0);
@@ -62,6 +161,19 @@ export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0
     const top = [...filtered]
         .sort((a, b) => b.durationMs - a.durationMs)
         .slice(0, topN);
+    // Enrich each top hang with main-thread violation classifications when
+    // the supplemental top-frame map was supplied. We mutate the cloned
+    // entries in `top` because they are not aliased back into `filtered`
+    // after the spread above.
+    if (topFramesByHangStartNs) {
+        for (const entry of top) {
+            const frame = topFramesByHangStartNs[hangFrameMapKey(entry.startNs)];
+            if (frame == null)
+                continue;
+            const violation = classifyHangFrame(frame);
+            entry.mainThreadViolations = violation ? [violation] : [];
+        }
+    }
     const diagnosis = buildHangDiagnosis(filtered.length, hangs.length, microhangs.length, longestMs, averageMs);
     return {
         ok: true,
@@ -76,6 +188,7 @@ export function analyzeHangsFromXml(xml, tracePath, topN = 10, minDurationMs = 0
         },
         top,
         diagnosis,
+        status: "available",
     };
 }
 function buildHangDiagnosis(rows, hangs, microhangs, longestMs, averageMs) {
@@ -109,6 +222,6 @@ export async function analyzeHangs(input) {
     if (result.code !== 0) {
         throw new Error(`xctrace export failed (code ${result.code}): ${result.stderr || result.stdout}`);
     }
-    return analyzeHangsFromXml(result.stdout, tracePath, input.topN ?? 10, input.minDurationMs ?? 0);
+    return analyzeHangsFromXml(result.stdout, tracePath, input.topN ?? 10, input.minDurationMs ?? 0, input.timeRangeMs, input.topFramesByHangStartNs);
 }
 //# sourceMappingURL=analyzeHangs.js.map

package/dist/tools/analyzeHangs.js.map

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

package/dist/tools/analyzeMemgraph.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type ReferenceTreeEntry } from "../parsers/referenceTree.js";
 import { type Verbosity } from "../parsers/shortenClassName.js";
 import type { LeaksReport, NextCallSuggestion } from "../types.js";
 export declare const analyzeMemgraphSchema: z.ZodObject<{
@@ -6,16 +7,22 @@ export declare const analyzeMemgraphSchema: z.ZodObject<{
     fullChains: z.ZodDefault<z.ZodBoolean>;
     verbosity: z.ZodDefault<z.ZodEnum<["compact", "normal", "full"]>>;
     maxClassesInChain: z.ZodDefault<z.ZodNumber>;
+    referenceTreeTopN: z.ZodDefault<z.ZodNumber>;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
 }, "strip", z.ZodTypeAny, {
     path: string;
     fullChains: boolean;
     verbosity: "compact" | "normal" | "full";
     maxClassesInChain: number;
+    referenceTreeTopN: number;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
 }, {
     path: string;
     fullChains?: boolean | undefined;
     verbosity?: "compact" | "normal" | "full" | undefined;
     maxClassesInChain?: number | undefined;
+    referenceTreeTopN?: number | undefined;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
 }>;
 export type AnalyzeMemgraphInput = z.infer<typeof analyzeMemgraphSchema>;
 export interface CycleSummary {
@@ -57,8 +64,40 @@ export interface AnalyzeMemgraphResult {
     fullReport?: LeaksReport;
     /** Plain-English diagnosis (one liner). */
     diagnosis: string;
-    /** Pipeline hints — chain `classifyCycle` next, then `reachableFromCycle` to scope blame. */
+    /** Pipeline hints. Chain `classifyCycle` next, then `reachableFromCycle` to scope blame. */
     suggestedNextCalls?: NextCallSuggestion[];
+    /**
+     * Top live classes by instance count from the heap reference tree.
+     * Populated when `leakCount` is 0 and `referenceTreeTopN > 0`. Surfaces
+     * the abandoned-memory shape that the standard `leaks` count misses:
+     * objects that are technically reachable (so not "leaked" in the strict
+     * sense) but whose growth across repeated workflows indicates a real
+     * accumulation bug (KVO observers not invalidated, NotificationCenter
+     * observers leaked, caches that never evict, etc.). These classes are
+     * not formal leaks; they are reachable-but-suspicious and worth diffing
+     * against a baseline via `analyzeAbandonedMemory(before, after)` for
+     * the verdict.
+     *
+     * **Raw view.** Includes framework noise (NSMutableDictionary, CFString,
+     * libMainThreadChecker bss, etc.) that grows with normal app activity
+     * and is rarely the actionable leak. Useful for cache-bloat or
+     * collection-explosion investigations.
+     */
+    abandonedMemoryTop?: ReferenceTreeEntry[];
+    /**
+     * Same top-N reference-tree analysis as `abandonedMemoryTop` but filtered
+     * to actionable classes only. Foundation collection types (NSMutableDictionary,
+     * CFString, ...), ObjC runtime metadata (Class.data, OBJC_METACLASS_),
+     * Apple-framework static-data sections (__DATA __bss / __data / __common),
+     * Stack of thread / non-object / VM region rows, and the `<<TOTAL>>`
+     * summary are all excluded. The remaining list surfaces AV*, KVO*,
+     * SwiftUI app-level types, user-named classes, and other classes the
+     * fix would actually live in. New in v1.10.
+     *
+     * Use this list for the "what should I worry about?" question; use
+     * `abandonedMemoryTop` for "what's the full heap distribution?".
+     */
+    abandonedMemorySuspects?: ReferenceTreeEntry[];
 }
 /**
  * Pure function: take a `leaks` stdout string and a source path, produce a structured analysis.

package/dist/tools/analyzeMemgraph.js

@@ -3,6 +3,8 @@ import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { runCommand } from "../runtime/exec.js";
 import { parseLeaksOutput, rootCyclesOnly } from "../parsers/leaksOutput.js";
+import { parseReferenceTreeText, isFrameworkNoise, } from "../parsers/referenceTree.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
 import { shortenForVerbosity, } from "../parsers/shortenClassName.js";
 import { suggestionClassifyCycle, suggestionReachableFromCycle, } from "../runtime/suggestions.js";
 export const analyzeMemgraphSchema = z.object({
@@ -24,7 +26,15 @@ export const analyzeMemgraphSchema = z.object({
         .positive()
         .max(50)
         .default(10)
-        .describe("Cap on how many unique class names to surface per cycle's `classesInChain` array. Default 10 — enough to identify app-level types without flooding the response."),
+        .describe("Cap on how many unique class names to surface per cycle's `classesInChain` array. Default 10, enough to identify app-level types without flooding the response."),
+    referenceTreeTopN: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(200)
+        .default(20)
+        .describe("When `leakCount` is 0 (the typical abandoned-memory case), also run `leaks --referenceTree --groupByType --noContent` and surface the top N classes by live instance count in `abandonedMemoryTop[]`. Set to 0 to skip the second leaks invocation. Default 20."),
+    outputFormat: outputFormatField,
 });
 /**
  * Pure function: take a `leaks` stdout string and a source path, produce a structured analysis.
@@ -130,6 +140,60 @@ export async function analyzeMemgraph(input) {
     if (result.code !== 0 && result.code !== 1) {
         throw new Error(`leaks failed (code ${result.code}): ${result.stderr || result.stdout}`);
     }
-    return summarizeLeaks(result.stdout, path, input.fullChains ?? false, input.verbosity ?? "compact", input.maxClassesInChain ?? 10);
+    const summary = summarizeLeaks(result.stdout, path, input.fullChains ?? false, input.verbosity ?? "compact", input.maxClassesInChain ?? 10);
+    // Abandoned-memory surface: when `leaks` finds zero leaks, the reference
+    // tree still carries information about what the heap is holding alive.
+    // This is the only signal for the "orphaned KVO observer" / "abandoned
+    // cache" class of bugs that don't form a closed cycle. We invoke a second
+    // leaks pass with `--referenceTree --groupByType --noContent` and rank
+    // classes by live instance count. The caller can then chain into
+    // `analyzeAbandonedMemory(before, after)` to confirm growth shape across
+    // a workflow.
+    const topN = input.referenceTreeTopN ?? 20;
+    if (summary.totals.leakCount === 0 && topN > 0) {
+        // Capture a much larger pool than `topN` so that after filtering for
+        // the actionable view (`abandonedMemorySuspects`), we still have enough
+        // entries to surface the user-relevant classes that would otherwise
+        // be ranked below framework noise in the raw view. The notelet
+        // investigation showed AVPlayerItem at raw rank ~82 in a ~200-class
+        // heap; 10x of a 20-element default reliably surfaces classes ranked
+        // outside the raw top 20 after the noise filter trims the leaders.
+        const captureTopN = Math.max(topN, topN * 10, 200);
+        const rawTop = await captureReferenceTreeTop(path, captureTopN);
+        if (rawTop.length > 0) {
+            // Raw view: first `topN` entries unchanged from existing behavior.
+            summary.abandonedMemoryTop = rawTop.slice(0, topN);
+            // Filtered view: drop framework noise, keep ranking, then trim to topN.
+            const filtered = rawTop.filter((e) => !isFrameworkNoise(e.className));
+            if (filtered.length > 0) {
+                summary.abandonedMemorySuspects = filtered.slice(0, topN);
+            }
+        }
+    }
+    return summary;
+}
+/**
+ * Spawn a second `leaks` invocation with the reference-tree flags and parse
+ * the top N classes by instance count. Exposed as a helper so the
+ * integration is testable without spawning, by passing a precomputed
+ * stdout via the pure `parseReferenceTreeText` directly.
+ *
+ * Failure here is non-fatal: if leaks fails on the second invocation, we
+ * return an empty array rather than throwing, so the main analyze result
+ * is still returned to the caller. The most likely failure path is the
+ * same macOS 26.x kernel regression that hit the first invocation, which
+ * would already be surfaced via the earlier captureMemgraph step.
+ */
+async function captureReferenceTreeTop(path, topN) {
+    try {
+        const result = await runCommand("leaks", [path, "--referenceTree", "--groupByType", "--noContent"], { timeoutMs: 5 * 60_000 });
+        if (result.code !== 0 && result.code !== 1) {
+            return [];
+        }
+        return parseReferenceTreeText(result.stdout, topN);
+    }
+    catch {
+        return [];
+    }
 }
 //# sourceMappingURL=analyzeMemgraph.js.map