disk-space-saviour 0.22.0 → 0.23.0

package/src/env/local.js

@@ -100,6 +100,7 @@ import { hostExecutor } from '../exec.js';
 import { parseBundleIdentifier } from '../app-owners.js';
 import { matchesGlob } from '../paths.js';
 import { mapLimit } from './parallel.js';
+import { withLinkAccounting } from './hardlinks.js';
 import { directoryFingerprint, SIZE_MAX_AGE } from '../scan-state.js';
 import { indexedDirectories } from './platform-index.js';
 
@@ -213,6 +214,15 @@ async function makeWritable(target) {
   }
 }
 
+function linkOf(stats, file) {
+  return {
+    path: file,
+    id: `${stats.dev}:${stats.ino}`,
+    nlink: stats.nlink,
+    bytes: diskBytes(stats),
+  };
+}
+
 export class LocalEnv {
   /**
    * @param {{homes?: string[], tmpDirs?: string[], executor?: object,
@@ -322,6 +332,7 @@ export class LocalEnv {
       mtimeMs: stats.mtimeMs,
       ctimeMs: stats.ctimeMs,
       inode: `${stats.dev}:${stats.ino}`,
+      nlink: stats.nlink,
       uid: stats.uid,
       gid: stats.gid,
       mode: stats.mode,
@@ -440,14 +451,16 @@ export class LocalEnv {
       return null;
     }
     const seen = new Set();
+    const links = [];
     let bytes = 0;
     let apparentBytes = 0;
     let files = 0;
     let errors = 0;
     let newestMtimeMs = 0;
-    const account = (stats) => {
+    const account = (stats, full) => {
       if (stats.nlink > 1 && !stats.isDirectory()) {
         const key = `${stats.dev}:${stats.ino}`;
+        links.push(linkOf(stats, full));
         if (seen.has(key)) {
           return;
         }
@@ -463,7 +476,7 @@ export class LocalEnv {
         newestMtimeMs = Math.max(newestMtimeMs, stats.mtimeMs);
       }
     };
-    account(root);
+    account(root, target);
     const visit = async (dir) => {
       let names;
       try {
@@ -489,7 +502,7 @@ export class LocalEnv {
         ) {
           continue;
         }
-        account(stats);
+        account(stats, full);
         if (stats.isDirectory()) {
           subdirs.push(full);
         }
@@ -511,7 +524,10 @@ export class LocalEnv {
     if (files === 0) {
       newestMtimeMs = root.mtimeMs;
     }
-    return { bytes, apparentBytes, files, errors, newestMtimeMs };
+    return withLinkAccounting(
+      { bytes, apparentBytes, files, errors, newestMtimeMs },
+      links
+    );
   }
 
   /**
@@ -734,6 +750,29 @@ export class LocalEnv {
     return usage;
   }
 
+  /** Multi-link files below `target`, which `du` cannot attribute. */
+  async #multiLinks(target) {
+    const result = await this.run([
+      'find',
+      target,
+      '-xdev',
+      '!',
+      '-type',
+      'd',
+      '-links',
+      '+1',
+      '-print0',
+    ]);
+    const files = result.stdout.split('\0').filter(Boolean);
+    const stats = await mapLimit(files, 32, async (file) => [
+      file,
+      await this.#lstat(file),
+    ]);
+    return stats
+      .filter(([, entry]) => entry)
+      .map(([file, entry]) => linkOf(entry, file));
+  }
+
   async quickUsage(target) {
     const stats = await this.stat(target);
     if (!stats) {
@@ -755,13 +794,16 @@ export class LocalEnv {
     if (result.code !== 0 || !match) {
       return this.rawUsage(target);
     }
-    const usage = {
-      bytes: Number(match[1]) * 1024,
-      apparentBytes: Number(match[1]) * 1024,
-      newestMtimeMs: 0,
-      files: 0,
-      errors: 0,
-    };
+    const usage = withLinkAccounting(
+      {
+        bytes: Number(match[1]) * 1024,
+        apparentBytes: Number(match[1]) * 1024,
+        newestMtimeMs: 0,
+        files: 0,
+        errors: 0,
+      },
+      await this.#multiLinks(target)
+    );
     if (this.scanMetrics) {
       this.scanMetrics.directoriesSized++;
     }

package/src/env/roots.js

@@ -0,0 +1,138 @@
+/**
+ * Effective scan roots of one environment and the scope report that makes
+ * them visible.
+ *
+ * Root semantics (also documented in README "Scan roots"):
+ * - host: `roots` (positional paths) or, when none, the homes and temporary
+ *   directories;
+ * - container (every Docker level): `containerRoots` replaces the defaults
+ *   when given; otherwise the defaults (homes, temporary directories and
+ *   the common workspace paths in CONTAINER_ROOTS that exist) plus every
+ *   host `roots` path that also exists inside that container. Host and
+ *   container namespaces differ, so a host root absent from a container is
+ *   reported as `absent`; paths are never guessed or remapped.
+ * The same requested roots reach the traversal policy (mount selection)
+ * and project discovery, so both always agree.
+ */
+import { existingPaths, matchesExcluded } from '../paths.js';
+
+/** Common project locations inside containers, scanned when present. */
+export const CONTAINER_ROOTS = [
+  '/workspace',
+  '/workspaces',
+  '/app',
+  '/src',
+  '/code',
+  '/project',
+  '/usr/src/app',
+];
+
+/** Roots explicitly requested for `env` (null when only defaults apply). */
+export function requestedRoots(env, options, overrides = {}) {
+  if (overrides.roots) {
+    return overrides.roots;
+  }
+  if (env.kind === 'container') {
+    return options.containerRoots ?? options.roots ?? null;
+  }
+  return options.roots ?? null;
+}
+
+const unique = (list) => [...new Set(list)];
+
+/**
+ * Resolves the roots project discovery walks plus one scope entry per
+ * considered root.
+ * @returns {Promise<{roots: string[], entries: object[]}>}
+ */
+export async function resolveRoots(env, options, overrides, homes, tmpDirs) {
+  const entries = [];
+  const add = (path, source) => {
+    if (!entries.some((entry) => entry.path === path)) {
+      entries.push({ path, source });
+    }
+  };
+  if (overrides.roots) {
+    overrides.roots.forEach((root) => add(root, 'roots'));
+  } else if (env.kind === 'container' && options.containerRoots) {
+    options.containerRoots.forEach((root) => add(root, 'container-roots'));
+  } else if (env.kind !== 'container' && options.roots) {
+    options.roots.forEach((root) => add(root, 'roots'));
+  } else {
+    homes.forEach((root) => add(root, 'home'));
+    tmpDirs.forEach((root) => add(root, 'tmp'));
+    if (env.kind === 'container') {
+      const present = await existingPaths(env, CONTAINER_ROOTS);
+      CONTAINER_ROOTS.filter((root) => present.has(root)).forEach((root) =>
+        add(root, 'container-default')
+      );
+      (options.roots ?? []).forEach((root) => add(root, 'roots'));
+    }
+  }
+  await classify(env, options, entries);
+  return {
+    roots: unique(
+      entries.filter((entry) => entry.status === 'pending').map((e) => e.path)
+    ),
+    entries,
+  };
+}
+
+async function classify(env, options, entries) {
+  const policy = env.scanPolicy;
+  const allowed = entries.filter((entry) => {
+    if (matchesExcluded(entry.path, options.exclude ?? [], env.path)) {
+      entry.status = 'excluded';
+      return false;
+    }
+    if (policy && !policy.allows(entry.path)) {
+      entry.status = 'pruned';
+      return false;
+    }
+    return true;
+  });
+  const present = allowed.length
+    ? await existingPaths(
+        env,
+        allowed.map((entry) => entry.path)
+      )
+    : new Set();
+  for (const entry of allowed) {
+    entry.status = present.has(entry.path) ? 'pending' : 'absent';
+  }
+}
+
+/** Scope descriptor stored on the environment and copied into reports. */
+export function scanScope(env, options, entries) {
+  return {
+    roots: entries.map((entry) => ({ ...entry })),
+    maxDepth: options.maxDepth,
+    exclude: [...(options.exclude ?? [])],
+    prunedMounts: [...(env.scanPolicy?.pruned ?? [])],
+    note:
+      'scanStatus "complete" means complete within these roots, maxDepth, ' +
+      'exclusions and mount boundaries; fixed cache, toolchain and agent ' +
+      'locations are checked independently of roots',
+  };
+}
+
+/** Final per-root status when the scanners of the environment finish. */
+export function finishScope(env, ranProjects) {
+  const scope = env.scanScope;
+  if (!scope) {
+    return;
+  }
+  const denied = new Set(env.accessErrors?.keys() ?? []);
+  for (const root of scope.roots) {
+    if (root.status !== 'pending') {
+      continue;
+    }
+    if (denied.has(root.path)) {
+      root.status = 'inaccessible';
+    } else if (!ranProjects) {
+      root.status = 'not-searched';
+    } else {
+      root.status = env.scanStatus === 'complete' ? 'searched' : 'partial';
+    }
+  }
+}

package/src/env/shell.js

@@ -20,6 +20,7 @@ import { sharedWritableLayer } from '../docker/writable.js';
 import { containerExecutor, shellQuote, trace } from '../exec.js';
 import { DEFAULT_SKIP_NAMES, parseDf, processAliases } from './local.js';
 import { batches } from './batches.js';
+import { LINKS_SCRIPT, parseLinks, withLinkAccounting } from './hardlinks.js';
 import { signalExecutor } from './scope.js';
 
 const STAT_FORMAT = '%F|%s|%b|%B|%Y|%n';
@@ -44,6 +45,8 @@ const USAGE_MANY_SCRIPT = `for t in "$@"; do
   du -skx -- "$t" 2>/dev/null | cut -f1
   find "$t" -xdev ! -type d -exec stat -c %Y {} + 2>/dev/null | awk 'BEGIN{m=0;n=0}{n++; if ($1>m) m=$1} END{print n, m}'
   stat -c %Y -- "$t"
+  echo links
+  ${LINKS_SCRIPT}
 done
 true`;
 
@@ -120,10 +123,18 @@ function splitRecords(output) {
 }
 
 function parseUsage(body) {
-  const [kib, counts = '', rootMtime] = body.trim().split('\n');
+  const [head, links = ''] = body.split('\nlinks\n');
+  const [kib, counts = '', rootMtime] = head.trim().split('\n');
   const [files, newest] = counts.trim().split(/\s+/).map(Number);
   const bytes = Number(kib) * 1024;
   const newestSeconds = files > 0 ? newest : Number(rootMtime);
+  return withLinkAccounting(
+    usageFields(bytes, files, newestSeconds),
+    parseLinks(links)
+  );
+}
+
+function usageFields(bytes, files, newestSeconds) {
   return {
     bytes: Number.isFinite(bytes) ? bytes : 0,
     apparentBytes: Number.isFinite(bytes) ? bytes : 0,
@@ -292,7 +303,7 @@ export class ShellEnv {
       const result = await this.executor.run([
         'stat',
         '-c',
-        `${STAT_FORMAT}|%d:%i:%u:%g:%f`,
+        `${STAT_FORMAT}|%d:%i:%u:%g:%f:%h`,
         '--',
         ...batch,
       ]);
@@ -310,6 +321,7 @@ export class ShellEnv {
               identity.length > 4
                 ? Number.parseInt(identity[4], 16)
                 : undefined,
+            nlink: identity.length > 5 ? Number(identity[5]) : undefined,
           });
         }
       }

package/src/index.d.ts

@@ -9,6 +9,13 @@ export type Duration = number | string;
 export interface ScanOptions {
   /** Directories to search for projects (default: homes and tmp dirs). */
   roots?: string[] | string | null;
+  /**
+   * Project roots inside every scanned container (all Docker depths).
+   * Replaces the container defaults; without it containers search their
+   * homes, temporary directories, common workspace paths and every `roots`
+   * path that exists inside them.
+   */
+  containerRoots?: string[] | string | null;
   /** Directory depth for project search. */
   maxDepth?: number;
   /** Time budget per filesystem environment (`2m`); incomplete findings are kept. */
@@ -117,7 +124,15 @@ export interface Item {
   description: string;
   path: string | null;
   paths: string[];
+  /**
+   * Physically reclaimable bytes: blocks of hard-linked files with a link
+   * outside the item are not counted.
+   */
   bytes: number;
+  /** Blocks reachable from the item (each inode once); set with sharedBytes. */
+  allocatedBytes?: number;
+  /** Blocks retained by hard links outside the item; present when non-zero. */
+  sharedBytes?: number;
   /** Cached size is advisory; cleanup always measures again. */
   sizeEstimated?: boolean;
   /** Merged filesystem bytes, including image data, when measured in Docker. */
@@ -180,6 +195,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;
@@ -196,9 +213,32 @@ export interface EnvironmentDescriptor {
     | 'budget-exceeded'
     | 'error'
     | null;
+  /** What `scanStatus: complete` covers in this environment. */
+  scope?: ScanScope | null;
   layerSource?: string | null;
 }
 
+export interface ScanScope {
+  roots: Array<{
+    path: string;
+    source: 'roots' | 'container-roots' | 'home' | 'tmp' | 'container-default';
+    status:
+      | 'searched'
+      | 'partial'
+      | 'absent'
+      | 'inaccessible'
+      | 'pruned'
+      | 'excluded'
+      | 'not-searched'
+      | 'pending';
+  }>;
+  maxDepth: number;
+  exclude: string[];
+  /** Mount points never traversed (unselected, read-only or overlay). */
+  prunedMounts: string[];
+  note: string;
+}
+
 export interface TierTotal {
   items: number;
   bytes: number;
@@ -258,6 +298,10 @@ export interface AuditEntry {
   freedBytes: number;
   /** True when authoritative before/after allocation could not be measured. */
   freedEstimated?: boolean;
+  /** `'hardlink-aware-estimate'`: freedBytes is the link-aware selection estimate. */
+  freedAccounting?: 'hardlink-aware-estimate';
+  /** Blocks of deleted files that stay allocated through outside hard links. */
+  sharedBytes?: number;
   durationMs: number;
   backup?: string;
   [key: string]: unknown;
@@ -288,6 +332,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)
     );
   }