feat(agents): track agent versions live from npm

docs/CONFIGURATION.md

@@ -226,6 +226,28 @@ be used as the permanent corporate configuration.
 - Cache location: `~/.codemie/.last-update-check`
 - See `codemie self-update --help` for manual update options
 
+#### Agent Version Checks
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `CODEMIE_VERSION_CHECKS_ENABLED` | Compare installed agents (Claude, Codex, Gemini, Kimi) against their latest release on npm | `true` | `false` to turn checks off |
+
+When enabled, CodeMie reads each agent's latest release from your configured npm registry (cached for 24h) and shows a one-time notice when your installed version differs; `codemie doctor` uses the same value, and `codemie update` always fetches it fresh. The lookup is a single HTTPS request that honors npm's `registry`/`@scope:registry` settings and npm's `https-proxy`/`proxy`/`noproxy` settings; without an npm proxy it uses `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` and then the Windows system proxy or PAC (see [Windows system proxy and PAC](#windows-system-proxy-and-pac)). Registries that require authentication aren't supported. npm's `cafile`/`ca`/`strict-ssl` settings aren't read: behind a TLS-intercepting proxy, trust the corporate CA with `NODE_EXTRA_CA_CERTS`, or set `CODEMIE_VERSION_CHECKS_ENABLED=false`. A failed lookup is written to the CodeMie log file and never stops a launch — the check is simply skipped. While the registry is unreachable, a launch can wait up to 3 seconds for the lookup; after a failure CodeMie skips further lookups for 10 minutes (`codemie update` always retries). Set `CODEMIE_VERSION_CHECKS_ENABLED=false` if you work offline. These npm settings come from your user `.npmrc` (or `npm_config_*` environment variables) only; a project's `.npmrc` is ignored for this lookup, so a checked-out repository can't choose the registry or proxy that decides the tracked version. When CodeMie is started through `npm run` or `npx`, npm exports the project's settings as `npm_config_*` variables, so those are ignored too and only `~/.npmrc` is read.
+
+With checks off there is no lookup, notice, or update offer for these agents. `codemie install <agent> --supported` then installs the latest release, and the minimum-version guard (which refuses versions known to be broken) still applies.
+
+The same switch can be set in `~/.codemie/codemie-cli.config.json` (all projects) or a project's `.codemie/codemie-cli.config.json`:
+
+```json
+{
+  "workspace": {
+    "versionChecks": { "enabled": false }
+  }
+}
+```
+
+Precedence: the env var, then the project setting, then the global one. Only an explicit `false` turns checks off.
+
 #### Security & File Access
 
 | Variable | Description | Example |

docs/specs/claude-version-management/installation-and-versioning.md

@@ -1,5 +1,13 @@
 # Claude Code CLI Installation and Version Management
 
+> **Superseded in part (EPMCDME-14767).** The hand-maintained "supported version" described below
+> is no longer the source of truth. Claude, Codex, Gemini and Kimi now track their latest npm
+> release live (cached for 24h), behind the global `versionChecks.enabled` toggle. The metadata
+> `supportedVersion` only marks an agent as version-checked and is never shown as current: when the
+> lookup fails or checks are off, the tracked version is unknown and `install --supported` installs
+> the latest release. `minimumSupportedVersion` stays hand-maintained and still blocks launch. See
+> "Agent Version Checks" in `docs/CONFIGURATION.md`. The installation flow below is unchanged.
+
 ## Specification Summary
 
 **Last Updated**: 2026-01-29

docs/superpowers/tasks/2026-10-07-pr576-review-round4-fixes/actual-complexity.json

@@ -0,0 +1,40 @@
+{
+  "schema": 1,
+  "generated": "2026-10-07T00:00:00Z",
+  "dimensions": {
+    "component_scope":      { "score": 4, "label": "L" },
+    "requirements_clarity": { "score": 2, "label": "S" },
+    "technical_risk":       { "score": 4, "label": "L" },
+    "file_change_estimate": { "score": 6, "label": "XXL" },
+    "dependencies":         { "score": 1, "label": "XS" },
+    "affected_layers":      { "score": 3, "label": "M" }
+  },
+  "total": 20,
+  "size": "M",
+  "band_range": "15-20",
+  "files_changed": 18,
+  "routing": "brainstorming",
+  "key_reasoning": [
+    {
+      "dimension": "component_scope",
+      "reason": "Targeted fixes across about 6 existing components in 3 layers: the version-cache and npm-registry shared utilities, version-resolution plus BaseAgentAdapter and types in the agent core, and the install and setup CLI commands. No new abstractions; the work extends the existing live-version-tracking design from PR #576. Base M, bumped to L because it touches core shared utilities (version-cache, npm-registry) that every live-tracked agent and command uses."
+    },
+    {
+      "dimension": "technical_risk",
+      "reason": "The changes are security-sensitive. The cache key no longer embeds the registry URL (which can carry credentials): it uses the URL origin plus a SHA-256 hash, and legacy raw-URL keys are dropped when the cache loads, so the next save removes them from disk. When a configured npm proxy is invalid, the lookup now fails instead of quietly going direct, and the proxy value is never logged. The closest existing pattern (sanitizeLogArgs-style log scrubbing) does not cover secrets stored in persisted cache keys or the no-direct-fallback rule, so Technical Risk was bumped from M to L. The rest (guarded minimum comparison, AgentInstallationError when the registry latest is below the minimum, setup warning) follows established patterns and is easy to roll back."
+    },
+    {
+      "dimension": "file_change_estimate",
+      "reason": "The diffstat reports 18 files changed (472 insertions, 28 deletions), which maps to XXL (16+) on the actual-mode scale. The count is inflated by tests and docs: 9 test files, 2 docs files (CONFIGURATION.md and the PR #576 spec) and 7 source files across src/utils, src/agents/core and src/cli/commands. The source footprint alone would score about L."
+    },
+    {
+      "dimension": "requirements_clarity",
+      "reason": "The work comes from specific, itemized code-review findings (round 4 and 5) on an existing PR, each with a clear expected behavior. No open design decisions."
+    }
+  ],
+  "red_flags_applied": [
+    "Technical Risk bumped from M to L: security requirement. Registry credentials must never reach the persisted version-cache keys, and a configured npm proxy must not be silently bypassed. The existing log-sanitization pattern does not cover either case.",
+    "Component Scope bumped from M to L: touches core shared utilities (src/utils/version-cache.ts, src/utils/npm-registry.ts) used by every live-tracked agent, install, setup and update."
+  ],
+  "split_recommendation": null
+}

docs/superpowers/tasks/2026-10-07-pr576-review-round4-fixes/code-review-brief.md

@@ -0,0 +1,22 @@
+# Code review — 2026-10-07-pr576-review-round4-fixes (2026-10-07)
+
+**request-changes** · confidence: high · 8 blocking · 2 deferred · 16 filtered as noise
+Coverage: blind ✓ · edge-case ✓ · verification-gap ✓ · acceptance ✓  (4/4 lenses ran)
+
+## Look here first
+
+- `src/cli/commands/install.ts:180` — [other: backwards compatibility] `--supported` on a lagging mirror prompts "Reinstall with the latest release?" but installs the minimum, which can downgrade the agent — CR-003
+- `src/cli/commands/install.ts:130` — [other: lagging mirror] plain `install claude/codex` installs the below-minimum `latest` that the launch gate then refuses — CR-002
+- `src/cli/commands/setup.ts:787` — [other: version gate] setup shows a green "installed" line for a Claude version below the minimum — CR-005
+- `src/utils/npm-registry.ts:117` — [security] an invalid npm proxy setting silently sends the lookup direct, bypassing the configured proxy — CR-007
+- `docs/superpowers/tasks/2026-09-22-agents-live-version-check/spec.md` — [other: spec] spec §2 does not describe the install-the-minimum path — CR-001
+
+## Also flagged
+
+- `src/utils/npm-registry.ts` — [infra] the user's .npmrc `cafile`/`ca`/`strict-ssl` settings are ignored, so lookups fail behind TLS-intercepting proxies — CR-008
+- `src/cli/commands/install.ts:213` — [other: copy] `install opencode|pi --supported` blames disabled checks or npm, and no test covers it — CR-004
+- `src/cli/commands/update.ts:63` — [other: tests] no test for a failed built-in agent lookup now reported as LOOKUP_FAILED — CR-006
+
+## Checked and clean
+
+commit-format ✓ · code-quality ✓ · security ✓ · 2 deferred → code-review-deferred.md

docs/superpowers/tasks/2026-10-07-pr576-review-round4-fixes/code-review-deferred.md

@@ -0,0 +1,4 @@
+# Deferred from code review — 2026-10-07-pr576-review-round4-fixes (2026-10-07)
+
+- **checkAndInstallClaude has no test** — `src/cli/commands/setup.ts:787` — The first-run setup branch for an installed Claude changed its isNewer output and its timeout, and no test reaches checkAndInstallClaude. Pre-existing: the original task explicitly excludes adding a checkAndInstallClaude test from this round.
+- **Kimi update routed through npm** — `src/cli/commands/update.ts` — updateAgent special-cases only Claude for the native installer, so a live-tracked Kimi update falls through to npm installGlobal. Pre-existing: the original task names "Kimi update via npm" as a pre-existing item deferred last round.