disk-space-saviour 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- 2c706f1: Treat every regenerable project directory as `safe` regardless of how recently
+  the project was used, and block it only while something uses it. Detect
+  processes that keep a directory on their `PATH`, stop a long-running Bun script
+  or Codex daemon from blocking caches they do not use, prune old Codex daemon
+  releases, resolve partial nvm pins to the newest matching install, keep Node.js
+  versions that hold user-installed global packages, inspect Git safety in linked
+  worktrees and submodules, and report per-phase scan timings.
+
 ## 0.17.0
 
 ### Minor Changes

package/README.md

@@ -30,17 +30,17 @@ dss emergency --free 20G --yes      # escalate tiers until 20 GiB is free
 dss docker scan --recursive         # containers and nested daemons
 ```
 
-Example (`dss scan ~/work` on two projects untouched for 40 days):
+Example (`dss scan ~/work` on two projects):
 
 ```
 disk-space-saviour scan of host (build-01) in 3.7s (report only, nothing was deleted)
 /: 75.8 GiB free of 193 GiB (61% used)
 
-MODERATE  2 items, 7.6 MiB
+SAFE  2 items, 7.6 MiB
      4.8 MiB  cargo-target  /home/me/work/api/target
      2.9 MiB  node-modules  /home/me/work/web/node_modules
 
-Reclaimable (cumulative): safe 0 B · moderate 7.6 MiB · aggressive 7.6 MiB; blocked 0 B
+Reclaimable (cumulative): safe 7.6 MiB · moderate 7.6 MiB · aggressive 7.6 MiB; blocked 0 B
 Audit log: /home/me/.local/state/disk-space-saviour/audit/dss-scan-2026-09-26T00-31-05-432Z-232874.json
 Run `dss clean --tier safe` to see the plan, add --yes to delete.
 ```
@@ -87,21 +87,23 @@ Run `dss --help` for every option. The most useful ones:
 
 ## Tiers
 
-Tiers are cumulative: `moderate` includes `safe`, and `aggressive` includes
-both.
+Tiers are cumulative: `moderate` includes `safe`. Regenerable data is never
+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`       | Download and application caches, idle package-runner entries, old browser revisions, inactive lockfile-backed `node_modules`, dangling Docker images and build cache. Includes writable caches inside running containers.                                                                             |
-| `moderate`   | Whole `target/`, `.venv`, `build/` and similar folders of inactive projects; old agent scratch and Telegram downloaded media (secret-chat media may be irreplaceable); unused toolchain versions and tagged images; stopped containers. Container and tagged-image removal requires explicit consent. |
-| `aggressive` | For emergencies: everything regenerable, including build outputs of projects in active use. Only `dss emergency` reaches it.                                                                                                                                                                          |
+| 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`.                                                                                                                                                                                                                                          |
 
 Covered ecosystems: JavaScript/TypeScript (npm, yarn, pnpm, bun, deno,
 framework build caches), Python, Rust, JVM (Gradle, Maven, Kotlin, Android),
 Go, C/C++ (CMake, ccache, vcpkg, Conan), .NET, PHP, Ruby, Swift/Xcode, Dart,
 Haskell, Scala, Elixir, OCaml, Lean, Julia, R, Zig, and scripting languages.
 Also covered: version managers (nvm, pyenv, rbenv, SDKMAN!, rustup, elan,
-ghcup, opam, swiftly, VS Code Server, Claude Code and Copilot CLI), Playwright, playwright-go, Puppeteer
+ghcup, opam, swiftly, VS Code Server, Claude Code, the Codex daemon and Copilot CLI), Playwright, playwright-go, Puppeteer
 and Cypress browsers, HTTP caches of Chrome, Chromium, Edge, Brave, Opera,
 Opera GX, Vivaldi, Arc, Yandex Browser, Naver Whale, 360, QQ Browser, Firefox,
 LibreWolf, Waterfox, Zen and Floorp, IDE caches (JetBrains, VS Code, Cursor,
@@ -124,7 +126,19 @@ is needed. Agent scratch cleanup requires inactivity and Git safety checks.
   that a process holds open (`/proc/*/fd`, `cwd`, `exe`, or `lsof` on
   macOS) are skipped. So are projects with a running `cargo`, `gradle`,
   `npm`, `node` or similar tool, and anything modified within
-  `--older-than` (1h).
+  `--older-than` (1h). How long ago a project was last used does not
+  matter. A tool running elsewhere does not block a runtime cache it is not
+  using: a script of an installed project keeps no lock on the Bun install
+  cache, while `bun install`, `bunx` or an auto-installing script does.
+  A directory on the `PATH` of a running process is kept too: the process
+  may still start programs from it.
+- **Toolchain versions are kept while anything may need them.** The
+  manager's default and aliases, versions pinned by a project (`.nvmrc`,
+  `rust-toolchain.toml`, ...) and the newest install stay. A partial nvm pin
+  such as `20` keeps only the newest matching 20.x, as nvm resolves it. A
+  version holding globally installed npm packages or pyenv virtual
+  environments is blocked; bundled `npm`/`corepack` and use-m caches
+  (`<name>-v-<version>`) are reinstalled on demand and do not count.
   Container paths are checked individually before each bounded deletion batch.
 - **Rust builds are pruned in two parts.** `cargo-superseded` removes
   older hashes of a unit (`.rlib`, `.rmeta`, `.so`/`.dylib`/`.a`,
@@ -343,7 +357,7 @@ example and `examples/universal-app` for a report viewer.
 | `--audit-dir`, `DSS_AUDIT_DIR`   | `$XDG_STATE_HOME/disk-space-saviour/audit` | Where audit logs go                         |
 | `--backup-dir`, `DSS_BACKUP_DIR` | `…/disk-space-saviour/backups`             | Container log backups before `docker rm`    |
 | `--older-than`                   | `1h`                                       | Activity window; newer files are kept       |
-| `--inactive`                     | `30d`                                      | Project inactivity before `moderate`        |
+| `--inactive`                     | `30d`                                      | Idle time before agent scratch is abandoned |
 | `--min-size`                     | `1M`                                       | Smaller items are not reported              |
 | `--depth`                        | `3`                                        | Docker nesting depth                        |
 | `--journal-keep`                 | `512M`                                     | journald size to keep                       |

package/bin/dss.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 
-import { runCli } from '../src/cli.js';
+// Scans are bound by file system calls, which run on libuv's thread pool
+// (4 threads by default). It is sized on first use, so set it before any
+// module that may touch the file system is loaded.
+process.env.UV_THREADPOOL_SIZE ??= '32';
+const { runCli } = await import('../src/cli.js');
 
 const controller = new AbortController();
 let received = null,

package/package.json

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

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { finished } from 'node:stream/promises';
 
 import { backupDirectory, startAudit, writeAudit } from './audit.js';
+import { PhaseTimer } from './timings.js';
 import { configureContainerHost } from './docker/writable.js';
 import { DockerCli, assertAllowed, parseDockerSize } from './docker/cli.js';
 import {
@@ -44,7 +45,6 @@ import { OTHER_RULES } from './rules/other.js';
 import { compareVersions, VERSION_RULES } from './rules/versions.js';
 import { scanVersions } from './scanners/versions.js';
 import { analyzeRustProfile } from './scanners/rust.js';
-import { currentProjectTier } from './scanners/projects.js';
 import {
   filterItems,
   revalidateReport,
@@ -163,6 +163,7 @@ export class Cleaner {
     this.options = options;
     this.contexts = new Map();
     this.health = new HealthWatch(options.priorHealth);
+    this.timings = options.timings ?? new PhaseTimer();
     this.descriptors = new Map(
       (report.environments ?? []).map((env) => [env.id, env])
     );
@@ -235,7 +236,9 @@ export class Cleaner {
   }
 
   async #processScoped(ctx, item, entry) {
-    const fresh = await this.#recheck(ctx, item);
+    const fresh = await this.timings.measure('recheck', () =>
+      this.#recheck(ctx, item)
+    );
     if (fresh.reason) {
       entry.reason = fresh.reason;
       return;
@@ -248,9 +251,15 @@ export class Cleaner {
       entry.status = 'planned';
       return;
     }
-    await this.health.baseline(ctx.env, item);
-    await this.#execute(ctx, fresh.item, entry);
-    const lost = await this.health.check(ctx.env, item);
+    await this.timings.measure('health', () =>
+      this.health.baseline(ctx.env, item)
+    );
+    await this.timings.measure(`execute:${fresh.item.action?.type}`, () =>
+      this.#execute(ctx, fresh.item, entry)
+    );
+    const lost = await this.timings.measure('health', () =>
+      this.health.check(ctx.env, item)
+    );
     if (lost && !entry.reason) {
       entry.reason = lost;
     }
@@ -372,15 +381,6 @@ export class Cleaner {
   }
 
   async #staticBlocker(ctx, item) {
-    if (item.project && this.options.tier === 'safe') {
-      const tier = await currentProjectTier(
-        { ...ctx, options: this.options, now: this.options.now() },
-        item
-      );
-      if (tierRank(tier) > tierRank(this.options.tier)) {
-        return `project recently active; requires the ${tier} tier`;
-      }
-    }
     if (item.recheck?.type === 'version') {
       if (!ctx.cacheRootsConfigured) {
         await configureCacheRoots(ctx.env, await ctx.env.homeDirs());
@@ -922,8 +922,11 @@ export function cleanOptions(report, input) {
  * @returns {Promise<object>} audit log
  */
 export async function clean(report, input = {}) {
-  report = await revalidateReport(report, input);
-  const options = cleanOptions(report, input);
+  const timings = new PhaseTimer();
+  report = await timings.measure('revalidate', () =>
+    revalidateReport(report, input)
+  );
+  const options = { ...cleanOptions(report, input), timings };
   const audit = startAudit(input.command ?? 'clean', {
     dryRun: Boolean(options.dryRun),
     tier: options.tier,
@@ -935,7 +938,9 @@ export async function clean(report, input = {}) {
       audit.entries.push(entry);
     }
     if (options.audit !== false) {
-      await writeAudit(audit, { ...options, inProgress: true });
+      await timings.measure('audit-write', () =>
+        writeAudit(audit, { ...options, inProgress: true })
+      );
     }
   };
   const cleaner = new Cleaner(report, {
@@ -944,6 +949,7 @@ export async function clean(report, input = {}) {
     onProgress: persistProgress,
   });
   audit.health = cleaner.health.records;
+  audit.timings = timings;
   if (options.audit !== false) {
     await writeAudit(audit, { ...options, inProgress: true });
   }
@@ -961,7 +967,9 @@ export async function clean(report, input = {}) {
       }
       options.onEntry?.(entry, item);
       if (options.audit !== false) {
-        await writeAudit(audit, { ...options, inProgress: true });
+        await timings.measure('audit-write', () =>
+          writeAudit(audit, { ...options, inProgress: true })
+        );
       }
     }
   } catch (error) {

package/src/cli.js

@@ -45,7 +45,7 @@ Scope:
   --scanner NAME             projects, global, versions, agents, system
   --min-size SIZE            ignore smaller items (default 1M)
   --older-than AGE           activity window, newer files are kept (1h)
-  --inactive AGE             project inactivity for moderate tier (30d)
+  --inactive AGE             idle time before agent scratch counts as abandoned (30d)
   --journal-keep SIZE        journald size to keep (512M)
 
 Goals (emergency):

package/src/docker/scan.js

@@ -634,6 +634,7 @@ class DockerScan {
       scanStatus: env.scanStatus,
       hint: env.probeHint ?? null,
       layerSource: env.writableLayer?.source ?? null,
+      timings: env.timings?.toJSON() ?? [],
     });
     if (await env.which('docker')) {
       try {

package/src/emergency.js

@@ -18,6 +18,7 @@ import { LocalEnv } from './env/local.js';
 import { TIERS, selectByTier, tierRank } from './items.js';
 import { resolveGoal, resolveOptions } from './options.js';
 import { revalidateReport, scan } from './scan.js';
+import { PhaseTimer } from './timings.js';
 
 /**
  * Used percentage the way `df` prints it: used / (used + available).
@@ -86,6 +87,8 @@ export async function emergency(input = {}) {
     path: target,
     diskBefore,
     bytesNeeded: bytesNeeded(goal, diskBefore),
+    // Shared by every cleanup pass of a streamed scan.
+    timings: new PhaseTimer(),
   });
   const report = input.report
     ? await revalidateReport(input.report, { ...input, env })
@@ -150,6 +153,7 @@ async function escalate({ report, options, env, target, goal, audit }) {
     env,
     onProgress: persistProgress,
     priorHealth: audit.health,
+    timings: audit.timings,
   });
   audit.health = cleaner.health.records;
   const done = new Set(audit.entries.map((entry) => entry.id));

package/src/env/local.js

@@ -48,6 +48,40 @@ export function parseLsofCwds(output) {
   return cwds;
 }
 
+/**
+ * Absolute directories of a `PATH` value.
+ * @param {string} value
+ * @returns {string[]}
+ */
+export function searchPathDirs(value) {
+  return (value ?? '').split(':').filter((dir) => dir.startsWith('/'));
+}
+
+/**
+ * `PATH` directories by pid from `ps -E -ww -axo pid=,command=` output,
+ * which appends the environment of the user's own processes to their
+ * arguments. A value ends at the first space, so a directory whose name
+ * contains one is not tracked.
+ * @param {string} output
+ * @returns {Map<number, string[]>}
+ */
+export function parsePsSearchPaths(output) {
+  const paths = new Map();
+  for (const line of output.split('\n')) {
+    const match = /^\s*(\d+)\s/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const dirs = [...line.matchAll(/(?:^|\s)PATH=(\S*)/g)].flatMap((found) =>
+      searchPathDirs(found[1])
+    );
+    if (dirs.length > 0) {
+      paths.set(Number(match[1]), [...new Set(dirs)]);
+    }
+  }
+  return paths;
+}
+
 /**
  * Environment adapter for the machine running dss, backed by node:fs.
  *
@@ -609,35 +643,6 @@ export class LocalEnv {
     ).filter(Boolean);
   }
 
-  /** Source activity excludes generated trees, and stops as soon as recent work is seen. */
-  async projectActivity(project, globs, since) {
-    let newest = 0;
-    let frontier = [project];
-    const device = await this.deviceId(project);
-    while (frontier.length && newest < since) {
-      const children = await mapLimit(frontier, 8, async (dir) => {
-        checkSignal(this.signal);
-        const next = [];
-        for (const entry of await this.list(dir)) {
-          if (entry.type === 'dir') {
-            if (
-              !this.skipDiscoveryDirectory(dir, entry.name) &&
-              !globs.some((glob) => matchesGlob(entry.name, glob)) &&
-              entry.device === device
-            ) {
-              next.push(entry.path);
-            }
-          } else if (entry.type === 'file') {
-            newest = Math.max(newest, entry.mtimeMs);
-          }
-        }
-        return next;
-      });
-      frontier = children.flat();
-    }
-    return newest;
-  }
-
   async usageMany(targets, options) {
     const usages = await this.rawUsageMany(targets, options);
     return this.writableLayer
@@ -789,6 +794,15 @@ export class LocalEnv {
             ).stdout
           )
         : new Map();
+    // A process may start programs from its PATH at any time without holding
+    // them open (for example a release directory of an updated tool).
+    const searchPaths =
+      this.platform === 'darwin'
+        ? parsePsSearchPaths(
+            (await this.run(['ps', '-E', '-ww', '-axo', 'pid=,command=']))
+              .stdout
+          )
+        : new Map();
     return result.stdout
       .split('\n')
       .map((line) => /^\s*(\d+)\s+(.+)$/.exec(line))
@@ -798,6 +812,7 @@ export class LocalEnv {
         name: path.basename(m[2].trim()),
         cwd: cwds.get(Number(m[1])) ?? null,
         command: commands.get(Number(m[1])) ?? '',
+        searchPath: searchPaths.get(Number(m[1])) ?? [],
       }))
       .filter((proc) => !selfPids.has(proc.pid));
   }
@@ -831,6 +846,9 @@ export class LocalEnv {
       const cmdline = await io
         .readFile(`${base}/cmdline`, 'utf8')
         .catch(() => '');
+      const environ = await io
+        .readFile(`${base}/environ`, 'utf8')
+        .catch(() => '');
       processes.push({
         pid: Number(pid),
         ...(await procIdentity(base, io)),
@@ -841,6 +859,12 @@ export class LocalEnv {
         aliases: processAliases(exe, cmdline.split('\0')[0]),
         command: cmdline.replaceAll('\0', ' '),
         argv: cmdline.split('\0').filter(Boolean),
+        searchPath: searchPathDirs(
+          environ
+            .split('\0')
+            .find((entry) => entry.startsWith('PATH='))
+            ?.slice('PATH='.length)
+        ),
       });
     }
     return processes;

package/src/env/shell.js

@@ -417,37 +417,6 @@ export class ShellEnv {
     ]);
   }
 
-  async projectActivity(project, globs) {
-    const prune = [
-      '-type',
-      'd',
-      '(',
-      ...findNameExpression([...new Set([...this.skipNames, ...globs])]),
-      ')',
-      '-prune',
-      '-o',
-    ];
-    const argv = [
-      'find',
-      project,
-      '-xdev',
-      ...this.#prunePaths(),
-      ...prune,
-      '-type',
-      'f',
-      '-exec',
-      'stat',
-      '-c',
-      '%Y',
-      '{}',
-      '+',
-    ];
-    const result = await this.sh(
-      `${argv.map(shellQuote).join(' ')} | awk 'BEGIN{m=0} {if ($1>m) m=$1} END{print m}'`
-    );
-    return Number(result.stdout.trim()) * 1000 || 0;
-  }
-
   /**
    * Runs one `find` that prints entries of `type` matching `globs` (without
    * descending into matched directories) and prunes `skipNames`.

package/src/git.js

@@ -36,36 +36,77 @@ const SAFE_GIT_ENV = {
   GIT_TERMINAL_PROMPT: '0',
 };
 
-/** A metadata-only Git directory, with no repository-supplied config or hooks. */
-async function safeGitDirectory(root, callback) {
-  const source = path.join(root, '.git');
-  const stat = await fsp.lstat(source);
-  if (!stat.isDirectory()) {
-    throw new Error('cannot safely inspect a linked Git worktree');
+/**
+ * The checkout's own Git directory (HEAD, index) and the common directory
+ * holding refs and objects. Both are `<root>/.git` in a plain repository;
+ * 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) {
+  const dotGit = path.join(root, '.git');
+  const stat = await fsp.lstat(dotGit);
+  let gitDir = dotGit;
+  if (stat.isFile()) {
+    const named = /^gitdir: (.+)$/m.exec(await fsp.readFile(dotGit, 'utf8'));
+    if (!named) {
+      throw new Error(`${dotGit} does not name a Git directory`);
+    }
+    gitDir = path.resolve(root, named[1].trim());
+  } else if (!stat.isDirectory()) {
+    throw new Error(`${dotGit} is neither a directory nor a gitdir file`);
+  }
+  const commonDir = await fsp
+    .readFile(path.join(gitDir, 'commondir'), 'utf8')
+    .then(
+      (text) => path.resolve(gitDir, text.trim()),
+      (error) => {
+        if (error.code === 'ENOENT') {
+          return gitDir;
+        }
+        throw error;
+      }
+    );
+  if (!(await fsp.stat(path.join(commonDir, 'objects'))).isDirectory()) {
+    throw new Error(`${commonDir} has no object database`);
+  }
+  return { gitDir, commonDir };
+}
+
+async function copyGitMetadata(source, dir, names, force) {
+  for (const name of names) {
+    await fsp
+      .cp(path.join(source, name), path.join(dir, name), {
+        recursive: true,
+        force,
+        errorOnExist: !force,
+      })
+      .catch((error) => {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      });
   }
+}
+
+/**
+ * A metadata-only Git directory, with no repository-supplied config or hooks.
+ * With `indexOnly`, refs and reflogs are left out: enough for `ls-files`,
+ * which reads only HEAD, the index and the work tree.
+ */
+async function safeGitDirectory(root, callback, { indexOnly = false } = {}) {
+  const { gitDir, commonDir } = await gitDirectories(root);
   const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'dss-safe-git-'));
   try {
-    for (const name of [
-      'HEAD',
-      'index',
-      'packed-refs',
-      'shallow',
-      'refs',
-      'logs',
-    ]) {
-      await fsp
-        .cp(path.join(source, name), path.join(dir, name), {
-          recursive: true,
-          force: false,
-          errorOnExist: true,
-        })
-        .catch((error) => {
-          if (error.code !== 'ENOENT') {
-            throw error;
-          }
-        });
+    if (indexOnly) {
+      await copyGitMetadata(gitDir, dir, ['HEAD', 'index'], false);
+      await fsp.mkdir(path.join(dir, 'refs'));
+    } else {
+      await copyIndexAndRefs(gitDir, commonDir, dir);
     }
-    await fsp.symlink(path.join(source, 'objects'), path.join(dir, 'objects'));
+    await fsp.symlink(
+      path.join(commonDir, 'objects'),
+      path.join(dir, 'objects')
+    );
     await fsp.writeFile(
       path.join(dir, 'config'),
       '[core]\n\trepositoryformatversion = 0\n\tbare = false\n'
@@ -76,6 +117,24 @@ async function safeGitDirectory(root, callback) {
   }
 }
 
+async function copyIndexAndRefs(gitDir, commonDir, dir) {
+  await copyGitMetadata(
+    commonDir,
+    dir,
+    ['packed-refs', 'shallow', 'refs', 'logs'],
+    false
+  );
+  // Per-worktree state overrides the shared refs and reflogs.
+  await copyGitMetadata(
+    gitDir,
+    dir,
+    gitDir === commonDir
+      ? ['HEAD', 'index']
+      : ['HEAD', 'index', 'refs', 'logs'],
+    true
+  );
+}
+
 function countLines(text) {
   return text.split('\n').filter((line) => line.trim() !== '').length;
 }
@@ -310,19 +369,22 @@ export class GitInspector {
     try {
       const result =
         this.env.kind === 'host'
-          ? await safeGitDirectory(root, (safeDir) =>
-              this.#git(
-                root,
-                [
-                  'ls-files',
-                  '--cached',
-                  '--others',
-                  '--exclude-standard',
-                  '--',
-                  relative,
-                ],
-                safeDir
-              )
+          ? await safeGitDirectory(
+              root,
+              (safeDir) =>
+                this.#git(
+                  root,
+                  [
+                    'ls-files',
+                    '--cached',
+                    '--others',
+                    '--exclude-standard',
+                    '--',
+                    relative,
+                  ],
+                  safeDir
+                ),
+              { indexOnly: true }
             )
           : await this.#git(root, [
               'ls-files',

package/src/index.d.ts

@@ -34,7 +34,7 @@ export interface ScanOptions {
   staleAge?: Duration;
   /** Alias of `staleAge`. */
   olderThan?: Duration;
-  /** Inactivity before lockfile-backed node_modules become `safe`, other dependency dirs `moderate` (`30d`). */
+  /** Idle time before agent scratch and similar leftovers count as abandoned (`30d`). Project build and dependency directories do not depend on it. */
   inactive?: Duration;
   /** Items smaller than this are dropped (`1M`). */
   minSize?: Size;