okstra 0.10.0 → 0.12.0

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

@@ -36,18 +36,26 @@ Do NOT hard-code or guess any okstra path. Every run loads them fresh from
 the single authority — `okstra`:
 
 ```bash
+# 0) Resolve runner: prefer PATH (npm-installed) over npx (avoids per-call registry lookup).
+#    If the user installed okstra via npm, they control upgrade timing — do not force @latest.
+if command -v okstra >/dev/null 2>&1; then
+  OKSTRA_CMD="okstra"
+else
+  OKSTRA_CMD="npx -y okstra@latest"
+fi
+
 # 1) Ensure runtime is fresh (idempotent, cached when up-to-date)
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+$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
 }
 
 # 2) Load all runtime paths into the shell as OKSTRA_* exports
-eval "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
 
 # 3) Verify the current project has okstra metadata (project.json + projectId)
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+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

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

@@ -40,13 +40,18 @@ If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadF
 Run before anything else in this skill:
 
 ```bash
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+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 "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+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

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

@@ -55,7 +55,13 @@ running the legacy `okstra-install.sh` — that path is dev-only.
 ## Step 2: Load runtime paths
 
 ```bash
-eval "$(npx -y okstra@latest paths --shell)"
+# 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"
 ```
 
@@ -113,7 +119,7 @@ PY
 ## Step 5: Verify
 
 ```bash
-npx -y okstra@latest doctor
+$OKSTRA_CMD doctor
 ```
 
 If all checks return `OK`, the setup is complete. If any check fails, surface

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

@@ -17,13 +17,18 @@ Before any other step, ensure both the okstra runtime and the current
 project's okstra metadata are in place:
 
 ```bash
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+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 "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+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

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

@@ -30,13 +30,18 @@ If a run never reached Phase 7, its `team-state` will not have `durationMs` fill
 ## Step 0: Verify okstra runtime + project setup
 
 ```bash
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+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 "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+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

package/runtime/validators/validate-run.py

@@ -324,6 +324,28 @@ def validate_team_state(
         failures.append("team-state.workers must be a list")
         return
 
+    dispatched_statuses = {"completed", "timeout", "error", "in-progress"}
+    any_dispatched = any(
+        isinstance(w, dict) and str(w.get("status", "")).strip() in dispatched_statuses
+        for w in workers
+    )
+    if any_dispatched:
+        team_create = team_state.get("teamCreate")
+        if not isinstance(team_create, dict) or not team_create.get("attempted"):
+            failures.append(
+                "team-state.teamCreate.attempted must be true once any worker has "
+                "been dispatched (status in completed/timeout/error/in-progress). "
+                "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
+                "the Teams split-pane surface. See agents/SKILL.md Phase 3."
+            )
+        else:
+            tc_status = str(team_create.get("status", "")).strip()
+            if tc_status not in {"ok", "error"}:
+                failures.append(
+                    "team-state.teamCreate.status must be `ok` or `error` once "
+                    f"workers have been dispatched (found: `{tc_status}`)."
+                )
+
     by_role: dict[str, dict] = {}
     for worker in workers:
         if not isinstance(worker, dict):