disk-space-saviour 0.20.0 → 0.22.0

package/src/scanners/app-clones.js

@@ -0,0 +1,53 @@
+/**
+ * Chromium browsers on macOS clone their app bundle at launch with APFS
+ * `clonefile` and replace the clone's main executable with a hard link to
+ * the installed one (chrome/browser/mac/code_sign_clone_manager.mm). The
+ * browser holds no file open inside its clone: it runs the shared inode,
+ * which `lsof` reports under the installed path until an update replaces
+ * the app. After an update the clone keeps the running browser's code
+ * signature valid, so a clone stays while any process runs its executable.
+ * Until then the clone shares every block with the installed app, and
+ * removing it frees nothing but directory entries.
+ */
+
+const BUNDLE_SUFFIX = '.bundle';
+
+/**
+ * Main executables of the bundle cloned in `clone`, and whether the clone
+ * still shares its blocks with an app installed in one of `appDirs`.
+ * @returns {Promise<{executables: string[], sharedWith: string|null}>}
+ */
+export async function appCloneDetails(env, clone, appDirs) {
+  const executables = [];
+  let sharedWith = null;
+  for (const bundle of await env.list(clone)) {
+    if (
+      bundle.type !== 'dir' ||
+      !bundle.name.endsWith(`.app${BUNDLE_SUFFIX}`)
+    ) {
+      continue;
+    }
+    const appName = bundle.name.slice(0, -BUNDLE_SUFFIX.length);
+    const macos = env.path.join(bundle.path, 'Contents', 'MacOS');
+    for (const entry of await env.list(macos)) {
+      if (entry.type !== 'file') {
+        continue;
+      }
+      executables.push(entry.path);
+      sharedWith ??= await installedCopy(env, entry, appName, appDirs);
+    }
+  }
+  return { executables, sharedWith };
+}
+
+async function installedCopy(env, executable, appName, appDirs) {
+  const inode = (await env.stat(executable.path))?.inode;
+  for (const dir of appDirs) {
+    const app = env.path.join(dir, appName);
+    const installed = env.path.join(app, 'Contents', 'MacOS', executable.name);
+    if (inode && (await env.stat(installed))?.inode === inode) {
+      return app;
+    }
+  }
+  return null;
+}

package/src/scanners/common.js

@@ -27,6 +27,7 @@ export async function listMany(env, dirs) {
  */
 export async function scanTimeBusy(context, item) {
   await resolvePaths(context, item.paths);
+  await context.liveness?.resolveExecutables(item.checks?.executables);
   return context.liveness ? context.liveness.busyReason(item) : null;
 }
 

package/src/scanners/global.js

@@ -1,4 +1,4 @@
-import { scanItems } from '../env/scope.js';
+import { checkSignal, scanItems } from '../env/scope.js';
 /**
  * Global per-user caches (ecosystem download and compilation caches, IDE and
  * browser caches), system package caches, and leftovers in temporary
@@ -7,7 +7,7 @@ import { scanItems } from '../env/scope.js';
  */
 
 import { CACHE_RULES } from '../rules/ecosystems.js';
-import { OTHER_RULES } from '../rules/other.js';
+import { OTHER_RULES, TEMP_CLONE_RULES } from '../rules/other.js';
 import { APP_RULES, expandChromiumCaches } from '../rules/apps.js';
 import { VERSION_RULES, compareVersions } from '../rules/versions.js';
 import { block, makeItem } from '../items.js';
@@ -17,6 +17,10 @@ import { configuredPattern } from '../env/cache-roots.js';
 import { TOOLCHAIN_CACHE_RULES } from '../rules/toolchains.js';
 import { DOWNLOAD_RULES } from '../rules/downloads.js';
 import { timed } from '../timings.js';
+import { appCloneDetails } from './app-clones.js';
+import { gitDirectories } from '../git.js';
+import { networkRemotes } from '../git-remote.js';
+import { playwrightBlocker } from '../playwright-registry.js';
 
 export const GLOBAL_RULES = [
   ...CACHE_RULES,
@@ -24,6 +28,7 @@ export const GLOBAL_RULES = [
   ...APP_RULES,
   ...TOOLCHAIN_CACHE_RULES,
   ...DOWNLOAD_RULES,
+  ...TEMP_CLONE_RULES,
 ];
 
 function scopeBases(rule, homes, tmpDirs) {
@@ -173,7 +178,13 @@ function olderVersions(env, rule, paths, stats) {
   return paths.filter((target) => old.has(target));
 }
 
-async function buildItem(context, rule, base, group) {
+/** What cleanup re-verifies right before deleting, by the rule's `git` mode. */
+const GIT_RECHECKS = {
+  ifPresent: { type: 'scratch' },
+  clone: { type: 'clone' },
+};
+
+async function buildItem(context, rule, base, group, homes) {
   const { env } = context;
   const paths = group.map((entry) => entry.path);
   const appRoot = rule.markers
@@ -195,7 +206,7 @@ async function buildItem(context, rule, base, group) {
     reason: rule.minAge
       ? `untouched for longer than the ${rule.minAge === 'stale' ? 'activity' : 'inactivity'} window`
       : 're-downloaded or re-created on demand',
-    recheck: rule.git === 'ifPresent' ? { type: 'scratch' } : undefined,
+    recheck: GIT_RECHECKS[rule.git],
     action: action ?? { type: 'none' },
     checks: {
       busy: [
@@ -207,10 +218,35 @@ async function buildItem(context, rule, base, group) {
     },
   });
   block(item, blocker);
+  if (rule.appClone) {
+    await describeAppClone(context, rule, item, homes);
+  }
   await addBlockers(context, rule, item);
   return item;
 }
 
+async function describeAppClone(context, rule, item, homes) {
+  const { env } = context;
+  const appDirs = rule.appClone.installed
+    .flatMap((dir) =>
+      homes.map((home) => expandRulePath(dir, { home, pathApi: env.path }))
+    )
+    .filter(Boolean);
+  const { executables, sharedWith } = await appCloneDetails(env, item.path, [
+    ...new Set(appDirs),
+  ]);
+  item.checks.executables = executables;
+  if (sharedWith) {
+    // Every block is shared with the installed app: nothing to reclaim.
+    // The report lists it under `shared` so the space `du` counts for it
+    // is explained.
+    item.sharedWith = sharedWith;
+    item.apparentBytes = item.bytes;
+    item.bytes = 0;
+    item.reason = `shares its disk blocks with ${sharedWith}`;
+  }
+}
+
 async function addBlockers(context, rule, item) {
   const { env, git } = context;
   if (rule.scope === 'system' && !(await env.isRoot())) {
@@ -218,13 +254,24 @@ async function addBlockers(context, rule, item) {
   }
   if (rule.git) {
     for (const target of item.paths) {
-      for (const reason of await git.treeBlockers(target, {
-        allowNoRepo: rule.git === 'ifPresent',
-      })) {
+      for (const reason of rule.git === 'clone'
+        ? await git.cloneBlockers(target)
+        : await git.treeBlockers(target, {
+            allowNoRepo: rule.git === 'ifPresent',
+          })) {
         block(item, reason);
       }
     }
   }
+  if (rule.registry === 'playwright') {
+    context.playwrightRegistries ??= new Map();
+    for (const target of item.paths) {
+      block(
+        item,
+        await playwrightBlocker(env, target, context.playwrightRegistries)
+      );
+    }
+  }
   const busy = await scanTimeBusy(context, item);
   if (busy) {
     block(item, `busy: ${busy}`);
@@ -292,9 +339,12 @@ export async function scanGlobal(
 
     const accepted = [];
     for (const target of candidates) {
+      // Acceptance can read Git metadata of thousands of temporary entries
+      // without passing through the environment, so honour the budget here.
+      checkSignal(env.signal);
       if (
         !(await timed(context.timings, 'global:accept', () =>
-          acceptedPath(env, rule, target, stats)
+          acceptedPath(env, rule, target, stats, seen)
         ))
       ) {
         continue;
@@ -338,7 +388,7 @@ export async function scanGlobal(
       : measured.filter(large).map((entry) => [entry]);
     for (const group of groups.filter((g) => g.length > 0)) {
       const item = await timed(context.timings, 'global:item', () =>
-        buildItem(context, rule, base, group)
+        buildItem(context, rule, base, group, homes)
       );
       items.push(item);
       if ((await context.ready?.([item])) === false) {
@@ -349,7 +399,40 @@ export async function scanGlobal(
   return items;
 }
 
-async function acceptedPath(env, rule, target, stats) {
+/**
+ * Whether `target` or one of its ancestors is in `claimed`. Both come from
+ * the same glob expansion, so ancestors compare as plain strings and the
+ * cost is the path depth, not the number of claimed paths.
+ */
+function claimedAbove(env, target, claimed) {
+  for (let dir = target; ; dir = env.path.dirname(dir)) {
+    if (claimed.has(dir)) {
+      return true;
+    }
+    if (env.path.dirname(dir) === dir) {
+      return false;
+    }
+  }
+}
+
+/**
+ * A temporary directory holding a Git work tree with a network remote,
+ * outside every path another rule (or a parent clone) already claimed.
+ */
+async function tempClone(env, target, seen) {
+  if (env.kind !== 'host' || claimedAbove(env, target, seen)) {
+    return false;
+  }
+  try {
+    // Other users' temporary directories are unreadable; that is no error.
+    const { commonDir } = await gitDirectories(target);
+    return (await networkRemotes(commonDir)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function acceptedPath(env, rule, target, stats, seen = new Set()) {
   const name = env.path.basename(target);
   if (rule.excludeNames?.includes(name)) {
     return false;
@@ -357,6 +440,9 @@ async function acceptedPath(env, rule, target, stats) {
   if (rule.directoryOnly && stats.get(target)?.type !== 'dir') {
     return false;
   }
+  if (rule.git === 'clone' && !(await tempClone(env, target, seen))) {
+    return false;
+  }
   if (rule.fileOnly && stats.get(target)?.type !== 'file') {
     return false;
   }

package/src/scanners/projects.js

@@ -9,6 +9,9 @@ import { scanItems } from '../env/scope.js';
  * are present. Generic names (`build`, `lib`, `target`, `bin`) that fail
  * every rule are searched again below, with the remaining depth, so a
  * non-matching `build` directory never hides real projects inside it.
+ * Git worktree folders (`.worktrees`, `worktrees`, `.claude/worktrees`)
+ * hold whole checkouts, so the search below them starts with the full
+ * depth again: an agent's worktree deep in a project is a project too.
  *
  * Cargo `target` directories additionally yield `cargo-superseded` items:
  * older build hashes that a newer build of the same unit replaced (see
@@ -23,6 +26,7 @@ import { analyzeRustProfile, findRustProfiles } from './rust.js';
 import { timed } from '../timings.js';
 
 const ECOSYSTEM_NAMES = new Map(ECOSYSTEMS.map((e) => [e.id, e.name]));
+const WORKTREE_DIRS = ['.worktrees', 'worktrees'];
 
 function anyMatch(entries, globs) {
   return (entries ?? []).some((entry) =>
@@ -37,6 +41,13 @@ function depthBelow(env, roots, target) {
   return env.path.relative(root, target).split(/[\\/]/).filter(Boolean).length;
 }
 
+/** Depth left below a directory no rule claims; worktrees start afresh. */
+function remainingDepth(env, dirs, candidate, { depth, maxDepth }) {
+  return WORKTREE_DIRS.includes(candidate.name)
+    ? maxDepth
+    : depth - depthBelow(env, dirs, candidate.path);
+}
+
 function ruleAccepts(env, rule, candidate, selfListing, grandListing) {
   if (rule.markers && !anyMatch(candidate.siblings, rule.markers)) {
     return false;
@@ -139,7 +150,9 @@ async function indexedMatches(env, roots, globs, maxDepth, rules) {
 export async function findProjectDirs(env, roots, options = {}) {
   const rules = options.rules ?? PROJECT_RULES;
   const maxDepth = options.maxDepth ?? 6;
-  const globs = [...new Set(rules.flatMap((rule) => rule.names))];
+  const globs = [
+    ...new Set([...rules.flatMap((rule) => rule.names), ...WORKTREE_DIRS]),
+  ];
   const matches = [];
   const seen = new Set();
   const accept = (match) => {
@@ -171,7 +184,10 @@ export async function findProjectDirs(env, roots, options = {}) {
           }
           continue;
         }
-        const remaining = depth - depthBelow(env, dirs, match.candidate.path);
+        const remaining = remainingDepth(env, dirs, match.candidate, {
+          depth,
+          maxDepth,
+        });
         if (remaining > 0) {
           next.set(remaining, [
             ...(next.get(remaining) ?? []),

package/src/scanners/versions.js

@@ -235,11 +235,13 @@ function referencedInstalls(rule, installs, refs, versionOf) {
 }
 
 /**
- * Global packages a user installed into a version (`npm install -g`) are
- * lost with it. Packages bundled with the runtime and caches that are
- * installed again on demand (`rule.globalPackages.regenerable`) are not.
+ * Global packages a user installed into a version (`npm install -g`) go
+ * with it, so the item names them. Packages bundled with the runtime and
+ * caches installed again on demand (`rule.globalPackages.regenerable`) are
+ * not named. A package that is running keeps the version through the
+ * process checks: its binary, arguments or PATH entry lies inside.
  */
-async function blockGlobalPackages(env, rule, dir, item) {
+async function noteGlobalPackages(env, rule, dir, item) {
   if (!rule.globalPackages) {
     return;
   }
@@ -262,7 +264,8 @@ async function blockGlobalPackages(env, rule, dir, item) {
   if (own.length > 0) {
     const shown = own.slice(0, 5).join(', ');
     const more = own.length > 5 ? ` and ${own.length - 5} more` : '';
-    block(item, `has globally installed packages: ${shown}${more}`);
+    item.globalPackages = own;
+    item.reason += `; also removes its global packages: ${shown}${more}`;
   }
 }
 
@@ -357,7 +360,7 @@ async function ruleItems(context, rule, home, pins) {
           : null,
     });
     await blockPyenvEnvironments(env, rule, dir, item);
-    await blockGlobalPackages(env, rule, dir, item);
+    await noteGlobalPackages(env, rule, dir, item);
     await blockLiveLock(context, rule, home, version, item);
     const busy = await scanTimeBusy(context, item);
     if (busy) {

package/src/swap.js

@@ -1,5 +1,23 @@
-/** Swap is a capacity diagnostic, never a deletion candidate. */
-import { parseSize } from './units.js';
+/**
+ * Swap is a capacity diagnostic, never a deletion candidate. Swap files
+ * live on the system disk, so memory a process keeps but never touches
+ * turns into used disk space. Each scan records swap usage and the largest
+ * memory holders in the state directory; the next scan reports how much
+ * both grew since the oldest sample of the last week.
+ */
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { AGENT_NAMES } from './health.js';
+import { formatBytes, parseSize } from './units.js';
+
+const GIB = 1024 ** 3;
+export const HISTORY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const HISTORY_LIMIT = 200;
+const HOLDER_LIMIT = 10;
+/** Growth below this is noise from normal paging. */
+const GROWTH_WARNING_BYTES = GIB;
+/** A single process holding this much is worth naming in a warning. */
+const LARGE_HOLDER_BYTES = 2 * GIB;
 
 export function parseSwapUsage(text) {
   const match =
@@ -31,39 +49,279 @@ export function parseMemoryHolders(text) {
       compressedBytes: parseSize(match[4].replace(/[+-]$/, '')),
     }))
     .sort((a, b) => b.memoryBytes - a.memoryBytes)
-    .slice(0, 10);
+    .slice(0, HOLDER_LIMIT);
+}
+
+/** Swap totals from `/proc/meminfo`, or null. */
+export function parseMeminfo(text) {
+  const field = (name) => {
+    const match = new RegExp(`^${name}:\\s+(\\d+)\\s*kB`, 'm').exec(text);
+    return match ? Number(match[1]) * 1024 : null;
+  };
+  const total = field('SwapTotal');
+  const free = field('SwapFree');
+  return total === null || free === null || total === 0
+    ? null
+    : { total, used: total - free, free };
+}
+
+/** Name, PID, resident and swapped bytes from a `/proc/<pid>/status`. */
+export function parseProcStatus(text) {
+  const value = (name) => new RegExp(`^${name}:\\s+(.*)$`, 'm').exec(text)?.[1];
+  const kib = (name) => Number(/^(\d+)/.exec(value(name) ?? '')?.[1] ?? 0);
+  const pid = Number(value('Pid'));
+  if (!Number.isInteger(pid)) {
+    return null;
+  }
+  const residentBytes = kib('VmRSS') * 1024;
+  const swappedBytes = kib('VmSwap') * 1024;
+  return {
+    pid,
+    command: value('Name')?.trim() ?? '',
+    memoryBytes: residentBytes + swappedBytes,
+    swappedBytes,
+  };
+}
+
+async function linuxHolders(procRoot) {
+  const pids = (await fsp.readdir(procRoot)).filter((name) =>
+    /^\d+$/.test(name)
+  );
+  const holders = await Promise.all(
+    pids.map((pid) =>
+      fsp
+        .readFile(path.join(procRoot, pid, 'status'), 'utf8')
+        .then(parseProcStatus, () => null)
+    )
+  );
+  return holders
+    .filter((holder) => holder && holder.memoryBytes > 0)
+    .sort(
+      (a, b) => b.swappedBytes - a.swappedBytes || b.memoryBytes - a.memoryBytes
+    )
+    .slice(0, HOLDER_LIMIT);
+}
+
+async function readDarwin(env) {
+  const usage = await env.run(['sysctl', 'vm.swapusage']);
+  const swap = usage.code === 0 ? parseSwapUsage(usage.stdout) : null;
+  if (!swap) {
+    return null;
+  }
+  const top = await env.run([
+    'top',
+    '-l',
+    '1',
+    '-o',
+    'mem',
+    '-n',
+    String(HOLDER_LIMIT),
+    '-stats',
+    'pid,command,mem,cmprs',
+  ]);
+  return {
+    ...swap,
+    holders: top.code === 0 ? parseMemoryHolders(top.stdout) : [],
+    attribution:
+      'Largest memory consumers (memory includes compressed and swapped pages); macOS does not expose per-process swap ownership here.',
+    advice:
+      'If Docker Desktop is consuming memory, restart it after saving running work or lower its VM memory limit. Swap files are managed by macOS; dss never deletes them.',
+  };
 }
 
-export async function readSwap(env) {
-  if (env.kind !== 'host' || env.platform !== 'darwin') {
+async function readLinux(procRoot) {
+  const swap = parseMeminfo(
+    await fsp.readFile(path.join(procRoot, 'meminfo'), 'utf8')
+  );
+  if (!swap) {
     return null;
   }
+  return {
+    ...swap,
+    holders: await linuxHolders(procRoot),
+    attribution:
+      'Processes with the most swapped memory (VmSwap in /proc/<pid>/status), then the most resident memory.',
+    advice:
+      'Swap is managed by the kernel; dss never deletes swap files or partitions.',
+  };
+}
+
+const holderKey = (holder) => `${holder.pid}\0${holder.command}`;
+
+/** Samples of the last week, oldest first; missing state is empty. */
+export async function loadSwapHistory(stateDir, now) {
+  if (!stateDir) {
+    return [];
+  }
+  try {
+    const data = JSON.parse(
+      await fsp.readFile(path.join(stateDir, 'swap-history.json'), 'utf8')
+    );
+    return (Array.isArray(data.samples) ? data.samples : []).filter(
+      (sample) =>
+        Number.isFinite(sample?.time) &&
+        sample.time <= now &&
+        now - sample.time <= HISTORY_WINDOW_MS
+    );
+  } catch {
+    return [];
+  }
+}
+
+async function saveSwapHistory(stateDir, samples) {
+  if (!stateDir) {
+    return;
+  }
   try {
-    const usage = await env.run(['sysctl', 'vm.swapusage']);
-    const swap = usage.code === 0 ? parseSwapUsage(usage.stdout) : null;
-    if (!swap) {
-      return null;
+    await fsp.mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const file = path.join(stateDir, 'swap-history.json');
+    const temporary = `${file}.${process.pid}`;
+    await fsp.writeFile(
+      temporary,
+      JSON.stringify({ schema: 1, samples: samples.slice(-HISTORY_LIMIT) }),
+      { mode: 0o600 }
+    );
+    await fsp.rename(temporary, file);
+  } catch {
+    // History only adds growth figures; a read-only state dir loses them.
+  }
+}
+
+/**
+ * Adds swap and per-holder growth since the oldest sample of `history`.
+ * A holder's baseline is the oldest sample that lists the same PID and
+ * command, so a restarted process starts over.
+ */
+export function withGrowth(swap, history) {
+  const baseline = history[0];
+  const firstSeen = new Map();
+  for (const sample of history) {
+    for (const holder of sample.holders ?? []) {
+      if (!firstSeen.has(holderKey(holder))) {
+        firstSeen.set(holderKey(holder), { time: sample.time, ...holder });
+      }
+    }
+  }
+  return {
+    ...swap,
+    growth: baseline
+      ? { since: baseline.time, usedBytes: swap.used - baseline.used }
+      : null,
+    holders: swap.holders.map((holder) => {
+      const first = firstSeen.get(holderKey(holder));
+      return first
+        ? {
+            ...holder,
+            growth: {
+              since: first.time,
+              memoryBytes: holder.memoryBytes - first.memoryBytes,
+            },
+          }
+        : holder;
+    }),
+  };
+}
+
+const isAgent = (holder) =>
+  AGENT_NAMES.includes(holder.command.trim().toLowerCase());
+
+function holderSummary(holder) {
+  const grew =
+    holder.growth?.memoryBytes > 0
+      ? `, +${formatBytes(holder.growth.memoryBytes)} since ${new Date(holder.growth.since).toISOString()}`
+      : '';
+  return `${holder.command} (pid ${holder.pid}): ${formatBytes(holder.memoryBytes)}${grew}`;
+}
+
+/**
+ * Warnings for swap that is large, growing, or larger than the free disk
+ * space it can grow into, naming the processes that hold the memory.
+ * @param {object} swap result of `withGrowth`
+ * @param {{free: number}|null} disk
+ * @returns {string[]}
+ */
+export function swapWarnings(swap, disk) {
+  const reasons = [];
+  if (swap.growth && swap.growth.usedBytes >= GROWTH_WARNING_BYTES) {
+    reasons.push(
+      `grew by ${formatBytes(swap.growth.usedBytes)} since ${new Date(swap.growth.since).toISOString()}`
+    );
+  }
+  if (swap.total > 0 && swap.used >= GIB && swap.used >= 0.75 * swap.total) {
+    reasons.push(
+      `is ${Math.round((100 * swap.used) / swap.total)}% full, so the system adds swap files on disk when memory demand grows`
+    );
+  }
+  if (disk && swap.used >= GIB && disk.free < swap.used) {
+    reasons.push(
+      `has only ${formatBytes(disk.free)} of free disk to grow into, less than the ${formatBytes(swap.used)} already used`
+    );
+  }
+  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);
+  const growing = candidates.filter(
+    (holder) => holder.growth?.memoryBytes >= GROWTH_WARNING_BYTES
+  );
+  const large = candidates.filter(
+    (holder) => holder.memoryBytes >= LARGE_HOLDER_BYTES
+  );
+  const named = [...new Set([...growing, ...large])].slice(0, 5);
+  const warnings = [`Swap ${reasons.join('; ')}.`];
+  if (named.length > 0) {
+    warnings.push(
+      `Memory held by: ${named.map(holderSummary).join('; ')}. Quitting or restarting them frees that swap and its disk space.`
+    );
+  }
+  if (named.some(isAgent)) {
+    warnings.push(
+      'Long-running AI agent sessions keep their history in memory: quit the session and resume it (for example `codex resume <session-id>` or `claude --resume`) to release it without losing the conversation.'
+    );
+  }
+  return warnings;
+}
+
+/**
+ * Swap usage, its largest memory holders, growth since earlier scans and
+ * warnings; null where swap cannot be read.
+ * @param {object} env
+ * @param {{stateDir?: string|false, disk?: object|null, now?: number,
+ *   procRoot?: string}} [options]
+ */
+export async function readSwap(env, options = {}) {
+  if (env.kind !== 'host') {
+    return null;
+  }
+  const { stateDir, disk = null, now = Date.now() } = options;
+  let swap = null;
+  try {
+    if (env.platform === 'darwin') {
+      swap = await readDarwin(env);
+    } else if (env.platform === 'linux') {
+      swap = await readLinux(options.procRoot ?? '/proc');
     }
-    const top = await env.run([
-      'top',
-      '-l',
-      '1',
-      '-o',
-      'mem',
-      '-n',
-      '10',
-      '-stats',
-      'pid,command,mem,cmprs',
-    ]);
-    return {
-      ...swap,
-      holders: top.code === 0 ? parseMemoryHolders(top.stdout) : [],
-      attribution:
-        'Largest resident/compressed memory consumers; macOS does not expose per-process swap ownership here.',
-      advice:
-        'If Docker Desktop is consuming memory, restart it after saving running work or lower its VM memory limit. Swap files are managed by macOS; dss never deletes them.',
-    };
   } catch {
+    swap = null;
+  }
+  if (!swap) {
     return null;
   }
+  const history = await loadSwapHistory(stateDir, now);
+  const grown = withGrowth(swap, history);
+  await saveSwapHistory(stateDir, [
+    ...history,
+    {
+      time: now,
+      used: swap.used,
+      total: swap.total,
+      holders: swap.holders.map(({ pid, command, memoryBytes }) => ({
+        pid,
+        command,
+        memoryBytes,
+      })),
+    },
+  ]);
+  return { ...grown, warnings: swapWarnings(grown, disk) };
 }