From 88d445efa2a1608369f4a4df4b46665ac4c6abb4 Mon Sep 17 00:00:00 2001
From: asmyshlyaev177 <asmyshlyaev177@gmail.com>
Date: Wed, 26 Aug 2026 20:53:52 +0400
Subject: [PATCH 1/2] fix: lru local cache eviction #71

---
 CHANGELOG.md                 |   7 ++
 README.md                    |  44 ++++---
 package.json                 |   2 +-
 src/caching/local-cache.ts   |  69 +++++++++--
 src/cli-options.ts           |  38 ++++++
 src/cli.ts                   |   2 +-
 src/test/cli-options.test.ts |  22 ++++
 src/test/local-cache.test.ts | 229 +++++++++++++++++++++++++++++++++++
 src/util/fs.ts               |   9 ++
 9 files changed, 396 insertions(+), 26 deletions(-)
 create mode 100644 src/test/local-cache.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f8baa1ddf..bd8b20798 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,13 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+### Added
+
+- Local caches are now limited to the 2 most recently used entries per script,
+  instead of growing without bound. Set `WIREIT_CACHE_MAX_ENTRIES` to change the
+  limit, or to `infinity` for the previous behavior. See
+  [#71](https://github.com/google/wireit/issues/71).
+
 ## [0.14.13] - 2026-06-23
 
 ### Added
diff --git a/README.md b/README.md
index 945ddecbe..4a010051a 100644
--- a/README.md
+++ b/README.md
@@ -346,10 +346,21 @@ Local caching is enabled by default, unless the
 environment variable is detected. To force local caching, set
 `WIREIT_CACHE=local`. To disable local caching, set `WIREIT_CACHE=none`.
 
-> ⚠️ Wireit does not currently limit the size of local caches. To free up this
-> space, use `rm -rf .wireit/*/cache`. Automatic cache size limits will be added
-> in an upcoming release, tracked at
-> [wireit#71](https://github.com/google/wireit/issues/71).
+Each script retains its 2 most recently used cache entries. Whenever a new entry
+is written, any entries beyond that limit are deleted, least recently used
+first. Because an entry is a full copy of the script's `output` files, this caps
+a script's cache at roughly 2× the size of its output.
+
+To change the limit, set `WIREIT_CACHE_MAX_ENTRIES` to a positive integer, or to
+`infinity` to retain every entry:
+
+```sh
+export WIREIT_CACHE_MAX_ENTRIES=10
+```
+
+Note the limit is applied per script, so a package with many cached scripts will
+still use a multiple of this space. To free all of it at once, use
+`rm -rf .wireit/*/cache`.
 
 ### GitHub Actions caching
 
@@ -868,18 +879,19 @@ The following syntaxes can be used in the `wireit.<script>.dependencies` array:
 
 The following environment variables affect the behavior of Wireit:
 
-| Variable                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `WIREIT_CACHE`          | [Caching mode](#caching).<br><br>Defaults to `local` unless `CI` is `true`, in which case defaults to `none`.<br><br>Automatically set to `github` by the [`google/wireit@setup-github-actions-caching/v2`](#github-actions-caching) action.<br><br>Options:<ul><li>[`local`](#local-caching): Cache to local disk.</li><li>[`github`](#github-actions-caching): Cache to GitHub Actions.</li><li>`none`: Disable caching.</li></ul>                                                                                                                                                                                                                                                      |
-| `WIREIT_FAILURES`       | [How to handle script failures](#failures-and-errors).<br><br>Options:<br><ul><li>[`no-new`](#failures-and-errors) (default): Allow running scripts to finish, but don't start new ones.</li><li>[`continue`](#continue): Allow running scripts to continue, and start new ones unless any of their dependencies failed.</li><li>[`kill`](#kill): Immediately kill running scripts, and don't start new ones.</li></ul>                                                                                                                                                                                                                                                                   |
-| `WIREIT_LOGGER`         | How to present progress and results on the command line.<br><br>Options:<br><ul><li>`quiet` (default for normal execution): Writes a single dynamically updating line summarizing progress. Only passes along stdout and stderr from commands if there's a failure, or if the command is a service.</li><li>`quiet-ci` (default when `env.CI` or `!stdout.isTTY`): like `quiet` but optimized for non-interactive environments, like GitHub Actions runners.</li><li>`simple`: A verbose logger that presents clear information about the work that Wireit is doing.</li><li>`metrics`: Like `simple`, but also presents a summary table of results once a command is finished.</li></ul> |
-| `WIREIT_DEBUG_LOG_FILE` | Path to a file which will receive detailed event logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `WIREIT_MAX_OPEN_FILES` | Limits the number of file descriptors Wireit will have open concurrently. Prevents resource exhaustion when checking large numbers of cached files. Set to a lower number if you hit file descriptor limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `WIREIT_PARALLEL`       | [Maximum number of scripts to run at one time](#parallelism).<br><br>Defaults to 2×logical CPU cores.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `WIREIT_WATCH`          | Set to `true` to enable [watch mode](#watch-mode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `WIREIT_WATCH_STRATEGY` | How Wireit determines when a file has changed which warrants a new watch iteration.<br><br>Options:<br><ul><li>`event` (default): Register OS file system watcher callbacks (using [chokidar](https://github.com/paulmillr/chokidar)).</li><li>`poll`: Poll the filesystem every `WIREIT_WATCH_POLL_MS` milliseconds. Less responsive and worse performance than `event`, but a good fallback for when `event` does not work well or at all (e.g. filesystems that don't support filesystem events, or performance and memory problems with large file trees).</li></ul>                                                                                                                  |
-| `WIREIT_WATCH_POLL_MS`  | When `WIREIT_WATCH_STRATEGY` is `poll`, how many milliseconds to wait between each filesystem poll. Defaults to `500`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `CI`                    | Affects the default value of `WIREIT_CACHE`.<br><br>Automatically set to `true` by [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) and most other CI (continuous integration) services.<br><br>Must be exactly `true`. If unset or any other value, interpreted as `false`.                                                                                                                                                                                                                                                                                                                                 |
+| Variable                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WIREIT_CACHE`             | [Caching mode](#caching).<br><br>Defaults to `local` unless `CI` is `true`, in which case defaults to `none`.<br><br>Automatically set to `github` by the [`google/wireit@setup-github-actions-caching/v2`](#github-actions-caching) action.<br><br>Options:<ul><li>[`local`](#local-caching): Cache to local disk.</li><li>[`github`](#github-actions-caching): Cache to GitHub Actions.</li><li>`none`: Disable caching.</li></ul>                                                                                                                                                                                                                                                      |
+| `WIREIT_FAILURES`          | [How to handle script failures](#failures-and-errors).<br><br>Options:<br><ul><li>[`no-new`](#failures-and-errors) (default): Allow running scripts to finish, but don't start new ones.</li><li>[`continue`](#continue): Allow running scripts to continue, and start new ones unless any of their dependencies failed.</li><li>[`kill`](#kill): Immediately kill running scripts, and don't start new ones.</li></ul>                                                                                                                                                                                                                                                                   |
+| `WIREIT_LOGGER`            | How to present progress and results on the command line.<br><br>Options:<br><ul><li>`quiet` (default for normal execution): Writes a single dynamically updating line summarizing progress. Only passes along stdout and stderr from commands if there's a failure, or if the command is a service.</li><li>`quiet-ci` (default when `env.CI` or `!stdout.isTTY`): like `quiet` but optimized for non-interactive environments, like GitHub Actions runners.</li><li>`simple`: A verbose logger that presents clear information about the work that Wireit is doing.</li><li>`metrics`: Like `simple`, but also presents a summary table of results once a command is finished.</li></ul> |
+| `WIREIT_CACHE_MAX_ENTRIES` | Maximum number of [local cache](#local-caching) entries to retain per script.<br><br>Defaults to `2`.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `WIREIT_DEBUG_LOG_FILE`    | Path to a file which will receive detailed event logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `WIREIT_MAX_OPEN_FILES`    | Limits the number of file descriptors Wireit will have open concurrently. Prevents resource exhaustion when checking large numbers of cached files. Set to a lower number if you hit file descriptor limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `WIREIT_PARALLEL`          | [Maximum number of scripts to run at one time](#parallelism).<br><br>Defaults to 2×logical CPU cores.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `WIREIT_WATCH`             | Set to `true` to enable [watch mode](#watch-mode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `WIREIT_WATCH_STRATEGY`    | How Wireit determines when a file has changed which warrants a new watch iteration.<br><br>Options:<br><ul><li>`event` (default): Register OS file system watcher callbacks (using [chokidar](https://github.com/paulmillr/chokidar)).</li><li>`poll`: Poll the filesystem every `WIREIT_WATCH_POLL_MS` milliseconds. Less responsive and worse performance than `event`, but a good fallback for when `event` does not work well or at all (e.g. filesystems that don't support filesystem events, or performance and memory problems with large file trees).</li></ul>                                                                                                                  |
+| `WIREIT_WATCH_POLL_MS`     | When `WIREIT_WATCH_STRATEGY` is `poll`, how many milliseconds to wait between each filesystem poll. Defaults to `500`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `CI`                       | Affects the default value of `WIREIT_CACHE`.<br><br>Automatically set to `true` by [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) and most other CI (continuous integration) services.<br><br>Must be exactly `true`. If unset or any other value, interpreted as `false`.                                                                                                                                                                                                                                                                                                                                 |
 
 ### Glob patterns
 
diff --git a/package.json b/package.json
index e5473234b..4c8f20098 100644
--- a/package.json
+++ b/package.json
@@ -170,7 +170,7 @@
       "output": []
     },
     "test:cache-local": {
-      "command": "node --test --test-reporter=dot lib/test/cache-local.test.js",
+      "command": "node --test --test-reporter=dot lib/test/cache-local.test.js lib/test/local-cache.test.js",
       "env": {
         "NODE_OPTIONS": "--enable-source-maps"
       },
diff --git a/src/caching/local-cache.ts b/src/caching/local-cache.ts
index d9c81db64..5dbf7665f 100644
--- a/src/caching/local-cache.ts
+++ b/src/caching/local-cache.ts
@@ -18,9 +18,22 @@ import type {AbsoluteEntry} from '../util/glob.js';
 
 /**
  * Caches script output to each package's
- * ".wireit/<script-name-hex>/cache/<cache-key-sha256-hex>" folder.
+ * ".wireit/<script-name-hex>/cache/<cache-key-sha256-hex>" folder, keeping only
+ * the {@link maxEntries} least recently read or written entries per script.
+ *
+ * Eviction needs no lock of its own. It only touches the calling script's own
+ * cache folder, and StandardScriptExecution#acquireSystemLockIfNeeded already
+ * holds that script's lock, except when "output" is empty, in which case the
+ * entries are empty directories.
  */
 export class LocalCache implements Cache {
+  readonly #maxEntries: number;
+
+  /** @param maxEntries Entries to retain per script, or Infinity for all. */
+  constructor(maxEntries: number) {
+    this.#maxEntries = maxEntries;
+  }
+
   async get(
     script: ScriptReference,
     fingerprint: Fingerprint,
@@ -34,6 +47,15 @@ export class LocalCache implements Cache {
       }
       throw error;
     }
+    // Recency lives in the mtime, so there is no index file to maintain. atime
+    // won't do, because filesystems are commonly mounted noatime or relatime.
+    const now = new Date();
+    try {
+      await fs.utimes(cacheDir, now, now);
+    } catch {
+      // A directory we can't stamp (read-only mount, foreign owner) must still
+      // produce a hit. It just ages as though it had only ever been written.
+    }
     return new LocalCacheHit(cacheDir, script.packageDir);
   }
 
@@ -42,11 +64,6 @@ export class LocalCache implements Cache {
     fingerprint: Fingerprint,
     absoluteFiles: AbsoluteEntry[],
   ): Promise<boolean> {
-    // TODO(aomarks) A script's cache directory currently just grows forever.
-    // We'll have the "clean" command to help with manual cleanup, but we'll
-    // almost certainly want an automated way to limit the size of the cache
-    // directory (e.g. LRU capped to some number of entries).
-    // https://github.com/google/wireit/issues/71
     const absCacheDir = this.#getCacheDir(script, fingerprint);
     // Note fs.mkdir returns the first created directory, or undefined if no
     // directory was created.
@@ -58,13 +75,49 @@ export class LocalCache implements Cache {
       throw new Error(`Did not expect ${absCacheDir} to already exist.`);
     }
     await copyEntries(absoluteFiles, script.packageDir, absCacheDir);
+    await this.#evictLeastRecentlyUsedEntries(script);
     return true;
   }
 
+  /**
+   * Housekeeping, so failures are swallowed: the entry we just wrote is still
+   * valid, the folder is only larger than asked for.
+   */
+  async #evictLeastRecentlyUsedEntries(script: ScriptReference): Promise<void> {
+    if (this.#maxEntries === Infinity) {
+      return;
+    }
+    try {
+      const cacheDir = this.#getScriptCacheDir(script);
+      const entries = await fs.readdir(cacheDir, {withFileTypes: true});
+      if (entries.length <= this.#maxEntries) {
+        return;
+      }
+      // lstat, so a broken symlink in the folder gets evicted rather than
+      // throwing on every future eviction.
+      const byRecency = await Promise.all(
+        entries.map(async (entry) => {
+          const path = pathlib.join(cacheDir, entry.name);
+          return {path, mtimeMs: (await fs.lstat(path)).mtimeMs};
+        }),
+      );
+      byRecency.sort((a, b) => a.mtimeMs - b.mtimeMs);
+      const doomed = byRecency.slice(0, byRecency.length - this.#maxEntries);
+      await Promise.all(
+        doomed.map(({path}) => fs.rm(path, {recursive: true, force: true})),
+      );
+    } catch {
+      // See above.
+    }
+  }
+
+  #getScriptCacheDir(script: ScriptReference): string {
+    return pathlib.join(getScriptDataDir(script), 'cache');
+  }
+
   #getCacheDir(script: ScriptReference, fingerprint: Fingerprint): string {
     return pathlib.join(
-      getScriptDataDir(script),
-      'cache',
+      this.#getScriptCacheDir(script),
       createHash('sha256').update(fingerprint.string).digest('hex'),
     );
   }
diff --git a/src/cli-options.ts b/src/cli-options.ts
index 6673228e8..1fc5b905d 100644
--- a/src/cli-options.ts
+++ b/src/cli-options.ts
@@ -46,6 +46,14 @@ export const packageDir = await (async (): Promise<string | undefined> => {
   }
 })();
 
+/**
+ * Deliberately small, because an entry is a full copy of a script's output, and
+ * scripts with large outputs are what make an unbounded cache painful. Two
+ * still covers what local caching is most useful for: bouncing between the
+ * current state and one other, like a branch you keep switching back to.
+ */
+const DEFAULT_CACHE_MAX_ENTRIES = 2;
+
 export type Agent = 'npm' | 'nodeRun' | 'pnpm' | 'yarnClassic' | 'yarnBerry';
 
 export interface Options {
@@ -54,6 +62,7 @@ export interface Options {
   extraArgs: string[] | undefined;
   numWorkers: number;
   cache: 'local' | 'github' | 'none';
+  cacheMaxEntries: number;
   failureMode: FailureMode;
   agent: Agent;
   logger: Logger;
@@ -161,6 +170,34 @@ export const getOptions = async (): Promise<Result<Options>> => {
     return cacheResult;
   }
 
+  const cacheMaxEntriesResult = ((): Result<number> => {
+    const str = process.env['WIREIT_CACHE_MAX_ENTRIES'] ?? '';
+    if (str === '') {
+      return {ok: true, value: DEFAULT_CACHE_MAX_ENTRIES};
+    }
+    if (str.match(/^infinity$/i)) {
+      return {ok: true, value: Infinity};
+    }
+    const parsedInt = parseInt(str, 10);
+    if (Number.isNaN(parsedInt) || parsedInt <= 0) {
+      return {
+        ok: false,
+        error: {
+          reason: 'invalid-usage',
+          message:
+            `Expected the WIREIT_CACHE_MAX_ENTRIES env variable to be ` +
+            `a positive integer or "infinity", got ${JSON.stringify(str)}`,
+          script,
+          type: 'failure',
+        },
+      };
+    }
+    return {ok: true, value: parsedInt};
+  })();
+  if (!cacheMaxEntriesResult.ok) {
+    return cacheMaxEntriesResult;
+  }
+
   const failureModeResult = ((): Result<FailureMode> => {
     const str = process.env['WIREIT_FAILURES'];
     if (!str) {
@@ -247,6 +284,7 @@ export const getOptions = async (): Promise<Result<Options>> => {
       script,
       numWorkers: numWorkersResult.value,
       cache: cacheResult.value,
+      cacheMaxEntries: cacheMaxEntriesResult.value,
       failureMode: failureModeResult.value,
       agent,
       logger,
diff --git a/src/cli.ts b/src/cli.ts
index d936db70c..5dc87ba3e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -23,7 +23,7 @@ const run = async (options: Options): Promise<Result<void, Failure[]>> => {
     case 'local': {
       // Import dynamically so that we import fewer unnecessary modules.
       const {LocalCache} = await import('./caching/local-cache.js');
-      cache = new LocalCache();
+      cache = new LocalCache(options.cacheMaxEntries);
       break;
     }
     case 'github': {
diff --git a/src/test/cli-options.test.ts b/src/test/cli-options.test.ts
index 2a231fd2c..cfa15665f 100644
--- a/src/test/cli-options.test.ts
+++ b/src/test/cli-options.test.ts
@@ -59,6 +59,7 @@ async function assertOptions(
       extraArgs: [],
       watch: false,
       cache: 'local',
+      cacheMaxEntries: 2,
       numWorkers: 10,
       failureMode: 'no-new',
       logger: 'QuietLogger',
@@ -563,4 +564,25 @@ for (const {agent, runCmd, testCmd, startCmd, needsExtraDashes} of commands) {
       );
     }),
   );
+
+  void test(
+    `${agent} WIREIT_CACHE_MAX_ENTRIES=5`,
+    rigTest(async ({rig}) => {
+      await assertOptions(
+        rig,
+        `${runCmd} main ${extraDashes}`,
+        {
+          agent,
+          script: {
+            packageDir: rig.temp,
+            name: 'main',
+          },
+          cacheMaxEntries: 5,
+        },
+        {
+          WIREIT_CACHE_MAX_ENTRIES: '5',
+        },
+      );
+    }),
+  );
 }
diff --git a/src/test/local-cache.test.ts b/src/test/local-cache.test.ts
new file mode 100644
index 000000000..6847e9994
--- /dev/null
+++ b/src/test/local-cache.test.ts
@@ -0,0 +1,229 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {test} from 'node:test';
+import * as assert from 'node:assert';
+import * as fs from 'fs/promises';
+import * as pathlib from 'path';
+import {createHash} from 'crypto';
+import {LocalCache} from '../caching/local-cache.js';
+import {Fingerprint} from '../fingerprint.js';
+import {getScriptDataDir} from '../util/script-data-dir.js';
+import {FilesystemTestRig} from './util/filesystem-test-rig.js';
+import {rigTest} from './util/rig-test.js';
+
+import type {AbsoluteEntry} from '../util/glob.js';
+import type {FingerprintString} from '../fingerprint.js';
+import type {ScriptReference} from '../config.js';
+
+// Eviction of least recently used cache entries.
+// https://github.com/google/wireit/issues/71
+
+const SCRIPT_NAME = 'a';
+
+async function setup(maxEntries: number): Promise<
+  {
+    rig: FilesystemTestRig;
+    cache: LocalCache;
+    script: ScriptReference;
+
+    /** The script's cache folder, one directory per entry. */
+    cacheDir: string;
+
+    /** Write `<name>` to the "output" file and cache it under `name`. */
+    cacheOutput: (name: string) => Promise<void>;
+
+    /** The names of the entries currently in the script's cache folder. */
+    entryHashes: () => Promise<string[]>;
+
+    /** Set an entry's recency directly, instead of racing the wall clock. */
+    setRecency: (name: string, secondsSinceEpoch: number) => Promise<void>;
+  } & AsyncDisposable
+> {
+  const rig = new FilesystemTestRig();
+  await rig.setup();
+  const script: ScriptReference = {
+    packageDir: rig.resolve('.'),
+    name: SCRIPT_NAME,
+  };
+  const cache = new LocalCache(maxEntries);
+  const cacheDir = pathlib.join(getScriptDataDir(script), 'cache');
+
+  const outputEntry: AbsoluteEntry = {
+    path: rig.resolve('output'),
+    dirent: {
+      isFile: () => true,
+      isDirectory: () => false,
+      isSymbolicLink: () => false,
+    },
+  } as AbsoluteEntry;
+
+  const cacheOutput = async (name: string) => {
+    await rig.write({output: name});
+    assert.equal(
+      await cache.set(script, fingerprint(name), [outputEntry]),
+      true,
+    );
+  };
+
+  const entryHashes = async () => {
+    try {
+      return (await fs.readdir(cacheDir)).sort();
+    } catch (error) {
+      if ((error as {code?: string}).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  };
+
+  const setRecency = async (name: string, secondsSinceEpoch: number) => {
+    const when = new Date(secondsSinceEpoch * 1000);
+    await fs.utimes(pathlib.join(cacheDir, hashOf(name)), when, when);
+  };
+
+  return {
+    rig,
+    cache,
+    script,
+    cacheDir,
+    cacheOutput,
+    entryHashes,
+    setRecency,
+    [Symbol.asyncDispose]: () => rig.cleanup(),
+  };
+}
+
+/** The cache only keys off the string form, so any distinct string works. */
+const fingerprint = (name: string) =>
+  Fingerprint.fromString(name as FingerprintString);
+
+const hashOf = (name: string) =>
+  createHash('sha256').update(name).digest('hex');
+
+void test('retains entries up to the limit without evicting', async () => {
+  await using ctx = await setup(3);
+  for (const name of ['v0', 'v1', 'v2']) {
+    await ctx.cacheOutput(name);
+  }
+  assert.deepEqual(
+    await ctx.entryHashes(),
+    ['v0', 'v1', 'v2'].map(hashOf).sort(),
+  );
+});
+
+void test('evicts down to the limit when it is exceeded', async () => {
+  await using ctx = await setup(2);
+  for (const [index, name] of ['v0', 'v1', 'v2', 'v3'].entries()) {
+    await ctx.cacheOutput(name);
+    await ctx.setRecency(name, 1_000 + index);
+  }
+  assert.deepEqual(await ctx.entryHashes(), ['v2', 'v3'].map(hashOf).sort());
+});
+
+void test('evicts the least recently used entry, not the oldest', async () => {
+  await using ctx = await setup(2);
+  await ctx.cacheOutput('v0');
+  await ctx.setRecency('v0', 1_000);
+  await ctx.cacheOutput('v1');
+  await ctx.setRecency('v1', 1_001);
+
+  // Reading v0 makes it the most recently used, though v1 is the newest.
+  assert.notEqual(
+    await ctx.cache.get(ctx.script, fingerprint('v0')),
+    undefined,
+  );
+
+  await ctx.cacheOutput('v2');
+  assert.deepEqual(await ctx.entryHashes(), ['v0', 'v2'].map(hashOf).sort());
+});
+
+void test('a broken symlink in the cache folder does not wedge eviction', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.rig.symlink(
+    'nowhere',
+    pathlib.join(ctx.cacheDir, 'dangling'),
+    'dir',
+  );
+  await ctx.cacheOutput('v1');
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v1')]);
+});
+
+void test('a stray file in the cache folder is evicted like an entry', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.rig.write(pathlib.join(ctx.cacheDir, '.DS_Store'), '');
+  await ctx.cacheOutput('v1');
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v1')]);
+});
+
+void test('retains every entry when the limit is Infinity', async () => {
+  await using ctx = await setup(Infinity);
+  const names = ['v0', 'v1', 'v2', 'v3', 'v4'];
+  for (const name of names) {
+    await ctx.cacheOutput(name);
+  }
+  assert.deepEqual(await ctx.entryHashes(), names.map(hashOf).sort());
+});
+
+void test('a surviving entry can still be restored after an eviction', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.cacheOutput('v1');
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v1')]);
+
+  await ctx.rig.delete('output');
+  const hit = await ctx.cache.get(ctx.script, fingerprint('v1'));
+  assert.notEqual(hit, undefined);
+  await hit!.apply();
+  assert.equal(await ctx.rig.read('output'), 'v1');
+});
+
+void test('get returns undefined for an evicted entry', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.cacheOutput('v1');
+  assert.equal(await ctx.cache.get(ctx.script, fingerprint('v0')), undefined);
+});
+
+void test(
+  'WIREIT_CACHE_MAX_ENTRIES caps the cache directory end to end',
+  rigTest(
+    async ({rig}) => {
+      const cmdA = await rig.newCommand();
+      await rig.write({
+        'package.json': {
+          scripts: {a: 'wireit'},
+          wireit: {
+            a: {
+              command: cmdA.command,
+              files: ['input'],
+              output: ['output'],
+            },
+          },
+        },
+      });
+
+      for (const version of ['v0', 'v1', 'v2', 'v3', 'v4']) {
+        await rig.write({input: version});
+        const exec = rig.exec('npm run a');
+        const inv = await cmdA.nextInvocation();
+        await rig.write({output: version});
+        inv.exit(0);
+        assert.equal((await exec.exit).code, 0);
+      }
+      assert.equal(cmdA.numInvocations, 5);
+
+      const cacheDir = pathlib.join(
+        getScriptDataDir({packageDir: rig.resolve('.'), name: 'a'}),
+        'cache',
+      );
+      assert.equal((await fs.readdir(cacheDir)).length, 2);
+    },
+    {env: {WIREIT_CACHE_MAX_ENTRIES: '2'}},
+  ),
+);
diff --git a/src/util/fs.ts b/src/util/fs.ts
index 44d3aa3b3..d99287305 100644
--- a/src/util/fs.ts
+++ b/src/util/fs.ts
@@ -146,6 +146,15 @@ export async function stat(path: string): Promise<fsTypes.Stats> {
   }
 }
 
+export async function utimes(
+  path: string,
+  atime: Date,
+  mtime: Date,
+): Promise<void> {
+  using _reservation = await fileBudget.reserve();
+  return await fs.utimes(path, atime, mtime);
+}
+
 export async function access(path: string): Promise<void> {
   const reservation = await fileBudget.reserve();
   try {

From 1e87e2422d714edce420560f34a6bfa4c5b098a3 Mon Sep 17 00:00:00 2001
From: asmyshlyaev177 <asmyshlyaev177@gmail.com>
Date: Sat, 29 Aug 2026 23:23:49 +0400
Subject: [PATCH 2/2] review: trash-based eviction, mark-used on fresh, default
 10

---
 CHANGELOG.md                        |   7 +-
 README.md                           |  16 +--
 src/caching/cache.ts                |  24 +++++
 src/caching/github-actions-cache.ts |  10 ++
 src/caching/local-cache.ts          | 128 ++++++++++++++++++++----
 src/cli-options.ts                  |  10 +-
 src/cli.ts                          |  40 ++++++++
 src/execution/standard.ts           |   7 +-
 src/test/cli-options.test.ts        |   2 +-
 src/test/local-cache.test.ts        | 149 ++++++++++++++++++++++++++++
 src/util/fs.ts                      |   5 +
 src/util/script-data-dir.ts         |   9 +-
 src/watcher.ts                      |   7 ++
 13 files changed, 374 insertions(+), 40 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd8b20798..f2edef018 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,10 +10,11 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-- Local caches are now limited to the 2 most recently used entries per script,
+- Local caches are now limited to the 10 most recently used entries per script,
   instead of growing without bound. Set `WIREIT_CACHE_MAX_ENTRIES` to change the
-  limit, or to `infinity` for the previous behavior. See
-  [#71](https://github.com/google/wireit/issues/71).
+  limit, or to `infinity` for the previous behavior. Evicted entries are moved
+  to `.wireit/trash` and deleted at the end of the run, which is safe to
+  interrupt. See [#71](https://github.com/google/wireit/issues/71).
 
 ## [0.14.13] - 2026-06-23
 
diff --git a/README.md b/README.md
index 4a010051a..19bcf757d 100644
--- a/README.md
+++ b/README.md
@@ -346,21 +346,25 @@ Local caching is enabled by default, unless the
 environment variable is detected. To force local caching, set
 `WIREIT_CACHE=local`. To disable local caching, set `WIREIT_CACHE=none`.
 
-Each script retains its 2 most recently used cache entries. Whenever a new entry
-is written, any entries beyond that limit are deleted, least recently used
+Each script retains its 10 most recently used cache entries. Whenever a new
+entry is written, any entries beyond that limit are evicted, least recently used
 first. Because an entry is a full copy of the script's `output` files, this caps
-a script's cache at roughly 2× the size of its output.
+a script's cache at roughly 10× the size of its output.
 
 To change the limit, set `WIREIT_CACHE_MAX_ENTRIES` to a positive integer, or to
 `infinity` to retain every entry:
 
 ```sh
-export WIREIT_CACHE_MAX_ENTRIES=10
+export WIREIT_CACHE_MAX_ENTRIES=2
 ```
 
+Evicted entries are moved to `.wireit/trash` and deleted at the end of the run,
+so that a script is never held up by a large delete. Interrupting that with
+Ctrl-C is safe — whatever is left is deleted by the next run.
+
 Note the limit is applied per script, so a package with many cached scripts will
 still use a multiple of this space. To free all of it at once, use
-`rm -rf .wireit/*/cache`.
+`rm -rf .wireit/*/cache .wireit/trash`.
 
 ### GitHub Actions caching
 
@@ -884,7 +888,7 @@ The following environment variables affect the behavior of Wireit:
 | `WIREIT_CACHE`             | [Caching mode](#caching).<br><br>Defaults to `local` unless `CI` is `true`, in which case defaults to `none`.<br><br>Automatically set to `github` by the [`google/wireit@setup-github-actions-caching/v2`](#github-actions-caching) action.<br><br>Options:<ul><li>[`local`](#local-caching): Cache to local disk.</li><li>[`github`](#github-actions-caching): Cache to GitHub Actions.</li><li>`none`: Disable caching.</li></ul>                                                                                                                                                                                                                                                      |
 | `WIREIT_FAILURES`          | [How to handle script failures](#failures-and-errors).<br><br>Options:<br><ul><li>[`no-new`](#failures-and-errors) (default): Allow running scripts to finish, but don't start new ones.</li><li>[`continue`](#continue): Allow running scripts to continue, and start new ones unless any of their dependencies failed.</li><li>[`kill`](#kill): Immediately kill running scripts, and don't start new ones.</li></ul>                                                                                                                                                                                                                                                                   |
 | `WIREIT_LOGGER`            | How to present progress and results on the command line.<br><br>Options:<br><ul><li>`quiet` (default for normal execution): Writes a single dynamically updating line summarizing progress. Only passes along stdout and stderr from commands if there's a failure, or if the command is a service.</li><li>`quiet-ci` (default when `env.CI` or `!stdout.isTTY`): like `quiet` but optimized for non-interactive environments, like GitHub Actions runners.</li><li>`simple`: A verbose logger that presents clear information about the work that Wireit is doing.</li><li>`metrics`: Like `simple`, but also presents a summary table of results once a command is finished.</li></ul> |
-| `WIREIT_CACHE_MAX_ENTRIES` | Maximum number of [local cache](#local-caching) entries to retain per script.<br><br>Defaults to `2`.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `WIREIT_CACHE_MAX_ENTRIES` | Maximum number of [local cache](#local-caching) entries to retain per script.<br><br>Defaults to `10`.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `WIREIT_DEBUG_LOG_FILE`    | Path to a file which will receive detailed event logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `WIREIT_MAX_OPEN_FILES`    | Limits the number of file descriptors Wireit will have open concurrently. Prevents resource exhaustion when checking large numbers of cached files. Set to a lower number if you hit file descriptor limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `WIREIT_PARALLEL`          | [Maximum number of scripts to run at one time](#parallelism).<br><br>Defaults to 2×logical CPU cores.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
diff --git a/src/caching/cache.ts b/src/caching/cache.ts
index 1de2d659d..5fcc63bb9 100644
--- a/src/caching/cache.ts
+++ b/src/caching/cache.ts
@@ -45,6 +45,30 @@ export interface Cache {
     fingerprint: Fingerprint,
     absoluteFiles: AbsoluteEntry[],
   ): Promise<boolean>;
+
+  /**
+   * Move the entry to the front of an evicting cache's queue without reading it
+   * (the local cache updates its mtime). Called when a script was fresh, so
+   * nothing was restored; without it, an always-fresh script's entry looks
+   * untouched and is eventually evicted. Does nothing if there is no entry.
+   *
+   * @param script The script whose entry was relied upon.
+   * @param fingerprint The string-encoded fingerprint for the script.
+   */
+  markEntryRecentlyUsed(
+    script: ScriptReference,
+    fingerprint: Fingerprint,
+  ): Promise<void>;
+
+  /**
+   * Delete everything this cache has moved aside, this run or a previous one.
+   * An evicted entry is a full copy of a script's output, so a script waits
+   * only for it to be moved out of the way; the deleting happens here.
+   *
+   * @param signal Aborts the sweep at the next entry boundary. Safe: whatever
+   * is left is picked up by the next run.
+   */
+  sweepTrash(signal?: AbortSignal): Promise<void>;
 }
 
 /**
diff --git a/src/caching/github-actions-cache.ts b/src/caching/github-actions-cache.ts
index 3f6fc630a..5c144c772 100644
--- a/src/caching/github-actions-cache.ts
+++ b/src/caching/github-actions-cache.ts
@@ -271,6 +271,16 @@ export class GitHubActionsCache implements Cache {
     );
   }
 
+  /** The service decides what to evict; recency isn't ours to report. */
+  markEntryRecentlyUsed(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** No entry of this cache lives on local disk. */
+  sweepTrash(): Promise<void> {
+    return Promise.resolve();
+  }
+
   /**
    * @returns True if we reserved, uploaded, and committed the tarball. False if
    * we gave up due to a rate limit error.
diff --git a/src/caching/local-cache.ts b/src/caching/local-cache.ts
index 5dbf7665f..4f8b211cb 100644
--- a/src/caching/local-cache.ts
+++ b/src/caching/local-cache.ts
@@ -6,8 +6,8 @@
 
 import * as fs from '../util/fs.js';
 import * as pathlib from 'path';
-import {createHash} from 'crypto';
-import {getScriptDataDir} from '../util/script-data-dir.js';
+import {createHash, randomBytes} from 'crypto';
+import {getPackageDataDir, getScriptDataDir} from '../util/script-data-dir.js';
 import {copyEntries} from '../util/copy.js';
 import {glob} from '../util/glob.js';
 
@@ -19,16 +19,22 @@ import type {AbsoluteEntry} from '../util/glob.js';
 /**
  * Caches script output to each package's
  * ".wireit/<script-name-hex>/cache/<cache-key-sha256-hex>" folder, keeping only
- * the {@link maxEntries} least recently read or written entries per script.
+ * the {@link maxEntries} most recently read or written entries per script.
+ * Evicted entries move to the package's ".wireit/trash", which
+ * {@link sweepTrash} empties, so a script never waits on a large delete.
  *
- * Eviction needs no lock of its own. It only touches the calling script's own
- * cache folder, and StandardScriptExecution#acquireSystemLockIfNeeded already
- * holds that script's lock, except when "output" is empty, in which case the
- * entries are empty directories.
+ * Eviction needs no lock of its own: it touches only the calling script's cache
+ * folder, and StandardScriptExecution#acquireSystemLockIfNeeded already holds
+ * that script's lock, except for an empty "output", where the entries are empty
+ * directories. Sweeping is deliberately unlocked, so any number of Wireit
+ * processes can empty the same trash at once and a vanished entry is expected.
  */
 export class LocalCache implements Cache {
   readonly #maxEntries: number;
 
+  /** Packages used this run, whose trash {@link sweepTrash} empties. */
+  readonly #packageDirs = new Set<string>();
+
   /** @param maxEntries Entries to retain per script, or Infinity for all. */
   constructor(maxEntries: number) {
     this.#maxEntries = maxEntries;
@@ -47,16 +53,24 @@ export class LocalCache implements Cache {
       }
       throw error;
     }
+    await this.markEntryRecentlyUsed(script, fingerprint);
+    return new LocalCacheHit(cacheDir, script.packageDir);
+  }
+
+  async markEntryRecentlyUsed(
+    script: ScriptReference,
+    fingerprint: Fingerprint,
+  ): Promise<void> {
+    this.#packageDirs.add(script.packageDir);
     // Recency lives in the mtime, so there is no index file to maintain. atime
     // won't do, because filesystems are commonly mounted noatime or relatime.
     const now = new Date();
     try {
-      await fs.utimes(cacheDir, now, now);
+      await fs.utimes(this.#getCacheDir(script, fingerprint), now, now);
     } catch {
-      // A directory we can't stamp (read-only mount, foreign owner) must still
-      // produce a hit. It just ages as though it had only ever been written.
+      // No entry, or one we can't stamp (read-only mount, foreign owner). A hit
+      // is still a hit; the entry just ages as though only ever written.
     }
-    return new LocalCacheHit(cacheDir, script.packageDir);
   }
 
   async set(
@@ -64,6 +78,7 @@ export class LocalCache implements Cache {
     fingerprint: Fingerprint,
     absoluteFiles: AbsoluteEntry[],
   ): Promise<boolean> {
+    this.#packageDirs.add(script.packageDir);
     const absCacheDir = this.#getCacheDir(script, fingerprint);
     // Note fs.mkdir returns the first created directory, or undefined if no
     // directory was created.
@@ -75,15 +90,32 @@ export class LocalCache implements Cache {
       throw new Error(`Did not expect ${absCacheDir} to already exist.`);
     }
     await copyEntries(absoluteFiles, script.packageDir, absCacheDir);
-    await this.#evictLeastRecentlyUsedEntries(script);
+    await this.#evictAllButMostRecentlyUsed(
+      script,
+      pathlib.basename(absCacheDir),
+    );
     return true;
   }
 
+  async sweepTrash(signal?: AbortSignal): Promise<void> {
+    await Promise.all(
+      [...this.#packageDirs].map((packageDir) =>
+        this.#sweepPackageTrash(packageDir, signal),
+      ),
+    );
+  }
+
   /**
-   * Housekeeping, so failures are swallowed: the entry we just wrote is still
+   * Housekeeping, so failures are swallowed: the entry just written is still
    * valid, the folder is only larger than asked for.
+   *
+   * @param justWrittenName Never evicted. mtime resolution is coarse on some
+   * filesystems, so it can tie with an older entry and lose the sort.
    */
-  async #evictLeastRecentlyUsedEntries(script: ScriptReference): Promise<void> {
+  async #evictAllButMostRecentlyUsed(
+    script: ScriptReference,
+    justWrittenName: string,
+  ): Promise<void> {
     if (this.#maxEntries === Infinity) {
       return;
     }
@@ -93,24 +125,78 @@ export class LocalCache implements Cache {
       if (entries.length <= this.#maxEntries) {
         return;
       }
+      const candidates = entries
+        .filter((entry) => entry.name !== justWrittenName)
+        .map((entry) => pathlib.join(cacheDir, entry.name));
       // lstat, so a broken symlink in the folder gets evicted rather than
       // throwing on every future eviction.
       const byRecency = await Promise.all(
-        entries.map(async (entry) => {
-          const path = pathlib.join(cacheDir, entry.name);
-          return {path, mtimeMs: (await fs.lstat(path)).mtimeMs};
-        }),
+        candidates.map(async (path) => ({
+          path,
+          mtimeMs: (await fs.lstat(path)).mtimeMs,
+        })),
       );
       byRecency.sort((a, b) => a.mtimeMs - b.mtimeMs);
-      const doomed = byRecency.slice(0, byRecency.length - this.#maxEntries);
-      await Promise.all(
-        doomed.map(({path}) => fs.rm(path, {recursive: true, force: true})),
+      const doomed = byRecency.slice(0, entries.length - this.#maxEntries);
+      // allSettled, so one entry we can't move (EPERM on Windows, while
+      // something holds it open) doesn't block evicting the rest.
+      await Promise.allSettled(
+        doomed.map(({path}) => this.#moveToTrash(script.packageDir, path)),
       );
     } catch {
       // See above.
     }
   }
 
+  async #moveToTrash(packageDir: string, path: string): Promise<void> {
+    const trashDir = this.#getTrashDir(packageDir);
+    await fs.mkdir(trashDir, {recursive: true});
+    // Random, not the entry's own name: the same entry can be evicted, written
+    // and evicted again before a sweep reaches it. Short, because every file in
+    // the entry is renamed onto this path.
+    const name = randomBytes(8).toString('hex');
+    await fs.rename(path, pathlib.join(trashDir, name));
+  }
+
+  async #sweepPackageTrash(
+    packageDir: string,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const trashDir = this.#getTrashDir(packageDir);
+    let entries;
+    try {
+      entries = await fs.readdir(trashDir, {withFileTypes: true});
+    } catch {
+      // ENOENT: nothing evicted, or another process already swept it away.
+      return;
+    }
+    for (const entry of entries) {
+      if (signal?.aborted) {
+        return;
+      }
+      try {
+        // force, because another process may be sweeping the same folder.
+        await fs.rm(pathlib.join(trashDir, entry.name), {
+          recursive: true,
+          force: true,
+        });
+      } catch {
+        // Undeletable right now (EBUSY on Windows). The next run tries again;
+        // a sweep must never fail a build.
+      }
+    }
+    try {
+      await fs.rmdir(trashDir);
+    } catch {
+      // Not empty: aborted, or another process is still evicting into it.
+    }
+  }
+
+  /** Safe beside the per-script dirs: a hex script name can't spell "trash". */
+  #getTrashDir(packageDir: string): string {
+    return pathlib.join(getPackageDataDir(packageDir), 'trash');
+  }
+
   #getScriptCacheDir(script: ScriptReference): string {
     return pathlib.join(getScriptDataDir(script), 'cache');
   }
diff --git a/src/cli-options.ts b/src/cli-options.ts
index 1fc5b905d..1af746197 100644
--- a/src/cli-options.ts
+++ b/src/cli-options.ts
@@ -47,12 +47,12 @@ export const packageDir = await (async (): Promise<string | undefined> => {
 })();
 
 /**
- * Deliberately small, because an entry is a full copy of a script's output, and
- * scripts with large outputs are what make an unbounded cache painful. Two
- * still covers what local caching is most useful for: bouncing between the
- * current state and one other, like a branch you keep switching back to.
+ * Bounded, because an entry is a full copy of a script's output, and scripts
+ * with large outputs are what make an unbounded cache painful. Ten is enough to
+ * survive a fair amount of churn, like jumping between a few branches, without
+ * the folder growing without limit.
  */
-const DEFAULT_CACHE_MAX_ENTRIES = 2;
+const DEFAULT_CACHE_MAX_ENTRIES = 10;
 
 export type Agent = 'npm' | 'nodeRun' | 'pnpm' | 'yarnClassic' | 'yarnBerry';
 
diff --git a/src/cli.ts b/src/cli.ts
index 5dc87ba3e..5a4e51aab 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -14,9 +14,43 @@ import {Console} from './logging/logger.js';
 import {unreachable} from './util/unreachable.js';
 import {WorkerPool} from './util/worker-pool.js';
 
+import type {Cache} from './caching/cache.js';
+
+/** Below this, a sweep finishes before the user wonders why they're waiting. */
+const SWEEP_NOTICE_MS = 1000;
+
+/**
+ * Delete the entries this run evicted, plus anything an earlier run left.
+ *
+ * The notice goes to the console rather than the logger because the default
+ * logger drops cache advisories, and this one is only ever seen while a prompt
+ * hasn't come back.
+ */
+const sweepTrash = async (
+  cache: Cache | undefined,
+  signal: AbortSignal,
+): Promise<void> => {
+  if (cache === undefined) {
+    return;
+  }
+  const sweep = cache.sweepTrash(signal);
+  const notice = setTimeout(() => {
+    console.warn(
+      '🗑️ Deleting evicted cache entries. ' +
+        'Ctrl-C is safe; anything left is deleted on the next run.',
+    );
+  }, SWEEP_NOTICE_MS);
+  try {
+    await sweep;
+  } finally {
+    clearTimeout(notice);
+  }
+};
+
 const run = async (options: Options): Promise<Result<void, Failure[]>> => {
   using logger = options.logger;
   const workerPool = new WorkerPool(options.numWorkers);
+  const sweepAbort = new AbortController();
 
   let cache;
   switch (options.cache) {
@@ -69,11 +103,14 @@ const run = async (options: Options): Promise<Result<void, Failure[]>> => {
     );
     process.on('SIGINT', () => {
       watcher.abort();
+      sweepAbort.abort();
     });
     process.on('SIGTERM', () => {
       watcher.abort();
+      sweepAbort.abort();
     });
     await watcher.watch();
+    await sweepTrash(cache, sweepAbort.signal);
     return {ok: true, value: undefined};
   } else {
     const analyzer = new Analyzer(options.agent, logger);
@@ -92,9 +129,11 @@ const run = async (options: Options): Promise<Result<void, Failure[]>> => {
     );
     process.on('SIGINT', () => {
       executor.abort();
+      sweepAbort.abort();
     });
     process.on('SIGTERM', () => {
       executor.abort();
+      sweepAbort.abort();
     });
     const {persistentServices, errors} = await executor.execute();
     if (persistentServices.size > 0) {
@@ -106,6 +145,7 @@ const run = async (options: Options): Promise<Result<void, Failure[]>> => {
       }
     }
     logger.printMetrics();
+    await sweepTrash(cache, sweepAbort.signal);
     return errors.length === 0
       ? {ok: true, value: undefined}
       : {ok: false, error: errors};
diff --git a/src/execution/standard.ts b/src/execution/standard.ts
index eabcb87c0..72dd62c8c 100644
--- a/src/execution/standard.ts
+++ b/src/execution/standard.ts
@@ -114,7 +114,7 @@ export class StandardScriptExecution extends BaseExecutionWithCommand<StandardSc
             return {ok: false, error: [manifestFresh.error]};
           }
           if (manifestFresh.value) {
-            return this.#handleFresh(fingerprint);
+            return await this.#handleFresh(fingerprint);
           }
         }
 
@@ -250,12 +250,15 @@ export class StandardScriptExecution extends BaseExecutionWithCommand<StandardSc
   /**
    * Handle the outcome where the script is already fresh.
    */
-  #handleFresh(fingerprint: Fingerprint): ExecutionResult {
+  async #handleFresh(fingerprint: Fingerprint): Promise<ExecutionResult> {
     this._logger.log({
       script: this._config,
       type: 'success',
       reason: 'fresh',
     });
+    // Nothing to restore, but this entry is the one we would have used, so a
+    // usually-fresh script must not have it evicted for looking untouched.
+    await this.#cache?.markEntryRecentlyUsed(this._config, fingerprint);
     return {ok: true, value: fingerprint};
   }
 
diff --git a/src/test/cli-options.test.ts b/src/test/cli-options.test.ts
index cfa15665f..72b5a3027 100644
--- a/src/test/cli-options.test.ts
+++ b/src/test/cli-options.test.ts
@@ -59,7 +59,7 @@ async function assertOptions(
       extraArgs: [],
       watch: false,
       cache: 'local',
-      cacheMaxEntries: 2,
+      cacheMaxEntries: 10,
       numWorkers: 10,
       failureMode: 'no-new',
       logger: 'QuietLogger',
diff --git a/src/test/local-cache.test.ts b/src/test/local-cache.test.ts
index 6847e9994..920a6131b 100644
--- a/src/test/local-cache.test.ts
+++ b/src/test/local-cache.test.ts
@@ -41,6 +41,12 @@ async function setup(maxEntries: number): Promise<
 
     /** Set an entry's recency directly, instead of racing the wall clock. */
     setRecency: (name: string, secondsSinceEpoch: number) => Promise<void>;
+
+    /** The package's trash folder, where evicted entries wait to be swept. */
+    trashDir: string;
+
+    /** The names of the evicted entries waiting to be swept. */
+    trashEntries: () => Promise<string[]>;
   } & AsyncDisposable
 > {
   const rig = new FilesystemTestRig();
@@ -51,6 +57,7 @@ async function setup(maxEntries: number): Promise<
   };
   const cache = new LocalCache(maxEntries);
   const cacheDir = pathlib.join(getScriptDataDir(script), 'cache');
+  const trashDir = rig.resolve(pathlib.join('.wireit', 'trash'));
 
   const outputEntry: AbsoluteEntry = {
     path: rig.resolve('output'),
@@ -85,6 +92,17 @@ async function setup(maxEntries: number): Promise<
     await fs.utimes(pathlib.join(cacheDir, hashOf(name)), when, when);
   };
 
+  const trashEntries = async () => {
+    try {
+      return (await fs.readdir(trashDir)).sort();
+    } catch (error) {
+      if ((error as {code?: string}).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  };
+
   return {
     rig,
     cache,
@@ -93,6 +111,8 @@ async function setup(maxEntries: number): Promise<
     cacheOutput,
     entryHashes,
     setRecency,
+    trashDir,
+    trashEntries,
     [Symbol.asyncDispose]: () => rig.cleanup(),
   };
 }
@@ -183,6 +203,128 @@ void test('a surviving entry can still be restored after an eviction', async ()
   assert.equal(await ctx.rig.read('output'), 'v1');
 });
 
+void test('the entry just written is never the one evicted', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  // A coarse mtime can make an older entry look at least as recent as the one
+  // we just wrote. Ranking by mtime alone would then evict the new entry.
+  await ctx.setRecency('v0', Date.now() / 1000 + 3600);
+  await ctx.cacheOutput('v1');
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v1')]);
+});
+
+void test('marking an entry used keeps it from being evicted', async () => {
+  await using ctx = await setup(2);
+  await ctx.cacheOutput('v0');
+  await ctx.setRecency('v0', 1_000);
+  await ctx.cacheOutput('v1');
+  await ctx.setRecency('v1', 1_001);
+
+  // What a fresh script does: nothing to restore, but this is its entry.
+  await ctx.cache.markEntryRecentlyUsed(ctx.script, fingerprint('v0'));
+
+  await ctx.cacheOutput('v2');
+  assert.deepEqual(await ctx.entryHashes(), ['v0', 'v2'].map(hashOf).sort());
+});
+
+void test('marking an entry that does not exist is a no-op', async () => {
+  await using ctx = await setup(2);
+  await ctx.cache.markEntryRecentlyUsed(
+    ctx.script,
+    fingerprint('nothing-cached'),
+  );
+  assert.deepEqual(await ctx.entryHashes(), []);
+});
+
+void test('an evicted entry waits in the trash until it is swept', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.cacheOutput('v1');
+  const trashed = await ctx.trashEntries();
+  assert.equal(trashed.length, 1);
+  // Renamed to something short and unique, not to anything derived from the
+  // entry: a second eviction of the same fingerprint must not collide.
+  assert.match(trashed[0]!, /^[0-9a-f]{16}$/);
+  // Every file in the entry is renamed onto this path, so a tree that fit
+  // before still fits. This is what keeps the Windows path limit out of it.
+  assert.ok(
+    pathlib.join(ctx.trashDir, trashed[0]!).length <
+      pathlib.join(ctx.cacheDir, hashOf('v0')).length,
+  );
+
+  await ctx.cache.sweepTrash();
+  assert.deepEqual(await ctx.trashEntries(), []);
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v1')]);
+});
+
+void test('an unusable trash path degrades, it does not fail set', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  // Nothing can be moved aside when the trash path is a file. Staying over the
+  // limit is allowed; failing the script that just wrote an entry is not.
+  await ctx.rig.write(pathlib.join('.wireit', 'trash'), '');
+
+  await ctx.cacheOutput('v1');
+  assert.deepEqual(await ctx.entryHashes(), ['v0', 'v1'].map(hashOf).sort());
+
+  await ctx.cache.sweepTrash();
+});
+
+void test('sweeping a cache that has evicted nothing is a no-op', async () => {
+  await using ctx = await setup(2);
+  await ctx.cacheOutput('v0');
+  await ctx.cache.sweepTrash();
+  assert.deepEqual(await ctx.entryHashes(), [hashOf('v0')]);
+});
+
+void test('two caches sweeping the same trash at once is not an error', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.cacheOutput('v1');
+  assert.equal((await ctx.trashEntries()).length, 1);
+
+  // Two Wireit processes in one package: both list the same entries, and the
+  // one that loses the race must tolerate them being gone.
+  const other = new LocalCache(1);
+  await other.markEntryRecentlyUsed(ctx.script, fingerprint('v1'));
+  await Promise.all([ctx.cache.sweepTrash(), other.sweepTrash()]);
+  assert.deepEqual(await ctx.trashEntries(), []);
+});
+
+void test('sweeping a symlinked entry does not delete its target', async () => {
+  await using ctx = await setup(1);
+  await ctx.rig.mkdir('elsewhere');
+  await ctx.rig.write({'elsewhere/keep-me': 'precious'});
+  await ctx.cacheOutput('v0');
+  // A symlink out of the cache folder must be unlinked, never followed.
+  await ctx.rig.symlink(
+    ctx.rig.resolve('elsewhere'),
+    pathlib.join(ctx.cacheDir, 'link'),
+    'dir',
+  );
+
+  await ctx.cacheOutput('v1');
+  // The link and the older entry, so the sweep really does handle a symlink.
+  assert.equal((await ctx.trashEntries()).length, 2);
+
+  await ctx.cache.sweepTrash();
+  assert.deepEqual(await ctx.trashEntries(), []);
+  assert.equal(await ctx.rig.read('elsewhere/keep-me'), 'precious');
+});
+
+void test('an aborted sweep leaves the trash for the next run', async () => {
+  await using ctx = await setup(1);
+  await ctx.cacheOutput('v0');
+  await ctx.cacheOutput('v1');
+  assert.equal((await ctx.trashEntries()).length, 1);
+
+  await ctx.cache.sweepTrash(AbortSignal.abort());
+  assert.equal((await ctx.trashEntries()).length, 1);
+
+  await ctx.cache.sweepTrash();
+  assert.deepEqual(await ctx.trashEntries(), []);
+});
+
 void test('get returns undefined for an evicted entry', async () => {
   await using ctx = await setup(1);
   await ctx.cacheOutput('v0');
@@ -223,6 +365,13 @@ void test(
         'cache',
       );
       assert.equal((await fs.readdir(cacheDir)).length, 2);
+      // The CLI sweeps the trash before it exits.
+      await assert.rejects(
+        fs.readdir(rig.resolve(pathlib.join('.wireit', 'trash'))),
+        {
+          code: 'ENOENT',
+        },
+      );
     },
     {env: {WIREIT_CACHE_MAX_ENTRIES: '2'}},
   ),
diff --git a/src/util/fs.ts b/src/util/fs.ts
index d99287305..a2a79ed94 100644
--- a/src/util/fs.ts
+++ b/src/util/fs.ts
@@ -155,6 +155,11 @@ export async function utimes(
   return await fs.utimes(path, atime, mtime);
 }
 
+export async function rename(oldPath: string, newPath: string): Promise<void> {
+  using _reservation = await fileBudget.reserve();
+  return await fs.rename(oldPath, newPath);
+}
+
 export async function access(path: string): Promise<void> {
   const reservation = await fileBudget.reserve();
   try {
diff --git a/src/util/script-data-dir.ts b/src/util/script-data-dir.ts
index 415ea8321..7165165b0 100644
--- a/src/util/script-data-dir.ts
+++ b/src/util/script-data-dir.ts
@@ -8,13 +8,18 @@ import * as pathlib from 'path';
 
 import type {ScriptReference} from '../config.js';
 
+/**
+ * Get the directory name where Wireit data can be saved for a package.
+ */
+export const getPackageDataDir = (packageDir: string) =>
+  pathlib.join(packageDir, '.wireit');
+
 /**
  * Get the directory name where Wireit data can be saved for a script.
  */
 export const getScriptDataDir = (script: ScriptReference) =>
   pathlib.join(
-    script.packageDir,
-    '.wireit',
+    getPackageDataDir(script.packageDir),
     // Script names can contain any character, so they aren't safe to use
     // directly in a filepath, because certain characters aren't allowed on
     // certain filesystems (e.g. ":" is forbidden on Windows). Hex-encode
diff --git a/src/watcher.ts b/src/watcher.ts
index 79dbb3439..6a4dd4bbc 100644
--- a/src/watcher.ts
+++ b/src/watcher.ts
@@ -100,6 +100,9 @@ export class Watcher {
   readonly #failureMode: FailureMode;
   readonly #agent: Agent;
   #executor?: Executor;
+
+  /** Stops the background trash sweep when watching is aborted. */
+  readonly #sweepAbort = new AbortController();
   #debounceTimeoutId?: NodeJS.Timeout = undefined;
   #previousIterationServices?: ServiceMap = undefined;
   #previousIterationFailures = new Map<ScriptReferenceString, Fingerprint>();
@@ -285,6 +288,9 @@ export class Watcher {
       this.#previousIterationFailures,
     );
     const result = await this.#executor.execute();
+    // Unawaited: the next iteration shouldn't wait on a delete, and whatever
+    // this sweep doesn't finish the next one picks up. Never rejects.
+    void this.#cache?.sweepTrash(this.#sweepAbort.signal);
     this.#previousIterationServices = result.persistentServices;
     if (result.errors.length > 0) {
       for (const error of result.errors) {
@@ -411,6 +417,7 @@ export class Watcher {
   }
 
   abort(): void {
+    this.#sweepAbort.abort();
     if (this.#executor !== undefined) {
       this.#executor.abort();
       this.#executor = undefined;