fix(tool-server): prevent duplicate tool-servers after an nvm node switch

[filip131311]

Problem

Switching Node versions with nvm can leave two (or more) tool-server processes alive at once while ~/.argent/tool-server.json tracks only one. The extra servers are orphaned (untracked, on leaked ports) until their 30‑minute idle timeout.

This was reproduced live: a machine had three node …/dist/tool-server.cjs start processes running, all spawned within the same minute, with state tracking only the last one.

Root cause

@argent/tools-client ensureToolsServer() ran a non-atomic
read state → check alive+healthy → clearState → spawn → writeState sequence with:

1. No cross-process serialization. An nvm switch relaunches argent mcp under the new Node while the previous MCP's 30s health monitor reconnects — several launchers run ensureToolsServer() at nearly the same time, all observe "no healthy server", and each spawns its own detached server on a fresh free port. Last‑writer‑wins on the state file orphans the rest.
2. No kill-before-respawn. When the tracked server was alive but unhealthy, the old code just clearState()d and spawned a new one, leaving the old detached process running untracked.

Fix (packages/argent-tools-client/src/launcher.ts)

• O_EXCL spawn lock (~/.argent/tool-server.lock) serialises the spawn decision across processes: per-acquisition nonce, stale‑steal (dead holder / aged lock), bounded wait, and a hot‑spin‑proof reclaim loop. Inside the lock, ensureToolsServer double‑checks for a peer‑spawned healthy server before spawning, so a burst of concurrent launches collapses to a single server.
• Kill-before-respawn terminates a wedged server we own before spawning its replacement, with three guards so it can never signal the wrong process:
  • managed === "autospawn" — a user's argent server start server is now tagged managed: "cli" and is never killed by the auto‑spawn path;
  • a structural node <bundlePath> start command-line identity match (not a bare substring);
  • a re-check of that identity immediately before each signal (covers PID reuse across the SIGTERM grace window).
• spawnToolsServer reaps its detached child on every reject path, so a readiness timeout can no longer leak a child that binds its port moments later as an untracked second server.

The lock-free fast path (reuse a healthy tracked server) is unchanged, so steady‑state behaviour and latency are unaffected; the lock is only taken when a spawn is actually needed.

Tests

New packages/argent-tools-client/test/launcher-duplicate-spawn.test.ts:

• a 5× concurrent launch burst collapses to one server;
• an alive‑but‑unhealthy autospawn server is terminated (not orphaned) on respawn;
• a recycled pid whose command line doesn't match is never signalled;
• a managed: "cli" server is left alive instead of being killed;
• a readiness timeout reaps the spawned child (no orphan).

Each case was verified to fail against the pre-fix code and pass with the fix. Existing launcher-spawn / launcher-state suites are unchanged and green.

Note: the @swmansion/argent dispatcher › forwards SIGTERM to the child binary unit test is a pre-existing flake (alternates pass/fail independent of this change, which doesn't touch that package).

🤖 Generated with Claude Code