disk-space-saviour 0.16.0 → 0.18.0

package/src/git.js

@@ -36,36 +36,77 @@ const SAFE_GIT_ENV = {
   GIT_TERMINAL_PROMPT: '0',
 };
 
-/** A metadata-only Git directory, with no repository-supplied config or hooks. */
-async function safeGitDirectory(root, callback) {
-  const source = path.join(root, '.git');
-  const stat = await fsp.lstat(source);
-  if (!stat.isDirectory()) {
-    throw new Error('cannot safely inspect a linked Git worktree');
+/**
+ * The checkout's own Git directory (HEAD, index) and the common directory
+ * holding refs and objects. Both are `<root>/.git` in a plain repository;
+ * a linked worktree or a submodule has a `.git` file naming its directory,
+ * and a linked worktree names the common directory in `commondir`.
+ */
+async function gitDirectories(root) {
+  const dotGit = path.join(root, '.git');
+  const stat = await fsp.lstat(dotGit);
+  let gitDir = dotGit;
+  if (stat.isFile()) {
+    const named = /^gitdir: (.+)$/m.exec(await fsp.readFile(dotGit, 'utf8'));
+    if (!named) {
+      throw new Error(`${dotGit} does not name a Git directory`);
+    }
+    gitDir = path.resolve(root, named[1].trim());
+  } else if (!stat.isDirectory()) {
+    throw new Error(`${dotGit} is neither a directory nor a gitdir file`);
+  }
+  const commonDir = await fsp
+    .readFile(path.join(gitDir, 'commondir'), 'utf8')
+    .then(
+      (text) => path.resolve(gitDir, text.trim()),
+      (error) => {
+        if (error.code === 'ENOENT') {
+          return gitDir;
+        }
+        throw error;
+      }
+    );
+  if (!(await fsp.stat(path.join(commonDir, 'objects'))).isDirectory()) {
+    throw new Error(`${commonDir} has no object database`);
+  }
+  return { gitDir, commonDir };
+}
+
+async function copyGitMetadata(source, dir, names, force) {
+  for (const name of names) {
+    await fsp
+      .cp(path.join(source, name), path.join(dir, name), {
+        recursive: true,
+        force,
+        errorOnExist: !force,
+      })
+      .catch((error) => {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      });
   }
+}
+
+/**
+ * A metadata-only Git directory, with no repository-supplied config or hooks.
+ * With `indexOnly`, refs and reflogs are left out: enough for `ls-files`,
+ * which reads only HEAD, the index and the work tree.
+ */
+async function safeGitDirectory(root, callback, { indexOnly = false } = {}) {
+  const { gitDir, commonDir } = await gitDirectories(root);
   const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'dss-safe-git-'));
   try {
-    for (const name of [
-      'HEAD',
-      'index',
-      'packed-refs',
-      'shallow',
-      'refs',
-      'logs',
-    ]) {
-      await fsp
-        .cp(path.join(source, name), path.join(dir, name), {
-          recursive: true,
-          force: false,
-          errorOnExist: true,
-        })
-        .catch((error) => {
-          if (error.code !== 'ENOENT') {
-            throw error;
-          }
-        });
+    if (indexOnly) {
+      await copyGitMetadata(gitDir, dir, ['HEAD', 'index'], false);
+      await fsp.mkdir(path.join(dir, 'refs'));
+    } else {
+      await copyIndexAndRefs(gitDir, commonDir, dir);
     }
-    await fsp.symlink(path.join(source, 'objects'), path.join(dir, 'objects'));
+    await fsp.symlink(
+      path.join(commonDir, 'objects'),
+      path.join(dir, 'objects')
+    );
     await fsp.writeFile(
       path.join(dir, 'config'),
       '[core]\n\trepositoryformatversion = 0\n\tbare = false\n'
@@ -76,6 +117,24 @@ async function safeGitDirectory(root, callback) {
   }
 }
 
+async function copyIndexAndRefs(gitDir, commonDir, dir) {
+  await copyGitMetadata(
+    commonDir,
+    dir,
+    ['packed-refs', 'shallow', 'refs', 'logs'],
+    false
+  );
+  // Per-worktree state overrides the shared refs and reflogs.
+  await copyGitMetadata(
+    gitDir,
+    dir,
+    gitDir === commonDir
+      ? ['HEAD', 'index']
+      : ['HEAD', 'index', 'refs', 'logs'],
+    true
+  );
+}
+
 function countLines(text) {
   return text.split('\n').filter((line) => line.trim() !== '').length;
 }
@@ -310,19 +369,22 @@ export class GitInspector {
     try {
       const result =
         this.env.kind === 'host'
-          ? await safeGitDirectory(root, (safeDir) =>
-              this.#git(
-                root,
-                [
-                  'ls-files',
-                  '--cached',
-                  '--others',
-                  '--exclude-standard',
-                  '--',
-                  relative,
-                ],
-                safeDir
-              )
+          ? await safeGitDirectory(
+              root,
+              (safeDir) =>
+                this.#git(
+                  root,
+                  [
+                    'ls-files',
+                    '--cached',
+                    '--others',
+                    '--exclude-standard',
+                    '--',
+                    relative,
+                  ],
+                  safeDir
+                ),
+              { indexOnly: true }
             )
           : await this.#git(root, [
               'ls-files',

package/src/health.js

@@ -107,9 +107,9 @@ function describe(lost) {
  * Per-environment snapshots and re-checks. `records` is the audit view.
  */
 export class HealthWatch {
-  constructor() {
-    this.records = [];
-    this.byEnv = new Map();
+  constructor(records = []) {
+    this.records = [...records];
+    this.byEnv = new Map(records.map((record) => [record.env, record]));
   }
 
   /**

package/src/index.d.ts

@@ -13,19 +13,28 @@ export interface ScanOptions {
   maxDepth?: number;
   /** Time budget per filesystem environment (`2m`); incomplete findings are kept. */
   scanBudget?: Duration;
+  /** Persistent scan/index directory. Library default is false; CLI uses XDG state. */
+  cacheDir?: string | false;
+  /** Use verified Spotlight/locate hints before the discovery walk. */
+  platformIndex?: boolean;
   signal?: AbortSignal;
   onScanProgress?: (progress: {
     env: string;
     scanner: string;
     elapsedMs: number;
     items: number;
+    candidates: number;
+    filesSized: number;
+    directoriesSized: number;
+    indexHits: number;
+    sizeCacheHits: number;
     status: string;
   }) => void;
   /** Activity window: newer files are kept (`1h`). */
   staleAge?: Duration;
   /** Alias of `staleAge`. */
   olderThan?: Duration;
-  /** Inactivity before lockfile-backed node_modules become `safe`, other dependency dirs `moderate` (`30d`). */
+  /** Idle time before agent scratch and similar leftovers count as abandoned (`30d`). Project build and dependency directories do not depend on it. */
   inactive?: Duration;
   /** Items smaller than this are dropped (`1M`). */
   minSize?: Size;
@@ -109,6 +118,8 @@ export interface Item {
   path: string | null;
   paths: string[];
   bytes: number;
+  /** Cached size is advisory; cleanup always measures again. */
+  sizeEstimated?: boolean;
   /** Merged filesystem bytes, including image data, when measured in Docker. */
   totalBytes?: number;
   /** Immutable image bytes excluded from reclaimable totals. */
@@ -154,9 +165,23 @@ export interface EnvironmentDescriptor {
   chain: Array<{ containerId: string; name: string }>;
   hint?: string | null;
   disk?: Disk | null;
+  swap?: {
+    total: number;
+    used: number;
+    free: number;
+    holders: Array<{
+      pid: number;
+      command: string;
+      memoryBytes: number;
+      compressedBytes: number;
+    }>;
+    attribution: string;
+    advice: string;
+  } | null;
   scanStatus?:
     | 'scanning'
     | 'complete'
+    | 'goal-reached'
     | 'aborted'
     | 'budget-exceeded'
     | 'error'
@@ -178,6 +203,7 @@ export interface Report {
   createdAt: string;
   durationMs: number;
   aborted?: boolean;
+  authentication?: { hostname: string; uid: number | string; digest: string };
   audit?: { file: string | null; error: string; code?: string };
   host: { env: string; label: string; platform: string };
   options: Record<string, unknown>;
@@ -235,6 +261,7 @@ export interface AuditLog {
   startedAt: string;
   finishedAt: string | null;
   aborted?: boolean;
+  report?: Partial<Report>;
   error?: string;
   entries: AuditEntry[];
   freedBytes: number;

package/src/liveness.js

@@ -8,7 +8,9 @@
  * - a process holds a file, working directory, or executable inside the path
  *   (`/proc/<pid>/{fd,cwd,exe}` on Linux, `lsof` on macOS).
  * - a command argument names a path inside the item (including scripts
- *   whose interpreter has already closed its input descriptor).
+ *   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.
  *
  * The cleaner refreshes the probe right before acting on each item.
  */
@@ -20,6 +22,44 @@ import { formatDuration } from './units.js';
 
 const PROC_COMM_LIMIT = 15;
 
+/** Bun subcommands that read or write the install cache. */
+const BUN_PACKAGE_COMMANDS = new Set([
+  'install',
+  'i',
+  'add',
+  'a',
+  'remove',
+  'rm',
+  'update',
+  'upgrade',
+  'outdated',
+  'link',
+  'unlink',
+  'pm',
+  'x',
+  'create',
+  'c',
+  'init',
+  'patch',
+  'publish',
+  'audit',
+  'why',
+  'info',
+]);
+
+function isBun(proc) {
+  return Boolean(matchingName(proc, ['bun', 'bunx']));
+}
+
+function bunPackageCommand(proc) {
+  const args = processArgs(proc);
+  if (path.posix.basename(args[0] ?? '') === 'bunx' || proc.name === 'bunx') {
+    return true;
+  }
+  const command = args.slice(1).find((arg) => !arg.startsWith('-'));
+  return BUN_PACKAGE_COMMANDS.has(command);
+}
+
 function uncertaintyRoots(proc) {
   const roots = processArgs(proc).flatMap((arg) => {
     const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
@@ -182,6 +222,7 @@ export class LivenessProbe {
     const processes = await this.env.processes().catch(() => null);
     this.listed = processes !== null;
     this.processes = processes ?? [];
+    this.bunCacheUsers = await this.#bunCacheUsers();
     this.probeError =
       (processes === null || this.openPaths === null) &&
       (this.env.platform === 'linux' || this.env.platform === 'darwin');
@@ -191,6 +232,49 @@ export class LivenessProbe {
     this.pathOwners.clear();
   }
 
+  /**
+   * Pids of Bun processes that may use the install cache: package commands,
+   * and anything else (scripts, tests, the REPL) without a `node_modules`
+   * directory above its working directory, because Bun then auto-installs
+   * from the cache. A long-running script of an installed project does not
+   * read the cache, so it does not keep the cache busy.
+   */
+  async #bunCacheUsers() {
+    const users = new Set();
+    const installed = new Map();
+    const hasModules = async (dir) => {
+      if (!installed.has(dir)) {
+        installed.set(
+          dir,
+          Boolean(
+            await this.env.exists?.(this.env.path.join(dir, 'node_modules'))
+          )
+        );
+      }
+      return installed.get(dir);
+    };
+    for (const proc of this.processes) {
+      if (!isBun(proc)) {
+        continue;
+      }
+      if (bunPackageCommand(proc) || !proc.cwd || !this.env.exists) {
+        users.add(proc.pid);
+        continue;
+      }
+      let found = false;
+      for (const dir of [proc.cwd, ...ancestors(proc.cwd, this.env.path)]) {
+        if (await hasModules(dir)) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        users.add(proc.pid);
+      }
+    }
+    return users;
+  }
+
   /** Processes of the last refresh, or null when they could not be listed. */
   processList() {
     return this.listed ? this.processes : null;
@@ -269,6 +353,13 @@ export class LivenessProbe {
       ) {
         continue;
       }
+      if (
+        item.rule === 'bun-cache' &&
+        isBun(proc) &&
+        !this.bunCacheUsers?.has(proc.pid)
+      ) {
+        continue;
+      }
       const name = matchingName(proc, names);
       if (!name) {
         continue;
@@ -291,10 +382,7 @@ export class LivenessProbe {
       return null;
     }
     const pathApi = this.env.path;
-    const targets = paths.flatMap((target) => {
-      const real = this.realPaths.get(target);
-      return real && real !== target ? [target, real] : [target];
-    });
+    const targets = this.withRealPaths(paths);
     for (const open of this.openPaths) {
       for (const target of targets) {
         if (isWithin(open, target, pathApi)) {
@@ -340,6 +428,26 @@ export class LivenessProbe {
     return null;
   }
 
+  /** `paths` plus their resolved forms, as processes report paths. */
+  withRealPaths(paths) {
+    return paths.flatMap((target) => {
+      const real = this.realPaths.get(target);
+      return real && real !== target ? [target, real] : [target];
+    });
+  }
+
+  searchPathUsage(paths) {
+    const targets = this.withRealPaths(paths);
+    for (const proc of this.processes) {
+      for (const dir of proc.searchPath ?? []) {
+        if (targets.some((target) => isWithin(dir, target, this.env.path))) {
+          return `on the PATH of ${proc.name || 'a process'} (pid ${proc.pid}): ${dir}`;
+        }
+      }
+    }
+    return null;
+  }
+
   uncertainUsage(paths) {
     for (const proc of this.env.unreadableProcesses ?? []) {
       const args = processArgs(proc);
@@ -399,14 +507,28 @@ export class LivenessProbe {
     const paths = checks.perPath ? [] : (item.paths ?? []);
     return (
       this.installationBlocker(item.paths ?? []) ??
-      (this.probeError
-        ? `cannot verify process and open-file activity${this.env.probeDiagnostic ? `: ${this.env.probeDiagnostic}` : ''}`
-        : null) ??
+      this.probeBlocker() ??
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
+      this.processUsage(paths) ??
+      this.uncertainUsage(item.paths ?? [])
+    );
+  }
+
+  probeBlocker() {
+    if (!this.probeError) {
+      return null;
+    }
+    const diagnostic = this.env.probeDiagnostic;
+    return `cannot verify process and open-file activity${diagnostic ? `: ${diagnostic}` : ''}`;
+  }
+
+  /** Open files, command arguments and PATH entries inside the paths. */
+  processUsage(paths) {
+    return (
       this.openInside(paths) ??
       this.commandUsage(paths) ??
-      this.uncertainUsage(item.paths ?? [])
+      this.searchPathUsage(paths)
     );
   }
 

package/src/options.js

@@ -16,7 +16,7 @@ export const DEFAULTS = {
   docker: null,
   dockerDepth: 3,
   containers: [],
-  scanners: ['projects', 'global', 'versions', 'agents', 'system'],
+  scanners: ['global', 'projects', 'versions', 'agents', 'system'],
   only: [],
   exclude: [],
   includeVolumes: false,
@@ -33,6 +33,8 @@ export const DEFAULTS = {
   backupDir: null,
   auditDir: null,
   scanBudget: '2m',
+  cacheDir: false,
+  platformIndex: true,
 };
 
 function toBytes(value) {

package/src/report.js

@@ -56,7 +56,7 @@ function itemLine(item, showEnv) {
     : item.imageBytes
       ? `  (${formatBytes(item.imageBytes)} in image${item.imageRef ? ` ${item.imageRef}` : ''}; 0 B of that data freeable now; remove the stopped container and unused image after the task completes)`
       : '';
-  return `  ${pad(formatBytes(item.bytes), 10)}  ${env}${item.rule}  ${itemLocation(item)}${confirm}${storage}`;
+  return `  ${pad(formatBytes(item.bytes), 10)}${item.sizeEstimated ? ' (estimated)' : ''}  ${env}${item.rule}  ${itemLocation(item)}${confirm}${storage}`;
 }
 
 function limited(lines, limit) {
@@ -305,6 +305,52 @@ function errorsSection(errors) {
   ];
 }
 
+const TIMING_LIMIT = 5;
+
+function phaseList(phases) {
+  return phases
+    .map(
+      (phase) =>
+        `${phase.phase} ${(phase.ms / 1000).toFixed(1)}s${phase.count > 1 ? ` ×${phase.count}` : ''}`
+    )
+    .join(', ');
+}
+
+/**
+ * Slowest cleanup phases and items. `audit.timings` is a live PhaseTimer
+ * while cleaning and a plain array once read back from JSON.
+ */
+function auditTimingLines(audit, { verbose }) {
+  const phases = audit.timings?.toJSON?.() ?? audit.timings ?? [];
+  const items = audit.entries
+    .filter((entry) => entry.durationMs > 0)
+    .sort((a, b) => b.durationMs - a.durationMs);
+  const limit = verbose ? Infinity : TIMING_LIMIT;
+  const lines = [];
+  if (phases.length > 0) {
+    lines.push(`  slowest phases: ${phaseList(phases.slice(0, limit))}`);
+  }
+  for (const entry of items.slice(0, limit)) {
+    lines.push(
+      `  ${(entry.durationMs / 1000).toFixed(1)}s  ${entry.rule}  ${entry.path ?? entry.description}`
+    );
+  }
+  return lines.length > 0 ? ['', 'TIMINGS', ...lines] : [];
+}
+
+/**
+ * The slowest phases of each environment, so bottlenecks are visible
+ * without debug flags.
+ */
+function timingLines(report, { verbose }) {
+  return report.environments
+    .filter((env) => env.timings?.length > 0)
+    .map((env) => {
+      const phases = verbose ? env.timings : env.timings.slice(0, TIMING_LIMIT);
+      return `  ${env.label} slowest phases: ${phaseList(phases)}`;
+    });
+}
+
 /**
  * Renders a scan report.
  * @param {object} report
@@ -318,6 +364,18 @@ export function formatReport(report, options = {}) {
     `disk-space-saviour scan of ${host.label} in ${(report.durationMs / 1000).toFixed(1)}s (report only, nothing was deleted)`,
     formatDisk(host.disk),
   ];
+  if (host.swap) {
+    lines.push(
+      `Swap: ${formatBytes(host.swap.used)} used of ${formatBytes(host.swap.total)} (managed by macOS)`
+    );
+    lines.push(host.swap.attribution);
+    for (const holder of host.swap.holders) {
+      lines.push(
+        `  ${holder.pid} ${holder.command}: ${formatBytes(holder.memoryBytes)} memory, ${formatBytes(holder.compressedBytes)} compressed`
+      );
+    }
+    lines.push(host.swap.advice);
+  }
   for (const tier of TIERS) {
     lines.push(...tierSection(report, tier, { limit }));
   }
@@ -325,7 +383,11 @@ export function formatReport(report, options = {}) {
     if (env.layerSource) {
       lines.push(`  ${env.label}: layer source ${env.layerSource}`);
     }
-    if (env.scanStatus && env.scanStatus !== 'complete') {
+    if (env.scanStatus === 'goal-reached') {
+      lines.push(
+        `  ${env.label}: scan stopped after the free-space goal was met`
+      );
+    } else if (env.scanStatus && env.scanStatus !== 'complete') {
       lines.push(`  ${env.label}: scan incomplete (${env.scanStatus})`);
     }
     if (env.hint) {
@@ -336,6 +398,10 @@ export function formatReport(report, options = {}) {
   lines.push(...dockerSection(report));
   lines.push(...errorsSection(report.errors));
   lines.push(...totalsSection(report));
+  const timings = timingLines(report, options);
+  if (timings.length > 0) {
+    lines.push('', 'TIMINGS', ...timings);
+  }
   return lines.join('\n');
 }
 
@@ -429,6 +495,7 @@ export function formatAudit(audit, options = {}) {
   }
   lines.push('', 'Per environment:', ...environmentLines(audit.environments));
   lines.push(...healthLines(audit.health));
+  lines.push(...auditTimingLines(audit, options));
   lines.push(
     '',
     audit.dryRun

package/src/rules/ecosystems.js

@@ -8,9 +8,8 @@
  *
  * `projects` are directories inside project trees, recognised by name plus a
  * marker file next to them (`markers`), inside them (`selfMarkers`), or next
- * to their parent (`parentMarkers`, with `parentName`). Kind `cache` is always
- * `safe`; `build` and `dependencies` are `moderate` after the project has been
- * inactive for the configured number of days and `aggressive` otherwise.
+ * to their parent (`parentMarkers`, with `parentName`). All kinds (`cache`,
+ * `build`, `dependencies`) are `safe` whenever nothing is using them.
  *
  * `busy` lists process names that, when running (inside the project for
  * project directories), mean the tool may be using the directory right now.
@@ -71,7 +70,9 @@ export const ECOSYSTEMS = [
         description: 'Bun install cache',
         paths: ['~/.bun/install/cache'],
         native: { tool: 'bun', argv: ['bun', 'pm', 'cache', 'rm'] },
-        busy: ['bun'],
+        // Only package commands and auto-installing scripts read the cache
+        // (see LivenessProbe.refresh).
+        busy: ['bun', 'bunx'],
       },
       {
         id: 'deno-cache',

package/src/rules/other.js

@@ -349,8 +349,11 @@ export const OTHER_RULES = [
     ecosystem: 'agents',
     description: 'abandoned Codex runtime install staging directories',
     paths: ['~/.cache/codex-runtimes/codex-runtime-install-*'],
+    // The Codex daemon runs for days, so a running `codex` says nothing
+    // about a staging directory: an install in progress writes to it and
+    // holds its files open, which the activity window and open-file checks
+    // catch.
     minAge: 'stale',
-    busy: ['codex'],
   },
   {
     id: 'claude-cli-mcp-logs',

package/src/rules/versions.js

@@ -6,6 +6,11 @@
  * - the newest installed version,
  * - in use by a running process (checked by the liveness layer).
  *
+ * `refsPickNewest` makes a partial ref keep only the newest install it
+ * matches (nvm runs the newest 20.x for `20`); otherwise it keeps them all.
+ * `globalPackages` blocks versions holding packages the user installed
+ * globally, which reinstalling the version would not bring back.
+ *
  * `versionOf(dirPath)` maps an install directory to the version string that
  * defaults and pin files are compared with (see `versionMatches`).
  */
@@ -112,6 +117,16 @@ export const VERSION_RULES = [
     busy: ['claude'],
     recheck: true,
   },
+  {
+    id: 'codex-daemon-releases',
+    ecosystem: 'agents',
+    manager: 'Codex',
+    description: 'Codex app-server daemon release',
+    dirs: ['~/.codex/packages/app-server-daemon/releases/*'],
+    defaultLinks: ['~/.codex/packages/app-server-daemon/current'],
+    busy: ['codex'],
+    recheck: true,
+  },
   {
     id: 'copilot-cli-versions',
     ecosystem: 'agents',
@@ -133,6 +148,14 @@ export const VERSION_RULES = [
     aliasDir: '~/.nvm/alias',
     defaults: [{ path: '~/.nvm/alias/default', parse: firstLines }],
     projectFiles: { '.nvmrc': firstLines, '.node-version': firstLines },
+    refsPickNewest: true,
+    globalPackages: {
+      dir: 'lib/node_modules',
+      // Bundled with Node.js, or a use-m cache (`<name>-v-<version>`) that
+      // use-m installs again on first use.
+      regenerable: (name) =>
+        name === 'npm' || name === 'corepack' || /^[^@][^/]*-v-./.test(name),
+    },
     busy: ['node'],
   },
   {