feat(agents): track agent versions live from npm

[YauheniHHH]

Summary

Implements EPMCDME-14767: the version CodeMie tracks for Claude, Codex, Gemini and Kimi now follows each agent's latest npm release instead of a hand-edited constant.

• Live tracking. Claude, Codex, Gemini and Kimi (incl. Kimi ACP, the same binary) resolve their tracked version from the npm registry, cached for 24h. The launch notice, codemie setup, codemie update and codemie doctor (which already compared versions on main) all read it through one resolver, resolveSupportedVersionDetailed. codemie update no longer special-cases Claude, and always fetches fresh (bypassing the cache) since the user asked to check now. The hardcoded *_SUPPORTED_VERSION constants now only mark an agent as version-checked and no longer need bumping.
• Fast lookup. One HTTPS GET to <registry>/<package>/latest, instead of spawning npm view. On a Windows laptop npm view took 2.5–3.8s per package and about 4s each in parallel, so the 3s limit was routinely hit and the feature silently did nothing. The direct request takes about 0.25s (4 packages in parallel: 0.67s). It honors npm's registry and @scope:registry settings, plus HTTPS_PROXY/HTTP_PROXY/NO_PROXY and npm's proxy settings. Registries that require auth aren't supported, and npm's strict-ssl/cafile settings aren't read (Node's NODE_EXTRA_CA_CERTS still works for a corporate CA). In those setups the tracked version stays unknown, so no notice is shown; nothing breaks. ${VAR} references are expanded only in the user .npmrc, never in a project .npmrc, so a checked-out repo can't route env secrets to its own host on agent launch.
• Ahead is fine. A live-tracked agent that is ahead of the tracked version (typically self-updated within the 24h cache window) gets no notice and no --supported hint, which would otherwise suggest a downgrade.
• Offline. codemie update reports "Could not check X" for agents whose lookup failed instead of dropping them; while the registry is unreachable a launch can wait up to 3s for the lookup, after which lookups are skipped for 10 minutes (update always retries).
• Unknown means unconfigured. When checks are off, the lookup fails, or npm reports a prerelease, the tracked version is reported as unknown. There's no notice, warning or update offer, and the hardcoded constant is never presented as current (criteria feat: add ability to pass command-line arguments directly to agents #4/feat: clean-up cli, remove aider, simplify initial setup #5). Failures go to the log file.
• Toggle. CODEMIE_VERSION_CHECKS_ENABLED, or workspace.versionChecks.enabled in the project or global config, resolved in that order. On by default; only an explicit false disables it. Documented in docs/CONFIGURATION.md.
• install --supported installs the tracked version, or the latest release when it's unknown, never the stale constant. For an already-installed agent it asks first.
• Other agents are unchanged. Copilot CLI and others keep their maintainer-pinned version and notice, as on main.
• Minimum-version block is unchanged, including with checks off. The ticket keeps it "as-is" and scopes this story to the recommended/supported advisory, so criterion feat: clean-up cli, remove aider, simplify initial setup #5 is read as covering the advisory only. This reading still needs to be recorded on the ticket.
• Copy. "CodeMie recommends / tested vX" becomes "CodeMie is tracking vX", answering the ticket's open question on terminology.

Windows: required for the feature

getVersion() now runs --version through a shell on Windows for Codex and Gemini, and for the PATH fallback of Kimi and Claude (npm installs). npm installs are .cmd shims that spawn() can't start directly, so without this getVersion() failed there and no version check ran for those agents on Windows (criterion #3). Native .exe installs worked before and still do. Agents' own self-updaters are left untouched: a self-update moves the agent to npm's latest release, which is exactly the tracked version.

Corrections to the previous description

The earlier description said the Codex test failures were "pre-existing … unrelated" and that "CI is green". Both were wrong: this branch's live lookup reached the real npm registry from inside codex.plugin.version-support.test.ts. The tests now mock the resolver.

Split out / follow-ups

• exec() quoting of the base command in shell mode is in its own PR (branch fix/exec-shell-command-quoting).
• codemie update kimi updates the npm package, not the native Kimi binary. Pre-existing.
• A malformed installed version skips the minimum gate, and setup shows a green check for a below-minimum Claude. Both pre-existing.

Test plan

• npm run license-check, typecheck, lint, build
• npx vitest run --project unit (300 files, 4.5k tests), including a registry client tested against a real local HTTP server (proxy, NO_PROXY, scoped registries, timeouts), plus version cache, resolver, and Codex/Gemini/Claude plugin tests
• Live check against the real registry: every package under 1s, none over the 3s limit
• npx vitest run --project cli: failures in a full parallel run all pass in isolation. upstream/main shows the same local flakiness, and CI's integration step hasn't failed in its last 100 runs.
• Mutation-checked: re-introducing the fixed bugs makes the new tests fail
• CI on GitHub (needs maintainer approval for fork PRs)

Generated with AI

Co-Authored-By: codemie-ai codemie.ai@gmail.com

[YauheniHHH]

@mykolanehrych Thanks — resolved. I rebased onto the latest main; the conflict was only the import block in BaseAgentAdapter.ts (vs. the system-proxy imports from #571), and the PR is mergeable again.
Changes added along with the rebase:

• Proxy: the npm registry lookup now uses the shared system-proxy resolver from fix(proxy): honor Windows system proxy and PAC settings #571, so it also works behind a Windows system proxy/PAC. npm's own https-proxy/proxy settings still take precedence, as in npm.
• Agent test setup: agent-build-setup.ts checks the installed Claude against the live tracked version, not the old constant. Before, it reinstalled Claude on every run.

[elluvium]

Security (medium/low): version cache is shared across registries, so a project .npmrc can poison it

getCachedLatestVersion keys the cache by package name only (here and at :155 on write). The registry it queries is resolved from the project .npmrc as well as the user one (src/utils/npm-registry.ts:61). The result is written to the global ~/.codemie/version-cache.json with a 24h TTL.

Scenario

1. A repo ships a .npmrc with registry=https://attacker.example/ (or @anthropic-ai:registry=...).
2. The user runs codemie claude in that repo. The lookup goes to the attacker's server, which returns {"version":"1.0.5"}, an old but real release. It passes the NPM_VERSION_PATTERN and extractVersion checks.
3. The value is cached under the package name. In any other project, a cache hit is served without a lookup, and resolveSupportedInstallVersion returns 1.0.5 as the install target for install --supported or update.

Impact

• The attacker can steer the install to an older real version, for example one with known vulnerabilities.
• isAheadOfLiveTracking suppresses update notices when the installed version is newer, so a downgrade is less likely to be noticed.
• No code injection: the version is digits-only and the install still comes from the real registry. Pointing a repo at another registry is normal npm behavior. The new part is that the effect outlives the repo through the shared cache.

Related, lower priority: http: registries are accepted (npm-registry.ts:139). That is fine for internal mirrors configured by the user, but it is another reason to trust only user-level registry config here.