## TL;DR
package.json changed without a lockfile refresh, so pnpm refuses to install. Run pnpm install, which updates pnpm-lock.yaml automatically, then review the lockfile diff and commit it. Never hand-edit the lockfile to match.

## Error

```text
pnpm 'ERR_PNPM_OUTDATED_LOCKFILE' after the agent edited package.json by hand
```

## Steps

1. Confirm the drift: git diff package.json shows the hand edit; git status shows pnpm-lock.yaml unchanged.
   Expected output: You see the manifest change with no matching lockfile change.
2. Refresh the lockfile: pnpm install.
   Expected output: pnpm updates pnpm-lock.yaml and the outdated error is gone.
3. Review what moved: git diff pnpm-lock.yaml, checking that only the intended packages changed versions.
   Expected output: The diff matches the hand edit's intent.
4. Run the test suite to confirm the refreshed graph still works.
   Expected output: Tests pass on the new resolution.
5. Commit both files together so the next install is deterministic.
   Expected output: CI with a frozen lockfile goes green.

## When to use

- pnpm fails with ERR_PNPM_OUTDATED_LOCKFILE after someone edited package.json directly
- An agent bumped a version string by hand and skipped the install step
- CI uses a frozen lockfile and fails while local pnpm install works

## When not to use

- The lockfile is current but a tarball is missing; that is a fetch problem, not staleness
- You want to change versions deliberately across many packages; use pnpm update instead
- The error is ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY; that needs a forced rewrite, not a refresh

## Variant phrasings

### pnpm install fails with outdated lockfile in CI
The CI shape: a frozen lockfile turns the drift into a hard failure; refresh locally and commit.

### Agent edited package.json and pnpm refuses to proceed
The agent skipped the lockfile step; add pnpm install to the agent's bump routine.

### pnpm-lock.yaml out of sync after merging main
Merge conflicts resolved in package.json but not re-locked; pnpm install reconciles them.

## Why it happens

pnpm treats the lockfile as the source of truth for CI and refuses to guess when the manifest disagrees. A hand edit to package.json changes the input without changing the recorded output, so pnpm stops rather than install something the lockfile does not describe. Running pnpm install re-resolves and records the new truth.

## Edge cases

- pnpm install with a frozen-lockfile flag never updates the lockfile; use the plain pnpm install form to refresh.
- If the hand edit itself was wrong (a typo in the version), fix package.json first, then refresh.
- Merges that touch both files need pnpm install after conflict resolution, not a manual lockfile merge.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_42fSSqM_1tyNV-13EK05ew