next-leak 0.12.1 → 0.13.0

package/dist/bootstrap.js

@@ -1,100 +1,15 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
+import {
+  requestProbe,
+  startControlServer
+} from "./chunk-IKWF7SSB.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/bootstrap.ts
 import { mkdir, writeFile } from "fs/promises";
-import http2 from "http";
-import https from "https";
-import path2 from "path";
-
-// src/control-server.ts
 import http from "http";
+import https from "https";
 import path from "path";
-import { writeHeapSnapshot } from "v8";
-var g = globalThis;
-var tick = () => new Promise((resolve) => setImmediate(resolve));
-async function forceGc(passes = 3) {
-  if (typeof g.gc !== "function") {
-    return false;
-  }
-  for (let i = 0; i < passes; i += 1) {
-    g.gc();
-    await tick();
-  }
-  return true;
-}
-var requestProbe = globalThis;
-function sampleMemory(gcExposed) {
-  const usage = process.memoryUsage();
-  return {
-    gcExposed,
-    heapUsed: usage.heapUsed,
-    rss: usage.rss,
-    external: usage.external,
-    arrayBuffers: usage.arrayBuffers,
-    pid: process.pid,
-    ppid: process.ppid,
-    argv: process.argv,
-    cwd: process.cwd(),
-    ...requestProbe.__nextLeakServedRequests === void 0 ? {} : { servedRequests: requestProbe.__nextLeakServedRequests }
-  };
-}
-async function startControlServer(options) {
-  const write = options.writeSnapshot ?? writeHeapSnapshot;
-  const server = http.createServer((request, response) => {
-    void handle(request, response);
-  });
-  async function handle(request, response) {
-    const url = new URL(request.url ?? "/", "http://control.local");
-    const respond = (status, body) => {
-      response.writeHead(status, { "content-type": "application/json" });
-      response.end(JSON.stringify(body));
-    };
-    try {
-      if (url.pathname === "/gc") {
-        const gcExposed = await forceGc();
-        respond(200, sampleMemory(gcExposed));
-        return;
-      }
-      if (url.pathname === "/mem") {
-        respond(200, sampleMemory(typeof g.gc === "function"));
-        return;
-      }
-      if (url.pathname === "/snapshot") {
-        const name = url.searchParams.get("name");
-        if (name === null || name === "") {
-          respond(400, { error: "missing ?name=<label>" });
-          return;
-        }
-        const gcExposed = await forceGc();
-        const sample = sampleMemory(gcExposed);
-        const file = write(
-          path.join(options.snapshotDir, `${path.basename(name)}.heapsnapshot`)
-        );
-        respond(200, { file, sample });
-        return;
-      }
-      respond(404, { error: `unknown path ${url.pathname}` });
-    } catch (cause) {
-      respond(500, { error: cause instanceof Error ? cause.message : String(cause) });
-    }
-  }
-  await new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", resolve);
-  });
-  server.unref();
-  const address = server.address();
-  if (address === null || typeof address === "string") {
-    throw new Error("control server has no bound port");
-  }
-  return {
-    port: address.port,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    })
-  };
-}
 
 // src/request-probe.ts
 function countServedRequests(module) {
@@ -110,18 +25,22 @@ function countServedRequests(module) {
 
 // src/bootstrap.ts
 var workDir = process.env["NEXT_LEAK_DIR"];
+var token = process.env["NEXT_LEAK_TOKEN"];
 function installRequestProbe() {
   requestProbe.__nextLeakServedRequests = 0;
-  countServedRequests(http2);
+  countServedRequests(http);
   countServedRequests(https);
 }
 if (workDir !== void 0 && workDir !== "") {
   try {
     await mkdir(workDir, { recursive: true });
-    const server = await startControlServer({ snapshotDir: workDir });
+    if (token === void 0 || token === "") {
+      throw new Error("NEXT_LEAK_TOKEN is not set, and the channel does not start without it");
+    }
+    const server = await startControlServer({ snapshotDir: workDir, token });
     installRequestProbe();
     await writeFile(
-      path2.join(workDir, `control-${process.pid}.json`),
+      path.join(workDir, `control-${process.pid}.json`),
       JSON.stringify({ port: server.port, pid: process.pid })
     );
   } catch (cause) {

package/dist/build-attribution.d.ts

@@ -15,6 +15,26 @@ export type BuildAttribution = {
     baselineFile: string;
     afterFile: string;
 };
+/**
+ * Why a run that asked for attribution came back without one.
+ *
+ * An absent section and a failed diff read the same in a report, and they are
+ * opposite findings: one says nobody asked what the worker retained, the other
+ * says the question was asked and the evidence could not be read. The build
+ * path fails this way hardest on the builds worth measuring — a snapshot past
+ * roughly a gigabyte of worker rss cannot be parsed back, so the bigger the
+ * build grew, the likelier the report says nothing about what grew.
+ */
+export type BuildAttributionGap = {
+    /**
+     * `capture-missed`: the run was told to capture and never got a usable pair.
+     * `snapshot-unreadable`: the pair exists and the diff refused it.
+     */
+    reason: "capture-missed" | "snapshot-unreadable";
+    detail: string;
+};
+/** Narrows the outcome of `attributeBuildCapture`. */
+export declare function isAttributionGap(outcome: BuildAttribution | BuildAttributionGap | null): outcome is BuildAttributionGap;
 export type BuildAttributionDeps = {
     diff: typeof diffSnapshotFiles;
     registry: typeof extractModuleRegistry;
@@ -22,12 +42,14 @@ export type BuildAttributionDeps = {
 /**
  * Names what a build's worker retained, from the pair the run captured.
  *
- * Returns null rather than throwing on every failure path. A build measurement
- * stands on its curve and its verdict; this is an addition to the report, and
- * an addition that can fail must not be able to take the report with it.
+ * Never throws on a failure path. A build measurement stands on its curve and
+ * its verdict; this is an addition to the report, and an addition that can
+ * fail must not be able to take the report with it. It returns a gap instead,
+ * so the report can tell a question nobody asked from one it could not answer.
+ * Null is reserved for the run that never asked.
  *
  * The registry is read from `.next/server` *after* the build, never during it:
  * a half-written chunk can resolve a module id to the wrong source, and naming
  * the wrong owner confidently is worse than naming none.
  */
-export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | null>;
+export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | BuildAttributionGap | null>;

package/dist/build-report.d.ts

@@ -1,12 +1,8 @@
-import type { BuildAttribution } from "./build-attribution.js";
+import { type BuildAttribution, type BuildAttributionGap } from "./build-attribution.js";
 import type { BuildRunResult } from "./build-run.js";
 /**
- * Renders the build report.
- *
- * Says "worker rss" everywhere rather than "heap" or "retained": these samples
- * are resident memory with no forced collection behind them, and calling them
- * retention would borrow a precision the measurement does not have. RSS is
- * still the honest axis here — it is what a CI runner's limit is enforced
- * against and what the OOM killer reads.
+ * The report as it is written to the terminal. The build's output and the
+ * names in the attribution come from the measured app, so the text goes
+ * through `terminalSafe` whichever branch produced it.
  */
-export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | null): string;
+export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | BuildAttributionGap | null): string;

package/dist/build-run.d.ts

@@ -51,6 +51,15 @@ export type BuildRunResult = {
      * produced whether or not capture worked.
      */
     capture: BuildCapture | null;
+    /**
+     * Whether this run was asked to capture at all. Without it a null `capture`
+     * is ambiguous — nobody asked, or it was asked and missed — and the report
+     * has to choose between staying silent on a lost measurement and nagging
+     * every run that never wanted one.
+     */
+    captureRequested: boolean;
+    /** How far capture got before giving up, when it was requested and missed. */
+    captureFailure: string | null;
     strippedCapWarning: string | null;
     exitCode: number | null;
     output: string;

package/dist/{chunk-YPVBX3QA.js → chunk-FJVY5MKV.js}

@@ -3,32 +3,55 @@ import {
   assessPeakPressure,
   describePeakPressure,
   retainedAfterLoad
-} from "./chunk-E464SO7G.js";
+} from "./chunk-VTKOO3YJ.js";
 
 // src/issue-report.ts
 import path from "path";
 var MB = 1024 * 1024;
+function codeSpan(text) {
+  const flat = text.replaceAll(/[\r\n]+/g, " ");
+  const longestRun = Math.max(0, ...[...flat.matchAll(/`+/g)].map((run) => run[0].length));
+  const fence = "`".repeat(longestRun + 1);
+  const padding = flat.startsWith("`") || flat.endsWith("`") ? " " : "";
+  return `${fence}${padding}${flat}${padding}${fence}`;
+}
+function publicWorkDir(run) {
+  const relative = path.relative(run.appDir, run.workDir);
+  return relative.startsWith("..") || path.isAbsolute(relative) ? path.basename(run.workDir) : relative;
+}
 function ownerLabel(attribution) {
   if (attribution === void 0 || attribution.owner === "unattributed") {
     return "unattributed";
   }
-  const source = attribution.source ? ` \u2014 \`${attribution.source}\`` : "";
-  const packageName = attribution.packageName ? ` \u2014 ${attribution.packageName}` : "";
+  const source = attribution.source ? ` \u2014 ${codeSpan(attribution.source)}` : "";
+  const packageName = attribution.packageName ? ` \u2014 ${codeSpan(attribution.packageName)}` : "";
   return `${attribution.owner}${source}${packageName}`;
 }
+function publicDetail(detail, run) {
+  return detail.replaceAll(run.workDir, publicWorkDir(run)).replaceAll(run.appDir, "<app-dir>").replaceAll(/[\r\n]+/g, " ");
+}
 function blamedParty(owner, culprit) {
   if (owner === "app") {
-    return `**your own code** (\`${culprit?.source ?? "app code"}\`)`;
+    return `**your own code** (${codeSpan(culprit?.source ?? "app code")})`;
+  }
+  const packageName = culprit?.packageName;
+  return `the dependency **${packageName ? codeSpan(packageName) : "a dependency"}**`;
+}
+function missingEvidence(route, run) {
+  if (route.attributionGap === void 0) {
+    return "- (no findings above thresholds)";
   }
-  return `the dependency **${culprit?.packageName ?? "a dependency"}**`;
+  const cause = route.attributionGap.reason === "snapshot-unavailable" ? "the final heap snapshot was never taken" : "the heap snapshots could not be read";
+  return `- **Attribution unavailable** \u2014 ${cause}, so this run cannot name what retains the memory. This is not a finding that nothing grew: the diff was never computed. The growth figure above is unaffected.
+  - ${publicDetail(route.attributionGap.detail, run)}`;
 }
 function evidenceRows(route) {
   const findings = [...route.diff?.grownNodes ?? [], ...route.diff?.newNodes ?? []];
   return findings.slice(0, 6).map((finding, index) => {
     const attribution = route.attribution?.findings[index];
     const owner = ownerLabel(attribution);
-    return `- **${finding.kind}** \`[${finding.nodeType}] ${finding.name}\` ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
-  - retainers: \`${finding.retainerChain || "(none)"}\``;
+    return `- **${finding.kind}** ${codeSpan(`[${finding.nodeType}] ${finding.name}`)} ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
+  - retainers: ${codeSpan(finding.retainerChain || "(none)")}`;
   }).join("\n");
 }
 function renderIssueMarkdown(route, run) {
@@ -71,7 +94,7 @@ Sampled during the load phases, without forcing collection: ${describePeakPressu
   const signatures = route.signatures.map(
     (signature) => `- ${signature.historical ? "(historical) " : ""}${signature.title} \u2014 ${signature.issue}`
   ).join("\n");
-  return `${preamble}${cacheDisclosure}# Memory leak on route \`${route.route}\`
+  return `${preamble}${cacheDisclosure}# Memory leak on route ${codeSpan(route.route)}
 
 Report generated by \`next-leak\` \u2014 every number below is reproducible from
 the raw heap snapshots referenced at the bottom.
@@ -93,7 +116,7 @@ Deployment: output "standalone", node --expose-gc --max-old-space-size=${paramet
    \`\`\`
    npx next-leak <app-dir>
    \`\`\`
-2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against \`${route.requestPath}\`:
+2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against ${codeSpan(route.requestPath)}:
    warm-up ${parameters.warmupRequests} requests \u2192 forced GC \u2192 baseline heap snapshot \u2192
    ${parameters.cycles} \xD7 [${parameters.loadRequests} requests at ${parameters.connections} connections \u2192 ${(parameters.idleMs / 1e3).toFixed(0)}s idle \u2192 forced GC \u2192 post-GC sample] \u2192 final snapshot.
 3. A cycle counts as growing when it retains at least ${(parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB
@@ -109,7 +132,7 @@ The first cycle is excluded from the verdict (engine warm-up).
 
 ### Heap evidence
 
-${evidenceRows(route) || "- (no findings above thresholds)"}
+${evidenceRows(route) || missingEvidence(route, run)}
 ${signatures === "" ? "" : `
 **Matched known causes:**
 ${signatures}
@@ -118,7 +141,7 @@ ${signatures}
 
 Raw snapshots (Chrome DevTools \u2192 Memory \u2192 Load, compare baseline vs after):
 
-- \`${path.basename(route.baselineSnapshot)}\` / \`${path.basename(route.afterSnapshot)}\` in \`${run.workDir}\`
+- ${codeSpan(path.basename(route.baselineSnapshot))} / ${codeSpan(path.basename(route.afterSnapshot))} in ${codeSpan(publicWorkDir(run))}
 - machine-readable data: \`run.json\`, curves: \`report.html\`
 `;
 }

package/dist/chunk-IKWF7SSB.js

@@ -0,0 +1,114 @@
+import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
+
+// src/control-server.ts
+import { timingSafeEqual } from "crypto";
+import http from "http";
+import path from "path";
+import { writeHeapSnapshot } from "v8";
+var g = globalThis;
+var tick = () => new Promise((resolve) => setImmediate(resolve));
+async function forceGc(passes = 3) {
+  if (typeof g.gc !== "function") {
+    return false;
+  }
+  for (let i = 0; i < passes; i += 1) {
+    g.gc();
+    await tick();
+  }
+  return true;
+}
+var requestProbe = globalThis;
+function sampleMemory(gcExposed) {
+  const usage = process.memoryUsage();
+  return {
+    gcExposed,
+    heapUsed: usage.heapUsed,
+    rss: usage.rss,
+    external: usage.external,
+    arrayBuffers: usage.arrayBuffers,
+    pid: process.pid,
+    ppid: process.ppid,
+    argv: process.argv,
+    cwd: process.cwd(),
+    ...requestProbe.__nextLeakServedRequests === void 0 ? {} : { servedRequests: requestProbe.__nextLeakServedRequests }
+  };
+}
+var CONTROL_TOKEN_HEADER = "x-next-leak-token";
+async function startControlServer(options) {
+  if (options.token === "") {
+    throw new Error("the control server needs a token and was given an empty one");
+  }
+  const write = options.writeSnapshot ?? writeHeapSnapshot;
+  const expected = Buffer.from(options.token);
+  const carriesToken = (request) => {
+    const header = request.headers[CONTROL_TOKEN_HEADER];
+    if (typeof header !== "string") {
+      return false;
+    }
+    const given = Buffer.from(header);
+    return given.length === expected.length && timingSafeEqual(given, expected);
+  };
+  const server = http.createServer((request, response) => {
+    void handle(request, response);
+  });
+  async function handle(request, response) {
+    const url = new URL(request.url ?? "/", "http://control.local");
+    const respond = (status, body) => {
+      response.writeHead(status, { "content-type": "application/json" });
+      response.end(JSON.stringify(body));
+    };
+    if (!carriesToken(request)) {
+      respond(403, { error: `missing or wrong ${CONTROL_TOKEN_HEADER} header` });
+      return;
+    }
+    try {
+      if (url.pathname === "/gc") {
+        const gcExposed = await forceGc();
+        respond(200, sampleMemory(gcExposed));
+        return;
+      }
+      if (url.pathname === "/mem") {
+        respond(200, sampleMemory(typeof g.gc === "function"));
+        return;
+      }
+      if (url.pathname === "/snapshot") {
+        const name = url.searchParams.get("name");
+        if (name === null || name === "") {
+          respond(400, { error: "missing ?name=<label>" });
+          return;
+        }
+        const gcExposed = await forceGc();
+        const sample = sampleMemory(gcExposed);
+        const file = write(
+          path.join(options.snapshotDir, `${path.basename(name)}.heapsnapshot`)
+        );
+        respond(200, { file, sample });
+        return;
+      }
+      respond(404, { error: `unknown path ${url.pathname}` });
+    } catch (cause) {
+      respond(500, { error: cause instanceof Error ? cause.message : String(cause) });
+    }
+  }
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  server.unref();
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("control server has no bound port");
+  }
+  return {
+    port: address.port,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    })
+  };
+}
+
+export {
+  requestProbe,
+  CONTROL_TOKEN_HEADER,
+  startControlServer
+};

package/dist/{chunk-UU4RXOZO.js → chunk-QUFL2FXU.js}

@@ -40,7 +40,7 @@ function isSaturating(deltas, minGrowth) {
   if (first === void 0 || last === void 0 || first < minGrowth) {
     return false;
   }
-  if (!deltas.every((delta) => delta > 0)) {
+  if (!hasArrivedWithoutResuming(deltas, minGrowth)) {
     return false;
   }
   if (last > first * SATURATION_MAX_FINAL_RATIO) {
@@ -48,6 +48,17 @@ function isSaturating(deltas, minGrowth) {
   }
   return isHeadingDown(deltas);
 }
+function hasArrivedWithoutResuming(deltas, minGrowth) {
+  const stop = deltas.findIndex((delta) => delta <= 0);
+  if (stop === -1) {
+    return true;
+  }
+  const approach = deltas[stop - 1];
+  if (approach === void 0 || approach >= minGrowth) {
+    return false;
+  }
+  return deltas.slice(stop).every((delta) => delta < minGrowth);
+}
 function isHeadingDown(deltas) {
   const midpoint = Math.floor(deltas.length / 2);
   const head = deltas.slice(0, midpoint);

package/dist/{chunk-L5KWU2RU.js → chunk-UKWFONEI.js}

@@ -1,4 +1,7 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
+import {
+  CONTROL_TOKEN_HEADER
+} from "./chunk-IKWF7SSB.js";
 import {
   assessConfidence,
   classifyMemoryTrend,
@@ -8,13 +11,13 @@ import {
   resolveCycles,
   warrantsIssueDraft,
   withdrawnByDisagreement
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   assessPeakPressure,
   assessPressureVerdict,
   describePeakPressure,
   retainedAfterLoad
-} from "./chunk-E464SO7G.js";
+} from "./chunk-VTKOO3YJ.js";
 import {
   __commonJS,
   __esm,
@@ -93182,15 +93185,15 @@ async function jsFilesUnder(dir) {
 async function extractModuleRegistry(nextServerDir) {
   const registry = /* @__PURE__ */ new Map();
   for (const file of await jsFilesUnder(nextServerDir)) {
-    let code;
-    let map;
+    let modules;
     try {
-      code = await readFile(file, "utf8");
-      map = JSON.parse(await readFile(`${file}.map`, "utf8"));
+      const code = await readFile(file, "utf8");
+      const map = JSON.parse(await readFile(`${file}.map`, "utf8"));
+      modules = extractChunkModules(code, map);
     } catch {
       continue;
     }
-    for (const [id, source] of extractChunkModules(code, map)) {
+    for (const [id, source] of modules) {
       if (!registry.has(id)) {
         registry.set(id, source);
       }
@@ -93199,6 +93202,16 @@ async function extractModuleRegistry(nextServerDir) {
   return registry;
 }
 
+// src/terminal-text.ts
+import { stripVTControlCharacters } from "util";
+var CONTROL_CHARACTER = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+function terminalSafe(text) {
+  return stripVTControlCharacters(text.replaceAll("\r\n", "\n")).replaceAll(
+    CONTROL_CHARACTER,
+    (character) => `\\x${character.charCodeAt(0).toString(16).padStart(2, "0")}`
+  );
+}
+
 // src/manifests.ts
 import { z as z2 } from "zod";
 var appPathsManifestSchema = z2.record(z2.string(), z2.string());
@@ -93392,6 +93405,7 @@ This only changes how the build is packaged \u2014 not how your app behaves.`
 
 // src/launcher.ts
 import { spawn } from "child_process";
+import { randomBytes } from "crypto";
 import { readdir as readdir2, readFile as readFile3 } from "fs/promises";
 import path3 from "path";
 import { pathToFileURL } from "url";
@@ -93489,6 +93503,7 @@ async function pollUntil(deadline, describe, probe, failed) {
 async function launchInstrumented(options) {
   const hostname = options.hostname ?? "127.0.0.1";
   const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+  const controlToken = randomBytes(32).toString("hex");
   const child = spawn(
     process.execPath,
     [
@@ -93506,7 +93521,8 @@ async function launchInstrumented(options) {
         NODE_ENV: "production",
         PORT: String(options.appPort),
         HOSTNAME: hostname,
-        NEXT_LEAK_DIR: options.workDir
+        NEXT_LEAK_DIR: options.workDir,
+        NEXT_LEAK_TOKEN: controlToken
       },
       stdio: ["ignore", "ignore", "pipe"]
     }
@@ -93550,7 +93566,9 @@ ${stderrTailBuffer}`;
             const parsed = controlFileSchema.parse(
               JSON.parse(await readFile3(path3.join(options.workDir, entry), "utf8"))
             );
-            const response = await fetch(`http://127.0.0.1:${parsed.port}/gc`);
+            const response = await fetch(`http://127.0.0.1:${parsed.port}/gc`, {
+              headers: { [CONTROL_TOKEN_HEADER]: controlToken }
+            });
             if (response.ok) {
               return parsed.port;
             }
@@ -93584,6 +93602,7 @@ ${stderrTailBuffer}`;
       pid: child.pid ?? -1,
       appPort: options.appPort,
       controlPort,
+      controlToken,
       explainExit: () => {
         if (!exited) {
           return null;
@@ -93922,6 +93941,12 @@ function parseCliArgs(argv) {
       }
     };
   }
+  if (options.attributeBuild) {
+    return {
+      kind: "error",
+      message: `option "--attribute" applies only to "next-leak build": a run already names what it retains \u2014 see --help`
+    };
+  }
   return { kind: "run", options };
 }
 
@@ -94251,7 +94276,7 @@ function describeProgress(bytes) {
 function describeDuration(ms) {
   return ms >= 36e5 ? `${Math.round(ms / 36e5)}h` : `${Math.round(ms / 1e3)}s`;
 }
-function get(port, pathname, deadlineMs, watch) {
+function get({ port, token }, pathname, deadlineMs, watch) {
   return new Promise((resolve, reject) => {
     let settled = false;
     const settle = (outcome) => {
@@ -94266,7 +94291,8 @@ function get(port, pathname, deadlineMs, watch) {
         reject(outcome.error);
       }
     };
-    const request2 = http.get({ host: "127.0.0.1", port, path: pathname }, (response) => {
+    const headers = { [CONTROL_TOKEN_HEADER]: token };
+    const request2 = http.get({ host: "127.0.0.1", port, path: pathname, headers }, (response) => {
       const chunks = [];
       response.on("data", (chunk) => chunks.push(chunk));
       response.once(
@@ -94336,8 +94362,8 @@ function get(port, pathname, deadlineMs, watch) {
     );
   });
 }
-async function request(port, pathname, deadlineMs = deadlineFor(pathname), watch) {
-  const response = await get(port, pathname, deadlineMs, watch);
+async function request(control, pathname, deadlineMs = deadlineFor(pathname), watch) {
+  const response = await get(control, pathname, deadlineMs, watch);
   if (response.status !== 200) {
     throw new ControlError(`control channel ${pathname} responded ${response.status}`);
   }
@@ -94347,8 +94373,8 @@ async function request(port, pathname, deadlineMs = deadlineFor(pathname), watch
     throw new ControlError(`control channel ${pathname} answered with malformed JSON`);
   }
 }
-async function requestGc(port) {
-  const sample = sampleSchema.parse(await request(port, "/gc"));
+async function requestGc(control) {
+  const sample = sampleSchema.parse(await request(control, "/gc"));
   if (!sample.gcExposed) {
     throw new ControlError(
       "the measured process is running without --expose-gc; samples would be meaningless"
@@ -94356,14 +94382,14 @@ async function requestGc(port) {
   }
   return sample;
 }
-async function requestMemory(port) {
-  return sampleSchema.parse(await request(port, "/mem"));
+async function requestMemory(control) {
+  return sampleSchema.parse(await request(control, "/mem"));
 }
-async function requestSnapshot(port, name, workDir) {
+async function requestSnapshot(control, name, workDir) {
   const pathname = `/snapshot?name=${encodeURIComponent(name)}`;
   const parsed = snapshotResponseSchema.parse(
     await request(
-      port,
+      control,
       pathname,
       deadlineFor(pathname),
       workDir === void 0 ? void 0 : productionWatch(snapshotPathFor(workDir, name))
@@ -94488,7 +94514,7 @@ var UNRECLAIMED_SETTLE_MS = SETTLE_POLL_MS;
 function unreclaimedSettleFor(idleMs) {
   return Math.min(UNRECLAIMED_SETTLE_MS, Math.floor(idleMs / 4));
 }
-function pollPeak(controlPort, phase, deps) {
+function pollPeak(control, phase, deps) {
   const peak = {
     phase,
     heapUsed: 0,
@@ -94506,7 +94532,7 @@ function pollPeak(controlPort, phase, deps) {
       }
       let sample;
       try {
-        sample = await deps.readMemory(controlPort);
+        sample = await deps.readMemory(control);
       } catch {
         return;
       }
@@ -94525,7 +94551,7 @@ function pollPeak(controlPort, phase, deps) {
     }
   };
 }
-async function waitUntilSettled(controlPort, maxIdleMs, deps) {
+async function waitUntilSettled(control, maxIdleMs, deps) {
   const deadline = Date.now() + maxIdleMs;
   let previous = null;
   let polls = 0;
@@ -94533,7 +94559,7 @@ async function waitUntilSettled(controlPort, maxIdleMs, deps) {
     await deps.sleep(Math.min(SETTLE_POLL_MS, Math.max(deadline - Date.now(), 0)));
     let current;
     try {
-      current = (await requestGc(controlPort)).heapUsed;
+      current = (await requestGc(control)).heapUsed;
     } catch {
       return { status: "unknown", polls };
     }
@@ -94592,6 +94618,7 @@ async function runRitual(options, deps = defaultDeps) {
     }
     app = await deps.launch({ ...launchOptions, appPort: options.appPort + 1 });
   }
+  const control = { port: app.controlPort, token: app.controlToken };
   const timings = [];
   const loadOutcomes = [];
   const settleOutcomes = [];
@@ -94661,13 +94688,13 @@ async function runRitual(options, deps = defaultDeps) {
     );
     const baseline = await timed(
       "baseline snapshot",
-      () => requestSnapshot(app.controlPort, "baseline", options.workDir)
+      () => requestSnapshot(control, "baseline", options.workDir)
     );
     memorySamples.push(baseline.sample);
     baselineSnapshot = baseline.file;
     for (let cycle = 1; cycle <= cycles; cycle += 1) {
       await timed(`cycle ${cycle} load`, async () => {
-        const poller = pollPeak(app.controlPort, `cycle ${cycle}`, deps);
+        const poller = pollPeak(control, `cycle ${cycle}`, deps);
         try {
           await loadCycle(`cycle ${cycle}`, loadRequests);
         } finally {
@@ -94678,30 +94705,30 @@ async function runRitual(options, deps = defaultDeps) {
       await timed(`cycle ${cycle} unreclaimed read`, async () => {
         await deps.sleep(unreclaimedSettleMs);
         try {
-          unreclaimedSamples.push(await deps.readMemory(app.controlPort));
+          unreclaimedSamples.push(await deps.readMemory(control));
         } catch {
           unreclaimedLost = true;
         }
       });
       const settle = await timed(
         `cycle ${cycle} settle`,
-        () => waitUntilSettled(app.controlPort, idleMs - unreclaimedSettleMs, deps)
+        () => waitUntilSettled(control, idleMs - unreclaimedSettleMs, deps)
       );
       settleOutcomes.push({ phase: `cycle ${cycle}`, ...settle });
       if (cycle === cycles) {
         try {
           const after = await timed(
             "after snapshot",
-            () => requestSnapshot(app.controlPort, "after", options.workDir)
+            () => requestSnapshot(control, "after", options.workDir)
           );
           afterSnapshot = after.file;
           memorySamples.push(after.sample);
         } catch (cause) {
           snapshotFailure = cause instanceof Error ? cause.message : String(cause);
-          memorySamples.push(await requestGc(app.controlPort));
+          memorySamples.push(await requestGc(control));
         }
       } else {
-        memorySamples.push(await requestGc(app.controlPort));
+        memorySamples.push(await requestGc(control));
       }
       cyclesCompleted = cycle;
     }
@@ -94812,7 +94839,7 @@ async function runSelfCheck(options, deps = defaultDeps2) {
       passed,
       verdict: result.trend.verdict,
       growthPer1000Requests,
-      summary: passed ? `harness verified: the planted leak was detected at ${rate}` : `harness NOT verified: a leak of ${PLANTED_LEAK_BYTES_PER_REQUEST} bytes per request came back ${result.trend.verdict} at ${rate}. Verdicts measured in this environment cannot be trusted \u2014 a flat curve here means the measurement is not working, not that nothing leaks`
+      summary: passed ? `harness detected the planted leak at ${rate} \u2014 it responds to retention in this environment; the routes' own figures are not checked by this` : `harness NOT verified: a leak of ${PLANTED_LEAK_BYTES_PER_REQUEST} bytes per request came back ${result.trend.verdict} at ${rate}. Verdicts measured in this environment cannot be trusted \u2014 a flat curve here means the measurement is not working, not that nothing leaks`
     };
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -95187,7 +95214,9 @@ function harnessLine(report) {
   const measured = report.routes.filter((route) => route.status === "measured");
   if (report.harness.verified) {
     const rate = formatGrowth(report.harness.growthPer1000Requests);
-    return [`harness verified this session: a planted leak measured ${rate}`];
+    return [
+      `harness detected a planted leak this session at ${rate} \u2014 it can see retention here; that is not a check on the figures above`
+    ];
   }
   const allStable = measured.length > 0 && measured.every((route) => effectiveVerdict(route) === "stable");
   if (!allStable) {
@@ -95231,7 +95260,7 @@ function formatReport(report) {
       `  next-leak ${report.appDir} --routes ${routeList} --cycles ${moreCycles}`
     );
   }
-  return lines.join("\n");
+  return terminalSafe(lines.join("\n"));
 }
 
 // src/environment.ts
@@ -95622,8 +95651,8 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-DLKFB3IU.js");
-  const { renderIssueMarkdown } = await import("./issue-report-OALZZLVR.js");
+  const { renderHtmlReport } = await import("./html-report-ZXDEJ6X5.js");
+  const { renderIssueMarkdown } = await import("./issue-report-4RW5YOT3.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
       const file = path9.join(workDir, `ISSUE-${routeSlug(route.route)}.md`);
@@ -95895,6 +95924,7 @@ export {
   sourceIndexAt,
   extractChunkModules,
   extractModuleRegistry,
+  terminalSafe,
   appPathsManifestSchema,
   routesManifestSchema,
   discoverPagesRoutes,

package/dist/{chunk-G2777DKL.js → chunk-UOAW5UA5.js}

@@ -2,12 +2,12 @@ import { createRequire as __nextLeakCreateRequire } from 'node:module';import {
 import {
   effectiveVerdict,
   withdrawnByDisagreement
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   assessPeakPressure,
   describePeakPressure,
   retainedAfterLoad
-} from "./chunk-E464SO7G.js";
+} from "./chunk-VTKOO3YJ.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
@@ -69,6 +69,13 @@ function peakBlock(route, parameters) {
   const note = pressure === null ? "" : `<p class="warn">Peak pressure: ${escapeHtml(describePeakPressure(pressure))}</p>`;
   return note + `<table><tr><th>peak during</th><th>heap</th><th>external</th><th>arrayBuffers</th><th>rss</th></tr>${peakRows}</table>`;
 }
+function attributionGapBlock(route) {
+  if (route.status !== "measured" || route.attributionGap === void 0) {
+    return "";
+  }
+  const cause = route.attributionGap.reason === "snapshot-unavailable" ? "the final heap snapshot was never taken" : "the heap snapshots could not be read";
+  return `<p class="warn">No attribution: ${cause}, so this run cannot name what retains the memory. The curve above is unaffected. ${escapeHtml(route.attributionGap.detail)}</p>`;
+}
 function measuredSection(route, parameters) {
   if (route.status !== "measured") {
     return "";
@@ -84,7 +91,7 @@ function measuredSection(route, parameters) {
     const owner = ownerCell(attribution);
     return `<tr><td>${finding.kind}</td><td>${escapeHtml(finding.nodeType)}</td><td>${escapeHtml(finding.name)}</td><td>${(finding.retainedBytes / MB).toFixed(2)} MB</td><td>${owner}</td></tr>`;
   }).join("");
-  return `<section><h2><span class="badge" style="background:${color}">${verdict}</span> <code>${escapeHtml(route.route)}</code></h2>` + heapCurveSvg(route.samples, color) + `<p class="curve">heap ${curve} MB \xB7 ${(route.growthPer1000Requests / MB).toFixed(2)} MB/1000 req</p>` + withdrawn + warnings + peakBlock(route, parameters) + (findingRows === "" ? "" : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;
+  return `<section><h2><span class="badge" style="background:${color}">${verdict}</span> <code>${escapeHtml(route.route)}</code></h2>` + heapCurveSvg(route.samples, color) + `<p class="curve">heap ${curve} MB \xB7 ${(route.growthPer1000Requests / MB).toFixed(2)} MB/1000 req</p>` + withdrawn + warnings + peakBlock(route, parameters) + (findingRows === "" ? attributionGapBlock(route) : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;
 }
 function renderHtmlReport(run) {
   const measured = run.routes.filter((route) => route.status === "measured");

package/dist/{chunk-E464SO7G.js → chunk-VTKOO3YJ.js}

@@ -20,23 +20,16 @@ function assessPeakPressure(input) {
   const heapLimitBytes = input.maxOldSpaceMb * MB;
   const peakHeap = maxOf(sampled, (peak) => peak.heapUsed);
   const peakRss = maxOf(sampled, (peak) => peak.rss);
-  if (reachesHeapCeiling(peakHeap, heapLimitBytes)) {
-    return {
-      class: "heap",
-      peakBytes: peakHeap,
-      retainedBytes: input.retainedHeapBytes,
-      heapLimitBytes
-    };
-  }
-  if (reachesRssCeiling(peakRss, input.retainedHeapBytes)) {
-    return {
-      class: "rss",
-      peakBytes: peakRss,
-      retainedBytes: input.retainedHeapBytes,
-      heapLimitBytes
-    };
+  const pressureClass = sustainedClass(input) ?? (reachesHeapCeiling(peakHeap, heapLimitBytes) ? "heap" : reachesRssCeiling(peakRss, input.retainedHeapBytes) ? "rss" : null);
+  if (pressureClass === null) {
+    return null;
   }
-  return null;
+  return {
+    class: pressureClass,
+    peakBytes: pressureClass === "heap" ? peakHeap : peakRss,
+    retainedBytes: input.retainedHeapBytes,
+    heapLimitBytes
+  };
 }
 var PRESSURE_MIN_SETTLED_CYCLES = 2;
 var reachesCeiling = (peak, pressureClass, input) => pressureClass === "heap" ? reachesHeapCeiling(peak.heapUsed, input.maxOldSpaceMb * MB) : reachesRssCeiling(peak.rss, input.retainedHeapBytes);
@@ -50,19 +43,15 @@ function isSustained(input, pressureClass) {
   }
   return settled.every((peak) => reachesCeiling(peak, pressureClass, input));
 }
+var PRESSURE_CLASSES = ["heap", "rss"];
+function sustainedClass(input) {
+  return PRESSURE_CLASSES.find((pressureClass) => isSustained(input, pressureClass)) ?? null;
+}
 function assessPressureVerdict(input) {
   if (input.trend.verdict !== "stable" && input.trend.verdict !== "saturating") {
     return input.trend;
   }
-  const pressure = assessPeakPressure({
-    peaks: input.peaks,
-    retainedHeapBytes: input.retainedHeapBytes,
-    maxOldSpaceMb: input.maxOldSpaceMb
-  });
-  if (pressure === null) {
-    return input.trend;
-  }
-  if (!isSustained(input, pressure.class)) {
+  if (sustainedClass(input) === null) {
     return input.trend;
   }
   return { ...input.trend, verdict: "pressure" };

package/dist/cli.js

@@ -20,13 +20,15 @@ import {
   renderConfigSkeleton,
   runMeasurement,
   runSelfCheck,
+  terminalSafe,
   unregisterChild,
   validateTarget
-} from "./chunk-L5KWU2RU.js";
+} from "./chunk-UKWFONEI.js";
+import "./chunk-IKWF7SSB.js";
 import {
   classifyTrend
-} from "./chunk-UU4RXOZO.js";
-import "./chunk-E464SO7G.js";
+} from "./chunk-QUFL2FXU.js";
+import "./chunk-VTKOO3YJ.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
@@ -151,6 +153,9 @@ function discardPendingSnapshotsSync() {
 }
 
 // src/build-attribution.ts
+function isAttributionGap(outcome) {
+  return outcome !== null && "reason" in outcome;
+}
 var defaultDeps = {
   diff: diffSnapshotFiles,
   registry: extractModuleRegistry
@@ -159,17 +164,19 @@ async function attributeBuildCapture(result, appDir, onProgress = () => {
 }, deps = defaultDeps) {
   const capture = result.capture;
   if (capture === null) {
-    return null;
+    return result.captureRequested ? {
+      reason: "capture-missed",
+      detail: result.captureFailure ?? "the run never captured a usable snapshot pair from the worker"
+    } : null;
   }
   onProgress(`diffing what worker ${capture.pid} retained`);
   let diff;
   try {
     diff = await deps.diff(capture.files.baselineFile, capture.files.afterFile);
   } catch (cause) {
-    onProgress(
-      cause instanceof SnapshotError ? `no attribution: ${cause.message}` : `no attribution: the snapshot pair could not be diffed`
-    );
-    return null;
+    const detail = cause instanceof SnapshotError ? cause.message : "the snapshot pair could not be diffed";
+    onProgress(`no attribution: ${detail}`);
+    return { reason: "snapshot-unreadable", detail };
   }
   const registry = await deps.registry(path2.join(appDir, ".next", "server"));
   return {
@@ -212,6 +219,13 @@ function attributionLines(attribution) {
   if (attribution === null) {
     return [];
   }
+  if (isAttributionGap(attribution)) {
+    return [
+      "",
+      `  no attribution: ${attribution.detail}.`,
+      `  This does not say nothing grew \u2014 the comparison was never made.`
+    ];
+  }
   const { diff, attributed, bracketed } = attribution;
   const findings = [...diff.grownNodes, ...diff.newNodes];
   if (findings.length === 0) {
@@ -242,7 +256,7 @@ function attributionLines(attribution) {
   }
   return lines;
 }
-function formatBuildReport(result, attribution = null) {
+function buildReportText(result, attribution = null) {
   const lines = [`next-leak build \xB7 ${result.appDir}`, ""];
   if (result.strippedCapWarning !== null) {
     lines.push(`  \u25B2 ${result.strippedCapWarning}`, "");
@@ -320,6 +334,9 @@ function formatBuildReport(result, attribution = null) {
   );
   return lines.join("\n");
 }
+function formatBuildReport(result, attribution = null) {
+  return terminalSafe(buildReportText(result, attribution));
+}
 
 // src/build-run.ts
 import { spawn } from "child_process";
@@ -566,6 +583,24 @@ function recordSample(rows, rootPid, atMs, workers, parentSamples) {
     workers.set(row.pid, series);
   }
 }
+function describeCaptureFailure(stage, pid, mismatchedWorker) {
+  if (mismatchedWorker) {
+    return "the snapshot pair belongs to a worker other than the one judged";
+  }
+  if (pid === null) {
+    return "no static-generation worker was seen to capture from";
+  }
+  switch (stage) {
+    case "waiting":
+      return `worker ${pid} never grew enough to snapshot`;
+    case "baseline-taken":
+      return `worker ${pid} was snapshotted once and never reached a second point`;
+    case "missed":
+      return `capture gave up on worker ${pid} before it had a pair`;
+    case "pair-taken":
+      return `the pair captured from worker ${pid} could not be collected from disk`;
+  }
+}
 async function collectCapture(options) {
   const { appDir, workDir, pid, stage, baselineRssBytes, afterRssBytes } = options;
   if (workDir === void 0 || pid === null) {
@@ -716,6 +751,8 @@ async function runBuildMeasurement(options, deps = defaultDeps2) {
       retentionPerPageBytes: null,
       heapExhausted,
       capture: workerCapture,
+      captureRequested: capturing,
+      captureFailure: workerCapture === null ? describeCaptureFailure(captureStage, capturePid, false) : null,
       strippedCapWarning,
       exitCode,
       output
@@ -747,6 +784,12 @@ async function runBuildMeasurement(options, deps = defaultDeps2) {
     // A pair belonging to a worker other than the one judged supports no claim
     // about the verdict above, so it is dropped rather than reported next to it.
     capture: workerCapture !== null && workerCapture.pid === worst?.pid ? workerCapture : null,
+    captureRequested: capturing,
+    captureFailure: workerCapture !== null && workerCapture.pid === worst?.pid ? null : describeCaptureFailure(
+      captureStage,
+      capturePid,
+      workerCapture !== null && workerCapture.pid !== worst?.pid
+    ),
     strippedCapWarning,
     exitCode,
     output
@@ -830,12 +873,12 @@ async function runBuildCommand(appDir, outputDir, attribute) {
     // is worth asking for, not worth risking every run for.
     ...attribute && { workDir },
     signal: aborter.signal,
-    onProgress: (message) => console.error(`\xB7 ${message}`)
+    onProgress: (message) => console.error(`\xB7 ${terminalSafe(message)}`)
   });
   const attribution = await attributeBuildCapture(
     result,
     appDir,
-    (message) => console.error(`\xB7 ${message}`)
+    (message) => console.error(`\xB7 ${terminalSafe(message)}`)
   );
   console.log(formatBuildReport(result, attribution));
   if (aborter.signal.aborted) {
@@ -911,9 +954,9 @@ async function main() {
       ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
       ...options.maxOldSpaceMb !== null && { maxOldSpaceMb: options.maxOldSpaceMb }
     });
-    console.error(`\xB7 ${check.summary}`);
+    console.error(`\xB7 ${terminalSafe(check.summary)}`);
     if (!check.passed) {
-      console.error(`error: ${check.summary}`);
+      console.error(`error: ${terminalSafe(check.summary)}`);
       process.exitCode = 1;
       return;
     }
@@ -939,7 +982,7 @@ async function main() {
     ...options.diffAll && { diffAll: true },
     ...options.noResolve && { resolveInconclusive: false },
     ...options.output !== null && { outputDir: options.output },
-    onProgress: (message) => console.error(`\xB7 ${message}`)
+    onProgress: (message) => console.error(`\xB7 ${terminalSafe(message)}`)
   });
   console.log(formatReport(report));
   if (aborter.signal.aborted) {
@@ -957,7 +1000,7 @@ try {
   await main();
 } catch (cause) {
   if (cause instanceof TargetError || cause instanceof RouteConfigError) {
-    console.error(`error: ${cause.message}`);
+    console.error(`error: ${terminalSafe(cause.message)}`);
   } else {
     console.error(cause);
   }

package/dist/control-client.d.ts

@@ -1,4 +1,9 @@
-import type { HeapSample } from "./control-server.js";
+import { type HeapSample } from "./control-server.js";
+/** Where a measured process listens for control requests, and the secret it expects. */
+export type ControlChannel = {
+    port: number;
+    token: string;
+};
 declare function deadlineFor(pathname: string): number;
 /** Where the control server will put `<name>.heapsnapshot`, so the client can watch it grow. */
 export declare function snapshotPathFor(workDir: string, name: string): string;
@@ -13,14 +18,14 @@ export type SnapshotWatch = {
     /** How often to look. */
     pollMs: number;
 };
-declare function request(port: number, pathname: string, deadlineMs?: number, watch?: SnapshotWatch): Promise<unknown>;
+declare function request(control: ControlChannel, pathname: string, deadlineMs?: number, watch?: SnapshotWatch): Promise<unknown>;
 /** Forces GC in the measured process and returns a settled memory sample. */
-export declare function requestGc(port: number): Promise<HeapSample>;
+export declare function requestGc(control: ControlChannel): Promise<HeapSample>;
 /**
  * Reads memory without collecting. Used to poll a process under load, where a
  * forced GC would change the number being read.
  */
-export declare function requestMemory(port: number): Promise<HeapSample>;
+export declare function requestMemory(control: ControlChannel): Promise<HeapSample>;
 /**
  * Forces GC, writes a named heap snapshot, and returns its path and sample.
  *
@@ -29,7 +34,7 @@ export declare function requestMemory(port: number): Promise<HeapSample>;
  * the call falls back to the plain wall-clock bound, which cannot tell a big
  * snapshot from a wedged process.
  */
-export declare function requestSnapshot(port: number, name: string, workDir?: string): Promise<{
+export declare function requestSnapshot(control: ControlChannel, name: string, workDir?: string): Promise<{
     file: string;
     sample: HeapSample;
 }>;

package/dist/control-server.d.ts

@@ -33,9 +33,13 @@ export type HeapSample = {
 export declare const requestProbe: typeof globalThis & {
     __nextLeakServedRequests?: number;
 };
+/** Header that carries the shared secret on every control request. */
+export declare const CONTROL_TOKEN_HEADER = "x-next-leak-token";
 export type ControlServerOptions = {
     /** Directory where heap snapshots are written. */
     snapshotDir: string;
+    /** Secret the launcher generated for this run; a request without it is refused. */
+    token: string;
     /** Injectable for tests; defaults to `v8.writeHeapSnapshot`. */
     writeSnapshot?: (file: string) => string;
 };
@@ -50,5 +54,11 @@ export type ControlServer = {
  * - `GET /mem` — respond with a memory sample WITHOUT collecting.
  * - `GET /snapshot?name=<label>` — force GC, write `<label>.heapsnapshot`
  *   into `snapshotDir`, respond `{ file, sample }` only once fully written.
+ *
+ * Every request must carry the run's token. The socket is bound to loopback,
+ * which keeps other machines out and nobody else: any local process can reach
+ * it, and so can a web page open in a browser on the same machine. Without
+ * the token either could read the process's argv and working directory, or
+ * ask for heap snapshots until the disk is full.
  */
 export declare function startControlServer(options: ControlServerOptions): Promise<ControlServer>;

package/dist/{html-report-DLKFB3IU.js → html-report-ZXDEJ6X5.js}

@@ -1,9 +1,9 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
 import {
   renderHtmlReport
-} from "./chunk-G2777DKL.js";
-import "./chunk-UU4RXOZO.js";
-import "./chunk-E464SO7G.js";
+} from "./chunk-UOAW5UA5.js";
+import "./chunk-QUFL2FXU.js";
+import "./chunk-VTKOO3YJ.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderHtmlReport

package/dist/index.js

@@ -41,17 +41,18 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-L5KWU2RU.js";
+} from "./chunk-UKWFONEI.js";
+import "./chunk-IKWF7SSB.js";
 import {
   renderHtmlReport
-} from "./chunk-G2777DKL.js";
+} from "./chunk-UOAW5UA5.js";
 import {
   classifyTrend
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   renderIssueMarkdown
-} from "./chunk-YPVBX3QA.js";
-import "./chunk-E464SO7G.js";
+} from "./chunk-FJVY5MKV.js";
+import "./chunk-VTKOO3YJ.js";
 import "./chunk-6XYFBOL2.js";
 export {
   LaunchError,

package/dist/{issue-report-OALZZLVR.js → issue-report-4RW5YOT3.js}

@@ -1,8 +1,8 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
 import {
   renderIssueMarkdown
-} from "./chunk-YPVBX3QA.js";
-import "./chunk-E464SO7G.js";
+} from "./chunk-FJVY5MKV.js";
+import "./chunk-VTKOO3YJ.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderIssueMarkdown

package/dist/launcher.d.ts

@@ -49,6 +49,8 @@ export type LaunchedApp = {
     pid: number;
     appPort: number;
     controlPort: number;
+    /** Secret the control channel expects on every request; generated per launch. */
+    controlToken: string;
     /**
      * Why the measured process is gone, or null while it is alive. Without it
      * a child that died mid-run surfaces as "fetch failed", which reads like a

package/dist/peak-pressure.d.ts

@@ -80,17 +80,17 @@ export type PressureVerdictInput = {
  * requests, because a forced GC handed all of it back before every sample. That
  * is the trap next-leak exists to warn other people about.
  *
- * Three conditions, and no threshold of its own: the ceiling rules are
+ * Two conditions, and no threshold of its own: the ceiling rules are
  * `assessPeakPressure`'s, asked of each cycle instead of the highest reading.
  *
  * - **The post-GC verdict is `stable` or `saturating`.** `leak` is already the
  *   worse news and `inconclusive` is an admission that the series did not
  *   decide — promoting *that* to an accusation would be inventing a finding out
  *   of a measurement that failed.
- * - **The peak is far enough from what the route retains to be remarked on** —
- *   `assessPeakPressure`, thresholds unchanged.
- * - **Every settled cycle reached that ceiling**, not just the highest one.
- *   This is the condition that makes the verdict safe. A single high peak is an
+ * - **Every settled cycle reached the same ceiling**, not just the highest one.
+ *   This is the condition that makes the verdict safe, and it contains the one
+ *   that used to stand beside it: if every settled cycle reached a ceiling, so
+ *   did the highest reading of the run. A single high peak is an
  *   episode and gets only the note; a process that returns to the ceiling every
  *   time it serves traffic is describing what it does under load, which is the
  *   thing a container is sized against.

package/dist/ritual.d.ts

@@ -1,3 +1,4 @@
+import { type ControlChannel } from "./control-client.js";
 import type { HeapSample } from "./control-server.js";
 import { launchInstrumented } from "./launcher.js";
 import { runAbandonPhase, type AbandonOrigin } from "./abandon-load.js";
@@ -164,7 +165,7 @@ export type RitualDeps = {
     abandon: typeof runAbandonPhase;
     sleep: (ms: number) => Promise<void>;
     /** GC-free read, polled while the app is under load. */
-    readMemory: (port: number) => Promise<HeapSample>;
+    readMemory: (control: ControlChannel) => Promise<HeapSample>;
 };
 /**
  * The pre-collection wait, taken *out of* the idle rather than added to it.

package/dist/terminal-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Text as it can be written to a terminal.
+ *
+ * Heap node names, source paths, route names and the build's own output all
+ * come from the measured app, and a terminal obeys what it is sent: an escape
+ * sequence in a string name can clear the screen, move the cursor over a
+ * verdict already printed, or retitle the window. next-leak writes no
+ * sequences of its own, so none that reaches the output is ours to keep.
+ *
+ * A complete sequence is an instruction, not text, and is dropped. A control
+ * character left on its own is shown as `\xNN`: it was in the value, and a
+ * reader comparing the report against `run.json` should still find it.
+ */
+export declare function terminalSafe(text: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",