disk-space-saviour 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.21.0
+
+### Minor Changes
+
+- Keep a Chromium code-sign clone while any process runs its hard-linked main executable, under the installed path or the clone's, at scan time and right before deletion; a clone that still shares its blocks with the installed app reports no reclaimable space.
+
+  Warn when swap grows, nearly fills, or outgrows the free disk space, naming the processes holding the memory and how much each grew since earlier scans (with Linux `VmSwap` support), and offer Git clones in temporary directories as safe once every worktree is clean and `git ls-remote` shows the remote still holds every local commit.
+
+  Keep a Playwright browser revision while an installed Playwright package recorded in the registry's `.links` still launches it (rechecked right before deletion), offer Playwright installs and downloads left in temporary directories, offer unused nvm Node versions while naming the global packages they take with them, and limit Telegram downloaded media to the cloud files Telegram downloads again, never its media database or files the user sent.
+
 ## 0.20.0
 
 ### Minor Changes

package/README.md

@@ -97,11 +97,11 @@ ranked by how recently it was used: a cache, build output or dependency
 directory is `safe` and is held back only while something uses it (see
 [Safety](#safety)).
 
-| Tier         | What it removes                                                                                                                                                                                                                                                                                                           |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `safe`       | Everything regenerable: download, runtime and application caches, idle package-runner entries, old browser revisions, `node_modules`, `vendor`, `target/`, `.venv`, `build/` and similar folders of any project, dangling Docker images and build cache.                                                                  |
-| `moderate`   | Data that is disposable but not regenerated by a tool: old agent scratch and Telegram downloaded media (secret-chat media may be irreplaceable), unused toolchain versions (never one holding globally installed packages or virtual environments), tagged images and stopped containers (both require explicit consent). |
-| `aggressive` | Accepted by `dss emergency` for compatibility; currently the same as `moderate`.                                                                                                                                                                                                                                          |
+| Tier         | What it removes                                                                                                                                                                                                                                                                                                                                                |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `safe`       | Everything regenerable: download, runtime and application caches, idle package-runner entries, old browser revisions, `node_modules`, `vendor`, `target/`, `.venv`, `build/` and similar folders of any project, dangling Docker images and build cache.                                                                                                       |
+| `moderate`   | Data that is disposable but not regenerated by a tool: old agent scratch and Telegram downloaded media (secret-chat media may be irreplaceable), unused toolchain versions no process runs from (the item names the global packages it removes; never one holding virtual environments), tagged images and stopped containers (both require explicit consent). |
+| `aggressive` | Accepted by `dss emergency` for compatibility; currently the same as `moderate`.                                                                                                                                                                                                                                                                               |
 
 Covered ecosystems: JavaScript/TypeScript (npm, yarn, pnpm, bun, deno,
 framework build caches), Python, Rust, JVM (Gradle, Maven, Kotlin, Android),
@@ -115,15 +115,21 @@ LibreWolf, Waterfox, Zen and Floorp, IDE caches (JetBrains, VS Code, Cursor,
 Windsurf, Qoder), AI agent caches and logs, the Discord cache, macOS app
 updates staged by Sparkle and Squirrel, package manager archives, trash, crash
 reports, core dumps and journald logs. Application downloads are covered too:
-Chrome bundle clones left by exited browsers, Chromium on-device AI models
+Chrome bundle clones left by exited browsers (kept while any browser runs the
+clone's hard-linked executable, and counted as free when they still share
+their blocks with the installed app), Chromium on-device AI models
 (downloaded again when a page uses built-in AI), Google Updater installers, ChatGPT Atlas and Codex app caches,
 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,
 Chromium code/GPU/Dawn/service-worker caches and marker-validated Electron
-caches are included. Telegram databases, browser profiles and Playwright MCP
-profiles are preserved. macOS access failures explain when Full Disk Access
+caches are included. Old Playwright browser revisions are kept while a
+Playwright package recorded in the registry's `.links` still launches them or
+a browser runs from them; Playwright installs and downloads left in temporary
+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.
 
 ## Safety
@@ -241,10 +247,27 @@ and sizes. Safe cleanup also rechecks source activity. Explicit moderate cleanup
 preserves the ability to remove ignored dependencies when only source changed.
 Library callers opt into state with `cacheDir`.
 
-On macOS, reports include `sysctl vm.swapusage` and the largest resident/compressed
-memory consumers from `top`. These are memory diagnostics, not verified per-process
-swap ownership. When Docker Desktop consumes memory, saving work and restarting it
-or lowering its VM memory limit can help. dss never deletes swap files.
+On macOS, reports include `sysctl vm.swapusage` and the largest memory consumers
+from `top` (memory includes compressed and swapped pages). These are memory
+diagnostics, not verified per-process swap ownership. On Linux, reports include
+`/proc/meminfo` swap and the processes with the most swapped memory (`VmSwap`).
+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
+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.
+
+Git clones in temporary directories (`{TMP}/*` and `{TMP}/*/*`) are safe to remove
+once untouched for the activity window when every worktree sharing the repository
+is clean, none lives outside the clone, nothing is stashed, and every commit
+reachable from `HEAD`, a branch or a worktree is advertised by an https or ssh
+remote. That last check runs `git ls-remote` against the remote rather than
+trusting remote-tracking refs, outside any repository, with only the https and
+ssh transports and no prompts. Clones of local paths and clones whose `.git` is a
+symlink are left alone, and cleanup repeats every check right before deleting.
 
 Cache discovery honors tool configuration before default paths, including
 `GOMODCACHE`, `GOPATH`, `GOCACHE`, `CARGO_HOME`, `RUSTUP_HOME`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk-space-saviour",
-  "version": "0.20.0",
+  "version": "0.21.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

@@ -39,6 +39,7 @@ import { GitInspector } from './git.js';
 import { HealthWatch } from './health.js';
 import { consentFlag, dropNested, selectByTier, tierRank } from './items.js';
 import { LivenessProbe } from './liveness.js';
+import { playwrightBlocker } from './playwright-registry.js';
 import { resolveOptions } from './options.js';
 import { isWithin } from './paths.js';
 import { OTHER_RULES } from './rules/other.js';
@@ -132,6 +133,11 @@ async function browserRevisionBlocker(env, item) {
     if (!newer) {
       return `${target} is now the newest installed browser revision`;
     }
+    const needed =
+      rule.registry === 'playwright' && (await playwrightBlocker(env, target));
+    if (needed) {
+      return needed;
+    }
   }
   return null;
 }
@@ -432,6 +438,7 @@ export class Cleaner {
   async #safetyBlocker(ctx, item, type) {
     await ctx.liveness.refresh(true);
     await ctx.liveness.resolve(item.paths);
+    await ctx.liveness.resolveExecutables(item.checks?.executables);
     const busy = ctx.liveness.busyReason(item);
     if (busy) {
       return `busy: ${busy}`;
@@ -475,6 +482,11 @@ export class Cleaner {
   }
 
   async #gitBlocker(ctx, item) {
+    if (item.recheck?.type === 'clone') {
+      ctx.git.invalidate();
+      const blockers = await ctx.git.cloneBlockers(item.path);
+      return blockers.length > 0 ? blockers.join('; ') : null;
+    }
     if (
       item.project ||
       item.rule === 'gh-issue-solver-workdirs' ||
@@ -667,6 +679,7 @@ export class Cleaner {
       return `stopped before ${target}: ${stopped}`;
     }
     await ctx.liveness.resolve([target]);
+    await ctx.liveness.resolveExecutables(item.checks?.executables);
     const busy = ctx.liveness.busyReason({ ...item, paths: [target] });
     return busy ? `stopped before ${target}: busy: ${busy}` : null;
   }

package/src/env/local.js

@@ -333,6 +333,24 @@ export class LocalEnv {
     return heads;
   }
 
+  /** Another user's entry of a sticky shared directory such as /tmp is private by design. */
+  async #foreignTempEntry(dir) {
+    const io = this.options.fileFs ?? fsp;
+    try {
+      const [own, parent] = await Promise.all([
+        io.lstat(dir),
+        io.stat(path.dirname(dir)),
+      ]);
+      return (
+        typeof process.getuid === 'function' &&
+        own.uid !== process.getuid() &&
+        (parent.mode & 0o1000) !== 0
+      );
+    } catch {
+      return false;
+    }
+  }
+
   async list(dir, { discovery = false } = {}) {
     let names;
     try {
@@ -340,7 +358,9 @@ export class LocalEnv {
         withFileTypes: true,
       });
     } catch (error) {
-      this.recordAccessError(dir, error);
+      if (!(await this.#foreignTempEntry(dir))) {
+        this.recordAccessError(dir, error);
+      }
       return [];
     }
     const entries = await mapLimit(names, 32, async (entry) => {

package/src/git-remote.js

@@ -0,0 +1,168 @@
+/**
+ * Proof that a repository's commits still exist on a network remote, and
+ * the linked worktrees that share its object database.
+ *
+ * Remote URLs are read from the repository config but never used through
+ * it: `git ls-remote` runs outside any repository, with only the https and
+ * ssh transports allowed and no prompts, so a planted config cannot run
+ * commands or ask for credentials. Only advertised branches, tags and
+ * review refs (`refs/pull/*`, `refs/merge-requests/*`) count, and only the
+ * advertised commits that exist locally, so "on the remote" never relies
+ * on cached remote-tracking refs.
+ */
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const LS_REMOTE_TIMEOUT_MS = 30 * 1000;
+const ADVERTISED = [
+  'refs/heads/*',
+  'refs/tags/*',
+  'refs/pull/*/head',
+  'refs/merge-requests/*/head',
+];
+
+/**
+ * A remote URL `git ls-remote` may contact: https/http or ssh, with a host
+ * that cannot be mistaken for an option. Local paths and `file://` remotes
+ * are not proof that the code exists elsewhere.
+ */
+export function networkRemote(url) {
+  const value = url.trim();
+  if (/\s/.test(value) || value.startsWith('-')) {
+    return null;
+  }
+  const standard = /^(https?|ssh|git\+ssh):\/\/(?:[^@/]+@)?([^/:]+)/i.exec(
+    value
+  );
+  const scp = /^(?:[\w.-]+@)?([\w.-]+):(?!\/\/)[^\\]/.exec(value);
+  const host = standard?.[2] ?? scp?.[1];
+  // `C:/repo` is a Windows path, not the host `C`.
+  const drive = !standard && /^[a-z]$/i.test(host ?? '');
+  return host && !drive && /^[\w.[\]-]+$/.test(host) && !host.startsWith('-')
+    ? { url: value, host }
+    : null;
+}
+
+/** `remote.<name>.url` values from a Git config, as `{name, url}`. */
+export function parseRemoteUrls(text) {
+  const remotes = [];
+  let remote = null;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    const section = /^\[\s*remote\s+"([^"]+)"\s*\]$/i.exec(line);
+    if (section) {
+      remote = section[1];
+      continue;
+    }
+    if (/^\[/.test(line)) {
+      remote = null;
+      continue;
+    }
+    const url = /^url\s*=\s*(.+)$/i.exec(line);
+    if (remote && url) {
+      remotes.push({ name: remote, url: url[1].replace(/^"(.*)"$/, '$1') });
+    }
+  }
+  return remotes;
+}
+
+/** Commit IDs from `git ls-remote` output, peeled tags included. */
+export function advertisedCommits(text) {
+  return [
+    ...new Set(
+      text
+        .split('\n')
+        .map((line) => /^([0-9a-f]{40,64})\t/.exec(line)?.[1])
+        .filter(Boolean)
+    ),
+  ];
+}
+
+/** Network remotes of the repository whose common Git directory is given. */
+export async function networkRemotes(commonDir) {
+  const text = await fsp
+    .readFile(path.join(commonDir, 'config'), 'utf8')
+    .catch(() => '');
+  return parseRemoteUrls(text)
+    .map((remote) => ({ name: remote.name, ...networkRemote(remote.url) }))
+    .filter((remote) => remote.host);
+}
+
+/**
+ * Work trees attached to a common Git directory: the main one (unless the
+ * repository is bare) and every linked one that still exists, with the
+ * detached HEAD commits of linked worktrees.
+ */
+export async function attachedWorktrees(commonDir) {
+  const trees = [];
+  const detached = [];
+  const config = await fsp
+    .readFile(path.join(commonDir, 'config'), 'utf8')
+    .catch(() => '');
+  if (
+    path.basename(commonDir) === '.git' &&
+    !/^\s*bare\s*=\s*true/m.test(config)
+  ) {
+    trees.push(path.dirname(commonDir));
+  }
+  const base = path.join(commonDir, 'worktrees');
+  for (const name of await fsp.readdir(base).catch(() => [])) {
+    const read = (file) =>
+      fsp.readFile(path.join(base, name, file), 'utf8').catch(() => '');
+    const gitdir = (await read('gitdir')).trim();
+    const head = (await read('HEAD')).trim();
+    if (/^[0-9a-f]{40,64}$/.test(head)) {
+      detached.push(head);
+    }
+    if (gitdir) {
+      const tree = path.dirname(path.resolve(base, name, gitdir));
+      if (await fsp.stat(tree).catch(() => null)) {
+        trees.push(tree);
+      }
+    }
+  }
+  return { trees, detached };
+}
+
+/**
+ * Runs `git ls-remote` for `url` outside every repository.
+ * @param {(argv: string[], options: object) => Promise<object>} run
+ */
+export async function lsRemote(run, url) {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'dss-ls-remote-'));
+  try {
+    return await run(
+      [
+        'git',
+        '-c',
+        'protocol.allow=never',
+        '-c',
+        'protocol.https.allow=always',
+        '-c',
+        'protocol.http.allow=always',
+        '-c',
+        'protocol.ssh.allow=always',
+        '-c',
+        'core.hooksPath=/dev/null',
+        '-C',
+        dir,
+        'ls-remote',
+        url,
+        ...ADVERTISED,
+      ],
+      {
+        timeoutMs: LS_REMOTE_TIMEOUT_MS,
+        env: {
+          GIT_TERMINAL_PROMPT: '0',
+          GIT_ASKPASS: '',
+          SSH_ASKPASS: '',
+          GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o ConnectTimeout=15',
+          GIT_CEILING_DIRECTORIES: path.dirname(dir),
+        },
+      }
+    );
+  } finally {
+    await fsp.rm(dir, { recursive: true, force: true });
+  }
+}

package/src/git.js

@@ -16,6 +16,12 @@ import path from 'node:path';
 
 import { trace } from './exec.js';
 import { preservedWork } from './git-preserved.js';
+import {
+  advertisedCommits,
+  attachedWorktrees,
+  lsRemote,
+  networkRemotes,
+} from './git-remote.js';
 
 const GIT_FLAGS = [
   '--no-optional-locks',
@@ -42,7 +48,7 @@ const SAFE_GIT_ENV = {
  * a linked worktree or a submodule has a `.git` file naming its directory,
  * and a linked worktree names the common directory in `commondir`.
  */
-async function gitDirectories(root) {
+export async function gitDirectories(root) {
   const dotGit = path.join(root, '.git');
   const stat = await fsp.lstat(dotGit);
   let gitDir = dotGit;
@@ -176,10 +182,11 @@ export class GitInspector {
     this.options = options;
     this.states = new Map();
     this.roots = new Map();
+    this.remoteRefs = new Map();
     this.available = null;
   }
 
-  async #git(root, args, safeDir = null) {
+  async #git(root, args, safeDir = null, input = undefined) {
     const result = await this.env.run(
       [
         'git',
@@ -189,7 +196,7 @@ export class GitInspector {
         ...(safeDir ? ['--git-dir', safeDir, '--work-tree', root] : []),
         ...args,
       ],
-      { env: SAFE_GIT_ENV }
+      { env: SAFE_GIT_ENV, input }
     );
     trace('git', root, args.join(' '), '->', result.code);
     return result;
@@ -246,6 +253,7 @@ export class GitInspector {
   invalidate() {
     this.states.clear();
     this.roots.clear();
+    this.remoteRefs.clear();
   }
 
   async #loadState(root) {
@@ -322,8 +330,8 @@ export class GitInspector {
     return stateBlockers(root, await this.repoState(root));
   }
 
-  /** Protect an entire temporary work directory, including nested clones. */
-  async treeBlockers(target, { allowNoRepo = false } = {}) {
+  /** Repositories at or below `target`. */
+  async #repoRoots(target) {
     const dirs = await this.env.findDirs([target], {
       globs: ['.git'],
       maxDepth: 32,
@@ -334,13 +342,18 @@ export class GitInspector {
       maxDepth: 32,
       skipNames: [],
     });
-    const roots = new Set([
+    return new Set([
       ...((await this.env.exists(this.env.path.join(target, '.git')))
         ? [target]
         : []),
       ...dirs.map((entry) => entry.parent),
       ...files.map((file) => this.env.path.dirname(file)),
     ]);
+  }
+
+  /** Protect an entire temporary work directory, including nested clones. */
+  async treeBlockers(target, { allowNoRepo = false } = {}) {
+    const roots = await this.#repoRoots(target);
     if (roots.size === 0) {
       if (allowNoRepo) {
         return [];
@@ -357,6 +370,134 @@ export class GitInspector {
     return blockers;
   }
 
+  /**
+   * Reasons a temporary clone must not be deleted. Every repository inside
+   * `target` must have no uncommitted, unpushed or stashed work in any of
+   * its worktrees, no linked worktree outside `target`, and every local
+   * commit must be advertised by one of its https or ssh remotes.
+   */
+  async cloneBlockers(target) {
+    if (this.env.kind !== 'host') {
+      return [`${target}: remote copies are only verified on the host`];
+    }
+    if (!(await this.isAvailable())) {
+      return [`${target}: git is not installed, cannot verify the repository`];
+    }
+    const roots = await this.#repoRoots(target);
+    if (roots.size === 0) {
+      return [`${target}: no Git repository found; cannot verify work`];
+    }
+    if (roots.size > 50) {
+      return [`${target}: too many repositories to verify safely`];
+    }
+    const blockers = [];
+    for (const root of roots) {
+      blockers.push(...(await this.#cloneRootBlockers(root, target)));
+    }
+    return blockers;
+  }
+
+  async #cloneRootBlockers(root, target) {
+    let commonDir;
+    try {
+      ({ commonDir } = await gitDirectories(root));
+    } catch (error) {
+      return [`${root}: ${error.message}`];
+    }
+    const inside = (dir) => {
+      const relative = path.relative(target, dir);
+      return (
+        relative === '' ||
+        (!relative.startsWith('..') && !path.isAbsolute(relative))
+      );
+    };
+    const { trees, detached } = await attachedWorktrees(commonDir);
+    // Deleting the repository strands every worktree that shares it.
+    const affected = inside(commonDir) ? [root, ...trees] : [root];
+    const blockers = [];
+    for (const tree of new Set(affected)) {
+      if (!inside(tree)) {
+        blockers.push(`linked worktree ${tree} uses the repository in ${root}`);
+      } else if (await this.env.exists(path.join(tree, '.git'))) {
+        blockers.push(...(await this.repoBlockers(tree)));
+      }
+    }
+    if (blockers.length > 0) {
+      return blockers;
+    }
+    return this.#remoteBlockers(root, commonDir, detached);
+  }
+
+  async #remoteBlockers(root, commonDir, detached) {
+    const remotes = await networkRemotes(commonDir);
+    if (remotes.length === 0) {
+      return [`Git repository ${root} has no https or ssh remote holding it`];
+    }
+    const advertised = [];
+    const unreachable = [];
+    for (const remote of remotes) {
+      if (!this.remoteRefs.has(remote.url)) {
+        this.remoteRefs.set(
+          remote.url,
+          lsRemote((argv, options) => this.env.run(argv, options), remote.url)
+        );
+      }
+      const result = await this.remoteRefs.get(remote.url);
+      if (result.code === 0) {
+        advertised.push(...advertisedCommits(result.stdout));
+      } else {
+        unreachable.push(`${remote.name} (${remote.host})`);
+      }
+    }
+    if (advertised.length === 0) {
+      return [
+        `cannot confirm Git repository ${root} on a remote: ${unreachable.length > 0 ? `${unreachable.join(', ')} unreachable` : 'its remotes advertise nothing'}`,
+      ];
+    }
+    try {
+      const missing = await safeGitDirectory(root, (safeDir) =>
+        this.#commitsMissingFrom(root, safeDir, advertised, detached)
+      );
+      if (missing === 0) {
+        return [];
+      }
+      const hosts = [...new Set(remotes.map((remote) => remote.host))];
+      return [
+        `Git repository ${root} has ${plural(missing, 'commit')} no branch, tag or pull request on ${hosts.join(', ')} contains`,
+      ];
+    } catch (error) {
+      return [`cannot compare ${root} with its remote: ${error.message}`];
+    }
+  }
+
+  /** Local commits reachable from HEAD, branches or `detached` but no advertised commit. */
+  async #commitsMissingFrom(root, safeDir, advertised, detached) {
+    const known = await this.#git(
+      root,
+      ['cat-file', '--batch-check=%(objectname) %(objecttype)'],
+      safeDir,
+      `${advertised.join('\n')}\n`
+    );
+    if (known.code !== 0) {
+      throw new Error(known.stderr.trim() || `exit ${known.code}`);
+    }
+    const commits = known.stdout
+      .split('\n')
+      .map((line) => /^([0-9a-f]+) commit$/.exec(line)?.[1])
+      .filter(Boolean);
+    const tips = ['HEAD', '--branches', ...detached];
+    const count = await this.#git(
+      root,
+      ['rev-list', '--count', '--stdin', ...tips],
+      safeDir,
+      commits.map((commit) => `^${commit}\n`).join('')
+    );
+    if (count.code !== 0) {
+      throw new Error(count.stderr.trim() || `exit ${count.code}`);
+    }
+    return Number(count.stdout.trim());
+  }
+
   /**
    * Number of tracked files inside `target` (a path within `root`).
    * Returns -1 when Git cannot answer.

package/src/index.d.ts

@@ -172,9 +172,19 @@ export interface EnvironmentDescriptor {
     holders: Array<{
       pid: number;
       command: string;
+      /** Resident plus compressed and swapped memory. */
       memoryBytes: number;
-      compressedBytes: number;
+      /** macOS only. */
+      compressedBytes?: number;
+      /** Linux only (`VmSwap`). */
+      swappedBytes?: number;
+      /** Change since the earliest scan of the last week listing this process. */
+      growth?: { since: number; memoryBytes: number };
     }>;
+    /** Change since the earliest scan of the last week. */
+    growth?: { since: number; usedBytes: number } | null;
+    /** Large, growing, or disk-threatening swap, naming the memory holders. */
+    warnings?: string[];
     attribution: string;
     advice: string;
   } | null;

package/src/liveness.js

@@ -212,6 +212,7 @@ export class LivenessProbe {
     this.realPaths = new Map();
     this.pathOwners = new Map();
     this.pathStats = new Map();
+    this.inodes = new Map();
   }
 
   async refresh(force = false) {
@@ -230,6 +231,50 @@ export class LivenessProbe {
     this.realPaths.clear();
     this.pathStats.clear();
     this.pathOwners.clear();
+    this.inodes.clear();
+  }
+
+  /**
+   * Inodes of `executables` and of the open files that share their names,
+   * because a process running a hard link of an executable reports
+   * whichever path it was started from.
+   * @param {string[]} [executables]
+   */
+  async resolveExecutables(executables = []) {
+    if (executables.length === 0) {
+      return;
+    }
+    const names = new Set(
+      executables.map((target) => this.env.path.basename(target))
+    );
+    const missing = [
+      ...executables,
+      ...[...(this.openPaths ?? [])].filter((open) =>
+        names.has(this.env.path.basename(open))
+      ),
+    ].filter((target) => !this.inodes.has(target));
+    const stats = await Promise.all(
+      missing.map((target) => this.env.stat(target))
+    );
+    missing.forEach((target, index) =>
+      this.inodes.set(target, stats[index]?.inode ?? null)
+    );
+  }
+
+  /** A process running one of `executables` under any of its links. */
+  executableUsage(executables = []) {
+    for (const target of executables) {
+      const inode = this.inodes.get(target);
+      if (!inode) {
+        continue;
+      }
+      for (const open of this.openPaths ?? []) {
+        if (open !== target && this.inodes.get(open) === inode) {
+          return `in use: ${open} is ${target}`;
+        }
+      }
+    }
+    return null;
   }
 
   /**
@@ -511,6 +556,7 @@ export class LivenessProbe {
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
       this.processUsage(paths) ??
+      this.executableUsage(checks.executables) ??
       this.uncertainUsage(item.paths ?? [])
     );
   }