okstra 0.30.2 → 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.2",
+  "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.2",
-  "builtAt": "2026-05-19T06:29:56.728Z",
+  "package": "0.30.3",
+  "builtAt": "2026-05-19T08:41:16.438Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -64,14 +64,10 @@ find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' \
 
 The columns produced are `size_bytes | mtime_epoch | path`.
 
-On macOS, `find -printf` is unavailable. Fall back to `stat` — again substitute the literal `<LOGS_ROOT>`:
+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 <projectRoot>` and exit.

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