`ax auth whoami` returns misleading "not found" inside a `claude_code_channel` workspace

[andrewprograde]

Summary

ax auth whoami run from inside a workspace bound to a claude_code_channel agent fails with a confusing error:

Error: Invalid value: Gateway local connect failed: not found

The agent itself is healthy — ax gateway agents list shows the row as LIVE. The user has done nothing wrong; the CLI is just routing identity verification down a path that doesn't apply to live-listener agents.

Repro

1. ax gateway login and ax gateway start.
2. Register a Claude Code Channel agent:

   ax gateway agents add cc_andrew \
     --template claude_code_channel \
     --workdir ~/agents/cc-andrew

3. Run setup so the workspace gets .ax/config.toml:

   ax channel setup cc_andrew --workdir ~/agents/cc-andrew

4. Inside the workspace:

   cd ~/agents/cc-andrew
   ax auth whoami

Result:

Error: Invalid value: Gateway local connect failed: not found

ax gateway agents list confirms the agent is registered and LIVE.

Root cause

ax_cli/commands/auth.py:336-340 routes whoami through _gateway_local_call when a project-local gateway config is present. That helper calls _gateway_local_connect (ax_cli/commands/messages.py:23), which POSTs to Gateway's /local/connect endpoint.

The /local/connect handler is _connect_local_pass_through_agent in ax_cli/commands/gateway.py:328-345. It is gated to pass_through template agents:

if entry is not None and str(entry.get("template_id") or "").strip() not in {"", "pass_through"}:
    raise ValueError("registry_ref_not_attachable")

For a claude_code_channel (or any non-pass-through) registry row, the lookup also fails earlier with LookupError("Gateway registry agent not found: …") because find_agent_entry_by_ref doesn't resolve channel rows by name in the same way. That not found string is what surfaces to the user, suggesting the agent doesn't exist when in fact it just isn't reachable through the pass-through connect path.

Why this matters

whoami is the canonical "did I bind correctly?" check the README and walkthroughs point users at. Hitting a not found error inside a freshly-set-up Claude Code Channel workspace makes users think the registration failed, when the registration is in fact correct.

Suggested fix

Two options, not mutually exclusive:

1. Make whoami aware of non-pass-through Gateway-managed identities. When the local .ax/config.toml references a registered claude_code_channel (or any live-listener template), resolve identity directly from the registry row instead of via /local/connect. The output should match what ax gateway agents show <name> already returns.
2. Improve the error message. If /local/connect is the only path attempted and the registry row exists but is not pass-through, surface that explicitly:

   Error: @cc_andrew is a claude_code_channel agent. Identity is bound at launch time
   via .mcp.json — `whoami` is not applicable for live-listener agents. Use
   `ax gateway agents show cc_andrew` to inspect identity.
   

   instead of the generic Gateway local connect failed: not found.

Option 1 is the right long-term fix; option 2 is a low-cost bandage that would have unblocked the affected user immediately.

Related

Follows up on #149 (README documents echo template id but registry uses echo_test). Both surfaced during a fresh-clone walkthrough.