coding cli updates

Coding CLI updates

AgentWorks uses the user's single globally installed coding CLI for every chat. It does not install private copies, select release directories, or pin a CLI version per chat.

The backend checks Codex, Claude Code, Cursor Agent, and Pi on startup when due, then on an hourly background timer. It invokes each installed CLI's official update command:

• codex update
• claude update
• cursor-agent update (with agent accepted as the executable name)
• pi update --self

After updating, AgentWorks resolves the executable from the normal process PATH again and verifies it with --version. PI_BIN, when supplied, must be an absolute executable path and is updated in place. Muse remains probe-only because its launcher already performs its own background updates.

After a successful update AgentWorks keeps one release per CLI. Cursor Agent's updater (and Claude Code's native installer) download each release beside the previous ones under ~/.local/share/<cli>/versions/ and never delete them (Cursor is ~0.5 GB per release). The updater removes every release there except the one the verified executable resolves to, and skips any release a running process still uses; that one goes on a later check. Only those two exact stores are pruned: npm-global installs update in place, and other "versions" directories (e.g. nvm's) are never touched.

An uninstalled CLI is recorded as not_installed; AgentWorks does not install it. A successful check is due again after 24 hours. A failure is retried after one hour without rerunning providers that are not due. Each attempt has a 15-minute timeout, and cancellation terminates its subprocess group.

Deployment provisioning

Every server deployment (rootless products, RTS and Dominion) uses deploy/common/install-coding-clis.sh to install or update Claude Code, Codex, Cursor Agent, Pi, Muse and AGY. It requests current official releases and checks that every managed executable launches with --version before the release can activate. Missing binaries are installed; existing binaries are updated. The backend updater above handles checks between deployments. Provider menus retain all offered CLIs and report authentication/runtime readiness. AGY has no separate local-only visibility gate.

State and migration

The durable, atomically written state.json lives in:

• $AGENTWORKS_STATE_ROOT/cli-updates/state.json when an absolute instance state root is supplied.
• Otherwise, Go's user config directory under agentworks/cli-updates/state.json (normally ~/Library/Application Support/agentworks/cli-updates/state.json on macOS and ${XDG_CONFIG_HOME:-~/.config}/agentworks/cli-updates/state.json on Linux).

The state records each executable's status, version, resolved absolute path, last attempt, last success, next check, and any error. An OS file lock serializes backend processes sharing the root. Invalid JSON is preserved rather than reset.

On the first enabled check after upgrading from the private-release design, AgentWorks removes its retired bin, current, releases, and sessions directories. Only state.json and update.lock remain. It also clears the old AGENTWORKS_MANAGED_CLI_BIN process override and removes that retired directory from the backend's PATH before agents can launch.

CLI_UPDATE_ENABLED=false disables update checks. CLI_UPDATE_DRY_RUN=true also disables updates. Neither setting changes which executable agents launch: all launches use the global CLI resolved by the existing adapter and shell environment.

Security and verification

The updater receives the user's real home and XDG paths because official self-updaters must modify the global installation. Workflow and provider secrets are omitted from its environment; locale, proxy, and CA settings are retained. Command output is not included in errors because proxy URLs can contain secrets.

Offline regression coverage uses fake global executables and never modifies a real installed CLI:

go -C agent_go test -race ./internal/cliupdate
bash scripts/test-local-instance.sh

The focused tests cover scheduling, restart persistence, retry isolation, lock contention, official command arguments, environment filtering, PI_BIN, Cursor's agent alias, process cancellation, Muse's probe-only policy, and removal of the retired private layout.