disk-space-saviour 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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
+
+- 9479acd: Keep a `node_modules` folder that holds data no package manager installs, naming each such entry and its size, at scan time and right before deletion.
+
+  Let `clean` and `emergency` delete on a full disk: an audit log that does not fit is reported as not written and written as soon as deletions free space.
+
+  Keep everything inside a live Claude Code session scratchpad until the session and its transcript stay idle for the inactive window, at scan time and right before deletion.
+
+  Show the dss run among swap holders as `(this dss run)` and never name it as a process to quit.
+
+  Name what fills a directory of many small entries in `dss usage` by name pattern, with their count and total size.
+
+  Offer rotated app logs in `~/Library/Logs`, Crashpad reports left unsent for 30 days and the GitHub CLI run-log cache in the moderate tier.
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -94,12 +94,19 @@ Run `dss --help` for every option. The most useful ones:
   files, and for each directory what the latest dss scan or clean found
   inside it (`[dss: 1.2 GiB freeable, 3.4 GiB blocked]`). On macOS it adds
   the APFS volumes a walk cannot see (system, VM swap, Preboot, Recovery),
-  local snapshots and the part of the Data volume left unread. It needs
-  `du`, so it runs on macOS and Linux; a full walk takes minutes.
+  local snapshots and the part of the Data volume left unread. A directory
+  filled by many small entries names what fills it by pattern
+  (`T/ms-*  (68523 entries, each under 64 MiB)`). It needs `du`, so it runs
+  on macOS and Linux; a full walk takes minutes.
 - APFS clones that share every block with an installed app, such as Chrome's
   code-sign clones, free nothing when deleted, so they are never offered. The
   scan lists them under `SHARED WITH INSTALLED APPS` and `dss usage` marks
   them, because `du` and Finder count them at full size.
+- `node_modules` counts as regenerable only while it holds what package
+  managers install: packages, `@scope` folders, `.bin`, lockfile copies and
+  tool caches such as `.cache` or `.vite`. Any other data kept there
+  (verification runs, captured evidence) blocks the whole directory, and the
+  check runs again right before deleting.
 - Git worktree folders (`.worktrees`, `worktrees`) restart the project search
   depth, so dependencies of nested worktrees are found below `--max-depth`.
 - `clean` automatically reuses a matching scan from the last 30 minutes.
@@ -139,7 +146,9 @@ their blocks with the installed app), Chromium on-device AI models
 Electron and electron-builder archives, the Bun transpiler cache, Docker
 Desktop and Warp staged updates (kept while the app runs), Zed language
 servers, tree-sitter toolchains, Codex plugin staging, the Clang module cache
-and processed Crashpad reports. Telegram pure caches, Safari/WebKit,
+Crashpad reports (processed ones, and unsent ones after 30 days), rotated app
+logs in `~/Library/Logs` (`warp.log.old.2`) and the GitHub CLI run-log cache.
+Telegram pure caches, Safari/WebKit,
 Chromium code/GPU/Dawn/service-worker caches and marker-validated Electron
 caches are included. Old Playwright browser revisions are kept while a
 Playwright package recorded in the registry's `.links` still launches them or
@@ -148,6 +157,10 @@ directories are removed once untouched. Telegram caches are removed only
 while Telegram is not running. Telegram databases, browser profiles and
 Playwright MCP profiles are preserved. macOS access failures explain when Full Disk Access
 is needed. Agent scratch cleanup requires inactivity and Git safety checks.
+Anything inside a Claude Code session scratchpad
+(`{TMP}/claude-<uid>/<project>/<session>`) is kept until the session and its
+transcript in `~/.claude/projects` stay untouched for the inactive window
+(30 days), checked again right before deletion.
 
 ## Safety
 
@@ -233,7 +246,10 @@ is needed. Agent scratch cleanup requires inactivity and Git safety checks.
   include every candidate and its blockers; blocked candidates do not
   contribute to reclaimable tier totals.
   If a read-only scan cannot save its audit, it warns and still prints the
-  report. Root scans with another user's `HOME` use a private temporary audit
+  report. When the disk is full, `clean` and `emergency` delete anyway and
+  write their audit as soon as deletions free room; if it never fits, the
+  summary says `Audit log: not written (ENOSPC ...)`. Other audit failures,
+  such as an unusable `--audit-dir`, still stop them before deleting. Root scans with another user's `HOME` use a private temporary audit
   directory. Set `--audit-dir` to choose a persistent writable location.
 
 Long-lived `npm exec`/`npx` servers allow idle npm download and node-gyp
@@ -290,7 +306,8 @@ Each scan records swap usage and its largest holders in the state directory, so
 the next scan shows how much both grew during the last week. A `WARNING:` line
 appears when swap grew by 1 GiB or more, is at least 75% full, or exceeds the free
 disk space it can grow into, naming the processes holding the memory and their
-growth. Long-running AI agent sessions keep their history in memory: quitting and
+growth. The dss run itself is listed as `(this dss run)` and never named as a
+process to quit. Long-running AI agent sessions keep their history in memory: quitting and
 resuming them (`codex resume <session-id>`, `claude --resume`) releases it. When
 Docker Desktop consumes memory, saving work and restarting it or lowering its VM
 memory limit can help. dss never deletes swap files.
@@ -394,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
@@ -759,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.0",
+  "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/audit.js

@@ -101,7 +101,38 @@ export async function writeAudit(audit, options = {}) {
     dir,
     `dss-${audit.command}-${stamp}-${audit.pid}.json`
   );
-  await fsp.writeFile(file, `${JSON.stringify(audit, null, 2)}\n`);
+  // A write that fails half way (a full disk) leaves the previous record.
+  const partial = `${file}.${process.pid}.tmp`;
+  try {
+    await fsp.writeFile(partial, `${JSON.stringify(audit, null, 2)}\n`);
+    await fsp.rename(partial, file);
+  } catch (error) {
+    await fsp.rm(partial, { force: true }).catch(() => {});
+    throw error;
+  }
   audit.file = file;
   return file;
 }
+
+/** Errors meaning the disk is full, which is what cleaning fixes. */
+const NO_SPACE = new Set(['ENOSPC', 'EDQUOT']);
+
+/**
+ * Writes the record of a run that deletes. A full disk does not stop the
+ * run: the failure is kept in `audit.auditError`, and the next write, after
+ * deletions freed space, tries again.
+ * @returns {Promise<string|null>} the file, or null when the disk is full
+ */
+export async function recordAudit(audit, options = {}) {
+  try {
+    const file = await writeAudit(audit, options);
+    delete audit.auditError;
+    return file;
+  } catch (error) {
+    if (!NO_SPACE.has(error.code)) {
+      throw error;
+    }
+    audit.auditError = { message: error.message, code: error.code };
+    return null;
+  }
+}

package/src/clean.js

@@ -12,12 +12,13 @@
  * 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';
 import { finished } from 'node:stream/promises';
 
-import { backupDirectory, startAudit, writeAudit } from './audit.js';
+import { backupDirectory, recordAudit, startAudit } from './audit.js';
 import { PhaseTimer } from './timings.js';
 import { configureContainerHost } from './docker/writable.js';
 import { DockerCli, assertAllowed, parseDockerSize } from './docker/cli.js';
@@ -45,6 +46,7 @@ import { isWithin } from './paths.js';
 import { OTHER_RULES } from './rules/other.js';
 import { compareVersions, VERSION_RULES } from './rules/versions.js';
 import { scanVersions } from './scanners/versions.js';
+import { foreignDataBlocker } from './scanners/node-modules.js';
 import { analyzeRustProfile } from './scanners/rust.js';
 import {
   filterItems,
@@ -78,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) {
@@ -192,6 +195,7 @@ export class Cleaner {
         git: new GitInspector(env),
         liveness: new LivenessProbe(env, {
           staleAgeMs: this.options.staleAgeMs,
+          inactiveMs: this.options.inactiveMs,
           now: this.options.now,
         }),
       });
@@ -332,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,
     };
@@ -447,6 +451,12 @@ export class Cleaner {
     if (mount) {
       return mount;
     }
+    if (item.rule === 'node-modules' && type === 'remove') {
+      const foreign = await foreignDataBlocker(ctx.env, item.path);
+      if (foreign) {
+        return foreign;
+      }
+    }
     return this.#gitBlocker(ctx, item);
   }
 
@@ -551,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';
@@ -591,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;
@@ -630,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
@@ -653,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;
   }
 
@@ -959,7 +985,7 @@ export async function clean(report, input = {}) {
     }
     if (options.audit !== false) {
       await timings.measure('audit-write', () =>
-        writeAudit(audit, { ...options, inProgress: true })
+        recordAudit(audit, { ...options, inProgress: true })
       );
     }
   };
@@ -971,7 +997,7 @@ export async function clean(report, input = {}) {
   audit.health = cleaner.health.records;
   audit.timings = timings;
   if (options.audit !== false) {
-    await writeAudit(audit, { ...options, inProgress: true });
+    await recordAudit(audit, { ...options, inProgress: true });
   }
   try {
     const done = new Set(audit.entries.map((entry) => entry.id));
@@ -988,7 +1014,7 @@ export async function clean(report, input = {}) {
       options.onEntry?.(entry, item);
       if (options.audit !== false) {
         await timings.measure('audit-write', () =>
-          writeAudit(audit, { ...options, inProgress: true })
+          recordAudit(audit, { ...options, inProgress: true })
         );
       }
     }
@@ -1025,7 +1051,7 @@ export async function finishAudit(audit, report, options) {
     )
     .map((env) => ({ label: env.label, status: env.scanStatus }));
   if (options.audit !== false) {
-    await writeAudit(audit, options);
+    await recordAudit(audit, options);
   }
   return audit;
 }

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/conditions.js

@@ -47,6 +47,13 @@ const CONDITIONS = [
       action: `they stay untouched for the ${m[1]} activity window`,
     }),
   ],
+  [
+    /^(?:busy: )?inside the scratchpad of Claude Code session (\S+) .*; kept until it is idle for (.+)$/,
+    (m) => ({
+      key: `session:${m[1]}`,
+      action: `the Claude Code session ${m[1]} stays idle for ${m[2]}`,
+    }),
+  ],
   [
     /^scan incomplete: (.+)$/,
     (m) => ({

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/emergency.js

@@ -12,7 +12,7 @@
  * kept for investigation needs its own `removeContainers` entry.
  */
 
-import { startAudit, writeAudit, throwIfAborted } from './audit.js';
+import { recordAudit, startAudit, throwIfAborted } from './audit.js';
 import { Cleaner, cleanOrder, finishAudit, wantedItems } from './clean.js';
 import { LocalEnv } from './env/local.js';
 import { TIERS, selectByTier, tierRank } from './items.js';
@@ -120,7 +120,7 @@ export async function emergency(input = {}) {
         });
   audit.report = report;
   if (options.audit !== false) {
-    await writeAudit(audit, { ...options, inProgress: true });
+    await recordAudit(audit, { ...options, inProgress: true });
   }
   let disk = audit.diskAfter ?? diskBefore;
   if (report.aborted) {
@@ -145,7 +145,7 @@ async function escalate({ report, options, env, target, goal, audit }) {
       audit.entries.push(entry);
     }
     if (options.audit !== false) {
-      await writeAudit(audit, { ...options, inProgress: true });
+      await recordAudit(audit, { ...options, inProgress: true });
     }
   };
   const cleaner = new Cleaner(report, {
@@ -195,7 +195,7 @@ async function escalate({ report, options, env, target, goal, audit }) {
       }
       options.onEntry?.(entry, item);
       if (options.audit !== false) {
-        await writeAudit(audit, { ...options, inProgress: true });
+        await recordAudit(audit, { ...options, inProgress: true });
       }
       if (entry.status !== 'removed' && entry.status !== 'planned') {
         continue;

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 };
+}