/audit-updates

name: audit-updates
description: Triage pnpm audit findings and produce a prioritized, supply-chain-cautious package-update plan, then apply approved batches

Triage the repo's `pnpm audit` output and dependency drift, then produce a **prioritized, risk-annotated update plan** that fixes real security exposure while avoiding supply-chain traps (compromised fresh releases, unnecessary major bumps, install-script risk).

**This command is two-phase.** Phase 1 investigates and reports a plan — it makes NO changes. Then STOP and wait for explicit user direction. Phase 2 applies the approved updates in small batches, verifying between each. Never edit `package.json`, run `pnpm install`, or commit during Phase 1.

Repo facts (don't re-derive)

• Single root `pnpm-lock.yaml`; pnpm **workspaces**. Run `pnpm audit` from the repo root — it covers all workspaces. All pnpm settings (`overrides`, `patchedDependencies`, `allowBuilds`, `minimumReleaseAge`) live in the root `pnpm-workspace.yaml`.
• Workspaces: `packages/electron`, `packages/runtime`, `packages/cli`, `packages/core`, `packages/collab-protocol`, `packages/collab-adapters`, `packages/ios`, `packages/android`, `packages/extension-sdk`, `packages/extensions/*`, `packages/marketplace`. Additional package.json files exist for `browser-extension` and `opencode-plugin`.
• **`minimumReleaseAge` is 72h (4320 minutes) in `pnpm-workspace.yaml`.** Versions younger than 3 days will not resolve at all; the 21-day cooldown below is a stricter policy on top of it. A fix that exists only in a version younger than 72h needs a scoped `minimumReleaseAgeExclude` entry with a reason, which is a decision for the user, not for this command.
• **`allowBuilds` gates install scripts.** A newly-introduced package with an install script fails `pnpm install` until it is listed in `allowBuilds` as `true` or `false`. Treat that entry as the security decision it is (see principle 5).
• The `overrides` block in `pnpm-workspace.yaml` pins some deps (e.g. `@anthropic-ai/claude-agent-sdk`). An override must be bumped in lockstep or the upgrade is silently neutered. Never revert `@anthropic-ai/claude-agent-sdk` below 0.2.113.
• Both SDKs ship platform binaries via `extraResources`/`optionalDependencies`; the package manager can silently skip these on stale integrity hashes. Validate binaries survive any bump that touches them.
• The `/update-libs` command owns the three AI SDKs (claude-agent-sdk, MCP sdk, codex-sdk). If audit findings land on those, defer to `/update-libs` rather than bumping them here.

Security principles (the whole point of this command)

1. **Cooldown window: 21 days.** Never move a dependency to a version published less than ~21 days ago. Supply-chain attacks are usually caught within days-to-weeks of a malicious publish. For each package, target the **newest version that is both (a) at least 21 days old and (b) resolves the advisory.** If the *only* fix is a version younger than 21 days, do NOT auto-recommend it — flag it as "fix requires a fresh release; hold or manually vet" and explain the tradeoff. A live-exploited advisory may justify overriding the cooldown, but call that out explicitly and let the user decide. 2. **Prefer the smallest semver move that clears the advisory.** Patch > minor > major. Never pull a major version bump "while we're here" — majors are a separate, deliberate decision with their own testing. 3. **Prefer transitive fixes via the dependency tree, not blanket `overrides`.** Reach for targeted version bumps first (`pnpm audit --fix` only adds `overrides` entries to `pnpm-workspace.yaml`, so review each one). Only propose an `overrides` entry when the vulnerable package is transitive and upstream hasn't released a fixed parent yet — and mark such overrides for later removal. 4. **Never bulk-apply audit fixes unreviewed.** `pnpm audit --fix` writes overrides for every fixable advisory at once, including semver-major and brand-new releases, defeating both the cooldown and the minimal-move principles. Apply each fix deliberately. 5. **Scrutinize install scripts.** New/changed `postinstall`/`preinstall`/`install` scripts are a primary supply-chain vector. For any newly-introduced package (not just bumped), note whether it runs install scripts. 6. **Judge reachability, not just severity.** A "critical" in a build-only devDependency reachable only in CI is lower real risk than a "high" in a runtime path shipped to users. Weight: is it a runtime (`dependencies`) or dev/build-only dep? Is the vulnerable code path actually reachable in how Nimbalyst uses it? Is it in the Electron main process, the renderer, the runtime shipped to users, or a build tool? 7. **Watch for new maintainers / typosquats / churn.** If a package changed ownership, was recently transferred, or a name looks like a typosquat of a popular package, flag it — don't silently trust it. 8. **Pin what you resolve.** After fixing, the lockfile is the source of truth. Don't loosen version ranges in `package.json` in a way that lets a future `pnpm install` silently pull an un-vetted newer release.

---

Phase 1: Investigate and report (always run first; no changes)

Run these yourself — never ask the user to paste output.

1. **Gather the audit surface:**

• `pnpm audit --json` from the repo root (full machine-readable advisory list).
• `pnpm audit` (human summary, for the severity counts).
• `pnpm outdated -r` (optional, to see how far behind direct deps are — helps spot deps that are old for non-security reasons too).

2. **Group advisories by fixable unit.** Multiple advisories often collapse to one package bump. For each vulnerable package determine: severity, whether it's a direct or transitive dependency, which workspace(s) pull it in, whether it's a runtime vs dev/build dep, and the CVE/GHSA summary (what the vuln actually is). 3. **For each candidate fix, resolve the target version under the cooldown rule:**

• `npm view <pkg> versions --json`