okstra 0.30.2 → 0.31.0

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

@@ -70,7 +70,7 @@ Every worker prompt MUST start with the following anchor headers, in this exact
 
 1. `**Project Root:** <absolute-path>` — absolute target project root (from `{{PROJECT_ROOT}}` in the lead's prompt). Required so the worker can self-anchor without relying on inherited cwd.
 2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>`
+3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file. Workers resolve it to absolute against `**Project Root:**` and use it for the post-completion existence check (see codex-worker / gemini-worker step 8c, and Lead's redispatch policy below). The path identifies a single file; do NOT deliver a directory.
 4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex/Gemini wrapper subagents extract this exact line.
 
 The body must include: role name, task type, task key, required bundle paths, assigned model, output contract, evidence handling rules, and any relevant config/deployment expectations from `reference-expectations.md`.
@@ -209,6 +209,29 @@ Terminal statuses that can be recorded for a worker:
 | `error` | Execution error, reason recorded; prompt history file must exist |
 | `not-run` | Not executed, reason recorded |
 
+## Lead Redispatch Policy on Result-Missing
+
+After each worker subagent returns (regardless of role), Lead MUST verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` anchor header (against `**Project Root:**`). The check is identical for in-process workers (claude-worker) and CLI-wrapper workers (codex-worker / gemini-worker).
+
+**Triggers (any of):**
+
+- The wrapper subagent returned an explicit `*_RESULT_MISSING` sentinel (codex-worker / gemini-worker step 8c — `CODEX_RESULT_MISSING` / `GEMINI_RESULT_MISSING`).
+- The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/gemini sub-agent forwarded raw stdout despite the contract.
+- The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
+
+**One-retry policy:**
+
+1. On the FIRST result-missing trigger for a given role within a single run, Lead MUST re-dispatch the same worker with the byte-identical prompt — same `**Result Path:**`, same `**Prompt History Path:**`, same model assignment, same `team_name`. The redispatch counts as a second attempt against the existing role slot; do NOT create a new role-id, do NOT change the result file path, do NOT switch to a different model as a "workaround".
+2. If the SECOND attempt also fails the same check, Lead records the role's terminal status as `error` with `--message "result-missing after 1 retry"` and proceeds to Phase 5.5 / Phase 6 with the remaining workers' results. Lead MUST NOT retry a third time — convergence and the report writer are designed to operate on reduced-confidence single-or-two-analyser mode when one role is absent (`agents/SKILL.md` "If only one worker result is usable: reduced-confidence synthesis").
+3. The retry counter is **per-run, per-role** and is NOT preserved across runs. A subsequent okstra run for the same task-key starts each role's counter fresh.
+4. Convergence reverify rounds (Phase 5.5) inherit the same one-retry budget — a reverify dispatch that triggers result-missing may be re-dispatched once.
+
+**Logging.** Lead records the first attempt's `cli-failure` (already emitted by the wrapper sub-agent) as-is. The retry, on success, is logged via the normal worker-completion path; on failure (second `*_RESULT_MISSING`), Lead records a single `contract-violation` entry with `--message "result-missing after 1 retry"` referencing both attempts' bash_ids / prompt-history paths.
+
+**Diagnostic sidecar (advisory).** Both codex/gemini wrappers also write a heartbeat sidecar at `<prompt-path>.status.json` recording `started_ts`, `ended_ts`, `exit_code`, `duration_ms`, and the canonical `log_path` (see `scripts/okstra-wrapper-status.py` for the schema). Lead MAY read this sidecar when deciding whether the first attempt actually launched the CLI (stage=`exited`, `exit_code=0`, non-zero `duration_ms`) versus failed before reaching it (sidecar absent, or stage=`started` with no exit fields). The sidecar is best-effort — its absence is NOT by itself a reason to skip the retry; the canonical trigger remains the missing result file.
+
+**Rationale.** Observed failure mode: the CLI (codex/gemini) streams its full analysis to stdout but hits its token budget or a sandbox EPERM mid-`Write` of the result file, exiting 0 with no artifact. Forwarding the partial stdout silently degrades synthesis; classifying the role as `error` without retrying gives up a recoverable signal. A single retry catches the transient class of this failure (re-dispatch with the same prompt typically succeeds when the underlying cause was an intermittent sandbox lock or a token-budget spike) while bounding the retry cost to a known upper bound (~2× the original wrapper budget per role).
+
 ## Worker Output Contract
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
@@ -355,8 +378,9 @@ empty run-level error logs in production.
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
   - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.
-  - 30-minute polling cap exceeded: call `KillShell(shell_id)` first, then record `cli-failure` with `--exit-code 124 --duration-ms 1800000 --message "<wrapper> exceeded 30m polling cap"`, then return the language-specific `*_CLI_TIMEOUT` sentinel.
+  - Polling cap reached: before `KillShell`, perform a one-shot **mtime-grace check** on the wrapper's live log (`<prompt>.log`). If the log was written within the last 90 seconds AND grace has not yet been applied this loop, extend the cap from 1800s → 2100s (one-shot +5min) and continue polling. Otherwise (log stale, OR grace already applied), call `KillShell(shell_id)`, record `cli-failure` with `--exit-code 124 --duration-ms <observed_ms> --message "<wrapper> exceeded polling cap (grace=<applied|not-applied>, last_mtime_age=<n>s)"`, then return the language-specific `*_CLI_TIMEOUT` sentinel. The grace exists to absorb token-budget spikes where the CLI is genuinely still producing output past the 30-minute mark; it is a one-shot soft extension, NOT a loop.
   - Token-usage matching is unaffected: the wrapper subagent stays alive throughout polling, so the wrapper's jsonl timestamp window continues to cover the underlying CLI rollout's full duration (see §"Token-usage accounting" below).
+- **No external timeout on wrapper subagents.** The codex/gemini wrapper subagent's polling loop (with optional mtime grace) is the SINGLE timeout authority for its dispatch. Lead MUST NOT impose a separate `Agent()` call timeout, an outer `Bash` wall-clock deadline, or any other mechanism that terminates the subagent before its own polling cap is reached. Doing so reproduces the historical failure mode that motivated this rule: Lead aborts the subagent at e.g. 18 minutes, the subagent returns nothing, and Lead classifies the role as "no response" while the underlying CLI was actively working. The wrapper's polling cap (30min + optional 5min grace) is calibrated so that, combined with Lead's redispatch policy (see "Lead Redispatch Policy on Result-Missing"), a recoverable single-run failure costs at most ~70 minutes of wall-clock — predictable enough to plan around. If a specific run requires a tighter cap, lower it in the wrapper subagent's polling contract (single source of truth), NOT by layering Lead-side timeouts.
 - `contract-violation` events (C) are recorded by Lead via `okstra-error-log.py append-observed --error-type contract-violation ...` after inspecting worker outputs.
 - Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra-error-log.py append-from-worker` after each worker terminates; Lead does not write into the sidecar.
 
@@ -419,7 +443,7 @@ Examples:
 **Task:** error-analysis
 **Target:** server/auth.ts
 **Date:** 2026-04-06
-**Model:** Report writer worker, opus
+**Model:** Report writer worker, opus-4-6
 ```
 
 Use the actual model identifier recorded in team-state (never invent a model ID — read it from `resultContract.requiredWorkerRoles[*].modelExecutionValue` or the tool response metadata).
@@ -432,15 +456,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/templates/reports/final-report.template.md

@@ -599,22 +599,28 @@ Empty-state placeholder (copy verbatim when nothing else applies): `- No further
 
 ## 7. Follow-up Tasks (후속 작업)
 
-본 run 의 구현·검증 범위를 **넘어서는** 작업을 후속 task 로 이어가기 위한 표.
+본 run 이 끝난 뒤 사용자가 이어갈 모든 task 를 한 표에 정리. 두 종류가 동거합니다:
 
-- `task-type` = `implementation` / `final-verification` / `release-handoff`: **필수**. 채울 항목이 없으면 표 대신 `- 후속 작업 없음.`
-- 그 외 task-type: 선택. lead 가 필요하다고 판단할 때만.
+1. **phase-continuation row (필수)** — 본 task 의 다음 phase. `Suggested task-type` 은 `## 2. Final Verdict` 의 다음 phase 와 byte-identical. `Auto-spawn? = no` 로 고정 (다음 phase 는 사용자가 `/okstra-run` 으로 직접 진입하며, spawn 스크립트가 task 디렉토리를 자동 생성하지 않음).
+2. **scope-boundary row (선택)** — 본 run 의 구현·검증 범위를 **넘어서는** 작업. lead 가 필요하다고 판단할 때만.
 
-후속 항목 출처: `out-of-plan` / `verifier-concern` / `scope-boundary` / `open-question` / `manual` 중 하나.
+phase-continuation row 의무 적용 범위:
 
-규칙: `Auto-spawn? = yes` 인 row 는 Phase 7 의 `scripts/okstra-spawn-followups.py` 가 자동으로 `tasks/<TASK_GROUP>/<New Task ID>/` 디렉터리 + `task-manifest.json` (status: `todo`) + stub task-brief 를 생성. `no` 는 사람이 처리. `New Task ID` 는 task-group 내 유일한 알파숫자·하이픈 slug. 동일 follow-up 이 여러 run 에 등장하면 `New Task ID` 를 동일하게 유지하여 중복 spawn 방지.
+- `task-type` ∈ {`requirements-discovery`, `implementation-planning`, `error-analysis`, `implementation`, `final-verification`}: **필수**. 다음 phase 가 자명하므로 phase-continuation row 한 개를 반드시 채움.
+- `release-handoff`: 다음 phase 없음 → phase-continuation 생략. scope-boundary row 만 (있다면) 채움.
+
+후속 항목 출처(`Origin` 컬럼): `phase-continuation` / `out-of-plan` / `verifier-concern` / `scope-boundary` / `open-question` / `manual` 중 하나.
+
+규칙: `Auto-spawn? = yes` 인 row 는 Phase 7 의 `scripts/okstra-spawn-followups.py` 가 자동으로 `tasks/<TASK_GROUP>/<New Task ID>/` 디렉터리 + `task-manifest.json` (status: `todo`) + stub task-brief 를 생성. `no` 는 사람이 처리. `phase-continuation` row 는 항상 `no` — 같은 task-key 를 재사용하여 다음 phase 로 진입하므로 새 task 디렉터리를 만들면 안 됨. `New Task ID` 는 task-group 내 유일한 알파숫자·하이픈 slug(phase-continuation row 의 경우 현재 task-id 를 그대로 사용). 동일 follow-up 이 여러 run 에 등장하면 `New Task ID` 를 동일하게 유지하여 중복 spawn 방지.
 
 | ID | Ticket ID | Origin | New Task ID | Title | Suggested task-type | Scope (files/areas) | Reason / Why deferred | Priority (P0/P1/P2) | Auto-spawn? |
 |----|-----------|--------|-------------|-------|---------------------|---------------------|------------------------|---------------------|-------------|
-| FU-001 | `<TICKET-or-fallback>` | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
+| FU-001 | `<TICKET-or-fallback>` | `phase-continuation` | `<current-task-id>` | <다음 phase 진입 요약> | `<next-task-type>` | `<scope summary>` | <다음 phase 가 자동으로 추천되는 사유 한 줄> | `P0` | `no` |
+| FU-002 | `<TICKET-or-fallback>` | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
 
-빈 상태: `- 후속 작업 없음.`
+빈 상태(phase-continuation 의무가 없는 task-type 이고 scope-boundary 도 없을 때): `- 후속 작업 없음. 본 run 의 다음 phase 는 §6 (Recommended Next Steps) 참고.`
 
-본 섹션이 채워진 경우 Section 6 의 "Follow-up tasks" 항목에 자동 생성된 task-key 와 진입 명령을 함께 적어 사용자가 즉시 이어갈 수 있게 합니다.
+본 섹션이 채워진 경우 Section 6 의 "Follow-up tasks" 항목에 진입 명령(phase-continuation 은 `/okstra-run` 형태, auto-spawn 된 row 는 새 task-key)을 함께 적어 사용자가 즉시 이어갈 수 있게 합니다.
 
 ## Writing Rules
 

package/runtime/templates/reports/report.css

@@ -41,11 +41,38 @@ body {
 .report-header > div { flex: 1; font-weight: 600; }
 
 main {
-  max-width: 80ch;
+  max-width: 120ch;
   margin: 1.5rem auto;
   padding: 0 1rem 4rem;
 }
 
+nav.toc {
+  margin: 1rem 0 2rem;
+  padding: 0.6em 1em;
+  border: 1px solid color-mix(in srgb, GrayText 40%, transparent);
+  border-radius: 4px;
+  background: color-mix(in srgb, CanvasText 4%, transparent);
+}
+nav.toc .toc-title {
+  font-weight: 600;
+  margin-bottom: 0.4em;
+  font-size: 0.95rem;
+}
+nav.toc ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  columns: 2;
+  column-gap: 1.5em;
+}
+@media (max-width: 60ch) {
+  nav.toc ul { columns: 1; }
+}
+nav.toc li { margin: 0.15em 0; break-inside: avoid; }
+nav.toc li.toc-h3 { padding-left: 1.2em; font-size: 0.92em; }
+nav.toc a { color: inherit; text-decoration: none; }
+nav.toc a:hover { text-decoration: underline; }
+
 h1, h2, h3, h4, h5, h6 { line-height: 1.25; margin-top: 1.6em; margin-bottom: 0.4em; }
 h1 { font-size: 1.7rem; }
 h2 { font-size: 1.35rem; border-bottom: 1px solid GrayText; padding-bottom: 0.2em; }
@@ -88,6 +115,16 @@ th, td {
   padding: 0.45em 0.6em;
   vertical-align: top;
   text-align: left;
+  word-break: keep-all;
+  overflow-wrap: anywhere;
+  min-width: 5ch;
+}
+/* Short single-token cells (<= 20 plain chars) — keep on one line so
+ * status / ID / kind columns do not get squeezed into narrow stacks
+ * by long-form neighbours. Class is applied by report_views._emit_table. */
+td.td-tight, th.td-tight {
+  white-space: nowrap;
+  width: 1%;  /* shrink-to-fit under auto-layout */
 }
 thead th {
   position: sticky;
@@ -105,18 +142,28 @@ tr[data-response-id][data-status="obsolete"] {
   opacity: 0.65;
 }
 
-textarea {
+textarea,
+select[data-response-id],
+input[data-response-id],
+input[data-other-for] {
   width: 100%;
-  min-height: 2.2em;
   font: inherit;
   padding: 0.3em 0.4em;
   border: 1px solid GrayText;
   border-radius: 3px;
   background: Canvas;
   color: CanvasText;
+}
+textarea {
+  min-height: 2.2em;
   resize: vertical;
 }
-textarea[disabled] { opacity: 0.55; }
+input[data-other-for] {
+  margin-top: 0.35em;
+}
+textarea[disabled],
+select[disabled],
+input[disabled] { opacity: 0.55; }
 
 button[data-action] {
   font: inherit;

package/runtime/templates/reports/report.js

@@ -1,10 +1,14 @@
 /* Client-side glue for the okstra final-report HTML view.
  *
  * Responsibilities:
- *   1. Collect <textarea> values for every <tr data-response-id> whose
- *      Status is open/answered (disabled rows are skipped automatically).
- *   2. Serialise them into markdown whose bytes are IDENTICAL to
- *      scripts/okstra_ctl/report_views.py serialize_user_response.
+ *   1. Collect entry values for every <tr data-response-id> whose
+ *      Status is open/answered (disabled rows skipped automatically).
+ *      Widgets: <select> (enum decision), <input data-other-for> (기타
+ *      input revealed when select == "__other__"), <input
+ *      data-response-id> (material/data-point single-line), <textarea>
+ *      (everything else / fallback).
+ *   2. Serialise the entries into markdown whose bytes are IDENTICAL
+ *      to scripts/okstra_ctl/report_views.py serialize_user_response.
  *   3. Write the result to <pre id="user-response-output"> and offer a
  *      [Copy] button.
  *
@@ -36,14 +40,46 @@
     return String(s == null ? "" : s).replace(/^\s+|\s+$/g, "");
   }
 
+  // Read the user-supplied value out of one clarification row. Returns
+  // the empty string when the row has no usable widget, the widget is
+  // disabled, the select sits on its blank "(선택)" placeholder, or the
+  // "기타" branch has an empty input. Caller decides whether to emit
+  // an entry.
+  function readRowValue(row) {
+    var sel = row.querySelector("select[data-response-id]");
+    if (sel) {
+      if (sel.disabled) return "";
+      var picked = sel.value;
+      if (picked === "") return "";
+      if (picked === "__other__") {
+        var rid = sel.getAttribute("data-response-id") || "";
+        var other = row.querySelector('input[data-other-for="' + rid + '"]');
+        return other ? trimMultiline(other.value) : "";
+      }
+      var opt = sel.options[sel.selectedIndex];
+      // Use the visible option text ("(a) one-time backfill") so the
+      // user-response sidecar stays human-readable, not just "a".
+      return opt ? trimMultiline(opt.textContent) : picked;
+    }
+    var ta = row.querySelector("textarea[data-response-id]");
+    if (ta) {
+      if (ta.disabled) return "";
+      return trimMultiline(ta.value);
+    }
+    var inp = row.querySelector("input[data-response-id]");
+    if (inp) {
+      if (inp.disabled) return "";
+      return trimMultiline(inp.value);
+    }
+    return "";
+  }
+
   function collectEntries() {
     var entries = [];
     var rows = document.querySelectorAll("tr[data-response-id]");
     for (var i = 0; i < rows.length; i++) {
       var row = rows[i];
-      var ta = row.querySelector("textarea[data-response-id]");
-      if (!ta || ta.disabled) continue;
-      var value = trimMultiline(ta.value);
+      var value = readRowValue(row);
       if (!value) continue;
       entries.push({
         responseId: row.getAttribute("data-response-id") || "",
@@ -55,6 +91,25 @@
     return entries;
   }
 
+  // Toggle the visibility of the "기타" companion input next to each
+  // select whose current value is "__other__". Wired at bind() time and
+  // also called once for the initial state.
+  function bindOtherInputToggle() {
+    var selects = document.querySelectorAll("select[data-response-id]");
+    for (var i = 0; i < selects.length; i++) {
+      (function (sel) {
+        var rid = sel.getAttribute("data-response-id") || "";
+        var other = document.querySelector('input[data-other-for="' + rid + '"]');
+        if (!other) return;
+        var update = function () {
+          other.hidden = sel.value !== "__other__";
+        };
+        sel.addEventListener("change", update);
+        update();
+      })(selects[i]);
+    }
+  }
+
   function buildUserResponseMarkdown(runMeta, entries, createdAt) {
     var head =
       "---\n" +
@@ -132,6 +187,7 @@
         btn.addEventListener("click", copyUserResponse);
       }
     }
+    bindOtherInputToggle();
   }
 
   if (typeof window !== "undefined") {

package/runtime/templates/reports/settings.template.json

@@ -135,6 +135,7 @@
       "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
       "Bash(STATE_FILE=:*)",
+      "Bash(ROOT=:*)",
 
       "Bash(gemini)",
       "Bash(gemini:*)",

package/src/install.mjs

@@ -25,6 +25,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-token-usage.py",
   "okstra-error-log.py",
   "okstra-render-report-views.py",
+  "okstra-wrapper-status.py",
 ];
 
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra

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));
+  });
+}