disk-space-saviour 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.23.0
+
+### Minor Changes
+
+- Recursive container scans honor requested roots: `--container-root PATH` (`containerRoots`) sets project roots inside every scanned container at any Docker depth, and host roots that exist inside a container join its defaults. The same roots reach the traversal policy and project discovery. Every environment now reports its effective `scope` (roots with source and status, max depth, exclusions, pruned mounts) and the text report names requested roots that were absent, inaccessible, pruned, excluded or not searched.
+
+  Hard-link aware sizes: items report physically reclaimable bytes, with `allocatedBytes` and `sharedBytes` when links outside the item keep blocks allocated. Each inode is counted once across a selected deletion set, and the audit records `sharedBytes` and marks link-aware estimated `freedBytes`.
+
+  Add explicit macOS app bundle removal through native Trash with process checks,
+  dry runs and audits. Report possible app leftovers separately from user data,
+  without automatically deleting either category.
+
 ## 0.22.1
 
 ### Patch Changes

package/README.md

@@ -411,6 +411,41 @@ is scanned as a new environment, down to `--depth` levels (default 3). The
 CI job `Docker-in-Docker Integration` builds a host → l1 → l2 chain and runs
 `tests/integration/dind.mjs` against it (`npm run test:dind`).
 
+### Scan roots
+
+Project discovery walks a list of roots per environment; the traversal
+policy (which mount points are crossed) uses the same requested roots, so
+both always agree:
+
+- host: the positional `paths` (`roots` in the API), otherwise the homes and
+  temporary directories;
+- every scanned container, at every Docker depth: `--container-root PATH`
+  (`containerRoots`, repeatable) replaces the defaults; without it, the
+  container's homes, temporary directories, existing common workspace paths
+  (`/workspace`, `/workspaces`, `/app`, `/src`, `/code`, `/project`,
+  `/usr/src/app`) and every host root that also exists inside the container.
+  Host and container paths are different namespaces, so no path is remapped.
+
+Each JSON environment carries `scope`: its roots with `source` (`roots`,
+`container-roots`, `home`, `tmp`, `container-default`) and `status`
+(`searched`, `partial`, `absent`, `inaccessible`, `pruned`, `excluded`,
+`not-searched`), plus `maxDepth`, `exclude` and `prunedMounts`. The text
+report names requested roots that were not searched. `scanStatus: complete`
+means complete within that scope; exclusions, mount boundaries and liveness
+checks still apply.
+
+### Hard links
+
+Sizes are physical reclaimable bytes. A file's blocks count toward an item
+only when every hard link to it lies inside the deletion set: a package
+cache or `node_modules` hard-linked to a shared store (pnpm, Nix, uv) reports
+those blocks as `sharedBytes`, next to `allocatedBytes` (what `du` prints).
+Each `dev:inode` is counted once across the whole selection, so files linked
+between two selected paths are reclaimable once. In the audit log,
+`sharedBytes` lists blocks that stayed allocated; `freedBytes` is a measured
+before/after value for Docker writable layers and otherwise the link-aware
+estimate, marked with `freedEstimated` and `freedAccounting`.
+
 ## Emergency mode
 
 `dss emergency --free 20G` (at least 20 GiB available) or
@@ -776,3 +811,33 @@ Quick steps:
 ## License
 
 [Unlicense](LICENSE) - Public Domain
+
+### Explicit macOS app removal and leftovers
+
+`dss apps remove "/Users/me/Applications/Example.app"` previews removal;
+`--yes` moves only that bundle to the macOS Trash. It never empties Trash or
+removes support data. App identity and process activity are checked before
+removal; symlinked paths, nested app components and App Store receipts are
+refused. Use a vendor uninstaller first when one exists.
+
+Chrome web apps should first be uninstalled using `chrome://apps`.
+`--launcher-only` explicitly allows moving their launcher bundles to Trash;
+it preserves Chrome's app registration, cookies, profiles and website data,
+so Chrome may recreate the launcher. The command is separate from automatic
+cache cleanup. Removed URL handlers may be recreated by their owning tool.
+
+`dss apps leftovers` reports possible leftover Library files, including logs.
+An absent bundle in standard application folders is only a clue: apps can live
+elsewhere, and helpers or other apps can share data. Caches and logs are marked
+`disposable-after-activity-check`; settings, application support, containers,
+and saved state require a user decision. Every candidate remains read-only,
+including disposable candidates. No leftover is safe to delete unconditionally;
+logs may be needed for investigation. Inventory errors appear in the report.
+
+### Platform-specific competitor comparison
+
+See the [feature comparison tables](docs/research/platform-feature-comparison.md)
+for dss and 30 competitors across Linux, macOS, FreeBSD, OpenBSD, NetBSD,
+illumos and AIX. Capability, interface and safety-backend tables distinguish
+implemented features, vendor documentation, partial coverage and unknowns.
+The comparison is a sourced inventory, not a performance or superiority claim.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk-space-saviour",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "Safely reclaims disk space: caches and build outputs of 20+ ecosystems, forgotten projects, and Docker (running, stopped and nested containers), with an emergency mode",
   "type": "module",
   "main": "src/index.js",

package/src/clean.js

@@ -12,6 +12,7 @@
  * log.
  */
 
+import { selectionBytes } from './env/hardlinks.js';
 import { once } from 'node:events';
 import { createWriteStream, promises as fsp } from 'node:fs';
 import path from 'node:path';
@@ -79,6 +80,7 @@ export function cleanOrder(a, b) {
   );
 }
 
+/** Plain per-path sum: used for before/after measurements of one set. */
 function sumBytes(usages, paths = [...usages.keys()]) {
   let total = 0;
   for (const target of paths) {
@@ -334,7 +336,7 @@ export class Cleaner {
     const fresh = {
       ...item,
       paths,
-      bytes: sumBytes(usages, paths),
+      bytes: selectionBytes(usages, paths).bytes,
       newestMtimeMs: newest || item.newestMtimeMs,
       action: type === 'remove' ? { ...item.action, paths } : item.action,
     };
@@ -559,7 +561,12 @@ export class Cleaner {
         entry.reason = boundary;
         return;
       }
-      await this.#deletePaths(ctx, entry, [target], usage?.bytes ?? 0);
+      await this.#deletePaths(
+        ctx,
+        entry,
+        [target],
+        selectionBytes(new Map([[target, usage]]), [target])
+      );
     }
     if (entry.deletedPaths.length === 0 && entry.skippedPaths.length > 0) {
       entry.reason = 'every path was in use or recently written';
@@ -599,7 +606,12 @@ export class Cleaner {
     if (!selected.length) {
       return true;
     }
-    await this.#deletePaths(ctx, entry, selected, sumBytes(usages, selected));
+    await this.#deletePaths(
+      ctx,
+      entry,
+      selected,
+      selectionBytes(usages, selected)
+    );
     const lost = await this.health.check(ctx.env, item);
     if (lost) {
       entry.reason = lost;
@@ -638,7 +650,12 @@ export class Cleaner {
     return usage.bytes === 0 ? 'no writable bytes remain' : null;
   }
 
-  async #deletePaths(ctx, entry, selected, estimate) {
+  /** `accounted`: hard-link aware {bytes, sharedBytes} of `selected`. */
+  async #deletePaths(ctx, entry, selected, accounted) {
+    const estimate = accounted.bytes;
+    if (accounted.sharedBytes > 0) {
+      entry.sharedBytes = (entry.sharedBytes ?? 0) + accounted.sharedBytes;
+    }
     const before = await ctx.env.writableLayer?.allocatedBytes?.(
       selected,
       ctx.env.path
@@ -661,9 +678,10 @@ export class Cleaner {
     if (typeof before === 'number' && typeof after === 'number') {
       return Math.max(0, before - after);
     }
-    if (ctx.env.writableLayer) {
-      entry.freedEstimated = true;
-    }
+    // Without a block measurement the hard-link aware selection estimate
+    // is reported, and marked as an estimate.
+    entry.freedEstimated = true;
+    entry.freedAccounting = 'hardlink-aware-estimate';
     return fallback;
   }
 

package/src/cli.js

@@ -13,6 +13,7 @@ import { parseArgs } from 'node:util';
 
 import { startAudit, writeAudit } from './audit.js';
 import { clean } from './clean.js';
+import { runApps } from './mac-apps.js';
 import { exitedBlockerPids, pidAlive } from './conditions.js';
 import { emergency } from './emergency.js';
 import { setTrace } from './exec.js';
@@ -34,6 +35,8 @@ Commands:
                              largest directories and files, what dss can
                              free inside them, APFS volumes (never deletes)
   docker scan|clean          Only Docker: daemons, containers, nested daemons
+  apps remove APP.app       Move explicitly selected macOS apps to Trash
+  apps leftovers            Report possible app leftovers (read-only)
   help, version
 
 Scope:
@@ -43,6 +46,9 @@ Scope:
   --depth N                  Docker nesting depth to recurse into (default 3)
   --recursive                docker: recurse into nested daemons
   --container ID|NAME        limit Docker work to these containers (repeat)
+  --container-root PATH      project root inside every scanned container,
+                             at any Docker depth; replaces the container
+                             defaults (repeat)
   --max-depth N              directory depth for project search (default 6)
   --scan-budget AGE          time budget per filesystem environment (2m)
   --only NAME|ID|PATH        only these ecosystems, rules, kinds, item ids,
@@ -91,6 +97,7 @@ const OPTIONS = {
   depth: { type: 'string' },
   recursive: { type: 'boolean' },
   container: { type: 'string', multiple: true },
+  'container-root': { type: 'string', multiple: true },
   'max-depth': { type: 'string' },
   'scan-budget': { type: 'string' },
   only: { type: 'string', multiple: true },
@@ -170,6 +177,7 @@ function tierOf(values) {
 export function toOptions(values, paths = []) {
   return {
     roots: paths.length > 0 ? paths : null,
+    containerRoots: values['container-root'],
     docker: dockerMode(values),
     dockerDepth: integer(values.depth, '--depth'),
     containers: values.container,
@@ -539,6 +547,9 @@ function dispatch(cli, command, options, values) {
 export async function runCli(argv, deps = {}) {
   const io = deps.io ?? processIo();
   try {
+    if (argv[0] === 'apps') {
+      return await runApps(argv.slice(1), io, deps.signal);
+    }
     const { command, paths, values } = parseCli(argv);
     if (command === 'help') {
       io.stdout(USAGE);

package/src/docker/scan.js

@@ -632,6 +632,7 @@ class DockerScan {
     this.result.items.push(...(await this.scanEnvironment(env)));
     Object.assign(descriptor, {
       scanStatus: env.scanStatus,
+      scope: env.scanScope ?? null,
       hint: env.probeHint ?? null,
       layerSource: env.writableLayer?.source ?? null,
       timings: env.timings?.toJSON() ?? [],

package/src/docker/writable.js

@@ -213,9 +213,15 @@ export class WritableLayer {
               )
           )
         : 0;
+      // Upper-layer blocks are measured directly: merged-view link data
+      // does not describe them, so the writable bytes are final.
+      const plain = { ...usage };
+      delete plain.links;
+      delete plain.sharedBytes;
       result.set(target, {
-        ...usage,
+        ...plain,
         bytes,
+        allocatedBytes: bytes,
         totalBytes: usage.bytes,
         imageBytes: known ? Math.max(0, usage.bytes - bytes) : 0,
         sizeUnknown: !known,

package/src/env/hardlinks.js

@@ -0,0 +1,139 @@
+/**
+ * Hard-link aware accounting of reclaimable blocks.
+ *
+ * `du` (and every per-path walk) counts each inode once per measured path,
+ * including inodes that also have links outside that path. Deleting such a
+ * path removes a directory entry but releases no file blocks while another
+ * link remains. A file's blocks are reclaimable only when every one of its
+ * links is inside the selected deletion set; several links that are all
+ * inside the set are reclaimable once.
+ *
+ * Usage objects carry:
+ * - `allocatedBytes`: blocks reachable from the path (what `du` prints);
+ * - `sharedBytes`: blocks of multi-link files with a link outside the path;
+ * - `bytes`: `allocatedBytes - sharedBytes`, the physically reclaimable part;
+ * - `links`: the multi-link non-directory entries below the path
+ *   (`{path, id, nlink, bytes}`), used to account a whole selection.
+ */
+
+/** POSIX shell fragment listing multi-link files below "$t" (GNU/busybox or BSD stat). */
+export const LINKS_SCRIPT = `if stat -c %h / >/dev/null 2>&1; then
+  find "$t" -xdev ! -type d -links +1 -exec stat -c '%d:%i %h %b %B %n' -- {} + 2>/dev/null
+else
+  find "$t" -xdev ! -type d -links +1 -exec stat -f '%d:%i %l %b 512 %N' {} + 2>/dev/null
+fi`;
+
+/** Parses LINKS_SCRIPT output lines (`dev:ino nlink blocks blocksize path`). */
+export function parseLinks(text) {
+  const links = [];
+  for (const line of (text ?? '').split('\n')) {
+    const match = /^(\d+:\d+) (\d+) (\d+) (\d+) (.+)$/.exec(line);
+    if (match) {
+      links.push({
+        id: match[1],
+        nlink: Number(match[2]),
+        bytes: Number(match[3]) * Number(match[4]),
+        path: match[5],
+      });
+    }
+  }
+  return links;
+}
+
+function groupLinks(groups) {
+  const inodes = new Map();
+  for (const [target, links] of groups) {
+    for (const link of links ?? []) {
+      if (!inodes.has(link.id)) {
+        inodes.set(link.id, {
+          nlink: link.nlink,
+          bytes: link.bytes,
+          paths: new Set(),
+          targets: new Set(),
+        });
+      }
+      const inode = inodes.get(link.id);
+      inode.nlink = Math.max(inode.nlink, link.nlink);
+      inode.paths.add(link.path);
+      inode.targets.add(target);
+    }
+  }
+  return inodes;
+}
+
+/**
+ * Accounts a deletion set measured per path.
+ * @param {Array<[string, {allocated: number, links?: object[]}]>} measured
+ *   one entry per selected path: its per-path allocated bytes (each inode
+ *   counted once within that path) and its multi-link entries
+ * @returns {{allocatedBytes: number, sharedBytes: number, bytes: number}}
+ *   blocks reachable from the set (each inode once), blocks retained by
+ *   links outside the set, and the physically reclaimable remainder
+ */
+export function accountLinks(measured) {
+  let allocated = measured.reduce((sum, [, entry]) => sum + entry.allocated, 0);
+  let shared = 0;
+  const inodes = groupLinks(
+    measured.map(([target, entry]) => [target, entry.links])
+  );
+  for (const inode of inodes.values()) {
+    // Per-path walks counted this inode once in every path containing it.
+    allocated -= (inode.targets.size - 1) * inode.bytes;
+    if (inode.paths.size < inode.nlink) {
+      shared += inode.bytes;
+    }
+  }
+  allocated = Math.max(0, allocated);
+  shared = Math.min(shared, allocated);
+  return {
+    allocatedBytes: allocated,
+    sharedBytes: shared,
+    bytes: allocated - shared,
+  };
+}
+
+/** Adds allocated/shared/reclaimable fields to one path's usage. */
+export function withLinkAccounting(usage, links) {
+  if (!usage) {
+    return usage;
+  }
+  const allocated = usage.allocatedBytes ?? usage.bytes;
+  const accounted = accountLinks([['', { allocated, links }]]);
+  return {
+    ...usage,
+    bytes: accounted.bytes,
+    allocatedBytes: accounted.allocatedBytes,
+    sharedBytes: accounted.sharedBytes,
+    ...(links?.length ? { links } : {}),
+  };
+}
+
+/**
+ * Reclaimable bytes of several selected paths of one environment, from
+ * their usages. Links between selected paths are reclaimable; links
+ * outside the selection are not.
+ */
+export function selectionBytes(usages, selected) {
+  const measured = selected
+    .map((target) => [target, usages.get(target)])
+    .filter(([, usage]) => usage)
+    .map(([target, usage]) => [
+      target,
+      {
+        allocated: usage.allocatedBytes ?? usage.bytes,
+        links: usage.links,
+      },
+    ]);
+  return accountLinks(measured);
+}
+
+/**
+ * Item size fields of the usages of one item's paths: `bytes` is the
+ * reclaimable total; `allocatedBytes`/`sharedBytes` are added only when
+ * hard links outside the item retain blocks.
+ */
+export function itemSize(entries) {
+  const usages = new Map(entries.filter(([, usage]) => usage));
+  const accounted = selectionBytes(usages, [...usages.keys()]);
+  return accounted.sharedBytes > 0 ? accounted : { bytes: accounted.bytes };
+}

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. */
@@ -198,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;
@@ -260,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;

package/src/mac-apps.js

@@ -0,0 +1,286 @@
+/** Explicit macOS application removal and conservative leftover inventory. */
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { LocalEnv } from './env/local.js';
+import { LivenessProbe } from './liveness.js';
+import { parseBundleIdentifier } from './app-owners.js';
+import { runProcess } from './exec.js';
+import { startAudit, writeAudit } from './audit.js';
+
+const TRASH = `ObjC.import('Foundation');
+function run(args) {
+ const url = $.NSURL.fileURLWithPath(args[0]);
+ if (!$.NSFileManager.defaultManager.trashItemAtURLResultingItemURLError(url, null, null))
+   throw new Error('macOS refused the Trash operation');
+ return 'In Trash';
+}`;
+
+export async function appIdentity(target, home = os.homedir()) {
+  const full = path.resolve(target);
+  const allowed = ['/Applications', path.join(home, 'Applications')].map(
+    (root) => path.resolve(root)
+  );
+  if (
+    !allowed.some((root) => full.startsWith(`${root}${path.sep}`)) ||
+    !full.endsWith('.app')
+  ) {
+    throw new Error(
+      'Select an explicit .app inside /Applications or ~/Applications'
+    );
+  }
+  if ((await fs.realpath(full)) !== full) {
+    throw new Error('Symlinked app paths are not supported');
+  }
+  if (
+    full
+      .split(path.sep)
+      .slice(0, -1)
+      .some((part) => part.endsWith('.app'))
+  ) {
+    throw new Error(
+      'Nested application components cannot be removed separately'
+    );
+  }
+  const stats = await fs.lstat(full);
+  if (!stats.isDirectory()) {
+    throw new Error('Application must be a directory');
+  }
+  const plist = await runProcess([
+    '/usr/bin/plutil',
+    '-convert',
+    'xml1',
+    '-o',
+    '-',
+    path.join(full, 'Contents/Info.plist'),
+  ]);
+  const id = parseBundleIdentifier(plist.stdout);
+  if (plist.code || !id) {
+    throw new Error('Application identity cannot be verified');
+  }
+  return {
+    path: full,
+    id,
+    device: stats.dev,
+    inode: stats.ino,
+    webApp: plist.stdout.includes('CrAppModeShortcutID'),
+    hasReceipt: await fs
+      .access(path.join(full, 'Contents/_MASReceipt/receipt'))
+      .then(
+        () => true,
+        () => false
+      ),
+  };
+}
+
+export function leftoverCategory(kind) {
+  return ['Caches', 'Logs'].includes(kind)
+    ? 'disposable-after-activity-check'
+    : 'user-decision';
+}
+
+async function installedIds(root, ids, errors, depth = 0) {
+  if (depth > 4) {
+    return;
+  }
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const full = path.join(root, entry.name);
+    if (entry.name.endsWith('.app')) {
+      try {
+        const result = await runProcess([
+          '/usr/bin/plutil',
+          '-convert',
+          'xml1',
+          '-o',
+          '-',
+          path.join(full, 'Contents/Info.plist'),
+        ]);
+        const id = parseBundleIdentifier(result.stdout);
+        if (!id) {
+          throw new Error('Unreadable app identity');
+        }
+        ids.add(id);
+      } catch {
+        errors.push(`Cannot inventory ${full}`);
+      }
+    } else {
+      await installedIds(full, ids, errors, depth + 1);
+    }
+  }
+}
+
+export async function appLeftovers(home = os.homedir()) {
+  const ids = new Set();
+  const errors = [];
+  for (const root of [
+    '/Applications',
+    '/System/Applications',
+    path.join(home, 'Applications'),
+  ]) {
+    try {
+      await installedIds(root, ids, errors);
+    } catch (error) {
+      errors.push(`${root}: ${error.message}`);
+    }
+  }
+  const items = [];
+  for (const kind of [
+    'Caches',
+    'Logs',
+    'Application Support',
+    'Containers',
+    'Group Containers',
+    'Preferences',
+    'Saved Application State',
+  ]) {
+    const root = path.join(home, 'Library', kind);
+    const entries = await fs.readdir(root).catch(() => []);
+    for (const name of entries) {
+      const id = name.replace(/\.(plist|savedState)$/, '');
+      if (
+        (kind !== 'Logs' &&
+          !/^(?:com|org|net|io|dev|ai|app|at|ru|us|notion)\.[a-zA-Z0-9_.-]+$/.test(
+            id
+          )) ||
+        id.startsWith('com.apple.')
+      ) {
+        continue;
+      }
+      if (
+        [...ids].some(
+          (installed) =>
+            installed === id ||
+            installed.startsWith(`${id}.`) ||
+            id.startsWith(`${installed}.`)
+        )
+      ) {
+        continue;
+      }
+      items.push({
+        path: path.join(root, name),
+        category: leftoverCategory(kind),
+        status: 'possible-leftover',
+        reason:
+          'No matching bundle in standard application folders; app may be elsewhere or ownership shared',
+        automaticDeletion: false,
+      });
+    }
+  }
+  return {
+    items,
+    errors,
+    note: 'Read-only candidates, not proof of uninstall. Logs can contain diagnostic history. No support data is automatically removed.',
+  };
+}
+
+async function trashApp(identity) {
+  const fresh = await appIdentity(identity.path);
+  if (
+    fresh.inode !== identity.inode ||
+    fresh.device !== identity.device ||
+    fresh.id !== identity.id
+  ) {
+    throw new Error('Application changed during removal');
+  }
+  const env = new LocalEnv();
+  const probe = new LivenessProbe(env, { staleAgeMs: 0 });
+  await probe.refresh(true);
+  await probe.resolve([identity.path]);
+  const blocker = probe.busyReason({
+    paths: [identity.path],
+    checks: { mtime: false },
+  });
+  if (blocker) {
+    throw new Error(blocker);
+  }
+  const result = await runProcess([
+    '/usr/bin/osascript',
+    '-l',
+    'JavaScript',
+    '-e',
+    TRASH,
+    identity.path,
+  ]);
+  if (result.code) {
+    throw new Error(result.stderr || 'macOS Trash operation failed');
+  }
+  if (
+    await fs.lstat(identity.path).then(
+      () => true,
+      () => false
+    )
+  ) {
+    throw new Error('Trash operation did not remove the original path');
+  }
+  return result.stdout.trim();
+}
+
+function removalDryRun(values) {
+  return !values.yes || Boolean(values['dry-run']);
+}
+
+export async function runApps(argv, io, signal) {
+  if (process.platform !== 'darwin') {
+    throw new Error('apps is currently macOS-only');
+  }
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      yes: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      'launcher-only': { type: 'boolean' },
+      json: { type: 'boolean' },
+      'audit-dir': { type: 'string' },
+    },
+  });
+  const [command, ...targets] = positionals;
+  if (command === 'leftovers') {
+    io.stdout(JSON.stringify(await appLeftovers(), null, 2));
+    return 0;
+  }
+  if (command !== 'remove' || !targets.length) {
+    throw new Error(
+      'Use apps remove /absolute/App.app [--yes] [--launcher-only], or apps leftovers'
+    );
+  }
+  const audit = startAudit('apps-remove', {
+    dryRun: removalDryRun(values),
+  });
+  for (const target of targets) {
+    if (signal?.aborted) {
+      throw new Error('Aborted');
+    }
+    try {
+      const identity = await appIdentity(target);
+      if (identity.hasReceipt) {
+        throw new Error('App Store app: use the macOS uninstall flow');
+      }
+      if (identity.webApp && !values['launcher-only']) {
+        throw new Error(
+          'Use Chrome > chrome://apps > Uninstall first; --launcher-only explicitly permits the Trash fallback, preserving browser data and registration'
+        );
+      }
+      const destination = audit.dryRun ? null : await trashApp(identity);
+      audit.entries.push({
+        ...identity,
+        status: audit.dryRun ? 'would-trash' : 'trashed',
+        destination,
+      });
+    } catch (error) {
+      audit.entries.push({
+        path: target,
+        status: 'blocked',
+        reason: error.message,
+      });
+    }
+  }
+  const file = await writeAudit(audit, { auditDir: values['audit-dir'] });
+  io.stdout(JSON.stringify({ ...audit, auditFile: file }, null, 2));
+  return audit.entries.some((entry) => entry.status === 'blocked') ? 1 : 0;
+}

package/src/options.js

@@ -8,6 +8,7 @@ import { parseDuration, parsePercent, parseSize } from './units.js';
 
 export const DEFAULTS = {
   roots: null,
+  containerRoots: null,
   maxDepth: 6,
   staleAge: '1h',
   inactive: '30d',
@@ -78,9 +79,11 @@ export function resolveOptions(input = {}) {
     throw new Error('scanBudget must be a positive finite duration');
   }
   const roots = toList(merged.roots);
+  const containerRoots = toList(merged.containerRoots);
   return {
     ...merged,
     roots: roots.length > 0 ? roots : null,
+    containerRoots: containerRoots.length > 0 ? containerRoots : null,
     maxDepth: Number(merged.maxDepth),
     dockerDepth: Number(merged.dockerDepth),
     staleAgeMs: toMs(staleAge),

package/src/report.js

@@ -455,6 +455,18 @@ function swapLines(swap) {
   ];
 }
 
+/** Requested roots that were not searched, so coverage gaps are visible. */
+function scopeLines(env) {
+  const skipped = (env.scope?.roots ?? []).filter(
+    (root) =>
+      ['roots', 'container-roots'].includes(root.source) &&
+      !['searched', 'pending'].includes(root.status)
+  );
+  return skipped.map(
+    (root) => `  ${env.label}: root ${root.path} ${root.status}`
+  );
+}
+
 function environmentStatusLines(env) {
   const lines = [];
   if (env.layerSource) {
@@ -470,6 +482,7 @@ function environmentStatusLines(env) {
   if (env.hint) {
     lines.push(`  ${env.label}: ${env.hint}`);
   }
+  lines.push(...scopeLines(env));
   return lines;
 }
 

package/src/scan-state.js

@@ -98,6 +98,7 @@ export async function authenticatedReport(report, directory, now = Date.now()) {
 export function scopeKey(options) {
   const names = [
     'roots',
+    'containerRoots',
     'scanners',
     'host',
     'docker',

package/src/scan.js

@@ -13,13 +13,20 @@ import { scanDocker } from './docker/scan.js';
 import { LocalEnv } from './env/local.js';
 import { configureScanPolicy } from './env/policy.js';
 import { configureCacheRoots } from './env/cache-roots.js';
+import {
+  CONTAINER_ROOTS,
+  finishScope,
+  requestedRoots,
+  resolveRoots,
+  scanScope,
+} from './env/roots.js';
 import { checkSignal, environmentScope } from './env/scope.js';
 import { block, tierTotals } from './items.js';
 import { hostExecutor, trace } from './exec.js';
 import { GitInspector } from './git.js';
 import { LivenessProbe } from './liveness.js';
 import { resolveOptions } from './options.js';
-import { existingPaths, isWithin, matchesExcluded } from './paths.js';
+import { isWithin, matchesExcluded } from './paths.js';
 import { scanAgents } from './scanners/agents.js';
 import { GLOBAL_RULES, scanGlobal, targetedRules } from './scanners/global.js';
 import { scanProjects } from './scanners/projects.js';
@@ -50,6 +57,7 @@ const reportEnvironments = new WeakMap();
 export const scannedEnvironment = (report) => reportEnvironments.get(report);
 const RESCAN_OPTIONS = new Set([
   'roots',
+  'containerRoots',
   'scanners',
   'containers',
   'host',
@@ -120,6 +128,7 @@ export async function revalidateReport(saved, input = {}) {
   const scope = Object.fromEntries(
     [
       'roots',
+      'containerRoots',
       'scanners',
       'containers',
       'host',
@@ -140,25 +149,7 @@ export async function revalidateReport(saved, input = {}) {
   return sealReport(current);
 }
 
-/** Common project locations inside containers, scanned when present. */
-export const CONTAINER_ROOTS = [
-  '/workspace',
-  '/workspaces',
-  '/app',
-  '/src',
-  '/code',
-  '/project',
-  '/usr/src/app',
-];
-
-async function defaultRoots(env, homes, tmpDirs) {
-  const roots = [...homes, ...tmpDirs];
-  if (env.kind === 'container') {
-    const present = await existingPaths(env, CONTAINER_ROOTS);
-    roots.push(...CONTAINER_ROOTS.filter((root) => present.has(root)));
-  }
-  return [...new Set(roots)];
-}
+export { CONTAINER_ROOTS };
 
 /**
  * Builds the scanner context of one environment.
@@ -169,7 +160,7 @@ async function defaultRoots(env, homes, tmpDirs) {
 export async function environmentContext(env, options, overrides = {}) {
   await configureScanPolicy(env, {
     ...options,
-    roots: overrides.roots ?? options.roots,
+    roots: requestedRoots(env, options, overrides),
   });
   const liveness = new LivenessProbe(env, {
     staleAgeMs: options.staleAgeMs,
@@ -180,7 +171,14 @@ export async function environmentContext(env, options, overrides = {}) {
   const homes = await env.homeDirs();
   await configureCacheRoots(env, homes);
   const tmpDirs = await env.tmpDirs();
-  const roots = overrides.roots ?? (await defaultRoots(env, homes, tmpDirs));
+  const { roots, entries } = await resolveRoots(
+    env,
+    options,
+    overrides,
+    homes,
+    tmpDirs
+  );
+  env.scanScope = scanScope(env, options, entries);
   return {
     env,
     git: new GitInspector(env),
@@ -274,6 +272,7 @@ export async function scanEnvironment(env, options, extra = {}) {
     }
     return items;
   } finally {
+    finishScope(env, selectedScanners(options).includes('projects'));
     clearTimeout(timer);
     clearInterval(interval);
     options.signal?.removeEventListener('abort', abort);
@@ -551,6 +550,7 @@ function envDescriptor(env, depth, chain) {
     chain,
     hint: env.probeHint ?? null,
     scanStatus: env.scanStatus ?? null,
+    scope: env.scanScope ?? null,
     layerSource: env.writableLayer?.source ?? null,
     timings: env.timings?.toJSON() ?? [],
   };
@@ -570,6 +570,15 @@ async function withDisk(env, descriptor, options) {
   };
 }
 
+/**
+ * Scans one running container found by the Docker walk (any depth). Roots
+ * come from `containerRoots`/`roots` via environmentContext, never from the
+ * host's resolved defaults.
+ */
+export function containerScanner(options, errors) {
+  return (inner) => scanEnvironment(inner, options, { errors });
+}
+
 async function dockerSection(env, options, errors) {
   if (options.docker === false) {
     return null;
@@ -583,7 +592,7 @@ async function dockerSection(env, options, errors) {
     const result = await scanDocker(
       hostRecord,
       { ...options, selfContainerIds: await selfContainerIds(env) },
-      (inner) => scanEnvironment(inner, options, { errors })
+      containerScanner(options, errors)
     );
     errors.push(...result.errors);
     if (options.docker === true && result.daemons.length === 0) {

package/src/scanners/agents.js

@@ -20,6 +20,7 @@ import { scanItems } from '../env/scope.js';
  * (the same rule the agent's own `Project.prune()` uses).
  */
 
+import { itemSize } from '../env/hardlinks.js';
 import { block, makeItem } from '../items.js';
 import { listMany, olderThan, scanTimeBusy } from './common.js';
 
@@ -127,7 +128,7 @@ async function appItems(context, app, root) {
       ecosystem: 'agents',
       description: `${app.name} snapshot store ${state.entry.name}`,
       path: state.entry.path,
-      bytes: usage.bytes,
+      ...itemSize([[state.entry.path, usage]]),
       newestMtimeMs: usage.newestMtimeMs,
       worktree: state.worktree,
       ...verdict,

package/src/scanners/global.js

@@ -6,6 +6,7 @@ import { checkSignal, scanItems } from '../env/scope.js';
  * ../rules/downloads.js.
  */
 
+import { itemSize } from '../env/hardlinks.js';
 import { CACHE_RULES } from '../rules/ecosystems.js';
 import { OTHER_RULES, TEMP_CLONE_RULES } from '../rules/other.js';
 import { APP_RULES, expandChromiumCaches } from '../rules/apps.js';
@@ -199,7 +200,7 @@ async function buildItem(context, rule, base, group, homes) {
     description: rule.description,
     path: paths[0],
     paths,
-    bytes: group.reduce((sum, entry) => sum + entry.usage.bytes, 0),
+    ...itemSize(group.map((entry) => [entry.path, entry.usage])),
     sizeEstimated: group.some((entry) => entry.usage.estimated),
     newestMtimeMs: Math.max(...group.map((e) => e.usage.newestMtimeMs ?? 0)),
     tier: rule.tier ?? 'safe',

package/src/scanners/projects.js

@@ -1,5 +1,6 @@
 import { performance } from 'node:perf_hooks';
 
+import { itemSize } from '../env/hardlinks.js';
 import { scanItems } from '../env/scope.js';
 /**
  * Per-project dependency, build and cache directories (node_modules, target,
@@ -241,7 +242,7 @@ async function projectItem(context, { candidate, rule }, usage) {
     ecosystem: rule.ecosystem,
     description: `${ECOSYSTEM_NAMES.get(rule.ecosystem)} ${rule.description}`,
     path: candidate.path,
-    bytes: usage?.bytes ?? 0,
+    ...itemSize([[candidate.path, usage]]),
     sizeEstimated: Boolean(usage?.estimated),
     newestMtimeMs: usage?.newestMtimeMs ?? 0,
     project,