okstra 0.10.0 → 0.11.0

package/README.kr.md

@@ -109,6 +109,8 @@ okstra install         # 'npx -y okstra@latest install' 와 동일
 
 글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 Claude 스킬(`~/.claude/skills/`) 은 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
 
+**글로벌 설치 시 스킬 동작.** 모든 okstra 스킬은 PATH 에 잡힌 `okstra` 를 자동 감지하여 `npx -y okstra@latest` 대신 우선 사용합니다. 즉 글로벌 설치를 해두면 매 스킬 호출(`okstra-run`, `okstra-status`, `okstra-history`, `okstra-schedule`, `okstra-report-finder`, `okstra-time-summary`, `okstra-setup` Step 2 의 Step 0) 마다 npx 가 패키지 fetch / 버전 체크하던 비용이 사라집니다. 스킬이 본인이 설치한 버전을 그대로 쓰므로 **업그레이드 타이밍은 사용자가 통제** 합니다 — 더 이상 호출마다 `@latest` 가 강제되지 않습니다. 새 릴리스를 받으려면 원하는 시점에 `npm i -g okstra@latest && okstra install` 을 실행하세요. `okstra` 가 PATH 에 없으면 스킬은 자동으로 npx fallback 으로 동작하므로 글로벌 설치가 없는 환경에서도 변경 없이 그대로 동작합니다.
+
 ### 3.2 프로젝트 등록 (프로젝트당 1회)
 
 CLI 에서:

package/README.md

@@ -108,6 +108,8 @@ okstra install         # same as 'npx -y okstra@latest install'
 
 The global install only registers the Node CLI on your PATH. The runtime (`~/.okstra/`) and the Claude skills (`~/.claude/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To upgrade later: `npm i -g okstra@latest && okstra install`. To remove the global binary: `npm uninstall -g okstra` (leaves `~/.okstra/` untouched; remove that with `okstra uninstall`).
 
+**Skill behaviour with a global install.** All okstra skills auto-detect a PATH-resolved `okstra` and prefer it over `npx -y okstra@latest`. That means a global install removes the per-call npx fetch / version-check from every skill invocation (Step 0 of `okstra-run`, `okstra-status`, `okstra-history`, `okstra-schedule`, `okstra-report-finder`, `okstra-time-summary`, `okstra-setup` Step 2). Since the skill uses your globally installed version directly, *you* control upgrade timing — `@latest` is no longer forced on each call. Run `npm i -g okstra@latest && okstra install` whenever you want to pull a new release. If `okstra` is not on PATH the skill silently falls back to npx, so machines without a global install keep working unchanged.
+
 ### 3.2 Register a project (once per project)
 
 From the CLI:

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.10.0",
-  "builtAt": "2026-05-12T16:26:44.380Z",
+  "package": "0.11.0",
+  "builtAt": "2026-05-12T17:46:50.784Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -160,8 +160,9 @@ These phases are governed by [okstra-team-contract](./skills/okstra-team-contrac
 
 1. Call `TeamCreate(team_name: "okstra-<task-key>", description: "Lead-plus-worker okstra run for <task-key>")`.
 2. Record the `TeamCreate` outcome in team-state under `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }` before any dispatch. This is the audit trail that justifies a later no-`team_name` fallback.
-3. If `TeamCreate` succeeds, proceed to Phase 4 (dispatch with `team_name`).
-4. If `TeamCreate` fails (tool unavailable, permission denied, environment lacks Agent Teams support), proceed to Phase 5 fallback (dispatch with `run_in_background: true` and no `team_name`).
+3. Verify `team-state.lead.sessionId` is populated. The `okstra.sh` exec path fills it automatically (`generate_claude_session_id` → `claude --session-id ...`). The render-only / in-session takeover path (`okstra-run` skill) auto-detects the live session's jsonl via `resolve_inproc_lead_session_id`, but the detector is best-effort and may return empty if `~/.claude/projects/<encoded-cwd>/` is unreadable or has no jsonl yet. If `lead.sessionId` is empty at this point, write the running session's id into team-state before proceeding — Phase 7 token-usage collection depends on it and will fail with `lead jsonl not found (sessionId=)` otherwise.
+4. If `TeamCreate` succeeds, proceed to Phase 4 (dispatch with `team_name`).
+5. If `TeamCreate` fails (tool unavailable, permission denied, environment lacks Agent Teams support), proceed to Phase 5 fallback (dispatch with `run_in_background: true` and no `team_name`).
 
 Use agent and subagent names that map cleanly to the selected worker roles. Do not create ambiguous role names that differ from `Claude worker`, `Codex worker`, `Gemini worker`, or `Report writer worker`.
 

package/runtime/prompts/launch.template.md

@@ -14,6 +14,32 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 - Phase advancement requires a new okstra invocation launched with `--task-type {{WORKFLOW_NEXT_RECOMMENDED_PHASE}}` after this run's final report is written and approved. The lead must not write source code, run builds/migrations/deployments, or otherwise produce artifacts of a different phase from inside this run.
 - See `Lifecycle Phase Boundaries` in the okstra skill (`agents/SKILL.md`) for the canonical rules and the phase-transition checklist.
 
+## Team Creation Gate (BLOCKING)
+
+Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the
+`okstra` skill (`agents/SKILL.md` → "Phase 3 — Team creation"). Skipping
+this gate silently degrades the run to in-process background dispatch and
+loses the Teams split-pane observability surface, even though worker
+outputs may still appear correct on disk.
+
+Required actions, in order, regardless of how many workers are selected
+for this run (roster comes from `resultContract.requiredWorkerRoles` in
+`task-manifest.json` — it may be 1, 2, 3, or more workers):
+
+1. Invoke the `okstra-team-contract` skill and verify the selected worker
+   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.
+2. Call `TeamCreate(team_name: "okstra-{{TASK_KEY}}", description: ...)`.
+3. Record the outcome in team-state under
+   `teamCreate: { attempted: true, status: "ok" | "error", error?: <msg> }`
+   BEFORE any `Agent(...)` worker dispatch.
+4. Only after `teamCreate` is persisted may you dispatch workers — with
+   `team_name` on success, or with `run_in_background: true` and no
+   `team_name` ONLY when `teamCreate.status == "error"` was recorded.
+
+If the Agent tool rejects a dispatch with `"team must be created first"` /
+`"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct
+response is to go back to step 2 — NOT to strip `team_name` and retry.
+
 ## Project Root
 
 - Absolute project root: `{{PROJECT_ROOT}}`

package/runtime/python/okstra_ctl/run.py

@@ -51,7 +51,11 @@ from .seeding import (
     render_runtime_settings_file,
     verify_installation,
 )
-from .session import generate_claude_session_id, write_claude_resume_command_file
+from .session import (
+    generate_claude_session_id,
+    resolve_inproc_lead_session_id,
+    write_claude_resume_command_file,
+)
 from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
 from .worktree import provision_implementation_worktree
@@ -537,7 +541,16 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "EXECUTOR_WORKTREE_NOTE": worktree.note,
     })
 
-    claude_session_id = "" if inp.render_only else generate_claude_session_id()
+    if inp.render_only:
+        # render-only entry path (e.g. okstra-run skill, in-session takeover):
+        # the calling Claude session itself becomes the lead, so we must NOT
+        # mint a fresh UUID — instead, best-effort detect the live session's
+        # jsonl under ~/.claude/projects/<encoded-cwd>/. Leaving this blank
+        # caused Phase 7 token-usage collection to fail (lead jsonl not
+        # found) and the validator to report `sessionId=`.
+        claude_session_id = resolve_inproc_lead_session_id(project_root)
+    else:
+        claude_session_id = generate_claude_session_id()
 
     # ---- material + related-tasks ----
     profile_content = _expand_profile_includes(profile_file)

package/runtime/python/okstra_ctl/session.py

@@ -15,6 +15,39 @@ def generate_claude_session_id() -> str:
     return str(uuid.uuid4())
 
 
+def _claude_projects_dir_for(cwd: Path) -> Path:
+    """Mirror of `okstra_token_usage.paths.claude_project_dir` — kept local to
+    avoid a cross-package import inside the run path.
+    """
+    encoded = "-" + str(cwd).strip("/").replace("/", "-")
+    return Path.home() / ".claude" / "projects" / encoded
+
+
+def resolve_inproc_lead_session_id(project_root: Path) -> str:
+    """Best-effort detection of the running Claude session's id when okstra is
+    invoked render-only from inside a live session (the `okstra-run` skill
+    path). The current session's jsonl is being actively written to under
+    `~/.claude/projects/<encoded-cwd>/`, so the most recently modified file
+    in that directory is, with very high probability, the calling session.
+
+    Returns the UUID stem on success, empty string on failure (directory
+    missing, no jsonl files, permission error). Callers must treat this as
+    best-effort — a failure does not invalidate the session, it just means
+    auto-detection could not confirm one.
+    """
+    try:
+        d = _claude_projects_dir_for(project_root)
+        if not d.exists():
+            return ""
+        candidates = [p for p in d.iterdir() if p.suffix == ".jsonl"]
+        if not candidates:
+            return ""
+        newest = max(candidates, key=lambda p: p.stat().st_mtime)
+        return newest.stem
+    except OSError:
+        return ""
+
+
 def write_claude_resume_command_file(
     *, resume_command_path: Path, project_root: Path, claude_session_id: str,
 ) -> None:

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

@@ -14,13 +14,18 @@ description: Use when the user asks to list past okstra runs, check execution hi
 ## 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/skills/okstra-report-finder/SKILL.md

@@ -15,13 +15,18 @@ user-invocable: false
 ## 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/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):