A dependency cooldown, also called a minimum release age, makes your package manager or update bot skip any version published less than a set time ago, so a hijacked release has time to be found and pulled before you install it. npm (min-release-age), pnpm (minimumReleaseAge), Yarn (npmMinimalAgeGate), Bun (minimumReleaseAge), uv (exclude-newer), pip (--uploaded-prior-to), Renovate (minimumReleaseAge) and Dependabot (cooldown) each have a setting. When an AI coding agent runs npm install or pip install itself, Dependabot and Renovate never see it, so the cooldown also has to sit where the agent installs: in a PreToolUse hook.
Package manager, Renovate and Dependabot facts checked against their own docs and changelogs on 21 Nov 2026. Skylos facts and output are for Skylos 5.7.0.
This page covers why a cooldown works, the setting in each tool with its unit and default, how Renovate and Dependabot differ, the gap an agent opens, a hook that holds the agent's installs with real output, how to keep the window from being lowered, and what a cooldown does not cover.
What is a dependency cooldown?
A dependency cooldown is a wait between the moment a package version is published and the moment you install it. William Woodruff's post "We should all be using dependency cooldowns" defines it as "a window of time between when a dependency is published and when it's considered suitable for use." During that window the version is public, so registries, scanners and maintainers can spot a bad release before you pull it.
It works when the bad release is found inside the window, and many are found within hours. PyPI's administrator posted the registry's audit log for the Ultralytics compromise on 6 Dec 2024 (times in UTC):
| Release | Created | Removed | Live for |
|---|---|---|---|
| ultralytics 8.3.41 | 2024-12-04 20:51 | 2024-12-05 09:15 | about 12 hours |
| ultralytics 8.3.42 | 2024-12-05 12:47 | 2024-12-05 13:47 | about 1 hour |
Woodruff's post (21 Nov 2025) lists approximate windows for ten attacks:
| Attack | Approx. window of opportunity |
|---|---|
| xz-utils | about 5 weeks |
| Ultralytics (phase 1) | 12 hours |
| Ultralytics (phase 2) | 1 hour |
| tj-actions | 3 days |
| chalk | under 12 hours |
| Nx | 4 hours |
| rspack | 1 hour |
| num2words | under 12 hours |
| Kong Ingress Controller | about 10 days |
| web3.js | 5 hours |
His summary: "8/10 attacks had windows of opportunity of less than a week." By our count of the same table, seven of the ten were live for 12 hours or less, and three (tj-actions, Kong, xz-utils) outlasted a 48-hour wait. A cooldown buys time for someone else to notice. It does not inspect the code.
What is the minimum release age setting in each package manager?
| Tool | Setting | Unit | Default on 21 Nov 2026 | Since | Where |
|---|---|---|---|---|---|
| npm | min-release-age | days | off (null) in npm 12.2.3 | npm 11.10.0, 11 Feb 2026 | .npmrc or --min-release-age |
| pnpm | minimumReleaseAge | minutes | one day, non-strict | added 10.16.0 (12 Sep 2025), default since 11.0.0 (28 Apr 2026) | pnpm-workspace.yaml |
| Yarn | npmMinimalAgeGate | duration such as 3d or 1w | 1d | added 4.10.0 (18 Sep 2025), default since 4.15.0 (19 May 2026) | .yarnrc.yml |
| Bun | install.minimumReleaseAge | seconds | off (null) | Bun 1.3, 10 Oct 2025 | bunfig.toml |
| uv | exclude-newer | timestamp, or a duration such as 2 days or P2D | none | durations since uv 0.9.17, 9 Dec 2025 | [tool.uv] in pyproject.toml, uv.toml or --exclude-newer |
| pip | --uploaded-prior-to | ISO 8601 datetime, or days as P2D | none | pip 26.0 (30 Jan 2026), days since 26.1 (26 Apr 2026) | command line or PIP_UPLOADED_PRIOR_TO |
| Renovate | minimumReleaseAge | duration such as 3 days | null | checked on Renovate 44.257.6 | renovate.json |
| Dependabot | cooldown | days | 3 days, version updates | GA 1 Jul 2025, default since 14 Jul 2026 | .github/dependabot.yml |
Minutes, seconds, days and duration strings, for one idea. Set the one for every tool your repository uses, and commit it.
Does npm have a minimum release age?
Yes, since npm 11.10.0 (11 Feb 2026). npm's config reference for 12.2.3: "If set, npm will build the npm tree such that only versions that were available more than the given number of days ago will be installed. If there are no versions available for the current set of dependencies, the command will error."
# .npmrc
min-release-age=2
On 21 Nov 2026 the npm latest tag of openai was 7.62.0, published 2026-11-20T01:43:43Z. With npm 11.20.0 in an empty project:
$ npm install openai --min-release-age=2 --dry-run
add openai 7.60.0
$ npm install openai --dry-run
add openai 7.62.0
min-release-age-exclude takes package names or globs that skip the filter. One line in the same reference matters for agents: "Across sources, the standard precedence applies (cli > env > project > user > global), so a higher-priority source can always relax or override a lower-priority one." A flag on the command beats your committed .npmrc.
How do you set minimumReleaseAge in pnpm, Yarn and Bun?
pnpm reads it from pnpm-workspace.yaml, in minutes:
# pnpm-workspace.yaml
minimumReleaseAge: 2880 # minutes, so two days (pnpm 10.16.0 and later)
minimumReleaseAgeExclude:
- "@myorg/*"
Since pnpm 11.0.0 (28 Apr 2026) the default is one day (1440 minutes). pnpm's docs add a catch: "The built-in default of minimumReleaseAge (1440 minutes) is non-strict for backward compatibility." Non-strict means that when no version in the requested range is old enough, pnpm "falls back to a version that doesn't meet the minimumReleaseAge constraint so installation can still succeed." An exact pin on a release from this morning installs. Set the value yourself and minimumReleaseAgeStrict becomes true.
Yarn (4.10.0 and later) reads npmMinimalAgeGate from .yarnrc.yml. The schema behind Yarn's docs gives the default as 1d, which became the default in 4.15.0 (19 May 2026), and its examples are 30m, 3h, 1d and 1w:
# .yarnrc.yml
npmMinimalAgeGate: "3d"
npmPreapprovedPackages:
- "@myorg/*"
Bun counts seconds, and the default is off. Bun 1.3 added it (10 Oct 2025), and the bunfig reference documents an exclude list next to it:
# bunfig.toml
[install]
minimumReleaseAge = 259200 # 3 days in seconds, Bun 1.3.0 and later
minimumReleaseAgeExcludes = ["@types/bun"]
How do you set a dependency cooldown in uv and pip?
uv uses exclude-newer. Since uv 0.9.17 (9 Dec 2025) it takes a relative duration, which uv's changelog calls "a.k.a., dependency cooldowns". From uv's settings reference: it "Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), a 'friendly' duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration". It compares each file's upload time, not the release date.
# pyproject.toml
[tool.uv]
exclude-newer = "2 days"
exclude-newer-package = { my-internal-lib = false }
pip has --uploaded-prior-to since pip 26.0 (30 Jan 2026), and since 26.1 (26 Apr 2026) it accepts days as P<n>D. pip's reference adds: "Only effective when using indexes that provide upload-time metadata." On 21 Nov 2026 PyPI's newest openai was 3.57.0, uploaded 2026-11-20T01:28:43Z. With pip 26.2.2 in a fresh virtual environment:
$ pip install --dry-run --no-deps --uploaded-prior-to P2D openai
Would install openai-3.55.1
$ PIP_UPLOADED_PRIOR_TO=P2D pip install --dry-run --no-deps openai
Would install openai-3.55.1
$ pip install --dry-run --no-deps openai
Would install openai-3.57.0
(Collecting and Downloading lines trimmed.) pip does not read this from pyproject.toml, so a plain pip install in your repository waits for nothing unless the command line, the environment or pip's own config sets it.
How do Renovate minimumReleaseAge and the Dependabot cooldown work?
Both delay the pull requests a bot opens. Neither changes what npm install does on a laptop.
Dependabot. On 14 Jul 2026 GitHub made a cooldown the default: "Dependabot now waits until a new release has been available on its registry for at least three days" before opening a version update. "Security updates still open immediately, so critical fixes are never delayed." It covers every ecosystem on github.com and arrives in GitHub Enterprise Server 3.23. To set a longer wait:
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
semver-major-days: 14
exclude:
- "@myorg/*"
The semver-*-days keys apply where GitHub supports SemVer for the ecosystem (npm and Yarn, pip, uv, Bun, Cargo, Maven and others per the options reference). include and exclude take up to 150 names each.
Skylos reports Dependabot entries that wait less than seven days as SKY-D361 (LOW). Real output from skylos . --danger --format json on a dependabot.yml with an npm entry and no cooldown (a pip entry with default-days: 7 was not reported), message trimmed by one middle sentence:
{
"rule_id": "SKY-D361",
"severity": "LOW",
"message": "Dependabot proposes version updates soon after a release for npm in / after 3 day(s) (no cooldown is set, so Dependabot's 3-day default applies). ... Set cooldown.default-days to 7 or more; security updates are not delayed.",
"file": ".../.github/dependabot.yml",
"line": 3
}
Renovate. minimumReleaseAge defaults to null. Renovate's docs: "When the time passed since the release is less than the set minimumReleaseAge: Renovate adds a 'pending' status check to that update's branch." The config:best-practices preset includes security:minimumReleaseAgeNpm, which sets 3 days for npm. The docs' own example:
{
"packageRules": [
{
"matchDatasources": ["npm"],
"minimumReleaseAge": "3 days"
}
]
}
Renovate's preset source notes that lock file maintenance "does not support validating Minimum Release Age, as the package manager performs the required changes". There, the package manager's own setting is what holds.
Why doesn't a Dependabot cooldown cover AI coding agents?
Because the agent is not Dependabot. Claude Code, Codex and Cursor run pip install, npm install, npx -y and uvx in your terminal, in the middle of a task, and the version they get is whatever the registry serves that minute. No bot opens a pull request, so no bot cooldown applies.
The package manager's own setting does apply when the agent runs that tool in a project where you set it. Three things still get through:
- Unset defaults. npm, Bun, uv and pip wait for nothing until configured. pnpm's built-in one day is non-strict, so an exact pin on a fresh release installs.
- One setting per tool. A repository with a Python backend and a TypeScript frontend needs
.npmrc,pnpm-workspace.yaml,.yarnrc.ymlorbunfig.toml, plus uv settings or a pip flag. An agent may usepipin one command anduvxin the next. - Overrides. npm's precedence puts the command line above your project file. An agent that hits the cooldown error can rerun the install with
--min-release-age=0.
The override, run with npm 11.20.0 and pip 26.2.2 at 09:55 UTC on 21 Nov 2026, with the cooldown committed in .npmrc and set in the environment for pip:
$ cat .npmrc
min-release-age=2
$ npm install openai --dry-run
add openai 7.60.0
$ npm install openai --min-release-age=0 --dry-run
add openai 7.62.0
$ PIP_UPLOADED_PRIOR_TO=P2D pip install --dry-run --no-deps --uploaded-prior-to P0D openai
Would install openai-3.57.0
So the cooldown for AI coding agents goes where the agent's command passes before it runs. In Claude Code, Codex and Cursor that is a PreToolUse (or beforeShellExecution) hook. Claude Code's hooks reference: with a deny, "Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason."
How do you add a dependency cooldown for AI coding agents?
Install the Skylos hooks in the project:
pip install skylos
cd your-project
skylos agent install-hooks # Claude Code (.claude/settings.json)
skylos agent install-hooks --codex # Codex (.codex/hooks.json)
skylos agent install-hooks --cursor # Cursor (.cursor/hooks.json)
Real output of the Claude Code command in a scratch repository, with --skylos-bin skylos added so the committed file runs skylos from each machine's PATH (trimmed):
Installed 9 Skylos hook(s) in .../install-demo/.claude/settings.json (skylos 5.7.0).
Claude Code picks up settings changes on the next session; run /hooks to review them.
One of the nine is skylos hook pre-bash --client claude || exit 0 on PreToolUse for Bash. Before any install runs, it reads the command, finds each package and version it would fetch, and asks PyPI or the npm registry when that version was published. Versions younger than 48 hours are denied.
We sent it a payload in the shape Claude Code documents for a Bash call (cwd shortened):
{
"session_id": "cooldown-demo-1",
"transcript_path": null,
"cwd": "/path/to/cooldown-demo",
"permission_mode": "default",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "pip install openai",
"description": "Install package"
},
"tool_use_id": "toolu_demo"
}
At 09:37 UTC on 21 Nov 2026, skylos hook pre-bash --client claude answered in 1.62 s:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Skylos blocked this install: 1 package version is newer than the release cooldown.\n- PyPI package 'openai' 3.57.0 was published 32 hours ago; new versions wait 48 hours. Install openai==3.55.1 instead.\nInstall the older version named above, or wait until the release is 48 hours old. The user can change the wait with min_release_age_hours under [tool.skylos.supply_chain] in pyproject.toml (0 turns it off)."
}
}
PyPI's JSON API showed why 3.55.1: 3.57.0 uploaded 2026-11-20T01:28:43Z (32 hours earlier), 3.56.0 at 2026-11-19T20:57:15Z (37 hours), 3.55.1 at 2026-11-18T16:05:20Z (65 hours). It is the same version pip picked with --uploaded-prior-to P2D. The reason is written for the agent, so it says what to install instead.
Other commands from the same run, all within ten minutes:
| Command the agent runs | pre-bash answer |
|---|---|
pip install openai==3.57.0 | deny, install openai==3.55.1 instead |
pip install openai==3.55.1 | nothing (allowed) |
uv add openai | deny, install openai==3.55.1 instead |
npm install openai | deny: "npm package 'openai' 7.62.0 was published 31 hours ago", install openai@7.60.0 instead |
npm install openai@7.60.0 | nothing (allowed) |
pnpm add openai | deny, install openai@7.60.0 instead |
npx -y openai@latest --version | deny, install openai@7.60.0 instead |
npm i -g openai | deny, install openai@7.60.0 instead |
npm install openai --min-release-age=0 | deny, install openai@7.60.0 instead |
pnpm add openai --config.minimum-release-age=0 | deny, install openai@7.60.0 instead |
pip install --uploaded-prior-to P0D openai | deny, install openai==3.55.1 instead |
Skylos 5.7.0, 21 Nov 2026, 09:37 to 09:45 UTC. Each answer took 1.1 to 1.7 s with the registry lookup. npm's openai@7.60.0 is again the version npm picked with min-release-age=2. The last three rows are the override case. In the npm and pip rows the flag turns off the package manager's own window (shown in the previous section), and the hook judges the version anyway. The pnpm row is the hook's answer to that command, pnpm itself was not run.
"Nothing" means the hook printed no decision, so Claude Code's normal permission flow applies. Codex and Cursor get the same deny in their own format. Where Skylos would ask on Claude Code (below), it denies on Codex, because Codex does not support ask from PreToolUse.
The same hook checks the install for packages that do not exist and look-alike names, versions reported as malware (OSV MAL- records), and npm versions that lost the provenance their earlier releases had. Those have their own pages: packages that don't exist and slopsquatting.
How do you change the cooldown window?
In pyproject.toml at the project root:
[tool.skylos.supply_chain]
min_release_age_hours = 72 # hook default 48; 0 turns the cooldown off
Same openai releases, same minute, three windows:
min_release_age_hours | pip install openai | npm install openai |
|---|---|---|
| 24 | nothing (3.57.0 was 32 hours old) | nothing (7.62.0 was 31 hours old) |
| 48 (default) | deny, install openai==3.55.1 | deny, install openai@7.60.0 |
| 72 | deny, install openai==3.55.0 | deny, install openai@7.59.0 |
Skylos 5.7.0, 21 Nov 2026, 09:37 to 09:38 UTC. With 72 hours, 3.55.1 (65 hours old) was too young as well, so the hook named 3.55.0 (76 hours).
The same setting turns on SKY-SCA-AGE001 in dependency scans, which have no default. A Skylos Cloud policy can raise the value and cannot lower it. To let one package skip the wait (your own fast-moving library, or a security fix you have read), list it:
[tool.skylos]
hooks_allow_packages = ["my-internal-lib", "npm:@myorg/ui"]
A listed name skips every install check, not just the wait. With a synced Skylos Cloud policy that sets block_malware, the malware check still runs for it.
How do you keep an agent or a pull request from removing the cooldown?
An agent can edit pyproject.toml like any other file. We sent pre-edit an Edit that changed min_release_age_hours = 48 to 0, and pre-bash the matching sed -i. Both printed nothing: the hooks do not block that edit. The check that catches it runs on the branch. On a branch with that one-line change, skylos done --base main exited 1 (trimmed):
Skylos done · base 2b6cf9c (merge base) · head 91967a4
FAIL Skylos settings and hooks left alone: 1 change(s) to Skylos settings or hooks
pyproject.toml:5 SKY-A114 changes Skylos settings ([tool.skylos])
Fix: Undo the changes to those files. A person should make changes there.
Verdict: FAIL: Skylos settings or hooks were changed. The tests were not run because of this
The package managers' own settings get the same treatment in a diff scan. On a branch that deleted an .npmrc holding min-release-age=2:
skylos . --sca --diff-base main --diff main --gate
exited 1 with (trimmed):
Quality Gate: FAILED
• 1 dependency vulnerability (max: 0)
SKY-SCA-HRD001 .npmrc:1 This change weakens install hardening: npm min-release-age was removed (was 2).
Per docs/dependency-scanning.md at v5.7.0, SKY-SCA-HRD001 compares npm min-release-age, pnpm minimumReleaseAge, Yarn npmMinimalAgeGate, Bun minimumReleaseAge, uv exclude-newer, pip --uploaded-prior-to, Dependabot cooldown and Renovate minimumReleaseAge between the merge base and the branch, and reports a removal or a lower value. A removal that falls back to an equal or longer default, such as pnpm 11's one day, is not reported. Run both in CI as required checks. The Codex hooks page shows skylos cicd init, which writes a workflow with a Done job.
What doesn't a dependency cooldown cover?
Any cooldown:
- It delays risk. It does not remove it. In Woodruff's table, xz-utils stayed hidden for about 5 weeks and Kong Ingress Controller for about 10 days. A bad version nobody catches inside the window installs like any other.
- Security fixes wait too, unless you exempt them. Dependabot never delays security updates. The package managers and Skylos each have an exclude list (FAQ below).
- It does nothing for what you already locked. A version in your lockfile from last week is installed again by
npm ciwhatever its age.
The Skylos hook, per docs/agent-hooks.md at v5.7.0 and our run:
- Lockfile installs get the malware check, not the cooldown. In the test repository, a
package-lock.jsonwe wrote by hand (with the registry's integrity hash) pinnedopenai7.62.0, then 31 hours old.npm ciwas allowed, and the hook log recorded"locked_packages": 1, "outcome": "pass". The same applies touv sync,pip install -rand the other lockfile installs. A dependency scan with the window set does report it:
skylos . --sca --format json
{
"rule_id": "SKY-SCA-AGE001",
"severity": "HIGH",
"message": "openai@7.62.0 was published 31.9 hours ago, younger than the 48-hour minimum release age. ... Pin openai@7.60.0 (older than the window) or wait.",
"file": ".../cooldown-demo/package-lock.json",
"line": 15
}
(Message trimmed by one sentence. The same finding is reported on package.json:6.)
- Git and URL sources are not judged by age. They ask.
pip install git+https://github.com/openai/openai-pythonreturned"permissionDecision": "ask"with "Skylos could not verify this install. Approve it only if you trust these sources." On Codex that becomes a deny. Unknown registries and failed lookups ask too, and the whole install check has a 20-second budget inside the 30-second hook timeout. - The cooldown covers npm and PyPI. Go and JSR packages get the existence and look-alike checks, not the cooldown.
cargo,gem,composerandcondainstalls, dependencies declared inside a script (uv run script.pywith inline metadata), package managers' lifecycle scripts, a script that callspip, andcurl ... | share not followed.cargo add serdegot no answer in our run. For Ruby, Bundler has its owncooldownsetting in days (bundle config set cooldown 7, per the RubyGems guides). - PyPI age is the release's newest upload. Per the SKY-SCA-AGE001 rule, a wheel added today to an old release makes the release new again. uv compares each file's upload time instead.
- It runs where it is installed, and nowhere else. Every hook command ends in
|| exit 0, so a missing or broken Skylos never blocks the agent and checks nothing.skylos doctorsendspre-basha test payload and says whether the hooks answer. - It is not a sandbox. It reads the command the agent typed. A program that installs something in a way Skylos does not parse is not checked.
- It needs the network. Package names in install commands go to PyPI, the npm registry and OSV. Your source stays on your machine.
Skylos is one way to put a check in the agent's loop. A hand-written PreToolUse hook that queries registry publish times does the same job for one package manager, and the package manager settings above stay the base layer for people and CI.
Setup in 60 seconds
pip install skylos
cd your-project
printf 'min-release-age=2\n' >> .npmrc # npm 11.10 and later; pick your tool's setting above
skylos agent install-hooks # add --codex or --cursor for those agents
skylos doctor # checks the hooks answer
Real skylos doctor output after the install in the scratch repository (path shortened):
Agent hooks
OK Claude Code: 9 of 9 hooks in .claude/settings.json (project) → .../bin/skylos
Self-test (passed): pre-bash allowed `ls` (0.5 s) and blocked `cat .env` of a file with a token (0.8 s)
Commit .npmrc (or your tool's file), .claude/settings.json and, to change the 48-hour window, [tool.skylos.supply_chain] in pyproject.toml. No account or API key is needed.
Changelog
- 21 Nov 2026: First version. Skylos 5.7.0. npm 12.2.3, pnpm, Yarn, Bun, uv, pip 26.3, Renovate and Dependabot docs read the same day. Captures use
openai3.57.0 (PyPI) and 7.62.0 (npm), both under 48 hours old at the time.
Related
- Claude Code hooks examples for security (Codex and Cursor too)
- Codex hooks: examples, hooks.json and a merge check
- Your AI agent just tried to install a package that doesn't exist
- Slopsquatting: hallucinated package names
- AI coding agent security checklist
- GitHub Actions PR gate for AI-generated code
References
- npm config reference, min-release-age (CLI 12.2.3) and npm CHANGELOG, read 21 Nov 2026
- pnpm dependency resolution settings, pnpm v10.16.0 and v11.0.0 release notes, read 21 Nov 2026
- Yarn yarnrc reference, 4.10.0 and 4.15.0 release notes, read 21 Nov 2026
- Bun bunfig reference and Bun 1.3 post, read 21 Nov 2026
- uv settings reference, exclude-newer and uv 0.9.x changelog, read 21 Nov 2026
- pip install reference, --uploaded-prior-to (pip 26.3) and pip changelog, read 21 Nov 2026
- Renovate minimumReleaseAge and security preset source, read 21 Nov 2026
- Dependabot options reference, cooldown, changelog 14 Jul 2026 and changelog 1 Jul 2025, read 21 Nov 2026
- PyPI administrator's audit-log timeline, Ultralytics, 6 Dec 2024, read 21 Nov 2026
- William Woodruff, "We should all be using dependency cooldowns", 21 Nov 2025, read 21 Nov 2026
- Claude Code hooks reference, read 21 Nov 2026
- RubyGems guide, Bundler cooldown, read 21 Nov 2026
- Skylos agent hooks reference, v5.7.0 and dependency scanning, v5.7.0