#17508 Agent Canvas update banner keeps showing 1.19.0 after npm install -g @openhands/agent-canvas@latest (installed package is 1.20.0)

Summary

After running npm install -g @openhands/agent-canvas@latest (and also after npx @openhands/agent-canvas@latest),the Agent Canvas UI keeps showing a "new version available" banner:

New version available - 1.20.0 - You're on 1.19.0. To update to 1.20.0, copy a command below, run it in your terminal, then restart Agent Canvas.

Meanwhile the machine reports:

npm view @openhands/agent-canvas version returns 1.20.0
npm list -g @openhands/agent-canvas shows @openhands/[email protected] under /opt/homebrew/lib

So the installed package is really 1.20.0, butthe UI still claims 1.19.0.

What I expected

After updating the package and restarting Agent Canvas,the version tile should not keep reporting 1.19.0 as the installed version.

Investigation / probable root causes

(Traced through the 1.20.0 npm tarball and the OpenHands repo at tag v1.20.0)

The version the UI shows is compile-time-embedded, not read from the installed package at runtime.
- src/api/client-source.ts sets AGENT_CANVAS_CLIENT_VERSION = packageJson.version.
- The published bundle inlines it into dist/package.js as a literal (version: "1.20.0").
- The static server serves prebuilt build/ assets from the installed package dir; nothing re-reads npm list/package.json at runtime. Hence the tile can only show the version of the bundle the running process was built from. Seeing 1.19.0 means a bundle/process built from 1.19.0 is still serving the UI you see.
npm install -g replaces files on disk but does not stop/restart a running agent-canvas process.
- If an old instance still listens on the default ingress port 8000 (agent-server/automation 18000/18001, static 3001),he newly invoked launcher's preflight assertPortsFree throws "Another agent-canvas instance may already be running" and exits. So the new instance never starts, and the URL you keep opening is the old server's UI. (Using PORT/OH_CANVAS_SAFE_*_PORT overrides would start a second stack instead, but users typically keep opening the old URL.)
- The banner in that old bundle correctly compares 1.19.0 against the npm registry latest dist-tag (currently 1.20.0),so it reports "update available" - the npm registry check is real and current; it is the installed-version label that is stale, from the old bundle.
Possible stale npx cache.
- npx @openhands/agent-canvas@latest launches from npm's npx cache (~/.npm/_npx/...). A previously cached older copy can be reused, so a "latest" invocation can keep launching an old build. Removing ~/.npm/_npx (or npx --force) forces a fresh install.

Side note: 1.20.1 (not causal here, butconfusing)

There is an open draft release-PR chore(main): release 1.20.1 (#17506, branch release-please--branches--main--components--agent-canvas), but 1.20.1 is not published on npm (dist-tags: latest is 1.20.0; npm view @openhands/[email protected] fails with ETARGET). Hence npm install -g @openhands/agent-canvas@latest cannot currently produce 1.20.1, even though the draft PR's release body mentions 1.20.1.

Steps to reproduce

Run Agent Canvas 1.19.0 on the default ports.
With it still running: npm install -g @openhands/agent-canvas@latest.
Re-invoke npx @openhands/agent-canvas@latest (or global agent-canvas): ifthe old process still holds port 8000,the launcher fails with "ports already in use"; if launched elsewhere,the UI you open keeps showing the old bundle's version.

Suggested workaround / fix candidates

User-side: fully stop the running instance (Ctrl+C; or lsof -i :8000 / pkill -f agent-canvas), then start the freshly installed binary, then hard-refresh the browser (and/or clear the site's data) -the tile should then read 1.20.0/up-to-date.

Product-side candidates:

Clarify the banner/launcher that an already-running process must be stopped before updating - e.g. have the launcher detect an existing instanceand print which version is running (agent-canvas --version, lsof -i :8000) alongside the "ports in use" error (which currently says "Another agent-canvas instance may already be running" but not which version).
Consider serving/reading the bundle version from package.json at boot (e.g. expose it via a /server_info/"bundle version" field) so a stale process is trivially distinguishable from an outdated install.

Environment

macOS with Homebrew-installed Node/npm (global prefix /opt/homebrew/lib)
npm view @openhands/agent-canvas version returns 1.20.0; dist-tags latest is 1.20.0
npm list -g @openhands/agent-canvas shows @openhands/[email protected]

This issue was created by an AI agent (OpenHands) on behalf of the reporter.