disk-space-saviour 0.13.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.15.2
+
+### Patch Changes
+
+- 841a999: Fix the remaining CI/CD false positives, false negatives and warnings: tests that cannot run on a runner are reported as skipped with the reason instead of passing vacuously or vanishing from the summary, the Deno leg runs with `-A --parallel`, the pedantic zizmor pass runs online and triggers on every file it reads, jscpd 5 receives the comment-skipping setting it understands, the example app reviews its locked install scripts, and release logs no longer warn about `deno.lock` or print the changeset publish output twice.
+
+## 0.15.1
+
+### Patch Changes
+
+- 2f4744b: Fix CI/CD false positives, false negatives, warnings and errors: release-preflight now proves npm trusted publishing with the OIDC package exchange, releases wait for every check (including the Docker-in-Docker job) and refuse to run after a failed or cancelled job, registry verification tolerates CDN lag, PR guards compare against a verified merge base, audit findings are cleared by upgrading Changesets, jscpd and lint-staged, and non-blocking advisories are reported as a notice. Runner images and workflow tools are pinned, CodeQL scans only shipped code, a missing GitHub release is recovered for a version already on npm, the link checker re-checks transient failures and no longer warns about an empty HTML glob, deno.lock is kept in step with package.json, and skipped tests name the real reason.
+
+## 0.15.0
+
+### Minor Changes
+
+- 1613aa2: Protect running package tools, expand safe application caches, respect scan boundaries and exclusions, and bound container writable-layer inspection with honest unknown-size reporting.
+
+## 0.14.1
+
+### Patch Changes
+
+- Tests: the repository URL check no longer reads the environment under Deno, which runs the suite without env access.
+
+  The repository moved to link-foundation/disk-space-saviour: package metadata and the example app link to the new location, so npm provenance matches the repository that publishes.
+
+## 0.14.0
+
+### Minor Changes
+
+- Make Docker cleanup reports resilient to size-query races and count writable-layer cache bytes separately from immutable image data. Improve process matching, privileged read-only liveness inspection, per-hash npx protection, stopped-container Git inspection and recovery-ref recognition. Add aged isolation-log, sanitized-upload, Claude Code and Copilot CLI cleanup candidates, direct opam download-cache removal, investigation-hold age controls, and complete scan audits with grouped hints and watched processes.
+
+  Release: npm publishes only through trusted publishing. The workflow no longer reads an `NPM_TOKEN` secret, the credential preflight requires the OIDC permission and flags any npm token, and the first-publish guidance points to package-registry-manager instead of a token.
+
 ## 0.13.1
 
 ### Patch Changes

package/README.md

@@ -70,7 +70,9 @@ Run `dss --help` for every option. The most useful ones:
 
 - `--only NAME` limits a run to an ecosystem, rule or kind (`--only rust`,
   `--only npm-cache`, `--only docker-stopped-container`).
-- `--exclude PATH|GLOB` makes paths untouchable.
+- `--exclude PATH|GLOB` prunes matching paths and descendants before reading
+  them. Patterns containing separators match full paths and their ancestors;
+  other patterns also match ancestor basenames.
 - `--scanner NAME` restricts scanning to `projects`, `global`, `versions`,
   `agents` or `system`.
 - `--report FILE` limits cleaning to items in a saved `dss scan --json`
@@ -81,24 +83,28 @@ Run `dss --help` for every option. The most useful ones:
 Tiers are cumulative: `moderate` includes `safe`, and `aggressive` includes
 both.
 
-| Tier         | What it removes                                                                                                                                                                                                                                                                                                         |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `safe`       | Download caches (npm, pnpm, yarn, pip, uv, Cargo registry, Gradle, Go, NuGet, and many more), dangling Docker images and build cache. Includes these caches inside running containers.                                                                                                                                  |
-| `moderate`   | Whole `node_modules`, `target/`, `.venv`, `build/` and similar folders of projects inactive for `--inactive` (30 days); toolchain versions nothing uses; unused tagged images, each one only with `--remove-image REF` or an interactive yes; stopped containers (`--remove-stopped-containers` or an interactive yes). |
-| `aggressive` | For emergencies: everything regenerable, including build outputs of projects in active use. Only `dss emergency` reaches it.                                                                                                                                                                                            |
+| 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.                                                                                                                                                                          |
 
 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), Playwright, playwright-go, Puppeteer
+ghcup, opam, swiftly, VS Code Server, Claude Code 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,
 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.
+reports, core dumps and journald logs. 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
+is needed. Agent scratch cleanup requires inactivity and Git safety checks.
 
 ## Safety
 
@@ -129,13 +135,35 @@ reports, core dumps and journald logs.
   environment stops at once, and the audit log and summary say which
   process was lost. A build that simply finishes during the cleanup also
   stops it: an exit cannot be told apart from a crash.
-- **Git awareness.** A project or container is not touched while it has
-  uncommitted changes, unpushed commits or stashes. The blocker is shown in
-  the report. Stopped containers with Git work require an exact
+- **Git awareness.** Whole projects and containers are protected while they
+  have unsaved changes, unpushed commits or stashes. Ignored dependency and
+  build outputs can be cleaned despite unrelated source changes; tracked or
+  non-ignored files inside an artifact remain protected. Stopped-container scans show
+  Git state before cleanup. Unstaged and untracked files can be recognized
+  as preserved when their bytes and modes all match one cached remote ref,
+  such as `origin/recovery/<branch>`. No remote fetch is performed; missing
+  refs, staged work and unreadable files remain blockers. Detached upstream
+  checkouts are accepted only when their commit is reachable from a remote
+  ref. Nested Docker layer copies and temporary Codex plugin checkouts are
+  excluded from this inspection. Unsaved container work requires an exact
   `--allow-dirty-container ID` override.
 - **Audit log on every run.** Each run, dry runs included, writes
   `dss-<command>-<time>-<pid>.json` with every decision, the bytes freed
-  and left per environment, and disk usage before and after.
+  and left per environment, and disk usage before and after. Scan audits
+  include every candidate and its blockers; blocked candidates do not
+  contribute to reclaimable tier totals.
+
+Long-lived `npm exec`/`npx` servers allow idle npm download and node-gyp
+header caches to be cleaned. Active npx hashes remain protected through
+their child command paths, working directories and open files; other
+hashes are separate candidates subject to the age window. Install commands
+still block relevant caches. Bunx, pnpm dlx and Yarn dlx entries use the same
+path protection, and dss always protects its own installation. Interrupts
+finish the partial audit and report the abort. Unreadable processes retain
+their readable identity; uncertain activity blocks relevant paths and owners
+and produces one environment hint. Old isolation logs and sanitized upload staging
+are moderate-tier candidates. Opam download cleanup removes its cache
+directory directly and does not invoke `opam clean` or migrate the root.
 
 ## Docker
 
@@ -155,7 +183,11 @@ three kinds of Docker data:
   the tier totals match what `clean --tier … --yes` removes.
 - **Running containers** are never stopped, restarted or removed. They are
   scanned and cleaned from the inside through `docker exec`, with the same
-  rules and liveness checks as the host.
+  rules and liveness checks as the host. An unreadable `/proc` probe is
+  retried with a read-only root `docker exec --privileged` inspection. If
+  this is denied or incomplete, cleanup stays blocked and names the
+  unreadable processes. This also applies when dss runs inside a container
+  with access to its Docker daemon.
 - **Stopped containers** are listed with their size, image, command, owner
   session (`HIVE_MIND_PARENT_SESSION_ID` and other session labels or
   environment variables, else a session id in the container name), task
@@ -169,6 +201,34 @@ three kinds of Docker data:
   killed) are never removed by a tier or by `--remove-stopped-containers`,
   in emergency mode too. Name each one with `--remove-container ID|NAME`
   (a full name, or an id prefix of at least 12 characters) to remove it.
+  Alternatively, `--investigation-max-age 7d` lifts holds for containers
+  that ended at least seven days ago; removal still requires consent and
+  Git checks. The default keeps investigation holds indefinitely.
+
+Container cache sizes count changed writable-layer file blocks and mounted
+data. Immutable image data is reported separately as `imageBytes` and is
+excluded from reclaimable totals, including the host scan when dss runs
+inside an identifiable container. Image-only caches stay visible and blocked;
+rebuild the image to remove that data. These estimates exclude directory
+metadata overhead. A small stopped container pinning a large image is shown
+even below `--min-size`; its potential image bytes require a separate image
+removal after the container is removed.
+
+`--no-docker` makes no Docker calls, including for storage accounting and
+saved-report cleanup. An overlay root without authoritative upperdir evidence
+has unknown freeable bytes and contributes zero to reclaimable totals.
+Measurements prefer accessible upperdirs; the diff fallback shares one
+serialized snapshot and cached stats per container/run, checks host and cgroup
+memory headroom, and skips excessive candidate counts. Fresh Git checks before
+stopped-container removal still inspect new work. Verbose mode reports storage
+measurement progress. Host scans prune runtime, nested overlay, read-only and
+unselected mount points; explicitly selected ordinary mount roots are allowed.
+
+Docker discovery uses a size-free container listing and measures each
+container independently. Failed size queries are retried once; objects
+remain visible with `sizeUnknown` when measurement fails. Scans continue
+through other objects and nested daemons, report partial errors, and return
+a nonzero CLI exit status when discovery is incomplete.
 
 `--recursive` follows Docker-in-Docker: a container that runs its own daemon
 is scanned as a new environment, down to `--depth` levels (default 3). The
@@ -283,7 +343,7 @@ Configured in `.prettierrc`:
 npm install
 npm test                  # Node.js, 30s per test
 bun test --timeout 30000  # Bun
-deno test --allow-read    # Deno (read-only tests)
+deno test -A --parallel   # Deno (fixtures need -A)
 npm run check             # lint + format + duplication
 npm run test:dind         # Docker-in-Docker integration (needs --privileged)
 node bin/dss.js scan --verbose
@@ -367,14 +427,14 @@ The release workflow uses [Changesets](https://github.com/changesets/changesets)
 5. **Optional Docker Hub publishing**: When configured, waits for the exact npm version and tags the Docker image with that version
 6. **GitHub releases**: Auto-created with formatted release notes
 
-> **First release of a brand-new package**: OIDC trusted publishing cannot
-> create a package that does not exist yet (the first publish fails with
-> `E404`, because a trusted publisher can only be configured for an existing
-> package). To bootstrap, add a repository secret named `NPM_TOKEN` (a
-> granular/automation token with publish access). The release workflow passes
-> it as `NODE_AUTH_TOKEN` automatically. Once the package exists and OIDC
-> trusted publishing is configured on npmjs.com, the token becomes optional and
-> can be removed.
+> **First release of a brand-new package**: npm publishes only through
+> trusted publishing, and a trusted publisher can only be attached to a package
+> that already exists (the first publish from CI fails with `E404`). Publish the
+> first version once with
+> [package-registry-manager](https://github.com/link-foundation/package-registry-manager):
+> `npx package-registry-manager setup --registry npm --execute`. It signs in
+> through the browser, publishes, attaches this workflow as the trusted
+> publisher and signs out again. No npm token is ever stored.
 
 #### Manual Releases
 
@@ -411,7 +471,7 @@ The GitHub Actions workflow (`.github/workflows/release.yml`) implements a fast-
 
 Every CI job declares an explicit `timeout-minutes` so hung steps fail
 in minutes instead of reaching the GitHub Actions default of six hours.
-Fast checks use 5-10 minute caps, release jobs use 30 minutes, and the
+Fast checks use 5-10 minute caps, release jobs use 50 minutes, and the
 link checker uses 10 minutes for external network variance.
 
 That cap is a backstop, never the deadline: GitHub reports a job it
@@ -485,13 +545,14 @@ variants without script edits.
 
 The link checker workflow (`.github/workflows/links.yml`) validates all links in Markdown and HTML files:
 
-1. **Detection**: Uses [lychee](https://github.com/lycheeverse/lychee-action) to scan all `*.md` and `*.html` files
-2. **Web Archive fallback**: For any broken links found, automatically checks the [Wayback Machine](https://web.archive.org) for archived versions
-3. **Actionable suggestions**: Reports one of three outcomes for each broken link:
+1. **Detection**: Uses [lychee](https://github.com/lycheeverse/lychee-action) to walk the checkout for `.md` and `.html` files (respecting `.gitignore`, including dot directories such as `.changeset`)
+2. **Transient re-check**: Links that failed with a transport error or an HTTP 429/5xx answer are retried with a capped wait before they count as broken; GitHub file links fall back to the contents API. Set `RECHECK_VERBOSE=true` to log every probe
+3. **Web Archive fallback**: For any broken links found, automatically checks the [Wayback Machine](https://web.archive.org) for archived versions
+4. **Actionable suggestions**: Reports one of three outcomes for each broken link:
    - **Archived**: Suggests the Web Archive URL as a replacement
    - **Not archived**: Clearly reports the link is unrecoverable
-4. **Scheduled checks**: Runs weekly to catch links that break over time (even if no files changed)
-5. **Issue creation**: On scheduled runs, creates a GitHub Issue with the full broken links report
+5. **Scheduled checks**: Runs weekly to catch links that break over time (even if no files changed)
+6. **Issue creation**: On scheduled runs, creates a GitHub Issue with the full broken links report
 
 Add regex patterns to `.lycheeignore` to exclude URLs from checks (e.g., local dev URLs, example.com, known rate-limited sites).
 

package/bin/dss.js

@@ -2,4 +2,15 @@
 
 import { runCli } from '../src/cli.js';
 
-process.exitCode = await runCli(process.argv.slice(2));
+const controller = new AbortController();
+const abort = () => controller.abort();
+process.once('SIGINT', abort);
+process.once('SIGTERM', abort);
+try {
+  process.exitCode = await runCli(process.argv.slice(2), {
+    signal: controller.signal,
+  });
+} finally {
+  process.removeListener('SIGINT', abort);
+  process.removeListener('SIGTERM', abort);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk-space-saviour",
-  "version": "0.13.1",
+  "version": "0.15.2",
   "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",
@@ -68,19 +68,19 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/konard/disk-space-saviour.git"
+    "url": "git+https://github.com/link-foundation/disk-space-saviour.git"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
+    "@changesets/cli": "^3.0.3",
     "eslint": "^9.38.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
-    "jscpd": "^4.0.5",
-    "lint-staged": "^16.2.6",
+    "jscpd": "^5.4.0",
+    "lint-staged": "^16.4.0",
     "prettier": "^3.6.2",
     "test-anywhere": "^0.8.48"
   },

package/src/audit.js

@@ -13,6 +13,12 @@ import path from 'node:path';
 
 export const AUDIT_SCHEMA = 1;
 
+export function throwIfAborted(options) {
+  if (options.signal?.aborted) {
+    throw new Error('cleanup aborted');
+  }
+}
+
 function stateDir(vars) {
   const base =
     vars.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');

package/src/clean.js

@@ -18,16 +18,19 @@ import path from 'node:path';
 import { finished } from 'node:stream/promises';
 
 import { backupDirectory, startAudit, writeAudit } from './audit.js';
+import { configureContainerHost } from './docker/writable.js';
 import { DockerCli, assertAllowed, parseDockerSize } from './docker/cli.js';
 import {
   containerGitState,
   containerNamed,
   gitBlockersForRemoval,
   investigationBlocker,
+  investigationExpired,
   runningBindMounts,
 } from './docker/containers.js';
 import { imageNamed } from './docker/images.js';
 import { resolveEnvironment } from './env/resolve.js';
+import { configureScanPolicy } from './env/policy.js';
 import { GitInspector } from './git.js';
 import { HealthWatch } from './health.js';
 import { consentFlag, dropNested, selectByTier, tierRank } from './items.js';
@@ -35,9 +38,15 @@ import { LivenessProbe } from './liveness.js';
 import { resolveOptions } from './options.js';
 import { isWithin } from './paths.js';
 import { OTHER_RULES } from './rules/other.js';
-import { compareVersions } from './rules/versions.js';
+import { compareVersions, VERSION_RULES } from './rules/versions.js';
+import { scanVersions } from './scanners/versions.js';
 import { analyzeRustProfile } from './scanners/rust.js';
-import { filterItems, revalidateReport } from './scan.js';
+import {
+  filterItems,
+  revalidateReport,
+  selfContainerIds,
+  scannedEnvironment,
+} from './scan.js';
 
 const STOPPED = new Set(['exited', 'created', 'dead']);
 const COMMAND_TIMEOUT_MS = 30 * 60 * 1000;
@@ -123,6 +132,23 @@ async function browserRevisionBlocker(env, item) {
   return null;
 }
 
+async function configureStorage(env, options) {
+  await configureScanPolicy(env, options);
+  if (env.kind === 'host' && !env.writableLayer) {
+    await configureContainerHost(
+      env,
+      options.docker === false ? [] : await selfContainerIds(env),
+      options
+    );
+  }
+}
+
+function imageOnly(bytes, usages) {
+  return (
+    bytes === 0 && [...usages.values()].some((usage) => usage.imageBytes > 0)
+  );
+}
+
 export class Cleaner {
   /**
    * @param {object} report output of `scan()`
@@ -229,7 +255,8 @@ export class Cleaner {
     if (type === 'docker-rm') {
       const git = await containerGitState(
         new DockerCli(ctx.executor),
-        item.action.containerId
+        item.action.containerId,
+        { fresh: true }
       );
       const blockers = gitBlockersForRemoval(
         git,
@@ -241,6 +268,17 @@ export class Cleaner {
     if (type === 'none' || item.paths.length === 0) {
       return { item };
     }
+    await configureStorage(ctx.env, this.options);
+    for (const target of item.paths) {
+      const boundary = ctx.env.scanPolicy.removalReason(target);
+      if (boundary) {
+        return { reason: boundary };
+      }
+    }
+    return this.#remeasure(ctx, item, type);
+  }
+
+  async #remeasure(ctx, item, type) {
     let paths = item.paths;
     if (item.recheck?.type === 'rust') {
       const current = await analyzeRustProfile(ctx.env, item.recheck.profile, {
@@ -263,10 +301,22 @@ export class Cleaner {
     const fresh = {
       ...item,
       paths,
-      bytes: type === 'remove' ? sumBytes(usages, paths) : item.bytes,
+      bytes: sumBytes(usages, paths),
       newestMtimeMs: newest || item.newestMtimeMs,
       action: type === 'remove' ? { ...item.action, paths } : item.action,
     };
+    if (imageOnly(fresh.bytes, usages)) {
+      return {
+        reason:
+          'all bytes are in the image layer; rebuild the image to reclaim them',
+      };
+    }
+    if ([...usages.values()].some((usage) => usage.sizeUnknown)) {
+      return {
+        reason:
+          'writable-layer size unknown; inspect container/image storage before cleanup',
+      };
+    }
     const staticBlocker = await this.#staticBlocker(ctx, fresh);
     if (staticBlocker) {
       return { reason: staticBlocker };
@@ -306,6 +356,27 @@ export class Cleaner {
   }
 
   async #staticBlocker(ctx, item) {
+    if (item.recheck?.type === 'version') {
+      const rule = VERSION_RULES.find(
+        (candidate) => candidate.id === item.rule
+      );
+      const candidates = await scanVersions(
+        {
+          ...ctx,
+          options: {
+            ...this.options,
+            homes: [item.recheck.home],
+            roots: this.report.options.roots ?? [],
+          },
+          now: this.options.now(),
+          liveness: null,
+        },
+        { rules: [rule] }
+      );
+      if (!candidates.some((candidate) => candidate.path === item.path)) {
+        return `${item.path} is now current, pinned, or the newest installed version`;
+      }
+    }
     if (
       item.recheck?.type === 'pyenv-envs' &&
       (await ctx.env.list(ctx.env.path.join(item.path, 'envs'))).length > 0
@@ -358,13 +429,20 @@ export class Cleaner {
   }
 
   async #gitBlocker(ctx, item) {
-    if (item.project || item.rule === 'gh-issue-solver-workdirs') {
+    if (
+      item.project ||
+      item.rule === 'gh-issue-solver-workdirs' ||
+      item.recheck?.type === 'scratch'
+    ) {
       ctx.git.invalidate();
       const blockers =
-        item.rule === 'gh-issue-solver-workdirs'
-          ? await ctx.git.treeBlockers(item.path)
+        item.rule === 'gh-issue-solver-workdirs' ||
+        item.recheck?.type === 'scratch'
+          ? await ctx.git.treeBlockers(item.path, {
+              allowNoRepo: item.recheck?.type === 'scratch',
+            })
           : await ctx.git.pathBlockers(item.path, {
-              requireClean: item.tier !== 'safe',
+              requireClean: false,
             });
       if (blockers.length > 0) {
         return blockers.join('; ');
@@ -392,28 +470,28 @@ export class Cleaner {
    */
   async #removePaths(ctx, item, entry) {
     for (const target of item.action.paths) {
-      await ctx.liveness.refresh(true);
-      const stopped = this.health.verify(item, ctx.liveness.processList());
-      if (stopped) {
-        entry.reason = `stopped before ${target}: ${stopped}`;
-        return;
+      if (this.options.signal?.aborted) {
+        throw new Error('cleanup aborted');
       }
-      await ctx.liveness.resolve([target]);
-      const busy = ctx.liveness.busyReason({ ...item, paths: [target] });
-      if (busy) {
-        entry.reason = `stopped before ${target}: busy: ${busy}`;
+      const blocker = await this.#removalBlocker(ctx, item, target);
+      if (blocker) {
+        entry.reason = blocker;
         return;
       }
       const usage = await ctx.env.usage(target);
-      const inUse =
-        item.checks?.perPath &&
-        (ctx.liveness.openInside([target]) ??
-          ctx.liveness.recentWrite(usage?.newestMtimeMs));
+      const inUse = this.#pathActivity(ctx, item, target, usage);
       if (inUse) {
         entry.skippedPaths.push({ path: target, reason: inUse });
         continue;
       }
+      // The usage walk may discover an excluded child that was added since scan.
+      const boundary = ctx.env.scanPolicy.removalReason(target);
+      if (boundary) {
+        entry.reason = boundary;
+        return;
+      }
       await ctx.env.remove([target]);
+      ctx.env.writableLayer?.forget?.(target, ctx.env.path);
       entry.status = 'removed';
       entry.deletedPaths.push(target);
       entry.freedBytes += usage?.bytes ?? 0;
@@ -424,6 +502,30 @@ export class Cleaner {
     }
   }
 
+  #pathActivity(ctx, item, target, usage) {
+    return (
+      item.checks?.perPath &&
+      (ctx.liveness.openInside([target]) ??
+        ctx.liveness.recentWrite(usage?.newestMtimeMs))
+    );
+  }
+
+  async #removalBlocker(ctx, item, target) {
+    await configureScanPolicy(ctx.env, this.options);
+    const boundary = ctx.env.scanPolicy.removalReason(target);
+    if (boundary) {
+      return boundary;
+    }
+    await ctx.liveness.refresh(true);
+    const stopped = this.health.verify(item, ctx.liveness.processList());
+    if (stopped) {
+      return `stopped before ${target}: ${stopped}`;
+    }
+    await ctx.liveness.resolve([target]);
+    const busy = ctx.liveness.busyReason({ ...item, paths: [target] });
+    return busy ? `stopped before ${target}: busy: ${busy}` : null;
+  }
+
   async #command(ctx, item, entry) {
     const { action } = item;
     const isDocker = action.argv[0] === 'docker';
@@ -490,7 +592,7 @@ export class Cleaner {
       entry.reason = kept;
       return;
     }
-    const git = await containerGitState(docker, containerId);
+    const git = await containerGitState(docker, containerId, { fresh: true });
     const blockers = gitBlockersForRemoval(git, containerId, this.options);
     if (blockers.length > 0) {
       entry.reason = blockers.join('; ');
@@ -589,6 +691,7 @@ export function environmentTotals(report, entries) {
 export function wantedItems(report, options) {
   const approved = options.approvedIds ? new Set(options.approvedIds) : null;
   return filterItems(report.items, { ...options, minSizeBytes: 0 }, [], path)
+    .filter((item) => options.docker !== false || !dockerItem(item, report))
     .filter((item) => !approved || approved.has(item.id))
     .map((item) => {
       if (item.action?.type === 'docker-rm') {
@@ -600,6 +703,19 @@ export function wantedItems(report, options) {
     });
 }
 
+function dockerItem(item, report) {
+  return (
+    ['docker', 'container'].includes(item.kind) ||
+    item.action?.argv?.[0] === 'docker' ||
+    (report.environments ?? []).some(
+      (env) =>
+        env.id === item.env &&
+        env.kind === 'container' &&
+        (env.depth > 0 || env.chain?.length > 0)
+    )
+  );
+}
+
 /**
  * Applies per-container consent: `--remove-container` approves the removal
  * of that container and lifts its investigation hold, an exact
@@ -609,11 +725,15 @@ function containerConsent(item, options) {
   const { containerId, name } = item.action;
   const named = containerNamed(options.removeContainers, containerId, name);
   const dirtyAllowed = options.allowDirtyContainers?.includes(containerId);
-  if (!named && !dirtyAllowed) {
+  const expired = investigationExpired(
+    { FinishedAt: item.container?.owner?.finishedAt },
+    options
+  );
+  if (!named && !dirtyAllowed && !expired) {
     return item;
   }
   const lifted = (reason) =>
-    (named && reason === item.container?.investigation) ||
+    ((named || expired) && reason === item.container?.investigation) ||
     (dirtyAllowed &&
       item.container?.gitBlockers?.includes(reason) &&
       /^Git repository .+ has /.test(reason));
@@ -636,6 +756,7 @@ export function planItems(report, options) {
 /** Options that only the cleaning run itself may grant. */
 export const CONFIRMATION_FLAGS = [
   'removeStoppedContainers',
+  'investigationMaxAge',
   'removeContainers',
   'removeImages',
   'includeVolumes',
@@ -680,21 +801,30 @@ export async function clean(report, input = {}) {
   };
   const cleaner = new Cleaner(report, {
     ...options,
+    env: options.env ?? scannedEnvironment(report),
     onProgress: persistProgress,
   });
   audit.health = cleaner.health.records;
   if (options.audit !== false) {
     await writeAudit(audit, { ...options, inProgress: true });
   }
-  for (const item of planItems(report, options)) {
-    const entry = await cleaner.process(item);
-    if (!audit.entries.includes(entry)) {
-      audit.entries.push(entry);
-    }
-    options.onEntry?.(entry, item);
-    if (options.audit !== false) {
-      await writeAudit(audit, { ...options, inProgress: true });
+  try {
+    for (const item of planItems(report, options)) {
+      if (options.signal?.aborted) {
+        throw new Error('cleanup aborted');
+      }
+      const entry = await cleaner.process(item);
+      if (!audit.entries.includes(entry)) {
+        audit.entries.push(entry);
+      }
+      options.onEntry?.(entry, item);
+      if (options.audit !== false) {
+        await writeAudit(audit, { ...options, inProgress: true });
+      }
     }
+  } catch (error) {
+    audit.aborted = true;
+    audit.error = error.message;
   }
   return finishAudit(audit, report, options);
 }
@@ -703,6 +833,10 @@ export async function clean(report, input = {}) {
  * Adds totals and writes the audit log (unless `audit: false`).
  */
 export async function finishAudit(audit, report, options) {
+  if (options.signal?.aborted) {
+    audit.aborted = true;
+    audit.error ??= 'cleanup aborted';
+  }
   audit.finishedAt = new Date().toISOString();
   audit.freedBytes = audit.entries.reduce((sum, e) => sum + e.freedBytes, 0);
   audit.plannedBytes = audit.entries