disk-space-saviour 0.21.0 → 0.22.0

package/src/liveness.js

@@ -17,6 +17,12 @@
 
 import path from 'node:path';
 
+import {
+  bundleRoots,
+  bundlesOwn,
+  ownerBundleId,
+  processBundles,
+} from './app-owners.js';
 import { isWithin } from './paths.js';
 import { formatDuration } from './units.js';
 
@@ -195,6 +201,12 @@ export function matchingName(proc, names) {
   return null;
 }
 
+/** `matched`, prefixed with the app it runs from: `Warp (stable)`. */
+function appLabel(proc, matched) {
+  const app = proc.bundles?.[0]?.name;
+  return app && app !== matched ? `${app} (${matched})` : matched;
+}
+
 export class LivenessProbe {
   /**
    * @param {object} env environment adapter
@@ -213,6 +225,8 @@ export class LivenessProbe {
     this.pathOwners = new Map();
     this.pathStats = new Map();
     this.inodes = new Map();
+    // Bundle identifiers never change, so they outlive refreshes.
+    this.bundleIds = new Map();
   }
 
   async refresh(force = false) {
@@ -224,6 +238,7 @@ export class LivenessProbe {
     this.listed = processes !== null;
     this.processes = processes ?? [];
     this.bunCacheUsers = await this.#bunCacheUsers();
+    await this.#resolveBundles();
     this.probeError =
       (processes === null || this.openPaths === null) &&
       (this.env.platform === 'linux' || this.env.platform === 'darwin');
@@ -234,6 +249,52 @@ export class LivenessProbe {
     this.inodes.clear();
   }
 
+  /** Reads the identifiers of the app bundles running processes come from. */
+  async #resolveBundles() {
+    if (!this.env.bundleIdentifier) {
+      return;
+    }
+    for (const proc of this.processes) {
+      const roots = bundleRoots(proc.executable);
+      for (const root of roots) {
+        if (!this.bundleIds.has(root)) {
+          this.bundleIds.set(
+            root,
+            await this.env.bundleIdentifier(root).catch(() => null)
+          );
+        }
+      }
+      proc.bundles = processBundles(roots, this.bundleIds);
+    }
+  }
+
+  /** ` (pid N, name)` of the process holding `open`, when the probe knows it. */
+  #holder(open) {
+    const pid = this.env.openPathPids?.get(open);
+    if (!pid) {
+      return '';
+    }
+    const proc = this.processes.find((entry) => entry.pid === pid);
+    return proc
+      ? ` (pid ${pid}, ${appLabel(proc, proc.name)})`
+      : ` (pid ${pid})`;
+  }
+
+  /** A running app that owns a per-app Library folder of `paths`. */
+  appUsage(paths) {
+    const owners = [...new Set(paths.map(ownerBundleId).filter(Boolean))];
+    if (owners.length === 0) {
+      return null;
+    }
+    for (const proc of this.processes) {
+      const owner = owners.find((id) => bundlesOwn(proc.bundles ?? [], id));
+      if (owner) {
+        return `${appLabel(proc, proc.name)} is running (pid ${proc.pid}) and owns ${owner}`;
+      }
+    }
+    return null;
+  }
+
   /**
    * Inodes of `executables` and of the open files that share their names,
    * because a process running a hard link of an executable reports
@@ -405,10 +466,11 @@ export class LivenessProbe {
       ) {
         continue;
       }
-      const name = matchingName(proc, names);
-      if (!name) {
+      const matched = matchingName(proc, names);
+      if (!matched) {
         continue;
       }
+      const name = appLabel(proc, matched);
       if (!cwd) {
         return `${name} is running (pid ${proc.pid})`;
       }
@@ -431,7 +493,7 @@ export class LivenessProbe {
     for (const open of this.openPaths) {
       for (const target of targets) {
         if (isWithin(open, target, pathApi)) {
-          return `in use: ${open}`;
+          return `in use: ${open}${this.#holder(open)}`;
         }
       }
     }
@@ -466,7 +528,7 @@ export class LivenessProbe {
           candidate &&
           paths.some((target) => isWithin(candidate, target, this.env.path))
         ) {
-          return `in use: ${candidate} (pid ${proc.pid})`;
+          return `in use: ${candidate} (pid ${proc.pid}, ${appLabel(proc, proc.name)})`;
         }
       }
     }
@@ -555,6 +617,7 @@ export class LivenessProbe {
       this.probeBlocker() ??
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
+      this.appUsage(item.paths ?? []) ??
       this.processUsage(paths) ??
       this.executableUsage(checks.executables) ??
       this.uncertainUsage(item.paths ?? [])

package/src/report.js

@@ -114,6 +114,72 @@ function blockedSection(report, options) {
   ];
 }
 
+/**
+ * Clones that share every block with an installed app: `du` and Finder
+ * count them at full size, deleting them frees nothing.
+ */
+export function sharedSection(shared) {
+  if (!shared?.length) {
+    return [];
+  }
+  const apparent = shared.reduce((sum, item) => sum + item.apparentBytes, 0);
+  return [
+    '',
+    `SHARED WITH INSTALLED APPS  ${plural(shared.length, 'item')}, ${formatBytes(apparent)} as du counts it, about 0 B to free (APFS clones; the app recreates them at launch)`,
+    ...shared.map(
+      (item) =>
+        `  ${pad(formatBytes(item.apparentBytes), 10)}  ${item.rule}  ${item.path}  (shares its blocks with ${item.sharedWith})`
+    ),
+  ];
+}
+
+function tierBreakdown(tiers) {
+  return TIERS.filter((tier) => tiers[tier])
+    .map((tier) => `${tier} ${formatBytes(tiers[tier])}`)
+    .join(', ');
+}
+
+/** One-line warning naming the largest conditions, or null. */
+export function conditionsWarning(blocked) {
+  const conditions = blocked?.conditions ?? [];
+  if (conditions.length === 0) {
+    return null;
+  }
+  const bytes = conditions.reduce((sum, group) => sum + group.bytes, 0);
+  const top = conditions
+    .slice(0, 3)
+    .map((group) => `${group.action} (${formatBytes(group.bytes)})`);
+  const more = conditions.length > 3 ? `, ${conditions.length - 3} more` : '';
+  return `${formatBytes(bytes)} more frees only once something stops using it: ${top.join('; ')}${more}. See FREEABLE ON CONDITIONS.`;
+}
+
+function conditionsWarningLines(blocked) {
+  const warning = conditionsWarning(blocked);
+  return warning ? [`WARNING: ${warning}`] : [];
+}
+
+/** Blocked space grouped by the condition that frees it. */
+export function conditionsSection(blocked, options = {}) {
+  const conditions = blocked?.conditions ?? [];
+  if (conditions.length === 0) {
+    return [];
+  }
+  const lines = conditions.map(
+    (group) =>
+      `  ${pad(formatBytes(group.bytes), 9)}  ${group.action} (${plural(group.items, 'item')}: ${tierBreakdown(group.tiers)})`
+  );
+  if (blocked.other?.items) {
+    lines.push(
+      `  ${pad(formatBytes(blocked.other.bytes), 9)}  kept for other reasons (Git state, still needed, protected or unverifiable): ${plural(blocked.other.items, 'item')}`
+    );
+  }
+  return [
+    '',
+    'FREEABLE ON CONDITIONS (blocked items free once these happen; rerun dss afterwards)',
+    ...limited(lines, options.limit ?? DEFAULT_LIMIT),
+  ];
+}
+
 function repoSummary(repo) {
   if (repo.error) {
     return `${repo.root}: ${repo.error}`;
@@ -375,6 +441,37 @@ function holderLine(holder) {
   return `${holder.pid} ${holder.command}: ${details.join(', ')}`;
 }
 
+function swapLines(swap) {
+  if (!swap) {
+    return [];
+  }
+  return [
+    `Swap: ${formatBytes(swap.used)} used of ${formatBytes(swap.total)} (managed by macOS)`,
+    ...(swap.warnings ?? []).map((warning) => `WARNING: ${warning}`),
+    swap.attribution,
+    ...swap.holders.map((holder) => `  ${holderLine(holder)}`),
+    swap.advice,
+  ];
+}
+
+function environmentStatusLines(env) {
+  const lines = [];
+  if (env.layerSource) {
+    lines.push(`  ${env.label}: layer source ${env.layerSource}`);
+  }
+  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) {
+    lines.push(`  ${env.label}: ${env.hint}`);
+  }
+  return lines;
+}
+
 /**
  * Renders a scan report.
  * @param {object} report
@@ -388,38 +485,15 @@ 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)`
-    );
-    for (const warning of host.swap.warnings ?? []) {
-      lines.push(`WARNING: ${warning}`);
-    }
-    lines.push(host.swap.attribution);
-    for (const holder of host.swap.holders) {
-      lines.push(`  ${holderLine(holder)}`);
-    }
-    lines.push(host.swap.advice);
-  }
+  lines.push(...swapLines(host.swap));
+  lines.push(...conditionsWarningLines(report.totals?.blocked));
   for (const tier of TIERS) {
     lines.push(...tierSection(report, tier, { limit }));
   }
-  for (const env of report.environments) {
-    if (env.layerSource) {
-      lines.push(`  ${env.label}: layer source ${env.layerSource}`);
-    }
-    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) {
-      lines.push(`  ${env.label}: ${env.hint}`);
-    }
-  }
+  lines.push(...report.environments.flatMap(environmentStatusLines));
   lines.push(...blockedSection(report, { limit }));
+  lines.push(...sharedSection(report.shared));
+  lines.push(...conditionsSection(report.totals?.blocked, { limit }));
   lines.push(...dockerSection(report));
   lines.push(...errorsSection(report.errors));
   lines.push(...totalsSection(report));
@@ -499,6 +573,14 @@ function emergencyLines(audit) {
  * @param {object} audit
  * @param {{verbose?: boolean}} [options]
  */
+/** Warns that a plan built on an incomplete scan misses what it never reached. */
+export function incompleteScanLines(incomplete) {
+  return (incomplete ?? []).map(
+    (env) =>
+      `WARNING: the scan of ${env.label} behind this plan stopped early (${env.status}), so items it did not reach were not considered; rerun with a larger --scan-budget (for example --scan-budget 5m).`
+  );
+}
+
 export function formatAudit(audit, options = {}) {
   const limit = options.verbose ? Infinity : DEFAULT_LIMIT * 2;
   const mode = audit.dryRun ? 'dry run, nothing was deleted' : 'deleting';
@@ -527,6 +609,14 @@ export function formatAudit(audit, options = {}) {
       ? `Would free ${formatBytes(audit.plannedBytes)} (run with --yes to delete)`
       : `Freed ${formatBytes(audit.freedBytes)}`
   );
+  lines.push(...incompleteScanLines(audit.incomplete));
+  const conditions = conditionsWarning(audit.blocked);
+  if (conditions) {
+    lines.push(
+      conditions,
+      ...conditionsSection(audit.blocked, options).slice(2)
+    );
+  }
   if (audit.file) {
     lines.push(`Audit log: ${audit.file}`);
   }

package/src/scan.js

@@ -377,13 +377,20 @@ async function scanEnvironmentScoped(
       block(item, env.scanPolicy.removalReason(target));
     }
   }
-  for (const message of env.accessErrors?.values() ?? []) {
+  for (const message of await accessErrorMessages(env)) {
     errors.push({ env: env.id, scanner: 'filesystem', message });
   }
   env.scanStatus = incomplete ? 'error' : 'complete';
   return items;
 }
 
+/** Report messages for paths the scan could not inspect. */
+function accessErrorMessages(env) {
+  return env.accessErrorMessages
+    ? env.accessErrorMessages()
+    : [...(env.accessErrors?.values() ?? [])];
+}
+
 async function attributeStorage(env, items) {
   if (env.writableLayer) {
     const usages = await env.usageMany([
@@ -516,6 +523,24 @@ export function filterItems(items, options, daemons = [], pathApi) {
   );
 }
 
+/**
+ * Items that share every block with an installed app (APFS clones): they
+ * free nothing, so they are not offered, but `du` counts them at full size.
+ */
+function sharedItems(items, options, pathApi) {
+  return filterItems(
+    items.filter((item) => item.sharedWith),
+    { ...options, minSizeBytes: 0 },
+    [],
+    pathApi
+  ).map((item) => ({
+    rule: item.rule,
+    path: item.path,
+    apparentBytes: item.apparentBytes,
+    sharedWith: item.sharedWith,
+  }));
+}
+
 function envDescriptor(env, depth, chain) {
   return {
     id: env.id,
@@ -665,6 +690,7 @@ async function scanScoped(input) {
     docker?.daemons ?? [],
     env.path
   );
+  const shared = sharedItems(hostItems, options, env.path);
   const environments = [envDescriptor(env, 0, [])];
   for (const inner of docker?.environments ?? []) {
     environments.push(inner);
@@ -677,6 +703,7 @@ async function scanScoped(input) {
     options,
     env,
     items,
+    shared,
     environments,
     docker,
     errors,
@@ -707,6 +734,7 @@ export function buildReport({
   options,
   env,
   items,
+  shared = [],
   environments,
   docker,
   errors,
@@ -722,6 +750,7 @@ export function buildReport({
     options: reportOptions(options),
     environments,
     items,
+    shared,
     totals: tierTotals(items),
     docker: docker
       ? {

package/src/scanners/global.js

@@ -238,6 +238,10 @@ async function describeAppClone(context, rule, item, homes) {
   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}`;
   }

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) ?? []),