air upgrade should keep extensions in lockstep with air-cli

[tadasant]

Problem

air upgrade only runs npm install -g @pulsemcp/air-cli@latest — it does not touch the extensions installed under air-cli's managed extension directory (e.g. ~/.air/node_modules/). Because the air monorepo does lockstep version bumps across all 8 packages, this leaves users with a CLI on the latest version and extensions multiple major versions behind, which produces hard-to-diagnose runtime errors.

Reproduction

Starting state — long-stale install, then air upgrade:

$ npm ls -g
@pulsemcp/air-cli              0.4.1   ← upgraded by `air upgrade`
@pulsemcp/air-adapter-claude   0.4.1   ← present globally but not the one loaded
@pulsemcp/air-provider-github  0.4.1
@pulsemcp/air-secrets-env      0.4.1

$ ls ~/.air/node_modules/@pulsemcp/
@pulsemcp/air-adapter-claude   0.0.25  ← actual loaded extensions
@pulsemcp/air-provider-github  0.0.25
@pulsemcp/air-secrets-env      0.0.25
@pulsemcp/air-secrets-file     0.0.25
@pulsemcp/air-core             0.0.25

$ cat ~/.air/package.json
{
  "dependencies": {
    "@pulsemcp/air-adapter-claude": "^0.0.25",
    "@pulsemcp/air-provider-github": "^0.0.25",
    ...
  }
}

air start claude then fails with:

Error: Provider for "github://" cannot resolve directory paths — it lacks resolveCatalogDir().
Upgrade the provider extension or replace the URI with a vendored relative path.

Even though the new global air-provider-github@0.4.1 implements resolveCatalogDir(), the extension loader uses createRequire(join(airJsonDir, "__placeholder.js")) where airJsonDir defaults to ~/.air/, so the v0.0.25 copy in ~/.air/node_modules/ is what's resolved.

Two underlying gaps

1. air upgrade doesn't update extensions. It needs to additionally rewrite ~/.air/package.json (or whichever <airJsonDir>/package.json the user's config resolves from) and reinstall — pinning each extension to a version compatible with the new CLI. Since the monorepo is lockstep, pinning to the CLI version is the simplest correct behavior.

2. air install's isPackageInstalled() only checks directory existence, never version compatibility. From packages/sdk/src/install.ts:

   function isPackageInstalled(specifier, prefix) {
     const name = stripVersion(specifier);
     return existsSync(join(prefix, "node_modules", name));
   }

   So even if the user runs air install after the CLI bump, it sees ~/.air/node_modules/@pulsemcp/air-provider-github exists and reports Already installed, never bumping. Pinned ^0.0.25 constraints in the package.json compound this — npm install alone in that dir won't upgrade either.

Proposed fix

air upgrade should:

1. Upgrade air-cli (today's behavior).
2. Read the resolved air.json's extensions array.
3. For each extension, rewrite the corresponding constraint in <airJsonDir>/package.json to a version range compatible with the upgraded CLI (e.g., ^<cli-major>.<cli-minor>.0, since the monorepo bumps in lockstep).
4. Run npm install --prefix <airJsonDir> (or equivalent), letting npm pull the new versions.

air install's isPackageInstalled should also be tightened so a user can force a re-check / reinstall when CLI compatibility shifts — at minimum, parsing <prefix>/node_modules/<name>/package.json and comparing against the desired constraint.

Workaround

For users hitting this now:

npm install --prefix ~/.air \
  @pulsemcp/air-adapter-claude@latest \
  @pulsemcp/air-provider-github@latest \
  @pulsemcp/air-secrets-env@latest \
  @pulsemcp/air-secrets-file@latest

(Adjust the package list to match your ~/.air/air.json extensions array.)

Related

This is likely subsumed by the broader air update/air upgrade unification work — filing separately so the install-location and version-aware install semantics are tracked explicitly regardless of how the command shape lands.

[tadasant]

🚦 Issue gate

Kind: bug (⚪ normal) · Scope: convergent · Facets: none

Verdict: HELD — A6, I cannot say what "done" looks like independently of #132. The defect is real, reproduced in the issue, and I confirmed the second half of it on main: isPackageInstalled (packages/sdk/src/install.ts:56–59) is existsSync(join(prefix, "node_modules", name)) and nothing more, so a stale extension tree reports Already installed forever. That much is convergent — a lockstep monorepo whose upgrade command leaves the install broken is violating an obvious intent, and I am not holding this as a feature request. What I cannot state in one sentence is which thing is being asked for: implementing lockstep inside today's air upgrade and implementing it inside the unified command #132 proposes are different work with different surfaces, and the issue's own closing line says this is "likely subsumed by the broader air update/air upgrade unification". #132 is held for a human to pick that shape, so this one's definition of done is downstream of a decision nobody has made yet.

Live pages: none — not alert-shaped, and nothing in pulsemcp/air is deployed (the surface doc: "nothing here is deployed, so nothing pages"), so anchor 2a has no rule to resolve; anchor 2b — quick_search_sessions for pulsemcp/air issue sessions with show_archived: true — returns no alert-genesis session. Normal dispatch.

Where I am not confident, said plainly: this is the closest call in this repo's twelve, and a reasonable reading proceeds. The version-pinning policy is the other open half — the issue offers ^<cli-major>.<cli-minor>.0 as an e.g., and picking the constraint is a compatibility decision with a blast radius across every installed extension. ISSUE_WORK_GATE_AIR_FRAMEWORK.md also names this issue under A6 by name. If Tadas reads it the other way, this is a cheap overrule.

Re-entry: once #132's command shape is settled — or a human says to land the lockstep semantics standalone against today's air upgrade, with a stated pinning constraint — hand it back and I will rate it in full.

Rating detail

Axis	Rating	Why
Requirement complexity	large	The surface doc's worked large: "how extensions stay in lockstep with air-cli (#131)".
Requirement impact	medium	The upgrade path only — but it fails closed and opaquely (Provider for "github://" cannot resolve directory paths is not a message that points at a stale ~/.air/node_modules).
Solution complexity	medium (est.)	Guessing: rewrite <airJsonDir>/package.json constraints, reinstall, and tighten isPackageInstalled to parse the installed package.json. Known shape once the constraint policy is chosen.
Implementation risk	medium (est.)	Guessing: it rewrites a user's manifest and runs npm install against their machine. A wrong constraint downgrades a working install.
Estimated cost	medium (est.)	Guessing: two SDK files plus tests, more if the resolution path in createRequire is touched.

Note: the three solution-side axes are estimates — there is no diff yet, and under this surface's posture they decided nothing.

Staleness check: live. packages/sdk/src/install.ts on main still has the existence-only isPackageInstalled at lines 56–59, called from line 150. Nothing merged since 2026-05-15 touches the upgrade or install path. The overlapping open issue is #132, which is not a duplicate — it is the command-shape question this one's answer depends on.

[tadasant]

🚦 Issue gate — re-rated, now clearing

Verdict: proceed. This issue was previously held, and the ground it was held on has been retired.

What changed

A6 — the “you cannot say what done looks like” hold was retired on 2026-09-06 at Tadas's instruction. In his words, on the design half:

"'design questions' should not be a hold either. those should proceed and the agent should make design decisions, for the human to override later if the human doesn't like what gets merged"

and on the done-statement half: "'cannot say what done looks like' should not be a hold reason."

So an open design or shape question in the issue is no longer a reason to wait for a human. The implementing agent makes the call; if the call is wrong, the human overrides it at review — that is the trade Tadas chose deliberately.

Why this issue clears now

The prior hold rested on this issue's done being downstream of a command-shape decision nobody had made (#132 proposes unifying air update/air upgrade). That indeterminacy is no longer a hold reason. Note #132 itself stays held, on A3 — it asks for a confirmation prompt, --yes/--no-upgrade flags and a non-TTY default that do not exist, which is a new CLI contract rather than a design call. Implement lockstep against today's air upgrade; if #132 later lands, this is re-shaped then.

Re-rated against the remaining tests

Every other hold test was re-checked with the retired ground unavailable, and none fires: A1 (self-escalation), A2 (never-auto kind / permanent exclusion), A3 (expands product scope), A4 (an agent could not finish it), A5 (stale, duplicate or already fixed), A7 (the work acts on production rather than on a PR), A8 (triviality).

Ratings

Carried from the prior rating; the last three are estimates made before any diff exists, not measurements.

Axis	Rating
Requirement complexity	large
Requirement impact	medium
Solution complexity (est.)	medium
Implementation risk (est.)	medium
Estimated cost (est.)	medium

Scope direction: convergent. Kind: bug.

The axes are recorded for calibration and do not decide anything under the action-by-default posture.

What happens next

Queued to the ranked work backlog, in the medium cost band. The backlog groomer starts it from there — at 04:00, or sooner if the fleet runs out of work. A human can re-order or remove it at any time.

_{Re-rated by the issue work gate · session 15287 · supersedes ledger decision #2020, which stays on the record.}