Add operator deployment commands to the OpenAgents CLI #12

Dependency

This work consumes the operator API specified in OpenAgentsInc/openagents.com#57. Do not bypass that API by automating /admin/forge, opening an SSH session, calling an internal RPC, or writing directly to the target table.

Problem

The OpenAgents CLI can send generic authenticated API requests, but it has no named deployment commands and its device login obtains only forge:write. An operator needs a safe, scriptable way to promote an exact commit and observe the result without using a browser for each deployment.

Commands

Add a deployment command group with this initial surface:

• openagents deploy promote creates an operator-approved Forge target.
• openagents deploy view <target-id> returns one target and its current state.
• openagents deploy list returns a bounded recent target history.

Support --json on every command. Add --wait to deploy promote and deploy view; it polls the status resource with bounded backoff until the target reaches live, failed, reverted, or needs_rolling_replace.

For production promotion, require all of these explicit inputs:

• --repo OpenAgentsInc/openagents.com or another canonical repository allowed by the server.
• --sha <full-40-character-sha>.
• --environment production.
• An idempotency key, generated once by the CLI and retained across automatic retries. Permit --idempotency-key for controlled automation.

Accept --expected-current-target <id> for compare-and-set promotion. Do not resolve branch names locally or silently promote the current working tree. The command may offer an explicit helper that prints the current full SHA, but production promotion must send the exact value the operator reviewed.

Authentication

Extend device login so an operator can request the deployments:promote scope defined by the server issue. For example:

openagents auth login --scope deployments:promote --profile production

The server remains authoritative for whether the signed-in account is an operator and may mint the scope. Store the returned credential through the existing profile credential mechanism. Never fall back to forge:write, a Git credential, browser cookies, or an environment-wide infrastructure token.

Show a specific remediation when the server returns an insufficient-scope or non-operator response. Redact bearer tokens and idempotency keys from normal output, debug logs, errors, shell completion, and telemetry.

Output and exit behavior

Human output should identify the environment, repository, full SHA, target ID, initial state, and status URL before reporting success. --json must preserve stable field names and include typed terminal outcome and failure code.

Use distinct nonzero exit codes for:

• Authentication or authorization failure.
• Invalid or unknown commit.
• Stale expected target or idempotency conflict.
• A terminal deployment failure or rollback.
• Poll timeout or transport failure while the target remains nonterminal.

A successful 202 Accepted without --wait means the promotion was accepted, not that production is live. Make that distinction explicit in both human and JSON output.

Handle SIGINT by stopping local polling without canceling or mutating the server-side target. Print the target ID so the operator can resume with deploy view.

Tests

Add command, authentication, retry, polling, and redaction tests that prove:

• Promotion sends the exact repository, SHA, environment, expected target, and stable idempotency key.
• Automatic retries reuse the same idempotency key.
• The command refuses abbreviated SHAs and missing production environment input before sending a request.
• --wait reaches every terminal state and reports the correct exit behavior.
• Transport timeouts do not claim that a deployment failed.
• SIGINT stops polling without sending a cancellation.
• Human and JSON output distinguish accepted, live, failed, reverted, and rolling-replacement-required states.
• Credentials and idempotency keys never appear in output or logs.
• A profile with only forge:write receives clear scope guidance and cannot promote.

Documentation

Document operator login, exact-SHA promotion, compare-and-set protection, idempotent retry, polling, CI use, credential revocation, and incident recovery. Include examples for interactive use and noninteractive release automation.

Acceptance criteria

• An authorized operator can promote and monitor a production target from a terminal without opening /admin/forge.
• The CLI uses only the public operator API from OpenAgentsInc/openagents.com#57.
• Ordinary forge:write credentials cannot run the command successfully.
• Scripts can rely on stable JSON and exit behavior.
• The CLI test and release checks pass.