okstra 0.119.0 → 0.121.0

package/README.md

@@ -169,6 +169,7 @@ Use these slash commands inside a Claude Code session:
 | `/okstra-memory` | Store, search, and archive global conversation memory in `~/.okstra/memory-book` |
 | `/okstra-inspect` | Unified read side. Subcommands: `status` (phase/state and workStatus updates), `history` (past tasks, reruns, resumes), `report` (find/read final reports), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory and cleanup suggestions), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), and `recap` (run-to-run before/after summary plus free-form Q&A over a task's `.okstra` artifacts) |
 | `/okstra-rollup` | Aggregate every task run in a task group or project, including per-task run counts, duration, errors, group totals, and a cross-task report digest |
+| `/okstra-usage` | Show the current project's recent run coverage, raw and billable-equivalent tokens, known USD cost, CPU time, and wall-clock time grouped by task type (default: last 30 days) |
 | `/okstra-schedule` | Generate a work schedule for an entire task group |
 | `/okstra-container-build` | Deploy a verified task's code as a local Docker Compose group and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `/okstra-graphify` | Build and query a knowledge graph over the project's own `.okstra/` memory—final reports, `decisions/*.md`, and `glossary.md`—with scope restricted to `.okstra/` and output under `.okstra/graph/` (subcommands: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |

package/docs/architecture.md

@@ -147,9 +147,9 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - [`prompts/lead/okstra-lead-contract.md`](../prompts/lead/okstra-lead-contract.md) — main okstra lead contract. It is a runtime resource (`~/.okstra/prompts/lead/`), not an agent skill.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
 - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — in-session entry point that **starts an okstra task in the current Claude session**. Calls `prepare_task_bundle` directly.
-- Only ten skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md`, and `skills/okstra-graphify/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), schedule support, and `okstra-container-build`, a nonlinear container deployment/monitoring skill outside PHASE_SEQUENCE that deploys verified task code as a docker compose group and monitors it with per-container watchers. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
+- Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-graphify/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, and `skills/okstra-user-response/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, `.okstra` knowledge graphs, PR description generation, and clarification-response submission. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
-- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the ten user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-schedule`, `okstra-container-build`, `okstra-graphify`).
+- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule`, `okstra-container-build`, `okstra-graphify`, `okstra-pr-gen`, `okstra-user-response`).
 - Installation location: `~/.claude/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`.
 - Release procedure: [`../../RELEASING.md`](../RELEASING.md) — npm publish flow and release-please / manual fallback.
 
@@ -254,7 +254,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - The main Claude is always the `Claude lead` and operates in synthesis-only mode.
 - The default required worker roles are `Claude worker`, `Codex worker`, and `Report writer worker`. `Antigravity worker` is optional and is included as required only when explicitly named by `--workers` or the profile's `- Workers:` section.
 - `Report writer worker` focuses on report structure and evidence organization, but `Claude lead` remains the final synthesis owner.
-- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, and `Antigravity worker`=`auto` (when opted in). Without a separate override, `Report writer worker` follows the `Claude lead` model (therefore `opus` by default).
+- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6`, and `Antigravity worker`=`auto` (when opted in). Without a separate override, `Report writer worker` follows the `Claude lead` model (therefore `opus` by default).
 - Because `Antigravity worker` is optional, it is attempted only in runs where it is explicitly included.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
@@ -711,6 +711,7 @@ Tokens used in each run are collected from lead/worker session transcripts and w
   - Antigravity CLI: per-message `tokens.total` in `~/.antigravity/tmp/*/chats/session-*.json`
 - Records billable-equivalent token math and USD cost estimates. It applies Anthropic billing ratios (`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`). When the transcript provides separate `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` values, they are counted separately.
 - Pricing is centrally managed in `scripts/okstra_token_usage/pricing.py`. Update it when model prices change. Model IDs that fail price matching are exposed to the user in `usageSummary.unmatchedModels`, preventing silent-zero incidents.
+- Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`src/commands/inspect/usage-report.mjs` → `scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
 - **Incremental scan cache (P6)**: To avoid rescanning session jsonl files, a per-file byte cursor and the extracted usage events before windowing are stored in `$OKSTRA_HOME/cache/token-usage/<transcript-dir>/<sessionId>.json` (`scripts/okstra_token_usage/cursor.py`). The run window (since/until) is reevaluated over events on every invocation, so even if a rerun narrows the window, the total matches a full scan. The cache is derived data; identifier mismatch, truncation, or corruption automatically falls back to a full rescan, and `okstra-token-usage.py --no-cache` forces a bypass.
 - **Phase timeline (P0 instrumentation)**: The collector extracts `PROGRESS: phase-*` checkpoint lines (see "Progress reporting" in prompts/lead/okstra-lead-contract.md) from the lead session jsonl scoped to the run window, and records them in team-state as a `phaseTimeline` block (`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`) (`scripts/okstra_token_usage/collect.py :: phase_timeline`). This provides measurement points for per-phase wall-clock time within the run and is consumed by the "Per-run phase breakdown" in the `okstra-inspect` time facet. Runs without markers explicitly report that measurement is unavailable with `phases: []`.
 
@@ -741,7 +742,7 @@ Each validator blocks the phase with a `contract-violated` exit code when a cont
 - The run directory is organized into typed subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`; prompt snapshots are prepared under `prompts/` first.
 - Claude creates workers and collects results.
 - The standard workflow uses a `Claude lead` with default workers `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and included only when explicitly requested.
-- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, and `Antigravity worker`=`auto`.
+- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6`, and `Antigravity worker`=`auto`.
 - For `--task-type implementation`, select the provider that takes the Executor role with `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`). Only the Executor may mutate project files. The other two providers and the Executor's own provider are each dispatched as verifiers in separate CLI sessions (session isolation preserves the self-review safeguard). The Executor's model reuses the selected provider's worker-model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). Provider / displayName / workerAgent / model are recorded in the run-manifest `teamContract.executor` block.
 - Worktree cwd injection by Executor: Codex / Antigravity executors pin cwd to the worktree at the CLI layer through wrappers (`okstra-codex-exec.sh -C` / `okstra-antigravity-exec.sh --include-directories`). Because the Bash tool has no per-call cwd argument, the Claude executor prefixes cwd-sensitive toolchain invocations (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` in the same Bash invocation. Wrapping in `bash -lc`/`bash -c` is prohibited because it hides the leading `cd` token and defeats permission auto-allow. Prefer working-directory flags such as `git -C` or `cargo --manifest-path` when available. See the *Executor Worktree* block in `prompts/profiles/implementation.md` and the Executor exception in `agents/workers/claude-worker.md` for details.
 - The project-level current-task convenience pointer is `.okstra/discovery/latest-task.json`.

package/docs/cli.md

@@ -342,7 +342,7 @@ The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are
 
 > Every `--*-model` flag accepts only aliases registered in the provider mappings in `scripts/okstra_ctl/models.py`. An unregistered value is immediately rejected with `UnknownModelError`, preventing a contract violation where the manifest's `modelExecutionValue` differs from the actual execution value. Allowed values:
 > - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5`, `claude-fable-5`, `opus`, `opus-4-8`, `claude-opus-4-8`, `opus-4-7`, `claude-opus-4-7`, `opus-4-6`, `claude-opus-4-6`, `sonnet`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
-> - Codex (`--codex-model`): `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
+> - Codex (`--codex-model`): `gpt-5.6`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
 > - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.5-flash`, and the space-separated aliases `gemini 3.1 pro` / `gemini 3.5 flash`. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
 
 ### `--claude-model`
@@ -358,7 +358,7 @@ When omitted, it uses the central default `OKSTRA_DEFAULT_LEAD_MODEL`, falling b
 ### `--codex-model`
 
 Selects the model used by the `Codex worker`.
-When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-5.5`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-5.6`.
 
 ### `--antigravity-model`
 
@@ -384,7 +384,7 @@ Fallback defaults are:
 - `Claude lead`: `opus`
 - `Report writer worker`: `opus`
 - `Claude worker`: `opus`
-- `Codex worker`: `gpt-5.5`
+- `Codex worker`: `gpt-5.6`
 - `Antigravity worker`: `auto`
 - Implementation executor: `claude`, so the default is `Claude executor`.
 
@@ -394,7 +394,7 @@ Selects the provider that performs the Executor role for `--task-type implementa
 
 - Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
 - The Executor is the **only worker allowed to mutate project files** in this run. The other two providers are dispatched as strict read-only verifiers in the same run.
-- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.5`; with `--executor antigravity`, it comes from `--antigravity-model`, default `auto`.
+- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6`; with `--executor antigravity`, it comes from `--antigravity-model`, default `auto`.
 - All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
 - Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox workspace-write`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Both wrappers—`scripts/okstra-codex-exec.sh` and `scripts/okstra-antigravity-exec.sh`—receive the worktree path as their fourth positional argument and forward it through `--add-dir` for Codex or `--include-directories` for Antigravity. Without it, the Codex `workspace-write` sandbox rejects worktree writes with EPERM.
 - **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
@@ -637,6 +637,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra memory <add\|list\|search\|show\|archive>` | Manage global conversation memory in `~/.okstra/memory-book`, a user-home store separate from project `.okstra/` and the CLI basis of the `save this in okstra` natural-language skill |
 | `okstra manager <init\|discover-projects\|new\|task>` | Public CLI for grouping cross-project okstra tasks into manager-owned context. `new project`, `new task-group`, and `new task` create manager plans; `task assign`, `task note`, `task sync`, `task status`, and `task run` manage per-project assignments and snapshots. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. Public documentation uses the full `project-id:task-group:task-id` child task key; when child task IDs differ within the same manager task, select the exact child with `--child-task-id`. `task run` does not execute the child lead directly; it returns `prepared` launch metadata/event and a child launch-context packet as JSON |
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]` | Read-only backend for the okstra-rollup skill. For every catalog task, or one task group, it emits JSON with per-task run counts, raw duration in ms, error counts, latest report paths, group totals, and status/category/phase distributions. Omitting `--task-group` targets the whole project catalog. The caller skill formats raw ms as HH:MM:SS and synthesizes report prose. Use the `okstra inspect` family for a single-task drill-down |
+| `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]` | Read-only backend for the okstra-usage skill. Defaults to the whole current project's last 30 days and emits task-type run coverage, raw/billable tokens, known USD cost, CPU-sum milliseconds, wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
 | `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
 | `okstra task-show <task-key> [--project-root <path>]` | Summarize workflow, phase, status, and artifacts from the Task Read-Side Snapshot |

package/docs/for-ai/README.md

@@ -22,6 +22,7 @@
 | 여러 프로젝트에 걸친 okstra task 묶음, 할당, sync snapshot, child launch packet 관리 | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
 | 상태, history, report, time, logs, cost, errors, error-zip, recap 확인 | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
 | task-group(또는 프로젝트 전체)의 여러 task run 결과를 모아 집계·종합 요약 | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
+| Project-wide recent run coverage, tokens, known cost, CPU, and wall-clock usage by task type | `okstra-usage` | [`skills/okstra-usage.md`](skills/okstra-usage.md) |
 | task-group 전체의 클라이언트용 작업 일정 생성 | `okstra-schedule` | [`skills/okstra-schedule.md`](skills/okstra-schedule.md) |
 | 대화/결정/선호/요구사항을 전역 Memory Book에 저장 또는 검색 | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
 | implementation task worktree 기반 docker compose 사용자 테스트 환경 관리 | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
@@ -45,7 +46,7 @@
 
 ## 공개 스킬 목록
 
-`src/lib/skill-catalog.mjs` 기준 공개 스킬은 다음 9개다.
+이 AI 매뉴얼에 나열된 공개 스킬은 다음 10개다.
 
 - `okstra-setup`
 - `okstra-brief-gen`
@@ -54,5 +55,6 @@
 - `okstra-memory`
 - `okstra-inspect`
 - `okstra-rollup`
+- `okstra-usage`
 - `okstra-schedule`
 - `okstra-container-build`

package/docs/for-ai/skills/okstra-usage.md

@@ -0,0 +1,28 @@
+# okstra-usage AI Manual
+
+## Purpose
+
+Use `okstra-usage` for a project-wide historical resource snapshot. It is not a
+single-task inspection (`okstra-inspect`) and not a cross-task status/report
+digest (`okstra-rollup`).
+
+## Call
+
+Run preflight, resolve a positive day count (default 30), then call exactly once:
+
+```bash
+okstra usage-report --days 30 --project-root <projectRoot> --json
+```
+
+## Render contract
+
+Render returned task-type rows and totals without recomputing them. Show Runs,
+Coverage, Raw tokens, Billable, Cost, CPU, and Wall. Surface unavailable reason
+counts and unmatched model names. Missing usage is excluded data, not zero usage.
+
+## Boundaries
+
+- One task's elapsed/context detail: `okstra-inspect`.
+- Task-group/project status and report digest: `okstra-rollup`.
+- HTML dashboards, budgets, forecasts, and task/model/worker drill-downs are not
+  part of this MVP.

package/docs/project-structure-overview.md

@@ -130,7 +130,7 @@ Runtime/install asset changes follow this checklist:
 - `runtime/python/*` → `~/.okstra/lib/python/`
 - `runtime/bin/*` → `~/.okstra/bin/`
 - `runtime/templates/*` → `~/.okstra/templates/`
-- `runtime/skills/<name>` (the eight user-facing skills only) → `~/.agents/skills` always, plus `~/.claude/skills` when `~/.claude` exists
+- `runtime/skills/<name>` (the thirteen user-facing skills only) → `~/.agents/skills` always, plus `~/.claude/skills` when `~/.claude` exists
 - `runtime/prompts/*` → `~/.okstra/prompts/` (lead contracts under `prompts/lead/`, coding-preflight pack under `prompts/coding-preflight/`)
 - `runtime/agents/workers/*.md` → `~/.claude/agents/*-worker.md` when `~/.claude` exists
 - install manifests → `~/.okstra/installed-skills.json` (target-aware), `~/.okstra/installed-agents.json`
@@ -184,6 +184,7 @@ Runtime/install asset changes follow this checklist:
 | `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
 | `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
 | `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
+| `usage-report` | `src/commands/inspect/usage-report.mjs` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
 | `manager` | `src/commands/manager.mjs` | Thin shim into `scripts/okstra_ctl/manager_cli.py` for cross-project manager state and child launch packets |
 
@@ -228,7 +229,7 @@ Important modules:
 | `recap.py` | okstra-inspect `recap` facet 의 결정론적 백엔드 — `assemble` 은 timeline 에서 run 간 phase 전이를 조립, `record` 는 `<task-root>/recap/recap-log.jsonl` 에 요약·Q&A append-only 기록 (다른 task 산출물 불변) |
 | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
 | `workflow.py` | Phase sequence, allowed outputs, forbidden actions, next phase |
-| `workers.py`, `models.py` | Worker roster and model metadata resolution |
+| `workers.py`, `models.py` | Worker roster; `models.py` is the model catalog SSOT (`ModelSpec` per alias + `ROLE_DEFAULTS`) — add-a-model single reference point from which picker options, codex pricing, and role defaults all derive |
 | `worktree.py`, `worktree_registry.py` | One worktree per task-key, branch registry, sync dirs/files/snapshots |
 | `project_meta.py`, `resolver.py`, `path_resolve.py` | Project/task/run resolution |
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
@@ -244,6 +245,7 @@ Important modules:
 | `error_report.py`, `error_log_core.py`, `error_zip.py` | okstra-inspect errors/error-zip facet 백엔드 — `error_log_core` 는 `errors-*.jsonl` 글롭·파싱·집계 read-only 코어, `error_report` 는 errors facet 렌더, `error_zip` 은 cross-project run 디렉터리 수집·allowlist 익명화·클러스터 집계·zip 생성 |
 | `log_report.py`, `time_report.py` | okstra-inspect logs/time facet 의 read-side 백엔드 (`okstra log-report` 는 wrapper sidecar 로그 인벤토리, `okstra time-report` 는 task 단위 시간 집계) |
 | `rollup.py` | okstra-rollup 스킬의 read-side 백엔드 — catalog 를 task-group(또는 프로젝트 전체) 단위로 fan-out 해 task 별 run 수·소요 시간(raw ms)·에러 수·최신 report 경로와 group 차원 합계/상태·카테고리·phase 분포를 deterministic 하게 집계. `time_report`/`error_log_core` 함수 재사용, report 본문 종합은 skill 에 위임 |
+| `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
 | `json_registry.py` | 작은 okstra 레지스트리 공용 flock + atomic JSON persistence (`registry_lock`/`load_registry_json`/`save_registry_json`) — `container_registry`·`worktree_registry` 가 공유 |
 | `stage_integrate.py` | whole-task stage 통합(머지)+worktree teardown 코어 (`integrate_stages`) — whole-task final-verification 진입·`okstra integrate-stages`·container up 이 공유 |
 | `resolve_task_key.py` | bare task-id → `task-catalog.json` 후보 entry 해석 skill 공용 helper (`okstra resolve-task-key`) |
@@ -320,7 +322,7 @@ Optional (v1.0 하위호환) 최상위 키:
 
 ### 4.10 `skills/`
 
-11 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it:
+13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
@@ -329,12 +331,14 @@ Optional (v1.0 하위호환) 최상위 키:
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
+| `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
 | `okstra-schedule` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
 | `okstra-manager` | yes | Coordinate cross-project okstra tasks through manager-owned plans, assignments, sync snapshots, status, and child launch context packets |
 | `okstra-setup` | yes | Install/check runtime and register project |
+| `okstra-user-response` | yes | Submit answers to a run's open clarification items through the installed response helper without hand-editing artifacts |
 
 > The former internal skills — `context-loader`, `team-contract`, `convergence`, `report-writer`, `coding-preflight` — and the lead contract are no longer skills. They ship as runtime resources under `prompts/lead/*` and `prompts/coding-preflight/*` (installed to `~/.okstra/prompts/`); see §4.11.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.119.0",
-  "builtAt": "2026-07-15T11:10:05.274Z",
+  "package": "0.121.0",
+  "builtAt": "2026-07-15T15:37:19.231Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/globals.sh

@@ -159,10 +159,5 @@ ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE=""
 REPORT_WRITER_MODEL=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
 DEFAULT_WORKERS="claude,codex,report-writer"
-DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
-DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-opus}"
-DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"
-DEFAULT_ANTIGRAVITY_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_ANTIGRAVITY_MODEL:-gemini-3.1-pro}"
-DEFAULT_REPORT_WRITER_MODEL_NAME="${OKSTRA_DEFAULT_REPORT_WRITER_MODEL:-$DEFAULT_LEAD_MODEL_NAME}"
 DISPLAY_COMMAND_NAME="${OKSTRA_COMMAND_NAME:-$(basename "$0")}"
 DISPLAY_TOOL_NAME="${OKSTRA_TOOL_NAME:-okstra}"

package/runtime/bin/lib/okstra/usage.sh

@@ -90,7 +90,7 @@ options:
                       (Antigravity worker is optional; add \`antigravity\` explicitly, e.g. --workers claude,codex,antigravity,report-writer)
   --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
+  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or auto
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
@@ -124,7 +124,7 @@ model defaults:
   Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
   Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
+  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or auto
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
 

package/runtime/prompts/lead/convergence.md

@@ -292,7 +292,7 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
 2. `team-state-<task-type>-<seq>.json` → `workers[].usage.cliModel` for that role (initial run's actual execution value)
 3. The `**Model:**` line of the initial Phase 4 prompt for that role (read from its persisted prompt-history file)
 
-If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra error-log append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this silently produces `o4-mini` instead of the assigned `gpt-5.5`-class model.
+If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra error-log append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this silently produces `o4-mini` instead of the assigned `gpt-5.6`-class model.
 
 For Codex/Antigravity wrapper subagents, the `**Model:** <role>, <modelExecutionValue>` line is what their wrapper extracts to pass into the underlying CLI's `--model` flag. Omitting it forces the wrapper to fall back to its own training-data knowledge of the CLI's historical default.
 

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -126,7 +126,7 @@ The table below documents those prep-time seed values **for reference only** —
 | Claude lead | opus | -- | orchestration + convergence supervision + final-report review/approval |
 | Report writer worker | opus | report-writer-worker | `agents/workers/report-writer-worker.md` |
 | Claude worker | opus | claude-worker | `agents/workers/claude-worker.md` |
-| Codex worker | gpt-5.5 | codex-worker | generated from `agents/workers/_cli-wrapper-template.md` + `codex-worker.params.json` |
+| Codex worker | gpt-5.6 | codex-worker | generated from `agents/workers/_cli-wrapper-template.md` + `codex-worker.params.json` |
 | Antigravity worker | auto | antigravity-worker | generated from `agents/workers/_cli-wrapper-template.md` + `antigravity-worker.params.json` |
 
 All three analysis workers use dedicated agent definitions; Codex/Antigravity wrappers handle external CLI invocation internally; Claude worker runs as an in-process subagent with explicitly registered MCP tools so it does not fall back to `claude --mcp-cli` Bash invocations.

package/runtime/prompts/profiles/_common-contract.md

@@ -8,7 +8,7 @@ profile document.
 - Team contract (shared):
   - `Claude lead` is synthesis-only and stays distinct from `Claude worker` (or, in `implementation`, the `Executor` and verifiers).
   - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `team-contract` and `report-writer` for the authoritative contract).
-  - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, `Antigravity worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
+  - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6`, `Antigravity worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
   - every required worker listed in the per-profile `Required workers:` block must be attempted; the final verdict waits until each has either a result or an explicit terminal status (`timeout`, `error`, `not-run`).
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster.
 - Worker interaction model (shared — read before inferring behaviour from the roster):

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -12,7 +12,7 @@ at Phase 5, BEFORE constructing the verifier worker dispatch prompts.
 - **Verifier dispatch labelling.** Agent `name` = `<provider>-verifier` (here, and identically in `final-verification`); for a `codex` / `antigravity` verifier, Lead additionally injects `**Pane role:** verifier` into the dispatched prompt body. Naming/mapping rules and the token-attribution guarantee are owned by `prompts/lead/okstra-lead-contract.md` Phase 4 "Agent `name` on dispatch".
 - The verifier slots are `Claude verifier` and `Codex verifier`, plus `Antigravity verifier` **only when `antigravity` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
 - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
-- Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.5`, `Antigravity verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.5`), antigravity→`--antigravity-model` (default `auto`).
+- Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.6`, `Antigravity verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.6`), antigravity→`--antigravity-model` (default `auto`).
 - Verifiers read from the SAME working tree path the Executor used so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
 
 ## Verifier QA duties (independent re-run mandate)

package/runtime/python/okstra_ctl/models.py

@@ -1,49 +1,66 @@
-"""Model display / execution-value resolution for okstra workers.
+"""Model catalog: display / execution / pricing / picker for okstra workers.
 
-bash `resolve_model_metadata` 의 동등한 python 구현. 사용자가 준 모델 alias
-또는 정식 이름을 `(display, execution_value)` 쌍으로 정규화한다.
+Single reference point. Adding a model = one ModelSpec entry here. Changing a
+role default = one ROLE_DEFAULTS line here.
 """
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Optional
 
-CLAUDE_MAPPING = {
-    "fable": ("fable", "fable"),
-    "fable-5": ("fable-5", "claude-fable-5"),
-    "claude-fable-5": ("fable-5", "claude-fable-5"),
-    "opus": ("opus", "opus"),
-    "opus-4-8": ("opus-4-8", "claude-opus-4-8"),
-    "claude-opus-4-8": ("opus-4-8", "claude-opus-4-8"),
-    "opus-4-7": ("opus-4-7", "claude-opus-4-7"),
-    "claude-opus-4-7": ("opus-4-7", "claude-opus-4-7"),
-    "opus-4-6": ("opus-4-6", "claude-opus-4-6"),
-    "claude-opus-4-6": ("opus-4-6", "claude-opus-4-6"),
-    "sonnet": ("sonnet", "sonnet"),
-    "sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),
-    "claude-sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),
-    "haiku": ("haiku", "haiku"),
-    "haiku-4-5": ("haiku-4-5", "claude-haiku-4-5"),
-    "claude-haiku-4-5": ("haiku-4-5", "claude-haiku-4-5"),
-    "claude-haiku-4-5-20251001": ("haiku-4-5", "claude-haiku-4-5-20251001"),
+
+@dataclass(frozen=True)
+class ModelSpec:
+    display: str
+    execution: str
+    pricing: Optional[tuple] = None   # codex only: (input, cached_input, output) USD/1M
+    in_picker: bool = False           # exposed in the wizard 3-option picker
+
+
+CLAUDE = {
+    "fable": ModelSpec("fable", "fable", in_picker=True),
+    "fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "claude-fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "opus": ModelSpec("opus", "opus", in_picker=True),
+    "opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "claude-opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "claude-opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "claude-opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "sonnet": ModelSpec("sonnet", "sonnet", in_picker=True),
+    "sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "claude-sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "haiku": ModelSpec("haiku", "haiku", in_picker=True),
+    "haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5-20251001": ModelSpec("haiku-4-5", "claude-haiku-4-5-20251001"),
+}
+# Execution values stay `gemini-3.x`: the `agy` CLI runs Gemini-family models and
+# accepts those slugs. Only the okstra provider/worker identity is "antigravity".
+ANTIGRAVITY = {
+    "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
+    "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),
+    "gemini-3.5-flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash", in_picker=True),
+    "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
 }
-# Antigravity worker runs the `agy` CLI, which executes Gemini-family models.
-# The execution values stay `gemini-3.x` (agy accepts those slugs); only the
-# okstra provider/worker identity is "antigravity".
-ANTIGRAVITY_MAPPING = {
-    "gemini 3.1 pro": ("Gemini 3.1 Pro", "gemini-3.1-pro"),
-    "gemini-3.1-pro": ("Gemini 3.1 Pro", "gemini-3.1-pro"),
-    "gemini 3.5 flash": ("Gemini 3.5 Flash", "gemini-3.5-flash"),
-    "gemini-3.5-flash": ("Gemini 3.5 Flash", "gemini-3.5-flash"),
+CODEX = {
+    "gpt-5.6": ModelSpec("gpt-5.6", "gpt-5.6", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.5": ModelSpec("gpt-5.5", "gpt-5.5", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.4": ModelSpec("gpt-5.4", "gpt-5.4", (2.50, 0.25, 15.0), in_picker=True),
+    "gpt-5.4-mini": ModelSpec("gpt-5.4-mini", "gpt-5.4-mini", (0.75, 0.075, 4.50), in_picker=True),
+    "gpt-5.3-codex": ModelSpec("gpt-5.4", "gpt-5.4"),
+    "gpt-5.2": ModelSpec("gpt-5.2", "gpt-5.2", (1.75, 0.175, 14.0)),
+    "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review"),
 }
-CODEX_MAPPING = {
-    "gpt-5.5": ("gpt-5.5", "gpt-5.5"),
-    "gpt-5.4": ("gpt-5.4", "gpt-5.4"),
-    "gpt-5.4-mini": ("gpt-5.4-mini", "gpt-5.4-mini"),
-    "gpt-5.3-codex": ("gpt-5.4", "gpt-5.4"),
-    "gpt-5.2": ("gpt-5.2", "gpt-5.2"),
-    "codex-auto-review": ("codex-auto-review", "codex-auto-review"),
+PROVIDER_MAPPINGS = {"claude": CLAUDE, "antigravity": ANTIGRAVITY, "codex": CODEX}
+
+# ROLE-keyed (not provider): 1:1 with run.py recommended_role_models. "lead" uses
+# the claude provider; "report-writer" is role-only (None → caller uses lead's).
+ROLE_DEFAULTS = {
+    "lead": "opus", "claude": "opus", "codex": "gpt-5.6",
+    "antigravity": "auto", "report-writer": None,
 }
-PROVIDER_MAPPINGS = {"claude": CLAUDE_MAPPING, "antigravity": ANTIGRAVITY_MAPPING, "codex": CODEX_MAPPING}
 
 
 @dataclass
@@ -59,15 +76,8 @@ class UnknownModelError(ValueError):
 def resolve_model_metadata(
     *, provider: str, raw_value: str, default_display: str, default_execution: str,
 ) -> ModelAssignment:
-    """alias → (display, execution_value).
-
-    provider: "claude" | "codex" | "antigravity" (그 외는 mapping 미적용)
-
-    Mapping 이 정의된 provider 에 대해 사용자가 빈 값이 아닌 raw_value 를 줬는데
-    mapping 에 없는 경우 `UnknownModelError` 를 발생시킨다. 이는 manifest 에
-    Codex 가 지원하지 않는 `gpt-5.5-high` 같은 유령 모델이 기록되어 실제
-    실행값과 contract 가 불일치하는 사고를 막기 위함이다.
-    """
+    """alias → (display, execution). Unchanged contract; mapping values are now
+    ModelSpec instead of tuples."""
     raw_value = (raw_value or "").strip()
     mapping = PROVIDER_MAPPINGS.get(provider)
     if raw_value and mapping is not None:
@@ -83,5 +93,23 @@ def resolve_model_metadata(
     execution = raw_value or default_execution
     normalized = value.strip().lower()
     if mapping and normalized in mapping:
-        display, execution = mapping[normalized]
+        spec = mapping[normalized]
+        display, execution = spec.display, spec.execution
     return ModelAssignment(display=display, execution=execution)
+
+
+def picker_options(provider: str) -> list[str]:
+    """Picker-exposed aliases for a provider, in catalog insertion order."""
+    mapping = PROVIDER_MAPPINGS.get(provider, {})
+    return [alias for alias, spec in mapping.items() if spec.in_picker]
+
+
+def default_model(role: str) -> Optional[str]:
+    """Role → default model alias (env override is the caller's concern)."""
+    return ROLE_DEFAULTS.get(role)
+
+
+def catalog_pricing(provider: str) -> dict:
+    """Selectable-model pricing for a provider (codex only carries pricing)."""
+    mapping = PROVIDER_MAPPINGS.get(provider, {})
+    return {alias: spec.pricing for alias, spec in mapping.items() if spec.pricing is not None}

package/runtime/python/okstra_ctl/rollup.py

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 
 from okstra_ctl.error_log_core import glob_error_logs, parse_records
-from okstra_ctl.time_report import _load_runs, aggregate_time
+from okstra_ctl.time_report import aggregate_time, load_runs
 from okstra_project import (
     ResolverError,
     list_project_tasks,
@@ -30,7 +30,7 @@ def _collect_task(entry: dict, project_root: Path) -> dict:
     cpuSumMs/wallClockMs 는 durationMs 가 있는 run 만 반영하므로 0 일 수 있다.
     """
     task_root = Path(entry["_resolvedTaskRoot"])
-    runs = _load_runs(task_root)
+    runs, _ = load_runs(task_root)
     time_agg = aggregate_time(runs, project_root)
     records, _ = parse_records(glob_error_logs(task_root))
     return {

package/runtime/python/okstra_ctl/run.py

@@ -46,7 +46,7 @@ from .final_report_schema import load_schema
 from .final_report_paths import final_report_data_path as _final_report_data_path
 from .lead_events import LeadEvent, append_lead_event
 from .lead_runtime import ALLOWED_LEAD_RUNTIMES
-from .models import ModelAssignment, resolve_model_metadata
+from .models import ModelAssignment, default_model, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
@@ -1339,12 +1339,12 @@ class _ModelBindings:
 def recommended_role_models() -> dict[str, str]:
     """역할 → 추천 모델 display 값 (env override 반영). prepare 의 모델 해소와
     wizard 의 안내 표기가 공유하는 단일 기준점."""
-    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
+    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", default_model("lead"))
     return {
         "lead": lead_default,
-        "claude": _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "opus"),
-        "codex": _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5"),
-        "antigravity": _default("OKSTRA_DEFAULT_ANTIGRAVITY_MODEL", "auto"),
+        "claude": _default("OKSTRA_DEFAULT_CLAUDE_MODEL", default_model("claude")),
+        "codex": _default("OKSTRA_DEFAULT_CODEX_MODEL", default_model("codex")),
+        "antigravity": _default("OKSTRA_DEFAULT_ANTIGRAVITY_MODEL", default_model("antigravity")),
         "report-writer": _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default),
     }
 

package/runtime/python/okstra_ctl/time_report.py

@@ -18,13 +18,16 @@ from okstra_ctl.paths import resolve_under_root
 from okstra_ctl.task_target import resolve_task_root
 
 
-def _load_runs(task_root: Path) -> list[dict]:
+def load_runs(task_root: Path) -> tuple[list[dict], bool]:
+    path = task_root / "history" / "timeline.json"
     try:
-        data = json.loads((task_root / "history" / "timeline.json").read_text(encoding="utf-8"))
+        data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError):
-        return []
-    runs = data.get("runs", [])
-    return runs if isinstance(runs, list) else []
+        return [], True
+    runs = data.get("runs", []) if isinstance(data, dict) else []
+    if not isinstance(runs, list):
+        return [], True
+    return runs, False
 
 
 def _task_key(task_root: Path) -> str:
@@ -190,8 +193,9 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
+    runs, _ = load_runs(task_root)
     result = {"ok": True, "taskKey": _task_key(task_root)}
-    result.update(aggregate_time(_load_runs(task_root), project_root))
+    result.update(aggregate_time(runs, project_root))
     print(json.dumps(result, ensure_ascii=False, indent=2))
     return 0
 

package/runtime/python/okstra_ctl/usage_report.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import math
+import sys
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl.time_report import (
+    _duration_ms,
+    _read_state,
+    _wall_clock_ms,
+    load_runs,
+)
+from okstra_project import ResolverError, list_project_tasks, resolve_project_root
+
+UTC = dt.timezone.utc
+UNAVAILABLE_KEYS = (
+    "invalidRunTimestamp",
+    "teamStateMissing",
+    "usageSummaryMissing",
+    "durationMissing",
+)
+
+
+def _iso_z(value: dt.datetime) -> str:
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _parse_timestamp(value: Any) -> dt.datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=UTC)
+        return parsed.astimezone(UTC)
+    except (OverflowError, ValueError):
+        return None
+
+
+def _project_id(project_root: Path) -> str:
+    try:
+        data = json.loads(
+            (project_root / ".okstra" / "project.json").read_text(encoding="utf-8")
+        )
+    except (OSError, ValueError):
+        return ""
+    return str(data.get("projectId") or "") if isinstance(data, dict) else ""
+
+
+def _int_value(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except (OverflowError, TypeError, ValueError):
+        return 0
+
+
+def _float_value(value: Any) -> float:
+    try:
+        result = float(value or 0)
+    except (OverflowError, TypeError, ValueError):
+        return 0.0
+    return result if math.isfinite(result) else 0.0
+
+
+def _usage_block(value: Any) -> dict:
+    if not isinstance(value, dict):
+        return {}
+    block = {"source": value["source"]} if "source" in value else {}
+    if "durationMs" in value:
+        block["durationMs"] = _int_value(value["durationMs"])
+    for key in ("startedAt", "endedAt"):
+        if isinstance(value.get(key), str):
+            block[key] = value[key]
+    return block
+
+
+def _usage_blocks(state: dict) -> tuple[dict, list[dict]]:
+    workers = state.get("workers")
+    worker_entries = workers if isinstance(workers, list) else []
+    return _usage_block(state.get("leadUsage")), [
+        _usage_block(worker.get("usage"))
+        for worker in worker_entries
+        if isinstance(worker, dict)
+    ]
+
+
+def _wall_clock_from_blocks(lead: dict, workers: list[dict]) -> int:
+    state = {
+        "leadUsage": lead,
+        "workers": [{"usage": usage} for usage in workers],
+    }
+    try:
+        return _wall_clock_ms(state)
+    except TypeError:
+        return 0
+
+
+def _run_metrics(run: dict, project_root: Path) -> tuple[dict | None, str | None]:
+    state = _read_state(project_root, str(run.get("teamStatePath") or ""))
+    if state is None:
+        return None, "teamStateMissing"
+    summary = state.get("usageSummary")
+    if not isinstance(summary, dict) or _int_value(summary.get("grandTotalTokens")) <= 0:
+        return None, "usageSummaryMissing"
+    lead, workers = _usage_blocks(state)
+    durations = [_duration_ms(lead), *(_duration_ms(worker) for worker in workers)]
+    positive_durations = [duration for duration in durations if duration > 0]
+    if not positive_durations:
+        return None, "durationMissing"
+    costs = summary.get("estimatedCostUsd")
+    cost = costs.get("grandTotal", 0) if isinstance(costs, dict) else 0
+    unmatched = summary.get("unmatchedModels")
+    unmatched_models = unmatched if isinstance(unmatched, list) else []
+    return {
+        "rawTokens": _int_value(summary.get("grandTotalTokens")),
+        "billableTokens": _int_value(summary.get("grandBillableEquivalentTokens")),
+        "costUsd": _float_value(cost),
+        "cpuSumMs": sum(positive_durations),
+        "wallClockMs": _wall_clock_from_blocks(lead, workers),
+        "unmatchedModels": [
+            model for model in unmatched_models if isinstance(model, str) and model
+        ],
+    }, None
+
+
+def _new_bucket(task_type: str, first_run_at: dt.datetime) -> dict:
+    return {
+        "taskType": task_type,
+        "firstRunAt": _iso_z(first_run_at),
+        "runs": 0,
+        "collectedRuns": 0,
+        "rawTokens": 0,
+        "billableTokens": 0,
+        "costUsd": 0.0,
+        "cpuSumMs": 0,
+        "wallClockMs": 0,
+    }
+
+
+def _collect_usage(
+    project_root: Path,
+    start_at: dt.datetime,
+    end_at: dt.datetime,
+    unavailable: dict[str, int],
+    warnings: dict[str, int],
+) -> tuple[dict[str, dict], set[str], int, int]:
+    buckets: dict[str, dict] = {}
+    unmatched_models: set[str] = set()
+    total_runs = 0
+    collected_runs = 0
+    for entry in list_project_tasks(project_root):
+        runs, timeline_warning = load_runs(Path(entry["_resolvedTaskRoot"]))
+        warnings["missingOrInvalidTimelines"] += int(timeline_warning)
+        for run in runs:
+            if not isinstance(run, dict):
+                unavailable["invalidRunTimestamp"] += 1
+                continue
+            run_at = _parse_timestamp(run.get("runTimestamp"))
+            if run_at is None:
+                unavailable["invalidRunTimestamp"] += 1
+                continue
+            if run_at < start_at or run_at > end_at:
+                continue
+            task_type = str(run.get("taskType") or "unknown")
+            bucket = buckets.setdefault(task_type, _new_bucket(task_type, run_at))
+            run_at_text = _iso_z(run_at)
+            if run_at_text < bucket["firstRunAt"]:
+                bucket["firstRunAt"] = run_at_text
+            total_runs += 1
+            bucket["runs"] += 1
+            metrics, reason = _run_metrics(run, project_root)
+            if reason is not None:
+                unavailable[reason] += 1
+                continue
+            collected_runs += 1
+            bucket["collectedRuns"] += 1
+            for key in ("rawTokens", "billableTokens", "cpuSumMs", "wallClockMs"):
+                bucket[key] += metrics[key]
+            bucket["costUsd"] += metrics["costUsd"]
+            unmatched_models.update(metrics["unmatchedModels"])
+    return buckets, unmatched_models, total_runs, collected_runs
+
+
+def build_usage_report(project_root: Path, days: int, now: dt.datetime) -> dict:
+    if days <= 0:
+        raise ValueError("days must be a positive integer")
+    project_root = Path(project_root).resolve()
+    end_at = now.astimezone(UTC)
+    try:
+        start_at = end_at - dt.timedelta(days=days)
+    except OverflowError:
+        start_at = dt.datetime.min.replace(tzinfo=UTC)
+    unavailable = {key: 0 for key in UNAVAILABLE_KEYS}
+    warnings = {"missingOrInvalidTimelines": 0}
+    buckets, unmatched_models, total_runs, collected_runs = _collect_usage(
+        project_root, start_at, end_at, unavailable, warnings
+    )
+
+    rows = sorted(buckets.values(), key=lambda row: row["firstRunAt"])
+    for row in rows:
+        row["costUsd"] = round(_float_value(row["costUsd"]), 4)
+    totals = {
+        "runs": total_runs,
+        "collectedRuns": collected_runs,
+        "rawTokens": sum(row["rawTokens"] for row in rows),
+        "billableTokens": sum(row["billableTokens"] for row in rows),
+        "costUsd": round(_float_value(sum(row["costUsd"] for row in rows)), 4),
+        "cpuSumMs": sum(row["cpuSumMs"] for row in rows),
+        "wallClockMs": sum(row["wallClockMs"] for row in rows),
+    }
+    return {
+        "ok": True,
+        "projectId": _project_id(project_root),
+        "range": {"days": days, "startAt": _iso_z(start_at), "endAt": _iso_z(end_at)},
+        "runs": {
+            "total": total_runs,
+            "collected": collected_runs,
+            "collectionRate": collected_runs / total_runs if total_runs else 0.0,
+        },
+        "byTaskType": rows,
+        "totals": totals,
+        "unavailable": unavailable,
+        "warnings": warnings,
+        "unmatchedModels": sorted(unmatched_models),
+    }
+
+
+def utc_now() -> dt.datetime:
+    return dt.datetime.now(UTC)
+
+
+def _positive_days(value: str) -> int:
+    try:
+        days = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("--days must be a positive integer") from exc
+    if days <= 0:
+        raise argparse.ArgumentTypeError("--days must be a positive integer")
+    return days
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra usage-report",
+        description="Aggregate recent project usage by task type.",
+    )
+    parser.add_argument("--days", type=_positive_days, default=30)
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+    try:
+        project_root = Path(
+            resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+        ).resolve()
+    except ResolverError as exc:
+        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+    result = build_usage_report(project_root, args.days, utc_now())
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/wizard.py

@@ -33,6 +33,7 @@ from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.models import (
     PROVIDER_MAPPINGS,
     UnknownModelError,
+    picker_options,
     resolve_model_metadata,
 )
 from okstra_ctl.clarification_items import scan_approval_gate, user_response_sidecars
@@ -128,9 +129,9 @@ _BRIEF_ENTRY_TASK_TYPES = ("requirements-discovery", "improvement-discovery",
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
 
-CLAUDE_MODEL_OPTIONS = ["default", "fable", "opus", "sonnet", "haiku"]
-CODEX_MODEL_OPTIONS = ["default", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"]
-ANTIGRAVITY_MODEL_OPTIONS = ["default", "gemini-3.1-pro", "gemini-3.5-flash"]
+CLAUDE_MODEL_OPTIONS = ["default", *picker_options("claude")]
+CODEX_MODEL_OPTIONS = ["default", *picker_options("codex")]
+ANTIGRAVITY_MODEL_OPTIONS = ["default", *picker_options("antigravity")]
 
 # special pick value: start a brand-new task
 TASK_PICK_NEW_TOKEN = "__new__"

package/runtime/python/okstra_token_usage/pricing.py

@@ -11,8 +11,9 @@ provider:
   * Google / Gemini — `gemini-3.5-flash*`, `gemini-3.1-pro*`, `gemini-3-flash*`,
     `gemini-2.5-pro*`, `gemini-2.5-flash*`, `gemini-2.0-flash*`.
 
-Insertion order is the match order, so list more specific keys first. Update
-when providers change list pricing.
+Matching prefers the longest key that is a substring of the model id (most
+specific wins), so table ordering does not affect the result. Update when
+providers change list pricing.
 
 Sources (last verified 2026-05-17, public list prices, USD per 1M tokens):
   * Anthropic: https://www.anthropic.com/pricing
@@ -21,6 +22,8 @@ Sources (last verified 2026-05-17, public list prices, USD per 1M tokens):
 """
 from __future__ import annotations
 
+from okstra_ctl.models import catalog_pricing
+
 
 # Anthropic billing ratios relative to base input: cache_creation (5m) = 1.25x,
 # cache_creation (1h) = 2x, cache_read = 0.1x, output = 5x. The CLAUDE_PRICING
@@ -29,8 +32,8 @@ from __future__ import annotations
 CLAUDE_PRICING = {
     # model substring -> (input, cache_creation_5m, cache_read, output) USD/1M.
     #
-    # Order matters — list more specific keys (e.g. `opus-4-7`, `3-7-sonnet`)
-    # before the family fallbacks (`opus-4`, `3-5-sonnet`).
+    # _match_pricing picks the longest matching key (most specific), so ordering
+    # here is for readability, not correctness.
     #
     # For the newer 4.x point releases (Opus 4.7, Sonnet 4.6, Haiku 4.5),
     # Anthropic's public price page only lists input/output. Cache-write and
@@ -65,20 +68,17 @@ CLAUDE_PRICING = {
 # Anthropic 1h ephemeral cache_creation multiplier on the base input rate.
 CLAUDE_CACHE_CREATE_1H_MULT = 2.0
 
-CODEX_PRICING = {
+# Legacy / non-selectable codex prices. Selectable-model prices (the aliases the
+# picker offers) live in the model catalog and are merged in below via
+# `catalog_pricing("codex")`. Substring match order is now longest-key-first
+# (see `_match_pricing`), so this dict's ordering no longer affects matching.
+# For models with no published cached-input rate (o1-pro, o3-pro), cached is set
+# equal to input as a conservative no-discount default.
+_LEGACY_CODEX_PRICING = {
     # model substring -> (input USD/1M, cached_input USD/1M, output USD/1M).
-    # IMPORTANT: substring match order is insertion order. List the most
-    # specific keys first (e.g. `gpt-5-mini` before `gpt-5`, `o3-mini` before
-    # `o3`, `gpt-4o-mini` before `gpt-4o`, `gpt-4o` before the legacy `gpt-4`).
-    # For models with no published cached-input rate (o1-pro, o3-pro), cached
-    # is set equal to input as a conservative no-discount default.
 
     # GPT-5 series.
-    "gpt-5.5":      (5.00,  0.50,  30.0),
-    "gpt-5.4-mini": (0.75,  0.075, 4.50),
-    "gpt-5.4":      (2.50,  0.25,  15.0),
     "gpt-5.2-pro":  (21.0,  2.10,  168.0),
-    "gpt-5.2":      (1.75,  0.175, 14.0),
     "gpt-5.1":      (1.25,  0.125, 10.0),
     "gpt-5-mini":   (0.25,  0.025, 2.00),
     "gpt-5-nano":   (0.05,  0.005, 0.40),
@@ -101,6 +101,10 @@ CODEX_PRICING = {
     "gpt-4":        (2.50, 0.625, 10.0),  # legacy gpt-4 fallback
 }
 
+# catalog + legacy: catalog owns selectable prices, legacy covers the rest. No
+# key overlaps today; if one ever collided, the legacy (right) side would win.
+CODEX_PRICING = {**catalog_pricing("codex"), **_LEGACY_CODEX_PRICING}
+
 GEMINI_PRICING = {
     # model substring -> (input USD/1M, output USD/1M).
     #
@@ -141,7 +145,7 @@ def _match_pricing(model: str | None, table: dict) -> tuple | None:
     if not model:
         return None
     m = model.lower()
-    for key, val in table.items():
+    for key, val in sorted(table.items(), key=lambda kv: len(kv[0]), reverse=True):
         if key in m:
             return val
     return None

package/runtime/skills/okstra-usage/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: okstra-usage
+description: >-
+  Show project-wide okstra resource usage over a recent day window. Use when the
+  user asks for okstra usage, token usage, estimated spend, CPU/wall time, usage
+  coverage, or which lifecycle task types consumed resources. Defaults to the
+  whole current project for the last 30 days. For one task's elapsed/context
+  detail use okstra-inspect; for status/report digests use okstra-rollup.
+---
+
+# OKSTRA Usage
+
+Read-only project usage snapshot. The CLI owns every sum; never re-add rows.
+
+## Step 0: Preflight
+
+Run one literal Bash call:
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+On `ok:true`, carry `projectRoot`. On `ok:false`, tell the user to run `/okstra-setup` first
+and stop. On `unknown command: preflight`, tell the user to run
+`npm i -g okstra@latest` and stop.
+
+## Step 1: Resolve the day window
+
+- No period stated: `30`.
+- “last N days”: use N only when it is a positive integer.
+- A calendar range, task/group/model/worker breakdown, forecast, or budget is
+  outside this MVP; state that limitation instead of inventing flags.
+
+## Step 2: Fetch once
+
+```bash
+okstra usage-report --days 30 --project-root <projectRoot> --json
+```
+
+Replace `30` only with the resolved positive integer. Do not wrap the command in
+`if`, `eval`, command substitution, variable assignment, `&&`, `||`, or `npx`.
+
+## Step 3: Render
+
+If `ok:false`, report `stage` and `reason`, then stop. If `runs.total == 0`, say
+`No okstra usage found in the last N days.`, omit the table, and continue to Step 4.
+
+Otherwise, render `byTaskType` in returned order:
+
+| Task type | Runs | Coverage | Raw tokens | Billable | Cost | CPU | Wall |
+|---|---:|---:|---:|---:|---:|---:|---:|
+
+- `Coverage` = returned `collectedRuns/runs`; never calculate a new aggregate.
+- Format tokens with K/M suffixes, milliseconds as zero-padded `HH:MM:SS`, and
+  USD to two decimals. For tokens, use one decimal at `>= 1,000` (`K`) and
+  `>= 1,000,000` (`M`), trimming a trailing `.0`; below 1,000 render the integer.
+- Render the `totals` object as the final bold row.
+- Never treat unavailable usage as collected zero usage.
+
+## Step 4: Diagnostics
+
+- Render non-zero `unavailable` and `warnings` counts after the Step 3 output.
+- If `unmatchedModels` is non-empty, mark Cost with `*` when the table exists and
+  always say known-price cost excludes those exact model names.

package/src/cli-registry.mjs

@@ -138,6 +138,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Aggregate elapsed work time across a task's runs (raw ms)"],
   },
+  {
+    name: "usage-report",
+    module: "./commands/inspect/usage-report.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Aggregate recent token, cost, and time usage by task type"],
+  },
   {
     name: "log-report",
     module: "./commands/inspect/log-report.mjs",

package/src/commands/inspect/usage-report.mjs

@@ -0,0 +1,25 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra usage-report — aggregate recent project usage by task type
+
+Usage:
+  okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]
+
+Read-only. Prints JSON containing run coverage, raw and billable-equivalent
+tokens, known USD cost, CPU-sum time, and wall-clock time grouped by task type.
+The default window is the current project's last 30 days.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.usage_report",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/lib/skill-catalog.mjs

@@ -12,6 +12,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-memory",
   "okstra-inspect",
   "okstra-rollup",
+  "okstra-usage",
   "okstra-schedule",
   "okstra-container-build",
   "okstra-graphify",