disk-space-saviour 0.21.0 → 0.22.1

package/src/env/local.js

@@ -89,7 +89,7 @@ export function parsePsSearchPaths(output) {
  * host and inside containers (see shell.js).
  */
 
-import { promises as fsp } from 'node:fs';
+import { constants as fsConstants, promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { URL, fileURLToPath } from 'node:url';
@@ -97,6 +97,7 @@ import { procIdentity, procOpenPaths } from './proc.js';
 import { CACHE_VARIABLES } from './cache-roots.js';
 
 import { hostExecutor } from '../exec.js';
+import { parseBundleIdentifier } from '../app-owners.js';
 import { matchesGlob } from '../paths.js';
 import { mapLimit } from './parallel.js';
 import { directoryFingerprint, SIZE_MAX_AGE } from '../scan-state.js';
@@ -251,6 +252,36 @@ export class LocalEnv {
     );
   }
 
+  /**
+   * Access errors as report messages. Paths inside a directory this user
+   * cannot enter collapse into one line: nothing inside such a directory
+   * can be deleted by this user, so no candidate hides there.
+   * @returns {Promise<string[]>}
+   */
+  async accessErrorMessages() {
+    const messages = [];
+    const foreign = new Set();
+    for (const [target, message] of this.accessErrors ?? []) {
+      const parent = path.dirname(target);
+      const enterable = await fsp
+        .access(parent, fsConstants.X_OK)
+        .then(() => true)
+        .catch(() => false);
+      if (enterable) {
+        messages.push(message);
+      } else {
+        foreign.add(parent);
+      }
+    }
+    if (foreign.size > 0) {
+      const [example] = [...foreign].sort();
+      messages.push(
+        `skipped ${foreign.size} ${foreign.size === 1 ? 'directory' : 'directories'} this user cannot enter, such as ${example}; nothing inside can be deleted without their owner's rights`
+      );
+    }
+    return messages;
+  }
+
   async #lstat(target) {
     try {
       return await (this.options.fileFs ?? fsp).lstat(target);
@@ -830,6 +861,8 @@ export class LocalEnv {
       .map((m) => ({
         pid: Number(m[1]),
         name: path.basename(m[2].trim()),
+        // macOS `comm` is the executable's full path.
+        executable: m[2].trim(),
         cwd: cwds.get(Number(m[1])) ?? null,
         command: commands.get(Number(m[1])) ?? '',
         searchPath: searchPaths.get(Number(m[1])) ?? [],
@@ -978,12 +1011,22 @@ export class LocalEnv {
       if (result.code !== 0 && !result.stdout) {
         return null;
       }
-      return new Set(
-        result.stdout
-          .split('\n')
-          .filter((line) => line.startsWith('n/'))
-          .map((line) => line.slice(1))
-      );
+      // `-F` always prints the pid (`p`) before the files of a process.
+      const paths = new Set();
+      const owners = new Map();
+      let pid = null;
+      for (const line of result.stdout.split('\n')) {
+        if (line.startsWith('p')) {
+          pid = Number(line.slice(1));
+        } else if (line.startsWith('n/')) {
+          paths.add(line.slice(1));
+          if (!owners.has(line.slice(1))) {
+            owners.set(line.slice(1), pid);
+          }
+        }
+      }
+      this.openPathPids = owners;
+      return paths;
     }
     return null;
   }
@@ -992,6 +1035,26 @@ export class LocalEnv {
     return this.executor.run(argv, options);
   }
 
+  /** `CFBundleIdentifier` of a macOS bundle, or null. */
+  async bundleIdentifier(bundle) {
+    if (this.platform !== 'darwin') {
+      return null;
+    }
+    const plist = path.join(bundle, 'Contents', 'Info.plist');
+    const text = await fsp.readFile(plist, 'utf8').catch(() => null);
+    if (text === null) {
+      return null;
+    }
+    if (!text.startsWith('bplist')) {
+      return parseBundleIdentifier(text);
+    }
+    const result = await this.run(
+      ['plutil', '-extract', 'CFBundleIdentifier', 'raw', '-o', '-', plist],
+      { timeoutMs: 10000 }
+    ).catch(() => null);
+    return result?.code === 0 ? result.stdout.trim() || null : null;
+  }
+
   async which(command) {
     const dirs = (process.env.PATH ?? '').split(path.delimiter);
     const extensions =

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;
@@ -219,6 +221,16 @@ export interface Report {
   options: Record<string, unknown>;
   environments: EnvironmentDescriptor[];
   items: Item[];
+  /**
+   * Host items that share every block with an installed app (APFS clones):
+   * never offered, listed so the space `du` counts for them is explained.
+   */
+  shared?: Array<{
+    rule: string;
+    path: string;
+    apparentBytes: number;
+    sharedWith: string;
+  }>;
   /** Tier totals exclude items that need explicit consent (`consent`). */
   totals: Record<Tier | 'blocked' | 'consent', TierTotal>;
   docker: {
@@ -278,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;
@@ -300,6 +314,50 @@ export declare function clean(
 /** Escalates tiers until the free-space goal is met, then stops. */
 export declare function emergency(options: EmergencyOptions): Promise<AuditLog>;
 
+export interface UsageOptions {
+  /** Directories to walk; default the macOS Data volume or `/`. */
+  roots?: string[] | null;
+  /** Smallest directory in the tree, in bytes; default 1% of a root. */
+  minSize?: number;
+  verbose?: boolean;
+  signal?: AbortSignal;
+  auditDir?: string;
+  onUsageProgress?: (progress: {
+    root: string;
+    elapsedMs: number;
+    entries: number;
+    at: string | null;
+  }) => void;
+}
+
+export interface UsageReport {
+  schema: 1;
+  createdAt: string;
+  durationMs: number;
+  platform: string;
+  scan: { file: string; createdAt: string | null } | null;
+  roots: Array<{
+    root: string;
+    path: string;
+    bytes: number;
+    entries: number;
+    tree: object;
+    files: Array<{ path: string; bytes: number }>;
+    [key: string]: unknown;
+  }>;
+  volumes: Array<{
+    name: string;
+    mount: string | null;
+    bytes: number;
+    role: string;
+  }>;
+  snapshots: number | null;
+}
+
+/** Shows where the space of whole volumes goes. Never deletes. */
+export declare function usage(options?: UsageOptions): Promise<UsageReport>;
+export declare function formatUsage(report: UsageReport): string;
+
 export declare function formatReport(
   report: Report,
   options?: { verbose?: boolean }

package/src/index.js

@@ -23,6 +23,7 @@ export {
   writeAudit,
 } from './audit.js';
 export { formatReport, formatAudit, formatDisk } from './report.js';
+export { usage, formatUsage } from './usage.js';
 export { runCli, parseCli, USAGE } from './cli.js';
 export { DEFAULTS, resolveOptions, resolveGoal } from './options.js';
 export {

package/src/items.js

@@ -7,6 +7,8 @@
  * named flag (or an interactive yes) on top of their tier being selected.
  */
 
+import { blockedConditions } from './conditions.js';
+
 export const TIERS = ['safe', 'moderate', 'aggressive'];
 
 /**
@@ -111,6 +113,7 @@ export function tierTotals(items) {
     unknownBytes: blocked
       .filter((item) => item.sizeUnknown)
       .reduce((sum, item) => sum + (item.totalBytes ?? item.bytes), 0),
+    ...blockedConditions(blocked),
   };
   return totals;
 }

package/src/liveness.js

@@ -10,17 +10,51 @@
  * - 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.
  */
 
 import path from 'node:path';
 
+import {
+  bundleRoots,
+  bundlesOwn,
+  ownerBundleId,
+  processBundles,
+} from './app-owners.js';
 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([
@@ -195,14 +229,30 @@ 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
-   * @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;
@@ -213,6 +263,9 @@ 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();
   }
 
   async refresh(force = false) {
@@ -224,6 +277,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');
@@ -232,6 +286,53 @@ 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. */
+  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;
   }
 
   /**
@@ -332,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(
@@ -375,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;
@@ -405,10 +573,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 +600,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 +635,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)})`;
         }
       }
     }
@@ -549,15 +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.processUsage(paths) ??
+      this.appUsage(all) ??
+      this.processUsage(checks.perPath ? [] : all) ??
       this.executableUsage(checks.executables) ??
-      this.uncertainUsage(item.paths ?? [])
+      this.uncertainUsage(all)
     );
   }