Implement P6 CLI commands for backend-unblocked APIs

[mrgoonie]

Summary

Implement the remaining GoClaw CLI P6 command surfaces now unblocked by backend PRs in digitopvn/goclaw.

Backend APIs are no longer speculative for this issue. The CLI should consume the existing HTTP contracts, add focused tests, and avoid command stubs for APIs that still do not exist.

Backend evidence

Released backend APIs from PR #37:

• digitopvn/goclaw#37
• Merge commit: 56e227c4030e85163cd882b29ab472f8ce3e1a27
• Known beta containing these APIs: v3.12.0-beta.16
• Endpoints:
  • GET /v1/traces/follow
  • POST /v1/providers/{id}/reconnect

Merged backend APIs from PR #44:

• digitopvn/goclaw#44
• Merge commit: 43049d3b3fbb5f457477118252d1f21fdc0480de
• Endpoints:
  • POST /v1/chat/sessions/{key}/branch
  • GET /v1/chat/sessions/{key}/history/follow
  • POST /v1/channels/instances/{id}/writers/test
  • GET /v1/activity/aggregate
  • GET /v1/logs/runtime/aggregate

Before live smoke, verify which beta tag contains 43049d3b. At the time the local implementation prompt was written, v3.12.0-beta.18 existed but PR #44 beta publishing was still in progress.

Local implementation prompt:

• plans/reports/codex-prompt-260522-p6-pr44-backend-unblocked-cli.md

Proposed CLI scope

Add or map these commands:

goclaw traces follow --session-key <key> [--since <RFC3339>] [--limit N] [--include-spans] [--status <status>] [--channel <channel>]
goclaw traces follow --agent <uuid-or-key> [same flags]

goclaw providers reconnect <provider-id>

goclaw sessions branch <session-key> --up-to-index <n> [--new-session-key <key>] [--label <label>] [--metadata k=v]...
goclaw sessions follow <session-key> [--cursor <n>] [--limit <n>]

goclaw channels writers test <instance-id> --group-id <group-scope> --user-id <user-id>

goclaw activity aggregate --group-by <action|actor_type|entity_type|actor_id> [filters]

goclaw logs aggregate [--group-by <level|source>] [--level <level>] [--source <source>] [--from <RFC3339>]

All commands should support the repo's existing output modes where applicable: table, JSON, YAML.

Expected implementation path

flowchart TD
    A[Verify backend beta / dev contracts] --> B[Create clean CLI branch or worktree]
    B --> C[Add failing command tests]
    C --> D[Implement Cobra commands using existing HTTP client]
    D --> E[Run go test, go vet, go build]
    E --> F[Red-team diff for path/body/output regressions]
    F --> G[Open PR]

Loading

Acceptance criteria

• traces follow calls GET /v1/traces/follow and requires exactly one target: --session-key or --agent.
• providers reconnect calls POST /v1/providers/{id}/reconnect with no request body by default and no --verify flag.
• sessions branch calls POST /v1/chat/sessions/{key}/branch, requires --up-to-index, validates metadata as key=value, and path-escapes session keys.
• sessions follow calls GET /v1/chat/sessions/{key}/history/follow, validates cursor/limit, and performs one polling request only.
• channels writers test calls POST /v1/channels/instances/{id}/writers/test with only group_id and user_id in the body.
• activity aggregate calls GET /v1/activity/aggregate, validates --group-by, RFC3339 ranges, and preserves response buckets in JSON/YAML.
• logs aggregate calls GET /v1/logs/runtime/aggregate and is clearly separate from logs tail.
• Focused tests cover request path, query params, request body, validation-before-HTTP, and JSON/table output preservation.
• Validation passes:
  • go test ./...
  • go vet ./...
  • go build ./...
• README/help text is updated if command inventory docs are expected to stay current.

Explicitly out of scope

Do not add commands, stubs, hidden flags, or docs for APIs that still do not exist:

• POST /v1/traces/{id}/replay
• generic GET /v1/logs/aggregate
• WebSocket chat.history.delta
• SSE chat history follow
• long-running watch loops for traces follow or sessions follow

Implementation notes

• Current local checkout may be on feat/claude-skill-v0.1 and may contain unrelated untracked files such as .claude/ and AGENTS.md; use a clean branch/worktree and do not stage unrelated files.
• Reuse existing command patterns in:
  • cmd/traces.go
  • cmd/providers.go
  • cmd/providers_crud.go
  • cmd/sessions.go
  • cmd/channels_writers.go
  • cmd/admin_activity.go
  • cmd/logs.go
  • cmd/helpers.go
  • internal/client/http.go
  • internal/output/output.go
• If any equivalent command already exists, preserve it and document the mapping instead of creating duplicate command names.

Unresolved questions

• Which beta tag ultimately contains backend commit 43049d3b? Verify before live smoke testing.
• Should command inventory in README be updated in the same PR or a follow-up docs PR if the implementation diff becomes large?