disk-space-saviour 0.22.0 → 0.22.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.22.1
+
+### Patch Changes
+
+- 9479acd: Keep a `node_modules` folder that holds data no package manager installs, naming each such entry and its size, at scan time and right before deletion.
+
+  Let `clean` and `emergency` delete on a full disk: an audit log that does not fit is reported as not written and written as soon as deletions free space.
+
+  Keep everything inside a live Claude Code session scratchpad until the session and its transcript stay idle for the inactive window, at scan time and right before deletion.
+
+  Show the dss run among swap holders as `(this dss run)` and never name it as a process to quit.
+
+  Name what fills a directory of many small entries in `dss usage` by name pattern, with their count and total size.
+
+  Offer rotated app logs in `~/Library/Logs`, Crashpad reports left unsent for 30 days and the GitHub CLI run-log cache in the moderate tier.
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -94,12 +94,19 @@ Run `dss --help` for every option. The most useful ones:
   files, and for each directory what the latest dss scan or clean found
   inside it (`[dss: 1.2 GiB freeable, 3.4 GiB blocked]`). On macOS it adds
   the APFS volumes a walk cannot see (system, VM swap, Preboot, Recovery),
-  local snapshots and the part of the Data volume left unread. It needs
-  `du`, so it runs on macOS and Linux; a full walk takes minutes.
+  local snapshots and the part of the Data volume left unread. A directory
+  filled by many small entries names what fills it by pattern
+  (`T/ms-*  (68523 entries, each under 64 MiB)`). It needs `du`, so it runs
+  on macOS and Linux; a full walk takes minutes.
 - APFS clones that share every block with an installed app, such as Chrome's
   code-sign clones, free nothing when deleted, so they are never offered. The
   scan lists them under `SHARED WITH INSTALLED APPS` and `dss usage` marks
   them, because `du` and Finder count them at full size.
+- `node_modules` counts as regenerable only while it holds what package
+  managers install: packages, `@scope` folders, `.bin`, lockfile copies and
+  tool caches such as `.cache` or `.vite`. Any other data kept there
+  (verification runs, captured evidence) blocks the whole directory, and the
+  check runs again right before deleting.
 - Git worktree folders (`.worktrees`, `worktrees`) restart the project search
   depth, so dependencies of nested worktrees are found below `--max-depth`.
 - `clean` automatically reuses a matching scan from the last 30 minutes.
@@ -139,7 +146,9 @@ their blocks with the installed app), Chromium on-device AI models
 Electron and electron-builder archives, the Bun transpiler cache, Docker
 Desktop and Warp staged updates (kept while the app runs), Zed language
 servers, tree-sitter toolchains, Codex plugin staging, the Clang module cache
-and processed Crashpad reports. Telegram pure caches, Safari/WebKit,
+Crashpad reports (processed ones, and unsent ones after 30 days), rotated app
+logs in `~/Library/Logs` (`warp.log.old.2`) and the GitHub CLI run-log cache.
+Telegram pure caches, Safari/WebKit,
 Chromium code/GPU/Dawn/service-worker caches and marker-validated Electron
 caches are included. Old Playwright browser revisions are kept while a
 Playwright package recorded in the registry's `.links` still launches them or
@@ -148,6 +157,10 @@ directories are removed once untouched. Telegram caches are removed only
 while Telegram is not running. Telegram databases, browser profiles and
 Playwright MCP profiles are preserved. macOS access failures explain when Full Disk Access
 is needed. Agent scratch cleanup requires inactivity and Git safety checks.
+Anything inside a Claude Code session scratchpad
+(`{TMP}/claude-<uid>/<project>/<session>`) is kept until the session and its
+transcript in `~/.claude/projects` stay untouched for the inactive window
+(30 days), checked again right before deletion.
 
 ## Safety
 
@@ -233,7 +246,10 @@ is needed. Agent scratch cleanup requires inactivity and Git safety checks.
   include every candidate and its blockers; blocked candidates do not
   contribute to reclaimable tier totals.
   If a read-only scan cannot save its audit, it warns and still prints the
-  report. Root scans with another user's `HOME` use a private temporary audit
+  report. When the disk is full, `clean` and `emergency` delete anyway and
+  write their audit as soon as deletions free room; if it never fits, the
+  summary says `Audit log: not written (ENOSPC ...)`. Other audit failures,
+  such as an unusable `--audit-dir`, still stop them before deleting. Root scans with another user's `HOME` use a private temporary audit
   directory. Set `--audit-dir` to choose a persistent writable location.
 
 Long-lived `npm exec`/`npx` servers allow idle npm download and node-gyp
@@ -290,7 +306,8 @@ Each scan records swap usage and its largest holders in the state directory, so
 the next scan shows how much both grew during the last week. A `WARNING:` line
 appears when swap grew by 1 GiB or more, is at least 75% full, or exceeds the free
 disk space it can grow into, naming the processes holding the memory and their
-growth. Long-running AI agent sessions keep their history in memory: quitting and
+growth. The dss run itself is listed as `(this dss run)` and never named as a
+process to quit. Long-running AI agent sessions keep their history in memory: quitting and
 resuming them (`codex resume <session-id>`, `claude --resume`) releases it. When
 Docker Desktop consumes memory, saving work and restarting it or lowering its VM
 memory limit can help. dss never deletes swap files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk-space-saviour",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Safely reclaims disk space: caches and build outputs of 20+ ecosystems, forgotten projects, and Docker (running, stopped and nested containers), with an emergency mode",
   "type": "module",
   "main": "src/index.js",

package/src/audit.js

@@ -101,7 +101,38 @@ export async function writeAudit(audit, options = {}) {
     dir,
     `dss-${audit.command}-${stamp}-${audit.pid}.json`
   );
-  await fsp.writeFile(file, `${JSON.stringify(audit, null, 2)}\n`);
+  // A write that fails half way (a full disk) leaves the previous record.
+  const partial = `${file}.${process.pid}.tmp`;
+  try {
+    await fsp.writeFile(partial, `${JSON.stringify(audit, null, 2)}\n`);
+    await fsp.rename(partial, file);
+  } catch (error) {
+    await fsp.rm(partial, { force: true }).catch(() => {});
+    throw error;
+  }
   audit.file = file;
   return file;
 }
+
+/** Errors meaning the disk is full, which is what cleaning fixes. */
+const NO_SPACE = new Set(['ENOSPC', 'EDQUOT']);
+
+/**
+ * Writes the record of a run that deletes. A full disk does not stop the
+ * run: the failure is kept in `audit.auditError`, and the next write, after
+ * deletions freed space, tries again.
+ * @returns {Promise<string|null>} the file, or null when the disk is full
+ */
+export async function recordAudit(audit, options = {}) {
+  try {
+    const file = await writeAudit(audit, options);
+    delete audit.auditError;
+    return file;
+  } catch (error) {
+    if (!NO_SPACE.has(error.code)) {
+      throw error;
+    }
+    audit.auditError = { message: error.message, code: error.code };
+    return null;
+  }
+}

package/src/clean.js

@@ -17,7 +17,7 @@ import { createWriteStream, promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { finished } from 'node:stream/promises';
 
-import { backupDirectory, startAudit, writeAudit } from './audit.js';
+import { backupDirectory, recordAudit, startAudit } from './audit.js';
 import { PhaseTimer } from './timings.js';
 import { configureContainerHost } from './docker/writable.js';
 import { DockerCli, assertAllowed, parseDockerSize } from './docker/cli.js';
@@ -45,6 +45,7 @@ import { isWithin } from './paths.js';
 import { OTHER_RULES } from './rules/other.js';
 import { compareVersions, VERSION_RULES } from './rules/versions.js';
 import { scanVersions } from './scanners/versions.js';
+import { foreignDataBlocker } from './scanners/node-modules.js';
 import { analyzeRustProfile } from './scanners/rust.js';
 import {
   filterItems,
@@ -192,6 +193,7 @@ export class Cleaner {
         git: new GitInspector(env),
         liveness: new LivenessProbe(env, {
           staleAgeMs: this.options.staleAgeMs,
+          inactiveMs: this.options.inactiveMs,
           now: this.options.now,
         }),
       });
@@ -447,6 +449,12 @@ export class Cleaner {
     if (mount) {
       return mount;
     }
+    if (item.rule === 'node-modules' && type === 'remove') {
+      const foreign = await foreignDataBlocker(ctx.env, item.path);
+      if (foreign) {
+        return foreign;
+      }
+    }
     return this.#gitBlocker(ctx, item);
   }
 
@@ -959,7 +967,7 @@ export async function clean(report, input = {}) {
     }
     if (options.audit !== false) {
       await timings.measure('audit-write', () =>
-        writeAudit(audit, { ...options, inProgress: true })
+        recordAudit(audit, { ...options, inProgress: true })
       );
     }
   };
@@ -971,7 +979,7 @@ export async function clean(report, input = {}) {
   audit.health = cleaner.health.records;
   audit.timings = timings;
   if (options.audit !== false) {
-    await writeAudit(audit, { ...options, inProgress: true });
+    await recordAudit(audit, { ...options, inProgress: true });
   }
   try {
     const done = new Set(audit.entries.map((entry) => entry.id));
@@ -988,7 +996,7 @@ export async function clean(report, input = {}) {
       options.onEntry?.(entry, item);
       if (options.audit !== false) {
         await timings.measure('audit-write', () =>
-          writeAudit(audit, { ...options, inProgress: true })
+          recordAudit(audit, { ...options, inProgress: true })
         );
       }
     }
@@ -1025,7 +1033,7 @@ export async function finishAudit(audit, report, options) {
     )
     .map((env) => ({ label: env.label, status: env.scanStatus }));
   if (options.audit !== false) {
-    await writeAudit(audit, options);
+    await recordAudit(audit, options);
   }
   return audit;
 }

package/src/conditions.js

@@ -47,6 +47,13 @@ const CONDITIONS = [
       action: `they stay untouched for the ${m[1]} activity window`,
     }),
   ],
+  [
+    /^(?:busy: )?inside the scratchpad of Claude Code session (\S+) .*; kept until it is idle for (.+)$/,
+    (m) => ({
+      key: `session:${m[1]}`,
+      action: `the Claude Code session ${m[1]} stays idle for ${m[2]}`,
+    }),
+  ],
   [
     /^scan incomplete: (.+)$/,
     (m) => ({

package/src/emergency.js

@@ -12,7 +12,7 @@
  * kept for investigation needs its own `removeContainers` entry.
  */
 
-import { startAudit, writeAudit, throwIfAborted } from './audit.js';
+import { recordAudit, startAudit, throwIfAborted } from './audit.js';
 import { Cleaner, cleanOrder, finishAudit, wantedItems } from './clean.js';
 import { LocalEnv } from './env/local.js';
 import { TIERS, selectByTier, tierRank } from './items.js';
@@ -120,7 +120,7 @@ export async function emergency(input = {}) {
         });
   audit.report = report;
   if (options.audit !== false) {
-    await writeAudit(audit, { ...options, inProgress: true });
+    await recordAudit(audit, { ...options, inProgress: true });
   }
   let disk = audit.diskAfter ?? diskBefore;
   if (report.aborted) {
@@ -145,7 +145,7 @@ async function escalate({ report, options, env, target, goal, audit }) {
       audit.entries.push(entry);
     }
     if (options.audit !== false) {
-      await writeAudit(audit, { ...options, inProgress: true });
+      await recordAudit(audit, { ...options, inProgress: true });
     }
   };
   const cleaner = new Cleaner(report, {
@@ -195,7 +195,7 @@ async function escalate({ report, options, env, target, goal, audit }) {
       }
       options.onEntry?.(entry, item);
       if (options.audit !== false) {
-        await writeAudit(audit, { ...options, inProgress: true });
+        await recordAudit(audit, { ...options, inProgress: true });
       }
       if (entry.status !== 'removed' && entry.status !== 'planned') {
         continue;

package/src/index.d.ts

@@ -180,6 +180,8 @@ export interface EnvironmentDescriptor {
       swappedBytes?: number;
       /** Change since the earliest scan of the last week listing this process. */
       growth?: { since: number; memoryBytes: number };
+      /** The dss process itself, never named as one to quit. */
+      self?: boolean;
     }>;
     /** Change since the earliest scan of the last week. */
     growth?: { since: number; usedBytes: number } | null;
@@ -288,6 +290,8 @@ export interface AuditLog {
   plannedBytes: number;
   environments: Record<string, EnvironmentTotal>;
   file?: string;
+  /** Set while the disk was too full to write the log; deletion went on. */
+  auditError?: { message: string; code: string };
   goal?: { freeBytes: number | null; untilPercent: number | null };
   goalMet?: boolean;
   reachedTier?: Tier;

package/src/liveness.js

@@ -10,7 +10,9 @@
  * - a command argument names a path inside the item (including scripts
  *   whose interpreter has already closed its input descriptor);
  * - a directory inside the item is on a process's `PATH`, so the process
- *   may start a program from it at any time.
+ *   may start a program from it at any time;
+ * - the path lies in the scratchpad of a Claude Code session that was active
+ *   inside the inactive window, so the session may still rely on it.
  *
  * The cleaner refreshes the probe right before acting on each item.
  */
@@ -27,6 +29,32 @@ import { isWithin } from './paths.js';
 import { formatDuration } from './units.js';
 
 const PROC_COMM_LIMIT = 15;
+const DEFAULT_INACTIVE_MS = 30 * 24 * 60 * 60 * 1000;
+const SESSION_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The Claude Code session directory a path lies in: Claude Code keeps each
+ * session's scratchpad under `<tmp>/claude-<uid>/<project>/<session id>`.
+ * @returns {{dir: string, project: string, id: string}|null}
+ */
+export function agentSessionOf(target, pathApi = path) {
+  const parts = target.split(/[\\/]/);
+  const index = parts.findIndex(
+    (part, at) =>
+      /^claude-\d+$/.test(part) &&
+      Boolean(parts[at + 1]) &&
+      SESSION_ID.test(parts[at + 2] ?? '')
+  );
+  if (index < 0) {
+    return null;
+  }
+  return {
+    dir: parts.slice(0, index + 3).join(pathApi.sep),
+    project: parts[index + 1],
+    id: parts[index + 2],
+  };
+}
 
 /** Bun subcommands that read or write the install cache. */
 const BUN_PACKAGE_COMMANDS = new Set([
@@ -210,11 +238,21 @@ function appLabel(proc, matched) {
 export class LivenessProbe {
   /**
    * @param {object} env environment adapter
-   * @param {{staleAgeMs: number, now?: () => number, refreshMs?: number}} options
+   * @param {{staleAgeMs: number, inactiveMs?: number, now?: () => number,
+   *   refreshMs?: number}} options
    */
-  constructor(env, { staleAgeMs, now = () => Date.now(), refreshMs = 2000 }) {
+  constructor(
+    env,
+    {
+      staleAgeMs,
+      inactiveMs = DEFAULT_INACTIVE_MS,
+      now = () => Date.now(),
+      refreshMs = 2000,
+    }
+  ) {
     this.env = env;
     this.staleAgeMs = staleAgeMs;
+    this.inactiveMs = inactiveMs;
     this.now = now;
     this.refreshMs = refreshMs;
     this.refreshedAt = -Infinity;
@@ -225,6 +263,7 @@ export class LivenessProbe {
     this.pathOwners = new Map();
     this.pathStats = new Map();
     this.inodes = new Map();
+    this.agentSessions = new Map();
     // Bundle identifiers never change, so they outlive refreshes.
     this.bundleIds = new Map();
   }
@@ -247,6 +286,7 @@ export class LivenessProbe {
     this.pathStats.clear();
     this.pathOwners.clear();
     this.inodes.clear();
+    this.agentSessions.clear();
   }
 
   /** Reads the identifiers of the app bundles running processes come from. */
@@ -393,6 +433,7 @@ export class LivenessProbe {
    * @param {string[]} paths
    */
   async resolve(paths) {
+    await this.#resolveAgentSessions(paths);
     if (this.env.unreadableProcesses?.length) {
       const missing = [
         ...new Set(
@@ -436,6 +477,72 @@ export class LivenessProbe {
     }
   }
 
+  /**
+   * When each Claude Code session holding one of the paths was last active:
+   * its transcript, its session directory and the entries two levels below.
+   */
+  async #resolveAgentSessions(paths) {
+    const pending = new Map();
+    for (const target of paths) {
+      const session = agentSessionOf(target, this.env.path);
+      if (session && !this.agentSessions.has(session.dir)) {
+        pending.set(session.dir, session);
+      }
+    }
+    if (pending.size === 0) {
+      return;
+    }
+    this.homes ??= (await this.env.homeDirs?.().catch(() => null)) ?? [];
+    for (const session of pending.values()) {
+      const children = await this.env.list(session.dir);
+      const grandchildren = await Promise.all(
+        children
+          .filter((entry) => entry.type === 'dir')
+          .map((entry) => this.env.list(entry.path))
+      );
+      const candidates = [
+        session.dir,
+        ...children.map((entry) => entry.path),
+        ...grandchildren.flat().map((entry) => entry.path),
+        ...this.homes.map((home) =>
+          this.env.path.join(
+            home,
+            '.claude',
+            'projects',
+            session.project,
+            `${session.id}.jsonl`
+          )
+        ),
+      ];
+      const stats = await Promise.all(
+        candidates.map((target) => this.env.stat?.(target))
+      );
+      const activeMs = Math.max(0, ...stats.map((stat) => stat?.mtimeMs ?? 0));
+      this.agentSessions.set(session.dir, { ...session, activeMs });
+    }
+  }
+
+  /** A path inside the scratchpad of a Claude Code session active recently. */
+  agentSessionUsage(paths) {
+    for (const target of paths) {
+      const session = this.agentSessions.get(
+        agentSessionOf(target, this.env.path)?.dir
+      );
+      if (!session) {
+        continue;
+      }
+      const age = this.now() - session.activeMs;
+      if (session.activeMs && age >= this.inactiveMs) {
+        continue;
+      }
+      const active = session.activeMs
+        ? `active ${formatDuration(Math.max(age, 0))} ago`
+        : 'activity unknown';
+      return `inside the scratchpad of Claude Code session ${session.id.slice(0, 8)} (${active}); kept until it is idle for ${formatDuration(this.inactiveMs)}`;
+    }
+    return null;
+  }
+
   recentWrite(newestMtimeMs) {
     if (!newestMtimeMs || this.staleAgeMs <= 0) {
       return null;
@@ -611,16 +718,17 @@ export class LivenessProbe {
    */
   busyReason(item) {
     const checks = item.checks ?? {};
-    const paths = checks.perPath ? [] : (item.paths ?? []);
+    const all = item.paths ?? [];
     return (
-      this.installationBlocker(item.paths ?? []) ??
+      this.installationBlocker(all) ??
       this.probeBlocker() ??
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
+      this.agentSessionUsage(all) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
-      this.appUsage(item.paths ?? []) ??
-      this.processUsage(paths) ??
+      this.appUsage(all) ??
+      this.processUsage(checks.perPath ? [] : all) ??
       this.executableUsage(checks.executables) ??
-      this.uncertainUsage(item.paths ?? [])
+      this.uncertainUsage(all)
     );
   }
 

package/src/report.js

@@ -438,7 +438,8 @@ function holderLine(holder) {
       `${change > 0 ? '+' : '-'}${formatBytes(Math.abs(change))} since ${new Date(holder.growth.since).toISOString()}`
     );
   }
-  return `${holder.pid} ${holder.command}: ${details.join(', ')}`;
+  const self = holder.self ? ' (this dss run)' : '';
+  return `${holder.pid} ${holder.command}${self}: ${details.join(', ')}`;
 }
 
 function swapLines(swap) {
@@ -617,7 +618,9 @@ export function formatAudit(audit, options = {}) {
       ...conditionsSection(audit.blocked, options).slice(2)
     );
   }
-  if (audit.file) {
+  if (audit.auditError) {
+    lines.push(`Audit log: not written (${audit.auditError.message})`);
+  } else if (audit.file) {
     lines.push(`Audit log: ${audit.file}`);
   }
   return lines.join('\n');

package/src/rules/downloads.js

@@ -184,4 +184,31 @@ export const DOWNLOAD_RULES = [
     ],
     minAge: 'stale',
   },
+  {
+    id: 'crashpad-pending-reports',
+    ecosystem: 'system',
+    description:
+      'Chromium and Electron app crash reports never sent: after a month no app uploads them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: [
+      '~/Library/Application Support/*/Crashpad/pending/*',
+      ...['Google', 'Yandex', 'BraveSoftware'].map(
+        (vendor) =>
+          `~/Library/Application Support/${vendor}/*/Crashpad/pending/*`
+      ),
+      '~/.config/*/Crashpad/pending/*',
+    ],
+    minAge: 'inactive',
+  },
+  {
+    id: 'gh-run-log-cache',
+    ecosystem: 'system',
+    description:
+      'GitHub CLI cached workflow run logs: gh downloads them again while GitHub keeps them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: ['~/.cache/gh/run-log-*.zip'],
+    minAge: 'stale',
+  },
 ];

package/src/rules/other.js

@@ -414,6 +414,15 @@ export const OTHER_RULES = [
     aggregate: true,
     paths: ['~/Library/Logs/DiagnosticReports/*'],
   },
+  {
+    id: 'rotated-app-logs',
+    ecosystem: 'system',
+    description:
+      'rotated app logs (warp.log.old.2, app.log.1): apps write only the current log',
+    tier: 'moderate',
+    paths: ['~/Library/Logs/*.log.*', '~/Library/Logs/*/*.log.*'],
+    minAge: 'stale',
+  },
   {
     id: 'apt-archives',
     ecosystem: 'system',

package/src/scan.js

@@ -173,6 +173,7 @@ export async function environmentContext(env, options, overrides = {}) {
   });
   const liveness = new LivenessProbe(env, {
     staleAgeMs: options.staleAgeMs,
+    inactiveMs: options.inactiveMs,
     now: options.now,
   });
   await liveness.refresh(true);

package/src/scanners/node-modules.js

@@ -0,0 +1,89 @@
+/**
+ * A node_modules directory is regenerable only as far as package managers
+ * fill it. Other data kept there (verification runs, evidence, hand-made
+ * fixtures) survives no reinstall, so it keeps the whole directory.
+ */
+
+import { formatBytes } from '../units.js';
+
+/**
+ * Top-level entries package managers and the tools they run create:
+ * links, lockfile copies, store and workspace state, and caches that
+ * re-create themselves.
+ */
+const MANAGED_ENTRIES = new Set([
+  '.bin',
+  '.package-lock.json',
+  '.modules.yaml',
+  '.pnpm',
+  '.pnpm-workspace-state.json',
+  '.pnpm-workspace-state-v1.json',
+  '.yarn-state.yml',
+  '.yarn-integrity',
+  '.yarn-metadata.json',
+  '.store',
+  '.staging',
+  '.ignored',
+  '.cache',
+  '.vite',
+  '.vite-temp',
+  '.vitest',
+  '.vitest-cache',
+  '.deno',
+  '.prisma',
+  '.astro',
+  '.mf',
+  '.tmp',
+  '.DS_Store',
+]);
+
+/**
+ * Entries of `dir` no package manager installs, with their size; empty
+ * leftovers are left out.
+ * @returns {Promise<Array<{name: string, bytes: number}>>}
+ */
+export async function foreignEntries(env, dir) {
+  const candidates = [];
+  for (const entry of await env.list(dir)) {
+    if (
+      MANAGED_ENTRIES.has(entry.name) ||
+      entry.name.startsWith('@') ||
+      entry.type === 'symlink'
+    ) {
+      continue;
+    }
+    if (
+      entry.type === 'dir' &&
+      (await env.stat(env.path.join(entry.path, 'package.json')))
+    ) {
+      continue;
+    }
+    candidates.push(entry);
+  }
+  if (candidates.length === 0) {
+    return [];
+  }
+  const usages = await env.usageMany(
+    candidates.map((entry) => entry.path),
+    { cache: true }
+  );
+  return candidates
+    .map((entry) => ({ name: entry.name, usage: usages.get(entry.path) }))
+    .filter(({ usage }) => usage && (usage.files ?? 1) > 0)
+    .map(({ name, usage }) => ({ name, bytes: usage.bytes }))
+    .sort((a, b) => b.bytes - a.bytes);
+}
+
+/** Blocker naming the foreign data inside `dir`, or null. */
+export async function foreignDataBlocker(env, dir) {
+  const foreign = await foreignEntries(env, dir);
+  if (foreign.length === 0) {
+    return null;
+  }
+  const names = foreign
+    .slice(0, 3)
+    .map((entry) => `${entry.name} (${formatBytes(entry.bytes)})`)
+    .join(', ');
+  const more = foreign.length > 3 ? ` and ${foreign.length - 3} more` : '';
+  return `holds data no package manager installs: ${names}${more}; a reinstall does not re-create it, so move it out of node_modules first`;
+}

package/src/scanners/projects.js

@@ -23,6 +23,7 @@ import { block, makeItem } from '../items.js';
 import { isWithin, matchesGlob } from '../paths.js';
 import { listMany, scanTimeBusy } from './common.js';
 import { analyzeRustProfile, findRustProfiles } from './rust.js';
+import { foreignDataBlocker } from './node-modules.js';
 import { timed } from '../timings.js';
 
 const ECOSYSTEM_NAMES = new Map(ECOSYSTEMS.map((e) => [e.id, e.name]));
@@ -248,6 +249,14 @@ async function projectItem(context, { candidate, rule }, usage) {
     ...projectTier(rule),
     checks: { busy: rule.busy ?? [], cwd: project, mtime: true },
   });
+  if (rule.id === 'node-modules') {
+    block(
+      item,
+      await timed(context.timings, 'projects:contents', () =>
+        foreignDataBlocker(env, candidate.path)
+      )
+    );
+  }
   await addBlockers(context, item, false);
   return item;
 }

package/src/swap.js

@@ -260,8 +260,11 @@ export function swapWarnings(swap, disk) {
   if (reasons.length === 0) {
     return [];
   }
-  // The kernel (PID 0) cannot be quit, so naming it helps nobody.
-  const candidates = swap.holders.filter((holder) => holder.pid > 0);
+  // The kernel (PID 0) cannot be quit and this dss run ends by itself, so
+  // naming either helps nobody.
+  const candidates = swap.holders.filter(
+    (holder) => holder.pid > 0 && !holder.self
+  );
   const growing = candidates.filter(
     (holder) => holder.growth?.memoryBytes >= GROWTH_WARNING_BYTES
   );
@@ -308,6 +311,10 @@ export async function readSwap(env, options = {}) {
   if (!swap) {
     return null;
   }
+  // This dss run shows up among the holders while it scans; it ends on its own.
+  swap.holders = swap.holders.map((holder) =>
+    holder.pid === process.pid ? { ...holder, self: true } : holder
+  );
   const history = await loadSwapHistory(stateDir, now);
   const grown = withGrowth(swap, history);
   await saveSwapHistory(stateDir, [

package/src/usage.js

@@ -26,6 +26,22 @@ import { formatBytes } from './units.js';
 
 const MiB = 1024 * 1024;
 const GiB = 1024 * MiB;
+const GROUP_PATTERNS = 64;
+const GROUP_MIN_ENTRIES = 10;
+
+/**
+ * The name pattern an entry is grouped under: its leading word and the
+ * separator after it (`ms-tg-creds-a1b2` is `ms-*`), else its extension
+ * (`trace.zip` is `*.zip`), else null.
+ */
+export function namePattern(name) {
+  const word = /^[A-Za-z][A-Za-z0-9]*[-_.]/.exec(name);
+  if (word && word[0].length < name.length) {
+    return `${word[0]}*`;
+  }
+  const extension = /\.[A-Za-z0-9]{1,8}$/.exec(name);
+  return extension ? `*${extension[0]}` : null;
+}
 const DATA_VOLUME = '/System/Volumes/Data';
 const DENIED = /^du: (.+): (Permission denied|Operation not permitted)$/;
 
@@ -52,6 +68,10 @@ export class UsageCollector {
     this.entries = 0;
     this.previous = null;
     this.last = null;
+    // Small entries summed by name pattern, per directory still being
+    // listed, so a directory of many small entries can say what fills it.
+    this.open = new Map();
+    this.groups = new Map();
   }
 
   add(line) {
@@ -64,7 +84,11 @@ export class UsageCollector {
     const isDir = this.previous?.startsWith(prefix) ?? false;
     this.previous = entry.path;
     this.last = entry;
+    if (isDir) {
+      this.#closeDir(entry);
+    }
     if (entry.bytes < this.minBytes) {
+      this.#group(entry);
       return;
     }
     if (isDir) {
@@ -77,6 +101,45 @@ export class UsageCollector {
     }
   }
 
+  #group(entry) {
+    const slash = entry.path.lastIndexOf('/');
+    const pattern = namePattern(entry.path.slice(slash + 1));
+    if (slash <= 0 || !pattern) {
+      return;
+    }
+    const parent = entry.path.slice(0, slash);
+    const groups = this.open.get(parent) ?? new Map();
+    this.open.set(parent, groups);
+    const group = groups.get(pattern);
+    if (group) {
+      group.bytes += entry.bytes;
+      group.count += 1;
+    } else if (groups.size < GROUP_PATTERNS) {
+      groups.set(pattern, { pattern, bytes: entry.bytes, count: 1 });
+    }
+  }
+
+  /** `du` lists a directory after everything inside it. */
+  #closeDir(entry) {
+    const groups = this.open.get(entry.path);
+    if (!groups) {
+      return;
+    }
+    this.open.delete(entry.path);
+    const kept = [...groups.values()].filter(
+      (group) =>
+        group.bytes >= this.minBytes && group.count >= GROUP_MIN_ENTRIES
+    );
+    if (entry.bytes >= this.minBytes && kept.length > 0) {
+      this.groups.set(
+        entry.path,
+        kept
+          .sort((a, b) => b.bytes - a.bytes)
+          .map((group) => ({ ...group, below: this.minBytes }))
+      );
+    }
+  }
+
   #trimFiles() {
     this.files.sort((a, b) => b.bytes - a.bytes);
     this.files.length = Math.min(this.files.length, this.topFiles);
@@ -93,6 +156,7 @@ export class UsageCollector {
       entries: this.entries,
       dirs: this.dirs,
       files: this.files,
+      groups: this.groups,
     };
   }
 }
@@ -417,9 +481,13 @@ function rootReport(result, items, options) {
     [...result.dirs].map(([dir, bytes]) => [show(dir), bytes])
   );
   const rootPath = show(result.root);
+  const groups = new Map(
+    [...(result.groups ?? [])].map(([dir, list]) => [show(dir), list])
+  );
   const annotate = (node) => ({
     ...node,
     dss: summary(scanCoverage(node.path, items)),
+    groups: smallEntries(node, groups.get(node.path), minBytes),
     children: node.children.map(annotate),
   });
   const inside = items.filter((item) =>
@@ -458,6 +526,18 @@ function rootReport(result, items, options) {
   };
 }
 
+/**
+ * Groups of small entries worth naming in `node`: those as large as a
+ * shown directory, when the shown subdirectories leave much of it unnamed.
+ */
+function smallEntries(node, groups, minBytes) {
+  const named = node.children.reduce((sum, child) => sum + child.bytes, 0);
+  if (!groups || named >= node.bytes * 0.5) {
+    return [];
+  }
+  return groups.filter((group) => group.bytes >= minBytes).slice(0, 5);
+}
+
 function summary(coverage) {
   return {
     rule: coverage.item?.rule ?? null,
@@ -517,9 +597,15 @@ function treeLines(node, depth = 0) {
   ) {
     return treeLines(only, depth);
   }
+  const indent = '  '.repeat(depth + 1);
+  const separator = node.path.endsWith('/') ? '' : '/';
   return [
     `${formatBytes(node.bytes).padStart(10)}  ${'  '.repeat(depth)}${node.path}${dssNote(node.dss)}`,
     ...node.children.flatMap((child) => treeLines(child, depth + 1)),
+    ...(node.groups ?? []).map(
+      (group) =>
+        `${formatBytes(group.bytes).padStart(10)}  ${indent}${node.path}${separator}${group.pattern}  (${group.count.toLocaleString('en-US')} entries, each under ${formatBytes(group.below)})`
+    ),
   ];
 }