okstra 0.79.0 → 0.80.0

package/docs/superpowers/specs/2026-06-14-host-runtime-auto-execution-design.md

@@ -0,0 +1,404 @@
+# Host 기반 runtime auto-detection + auto-execution 설계
+
+- 날짜: 2026-06-14
+- 상태: 설계 초안
+- 대상: `okstra install`, `okstra doctor`, `okstra run`, lead runtime resolution, runtime manifest
+- 선행 문서:
+  - [`2026-06-12-codex-lead-adapter-design.md`](2026-06-12-codex-lead-adapter-design.md)
+  - [`2026-06-13-neutral-tmux-lead-adapter-design.md`](2026-06-13-neutral-tmux-lead-adapter-design.md)
+
+## 1. 배경
+
+현재 runtime 선택은 자동 감지가 아니다. `okstra install` 은 기본값 `claude-code` 를 사용하고, `installed-runtimes.json` 의 `codexAdapter` / `externalAdapter` 는 실제 adapter 실행 가능성이 아니라 install 인자 선택값만 반영한다.
+
+확인된 현재 상태:
+
+- `installed-runtimes.json` 은 `runtime === "codex" || "all"` 일 때만 `codexAdapter:true`, `runtime === "external" || "all"` 일 때만 `externalAdapter:true` 를 쓴다([runtime-manifest.mjs:8](../../../src/runtime-manifest.mjs:8)).
+- `okstra install` 기본 runtime 은 `claude-code` 다([install.mjs:606](../../../src/install.mjs:606)).
+- `okstra doctor` 기본 runtime 도 `claude-code` 다([doctor.mjs:37](../../../src/doctor.mjs:37)).
+- Python prepare layer 는 `leadRuntime != "claude-code"` 이고 non-render 이면 막는다([run.py:2053](../../../scripts/okstra_ctl/run.py:2053)).
+- `--lead-runtime` 기본값도 `claude-code` 다([run.py:2416](../../../scripts/okstra_ctl/run.py:2416)).
+- `okstra team` 은 `leadRuntime=external` bundle 을 받아 tmux-pane worker dispatch/await/teardown 을 수행하는 Node→Python CLI 경계다([team.mjs:4](../../../src/team.mjs:4)).
+
+사용자 결정:
+
+1. 자동 감지 범위는 **실행까지 자동**이다.
+2. runtime 우선순위는 **host 기반**이다.
+3. fallback 은 **safe fallback** 이다. 의도와 다른 runtime 으로 조용히 넘어가지 않는다.
+
+## 2. 문제
+
+현재 이름과 동작이 서로 맞지 않는다.
+
+- `codexAdapter:false` / `externalAdapter:false` 는 adapter 미설치 또는 CLI 부재처럼 보이지만, 실제 의미는 "이번 install 선택값이 `claude-code`" 이다.
+- 공유 runtime 은 항상 `~/.okstra/bin` 으로 복사되므로 wrapper 파일 존재와 manifest flag 가 일치하지 않는다.
+- 사용자는 `okstra install` / `okstra run` 이 현재 host 를 이해한다고 기대하지만, 실제로는 `claude-code` 로 고정된다.
+- `external` 실행은 Python non-render gate 때문에 직접 full-run 으로 열 수 없고, Node driver 가 render-only prepare → team dispatch/await 를 orchestration 해야 한다.
+
+## 3. 결정
+
+`auto` 를 runtime 값 자체가 아니라 **resolver 입력값**으로 도입한다.
+
+```text
+explicit runtime: claude-code | codex | external | all
+auto request: host/context 를 감지해 위 runtime 중 하나로 resolve
+```
+
+새 단일 참조점:
+
+```text
+src/runtime-resolver.mjs
+```
+
+역할:
+
+1. host signal 수집
+2. 설치 자산과 실행 capability 검사
+3. command 별 허용 runtime 계산
+4. safe fallback 적용
+5. 최종 runtime, 이유, 경고를 구조화해서 반환
+
+예상 API:
+
+```js
+resolveRuntime({
+  requestedRuntime: "auto" | "claude-code" | "codex" | "external" | "all",
+  command: "install" | "ensure-installed" | "doctor" | "render" | "run" | "dispatch",
+  env: process.env,
+  paths,
+})
+```
+
+반환:
+
+```json
+{
+  "requestedRuntime": "auto",
+  "resolvedRuntime": "external",
+  "host": "generic-terminal",
+  "confidence": "high",
+  "reason": "No Claude Code or Codex host signal; tmux is available.",
+  "fallbackFrom": null,
+  "warnings": []
+}
+```
+
+핵심 규칙:
+
+- 명시 runtime 은 자동 override 하지 않는다.
+- `auto` 일 때만 감지한다.
+- resolver 결과는 install manifest, run manifest, doctor JSON, console output 에 남긴다.
+- `codexAdapter` / `externalAdapter` 는 새 manifest 에서 쓰지 않는다. v1 manifest read compatibility 에서만 해석한다.
+
+## 4. 용어
+
+| 용어 | 의미 |
+|---|---|
+| install runtime | 어떤 asset set 을 설치/보장할지 결정하는 값 |
+| lead runtime | 이번 run 의 lead adapter 정체성: `claude-code`, `codex`, `external` |
+| host | 현재 `okstra` 를 실행 중인 환경: Claude Code session, Codex CLI/session, generic terminal |
+| dispatch backend | worker 를 어떻게 실행하는지: Claude Teams, CLI wrapper, tmux pane |
+| capability | 현재 시점에서 실행 가능한 조건: CLI binary, tmux, installed assets, phase support |
+| safe fallback | 같은 intent 를 보존할 수 있을 때만 fallback 하는 정책 |
+
+## 5. Host 감지
+
+Resolver 는 allowlist 기반 signal 만 사용한다. 불명확한 signal 은 runtime 을 결정하지 않고 warning 으로 남긴다.
+
+감지 우선순위:
+
+1. **Explicit runtime**
+   - CLI flag 또는 env override 가 `auto` 가 아니면 그대로 사용한다.
+   - 예: `--lead-runtime external`, `OKSTRA_LEAD_RUNTIME=codex`.
+2. **Explicit host override**
+   - 새 env `OKSTRA_RUNTIME_HOST=claude-code|codex|external`.
+   - 테스트와 wrapper 가 안정적으로 host 를 주입할 수 있는 public contract 다.
+3. **Claude Code host**
+   - Claude Code slash skill 또는 agent contract 가 `OKSTRA_RUNTIME_HOST=claude-code` 를 넘기는 방식이 primary signal 이다.
+   - 환경 fingerprint 는 보조 signal 로만 사용한다.
+4. **Codex host**
+   - Codex wrapper/entrypoint 가 `OKSTRA_RUNTIME_HOST=codex` 를 넘기는 방식이 primary signal 이다.
+   - `codex` executable 존재만으로 Codex host 라고 판단하지 않는다. binary availability 는 capability 일 뿐 host 가 아니다.
+5. **External host**
+   - 명시 host 가 없고, 일반 terminal 에서 `tmux` 가 사용 가능하면 `external`.
+6. **Unknown**
+   - host 와 capability 가 모두 부족하면 fail-fast.
+
+이 설계는 "binary가 설치되어 있으니 그 runtime으로 실행" 을 피한다. host 기반 결정과 capability 검사를 분리해야 예측 가능하다.
+
+## 6. Safe fallback matrix
+
+Fallback 은 `requestedRuntime:auto` 에서만 동작한다. 명시 runtime 은 실패를 사용자에게 보여주고 중단한다.
+
+| resolved candidate | 실행 불가 이유 | fallback |
+|---|---|---|
+| `claude-code` | Claude Code host signal 은 있으나 Claude assets 누락 | `ensure-installed --runtime claude-code` 로 보강 후 재시도 |
+| `claude-code` | Claude Code host 가 아닌 것으로 판정 | `external` if tmux 가능, 아니면 fail |
+| `codex` | Codex host signal 은 있으나 Codex CLI 없음 | fail. Claude/external 로 조용히 전환하지 않음 |
+| `codex` | requested roster 에 unsupported worker 포함 | fail with supported worker/report-writer opt-in 안내 |
+| `external` | tmux 없음 | prepare/render-only 까지는 가능, dispatch 는 fail |
+| `external` | `claude` worker 포함, Claude CLI wrapper 실행 불가 | 해당 worker dispatch fail. roster 를 몰래 줄이지 않음 |
+| unknown | host signal 없음 + tmux 없음 | fail with next-command suggestion |
+
+Fallback reason 은 run manifest 에 남긴다.
+
+## 7. CLI UX
+
+### 7.1 기본값
+
+다음 command 의 기본 runtime 을 `auto` 로 바꾼다.
+
+```bash
+okstra install
+okstra ensure-installed
+okstra doctor
+okstra render-bundle ...
+okstra run ...
+```
+
+명시 선택은 유지한다.
+
+```bash
+okstra install --runtime claude-code
+okstra install --runtime codex
+okstra install --runtime external
+okstra install --runtime all
+okstra run --lead-runtime external ...
+```
+
+`all` 은 감지값이 아니다. 모든 runtime asset set 을 명시 설치/검사하는 admin mode 로 유지한다.
+
+### 7.2 Execution front doors
+
+Auto execution has two front doors because Claude Code native tools are not available to a plain Node process.
+
+| Front door | Host | Responsibility |
+|---|---|---|
+| `/okstra-run` skill | Claude Code | Uses resolver context, keeps the existing Claude Code interactive/team path |
+| `okstra run` Node CLI | Codex / generic terminal | Resolves runtime and orchestrates CLI-backed `codex` or `external` execution |
+
+New Node driver `okstra run` is still useful, but it must not pretend it can call Claude Code `TeamCreate` / `Agent(...)` from a terminal. If `okstra run` resolves `claude-code` without being invoked by a Claude Code skill handoff, it fails with an instruction to use `/okstra-run` or pass another explicit runtime.
+
+```text
+okstra run ...
+  → resolveRuntime(requestedRuntime=auto by default, command=run)
+  → if resolvedRuntime=codex: codex-run → codex-dispatch
+  → if resolvedRuntime=external: render-bundle → team dispatch → team await
+  → if resolvedRuntime=claude-code outside skill handoff: fail with /okstra-run guidance
+```
+
+`external` 은 Python `prepare_task_bundle()` 의 non-render gate 를 열지 않는다. Node `okstra run` 이 render-only prepare 이후 dispatch/await 를 소유한다.
+
+### 7.3 기존 command 와의 관계
+
+- `okstra codex-run`: 유지. Codex lead prompt materialization 의 explicit low-level command.
+- `okstra codex-dispatch`: 유지. Prepared Codex run 의 explicit dispatch command.
+- `okstra team dispatch/await/teardown`: 유지. External/tmux backend 의 explicit low-level command.
+- `okstra render-bundle`: 유지. Preview/debug 목적의 low-level prepare command.
+- `okstra run`: 위 command 들을 host-aware 하게 묶는 high-level command.
+
+## 8. Manifest 변경
+
+### 8.1 installed-runtimes.json v2
+
+현재 v1 의 `codexAdapter` / `externalAdapter` 는 쓰지 않는다. 새 manifest 는 설치 요청과 설치 자산을 분리한다.
+
+```json
+{
+  "schemaVersion": 2,
+  "installedAt": "2026-06-14T00:00:00.000Z",
+  "installRequest": "auto",
+  "runtimeResolution": {
+    "requestedRuntime": "auto",
+    "resolvedRuntime": "external",
+    "host": "generic-terminal",
+    "reason": "No Claude Code or Codex host signal; tmux is available.",
+    "fallbackFrom": null,
+    "warnings": []
+  },
+  "installedRuntimes": ["external"],
+  "installedAssets": {
+    "sharedRuntime": true,
+    "claudeSkills": false,
+    "claudeAgents": false,
+    "binWrappers": true,
+    "templates": true,
+    "schemas": true,
+    "validators": true
+  }
+}
+```
+
+Dynamic capability 는 install manifest 에 고정하지 않는다. `tmux`, `codex`, `claude` CLI availability 는 시간이 지나면 바뀌므로 `doctor` 와 `run` 이 매번 검사한다.
+
+### 8.2 run manifest additions
+
+Run manifest 에 runtime request/resolution 을 기록한다.
+
+```json
+{
+  "leadRuntimeRequest": "auto",
+  "leadRuntime": "external",
+  "runtimeResolution": {
+    "requestedRuntime": "auto",
+    "resolvedRuntime": "external",
+    "host": "generic-terminal",
+    "reason": "No Claude Code or Codex host signal; tmux is available.",
+    "fallbackFrom": null,
+    "warnings": []
+  }
+}
+```
+
+`leadRuntime` 은 기존 consumer 호환을 위해 최종 resolved runtime 을 유지한다.
+
+## 9. Install / ensure / doctor 동작
+
+### 9.1 install
+
+`okstra install` 기본값은 `--runtime auto` 와 같다.
+
+- Claude Code host → `claude-code` assets 설치: shared runtime + Claude skills/agents.
+- Codex host → `codex` assets 설치: shared runtime only.
+- Generic terminal + tmux → `external` assets 설치: shared runtime only.
+- `--runtime all` → shared runtime + Claude skills/agents + all installedRuntimes 기록.
+
+공유 runtime 은 모든 install mode 에서 복사한다. 이 때문에 `bin/okstra-codex-exec.sh` 같은 wrapper 존재만으로 `codex` runtime 설치를 의미하지 않는다. v2 manifest 는 이 혼동을 `installedAssets` 와 `installedRuntimes` 로 나눠 제거한다.
+
+### 9.2 ensure-installed
+
+`okstra ensure-installed` 기본값도 auto다.
+
+- 현재 host 에 필요한 asset 이 없으면 같은 host-resolved runtime 으로 install 을 수행한다.
+- generic terminal 에서 `external` 로 설치된 뒤 Claude Code 에서 `/okstra-run` 이 실행되면, Claude Code host signal 이 `claude-code` 로 resolve 되고 Claude assets 를 보강 설치한다.
+- v1 manifest 는 읽을 수 있어야 한다. v1 에서 `runtime:"claude-code"` 이면 `installedRuntimes:["claude-code"]` 로 해석한다.
+
+### 9.3 doctor
+
+`okstra doctor --runtime auto` 는 현재 host 에 필요한 readiness 만 검사한다.
+
+`okstra doctor --runtime all` 은 admin check 로 다음을 모두 검사한다.
+
+- shared runtime files
+- Claude assets
+- Codex CLI availability
+- external/tmux availability
+- manifest v1/v2 해석
+
+JSON output 에 `runtimeResolution` 을 포함한다.
+
+## 10. Execution flow
+
+### 10.1 Claude Code host
+
+```text
+/okstra-run
+  → resolver context = claude-code
+  → ensure-installed claude-code
+  → existing Claude Code interactive/team path
+```
+
+Bare `okstra run` must not claim Claude Code execution unless it is part of a Claude Code skill handoff. A Node process cannot invoke native `TeamCreate` / `Agent(...)` directly.
+
+이 경로는 기존 slash skill UX 를 깨지 않는다.
+
+### 10.2 Codex host
+
+```text
+okstra run ...
+  → resolveRuntime = codex
+  → ensure-installed codex
+  → okstra codex-run ...
+  → okstra codex-dispatch ...
+```
+
+Report-writer 는 기존 Codex opt-in 정책을 따른다. 필요한 phase 에서 report-writer 가 required 인데 opt-in 이 없으면 fail-fast 한다. Worker roster 를 몰래 줄이지 않는다.
+
+### 10.3 External/generic terminal host
+
+```text
+okstra run ...
+  → resolveRuntime = external
+  → ensure-installed external
+  → okstra render-bundle ... --lead-runtime external
+  → read produced run manifest
+  → okstra team dispatch --run-manifest <path>
+  → okstra team await --run-manifest <path>
+  → post-processing / validation
+```
+
+Python `prepare_task_bundle()` 의 non-render gate 는 유지한다. Full external execution 은 Node driver 가 orchestration 한다.
+
+## 11. Error handling
+
+All resolver failures should be actionable.
+
+Examples:
+
+- `auto resolved codex but codex CLI is unavailable. Install Codex CLI or run with --lead-runtime external.`
+- `auto resolved external but tmux is unavailable. Run render-only or install tmux.`
+- `explicit --lead-runtime codex requested, but worker claude is unsupported by codex-dispatch. Choose supported workers or use claude-code/external.`
+- `host unknown. Set OKSTRA_RUNTIME_HOST=claude-code|codex|external or pass --lead-runtime explicitly.`
+
+No fallback may change worker roster, phase, task type, executor, or report-writer role without explicit user input.
+
+## 12. Backward compatibility
+
+- Existing explicit flags keep working.
+- Existing `okstra codex-run`, `okstra codex-dispatch`, `okstra team *`, `okstra render-bundle` keep working.
+- v1 `installed-runtimes.json` remains readable.
+- New installs write v2.
+- Existing v1 `codexAdapter` / `externalAdapter` are interpreted only while reading old manifests.
+- `leadRuntime` in run manifest remains final resolved runtime, so validators that already read `leadRuntime` do not need a broad schema break.
+
+## 13. Tests
+
+Required test groups:
+
+1. `runtime-resolver` unit tests
+   - explicit runtime bypasses auto
+   - host override resolves each runtime
+   - generic terminal + tmux resolves external
+   - binary availability alone does not imply host
+   - safe fallback matrix
+2. install tests
+   - default install writes v2 auto manifest
+   - Claude host installs Claude assets
+   - external host skips Claude assets
+   - v1 manifest read compatibility
+3. doctor tests
+   - `--runtime auto` reports runtimeResolution
+   - `--runtime all` checks all readiness categories
+4. run driver tests
+   - auto external builds render-only bundle and invokes team dispatch/await in dry-run/fake mode
+   - auto codex invokes codex-run/codex-dispatch in dry-run/fake mode
+   - bare `okstra run` resolving `claude-code` fails with `/okstra-run` guidance
+   - unsupported Codex worker fails without roster shrink
+5. docs contract tests
+   - default runtime is auto
+   - host-based priority documented
+   - safe fallback documented
+   - manifest v2 no longer documents `codexAdapter` / `externalAdapter` as live fields
+
+## 14. Rollout plan
+
+Recommended implementation order:
+
+1. Add `runtime-resolver.mjs` and tests.
+2. Add v2 runtime manifest writer/reader while preserving v1 read path.
+3. Switch install/ensure/doctor defaults from `claude-code` to `auto`.
+4. Add `okstra run` high-level driver with dry-run/fake subprocess tests.
+5. Wire external execution path through render-bundle → team dispatch → team await.
+6. Wire codex execution path through codex-run → codex-dispatch.
+7. Update docs and CLI help.
+8. Keep explicit low-level commands unchanged.
+
+## 15. Non-goals
+
+- Do not remove explicit runtime flags.
+- Do not remove Claude Code slash skill UX.
+- Do not make binary availability alone choose a host.
+- Do not open Python `prepare_task_bundle()` non-render for `external` in this change.
+- Do not silently shrink worker roster for fallback.
+- Do not implement non-tmux external dispatch backends.
+- Do not change phase profile/schema/validator contracts by provider fork.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.79.0",
+  "version": "0.80.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.79.0",
-  "builtAt": "2026-06-14T09:17:32.918Z",
+  "package": "0.80.0",
+  "builtAt": "2026-06-14T13:33:02.891Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/render.py

@@ -91,6 +91,15 @@ def _lead_adapter(ctx: dict) -> dict:
     return _lead_info(ctx).adapter_payload()
 
 
+def _runtime_resolution(ctx: dict) -> dict:
+    raw = ctx.get("RUNTIME_RESOLUTION_JSON", "") or "{}"
+    try:
+        payload = json.loads(raw)
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
 _PHASE_BLOCK_RE = re.compile(
     r"\{% if header\.taskType == '(implementation-planning|release-handoff|implementation|final-verification)' %\}\n(.*?)\{% endif %\}\n",
     re.DOTALL,
@@ -1185,6 +1194,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
         "leadRuntime": _lead_runtime(ctx),
+        "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
+        "runtimeResolution": _runtime_resolution(ctx),
         "leadAdapter": _lead_adapter(ctx),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")

package/runtime/python/okstra_ctl/run.py

@@ -296,6 +296,8 @@ class PrepareInputs:
     gemini_model: str = ""
     report_writer_model: str = ""
     lead_runtime: str = "claude-code"
+    lead_runtime_request: str = ""
+    runtime_resolution_json: str = ""
     executor: str = ""
     critic: str = ""
     related_tasks_raw: str = ""
@@ -2055,6 +2057,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     workspace_root = Path(inp.workspace_root)
     project_root = Path(inp.project_root)
     lead_runtime = _normalize_lead_runtime(inp.lead_runtime)
+    lead_runtime_request = (inp.lead_runtime_request or lead_runtime).strip()
+    runtime_resolution_json = (inp.runtime_resolution_json or "{}").strip()
+    try:
+        json.loads(runtime_resolution_json or "{}")
+    except json.JSONDecodeError as exc:
+        raise PrepareError(f"invalid --runtime-resolution-json: {exc}") from exc
     if lead_runtime != "claude-code" and not inp.render_only:
         raise PrepareError(
             f"lead runtime `{lead_runtime}` is currently render-only; "
@@ -2247,6 +2255,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "ANALYSIS_PROFILE": inp.task_type,
         "RECOMMENDED_ANALYSERS": selected_reviewers,
         "LEAD_RUNTIME": lead_runtime,
+        "LEAD_RUNTIME_REQUEST": lead_runtime_request,
+        "RUNTIME_RESOLUTION_JSON": runtime_resolution_json or "{}",
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
         **handoff_tokens,
@@ -2424,6 +2434,18 @@ def main(argv: list[str]) -> int:
             "bundles for manifest inspection until a dispatch backend is enabled."
         ),
     )
+    p.add_argument(
+        "--lead-runtime-request",
+        default="",
+        dest="lead_runtime_request",
+        help="Original lead runtime request before Node-side resolution, e.g. auto.",
+    )
+    p.add_argument(
+        "--runtime-resolution-json",
+        default="",
+        dest="runtime_resolution_json",
+        help="Node-side runtime resolution payload serialized as JSON.",
+    )
     p.add_argument("--executor", default="")
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
@@ -2561,6 +2583,8 @@ def main(argv: list[str]) -> int:
         gemini_model=args.gemini_model,
         report_writer_model=args.report_writer_model,
         lead_runtime=args.lead_runtime,
+        lead_runtime_request=args.lead_runtime_request,
+        runtime_resolution_json=args.runtime_resolution_json,
         executor=args.executor,
         critic=args.critic,
         related_tasks_raw=args.related_tasks_raw,
@@ -2591,6 +2615,7 @@ def main(argv: list[str]) -> int:
     print(f"okstra latest task discovery file: {ctx['OKSTRA_LATEST_TASK_FILE']}")
     print(f"okstra task catalog file: {ctx['OKSTRA_TASK_CATALOG_FILE']}")
     print(f"okstra instruction-set: {ctx['INSTRUCTION_SET_PATH']}")
+    print(f"okstra run manifest: {ctx['RUN_MANIFEST_PATH']}")
     print(f"okstra reference expectations: {ctx['REFERENCE_EXPECTATIONS_FILE']}")
     print(f"okstra final report template: {ctx['FINAL_REPORT_TEMPLATE_PATH']}")
     cr = out.extras.get("concurrent_run", {})

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

@@ -21,7 +21,7 @@ Single read-side entry point for okstra runtime inspection plus the one write-si
 
 Before any sub-command, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
 
-1. `okstra ensure-installed`
+1. `okstra ensure-installed --runtime claude-code`
    If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
 
 2. `okstra check-project --json`

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

@@ -55,7 +55,7 @@ Never invent additional questions. Never reorder. **Never drop, hide, or merge a
 
 Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&` — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's JSON output and decides what to do next in natural language — never in shell.
 
-1. `okstra ensure-installed`
+1. `okstra ensure-installed --runtime claude-code`
    If this exits non-zero, tell the user: "okstra runtime missing — run `npx okstra@latest install` once and retry." Then stop.
 
 2. `okstra paths --json`
@@ -155,8 +155,11 @@ Output: `{ok: true, args: {"project-root": "...", "task-type": "...", ...}}`. Bu
 
 **Escaping rule**: inside a double-quoted value, escape any literal `"` as `\"`. Do not collapse `--key ""` into `--key` even when the value is empty.
 
+The okstra-run skill is the Claude Code execution front door, so it marks the host explicitly with `--runtime claude-code` / `--lead-runtime claude-code`; bare `okstra run` cannot invoke Claude Code `TeamCreate` / `Agent(...)` from a terminal.
+
 ```bash
 okstra render-bundle \
+  --lead-runtime claude-code \
   --project-root "<args.project-root>" \
   --project-id   "<args.project-id>" \
   --task-group   "<args.task-group>" \

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

@@ -39,7 +39,7 @@ If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadF
 
 Before anything else in this skill, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
 
-1. `okstra ensure-installed`
+1. `okstra ensure-installed --runtime claude-code`
    If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
 
 2. `okstra check-project --json`

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

@@ -34,7 +34,7 @@ Inform the user up-front and confirm before continuing:
 ## Step 1: Install okstra
 
 ```bash
-npx -y okstra@latest install
+npx -y okstra@latest install --runtime claude-code
 ```
 
 This single command populates everything the user needs:
@@ -316,7 +316,7 @@ If the user picks 1/2/3, run:
 ## Step 5: Verify
 
 ```bash
-okstra doctor
+okstra doctor --runtime claude-code
 ```
 
 If all checks return `OK`, the setup is complete. If any check fails, surface

package/src/cli-registry.mjs

@@ -127,6 +127,13 @@ export const COMMAND_REGISTRY = [
       "python3 -m okstra_ctl.run --render-only)",
     ],
   },
+  {
+    name: "run",
+    module: "./run.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Host-aware auto execution front door"],
+  },
   {
     name: "codex-run",
     module: "./codex-run.mjs",
@@ -232,7 +239,7 @@ This CLI is the installer/admin tool. Day-to-day usage happens inside a
 Claude Code session via slash commands (/okstra-setup, /okstra-run, ...).
 
 Quick start (CLI):
-  1. npx -y okstra@latest install                       # one-time, this machine
+  1. npx -y okstra@latest install --runtime claude-code # one-time, this machine
   2. cd <your project>
   3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
   4. open a Claude Code session and run /okstra-run     # start a task

package/src/doctor.mjs

@@ -5,6 +5,7 @@ import { resolvePaths } from "./paths.mjs";
 import { fileExists, runProcess } from "./_proc.mjs";
 import { runPythonSnippet } from "./_python-helper.mjs";
 import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -38,7 +39,7 @@ export function parseDoctorArgs(args) {
   const result = {
     jsonMode: false,
     phase: null,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -182,6 +183,17 @@ export async function run(args) {
     return 2;
   }
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "doctor",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
+  const resolvedRuntime = runtimeResolution.resolvedRuntime;
 
   const results = [
     await check("python3", checkPython3),
@@ -197,7 +209,7 @@ export async function run(args) {
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
-      requiredSkillNamesForRuntime(opts.runtime).map((name) =>
+      requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
           return (await fileExists(p))
@@ -229,7 +241,9 @@ export async function run(args) {
     process.stdout.write(
       `${JSON.stringify({
         ok: allOk,
-        runtime: opts.runtime,
+        runtimeRequest: opts.runtime,
+        runtime: resolvedRuntime,
+        runtimeResolution,
         phase: opts.phase,
         paths,
         phaseDiagnostics,