cli: axctl bootstrap-agent — one-shot scoped agent setup

[madtank]

Summary

Collapses the 15-step manual sequence we hit bootstrapping @axolotl yesterday into a single command. Closes friction items §0, §2, §3, and §4 from shared/state/axctl-friction-2026-04-17.md.

axctl bootstrap-agent axolotl \
  --space-id ed81ae98-50cb-4268-b986-1b9fe76df742 \
  --description "Playful ax-cli helper" \
  --model codex:gpt-5.4 \
  --audience both \
  --save-to /home/ax-agent/agents/axolotl \
  --profile next-axolotl

What's hidden inside

1. User-PAT gate. Agent PATs (axp_a_) are refused with a clear message; the command explains you need axp_u_ to create agents.
2. Effective-config line. Prints base_url= user_env= source= as the first line — kills the .active silent-override footgun for good.
3. Space-aware creation. POST /api/v1/agents with X-Space-Id, not the legacy /agents in the caller's default space. This is the only path that actually survives the prod ALB.
4. Idempotent. If the agent already exists in the target space, exits 2 unless --allow-existing is set.
5. Metadata polish. Optional --bio, --specialization, --system-prompt via the proxied PUT /api/v1/agents/manage/{name}.
6. PAT minting with automatic fallback. Tries /credentials/agent-pat first (canonical per the ax-operator skill). On HTML / 404 / 405 it transparently falls back to POST /api/v1/keys with bound_agent_id, allowed_agent_ids, audience, and the correct prod scope vocabulary (api:read, api:write). User sees Minted via mgmt or Minted via keys_fallback so operators know which path worked.
7. Workspace scaffold. {save_to}/.ax/config.toml + .ax/token at 0600. Optional named profile compatible with axctl profile verify.
8. Post-mint verification. GET /auth/me with the fresh PAT and prints allowed_spaces so the caller immediately sees that containment landed (agent-lock + space-lock).

Test plan

• uv run pytest tests/test_bootstrap_agent.py -v → 9 passed (all new)
• uv run pytest tests/ → 230 passed (no regressions)
• uv run ruff check + ruff format --check → clean
• Smoke test on dev: axctl bootstrap-agent smoke-$(date +%s) --space-id <dev-space> --save-to /tmp/smoke → full flow, verify .ax/token + whoami shows space-lock.
• Smoke test on prod: same, in ax-cli-dev space — should use keys_fallback path since /credentials/* isn't proxied.
• --dry-run prints plan without calling the API (covered by unit test, should also be visually verified).
• --allow-existing reuses an existing agent and mints a fresh PAT (covered by unit test).

What's intentionally NOT in this PR

• Delete-on-failure / rollback. If PAT minting fails after agent creation, the agent remains. Keeping it manual for now — axctl agents delete <name> works.
• Bulk --from-file <yaml>. The one-shot works for one-shot. Bulk provisioning is future scope.
• Avatar at create time. We ship the separate --avatar-file flag on agents update in PR agents: avatar-day bundle — set via PUT, --avatar-url/-file, config line #65; users can follow-up with that command for now.

🤖 Generated with Claude Code