# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What to Tell Your User

If your agent's CLI was installed through nvm, the agent can now find and launch it
reliably even when it's running as a background service. This fixes a case where a
session would fail to start because the program couldn't be located. It only adds
places to look, so agents that already worked are unaffected. Nothing to configure.

## Summary of New Capabilities

- `detectFrameworkBinary` scans `~/.nvm/versions/node/<version>/bin/<name>` (running
  version first, then any installed version) after the existing checks — so a CLI
  installed only under nvm is found even when the server runs under launchd with
  `NVM_BIN` unset and the nvm bin dir off the PATH.

## Evidence

- Verified live in the affected machine's server environment: the binary detector
  returned null, NVM_BIN was unset, and the PATH had no nvm directory — so a spawned
  session died at startup with no CLI to run.
- Unit, `tests/unit/detectFrameworkBinary.test.ts`: with HOME pointed at a temp nvm
  layout and NVM_BIN deleted, detection resolves the binary; plus a source guard that
  the detector scans the nvm version dirs.
- 24 detection + loadConfig tests pass; tsc --noEmit clean.
- Spec, `docs/specs/detect-framework-binary-nvm.md` plus the .eli16.md sibling.
- Side-effects, `upgrades/side-effects/detect-framework-binary-nvm.md`.

## What Changed — the agent now finds its CLI when it's installed via nvm

Another step toward making the multi-machine "move this conversation to my other
machine" feature work, and a general robustness fix for any agent installed through
nvm (Node Version Manager). To start a session, the agent has to find its CLI binary
(like the Claude or Codex command) on disk. The finder checked the usual locations
but missed binaries that nvm installs under its own version folders — because the
background server is launched by the operating system, which does not load nvm's
shell setup, so that folder is off the PATH and nvm's location hint is unset.

The finder now also looks directly inside the nvm version folders (preferring the
running version), exactly like it already does for the asdf tool manager, and for the
same reason. On the machine where this surfaced, a session spawn was crashing
instantly because the CLI couldn't be found; now it resolves.
