okstra 0.163.2 → 0.165.0

package/runtime/validators/validate-run.py

@@ -51,7 +51,8 @@ from okstra_ctl.conformance import (  # noqa: E402
     validate_conformance_manifest,
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
-from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES  # noqa: E402
+from okstra_ctl.domain.host import HostNotRegistered  # noqa: E402
+from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E402
 from okstra_ctl.build_tools import (  # noqa: E402
     command_invokes_build_tool,
     resolve_build_tool_tokens,
@@ -65,7 +66,7 @@ from okstra_ctl.report_translation import (  # noqa: E402
     HANGUL_PROSE_LIMIT,
     hangul_share,
 )
-from okstra_ctl.stage_citations import cited_stage_numbers  # noqa: E402
+from okstra_ctl.stage_citations import enumerated_stage_numbers  # noqa: E402
 from okstra_ctl.incremental_scope import (  # noqa: E402
     coverage_row_blocked_on,
     stages_for_clarification,
@@ -170,11 +171,11 @@ def _session_accounting(team_state: dict) -> str:
     value = str(adapter.get("sessionAccounting", "")).strip()
     if value:
         return value
-    return (
-        "artifact-only"
-        if team_state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES
-        else "claude-jsonl"
-    )
+    runtime = str(team_state.get("leadRuntime", "")).strip()
+    try:
+        return default_host_registry().resolve(runtime).descriptor.session_accounting
+    except HostNotRegistered:
+        return "claude-jsonl"
 
 
 
@@ -742,7 +743,7 @@ def validate_team_state(
         dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
         if (
             dispatch_mode in WORKER_DISPATCH_MODES
-            or team_state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES
+            or _session_accounting(team_state) == "artifact-only"
         ):
             if dispatch_mode not in WORKER_DISPATCH_MODES:
                 expected = ", ".join(sorted(WORKER_DISPATCH_MODES))
@@ -3132,6 +3133,7 @@ def validate_final_report_data(
     # Called here rather than from a task-type branch: four profiles raise
     # clarification rows, and the gate scopes itself by task type internally.
     _validate_clarification_options(data, failures)
+    _validate_open_approval_blocker_provenance(data, failures)
 
     task_type = (data.get("header") or {}).get("taskType")
     _validate_verifier_fail_blocks_verdict(data, failures)
@@ -4125,6 +4127,80 @@ def _validate_option_set(
             )
 
 
+def _validate_open_approval_blocker_provenance(
+    data: dict, failures: list[str]
+) -> None:
+    """An open approval blocker records who raised it and what the lead did about it.
+
+    A lead can foresee a blocker, write it into the report as a
+    `blocks: approval` row, and let the run finish — the row then withholds
+    approval until a separate user-response cycle answers it. That path cost a
+    full planning run: the user pointed at a reduction document and said "remove
+    what it flags", the lead read that document's own "user decision required"
+    note as outranking the instruction, and told the report writer to raise the
+    item instead of applying it. The two verifiers then agreed unanimously that
+    it was a user decision — not an independent finding, but the lead's own
+    instruction returning to it. The run spent its whole self-fix budget on a
+    gate no round could clear, because the thing blocking it was already
+    answered before the run started.
+
+    `origin` names who produced the row, so a lead-authored blocker can no
+    longer arrive dressed as a worker consensus. `userConfirmation` records what
+    the lead did before writing it. Neither is required on a row the user has
+    already answered (`answered` / `resolved`) — the record is in `userInput`.
+
+    The one shape rejected outright is a lead-directed blocker raised with no
+    interactive session: with nobody to ask, a defect the lead itself surfaced
+    belongs in `## 5. Missing Information and Risks` as a Working Assumption,
+    the same outlet the surviving planner-fixable items already use. Blocking a
+    plan on the lead's own judgment, in a run where that judgment cannot be put
+    to the user, only defers the work to a re-run.
+    """
+    for row in data.get("clarificationItems") or []:
+        if not isinstance(row, dict):
+            continue
+        if row.get("blocks") != "approval" or row.get("status") != "open":
+            continue
+        row_id = str(row.get("id") or "<unknown>")
+        origin = row.get("origin")
+        confirmation = row.get("userConfirmation")
+        if not origin:
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` is an open "
+                "approval blocker with no `origin`. Record who raised it — "
+                "`worker-finding` (an analyser or verifier reached it "
+                "independently), `material-gap` (the brief and the codebase "
+                "both leave it unanswered), or `lead-directed` (the lead's own "
+                "judgment, including anything the lead instructed a worker to "
+                "raise). A lead-authored blocker recorded as a worker consensus "
+                "is how a run blocks on a question the user already answered."
+            )
+        if not confirmation:
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` is an open "
+                "approval blocker with no `userConfirmation`. Record what "
+                "happened before the row was written — `asked-and-answered`, "
+                "`asked-awaiting`, or `deferred-no-interactive-session`. "
+                "Withholding approval is the most expensive thing a report can "
+                "do to a run; doing it without recording whether the user was "
+                "ever asked leaves the next run unable to tell a real blocker "
+                "from a question nobody put to them."
+            )
+        if (
+            origin == "lead-directed"
+            and confirmation == "deferred-no-interactive-session"
+        ):
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` blocks "
+                "approval on the lead's own judgment (`origin: lead-directed`) "
+                "in a run with no interactive session to answer it. Record it "
+                "as a Working Assumption in `## 5. Missing Information and "
+                "Risks` and let the plan proceed — that is the outlet surviving "
+                "planner-fixable items already use. A blocker nobody can answer "
+                "inside this run only moves the work to a re-run."
+            )
+
+
 def _has_clarification_backtrace(
     row_id: str, plan_items: object, coverage: object
 ) -> bool:
@@ -6346,10 +6422,14 @@ def _validate_requirement_provenance(
 # Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
 # what "no match" means — forward treats it as nothing to verify and passes,
 # reverse treats it as nothing cited and orphans every stage — so the reverse
-# reader must cover `Stages 1, 2`, `Stages 1-3` and `Stage 1 and 2` too. The
-# grammar is shared with the incremental-scope back-trace, which resolves the
-# same citations in the opposite direction.
-_cited_stage_numbers = cited_stage_numbers
+# reader must cover `Stages 1, 2` and `Stage 1 and 2` too.
+#
+# It reads hand-enumerated numbers only. A range's interior is deliberately NOT
+# coverage evidence: one `Stages 1-64` cell would otherwise stamp every stage in
+# the map while the planner confirmed none of them. The incremental-scope
+# back-trace keeps the widening reader (`cited_stage_numbers`) because "could
+# this answer reach stage 5" is the opposite question and must over-approximate.
+_enumerated_stage_numbers = enumerated_stage_numbers
 
 
 # Statuses under which a row asserts the plan does work for the requirement.
@@ -6386,14 +6466,16 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
             continue
         if not _COVERAGE_CLAIMING_STATUS_RE.match(str(row.get("status") or "").strip()):
             continue
-        cited |= _cited_stage_numbers(str(row.get("coveredBy") or ""))
+        cited |= _enumerated_stage_numbers(str(row.get("coveredBy") or ""))
 
     for orphan in sorted(stage_numbers - cited):
         failures.append(
             f"final-report data.json: Stage {orphan} is cited by no requirementCoverage "
             "row — it traces back to nothing the brief asked for. Either cite the "
             "requirement it serves, or drop it and raise it as a `Blocks=approval` "
-            "clarification (profile: scope provenance)."
+            "clarification (profile: scope provenance). A range cites only its "
+            "endpoints here: write `Stages 1, 2, 3` rather than `Stages 1-3`, so each "
+            "stage this requirement covers is one the planner named."
         )
 
 

package/runtime/validators/validate_session_conformance.py

@@ -39,7 +39,8 @@ from okstra_ctl.worker_heartbeat import (  # noqa: E402
     IN_STAGE_PREFIX,
     max_gap_seconds_after,
 )
-from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES  # noqa: E402
+from okstra_ctl.domain.host import HostNotRegistered  # noqa: E402
+from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E402
 from okstra_ctl.wrapper_status import read_wrapper_status  # noqa: E402
 
 _DISPATCHED_STATUSES = {"completed", "timeout", "error", "in-progress"}
@@ -414,7 +415,11 @@ def _conformance_evidence_source(
             return None, f"unsupported sessionAccounting: `{accounting}`"
 
     legacy_runtime = str(team_state.get("leadRuntime", "") or "claude-code")
-    if legacy_runtime in ARTIFACT_ONLY_LEAD_RUNTIMES:
+    try:
+        accounting = default_host_registry().resolve(legacy_runtime).descriptor.session_accounting
+    except HostNotRegistered:
+        accounting = "claude-jsonl"
+    if accounting == "artifact-only":
         return "artifact-only", None
     return "claude-jsonl", None
 
@@ -452,6 +457,61 @@ def _plan_body_rounds_ran(run_dir: Path, suffix: str | None) -> int:
     return rounds if isinstance(rounds, int) and rounds > 0 else 0
 
 
+def _ids_reported_as_asked(report_path: Path) -> list[str]:
+    """리포트가 "사용자에게 물었다"고 기록한 열린 승인 차단 행의 id."""
+    name = report_path.name
+    if not name.endswith(".md"):
+        return []
+    data_path = report_path.with_name(name.removesuffix(".md") + ".data.json")
+    try:
+        doc = json.loads(data_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return []
+    if not isinstance(doc, dict):
+        return []
+    asked: list[str] = []
+    for row in doc.get("clarificationItems") or []:
+        if not isinstance(row, dict):
+            continue
+        if row.get("blocks") != "approval" or row.get("status") != "open":
+            continue
+        if not str(row.get("userConfirmation") or "").startswith("asked-"):
+            continue
+        row_id = str(row.get("id") or "").strip()
+        if row_id:
+            asked.append(row_id)
+    return asked
+
+
+def _check_user_confirm_checkpoints(
+    by_phase: dict[str, list[tuple[str, str]]],
+    asked_ids: list[str],
+    errors: list[str],
+) -> None:
+    """"물어봤다"는 리포트의 기록에는 물어본 흔적이 세션에 남아 있어야 한다.
+
+    승인을 막는 행은 run 하나를 통째로 대기 상태로 만든다. 그런 행을 세우기 전에
+    사용자에게 그 자리에서 묻는 것이 계약인데, 그 이행 여부를 리포트의 자기 신고
+    말고는 확인할 길이 없었다. 한 번은 리드가 차단이 생길 것을 미리 예측해 말해
+    놓고도 묻지 않은 채 행으로 만들었고, run 은 사용자가 이미 답해 둔 질문 앞에서
+    self-fix 예산을 전부 썼다. 체크포인트가 그 격차를 좁힌다 — 세션에 질문이 남지
+    않았다면 리드는 묻지 않은 것이다."""
+    if not asked_ids:
+        return
+    detail = "prompts/lead/okstra-lead-contract.md 'User confirmation before an approval blocker'"
+    asked_lines = " ".join(line for _ts, line in by_phase.get("user-confirm", []))
+    for row_id in asked_ids:
+        if row_id in asked_lines:
+            continue
+        errors.append(
+            f"PROGRESS checkpoint missing: `user-confirm {row_id}` — the final "
+            f"report records `{row_id}` as an approval blocker the user was "
+            "asked about, but no such line exists in this run's evidence. Either "
+            "ask before writing the row, or record what actually happened "
+            f"(`deferred-no-interactive-session`) ({detail})."
+        )
+
+
 def _phase_mentions_worker(lines: list[tuple[str, str]], needles: list[str]) -> bool:
     return any(needle in _norm(line) for _ts, line in lines for needle in needles)
 
@@ -555,6 +615,7 @@ def _check_progress_checkpoints(
     team_state: dict,
     run_dir: Path,
     suffix: str | None,
+    report_path: Path,
     errors: list[str],
 ) -> None:
     by_phase: dict[str, list[tuple[str, str]]] = {}
@@ -617,6 +678,9 @@ def _check_progress_checkpoints(
     _check_plan_verify_cleanup_checkpoints(
         by_phase, _plan_body_rounds_ran(run_dir, suffix), errors
     )
+    _check_user_confirm_checkpoints(
+        by_phase, _ids_reported_as_asked(report_path), errors
+    )
 
 
 def _parse_iso(ts: str) -> datetime | None:
@@ -869,7 +933,9 @@ def validate_session_conformance(
     if error:
         result.errors.append(error)
         return result
-    _check_progress_checkpoints(evidence, team_state, run_dir, suffix, result.errors)
+    _check_progress_checkpoints(
+        evidence, team_state, run_dir, suffix, report_path, result.errors
+    )
     _check_cmux_adapter_read(evidence, team_state, result.errors)
     if task_type == "implementation":
         _check_implementation_entry_guard(

package/src/cli-registry.mjs

@@ -218,13 +218,6 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Bundle cross-project okstra error logs into a zip"],
   },
-  {
-    name: "error-issue",
-    module: "./commands/inspect/error-issue.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Turn okstra run anomalies into GitHub issue candidates"],
-  },
   {
     name: "run-audit",
     module: "./commands/inspect/run-audit.mjs",

package/src/commands/execute/render-bundle.mjs

@@ -1,6 +1,6 @@
 import { runPythonModule } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
-import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
+import { resolveRuntime } from "../../lib/host-registry-client.mjs";
 
 const USAGE = `okstra render-bundle — preview the task bundle without launching a lead
 
@@ -18,7 +18,7 @@ Usage:
     [--analysis-target <text>] [--evidence-inputs <csv>] \\
     [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
     [--antigravity-model <m>] [--report-writer-model <m>] \\
-    [--lead-runtime claude-code|codex|antigravity|external] \\
+    [--lead-runtime auto|<host-id-or-alias>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
     [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
@@ -26,7 +26,7 @@ Usage:
 
   --stage             implementation / final-verification only
   --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
-  --lead-runtime      host-native lead adapter marker
+  --lead-runtime      registered host ID or alias
   --pr-template-path  release-handoff only
   --fix-cycle         entry phase only: record this re-entry of a done task as a
                       bug-fix cycle (yes opens/continues the cycle)
@@ -85,7 +85,7 @@ export async function run(args) {
   }
 
   const requestedRuntime = findFlagValue(args, "--lead-runtime") || "auto";
-  const runtimeResolution = resolveRuntime({
+  const runtimeResolution = await resolveRuntime({
     requestedRuntime,
     command: "render",
     env: process.env,

package/src/commands/execute/run.mjs

@@ -5,14 +5,14 @@ import { join } from "node:path";
 import { runEnsureInstalled } from "../lifecycle/install.mjs";
 import { runPythonModule } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
-import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
+import { resolveRuntime } from "../../lib/host-registry-client.mjs";
 
 const USAGE = `okstra run — host-aware okstra execution front door
 
 Usage:
-  okstra run [claude|codex|antigravity|external] --project-root <dir> \\
+  okstra run [<host-id-or-alias>] --project-root <dir> \\
     --project-id <id> --task-group <tg> --task-id <tid> --task-type <type> \\
-    [--lead-runtime auto|claude-code|codex|antigravity|external] [--yes]
+    [--lead-runtime auto|<host-id-or-alias>] [--yes]
 
 The leading word selects the lead and is an alias for --lead-runtime, so
 'okstra run codex' starts a Codex lead. Naming a lead starts that CLI with the
@@ -21,22 +21,6 @@ team. Starting a lead whose CLI sandboxes itself asks for confirmation first,
 which --yes answers.
 `;
 
-// Leads okstra can start itself. `external` is not one: it names a harness
-// okstra does not own, so those runs are orchestrated rather than launched.
-const LAUNCHABLE_RUNTIMES = new Set(["claude-code", "codex", "antigravity"]);
-
-// The leading word users actually type. `claude` is the provider's name while
-// the runtime is `claude-code`; the rest coincide.
-const RUNTIME_ALIASES = new Map([
-  ["claude", "claude-code"],
-  ["claude-code", "claude-code"],
-  ["codex", "codex"],
-  ["antigravity", "antigravity"],
-  ["avg", "antigravity"],
-  ["agy", "antigravity"],
-  ["external", "external"],
-]);
-
 function flagValue(args, flag) {
   const equals = args.find((arg) => arg.startsWith(`${flag}=`));
   if (equals) return equals.slice(flag.length + 1);
@@ -46,8 +30,7 @@ function flagValue(args, flag) {
 
 export function positionalRuntime(args) {
   const first = args[0];
-  if (!first || first.startsWith("-")) return "";
-  return RUNTIME_ALIASES.get(first) || "";
+  return !first || first.startsWith("-") ? "" : first;
 }
 
 export function requestedRuntimeFromArgs(args) {
@@ -91,7 +74,7 @@ function renderArgs(args, resolution) {
 export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
   void paths;
   const projectRoot = projectRootFromArgs(args);
-  if (resolution.resolvedRuntime === "external") {
+  if (resolution.launchMode === "team") {
     return {
       ok: true,
       kind: "team",
@@ -104,7 +87,7 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
     };
   }
 
-  if (LAUNCHABLE_RUNTIMES.has(resolution.resolvedRuntime)) {
+  if (resolution.launchMode === "lead") {
     return {
       ok: true,
       kind: "launch-lead",
@@ -130,7 +113,7 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
     };
   }
 
-  return { ok: false, reason: `unsupported resolved runtime: ${resolution.resolvedRuntime}`, commands: [] };
+  return { ok: false, reason: `unsupported launch mode: ${resolution.launchMode}`, commands: [] };
 }
 
 async function ensureRuntime(requestedRuntime) {
@@ -182,7 +165,7 @@ export async function run(args) {
 
   const paths = await resolvePaths();
   const requestedRuntime = requestedRuntimeFromArgs(args);
-  const resolution = resolveRuntime({
+  const resolution = await resolveRuntime({
     requestedRuntime,
     command: "run",
     env: process.env,

package/src/commands/execute/wizard.mjs

@@ -20,7 +20,8 @@ Subcommands:
 
 Usage:
   okstra wizard new-state-file
-  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime>
+  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime> \\
+    --entry-mode current-session --available-function <semantic-name>
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
   okstra wizard confirmation --state-file <path>
@@ -40,6 +41,13 @@ All subcommands emit a single JSON object on stdout. On validation failure
 // callers pass any value (including empty) unambiguously.
 export function parseFlags(args) {
   const out = {};
+  const setFlag = (key, value) => {
+    if (key === "available-function") {
+      out[key] = [...(out[key] ?? []), value];
+      return;
+    }
+    out[key] = value;
+  };
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i];
     if (!a.startsWith("--")) {
@@ -47,19 +55,38 @@ export function parseFlags(args) {
     }
     const eq = a.indexOf("=");
     if (eq !== -1) {
-      out[a.slice(2, eq)] = a.slice(eq + 1);
+      setFlag(a.slice(2, eq), a.slice(eq + 1));
       continue;
     }
     const key = a.slice(2);
     if (i + 1 >= args.length) {
       throw new Error(`flag --${key} requires a value`);
     }
-    out[key] = args[i + 1];
+    setFlag(key, args[i + 1]);
     i += 1;
   }
   return out;
 }
 
+export function buildPythonArgs(sub, flags, workspaceRoot = "") {
+  const pyArgs = [sub, "--state-file", flags["state-file"]];
+  if (sub === "init") {
+    pyArgs.push("--workspace-root", workspaceRoot);
+    pyArgs.push("--project-root", flags["project-root"]);
+    pyArgs.push("--project-id", flags["project-id"]);
+    if (flags["host-runtime"]) {
+      pyArgs.push("--host-runtime", flags["host-runtime"]);
+    }
+    for (const value of flags["available-function"] ?? []) {
+      pyArgs.push("--available-function", value);
+    }
+    pyArgs.push("--entry-mode", flags["entry-mode"] ?? "current-session");
+  } else if (sub === "step" && flags.answer !== undefined) {
+    pyArgs.push("--answer", flags.answer);
+  }
+  return pyArgs;
+}
+
 export async function run(args) {
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -95,23 +122,16 @@ export async function run(args) {
     return 2;
   }
 
-  // build python argv
-  const pyArgs = [sub, "--state-file", flags["state-file"]];
+  let workspaceRoot = "";
   if (sub === "init") {
     if (!flags["project-root"] || !flags["project-id"]) {
       process.stderr.write("error: init requires --project-root and --project-id\n");
       return 2;
     }
     const paths = await resolvePaths();
-    pyArgs.push("--workspace-root", paths.workspace);
-    pyArgs.push("--project-root", flags["project-root"]);
-    pyArgs.push("--project-id", flags["project-id"]);
-    if (flags["host-runtime"]) {
-      pyArgs.push("--host-runtime", flags["host-runtime"]);
-    }
-  } else if (sub === "step" && flags.answer !== undefined) {
-    pyArgs.push("--answer", flags.answer);
+    workspaceRoot = paths.workspace;
   }
+  const pyArgs = buildPythonArgs(sub, flags, workspaceRoot);
 
   const result = await runPythonModule({
     module: "okstra_ctl.wizard",

package/src/commands/lifecycle/doctor.mjs

@@ -5,7 +5,7 @@ import { resolvePaths } from "../../lib/paths.mjs";
 import { fileExists, runProcess } from "../../lib/proc.mjs";
 import { runPythonSnippet } from "../../lib/python-helper.mjs";
 import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
-import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
+import { resolveRuntime } from "../../lib/host-registry-client.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -14,7 +14,7 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
-  okstra doctor --runtime <claude-code|codex|antigravity|external|all>
+  okstra doctor --runtime <host-id|alias|all>
   okstra doctor --phase <phase>
   okstra doctor --json        Machine-readable result
 Checks:
@@ -48,7 +48,7 @@ export function parseDoctorArgs(args) {
     } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
       const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error("--runtime requires one of: claude-code, codex, antigravity, external, all");
+        throw new Error("--runtime requires a host ID, alias, or all");
       }
       result.runtime = validateInstallRuntime(value);
       if (arg === "--runtime") i++;
@@ -66,8 +66,8 @@ export function parseDoctorArgs(args) {
   return result;
 }
 
-export function requiredSkillNamesForRuntime(runtime) {
-  return runtimeIncludesClaudeAssets(runtime) ? REQUIRED_SKILLS : [];
+export function requiredSkillNamesForRuntime(resolution) {
+  return runtimeIncludesClaudeAssets(resolution) ? REQUIRED_SKILLS : [];
 }
 
 export function phaseDiagnosticsToChecks(phase, phaseDiagnostics) {
@@ -194,7 +194,7 @@ export async function run(args) {
     return 2;
   }
   const paths = await resolvePaths();
-  const runtimeResolution = resolveRuntime({
+  const runtimeResolution = await resolveRuntime({
     requestedRuntime: opts.runtime,
     command: "doctor",
     env: process.env,
@@ -204,8 +204,8 @@ export async function run(args) {
   // auto-detection only means we cannot attribute the optional skill checks to a
   // runtime, so degrade it to a warning and keep running the host-independent
   // checks. Dispatch callers of resolveRuntime stay fail-closed by design — this
-  // leniency lives only here. With resolvedRuntime null the skill checks skip
-  // (requiredSkillNamesForRuntime → []); pass --runtime to include them.
+  // leniency lives only here. A failed resolution has no install targets, so
+  // skill checks skip; pass --runtime to include them.
   const resolvedRuntime = runtimeResolution.ok ? runtimeResolution.resolvedRuntime : null;
 
   // docker is OPTIONAL for okstra (only the container runtime needs it). Like
@@ -231,7 +231,7 @@ export async function run(args) {
     await check("bin: okstra-provider-exec.py", () => checkBashEntry(paths.bin, "okstra-provider-exec.py")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
-      requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
+      requiredSkillNamesForRuntime(runtimeResolution.ok ? runtimeResolution : null).map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
           return (await fileExists(p))
@@ -278,7 +278,7 @@ export async function run(args) {
 
   if (!runtimeResolution.ok) {
     process.stdout.write(
-      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|antigravity|external> to include them.\n`,
+      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <host-id|alias> to include them.\n`,
     );
   }
   if (dockerWarning) {