okstra 0.78.1 → 0.79.0

package/docs/kr/cli.md

@@ -312,12 +312,17 @@ scripts/okstra.sh --task-type implementation-planning --workers claude,codex --p
 
 Lead 실행 adapter 를 지정합니다. 기본값은 `claude-code` 입니다.
 
+Lead runtime independence boundary:
+
 - `claude-code`: 현재 기본 실행 경로입니다. Claude Code lead 가 `TeamCreate` / `Agent(...)` / Claude session jsonl 기반으로 worker dispatch 와 사용량 집계를 수행합니다.
 - `codex`: Codex lead adapter 용 runtime marker 입니다. `okstra codex-run` 이 `--render-only --lead-runtime codex` 를 소유해 task bundle 을 준비하고, 준비된 run manifest 는 `okstra codex-dispatch` 로 CLI-backed worker 실행에 넘길 수 있습니다.
+- `external`: Claude Code Teams 없이 `--render-only --lead-runtime external` 로 task bundle 과 external lead prompt 를 준비하고, lead 는 `okstra team dispatch` / `okstra team await` / `okstra team teardown` 으로 tmux-pane worker lifecycle 을 관리합니다. 이 path 는 `TeamCreate` / `Agent(...)` 를 쓰지 않고 artifact-only accounting 을 사용합니다.
+
+현재 Claude Code 독립 범위는 external lead prompt + `okstra team *` worker dispatch 입니다. non-render `okstra_ctl.run --lead-runtime external` remains blocked; 완전한 external lead driver 는 아직 별도 구현 대상입니다. `--runtime external` does not install `~/.claude` assets, but selecting a `claude` worker still requires a local Claude CLI wrapper.
 
 Codex lead dry-run 은 `okstra codex-run <args...>` 를 쓰면 됩니다. 이 명령은 `--render-only --lead-runtime codex` 를 직접 붙이고, worker dispatch 없이 준비된 task bundle 과 lead prompt 를 출력합니다.
 생성된 team-state / run-manifest / task-manifest 는 `leadEventsPath` 로 `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl` 를 가리키며, render 단계는 `bundle-prepared` event 를 기록합니다.
-이후 `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> --workers codex[,gemini[,report-writer]]` 가 기존 CLI wrapper 기반 worker 를 실행합니다. `--workers` 를 생략하면 run roster 중 Codex-side 지원 worker(`codex`, `gemini`, opt-in 된 `report-writer`)만 자동 선택하고, `claude` 처럼 지원하지 않는 worker 를 명시 요청하면 실패합니다. `report-writer` 는 명시 opt-in (`--enable-codex-report-writer --report-writer-codex-model <model>`) 이 필요하며, 성공 시 token-usage substitution → render-views → spawn-followups → validate-run 후처리를 순서대로 수행합니다.
+이후 `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> --workers codex[,gemini[,report-writer]]` 가 기존 CLI wrapper 기반 worker 를 실행합니다. `--workers` 를 생략하면 run roster 중 Codex-side 지원 worker(`codex`, `gemini`, opt-in 된 `report-writer`)만 자동 선택하고, 명시 요청하면 미지원 worker 를 실패 처리합니다. `report-writer` 는 명시 opt-in (`--enable-codex-report-writer --report-writer-codex-model <model>`) 이 필요하며, 성공 시 token-usage substitution → render-views → spawn-followups → validate-run 후처리를 순서대로 수행합니다.
 
 Codex worker(`--workers codex`, `--codex-model`)와 Codex lead runtime 은 별개입니다. 전자는 Claude Code lead 가 dispatch 하는 worker provider 선택이고, 후자는 lead 자체를 Codex adapter 로 실행하기 위한 상위 runtime 경계입니다.
 

package/docs/project-structure-overview.md

@@ -106,8 +106,19 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 
 `npm run build` and `prepack` both run this sync. Never hand-edit `runtime/`.
 
+Runtime/install asset changes follow this checklist:
+
+1. Add or edit the source asset under `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas`, `templates`, or `validators`.
+2. Add a `tools/build.mjs` sync mapping when the asset must appear under `runtime/` (for example, a new executable such as `okstra-claude-exec.sh`).
+3. Run `npm run build`.
+4. Verify `tests-js/runtime-build-sync.test.mjs`.
+5. Verify `tests-js/install-runtime.test.mjs`.
+6. Reinstall or repack the package before testing global `okstra install`.
+
 ### 3.3 Install output
 
+`okstra install` copies from the installed npm package `runtime/` tree, not from the source checkout. `okstra -v` only proves the CLI version; the same semver can still point at stale package contents when the global package was installed before the latest build.
+
 `okstra install` copies or symlinks:
 
 - `runtime/python/*` → `~/.okstra/lib/python/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.78.1",
+  "version": "0.79.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.78.1",
-  "builtAt": "2026-06-14T07:26:32.969Z",
+  "package": "0.79.0",
+  "builtAt": "2026-06-14T09:17:32.918Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-claude-exec.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# okstra-claude-exec.sh — wrapper around Claude Code non-interactive print mode.
+set -euo pipefail
+
+if [[ $# -lt 3 || $# -gt 6 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]\n' "$(basename "$0")" >&2
+  exit 64
+fi
+
+project_root="$1"
+model="$2"
+prompt_path="$3"
+worktree_path="${4-}"
+role="${5:-worker}"
+idle_timeout_secs="${6:-600}"
+
+if [[ ! -d "$project_root" ]]; then
+  printf 'okstra-claude-exec.sh: project root not found: %s\n' "$project_root" >&2
+  exit 65
+fi
+if [[ -z "$model" ]]; then
+  printf 'okstra-claude-exec.sh: model is required\n' >&2
+  exit 66
+fi
+if [[ ! -f "$prompt_path" ]]; then
+  printf 'okstra-claude-exec.sh: prompt not found: %s\n' "$prompt_path" >&2
+  exit 67
+fi
+if [[ -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  printf 'okstra-claude-exec.sh: worktree not found: %s\n' "$worktree_path" >&2
+  exit 68
+fi
+if ! [[ "$idle_timeout_secs" =~ ^[0-9]+$ ]]; then
+  printf 'okstra-claude-exec.sh: idle timeout must be a non-negative integer\n' >&2
+  exit 69
+fi
+if ! command -v claude >/dev/null 2>&1; then
+  printf 'okstra-claude-exec.sh: claude CLI not found\n' >&2
+  exit 127
+fi
+
+log_path="${prompt_path%.md}.log"
+[[ "$log_path" == "$prompt_path" ]] && log_path="${prompt_path}.log"
+: > "$log_path"
+status_path="${prompt_path}.status.json"
+started_ts=$(date +%s)
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+python3 "$script_dir/okstra-wrapper-status.py" \
+  init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
+  >>"$log_path" 2>&1 || true
+
+_okstra_status_finish() {
+  local exit_code=$?
+  local ended_ts
+  ended_ts=$(date +%s)
+  local duration_ms=$(( (ended_ts - started_ts) * 1000 ))
+  python3 "$script_dir/okstra-wrapper-status.py" \
+    finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
+    >>"$log_path" 2>&1 || true
+}
+trap _okstra_status_finish EXIT
+
+cd "$project_root"
+set +e
+claude -p --model "$model" --output-format=stream-json < "$prompt_path" \
+  > >(tee -a "$log_path") \
+  2> >(tee -a "$log_path" >&2)
+claude_exit=$?
+set -e
+
+exit "$claude_exit"

package/runtime/validators/validate-workflow.sh

@@ -13,6 +13,8 @@ SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
 WORKSPACE_ROOT="$(cd -P "$SCRIPT_DIR/.." && pwd)"
 PROJECT_ID="okstra-validation"
 PROJECT_ROOT="${OKSTRA_VALIDATION_PROJECT_ROOT:-/tmp/okstra-validate.workflow}"
+export OKSTRA_HOME="${OKSTRA_HOME:-$PROJECT_ROOT/.okstra-home}"
+
 WORKSPACE_APP_PATH="$PROJECT_ROOT"
 OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
 RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
@@ -30,6 +32,14 @@ SECONDARY_TASK_GROUP="discovery"
 SECONDARY_TASK_ID="task-catalog"
 SECONDARY_BRIEF_FILENAME="validation-brief-secondary.md"
 
+# Workflow validation is a hermetic contract test for bundle prep / discovery
+# artifacts / validator round-trips. It must not depend on the developer or CI
+# machine having a preinstalled ~/.okstra runtime, and it must not reconcile or
+# backfill against unrelated local state.
+export OKSTRA_SKIP_INSTALL_CHECK="${OKSTRA_SKIP_INSTALL_CHECK:-1}"
+export OKSTRA_CTL_SKIP_RECONCILE="${OKSTRA_CTL_SKIP_RECONCILE:-1}"
+export OKSTRA_CTL_SKIP_BACKFILL="${OKSTRA_CTL_SKIP_BACKFILL:-1}"
+
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
 # shellcheck source=lib/paths.sh