Claude spawns can lose all Relay tools when cold npx MCP startup exceeds the connect timeout

[willwashburn]

Summary

Claude workers can finish spawning without any Agent Relay MCP tools when the broker's inline --mcp-config starts the server through a cold npx -y agent-relay mcp resolution. Package resolution can exceed Claude Code's approximately 30-second MCP connection timeout, leaving a session that looks alive in its PTY but cannot call send_dm, post_message, check_inbox, or any other Relay tool.

The worker can then communicate only with an operator attached to its PTY. This is a silent partial-start failure: process/session liveness is not Relay connectivity.

Observed failure

Khaliq reproduced this on his machine while running the chief repository at commit 99ffd56.

• Claude Code MCP logs: ~/Library/Caches/claude-cli-nodejs/-Users-khaliqgant-Projects-AgentWorkforce-chief/mcp-logs-agent-relay/
• A cold npx package resolution exceeded Claude Code's MCP connect window.
• The Claude session remained available, but it had no mcp__agent-relay__* tools.

The referenced log directory is on Khaliq's machine and is recorded here as the source evidence; it was not copied into this issue or re-run on the filing machine.

Current Relay implementation

Verified on origin/main at 56776839f9800e6455172dd3536be5cea073203d:

• crates/broker/src/snippets.rs:31-52 defaults the MCP command to:

  npx -y agent-relay mcp
  

• crates/broker/src/snippets.rs:828-850 places that command in Claude's generated inline --mcp-config.

• Tests currently pin the npx default, so this behavior is intentional rather than an environment accident.

• AGENT_RELAY_MCP_COMMAND can override the command, but normal spawned sessions do not receive an installed-binary default.

Fix direction

Prefer a deterministic already-installed Relay executable for spawned MCP servers, such as the fleet installation under ~/.agentworkforce/relay/bin/agent-relay or a resolved agent-relay on PATH, instead of paying package-manager/network resolution cost on every spawn.

If Claude Code exposes a configurable MCP connection timeout, increasing it can be defense in depth, but it should not be the only fix: cold network/package resolution remains variable and a timed-out MCP server must not be reported as a healthy Relay-capable session.

Server-name / allowlist check

The same pass should settle the canonical settings-allowlist name:

• Relay's canonical MCP server key is currently agent-relay (AGENT_RELAY_MCP_SERVER).
• relaycast is retained as a legacy server-name alias for migration/detection.
• Current Claude injection guidance and tests use decorated names such as mcp__agent-relay__send_dm.
• Some older repository guidance still uses mcp__relaycast__*.

Confirm Claude Code's actual allowlist syntax for a server key containing a hyphen, then update settings, tests, and durable guidance consistently. Do not infer the allowlist name only from an MCP config key or from prose.

Acceptance criteria

• Claude spawn MCP configuration uses a deterministic installed Relay binary without cold npx resolution in the normal fleet path.
• Binary resolution has an explicit order and a loud failure when no usable installed binary exists.
• A spawned session is not reported as Relay-ready when the Agent Relay MCP server failed to connect; the operator receives an actionable error.
• Tests cover a cold/slow package-resolution scenario exceeding 30 seconds and prove the installed-binary path still exposes Relay tools.
• An end-to-end Claude spawn verifies send_dm, post_message, and check_inbox are registered and callable before the worker is treated as ready.
• The canonical Claude settings-allowlist spelling is verified against live tool registration and encoded in tests/docs; legacy mcp__relaycast__* references are either migrated or explicitly justified.
• No workspace keys, API keys, or agent tokens are written into test output or failure diagnostics.

Out of scope

• Changing the credentials injected into --mcp-config.
• The separate --mcp-config argv-to-file hardening tracked in Live credentials exposed on process argv, in plaintext logs/stdout, and in unredacted JSON output #1379.