feat(cli): context-aware agent spawn with agent catalog and auth preflight

[nikhilachale]

---

Summary

This branch adds a CLI-facing agent catalog command and makes ao spawn more context-aware for direct shell usage. The main goal is to let users start worker sessions without always passing every low-level flag, while still keeping the CLI thin and daemon-backed.

What Changed

Added ao agent ls

New command:

ao agent ls
ao agent ls --refresh
ao agent ls --json

Behavior:

• ao agent ls calls GET /api/v1/agents.
• ao agent ls --refresh calls POST /api/v1/agents/refresh.
• ao agent ls --json prints the raw agent inventory response.
• Table output shows supported agents with install/auth status:
  • authorized
  • auth unknown
  • needs auth
  • needs install

No new backend API was added — this reuses the existing agent catalog endpoints.

Made ao spawn context-aware

ao spawn no longer requires --project, --agent, and --name in every direct CLI invocation.

Supported paths now include:

ao spawn --prompt "Fix failing tests"
ao spawn --agent codex --prompt "Fix failing tests"

Project resolution order:

1. Explicit --project
2. AO_PROJECT_ID
3. Current working directory matched against registered project paths
4. Otherwise, returns a helpful setup error

Agent resolution order:

1. Explicit --agent / --harness
2. Resolved project config worker.agent
3. Otherwise, returns a helpful config error

Display name behavior:

• Explicit --name still works and is still capped at 20 characters.
• If --name is omitted, the CLI derives a short display name from --prompt.
• If neither name nor prompt gives a name, the CLI omits displayName and lets the API/UI fall back to session id.

Added spawn auth preflight

Before calling POST /api/v1/sessions, ao spawn now checks the agent catalog:

State	Behavior
Cached catalog shows authorized	Spawn proceeds without refresh
Cached catalog can't confirm auth	Refreshes catalog once
Refreshed status is unauthorized	Spawn blocked with a clear auth error
Auth remains unknown after refresh	CLI warns and proceeds

Spawn remains the final authority for runtime/binary/model failures.

Updated docs

Updated CLI documentation to cover:

• ao agent ls, ao agent ls --refresh, ao agent ls --json
• Direct shell usage requirements
• Daemon requirement for product commands
• Source checkout build/run example
• ao spawn project resolution behavior
• ao spawn default worker.agent behavior
• Auth preflight behavior

The root README now links to the CLI guide instead of duplicating detailed command instructions.

Files Changed

Main implementation:

• backend/internal/cli/agent.go
• backend/internal/cli/root.go
• backend/internal/cli/spawn.go

Tests:

• backend/internal/cli/agent_test.go
• backend/internal/cli/spawn_test.go
• backend/internal/cli/dto_drift_e2e_test.go

Docs:

• README.md
• docs/cli/README.md

Testing

Passed:

npm run lint
npm run frontend:typecheck

Manually verified with the local built binary:

cd backend
./bin/ao agent ls
./bin/ao agent ls --refresh
./bin/ao agent ls --json

Notes

• No backend API changes were needed.
• No OpenAPI regeneration was needed.
• The CLI remains a thin client over daemon HTTP routes.
• An unrelated generated frontend route tree change was removed from the branch diff.

---