fix(cli): stop argent mcp --help starting the server, and argent tools --help dumping the catalogue

[filip131311]

Fixes #638.

The report understated it

The issue says argent mcp --help "does not hang and does not start the server — it simply prints
nothing". Reproducing it showed the opposite:

$ argent mcp --help < /dev/null ; echo $?
0                          # 0 bytes  ← what the reporter saw
$ argent mcp --help        # stdin open (a pipe, an editor, a CI step)
                           # HANGS — I hit a 300s timeout

--help starts the MCP stdio server, which blocks reading JSON-RPC from stdin. The "prints
nothing, exit 0" is just the server getting an immediate EOF from a closed stdin. So this is the same
"--help runs the real command" bug that was fixed for the installers — mcp was missed.

startMcpServer takes no argv at all (mcp-server.ts:96 — its only parameter is { paths }), so a
help flag was structurally unreachable; there was nowhere downstream that could have handled it.

Fix

mcp joins the existing guarded set rather than growing a second help path. That set's defining
property is "the handler never inspects its argv", and mcp qualifies more strongly than the
installers do — it isn't merely ignoring rest, it is never handed it.

It cannot fire on a real launch. The guard tests rest, which is [] for every generated editor
config (all four shapes end at mcp, and isArgentManagedEntry requires exactly that), and
[].some(...) evaluates no predicate. This is pinned in both directions, because a guard that did
fire here would print usage onto the JSON-RPC channel and break every editor at handshake — the
highest-cost regression in this file, and it was untested.

The top-level table's mcp row now reads the same metadata as its own help, so the two cannot drift.

No rename. An earlier draft renamed the module and six identifiers (installer-help →
command-help, etc.) on the grounds that its comments had become false. They hadn't quite: fixing
mcp and tools makes "every other subcommand parses --help itself" true again — I checked all
ten siblings. Since #530 and #568 both edit cli.ts, a rename would have forced them through churn
for no behavioural gain. Prose-only.

Second commit: argent tools --help

The issue mentions it in passing; it's a different mechanism and a genuinely dead branch.
argv.filter((a) => !a.startsWith("--")) dropped --help before the subcommand was read, so it fell
through to listing all 77 tools — contacting the tool-server, starting one if none was running,
to do it. Only -h ever reached the existing help branch.

Scoped to the subcommand position on purpose: a global check would have broken
argent tools describe <name> --help, which today prints that tool's flags. It still does — there
is a test.

Separate commit so it can be reverted alone.

Verification

Live, against the built CLI:

	before	after
mcp --help, stdin open	hangs indefinitely	usage, returns immediately
mcp --help, stdin closed	0 bytes, exit 0	849 bytes of help, exit 0
mcp (real launch)	works	works — verified with an actual initialize handshake, server replies with its capabilities
mcp --metro-port 8082	starts server	starts server (guard keys on help, not on "any argv")
tools --help	77-line catalogue	usage
tools describe gesture-tap --help	tool's flags	tool's flags
argent --help mcp row	—	byte-identical

argent 80 passed, argent-cli 284 passed.

Note on the help text

Every claim in it is sourced (stdio/JSON-RPC transport, stdout ownership, the ~/.argent/mcp-calls.log
default and ARGENT_MCP_LOG override, auto-spawn vs ARGENT_TOOLS_URL/argent link). It deliberately
does not suggest running argent mcp by hand to check an install — that is the reported hang — and
instead says it will look like it has hung and why.

🤖 Generated with Claude Code