feat(cli): add provider capacity command

docs/ai/design/2026-08-09-feature-capacity-command.md

@@ -0,0 +1,53 @@
+---
+phase: design
+title: Capacity Command Design
+description: Thin CLI over a Codex capacity model owned by agent-manager
+---
+
+# Capacity Command Design
+
+## Architecture
+
+```mermaid
+flowchart LR
+  CLI[CLI registration and validation] --> Manager[agent-manager getCodexCapacityReport]
+  Manager --> Detect[Codex config and PATH detection]
+  Manager --> Probe[PAT then OAuth then read-only app-server]
+  Probe --> Normalize[CapacityReport v1]
+  Normalize --> Render[CLI text or JSON rendering]
+```
+
+`packages/agent-manager/src/capacity/` is the domain boundary. `types.ts` defines normalized output, `codex.ts` owns credential-safe probing and mapping, and `index.ts` detects Codex, calls the probe once, redacts unexpected failures, and builds the report. The root package export exposes the report function and types.
+
+`packages/cli/src/commands/capacity.ts` registers `capacity [provider]`, validates that an explicit provider is `codex`, calls agent-manager, and delegates rendering. `capacity/render.ts` contains presentation only.
+
+## Fresh Probe Flow
+
+Each invocation checks `~/.codex` and PATH, then probes once. No filesystem cache, freshness key, TTL, bypass option, multi-provider selection, parallel grouping, or orchestration timeout exists.
+
+The Codex probe remains tiered:
+
+1. Resolve `CODEX_HOME/auth.json`, falling back to `~/.codex/auth.json`.
+2. If a PAT exists, use `whoami` then the usage endpoint.
+3. Otherwise use a fresh OAuth token and stored account ID.
+4. On missing, stale, unauthorized, or failed credentials, run `codex -s read-only -a untrusted app-server` and call only `account/rateLimits/read` and `account/read`.
+
+Network and app-server calls remain bounded inside the probe. Results are normalized into schema v1; raw inputs and exceptions are never returned.
+
+## Simplification Decisions
+
+| Opportunity | Decision | Reason |
+|---|---|---|
+| Remove normalized cache and cache tests | Acted | Every run must be fresh; TTL, permissions, keying, atomic writes, and bypass paths no longer serve behavior. |
+| Remove `--max-age` and `--refresh` | Acted | They only controlled the removed cache. |
+| Remove Claude, Pi, GLM, and generic stubs/tests | Acted | Codex is the only supported capacity provider. |
+| Replace provider registry and configured-provider scan | Acted | A direct Codex config/PATH check is clearer than generic mappings for one provider. |
+| Remove parallel orchestration, provider arrays, sorting, and outer timeout | Acted | One probe has no concurrency or partial-result problem; probe boundaries already time out. |
+| Move model/probe/types into agent-manager | Acted | Capacity informs agent dispatch and is reusable independently of CLI presentation. |
+| Flatten the report to the minimal JSON shape (provider, generatedAt, authenticated, available, windows, creditsRemaining) | Acted | Owner decision before merge: the unmerged contract carried multi-provider-era fields (schemaVersion, providers[], status, configured, installed, agentType, plan, checkedAt, source, aliases, resetCredits wrapper, usage snapshot, warnings, error) with no current consumer; fields can return when a second provider lands. |
+| Drop derived fields (`remainingPercent`, aliases) and the credit-limit fallback chain | Acted | Derivable from `usedPercent`/`durationMinutes` by consumers; the chain fed only removed output fields. |
+| Collapse PAT, OAuth, and CLI probing to app-server only | Rejected | The fallbacks have distinct availability/authentication value and preserve credential-safe behavior. |
+| Merge renderer into command | Rejected | Rendering has separate behavior and tests; keeping it isolated makes the CLI flow linear. |
+| Add a new package dependency/helper library | Rejected | Node APIs and the existing agent-manager dependency are sufficient. |
+
+All acted changes pass the readability guide's Reading Test: the command path is linear, names are explicit, functions stay at one abstraction level, and no speculative abstraction remains.

docs/ai/implementation/2026-08-09-feature-capacity-command.md

@@ -0,0 +1,52 @@
+---
+phase: implementation
+title: Capacity Command Implementation Record
+description: Codex-only capacity model and thin CLI integration
+---
+
+# Capacity Command Implementation Record
+
+## Module Map
+
+```text
+packages/agent-manager/src/
+├── capacity/
+│   ├── index.ts       # detection, one fresh probe, report construction
+│   ├── codex.ts       # PAT/OAuth/app-server probing and normalization
+│   └── types.ts       # capacity report model
+└── __tests__/capacity/
+    ├── index.test.ts
+    └── codex.test.ts
+
+packages/cli/src/commands/
+├── capacity.ts        # Commander registration, provider validation, manager call
+└── capacity/render.ts # human and JSON presentation
+```
+
+Agent-manager's root `index.ts` exports `getCodexCapacityReport` and the public capacity types. No package dependency was added because the CLI already depends on `@ai-devkit/agent-manager`.
+
+## Runtime Behavior
+
+`capacity` and `capacity codex` are equivalent. An explicit provider is normalized to lowercase and must be `codex`. The report function checks installation, invokes the Codex probe on every call, catches unexpected probe failures into a fixed unknown result, and returns one flat report: provider, generatedAt, authenticated, available, native windows, creditsRemaining.
+
+The retained Codex implementation validates normalized identifiers and labels, preserves arbitrary windows, keeps unknown values null, and keeps the PAT → fresh OAuth → hardened app-server sequence. It does not refresh tokens or invoke a model method.
+
+## Removed Implementation
+
+- `capacity/cache.ts` and its cache test.
+- `capacity/detection.ts` generic environment discovery and its test.
+- `capacity/orchestrate.ts` provider selection, grouping, sorting, caching, dependency graph, and its tests.
+- Claude, Pi/GLM, and unsupported stub providers plus provider tests.
+- CLI max-age parsing and refresh forwarding.
+
+## Simplification Review
+
+The complete opportunity ledger is in the design document. Acted changes remove unused feature surface and abstractions. Rejected changes retain the stable JSON contract, meaningful tiered probing, normalized usage details, and isolated rendering because deleting them would reduce behavior or clarity rather than complexity.
+
+## Security Invariants
+
+- Only normalized allowlisted data crosses the agent-manager boundary.
+- PATs, access/refresh tokens, account IDs, headers, bodies, stderr, and raw exceptions are not emitted.
+- The CLI fallback uses read-only/untrusted app-server flags and account-only methods.
+- Missing or failed data remains unknown; reset credits are never redeemed.
+- Every run is read-only and fresh, with no AI DevKit capacity cache writes.

docs/ai/planning/2026-08-09-feature-capacity-command.md

@@ -0,0 +1,38 @@
+---
+phase: planning
+title: Capacity Command Simplification Plan
+description: Completed plan for a fresh Codex-only capacity command
+---
+
+# Capacity Command Simplification Plan
+
+## Completed Tasks
+
+- [x] Remove cache implementation, cache tests, cache calls, `--max-age`, and `--refresh`.
+- [x] Remove Claude, Pi, GLM, unsupported-provider adapters, and their tests.
+- [x] Replace generic provider detection and multi-provider orchestration with one fresh Codex report function.
+- [x] Move Codex probing, normalization, types, and report construction to `@ai-devkit/agent-manager` using `src/capacity/` and `src/__tests__/capacity/` conventions.
+- [x] Export the capacity API and types from agent-manager's root entry point.
+- [x] Reduce CLI integration to registration, Codex argument validation, one agent-manager call, and rendering.
+- [x] Relocate behavioral tests to the owning workspace and remove tests whose only behavior was deleted.
+- [x] Update CLI README and all 2026-08-09 lifecycle documents.
+
+## Order and Dependencies
+
+1. Preserve the normalized contract while moving it and the Codex probe.
+2. Add the agent-manager report boundary and tests.
+3. Switch the CLI to that boundary.
+4. Delete superseded provider/cache/orchestration modules and tests.
+5. Update lifecycle records, then run build and test validation.
+
+## Risk Controls
+
+- Root agent-manager exports preserve one supported import path.
+- Probe exceptions become fixed normalized failures; raw provider details remain redacted.
+- Existing mocked PAT/OAuth/app-server tests move with the domain code.
+- Commander tests prove non-Codex rejection and the absence of cache-option forwarding.
+- Full workspace build/tests catch package-boundary and declaration-generation errors.
+
+## Deferred Scope
+
+Future providers should be added only with a verified, read-only capacity mechanism and a concrete product requirement. Do not restore generic provider scaffolding or caching speculatively.

docs/ai/requirements/2026-08-09-feature-capacity-command.md

@@ -0,0 +1,46 @@
+---
+phase: requirements
+title: Capacity Command Requirements
+description: Define fresh, read-only Codex capacity reporting
+---
+
+# Capacity Command Requirements
+
+## Problem
+
+Codex users need a factual capacity report before dispatching work. The command must obtain current data without starting a model turn, exposing credentials, or carrying provider and cache machinery that has no supported use.
+
+## Command Surface
+
+```text
+ai-devkit capacity
+ai-devkit capacity codex
+ai-devkit capacity [codex] --json
+```
+
+The optional provider argument exists for discoverability and accepts only `codex`, case-insensitively. Any other value fails before probing. Every invocation probes fresh; there is no cache, `--max-age`, or `--refresh` option.
+
+## Acceptance Criteria
+
+- Capacity supports Codex only and always emits exactly one Codex row.
+- `@ai-devkit/agent-manager` owns probing, normalization, detection, and public capacity types.
+- The CLI owns only command registration, provider validation, the agent-manager call, and text/JSON rendering.
+- JSON reports the provider, generation time, authentication, availability, native usage windows (`id`, `label`, `durationMinutes`, `usedPercent`, `resetsAt`), and remaining credits in one flat object. Derived values and provider-internals are omitted; fields may be added when a second provider lands.
+- Codex configuration and executable presence are reported independently.
+- Probing prefers PAT, then fresh OAuth, then the hardened read-only Codex app-server fallback.
+- Missing data is `unknown`, never inferred as available; explicit exhaustion may report `no`.
+- Probing never starts a model turn, refreshes credentials, writes provider data, or exposes secrets/raw failures.
+- Existing meaningful normalization, fallback, redaction, rendering, and command-contract tests remain covered in their owning packages.
+
+## Non-Goals
+
+- Claude, Pi, GLM, generic provider stubs, or future-provider scaffolding.
+- Cross-provider selection, parallel orchestration, partial multi-provider results, or scheduling policy.
+- Cached or historical capacity, forecasting, cost prediction, token-history estimation, or reset-credit redemption.
+- OAuth refresh, TUI scraping, or inference-based probes.
+
+## Constraints
+
+- Keep the schema stable where it still describes Codex truthfully.
+- Use provider-owned credentials read-only and discard raw exception details.
+- Do not add a dependency: the CLI already depends on agent-manager.

docs/ai/testing/2026-08-09-feature-capacity-command.md

@@ -0,0 +1,40 @@
+---
+phase: testing
+title: Capacity Command Test Record
+description: Coverage and validation for the Codex-only implementation
+---
+
+# Capacity Command Test Record
+
+## Agent-manager Capacity Coverage
+
+- [x] Resolve `CODEX_HOME` before the home fallback.
+- [x] Normalize API and CLI windows without converting missing values to zero.
+- [x] Preserve session, weekly, credit, individual-limit, and additional-window data.
+- [x] Prefer PAT, then fresh OAuth, then CLI; fall back on stale credentials, 401s, and request failures.
+- [x] Use read-only/untrusted app-server arguments and account-only methods.
+- [x] Distinguish logged-out account state and keep unknown/unavailable semantics.
+- [x] Prevent token and raw failure leakage.
+- [x] Detect Codex configuration and installation independently before probing.
+- [x] Build exactly one Codex report and redact unexpected probe failures.
+
+## CLI Coverage
+
+- [x] Render the JSON report exactly.
+- [x] Render human headers, windows, and credits.
+- [x] Accept omitted provider and `codex`, forwarding no cache options.
+- [x] Reject non-Codex providers before probing.
+
+## Removed Coverage
+
+Cache freshness/permissions, generic provider detection, parallel/partial multi-provider orchestration, and Claude/Pi/stub tests were removed with their behavior. They provided no unique coverage of the simplified contract.
+
+## Required Fresh Validation
+
+- `npm ci` only if `node_modules` is absent.
+- `npm run build` at repository root.
+- `npm test --workspace=@ai-devkit/agent-manager`.
+- `npm test --workspace=ai-devkit`.
+- `npm test` for the complete repository suite.
+
+Final command output and pass/fail counts are recorded in the implementation handoff for this uncommitted worktree change.