Dashboard spawner resolves wrong projectRoot when NVM's package.json exists in path

[lightstrike]

Description

When using agent-relay installed via the shell script on a system with NVM, the relay-dashboard-server's embedded AgentSpawner resolves projectRoot to ~/.nvm/ instead of the actual home directory. This causes spawned agents to fail with a socket connection timeout because the spawner polls for agent registration at the wrong path.

The root agent-relay daemon resolves paths correctly. The issue is isolated to the spawner embedded in relay-dashboard-server --integrated.

Steps to reproduce

1. Have NVM installed (which ships ~/.nvm/package.json)
2. Install agent-relay via the shell script (curl -fsSL ... | bash)
3. agent-relay up --dashboard
4. Spawn an agent from the dashboard (or via agent-relay spawn)

Expected behavior

Agent spawns and registers successfully.

Actual behavior

[dashboard] [client] Error: connect ENOENT /Users/<user>/.nvm/.agent-relay/relay.sock
[dashboard] [relay-pty-orchestrator] SIGKILL for cf-1:
  Memory: 242MB free / 32768MB total (99% used)

Agent is killed after 30s registration timeout.

Root cause

The daemon log shows two AgentSpawner instances initialized with different paths:

# Main daemon (correct)
[spawner] AgentSpawner paths: projectRoot=/Users/<user> teamDir=/Users/<user>/.agent-relay/team

# Dashboard's embedded spawner (wrong)
[spawner] AgentSpawner paths: projectRoot=/Users/<user>/.nvm teamDir=/Users/<user>/.nvm/.agent-relay/team

The dashboard server is started with the correct flags:

relay-dashboard-server --integrated --data-dir ~/.agent-relay --team-dir ~/.agent-relay/team --project-root /Users/<user>

But its embedded spawner ignores --project-root and does its own project root detection by walking up directories looking for a package.json. NVM ships with ~/.nvm/package.json, so the spawner latches onto ~/.nvm/ as the project root and derives all data paths from there.

The spawner then:

• Looks for the socket at ~/.nvm/.agent-relay/relay.sock (doesn't exist)
• Polls for agent registration at ~/.nvm/.agent-relay/team/connected-agents.json (wrong file)
• Times out after 30s and SIGKILLs the agent

Workaround

Symlink the paths so the wrong location resolves to the correct one:

ln -sf ~/.agent-relay/relay.sock ~/.nvm/.agent-relay/relay.sock
rm -rf ~/.nvm/.agent-relay/team
ln -sf ~/.agent-relay/team ~/.nvm/.agent-relay/team

Suggested fix

The dashboard server's embedded spawner should respect the --project-root / --data-dir flags passed on the command line rather than performing independent project root detection. Alternatively, the package.json walk could skip known tool directories like .nvm, .rbenv, .pyenv, etc.

Environment

• agent-relay v2.1.20
• macOS (Darwin 25.2.0, arm64)
• NVM 0.39.1 (with ~/.nvm/package.json present)
• Installed via shell script (~/.local/bin/agent-relay)

[khaliqgant]

Thanks for the detailed report! I also noticed this happening earlier today and have a fix in PR for it #379 and related AgentWorkforce/relay-dashboard#22

Wil do some additional testing and get this out!

[lightstrike]

Thanks! Really cool project, will continue exploring 🚢

[khaliqgant]

Hi @lightstrike I think this should be fixed but I had some trouble recreating it. If you have a moment would you mind upgrading and seeing if it is resolved?

curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash

^ to upgrade. Will leave the issue open in the mean time