okstra 0.30.1 → 0.30.3

package/bin/okstra

@@ -17,6 +17,7 @@ const COMMANDS = new Map([
   ["render-bundle", () => import("../src/render-bundle.mjs").then((m) => m.run)],
   ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
   ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
+  ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],
 ]);
 
 const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
@@ -55,6 +56,9 @@ Introspection commands (JSON output, used by skills to avoid python heredocs):
                          python3 -m okstra_ctl.run --render-only)
   wizard                 Drive the okstra-run interactive input state machine
                          (init / step / render-args / confirmation)
+  token-usage            Collect token usage for a run (wraps the installed
+                         okstra-token-usage.py so skills avoid emitting
+                         python3 "$HOME/..." invocations).
 
 Global options:
   --version              Print okstra version and exit

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.30.1",
-  "builtAt": "2026-05-17T11:12:55.482Z",
+  "package": "0.30.3",
+  "builtAt": "2026-05-19T08:41:16.438Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -107,26 +107,24 @@ at external `docs/adr/`.
 
 ## Step 0: Resolve project root
 
-Reuse the same disk-only resolution rule as `okstra-run`:
+Reuse the same literal-token-first rule as `okstra-run`. Each command below is a **separate Bash tool call** starting with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call.
 
 ```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  # `~/.okstra/bin/okstra.sh` exists on every installed machine but it is
-  # the bash run-wrapper, NOT the Node CLI — it does not implement
-  # `check-project`. Do not branch into it as a fallback. Go straight to
-  # `npx` so the user always reaches a working `check-project` even when
-  # the Node CLI is off-$PATH.
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD check-project --cwd "$(pwd)"
+okstra check-project --json
 ```
 
-- `ok: true` → use `projectRoot`.
-- `ok: false` → `AskUserQuestion` (free text) for an absolute project root, then
-  re-run `okstra check-project --cwd <input>`. If still not ok, tell the user
-  to run `okstra-setup` and stop.
+Parse the JSON from stdout:
+
+- `ok: true` → use `projectRoot` from the JSON output. Carry it as a literal string into the steps below.
+- `ok: false` → ask the user with a **plain text prompt** for an absolute project-root path, then rerun as a separate tool call with the literal absolute path (no `$(pwd)`, no shell variables):
+
+  ```bash
+  okstra check-project --cwd /abs/path/from/user --json
+  ```
+
+  If still `ok: false`, tell the user to run `okstra-setup` and stop.
+
+> If the `okstra` binary is not on `PATH` at all, the command above will not run. In that case tell the user verbatim: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list this skill targets and will force a confirmation prompt on every subsequent call.
 
 ## Step 1: Choose input source
 

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

@@ -26,27 +26,18 @@ If the user is ambiguous, ask. Defaulting to the wrong one either wastes a fresh
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Read the Task Catalog
 

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

@@ -36,57 +36,41 @@ multi-MB logs; analysis-phase dispatches are typically smaller.
 
 ## Step 0: Verify okstra runtime + project setup
 
-Before any other step, ensure both the okstra runtime and the current
-project's okstra metadata are in place:
+Before any other step, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string and use it as the search root for the steps below.
 
-Parse `projectRoot` from the JSON and use it as the search root for the
-steps below.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Inventory
 
 Find all wrapper log files and collect metadata. Use a single `find` to
 keep the I/O cost predictable, then format the results.
 
-```bash
-PROJECT_ROOT=$(echo "$OKSTRA_PROJECT_INFO" | python3 -c 'import sys,json;print(json.load(sys.stdin)["projectRoot"])')
-LOGS_ROOT="$PROJECT_ROOT/.project-docs/okstra/tasks"
+Construct the logs root by appending `/.project-docs/okstra/tasks` to the literal `projectRoot` value parsed in Step 0, and paste it as a literal absolute path in place of `<LOGS_ROOT>` below (no shell variables, no `$(...)`):
 
-# columns: size_bytes | mtime_epoch | path
-find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' \
+```bash
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' \
   -printf '%s\t%T@\t%p\n' 2>/dev/null \
   | sort -k1,1nr
 ```
 
-On macOS, `find -printf` is unavailable. Fall back to `stat`:
+The columns produced are `size_bytes | mtime_epoch | path`.
+
+On macOS, `find -printf` is unavailable. Fall back to `-exec stat` — again substitute the literal `<LOGS_ROOT>`. The `-exec ... {} +` form contains no shell variables and no `$(...)`, so the `Bash(find:*)` permission match holds:
 
 ```bash
-find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' 2>/dev/null \
-  | while IFS= read -r p; do
-      stat -f '%z%t%m%t%N' "$p"
-    done \
-  | sort -k1,1nr
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' -exec stat -f '%z%t%m%t%N' {} + 2>/dev/null | sort -k1,1nr
 ```
 
-If the result is empty, report `No wrapper log files found under <PROJECT_ROOT>` and exit.
+If the result is empty, report `No wrapper log files found under <projectRoot>` and exit.
 
 ## Step 2: Summary table
 

package/runtime/skills/okstra-report-finder/SKILL.md

@@ -14,27 +14,18 @@ user-invocable: false
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+각 명령은 **별도 Bash tool call** 로 실행한다. 모든 명령은 리터럴 `okstra` 토큰으로 시작해 `Bash(okstra:*)` 권한 매칭을 통과해야 한다. `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, `&&` 로 감싸지 말고, `$OKSTRA_CMD` 변수나 `npx -y okstra@latest` 폴백도 도입하지 않는다 — 첫 토큰이 비리터럴이면 권한 매칭이 깨져 호출마다 확인 프롬프트가 뜬다. 각 명령의 출력은 LLM(너) 이 보고 자연어로 분기 판단을 한다 — shell 분기는 쓰지 않는다.
+
+1. `okstra ensure-installed`
+   비정상 종료 → 사용자에게 그대로 안내: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 그리고 중단. 폴백으로 `npx -y okstra@latest ...` 를 호출하지 않는다.
+
+2. `okstra check-project --json`
+   현재 작업 디렉터리 기준 프로젝트를 읽는다. stdout 의 JSON shape: `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → 사용자에게 "this project has no okstra setup. Run `/okstra-setup` first." 안내 후 중단.
+   - `ok: true` → `projectRoot` 를 리터럴 문자열로 들고 catalog/manifest 위치를 잡는다.
 
-`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`) —
-`projectRoot` 로 catalog/manifest 위치를 잡는다.
+후속 `okstra <subcmd>` 호출은 Python path 를 자체 부트스트랩하므로 본 스킬은 `okstra paths --shell` / `export PYTHONPATH=...` 를 필요로 하지 않는다.
 
 ## Step 1: Task Key로 Report 경로 찾기
 

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

@@ -37,30 +37,18 @@ If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadF
 
 ## Preflight: Verify okstra runtime + project setup
 
-Run before anything else in this skill:
+Before anything else in this skill, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json` and the task-group directory.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`
-and the task-group directory.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Process Procedure
 

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

@@ -53,44 +53,32 @@ Show the final summary line back to the user (`version stamp: x.y.z`).
 If install fails, surface the stderr verbatim. Do NOT try to "fix" it by
 running the legacy `okstra-install.sh` — that path is dev-only.
 
-## Step 2: Load runtime paths
+## Step 2: Load runtime paths (no-op)
 
-```bash
-# Prefer PATH-resolved okstra (npm-installed) over npx — avoids per-call registry lookup.
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-```
+After `okstra install`, every `okstra <subcmd>` call self-bootstraps its Python path, so this skill does NOT run `okstra paths --shell` / `eval ...` / `export PYTHONPATH=...`. The previously-set `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`, `$OKSTRA_BIN`, `$OKSTRA_HOME` env vars are NOT set by this skill. If a later step needs one of those paths, call `okstra paths --json` as a **separate Bash tool call** (literal-token-first) and read the value from JSON output.
 
-After this, `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`,
-`$OKSTRA_BIN`, `$OKSTRA_HOME` are all set. Do not hardcode any of these — read
-them from the env vars.
+**Bash invocation rule (permission-friendly)**: from this step on, every Bash command in this skill MUST begin with the literal token `okstra` and pass literal argument values. Do not introduce shell variables (`$PROJECT_ROOT`, `$PROJECT_ID`, ...), `$(...)` command substitution, leading `VAR=...` assignments, or wrap commands in `if`/`eval`/`||`/`&&` — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
 
 ## Step 3: Resolve PROJECT_ROOT
 
 ```bash
-PROJECT_ROOT=$(okstra check-project --cwd "$(pwd)" | jq -r '.projectRoot')
+okstra check-project --json
 ```
 
-The JSON includes `projectRoot` on success. Bind it into the shell so
-Step 4 onwards can expand `$PROJECT_ROOT`. On failure (`ok: false`,
-`stage: "resolve"`) ask the user (`AskUserQuestion`, free text) for an
-absolute project root and rerun with `--cwd <their answer>`.
+Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId, stage?}`.
+
+- `ok: true` → carry `projectRoot` as a literal absolute string and paste it into every subsequent command in this skill.
+- `ok: false`, `stage: "resolve"` → ask the user (`AskUserQuestion`, free text) for an absolute project root and rerun as a separate Bash tool call with the literal absolute path:
+
+  ```bash
+  okstra check-project --cwd /abs/path/from/user --json
+  ```
 
 ## Step 4: Inspect or create `project.json`
 
-```bash
-PROJECT_JSON="$PROJECT_ROOT/.project-docs/okstra/project.json"
-if [ -f "$PROJECT_JSON" ]; then
-  cat "$PROJECT_JSON"
-fi
-```
+Use the `Read` tool on the literal absolute path `<projectRoot>/.project-docs/okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 3). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
 
-If the file exists, print its `projectId`/`projectRoot` and ask whether to
+If the file exists, surface its `projectId`/`projectRoot` and ask whether to
 keep or overwrite. Default is to keep — okstra refuses to change `projectId`
 on an existing project (see `okstra_project.resolver.upsert_project_json`),
 so overwriting requires manually deleting the file first.
@@ -104,10 +92,10 @@ If the file does NOT exist, ask via `AskUserQuestion`:
   `error: --project-id is required (no existing project.json, not a TTY)`,
   so passing the user's empty answer through is a silent failure path.
 
-Then create the file:
+Then create the file — paste the literal `projectRoot` from Step 3 and the literal `projectId` from the user's answer (no shell variables):
 
 ```bash
-okstra setup --yes --project-root "$PROJECT_ROOT" --project-id "$PROJECT_ID"
+okstra setup --yes --project-root /abs/path/to/projectRoot --project-id my-project-id
 ```
 
 > After this, **Steps 4.5–4.8 are all optional**. The built-in defaults
@@ -266,7 +254,7 @@ If the user chose `나중에`, tell them they can register later with one of:
 ## Step 5: Verify
 
 ```bash
-$OKSTRA_CMD doctor
+okstra doctor
 ```
 
 If all checks return `OK`, the setup is complete. If any check fails, surface

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

@@ -13,30 +13,18 @@ description: Use when the user asks for overall okstra task status, current life
 
 ## Step 0: Verify okstra runtime + project setup
 
-Before any other step, ensure both the okstra runtime and the current
-project's okstra metadata are in place:
-
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+Before any other step, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string into the steps below; reuse it instead of re-resolving.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-parse and reuse it instead of re-resolving in the steps below.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Overall Project Status
 
@@ -255,4 +243,4 @@ This skill updates `task-manifest.json` only. `discovery/task-catalog.json` may
 
 ## Out-of-Scope Backlog
 
-- **Step 0 boilerplate duplication.** The `ensure-installed` + `paths --shell` + `check-project --json` preamble is byte-identical across every user-facing okstra skill. The Claude Code skill framework has no include/snippet mechanism today, so each skill duplicates the block. A future change should either (a) extract the preamble into a single `okstra preflight` subcommand the skill can call in one line, or (b) ship the block as a shared SKILL fragment if the framework gains include support. Not actionable inside this skill alone.
+- **Step 0 boilerplate duplication.** The `ensure-installed` + `check-project --json` preamble (literal-token-first, separate Bash calls) is near-identical across every user-facing okstra skill. The Claude Code skill framework has no include/snippet mechanism today, so each skill duplicates the prose. A future change should either (a) extract the preamble into a single `okstra preflight` subcommand the skill can call in one line, or (b) ship the block as a shared SKILL fragment if the framework gains include support. Not actionable inside this skill alone.

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -432,15 +432,13 @@ Token usage is collected from agent session transcripts after the run, NOT from
 
 ### How to Collect
 
-At the **start of Phase 7** (persistence), run the helper script with the path to this run's `team-state.json`:
+At the **start of Phase 7** (persistence), run the helper via the okstra CLI with the path to this run's `team-state.json`. Substitute `<runDirectoryPath>` with a literal absolute path (no shell variables, no `$(...)`) so the `Bash(okstra:*)` permission match holds:
 
 ```bash
-python3 "$HOME/.okstra/lib/python/okstra-token-usage.py" \
-  <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
-  --write --summary
+okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --write --summary
 ```
 
-The script is installed at `$HOME/.okstra/lib/python/okstra-token-usage.py` by `okstra install`. The previous repo-relative path (`scripts/okstra-token-usage.py`) only exists in a working clone of the okstra repo and is not appropriate for end-user-deployed runs.
+`okstra token-usage` is a thin Node-side wrapper around the python helper installed at `~/.okstra/bin/okstra-token-usage.py`. Calling the python script directly with `python3 "$HOME/..."` is forbidden — the `$HOME` expansion breaks the literal-token permission match and forces a confirmation prompt every call.
 
 The script reads:
 - `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`).

package/runtime/skills/okstra-time-summary/SKILL.md

@@ -29,27 +29,18 @@ If a run never reached Phase 7, its `team-state` will not have `durationMs` fill
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
 
-`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`)
-gives `projectRoot` for locating `.project-docs/okstra/discovery/task-catalog.json`.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Resolve task-id → timeline path
 

package/src/token-usage.mjs

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { promises as fs } from "node:fs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra token-usage — collect token usage for a run
+
+Wraps the python helper (\`okstra-token-usage.py\`) installed under
+\`~/.okstra/bin/\` so skills can call this command without emitting a
+shell-expansion-bearing \`python3 "$HOME/..."\` invocation (which would
+break \`Bash(okstra:*)\` permission matching and force a confirmation
+prompt every call).
+
+Usage:
+  okstra token-usage <state-file> [--write] [--summary] [...]
+
+Arguments and flags after the state-file path are forwarded verbatim to
+the python helper. See \`python3 ~/.okstra/bin/okstra-token-usage.py --help\`
+for the full option list.
+`;
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+
+  const paths = await resolvePaths();
+  const script = join(paths.bin, "okstra-token-usage.py");
+
+  try {
+    await fs.access(script);
+  } catch {
+    process.stderr.write(
+      `error: ${script} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
+    );
+    return 1;
+  }
+
+  return await new Promise((resolve) => {
+    const child = spawn("python3", [script, ...args], {
+      stdio: "inherit",
+      env: { ...process.env, PYTHONPATH: paths.pythonpath },
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
+  });
+}