# What is a release cooldown (min-release-age), and should I use one?

Source: https://getaiguard.dev/guides/release-cooldowns · Last updated: 2026-11-14 · AI Guard 1.4.7

A release cooldown is a package-manager setting that refuses to install a version until it has been public for a minimum time, such as one day. It protects against hijacked releases of real packages, which go out like any other release and are usually removed within hours. For most projects a one-day cooldown is worth turning on; npm calls it `min-release-age`, pnpm `minimumReleaseAge`, Yarn `npmMinimalAgeGate` and Bun `minimumReleaseAge`.

## Why a cooldown helps

When an attacker takes over a maintainer's account, the malicious version is published like any other release, under the real package name. Checks on the name cannot catch it, because the name is genuine. What gives it away is time: such releases are usually found and removed within hours. The compromised axios releases of March 2026 were live for about three hours. A package manager that waits a day before installing a new version skips that window.

## The setting for each package manager

| Package manager | Setting | Unit | Exclusions | Docs |
| --- | --- | --- | --- | --- |
| npm 11.10+ | `min-release-age` in `.npmrc` | days | `min-release-age-exclude` | [npm config](https://docs.npmjs.com/cli/v11/using-npm/config) |
| pnpm 10.16+ | `minimumReleaseAge` in `pnpm-workspace.yaml` | minutes (pnpm 11 default: 1440) | `minimumReleaseAgeExclude` | [pnpm settings](https://pnpm.io/settings/dependency-resolution) |
| Yarn 4.10+ | `npmMinimalAgeGate` in `.yarnrc.yml` | duration, e.g. `1d` | `npmPreapprovedPackages` | [Yarn yarnrc](https://yarnpkg.com/configuration/yarnrc) |
| Bun 1.3+ | `minimumReleaseAge` under `[install]` in `bunfig.toml` | seconds | `minimumReleaseAgeExcludes` | [Bun bunfig](https://bun.com/docs/runtime/bunfig) |

A one-day cooldown in each:

```text
# .npmrc (npm, days)
min-release-age=1

# pnpm-workspace.yaml (pnpm, minutes)
minimumReleaseAge: 1440

# .yarnrc.yml (Yarn)
npmMinimalAgeGate: 1d

# bunfig.toml (Bun, seconds)
[install]
minimumReleaseAge = 86400
```

pnpm's documentation lists 1440 minutes (one day) as the default for `minimumReleaseAge`. Each package manager has an exclusion list for packages that must always install the newest version immediately.

## How often popular packages have a very new release

To pick a sensible window, AI Guard's maintainers measured the age of the latest release of each of the 5,000 most-downloaded npm packages on 12 November 2026:

Share of the top 5,000 npm packages whose latest release was younger than each window (4,998 answered), measured 12 November 2026:

| Latest release younger than | Share of the top 5,000 |
| --- | --- |
| 6 hours | 0.22% |
| **24 hours (default)** | **3.02%** |
| 48 hours | 6.44% |
| 72 hours | 9.20% |
| 7 days | 13.79% |

A one-day window affected 3.02% of them: about 3 in 100 installs of popular packages would wait. A six-hour window would affect 0.22% but leaves less time for a hijacked release to be found. These are one day's numbers, taken on a busy release day.

## Should I use one?

For most projects, yes: one day is short enough that you rarely notice it and long enough to skip the hours when a hijacked release is usually live. The cost is that every new release waits, including a fix you may want quickly; use the exclusion list for those packages. A cooldown also covers installs that no other tool sees, such as a teammate's `npm install`.

## How AI Guard's fresh-release check fits in

AI Guard has a **fresh-release** check for projects that do not use a cooldown:

- `npx ai-guard verify-deps` **warns** when the version being installed was published in the last 24 hours. It never blocks on age alone.
- The agent install hook (`npx ai-guard init-hooks --check-installs`) **asks you** before installing such a version; in Codex, which cannot ask, it denies the install and tells the agent why.
- The MCP tool `ai_guard_check_package` returns `safeToInstall: false` for it.
- `--fresh-hours` (or `AI_GUARD_FRESH_HOURS`) changes the window; `0` turns it off.

When the project's package manager already enforces a cooldown at least as long, the check steps aside, because it would only repeat what the package manager does. Without one, `verify-deps` prints the one line that turns a cooldown on. A cooldown is the better fix.

## Frequently asked questions

### Does a cooldown slow down security fixes?

Yes, by the length of the cooldown. That is the trade-off. Add packages that need fixes immediately to the exclusion list (`min-release-age-exclude`, `minimumReleaseAgeExclude`, `npmPreapprovedPackages` or `minimumReleaseAgeExcludes`).

### Do I need AI Guard if I already use a cooldown?

Not for fresh releases: the fresh-release check steps aside when your cooldown covers it. The other package checks still apply, because a cooldown does not check whether a name exists or imitates a popular package.

## Sources

- [docs/evidence.md: results on real projects](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/docs/evidence.md)
- [docs/cli/verify-deps.md: every check and option](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/docs/cli/verify-deps.md)
- [npm docs: min-release-age](https://docs.npmjs.com/cli/v11/using-npm/config)
- [pnpm docs: minimumReleaseAge](https://pnpm.io/settings/dependency-resolution)
- [Yarn docs: npmMinimalAgeGate](https://yarnpkg.com/configuration/yarnrc)
- [Bun docs: install.minimumReleaseAge](https://bun.com/docs/runtime/bunfig)
