okstra 0.120.0 → 0.121.1

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.
 
@@ -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: []`.
 

package/docs/cli.md

@@ -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.120.0",
+  "version": "0.121.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.120.0",
-  "builtAt": "2026-07-15T13:14:37.088Z",
+  "package": "0.121.1",
+  "builtAt": "2026-07-15T16:40:10.638Z",
   "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.6}"
-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

@@ -91,7 +91,7 @@ options:
   --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.6
-  --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or auto
+  --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
   --lead-runtime      Lead runtime adapter. Default: claude-code.
@@ -125,7 +125,7 @@ model defaults:
   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.6
-  Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or auto
+  Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
 
 output:

package/runtime/python/okstra_ctl/models.py

@@ -1,50 +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.6": ("gpt-5.6", "gpt-5.6"),
-    "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": "gemini-3.1-pro", "report-writer": None,
 }
-PROVIDER_MAPPINGS = {"claude": CLAUDE_MAPPING, "antigravity": ANTIGRAVITY_MAPPING, "codex": CODEX_MAPPING}
 
 
 @dataclass
@@ -60,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:
@@ -84,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.6"),
-        "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.6", "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,24 +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.6 pricing assumed equal to gpt-5.5 (its flagship predecessor) until
-    # OpenAI publishes rates; without this entry it prefix-matches base `gpt-5`
-    # ($1.25) and undercounts cost.
-    "gpt-5.6":      (5.00,  0.50,  30.0),
-    "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),
@@ -105,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).
     #
@@ -145,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",